@vercel/factory 0.0.14 → 0.0.16

package/dist/changes/eve-record-change.d.mts

@@ -0,0 +1,56 @@
+import { Task } from "../schema/task.mjs";
+import { Change } from "../schema/change.mjs";
+import { FactoryStores } from "../store/engine.mjs";
+import { ChangePresenter } from "./presentation.mjs";
+import { PullRequestPublicationGateResult } from "../pull-requests/contracts.mjs";
+import { z } from "zod";
+import { ToolContext, ToolDefinition } from "eve/tools";
+//#region src/changes/eve-record-change.d.ts
+/** Change and Task capabilities required by the record-change tool. */
+type RecordChangeToolStores = Pick<FactoryStores, "changes" | "tasks">;
+declare const recordChangeInputSchema: z.ZodObject<{
+  taskId: z.ZodType<`task_${string}`, string, z.core.$ZodTypeInternals<`task_${string}`, string>>;
+  repositoryId: z.ZodType<`repo_${string}`, string, z.core.$ZodTypeInternals<`repo_${string}`, string>>;
+  prNumber: z.ZodNumber;
+  prUrl: z.ZodURL;
+  risk: z.ZodEnum<{
+    low: "low";
+    medium: "medium";
+    high: "high";
+  }>;
+  confidence: z.ZodEnum<{
+    low: "low";
+    medium: "medium";
+    high: "high";
+  }>;
+  summary: z.ZodString;
+}, z.core.$strip>;
+/** Validated input accepted by the tool that links a pull request to its producing Task. */
+type RecordChangeInput = z.infer<typeof recordChangeInputSchema>;
+/** Configures policy gates and durable presentation for the software record-change tool. */
+interface RecordChangeToolOptions {
+  /**
+   * PR association gate, run as an Eve approval policy and again after
+   * authentication before recording. Refusals include the gate's reason.
+   * Gates must fail closed: when they cannot verify, they refuse.
+   */
+  recordChangeGate?: (input: RecordChangeInput) => Promise<PullRequestPublicationGateResult>;
+  /** Whether recorded code changes wait for an independent verification task. Default: required. */
+  verification?: "required" | "disabled";
+  /** Present the pull request after record_change persists its durable state. */
+  presentChange?: ChangePresenter;
+}
+/** Change and producing Task returned after a pull request is recorded. */
+interface RecordChangeResult {
+  readonly change: Change;
+  readonly task: Task;
+}
+/** Eve outcome tool that links a pull request to its producing Task. */
+interface RecordChangeTool extends ToolDefinition<RecordChangeInput, RecordChangeResult> {
+  execute(input: RecordChangeInput, ctx: ToolContext): Promise<RecordChangeResult>;
+}
+/** Create the supplied software workflow's pull-request outcome tool. */
+declare function createRecordChangeTool(stores: RecordChangeToolStores, options?: RecordChangeToolOptions): RecordChangeTool;
+//#endregion
+export { RecordChangeInput, RecordChangeResult, RecordChangeTool, RecordChangeToolOptions, RecordChangeToolStores, createRecordChangeTool };
+//# sourceMappingURL=eve-record-change.d.mts.map

package/dist/changes/eve-record-change.mjs

@@ -0,0 +1,131 @@
+import { repositoryIdSchema, taskIdSchema } from "../schema/id.mjs";
+import { requireTaskExecution, requireTaskExecutionIdentity } from "../eve/task-execution.mjs";
+import { changeLevelSchema } from "../schema/change.mjs";
+import { z } from "zod";
+import { defineTool } from "eve/tools";
+//#region src/changes/eve-record-change.ts
+const recordChangeInputSchema = z.object({
+	taskId: taskIdSchema,
+	repositoryId: repositoryIdSchema,
+	prNumber: z.number().int().min(1),
+	prUrl: z.url(),
+	risk: changeLevelSchema.describe("Blast radius of the change if it is wrong."),
+	confidence: changeLevelSchema.describe("How certain you are the change is correct."),
+	summary: z.string().min(1).describe("One-sentence description of the change.")
+});
+/** Create the supplied software workflow's pull-request outcome tool. */
+function createRecordChangeTool(stores, options = {}) {
+	const recordChangeGate = options.recordChangeGate;
+	const verification = options.verification ?? "required";
+	return defineTool({
+		description: verification === "required" ? "Record the pull request produced for a code_change task. Creates the change, links it to the task, and moves the task to verifying." : "Record the pull request produced for a code_change task. Creates the change and marks it ready for human review without independent verification.",
+		inputSchema: recordChangeInputSchema,
+		...recordChangeGate === void 0 ? {} : { approval: async ({ toolInput }) => {
+			const parsed = recordChangeInputSchema.safeParse(toolInput);
+			if (!parsed.success) return {
+				type: "denied",
+				reason: "record_change input is malformed; fix the arguments and retry"
+			};
+			const verdict = await recordChangeGate(parsed.data);
+			return verdict.ok ? "not-applicable" : {
+				type: "denied",
+				reason: verdict.reason
+			};
+		} },
+		async execute({ taskId, repositoryId, prNumber, prUrl, risk, confidence, summary }, ctx) {
+			const currentTask = await requireTaskExecutionIdentity(stores, ctx, taskId);
+			if (currentTask.state !== "running" && currentTask.state !== "verifying" && currentTask.state !== "succeeded") throw new Error(`task ${taskId} is ${currentTask.state}, not running`);
+			if (currentTask.repositoryIds.length !== 1 || currentTask.repositoryIds[0] !== repositoryId) throw new Error("Repository does not match the authenticated Task");
+			if (currentTask.state !== "running" && currentTask.changeId === void 0) throw new Error(`task ${taskId} has no recorded change`);
+			const linkedChange = currentTask.changeId === void 0 ? void 0 : await stores.changes.get(currentTask.changeId);
+			if (currentTask.changeId !== void 0 && linkedChange === null) throw new Error(`change ${currentTask.changeId} does not exist`);
+			let change = linkedChange ?? (await stores.changes.list()).find((candidate) => candidate.taskId === taskId);
+			if (change !== void 0 && (change.repositoryId !== repositoryId || change.prNumber !== prNumber || change.prUrl !== prUrl)) throw new Error("Pull request does not match the Task's recorded Change");
+			if (currentTask.state === "running") {
+				await requireTaskExecution(stores, ctx, taskId);
+				if (recordChangeGate !== void 0) {
+					const verdict = await recordChangeGate({
+						taskId,
+						repositoryId,
+						prNumber,
+						prUrl,
+						risk,
+						confidence,
+						summary
+					});
+					if (!verdict.ok) throw new Error(verdict.reason);
+				}
+				await requireTaskExecution(stores, ctx, taskId);
+			}
+			if (change === void 0) {
+				if (currentTask.state !== "running") throw new Error(`task ${taskId} has no recorded change`);
+				change = await stores.changes.create({
+					repositoryId,
+					taskId,
+					prNumber,
+					prUrl,
+					author: "factory",
+					risk,
+					confidence,
+					evidence: {
+						reproVerified: false,
+						testsAdded: 0,
+						checksGreen: false,
+						attackPassed: false,
+						scopeMatches: false
+					}
+				});
+			}
+			if (change === void 0) throw new Error(`task ${taskId} has no recorded change`);
+			let recordedChange = change;
+			if (currentTask.state === "succeeded") return {
+				change: recordedChange,
+				task: currentTask
+			};
+			if (currentTask.state === "running") {
+				await requireTaskExecution(stores, ctx, taskId);
+				await options.presentChange?.({
+					taskId,
+					changeId: recordedChange.id,
+					verification,
+					summary
+				});
+			}
+			let task = currentTask;
+			if (task.state === "running") task = await stores.tasks.transition(taskId, "verifying", {
+				expectFrom: "running",
+				expectAttempt: currentTask.attempt,
+				expectExecution: currentTask.execution,
+				patch: { changeId: recordedChange.id },
+				reason: summary
+			});
+			if (verification === "required") return {
+				change: recordedChange,
+				task
+			};
+			const completion = await requireTaskExecutionIdentity(stores, ctx, taskId);
+			if (completion.state !== "verifying" || completion.changeId !== recordedChange.id) throw new Error("Task is no longer awaiting this Change's completion");
+			if (recordedChange.state === "verifying") recordedChange = await stores.changes.transition(recordedChange.id, "ready", { reason: "independent verification is not configured" });
+			if (task.state === "verifying") task = await stores.tasks.transition(taskId, "succeeded", {
+				expectFrom: "verifying",
+				expectAttempt: currentTask.attempt,
+				expectExecution: currentTask.execution,
+				reason: "change recorded for human review without independent verification",
+				output: {
+					changeId: recordedChange.id,
+					prUrl: recordedChange.prUrl,
+					summary,
+					verification
+				}
+			});
+			return {
+				change: recordedChange,
+				task
+			};
+		}
+	});
+}
+//#endregion
+export { createRecordChangeTool };
+
+//# sourceMappingURL=eve-record-change.mjs.map

package/dist/changes/eve-record-change.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"eve-record-change.mjs","names":[],"sources":["../../src/changes/eve-record-change.ts"],"sourcesContent":["import { defineTool, type ToolContext, type ToolDefinition } from \"eve/tools\";\nimport { z } from \"zod\";\nimport type { ChangePresenter } from \"./presentation\";\nimport { changeLevelSchema, type Change } from \"../schema/change\";\nimport { repositoryIdSchema, taskIdSchema } from \"../schema/id\";\nimport type { Task } from \"../schema/task\";\nimport type { PullRequestPublicationGateResult } from \"../pull-requests/contracts\";\nimport type { FactoryStores } from \"../store/engine\";\nimport { requireTaskExecution, requireTaskExecutionIdentity } from \"../eve/task-execution\";\n\n/** Change and Task capabilities required by the record-change tool. */\nexport type RecordChangeToolStores = Pick<FactoryStores, \"changes\" | \"tasks\">;\n\nconst recordChangeInputSchema = z.object({\n  taskId: taskIdSchema,\n  repositoryId: repositoryIdSchema,\n  prNumber: z.number().int().min(1),\n  prUrl: z.url(),\n  risk: changeLevelSchema.describe(\"Blast radius of the change if it is wrong.\"),\n  confidence: changeLevelSchema.describe(\"How certain you are the change is correct.\"),\n  summary: z.string().min(1).describe(\"One-sentence description of the change.\"),\n});\n\n/** Validated input accepted by the tool that links a pull request to its producing Task. */\nexport type RecordChangeInput = z.infer<typeof recordChangeInputSchema>;\n\n/** Configures policy gates and durable presentation for the software record-change tool. */\nexport interface RecordChangeToolOptions {\n  /**\n   * PR association gate, run as an Eve approval policy and again after\n   * authentication before recording. Refusals include the gate's reason.\n   * Gates must fail closed: when they cannot verify, they refuse.\n   */\n  recordChangeGate?: (input: RecordChangeInput) => Promise<PullRequestPublicationGateResult>;\n  /** Whether recorded code changes wait for an independent verification task. Default: required. */\n  verification?: \"required\" | \"disabled\";\n  /** Present the pull request after record_change persists its durable state. */\n  presentChange?: ChangePresenter;\n}\n\n/** Change and producing Task returned after a pull request is recorded. */\nexport interface RecordChangeResult {\n  readonly change: Change;\n  readonly task: Task;\n}\n\n/** Eve outcome tool that links a pull request to its producing Task. */\nexport interface RecordChangeTool extends ToolDefinition<RecordChangeInput, RecordChangeResult> {\n  execute(input: RecordChangeInput, ctx: ToolContext): Promise<RecordChangeResult>;\n}\n\n/** Create the supplied software workflow's pull-request outcome tool. */\nexport function createRecordChangeTool(\n  stores: RecordChangeToolStores,\n  options: RecordChangeToolOptions = {},\n): RecordChangeTool {\n  const recordChangeGate = options.recordChangeGate;\n  const verification = options.verification ?? \"required\";\n  return defineTool({\n    description:\n      verification === \"required\"\n        ? \"Record the pull request produced for a code_change task. Creates the change, links it to the task, and moves the task to verifying.\"\n        : \"Record the pull request produced for a code_change task. Creates the change and marks it ready for human review without independent verification.\",\n    inputSchema: recordChangeInputSchema,\n    ...(recordChangeGate === undefined\n      ? {}\n      : {\n          approval: async ({ toolInput }: { toolInput?: unknown }) => {\n            const parsed = recordChangeInputSchema.safeParse(toolInput);\n            if (!parsed.success) {\n              return {\n                type: \"denied\" as const,\n                reason: \"record_change input is malformed; fix the arguments and retry\",\n              };\n            }\n            const verdict = await recordChangeGate(parsed.data);\n            return verdict.ok\n              ? (\"not-applicable\" as const)\n              : { type: \"denied\" as const, reason: verdict.reason };\n          },\n        }),\n    async execute(\n      { taskId, repositoryId, prNumber, prUrl, risk, confidence, summary },\n      ctx,\n    ): Promise<RecordChangeResult> {\n      const currentTask = await requireTaskExecutionIdentity(stores, ctx, taskId);\n      if (\n        currentTask.state !== \"running\" &&\n        currentTask.state !== \"verifying\" &&\n        currentTask.state !== \"succeeded\"\n      ) {\n        throw new Error(`task ${taskId} is ${currentTask.state}, not running`);\n      }\n      if (currentTask.repositoryIds.length !== 1 || currentTask.repositoryIds[0] !== repositoryId) {\n        throw new Error(\"Repository does not match the authenticated Task\");\n      }\n      if (currentTask.state !== \"running\" && currentTask.changeId === undefined) {\n        throw new Error(`task ${taskId} has no recorded change`);\n      }\n      const linkedChange =\n        currentTask.changeId === undefined\n          ? undefined\n          : await stores.changes.get(currentTask.changeId);\n      if (currentTask.changeId !== undefined && linkedChange === null) {\n        throw new Error(`change ${currentTask.changeId} does not exist`);\n      }\n      let change =\n        linkedChange ??\n        (await stores.changes.list()).find((candidate) => candidate.taskId === taskId);\n\n      if (\n        change !== undefined &&\n        (change.repositoryId !== repositoryId ||\n          change.prNumber !== prNumber ||\n          change.prUrl !== prUrl)\n      ) {\n        throw new Error(\"Pull request does not match the Task's recorded Change\");\n      }\n      if (currentTask.state === \"running\") {\n        await requireTaskExecution(stores, ctx, taskId);\n        if (recordChangeGate !== undefined) {\n          const verdict = await recordChangeGate({\n            taskId,\n            repositoryId,\n            prNumber,\n            prUrl,\n            risk,\n            confidence,\n            summary,\n          });\n          if (!verdict.ok) throw new Error(verdict.reason);\n        }\n        await requireTaskExecution(stores, ctx, taskId);\n      }\n\n      if (change === undefined) {\n        if (currentTask.state !== \"running\") {\n          throw new Error(`task ${taskId} has no recorded change`);\n        }\n        change = await stores.changes.create({\n          repositoryId,\n          taskId,\n          prNumber,\n          prUrl,\n          author: \"factory\",\n          risk,\n          confidence,\n          evidence: {\n            reproVerified: false,\n            testsAdded: 0,\n            checksGreen: false,\n            attackPassed: false,\n            scopeMatches: false,\n          },\n        });\n      }\n      if (change === undefined) throw new Error(`task ${taskId} has no recorded change`);\n      let recordedChange = change;\n\n      if (currentTask.state === \"succeeded\") return { change: recordedChange, task: currentTask };\n\n      if (currentTask.state === \"running\") {\n        await requireTaskExecution(stores, ctx, taskId);\n        await options.presentChange?.({\n          taskId,\n          changeId: recordedChange.id,\n          verification,\n          summary,\n        });\n      }\n\n      let task: Task = currentTask;\n      if (task.state === \"running\") {\n        task = await stores.tasks.transition(taskId, \"verifying\", {\n          expectFrom: \"running\",\n          expectAttempt: currentTask.attempt,\n          expectExecution: currentTask.execution,\n          patch: { changeId: recordedChange.id },\n          reason: summary,\n        });\n      }\n      if (verification === \"required\") return { change: recordedChange, task };\n\n      const completion = await requireTaskExecutionIdentity(stores, ctx, taskId);\n      if (completion.state !== \"verifying\" || completion.changeId !== recordedChange.id) {\n        throw new Error(\"Task is no longer awaiting this Change's completion\");\n      }\n      if (recordedChange.state === \"verifying\") {\n        recordedChange = await stores.changes.transition(recordedChange.id, \"ready\", {\n          reason: \"independent verification is not configured\",\n        });\n      }\n      if (task.state === \"verifying\") {\n        task = await stores.tasks.transition(taskId, \"succeeded\", {\n          expectFrom: \"verifying\",\n          expectAttempt: currentTask.attempt,\n          expectExecution: currentTask.execution,\n          reason: \"change recorded for human review without independent verification\",\n          output: {\n            changeId: recordedChange.id,\n            prUrl: recordedChange.prUrl,\n            summary,\n            verification,\n          },\n        });\n      }\n      return { change: recordedChange, task };\n    },\n  });\n}\n"],"mappings":"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"}

package/dist/changes/presentation.d.mts

@@ -0,0 +1,14 @@
+import { ChangeId, TaskId } from "../schema/id.mjs";
+//#region src/changes/presentation.d.ts
+/** Details presented after a pull request is durably recorded as a Change. */
+interface PresentChangeInput {
+  taskId: TaskId;
+  changeId: ChangeId;
+  verification: "required" | "disabled";
+  summary: string;
+}
+/** Presents a newly recorded Change through an application-owned channel. */
+type ChangePresenter = (input: PresentChangeInput) => Promise<void>;
+//#endregion
+export { ChangePresenter, PresentChangeInput };
+//# sourceMappingURL=presentation.d.mts.map

package/dist/changes.d.mts

@@ -0,0 +1,24 @@
+/// <reference types="node" />
+import { ChangeId, RepositoryId, changeIdSchema } from "./schema/id.mjs";
+import { Change, ChangeEvidence, ChangeInState, ChangeLevel, ChangeState, changeEvidenceSchema, changeLevelSchema, changeSchema, changeStateSchema } from "./schema/change.mjs";
+import { ChangeAssociationError, ChangePatch, ChangeTransitionArguments, ChangeTransitionOptions, CreateChangeInput, FactoryStores, UpdateChangeEvidenceInput } from "./store/engine.mjs";
+import { changeInitialState, changeTransitions } from "./schema/transitions.mjs";
+import { ChangePresenter, PresentChangeInput } from "./changes/presentation.mjs";
+import { RecordChangeInput, RecordChangeResult, RecordChangeTool, RecordChangeToolOptions, RecordChangeToolStores, createRecordChangeTool } from "./changes/eve-record-change.mjs";
+import { formatChangeVerificationBrief } from "./change-verification/brief.mjs";
+import { PresentVerificationResultInput, RecordVerificationInput, RecordVerificationRefusal, RecordVerificationResult, RecordVerificationSuccess, RecordVerificationTool, RecordVerificationToolOptions, RecordVerificationToolStores, createRecordVerificationTool } from "./change-verification/eve-tool.mjs";
+import { ChangeVerificationStores, EnsureChangeVerificationTasksOptions, EnsureChangeVerificationTasksResult, RecoverChangeVerificationResultOptions, ensureChangeVerificationTasks, recoverChangeVerificationResult } from "./change-verification/dispatch.mjs";
+import { CreateMultiRepositoryChangeTasksInput, CreateMultiRepositoryChangeTasksStores, MultiRepositoryChangePlan, ReconcileMultiRepositoryChangeTasksResult, ReconcileMultiRepositoryChangeTasksStores, createMultiRepositoryChangeTasks, reconcileMultiRepositoryChangeTasks } from "./multi-repository-changes/coordination.mjs";
+//#region src/changes.d.ts
+/** Provider identity and author required to represent an existing pull request as a Change. */
+interface AdoptPullRequestInput {
+  repositoryId: RepositoryId;
+  prNumber: number;
+  prUrl: string;
+  author: string;
+}
+/** Create a conservative, unverified Change for a pull request not authored by Factory. */
+declare function adoptPullRequest(stores: Pick<FactoryStores, "changes">, input: AdoptPullRequestInput): Promise<Change>;
+//#endregion
+export { AdoptPullRequestInput, type Change, ChangeAssociationError, type ChangeEvidence, type ChangeId, type ChangeInState, type ChangeLevel, type ChangePatch, type ChangePresenter, type ChangeState, type ChangeTransitionArguments, type ChangeTransitionOptions, type ChangeVerificationStores, type CreateChangeInput, type CreateMultiRepositoryChangeTasksInput, type CreateMultiRepositoryChangeTasksStores, type EnsureChangeVerificationTasksOptions, type EnsureChangeVerificationTasksResult, type MultiRepositoryChangePlan, type PresentChangeInput, type PresentVerificationResultInput, type ReconcileMultiRepositoryChangeTasksResult, type ReconcileMultiRepositoryChangeTasksStores, type RecordChangeInput, type RecordChangeResult, type RecordChangeTool, type RecordChangeToolOptions, type RecordChangeToolStores, type RecordVerificationInput, type RecordVerificationRefusal, type RecordVerificationResult, type RecordVerificationSuccess, type RecordVerificationTool, type RecordVerificationToolOptions, type RecordVerificationToolStores, type RecoverChangeVerificationResultOptions, type UpdateChangeEvidenceInput, adoptPullRequest, changeEvidenceSchema, changeIdSchema, changeInitialState, changeLevelSchema, changeSchema, changeStateSchema, changeTransitions, createMultiRepositoryChangeTasks, createRecordChangeTool, createRecordVerificationTool, ensureChangeVerificationTasks, formatChangeVerificationBrief, reconcileMultiRepositoryChangeTasks, recoverChangeVerificationResult };
+//# sourceMappingURL=changes.d.mts.map

package/dist/changes.mjs

@@ -0,0 +1,29 @@
+import { changeIdSchema } from "./schema/id.mjs";
+import { changeInitialState, changeTransitions } from "./schema/transitions.mjs";
+import { changeEvidenceSchema, changeLevelSchema, changeSchema, changeStateSchema } from "./schema/change.mjs";
+import { ChangeAssociationError } from "./store/engine.mjs";
+import { createRecordChangeTool } from "./changes/eve-record-change.mjs";
+import { formatChangeVerificationBrief } from "./change-verification/brief.mjs";
+import { ensureChangeVerificationTasks, recoverChangeVerificationResult } from "./change-verification/dispatch.mjs";
+import { createRecordVerificationTool } from "./change-verification/eve-tool.mjs";
+import { createMultiRepositoryChangeTasks, reconcileMultiRepositoryChangeTasks } from "./multi-repository-changes/coordination.mjs";
+//#region src/changes.ts
+/** Create a conservative, unverified Change for a pull request not authored by Factory. */
+async function adoptPullRequest(stores, input) {
+	return stores.changes.create({
+		...input,
+		risk: "low",
+		confidence: "low",
+		evidence: {
+			reproVerified: false,
+			testsAdded: 0,
+			checksGreen: false,
+			attackPassed: false,
+			scopeMatches: false
+		}
+	});
+}
+//#endregion
+export { ChangeAssociationError, adoptPullRequest, changeEvidenceSchema, changeIdSchema, changeInitialState, changeLevelSchema, changeSchema, changeStateSchema, changeTransitions, createMultiRepositoryChangeTasks, createRecordChangeTool, createRecordVerificationTool, ensureChangeVerificationTasks, formatChangeVerificationBrief, reconcileMultiRepositoryChangeTasks, recoverChangeVerificationResult };
+
+//# sourceMappingURL=changes.mjs.map

package/dist/changes.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"changes.mjs","names":[],"sources":["../src/changes.ts"],"sourcesContent":["import type { Change } from \"./schema/change\";\nimport type { RepositoryId } from \"./schema/id\";\nimport type { FactoryStores } from \"./store/engine\";\n\nexport { type ChangePresenter, type PresentChangeInput } from \"./changes/presentation\";\nexport {\n  createRecordChangeTool,\n  type RecordChangeInput,\n  type RecordChangeResult,\n  type RecordChangeTool,\n  type RecordChangeToolStores,\n  type RecordChangeToolOptions,\n} from \"./changes/eve-record-change\";\nexport { formatChangeVerificationBrief } from \"./change-verification/brief\";\nexport {\n  ensureChangeVerificationTasks,\n  recoverChangeVerificationResult,\n  type ChangeVerificationStores,\n  type EnsureChangeVerificationTasksOptions,\n  type EnsureChangeVerificationTasksResult,\n  type RecoverChangeVerificationResultOptions,\n} from \"./change-verification/dispatch\";\nexport {\n  createRecordVerificationTool,\n  type PresentVerificationResultInput,\n  type RecordVerificationInput,\n  type RecordVerificationRefusal,\n  type RecordVerificationResult,\n  type RecordVerificationSuccess,\n  type RecordVerificationTool,\n  type RecordVerificationToolStores,\n  type RecordVerificationToolOptions,\n} from \"./change-verification/eve-tool\";\nexport {\n  createMultiRepositoryChangeTasks,\n  reconcileMultiRepositoryChangeTasks,\n  type CreateMultiRepositoryChangeTasksInput,\n  type CreateMultiRepositoryChangeTasksStores,\n  type MultiRepositoryChangePlan,\n  type ReconcileMultiRepositoryChangeTasksResult,\n  type ReconcileMultiRepositoryChangeTasksStores,\n} from \"./multi-repository-changes/coordination\";\n\n/** Provider identity and author required to represent an existing pull request as a Change. */\nexport interface AdoptPullRequestInput {\n  repositoryId: RepositoryId;\n  prNumber: number;\n  prUrl: string;\n  author: string;\n}\n\n/** Create a conservative, unverified Change for a pull request not authored by Factory. */\nexport async function adoptPullRequest(\n  stores: Pick<FactoryStores, \"changes\">,\n  input: AdoptPullRequestInput,\n): Promise<Change> {\n  return stores.changes.create({\n    ...input,\n    risk: \"low\",\n    confidence: \"low\",\n    evidence: {\n      reproVerified: false,\n      testsAdded: 0,\n      checksGreen: false,\n      attackPassed: false,\n      scopeMatches: false,\n    },\n  });\n}\n\nexport {\n  changeEvidenceSchema,\n  changeSchema,\n  changeStateSchema,\n  changeLevelSchema,\n  type Change,\n  type ChangeEvidence,\n  type ChangeInState,\n  type ChangeState,\n  type ChangeLevel,\n} from \"./schema/change\";\nexport { changeIdSchema, type ChangeId } from \"./schema/id\";\nexport { changeInitialState, changeTransitions } from \"./schema/transitions\";\nexport {\n  ChangeAssociationError,\n  type ChangePatch,\n  type ChangeTransitionOptions,\n  type ChangeTransitionArguments,\n  type CreateChangeInput,\n  type UpdateChangeEvidenceInput,\n} from \"./store/engine\";\n"],"mappings":";;;;;;;;;;;AAoDA,eAAsB,iBACpB,QACA,OACiB;CACjB,OAAO,OAAO,QAAQ,OAAO;EAC3B,GAAG;EACH,MAAM;EACN,YAAY;EACZ,UAAU;GACR,eAAe;GACf,YAAY;GACZ,aAAa;GACb,cAAc;GACd,cAAc;EAChB;CACF,CAAC;AACH"}

package/dist/client-events.d.mts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+//#region src/client-events.d.ts
+/** Validates an execution stream event, normalizing payloadless completion events. */
+declare const streamEventSchema: z.ZodUnion<[z.ZodObject<{
+  type: z.ZodString;
+  data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+  meta: z.ZodOptional<z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    at: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+  meta: z.ZodOptional<z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    at: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+  type: z.ZodLiteral<"session.completed">;
+  data: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>]>;
+/** One validated event received from a Factory execution stream. */
+type StreamEvent = z.infer<typeof streamEventSchema>;
+/** Parses validated newline-delimited events from a response body. */
+declare function readEvents(body: ReadableStream<Uint8Array>): AsyncGenerator<StreamEvent>;
+//#endregion
+export { StreamEvent, readEvents, streamEventSchema };
+//# sourceMappingURL=client-events.d.mts.map

package/dist/client-events.mjs

@@ -0,0 +1,45 @@
+import { z } from "zod";
+//#region src/client-events.ts
+const eventWithDataSchema = z.object({
+	type: z.string(),
+	data: z.record(z.string(), z.unknown()),
+	meta: z.object({
+		id: z.string().optional(),
+		at: z.string().optional()
+	}).optional()
+});
+/** Validates an execution stream event, normalizing payloadless completion events. */
+const streamEventSchema = eventWithDataSchema.or(eventWithDataSchema.extend({
+	type: z.literal("session.completed"),
+	data: z.record(z.string(), z.unknown()).default({})
+}));
+/** Parses validated newline-delimited events from a response body. */
+async function* readEvents(body) {
+	const reader = body.getReader();
+	const decoder = new TextDecoder();
+	let pending = "";
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			pending += done ? decoder.decode() : decoder.decode(value, { stream: true });
+			let newline;
+			while ((newline = pending.indexOf("\n")) >= 0) {
+				const line = pending.slice(0, newline).trim();
+				pending = pending.slice(newline + 1);
+				if (line) yield streamEventSchema.parse(JSON.parse(line));
+			}
+			if (pending.length > 2e6) throw new Error("Stream event exceeds the 2 MB limit");
+			if (done) {
+				if (pending.trim()) yield streamEventSchema.parse(JSON.parse(pending));
+				return;
+			}
+		}
+	} finally {
+		await reader.cancel().catch(() => {});
+		reader.releaseLock();
+	}
+}
+//#endregion
+export { readEvents, streamEventSchema };
+
+//# sourceMappingURL=client-events.mjs.map

package/dist/client-events.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-events.mjs","names":[],"sources":["../src/client-events.ts"],"sourcesContent":["import { z } from \"zod\";\n\nconst eventWithDataSchema = z.object({\n  type: z.string(),\n  data: z.record(z.string(), z.unknown()),\n  meta: z.object({ id: z.string().optional(), at: z.string().optional() }).optional(),\n});\n/** Validates an execution stream event, normalizing payloadless completion events. */\nexport const streamEventSchema = eventWithDataSchema.or(\n  eventWithDataSchema.extend({\n    type: z.literal(\"session.completed\"),\n    data: z.record(z.string(), z.unknown()).default({}),\n  }),\n);\n/** One validated event received from a Factory execution stream. */\nexport type StreamEvent = z.infer<typeof streamEventSchema>;\n\n/** Parses validated newline-delimited events from a response body. */\nexport async function* readEvents(body: ReadableStream<Uint8Array>): AsyncGenerator<StreamEvent> {\n  const reader = body.getReader();\n  const decoder = new TextDecoder();\n  let pending = \"\";\n  try {\n    for (;;) {\n      const { done, value } = await reader.read();\n      pending += done ? decoder.decode() : decoder.decode(value, { stream: true });\n      let newline: number;\n      while ((newline = pending.indexOf(\"\\n\")) >= 0) {\n        const line = pending.slice(0, newline).trim();\n        pending = pending.slice(newline + 1);\n        if (line) yield streamEventSchema.parse(JSON.parse(line));\n      }\n      if (pending.length > 2_000_000) throw new Error(\"Stream event exceeds the 2 MB limit\");\n      if (done) {\n        if (pending.trim()) yield streamEventSchema.parse(JSON.parse(pending));\n        return;\n      }\n    }\n  } finally {\n    await reader.cancel().catch(() => {});\n    reader.releaseLock();\n  }\n}\n"],"mappings":";;AAEA,MAAM,sBAAsB,EAAE,OAAO;CACnC,MAAM,EAAE,OAAO;CACf,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,EAAE,QAAQ,CAAC;CACtC,MAAM,EAAE,OAAO;EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,SAAS;EAAG,IAAI,EAAE,OAAO,CAAC,CAAC,SAAS;CAAE,CAAC,CAAC,CAAC,SAAS;AACpF,CAAC;;AAED,MAAa,oBAAoB,oBAAoB,GACnD,oBAAoB,OAAO;CACzB,MAAM,EAAE,QAAQ,mBAAmB;CACnC,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;AACpD,CAAC,CACH;;AAKA,gBAAuB,WAAW,MAA+D;CAC/F,MAAM,SAAS,KAAK,UAAU;CAC9B,MAAM,UAAU,IAAI,YAAY;CAChC,IAAI,UAAU;CACd,IAAI;EACF,SAAS;GACP,MAAM,EAAE,MAAM,UAAU,MAAM,OAAO,KAAK;GAC1C,WAAW,OAAO,QAAQ,OAAO,IAAI,QAAQ,OAAO,OAAO,EAAE,QAAQ,KAAK,CAAC;GAC3E,IAAI;GACJ,QAAQ,UAAU,QAAQ,QAAQ,IAAI,MAAM,GAAG;IAC7C,MAAM,OAAO,QAAQ,MAAM,GAAG,OAAO,CAAC,CAAC,KAAK;IAC5C,UAAU,QAAQ,MAAM,UAAU,CAAC;IACnC,IAAI,MAAM,MAAM,kBAAkB,MAAM,KAAK,MAAM,IAAI,CAAC;GAC1D;GACA,IAAI,QAAQ,SAAS,KAAW,MAAM,IAAI,MAAM,qCAAqC;GACrF,IAAI,MAAM;IACR,IAAI,QAAQ,KAAK,GAAG,MAAM,kBAAkB,MAAM,KAAK,MAAM,OAAO,CAAC;IACrE;GACF;EACF;CACF,UAAU;EACR,MAAM,OAAO,OAAO,CAAC,CAAC,YAAY,CAAC,CAAC;EACpC,OAAO,YAAY;CACrB;AACF"}

package/dist/client-stream.d.mts

@@ -0,0 +1,28 @@
+import { TaskId } from "./schema/id.mjs";
+import { AgentSessionId } from "./schema/session.mjs";
+import { Transcript } from "./client-transcript.mjs";
+import { FactoryClient } from "./client.mjs";
+import { SessionView } from "./api-contracts.mjs";
+//#region src/client-stream.d.ts
+/** Client operations required to hydrate and follow a Factory session stream. */
+type SessionStreamClient = Pick<FactoryClient, "getSessionTranscriptResponse" | "getSessionEventStreamResponse">;
+/** Callbacks and exact execution identity used while following a session stream. */
+interface FollowSessionStreamOptions {
+  readonly sessionId: AgentSessionId;
+  readonly executionId: string | null;
+  readonly taskId?: TaskId;
+  readonly history?: readonly NonNullable<SessionView["history"]>[number][];
+  readonly transcript: Transcript;
+  readonly signal: AbortSignal;
+  readonly pollIntervalMs?: number;
+  readonly onHydrated: () => void;
+  readonly onChange: () => void;
+  readonly onConnection: (state: "connected" | "reconnecting") => void;
+  readonly onError: (error: unknown) => void;
+  readonly onConflict: () => Promise<void>;
+}
+/** Hydrates a transcript and follows its current execution until completion or disconnection. */
+declare function followSessionStream(client: SessionStreamClient, options: FollowSessionStreamOptions): Promise<void>;
+//#endregion
+export { FollowSessionStreamOptions, SessionStreamClient, followSessionStream };
+//# sourceMappingURL=client-stream.d.mts.map

package/dist/client-stream.mjs

@@ -0,0 +1,210 @@
+import { readEvents } from "./client-events.mjs";
+import { transcriptSnapshotSchema } from "./schema/transcript.mjs";
+import { Transcript } from "./client-transcript.mjs";
+import { ApiError } from "./client.mjs";
+//#region src/client-stream.ts
+function pause(ms, signal) {
+	return new Promise((resolve) => {
+		const finish = () => {
+			clearTimeout(timer);
+			signal.removeEventListener("abort", finish);
+			resolve();
+		};
+		const timer = setTimeout(finish, ms);
+		signal.addEventListener("abort", finish, { once: true });
+		if (signal.aborted) finish();
+	});
+}
+async function readSnapshot(client, input) {
+	let failures = 0;
+	while (!input.signal.aborted) try {
+		const requestSignal = AbortSignal.any([input.signal, AbortSignal.timeout(15e3)]);
+		const response = await client.getSessionTranscriptResponse({
+			sessionId: input.sessionId,
+			executionId: input.executionId,
+			...input.taskId === void 0 ? {} : { taskId: input.taskId },
+			...input.history ? { history: true } : {},
+			signal: requestSignal
+		});
+		input.transcript.hydrate(transcriptSnapshotSchema.parse(await response.json()));
+		return;
+	} catch (error) {
+		if (input.signal.aborted) return;
+		if (error instanceof ApiError) throw error;
+		input.onRetry?.(error);
+		failures++;
+		await pause(Math.min(15e3, input.pollIntervalMs * 2 ** Math.min(failures, 3)), input.signal);
+	}
+}
+async function loadHistory(client, options) {
+	const entries = options.history ?? [];
+	const results = /* @__PURE__ */ new Map();
+	let next = 0;
+	await Promise.all(Array.from({ length: Math.min(4, entries.length) }, async () => {
+		while (next < entries.length) {
+			const index = next++;
+			const entry = entries[index];
+			if (!entry) throw new Error("Historical transcript index is unavailable");
+			const id = entry.execution.sessionId;
+			const previous = new Transcript(entry.message, entry.attachments);
+			const header = {
+				id: "run",
+				kind: "status",
+				title: entry.agent,
+				text: entry.taskId ? `Earlier work · ${entry.taskId}` : "Earlier execution"
+			};
+			try {
+				const historySignal = AbortSignal.any([options.signal, AbortSignal.timeout(15e3)]);
+				await readSnapshot(client, {
+					sessionId: options.sessionId,
+					executionId: id,
+					history: true,
+					transcript: previous,
+					signal: historySignal,
+					pollIntervalMs: options.pollIntervalMs ?? 2e3
+				});
+				if (historySignal.aborted && !options.signal.aborted) throw new Error("Historical transcript loading timed out");
+			} catch (error) {
+				if (options.signal.aborted) return;
+				if (error instanceof ApiError && [401, 403].includes(error.status)) throw error;
+				previous.put({
+					id: "unavailable",
+					kind: "status",
+					title: "History unavailable",
+					text: "This execution's transcript could not be loaded."
+				});
+			}
+			previous.blocks.unshift(header);
+			results.set(index, {
+				id,
+				transcript: previous
+			});
+		}
+	}));
+	return entries.map((_, index) => {
+		const result = results.get(index);
+		if (!result) throw new Error("Historical transcript loading did not complete");
+		return result;
+	});
+}
+async function hydrateCurrent(client, options) {
+	const executionId = options.executionId;
+	if (executionId === null) return true;
+	let failures = 0;
+	while (!options.signal.aborted) try {
+		await readSnapshot(client, {
+			sessionId: options.sessionId,
+			executionId,
+			taskId: options.taskId,
+			history: false,
+			transcript: options.transcript,
+			signal: options.signal,
+			pollIntervalMs: options.pollIntervalMs ?? 2e3,
+			onRetry: (error) => {
+				options.onConnection("reconnecting");
+				options.onError(error);
+			}
+		});
+		if (options.signal.aborted) return false;
+		options.onConnection("connected");
+		return true;
+	} catch (error) {
+		if (options.signal.aborted) return false;
+		options.onConnection("reconnecting");
+		failures++;
+		options.onError(error);
+		if (error instanceof ApiError && [
+			0,
+			301,
+			302,
+			303,
+			307,
+			308,
+			401,
+			403
+		].includes(error.status)) return false;
+		if (error instanceof ApiError && error.status === 404) return false;
+		if (error instanceof ApiError && error.status === 409) {
+			await options.onConflict();
+			return false;
+		}
+		await pause(Math.min(15e3, (options.pollIntervalMs ?? 2e3) * 2 ** Math.min(failures, 3)), options.signal);
+	}
+	return false;
+}
+/** Hydrates a transcript and follows its current execution until completion or disconnection. */
+async function followSessionStream(client, options) {
+	const { sessionId, executionId, transcript, signal } = options;
+	let history;
+	let hydrated;
+	try {
+		[history, hydrated] = await Promise.all([loadHistory(client, options), hydrateCurrent(client, options)]);
+	} catch (error) {
+		if (!signal.aborted) options.onError(error);
+		return;
+	}
+	if (signal.aborted || !hydrated) return;
+	transcript.prependHistory(history);
+	if (executionId === null) transcript.state = "waiting";
+	options.onHydrated();
+	if (executionId === null || ["completed", "failed"].includes(transcript.state)) return;
+	let failures = 0;
+	while (!signal.aborted) {
+		const recycle = AbortSignal.timeout(6e4);
+		let established = false;
+		try {
+			const response = await client.getSessionEventStreamResponse({
+				sessionId,
+				executionId,
+				cursor: transcript.cursor,
+				...options.taskId === void 0 ? {} : { taskId: options.taskId },
+				signal: AbortSignal.any([signal, recycle])
+			});
+			if (!response.body) throw new Error("The factory returned an empty stream");
+			established = true;
+			options.onConnection("connected");
+			for await (const event of readEvents(response.body)) {
+				if (signal.aborted) return;
+				transcript.accept(event);
+				failures = 0;
+				options.onChange();
+			}
+			if (["completed", "failed"].includes(transcript.state)) return;
+		} catch (error) {
+			if (signal.aborted) return;
+			options.onConnection("reconnecting");
+			if (recycle.aborted && established) {
+				failures = 0;
+				continue;
+			}
+			failures++;
+			options.onError(error);
+			if (error instanceof ApiError && [
+				0,
+				301,
+				302,
+				303,
+				307,
+				308,
+				401,
+				403
+			].includes(error.status)) return;
+			if (error instanceof ApiError && error.status === 404) {
+				if (transcript.state === "running") {
+					transcript.state = "connecting";
+					options.onChange();
+				}
+				return;
+			}
+			if (error instanceof ApiError && error.status === 409) {
+				await options.onConflict();
+				return;
+			}
+		}
+		await pause(Math.min(15e3, (options.pollIntervalMs ?? 2e3) * 2 ** Math.min(failures, 3)), signal);
+	}
+}
+//#endregion
+export { followSessionStream };
+
+//# sourceMappingURL=client-stream.mjs.map

package/dist/client-stream.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-stream.mjs","names":[],"sources":["../src/client-stream.ts"],"sourcesContent":["import { ApiError, type FactoryClient } from \"./client\";\nimport { readEvents } from \"./client-events\";\nimport { Transcript } from \"./client-transcript\";\nimport type { SessionView } from \"./api-contracts\";\nimport type { TaskId } from \"./schema/id\";\nimport type { AgentSessionId } from \"./schema/session\";\nimport { transcriptSnapshotSchema } from \"./schema/transcript\";\n\n/** Client operations required to hydrate and follow a Factory session stream. */\nexport type SessionStreamClient = Pick<\n  FactoryClient,\n  \"getSessionTranscriptResponse\" | \"getSessionEventStreamResponse\"\n>;\n\n/** Callbacks and exact execution identity used while following a session stream. */\nexport interface FollowSessionStreamOptions {\n  readonly sessionId: AgentSessionId;\n  readonly executionId: string | null;\n  readonly taskId?: TaskId;\n  readonly history?: readonly NonNullable<SessionView[\"history\"]>[number][];\n  readonly transcript: Transcript;\n  readonly signal: AbortSignal;\n  readonly pollIntervalMs?: number;\n  readonly onHydrated: () => void;\n  readonly onChange: () => void;\n  readonly onConnection: (state: \"connected\" | \"reconnecting\") => void;\n  readonly onError: (error: unknown) => void;\n  readonly onConflict: () => Promise<void>;\n}\n\nfunction pause(ms: number, signal: AbortSignal): Promise<void> {\n  return new Promise((resolve) => {\n    const finish = () => {\n      clearTimeout(timer);\n      signal.removeEventListener(\"abort\", finish);\n      resolve();\n    };\n    const timer = setTimeout(finish, ms);\n    signal.addEventListener(\"abort\", finish, { once: true });\n    if (signal.aborted) finish();\n  });\n}\n\nasync function readSnapshot(\n  client: SessionStreamClient,\n  input: {\n    sessionId: AgentSessionId;\n    executionId: string;\n    taskId?: TaskId;\n    history: boolean;\n    transcript: Transcript;\n    signal: AbortSignal;\n    pollIntervalMs: number;\n    onRetry?(error: unknown): void;\n  },\n) {\n  let failures = 0;\n  while (!input.signal.aborted) {\n    try {\n      const requestSignal = AbortSignal.any([input.signal, AbortSignal.timeout(15_000)]);\n      const response = await client.getSessionTranscriptResponse({\n        sessionId: input.sessionId,\n        executionId: input.executionId,\n        ...(input.taskId === undefined ? {} : { taskId: input.taskId }),\n        ...(input.history ? { history: true } : {}),\n        signal: requestSignal,\n      });\n      input.transcript.hydrate(transcriptSnapshotSchema.parse(await response.json()));\n      return;\n    } catch (error) {\n      if (input.signal.aborted) return;\n      if (error instanceof ApiError) throw error;\n      input.onRetry?.(error);\n      failures++;\n      await pause(\n        Math.min(15_000, input.pollIntervalMs * 2 ** Math.min(failures, 3)),\n        input.signal,\n      );\n    }\n  }\n}\n\nasync function loadHistory(\n  client: SessionStreamClient,\n  options: FollowSessionStreamOptions,\n): Promise<{ id: string; transcript: Transcript }[]> {\n  const entries = options.history ?? [];\n  const results = new Map<number, { id: string; transcript: Transcript }>();\n  let next = 0;\n  await Promise.all(\n    Array.from({ length: Math.min(4, entries.length) }, async () => {\n      while (next < entries.length) {\n        const index = next++;\n        const entry = entries[index];\n        if (!entry) throw new Error(\"Historical transcript index is unavailable\");\n        const id = entry.execution.sessionId;\n        const previous = new Transcript(entry.message, entry.attachments);\n        const header = {\n          id: \"run\",\n          kind: \"status\",\n          title: entry.agent,\n          text: entry.taskId ? `Earlier work · ${entry.taskId}` : \"Earlier execution\",\n        } as const;\n        try {\n          const historySignal = AbortSignal.any([options.signal, AbortSignal.timeout(15_000)]);\n          await readSnapshot(client, {\n            sessionId: options.sessionId,\n            executionId: id,\n            history: true,\n            transcript: previous,\n            signal: historySignal,\n            pollIntervalMs: options.pollIntervalMs ?? 2000,\n          });\n          if (historySignal.aborted && !options.signal.aborted)\n            throw new Error(\"Historical transcript loading timed out\");\n        } catch (error) {\n          if (options.signal.aborted) return;\n          if (error instanceof ApiError && [401, 403].includes(error.status)) throw error;\n          previous.put({\n            id: \"unavailable\",\n            kind: \"status\",\n            title: \"History unavailable\",\n            text: \"This execution's transcript could not be loaded.\",\n          });\n        }\n        previous.blocks.unshift(header);\n        results.set(index, { id, transcript: previous });\n      }\n    }),\n  );\n  return entries.map((_, index) => {\n    const result = results.get(index);\n    if (!result) throw new Error(\"Historical transcript loading did not complete\");\n    return result;\n  });\n}\n\nasync function hydrateCurrent(\n  client: SessionStreamClient,\n  options: FollowSessionStreamOptions,\n): Promise<boolean> {\n  const executionId = options.executionId;\n  if (executionId === null) return true;\n  let failures = 0;\n  while (!options.signal.aborted) {\n    try {\n      await readSnapshot(client, {\n        sessionId: options.sessionId,\n        executionId,\n        taskId: options.taskId,\n        history: false,\n        transcript: options.transcript,\n        signal: options.signal,\n        pollIntervalMs: options.pollIntervalMs ?? 2000,\n        onRetry: (error) => {\n          options.onConnection(\"reconnecting\");\n          options.onError(error);\n        },\n      });\n      if (options.signal.aborted) return false;\n      options.onConnection(\"connected\");\n      return true;\n    } catch (error) {\n      if (options.signal.aborted) return false;\n      options.onConnection(\"reconnecting\");\n      failures++;\n      options.onError(error);\n      if (\n        error instanceof ApiError &&\n        [0, 301, 302, 303, 307, 308, 401, 403].includes(error.status)\n      )\n        return false;\n      if (error instanceof ApiError && error.status === 404) return false;\n      if (error instanceof ApiError && error.status === 409) {\n        await options.onConflict();\n        return false;\n      }\n      await pause(\n        Math.min(15_000, (options.pollIntervalMs ?? 2000) * 2 ** Math.min(failures, 3)),\n        options.signal,\n      );\n    }\n  }\n  return false;\n}\n\n/** Hydrates a transcript and follows its current execution until completion or disconnection. */\nexport async function followSessionStream(\n  client: SessionStreamClient,\n  options: FollowSessionStreamOptions,\n): Promise<void> {\n  const { sessionId, executionId, transcript, signal } = options;\n  let history: { id: string; transcript: Transcript }[];\n  let hydrated: boolean;\n  try {\n    [history, hydrated] = await Promise.all([\n      loadHistory(client, options),\n      hydrateCurrent(client, options),\n    ]);\n  } catch (error) {\n    if (!signal.aborted) options.onError(error);\n    return;\n  }\n  if (signal.aborted || !hydrated) return;\n  transcript.prependHistory(history);\n  if (executionId === null) transcript.state = \"waiting\";\n  options.onHydrated();\n  if (executionId === null || [\"completed\", \"failed\"].includes(transcript.state)) return;\n  let failures = 0;\n  while (!signal.aborted) {\n    const recycle = AbortSignal.timeout(60_000);\n    let established = false;\n    try {\n      const response = await client.getSessionEventStreamResponse({\n        sessionId,\n        executionId,\n        cursor: transcript.cursor,\n        ...(options.taskId === undefined ? {} : { taskId: options.taskId }),\n        signal: AbortSignal.any([signal, recycle]),\n      });\n      if (!response.body) throw new Error(\"The factory returned an empty stream\");\n      established = true;\n      options.onConnection(\"connected\");\n      for await (const event of readEvents(response.body)) {\n        if (signal.aborted) return;\n        transcript.accept(event);\n        failures = 0;\n        options.onChange();\n      }\n      if ([\"completed\", \"failed\"].includes(transcript.state)) return;\n    } catch (error) {\n      if (signal.aborted) return;\n      options.onConnection(\"reconnecting\");\n      if (recycle.aborted && established) {\n        failures = 0;\n        continue;\n      }\n      failures++;\n      options.onError(error);\n      if (\n        error instanceof ApiError &&\n        [0, 301, 302, 303, 307, 308, 401, 403].includes(error.status)\n      )\n        return;\n      if (error instanceof ApiError && error.status === 404) {\n        if (transcript.state === \"running\") {\n          transcript.state = \"connecting\";\n          options.onChange();\n        }\n        return;\n      }\n      if (error instanceof ApiError && error.status === 409) {\n        await options.onConflict();\n        return;\n      }\n    }\n    await pause(\n      Math.min(15_000, (options.pollIntervalMs ?? 2000) * 2 ** Math.min(failures, 3)),\n      signal,\n    );\n  }\n}\n"],"mappings":"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"}