@vercel/factory 0.0.13 → 0.0.15

package/dist/store/task-work.mjs

@@ -0,0 +1,134 @@
+import { taskSchema } from "../schema/task.mjs";
+import { InvalidTransitionError } from "../schema/transitions.mjs";
+import { RecordNotFoundError, VersionConflictError } from "./driver.mjs";
+import { assertTaskAdmission } from "./task-graphs.mjs";
+import { z } from "zod";
+import { isDeepStrictEqual } from "node:util";
+//#region src/store/task-work.ts
+/** Creates workflow-facing Task operations backed by canonical graph and Task stores. */
+function createTaskWorkStore(options) {
+	const { driver, now, stores, workflows, update, restore } = options;
+	function parseTask(value) {
+		const task = taskSchema.parse(value);
+		workflows.validateStoredInput(task.work.workflow, task.work.input);
+		if (task.workResult) workflows.validateStoredOutput(task.work.workflow, task.workResult.output);
+		return task;
+	}
+	async function read(id) {
+		const record = await driver.get("tasks", id);
+		if (!record) throw new RecordNotFoundError("tasks", id);
+		const task = parseTask(record.value);
+		if (task.id !== id) throw new Error(`Task ${id} does not match its storage key`);
+		return {
+			task,
+			version: record.version,
+			work: task.work
+		};
+	}
+	async function recover(rootTaskId) {
+		const graph = await stores().graphs.get(rootTaskId);
+		if (!graph) throw new RecordNotFoundError("taskGraphs", rootTaskId);
+		const tasks = [];
+		for (const node of graph.nodes) {
+			const admission = parseTask(node.admission);
+			const task = parseTask(await stores().tasks.get(node.taskId) ?? await restore(admission));
+			assertTaskAdmission({
+				task,
+				admission
+			});
+			tasks.push(task);
+		}
+		return tasks;
+	}
+	function assertAttempt(task, expectAttempt) {
+		z.number().int().positive().parse(expectAttempt);
+		if (task.attempt !== expectAttempt) throw new Error(`Task ${task.id} is on attempt ${task.attempt}, not ${expectAttempt}`);
+	}
+	async function setWaiting(id, expectAttempt, waiting, phase) {
+		for (;;) {
+			const { task, version } = await read(id);
+			assertAttempt(task, expectAttempt);
+			if (task.state !== "running") throw new Error(`Task ${id} must be running to ${waiting ? "wait" : "resume"}`);
+			const next = taskSchema.parse({
+				...task,
+				waitingForMessages: waiting,
+				workflowPhase: phase ?? task.workflowPhase,
+				lastProgressAt: waiting ? task.lastProgressAt : now(),
+				updatedAt: now()
+			});
+			if (task.waitingForMessages === waiting && next.workflowPhase === task.workflowPhase) return task;
+			await stores().receipts.append({
+				taskId: id,
+				repositoryIds: task.repositoryIds,
+				kind: task.kind,
+				state: waiting ? "waiting" : "resumed",
+				phase: "workflow",
+				attempt: task.attempt,
+				reason: waiting ? "Workflow is waiting for Task messages" : "Workflow resumed message processing",
+				dedupeKey: `work:${id}:${version}:${waiting ? "wait" : "resume"}`
+			});
+			try {
+				await update(next, version);
+				return next;
+			} catch (error) {
+				if (!(error instanceof VersionConflictError)) throw error;
+			}
+		}
+	}
+	async function complete(input, expectedWorkflow) {
+		const { task: { taskId: id, attempt: expectAttempt }, output: value } = input;
+		for (;;) {
+			const { task, work } = await read(id);
+			assertAttempt(task, expectAttempt);
+			if (expectedWorkflow !== void 0 && !isDeepStrictEqual(work.workflow, expectedWorkflow)) throw new Error(`Task ${id} uses workflow ${work.workflow.id}@${work.workflow.version}, not ${expectedWorkflow.id}@${expectedWorkflow.version}`);
+			if (task.state === "succeeded") {
+				const output = workflows.validateOutput(work.workflow, value);
+				if (!isDeepStrictEqual(task.workResult?.output, output)) throw new Error(`Task ${id} already recorded a different workflow output`);
+				return task;
+			}
+			try {
+				return await stores().tasks.transition(id, "succeeded", {
+					output: value,
+					expectAttempt,
+					expectFrom: task.state,
+					phase: "workflow"
+				});
+			} catch (error) {
+				if (error instanceof VersionConflictError) continue;
+				if (error instanceof InvalidTransitionError && (await read(id)).task.state === "succeeded") continue;
+				throw error;
+			}
+		}
+	}
+	return {
+		complete,
+		completeWorkflow: ({ task, workflow, output }) => complete({
+			task,
+			output
+		}, workflow),
+		waitForMessages: ({ task: { taskId, attempt }, phase }) => setWaiting(taskId, attempt, true, phase),
+		resume: ({ task: { taskId, attempt } }) => setWaiting(taskId, attempt, false),
+		recover,
+		async usage(rootTaskId) {
+			const tasks = await recover(rootTaskId);
+			let micros = 0;
+			let inputTokens = 0;
+			let outputTokens = 0;
+			for (const task of tasks) {
+				micros += Math.round((task.usage?.costUsd ?? task.settledUsd ?? 0) * 1e6);
+				inputTokens += task.usage?.inputTokens ?? 0;
+				outputTokens += task.usage?.outputTokens ?? 0;
+			}
+			return {
+				costUsd: micros / 1e6,
+				inputTokens,
+				outputTokens,
+				taskCount: tasks.length
+			};
+		}
+	};
+}
+//#endregion
+export { createTaskWorkStore };
+
+//# sourceMappingURL=task-work.mjs.map

package/dist/store/task-work.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-work.mjs","names":[],"sources":["../../src/store/task-work.ts"],"sourcesContent":["import { isDeepStrictEqual } from \"node:util\";\nimport { z } from \"zod\";\nimport type { IsoDateTimeClock } from \"../schema/common\";\nimport type { TaskAttemptRef } from \"../schema/execution\";\nimport type { TaskId } from \"../schema/id\";\nimport { taskSchema, type Task } from \"../schema/task\";\nimport { InvalidTransitionError } from \"../schema/transitions\";\nimport type { JsonValue, WorkflowBinding } from \"../schema/work\";\nimport type { WorkflowRegistry } from \"../workflows\";\nimport { RecordNotFoundError, VersionConflictError, type StoreDriver } from \"./driver\";\nimport type { FactoryStores } from \"./engine\";\nimport { assertTaskAdmission } from \"./task-graphs\";\n\n/** Workflow-facing Task operations for completion, message waiting, recovery, and usage aggregation. */\nexport interface TaskWorkStore {\n  /** Complete through the dynamic registry boundary, which validates unknown output at runtime. */\n  complete(input: CompleteTaskWorkInput): Promise<Task>;\n  /** Complete work while statically checking output against its exact workflow binding. */\n  completeWorkflow<Output extends JsonValue>(\n    input: CompleteWorkflowTaskWorkInput<Output>,\n  ): Promise<Task>;\n  waitForMessages(input: WaitForTaskMessagesInput): Promise<Task>;\n  resume(input: ResumeTaskWorkInput): Promise<Task>;\n  /** Repair admitted creation snapshots by direct graph IDs, never by scanning the bucket. */\n  recover(rootTaskId: TaskId): Promise<readonly Task[]>;\n  /** Each Task contributes local measured usage once; no parent roll-up is charged again. */\n  usage(rootTaskId: TaskId): Promise<TaskWorkUsage>;\n}\n\n/** Exact Task attempt and candidate workflow output used to complete work. */\nexport interface CompleteTaskWorkInput {\n  task: TaskAttemptRef;\n  output: unknown;\n}\n\n/** Exact Task attempt, workflow contract, and statically checked output used to complete work. */\nexport interface CompleteWorkflowTaskWorkInput<Output extends JsonValue = JsonValue> {\n  task: TaskAttemptRef;\n  workflow: WorkflowBinding<JsonValue, Output>;\n  output: NoInfer<Output>;\n}\n\n/** Aggregated measured usage across one canonical Task graph. */\nexport interface TaskWorkUsage {\n  costUsd: number;\n  inputTokens: number;\n  outputTokens: number;\n  taskCount: number;\n}\n\n/** Exact running Task attempt and optional workflow phase used to await messages. */\nexport interface WaitForTaskMessagesInput {\n  task: TaskAttemptRef;\n  phase?: string;\n}\n\n/** Exact running Task attempt to resume after message delivery. */\nexport interface ResumeTaskWorkInput {\n  task: TaskAttemptRef;\n}\n\n/** Canonical Task graph, receipt, and Task capabilities used by workflow-facing operations. */\nexport type TaskWorkStores = Pick<FactoryStores, \"graphs\" | \"receipts\" | \"tasks\">;\n\n/** Engine-owned dependencies used to construct workflow-facing Task operations. */\nexport interface CreateTaskWorkStoreOptions {\n  driver: StoreDriver;\n  now: IsoDateTimeClock;\n  stores: () => TaskWorkStores;\n  workflows: WorkflowRegistry;\n  update(task: Task, version: number): Promise<void>;\n  restore(task: Task): Promise<Task>;\n}\n\n/** Creates workflow-facing Task operations backed by canonical graph and Task stores. */\nexport function createTaskWorkStore(options: CreateTaskWorkStoreOptions): TaskWorkStore {\n  const { driver, now, stores, workflows, update, restore } = options;\n  function parseTask(value: unknown): Task {\n    const task = taskSchema.parse(value);\n    workflows.validateStoredInput(task.work.workflow, task.work.input);\n    if (task.workResult) workflows.validateStoredOutput(task.work.workflow, task.workResult.output);\n    return task;\n  }\n  async function read(id: TaskId) {\n    const record = await driver.get(\"tasks\", id);\n    if (!record) throw new RecordNotFoundError(\"tasks\", id);\n    const task = parseTask(record.value);\n    if (task.id !== id) throw new Error(`Task ${id} does not match its storage key`);\n    return { task, version: record.version, work: task.work };\n  }\n  async function recover(rootTaskId: TaskId): Promise<readonly Task[]> {\n    const graph = await stores().graphs.get(rootTaskId);\n    if (!graph) throw new RecordNotFoundError(\"taskGraphs\", rootTaskId);\n    const tasks: Task[] = [];\n    for (const node of graph.nodes) {\n      const admission = parseTask(node.admission);\n      const existing = await stores().tasks.get(node.taskId);\n      const task = parseTask(existing ?? (await restore(admission)));\n      assertTaskAdmission({ task, admission });\n      tasks.push(task);\n    }\n    return tasks;\n  }\n  function assertAttempt(task: Task, expectAttempt: number) {\n    z.number().int().positive().parse(expectAttempt);\n    if (task.attempt !== expectAttempt)\n      throw new Error(`Task ${task.id} is on attempt ${task.attempt}, not ${expectAttempt}`);\n  }\n  async function setWaiting(\n    id: TaskId,\n    expectAttempt: number,\n    waiting: boolean,\n    phase?: string,\n  ): Promise<Task> {\n    for (;;) {\n      const { task, version } = await read(id);\n      assertAttempt(task, expectAttempt);\n      if (task.state !== \"running\")\n        throw new Error(`Task ${id} must be running to ${waiting ? \"wait\" : \"resume\"}`);\n      const next = taskSchema.parse({\n        ...task,\n        waitingForMessages: waiting,\n        workflowPhase: phase ?? task.workflowPhase,\n        lastProgressAt: waiting ? task.lastProgressAt : now(),\n        updatedAt: now(),\n      });\n      if (task.waitingForMessages === waiting && next.workflowPhase === task.workflowPhase)\n        return task;\n      await stores().receipts.append({\n        taskId: id,\n        repositoryIds: task.repositoryIds,\n        kind: task.kind,\n        state: waiting ? \"waiting\" : \"resumed\",\n        phase: \"workflow\",\n        attempt: task.attempt,\n        reason: waiting\n          ? \"Workflow is waiting for Task messages\"\n          : \"Workflow resumed message processing\",\n        dedupeKey: `work:${id}:${version}:${waiting ? \"wait\" : \"resume\"}`,\n      });\n      try {\n        await update(next, version);\n        return next;\n      } catch (error) {\n        if (!(error instanceof VersionConflictError)) throw error;\n      }\n    }\n  }\n  async function complete(\n    input: CompleteTaskWorkInput,\n    expectedWorkflow?: WorkflowBinding,\n  ): Promise<Task> {\n    const {\n      task: { taskId: id, attempt: expectAttempt },\n      output: value,\n    } = input;\n    for (;;) {\n      const { task, work } = await read(id);\n      assertAttempt(task, expectAttempt);\n      if (expectedWorkflow !== undefined && !isDeepStrictEqual(work.workflow, expectedWorkflow)) {\n        throw new Error(\n          `Task ${id} uses workflow ${work.workflow.id}@${work.workflow.version}, not ${expectedWorkflow.id}@${expectedWorkflow.version}`,\n        );\n      }\n      if (task.state === \"succeeded\") {\n        const output = workflows.validateOutput(work.workflow, value);\n        if (!isDeepStrictEqual(task.workResult?.output, output)) {\n          throw new Error(`Task ${id} already recorded a different workflow output`);\n        }\n        return task;\n      }\n      try {\n        return await stores().tasks.transition(id, \"succeeded\", {\n          output: value,\n          expectAttempt,\n          expectFrom: task.state,\n          phase: \"workflow\",\n        });\n      } catch (error) {\n        if (error instanceof VersionConflictError) continue;\n        if (error instanceof InvalidTransitionError && (await read(id)).task.state === \"succeeded\")\n          continue;\n        throw error;\n      }\n    }\n  }\n  return {\n    complete,\n    completeWorkflow: ({ task, workflow, output }) => complete({ task, output }, workflow),\n    waitForMessages: ({ task: { taskId, attempt }, phase }) =>\n      setWaiting(taskId, attempt, true, phase),\n    resume: ({ task: { taskId, attempt } }) => setWaiting(taskId, attempt, false),\n    recover,\n    async usage(rootTaskId) {\n      const tasks = await recover(rootTaskId);\n      let micros = 0;\n      let inputTokens = 0;\n      let outputTokens = 0;\n      for (const task of tasks) {\n        micros += Math.round((task.usage?.costUsd ?? task.settledUsd ?? 0) * 1_000_000);\n        inputTokens += task.usage?.inputTokens ?? 0;\n        outputTokens += task.usage?.outputTokens ?? 0;\n      }\n      return { costUsd: micros / 1_000_000, inputTokens, outputTokens, taskCount: tasks.length };\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/store/work-notifications.d.mts

@@ -0,0 +1,19 @@
+import "../schema/task.mjs";
+import { z } from "zod";
+//#region src/store/work-notifications.d.ts
+/** Validates a stable wakeup that addresses canonical work by root graph. */
+declare const workNotificationSchema: z.ZodObject<{
+  rootTaskId: z.ZodType<`task_${string}`, string, z.core.$ZodTypeInternals<`task_${string}`, string>>;
+  key: z.ZodString;
+}, z.core.$strict>;
+/** Retry-safe notification telling a consumer to reread one canonical Task graph. */
+type WorkNotification = z.infer<typeof workNotificationSchema>;
+/** Application transport for post-commit work wakeups and delivery-failure reporting. */
+interface WorkNotifications {
+  publish(event: WorkNotification): Promise<void>;
+  /** The source write already committed. Report transport failure without pretending it rolled back. */
+  onError(error: unknown, event: WorkNotification): void;
+}
+//#endregion
+export { WorkNotification, WorkNotifications, workNotificationSchema };
+//# sourceMappingURL=work-notifications.d.mts.map

package/dist/store/work-notifications.mjs

@@ -0,0 +1,48 @@
+import { taskIdSchema } from "../schema/id.mjs";
+import { z } from "zod";
+import { isDeepStrictEqual } from "node:util";
+//#region src/store/work-notifications.ts
+/** Validates a stable wakeup that addresses canonical work by root graph. */
+const workNotificationSchema = z.strictObject({
+	rootTaskId: taskIdSchema.describe("Canonical graph to reconcile; never an execution authorization."),
+	key: z.string().min(1).max(256).describe("Stable identity of the committed source change.")
+}).describe("Durable work wakeup. Consumers reread canonical state and tolerate duplicate delivery.");
+/** Creates a best-effort post-commit notifier whose failures never roll back source writes. */
+function createWorkNotifier(options) {
+	async function publish(event) {
+		if (!options) return;
+		try {
+			await options.publish(event);
+		} catch (error) {
+			try {
+				options.onError(error, event);
+			} catch {}
+		}
+	}
+	function schedulingState(task) {
+		return [
+			task.state,
+			task.attempt,
+			task.approval,
+			task.waitingForMessages,
+			task.workflowPhase,
+			task.changeId,
+			task.questionTaskId,
+			task.answerEventIds
+		];
+	}
+	return {
+		publish,
+		async task(task, previous, version) {
+			if (previous && isDeepStrictEqual(schedulingState(task), schedulingState(previous))) return;
+			await publish({
+				rootTaskId: task.rootTaskId,
+				key: `task:${task.id}:${version}`
+			});
+		}
+	};
+}
+//#endregion
+export { createWorkNotifier, workNotificationSchema };
+
+//# sourceMappingURL=work-notifications.mjs.map

package/dist/store/work-notifications.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"work-notifications.mjs","names":[],"sources":["../../src/store/work-notifications.ts"],"sourcesContent":["import { isDeepStrictEqual } from \"node:util\";\nimport { z } from \"zod\";\nimport { taskIdSchema } from \"../schema/id\";\nimport type { Task } from \"../schema/task\";\n\n/** Validates a stable wakeup that addresses canonical work by root graph. */\nexport const workNotificationSchema = z\n  .strictObject({\n    rootTaskId: taskIdSchema.describe(\n      \"Canonical graph to reconcile; never an execution authorization.\",\n    ),\n    key: z.string().min(1).max(256).describe(\"Stable identity of the committed source change.\"),\n  })\n  .describe(\n    \"Durable work wakeup. Consumers reread canonical state and tolerate duplicate delivery.\",\n  );\n/** Retry-safe notification telling a consumer to reread one canonical Task graph. */\nexport type WorkNotification = z.infer<typeof workNotificationSchema>;\n/** Application transport for post-commit work wakeups and delivery-failure reporting. */\nexport interface WorkNotifications {\n  publish(event: WorkNotification): Promise<void>;\n  /** The source write already committed. Report transport failure without pretending it rolled back. */\n  onError(error: unknown, event: WorkNotification): void;\n}\n\n/** Creates a best-effort post-commit notifier whose failures never roll back source writes. */\nexport function createWorkNotifier(options?: WorkNotifications) {\n  async function publish(event: WorkNotification): Promise<void> {\n    if (!options) return;\n    try {\n      await options.publish(event);\n    } catch (error) {\n      // Reporting must not turn a committed CAS write into an apparent write failure.\n      try {\n        options.onError(error, event);\n      } catch {\n        /* Recovery rediscovers canonical work. */\n      }\n    }\n  }\n  function schedulingState(task: Task) {\n    return [\n      task.state,\n      task.attempt,\n      task.approval,\n      task.waitingForMessages,\n      task.workflowPhase,\n      task.changeId,\n      task.questionTaskId,\n      task.answerEventIds,\n    ];\n  }\n  return {\n    publish,\n    async task(task: Task, previous: Task | null, version: number) {\n      if (previous && isDeepStrictEqual(schedulingState(task), schedulingState(previous))) return;\n      await publish({ rootTaskId: task.rootTaskId, key: `task:${task.id}:${version}` });\n    },\n  };\n}\n"],"mappings":";;;;;AAMA,MAAa,yBAAyB,EACnC,aAAa;CACZ,YAAY,aAAa,SACvB,iEACF;CACA,KAAK,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,SAAS,iDAAiD;AAC5F,CAAC,CAAC,CACD,SACC,wFACF;;AAWF,SAAgB,mBAAmB,SAA6B;CAC9D,eAAe,QAAQ,OAAwC;EAC7D,IAAI,CAAC,SAAS;EACd,IAAI;GACF,MAAM,QAAQ,QAAQ,KAAK;EAC7B,SAAS,OAAO;GAEd,IAAI;IACF,QAAQ,QAAQ,OAAO,KAAK;GAC9B,QAAQ,CAER;EACF;CACF;CACA,SAAS,gBAAgB,MAAY;EACnC,OAAO;GACL,KAAK;GACL,KAAK;GACL,KAAK;GACL,KAAK;GACL,KAAK;GACL,KAAK;GACL,KAAK;GACL,KAAK;EACP;CACF;CACA,OAAO;EACL;EACA,MAAM,KAAK,MAAY,UAAuB,SAAiB;GAC7D,IAAI,YAAY,kBAAkB,gBAAgB,IAAI,GAAG,gBAAgB,QAAQ,CAAC,GAAG;GACrF,MAAM,QAAQ;IAAE,YAAY,KAAK;IAAY,KAAK,QAAQ,KAAK,GAAG,GAAG;GAAU,CAAC;EAClF;CACF;AACF"}

package/dist/sweep.d.mts

@@ -0,0 +1,57 @@
+import { TaskId } from "./schema/id.mjs";
+import { Repository } from "./schema/repository.mjs";
+import { ExecutionReference, Task } from "./schema/task.mjs";
+import { AgentRouteKey } from "./agent-routes.mjs";
+import { FactoryStores } from "./store/engine.mjs";
+import { DispatchBudget, DispatchRefusalCode } from "./dispatch.mjs";
+//#region src/sweep.d.ts
+/** Graph, receipt, repository, and Task capabilities required by queued-work dispatch. */
+type SweepQueuedStores = Pick<FactoryStores, "graphs" | "receipts" | "repositories" | "tasks">;
+/**
+ * Single-repository adapter for an exact agent route. Supplied by the app, which knows its
+ * agents' addresses. Returns the provider's execution reference when it has one.
+ */
+type TaskLauncher = (task: Task, repository: Repository) => Promise<ExecutionReference>;
+/** Exact-route launchers, budget gate, and pass bounds for queued Task dispatch. */
+interface SweepQueuedOptions {
+  /** Single-repository agent adapters keyed by routeKey(binding), e.g. code-change@1. */
+  launchers: Readonly<Partial<Record<AgentRouteKey, TaskLauncher>>>;
+  /** Reserve-before-execution limits, passed through to every dispatch. */
+  budget?: DispatchBudget;
+  /** Maximum task launches attempted in one pass; omitted means no limit. */
+  maxDispatches?: number;
+  /** A dispatcher-wide snapshot avoids another complete task read. */
+  tasks?: readonly Task[];
+}
+/** Tasks dispatched, deferred by a gate, or failed by one queued-work pass. */
+interface SweepQueuedResult {
+  readonly dispatched: readonly TaskId[];
+  /** Tasks left in the queue because a declared gate may become eligible later. */
+  readonly skipped: readonly {
+    readonly taskId: TaskId;
+    readonly reasonCode: SweepSkipReasonCode;
+    readonly reason: string;
+  }[];
+  /** Tasks whose routing is invalid or whose launch threw. */
+  readonly failed: readonly {
+    readonly taskId: TaskId;
+    readonly reasonCode: SweepFailureReasonCode;
+    readonly reason: string;
+  }[];
+}
+/** Stable reason a queued Task remained eligible for a later dispatch pass. */
+type SweepSkipReasonCode = DispatchRefusalCode | "workflow_owned" | "awaiting_approval" | "dispatch_limit" | "task_changed";
+/** Stable reason a queued Task could not be routed or launched. */
+type SweepFailureReasonCode = "invalid_repository_scope" | "repository_not_found" | "launcher_not_registered" | "launch_failed";
+/**
+ * One pass of the factory's dispatcher, meant to run on a schedule inside the
+ * deployment: every queued task that is allowed to run is started, in
+ * creation order. Nothing outside the factory ever starts an agent; the CLI
+ * only writes tasks and approvals, and this picks them up.
+ * Idempotent by construction: dispatchTask's single-winner transition means
+ * two overlapping sweeps cannot start the same task twice.
+ */
+declare function sweepQueued(stores: SweepQueuedStores, options: SweepQueuedOptions): Promise<SweepQueuedResult>;
+//#endregion
+export { SweepFailureReasonCode, SweepQueuedOptions, SweepQueuedResult, SweepQueuedStores, SweepSkipReasonCode, TaskLauncher, sweepQueued };
+//# sourceMappingURL=sweep.d.mts.map

package/dist/sweep.mjs

@@ -0,0 +1,143 @@
+import { InvalidTransitionError } from "./schema/transitions.mjs";
+import { routeKey } from "./agent-routes.mjs";
+import { VersionConflictError } from "./store/driver.mjs";
+import { DispatchRefusedError, dispatchTask } from "./dispatch.mjs";
+//#region src/sweep.ts
+async function failUnrouteable(stores, task, reasonCode, reason, result) {
+	try {
+		await stores.tasks.transition(task.id, "failed", {
+			reason,
+			expectFrom: "queued"
+		});
+		result.failed.push({
+			taskId: task.id,
+			reasonCode,
+			reason
+		});
+	} catch (error) {
+		if (error instanceof InvalidTransitionError || error instanceof VersionConflictError) {
+			result.skipped.push({
+				taskId: task.id,
+				reasonCode: "task_changed",
+				reason: "task changed during routing"
+			});
+			return;
+		}
+		throw error;
+	}
+}
+/**
+* One pass of the factory's dispatcher, meant to run on a schedule inside the
+* deployment: every queued task that is allowed to run is started, in
+* creation order. Nothing outside the factory ever starts an agent; the CLI
+* only writes tasks and approvals, and this picks them up.
+* Idempotent by construction: dispatchTask's single-winner transition means
+* two overlapping sweeps cannot start the same task twice.
+*/
+async function sweepQueued(stores, options) {
+	const result = {
+		dispatched: [],
+		skipped: [],
+		failed: []
+	};
+	const maxDispatches = options.maxDispatches ?? Number.POSITIVE_INFINITY;
+	if (!(Number.isInteger(maxDispatches) || maxDispatches === Number.POSITIVE_INFINITY) || maxDispatches < 1) throw new Error("maxDispatches must be a positive integer");
+	let attempted = 0;
+	const taskSnapshot = options.tasks ?? await stores.tasks.list();
+	const budgetSnapshot = options.budget?.tasks ?? (options.budget && options.tasks ? await stores.tasks.list() : taskSnapshot);
+	const budgetTasks = new Map(budgetSnapshot.map((task) => [task.id, task]));
+	const queued = taskSnapshot.filter((task) => task.state === "queued").sort((a, b) => b.attempt - a.attempt || a.createdAt.localeCompare(b.createdAt));
+	for (const task of queued) {
+		const route = task.work.route;
+		if (route === void 0) {
+			result.skipped.push({
+				taskId: task.id,
+				reasonCode: "workflow_owned",
+				reason: "no agent route; workflow owns execution"
+			});
+			continue;
+		}
+		const [repositoryId] = task.repositoryIds;
+		if (task.repositoryIds.length !== 1 || repositoryId === void 0) {
+			await failUnrouteable(stores, task, "invalid_repository_scope", "sweep launcher adapter requires exactly one repository", result);
+			continue;
+		}
+		if (task.approval === "required") {
+			result.skipped.push({
+				taskId: task.id,
+				reasonCode: "awaiting_approval",
+				reason: "awaiting human approval"
+			});
+			continue;
+		}
+		const key = routeKey(route);
+		const launcher = Object.hasOwn(options.launchers, key) ? options.launchers[key] : void 0;
+		if (launcher === void 0) {
+			await failUnrouteable(stores, task, "launcher_not_registered", `no registered launcher handles agent route ${key}`, result);
+			continue;
+		}
+		if (!await stores.graphs.dependenciesSatisfied({
+			rootTaskId: task.rootTaskId,
+			taskId: task.id
+		})) {
+			result.skipped.push({
+				taskId: task.id,
+				reasonCode: "dependencies_unsatisfied",
+				reason: "graph dependencies must all be succeeded before dispatch"
+			});
+			continue;
+		}
+		if (attempted >= maxDispatches) {
+			result.skipped.push({
+				taskId: task.id,
+				reasonCode: "dispatch_limit",
+				reason: "per-sweep dispatch limit reached"
+			});
+			continue;
+		}
+		const repository = await stores.repositories.get(repositoryId);
+		if (repository === null) {
+			await failUnrouteable(stores, task, "repository_not_found", "task has no repository", result);
+			continue;
+		}
+		try {
+			const dispatched = await dispatchTask(stores, {
+				taskId: task.id,
+				route,
+				launch: (dispatched) => {
+					attempted += 1;
+					return launcher(dispatched, repository);
+				},
+				budget: options.budget === void 0 ? void 0 : {
+					...options.budget,
+					tasks: [...budgetTasks.values()]
+				}
+			});
+			budgetTasks.set(dispatched.id, dispatched);
+			result.dispatched.push(task.id);
+		} catch (error) {
+			if (options.budget !== void 0) {
+				const current = await stores.tasks.get(task.id).catch(() => null);
+				if (current !== null) budgetTasks.set(current.id, current);
+			}
+			if (error instanceof DispatchRefusedError) {
+				result.skipped.push({
+					taskId: task.id,
+					reasonCode: error.code,
+					reason: error.reason
+				});
+				continue;
+			}
+			result.failed.push({
+				taskId: task.id,
+				reasonCode: "launch_failed",
+				reason: error instanceof Error ? error.message : String(error)
+			});
+		}
+	}
+	return result;
+}
+//#endregion
+export { sweepQueued };
+
+//# sourceMappingURL=sweep.mjs.map

package/dist/sweep.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"sweep.mjs","names":[],"sources":["../src/sweep.ts"],"sourcesContent":["import { routeKey, type AgentRouteKey } from \"./agent-routes\";\nimport { dispatchTask, DispatchRefusedError, type DispatchBudget } from \"./dispatch\";\nimport type { DispatchRefusalCode } from \"./dispatch\";\nimport type { TaskId } from \"./schema/id\";\nimport type { Repository } from \"./schema/repository\";\nimport type { ExecutionReference, Task } from \"./schema/task\";\nimport { InvalidTransitionError } from \"./schema/transitions\";\nimport { VersionConflictError } from \"./store/driver\";\nimport type { FactoryStores } from \"./store/engine\";\n\n/** Graph, receipt, repository, and Task capabilities required by queued-work dispatch. */\nexport type SweepQueuedStores = Pick<\n  FactoryStores,\n  \"graphs\" | \"receipts\" | \"repositories\" | \"tasks\"\n>;\n\n/**\n * Single-repository adapter for an exact agent route. Supplied by the app, which knows its\n * agents' addresses. Returns the provider's execution reference when it has one.\n */\nexport type TaskLauncher = (task: Task, repository: Repository) => Promise<ExecutionReference>;\n\n/** Exact-route launchers, budget gate, and pass bounds for queued Task dispatch. */\nexport interface SweepQueuedOptions {\n  /** Single-repository agent adapters keyed by routeKey(binding), e.g. code-change@1. */\n  launchers: Readonly<Partial<Record<AgentRouteKey, TaskLauncher>>>;\n  /** Reserve-before-execution limits, passed through to every dispatch. */\n  budget?: DispatchBudget;\n  /** Maximum task launches attempted in one pass; omitted means no limit. */\n  maxDispatches?: number;\n  /** A dispatcher-wide snapshot avoids another complete task read. */\n  tasks?: readonly Task[];\n}\n\n/** Tasks dispatched, deferred by a gate, or failed by one queued-work pass. */\nexport interface SweepQueuedResult {\n  readonly dispatched: readonly TaskId[];\n  /** Tasks left in the queue because a declared gate may become eligible later. */\n  readonly skipped: readonly {\n    readonly taskId: TaskId;\n    readonly reasonCode: SweepSkipReasonCode;\n    readonly reason: string;\n  }[];\n  /** Tasks whose routing is invalid or whose launch threw. */\n  readonly failed: readonly {\n    readonly taskId: TaskId;\n    readonly reasonCode: SweepFailureReasonCode;\n    readonly reason: string;\n  }[];\n}\n\n/** Stable reason a queued Task remained eligible for a later dispatch pass. */\nexport type SweepSkipReasonCode =\n  | DispatchRefusalCode\n  | \"workflow_owned\"\n  | \"awaiting_approval\"\n  | \"dispatch_limit\"\n  | \"task_changed\";\n\n/** Stable reason a queued Task could not be routed or launched. */\nexport type SweepFailureReasonCode =\n  | \"invalid_repository_scope\"\n  | \"repository_not_found\"\n  | \"launcher_not_registered\"\n  | \"launch_failed\";\n\ntype MutableSweepQueuedResult = {\n  dispatched: TaskId[];\n  skipped: { taskId: TaskId; reasonCode: SweepSkipReasonCode; reason: string }[];\n  failed: { taskId: TaskId; reasonCode: SweepFailureReasonCode; reason: string }[];\n};\n\nasync function failUnrouteable(\n  stores: SweepQueuedStores,\n  task: Task,\n  reasonCode: SweepFailureReasonCode,\n  reason: string,\n  result: MutableSweepQueuedResult,\n): Promise<void> {\n  try {\n    await stores.tasks.transition(task.id, \"failed\", { reason, expectFrom: \"queued\" });\n    result.failed.push({ taskId: task.id, reasonCode, reason });\n  } catch (error) {\n    if (error instanceof InvalidTransitionError || error instanceof VersionConflictError) {\n      result.skipped.push({\n        taskId: task.id,\n        reasonCode: \"task_changed\",\n        reason: \"task changed during routing\",\n      });\n      return;\n    }\n    throw error;\n  }\n}\n\n/**\n * One pass of the factory's dispatcher, meant to run on a schedule inside the\n * deployment: every queued task that is allowed to run is started, in\n * creation order. Nothing outside the factory ever starts an agent; the CLI\n * only writes tasks and approvals, and this picks them up.\n * Idempotent by construction: dispatchTask's single-winner transition means\n * two overlapping sweeps cannot start the same task twice.\n */\nexport async function sweepQueued(\n  stores: SweepQueuedStores,\n  options: SweepQueuedOptions,\n): Promise<SweepQueuedResult> {\n  const result: MutableSweepQueuedResult = { dispatched: [], skipped: [], failed: [] };\n  const maxDispatches = options.maxDispatches ?? Number.POSITIVE_INFINITY;\n  if (\n    !(Number.isInteger(maxDispatches) || maxDispatches === Number.POSITIVE_INFINITY) ||\n    maxDispatches < 1\n  ) {\n    throw new Error(\"maxDispatches must be a positive integer\");\n  }\n  let attempted = 0;\n  const taskSnapshot = options.tasks ?? (await stores.tasks.list());\n  const budgetSnapshot =\n    options.budget?.tasks ??\n    (options.budget && options.tasks ? await stores.tasks.list() : taskSnapshot);\n  const budgetTasks = new Map(budgetSnapshot.map((task) => [task.id, task]));\n  const queued = taskSnapshot\n    .filter((task) => task.state === \"queued\")\n    .sort((a, b) => b.attempt - a.attempt || a.createdAt.localeCompare(b.createdAt));\n\n  for (const task of queued) {\n    const route = task.work.route;\n    if (route === undefined) {\n      result.skipped.push({\n        taskId: task.id,\n        reasonCode: \"workflow_owned\",\n        reason: \"no agent route; workflow owns execution\",\n      });\n      continue;\n    }\n    const [repositoryId] = task.repositoryIds;\n    if (task.repositoryIds.length !== 1 || repositoryId === undefined) {\n      await failUnrouteable(\n        stores,\n        task,\n        \"invalid_repository_scope\",\n        \"sweep launcher adapter requires exactly one repository\",\n        result,\n      );\n      continue;\n    }\n    if (task.approval === \"required\") {\n      result.skipped.push({\n        taskId: task.id,\n        reasonCode: \"awaiting_approval\",\n        reason: \"awaiting human approval\",\n      });\n      continue;\n    }\n    const key = routeKey(route);\n    const launcher = Object.hasOwn(options.launchers, key) ? options.launchers[key] : undefined;\n    if (launcher === undefined) {\n      await failUnrouteable(\n        stores,\n        task,\n        \"launcher_not_registered\",\n        `no registered launcher handles agent route ${key}`,\n        result,\n      );\n      continue;\n    }\n    if (\n      !(await stores.graphs.dependenciesSatisfied({\n        rootTaskId: task.rootTaskId,\n        taskId: task.id,\n      }))\n    ) {\n      result.skipped.push({\n        taskId: task.id,\n        reasonCode: \"dependencies_unsatisfied\",\n        reason: \"graph dependencies must all be succeeded before dispatch\",\n      });\n      continue;\n    }\n    if (attempted >= maxDispatches) {\n      result.skipped.push({\n        taskId: task.id,\n        reasonCode: \"dispatch_limit\",\n        reason: \"per-sweep dispatch limit reached\",\n      });\n      continue;\n    }\n    const repository = await stores.repositories.get(repositoryId);\n    if (repository === null) {\n      await failUnrouteable(stores, task, \"repository_not_found\", \"task has no repository\", result);\n      continue;\n    }\n    try {\n      const dispatched = await dispatchTask(stores, {\n        taskId: task.id,\n        route,\n        launch: (dispatched) => {\n          attempted += 1;\n          return launcher(dispatched, repository);\n        },\n        budget:\n          options.budget === undefined\n            ? undefined\n            : { ...options.budget, tasks: [...budgetTasks.values()] },\n      });\n      budgetTasks.set(dispatched.id, dispatched);\n      result.dispatched.push(task.id);\n    } catch (error) {\n      if (options.budget !== undefined) {\n        const current = await stores.tasks.get(task.id).catch(() => null);\n        if (current !== null) budgetTasks.set(current.id, current);\n      }\n      if (error instanceof DispatchRefusedError) {\n        // Dependencies not ready, or another sweep won the race. Leave it.\n        result.skipped.push({ taskId: task.id, reasonCode: error.code, reason: error.reason });\n        continue;\n      }\n      result.failed.push({\n        taskId: task.id,\n        reasonCode: \"launch_failed\",\n        reason: error instanceof Error ? error.message : String(error),\n      });\n    }\n  }\n  return result;\n}\n"],"mappings":"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"}

package/dist/task-communication.d.mts

@@ -0,0 +1,35 @@
+import { Task } from "./schema/task.mjs";
+import { MaybePromise } from "./schema/common.mjs";
+import { CommunicationEvent } from "./schema/communication.mjs";
+import { Receipt } from "./schema/receipt.mjs";
+import { FactoryStores } from "./store/engine.mjs";
+//#region src/task-communication.d.ts
+/** Outbox, receipt, and Task capabilities required by communication reconciliation. */
+type TaskCommunicationStores = Pick<FactoryStores, "outbox" | "receipts" | "tasks">;
+/** Number of connector-neutral events newly enqueued during reconciliation. */
+interface TaskCommunicationResult {
+  enqueued: number;
+}
+/** Repairs pending Task communication projections against the durable outbox. */
+type TaskCommunicationReconciler<Stores extends TaskCommunicationStores = TaskCommunicationStores> = (stores: Stores, snapshot?: readonly Task[]) => Promise<TaskCommunicationResult>;
+/** Durable Task and receipt context supplied to a lifecycle event projection. */
+interface TaskLifecycleProjectionInput<Stores extends TaskCommunicationStores = TaskCommunicationStores> {
+  stores: Stores;
+  tasks: readonly Task[];
+  task: Task;
+  receipt: Receipt;
+}
+/** Application policy for projecting durable task state into connector-neutral events. */
+interface TaskCommunicationProjection<Stores extends TaskCommunicationStores = TaskCommunicationStores> {
+  question(task: Task): MaybePromise<readonly CommunicationEvent[]>;
+  lifecycle(input: TaskLifecycleProjectionInput<Stores>): MaybePromise<readonly CommunicationEvent[]>;
+}
+/**
+ * Build the generic durable receipt reconciler around an application's event
+ * projection. Events are acknowledged only after every projected event has
+ * reached the outbox.
+ */
+declare function createTaskCommunicationReconciler<Stores extends TaskCommunicationStores>(projection: TaskCommunicationProjection<Stores>): TaskCommunicationReconciler<Stores>;
+//#endregion
+export { TaskCommunicationProjection, TaskCommunicationReconciler, TaskCommunicationResult, TaskCommunicationStores, TaskLifecycleProjectionInput, createTaskCommunicationReconciler };
+//# sourceMappingURL=task-communication.d.mts.map

package/dist/task-communication.mjs

@@ -0,0 +1,47 @@
+//#region src/task-communication.ts
+/**
+* Build the generic durable receipt reconciler around an application's event
+* projection. Events are acknowledged only after every projected event has
+* reached the outbox.
+*/
+function createTaskCommunicationReconciler(projection) {
+	return async function reconcileTaskCommunications(stores, snapshot) {
+		const tasks = snapshot ?? await stores.tasks.list();
+		let enqueued = 0;
+		for (const task of tasks) {
+			const presentsQuestion = task.question !== void 0;
+			if (presentsQuestion && task.state === "needs_human" && task.needsHumanNotifiedAt !== void 0) await stores.tasks.recordNeedsHumanDelivery(task.id, { attempt: task.attempt });
+			if (presentsQuestion && task.state === "needs_human" && task.needsHumanNotifiedAt === void 0 && !task.pendingCommunicationReceiptIds?.length) for (const event of await projection.question(task)) {
+				await stores.outbox.enqueue(event);
+				enqueued += 1;
+			}
+			for (const receiptId of task.pendingCommunicationReceiptIds ?? []) {
+				const receipt = await stores.receipts.get(receiptId);
+				if (receipt === null || receipt.taskId !== task.id) throw new Error(`Task ${task.id} references missing lifecycle receipt ${receiptId}.`);
+				if (receipt.state === "needs_human" && presentsQuestion) {
+					if (task.state === "needs_human" && task.attempt === receipt.attempt) for (const event of await projection.question(task)) {
+						await stores.outbox.enqueue(event);
+						enqueued += 1;
+					}
+					await stores.tasks.acknowledgeCommunication(task.id, receiptId);
+					continue;
+				}
+				for (const event of await projection.lifecycle({
+					stores,
+					tasks,
+					task,
+					receipt
+				})) {
+					await stores.outbox.enqueue(event);
+					enqueued += 1;
+				}
+				await stores.tasks.acknowledgeCommunication(task.id, receiptId);
+			}
+		}
+		return { enqueued };
+	};
+}
+//#endregion
+export { createTaskCommunicationReconciler };
+
+//# sourceMappingURL=task-communication.mjs.map

package/dist/task-communication.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-communication.mjs","names":[],"sources":["../src/task-communication.ts"],"sourcesContent":["import type { CommunicationEvent } from \"./schema/communication\";\nimport type { MaybePromise } from \"./schema/common\";\nimport type { Receipt } from \"./schema/receipt\";\nimport type { Task } from \"./schema/task\";\nimport type { FactoryStores } from \"./store/engine\";\n\n/** Outbox, receipt, and Task capabilities required by communication reconciliation. */\nexport type TaskCommunicationStores = Pick<FactoryStores, \"outbox\" | \"receipts\" | \"tasks\">;\n\n/** Number of connector-neutral events newly enqueued during reconciliation. */\nexport interface TaskCommunicationResult {\n  enqueued: number;\n}\n\n/** Repairs pending Task communication projections against the durable outbox. */\nexport type TaskCommunicationReconciler<\n  Stores extends TaskCommunicationStores = TaskCommunicationStores,\n> = (stores: Stores, snapshot?: readonly Task[]) => Promise<TaskCommunicationResult>;\n\n/** Durable Task and receipt context supplied to a lifecycle event projection. */\nexport interface TaskLifecycleProjectionInput<\n  Stores extends TaskCommunicationStores = TaskCommunicationStores,\n> {\n  stores: Stores;\n  tasks: readonly Task[];\n  task: Task;\n  receipt: Receipt;\n}\n\n/** Application policy for projecting durable task state into connector-neutral events. */\nexport interface TaskCommunicationProjection<\n  Stores extends TaskCommunicationStores = TaskCommunicationStores,\n> {\n  question(task: Task): MaybePromise<readonly CommunicationEvent[]>;\n  lifecycle(\n    input: TaskLifecycleProjectionInput<Stores>,\n  ): MaybePromise<readonly CommunicationEvent[]>;\n}\n\n/**\n * Build the generic durable receipt reconciler around an application's event\n * projection. Events are acknowledged only after every projected event has\n * reached the outbox.\n */\nexport function createTaskCommunicationReconciler<Stores extends TaskCommunicationStores>(\n  projection: TaskCommunicationProjection<Stores>,\n): TaskCommunicationReconciler<Stores> {\n  return async function reconcileTaskCommunications(\n    stores: Stores,\n    snapshot?: readonly Task[],\n  ): Promise<TaskCommunicationResult> {\n    const tasks = snapshot ?? (await stores.tasks.list());\n    let enqueued = 0;\n    for (const task of tasks) {\n      const presentsQuestion = task.question !== undefined;\n      // A connector may confirm before the parent starts waiting, or before\n      // its delivery stamp is persisted.\n      if (\n        presentsQuestion &&\n        task.state === \"needs_human\" &&\n        task.needsHumanNotifiedAt !== undefined\n      ) {\n        await stores.tasks.recordNeedsHumanDelivery(task.id, { attempt: task.attempt });\n      }\n      if (\n        presentsQuestion &&\n        task.state === \"needs_human\" &&\n        task.needsHumanNotifiedAt === undefined &&\n        !task.pendingCommunicationReceiptIds?.length\n      ) {\n        for (const event of await projection.question(task)) {\n          await stores.outbox.enqueue(event);\n          enqueued += 1;\n        }\n      }\n      for (const receiptId of task.pendingCommunicationReceiptIds ?? []) {\n        const receipt = await stores.receipts.get(receiptId);\n        if (receipt === null || receipt.taskId !== task.id) {\n          throw new Error(`Task ${task.id} references missing lifecycle receipt ${receiptId}.`);\n        }\n        if (receipt.state === \"needs_human\" && presentsQuestion) {\n          if (task.state === \"needs_human\" && task.attempt === receipt.attempt) {\n            for (const event of await projection.question(task)) {\n              await stores.outbox.enqueue(event);\n              enqueued += 1;\n            }\n          }\n          await stores.tasks.acknowledgeCommunication(task.id, receiptId);\n          continue;\n        }\n        for (const event of await projection.lifecycle({ stores, tasks, task, receipt })) {\n          await stores.outbox.enqueue(event);\n          enqueued += 1;\n        }\n        await stores.tasks.acknowledgeCommunication(task.id, receiptId);\n      }\n    }\n    return { enqueued };\n  };\n}\n"],"mappings":";;;;;;AA4CA,SAAgB,kCACd,YACqC;CACrC,OAAO,eAAe,4BACpB,QACA,UACkC;EAClC,MAAM,QAAQ,YAAa,MAAM,OAAO,MAAM,KAAK;EACnD,IAAI,WAAW;EACf,KAAK,MAAM,QAAQ,OAAO;GACxB,MAAM,mBAAmB,KAAK,aAAa,KAAA;GAG3C,IACE,oBACA,KAAK,UAAU,iBACf,KAAK,yBAAyB,KAAA,GAE9B,MAAM,OAAO,MAAM,yBAAyB,KAAK,IAAI,EAAE,SAAS,KAAK,QAAQ,CAAC;GAEhF,IACE,oBACA,KAAK,UAAU,iBACf,KAAK,yBAAyB,KAAA,KAC9B,CAAC,KAAK,gCAAgC,QAEtC,KAAK,MAAM,SAAS,MAAM,WAAW,SAAS,IAAI,GAAG;IACnD,MAAM,OAAO,OAAO,QAAQ,KAAK;IACjC,YAAY;GACd;GAEF,KAAK,MAAM,aAAa,KAAK,kCAAkC,CAAC,GAAG;IACjE,MAAM,UAAU,MAAM,OAAO,SAAS,IAAI,SAAS;IACnD,IAAI,YAAY,QAAQ,QAAQ,WAAW,KAAK,IAC9C,MAAM,IAAI,MAAM,QAAQ,KAAK,GAAG,wCAAwC,UAAU,EAAE;IAEtF,IAAI,QAAQ,UAAU,iBAAiB,kBAAkB;KACvD,IAAI,KAAK,UAAU,iBAAiB,KAAK,YAAY,QAAQ,SAC3D,KAAK,MAAM,SAAS,MAAM,WAAW,SAAS,IAAI,GAAG;MACnD,MAAM,OAAO,OAAO,QAAQ,KAAK;MACjC,YAAY;KACd;KAEF,MAAM,OAAO,MAAM,yBAAyB,KAAK,IAAI,SAAS;KAC9D;IACF;IACA,KAAK,MAAM,SAAS,MAAM,WAAW,UAAU;KAAE;KAAQ;KAAO;KAAM;IAAQ,CAAC,GAAG;KAChF,MAAM,OAAO,OAAO,QAAQ,KAAK;KACjC,YAAY;IACd;IACA,MAAM,OAAO,MAAM,yBAAyB,KAAK,IAAI,SAAS;GAChE;EACF;EACA,OAAO,EAAE,SAAS;CACpB;AACF"}