dsh-advisor 0.1.0

package/lib/advisor-runtime.d.ts

@@ -0,0 +1,242 @@
+/**
+ * Per-session advisor runtime (spec §2 S2, §4 mapping rows, §6, §8.2 KD-2,
+ * §8.5 KD-5) — the "advisor model call + note extraction + drain/backlog"
+ * core.
+ *
+ * One {@link AdvisorRuntime} exists per session (created on `agent/created` or
+ * lazily on the first stepped `turn/end`, disposed on `agent/disposed` /
+ * `session/disposed` — wired in `index.ts`). It owns:
+ *
+ * - a FIFO queue of pending transcript deltas (bounded — spec §6 "bounded
+ *   backlog"; drop-newest when full);
+ * - a serialized async drain loop: one `llm.stream` call per delta with
+ *   `{ provider, model, system, messages: [user delta], maxTokens: 5120 }` and
+ *   `purpose` left UNSET (KD-5 — an advisor call is an ordinary conversation
+ *   request);
+ * - a call-level deadline on every `llm.stream` call (dsh-timeout `deadline`,
+ *   fused with the dispose signal and raced per chunk): a hung provider stream
+ *   times out instead of wedging the drain, and a timeout is a transient
+ *   failure (KD-5 retry → drop);
+ * - KD-2 JSON-frame extraction: the first balanced `{…}` in the reply is
+ *   parsed (tolerant of prose/fences), `note` must be non-empty (else
+ *   drop+log), `severity` missing/invalid defaults to `nit`, no parse retry;
+ * - the KD-5 failure policy: transient → 1 retry with a short backoff → drop;
+ *   3 consecutive dropped deltas → flush the pending backlog (never stall);
+ *   permanent errors (`invalid_request_error`, model-not-found, "is not
+ *   supported when") → halt the session's advisor; quota/rate-limit → pause
+ *   (`quota_exhausted`), batch retained, no auto-resume timer; the in-flight
+ *   call is aborted on dispose via the `signal`. `halted` is terminal in
+ *   place — the command layer rebuilds the runtime (dispose + recreate); a
+ *   `quota_exhausted` runtime resumes via {@link AdvisorRuntime.resume}.
+ *
+ * The runtime never parks the primary loop: everything is fire-and-forget
+ * async and a failing advisor can only drop its own backlog.
+ *
+ * @module dsh-advisor/advisor-runtime
+ */
+import type { GenerateOptions, LlmResolvedModelInfo, StreamChunk } from '@deepseek-ai/dsh-llm';
+import type { EmissionGuard } from './emission-guard.js';
+import type { Delta } from './transcript.js';
+/** Severity vocabulary (spec §6) carried by every delivered advice note. */
+export type AdviceSeverity = 'nit' | 'concern' | 'blocker';
+/** One extracted advice note, fed to the T5 emission guard for delivery. */
+export interface AdviceNote {
+    readonly note: string;
+    readonly severity: AdviceSeverity;
+}
+/**
+ * Per-session runtime status surface for T7 `/advisor status`.
+ *
+ * T4 sets `running` | `quota_exhausted` | `halted`; `paused` is reserved for
+ * explicit pause semantics and `disabled` for the config gate — the runtime is
+ * never constructed in either state (`index.ts` returns early when the resolved
+ * config is disabled).
+ */
+export type AdvisorRuntimeStatus = 'running' | 'paused' | 'quota_exhausted' | 'halted' | 'disabled';
+/** Minimal `ctx.llm` surface the runtime drives (satisfied by `LlmRuntime`). */
+export interface AdvisorLlm {
+    stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+    /**
+     * Optional capability query (LlmRuntime exposes it; injected fakes may not).
+     * Used to capability-gate `reasoningEffort` (qc2 W-1 / qc1 W-1 / qc3 F-3):
+     * the dsh LlmRuntime rejects an explicit effort for any model whose adapter
+     * does not declare it, so the runtime resolves the model's declared efforts
+     * and passes `'off'` only when the model supports it. Absent → the option
+     * is omitted and `resolveCallFor` materializes the adapter default.
+     */
+    resolveModelInfo?(provider: string, model: string, signal?: AbortSignal): Promise<LlmResolvedModelInfo>;
+}
+/** Logger seam (cordis `ctx.logger('advisor')` satisfies it; console works too). */
+export interface AdvisorRuntimeLogger {
+    debug(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+}
+/** Options for one per-session {@link AdvisorRuntime}. */
+export interface AdvisorRuntimeOptions {
+    /** Resolved provider route (the explicit gate guarantees it when enabled). */
+    readonly provider: string;
+    /** Resolved model id (the explicit gate guarantees it when enabled). */
+    readonly model: string;
+    /** System prompt sent with every advisor call (config override or KD-2 default). */
+    readonly systemPrompt: string;
+    /** Output-token cap (KD-2); default 256. */
+    readonly maxTokens?: number;
+    /** Backoff for the single transient retry (KD-5); default 1000ms. */
+    readonly retryBackoffMs?: number;
+    /**
+     * Call-level deadline for one `llm.stream` call (qc2 W-4 / qc3 W-1): a hung
+     * provider stream (no chunk, no end, no error) times out instead of wedging
+     * this session's drain. A timeout is classified as a transient failure —
+     * KD-5 retry(1) → drop. Default 60000ms.
+     */
+    readonly callTimeoutMs?: number;
+    /** Bounded backlog (spec §6); default 32 — drop-newest with a log when full. */
+    readonly maxQueued?: number;
+    /** The llm service (`ctx.llm`); injectable for tests. */
+    readonly llm: AdvisorLlm;
+    /**
+     * The T5 emission guard gating extracted notes before delivery. Defaults to
+     * a fresh {@link createEmissionGuard} (per-runtime lifetime — a new guard
+     * per session); injectable for tests.
+     */
+    readonly guard?: EmissionGuard;
+    /**
+     * Invoked once per extracted note that passes the T5 emission guard
+     * (accepted = delivered to T6; suppressed notes are dropped silently).
+     */
+    readonly onNote: (note: AdviceNote) => void;
+    readonly logger?: AdvisorRuntimeLogger;
+}
+/**
+ * n4 user direction: the advisor call runs with a 20x token budget
+ * (256 -> 5120) so even a reasoning-heavy reply cannot starve the JSON frame.
+ * Exported so the test suites assert the pinned value instead of a magic
+ * literal.
+ *
+ * Supersession note (qc2 S-2 / qc1 S-2 / qc3 F-2): the frozen spec §8.2
+ * (KD-2) pins `maxTokens: 256` ("so a runaway reply cannot blow the budget").
+ * This 5120 value is the USER-DIRECTED supersession of that pin — a 20x
+ * worst-case per-call ceiling, adopted together with `reasoningEffort: 'off'`
+ * (capability-gated, see `resolveReasoningEffort`) so the raised budget goes
+ * to the JSON frame rather than reasoning output. The looser runaway-reply
+ * guard is re-bounded downstream: `extractAdviceNote` caps the note at
+ * `ADVISOR_NOTE_MAX_CHARS` and `buildAdvisorMessage` bounds the notice
+ * summary via `boundContextSummary`.
+ */
+export declare const ADVISOR_MAX_TOKENS = 5120;
+/**
+ * One extracted note's length cap (qc3 F-2 / qc2 S-1): a verbose/rogue advisor
+ * reply with the 20x token budget must not inject an unbounded user-role
+ * message into the primary session. Truncated with a '…' marker.
+ */
+export declare const ADVISOR_NOTE_MAX_CHARS = 1000;
+/**
+ * Extract one {@link AdviceNote} from the advisor's reply (KD-2).
+ *
+ * Locates the first balanced `{…}` object (tolerant of surrounding prose and
+ * markdown fences), parses it, and validates: `note` must be a non-empty
+ * string after trim (else drop), `severity` missing/invalid defaults to
+ * `nit`. A reply with no parseable frame returns `undefined` — the caller
+ * drops + logs, and there is NO retry for parse failures (the retry budget is
+ * reserved for transport errors, KD-2). The note is capped at
+ * {@link ADVISOR_NOTE_MAX_CHARS} with a '…' marker (qc3 F-2 — the 20x token
+ * budget must not translate into an unbounded injection into the primary
+ * session). Never throws.
+ */
+export declare function extractAdviceNote(reply: string): AdviceNote | undefined;
+/**
+ * Per-session advisor runtime: queue deltas, async drain, `llm.stream` call,
+ * JSON-frame note extraction, and the KD-5 failure policy. All async work is
+ * fire-and-forget — the primary loop is never parked.
+ */
+export declare class AdvisorRuntime {
+    private readonly provider;
+    private readonly model;
+    private readonly systemPrompt;
+    private readonly maxTokens;
+    private readonly retryBackoffMs;
+    private readonly callTimeoutMs;
+    private readonly maxQueued;
+    private readonly llm;
+    private readonly guard;
+    private readonly onNote;
+    private readonly logger;
+    private readonly controller;
+    /**
+     * Per-(provider, model) reasoning-effort capability cache (qc2 W-1 / qc1
+     * W-1 / qc3 F-3): resolving the model's declared efforts on EVERY advisor
+     * call would add an adapter round-trip per delta; one resolution per
+     * (provider, model) per runtime suffices — the route is pinned for the
+     * runtime's lifetime.
+     */
+    private readonly reasoningEffortCache;
+    private readonly queue;
+    private state;
+    private draining;
+    private disposed;
+    private consecutiveDrops;
+    private drainPromise;
+    /** Epoch-ms of the last note accepted by the emission guard (T7 status). */
+    private lastActivityAt;
+    constructor(options: AdvisorRuntimeOptions);
+    /** Current per-session status (T7 `/advisor status` surface). */
+    status(): AdvisorRuntimeStatus;
+    /** Number of deltas waiting to be drained (bounded by `maxQueued`). */
+    get pendingCount(): number;
+    /**
+     * T7 `/advisor status` surface — epoch-ms of the last note accepted by the
+     * emission guard, or `undefined` before the first accepted note.
+     */
+    get lastActivity(): number | undefined;
+    /**
+     * Queue one rendered transcript delta (from the T3 observer's `onDelta`).
+     * While `quota_exhausted`, deltas queue up (bounded) but the drain is never
+     * auto-restarted (KD-5 — no auto-resume timer); while `halted`/disposed they
+     * are dropped with a log. Never throws, never parks the caller.
+     */
+    enqueue(delta: Delta): void;
+    /** Abort the in-flight call and stop the drain (wiring: session/agent disposed). */
+    dispose(): void;
+    /**
+     * Manual resume after a quota pause (T7 `/advisor on`); no-op when halted/
+     * disposed — a halted runtime is terminal in place and is recovered by the
+     * command layer via dispose-and-recreate (qc1/qc2/qc3 W-1/I-4), never
+     * resumed here.
+     */
+    resume(): void;
+    /**
+     * KD-5 reset trigger: a compaction / surface rewrite clears the emission
+     * guard's dedupe history and per-update latch — the session state is being
+     * rewritten, so the old note history no longer applies (a note already
+     * advised before the rewrite may legitimately be advised again). The wiring
+     * (`index.ts` onRewrite) calls this alongside the delivery cooldown reset.
+     */
+    resetGuard(): void;
+    /** Resolve once the current drain run settles (test/integration hook). */
+    waitForDrain(): Promise<void>;
+    private kickDrain;
+    /** Serialized drain loop: process the queue one delta at a time. */
+    private drain;
+    /** KD-5: clear the pending backlog after consecutive failures (never stall). */
+    private flushBacklog;
+    /** Process one delta: attempt + single retry (transient), classify terminal failures. */
+    private processDelta;
+    /** One model call: build options, stream text, extract the note (KD-2). */
+    private callModel;
+    private buildOptions;
+    /**
+     * Capability-gate the `reasoningEffort: 'off'` option (qc2 W-1 / qc1 W-1 /
+     * qc3 F-3): pass the branded 'off' effort only when the resolved model's
+     * `reasoning.efforts` includes it, else omit the option (`resolveCallFor`
+     * materializes the adapter default). Cached per (provider, model) — one
+     * resolution per runtime, never per call. A resolution failure (unknown
+     * route, adapter throw, or a deadline abort — n4 QC N-5) is advisory: the
+     * call proceeds WITHOUT the option, matching the pre-n4 behavior for every
+     * model that does not declare 'off'. The optional `signal` (the call's
+     * deadline signal) is threaded into `resolveModelInfo`, whose contract
+     * allows adapter-owned asynchronous lookup with cancellation — a hung
+     * lookup that honors the signal aborts with the call deadline instead of
+     * wedging the drain.
+     */
+    private resolveReasoningEffort;
+}