@intx/hub-sessions 0.2.2 → 0.3.0

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

@@ -1,8 +1,13 @@
-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";
 export type SidecarConnection = {
     sidecarId: string;
+    identity: SidecarAuthIdentity;
     agentAddresses: Set<string>;
     workflowAddresses: Set<string>;
     send(frame: HubFrame): void;
@@ -20,15 +25,59 @@ 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;
+};
 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, 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
@@ -55,8 +104,26 @@ export type SidecarRouter = {
     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
@@ -137,9 +204,48 @@ 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;
+    /** 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
@@ -161,10 +267,24 @@ export type SidecarRouterConfig = {
      * 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.
@@ -181,4 +301,5 @@ export type WsHandle = {
     send(data: string): void;
     close(): void;
 };
-export declare function createSidecarRouter(config: SidecarRouterConfig): SidecarRouter;
+export declare const DEFAULT_PROBE_TIMEOUT_MS = 60000;
+export declare function createSidecarRouter(config: SidecarRouterConfig): SidecarRouter & SidecarAllocationRouter;