@vercel/factory 0.0.13 → 0.0.15

package/dist/presets/software-development/dispatch.d.mts

@@ -0,0 +1,53 @@
+import { RepositoryId } from "../../schema/id.mjs";
+import { AgentRouteBinding } from "../../schema/agent-route.mjs";
+import { Task } from "../../schema/task.mjs";
+import "../../agent-routes.mjs";
+import { WorkNotification } from "../../store/work-notifications.mjs";
+import { MillisecondClock } from "../../schema/common.mjs";
+import { FactoryStores } from "../../store/engine.mjs";
+import { DispatchBudget } from "../../dispatch.mjs";
+import { TaskCommunicationReconciler } from "../../task-communication.mjs";
+import { SweepQueuedOptions, SweepQueuedResult } from "../../sweep.mjs";
+import { PlannerReconcileResult } from "../../planning/contracts.mjs";
+import "../../planning/runtime.mjs";
+import { SoftwareDevelopmentTaskCommunicationStores } from "./task-communication.mjs";
+//#region src/presets/software-development/dispatch.d.ts
+/** Factory capabilities composed by the supplied software-development dispatcher. */
+type SoftwareDevelopmentDispatchStores = Pick<FactoryStores, "changes" | "graphs" | "outbox" | "receipts" | "repositories" | "sessions" | "tasks" | "work">;
+/** Application policies and adapters for reconciling one reference-work root graph. */
+interface DispatchSoftwareDevelopmentWorkOptions {
+  /** Durable wakeup identifying the canonical Task graph to reconcile. */
+  readonly event: WorkNotification;
+  /** Provider delivery identity used to deduplicate continuation wakeups. */
+  readonly deliveryId: string;
+  stores: SoftwareDevelopmentDispatchStores;
+  planning: {
+    isPlanner(task: Task): boolean;
+    reconcile(tasks: readonly Task[]): Promise<PlannerReconcileResult>;
+  };
+  launchers: SweepQueuedOptions["launchers"];
+  budget: DispatchBudget;
+  verificationRoute?: AgentRouteBinding;
+  canUseRepository(id: RepositoryId): Promise<boolean>;
+  publish(event: WorkNotification, delaySeconds?: number): Promise<void>;
+  /**
+   * Tasks a workflow owns and reconciles itself. The reference dispatcher skips
+   * them so the two never drive the same execution.
+   */
+  ownedByWorkflow?(tasks: readonly Task[]): readonly Task[];
+  now?: MillisecondClock;
+  retryDelayMs?: number;
+  maxDispatches?: number;
+  plannerBatchSize?: number;
+  /** Application-selected projection from task state to outbound communication. */
+  reconcileCommunications?: TaskCommunicationReconciler<SoftwareDevelopmentTaskCommunicationStores>;
+}
+/** Queued-dispatch and planner reconciliation results for one notified root graph. */
+interface DispatchSoftwareDevelopmentWorkResult extends SweepQueuedResult {
+  readonly planner: PlannerReconcileResult;
+}
+/** Reconcile one notified root graph without scanning or scheduling unrelated work. */
+declare function dispatchSoftwareDevelopmentWork(options: DispatchSoftwareDevelopmentWorkOptions): Promise<DispatchSoftwareDevelopmentWorkResult>;
+//#endregion
+export { DispatchSoftwareDevelopmentWorkOptions, DispatchSoftwareDevelopmentWorkResult, SoftwareDevelopmentDispatchStores, dispatchSoftwareDevelopmentWork };
+//# sourceMappingURL=dispatch.d.mts.map

package/dist/presets/software-development/dispatch.mjs

@@ -0,0 +1,66 @@
+import { sweepSettlements } from "../../budget.mjs";
+import { agentSessionIdSchema } from "../../schema/session.mjs";
+import { sweepQueued } from "../../sweep.mjs";
+import { ensureChangeVerificationTasks } from "../../change-verification/dispatch.mjs";
+import { reconcileMultiRepositoryChangeTasks } from "../../multi-repository-changes/coordination.mjs";
+import { createSoftwareDevelopmentTaskCommunication } from "./task-communication.mjs";
+//#region src/presets/software-development/dispatch.ts
+const defaultReconcileTaskCommunications = createSoftwareDevelopmentTaskCommunication().reconcile;
+/** Reconcile one notified root graph without scanning or scheduling unrelated work. */
+async function dispatchSoftwareDevelopmentWork(options) {
+	const { deliveryId, event, stores, planning } = options;
+	const recover = async () => {
+		const graph = await stores.work.recover(event.rootTaskId);
+		const owned = new Set((options.ownedByWorkflow?.(graph) ?? []).map((task) => task.id));
+		return graph.filter((task) => !owned.has(task.id));
+	};
+	let tasks = await recover();
+	for (const id of new Set(tasks.flatMap((task) => task.repositoryIds))) if (!await options.canUseRepository(id)) throw new Error(`Work repository ${id} is no longer enabled and configured`);
+	for (const task of tasks.filter((task) => task.state === "queued" && task.replyTo.channel === "api")) {
+		const session = await stores.sessions.get(agentSessionIdSchema.parse(task.replyTo.address));
+		if (!session || session.route !== void 0 && session.taskId === void 0 || task.work.route?.id === "conversation" && !session.continuations?.some((entry) => entry.taskId === task.id)) throw new Error(`Task ${task.id} is waiting for its durable API session binding`);
+	}
+	for (const task of tasks) if (task.kind === "coordination" && task.state === "running") await reconcileMultiRepositoryChangeTasks(stores, task.id);
+	if (options.verificationRoute) await ensureChangeVerificationTasks({
+		stores,
+		tasks: await recover(),
+		route: options.verificationRoute
+	});
+	await sweepSettlements(stores, { tasks: await recover() });
+	const planner = await planning.reconcile(await recover());
+	tasks = await recover();
+	const ready = [];
+	const now = (options.now ?? Date.now)();
+	for (const task of tasks.filter((task) => !planning.isPlanner(task))) {
+		const retryAt = Date.parse(task.updatedAt) + (options.retryDelayMs ?? 6e4);
+		if (task.state === "queued" && task.attempt > 1 && retryAt > now) await options.publish({
+			rootTaskId: event.rootTaskId,
+			key: `retry:${task.id}:${task.attempt}`
+		}, Math.ceil((retryAt - now) / 1e3));
+		else ready.push(task);
+	}
+	const result = await sweepQueued(stores, {
+		tasks: ready,
+		launchers: options.launchers,
+		budget: options.budget,
+		maxDispatches: options.maxDispatches ?? 1
+	});
+	await (options.reconcileCommunications ?? defaultReconcileTaskCommunications)(stores, await recover());
+	if (result.skipped.some((entry) => entry.reason === "per-sweep dispatch limit reached") || planner.dispatched.length || planner.delivered >= (options.plannerBatchSize ?? 32) || planner.recovered + planner.discarded >= (options.plannerBatchSize ?? 32)) await options.publish({
+		rootTaskId: event.rootTaskId,
+		key: `continue:${deliveryId}`
+	});
+	if (planner.errors.length || planner.cancellationPending?.length || result.failed.length) throw new Error(`Work reconciliation needs retry: ${JSON.stringify({
+		planner: planner.errors,
+		cancellationPending: planner.cancellationPending,
+		failed: result.failed
+	})}`);
+	return {
+		...result,
+		planner
+	};
+}
+//#endregion
+export { dispatchSoftwareDevelopmentWork };
+
+//# sourceMappingURL=dispatch.mjs.map

package/dist/presets/software-development/dispatch.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.mjs","names":[],"sources":["../../../src/presets/software-development/dispatch.ts"],"sourcesContent":["import { sweepSettlements } from \"../../budget\";\nimport type { AgentRouteBinding } from \"../../agent-routes\";\nimport { ensureChangeVerificationTasks } from \"../../change-verification/dispatch\";\nimport type { DispatchBudget } from \"../../dispatch\";\nimport { reconcileMultiRepositoryChangeTasks } from \"../../multi-repository-changes/coordination\";\nimport type { PlannerReconcileResult } from \"../../planning/runtime\";\nimport type { MillisecondClock } from \"../../schema/common\";\nimport type { RepositoryId } from \"../../schema/id\";\nimport { agentSessionIdSchema } from \"../../schema/session\";\nimport type { Task } from \"../../schema/task\";\nimport type { FactoryStores } from \"../../store/engine\";\nimport type { WorkNotification } from \"../../store/work-notifications\";\nimport { sweepQueued, type SweepQueuedOptions, type SweepQueuedResult } from \"../../sweep\";\nimport type { TaskCommunicationReconciler } from \"../../task-communication\";\nimport {\n  createSoftwareDevelopmentTaskCommunication,\n  type SoftwareDevelopmentTaskCommunicationStores,\n} from \"./task-communication\";\n\nconst defaultReconcileTaskCommunications = createSoftwareDevelopmentTaskCommunication().reconcile;\n\n/** Factory capabilities composed by the supplied software-development dispatcher. */\nexport type SoftwareDevelopmentDispatchStores = Pick<\n  FactoryStores,\n  \"changes\" | \"graphs\" | \"outbox\" | \"receipts\" | \"repositories\" | \"sessions\" | \"tasks\" | \"work\"\n>;\n\n/** Application policies and adapters for reconciling one reference-work root graph. */\nexport interface DispatchSoftwareDevelopmentWorkOptions {\n  /** Durable wakeup identifying the canonical Task graph to reconcile. */\n  readonly event: WorkNotification;\n  /** Provider delivery identity used to deduplicate continuation wakeups. */\n  readonly deliveryId: string;\n  stores: SoftwareDevelopmentDispatchStores;\n  planning: {\n    isPlanner(task: Task): boolean;\n    reconcile(tasks: readonly Task[]): Promise<PlannerReconcileResult>;\n  };\n  launchers: SweepQueuedOptions[\"launchers\"];\n  budget: DispatchBudget;\n  verificationRoute?: AgentRouteBinding;\n  canUseRepository(id: RepositoryId): Promise<boolean>;\n  publish(event: WorkNotification, delaySeconds?: number): Promise<void>;\n  /**\n   * Tasks a workflow owns and reconciles itself. The reference dispatcher skips\n   * them so the two never drive the same execution.\n   */\n  ownedByWorkflow?(tasks: readonly Task[]): readonly Task[];\n  now?: MillisecondClock;\n  retryDelayMs?: number;\n  maxDispatches?: number;\n  plannerBatchSize?: number;\n  /** Application-selected projection from task state to outbound communication. */\n  reconcileCommunications?: TaskCommunicationReconciler<SoftwareDevelopmentTaskCommunicationStores>;\n}\n\n/** Queued-dispatch and planner reconciliation results for one notified root graph. */\nexport interface DispatchSoftwareDevelopmentWorkResult extends SweepQueuedResult {\n  readonly planner: PlannerReconcileResult;\n}\n\n/** Reconcile one notified root graph without scanning or scheduling unrelated work. */\nexport async function dispatchSoftwareDevelopmentWork(\n  options: DispatchSoftwareDevelopmentWorkOptions,\n): Promise<DispatchSoftwareDevelopmentWorkResult> {\n  const { deliveryId, event, stores, planning } = options;\n  const recover = async () => {\n    const graph = await stores.work.recover(event.rootTaskId);\n    const owned = new Set((options.ownedByWorkflow?.(graph) ?? []).map((task) => task.id));\n    return graph.filter((task) => !owned.has(task.id));\n  };\n  let tasks = await recover();\n  for (const id of new Set(tasks.flatMap((task) => task.repositoryIds))) {\n    if (!(await options.canUseRepository(id)))\n      throw new Error(`Work repository ${id} is no longer enabled and configured`);\n  }\n  // Admission may publish before the API finishes binding its session or continuation.\n  for (const task of tasks.filter(\n    (task) => task.state === \"queued\" && task.replyTo.channel === \"api\",\n  )) {\n    const session = await stores.sessions.get(agentSessionIdSchema.parse(task.replyTo.address));\n    if (\n      !session ||\n      (session.route !== undefined && session.taskId === undefined) ||\n      (task.work.route?.id === \"conversation\" &&\n        !session.continuations?.some((entry) => entry.taskId === task.id))\n    ) {\n      throw new Error(`Task ${task.id} is waiting for its durable API session binding`);\n    }\n  }\n  for (const task of tasks) {\n    if (task.kind === \"coordination\" && task.state === \"running\")\n      await reconcileMultiRepositoryChangeTasks(stores, task.id);\n  }\n  if (options.verificationRoute)\n    await ensureChangeVerificationTasks({\n      stores,\n      tasks: await recover(),\n      route: options.verificationRoute,\n    });\n  await sweepSettlements(stores, { tasks: await recover() });\n  const planner = await planning.reconcile(await recover());\n  tasks = await recover();\n  const ready: Task[] = [];\n  const now = (options.now ?? Date.now)();\n  for (const task of tasks.filter((task) => !planning.isPlanner(task))) {\n    const retryAt = Date.parse(task.updatedAt) + (options.retryDelayMs ?? 60_000);\n    if (task.state === \"queued\" && task.attempt > 1 && retryAt > now) {\n      await options.publish(\n        { rootTaskId: event.rootTaskId, key: `retry:${task.id}:${task.attempt}` },\n        Math.ceil((retryAt - now) / 1000),\n      );\n    } else ready.push(task);\n  }\n  const result = await sweepQueued(stores, {\n    tasks: ready,\n    launchers: options.launchers,\n    budget: options.budget,\n    maxDispatches: options.maxDispatches ?? 1,\n  });\n  await (options.reconcileCommunications ?? defaultReconcileTaskCommunications)(\n    stores,\n    await recover(),\n  );\n  // Continue bounded batches through the queue, never through the next recovery interval.\n  if (\n    result.skipped.some((entry) => entry.reason === \"per-sweep dispatch limit reached\") ||\n    planner.dispatched.length ||\n    planner.delivered >= (options.plannerBatchSize ?? 32) ||\n    planner.recovered + planner.discarded >= (options.plannerBatchSize ?? 32)\n  ) {\n    await options.publish({ rootTaskId: event.rootTaskId, key: `continue:${deliveryId}` });\n  }\n  if (planner.errors.length || planner.cancellationPending?.length || result.failed.length) {\n    throw new Error(\n      `Work reconciliation needs retry: ${JSON.stringify({ planner: planner.errors, cancellationPending: planner.cancellationPending, failed: result.failed })}`,\n    );\n  }\n  return { ...result, planner };\n}\n"],"mappings":"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"}

package/dist/presets/software-development/eve-delegation-policy.d.mts

@@ -0,0 +1,7 @@
+import { DelegateWorkflowPolicy } from "../../eve/invoke.mjs";
+//#region src/presets/software-development/eve-delegation-policy.d.ts
+/** Multi-repository code changes are supplied as one coordination tree. */
+declare const softwareDevelopmentDelegationPolicy: DelegateWorkflowPolicy;
+//#endregion
+export { softwareDevelopmentDelegationPolicy };
+//# sourceMappingURL=eve-delegation-policy.d.mts.map

package/dist/presets/software-development/eve-delegation-policy.mjs

@@ -0,0 +1,34 @@
+import { parseAgentRouteBinding } from "../../schema/agent-route.mjs";
+import { createMultiRepositoryChangeTasks } from "../../multi-repository-changes/coordination.mjs";
+//#region src/presets/software-development/eve-delegation-policy.ts
+/** Multi-repository code changes are supplied as one coordination tree. */
+const softwareDevelopmentDelegationPolicy = async ({ stores, route, repositoryIds, signalId, replyTo, operator, dispatch }) => {
+	if (route.taskKind !== "code_change" || repositoryIds.length < 2) return null;
+	const [first, second, ...rest] = repositoryIds;
+	const coordination = await createMultiRepositoryChangeTasks(stores, {
+		repositoryIds: [
+			first,
+			second,
+			...rest
+		],
+		replyTo,
+		childRoute: route,
+		...signalId === void 0 ? {} : { dedupeKey: `route:${signalId}:${route.id}:${route.version}` },
+		...signalId === void 0 ? { operator } : { signalId }
+	});
+	await Promise.all(coordination.children.filter((child) => child.state === "queued").map(dispatch));
+	return {
+		taskId: coordination.parent.id,
+		childTaskIds: coordination.children.map(({ id }) => id),
+		route: parseAgentRouteBinding({
+			id: route.id,
+			version: route.version
+		}),
+		agent: route.agent,
+		state: coordination.parent.state
+	};
+};
+//#endregion
+export { softwareDevelopmentDelegationPolicy };
+
+//# sourceMappingURL=eve-delegation-policy.mjs.map

package/dist/presets/software-development/eve-delegation-policy.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"eve-delegation-policy.mjs","names":[],"sources":["../../../src/presets/software-development/eve-delegation-policy.ts"],"sourcesContent":["import type { DelegateWorkflowPolicy } from \"../../eve/invoke\";\nimport { parseAgentRouteBinding } from \"../../agent-routes\";\nimport { createMultiRepositoryChangeTasks } from \"../../multi-repository-changes/coordination\";\n\n/** Multi-repository code changes are supplied as one coordination tree. */\nexport const softwareDevelopmentDelegationPolicy: DelegateWorkflowPolicy = async ({\n  stores,\n  route,\n  repositoryIds,\n  signalId,\n  replyTo,\n  operator,\n  dispatch,\n}) => {\n  if (route.taskKind !== \"code_change\" || repositoryIds.length < 2) return null;\n  const [first, second, ...rest] = repositoryIds;\n  const coordination = await createMultiRepositoryChangeTasks(stores, {\n    repositoryIds: [first, second, ...rest],\n    replyTo,\n    childRoute: route,\n    ...(signalId === undefined\n      ? {}\n      : { dedupeKey: `route:${signalId}:${route.id}:${route.version}` }),\n    ...(signalId === undefined ? { operator } : { signalId }),\n  });\n  await Promise.all(\n    coordination.children.filter((child) => child.state === \"queued\").map(dispatch),\n  );\n  return {\n    taskId: coordination.parent.id,\n    childTaskIds: coordination.children.map(({ id }) => id),\n    route: parseAgentRouteBinding({ id: route.id, version: route.version }),\n    agent: route.agent,\n    state: coordination.parent.state,\n  };\n};\n"],"mappings":";;;;AAKA,MAAa,sCAA8D,OAAO,EAChF,QACA,OACA,eACA,UACA,SACA,UACA,eACI;CACJ,IAAI,MAAM,aAAa,iBAAiB,cAAc,SAAS,GAAG,OAAO;CACzE,MAAM,CAAC,OAAO,QAAQ,GAAG,QAAQ;CACjC,MAAM,eAAe,MAAM,iCAAiC,QAAQ;EAClE,eAAe;GAAC;GAAO;GAAQ,GAAG;EAAI;EACtC;EACA,YAAY;EACZ,GAAI,aAAa,KAAA,IACb,CAAC,IACD,EAAE,WAAW,SAAS,SAAS,GAAG,MAAM,GAAG,GAAG,MAAM,UAAU;EAClE,GAAI,aAAa,KAAA,IAAY,EAAE,SAAS,IAAI,EAAE,SAAS;CACzD,CAAC;CACD,MAAM,QAAQ,IACZ,aAAa,SAAS,QAAQ,UAAU,MAAM,UAAU,QAAQ,CAAC,CAAC,IAAI,QAAQ,CAChF;CACA,OAAO;EACL,QAAQ,aAAa,OAAO;EAC5B,cAAc,aAAa,SAAS,KAAK,EAAE,SAAS,EAAE;EACtD,OAAO,uBAAuB;GAAE,IAAI,MAAM;GAAI,SAAS,MAAM;EAAQ,CAAC;EACtE,OAAO,MAAM;EACb,OAAO,aAAa,OAAO;CAC7B;AACF"}

package/dist/presets/software-development/eve.d.mts

@@ -0,0 +1,18 @@
+import { FactoryStores } from "../../store/engine.mjs";
+import { RecordChangeTool, RecordChangeToolOptions } from "../../changes/eve-record-change.mjs";
+import { TaskTools, TaskToolsOptions } from "../../eve/index.mjs";
+import { softwareDevelopmentDelegationPolicy } from "./eve-delegation-policy.mjs";
+//#region src/presets/software-development/eve.d.ts
+/** Change, receipt, Signal, and Task capabilities used by the supplied software tool bundle. */
+type SoftwareDevelopmentToolsStores = Pick<FactoryStores, "changes" | "receipts" | "signals" | "tasks">;
+/** Configuration for the generic and software-development tools exposed to an Eve agent. */
+interface SoftwareDevelopmentToolsOptions extends TaskToolsOptions, RecordChangeToolOptions {}
+/** Generic Task tools plus the software workflow's pull-request outcome tool. */
+interface SoftwareDevelopmentTools extends TaskTools {
+  readonly record_change: RecordChangeTool;
+}
+/** Build Eve tools with the software-development completion policy. */
+declare function createSoftwareDevelopmentTools(stores: SoftwareDevelopmentToolsStores, options?: SoftwareDevelopmentToolsOptions): SoftwareDevelopmentTools;
+//#endregion
+export { SoftwareDevelopmentTools, SoftwareDevelopmentToolsOptions, SoftwareDevelopmentToolsStores, createSoftwareDevelopmentTools, softwareDevelopmentDelegationPolicy };
+//# sourceMappingURL=eve.d.mts.map

package/dist/presets/software-development/eve.mjs

@@ -0,0 +1,19 @@
+import { createTaskTools } from "../../eve/index.mjs";
+import { createRecordChangeTool } from "../../changes/eve-record-change.mjs";
+import { softwareDevelopmentFinishTaskPolicy } from "./finish-task-policy.mjs";
+import { softwareDevelopmentDelegationPolicy } from "./eve-delegation-policy.mjs";
+//#region src/presets/software-development/eve.ts
+/** Build Eve tools with the software-development completion policy. */
+function createSoftwareDevelopmentTools(stores, options = {}) {
+	return {
+		...createTaskTools(stores, {
+			...options,
+			finishTaskPolicy: options.finishTaskPolicy ?? softwareDevelopmentFinishTaskPolicy
+		}),
+		record_change: createRecordChangeTool(stores, options)
+	};
+}
+//#endregion
+export { createSoftwareDevelopmentTools, softwareDevelopmentDelegationPolicy };
+
+//# sourceMappingURL=eve.mjs.map

package/dist/presets/software-development/eve.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"eve.mjs","names":[],"sources":["../../../src/presets/software-development/eve.ts"],"sourcesContent":["import { createTaskTools, type TaskTools, type TaskToolsOptions } from \"../../eve\";\nimport { softwareDevelopmentFinishTaskPolicy } from \"./finish-task-policy\";\nexport { softwareDevelopmentDelegationPolicy } from \"./eve-delegation-policy\";\nimport type { FactoryStores } from \"../../store/engine\";\nimport {\n  createRecordChangeTool,\n  type RecordChangeTool,\n  type RecordChangeToolOptions,\n} from \"../../changes/eve-record-change\";\n\n/** Change, receipt, Signal, and Task capabilities used by the supplied software tool bundle. */\nexport type SoftwareDevelopmentToolsStores = Pick<\n  FactoryStores,\n  \"changes\" | \"receipts\" | \"signals\" | \"tasks\"\n>;\n\n/** Configuration for the generic and software-development tools exposed to an Eve agent. */\nexport interface SoftwareDevelopmentToolsOptions\n  extends TaskToolsOptions, RecordChangeToolOptions {}\n\n/** Generic Task tools plus the software workflow's pull-request outcome tool. */\nexport interface SoftwareDevelopmentTools extends TaskTools {\n  readonly record_change: RecordChangeTool;\n}\n\n/** Build Eve tools with the software-development completion policy. */\nexport function createSoftwareDevelopmentTools(\n  stores: SoftwareDevelopmentToolsStores,\n  options: SoftwareDevelopmentToolsOptions = {},\n): SoftwareDevelopmentTools {\n  return {\n    ...createTaskTools(stores, {\n      ...options,\n      finishTaskPolicy: options.finishTaskPolicy ?? softwareDevelopmentFinishTaskPolicy,\n    }),\n    record_change: createRecordChangeTool(stores, options),\n  };\n}\n"],"mappings":";;;;;;AA0BA,SAAgB,+BACd,QACA,UAA2C,CAAC,GAClB;CAC1B,OAAO;EACL,GAAG,gBAAgB,QAAQ;GACzB,GAAG;GACH,kBAAkB,QAAQ,oBAAoB;EAChD,CAAC;EACD,eAAe,uBAAuB,QAAQ,OAAO;CACvD;AACF"}

package/dist/presets/software-development/finish-task-policy.d.mts

@@ -0,0 +1,7 @@
+import { Task } from "../../schema/task.mjs";
+//#region src/presets/software-development/finish-task-policy.d.ts
+/** Require the supplied code-change and verification outcome tools. */
+declare function softwareDevelopmentFinishTaskPolicy(task: Task): string | null;
+//#endregion
+export { softwareDevelopmentFinishTaskPolicy };
+//# sourceMappingURL=finish-task-policy.d.mts.map

package/dist/presets/software-development/finish-task-policy.mjs

@@ -0,0 +1,9 @@
+//#region src/presets/software-development/finish-task-policy.ts
+/** Require the supplied code-change and verification outcome tools. */
+function softwareDevelopmentFinishTaskPolicy(task) {
+	return task.kind === "code_change" || task.kind === "verification" ? `${task.kind} tasks end with their own outcome tool` : null;
+}
+//#endregion
+export { softwareDevelopmentFinishTaskPolicy };
+
+//# sourceMappingURL=finish-task-policy.mjs.map

package/dist/presets/software-development/finish-task-policy.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"finish-task-policy.mjs","names":[],"sources":["../../../src/presets/software-development/finish-task-policy.ts"],"sourcesContent":["import type { Task } from \"../../schema/task\";\n\n/** Require the supplied code-change and verification outcome tools. */\nexport function softwareDevelopmentFinishTaskPolicy(task: Task): string | null {\n  return task.kind === \"code_change\" || task.kind === \"verification\"\n    ? `${task.kind} tasks end with their own outcome tool`\n    : null;\n}\n"],"mappings":";;AAGA,SAAgB,oCAAoC,MAA2B;CAC7E,OAAO,KAAK,SAAS,iBAAiB,KAAK,SAAS,iBAChD,GAAG,KAAK,KAAK,0CACb;AACN"}

package/dist/presets/software-development/recovery.d.mts

@@ -0,0 +1,32 @@
+import { ExecutionReference, Task } from "../../schema/task.mjs";
+import { AgentRoute, AgentRouteRegistry } from "../../agent-routes.mjs";
+import { ImageAttachment } from "../../image-input.mjs";
+import { FactoryStores } from "../../store/engine.mjs";
+import { SweepQueuedOptions } from "../../sweep.mjs";
+//#region src/presets/software-development/recovery.d.ts
+/** Answer, Change, session, and Signal capabilities used to assemble recovery launchers. */
+type SoftwareDevelopmentRecoveryStores = Pick<FactoryStores, "answers" | "changes" | "sessions" | "signals">;
+/** Identifies one replacement attempt on its exact registered software agent route. */
+interface StartSoftwareDevelopmentRecoveryInput {
+  readonly route: AgentRoute;
+  readonly task: Task;
+  readonly message: string;
+  readonly images?: {
+    readonly owner: string;
+    readonly attachments: readonly ImageAttachment[];
+  };
+}
+/** Starts a replacement attempt using its exact registered software agent route. */
+type StartSoftwareDevelopmentRecovery = (input: StartSoftwareDevelopmentRecoveryInput) => Promise<ExecutionReference>;
+/** Stores, route registry, and execution boundaries used to assemble recovery launchers. */
+interface SoftwareDevelopmentRecoveryOptions {
+  stores: SoftwareDevelopmentRecoveryStores;
+  routes: AgentRouteRegistry;
+  start: StartSoftwareDevelopmentRecovery;
+  continueConversation: (task: Task) => Promise<ExecutionReference>;
+}
+/** Assemble replacement-attempt launchers for the supplied software-factory routes. */
+declare function createSoftwareDevelopmentRecoveryLaunchers(options: SoftwareDevelopmentRecoveryOptions): SweepQueuedOptions["launchers"];
+//#endregion
+export { SoftwareDevelopmentRecoveryOptions, SoftwareDevelopmentRecoveryStores, StartSoftwareDevelopmentRecovery, StartSoftwareDevelopmentRecoveryInput, createSoftwareDevelopmentRecoveryLaunchers };
+//# sourceMappingURL=recovery.d.mts.map

package/dist/presets/software-development/recovery.mjs

@@ -0,0 +1,120 @@
+import { routeKey } from "../../agent-routes.mjs";
+import { findFindingForTask, formatFindingRemediationBrief } from "../../finding-remediation/brief.mjs";
+import { agentSessionIdSchema } from "../../schema/session.mjs";
+import { normalizeFactoryReviewComment, normalizeGitHubPullRequest } from "../../github.mjs";
+import { formatChangeVerificationBrief } from "../../change-verification/brief.mjs";
+import { mergeConflictPayloadSchema } from "../../merge-resolution/contracts.mjs";
+import { formatDeepsecScanBrief } from "./deepsec-brief.mjs";
+//#region src/presets/software-development/recovery.ts
+/** Assemble replacement-attempt launchers for the supplied software-factory routes. */
+function createSoftwareDevelopmentRecoveryLaunchers(options) {
+	const { stores, routes, start, continueConversation } = options;
+	const briefs = {
+		"code-change@1": async (task, repository) => withAnsweredQuestions(stores, task, formatFindingRemediationBrief(task, repository, await findFindingForTask(stores, task))),
+		"code-review@1": (task, repository) => codeReviewBrief(stores, task, repository),
+		"review-follow-up@1": (task, repository) => reviewFollowUpBrief(stores, task, repository),
+		"merge-conflict@1": (task, repository) => mergeConflictBrief(stores, task, repository),
+		"security-scan@1": async (task, repository) => formatDeepsecScanBrief(task, repository),
+		"verification@1": (task, repository) => verificationTaskBrief(stores, task, repository)
+	};
+	const launchers = {};
+	for (const route of routes.routes) {
+		const key = routeKey(route);
+		const brief = briefs[key] ?? ((task) => withAnsweredQuestions(stores, task, `You are assigned replacement attempt ${task.attempt} for task ${task.id}. Read the task before starting.\n\n${task.work.title}\n\nWork input:\n${JSON.stringify(task.work.input)}`));
+		launchers[key] = async (task, repository) => {
+			if (!task.work.route || routeKey(task.work.route) !== key) throw new Error(`Task ${task.id} is not bound to agent route ${key}`);
+			if (task.replyTo.channel === "api") {
+				const session = await stores.sessions.get(agentSessionIdSchema.parse(task.replyTo.address));
+				if (session === null) throw new Error(`API session binding is missing for task ${task.id}`);
+				if (session.taskId === task.id) {
+					if (session.agent !== route.agent) throw new Error(`API session agent differs from route ${route.id}`);
+					const message = await withAnsweredQuestions(stores, task, `You are assigned Factory task ${task.id}. Read it before starting.\n\n${session.changeId === void 0 ? "" : `Existing change: ${session.changeId}.\n\n`}${session.message}`);
+					return start({
+						route,
+						task,
+						message,
+						...session.attachments?.length ? { images: {
+							owner: session.owner,
+							attachments: session.attachments
+						} } : {}
+					});
+				}
+			}
+			const input = task.work.input;
+			const instructions = isJsonObject(input) && typeof input.instructions === "string" ? input.instructions : void 0;
+			const message = instructions === void 0 ? await brief(task, repository) : await withAnsweredQuestions(stores, task, `You are assigned Factory task ${task.id}. Read it before starting.\n\n${task.work.title}\n\n${instructions}\n\nCompletion criteria:\n${task.work.completionCriteria.join("\n")}`);
+			return start({
+				route,
+				task,
+				message
+			});
+		};
+	}
+	launchers["conversation@1"] = async (task) => {
+		if (task.work.route?.id !== "conversation" || task.work.route.version !== 1 || task.replyTo.channel !== "api") throw new Error(`Task ${task.id} is not bound to conversation@1`);
+		if (!(await stores.sessions.get(agentSessionIdSchema.parse(task.replyTo.address)))?.continuations?.some((item) => item.taskId === task.id)) throw new Error(`Conversation binding is missing for task ${task.id}`);
+		return continueConversation(task);
+	};
+	return launchers;
+}
+function isJsonObject(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+async function codeReviewBrief(stores, task, repository) {
+	const signal = task.origin.signalId === void 0 ? null : await stores.signals.get(task.origin.signalId);
+	const normalized = signal?.source === "github_pr" ? normalizeGitHubPullRequest({
+		deliveryId: signal.deliveryId,
+		event: "pull_request",
+		payload: signal.payload
+	}) : null;
+	const changeId = task.changeId ?? await changeIdForPullRequest(stores, repository, normalized?.pullRequest.pullRequestUrl);
+	return withAnsweredQuestions(stores, task, [
+		`You are assigned replacement attempt ${task.attempt} for code review task ${task.id}.`,
+		changeId === void 0 ? null : `Change under review: ${changeId}.`,
+		normalized === null ? null : `Pull request: ${normalized.pullRequest.pullRequestUrl}.`,
+		normalized === null ? null : `Expected head commit: ${normalized.pullRequest.headSha}.`,
+		"Read the task, fetch and review the pull request, then record exactly one review result with record_post_review."
+	].filter((line) => line !== null).join("\n\n"));
+}
+async function reviewFollowUpBrief(stores, task, repository) {
+	const signal = task.origin.signalId === void 0 ? null : await stores.signals.get(task.origin.signalId);
+	const review = signal?.source === "github_pr_comment" ? normalizeFactoryReviewComment({
+		event: "pull_request_review_comment",
+		payload: signal.payload
+	}) : null;
+	const changeId = task.changeId ?? await changeIdForPullRequest(stores, repository, review?.pullRequestUrl);
+	return withAnsweredQuestions(stores, task, [
+		`You are assigned replacement attempt ${task.attempt} for factory task ${task.id}.`,
+		changeId === void 0 ? null : `Change under review: ${changeId}.`,
+		review === null ? null : `Inline review comment: ${review.commentId}.`,
+		review === null ? null : `Pull request: ${review.pullRequestUrl}.`,
+		"Read the task and originating review comment. Apply a concrete high-confidence fix, post a medium-confidence suggestion, or answer with findings, then finish the task."
+	].filter((line) => line !== null).join("\n\n"));
+}
+async function mergeConflictBrief(stores, task, repository) {
+	const signal = task.origin.signalId === void 0 ? null : await stores.signals.get(task.origin.signalId);
+	const parsed = mergeConflictPayloadSchema.safeParse(signal?.payload);
+	return withAnsweredQuestions(stores, task, parsed.success ? [
+		`You are assigned replacement attempt ${task.attempt} for merge conflict task ${task.id} in ${repository.slug}.`,
+		`Pull request: ${parsed.data.prUrl}.`,
+		"Read the task, fetch the conflict with fetch_merge_conflict, resolve and test it, then publish_merge_resolution."
+	].join("\n\n") : [`You are assigned replacement attempt ${task.attempt} for merge conflict task ${task.id} in ${repository.slug}.`, "Read the task and recover its merge-conflict context with the dedicated tools. Do not guess a pull request identifier."].join("\n\n"));
+}
+async function verificationTaskBrief(stores, task, repository) {
+	if (task.changeId === void 0) throw new Error(`verification task ${task.id} has no change`);
+	const change = await stores.changes.get(task.changeId);
+	if (change === null) throw new Error(`change ${task.changeId} does not exist`);
+	return withAnsweredQuestions(stores, task, formatChangeVerificationBrief(task, repository, change));
+}
+async function changeIdForPullRequest(stores, repository, prUrl) {
+	if (prUrl === void 0) return void 0;
+	return (await stores.changes.list()).find((change) => change.repositoryId === repository.id && change.prUrl === prUrl)?.id;
+}
+async function withAnsweredQuestions(stores, task, brief) {
+	const answers = (await Promise.all((task.answerEventIds ?? []).map((id) => stores.answers.get(id)))).flatMap((event) => event === null ? [] : [`${event.question}\nAnswer: ${event.answer}`]);
+	return answers.length === 0 ? brief : `${brief}\n\nHuman answers:\n${answers.join("\n\n")}`;
+}
+//#endregion
+export { createSoftwareDevelopmentRecoveryLaunchers };
+
+//# sourceMappingURL=recovery.mjs.map

package/dist/presets/software-development/recovery.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery.mjs","names":[],"sources":["../../../src/presets/software-development/recovery.ts"],"sourcesContent":["import {\n  routeKey,\n  type AgentRoute,\n  type AgentRouteKey,\n  type AgentRouteRegistry,\n} from \"../../agent-routes\";\nimport { formatChangeVerificationBrief } from \"../../change-verification/brief\";\nimport { findFindingForTask, formatFindingRemediationBrief } from \"../../finding-remediation/brief\";\nimport { normalizeFactoryReviewComment, normalizeGitHubPullRequest } from \"../../github\";\nimport type { ImageAttachment } from \"../../image-input\";\nimport { mergeConflictPayloadSchema } from \"../../merge-resolution/contracts\";\nimport type { Repository } from \"../../schema/repository\";\nimport { agentSessionIdSchema } from \"../../schema/session\";\nimport type { ExecutionReference, Task } from \"../../schema/task\";\nimport type { JsonValue } from \"../../schema/work\";\nimport type { FactoryStores } from \"../../store/engine\";\nimport type { SweepQueuedOptions, TaskLauncher } from \"../../sweep\";\nimport { formatDeepsecScanBrief } from \"./deepsec-brief\";\n\n/** Answer, Change, session, and Signal capabilities used to assemble recovery launchers. */\nexport type SoftwareDevelopmentRecoveryStores = Pick<\n  FactoryStores,\n  \"answers\" | \"changes\" | \"sessions\" | \"signals\"\n>;\n\n/** Identifies one replacement attempt on its exact registered software agent route. */\nexport interface StartSoftwareDevelopmentRecoveryInput {\n  readonly route: AgentRoute;\n  readonly task: Task;\n  readonly message: string;\n  readonly images?: {\n    readonly owner: string;\n    readonly attachments: readonly ImageAttachment[];\n  };\n}\n\n/** Starts a replacement attempt using its exact registered software agent route. */\nexport type StartSoftwareDevelopmentRecovery = (\n  input: StartSoftwareDevelopmentRecoveryInput,\n) => Promise<ExecutionReference>;\n\ntype RecoveryBrief = (task: Task, repository: Repository) => Promise<string>;\n\n/** Stores, route registry, and execution boundaries used to assemble recovery launchers. */\nexport interface SoftwareDevelopmentRecoveryOptions {\n  stores: SoftwareDevelopmentRecoveryStores;\n  routes: AgentRouteRegistry;\n  start: StartSoftwareDevelopmentRecovery;\n  continueConversation: (task: Task) => Promise<ExecutionReference>;\n}\n\n/** Assemble replacement-attempt launchers for the supplied software-factory routes. */\nexport function createSoftwareDevelopmentRecoveryLaunchers(\n  options: SoftwareDevelopmentRecoveryOptions,\n): SweepQueuedOptions[\"launchers\"] {\n  const { stores, routes, start, continueConversation } = options;\n  const briefs: Readonly<Partial<Record<AgentRouteKey, RecoveryBrief>>> = {\n    \"code-change@1\": async (task, repository) =>\n      withAnsweredQuestions(\n        stores,\n        task,\n        formatFindingRemediationBrief(task, repository, await findFindingForTask(stores, task)),\n      ),\n    \"code-review@1\": (task, repository) => codeReviewBrief(stores, task, repository),\n    \"review-follow-up@1\": (task, repository) => reviewFollowUpBrief(stores, task, repository),\n    \"merge-conflict@1\": (task, repository) => mergeConflictBrief(stores, task, repository),\n    \"security-scan@1\": async (task, repository) => formatDeepsecScanBrief(task, repository),\n    \"verification@1\": (task, repository) => verificationTaskBrief(stores, task, repository),\n  };\n  const launchers: Partial<Record<AgentRouteKey, TaskLauncher>> = {};\n  for (const route of routes.routes) {\n    const key = routeKey(route);\n    const brief =\n      briefs[key] ??\n      ((task: Task) =>\n        withAnsweredQuestions(\n          stores,\n          task,\n          `You are assigned replacement attempt ${task.attempt} for task ${task.id}. Read the task before starting.\\n\\n${task.work.title}\\n\\nWork input:\\n${JSON.stringify(task.work.input)}`,\n        ));\n    launchers[key] = async (task, repository) => {\n      if (!task.work.route || routeKey(task.work.route) !== key) {\n        throw new Error(`Task ${task.id} is not bound to agent route ${key}`);\n      }\n      if (task.replyTo.channel === \"api\") {\n        const session = await stores.sessions.get(agentSessionIdSchema.parse(task.replyTo.address));\n        if (session === null) {\n          throw new Error(`API session binding is missing for task ${task.id}`);\n        }\n        if (session.taskId === task.id) {\n          if (session.agent !== route.agent) {\n            throw new Error(`API session agent differs from route ${route.id}`);\n          }\n          const message = await withAnsweredQuestions(\n            stores,\n            task,\n            `You are assigned Factory task ${task.id}. Read it before starting.\\n\\n${session.changeId === undefined ? \"\" : `Existing change: ${session.changeId}.\\n\\n`}${session.message}`,\n          );\n          return start({\n            route,\n            task,\n            message,\n            ...(session.attachments?.length\n              ? {\n                  images: {\n                    owner: session.owner,\n                    attachments: session.attachments,\n                  },\n                }\n              : {}),\n          });\n        }\n      }\n      const input = task.work.input;\n      const instructions =\n        isJsonObject(input) && typeof input.instructions === \"string\"\n          ? input.instructions\n          : undefined;\n      const message =\n        instructions === undefined\n          ? await brief(task, repository)\n          : await withAnsweredQuestions(\n              stores,\n              task,\n              `You are assigned Factory task ${task.id}. Read it before starting.\\n\\n${task.work.title}\\n\\n${instructions}\\n\\nCompletion criteria:\\n${task.work.completionCriteria.join(\"\\n\")}`,\n            );\n      return start({ route, task, message });\n    };\n  }\n  launchers[\"conversation@1\"] = async (task) => {\n    if (\n      task.work.route?.id !== \"conversation\" ||\n      task.work.route.version !== 1 ||\n      task.replyTo.channel !== \"api\"\n    ) {\n      throw new Error(`Task ${task.id} is not bound to conversation@1`);\n    }\n    const session = await stores.sessions.get(agentSessionIdSchema.parse(task.replyTo.address));\n    if (!session?.continuations?.some((item) => item.taskId === task.id)) {\n      throw new Error(`Conversation binding is missing for task ${task.id}`);\n    }\n    return continueConversation(task);\n  };\n  return launchers;\n}\n\nfunction isJsonObject(value: JsonValue): value is { readonly [key: string]: JsonValue } {\n  return value !== null && typeof value === \"object\" && !Array.isArray(value);\n}\n\nasync function codeReviewBrief(\n  stores: SoftwareDevelopmentRecoveryStores,\n  task: Task,\n  repository: Repository,\n): Promise<string> {\n  const signal =\n    task.origin.signalId === undefined ? null : await stores.signals.get(task.origin.signalId);\n  const normalized =\n    signal?.source === \"github_pr\"\n      ? normalizeGitHubPullRequest({\n          deliveryId: signal.deliveryId,\n          event: \"pull_request\",\n          payload: signal.payload,\n        })\n      : null;\n  const changeId =\n    task.changeId ??\n    (await changeIdForPullRequest(stores, repository, normalized?.pullRequest.pullRequestUrl));\n  const facts = [\n    `You are assigned replacement attempt ${task.attempt} for code review task ${task.id}.`,\n    changeId === undefined ? null : `Change under review: ${changeId}.`,\n    normalized === null ? null : `Pull request: ${normalized.pullRequest.pullRequestUrl}.`,\n    normalized === null ? null : `Expected head commit: ${normalized.pullRequest.headSha}.`,\n    \"Read the task, fetch and review the pull request, then record exactly one review result with record_post_review.\",\n  ]\n    .filter((line) => line !== null)\n    .join(\"\\n\\n\");\n  return withAnsweredQuestions(stores, task, facts);\n}\n\nasync function reviewFollowUpBrief(\n  stores: SoftwareDevelopmentRecoveryStores,\n  task: Task,\n  repository: Repository,\n): Promise<string> {\n  const signal =\n    task.origin.signalId === undefined ? null : await stores.signals.get(task.origin.signalId);\n  const review =\n    signal?.source === \"github_pr_comment\"\n      ? normalizeFactoryReviewComment({\n          event: \"pull_request_review_comment\",\n          payload: signal.payload,\n        })\n      : null;\n  const changeId =\n    task.changeId ?? (await changeIdForPullRequest(stores, repository, review?.pullRequestUrl));\n  const facts = [\n    `You are assigned replacement attempt ${task.attempt} for factory task ${task.id}.`,\n    changeId === undefined ? null : `Change under review: ${changeId}.`,\n    review === null ? null : `Inline review comment: ${review.commentId}.`,\n    review === null ? null : `Pull request: ${review.pullRequestUrl}.`,\n    \"Read the task and originating review comment. Apply a concrete high-confidence fix, post a medium-confidence suggestion, or answer with findings, then finish the task.\",\n  ]\n    .filter((line) => line !== null)\n    .join(\"\\n\\n\");\n  return withAnsweredQuestions(stores, task, facts);\n}\n\nasync function mergeConflictBrief(\n  stores: SoftwareDevelopmentRecoveryStores,\n  task: Task,\n  repository: Repository,\n): Promise<string> {\n  const signal =\n    task.origin.signalId === undefined ? null : await stores.signals.get(task.origin.signalId);\n  const parsed = mergeConflictPayloadSchema.safeParse(signal?.payload);\n  const facts = parsed.success\n    ? [\n        `You are assigned replacement attempt ${task.attempt} for merge conflict task ${task.id} in ${repository.slug}.`,\n        `Pull request: ${parsed.data.prUrl}.`,\n        \"Read the task, fetch the conflict with fetch_merge_conflict, resolve and test it, then publish_merge_resolution.\",\n      ].join(\"\\n\\n\")\n    : [\n        `You are assigned replacement attempt ${task.attempt} for merge conflict task ${task.id} in ${repository.slug}.`,\n        \"Read the task and recover its merge-conflict context with the dedicated tools. Do not guess a pull request identifier.\",\n      ].join(\"\\n\\n\");\n  return withAnsweredQuestions(stores, task, facts);\n}\n\nasync function verificationTaskBrief(\n  stores: SoftwareDevelopmentRecoveryStores,\n  task: Task,\n  repository: Repository,\n): Promise<string> {\n  if (task.changeId === undefined) throw new Error(`verification task ${task.id} has no change`);\n  const change = await stores.changes.get(task.changeId);\n  if (change === null) throw new Error(`change ${task.changeId} does not exist`);\n  return withAnsweredQuestions(\n    stores,\n    task,\n    formatChangeVerificationBrief(task, repository, change),\n  );\n}\n\nasync function changeIdForPullRequest(\n  stores: SoftwareDevelopmentRecoveryStores,\n  repository: Repository,\n  prUrl: string | undefined,\n): Promise<string | undefined> {\n  if (prUrl === undefined) return undefined;\n  return (await stores.changes.list()).find(\n    (change) => change.repositoryId === repository.id && change.prUrl === prUrl,\n  )?.id;\n}\n\nasync function withAnsweredQuestions(\n  stores: SoftwareDevelopmentRecoveryStores,\n  task: Task,\n  brief: string,\n): Promise<string> {\n  const answers = (\n    await Promise.all((task.answerEventIds ?? []).map((id) => stores.answers.get(id)))\n  ).flatMap((event) => (event === null ? [] : [`${event.question}\\nAnswer: ${event.answer}`]));\n  return answers.length === 0 ? brief : `${brief}\\n\\nHuman answers:\\n${answers.join(\"\\n\\n\")}`;\n}\n"],"mappings":"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"}

package/dist/presets/software-development/task-communication.d.mts

@@ -0,0 +1,23 @@
+import { Task } from "../../schema/task.mjs";
+import { ReplyTo } from "../../schema/common.mjs";
+import { CommunicationEvent } from "../../schema/communication.mjs";
+import { FactoryStores } from "../../store/engine.mjs";
+import { TaskCommunicationReconciler } from "../../task-communication.mjs";
+//#region src/presets/software-development/task-communication.d.ts
+/** Store capabilities required by supplied software-development communication projections. */
+type SoftwareDevelopmentTaskCommunicationStores = Pick<FactoryStores, "changes" | "outbox" | "receipts" | "repositories" | "tasks">;
+/** Connector presentation settings for supplied software Task communications. */
+interface SoftwareDevelopmentTaskCommunicationOptions {
+  githubMention?: string;
+  needsHumanReplyTo?: ReplyTo;
+}
+/** Supplied question projection and durable lifecycle communication reconciler. */
+interface SoftwareDevelopmentTaskCommunication {
+  questionEvents(task: Task): readonly CommunicationEvent[];
+  reconcile: TaskCommunicationReconciler<SoftwareDevelopmentTaskCommunicationStores>;
+}
+/** Supplied Slack, GitHub, and API presentation for a task question. */
+declare function createSoftwareDevelopmentTaskCommunication(options?: SoftwareDevelopmentTaskCommunicationOptions): SoftwareDevelopmentTaskCommunication;
+//#endregion
+export { SoftwareDevelopmentTaskCommunication, SoftwareDevelopmentTaskCommunicationOptions, SoftwareDevelopmentTaskCommunicationStores, createSoftwareDevelopmentTaskCommunication };
+//# sourceMappingURL=task-communication.d.mts.map

package/dist/presets/software-development/task-communication.mjs

@@ -0,0 +1,120 @@
+import { createTaskCommunicationReconciler } from "../../task-communication.mjs";
+//#region src/presets/software-development/task-communication.ts
+/** Supplied Slack, GitHub, and API presentation for a task question. */
+function createSoftwareDevelopmentTaskCommunication(options = {}) {
+	const githubMention = options.githubMention ?? "@agent-factory";
+	if (githubMention.trim().length === 0) throw new Error("githubMention must not be empty");
+	const needsHumanReplyTo = options.needsHumanReplyTo ?? {
+		channel: "slack",
+		address: "owner"
+	};
+	function questionEvents(task) {
+		if (task.kind !== "question" || task.question === void 0) throw new Error(`Task ${task.id} has no question.`);
+		const reference = `Reference: ${task.id}`;
+		const instructions = task.replyTo.channel === "slack" ? "To answer, reply in this thread and mention the Factory app." : task.replyTo.channel === "github" && task.replyTo.address.includes("#") ? `To answer, comment on this issue starting with \`${githubMention}\`.` : "Answer in the original conversation.";
+		const common = {
+			repositoryIds: task.repositoryIds,
+			taskId: task.id
+		};
+		const action = task.needsHumanAction ?? task.question.text;
+		const apiInstructions = task.replyTo.channel === "api" ? `\nOpen session ${task.replyTo.address} in your Factory client to answer.${/^ses_[a-z0-9]{6,64}$/u.test(task.replyTo.address) ? ` In Factory TUI: factory-tui --session ${task.replyTo.address}` : ""}` : "";
+		return [{
+			...common,
+			eventId: `question:${task.id}:${task.attempt}`,
+			replyTo: task.replyTo,
+			outcome: "question",
+			data: {
+				question: `${reference}\n\n${instructions}\n\n${task.question.text}`,
+				options: task.question.options
+			}
+		}, {
+			...common,
+			eventId: `needs-human:${task.id}:${task.attempt}`,
+			replyTo: needsHumanReplyTo,
+			outcome: "needs_human",
+			data: {
+				requestedAction: action.length > 2e3 ? `${action.slice(0, 2e3)}…` : action,
+				message: `${reference}\nOpen the original conversation to answer.${apiInstructions}\nReplies in this notification DM do not answer the question.`,
+				options: task.question.options,
+				questionAttempt: task.attempt,
+				...task.parentTaskId === void 0 ? {} : { parentTaskId: task.parentTaskId },
+				replyChannel: task.replyTo.channel,
+				replyAddress: task.replyTo.address
+			}
+		}];
+	}
+	return {
+		questionEvents,
+		reconcile: createTaskCommunicationReconciler({
+			question: questionEvents,
+			async lifecycle({ stores, tasks, task, receipt }) {
+				return [task.kind === "coordination" && (receipt.state === "succeeded" || receipt.state === "failed") ? await coordinationEvent(stores, tasks, task, receipt) : eventFor(task, receipt)];
+			}
+		})
+	};
+}
+function eventFor(task, receipt) {
+	const common = {
+		eventId: `task-lifecycle:${receipt.receiptId}`,
+		repositoryIds: task.repositoryIds,
+		taskId: task.id,
+		...task.changeId === void 0 ? {} : { changeId: task.changeId },
+		replyTo: task.replyTo
+	};
+	if (receipt.state === "dispatched" && receipt.phase === "retry") return {
+		...common,
+		outcome: "started",
+		data: { message: `Retry attempt ${receipt.attempt} started.${receipt.reason === void 0 ? "" : ` ${receipt.reason}`}` }
+	};
+	if (receipt.state === "failed") {
+		let prefix = "Work failed.";
+		if (receipt.reason?.startsWith("launch failed")) prefix = "Work failed to start.";
+		else if (receipt.phase === "retry") prefix = "Retries exhausted.";
+		return {
+			...common,
+			outcome: "failed",
+			data: { reason: `${prefix}${receipt.reason === void 0 ? "" : ` ${receipt.reason}`}` }
+		};
+	}
+	if (receipt.state === "cancelled") {
+		const prefix = receipt.phase === "approval" ? "Request rejected." : "Work cancelled.";
+		return {
+			...common,
+			outcome: "cancelled",
+			data: {
+				message: `${prefix}${receipt.reason === void 0 ? "" : ` ${receipt.reason}`}`,
+				...receipt.phase === "approval" ? { approvalDecision: true } : {}
+			}
+		};
+	}
+	if (receipt.state === "succeeded") return {
+		...common,
+		outcome: "succeeded",
+		data: {
+			summary: receipt.reason ?? "The task completed successfully.",
+			output: task.workResult?.output
+		}
+	};
+	throw new Error(`Receipt ${receipt.receiptId} is not a communicable task lifecycle event.`);
+}
+async function coordinationEvent(stores, tasks, parent, receipt) {
+	const children = tasks.filter((task) => task.parentTaskId === parent.id);
+	const items = await Promise.all(children.map(async (child) => {
+		const repository = await stores.repositories.get(child.repositoryIds[0]);
+		const change = child.changeId === void 0 ? null : await stores.changes.get(child.changeId);
+		return `${repository?.slug ?? child.repositoryIds[0]}: ${change?.prUrl ?? child.state}`;
+	}));
+	const event = eventFor(parent, receipt);
+	return {
+		...event,
+		data: {
+			...event.data,
+			summary: receipt.state === "succeeded" ? "Coordinated work completed." : "Coordinated work failed in one or more repositories.",
+			items
+		}
+	};
+}
+//#endregion
+export { createSoftwareDevelopmentTaskCommunication };
+
+//# sourceMappingURL=task-communication.mjs.map