@warlock.js/ai 4.1.1

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

@@ -0,0 +1,160 @@
+import { ToolContract } from "../tool/tool.mjs";
+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 { ModelCallOptions, ModelContract } from "../contracts/model.contract.mjs";
+import { AgentMiddleware } from "../contracts/middleware/middleware.contract.mjs";
+import { CompleteEvent } from "../contracts/events/complete-event.type.mjs";
+import { UsageEvent } from "../contracts/events/usage-event.type.mjs";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#region ../../@warlock.js/ai/src/agent/agent-config.type.d.ts
+/**
+ * Map of factory-level event handlers. Every key is optional; handlers
+ * registered here fire on every `execute()` / `stream()` call made
+ * through this agent, before instance-level and per-call handlers.
+ */
+type AgentEventHandlers = Partial<{ [K in keyof AgentEventMap]: (payload: AgentEventMap[K]) => void }>;
+/**
+ * Configuration passed to `agent()` to create an AgentContract instance.
+ *
+ * @example
+ * const config: AgentConfig<{ answer: string }> = {
+ *   model: openai.model({ name: "gpt-4o" }),
+ *   systemPrompt: "You are a helpful assistant.",
+ *   tools: [searchTool, calculatorTool],
+ *   placeholders: { language: "English" },
+ *   maxTrips: 5,
+ *   modelOptions: { temperature: 0.2 },
+ * };
+ *
+ * @example
+ * // With a SystemPromptContract instance
+ * const config: AgentConfig = {
+ *   model: myModel,
+ *   systemPrompt: systemPrompt
+ *     .persona("You are Alex, a TypeScript expert")
+ *     .instruction("Always respond in {{language|English}}"),
+ *   placeholders: { language: "Arabic" },
+ * };
+ */
+type AgentConfig<TOutput = unknown> = {
+  /**
+   * Stable identifier for this agent. Optional — when absent, the
+   * factory synthesizes a deterministic anonymous fingerprint
+   * (`anon_<provider>_<model>[_<tool>+...]`) used for logs and trace
+   * attribution.
+   *
+   * **Required at real boundaries:** boundaries that depend on *stable*
+   * agent identity (workflow signature drift detection when used as a
+   * step's `agent`, `agent.asTool()` wrapper) throw `WorkflowError` /
+   * `ToolError` if the agent is still anonymous. Pass a name whenever
+   * the agent will be composed into a higher-level primitive.
+   */
+  name?: string;
+  /**
+   * Short natural-language summary of what this agent does — the "when
+   * would a router pick this?" line. Used by `ai.supervisor()`'s router
+   * prompt and by `agent.asTool()` as the default tool description.
+   * Optional at the agent level; entries in a supervisor's `agents` map
+   * may override it per-use.
+   */
+  description?: string;
+  /**
+   * Dev-curated version string for this agent — free-form (semver,
+   * date, hash, anything). Stored on every report node this agent
+   * produces so trip-archive consumers can distinguish runs of "agent
+   * X v2.1" from "agent X v2.2" even when name + signature are
+   * identical.
+   *
+   * Bump when you change behavior in a way that matters to stored
+   * reports — prompt rewrite, model swap, tool list change. The
+   * framework neither parses nor compares it; signature drift
+   * detection remains independent.
+   */
+  version?: string; /** The model to use for LLM calls */
+  model: ModelContract;
+  /**
+   * System prompt for the agent. A plain string is treated as a single instruction.
+   * A SystemPromptContract gives full builder control with placeholder support.
+   */
+  systemPrompt?: SystemPromptContract | string; /** Tools exposed to the LLM during execution */
+  tools?: ToolContract<any, any>[]; /** Placeholder values merged into system prompt templates */
+  placeholders?: Placeholders;
+  /**
+   * Maximum number of LLM trips before aborting with an error.
+   * Prevents infinite tool-call loops. Defaults to 10.
+   */
+  maxTrips?: number; /** Base model call options merged with per-execute options (execute wins on conflict) */
+  modelOptions?: ModelCallOptions;
+  /**
+   * Default Standard Schema for structured output. Bakes the output
+   * contract into the agent's identity for agents whose shape never
+   * varies per call (title generators, intent classifiers, routers).
+   * `execute()` / `stream()` callers can still pass `options.output`
+   * to override for a single run — call-site fully replaces this,
+   * no merging.
+   */
+  output?: StandardSchemaV1<TOutput>;
+  /**
+   * Factory-level event handlers. Fire before instance-level `.on()`
+   * additions and before per-call `options.on` handlers on every
+   * `execute()` / `stream()` call.
+   */
+  on?: AgentEventHandlers;
+  /**
+   * Agent-level middleware pipeline. Each middleware may hook any
+   * subset of three levels: `execute` (wraps the whole run), `trip`
+   * (wraps each LLM round-trip), `tool` (wraps each tool dispatch).
+   *
+   * Registration order is execution order — `before` hooks run
+   * top-down, `after` / `onError` run bottom-up (onion model).
+   * Canonical install order: `[cache, budget, guardrail, observability]`.
+   *
+   * See `AgentMiddleware` for the full contract.
+   */
+  middleware?: AgentMiddleware[];
+  /**
+   * Opt-in stream-time guard that recovers a tool call when the model
+   * emits its structured input as **text** in the content channel
+   * instead of as a structured tool-call. Off when absent (faithful
+   * relay); `{}` enables it with defaults. Per-call
+   * `AgentExecuteOptions.streamingToolGuard` overrides this on a single
+   * `execute()` / `stream()` call. See {@link StreamingToolGuardConfig}
+   * for the full contract — limitations, latency tradeoff, matcher
+   * tier.
+   */
+  streamingToolGuard?: StreamingToolGuardConfig;
+  /**
+   * Per-trip usage callback. Fires once after every LLM round-trip
+   * (initial trip, continuation trips after tool results, repair
+   * trips) with a flat `{ runId, tripIndex, model, provider, usage,
+   * timestamp }` payload — pre-packaged so cost-ledger code can write
+   * one row per trip without joining identity from elsewhere.
+   *
+   * Sync or async. Errors thrown inside the hook are swallowed so
+   * consumer bugs cannot crash the agent loop.
+   *
+   * Distinct from the existing `agent.trip.completed` event — that
+   * event still fires for general subscribers; `onUsage` is the
+   * dedicated cost-attribution surface.
+   */
+  onUsage?: (event: UsageEvent) => void | Promise<void>;
+  /**
+   * Per-execution completion callback. Fires once at the end of every
+   * `agent.execute()` / `agent.stream()` call — completed, failed,
+   * cancelled. Receives the full `AgentResult` plus pre-extracted
+   * `runId` and end-to-end `durationMs`. Audit-log code subscribes
+   * here to write one `ai_runs` row per execution with the (redacted)
+   * report.
+   *
+   * Sync or async. Errors thrown inside the hook are swallowed.
+   *
+   * Distinct from the existing `agent.completed` event — both fire.
+   */
+  onComplete?: (event: CompleteEvent<TOutput>) => void | Promise<void>;
+};
+//#endregion
+export { AgentConfig };
+//# sourceMappingURL=agent-config.type.d.mts.map

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

@@ -0,0 +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;EA0FW;;;;;;;;;;;;EA7ErB,IAAA;EAuBO;;;;;;;EAfP,WAAA;EA+BA;;;;;;;;;;;;EAlBA,OAAA,WAuEW;EArEX,KAAA,EAAO,aAAA;EAkFP;;;;EA7EA,YAAA,GAAe,oBAAA,WA6E+C;EA3E9D,KAAA,GAAQ,YAAA;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"}

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

@@ -0,0 +1,111 @@
+import { InvalidRequestError } from "../errors/invalid-request-error.mjs";
+import "../errors/index.mjs";
+import { extractJsonSchema } from "../utils/json-schema.mjs";
+import { prepareAttachmentPart } from "../utils/prepare-attachment-part.mjs";
+import "../utils/index.mjs";
+
+//#region ../../@warlock.js/ai/src/agent/agent-input-builder.ts
+/**
+* Assemble the seed conversation for an agent execution. Runs exactly
+* once per run — subsequent trips append to the same message list.
+*
+* Responsibilities (previously three methods on `Execution`):
+* 1. Merge factory + per-call placeholders.
+* 2. Resolve the system prompt (string, contract, or absent).
+* 3. When an output schema is supplied:
+*    - cache its JSON Schema form for `ModelCallOptions.responseSchema`
+*      so native-structured-output providers enforce it at the token
+*      level;
+*    - fall back to a soft system-prompt instruction for providers
+*      that don't advertise `structuredOutput` capability.
+* 4. Append caller-supplied `history` (e.g. session-level prior turns).
+* 5. Shape the user message — plain string in the common case,
+*    multipart `ContentPart[]` when `attachments` are present. Image
+*    attachments require model vision capability; mismatch throws
+*    `InvalidRequestError` here rather than failing opaquely at the
+*    provider.
+*
+* Extracted from the `Execution` class to isolate the declarative
+* input-shaping phase from the stateful trip loop.
+*/
+async function buildAgentInputMessages(params) {
+	const { config, input, options } = params;
+	const placeholders = {
+		...config.placeholders,
+		...options?.placeholders
+	};
+	const systemPrompt = options?.systemPrompt ?? config.systemPrompt;
+	let systemContent = "";
+	if (typeof systemPrompt === "string") systemContent = systemPrompt;
+	else if (systemPrompt) systemContent = systemPrompt.resolve(placeholders);
+	const { responseSchema, instruction } = resolveStructuredOutput({
+		outputSchema: options?.output ?? config.output,
+		overrideResponseSchema: options?.responseSchema,
+		modelSupportsStructuredOutput: Boolean(config.model.capabilities?.structuredOutput)
+	});
+	if (instruction) systemContent = systemContent ? `${systemContent}\n\n${instruction}` : instruction;
+	const messages = [];
+	if (systemContent) messages.push({
+		role: "system",
+		content: systemContent
+	});
+	if (options?.history) messages.push(...options.history);
+	const userContent = await buildUserMessageContent({
+		input,
+		attachments: options?.attachments,
+		modelName: config.model.name,
+		modelSupportsVision: Boolean(config.model.capabilities?.vision)
+	});
+	messages.push({
+		role: "user",
+		content: userContent
+	});
+	return {
+		messages,
+		responseSchema
+	};
+}
+/**
+* Build the user message `content` field. Plain string when no
+* attachments (the hot path) — keeps wire payloads small. Multipart
+* `ContentPart[]` when attachments exist: input text first, resolved
+* parts in declaration order.
+*/
+async function buildUserMessageContent(params) {
+	const { input, attachments, modelName, modelSupportsVision } = 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 } });
+	return [{
+		type: "text",
+		text: input
+	}, ...parts];
+}
+/**
+* When the caller supplied an `output` schema, resolve two artifacts:
+*
+* - `responseSchema` — extracted JSON Schema to attach on every trip.
+*   Adapters that natively support structured output (OpenAI's
+*   `response_format: json_schema`) consume it; others ignore it.
+* - `instruction` — a soft fallback appended to the system prompt
+*   **only** for models without native structured-output capability.
+*   Capable adapters skip it to save tokens and avoid redundancy.
+*/
+function resolveStructuredOutput(params) {
+	const { outputSchema, overrideResponseSchema, modelSupportsStructuredOutput } = params;
+	if (!outputSchema) return {};
+	const responseSchema = overrideResponseSchema ?? extractJsonSchema(outputSchema);
+	if (modelSupportsStructuredOutput) return { responseSchema };
+	return {
+		responseSchema,
+		instruction: [
+			"You MUST respond with a single valid JSON value only.",
+			"Do not wrap it in markdown code fences. Do not include prose, commentary, or explanation — JSON only.",
+			responseSchema ? `\n\nThe response MUST match this JSON Schema:\n${JSON.stringify(responseSchema, null, 2)}` : ""
+		].join("").trim()
+	};
+}
+
+//#endregion
+export { buildAgentInputMessages };
+//# sourceMappingURL=agent-input-builder.mjs.map

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

@@ -0,0 +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,EACG,KAAK,EAAE,EACP,KAEgC;CAAE;AACvC"}

package/esm/agent/agent-log-event.mjs

@@ -0,0 +1,101 @@
+//#region ../../@warlock.js/ai/src/agent/agent-log-event.ts
+/**
+* Structured logging for agent lifecycle events. Mirrors
+* `Execution.emit`'s call sites without touching class state — the
+* caller passes the ambient snapshot in `ctx`, we route each event to
+* the right logger level and enrich with the per-event forensic
+* detail.
+*
+* Log-level convention:
+* - `info` — lifecycle boundaries (agent starting / completed) users
+*   want to see at default verbosity
+* - `debug` — per-trip + per-tool progress (hot-path, opt-in)
+* - `success` — trip completion + tool success (terminal per-step state)
+* - `warn` — tool failures (recoverable, agent loop continues)
+* - `error` — agent-level terminal errors
+*
+* Streaming deltas (`agent.trip.streaming`) are intentionally skipped
+* to avoid token-granularity log spam.
+*/
+function logAgentEvent(logger, ctx, event, payload) {
+	const action = event.replace(/^agent\./, "");
+	switch (event) {
+		case "agent.starting": {
+			const { input } = payload;
+			logger.info(ctx.module, action, "agent starting", {
+				maxTrips: ctx.maxTrips,
+				model: ctx.modelName,
+				inputLength: input.length
+			});
+			return;
+		}
+		case "agent.trip.started": {
+			const { tripIndex } = payload;
+			logger.debug(ctx.module, action, "trip started", { tripIndex });
+			return;
+		}
+		case "agent.trip.streaming": return;
+		case "agent.trip.completed": {
+			const { trip } = payload;
+			logger.success(ctx.module, action, "trip completed", {
+				tripIndex: trip.index,
+				duration: trip.duration,
+				usage: trip.usage,
+				finishReason: trip.finishReason
+			});
+			return;
+		}
+		case "agent.tool.calling": {
+			const { tool, tripIndex } = payload;
+			logger.debug(ctx.module, action, `calling tool "${tool.name}"`, {
+				tool: tool.name,
+				action: tool.action,
+				tripIndex
+			});
+			return;
+		}
+		case "agent.tool.called": {
+			const toolCall = payload;
+			logger.success(ctx.module, action, `tool "${toolCall.name}" finished`, {
+				tool: toolCall.name,
+				duration: toolCall.duration,
+				tripIndex: toolCall.tripIndex
+			});
+			return;
+		}
+		case "agent.tool.failed": {
+			const { tool, error, tripIndex } = payload;
+			logger.warn(ctx.module, action, `tool "${tool.name}" failed`, {
+				tool: tool.name,
+				tripIndex,
+				error: {
+					code: error.code,
+					message: error.message,
+					name: error.name,
+					stack: error.stack
+				}
+			});
+			return;
+		}
+		case "agent.completed":
+			logger.info(ctx.module, action, "agent completed", {
+				duration: ctx.totalDurationMs,
+				usage: ctx.totalUsage,
+				trips: ctx.trips.length,
+				tools: ctx.toolCalls.length
+			});
+			return;
+		case "agent.error": {
+			const { error } = payload;
+			logger.error(ctx.module, action, error.message, {
+				code: error.code,
+				context: error.context
+			});
+			return;
+		}
+	}
+}
+
+//#endregion
+export { logAgentEvent };
+//# sourceMappingURL=agent-log-event.mjs.map

package/esm/agent/agent-log-event.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-log-event.mjs","names":[],"sources":["../../../../../../@warlock.js/ai/src/agent/agent-log-event.ts"],"sourcesContent":["import type { Logger } from \"@warlock.js/logger\";\nimport type { AgentEventMap } from \"../contracts/events/event-map.type\";\nimport type { LLMTrip } from \"../contracts/result/llm-trip.type\";\nimport type { ToolCall } from \"../contracts/result/tool-call.type\";\nimport type { Usage } from \"../contracts/result/usage.type\";\n\n/**\n * Aggregate snapshot the agent-level log entries need at emission time\n * (agent completion + model name + running totals). Passed instead of\n * storing a back-reference to the Execution class — keeps this helper\n * a pure function.\n */\nexport type AgentLogContext = {\n  /** Dotted logger module, e.g. `\"ai.agent.my-writer\"`. */\n  module: string;\n  /** Maximum trips configured for this run — logged once on `agent.starting`. */\n  maxTrips: number;\n  /** Model identifier — logged once on `agent.starting`. */\n  modelName: string;\n  /** Final running usage totals at the moment `agent.completed` fires. */\n  totalUsage: Usage;\n  /** Monotonic duration (ms) since start at the moment `agent.completed` fires. */\n  totalDurationMs: number;\n  /** All trips recorded so far — logged count on `agent.completed`. */\n  trips: LLMTrip[];\n  /** All tool calls recorded so far — logged count on `agent.completed`. */\n  toolCalls: ToolCall[];\n};\n\n/**\n * Structured logging for agent lifecycle events. Mirrors\n * `Execution.emit`'s call sites without touching class state — the\n * caller passes the ambient snapshot in `ctx`, we route each event to\n * the right logger level and enrich with the per-event forensic\n * detail.\n *\n * Log-level convention:\n * - `info` — lifecycle boundaries (agent starting / completed) users\n *   want to see at default verbosity\n * - `debug` — per-trip + per-tool progress (hot-path, opt-in)\n * - `success` — trip completion + tool success (terminal per-step state)\n * - `warn` — tool failures (recoverable, agent loop continues)\n * - `error` — agent-level terminal errors\n *\n * Streaming deltas (`agent.trip.streaming`) are intentionally skipped\n * to avoid token-granularity log spam.\n */\nexport function logAgentEvent<K extends keyof AgentEventMap>(\n  logger: Logger,\n  ctx: AgentLogContext,\n  event: K,\n  payload: AgentEventMap[K],\n): void {\n  const action = event.replace(/^agent\\./, \"\");\n\n  switch (event) {\n    case \"agent.starting\": {\n      const { input } = payload as AgentEventMap[\"agent.starting\"];\n      logger.info(ctx.module, action, \"agent starting\", {\n        maxTrips: ctx.maxTrips,\n        model: ctx.modelName,\n        inputLength: input.length,\n      });\n      return;\n    }\n\n    case \"agent.trip.started\": {\n      const { tripIndex } = payload as AgentEventMap[\"agent.trip.started\"];\n      logger.debug(ctx.module, action, \"trip started\", { tripIndex });\n      return;\n    }\n\n    case \"agent.trip.streaming\": {\n      // Deltas are too high-volume to log at token granularity.\n      // Skipped on purpose; debug level still fires on trip boundaries.\n      return;\n    }\n\n    case \"agent.trip.completed\": {\n      const { trip } = payload as AgentEventMap[\"agent.trip.completed\"];\n      logger.success(ctx.module, action, \"trip completed\", {\n        tripIndex: trip.index,\n        duration: trip.duration,\n        usage: trip.usage,\n        finishReason: trip.finishReason,\n      });\n      return;\n    }\n\n    case \"agent.tool.calling\": {\n      const { tool, tripIndex } =\n        payload as AgentEventMap[\"agent.tool.calling\"];\n      logger.debug(ctx.module, action, `calling tool \"${tool.name}\"`, {\n        tool: tool.name,\n        action: tool.action,\n        tripIndex,\n      });\n      return;\n    }\n\n    case \"agent.tool.called\": {\n      const toolCall = payload as AgentEventMap[\"agent.tool.called\"];\n      logger.success(ctx.module, action, `tool \"${toolCall.name}\" finished`, {\n        tool: toolCall.name,\n        duration: toolCall.duration,\n        tripIndex: toolCall.tripIndex,\n      });\n      return;\n    }\n\n    case \"agent.tool.failed\": {\n      const { tool, error, tripIndex } =\n        payload as AgentEventMap[\"agent.tool.failed\"];\n      logger.warn(ctx.module, action, `tool \"${tool.name}\" failed`, {\n        tool: tool.name,\n        tripIndex,\n        error: {\n          code: error.code,\n          message: error.message,\n          name: error.name,\n          stack: error.stack,\n        },\n      });\n      return;\n    }\n\n    case \"agent.completed\": {\n      logger.info(ctx.module, action, \"agent completed\", {\n        duration: ctx.totalDurationMs,\n        usage: ctx.totalUsage,\n        trips: ctx.trips.length,\n        tools: ctx.toolCalls.length,\n      });\n      return;\n    }\n\n    case \"agent.error\": {\n      const { error } = payload as AgentEventMap[\"agent.error\"];\n      logger.error(ctx.module, action, error.message, {\n        code: error.code,\n        context: error.context,\n      });\n      return;\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AA+CA,SAAgB,cACd,QACA,KACA,OACA,SACM;CACN,MAAM,SAAS,MAAM,QAAQ,YAAY,EAAE;CAE3C,QAAQ,OAAR;EACE,KAAK,kBAAkB;GACrB,MAAM,EAAE,UAAU;GAClB,OAAO,KAAK,IAAI,QAAQ,QAAQ,kBAAkB;IAChD,UAAU,IAAI;IACd,OAAO,IAAI;IACX,aAAa,MAAM;GACrB,CAAC;GACD;EACF;EAEA,KAAK,sBAAsB;GACzB,MAAM,EAAE,cAAc;GACtB,OAAO,MAAM,IAAI,QAAQ,QAAQ,gBAAgB,EAAE,UAAU,CAAC;GAC9D;EACF;EAEA,KAAK,wBAGH;EAGF,KAAK,wBAAwB;GAC3B,MAAM,EAAE,SAAS;GACjB,OAAO,QAAQ,IAAI,QAAQ,QAAQ,kBAAkB;IACnD,WAAW,KAAK;IAChB,UAAU,KAAK;IACf,OAAO,KAAK;IACZ,cAAc,KAAK;GACrB,CAAC;GACD;EACF;EAEA,KAAK,sBAAsB;GACzB,MAAM,EAAE,MAAM,cACZ;GACF,OAAO,MAAM,IAAI,QAAQ,QAAQ,iBAAiB,KAAK,KAAK,IAAI;IAC9D,MAAM,KAAK;IACX,QAAQ,KAAK;IACb;GACF,CAAC;GACD;EACF;EAEA,KAAK,qBAAqB;GACxB,MAAM,WAAW;GACjB,OAAO,QAAQ,IAAI,QAAQ,QAAQ,SAAS,SAAS,KAAK,aAAa;IACrE,MAAM,SAAS;IACf,UAAU,SAAS;IACnB,WAAW,SAAS;GACtB,CAAC;GACD;EACF;EAEA,KAAK,qBAAqB;GACxB,MAAM,EAAE,MAAM,OAAO,cACnB;GACF,OAAO,KAAK,IAAI,QAAQ,QAAQ,SAAS,KAAK,KAAK,WAAW;IAC5D,MAAM,KAAK;IACX;IACA,OAAO;KACL,MAAM,MAAM;KACZ,SAAS,MAAM;KACf,MAAM,MAAM;KACZ,OAAO,MAAM;IACf;GACF,CAAC;GACD;EACF;EAEA,KAAK;GACH,OAAO,KAAK,IAAI,QAAQ,QAAQ,mBAAmB;IACjD,UAAU,IAAI;IACd,OAAO,IAAI;IACX,OAAO,IAAI,MAAM;IACjB,OAAO,IAAI,UAAU;GACvB,CAAC;GACD;EAGF,KAAK,eAAe;GAClB,MAAM,EAAE,UAAU;GAClB,OAAO,MAAM,IAAI,QAAQ,QAAQ,MAAM,SAAS;IAC9C,MAAM,MAAM;IACZ,SAAS,MAAM;GACjB,CAAC;GACD;EACF;CACF;AACF"}

package/esm/agent/agent-stream.d.mts

@@ -0,0 +1,47 @@
+import { StreamEvent } from "../contracts/stream/stream-event.type.mjs";
+import { StreamContract } from "../contracts/stream/stream.contract.mjs";
+//#region ../../@warlock.js/ai/src/agent/agent-stream.d.ts
+/**
+ * Internal async-queue `StreamContract` used by `agent().stream()`.
+ *
+ * **Role.** The bridge between a streaming `Execution` (which runs in the
+ * background, pushing events as they happen) and a consumer that reads
+ * those events with `for await` or an `on(...)` handler map.
+ *
+ * **Responsibility.**
+ * - Owns: the event queue, the pending-read promise chain, the terminal
+ *   `result` promise, and any user-registered event handlers.
+ * - Does NOT own: any knowledge of agents, models, or tool calls — it is a
+ *   generic producer/consumer pipe parameterized by `TResult`. The streaming
+ *   execution writes via `push()` / `end()` / `fail()`; the consumer reads
+ *   via the AsyncIterable surface.
+ *
+ * Events are coalesced into a queue so that a consumer that starts
+ * iterating late still sees every event in order — nothing is dropped. The
+ * `on()` handlers fire the moment an event is pushed, independent of
+ * whether anyone is iterating.
+ *
+ * @example
+ * // Inside agent.stream():
+ * const { controller, stream } = createAgentStream<AgentResult<TOutput>>();
+ * new Execution(config, input, options, controller).run();
+ * return stream;
+ *
+ * // Consumer:
+ * for await (const event of stream) {
+ *   if (event.type === "streaming") process.stdout.write(event.delta);
+ * }
+ * const result = await stream.result;
+ */
+type StreamController<TResult> = {
+  push(event: StreamEvent): void;
+  end(result: TResult): void;
+  fail(error: Error): void;
+};
+declare function createAgentStream<TResult>(): {
+  controller: StreamController<TResult>;
+  stream: StreamContract<TResult>;
+};
+//#endregion
+export { StreamController, createAgentStream };
+//# sourceMappingURL=agent-stream.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent-stream.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/agent/agent-stream.ts"],"mappings":";;;;;;;AAkCA;;;;;;;;;;;;;;;;;;;AAGmB;AAQnB;;;;;;;;KAXY,gBAAA;EACV,IAAA,CAAK,KAAA,EAAO,WAAA;EACZ,GAAA,CAAI,MAAA,EAAQ,OAAA;EACZ,IAAA,CAAK,KAAA,EAAO,KAAA;AAAA;AAAA,iBAQE,iBAAA,SAAA,CAAA;EACd,UAAA,EAAY,gBAAA,CAAiB,OAAA;EAC7B,MAAA,EAAQ,cAAA,CAAe,OAAA;AAAA"}

package/esm/agent/agent-stream.mjs

@@ -0,0 +1,82 @@
+//#region ../../@warlock.js/ai/src/agent/agent-stream.ts
+function createAgentStream() {
+	const queue = [];
+	const pending = [];
+	const handlers = /* @__PURE__ */ new Map();
+	let closed = false;
+	let failure;
+	let resolveResult;
+	let rejectResult;
+	const result = new Promise((resolve, reject) => {
+		resolveResult = resolve;
+		rejectResult = reject;
+	});
+	const controller = {
+		push(event) {
+			const handler = handlers.get(event.type);
+			if (handler) try {
+				handler(event);
+			} catch {}
+			const reader = pending.shift();
+			if (reader) {
+				reader.resolve({
+					value: event,
+					done: false
+				});
+				return;
+			}
+			queue.push(event);
+		},
+		end(finalResult) {
+			closed = true;
+			resolveResult(finalResult);
+			while (pending.length > 0) pending.shift()?.resolve({
+				value: void 0,
+				done: true
+			});
+		},
+		fail(error) {
+			closed = true;
+			failure = error;
+			rejectResult(error);
+			while (pending.length > 0) pending.shift()?.reject(error);
+		}
+	};
+	const iterator = { next() {
+		if (queue.length > 0) return Promise.resolve({
+			value: queue.shift(),
+			done: false
+		});
+		if (closed) {
+			if (failure) return Promise.reject(failure);
+			return Promise.resolve({
+				value: void 0,
+				done: true
+			});
+		}
+		return new Promise((resolve, reject) => {
+			pending.push({
+				resolve,
+				reject
+			});
+		});
+	} };
+	const stream = {
+		result,
+		on(handlerMap) {
+			for (const [key, handler] of Object.entries(handlerMap)) if (handler) handlers.set(key, handler);
+			return stream;
+		},
+		[Symbol.asyncIterator]() {
+			return iterator;
+		}
+	};
+	return {
+		controller,
+		stream
+	};
+}
+
+//#endregion
+export { createAgentStream };
+//# sourceMappingURL=agent-stream.mjs.map

package/esm/agent/agent-stream.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-stream.mjs","names":[],"sources":["../../../../../../@warlock.js/ai/src/agent/agent-stream.ts"],"sourcesContent":["import type { StreamContract, StreamEvent } from \"../contracts\";\n\n/**\n * Internal async-queue `StreamContract` used by `agent().stream()`.\n *\n * **Role.** The bridge between a streaming `Execution` (which runs in the\n * background, pushing events as they happen) and a consumer that reads\n * those events with `for await` or an `on(...)` handler map.\n *\n * **Responsibility.**\n * - Owns: the event queue, the pending-read promise chain, the terminal\n *   `result` promise, and any user-registered event handlers.\n * - Does NOT own: any knowledge of agents, models, or tool calls — it is a\n *   generic producer/consumer pipe parameterized by `TResult`. The streaming\n *   execution writes via `push()` / `end()` / `fail()`; the consumer reads\n *   via the AsyncIterable surface.\n *\n * Events are coalesced into a queue so that a consumer that starts\n * iterating late still sees every event in order — nothing is dropped. The\n * `on()` handlers fire the moment an event is pushed, independent of\n * whether anyone is iterating.\n *\n * @example\n * // Inside agent.stream():\n * const { controller, stream } = createAgentStream<AgentResult<TOutput>>();\n * new Execution(config, input, options, controller).run();\n * return stream;\n *\n * // Consumer:\n * for await (const event of stream) {\n *   if (event.type === \"streaming\") process.stdout.write(event.delta);\n * }\n * const result = await stream.result;\n */\nexport type StreamController<TResult> = {\n  push(event: StreamEvent): void;\n  end(result: TResult): void;\n  fail(error: Error): void;\n};\n\ntype PendingRead = {\n  resolve(value: IteratorResult<StreamEvent>): void;\n  reject(error: Error): void;\n};\n\nexport function createAgentStream<TResult>(): {\n  controller: StreamController<TResult>;\n  stream: StreamContract<TResult>;\n} {\n  const queue: StreamEvent[] = [];\n  const pending: PendingRead[] = [];\n  const handlers = new Map<StreamEvent[\"type\"], (event: StreamEvent) => void>();\n\n  let closed = false;\n  let failure: Error | undefined;\n  let resolveResult!: (value: TResult) => void;\n  let rejectResult!: (error: Error) => void;\n\n  const result = new Promise<TResult>((resolve, reject) => {\n    resolveResult = resolve;\n    rejectResult = reject;\n  });\n\n  const controller: StreamController<TResult> = {\n    push(event) {\n      const handler = handlers.get(event.type);\n\n      if (handler) {\n        try {\n          handler(event);\n        } catch {\n          // User-provided stream handlers must never crash the agent.\n          // Swallow — structured logging attaches here in Phase 0.5.\n        }\n      }\n\n      const reader = pending.shift();\n\n      if (reader) {\n        reader.resolve({ value: event, done: false });\n        return;\n      }\n\n      queue.push(event);\n    },\n\n    end(finalResult) {\n      closed = true;\n      resolveResult(finalResult);\n\n      while (pending.length > 0) {\n        const reader = pending.shift();\n\n        reader?.resolve({ value: undefined, done: true });\n      }\n    },\n\n    fail(error) {\n      closed = true;\n      failure = error;\n      rejectResult(error);\n\n      while (pending.length > 0) {\n        const reader = pending.shift();\n\n        reader?.reject(error);\n      }\n    },\n  };\n\n  const iterator: AsyncIterator<StreamEvent> = {\n    next() {\n      if (queue.length > 0) {\n        return Promise.resolve({ value: queue.shift()!, done: false });\n      }\n\n      if (closed) {\n        if (failure) {\n          return Promise.reject(failure);\n        }\n\n        return Promise.resolve({ value: undefined, done: true });\n      }\n\n      return new Promise<IteratorResult<StreamEvent>>((resolve, reject) => {\n        pending.push({ resolve, reject });\n      });\n    },\n  };\n\n  const stream: StreamContract<TResult> = {\n    result,\n    on(handlerMap) {\n      for (const [key, handler] of Object.entries(handlerMap)) {\n        if (handler) {\n          handlers.set(\n            key as StreamEvent[\"type\"],\n            handler as (event: StreamEvent) => void,\n          );\n        }\n      }\n\n      return stream;\n    },\n    [Symbol.asyncIterator]() {\n      return iterator;\n    },\n  };\n\n  return { controller, stream };\n}\n"],"mappings":";AA6CA,SAAgB,oBAGd;CACA,MAAM,QAAuB,CAAC;CAC9B,MAAM,UAAyB,CAAC;CAChC,MAAM,2BAAW,IAAI,IAAuD;CAE5E,IAAI,SAAS;CACb,IAAI;CACJ,IAAI;CACJ,IAAI;CAEJ,MAAM,SAAS,IAAI,SAAkB,SAAS,WAAW;EACvD,gBAAgB;EAChB,eAAe;CACjB,CAAC;CAED,MAAM,aAAwC;EAC5C,KAAK,OAAO;GACV,MAAM,UAAU,SAAS,IAAI,MAAM,IAAI;GAEvC,IAAI,SACF,IAAI;IACF,QAAQ,KAAK;GACf,QAAQ,CAGR;GAGF,MAAM,SAAS,QAAQ,MAAM;GAE7B,IAAI,QAAQ;IACV,OAAO,QAAQ;KAAE,OAAO;KAAO,MAAM;IAAM,CAAC;IAC5C;GACF;GAEA,MAAM,KAAK,KAAK;EAClB;EAEA,IAAI,aAAa;GACf,SAAS;GACT,cAAc,WAAW;GAEzB,OAAO,QAAQ,SAAS,GAGtB,AAFe,QAAQ,MAElB,GAAG,QAAQ;IAAE,OAAO;IAAW,MAAM;GAAK,CAAC;EAEpD;EAEA,KAAK,OAAO;GACV,SAAS;GACT,UAAU;GACV,aAAa,KAAK;GAElB,OAAO,QAAQ,SAAS,GAGtB,AAFe,QAAQ,MAElB,GAAG,OAAO,KAAK;EAExB;CACF;CAEA,MAAM,WAAuC,EAC3C,OAAO;EACL,IAAI,MAAM,SAAS,GACjB,OAAO,QAAQ,QAAQ;GAAE,OAAO,MAAM,MAAM;GAAI,MAAM;EAAM,CAAC;EAG/D,IAAI,QAAQ;GACV,IAAI,SACF,OAAO,QAAQ,OAAO,OAAO;GAG/B,OAAO,QAAQ,QAAQ;IAAE,OAAO;IAAW,MAAM;GAAK,CAAC;EACzD;EAEA,OAAO,IAAI,SAAsC,SAAS,WAAW;GACnE,QAAQ,KAAK;IAAE;IAAS;GAAO,CAAC;EAClC,CAAC;CACH,EACF;CAEA,MAAM,SAAkC;EACtC;EACA,GAAG,YAAY;GACb,KAAK,MAAM,CAAC,KAAK,YAAY,OAAO,QAAQ,UAAU,GACpD,IAAI,SACF,SAAS,IACP,KACA,OACF;GAIJ,OAAO;EACT;EACA,CAAC,OAAO,iBAAiB;GACvB,OAAO;EACT;CACF;CAEA,OAAO;EAAE;EAAY;CAAO;AAC9B"}

package/esm/agent/agent-to-stream-event.mjs

@@ -0,0 +1,86 @@
+//#region ../../@warlock.js/ai/src/agent/agent-to-stream-event.ts
+/**
+* Map an internal `AgentEventMap` entry into the public `StreamEvent`
+* shape. Event names are the same dot-notation strings on both sides;
+* only the payload shape needs per-event translation — the notable
+* case is `agent.tool.called`, whose event-map payload is a bare
+* `ToolCall` but whose stream wrapper is `{ toolCall }`.
+*
+* Extracted from the `Execution` class in `agent.ts` because it's
+* fully stateless (pure function of event name + payload) and used
+* only from the stream-forwarding path. Keeps the class focused on
+* stateful orchestration.
+*/
+function agentEventToStreamEvent(event, payload) {
+	switch (event) {
+		case "agent.starting": {
+			const { input } = payload;
+			return {
+				type: "agent.starting",
+				input
+			};
+		}
+		case "agent.trip.started": {
+			const { tripIndex, input } = payload;
+			return {
+				type: "agent.trip.started",
+				tripIndex,
+				input
+			};
+		}
+		case "agent.trip.streaming": {
+			const { delta, tripIndex } = payload;
+			return {
+				type: "agent.trip.streaming",
+				delta,
+				tripIndex
+			};
+		}
+		case "agent.tool.calling": {
+			const { tool, input, tripIndex } = payload;
+			return {
+				type: "agent.tool.calling",
+				tool,
+				input,
+				tripIndex
+			};
+		}
+		case "agent.tool.called": {
+			const { tool, ...toolCall } = payload;
+			return {
+				type: "agent.tool.called",
+				toolCall,
+				tool
+			};
+		}
+		case "agent.tool.failed": {
+			const { tool, error, tripIndex } = payload;
+			return {
+				type: "agent.tool.failed",
+				tool,
+				error,
+				tripIndex
+			};
+		}
+		case "agent.trip.completed": {
+			const { trip } = payload;
+			return {
+				type: "agent.trip.completed",
+				trip
+			};
+		}
+		case "agent.completed": return { type: "agent.completed" };
+		case "agent.error": {
+			const { error } = payload;
+			return {
+				type: "agent.error",
+				error
+			};
+		}
+		default: return;
+	}
+}
+
+//#endregion
+export { agentEventToStreamEvent };
+//# sourceMappingURL=agent-to-stream-event.mjs.map

package/esm/agent/agent-to-stream-event.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-to-stream-event.mjs","names":["called"],"sources":["../../../../../../@warlock.js/ai/src/agent/agent-to-stream-event.ts"],"sourcesContent":["import type { AgentEventMap } from \"../contracts/events/event-map.type\";\nimport type { StreamEventBody } from \"../contracts/stream/stream-event.type\";\n\n/**\n * Map an internal `AgentEventMap` entry into the public `StreamEvent`\n * shape. Event names are the same dot-notation strings on both sides;\n * only the payload shape needs per-event translation — the notable\n * case is `agent.tool.called`, whose event-map payload is a bare\n * `ToolCall` but whose stream wrapper is `{ toolCall }`.\n *\n * Extracted from the `Execution` class in `agent.ts` because it's\n * fully stateless (pure function of event name + payload) and used\n * only from the stream-forwarding path. Keeps the class focused on\n * stateful orchestration.\n */\nexport function agentEventToStreamEvent<K extends keyof AgentEventMap>(\n  event: K,\n  payload: AgentEventMap[K],\n): StreamEventBody | undefined {\n  switch (event) {\n    case \"agent.starting\": {\n      const { input } = payload as AgentEventMap[\"agent.starting\"];\n      return { type: \"agent.starting\", input };\n    }\n\n    case \"agent.trip.started\": {\n      const { tripIndex, input } =\n        payload as AgentEventMap[\"agent.trip.started\"];\n      return { type: \"agent.trip.started\", tripIndex, input };\n    }\n\n    case \"agent.trip.streaming\": {\n      const { delta, tripIndex } =\n        payload as AgentEventMap[\"agent.trip.streaming\"];\n      return { type: \"agent.trip.streaming\", delta, tripIndex };\n    }\n\n    case \"agent.tool.calling\": {\n      const { tool, input, tripIndex } =\n        payload as AgentEventMap[\"agent.tool.calling\"];\n      return { type: \"agent.tool.calling\", tool, input, tripIndex };\n    }\n\n    case \"agent.tool.called\": {\n      const called = payload as AgentEventMap[\"agent.tool.called\"];\n      // Split off the agent's enriched ToolCall record from the tool meta\n      // so the stream event surface mirrors the bus payload shape.\n      const { tool, ...toolCall } = called;\n      return { type: \"agent.tool.called\", toolCall, tool };\n    }\n\n    case \"agent.tool.failed\": {\n      const { tool, error, tripIndex } =\n        payload as AgentEventMap[\"agent.tool.failed\"];\n      return { type: \"agent.tool.failed\", tool, error, tripIndex };\n    }\n\n    case \"agent.trip.completed\": {\n      const { trip } = payload as AgentEventMap[\"agent.trip.completed\"];\n      return { type: \"agent.trip.completed\", trip };\n    }\n\n    case \"agent.completed\": {\n      return { type: \"agent.completed\" };\n    }\n\n    case \"agent.error\": {\n      const { error } = payload as AgentEventMap[\"agent.error\"];\n      return { type: \"agent.error\", error };\n    }\n\n    default: {\n      return undefined;\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;AAeA,SAAgB,wBACd,OACA,SAC6B;CAC7B,QAAQ,OAAR;EACE,KAAK,kBAAkB;GACrB,MAAM,EAAE,UAAU;GAClB,OAAO;IAAE,MAAM;IAAkB;GAAM;EACzC;EAEA,KAAK,sBAAsB;GACzB,MAAM,EAAE,WAAW,UACjB;GACF,OAAO;IAAE,MAAM;IAAsB;IAAW;GAAM;EACxD;EAEA,KAAK,wBAAwB;GAC3B,MAAM,EAAE,OAAO,cACb;GACF,OAAO;IAAE,MAAM;IAAwB;IAAO;GAAU;EAC1D;EAEA,KAAK,sBAAsB;GACzB,MAAM,EAAE,MAAM,OAAO,cACnB;GACF,OAAO;IAAE,MAAM;IAAsB;IAAM;IAAO;GAAU;EAC9D;EAEA,KAAK,qBAAqB;GAIxB,MAAM,EAAE,MAAM,GAAG,aAAaA;GAC9B,OAAO;IAAE,MAAM;IAAqB;IAAU;GAAK;EACrD;EAEA,KAAK,qBAAqB;GACxB,MAAM,EAAE,MAAM,OAAO,cACnB;GACF,OAAO;IAAE,MAAM;IAAqB;IAAM;IAAO;GAAU;EAC7D;EAEA,KAAK,wBAAwB;GAC3B,MAAM,EAAE,SAAS;GACjB,OAAO;IAAE,MAAM;IAAwB;GAAK;EAC9C;EAEA,KAAK,mBACH,OAAO,EAAE,MAAM,kBAAkB;EAGnC,KAAK,eAAe;GAClB,MAAM,EAAE,UAAU;GAClB,OAAO;IAAE,MAAM;IAAe;GAAM;EACtC;EAEA,SACE;CAEJ;AACF"}