@warlock.js/core 4.4.0 → 4.6.0

package/CHANGELOG.md

@@ -4,6 +4,73 @@ All notable changes to `@warlock.js/core` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
+## 4.6.0
+
+### Added
+
+- release-hygiene tests: version↔changelog invariant + generator-stub import check
+- `router.routeCount()` exposes the number of registered routes as a boot/readiness signal
+- `health.addRoutesRegisteredCheck(getRouteCount)` registers a readiness check that reports not-ready when a booted HTTP app has zero routes
+- seeders now receive a `{ track }` context — `track(model)`, `track(models[])`, and `track(table, id)` register created records (each call returns its argument so it can be chained inline); `recordsCreated` is auto-derived from the track count
+- `seed_records` table (created via the new `SeedRecordsTableMigration`) records every tracked seed reference within the same transaction the seed runs in; only the last run's refs are kept per seeder
+- `warlock seed --drop [name]` undoes a seed: deletes its tracked records in reverse run/insertion order inside a transaction, then resets the matching seeds-log rows so `once: true` seeds re-run; scope to one seeder with `--drop=<name>`
+- `Seeder.dependsOn` is now resolved — seeders are topologically sorted so dependencies run before dependents, layered over the numeric `order` tie-break; throws `UnknownSeederDependencyError` for a missing dependency and `SeederDependencyCycleError` for a cycle
+- seeders receive an injectable clock and a meaningful batch size — `run({ track, now, batchSize })`; `now()` (default `() => new Date()`) drives both seed data and the seeds-log timestamps so historical/back-fill runs are deterministic, and `batchSize` surfaces the seeder's own `batchSize` for `Model.createMany(rows, { batchSize })`
+- repository-level aggregation — `aggregate()`, `sum()`, `avg()`, `min()`, `max()`, and `groupBy()` on `RepositoryManager`, each reusing `filterBy` (and its operator-injection guard), `where`, and scopes before the aggregate, exactly like `count()`
+- `warlock doctor` — a read-only diagnostics command that runs routes / config / connectors / optional-peers / health / release-hygiene checks and prints a pass/warn/fail report (exits non-zero on any failure, never opens a DB/cache/socket connection)
+- `warlock routes` — a read-only command that lists the registered HTTP routes as a verb-colored table (method / path / name / action / middleware-count / source); filter with `--method` / `--path` / `--name`, or emit the normalized rows as JSON with `--json`. Boots app code to register routes but starts no connectors
+
+### Changed
+
+- `Seeder.run` now receives a `SeedContext` (`run(ctx)`) — backward compatible, an existing zero-arg `run()` keeps working unchanged
+
+### Fixed
+
+- route-module load/registration failures are no longer swallowed: a route file that throws on import or registration now surfaces loudly instead of silently 404'ing the whole surface
+- `ModuleLoader.loadModule` rethrows after logging (wrapped in a new `ModuleLoadError` carrying the failing file + cause), so a broken module aborts boot and is caught loudly by the HMR batch-reload handler in dev
+- `ModuleLoader.loadAll` aggregates per-file failures and throws an `AggregateError` at the end, so one broken module no longer hides the others
+- `router.withSourceFile` rethrows the callback error after logging instead of consuming it with a bare `console.log` (the `try/finally` source-file stack cleanup is preserved)
+
+## 4.5.0
+
+### Changed
+
+- dev-server update notice now fires immediately on `warlock dev` — the check is spawned in parallel with server startup instead of awaiting it, so the notice surfaces as soon as npm responds
+- raised the update check's npm registry timeout from 2.5s to 30s, so a slow connection no longer drops the notice
+- repository lifecycle hooks (`onCreating` / `onCreate` / `onUpdating` / `onSaving` / `onDeleting` / …) now run on `create` / `update` / `delete` — they were defined but never invoked
+- `repository.list()` / `all()` now honor the `sortBy`, `sortDirection`, and `purgeCache` options — previously accepted but silently ignored
+
+### Removed
+
+- presigned-upload `maxSize` option — a presigned PUT URL cannot enforce a size cap, so the option was a false guarantee
+
+### Fixed
+
+- `response.sendFile({ filename })` and `response.download()` no longer 500 on non-ASCII file names — the `Content-Disposition` header is now RFC 6266-encoded (a sanitized ASCII `filename` fallback plus an RFC 5987 `filename*=UTF-8''…`), so an Arabic / emoji / UTF-8 download name streams correctly instead of throwing Node's `ERR_INVALID_CHAR`
+- local storage paths are contained to their disk root — `../` traversal segments and absolute paths can no longer escape the configured directory
+- `storage.putFromUrl` adds SSRF guards — private / loopback / link-local hosts are rejected and the fetched body is size-capped
+- S3 / R2 / DigitalOcean Spaces `url()` no longer produces a malformed double-host URL when `urlPrefix` is set
+- cloud `deleteDirectory` paginates via the list continuation cursor instead of re-listing the first page
+- local-storage metadata cache is invalidated on write / delete — it was serving a stale size / modified-time
+- the cloud driver no longer reports a misleading "SDK not installed" error when the AWS SDK is in fact present (driver load race)
+- repository `countCached` / `countActiveCached` now cache and return correctly — a `null` cache miss was being returned as the count
+- repository `firstCached` / `lastCached` no longer fetch and cache the entire table to return a single row
+- repository boolean filters no longer coerce `false` / `0` to `true`
+- repository cache keys are now order-independent (stable key serialization)
+- router groups restore prefix / name / middleware state via `try/finally` even when the group callback throws
+- `router.any()` / `all` routes now match every HTTP verb under the dev server — they previously matched only GET and POST, diverging from production
+- the HTTP concurrency limiter releases its slot on every response path (`noContent`, redirect, file, buffer) — a throwing or non-`send` handler no longer leaks a permit and permanently 429s the route
+- the cached-response middleware replays a hit through `response.replay()` instead of re-sending an already-sent reply, preserving status and content-type
+- `onSent` cache writes in the idempotency and cache middleware are error-handled — a cache-backend failure no longer surfaces as an unhandled rejection
+- `X-Forwarded-For` is parsed to its first hop, so IP-filter / rate-limit / idempotency scoping cannot be spoofed with extra header hops
+- the `maintenance` middleware allowlist matches request paths that carry a query string
+- use-cases run their `after` middleware and broadcast for a `void` handler, and a failed history write no longer fails an otherwise-successful call
+- the use-case retry counter reports the correct count on total failure
+- the socket connector no longer double-closes the shared HTTP server during graceful shutdown
+- the cache connector disconnects its drivers on shutdown — an open Redis connection was left dangling
+- generator stubs import `v` / `Infer` from `@warlock.js/seal` (core never re-exported them), so generated models compile and run
+- `warlock dev` hot-reloads when a file is emptied or saved with no trailing newline — a stale no-op-change check was silently dropping those saves before they reached HMR
+
 ## 4.4.0 - 2026-06-21
 
 ### Added
@@ -38,9 +105,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Added
 
-- `lowerStage3Decorators()` — Vite/Vitest plugin that lowers TC39 Stage-3 decorators with esbuild before oxc / the SSR rewrite mangles them; drop it first in a config's `plugins` so model-decorated files load under Vitest 4 / Vite 8.
-- `warlock add notifications` — installs `@warlock.js/notifications` (+ the `mail` feature), ejects `config/notifications.ts`, and scaffolds the app-owned `Notification` model + migration into `src/app/notifications/` (idempotent; async queue opt-in).
-- Notifications connector — built-in connector (priority `8`, early phase) reads `config/notifications.ts` at boot and passes it to `setNotificationConfig`; lazy-imports `@warlock.js/notifications` (config-gated), so core keeps no hard dependency on it.
+- `lowerStage3Decorators()` — Vite/Vitest plugin that lowers TC39 Stage-3 decorators with esbuild before oxc / the SSR rewrite mangles them; drop it first in `plugins` so model-decorated files load under Vitest 4 / Vite 8.
+- `warlock add notifications` — installs `@warlock.js/notifications` (+ the `mail` feature), ejects `config/notifications.ts`, and scaffolds the app-owned `Notification` model + migration (idempotent).
+- Notifications connector — a built-in, config-gated connector that lazy-imports `@warlock.js/notifications`, so core keeps no hard dependency on it.
 
 ### Changed
 
@@ -50,7 +117,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Fixed
 
-- `startHttpTestServer` now starts early-phase connectors (database, cache, logger, …) before loading app modules, then late-phase (http, socket) after — mirroring dev/prod boot order; fixes a `MissingDataSourceError` when a module's boot side-effect queries the DB at import under the Vitest integration harness.
+- `startHttpTestServer` now starts early-phase connectors (database, cache, logger, …) before app modules, then late-phase (http, socket) after — mirroring dev/prod boot order; fixes a `MissingDataSourceError` under the Vitest integration harness.
 
 ## 4.2.5
 
@@ -86,7 +153,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Changed
 
-- `herald-connector` and `http-connector` now log a failed boot-time connection at `log.fatal` (was `log.error` / a dev-only console write). A broker connection failure or an HTTP port-bind failure at boot is unrecoverable — `fatal` makes "page on fatal only" alerting clean, aligned with the cascade and cache drivers. The HTTP connector additionally `await log.flush()` before `process.exit(1)` so the fatal entry reaches Sentry/file before the process dies. Disconnect/shutdown failures stay at `error`.
+- `herald-connector` and `http-connector` now log a failed boot-time connection at `log.fatal` (was `log.error`) — an unrecoverable broker connection or HTTP port-bind failure makes "page on fatal only" alerting clean; the HTTP connector flushes logs before `process.exit(1)`. Disconnect / shutdown failures stay at `error`.
 
 ## 4.1.15
 

package/README.md

@@ -1,11 +1,47 @@
-# Warlock
-
-A robust nodejs framework for building blazing fast applications.
-
-## Installation
-
-`yarn create warlock my-backend-app`
-
-## Documentation
-
-Full documentation is available at [official documentation](https://warlock.js.org).
+# @warlock.js/core
+
+A robust Node.js framework for building blazing fast applications.
+
+## Installation
+
+```bash
+yarn create warlock my-backend-app
+```
+
+## What's in the box
+
+`@warlock.js/core` bundles the runtime primitives an application boots on:
+
+| Primitive          | What it does                                                            |
+| ------------------ | ----------------------------------------------------------------------- |
+| Application        | Boot/shutdown lifecycle, boot hooks, health & readiness endpoints       |
+| HTTP + router      | Fastify-backed server, route groups, RESTful resource routes            |
+| Middleware         | Request pipeline guards and transformers                                |
+| Storage            | Disk-contained local + remote file storage                              |
+| Repositories       | Cached query layer over Cascade models                                  |
+| Use-cases          | Composable application services with history                            |
+| Validation         | Framework validators (file, database rules) layered on `@warlock.js/seal` |
+| Mail               | Mail sending and templating                                             |
+| Cache              | Application cache facade                                                 |
+| Socket             | Real-time socket layer                                                  |
+| Dev-server         | `warlock dev` with type generation and update notices                   |
+| CLI                | `warlock` generators, migrations, and project commands                  |
+
+## Optional peer dependencies
+
+Core keeps these as **optional** peers — install a package only when you use the
+feature that needs it:
+
+| Install                                                                          | Needed for                                  |
+| -------------------------------------------------------------------------------- | ------------------------------------------- |
+| `sharp`                                                                          | image processing / resizing                 |
+| `socket.io`                                                                      | the socket layer                            |
+| `nodemailer`                                                                     | sending mail                                |
+| `@aws-sdk/client-s3` + `@aws-sdk/lib-storage` + `@aws-sdk/s3-request-presigner`  | S3 storage driver + presigned URLs          |
+| `@aws-sdk/client-sesv2`                                                          | the AWS SES mail driver                     |
+| `react` + `react-dom` + `@react-email/render`                                    | React Email templates                       |
+| `@warlock.js/herald`                                                             | the Herald message-broker connector         |
+
+## Documentation
+
+Full documentation is available at the [official documentation](https://warlock.js.org).

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

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

package/esm/ai/src/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/ai/src/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\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;GAEF,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/ai/src/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/ai/src/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,CAAC,EAAE,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,CAAC,EAAE,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/ai/src/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/ai/src/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"}