@warlock.js/ai 4.3.0 → 4.4.0

package/esm/contracts/planner/planner-result.type.d.mts

@@ -8,9 +8,15 @@ import { PlannerPlan, PlannerStep } from "./planner-plan.type.mjs";
 /**
  * Discriminator literal the planner stamps onto its report's `type`
  * field. A member of the shared
- * {@link import("../result/base-report.type").ReportType} closed union,
- * so {@link PlannerReport} narrows `type` against the shared union
- * directly rather than overriding it.
+ * {@link import("../result/base-report.type").ReportType} closed union.
+ *
+ * {@link PlannerReport} re-declares `type` as this literal by *overriding*
+ * it (`Omit<BaseReport, "type"> & { type: PlannerReportType }`) rather than
+ * intersecting (`BaseReport & { type: "planner" }`). Intersecting a single
+ * literal against `BaseReport.type` (the whole `ReportType` union) lets a
+ * strict TypeScript collapse the entire report to `never` ("property `type`
+ * has conflicting types in some constituents"); the `Omit` override sidesteps
+ * that while still producing the same `type: "planner"` for consumers.
  */
 type PlannerReportType = "planner";
 /**
@@ -45,7 +51,7 @@ type PlannerStepSnapshot = {
  * per-step record (one entry per step the planner attempted), and
  * `plan` is the verbatim LLM output before any step ran.
  */
-type PlannerReport = BaseReport & {
+type PlannerReport = Omit<BaseReport, "type"> & {
   type: PlannerReportType; /** Structural fingerprint — same value exposed on the planner instance. */
   signature: string; /** The full plan the planner's LLM generated before execution began. */
   plan?: PlannerPlan; /** Per-step forensic records, in execution order. */
@@ -73,7 +79,7 @@ type PlannerReport = BaseReport & {
  *
  * console.log(report.plan?.summary, usage.total);
  */
-type PlannerResult<TOutput = unknown> = ExecuteResult<TOutput> & {
+type PlannerResult<TOutput = unknown> = Omit<ExecuteResult<TOutput>, "report"> & {
   /** Discriminant for narrowing a heterogeneous result union. */type: "planner";
   report: PlannerReport;
 };

package/esm/contracts/planner/planner-result.type.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"planner-result.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/planner/planner-result.type.ts"],"mappings":";;;;;;;;;AAaA;;;;AAA6B;KAAjB,iBAAA;;;;;;;;;;KAWA,mBAAA;EAIJ,0DAFN,KAAA,UAMA;EAJA,IAAA,EAAM,WAAA,EAME;EAJR,MAAA,sCAMA;EAJA,MAAA,YAMA;EAJA,KAAA,GAAQ,OAAA;EACR,SAAA;EACA,OAAA;EACA,QAAA;EACA,KAAA,EAAO,KAAA,EAgBG;EAdV,WAAA,GAAc,UAAA;AAAA;;;;;;;;;;;;KAcJ,aAAA,GAAgB,UAAA;EAC1B,IAAA,EAAM,iBAAA,EAMS;EAJf,SAAA,UAMW;EAJX,IAAA,GAAO,WAAA,EA4BG;EA1BV,aAAA,EAAe,mBAAA,IA0BQ;EAxBvB,WAAA;AAAA;;;;;;;;;;;AA2BqB;;;;;;;;;;;KAHX,aAAA,sBAAmC,aAAA,CAAc,OAAA;iEAE3D,IAAA;EACA,MAAA,EAAQ,aAAA;AAAA"}
+{"version":3,"file":"planner-result.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/planner/planner-result.type.ts"],"mappings":";;;;;;;;;AAmBA;;;;AAA6B;AAW7B;;;;;;KAXY,iBAAA;;;;;;;;;;KAWA,mBAAA;EAYV,0DAVA,KAAA,UAYA;EAVA,IAAA,EAAM,WAAA,EAYN;EAVA,MAAA,sCAUwB;EARxB,MAAA,YAsBU;EApBV,KAAA,GAAQ,OAAA;EACR,SAAA;EACA,OAAA;EACA,QAAA;EACA,KAAA,EAAO,KAAA,EAqBA;EAnBP,WAAA,GAAc,UAAA;AAAA;;;;;;;;;;;;KAcJ,aAAA,GAAgB,IAAA,CAAK,UAAA;EAC/B,IAAA,EAAM,iBAAA,EAgCI;EA9BV,SAAA,UA8BuB;EA5BvB,IAAA,GAAO,WAAA,EA4B2C;EA1BlD,aAAA,EAAe,mBAAA,IA6BP;EA3BR,WAAA;AAAA;;;;;;;;;AA2BqB;;;;;;;;;;;;;KAHX,aAAA,sBAAmC,IAAA,CAAK,aAAA,CAAc,OAAA;iEAEhE,IAAA;EACA,MAAA,EAAQ,aAAA;AAAA"}

package/esm/contracts/result/orchestrator-result.type.d.mts

@@ -9,10 +9,14 @@ import { AgentBranchSnapshot } from "../supervisor/iteration-snapshot.type.mjs";
 //#region ../@warlock.js/ai/src/contracts/result/orchestrator-result.type.d.ts
 /**
  * Discriminator literal the orchestrator stamps onto its report's
- * `type` field (design §15.5). Now a member of the shared
- * {@link ReportType} closed union in `base-report.type.ts`, so
- * {@link OrchestratorReport} narrows `type` against the shared union
- * directly rather than overriding it.
+ * `type` field (design §15.5). A member of the shared
+ * {@link ReportType} closed union in `base-report.type.ts`.
+ *
+ * {@link OrchestratorReport} re-declares `type` as this literal by
+ * *overriding* it (`Omit<BaseReport, "type"> & { type: ... }`) rather than
+ * intersecting `BaseReport` with it: intersecting a single literal against
+ * `BaseReport.type` (the whole `ReportType` union) lets a strict TypeScript
+ * collapse the report to `never` ("conflicting types in some constituents").
  */
 type OrchestratorReportType = "orchestrator";
 /**
@@ -88,13 +92,13 @@ type TurnSnapshot = Readonly<{
  * recurse via `children[]` will NOT reach prior turns — intentional.
  *
  * @remarks
- * `type` and `status` narrow the shared {@link BaseReport} fields to
- * the orchestrator-specific literals. Both `"orchestrator"` and
- * `"awaiting-input"` are now members of the shared {@link ReportType} /
- * {@link ReportStatus} unions, so this inherits {@link BaseReport}
- * directly and re-declares the two fields as compatible narrowings.
+ * `type` and `status` are the orchestrator-specific literals — both
+ * `"orchestrator"` and `"awaiting-input"` are members of the shared
+ * {@link ReportType} / {@link ReportStatus} unions. `type` is OVERRIDDEN
+ * via `Omit<BaseReport, "type">` (not intersected) so a strict TypeScript
+ * can't collapse the report to `never`; `status` is re-declared compatibly.
  */
-type OrchestratorReport = BaseReport & {
+type OrchestratorReport = Omit<BaseReport, "type"> & {
   type: OrchestratorReportType;
   status: OrchestratorReportStatus;
   sessionId: string;
@@ -128,7 +132,7 @@ type OrchestratorReport = BaseReport & {
  *   await myMessageStore.applyCompaction(result.sessionId, result.compaction);
  * }
  */
-type OrchestratorResult<TOutput = unknown> = ExecuteResult<TOutput> & {
+type OrchestratorResult<TOutput = unknown> = Omit<ExecuteResult<TOutput>, "report"> & {
   sessionId: string;
   turnIndex: number;
   compaction?: CompactionResult;

package/esm/contracts/result/orchestrator-result.type.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"orchestrator-result.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/result/orchestrator-result.type.ts"],"mappings":";;;;;;;;;;;AAeA;;;;AAAkC;KAAtB,sBAAA;;;;AAS0B;AAStC;;;KATY,0BAAA;AASoE;AAWhF;;;;;;AAXgF,KAApE,wBAAA,GAA2B,YAAA,GAAe,0BAA0B;;;AAiB/D;AAajB;;;;;;KAnBY,gBAAA;EAuCH,6DArCP,OAAA,EAAS,OAAO,EAiBS;EAfzB,iBAAA,UAeiC;EAbjC,eAAA;AAAA;;;;;;;;;;;KAaU,YAAA,GAAe,QAAA;EAgBd,gCAdX,IAAA,UAgBA;EAdA,KAAA,EAAO,eAAA,EAgBP;EAdA,QAAA;IACE,MAAA;IACA,GAAA;IACA,SAAA;EAAA,GAqCQ;EAlCV,MAAA,EAAQ,MAAA,SAAe,mBAAA;EAEvB,KAAA,WAiCM;EA/BN,QAAA,GAAW,cAAA;EACX,SAAA;EACA,OAAA;EACA,QAAA;EACA,KAAA,EAAO,KAAA;EA2BP;;;;;EArBA,WAAA,GAAc,UAAA;AAAA;;;;;AA6BK;AA4BrB;;;;;;;;;;;;KArCY,kBAAA,GAAqB,UAAA;EAC/B,IAAA,EAAM,sBAAA;EACN,MAAA,EAAQ,wBAAA;EACR,SAAA;EACA,SAAA,UAqCQ;EAnCR,SAAA;EACA,OAAA;EAEA,KAAA,EAAO,YAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;KA4BG,kBAAA,sBAAwC,aAAA,CAAc,OAAA;EAChE,SAAA;EACA,SAAA;EACA,UAAA,GAAa,gBAAA;EACb,MAAA,EAAQ,kBAAA;AAAA"}
+{"version":3,"file":"orchestrator-result.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/result/orchestrator-result.type.ts"],"mappings":";;;;;;;;;;;AAmBA;;;;AAAkC;AASlC;;;;KATY,sBAAA;AAkBZ;;;;AAAgF;AAWhF;;AAXA,KATY,0BAAA;;;;;;;AA0BK;KAjBL,wBAAA,GAA2B,YAAA,GAAe,0BAA0B;;;;;;;;;;KAWpE,gBAAA;EAmBuB,6DAjBjC,OAAA,EAAS,OAAO,EAmBhB;EAjBA,iBAAA,UAmBO;EAjBP,eAAA;AAAA;;;;;;;;;;;KAaU,YAAA,GAAe,QAAA;EAoBzB,gCAlBA,IAAA,UAwBA;EAtBA,KAAA,EAAO,eAAA,EAsBiB;EApBxB,QAAA;IACE,MAAA;IACA,GAAA;IACA,SAAA;EAAA,GAqC6B;EAlC/B,MAAA,EAAQ,MAAA,SAAe,mBAAA,GAoCf;EAlCR,KAAA,WAyCmB;EAvCnB,QAAA,GAAW,cAAA;EACX,SAAA;EACA,OAAA;EACA,QAAA;EACA,KAAA,EAAO,KAAA;EA4BP;;;;;EAtBA,WAAA,GAAc,UAAA;AAAA;;;AA6BK;AA4BrB;;;;;;;;;;;;;;KArCY,kBAAA,GAAqB,IAAA,CAAK,UAAA;EACpC,IAAA,EAAM,sBAAA;EACN,MAAA,EAAQ,wBAAA;EACR,SAAA;EACA,SAAA,UAqCQ;EAnCR,SAAA;EACA,OAAA;EAEA,KAAA,EAAO,YAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;KA4BG,kBAAA,sBAAwC,IAAA,CAAK,aAAA,CAAc,OAAA;EACrE,SAAA;EACA,SAAA;EACA,UAAA,GAAa,gBAAA;EACb,MAAA,EAAQ,kBAAA;AAAA"}

package/esm/contracts/result/supervisor-result.type.d.mts

@@ -24,7 +24,7 @@ type SupervisorTerminatedBy = "router" | "route" | "classifier" | "evaluate" | "
  * on {@link BaseReport.children}, which duplicates nothing: it's the
  * reports of the child agents/workflows dispatched across iterations.
  */
-type SupervisorReport = BaseReport & {
+type SupervisorReport = Omit<BaseReport, "type"> & {
   supervisorName: string; /** Structural fingerprint — same value exposed on the instance. */
   signature: string;
   terminatedBy: SupervisorTerminatedBy; /** How many iterations ran (including the terminal one). */

package/esm/contracts/result/supervisor-result.type.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"supervisor-result.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/result/supervisor-result.type.ts"],"mappings":";;;;;;;;AAWA;;;;KAAY,sBAAA;AAsBZ;;;;;;;;;;;;;AAAA,KAAY,gBAAA,GAAmB,UAAA;EAC7B,cAAA,UAKA;EAHA,SAAA;EACA,YAAA,EAAc,sBAAA,EAKH;EAHX,UAAA,UAUM;EARN,WAAA;EACA,SAAA,EAAW,iBAAA;EAgBoB;AAAA;AA+BjC;;;;EAxCE,GAAA,GAAM,WAAA;EA4CE;;;;;;;;EAnCR,UAAA,GAAa,kBAAA;AAAA;;AAmCW;;;;;;;;;;;;;;;;;;;;;;;;;;;KAJd,gBAAA,sBAAsC,UAAA;wEAEhD,IAAA;EACA,IAAA,GAAO,OAAA;EACP,MAAA,EAAQ,gBAAA;AAAA"}
+{"version":3,"file":"supervisor-result.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/result/supervisor-result.type.ts"],"mappings":";;;;;;;;AAWA;;;;KAAY,sBAAA;AAsBZ;;;;;;;;;;;;;AAAA,KAAY,gBAAA,GAAmB,IAAA,CAAK,UAAA;EAClC,cAAA,UAGA;EADA,SAAA;EACA,YAAA,EAAc,sBAAA,EAId;EAFA,UAAA,UAGW;EADX,WAAA;EACA,SAAA,EAAW,iBAAA;EAgBX;;;AAA+B;AA+BjC;;EAxCE,GAAA,GAAM,WAAA;EAwC0C;;;;;;;;EA/BhD,UAAA,GAAa,kBAAA;AAAA;;;;AAmCW;;;;;;;;;;;;;;;;;;;;;;;;;KAJd,gBAAA,sBAAsC,UAAA;wEAEhD,IAAA;EACA,IAAA,GAAO,OAAA;EACP,MAAA,EAAQ,gBAAA;AAAA"}

package/esm/contracts/result/tool-call.type.d.mts

@@ -23,8 +23,8 @@ import { BaseReport } from "./base-report.type.mjs";
  *   console.log(call.name, call.tripIndex, call.input, call.output);
  * }
  */
-type ToolCall = BaseReport & {
-  /** Discriminator already fixed on BaseReport, narrowed to "tool" here. */type: "tool"; /** Which LLM trip triggered this tool call (0-indexed). */
+type ToolCall = Omit<BaseReport, "type"> & {
+  /** Discriminator overridden to "tool" via `Omit<BaseReport, "type">`. */type: "tool"; /** Which LLM trip triggered this tool call (0-indexed). */
   tripIndex: number; /** Input passed to the tool (validated args from the model's request). */
   input: unknown; /** Output returned by the tool (undefined if an error occurred). */
   output?: unknown; /** Typed AI error thrown during dispatch (validation or execute), if any. */

package/esm/contracts/result/tool-call.type.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-call.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/result/tool-call.type.ts"],"mappings":";;;;;;AAwBA;;;;;;;;;;;;;AAmBe;;;;;;KAnBH,QAAA,GAAW,UAAA;4EAErB,IAAA;EAEA,SAAA;EAEA,KAAA;EAEA,MAAA;EAEA,KAAA,GAAQ,OAAO;;;;;;;;;EASf,aAAA;AAAA"}
+{"version":3,"file":"tool-call.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/result/tool-call.type.ts"],"mappings":";;;;;;AAwBA;;;;;;;;;;;;;;;;;;AAmBe;KAnBH,QAAA,GAAW,IAAA,CAAK,UAAA;2EAE1B,IAAA;EAEA,SAAA;EAEA,KAAA;EAEA,MAAA;EAEA,KAAA,GAAQ,OAAA;;;;;;;;;EASR,aAAA;AAAA"}

package/esm/contracts/result/workflow-result.type.d.mts

@@ -14,7 +14,7 @@ import { StepSnapshot } from "./step-result.type.mjs";
  * structure — one entry per defined step — while `children` gives
  * the cross-cutting tree view shared with other primitives.
  */
-type WorkflowReport = BaseReport & {
+type WorkflowReport = Omit<BaseReport, "type"> & {
   workflowName: string; /** Structural fingerprint — same value exposed on the workflow instance. */
   signature: string; /** ISO-8601 timestamp when cancellation was observed, if any. */
   cancelledAt?: string; /** Per-step snapshots keyed by step name. */

package/esm/contracts/result/workflow-result.type.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"workflow-result.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/result/workflow-result.type.ts"],"mappings":";;;;;;;;AAeA;;;;;;;;KAAY,cAAA,GAAiB,UAAA;EAC3B,YAAA,UAD2B;EAG3B,SAAA;EAEA,WAAA,WAEA;EAAA,KAAA,EAAO,MAAA,SAAe,YAAA,GAAA;EAEtB,KAAA,EAAO,QAAA,CAAS,MAAA;AAAA;;;AAAM;AAgBxB;;;;;;;;;;KAAY,cAAA,sBAAoC,UAAA;EAC9C,IAAA;EACA,IAAA,GAAO,OAAA;EACP,MAAA,EAAQ,cAAA;EACR,KAAA,GAAQ,OAAA;AAAA"}
+{"version":3,"file":"workflow-result.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/result/workflow-result.type.ts"],"mappings":";;;;;;;;AAeA;;;;;;;;KAAY,cAAA,GAAiB,IAAA,CAAK,UAAA;EAChC,YAAA,UAQe;EANf,SAAA,UAHgC;EAKhC,WAAA,WAFA;EAIA,KAAA,EAAO,MAAA,SAAe,YAAA,GAAtB;EAEA,KAAA,EAAO,QAAA,CAAS,MAAA;AAAA;;;;;AAAM;AAgBxB;;;;;;;;KAAY,cAAA,sBAAoC,UAAA;EAC9C,IAAA;EACA,IAAA,GAAO,OAAA;EACP,MAAA,EAAQ,cAAA;EACR,KAAA,GAAQ,OAAA;AAAA"}

package/esm/planner/plan-schema.mjs

@@ -19,23 +19,20 @@
 * (the planner still truncates the tail to `skipped` defensively).
 */
 function planSchema(capabilityNames, maxSteps) {
-	const stepsSchema = {
-		type: "array",
-		minItems: 1,
-		description: "Ordered steps to execute, one capability dispatch each.",
-		items: stepItemsSchema(capabilityNames)
-	};
-	if (maxSteps !== void 0) stepsSchema.maxItems = maxSteps;
 	const jsonSchema = {
 		type: "object",
 		properties: {
 			summary: {
-				type: "string",
+				type: ["string", "null"],
 				description: "One-line summary of the overall strategy."
 			},
-			steps: stepsSchema
+			steps: {
+				type: "array",
+				description: "Ordered steps to execute, one capability dispatch each.",
+				items: stepItemsSchema(capabilityNames)
+			}
 		},
-		required: ["steps"],
+		required: ["summary", "steps"],
 		additionalProperties: false
 	};
 	return { "~standard": {
@@ -66,7 +63,7 @@ function stepItemsSchema(capabilityNames) {
 		type: "object",
 		properties: {
 			id: {
-				type: "string",
+				type: ["string", "null"],
 				description: "Stable step id, referenced by dependsOn."
 			},
 			capability: {
@@ -79,16 +76,22 @@ function stepItemsSchema(capabilityNames) {
 				description: "Concrete input passed to the capability's execute()."
 			},
 			reason: {
-				type: "string",
+				type: ["string", "null"],
 				description: "Why this step exists."
 			},
 			dependsOn: {
-				type: "array",
+				type: ["array", "null"],
 				items: { type: "string" },
 				description: "Ids of steps this one conceptually follows."
 			}
 		},
-		required: ["capability", "input"],
+		required: [
+			"id",
+			"capability",
+			"input",
+			"reason",
+			"dependsOn"
+		],
 		additionalProperties: false
 	};
 }

package/esm/planner/plan-schema.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"plan-schema.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/planner/plan-schema.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport type { PlannerPlan, PlannerStep } from \"../contracts/planner/planner-plan.type\";\n\n/**\n * Build the Standard Schema the planning agent emits — an ordered\n * `{ steps: [...], summary? }` plan whose every step references one of\n * `capabilityNames` via the `capability` field.\n *\n * Mirrors the router's hand-built schema approach\n * (`supervisor/router-factory.ts`): the JSON Schema extension carries\n * the capability names as an `enum` so capable providers enforce the\n * choice natively, while `validate()` still accepts the shape softly so\n * providers without native structured output can pass a parsed object\n * through. Validation is intentionally lenient on `capability` — an\n * unknown name is surfaced later by the planner as a typed\n * `PlannerPlanInvalidError`, with the full forensic context, rather\n * than as an opaque schema issue here.\n *\n * `maxSteps`, when provided, is emitted as the `steps` array's\n * `maxItems` so capable providers refuse to over-produce up front\n * (the planner still truncates the tail to `skipped` defensively).\n */\nexport function planSchema(\n  capabilityNames: string[],\n  maxSteps?: number,\n): StandardSchemaV1<PlannerPlan> {\n  const stepsSchema: Record<string, unknown> = {\n    type: \"array\",\n    minItems: 1,\n    description: \"Ordered steps to execute, one capability dispatch each.\",\n    items: stepItemsSchema(capabilityNames),\n  };\n\n  if (maxSteps !== undefined) {\n    stepsSchema.maxItems = maxSteps;\n  }\n\n  const jsonSchema = {\n    type: \"object\",\n    properties: {\n      summary: {\n        type: \"string\",\n        description: \"One-line summary of the overall strategy.\",\n      },\n      steps: stepsSchema,\n    },\n    required: [\"steps\"],\n    additionalProperties: false,\n  };\n\n  return {\n    \"~standard\": {\n      version: 1,\n      vendor: \"warlock-planner\",\n      jsonSchema: {\n        input: () => jsonSchema,\n      },\n      validate(value: unknown): StandardSchemaV1.Result<PlannerPlan> {\n        if (!value || typeof value !== \"object\") {\n          return { issues: [{ message: \"plan must be an object\" }] };\n        }\n\n        const record = value as { steps?: unknown; summary?: unknown };\n\n        if (!Array.isArray(record.steps) || record.steps.length === 0) {\n          return { issues: [{ message: \"plan `steps` must be a non-empty array\" }] };\n        }\n\n        const steps: PlannerStep[] = [];\n\n        for (const raw of record.steps) {\n          const normalized = normalizeStep(raw);\n\n          if (!normalized) {\n            return {\n              issues: [{ message: \"each plan step must carry a string `capability` and `input`\" }],\n            };\n          }\n\n          steps.push(normalized);\n        }\n\n        const summary = typeof record.summary === \"string\" ? record.summary : undefined;\n\n        return { value: summary !== undefined ? { steps, summary } : { steps } };\n      },\n    } as StandardSchemaV1<PlannerPlan>[\"~standard\"] & {\n      jsonSchema: { input: () => Record<string, unknown> };\n    },\n  };\n}\n\n/** Per-step JSON Schema object — one capability dispatch. */\nfunction stepItemsSchema(capabilityNames: string[]): Record<string, unknown> {\n  return {\n    type: \"object\",\n    properties: {\n      id: { type: \"string\", description: \"Stable step id, referenced by dependsOn.\" },\n      capability: {\n        type: \"string\",\n        enum: capabilityNames,\n        description: \"Name of the capability to dispatch for this step.\",\n      },\n      input: {\n        type: \"string\",\n        description: \"Concrete input passed to the capability's execute().\",\n      },\n      reason: { type: \"string\", description: \"Why this step exists.\" },\n      dependsOn: {\n        type: \"array\",\n        items: { type: \"string\" },\n        description: \"Ids of steps this one conceptually follows.\",\n      },\n    },\n    required: [\"capability\", \"input\"],\n    additionalProperties: false,\n  };\n}\n\n/**\n * Coerce one raw step object into a {@link PlannerStep}, returning\n * `undefined` when the mandatory `capability` / `input` strings are\n * missing. Optional fields are copied only when well-typed.\n */\nfunction normalizeStep(raw: unknown): PlannerStep | undefined {\n  if (!raw || typeof raw !== \"object\") {\n    return undefined;\n  }\n\n  const record = raw as {\n    id?: unknown;\n    capability?: unknown;\n    input?: unknown;\n    reason?: unknown;\n    dependsOn?: unknown;\n  };\n\n  if (typeof record.capability !== \"string\" || record.capability.length === 0) {\n    return undefined;\n  }\n\n  if (typeof record.input !== \"string\") {\n    return undefined;\n  }\n\n  const step: PlannerStep = {\n    capability: record.capability,\n    input: record.input,\n  };\n\n  if (typeof record.id === \"string\") {\n    step.id = record.id;\n  }\n\n  if (typeof record.reason === \"string\") {\n    step.reason = record.reason;\n  }\n\n  if (Array.isArray(record.dependsOn) && record.dependsOn.every((entry) => typeof entry === \"string\")) {\n    step.dependsOn = record.dependsOn as string[];\n  }\n\n  return step;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAsBA,SAAgB,WACd,iBACA,UAC+B;CAC/B,MAAM,cAAuC;EAC3C,MAAM;EACN,UAAU;EACV,aAAa;EACb,OAAO,gBAAgB,eAAe;CACxC;CAEA,IAAI,aAAa,QACf,YAAY,WAAW;CAGzB,MAAM,aAAa;EACjB,MAAM;EACN,YAAY;GACV,SAAS;IACP,MAAM;IACN,aAAa;GACf;GACA,OAAO;EACT;EACA,UAAU,CAAC,OAAO;EAClB,sBAAsB;CACxB;CAEA,OAAO,EACL,aAAa;EACX,SAAS;EACT,QAAQ;EACR,YAAY,EACV,aAAa,WACf;EACA,SAAS,OAAsD;GAC7D,IAAI,CAAC,SAAS,OAAO,UAAU,UAC7B,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS,yBAAyB,CAAC,EAAE;GAG3D,MAAM,SAAS;GAEf,IAAI,CAAC,MAAM,QAAQ,OAAO,KAAK,KAAK,OAAO,MAAM,WAAW,GAC1D,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS,yCAAyC,CAAC,EAAE;GAG3E,MAAM,QAAuB,CAAC;GAE9B,KAAK,MAAM,OAAO,OAAO,OAAO;IAC9B,MAAM,aAAa,cAAc,GAAG;IAEpC,IAAI,CAAC,YACH,OAAO,EACL,QAAQ,CAAC,EAAE,SAAS,8DAA8D,CAAC,EACrF;IAGF,MAAM,KAAK,UAAU;GACvB;GAEA,MAAM,UAAU,OAAO,OAAO,YAAY,WAAW,OAAO,UAAU;GAEtE,OAAO,EAAE,OAAO,YAAY,SAAY;IAAE;IAAO;GAAQ,IAAI,EAAE,MAAM,EAAE;EACzE;CACF,EAGF;AACF;;AAGA,SAAS,gBAAgB,iBAAoD;CAC3E,OAAO;EACL,MAAM;EACN,YAAY;GACV,IAAI;IAAE,MAAM;IAAU,aAAa;GAA2C;GAC9E,YAAY;IACV,MAAM;IACN,MAAM;IACN,aAAa;GACf;GACA,OAAO;IACL,MAAM;IACN,aAAa;GACf;GACA,QAAQ;IAAE,MAAM;IAAU,aAAa;GAAwB;GAC/D,WAAW;IACT,MAAM;IACN,OAAO,EAAE,MAAM,SAAS;IACxB,aAAa;GACf;EACF;EACA,UAAU,CAAC,cAAc,OAAO;EAChC,sBAAsB;CACxB;AACF;;;;;;AAOA,SAAS,cAAc,KAAuC;CAC5D,IAAI,CAAC,OAAO,OAAO,QAAQ,UACzB;CAGF,MAAM,SAAS;CAQf,IAAI,OAAO,OAAO,eAAe,YAAY,OAAO,WAAW,WAAW,GACxE;CAGF,IAAI,OAAO,OAAO,UAAU,UAC1B;CAGF,MAAM,OAAoB;EACxB,YAAY,OAAO;EACnB,OAAO,OAAO;CAChB;CAEA,IAAI,OAAO,OAAO,OAAO,UACvB,KAAK,KAAK,OAAO;CAGnB,IAAI,OAAO,OAAO,WAAW,UAC3B,KAAK,SAAS,OAAO;CAGvB,IAAI,MAAM,QAAQ,OAAO,SAAS,KAAK,OAAO,UAAU,OAAO,UAAU,OAAO,UAAU,QAAQ,GAChG,KAAK,YAAY,OAAO;CAG1B,OAAO;AACT"}
+{"version":3,"file":"plan-schema.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/planner/plan-schema.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport type { PlannerPlan, PlannerStep } from \"../contracts/planner/planner-plan.type\";\n\n/**\n * Build the Standard Schema the planning agent emits — an ordered\n * `{ steps: [...], summary? }` plan whose every step references one of\n * `capabilityNames` via the `capability` field.\n *\n * Mirrors the router's hand-built schema approach\n * (`supervisor/router-factory.ts`): the JSON Schema extension carries\n * the capability names as an `enum` so capable providers enforce the\n * choice natively, while `validate()` still accepts the shape softly so\n * providers without native structured output can pass a parsed object\n * through. Validation is intentionally lenient on `capability` — an\n * unknown name is surfaced later by the planner as a typed\n * `PlannerPlanInvalidError`, with the full forensic context, rather\n * than as an opaque schema issue here.\n *\n * `maxSteps`, when provided, is emitted as the `steps` array's\n * `maxItems` so capable providers refuse to over-produce up front\n * (the planner still truncates the tail to `skipped` defensively).\n */\nexport function planSchema(\n  capabilityNames: string[],\n  maxSteps?: number,\n): StandardSchemaV1<PlannerPlan> {\n  // OpenAI strict `json_schema` mode (and other native structured-output\n  // providers) require EVERY property to appear in `required` — with truly\n  // optional fields expressed as nullable — and reject array `minItems` /\n  // `maxItems`. So the schema is strict-shaped: all keys required, the\n  // optional ones nullable, no item-count bounds. A non-empty plan is\n  // enforced in `validate()`, and `maxSteps` by the runtime's tail\n  // truncation, so neither bound is needed on the wire.\n  void maxSteps;\n\n  const jsonSchema = {\n    type: \"object\",\n    properties: {\n      summary: {\n        type: [\"string\", \"null\"],\n        description: \"One-line summary of the overall strategy.\",\n      },\n      steps: {\n        type: \"array\",\n        description: \"Ordered steps to execute, one capability dispatch each.\",\n        items: stepItemsSchema(capabilityNames),\n      },\n    },\n    required: [\"summary\", \"steps\"],\n    additionalProperties: false,\n  };\n\n  return {\n    \"~standard\": {\n      version: 1,\n      vendor: \"warlock-planner\",\n      jsonSchema: {\n        input: () => jsonSchema,\n      },\n      validate(value: unknown): StandardSchemaV1.Result<PlannerPlan> {\n        if (!value || typeof value !== \"object\") {\n          return { issues: [{ message: \"plan must be an object\" }] };\n        }\n\n        const record = value as { steps?: unknown; summary?: unknown };\n\n        if (!Array.isArray(record.steps) || record.steps.length === 0) {\n          return { issues: [{ message: \"plan `steps` must be a non-empty array\" }] };\n        }\n\n        const steps: PlannerStep[] = [];\n\n        for (const raw of record.steps) {\n          const normalized = normalizeStep(raw);\n\n          if (!normalized) {\n            return {\n              issues: [{ message: \"each plan step must carry a string `capability` and `input`\" }],\n            };\n          }\n\n          steps.push(normalized);\n        }\n\n        const summary = typeof record.summary === \"string\" ? record.summary : undefined;\n\n        return { value: summary !== undefined ? { steps, summary } : { steps } };\n      },\n    } as StandardSchemaV1<PlannerPlan>[\"~standard\"] & {\n      jsonSchema: { input: () => Record<string, unknown> };\n    },\n  };\n}\n\n/** Per-step JSON Schema object — one capability dispatch. */\nfunction stepItemsSchema(capabilityNames: string[]): Record<string, unknown> {\n  return {\n    type: \"object\",\n    properties: {\n      id: {\n        type: [\"string\", \"null\"],\n        description: \"Stable step id, referenced by dependsOn.\",\n      },\n      capability: {\n        type: \"string\",\n        enum: capabilityNames,\n        description: \"Name of the capability to dispatch for this step.\",\n      },\n      input: {\n        type: \"string\",\n        description: \"Concrete input passed to the capability's execute().\",\n      },\n      reason: { type: [\"string\", \"null\"], description: \"Why this step exists.\" },\n      dependsOn: {\n        type: [\"array\", \"null\"],\n        items: { type: \"string\" },\n        description: \"Ids of steps this one conceptually follows.\",\n      },\n    },\n    // Strict mode: every property required; the genuinely-optional ones\n    // (id / reason / dependsOn) are nullable. `validate()` treats null and\n    // missing identically, so a model emitting `null` round-trips fine.\n    required: [\"id\", \"capability\", \"input\", \"reason\", \"dependsOn\"],\n    additionalProperties: false,\n  };\n}\n\n/**\n * Coerce one raw step object into a {@link PlannerStep}, returning\n * `undefined` when the mandatory `capability` / `input` strings are\n * missing. Optional fields are copied only when well-typed.\n */\nfunction normalizeStep(raw: unknown): PlannerStep | undefined {\n  if (!raw || typeof raw !== \"object\") {\n    return undefined;\n  }\n\n  const record = raw as {\n    id?: unknown;\n    capability?: unknown;\n    input?: unknown;\n    reason?: unknown;\n    dependsOn?: unknown;\n  };\n\n  if (typeof record.capability !== \"string\" || record.capability.length === 0) {\n    return undefined;\n  }\n\n  if (typeof record.input !== \"string\") {\n    return undefined;\n  }\n\n  const step: PlannerStep = {\n    capability: record.capability,\n    input: record.input,\n  };\n\n  if (typeof record.id === \"string\") {\n    step.id = record.id;\n  }\n\n  if (typeof record.reason === \"string\") {\n    step.reason = record.reason;\n  }\n\n  if (Array.isArray(record.dependsOn) && record.dependsOn.every((entry) => typeof entry === \"string\")) {\n    step.dependsOn = record.dependsOn as string[];\n  }\n\n  return step;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAsBA,SAAgB,WACd,iBACA,UAC+B;CAU/B,MAAM,aAAa;EACjB,MAAM;EACN,YAAY;GACV,SAAS;IACP,MAAM,CAAC,UAAU,MAAM;IACvB,aAAa;GACf;GACA,OAAO;IACL,MAAM;IACN,aAAa;IACb,OAAO,gBAAgB,eAAe;GACxC;EACF;EACA,UAAU,CAAC,WAAW,OAAO;EAC7B,sBAAsB;CACxB;CAEA,OAAO,EACL,aAAa;EACX,SAAS;EACT,QAAQ;EACR,YAAY,EACV,aAAa,WACf;EACA,SAAS,OAAsD;GAC7D,IAAI,CAAC,SAAS,OAAO,UAAU,UAC7B,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS,yBAAyB,CAAC,EAAE;GAG3D,MAAM,SAAS;GAEf,IAAI,CAAC,MAAM,QAAQ,OAAO,KAAK,KAAK,OAAO,MAAM,WAAW,GAC1D,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS,yCAAyC,CAAC,EAAE;GAG3E,MAAM,QAAuB,CAAC;GAE9B,KAAK,MAAM,OAAO,OAAO,OAAO;IAC9B,MAAM,aAAa,cAAc,GAAG;IAEpC,IAAI,CAAC,YACH,OAAO,EACL,QAAQ,CAAC,EAAE,SAAS,8DAA8D,CAAC,EACrF;IAGF,MAAM,KAAK,UAAU;GACvB;GAEA,MAAM,UAAU,OAAO,OAAO,YAAY,WAAW,OAAO,UAAU;GAEtE,OAAO,EAAE,OAAO,YAAY,SAAY;IAAE;IAAO;GAAQ,IAAI,EAAE,MAAM,EAAE;EACzE;CACF,EAGF;AACF;;AAGA,SAAS,gBAAgB,iBAAoD;CAC3E,OAAO;EACL,MAAM;EACN,YAAY;GACV,IAAI;IACF,MAAM,CAAC,UAAU,MAAM;IACvB,aAAa;GACf;GACA,YAAY;IACV,MAAM;IACN,MAAM;IACN,aAAa;GACf;GACA,OAAO;IACL,MAAM;IACN,aAAa;GACf;GACA,QAAQ;IAAE,MAAM,CAAC,UAAU,MAAM;IAAG,aAAa;GAAwB;GACzE,WAAW;IACT,MAAM,CAAC,SAAS,MAAM;IACtB,OAAO,EAAE,MAAM,SAAS;IACxB,aAAa;GACf;EACF;EAIA,UAAU;GAAC;GAAM;GAAc;GAAS;GAAU;EAAW;EAC7D,sBAAsB;CACxB;AACF;;;;;;AAOA,SAAS,cAAc,KAAuC;CAC5D,IAAI,CAAC,OAAO,OAAO,QAAQ,UACzB;CAGF,MAAM,SAAS;CAQf,IAAI,OAAO,OAAO,eAAe,YAAY,OAAO,WAAW,WAAW,GACxE;CAGF,IAAI,OAAO,OAAO,UAAU,UAC1B;CAGF,MAAM,OAAoB;EACxB,YAAY,OAAO;EACnB,OAAO,OAAO;CAChB;CAEA,IAAI,OAAO,OAAO,OAAO,UACvB,KAAK,KAAK,OAAO;CAGnB,IAAI,OAAO,OAAO,WAAW,UAC3B,KAAK,SAAS,OAAO;CAGvB,IAAI,MAAM,QAAQ,OAAO,SAAS,KAAK,OAAO,UAAU,OAAO,UAAU,OAAO,UAAU,QAAQ,GAChG,KAAK,YAAY,OAAO;CAG1B,OAAO;AACT"}

package/package.json

@@ -15,10 +15,10 @@
     "@standard-schema/spec": "^1.0.0"
   },
   "peerDependencies": {
-    "@warlock.js/cache": "4.3.0",
-    "@warlock.js/logger": "4.3.0"
+    "@warlock.js/cache": "4.4.0",
+    "@warlock.js/logger": "4.4.0"
   },
-  "version": "4.3.0",
+  "version": "4.4.0",
   "main": "./cjs/index.cjs",
   "module": "./esm/index.mjs",
   "types": "./esm/index.d.mts",