dsh-realtime-audio-ws 0.2.2 → 0.2.4

package/lib/strip.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The strip: the panel this plugin puts in the host's own page.
+ *
+ * S2 story 3. Until it existed the plugin was driven from a `globalThis` key in a devtools console, and the
+ * roadmap's judgement on that was blunt — *a plugin driven from a console global will not be installed by
+ * anyone*. What changes is not decoration: the on-switch moves into the page, and `sessionId`, which cost
+ * two restarts and a false lead to change, becomes a picker.
+ *
+ * ## Where the behaviour lives, and why not here
+ *
+ * This module mints **rows** for `webserver/index-inject` — the door the page already receives its settings
+ * through. Two of the six row kinds carry UI: `html` for raw markup, `script` for an inline classic script.
+ * So the markup is here and the bootstrap is here, and **the panel's logic is not**: everything that
+ * decides what to render and what a button does lives in the client bundle
+ * (`src/client/index.ts`), where it is covered by tests. A panel implemented inside an injected string is a
+ * feature nothing can execute in CI, which is the same defect class as a build artefact no test reads.
+ *
+ * The bootstrap is therefore three statements, and it is still *executed* by a test — as a function with a
+ * fake scope — so the injected code is not exempt from the gate just because it is shipped as text.
+ *
+ * ## Two ways in, deliberately
+ *
+ * The bundle mounts the panel when it applies, and the injected script mounts it again in case it lands
+ * first. Both are idempotent, because the order between the module table and the body rows is not something
+ * this package controls, and a panel that appears only when two independent orderings agree is a panel that
+ * appears only on the author's machine.
+ *
+ * @module dsh-realtime-audio-ws/strip
+ */
+import type { InjectedRow } from './injection.ts';
+/** The element the panel mounts on. Duplicated in the client half, which cannot import it. */
+export declare const STRIP_ELEMENT_ID = "dsh-realtime-strip";
+/**
+ * The panel's container, as markup.
+ *
+ * Fixed to the bottom right, inheriting the host's font and colour rather than inventing a second visual
+ * language beside it — but **opaque**, and that is a correction rather than a taste. This panel sits over
+ * the host's own text, so a translucent wash lets the page show through and the two become unreadable
+ * together: two texts superimposed, neither of them legible. That was reported from a screenshot of the
+ * running app, which is the only way it was ever going to be found — nothing in a DOM test can see what is
+ * *behind* the panel.
+ *
+ * `Canvas` is the theme's own surface colour, so the panel follows light or dark mode without naming a
+ * palette of its own, and the 6% tint of the inherited colour keeps the surface from reading as a hole
+ * punched in the page. The soft shadow says it sits above the page — not a border, which would be visual
+ * noise around a strip whose job is to be glanced at.
+ * @returns one `html` row's payload.
+ */
+export declare function stripMarkup(): string;
+/**
+ * The bootstrap the page runs after the markup.
+ *
+ * It calls the bundle's own `mount`, and does nothing when the bundle has not been materialised yet — in
+ * which case the bundle mounts the panel itself when it applies, or this is called again on
+ * `DOMContentLoaded`. Nothing here decides anything about the panel; it is a doorbell.
+ * @returns one `script` row's payload.
+ */
+export declare function stripBootstrap(): string;
+/**
+ * The two rows this plugin contributes for its panel.
+ *
+ * `body` placement for both: the strip belongs to the page's chrome rather than to its head, and a `body`
+ * row is rendered after the module queue's own `head` rows, which is the ordering the bundle's bootstrap
+ * expects.
+ *
+ * Neither payload may contain a closing script or style tag — the table's own contract, because the row is
+ * spliced into the document text — and a test asserts that for both, alongside executing the bootstrap.
+ * @returns the rows, in the order they must execute.
+ */
+export declare function stripRows(): InjectedRow[];
+//# sourceMappingURL=strip.d.ts.map

package/lib/strip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strip.d.ts","sourceRoot":"","sources":["../src/strip.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAEjD,8FAA8F;AAC9F,eAAO,MAAM,gBAAgB,uBAAuB,CAAA;AAEpD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAUpC;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAQvC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,IAAI,WAAW,EAAE,CAKzC"}

package/lib/strip.js

@@ -0,0 +1,93 @@
+/**
+ * The strip: the panel this plugin puts in the host's own page.
+ *
+ * S2 story 3. Until it existed the plugin was driven from a `globalThis` key in a devtools console, and the
+ * roadmap's judgement on that was blunt — *a plugin driven from a console global will not be installed by
+ * anyone*. What changes is not decoration: the on-switch moves into the page, and `sessionId`, which cost
+ * two restarts and a false lead to change, becomes a picker.
+ *
+ * ## Where the behaviour lives, and why not here
+ *
+ * This module mints **rows** for `webserver/index-inject` — the door the page already receives its settings
+ * through. Two of the six row kinds carry UI: `html` for raw markup, `script` for an inline classic script.
+ * So the markup is here and the bootstrap is here, and **the panel's logic is not**: everything that
+ * decides what to render and what a button does lives in the client bundle
+ * (`src/client/index.ts`), where it is covered by tests. A panel implemented inside an injected string is a
+ * feature nothing can execute in CI, which is the same defect class as a build artefact no test reads.
+ *
+ * The bootstrap is therefore three statements, and it is still *executed* by a test — as a function with a
+ * fake scope — so the injected code is not exempt from the gate just because it is shipped as text.
+ *
+ * ## Two ways in, deliberately
+ *
+ * The bundle mounts the panel when it applies, and the injected script mounts it again in case it lands
+ * first. Both are idempotent, because the order between the module table and the body rows is not something
+ * this package controls, and a panel that appears only when two independent orderings agree is a panel that
+ * appears only on the author's machine.
+ *
+ * @module dsh-realtime-audio-ws/strip
+ */
+/** The element the panel mounts on. Duplicated in the client half, which cannot import it. */
+export const STRIP_ELEMENT_ID = 'dsh-realtime-strip';
+/**
+ * The panel's container, as markup.
+ *
+ * Fixed to the bottom right, inheriting the host's font and colour rather than inventing a second visual
+ * language beside it — but **opaque**, and that is a correction rather than a taste. This panel sits over
+ * the host's own text, so a translucent wash lets the page show through and the two become unreadable
+ * together: two texts superimposed, neither of them legible. That was reported from a screenshot of the
+ * running app, which is the only way it was ever going to be found — nothing in a DOM test can see what is
+ * *behind* the panel.
+ *
+ * `Canvas` is the theme's own surface colour, so the panel follows light or dark mode without naming a
+ * palette of its own, and the 6% tint of the inherited colour keeps the surface from reading as a hole
+ * punched in the page. The soft shadow says it sits above the page — not a border, which would be visual
+ * noise around a strip whose job is to be glanced at.
+ * @returns one `html` row's payload.
+ */
+export function stripMarkup() {
+    return [
+        `<div id="${STRIP_ELEMENT_ID}"`,
+        ' style="position:fixed;right:12px;bottom:12px;z-index:40;',
+        'max-width:26rem;max-height:60vh;overflow:auto;padding:10px 12px;',
+        'font:inherit;color:inherit;line-height:1.4;',
+        'background:color-mix(in srgb, Canvas 94%, currentColor);',
+        'box-shadow:0 4px 16px rgb(0 0 0 / 0.18);border-radius:10px">',
+        '</div>',
+    ].join('');
+}
+/**
+ * The bootstrap the page runs after the markup.
+ *
+ * It calls the bundle's own `mount`, and does nothing when the bundle has not been materialised yet — in
+ * which case the bundle mounts the panel itself when it applies, or this is called again on
+ * `DOMContentLoaded`. Nothing here decides anything about the panel; it is a doorbell.
+ * @returns one `script` row's payload.
+ */
+export function stripBootstrap() {
+    return [
+        ';(function () {',
+        "  function mount() { var G = globalThis.__dshRealtimeAudio; if (G && typeof G.mount === 'function') G.mount() }",
+        '  mount()',
+        "  if (typeof document !== 'undefined' && document.readyState === 'loading') document.addEventListener('DOMContentLoaded', mount)",
+        '})()',
+    ].join('\n');
+}
+/**
+ * The two rows this plugin contributes for its panel.
+ *
+ * `body` placement for both: the strip belongs to the page's chrome rather than to its head, and a `body`
+ * row is rendered after the module queue's own `head` rows, which is the ordering the bundle's bootstrap
+ * expects.
+ *
+ * Neither payload may contain a closing script or style tag — the table's own contract, because the row is
+ * spliced into the document text — and a test asserts that for both, alongside executing the bootstrap.
+ * @returns the rows, in the order they must execute.
+ */
+export function stripRows() {
+    return [
+        { kind: 'html', placement: 'body', html: stripMarkup() },
+        { kind: 'script', placement: 'body', text: stripBootstrap() },
+    ];
+}
+//# sourceMappingURL=strip.js.map

package/lib/strip.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"strip.js","sourceRoot":"","sources":["../src/strip.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAIH,8FAA8F;AAC9F,MAAM,CAAC,MAAM,gBAAgB,GAAG,oBAAoB,CAAA;AAEpD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,WAAW;IACzB,OAAO;QACL,YAAY,gBAAgB,GAAG;QAC/B,2DAA2D;QAC3D,kEAAkE;QAClE,6CAA6C;QAC7C,0DAA0D;QAC1D,8DAA8D;QAC9D,QAAQ;KACT,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;AACZ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc;IAC5B,OAAO;QACL,iBAAiB;QACjB,iHAAiH;QACjH,WAAW;QACX,kIAAkI;QAClI,MAAM;KACP,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACd,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,SAAS;IACvB,OAAO;QACL,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE;QACxD,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,EAAE;KAC9D,CAAA;AACH,CAAC"}

package/lib/types.d.ts

@@ -61,6 +61,14 @@ export interface RealtimeAudioWsConfig {
      * more to a stranger than an empty socket.
      */
     readonly diagnosticsPath: string;
+    /**
+     * File the journal is appended to, one JSON object per line. Empty means no file.
+     *
+     * Off by default, and named by the deployment that wants a recording: the journal is held in memory and
+     * served over a route that wants a capability token, so a deployment that needs the record to outlive the
+     * process — or to be handed to somebody else — says so here.
+     */
+    readonly journalPath: string;
 }
 /**
  * The slice of a WebSocket this package uses, described structurally.
@@ -74,7 +82,7 @@ export interface RealtimeAudioWsConfig {
  * `Uint8Array`.
  */
 export interface AudioSocket {
-    send(data: Uint8Array): void;
+    send(data: Uint8Array | string): void;
     close(code?: number, reason?: string): void;
     terminate(): void;
     on(event: 'message', listener: (data: unknown, isBinary: boolean) => void): unknown;

package/lib/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,0GAA0G;AAC1G,eAAO,MAAM,YAAY,wBAAwB,CAAA;AAEjD,6FAA6F;AAC7F,eAAO,MAAM,uBAAuB,SAAU,CAAA;AAE9C,sFAAsF;AACtF,eAAO,MAAM,uBAAuB,IAAI,CAAA;AAExC,0GAA0G;AAC1G,eAAO,MAAM,+BAA+B,OAAO,CAAA;AAEnD;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,8BAA8B,CAAA;AAEnE,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B;;;;;;;;OAQG;IACH,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAA;IACtC;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;CACjC;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAAA;IAC5B,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3C,SAAS,IAAI,IAAI,CAAA;IACjB,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAA;IACnF,EAAE,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,OAAO,CAAA;CAC9E"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,0GAA0G;AAC1G,eAAO,MAAM,YAAY,wBAAwB,CAAA;AAEjD,6FAA6F;AAC7F,eAAO,MAAM,uBAAuB,SAAU,CAAA;AAE9C,sFAAsF;AACtF,eAAO,MAAM,uBAAuB,IAAI,CAAA;AAExC,0GAA0G;AAC1G,eAAO,MAAM,+BAA+B,OAAO,CAAA;AAEnD;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,8BAA8B,CAAA;AAEnE,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B;;;;;;;;OAQG;IACH,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAA;IACtC;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;IAChC;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC7B;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAAA;IACrC,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3C,SAAS,IAAI,IAAI,CAAA;IACjB,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAA;IACnF,EAAE,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,OAAO,CAAA;CAC9E"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-realtime-audio-ws",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "The host end of the client half's transport: a WebSocket upgrade route that bridges microphone audio in and agent speech out.",
   "type": "module",
   "main": "lib/index.js",
@@ -52,7 +52,8 @@
   },
   "dependencies": {
     "ws": "^8.22.0",
-    "dsh-realtime-agent": "^0.2.6"
+    "dsh-realtime-agent": "^0.2.8",
+    "dsh-realtime": "^0.2.5"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.3",

package/src/bridge.ts

@@ -14,6 +14,20 @@ export interface AudioSocketBridgeDeps {
   readonly subscribeAudio: (listener: (pcm16: Uint8Array) => void) => () => void
   /** Longest inbound frame accepted, in bytes. */
   readonly maxFrameBytes: number
+  /**
+   * Handle one **control frame** — a text frame on this socket.
+   *
+   * Until S2 story 2 a text frame was not part of this contract, and the comment that said so was right
+   * about the wire as it was: the socket carried PCM16 in both directions and nothing else. It now
+   * carries a channel too, because it is the only duplex connection the client already holds, and one
+   * text frame in / one text frame out is a smaller contract than a second route with its own
+   * authentication would have been.
+   *
+   * `reply` writes exactly one text frame back, and silently drops it once the socket is gone: a control
+   * handler is asynchronous, and a reply to a closed socket would throw from inside a promise nobody
+   * awaits.
+   */
+  readonly onControl: (frame: string, reply: (text: string) => void) => void
   /** Called exactly once when the bridge stops, however it stops. */
   readonly onDetach: () => void
 }
@@ -35,6 +49,22 @@ export function toBytes(data: unknown): Uint8Array {
   return new Uint8Array(Buffer.from(data as ArrayBufferLike))
 }
 
+/**
+ * Normalise a `ws` message payload to text.
+ *
+ * The same three shapes {@link toBytes} handles, decoded as UTF-8 — a control frame arrives as a Buffer
+ * whichever way it was framed, and a fragmented one as an array of them.
+ *
+ * @param data - the payload as `ws` delivered it.
+ * @returns the payload as text.
+ */
+export function toText(data: unknown): string {
+  if (typeof data === 'string') return data
+  if (Array.isArray(data)) return Buffer.concat(data as readonly Uint8Array[]).toString('utf8')
+  if (data instanceof Uint8Array) return Buffer.from(data.buffer, data.byteOffset, data.byteLength).toString('utf8')
+  return Buffer.from(data as ArrayBufferLike).toString('utf8')
+}
+
 /**
  * Wire one accepted socket to the agent's audio events.
  *
@@ -61,10 +91,36 @@ export function attachAudioSocket(client: AudioSocket, deps: AudioSocketBridgeDe
     deps.onDetach()
   }
 
+  /**
+   * Answer one control frame, if the socket is still there.
+   *
+   * The guard is here rather than at the call site because this is the only place that knows whether the
+   * bridge is still live, and because a control handler settles asynchronously: a reply that arrives after
+   * the socket went away must be dropped, not thrown.
+   *
+   * **Total**, including the write: a socket can die between the check above and the send, and a throw here
+   * would escape into a promise nobody awaits — and, in the plugin, would break the reply queue for every
+   * frame behind it.
+   * @param text - the reply frame.
+   */
+  const reply = (text: string): void => {
+    if (stopped) return
+    try {
+      client.send(text)
+    } catch {
+      stop()
+    }
+  }
+
   client.on('message', (data, isBinary) => {
-    // A text frame is not part of this contract. Ignoring one is cheaper than closing the connection and
-    // no less correct: nothing on this wire is JSON.
-    if (!isBinary) return
+    // A **text** frame is a control frame. This is the deliberate widening of the contract that used to
+    // say the opposite: the socket is the one duplex connection the client already holds, and a control
+    // plane that needs a second route with a second authentication is a control plane nobody builds.
+    // Checked before the audio path, because a text frame is never audio whatever it contains.
+    if (!isBinary) {
+      deps.onControl(toText(data), reply)
+      return
+    }
     const pcm16 = toBytes(data)
     if (pcm16.byteLength > deps.maxFrameBytes) {
       // 1009 = message too big. `ws` enforces its own `maxPayload` first, so reaching this means the bound