@intx/hub-sessions 0.3.0 → 0.4.0

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

@@ -5,6 +5,27 @@ import type { SidecarCredentialIdentity } from "../sidecar-allocation/contracts.
 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";
+import { type WsHandle } from "./pending-tracker.js";
+/**
+ * A deploy-frame send failure, tagged with whether the `agent.deploy` frame
+ * reached the wire. `frameSent: false` means the send was refused before
+ * `conn.send` (a guard failed, or the send threw synchronously) -- the deploy
+ * provably never started, so a caller may safely roll back anything it staged.
+ * `frameSent: true` means the frame was sent and the failure came afterward (ack
+ * timeout, sidecar disconnect), so the sidecar may hold a live agent.
+ */
+export interface DeployFrameFailure extends Error {
+    readonly frameSent: boolean;
+}
+export declare function isDeployFrameFailure(err: unknown): err is DeployFrameFailure;
+/**
+ * Identity validation failed or remained pending at the connection deadline.
+ * Readiness is unknown: the worker may be healthy behind the lookup, so
+ * callers must retry rather than treat this as a missed connection deadline.
+ */
+export declare class SidecarIdentityValidationError extends Error {
+    constructor(allocationId: string, generation: number, cause?: unknown);
+}
 export type SidecarConnection = {
     sidecarId: string;
     identity: SidecarAuthIdentity;
@@ -57,11 +78,31 @@ export type WorkflowProbeResult = {
     grantWalkSnapshot: GrantWalkSnapshot;
     wireHash: string;
 };
+/**
+ * The result of a run-address sender's deploy, reported to the router once the
+ * deploy's key write is durable. `recorded` carries the sender's now-persisted
+ * public key and wakes the sender's parked pre-ack mail for redelivery;
+ * `failed` carries a failure reason and drains that mail to
+ * `mail.outbound.undelivered`. Modeled as a discriminated result so a settle is
+ * unambiguous about which side of the deploy it reports.
+ */
+export type SenderDeploySettledOutcome = {
+    recorded: string;
+} | {
+    failed: string;
+};
+export type AllocatedSenderDeployAttempt = AllocatedSidecarTarget & {
+    readonly leaseId: 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;
+    routeMail(agentAddress: string, rawMessage: string, authenticatedSender: string, messageId?: string, runGrants?: {
+        runId: string;
+        stepGrants: RunGrantsFrame["stepGrants"];
+        senderIdentities?: RunGrantsFrame["senderIdentities"];
+    }): 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
@@ -70,14 +111,40 @@ export type SidecarRouter = {
      * 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
+     * and ride the same reconnect flush. After an authenticated 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.
+     *
+     * `senderIdentities` co-delivers the run's authorized senders' resolved keys
+     * on the same barrier as the grant, so a recipient that caches from this
+     * frame binds each sender address to the hub-vouched key. The caller passes
+     * `undefined` when there is no sender to co-deliver (a standing-grant refresh)
+     * or the sender has no resolvable key; a null key is never carried.
      */
-    sendRunGrants(agentAddress: string, runId: string, stepGrants: RunGrantsFrame["stepGrants"]): boolean;
+    sendRunGrants(agentAddress: string, runId: string, stepGrants: RunGrantsFrame["stepGrants"], senderIdentities: RunGrantsFrame["senderIdentities"]): boolean;
+    /**
+     * Report that a run-address sender's deploy has settled, driving any mail the
+     * sender parked while its public key was not yet recorded. A `recorded`
+     * outcome wakes the parked mail and re-drives its delivery now that the key
+     * co-delivers; a `failed` outcome drains it to `mail.outbound.undelivered`.
+     * Allocated callbacks name their exact attempt; recovery may settle the
+     * previous attempt by generation after claiming its reconciliation lease.
+     * An address-only settlement belongs to a non-allocated deployment and cannot
+     * settle an allocated attempt. Stale or repeated settlements are no-ops.
+     */
+    noteSenderDeploySettled(sender: string | AllocatedSidecarTarget | AllocatedSenderDeployAttempt, outcome: SenderDeploySettledOutcome): void;
+    /**
+     * Mark a run-address sender's ALLOCATED deploy as mid-flight, before the deploy
+     * emit and its anchor-key update. An allocated run records its key later than
+     * the deploy ack clears `pendingDeploys`, so this marker covers the allocated
+     * pre-ack window that `pendingDeploys` alone under-covers. `noteSenderDeploySettled`
+     * clears it only when the durable outcome is known. Cancellation leaves it
+     * pending for recovery, so a lost publication response cannot discard mail.
+     */
+    noteSenderDeployStarted(address: string, attempt: AllocatedSenderDeployAttempt): void;
     /**
      * Returns the current connector-thread state for the named agent, or
      * `null` if the agent has no active connector thread (or if the
@@ -88,65 +155,9 @@ export type SidecarRouter = {
      * 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>;
+    sendCredentialsUpdate(agentAddress: string, delivery: CredentialDelivery, revoke?: string[]): Promise<void>;
     sendSyncRequest(agentAddress: string): void;
     /**
      * Deliver a workflow-run signal to the sidecar that hosts the named
@@ -212,13 +223,31 @@ export type AllocatedSidecarTarget = {
 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. */
+    /**
+     * Remove an exact generation's fence after its durable owner becomes
+     * terminal. Durable identity validation rejects later stale reconnects.
+     */
+    retireAllocation(target: AllocatedSidecarTarget): void;
+    /**
+     * Resolve once the exact authenticated allocation generation is connected.
+     * Throws `SidecarIdentityValidationError` when readiness cannot be
+     * determined; only confirmed absence surfaces as a connection timeout.
+     * `onValidation` observes notification lookups that may outlive this wait.
+     */
+    waitForAllocatedSidecar(target: AllocatedSidecarTarget, timeoutMs: number, onValidation?: (validation: Promise<boolean>) => void): Promise<void>;
+    /**
+     * Check exact allocated readiness without parking a reconciliation worker.
+     * Throws `SidecarIdentityValidationError` when identity validation fails;
+     * `false` means the worker is confirmed absent or stale.
+     */
     isAllocatedSidecarReady(target: AllocatedSidecarTarget): Promise<boolean>;
-    /** Check whether the exact generation already hosts its workflow supervisor. */
+    /** Check for an active supervisor, throwing when identity validation fails. */
     isAllocatedWorkflowActive(target: AllocatedSidecarTarget): Promise<boolean>;
-    sendAgentDeployToAllocation(target: AllocatedSidecarTarget, agentAddress: string, config: HarnessConfig, workflow?: AgentDeployFrame["workflow"]): Promise<{
+    /** Probe a workflow on the exact provisioned allocation generation. */
+    sendProbeToAllocation(target: AllocatedSidecarTarget, args: SendProbeArgs): Promise<WorkflowProbeResult>;
+    /** Close an exact provisioned connection before changing its durable owner. */
+    disconnectAllocation(target: AllocatedSidecarTarget): void;
+    sendAgentDeployToAllocation(target: AllocatedSidecarTarget, agentAddress: string, config: HarnessConfig, workflow?: AgentDeployFrame["workflow"], signal?: AbortSignal, beforeSend?: () => Promise<void>): Promise<{
         publicKey: string;
     }>;
     sendPackToAllocation(target: AllocatedSidecarTarget, agentAddress: string, pack: Uint8Array, ref: string, commitSha: string, options?: SendPackOptions): Promise<void>;
@@ -226,7 +255,7 @@ export type SidecarAllocationRouter = {
      * 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>;
+    sendWorkflowRunPackToAllocation(target: AllocatedSidecarTarget, agentAddress: string, pack: Uint8Array, ref: string, commitSha: string, signal?: AbortSignal): Promise<void>;
     bindAllocatedStepRoute(target: AllocatedSidecarTarget, stepAddress: string): Promise<void>;
     unbindAllocatedStepRoute(target: AllocatedSidecarTarget, stepAddress: string): void;
     sendProvisionStepToAllocation(target: AllocatedSidecarTarget, agentAddress: string, config: HarnessConfig): Promise<void>;
@@ -237,15 +266,15 @@ export type SidecarAllocationRouter = {
      * 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. */
+    sendWorkflowRunDispatchToAllocation(target: AllocatedSidecarTarget, agentAddress: string, runId: string, stepGrants: RunGrantsFrame["stepGrants"], rawMessage: string, authenticatedSender: string, messageId: string, signal?: AbortSignal): Promise<void>;
+    /** Deliver an idempotent signal to the exact provisioned generation. */
     sendSignalDeliverToAllocation(target: AllocatedSidecarTarget, opts: {
         agentAddress: string;
         runId: string;
         signalName: string;
         signalId: string;
         payload: unknown;
-    }): Promise<void>;
+    }, signal?: AbortSignal): Promise<void>;
 };
 /**
  * Resolves the credentials a sidecar presents on the handshake to a
@@ -268,8 +297,7 @@ export type SidecarRouterConfig = {
      * 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;
+    validateSidecarIdentity: (identity: SidecarAuthIdentity, use: "registration" | "readiness" | "routing") => Promise<boolean>;
     /** 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
@@ -281,25 +309,34 @@ export type SidecarRouterConfig = {
     /** Interval between redelivery attempts of a connected-window `mail.inbound`
      * the sidecar has not yet acknowledged with `mail.inbound.ack`. */
     mailAckRetryIntervalMs?: number;
+    /**
+     * Arms the mail-redelivery retry and the connection-liveness timers, and
+     * returns each one's canceller. Defaults to the global timer, which is what
+     * production wants.
+     *
+     * The intervals beside it say how long until something should happen; this
+     * says what makes it happen. With only the intervals injectable, a test had
+     * to shorten one and then sleep past it, which turns an assertion about
+     * WHETHER something happened into a bet on how much the machine got through
+     * -- and, for the liveness deadline, on a pause landing inside a window
+     * rather than past it.
+     *
+     * REQUIRED of the returned canceller: calling it more than once must be
+     * harmless. A pending-mail entry outlives a disconnect, so the disconnect
+     * path cancels its retry and a later reconnect can cancel the same one
+     * again. `clearTimeout` on an already-cleared timer is a no-op, which is
+     * what makes the default satisfy this; a substitute must arrange the same,
+     * typically by flipping a flag.
+     */
+    scheduleTimeout?: (handler: () => void, ms: number) => () => void;
     /** 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. */
+    /** Query handlers the wire layer issues during frame processing. */
     lookups?: SidecarLookups;
 };
-export type WsHandle = {
-    send(data: string): void;
-    close(): void;
-};
+export type { WsHandle };
 export declare const DEFAULT_PROBE_TIMEOUT_MS = 60000;
+export declare const MAX_RESYNC_SENDER_ADDRESSES = 2048;
 export declare function createSidecarRouter(config: SidecarRouterConfig): SidecarRouter & SidecarAllocationRouter;