@warlock.js/core 4.8.0 → 4.8.1

package/esm/ai/src/planner/plan-schema.mjs

@@ -1,120 +0,0 @@
-//#region ../@warlock.js/ai/src/planner/plan-schema.ts
-/**
-* Build the Standard Schema the planning agent emits — an ordered
-* `{ steps: [...], summary? }` plan whose every step references one of
-* `capabilityNames` via the `capability` field.
-*
-* Mirrors the router's hand-built schema approach
-* (`supervisor/router-factory.ts`): the JSON Schema extension carries
-* the capability names as an `enum` so capable providers enforce the
-* choice natively, while `validate()` still accepts the shape softly so
-* providers without native structured output can pass a parsed object
-* through. Validation is intentionally lenient on `capability` — an
-* unknown name is surfaced later by the planner as a typed
-* `PlannerPlanInvalidError`, with the full forensic context, rather
-* than as an opaque schema issue here.
-*
-* `maxSteps`, when provided, is emitted as the `steps` array's
-* `maxItems` so capable providers refuse to over-produce up front
-* (the planner still truncates the tail to `skipped` defensively).
-*/
-function planSchema(capabilityNames, maxSteps) {
-	const jsonSchema = {
-		type: "object",
-		properties: {
-			summary: {
-				type: ["string", "null"],
-				description: "One-line summary of the overall strategy."
-			},
-			steps: {
-				type: "array",
-				description: "Ordered steps to execute, one capability dispatch each.",
-				items: stepItemsSchema(capabilityNames)
-			}
-		},
-		required: ["summary", "steps"],
-		additionalProperties: false
-	};
-	return { "~standard": {
-		version: 1,
-		vendor: "warlock-planner",
-		jsonSchema: { input: () => jsonSchema },
-		validate(value) {
-			if (!value || typeof value !== "object") return { issues: [{ message: "plan must be an object" }] };
-			const record = value;
-			if (!Array.isArray(record.steps) || record.steps.length === 0) return { issues: [{ message: "plan `steps` must be a non-empty array" }] };
-			const steps = [];
-			for (const raw of record.steps) {
-				const normalized = normalizeStep(raw);
-				if (!normalized) return { issues: [{ message: "each plan step must carry a string `capability` and `input`" }] };
-				steps.push(normalized);
-			}
-			const summary = typeof record.summary === "string" ? record.summary : void 0;
-			return { value: summary !== void 0 ? {
-				steps,
-				summary
-			} : { steps } };
-		}
-	} };
-}
-/** Per-step JSON Schema object — one capability dispatch. */
-function stepItemsSchema(capabilityNames) {
-	return {
-		type: "object",
-		properties: {
-			id: {
-				type: ["string", "null"],
-				description: "Stable step id, referenced by dependsOn."
-			},
-			capability: {
-				type: "string",
-				enum: capabilityNames,
-				description: "Name of the capability to dispatch for this step."
-			},
-			input: {
-				type: "string",
-				description: "Concrete input passed to the capability's execute()."
-			},
-			reason: {
-				type: ["string", "null"],
-				description: "Why this step exists."
-			},
-			dependsOn: {
-				type: ["array", "null"],
-				items: { type: "string" },
-				description: "Ids of steps this one conceptually follows."
-			}
-		},
-		required: [
-			"id",
-			"capability",
-			"input",
-			"reason",
-			"dependsOn"
-		],
-		additionalProperties: false
-	};
-}
-/**
-* Coerce one raw step object into a {@link PlannerStep}, returning
-* `undefined` when the mandatory `capability` / `input` strings are
-* missing. Optional fields are copied only when well-typed.
-*/
-function normalizeStep(raw) {
-	if (!raw || typeof raw !== "object") return;
-	const record = raw;
-	if (typeof record.capability !== "string" || record.capability.length === 0) return;
-	if (typeof record.input !== "string") return;
-	const step = {
-		capability: record.capability,
-		input: record.input
-	};
-	if (typeof record.id === "string") step.id = record.id;
-	if (typeof record.reason === "string") step.reason = record.reason;
-	if (Array.isArray(record.dependsOn) && record.dependsOn.every((entry) => typeof entry === "string")) step.dependsOn = record.dependsOn;
-	return step;
-}
-
-//#endregion
-export { planSchema };
-//# sourceMappingURL=plan-schema.mjs.map

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

@@ -1 +0,0 @@
-{"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"}