@intx/hub-sessions 0.2.2 → 0.4.0

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

@@ -1,15 +1,41 @@
-import type { PackRejectReason, RepoId } from "@intx/types/sidecar";
-import type { ConnectorThreadState } from "@intx/types/runtime";
+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";
-    instanceId: string | null;
+    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: "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
@@ -21,11 +47,21 @@ 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. */
+        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
@@ -40,11 +76,30 @@ export type SidecarEventMap = {
      * 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 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. */
+    "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
@@ -56,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>;
@@ -88,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. */
@@ -105,9 +146,73 @@ 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
+     * 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 agent address. The wire
+     * 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"`. */
@@ -118,14 +223,11 @@ export type SidecarLookups = {
         reason: PackRejectReason;
     }>;
     /** Ingests a received workflow-run pack and returns whether the wire
-     * layer should ack or reject the pack to the sidecar. `repoId.kind`
-     * is `"workflow-run"` and `repoId.id` is the deployment id (which the
-     * hub-side substrate maps to a `WorkflowRunSupervisorPrincipal`
-     * during the receivePack call). 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
-     * `"workflow-run"`. */
-    receiveWorkflowRunPack?: (repoId: RepoId, pack: Uint8Array, ref: string, commitSha: string) => Promise<{
+     * 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;

package/dist/ws/sidecar-events.js

@@ -24,11 +24,11 @@ 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) {