@vercel/factory 0.0.14 → 0.0.16

package/dist/work-triage/eve-tool.mjs

@@ -0,0 +1,32 @@
+import { repositoryIdSchema } from "../schema/id.mjs";
+import { repositoryIdsForSession } from "../eve/task-session.mjs";
+import { findExistingWork } from "./find-existing-work.mjs";
+import { z } from "zod";
+import { defineTool } from "eve/tools";
+//#region src/work-triage/eve-tool.ts
+/**
+* Read-only triage helper: before delegating new work or accepting a signal,
+* check whether an open pull request, a recorded Change, or an in-flight
+* Task already covers the same repository, so Foreman does not duplicate
+* work that is already underway.
+*/
+function createFindExistingWorkTool(input) {
+	const { stores, ...options } = input;
+	return defineTool({
+		description: "Check whether an open pull request, a recorded change, or an in-flight task already covers a repository's pending work. Call this before delegating new work or deciding a signal as accepted, so Factory does not duplicate work already underway. Read-only.",
+		inputSchema: z.object({ repositoryId: repositoryIdSchema.describe("Repository the pending signal or request is about.") }),
+		async execute({ repositoryId }, ctx) {
+			const binding = repositoryIdsForSession(ctx.session.auth.initiator);
+			if (binding !== null && !binding.includes(repositoryId)) throw new Error(`Repository ${repositoryId} is outside the connector-authenticated context.`);
+			return findExistingWork({
+				stores,
+				repositoryId,
+				...options
+			});
+		}
+	});
+}
+//#endregion
+export { createFindExistingWorkTool };
+
+//# sourceMappingURL=eve-tool.mjs.map

package/dist/work-triage/eve-tool.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"eve-tool.mjs","names":[],"sources":["../../src/work-triage/eve-tool.ts"],"sourcesContent":["import { defineTool, type ToolContext, type ToolDefinition } from \"eve/tools\";\nimport { z } from \"zod\";\nimport { repositoryIdSchema, type RepositoryId } from \"../schema/id\";\nimport type { FactoryStores } from \"../store/engine\";\nimport {\n  findExistingWork,\n  type ExistingWorkLookupOptions,\n  type ExistingWorkLookupResult,\n} from \"./find-existing-work\";\nimport { repositoryIdsForSession } from \"../eve/task-session\";\n\n/** Change, repository, and Task capabilities required by the existing-work tool. */\nexport type FindExistingWorkToolStores = Pick<FactoryStores, \"changes\" | \"repositories\" | \"tasks\">;\n\n/** Stores and provider lookup used to construct the existing-work tool. */\nexport interface FindExistingWorkToolOptions extends ExistingWorkLookupOptions {\n  stores: FindExistingWorkToolStores;\n}\n\n/** Repository selected for a read-only existing-work lookup. */\nexport interface FindExistingWorkToolInput {\n  repositoryId: RepositoryId;\n}\n\n/** Eve tool that checks a repository for overlapping open work. */\nexport interface FindExistingWorkTool extends ToolDefinition<\n  FindExistingWorkToolInput,\n  ExistingWorkLookupResult\n> {\n  execute(input: FindExistingWorkToolInput, ctx: ToolContext): Promise<ExistingWorkLookupResult>;\n}\n\n/**\n * Read-only triage helper: before delegating new work or accepting a signal,\n * check whether an open pull request, a recorded Change, or an in-flight\n * Task already covers the same repository, so Foreman does not duplicate\n * work that is already underway.\n */\nexport function createFindExistingWorkTool(\n  input: FindExistingWorkToolOptions,\n): FindExistingWorkTool {\n  const { stores, ...options } = input;\n  return defineTool({\n    description:\n      \"Check whether an open pull request, a recorded change, or an in-flight task already \" +\n      \"covers a repository's pending work. Call this before delegating new work or deciding a \" +\n      \"signal as accepted, so Factory does not duplicate work already underway. Read-only.\",\n    inputSchema: z.object({\n      repositoryId: repositoryIdSchema.describe(\n        \"Repository the pending signal or request is about.\",\n      ),\n    }),\n    async execute({ repositoryId }, ctx): Promise<ExistingWorkLookupResult> {\n      // The connector binding is an authorization envelope: a steered\n      // conversation must not read another repository's in-flight work.\n      const binding = repositoryIdsForSession(ctx.session.auth.initiator);\n      if (binding !== null && !binding.includes(repositoryId)) {\n        throw new Error(\n          `Repository ${repositoryId} is outside the connector-authenticated context.`,\n        );\n      }\n      return findExistingWork({ stores, repositoryId, ...options });\n    },\n  });\n}\n"],"mappings":";;;;;;;;;;;;AAsCA,SAAgB,2BACd,OACsB;CACtB,MAAM,EAAE,QAAQ,GAAG,YAAY;CAC/B,OAAO,WAAW;EAChB,aACE;EAGF,aAAa,EAAE,OAAO,EACpB,cAAc,mBAAmB,SAC/B,oDACF,EACF,CAAC;EACD,MAAM,QAAQ,EAAE,gBAAgB,KAAwC;GAGtE,MAAM,UAAU,wBAAwB,IAAI,QAAQ,KAAK,SAAS;GAClE,IAAI,YAAY,QAAQ,CAAC,QAAQ,SAAS,YAAY,GACpD,MAAM,IAAI,MACR,cAAc,aAAa,iDAC7B;GAEF,OAAO,iBAAiB;IAAE;IAAQ;IAAc,GAAG;GAAQ,CAAC;EAC9D;CACF,CAAC;AACH"}

package/dist/work-triage/find-existing-work.d.mts

@@ -0,0 +1,32 @@
+import { RepositoryId } from "../schema/id.mjs";
+import { RepositorySlug } from "../schema/repository.mjs";
+import { Task } from "../schema/task.mjs";
+import { Change } from "../schema/change.mjs";
+import { FactoryStores } from "../store/engine.mjs";
+import { OpenPullRequest } from "../pull-requests/contracts.mjs";
+//#region src/work-triage/find-existing-work.d.ts
+/** Provider-neutral readers used to discover work already in progress. */
+interface ExistingWorkLookupOptions {
+  listOpenPullRequests: (repository: RepositorySlug) => Promise<readonly OpenPullRequest[]>;
+}
+/** Stores, repository identity, and provider lookup used for one existing-work query. */
+interface FindExistingWorkInput extends ExistingWorkLookupOptions {
+  stores: Pick<FactoryStores, "changes" | "repositories" | "tasks">;
+  repositoryId: RepositoryId;
+}
+/** The refusal or existing pull requests, Changes, and active Tasks found during triage. */
+type ExistingWorkLookupResult = {
+  found: false;
+  reasonCode: "repository_not_found";
+  reason: string;
+} | {
+  found: true;
+  openPullRequests: readonly OpenPullRequest[];
+  openChanges: readonly Change[];
+  activeTasks: readonly Task[];
+};
+/** Find open pull requests, Changes, and active Tasks for one repository. */
+declare function findExistingWork(input: FindExistingWorkInput): Promise<ExistingWorkLookupResult>;
+//#endregion
+export { ExistingWorkLookupOptions, ExistingWorkLookupResult, FindExistingWorkInput, findExistingWork };
+//# sourceMappingURL=find-existing-work.d.mts.map

package/dist/work-triage/find-existing-work.mjs

@@ -0,0 +1,31 @@
+//#region src/work-triage/find-existing-work.ts
+const openChangeStates = /* @__PURE__ */ new Set(["verifying", "ready"]);
+const activeTaskStates = /* @__PURE__ */ new Set([
+	"queued",
+	"running",
+	"needs_human"
+]);
+/** Find open pull requests, Changes, and active Tasks for one repository. */
+async function findExistingWork(input) {
+	const repository = await input.stores.repositories.get(input.repositoryId);
+	if (repository === null) return {
+		found: false,
+		reasonCode: "repository_not_found",
+		reason: `repository ${input.repositoryId} does not exist`
+	};
+	const [openPullRequests, changes, tasks] = await Promise.all([
+		input.listOpenPullRequests(repository.slug),
+		input.stores.changes.list(),
+		input.stores.tasks.list()
+	]);
+	return {
+		found: true,
+		openPullRequests,
+		openChanges: changes.filter((change) => change.repositoryId === input.repositoryId && openChangeStates.has(change.state)),
+		activeTasks: tasks.filter((task) => task.repositoryIds.includes(input.repositoryId) && activeTaskStates.has(task.state))
+	};
+}
+//#endregion
+export { findExistingWork };
+
+//# sourceMappingURL=find-existing-work.mjs.map

package/dist/work-triage/find-existing-work.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-existing-work.mjs","names":[],"sources":["../../src/work-triage/find-existing-work.ts"],"sourcesContent":["import type { Change } from \"../schema/change\";\nimport type { Task } from \"../schema/task\";\nimport type { FactoryStores } from \"../store/engine\";\nimport type { OpenPullRequest } from \"../pull-requests/contracts\";\nimport type { RepositoryId } from \"../schema/id\";\nimport type { RepositorySlug } from \"../schema/repository\";\n\n/** Provider-neutral readers used to discover work already in progress. */\nexport interface ExistingWorkLookupOptions {\n  listOpenPullRequests: (repository: RepositorySlug) => Promise<readonly OpenPullRequest[]>;\n}\n\n/** Stores, repository identity, and provider lookup used for one existing-work query. */\nexport interface FindExistingWorkInput extends ExistingWorkLookupOptions {\n  stores: Pick<FactoryStores, \"changes\" | \"repositories\" | \"tasks\">;\n  repositoryId: RepositoryId;\n}\n\n/** The refusal or existing pull requests, Changes, and active Tasks found during triage. */\nexport type ExistingWorkLookupResult =\n  | { found: false; reasonCode: \"repository_not_found\"; reason: string }\n  | {\n      found: true;\n      openPullRequests: readonly OpenPullRequest[];\n      openChanges: readonly Change[];\n      activeTasks: readonly Task[];\n    };\n\nconst openChangeStates: ReadonlySet<Change[\"state\"]> = new Set([\"verifying\", \"ready\"]);\nconst activeTaskStates: ReadonlySet<Task[\"state\"]> = new Set([\"queued\", \"running\", \"needs_human\"]);\n\n/** Find open pull requests, Changes, and active Tasks for one repository. */\nexport async function findExistingWork(\n  input: FindExistingWorkInput,\n): Promise<ExistingWorkLookupResult> {\n  const repository = await input.stores.repositories.get(input.repositoryId);\n  if (repository === null) {\n    return {\n      found: false,\n      reasonCode: \"repository_not_found\",\n      reason: `repository ${input.repositoryId} does not exist`,\n    };\n  }\n  const [openPullRequests, changes, tasks] = await Promise.all([\n    input.listOpenPullRequests(repository.slug),\n    input.stores.changes.list(),\n    input.stores.tasks.list(),\n  ]);\n  return {\n    found: true,\n    openPullRequests,\n    openChanges: changes.filter(\n      (change) => change.repositoryId === input.repositoryId && openChangeStates.has(change.state),\n    ),\n    activeTasks: tasks.filter(\n      (task) => task.repositoryIds.includes(input.repositoryId) && activeTaskStates.has(task.state),\n    ),\n  };\n}\n"],"mappings":";AA4BA,MAAM,mCAAiD,IAAI,IAAI,CAAC,aAAa,OAAO,CAAC;AACrF,MAAM,mCAA+C,IAAI,IAAI;CAAC;CAAU;CAAW;AAAa,CAAC;;AAGjG,eAAsB,iBACpB,OACmC;CACnC,MAAM,aAAa,MAAM,MAAM,OAAO,aAAa,IAAI,MAAM,YAAY;CACzE,IAAI,eAAe,MACjB,OAAO;EACL,OAAO;EACP,YAAY;EACZ,QAAQ,cAAc,MAAM,aAAa;CAC3C;CAEF,MAAM,CAAC,kBAAkB,SAAS,SAAS,MAAM,QAAQ,IAAI;EAC3D,MAAM,qBAAqB,WAAW,IAAI;EAC1C,MAAM,OAAO,QAAQ,KAAK;EAC1B,MAAM,OAAO,MAAM,KAAK;CAC1B,CAAC;CACD,OAAO;EACL,OAAO;EACP;EACA,aAAa,QAAQ,QAClB,WAAW,OAAO,iBAAiB,MAAM,gBAAgB,iBAAiB,IAAI,OAAO,KAAK,CAC7F;EACA,aAAa,MAAM,QAChB,SAAS,KAAK,cAAc,SAAS,MAAM,YAAY,KAAK,iBAAiB,IAAI,KAAK,KAAK,CAC9F;CACF;AACF"}

package/dist/work-triage/github.d.mts

@@ -0,0 +1,15 @@
+import { RepositorySlug } from "../schema/repository.mjs";
+import { OpenPullRequest } from "../pull-requests/contracts.mjs";
+//#region src/work-triage/github.d.ts
+/** Lists open GitHub pull requests for one repository during work triage. */
+type GitHubOpenPullRequestLister = (repository: RepositorySlug) => Promise<readonly OpenPullRequest[]>;
+/** GitHub credentials and transport used to list open pull requests during work triage. */
+interface GitHubOpenPullRequestListerOptions {
+  tokenForRepository: (repository: RepositorySlug) => Promise<string>;
+  fetch?: typeof globalThis.fetch;
+}
+/** Create the GitHub open-pull-request reader consumed by provider-neutral work triage. */
+declare function createGitHubOpenPullRequestLister(options: GitHubOpenPullRequestListerOptions): GitHubOpenPullRequestLister;
+//#endregion
+export { GitHubOpenPullRequestLister, GitHubOpenPullRequestListerOptions, createGitHubOpenPullRequestLister };
+//# sourceMappingURL=github.d.mts.map

package/dist/work-triage/github.mjs

@@ -0,0 +1,14 @@
+import { listOpenPullRequests } from "../github.mjs";
+//#region src/work-triage/github.ts
+/** Create the GitHub open-pull-request reader consumed by provider-neutral work triage. */
+function createGitHubOpenPullRequestLister(options) {
+	return async (repository) => listOpenPullRequests({
+		repository,
+		token: await options.tokenForRepository(repository),
+		fetch: options.fetch
+	});
+}
+//#endregion
+export { createGitHubOpenPullRequestLister };
+
+//# sourceMappingURL=github.mjs.map

package/dist/work-triage/github.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"github.mjs","names":[],"sources":["../../src/work-triage/github.ts"],"sourcesContent":["import { listOpenPullRequests } from \"../github\";\nimport type { OpenPullRequest } from \"../pull-requests/contracts\";\nimport type { RepositorySlug } from \"../schema/repository\";\n\n/** Lists open GitHub pull requests for one repository during work triage. */\nexport type GitHubOpenPullRequestLister = (\n  repository: RepositorySlug,\n) => Promise<readonly OpenPullRequest[]>;\n\n/** GitHub credentials and transport used to list open pull requests during work triage. */\nexport interface GitHubOpenPullRequestListerOptions {\n  tokenForRepository: (repository: RepositorySlug) => Promise<string>;\n  fetch?: typeof globalThis.fetch;\n}\n\n/** Create the GitHub open-pull-request reader consumed by provider-neutral work triage. */\nexport function createGitHubOpenPullRequestLister(\n  options: GitHubOpenPullRequestListerOptions,\n): GitHubOpenPullRequestLister {\n  return async (repository) =>\n    listOpenPullRequests({\n      repository,\n      token: await options.tokenForRepository(repository),\n      fetch: options.fetch,\n    });\n}\n"],"mappings":";;;AAgBA,SAAgB,kCACd,SAC6B;CAC7B,OAAO,OAAO,eACZ,qBAAqB;EACnB;EACA,OAAO,MAAM,QAAQ,mBAAmB,UAAU;EAClD,OAAO,QAAQ;CACjB,CAAC;AACL"}

package/dist/work-triage.d.mts

@@ -0,0 +1,4 @@
+/// <reference types="node" />
+import { ExistingWorkLookupOptions, ExistingWorkLookupResult, FindExistingWorkInput, findExistingWork } from "./work-triage/find-existing-work.mjs";
+import { FindExistingWorkTool, FindExistingWorkToolInput, FindExistingWorkToolOptions, FindExistingWorkToolStores, createFindExistingWorkTool } from "./work-triage/eve-tool.mjs";
+export { type ExistingWorkLookupOptions, type ExistingWorkLookupResult, type FindExistingWorkInput, type FindExistingWorkTool, type FindExistingWorkToolInput, type FindExistingWorkToolOptions, type FindExistingWorkToolStores, createFindExistingWorkTool, findExistingWork };

package/dist/work-triage.mjs

@@ -0,0 +1,3 @@
+import { findExistingWork } from "./work-triage/find-existing-work.mjs";
+import { createFindExistingWorkTool } from "./work-triage/eve-tool.mjs";
+export { createFindExistingWorkTool, findExistingWork };

package/dist/workflows.d.mts

@@ -0,0 +1,146 @@
+import { AgentRouteBinding, AgentRouteBindingInput, agentRouteBindingSchema, parseAgentRouteBinding } from "./schema/agent-route.mjs";
+import { JsonValue, MAX_WORK_JSON_BYTES, MAX_WORK_JSON_DEPTH, TaskWork, TaskWorkOptions, TaskWorkResult, WorkflowBinding, WorkflowBindingInput, WorkflowReference, WorkflowReferenceInput, WorkflowTaskWorkOptions, jsonValueSchema, parseWorkflowBinding, taskWork, taskWorkResultSchema, taskWorkSchema, workflowBindingSchema } from "./schema/work.mjs";
+import { AgentRoute, AgentRouteInput, AgentRouteKey, AgentRouteRegistry, RouteTaskWorkOptions, RoutedTaskWork, agentRouteSchema, defineAgentRoutes, routeKey, routeTaskWork } from "./agent-routes.mjs";
+import { z } from "zod";
+//#region src/workflows.d.ts
+/** Generic `task@1` workflow accepting bounded JSON input and output. */
+declare const defaultTaskWorkflow: Readonly<WorkflowDefinition<z.ZodCustom<JsonValue, JsonValue>, z.ZodCustom<JsonValue, JsonValue>, "task", 1>>;
+/** Caller input accepted when defining one exact workflow contract. */
+interface WorkflowDefinitionInput<Input extends z.ZodType = z.ZodType, Output extends z.ZodType = z.ZodType, Id extends string = string, Version extends number = number> {
+  /** Stable lowercase workflow identifier persisted on every Task. */
+  readonly id: Id;
+  /** Positive exact version; callers and recovery never select an implicit latest version. */
+  readonly version: Version;
+  /** Schema that validates caller input and supplies its static input type. */
+  readonly input: Input;
+  /** Schema that validates successful completion and supplies its static output type. */
+  readonly output: Output;
+  /**
+   * Canonical persisted-input schema required when `input` transforms its value. It must validate
+   * without changing the stored JSON shape.
+   */
+  readonly storedInput?: z.ZodType<NoInfer<z.output<Input>>>;
+  /**
+   * Canonical persisted-output schema required when `output` transforms its value. It must
+   * validate without changing the stored JSON shape.
+   */
+  readonly storedOutput?: z.ZodType<NoInfer<z.output<Output>>>;
+}
+/** Exact-version workflow contract with a typed binding for constructing work. */
+interface WorkflowDefinition<Input extends z.ZodType = z.ZodType, Output extends z.ZodType = z.ZodType, Id extends string = string, Version extends number = number> extends WorkflowDefinitionInput<Input, Output, Id, Version>, WorkflowReference<Input, WorkflowBinding<z.input<Input> & JsonValue, z.input<Output> & JsonValue, Id, Version>> {}
+/** JSON input accepted by a workflow definition before its schema transforms it. */
+type WorkflowInput<Definition extends WorkflowDefinition> = z.input<Definition["input"]> & JsonValue;
+/** JSON output accepted by a workflow definition before its schema transforms it. */
+type WorkflowOutput<Definition extends WorkflowDefinition> = z.input<Definition["output"]> & JsonValue;
+type RegisteredWorkflow<Definition extends WorkflowDefinitionInput> = Definition extends WorkflowDefinitionInput<infer Input, infer Output, infer Id, infer Version> ? WorkflowDefinition<Input, Output, Id, Version> : never;
+type WorkflowForBinding<Definition extends WorkflowDefinition, Binding extends WorkflowBinding> = Definition extends WorkflowDefinition ? Binding extends {
+  readonly id: Definition["id"];
+  readonly version: Definition["version"];
+} ? Definition : Definition extends {
+  readonly id: Binding["id"];
+  readonly version: Binding["version"];
+} ? Definition : never : never;
+/** Immutable registry that validates data against exact workflow versions. */
+interface WorkflowRegistry<Definition extends WorkflowDefinition = WorkflowDefinition> {
+  /** Immutable exact-version definitions in registration order. */
+  readonly definitions: readonly Readonly<Definition>[];
+  /**
+   * Resolves one exact binding, throwing with the registered alternatives when it is unknown.
+   *
+   * @param binding - Exact workflow ID and version.
+   * @returns The matching immutable workflow definition.
+   */
+  resolve<const Binding extends WorkflowBinding>(binding: Binding): Readonly<WorkflowForBinding<Definition, Binding>>;
+  /**
+   * Validates caller input through the selected workflow and returns bounded canonical JSON.
+   *
+   * @param binding - Exact workflow ID and version.
+   * @param value - Untrusted caller input to validate and transform.
+   * @returns Validated bounded JSON produced by the input schema.
+   */
+  validateInput(binding: WorkflowBinding, value: unknown): JsonValue;
+  /**
+   * Validates candidate completion output through the selected workflow.
+   *
+   * @param binding - Exact workflow ID and version.
+   * @param value - Untrusted candidate output to validate and transform.
+   * @returns Validated bounded JSON produced by the output schema.
+   */
+  validateOutput(binding: WorkflowBinding, value: unknown): JsonValue;
+  /**
+   * Validates persisted input without permitting a schema transform to change its JSON shape.
+   *
+   * @param binding - Exact workflow ID and version stored on the Task.
+   * @param value - Canonical persisted JSON to validate.
+   * @returns A cloned validated value equal to the persisted JSON.
+   */
+  validateStoredInput(binding: WorkflowBinding, value: unknown): JsonValue;
+  /**
+   * Validates persisted output without permitting a schema transform to change its JSON shape.
+   *
+   * @param binding - Exact workflow ID and version stored on the Task.
+   * @param value - Canonical persisted JSON to validate.
+   * @returns A cloned validated value equal to the persisted JSON.
+   */
+  validateStoredOutput(binding: WorkflowBinding, value: unknown): JsonValue;
+}
+/**
+ * Validates and freezes one exact workflow definition without executing it.
+ *
+ * @remarks
+ * A definition is a typed contract, not a registered runtime. Pass every definition that stored
+ * Tasks may reference to `defineWorkflows`, then supply that registry to `createStores`. Input and
+ * output schemas may transform caller values only when `storedInput` or `storedOutput` describes
+ * the unchanged canonical JSON representation used after persistence.
+ *
+ * @param definition - Stable ID, positive version, and Zod input/output contracts.
+ * @returns An immutable definition whose binding carries the input and output types.
+ * @throws When the binding is invalid or the input/output fields are not Zod schemas.
+ * @see The shipped `docs/recipes/custom-workflow.md` recipe for registration and completion.
+ *
+ * @example
+ * ```ts
+ * import { defineWorkflow, defineWorkflows } from "@vercel/factory/workflows";
+ * import { z } from "zod";
+ *
+ * const greeting = defineWorkflow({
+ *   id: "greeting",
+ *   version: 1,
+ *   input: z.object({ name: z.string() }),
+ *   output: z.object({ message: z.string() }),
+ * });
+ * const workflows = defineWorkflows([greeting]);
+ * ```
+ */
+declare function defineWorkflow<Input extends z.ZodType, Output extends z.ZodType, const Id extends string, const Version extends number>(definition: WorkflowDefinitionInput<Input, Output, Id, Version>): Readonly<WorkflowDefinition<Input, Output, Id, Version>>;
+/**
+ * Builds an immutable exact-version workflow registry and rejects duplicate definitions.
+ *
+ * @remarks
+ * Register old versions for as long as persisted Tasks can still reference them. Resolution uses
+ * both ID and version and never falls forward to another version. Creating a new registry has no
+ * persistence side effects.
+ *
+ * @param definitions - All exact workflow versions readable by this runtime.
+ * @returns A registry for resolving bindings and validating caller and persisted values.
+ * @throws When a definition is invalid or the same `id@version` appears more than once.
+ *
+ * @example
+ * ```ts
+ * import { defineWorkflow, defineWorkflows } from "@vercel/factory/workflows";
+ * import { z } from "zod";
+ *
+ * const v1 = defineWorkflow({
+ *   id: "report",
+ *   version: 1,
+ *   input: z.object({ topic: z.string() }),
+ *   output: z.object({ summary: z.string() }),
+ * });
+ * const workflows = defineWorkflows([v1]);
+ * workflows.resolve(v1.binding);
+ * ```
+ */
+declare function defineWorkflows<const Definition extends WorkflowDefinitionInput>(definitions: readonly Definition[]): WorkflowRegistry<RegisteredWorkflow<Definition>>;
+//#endregion
+export { type AgentRoute, type AgentRouteBinding, type AgentRouteBindingInput, type AgentRouteInput, type AgentRouteKey, type AgentRouteRegistry, type JsonValue, MAX_WORK_JSON_BYTES, MAX_WORK_JSON_DEPTH, type RouteTaskWorkOptions, type RoutedTaskWork, type TaskWork, type TaskWorkOptions, type TaskWorkResult, type WorkflowBinding, type WorkflowBindingInput, WorkflowDefinition, WorkflowDefinitionInput, WorkflowInput, WorkflowOutput, type WorkflowReference, type WorkflowReferenceInput, WorkflowRegistry, type WorkflowTaskWorkOptions, agentRouteBindingSchema, agentRouteSchema, defaultTaskWorkflow, defineAgentRoutes, defineWorkflow, defineWorkflows, jsonValueSchema, parseAgentRouteBinding, parseWorkflowBinding, routeKey, routeTaskWork, taskWork, taskWorkResultSchema, taskWorkSchema, workflowBindingSchema };
+//# sourceMappingURL=workflows.d.mts.map

package/dist/workflows.mjs

@@ -0,0 +1,139 @@
+import { agentRouteBindingSchema, parseAgentRouteBinding } from "./schema/agent-route.mjs";
+import { MAX_WORK_JSON_BYTES, MAX_WORK_JSON_DEPTH, jsonValueSchema, parseWorkflowBinding, taskWork, taskWorkResultSchema, taskWorkSchema, workflowBindingSchema } from "./schema/work.mjs";
+import { agentRouteSchema, defineAgentRoutes, routeKey, routeTaskWork } from "./agent-routes.mjs";
+import { z } from "zod";
+import { isDeepStrictEqual } from "node:util";
+//#region src/workflows.ts
+/** Generic `task@1` workflow accepting bounded JSON input and output. */
+const defaultTaskWorkflow = defineWorkflow({
+	id: "task",
+	version: 1,
+	input: jsonValueSchema,
+	output: jsonValueSchema
+});
+/**
+* Validates and freezes one exact workflow definition without executing it.
+*
+* @remarks
+* A definition is a typed contract, not a registered runtime. Pass every definition that stored
+* Tasks may reference to `defineWorkflows`, then supply that registry to `createStores`. Input and
+* output schemas may transform caller values only when `storedInput` or `storedOutput` describes
+* the unchanged canonical JSON representation used after persistence.
+*
+* @param definition - Stable ID, positive version, and Zod input/output contracts.
+* @returns An immutable definition whose binding carries the input and output types.
+* @throws When the binding is invalid or the input/output fields are not Zod schemas.
+* @see The shipped `docs/recipes/custom-workflow.md` recipe for registration and completion.
+*
+* @example
+* ```ts
+* import { defineWorkflow, defineWorkflows } from "@vercel/factory/workflows";
+* import { z } from "zod";
+*
+* const greeting = defineWorkflow({
+*   id: "greeting",
+*   version: 1,
+*   input: z.object({ name: z.string() }),
+*   output: z.object({ message: z.string() }),
+* });
+* const workflows = defineWorkflows([greeting]);
+* ```
+*/
+function defineWorkflow(definition) {
+	const parsedBinding = parseWorkflowBinding({
+		id: definition.id,
+		version: definition.version
+	});
+	if (!(definition.input instanceof z.ZodType) || !(definition.output instanceof z.ZodType)) throw new Error(`Workflow ${definition.id}@${definition.version} requires Zod input and output schemas`);
+	for (const field of ["storedInput", "storedOutput"]) if (definition[field] !== void 0 && !(definition[field] instanceof z.ZodType)) throw new Error(`Workflow ${definition.id}@${definition.version} requires a Zod ${field} schema`);
+	const binding = Object.freeze(parsedBinding);
+	return Object.freeze({
+		id: definition.id,
+		version: definition.version,
+		binding,
+		input: definition.input,
+		output: definition.output,
+		storedInput: definition.storedInput,
+		storedOutput: definition.storedOutput
+	});
+}
+/**
+* Builds an immutable exact-version workflow registry and rejects duplicate definitions.
+*
+* @remarks
+* Register old versions for as long as persisted Tasks can still reference them. Resolution uses
+* both ID and version and never falls forward to another version. Creating a new registry has no
+* persistence side effects.
+*
+* @param definitions - All exact workflow versions readable by this runtime.
+* @returns A registry for resolving bindings and validating caller and persisted values.
+* @throws When a definition is invalid or the same `id@version` appears more than once.
+*
+* @example
+* ```ts
+* import { defineWorkflow, defineWorkflows } from "@vercel/factory/workflows";
+* import { z } from "zod";
+*
+* const v1 = defineWorkflow({
+*   id: "report",
+*   version: 1,
+*   input: z.object({ topic: z.string() }),
+*   output: z.object({ summary: z.string() }),
+* });
+* const workflows = defineWorkflows([v1]);
+* workflows.resolve(v1.binding);
+* ```
+*/
+function defineWorkflows(definitions) {
+	const registered = definitions.map((definition) => defineWorkflow(definition));
+	const byBinding = /* @__PURE__ */ new Map();
+	for (const definition of registered) {
+		const key = `${definition.id}@${definition.version}`;
+		if (byBinding.has(key)) throw new Error(`Duplicate workflow definition ${key}; register each id and version exactly once`);
+		byBinding.set(key, definition);
+	}
+	function resolve(binding) {
+		const { id, version } = workflowBindingSchema.parse(binding);
+		const key = `${id}@${version}`;
+		const definition = byBinding.get(key);
+		if (!definition) {
+			const alternatives = [...byBinding.keys()].sort().join(", ") || "none";
+			throw new Error(`Unknown workflow ${key}. Registered workflows: ${alternatives}`);
+		}
+		return definition;
+	}
+	const validateStored = (binding, value, field) => {
+		const definition = resolve(binding);
+		const storedField = field === "input" ? "storedInput" : "storedOutput";
+		const storedSchema = definition[storedField];
+		const json = structuredClone(jsonValueSchema.parse(value));
+		let parsed;
+		try {
+			parsed = (storedSchema ?? definition[field]).parse(structuredClone(json));
+		} catch (cause) {
+			if (storedSchema !== void 0) throw cause;
+			throw new Error(`Workflow ${definition.id}@${definition.version} cannot validate stored ${field}; provide ${storedField} when the ${field} transform changes shape`, { cause });
+		}
+		const validated = jsonValueSchema.parse(parsed);
+		if (!isDeepStrictEqual(json, validated)) throw new Error(`Workflow ${definition.id}@${definition.version} stored ${field} validation must preserve canonical JSON; provide a non-transforming ${storedField} schema`);
+		return structuredClone(validated);
+	};
+	const validate = (binding, value, field) => {
+		const definition = resolve(binding);
+		const json = jsonValueSchema.parse(value);
+		const parsed = jsonValueSchema.parse(definition[field].parse(structuredClone(json)));
+		return validateStored(binding, parsed, field);
+	};
+	return Object.freeze({
+		definitions: Object.freeze(registered),
+		resolve,
+		validateInput: (binding, value) => validate(binding, value, "input"),
+		validateOutput: (binding, value) => validate(binding, value, "output"),
+		validateStoredInput: (binding, value) => validateStored(binding, value, "input"),
+		validateStoredOutput: (binding, value) => validateStored(binding, value, "output")
+	});
+}
+//#endregion
+export { MAX_WORK_JSON_BYTES, MAX_WORK_JSON_DEPTH, agentRouteBindingSchema, agentRouteSchema, defaultTaskWorkflow, defineAgentRoutes, defineWorkflow, defineWorkflows, jsonValueSchema, parseAgentRouteBinding, parseWorkflowBinding, routeKey, routeTaskWork, taskWork, taskWorkResultSchema, taskWorkSchema, workflowBindingSchema };
+
+//# sourceMappingURL=workflows.mjs.map

package/dist/workflows.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflows.mjs","names":[],"sources":["../src/workflows.ts"],"sourcesContent":["import { isDeepStrictEqual } from \"node:util\";\nimport { z } from \"zod\";\nimport {\n  jsonValueSchema,\n  parseWorkflowBinding,\n  workflowBindingSchema,\n  type JsonValue,\n  type WorkflowBinding,\n  type WorkflowReference,\n} from \"./schema/work\";\n\nexport {\n  jsonValueSchema,\n  MAX_WORK_JSON_BYTES,\n  MAX_WORK_JSON_DEPTH,\n  taskWork,\n  taskWorkResultSchema,\n  taskWorkSchema,\n  parseWorkflowBinding,\n  workflowBindingSchema,\n} from \"./schema/work\";\nexport {\n  agentRouteBindingSchema,\n  agentRouteSchema,\n  defineAgentRoutes,\n  parseAgentRouteBinding,\n  routeKey,\n  routeTaskWork,\n  type AgentRoute,\n  type AgentRouteBinding,\n  type AgentRouteBindingInput,\n  type AgentRouteInput,\n  type AgentRouteKey,\n  type AgentRouteRegistry,\n  type RouteTaskWorkOptions,\n  type RoutedTaskWork,\n} from \"./agent-routes\";\n\n/** Generic `task@1` workflow accepting bounded JSON input and output. */\nexport const defaultTaskWorkflow = defineWorkflow({\n  id: \"task\",\n  version: 1,\n  input: jsonValueSchema,\n  output: jsonValueSchema,\n});\nexport type {\n  JsonValue,\n  TaskWork,\n  TaskWorkOptions,\n  TaskWorkResult,\n  WorkflowBinding,\n  WorkflowBindingInput,\n  WorkflowReference,\n  WorkflowReferenceInput,\n  WorkflowTaskWorkOptions,\n} from \"./schema/work\";\n\n/** Caller input accepted when defining one exact workflow contract. */\nexport interface WorkflowDefinitionInput<\n  Input extends z.ZodType = z.ZodType,\n  Output extends z.ZodType = z.ZodType,\n  Id extends string = string,\n  Version extends number = number,\n> {\n  /** Stable lowercase workflow identifier persisted on every Task. */\n  readonly id: Id;\n  /** Positive exact version; callers and recovery never select an implicit latest version. */\n  readonly version: Version;\n  /** Schema that validates caller input and supplies its static input type. */\n  readonly input: Input;\n  /** Schema that validates successful completion and supplies its static output type. */\n  readonly output: Output;\n  /**\n   * Canonical persisted-input schema required when `input` transforms its value. It must validate\n   * without changing the stored JSON shape.\n   */\n  readonly storedInput?: z.ZodType<NoInfer<z.output<Input>>>;\n  /**\n   * Canonical persisted-output schema required when `output` transforms its value. It must\n   * validate without changing the stored JSON shape.\n   */\n  readonly storedOutput?: z.ZodType<NoInfer<z.output<Output>>>;\n}\n\n/** Exact-version workflow contract with a typed binding for constructing work. */\nexport interface WorkflowDefinition<\n  Input extends z.ZodType = z.ZodType,\n  Output extends z.ZodType = z.ZodType,\n  Id extends string = string,\n  Version extends number = number,\n>\n  extends\n    WorkflowDefinitionInput<Input, Output, Id, Version>,\n    WorkflowReference<\n      Input,\n      WorkflowBinding<z.input<Input> & JsonValue, z.input<Output> & JsonValue, Id, Version>\n    > {}\n\n/** JSON input accepted by a workflow definition before its schema transforms it. */\nexport type WorkflowInput<Definition extends WorkflowDefinition> = z.input<Definition[\"input\"]> &\n  JsonValue;\n\n/** JSON output accepted by a workflow definition before its schema transforms it. */\nexport type WorkflowOutput<Definition extends WorkflowDefinition> = z.input<Definition[\"output\"]> &\n  JsonValue;\n\ntype RegisteredWorkflow<Definition extends WorkflowDefinitionInput> =\n  Definition extends WorkflowDefinitionInput<infer Input, infer Output, infer Id, infer Version>\n    ? WorkflowDefinition<Input, Output, Id, Version>\n    : never;\n\ntype WorkflowForBinding<\n  Definition extends WorkflowDefinition,\n  Binding extends WorkflowBinding,\n> = Definition extends WorkflowDefinition\n  ? Binding extends {\n      readonly id: Definition[\"id\"];\n      readonly version: Definition[\"version\"];\n    }\n    ? Definition\n    : Definition extends {\n          readonly id: Binding[\"id\"];\n          readonly version: Binding[\"version\"];\n        }\n      ? Definition\n      : never\n  : never;\n\n/** Immutable registry that validates data against exact workflow versions. */\nexport interface WorkflowRegistry<Definition extends WorkflowDefinition = WorkflowDefinition> {\n  /** Immutable exact-version definitions in registration order. */\n  readonly definitions: readonly Readonly<Definition>[];\n  /**\n   * Resolves one exact binding, throwing with the registered alternatives when it is unknown.\n   *\n   * @param binding - Exact workflow ID and version.\n   * @returns The matching immutable workflow definition.\n   */\n  resolve<const Binding extends WorkflowBinding>(\n    binding: Binding,\n  ): Readonly<WorkflowForBinding<Definition, Binding>>;\n  /**\n   * Validates caller input through the selected workflow and returns bounded canonical JSON.\n   *\n   * @param binding - Exact workflow ID and version.\n   * @param value - Untrusted caller input to validate and transform.\n   * @returns Validated bounded JSON produced by the input schema.\n   */\n  validateInput(binding: WorkflowBinding, value: unknown): JsonValue;\n  /**\n   * Validates candidate completion output through the selected workflow.\n   *\n   * @param binding - Exact workflow ID and version.\n   * @param value - Untrusted candidate output to validate and transform.\n   * @returns Validated bounded JSON produced by the output schema.\n   */\n  validateOutput(binding: WorkflowBinding, value: unknown): JsonValue;\n  /**\n   * Validates persisted input without permitting a schema transform to change its JSON shape.\n   *\n   * @param binding - Exact workflow ID and version stored on the Task.\n   * @param value - Canonical persisted JSON to validate.\n   * @returns A cloned validated value equal to the persisted JSON.\n   */\n  validateStoredInput(binding: WorkflowBinding, value: unknown): JsonValue;\n  /**\n   * Validates persisted output without permitting a schema transform to change its JSON shape.\n   *\n   * @param binding - Exact workflow ID and version stored on the Task.\n   * @param value - Canonical persisted JSON to validate.\n   * @returns A cloned validated value equal to the persisted JSON.\n   */\n  validateStoredOutput(binding: WorkflowBinding, value: unknown): JsonValue;\n}\n\n/**\n * Validates and freezes one exact workflow definition without executing it.\n *\n * @remarks\n * A definition is a typed contract, not a registered runtime. Pass every definition that stored\n * Tasks may reference to `defineWorkflows`, then supply that registry to `createStores`. Input and\n * output schemas may transform caller values only when `storedInput` or `storedOutput` describes\n * the unchanged canonical JSON representation used after persistence.\n *\n * @param definition - Stable ID, positive version, and Zod input/output contracts.\n * @returns An immutable definition whose binding carries the input and output types.\n * @throws When the binding is invalid or the input/output fields are not Zod schemas.\n * @see The shipped `docs/recipes/custom-workflow.md` recipe for registration and completion.\n *\n * @example\n * ```ts\n * import { defineWorkflow, defineWorkflows } from \"@vercel/factory/workflows\";\n * import { z } from \"zod\";\n *\n * const greeting = defineWorkflow({\n *   id: \"greeting\",\n *   version: 1,\n *   input: z.object({ name: z.string() }),\n *   output: z.object({ message: z.string() }),\n * });\n * const workflows = defineWorkflows([greeting]);\n * ```\n */\nexport function defineWorkflow<\n  Input extends z.ZodType,\n  Output extends z.ZodType,\n  const Id extends string,\n  const Version extends number,\n>(\n  definition: WorkflowDefinitionInput<Input, Output, Id, Version>,\n): Readonly<WorkflowDefinition<Input, Output, Id, Version>> {\n  const parsedBinding = parseWorkflowBinding({\n    id: definition.id,\n    version: definition.version,\n  });\n  if (!(definition.input instanceof z.ZodType) || !(definition.output instanceof z.ZodType)) {\n    throw new Error(\n      `Workflow ${definition.id}@${definition.version} requires Zod input and output schemas`,\n    );\n  }\n  for (const field of [\"storedInput\", \"storedOutput\"] as const) {\n    if (definition[field] !== undefined && !(definition[field] instanceof z.ZodType)) {\n      throw new Error(\n        `Workflow ${definition.id}@${definition.version} requires a Zod ${field} schema`,\n      );\n    }\n  }\n  const binding: WorkflowBinding<\n    z.input<Input> & JsonValue,\n    z.input<Output> & JsonValue,\n    Id,\n    Version\n  > = Object.freeze(parsedBinding) as WorkflowBinding<\n    z.input<Input> & JsonValue,\n    z.input<Output> & JsonValue,\n    Id,\n    Version\n  >;\n  return Object.freeze({\n    id: definition.id,\n    version: definition.version,\n    binding,\n    input: definition.input,\n    output: definition.output,\n    storedInput: definition.storedInput,\n    storedOutput: definition.storedOutput,\n  });\n}\n\n/**\n * Builds an immutable exact-version workflow registry and rejects duplicate definitions.\n *\n * @remarks\n * Register old versions for as long as persisted Tasks can still reference them. Resolution uses\n * both ID and version and never falls forward to another version. Creating a new registry has no\n * persistence side effects.\n *\n * @param definitions - All exact workflow versions readable by this runtime.\n * @returns A registry for resolving bindings and validating caller and persisted values.\n * @throws When a definition is invalid or the same `id@version` appears more than once.\n *\n * @example\n * ```ts\n * import { defineWorkflow, defineWorkflows } from \"@vercel/factory/workflows\";\n * import { z } from \"zod\";\n *\n * const v1 = defineWorkflow({\n *   id: \"report\",\n *   version: 1,\n *   input: z.object({ topic: z.string() }),\n *   output: z.object({ summary: z.string() }),\n * });\n * const workflows = defineWorkflows([v1]);\n * workflows.resolve(v1.binding);\n * ```\n */\nexport function defineWorkflows<const Definition extends WorkflowDefinitionInput>(\n  definitions: readonly Definition[],\n): WorkflowRegistry<RegisteredWorkflow<Definition>> {\n  const registered = definitions.map((definition) =>\n    defineWorkflow(definition),\n  ) as unknown as readonly Readonly<RegisteredWorkflow<Definition>>[];\n  const byBinding = new Map<string, Readonly<RegisteredWorkflow<Definition>>>();\n  for (const definition of registered) {\n    const key = `${definition.id}@${definition.version}`;\n    if (byBinding.has(key)) {\n      throw new Error(\n        `Duplicate workflow definition ${key}; register each id and version exactly once`,\n      );\n    }\n    byBinding.set(key, definition);\n  }\n\n  function resolve<const Binding extends WorkflowBinding>(\n    binding: Binding,\n  ): Readonly<WorkflowForBinding<RegisteredWorkflow<Definition>, Binding>>;\n  function resolve(binding: WorkflowBinding): Readonly<RegisteredWorkflow<Definition>> {\n    const { id, version } = workflowBindingSchema.parse(binding);\n    const key = `${id}@${version}`;\n    const definition = byBinding.get(key);\n    if (!definition) {\n      const alternatives = [...byBinding.keys()].sort().join(\", \") || \"none\";\n      throw new Error(`Unknown workflow ${key}. Registered workflows: ${alternatives}`);\n    }\n    return definition;\n  }\n  const validateStored = (\n    binding: WorkflowBinding,\n    value: unknown,\n    field: \"input\" | \"output\",\n  ): JsonValue => {\n    const definition = resolve(binding);\n    const storedField = field === \"input\" ? \"storedInput\" : \"storedOutput\";\n    const storedSchema = definition[storedField];\n    const json = structuredClone(jsonValueSchema.parse(value));\n    let parsed: unknown;\n    try {\n      parsed = (storedSchema ?? definition[field]).parse(structuredClone(json));\n    } catch (cause) {\n      if (storedSchema !== undefined) throw cause;\n      throw new Error(\n        `Workflow ${definition.id}@${definition.version} cannot validate stored ${field}; provide ${storedField} when the ${field} transform changes shape`,\n        { cause },\n      );\n    }\n    const validated = jsonValueSchema.parse(parsed);\n    if (!isDeepStrictEqual(json, validated)) {\n      throw new Error(\n        `Workflow ${definition.id}@${definition.version} stored ${field} validation must preserve canonical JSON; provide a non-transforming ${storedField} schema`,\n      );\n    }\n    return structuredClone(validated);\n  };\n  const validate = (\n    binding: WorkflowBinding,\n    value: unknown,\n    field: \"input\" | \"output\",\n  ): JsonValue => {\n    const definition = resolve(binding);\n    const json = jsonValueSchema.parse(value);\n    const parsed = jsonValueSchema.parse(definition[field].parse(structuredClone(json)));\n    return validateStored(binding, parsed, field);\n  };\n\n  return Object.freeze({\n    definitions: Object.freeze(registered),\n    resolve,\n    validateInput: (binding: WorkflowBinding, value: unknown) => validate(binding, value, \"input\"),\n    validateOutput: (binding: WorkflowBinding, value: unknown) =>\n      validate(binding, value, \"output\"),\n    validateStoredInput: (binding: WorkflowBinding, value: unknown) =>\n      validateStored(binding, value, \"input\"),\n    validateStoredOutput: (binding: WorkflowBinding, value: unknown) =>\n      validateStored(binding, value, \"output\"),\n  });\n}\n"],"mappings":";;;;;;;AAuCA,MAAa,sBAAsB,eAAe;CAChD,IAAI;CACJ,SAAS;CACT,OAAO;CACP,QAAQ;AACV,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+JD,SAAgB,eAMd,YAC0D;CAC1D,MAAM,gBAAgB,qBAAqB;EACzC,IAAI,WAAW;EACf,SAAS,WAAW;CACtB,CAAC;CACD,IAAI,EAAE,WAAW,iBAAiB,EAAE,YAAY,EAAE,WAAW,kBAAkB,EAAE,UAC/E,MAAM,IAAI,MACR,YAAY,WAAW,GAAG,GAAG,WAAW,QAAQ,uCAClD;CAEF,KAAK,MAAM,SAAS,CAAC,eAAe,cAAc,GAChD,IAAI,WAAW,WAAW,KAAA,KAAa,EAAE,WAAW,kBAAkB,EAAE,UACtE,MAAM,IAAI,MACR,YAAY,WAAW,GAAG,GAAG,WAAW,QAAQ,kBAAkB,MAAM,QAC1E;CAGJ,MAAM,UAKF,OAAO,OAAO,aAAa;CAM/B,OAAO,OAAO,OAAO;EACnB,IAAI,WAAW;EACf,SAAS,WAAW;EACpB;EACA,OAAO,WAAW;EAClB,QAAQ,WAAW;EACnB,aAAa,WAAW;EACxB,cAAc,WAAW;CAC3B,CAAC;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,SAAgB,gBACd,aACkD;CAClD,MAAM,aAAa,YAAY,KAAK,eAClC,eAAe,UAAU,CAC3B;CACA,MAAM,4BAAY,IAAI,IAAsD;CAC5E,KAAK,MAAM,cAAc,YAAY;EACnC,MAAM,MAAM,GAAG,WAAW,GAAG,GAAG,WAAW;EAC3C,IAAI,UAAU,IAAI,GAAG,GACnB,MAAM,IAAI,MACR,iCAAiC,IAAI,4CACvC;EAEF,UAAU,IAAI,KAAK,UAAU;CAC/B;CAKA,SAAS,QAAQ,SAAoE;EACnF,MAAM,EAAE,IAAI,YAAY,sBAAsB,MAAM,OAAO;EAC3D,MAAM,MAAM,GAAG,GAAG,GAAG;EACrB,MAAM,aAAa,UAAU,IAAI,GAAG;EACpC,IAAI,CAAC,YAAY;GACf,MAAM,eAAe,CAAC,GAAG,UAAU,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,IAAI,KAAK;GAChE,MAAM,IAAI,MAAM,oBAAoB,IAAI,0BAA0B,cAAc;EAClF;EACA,OAAO;CACT;CACA,MAAM,kBACJ,SACA,OACA,UACc;EACd,MAAM,aAAa,QAAQ,OAAO;EAClC,MAAM,cAAc,UAAU,UAAU,gBAAgB;EACxD,MAAM,eAAe,WAAW;EAChC,MAAM,OAAO,gBAAgB,gBAAgB,MAAM,KAAK,CAAC;EACzD,IAAI;EACJ,IAAI;GACF,UAAU,gBAAgB,WAAW,OAAA,CAAQ,MAAM,gBAAgB,IAAI,CAAC;EAC1E,SAAS,OAAO;GACd,IAAI,iBAAiB,KAAA,GAAW,MAAM;GACtC,MAAM,IAAI,MACR,YAAY,WAAW,GAAG,GAAG,WAAW,QAAQ,0BAA0B,MAAM,YAAY,YAAY,YAAY,MAAM,2BAC1H,EAAE,MAAM,CACV;EACF;EACA,MAAM,YAAY,gBAAgB,MAAM,MAAM;EAC9C,IAAI,CAAC,kBAAkB,MAAM,SAAS,GACpC,MAAM,IAAI,MACR,YAAY,WAAW,GAAG,GAAG,WAAW,QAAQ,UAAU,MAAM,uEAAuE,YAAY,QACrJ;EAEF,OAAO,gBAAgB,SAAS;CAClC;CACA,MAAM,YACJ,SACA,OACA,UACc;EACd,MAAM,aAAa,QAAQ,OAAO;EAClC,MAAM,OAAO,gBAAgB,MAAM,KAAK;EACxC,MAAM,SAAS,gBAAgB,MAAM,WAAW,MAAM,CAAC,MAAM,gBAAgB,IAAI,CAAC,CAAC;EACnF,OAAO,eAAe,SAAS,QAAQ,KAAK;CAC9C;CAEA,OAAO,OAAO,OAAO;EACnB,aAAa,OAAO,OAAO,UAAU;EACrC;EACA,gBAAgB,SAA0B,UAAmB,SAAS,SAAS,OAAO,OAAO;EAC7F,iBAAiB,SAA0B,UACzC,SAAS,SAAS,OAAO,QAAQ;EACnC,sBAAsB,SAA0B,UAC9C,eAAe,SAAS,OAAO,OAAO;EACxC,uBAAuB,SAA0B,UAC/C,eAAe,SAAS,OAAO,QAAQ;CAC3C,CAAC;AACH"}

package/dist/workspace-diff-assembly.d.mts

@@ -0,0 +1,33 @@
+import { WorkspaceDiff } from "./workspace-diff.mjs";
+import { WorkspaceSnapshot } from "./workspace-snapshot.mjs";
+//#region src/workspace-diff-assembly.d.ts
+/** Metadata for one file in the pinned comparison base tree. */
+interface WorkspaceBaseEntry {
+  readonly sha: string;
+  readonly size: number;
+}
+/** Encoded contents and metadata for one pinned base-tree blob. */
+interface WorkspaceBaseBlob {
+  readonly content: string;
+  readonly encoding: string;
+  readonly size: number | null;
+}
+/** Pinned inputs and display limits used to assemble a workspace diff. */
+interface WorkspaceDiffAssemblyOptions {
+  readonly executionId: string;
+  readonly baseSha: string;
+  readonly headSha: string;
+  readonly capturedAt: string;
+  readonly snapshot: WorkspaceSnapshot;
+  readonly baseEntries: readonly WorkspaceBaseEntry[];
+  readonly readBaseBlob: (sha: string) => Promise<WorkspaceBaseBlob>;
+  readonly signal?: AbortSignal;
+  readonly maxBlobBytes?: number;
+  readonly maxPatchBytes?: number;
+  readonly maxTotalPatchBytes?: number;
+}
+/** Assemble bounded unified patches from a sandbox snapshot and pinned base blobs. */
+declare function assembleWorkspaceDiff(options: WorkspaceDiffAssemblyOptions): Promise<WorkspaceDiff>;
+//#endregion
+export { WorkspaceBaseBlob, WorkspaceBaseEntry, WorkspaceDiffAssemblyOptions, assembleWorkspaceDiff };
+//# sourceMappingURL=workspace-diff-assembly.d.mts.map

package/dist/workspace-diff-assembly.mjs

@@ -0,0 +1,95 @@
+import { workspaceDiffSchema } from "./workspace-diff.mjs";
+import { workspaceSnapshotSchema } from "./workspace-snapshot.mjs";
+import { Buffer } from "node:buffer";
+import { formatPatch, structuredPatch } from "diff";
+//#region src/workspace-diff-assembly.ts
+/** Assemble bounded unified patches from a sandbox snapshot and pinned base blobs. */
+async function assembleWorkspaceDiff(options) {
+	const snapshot = workspaceSnapshotSchema.parse(options.snapshot);
+	const maxBlobBytes = options.maxBlobBytes ?? 2e5;
+	const maxPatchBytes = options.maxPatchBytes ?? 1e5;
+	const maxTotalPatchBytes = options.maxTotalPatchBytes ?? 2e6;
+	const sizes = new Map(options.baseEntries.map((entry) => [entry.sha, entry.size]));
+	const renamed = /* @__PURE__ */ new Set();
+	const renames = /* @__PURE__ */ new Map();
+	for (const added of snapshot.files.filter((file) => file.oldMode === null && file.newSha !== null)) {
+		const previous = snapshot.files.find((file) => file.newMode === null && file.oldSha === added.newSha && !renamed.has(file.path));
+		if (previous) {
+			renames.set(added.path, previous);
+			renamed.add(previous.path);
+		}
+	}
+	const files = [];
+	let patchBytes = 0;
+	for (const file of snapshot.files) {
+		options.signal?.throwIfAborted();
+		if (renamed.has(file.path)) continue;
+		const rename = renames.get(file.path);
+		const oldSha = rename?.oldSha ?? file.oldSha;
+		const oldMode = rename?.oldMode ?? file.oldMode;
+		let binary = file.binary;
+		let omitted = file.omitted || (sizes.get(oldSha ?? "") ?? 0) > maxBlobBytes || oldMode === "160000" || file.newMode === "160000";
+		let before = "";
+		if (oldSha && !binary && !omitted && !rename) {
+			const blob = await options.readBaseBlob(oldSha);
+			if (blob.size === null || blob.size > maxBlobBytes || blob.encoding !== "base64") omitted = true;
+			else {
+				const bytes = Buffer.from(blob.content, "base64");
+				binary = bytes.includes(0);
+				if (!binary) try {
+					before = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+				} catch {
+					binary = true;
+				}
+			}
+		}
+		let patch = "";
+		let additions = null;
+		let deletions = null;
+		if (!binary && !omitted) {
+			if (rename) before = file.content ?? "";
+			const diff = structuredPatch(rename?.path ?? file.path, file.path, before, file.content ?? "", void 0, void 0, {
+				context: 3,
+				timeout: 100,
+				maxEditLength: 2e4
+			});
+			if (!diff) omitted = true;
+			else {
+				patch = diff.hunks.length ? formatPatch(diff) : "";
+				if (patch.length > maxPatchBytes || patchBytes + Buffer.byteLength(patch) > maxTotalPatchBytes) {
+					patch = "";
+					omitted = true;
+				} else {
+					patchBytes += Buffer.byteLength(patch);
+					additions = diff.hunks.reduce((sum, hunk) => sum + hunk.lines.filter((line) => line.startsWith("+")).length, 0);
+					deletions = diff.hunks.reduce((sum, hunk) => sum + hunk.lines.filter((line) => line.startsWith("-")).length, 0);
+				}
+			}
+		}
+		files.push({
+			path: file.path,
+			...rename ? { previousPath: rename.path } : {},
+			status: rename ? "renamed" : oldMode === null ? "added" : file.newMode === null ? "deleted" : "modified",
+			oldMode,
+			newMode: file.newMode,
+			additions,
+			deletions,
+			patch,
+			binary,
+			omitted
+		});
+	}
+	return workspaceDiffSchema.parse({
+		executionId: options.executionId,
+		state: "ready",
+		base: { sha: options.baseSha },
+		head: { sha: options.headSha },
+		capturedAt: options.capturedAt,
+		files,
+		truncated: snapshot.truncated || files.some((file) => file.omitted)
+	});
+}
+//#endregion
+export { assembleWorkspaceDiff };
+
+//# sourceMappingURL=workspace-diff-assembly.mjs.map

package/dist/workspace-diff-assembly.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-diff-assembly.mjs","names":[],"sources":["../src/workspace-diff-assembly.ts"],"sourcesContent":["import { Buffer } from \"node:buffer\";\nimport { formatPatch, structuredPatch } from \"diff\";\nimport { workspaceDiffSchema, type WorkspaceDiff, type WorkspaceDiffFile } from \"./workspace-diff\";\nimport { workspaceSnapshotSchema, type WorkspaceSnapshot } from \"./workspace-snapshot\";\n\n/** Metadata for one file in the pinned comparison base tree. */\nexport interface WorkspaceBaseEntry {\n  readonly sha: string;\n  readonly size: number;\n}\n\n/** Encoded contents and metadata for one pinned base-tree blob. */\nexport interface WorkspaceBaseBlob {\n  readonly content: string;\n  readonly encoding: string;\n  readonly size: number | null;\n}\n\n/** Pinned inputs and display limits used to assemble a workspace diff. */\nexport interface WorkspaceDiffAssemblyOptions {\n  readonly executionId: string;\n  readonly baseSha: string;\n  readonly headSha: string;\n  readonly capturedAt: string;\n  readonly snapshot: WorkspaceSnapshot;\n  readonly baseEntries: readonly WorkspaceBaseEntry[];\n  readonly readBaseBlob: (sha: string) => Promise<WorkspaceBaseBlob>;\n  readonly signal?: AbortSignal;\n  readonly maxBlobBytes?: number;\n  readonly maxPatchBytes?: number;\n  readonly maxTotalPatchBytes?: number;\n}\n\n/** Assemble bounded unified patches from a sandbox snapshot and pinned base blobs. */\nexport async function assembleWorkspaceDiff(\n  options: WorkspaceDiffAssemblyOptions,\n): Promise<WorkspaceDiff> {\n  const snapshot = workspaceSnapshotSchema.parse(options.snapshot);\n  const maxBlobBytes = options.maxBlobBytes ?? 200_000;\n  const maxPatchBytes = options.maxPatchBytes ?? 100_000;\n  const maxTotalPatchBytes = options.maxTotalPatchBytes ?? 2_000_000;\n  const sizes = new Map(options.baseEntries.map((entry) => [entry.sha, entry.size]));\n  const renamed = new Set<string>();\n  const renames = new Map<string, (typeof snapshot.files)[number]>();\n  for (const added of snapshot.files.filter(\n    (file) => file.oldMode === null && file.newSha !== null,\n  )) {\n    const previous = snapshot.files.find(\n      (file) => file.newMode === null && file.oldSha === added.newSha && !renamed.has(file.path),\n    );\n    if (previous) {\n      renames.set(added.path, previous);\n      renamed.add(previous.path);\n    }\n  }\n\n  const files: WorkspaceDiffFile[] = [];\n  let patchBytes = 0;\n  for (const file of snapshot.files) {\n    options.signal?.throwIfAborted();\n    if (renamed.has(file.path)) continue;\n    const rename = renames.get(file.path);\n    const oldSha = rename?.oldSha ?? file.oldSha;\n    const oldMode = rename?.oldMode ?? file.oldMode;\n    let binary = file.binary;\n    let omitted =\n      file.omitted ||\n      (sizes.get(oldSha ?? \"\") ?? 0) > maxBlobBytes ||\n      oldMode === \"160000\" ||\n      file.newMode === \"160000\";\n    let before = \"\";\n    if (oldSha && !binary && !omitted && !rename) {\n      const blob = await options.readBaseBlob(oldSha);\n      if (blob.size === null || blob.size > maxBlobBytes || blob.encoding !== \"base64\") {\n        omitted = true;\n      } else {\n        const bytes = Buffer.from(blob.content, \"base64\");\n        binary = bytes.includes(0);\n        if (!binary) {\n          try {\n            before = new TextDecoder(\"utf-8\", { fatal: true }).decode(bytes);\n          } catch {\n            binary = true;\n          }\n        }\n      }\n    }\n    let patch = \"\";\n    let additions: number | null = null;\n    let deletions: number | null = null;\n    if (!binary && !omitted) {\n      if (rename) before = file.content ?? \"\";\n      const diff = structuredPatch(\n        rename?.path ?? file.path,\n        file.path,\n        before,\n        file.content ?? \"\",\n        undefined,\n        undefined,\n        { context: 3, timeout: 100, maxEditLength: 20_000 },\n      );\n      if (!diff) {\n        omitted = true;\n      } else {\n        patch = diff.hunks.length ? formatPatch(diff) : \"\";\n        if (\n          patch.length > maxPatchBytes ||\n          patchBytes + Buffer.byteLength(patch) > maxTotalPatchBytes\n        ) {\n          patch = \"\";\n          omitted = true;\n        } else {\n          patchBytes += Buffer.byteLength(patch);\n          additions = diff.hunks.reduce(\n            (sum, hunk) => sum + hunk.lines.filter((line) => line.startsWith(\"+\")).length,\n            0,\n          );\n          deletions = diff.hunks.reduce(\n            (sum, hunk) => sum + hunk.lines.filter((line) => line.startsWith(\"-\")).length,\n            0,\n          );\n        }\n      }\n    }\n    files.push({\n      path: file.path,\n      ...(rename ? { previousPath: rename.path } : {}),\n      status: rename\n        ? \"renamed\"\n        : oldMode === null\n          ? \"added\"\n          : file.newMode === null\n            ? \"deleted\"\n            : \"modified\",\n      oldMode,\n      newMode: file.newMode,\n      additions,\n      deletions,\n      patch,\n      binary,\n      omitted,\n    });\n  }\n  return workspaceDiffSchema.parse({\n    executionId: options.executionId,\n    state: \"ready\",\n    base: { sha: options.baseSha },\n    head: { sha: options.headSha },\n    capturedAt: options.capturedAt,\n    files,\n    truncated: snapshot.truncated || files.some((file) => file.omitted),\n  });\n}\n"],"mappings":"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"}