@warlock.js/ai 4.4.0 → 4.6.0

package/esm/contracts/workflow/workflow.contract.d.mts

@@ -1,6 +1,7 @@
 import { ExecutableContract } from "../executable.contract.mjs";
 import { WorkflowResult } from "../result/workflow-result.type.mjs";
 import { ToolContract } from "../../tool/tool.mjs";
+import { FlowObserveOption } from "../../observe/resolve-observers.mjs";
 import { SnapshotStore } from "../orchestrator/snapshot-store.contract.mjs";
 import { NextStepResult } from "./next-step-result.type.mjs";
 import { RetryConfig } from "./retry-config.type.mjs";
@@ -99,6 +100,21 @@ type WorkflowDefinition<TInput = unknown, TOutput = unknown, TState = Record<str
   nextStep?: (stepName: string, ctx: WorkflowContext<TInput, TState, TContext>) => NextStepResult | Promise<NextStepResult>;
   output?: StepOutputSpec<TOutput, TInput, TState, TContext>;
   on?: WorkflowEventHandlers;
+  /**
+   * Observability for this workflow. Additive and gated — when omitted,
+   * the workflow follows the global observe-all flag (off unless an
+   * observability tool turned it on), so behavior is unchanged by
+   * default.
+   *
+   * - `true` → route this run's completed report to the globally
+   *   registered observers, even when observe-all is off.
+   * - `false` → opt this workflow out entirely, even when observe-all is on.
+   * - an `Observer` object → a flow-local collector receiving only this
+   *   workflow's report. Typed as the structural `Observer` so core stays
+   *   panoptic-agnostic; a panoptic flow-local collector can be passed
+   *   directly. Observer errors are swallowed — they never break the run.
+   */
+  observe?: FlowObserveOption;
 };
 /**
  * Runtime handle returned by `ai.workflow(def)`. Implements the

package/esm/contracts/workflow/workflow.contract.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"workflow.contract.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/workflow/workflow.contract.ts"],"mappings":";;;;;;;;;;;;;KAYY,oBAAA,iBAAqC,gBAAA,KAC/C,OAAA,EAAS,gBAAA,CAAiB,CAAA;AAAA,KAGhB,qBAAA,GAAwB,OAAA,eACtB,gBAAA,GAAmB,oBAAA,CAAqB,CAAA;;;;;KAO1C,kBAAA;EAXiB,sEAa3B,KAAA,WAd+C;EAgB/C,MAAA,GAAS,WAAA,EAfiB;EAiB1B,EAAA,GAAK,qBAAA;EAjBuB;AAAA;AAG9B;;;;;EAsBE,OAAA,GAAU,QAAA;EAtBwB;;;;;;;EA8BlC,SAAA;AAAA;AA7BqD;AAOvD;;;;AAPuD,KAqC3C,sBAAA,yCAGR,kBAAA,CAAmB,QAAA;EACrB,KAAA,EAAO,MAAA;AAAA;AAAA,KAGG,qBAAA,uBACV,kBAAkB,CAAC,QAAA;EAtCU;;EAyC3B,KAAA;AAAA;AAAA,KAGQ,kBAAA,+CAGD,MAAA;EAGT,IAAA;EApCA;;;;AAQS;EAkCT,WAAA;EA1BgC;;;;;;;;;;EAqChC,WAAA,GAAc,gBAAA,CAAiB,MAAA;EAC/B,OAAA;EACA,KAAA,EAAO,cAAA,CAAe,MAAA,EAAQ,MAAA,EAAQ,QAAA;EAnCzB;AAAA;AAGf;;;;;;;;;EA4CE,aAAA,GAAgB,aAAA,CAAc,gBAAA;EArCpB;;;;;;;;;EA+CV,YAAA,GAAe,WAAA;EACf,QAAA;EACA,aAAA;EACA,QAAA,IACE,QAAA,UACA,GAAA,EAAK,eAAA,CAAgB,MAAA,EAAQ,MAAA,EAAQ,QAAA,MAClC,cAAA,GAAiB,OAAA,CAAQ,cAAA;EAC9B,MAAA,GAAS,cAAA,CAAe,OAAA,EAAS,MAAA,EAAQ,MAAA,EAAQ,QAAA;EACjD,EAAA,GAAK,qBAAA;AAAA;;;;;;;UASU,gBAAA,+CAGN,MAAA,+CAED,kBAAA,CACR,MAAA,EACA,kBAAA,CAAmB,QAAA,GACnB,cAAA,CAAe,OAAA;EAAA,SAEN,IAAA;EAAA,SACA,WAAA;EApBJ;;;;;;EAAA,SA2BI,WAAA,GAAc,gBAAA,CAAiB,MAAA;EAAA,SAC/B,SAAA;EAAA,SACA,OAAA;EAxET;;;;;;;;;;;;;;EAwFA,OAAA,CACE,KAAA,EAAO,MAAA,EACP,OAAA,GAAU,kBAAA,CAAmB,QAAA,IAC5B,OAAA,CAAQ,cAAA,CAAe,OAAA;EAC1B,OAAA,CACE,OAAA,EAAS,sBAAA,CAAuB,MAAA,EAAQ,QAAA,IACvC,OAAA,CAAQ,cAAA,CAAe,OAAA;EAE1B,MAAA,CACE,KAAA,UACA,OAAA,GAAU,qBAAA,CAAsB,QAAA,IAC/B,OAAA,CAAQ,cAAA,CAAe,OAAA;EAE1B,EAAA,iBAAmB,gBAAA,EAAkB,KAAA,EAAO,CAAA,EAAG,OAAA,EAAS,oBAAA,CAAqB,CAAA;EAC7E,GAAA,iBAAoB,gBAAA,EAAkB,KAAA,EAAO,CAAA,EAAG,OAAA,EAAS,oBAAA,CAAqB,CAAA;EA9DvE;;;;;;;;;;;;;;;;EAgFP,MAAA,cAAoB,MAAA,EAAQ,OAAA;IAC1B,WAAA;IACA,WAAA,EAAa,gBAAA,CAAiB,UAAA;EAAA,IAC5B,YAAA,CAAa,UAAA,EAAY,OAAA;AAAA"}
+{"version":3,"file":"workflow.contract.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/workflow/workflow.contract.ts"],"mappings":";;;;;;;;;;;;;;KAaY,oBAAA,iBAAqC,gBAAA,KAC/C,OAAA,EAAS,gBAAA,CAAiB,CAAA;AAAA,KAGhB,qBAAA,GAAwB,OAAA,eACtB,gBAAA,GAAmB,oBAAA,CAAqB,CAAA;;;;;KAO1C,kBAAA;EAXiB,sEAa3B,KAAA,WAd+C;EAgB/C,MAAA,GAAS,WAAA,EAfiB;EAiB1B,EAAA,GAAK,qBAAA;EAjBuB;AAAA;AAG9B;;;;;EAsBE,OAAA,GAAU,QAAA;EAtBwB;;;;;;;EA8BlC,SAAA;AAAA;AA7BqD;AAOvD;;;;AAPuD,KAqC3C,sBAAA,yCAGR,kBAAA,CAAmB,QAAA;EACrB,KAAA,EAAO,MAAA;AAAA;AAAA,KAGG,qBAAA,uBACV,kBAAkB,CAAC,QAAA;EAtCU;;EAyC3B,KAAA;AAAA;AAAA,KAGQ,kBAAA,+CAGD,MAAA;EAGT,IAAA;EApCA;;;;AAQS;EAkCT,WAAA;EA1BgC;;;;;;;;;;EAqChC,WAAA,GAAc,gBAAA,CAAiB,MAAA;EAC/B,OAAA;EACA,KAAA,EAAO,cAAA,CAAe,MAAA,EAAQ,MAAA,EAAQ,QAAA;EAnCzB;AAAA;AAGf;;;;;;;;;EA4CE,aAAA,GAAgB,aAAA,CAAc,gBAAA;EArCpB;;;;;;;;;EA+CV,YAAA,GAAe,WAAA;EACf,QAAA;EACA,aAAA;EACA,QAAA,IACE,QAAA,UACA,GAAA,EAAK,eAAA,CAAgB,MAAA,EAAQ,MAAA,EAAQ,QAAA,MAClC,cAAA,GAAiB,OAAA,CAAQ,cAAA;EAC9B,MAAA,GAAS,cAAA,CAAe,OAAA,EAAS,MAAA,EAAQ,MAAA,EAAQ,QAAA;EACjD,EAAA,GAAK,qBAAA;EAHkC;;;;;;;;;;;;;;EAkBvC,OAAA,GAAU,iBAAA;AAAA;;;;;;;UASK,gBAAA,+CAGN,MAAA,+CAED,kBAAA,CACR,MAAA,EACA,kBAAA,CAAmB,QAAA,GACnB,cAAA,CAAe,OAAA;EAAA,SAEN,IAAA;EAAA,SACA,WAAA;EAjET;;;;;;EAAA,SAwES,WAAA,GAAc,gBAAA,CAAiB,MAAA;EAAA,SAC/B,SAAA;EAAA,SACA,OAAA;EApDM;;;;;;;;;;;;;;EAoEf,OAAA,CACE,KAAA,EAAO,MAAA,EACP,OAAA,GAAU,kBAAA,CAAmB,QAAA,IAC5B,OAAA,CAAQ,cAAA,CAAe,OAAA;EAC1B,OAAA,CACE,OAAA,EAAS,sBAAA,CAAuB,MAAA,EAAQ,QAAA,IACvC,OAAA,CAAQ,cAAA,CAAe,OAAA;EAE1B,MAAA,CACE,KAAA,UACA,OAAA,GAAU,qBAAA,CAAsB,QAAA,IAC/B,OAAA,CAAQ,cAAA,CAAe,OAAA;EAE1B,EAAA,iBAAmB,gBAAA,EAAkB,KAAA,EAAO,CAAA,EAAG,OAAA,EAAS,oBAAA,CAAqB,CAAA;EAC7E,GAAA,iBAAoB,gBAAA,EAAkB,KAAA,EAAO,CAAA,EAAG,OAAA,EAAS,oBAAA,CAAqB,CAAA;EA1E9E;;;;;AAe2B;AAS7B;;;;;;;;;;EAoEE,MAAA,cAAoB,MAAA,EAAQ,OAAA;IAC1B,WAAA;IACA,WAAA,EAAa,gBAAA,CAAiB,UAAA;EAAA,IAC5B,YAAA,CAAa,UAAA,EAAY,OAAA;AAAA"}

package/esm/errors/agent-drift-error.d.mts

@@ -0,0 +1,32 @@
+import { ErrorCategory } from "./error-category.type.mjs";
+import { AIErrorOptions } from "./ai-error.mjs";
+import { AgentExecutionError } from "./agent-execution-error.mjs";
+
+//#region ../@warlock.js/ai/src/errors/agent-drift-error.d.ts
+type AgentDriftErrorOptions = AIErrorOptions & {
+  /** Signature recorded on the snapshot being resumed. */savedSignature: string; /** Signature computed from the current agent definition. */
+  currentSignature: string;
+  runId: string;
+};
+/**
+ * `agent.resume(runId)` loaded a durable snapshot whose structural
+ * fingerprint does not match the current agent definition (model +
+ * provider + sorted tool names + maxTrips + output presence + version).
+ * The resume is refused — no trip runs — and the user decides how to
+ * recover: discard the snapshot, migrate manually, or call
+ * `resume(runId, { force: true })` to bypass the check.
+ *
+ * Mirrors `SupervisorDriftError` / `WorkflowDriftError` — same rationale,
+ * different primitive. Thrown (not returned on `result.error`) because a
+ * drifted resume never produces a valid run.
+ */
+declare class AgentDriftError extends AgentExecutionError {
+  static readonly defaultCategory: ErrorCategory;
+  readonly savedSignature: string;
+  readonly currentSignature: string;
+  readonly runId: string;
+  constructor(message: string, options: AgentDriftErrorOptions);
+}
+//#endregion
+export { AgentDriftError, AgentDriftErrorOptions };
+//# sourceMappingURL=agent-drift-error.d.mts.map

package/esm/errors/agent-drift-error.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-drift-error.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/errors/agent-drift-error.ts"],"mappings":";;;;;KAIY,sBAAA,GAAyB,cAAc;0DAEjD,cAAA,UAFgC;EAIhC,gBAAA;EACA,KAAA;AAAA;;;;;AAAK;AAeP;;;;;;;cAAa,eAAA,SAAwB,mBAAA;EAAA,gBACZ,eAAA,EAAiB,aAAA;EAAA,SAExB,cAAA;EAAA,SACA,gBAAA;EAAA,SACA,KAAA;cAEG,OAAA,UAAiB,OAAA,EAAS,sBAAA;AAAA"}

package/esm/errors/agent-drift-error.mjs

@@ -0,0 +1,31 @@
+import { AgentExecutionError } from "./agent-execution-error.mjs";
+
+//#region ../@warlock.js/ai/src/errors/agent-drift-error.ts
+/**
+* `agent.resume(runId)` loaded a durable snapshot whose structural
+* fingerprint does not match the current agent definition (model +
+* provider + sorted tool names + maxTrips + output presence + version).
+* The resume is refused — no trip runs — and the user decides how to
+* recover: discard the snapshot, migrate manually, or call
+* `resume(runId, { force: true })` to bypass the check.
+*
+* Mirrors `SupervisorDriftError` / `WorkflowDriftError` — same rationale,
+* different primitive. Thrown (not returned on `result.error`) because a
+* drifted resume never produces a valid run.
+*/
+var AgentDriftError = class extends AgentExecutionError {
+	static {
+		this.defaultCategory = "drift";
+	}
+	constructor(message, options) {
+		super(message, options, "AGENT_DRIFT");
+		this.name = "AgentDriftError";
+		this.savedSignature = options.savedSignature;
+		this.currentSignature = options.currentSignature;
+		this.runId = options.runId;
+	}
+};
+
+//#endregion
+export { AgentDriftError };
+//# sourceMappingURL=agent-drift-error.mjs.map

package/esm/errors/agent-drift-error.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-drift-error.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/errors/agent-drift-error.ts"],"sourcesContent":["import type { AIErrorOptions } from \"./ai-error\";\nimport { AgentExecutionError } from \"./agent-execution-error\";\nimport type { ErrorCategory } from \"./error-category.type\";\n\nexport type AgentDriftErrorOptions = AIErrorOptions & {\n  /** Signature recorded on the snapshot being resumed. */\n  savedSignature: string;\n  /** Signature computed from the current agent definition. */\n  currentSignature: string;\n  runId: string;\n};\n\n/**\n * `agent.resume(runId)` loaded a durable snapshot whose structural\n * fingerprint does not match the current agent definition (model +\n * provider + sorted tool names + maxTrips + output presence + version).\n * The resume is refused — no trip runs — and the user decides how to\n * recover: discard the snapshot, migrate manually, or call\n * `resume(runId, { force: true })` to bypass the check.\n *\n * Mirrors `SupervisorDriftError` / `WorkflowDriftError` — same rationale,\n * different primitive. Thrown (not returned on `result.error`) because a\n * drifted resume never produces a valid run.\n */\nexport class AgentDriftError extends AgentExecutionError {\n  public static readonly defaultCategory: ErrorCategory = \"drift\";\n\n  public readonly savedSignature: string;\n  public readonly currentSignature: string;\n  public readonly runId: string;\n\n  public constructor(message: string, options: AgentDriftErrorOptions) {\n    super(message, options, \"AGENT_DRIFT\");\n    this.name = \"AgentDriftError\";\n    this.savedSignature = options.savedSignature;\n    this.currentSignature = options.currentSignature;\n    this.runId = options.runId;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;AAwBA,IAAa,kBAAb,cAAqC,oBAAoB;;yBACC;;CAMxD,AAAO,YAAY,SAAiB,SAAiC;EACnE,MAAM,SAAS,SAAS,aAAa;EACrC,KAAK,OAAO;EACZ,KAAK,iBAAiB,QAAQ;EAC9B,KAAK,mBAAmB,QAAQ;EAChC,KAAK,QAAQ,QAAQ;CACvB;AACF"}

package/esm/errors/error-code.type.d.mts

@@ -13,7 +13,7 @@
  *   return agent.execute(input);
  * }
  */
-type AIErrorCode = "AGENT_EXEC_FAILED" | "AGENT_CANCELLED" | "AGENT_MAX_TRIPS" | "SCHEMA_VALIDATION_FAILED" | "TOOL_EXEC_FAILED" | "PROVIDER_ERROR" | "PROVIDER_RATE_LIMIT" | "PROVIDER_QUOTA_EXCEEDED" | "PROVIDER_TIMEOUT" | "CONTEXT_LENGTH_EXCEEDED" | "CONTENT_FILTER" | "PROVIDER_INVALID_REQUEST" | "PROVIDER_AUTH" | "BUDGET_EXCEEDED" | "GUARDRAIL_VIOLATION" | "WORKFLOW_ERROR" | "STEP_FAILED" | "WORKFLOW_DRIFT" | "WORKFLOW_CANCELLED" | "WORKFLOW_MAX_STEPS" | "WORKFLOW_INVALID_GOTO" | "SUPERVISOR_FAILED" | "SUPERVISOR_MAX_ITERATIONS" | "SUPERVISOR_INVALID_ROUTE" | "SUPERVISOR_CANCELLED" | "SUPERVISOR_DRIFT" | "SUPERVISOR_INTENT_DESCRIPTION_REQUIRED" | "SUPERVISOR_INTENT_MIXED_DISPATCH" | "SUPERVISOR_INTENT_STREAM_AND_OUTPUT" | "SUPERVISOR_INTENT_STREAM_TO_REQUIRED" | "SUPERVISOR_INTENT_STREAM_ON_WORKFLOW" | "SUPERVISOR_DISPATCH_CYCLE" | "ORCHESTRATOR_FAILED" | "ORCHESTRATOR_DRIFT" | "ORCHESTRATOR_CONFIG" | "ORCHESTRATOR_CANCELLED" | "PLANNER_FAILED" | "PLANNER_PLAN_INVALID" | "PLANNER_CANCELLED";
+type AIErrorCode = "AGENT_EXEC_FAILED" | "AGENT_CANCELLED" | "AGENT_MAX_TRIPS" | "AGENT_DRIFT" | "SCHEMA_VALIDATION_FAILED" | "TOOL_EXEC_FAILED" | "PROVIDER_ERROR" | "PROVIDER_RATE_LIMIT" | "PROVIDER_QUOTA_EXCEEDED" | "PROVIDER_TIMEOUT" | "CONTEXT_LENGTH_EXCEEDED" | "CONTENT_FILTER" | "PROVIDER_INVALID_REQUEST" | "PROVIDER_AUTH" | "BUDGET_EXCEEDED" | "GUARDRAIL_VIOLATION" | "WORKFLOW_ERROR" | "STEP_FAILED" | "WORKFLOW_DRIFT" | "WORKFLOW_CANCELLED" | "WORKFLOW_MAX_STEPS" | "WORKFLOW_INVALID_GOTO" | "SUPERVISOR_FAILED" | "SUPERVISOR_MAX_ITERATIONS" | "SUPERVISOR_INVALID_ROUTE" | "SUPERVISOR_CANCELLED" | "SUPERVISOR_DRIFT" | "SUPERVISOR_INTENT_DESCRIPTION_REQUIRED" | "SUPERVISOR_INTENT_MIXED_DISPATCH" | "SUPERVISOR_INTENT_STREAM_AND_OUTPUT" | "SUPERVISOR_INTENT_STREAM_TO_REQUIRED" | "SUPERVISOR_INTENT_STREAM_ON_WORKFLOW" | "SUPERVISOR_DISPATCH_CYCLE" | "ORCHESTRATOR_FAILED" | "ORCHESTRATOR_DRIFT" | "ORCHESTRATOR_CONFIG" | "ORCHESTRATOR_CANCELLED" | "PLANNER_FAILED" | "PLANNER_PLAN_INVALID" | "PLANNER_CANCELLED" | "PLANNER_DRIFT" | "VCR_CASSETTE_MISS" | "OUTBOUND_POLICY_BLOCKED";
 //#endregion
 export { AIErrorCode };
 //# sourceMappingURL=error-code.type.d.mts.map

package/esm/errors/index.d.mts

@@ -3,6 +3,7 @@ import { AIErrorCode } from "./error-code.type.mjs";
 import { AIError, AIErrorOptions } from "./ai-error.mjs";
 import { AgentExecutionError } from "./agent-execution-error.mjs";
 import { AgentCancelledError, AgentCancelledErrorOptions } from "./agent-cancelled-error.mjs";
+import { AgentDriftError, AgentDriftErrorOptions } from "./agent-drift-error.mjs";
 import { AgentMaxTripsError, AgentMaxTripsErrorOptions } from "./agent-max-trips-error.mjs";
 import { BudgetExceededError, BudgetExceededErrorOptions, BudgetUnit } from "./budget-exceeded-error.mjs";
 import { ProviderError } from "./provider-error.mjs";
@@ -18,8 +19,10 @@ import { OrchestratorFailedError } from "./orchestrator-failed-error.mjs";
 import { OrchestratorCancelledError, OrchestratorCancelledErrorOptions } from "./orchestrator-cancelled-error.mjs";
 import { OrchestratorConfigError } from "./orchestrator-config-error.mjs";
 import { OrchestratorDriftError, OrchestratorDriftErrorOptions } from "./orchestrator-drift-error.mjs";
+import { OutboundPolicyError } from "./outbound-policy-error.mjs";
 import { PlannerFailedError } from "./planner-failed-error.mjs";
 import { PlannerCancelledError, PlannerCancelledErrorOptions } from "./planner-cancelled-error.mjs";
+import { PlannerDriftError, PlannerDriftErrorOptions } from "./planner-drift-error.mjs";
 import { PlannerPlanInvalidError } from "./planner-plan-invalid-error.mjs";
 import { ProviderAuthError } from "./provider-auth-error.mjs";
 import { ProviderRateLimitError, ProviderRateLimitErrorOptions } from "./provider-rate-limit-error.mjs";

package/esm/errors/index.mjs

@@ -1,6 +1,7 @@
 import { AIError } from "./ai-error.mjs";
 import { AgentExecutionError } from "./agent-execution-error.mjs";
 import { AgentCancelledError } from "./agent-cancelled-error.mjs";
+import { AgentDriftError } from "./agent-drift-error.mjs";
 import { AgentMaxTripsError } from "./agent-max-trips-error.mjs";
 import { BudgetExceededError } from "./budget-exceeded-error.mjs";
 import { ProviderError } from "./provider-error.mjs";
@@ -16,8 +17,10 @@ import { OrchestratorFailedError } from "./orchestrator-failed-error.mjs";
 import { OrchestratorCancelledError } from "./orchestrator-cancelled-error.mjs";
 import { OrchestratorConfigError } from "./orchestrator-config-error.mjs";
 import { OrchestratorDriftError } from "./orchestrator-drift-error.mjs";
+import { OutboundPolicyError } from "./outbound-policy-error.mjs";
 import { PlannerFailedError } from "./planner-failed-error.mjs";
 import { PlannerCancelledError } from "./planner-cancelled-error.mjs";
+import { PlannerDriftError } from "./planner-drift-error.mjs";
 import { PlannerPlanInvalidError } from "./planner-plan-invalid-error.mjs";
 import { ProviderAuthError } from "./provider-auth-error.mjs";
 import { ProviderRateLimitError } from "./provider-rate-limit-error.mjs";

package/esm/errors/outbound-policy-error.d.mts

@@ -0,0 +1,27 @@
+import { ErrorCategory } from "./error-category.type.mjs";
+import { AIError, AIErrorOptions } from "./ai-error.mjs";
+
+//#region ../@warlock.js/ai/src/errors/outbound-policy-error.d.ts
+/**
+ * A server-side outbound request (attachment fetch, URL skill manifest,
+ * RAG loader, …) was blocked by the shared `OutboundPolicy` before it
+ * left the process — a disallowed scheme, a host outside the allowlist, a
+ * private / loopback / link-local / cloud-metadata address resolved after
+ * DNS, an oversized body, or a timeout.
+ *
+ * This is the framework's SSRF / resource-exhaustion guard surfacing: the
+ * request was refused on purpose, not a provider failure. `context`
+ * carries the offending `url` / `host` / `reason` for logs.
+ *
+ * @example
+ * if (error instanceof OutboundPolicyError) {
+ *   logger.warn("blocked outbound fetch", { context: error.context });
+ * }
+ */
+declare class OutboundPolicyError extends AIError {
+  static readonly defaultCategory: ErrorCategory;
+  constructor(message: string, options?: AIErrorOptions);
+}
+//#endregion
+export { OutboundPolicyError };
+//# sourceMappingURL=outbound-policy-error.d.mts.map

package/esm/errors/outbound-policy-error.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbound-policy-error.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/errors/outbound-policy-error.ts"],"mappings":";;;;;;AAmBA;;;;;;;;;;;;;;cAAa,mBAAA,SAA4B,OAAA;EAAA,gBAChB,eAAA,EAAiB,aAAA;cAErB,OAAA,UAAiB,OAAA,GAAU,cAAA;AAAA"}

package/esm/errors/outbound-policy-error.mjs

@@ -0,0 +1,32 @@
+import { AIError } from "./ai-error.mjs";
+
+//#region ../@warlock.js/ai/src/errors/outbound-policy-error.ts
+/**
+* A server-side outbound request (attachment fetch, URL skill manifest,
+* RAG loader, …) was blocked by the shared `OutboundPolicy` before it
+* left the process — a disallowed scheme, a host outside the allowlist, a
+* private / loopback / link-local / cloud-metadata address resolved after
+* DNS, an oversized body, or a timeout.
+*
+* This is the framework's SSRF / resource-exhaustion guard surfacing: the
+* request was refused on purpose, not a provider failure. `context`
+* carries the offending `url` / `host` / `reason` for logs.
+*
+* @example
+* if (error instanceof OutboundPolicyError) {
+*   logger.warn("blocked outbound fetch", { context: error.context });
+* }
+*/
+var OutboundPolicyError = class extends AIError {
+	static {
+		this.defaultCategory = "validation";
+	}
+	constructor(message, options) {
+		super("OUTBOUND_POLICY_BLOCKED", message, options);
+		this.name = "OutboundPolicyError";
+	}
+};
+
+//#endregion
+export { OutboundPolicyError };
+//# sourceMappingURL=outbound-policy-error.mjs.map

package/esm/errors/outbound-policy-error.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbound-policy-error.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/errors/outbound-policy-error.ts"],"sourcesContent":["import { AIError, type AIErrorOptions } from \"./ai-error\";\nimport type { ErrorCategory } from \"./error-category.type\";\n\n/**\n * A server-side outbound request (attachment fetch, URL skill manifest,\n * RAG loader, …) was blocked by the shared `OutboundPolicy` before it\n * left the process — a disallowed scheme, a host outside the allowlist, a\n * private / loopback / link-local / cloud-metadata address resolved after\n * DNS, an oversized body, or a timeout.\n *\n * This is the framework's SSRF / resource-exhaustion guard surfacing: the\n * request was refused on purpose, not a provider failure. `context`\n * carries the offending `url` / `host` / `reason` for logs.\n *\n * @example\n * if (error instanceof OutboundPolicyError) {\n *   logger.warn(\"blocked outbound fetch\", { context: error.context });\n * }\n */\nexport class OutboundPolicyError extends AIError {\n  public static readonly defaultCategory: ErrorCategory = \"validation\";\n\n  public constructor(message: string, options?: AIErrorOptions) {\n    super(\"OUTBOUND_POLICY_BLOCKED\", message, options);\n    this.name = \"OutboundPolicyError\";\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAmBA,IAAa,sBAAb,cAAyC,QAAQ;;yBACS;;CAExD,AAAO,YAAY,SAAiB,SAA0B;EAC5D,MAAM,2BAA2B,SAAS,OAAO;EACjD,KAAK,OAAO;CACd;AACF"}

package/esm/errors/planner-drift-error.d.mts

@@ -0,0 +1,34 @@
+import { ErrorCategory } from "./error-category.type.mjs";
+import { AIErrorOptions } from "./ai-error.mjs";
+import { PlannerFailedError } from "./planner-failed-error.mjs";
+
+//#region ../@warlock.js/ai/src/errors/planner-drift-error.d.ts
+type PlannerDriftErrorOptions = AIErrorOptions & {
+  /** Signature recorded on the snapshot being resumed. */savedSignature: string; /** Signature computed from the current planner definition. */
+  currentSignature: string;
+  runId: string;
+};
+/**
+ * `planner.resume(runId)` loaded a durable snapshot whose structural
+ * fingerprint does not match the current planner definition (name +
+ * ordered capability names). The resume is refused — no node runs — and
+ * the user decides how to recover: discard the snapshot, migrate
+ * manually, or call `resume(runId, { force: true })` to bypass the check.
+ *
+ * A mid-run re-plan is NOT drift — the plan changed, not the definition;
+ * the persisted `replanCount` honors the replan budget across a resume.
+ *
+ * Mirrors `SupervisorDriftError` / `WorkflowDriftError` — same rationale,
+ * different primitive. Thrown (not returned on `result.error`) because a
+ * drifted resume never produces a valid run.
+ */
+declare class PlannerDriftError extends PlannerFailedError {
+  static readonly defaultCategory: ErrorCategory;
+  readonly savedSignature: string;
+  readonly currentSignature: string;
+  readonly runId: string;
+  constructor(message: string, options: PlannerDriftErrorOptions);
+}
+//#endregion
+export { PlannerDriftError, PlannerDriftErrorOptions };
+//# sourceMappingURL=planner-drift-error.d.mts.map

package/esm/errors/planner-drift-error.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner-drift-error.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/errors/planner-drift-error.ts"],"mappings":";;;;;KAIY,wBAAA,GAA2B,cAAc;0DAEnD,cAAA,UAFkC;EAIlC,gBAAA;EACA,KAAA;AAAA;;;;;AAAK;AAiBP;;;;;;;;;cAAa,iBAAA,SAA0B,kBAAA;EAAA,gBACd,eAAA,EAAiB,aAAA;EAAA,SAExB,cAAA;EAAA,SACA,gBAAA;EAAA,SACA,KAAA;cAEG,OAAA,UAAiB,OAAA,EAAS,wBAAA;AAAA"}

package/esm/errors/planner-drift-error.mjs

@@ -0,0 +1,33 @@
+import { PlannerFailedError } from "./planner-failed-error.mjs";
+
+//#region ../@warlock.js/ai/src/errors/planner-drift-error.ts
+/**
+* `planner.resume(runId)` loaded a durable snapshot whose structural
+* fingerprint does not match the current planner definition (name +
+* ordered capability names). The resume is refused — no node runs — and
+* the user decides how to recover: discard the snapshot, migrate
+* manually, or call `resume(runId, { force: true })` to bypass the check.
+*
+* A mid-run re-plan is NOT drift — the plan changed, not the definition;
+* the persisted `replanCount` honors the replan budget across a resume.
+*
+* Mirrors `SupervisorDriftError` / `WorkflowDriftError` — same rationale,
+* different primitive. Thrown (not returned on `result.error`) because a
+* drifted resume never produces a valid run.
+*/
+var PlannerDriftError = class extends PlannerFailedError {
+	static {
+		this.defaultCategory = "drift";
+	}
+	constructor(message, options) {
+		super(message, options, "PLANNER_DRIFT");
+		this.name = "PlannerDriftError";
+		this.savedSignature = options.savedSignature;
+		this.currentSignature = options.currentSignature;
+		this.runId = options.runId;
+	}
+};
+
+//#endregion
+export { PlannerDriftError };
+//# sourceMappingURL=planner-drift-error.mjs.map

package/esm/errors/planner-drift-error.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner-drift-error.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/errors/planner-drift-error.ts"],"sourcesContent":["import type { AIErrorOptions } from \"./ai-error\";\nimport type { ErrorCategory } from \"./error-category.type\";\nimport { PlannerFailedError } from \"./planner-failed-error\";\n\nexport type PlannerDriftErrorOptions = AIErrorOptions & {\n  /** Signature recorded on the snapshot being resumed. */\n  savedSignature: string;\n  /** Signature computed from the current planner definition. */\n  currentSignature: string;\n  runId: string;\n};\n\n/**\n * `planner.resume(runId)` loaded a durable snapshot whose structural\n * fingerprint does not match the current planner definition (name +\n * ordered capability names). The resume is refused — no node runs — and\n * the user decides how to recover: discard the snapshot, migrate\n * manually, or call `resume(runId, { force: true })` to bypass the check.\n *\n * A mid-run re-plan is NOT drift — the plan changed, not the definition;\n * the persisted `replanCount` honors the replan budget across a resume.\n *\n * Mirrors `SupervisorDriftError` / `WorkflowDriftError` — same rationale,\n * different primitive. Thrown (not returned on `result.error`) because a\n * drifted resume never produces a valid run.\n */\nexport class PlannerDriftError extends PlannerFailedError {\n  public static readonly defaultCategory: ErrorCategory = \"drift\";\n\n  public readonly savedSignature: string;\n  public readonly currentSignature: string;\n  public readonly runId: string;\n\n  public constructor(message: string, options: PlannerDriftErrorOptions) {\n    super(message, options, \"PLANNER_DRIFT\");\n    this.name = \"PlannerDriftError\";\n    this.savedSignature = options.savedSignature;\n    this.currentSignature = options.currentSignature;\n    this.runId = options.runId;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AA0BA,IAAa,oBAAb,cAAuC,mBAAmB;;yBACA;;CAMxD,AAAO,YAAY,SAAiB,SAAmC;EACrE,MAAM,SAAS,SAAS,eAAe;EACvC,KAAK,OAAO;EACZ,KAAK,iBAAiB,QAAQ;EAC9B,KAAK,mBAAmB,QAAQ;EAChC,KAAK,QAAQ,QAAQ;CACvB;AACF"}

package/esm/eval/dataset.d.mts

@@ -0,0 +1,28 @@
+import { DatasetContract, DatasetOptions } from "./dataset.type.mjs";
+
+//#region ../@warlock.js/ai/src/eval/dataset.d.ts
+/**
+ * Create an immutable evaluation dataset that feeds `agent.eval({ cases })`
+ * directly.
+ *
+ * **Role.** A taggable, filterable, shardable wrapper around a list of
+ * {@link DatasetEntry} rows. `agent.eval` accepts a `DatasetContract` in
+ * place of a raw `EvalCase[]`, reading `.cases` off it.
+ *
+ * Sources (combinable — file entries append after inline `cases`):
+ * - `cases` → inline entries.
+ * - `fromFile` → a JSONL file read once, synchronously, at construction
+ *   (one JSON object per line). A malformed line throws an
+ *   `InvalidRequestError` naming the 1-based line number.
+ *
+ * @example
+ * const ds = dataset({ name: "support", fromFile: "./eval/support.jsonl" });
+ * const smoke = ds.filter((entry) => entry.tags?.includes("smoke"));
+ * const shard = ds.shard(0, 4); // first of four parallel CI shards
+ *
+ * const report = await agent.eval({ cases: ds, scorers: [contains()] });
+ */
+declare function dataset<TOutput = unknown>(options: DatasetOptions<TOutput>): DatasetContract<TOutput>;
+//#endregion
+export { dataset };
+//# sourceMappingURL=dataset.d.mts.map

package/esm/eval/dataset.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataset.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/eval/dataset.ts"],"mappings":";;;;;AAkIA;;;;;;;;;;;;;;;;AAE0B;;;iBAFV,OAAA,oBACd,OAAA,EAAS,cAAA,CAAe,OAAA,IACvB,eAAA,CAAgB,OAAA"}

package/esm/eval/dataset.mjs

@@ -0,0 +1,112 @@
+import { InvalidRequestError } from "../errors/invalid-request-error.mjs";
+import "../errors/index.mjs";
+import { readFileSync } from "node:fs";
+
+//#region ../@warlock.js/ai/src/eval/dataset.ts
+/**
+* Parse a JSONL file's contents into {@link DatasetEntry} rows. Blank
+* lines (and trailing whitespace-only lines) are skipped; every other
+* line must be a JSON object. A malformed line throws an
+* `InvalidRequestError` naming the 1-based line number — failing loud at
+* construction, like `SystemPrompt.fromFile`.
+*/
+function parseJsonl(path, contents) {
+	const entries = [];
+	const lines = contents.split(/\r?\n/);
+	for (let index = 0; index < lines.length; index++) {
+		const line = lines[index].trim();
+		if (line === "") continue;
+		let parsed;
+		try {
+			parsed = JSON.parse(line);
+		} catch (error) {
+			throw new InvalidRequestError(`Failed to parse dataset file "${path}" — line ${index + 1} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`, {
+				context: {
+					path,
+					line: index + 1
+				},
+				cause: error
+			});
+		}
+		if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new InvalidRequestError(`Failed to parse dataset file "${path}" — line ${index + 1} is not a JSON object`, { context: {
+			path,
+			line: index + 1
+		} });
+		entries.push(parsed);
+	}
+	return entries;
+}
+/**
+* Read a JSONL dataset file once, synchronously, at construction.
+* Mirrors `SystemPrompt.fromFile`: a read failure (missing path,
+* permission denied) throws an `InvalidRequestError` surfacing the
+* underlying cause.
+*/
+function readDatasetFile(path) {
+	let contents;
+	try {
+		contents = readFileSync(path, "utf8");
+	} catch (error) {
+		throw new InvalidRequestError(`Failed to read dataset file "${path}" — ${error instanceof Error ? error.message : String(error)}`, {
+			context: { path },
+			cause: error
+		});
+	}
+	return parseJsonl(path, contents);
+}
+/**
+* Build an immutable {@link DatasetContract} over the given entries.
+* Shared by the {@link dataset} factory and by `filter` / `shard`, which
+* each return a fresh dataset built from a derived case list.
+*/
+function makeDataset(name, cases) {
+	return {
+		name,
+		cases,
+		filter(predicate) {
+			return makeDataset(name, cases.filter(predicate));
+		},
+		shard(index, total) {
+			if (!Number.isInteger(total) || total <= 0) throw new InvalidRequestError(`dataset.shard: "total" must be a positive integer, received ${total}`, { context: {
+				name,
+				total
+			} });
+			if (!Number.isInteger(index) || index < 0 || index >= total) throw new InvalidRequestError(`dataset.shard: "index" must be an integer in [0, ${total}), received ${index}`, { context: {
+				name,
+				index,
+				total
+			} });
+			return makeDataset(name, cases.filter((_, position) => position % total === index));
+		}
+	};
+}
+/**
+* Create an immutable evaluation dataset that feeds `agent.eval({ cases })`
+* directly.
+*
+* **Role.** A taggable, filterable, shardable wrapper around a list of
+* {@link DatasetEntry} rows. `agent.eval` accepts a `DatasetContract` in
+* place of a raw `EvalCase[]`, reading `.cases` off it.
+*
+* Sources (combinable — file entries append after inline `cases`):
+* - `cases` → inline entries.
+* - `fromFile` → a JSONL file read once, synchronously, at construction
+*   (one JSON object per line). A malformed line throws an
+*   `InvalidRequestError` naming the 1-based line number.
+*
+* @example
+* const ds = dataset({ name: "support", fromFile: "./eval/support.jsonl" });
+* const smoke = ds.filter((entry) => entry.tags?.includes("smoke"));
+* const shard = ds.shard(0, 4); // first of four parallel CI shards
+*
+* const report = await agent.eval({ cases: ds, scorers: [contains()] });
+*/
+function dataset(options) {
+	const cases = [...options.cases ?? []];
+	if (options.fromFile !== void 0) cases.push(...readDatasetFile(options.fromFile));
+	return makeDataset(options.name, cases);
+}
+
+//#endregion
+export { dataset };
+//# sourceMappingURL=dataset.mjs.map

package/esm/eval/dataset.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataset.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/eval/dataset.ts"],"sourcesContent":["import { readFileSync } from \"node:fs\";\nimport type { DatasetContract, DatasetEntry, DatasetOptions } from \"./dataset.type\";\nimport { InvalidRequestError } from \"../errors\";\n\n/**\n * Parse a JSONL file's contents into {@link DatasetEntry} rows. Blank\n * lines (and trailing whitespace-only lines) are skipped; every other\n * line must be a JSON object. A malformed line throws an\n * `InvalidRequestError` naming the 1-based line number — failing loud at\n * construction, like `SystemPrompt.fromFile`.\n */\nfunction parseJsonl<TOutput>(path: string, contents: string): DatasetEntry<TOutput>[] {\n  const entries: DatasetEntry<TOutput>[] = [];\n  const lines = contents.split(/\\r?\\n/);\n\n  for (let index = 0; index < lines.length; index++) {\n    const line = lines[index].trim();\n\n    if (line === \"\") {\n      continue;\n    }\n\n    let parsed: unknown;\n\n    try {\n      parsed = JSON.parse(line);\n    } catch (error) {\n      throw new InvalidRequestError(\n        `Failed to parse dataset file \"${path}\" — line ${index + 1} is not valid JSON: ${\n          error instanceof Error ? error.message : String(error)\n        }`,\n        { context: { path, line: index + 1 }, cause: error },\n      );\n    }\n\n    if (parsed === null || typeof parsed !== \"object\" || Array.isArray(parsed)) {\n      throw new InvalidRequestError(\n        `Failed to parse dataset file \"${path}\" — line ${index + 1} is not a JSON object`,\n        { context: { path, line: index + 1 } },\n      );\n    }\n\n    entries.push(parsed as DatasetEntry<TOutput>);\n  }\n\n  return entries;\n}\n\n/**\n * Read a JSONL dataset file once, synchronously, at construction.\n * Mirrors `SystemPrompt.fromFile`: a read failure (missing path,\n * permission denied) throws an `InvalidRequestError` surfacing the\n * underlying cause.\n */\nfunction readDatasetFile<TOutput>(path: string): DatasetEntry<TOutput>[] {\n  let contents: string;\n\n  try {\n    contents = readFileSync(path, \"utf8\");\n  } catch (error) {\n    throw new InvalidRequestError(\n      `Failed to read dataset file \"${path}\" — ${\n        error instanceof Error ? error.message : String(error)\n      }`,\n      { context: { path }, cause: error },\n    );\n  }\n\n  return parseJsonl<TOutput>(path, contents);\n}\n\n/**\n * Build an immutable {@link DatasetContract} over the given entries.\n * Shared by the {@link dataset} factory and by `filter` / `shard`, which\n * each return a fresh dataset built from a derived case list.\n */\nfunction makeDataset<TOutput>(\n  name: string,\n  cases: DatasetEntry<TOutput>[],\n): DatasetContract<TOutput> {\n  return {\n    name,\n    cases,\n    filter(predicate) {\n      return makeDataset(name, cases.filter(predicate));\n    },\n    shard(index, total) {\n      if (!Number.isInteger(total) || total <= 0) {\n        throw new InvalidRequestError(\n          `dataset.shard: \"total\" must be a positive integer, received ${total}`,\n          { context: { name, total } },\n        );\n      }\n\n      if (!Number.isInteger(index) || index < 0 || index >= total) {\n        throw new InvalidRequestError(\n          `dataset.shard: \"index\" must be an integer in [0, ${total}), received ${index}`,\n          { context: { name, index, total } },\n        );\n      }\n\n      return makeDataset(\n        name,\n        cases.filter((_, position) => position % total === index),\n      );\n    },\n  };\n}\n\n/**\n * Create an immutable evaluation dataset that feeds `agent.eval({ cases })`\n * directly.\n *\n * **Role.** A taggable, filterable, shardable wrapper around a list of\n * {@link DatasetEntry} rows. `agent.eval` accepts a `DatasetContract` in\n * place of a raw `EvalCase[]`, reading `.cases` off it.\n *\n * Sources (combinable — file entries append after inline `cases`):\n * - `cases` → inline entries.\n * - `fromFile` → a JSONL file read once, synchronously, at construction\n *   (one JSON object per line). A malformed line throws an\n *   `InvalidRequestError` naming the 1-based line number.\n *\n * @example\n * const ds = dataset({ name: \"support\", fromFile: \"./eval/support.jsonl\" });\n * const smoke = ds.filter((entry) => entry.tags?.includes(\"smoke\"));\n * const shard = ds.shard(0, 4); // first of four parallel CI shards\n *\n * const report = await agent.eval({ cases: ds, scorers: [contains()] });\n */\nexport function dataset<TOutput = unknown>(\n  options: DatasetOptions<TOutput>,\n): DatasetContract<TOutput> {\n  const cases: DatasetEntry<TOutput>[] = [...(options.cases ?? [])];\n\n  if (options.fromFile !== undefined) {\n    cases.push(...readDatasetFile<TOutput>(options.fromFile));\n  }\n\n  return makeDataset(options.name, cases);\n}\n"],"mappings":";;;;;;;;;;;;AAWA,SAAS,WAAoB,MAAc,UAA2C;CACpF,MAAM,UAAmC,CAAC;CAC1C,MAAM,QAAQ,SAAS,MAAM,OAAO;CAEpC,KAAK,IAAI,QAAQ,GAAG,QAAQ,MAAM,QAAQ,SAAS;EACjD,MAAM,OAAO,MAAM,MAAM,CAAC,KAAK;EAE/B,IAAI,SAAS,IACX;EAGF,IAAI;EAEJ,IAAI;GACF,SAAS,KAAK,MAAM,IAAI;EAC1B,SAAS,OAAO;GACd,MAAM,IAAI,oBACR,iCAAiC,KAAK,WAAW,QAAQ,EAAE,sBACzD,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,KAEvD;IAAE,SAAS;KAAE;KAAM,MAAM,QAAQ;IAAE;IAAG,OAAO;GAAM,CACrD;EACF;EAEA,IAAI,WAAW,QAAQ,OAAO,WAAW,YAAY,MAAM,QAAQ,MAAM,GACvE,MAAM,IAAI,oBACR,iCAAiC,KAAK,WAAW,QAAQ,EAAE,wBAC3D,EAAE,SAAS;GAAE;GAAM,MAAM,QAAQ;EAAE,EAAE,CACvC;EAGF,QAAQ,KAAK,MAA+B;CAC9C;CAEA,OAAO;AACT;;;;;;;AAQA,SAAS,gBAAyB,MAAuC;CACvE,IAAI;CAEJ,IAAI;EACF,WAAW,aAAa,MAAM,MAAM;CACtC,SAAS,OAAO;EACd,MAAM,IAAI,oBACR,gCAAgC,KAAK,MACnC,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,KAEvD;GAAE,SAAS,EAAE,KAAK;GAAG,OAAO;EAAM,CACpC;CACF;CAEA,OAAO,WAAoB,MAAM,QAAQ;AAC3C;;;;;;AAOA,SAAS,YACP,MACA,OAC0B;CAC1B,OAAO;EACL;EACA;EACA,OAAO,WAAW;GAChB,OAAO,YAAY,MAAM,MAAM,OAAO,SAAS,CAAC;EAClD;EACA,MAAM,OAAO,OAAO;GAClB,IAAI,CAAC,OAAO,UAAU,KAAK,KAAK,SAAS,GACvC,MAAM,IAAI,oBACR,+DAA+D,SAC/D,EAAE,SAAS;IAAE;IAAM;GAAM,EAAE,CAC7B;GAGF,IAAI,CAAC,OAAO,UAAU,KAAK,KAAK,QAAQ,KAAK,SAAS,OACpD,MAAM,IAAI,oBACR,oDAAoD,MAAM,cAAc,SACxE,EAAE,SAAS;IAAE;IAAM;IAAO;GAAM,EAAE,CACpC;GAGF,OAAO,YACL,MACA,MAAM,QAAQ,GAAG,aAAa,WAAW,UAAU,KAAK,CAC1D;EACF;CACF;AACF;;;;;;;;;;;;;;;;;;;;;;AAuBA,SAAgB,QACd,SAC0B;CAC1B,MAAM,QAAiC,CAAC,GAAI,QAAQ,SAAS,CAAC,CAAE;CAEhE,IAAI,QAAQ,aAAa,QACvB,MAAM,KAAK,GAAG,gBAAyB,QAAQ,QAAQ,CAAC;CAG1D,OAAO,YAAY,QAAQ,MAAM,KAAK;AACxC"}

package/esm/eval/dataset.type.d.mts

@@ -0,0 +1,53 @@
+import { EvalCase } from "../contracts/agent/eval.type.mjs";
+
+//#region ../@warlock.js/ai/src/eval/dataset.type.d.ts
+/**
+ * A single dataset row. A superset of {@link EvalCase} — every dataset
+ * entry is a valid eval case, plus optional `tags` for filtering and
+ * sharding a large suite.
+ */
+type DatasetEntry<TOutput = unknown> = EvalCase<TOutput> & {
+  /** Optional tags for filtering / sharding a large dataset. */tags?: string[];
+};
+/**
+ * An immutable, filterable, shardable collection of {@link DatasetEntry}
+ * rows that feeds `agent.eval({ cases })` directly. Built via the
+ * {@link dataset} factory — never `new`.
+ */
+type DatasetContract<TOutput = unknown> = {
+  /** Stable identifier for the dataset — surfaced for logging / artifacts. */readonly name: string; /** All entries (after any filter / shard applied at construction). */
+  readonly cases: DatasetEntry<TOutput>[];
+  /**
+   * Narrow by an arbitrary predicate (typically a tag check) — returns a
+   * new dataset sharing nothing mutable with this one.
+   */
+  filter(predicate: (entry: DatasetEntry<TOutput>) => boolean): DatasetContract<TOutput>;
+  /**
+   * Deterministic shard `index`-of-`total` for parallel CI jobs. Every
+   * entry lands in exactly one shard (round-robin by position), so the
+   * union of all `total` shards reproduces the full case list with no
+   * gaps or overlaps.
+   */
+  shard(index: number, total: number): DatasetContract<TOutput>;
+};
+/**
+ * Options for the {@link dataset} factory. Supply `cases` inline, or
+ * `fromFile` to load a JSONL file (one JSON-encoded {@link DatasetEntry}
+ * per line) synchronously at construction — mirroring
+ * `SystemPrompt.fromFile`'s one-shot sync read. Both may be combined;
+ * file entries are appended after inline `cases`.
+ */
+type DatasetOptions<TOutput = unknown> = {
+  /** Stable identifier for the dataset. */name: string; /** Inline entries. */
+  cases?: DatasetEntry<TOutput>[];
+  /**
+   * Path to a JSONL file read once, synchronously, at construction. Each
+   * non-blank line must be a JSON object matching {@link DatasetEntry}; a
+   * malformed line throws an `InvalidRequestError` naming the 1-based line
+   * number.
+   */
+  fromFile?: string;
+};
+//#endregion
+export { DatasetContract, DatasetEntry, DatasetOptions };
+//# sourceMappingURL=dataset.type.d.mts.map

package/esm/eval/dataset.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataset.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/eval/dataset.type.ts"],"mappings":";;;;;AAOA;;;KAAY,YAAA,sBAAkC,QAAQ,CAAC,OAAA;EAA9B,8DAEvB,IAAA;AAAA;;;AAAI;AAQN;;KAAY,eAAA;EAImB,qFAFpB,IAAA,UAQyB;EAAA,SANzB,KAAA,EAAO,YAAA,CAAa,OAAA;EAOV;;;;EAFnB,MAAA,CACE,SAAA,GAAY,KAAA,EAAO,YAAA,CAAa,OAAA,gBAC/B,eAAA,CAAgB,OAAA;EAOiC;;;;;;EAApD,KAAA,CAAM,KAAA,UAAe,KAAA,WAAgB,eAAA,CAAgB,OAAA;AAAA;;;;;;;;KAU3C,cAAA;EAV2B,yCAYrC,IAAA,UAZ4D;EAc5D,KAAA,GAAQ,YAAY,CAAC,OAAA;EAJX;;;;;;EAWV,QAAA;AAAA"}

package/esm/eval/eval-runner.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"eval-runner.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/eval/eval-runner.ts"],"mappings":";;;;;;AAmIA;;;;;;;iBAAsB,OAAA,UACpB,KAAA,EAAO,aAAA,CAAc,OAAA,GACrB,OAAA,EAAS,WAAA,CAAY,OAAA,IACpB,OAAA,CAAQ,UAAA,CAAW,OAAA"}
+{"version":3,"file":"eval-runner.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/eval/eval-runner.ts"],"mappings":";;;;;;AAqJA;;;;;;;iBAAsB,OAAA,UACpB,KAAA,EAAO,aAAA,CAAc,OAAA,GACrB,OAAA,EAAS,WAAA,CAAY,OAAA,IACpB,OAAA,CAAQ,UAAA,CAAW,OAAA"}

package/esm/eval/eval-runner.mjs

@@ -1,9 +1,20 @@
 import { AgentExecutionError } from "../errors/agent-execution-error.mjs";
 import "../errors/index.mjs";
 import { judge } from "./judge-scorer.mjs";
+import { diff } from "./regression.mjs";
 import { log } from "@warlock.js/logger";
 
 //#region ../@warlock.js/ai/src/eval/eval-runner.ts
+/**
+* Narrow `EvalOptions.cases` to the underlying `EvalCase[]`. A
+* `DatasetContract` is identified structurally by its `cases` property
+* (an array carried alongside `name` / `filter` / `shard`); a raw
+* `EvalCase[]` is used as-is.
+*/
+function resolveCases(cases) {
+	if (Array.isArray(cases)) return cases;
+	return cases.cases;
+}
 const LOG_MODULE = "ai.eval";
 const DEFAULT_PASS_THRESHOLD = .5;
 /**
@@ -86,8 +97,9 @@ async function runCase(agent, evalCase, options, passThreshold) {
 async function runEval(agent, options) {
 	const passThreshold = options.passThreshold ?? DEFAULT_PASS_THRESHOLD;
 	const start = performance.now();
+	const suiteCases = resolveCases(options.cases);
 	const cases = [];
-	for (const evalCase of options.cases) {
+	for (const evalCase of suiteCases) {
 		const caseResult = await runCase(agent, evalCase, options, passThreshold);
 		cases.push(caseResult);
 		if (!caseResult.passed && options.onFailure) try {
@@ -103,7 +115,7 @@ async function runEval(agent, options) {
 	const passedCount = cases.filter((entry) => entry.passed).length;
 	const total = cases.length;
 	const meanScore = total > 0 ? cases.reduce((sum, entry) => sum + entry.score, 0) / total : 0;
-	return {
+	const report = {
 		agentName: agent.name,
 		total,
 		passedCount,
@@ -114,6 +126,8 @@ async function runEval(agent, options) {
 		cases,
 		duration: performance.now() - start
 	};
+	if (options.baseline) report.regression = diff(report, options.baseline, options.tolerance);
+	return report;
 }
 
 //#endregion