dsh-llm-fallbacks 0.1.0-alpha.1

package/dist/roles.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Role resolution for fallback chains (spec §7.1; plan fallbacks-role-runtime
+ * Task 1).
+ *
+ * Precedence (first hit wins):
+ * 1. the first `rules` entry whose specified origin/provider/model patterns
+ *    all match the agent;
+ * 2. the built-in `'inherit'` role (no-rule-match default, spec §7.1 / D4).
+ *
+ * A matched rule must target a declared role id (`roleIds`, derived from
+ * `config.roles.list`) or the built-in `'inherit'` — an undeclared target
+ * warns and falls back to `'inherit'` (defensive; startup validation already
+ * flagged the reference, spec §7.1 / AC-4).
+ *
+ * Role ids are canonicalized by trim (qc2 F-001, client-canonical trim
+ * alignment — `validateFallbacksConfig` trims ids and rule references, so
+ * the runtime must too): `roleIds` maps a TRIMMED id to the DECLARED RAW
+ * id, membership compares `rule.role.trim()`, and a matched rule returns
+ * the declared raw id — so roleDef lookups in `chains.ts` / `commands.ts`
+ * match the stored `roles.list[].id` exactly and a padded YAML id
+ * (`' coder '`) with a trimmed rule reference (`'coder'`) resolves to the
+ * same role instead of silently degrading to `'inherit'`.
+ *
+ * A missing agent origin is treated as `'root'`. Origin is read from
+ * `session.header.origin` — a native `SessionHeader` field the store folds
+ * from `CreateSessionOptions.meta.origin` (`packages/core/session/src/
+ * index.ts:884`); subagent children set it via `childSessionMeta`
+ * (`packages/subagent/subagent/src/child-agent.ts:115`), root agents carry
+ * none. A subagent `persona` is NOT readable at the decision point:
+ * `AgentOptions` is provider/model/maxTokens only, and persona is installed
+ * as a scoped system-prompt section in the child's creation window — see
+ * `.mstar/iterations/iter-20260811-fallbacks-mount-only/guides/
+ * role-and-model-selection-exploration.md` (Role section).
+ *
+ * @module dsh-llm-fallbacks/roles
+ */
+import { type FallbacksRoleRule } from './config.ts';
+export type { FallbacksRoleRule } from './config.ts';
+/** Agent origins understood by role rules (spec §3). */
+export type Origin = 'root' | 'subagent';
+/** Loose agent shape sufficient for role resolution (spec §3 / brief). */
+export interface AgentLike {
+    options?: {
+        provider?: string;
+        model?: string;
+    };
+    session?: {
+        header?: {
+            origin?: Origin;
+        };
+    };
+}
+/**
+ * Resolve the fallback-chain role for an agent: first matching rule (in
+ * listed order) → the built-in `'inherit'` role. A rule targeting an id
+ * outside the declared-id set ∪ {'inherit'} warns once and resolves to
+ * `'inherit'` (the defensive path — `validateFallbacksConfig` already
+ * warned at startup, spec §7.1).
+ *
+ * `roleIds` is the canonical trimmed-id map built by the wiring
+ * (`trimmed id → declared raw id`, see `src/index.ts` apply()): a matched
+ * rule returns the declared RAW id so the roleDef lookups in
+ * `chains.ts` / `commands.ts` find the stored `roles.list[]` entry exactly
+ * (qc2 F-001 — no silent rule inertness on padded YAML ids).
+ *
+ * `warn` defaults to `console.warn` (direct-call compatibility); the
+ * decision path injects the cordis `logger.warn` so every plugin warning
+ * flows through the plugin log namespace (qc2 F-002 / qc3 S-3).
+ */
+export declare function resolveRole(agent: AgentLike, rules: FallbacksRoleRule[], roleIds: ReadonlyMap<string, string>, warn?: (message: string) => void): string;

package/dist/selectors.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Selector parsing for `fallbacks` chains (spec §4, plan Task 2).
+ *
+ * Grammar: `provider/model` (exact) and `provider/*` (wildcard — the parsed
+ * `model` is `undefined`). Illegal selectors throw {@link SelectorError} —
+ * the catchable "config warning" path; warn-and-continue lives in Task 3.
+ * These modules never crash on their own.
+ *
+ * @module dsh-llm-fallbacks/selectors
+ */
+/** A parsed selector: `provider` + optional `model` (`undefined` = wildcard). */
+export interface Selector {
+    provider: string;
+    model?: string;
+    /** Original selector string, kept for diagnostics/logging. */
+    raw: string;
+}
+/** Catchable error for illegal/unknown selectors (config-warning path). */
+export declare class SelectorError extends Error {
+    constructor(message: string);
+}
+/** Canonical key: `provider/model`, or `provider/*` for a wildcard model. */
+export declare function selectorKey(provider: string, model?: string): string;
+/**
+ * Parse a chain key or entry selector.
+ *
+ * Accepts `provider/model` and `provider/*`; throws {@link SelectorError}
+ * on anything else (missing separator, empty parts, extra separators).
+ */
+export declare function parseSelector(input: string): Selector;
+/**
+ * Wildcard-entry resolution: keep the failing model id, swap only the
+ * provider (`provider/*` entry semantics, spec §2 clause 2).
+ */
+export declare function resolveWildcardEntry(failingModel: string, provider: string): Selector;

package/dist/state.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Per-agent fallback state machine (spec §5.1; plan Task 3).
+ *
+ * One `AgentFallbackState` per `agent.id`, held in a `FallbackStateStore`
+ * created at plugin apply, removed on `agent/disposed`, defensively pruned on
+ * `agent/status` idle, and cleared wholesale on plugin dispose (spec §6:
+ * 无残留状态).
+ *
+ * **pendingSwitch lifecycle** (spec §5.1):
+ * 1. **Produce** (decision point — request-error trigger-code or
+ *    agent/request always-cap): `writePending` stores the decision and clears
+ *    `appliedTurnStep`, so a *fresh* decision is always applicable at the
+ *    current (turn, step) — required for chains (decision B→C must apply even
+ *    though A→B was already applied at the same (turn, step)).
+ * 2. **Apply** (`agent/request`): `applyPending` returns the pending switch
+ *    when one exists and has not already been applied at the current
+ *    (turn, step), records `appliedTurnStep`, and clears `pendingSwitch`
+ *    (anti-replay guard).
+ * 3. **Discard**: chain exhaustion / safety valve → the caller delegates
+ *    (`next()`) and the pending state dies with the agent.
+ *
+ * **stepFailures** resets whenever (turn, step) advances (`syncStep`);
+ * **cooldown** (`CooldownStore`) is a `provider/model → expiry epoch ms` map
+ * with lazy expiry (`revertPolicy: 'never'` = `Infinity` TTL). The time-boxed
+ * cooldown deliberately survives idle cleanup so `cooldown-expiry` revert
+ * (US-4 / T4 integration) works across turns.
+ *
+ * @module dsh-llm-fallbacks/state
+ */
+import type { FallbackSwitchReason } from './events.ts';
+import { CooldownStore, StepFailureSet } from './cooldown.ts';
+/** Decision awaiting application at the next `agent/request` boundary (spec §5.1). */
+export interface PendingSwitch {
+    from: {
+        provider: string;
+        model: string;
+    };
+    to: {
+        provider: string;
+        model: string;
+    };
+    role: string;
+    reason: FallbackSwitchReason;
+}
+/** The current (turn, step)'s failed-model set and switch budget (spec §5.1). */
+export interface StepFailures {
+    turn: number;
+    step: number;
+    /** `${provider}/${model}` keys failed in this step (double suppression with cooldown). */
+    failed: StepFailureSet;
+    /** Switches committed in this step; the caller judges it against `maxSwitchesPerStep`. */
+    switchCount: number;
+}
+/** One agent's whole fallback runtime state (spec §5.1). */
+export interface AgentFallbackState {
+    /** Decision produced but not yet applied at an `agent/request` boundary. */
+    pendingSwitch?: PendingSwitch;
+    /** The (turn, step) the last pending switch was applied to — anti-replay. */
+    appliedTurnStep?: {
+        turn: number;
+        step: number;
+    };
+    /** Current (turn, step)'s failure bookkeeping. */
+    stepFailures: StepFailures;
+    /** `provider/model → expiry epoch ms`; lazily expired on read. */
+    cooldown: CooldownStore;
+}
+/**
+ * The `Map<agent.id, AgentFallbackState>` store plus the state-machine
+ * operations (spec §5.1).
+ */
+export declare class FallbackStateStore {
+    private readonly states;
+    /** Number of tracked agents. */
+    get size(): number;
+    has(agentId: string): boolean;
+    /** Read without creating; `undefined` for unknown agents. */
+    peek(agentId: string): AgentFallbackState | undefined;
+    /** Read, creating an empty state on first sight. */
+    get(agentId: string): AgentFallbackState;
+    /** Remove one agent's state (`agent/disposed`). */
+    delete(agentId: string): void;
+    /** Remove every agent's state (plugin dispose — no residual state). */
+    clear(): void;
+    /** Reset step-scoped bookkeeping when (turn, step) advances (spec §5.1). */
+    syncStep(state: AgentFallbackState, turn: number, step: number): void;
+    /** Record the current model as failed in this step (spec §5.1). */
+    recordFailure(state: AgentFallbackState, key: string): void;
+    /** Bump the step's switch budget (spec §5.1). */
+    recordSwitch(state: AgentFallbackState): void;
+    /**
+     * Produce a pending switch. A fresh decision always supersedes a previous
+     * one and must be applicable at the current (turn, step), so the applied
+     * marker is cleared here (see module doc — chains).
+     */
+    writePending(state: AgentFallbackState, pending: PendingSwitch): void;
+    /**
+     * Apply the pending switch at (turn, step) when one exists and has not
+     * already been applied there; records the applied marker and clears the
+     * pending switch (spec §5.1 lifecycle step 2).
+     */
+    applyPending(state: AgentFallbackState, turn: number, step: number): PendingSwitch | undefined;
+    /**
+     * Defensive `agent/status` idle cleanup: drop per-step state. The time-boxed
+     * cooldown survives so `cooldown-expiry` revert works across turns (US-4).
+     */
+    clearStepState(state: AgentFallbackState): void;
+    /** Suppress `key` until `untilEpochMs` (`Infinity` for `revertPolicy: 'never'`). */
+    suppress(state: AgentFallbackState, key: string, untilEpochMs: number): void;
+    /** Lazy cooldown read: expired entries are dropped on read (spec §5.1). */
+    isSuppressed(state: AgentFallbackState, key: string, now?: number): boolean;
+}

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "dsh-llm-fallbacks",
+  "description": "Automatic provider/model fallback chains for DeepSeek Harness agents when LLM requests keep failing (retry exhausted, auth, quota, rate limit)",
+  "keywords": [
+    "dsh",
+    "dsh-plugin"
+  ],
+  "version": "0.1.0-alpha.1",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "default": "./dist/client/index.js"
+    },
+    "./bundle/cordis.patch.yml": "./bundle/cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "bundle",
+    "scripts"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./bundle/cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-ui-settings-plugins",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-connection",
+        "@deepseek-ai/dsh-api-remotes"
+      ],
+      "platform": "web"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && tsdown && pnpm run build-client && tsc && node scripts/verify-dist.mjs",
+    "build-client": "tsx scripts/build-client.ts",
+    "test": "vitest run",
+    "prepare": "pnpm run build"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-api-gateway": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-api-remotes": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-connection": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-settings-plugins": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-settings": "^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-client-web-react": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-commands": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-settings": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-typert-protocol": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-typert-registry": "^0.1.0-rc.6",
+    "react": "^18.2.0"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^22.20.0",
+    "@types/react": "~18.3.31",
+    "@types/react-dom": "~18.3.7",
+    "jsdom": "29.1.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "schemastery": "^3.18.0",
+    "tsdown": "^0.22.2",
+    "tsx": "^4.22.4",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.8"
+  }
+}