dsh-advisor 0.1.0

package/lib/commands.d.ts

@@ -0,0 +1,136 @@
+/**
+ * T7 — slash commands (spec §2 S5, §6 status surface, §8.5 KD-5 seed-on-enable).
+ *
+ * One `/advisor` command is registered (through {@link registerAdvisorCommands})
+ * with four forms:
+ *
+ * - `/advisor`           — toggle the per-session override (on ↔ off);
+ * - `/advisor on`        — enable the advisor for this session;
+ * - `/advisor off`       — disable the advisor for this session;
+ * - `/advisor status`    — report the per-session status surface;
+ * - anything else        — usage text.
+ *
+ * Toggle/on/off are **session-scoped and ephemeral**: they drive a per-session
+ * override flag (`AdvisorSessionOverrides`) that the runtime gate consults as
+ * `override ?? config.enabled`, so no command ever touches the persisted
+ * config (spec §4 mapping — matches omp `/advisor` semantics). Enabling a
+ * session whose config has no provider/model starts no model call: the S4
+ * explicit gate (spec §5.2) still applies, and the status/on text explains
+ * the disabled-with-reason.
+ *
+ * The module is cordis-free (pure parse + render + registration contract), so
+ * it is unit-testable with a fake command registry and a fake controller;
+ * `index.ts` binds it into the plugin through the conditional
+ * `ctx.inject(['commands'], ...)` child (commands must NOT join the top-level
+ * inject list — T1 fix).
+ *
+ * @module dsh-advisor/commands
+ */
+import type { CommandDefinition } from '@deepseek-ai/dsh-commands';
+import type { AdvisorRuntimeStatus } from './advisor-runtime.js';
+/** The parsed form of the exact text following `/advisor`. */
+export type AdvisorCommand = {
+    readonly kind: 'toggle';
+} | {
+    readonly kind: 'on';
+} | {
+    readonly kind: 'off';
+} | {
+    readonly kind: 'status';
+} | {
+    readonly kind: 'usage';
+};
+/**
+ * Parse the text following `/advisor` (the dsh `parseCommand` split already
+ * yields `rawInput` including the separator whitespace, e.g. `' on'` for
+ * `/advisor on`). Subcommands match exactly after trimming — same
+ * case-sensitivity as dsh command names; anything else is a usage error.
+ */
+export declare function parseAdvisorCommand(rawInput: string): AdvisorCommand;
+/**
+ * The per-session override consulted by the runtime gate as
+ * `override ?? config.enabled`. `/advisor on|off|toggle` write here — the
+ * persisted config is never modified. The map is keyed by session id and
+ * entries live for the session lifetime (`index.ts` clears them on
+ * `agent/disposed` / `session/disposed`).
+ */
+export declare class AdvisorSessionOverrides {
+    private configEnabled;
+    private readonly overrides;
+    constructor(configEnabled: boolean);
+    /** Effective switch for one session: `override ?? config.enabled`. */
+    effective(sessionId: string): boolean;
+    /**
+     * Update the config-level fallback switch (live config — settings onChange,
+     * plan dsh-advisor-settings-n2 T1). Sessions with an explicit override keep
+     * it; every other session follows the new switch, so a Settings-page edit
+     * takes effect for new sessions without touching the override mechanism.
+     */
+    setConfigEnabled(enabled: boolean): void;
+    /** Set the override for one session. */
+    set(sessionId: string, enabled: boolean): void;
+    /** Remove a session's override, falling back to the config switch. */
+    clear(sessionId: string): void;
+}
+/**
+ * Per-session status snapshot consumed by `/advisor status`. Built by the
+ * wiring (`index.ts`) from the resolved config, the session's runtime, and
+ * the override state.
+ */
+export interface AdvisorSessionStatus {
+    /** Effective switch for this session (`override ?? config.enabled`). */
+    readonly enabled: boolean;
+    /**
+     * Present iff the session is effectively enabled but the S4 explicit gate
+     * blocks model calls (provider/model missing or empty) — disabled-with-
+     * reason (spec §5.2).
+     */
+    readonly disabledReason?: string;
+    /** Configured provider route (shown even while disabled — spec §5.2). */
+    readonly provider?: string;
+    /** Configured model id (shown even while disabled — spec §5.2). */
+    readonly model?: string;
+    /** The session's runtime status; `disabled` when no runtime exists. */
+    readonly runtimeStatus: AdvisorRuntimeStatus;
+    /** Deltas waiting to be drained (bounded backlog, spec §6). */
+    readonly pendingCount: number;
+    /** Epoch-ms of the last accepted note; undefined before the first (T4). */
+    readonly lastActivityAt?: number;
+}
+/**
+ * Render the status surface. Kept minimal and truthful: state, the S4 reason
+ * when the gate blocks, the resolved provider/model, the runtime status with
+ * the pending count, and the last accepted-note activity (ISO, or `never`).
+ */
+export declare function advisorStatusText(status: AdvisorSessionStatus): string;
+/**
+ * The session-scoped operations the `/advisor` handler drives. Implemented by
+ * the wiring (`index.ts`) against the observer, the per-session runtimes, and
+ * the resolved config; faked in unit tests.
+ */
+export interface AdvisorCommandController {
+    /**
+     * Apply the session override and start/stop the session's runtime:
+     * enabling seeds the observer cursor to the current transcript length
+     * (KD-5 — no full-history replay) and resumes/creates the runtime; disabling
+     * disposes the runtime (aborts the in-flight call, drops the backlog).
+     * @param sessionLength - current transcript length, used for the KD-5 seed.
+     */
+    setEnabled(sessionId: string, enabled: boolean, sessionLength?: number): void;
+    /** Snapshot the per-session status surface. */
+    getStatus(sessionId: string): AdvisorSessionStatus;
+}
+/** Minimal command registry surface (satisfied by the dsh `CommandService`). */
+export interface AdvisorCommandRegistry {
+    register(definition: CommandDefinition): () => void;
+}
+/** Usage text for an unknown `/advisor` subcommand. */
+export declare const USAGE: string;
+/**
+ * Register the `/advisor` command with a command registry (the dsh
+ * `CommandService`, or a fake in tests). Called from the plugin's conditional
+ * `ctx.inject(['commands'], ...)` child — the command exists only when a
+ * registry is composed.
+ * @returns the registry disposer (the inject child owns its lifetime).
+ */
+export declare function registerAdvisorCommands(registry: AdvisorCommandRegistry, controller: AdvisorCommandController): () => void;

package/lib/commands.js

@@ -0,0 +1,185 @@
+/**
+ * T7 — slash commands (spec §2 S5, §6 status surface, §8.5 KD-5 seed-on-enable).
+ *
+ * One `/advisor` command is registered (through {@link registerAdvisorCommands})
+ * with four forms:
+ *
+ * - `/advisor`           — toggle the per-session override (on ↔ off);
+ * - `/advisor on`        — enable the advisor for this session;
+ * - `/advisor off`       — disable the advisor for this session;
+ * - `/advisor status`    — report the per-session status surface;
+ * - anything else        — usage text.
+ *
+ * Toggle/on/off are **session-scoped and ephemeral**: they drive a per-session
+ * override flag (`AdvisorSessionOverrides`) that the runtime gate consults as
+ * `override ?? config.enabled`, so no command ever touches the persisted
+ * config (spec §4 mapping — matches omp `/advisor` semantics). Enabling a
+ * session whose config has no provider/model starts no model call: the S4
+ * explicit gate (spec §5.2) still applies, and the status/on text explains
+ * the disabled-with-reason.
+ *
+ * The module is cordis-free (pure parse + render + registration contract), so
+ * it is unit-testable with a fake command registry and a fake controller;
+ * `index.ts` binds it into the plugin through the conditional
+ * `ctx.inject(['commands'], ...)` child (commands must NOT join the top-level
+ * inject list — T1 fix).
+ *
+ * @module dsh-advisor/commands
+ */
+/**
+ * Parse the text following `/advisor` (the dsh `parseCommand` split already
+ * yields `rawInput` including the separator whitespace, e.g. `' on'` for
+ * `/advisor on`). Subcommands match exactly after trimming — same
+ * case-sensitivity as dsh command names; anything else is a usage error.
+ */
+export function parseAdvisorCommand(rawInput) {
+    const argument = rawInput.trim();
+    if (argument === '')
+        return { kind: 'toggle' };
+    if (argument === 'on')
+        return { kind: 'on' };
+    if (argument === 'off')
+        return { kind: 'off' };
+    if (argument === 'status')
+        return { kind: 'status' };
+    return { kind: 'usage' };
+}
+// ---------------------------------------------------------------------------
+// Per-session override mechanism (session-scoped, ephemeral)
+// ---------------------------------------------------------------------------
+/**
+ * The per-session override consulted by the runtime gate as
+ * `override ?? config.enabled`. `/advisor on|off|toggle` write here — the
+ * persisted config is never modified. The map is keyed by session id and
+ * entries live for the session lifetime (`index.ts` clears them on
+ * `agent/disposed` / `session/disposed`).
+ */
+export class AdvisorSessionOverrides {
+    configEnabled;
+    overrides = new Map();
+    constructor(configEnabled) {
+        this.configEnabled = configEnabled;
+    }
+    /** Effective switch for one session: `override ?? config.enabled`. */
+    effective(sessionId) {
+        return this.overrides.get(sessionId) ?? this.configEnabled;
+    }
+    /**
+     * Update the config-level fallback switch (live config — settings onChange,
+     * plan dsh-advisor-settings-n2 T1). Sessions with an explicit override keep
+     * it; every other session follows the new switch, so a Settings-page edit
+     * takes effect for new sessions without touching the override mechanism.
+     */
+    setConfigEnabled(enabled) {
+        this.configEnabled = enabled;
+    }
+    /** Set the override for one session. */
+    set(sessionId, enabled) {
+        this.overrides.set(sessionId, enabled);
+    }
+    /** Remove a session's override, falling back to the config switch. */
+    clear(sessionId) {
+        this.overrides.delete(sessionId);
+    }
+}
+/**
+ * Render the status surface. Kept minimal and truthful: state, the S4 reason
+ * when the gate blocks, the resolved provider/model, the runtime status with
+ * the pending count, and the last accepted-note activity (ISO, or `never`).
+ */
+export function advisorStatusText(status) {
+    const lines = [];
+    lines.push(status.enabled ? 'Advisor: enabled' : 'Advisor: disabled');
+    if (status.disabledReason !== undefined)
+        lines.push(`Reason: ${status.disabledReason}`);
+    if (status.provider && status.model) {
+        lines.push(`Model: ${status.provider}/${status.model}`);
+    }
+    const pending = status.pendingCount > 0 ? ` (${status.pendingCount} pending)` : '';
+    lines.push(`Runtime: ${status.runtimeStatus}${pending}`);
+    lines.push(`Last activity: ${status.lastActivityAt === undefined ? 'never' : new Date(status.lastActivityAt).toISOString()}`);
+    return lines.join('\n');
+}
+/** Usage text for an unknown `/advisor` subcommand. */
+export const USAGE = [
+    'Usage: /advisor [on|off|status]',
+    '  /advisor          toggle the advisor for this session',
+    '  /advisor on       enable the advisor for this session',
+    '  /advisor off      disable the advisor for this session',
+    '  /advisor status   show per-session advisor status (state, model, runtime, pending, last activity)',
+].join('\n');
+/**
+ * "Enabled" outcome text — mentions the S4 gate when it blocks model calls.
+ * Callers pass the status AFTER the override flip, so the caveat appears when
+ * the flip itself is what trips the gate (qc2 W-2 / qc3 I-2 — the pre-flip
+ * status cannot know the gate yet: the gate only fires when enabled).
+ */
+function enableText(status) {
+    if (status.disabledReason === undefined)
+        return 'Advisor on for this session.';
+    return `Advisor on for this session — but no model call can start: ${status.disabledReason}`;
+}
+/** Build the `/advisor` handler bound to one controller. */
+function createAdvisorCommandHandler(controller) {
+    return (invocation) => {
+        const sessionId = invocation.agent.session.id;
+        switch (parseAdvisorCommand(invocation.rawInput).kind) {
+            case 'toggle': {
+                const before = controller.getStatus(sessionId);
+                const next = !before.enabled;
+                // The KD-5 seed length is only meaningful when enabling.
+                controller.setEnabled(sessionId, next, next ? invocation.agent.session.events.length : undefined);
+                if (!next)
+                    return { kind: 'success', text: 'Advisor off for this session.' };
+                // Post-flip status: the reply carries the S4 gate caveat when the
+                // toggle-to-on flip trips the gate (qc2 W-2 / qc3 I-2).
+                return { kind: 'success', text: enableText(controller.getStatus(sessionId)) };
+            }
+            case 'on': {
+                const before = controller.getStatus(sessionId);
+                // Recovery routing (qc1/qc2/qc3 W-1/I-4): an effectively-enabled
+                // session whose runtime is halted/quota-paused must reach `setEnabled`
+                // (which resumes/rebuilds it) — a plain "already on" would be a dead
+                // end, since the only resume call site sits behind the enable path.
+                const needsRecovery = before.enabled
+                    && (before.runtimeStatus === 'halted' || before.runtimeStatus === 'quota_exhausted');
+                if (before.enabled && !needsRecovery) {
+                    return { kind: 'success', text: 'Advisor is already on for this session.' };
+                }
+                controller.setEnabled(sessionId, true, invocation.agent.session.events.length);
+                // Reply from the POST-flip status: when the override flip trips the
+                // S4 gate (config-off + missing provider/model), the reply must say
+                // the advisor did not start and why, not a bare "Advisor on" (qc2
+                // W-2 / qc3 I-2).
+                return { kind: 'success', text: enableText(controller.getStatus(sessionId)) };
+            }
+            case 'off': {
+                const before = controller.getStatus(sessionId);
+                if (!before.enabled)
+                    return { kind: 'success', text: 'Advisor is already off for this session.' };
+                controller.setEnabled(sessionId, false);
+                return { kind: 'success', text: 'Advisor off for this session.' };
+            }
+            case 'status':
+                return { kind: 'success', text: advisorStatusText(controller.getStatus(sessionId)) };
+            case 'usage':
+                return { kind: 'success', text: USAGE };
+        }
+    };
+}
+/**
+ * Register the `/advisor` command with a command registry (the dsh
+ * `CommandService`, or a fake in tests). Called from the plugin's conditional
+ * `ctx.inject(['commands'], ...)` child — the command exists only when a
+ * registry is composed.
+ * @returns the registry disposer (the inject child owns its lifetime).
+ */
+export function registerAdvisorCommands(registry, controller) {
+    return registry.register({
+        name: 'advisor',
+        description: 'Toggle, enable, disable, or inspect the per-session advisor',
+        input: { hint: '[on|off|status]' },
+        handler: createAdvisorCommandHandler(controller),
+    });
+}
+//# sourceMappingURL=commands.js.map

package/lib/commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.js","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"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"}

package/lib/config.d.ts

@@ -0,0 +1,74 @@
+/**
+ * dsh-advisor plugin configuration contract (spec §5 / S4).
+ *
+ * The exported schemastery `Config` schema is what the cordis Loader uses to
+ * validate the plugin row config: it applies defaults (`enabled` false,
+ * `immuneTurns` 3, `maxDeltaMessages` 60, `systemPrompt` "") and enforces
+ * types/bounds (integers ≥ 0). `resolveAdvisorConfig(raw)` additionally
+ * enforces the explicit model gate: when `enabled` is true but `provider` or
+ * `model` is missing or empty, it resolves to a disabled-with-reason config —
+ * the advisor never starts a model call (hard gate, not a warning).
+ *
+ * @module dsh-advisor/config
+ */
+import z from 'schemastery';
+/** Raw plugin row config after Loader defaults — spec §5.1. */
+export interface AdvisorConfig {
+    /** Master switch; default false. */
+    readonly enabled: boolean;
+    /** Provider route; REQUIRED (non-empty) when enabled. */
+    readonly provider?: string;
+    /** Model id; REQUIRED (non-empty) when enabled. */
+    readonly model?: string;
+    /** Optional system prompt override; "" = built-in reviewer prompt (T4). */
+    readonly systemPrompt: string;
+    /** Cooldown after a delivered interrupt; integer ≥ 0, default 3. */
+    readonly immuneTurns: number;
+    /** Delta window; integer ≥ 0, default 60, 0 = unbounded (KD-3). */
+    readonly maxDeltaMessages: number;
+}
+/** Config after the explicit model gate (spec §5.2) — consumed by T4/T6. */
+export interface ResolvedAdvisorConfig {
+    readonly enabled: boolean;
+    readonly provider?: string;
+    readonly model?: string;
+    readonly systemPrompt: string;
+    readonly immuneTurns: number;
+    readonly maxDeltaMessages: number;
+    /** Present iff the advisor is disabled by the explicit model gate. */
+    readonly disabledReason?: string;
+}
+/**
+ * Loader schema (strict): defaults + type/bounds validation for the plugin
+ * row config. The explicit gate is intentionally NOT here — `provider`/`model`
+ * stay optional so an enabled-without-pair config validates and then resolves
+ * to disabled-with-reason instead of failing to load.
+ *
+ * Type note: left to inference (`Schema<ObjectS, ObjectT>`), so calling the
+ * schema accepts partial input (each key optional, `| null`) and yields the
+ * fully-defaulted output — matching schemastery's runtime semantics.
+ */
+export declare const Config: z<Schemastery.ObjectS<{
+    enabled: z<boolean, boolean>;
+    provider: z<string, string>;
+    model: z<string, string>;
+    systemPrompt: z<string, string>;
+    immuneTurns: z<number, number>;
+    maxDeltaMessages: z<number, number>;
+}>, Schemastery.ObjectT<{
+    enabled: z<boolean, boolean>;
+    provider: z<string, string>;
+    model: z<string, string>;
+    systemPrompt: z<string, string>;
+    immuneTurns: z<number, number>;
+    maxDeltaMessages: z<number, number>;
+}>>;
+/**
+ * Resolve the raw config into the runtime contract.
+ *
+ * - Rejects unknown keys (strict schema, spec §5.2) and non-object input.
+ * - Applies the explicit model gate (S4): `enabled: true` with `provider` or
+ *   `model` missing/empty → disabled-with-reason, never throws, no model call.
+ * - `provider`/`model` are ignored while disabled.
+ */
+export declare function resolveAdvisorConfig(raw: unknown): ResolvedAdvisorConfig;

package/lib/config.js

@@ -0,0 +1,93 @@
+/**
+ * dsh-advisor plugin configuration contract (spec §5 / S4).
+ *
+ * The exported schemastery `Config` schema is what the cordis Loader uses to
+ * validate the plugin row config: it applies defaults (`enabled` false,
+ * `immuneTurns` 3, `maxDeltaMessages` 60, `systemPrompt` "") and enforces
+ * types/bounds (integers ≥ 0). `resolveAdvisorConfig(raw)` additionally
+ * enforces the explicit model gate: when `enabled` is true but `provider` or
+ * `model` is missing or empty, it resolves to a disabled-with-reason config —
+ * the advisor never starts a model call (hard gate, not a warning).
+ *
+ * @module dsh-advisor/config
+ */
+import z from 'schemastery';
+/**
+ * Complete configuration key set for strict unknown-key rejection. The
+ * schemastery object resolver merges unknown keys by default (strict flag is
+ * never passed by the cordis Loader), so the resolver rejects them explicitly
+ * — same pattern as `resolveSessionTitleLlmConfig` in the dsh repo.
+ */
+const CONFIG_KEYS = new Set([
+    'enabled',
+    'provider',
+    'model',
+    'systemPrompt',
+    'immuneTurns',
+    'maxDeltaMessages',
+]);
+/**
+ * Loader schema (strict): defaults + type/bounds validation for the plugin
+ * row config. The explicit gate is intentionally NOT here — `provider`/`model`
+ * stay optional so an enabled-without-pair config validates and then resolves
+ * to disabled-with-reason instead of failing to load.
+ *
+ * Type note: left to inference (`Schema<ObjectS, ObjectT>`), so calling the
+ * schema accepts partial input (each key optional, `| null`) and yields the
+ * fully-defaulted output — matching schemastery's runtime semantics.
+ */
+export const Config = z.object({
+    enabled: z.boolean().default(false),
+    provider: z.string(),
+    model: z.string(),
+    systemPrompt: z.string().default(''),
+    immuneTurns: z.number().step(1).min(0).default(3),
+    maxDeltaMessages: z.number().step(1).min(0).default(60),
+});
+function isNonEmptyString(value) {
+    // Trim before checking: a whitespace-only value ("   ") is empty in effect
+    // and must trip the explicit gate (spec §5.2 "missing or empty"; qc2 W-3 /
+    // qc3 I-3 — a strict superset of dsh's own `length === 0` check).
+    return typeof value === 'string' && value.trim().length > 0;
+}
+/**
+ * Resolve the raw config into the runtime contract.
+ *
+ * - Rejects unknown keys (strict schema, spec §5.2) and non-object input.
+ * - Applies the explicit model gate (S4): `enabled: true` with `provider` or
+ *   `model` missing/empty → disabled-with-reason, never throws, no model call.
+ * - `provider`/`model` are ignored while disabled.
+ */
+export function resolveAdvisorConfig(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new TypeError('dsh-advisor: configuration must be a plain object');
+    }
+    for (const key of Object.keys(raw)) {
+        if (!CONFIG_KEYS.has(key)) {
+            throw new Error(`dsh-advisor: unknown config key "${key}"`);
+        }
+    }
+    const config = Config(raw);
+    // schemastery passes nullable input (null) through for fields without a
+    // default — normalize to undefined so the resolved contract is null-free
+    // and the gate treats null exactly like a missing value.
+    const normalized = {
+        ...config,
+        provider: config.provider ?? undefined,
+        model: config.model ?? undefined,
+    };
+    if (!normalized.enabled)
+        return normalized;
+    const missing = [];
+    if (!isNonEmptyString(normalized.provider))
+        missing.push('provider');
+    if (!isNonEmptyString(normalized.model))
+        missing.push('model');
+    if (missing.length === 0)
+        return normalized;
+    const disabledReason = missing.length === 2
+        ? 'enabled but provider and model are missing — configure both to enable the advisor'
+        : `enabled but ${missing[0]} is missing or empty — configure provider and model`;
+    return { ...normalized, enabled: false, disabledReason };
+}
+//# sourceMappingURL=config.js.map

package/lib/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,CAAC,MAAM,aAAa,CAAA;AA8B3B;;;;;GAKG;AACH,MAAM,WAAW,GAAwB,IAAI,GAAG,CAAC;IAC/C,SAAS;IACT,UAAU;IACV,OAAO;IACP,cAAc;IACd,aAAa;IACb,kBAAkB;CACnB,CAAC,CAAA;AAEF;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7B,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IACnC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;IACpC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IACjD,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;CACxD,CAAC,CAAA;AAEF,SAAS,gBAAgB,CAAC,KAAyB;IACjD,2EAA2E;IAC3E,2EAA2E;IAC3E,kEAAkE;IAClE,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAA;AAC7D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAY;IAC/C,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAClE,MAAM,IAAI,SAAS,CAAC,mDAAmD,CAAC,CAAA;IAC1E,CAAC;IACD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACnC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,oCAAoC,GAAG,GAAG,CAAC,CAAA;QAC7D,CAAC;IACH,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAA;IAC1B,wEAAwE;IACxE,yEAAyE;IACzE,yDAAyD;IACzD,MAAM,UAAU,GAAkB;QAChC,GAAG,MAAM;QACT,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,SAAS;QACtC,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,SAAS;KACjC,CAAA;IACD,IAAI,CAAC,UAAU,CAAC,OAAO;QAAE,OAAO,UAAU,CAAA;IAC1C,MAAM,OAAO,GAAa,EAAE,CAAA;IAC5B,IAAI,CAAC,gBAAgB,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;IACpE,IAAI,CAAC,gBAAgB,CAAC,UAAU,CAAC,KAAK,CAAC;QAAE,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IAC9D,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,UAAU,CAAA;IAC3C,MAAM,cAAc,GAAG,OAAO,CAAC,MAAM,KAAK,CAAC;QACzC,CAAC,CAAC,mFAAmF;QACrF,CAAC,CAAC,eAAe,OAAO,CAAC,CAAC,CAAC,qDAAqD,CAAA;IAClF,OAAO,EAAE,GAAG,UAAU,EAAE,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,CAAA;AAC1D,CAAC"}

package/lib/delivery.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Delivery routing (spec §2 S3, §4 mapping row, §6 delivery semantics,
+ * §8.4 KD-4) — the advice delivery channel into the primary agent.
+ *
+ * One {@link AdvisorDelivery} exists per plugin load and owns:
+ *
+ * - **The KD-4 per-session agent map**: keyed by `agent.id` (=== `session.id`),
+ *   maintained by `index.ts` on `agent/created` / `agent/disposed`, with a
+ *   registry fallback (`ctx.agents.get(session.id)`, injected as
+ *   `lookupAgent`) that covers agents published before this plugin loaded.
+ *   A missing agent at delivery time drops the note with a log — advisory
+ *   only, never throw, never stall.
+ * - **Severity routing (spec §6)**: nit → `agent.inject` (non-waking, consumed
+ *   at the next pre-step boundary); concern/blocker → `agent.steer` (waking —
+ *   an idle driver starts a turn, a running driver consumes at its next step
+ *   boundary).
+ * - **The immuneTurns cooldown (spec §6)**: after a concern/blocker is actually
+ *   steered, the next `immuneTurns` stepped primary turns must complete before
+ *   another interrupting note may steer; interrupting notes inside the window
+ *   downgrade to inject. The fence arms only on a real steer delivery; the
+ *   observer's `onSteppedTurnEnd` / `onRewrite` hooks (T3 wiring) drive the
+ *   countdown and the KD-5 reset.
+ *
+ * Message shape (spec §6): a user-role message via `createUserMessage` whose
+ * source carries the distinct `kind === 'advisor'` (the plugin's
+ * `MessageSourceMap` merge extension, src/kinds.ts) and whose content is
+ * self-describing `[advisor:{severity}] {note}` — the only cue the primary
+ * model gets about how to treat it ("weigh, don't blindly obey" spirit).
+ *
+ * Delivery is synchronous and fire-and-forget; the runtime path (T4 F1) is
+ * what contains a throwing `inject`/`steer` — this module lets agent-method
+ * throws propagate to that containment seam.
+ *
+ * @module dsh-advisor/delivery
+ */
+import type { UserMessage } from '@deepseek-ai/dsh-llm';
+import type { AdviceNote } from './advisor-runtime.js';
+/** The channel one accepted note is delivered on (spec §6). */
+export type DeliveryChannel = 'inject' | 'steer';
+/** Minimal `Agent` surface the delivery router drives (spec §4, KD-4). */
+export interface AdvisorDeliveryAgent {
+    /** `Agent.id` — equals the session id by construction (KD-4). */
+    readonly id: string;
+    /** Non-waking: queue model-facing context for the next pre-step (spec §6). */
+    inject(message: UserMessage): void;
+    /** Waking: submit steering for the nearest step (spec §6). */
+    steer(message: UserMessage): void;
+}
+/** Logger seam (cordis `ctx.logger('advisor')` satisfies it; console works too). */
+export interface AdvisorDeliveryLogger {
+    debug(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+}
+/** Options for one {@link AdvisorDelivery}. */
+export interface AdvisorDeliveryOptions {
+    /** immuneTurns cooldown length (config, default 3, ≥ 0). */
+    readonly immuneTurns: number;
+    /**
+     * KD-4 registry fallback (`ctx.agents.get(sessionId)`) — resolves agents
+     * published before this plugin loaded, whose `agent/created` was never
+     * observed. Absent → the map alone is authoritative.
+     */
+    readonly lookupAgent?: (sessionId: string) => AdvisorDeliveryAgent | undefined;
+    readonly logger?: AdvisorDeliveryLogger;
+}
+/**
+ * Build the advisor message for one note (spec §6): a user-role message whose
+ * source carries the distinct advisor kind and whose content is self-describing
+ * `[advisor:{severity}] {note}`.
+ *
+ * Bounds (qc3 F-2 / qc2 S-1): the note itself is already capped at
+ * `ADVISOR_NOTE_MAX_CHARS` by extraction; the collapsed-row summary is
+ * additionally bounded via `boundContextSummary` (120 chars — the platform
+ * `CONTEXT_SUMMARY_MAX_CHARS` convention), so the durable log and the
+ * collapsed context row never carry an unbounded account.
+ */
+export declare function buildAdvisorMessage(note: AdviceNote): UserMessage;
+/**
+ * Per-plugin delivery router: severity → channel, the KD-4 agent map, and the
+ * immuneTurns cooldown. Cordis-free, so the routing logic is unit-testable.
+ */
+export declare class AdvisorDelivery {
+    private immuneTurns;
+    private readonly lookupAgent;
+    private readonly logger;
+    /** KD-4 per-session agent map, keyed by `agent.id` (=== session.id). */
+    private readonly agents;
+    /**
+     * immuneTurns latch: remaining stepped primary turns before an interrupting
+     * note may steer again (spec §6). A present entry > 0 means armed; the entry
+     * is removed when the countdown exhausts.
+     */
+    private readonly cooldown;
+    constructor(options: AdvisorDeliveryOptions);
+    /** KD-4: register an agent on `agent/created` (keyed by `agent.id`). */
+    registerAgent(agent: AdvisorDeliveryAgent): void;
+    /** KD-4: drop an agent — and its cooldown with the session — on `agent/disposed`. */
+    unregisterAgent(sessionId: string): void;
+    /**
+     * Update the immuneTurns cooldown length (live config — settings onChange,
+     * plan dsh-advisor-settings-n2 T1). The fence is re-armed with the new
+     * length on the next real steer; the per-session cooldown countdown itself
+     * is untouched, so the delivery semantics (spec §6) never change mid-window.
+     */
+    setImmuneTurns(value: number): void;
+    /**
+     * One completed stepped primary turn (observer `onSteppedTurnEnd`): decrement
+     * the immuneTurns countdown. The latch is removed at zero, so the next
+     * interrupting note steers again. Total — never throws.
+     */
+    onSteppedTurnEnd(sessionId: string): void;
+    /**
+     * KD-5 reset trigger: a compaction / surface rewrite clears the immuneTurns
+     * latch — the session state is being rewritten, so the cooldown's turn-count
+     * basis no longer applies. Total — never throws.
+     */
+    reset(sessionId: string): void;
+    /**
+     * Route one accepted advice note (spec §6, KD-4).
+     *
+     * Resolves the primary agent via the map, falling back to the registry; a
+     * missing agent drops the note with a log (advisory only — never throw,
+     * never stall). nit → inject; concern/blocker → steer, unless the
+     * immuneTurns fence is armed, in which case they downgrade to inject.
+     *
+     * @returns the channel delivered on, or `undefined` when dropped (no agent).
+     */
+    route(sessionId: string, note: AdviceNote): DeliveryChannel | undefined;
+}