dsh-llm-fallbacks 0.6.13 → 0.7.0

package/package.json

@@ -5,7 +5,7 @@
     "dsh",
     "dsh-plugin"
   ],
-  "version": "0.6.13",
+  "version": "0.7.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -28,7 +28,11 @@
     "bundle",
     "locale",
     "icon.svg",
-    "scripts"
+    "scripts",
+    "docs/DETAIL.md",
+    "docs/DETAIL.zh.md",
+    "docs/preview.svg",
+    "docs/preview.zh.svg"
   ],
   "dsh": {
     "bundle": {
@@ -65,29 +69,29 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.5",
-    "@deepseek-ai/dsh-agent": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-api-gateway": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-api-remotes": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-api-session-controller": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-client-connection": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-client-locale": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-client-store": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-client-ui-chat": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-client-ui-conversation": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-client-ui-plugin-manager": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-client-ui-renderer": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-commands": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-llm": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-llm-retry": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-session": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-session-projection": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-settings": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-system-prompt": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-tool-subagent": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-typert-protocol": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-typert-registry": "^0.2.1-rc.4",
+    "@deepseek-ai/dsh-agent": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-api-gateway": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-api-remotes": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-api-session-controller": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-client-connection": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-client-locale": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-client-store": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-chat": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-plugin-manager": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-renderer": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-commands": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-llm-retry": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-session": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-session-projection": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-settings": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-tool-subagent": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-typert-protocol": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-typert-registry": "^0.2.2-rc.1",
     "@deepseek-ai/schemastery": "^3.18.5",
     "react": "^18.2.0"
   },

package/dist/authorized-route.d.ts

@@ -1,68 +0,0 @@
-/**
- * Authorized-route detection from durable child state (plan
- * dsh-012-subagent-routing T2; spec D2).
- *
- * Pure, host-free module: a plain-data session view in, one route out. The
- * wiring captures the view at a subagent's first request from the detection
- * sources the plan names (shapes verified against upstream
- * `packages/subagent/subagent/src/child-agent.ts:68-85` and
- * `packages/api/session-controller/src/types.ts:284`):
- *
- * - the session's `model/selection` log entries (plain descriptors; payload
- *   is the `ModelSelection` shape — provider, model, optional
- *   reasoningEffort), an explicit host-recorded selection for this session;
- * - the durable `request/header` config fold (`requestHeader()?.config`);
- * - the resolved creation options (`agent.options`) as the pre-first-request
- *   fallback — upstream precedence: the durable header wins, options
- *   fallback (`parentAgentOptionsForDelegation`);
- * - the pure-inheritance baseline: the delegating parent's current route,
- *   resolved by the wiring the same way (`requestHeader()?.config` else
- *   creation options).
- *
- * A source yields a route only when BOTH provider and model are present
- * non-empty strings — an effort alone is not a route (spec Terms). A
- * `model/selection` entry is definitionally an explicit selection, so it is
- * authorized as-is. A route read from the header or the creation options is
- * explicit only when it is NOT the pure-inheritance continuation: when the
- * baseline is provable (complete) and equals the candidate exactly, the
- * candidate is the parent's inherited route, not a selection — pure
- * inheritance is NOT an authorized route (spec Terms; upstream
- * `resolveChildAgentOptions` materializes the parent route into child
- * options even without an explicit selection, so equality with the baseline
- * is the only child-side inheritance signal). With the baseline unprovable
- * the candidate stands: D2 keeps authorized chain heads unoverwritten, and
- * the allowlist-constrained inject below this decision holds D1 either way.
- *
- * Never throws; malformed source shapes yield `undefined`, not routes.
- *
- * @module dsh-llm-fallbacks/authorized-route
- */
-import type { PolicyRoute } from './subagent-policy.ts';
-/** One plain route-bearing source shape (header config, options, selection payload, baseline). */
-export type RouteSource = {
-    readonly provider?: unknown;
-    readonly model?: unknown;
-    readonly reasoningEffort?: unknown;
-};
-/** Structural session view consumed by {@link detectAuthorizedRoute} — plain data only, no live host objects. */
-export interface AuthorizedRouteSession {
-    /** Durable request-header config fold captured from the child session (absent before the first logged header). */
-    readonly requestHeader?: RouteSource | undefined;
-    /** Plain event descriptors (`type` + optional `data`) captured from the child session's log. */
-    readonly events?: readonly {
-        readonly type: string;
-        readonly data?: unknown;
-    }[] | undefined;
-    /** Resolved creation options captured from the agent (pre-first-request fallback). */
-    readonly options?: RouteSource | undefined;
-    /** Pure-inheritance baseline: the delegating parent's current route (absent when unprovable). */
-    readonly inherited?: RouteSource | undefined;
-}
-/**
- * Detect the subagent's explicit authorized route at its first request, or
- * `undefined` for pure inheritance (semantics in the module doc). The wiring
- * skips role-inject on a defined result — the authorized route is the chain
- * head (spec D2) — and runs the allowlist-constrained four-stage inject on
- * `undefined`.
- */
-export declare function detectAuthorizedRoute(session: AuthorizedRouteSession): PolicyRoute | undefined;

package/dist/automatch.d.ts

@@ -1,98 +0,0 @@
-/**
- * LLM auto-match role selection (plan fallbacks-role-automatch Task 3).
- *
- * This module is the bounded LLM caller behind the resolver's stage-3
- * auto-match hook (`resolveRoleAtDispatch`, `role-resolution.ts`). When the
- * explicit and rules stages resolve to `'inherit'` and `roleAutoMatch` is
- * enabled, `pickRoleByLlm` asks the model to pick the best-fit declared role
- * from the taxonomy and returns its declared RAW id, or `null` (= `'inherit'`).
- *
- * Contract (architect-locked, plan Global Constraints · Auto-match bounded):
- * - ONE bounded completion per decision: small `maxTokens`
- *   ({@link AUTOMATCH_MAX_TOKENS}) and a timeout
- *   ({@link AUTOMATCH_TIMEOUT_MS}, default 5s) that abandons the stream via
- *   the streaming contract's cancellation (`options.signal`) — no dangling
- *   iterator, no unhandled rejection.
- * - Never throws. Every failure mode — throw, timeout, `none`, no valid id,
- *   garbage answer, malformed inputs — resolves to `null`, so the "never
- *   throws out of `agent/request`" invariant holds end-to-end (the resolver
- *   deliberately does NOT catch the hook).
- * - Fast paths that avoid an LLM call entirely: empty taxonomy, absent
- *   `ctx.llm` service, and no concrete provider/model route for the judgment
- *   call. The plugin does NOT listen on `llm/stream`, so this call cannot
- *   recurse into the plugin.
- *
- * Judgment-call route choice (documented): the concrete provider/model for the
- * judgment call is taken from the roles' DECLARED context first — the first
- * exact (non-wildcard) `provider/model` selector across the declared chains,
- * in declaration order (the operator's own taxonomy is the most stable route
- * set). If no declared chain yields an exact selector, the agent's current
- * `options.provider`/`options.model` is used when both halves are present;
- * otherwise the call is skipped (`null`).
- *
- * Pure helpers exported for unit testing:
- * - {@link buildAutomatchPrompt} — the taxonomy prompt (declared ids +
- *   personas + agent origin/agentPreset; instructs exactly-one-declared-id-or-
- *   `none`).
- * - {@link parseAutomatchAnswer} — parses a declared id out of the model
- *   answer with surrounding whitespace/punctuation/quote/backtick tolerance;
- *   `none` (case-insensitive) and unknown ids → `null`. `roleIds` is the
- *   trimmed-id → declared-raw-id map, the same canonicalization the resolver
- *   uses.
- *
- * @module dsh-llm-fallbacks/automatch
- */
-import { type GenerateOptions, type StreamChunk } from '@deepseek-ai/dsh-llm';
-import type { FallbacksRole, FallbacksRoles } from './config.ts';
-import type { AgentLike } from './roles.ts';
-/** Default auto-match completion timeout in ms — abandons the stream. */
-export declare const AUTOMATCH_TIMEOUT_MS = 5000;
-/** Output bound (tokens) for the judgment call: one id or the literal `none`. */
-export declare const AUTOMATCH_MAX_TOKENS = 32;
-/**
- * Minimal `llm` service surface {@link pickRoleByLlm} reads. The real
- * `LlmRuntime.stream(options)` matches structurally; this face keeps the
- * module free of the full cordis Context merge.
- */
-export interface AutomatchLlm {
-    stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
-}
-/**
- * Minimal context surface: `ctx.get('llm')` (optional service — absent →
- * `null` fast-path). The broad `get(name: string)` face is satisfied by the
- * real cordis `Context` (`ReflectService.get` overloads return `any`/the
- * merged service), so the Task-4 wiring can pass `ctx` directly.
- */
-export interface AutomatchContext {
-    get(name: string): AutomatchLlm | undefined;
-}
-/** Options for {@link pickRoleByLlm}. */
-export interface PickRoleByLlmOptions {
-    /** Completion timeout in ms; defaults to {@link AUTOMATCH_TIMEOUT_MS}. */
-    timeoutMs?: number;
-    /** Warning sink — the decision path injects the plugin logger. */
-    warn: (message: string) => void;
-}
-/**
- * Build the auto-match taxonomy prompt: every declared role's trimmed id and
- * persona, the agent's origin (and non-empty `agentPreset` when present), and
- * the exactly-one-declared-id-or-`none` instruction. Pure — no I/O.
- */
-export declare function buildAutomatchPrompt(roles: readonly FallbacksRole[], agent: AgentLike): string;
-/**
- * Parse the model's answer into a declared role id.
- *
- * The answer is expected to BE an id (possibly wrapped in whitespace, quotes,
- * backticks, or trailing punctuation); surrounding characters outside the id
- * grammar (`[a-zA-Z0-9-]`) are stripped, then the remaining string must match
- * a declared id exactly (case-insensitive) via `roleIds` (trimmed id →
- * declared RAW id, the resolver's canonicalization). `none` (case-insensitive)
- * and any unknown/malformed answer → `null`.
- */
-export declare function parseAutomatchAnswer(answer: string, roleIds: ReadonlyMap<string, string>): string | null;
-/**
- * Bounded LLM role-selection call (see module header). Resolves the declared
- * RAW id of the best-fit role, or `null` on any fast path or failure. NEVER
- * throws.
- */
-export declare function pickRoleByLlm(ctx: AutomatchContext, roles: FallbacksRoles, agent: AgentLike, opts: PickRoleByLlmOptions): Promise<string | null>;

package/dist/override.d.ts

@@ -1,39 +0,0 @@
-/**
- * RouteChanged effort rule for config overrides (plan dsh-012-subagent-routing
- * T4; spec D3).
- *
- * Pure, host-free module: plain seed config plus a target route in, the
- * overridden config out. The effort handling mirrors the upstream
- * `resolveChildAgentOptions` rule (deepseek-harness
- * `subagent/src/child-agent.ts:117`): a changed provider+model route drops the
- * seed's route-owned `reasoningEffort` so the selected model resolves its own
- * default, unless an effort is explicitly named for the override; an
- * unchanged route keeps the seed effort. Policy-independent by design — the
- * same rule applies on every override path whether the subagent routing
- * policy is on or off (spec D3). Never throws.
- *
- * @module dsh-llm-fallbacks/override
- */
-import type { LlmCallConfig } from '@deepseek-ai/dsh-llm';
-/** Reasoning-effort value carried by `LlmCallConfig.reasoningEffort`. */
-export type LlmReasoningEffort = NonNullable<LlmCallConfig['reasoningEffort']>;
-/**
- * Override a request config with a target route under the upstream
- * routeChanged effort rule (spec D3):
- *
- * - An explicitly named effort always survives — it wins over the seed effort
- *   on either route (upstream semantics: the request overrides the parent).
- * - Same provider+model route → the seed `reasoningEffort` is preserved.
- * - Route changed without an explicit effort → the seed effort is dropped
- *   (never carry a stale effort into a different provider/model route).
- *
- * @param seed - the caller's current request config.
- * @param to - the effective target route.
- * @param explicitEffort - an effort explicitly named for this override.
- * @returns a fresh config routed to `to` with the effort rule applied; never
- * mutates `seed`.
- */
-export declare function overrideConfigWithRouteRule(seed: LlmCallConfig, to: {
-    provider: string;
-    model: string;
-}, explicitEffort?: LlmReasoningEffort): LlmCallConfig;