super-dsh 0.1.0 → 0.1.2

package/agent-hub/dist/world-mux.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Per-world Remote stream mux server (AW-B DL6).
+ *
+ * Upstream's `RemoteStreamMuxServer` owns `/api/remote.mux` for the native
+ * gateway and is NOT reachable from outside its package (root exports omit it;
+ * `./src/*` cannot be imported at runtime). So this is our own wire-compatible
+ * implementation of the same protocol, bound to the ADDRESSED world's
+ * `openWireStream`:
+ *
+ *   browser → server   { type:'open', streamId, endpoint, payload }
+ *                      { type:'cancel', streamId }
+ *   server → browser   { type:'item', streamId, value }
+ *                      { type:'end', streamId }
+ *                      { type:'error', streamId, error:{code,message,details} }
+ *
+ * Heartbeat: ping every interval, terminate after two missed pongs (same
+ * policy as upstream).
+ */
+/** Open one world stream (the world gateway's `openWireStream`). */
+export type MuxOpen = (endpoint: string, payload: unknown, signal: AbortSignal) => Promise<AsyncIterable<unknown>>;
+/** Wire failure body (upstream `RemoteStreamFailure`). */
+export interface MuxFailure {
+    code: string;
+    message: string;
+    details: object;
+}
+/** Options. */
+export interface WorldMuxOptions {
+    /** Ping interval; upstream default is 30s. */
+    heartbeatIntervalMs?: number;
+    /** Error → wire failure mapper. */
+    failure?: (error: unknown) => MuxFailure;
+}
+/** One client request frame. */
+type ClientMessage = {
+    type: 'open';
+    streamId: string;
+    endpoint: string;
+    payload: unknown;
+} | {
+    type: 'cancel';
+    streamId: string;
+};
+/**
+ * Parse one browser text frame.
+ * @param text - complete WebSocket text message.
+ * @returns the validated request.
+ * @throws {Error} on a malformed frame.
+ */
+export declare function parseClientMessage(text: string): ClientMessage;
+/** Default failure mapper: keep the error code when it looks like one. */
+export declare function defaultFailure(error: unknown): MuxFailure;
+/** One world's mux endpoint. */
+export declare class WorldMuxServer {
+    private readonly open;
+    private readonly options;
+    private server;
+    private ws;
+    private heartbeat;
+    private readonly connections;
+    private readonly missed;
+    private closed;
+    constructor(open: MuxOpen, options?: WorldMuxOptions);
+    /** Take over one accepted upgrade request. */
+    handleUpgrade(req: unknown, socket: unknown, head: Buffer): Promise<void>;
+    /** Terminate every socket and wait for the active streams to unwind. */
+    close(): Promise<void>;
+    private load;
+    private runConnection;
+    private startHeartbeat;
+}
+export {};

package/agent-hub/dist/world-mux.js

@@ -0,0 +1,224 @@
+/**
+ * Per-world Remote stream mux server (AW-B DL6).
+ *
+ * Upstream's `RemoteStreamMuxServer` owns `/api/remote.mux` for the native
+ * gateway and is NOT reachable from outside its package (root exports omit it;
+ * `./src/*` cannot be imported at runtime). So this is our own wire-compatible
+ * implementation of the same protocol, bound to the ADDRESSED world's
+ * `openWireStream`:
+ *
+ *   browser → server   { type:'open', streamId, endpoint, payload }
+ *                      { type:'cancel', streamId }
+ *   server → browser   { type:'item', streamId, value }
+ *                      { type:'end', streamId }
+ *                      { type:'error', streamId, error:{code,message,details} }
+ *
+ * Heartbeat: ping every interval, terminate after two missed pongs (same
+ * policy as upstream).
+ */
+/** Specifier is widened on purpose: `ws` is a runtime peer, not a typed dep. */
+const WS_MODULE = 'ws';
+const MAX_MISSED_HEARTBEATS = 2;
+const DEFAULT_HEARTBEAT_MS = 30_000;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function exactKeys(value, keys) {
+    const own = Object.keys(value);
+    return own.length === keys.length && keys.every(key => Object.hasOwn(value, key));
+}
+function validId(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+/**
+ * Parse one browser text frame.
+ * @param text - complete WebSocket text message.
+ * @returns the validated request.
+ * @throws {Error} on a malformed frame.
+ */
+export function parseClientMessage(text) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        throw new Error('world-mux: invalid client message');
+    }
+    if (!isRecord(raw))
+        throw new Error('world-mux: invalid client message');
+    if (raw['type'] === 'cancel' && exactKeys(raw, ['type', 'streamId']) && validId(raw['streamId'])) {
+        return { type: 'cancel', streamId: raw['streamId'] };
+    }
+    if (raw['type'] === 'open'
+        && exactKeys(raw, ['type', 'streamId', 'endpoint', 'payload'])
+        && validId(raw['streamId'])
+        && typeof raw['endpoint'] === 'string'
+        && raw['endpoint'].length > 0) {
+        return { type: 'open', streamId: raw['streamId'], endpoint: raw['endpoint'], payload: raw['payload'] };
+    }
+    throw new Error('world-mux: invalid client message');
+}
+/** Default failure mapper: keep the error code when it looks like one. */
+export function defaultFailure(error) {
+    if (isRecord(error)) {
+        const code = typeof error['code'] === 'string' ? error['code'] : undefined;
+        const message = typeof error['message'] === 'string' ? error['message'] : undefined;
+        if (code !== undefined)
+            return { code, message: message ?? code, details: {} };
+    }
+    return { code: 'gateway/stream-error', message: error instanceof Error ? error.message : String(error), details: {} };
+}
+/** One world's mux endpoint. */
+export class WorldMuxServer {
+    open;
+    options;
+    server;
+    ws;
+    heartbeat;
+    connections = new Set();
+    missed = new WeakMap();
+    closed = false;
+    constructor(open, options = {}) {
+        this.open = open;
+        this.options = options;
+    }
+    /** Take over one accepted upgrade request. */
+    async handleUpgrade(req, socket, head) {
+        const { server, ws } = await this.load();
+        server.handleUpgrade(req, socket, head, (client) => {
+            this.missed.set(client, 0);
+            client.on('pong', () => { this.missed.set(client, 0); });
+            this.startHeartbeat();
+            const done = this.runConnection(client, ws);
+            this.connections.add(done);
+            void done.then(() => { this.connections.delete(done); });
+        });
+    }
+    /** Terminate every socket and wait for the active streams to unwind. */
+    async close() {
+        this.closed = true;
+        clearInterval(this.heartbeat);
+        this.heartbeat = undefined;
+        const server = this.server;
+        if (server !== undefined) {
+            for (const client of server.clients)
+                client.terminate();
+            await new Promise((resolve) => { server.close(() => resolve()); });
+        }
+        await Promise.all([...this.connections]);
+    }
+    async load() {
+        if (this.server !== undefined && this.ws !== undefined)
+            return { server: this.server, ws: this.ws };
+        const mod = (await import(WS_MODULE));
+        const ws = typeof mod.WebSocketServer === 'function' ? mod : mod.default;
+        const server = new ws.WebSocketServer({ noServer: true });
+        this.server = server;
+        this.ws = ws;
+        return { server, ws };
+    }
+    async runConnection(client, ws) {
+        const streams = new Map();
+        let writes = Promise.resolve();
+        const send = (message) => {
+            let text;
+            try {
+                text = JSON.stringify(message);
+            }
+            catch (cause) {
+                return Promise.reject(new Error('world-mux: item is not JSON serializable', { cause }));
+            }
+            const delivery = writes.then(() => new Promise((resolve, reject) => {
+                if (client.readyState !== ws.WebSocket.OPEN) {
+                    reject(new Error('world-mux: socket is closed'));
+                    return;
+                }
+                client.send(text, (error) => { if (error)
+                    reject(error);
+                else
+                    resolve(); });
+            }));
+            writes = delivery.catch(() => undefined);
+            return delivery;
+        };
+        const pump = async (streamId, endpoint, payload, active) => {
+            try {
+                const source = await this.open(endpoint, payload, active.abort.signal);
+                for await (const value of source) {
+                    await send({ type: 'item', streamId, value });
+                }
+                if (!active.abort.signal.aborted)
+                    await send({ type: 'end', streamId });
+            }
+            catch (error) {
+                if (!active.abort.signal.aborted && client.readyState === ws.WebSocket.OPEN) {
+                    const failure = (this.options.failure ?? defaultFailure)(error);
+                    try {
+                        await send({ type: 'error', streamId, error: failure });
+                    }
+                    catch {
+                        client.close(1011, 'Remote stream failure could not be delivered');
+                    }
+                }
+            }
+        };
+        await new Promise((resolve) => {
+            client.once('close', () => { resolve(); });
+            client.on('error', () => { client.terminate(); });
+            client.on('message', (data, isBinary) => {
+                if (isBinary === true) {
+                    client.close(1003, 'text messages required');
+                    return;
+                }
+                let message;
+                try {
+                    message = parseClientMessage(String(data));
+                }
+                catch {
+                    client.close(1008, 'invalid Remote stream request');
+                    return;
+                }
+                if (message.type === 'cancel') {
+                    streams.get(message.streamId)?.abort.abort(new Error('Remote stream cancelled'));
+                    return;
+                }
+                if (streams.has(message.streamId)) {
+                    client.close(1008, 'duplicate Remote stream id');
+                    return;
+                }
+                const abort = new AbortController();
+                const active = { abort, done: Promise.resolve() };
+                streams.set(message.streamId, active);
+                const done = pump(message.streamId, message.endpoint, message.payload, active);
+                active.done = done;
+                void done.then(() => streams.delete(message.streamId), () => streams.delete(message.streamId));
+            });
+        });
+        const active = [...streams.values()];
+        for (const stream of active)
+            stream.abort.abort(new Error('Remote stream socket closed'));
+        await Promise.all(active.map(stream => stream.done));
+    }
+    startHeartbeat() {
+        if (this.heartbeat !== undefined || this.closed)
+            return;
+        const interval = this.options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_MS;
+        this.heartbeat = setInterval(() => {
+            const server = this.server;
+            if (server === undefined)
+                return;
+            for (const client of server.clients) {
+                if (client.readyState !== (this.ws?.WebSocket.OPEN ?? 1))
+                    continue;
+                const missed = this.missed.get(client) ?? 0;
+                if (missed >= MAX_MISSED_HEARTBEATS) {
+                    client.terminate();
+                    continue;
+                }
+                this.missed.set(client, missed + 1);
+                client.ping();
+            }
+        }, interval);
+        this.heartbeat.unref();
+    }
+}

package/agent-hub/dist/world-provision.d.ts

@@ -0,0 +1,20 @@
+export interface ProvisionWorldOptions {
+    /** Runtime key — also the mount label and the `agents/<key>` home segment. */
+    key: string;
+    /** The adapter's own package name (the world profile's third bundle). */
+    adapterPkg: string;
+    /** Nested home root: `<DSH_HOME>/agents/<key>`. */
+    worldHome: string;
+    /** Profile directory name under `<worldHome>/profiles`. Default `'web'`. */
+    profileName?: string;
+}
+/**
+ * Provision one world's nested profile (idempotent: rewrites profile files,
+ * re-links packages — lstat-safe against dangling links). Returns the
+ * `bareModuleBaseUrl` for {@link spawnWorld}, or null when unresolvable.
+ *
+ * Never throws: any provisioning failure is logged and returns null so the
+ * calling world plugin degrades to a not-ready roster row instead of failing
+ * the loader entry — a failed apply would take down the whole host boot.
+ */
+export declare function provisionWorldProfile(opts: ProvisionWorldOptions): string | null;

package/agent-hub/dist/world-provision.js

@@ -0,0 +1,122 @@
+/**
+ * Nested-world profile provisioning — the publish story.
+ *
+ * The dev line (test/smoke.mjs) hand-provisions every world's nested profile
+ * (`<home>/agents/<label>/profiles/web`) and the `@pgmi-builds/*` links its
+ * resolution needs. A foreign install has NO line bootstrap:
+ *
+ *   dsh plugin --profile <name> add super-dsh
+ *
+ * mounts the hub + adapter world plugins into the consumer's profile, and the
+ * spawn call sites (adapter world-plugins, hub join) must provision the same
+ * layout THEMSELVES or every world spawn fails on a missing profile.
+ *
+ * This module is the library form of that bootstrap, called by all six spawn
+ * sites. Layout invariants (super-dsh/AGENTS.md S7, smoke.mjs parity):
+ *
+ *   - `<worldHome>/profiles/web/package.json` — bundles `[dsh-base, dsh-web-app,
+ *     adapterPkg]`; the world tree is a full sibling root, nothing shared.
+ *   - `<worldHome>/profiles/web/cordis.patch.yml` — per-world home pinning:
+ *     every home-resolving DSH plugin reads THIS tree's nested root.
+ *   - `<worldHome>/profiles/node_modules/@pgmi-builds/{adapter,hub}` — links
+ *     for the profile's bundle resolution and the inserted mount rows
+ *     (`@deepseek-ai/*` is loadProfile's heal farm, not ours).
+ *
+ * Link identity rule: both links point INSIDE the running line tree — the hub
+ * at this module's own package root, the adapter at its sibling
+ * `agent-<key>` directory — identical in the dev repo layout and inside the
+ * published single `super-dsh` package, so ctx0 and every world root share
+ * one hub/adapter instance with zero registry involvement.
+ *
+ * Returns the bare module base for `spawnWorld` (`…/profiles/node_modules/`),
+ * or null when the adapter sibling does not exist next to the hub (a foreign
+ * composition this module does not own — keep the caller's env/fallback path).
+ */
+import { existsSync, lstatSync, mkdirSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+const HUB_SCOPE = '@pgmi-builds';
+const HARNESS_SCOPE = '@deepseek-ai';
+/** The profile bundles every world tree composes besides its adapter. */
+const WORLD_BASE_BUNDLES = ['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app'];
+/**
+ * Provision one world's nested profile (idempotent: rewrites profile files,
+ * re-links packages — lstat-safe against dangling links). Returns the
+ * `bareModuleBaseUrl` for {@link spawnWorld}, or null when unresolvable.
+ *
+ * Never throws: any provisioning failure is logged and returns null so the
+ * calling world plugin degrades to a not-ready roster row instead of failing
+ * the loader entry — a failed apply would take down the whole host boot.
+ */
+export function provisionWorldProfile(opts) {
+    try {
+        return provisionWorldProfileUnchecked(opts);
+    }
+    catch (cause) {
+        console.error(`[super-dsh] provisioning world '${opts.key}' failed:`, cause);
+        return null;
+    }
+}
+function provisionWorldProfileUnchecked(opts) {
+    // Single-pack topology: this module lives at `<line>/agent-hub/dist/`, and
+    // every adapter is a SIBLING directory (`<line>/agent-<key>`) — the same
+    // layout in the repo (dev link: lines) and inside the published `super-dsh`
+    // package. The adapter link therefore points at the sibling; no registry
+    // resolution is involved anywhere.
+    const hubRoot = dirname(dirname(fileURLToPath(import.meta.url))); // <line>/agent-hub
+    const lineRoot = dirname(hubRoot); // monolith root / repo super-dsh/
+    const adapterDir = join(lineRoot, `agent-${opts.key}`);
+    if (!existsSync(join(adapterDir, 'package.json')))
+        return null;
+    const profileName = opts.profileName ?? 'web';
+    const profDir = join(opts.worldHome, 'profiles', profileName);
+    mkdirSync(profDir, { recursive: true });
+    writeFileSync(join(profDir, 'package.json'), JSON.stringify({
+        name: `aw-${opts.key}-world-profile`,
+        private: true,
+        dsh: { profile: { bundles: [...WORLD_BASE_BUNDLES, opts.adapterPkg] } },
+    }, null, 2) + '\n');
+    // Per-world home pinning (smoke.mjs parity): settings, credentials,
+    // attachments, shell env and skills all land inside `agents/<key>/`.
+    // (`agent-instructions` keeps its base `maxBytes` home — instruction
+    // discovery root, not agent data.)
+    writeFileSync(join(profDir, 'cordis.patch.yml'), [
+        '# Per-world home pinning (dshHomePath is this tree\'s nested home).',
+        ...['settings', 'credentials', 'attachment-local', 'shell-env', 'skill-filesystem'].flatMap((id) => [`- id: ${id}`, '  config:', '    dshHome: !!js dshHomePath()']),
+        '',
+    ].join('\n'));
+    // @pgmi-builds links for the world tree's bare-name resolution (profile
+    // bundles + the inserted mount rows). Dangling links first (lstat:
+    // existsSync is false for them, which skipped rmSync and crashed
+    // symlinkSync with EEXIST after repo moves).
+    const linkRoot = join(opts.worldHome, 'profiles', 'node_modules');
+    mkdirSync(join(linkRoot, HUB_SCOPE), { recursive: true });
+    const links = [
+        [opts.adapterPkg.slice(HUB_SCOPE.length + 1), adapterDir],
+        ['agent-hub', hubRoot],
+    ];
+    for (const [name, target] of links) {
+        const dst = join(linkRoot, HUB_SCOPE, name);
+        const st = lstatSync(dst, { throwIfNoEntry: false });
+        if (st)
+            rmSync(dst, { recursive: true, force: true });
+        symlinkSync(target, dst);
+    }
+    // The harness scope rides along as ONE scope-level link into the first
+    // `@deepseek-ai` directory visible from this module (the shared heal farm
+    // in a dsh home, the repo farm in dev) — every `@deepseek-ai/*` row of the
+    // world composition resolves through it without farming per package.
+    for (const searchPath of createRequire(import.meta.url).resolve.paths(`${HARNESS_SCOPE}/x`) ?? []) {
+        const scopeDir = join(searchPath, HARNESS_SCOPE);
+        if (!existsSync(scopeDir))
+            continue;
+        const dst = join(linkRoot, HARNESS_SCOPE);
+        const st = lstatSync(dst, { throwIfNoEntry: false });
+        if (st)
+            rmSync(dst, { recursive: true, force: true });
+        symlinkSync(scopeDir, dst);
+        break;
+    }
+    return join(opts.worldHome, 'profiles', 'node_modules') + '/';
+}

package/agent-hub/dist/world-web-server.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Per-world virtual webServer (AW-B DL3).
+ *
+ * A world's plugins must be able to declare ANY path they like (`/api`,
+ * `/plugins`, `/whatever-name-i-like`). Enumerating those namespaces in the
+ * carrier is wrong by construction — a third-party plugin may declare a new
+ * one at any time. So this class translates at REGISTRATION time:
+ *
+ *   world registers  { kind, path }        →  real registers { kind, `${labelPath}${path}` }
+ *   real receives    /<label>/<path>/...   →  plugin handler sees /<path>/...
+ *
+ * Consequences:
+ *  - any declared prefix lands under the label automatically; no list;
+ *  - two worlds may both own `/api` (they become `/omp/api`, `/codex/api`);
+ *  - ctx0 only ever sees the label namespaces, so a world cannot collide with
+ *    ctx0's own routes.
+ *
+ * Index rows stay world-local: this instance owns its taps and emits nothing
+ * on the shared tree (worlds run as their own cordis ROOTS, whose event buses
+ * are isolated — probe 2026-09-16: emit on root B never reaches root A).
+ */
+import { type IndexInjection } from '@deepseek-ai/dsh-host-webserver';
+/** Route match kind (mirrors the upstream contract). */
+export type WebRouteKind = 'exact' | 'prefix';
+/** The slice of node:http we touch (kept structural for testability). */
+export interface WorldRequest {
+    url?: string;
+}
+export interface WorldResponse {
+    writeHead(status: number, headers: Record<string, string>): unknown;
+    end(...args: unknown[]): unknown;
+}
+/** A world route handler as plugins write it. */
+export type WorldHandler = (req: WorldRequest, ...rest: never[]) => void | Promise<void>;
+/** One named route registration (structural mirror of the upstream type). */
+export interface WorldWebRoute {
+    kind: WebRouteKind;
+    path: string;
+    handler: (req: WorldRequest, res: WorldResponse) => void | Promise<void>;
+}
+/** One exact-path HTTP upgrade registration. */
+export interface WorldWebUpgradeRoute {
+    path: string;
+    handler: (req: WorldRequest, socket: unknown, head: Buffer) => void | Promise<void>;
+}
+/** The real (ctx0) webServer surface this world forwards into. */
+export interface RealWebServerFace {
+    register(route: {
+        kind: WebRouteKind;
+        path: string;
+        handler: never;
+    }): () => void;
+    registerUpgrade(route: {
+        path: string;
+        handler: never;
+    }): () => void;
+    registerFallback(handler: never): () => void;
+    tapIndex?(transform: (html: string) => string): () => void;
+    readonly port?: number;
+    readonly host?: string;
+}
+/** Options: how this world collects its own index rows. */
+export interface WorldWebServerOptions {
+    /**
+     * Push the world's index injection rows. The world plugin supplies a
+     * function that emits on the WORLD root (never on ctx0's tree).
+     */
+    onIndexInject?(table: IndexInjection[]): void;
+    /**
+     * ctx0's index authorization, applied to every route this mount forwards
+     * (pages, assets, fallback): the SAME gate native uses, so one cookie opens
+     * everything under the origin. The world owns no listener and the browser
+     * reaches it only through this mount, so authentication is decided HERE, in
+     * ctx0's auth domain — never by the world's own browser-auth gate. A false
+     * return means the authorizer already wrote the response (401 / 303).
+     */
+    authorize?(req: WorldRequest, res: WorldResponse): boolean;
+}
+/** Remove the mount label from `req.url`, preserving the trailing query. */
+export declare function stripLabelFromUrl(url: string | undefined, labelPath: string): string;
+/** One world's web surface, mounted under `<labelPath>`. */
+export declare class WorldWebServer {
+    readonly labelPath: string;
+    private readonly real;
+    private readonly options;
+    private readonly disposers;
+    private readonly taps;
+    /**
+     * @param labelPath - mount root, e.g. `/omp` (no trailing slash).
+     * @param real - the ctx0 webServer this world's routes forward into.
+     * @param options - world-local index row source.
+     */
+    constructor(labelPath: string, real: RealWebServerFace, options?: WorldWebServerOptions);
+    /** The ctx0 listener port (read-through; the world owns no socket). */
+    get port(): number;
+    /** The ctx0 bind host (read-through). */
+    get host(): string;
+    /**
+     * The RPC channel belongs to the HUB, not to the world: the hub's carrier
+     * answers `/<label>/api/*` and `/<label>/api/remote.mux` with ctx0's auth
+     * domain, so the world's own connection/gateway registrations are swallowed
+     * here (returning a no-op disposer) instead of colliding on the real table.
+     * Non-envelope GET/HEAD traffic on `/<label>/api` still reaches the world's
+     * exact Fetch routes: `world-entry` publishes the world connection's shared
+     * `/api` fetch handler through `world-host`, and the carrier forwards into
+     * it AFTER ctx0's fence — the world's own browser-auth gate is never in the
+     * path (a different tree, a different secret).
+     */
+    private static hubOwned;
+    /**
+     * Mount-side authentication for one forwarded world route.
+     *
+     * The world's own browser-auth gate never sees a browser: it is reached
+     * in-ctx through this mount, and its cookie secret belongs to a different
+     * tree (every runtime is nested with its own home). So the decision is made
+     * here, with ctx0's connection: the same cookie that authenticated `<label>`
+     * in ctx0 authorizes its pages and assets.
+     */
+    private gate;
+    /** Register a world route; the real table stores its translated path. */
+    register(route: WorldWebRoute): () => void;
+    /** Register a world upgrade route (verbatim exact path; hub-owned RPC paths are swallowed). */
+    registerUpgrade(route: WorldWebUpgradeRoute): () => void;
+    /**
+     * Claim the world's SPA fallback: the ctx0 fallback seat is already owned by
+     * native frontend-static, so the world's fallback lives as a PREFIX route on
+     * the mount path (`/<label>`), which also keeps it inside the label namespace.
+     */
+    registerFallback(handler: (req: WorldRequest, res: WorldResponse) => void | Promise<void>): () => void;
+    /**
+     * Fix up HTML on its way out. Two passes belong here, in this order:
+     *
+     *   1. the world's own frontend-static injects `<base href="/">` AFTER
+     *      `renderIndex`, and the FIRST `<base>` wins in a document, so the mount
+     *      base is re-pinned on the bytes actually sent;
+     *   2. the agent roster is injected LAST — its values are the mount paths of
+     *      OTHER worlds (`/`, `/omp/`, `/codex/`), which the mount pass above
+     *      would otherwise re-root under this world's label.
+     */
+    private htmlRewrite;
+    /** World-local raw index transform (never forwarded to ctx0's taps). */
+    tapIndex(transform: (html: string) => string): () => void;
+    /** Apply this world's taps in registration order. */
+    applyIndexTaps(html: string): string;
+    /** Collect this world's structured rows (supplied by the world root). */
+    collectIndexInjections(): IndexInjection[];
+    /**
+     * Render the world's index: the client mount shim first (it must run before
+     * the app entry module), then the world's rows, then its taps, then the mount
+     * pass (base pinned at `/<label>/`, root-absolute strings re-rooted).
+     *
+     * The agent roster is injected LAST, after the mount pass: its values are
+     * mount paths of OTHER worlds (`/`, `/omp/`, `/codex/`), and the pass would
+     * happily re-root them under this world's label.
+     */
+    renderIndex(html: string): string;
+    /** Unregister every translated route (world unloaded). */
+    dispose(): void;
+    /** Wrap a plugin handler so it sees the world-relative URL. */
+    private strip;
+    private track;
+}