dsh-advisor 0.1.0

package/lib/gateway.js

@@ -0,0 +1,214 @@
+/**
+ * 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 { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import { ADVISOR_SETTINGS_NAMESPACE } from './settings.js';
+import { resolveAdvisorConfig } from './config.js';
+/**
+ * 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 class AdvisorConfigGateway extends TypertRemoteService {
+    bridge;
+    /** The live settings service once the optional inject child activates. */
+    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, bridge) {
+        super(ctx, 'advisor');
+        this.bridge = bridge;
+        // The settings service is optional (no settings → entry fallback). The
+        // inject child activates only when a settings service is composed, mirroring
+        // installAdvisorSettings' conditional child; the returned disposer mirrors
+        // its detach path — when the settings service goes away, the write channel
+        // is gone with it, and `set` must fail cleanly (KD-G5) instead of holding a
+        // stale service reference.
+        ctx.inject(['settings'], (sctx) => {
+            this.settings = sctx.settings;
+            return () => {
+                this.settings = undefined;
+            };
+        });
+    }
+    /**
+     * 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() {
+        return { config: this.readConfig() };
+    }
+    /**
+     * 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).
+     */
+    async set(patch) {
+        // Unknown-key rejection + type/bounds validation. The settings service
+        // schema is non-strict (unknown keys merge through), so the explicit
+        // reject happens here, before the write — same strictness as the Loader.
+        resolveAdvisorConfig(patch);
+        // S2: an empty patch is a no-op — return the current composed value
+        // without a pointless settings round-trip.
+        if (Object.keys(patch).length === 0)
+            return { config: this.readConfig() };
+        const settings = this.settings;
+        if (settings === undefined) {
+            throw new Error('advisor: settings service is unavailable — configuration cannot be written');
+        }
+        // Wire normalization (QC tri M-2): JSON cannot carry undefined, so a
+        // null-valued key is a third-party client's way of saying "absent" — the
+        // resolver already treats null as missing on read, but the raw user layer
+        // must not store it. Drop null values before the write (an all-null patch
+        // is a no-op, like the empty patch above).
+        const normalized = Object.fromEntries(Object.entries(patch).filter(([, value]) => value !== null));
+        if (Object.keys(normalized).length === 0)
+            return { config: this.readConfig() };
+        await settings.update(ADVISOR_SETTINGS_NAMESPACE, normalized);
+        return { config: this.readConfig() };
+    }
+    /**
+     * 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.
+     */
+    readConfig() {
+        let config;
+        try {
+            config = resolveAdvisorConfig(this.bridge.source());
+        }
+        catch (error) {
+            let raw;
+            try {
+                raw = this.bridge.source();
+            }
+            catch {
+                // unreadable source — fall back to the schema defaults below
+            }
+            config = {
+                enabled: false,
+                systemPrompt: raw?.systemPrompt ?? '',
+                immuneTurns: raw?.immuneTurns ?? 3,
+                maxDeltaMessages: raw?.maxDeltaMessages ?? 60,
+                disabledReason: error instanceof Error ? error.message : String(error),
+            };
+        }
+        // typertGateway wire boundary: absent keys are omitted, never
+        // present-as-undefined (the result validator rejects undefined values).
+        const wire = {
+            enabled: config.enabled,
+            systemPrompt: config.systemPrompt,
+            immuneTurns: config.immuneTurns,
+            maxDeltaMessages: config.maxDeltaMessages,
+        };
+        if (config.provider !== undefined)
+            wire.provider = config.provider;
+        if (config.model !== undefined)
+            wire.model = config.model;
+        if (config.disabledReason !== undefined)
+            wire.disabledReason = config.disabledReason;
+        return wire;
+    }
+}
+/**
+ * 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 function advisorTypertContribution() {
+    return {
+        package: 'dsh-advisor',
+        face: 'host',
+        schemas: [],
+        model: { services: [], events: [], objects: [] },
+        invocations: [
+            {
+                id: 'dsh-advisor#advisor/get',
+                service: 'advisor',
+                namespace: 'advisor',
+                method: 'get',
+                invocation: { kind: 'direct' },
+                parameters: [],
+                result: { mode: 'src-json' },
+            },
+            {
+                id: 'dsh-advisor#advisor/set',
+                service: 'advisor',
+                namespace: 'advisor',
+                method: 'set',
+                invocation: { kind: 'direct' },
+                parameters: [
+                    { name: 'patch', wire: 'patch', source: 'json', codec: { mode: 'src-json' } },
+                ],
+                result: { mode: 'src-json' },
+            },
+        ],
+    };
+}
+//# sourceMappingURL=gateway.js.map

package/lib/gateway.js.map

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

package/lib/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * dsh advisor plugin — a per-session reviewer model (port of the omp
+ * "advisor" subsystem). Observes the primary transcript, reviews each stepped
+ * turn with an explicitly configured model, and injects severity-ranked
+ * advice (nit/concern/blocker) without polluting or recursively reviewing
+ * itself.
+ *
+ * T1 scaffold: declares the Cordis plugin entry (`name`/`inject`/`apply`).
+ * T2: config contract — the Loader schema (`Config`) plus the explicit
+ * provider/model gate via `resolveAdvisorConfig` (spec §5 / S4).
+ * T3: session observation — subscribe `session/event`, detect stepped
+ * `turn/end` (reason.kind ∈ {completed, 'max-tokens', error}, spec §4), drive
+ * a per-session bounded delta renderer, and dispose per-session state on
+ * `session/disposed` / `agent/disposed` (KD-5).
+ * T4: the per-session advisor runtime — queue each rendered delta, drain
+ * asynchronously via `ctx.llm.stream` (system prompt + delta, `purpose` left
+ * unset, KD-5), extract `{note, severity}` (KD-2), and apply the failure
+ * policy (retry-light → drop, 3-drop backlog flush, quota pause, permanent
+ * halt — never park the primary). The emission guard (T5) gates extracted
+ * notes before delivery; the delivery router (T6) routes accepted notes into
+ * the primary agent (nit → inject, concern/blocker → steer, immuneTurns
+ * cooldown, KD-4 agent map). T7: `/advisor` toggle/on/off/status commands
+ * (registered through the conditional `ctx.inject(['commands'], ...)` child)
+ * drive a per-session override consulted by the runtime gate — the commands
+ * start/stop per-session runtimes without touching the persisted config.
+ * Settings (plan dsh-advisor-settings-n2): the plugin-row config is the
+ * composition base of the `advisor` settings namespace (`src/settings.ts`),
+ * read live through the bridge source; committed settings edits re-apply
+ * derived state (immuneTurns / maxDeltaMessages / per-session runtimes)
+ * without a restart.
+ * Config gateway (plan dsh-advisor-settings-gateway-n5): `apply` also
+ * registers the host-side `AdvisorConfigGateway` (`src/gateway.ts`) — the
+ * `/api/advisor/get` + `/api/advisor/set` endpoints (explicit
+ * `ctx.typert.register` contribution — the host typertGateway claims
+ * `ctx.typert.local` first, so link-plugin module identity never matters)
+ * that make the Settings card truly readable/writable from the web client.
+ *
+ * @module dsh-advisor
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { AdvisorConfig } from './config.js';
+export declare const name = "dsh-advisor";
+/** Services the advisor consumes; the row loads once all are available. */
+export declare const inject: string[];
+/** Loader schema (schemastery, strict) — validated by the cordis Loader. */
+export { Config } from './config.js';
+export type { AdvisorConfig, ResolvedAdvisorConfig } from './config.js';
+export declare function apply(ctx: Context, config: AdvisorConfig): void;