@intx/hub-sessions 0.2.2 → 0.4.0

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

@@ -1,8 +1,34 @@
-import { type AgentDeployFrame, type HubFrame, type RepoId } from "@intx/types/sidecar";
+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";
+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;
     agentAddresses: Set<string>;
     workflowAddresses: Set<string>;
     send(frame: HubFrame): void;
@@ -20,15 +46,105 @@ export type SendPackOptions = {
      * 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.
+     * 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;
+};
+/**
+ * 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): 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
+     * 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 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"], 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
@@ -39,47 +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;
-    }>;
     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>;
+    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
@@ -137,9 +215,66 @@ export type SidecarRouter = {
  * principal (e.g. an operator user) can be added as an additional arm
  * without changing existing consumers.
  */
-export type SidecarAuthIdentity = {
-    kind: "sidecar";
-    sidecarId: string;
+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;
+    /**
+     * 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 for an active supervisor, throwing when identity validation fails. */
+    isAllocatedWorkflowActive(target: AllocatedSidecarTarget): Promise<boolean>;
+    /** 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>;
+    /**
+     * 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, 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>;
+    /**
+     * 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, 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;
+    }, signal?: AbortSignal): Promise<void>;
 };
 /**
  * Resolves the credentials a sidecar presents on the handshake to a
@@ -161,24 +296,47 @@ export type SidecarRouterConfig = {
      * identity. Required: without it a connection could route on an
      * unverified frame claim. Return null to reject the handshake. */
     authenticateSidecar: SidecarAuthenticator;
-    challengeTimeoutMs?: number;
+    /** Revalidate durable identity at registration and routing boundaries. */
+    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
+     * the request timeout. */
+    probeTimeoutMs?: 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.
+    /** 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.
      *
-     * `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. */
+     * 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. */
     lookups?: SidecarLookups;
 };
-export type WsHandle = {
-    send(data: string): void;
-    close(): void;
-};
-export declare function createSidecarRouter(config: SidecarRouterConfig): SidecarRouter;
+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;