@vercel/factory 0.0.14 → 0.0.16

package/dist/sweep.mjs

@@ -0,0 +1,171 @@
+import { InvalidTransitionError } from "./schema/transitions.mjs";
+import { routeKey } from "./agent-routes.mjs";
+import { VersionConflictError } from "./store/driver.mjs";
+import { DispatchRefusedError, dispatchTask } from "./dispatch.mjs";
+import { TaskAttemptConflictError } from "./store/engine.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;
+	}
+}
+/**
+* Runs one bounded pass over queued Tasks and dispatches each eligible exact route.
+*
+* @remarks
+* Candidates are ordered by newest attempt first and then creation time. Route-less work remains
+* queued for its workflow owner; unmet dependencies, approvals, and pass limits appear in
+* `skipped`. Invalid repository scope, missing repositories or launchers, and launch failures
+* appear in `failed`, with unrouteable Tasks transitioned to `failed` when this sweep wins the
+* race. A result entry describes this pass rather than guaranteeing the Task's lifecycle state:
+* an ambiguously accepted launch is reported as `launch_failed` while its Task intentionally stays
+* running for recovery. Callers should surface every failure, reread those Tasks before deciding
+* remediation, and schedule another pass for skipped work.
+*
+* Overlapping passes are safe: {@link dispatchTask} atomically admits one winner before invoking a
+* launcher. A supplied `tasks` snapshot bounds reads and candidate selection for this pass; it can
+* become stale, and corresponding races are returned as `task_changed` rather than hidden.
+* `maxDispatches` counts provider launches started during the pass, including launches that later
+* fail, so `dispatched.length` may be smaller than the limit.
+*
+* @param stores - Graph, receipt, repository, and Task stores used during the pass.
+* @param options - Exact-route launchers plus optional budget, Task snapshot, and dispatch limit.
+* @returns IDs dispatched and structured skipped/failed outcomes for every considered candidate.
+* @throws When `maxDispatches` is not a positive integer or an unexpected persistence error occurs.
+* @see The shipped `docs/recipes/retry-recovery.md` recipe for scheduled recovery.
+*/
+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;
+		}
+		let launchStarted = false;
+		try {
+			const dispatched = await dispatchTask(stores, {
+				taskId: task.id,
+				route,
+				launch: (dispatched) => {
+					attempted += 1;
+					launchStarted = true;
+					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;
+			}
+			if (!launchStarted && (error instanceof InvalidTransitionError || error instanceof TaskAttemptConflictError || error instanceof VersionConflictError)) {
+				result.skipped.push({
+					taskId: task.id,
+					reasonCode: "task_changed",
+					reason: "task changed before dispatch"
+				});
+				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 { TaskAttemptConflictError, 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 *\n * @param task - Running Task already admitted by the dispatch gate.\n * @param repository - Exact enabled repository selected from the Task scope.\n * @returns Provider execution reference that dispatch can persist for recovery.\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  /** Task IDs whose provider execution reference was durably recorded. */\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 * Runs one bounded pass over queued Tasks and dispatches each eligible exact route.\n *\n * @remarks\n * Candidates are ordered by newest attempt first and then creation time. Route-less work remains\n * queued for its workflow owner; unmet dependencies, approvals, and pass limits appear in\n * `skipped`. Invalid repository scope, missing repositories or launchers, and launch failures\n * appear in `failed`, with unrouteable Tasks transitioned to `failed` when this sweep wins the\n * race. A result entry describes this pass rather than guaranteeing the Task's lifecycle state:\n * an ambiguously accepted launch is reported as `launch_failed` while its Task intentionally stays\n * running for recovery. Callers should surface every failure, reread those Tasks before deciding\n * remediation, and schedule another pass for skipped work.\n *\n * Overlapping passes are safe: {@link dispatchTask} atomically admits one winner before invoking a\n * launcher. A supplied `tasks` snapshot bounds reads and candidate selection for this pass; it can\n * become stale, and corresponding races are returned as `task_changed` rather than hidden.\n * `maxDispatches` counts provider launches started during the pass, including launches that later\n * fail, so `dispatched.length` may be smaller than the limit.\n *\n * @param stores - Graph, receipt, repository, and Task stores used during the pass.\n * @param options - Exact-route launchers plus optional budget, Task snapshot, and dispatch limit.\n * @returns IDs dispatched and structured skipped/failed outcomes for every considered candidate.\n * @throws When `maxDispatches` is not a positive integer or an unexpected persistence error occurs.\n * @see The shipped `docs/recipes/retry-recovery.md` recipe for scheduled recovery.\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    let launchStarted = false;\n    try {\n      const dispatched = await dispatchTask(stores, {\n        taskId: task.id,\n        route,\n        launch: (dispatched) => {\n          attempted += 1;\n          launchStarted = true;\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      if (\n        !launchStarted &&\n        (error instanceof InvalidTransitionError ||\n          error instanceof TaskAttemptConflictError ||\n          error instanceof VersionConflictError)\n      ) {\n        result.skipped.push({\n          taskId: task.id,\n          reasonCode: \"task_changed\",\n          reason: \"task changed before dispatch\",\n        });\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"}

package/dist/task-graph-view.d.mts

@@ -0,0 +1,267 @@
+import { JsonValue } from "./schema/work.mjs";
+import { Task, TaskKind } from "./schema/task.mjs";
+import "./workflows.mjs";
+import "./tasks.mjs";
+import { z } from "zod";
+//#region src/task-graph-view.d.ts
+declare const taskGraphViewSchema: z.ZodObject<{
+  rootTaskId: z.ZodNullable<z.ZodType<`task_${string}`, string, z.core.$ZodTypeInternals<`task_${string}`, string>>>;
+  currentTaskId: z.ZodOptional<z.ZodNullable<z.ZodType<`task_${string}`, string, z.core.$ZodTypeInternals<`task_${string}`, string>>>>;
+  nodes: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+    task: Omit<z.ZodObject<{
+      schemaVersion: z.ZodLiteral<1>;
+      id: z.ZodType<`task_${string}`, string, z.core.$ZodTypeInternals<`task_${string}`, string>>;
+      repositoryIds: z.ZodReadonly<z.ZodTuple<[z.ZodType<`repo_${string}`, string, z.core.$ZodTypeInternals<`repo_${string}`, string>>], z.ZodType<`repo_${string}`, string, z.core.$ZodTypeInternals<`repo_${string}`, string>>>>;
+      kind: z.ZodType<TaskKind, unknown, z.core.$ZodTypeInternals<TaskKind, unknown>>;
+      model: z.ZodOptional<z.ZodString>;
+      area: z.ZodOptional<z.ZodString>;
+      state: z.ZodEnum<{
+        queued: "queued";
+        running: "running";
+        stalled: "stalled";
+        verifying: "verifying";
+        succeeded: "succeeded";
+        failed: "failed";
+        needs_human: "needs_human";
+        cancelled: "cancelled";
+      }>;
+      approval: z.ZodOptional<z.ZodEnum<{
+        required: "required";
+        granted: "granted";
+        denied: "denied";
+      }>>;
+      origin: z.ZodObject<{
+        signalId: z.ZodOptional<z.ZodType<`sig_${string}`, string, z.core.$ZodTypeInternals<`sig_${string}`, string>>>;
+        operator: z.ZodOptional<z.ZodString>;
+      }, z.core.$strict>;
+      work: z.ZodObject<{
+        title: z.ZodString;
+        input: z.ZodCustom<JsonValue, JsonValue>;
+        completionCriteria: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+        workflow: z.core.$ZodBranded<z.ZodObject<{
+          id: z.ZodString;
+          version: z.ZodNumber;
+        }, z.core.$strict>, "WorkflowBinding", "out">;
+        route: z.ZodOptional<z.core.$ZodBranded<z.ZodObject<{
+          id: z.ZodString;
+          version: z.ZodNumber;
+        }, z.core.$strict>, "AgentRouteBinding", "out">>;
+      }, z.core.$strict>;
+      workResult: z.ZodOptional<z.ZodObject<{
+        output: z.ZodCustom<JsonValue, JsonValue>;
+        completedAt: z.ZodISODateTime;
+      }, z.core.$strict>>;
+      waitingForMessages: z.ZodOptional<z.ZodBoolean>;
+      workflowPhase: z.ZodOptional<z.ZodString>;
+      rootTaskId: z.ZodType<`task_${string}`, string, z.core.$ZodTypeInternals<`task_${string}`, string>>;
+      parentTaskId: z.ZodOptional<z.ZodType<`task_${string}`, string, z.core.$ZodTypeInternals<`task_${string}`, string>>>;
+      parentTaskAttempt: z.ZodOptional<z.ZodNumber>;
+      replyTo: z.ZodObject<{
+        channel: z.ZodString;
+        address: z.ZodString;
+      }, z.core.$strict>;
+      pendingCommunicationReceiptIds: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodType<`rcpt_${string}`, string, z.core.$ZodTypeInternals<`rcpt_${string}`, string>>>>>;
+      failureReceiptId: z.ZodOptional<z.ZodType<`rcpt_${string}`, string, z.core.$ZodTypeInternals<`rcpt_${string}`, string>>>;
+      attempt: z.ZodNumber;
+      execution: z.ZodOptional<z.ZodObject<{
+        provider: z.ZodString;
+        sessionId: z.ZodString;
+        environmentId: z.ZodOptional<z.ZodString>;
+        harness: z.ZodOptional<z.ZodString>;
+        traceId: z.ZodOptional<z.ZodString>;
+      }, z.core.$strict>>;
+      lastProgressAt: z.ZodOptional<z.ZodISODateTime>;
+      stalledAt: z.ZodOptional<z.ZodISODateTime>;
+      stalledReason: z.ZodOptional<z.ZodString>;
+      needsHumanAction: z.ZodOptional<z.ZodString>;
+      needsHumanNotifiedAt: z.ZodOptional<z.ZodISODateTime>;
+      reservedUsd: z.ZodOptional<z.ZodNumber>;
+      reservedAt: z.ZodOptional<z.ZodISODateTime>;
+      usage: z.ZodOptional<z.ZodObject<{
+        costUsd: z.ZodNumber;
+        inputTokens: z.ZodNumber;
+        outputTokens: z.ZodNumber;
+        cacheReadTokens: z.ZodNumber;
+        cacheWriteTokens: z.ZodNumber;
+        steps: z.ZodRecord<z.ZodString, z.ZodNumber>;
+      }, z.core.$strict>>;
+      settledUsd: z.ZodOptional<z.ZodNumber>;
+      question: z.ZodOptional<z.ZodObject<{
+        text: z.ZodString;
+        options: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+        closingOptions: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+        answer: z.ZodOptional<z.ZodString>;
+        answeredBy: z.ZodOptional<z.ZodString>;
+      }, z.core.$strict>>;
+      questionTaskId: z.ZodOptional<z.ZodType<`task_${string}`, string, z.core.$ZodTypeInternals<`task_${string}`, string>>>;
+      answerEventIds: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodType<`ans_${string}`, string, z.core.$ZodTypeInternals<`ans_${string}`, string>>>>>;
+      changeId: z.ZodOptional<z.ZodType<`chg_${string}`, string, z.core.$ZodTypeInternals<`chg_${string}`, string>>>;
+      reportRef: z.ZodOptional<z.ZodString>;
+      createdAt: z.ZodISODateTime;
+      updatedAt: z.ZodISODateTime;
+    }, z.core.$strict>, keyof z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>> & z.ZodType<Task, {
+      schemaVersion: 1;
+      id: string;
+      repositoryIds: readonly [string, ...string[]];
+      kind: unknown;
+      state: "queued" | "running" | "stalled" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
+      origin: {
+        signalId?: string | undefined;
+        operator?: string | undefined;
+      };
+      work: {
+        title: string;
+        input: JsonValue;
+        completionCriteria: readonly string[];
+        workflow: {
+          id: string;
+          version: number;
+        };
+        route?: {
+          id: string;
+          version: number;
+        } | undefined;
+      };
+      rootTaskId: string;
+      replyTo: {
+        channel: string;
+        address: string;
+      };
+      attempt: number;
+      createdAt: string;
+      updatedAt: string;
+      model?: string | undefined;
+      area?: string | undefined;
+      approval?: "required" | "granted" | "denied" | undefined;
+      workResult?: {
+        output: JsonValue;
+        completedAt: string;
+      } | undefined;
+      waitingForMessages?: boolean | undefined;
+      workflowPhase?: string | undefined;
+      parentTaskId?: string | undefined;
+      parentTaskAttempt?: number | undefined;
+      pendingCommunicationReceiptIds?: readonly string[] | undefined;
+      failureReceiptId?: string | undefined;
+      execution?: {
+        provider: string;
+        sessionId: string;
+        environmentId?: string | undefined;
+        harness?: string | undefined;
+        traceId?: string | undefined;
+      } | undefined;
+      lastProgressAt?: string | undefined;
+      stalledAt?: string | undefined;
+      stalledReason?: string | undefined;
+      needsHumanAction?: string | undefined;
+      needsHumanNotifiedAt?: string | undefined;
+      reservedUsd?: number | undefined;
+      reservedAt?: string | undefined;
+      usage?: {
+        costUsd: number;
+        inputTokens: number;
+        outputTokens: number;
+        cacheReadTokens: number;
+        cacheWriteTokens: number;
+        steps: Record<string, number>;
+      } | undefined;
+      settledUsd?: number | undefined;
+      question?: {
+        text: string;
+        options: readonly string[];
+        closingOptions?: readonly string[] | undefined;
+        answer?: string | undefined;
+        answeredBy?: string | undefined;
+      } | undefined;
+      questionTaskId?: string | undefined;
+      answerEventIds?: readonly string[] | undefined;
+      changeId?: string | undefined;
+      reportRef?: string | undefined;
+    }, z.core.$ZodTypeInternals<Task, {
+      schemaVersion: 1;
+      id: string;
+      repositoryIds: readonly [string, ...string[]];
+      kind: unknown;
+      state: "queued" | "running" | "stalled" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
+      origin: {
+        signalId?: string | undefined;
+        operator?: string | undefined;
+      };
+      work: {
+        title: string;
+        input: JsonValue;
+        completionCriteria: readonly string[];
+        workflow: {
+          id: string;
+          version: number;
+        };
+        route?: {
+          id: string;
+          version: number;
+        } | undefined;
+      };
+      rootTaskId: string;
+      replyTo: {
+        channel: string;
+        address: string;
+      };
+      attempt: number;
+      createdAt: string;
+      updatedAt: string;
+      model?: string | undefined;
+      area?: string | undefined;
+      approval?: "required" | "granted" | "denied" | undefined;
+      workResult?: {
+        output: JsonValue;
+        completedAt: string;
+      } | undefined;
+      waitingForMessages?: boolean | undefined;
+      workflowPhase?: string | undefined;
+      parentTaskId?: string | undefined;
+      parentTaskAttempt?: number | undefined;
+      pendingCommunicationReceiptIds?: readonly string[] | undefined;
+      failureReceiptId?: string | undefined;
+      execution?: {
+        provider: string;
+        sessionId: string;
+        environmentId?: string | undefined;
+        harness?: string | undefined;
+        traceId?: string | undefined;
+      } | undefined;
+      lastProgressAt?: string | undefined;
+      stalledAt?: string | undefined;
+      stalledReason?: string | undefined;
+      needsHumanAction?: string | undefined;
+      needsHumanNotifiedAt?: string | undefined;
+      reservedUsd?: number | undefined;
+      reservedAt?: string | undefined;
+      usage?: {
+        costUsd: number;
+        inputTokens: number;
+        outputTokens: number;
+        cacheReadTokens: number;
+        cacheWriteTokens: number;
+        steps: Record<string, number>;
+      } | undefined;
+      settledUsd?: number | undefined;
+      question?: {
+        text: string;
+        options: readonly string[];
+        closingOptions?: readonly string[] | undefined;
+        answer?: string | undefined;
+        answeredBy?: string | undefined;
+      } | undefined;
+      questionTaskId?: string | undefined;
+      answerEventIds?: readonly string[] | undefined;
+      changeId?: string | undefined;
+      reportRef?: string | undefined;
+    }>>;
+    dependencyTaskIds: z.ZodReadonly<z.ZodArray<z.ZodType<`task_${string}`, string, z.core.$ZodTypeInternals<`task_${string}`, string>>>>;
+    agent: z.ZodNullable<z.ZodString>;
+  }, z.core.$strict>>>;
+}, z.core.$strict>;
+/** An authorized, read-only operator projection of one canonical Task graph. */
+type TaskGraphView = z.infer<typeof taskGraphViewSchema>;
+//#endregion
+export { TaskGraphView, taskGraphViewSchema };
+//# sourceMappingURL=task-graph-view.d.mts.map

package/dist/task-graph-view.mjs

@@ -0,0 +1,17 @@
+import { taskIdSchema } from "./schema/id.mjs";
+import { taskSchema } from "./schema/task.mjs";
+import { z } from "zod";
+//#region src/task-graph-view.ts
+const taskGraphViewSchema = z.strictObject({
+	rootTaskId: taskIdSchema.nullable().describe("Canonical root, or null for a taskless conversation."),
+	currentTaskId: taskIdSchema.nullable().optional().describe("Task currently shown by the entrypoint conversation, or null when it is not in this graph."),
+	nodes: z.array(z.strictObject({
+		task: taskSchema.describe("Current persisted Task snapshot."),
+		dependencyTaskIds: z.array(taskIdSchema).max(255).readonly().describe("Canonical prerequisites, distinct from parent ownership."),
+		agent: z.string().nullable().describe("Exact exposed route agent, or null for workflow-owned or unavailable execution.")
+	})).max(256).readonly().describe("Authorized canonical graph membership, independent of session pagination.")
+}).describe("Read-only operator view of one root Task graph.");
+//#endregion
+export { taskGraphViewSchema };
+
+//# sourceMappingURL=task-graph-view.mjs.map

package/dist/task-graph-view.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-graph-view.mjs","names":[],"sources":["../src/task-graph-view.ts"],"sourcesContent":["import { z } from \"zod\";\nimport { taskIdSchema } from \"./schema/id\";\nimport { taskSchema } from \"./schema/task\";\n\nexport const taskGraphViewSchema = z\n  .strictObject({\n    rootTaskId: taskIdSchema\n      .nullable()\n      .describe(\"Canonical root, or null for a taskless conversation.\"),\n    currentTaskId: taskIdSchema\n      .nullable()\n      .optional()\n      .describe(\n        \"Task currently shown by the entrypoint conversation, or null when it is not in this graph.\",\n      ),\n    nodes: z\n      .array(\n        z.strictObject({\n          task: taskSchema.describe(\"Current persisted Task snapshot.\"),\n          dependencyTaskIds: z\n            .array(taskIdSchema)\n            .max(255)\n            .readonly()\n            .describe(\"Canonical prerequisites, distinct from parent ownership.\"),\n          agent: z\n            .string()\n            .nullable()\n            .describe(\n              \"Exact exposed route agent, or null for workflow-owned or unavailable execution.\",\n            ),\n        }),\n      )\n      .max(256)\n      .readonly()\n      .describe(\"Authorized canonical graph membership, independent of session pagination.\"),\n  })\n  .describe(\"Read-only operator view of one root Task graph.\");\n/** An authorized, read-only operator projection of one canonical Task graph. */\nexport type TaskGraphView = z.infer<typeof taskGraphViewSchema>;\n"],"mappings":";;;;AAIA,MAAa,sBAAsB,EAChC,aAAa;CACZ,YAAY,aACT,SAAS,CAAC,CACV,SAAS,sDAAsD;CAClE,eAAe,aACZ,SAAS,CAAC,CACV,SAAS,CAAC,CACV,SACC,4FACF;CACF,OAAO,EACJ,MACC,EAAE,aAAa;EACb,MAAM,WAAW,SAAS,kCAAkC;EAC5D,mBAAmB,EAChB,MAAM,YAAY,CAAC,CACnB,IAAI,GAAG,CAAC,CACR,SAAS,CAAC,CACV,SAAS,0DAA0D;EACtE,OAAO,EACJ,OAAO,CAAC,CACR,SAAS,CAAC,CACV,SACC,iFACF;CACJ,CAAC,CACH,CAAC,CACA,IAAI,GAAG,CAAC,CACR,SAAS,CAAC,CACV,SAAS,2EAA2E;AACzF,CAAC,CAAC,CACD,SAAS,iDAAiD"}

package/dist/task-message-processing.d.mts

@@ -0,0 +1,60 @@
+import { WorkflowBinding } from "./schema/work.mjs";
+import { Task } from "./schema/task.mjs";
+import { TaskMessageForProtocol, TaskMessageId, TaskMessagePrincipal, TaskMessageProtocol } from "./schema/task-message.mjs";
+import { IsoDateTimeClock } from "./schema/common.mjs";
+import { TaskAttemptRef } from "./schema/execution.mjs";
+import { FactoryStores } from "./store/engine.mjs";
+import { z } from "zod";
+//#region src/task-message-processing.d.ts
+/** Minimal persistence capabilities required to decide and apply one Task message. */
+type TaskMessageProcessingStores = Pick<FactoryStores, "messages" | "tasks" | "workflowRecords">;
+/** Trusted dependencies and pure/effectful callbacks for processing one Task inbox head. */
+interface ProcessTaskMessageOptions<Schema extends z.ZodType, Protocol extends TaskMessageProtocol = TaskMessageProtocol> {
+  readonly stores: TaskMessageProcessingStores;
+  /** Authenticated externally; the message store enforces its configured claim policy. */
+  readonly principal: TaskMessagePrincipal;
+  /** Exact recipient Task attempt authorized to process the inbox head. */
+  readonly task: TaskAttemptRef;
+  /** Refuse a different inbox head before deciding or replaying effects. */
+  readonly expectMessageId?: TaskMessageId;
+  readonly leaseMs: number;
+  readonly workflow: WorkflowBinding;
+  /** Exact protocol required for the claimed message and exposed to typed callbacks. */
+  readonly protocol: Protocol;
+  /** Trusted UTC clock for decision timestamps; defaults to the system clock. */
+  readonly now?: IsoDateTimeClock;
+  /** Must accept its canonical JSON output unchanged. Exclude secrets from the decision contract. */
+  readonly decisionSchema: Schema;
+  /** Pure computation: may run concurrently or repeat until a decision is durably inserted. */
+  decide(context: Readonly<{
+    task: Task;
+    message: TaskMessageForProtocol<Protocol>;
+  }>): Promise<z.input<Schema>>;
+  /**
+   * Honor effectKey for every external write (derive stable subkeys for multiple effects).
+   * Lease checks cannot fence external systems: apply may repeat, overlap, or outlive its claim.
+   * Resolve only after all effects commit; never mutate the decision to select different effects.
+   */
+  apply(context: Readonly<{
+    task: Task;
+    message: TaskMessageForProtocol<Protocol>;
+    decision: z.output<Schema>;
+    effectKey: string;
+  }>): Promise<void>;
+}
+/** Result of finding no claimable work or durably processing one Task message. */
+type ProcessTaskMessageResult<Decision> = {
+  status: "idle";
+} | {
+  status: "processed";
+  messageId: TaskMessageId;
+  decision: Decision;
+  effectKey: string;
+};
+/** Authorized typed inspection; null means no committed decision, not permission to decide for a terminal Task. */
+declare function readTaskMessageDecision<Schema extends z.ZodType>(options: Pick<ProcessTaskMessageOptions<Schema>, "stores" | "principal" | "task" | "workflow" | "decisionSchema">, messageId: TaskMessageId): Promise<z.output<Schema> | null>;
+/** Process one authorized inbox head. Idle means empty or already leased, not necessarily drained. */
+declare function processTaskMessage<Schema extends z.ZodType, Protocol extends TaskMessageProtocol = TaskMessageProtocol>(options: ProcessTaskMessageOptions<Schema, Protocol>): Promise<ProcessTaskMessageResult<z.output<Schema>>>;
+//#endregion
+export { ProcessTaskMessageOptions, ProcessTaskMessageResult, TaskMessageProcessingStores, processTaskMessage, readTaskMessageDecision };
+//# sourceMappingURL=task-message-processing.d.mts.map