dsh-realtime 0.1.1 → 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

@@ -1 +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;;EAE3D,CAAA;AAEF,2CAA2C;AAC3C,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,OAAO,oBAAoB,CAAC,CAAA;AAEhG;;;;;GAKG;AACH,qBAAa,aAAc,SAAQ,KAAK;IACtC,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAA;IAEhC;;;;OAIG;IACH,YAAY,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,EAAE,OAAO,CAAC,EAAE,YAAY,EAU3E;CACF"}
+{"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

@@ -1 +1 @@
-{"version":3,"file":"error.js","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,gDAAgD;AAChD,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC,MAAM,CAAC;IAChD,iEAAiE;IACjE,gBAAgB,EAAE,kBAAkB;IACpC,yEAAyE;IACzE,kBAAkB,EAAE,oBAAoB;IACxC,yEAAyE;IACzE,qBAAqB,EAAE,uBAAuB;IAC9C,wDAAwD;IACxD,UAAU,EAAE,YAAY;IACxB,mEAAmE;IACnE,cAAc,EAAE,gBAAgB;IAChC,2CAA2C;IAC3C,cAAc,EAAE,gBAAgB;IAChC,iGAAiG;IACjG,kBAAkB,EAAE,oBAAoB;IACxC,iGAAiG;IACjG,cAAc,EAAE,gBAAgB;IAChC,2DAA2D;IAC3D,iBAAiB,EAAE,mBAAmB;CACvC,CAAC,CAAA;AAKF;;;;;GAKG;AACH,MAAM,OAAO,aAAc,SAAQ,KAAK;IACtC,+DAA+D;IACtD,IAAI,CAAmB;IAEhC;;;;OAIG;IACH,YAAY,OAAe,EAAE,IAAuB,EAAE,OAAsB;QAC1E,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxD,MAAM,IAAI,SAAS,CAAC,kDAAkD,CAAC,CAAA;QACzE,CAAC;QACD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAClD,MAAM,IAAI,SAAS,CAAC,+CAA+C,CAAC,CAAA;QACtE,CAAC;QACD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;QACvB,IAAI,CAAC,IAAI,GAAG,eAAe,CAAA;QAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;CACF"}
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../src/error.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

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

package/lib/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAsLH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAA"}
+{"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.1",
+  "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",

package/src/error.ts

@@ -27,11 +27,87 @@ 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',
 })
 
 /** 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.
  *
@@ -42,20 +118,27 @@ 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`.
+   * @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 }) {
     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/types.ts

@@ -159,22 +159,34 @@ export interface RealtimeSession {
 
   /**
    * 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>