@warlock.js/ai 4.1.1

package/esm/ai.d.mts

@@ -0,0 +1,64 @@
+import { tool } from "./tool/tool.mjs";
+import { agent } from "./agent/agent.mjs";
+import { setAIConfig } from "./config.mjs";
+import { budget } from "./middleware/builtins/budget.mjs";
+import { guardrail } from "./middleware/builtins/guardrail.mjs";
+import { semanticCache } from "./middleware/builtins/semantic-cache.mjs";
+import { composeMiddleware } from "./middleware/helpers/compose.mjs";
+import { forTool } from "./middleware/helpers/for-tool.mjs";
+import { supervisor } from "./supervisor/supervisor.mjs";
+import { instruction } from "./system-prompt/instruction.mjs";
+import { persona } from "./system-prompt/persona.mjs";
+import { systemPrompt } from "./system-prompt/system-prompt.mjs";
+import { step } from "./workflow/step.mjs";
+import { workflow } from "./workflow/workflow.mjs";
+
+//#region ../../@warlock.js/ai/src/ai.d.ts
+/**
+ * Top-level `ai` namespace — holds built-in factories and user-registered SDK adapters.
+ *
+ * Factories:
+ * - `ai.tool(...)` — wrap an async function with a schema-validated input.
+ * - `ai.agent(...)` — build an executable agent from model + tools + prompt.
+ * - `ai.systemPrompt(...)` — compose a layered persona + instructions prompt.
+ * - `ai.persona(text)` — reusable persona block (can be passed to `systemPrompt`).
+ * - `ai.instruction(text)` — reusable instruction block (can be passed to `systemPrompt`).
+ * - `ai.openai.model(...)` / `ai.anthropic.model(...)` / ... once the adapter SDK is registered.
+ *
+ * @example
+ * const alex = ai.persona("You are Alex, a TypeScript expert.");
+ * const replyIn = ai.instruction("Respond in {{language|English}}.");
+ *
+ * const prompt = ai.systemPrompt().persona(alex).instruction(replyIn);
+ *
+ * const myAgent = ai.agent({
+ *   model: ai.openai.model({ name: "gpt-4o" }),
+ *   systemPrompt: prompt,
+ *   tools: [myTool],
+ * });
+ *
+ * const result = await myAgent.execute("What is the weather in Cairo?", {
+ *   placeholders: { language: "Arabic" },
+ * });
+ */
+declare const ai: {
+  config: typeof setAIConfig;
+  tool: typeof tool;
+  agent: typeof agent;
+  systemPrompt: typeof systemPrompt;
+  persona: typeof persona;
+  instruction: typeof instruction;
+  workflow: typeof workflow;
+  step: typeof step;
+  supervisor: typeof supervisor;
+  middleware: {
+    budget: typeof budget;
+    guardrail: typeof guardrail;
+    semanticCache: typeof semanticCache;
+    compose: typeof composeMiddleware;
+    forTool: typeof forTool;
+  };
+};
+//#endregion
+export { ai };
+//# sourceMappingURL=ai.d.mts.map

package/esm/ai.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai.d.mts","names":[],"sources":["../../../../../@warlock.js/ai/src/ai.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;AAyCA;;;;;;;;;;;;;;;;;;;;;;;cAAa,EAAA"}

package/esm/ai.mjs

@@ -0,0 +1,65 @@
+import { budget } from "./middleware/builtins/budget.mjs";
+import { guardrail } from "./middleware/builtins/guardrail.mjs";
+import { setAIConfig } from "./config.mjs";
+import { semanticCache } from "./middleware/builtins/semantic-cache.mjs";
+import { composeMiddleware } from "./middleware/helpers/compose.mjs";
+import { forTool } from "./middleware/helpers/for-tool.mjs";
+import { agent } from "./agent/agent.mjs";
+import { tool } from "./tool/tool.mjs";
+import { supervisor } from "./supervisor/supervisor.mjs";
+import { instruction } from "./system-prompt/instruction.mjs";
+import { persona } from "./system-prompt/persona.mjs";
+import { systemPrompt } from "./system-prompt/system-prompt.mjs";
+import { step } from "./workflow/step.mjs";
+import { workflow } from "./workflow/workflow.mjs";
+
+//#region ../../@warlock.js/ai/src/ai.ts
+/**
+* Top-level `ai` namespace — holds built-in factories and user-registered SDK adapters.
+*
+* Factories:
+* - `ai.tool(...)` — wrap an async function with a schema-validated input.
+* - `ai.agent(...)` — build an executable agent from model + tools + prompt.
+* - `ai.systemPrompt(...)` — compose a layered persona + instructions prompt.
+* - `ai.persona(text)` — reusable persona block (can be passed to `systemPrompt`).
+* - `ai.instruction(text)` — reusable instruction block (can be passed to `systemPrompt`).
+* - `ai.openai.model(...)` / `ai.anthropic.model(...)` / ... once the adapter SDK is registered.
+*
+* @example
+* const alex = ai.persona("You are Alex, a TypeScript expert.");
+* const replyIn = ai.instruction("Respond in {{language|English}}.");
+*
+* const prompt = ai.systemPrompt().persona(alex).instruction(replyIn);
+*
+* const myAgent = ai.agent({
+*   model: ai.openai.model({ name: "gpt-4o" }),
+*   systemPrompt: prompt,
+*   tools: [myTool],
+* });
+*
+* const result = await myAgent.execute("What is the weather in Cairo?", {
+*   placeholders: { language: "Arabic" },
+* });
+*/
+const ai = {
+	config: setAIConfig,
+	tool,
+	agent,
+	systemPrompt,
+	persona,
+	instruction,
+	workflow,
+	step,
+	supervisor,
+	middleware: {
+		budget,
+		guardrail,
+		semanticCache,
+		compose: composeMiddleware,
+		forTool
+	}
+};
+
+//#endregion
+export { ai };
+//# sourceMappingURL=ai.mjs.map

package/esm/ai.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai.mjs","names":[],"sources":["../../../../../@warlock.js/ai/src/ai.ts"],"sourcesContent":["import { agent } from \"./agent/agent\";\nimport { setAIConfig } from \"./config\";\nimport { budget } from \"./middleware/builtins/budget\";\nimport { guardrail } from \"./middleware/builtins/guardrail\";\nimport { semanticCache } from \"./middleware/builtins/semantic-cache\";\nimport { composeMiddleware, forTool } from \"./middleware/helpers\";\nimport { supervisor } from \"./supervisor/supervisor\";\nimport { instruction } from \"./system-prompt/instruction\";\nimport { persona } from \"./system-prompt/persona\";\nimport { systemPrompt } from \"./system-prompt/system-prompt\";\nimport { tool } from \"./tool/tool\";\nimport { step } from \"./workflow/step\";\nimport { workflow } from \"./workflow/workflow\";\n\n/**\n * Top-level `ai` namespace — holds built-in factories and user-registered SDK adapters.\n *\n * Factories:\n * - `ai.tool(...)` — wrap an async function with a schema-validated input.\n * - `ai.agent(...)` — build an executable agent from model + tools + prompt.\n * - `ai.systemPrompt(...)` — compose a layered persona + instructions prompt.\n * - `ai.persona(text)` — reusable persona block (can be passed to `systemPrompt`).\n * - `ai.instruction(text)` — reusable instruction block (can be passed to `systemPrompt`).\n * - `ai.openai.model(...)` / `ai.anthropic.model(...)` / ... once the adapter SDK is registered.\n *\n * @example\n * const alex = ai.persona(\"You are Alex, a TypeScript expert.\");\n * const replyIn = ai.instruction(\"Respond in {{language|English}}.\");\n *\n * const prompt = ai.systemPrompt().persona(alex).instruction(replyIn);\n *\n * const myAgent = ai.agent({\n *   model: ai.openai.model({ name: \"gpt-4o\" }),\n *   systemPrompt: prompt,\n *   tools: [myTool],\n * });\n *\n * const result = await myAgent.execute(\"What is the weather in Cairo?\", {\n *   placeholders: { language: \"Arabic\" },\n * });\n */\nexport const ai = {\n  config: setAIConfig,\n  tool,\n  agent,\n  systemPrompt,\n  persona,\n  instruction,\n  workflow,\n  step,\n  supervisor,\n  middleware: {\n    budget,\n    guardrail,\n    semanticCache,\n    compose: composeMiddleware,\n    forTool,\n  },\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCA,MAAa,KAAK;CAChB,QAAQ;CACR;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA,YAAY;EACV;EACA;EACA;EACA,SAAS;EACT;CACF;AACF"}

package/esm/config.d.mts

@@ -0,0 +1,79 @@
+import { CacheDriver } from "@warlock.js/cache";
+
+//#region ../../@warlock.js/ai/src/config.d.ts
+/**
+ * Process-wide `@warlock.js/ai` configuration. **Intentionally tiny.**
+ * Lives here only for genuinely cross-cutting defaults that would
+ * otherwise force users to wire the same value into every consumer.
+ *
+ * **What lives here.** A field earns a slot only when it satisfies
+ * all three:
+ * 1. Multiple unrelated consumers need the same value.
+ * 2. The value is infrastructure (drivers, clients, pools), not
+ *    behavior (kill-switches, mode flags).
+ * 3. Per-call override doesn't make sense for the use case.
+ *
+ * **What does NOT live here.** Logger config (use
+ * `@warlock.js/logger` directly). Per-primitive feature flags
+ * (live on the relevant config type). Anything that's really one
+ * consumer's concern (lives on that consumer).
+ *
+ * Phase 3.2 deliberately removed the previous `configureAI()` bag
+ * because it was growing unbounded. Treat new fields here with the
+ * same suspicion.
+ */
+type AIConfig = {
+  /**
+   * Default store used by every consumer that supports persistence
+   * but didn't supply its own `store` / `snapshotStore`. Most
+   * realistic deployments back resume snapshots, semantic cache, and
+   * future memory primitives with the same driver — declaring it
+   * once here removes the repetition.
+   *
+   * Per-declaration overrides (`SupervisorConfig.snapshotStore`,
+   * `semanticCache({ store })`) win when supplied. Set this once at
+   * app boot, *after* you've constructed your driver.
+   *
+   * @example
+   * import { cache } from "@warlock.js/cache";
+   * import { ai } from "@warlock.js/ai";
+   *
+   * ai.config({
+   *   defaultStore: cache.driver("redis", { client: redisClient }),
+   * });
+   */
+  defaultStore?: CacheDriver<any, any>;
+};
+/**
+ * Set or extend process-wide AI configuration. Merges over existing
+ * values — fields not present in `partial` keep whatever was set
+ * before (or stay unset). Call once at app boot, before constructing
+ * any agent / supervisor / middleware that should pick up the
+ * defaults.
+ *
+ * Returns the merged config so callers can verify what landed.
+ *
+ * @example
+ * import { cache } from "@warlock.js/cache";
+ * import { ai } from "@warlock.js/ai";
+ *
+ * ai.config({ defaultStore: cache.driver("redis", { client }) });
+ */
+declare function setAIConfig(partial: Partial<AIConfig>): AIConfig;
+/**
+ * Read the current AI config snapshot. Returns a shallow copy so
+ * callers can't accidentally mutate the source of truth. Used
+ * internally by consumers to resolve their `defaultStore` fallback.
+ */
+declare function getAIConfig(): AIConfig;
+/**
+ * Resolve the effective store for a consumer that didn't receive an
+ * explicit one. Returns the global `defaultStore` if set, otherwise
+ * `undefined`. Consumers decide whether `undefined` is fatal (semantic
+ * cache: yes, throws) or a no-op (snapshot persistence: yes, just
+ * skips).
+ */
+declare function resolveDefaultStore(): CacheDriver<any, any> | undefined;
+//#endregion
+export { AIConfig, getAIConfig, resolveDefaultStore, setAIConfig };
+//# sourceMappingURL=config.d.mts.map

package/esm/config.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.mts","names":[],"sources":["../../../../../@warlock.js/ai/src/config.ts"],"mappings":";;;;;AAuBA;;;;AAoB4B;AAoB5B;;;;;;;;;;;;;AAAiE;KAxCrD,QAAA;EAkDe;;;AAAY;AAWvC;;;;AAAkD;;;;;;;;;;;EAzChD,YAAA,GAAe,WAAW;AAAA;;;;;;;;;;;;;;;;iBAoBZ,WAAA,CAAY,OAAA,EAAS,OAAA,CAAQ,QAAA,IAAY,QAAA;;;;;;iBAUzC,WAAA,CAAA,GAAe,QAAQ;;;;;;;;iBAWvB,mBAAA,CAAA,GAAuB,WAAW"}

package/esm/config.mjs

@@ -0,0 +1,43 @@
+//#region ../../@warlock.js/ai/src/config.ts
+const aiConfig = {};
+/**
+* Set or extend process-wide AI configuration. Merges over existing
+* values — fields not present in `partial` keep whatever was set
+* before (or stay unset). Call once at app boot, before constructing
+* any agent / supervisor / middleware that should pick up the
+* defaults.
+*
+* Returns the merged config so callers can verify what landed.
+*
+* @example
+* import { cache } from "@warlock.js/cache";
+* import { ai } from "@warlock.js/ai";
+*
+* ai.config({ defaultStore: cache.driver("redis", { client }) });
+*/
+function setAIConfig(partial) {
+	Object.assign(aiConfig, partial);
+	return { ...aiConfig };
+}
+/**
+* Read the current AI config snapshot. Returns a shallow copy so
+* callers can't accidentally mutate the source of truth. Used
+* internally by consumers to resolve their `defaultStore` fallback.
+*/
+function getAIConfig() {
+	return { ...aiConfig };
+}
+/**
+* Resolve the effective store for a consumer that didn't receive an
+* explicit one. Returns the global `defaultStore` if set, otherwise
+* `undefined`. Consumers decide whether `undefined` is fatal (semantic
+* cache: yes, throws) or a no-op (snapshot persistence: yes, just
+* skips).
+*/
+function resolveDefaultStore() {
+	return aiConfig.defaultStore;
+}
+
+//#endregion
+export { getAIConfig, resolveDefaultStore, setAIConfig };
+//# sourceMappingURL=config.mjs.map

package/esm/config.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.mjs","names":[],"sources":["../../../../../@warlock.js/ai/src/config.ts"],"sourcesContent":["import type { CacheDriver } from \"@warlock.js/cache\";\n\n/**\n * Process-wide `@warlock.js/ai` configuration. **Intentionally tiny.**\n * Lives here only for genuinely cross-cutting defaults that would\n * otherwise force users to wire the same value into every consumer.\n *\n * **What lives here.** A field earns a slot only when it satisfies\n * all three:\n * 1. Multiple unrelated consumers need the same value.\n * 2. The value is infrastructure (drivers, clients, pools), not\n *    behavior (kill-switches, mode flags).\n * 3. Per-call override doesn't make sense for the use case.\n *\n * **What does NOT live here.** Logger config (use\n * `@warlock.js/logger` directly). Per-primitive feature flags\n * (live on the relevant config type). Anything that's really one\n * consumer's concern (lives on that consumer).\n *\n * Phase 3.2 deliberately removed the previous `configureAI()` bag\n * because it was growing unbounded. Treat new fields here with the\n * same suspicion.\n */\nexport type AIConfig = {\n  /**\n   * Default store used by every consumer that supports persistence\n   * but didn't supply its own `store` / `snapshotStore`. Most\n   * realistic deployments back resume snapshots, semantic cache, and\n   * future memory primitives with the same driver — declaring it\n   * once here removes the repetition.\n   *\n   * Per-declaration overrides (`SupervisorConfig.snapshotStore`,\n   * `semanticCache({ store })`) win when supplied. Set this once at\n   * app boot, *after* you've constructed your driver.\n   *\n   * @example\n   * import { cache } from \"@warlock.js/cache\";\n   * import { ai } from \"@warlock.js/ai\";\n   *\n   * ai.config({\n   *   defaultStore: cache.driver(\"redis\", { client: redisClient }),\n   * });\n   */\n  defaultStore?: CacheDriver<any, any>;\n};\n\nconst aiConfig: AIConfig = {};\n\n/**\n * Set or extend process-wide AI configuration. Merges over existing\n * values — fields not present in `partial` keep whatever was set\n * before (or stay unset). Call once at app boot, before constructing\n * any agent / supervisor / middleware that should pick up the\n * defaults.\n *\n * Returns the merged config so callers can verify what landed.\n *\n * @example\n * import { cache } from \"@warlock.js/cache\";\n * import { ai } from \"@warlock.js/ai\";\n *\n * ai.config({ defaultStore: cache.driver(\"redis\", { client }) });\n */\nexport function setAIConfig(partial: Partial<AIConfig>): AIConfig {\n  Object.assign(aiConfig, partial);\n  return { ...aiConfig };\n}\n\n/**\n * Read the current AI config snapshot. Returns a shallow copy so\n * callers can't accidentally mutate the source of truth. Used\n * internally by consumers to resolve their `defaultStore` fallback.\n */\nexport function getAIConfig(): AIConfig {\n  return { ...aiConfig };\n}\n\n/**\n * Resolve the effective store for a consumer that didn't receive an\n * explicit one. Returns the global `defaultStore` if set, otherwise\n * `undefined`. Consumers decide whether `undefined` is fatal (semantic\n * cache: yes, throws) or a no-op (snapshot persistence: yes, just\n * skips).\n */\nexport function resolveDefaultStore(): CacheDriver<any, any> | undefined {\n  return aiConfig.defaultStore;\n}\n"],"mappings":";AA8CA,MAAM,WAAqB,CAAC;;;;;;;;;;;;;;;;AAiB5B,SAAgB,YAAY,SAAsC;CAChE,OAAO,OAAO,UAAU,OAAO;CAC/B,OAAO,EAAE,GAAG,SAAS;AACvB;;;;;;AAOA,SAAgB,cAAwB;CACtC,OAAO,EAAE,GAAG,SAAS;AACvB;;;;;;;;AASA,SAAgB,sBAAyD;CACvE,OAAO,SAAS;AAClB"}

package/esm/contracts/agent/agent-options.type.d.mts

@@ -0,0 +1,132 @@
+import { Attachment } from "../attachment.type.mjs";
+import { Message } from "../conversation-message.type.mjs";
+import { ToolContext } from "../tool.contract.mjs";
+import { Placeholders } from "../placeholders.type.mjs";
+import { SystemPromptContract } from "../system-prompt.contract.mjs";
+import { AgentEventMap } from "../events/event-map.type.mjs";
+import { StreamingToolGuardConfig } from "../streaming-tool-guard-config.type.mjs";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#region ../../@warlock.js/ai/src/contracts/agent/agent-options.type.d.ts
+/**
+ * Options passed to AgentContract.execute() to configure a single execution run.
+ *
+ * @example
+ * const result = await agent.execute("Analyze this document", {
+ *   history: previousMessages,
+ *   attachments: ["/path/to/doc.pdf"],
+ *   placeholders: { language: "English" },
+ *   output: z.object({ summary: z.string(), keyPoints: z.array(z.string()) }),
+ *   on: {
+ *     streaming: ({ delta }) => process.stdout.write(delta),
+ *     completed: ({ result }) => console.log("Done"),
+ *   },
+ * });
+ */
+type AgentExecuteOptions<TOutput = unknown> = {
+  /** Prior conversation messages to prepend as context */history?: Message[]; /** Files or URLs to attach to the message */
+  attachments?: Attachment[]; /** Values to inject into {{mustache}} placeholders in prompts */
+  placeholders?: Placeholders;
+  /**
+   * Standard Schema for structured output extraction.
+   * When provided, the agent will attempt to return typed data in result.data.
+   */
+  output?: StandardSchemaV1<TOutput>;
+  /**
+   * Hand-crafted JSON Schema used to drive native structured-output mode
+   * (OpenAI `response_format: json_schema`, etc.) and to embed in the
+   * soft system-prompt instruction.
+   *
+   * Primary use case: libraries whose JSON Schema output isn't
+   * automatically extractable by `extractJsonSchema` — notably Zod,
+   * which ships `z.toJSONSchema` as a top-level module function rather
+   * than a property on the schema. Pass the converter's output here and
+   * the agent will use it verbatim, skipping extraction.
+   *
+   * When both `output` and `responseSchema` are set, `responseSchema`
+   * wins — `output` still runs for client-side validation into
+   * `result.data`, but the wire-level schema sent to the model is
+   * whatever was passed here.
+   *
+   * @example
+   * import { z, toJSONSchema } from "zod";
+   * const schema = z.object({ summary: z.string() });
+   * await agent.execute(input, {
+   *   output: schema,
+   *   responseSchema: toJSONSchema(schema),
+   * });
+   */
+  responseSchema?: Record<string, unknown>;
+  /**
+   * Opt-in self-repair when the model's response fails to parse or
+   * validate against `output`. When enabled, the agent appends the bad
+   * assistant message plus a corrective user message to the conversation
+   * and re-invokes the model up to `maxAttempts` times, re-parsing on
+   * each attempt. Disabled by default — schema failures normally surface
+   * a real prompt/model issue worth seeing rather than silently retrying.
+   *
+   * Each repair attempt counts as a normal trip and is bounded by the
+   * agent's `maxTrips` cap (belt-and-suspenders against runaway loops).
+   *
+   * Only active when `output` (or `responseSchema`) is set; ignored
+   * otherwise.
+   *
+   * @example
+   * await agent.execute(input, {
+   *   output: schema,
+   *   repair: { maxAttempts: 1 },
+   * });
+   */
+  repair?: {
+    /** Max number of re-ask attempts after the initial failure. Default 1. */maxAttempts?: number;
+  }; /** Override the agent's system prompt for this execution */
+  systemPrompt?: SystemPromptContract;
+  /**
+   * Cancellation handle. When `signal.aborted` becomes true the agent
+   * short-circuits at the next trip boundary and returns with
+   * `report.status = "cancelled"` + `result.error` set to an
+   * `AgentExecutionError` carrying the abort reason. Mid-trip abort
+   * is best-effort — it relies on the underlying provider adapter
+   * threading `signal` into its HTTP client. The workflow engine
+   * passes its own signal through automatically when a step has an
+   * `agent`.
+   */
+  signal?: AbortSignal; /** Event handlers for observing execution progress */
+  on?: Partial<{ [K in keyof AgentEventMap]: (payload: AgentEventMap[K]) => void }>;
+  /**
+   * Tool context threaded into every `tool.invoke()` call this agent
+   * runs (Phase 5 / decisions §35). Tools mutate `ctx.artifacts` to
+   * contribute system-only side data; the supervisor that supplied
+   * the ctx merges that bag into state at iteration end.
+   *
+   * Typically set by the supervisor's dispatch loop, not by user
+   * code. Standalone callers may omit it — the framework supplies a
+   * degraded `{ artifacts: {} }` so single-arg legacy tools keep
+   * working unchanged.
+   */
+  toolCtx?: ToolContext;
+  /**
+   * Per-call override for the stream-time tool-call guard. Wins over
+   * `AgentConfig.streamingToolGuard` when set. Pass `undefined` to
+   * disable for a single call when the agent-level config has the
+   * guard enabled (e.g. a one-off "give me a raw JSON config" call
+   * where the buffering delay isn't worth it).
+   */
+  streamingToolGuard?: StreamingToolGuardConfig;
+  /**
+   * Opaque caller-supplied identifier that groups multiple `execute()`
+   * calls into one conceptual user session / request. Mirrored onto
+   * every report node this run produces (and every nested executable
+   * it invokes via `asTool` wrappers) so flat queries like "total
+   * spend for user X this morning" don't need to walk the tree.
+   *
+   * Auto-propagated to composite primitives — an inner supervisor
+   * dispatched via `asTool` inherits the outer agent's `sessionId`.
+   * Execution state (artifacts, snapshots) stays isolated; only the
+   * observability identity is shared.
+   */
+  sessionId?: string;
+};
+//#endregion
+export { AgentExecuteOptions };
+//# sourceMappingURL=agent-options.type.d.mts.map

package/esm/contracts/agent/agent-options.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-options.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/agent/agent-options.type.ts"],"mappings":";;;;;;;;;;;;AAwBA;;;;;;;;;;;;;KAAY,mBAAA;EA2EL,wDAzEL,OAAA,GAAU,OAAA,IA+FW;EA7FrB,WAAA,GAAc,UAAA,IA6F+B;EA3F7C,YAAA,GAAe,YAAA;EAJf;;;;EASA,MAAA,GAAS,gBAAA,CAAiB,OAAA;EALX;;;;;;;;;;;;;;;;;;;;;;;;EA8Bf,cAAA,GAAiB,MAAA;EA0ER;;;;;;;;;;;;;;;;;;;;EArDT,MAAA;8EAEE,WAAA;EAAA;EAGF,YAAA,GAAe,oBAAA;;;;;;;;;;;EAWf,MAAA,GAAS,WAAA;EAET,EAAA,GAAK,OAAA,eACS,aAAA,IAAiB,OAAA,EAAS,aAAA,CAAc,CAAA;;;;;;;;;;;;EAatD,OAAA,GAAU,WAAA;;;;;;;;EAQV,kBAAA,GAAqB,wBAAA;;;;;;;;;;;;;EAarB,SAAA;AAAA"}

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

@@ -0,0 +1,92 @@
+import { AgentResult } from "../result/agent-result.type.mjs";
+import { ExecutableContract } from "../executable.contract.mjs";
+import { StreamContract } from "../stream/stream.contract.mjs";
+import { AgentEventMap } from "../events/event-map.type.mjs";
+import { AgentExecuteOptions } from "./agent-options.type.mjs";
+
+//#region ../../@warlock.js/ai/src/contracts/agent/agent.contract.d.ts
+/**
+ * Handler function for a single agent event. Takes the event's typed
+ * payload; return value is ignored.
+ */
+type AgentEventHandler<K extends keyof AgentEventMap> = (payload: AgentEventMap[K]) => void;
+/**
+ * Contract for an AI agent — the core executable primitive.
+ *
+ * Supports a 3-tier event subscription model. All three layers fire in
+ * order on every event: **factory → instance → per-call**. A listener
+ * at any level can inspect the same event without the others needing
+ * to know.
+ *
+ * - **Factory-level** — `ai.agent({ on: {...} })`. Fires on every run.
+ * - **Instance-level** — `agent.on(event, handler)` / `agent.off(...)`.
+ *   Imperative additions that persist across every `execute()`/`stream()`
+ *   call on this instance. `on()` returns an unsubscribe function.
+ * - **Per-call** — `agent.execute(input, { on: {...} })` or
+ *   `agent.stream(input, { on: {...} })`. Scoped to that one run.
+ *
+ * @example
+ * const myAgent = ai.agent({
+ *   model,
+ *   on: { "agent.starting": () => metrics.inc("agent.runs") },
+ * });
+ *
+ * const unsubscribe = myAgent.on("agent.error", ({ error }) => logger.error(error));
+ *
+ * const result = await myAgent.execute("Summarize this", {
+ *   output: z.object({ summary: z.string() }),
+ *   on: { "agent.trip.completed": ({ trip }) => console.log(trip.duration) },
+ * });
+ *
+ * unsubscribe();
+ *
+ * @example
+ * // Stream tokens as they arrive
+ * const stream = myAgent.stream("Write a poem");
+ * for await (const event of stream) {
+ *   if (event.type === "agent.trip.streaming") process.stdout.write(event.delta);
+ * }
+ * const result = await stream.result;
+ */
+interface AgentContract<TOutput = unknown> extends ExecutableContract<string, AgentExecuteOptions<TOutput>, AgentResult<TOutput>> {
+  /**
+   * Stable identifier for this agent. Always populated — if the
+   * factory caller omitted `name`, a deterministic
+   * `anon_<provider>_<model>[_<tool>+...]` fingerprint is synthesized
+   * (same config → same name across restarts). Consumers that require
+   * a *meaningful* name (workflow step, tool wrapper) should
+   * additionally check `isAnonymous`.
+   */
+  readonly name: string;
+  /**
+   * `true` when the agent was constructed without an explicit name.
+   * Workflow / tool boundaries reject anonymous agents at author time
+   * so signature drift detection and tool routing stay honest.
+   */
+  readonly isAnonymous: boolean;
+  /**
+   * Optional short summary — surfaced to supervisor router prompts and
+   * to `asTool()` wrappers. Mirrors whatever was set on
+   * `AgentConfig.description` at factory time.
+   */
+  readonly description?: string;
+  /**
+   * Stream execution events in real time.
+   * Yields typed StreamEvent values and resolves result when done.
+   */
+  stream(input: string, options?: AgentExecuteOptions<TOutput>): StreamContract<AgentResult<TOutput>>;
+  /**
+   * Subscribe a handler to a single event name for the lifetime of
+   * this agent instance. Returns an unsubscribe function; calling it
+   * is equivalent to `off(event, handler)`.
+   */
+  on<K extends keyof AgentEventMap>(event: K, handler: AgentEventHandler<K>): () => void;
+  /**
+   * Remove a previously-subscribed handler. No-op when the handler was
+   * never registered or was already removed.
+   */
+  off<K extends keyof AgentEventMap>(event: K, handler: AgentEventHandler<K>): void;
+}
+//#endregion
+export { AgentContract, AgentEventHandler };
+//# sourceMappingURL=agent.contract.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent.contract.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/agent/agent.contract.ts"],"mappings":";;;;;;;;;AAUA;;KAAY,iBAAA,iBAAkC,aAAA,KAC5C,OAAA,EAAS,aAAA,CAAc,CAAA;;;;;;;;;;;;AAAE;AAyC3B;;;;;;;;;;;;;;;;;;;;;;;;;;UAAiB,aAAA,4BAAyC,kBAAA,SAExD,mBAAA,CAAoB,OAAA,GACpB,WAAA,CAAY,OAAA;EAAZ;;;;;;;;EAAA,SAUS,IAAA;EAmBP;;;;;EAAA,SAbO,WAAA;EAqBU;;;;;EAAA,SAfV,WAAA;EAwBT;;;;EAnBA,MAAA,CACE,KAAA,UACA,OAAA,GAAU,mBAAA,CAAoB,OAAA,IAC7B,cAAA,CAAe,WAAA,CAAY,OAAA;EAkBnB;;;;AAAoB;EAX/B,EAAA,iBAAmB,aAAA,EACjB,KAAA,EAAO,CAAA,EACP,OAAA,EAAS,iBAAA,CAAkB,CAAA;;;;;EAO7B,GAAA,iBAAoB,aAAA,EAClB,KAAA,EAAO,CAAA,EACP,OAAA,EAAS,iBAAA,CAAkB,CAAA;AAAA"}

package/esm/contracts/agent/index.d.mts

@@ -0,0 +1,2 @@
+import { AgentContract, AgentEventHandler } from "./agent.contract.mjs";
+import { AgentExecuteOptions } from "./agent-options.type.mjs";

package/esm/contracts/attachment.type.d.mts

@@ -0,0 +1,100 @@
+//#region ../../@warlock.js/ai/src/contracts/attachment.type.d.ts
+/**
+ * Shape of a StorageFile object from @warlock.js/core.
+ * Used to detect storage files in the Attachment union.
+ *
+ * @example
+ * const file: StorageFileShape = {
+ *   url: "https://cdn.example.com/uploads/doc.pdf",
+ *   absolutePath: "/var/www/uploads/doc.pdf",
+ * };
+ */
+type StorageFileShape = {
+  /** Public URL of the file */url?: string; /** Absolute filesystem path to the file */
+  absolutePath?: string;
+};
+/**
+ * Where the bytes of an attachment originate. The agent's
+ * `prepareAttachmentPart` collapses every variant into a `ContentPart`
+ * the model adapter can consume.
+ *
+ * - `string` — local file path or remote URL (auto-detected via the
+ *   `https?://` prefix).
+ * - `StorageFileShape` — a `@warlock.js/core` storage file; URL wins
+ *   over path when both are present.
+ * - `{ base64, mediaType }` — raw inline bytes with an explicit IANA
+ *   media type, useful for in-memory data that never touched disk.
+ */
+type AttachmentSource = string | StorageFileShape | {
+  base64: string;
+  mediaType: string;
+};
+/**
+ * An attachment that can be passed to an agent execution.
+ *
+ * Two forms:
+ *
+ * - **Tagged form** (preferred for non-image types and for explicit
+ *   intent): `{ type: "image" | "text", source }`.
+ * - **Shorthand string / StorageFileShape**: the agent infers the
+ *   media kind from the file extension. Recognized image extensions:
+ *   `.png`, `.jpg`, `.jpeg`, `.webp`, `.gif`. Recognized text
+ *   extension: `.txt`. Anything else throws — silent inference for
+ *   ambiguous inputs causes silent bugs.
+ *
+ * @example
+ * // Shorthand — extension-inferred image
+ * agent.execute("What's in this?", { attachments: ["./photo.png"] });
+ *
+ * @example
+ * // Tagged form — explicit kind
+ * agent.execute("Compare", {
+ *   attachments: [
+ *     { type: "image", source: "https://cdn.example.com/a.jpg" },
+ *     { type: "image", source: { base64: "iVBOR...", mediaType: "image/png" } },
+ *   ],
+ * });
+ *
+ * @example
+ * // Text attachment — contents are read and injected as extra text
+ * agent.execute("Summarize", { attachments: [{ type: "text", source: "./notes.txt" }] });
+ *
+ * @example
+ * // StorageFileShape from @warlock.js/core (extension-inferred)
+ * agent.execute("Describe", { attachments: [storageFile] });
+ */
+type Attachment = string | StorageFileShape | {
+  type: "image";
+  source: AttachmentSource;
+} | {
+  type: "text";
+  source: AttachmentSource;
+};
+/**
+ * A normalized attachment after source resolution — a tagged value the
+ * agent can hand to file-reading code without re-discriminating the
+ * input variant.
+ *
+ * @example
+ * const resolved: ResolvedAttachment = { type: "url", value: "https://..." };
+ * const resolved2: ResolvedAttachment = { type: "path", value: "/tmp/doc.pdf" };
+ * const resolved3: ResolvedAttachment = {
+ *   type: "base64",
+ *   value: "iVBORw0...",
+ *   mediaType: "image/png",
+ * };
+ */
+type ResolvedAttachment = {
+  type: "url";
+  value: string;
+} | {
+  type: "path";
+  value: string;
+} | {
+  type: "base64";
+  value: string;
+  mediaType: string;
+};
+//#endregion
+export { Attachment, AttachmentSource, ResolvedAttachment, StorageFileShape };
+//# sourceMappingURL=attachment.type.d.mts.map

package/esm/contracts/attachment.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment.type.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/contracts/attachment.type.ts"],"mappings":";;AAUA;;;;AAIc;AAed;;;;KAnBY,gBAAA;EAsBN,6BApBJ,GAAA,WAoB6B;EAlB7B,YAAY;AAAA;;;;;;;;;;;;;KAeF,gBAAA,YAER,gBAAgB;EACd,MAAA;EAAgB,SAAA;AAAA;AAwDtB;;;;;;;;;;;;AAG8C;;;;;;;;;;;;;;;;;;;;;;AAH9C,KApBY,UAAA,YAER,gBAAA;EACE,IAAA;EAAe,MAAA,EAAQ,gBAAA;AAAA;EACvB,IAAA;EAAc,MAAA,EAAQ,gBAAA;AAAA;;;;;;;;;;;;;;;KAgBhB,kBAAA;EACN,IAAA;EAAa,KAAA;AAAA;EACb,IAAA;EAAc,KAAA;AAAA;EACd,IAAA;EAAgB,KAAA;EAAe,SAAA;AAAA"}