@vercel/factory 0.0.14 → 0.0.16

package/dist/planning/cancellation.mjs

@@ -0,0 +1,82 @@
+import { taskIdSchema } from "../schema/id.mjs";
+import { isoDateTimeSchema, schemaVersionSchema } from "../schema/common.mjs";
+import { taskSchema } from "../schema/task.mjs";
+import { RecordExistsError } from "../store/driver.mjs";
+import { createHash } from "node:crypto";
+import { z } from "zod";
+//#region src/planning/cancellation.ts
+const confirmationSchema = z.strictObject({
+	schemaVersion: schemaVersionSchema,
+	taskId: taskIdSchema.describe("Cancelled Task owning the execution."),
+	attempt: z.number().int().positive().describe("Cancelled execution attempt."),
+	provider: z.string().min(1).describe("Execution provider that acknowledged cancellation."),
+	sessionId: z.string().min(1).describe("Exact provider session whose cancellation was acknowledged."),
+	confirmedAt: isoDateTimeSchema.describe("Time the callback succeeded; not a provider lifecycle mirror.")
+});
+/** Shared per invocation, including decision replay. Confirmation is durable; ambiguous provider writes must be safe to repeat. */
+function plannerCancellationBatch(options) {
+	const driver = options.stores.workflowRecords;
+	let attempts = 0;
+	const attempted = /* @__PURE__ */ new Set();
+	const pending = /* @__PURE__ */ new Set();
+	const errors = [];
+	async function stop(input) {
+		const task = taskSchema.parse(input);
+		if (task.state !== "cancelled" || !task.execution) return "not_needed";
+		const identity = {
+			taskId: task.id,
+			attempt: task.attempt,
+			provider: task.execution.provider,
+			sessionId: task.execution.sessionId
+		};
+		const id = `cancel_${createHash("sha256").update(JSON.stringify(identity)).digest("hex")}`;
+		async function confirmed() {
+			const stored = await driver.get("plannerCancellations", id);
+			if (!stored) return false;
+			const value = confirmationSchema.parse(stored.value);
+			if (value.taskId !== identity.taskId || value.attempt !== identity.attempt || value.provider !== identity.provider || value.sessionId !== identity.sessionId) throw new Error("Planner cancellation confirmation identity mismatch");
+			pending.delete(task.id);
+			return true;
+		}
+		if (await confirmed()) return "confirmed";
+		if (!options.cancelExecution) return "unconfigured";
+		pending.add(task.id);
+		if (attempts >= 32 || attempted.has(id)) return "pending";
+		attempted.add(id);
+		attempts++;
+		try {
+			await options.cancelExecution(task);
+			const record = confirmationSchema.parse({
+				...identity,
+				schemaVersion: 1,
+				confirmedAt: (options.now ?? (() => (/* @__PURE__ */ new Date()).toISOString()))()
+			});
+			try {
+				await driver.insert({
+					collection: "plannerCancellations",
+					id,
+					value: record
+				});
+			} catch (error) {
+				if (!(error instanceof RecordExistsError) || !await confirmed()) throw error;
+			}
+			pending.delete(task.id);
+			return "confirmed";
+		} catch (error) {
+			errors.push({
+				taskId: task.id,
+				message: (error instanceof Error ? error.message : String(error)).slice(0, 1e3)
+			});
+			return "pending";
+		}
+	}
+	return {
+		stop,
+		pending,
+		errors
+	};
+}
+//#endregion
+export { plannerCancellationBatch };
+
+//# sourceMappingURL=cancellation.mjs.map

package/dist/planning/cancellation.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cancellation.mjs","names":[],"sources":["../../src/planning/cancellation.ts"],"sourcesContent":["import { createHash } from \"node:crypto\";\nimport { z } from \"zod\";\nimport { isoDateTimeSchema, schemaVersionSchema } from \"../schema/common\";\nimport { taskIdSchema, type TaskId } from \"../schema/id\";\nimport { taskSchema, type Task } from \"../schema/task\";\nimport { RecordExistsError } from \"../store/driver\";\nimport type { PlannerRuntimeOptions } from \"./contracts\";\n\nconst confirmationSchema = z.strictObject({\n  schemaVersion: schemaVersionSchema,\n  taskId: taskIdSchema.describe(\"Cancelled Task owning the execution.\"),\n  attempt: z.number().int().positive().describe(\"Cancelled execution attempt.\"),\n  provider: z.string().min(1).describe(\"Execution provider that acknowledged cancellation.\"),\n  sessionId: z\n    .string()\n    .min(1)\n    .describe(\"Exact provider session whose cancellation was acknowledged.\"),\n  confirmedAt: isoDateTimeSchema.describe(\n    \"Time the callback succeeded; not a provider lifecycle mirror.\",\n  ),\n});\n\n/** Shared per invocation, including decision replay. Confirmation is durable; ambiguous provider writes must be safe to repeat. */\nexport function plannerCancellationBatch(options: PlannerRuntimeOptions) {\n  const driver = options.stores.workflowRecords;\n  let attempts = 0;\n  const attempted = new Set<string>();\n  const pending = new Set<TaskId>();\n  const errors: { taskId: TaskId; message: string }[] = [];\n  async function stop(\n    input: Task,\n  ): Promise<\"confirmed\" | \"pending\" | \"unconfigured\" | \"not_needed\"> {\n    const task = taskSchema.parse(input);\n    if (task.state !== \"cancelled\" || !task.execution) return \"not_needed\";\n    const identity = {\n      taskId: task.id,\n      attempt: task.attempt,\n      provider: task.execution.provider,\n      sessionId: task.execution.sessionId,\n    };\n    const id = `cancel_${createHash(\"sha256\").update(JSON.stringify(identity)).digest(\"hex\")}`;\n    async function confirmed(): Promise<boolean> {\n      const stored = await driver.get(\"plannerCancellations\", id);\n      if (!stored) return false;\n      const value = confirmationSchema.parse(stored.value);\n      if (\n        value.taskId !== identity.taskId ||\n        value.attempt !== identity.attempt ||\n        value.provider !== identity.provider ||\n        value.sessionId !== identity.sessionId\n      )\n        throw new Error(\"Planner cancellation confirmation identity mismatch\");\n      pending.delete(task.id);\n      return true;\n    }\n    if (await confirmed()) return \"confirmed\";\n    if (!options.cancelExecution) return \"unconfigured\";\n    pending.add(task.id);\n    if (attempts >= 32 || attempted.has(id)) return \"pending\";\n    attempted.add(id);\n    attempts++;\n    try {\n      await options.cancelExecution(task);\n      const record = confirmationSchema.parse({\n        ...identity,\n        schemaVersion: 1,\n        confirmedAt: (options.now ?? (() => new Date().toISOString()))(),\n      });\n      try {\n        await driver.insert({ collection: \"plannerCancellations\", id, value: record });\n      } catch (error) {\n        if (!(error instanceof RecordExistsError) || !(await confirmed())) throw error;\n      }\n      pending.delete(task.id);\n      return \"confirmed\";\n    } catch (error) {\n      errors.push({\n        taskId: task.id,\n        message: (error instanceof Error ? error.message : String(error)).slice(0, 1000),\n      });\n      return \"pending\";\n    }\n  }\n  return { stop, pending, errors };\n}\nexport type PlannerCancellationBatch = ReturnType<typeof plannerCancellationBatch>;\n"],"mappings":";;;;;;;AAQA,MAAM,qBAAqB,EAAE,aAAa;CACxC,eAAe;CACf,QAAQ,aAAa,SAAS,sCAAsC;CACpE,SAAS,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,8BAA8B;CAC5E,UAAU,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,oDAAoD;CACzF,WAAW,EACR,OAAO,CAAC,CACR,IAAI,CAAC,CAAC,CACN,SAAS,6DAA6D;CACzE,aAAa,kBAAkB,SAC7B,+DACF;AACF,CAAC;;AAGD,SAAgB,yBAAyB,SAAgC;CACvE,MAAM,SAAS,QAAQ,OAAO;CAC9B,IAAI,WAAW;CACf,MAAM,4BAAY,IAAI,IAAY;CAClC,MAAM,0BAAU,IAAI,IAAY;CAChC,MAAM,SAAgD,CAAC;CACvD,eAAe,KACb,OACkE;EAClE,MAAM,OAAO,WAAW,MAAM,KAAK;EACnC,IAAI,KAAK,UAAU,eAAe,CAAC,KAAK,WAAW,OAAO;EAC1D,MAAM,WAAW;GACf,QAAQ,KAAK;GACb,SAAS,KAAK;GACd,UAAU,KAAK,UAAU;GACzB,WAAW,KAAK,UAAU;EAC5B;EACA,MAAM,KAAK,UAAU,WAAW,QAAQ,CAAC,CAAC,OAAO,KAAK,UAAU,QAAQ,CAAC,CAAC,CAAC,OAAO,KAAK;EACvF,eAAe,YAA8B;GAC3C,MAAM,SAAS,MAAM,OAAO,IAAI,wBAAwB,EAAE;GAC1D,IAAI,CAAC,QAAQ,OAAO;GACpB,MAAM,QAAQ,mBAAmB,MAAM,OAAO,KAAK;GACnD,IACE,MAAM,WAAW,SAAS,UAC1B,MAAM,YAAY,SAAS,WAC3B,MAAM,aAAa,SAAS,YAC5B,MAAM,cAAc,SAAS,WAE7B,MAAM,IAAI,MAAM,qDAAqD;GACvE,QAAQ,OAAO,KAAK,EAAE;GACtB,OAAO;EACT;EACA,IAAI,MAAM,UAAU,GAAG,OAAO;EAC9B,IAAI,CAAC,QAAQ,iBAAiB,OAAO;EACrC,QAAQ,IAAI,KAAK,EAAE;EACnB,IAAI,YAAY,MAAM,UAAU,IAAI,EAAE,GAAG,OAAO;EAChD,UAAU,IAAI,EAAE;EAChB;EACA,IAAI;GACF,MAAM,QAAQ,gBAAgB,IAAI;GAClC,MAAM,SAAS,mBAAmB,MAAM;IACtC,GAAG;IACH,eAAe;IACf,cAAc,QAAQ,+BAAc,IAAI,KAAK,EAAA,CAAE,YAAY,GAAA,CAAI;GACjE,CAAC;GACD,IAAI;IACF,MAAM,OAAO,OAAO;KAAE,YAAY;KAAwB;KAAI,OAAO;IAAO,CAAC;GAC/E,SAAS,OAAO;IACd,IAAI,EAAE,iBAAiB,sBAAsB,CAAE,MAAM,UAAU,GAAI,MAAM;GAC3E;GACA,QAAQ,OAAO,KAAK,EAAE;GACtB,OAAO;EACT,SAAS,OAAO;GACd,OAAO,KAAK;IACV,QAAQ,KAAK;IACb,UAAU,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,EAAA,CAAG,MAAM,GAAG,GAAI;GACjF,CAAC;GACD,OAAO;EACT;CACF;CACA,OAAO;EAAE;EAAM;EAAS;CAAO;AACjC"}

package/dist/planning/configuration.d.mts

@@ -0,0 +1,23 @@
+import { AgentRouteBinding } from "../schema/agent-route.mjs";
+import "../schema/task.mjs";
+import "../agent-routes.mjs";
+import { TaskMessageProtocol, TaskMessageProtocols } from "../schema/task-message.mjs";
+import { TaskMessageAuthorize } from "../store/task-messages.mjs";
+import { StandardTaskMessageProtocol } from "../task-protocols.mjs";
+import "../tasks.mjs";
+import "./contracts.mjs";
+import { z } from "zod";
+//#region src/planning/configuration.d.ts
+/** Exact task-scoped protocol that activates an initial or recovery planner turn. */
+declare const plannerStartTaskMessageProtocol: Readonly<TaskMessageProtocol<z.ZodObject<{
+  reason: z.ZodString;
+}, z.core.$strict>, "planner-start", 1>>;
+/** Registry containing the standard protocols and the exact planner-start protocol. */
+type PlannerMessageProtocols = TaskMessageProtocols<StandardTaskMessageProtocol | typeof plannerStartTaskMessageProtocol>;
+/** Creates the standard task-message protocol registry used by planners. */
+declare function createPlannerMessageProtocols(): PlannerMessageProtocols;
+/** Only trusted server code may construct this identity; agent tools authenticate a Task binding separately. */
+declare function createPlannerMessagePolicy(plannerRoute: AgentRouteBinding, workerRoutes?: readonly AgentRouteBinding[]): TaskMessageAuthorize;
+//#endregion
+export { PlannerMessageProtocols, createPlannerMessagePolicy, createPlannerMessageProtocols, plannerStartTaskMessageProtocol };
+//# sourceMappingURL=configuration.d.mts.map

package/dist/planning/configuration.mjs

@@ -0,0 +1,56 @@
+import { agentRouteBindingSchema } from "../schema/agent-route.mjs";
+import { routeKey } from "../agent-routes.mjs";
+import { defineTaskMessageProtocol, defineTaskMessageProtocols } from "../schema/task-message.mjs";
+import { standardTaskMessageProtocols } from "../task-protocols.mjs";
+import { z } from "zod";
+//#region src/planning/configuration.ts
+/** Exact task-scoped protocol that activates an initial or recovery planner turn. */
+const plannerStartTaskMessageProtocol = defineTaskMessageProtocol({
+	id: "planner-start",
+	version: 1,
+	sourceFence: "task",
+	payload: z.strictObject({ reason: z.string().min(1).max(1e3).describe("Durable initial or recovery turn reason, not execution instructions.") })
+});
+/** Creates the standard task-message protocol registry used by planners. */
+function createPlannerMessageProtocols() {
+	return defineTaskMessageProtocols([...standardTaskMessageProtocols, plannerStartTaskMessageProtocol]);
+}
+/** Only trusted server code may construct this identity; agent tools authenticate a Task binding separately. */
+function createPlannerMessagePolicy(plannerRoute, workerRoutes = []) {
+	const planner = routeKey(agentRouteBindingSchema.parse(plannerRoute));
+	const workers = new Set(workerRoutes.map((route) => routeKey(agentRouteBindingSchema.parse(route))));
+	const isPlanner = (task) => task.work.route !== void 0 && routeKey(task.work.route) === planner;
+	const ownedChild = (child, parent) => child.parentTaskId === parent.id && child.rootTaskId === parent.rootTaskId && isPlanner(parent) && (isPlanner(child) || child.work.route !== void 0 && workers.has(routeKey(child.work.route)));
+	return ({ principal, action, fromTask, toTask }) => {
+		if (principal.id !== "factory:planner-runtime" || principal.taskId !== void 0) return false;
+		if (!fromTask) return isPlanner(toTask) && action !== "send" && action !== "send_result";
+		if (fromTask.rootTaskId !== toTask.rootTaskId) return false;
+		if (action === "send_result") return ownedChild(fromTask, toTask);
+		if (action === "send") return isPlanner(fromTask) && fromTask.id === toTask.id || ownedChild(toTask, fromTask);
+		return isPlanner(toTask) && (fromTask.id === toTask.id || ownedChild(fromTask, toTask) || ownedChild(toTask, fromTask));
+	};
+}
+function plannerConfiguration(options) {
+	const plannerRoute = agentRouteBindingSchema.parse(options.plannerRoute);
+	const workerRoutes = options.workerRoutes.map((route) => agentRouteBindingSchema.parse(route));
+	const allowed = new Map([plannerRoute, ...workerRoutes].map((binding) => {
+		const route = options.routes.get(binding);
+		if (!route) throw new Error(`Planner route ${routeKey(binding)} is not registered`);
+		return [routeKey(binding), structuredClone(route)];
+	}));
+	if (allowed.size > 32) throw new Error("At most 32 planner and worker routes may be configured");
+	return {
+		allowed,
+		limits: Object.freeze(z.strictObject({
+			maxDepth: z.number().int().min(0).max(255).default(4).describe("Maximum child depth below the graph root."),
+			maxChildren: z.number().int().min(1).max(32).default(32).describe("Total direct children per planner, including previous batches."),
+			maxTurns: z.number().int().min(1).max(256).default(16).describe("Maximum execution attempts per planner, including recovery turns.")
+		}).parse(options.limits ?? {})),
+		plannerRoute,
+		isPlanner: (task) => task.work.route !== void 0 && routeKey(task.work.route) === routeKey(plannerRoute)
+	};
+}
+//#endregion
+export { createPlannerMessagePolicy, createPlannerMessageProtocols, plannerConfiguration, plannerStartTaskMessageProtocol };
+
+//# sourceMappingURL=configuration.mjs.map

package/dist/planning/configuration.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"configuration.mjs","names":[],"sources":["../../src/planning/configuration.ts"],"sourcesContent":["import { z } from \"zod\";\nimport { agentRouteBindingSchema, routeKey, type AgentRouteBinding } from \"../agent-routes\";\nimport type { Task } from \"../schema/task\";\nimport {\n  defineTaskMessageProtocol,\n  defineTaskMessageProtocols,\n  type TaskMessageProtocols,\n} from \"../schema/task-message\";\nimport type { TaskMessageAuthorize } from \"../store/task-messages\";\nimport { standardTaskMessageProtocols, type StandardTaskMessageProtocol } from \"../task-protocols\";\nimport type { PlannerRuntimeOptions } from \"./contracts\";\n\n/** Exact task-scoped protocol that activates an initial or recovery planner turn. */\nexport const plannerStartTaskMessageProtocol = defineTaskMessageProtocol({\n  id: \"planner-start\",\n  version: 1,\n  sourceFence: \"task\",\n  payload: z.strictObject({\n    reason: z\n      .string()\n      .min(1)\n      .max(1000)\n      .describe(\"Durable initial or recovery turn reason, not execution instructions.\"),\n  }),\n});\n\n/** Registry containing the standard protocols and the exact planner-start protocol. */\nexport type PlannerMessageProtocols = TaskMessageProtocols<\n  StandardTaskMessageProtocol | typeof plannerStartTaskMessageProtocol\n>;\n\n/** Creates the standard task-message protocol registry used by planners. */\nexport function createPlannerMessageProtocols(): PlannerMessageProtocols {\n  return defineTaskMessageProtocols([\n    ...standardTaskMessageProtocols,\n    plannerStartTaskMessageProtocol,\n  ]);\n}\n\n/** Only trusted server code may construct this identity; agent tools authenticate a Task binding separately. */\nexport function createPlannerMessagePolicy(\n  plannerRoute: AgentRouteBinding,\n  workerRoutes: readonly AgentRouteBinding[] = [],\n): TaskMessageAuthorize {\n  const planner = routeKey(agentRouteBindingSchema.parse(plannerRoute));\n  const workers = new Set(\n    workerRoutes.map((route) => routeKey(agentRouteBindingSchema.parse(route))),\n  );\n  const isPlanner = (task: Task) =>\n    task.work.route !== undefined && routeKey(task.work.route) === planner;\n  const ownedChild = (child: Task, parent: Task) =>\n    child.parentTaskId === parent.id &&\n    child.rootTaskId === parent.rootTaskId &&\n    isPlanner(parent) &&\n    (isPlanner(child) ||\n      (child.work.route !== undefined && workers.has(routeKey(child.work.route))));\n  return ({ principal, action, fromTask, toTask }) => {\n    if (principal.id !== \"factory:planner-runtime\" || principal.taskId !== undefined) return false;\n    if (!fromTask) return isPlanner(toTask) && action !== \"send\" && action !== \"send_result\";\n    if (fromTask.rootTaskId !== toTask.rootTaskId) return false;\n    if (action === \"send_result\") return ownedChild(fromTask, toTask);\n    if (action === \"send\")\n      return (isPlanner(fromTask) && fromTask.id === toTask.id) || ownedChild(toTask, fromTask);\n    return (\n      isPlanner(toTask) &&\n      (fromTask.id === toTask.id || ownedChild(fromTask, toTask) || ownedChild(toTask, fromTask))\n    );\n  };\n}\n\nexport function plannerConfiguration(options: PlannerRuntimeOptions) {\n  const plannerRoute = agentRouteBindingSchema.parse(options.plannerRoute);\n  const workerRoutes = options.workerRoutes.map((route) => agentRouteBindingSchema.parse(route));\n  const allowed = new Map(\n    [plannerRoute, ...workerRoutes].map((binding) => {\n      const route = options.routes.get(binding);\n      if (!route) throw new Error(`Planner route ${routeKey(binding)} is not registered`);\n      return [routeKey(binding), structuredClone(route)] as const;\n    }),\n  );\n  if (allowed.size > 32) throw new Error(\"At most 32 planner and worker routes may be configured\");\n  const limits = Object.freeze(\n    z\n      .strictObject({\n        maxDepth: z\n          .number()\n          .int()\n          .min(0)\n          .max(255)\n          .default(4)\n          .describe(\"Maximum child depth below the graph root.\"),\n        maxChildren: z\n          .number()\n          .int()\n          .min(1)\n          .max(32)\n          .default(32)\n          .describe(\"Total direct children per planner, including previous batches.\"),\n        maxTurns: z\n          .number()\n          .int()\n          .min(1)\n          .max(256)\n          .default(16)\n          .describe(\"Maximum execution attempts per planner, including recovery turns.\"),\n      })\n      .parse(options.limits ?? {}),\n  );\n  return {\n    allowed,\n    limits,\n    plannerRoute,\n    isPlanner: (task: Task) =>\n      task.work.route !== undefined && routeKey(task.work.route) === routeKey(plannerRoute),\n  };\n}\nexport type PlannerConfiguration = ReturnType<typeof plannerConfiguration>;\n"],"mappings":";;;;;;;AAaA,MAAa,kCAAkC,0BAA0B;CACvE,IAAI;CACJ,SAAS;CACT,aAAa;CACb,SAAS,EAAE,aAAa,EACtB,QAAQ,EACL,OAAO,CAAC,CACR,IAAI,CAAC,CAAC,CACN,IAAI,GAAI,CAAC,CACT,SAAS,sEAAsE,EACpF,CAAC;AACH,CAAC;;AAQD,SAAgB,gCAAyD;CACvE,OAAO,2BAA2B,CAChC,GAAG,8BACH,+BACF,CAAC;AACH;;AAGA,SAAgB,2BACd,cACA,eAA6C,CAAC,GACxB;CACtB,MAAM,UAAU,SAAS,wBAAwB,MAAM,YAAY,CAAC;CACpE,MAAM,UAAU,IAAI,IAClB,aAAa,KAAK,UAAU,SAAS,wBAAwB,MAAM,KAAK,CAAC,CAAC,CAC5E;CACA,MAAM,aAAa,SACjB,KAAK,KAAK,UAAU,KAAA,KAAa,SAAS,KAAK,KAAK,KAAK,MAAM;CACjE,MAAM,cAAc,OAAa,WAC/B,MAAM,iBAAiB,OAAO,MAC9B,MAAM,eAAe,OAAO,cAC5B,UAAU,MAAM,MACf,UAAU,KAAK,KACb,MAAM,KAAK,UAAU,KAAA,KAAa,QAAQ,IAAI,SAAS,MAAM,KAAK,KAAK,CAAC;CAC7E,QAAQ,EAAE,WAAW,QAAQ,UAAU,aAAa;EAClD,IAAI,UAAU,OAAO,6BAA6B,UAAU,WAAW,KAAA,GAAW,OAAO;EACzF,IAAI,CAAC,UAAU,OAAO,UAAU,MAAM,KAAK,WAAW,UAAU,WAAW;EAC3E,IAAI,SAAS,eAAe,OAAO,YAAY,OAAO;EACtD,IAAI,WAAW,eAAe,OAAO,WAAW,UAAU,MAAM;EAChE,IAAI,WAAW,QACb,OAAQ,UAAU,QAAQ,KAAK,SAAS,OAAO,OAAO,MAAO,WAAW,QAAQ,QAAQ;EAC1F,OACE,UAAU,MAAM,MACf,SAAS,OAAO,OAAO,MAAM,WAAW,UAAU,MAAM,KAAK,WAAW,QAAQ,QAAQ;CAE7F;AACF;AAEA,SAAgB,qBAAqB,SAAgC;CACnE,MAAM,eAAe,wBAAwB,MAAM,QAAQ,YAAY;CACvE,MAAM,eAAe,QAAQ,aAAa,KAAK,UAAU,wBAAwB,MAAM,KAAK,CAAC;CAC7F,MAAM,UAAU,IAAI,IAClB,CAAC,cAAc,GAAG,YAAY,CAAC,CAAC,KAAK,YAAY;EAC/C,MAAM,QAAQ,QAAQ,OAAO,IAAI,OAAO;EACxC,IAAI,CAAC,OAAO,MAAM,IAAI,MAAM,iBAAiB,SAAS,OAAO,EAAE,mBAAmB;EAClF,OAAO,CAAC,SAAS,OAAO,GAAG,gBAAgB,KAAK,CAAC;CACnD,CAAC,CACH;CACA,IAAI,QAAQ,OAAO,IAAI,MAAM,IAAI,MAAM,wDAAwD;CA4B/F,OAAO;EACL;EACA,QA7Ba,OAAO,OACpB,EACG,aAAa;GACZ,UAAU,EACP,OAAO,CAAC,CACR,IAAI,CAAC,CACL,IAAI,CAAC,CAAC,CACN,IAAI,GAAG,CAAC,CACR,QAAQ,CAAC,CAAC,CACV,SAAS,2CAA2C;GACvD,aAAa,EACV,OAAO,CAAC,CACR,IAAI,CAAC,CACL,IAAI,CAAC,CAAC,CACN,IAAI,EAAE,CAAC,CACP,QAAQ,EAAE,CAAC,CACX,SAAS,gEAAgE;GAC5E,UAAU,EACP,OAAO,CAAC,CACR,IAAI,CAAC,CACL,IAAI,CAAC,CAAC,CACN,IAAI,GAAG,CAAC,CACR,QAAQ,EAAE,CAAC,CACX,SAAS,mEAAmE;EACjF,CAAC,CAAC,CACD,MAAM,QAAQ,UAAU,CAAC,CAAC,CAIxB;EACL;EACA,YAAY,SACV,KAAK,KAAK,UAAU,KAAA,KAAa,SAAS,KAAK,KAAK,KAAK,MAAM,SAAS,YAAY;CACxF;AACF"}

package/dist/planning/contracts.d.mts

@@ -0,0 +1,136 @@
+import { RepositoryId, TaskId } from "../schema/id.mjs";
+import { AgentRouteBinding } from "../schema/agent-route.mjs";
+import { ExecutionReference, Task } from "../schema/task.mjs";
+import { AgentRouteRegistry } from "../agent-routes.mjs";
+import { TaskMessageId, TaskMessageProtocolBinding } from "../schema/task-message.mjs";
+import { IsoDateTimeClock, MaybePromise } from "../schema/common.mjs";
+import { TaskAttemptRef } from "../schema/execution.mjs";
+import { FactoryStores } from "../store/engine.mjs";
+import { DispatchBudget } from "../dispatch.mjs";
+import { z } from "zod";
+//#region src/planning/contracts.d.ts
+/** Minimal persistence capabilities required by the recursive planner runtime. */
+type PlannerStores = Pick<FactoryStores, "answers" | "graphs" | "messages" | "receipts" | "tasks" | "work" | "workflowRecords">;
+/** Validates one bounded, durable decision produced by a planner turn. */
+declare const plannerDecisionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+  action: z.ZodLiteral<"delegate">;
+  summary: z.ZodString;
+  children: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+    key: z.ZodString;
+    title: z.ZodString;
+    instructions: z.ZodString;
+    route: z.core.$ZodBranded<z.ZodObject<{
+      id: z.ZodString;
+      version: z.ZodNumber;
+    }, z.core.$strict>, "AgentRouteBinding", "out">;
+    repositoryIds: z.ZodReadonly<z.ZodArray<z.ZodType<`repo_${string}`, string, z.core.$ZodTypeInternals<`repo_${string}`, string>>>>;
+    completionCriteria: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+    dependsOn: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+  }, z.core.$strict>>>;
+}, z.core.$strict>, z.ZodObject<{
+  action: z.ZodLiteral<"wait">;
+  summary: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+  action: z.ZodLiteral<"complete">;
+  summary: z.ZodString;
+  output: z.ZodJSONSchema;
+  evidenceTaskIds: z.ZodReadonly<z.ZodArray<z.ZodType<`task_${string}`, string, z.core.$ZodTypeInternals<`task_${string}`, string>>>>;
+}, z.core.$strict>, z.ZodObject<{
+  action: z.ZodLiteral<"fail">;
+  reason: z.ZodString;
+}, z.core.$strict>], "action">;
+/** A bounded planner decision that can delegate, wait, complete, or fail. */
+type PlannerDecision = z.infer<typeof plannerDecisionSchema>;
+/** Result of submitting one exact planner trigger for durable decision processing. */
+type PlannerSubmitResult = {
+  readonly status: "busy";
+  readonly messageId: TaskMessageId;
+} | {
+  readonly status: "processed" | "already_processed";
+  readonly messageId: TaskMessageId;
+  readonly decision: PlannerDecision;
+};
+/** Trigger and provider prompt prepared for one exact planner attempt. */
+interface PlannerPrepareResult {
+  readonly triggerId: TaskMessageId;
+  readonly prompt: string;
+}
+/** Structural limits applied to one recursive planner. */
+interface PlannerLimits {
+  readonly maxDepth: number;
+  readonly maxChildren: number;
+  readonly maxTurns: number;
+}
+/** Dependencies, policies, and limits required to run a durable planner. */
+interface PlannerRuntimeOptions {
+  readonly stores: PlannerStores;
+  readonly routes: AgentRouteRegistry;
+  readonly plannerRoute: AgentRouteBinding;
+  readonly workerRoutes: readonly AgentRouteBinding[];
+  readonly budget?: DispatchBudget;
+  /** Publish after the provider turn-finished marker is durable, including idempotent replays. */
+  onTurnFinished?(task: Task): Promise<void>;
+  readonly now?: IsoDateTimeClock;
+  readonly limits?: Partial<PlannerLimits>;
+  /** Launch a fresh Task/attempt-bound session, never a followup. Stable provider keys do not guarantee exactly-once creation. */
+  launchPlanner(task: Task, prompt: string): Promise<ExecutionReference>;
+  canUseRepository?(repositoryId: RepositoryId, task: Task): MaybePromise<boolean>;
+  /** Stop after canonical cancellation. Confirmations are durable; ambiguous failures and concurrent calls must be safe to repeat. */
+  cancelExecution?(task: Task): Promise<void>;
+}
+/** Bounded graph and workflow context supplied to a planner turn. */
+interface PlannerContext extends TaskAttemptRef {
+  readonly triggerId: TaskMessageId;
+  readonly trigger: {
+    readonly fromTaskId: TaskId;
+    readonly type: TaskMessageProtocolBinding;
+    readonly content: string;
+    readonly truncated: boolean;
+  };
+  readonly title: string;
+  readonly repositoryIds: readonly RepositoryId[];
+  readonly repositoriesTruncated: boolean;
+  readonly completionCriteria: readonly string[];
+  readonly criteriaTruncated: boolean;
+  readonly input: string;
+  readonly inputTruncated: boolean;
+  readonly children: readonly {
+    readonly taskId: TaskId;
+    readonly title: string;
+    readonly state: Task["state"];
+    readonly summary: string;
+    readonly truncated: boolean;
+  }[];
+  readonly childrenTruncated: boolean;
+  readonly answers: readonly {
+    readonly question: string;
+    readonly answer: string;
+    readonly answeredBy: string;
+  }[];
+  readonly answersTruncated: boolean;
+  readonly limits: PlannerLimits;
+  readonly routes: readonly {
+    readonly id: string;
+    readonly version: number;
+    readonly description: string;
+  }[];
+}
+/** Effects and recovery outcomes produced by one planner reconciliation pass. */
+interface PlannerReconcileResult {
+  readonly queued: readonly TaskId[];
+  readonly dispatched: readonly TaskId[];
+  readonly delivered: number;
+  readonly recovered: number;
+  readonly discarded: number;
+  readonly cancelled: readonly TaskId[];
+  /** Configured provider stops deferred by the shared callback budget or an ambiguous failure. */
+  readonly cancellationPending?: readonly TaskId[];
+  readonly failed: readonly TaskId[];
+  readonly errors: readonly {
+    readonly taskId: TaskId;
+    readonly message: string;
+  }[];
+}
+//#endregion
+export { PlannerContext, PlannerDecision, PlannerLimits, PlannerPrepareResult, PlannerReconcileResult, PlannerRuntimeOptions, PlannerStores, PlannerSubmitResult, plannerDecisionSchema };
+//# sourceMappingURL=contracts.d.mts.map

package/dist/planning/contracts.mjs

@@ -0,0 +1,42 @@
+import { repositoryIdSchema, taskIdSchema } from "../schema/id.mjs";
+import { agentRouteBindingSchema } from "../schema/agent-route.mjs";
+import { jsonValueSchema } from "../schema/work.mjs";
+import { z } from "zod";
+//#region src/planning/contracts.ts
+const summary = z.string().trim().min(1).max(1e3).describe("Bounded explanation of the planner's decision.");
+const plannerOutputSchema = z.json().refine((value) => jsonValueSchema.safeParse(value).success, "Completion output is too large").describe("Required bounded JSON completion output.");
+const childSchema = z.strictObject({
+	key: z.string().regex(/^[a-z][a-z0-9-]{0,63}$/).describe("Unique sibling key within this delegation batch."),
+	title: z.string().trim().min(1).max(256).describe("Child work title."),
+	instructions: z.string().trim().min(1).max(16e3).describe("Instructions stored in the child's work input."),
+	route: agentRouteBindingSchema.describe("Exact configured worker or recursive planner route."),
+	repositoryIds: z.array(repositoryIdSchema).min(1).max(32).readonly().describe("Distinct repositories, restricted to the parent's scope."),
+	completionCriteria: z.array(z.string().trim().min(1).max(2048)).max(32).readonly().describe("Explicit child completion criteria."),
+	dependsOn: z.array(z.string().min(1).max(69)).max(255).readonly().describe("Sibling keys in this batch or existing same-root Task IDs.")
+});
+/** Validates one bounded, durable decision produced by a planner turn. */
+const plannerDecisionSchema = z.discriminatedUnion("action", [
+	z.strictObject({
+		action: z.literal("delegate").describe("Admit bounded children and wait for results."),
+		summary,
+		children: z.array(childSchema).min(1).max(8).readonly().describe("At most eight new children, validated together before effects.")
+	}),
+	z.strictObject({
+		action: z.literal("wait").describe("Wait only while a direct child is outstanding."),
+		summary
+	}),
+	z.strictObject({
+		action: z.literal("complete").describe("Explicitly complete after all direct children are terminal."),
+		summary,
+		output: plannerOutputSchema,
+		evidenceTaskIds: z.array(taskIdSchema).max(32).readonly().describe("Successful owned direct children deliberately supporting completion.")
+	}),
+	z.strictObject({
+		action: z.literal("fail").describe("Fail this planner and reconcile cancellation of unfinished descendants."),
+		reason: summary.describe("Reason for failing the planner.")
+	})
+]).refine((value) => jsonValueSchema.safeParse(value).success, "Decision must fit bounded work JSON");
+//#endregion
+export { plannerDecisionSchema };
+
+//# sourceMappingURL=contracts.mjs.map

package/dist/planning/contracts.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.mjs","names":[],"sources":["../../src/planning/contracts.ts"],"sourcesContent":["import { z } from \"zod\";\nimport type { IsoDateTimeClock, MaybePromise } from \"../schema/common\";\nimport {\n  agentRouteBindingSchema,\n  type AgentRouteBinding,\n  type AgentRouteRegistry,\n} from \"../agent-routes\";\nimport type { DispatchBudget } from \"../dispatch\";\nimport type { TaskAttemptRef } from \"../schema/execution\";\nimport { repositoryIdSchema, taskIdSchema, type RepositoryId, type TaskId } from \"../schema/id\";\nimport type { ExecutionReference, Task } from \"../schema/task\";\nimport type { TaskMessageId, TaskMessageProtocolBinding } from \"../schema/task-message\";\nimport { jsonValueSchema } from \"../schema/work\";\nimport type { FactoryStores } from \"../store/engine\";\n\n/** Minimal persistence capabilities required by the recursive planner runtime. */\nexport type PlannerStores = Pick<\n  FactoryStores,\n  \"answers\" | \"graphs\" | \"messages\" | \"receipts\" | \"tasks\" | \"work\" | \"workflowRecords\"\n>;\n\nconst summary = z\n  .string()\n  .trim()\n  .min(1)\n  .max(1000)\n  .describe(\"Bounded explanation of the planner's decision.\");\nconst plannerOutputSchema = z\n  .json()\n  .refine((value) => jsonValueSchema.safeParse(value).success, \"Completion output is too large\")\n  .describe(\"Required bounded JSON completion output.\");\nconst childSchema = z.strictObject({\n  key: z\n    .string()\n    .regex(/^[a-z][a-z0-9-]{0,63}$/)\n    .describe(\"Unique sibling key within this delegation batch.\"),\n  title: z.string().trim().min(1).max(256).describe(\"Child work title.\"),\n  instructions: z\n    .string()\n    .trim()\n    .min(1)\n    .max(16_000)\n    .describe(\"Instructions stored in the child's work input.\"),\n  route: agentRouteBindingSchema.describe(\"Exact configured worker or recursive planner route.\"),\n  repositoryIds: z\n    .array(repositoryIdSchema)\n    .min(1)\n    .max(32)\n    .readonly()\n    .describe(\"Distinct repositories, restricted to the parent's scope.\"),\n  completionCriteria: z\n    .array(z.string().trim().min(1).max(2048))\n    .max(32)\n    .readonly()\n    .describe(\"Explicit child completion criteria.\"),\n  dependsOn: z\n    .array(z.string().min(1).max(69))\n    .max(255)\n    .readonly()\n    .describe(\"Sibling keys in this batch or existing same-root Task IDs.\"),\n});\n/** Validates one bounded, durable decision produced by a planner turn. */\nexport const plannerDecisionSchema = z\n  .discriminatedUnion(\"action\", [\n    z.strictObject({\n      action: z.literal(\"delegate\").describe(\"Admit bounded children and wait for results.\"),\n      summary,\n      children: z\n        .array(childSchema)\n        .min(1)\n        .max(8)\n        .readonly()\n        .describe(\"At most eight new children, validated together before effects.\"),\n    }),\n    z.strictObject({\n      action: z.literal(\"wait\").describe(\"Wait only while a direct child is outstanding.\"),\n      summary,\n    }),\n    z.strictObject({\n      action: z\n        .literal(\"complete\")\n        .describe(\"Explicitly complete after all direct children are terminal.\"),\n      summary,\n      output: plannerOutputSchema,\n      evidenceTaskIds: z\n        .array(taskIdSchema)\n        .max(32)\n        .readonly()\n        .describe(\"Successful owned direct children deliberately supporting completion.\"),\n    }),\n    z.strictObject({\n      action: z\n        .literal(\"fail\")\n        .describe(\"Fail this planner and reconcile cancellation of unfinished descendants.\"),\n      reason: summary.describe(\"Reason for failing the planner.\"),\n    }),\n  ])\n  .refine(\n    (value) => jsonValueSchema.safeParse(value).success,\n    \"Decision must fit bounded work JSON\",\n  );\n\n/** A bounded planner decision that can delegate, wait, complete, or fail. */\nexport type PlannerDecision = z.infer<typeof plannerDecisionSchema>;\n\n/** Result of submitting one exact planner trigger for durable decision processing. */\nexport type PlannerSubmitResult =\n  | { readonly status: \"busy\"; readonly messageId: TaskMessageId }\n  | {\n      readonly status: \"processed\" | \"already_processed\";\n      readonly messageId: TaskMessageId;\n      readonly decision: PlannerDecision;\n    };\n\n/** Trigger and provider prompt prepared for one exact planner attempt. */\nexport interface PlannerPrepareResult {\n  readonly triggerId: TaskMessageId;\n  readonly prompt: string;\n}\n\n/** Structural limits applied to one recursive planner. */\nexport interface PlannerLimits {\n  readonly maxDepth: number;\n  readonly maxChildren: number;\n  readonly maxTurns: number;\n}\n/** Dependencies, policies, and limits required to run a durable planner. */\nexport interface PlannerRuntimeOptions {\n  readonly stores: PlannerStores;\n  readonly routes: AgentRouteRegistry;\n  readonly plannerRoute: AgentRouteBinding;\n  readonly workerRoutes: readonly AgentRouteBinding[];\n  readonly budget?: DispatchBudget;\n  /** Publish after the provider turn-finished marker is durable, including idempotent replays. */\n  onTurnFinished?(task: Task): Promise<void>;\n  readonly now?: IsoDateTimeClock;\n  readonly limits?: Partial<PlannerLimits>;\n  /** Launch a fresh Task/attempt-bound session, never a followup. Stable provider keys do not guarantee exactly-once creation. */\n  launchPlanner(task: Task, prompt: string): Promise<ExecutionReference>;\n  canUseRepository?(repositoryId: RepositoryId, task: Task): MaybePromise<boolean>;\n  /** Stop after canonical cancellation. Confirmations are durable; ambiguous failures and concurrent calls must be safe to repeat. */\n  cancelExecution?(task: Task): Promise<void>;\n}\n/** Bounded graph and workflow context supplied to a planner turn. */\nexport interface PlannerContext extends TaskAttemptRef {\n  readonly triggerId: TaskMessageId;\n  readonly trigger: {\n    readonly fromTaskId: TaskId;\n    readonly type: TaskMessageProtocolBinding;\n    readonly content: string;\n    readonly truncated: boolean;\n  };\n  readonly title: string;\n  readonly repositoryIds: readonly RepositoryId[];\n  readonly repositoriesTruncated: boolean;\n  readonly completionCriteria: readonly string[];\n  readonly criteriaTruncated: boolean;\n  readonly input: string;\n  readonly inputTruncated: boolean;\n  readonly children: readonly {\n    readonly taskId: TaskId;\n    readonly title: string;\n    readonly state: Task[\"state\"];\n    readonly summary: string;\n    readonly truncated: boolean;\n  }[];\n  readonly childrenTruncated: boolean;\n  readonly answers: readonly {\n    readonly question: string;\n    readonly answer: string;\n    readonly answeredBy: string;\n  }[];\n  readonly answersTruncated: boolean;\n  readonly limits: PlannerLimits;\n  readonly routes: readonly {\n    readonly id: string;\n    readonly version: number;\n    readonly description: string;\n  }[];\n}\n/** Effects and recovery outcomes produced by one planner reconciliation pass. */\nexport interface PlannerReconcileResult {\n  readonly queued: readonly TaskId[];\n  readonly dispatched: readonly TaskId[];\n  readonly delivered: number;\n  readonly recovered: number;\n  readonly discarded: number;\n  readonly cancelled: readonly TaskId[];\n  /** Configured provider stops deferred by the shared callback budget or an ambiguous failure. */\n  readonly cancellationPending?: readonly TaskId[];\n  readonly failed: readonly TaskId[];\n  readonly errors: readonly { readonly taskId: TaskId; readonly message: string }[];\n}\n"],"mappings":";;;;;AAqBA,MAAM,UAAU,EACb,OAAO,CAAC,CACR,KAAK,CAAC,CACN,IAAI,CAAC,CAAC,CACN,IAAI,GAAI,CAAC,CACT,SAAS,gDAAgD;AAC5D,MAAM,sBAAsB,EACzB,KAAK,CAAC,CACN,QAAQ,UAAU,gBAAgB,UAAU,KAAK,CAAC,CAAC,SAAS,gCAAgC,CAAC,CAC7F,SAAS,0CAA0C;AACtD,MAAM,cAAc,EAAE,aAAa;CACjC,KAAK,EACF,OAAO,CAAC,CACR,MAAM,wBAAwB,CAAC,CAC/B,SAAS,kDAAkD;CAC9D,OAAO,EAAE,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,SAAS,mBAAmB;CACrE,cAAc,EACX,OAAO,CAAC,CACR,KAAK,CAAC,CACN,IAAI,CAAC,CAAC,CACN,IAAI,IAAM,CAAC,CACX,SAAS,gDAAgD;CAC5D,OAAO,wBAAwB,SAAS,qDAAqD;CAC7F,eAAe,EACZ,MAAM,kBAAkB,CAAC,CACzB,IAAI,CAAC,CAAC,CACN,IAAI,EAAE,CAAC,CACP,SAAS,CAAC,CACV,SAAS,0DAA0D;CACtE,oBAAoB,EACjB,MAAM,EAAE,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CACzC,IAAI,EAAE,CAAC,CACP,SAAS,CAAC,CACV,SAAS,qCAAqC;CACjD,WAAW,EACR,MAAM,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAChC,IAAI,GAAG,CAAC,CACR,SAAS,CAAC,CACV,SAAS,4DAA4D;AAC1E,CAAC;;AAED,MAAa,wBAAwB,EAClC,mBAAmB,UAAU;CAC5B,EAAE,aAAa;EACb,QAAQ,EAAE,QAAQ,UAAU,CAAC,CAAC,SAAS,8CAA8C;EACrF;EACA,UAAU,EACP,MAAM,WAAW,CAAC,CAClB,IAAI,CAAC,CAAC,CACN,IAAI,CAAC,CAAC,CACN,SAAS,CAAC,CACV,SAAS,gEAAgE;CAC9E,CAAC;CACD,EAAE,aAAa;EACb,QAAQ,EAAE,QAAQ,MAAM,CAAC,CAAC,SAAS,gDAAgD;EACnF;CACF,CAAC;CACD,EAAE,aAAa;EACb,QAAQ,EACL,QAAQ,UAAU,CAAC,CACnB,SAAS,6DAA6D;EACzE;EACA,QAAQ;EACR,iBAAiB,EACd,MAAM,YAAY,CAAC,CACnB,IAAI,EAAE,CAAC,CACP,SAAS,CAAC,CACV,SAAS,sEAAsE;CACpF,CAAC;CACD,EAAE,aAAa;EACb,QAAQ,EACL,QAAQ,MAAM,CAAC,CACf,SAAS,yEAAyE;EACrF,QAAQ,QAAQ,SAAS,iCAAiC;CAC5D,CAAC;AACH,CAAC,CAAC,CACD,QACE,UAAU,gBAAgB,UAAU,KAAK,CAAC,CAAC,SAC5C,qCACF"}

package/dist/planning/dependencies.mjs

@@ -0,0 +1,44 @@
+import { routeKey } from "../agent-routes.mjs";
+//#region src/planning/dependencies.ts
+/** Only the configured planner's owned routed children participate; graph edges, never kind or PR state, establish failure. */
+async function cancelBlockedPlannerChildren(options, config, rootTaskId) {
+	const graph = await options.stores.graphs.get(rootTaskId);
+	if (!graph) throw new Error("Planner graph missing during dependency reconciliation");
+	const cancelled = [];
+	for (let pass = 0; pass < graph.nodes.length; pass++) {
+		let changed = false;
+		for (const node of graph.nodes) {
+			const parent = graph.nodes.find((entry) => entry.taskId === node.parentTaskId)?.admission;
+			const route = node.admission.work.route;
+			if (!parent || !config.isPlanner(parent) || !route || !config.allowed.has(routeKey(route)) || node.admission.question) continue;
+			const task = await options.stores.tasks.get(node.taskId);
+			if (!task || task.state !== "queued") continue;
+			const dependencies = (await options.stores.graphs.get(rootTaskId))?.nodes.find((entry) => entry.taskId === task.id)?.dependencies;
+			if (!dependencies) throw new Error("Planner dependency membership missing");
+			const failed = [];
+			for (const id of dependencies) {
+				const dependency = await options.stores.tasks.get(id);
+				if (dependency?.state === "failed" || dependency?.state === "cancelled") failed.push(id);
+			}
+			if (!failed.length) continue;
+			try {
+				const stopped = await options.stores.tasks.transition(task.id, "cancelled", {
+					expectFrom: "queued",
+					expectAttempt: task.attempt,
+					phase: "workflow",
+					reason: `Planner dependency failed or cancelled: ${failed.join(", ")}`.slice(0, 1e3)
+				});
+				cancelled.push(stopped);
+				changed = true;
+			} catch (error) {
+				if ((await options.stores.tasks.get(task.id))?.state === "queued") throw error;
+			}
+		}
+		if (!changed) break;
+	}
+	return cancelled;
+}
+//#endregion
+export { cancelBlockedPlannerChildren };
+
+//# sourceMappingURL=dependencies.mjs.map

package/dist/planning/dependencies.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependencies.mjs","names":[],"sources":["../../src/planning/dependencies.ts"],"sourcesContent":["import { routeKey } from \"../agent-routes\";\nimport type { TaskId } from \"../schema/id\";\nimport type { Task } from \"../schema/task\";\nimport type { PlannerConfiguration } from \"./configuration\";\nimport type { PlannerRuntimeOptions } from \"./contracts\";\n\n/** Only the configured planner's owned routed children participate; graph edges, never kind or PR state, establish failure. */\nexport async function cancelBlockedPlannerChildren(\n  options: PlannerRuntimeOptions,\n  config: PlannerConfiguration,\n  rootTaskId: TaskId,\n): Promise<Task[]> {\n  const graph = await options.stores.graphs.get(rootTaskId);\n  if (!graph) throw new Error(\"Planner graph missing during dependency reconciliation\");\n  const cancelled: Task[] = [];\n  for (let pass = 0; pass < graph.nodes.length; pass++) {\n    let changed = false;\n    for (const node of graph.nodes) {\n      const parent = graph.nodes.find((entry) => entry.taskId === node.parentTaskId)?.admission;\n      const route = node.admission.work.route;\n      if (\n        !parent ||\n        !config.isPlanner(parent) ||\n        !route ||\n        !config.allowed.has(routeKey(route)) ||\n        node.admission.question\n      )\n        continue;\n      const task = await options.stores.tasks.get(node.taskId);\n      if (!task || task.state !== \"queued\") continue;\n      const currentGraph = await options.stores.graphs.get(rootTaskId);\n      const dependencies = currentGraph?.nodes.find(\n        (entry) => entry.taskId === task.id,\n      )?.dependencies;\n      if (!dependencies) throw new Error(\"Planner dependency membership missing\");\n      const failed = [];\n      for (const id of dependencies) {\n        const dependency = await options.stores.tasks.get(id);\n        if (dependency?.state === \"failed\" || dependency?.state === \"cancelled\") failed.push(id);\n      }\n      if (!failed.length) continue;\n      try {\n        const stopped = await options.stores.tasks.transition(task.id, \"cancelled\", {\n          expectFrom: \"queued\",\n          expectAttempt: task.attempt,\n          phase: \"workflow\",\n          reason: `Planner dependency failed or cancelled: ${failed.join(\", \")}`.slice(0, 1000),\n        });\n        cancelled.push(stopped);\n        changed = true;\n      } catch (error) {\n        if ((await options.stores.tasks.get(task.id))?.state === \"queued\") throw error;\n      }\n    }\n    if (!changed) break;\n  }\n  return cancelled;\n}\n"],"mappings":";;;AAOA,eAAsB,6BACpB,SACA,QACA,YACiB;CACjB,MAAM,QAAQ,MAAM,QAAQ,OAAO,OAAO,IAAI,UAAU;CACxD,IAAI,CAAC,OAAO,MAAM,IAAI,MAAM,wDAAwD;CACpF,MAAM,YAAoB,CAAC;CAC3B,KAAK,IAAI,OAAO,GAAG,OAAO,MAAM,MAAM,QAAQ,QAAQ;EACpD,IAAI,UAAU;EACd,KAAK,MAAM,QAAQ,MAAM,OAAO;GAC9B,MAAM,SAAS,MAAM,MAAM,MAAM,UAAU,MAAM,WAAW,KAAK,YAAY,CAAC,EAAE;GAChF,MAAM,QAAQ,KAAK,UAAU,KAAK;GAClC,IACE,CAAC,UACD,CAAC,OAAO,UAAU,MAAM,KACxB,CAAC,SACD,CAAC,OAAO,QAAQ,IAAI,SAAS,KAAK,CAAC,KACnC,KAAK,UAAU,UAEf;GACF,MAAM,OAAO,MAAM,QAAQ,OAAO,MAAM,IAAI,KAAK,MAAM;GACvD,IAAI,CAAC,QAAQ,KAAK,UAAU,UAAU;GAEtC,MAAM,gBAAe,MADM,QAAQ,OAAO,OAAO,IAAI,UAAU,EAAA,EAC5B,MAAM,MACtC,UAAU,MAAM,WAAW,KAAK,EACnC,CAAC,EAAE;GACH,IAAI,CAAC,cAAc,MAAM,IAAI,MAAM,uCAAuC;GAC1E,MAAM,SAAS,CAAC;GAChB,KAAK,MAAM,MAAM,cAAc;IAC7B,MAAM,aAAa,MAAM,QAAQ,OAAO,MAAM,IAAI,EAAE;IACpD,IAAI,YAAY,UAAU,YAAY,YAAY,UAAU,aAAa,OAAO,KAAK,EAAE;GACzF;GACA,IAAI,CAAC,OAAO,QAAQ;GACpB,IAAI;IACF,MAAM,UAAU,MAAM,QAAQ,OAAO,MAAM,WAAW,KAAK,IAAI,aAAa;KAC1E,YAAY;KACZ,eAAe,KAAK;KACpB,OAAO;KACP,QAAQ,2CAA2C,OAAO,KAAK,IAAI,IAAI,MAAM,GAAG,GAAI;IACtF,CAAC;IACD,UAAU,KAAK,OAAO;IACtB,UAAU;GACZ,SAAS,OAAO;IACd,KAAK,MAAM,QAAQ,OAAO,MAAM,IAAI,KAAK,EAAE,EAAA,EAAI,UAAU,UAAU,MAAM;GAC3E;EACF;EACA,IAAI,CAAC,SAAS;CAChB;CACA,OAAO;AACT"}

package/dist/planning/effects.mjs

@@ -0,0 +1,122 @@
+import { repositoryIdsSchema, taskIdSchema } from "../schema/id.mjs";
+import { routeKey, routeTaskWork } from "../agent-routes.mjs";
+import { plannerCancellationBatch } from "./cancellation.mjs";
+import { terminal } from "./state.mjs";
+import { orderedChildren, validateChildScope, validatePlannerDecision } from "./validation.mjs";
+//#region src/planning/effects.ts
+/** Task/graph writes are not atomic; repeated reconciliation catches admission/cancellation races. */
+async function cancelDescendants(options, parent, cancellations = plannerCancellationBatch(options)) {
+	const tasks = await options.stores.work.recover(parent.rootTaskId);
+	const owned = /* @__PURE__ */ new Set([parent.id]);
+	for (let pass = 0; pass < tasks.length; pass++) {
+		const previous = owned.size;
+		for (const task of tasks) if (task.parentTaskId && owned.has(task.parentTaskId)) owned.add(task.id);
+		if (previous === owned.size) break;
+	}
+	const cancelled = [];
+	const failures = [];
+	for (const candidate of tasks) {
+		if (candidate.id === parent.id || !owned.has(candidate.id)) continue;
+		const current = await options.stores.tasks.get(candidate.id);
+		if (!current) continue;
+		if (terminal(current)) {
+			try {
+				await cancellations.stop(current);
+			} catch (error) {
+				failures.push(error);
+			}
+			continue;
+		}
+		try {
+			const stopped = await options.stores.tasks.transition(current.id, "cancelled", {
+				expectFrom: current.state,
+				expectAttempt: current.attempt,
+				reason: `Planner ancestor ${parent.id} ${parent.state}`,
+				phase: "workflow"
+			});
+			cancelled.push(current.id);
+			try {
+				await cancellations.stop(stopped);
+			} catch (error) {
+				failures.push(error);
+			}
+		} catch (error) {
+			const latest = await options.stores.tasks.get(candidate.id);
+			if (!latest || !terminal(latest)) failures.push(error);
+		}
+	}
+	if (failures.length) throw new AggregateError(failures, `Planner ${parent.id} descendant cancellation needs reconciliation`);
+	return cancelled;
+}
+function plannerEffects(options, config, state) {
+	return async (task, decision, effectKey, cancellations) => {
+		const current = await state.authority(task, true);
+		if (decision.action === "fail") {
+			await cancelDescendants(options, current.state === "failed" ? current : await options.stores.tasks.transition(task.id, "failed", {
+				expectFrom: "running",
+				expectAttempt: task.attempt,
+				reason: decision.reason,
+				phase: "workflow"
+			}), cancellations);
+			return;
+		}
+		if (decision.action === "complete") {
+			if (current.state !== "succeeded") await validatePlannerDecision(options, config, current, decision);
+			if (current.state === "succeeded") await options.stores.work.complete({
+				task: {
+					taskId: task.id,
+					attempt: task.attempt
+				},
+				output: decision.output
+			});
+			else await options.stores.tasks.transition(task.id, "succeeded", {
+				expectFrom: "running",
+				expectAttempt: task.attempt,
+				output: decision.output,
+				reason: decision.summary,
+				phase: "workflow"
+			});
+			return;
+		}
+		if (current.state !== "running") throw new Error("Delegation and wait effects require a running planner");
+		if (decision.action === "delegate") {
+			validateChildScope(current, decision, config);
+			const ids = /* @__PURE__ */ new Map();
+			for (const child of orderedChildren(decision)) {
+				await state.authority(task);
+				const route = config.allowed.get(routeKey(child.route));
+				if (!route) throw new Error("Planner child route is no longer permitted");
+				const created = await options.stores.tasks.create({
+					parentTaskId: task.id,
+					origin: {},
+					repositoryIds: repositoryIdsSchema.parse(child.repositoryIds),
+					kind: route.taskKind,
+					replyTo: current.replyTo,
+					work: {
+						...routeTaskWork({
+							route,
+							title: child.title,
+							input: { instructions: child.instructions }
+						}),
+						completionCriteria: child.completionCriteria
+					},
+					dependencies: child.dependsOn.map((key) => ids.get(key) ?? taskIdSchema.parse(key)),
+					dedupeKey: `${effectKey}:${child.key}`
+				});
+				ids.set(child.key, created.id);
+			}
+		}
+		await state.authority(task);
+		await options.stores.work.waitForMessages({
+			task: {
+				taskId: task.id,
+				attempt: task.attempt
+			},
+			phase: "planner-waiting"
+		});
+	};
+}
+//#endregion
+export { cancelDescendants, plannerEffects };
+
+//# sourceMappingURL=effects.mjs.map

package/dist/planning/effects.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"effects.mjs","names":[],"sources":["../../src/planning/effects.ts"],"sourcesContent":["import { routeKey, routeTaskWork } from \"../agent-routes\";\nimport { repositoryIdsSchema, taskIdSchema, type TaskId } from \"../schema/id\";\nimport type { Task } from \"../schema/task\";\nimport { plannerCancellationBatch, type PlannerCancellationBatch } from \"./cancellation\";\nimport type { PlannerConfiguration } from \"./configuration\";\nimport type { PlannerDecision, PlannerRuntimeOptions } from \"./contracts\";\nimport { terminal, type PlannerState } from \"./state\";\nimport { orderedChildren, validateChildScope, validatePlannerDecision } from \"./validation\";\n\n/** Task/graph writes are not atomic; repeated reconciliation catches admission/cancellation races. */\nexport async function cancelDescendants(\n  options: PlannerRuntimeOptions,\n  parent: Task,\n  cancellations = plannerCancellationBatch(options),\n): Promise<TaskId[]> {\n  const tasks = await options.stores.work.recover(parent.rootTaskId);\n  const owned = new Set([parent.id]);\n  for (let pass = 0; pass < tasks.length; pass++) {\n    const previous = owned.size;\n    for (const task of tasks)\n      if (task.parentTaskId && owned.has(task.parentTaskId)) owned.add(task.id);\n    if (previous === owned.size) break;\n  }\n  const cancelled: TaskId[] = [];\n  const failures: unknown[] = [];\n  for (const candidate of tasks) {\n    if (candidate.id === parent.id || !owned.has(candidate.id)) continue;\n    const current = await options.stores.tasks.get(candidate.id);\n    if (!current) continue;\n    if (terminal(current)) {\n      try {\n        await cancellations.stop(current);\n      } catch (error) {\n        failures.push(error);\n      }\n      continue;\n    }\n    try {\n      const stopped = await options.stores.tasks.transition(current.id, \"cancelled\", {\n        expectFrom: current.state,\n        expectAttempt: current.attempt,\n        reason: `Planner ancestor ${parent.id} ${parent.state}`,\n        phase: \"workflow\",\n      });\n      cancelled.push(current.id);\n      try {\n        await cancellations.stop(stopped);\n      } catch (error) {\n        failures.push(error);\n      }\n    } catch (error) {\n      const latest = await options.stores.tasks.get(candidate.id);\n      if (!latest || !terminal(latest)) failures.push(error);\n    }\n  }\n  if (failures.length)\n    throw new AggregateError(\n      failures,\n      `Planner ${parent.id} descendant cancellation needs reconciliation`,\n    );\n  return cancelled;\n}\n\nexport function plannerEffects(\n  options: PlannerRuntimeOptions,\n  config: PlannerConfiguration,\n  state: PlannerState,\n) {\n  return async (\n    task: Task,\n    decision: PlannerDecision,\n    effectKey: string,\n    cancellations?: PlannerCancellationBatch,\n  ): Promise<void> => {\n    const current = await state.authority(task, true);\n    if (decision.action === \"fail\") {\n      const failed =\n        current.state === \"failed\"\n          ? current\n          : await options.stores.tasks.transition(task.id, \"failed\", {\n              expectFrom: \"running\",\n              expectAttempt: task.attempt,\n              reason: decision.reason,\n              phase: \"workflow\",\n            });\n      await cancelDescendants(options, failed, cancellations);\n      return;\n    }\n    if (decision.action === \"complete\") {\n      if (current.state !== \"succeeded\")\n        await validatePlannerDecision(options, config, current, decision);\n      if (current.state === \"succeeded\")\n        await options.stores.work.complete({\n          task: { taskId: task.id, attempt: task.attempt },\n          output: decision.output,\n        });\n      else\n        await options.stores.tasks.transition(task.id, \"succeeded\", {\n          expectFrom: \"running\",\n          expectAttempt: task.attempt,\n          output: decision.output,\n          reason: decision.summary,\n          phase: \"workflow\",\n        });\n      return;\n    }\n    if (current.state !== \"running\")\n      throw new Error(\"Delegation and wait effects require a running planner\");\n    if (decision.action === \"delegate\") {\n      validateChildScope(current, decision, config);\n      const ids = new Map<string, TaskId>();\n      for (const child of orderedChildren(decision)) {\n        await state.authority(task);\n        const route = config.allowed.get(routeKey(child.route));\n        if (!route) throw new Error(\"Planner child route is no longer permitted\");\n        const created = await options.stores.tasks.create({\n          parentTaskId: task.id,\n          origin: {},\n          repositoryIds: repositoryIdsSchema.parse(child.repositoryIds),\n          kind: route.taskKind,\n          replyTo: current.replyTo,\n          work: {\n            ...routeTaskWork({\n              route: route,\n              title: child.title,\n              input: { instructions: child.instructions },\n            }),\n            completionCriteria: child.completionCriteria,\n          },\n          dependencies: child.dependsOn.map((key) => ids.get(key) ?? taskIdSchema.parse(key)),\n          dedupeKey: `${effectKey}:${child.key}`,\n        });\n        ids.set(child.key, created.id);\n      }\n    }\n    await state.authority(task);\n    await options.stores.work.waitForMessages({\n      task: { taskId: task.id, attempt: task.attempt },\n      phase: \"planner-waiting\",\n    });\n  };\n}\n"],"mappings":"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"}