@intx/hub-sessions 0.1.2 → 0.3.0

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

@@ -0,0 +1,222 @@
+import type { PackRejectReason, RepoId, RunGrantsFrame } from "@intx/types/sidecar";
+import type { ApprovalSnapshot, ConnectorThreadState } from "@intx/types/runtime";
+import type { SignalKind } from "@intx/types";
+export type SidecarMailPersistedRow = {
+    id: string;
+    createdAt: Date;
+    direction: "inbound" | "outbound";
+    runId: string | null;
+    address: string;
+};
+export type SidecarMailPersistedPayload = SidecarMailPersistedRow & {
+    raw: Uint8Array;
+};
+/** Authenticated connection scope attached to a workflow-run pack. */
+export type WorkflowRunPackSource = {
+    readonly kind: "shared";
+    readonly agentAddress: string;
+} | {
+    readonly kind: "allocated";
+    readonly agentAddress: string;
+    readonly allocationId: string;
+    readonly anchorRunId: string;
+    readonly generation: number;
+};
+/**
+ * Outcome of reserving a mail-triggered run's grants. `skip` means the
+ * recipient names no workflow deployment; `rejected` means the deployment's
+ * stable run is terminal or its requirements cannot be authorized;
+ * `materialized` carries the canonical persisted wire rows.
+ */
+export type MailTriggeredRunGrantsResult = {
+    outcome: "skip";
+} | {
+    outcome: "rejected";
+    status: 403 | 409;
+    code: string;
+    message: string;
+} | {
+    outcome: "materialized";
+    stepGrants: RunGrantsFrame["stepGrants"];
+};
+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[];
+        /** Present only when the closing socket was the current allocated owner. */
+        allocated?: {
+            allocationId: string;
+            generation: number;
+        };
+    };
+    /** Notification after the exact authenticated allocation generation registers. */
+    "sidecar.allocated.connected": {
+        allocationId: string;
+        generation: number;
+    };
+    /** 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;
+    /** Notification after a sidecar confirms a mail trigger is in its durable
+     * local inbox. For an exclusive worker, `allocated` identifies the exact
+     * generation that acknowledged the message. This is not workflow
+     * settlement; the Hub retains the payload until the Git claim-check records
+     * consumption. */
+    "mail.inbound.acknowledged": {
+        agentAddress: string;
+        messageId: string;
+        allocated?: {
+            allocationId: string;
+            anchorRunId: string;
+            generation: number;
+        };
+    };
+    /** 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;
+        allocated?: {
+            allocationId: string;
+            anchorRunId: string;
+            generation: number;
+        };
+    };
+    /** 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[]>;
+    /** Co-writes the `signal_correlation` routing row and the `approval` row
+     * for a suspending workflow agent step, in one transaction. Called from
+     * the `signal.correlation.register` frame handler after the wire layer has
+     * confirmed the sending sidecar owns `agentAddress`. Idempotent: a
+     * redelivered frame (reconnect, workflow-log replay, supervisor restart
+     * re-emitting) is a no-op, not an error. The wire layer does not carry
+     * `signalName`; the host derives it from `correlationId`. Resolves the
+     * tenancy from the workflow deployment the address names. */
+    registerSignalCorrelation?: (args: {
+        correlationId: string;
+        runId: string;
+        anchorRunId: string;
+        agentAddress: string;
+        kind: SignalKind;
+        approvalSnapshot: ApprovalSnapshot;
+    }) => Promise<void>;
+    /** Reserves a mail-triggered workflow run's grants from the receiving
+     * deployment's definition, returning a discriminated result the
+     * `mail.outbound` handler orders against delivery. Called for each recipient
+     * that is a workflow deployment. The `runId` is the deployment's stable
+     * address-derived run id.
+     *
+     * On `materialized`, `stepGrants` are already persisted and the caller sends
+     * them ahead of the inbound mail. Reservation is idempotent on the runId, so
+     * a redelivered inbound mail neither double-mints nor throws. On `skip` the
+     * address names no deployed workflow deployment, so no grants are sent and
+     * the mail still forwards. On `rejected` the stable run is terminal or a
+     * declared requirement's authority is insufficient; the caller fails the
+     * mail closed for that recipient. */
+    materializeMailTriggeredRunGrants?: (args: {
+        agentAddress: string;
+        runId: string;
+    }) => Promise<MailTriggeredRunGrantsResult>;
+    /** 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 run 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. `source` is derived
+     * from the authenticated socket, never from the frame. The lookup must
+     * revalidate that source against durable deployment/allocation ownership
+     * before advancing the Git ref. */
+    receiveWorkflowRunPack?: (repoId: RepoId, pack: Uint8Array, ref: string, commitSha: string, source: WorkflowRunPackSource) => Promise<{
+        accepted: true;
+    } | {
+        accepted: false;
+        reason: PackRejectReason;
+    }>;
+};

package/dist/ws/sidecar-events.js

@@ -0,0 +1,72 @@
+// 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(),
+        "sidecar.allocated.connected": new Set(),
+        "mail.outbound.undelivered": new Set(),
+        "mail.persisted": new Set(),
+        "mail.inbound.acknowledged": 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,305 @@
+import type { GrantWalkSnapshot } from "@intx/types";
+import { type AgentDeployFrame, type HubFrame, type RepoId, type RunGrantsFrame, type CredentialDelivery, type WorkflowSourceAssetMount, type WorkflowProjectionDefinition } from "@intx/types/sidecar";
+import type { ConnectorThreadState, HarnessConfig, InferenceSource } from "@intx/types/runtime";
+import type { SidecarCredentialIdentity } from "../sidecar-allocation/contracts.js";
+import type { ToolPackageManifest } from "@intx/types/tool-packages";
+import type { WorkflowDefinitionSource } from "@intx/types/workflow-sources";
+import { type SidecarEventEmitter, type SidecarLookups } from "./sidecar-events.js";
+export type SidecarConnection = {
+    sidecarId: string;
+    identity: SidecarAuthIdentity;
+    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. Workflow-run restoration uses a
+     * dedicated allocation-bound sender that supplies its derived repo id.
+     */
+    repoId?: RepoId;
+};
+/**
+ * Everything a `sendProbe` caller supplies to populate the outbound
+ * `workflow.probe.request` frame: where the definition's bytes come from, the
+ * frozen dependency closure the hub already resolved, and the
+ * `interchange.workflow` entry-module path whose evaluation produces the
+ * `WorkflowDefinition`. The `requestId` is minted inside `sendProbe`, not
+ * supplied here.
+ */
+export type SendProbeArgs = {
+    source: WorkflowDefinitionSource;
+    closure: ToolPackageManifest;
+    entry: string;
+    /** Hub assets a `kind:"asset"` closure entry reads from, delivered inline. */
+    assets?: WorkflowSourceAssetMount[];
+};
+/**
+ * The payload a `sendProbe` promise resolves with, lifted off the sidecar's
+ * `workflow.probe.result` frame: the inert needs-surface projection of the
+ * probed workflow, the inert grant set derived from it, the un-flattened grant
+ * walk snapshot the set is derived from, and the projection's content hash.
+ */
+export type WorkflowProbeResult = {
+    projection: WorkflowProjectionDefinition;
+    grants: string[];
+    grantWalkSnapshot: GrantWalkSnapshot;
+    wireHash: string;
+};
+export type SidecarRouter = {
+    handleOpen(ws: WsHandle): void;
+    handleMessage(ws: WsHandle, data: string): void;
+    handleClose(ws: WsHandle): void;
+    routeMail(agentAddress: string, rawMessage: string, messageId?: string): boolean;
+    /**
+     * Deliver a run's authorization grants to the sidecar hosting the named
+     * deployment-level mail address, ahead of the trigger mail that starts the
+     * run. Routes through the same per-address channel as `routeMail`: over the
+     * live connection when the deployment is connected, and into the disconnect
+     * queue when the deployment dropped in the window before its first
+     * reconnect (while its address is still on `agentAddresses`) -- so grants
+     * are queued for a disconnected deployment exactly when the trigger mail is,
+     * and ride the same reconnect flush. After a challenged reconnect the
+     * address moves to `workflowAddresses`, which carries no queue (that
+     * generation's in-flight state is reconstructed sidecar-locally); a
+     * `run.grants` then has no queue to ride and this returns `false`. Returns
+     * `false` whenever the address is unroutable; the caller keeps any stable-run
+     * grant reservation so a later first-delivery attempt reuses it.
+     */
+    sendRunGrants(agentAddress: string, runId: string, stepGrants: RunGrantsFrame["stepGrants"]): 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;
+    }>;
+    /**
+     * Ask a connected sidecar to probe a code-sourced workflow WITHOUT
+     * deploying it, and resolve with the sidecar's inert answer (needs-surface
+     * projection + grant set + content hash). Selects any connected sidecar via
+     * `findSidecarForNewAgent` -- the probe runs in the sidecar's pre-deploy
+     * state, so it needs no deployed agent and enters no address map -- and
+     * correlates the round-trip purely by a minted `requestId`. Rejects if no
+     * sidecar is connected, if the probe times out (`probeTimeoutMs`), if the
+     * sidecar answers `workflow.probe.error`, or if the sidecar disconnects with
+     * the probe in flight.
+     *
+     * Optional so existing `SidecarRouter` consumers -- and their test doubles
+     * -- that never probe need not implement it, mirroring `DeployRouter`'s
+     * optional `undeploy`. The concrete `createSidecarRouter` always provides
+     * it.
+     */
+    sendProbe?(args: SendProbeArgs): Promise<WorkflowProbeResult>;
+    sendAgentUndeploy(agentAddress: string, reason: string): Promise<void>;
+    sendSourcesUpdate(agentAddress: string, sources: InferenceSource[], defaultSource: string): Promise<void>;
+    sendCredentialsUpdate(agentAddress: string, delivery: CredentialDelivery): 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 = SidecarCredentialIdentity;
+export type AllocatedSidecarTarget = {
+    readonly allocationId: string;
+    readonly generation: number;
+};
+export type SidecarAllocationRouter = {
+    /** Advance the in-memory trust boundary before provisioning a generation. */
+    fenceAllocation(allocationId: string, generation: number): void;
+    /** Resolve once the exact authenticated allocation generation is connected. */
+    waitForAllocatedSidecar(target: AllocatedSidecarTarget, timeoutMs: number): Promise<void>;
+    /** Check exact allocated readiness without parking a reconciliation worker. */
+    isAllocatedSidecarReady(target: AllocatedSidecarTarget): Promise<boolean>;
+    /** Check whether the exact generation already hosts its workflow supervisor. */
+    isAllocatedWorkflowActive(target: AllocatedSidecarTarget): Promise<boolean>;
+    sendAgentDeployToAllocation(target: AllocatedSidecarTarget, agentAddress: string, config: HarnessConfig, workflow?: AgentDeployFrame["workflow"]): Promise<{
+        publicKey: string;
+    }>;
+    sendPackToAllocation(target: AllocatedSidecarTarget, agentAddress: string, pack: Uint8Array, ref: string, commitSha: string, options?: SendPackOptions): Promise<void>;
+    /**
+     * Restore one Hub-authoritative workflow-run ref onto the exact allocation
+     * generation before its deployment address is routed or supervisor spawned.
+     */
+    sendWorkflowRunPackToAllocation(target: AllocatedSidecarTarget, agentAddress: string, pack: Uint8Array, ref: string, commitSha: string): Promise<void>;
+    bindAllocatedStepRoute(target: AllocatedSidecarTarget, stepAddress: string): Promise<void>;
+    unbindAllocatedStepRoute(target: AllocatedSidecarTarget, stepAddress: string): void;
+    sendProvisionStepToAllocation(target: AllocatedSidecarTarget, agentAddress: string, config: HarnessConfig): Promise<void>;
+    /**
+     * Deliver one durable workflow trigger to the exact allocation generation.
+     * Grants and mail are written to the same websocket in FIFO order. The
+     * returned promise proves only that both frames were sent; the sidecar's
+     * durable-inbox acknowledgement is surfaced separately through
+     * `mail.inbound.acknowledged`.
+     */
+    sendWorkflowRunDispatchToAllocation(target: AllocatedSidecarTarget, agentAddress: string, runId: string, stepGrants: RunGrantsFrame["stepGrants"], rawMessage: string, messageId: string): Promise<void>;
+    /** Deliver an idempotent signal to the exact exclusive generation. */
+    sendSignalDeliverToAllocation(target: AllocatedSidecarTarget, opts: {
+        agentAddress: string;
+        runId: string;
+        signalName: string;
+        signalId: string;
+        payload: unknown;
+    }): Promise<void>;
+};
+/**
+ * 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;
+    /** Revalidate durable identity at registration and routing boundaries. */
+    validateSidecarIdentity?: (identity: SidecarAuthIdentity, use: "registration" | "readiness" | "routing") => Promise<boolean>;
+    challengeTimeoutMs?: number;
+    /** Timeout for a `sendProbe` round-trip. A probe materializes a workflow's
+     * dependency closure and evaluates it on the sidecar, so it can run longer
+     * than a routine `sendRequest`; it gets its own timeout rather than sharing
+     * the request timeout. */
+    probeTimeoutMs?: number;
+    disconnectQueueMaxSize?: number;
+    disconnectQueueTTLMs?: number;
+    pingTimeoutMs?: number;
+    /** Interval between redelivery attempts of a connected-window `mail.inbound`
+     * the sidecar has not yet acknowledged with `mail.inbound.ack`. */
+    mailAckRetryIntervalMs?: number;
+    /** Maximum redelivery attempts before the hub stops retrying an un-acked
+     * connected-window `mail.inbound`. Bounds the retry so a sidecar that never
+     * acks does not accumulate an unbounded timer per delivery. */
+    mailAckMaxRetries?: 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 const DEFAULT_PROBE_TIMEOUT_MS = 60000;
+export declare function createSidecarRouter(config: SidecarRouterConfig): SidecarRouter & SidecarAllocationRouter;