@intx/hub-sessions 0.2.2 → 0.4.0

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

@@ -22,7 +22,7 @@ export type WorkflowRunEvent = {
  * path computation) with direct `isomorphic-git` tree/blob reads. It
  * never writes, so it carries no authorize gate of its own; callers
  * gate access at their own boundary (the REST routes use a
- * `workflow-run:<deploymentId>` grant check).
+ * `workflow-run:<runId>` grant check).
  */
 export interface WorkflowRunReader {
     /**

package/dist/workflow-run-reader.js

@@ -1,8 +1,7 @@
 import fs from "node:fs";
 import git from "isomorphic-git";
-import { WORKFLOW_RUN_EVENTS_DIR, WORKFLOW_RUN_RUNS_PREFIX, } from "./workflow-run-kind.js";
+import { requireEventSeq, WORKFLOW_RUN_EVENTS_DIR, WORKFLOW_RUN_RUNS_PREFIX, } from "./workflow-run-kind.js";
 import { WORKFLOW_RUN_EVENTS_FILE, splitCombinedEventLog, } from "./workflow-run-event-log.js";
-const EVENT_FILENAME_RE = /^(0|[1-9][0-9]*)\.json$/;
 export function createWorkflowRunReader(repoStore) {
     function repoDirOrNull(repoId) {
         try {
@@ -106,12 +105,9 @@ export function createWorkflowRunReader(repoStore) {
         for (const entry of tree.tree) {
             if (entry.type !== "blob")
                 continue;
-            const m = EVENT_FILENAME_RE.exec(entry.path);
-            if (m === null || m[1] === undefined)
-                continue;
-            const seq = Number.parseInt(m[1], 10);
-            const blob = await git.readBlob({ fs, dir, oid: entry.oid });
             const path = `${eventsDir}/${entry.path}`;
+            const seq = requireEventSeq(entry.path, path);
+            const blob = await git.readBlob({ fs, dir, oid: entry.oid });
             const parsed = parseEventObject(new TextDecoder().decode(blob.blob), path);
             const type = parsed["type"];
             if (typeof type !== "string") {

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

@@ -0,0 +1,16 @@
+import type { AgentRepoStore } from "./agent-repo.js";
+import type { AllocatedSidecarTarget, SidecarAllocationRouter } from "./ws/sidecar-handler.js";
+export declare const WORKFLOW_RUN_RESTORE_REFS: readonly ["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 declare function restoreWorkflowRunToAllocation(args: {
+    agentRepoStore: AgentRepoStore;
+    allocationRouter: Pick<SidecarAllocationRouter, "sendWorkflowRunPackToAllocation">;
+    allocationTarget: AllocatedSidecarTarget;
+    agentAddress: string;
+    signal?: AbortSignal;
+}): Promise<void>;

package/dist/workflow-run-restore.js

@@ -0,0 +1,30 @@
+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) {
+        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);
+        args.signal?.throwIfAborted();
+        await allocationRouter.sendWorkflowRunPackToAllocation(allocationTarget, agentAddress, pack.pack, pack.ref, pack.commitSha, args.signal);
+    }
+    args.signal?.throwIfAborted();
+}

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/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 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, 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 { createSidecarTokenAuthenticator, } from "./sidecar-token-authenticator.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;
+}