@warlock.js/ai 4.4.0 → 4.6.0

package/esm/agent/agent-config.type.d.mts

@@ -1,3 +1,6 @@
+import { AttachmentPolicy } from "../contracts/attachment-policy.type.mjs";
+import { FlowObserveOption } from "../observe/resolve-observers.mjs";
+import { SnapshotStore } from "../contracts/orchestrator/snapshot-store.contract.mjs";
 import { AgentToolEntry } from "../tool/executable-as-tool.mjs";
 import { ModelCallOptions, ModelContract } from "../contracts/model.contract.mjs";
 import { AgentMiddleware } from "../contracts/middleware/middleware.contract.mjs";
@@ -5,8 +8,12 @@ import { Placeholders } from "../contracts/placeholders.type.mjs";
 import { SystemPromptContract } from "../contracts/system-prompt.contract.mjs";
 import { AgentEventMap } from "../contracts/events/event-map.type.mjs";
 import { StreamingToolGuardConfig } from "../contracts/streaming-tool-guard-config.type.mjs";
+import { AgentSnapshot } from "../contracts/agent/agent-snapshot.type.mjs";
 import { CompleteEvent } from "../contracts/events/complete-event.type.mjs";
 import { UsageEvent } from "../contracts/events/usage-event.type.mjs";
+import { SkillsConfig } from "../skills/contracts/skills-config.type.mjs";
+import { SkillsContract } from "../skills/contracts/skills.contract.mjs";
+import { JudgeConfig } from "./judge-config.type.mjs";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 
 //#region ../@warlock.js/ai/src/agent/agent-config.type.d.ts
@@ -93,7 +100,29 @@ type AgentConfig<TOutput = unknown> = {
    *   through its `execute()`. `.asTool()` remains fully supported and
    *   takes precedence when you need a custom name / schema per use.
    */
-  tools?: AgentToolEntry<any, any>[]; /** Placeholder values merged into system prompt templates */
+  tools?: AgentToolEntry<any, any>[];
+  /**
+   * Factory-level trust-boundary policy for attachments (S1). Governs
+   * server-side attachment I/O: remote-text fetch is default-deny, a
+   * permitted fetch runs through the shared `OutboundPolicy`
+   * (scheme/host/private-IP/max-bytes/timeout), and local reads honor an
+   * `allowedRoots` sandbox. A per-call `AgentExecuteOptions.attachmentPolicy`
+   * overrides this. Omit to keep the safe defaults.
+   */
+  attachmentPolicy?: AttachmentPolicy;
+  /**
+   * Attach a runtime skills library. Accepts the {@link SkillsContract}
+   * returned by `ai.skills(...)` or a raw {@link SkillsConfig} (the agent
+   * passes it to `skills()` for you). When set the agent owns the skills
+   * runtime flow at execute time: it prepends the always-injected metadata
+   * catalog (and, under `inject`, the preloaded bodies) in front of the
+   * developer's system prompt, auto-registers the `loadSkill` tool (plus
+   * `saveSkill` only when a `review` gate is configured), and threads the
+   * run id so `maxLoadsPerRun` is enforced per execution.
+   *
+   * Omitted ⇒ no skills behavior; the agent runs byte-for-byte as today.
+   */
+  skills?: SkillsContract | SkillsConfig; /** Placeholder values merged into system prompt templates */
   placeholders?: Placeholders;
   /**
    * Maximum number of LLM trips before aborting with an error.
@@ -110,6 +139,41 @@ type AgentConfig<TOutput = unknown> = {
    * no merging.
    */
   output?: StandardSchemaV1<TOutput>;
+  /**
+   * Judge-safe preset for structured-output judges (LLM-as-judge graders,
+   * verdict classifiers) running on models that may emit *corrupted* JSON —
+   * notably the Amazon Nova family, which wraps verdicts in fenced
+   * ` ```json ` blocks, prepends an explanation paragraph, or trails the
+   * object with commentary.
+   *
+   * `true` (or a {@link JudgeConfig} object) turns on three behaviors at
+   * once:
+   * 1. **Repair** — a couple of re-ask attempts by default
+   *    ({@link JudgeConfig.repairAttempts}) when the verdict fails to parse
+   *    or validate, bounded by `maxTrips`. The caller's per-call
+   *    `options.repair` still wins when explicitly set.
+   * 2. **Lenient verdict parsing** — tolerates fenced ` ```json ` blocks,
+   *    leading / trailing prose, and minor malformations by extracting the
+   *    first balanced JSON object / array from the response (via
+   *    `extractJsonLenient`) instead of the strict `extractJsonPayload`.
+   * 3. **Never throws on a parse miss** — `execute()` already attaches
+   *    errors to `result.error` rather than throwing; the preset hardens
+   *    that into a guarantee: even an unparseable verdict yields a
+   *    well-formed result (`result.error` populated, `result.data`
+   *    undefined) so a flaky judge degrades gracefully instead of crashing
+   *    the surrounding flow.
+   *
+   * **Trade-off — resilience over strictness.** The lenient slice can in
+   * principle recover JSON the strict parser would (correctly) reject, so
+   * only enable it where a tolerant parse is wanted (judges / classifiers
+   * over Nova-class models). Leave it off for normal structured output,
+   * where a hard parse failure is a useful signal that the prompt or model
+   * needs fixing rather than papering over.
+   *
+   * Off by default — when omitted the agent parses strictly and never
+   * auto-enables repair, byte-for-byte as before.
+   */
+  judge?: boolean | JudgeConfig;
   /**
    * Factory-level event handlers. Fire before instance-level `.on()`
    * additions and before per-call `options.on` handlers on every
@@ -167,6 +231,60 @@ type AgentConfig<TOutput = unknown> = {
    * Distinct from the existing `agent.completed` event — both fire.
    */
   onComplete?: (event: CompleteEvent<TOutput>) => void | Promise<void>;
+  /**
+   * Persist the full multi-turn message array onto
+   * `AgentReport.messages`. Off by default — the captured conversation
+   * can be large and may contain sensitive content (full prompts, tool
+   * inputs/outputs). When omitted the report carries no `messages` field
+   * and the agent runs byte-for-byte as before. Required for panoptic
+   * full-history capture.
+   */
+  captureMessages?: boolean;
+  /**
+   * Observability for this flow. Additive and gated — when omitted, the
+   * flow follows the global observe-all flag (off unless an
+   * observability tool turned it on), so behavior is unchanged by
+   * default.
+   *
+   * - `true` → route this flow's completed report to the globally
+   *   registered observers, even when observe-all is off.
+   * - `false` → opt this flow out entirely, even when observe-all is on.
+   * - an `Observer` object → a flow-local collector; only this flow's
+   *   report is routed, and only to it. Core types this as the
+   *   structural `Observer` (NOT a panoptic-specific type) so core stays
+   *   panoptic-agnostic; a panoptic flow-local collector implements
+   *   `Observer` and can be passed directly.
+   *
+   * Observer errors are swallowed — they never break the run.
+   */
+  observe?: FlowObserveOption;
+  /**
+   * Opt-in durable mid-run crash-resume. When set, the agent checkpoints
+   * its state to a {@link SnapshotStore} after every settled trip, so a
+   * `agent.resume(runId)` after a crash re-hydrates the completed trips +
+   * tool calls + usage and continues the trip loop from the next trip —
+   * never re-issuing a completed trip's model call or re-invoking its
+   * tools.
+   *
+   * Absent ⇒ no persistence, zero behavior change: the trip loop starts
+   * at trip 0, never writes a snapshot, and runs byte-for-byte as today.
+   *
+   * - `store` — the snapshot store to persist to. Optional; falls back to
+   *   `ai.config({ defaultSnapshotStore })` when omitted. When neither is
+   *   set, snapshot writes silently skip and `resume()` throws.
+   * - `deleteOnComplete` — drop the snapshot once the run terminates
+   *   successfully. Default `false` (keep it, so a completed-run resume
+   *   short-circuits to the stored result and the snapshot stays for audit).
+   *
+   * **Idempotency caveat.** A crash mid-trip re-runs that trip's tools on
+   * resume; side-effectful tools (charging a card, sending an email) must
+   * be idempotent — the same caller-responsibility boundary the supervisor
+   * and workflow primitives already document.
+   */
+  durable?: {
+    /** Snapshot store to persist to. Falls back to the global default. */store?: SnapshotStore<AgentSnapshot>; /** Drop the snapshot on successful completion. Default `false`. */
+    deleteOnComplete?: boolean;
+  };
 };
 //#endregion
 export { AgentConfig, AgentEventHandlers };

package/esm/agent/agent-config.type.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-config.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/agent/agent-config.type.ts"],"mappings":";;;;;;;;;;;;;;;AAgBA;;KAAY,kBAAA,GAAqB,OAAA,eACnB,aAAA,IAAiB,OAAA,EAAS,aAAA,CAAc,CAAA;;;;;;;;;;;;AAAE;AA0BxD;;;;;;;;;;;KAAY,WAAA;EAsGW;;;;;;;;;;;;EAzFrB,IAAA;EAuBO;;;;;;;EAfP,WAAA;EA2CA;;;;;;;;;;;;EA9BA,OAAA,WAmFW;EAjFX,KAAA,EAAO,aAAA;EA8FP;;;;EAzFA,YAAA,GAAe,oBAAA;EAyF+C;AAAA;;;;;;;;;;;;EA3E9D,KAAA,GAAQ,cAAA;EAER,YAAA,GAAe,YAAA;;;;;EAKf,QAAA;EAEA,YAAA,GAAe,gBAAA;;;;;;;;;EASf,MAAA,GAAS,gBAAA,CAAiB,OAAA;;;;;;EAM1B,EAAA,GAAK,kBAAA;;;;;;;;;;;;EAYL,UAAA,GAAa,eAAA;;;;;;;;;;;EAWb,kBAAA,GAAqB,wBAAA;;;;;;;;;;;;;;;EAerB,OAAA,IAAW,KAAA,EAAO,UAAA,YAAsB,OAAA;;;;;;;;;;;;;EAaxC,UAAA,IAAc,KAAA,EAAO,aAAA,CAAc,OAAA,aAAoB,OAAA;AAAA"}
+{"version":3,"file":"agent-config.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/agent/agent-config.type.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAuBA;;KAAY,kBAAA,GAAqB,OAAA,eACnB,aAAA,IAAiB,OAAA,EAAS,aAAA,CAAc,CAAA;;;;;;;;;;;;AAAE;AA0BxD;;;;;;;;;;;KAAY,WAAA;EA+FD;;;;;;;;;;;;EAlFT,IAAA;EAmOuB;;;;;;;EA3NvB,WAAA;EAoBA;;;;;;;;;;;;EAPA,OAAA,WAoDe;EAlDf,KAAA,EAAO,aAAA;EA2DE;;;;EAtDT,YAAA,GAAe,oBAAA;EA+FV;;;;;;;;;;;;;EAjFL,KAAA,GAAQ,cAAA;EA6IR;;;;;;;;EApIA,gBAAA,GAAmB,gBAAA;EAkLD;;;;;;;;;;;;EArKlB,MAAA,GAAS,cAAA,GAAiB,YAAA;EAE1B,YAAA,GAAe,YAAA;;;;;EAKf,QAAA;EAEA,YAAA,GAAe,gBAAA;;;;;;;;;EASf,MAAA,GAAS,gBAAA,CAAiB,OAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmC1B,KAAA,aAAkB,WAAA;;;;;;EAMlB,EAAA,GAAK,kBAAA;;;;;;;;;;;;EAYL,UAAA,GAAa,eAAA;;;;;;;;;;;EAWb,kBAAA,GAAqB,wBAAA;;;;;;;;;;;;;;;EAerB,OAAA,IAAW,KAAA,EAAO,UAAA,YAAsB,OAAA;;;;;;;;;;;;;EAaxC,UAAA,IAAc,KAAA,EAAO,aAAA,CAAc,OAAA,aAAoB,OAAA;;;;;;;;;EASvD,eAAA;;;;;;;;;;;;;;;;;;EAkBA,OAAA,GAAU,iBAAA;;;;;;;;;;;;;;;;;;;;;;;;EAwBV,OAAA;0EAEE,KAAA,GAAQ,aAAA,CAAc,aAAA;IAEtB,gBAAA;EAAA;AAAA"}

package/esm/agent/agent-input-builder.mjs

@@ -36,8 +36,17 @@ async function buildAgentInputMessages(params) {
 	};
 	const systemPrompt = options?.systemPrompt ?? config.systemPrompt;
 	let systemContent = "";
+	let promptName;
+	let promptVersion;
 	if (typeof systemPrompt === "string") systemContent = systemPrompt;
-	else if (systemPrompt) systemContent = systemPrompt.resolve(placeholders);
+	else if (systemPrompt) {
+		systemContent = systemPrompt.resolve(placeholders);
+		const meta = systemPrompt.meta();
+		if (meta?.name) {
+			promptName = meta.name;
+			promptVersion = meta.version ?? "1";
+		}
+	}
 	const { responseSchema, instruction } = resolveStructuredOutput({
 		outputSchema: options?.output ?? config.output,
 		overrideResponseSchema: options?.responseSchema,
@@ -53,8 +62,11 @@ async function buildAgentInputMessages(params) {
 	const userContent = await buildUserMessageContent({
 		input,
 		attachments: options?.attachments,
+		attachmentPolicy: options?.attachmentPolicy ?? config.attachmentPolicy,
 		modelName: config.model.name,
-		modelSupportsVision: Boolean(config.model.capabilities?.vision)
+		modelSupportsVision: Boolean(config.model.capabilities?.vision),
+		modelSupportsPdf: Boolean(config.model.capabilities?.pdf),
+		modelSupportsAudio: Boolean(config.model.capabilities?.audio)
 	});
 	messages.push({
 		role: "user",
@@ -62,7 +74,10 @@ async function buildAgentInputMessages(params) {
 	});
 	return {
 		messages,
-		responseSchema
+		responseSchema,
+		systemPrompt: systemContent || void 0,
+		promptName,
+		promptVersion
 	};
 }
 /**
@@ -72,15 +87,21 @@ async function buildAgentInputMessages(params) {
 * parts in declaration order.
 */
 async function buildUserMessageContent(params) {
-	const { input, attachments, modelName, modelSupportsVision } = params;
+	const { input, attachments, attachmentPolicy, modelName, modelSupportsVision, modelSupportsPdf, modelSupportsAudio } = params;
 	if (!attachments || attachments.length === 0) return input;
-	const parts = await Promise.all(attachments.map((attachment) => prepareAttachmentPart(attachment)));
-	if (parts.some((part) => part.type === "image") && !modelSupportsVision) throw new InvalidRequestError(`Model "${modelName}" does not declare vision capability — image attachments are not supported`, { context: { modelName } });
+	const parts = await Promise.all(attachments.map((attachment) => prepareAttachmentPart(attachment, attachmentPolicy)));
+	assertModality(parts, "image", modelSupportsVision, "vision", modelName);
+	assertModality(parts, "pdf", modelSupportsPdf, "pdf", modelName);
+	assertModality(parts, "audio", modelSupportsAudio, "audio", modelName);
 	return [{
 		type: "text",
 		text: input
 	}, ...parts];
 }
+/** Throw when a modality is present but the model doesn't declare it. */
+function assertModality(parts, partType, supported, capability, modelName) {
+	if (!supported && parts.some((part) => part.type === partType)) throw new InvalidRequestError(`Model "${modelName}" does not declare ${capability} capability — ${partType} attachments are not supported`, { context: { modelName } });
+}
 /**
 * When the caller supplied an `output` schema, resolve two artifacts:
 *

package/esm/agent/agent-input-builder.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"agent-input-builder.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/agent/agent-input-builder.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport type { AgentExecuteOptions } from \"../contracts/agent/agent-options.type\";\nimport type { Attachment } from \"../contracts/attachment.type\";\nimport type { ContentPart } from \"../contracts/content-part.type\";\nimport type { Message } from \"../contracts/conversation-message.type\";\nimport type { Placeholders } from \"../contracts/placeholders.type\";\nimport { InvalidRequestError } from \"../errors\";\nimport { extractJsonSchema, prepareAttachmentPart } from \"../utils\";\nimport type { AgentConfig } from \"./agent-config.type\";\n\n/**\n * Outcome of `buildAgentInputMessages` — the seeded message list and\n * the JSON Schema cached for every trip's\n * `ModelCallOptions.responseSchema`. `responseSchema` is `undefined`\n * when the caller didn't ask for structured output.\n */\nexport type AgentInputBuildResult = {\n  messages: Message[];\n  responseSchema?: Record<string, unknown>;\n};\n\n/**\n * Assemble the seed conversation for an agent execution. Runs exactly\n * once per run — subsequent trips append to the same message list.\n *\n * Responsibilities (previously three methods on `Execution`):\n * 1. Merge factory + per-call placeholders.\n * 2. Resolve the system prompt (string, contract, or absent).\n * 3. When an output schema is supplied:\n *    - cache its JSON Schema form for `ModelCallOptions.responseSchema`\n *      so native-structured-output providers enforce it at the token\n *      level;\n *    - fall back to a soft system-prompt instruction for providers\n *      that don't advertise `structuredOutput` capability.\n * 4. Append caller-supplied `history` (e.g. session-level prior turns).\n * 5. Shape the user message — plain string in the common case,\n *    multipart `ContentPart[]` when `attachments` are present. Image\n *    attachments require model vision capability; mismatch throws\n *    `InvalidRequestError` here rather than failing opaquely at the\n *    provider.\n *\n * Extracted from the `Execution` class to isolate the declarative\n * input-shaping phase from the stateful trip loop.\n */\nexport async function buildAgentInputMessages<TOutput>(params: {\n  config: AgentConfig<TOutput>;\n  input: string;\n  options?: AgentExecuteOptions<TOutput>;\n}): Promise<AgentInputBuildResult> {\n  const { config, input, options } = params;\n\n  const placeholders: Placeholders = {\n    ...config.placeholders,\n    ...options?.placeholders,\n  };\n\n  const systemPrompt = options?.systemPrompt ?? config.systemPrompt;\n  let systemContent = \"\";\n\n  if (typeof systemPrompt === \"string\") {\n    systemContent = systemPrompt;\n  } else if (systemPrompt) {\n    systemContent = systemPrompt.resolve(placeholders);\n  }\n\n  const { responseSchema, instruction } = resolveStructuredOutput({\n    outputSchema: options?.output ?? config.output,\n    overrideResponseSchema: options?.responseSchema,\n    modelSupportsStructuredOutput: Boolean(config.model.capabilities?.structuredOutput),\n  });\n\n  if (instruction) {\n    systemContent = systemContent ? `${systemContent}\\n\\n${instruction}` : instruction;\n  }\n\n  const messages: Message[] = [];\n\n  if (systemContent) {\n    messages.push({ role: \"system\", content: systemContent });\n  }\n\n  if (options?.history) {\n    messages.push(...options.history);\n  }\n\n  const userContent = await buildUserMessageContent({\n    input,\n    attachments: options?.attachments,\n    modelName: config.model.name,\n    modelSupportsVision: Boolean(config.model.capabilities?.vision),\n  });\n\n  messages.push({ role: \"user\", content: userContent });\n\n  return { messages, responseSchema };\n}\n\n/**\n * Build the user message `content` field. Plain string when no\n * attachments (the hot path) — keeps wire payloads small. Multipart\n * `ContentPart[]` when attachments exist: input text first, resolved\n * parts in declaration order.\n */\nasync function buildUserMessageContent(params: {\n  input: string;\n  attachments?: Attachment[];\n  modelName: string;\n  modelSupportsVision: boolean;\n}): Promise<string | ContentPart[]> {\n  const { input, attachments, modelName, modelSupportsVision } = params;\n\n  if (!attachments || attachments.length === 0) {\n    return input;\n  }\n\n  const parts: ContentPart[] = await Promise.all(\n    attachments.map((attachment) => prepareAttachmentPart(attachment)),\n  );\n\n  const hasImage = parts.some((part) => part.type === \"image\");\n\n  if (hasImage && !modelSupportsVision) {\n    throw new InvalidRequestError(\n      `Model \"${modelName}\" does not declare vision capability — image attachments are not supported`,\n      { context: { modelName } },\n    );\n  }\n\n  return [{ type: \"text\", text: input }, ...parts];\n}\n\n/**\n * When the caller supplied an `output` schema, resolve two artifacts:\n *\n * - `responseSchema` — extracted JSON Schema to attach on every trip.\n *   Adapters that natively support structured output (OpenAI's\n *   `response_format: json_schema`) consume it; others ignore it.\n * - `instruction` — a soft fallback appended to the system prompt\n *   **only** for models without native structured-output capability.\n *   Capable adapters skip it to save tokens and avoid redundancy.\n */\nfunction resolveStructuredOutput(params: {\n  outputSchema?: StandardSchemaV1<unknown>;\n  overrideResponseSchema?: Record<string, unknown>;\n  modelSupportsStructuredOutput: boolean;\n}): {\n  responseSchema?: Record<string, unknown>;\n  instruction?: string;\n} {\n  const { outputSchema, overrideResponseSchema, modelSupportsStructuredOutput } = params;\n\n  if (!outputSchema) {\n    return {};\n  }\n\n  const responseSchema = overrideResponseSchema ?? extractJsonSchema(outputSchema);\n\n  if (modelSupportsStructuredOutput) {\n    return { responseSchema };\n  }\n\n  const schemaHint = responseSchema\n    ? `\\n\\nThe response MUST match this JSON Schema:\\n${JSON.stringify(responseSchema, null, 2)}`\n    : \"\";\n\n  const instruction = [\n    \"You MUST respond with a single valid JSON value only.\",\n    \"Do not wrap it in markdown code fences. Do not include prose, commentary, or explanation — JSON only.\",\n    schemaHint,\n  ]\n    .join(\"\")\n    .trim();\n\n  return { responseSchema, instruction };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4CA,eAAsB,wBAAiC,QAIpB;CACjC,MAAM,EAAE,QAAQ,OAAO,YAAY;CAEnC,MAAM,eAA6B;EACjC,GAAG,OAAO;EACV,GAAG,SAAS;CACd;CAEA,MAAM,eAAe,SAAS,gBAAgB,OAAO;CACrD,IAAI,gBAAgB;CAEpB,IAAI,OAAO,iBAAiB,UAC1B,gBAAgB;MACX,IAAI,cACT,gBAAgB,aAAa,QAAQ,YAAY;CAGnD,MAAM,EAAE,gBAAgB,gBAAgB,wBAAwB;EAC9D,cAAc,SAAS,UAAU,OAAO;EACxC,wBAAwB,SAAS;EACjC,+BAA+B,QAAQ,OAAO,MAAM,cAAc,gBAAgB;CACpF,CAAC;CAED,IAAI,aACF,gBAAgB,gBAAgB,GAAG,cAAc,MAAM,gBAAgB;CAGzE,MAAM,WAAsB,CAAC;CAE7B,IAAI,eACF,SAAS,KAAK;EAAE,MAAM;EAAU,SAAS;CAAc,CAAC;CAG1D,IAAI,SAAS,SACX,SAAS,KAAK,GAAG,QAAQ,OAAO;CAGlC,MAAM,cAAc,MAAM,wBAAwB;EAChD;EACA,aAAa,SAAS;EACtB,WAAW,OAAO,MAAM;EACxB,qBAAqB,QAAQ,OAAO,MAAM,cAAc,MAAM;CAChE,CAAC;CAED,SAAS,KAAK;EAAE,MAAM;EAAQ,SAAS;CAAY,CAAC;CAEpD,OAAO;EAAE;EAAU;CAAe;AACpC;;;;;;;AAQA,eAAe,wBAAwB,QAKH;CAClC,MAAM,EAAE,OAAO,aAAa,WAAW,wBAAwB;CAE/D,IAAI,CAAC,eAAe,YAAY,WAAW,GACzC,OAAO;CAGT,MAAM,QAAuB,MAAM,QAAQ,IACzC,YAAY,KAAK,eAAe,sBAAsB,UAAU,CAAC,CACnE;CAIA,IAFiB,MAAM,MAAM,SAAS,KAAK,SAAS,OAEzC,KAAK,CAAC,qBACf,MAAM,IAAI,oBACR,UAAU,UAAU,6EACpB,EAAE,SAAS,EAAE,UAAU,EAAE,CAC3B;CAGF,OAAO,CAAC;EAAE,MAAM;EAAQ,MAAM;CAAM,GAAG,GAAG,KAAK;AACjD;;;;;;;;;;;AAYA,SAAS,wBAAwB,QAO/B;CACA,MAAM,EAAE,cAAc,wBAAwB,kCAAkC;CAEhF,IAAI,CAAC,cACH,OAAO,CAAC;CAGV,MAAM,iBAAiB,0BAA0B,kBAAkB,YAAY;CAE/E,IAAI,+BACF,OAAO,EAAE,eAAe;CAe1B,OAAO;EAAE;EAAgB,aARL;GAClB;GACA;GANiB,iBACf,kDAAkD,KAAK,UAAU,gBAAgB,MAAM,CAAC,MACxF;EAMJ,CAAC,CACE,KAAK,EAAE,CAAC,CACR,KAEgC;CAAE;AACvC"}
+{"version":3,"file":"agent-input-builder.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/agent/agent-input-builder.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport type { AgentExecuteOptions } from \"../contracts/agent/agent-options.type\";\nimport type { AttachmentPolicy } from \"../contracts/attachment-policy.type\";\nimport type { Attachment } from \"../contracts/attachment.type\";\nimport type { ContentPart } from \"../contracts/content-part.type\";\nimport type { Message } from \"../contracts/conversation-message.type\";\nimport type { Placeholders } from \"../contracts/placeholders.type\";\nimport { InvalidRequestError } from \"../errors\";\nimport { extractJsonSchema, prepareAttachmentPart } from \"../utils\";\nimport type { AgentConfig } from \"./agent-config.type\";\n\n/**\n * Outcome of `buildAgentInputMessages` — the seeded message list and\n * the JSON Schema cached for every trip's\n * `ModelCallOptions.responseSchema`. `responseSchema` is `undefined`\n * when the caller didn't ask for structured output.\n */\nexport type AgentInputBuildResult = {\n  messages: Message[];\n  responseSchema?: Record<string, unknown>;\n  /**\n   * The resolved system-prompt text actually sent as the `role: \"system\"`\n   * message (persona + instructions + any auto-appended structured-output\n   * instruction). Captured for observability; absent when the agent ran\n   * without a system prompt.\n   */\n  systemPrompt?: string;\n  /**\n   * Registry name of the `SystemPromptContract` the agent resolved, read from\n   * its `meta().name`. Present only when the agent ran against a *named*\n   * prompt (one registered in `ai.prompts`); absent for a raw-string prompt,\n   * an anonymous contract, or no prompt at all. Lets observers attribute a run\n   * to a specific prompt in the registry.\n   */\n  promptName?: string;\n  /**\n   * Registry version label of the named prompt the agent resolved, read from\n   * its `meta().version` (defaulting to `\"1\"` when the prompt carries a name\n   * but no explicit version, mirroring the registry's default). Present only\n   * alongside {@link AgentInputBuildResult.promptName}.\n   */\n  promptVersion?: string;\n};\n\n/**\n * Assemble the seed conversation for an agent execution. Runs exactly\n * once per run — subsequent trips append to the same message list.\n *\n * Responsibilities (previously three methods on `Execution`):\n * 1. Merge factory + per-call placeholders.\n * 2. Resolve the system prompt (string, contract, or absent).\n * 3. When an output schema is supplied:\n *    - cache its JSON Schema form for `ModelCallOptions.responseSchema`\n *      so native-structured-output providers enforce it at the token\n *      level;\n *    - fall back to a soft system-prompt instruction for providers\n *      that don't advertise `structuredOutput` capability.\n * 4. Append caller-supplied `history` (e.g. session-level prior turns).\n * 5. Shape the user message — plain string in the common case,\n *    multipart `ContentPart[]` when `attachments` are present. Image\n *    attachments require model vision capability; mismatch throws\n *    `InvalidRequestError` here rather than failing opaquely at the\n *    provider.\n *\n * Extracted from the `Execution` class to isolate the declarative\n * input-shaping phase from the stateful trip loop.\n */\nexport async function buildAgentInputMessages<TOutput>(params: {\n  config: AgentConfig<TOutput>;\n  input: string;\n  options?: AgentExecuteOptions<TOutput>;\n}): Promise<AgentInputBuildResult> {\n  const { config, input, options } = params;\n\n  const placeholders: Placeholders = {\n    ...config.placeholders,\n    ...options?.placeholders,\n  };\n\n  const systemPrompt = options?.systemPrompt ?? config.systemPrompt;\n  let systemContent = \"\";\n  let promptName: string | undefined;\n  let promptVersion: string | undefined;\n\n  if (typeof systemPrompt === \"string\") {\n    systemContent = systemPrompt;\n  } else if (systemPrompt) {\n    systemContent = systemPrompt.resolve(placeholders);\n\n    // Capture prompt-version linkage from the contract's metadata: a *named*\n    // prompt (one addressable in `ai.prompts`) stamps `promptName@version`\n    // onto the run's report so observers can group runs by the exact prompt\n    // version that produced them. Anonymous prompts carry no name and are\n    // left unlinked.\n    const meta = systemPrompt.meta();\n\n    if (meta?.name) {\n      promptName = meta.name;\n      promptVersion = meta.version ?? \"1\";\n    }\n  }\n\n  const { responseSchema, instruction } = resolveStructuredOutput({\n    outputSchema: options?.output ?? config.output,\n    overrideResponseSchema: options?.responseSchema,\n    modelSupportsStructuredOutput: Boolean(config.model.capabilities?.structuredOutput),\n  });\n\n  if (instruction) {\n    systemContent = systemContent ? `${systemContent}\\n\\n${instruction}` : instruction;\n  }\n\n  const messages: Message[] = [];\n\n  if (systemContent) {\n    messages.push({ role: \"system\", content: systemContent });\n  }\n\n  if (options?.history) {\n    messages.push(...options.history);\n  }\n\n  const userContent = await buildUserMessageContent({\n    input,\n    attachments: options?.attachments,\n    attachmentPolicy: options?.attachmentPolicy ?? config.attachmentPolicy,\n    modelName: config.model.name,\n    modelSupportsVision: Boolean(config.model.capabilities?.vision),\n    modelSupportsPdf: Boolean(config.model.capabilities?.pdf),\n    modelSupportsAudio: Boolean(config.model.capabilities?.audio),\n  });\n\n  messages.push({ role: \"user\", content: userContent });\n\n  return {\n    messages,\n    responseSchema,\n    systemPrompt: systemContent || undefined,\n    promptName,\n    promptVersion,\n  };\n}\n\n/**\n * Build the user message `content` field. Plain string when no\n * attachments (the hot path) — keeps wire payloads small. Multipart\n * `ContentPart[]` when attachments exist: input text first, resolved\n * parts in declaration order.\n */\nasync function buildUserMessageContent(params: {\n  input: string;\n  attachments?: Attachment[];\n  attachmentPolicy?: AttachmentPolicy;\n  modelName: string;\n  modelSupportsVision: boolean;\n  modelSupportsPdf: boolean;\n  modelSupportsAudio: boolean;\n}): Promise<string | ContentPart[]> {\n  const {\n    input,\n    attachments,\n    attachmentPolicy,\n    modelName,\n    modelSupportsVision,\n    modelSupportsPdf,\n    modelSupportsAudio,\n  } = params;\n\n  if (!attachments || attachments.length === 0) {\n    return input;\n  }\n\n  const parts: ContentPart[] = await Promise.all(\n    attachments.map((attachment) => prepareAttachmentPart(attachment, attachmentPolicy)),\n  );\n\n  // Capability gate per modality (A2) — reject an attachment the model\n  // can't consume here, with a clear message, rather than failing opaquely\n  // at the provider.\n  assertModality(parts, \"image\", modelSupportsVision, \"vision\", modelName);\n  assertModality(parts, \"pdf\", modelSupportsPdf, \"pdf\", modelName);\n  assertModality(parts, \"audio\", modelSupportsAudio, \"audio\", modelName);\n\n  return [{ type: \"text\", text: input }, ...parts];\n}\n\n/** Throw when a modality is present but the model doesn't declare it. */\nfunction assertModality(\n  parts: ContentPart[],\n  partType: ContentPart[\"type\"],\n  supported: boolean,\n  capability: string,\n  modelName: string,\n): void {\n  if (!supported && parts.some((part) => part.type === partType)) {\n    throw new InvalidRequestError(\n      `Model \"${modelName}\" does not declare ${capability} capability — ${partType} attachments are not supported`,\n      { context: { modelName } },\n    );\n  }\n}\n\n/**\n * When the caller supplied an `output` schema, resolve two artifacts:\n *\n * - `responseSchema` — extracted JSON Schema to attach on every trip.\n *   Adapters that natively support structured output (OpenAI's\n *   `response_format: json_schema`) consume it; others ignore it.\n * - `instruction` — a soft fallback appended to the system prompt\n *   **only** for models without native structured-output capability.\n *   Capable adapters skip it to save tokens and avoid redundancy.\n */\nfunction resolveStructuredOutput(params: {\n  outputSchema?: StandardSchemaV1<unknown>;\n  overrideResponseSchema?: Record<string, unknown>;\n  modelSupportsStructuredOutput: boolean;\n}): {\n  responseSchema?: Record<string, unknown>;\n  instruction?: string;\n} {\n  const { outputSchema, overrideResponseSchema, modelSupportsStructuredOutput } = params;\n\n  if (!outputSchema) {\n    return {};\n  }\n\n  const responseSchema = overrideResponseSchema ?? extractJsonSchema(outputSchema);\n\n  if (modelSupportsStructuredOutput) {\n    return { responseSchema };\n  }\n\n  const schemaHint = responseSchema\n    ? `\\n\\nThe response MUST match this JSON Schema:\\n${JSON.stringify(responseSchema, null, 2)}`\n    : \"\";\n\n  const instruction = [\n    \"You MUST respond with a single valid JSON value only.\",\n    \"Do not wrap it in markdown code fences. Do not include prose, commentary, or explanation — JSON only.\",\n    schemaHint,\n  ]\n    .join(\"\")\n    .trim();\n\n  return { responseSchema, instruction };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmEA,eAAsB,wBAAiC,QAIpB;CACjC,MAAM,EAAE,QAAQ,OAAO,YAAY;CAEnC,MAAM,eAA6B;EACjC,GAAG,OAAO;EACV,GAAG,SAAS;CACd;CAEA,MAAM,eAAe,SAAS,gBAAgB,OAAO;CACrD,IAAI,gBAAgB;CACpB,IAAI;CACJ,IAAI;CAEJ,IAAI,OAAO,iBAAiB,UAC1B,gBAAgB;MACX,IAAI,cAAc;EACvB,gBAAgB,aAAa,QAAQ,YAAY;EAOjD,MAAM,OAAO,aAAa,KAAK;EAE/B,IAAI,MAAM,MAAM;GACd,aAAa,KAAK;GAClB,gBAAgB,KAAK,WAAW;EAClC;CACF;CAEA,MAAM,EAAE,gBAAgB,gBAAgB,wBAAwB;EAC9D,cAAc,SAAS,UAAU,OAAO;EACxC,wBAAwB,SAAS;EACjC,+BAA+B,QAAQ,OAAO,MAAM,cAAc,gBAAgB;CACpF,CAAC;CAED,IAAI,aACF,gBAAgB,gBAAgB,GAAG,cAAc,MAAM,gBAAgB;CAGzE,MAAM,WAAsB,CAAC;CAE7B,IAAI,eACF,SAAS,KAAK;EAAE,MAAM;EAAU,SAAS;CAAc,CAAC;CAG1D,IAAI,SAAS,SACX,SAAS,KAAK,GAAG,QAAQ,OAAO;CAGlC,MAAM,cAAc,MAAM,wBAAwB;EAChD;EACA,aAAa,SAAS;EACtB,kBAAkB,SAAS,oBAAoB,OAAO;EACtD,WAAW,OAAO,MAAM;EACxB,qBAAqB,QAAQ,OAAO,MAAM,cAAc,MAAM;EAC9D,kBAAkB,QAAQ,OAAO,MAAM,cAAc,GAAG;EACxD,oBAAoB,QAAQ,OAAO,MAAM,cAAc,KAAK;CAC9D,CAAC;CAED,SAAS,KAAK;EAAE,MAAM;EAAQ,SAAS;CAAY,CAAC;CAEpD,OAAO;EACL;EACA;EACA,cAAc,iBAAiB;EAC/B;EACA;CACF;AACF;;;;;;;AAQA,eAAe,wBAAwB,QAQH;CAClC,MAAM,EACJ,OACA,aACA,kBACA,WACA,qBACA,kBACA,uBACE;CAEJ,IAAI,CAAC,eAAe,YAAY,WAAW,GACzC,OAAO;CAGT,MAAM,QAAuB,MAAM,QAAQ,IACzC,YAAY,KAAK,eAAe,sBAAsB,YAAY,gBAAgB,CAAC,CACrF;CAKA,eAAe,OAAO,SAAS,qBAAqB,UAAU,SAAS;CACvE,eAAe,OAAO,OAAO,kBAAkB,OAAO,SAAS;CAC/D,eAAe,OAAO,SAAS,oBAAoB,SAAS,SAAS;CAErE,OAAO,CAAC;EAAE,MAAM;EAAQ,MAAM;CAAM,GAAG,GAAG,KAAK;AACjD;;AAGA,SAAS,eACP,OACA,UACA,WACA,YACA,WACM;CACN,IAAI,CAAC,aAAa,MAAM,MAAM,SAAS,KAAK,SAAS,QAAQ,GAC3D,MAAM,IAAI,oBACR,UAAU,UAAU,qBAAqB,WAAW,gBAAgB,SAAS,iCAC7E,EAAE,SAAS,EAAE,UAAU,EAAE,CAC3B;AAEJ;;;;;;;;;;;AAYA,SAAS,wBAAwB,QAO/B;CACA,MAAM,EAAE,cAAc,wBAAwB,kCAAkC;CAEhF,IAAI,CAAC,cACH,OAAO,CAAC;CAGV,MAAM,iBAAiB,0BAA0B,kBAAkB,YAAY;CAE/E,IAAI,+BACF,OAAO,EAAE,eAAe;CAe1B,OAAO;EAAE;EAAgB,aARL;GAClB;GACA;GANiB,iBACf,kDAAkD,KAAK,UAAU,gBAAgB,MAAM,CAAC,MACxF;EAMJ,CAAC,CACE,KAAK,EAAE,CAAC,CACR,KAEgC;CAAE;AACvC"}

package/esm/agent/agent.d.mts

@@ -1,4 +1,5 @@
 import { AgentContract } from "../contracts/agent/agent.contract.mjs";
+import { JudgeConfig } from "./judge-config.type.mjs";
 import { AgentConfig } from "./agent-config.type.mjs";
 
 //#region ../@warlock.js/ai/src/agent/agent.d.ts
@@ -33,6 +34,44 @@ import { AgentConfig } from "./agent-config.type.mjs";
  * const result = await stream.result;
  */
 declare function agent<TOutput = unknown>(config: AgentConfig<TOutput>): AgentContract<TOutput>;
+declare namespace agent {
+  var judge: typeof judgeAgent;
+}
+/**
+ * Config for the `ai.agent.judge(...)` helper — every `AgentConfig` field
+ * except `judge` itself (the helper sets it). Callers tune resilience by
+ * passing a {@link JudgeConfig} as the second argument instead.
+ */
+type JudgeAgentConfig<TOutput = unknown> = Omit<AgentConfig<TOutput>, "judge">;
+/**
+ * Build a judge-safe agent — sugar for `agent({ ...config, judge })`.
+ *
+ * Use this for LLM-as-judge graders and verdict classifiers running on
+ * models that may emit corrupted structured output (e.g. the Amazon Nova
+ * family). The returned agent parses verdicts leniently (tolerates fenced
+ * ` ```json ` blocks + surrounding prose), auto-enables a couple of repair
+ * re-asks, and never throws on a parse miss — surfacing `result.error` with
+ * `result.data` left undefined so a flaky judge degrades gracefully.
+ *
+ * See {@link AgentConfig.judge} for the full behavior + the resilience-over-
+ * strictness trade-off.
+ *
+ * @param config - Any agent config (model, system prompt, output schema, …).
+ * @param judge - Optional fine-tuning ({@link JudgeConfig}); defaults to `true`.
+ *
+ * @example
+ * const grader = ai.agent.judge({
+ *   model: nova.model({ name: "amazon.nova-pro-v1:0" }),
+ *   systemPrompt: "Grade the answer. Respond with JSON only.",
+ *   output: verdictSchema,
+ * });
+ *
+ * const result = await grader.execute(prompt);
+ * if (result.error) {
+ *   // graceful default — the judge couldn't produce a clean verdict
+ * }
+ */
+declare function judgeAgent<TOutput = unknown>(config: JudgeAgentConfig<TOutput>, judge?: JudgeConfig | boolean): AgentContract<TOutput>;
 //#endregion
-export { agent };
+export { JudgeAgentConfig, agent };
 //# sourceMappingURL=agent.d.mts.map

package/esm/agent/agent.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/agent/agent.ts"],"mappings":";;;;;;;AA+LA;;;;;;;;;;;;;;;;AAA6F;;;;;;;;;;;iBAA7E,KAAA,oBAAyB,MAAA,EAAQ,WAAA,CAAY,OAAA,IAAW,aAAA,CAAc,OAAA"}
+{"version":3,"file":"agent.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/agent/agent.ts"],"mappings":";;;;;;;;AA6PA;;;;;;;;;;;;;;;;AAA6F;;;;;;AAqL7F;;;;;iBArLgB,KAAA,oBAAyB,MAAA,EAAQ,WAAA,CAAY,OAAA,IAAW,aAAA,CAAc,OAAA;AAAA,kBAAtE,KAAA;EAAA,kBAAK,UAAA;AAAA;;;;;AAqLqD;KAA9D,gBAAA,sBAAsC,IAAA,CAAK,WAAA,CAAY,OAAA;;;;;;;;;;;;;;;;;;;AAiC3C;;;;;;;;;;iBAHf,UAAA,oBACP,MAAA,EAAQ,gBAAA,CAAiB,OAAA,GACzB,KAAA,GAAO,WAAA,aACN,aAAA,CAAc,OAAA"}