@intx/hub-sessions 0.2.2 → 0.3.0

package/dist/workflow-run-restore.js

@@ -0,0 +1,26 @@
+import { deriveWorkflowRunRepoId } from "@intx/workflow-deploy";
+export const WORKFLOW_RUN_RESTORE_REFS = [
+    "refs/heads/main",
+    "refs/heads/events",
+];
+/**
+ * Replay every authoritative workflow-run ref the runtime understands onto an
+ * exact replacement allocation. Refs are sent sequentially and the function
+ * resolves only after the worker acknowledges each one, making it a barrier
+ * the deploy path can place before supervisor spawn.
+ */
+export async function restoreWorkflowRunToAllocation(args) {
+    const { agentRepoStore, allocationRouter, allocationTarget, agentAddress } = args;
+    const principal = { kind: "hub" };
+    const repoId = {
+        kind: "workflow-run",
+        id: deriveWorkflowRunRepoId(agentAddress),
+    };
+    for (const ref of WORKFLOW_RUN_RESTORE_REFS) {
+        const tip = await agentRepoStore.repoStore.resolveRef(principal, repoId, ref);
+        if (tip === null)
+            continue;
+        const pack = await agentRepoStore.repoStore.createPack(principal, repoId, ref);
+        await allocationRouter.sendWorkflowRunPackToAllocation(allocationTarget, agentAddress, pack.pack, pack.ref, pack.commitSha);
+    }
+}

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

@@ -0,0 +1,35 @@
+import { type PackumentFetcher, type RegistryConfig } from "@intx/tool-packaging";
+import type { ToolPackageManifest } from "@intx/types/tool-packages";
+import type { WorkflowDefinitionAssetSource } from "@intx/types/workflow-sources";
+import type { CommittedTreeEntry } from "./repo-store/types.js";
+/** Git-tree reads pinned to the source's commit. */
+export interface SourceTreeReads {
+    readBlob(path: string): Promise<Uint8Array>;
+    listDir(path: string): Promise<CommittedTreeEntry[]>;
+    treeOid(path: string): Promise<string | null>;
+}
+export interface ResolveSourceWorkflowClosureArgs {
+    /** A source whose `package.format` is `"source"`. */
+    readonly source: WorkflowDefinitionAssetSource;
+    readonly reads: SourceTreeReads;
+    /**
+     * The registry name external deps are stamped with in the frozen closure.
+     * The sidecar resolves each entry's `source.registry` against its own
+     * registry map at materialization, so this MUST be a name that map is keyed
+     * by (the sidecar's npm registry, e.g. `"npmjs"`); an unknown name fails the
+     * materialization loud. The caller owns the sidecar's registry configuration,
+     * so it supplies the name here rather than the walk inventing one.
+     */
+    readonly registryName: string;
+    /** URL and credentials for the npm registry external deps resolve against. */
+    readonly registryConfig: RegistryConfig;
+    /** Test seam for external packument fetches. */
+    readonly fetchPackument?: PackumentFetcher;
+}
+/**
+ * Resolve a source-format workflow definition's dependency closure to a frozen
+ * `ToolPackageManifest`: a `format:"source"` entry for the workflow package and
+ * each workspace-local dependency (identity = git tree oid), plus tarball
+ * entries for the external npm closure.
+ */
+export declare function resolveSourceWorkflowClosure(args: ResolveSourceWorkflowClosureArgs): Promise<ToolPackageManifest>;

package/dist/workflow-source-closure.js

@@ -0,0 +1,342 @@
+// Hub-side dependency-closure resolution for a SOURCE-format workflow
+// definition -- a codebase living as a subtree of a hub git asset at a
+// pinned commit.
+//
+// Unlike the registry and tarball arms (which resolve against npm packuments
+// with SRI integrity), a source package has no packument: its content
+// identity is the git tree oid of its subtree, and its dependency closure is
+// a DISJOINT UNION of two origins built by construction --
+//   - workspace-local members (other subtrees in the SAME asset) become
+//     `format:"source"` entries and are walked recursively, and
+//   - external npm dependencies are resolved through the pristine registry
+//     walker (which keeps its SRI invariant intact) into tarball entries.
+// A member name never appears in the external set, so the two origins cannot
+// collide on a workspace member; the one residual collision (an external
+// transitive dep whose `name@version` equals a member's) is detected and
+// fails loud rather than silently picking an origin.
+import { HttpRegistrySource, createClosureResolver, } from "@intx/tool-packaging";
+/**
+ * Resolve a source-format workflow definition's dependency closure to a frozen
+ * `ToolPackageManifest`: a `format:"source"` entry for the workflow package and
+ * each workspace-local dependency (identity = git tree oid), plus tarball
+ * entries for the external npm closure.
+ */
+export async function resolveSourceWorkflowClosure(args) {
+    const { source, reads, registryName, registryConfig, fetchPackument } = args;
+    if (source.package.format !== "source") {
+        throw new Error("resolveSourceWorkflowClosure: source.package.format must be 'source'");
+    }
+    const { commitSha, packageName } = source.package;
+    const assetId = source.assetId;
+    const { members, rootName, catalog } = await enumerateMembers(reads);
+    const selected = selectMember(members, packageName);
+    // BFS over the reachable workspace members. A dependency classifies by NAME,
+    // never by parsing its range: a name that is a member recurses (a
+    // workspace-local edge); the workspace root's own name is an invalid target
+    // (the root is not a member) and fails loud regardless of how the range is
+    // spelled; anything else is external and resolves through the registry walker.
+    //
+    // External deps collect by name, and a second member contributing the same
+    // name at a DIFFERENT resolved range fails loud rather than silently
+    // collapsing to one pin -- the walker resolves a single range per name, so a
+    // silent overwrite would drop a real constraint. This is a DELIBERATE v1
+    // limitation: two members with drifting-but-compatible ranges (e.g. `^1.0.0`
+    // and `^1.2.0`) that npm/bun would reconcile to one version are rejected here,
+    // not intersected. Aligning the ranges across members, or declaring the dep
+    // once in the root `catalog`, resolves it. (Semver intersection across
+    // members is tracked separately as INTR-460.)
+    const sourceEntries = [];
+    const externalPins = new Map();
+    const seen = new Set();
+    const queue = [selected.name];
+    while (queue.length > 0) {
+        const memberName = queue.shift();
+        if (memberName === undefined || seen.has(memberName))
+            continue;
+        seen.add(memberName);
+        const member = members.get(memberName);
+        if (member === undefined) {
+            throw new Error(`resolveSourceWorkflowClosure: internal -- member ${JSON.stringify(memberName)} was queued but not enumerated`);
+        }
+        const treeOid = await reads.treeOid(member.packageDir);
+        if (treeOid === null) {
+            throw new Error(`resolveSourceWorkflowClosure: subtree ${JSON.stringify(member.packageDir)} not found at commit ${commitSha}`);
+        }
+        sourceEntries.push({
+            name: member.name,
+            version: member.version,
+            source: {
+                kind: "asset",
+                assetId,
+                package: {
+                    format: "source",
+                    commitSha,
+                    packageDir: member.packageDir,
+                    treeOid,
+                },
+            },
+        });
+        for (const [depName, depSpec] of Object.entries(member.dependencies)) {
+            if (members.has(depName)) {
+                queue.push(depName);
+                continue;
+            }
+            if (rootName !== undefined && depName === rootName) {
+                throw new Error(`resolveSourceWorkflowClosure: member ${JSON.stringify(member.name)} depends on the workspace root ${JSON.stringify(rootName)}, which is not a workspace member`);
+            }
+            const resolvedSpec = resolveExternalSpec(depName, depSpec, catalog);
+            const existing = externalPins.get(depName);
+            if (existing !== undefined && existing !== resolvedSpec) {
+                throw new Error(`resolveSourceWorkflowClosure: workspace members pin external ${JSON.stringify(depName)} at conflicting ranges ${JSON.stringify(existing)} and ${JSON.stringify(resolvedSpec)}; the closure resolves a single range per name`);
+            }
+            externalPins.set(depName, resolvedSpec);
+        }
+    }
+    const externalEntries = externalPins.size > 0
+        ? await resolveExternalClosure(externalPins, registryName, registryConfig, fetchPackument)
+        : [];
+    return {
+        schemaVersion: "1",
+        topLevel: [{ name: selected.name, version: selected.version }],
+        entries: mergeDisjoint(sourceEntries, externalEntries),
+    };
+}
+/**
+ * Read the workspace members from the asset's tree. A repo with no
+ * `workspaces` field is a single package rooted at the tree (the root IS the
+ * one member). A `workspaces` monorepo enumerates its members from the globs;
+ * the root is the workspace root, NOT a member -- its `name`/`catalog` inform
+ * dependency classification but it contributes no closure entry.
+ */
+async function enumerateMembers(reads) {
+    const root = await readPackageJSON(reads, ".");
+    if (root.workspaces === undefined) {
+        // A pnpm monorepo declares its members in `pnpm-workspace.yaml`, not the
+        // package.json `workspaces` field, so a pnpm root reaches here looking like
+        // a single package. Detect that layout and fail loud rather than silently
+        // misread the private root as the workflow. Full pnpm support is tracked in
+        // INTR-461.
+        if (await rootHasPnpmWorkspaceFile(reads)) {
+            throw new Error(`resolveSourceWorkflowClosure: the asset root declares a pnpm-workspace.yaml; the pnpm workspace layout is not supported -- declare members via a package.json "workspaces" array`);
+        }
+        // Single-package: the root is the workflow package itself, so it must
+        // declare a name and version.
+        const member = requireMember(root, ".");
+        return {
+            members: new Map([[member.name, member]]),
+            rootName: root.name,
+            catalog: root.catalog,
+        };
+    }
+    const members = new Map();
+    for (const glob of root.workspaces) {
+        for (const packageDir of await expandWorkspaceGlob(reads, glob)) {
+            // A `<dir>/*` glob matches every subdirectory, but not all are packages
+            // (docs, fixtures, ...). Skip a directory with no package.json rather than
+            // fail the whole resolution, matching how bun/yarn/pnpm treat a
+            // non-package directory that a workspace glob happens to match. A
+            // directory that HAS a package.json must still parse and declare a name
+            // and version, so a malformed member fails loud.
+            if (!(await dirHasPackageJSON(reads, packageDir)))
+                continue;
+            const parsed = await readPackageJSON(reads, packageDir);
+            const member = requireMember(parsed, packageDir);
+            if (members.has(member.name)) {
+                throw new Error(`resolveSourceWorkflowClosure: workspace member ${JSON.stringify(member.name)} is declared by more than one package directory`);
+            }
+            members.set(member.name, member);
+        }
+    }
+    if (members.size === 0) {
+        throw new Error(`resolveSourceWorkflowClosure: workspaces ${JSON.stringify(root.workspaces)} matched no member packages`);
+    }
+    return { members, rootName: root.name, catalog: root.catalog };
+}
+/**
+ * Turn a parsed package.json at `packageDir` into a workspace member, failing
+ * loud if it does not declare both a string `name` and `version` (the closure
+ * entry it produces is keyed on `name@version`).
+ */
+function requireMember(parsed, packageDir) {
+    if (parsed.name === undefined || parsed.version === undefined) {
+        const blobPath = packageDir === "." ? "package.json" : `${packageDir}/package.json`;
+        throw new Error(`resolveSourceWorkflowClosure: ${blobPath} must declare string "name" and "version"`);
+    }
+    return {
+        name: parsed.name,
+        version: parsed.version,
+        packageDir,
+        dependencies: parsed.dependencies,
+    };
+}
+/**
+ * Expand one `workspaces` glob to the member directories it names. Supports
+ * `<base>/*` (each subtree directly under `<base>`) and an exact path (no glob
+ * character). Any richer shape (`**`, a mid-segment `*`, braces, negation)
+ * fails loud rather than risk mis-enumerating the workspace.
+ */
+async function expandWorkspaceGlob(reads, glob) {
+    const trimmed = glob.replace(/\/+$/, "");
+    if (!/[*{}!]/.test(trimmed)) {
+        return [trimmed];
+    }
+    const suffix = "/*";
+    const base = trimmed.slice(0, -suffix.length);
+    if (trimmed.endsWith(suffix) && !/[*{}!]/.test(base)) {
+        const children = await reads.listDir(base === "" ? "." : base);
+        return children
+            .filter((child) => child.type === "tree")
+            .map((child) => (base === "" ? child.name : `${base}/${child.name}`));
+    }
+    throw new Error(`resolveSourceWorkflowClosure: unsupported workspaces glob ${JSON.stringify(glob)}; only "<dir>/*" and exact paths are supported`);
+}
+/** Whether `dir` holds a `package.json` blob (i.e. is a package directory). */
+async function dirHasPackageJSON(reads, dir) {
+    const entries = await reads.listDir(dir);
+    return entries.some((entry) => entry.name === "package.json" && entry.type === "blob");
+}
+/** Whether the tree root holds a `pnpm-workspace.yaml` blob (the pnpm layout). */
+async function rootHasPnpmWorkspaceFile(reads) {
+    const entries = await reads.listDir(".");
+    return entries.some((entry) => entry.name === "pnpm-workspace.yaml" && entry.type === "blob");
+}
+function selectMember(members, packageName) {
+    if (packageName !== undefined) {
+        const member = members.get(packageName);
+        if (member === undefined) {
+            throw new Error(`resolveSourceWorkflowClosure: workflow member ${JSON.stringify(packageName)} is not a workspace member`);
+        }
+        return member;
+    }
+    if (members.size !== 1) {
+        throw new Error("resolveSourceWorkflowClosure: a monorepo source requires a packageName selector");
+    }
+    const [only] = members.values();
+    if (only === undefined) {
+        throw new Error("resolveSourceWorkflowClosure: internal -- no members");
+    }
+    return only;
+}
+async function readPackageJSON(reads, packageDir) {
+    const blobPath = packageDir === "." ? "package.json" : `${packageDir}/package.json`;
+    let bytes;
+    try {
+        bytes = await reads.readBlob(blobPath);
+    }
+    catch (err) {
+        throw new Error(`resolveSourceWorkflowClosure: could not read ${blobPath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(new TextDecoder().decode(bytes));
+    }
+    catch (err) {
+        throw new Error(`resolveSourceWorkflowClosure: ${blobPath} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!isRecord(raw)) {
+        throw new Error(`resolveSourceWorkflowClosure: ${blobPath} is not an object`);
+    }
+    // `name`/`version` are optional here: a private workspace root routinely
+    // omits them. A member that omits either fails loud where it is turned into a
+    // WorkspaceMember (`requireMember`), not here.
+    const nameRaw = raw["name"];
+    const versionRaw = raw["version"];
+    const name = typeof nameRaw === "string" ? nameRaw : undefined;
+    const version = typeof versionRaw === "string" ? versionRaw : undefined;
+    const depsRaw = raw["dependencies"];
+    const dependencies = {};
+    if (isRecord(depsRaw)) {
+        for (const [k, v] of Object.entries(depsRaw)) {
+            if (typeof v === "string")
+                dependencies[k] = v;
+        }
+    }
+    const workspacesRaw = raw["workspaces"];
+    let workspaces;
+    if (workspacesRaw === undefined) {
+        workspaces = undefined;
+    }
+    else if (Array.isArray(workspacesRaw) &&
+        workspacesRaw.every((w) => typeof w === "string")) {
+        workspaces = workspacesRaw;
+    }
+    else {
+        throw new Error(`resolveSourceWorkflowClosure: ${blobPath} "workspaces" must be an array of glob strings; the object form ({ packages, catalog, catalogs }) is not supported`);
+    }
+    const catalogRaw = raw["catalog"];
+    let catalog;
+    if (isRecord(catalogRaw)) {
+        catalog = {};
+        for (const [k, v] of Object.entries(catalogRaw)) {
+            if (typeof v === "string")
+                catalog[k] = v;
+        }
+    }
+    return { name, version, dependencies, workspaces, catalog };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Translate an EXTERNAL dependency specifier (one whose name is not a workspace
+ * member) to a concrete npm range the registry walker can pick against:
+ *   - `workspace:` protocol -- the name is not a member, so this is an invalid
+ *     workspace reference; fail loud.
+ *   - bare `catalog:` -- expand against the root `catalog` object; fail loud if
+ *     the catalog declares no entry for this name.
+ *   - named `catalog:<name>` -- not supported; fail loud.
+ *   - plain range -- pass through.
+ */
+function resolveExternalSpec(depName, spec, catalog) {
+    if (spec.startsWith("workspace:")) {
+        throw new Error(`resolveSourceWorkflowClosure: ${depName} uses ${JSON.stringify(spec)} but is not a workspace member`);
+    }
+    if (spec === "catalog:") {
+        const range = catalog?.[depName];
+        if (range === undefined) {
+            throw new Error(`resolveSourceWorkflowClosure: ${depName} uses the default catalog but the workspace root declares no "catalog" entry for it`);
+        }
+        return range;
+    }
+    if (spec.startsWith("catalog:")) {
+        throw new Error(`resolveSourceWorkflowClosure: ${depName} uses named catalog ${JSON.stringify(spec)}, which is not supported`);
+    }
+    return spec;
+}
+async function resolveExternalClosure(pins, registryName, registryConfig, fetchPackument) {
+    const registrySource = new HttpRegistrySource({
+        name: registryName,
+        config: registryConfig,
+        ...(fetchPackument !== undefined ? { fetchPackument } : {}),
+    });
+    const resolver = createClosureResolver({
+        registries: new Map([[registryName, registrySource]]),
+        defaultRegistry: registryName,
+    });
+    const rootPins = [...pins].map(([name, version]) => ({
+        name,
+        version,
+    }));
+    const manifest = await resolver.resolveClosure(rootPins);
+    return [...manifest.entries];
+}
+/**
+ * Union the source and external entries, deduped on `name@version`. A key that
+ * appears in BOTH origins is an unrepresentable collision (the manifest keys on
+ * `name@version` with neither treeOid nor SRI participating), so fail loud
+ * rather than silently picking one origin.
+ */
+function mergeDisjoint(sourceEntries, externalEntries) {
+    const byKey = new Map();
+    for (const entry of sourceEntries) {
+        byKey.set(`${entry.name}@${entry.version}`, entry);
+    }
+    for (const entry of externalEntries) {
+        const key = `${entry.name}@${entry.version}`;
+        if (byKey.has(key)) {
+            throw new Error(`resolveSourceWorkflowClosure: ${key} resolved from both a workspace member and an external registry; the closure cannot represent both origins`);
+        }
+        byKey.set(key, entry);
+    }
+    return [...byKey.values()];
+}

package/dist/ws/index.d.ts

@@ -1,3 +1,3 @@
-export { createSidecarRouter, type SidecarRouter, type SidecarRouterConfig, type SidecarConnection, type SidecarAuthIdentity, type SidecarAuthenticator, type SendPackOptions, type WsHandle, } from "./sidecar-handler.js";
-export { createSidecarTokenAuthenticator, type CreateSidecarTokenAuthenticatorDeps, } from "./sidecar-token-authenticator.js";
-export { createSidecarEmitter, type SidecarEventEmitter, type SidecarEventMap, type SidecarEventType, type SidecarEventListener, type SidecarLookups, type SidecarMailPersistedRow, type SidecarMailPersistedPayload, } from "./sidecar-events.js";
+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 { 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 { createSidecarTokenAuthenticator, } from "./sidecar-token-authenticator.js";
+export { createSidecarCredentialResolver, createSidecarTokenAuthenticator, } from "./sidecar-token-authenticator.js";
 export { createSidecarEmitter, } from "./sidecar-events.js";

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

@@ -1,15 +1,44 @@
-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: "shared";
+    readonly agentAddress: string;
+} | {
+    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
@@ -26,6 +55,16 @@ export type SidecarEventMap = {
      * 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 +79,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 an exclusive 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
@@ -105,9 +163,42 @@ export type SidecarLookups = {
         recipients: string[];
         raw: Uint8Array;
     }) => Promise<SidecarMailPersistedRow[]>;
+    /** 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 +209,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,8 +24,10 @@ 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(),