super-dsh 0.1.5 → 0.1.9

package/superd-hub/dist/machines.js

@@ -0,0 +1,125 @@
+/**
+ * Machine registry (mesh P1, spec §3.1/§3.3): the persisted identity of
+ * THIS machine (`self`, owner-minted m4 per D4) plus the remote machine
+ * rows created by pairing.
+ *
+ * Pure module — no cordis dependencies. All state lives in
+ * `<home>/superd/machines.json` (0600, atomic tmp+rename writes); every
+ * mutation is a read-modify-write of the whole file with no in-process
+ * cache, which is sufficient at P1 machine counts. A missing or
+ * unreadable file reads as the empty shape (`self.id === ''` = not yet
+ * minted); `ensureSelf` mints lazily on first need and never re-mints.
+ */
+import { randomInt } from 'node:crypto';
+import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+const ID_ALPHABET = 'abcdefghijklmnopqrstuvwxyz0123456789';
+const MINT_MAX_ATTEMPTS = 32;
+function machinesPath(home) {
+    return join(home, 'superd', 'machines.json');
+}
+function emptyMachines() {
+    return { self: { id: '', label: '' }, remotes: [] };
+}
+function isMachineRow(v) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const r = v;
+    return (typeof r.id === 'string' && typeof r.name === 'string' && typeof r.label === 'string' &&
+        typeof r.origin === 'string' && typeof r.enabled === 'boolean' && typeof r.addedAt === 'number' &&
+        (r.token === undefined || typeof r.token === 'string') &&
+        (r.cookie === undefined || typeof r.cookie === 'string') &&
+        (r.execEnabled === undefined || r.execEnabled === true || r.execEnabled === false));
+}
+/** Mint a random short id over [a-z0-9], re-minting on collision with `taken`; loud after 32 attempts. */
+export function mintShortId(len, taken) {
+    const used = new Set(taken);
+    for (let attempt = 0; attempt < MINT_MAX_ATTEMPTS; attempt++) {
+        let id = '';
+        for (let i = 0; i < len; i++)
+            id += ID_ALPHABET[randomInt(ID_ALPHABET.length)];
+        if (!used.has(id))
+            return id;
+    }
+    throw new Error(`machines: short-id space exhausted after ${MINT_MAX_ATTEMPTS} attempts (len=${len})`);
+}
+/** Read the registry; a missing or unreadable/corrupt file degrades to the empty shape (never throws). */
+export function loadMachines(home) {
+    let raw;
+    try {
+        raw = readFileSync(machinesPath(home), 'utf8');
+    }
+    catch {
+        return emptyMachines();
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return emptyMachines();
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return emptyMachines();
+    const o = parsed;
+    const self = o.self;
+    if (typeof self !== 'object' || self === null)
+        return emptyMachines();
+    const s = self;
+    if (typeof s.id !== 'string' || typeof s.label !== 'string' || !Array.isArray(o.remotes)) {
+        return emptyMachines();
+    }
+    return { self: { id: s.id, label: s.label }, remotes: o.remotes.filter(isMachineRow) };
+}
+/** Persist the whole registry: recursive mkdir, tmp write, chmod 0600, atomic rename. */
+export function saveMachines(home, file) {
+    if (typeof file.self?.id !== 'string' || typeof file.self?.label !== 'string' || !Array.isArray(file.remotes)) {
+        throw new TypeError('machines: save rejected — file must be {self: {id, label}, remotes: []}');
+    }
+    for (const r of file.remotes) {
+        if (typeof r?.id !== 'string' || r.id === '' || typeof r.name !== 'string' || r.name === '' ||
+            typeof r.origin !== 'string' || r.origin === '') {
+            throw new TypeError('machines: save rejected — row id/name/origin must be non-empty strings');
+        }
+    }
+    const dir = join(home, 'superd');
+    mkdirSync(dir, { recursive: true });
+    const target = machinesPath(home);
+    const tmp = `${target}.tmp`;
+    writeFileSync(tmp, JSON.stringify(file, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 });
+    chmodSync(tmp, 0o600);
+    renameSync(tmp, target);
+}
+/** Lazily mint + persist the self identity; an already-minted self is returned unchanged. */
+export function ensureSelf(home, fallbackLabel) {
+    const file = loadMachines(home);
+    if (file.self.id !== '')
+        return file.self;
+    const taken = new Set([...file.remotes.map((r) => r.id)]);
+    const self = { id: mintShortId(4, taken), label: fallbackLabel };
+    saveMachines(home, { self, remotes: file.remotes });
+    return self;
+}
+/** Snapshot copy of the remote rows — callers can hold it without aliasing the store. */
+export function listRemotes(home) {
+    return loadMachines(home).remotes.map((r) => ({ ...r }));
+}
+/** Insert or overwrite (same id) one remote row; full read-modify-write persistence. */
+export function upsertRemote(home, row) {
+    const file = loadMachines(home);
+    const idx = file.remotes.findIndex((r) => r.id === row.id);
+    if (idx === -1)
+        file.remotes.push({ ...row });
+    else
+        file.remotes[idx] = { ...row };
+    saveMachines(home, file);
+}
+/** Drop one remote row; returns false when the id was not present. */
+export function removeRemote(home, id) {
+    const file = loadMachines(home);
+    const remotes = file.remotes.filter((r) => r.id !== id);
+    if (remotes.length === file.remotes.length)
+        return false;
+    saveMachines(home, { self: file.self, remotes });
+    return true;
+}

package/superd-hub/dist/mesh-federate.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Federation registrar (machine-mesh P2 Task 3): adopts a paired machine's
+ * PROBED roster into the LOCAL registries, so a remote agent is addressable
+ * and visible exactly like a local world:
+ *
+ *   targets.ts  `registerForeignTarget({key: a6, gateway})` — the a6-keyed
+ *               wire gateway (Task 2's `createRemoteGateway`), so the `/hub`
+ *               family demuxes `?agent=<a6>` to the peer's `/hub` family
+ *               carrying the remote RUNTIME key (`?agent=codex` at the peer).
+ *               The peer's NATIVE agent row federates the same way — its
+ *               row carries a minted a6 plus `key:'native'`, and its gateway
+ *               is built with the NATIVE face (Task 2's `face` option): the
+ *               peer's ctx0 `/api` surface, no demux key — exactly how a
+ *               browser ON the peer consumes its native DSH (the `/hub`
+ *               family would 404 `?agent=native` as foreign-only).
+ *   roster.ts   one row per agent: `{key: a6, label: '<Label> · <machine
+ *               name>', machine: m4, ready, failed}` — `machine` set marks
+ *               the row federated; `agentLinks` projects it into the UI rows.
+ *
+ * The a6 IS the local registration key (spec §3.2): runtime keys are NOT
+ * reused across machines (a remote `codex` would collide with — and silently
+ * replace — the local codex world), while a6s are owner-minted 6-char ids
+ * adopted verbatim. EVERY row federates, the peer's native included — the
+ * face selector is `agent.key === 'native'`, never an a6 test (only
+ * `'native'` is pre-screened as a hard reserve). Cross-machine a6 collision
+ * (two peers minting the same id, p ≈ 36⁻¹² per pair) and a6-vs-local-key
+ * collision (p ≈ 36⁻⁶ per adoption) are accepted at P2 machine counts — the
+ * registry replaces last-write-wins, same ruling as spec §3.1's m4 collision
+ * roughness.
+ *
+ * ## Import direction (frozen): mesh-federate → {mesh-link, mesh-gateway,
+ * ## roster, targets} — NEVER the reverse. mesh-link emits machine lifecycle
+ * ## events (`onMeshFederationEvent`: federated / degraded / defederated);
+ * ## this module subscribes at wiring time ({@link startMeshFederation},
+ * ## called once from gateway.ts apply). mesh-rpc's DELETE path announces
+ * ## removals through mesh-link's {@link emitMachineRemoved} — no route-module
+ * ## federation logic anywhere.
+ *
+ * ## Gateway memo — one `RemoteGateway` per (m4, a6), built by the wiring's
+ * ## factory, keyed by a6. Reused across probe events (identity-stable: a
+ * ## reprobe does not rebuild a live gateway); rebuilt when the peer facts
+ * ## change (origin moved, remote runtime key re-minted); disposed and
+ * ## forgotten on defederate. The cookie is NOT memoized — the gateway reads
+ * ## it per call through `cookieOf(m4, home)` (jar-fronted), so a re-minted
+ * ## cookie is picked up by the NEXT call with zero rebuilds.
+ *
+ * ## Degrade semantics (spec §6.3): a failed probe KEEPS the machine's rows
+ * ## and flips `ready` false — visible but not servable. Defederate (machine
+ * ## removal) and stale-convergence (an agent vanished from the peer's
+ * ## roster) are the only row-removing paths.
+ */
+import { type MuxClientSocket } from './mesh-gateway.js';
+import { type GatewayFace } from './targets.js';
+/** One remote agent as adopted from a probe — mesh-link's `ProbeAgent` shape
+ *  (kept structural so callers and tests can pass plain objects). */
+export interface FederatedAgent {
+    /** The remote-owner-minted a6 — the LOCAL registration key. */
+    id: string;
+    /** The remote RUNTIME key (`codex`, `omp`, …) — the peer's `?agent=` demux
+     *  key on the wire; `'native'` selects the NATIVE face (peer ctx0 `/api`, no
+     *  demux key) in the wiring's gateway factory. An EMPTY key cannot address
+     *  anything at the peer; {@link gatewayFor} falls back to the a6 there
+     *  (T3-M1) rather than shipping `?agent=` on the wire. */
+    key: string;
+    label: string;
+    ready: boolean;
+    failed: boolean;
+}
+/** The machine half of a federation fact (m4 + display name for label suffixes). */
+export interface FederatedMachine {
+    id: string;
+    name: string;
+}
+/** Wiring deps: the hub home (cookie row fallback) + test seams for the wire. */
+export interface FederationWireDeps {
+    home: string;
+    fetchImpl?: typeof fetch;
+    wsFactory?: (url: string, headers: Record<string, string>) => MuxClientSocket;
+}
+/**
+ * Register one machine's probed agents — IDEMPOTENT replace per a6: a row
+ * whose key/label/machine/ready/failed all match the live registry is left
+ * untouched (zero roster churn on repeated probes); a changed row is
+ * unregistered then re-registered (`registerAgent` throws on duplicate keys —
+ * federate always unregisters first, so repeated probes never throw).
+ * Agents with an empty id (unkeyable) are skipped; EVERY keyed row
+ * federates — the peer's native row included (its `key:'native'` selects the
+ * native gateway face; see {@link gatewayFor}).
+ * @param machine - the peer's identity (m4 + name; the name lands in every label suffix).
+ * @param agents - the probe's agent snapshot (a6 `id`, remote `key`, label, ready, failed).
+ * @param gatewayOf - gateway factory receiving the FULL agent row (the wiring
+ * derives the face from `agent.key`; tests inject fakes) — called once per
+ * (re)registration and once per converged-row target re-arm.
+ */
+export declare function federateAgents(machine: FederatedMachine, agents: FederatedAgent[], gatewayOf: (agent: FederatedAgent) => GatewayFace): void;
+/**
+ * Drop EVERY federated row of one machine (mesh-rpc DELETE / unpair): roster
+ * rows, target registrations, and the memoized wire gateways (disposed —
+ * in-flight streams fail `gateway/disposed` per Task 2's contract).
+ */
+export declare function defederateMachine(m4: string): void;
+/**
+ * Roster convergence: unregister the machine's rows whose a6s are ABSENT from
+ * the peer's latest probe (the agent was removed/renamed remotely) — live
+ * agents are left to {@link federateAgents}.
+ * @param m4 - the machine id.
+ * @param liveA6s - the a6 set of the latest successful probe.
+ */
+export declare function defederateStaleMachine(m4: string, liveA6s: ReadonlySet<string>): void;
+/**
+ * Degrade one machine's rows after a failed probe (unreachable peer or
+ * auth-expired cookie): rows are KEPT, `ready` flipped false, `failed`
+ * untouched — visible but not servable (spec §6.3; the orchestra downgrade).
+ * Rows already degraded are left alone (no roster churn); local rows are
+ * never touched.
+ */
+export declare function degradeMachine(m4: string): void;
+/**
+ * The federated gateway of one a6 — the `/hub` demux's federation-table step
+ * (exact a6 match; the same pair `federateAgents` registers into the shared
+ * target registry, so the two sources never disagree). Undefined for local
+ * labels and unknown/defederated a6s.
+ */
+export declare function federatedGatewayOf(a6: string): GatewayFace | undefined;
+/**
+ * Wire the registrar to mesh-link's machine lifecycle events (called ONCE at
+ * plugin activation — gateway.ts apply):
+ *
+ *  - `federated` → {@link federateAgents} (converge onto the probe snapshot)
+ *    + {@link defederateStaleMachine} (drop vanished agents);
+ *  - `degraded` → {@link degradeMachine} (rows kept, ready=false);
+ *  - `defederated` → {@link defederateMachine} (mesh-rpc DELETE).
+ *
+ * Re-probing a machine after a hub restart rebuilds its federation from the
+ * probe alone — the events are the single rebuild path.
+ * @returns the disposer (unsubscribes; registered rows are left as-is).
+ */
+export declare function startMeshFederation(deps: FederationWireDeps): () => void;

package/superd-hub/dist/mesh-federate.js

@@ -0,0 +1,223 @@
+/**
+ * Federation registrar (machine-mesh P2 Task 3): adopts a paired machine's
+ * PROBED roster into the LOCAL registries, so a remote agent is addressable
+ * and visible exactly like a local world:
+ *
+ *   targets.ts  `registerForeignTarget({key: a6, gateway})` — the a6-keyed
+ *               wire gateway (Task 2's `createRemoteGateway`), so the `/hub`
+ *               family demuxes `?agent=<a6>` to the peer's `/hub` family
+ *               carrying the remote RUNTIME key (`?agent=codex` at the peer).
+ *               The peer's NATIVE agent row federates the same way — its
+ *               row carries a minted a6 plus `key:'native'`, and its gateway
+ *               is built with the NATIVE face (Task 2's `face` option): the
+ *               peer's ctx0 `/api` surface, no demux key — exactly how a
+ *               browser ON the peer consumes its native DSH (the `/hub`
+ *               family would 404 `?agent=native` as foreign-only).
+ *   roster.ts   one row per agent: `{key: a6, label: '<Label> · <machine
+ *               name>', machine: m4, ready, failed}` — `machine` set marks
+ *               the row federated; `agentLinks` projects it into the UI rows.
+ *
+ * The a6 IS the local registration key (spec §3.2): runtime keys are NOT
+ * reused across machines (a remote `codex` would collide with — and silently
+ * replace — the local codex world), while a6s are owner-minted 6-char ids
+ * adopted verbatim. EVERY row federates, the peer's native included — the
+ * face selector is `agent.key === 'native'`, never an a6 test (only
+ * `'native'` is pre-screened as a hard reserve). Cross-machine a6 collision
+ * (two peers minting the same id, p ≈ 36⁻¹² per pair) and a6-vs-local-key
+ * collision (p ≈ 36⁻⁶ per adoption) are accepted at P2 machine counts — the
+ * registry replaces last-write-wins, same ruling as spec §3.1's m4 collision
+ * roughness.
+ *
+ * ## Import direction (frozen): mesh-federate → {mesh-link, mesh-gateway,
+ * ## roster, targets} — NEVER the reverse. mesh-link emits machine lifecycle
+ * ## events (`onMeshFederationEvent`: federated / degraded / defederated);
+ * ## this module subscribes at wiring time ({@link startMeshFederation},
+ * ## called once from gateway.ts apply). mesh-rpc's DELETE path announces
+ * ## removals through mesh-link's {@link emitMachineRemoved} — no route-module
+ * ## federation logic anywhere.
+ *
+ * ## Gateway memo — one `RemoteGateway` per (m4, a6), built by the wiring's
+ * ## factory, keyed by a6. Reused across probe events (identity-stable: a
+ * ## reprobe does not rebuild a live gateway); rebuilt when the peer facts
+ * ## change (origin moved, remote runtime key re-minted); disposed and
+ * ## forgotten on defederate. The cookie is NOT memoized — the gateway reads
+ * ## it per call through `cookieOf(m4, home)` (jar-fronted), so a re-minted
+ * ## cookie is picked up by the NEXT call with zero rebuilds.
+ *
+ * ## Degrade semantics (spec §6.3): a failed probe KEEPS the machine's rows
+ * ## and flips `ready` false — visible but not servable. Defederate (machine
+ * ## removal) and stale-convergence (an agent vanished from the peer's
+ * ## roster) are the only row-removing paths.
+ */
+import { createRemoteGateway } from './mesh-gateway.js';
+import { cookieOf, onMeshFederationEvent } from './mesh-link.js';
+import { registerAgent, unregisterAgent, listAgents, setReady } from './roster.js';
+import { registerForeignTarget, unregisterForeignTarget, getTarget } from './targets.js';
+const gatewayMemo = new Map();
+/** Roster rows of one machine (its a6s), from the live registry. */
+function rowsOf(m4) {
+    return listAgents().filter((e) => (e.machine ?? 'local') === m4);
+}
+/** Unregister one federated a6 from both registries + drop its memo gateway. */
+function dropA6(a6) {
+    if (listAgents().some((e) => e.key === a6))
+        unregisterAgent(a6); // guard: unregister no-ops still emit roster churn
+    unregisterForeignTarget(a6);
+    const memo = gatewayMemo.get(a6);
+    if (memo !== undefined) {
+        gatewayMemo.delete(a6);
+        memo.gateway.dispose();
+    }
+}
+/**
+ * Register one machine's probed agents — IDEMPOTENT replace per a6: a row
+ * whose key/label/machine/ready/failed all match the live registry is left
+ * untouched (zero roster churn on repeated probes); a changed row is
+ * unregistered then re-registered (`registerAgent` throws on duplicate keys —
+ * federate always unregisters first, so repeated probes never throw).
+ * Agents with an empty id (unkeyable) are skipped; EVERY keyed row
+ * federates — the peer's native row included (its `key:'native'` selects the
+ * native gateway face; see {@link gatewayFor}).
+ * @param machine - the peer's identity (m4 + name; the name lands in every label suffix).
+ * @param agents - the probe's agent snapshot (a6 `id`, remote `key`, label, ready, failed).
+ * @param gatewayOf - gateway factory receiving the FULL agent row (the wiring
+ * derives the face from `agent.key`; tests inject fakes) — called once per
+ * (re)registration and once per converged-row target re-arm.
+ */
+export function federateAgents(machine, agents, gatewayOf) {
+    for (const agent of agents) {
+        if (agent.id === '')
+            continue;
+        const desired = {
+            key: agent.id,
+            label: `${agent.label} · ${machine.name}`,
+            machine: machine.id,
+            ready: agent.ready === true,
+            failed: agent.failed === true,
+        };
+        const existing = listAgents().find((e) => e.key === agent.id);
+        if (existing !== undefined
+            && existing.label === desired.label
+            && existing.ready === desired.ready
+            && (existing.failed ?? false) === desired.failed
+            && (existing.machine ?? 'local') === machine.id) {
+            // Converged — but never trust a half-state: the roster row may survive
+            // a target that something else dropped. Re-arm the registration only.
+            if (getTarget(agent.id) === undefined)
+                registerForeignTarget({ key: agent.id, gateway: gatewayOf(agent) });
+            continue;
+        }
+        if (existing !== undefined)
+            unregisterAgent(agent.id); // defeats registerAgent's duplicate-key throw
+        unregisterForeignTarget(agent.id); // explicit replace, not map-overwrite
+        registerForeignTarget({ key: agent.id, gateway: gatewayOf(agent) });
+        registerAgent(desired);
+    }
+}
+/**
+ * Drop EVERY federated row of one machine (mesh-rpc DELETE / unpair): roster
+ * rows, target registrations, and the memoized wire gateways (disposed —
+ * in-flight streams fail `gateway/disposed` per Task 2's contract).
+ */
+export function defederateMachine(m4) {
+    for (const row of rowsOf(m4))
+        dropA6(row.key);
+    // Belt: memo entries whose roster rows vanished independently still die with the machine.
+    for (const [a6, memo] of [...gatewayMemo]) {
+        if (memo.machineId === m4)
+            dropA6(a6);
+    }
+}
+/**
+ * Roster convergence: unregister the machine's rows whose a6s are ABSENT from
+ * the peer's latest probe (the agent was removed/renamed remotely) — live
+ * agents are left to {@link federateAgents}.
+ * @param m4 - the machine id.
+ * @param liveA6s - the a6 set of the latest successful probe.
+ */
+export function defederateStaleMachine(m4, liveA6s) {
+    for (const row of rowsOf(m4)) {
+        if (!liveA6s.has(row.key))
+            dropA6(row.key);
+    }
+}
+/**
+ * Degrade one machine's rows after a failed probe (unreachable peer or
+ * auth-expired cookie): rows are KEPT, `ready` flipped false, `failed`
+ * untouched — visible but not servable (spec §6.3; the orchestra downgrade).
+ * Rows already degraded are left alone (no roster churn); local rows are
+ * never touched.
+ */
+export function degradeMachine(m4) {
+    for (const row of rowsOf(m4)) {
+        if (row.ready !== false)
+            setReady(row.key, false);
+    }
+}
+/**
+ * The federated gateway of one a6 — the `/hub` demux's federation-table step
+ * (exact a6 match; the same pair `federateAgents` registers into the shared
+ * target registry, so the two sources never disagree). Undefined for local
+ * labels and unknown/defederated a6s.
+ */
+export function federatedGatewayOf(a6) {
+    return gatewayMemo.get(a6)?.gateway;
+}
+/** The wiring's gateway factory: memoized per a6, rebuilt on peer-fact
+ * change (origin, remote runtime key, or face flip). The FACE is selected
+ * from the agent ROW — `key === 'native'` → the peer's ctx0 `/api` surface,
+ * anything else → the `/hub` family with the runtime-key demux. */
+function gatewayFor(event, agent, deps) {
+    const a6 = agent.id;
+    const face = agent.key === 'native' ? 'native' : 'foreign';
+    // T3-M1: an empty remote key must not ride the wire as `?agent=` (the
+    // nullish class miss — '' is not nullish); fall back to the a6 so the
+    // registration stays addressable and the wrong key fails LOUDLY at the
+    // peer (its demux 404s the unknown key) instead of silently here.
+    const agentKey = agent.key !== '' ? agent.key : agent.id;
+    const memo = gatewayMemo.get(a6);
+    if (memo !== undefined && memo.machineId === event.machineId && memo.origin === event.origin && memo.agentKey === agentKey && memo.face === face) {
+        return memo.gateway;
+    }
+    if (memo !== undefined) {
+        gatewayMemo.delete(a6);
+        memo.gateway.dispose();
+    }
+    const gateway = createRemoteGateway({
+        origin: event.origin,
+        agentKey,
+        face,
+        cookie: () => cookieOf(event.machineId, deps.home),
+        fetchImpl: deps.fetchImpl,
+        wsFactory: deps.wsFactory,
+    });
+    gatewayMemo.set(a6, { gateway, machineId: event.machineId, origin: event.origin, agentKey, face });
+    return gateway;
+}
+/**
+ * Wire the registrar to mesh-link's machine lifecycle events (called ONCE at
+ * plugin activation — gateway.ts apply):
+ *
+ *  - `federated` → {@link federateAgents} (converge onto the probe snapshot)
+ *    + {@link defederateStaleMachine} (drop vanished agents);
+ *  - `degraded` → {@link degradeMachine} (rows kept, ready=false);
+ *  - `defederated` → {@link defederateMachine} (mesh-rpc DELETE).
+ *
+ * Re-probing a machine after a hub restart rebuilds its federation from the
+ * probe alone — the events are the single rebuild path.
+ * @returns the disposer (unsubscribes; registered rows are left as-is).
+ */
+export function startMeshFederation(deps) {
+    return onMeshFederationEvent((event) => {
+        if (event.type === 'federated') {
+            federateAgents({ id: event.machineId, name: event.machineName }, event.agents, (agent) => gatewayFor(event, agent, deps));
+            defederateStaleMachine(event.machineId, new Set(event.agents.map((a) => a.id)));
+        }
+        else if (event.type === 'degraded') {
+            degradeMachine(event.machineId);
+        }
+        else {
+            defederateMachine(event.machineId);
+        }
+    });
+}

package/superd-hub/dist/mesh-gateway.d.ts

@@ -0,0 +1,67 @@
+import type { MuxClientSocket } from './mux-client.js';
+import type { GatewayFace } from './targets.js';
+export type { MuxClientSocket } from './mux-client.js';
+/**
+ * The default ws seam: connect one `ws` WebSocket to `url` with `headers`
+ * riding the upgrade request (the pairing Cookie), presented as T1's
+ * {@link MuxClientSocket}.
+ *
+ * The adapter is crash-proof by construction (fix round 1):
+ *  - an `'error'` listener is ALWAYS registered: an unreachable peer
+ *    (ECONNREFUSED) or a rejected upgrade (non-101, e.g. a dead cookie's
+ *    HTTP 401) emits `'error'` with no listener of its own — an uncaught
+ *    exception that kills the hub process. The listener is a no-op: ws
+ *    guarantees `'close'` follows `'error'`, and the close path already
+ *    classifies (in-flight streams fail `gateway/socket-closed`) and retires
+ *    the connection for redial. WS-lane auth failure therefore classifies
+ *    as a socket cut post-fix — acceptable: the next POST-lane call is the
+ *    one that reports `gateway/auth-expired`.
+ *  - `ws` THROWS on sends made while CONNECTING, and its post-close send
+ *    bookkeeping can itself throw in teardown windows, so every send is
+ *    guarded: pre-open sends queue (flushed in order on 'open'), post-close
+ *    sends are swallowed — the stream is dead and the close path owns the
+ *    teardown. WS-level pings stay at the WS layer: `on('message')` fires
+ *    for text data frames only, so protocol-level ping/pong NEVER surfaces
+ *    as text.
+ */
+export declare function defaultWsFactory(url: string, headers: Record<string, string>): MuxClientSocket;
+/** Options for {@link createRemoteGateway}. */
+export interface RemoteGatewayOptions {
+    /** The peer hub origin (`http(s)://host[:port]`; the mux lane maps it to ws(s)). */
+    origin: string;
+    /** The remote agent's demux key (`?agent=` on both lanes; ignored by the native face). */
+    agentKey: string;
+    /** The machine's pairing cookie, read per call (the jar fronting `MachineRow.cookie`). */
+    cookie: () => string;
+    /** Fetch override (tests); defaults to `globalThis.fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Socket factory override (tests); defaults to {@link defaultWsFactory}. */
+    wsFactory?: (url: string, headers: Record<string, string>) => MuxClientSocket;
+    /** Which peer surface to address (see the header's face table): 'foreign' =
+     * the `/hub` family with the `?agent=` demux (default); 'native' = ctx0's
+     * own `/api` surface, no demux key — how a browser ON the peer consumes its
+     * native DSH. */
+    face?: 'foreign' | 'native';
+    /** Idle ms with zero live streams before the ws closes (default 30 s; test hook for short real timers). */
+    idleCloseMs?: number;
+}
+/** A wire-form gateway: a {@link GatewayFace} plus the carrier call shape and a hard close. */
+export interface RemoteGateway extends GatewayFace {
+    /**
+     * CarrierGatewayFace shape — the canonical order `worldMuxOf` calls with
+     * (`(endpoint, payload, uplink, peer, signal, control)`); the uplink is
+     * bridged into the wire upstream lane.
+     */
+    openWireStream(endpoint: string, payload: unknown, uplink: AsyncIterable<unknown> | Iterable<unknown>, peer: undefined, signal: AbortSignal, control: AbortController): AsyncIterable<unknown>;
+    /** GatewayFace shape — no uplink lane; the stream's uplink half-closes immediately. */
+    openWireStream(endpoint: string, payload: unknown, signal: AbortSignal): AsyncIterable<unknown>;
+    /** Hard-close the shared connection now (machine unpair); in-flight streams fail `gateway/disposed`. */
+    dispose(): void;
+}
+/**
+ * Build one remote agent's wire gateway toward a paired hub's `/hub` family.
+ * @param options - see {@link RemoteGatewayOptions}.
+ * @returns the {@link RemoteGateway} (a GatewayFace; register it with
+ * `registerForeignTarget` — callers cannot tell it from a local world gateway).
+ */
+export declare function createRemoteGateway(options: RemoteGatewayOptions): RemoteGateway;