dsh-poker-plugin

dsh-poker — Poker Plugin for DSH

A community-built game center for the DSH Web UI (dsh web): a local,
multiplayer Texas Hold'em MVP playable from multiple browser windows on
the same machine. Play Tokens only — no wallet, no real money, no public
network.

Unofficial community plugin. This project is not affiliated with,
sponsored by, or endorsed by DeepSeek. It uses its own name and visual
identity. No deposits, prizes, withdrawals, cash-out, or real-money wagering
are supported.

The architecture adopts several lessons from
leeclouddragon/dsh-all-in—a
minimal DSH slot seam, pure and injectable game rules, explicit betting state,
invariant-driven simulations and artifact-level build gates—while deliberately
retaining this project's server-authoritative multiplayer, WebSocket, ledger,
identity registry and optional AI-provider model. See
Architecture → Adopted principles and deliberate differences.

┌──────────────────────────────────────────────────────────────┐
│ dsh web (127.0.0.1:3080)                                     │
│  sidebar footer:  ♠ Poker   ← game center entry              │
│  overlay:         lobby → dark poker table                    │
│                                                              │
│  Host (same process)                                         │
│   dsh-poker (cordis plugin)                                  │
│    ├─ TableService   authoritative state, commands, timers   │
│    ├─ PokerEngine    pure Texas Hold'em state machine        │
│    ├─ Ledger         Play Token ledger (immutable, integer)  │
│    ├─ storage-domain poker unit  ($DSH_HOME/storages/poker.json) │
│    └─ /poker/ws      WebSocket gateway (realtime)            │
└──────────────────────────────────────────────────────────────┘

Features (MVP)

• Lobby — create a table (2–10 seats), join by list or by room ID (copy
  button), nickname + buy-in, wallet display.
• Chinese / English modes — switch the complete interface from the room
  bar, lobby and actions through results, errors and hand history. The browser
  remembers the selected language.
• Expressive table UI — the sidebar and table expose the host Agent's
  thinking / idle state; AI seats have stable visual characters and localized
  thought lines across idle, observing, thinking, acting and reacting states.
  Dealing, chips moving to the pot, folding, pot changes, turns and winner
  payouts are animated while still respecting prefers-reduced-motion.
• Complete raise sizing — choose minimum, half-pot, three-quarter-pot,
  pot or maximum, drag the legal range slider, or enter an exact raise-to
  amount. Every value is normalized to the server-provided legal bounds; on
  mobile the controls become a touch-friendly bottom sheet.
• Optional AI players — add one or more server-side bots before or during
  a game. Each bot calls a user-configured API with only its private player
  view; every
  response is validated against the engine's legal actions before it applies.
  When the last human deliberately leaves, the current hand is settled without
  further AI requests and the table returns to idle. A dropped connection
  pauses the hand for resumption; no AI requests or timeout actions run while
  no human is connected.
• Real poker rules — blinds 5/10, hole cards, flop/turn/river, showdown,
  fold/check/call/bet/raise/all-in, minimum-raise progression, side pots,
  uncalled-bet refunds, odd-chip tiebreak, big-blind option, heads-up rules,
  short-all-in "does not reopen betting" rule.
• Play Tokens — each new player gets 10,000; buy-in defaults to
  1,000. Every wallet change is an immutable ledger entry
  (transactionId, playerId, tableId, handId, amount, reason, createdAt),
  integer-only, idempotent. Hand results are recorded as audit entries.
• Realtime & consistency — server-authoritative state, poker-action
  commandId dedup, expectedVersion fencing, WebSocket reconnect with
  snapshot resume, heartbeat, per-player private views (nobody sees anyone
  else's unrevealed hole cards), crypto-secure shuffle (never Math.random).
• Disconnect rules — while another human remains connected, the acting
  player auto-folds when facing a bet after the 30 s deadline, otherwise
  auto-checks. If the final human disconnects, the hand freezes for resume;
  seats persist across refreshes.
• Durable state — tables, player identities, wallets and the ledger survive
  dsh web restarts via the DSH storage domain.

Requirements

• DeepSeek Harness dsh ≥ 0.1.0-rc.7, run the normal way: no global
  install needed, npx @deepseek-ai/dsh resolves it.
• pnpm on PATH (the dsh plugin command forwards to pnpm).

Install

The package is a profile bundle (package.json → dsh.bundle.patch, the
same mechanism @deepseek-ai/dsh-base and @deepseek-ai/dsh-web-app use):
installing it with dsh plugin automatically appends it to the web profile's
dsh.profile.bundles, and its cordis.patch.yml auto-inserts the poker
loader row at every boot. No manual cordis.patch.yml editing — ever.

# 1. pack the plugin (a tarball is the distributable artifact)
npm pack

# 2. install it into the web profile (from this directory, or point at the tarball)
npx @deepseek-ai/dsh plugin --profile web add -w file:/absolute/path/to/dsh-poker
# or: npx @deepseek-ai/dsh plugin --profile web add -w file:./dsh-poker-0.1.0.tgz

# 3. restart the web UI (npx is the supported launcher)
npx @deepseek-ai/dsh web

That's it: the profile's dsh.profile.bundles now includes dsh-poker and
--dump-config shows exactly one poker loader row (verified by
npm run test:install). To tune the game config from a profile, override the
row by id in ~/.dsh/profiles/web/cordis.patch.yml (a patch, not a second
insert):

- id: poker
  config:
    actionTimeoutMs: 15000

A running dsh web hot-applies profile-patch changes, but a restart is the
supported way to pick up a new client bundle in window.__DSH_BOOT__.

Play locally (multi-window multiplayer)

1. Open http://127.0.0.1:3080 in two browser windows (or a window +
   an incognito window).
2. Click ♠ Poker in the sidebar footer of both windows.
3. Window 1: enter a nickname, Create table. Window 2: enter a different
   nickname, then Join the table from the list (or copy the room ID and
   paste it into "Join by room ID").
4. A hand starts as soon as two players are seated and connected. Act when it
   is your turn; the countdown drives auto-fold/check on timeout.
5. Refresh a page mid-game: the seat and table state are restored via
   resume.
6. Full tables can be watched (spectate): the "Watch" button subscribes to
   the table's public snapshots without a seat — no hole cards are ever shown.
7. A browser running on the host can delete a room from the lobby with a
   two-step confirmation. An unfinished hand is cancelled and every seat's
   current chips are refunded before the durable room record is removed.

Play against an AI player

For local play, open AI 设置 in the game header—or click ＋ 加入机器人—
and enter a DeepSeek API key. This option is available only to a same-origin
browser connected over loopback. The key is sent directly to the host process,
kept in memory only, never written to game state, the ledger, logs,
localStorage or profile files, and cannot be read back by the page. Enter it
again after restarting dsh web.

For unattended startup, supply the key to the host as an environment variable:

DEEPSEEK_API_KEY=sk-your-key npx @deepseek-ai/dsh web

Create and join a table, then click ＋ 加入机器人. The first bot starts
heads-up play immediately; additional bots can fill the remaining seats and
join from the next hand. The current adapter uses a user-supplied DeepSeek API
account and defaults to deepseek-v4-flash. Each bot turn makes one API
request. If the API times out, fails, or returns an illegal move, the server
chooses a safe legal fallback so the table never stalls.

AI data disclosure

When an AI seat acts, the host sends the configured API provider only the
state needed for that seat's decision: that AI seat's hole cards, community
cards, pot and betting state, stacks, player nicknames, public actions, legal
actions, and the last 10 public log entries. It never sends another player's
unrevealed hole cards. Operators are responsible for informing players and
complying with the selected provider's terms and applicable privacy law.

Optional profile overrides (the key should still remain an environment
variable):

- id: poker
  config:
    deepseekModel: deepseek-v4-flash
    deepseekBaseUrl: https://api.deepseek.com
    botDecisionTimeoutMs: 12000

The UI is responsive (1440 / 1024 / 390 px) and styled with the DSH theme
tokens.

Development

npm install          # typescript + @types (node/ws/react) + react/react-dom
npm run typecheck    # tsc --noEmit over src/ + test/
npm run build        # tsc → lib/ + dist-test/, bundles the TSX/CSS client
npm test             # build + node --test
npm run test:ui      # browser layout/actions at desktop, tablet and mobile sizes
npm run test:install # install & distribution verification (see below)

Layout:

src/
  engine/   cards.ts (secure shuffle) · evaluator.ts (hand ranking)
            engine.ts (state machine) · types.ts (domain types)
  ledger.ts immutable Play Token ledger
  protocol.ts wire schema (zod) + per-player view builders
  host/     index.ts (cordis plugin) · table-service.ts · gateway.ts
            bot-controller.ts · persistence.ts · types-augment.ts
  client/   entry.ts + i18n/store/components/styles  ← TS/TSX browser source
cordis.patch.yml       ← the profile bundle patch (auto-inserts the poker row)
test/       evaluator · engine · ledger · service · full-game · frontend · bot
            gateway · audit · simulation · package-exports · ui-layout
scripts/    build.mjs (artifact contract gate) · smoke-test.mjs (end-to-end)
            install-test.sh

scripts/build.mjs bundles src/client/entry.ts and its TSX/CSS dependencies
into the distributed lib/client.js __ModuleLoader__ module. The build then
parses that final wrapper and dynamically imports the host and engine artifacts
to verify their public export contracts before succeeding.

The dependency-free engine is also a public package subpath for bot policies,
simulators and external tests:

import { PokerEngine, seededRng, evaluateBest } from "dsh-poker/engine";

Install & distribution verification

npm run test:install packs the tarball, installs it from the tarball into a
fresh temporary DSH_HOME with npx @deepseek-ai/dsh, asserts the poker
loader row appears exactly once in --dump-config, boots a temporary
dsh web, and runs the smoke test against it.

End-to-end smoke test

npx @deepseek-ai/dsh --profile web --port 3091 &   # or any profile with the plugin
node scripts/smoke-test.mjs ws://127.0.0.1:3091/poker/ws

Simulates two browser windows over WebSocket: create/join, play hands,
verifies privacy, stale-version rejection, reconnect/resume, forged-token
rejection, spectator privacy, chip conservation and cash-out.

Configuration

The poker row config (all optional):

key	default	meaning
smallBlind	5	small blind (chips)
bigBlind	10	big blind
buyIn	1000	default buy-in per table
maxSeats	6	default table size (2–10)
actionTimeoutMs	30000	turn deadline before auto-action
startingWallet	10000	Play Tokens granted per new player
deepseekApiKey	unset; falls back to DEEPSEEK_API_KEY	server-side AI API key
deepseekBaseUrl	https://api.deepseek.com	AI API base URL
deepseekModel	deepseek-v4-flash	AI model name
botDecisionTimeoutMs	12000	AI decision request timeout

Prefer the in-game memory-only setting for interactive local play, or the
DEEPSEEK_API_KEY environment variable for unattended startup. Avoid
deepseekApiKey because it writes the secret to a profile patch.

Reset / data

All game data lives in the storage-domain unit poker (JSON backend):

rm ~/.dsh/storages/poker.json   # wipes tables, identities, wallets and the ledger

Known limitations

See ARCHITECTURE.md → "Known limitations".

Security

The WebSocket gateway rejects browser handshakes whose Origin does not match
the DSH Web host. This reduces cross-site access to the local game service, but
the plugin is still designed only for a loopback-bound, trusted local DSH
instance. Do not expose it through 0.0.0.0, a LAN or the public internet
without additional authentication, TLS, rate limiting and access controls.

In-game AI credential configuration additionally requires both the browser and
the requested host to be loopback. Remote clients do not receive the settings
control, and the gateway rejects forged configuration messages. Any seated
player can request AI seats after the local operator has configured a provider;
each AI turn may consume paid provider tokens.

Report vulnerabilities privately according to SECURITY.md.

License

MIT for this plugin. DSH and its dependencies are separate
projects governed by their own licenses and terms. This plugin does not modify
or fork DSH, and no upstream trademarks or logos are licensed as part of this
repository.

Responsible use

This software is a local play-token game and is provided for entertainment and
software-development purposes. Do not add deposits, withdrawals, redeemable
prizes, paid entry, rake, or other real-money wagering features without first
obtaining jurisdiction-specific legal advice. Operators remain responsible for
API-provider terms, privacy notices, age restrictions, and local law.