dsh-advisor 0.1.0

package/lib/delivery.js

@@ -0,0 +1,169 @@
+/**
+ * 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 { boundContextSummary, createUserMessage } from '@deepseek-ai/dsh-llm';
+import { ADVISOR_SOURCE_KIND } from './kinds.js';
+/**
+ * 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 function buildAdvisorMessage(note) {
+    // One formatter for content and summary: the summary is derived from the
+    // same string as the content via a fixed slice of the `[advisor:` marker
+    // (`[` + everything after it), so the severity formatting can never drift
+    // between the two — and note text mentioning "advisor:" cannot affect it.
+    const text = `[advisor:${note.severity}] ${note.note}`;
+    const summary = `[${text.slice('[advisor:'.length)}`;
+    return createUserMessage({
+        content: [{ type: 'text', text }],
+        // n4 (user direction): declare the notice form + a collapsed-row summary so
+        // the web shell's ContextInjectionRow shows "… · advisor · [nit] <note>"
+        // instead of a bare producer label. The severity tag is part of the summary
+        // text; per-severity COLOR needs the shell UI (out of plugin reach).
+        source: {
+            kind: ADVISOR_SOURCE_KIND,
+            form: 'notice',
+            summary: boundContextSummary(summary),
+        },
+    });
+}
+/** True when a note interrupts the primary (concern/blocker — spec §6). */
+function isInterrupting(severity) {
+    return severity === 'concern' || severity === 'blocker';
+}
+/**
+ * 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 class AdvisorDelivery {
+    immuneTurns;
+    lookupAgent;
+    logger;
+    /** KD-4 per-session agent map, keyed by `agent.id` (=== session.id). */
+    agents = new Map();
+    /**
+     * 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.
+     */
+    cooldown = new Map();
+    constructor(options) {
+        this.immuneTurns = options.immuneTurns;
+        this.lookupAgent = options.lookupAgent ?? (() => undefined);
+        this.logger = options.logger ?? console;
+    }
+    /** KD-4: register an agent on `agent/created` (keyed by `agent.id`). */
+    registerAgent(agent) {
+        this.agents.set(agent.id, agent);
+    }
+    /** KD-4: drop an agent — and its cooldown with the session — on `agent/disposed`. */
+    unregisterAgent(sessionId) {
+        this.agents.delete(sessionId);
+        this.cooldown.delete(sessionId);
+    }
+    /**
+     * 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) {
+        this.immuneTurns = value;
+    }
+    /**
+     * 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) {
+        const remaining = this.cooldown.get(sessionId);
+        if (remaining === undefined || remaining <= 0)
+            return;
+        if (remaining <= 1)
+            this.cooldown.delete(sessionId);
+        else
+            this.cooldown.set(sessionId, remaining - 1);
+    }
+    /**
+     * 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) {
+        this.cooldown.delete(sessionId);
+    }
+    /**
+     * 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, note) {
+        const agent = this.agents.get(sessionId) ?? this.lookupAgent(sessionId);
+        if (agent === undefined) {
+            this.logger.warn('advisor: note dropped — no agent for session', {
+                sessionId,
+                severity: note.severity,
+            });
+            return undefined;
+        }
+        const message = buildAdvisorMessage(note);
+        const cooldown = this.cooldown.get(sessionId) ?? 0;
+        if (isInterrupting(note.severity) && cooldown <= 0) {
+            // A real steer delivery arms the fence (spec §6). Armed before the call:
+            // a failed steer delivery still counts as an attempted interrupt, keeping
+            // a throwing agent out of the noise loop — and a downgraded or dropped
+            // note never reaches this branch, so the fence never arms on one.
+            if (this.immuneTurns > 0)
+                this.cooldown.set(sessionId, this.immuneTurns);
+            agent.steer(message);
+            return 'steer';
+        }
+        agent.inject(message);
+        return 'inject';
+    }
+}
+//# sourceMappingURL=delivery.js.map

package/lib/delivery.js.map

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

package/lib/emission-guard.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Emission guard (spec §4 mapping row — omp `advisor/emission-guard.ts`
+ * ported 1:1: normalize / dedupe / content-free suppression / one-per-update
+ * / escalation; §6 one-note-per-update; §8.2 KD-2 "guard also drops extras").
+ *
+ * The guard sits between the T4 runtime (note extraction) and delivery (T6):
+ * {@link EmissionGuard.accept} returns `true` to pass a note through to the
+ * delivery callback and `false` to suppress it **silently** — the caller can
+ * never tell an accepted from a suppressed note, and no error is thrown.
+ *
+ * Rules (in order):
+ * 1. **Normalization** — lowercase, NFKC, every run of non-alphanumeric
+ *    characters collapsed to one space, trimmed. `"Stop."`, `*stop*` and
+ *    `"  STOP  "` all key to `stop`.
+ * 2. **Content-free phrase filter** — short phrases with no concrete reason
+ *    (`stop`, `done`, `complete`, `no issue continue`, `lgtm`,
+ *    `nothing to add`, plus documented equivalents — see
+ *    {@link CONTENT_FREE_PHRASES}) are suppressed. Matching is exact on the
+ *    normalized text, so a note that merely contains a phrase survives.
+ * 3. **Per-update rate limit** — at most one note per advisor model cycle is
+ *    accepted. The runtime signals each new cycle with {@link
+ *    EmissionGuard.beginUpdate} (once per processed delta), resetting the
+ *    latch. A guard whose `beginUpdate` is never called still accepts the
+ *    first note of the session (fail-safe toward fewer notes).
+ * 4. **Normalized dedupe with escalation** — a normalized note already
+ *    accepted this session is dropped, with a FIFO-bounded history
+ *    (default 4096, omp parity; {@link DEFAULT_MAX_HISTORY}); the oldest
+ *    entry is evicted past the bound. A repeat at equal or lower severity is
+ *    suppressed, but a real escalation (nit → concern → blocker) of the same
+ *    note is accepted and updates the remembered severity.
+ *
+ * Guard state clears per session: a new runtime (and therefore a new guard)
+ * is created per session and discarded on dispose; {@link
+ * EmissionGuard.reset} is exposed for the KD-5 session-reset triggers
+ * (`compact/*`, `user/message` replace) when the reset wiring lands.
+ *
+ * @module dsh-advisor/emission-guard
+ */
+import type { AdviceNote } from './advisor-runtime.js';
+/**
+ * FIFO dedupe history bound (omp parity: 4096). Deliberately capped — a
+ * session that accepts more than this many distinct notes keeps only the most
+ * recent window, so an old note may legitimately be advised again.
+ */
+export declare const DEFAULT_MAX_HISTORY = 4096;
+/**
+ * Content-free phrases suppressed at delivery. The omp base list is
+ * `stop` / `done` / `complete` / `no issue continue` / `lgtm` /
+ * `nothing to add` (this is also the frame the KD-2 prompt asks the model to
+ * emit when there is nothing to advise). Additions beyond the omp base —
+ * short acknowledgements with no concrete reason — are listed after them.
+ */
+export declare const CONTENT_FREE_PHRASES: ReadonlySet<string>;
+/** Options for one {@link EmissionGuard}. */
+export interface EmissionGuardOptions {
+    /**
+     * FIFO dedupe history bound (normalized notes remembered per session);
+     * default {@link DEFAULT_MAX_HISTORY} (4096, omp parity).
+     */
+    readonly maxHistory?: number;
+}
+/**
+ * Per-session emission guard. One instance per advisor runtime; created via
+ * {@link createEmissionGuard} (or the constructor directly).
+ */
+export declare class EmissionGuard {
+    private readonly maxHistory;
+    /**
+     * normalized note → last accepted severity. Map insertion order is the
+     * FIFO order (updating an existing key does not move it), so the oldest
+     * entry is simply the first key.
+     */
+    private readonly history;
+    /** One-note-per-update latch; reset by {@link beginUpdate} and {@link reset}. */
+    private acceptedThisUpdate;
+    constructor(options?: EmissionGuardOptions);
+    /**
+     * Mark the start of one advisor model cycle (one processed transcript
+     * delta). The per-update rate limit latch resets here, so each cycle may
+     * deliver one note again. The runtime calls this once per delta it drains.
+     */
+    beginUpdate(): void;
+    /**
+     * Accept or suppress one extracted note.
+     *
+     * @returns `true` = pass through to delivery (T6); `false` = suppressed
+     *   (normalized-empty, content-free, a repeat at equal/lower severity, or
+     *   the second note of the same update). Never throws.
+     */
+    accept(note: AdviceNote): boolean;
+    /**
+     * Clear all session state (dedupe history + per-update latch). Exposed for
+     * the KD-5 session-reset triggers; a new session gets a fresh guard anyway
+     * (per-runtime lifetime).
+     */
+    reset(): void;
+}
+/** Factory (plan T5: "Export the guard class + a factory"). */
+export declare function createEmissionGuard(options?: EmissionGuardOptions): EmissionGuard;

package/lib/emission-guard.js

@@ -0,0 +1,155 @@
+/**
+ * Emission guard (spec §4 mapping row — omp `advisor/emission-guard.ts`
+ * ported 1:1: normalize / dedupe / content-free suppression / one-per-update
+ * / escalation; §6 one-note-per-update; §8.2 KD-2 "guard also drops extras").
+ *
+ * The guard sits between the T4 runtime (note extraction) and delivery (T6):
+ * {@link EmissionGuard.accept} returns `true` to pass a note through to the
+ * delivery callback and `false` to suppress it **silently** — the caller can
+ * never tell an accepted from a suppressed note, and no error is thrown.
+ *
+ * Rules (in order):
+ * 1. **Normalization** — lowercase, NFKC, every run of non-alphanumeric
+ *    characters collapsed to one space, trimmed. `"Stop."`, `*stop*` and
+ *    `"  STOP  "` all key to `stop`.
+ * 2. **Content-free phrase filter** — short phrases with no concrete reason
+ *    (`stop`, `done`, `complete`, `no issue continue`, `lgtm`,
+ *    `nothing to add`, plus documented equivalents — see
+ *    {@link CONTENT_FREE_PHRASES}) are suppressed. Matching is exact on the
+ *    normalized text, so a note that merely contains a phrase survives.
+ * 3. **Per-update rate limit** — at most one note per advisor model cycle is
+ *    accepted. The runtime signals each new cycle with {@link
+ *    EmissionGuard.beginUpdate} (once per processed delta), resetting the
+ *    latch. A guard whose `beginUpdate` is never called still accepts the
+ *    first note of the session (fail-safe toward fewer notes).
+ * 4. **Normalized dedupe with escalation** — a normalized note already
+ *    accepted this session is dropped, with a FIFO-bounded history
+ *    (default 4096, omp parity; {@link DEFAULT_MAX_HISTORY}); the oldest
+ *    entry is evicted past the bound. A repeat at equal or lower severity is
+ *    suppressed, but a real escalation (nit → concern → blocker) of the same
+ *    note is accepted and updates the remembered severity.
+ *
+ * Guard state clears per session: a new runtime (and therefore a new guard)
+ * is created per session and discarded on dispose; {@link
+ * EmissionGuard.reset} is exposed for the KD-5 session-reset triggers
+ * (`compact/*`, `user/message` replace) when the reset wiring lands.
+ *
+ * @module dsh-advisor/emission-guard
+ */
+/**
+ * FIFO dedupe history bound (omp parity: 4096). Deliberately capped — a
+ * session that accepts more than this many distinct notes keeps only the most
+ * recent window, so an old note may legitimately be advised again.
+ */
+export const DEFAULT_MAX_HISTORY = 4096;
+/**
+ * Content-free phrases suppressed at delivery. The omp base list is
+ * `stop` / `done` / `complete` / `no issue continue` / `lgtm` /
+ * `nothing to add` (this is also the frame the KD-2 prompt asks the model to
+ * emit when there is nothing to advise). Additions beyond the omp base —
+ * short acknowledgements with no concrete reason — are listed after them.
+ */
+export const CONTENT_FREE_PHRASES = new Set([
+    // omp base list
+    'stop',
+    'done',
+    'complete',
+    'no issue continue',
+    'lgtm',
+    'nothing to add',
+    // additions (documented in the task-5 report): content-free equivalents
+    'ok',
+    'okay',
+    'good',
+    'fine',
+    'looks good',
+    'looks fine',
+    'all good',
+    'all clear',
+    'no issue',
+    'no issues',
+    'nothing',
+    'looks good to me',
+]);
+/** Severity order for the escalation check (spec §6): nit < concern < blocker. */
+const SEVERITY_RANK = { nit: 0, concern: 1, blocker: 2 };
+/**
+ * Normalize one note to its identity key (spec §4): lowercase, NFKC, every
+ * run of non-alphanumeric characters collapsed to one space, trimmed.
+ */
+function normalizeNote(text) {
+    return text
+        .normalize('NFKC')
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}]+/gu, ' ')
+        .trim();
+}
+/**
+ * Per-session emission guard. One instance per advisor runtime; created via
+ * {@link createEmissionGuard} (or the constructor directly).
+ */
+export class EmissionGuard {
+    maxHistory;
+    /**
+     * normalized note → last accepted severity. Map insertion order is the
+     * FIFO order (updating an existing key does not move it), so the oldest
+     * entry is simply the first key.
+     */
+    history = new Map();
+    /** One-note-per-update latch; reset by {@link beginUpdate} and {@link reset}. */
+    acceptedThisUpdate = false;
+    constructor(options) {
+        this.maxHistory = options?.maxHistory ?? DEFAULT_MAX_HISTORY;
+    }
+    /**
+     * Mark the start of one advisor model cycle (one processed transcript
+     * delta). The per-update rate limit latch resets here, so each cycle may
+     * deliver one note again. The runtime calls this once per delta it drains.
+     */
+    beginUpdate() {
+        this.acceptedThisUpdate = false;
+    }
+    /**
+     * Accept or suppress one extracted note.
+     *
+     * @returns `true` = pass through to delivery (T6); `false` = suppressed
+     *   (normalized-empty, content-free, a repeat at equal/lower severity, or
+     *   the second note of the same update). Never throws.
+     */
+    accept(note) {
+        const key = normalizeNote(note.note);
+        if (key.length === 0)
+            return false; // punctuation-only / whitespace-only
+        if (CONTENT_FREE_PHRASES.has(key))
+            return false;
+        if (this.acceptedThisUpdate)
+            return false; // one note per update
+        const prior = this.history.get(key);
+        if (prior !== undefined && SEVERITY_RANK[note.severity] <= SEVERITY_RANK[prior]) {
+            return false; // equal/lower-severity repeat suppressed
+        }
+        this.history.set(key, note.severity); // new note, or an accepted escalation
+        if (this.history.size > this.maxHistory) {
+            // FIFO eviction: drop the oldest accepted note past the bound.
+            const oldest = this.history.keys().next().value;
+            if (oldest !== undefined)
+                this.history.delete(oldest);
+        }
+        this.acceptedThisUpdate = true;
+        return true;
+    }
+    /**
+     * Clear all session state (dedupe history + per-update latch). Exposed for
+     * the KD-5 session-reset triggers; a new session gets a fresh guard anyway
+     * (per-runtime lifetime).
+     */
+    reset() {
+        this.history.clear();
+        this.acceptedThisUpdate = false;
+    }
+}
+/** Factory (plan T5: "Export the guard class + a factory"). */
+export function createEmissionGuard(options) {
+    return new EmissionGuard(options);
+}
+//# sourceMappingURL=emission-guard.js.map

package/lib/emission-guard.js.map

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

package/lib/gateway.d.ts

@@ -0,0 +1,116 @@
+/**
+ * T1 (plan dsh-advisor-settings-gateway-n5) — host-side `advisor` config
+ * gateway: the `/api/advisor/get` + `/api/advisor/set` Remote endpoints.
+ *
+ * Transport: the typertGateway `/api` interceptor is the single host-wide RPC
+ * slot (a plugin must NOT `connection.rpc.intercept('/api')` again — it would
+ * throw). Instead this service declares a typertGateway binding (via the
+ * `TypertRemoteService` base) plus `@Remote` method markers; the gateway's SRC
+ * discovery (`claimsEndpoint` — `ctx.reflect.props` + `remoteMethods`) claims
+ * `/api/advisor/get` and `/api/advisor/set`, and the payload contract is
+ * exactly one plain-object `args` field whose keys are the method parameter
+ * names (`get()` → `{ args: {} }`; `set(patch)` → `{ args: { patch } }`).
+ *
+ * Data: `get` reads the `AdvisorSettingsBridge` source — the same live
+ * composed config the runtime reads (schema defaults → plugin-row base →
+ * settings user layer), resolved through the `resolveAdvisorConfig` hard gate
+ * (the SSOT for enabled-without-pair disabled-with-reason). `set` validates
+ * the patch against the `Config` schema first (unknown-key rejection
+ * unchanged — the settings service itself is non-strict and would accept the
+ * unknown key), then writes the USER layer in-process via
+ * `ctx.settings.update` (no exposed-namespace gate on the in-process write —
+ * the wire-level `exposedNamespaces()` check only guards the apiproxy path),
+ * and returns the new composed value.
+ *
+ * The settings service is OPTIONAL (no settings service → the bridge source
+ * stays the entry, `get` still works; `set` fails with a clear error — KD-G5
+ * fallback). The gateway captures the service through a conditional
+ * `ctx.inject(['settings'], ...)` child (the same activation pattern as
+ * `installAdvisorSettings`), because `ctx.settings` is only resolvable from a
+ * fiber that declares it.
+ *
+ * The returned config is normalized to the typertGateway JSON wire boundary:
+ * absent keys (provider/model/disabledReason) are OMITTED, never
+ * present-as-undefined (the gateway's result validation rejects undefined
+ * values).
+ *
+ * @module dsh-advisor/gateway
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { TypertContribution } from '@deepseek-ai/dsh-typert-registry';
+import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import type { AdvisorSettingsBridge } from './settings.js';
+import type { AdvisorConfig, ResolvedAdvisorConfig } from './config.js';
+/** Patch shape accepted by `advisor.set` — any subset of the config keys. */
+export type AdvisorConfigPatch = Partial<AdvisorConfig>;
+/**
+ * The host-side `advisor` config gateway (`/api/advisor/get` +
+ * `/api/advisor/set`). Registered as the cordis service key `'advisor'`
+ * (namespace defaults to the service key). The `TypertRemoteService` base is
+ * kept ONLY for its `typertRemote` binding — the typertGateway's dispatch
+ * `validateBinding` requires the visible binding on the live service (a pure
+ * instance property, no module-private state). Endpoints are registered
+ * EXPLICITLY through `ctx.typert.register(advisorTypertContribution())`
+ * (see `apply` in `src/index.ts`) instead of the `@Remote` SRC markers:
+ * SRC discovery reads `remoteMethods()` — a module-private WeakMap in
+ * `@deepseek-ai/dsh-typert-protocol` — so a locally-linked plugin whose
+ * peers resolve outside the host installation never shares that table with
+ * the host typertGateway (zero claimed endpoints, `/api/advisor/*` 404).
+ * The explicit `TypertRegistry.register` path writes the invocation
+ * descriptors into `ctx.typert.local`, which `claimsEndpoint` checks FIRST,
+ * so claim + dispatch work regardless of module identity.
+ */
+export declare class AdvisorConfigGateway extends TypertRemoteService {
+    private readonly bridge;
+    /** The live settings service once the optional inject child activates. */
+    private settings;
+    /**
+     * @param ctx - owning context (the plugin fiber's ctx inside `apply`).
+     * @param bridge - the same `AdvisorSettingsBridge` the runtime reads, so
+     *   get/set always operate on the live composed config.
+     */
+    constructor(ctx: Context, bridge: AdvisorSettingsBridge);
+    /**
+     * Read the current composed config (schema defaults → entry base → settings
+     * user layer) through the hard gate.
+     * @returns the resolved config (incl. disabledReason when the gate blocks).
+     */
+    get(): {
+        config: ResolvedAdvisorConfig;
+    };
+    /**
+     * Validate a config patch and write it to the settings USER layer (live —
+     * the runtime re-applies through the bridge `onChange`; no restart needed).
+     * @param patch - any subset of the config keys; unknown keys are rejected
+     *   by the `Config` schema before anything is written.
+     * @returns the NEW composed config after the write.
+     * @throws when the patch fails `Config` validation, or when no settings
+     *   service is composed (KD-G5: the write channel is unavailable).
+     */
+    set(patch: AdvisorConfigPatch): Promise<{
+        config: ResolvedAdvisorConfig;
+    }>;
+    /**
+     * Resolve the live composed config through the hard gate. Containment
+     * (qc2 W-1): a user layer the resolver rejects (e.g. an unknown key that
+     * survived the non-strict settings schema) resolves to disabled-with-reason
+     * carrying the message — the gateway never fails the RPC on a bad user
+     * layer, and gate semantics hold (no model call can start). S1: when the
+     * raw source is still readable, the fallback seeds its scalar latches
+     * (systemPrompt / immuneTurns / maxDeltaMessages) instead of hardcoded
+     * defaults, so an invalid layer only drops the offending keys.
+     */
+    private readConfig;
+}
+/**
+ * The explicit typert contribution for the `advisor` gateway endpoints —
+ * registered via `ctx.typert.register(...)` (see `apply` in `src/index.ts`).
+ * The descriptors mirror exactly what the former SRC discovery derived from
+ * the `@Remote` markers (`src:advisor#<endpoint>` identity shape, direct
+ * receiver, JSON wire params with `src-json` codec), so the host
+ * typertGateway claim + dispatch behavior is byte-for-byte the same — the
+ * only difference is the registration does not depend on the module-private
+ * `remoteMethods` marker table, which a locally-linked plugin can never
+ * share with the host installation.
+ */
+export declare function advisorTypertContribution(): TypertContribution;