super-dsh 0.1.6 → 0.1.10-e

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

@@ -0,0 +1,441 @@
+/**
+ * Mesh link (mesh P1, spec §4/§6.3): remote connection management —
+ * token-URL parsing, cookie mint, roster probe, and the pairing /
+ * reprobe orchestration that adopts the remote machine id (D4) into
+ * the machine registry from `./machines.js`.
+ *
+ * Pure module — no cordis dependencies. Outbound calls use the global
+ * fetch (injectable via `fetchImpl` / `deps.fetchImpl` for tests) with
+ * a 10s AbortSignal timeout. The minted cookie is persisted on the machine
+ * row (`MachineRow.cookie`, D1 sensitivity, §3.3/§4) so hub restarts keep the
+ * remote's 30-day session; an in-process jar fronts the row as a write-through
+ * cache of the same value. Probe outcomes land
+ * in the module-level status table exported read-only via
+ * `machineStatus()` (mesh API consumes; `resetMachineStatus()` is the
+ * test hook). P1 was probe-on-demand only; the mesh P3 Task 5a user
+ * mandate ("状态更新走单向 API + 5 分钟周期轮询") adds the PERIODIC sweep
+ * (`startReprobeSweep`) — a timer-discipline layer over the same
+ * `reprobeMachine`, never a second probing path. I2 also lands here: every
+ * successful probe compares the peer's `hub.version` against ours and
+ * records a `versionWarning` on the status entry (diff major/minor or
+ * unparsable → warn; patch-only drift → clean).
+ */
+import { loadMachines, saveMachines, upsertRemote, listRemotes } from './machines.js';
+import { PACK_VERSION } from './pack-version.js';
+/**
+ * The `ours` side of the I2 comparison — the super-dsh PACK version (D6: the
+ * hub subpackage's constant 0.1.0 made the comparator dead; the pack number
+ * is what `dsh plugin add` versions and the only one that moves). Exported so
+ * tests can pin the comparator's production input to the real pack manifest.
+ */
+export const OWN_VERSION = PACK_VERSION;
+/**
+ * Parse a version's major.minor core (I2): tolerant of a leading `v`, a
+ * missing patch segment, and a prerelease/build suffix — the mismatch rule
+ * ignores everything past `major.minor` by design (patch drift between
+ * paired hubs is routine and harmless).
+ */
+function parseVersionCore(version) {
+    const m = /^\s*v?(\d+)\.(\d+)/.exec(version);
+    if (m === null)
+        return undefined;
+    return { major: Number(m[1]), minor: Number(m[2]) };
+}
+/**
+ * The I2 comparator: when to warn about a peer's superd version.
+ *   - different major OR minor → a warning naming both versions;
+ *   - same major+minor (patch-only drift) → `undefined` (clean);
+ *   - unparsable or missing on EITHER side → a warning carrying 'unknown'
+ *     (an unreadable peer version is itself a compatibility fact).
+ * Pure and exported for direct unit testing; the pair/reprobe paths feed it
+ * `probe.version` and the module's {@link OWN_VERSION}.
+ */
+export function versionWarningFor(peer, ours) {
+    const peerCore = peer !== undefined ? parseVersionCore(peer) : undefined;
+    const ourCore = parseVersionCore(ours);
+    if (peerCore === undefined || ourCore === undefined) {
+        if (peer === undefined)
+            return 'version unknown (peer carries none)';
+        if (peerCore === undefined)
+            return `version unknown ("${peer}")`;
+        return `version unknown (ours "${ours}")`;
+    }
+    if (peerCore.major !== ourCore.major || peerCore.minor !== ourCore.minor) {
+        return `version ${peer} ≠ ours ${ours}`;
+    }
+    return undefined;
+}
+const FETCH_TIMEOUT_MS = 10_000;
+/** <machineId, cookie> — in-process jar, a front for the persisted `MachineRow.cookie` (same value; write-through on every mint). */
+const cookieJar = new Map();
+const machineStatusTable = new Map();
+function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** Validate a pasted token URL: absolute http(s) origin + non-empty `?token=`.
+ *  Error copy never echoes the raw input — a typo'd paste may still carry a live
+ *  token, so messages carry at most the (userinfo-free) origin. */
+export function parseTokenUrl(tokenUrl) {
+    let url;
+    try {
+        url = new URL(tokenUrl);
+    }
+    catch {
+        throw new Error('mesh-link: invalid token url — not a parseable absolute URL');
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new Error(`mesh-link: invalid token url — origin must be http(s), got "${url.origin}"`);
+    }
+    const token = url.searchParams.get('token') ?? '';
+    if (token === '') {
+        throw new Error(`mesh-link: invalid token url at "${url.origin}" — missing ?token= query parameter`);
+    }
+    return { origin: url.origin, token };
+}
+/** Fallback Set-Cookie splitter for header environments without `getSetCookie()`. */
+function splitSetCookieHeader(joined) {
+    if (!joined)
+        return [];
+    return joined.split(/,(?=\s*[^;=\s]+\s*=)/);
+}
+/** First `name=value` pair of a Set-Cookie value (attributes stripped). */
+function firstCookiePair(raw) {
+    const m = /^\s*([^=;\s]+=[^;]*)/.exec(raw);
+    return m ? m[1].trim() : null;
+}
+/**
+ * Mint a request cookie from a launch token: `GET <origin>/?token=<t>` with
+ * `redirect: 'manual'`, taking the first `dsh-auth-*` name=value pair from
+ * Set-Cookie. Non-303/2xx, a missing cookie, or a network failure throws
+ * with the status/cause attached.
+ */
+export async function mintCookie(origin, token, fetchImpl = globalThis.fetch) {
+    let res;
+    try {
+        res = await fetchImpl(`${origin}/?token=${encodeURIComponent(token)}`, {
+            redirect: 'manual',
+            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+        });
+    }
+    catch (err) {
+        throw new Error(`mesh-link: token mint to ${origin} failed — ${errMsg(err)}`);
+    }
+    if (res.status !== 303 && !(res.status >= 200 && res.status < 300)) {
+        throw new Error(`mesh-link: token mint failed — unexpected status ${res.status} from ${origin}`);
+    }
+    const rawCookies = typeof res.headers.getSetCookie === 'function'
+        ? res.headers.getSetCookie()
+        : splitSetCookieHeader(res.headers.get('set-cookie'));
+    for (const raw of rawCookies) {
+        const pair = firstCookiePair(raw);
+        if (pair !== null && pair.startsWith('dsh-auth-'))
+            return pair;
+    }
+    throw new Error(`mesh-link: token mint failed — no dsh-auth-* Set-Cookie in response (status ${res.status}) from ${origin}`);
+}
+function coerceAgent(v) {
+    const a = (typeof v === 'object' && v !== null ? v : {});
+    return {
+        id: typeof a.id === 'string' ? a.id : '',
+        key: typeof a.key === 'string' ? a.key : '',
+        label: typeof a.label === 'string' ? a.label : '',
+        ready: a.ready === true,
+        failed: a.failed === true,
+        machine: typeof a.machine === 'string' && a.machine !== '' ? a.machine : 'local',
+    };
+}
+/**
+ * Probe a remote hub's roster: `GET <origin>/api/agent-runtime` with the
+ * cookie riding along. 401 → `auth-expired`; network error → `unreachable`;
+ * 200 without a `hub.machineId` block is a non-superdsh 0.1.6+ peer →
+ * `unreachable` with `peer roster has no hub block`.
+ */
+export async function probeMachine(origin, cookie, fetchImpl = globalThis.fetch) {
+    let res;
+    try {
+        // `?mesh=1` asks the peer for ITS OWN rows only (self-description
+        // discipline): a hub never re-broadcasts other remotes' agents. The
+        // adoption filter below is the belt-and-braces leg for older peers.
+        res = await fetchImpl(`${origin}/api/agent-runtime?mesh=1`, {
+            headers: cookie === '' ? {} : { cookie },
+            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+        });
+    }
+    catch (err) {
+        return { ok: false, status: 'unreachable', error: `probe fetch to ${origin} failed — ${errMsg(err)}` };
+    }
+    if (res.status === 401) {
+        return { ok: false, status: 'auth-expired', error: `probe got 401 from ${origin} — cookie rejected` };
+    }
+    if (res.status !== 200) {
+        return { ok: false, status: 'unreachable', error: `probe got status ${res.status} from ${origin}` };
+    }
+    let body;
+    try {
+        body = await res.json();
+    }
+    catch (err) {
+        return { ok: false, status: 'unreachable', error: `probe roster from ${origin} is not JSON — ${errMsg(err)}` };
+    }
+    const o = (typeof body === 'object' && body !== null ? body : {});
+    const hub = (typeof o.hub === 'object' && o.hub !== null ? o.hub : {});
+    if (typeof hub.machineId !== 'string' || hub.machineId === '') {
+        return { ok: false, status: 'unreachable', error: 'peer roster has no hub block' };
+    }
+    // P2P (2026-09-28 user ruling): adopt ONLY the responder's own rows
+    // (machine === 'local'). Whatever else its roster carries — mirrors of US,
+    // third-party remotes it federates — is its own business; the requester
+    // merges its N paired machines itself, one probe each.
+    const agents = (Array.isArray(o.agents) ? o.agents.map(coerceAgent) : [])
+        .filter((a) => a.machine === 'local');
+    return {
+        ok: true,
+        machineId: hub.machineId,
+        version: typeof hub.version === 'string' ? hub.version : undefined,
+        agents,
+    };
+}
+/** Read-only snapshot copy of the status table — callers can hold/mutate it freely. */
+export function machineStatus() {
+    return new Map(Array.from(machineStatusTable, ([id, e]) => [id, { ...e }]));
+}
+/** Test hook: drop all status entries. */
+export function resetMachineStatus() {
+    machineStatusTable.clear();
+}
+const federationListeners = new Set();
+/** Subscribe to federation lifecycle events; returns an unsubscribe function. */
+export function onMeshFederationEvent(fn) {
+    federationListeners.add(fn);
+    return () => {
+        federationListeners.delete(fn);
+    };
+}
+function emitFederation(event) {
+    for (const fn of federationListeners)
+        fn(event);
+}
+/**
+ * Announce a machine removal on the federation bus (`{type: 'defederated'}`).
+ * Called by mesh-rpc's DELETE path AFTER a successful `removeRemote` — the
+ * route module stays free of federation logic (one-way imports: mesh-rpc →
+ * mesh-link, the registrar subscribes at wiring time).
+ */
+export function emitMachineRemoved(machineId) {
+    emitFederation({ type: 'defederated', machineId });
+}
+/**
+ * The machine's CURRENT pairing cookie: the in-process jar first (warm after
+ * every mint this process — pair and reprobe both write it before any
+ * federation event fires), then the persisted `MachineRow.cookie` (only when
+ * `home` is given; the defensive cold path for gateways built without a probe
+ * in this process), else `''` (wire calls then simply omit the Cookie header).
+ */
+export function cookieOf(machineId, home) {
+    const jarred = cookieJar.get(machineId);
+    if (jarred !== undefined)
+        return jarred;
+    if (home === undefined)
+        return '';
+    return listRemotes(home).find((r) => r.id === machineId)?.cookie ?? '';
+}
+/** Record one probe outcome; the I2 versionWarning (4th arg) lands only on
+ *  reachable probes — every entry is written FRESH, so a re-probe against a
+ *  converged peer replaces a stale warning with a clean entry. */
+function recordStatus(id, status, error, versionWarning) {
+    const entry = error === undefined
+        ? { status, lastProbeAt: Date.now() }
+        : { status, lastProbeAt: Date.now(), error };
+    if (versionWarning !== undefined)
+        entry.versionWarning = versionWarning;
+    machineStatusTable.set(id, entry);
+}
+/** Persist one remote row; uses `upsertRemote` unless a load/save seam is injected (test isolation). */
+function persistRow(home, row, deps) {
+    if (!deps?.load && !deps?.save) {
+        upsertRemote(home, row);
+        return;
+    }
+    const file = (deps.load ?? loadMachines)(home);
+    const idx = file.remotes.findIndex((r) => r.id === row.id);
+    if (idx === -1)
+        file.remotes.push({ ...row });
+    else
+        file.remotes[idx] = { ...row };
+    (deps.save ?? saveMachines)(home, file);
+}
+/**
+ * Full pairing: parse the pasted token URL → mint a cookie → probe the roster
+ * → adopt the remote machine id (fail-loud on collision with self or an
+ * existing remote) → persist the row with the retained token and minted
+ * cookie → jar the cookie and mark the machine reachable. A failed mint/probe throws before
+ * anything is persisted.
+ */
+export async function pairMachine(home, input, deps) {
+    const fetchImpl = deps?.fetchImpl ?? globalThis.fetch;
+    const load = deps?.load ?? loadMachines;
+    const { origin, token } = parseTokenUrl(input.tokenUrl);
+    const cookie = await mintCookie(origin, token, fetchImpl);
+    const probe = await probeMachine(origin, cookie, fetchImpl);
+    if (!probe.ok) {
+        throw new Error(`mesh-link: pairing ${origin} failed — ${probe.status}: ${probe.error}`);
+    }
+    const file = load(home);
+    if (probe.machineId === file.self.id || file.remotes.some((r) => r.id === probe.machineId)) {
+        throw new Error(`mesh-link: duplicate-machine-id ${probe.machineId} — collides with self or an existing remote row; remove the stale row before re-pairing`);
+    }
+    const row = {
+        id: probe.machineId,
+        name: input.name,
+        label: input.label ?? input.name,
+        origin,
+        token,
+        cookie,
+        enabled: true,
+        addedAt: Date.now(),
+    };
+    persistRow(home, row, deps);
+    cookieJar.set(row.id, cookie);
+    recordStatus(row.id, 'reachable', undefined, versionWarningFor(probe.version, OWN_VERSION));
+    emitFederation({ type: 'federated', machineId: row.id, machineName: row.name, origin, agents: probe.agents });
+    return { machineId: row.id, row, probe };
+}
+/**
+ * Re-probe a paired machine: the jar's cookie, falling back to the cookie
+ * persisted on the row (cold jar after a hub restart), rides the probe. On
+ * `auth-expired`, if the row retains a token, re-mint once and probe again; a
+ * successful re-mint writes the new cookie back into the jar AND the row. Every
+ * outcome lands in the status table
+ * (`reachable` / `auth-expired` / `unreachable`, the latter two with the error).
+ */
+export async function reprobeMachine(home, id, deps) {
+    const fetchImpl = deps?.fetchImpl ?? globalThis.fetch;
+    const remotes = deps?.load ? deps.load(home).remotes : listRemotes(home);
+    const row = remotes.find((r) => r.id === id);
+    if (!row) {
+        throw new Error(`mesh-link: unknown machine id "${id}" — no remote row in the registry`);
+    }
+    const origin = row.origin;
+    let cookie = cookieJar.get(id) ?? row.cookie ?? '';
+    let probe = await probeMachine(origin, cookie, fetchImpl);
+    if (!probe.ok && probe.status === 'auth-expired' && row.token) {
+        try {
+            cookie = await mintCookie(origin, row.token, fetchImpl);
+            cookieJar.set(id, cookie);
+            persistRow(home, { ...row, cookie }, deps);
+            probe = await probeMachine(origin, cookie, fetchImpl);
+        }
+        catch (err) {
+            probe = { ok: false, status: 'auth-expired', error: `re-mint failed — ${errMsg(err)}` };
+        }
+    }
+    if (probe.ok) {
+        cookieJar.set(id, cookie);
+        recordStatus(id, 'reachable', undefined, versionWarningFor(probe.version, OWN_VERSION));
+        emitFederation({ type: 'federated', machineId: id, machineName: row.name, origin, agents: probe.agents });
+    }
+    else if (probe.status === 'auth-expired') {
+        recordStatus(id, 'auth-expired', probe.error);
+        emitFederation({ type: 'degraded', machineId: id, reason: 'auth-expired', error: probe.error });
+    }
+    else {
+        recordStatus(id, 'unreachable', probe.error);
+        emitFederation({ type: 'degraded', machineId: id, reason: probe.status, error: probe.error });
+    }
+    return probe;
+}
+// ---- I1(a): the periodic reprobe sweep (mesh P3 Task 5a) ----------------------
+/** Default sweep period — the user mandate's 5 minutes (5a I1-a). */
+export const REPROBE_SWEEP_DEFAULT_SEC = 300;
+/** Floor for any sweep period: below this a reprobe loop is a self-inflicted storm. */
+export const REPROBE_SWEEP_MIN_SEC = 60;
+let registeredCollectors = {};
+/** Register/unregister the process-level collectors (the a2a row's assembly; set-once semantics, ctx0 only). */
+export function setSweepCollectors(collectors) {
+    registeredCollectors = collectors ?? {};
+}
+/** One full sweep — the timer's entire payload. Reads the registry FRESH at
+ * start (rows paired/removed since the last tick are honored), probes every
+ * ENABLED remote through the real {@link reprobeMachine} (success converges
+ * federation via the existing event hook; failure degrades — no second
+ * probing path), and swallows every per-machine rejection so one dead peer
+ * (or a row deleted mid-sweep → unknown-id throw) never rejects the sweep.
+ * Since R5 the collectors run inside the same swallow discipline.
+ * `localCollect: false` (O1b, 0.1.8-e) skips ONLY the local leg: the boot tick
+ * uses it because the local session plane is not mounted yet the moment the
+ * hub's rows come up — sampling there yields an all-error collection that
+ * would then read as a fresh, empty window (see `startReprobeSweep`). */
+export async function runReprobeSweep(deps) {
+    const collectors = deps.collectors ?? registeredCollectors;
+    if (deps.localCollect !== false && collectors.onLocalCollect !== undefined) {
+        try {
+            await collectors.onLocalCollect();
+        }
+        catch {
+            // the local leg degrades — remotes still get their probe
+        }
+    }
+    for (const row of listRemotes(deps.home)) {
+        if (!row.enabled)
+            continue;
+        try {
+            const probe = await reprobeMachine(deps.home, row.id, { fetchImpl: deps.fetchImpl });
+            if (probe.ok && collectors.onRemoteProbed !== undefined) {
+                try {
+                    await collectors.onRemoteProbed({ remote: row, probe });
+                }
+                catch {
+                    // a leg failure never breaks probe accounting or the sweep loop
+                }
+            }
+        }
+        catch {
+            // Per-machine errors end here — the sweep itself always settles clean.
+        }
+    }
+}
+/**
+ * Start the periodic reprobe sweep (I1-a). Discipline, all of it load-bearing:
+ *   - the interval handle is `unref()`d — a freshness sweep never holds the
+ *     hub process (or a test runner) open;
+ *   - a tick while the previous sweep is still in flight is SKIPPED (no
+ *     overlap: a slow peer slows the cadence, it never stacks sweeps);
+ *   - the returned disposer clears the timer AND kills any late tick — the
+ *     hub host wiring registers it as a ctx effect, so the sweep dies with
+ *     the row (dispose-clean); the disposer is idempotent.
+ * The first sweep runs after one full period, except when `immediate` asks
+ *     for one at boot (the mesh UI's own reprobe stays available too).
+ */
+export function startReprobeSweep(deps) {
+    const seconds = Math.max(REPROBE_SWEEP_MIN_SEC, deps.intervalSec ?? REPROBE_SWEEP_DEFAULT_SEC);
+    const setInt = deps.setIntervalFn ?? ((fn, ms) => globalThis.setInterval(fn, ms));
+    const clearInt = deps.clearIntervalFn ?? ((handle) => globalThis.clearInterval(handle));
+    let inFlight = false;
+    let disposed = false;
+    /** One tick. The boot tick passes `localCollect=false` (O1b, 0.1.8-e). */
+    const tick = (localCollect) => {
+        if (disposed || inFlight)
+            return;
+        inFlight = true;
+        void runReprobeSweep({
+            home: deps.home,
+            ...(deps.fetchImpl === undefined ? {} : { fetchImpl: deps.fetchImpl }),
+            ...(deps.collectors === undefined ? {} : { collectors: deps.collectors }),
+            ...(localCollect ? {} : { localCollect: false }),
+        }).finally(() => { inFlight = false; });
+    };
+    const handle = setInt(() => tick(true), seconds * 1_000);
+    handle.unref?.();
+    // O1 (0.1.8-c): fill the roster at BOOT, not one full period later.
+    // O1b (0.1.8-e): the local leg is deferred to the first regular tick — the
+    // local session plane is still mounting and an early sample would be cached
+    // as an empty window for a full interval.
+    if (deps.immediate === true)
+        tick(false);
+    return () => {
+        if (disposed)
+            return;
+        disposed = true;
+        clearInt(handle);
+    };
+}

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

@@ -0,0 +1,123 @@
+/**
+ * Machine-mesh management API (mesh P1, spec §6.3): the add-machine face
+ * mounted behind `ctx.connection.fetch` — the client-connection service owns
+ * the single `/api` prefix webServer route and runs the Host/Origin
+ * browser-trust fence + persistent browser auth before dispatching (same
+ * auth conclusion as rpc.ts; registering our own webServer route would
+ * bypass that fence).
+ *
+ * Route + handler ONLY — pairing/probing business logic lives in
+ * `./mesh-link.js`, persistence in `./machines.js`. This module never writes
+ * the mesh-link status table: `machineStatus()` is imported READ-ONLY and
+ * joined into GET rows by id (absent → `'pending'`).
+ *
+ * One exact route, body/method dispatched:
+ *   GET    /api/superd/machines            → `{self, machines}` (public row
+ *                                           projection — NEVER token/cookie,
+ *                                           D1 + Task 2 review's deferred
+ *                                           finding: the row carries two
+ *                                           secrets and the wire carries
+ *                                           none; since mesh P3 5a (I2) a
+ *                                           row may also carry
+ *                                           `versionWarning` — additive,
+ *                                           present only when the peer's
+ *                                           superd version differs from
+ *                                           ours by more than patch)
+ *   POST   /api/superd/machines            → `{op?: 'reprobe', ...}`:
+ *        op:'reprobe' + {id}               → `{probe: ProbeResult}` (the
+ *                                           brief's `/machines/reprobe` path
+ *                                           variant is FOLDED here because
+ *                                           connection.fetch matches by exact
+ *                                           path — one registration, body
+ *                                           dispatch; documented per Task 3
+ *                                           controller amendment)
+ *        otherwise `{name, label?, tokenUrl}` → pairMachine → 201 `{machine}`;
+ *                                           any failure → 400 `{error}` (the
+ *                                           message is mesh-link's own,
+ *                                           already token-redacted)
+ *   DELETE /api/superd/machines?id=<m4>    → `{removed: true|false}`
+ *   DELETE /api/superd/machines?id=<m4>    → `{removed: true|false}`; a successful
+ *                                           removal ALSO announces `emitMachineRemoved`
+ *                                           on mesh-link's federation bus (mesh P2
+ *                                           Task 3) — the registrar defederates the
+ *                                           machine's rows; this module stays
+ *                                           route+handler only (no mesh-federate import)
+ * `DELETE` note: upstream's declared `ConnectionFetchMethod` union is
+ * `GET | HEAD | POST`, but the runtime route table dispatches through an
+ * untyped `methods.has(method)` set and `assertFetchRoute` never inspects
+ * method names (packages/client/connection/src/rpc-host.ts, verified against
+ * dsh-v0.1.7-rc.1) — DELETE rides the same exact-path dispatch. If a future
+ * upstream tightens that, remove folds into a POST op like reprobe.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type A2aIngest } from './a2a-ingest.js';
+import type { A2aLogFn } from './a2a-log.js';
+/** The shared-channel Fetch route path this API owns. */
+export declare const MESH_API_BASE = "/api/superd/machines";
+/** Injection seam: the hub home (registry + pairing live under it) and an
+ *  optional fetch override for tests. `home` is resolved by the caller
+ *  (gateway.ts passes `resolveDshHome()` at registration time); this module
+ *  stays free of home-resolution logic. */
+export interface MeshDeps {
+    home: string;
+    fetchImpl?: typeof fetch;
+}
+/** The GET/POST row shape as it crosses the wire — the persisted MachineRow
+ *  minus its two secrets (`token`, `cookie`), plus the joined status (and,
+ *  additively since I2/mesh P3 5a, the version-mismatch warning when the
+ *  mesh-link status entry carries one). */
+export interface MachinePublicRow {
+    id: string;
+    name: string;
+    label: string;
+    origin: string;
+    enabled: boolean;
+    addedAt: number;
+    status: string;
+    lastProbeAt?: number;
+    error?: string;
+    versionWarning?: string;
+}
+/**
+ * The mesh-machines handler: GET list / POST pair-or-reprobe / DELETE remove.
+ * @param request - the incoming `/api/superd/machines` request.
+ * @param deps - home + optional fetch override (tests inject a fixture).
+ * @returns the JSON response.
+ */
+export declare function handleMeshMachines(request: Request, deps: MeshDeps): Promise<Response>;
+/**
+ * Register the mesh-machines API 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 registerMeshRpc(ctx: Context, deps: MeshDeps): void;
+/**
+ * POST /api/superd/a2a — body = one v1 wire frame `{v: 1, envelope}` → the
+ * envelope's receipt (new/message: send receipt; stop: stop receipt;
+ * reply/notice: the local delivery outcome). Malformed frames are 400s with
+ * the decoder's named reason.
+ */
+export declare function handleA2aIngestPost(request: Request, ingest: A2aIngest): Promise<Response>;
+/**
+ * GET /api/superd/a2a/outbox?machine=<m4> — claim & clear the buffered
+ * envelopes addressed to the claiming machine (declarative claim, D1).
+ */
+export declare function handleA2aOutboxGet(request: Request, ingest: A2aIngest): Response;
+/**
+ * Register the a2a endpoints (POST /api/superd/a2a + GET .../outbox) on the
+ * shared `/api` connection channel — same fence as the machines route. The
+ * ingest instance is SHARED (R4): the initiator service's self-routing leg
+ * calls the very same handler these routes call. No-op when `connection` is
+ * absent.
+ */
+export declare function registerA2aRpc(ctx: Context, ingest: A2aIngest): void;
+/**
+ * POST /api/superd/exec — one-shot `bash -lc <cmd>` on THIS machine (spec
+ * §8.1): tail-windowed stdout/stderr, two-stage group kill on timeout. The
+ * auth trust boundary is the shared `/api` fence (same as machines/a2a);
+ * the initiator-side per-machine knob (`execEnabled`) lives on the CALLER's
+ * registry row, not here.
+ */
+export declare function handleExecPost(request: Request, log?: A2aLogFn): Promise<Response>;
+/** Register the exec endpoint on the shared `/api` connection channel. */
+export declare function registerExecRpc(ctx: Context, log?: A2aLogFn): void;