@intx/hub-sessions 0.1.2 → 0.2.2

package/dist/workflow-run-reader.d.ts

@@ -0,0 +1,47 @@
+import type { RepoId } from "./repo-store/types.js";
+import type { RepoStore } from "./repo-store/types.js";
+/**
+ * A workflow-run event as committed under
+ * `runs/<runId>/events/<seq>.json`. The discriminator field is `type`;
+ * the per-type body is opaque to the reader and surfaced verbatim as
+ * `body` so consumers narrow on the discriminator they care about.
+ */
+export type WorkflowRunEvent = {
+    seq: number;
+    type: string;
+    body: Record<string, unknown>;
+};
+/**
+ * Reader for a workflow-run repo's committed event log. Projects the
+ * `runs/<runId>/events/<seq>.json` substrate the workflow-process child
+ * writes (validated at push time by the workflow-run kind handler) into
+ * seq-ordered in-memory events, mirroring the read-model approach the
+ * per-session timeline reconstruction uses against an agent-state repo.
+ *
+ * The reader is read-only: it composes `RepoStore.getRepoDir` (a pure
+ * path computation) with direct `isomorphic-git` tree/blob reads. It
+ * never writes, so it carries no authorize gate of its own; callers
+ * gate access at their own boundary (the REST routes use a
+ * `workflow-run:<deploymentId>` grant check).
+ */
+export interface WorkflowRunReader {
+    /**
+     * Enumerate the run ids present under `runs/` on `ref`. Returns an
+     * empty array when the repo has not been initialised yet (no on-disk
+     * repoDir, no ref, or no `runs/` tree). A corrupt repo, a
+     * present-but-malformed tree, or any other unexpected isomorphic-git
+     * error propagates so the caller sees the failure rather than
+     * treating it as "no runs yet".
+     */
+    listRunIds(repoId: RepoId, ref: string): Promise<string[]>;
+    /**
+     * Read every event under `runs/<runId>/events/` on `ref` and return
+     * them in ascending `seq` order. Returns an empty array when the run
+     * has not yet committed any events or the repo/ref has not been
+     * created. A blob that parses but is missing a string `type`
+     * discriminator is a substrate-invariant violation and throws rather
+     * than being silently dropped.
+     */
+    readRunEvents(repoId: RepoId, ref: string, runId: string): Promise<WorkflowRunEvent[]>;
+}
+export declare function createWorkflowRunReader(repoStore: RepoStore): WorkflowRunReader;

package/dist/workflow-run-reader.js

@@ -0,0 +1,157 @@
+import fs from "node:fs";
+import git from "isomorphic-git";
+import { WORKFLOW_RUN_EVENTS_DIR, WORKFLOW_RUN_RUNS_PREFIX, } from "./workflow-run-kind.js";
+import { WORKFLOW_RUN_EVENTS_FILE, splitCombinedEventLog, } from "./workflow-run-event-log.js";
+const EVENT_FILENAME_RE = /^(0|[1-9][0-9]*)\.json$/;
+export function createWorkflowRunReader(repoStore) {
+    function repoDirOrNull(repoId) {
+        try {
+            return repoStore.getRepoDir(repoId);
+        }
+        catch {
+            // getRepoDir throws only when the repoId fails the kind handler's
+            // slug validation; an uninitialised-but-valid repo returns a path
+            // that does not yet exist on disk. A validation failure here means
+            // the caller handed an id the substrate would never have written,
+            // which is indistinguishable from "no such run repo" at this read
+            // boundary.
+            return null;
+        }
+    }
+    async function resolveRefOrNull(dir, ref) {
+        try {
+            return await git.resolveRef({ fs, dir, ref });
+        }
+        catch (cause) {
+            if (cause instanceof git.Errors.NotFoundError ||
+                (cause instanceof Error && /ENOENT|not found/i.test(cause.message))) {
+                return null;
+            }
+            throw cause;
+        }
+    }
+    async function listRunIds(repoId, ref) {
+        const dir = repoDirOrNull(repoId);
+        if (dir === null)
+            return [];
+        const oid = await resolveRefOrNull(dir, ref);
+        if (oid === null)
+            return [];
+        let tree;
+        try {
+            tree = await git.readTree({
+                fs,
+                dir,
+                oid,
+                filepath: WORKFLOW_RUN_RUNS_PREFIX,
+            });
+        }
+        catch (cause) {
+            if (cause instanceof git.Errors.NotFoundError)
+                return [];
+            throw cause;
+        }
+        return tree.tree
+            .filter((entry) => entry.type === "tree")
+            .map((entry) => entry.path);
+    }
+    async function readRunEvents(repoId, ref, runId) {
+        const dir = repoDirOrNull(repoId);
+        if (dir === null)
+            return [];
+        const oid = await resolveRefOrNull(dir, ref);
+        if (oid === null)
+            return [];
+        const runDir = `${WORKFLOW_RUN_RUNS_PREFIX}/${runId}`;
+        let runTree;
+        try {
+            runTree = await git.readTree({ fs, dir, oid, filepath: runDir });
+        }
+        catch (cause) {
+            if (cause instanceof git.Errors.NotFoundError)
+                return [];
+            throw cause;
+        }
+        // A terminated run is sealed into a single combined `events.jsonl`;
+        // an in-flight run keeps per-event `events/<seq>.json` files. The two
+        // forms are mutually exclusive in a run directory; a run carrying both
+        // is a botched seal, and silently preferring one would mask it, so
+        // surface it instead.
+        const combined = runTree.tree.find((e) => e.type === "blob" && e.path === WORKFLOW_RUN_EVENTS_FILE);
+        const perEventDir = runTree.tree.find((e) => e.type === "tree" && e.path === WORKFLOW_RUN_EVENTS_DIR);
+        if (combined !== undefined && perEventDir !== undefined) {
+            throw new Error(`workflow-run reader: run ${runId} carries both a combined ${WORKFLOW_RUN_EVENTS_FILE} and a per-event ${WORKFLOW_RUN_EVENTS_DIR}/ directory`);
+        }
+        if (combined !== undefined) {
+            const blob = await git.readBlob({ fs, dir, oid: combined.oid });
+            const source = `${runDir}/${WORKFLOW_RUN_EVENTS_FILE}`;
+            const events = [];
+            for (const line of splitCombinedEventLog(new TextDecoder().decode(blob.blob))) {
+                events.push(parseRunEventLine(line, source));
+            }
+            events.sort((a, b) => a.seq - b.seq);
+            return events;
+        }
+        const eventsDir = `${runDir}/${WORKFLOW_RUN_EVENTS_DIR}`;
+        let tree;
+        try {
+            tree = await git.readTree({ fs, dir, oid, filepath: eventsDir });
+        }
+        catch (cause) {
+            if (cause instanceof git.Errors.NotFoundError)
+                return [];
+            throw cause;
+        }
+        const events = [];
+        for (const entry of tree.tree) {
+            if (entry.type !== "blob")
+                continue;
+            const m = EVENT_FILENAME_RE.exec(entry.path);
+            if (m === null || m[1] === undefined)
+                continue;
+            const seq = Number.parseInt(m[1], 10);
+            const blob = await git.readBlob({ fs, dir, oid: entry.oid });
+            const path = `${eventsDir}/${entry.path}`;
+            const parsed = parseEventObject(new TextDecoder().decode(blob.blob), path);
+            const type = parsed["type"];
+            if (typeof type !== "string") {
+                throw new Error(`workflow-run reader: event at ${path} is missing a string \`type\` field`);
+            }
+            // The per-event form carries the seq in the filename; when the body
+            // also carries one, the two must agree (the combined form reads the
+            // seq from the body, so a disagreement would make the forms diverge).
+            const bodySeq = parsed["seq"];
+            if (typeof bodySeq === "number" && bodySeq !== seq) {
+                throw new Error(`workflow-run reader: event at ${path} body seq ${String(bodySeq)} does not match filename seq ${String(seq)}`);
+            }
+            events.push({ seq, type, body: parsed });
+        }
+        events.sort((a, b) => a.seq - b.seq);
+        return events;
+    }
+    // Parse one combined-log line (the verbatim text of a former
+    // `events/<seq>.json` blob): the seq is read from the body, since the
+    // combined form drops the per-event filename that carried it.
+    function parseRunEventLine(line, source) {
+        const parsed = parseEventObject(line, source);
+        const seq = parsed["seq"];
+        const type = parsed["type"];
+        if (typeof seq !== "number") {
+            throw new Error(`workflow-run reader: event in ${source} is missing a numeric \`seq\` field`);
+        }
+        if (typeof type !== "string") {
+            throw new Error(`workflow-run reader: event in ${source} is missing a string \`type\` field`);
+        }
+        return { seq, type, body: parsed };
+    }
+    function parseEventObject(text, source) {
+        const parsed = JSON.parse(text);
+        if (typeof parsed !== "object" ||
+            parsed === null ||
+            Array.isArray(parsed)) {
+            throw new Error(`workflow-run reader: event at ${source} is not a JSON object`);
+        }
+        return { ...parsed };
+    }
+    return { listRunIds, readRunEvents };
+}

package/dist/ws/index.d.ts

@@ -0,0 +1,3 @@
+export { createSidecarRouter, type SidecarRouter, type SidecarRouterConfig, type SidecarConnection, type SidecarAuthIdentity, type SidecarAuthenticator, type SendPackOptions, type WsHandle, } from "./sidecar-handler.js";
+export { createSidecarTokenAuthenticator, type CreateSidecarTokenAuthenticatorDeps, } from "./sidecar-token-authenticator.js";
+export { createSidecarEmitter, type SidecarEventEmitter, type SidecarEventMap, type SidecarEventType, type SidecarEventListener, type SidecarLookups, type SidecarMailPersistedRow, type SidecarMailPersistedPayload, } from "./sidecar-events.js";

package/dist/ws/index.js

@@ -0,0 +1,3 @@
+export { createSidecarRouter, } from "./sidecar-handler.js";
+export { createSidecarTokenAuthenticator, } from "./sidecar-token-authenticator.js";
+export { createSidecarEmitter, } from "./sidecar-events.js";

package/dist/ws/sidecar-events.d.ts

@@ -0,0 +1,134 @@
+import type { PackRejectReason, RepoId } from "@intx/types/sidecar";
+import type { ConnectorThreadState } from "@intx/types/runtime";
+export type SidecarMailPersistedRow = {
+    id: string;
+    createdAt: Date;
+    direction: "inbound" | "outbound";
+    instanceId: string | null;
+    address: string;
+};
+export type SidecarMailPersistedPayload = SidecarMailPersistedRow & {
+    raw: Uint8Array;
+};
+export type SidecarEventMap = {
+    /** Notification. Emitted for every agent.event frame the wire layer
+     * decodes. The wire layer also forwards the event to in-process agent
+     * subscribers registered via `router.subscribeAgent`; this event is
+     * the host-side observation point. */
+    "agent.event": {
+        agentAddress: string;
+        sessionId: string;
+        event: unknown;
+    };
+    /** Notification. Emitted once when a sidecar's connection closes,
+     * carrying every address the connection owned -- challenged session
+     * addresses and hub-minted workflow-substrate deployment addresses
+     * alike -- so lifecycle teardown covers both. */
+    "sidecar.disconnect": {
+        ownedAddresses: string[];
+    };
+    /** Notification. Emitted when a mail.outbound frame from a sidecar
+     * names recipients that the wire layer could not deliver locally and
+     * could not enqueue for a disconnected agent. The host is free to
+     * relay it onto an external transport or drop it. */
+    "mail.outbound.undelivered": {
+        rawMessage: string;
+        recipients: string[];
+    };
+    /** Notification. Emitted once per row produced by the host's
+     * `persistMail` lookup. The wire layer calls `persistMail` to obtain
+     * the rows; this event fires for each so subscribers can react
+     * per-row (e.g. dispatch a delivered event). */
+    "mail.persisted": SidecarMailPersistedPayload;
+    /** Awaited. Emitted when an agent.deploy.ack frame arrives. Rejection
+     * fails the pending deploy with the listener's error. */
+    "agent.deploy.ack": {
+        agentAddress: string;
+        publicKey: string;
+    };
+    /** Notification. Emitted when the sidecar reports a change to an
+     * agent's connector-thread state. The wire layer caches the state
+     * per agent so the host can read it via
+     * `router.getConnectorState(agentAddress)`; this event is for hosts
+     * that want to observe transitions directly. `connectorState` is
+     * `null` when the agent has no active connector thread. */
+    "connector.state.changed": {
+        agentAddress: string;
+        connectorState: ConnectorThreadState | null;
+    };
+    /** Awaited. Emitted per address after challenge verification
+     * succeeds and before the disconnect queue is flushed. Rejection
+     * rolls that address back from the routing table; earlier listeners
+     * in registration order have already executed and their side effects
+     * are not undone. A subsequent reconnect arriving mid-flight may
+     * supersede this one, so listeners must be idempotent. */
+    "agent.reconnected": {
+        agentAddress: string;
+    };
+    /** Awaited. Emitted per address after the wire layer has confirmed
+     * the sidecar's deploy ref is stale relative to the hub's current
+     * ref. The listener's job is to push a fresh deploy pack. The wire
+     * layer fires this only when staleness is confirmed; subscribing
+     * without a `lookupDeployRef` configured on the router will never
+     * deliver. */
+    "deploy.ref.stale": {
+        agentAddress: string;
+    };
+};
+export type SidecarEventType = keyof SidecarEventMap;
+export type SidecarEventListener<T extends SidecarEventType> = (payload: SidecarEventMap[T]) => void | Promise<void>;
+export type SidecarEventEmitter = {
+    on<T extends SidecarEventType>(type: T, listener: SidecarEventListener<T>): () => void;
+    emit<T extends SidecarEventType>(type: T, payload: SidecarEventMap[T]): void;
+    emitAndAwait<T extends SidecarEventType>(type: T, payload: SidecarEventMap[T]): Promise<void>;
+    /** Number of listeners registered for `type`. Wire-layer callers use
+     * this to skip an `await` when nothing is listening, preserving the
+     * synchronous scheduling of unconfigured-handler paths. */
+    listenerCount(type: SidecarEventType): number;
+};
+export declare function createSidecarEmitter(): SidecarEventEmitter;
+export type SidecarLookups = {
+    /** Returns the hex-encoded Ed25519 public key stored for the address,
+     * or `null` if the address is unknown. Used during the reconnect
+     * challenge to verify the sidecar's signature. */
+    lookupPublicKey?: (agentAddress: string) => Promise<string | null>;
+    /** Returns the hub's current deploy ref for the address, or `null` if
+     * no deploy state is tracked. The wire layer compares this against
+     * the sidecar's reported ref during reconnect and emits
+     * `deploy.ref.stale` only on mismatch. */
+    lookupDeployRef?: (agentAddress: string) => Promise<string | null>;
+    /** Persists a delivered outbound mail frame. Returns one row per
+     * persisted record; the wire layer attaches `raw` to each row and
+     * emits a `mail.persisted` event. */
+    persistMail?: (args: {
+        senderAddress: string;
+        recipients: string[];
+        raw: Uint8Array;
+    }) => Promise<SidecarMailPersistedRow[]>;
+    /** Ingests a received agent-state pack and returns whether the wire
+     * layer should ack or reject the pack to the sidecar. `repoId.kind`
+     * is `"agent-state"` and `repoId.id` is the agent address. The wire
+     * layer dispatches on `repoId.kind` against the receive lookups
+     * before calling either; this lookup must reject any pack whose
+     * `repoId.kind` is not `"agent-state"`. */
+    receiveAgentStatePack?: (repoId: RepoId, pack: Uint8Array, ref: string, commitSha: string) => Promise<{
+        accepted: true;
+    } | {
+        accepted: false;
+        reason: PackRejectReason;
+    }>;
+    /** Ingests a received workflow-run pack and returns whether the wire
+     * layer should ack or reject the pack to the sidecar. `repoId.kind`
+     * is `"workflow-run"` and `repoId.id` is the deployment id (which the
+     * hub-side substrate maps to a `WorkflowRunSupervisorPrincipal`
+     * during the receivePack call). The wire layer dispatches on
+     * `repoId.kind` against the receive lookups before calling either;
+     * this lookup must reject any pack whose `repoId.kind` is not
+     * `"workflow-run"`. */
+    receiveWorkflowRunPack?: (repoId: RepoId, pack: Uint8Array, ref: string, commitSha: string) => Promise<{
+        accepted: true;
+    } | {
+        accepted: false;
+        reason: PackRejectReason;
+    }>;
+};

package/dist/ws/sidecar-events.js

@@ -0,0 +1,70 @@
+// Typed event emitter for the sidecar router.
+//
+// The router emits events at the points where wire-layer frame handling
+// completes and a host-side decision or side effect is required. Two
+// emission shapes are exposed:
+//
+// - `emit(type, payload)` — notification semantics. Each listener runs
+//   inside its own try/catch; a thrown error is logged and does not
+//   affect other listeners or the wire layer. Used for events whose
+//   outcome does not feed back into protocol behavior.
+//
+// - `emitAndAwait(type, payload)` — sequential await semantics.
+//   Listeners run in registration order; the first rejection propagates
+//   to the caller and stops the chain. Used for events whose outcome
+//   affects subsequent wire-layer state (e.g. reconnect rollback).
+//
+// The TSDoc on each entry in `SidecarEventMap` records which semantic
+// applies. Mixing the two on a single event is intentional: today's
+// wire layer already has both behaviors, and pretending otherwise
+// would silently change failure handling.
+import { getLogger } from "@intx/log";
+const logger = getLogger(["hub", "ws", "sidecar", "events"]);
+export function createSidecarEmitter() {
+    const listeners = {
+        "agent.event": new Set(),
+        "sidecar.disconnect": new Set(),
+        "mail.outbound.undelivered": new Set(),
+        "mail.persisted": new Set(),
+        "agent.deploy.ack": new Set(),
+        "agent.reconnected": new Set(),
+        "deploy.ref.stale": new Set(),
+        "connector.state.changed": new Set(),
+    };
+    function on(type, listener) {
+        listeners[type].add(listener);
+        return () => {
+            listeners[type].delete(listener);
+        };
+    }
+    function emit(type, payload) {
+        const set = listeners[type];
+        if (set.size === 0)
+            return;
+        for (const listener of [...set]) {
+            try {
+                const result = listener(payload);
+                if (result instanceof Promise) {
+                    result.catch((err) => {
+                        logger.warn `Listener for ${type} threw: ${err instanceof Error ? err.message : String(err)}`;
+                    });
+                }
+            }
+            catch (err) {
+                logger.warn `Listener for ${type} threw: ${err instanceof Error ? err.message : String(err)}`;
+            }
+        }
+    }
+    async function emitAndAwait(type, payload) {
+        const set = listeners[type];
+        if (set.size === 0)
+            return;
+        for (const listener of [...set]) {
+            await listener(payload);
+        }
+    }
+    function listenerCount(type) {
+        return listeners[type].size;
+    }
+    return { on, emit, emitAndAwait, listenerCount };
+}

package/dist/ws/sidecar-handler.d.ts

@@ -0,0 +1,184 @@
+import { type AgentDeployFrame, type HubFrame, type RepoId } from "@intx/types/sidecar";
+import type { ConnectorThreadState, HarnessConfig, InferenceSource } from "@intx/types/runtime";
+import { type SidecarEventEmitter, type SidecarLookups } from "./sidecar-events.js";
+export type SidecarConnection = {
+    sidecarId: string;
+    agentAddresses: Set<string>;
+    workflowAddresses: Set<string>;
+    send(frame: HubFrame): void;
+};
+export type SendPackOptions = {
+    /**
+     * Repo-relative mount path under the sidecar's per-agent workspace.
+     * When set, the receiving sidecar materializes the pack as plain
+     * files at `<workspaceRoot>/<mountPath>/` and does NOT apply it to
+     * the agent's deploy git tree. Absent for agent-state deploy/state
+     * packs, which continue to apply to the deploy tree.
+     */
+    mountPath?: string;
+    /**
+     * Override the `repoId` emitted on the wire. The agent-state flow
+     * defaults to `{ kind: "agent-state", id: agentAddress }`; asset
+     * packs must pass the SOURCE asset's id so audit can correlate the
+     * pack back to its hub-side origin.
+     */
+    repoId?: RepoId;
+};
+export type SidecarRouter = {
+    handleOpen(ws: WsHandle): void;
+    handleMessage(ws: WsHandle, data: string): void;
+    handleClose(ws: WsHandle): void;
+    routeMail(agentAddress: string, rawMessage: string): boolean;
+    /**
+     * Returns the current connector-thread state for the named agent, or
+     * `null` if the agent has no active connector thread (or if the
+     * sidecar has not yet reported any state — e.g. mid-reconnect, before
+     * the harness has loaded its context store). The state is cached
+     * from `connector.state.changed` frames; callers should treat `null`
+     * as "no threading info available" and fall through to whatever
+     * default the calling path uses.
+     */
+    getConnectorState(agentAddress: string): ConnectorThreadState | null;
+    /**
+     * Send an `agent.deploy` frame to the sidecar. When `workflow` is
+     * supplied, the frame carries the multi-step deploy projection
+     * (workflow definition plus per-step source pins); the sidecar's
+     * deploy router routes it to the workflow deploy path. The sole
+     * caller supplies `workflow` on every deploy; per-step provisioning
+     * uses `sendProvisionStep`.
+     *
+     * The returned promise resolves with the supervisor's principal
+     * public key (hex-encoded Ed25519) carried on `agent.deploy.ack`.
+     * The legacy callers that ignore the return value continue to work
+     * unchanged.
+     */
+    sendAgentDeploy(agentAddress: string, config: HarnessConfig, workflow?: AgentDeployFrame["workflow"]): Promise<{
+        publicKey: string;
+    }>;
+    sendAgentUndeploy(agentAddress: string, reason: string): Promise<void>;
+    sendSourcesUpdate(agentAddress: string, sources: InferenceSource[], defaultSource: string): Promise<void>;
+    sendPack(agentAddress: string, pack: Uint8Array, ref: string, commitSha: string, options?: SendPackOptions): Promise<void>;
+    /**
+     * Bind a per-step workflow-substrate address to a sidecar for the staging
+     * window of a multi-step deploy, so `sendPack` can route the step's deploy
+     * and asset packs before the deployment-level frame spawns the child. The
+     * address enters the keyless `workflowAddresses` routing set; call
+     * `unbindStepRoute` once the step's packs land. Throws if no sidecar is
+     * available.
+     */
+    bindStepRoute(stepAddress: string): void;
+    /**
+     * Remove a per-step route bound by `bindStepRoute`. Idempotent: an unbound
+     * address is a no-op.
+     */
+    unbindStepRoute(stepAddress: string): void;
+    /**
+     * Provision one step of a multi-step deploy on the sidecar WITHOUT
+     * spawning: the sidecar initializes the step's agent-state repo and
+     * records the hub key so the follow-up deploy pack applies and verifies.
+     * The step address must already be bound via `bindStepRoute`. Resolves
+     * once the sidecar acks, so the caller can then deliver the deploy pack.
+     */
+    sendProvisionStep(agentAddress: string, config: HarnessConfig): Promise<void>;
+    sendSyncRequest(agentAddress: string): void;
+    /**
+     * Deliver a workflow-run signal to the sidecar that hosts the named
+     * deployment-level mail address. The sidecar's hub-link routes the
+     * frame through its `signalInboundRouter` into the deployment's
+     * supervisor, which sends a `signal.deliver` control IPC frame to
+     * the workflow-process child. The child commits the resulting
+     * `SignalReceived` event through its own substrate -- the single
+     * writer of the workflow-run repo on the sidecar side -- so the
+     * pack-push pipeline that propagates the commit to the hub never
+     * sees a concurrent writer at the same ref.
+     *
+     * Throws when no sidecar is registered for `agentAddress`; the
+     * caller is responsible for ensuring the deployment is live.
+     */
+    sendSignalDeliver(opts: {
+        agentAddress: string;
+        runId: string;
+        signalName: string;
+        signalId: string;
+        payload: unknown;
+    }): void;
+    /**
+     * Deliver a workflow-host drain control payload to the sidecar that
+     * hosts the named deployment-level mail address. The sidecar's
+     * hub-link routes the frame through its `drainInboundRouter` into
+     * the deployment's supervisor, which sends a `drain` control IPC
+     * frame to the workflow-process child and arms one `drainTimeout`
+     * accumulator per in-flight run. Cancel-mode steps abort on the
+     * child side; wait-mode steps continue. Accumulators commit a
+     * signed `CancelRequested{origin: "supervisor-drain"}` against the
+     * workflow-run repo when the deadline expires.
+     *
+     * Throws when no sidecar is registered for `agentAddress`; the
+     * caller is responsible for ensuring the deployment is live.
+     */
+    sendDrain(opts: {
+        agentAddress: string;
+        deadlineMs: number;
+    }): void;
+    subscribeAgent(agentAddress: string, callback: (event: unknown) => void): () => void;
+    dispatchAgentEvent(agentAddress: string, event: unknown): void;
+    getConnectedSidecars(): string[];
+    getRoutableAddresses(): string[];
+    /** Typed event emitter for the receiver-dispatch surface. See
+     * `sidecar-events.ts` for the event map and emission semantics. */
+    events: SidecarEventEmitter;
+};
+/**
+ * A verified sidecar-connection identity resolved by an authenticator from
+ * the credentials a sidecar presents on the WebSocket handshake. The
+ * `sidecarId` is the connection's own trusted id; it is not the untrusted
+ * `sidecarId` claimed on the register/reconnect frame, and it carries no
+ * tenant scope. Modeled as a discriminated union so a future non-sidecar
+ * principal (e.g. an operator user) can be added as an additional arm
+ * without changing existing consumers.
+ */
+export type SidecarAuthIdentity = {
+    kind: "sidecar";
+    sidecarId: string;
+};
+/**
+ * Resolves the credentials a sidecar presents on the handshake to a
+ * verified identity, or `null` when the credentials are not recognized.
+ * The claimed `sidecarId` is an unauthenticated hint; the authenticator
+ * derives the trusted identity from the `token` and the returned
+ * `sidecarId` is what the router keys connection state off of.
+ */
+export type SidecarAuthenticator = (claim: {
+    sidecarId: string;
+    token: string;
+}) => Promise<SidecarAuthIdentity | null>;
+export type SidecarRouterConfig = {
+    requestTimeoutMs?: number;
+    /** Hex-encoded 32-byte Ed25519 public key for signing deploy commits.
+     * Included in agent.deploy frames so sidecars can verify pack signatures. */
+    hubPublicKey?: string;
+    /** Resolves each register/reconnect handshake to a verified sidecar
+     * identity. Required: without it a connection could route on an
+     * unverified frame claim. Return null to reject the handshake. */
+    authenticateSidecar: SidecarAuthenticator;
+    challengeTimeoutMs?: number;
+    disconnectQueueMaxSize?: number;
+    disconnectQueueTTLMs?: number;
+    pingTimeoutMs?: number;
+    /** Query handlers the wire layer issues during frame processing.
+     * Each lookup is one-handler-returns-a-value; for multi-subscriber
+     * notifications use `router.events.on(...)` instead.
+     *
+     * `lookupDeployRef` and the `deploy.ref.stale` event are paired by
+     * convention: the wire layer only issues the staleness comparison
+     * when the lookup is set, and only emits the event on a confirmed
+     * mismatch. The host is responsible for subscribing a listener
+     * whenever the lookup is provided; the router does not enforce
+     * the pairing. */
+    lookups?: SidecarLookups;
+};
+export type WsHandle = {
+    send(data: string): void;
+    close(): void;
+};
+export declare function createSidecarRouter(config: SidecarRouterConfig): SidecarRouter;