dsh-realtime 0.1.0 → 0.2.0

package/lib/error.d.ts

@@ -26,9 +26,51 @@ export declare const REALTIME_ERROR_CODES: Readonly<{
     PROVIDER_ERROR: "PROVIDER_ERROR";
     /** A recorded session could not be read as a recording. */
     INVALID_RECORDING: "INVALID_RECORDING";
+    /**
+     * The capability is not configured yet — an expected state on a fresh install, not a fault.
+     *
+     * Distinct from {@link REALTIME_ERROR_CODES.CREDENTIAL_REJECTED}: absent is fixed by supplying a
+     * value, unusable by replacing one.
+     */
+    NOT_CONFIGURED: "NOT_CONFIGURED";
+    /** A credential is present and the provider refused it. Replace it; retrying cannot help. */
+    CREDENTIAL_REJECTED: "CREDENTIAL_REJECTED";
+    /** The credential is valid but the account cannot use what was requested (model, region, scope). */
+    NOT_ENTITLED: "NOT_ENTITLED";
+    /** The account cannot pay for the request — an exhausted balance or a hard billing limit. */
+    INSUFFICIENT_CREDIT: "INSUFFICIENT_CREDIT";
+    /** The provider throttled the request. Repeating later may succeed. */
+    RATE_LIMITED: "RATE_LIMITED";
+    /** The provider was asked something and did not answer within the bound. */
+    PROVIDER_TIMEOUT: "PROVIDER_TIMEOUT";
+    /** The transport failed — a socket error, not a decision the provider made. */
+    NETWORK: "NETWORK";
 }>;
 /** One of {@link REALTIME_ERROR_CODES}. */
 export type RealtimeErrorCode = (typeof REALTIME_ERROR_CODES)[keyof typeof REALTIME_ERROR_CODES];
+/**
+ * What a caller can act on, carried as structure rather than prose.
+ *
+ * A failure a user cannot act on is a failure report that wasted their time. Every field here exists
+ * so the *class* of a failure survives translation: an agent can relay `remedy` verbatim, a settings
+ * surface can highlight `setting`, a retry loop can consult `retryable`, and a human reading a log
+ * can see the provider's own `providerCode` instead of a paraphrase of it.
+ *
+ * Never carries secret material. `providerCode` is the provider's own error code, never a credential.
+ */
+export interface RealtimeFailureDetail {
+    /**
+     * What to do about it, written to be relayed **verbatim** to whoever is trying to use the feature.
+     * One sentence, imperative, no jargon.
+     */
+    remedy?: string;
+    /** The configuration key that must be supplied, when the failure is a configuration state. */
+    setting?: string;
+    /** Whether repeating the identical call could succeed without any change. */
+    retryable?: boolean;
+    /** The provider's own error code, verbatim. Never a translated or inferred value. */
+    providerCode?: string;
+}
 /**
  * A typed seam failure.
  *
@@ -38,11 +80,15 @@ export type RealtimeErrorCode = (typeof REALTIME_ERROR_CODES)[keyof typeof REALT
 export declare class RealtimeError extends Error {
     /** Stable machine code. Branch on this, never on `message`. */
     readonly code: RealtimeErrorCode;
+    /** What a caller can act on, when the failure is one they can act on. */
+    readonly detail: RealtimeFailureDetail | undefined;
     /**
      * @param message - non-empty human-readable summary. Must not contain secret material.
      * @param code - one of {@link REALTIME_ERROR_CODES}.
-     * @param options - optional `cause`.
+     * @param options - optional `cause`, and an optional structured `detail`.
      */
-    constructor(message: string, code: RealtimeErrorCode, options?: ErrorOptions);
+    constructor(message: string, code: RealtimeErrorCode, options?: ErrorOptions & {
+        detail?: RealtimeFailureDetail;
+    });
 }
 //# sourceMappingURL=error.d.ts.map

package/lib/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,gDAAgD;AAChD,eAAO,MAAM,oBAAoB;IAC/B,iEAAiE;;IAEjE,yEAAyE;;IAEzE,yEAAyE;;IAEzE,wDAAwD;;IAExD,mEAAmE;;IAEnE,2CAA2C;;IAE3C,iGAAiG;;IAEjG,iGAAiG;;IAEjG,2DAA2D;;IAS3D;;;;;OAKG;;IAEH,6FAA6F;;IAE7F,oGAAoG;;IAEpG,6FAA6F;;IAE7F,uEAAuE;;IAEvE,4EAA4E;;IAE5E,+EAA+E;;EAE/E,CAAA;AAEF,2CAA2C;AAC3C,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,OAAO,oBAAoB,CAAC,CAAA;AAEhG;;;;;;;;;GASG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,8FAA8F;IAC9F,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,qFAAqF;IACrF,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AA4BD;;;;;GAKG;AACH,qBAAa,aAAc,SAAQ,KAAK;IACtC,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAA;IAEhC,yEAAyE;IACzE,QAAQ,CAAC,MAAM,EAAE,qBAAqB,GAAG,SAAS,CAAA;IAElD;;;;OAIG;IACH,YAAY,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG;QAAE,MAAM,CAAC,EAAE,qBAAqB,CAAA;KAAE,EAchH;CACF"}

package/lib/error.js

@@ -26,7 +26,56 @@ 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',
+    // ---------------------------------------------------------------------------------------------
+    // Failure taxonomy. These exist so a consumer can branch on the *class* of a failure rather than
+    // parse prose: a setup state, a rejected credential, an account that cannot pay, and a throttle
+    // need four different responses, and collapsing them is what makes onboarding feel unfinished.
+    // ---------------------------------------------------------------------------------------------
+    /**
+     * The capability is not configured yet — an expected state on a fresh install, not a fault.
+     *
+     * Distinct from {@link REALTIME_ERROR_CODES.CREDENTIAL_REJECTED}: absent is fixed by supplying a
+     * value, unusable by replacing one.
+     */
+    NOT_CONFIGURED: 'NOT_CONFIGURED',
+    /** A credential is present and the provider refused it. Replace it; retrying cannot help. */
+    CREDENTIAL_REJECTED: 'CREDENTIAL_REJECTED',
+    /** The credential is valid but the account cannot use what was requested (model, region, scope). */
+    NOT_ENTITLED: 'NOT_ENTITLED',
+    /** The account cannot pay for the request — an exhausted balance or a hard billing limit. */
+    INSUFFICIENT_CREDIT: 'INSUFFICIENT_CREDIT',
+    /** The provider throttled the request. Repeating later may succeed. */
+    RATE_LIMITED: 'RATE_LIMITED',
+    /** The provider was asked something and did not answer within the bound. */
+    PROVIDER_TIMEOUT: 'PROVIDER_TIMEOUT',
+    /** The transport failed — a socket error, not a decision the provider made. */
+    NETWORK: 'NETWORK',
+});
+/** Expected `typeof` for each optional detail field. Data, so the check costs one loop and not a branch each. */
+const DETAIL_FIELD_TYPES = Object.freeze({
+    remedy: 'string',
+    setting: 'string',
+    providerCode: 'string',
+    retryable: 'boolean',
 });
+/**
+ * Reject a malformed detail before it is attached to a failure.
+ * @param detail - candidate detail.
+ * @throws TypeError naming the offending field.
+ */
+function assertDetail(detail) {
+    for (const [field, expected] of Object.entries(DETAIL_FIELD_TYPES)) {
+        const value = detail[field];
+        if (value === undefined)
+            continue;
+        if (typeof value !== expected) {
+            throw new TypeError(`RealtimeError detail.${field} must be a ${expected}`);
+        }
+        if (expected === 'string' && value === '') {
+            throw new TypeError(`RealtimeError detail.${field} must be non-empty when supplied`);
+        }
+    }
+}
 /**
  * A typed seam failure.
  *
@@ -36,10 +85,12 @@ export const REALTIME_ERROR_CODES = Object.freeze({
 export class RealtimeError extends Error {
     /** Stable machine code. Branch on this, never on `message`. */
     code;
+    /** What a caller can act on, when the failure is one they can act on. */
+    detail;
     /**
      * @param message - non-empty human-readable summary. Must not contain secret material.
      * @param code - one of {@link REALTIME_ERROR_CODES}.
-     * @param options - optional `cause`.
+     * @param options - optional `cause`, and an optional structured `detail`.
      */
     constructor(message, code, options) {
         if (typeof message !== 'string' || message.length === 0) {
@@ -48,9 +99,13 @@ export class RealtimeError extends Error {
         if (typeof code !== 'string' || code.length === 0) {
             throw new TypeError('RealtimeError code must be a non-empty string');
         }
+        if (options?.detail !== undefined) {
+            assertDetail(options.detail);
+        }
         super(message, options);
         this.name = 'RealtimeError';
         this.code = code;
+        this.detail = options?.detail;
     }
 }
 //# sourceMappingURL=error.js.map

package/lib/error.js.map

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

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAE3D,OAAO,KAAK,EACV,kBAAkB,EAClB,iBAAiB,EACjB,oBAAoB,EACpB,eAAe,EACf,uBAAuB,EACvB,sBAAsB,EACvB,MAAM,YAAY,CAAA;AAEnB,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AAEhE,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,OAAO;QACf,QAAQ,EAAE,eAAe,CAAA;KAC1B;CACF;AAED;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACxC,6DAA6D;IAC7D,IAAI,IAAI,CAAA;IACR;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;CACnC;AAED;;;;;;GAMG;AACH,8BAAsB,eAAe;IACnC;;;;OAIG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,oBAAoB,CAEnD;IAED;;;;;;;OAOG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CAEnE;IAED;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,eAAe,CAAC,CAAA;CAC5E;AAQD;;;;;GAKG;AACH,qBAAa,eAAgB,SAAQ,OAAO;IAC1C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyC;IAElE;;OAEG;IACH,YAAY,GAAG,EAAE,OAAO,EAEvB;IAED;;;;;;;;OAQG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,eAAe,GAAG,yBAAyB,CAiCxF;IAED;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,OAAO;IAgCf;;;;;OAKG;IACH,OAAO,CAAC,MAAM;IASd;;;OAGG;IACH,aAAa,IAAI,oBAAoB,EAAE,CAEtC;IAED;;;;;OAKG;IACH,OAAO,CAAC,YAAY;IAQpB;;;;OAIG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAe/D;IAED;;;;;;;;OAQG;IACG,OAAO,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,eAAe,CAAC,CAgBvE;IAED;;;;;;;;;;OAUG;IACH,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAWjE;CACF;AAED,qFAAqF;AACrF,YAAY,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,CAAA;eAE5C,eAAe"}

package/lib/index.js.map

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

package/lib/types.d.ts

@@ -144,20 +144,32 @@ export interface RealtimeSession {
     unmuteInput(): void;
     /**
      * Return a delegated result for the model to **speak aloud**.
+     *
+     * Resolves on the provider's **acknowledgement** when it answers a delegation. With no
+     * `delegationId` there is no acknowledgement to wait for: the provider accepts a session-wide append
+     * in silence, because it does not begin applying context at a bare `session.start`. That form
+     * therefore resolves on the write and is **best-effort** — it is applied once audio has flowed, and
+     * this seam cannot say when. It is not a way to speak unprompted.
      * @param content - plain text, non-empty and within {@link MAX_APPEND_CHARS}.
-     * @param delegationId - the delegation this answers, or `undefined` for session-wide context.
+     * @param delegationId - the delegation this answers, or `undefined` for best-effort session context.
      */
     appendCommentary(content: string, delegationId?: string): Promise<void>;
     /**
      * Add context the model may use **without speaking it** — progress, facts, intermediate state.
+     *
+     * With no `delegationId` this resolves on the write and is best-effort, for the reason recorded on
+     * {@link appendCommentary}: the provider does not acknowledge a session-wide append.
      * @param content - plain text, non-empty and within {@link MAX_APPEND_CHARS}.
-     * @param delegationId - the delegation this relates to, or `undefined` for session-wide context.
+     * @param delegationId - the delegation this relates to, or `undefined` for best-effort session context.
      */
     appendThinking(content: string, delegationId?: string): Promise<void>;
     /**
      * Steer the live conversation's behaviour (tone, brevity, policy) without speaking anything.
+     *
+     * With no `delegationId` this resolves on the write and is best-effort, for the reason recorded on
+     * {@link appendCommentary}.
      * @param content - plain text, non-empty and within {@link MAX_APPEND_CHARS}.
-     * @param delegationId - `undefined` for session-wide steering.
+     * @param delegationId - `undefined` for best-effort session-wide steering.
      */
     appendInstructions(content: string, delegationId?: string): Promise<void>;
     /**

package/lib/types.d.ts.map

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

package/lib/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAkMH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-realtime",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Realtime voice capability seam for DeepSeek Harness: a provider registry plus the session adapter base.",
   "type": "module",
   "main": "lib/index.js",
@@ -18,15 +18,12 @@
       "types": "./lib/error.d.ts",
       "default": "./lib/error.js"
     },
+    "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
   "files": [
-    "lib/index.js",
-    "lib/index.d.ts",
-    "lib/types.js",
-    "lib/types.d.ts",
-    "lib/error.js",
-    "lib/error.d.ts"
+    "lib",
+    "src"
   ],
   "license": "MIT",
   "keywords": [

package/src/error.ts

@@ -0,0 +1,144 @@
+/**
+ * Typed failures for the realtime seam, carrying stable machine codes.
+ *
+ * Codes are the seam's API: a consumer branches on `code`, never on message text. Adding a code is a
+ * minor release; changing what an existing code means is a breaking one.
+ *
+ * @module dsh-realtime/error
+ */
+
+/** Stable machine codes raised by this seam. */
+export const REALTIME_ERROR_CODES = Object.freeze({
+  /** A registration named an empty or malformed provider route. */
+  INVALID_PROVIDER: 'INVALID_PROVIDER',
+  /** A route already has an adapter registered by another registration. */
+  DUPLICATE_PROVIDER: 'DUPLICATE_PROVIDER',
+  /** Registration was released, so it can no longer replace its routes. */
+  REGISTRATION_DISPOSED: 'REGISTRATION_DISPOSED',
+  /** No adapter is registered for the requested route. */
+  NO_ADAPTER: 'NO_ADAPTER',
+  /** An append was empty, not a string, or over the seam's bound. */
+  INVALID_APPEND: 'INVALID_APPEND',
+  /** The session has already been closed. */
+  SESSION_CLOSED: 'SESSION_CLOSED',
+  /** The credential an adapter needs is absent or unusable. Names the setting, never the value. */
+  MISSING_CREDENTIAL: 'MISSING_CREDENTIAL',
+  /** The provider reported a failure, or an operation it was expected to acknowledge never was. */
+  PROVIDER_ERROR: 'PROVIDER_ERROR',
+  /** A recorded session could not be read as a recording. */
+  INVALID_RECORDING: 'INVALID_RECORDING',
+
+  // ---------------------------------------------------------------------------------------------
+  // Failure taxonomy. These exist so a consumer can branch on the *class* of a failure rather than
+  // parse prose: a setup state, a rejected credential, an account that cannot pay, and a throttle
+  // need four different responses, and collapsing them is what makes onboarding feel unfinished.
+  // ---------------------------------------------------------------------------------------------
+
+  /**
+   * The capability is not configured yet — an expected state on a fresh install, not a fault.
+   *
+   * Distinct from {@link REALTIME_ERROR_CODES.CREDENTIAL_REJECTED}: absent is fixed by supplying a
+   * value, unusable by replacing one.
+   */
+  NOT_CONFIGURED: 'NOT_CONFIGURED',
+  /** A credential is present and the provider refused it. Replace it; retrying cannot help. */
+  CREDENTIAL_REJECTED: 'CREDENTIAL_REJECTED',
+  /** The credential is valid but the account cannot use what was requested (model, region, scope). */
+  NOT_ENTITLED: 'NOT_ENTITLED',
+  /** The account cannot pay for the request — an exhausted balance or a hard billing limit. */
+  INSUFFICIENT_CREDIT: 'INSUFFICIENT_CREDIT',
+  /** The provider throttled the request. Repeating later may succeed. */
+  RATE_LIMITED: 'RATE_LIMITED',
+  /** The provider was asked something and did not answer within the bound. */
+  PROVIDER_TIMEOUT: 'PROVIDER_TIMEOUT',
+  /** The transport failed — a socket error, not a decision the provider made. */
+  NETWORK: 'NETWORK',
+})
+
+/** One of {@link REALTIME_ERROR_CODES}. */
+export type RealtimeErrorCode = (typeof REALTIME_ERROR_CODES)[keyof typeof REALTIME_ERROR_CODES]
+
+/**
+ * What a caller can act on, carried as structure rather than prose.
+ *
+ * A failure a user cannot act on is a failure report that wasted their time. Every field here exists
+ * so the *class* of a failure survives translation: an agent can relay `remedy` verbatim, a settings
+ * surface can highlight `setting`, a retry loop can consult `retryable`, and a human reading a log
+ * can see the provider's own `providerCode` instead of a paraphrase of it.
+ *
+ * Never carries secret material. `providerCode` is the provider's own error code, never a credential.
+ */
+export interface RealtimeFailureDetail {
+  /**
+   * What to do about it, written to be relayed **verbatim** to whoever is trying to use the feature.
+   * One sentence, imperative, no jargon.
+   */
+  remedy?: string
+  /** The configuration key that must be supplied, when the failure is a configuration state. */
+  setting?: string
+  /** Whether repeating the identical call could succeed without any change. */
+  retryable?: boolean
+  /** The provider's own error code, verbatim. Never a translated or inferred value. */
+  providerCode?: string
+}
+
+/** Expected `typeof` for each optional detail field. Data, so the check costs one loop and not a branch each. */
+const DETAIL_FIELD_TYPES = Object.freeze({
+  remedy: 'string',
+  setting: 'string',
+  providerCode: 'string',
+  retryable: 'boolean',
+})
+
+/**
+ * Reject a malformed detail before it is attached to a failure.
+ * @param detail - candidate detail.
+ * @throws TypeError naming the offending field.
+ */
+function assertDetail(detail: RealtimeFailureDetail): void {
+  for (const [field, expected] of Object.entries(DETAIL_FIELD_TYPES)) {
+    const value = (detail as Record<string, unknown>)[field]
+    if (value === undefined) continue
+    if (typeof value !== expected) {
+      throw new TypeError(`RealtimeError detail.${field} must be a ${expected}`)
+    }
+    if (expected === 'string' && value === '') {
+      throw new TypeError(`RealtimeError detail.${field} must be non-empty when supplied`)
+    }
+  }
+}
+
+/**
+ * A typed seam failure.
+ *
+ * The constructor validates its own arguments rather than trusting callers: a failure raised while
+ * reporting a failure is the worst place to discover a malformed argument.
+ */
+export class RealtimeError extends Error {
+  /** Stable machine code. Branch on this, never on `message`. */
+  readonly code: RealtimeErrorCode
+
+  /** What a caller can act on, when the failure is one they can act on. */
+  readonly detail: RealtimeFailureDetail | undefined
+
+  /**
+   * @param message - non-empty human-readable summary. Must not contain secret material.
+   * @param code - one of {@link REALTIME_ERROR_CODES}.
+   * @param options - optional `cause`, and an optional structured `detail`.
+   */
+  constructor(message: string, code: RealtimeErrorCode, options?: ErrorOptions & { detail?: RealtimeFailureDetail }) {
+    if (typeof message !== 'string' || message.length === 0) {
+      throw new TypeError('RealtimeError message must be a non-empty string')
+    }
+    if (typeof code !== 'string' || code.length === 0) {
+      throw new TypeError('RealtimeError code must be a non-empty string')
+    }
+    if (options?.detail !== undefined) {
+      assertDetail(options.detail)
+    }
+    super(message, options)
+    this.name = 'RealtimeError'
+    this.code = code
+    this.detail = options?.detail
+  }
+}

package/src/index.ts

@@ -0,0 +1,320 @@
+/**
+ * Realtime voice seam: a provider registry plus the adapter base every voice backend extends.
+ *
+ * Exports the `RealtimeRuntime` service as the **default** export (a DeepSeek Harness convention for
+ * service packages) and the abstract `RealtimeAdapter` for provider backends. Function plugins
+ * must supply `name` / `inject` / `Config` / `apply` and no default export; this package is a
+ * service package, so it is mounted as a class plugin and default-exports its service.
+ *
+ * @module dsh-realtime
+ */
+
+import { Service, type Context } from '@deepseek-ai/cordis'
+import { REALTIME_ERROR_CODES, RealtimeError } from './error.ts'
+import type {
+  RealtimeDelegation,
+  RealtimeModelInfo,
+  RealtimeProviderInfo,
+  RealtimeSession,
+  RealtimeSessionHandlers,
+  RealtimeSessionOptions,
+} from './types.ts'
+
+export * from './types.ts'
+export * from './error.ts'
+export { RealtimeError, REALTIME_ERROR_CODES } from './error.ts'
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    realtime: RealtimeRuntime
+  }
+}
+
+/**
+ * What {@link RealtimeRuntime.registerAdapter} returns: the disposer, plus an atomic route
+ * replacement for the same adapter instance.
+ */
+export interface AdapterRegistrationHandle {
+  /** Release every route this registration currently holds. */
+  (): void
+  /**
+   * Replace this registration's routes, keeping the same adapter instance. The candidate set is
+   * validated in full first — a conflict with another registration or a malformed route throws and
+   * leaves the current routes untouched — and the swap is one synchronous section, so no observer
+   * can see the registry between release and re-registration.
+   *
+   * An empty array is legal here (a plugin whose configuration emptied holds zero routes while
+   * staying registered), unlike an empty initial registration.
+   *
+   * Throws `REGISTRATION_DISPOSED` once the registration was released: its routes are gone and its
+   * disposer has already run, so anything registered afterwards would have no owner left to release it.
+   * @param providers - the complete next route set for this registration.
+   */
+  replace(providers: string[]): void
+}
+
+/**
+ * Provider-wire adapter for the realtime session vocabulary.
+ *
+ * Register implementations with `ctx.realtime.registerAdapter(providers, adapter)`. The single
+ * required method is {@link session}; every other method exists so a provider can describe itself
+ * without the seam having to special-case it.
+ */
+export abstract class RealtimeAdapter {
+  /**
+   * Describe one provider route owned by this adapter.
+   * @param provider - a route passed to `registerAdapter()` for this instance.
+   * @returns detached display metadata whose `id` must equal `provider`.
+   */
+  providerInfo(provider: string): RealtimeProviderInfo {
+    return { id: provider, name: provider }
+  }
+
+  /**
+   * List the voice models this adapter can currently advertise for one owned route.
+   *
+   * The result is advisory: an adapter may accept unlisted model ids, and consumers must not turn
+   * absence into request rejection.
+   * @param _provider - one provider route owned by this adapter.
+   * @returns discoverable models in adapter-preferred order.
+   */
+  listModels(_provider: string): Promise<readonly RealtimeModelInfo[]> {
+    return Promise.resolve([])
+  }
+
+  /**
+   * Open one voice session. The only required method.
+   *
+   * Implementations must honor `options.signal` during establishment, and must throw (rather than
+   * resolve with a dead session) when the session cannot open.
+   * @param options - the fully-resolved request; `options.provider` selects the registered route.
+   * @returns the live session, with `options.handlers` already wired.
+   */
+  abstract session(options: RealtimeSessionOptions): Promise<RealtimeSession>
+}
+
+/** One resolved route registration. */
+interface AdapterRegistration {
+  readonly adapter: RealtimeAdapter
+  readonly provider: RealtimeProviderInfo
+}
+
+/**
+ * The `realtime` service: an adapter registry over the session vocabulary.
+ *
+ * Registration is effect-based, so HMR or a disposal unmounts routes with the contributing fiber —
+ * there is no separate teardown path that can be forgotten.
+ */
+export class RealtimeRuntime extends Service {
+  private readonly adapters = new Map<string, AdapterRegistration>()
+
+  /**
+   * @param ctx - the Cordis context this service is mounted on.
+   */
+  constructor(ctx: Context) {
+    super(ctx, 'realtime')
+  }
+
+  /**
+   * Register an adapter for the given provider routes, all-or-nothing.
+   *
+   * Disposed with the fiber. Throws `INVALID_PROVIDER` for a malformed route, `DUPLICATE_PROVIDER`
+   * if any route is already held by another registration.
+   * @param providers - every provider route this adapter should serve.
+   * @param adapter - the adapter that opens sessions for those routes.
+   * @returns the disposer, carrying {@link AdapterRegistrationHandle.replace}.
+   */
+  registerAdapter(providers: string[], adapter: RealtimeAdapter): AdapterRegistrationHandle {
+    if (providers.length === 0) {
+      throw new RealtimeError('an adapter must register at least one provider', REALTIME_ERROR_CODES.INVALID_PROVIDER)
+    }
+    // Routes this registration currently holds; `replace` rewrites it, and the disposer releases
+    // whatever it holds at disposal time.
+    const owned = new Set<string>()
+    // `owned` being empty cannot report disposal on its own, because `replace([])` legally leaves a
+    // live registration holding none.
+    let released = false
+
+    const dispose = this.ctx.effect(function* (this: RealtimeRuntime) {
+      this.commit(owned, this.prepare(providers, adapter, owned))
+      yield () => {
+        released = true
+        for (const provider of owned) this.adapters.delete(provider)
+        owned.clear()
+      }
+    }.bind(this), 'realtime.registerAdapter()')
+
+    const handle = (() => void dispose()) as AdapterRegistrationHandle
+    handle.replace = (next: string[]): void => {
+      // Registering here would leak: the effect's disposer already ran, so nothing remains to
+      // release whatever this call would put in the map.
+      if (released) {
+        throw new RealtimeError(
+          'a disposed adapter registration cannot replace its routes',
+          REALTIME_ERROR_CODES.REGISTRATION_DISPOSED,
+        )
+      }
+      this.commit(owned, this.prepare(next, adapter, owned))
+    }
+    return handle
+  }
+
+  /**
+   * Validate one candidate route set for `adapter`, treating routes this registration already holds
+   * as available.
+   *
+   * Nothing is mutated: a rejected candidate leaves the registry exactly as it was, which is what
+   * makes {@link AdapterRegistrationHandle.replace} a swap rather than a delete-then-add that can
+   * strand the registry empty.
+   * @param providers - candidate routes.
+   * @param adapter - the adapter that would own them.
+   * @param owned - routes this same registration already holds.
+   * @returns registrations ready to commit.
+   */
+  private prepare(providers: string[], adapter: RealtimeAdapter, owned: ReadonlySet<string>): AdapterRegistration[] {
+    const unique = new Set<string>()
+    const registrations: AdapterRegistration[] = []
+    for (const provider of providers) {
+      if (typeof provider !== 'string' || provider.length === 0) {
+        throw new RealtimeError('adapter provider names must be non-empty strings', REALTIME_ERROR_CODES.INVALID_PROVIDER)
+      }
+      if (unique.has(provider) || (this.adapters.has(provider) && !owned.has(provider))) {
+        throw new RealtimeError(
+          `an adapter for provider "${provider}" is already registered`,
+          REALTIME_ERROR_CODES.DUPLICATE_PROVIDER,
+        )
+      }
+      const info = adapter.providerInfo(provider)
+      if (typeof info.id !== 'string' || info.id !== provider
+        || typeof info.name !== 'string' || info.name.length === 0) {
+        throw new RealtimeError(
+          `adapter metadata for provider "${provider}" must preserve its id and have a non-empty name`,
+          REALTIME_ERROR_CODES.INVALID_PROVIDER,
+        )
+      }
+      unique.add(provider)
+      registrations.push({
+        adapter,
+        provider: info.description === undefined
+          ? { id: info.id, name: info.name }
+          : { id: info.id, name: info.name, description: info.description },
+      })
+    }
+    return registrations
+  }
+
+  /**
+   * Swap this registration's routes for the prepared ones in one synchronous section, so no
+   * observer can see the registry between the release and the re-registration.
+   * @param owned - mutable set tracking which routes this registration holds.
+   * @param registrations - validated registrations to install.
+   */
+  private commit(owned: Set<string>, registrations: readonly AdapterRegistration[]): void {
+    for (const provider of owned) this.adapters.delete(provider)
+    owned.clear()
+    for (const registration of registrations) {
+      this.adapters.set(registration.provider.id, registration)
+      owned.add(registration.provider.id)
+    }
+  }
+
+  /**
+   * Describe the provider routes that currently have an adapter.
+   * @returns detached provider metadata in registration order.
+   */
+  listProviders(): RealtimeProviderInfo[] {
+    return [...this.adapters.values()].map(({ provider }) => ({ ...provider }))
+  }
+
+  /**
+   * Resolve the adapter owning one route.
+   * @param provider - registered route to look up.
+   * @returns that route's registration.
+   * @throws RealtimeError `NO_ADAPTER` when the route is unregistered.
+   */
+  private registration(provider: string): AdapterRegistration {
+    const registration = this.adapters.get(provider)
+    if (registration === undefined) {
+      throw new RealtimeError(`no realtime adapter registered for provider "${provider}"`, REALTIME_ERROR_CODES.NO_ADAPTER)
+    }
+    return registration
+  }
+
+  /**
+   * Discover the voice models one registered route advertises.
+   * @param provider - registered route to inspect.
+   * @returns detached model metadata in adapter-preferred order, duplicates removed.
+   */
+  async listModels(provider: string): Promise<RealtimeModelInfo[]> {
+    const models = await this.registration(provider).adapter.listModels(provider)
+    const seen = new Set<string>()
+    const detached: RealtimeModelInfo[] = []
+    for (const model of models) {
+      if (typeof model.id !== 'string' || model.id.length === 0 || seen.has(model.id)) continue
+      seen.add(model.id)
+      detached.push({
+        id: model.id,
+        name: typeof model.name === 'string' && model.name.length > 0 ? model.name : model.id,
+        ...model.inputModalities === undefined ? {} : { inputModalities: [...model.inputModalities] },
+        ...model.outputModalities === undefined ? {} : { outputModalities: [...model.outputModalities] },
+      })
+    }
+    return detached
+  }
+
+  /**
+   * Open one voice session through the adapter registered for its route.
+   *
+   * A field this seam cannot honor is rejected here rather than forwarded as a no-op — the caller
+   * learns the request is unsupported before a live conversation depends on it.
+   * @param options - the session request; `options.provider` selects the adapter.
+   * @returns the adapter's live session.
+   * @throws RealtimeError `NO_ADAPTER` for an unregistered route.
+   */
+  async session(options: RealtimeSessionOptions): Promise<RealtimeSession> {
+    if (typeof options.provider !== 'string' || options.provider.length === 0) {
+      throw new RealtimeError('a session needs a non-empty provider route', REALTIME_ERROR_CODES.INVALID_PROVIDER)
+    }
+    if (typeof options.model !== 'string' || options.model.length === 0) {
+      throw new RealtimeError('a session needs a non-empty model id', REALTIME_ERROR_CODES.INVALID_PROVIDER)
+    }
+    if (options.instructions !== undefined && options.instructions.length === 0) {
+      throw new RealtimeError('session instructions must be non-empty when supplied', REALTIME_ERROR_CODES.INVALID_APPEND)
+    }
+    if (options.signal?.aborted) {
+      throw new RealtimeError('session establishment was aborted before it started', REALTIME_ERROR_CODES.SESSION_CLOSED, {
+        cause: options.signal.reason,
+      })
+    }
+    return await this.registration(options.provider).adapter.session(options)
+  }
+
+  /**
+   * Validate one context append against the seam's bounds.
+   *
+   * Exposed so an adapter can enforce the same bound the seam promises, instead of each backend
+   * re-deriving it. Bound enforcement lives at the operation that makes the decision: a caller that
+   * bypasses this cannot silently send an over-long append.
+   * @param content - candidate append text.
+   * @param maxChars - character ceiling; defaults to the provider's documented bound.
+   * @returns the content unchanged, for convenient inline use.
+   * @throws RealtimeError `INVALID_APPEND` for a non-string, empty, or over-long value.
+   */
+  static assertAppendable(content: string, maxChars: number): string {
+    if (typeof content !== 'string' || content.length === 0) {
+      throw new RealtimeError('an append needs non-empty content', REALTIME_ERROR_CODES.INVALID_APPEND)
+    }
+    if (content.length > maxChars) {
+      throw new RealtimeError(
+        `an append of ${content.length} characters exceeds the ${maxChars}-character seam bound`,
+        REALTIME_ERROR_CODES.INVALID_APPEND,
+      )
+    }
+    return content
+  }
+}
+
+/** Re-exported so adapters can type their handler wiring without a second import. */
+export type { RealtimeDelegation, RealtimeSessionHandlers }
+
+export default RealtimeRuntime

package/src/types.ts

@@ -0,0 +1,208 @@
+/**
+ * Types for the realtime voice seam. This module contains **no runtime code** — a
+ * DeepSeek Harness convention that keeps type-only imports erasable.
+ *
+ * @module dsh-realtime/types
+ */
+
+/** A model route a realtime adapter can serve. */
+export interface RealtimeProviderInfo {
+  /** Route id a caller passes as `RealtimeSessionOptions.provider`. Must equal the registered route. */
+  id: string
+  /** Human-readable label for diagnostics and surfaces. */
+  name: string
+  /** Optional one-line description of what this route speaks. */
+  description?: string
+}
+
+/** One voice model advertised by an adapter. Catalog membership is advisory: it never gates a session. */
+export interface RealtimeModelInfo {
+  /** Exact model id passed as `RealtimeSessionOptions.model`. */
+  id: string
+  /** Human-readable label. */
+  name: string
+  /** What the model can take in, e.g. `audio`, `text`, `image`. */
+  inputModalities?: readonly RealtimeModality[]
+  /** What the model puts out, e.g. `audio`, `text`. */
+  outputModalities?: readonly RealtimeModality[]
+}
+
+/** A modality a realtime model accepts or emits. */
+export type RealtimeModality = 'audio' | 'text' | 'image'
+
+/** Raw audio encoding expected on the wire. */
+export interface RealtimeAudioFormat {
+  /** Sample rate in Hz. `24000` for GPT-Live-1. */
+  sampleRate: number
+  /** Channel count. `1` (mono) for GPT-Live-1. */
+  channels: number
+  /** Sample encoding. `pcm16` is signed little-endian 16-bit. */
+  encoding: 'pcm16'
+}
+
+/** What a caller asks an adapter to open. */
+export interface RealtimeSessionOptions {
+  /** Registered route to use. Selects the adapter. */
+  provider: string
+  /** Exact model id. */
+  model: string
+  /**
+   * Opening system instructions.
+   *
+   * Advisory at the seam: the protocol may treat these as immutable once a session starts, in which
+   * case an adapter must surface a coded error rather than silently dropping the request. Extending
+   * live instructions is `RealtimeSession.appendInstructions`, not a new session.
+   */
+  instructions?: string
+  /** Output voice id. Provider-specific; `undefined` leaves the provider default. */
+  voice?: string
+  /** Cancellation for session establishment. Implementations must settle promptly after it aborts. */
+  signal?: AbortSignal
+  /** Handler callbacks for the life of the session. */
+  handlers?: RealtimeSessionHandlers
+}
+
+/** A delegated unit of work handed to the application by the voice model. */
+export interface RealtimeDelegation {
+  /** Opaque correlation id. Preserve it unchanged on every update about this delegation. */
+  id: string
+  /** Who is expected to do the work. `client` means this application. */
+  target: 'client' | 'responses'
+  /**
+   * Position on the session timeline, in milliseconds.
+   *
+   * Note there is deliberately **no task text** here: the protocol sends metadata only, so a
+   * consumer reconstructs intent from transcripts plus its own application state.
+   */
+  offsetMs: number
+}
+
+/** A transcript fragment from either side of the conversation. */
+export interface RealtimeTranscript {
+  /** Which side spoke. */
+  kind: 'input' | 'output'
+  /** The fragment text. Deltas concatenate in arrival order. */
+  text: string
+  /** Whether this fragment closes the utterance. */
+  final: boolean
+}
+
+/** Cumulative session usage. The protocol reports this in audio-seconds, not tokens. */
+export interface RealtimeUsage {
+  /** Cumulative audio seconds billed for this session. */
+  seconds: number
+}
+
+/** Callbacks an adapter invokes for session lifetime events. */
+export interface RealtimeSessionHandlers {
+  /** The session is established and can accept audio. */
+  onReady?(info: RealtimeSessionStarted): void
+  /** A transcript fragment arrived. */
+  onTranscript?(transcript: RealtimeTranscript): void
+  /** The model delegated work to this application. */
+  onDelegation?(delegation: RealtimeDelegation): void
+  /** Cumulative usage was updated. */
+  onUsage?(usage: RealtimeUsage): void
+  /** Raw output audio, already decoded from the wire encoding. */
+  onAudio?(pcm16: Uint8Array): void
+  /** The session ended. `reason` is provider-supplied when available. */
+  onClosed?(reason?: string): void
+  /**
+   * A session-scoped failure the adapter contained rather than throwing.
+   *
+   * Adapters report here for failures that occur *after* the session opened; failures that prevent
+   * the session opening are thrown from `session()`.
+   */
+  onError?(error: Error): void
+}
+
+/** Facts about an established session. */
+export interface RealtimeSessionStarted {
+  /** The route that opened it. */
+  provider: string
+  /** The model the provider accepted — which may differ from the requested id if the provider aliases. */
+  model: string
+  /** The output voice the provider accepted. */
+  voice?: string
+  /** Audio encoding the session expects for input. */
+  inputAudio: RealtimeAudioFormat
+  /** Audio encoding the session emits. */
+  outputAudio: RealtimeAudioFormat
+}
+
+/**
+ * A live voice session.
+ *
+ * Implementations own the transport. Callers own the conversation: they push audio in, receive
+ * callbacks, and answer delegations through the append methods.
+ */
+export interface RealtimeSession {
+  /** Provider-assigned session identifier, for correlation in logs. */
+  readonly id: string
+  /** Facts the provider accepted at startup. */
+  readonly started: RealtimeSessionStarted
+
+  /**
+   * Append one frame of microphone audio.
+   *
+   * There is deliberately **no end-of-utterance call**: endpointing belongs to the provider, and a
+   * client-side detector would be a second, competing turn boundary. Frames are the only input.
+   * @param pcm16 - raw samples in the session's `inputAudio` format.
+   */
+  sendAudio(pcm16: Uint8Array): void
+
+  /** Stop the provider consuming microphone audio, without ending the session. */
+  muteInput(): void
+
+  /** Resume microphone consumption after {@link muteInput}. */
+  unmuteInput(): void
+
+  /**
+   * Return a delegated result for the model to **speak aloud**.
+   *
+   * Resolves on the provider's **acknowledgement** when it answers a delegation. With no
+   * `delegationId` there is no acknowledgement to wait for: the provider accepts a session-wide append
+   * in silence, because it does not begin applying context at a bare `session.start`. That form
+   * therefore resolves on the write and is **best-effort** — it is applied once audio has flowed, and
+   * this seam cannot say when. It is not a way to speak unprompted.
+   * @param content - plain text, non-empty and within {@link MAX_APPEND_CHARS}.
+   * @param delegationId - the delegation this answers, or `undefined` for best-effort session context.
+   */
+  appendCommentary(content: string, delegationId?: string): Promise<void>
+
+  /**
+   * Add context the model may use **without speaking it** — progress, facts, intermediate state.
+   *
+   * With no `delegationId` this resolves on the write and is best-effort, for the reason recorded on
+   * {@link appendCommentary}: the provider does not acknowledge a session-wide append.
+   * @param content - plain text, non-empty and within {@link MAX_APPEND_CHARS}.
+   * @param delegationId - the delegation this relates to, or `undefined` for best-effort session context.
+   */
+  appendThinking(content: string, delegationId?: string): Promise<void>
+
+  /**
+   * Steer the live conversation's behaviour (tone, brevity, policy) without speaking anything.
+   *
+   * With no `delegationId` this resolves on the write and is best-effort, for the reason recorded on
+   * {@link appendCommentary}.
+   * @param content - plain text, non-empty and within {@link MAX_APPEND_CHARS}.
+   * @param delegationId - `undefined` for best-effort session-wide steering.
+   */
+  appendInstructions(content: string, delegationId?: string): Promise<void>
+
+  /**
+   * End the session and release the transport. Idempotent.
+   * @returns a promise settling once the transport is released.
+   */
+  close(): Promise<void>
+}
+
+/**
+ * Upper bound, in characters, on one context append.
+ *
+ * The provider's real limit is **500 tokens**, which this seam cannot count without binding to a
+ * tokenizer it does not own. The character ceiling is therefore a deliberate conservative proxy:
+ * it is enforced here so that an over-long append fails locally with a coded error rather than
+ * halfway through a live conversation. Exact token accounting belongs to the adapter.
+ */
+export const MAX_APPEND_CHARS = 2000