dsh-realtime 0.2.2 → 0.2.3

package/lib/settings.js

@@ -0,0 +1,338 @@
+/**
+ * The settings surface: what a running plugin's settings are, and which of them a change can reach.
+ *
+ * `docs/control-plane-fields.md` is the design gate, and it classifies every field into one of three
+ * classes: **live** (read at the moment of use, so a change takes effect then), **session-bound** (it
+ * travelled in the provider's `session.start`, so only a new session can carry a new value) and
+ * **restart-bound** (claimed once against the web server's registry or enforced by the socket). This
+ * module is that classification in code, because a classification that lives only in prose cannot
+ * refuse anything: the design rule is *an affordance the protocol cannot honour is worse than no
+ * affordance*, and the only way to honour it is for the surface to know a setting's class and answer a
+ * change with the reason instead of applying it.
+ *
+ * Four properties are load-bearing, and each is a test rather than a promise:
+ *
+ * - **The value is read at the moment of use, from the plugin that owns it.** A setting holds a
+ *   `get()`, and the consumer calls it where it acts — not a copy taken at apply time. That is what
+ *   makes the change take effect on the next use, and it is why a stale copy is impossible rather than
+ *   merely discouraged.
+ * - **A change is refused with a reason on the same channel it arrived on.** Unknown key, a class that
+ *   cannot honour a change, a value that does not parse, a setter that rejects one — four different
+ *   reasons, because they call for four different responses and collapsing them is the failure this
+ *   project has already paid for once (see `realtime-responder/src/turn.ts`).
+ * - **A secret setting is write-only.** `redactSecrets` holds values that must never be spoken,
+ *   journalled or handed to a page; a surface that echoed them back through `status` or a `set`
+ *   outcome would breach `design.md` invariant 3 one layer out. A setting declared `secret` reports no
+ *   value at all.
+ * - **Registration is a contract, checked at registration.** The declared `kind` must match what
+ *   `get()` actually returns, and only a `live` setting may have a setter — so a setting that would
+ *   render the wrong control, or claim a change it cannot apply, fails where it is declared rather
+ *   than in a user's session.
+ *
+ * @module dsh-realtime/settings
+ */
+import { REALTIME_ERROR_CODES, RealtimeError } from './error.js';
+import { redact } from './redact.js';
+/** The classes a setting may declare, for validating a caller that is not TypeScript. */
+const SCOPES = Object.freeze(['live', 'session', 'restart']);
+/** The kinds a setting may declare, for the same reason. */
+const KINDS = Object.freeze(['string', 'number', 'boolean', 'string-list']);
+/** Field names are dotted onto an owner, so they must be a single identifier-shaped word. */
+const FIELD_SHAPE = /^[A-Za-z][A-Za-z0-9]*$/;
+/** Longest reason carried out of a refusal, so an owner's error cannot flood a status surface. */
+const MAX_REASON_CHARS = 200;
+/**
+ * The registry of settings a running plugin can be steered by.
+ *
+ * Owned by the seam, like the journal, and for the same reason: it is an object every plugin in the
+ * bundle already holds, and a surface split across three of them would leave a reader — or a control
+ * plane — correlating three partial answers to one question.
+ *
+ * Not a service and not tied to a Cordis context: a plain object, so it can be constructed in a test
+ * and asked things without a harness. Registration returns a disposer rather than taking ownership of
+ * one, so the *contributing* fiber is what releases a plugin's settings — call it inside
+ * `ctx.effect`, exactly as a plugin registers a listener.
+ */
+export class RealtimeSettings {
+    journal;
+    settings = new Map();
+    /**
+     * @param journal - the seam's journal. A successful change is recorded there as `config.changed`;
+     *   see {@link apply} for what is deliberately not recorded.
+     */
+    constructor(journal) {
+        this.journal = journal;
+    }
+    /**
+     * Declare the settings one plugin owns, all-or-nothing.
+     *
+     * A malformed spec fails here rather than at the moment somebody tries to change it: the point of a
+     * declared kind is that a control and a parser agree with the plugin's own type, and a setting whose
+     * declaration does not match what it returns has neither.
+     * @param owner - the plugin's name, as it appears in Loader diagnostics. Becomes the key's prefix.
+     * @param specs - every setting this plugin declares.
+     * @returns the disposer that releases them. Call it inside the contributing fiber's effect.
+     * @throws RealtimeError `INVALID_SETTING` for a malformed owner, field, kind, scope or declaration.
+     * @throws RealtimeError `DUPLICATE_SETTING` for a key another registration already holds.
+     */
+    register(owner, specs) {
+        if (typeof owner !== 'string' || owner.length === 0) {
+            throw new RealtimeError('a settings owner must be a non-empty string', REALTIME_ERROR_CODES.INVALID_SETTING);
+        }
+        const prepared = [];
+        const claimed = new Set();
+        for (const spec of specs) {
+            const key = `${owner}.${String(spec.field)}`;
+            if (typeof spec.field !== 'string' || !FIELD_SHAPE.test(spec.field)) {
+                throw new RealtimeError(`a setting's field must be identifier-shaped, received "${String(spec.field)}"`, REALTIME_ERROR_CODES.INVALID_SETTING);
+            }
+            if (claimed.has(key) || this.settings.has(key)) {
+                throw new RealtimeError(`a setting named "${key}" is already registered`, REALTIME_ERROR_CODES.DUPLICATE_SETTING);
+            }
+            if (!SCOPES.includes(spec.scope)) {
+                throw new RealtimeError(`"${key}" declared an unknown scope "${String(spec.scope)}"`, REALTIME_ERROR_CODES.INVALID_SETTING);
+            }
+            if (!KINDS.includes(spec.kind)) {
+                throw new RealtimeError(`"${key}" declared an unknown kind "${String(spec.kind)}"`, REALTIME_ERROR_CODES.INVALID_SETTING);
+            }
+            // A list of candidates is a claim about the values a *picker* offers, and a picker only exists for a
+            // string: numbers, booleans and lists each have one representation a control does not need help with.
+            if (spec.choices !== undefined && spec.kind !== 'string') {
+                throw new RealtimeError(`"${key}" declares choices and the kind "${spec.kind}" — candidates are for a string setting`, REALTIME_ERROR_CODES.INVALID_SETTING);
+            }
+            // A change can only reach a `live` field, and only a `live` field has anything to apply it. Two
+            // one-sided declarations, and both are refusals rather than warnings for the same reason: the
+            // first would offer a control that silently does nothing, the second would answer a change by
+            // doing nothing at all.
+            if (spec.scope === 'live' && spec.set === undefined) {
+                throw new RealtimeError(`"${key}" is live and must declare how a change is applied`, REALTIME_ERROR_CODES.INVALID_SETTING);
+            }
+            if (spec.scope !== 'live' && spec.set !== undefined) {
+                throw new RealtimeError(`"${key}" is ${spec.scope}-bound and cannot declare a setter`, REALTIME_ERROR_CODES.INVALID_SETTING);
+            }
+            // Read once, at registration: the declared kind is a claim about what this setting *is*, and a
+            // claim that does not hold here produces a control that shows the wrong thing for ever.
+            const now = spec.get();
+            if (!matchesKind(spec.kind, now)) {
+                throw new RealtimeError(`"${key}" declares the kind "${spec.kind}" and returns ${describeValue(now)}`, REALTIME_ERROR_CODES.INVALID_SETTING);
+            }
+            claimed.add(key);
+            prepared.push({
+                key,
+                owner,
+                field: spec.field,
+                kind: spec.kind,
+                scope: spec.scope,
+                ...spec.describe === undefined ? {} : { describe: spec.describe },
+                secret: spec.secret === true,
+                ...spec.choices === undefined ? {} : { choices: spec.choices },
+                get: spec.get,
+                ...spec.set === undefined ? {} : { set: spec.set },
+            });
+        }
+        for (const registered of prepared)
+            this.settings.set(registered.key, registered);
+        return () => {
+            for (const registered of prepared)
+                this.settings.delete(registered.key);
+        };
+    }
+    /**
+     * Every registered setting, in the order its plugins registered them.
+     *
+     * Registration order is composition order, which is what a status surface wants to show; sorting
+     * would be deterministic and would also hide which plugin arrived first, which is exactly the thing
+     * a reader is trying to work out when a row waits.
+     * @returns detached descriptions, each with the value read now.
+     */
+    list() {
+        return [...this.settings.values()].map(registered => this.describe(registered));
+    }
+    /**
+     * Describe one setting.
+     * @param key - `<owner>.<field>`.
+     * @returns the description, or `undefined` when nothing is registered under that key.
+     */
+    get(key) {
+        const registered = this.settings.get(key);
+        return registered === undefined ? undefined : this.describe(registered);
+    }
+    /**
+     * Apply a change addressed as text, and say what happened.
+     *
+     * The one operation a control plane needs: it parses by the declared kind, refuses anything the
+     * setting's class cannot honour, hands the value to the owner's own setter and reports the value the
+     * owner now holds. A change that landed is journalled as `config.changed` **with its key and not its
+     * value** — the value of a secret setting is precisely the text that must not be retained, and a
+     * surface that journalled "the values it was given" would write them into the one record built to be
+     * read and pasted.
+     * @param key - the setting's `<owner>.<field>` key, exactly as {@link RealtimeSettingInfo.key} reports it.
+     * @param text - the value as a text frame carries it.
+     * @returns whether the change was applied, and either the value now or the reason it was refused.
+     */
+    apply(key, text) {
+        const registered = this.settings.get(key);
+        // Checked before the value is looked at: whether a setting can be changed at all is a property of
+        // the setting, and answering a malformed value first would tell a caller to fix a typo in a number
+        // where the real answer is that this field needs a restart.
+        if (registered === undefined) {
+            return this.refuse(key, 'UNKNOWN_SETTING', `no setting named "${key}" is registered`);
+        }
+        if (registered.scope !== 'live')
+            return this.refuse(key, 'FROZEN_SETTING', frozenReason(registered));
+        const parsed = parseValue(registered.kind, text);
+        if (!parsed.ok) {
+            return this.refuse(key, 'INVALID_SETTING', `"${key}" expects a ${registered.kind}, received ${describeText(text)}`);
+        }
+        try {
+            registered.set?.(parsed.value);
+        }
+        catch (error) {
+            // The owner's own rules — a non-empty session id, a positive budget — are the ones a caller can
+            // act on, so its message is carried rather than replaced by a generic one.
+            return this.refuse(key, 'INVALID_SETTING', `"${key}" refused the change: ${reasonOf(error)}`);
+        }
+        this.journal.record('config.changed', { key });
+        return { ok: true, key, value: registered.secret ? undefined : registered.get() };
+    }
+    /**
+     * Build one detached description, reading the value now.
+     * @param registered - the stored setting.
+     * @returns the description, with no value at all when the setting is secret.
+     */
+    describe(registered) {
+        return {
+            key: registered.key,
+            owner: registered.owner,
+            field: registered.field,
+            kind: registered.kind,
+            scope: registered.scope,
+            ...registered.describe === undefined ? {} : { describe: registered.describe },
+            ...registered.choices === undefined ? {} : { choices: registered.choices() },
+            value: registered.secret ? undefined : registered.get(),
+        };
+    }
+    /**
+     * Build one refusal, redacted and bounded.
+     * @param key - the setting the change addressed.
+     * @param code - which class of refusal this is.
+     * @param reason - the line to relay.
+     * @returns the refusal to hand back.
+     */
+    refuse(key, code, reason) {
+        // The reason may quote the value the caller sent, and a caller is not always entitled to read it:
+        // the shape arm runs over it, and the bound stops an owner's error message becoming the payload.
+        return { ok: false, key, code, reason: redact(reason).slice(0, MAX_REASON_CHARS) };
+    }
+}
+/**
+ * Why a setting of this class cannot take a change, in the words the person making the change needs.
+ *
+ * The two classes are different instructions — one reconnect, one restart — and naming which is the
+ * whole value of refusing rather than ignoring.
+ * @param registered - the frozen setting.
+ * @returns the reason.
+ */
+function frozenReason(registered) {
+    return registered.scope === 'session'
+        ? `"${registered.key}" is fixed when the voice session opens — reconnect to apply a new value`
+        : `"${registered.key}" is claimed when the plugin loads — restart to change it`;
+}
+/**
+ * Does this value match the kind the setting declared?
+ *
+ * `get()` is the plugin's own, so the check costs nothing at runtime and catches the failure that
+ * matters: a declaration that would render a control for one kind over a value of another.
+ * @param kind - the declared kind.
+ * @param value - what `get()` returned.
+ * @returns whether they agree.
+ */
+function matchesKind(kind, value) {
+    switch (kind) {
+        case 'string': return typeof value === 'string';
+        case 'number': return typeof value === 'number' && Number.isFinite(value);
+        case 'boolean': return typeof value === 'boolean';
+        case 'string-list': return Array.isArray(value) && value.every(entry => typeof entry === 'string');
+    }
+}
+/**
+ * Describe a value's shape, for a registration that declared the wrong kind.
+ * @param value - whatever `get()` returned.
+ * @returns a short description, never the value's content.
+ */
+function describeValue(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'an array';
+    return `a ${typeof value}`;
+}
+/**
+ * Parse one text value into the declared kind.
+ *
+ * `string` cannot fail — every text is a string — so an empty value is deliberately *not* refused here:
+ * whether a particular string may be empty is the owner's rule, and it can say why. The other three
+ * kinds have exactly one representation each, because an ambiguous parse is a change that applies
+ * something the caller did not ask for.
+ * @param kind - the setting's declared kind.
+ * @param text - the value as it arrived.
+ * @returns the parsed value, or that it did not parse.
+ */
+function parseValue(kind, text) {
+    switch (kind) {
+        case 'string':
+            return { ok: true, value: text };
+        case 'number': {
+            const trimmed = text.trim();
+            if (trimmed.length === 0)
+                return { ok: false };
+            const value = Number(trimmed);
+            return Number.isFinite(value) ? { ok: true, value } : { ok: false };
+        }
+        case 'boolean':
+            if (text !== 'true' && text !== 'false')
+                return { ok: false };
+            return { ok: true, value: text === 'true' };
+        case 'string-list': {
+            // JSON, and only JSON: a list of secrets separated by commas cannot be split on a comma, and a
+            // rule that guessed would silently drop half a secret from the redaction list.
+            let parsed;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                return { ok: false };
+            }
+            if (!Array.isArray(parsed) || !parsed.every(entry => typeof entry === 'string'))
+                return { ok: false };
+            return { ok: true, value: parsed };
+        }
+    }
+}
+/**
+ * Quote a received value back, redacted and bounded.
+ *
+ * Redacted because the echo travels to whoever asked and into whatever they render it in, and a caller
+ * that sent a credential to the right route by mistake should not have it handed back for display.
+ * @param text - the value as it arrived.
+ * @returns a short, safe quotation of it.
+ */
+function describeText(text) {
+    return JSON.stringify(redact(text).slice(0, 40));
+}
+/**
+ * The reason a setter refused, as a line to relay.
+ *
+ * A rejection that carries no message is still a rejection, and naming the absence is more useful than
+ * an empty string that reads as "no reason".
+ * @param error - whatever the setter threw.
+ * @returns a non-empty reason.
+ */
+function reasonOf(error) {
+    if (error instanceof Error && error.message.length > 0)
+        return error.message;
+    if (typeof error === 'string' && error.length > 0)
+        return error;
+    return 'the setting declined the value';
+}
+//# sourceMappingURL=settings.js.map

package/lib/settings.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-realtime",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Realtime voice capability seam for DeepSeek Harness: a provider registry plus the session adapter base.",
   "type": "module",
   "main": "lib/index.js",

package/src/error.ts

@@ -27,6 +27,10 @@ export const REALTIME_ERROR_CODES = Object.freeze({
   PROVIDER_ERROR: 'PROVIDER_ERROR',
   /** A recorded session could not be read as a recording. */
   INVALID_RECORDING: 'INVALID_RECORDING',
+  /** A setting's declaration is malformed: a bad field name, kind, scope, or a kind that does not match what it returns. */
+  INVALID_SETTING: 'INVALID_SETTING',
+  /** A setting is already registered under that key by another registration. */
+  DUPLICATE_SETTING: 'DUPLICATE_SETTING',
 
   // ---------------------------------------------------------------------------------------------
   // Failure taxonomy. These exist so a consumer can branch on the *class* of a failure rather than

package/src/index.ts

@@ -12,6 +12,7 @@
 import { Service, type Context } from '@deepseek-ai/cordis'
 import { REALTIME_ERROR_CODES, RealtimeError } from './error.ts'
 import { Journal } from './journal.ts'
+import { RealtimeSettings } from './settings.ts'
 import type {
   RealtimeDelegation,
   RealtimeModelInfo,
@@ -25,6 +26,7 @@ export * from './types.ts'
 export * from './error.ts'
 export * from './redact.ts'
 export * from './journal.ts'
+export * from './settings.ts'
 export { RealtimeError, REALTIME_ERROR_CODES } from './error.ts'
 
 declare module '@deepseek-ai/cordis' {
@@ -120,6 +122,18 @@ export class RealtimeRuntime extends Service {
    */
   readonly journal = new Journal()
 
+  /**
+   * The settings every plugin in this bundle declares, and the surface a control plane changes them
+   * through.
+   *
+   * Owned here beside the journal, for the same reason: it is the one object all of them already hold,
+   * and a surface split across three of them would leave a reader correlating three partial answers to
+   * one question. A setting's class comes from `docs/control-plane-fields.md`, and the registry is what
+   * makes that classification bite — a change to a field the protocol cannot honour is refused with the
+   * reason, on the same channel it arrived on.
+   */
+  readonly settings = new RealtimeSettings(this.journal)
+
   /**
    * @param ctx - the Cordis context this service is mounted on.
    */

package/src/journal.ts

@@ -59,6 +59,15 @@ export type JournalKind =
   | 'speech.sent'
   /** The configuration as resolved, so a journal can be read without the profile beside it. */
   | 'config.resolved'
+  /**
+   * A live setting changed while the plugin was running.
+   *
+   * Recorded with the setting's **key and not its value**: the value of a secret-bearing setting is
+   * exactly the text that must not be retained, and this is the one record built to be read, quoted
+   * and pasted. What a reader needs is that a change happened and which setting it was — the value is
+   * whatever the plugin now reports through the settings surface.
+   */
+  | 'config.changed'
 
 /** One retained entry. */
 export interface JournalEntry {