super-dsh 0.1.0 → 0.1.2

package/agent-hub/dist/envelope.js

@@ -0,0 +1,92 @@
+/**
+ * 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.
+ */
+/** Upstream's endpoint segment pattern (`rpc-host.ts`). */
+export const ENDPOINT_SEGMENT_PATTERN = /^[A-Za-z0-9_$.-]+$/;
+/** Envelope-level failure carrying the wire error to answer with. */
+export class EnvelopeError extends Error {
+    wire;
+    constructor(wire) {
+        super(wire.message);
+        this.wire = wire;
+        this.name = 'EnvelopeError';
+    }
+}
+function badRequest(message) {
+    throw new EnvelopeError({ code: 'gateway/bad-request', message });
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * 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 function parseClientRequest(text) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        badRequest('invalid client-request message');
+    }
+    if (!isRecord(raw))
+        badRequest('invalid client-request message');
+    if (raw['type'] !== 'client-request')
+        badRequest('invalid client-request message');
+    const rpcId = raw['rpcId'];
+    const method = raw['method'];
+    if (typeof rpcId !== 'string' || rpcId === '')
+        badRequest('invalid client-request message');
+    if (typeof method !== 'string' || method === '')
+        badRequest('invalid client-request message');
+    const segments = method.split('/');
+    if (segments.some(segment => segment === '' || !ENDPOINT_SEGMENT_PATTERN.test(segment))) {
+        badRequest('invalid client-request message');
+    }
+    return { rpcId, method, payload: raw['payload'] };
+}
+/** Serialize a successful server response from a raw value. */
+export function serverResponse(rpcId, value) {
+    return JSON.stringify({ type: 'server-response', rpcId, result: { ok: true, value } });
+}
+/**
+ * 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 function serverResult(rpcId, result) {
+    return JSON.stringify({ type: 'server-response', rpcId, result });
+}
+/** Serialize a failed server response. */
+export function serverError(rpcId, error) {
+    return JSON.stringify({ type: 'server-response', rpcId, result: { ok: false, error } });
+}
+/** Normalize an unknown thrown value into a wire error. */
+export function wireErrorOf(error) {
+    if (error instanceof EnvelopeError)
+        return error.wire;
+    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, ...(error['details'] === undefined ? {} : { details: error['details'] }) };
+        }
+    }
+    return {
+        code: 'gateway/internal-error',
+        message: error instanceof Error ? error.message : String(error),
+    };
+}

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

@@ -0,0 +1,28 @@
+/**
+ * @pgmi-builds/agent-hub — plugin entry (host half).
+ *
+ * DL7 (2026-09-16): there is NO server-side selected state. The module-level
+ * selector and the instance-delegation wrapper that consumed it were removed;
+ * world ownership is per-request and travels on the mount path:
+ *
+ *   /<label>/...              → that world's web surface (carrier.ts, AW-B)
+ *   /api/...                  → ctx0/native, untouched (upstream route owner)
+ *
+ * This file therefore only mounts the CTX0-owned control plane today. The
+ * per-world mount registers through `carrier.ts` (AW-B tasks 2-9), which calls
+ * the addressed world's own `typertGateway` instance directly — again without
+ * any shared selection value.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Stable Cordis plugin name. */
+export declare const name = "agent-hub";
+/**
+ * The plugin form (row contract): applied when the row mounts.
+ *
+ * Two CTX0-owned contributions, neither carrying any selection value:
+ *   - the world inventory control plane (read-only);
+ *   - the agent roster row baked into ctx0's own index, so the selector lists
+ *     every mount path the hub currently serves.
+ */
+export declare function apply(ctx: Context): void;
+export default apply;

package/agent-hub/dist/gateway.js

@@ -0,0 +1,18 @@
+import { registerSelectorRpc, registryTargets } from './rpc.js';
+import { agentRosterRow } from './agent-roster.js';
+/** Stable Cordis plugin name. */
+export const name = 'agent-hub';
+/**
+ * The plugin form (row contract): applied when the row mounts.
+ *
+ * Two CTX0-owned contributions, neither carrying any selection value:
+ *   - the world inventory control plane (read-only);
+ *   - the agent roster row baked into ctx0's own index, so the selector lists
+ *     every mount path the hub currently serves.
+ */
+export function apply(ctx) {
+    registerSelectorRpc(ctx, registryTargets);
+    const on = ctx.on;
+    on?.call(ctx, 'webserver/index-inject', (table) => { table.push(agentRosterRow()); });
+}
+export default apply;

package/agent-hub/dist/index-pass.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Mount HTML pass (AW-B DL1/DL8 server half).
+ *
+ * The world dist is built with RELATIVE asset URLs (`./assets/...`), so a
+ * `<base>` pointing at the mount makes every relative reference resolve under
+ * `/<label>/`. Root-absolute strings (the boot graph's `/plugins/...` URLs,
+ * injected script sources, `href="/"`-style anchors) do NOT follow `<base>`,
+ * so they are re-rooted explicitly — one generic rule, no namespace list.
+ */
+/**
+ * Rewrite a world index for serving under `<labelPath>/`.
+ *
+ * - pins `<base>` at the mount (inserting one after `<head>` when absent);
+ * - prefixes every double-quoted root-absolute string that is not already
+ *   mounted and not protocol-relative (`//host/...`);
+ * - idempotent (a second pass changes nothing).
+ *
+ * @param html - the world's index.html (already rendered with its own rows).
+ * @param labelPath - mount root, e.g. `/omp`.
+ * @returns the mount-ready HTML.
+ */
+export declare function rewriteIndexHtml(html: string, labelPath: string): string;

package/agent-hub/dist/index-pass.js

@@ -0,0 +1,47 @@
+/**
+ * Mount HTML pass (AW-B DL1/DL8 server half).
+ *
+ * The world dist is built with RELATIVE asset URLs (`./assets/...`), so a
+ * `<base>` pointing at the mount makes every relative reference resolve under
+ * `/<label>/`. Root-absolute strings (the boot graph's `/plugins/...` URLs,
+ * injected script sources, `href="/"`-style anchors) do NOT follow `<base>`,
+ * so they are re-rooted explicitly — one generic rule, no namespace list.
+ */
+/** Root of the mount including the trailing slash (`/omp` → `/omp/`). */
+function mountPrefix(labelPath) {
+    return labelPath.endsWith('/') ? labelPath : `${labelPath}/`;
+}
+/**
+ * Rewrite a world index for serving under `<labelPath>/`.
+ *
+ * - pins `<base>` at the mount (inserting one after `<head>` when absent);
+ * - prefixes every double-quoted root-absolute string that is not already
+ *   mounted and not protocol-relative (`//host/...`);
+ * - idempotent (a second pass changes nothing).
+ *
+ * @param html - the world's index.html (already rendered with its own rows).
+ * @param labelPath - mount root, e.g. `/omp`.
+ * @returns the mount-ready HTML.
+ */
+export function rewriteIndexHtml(html, labelPath) {
+    if (typeof labelPath !== 'string' || !labelPath.startsWith('/') || labelPath === '/' || labelPath.endsWith('/')) {
+        throw new Error(`index-pass: labelPath must start with "/" and carry no trailing slash, got ${JSON.stringify(labelPath)}`);
+    }
+    const prefix = mountPrefix(labelPath);
+    let out = html;
+    if (/<base\b[^>]*>/i.test(out)) {
+        out = out.replace(/<base\b[^>]*>/i, `<base href="${prefix}">`);
+    }
+    else if (/<head(?:\s[^>]*)?>/i.test(out)) {
+        out = out.replace(/<head(?:\s[^>]*)?>/i, open => `${open}<base href="${prefix}">`);
+    }
+    out = out.replace(/"(\/[^"]*)"/g, (whole, path) => {
+        if (path.startsWith('//'))
+            return whole;
+        // Load-bearing contract: client-shim.ts derives its storage NS from the surviving "<label>/" literal (regression test: the storage NS survives the mount HTML pass). Changing this exclusion breaks that coupling.
+        if (path.startsWith(prefix))
+            return whole;
+        return `"${prefix}${path.slice(1)}"`;
+    });
+    return out;
+}

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

@@ -0,0 +1,29 @@
+/**
+ * @pgmi-builds/agent-hub — host half public surface (Agent Worlds line).
+ *
+ * The line owns the switch and the gateway (per super-dsh/AGENTS.md):
+ * the world inventory control plane + the foreign agent roster + the world
+ * spawner, and (AW-B) the per-world mount carrier.
+ *
+ * DL7 (2026-09-16): the app-level selector value is GONE. World ownership is
+ * per-request: the addressed world is the mount path of the request
+ * (`/<label>/...`). `/api/*` stays ctx0/native and untouched.
+ */
+export { handleAgentRuntime, registerSelectorRpc, AGENT_RUNTIME_RPC_PATH, registryTargets, type RuntimeTargetSource } from './rpc.js';
+export { registerForeignTarget, unregisterForeignTarget, getTarget, listRuntimeKeys, type ForeignTarget, type GatewayFace } from './targets.js';
+export { registerAgent, unregisterAgent, setReady, listAgents, onRosterChanged, type RosterEntry } from './roster.js';
+export { spawnWorld, type SpawnWorldOptions } from './spawn-world.js';
+export { provisionWorldProfile, type ProvisionWorldOptions } from './world-provision.js';
+export { claimLabel, labelOf, releaseLabel, listLabels, type LabelClaim, type ClaimOptions } from './labels.js';
+export { WorldWebServer, stripLabelFromUrl, type WorldWebRoute, type WorldWebUpgradeRoute, type RealWebServerFace } from './world-web-server.js';
+export { parseClientRequest, serverResponse, serverError, serverResult, wireErrorOf, EnvelopeError, type ClientRequestEnvelope, type WireError } from './envelope.js';
+export { WorldMuxServer, parseClientMessage, defaultFailure, type MuxOpen, type MuxFailure, type WorldMuxOptions } from './world-mux.js';
+export { mountWorld, rewriteIndexHtml, type CarrierGatewayFace, type MountWorldOptions, type MountedWorld } from './carrier.js';
+export { renderClientShim } from './client-shim.js';
+export { agentLinks, agentRosterRow, AGENT_ROSTER_GLOBAL, type AgentLink } from './agent-roster.js';
+export { createOwnershipIndex, type OwnershipIndex, type OwnershipRow } from './ownership.js';
+export { registerHostMount, takeHostMount, listHostMounts, noteWorldServer, worldServerOf, type HostMount } from './world-host.js';
+export { worldMountPatches, WORLD_MOUNT_PLUGIN, WORLD_MOUNT_ROW_ID, type WorldPatchLayer } from './world-mount.js';
+export { default as worldApply, name as worldPluginName, type Config as WorldEntryConfig } from './world-entry.js';
+export { default as joinApply, name as worldJoinPluginName, type Config as WorldJoinConfig } from './world-join.js';
+export { default } from './gateway.js';

package/agent-hub/dist/index.js

@@ -0,0 +1,29 @@
+/**
+ * @pgmi-builds/agent-hub — host half public surface (Agent Worlds line).
+ *
+ * The line owns the switch and the gateway (per super-dsh/AGENTS.md):
+ * the world inventory control plane + the foreign agent roster + the world
+ * spawner, and (AW-B) the per-world mount carrier.
+ *
+ * DL7 (2026-09-16): the app-level selector value is GONE. World ownership is
+ * per-request: the addressed world is the mount path of the request
+ * (`/<label>/...`). `/api/*` stays ctx0/native and untouched.
+ */
+export { handleAgentRuntime, registerSelectorRpc, AGENT_RUNTIME_RPC_PATH, registryTargets } from './rpc.js';
+export { registerForeignTarget, unregisterForeignTarget, getTarget, listRuntimeKeys } from './targets.js';
+export { registerAgent, unregisterAgent, setReady, listAgents, onRosterChanged } from './roster.js';
+export { spawnWorld } from './spawn-world.js';
+export { provisionWorldProfile } from './world-provision.js';
+export { claimLabel, labelOf, releaseLabel, listLabels } from './labels.js';
+export { WorldWebServer, stripLabelFromUrl } from './world-web-server.js';
+export { parseClientRequest, serverResponse, serverError, serverResult, wireErrorOf, EnvelopeError } from './envelope.js';
+export { WorldMuxServer, parseClientMessage, defaultFailure } from './world-mux.js';
+export { mountWorld, rewriteIndexHtml } from './carrier.js';
+export { renderClientShim } from './client-shim.js';
+export { agentLinks, agentRosterRow, AGENT_ROSTER_GLOBAL } from './agent-roster.js';
+export { createOwnershipIndex } from './ownership.js';
+export { registerHostMount, takeHostMount, listHostMounts, noteWorldServer, worldServerOf } from './world-host.js';
+export { worldMountPatches, WORLD_MOUNT_PLUGIN, WORLD_MOUNT_ROW_ID } from './world-mount.js';
+export { default as worldApply, name as worldPluginName } from './world-entry.js';
+export { default as joinApply, name as worldJoinPluginName } from './world-join.js';
+export { default } from './gateway.js';

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

@@ -0,0 +1,45 @@
+/**
+ * Label table (AW-B DL2/DL4): one world ↔ one mount path under the ctx0 origin.
+ *
+ * The addressed world is the request's path (`/<label>/...`), so the label is
+ * the ONLY routing key. Reserving it must be atomic against the real
+ * webServer's duplicate-registration throw — that throw is the only collision
+ * signal the framework offers (the route tables are private and there is no
+ * query API), so it is used here as the probe.
+ *
+ * A collision is a composition-level conflict and must be loud; an optional
+ * alternate root lets a deployment re-home instead of failing to boot.
+ */
+/** One reserved mount path. */
+export interface LabelClaim {
+    /** Runtime key (`omp`, `codex`, …). */
+    readonly key: string;
+    /** Reserved mount root, e.g. `/omp` or `/_agents/omp` (no trailing slash). */
+    readonly path: string;
+    /** Release the claim (idempotent). */
+    release(): void;
+}
+/** How to reserve a path: the injected real-webServer registration. */
+export interface ClaimOptions {
+    /** Attempt a prefix registration; throws when `(kind, path)` is already taken. */
+    register(path: string): () => void;
+    /** Optional root prefix (default: the origin root). */
+    root?: string;
+    /** Candidate roots to try, in order, when the clean path is taken. */
+    alternateRoots?: readonly string[];
+}
+/**
+ * Reserve the mount path for `key`.
+ * @param key - runtime key (one path segment).
+ * @param opts - registration probe plus optional roots.
+ * @returns the live claim.
+ */
+export declare function claimLabel(key: string, opts: ClaimOptions): LabelClaim;
+/** The reserved mount root for a key, or undefined when unclaimed. */
+export declare function labelOf(key: string): string | undefined;
+/** Release a key's claim; unknown keys are a no-op. */
+export declare function releaseLabel(key: string): void;
+/** Claimed keys, registration order. */
+export declare function listLabels(): string[];
+/** Test/introspection helper: is this object a claim? */
+export declare function isLabelClaim(value: unknown): value is LabelClaim;

package/agent-hub/dist/labels.js

@@ -0,0 +1,83 @@
+/**
+ * Label table (AW-B DL2/DL4): one world ↔ one mount path under the ctx0 origin.
+ *
+ * The addressed world is the request's path (`/<label>/...`), so the label is
+ * the ONLY routing key. Reserving it must be atomic against the real
+ * webServer's duplicate-registration throw — that throw is the only collision
+ * signal the framework offers (the route tables are private and there is no
+ * query API), so it is used here as the probe.
+ *
+ * A collision is a composition-level conflict and must be loud; an optional
+ * alternate root lets a deployment re-home instead of failing to boot.
+ */
+const claims = new Map();
+function isRecordLike(value) {
+    return typeof value === 'object' && value !== null;
+}
+/** Reject keys that cannot be a single path segment. */
+function assertKey(key) {
+    if (typeof key !== 'string' || key === '' || key.includes('/') || key.includes('?')) {
+        throw new Error(`labels: invalid label key ${JSON.stringify(key)} (one non-empty path segment required)`);
+    }
+}
+function joinRoot(root, key) {
+    const trimmed = root.replace(/\/+$/, '');
+    return trimmed === '' ? `/${key}` : `${trimmed}/${key}`;
+}
+/**
+ * Reserve the mount path for `key`.
+ * @param key - runtime key (one path segment).
+ * @param opts - registration probe plus optional roots.
+ * @returns the live claim.
+ */
+export function claimLabel(key, opts) {
+    assertKey(key);
+    const existing = claims.get(key);
+    if (existing !== undefined) {
+        throw new Error(`labels: key ${JSON.stringify(key)} already claimed at "${existing.path}"`);
+    }
+    const roots = [opts.root ?? '', ...(opts.alternateRoots ?? [])];
+    const tried = [];
+    for (const root of roots) {
+        const path = joinRoot(root, key);
+        if (tried.includes(path))
+            continue;
+        tried.push(path);
+        let dispose;
+        try {
+            dispose = opts.register(path);
+        }
+        catch {
+            continue;
+        }
+        const claim = {
+            key,
+            path,
+            release: () => {
+                if (claims.get(key)?.path !== path)
+                    return;
+                claims.delete(key);
+                dispose?.();
+            },
+        };
+        claims.set(key, claim);
+        return claim;
+    }
+    throw new Error(`labels: no free mount path for ${JSON.stringify(key)} (tried ${tried.map(p => `"${p}"`).join(', ')})`);
+}
+/** The reserved mount root for a key, or undefined when unclaimed. */
+export function labelOf(key) {
+    return claims.get(key)?.path;
+}
+/** Release a key's claim; unknown keys are a no-op. */
+export function releaseLabel(key) {
+    claims.get(key)?.release();
+}
+/** Claimed keys, registration order. */
+export function listLabels() {
+    return [...claims.keys()];
+}
+/** Test/introspection helper: is this object a claim? */
+export function isLabelClaim(value) {
+    return isRecordLike(value) && typeof value['key'] === 'string' && typeof value['path'] === 'string';
+}

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

@@ -0,0 +1,37 @@
+/**
+ * Session → world ownership index (AW-B DL9/DL10).
+ *
+ * The mount path addresses the world for UI traffic, but a session-scoped
+ * caller (resume, export, a deep link) may only carry a sessionId. Resolving it
+ * must be O(1) and must NEVER degrade into a probe waterfall: a miss triggers
+ * AT MOST one bounded refresh (in-flight refreshes coalesce), and a miss after
+ * that refresh is a miss — the caller fails where it asked instead of asking
+ * every world in turn.
+ */
+/** One ownership row returned by a refresh. */
+export interface OwnershipRow {
+    sessionId: string;
+    /** Runtime key (`native`, `omp`, …). */
+    key: string;
+}
+/** The ownership index surface. */
+export interface OwnershipIndex {
+    /** Record (or overwrite) one ownership. */
+    set(sessionId: string, key: string): void;
+    /** Drop one ownership (session deleted). */
+    forget(sessionId: string): void;
+    /** Synchronous lookup; performs NO refresh. */
+    lookup(sessionId: string): string | undefined;
+    /** Lookup, then at most one bounded refresh, then lookup again. */
+    resolve(sessionId: string): Promise<string | undefined>;
+    /** Current index size (diagnostics/tests). */
+    size(): number;
+    /** Drop everything (world roster replaced). */
+    clear(): void;
+}
+/**
+ * Create an ownership index.
+ * @param refresh - optional bounded re-read of the ownership rows.
+ * @returns the index.
+ */
+export declare function createOwnershipIndex(refresh?: () => Promise<readonly OwnershipRow[]>): OwnershipIndex;

package/agent-hub/dist/ownership.js

@@ -0,0 +1,54 @@
+/**
+ * Session → world ownership index (AW-B DL9/DL10).
+ *
+ * The mount path addresses the world for UI traffic, but a session-scoped
+ * caller (resume, export, a deep link) may only carry a sessionId. Resolving it
+ * must be O(1) and must NEVER degrade into a probe waterfall: a miss triggers
+ * AT MOST one bounded refresh (in-flight refreshes coalesce), and a miss after
+ * that refresh is a miss — the caller fails where it asked instead of asking
+ * every world in turn.
+ */
+/**
+ * Create an ownership index.
+ * @param refresh - optional bounded re-read of the ownership rows.
+ * @returns the index.
+ */
+export function createOwnershipIndex(refresh) {
+    const owners = new Map();
+    let inflight;
+    const runRefresh = () => {
+        if (inflight !== undefined)
+            return inflight;
+        const started = (async () => {
+            const rows = refresh === undefined ? [] : await refresh();
+            for (const row of rows)
+                owners.set(row.sessionId, row.key);
+        })();
+        inflight = started.finally(() => { inflight = undefined; });
+        return inflight;
+    };
+    return {
+        set(sessionId, key) {
+            owners.set(sessionId, key);
+        },
+        forget(sessionId) {
+            owners.delete(sessionId);
+        },
+        lookup(sessionId) {
+            return owners.get(sessionId);
+        },
+        async resolve(sessionId) {
+            const hit = owners.get(sessionId);
+            if (hit !== undefined)
+                return hit;
+            await runRefresh();
+            return owners.get(sessionId);
+        },
+        size() {
+            return owners.size;
+        },
+        clear() {
+            owners.clear();
+        },
+    };
+}

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

@@ -0,0 +1,28 @@
+/**
+ * Foreign agent roster (S2: plugin-presence IS the roster).
+ *
+ * No config file: an agent is in the roster exactly while its adapter
+ * plugin is loaded and registered. Adapter plugins self-register on
+ * activation (key/label/ready) and the RuntimeSeat chip consumes the
+ * snapshot. Roster entries are inventory only: they carry NO selection —
+ * the addressed world is the request's mount path (`DL7`, 2026-09-16).
+ * one authority.
+ */
+export interface RosterEntry {
+    /** Runtime key (`omp`, `codex`, …) — what the selector addresses. */
+    key: string;
+    /** Human label for the selector chip. */
+    label: string;
+    /** True once the adapter's world context is spawned and its target registered. */
+    ready: boolean;
+}
+/** Register an agent. Duplicate keys are a plugin bug — throw loud. */
+export declare function registerAgent(entry: RosterEntry): void;
+/** Drop an agent (adapter plugin disposed). */
+export declare function unregisterAgent(key: string): void;
+/** Flip readiness (world spawned / disposed). Unknown keys are a plugin bug. */
+export declare function setReady(key: string, ready: boolean): void;
+/** Snapshot copy — callers can hold it without aliasing the roster. */
+export declare function listAgents(): RosterEntry[];
+/** Subscribe to roster changes; returns an unsubscribe function. */
+export declare function onRosterChanged(fn: (entries: RosterEntry[]) => void): () => void;

package/agent-hub/dist/roster.js

@@ -0,0 +1,38 @@
+const entries = new Map();
+const listeners = new Set();
+function emit() {
+    const snap = listAgents();
+    for (const fn of listeners)
+        fn(snap);
+}
+/** Register an agent. Duplicate keys are a plugin bug — throw loud. */
+export function registerAgent(entry) {
+    if (entries.has(entry.key))
+        throw new Error(`roster: duplicate agent key ${entry.key}`);
+    entries.set(entry.key, { ...entry });
+    emit();
+}
+/** Drop an agent (adapter plugin disposed). */
+export function unregisterAgent(key) {
+    entries.delete(key);
+    emit();
+}
+/** Flip readiness (world spawned / disposed). Unknown keys are a plugin bug. */
+export function setReady(key, ready) {
+    const e = entries.get(key);
+    if (!e)
+        throw new Error(`roster: unknown agent ${key}`);
+    e.ready = ready;
+    emit();
+}
+/** Snapshot copy — callers can hold it without aliasing the roster. */
+export function listAgents() {
+    return [...entries.values()].map((e) => ({ ...e }));
+}
+/** Subscribe to roster changes; returns an unsubscribe function. */
+export function onRosterChanged(fn) {
+    listeners.add(fn);
+    return () => {
+        listeners.delete(fn);
+    };
+}

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

@@ -0,0 +1,38 @@
+/**
+ * Control-plane RPC face for the agents hub (DL7: NO server-side selection).
+ *
+ * Auth conclusion (upstream source, inherited from the shelved route): every
+ * upstream `/api/*` feature mounts via `ctx.connection.fetch.register(...)` —
+ * the client-connection service owns the single `/api` prefix webServer route
+ * and runs the Host/Origin browser-trust fence + persistent browser auth
+ * before dispatching. Registering our own webServer route would bypass that
+ * fence; we mount through `connection.fetch` and inherit it.
+ *
+ * This face is superd-owned control traffic and is ALWAYS answered by CTX0:
+ * it reports which worlds exist. It carries no selection: world ownership is
+ * per-request and travels on the mount path (`/<label>/...`, see carrier.ts),
+ * so two tabs on two worlds cannot step on each other.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** The shared-channel Fetch route path this RPC face owns. */
+export declare const AGENT_RUNTIME_RPC_PATH = "/api/agent-runtime";
+/** What the RPC reads to compute the `available` list. */
+export interface RuntimeTargetSource {
+    /** Registered runtime keys, including `native`. */
+    listRuntimes(): string[];
+}
+/** The live registry view: native plus every registered foreign context. */
+export declare const registryTargets: RuntimeTargetSource;
+/**
+ * The control-plane handler: world inventory only.
+ * @param request - the incoming `/api/agent-runtime` request.
+ * @param source - live runtime registry view.
+ * @returns the JSON response.
+ */
+export declare function handleAgentRuntime(request: Request, source: RuntimeTargetSource): Promise<Response>;
+/**
+ * Register the control-plane RPC face on the shared `/api` connection channel
+ * (behind the standard browser-trust + auth fence). No-op when the
+ * `connection` service is absent (e.g. fake-ctx unit tests).
+ */
+export declare function registerSelectorRpc(ctx: Context, source: RuntimeTargetSource): void;

package/agent-hub/dist/rpc.js

@@ -0,0 +1,52 @@
+import { listRuntimeKeys } from './targets.js';
+import { agentLinks } from './agent-roster.js';
+/** The shared-channel Fetch route path this RPC face owns. */
+export const AGENT_RUNTIME_RPC_PATH = '/api/agent-runtime';
+/** The live registry view: native plus every registered foreign context. */
+export const registryTargets = {
+    listRuntimes: listRuntimeKeys,
+};
+function json(status, body) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { 'content-type': 'application/json' },
+    });
+}
+/**
+ * The control-plane handler: world inventory only.
+ * @param request - the incoming `/api/agent-runtime` request.
+ * @param source - live runtime registry view.
+ * @returns the JSON response.
+ */
+export async function handleAgentRuntime(request, source) {
+    const available = source.listRuntimes();
+    if (request.method === 'GET' || request.method === 'HEAD') {
+        // The selector asks this face for the roster: keys AND the mount path each
+        // key is addressed by. Read-only — the roster carries no selection.
+        return json(200, { available, agents: agentLinks() });
+    }
+    // A POST that used to switch a global selector has no meaning any more:
+    // the addressed world is the mount path of the request, not a shared value.
+    return json(400, {
+        error: 'selection is per-request (mount path); no server-side switch',
+        available,
+    });
+}
+/**
+ * Register the control-plane RPC face on the shared `/api` connection channel
+ * (behind the standard browser-trust + auth fence). No-op when the
+ * `connection` service is absent (e.g. fake-ctx unit tests).
+ */
+export function registerSelectorRpc(ctx, source) {
+    ctx.inject(['connection'], (connCtx) => {
+        const fetchFace = Reflect.get(connCtx, 'connection')?.fetch;
+        if (fetchFace === undefined)
+            return; // connection not actually present (test ctx)
+        connCtx.effect(() => fetchFace.register({
+            path: AGENT_RUNTIME_RPC_PATH,
+            methods: ['GET', 'POST'],
+            requestBody: 'buffered',
+            fetch: (request) => handleAgentRuntime(request, source),
+        }), 'agent-hub: /api/agent-runtime route');
+    });
+}