super-dsh 0.1.0 → 0.1.2

package/agent-hub/dist/carrier.d.ts

@@ -0,0 +1,43 @@
+import { type RealWebServerFace } from './world-web-server.js';
+import { type MuxFailure } from './world-mux.js';
+/** The two-method face of a world's typertGateway service instance. */
+export interface CarrierGatewayFace {
+    dispatchRpc(endpoint: string, payload: unknown, signal: AbortSignal): Promise<unknown>;
+    /** Streams return an async iterable (upstream face is synchronous-returning). */
+    openWireStream(endpoint: string, payload: unknown, signal: AbortSignal): Promise<AsyncIterable<unknown>> | AsyncIterable<unknown>;
+}
+/** Options for mounting one world. */
+export interface MountWorldOptions {
+    /** The ctx0 webServer the translated routes register on. */
+    real: RealWebServerFace;
+    /** Runtime key: the mount label (`omp` → `/omp`). */
+    label: string;
+    /** The addressed world's gateway instance. */
+    gateway: CarrierGatewayFace;
+    /** ctx0's browser-trust fence: returns an HTTP status to reject with. */
+    requestRejection?(req: unknown): number | undefined;
+    /** Max request body bytes (mirrors the connection default). */
+    maxBodyBytes?: number;
+    /** Mux ping interval (upstream default 30s). */
+    heartbeatIntervalMs?: number;
+    /** Error → wire failure mapper for the world's streams. */
+    failure?(error: unknown): MuxFailure;
+}
+/** The live mount handle. */
+export interface MountedWorld {
+    /** Mount root (`/omp`). */
+    readonly labelPath: string;
+    /** Unary channel root (`/omp/api`). */
+    readonly apiPath: string;
+    /** Mux websocket path (`/omp/api/remote.mux`). */
+    readonly muxPath: string;
+    /** Unregister everything this mount installed. */
+    dispose(): void;
+}
+/**
+ * Mount one world on the shared ctx0 webServer.
+ * @param options - see {@link MountWorldOptions}.
+ * @returns the live mount handle.
+ */
+export declare function mountWorld(options: MountWorldOptions): MountedWorld;
+export { rewriteIndexHtml } from './index-pass.js';

package/agent-hub/dist/carrier.js

@@ -0,0 +1,241 @@
+/**
+ * ctx0 WebCarrier (AW-B DL1/DL5): mounts one world's traffic under `/<label>`.
+ *
+ * Responsibilities (grow per AW-B task):
+ *  - Task 4: unary RPC — `/<label>/api/<endpoint>` decodes the connection
+ *    envelope and dispatches into the ADDRESSED world's gateway instance.
+ *  - Task 6: mux — `/<label>/api/remote.mux` upgrade bridged to the same
+ *    instance (no shared selection anywhere).
+ *  - 2026-09-17 (H1): non-envelope GET/HEAD on `/<label>/api` forwards into
+ *    the owning world's registered exact Fetch routes — the world connection's
+ *    shared `/api` handler, published from `world-entry` via `world-host` —
+ *    still behind ctx0's fence, so `HEAD /<label>/api/session.export?...`
+ *    reaches the world's session-log-download route.
+ *
+ * The addressed world is the request's path. Nothing here reads a global.
+ */
+import { EnvelopeError, parseClientRequest, serverError, serverResult, wireErrorOf, } from './envelope.js';
+import { stripLabelFromUrl } from './world-web-server.js';
+import { worldFetchHandlerOf } from './world-host.js';
+import { WorldMuxServer } from './world-mux.js';
+/** Default body cap, aligned with the connection service. */
+const DEFAULT_MAX_BODY_BYTES = 1024 * 1024;
+async function readBody(req, limit) {
+    const carrier = req;
+    const chunks = [];
+    let size = 0;
+    if (typeof carrier[Symbol.asyncIterator] === 'function') {
+        for await (const chunk of carrier) {
+            const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+            size += buf.byteLength;
+            if (size > limit)
+                throw new EnvelopeError({ code: 'gateway/bad-request', message: 'request body too large' });
+            chunks.push(buf);
+        }
+        return Buffer.concat(chunks).toString('utf8');
+    }
+    if (typeof carrier.on !== 'function')
+        return '';
+    return await new Promise((resolve, reject) => {
+        carrier.on?.('data', (chunk) => {
+            const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk ?? ''));
+            size += buf.byteLength;
+            if (size > limit) {
+                reject(new EnvelopeError({ code: 'gateway/bad-request', message: 'request body too large' }));
+                return;
+            }
+            chunks.push(buf);
+        });
+        carrier.on?.('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        carrier.on?.('error', (error) => reject(error instanceof Error ? error : new Error(String(error))));
+    });
+}
+/** Reject an upgrade on the raw socket (no ws ownership transfer). */
+function rejectUpgrade(socket, status) {
+    const reason = status === 401 ? 'Unauthorized' : 'Forbidden';
+    const body = reason.toLowerCase();
+    const writable = socket;
+    writable.write?.(`HTTP/1.1 ${status} ${reason}\r\n`
+        + 'Connection: close\r\n'
+        + 'Content-Type: text/plain; charset=utf-8\r\n'
+        + `Content-Length: ${String(Buffer.byteLength(body, 'utf8'))}\r\n\r\n`
+        + body);
+    writable.destroy?.();
+}
+function writeJson(res, status, body) {
+    const carrier = res;
+    carrier.writeHead?.(status, { 'content-type': 'application/json' });
+    res.end(body);
+}
+/** Write a plain-text answer (the shape upstream's own 404/413 answers use). */
+function writeText(res, status, body) {
+    const carrier = res;
+    carrier.writeHead?.(status, { 'content-type': 'text/plain; charset=utf-8' });
+    res.end(body);
+}
+/**
+ * Mount one world on the shared ctx0 webServer.
+ * @param options - see {@link MountWorldOptions}.
+ * @returns the live mount handle.
+ */
+export function mountWorld(options) {
+    const labelPath = `/${options.label}`;
+    const apiPath = `${labelPath}/api`;
+    const muxPath = `${apiPath}/remote.mux`;
+    const maxBody = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+    const disposers = [];
+    const forwardsFetchMethod = (req) => {
+        const method = req.method;
+        return method === 'GET' || method === 'HEAD';
+    };
+    /**
+     * Forward one non-envelope GET/HEAD request into the owning world's shared
+     * `/api` fetch handler (exact Fetch routes first, then the gateway's RPC
+     * interceptor, then 404 — the upstream composition). The ctx0 fence has
+     * already answered by the time we get here; the world's own browser-auth
+     * gate is never consulted (a different tree, a different secret).
+     */
+    const bridgeWorldFetch = async (req, res) => {
+        const worldFetch = worldFetchHandlerOf(options.label);
+        if (worldFetch === undefined) {
+            writeText(res, 404, 'not found');
+            return;
+        }
+        const method = (req.method ?? 'GET');
+        const resCarrier = res;
+        // Client-disconnect detection rides the response (same reason as the
+        // upstream node:http bridge: the request 'close' fires as soon as a
+        // bodyless GET is consumed).
+        const abort = new AbortController();
+        const onClose = () => {
+            if (resCarrier.writableEnded !== true)
+                abort.abort();
+        };
+        resCarrier.once?.('close', onClose);
+        let headersSent = false;
+        try {
+            const headers = {};
+            for (const [name, value] of Object.entries(req.headers ?? {})) {
+                if (typeof value === 'string')
+                    headers[name.toLowerCase()] = value;
+            }
+            // The world route owns the world-relative URL: strip the mount label,
+            // keep the query (the session-export route reads it from searchParams).
+            const request = new Request(new URL(stripLabelFromUrl(req.url, labelPath), 'http://dsh.internal'), { method, headers, signal: abort.signal });
+            const response = await worldFetch.fetch(request);
+            res.writeHead(response.status, Object.fromEntries(response.headers.entries()));
+            headersSent = true;
+            if (response.body === null) {
+                res.end();
+                return;
+            }
+            for await (const chunk of response.body) {
+                // Backpressure: wait for drain instead of buffering unboundedly; a
+                // socket close resolves the wait and the aborted signal ends the stream.
+                if (resCarrier.write?.(chunk) === false && typeof resCarrier.once === 'function') {
+                    await new Promise((resolve) => {
+                        const done = () => {
+                            resCarrier.off?.('drain', done);
+                            resCarrier.off?.('close', done);
+                            resolve();
+                        };
+                        resCarrier.once?.('drain', done);
+                        resCarrier.once?.('close', done);
+                    });
+                }
+            }
+            res.end();
+        }
+        catch {
+            // The world route owns its statuses; only carrier-level faults land here.
+            if (!headersSent)
+                writeText(res, 500, 'carrier fetch bridge failure');
+            else
+                resCarrier.destroy?.();
+        }
+        finally {
+            resCarrier.off?.('close', onClose);
+        }
+    };
+    const handleUnary = async (req, res) => {
+        const rejection = options.requestRejection?.(req);
+        if (rejection !== undefined) {
+            writeJson(res, rejection, JSON.stringify({ error: rejection === 401 ? 'unauthorized' : 'forbidden' }));
+            return;
+        }
+        let rpcId = 'invalid-request';
+        try {
+            const text = await readBody(req, maxBody);
+            let envelope;
+            try {
+                envelope = parseClientRequest(text);
+            }
+            catch (error) {
+                // Non-envelope GET/HEAD traffic on the shared mount prefix belongs to
+                // the world's own registered fetch routes; envelopes (and every other
+                // method) keep the transport-level 400 below.
+                if (error instanceof EnvelopeError && forwardsFetchMethod(req)) {
+                    await bridgeWorldFetch(req, res);
+                    return;
+                }
+                throw error;
+            }
+            rpcId = envelope.rpcId;
+            const controller = new AbortController();
+            const result = await options.gateway.dispatchRpc(envelope.method, envelope.payload, controller.signal);
+            // The gateway already returns a Result (`{ok:true,value}` | `{ok:false,error}`),
+            // which is exactly the server-response's `result` field.
+            writeJson(res, 200, serverResult(rpcId, result));
+        }
+        catch (error) {
+            const wire = wireErrorOf(error);
+            // Envelope-level failures are transport-level 400s; dispatch failures are
+            // business results carried inside a 200 server-response (upstream shape).
+            if (error instanceof EnvelopeError) {
+                writeJson(res, 400, serverError(rpcId, wire));
+                return;
+            }
+            writeJson(res, 200, serverError(rpcId, wire));
+        }
+    };
+    disposers.push(options.real.register({
+        kind: 'prefix',
+        path: apiPath,
+        handler: handleUnary,
+    }));
+    // Mux: the world's own stream face behind the same mount prefix.
+    const mux = new WorldMuxServer((endpoint, payload, signal) => Promise.resolve(options.gateway.openWireStream(endpoint, payload, signal)), {
+        ...(options.heartbeatIntervalMs === undefined ? {} : { heartbeatIntervalMs: options.heartbeatIntervalMs }),
+        ...(options.failure === undefined ? {} : { failure: options.failure }),
+    });
+    disposers.push(options.real.registerUpgrade({
+        path: muxPath,
+        handler: ((req, socket, head) => {
+            const rejection = options.requestRejection?.(req);
+            if (rejection !== undefined) {
+                rejectUpgrade(socket, rejection === 401 ? 401 : 403);
+                return;
+            }
+            return mux.handleUpgrade(req, socket, head);
+        }),
+    }));
+    disposers.push(() => { void mux.close().catch(() => undefined); });
+    return {
+        labelPath,
+        apiPath,
+        muxPath,
+        dispose() {
+            for (const dispose of disposers.splice(0).reverse()) {
+                try {
+                    dispose();
+                }
+                catch {
+                    // teardown must not throw
+                }
+            }
+        },
+    };
+}
+// The mount HTML pass lives in its own module; re-exported here so the carrier
+// remains the single import surface for mount behaviour.
+export { rewriteIndexHtml } from './index-pass.js';

package/agent-hub/dist/client-shim.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Client mount shim (AW-B DL8).
+ *
+ * ONE head script installs every client-side break point:
+ *   - `__DSH_TRANSPORT__.fetch`  → the Connection RPC fetch (URL object input)
+ *   - `WebSocket` / `EventSource` / `XMLHttpRequest` constructors → path rewrite
+ *   - `__DSH_FILE_UPLOAD__`      → uploads bypass the blob worker + its XHR
+ *   - Storage.prototype get/set/remove → per-world key namespace
+ *   - `globalThis.fetch`         → global-fetch calls asking for ctx0-root `/api`
+ *     URLs (2026-09-17 H1: upstream session-log-export resolves the GLOBAL
+ *     fetch at call time; narrow `/api`-only rule, query + hash preserved)
+ *   - `HTMLAnchorElement.prototype.click` → download-anchor clicks re-rooted
+ *     (2026-09-18 H1 r2: upstream hands the UNREWRITTEN absolute URL to a
+ *     DETACHED `<a download>` and clicks it — detached clicks never reach
+ *     document, so a document-level listener cannot see them, and a blanket
+ *     rewrite breaks the runtime selector's root-absolute anchors
+ *     (live-found 2026-09-18). Narrow rule: ONLY anchors carrying a
+ *     `download` attribute AND a same-authority root-absolute `/api` href.)
+ * The rule is namespace-agnostic: a same-origin root-absolute URL is re-rooted
+ * under the mount (`/omp`), nothing else is touched. That covers every prefix
+ * a plugin may declare later — no list to keep in sync.
+ */
+/**
+ * Render the shim as a classic script (parser-blocking head injection).
+ * @param labelPath - mount root, e.g. `/omp`.
+ * @returns JavaScript source.
+ */
+export declare function renderClientShim(labelPath: string): string;

package/agent-hub/dist/client-shim.js

@@ -0,0 +1,251 @@
+/**
+ * Client mount shim (AW-B DL8).
+ *
+ * ONE head script installs every client-side break point:
+ *   - `__DSH_TRANSPORT__.fetch`  → the Connection RPC fetch (URL object input)
+ *   - `WebSocket` / `EventSource` / `XMLHttpRequest` constructors → path rewrite
+ *   - `__DSH_FILE_UPLOAD__`      → uploads bypass the blob worker + its XHR
+ *   - Storage.prototype get/set/remove → per-world key namespace
+ *   - `globalThis.fetch`         → global-fetch calls asking for ctx0-root `/api`
+ *     URLs (2026-09-17 H1: upstream session-log-export resolves the GLOBAL
+ *     fetch at call time; narrow `/api`-only rule, query + hash preserved)
+ *   - `HTMLAnchorElement.prototype.click` → download-anchor clicks re-rooted
+ *     (2026-09-18 H1 r2: upstream hands the UNREWRITTEN absolute URL to a
+ *     DETACHED `<a download>` and clicks it — detached clicks never reach
+ *     document, so a document-level listener cannot see them, and a blanket
+ *     rewrite breaks the runtime selector's root-absolute anchors
+ *     (live-found 2026-09-18). Narrow rule: ONLY anchors carrying a
+ *     `download` attribute AND a same-authority root-absolute `/api` href.)
+ * The rule is namespace-agnostic: a same-origin root-absolute URL is re-rooted
+ * under the mount (`/omp`), nothing else is touched. That covers every prefix
+ * a plugin may declare later — no list to keep in sync.
+ */
+/** Escape a label for embedding in generated JavaScript. */
+function js(value) {
+    return JSON.stringify(value);
+}
+/**
+ * Render the shim as a classic script (parser-blocking head injection).
+ * @param labelPath - mount root, e.g. `/omp`.
+ * @returns JavaScript source.
+ */
+export function renderClientShim(labelPath) {
+    if (typeof labelPath !== 'string' || !labelPath.startsWith('/') || labelPath === '/' || labelPath.endsWith('/')) {
+        throw new Error(`client-shim: labelPath must start with "/" and carry no trailing slash, got ${JSON.stringify(labelPath)}`);
+    }
+    const prefix = `${labelPath}/`;
+    return `(() => {
+  const LABEL = ${js(labelPath)}
+  const PREFIX = ${js(prefix)}
+
+  /** Re-root one pathname when it is same-origin root-absolute and not mounted yet. */
+  const rewritePath = (path) => {
+    if (typeof path !== 'string' || !path.startsWith('/') || path.startsWith('//')) return path
+    if (path === LABEL || path.startsWith(PREFIX)) return path
+    return PREFIX + path.slice(1)
+  }
+
+  const origin = () => {
+    const loc = globalThis.location
+    if (loc !== undefined && typeof loc.origin === 'string' && loc.origin !== 'null') return loc.origin
+    return 'http://dsh.internal'
+  }
+
+  /** Same authority as the page (scheme-agnostic: ws/wss/http/https share host). */
+  const sameAuthority = (url) => {
+    try {
+      return url.host === new URL(origin()).host
+    } catch {
+      return false
+    }
+  }
+
+  /** Rewrite a full URL (absolute or relative); other authorities are untouched. */
+  const rewriteUrl = (input) => {
+    if (typeof input === 'string') {
+      if (input.startsWith('/')) return rewritePath(input)
+      try {
+        const url = new URL(input, origin())
+        if (!sameAuthority(url)) return input
+        const next = rewritePath(url.pathname)
+        if (next === url.pathname) return input
+        url.pathname = next
+        return url.href
+      } catch {
+        return input
+      }
+    }
+    if (input !== null && typeof input === 'object' && typeof input.href === 'string') {
+      try {
+        const url = new URL(input.href)
+        if (!sameAuthority(url)) return input
+        const next = rewritePath(url.pathname)
+        if (next === url.pathname) return input
+        url.pathname = next
+        return url
+      } catch {
+        return input
+      }
+    }
+    return input
+  }
+
+  const nativeFetch = globalThis.fetch
+  const shimFetch = (input, init) => {
+    if (typeof nativeFetch !== 'function') throw new Error('client-shim: fetch is unavailable')
+    if (typeof Request === 'function' && input instanceof Request) {
+      const url = rewriteUrl(input.url)
+      return nativeFetch(url === input.url ? input : new Request(url, input), init)
+    }
+    return nativeFetch(rewriteUrl(input), init)
+  }
+
+  const transport = (globalThis.__DSH_TRANSPORT__ = globalThis.__DSH_TRANSPORT__ || {})
+  transport.rewrite = rewritePath
+  transport.fetch = shimFetch
+
+  // Construct through a Proxy, never a hand-rolled wrapper function: the
+  // upstream client compares socket.readyState against WebSocket.OPEN, so the
+  // native statics (CONNECTING/OPEN/CLOSING/CLOSED), prototype and instanceof
+  // must survive the interception.
+  const NativeWebSocket = globalThis.WebSocket
+  if (typeof NativeWebSocket === 'function') {
+    globalThis.WebSocket = new Proxy(NativeWebSocket, {
+      construct: (Target, args) => new Target(rewriteUrl(args[0]), ...args.slice(1)),
+    })
+  }
+
+  const NativeEventSource = globalThis.EventSource
+
+  if (typeof NativeEventSource === 'function') {
+    globalThis.EventSource = new Proxy(NativeEventSource, {
+      construct: (Target, args) => new Target(rewriteUrl(args[0]), ...args.slice(1)),
+    })
+  }
+
+  const NativeXhr = globalThis.XMLHttpRequest
+  if (typeof NativeXhr === 'function' && NativeXhr.prototype !== undefined && typeof NativeXhr.prototype.open === 'function') {
+    const nativeOpen = NativeXhr.prototype.open
+    NativeXhr.prototype.open = function (method, url, ...rest) {
+      return nativeOpen.call(this, method, rewriteUrl(url), ...rest)
+    }
+  }
+
+  // Read by the file-upload service at construction time: present ⇒ the page
+  // fetch carries uploads (no blob worker, and therefore no worker-scope XHR).
+  globalThis.__DSH_FILE_UPLOAD__ = { fetch: shimFetch }
+
+  // Narrow '/api' re-root helpers (2026-09-17 session-log 404, H1): upstream
+  // client code (session-log-export) resolves the GLOBAL fetch at call time
+  // and hands absolute ctx0-root URLs both to fetch and to a DETACHED
+  // download anchor — neither is visible to the transport faces above.
+  // Narrow rule: only root-absolute '/api' paths move under the mount;
+  // relative, same-mount, and foreign URLs pass through untouched. Query and
+  // hash survive because only the pathname is rewritten. The mount root comes
+  // from this shim's argument, never from location.pathname. NOTE: the '/api'
+  // literals below stay SINGLE-quoted on purpose — index-pass.ts rewrites
+  // every DOUBLE-quoted root-absolute string in the served HTML, and a
+  // doubled literal would silently disable these rewrites (regression tests
+  // survive the mount HTML pass).
+  const rewriteApiPath = (path) => {
+    if (path === '/api' || path.startsWith('/api/')) return PREFIX + path.slice(1)
+    return path
+  }
+  const rewriteApiUrl = (input) => {
+    if (typeof input === 'string') {
+      if (input.startsWith('/') && !input.startsWith('//')) return rewriteApiPath(input)
+      try {
+        const url = new URL(input, origin())
+        if (!sameAuthority(url)) return input
+        const next = rewriteApiPath(url.pathname)
+        if (next === url.pathname) return input
+        url.pathname = next
+        return url.href
+      } catch {
+        return input
+      }
+    }
+    if (input !== null && typeof input === 'object' && typeof input.href === 'string') {
+      try {
+        const url = new URL(input.href)
+        if (!sameAuthority(url)) return input
+        const next = rewriteApiPath(url.pathname)
+        if (next === url.pathname) return input
+        url.pathname = next
+        return url
+      } catch {
+        return input
+      }
+    }
+    return input
+  }
+  if (typeof nativeFetch === 'function' && globalThis.__DSH_FETCH_REWRITE__ !== true) {
+    globalThis.__DSH_FETCH_REWRITE__ = true
+    globalThis.fetch = (input, init) => nativeFetch(rewriteApiUrl(input), init)
+  }
+
+  // Download anchors (2026-09-18 H1 r2): upstream session-log-export hands
+  // the UNREWRITTEN absolute URL to a DETACHED '<a download>' element and
+  // calls .click() — detached clicks never propagate to document, so the r1
+  // document-level capture listener could not see them, while its BLANKET
+  // rewrite re-rooted the runtime selector's root-absolute anchors and broke
+  // cross-world navigation (live-found 2026-09-18). Narrow seam: wrap
+  // HTMLAnchorElement.prototype.click itself and rewrite ONLY anchors that
+  // carry a 'download' attribute AND a same-authority root-absolute '/api'
+  // href. Everything else — the runtime selector's links included — passes
+  // through untouched.
+  if (globalThis.HTMLAnchorElement !== undefined
+    && globalThis.HTMLAnchorElement.prototype !== undefined
+    && typeof globalThis.HTMLAnchorElement.prototype.click === 'function'
+    && globalThis.__DSH_ANCHOR_CLICK_REWRITE__ !== true) {
+    globalThis.__DSH_ANCHOR_CLICK_REWRITE__ = true
+    const nativeAnchorClick = globalThis.HTMLAnchorElement.prototype.click
+    globalThis.HTMLAnchorElement.prototype.click = function (...args) {
+      try {
+        if (this.hasAttribute('download')) {
+          const current = this.getAttribute('href')
+          if (typeof current === 'string' && current !== '') {
+            const next = rewriteApiUrl(current)
+            if (typeof next === 'string' && next !== current) this.setAttribute('href', next)
+          }
+        }
+      } catch {
+        /* best-effort: never break the click itself */
+      }
+      return nativeAnchorClick.apply(this, args)
+    }
+  }
+
+  // Storage namespace (2026-09-16 storage findings P1): all worlds share one
+
+  // origin, so bare localStorage keys would overwrite each other across
+  // mounts. Prefix every key with the label; root '/' never injects this
+  // shim and keeps bare keys. Never throws: attachPersistence only
+  // console-errors on failure, so a throwing shim would silently disable
+  // persistence.
+  try {
+  const StorageProto = globalThis.Storage && globalThis.Storage.prototype
+  if (globalThis.localStorage !== undefined && StorageProto !== undefined
+    && !globalThis.__DSH_STORAGE_NS__
+    && typeof StorageProto.getItem === 'function'
+    && typeof StorageProto.setItem === 'function'
+    && typeof StorageProto.removeItem === 'function') {
+    // NS derives from PREFIX, never LABEL: the mount HTML pass (index-pass)
+    // rewrites every quoted root-absolute string EXCEPT "<label>/"-prefixed
+    // ones, so the shim's LABEL="/omp" literal doubles to "/omp/omp" while
+    // PREFIX="/omp/" is immune (live-found 2026-09-17, acceptance A2/A5).
+    // The NS-from-PREFIX coupling is DELIBERATE: index-pass.ts rewrites double-quoted root-absolute strings except "<label>/"-prefixed ones, so LABEL="/omp" doubles while PREFIX="/omp/" survives; do NOT derive NS from LABEL.
+    const NS = PREFIX.slice(1, -1) + ':'
+    globalThis.__DSH_STORAGE_NS__ = NS
+    const nativeGetItem = StorageProto.getItem
+    const nativeSetItem = StorageProto.setItem
+    const nativeRemoveItem = StorageProto.removeItem
+    StorageProto.getItem = function (name) { return nativeGetItem.call(this, NS + name) }
+    StorageProto.setItem = function (name, value) { return nativeSetItem.call(this, NS + name, value) }
+    StorageProto.removeItem = function (name) { return nativeRemoveItem.call(this, NS + name) }
+  }
+  } catch {
+    /* storage namespace is best-effort: never break the shim */
+  }
+})()`;
+}

package/agent-hub/dist/envelope.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Connection unary envelope (AW-B DL5).
+ *
+ * Our carrier owns `/<label>/api/*` and therefore must speak the wire shape
+ * itself. The shape is fixed by upstream (`client/connection/src/rpc-host.ts`):
+ *
+ *   request   { type: 'client-request',  rpcId, method, payload }
+ *   response  { type: 'server-response', rpcId, result: { ok: true, value } }
+ *             { type: 'server-response', rpcId, result: { ok: false, error } }
+ *
+ * Endpoint segments follow upstream's pattern so a crafted path cannot smuggle
+ * anything the native route would have rejected.
+ */
+/** One decoded client request. */
+export interface ClientRequestEnvelope {
+    /** Correlates the response; echoed verbatim. */
+    rpcId: string;
+    /** Typert endpoint (the gateway's dispatch key). */
+    method: string;
+    /** Invocation payload. */
+    payload: unknown;
+}
+/** One wire error body. */
+export interface WireError {
+    code: string;
+    message: string;
+    details?: unknown;
+}
+/** Upstream's endpoint segment pattern (`rpc-host.ts`). */
+export declare const ENDPOINT_SEGMENT_PATTERN: RegExp;
+/** Envelope-level failure carrying the wire error to answer with. */
+export declare class EnvelopeError extends Error {
+    readonly wire: WireError;
+    constructor(wire: WireError);
+}
+/**
+ * Decode one request body.
+ * @param text - raw body text.
+ * @returns the decoded envelope.
+ * @throws {EnvelopeError} when the body is not a valid client-request.
+ */
+export declare function parseClientRequest(text: string): ClientRequestEnvelope;
+/** Serialize a successful server response from a raw value. */
+export declare function serverResponse(rpcId: string, value: unknown): string;
+/**
+ * Serialize a server response whose `result` is already a gateway Result
+ * (`{ ok: true, value }` | `{ ok: false, error }`). The typert gateway's
+ * `dispatchRpc` returns exactly that shape, so it is copied verbatim.
+ */
+export declare function serverResult(rpcId: string, result: unknown): string;
+/** Serialize a failed server response. */
+export declare function serverError(rpcId: string, error: WireError): string;
+/** Normalize an unknown thrown value into a wire error. */
+export declare function wireErrorOf(error: unknown): WireError;