dsh-realtime-audio-ws 0.2.0 → 0.2.1

package/lib/diagnostics.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The diagnostics route: the journal, served as JSON over the web server's route registry.
+ *
+ * S1 story 4. It exists so a failure can be read *after* the fact without a console attached — which is
+ * the whole cost this project kept paying, an evening spent inferring a reason that was never written
+ * down anywhere.
+ *
+ * ## The access policy is the audio route's, reused rather than re-derived
+ *
+ * The host's route registry "knows no harness concepts" and its handlers own the full response, so
+ * nothing upstream answers the authentication question for us. The audio route already answers it in
+ * this package: ask the connection service, and let the process's capability token override a refusal,
+ * because the desktop app's page is served from `dsh-app://app` and is therefore cross-site to loopback
+ * — it can never carry the harness's `SameSite=Strict` cookie. This route asks in the same position with
+ * the same token: one policy, two doors. Inventing a second check here is how two schemes drift until
+ * one of them is found holding the weaker answer.
+ *
+ * ## What it deliberately does not do
+ *
+ * It does not redact on the way out. The journal redacts on **write**, so there is no unredacted value
+ * in the buffer to serve and no second step for a later edit to forget. A route that redacted at the
+ * boundary would look safer and be strictly worse: the secret would already be retained, in memory and
+ * in whatever the process dumps.
+ *
+ * @module dsh-realtime-audio-ws/diagnostics
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Journal } from 'dsh-realtime';
+/**
+ * The slice of the journal this route reads.
+ *
+ * Typed as the public surface rather than as the class: `Journal` exists as two declarations in this
+ * repository — built `lib/` and `src/` — and a class with a private member is nominally typed, so the
+ * two are not assignable to each other even though they are the same code.
+ */
+export type DiagnosticsJournal = Pick<Journal, 'snapshot' | 'size' | 'oldestSeq'>;
+/** What the route needs from the plugin that owns it. */
+export interface DiagnosticsDeps {
+    /** Absolute pathname to claim, no trailing slash — the registry's own contract. */
+    readonly path: string;
+    /** This process's capability token, the same one the audio route publishes to the page. */
+    readonly token: string;
+    /** The connection service's verdict for one request. */
+    readonly rejectionFor: (request: {
+        headers: IncomingMessage['headers'];
+    }) => 401 | 403 | undefined;
+    /** The journal to serve. */
+    readonly journal: DiagnosticsJournal;
+}
+/** A route the host's registry accepts, described structurally as this package describes the registry. */
+export interface DiagnosticsRoute {
+    readonly kind: 'exact';
+    readonly path: string;
+    readonly handler: (req: IncomingMessage, res: ServerResponse) => void;
+}
+/**
+ * Build the diagnostics route.
+ * @param deps - the path to claim, this process's token, the connection service's verdict, and the journal.
+ * @returns the route registration, ready for `webServer.register`.
+ */
+export declare function diagnosticsRoute(deps: DiagnosticsDeps): DiagnosticsRoute;
+//# sourceMappingURL=diagnostics.d.ts.map

package/lib/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../src/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAChE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAG3C;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,IAAI,CAAC,OAAO,EAAE,UAAU,GAAG,MAAM,GAAG,WAAW,CAAC,CAAA;AAEjF,yDAAyD;AACzD,MAAM,WAAW,eAAe;IAC9B,mFAAmF;IACnF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,2FAA2F;IAC3F,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,wDAAwD;IACxD,QAAQ,CAAC,YAAY,EAAE,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,eAAe,CAAC,SAAS,CAAC,CAAA;KAAE,KAAK,GAAG,GAAG,GAAG,GAAG,SAAS,CAAA;IAClG,4BAA4B;IAC5B,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAA;CACrC;AAED,0GAA0G;AAC1G,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,KAAK,IAAI,CAAA;CACtE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,eAAe,GAAG,gBAAgB,CAmBxE"}

package/lib/diagnostics.js

@@ -0,0 +1,66 @@
+/**
+ * The diagnostics route: the journal, served as JSON over the web server's route registry.
+ *
+ * S1 story 4. It exists so a failure can be read *after* the fact without a console attached — which is
+ * the whole cost this project kept paying, an evening spent inferring a reason that was never written
+ * down anywhere.
+ *
+ * ## The access policy is the audio route's, reused rather than re-derived
+ *
+ * The host's route registry "knows no harness concepts" and its handlers own the full response, so
+ * nothing upstream answers the authentication question for us. The audio route already answers it in
+ * this package: ask the connection service, and let the process's capability token override a refusal,
+ * because the desktop app's page is served from `dsh-app://app` and is therefore cross-site to loopback
+ * — it can never carry the harness's `SameSite=Strict` cookie. This route asks in the same position with
+ * the same token: one policy, two doors. Inventing a second check here is how two schemes drift until
+ * one of them is found holding the weaker answer.
+ *
+ * ## What it deliberately does not do
+ *
+ * It does not redact on the way out. The journal redacts on **write**, so there is no unredacted value
+ * in the buffer to serve and no second step for a later edit to forget. A route that redacted at the
+ * boundary would look safer and be strictly worse: the secret would already be retained, in memory and
+ * in whatever the process dumps.
+ *
+ * @module dsh-realtime-audio-ws/diagnostics
+ */
+import { tokenFromUrl, verdictFor } from './injection.js';
+/**
+ * Build the diagnostics route.
+ * @param deps - the path to claim, this process's token, the connection service's verdict, and the journal.
+ * @returns the route registration, ready for `webServer.register`.
+ */
+export function diagnosticsRoute(deps) {
+    return {
+        kind: 'exact',
+        path: deps.path,
+        handler: (req, res) => {
+            const rejection = verdictFor(deps.rejectionFor(req), tokenFromUrl(req.url), deps.token);
+            if (rejection !== undefined) {
+                // The status carries the verdict the connection service actually gave, so a reader can tell a
+                // missing credential from a refused one rather than guessing from a generic failure.
+                send(res, rejection, { error: rejection === 401 ? 'unauthorized' : 'forbidden' });
+                return;
+            }
+            const entries = deps.journal.snapshot();
+            // `size` and `oldestSeq` travel with the entries rather than being left for the reader to infer:
+            // a truncated buffer and an idle one are the same empty-looking list otherwise, and the sequence
+            // number is the only thing that separates "nothing happened" from "the buffer rolled over".
+            send(res, 200, { size: deps.journal.size, oldestSeq: deps.journal.oldestSeq, entries });
+        },
+    };
+}
+/**
+ * Write one JSON response.
+ *
+ * `no-store` on both branches. This response is a picture of a moving buffer, and a cached one would be
+ * read as current — the same class of mistake as a journal that cannot show its own eviction.
+ * @param res - the response this handler owns.
+ * @param status - HTTP status to write.
+ * @param body - value to serialise as the JSON body.
+ */
+function send(res, status, body) {
+    res.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'no-store' });
+    res.end(JSON.stringify(body));
+}
+//# sourceMappingURL=diagnostics.js.map

package/lib/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../src/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AA8BzD;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAqB;IACpD,OAAO;QACL,IAAI,EAAE,OAAO;QACb,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,OAAO,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;YACpB,MAAM,SAAS,GAAG,UAAU,CAAC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAA;YACvF,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;gBAC5B,8FAA8F;gBAC9F,qFAAqF;gBACrF,IAAI,CAAC,GAAG,EAAE,SAAS,EAAE,EAAE,KAAK,EAAE,SAAS,KAAK,GAAG,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAA;gBACjF,OAAM;YACR,CAAC;YACD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAA;YACvC,iGAAiG;YACjG,iGAAiG;YACjG,4FAA4F;YAC5F,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,OAAO,EAAE,CAAC,CAAA;QACzF,CAAC;KACF,CAAA;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,IAAI,CAAC,GAAmB,EAAE,MAAc,EAAE,IAAa;IAC9D,GAAG,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,eAAe,EAAE,UAAU,EAAE,CAAC,CAAA;IAC1F,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAA;AAC/B,CAAC"}

package/lib/index.d.ts

@@ -9,13 +9,26 @@
  * connection services exist, so a composition without a web stack gets a row that visibly waits rather
  * than one that loads and silently claims nothing. `packages/realtime-audio-ws/tests/plugin.spec.ts` proves
  * the functional path against a real socket with both services present.
+ *
+ * It claims **two** routes on that registry, and one policy authenticates both: the WebSocket upgrade
+ * that carries audio, and the JSON diagnostics route that serves the journal. See `./diagnostics.ts` for
+ * why the second reuses the first's check rather than deriving its own.
  */
 import Schema from '@deepseek-ai/schemastery';
 import type { Context } from '@deepseek-ai/cordis';
 import { type RealtimeAudioWsConfig } from './types.ts';
 export * from './types.ts';
+/**
+ * The query parameter carrying the capability token.
+ *
+ * Published with the route rather than kept internal: nothing can address the route without it, and a
+ * consumer restating the literal is a consumer that drifts. It is one string; the rest of `injection.ts`
+ * stays where it is.
+ */
+export { TOKEN_PARAM } from './injection.ts';
 export { attachAudioSocket, toBytes, type AudioSocketBridgeDeps } from './bridge.ts';
 export { createUpgradeAcceptor, rejectUpgrade, type UpgradeAcceptor } from './upgrade.ts';
+export { diagnosticsRoute, type DiagnosticsDeps, type DiagnosticsJournal, type DiagnosticsRoute } from './diagnostics.ts';
 /** Plugin name. */
 export declare const name = "realtime-audio-ws";
 export declare const Config: Schema<Schemastery.ObjectS<NoInfer<{
@@ -23,11 +36,13 @@ export declare const Config: Schema<Schemastery.ObjectS<NoInfer<{
     maxFrameBytes: Schema<number, number, "defined">;
     maxConnections: Schema<number, number, "defined">;
     openSessionOnConnect: Schema<boolean, boolean, "defined">;
+    diagnosticsPath: Schema<string, string, "defined">;
 }>>, Schemastery.ObjectT<NoInfer<{
     path: Schema<string, string, "defined">;
     maxFrameBytes: Schema<number, number, "defined">;
     maxConnections: Schema<number, number, "defined">;
     openSessionOnConnect: Schema<boolean, boolean, "defined">;
+    diagnosticsPath: Schema<string, string, "defined">;
 }>>, "plain">;
 export declare function apply(ctx: Context, config: RealtimeAudioWsConfig): void;
 //# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,MAAM,MAAM,0BAA0B,CAAA;AAC7C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAelD,OAAO,EAML,KAAK,qBAAqB,EAC3B,MAAM,YAAY,CAAA;AAEnB,cAAc,YAAY,CAAA;AAC1B,OAAO,EAAE,iBAAiB,EAAE,OAAO,EAAE,KAAK,qBAAqB,EAAE,MAAM,aAAa,CAAA;AACpF,OAAO,EAAE,qBAAqB,EAAE,aAAa,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAA;AAEzF,mBAAmB;AACnB,eAAO,MAAM,IAAI,sBAAsB,CAAA;AAEvC,eAAO,MAAM,MAAM;;;;;;;;;;aAQjB,CAAA;AA4BF,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,qBAAqB,GAAG,IAAI,CA+EvE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,MAAM,MAAM,0BAA0B,CAAA;AAC7C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAgBlD,OAAO,EAOL,KAAK,qBAAqB,EAC3B,MAAM,YAAY,CAAA;AAEnB,cAAc,YAAY,CAAA;AAC1B;;;;;;GAMG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAC5C,OAAO,EAAE,iBAAiB,EAAE,OAAO,EAAE,KAAK,qBAAqB,EAAE,MAAM,aAAa,CAAA;AACpF,OAAO,EAAE,qBAAqB,EAAE,aAAa,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAA;AACzF,OAAO,EAAE,gBAAgB,EAAE,KAAK,eAAe,EAAE,KAAK,kBAAkB,EAAE,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAEzH,mBAAmB;AACnB,eAAO,MAAM,IAAI,sBAAsB,CAAA;AAEvC,eAAO,MAAM,MAAM;;;;;;;;;;;;aASjB,CAAA;AAqCF,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,qBAAqB,GAAG,IAAI,CA6GvE"}

package/lib/index.js

@@ -9,15 +9,29 @@
  * connection services exist, so a composition without a web stack gets a row that visibly waits rather
  * than one that loads and silently claims nothing. `packages/realtime-audio-ws/tests/plugin.spec.ts` proves
  * the functional path against a real socket with both services present.
+ *
+ * It claims **two** routes on that registry, and one policy authenticates both: the WebSocket upgrade
+ * that carries audio, and the JSON diagnostics route that serves the journal. See `./diagnostics.ts` for
+ * why the second reuses the first's check rather than deriving its own.
  */
 import Schema from '@deepseek-ai/schemastery';
 import { attachAudioSocket } from './bridge.js';
+import { diagnosticsRoute } from './diagnostics.js';
 import { createRouteToken, routeAuthority, routeInjectionRow, tokenFromUrl, verdictFor, } from './injection.js';
 import { createUpgradeAcceptor, rejectUpgrade } from './upgrade.js';
-import { DEFAULT_MAX_CONNECTIONS, DEFAULT_MAX_FRAME_BYTES, DEFAULT_OPEN_SESSION_ON_CONNECT, DEFAULT_PATH, } from './types.js';
+import { DEFAULT_DIAGNOSTICS_PATH, DEFAULT_MAX_CONNECTIONS, DEFAULT_MAX_FRAME_BYTES, DEFAULT_OPEN_SESSION_ON_CONNECT, DEFAULT_PATH, } from './types.js';
 export * from './types.js';
+/**
+ * The query parameter carrying the capability token.
+ *
+ * Published with the route rather than kept internal: nothing can address the route without it, and a
+ * consumer restating the literal is a consumer that drifts. It is one string; the rest of `injection.ts`
+ * stays where it is.
+ */
+export { TOKEN_PARAM } from './injection.js';
 export { attachAudioSocket, toBytes } from './bridge.js';
 export { createUpgradeAcceptor, rejectUpgrade } from './upgrade.js';
+export { diagnosticsRoute } from './diagnostics.js';
 /** Plugin name. */
 export const name = 'realtime-audio-ws';
 export const Config = Schema.object({
@@ -28,13 +42,20 @@ export const Config = Schema.object({
     // boot with nobody asking, which is why it is false. This one opens a session because someone connected a
     // microphone: a connection takes an explicit action, an authenticated one, and its absence is silence.
     openSessionOnConnect: Schema.boolean().default(DEFAULT_OPEN_SESSION_ON_CONNECT),
+    diagnosticsPath: Schema.string().default(DEFAULT_DIAGNOSTICS_PATH),
 });
 export function apply(ctx, config) {
-    ctx.inject(['connection', 'webServer'], (injected) => {
+    ctx.inject(['connection', 'webServer', 'realtime'], (injected) => {
         const services = injected;
         const acceptor = createUpgradeAcceptor(config.maxFrameBytes);
         const clients = new Set();
         const token = createRouteToken();
+        const journal = injected.realtime.journal;
+        // The token travels in a URL query, and this route records request targets, so the journal has to be
+        // able to redact it before it records one. This is exactly why `addSecrets` is additive instead of a
+        // constructor argument: the plugin that mints the token is the only one that can name it, and it
+        // mints it here, after the journal already exists.
+        journal.addSecrets([token]);
         // The injection event is declared by `@deepseek-ai/dsh-host-webserver`, which this package deliberately
         // does not import: importing it would augment `Context` with a second declaration of `webServer` and
         // turn the structural dependency above into a compile error. The name is cast at this one boundary.
@@ -46,6 +67,12 @@ export function apply(ctx, config) {
             onInjection('webserver/index-inject', (table) => {
                 table.push(routeInjectionRow(config.path, routeAuthority(services.webServer.config?.host, services.webServer.listenedPort), token));
             });
+            const unregisterDiagnostics = services.webServer.register(diagnosticsRoute({
+                path: config.diagnosticsPath,
+                token,
+                rejectionFor: (request) => services.connection.requestRejection(request),
+                journal,
+            }));
             const unregister = services.webServer.registerUpgrade({
                 path: config.path,
                 handler: (req, socket, head) => {
@@ -59,18 +86,34 @@ export function apply(ctx, config) {
                     // from `dsh-app://app`, so its requests to loopback are cross-site and the harness's
                     // `SameSite=Strict` cookie cannot travel; without the token that page is refused forever, however
                     // correct the rest of the client half is.
+                    // Normalised once, at the caller's edge, so no record below repeats the check. `node:http`
+                    // always reports a target on a server request; the type admits `undefined` for client requests,
+                    // which this handler cannot see.
+                    const target = req.url ?? '';
                     const rejection = verdictFor(services.connection.requestRejection(req), tokenFromUrl(req.url), token);
                     if (rejection !== undefined) {
+                        // The verdict only, and no target. A valid token is never rejected — it overrides the
+                        // refusal — so any target recorded here belongs to something else, and a wrong token is
+                        // still a credential. Retaining a caller's secret in order to log a refusal is a worse trade
+                        // than losing which path was probed.
+                        journal.record('socket.rejected', { verdict: String(rejection) });
                         rejectUpgrade(socket, rejection);
                         return;
                     }
                     acceptor.handleUpgrade(req, socket, head, (client) => {
                         if (clients.size >= config.maxConnections) {
                             // 1013 = try again later. Closing the newcomer leaves the existing microphone live.
+                            journal.record('socket.rejected', { verdict: '1013', reason: 'busy' });
                             client.close(1013, 'busy');
                             return;
                         }
                         clients.add(client);
+                        // The target here, because an accepted request is the one place this process's own token
+                        // travels: the app page presents it in the query precisely because it cannot carry the
+                        // cookie. The journal redacts it on write — which is what the token was added to the journal's
+                        // secrets for, and the reason that has to be additive rather than a constructor argument,
+                        // since the token does not exist until this plugin applies.
+                        journal.record('socket.accepted', { clients: String(clients.size), url: target });
                         // Ask for the session before the bridge goes in, so the first frames are written into a session
                         // that is being opened rather than dropped by the mic seam's no-session rule.
                         if (config.openSessionOnConnect)
@@ -81,6 +124,7 @@ export function apply(ctx, config) {
                             maxFrameBytes: config.maxFrameBytes,
                             onDetach: () => {
                                 clients.delete(client);
+                                journal.record('socket.closed', { clients: String(clients.size) });
                                 // The last client leaving ends the session. This also covers the transport's own disposal,
                                 // which terminates its clients — so a profile reload does not leave a session nobody holds.
                                 if (config.openSessionOnConnect && clients.size === 0)
@@ -92,6 +136,7 @@ export function apply(ctx, config) {
             });
             return async () => {
                 unregister();
+                unregisterDiagnostics();
                 for (const client of clients)
                     client.terminate();
                 clients.clear();

package/lib/index.js.map

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

package/lib/types.d.ts

@@ -19,6 +19,14 @@ export declare const DEFAULT_MAX_FRAME_BYTES = 480000;
 export declare const DEFAULT_MAX_CONNECTIONS = 1;
 /** Whether an authenticated connection asks the agent to open the voice session. See the config field. */
 export declare const DEFAULT_OPEN_SESSION_ON_CONNECT = true;
+/**
+ * Default pathname the diagnostics route claims.
+ *
+ * A fixed API path in spirit, but a validated config field like the audio route's — so a composition
+ * that already owns this path can move it deliberately rather than discovering the collision when the
+ * registry throws at registration.
+ */
+export declare const DEFAULT_DIAGNOSTICS_PATH = "/dsh-realtime/diagnostics";
 export interface RealtimeAudioWsConfig {
     /**
      * Absolute pathname to claim. Registered exactly, so it must be distinct from every other route in the
@@ -45,6 +53,14 @@ export interface RealtimeAudioWsConfig {
      * that looks like a fault anywhere but in this file.
      */
     readonly openSessionOnConnect: boolean;
+    /**
+     * Absolute pathname the diagnostics route claims, served as JSON.
+     *
+     * Authenticated by the same policy as the audio route, and for the same reason: it is an HTTP route on
+     * loopback that the host's registry does not gate for us, and it reports the journal — which is worth
+     * more to a stranger than an empty socket.
+     */
+    readonly diagnosticsPath: string;
 }
 /**
  * The slice of a WebSocket this package uses, described structurally.

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,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;CACvC;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;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"}

package/lib/types.js

@@ -19,4 +19,12 @@ export const DEFAULT_MAX_FRAME_BYTES = 480_000;
 export const DEFAULT_MAX_CONNECTIONS = 1;
 /** Whether an authenticated connection asks the agent to open the voice session. See the config field. */
 export const DEFAULT_OPEN_SESSION_ON_CONNECT = true;
+/**
+ * Default pathname the diagnostics route claims.
+ *
+ * A fixed API path in spirit, but a validated config field like the audio route's — so a composition
+ * that already owns this path can move it deliberately rather than discovering the collision when the
+ * registry throws at registration.
+ */
+export const DEFAULT_DIAGNOSTICS_PATH = '/dsh-realtime/diagnostics';
 //# sourceMappingURL=types.js.map

package/lib/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,0GAA0G;AAC1G,MAAM,CAAC,MAAM,YAAY,GAAG,qBAAqB,CAAA;AAEjD,6FAA6F;AAC7F,MAAM,CAAC,MAAM,uBAAuB,GAAG,OAAO,CAAA;AAE9C,sFAAsF;AACtF,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAA;AAExC,0GAA0G;AAC1G,MAAM,CAAC,MAAM,+BAA+B,GAAG,IAAI,CAAA"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,0GAA0G;AAC1G,MAAM,CAAC,MAAM,YAAY,GAAG,qBAAqB,CAAA;AAEjD,6FAA6F;AAC7F,MAAM,CAAC,MAAM,uBAAuB,GAAG,OAAO,CAAA;AAE9C,sFAAsF;AACtF,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAA;AAExC,0GAA0G;AAC1G,MAAM,CAAC,MAAM,+BAA+B,GAAG,IAAI,CAAA;AAEnD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,2BAA2B,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-realtime-audio-ws",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "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,7 @@
   },
   "dependencies": {
     "ws": "^8.22.0",
-    "dsh-realtime-agent": "^0.2.2"
+    "dsh-realtime-agent": "^0.2.6"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.3",

package/src/diagnostics.ts

@@ -0,0 +1,98 @@
+/**
+ * The diagnostics route: the journal, served as JSON over the web server's route registry.
+ *
+ * S1 story 4. It exists so a failure can be read *after* the fact without a console attached — which is
+ * the whole cost this project kept paying, an evening spent inferring a reason that was never written
+ * down anywhere.
+ *
+ * ## The access policy is the audio route's, reused rather than re-derived
+ *
+ * The host's route registry "knows no harness concepts" and its handlers own the full response, so
+ * nothing upstream answers the authentication question for us. The audio route already answers it in
+ * this package: ask the connection service, and let the process's capability token override a refusal,
+ * because the desktop app's page is served from `dsh-app://app` and is therefore cross-site to loopback
+ * — it can never carry the harness's `SameSite=Strict` cookie. This route asks in the same position with
+ * the same token: one policy, two doors. Inventing a second check here is how two schemes drift until
+ * one of them is found holding the weaker answer.
+ *
+ * ## What it deliberately does not do
+ *
+ * It does not redact on the way out. The journal redacts on **write**, so there is no unredacted value
+ * in the buffer to serve and no second step for a later edit to forget. A route that redacted at the
+ * boundary would look safer and be strictly worse: the secret would already be retained, in memory and
+ * in whatever the process dumps.
+ *
+ * @module dsh-realtime-audio-ws/diagnostics
+ */
+
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { Journal } from 'dsh-realtime'
+import { tokenFromUrl, verdictFor } from './injection.ts'
+
+/**
+ * The slice of the journal this route reads.
+ *
+ * Typed as the public surface rather than as the class: `Journal` exists as two declarations in this
+ * repository — built `lib/` and `src/` — and a class with a private member is nominally typed, so the
+ * two are not assignable to each other even though they are the same code.
+ */
+export type DiagnosticsJournal = Pick<Journal, 'snapshot' | 'size' | 'oldestSeq'>
+
+/** What the route needs from the plugin that owns it. */
+export interface DiagnosticsDeps {
+  /** Absolute pathname to claim, no trailing slash — the registry's own contract. */
+  readonly path: string
+  /** This process's capability token, the same one the audio route publishes to the page. */
+  readonly token: string
+  /** The connection service's verdict for one request. */
+  readonly rejectionFor: (request: { headers: IncomingMessage['headers'] }) => 401 | 403 | undefined
+  /** The journal to serve. */
+  readonly journal: DiagnosticsJournal
+}
+
+/** A route the host's registry accepts, described structurally as this package describes the registry. */
+export interface DiagnosticsRoute {
+  readonly kind: 'exact'
+  readonly path: string
+  readonly handler: (req: IncomingMessage, res: ServerResponse) => void
+}
+
+/**
+ * Build the diagnostics route.
+ * @param deps - the path to claim, this process's token, the connection service's verdict, and the journal.
+ * @returns the route registration, ready for `webServer.register`.
+ */
+export function diagnosticsRoute(deps: DiagnosticsDeps): DiagnosticsRoute {
+  return {
+    kind: 'exact',
+    path: deps.path,
+    handler: (req, res) => {
+      const rejection = verdictFor(deps.rejectionFor(req), tokenFromUrl(req.url), deps.token)
+      if (rejection !== undefined) {
+        // The status carries the verdict the connection service actually gave, so a reader can tell a
+        // missing credential from a refused one rather than guessing from a generic failure.
+        send(res, rejection, { error: rejection === 401 ? 'unauthorized' : 'forbidden' })
+        return
+      }
+      const entries = deps.journal.snapshot()
+      // `size` and `oldestSeq` travel with the entries rather than being left for the reader to infer:
+      // a truncated buffer and an idle one are the same empty-looking list otherwise, and the sequence
+      // number is the only thing that separates "nothing happened" from "the buffer rolled over".
+      send(res, 200, { size: deps.journal.size, oldestSeq: deps.journal.oldestSeq, entries })
+    },
+  }
+}
+
+/**
+ * Write one JSON response.
+ *
+ * `no-store` on both branches. This response is a picture of a moving buffer, and a cached one would be
+ * read as current — the same class of mistake as a journal that cannot show its own eviction.
+ * @param res - the response this handler owns.
+ * @param status - HTTP status to write.
+ * @param body - value to serialise as the JSON body.
+ */
+function send(res: ServerResponse, status: number, body: unknown): void {
+  res.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'no-store' })
+  res.end(JSON.stringify(body))
+}

package/src/index.ts

@@ -9,15 +9,20 @@
  * connection services exist, so a composition without a web stack gets a row that visibly waits rather
  * than one that loads and silently claims nothing. `packages/realtime-audio-ws/tests/plugin.spec.ts` proves
  * the functional path against a real socket with both services present.
+ *
+ * It claims **two** routes on that registry, and one policy authenticates both: the WebSocket upgrade
+ * that carries audio, and the JSON diagnostics route that serves the journal. See `./diagnostics.ts` for
+ * why the second reuses the first's check rather than deriving its own.
  */
 
 import Schema from '@deepseek-ai/schemastery'
 import type { Context } from '@deepseek-ai/cordis'
-import type { IncomingMessage } from 'node:http'
+import type { IncomingMessage, ServerResponse } from 'node:http'
 import type { Duplex } from 'node:stream'
 // Type-only: pulls the `Events` augmentation that declares the two audio events this package bridges.
 import type {} from 'dsh-realtime-agent'
 import { attachAudioSocket } from './bridge.ts'
+import { diagnosticsRoute } from './diagnostics.ts'
 import {
   createRouteToken,
   routeAuthority,
@@ -28,6 +33,7 @@ import {
 } from './injection.ts'
 import { createUpgradeAcceptor, rejectUpgrade } from './upgrade.ts'
 import {
+  DEFAULT_DIAGNOSTICS_PATH,
   DEFAULT_MAX_CONNECTIONS,
   DEFAULT_MAX_FRAME_BYTES,
   DEFAULT_OPEN_SESSION_ON_CONNECT,
@@ -37,8 +43,17 @@ import {
 } from './types.ts'
 
 export * from './types.ts'
+/**
+ * The query parameter carrying the capability token.
+ *
+ * Published with the route rather than kept internal: nothing can address the route without it, and a
+ * consumer restating the literal is a consumer that drifts. It is one string; the rest of `injection.ts`
+ * stays where it is.
+ */
+export { TOKEN_PARAM } from './injection.ts'
 export { attachAudioSocket, toBytes, type AudioSocketBridgeDeps } from './bridge.ts'
 export { createUpgradeAcceptor, rejectUpgrade, type UpgradeAcceptor } from './upgrade.ts'
+export { diagnosticsRoute, type DiagnosticsDeps, type DiagnosticsJournal, type DiagnosticsRoute } from './diagnostics.ts'
 
 /** Plugin name. */
 export const name = 'realtime-audio-ws'
@@ -51,6 +66,7 @@ export const Config = Schema.object({
   // boot with nobody asking, which is why it is false. This one opens a session because someone connected a
   // microphone: a connection takes an explicit action, an authenticated one, and its absence is silence.
   openSessionOnConnect: Schema.boolean().default(DEFAULT_OPEN_SESSION_ON_CONNECT),
+  diagnosticsPath: Schema.string().default(DEFAULT_DIAGNOSTICS_PATH),
 })
 
 /**
@@ -59,12 +75,21 @@ export const Config = Schema.object({
  * Structural rather than imported: `@deepseek-ai/dsh-host-webserver` is a DeepSeek package, and importing
  * it would both add a dependency edge for one shape and augment `Context` with another declaration of
  * `webServer` — two declarations of one property with different types is a compile error.
+ *
+ * `register` applies no authentication of its own and knows no harness concepts: the handler owns the
+ * whole response. That is why both routes here carry the same explicit check rather than trusting the
+ * registry to have made the decision.
  */
 interface WebServerLike {
   registerUpgrade(route: {
     path: string
     handler: (req: IncomingMessage, socket: Duplex, head: Buffer) => void | Promise<void>
   }): () => void
+  register(route: {
+    kind: 'exact' | 'prefix'
+    path: string
+    handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>
+  }): () => void
   /**
    * The port actually listening — the OS-assigned value when the config asked for zero. Read at injection
    * time rather than at boot, because an index render happens after the listen.
@@ -80,11 +105,17 @@ interface ConnectionLike {
 }
 
 export function apply(ctx: Context, config: RealtimeAudioWsConfig): void {
-  ctx.inject(['connection', 'webServer'], (injected) => {
+  ctx.inject(['connection', 'webServer', 'realtime'], (injected) => {
     const services = injected as unknown as { webServer: WebServerLike; connection: ConnectionLike }
     const acceptor = createUpgradeAcceptor(config.maxFrameBytes)
     const clients = new Set<AudioSocket>()
     const token = createRouteToken()
+    const journal = injected.realtime.journal
+    // The token travels in a URL query, and this route records request targets, so the journal has to be
+    // able to redact it before it records one. This is exactly why `addSecrets` is additive instead of a
+    // constructor argument: the plugin that mints the token is the only one that can name it, and it
+    // mints it here, after the journal already exists.
+    journal.addSecrets([token])
     // The injection event is declared by `@deepseek-ai/dsh-host-webserver`, which this package deliberately
     // does not import: importing it would augment `Context` with a second declaration of `webServer` and
     // turn the structural dependency above into a compile error. The name is cast at this one boundary.
@@ -104,6 +135,12 @@ export function apply(ctx: Context, config: RealtimeAudioWsConfig): void {
           token,
         ))
       })
+      const unregisterDiagnostics = services.webServer.register(diagnosticsRoute({
+        path: config.diagnosticsPath,
+        token,
+        rejectionFor: (request) => services.connection.requestRejection(request),
+        journal,
+      }))
       const unregister = services.webServer.registerUpgrade({
         path: config.path,
         handler: (req, socket, head) => {
@@ -117,22 +154,38 @@ export function apply(ctx: Context, config: RealtimeAudioWsConfig): void {
           // from `dsh-app://app`, so its requests to loopback are cross-site and the harness's
           // `SameSite=Strict` cookie cannot travel; without the token that page is refused forever, however
           // correct the rest of the client half is.
+          // Normalised once, at the caller's edge, so no record below repeats the check. `node:http`
+          // always reports a target on a server request; the type admits `undefined` for client requests,
+          // which this handler cannot see.
+          const target = req.url ?? ''
           const rejection = verdictFor(
             services.connection.requestRejection(req),
             tokenFromUrl(req.url),
             token,
           )
           if (rejection !== undefined) {
+            // The verdict only, and no target. A valid token is never rejected — it overrides the
+            // refusal — so any target recorded here belongs to something else, and a wrong token is
+            // still a credential. Retaining a caller's secret in order to log a refusal is a worse trade
+            // than losing which path was probed.
+            journal.record('socket.rejected', { verdict: String(rejection) })
             rejectUpgrade(socket, rejection)
             return
           }
           acceptor.handleUpgrade(req, socket, head, (client) => {
             if (clients.size >= config.maxConnections) {
               // 1013 = try again later. Closing the newcomer leaves the existing microphone live.
+              journal.record('socket.rejected', { verdict: '1013', reason: 'busy' })
               client.close(1013, 'busy')
               return
             }
             clients.add(client)
+            // The target here, because an accepted request is the one place this process's own token
+            // travels: the app page presents it in the query precisely because it cannot carry the
+            // cookie. The journal redacts it on write — which is what the token was added to the journal's
+            // secrets for, and the reason that has to be additive rather than a constructor argument,
+            // since the token does not exist until this plugin applies.
+            journal.record('socket.accepted', { clients: String(clients.size), url: target })
             // Ask for the session before the bridge goes in, so the first frames are written into a session
             // that is being opened rather than dropped by the mic seam's no-session rule.
             if (config.openSessionOnConnect) ctx.emit('realtime-agent/start')
@@ -142,6 +195,7 @@ export function apply(ctx: Context, config: RealtimeAudioWsConfig): void {
               maxFrameBytes: config.maxFrameBytes,
               onDetach: () => {
                 clients.delete(client)
+                journal.record('socket.closed', { clients: String(clients.size) })
                 // The last client leaving ends the session. This also covers the transport's own disposal,
                 // which terminates its clients — so a profile reload does not leave a session nobody holds.
                 if (config.openSessionOnConnect && clients.size === 0) ctx.emit('realtime-agent/stop')
@@ -152,6 +206,7 @@ export function apply(ctx: Context, config: RealtimeAudioWsConfig): void {
       })
       return async () => {
         unregister()
+        unregisterDiagnostics()
         for (const client of clients) client.terminate()
         clients.clear()
         await acceptor.close()

package/src/types.ts

@@ -24,6 +24,15 @@ export const DEFAULT_MAX_CONNECTIONS = 1
 /** Whether an authenticated connection asks the agent to open the voice session. See the config field. */
 export const DEFAULT_OPEN_SESSION_ON_CONNECT = true
 
+/**
+ * Default pathname the diagnostics route claims.
+ *
+ * A fixed API path in spirit, but a validated config field like the audio route's — so a composition
+ * that already owns this path can move it deliberately rather than discovering the collision when the
+ * registry throws at registration.
+ */
+export const DEFAULT_DIAGNOSTICS_PATH = '/dsh-realtime/diagnostics'
+
 export interface RealtimeAudioWsConfig {
   /**
    * Absolute pathname to claim. Registered exactly, so it must be distinct from every other route in the
@@ -50,6 +59,14 @@ export interface RealtimeAudioWsConfig {
    * that looks like a fault anywhere but in this file.
    */
   readonly openSessionOnConnect: boolean
+  /**
+   * Absolute pathname the diagnostics route claims, served as JSON.
+   *
+   * Authenticated by the same policy as the audio route, and for the same reason: it is an HTTP route on
+   * loopback that the host's registry does not gate for us, and it reports the journal — which is worth
+   * more to a stranger than an empty socket.
+   */
+  readonly diagnosticsPath: string
 }
 
 /**