super-dsh 0.1.6 → 0.1.10

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

@@ -0,0 +1,274 @@
+/**
+ * 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 { type MachineRow, loadMachines, saveMachines } from './machines.js';
+/** One roster agent as seen through a successful probe (§6.2 additive fields). */
+export interface ProbeAgent {
+    id: string;
+    key: string;
+    label: string;
+    ready: boolean;
+    failed: boolean;
+    /** Row machine as the peer reported it: `'local'` = self-hosted on the responder; an m4 = a THIRD-party machine the responder federated — never adopted (self-description discipline, 2026-09-28 user ruling). */
+    machine: string;
+}
+/** Roster probe outcome: 200+hub → ok with adopted machineId; 401 → auth-expired; network/peer-shape errors → unreachable. */
+export type ProbeResult = {
+    ok: true;
+    machineId: string;
+    version?: string;
+    agents: ProbeAgent[];
+} | {
+    ok: false;
+    status: 'unreachable' | 'auth-expired';
+    error: string;
+};
+/** Result of a full pairing: the adopted id, the persisted row, and the probe that vouched for it. */
+export interface PairOutcome {
+    machineId: string;
+    row: MachineRow;
+    probe: ProbeResult;
+}
+/** Test injection seam: fetch + registry load/save overrides. */
+export interface LinkDeps {
+    fetchImpl?: typeof fetch;
+    load?: typeof loadMachines;
+    save?: typeof saveMachines;
+}
+/** Machine health entry in the module-level status table. */
+export interface MachineStatusEntry {
+    status: string;
+    lastProbeAt: number;
+    error?: string;
+    /** I2 version-mismatch warning (mesh P3 Task 5a): present when the peer's
+     *  superd version differs from ours by more than patch, or is
+     *  unparsable/absent — recomputed on every successful probe, so a peer
+     *  converging back onto our major/minor clears it on the next probe. */
+    versionWarning?: string;
+}
+/**
+ * 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 declare const OWN_VERSION: string;
+/**
+ * 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 declare function versionWarningFor(peer: string | undefined, ours: string): string | undefined;
+/** 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 declare function parseTokenUrl(tokenUrl: string): {
+    origin: string;
+    token: string;
+};
+/**
+ * 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 declare function mintCookie(origin: string, token: string, fetchImpl?: typeof fetch): Promise<string>;
+/**
+ * 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 declare function probeMachine(origin: string, cookie: string, fetchImpl?: typeof fetch): Promise<ProbeResult>;
+/** Read-only snapshot copy of the status table — callers can hold/mutate it freely. */
+export declare function machineStatus(): Map<string, MachineStatusEntry>;
+/** Test hook: drop all status entries. */
+export declare function resetMachineStatus(): void;
+/**
+ * Federation lifecycle event (mesh P2 Task 3) — emitted HERE, at the machine
+ * orchestration points, so the federation registrar (mesh-federate.ts) can
+ * react WITHOUT mesh-link ever importing it (the import direction is frozen:
+ * mesh-federate → mesh-link, never the reverse; the seam is this bus):
+ *
+ *  - `federated` — a probe SUCCEEDED (pairMachine or reprobeMachine): the
+ *    machine identity (m4 + name), its origin, and the adopted agent list
+ *    (each row carrying its remote a6 `id`, the remote RUNTIME key `key` —
+ *    the wire `?agent=` demux key at the peer — label, ready, failed). The
+ *    consumer converges its registries onto this snapshot and defederates
+ *    rows whose a6s no longer appear (roster convergence).
+ *  - `degraded` — a probe FAILED after the machine was already probed at
+ *    least once (unreachable peer or auth-expired cookie). Degrade semantics:
+ *    federated rows are KEPT with `ready` flipped false — visible but not
+ *    servable (orchestra downgrade, never a silent vanish).
+ *  - `defederated` — the machine row was removed (mesh-rpc DELETE →
+ *    {@link emitMachineRemoved}); the consumer drops every row of the machine.
+ */
+export type MeshFederationEvent = {
+    type: 'federated';
+    machineId: string;
+    machineName: string;
+    origin: string;
+    agents: ProbeAgent[];
+} | {
+    type: 'degraded';
+    machineId: string;
+    reason: 'unreachable' | 'auth-expired';
+    error: string;
+} | {
+    type: 'defederated';
+    machineId: string;
+};
+/** Subscribe to federation lifecycle events; returns an unsubscribe function. */
+export declare function onMeshFederationEvent(fn: (event: MeshFederationEvent) => void): () => void;
+/**
+ * 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 declare function emitMachineRemoved(machineId: string): void;
+/**
+ * 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 declare function cookieOf(machineId: string, home?: string): string;
+/**
+ * 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 declare function pairMachine(home: string, input: {
+    name: string;
+    label?: string;
+    tokenUrl: string;
+}, deps?: LinkDeps): Promise<PairOutcome>;
+/**
+ * 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 declare function reprobeMachine(home: string, id: string, deps?: LinkDeps): Promise<ProbeResult>;
+/** Default sweep period — the user mandate's 5 minutes (5a I1-a). */
+export declare const REPROBE_SWEEP_DEFAULT_SEC = 300;
+/** Floor for any sweep period: below this a reprobe loop is a self-inflicted storm. */
+export declare const REPROBE_SWEEP_MIN_SEC = 60;
+/** Structural interval-timer handle: Node's Timeout (with `unref`), faked in tests. */
+interface SweepTimerHandle {
+    unref?(): void;
+}
+/**
+ * R5 SWEEP COLLECTORS — the dual-responsibility legs (outbox pull +
+ * session-list collection) ride THIS sweep; there is no second timer and no
+ * new probing path. Two injection routes, deps-win: (a) `collectors` on the
+ * deps (tests, hermetic); (b) the process-level registry below (the a2a row
+ * registers its assembly's legs — the sweep site in gateway.ts stays
+ * unchanged). Every collector rejection is swallowed HERE: a leg failure
+ * degrades (log, keep sweeping) and never breaks probe accounting.
+ */
+export interface SweepCollectors {
+    /** Once per sweep, before the remote loop: collect the LOCAL machine's agents. */
+    onLocalCollect?(): Promise<void> | void;
+    /** After each SUCCESSFUL reprobe: pull the outbox + collect that machine's session lists. */
+    onRemoteProbed?(info: {
+        remote: MachineRow;
+        probe: ProbeResult;
+    }): Promise<void> | void;
+}
+/** Register/unregister the process-level collectors (the a2a row's assembly; set-once semantics, ctx0 only). */
+export declare function setSweepCollectors(collectors: SweepCollectors | undefined): void;
+/** 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 declare function runReprobeSweep(deps: {
+    home: string;
+    fetchImpl?: typeof fetch;
+    collectors?: SweepCollectors;
+    localCollect?: boolean;
+}): Promise<void>;
+/** Timer-discipline seams: production passes nothing (the platform
+ *  setInterval/clearInterval); tests inject a fake clock and drive ticks by hand. */
+export interface ReprobeSweepDeps {
+    home: string;
+    /** Sweep period in seconds; default 300, floored at 60 (config knob: the
+     *  superd-hub row's `reprobeIntervalSec`, gateway.ts Config). */
+    intervalSec?: number;
+    fetchImpl?: typeof fetch;
+    /** R5: the dual-responsibility legs; defaults to the process-level registry (see setSweepCollectors). */
+    collectors?: SweepCollectors;
+    /**
+     * O1b (0.1.8-e): run the R5 LOCAL collector on this tick (default true).
+     * The BOOT tick passes false — the local session plane is not mounted yet
+     * when the hub's rows come up, so an early sample is an all-error
+     * collection, not a fact. Remotes are untouched (a probe is a direct HTTP
+     * call that needs no local plane); the local leg simply waits for the first
+     * regular tick.
+     */
+    localCollect?: boolean;
+    setIntervalFn?: (fn: () => void, ms: number) => SweepTimerHandle;
+    clearIntervalFn?: (handle: SweepTimerHandle) => void;
+    /**
+     * O1 (0.1.8-c): run ONE sweep immediately at startup, then on the interval.
+     * Without it the first tick is a full period away, so after a hub restart the
+     * roster is empty and `/api/superd/machines` reads "pending" for up to
+     * `intervalSec` — even though the peers are reachable (a direct one-shot
+     * `exec` proves it). The probe is per-machine and cheap; opt-in so timer
+     * tests keep their deterministic tick-only clock.
+     * The boot tick runs WITHOUT the local collector (O1b, 0.1.8-e): the local
+     * plane is still mounting at that instant, and caching that failure would
+     * cost a whole interval of truthful-looking emptiness.
+     */
+    immediate?: boolean;
+}
+/**
+ * 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 declare function startReprobeSweep(deps: ReprobeSweepDeps): () => void;
+export {};