dsh-blackjack 0.1.0

package/dist/router.js

@@ -0,0 +1,179 @@
+import { QUOTA_EXCEEDED_CODE, isQuotaExceededError } from '@deepseek-ai/dsh-llm';
+import { createPoolAdapter } from './adapter.js';
+/** Provider route the pool adapter is registered under; also the loop-guard for `shouldFallback`. */
+export const POOL_PROVIDER = 'blackjack-pool';
+/** Chunk types that count as "content already reached the consumer" for the no-duplicate-output rule. */
+const CONTENT_TYPES = new Set(['block-start', 'text-delta', 'reasoning-delta', 'tool-call-delta', 'block-end']);
+/** Narrow a finish chunk's `error` failure to whether it reads as quota exhaustion. */
+function isQuotaFailure(failure) {
+    // Our own pool adapter (DeepSeekAdapter) already normalizes provider wire
+    // errors to the stable QUOTA_EXCEEDED_CODE (see dsh-llm-deepseek's
+    // httpErrorCode), so the direct code check is the common case. The
+    // isQuotaExceededError(...) fallback — over the same
+    // `[code, message].filter(Boolean).join(' ')` shape dsh-llm-deepseek's own
+    // httpErrorCode uses — catches a third-party adapter that never normalized
+    // its wording into that code at all (e.g. it fell through to `UNKNOWN`
+    // carrying a plainly quota-worded message).
+    return failure.code === QUOTA_EXCEEDED_CODE
+        || isQuotaExceededError([failure.code, failure.message].filter(Boolean).join(' '));
+}
+/**
+ * Decide whether one finished call should be retried on the pool route.
+ *
+ * NOTE on `QUOTA_EXCEEDED_CODE` vs `isQuotaExceededError`: the brief's
+ * original sketch called `isQuotaExceededError(reason.failure)` directly on
+ * the failure object. Checking the installed `@deepseek-ai/dsh-llm@0.1.0-rc.6`
+ * package directly shows `isQuotaExceededError(detail: string): boolean` is a
+ * *raw provider wording* classifier (regexes over free text such as
+ * "insufficient quota") — it is what an adapter uses internally while
+ * normalizing a thrown provider error into a `LlmFailure`, not something a
+ * downstream consumer applies to an already-normalized `finish` chunk as-is.
+ * The normalized signal to compare first is `LlmFailure.code` against
+ * `QUOTA_EXCEEDED_CODE`; `isQuotaExceededError` is kept only as a secondary,
+ * string-joined fallback for adapters that never normalized at all (see
+ * `isQuotaFailure` above).
+ */
+export function shouldFallback(input) {
+    if (input.provider === POOL_PROVIDER)
+        return false;
+    if (!input.hasToken || input.emittedContent)
+        return false;
+    const reason = input.finish.reason;
+    if (reason.kind !== 'error')
+        return false;
+    return isQuotaFailure(reason.failure);
+}
+/**
+ * Wrap one model call: pass everything through, and only when the call ends
+ * with a content-free quota failure retry it against the pool route. Any
+ * failure of that retry surfaces the ORIGINAL failure, so installing this
+ * plugin can never make a call worse than not having it.
+ *
+ * Two invariants the pool-retry branch upholds that are easy to get wrong:
+ * - The stream ALWAYS ends with exactly one terminal `finish` chunk. A pool
+ *   retry that throws mid-stream (after already forwarding content), or one
+ *   that simply ends without ever sending its own finish, would otherwise
+ *   leave the consumer's `BlockAssembler` defaulting an absent finish to
+ *   `{kind: 'stop'}` — silently presenting a FAILED fallback as a successful,
+ *   truncated turn. `poolFinished` tracks whether the pool ever produced its
+ *   own terminal finish; whenever it did not, the ORIGINAL failure is yielded
+ *   as the terminal chunk instead (legal even after open content blocks,
+ *   since its `reason.kind` is `'error'`).
+ * - `usage` never gets forwarded twice. Adapters emit at most one `usage`
+ *   chunk, just before their finish. The primary attempt's `usage` (if any)
+ *   is buffered rather than forwarded immediately, so it can be dropped
+ *   entirely once a fallback is underway — the pool call reports its own —
+ *   instead of both being forwarded and double-counting tokens.
+ */
+export async function* runWithFallback(options, next, deps) {
+    let emittedContent = false;
+    let finish;
+    const pendingUsage = [];
+    for await (const c of next()) {
+        if (c.type === 'finish') {
+            finish = c;
+            break;
+        }
+        if (c.type === 'usage') {
+            pendingUsage.push(c);
+            continue;
+        }
+        if (CONTENT_TYPES.has(c.type))
+            emittedContent = true;
+        yield c;
+    }
+    if (!finish)
+        return;
+    // Cheap, synchronous eligibility (provider / content / finish code) comes
+    // first. `deps.hasToken()` is awaited only once everything else already
+    // says yes, so a normal call — success or a non-quota failure — never pays
+    // a credential resolve, and a credentials-provider rejection can only ever
+    // affect a call this plugin was already about to intervene on.
+    if (!shouldFallback({ finish, emittedContent, hasToken: true, provider: options.provider })) {
+        yield* pendingUsage;
+        yield finish;
+        return;
+    }
+    let hasToken;
+    try {
+        hasToken = await deps.hasToken();
+    }
+    catch {
+        hasToken = false;
+    }
+    if (!hasToken) {
+        yield* pendingUsage;
+        yield finish;
+        return;
+    }
+    // Falling back: the primary attempt's pre-retry usage (if any) is dropped
+    // on purpose — see the usage invariant note above.
+    let announced = false;
+    let poolFinished = false;
+    try {
+        for await (const c of deps.poolStream({ ...options, provider: POOL_PROVIDER })) {
+            if (c.type === 'finish' && c.reason.kind === 'error') {
+                yield finish;
+                return;
+            }
+            if (!announced) {
+                announced = true;
+                deps.notify('已切换至奖池余额继续本次请求。');
+            }
+            if (c.type === 'finish')
+                poolFinished = true;
+            yield c;
+        }
+    }
+    catch (error) {
+        deps.logError?.(error);
+    }
+    if (!poolFinished)
+        yield finish;
+}
+/**
+ * Register the pool-route adapter and hang the `llm/stream` fallback
+ * waterfall off it.
+ *
+ * KNOWN LIMITATION — where the switch notice actually goes. `notify` defaults
+ * to `ctx.logger.info`, which means the player normally never SEES it: in dsh
+ * 0.1.0-rc.6 a waterfall listener has no FIRE-AND-FORGET notice channel it may
+ * use. Everything reachable from here was checked (see the plugin spec's §7
+ * appendix for the full record): no host service in this plugin's dependency
+ * closure is a notification sink (`agents`, `sessions`, `credentials`,
+ * `commands`, `llm`, `webServer`, `conversation`, `chatFileMentions`). The one
+ * human-visible in-conversation seam that does exist elsewhere in the host,
+ * `ctx.userQuestions.ask()`, BLOCKS on a human answer and needs a GUI
+ * provider — wrong semantics for a passive notice, and it would stall the very
+ * stream this fallback is rescuing. `commands` only runs when the player types
+ * a slash command;
+ * `agent.inject()` writes a model-visible `user/message`, which is exactly
+ * what this project forbids; and `SurfaceEventType` is a CLOSED three-member
+ * set, so the UI's generic unclaimed-event fallback covers only
+ * model-visible events — a log-only custom event has no renderer at all.
+ * Surfacing it would take a plugin-owned `ConversationNodeDefinition` in the
+ * client bundle, i.e. a new feature that still would not reach TUI/headless
+ * players. The README says plainly that the notice lands in the log, rather
+ * than promising an on-screen one. Revisit when dsh grows a plugin-usable
+ * in-session notice slot.
+ *
+ * What is NOT negotiable either way: the notice must never be injected into
+ * model messages, so a fallback can never pollute conversation history.
+ *
+ * `ctx.llm.registerAdapter()` already ties its disposal to the calling
+ * fiber (cordis re-binds a service's `this.ctx` to whichever context reads
+ * it, so the registration's own internal `ctx.effect` lands on OUR plugin's
+ * fiber, not `llm`'s construction context — confirmed by disposing a probe
+ * fiber and observing the route drop from `listProviders()` with no extra
+ * wrapping). No separate `ctx.effect` around `registration` is needed.
+ */
+export function registerRouter(ctx, deps) {
+    const notify = deps.notify ?? ((line) => ctx.logger.info(line));
+    ctx.llm.registerAdapter([POOL_PROVIDER], createPoolAdapter(ctx, deps.serverUrl));
+    ctx.on('llm/stream', (options, next) => runWithFallback(options, next, {
+        hasToken: async () => (await deps.identity.current()) !== undefined,
+        poolStream: (o) => ctx.llm.stream(o),
+        notify,
+        logError: (error) => ctx.logger.warn('dsh-blackjack: pool fallback failed after a quota exhaustion; the original failure was surfaced instead', error),
+    }));
+}

package/dist/routes.d.ts

@@ -0,0 +1,54 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { type Api } from './api.js';
+import type { Identity } from './identity.js';
+/**
+ * Host half of the graphical table: a JSON read/act surface under
+ * `/blackjack/api/*` on the web GUI's own `ctx.webServer`, consumed by the
+ * browser table (a separate module, task 8). Registered as a NESTED plugin
+ * from `src/index.ts` with its own `inject: ['webServer']`, so a headless
+ * host without a web server leaves this fiber pending while the text
+ * commands keep working — the table is an optional surface, not a
+ * requirement.
+ *
+ * Security: the player's bearer token lives only in the dsh process
+ * (`Identity`) — it MUST NEVER appear in a response body. Before consent (no
+ * token yet) `GET .../state` reports `{ consented: false }` and every write
+ * route refuses with 403; consent can only be granted from the command plane
+ * (`/blackjack agree`), never from the browser.
+ *
+ * The bind address is NOT the whole trust boundary. A dsh host may bind
+ * `0.0.0.0`, and even on loopback any page the player has open can reach
+ * `http://localhost:<port>` — a cross-site `<form enctype="text/plain">` needs
+ * no CORS preflight, so without a check a hostile page could burn free hands
+ * through `/api/deal` or force actions through `/api/action`. Two same-origin
+ * gates close that (see `isSameOrigin` / `hasJsonBody`):
+ * - a request carrying an `Origin` whose host differs from this request's
+ *   `Host`, or a `Sec-Fetch-Site` that is anything other than `same-origin`,
+ *   is refused 403 outright (the browser sets both and a page cannot forge
+ *   either);
+ * - the write routes require `content-type: application/json`, which a
+ *   simple (preflight-free) cross-site form can never send.
+ * The browser table (`src/client/index.tsx`) calls these with same-origin
+ * relative URLs and an explicit JSON content type, so it satisfies both.
+ *
+ * Exchange is deliberately NOT here: it is a command-plane concern
+ * (`/blackjack exchange`), because the pairing `code` is itself a bearer
+ * capability — whoever holds it can claim the exchange — and must never reach
+ * the browser through a route this file owns.
+ *
+ * @module dsh-blackjack/routes
+ */
+/** Route prefix this plugin owns on the host's web server. */
+export declare const PREFIX = "/blackjack";
+/**
+ * Register the table's API routes into `ctx`'s effect scope (the route
+ * disposer rides the fiber, so plugin dispose unregisters the prefix).
+ * @param ctx - a context whose `webServer` service is live (the nested
+ *   plugin's `inject` guarantees it).
+ * @param deps - the same `Api`/`Identity` the command plane uses, so the
+ *   browser table and the zero-token commands stay consistent.
+ */
+export declare function registerRoutes(ctx: Context, deps: {
+    api: Api;
+    identity: Identity;
+}): void;

package/dist/routes.js

@@ -0,0 +1,195 @@
+import { ApiError } from './api.js';
+/**
+ * Host half of the graphical table: a JSON read/act surface under
+ * `/blackjack/api/*` on the web GUI's own `ctx.webServer`, consumed by the
+ * browser table (a separate module, task 8). Registered as a NESTED plugin
+ * from `src/index.ts` with its own `inject: ['webServer']`, so a headless
+ * host without a web server leaves this fiber pending while the text
+ * commands keep working — the table is an optional surface, not a
+ * requirement.
+ *
+ * Security: the player's bearer token lives only in the dsh process
+ * (`Identity`) — it MUST NEVER appear in a response body. Before consent (no
+ * token yet) `GET .../state` reports `{ consented: false }` and every write
+ * route refuses with 403; consent can only be granted from the command plane
+ * (`/blackjack agree`), never from the browser.
+ *
+ * The bind address is NOT the whole trust boundary. A dsh host may bind
+ * `0.0.0.0`, and even on loopback any page the player has open can reach
+ * `http://localhost:<port>` — a cross-site `<form enctype="text/plain">` needs
+ * no CORS preflight, so without a check a hostile page could burn free hands
+ * through `/api/deal` or force actions through `/api/action`. Two same-origin
+ * gates close that (see `isSameOrigin` / `hasJsonBody`):
+ * - a request carrying an `Origin` whose host differs from this request's
+ *   `Host`, or a `Sec-Fetch-Site` that is anything other than `same-origin`,
+ *   is refused 403 outright (the browser sets both and a page cannot forge
+ *   either);
+ * - the write routes require `content-type: application/json`, which a
+ *   simple (preflight-free) cross-site form can never send.
+ * The browser table (`src/client/index.tsx`) calls these with same-origin
+ * relative URLs and an explicit JSON content type, so it satisfies both.
+ *
+ * Exchange is deliberately NOT here: it is a command-plane concern
+ * (`/blackjack exchange`), because the pairing `code` is itself a bearer
+ * capability — whoever holds it can claim the exchange — and must never reach
+ * the browser through a route this file owns.
+ *
+ * @module dsh-blackjack/routes
+ */
+/** Route prefix this plugin owns on the host's web server. */
+export const PREFIX = '/blackjack';
+function sendJson(res, status, body) {
+    const text = JSON.stringify(body);
+    res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
+    res.end(text);
+}
+/**
+ * Whether this request provably did not come from another origin.
+ *
+ * Both headers are browser-controlled and unforgeable from page script, so a
+ * present-and-wrong value is a positive signal of a cross-site attempt:
+ * - `Sec-Fetch-Site` must be exactly `same-origin` when present. `cross-site`
+ *   and `same-site` are refused for the obvious reason; `none` (a
+ *   user-typed URL or bookmark) is refused too, because nothing legitimate
+ *   navigates directly to a JSON endpoint here and refusing costs nothing.
+ * - `Origin`, when present, must name the same host this request was
+ *   addressed to (`Host`). A non-browser client (curl, a test harness) sends
+ *   neither header and is unaffected — the goal is stopping a hostile PAGE,
+ *   which cannot suppress them.
+ */
+function isSameOrigin(req) {
+    const site = req.headers['sec-fetch-site'];
+    if (typeof site === 'string' && site !== 'same-origin')
+        return false;
+    const origin = req.headers.origin;
+    if (typeof origin === 'string' && origin.length > 0) {
+        const host = req.headers.host;
+        if (!host)
+            return false;
+        try {
+            if (new URL(origin).host !== host)
+                return false;
+        }
+        catch {
+            return false; // an unparseable Origin (including the opaque `null`) is not ours
+        }
+    }
+    return true;
+}
+/**
+ * Whether a write request declared a JSON body. Required on every write route:
+ * the cross-site form POST this file defends against can only send
+ * `text/plain`, `application/x-www-form-urlencoded`, or `multipart/form-data`
+ * without triggering a CORS preflight, so demanding JSON is a second,
+ * independent gate that does not depend on any `Sec-Fetch-*` support.
+ */
+function hasJsonBody(req) {
+    const type = req.headers['content-type'];
+    return typeof type === 'string' && type.split(';')[0].trim().toLowerCase() === 'application/json';
+}
+/** Read the request body as JSON. Any non-object result — empty body, parse failure, array, null — becomes `{}`. */
+async function readJsonBody(req) {
+    const chunks = [];
+    for await (const chunk of req) {
+        chunks.push(chunk);
+    }
+    if (chunks.length === 0)
+        return {};
+    try {
+        const parsed = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+        return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** Map a caught failure to a player-safe status/body pair. Never leaks stack traces, URLs, or raw messages. */
+function mapError(e) {
+    if (e instanceof ApiError) {
+        const status = e.status === 0 ? 502 : e.status;
+        return { status, body: { error: e.code ?? 'upstream error' } };
+    }
+    return { status: 500, body: { error: 'internal error' } };
+}
+/**
+ * Register the table's API routes into `ctx`'s effect scope (the route
+ * disposer rides the fiber, so plugin dispose unregisters the prefix).
+ * @param ctx - a context whose `webServer` service is live (the nested
+ *   plugin's `inject` guarantees it).
+ * @param deps - the same `Api`/`Identity` the command plane uses, so the
+ *   browser table and the zero-token commands stay consistent.
+ */
+export function registerRoutes(ctx, deps) {
+    const { api, identity } = deps;
+    async function handle(req, res) {
+        const url = new URL(req.url ?? '/', 'http://blackjack.local');
+        const route = url.pathname;
+        const method = req.method ?? 'GET';
+        if (!isSameOrigin(req))
+            return sendJson(res, 403, { error: 'cross-origin request refused' });
+        try {
+            if (route === `${PREFIX}/api/state` && method === 'GET') {
+                const token = await identity.current();
+                if (!token)
+                    return sendJson(res, 200, { consented: false });
+                const [me, round] = await Promise.all([api.me(token), api.activeRound(token)]);
+                return sendJson(res, 200, { consented: true, me, round });
+            }
+            if (route === `${PREFIX}/api/deal` && method === 'POST') {
+                if (!hasJsonBody(req))
+                    return sendJson(res, 415, { error: 'expected content-type: application/json' });
+                const token = await identity.current();
+                if (!token)
+                    return sendJson(res, 403, { error: 'not consented' });
+                const body = await readJsonBody(req);
+                const betChips = body.betChips;
+                let startBody;
+                if (betChips === undefined) {
+                    startBody = { mode: 'free' };
+                }
+                else if (typeof betChips === 'number' && Number.isInteger(betChips) && betChips > 0) {
+                    startBody = { mode: 'raise', betChips };
+                }
+                else {
+                    return sendJson(res, 400, { error: 'invalid betChips' });
+                }
+                const round = await api.startRound(token, startBody);
+                return sendJson(res, 200, round);
+            }
+            if (route === `${PREFIX}/api/action` && method === 'POST') {
+                if (!hasJsonBody(req))
+                    return sendJson(res, 415, { error: 'expected content-type: application/json' });
+                const token = await identity.current();
+                if (!token)
+                    return sendJson(res, 403, { error: 'not consented' });
+                const body = await readJsonBody(req);
+                if (typeof body.action !== 'string' || body.action.length === 0) {
+                    return sendJson(res, 400, { error: 'invalid action' });
+                }
+                const round = await api.activeRound(token);
+                if (!round)
+                    return sendJson(res, 404, { error: 'no active round' });
+                const result = await api.act(token, round.id, body.action);
+                return sendJson(res, 200, result);
+            }
+            return sendJson(res, 404, { error: 'unknown route' });
+        }
+        catch (e) {
+            const { status, body } = mapError(e);
+            return sendJson(res, status, body);
+        }
+    }
+    ctx.effect(() => ctx.webServer.register({
+        kind: 'prefix',
+        path: PREFIX,
+        handler: (req, res) => handle(req, res).catch((err) => {
+            ctx.logger.warn('dsh-blackjack: web route failed: %o', err);
+            if (!res.headersSent)
+                sendJson(res, 500, { error: 'internal error' });
+            else
+                res.end();
+        }),
+    }), 'dsh-blackjack: /blackjack web routes');
+}

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "dsh-blackjack",
+  "version": "0.1.0",
+  "description": "社区福利小游戏插件：在 dsh 里玩 21 点赢取可消费的模型额度",
+  "license": "MIT",
+  "keywords": [
+    "dsh-plugin",
+    "blackjack",
+    "community"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./client": "./dist/client.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "blackjack.cordis.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./blackjack.cordis.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-ui-conversation"
+      ]
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node build.client.mjs",
+    "prepack": "pnpm run build",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "prepare": "pnpm run build"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-anonymous-user-id": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-commands": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-credentials": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm-deepseek": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.6"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "devDependencies": {
+    "@dsh-blackjack/server": "workspace:*",
+    "@deepseek-ai/cordis": "4.0.1",
+    "@deepseek-ai/dsh-agent": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-anonymous-user-id": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-runtime": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-conversation": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-slots": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-commands": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-credentials": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-host-webserver": "0.1.0-rc.8",
+    "@deepseek-ai/dsh-llm": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm-deepseek": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-session": "0.1.0-rc.6",
+    "@types/node": "^22.0.0",
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "~18.3.0",
+    "esbuild": "^0.24.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yul761/dsh-blackjack.git",
+    "directory": "packages/plugin"
+  },
+  "homepage": "https://github.com/yul761/dsh-blackjack/tree/master/packages/plugin#readme",
+  "bugs": {
+    "url": "https://github.com/yul761/dsh-blackjack/issues"
+  }
+}