@intx/hub-sessions 0.3.0 → 0.4.0

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

@@ -12,4 +12,5 @@ export declare function restoreWorkflowRunToAllocation(args: {
     allocationRouter: Pick<SidecarAllocationRouter, "sendWorkflowRunPackToAllocation">;
     allocationTarget: AllocatedSidecarTarget;
     agentAddress: string;
+    signal?: AbortSignal;
 }): Promise<void>;

package/dist/workflow-run-restore.js

@@ -17,10 +17,14 @@ export async function restoreWorkflowRunToAllocation(args) {
         id: deriveWorkflowRunRepoId(agentAddress),
     };
     for (const ref of WORKFLOW_RUN_RESTORE_REFS) {
+        args.signal?.throwIfAborted();
         const tip = await agentRepoStore.repoStore.resolveRef(principal, repoId, ref);
+        args.signal?.throwIfAborted();
         if (tip === null)
             continue;
         const pack = await agentRepoStore.repoStore.createPack(principal, repoId, ref);
-        await allocationRouter.sendWorkflowRunPackToAllocation(allocationTarget, agentAddress, pack.pack, pack.ref, pack.commitSha);
+        args.signal?.throwIfAborted();
+        await allocationRouter.sendWorkflowRunPackToAllocation(allocationTarget, agentAddress, pack.pack, pack.ref, pack.commitSha, args.signal);
     }
+    args.signal?.throwIfAborted();
 }

package/dist/workflow-source-pins.d.ts

@@ -0,0 +1,8 @@
+import type { WorkflowProjectionWithSources } from "@intx/types/sidecar";
+import type { HarnessConfig } from "@intx/types/runtime";
+import { type ApprovalSet } from "@intx/workflow-deploy";
+export declare function buildReferencedWorkflowSourcePins(args: {
+    projection: WorkflowProjectionWithSources["definition"];
+    config: HarnessConfig;
+    operatorApprovals: ApprovalSet;
+}): Promise<readonly WorkflowProjectionWithSources[]>;

package/dist/workflow-source-pins.js

@@ -0,0 +1,14 @@
+import { computeWireDefinitionHash } from "@intx/types/wire-definition-hash";
+import { buildInertBodyStepSources, enumerateInertBodies, } from "@intx/workflow-deploy";
+export async function buildReferencedWorkflowSourcePins(args) {
+    return Promise.all(enumerateInertBodies(args.projection).map(async (body) => ({
+        definition: body.definition,
+        sources: buildInertBodyStepSources({
+            definition: body.definition,
+            workflowId: body.ref,
+            config: args.config,
+            operatorApprovals: args.operatorApprovals,
+        }),
+        approvedWireHash: await computeWireDefinitionHash(body.definition),
+    })));
+}

package/dist/ws/index.d.ts

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

package/dist/ws/index.js

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

package/dist/ws/pending-tracker.d.ts

@@ -0,0 +1,93 @@
+export type WsHandle = {
+    send(data: string): void;
+    close(): void;
+};
+/**
+ * Arms a one-shot timeout and returns the canceller for it.
+ *
+ * The tracker's timeouts are the only thing about it that depends on time
+ * passing, and a caller that wants them settled on demand rather than by
+ * waiting has nowhere to reach in: the global timer is not addressable from
+ * outside. Injecting the arming function makes the timeout observable and
+ * cancellable by whoever owns the tracker, so a test can fire a timeout, or
+ * assert one was disarmed, without a real duration elapsing.
+ *
+ * Returning the canceller rather than a handle keeps the timer's identity
+ * private to whichever implementation armed it.
+ */
+export type ScheduleTimeout = (handler: () => void, ms: number) => () => void;
+export type PendingEntry<Key, Value, Meta> = {
+    key: Key;
+    ws: WsHandle;
+    /**
+     * Opaque per-entry payload for settle-time ownership checks. The pack
+     * tracker stores the send-site `{ agentAddress, repoId }` so an ack/reject
+     * is honored only when it comes from the connection that owns the transfer
+     * for the same repo; the other trackers pass `undefined`.
+     */
+    meta: Meta;
+    resolve(value: Value): void;
+    reject(error: string): void;
+    /**
+     * Disarms this entry's timeout.
+     *
+     * Runs at most once per entry, which is why it need not be idempotent and
+     * `ScheduleTimeout` does not ask its implementations for that: each of the
+     * four settle paths cancels and drops the entry from the map in one
+     * synchronous block, and a timeout that fires drops the entry itself, so
+     * nothing can reach the entry to cancel it a second time.
+     */
+    cancelTimeout(): void;
+};
+export declare class PendingTracker<Key, Value = void, Meta = undefined> {
+    private readonly schedule;
+    private readonly entries;
+    /**
+     * `schedule` defaults to the global timer, which is what every production
+     * caller wants; it is injectable so a caller can drive the timeouts.
+     */
+    constructor(schedule?: ScheduleTimeout);
+    /**
+     * Register a pending round-trip and arm its timeout. The entry is stored
+     * before the caller sends its frame, so a synchronous reply (loopback
+     * transports, tests) settles it. When `timeoutMs` elapses the entry is
+     * dropped and `reject` is invoked with `timeoutMessage` — the same
+     * rejection path an error reply frame uses, so per-site cleanup (routing
+     * rollback, address bookkeeping) runs exactly once either way.
+     *
+     * `meta` is the opaque per-entry payload settle-time ownership checks read
+     * off `get`; pass `undefined` when the round-trip carries none.
+     */
+    register(key: Key, ws: WsHandle, options: {
+        timeoutMs: number;
+        timeoutMessage: string;
+        resolve(value: Value): void;
+        reject(error: string): void;
+    }, meta: Meta): void;
+    has(key: Key): boolean;
+    get(key: Key): PendingEntry<Key, Value, Meta> | undefined;
+    /**
+     * Settle a pending entry as resolved. No-op when the entry is already
+     * gone (timed out or swept on disconnect).
+     */
+    resolve(key: Key, value: Value): boolean;
+    /**
+     * Settle a pending entry as rejected. No-op when the entry is already
+     * gone (timed out or swept on disconnect).
+     */
+    reject(key: Key, error: string): boolean;
+    /**
+     * Drop a pending entry without settling it. The caller rejects its own
+     * promise directly — used when a frame provably never reached the wire, so
+     * the failure must not take the normal rejection path (the deploy
+     * "failed to send" path, which must report `frameSent: false` and must not
+     * let the armed timer fire later and double-reject).
+     */
+    delete(key: Key): void;
+    /**
+     * Reject every pending entry owned by `ws` — the disconnect sweep. Each
+     * entry's reject closure runs its own per-site cleanup (address
+     * bookkeeping), identical to a frame-error rejection.
+     */
+    rejectAllForWs(ws: WsHandle, error: string): void;
+}

package/dist/ws/pending-tracker.js

@@ -0,0 +1,132 @@
+// Generic pending-round-trip tracker for hub→sidecar requests.
+//
+// `sidecar-handler.ts` runs five request/response round-trips over the same
+// websocket (session requests, agent deploys, pack transfers, undeploys,
+// workflow probes). Each used to hand-roll the same lifecycle: register an
+// entry in a Map keyed by request/transfer/address, arm a timeout that
+// settles the entry, settle it early when the matching reply frame arrives,
+// and sweep every entry owned by a connection when that connection drops.
+// The sites differ only in the key, the resolved value, and the per-site
+// cleanup their resolve/reject closures capture — the map + timer lifecycle
+// is identical. `PendingTracker` owns that lifecycle so timeouts and
+// disconnect sweeps behave uniformly and a fix to either lands in one place.
+const scheduleOnGlobalTimer = (handler, ms) => {
+    const timer = setTimeout(handler, ms);
+    return () => {
+        clearTimeout(timer);
+    };
+};
+export class PendingTracker {
+    schedule;
+    entries = new Map();
+    /**
+     * `schedule` defaults to the global timer, which is what every production
+     * caller wants; it is injectable so a caller can drive the timeouts.
+     */
+    constructor(schedule = scheduleOnGlobalTimer) {
+        this.schedule = schedule;
+    }
+    /**
+     * Register a pending round-trip and arm its timeout. The entry is stored
+     * before the caller sends its frame, so a synchronous reply (loopback
+     * transports, tests) settles it. When `timeoutMs` elapses the entry is
+     * dropped and `reject` is invoked with `timeoutMessage` — the same
+     * rejection path an error reply frame uses, so per-site cleanup (routing
+     * rollback, address bookkeeping) runs exactly once either way.
+     *
+     * `meta` is the opaque per-entry payload settle-time ownership checks read
+     * off `get`; pass `undefined` when the round-trip carries none.
+     */
+    register(key, ws, options, meta) {
+        // Identifies the entry this call is about to register, so the handler
+        // below can recognize it. Allocated before `schedule`, because the
+        // handler closes over it and the entry itself does not exist yet.
+        const token = Symbol("pending-entry");
+        const cancelTimeout = this.schedule(() => {
+            // Only the entry this call registered may be timed out. The global
+            // timer never fires a cancelled timeout, but `schedule` is injectable
+            // now and a caller's implementation is not owed that guarantee -- so
+            // the handler checks rather than trusting cancellation to be perfect.
+            // The check compares `token` rather than asking whether the key is
+            // occupied: keys are reused (`pendingDeploys` is keyed by agent
+            // address), so a stale fire can find the key held by a live successor.
+            // Treating that as its own entry would drop the successor without
+            // settling it and run this already-settled entry's per-site cleanup a
+            // second time.
+            const current = this.entries.get(key);
+            if (current === undefined || current.token !== token)
+                return;
+            this.entries.delete(key);
+            options.reject(options.timeoutMessage);
+        }, options.timeoutMs);
+        this.entries.set(key, {
+            key,
+            ws,
+            meta,
+            resolve: options.resolve,
+            reject: options.reject,
+            cancelTimeout,
+            token,
+        });
+    }
+    has(key) {
+        return this.entries.has(key);
+    }
+    get(key) {
+        return this.entries.get(key);
+    }
+    /**
+     * Settle a pending entry as resolved. No-op when the entry is already
+     * gone (timed out or swept on disconnect).
+     */
+    resolve(key, value) {
+        const entry = this.entries.get(key);
+        if (entry === undefined)
+            return false;
+        entry.cancelTimeout();
+        this.entries.delete(key);
+        entry.resolve(value);
+        return true;
+    }
+    /**
+     * Settle a pending entry as rejected. No-op when the entry is already
+     * gone (timed out or swept on disconnect).
+     */
+    reject(key, error) {
+        const entry = this.entries.get(key);
+        if (entry === undefined)
+            return false;
+        entry.cancelTimeout();
+        this.entries.delete(key);
+        entry.reject(error);
+        return true;
+    }
+    /**
+     * Drop a pending entry without settling it. The caller rejects its own
+     * promise directly — used when a frame provably never reached the wire, so
+     * the failure must not take the normal rejection path (the deploy
+     * "failed to send" path, which must report `frameSent: false` and must not
+     * let the armed timer fire later and double-reject).
+     */
+    delete(key) {
+        const entry = this.entries.get(key);
+        if (entry === undefined)
+            return;
+        entry.cancelTimeout();
+        this.entries.delete(key);
+    }
+    /**
+     * Reject every pending entry owned by `ws` — the disconnect sweep. Each
+     * entry's reject closure runs its own per-site cleanup (address
+     * bookkeeping), identical to a frame-error rejection.
+     */
+    rejectAllForWs(ws, error) {
+        for (const [key, entry] of this.entries) {
+            if (entry.ws !== ws)
+                continue;
+            entry.cancelTimeout();
+            this.entries.delete(key);
+            entry.reject(error);
+        }
+    }
+}

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

@@ -13,9 +13,6 @@ export type SidecarMailPersistedPayload = SidecarMailPersistedRow & {
 };
 /** 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;
@@ -50,9 +47,9 @@ export type SidecarEventMap = {
         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. */
+     * carrying every address the connection owned -- 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. */
@@ -80,7 +77,7 @@ export type SidecarEventMap = {
      * 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
+     * local inbox. For a provisioned 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. */
@@ -114,24 +111,6 @@ export type SidecarEventMap = {
         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>;
@@ -146,15 +125,19 @@ export type SidecarEventEmitter = {
 };
 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>;
+    /** Re-resolves a reconnecting deployment's current credential delivery and
+     * reconciles the child, so a credential revoked, deleted, or rotated while
+     * the sidecar was disconnected is applied on reconnect (closing the offline
+     * window). Keyed by the run address. Fire-and-forget: the wire layer does not
+     * await it and it never throws -- a failure is logged and dropped, like the
+     * best-effort source-update pushes. No-ops for a run that persisted no
+     * credential refs. */
+    resyncCredentials?: (agentAddress: string) => void;
     /** 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. */
@@ -163,6 +146,37 @@ export type SidecarLookups = {
         recipients: string[];
         raw: Uint8Array;
     }) => Promise<SidecarMailPersistedRow[]>;
+    /** Resolves the hub-held public key a sender address signs with, hex-encoded,
+     * or `null` when the sender has no resolvable key (a run whose deploy is not
+     * yet acked, an address matching no known principal). The `mail.inbound` frame
+     * carries the result so a recipient verifies the signature locally against the
+     * hub-resolved key rather than the message's own spoofable From. Returns only
+     * the key string, not its source, so the recipient cannot branch on sender
+     * kind.
+     *
+     * Best-effort: this NEVER throws. A resolution fault degrades to `null`
+     * (logged at ERROR by the resolver), so a key-resolution problem can never
+     * block mail delivery. The strict, throwing resolver is `resolveSenderKey`
+     * in `@intx/db`; the reconnect reconciliation consumes it through
+     * `resolveSenderKeyStrict` below, which needs to tell a fault from a genuine
+     * absence. */
+    resolveSenderKey?: (address: string) => Promise<string | null>;
+    /** Strict sibling of `resolveSenderKey` for the reconnect reconciliation. The
+     * register/reconnect handler re-resolves each reported cached sender and acts
+     * on the three-way outcome the best-effort resolver collapses:
+     *   - returns the hex key when the sender resolves -> push `sender.key.refresh`;
+     *   - returns `null` for a CONFIRMED absence (no matching principal = a deleted
+     *     sender) -> push `sender.key.evict`;
+     *   - THROWS on a fault (ambiguous address, a keyless-principal invariant
+     *     break, a DB error) -> keep the stale cached key, evict nothing.
+     * Never evicting on a throw is load-bearing: dropping a live key on a
+     * transient DB fault would be worse than doing nothing. Wraps the strict
+     * `resolveSenderKey` in `@intx/db` (unwrapped to the key string). Note the
+     * naming inversion: in `@intx/db` the STRICT resolver is `resolveSenderKey`
+     * and the best-effort one is `resolveFrameSenderKey`, whereas on this lookup
+     * type the best-effort field is `resolveSenderKey` and this is the strict
+     * one. */
+    resolveSenderKeyStrict?: (address: string) => Promise<string | null>;
     /** 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

package/dist/ws/sidecar-events.js

@@ -29,8 +29,6 @@ export function createSidecarEmitter() {
         "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) {