@warlock.js/ai 4.4.0 → 4.6.0

package/esm/team/team.mjs

@@ -0,0 +1,94 @@
+import { SupervisorFailedError } from "../errors/supervisor-failed-error.mjs";
+import "../errors/index.mjs";
+import { supervisor } from "../supervisor/supervisor.mjs";
+import { buildQualityGate, buildVerifyGate } from "./gates.mjs";
+
+//#region ../@warlock.js/ai/src/team/team.ts
+/**
+* `ai.team(config)` — thin, transparent sugar over `ai.supervisor`.
+*
+* Builds a {@link SupervisorConfig} from the team-shaped config and
+* calls `supervisor(...)`, returning the **unchanged**
+* `SupervisorContract<TOutput>` — the same object `ai.supervisor`
+* returns, so `ctx.intents.<member>.execute()`, `.asTool()`,
+* `.resume()`, snapshots, and events all stay intact. `team()` owns no
+* loop: the manager becomes `route`/`router`, the members become
+* `intents`, and the `gate` becomes `evaluate`. Everything else passes
+* through 1:1.
+*
+* A `gate: "quality" | "verify"` string selects a pre-built `evaluate`
+* strategy ({@link buildQualityGate} / {@link buildVerifyGate}); a
+* function forwards straight to `SupervisorConfig.evaluate` (full
+* escape hatch). When the gate is a string, the resolved `fixer` (and,
+* for `"quality"`, the `reviewer`) roles are validated against
+* `members` at construction — a missing role throws an authoring-style
+* {@link SupervisorFailedError} (`context: { authoring: true }`) rather
+* than silently starving until `maxIterations`.
+*
+* @example
+* const codeTeam = ai.team({
+*   name: "code-team",
+*   goal: "Ship a tested module that passes review.",
+*   manager: techLeadRouter,
+*   members: { builder, reviewer, fixer },
+*   gate: "quality",
+*   output: v.object({ code: v.string() }),
+*   maxIterations: 6,
+* });
+*
+* const { data, report } = await codeTeam.execute("Build a debounce<T> utility.");
+*/
+function team(config) {
+	const supervisorConfig = {
+		name: config.name,
+		version: config.version,
+		reportType: "team",
+		intents: config.members,
+		evaluate: resolveGate(config),
+		goal: config.goal,
+		output: config.output,
+		state: config.state,
+		maxIterations: config.maxIterations,
+		snapshotStore: config.snapshotStore,
+		on: config.on,
+		observe: config.observe
+	};
+	if (isRouteManager(config.manager)) supervisorConfig.route = config.manager.route;
+	else supervisorConfig.router = config.manager;
+	return supervisor(supervisorConfig);
+}
+/**
+* Resolve the team's `gate` into a concrete `evaluate` callback. A
+* function forwards untouched; a {@link TeamGate} string is validated
+* against `members` and desugared into the matching pre-built gate.
+*/
+function resolveGate(config) {
+	if (typeof config.gate === "function") return config.gate;
+	const gate = config.gate;
+	const fixerRole = config.roles?.fixer ?? "fixer";
+	assertMemberExists(config, fixerRole, "fixer");
+	if (gate === "quality") {
+		assertMemberExists(config, config.roles?.reviewer ?? "reviewer", "reviewer");
+		return buildQualityGate(config.gateKey ?? "approved", fixerRole);
+	}
+	return buildVerifyGate(config.gateKey ?? "passed", fixerRole);
+}
+/**
+* Construction-time guard: assert the resolved role key exists in
+* `members`, throwing an authoring-style {@link SupervisorFailedError}
+* (tagged `authoring: true`) listing the missing role when it doesn't.
+*/
+function assertMemberExists(config, role, label) {
+	if (!Object.prototype.hasOwnProperty.call(config.members, role)) throw new SupervisorFailedError(`ai.team("${config.name}"): gate "${config.gate}" needs a "${label}" member but no \`members.${role}\` key exists`, { context: { authoring: true } });
+}
+/**
+* Discriminate the `manager` union: `true` when it is the deterministic
+* `{ route }` form, `false` for a bare `AgentContract` / `RouterEntry`.
+*/
+function isRouteManager(manager) {
+	return typeof manager === "object" && manager !== null && "route" in manager && typeof manager.route === "function";
+}
+
+//#endregion
+export { team };
+//# sourceMappingURL=team.mjs.map

package/esm/team/team.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"team.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/team/team.ts"],"sourcesContent":["import type {\n  EvaluateContext,\n  EvaluateResult,\n} from \"../contracts/supervisor/evaluate-context.type\";\nimport type { SupervisorIntentValue } from \"../contracts/supervisor/intent-entry.type\";\nimport type { SupervisorConfig } from \"../contracts/supervisor/supervisor-config.type\";\nimport type { SupervisorContract } from \"../contracts/supervisor/supervisor.contract\";\nimport type {\n  TeamConfig,\n  TeamGate,\n  TeamGateFn,\n  TeamMemberValue,\n} from \"../contracts/team/team-config.type\";\nimport { SupervisorFailedError } from \"../errors\";\nimport { supervisor } from \"../supervisor/supervisor\";\nimport { buildQualityGate, buildVerifyGate } from \"./gates\";\n\n/**\n * `ai.team(config)` — thin, transparent sugar over `ai.supervisor`.\n *\n * Builds a {@link SupervisorConfig} from the team-shaped config and\n * calls `supervisor(...)`, returning the **unchanged**\n * `SupervisorContract<TOutput>` — the same object `ai.supervisor`\n * returns, so `ctx.intents.<member>.execute()`, `.asTool()`,\n * `.resume()`, snapshots, and events all stay intact. `team()` owns no\n * loop: the manager becomes `route`/`router`, the members become\n * `intents`, and the `gate` becomes `evaluate`. Everything else passes\n * through 1:1.\n *\n * A `gate: \"quality\" | \"verify\"` string selects a pre-built `evaluate`\n * strategy ({@link buildQualityGate} / {@link buildVerifyGate}); a\n * function forwards straight to `SupervisorConfig.evaluate` (full\n * escape hatch). When the gate is a string, the resolved `fixer` (and,\n * for `\"quality\"`, the `reviewer`) roles are validated against\n * `members` at construction — a missing role throws an authoring-style\n * {@link SupervisorFailedError} (`context: { authoring: true }`) rather\n * than silently starving until `maxIterations`.\n *\n * @example\n * const codeTeam = ai.team({\n *   name: \"code-team\",\n *   goal: \"Ship a tested module that passes review.\",\n *   manager: techLeadRouter,\n *   members: { builder, reviewer, fixer },\n *   gate: \"quality\",\n *   output: v.object({ code: v.string() }),\n *   maxIterations: 6,\n * });\n *\n * const { data, report } = await codeTeam.execute(\"Build a debounce<T> utility.\");\n */\nexport function team<\n  TOutput = unknown,\n  TState = TOutput,\n  TMembers extends Record<string, TeamMemberValue> = Record<string, TeamMemberValue>,\n>(config: TeamConfig<TOutput, TState, TMembers>): SupervisorContract<TOutput> {\n  const supervisorConfig: SupervisorConfig<TOutput, TState> = {\n    name: config.name,\n    version: config.version,\n    // Stamp the report/result discriminator as \"team\" so team runs are\n    // distinguishable on the wire (Panoptic groups/filters them as their\n    // own type) — the only behavioural difference from a plain supervisor.\n    reportType: \"team\",\n    intents: config.members as unknown as Record<string, SupervisorIntentValue>,\n    evaluate: resolveGate<TOutput, TState, TMembers>(config),\n    goal: config.goal,\n    output: config.output,\n    state: config.state,\n    maxIterations: config.maxIterations,\n    snapshotStore: config.snapshotStore,\n    on: config.on,\n    // Forward observability verbatim — the supervisor `team()` returns\n    // routes its report through the generic Observer seam, so a team\n    // inherits observation with no team-specific wiring (F1/F3).\n    observe: config.observe,\n  };\n\n  // Manager → `route` XOR `router`. Reuse the supervisor's own XOR\n  // validation; team() forwards exactly one of the two, so a malformed\n  // manager surfaces the existing SupervisorFailedError downstream.\n  if (isRouteManager(config.manager)) {\n    supervisorConfig.route = config.manager.route;\n  } else {\n    supervisorConfig.router = config.manager;\n  }\n\n  return supervisor<TOutput, TState>(supervisorConfig);\n}\n\n/**\n * Resolve the team's `gate` into a concrete `evaluate` callback. A\n * function forwards untouched; a {@link TeamGate} string is validated\n * against `members` and desugared into the matching pre-built gate.\n */\nfunction resolveGate<\n  TOutput,\n  TState,\n  TMembers extends Record<string, TeamMemberValue>,\n>(\n  config: TeamConfig<TOutput, TState, TMembers>,\n): (ctx: EvaluateContext<TState>) => EvaluateResult | Promise<EvaluateResult> {\n  if (typeof config.gate === \"function\") {\n    return config.gate as TeamGateFn<TState>;\n  }\n\n  const gate: TeamGate = config.gate;\n  const fixerRole = config.roles?.fixer ?? \"fixer\";\n\n  assertMemberExists(config, fixerRole, \"fixer\");\n\n  if (gate === \"quality\") {\n    const reviewerRole = config.roles?.reviewer ?? \"reviewer\";\n\n    assertMemberExists(config, reviewerRole, \"reviewer\");\n\n    const gateKey = config.gateKey ?? \"approved\";\n\n    return buildQualityGate<TState>(gateKey, fixerRole);\n  }\n\n  const gateKey = config.gateKey ?? \"passed\";\n\n  return buildVerifyGate<TState>(gateKey, fixerRole);\n}\n\n/**\n * Construction-time guard: assert the resolved role key exists in\n * `members`, throwing an authoring-style {@link SupervisorFailedError}\n * (tagged `authoring: true`) listing the missing role when it doesn't.\n */\nfunction assertMemberExists<\n  TOutput,\n  TState,\n  TMembers extends Record<string, TeamMemberValue>,\n>(\n  config: TeamConfig<TOutput, TState, TMembers>,\n  role: string,\n  label: string,\n): void {\n  if (!Object.prototype.hasOwnProperty.call(config.members, role)) {\n    throw new SupervisorFailedError(\n      `ai.team(\"${config.name}\"): gate \"${config.gate as string}\" needs a \"${label}\" member but no \\`members.${role}\\` key exists`,\n      { context: { authoring: true } },\n    );\n  }\n}\n\n/**\n * Discriminate the `manager` union: `true` when it is the deterministic\n * `{ route }` form, `false` for a bare `AgentContract` / `RouterEntry`.\n */\nfunction isRouteManager<TOutput, TState>(\n  manager: TeamConfig<TOutput, TState>[\"manager\"],\n): manager is { route: NonNullable<SupervisorConfig<TOutput, TState>[\"route\"]> } {\n  return (\n    typeof manager === \"object\" &&\n    manager !== null &&\n    \"route\" in manager &&\n    typeof (manager as { route?: unknown }).route === \"function\"\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmDA,SAAgB,KAId,QAA4E;CAC5E,MAAM,mBAAsD;EAC1D,MAAM,OAAO;EACb,SAAS,OAAO;EAIhB,YAAY;EACZ,SAAS,OAAO;EAChB,UAAU,YAAuC,MAAM;EACvD,MAAM,OAAO;EACb,QAAQ,OAAO;EACf,OAAO,OAAO;EACd,eAAe,OAAO;EACtB,eAAe,OAAO;EACtB,IAAI,OAAO;EAIX,SAAS,OAAO;CAClB;CAKA,IAAI,eAAe,OAAO,OAAO,GAC/B,iBAAiB,QAAQ,OAAO,QAAQ;MAExC,iBAAiB,SAAS,OAAO;CAGnC,OAAO,WAA4B,gBAAgB;AACrD;;;;;;AAOA,SAAS,YAKP,QAC4E;CAC5E,IAAI,OAAO,OAAO,SAAS,YACzB,OAAO,OAAO;CAGhB,MAAM,OAAiB,OAAO;CAC9B,MAAM,YAAY,OAAO,OAAO,SAAS;CAEzC,mBAAmB,QAAQ,WAAW,OAAO;CAE7C,IAAI,SAAS,WAAW;EAGtB,mBAAmB,QAFE,OAAO,OAAO,YAAY,YAEN,UAAU;EAInD,OAAO,iBAFS,OAAO,WAAW,YAEO,SAAS;CACpD;CAIA,OAAO,gBAFS,OAAO,WAAW,UAEM,SAAS;AACnD;;;;;;AAOA,SAAS,mBAKP,QACA,MACA,OACM;CACN,IAAI,CAAC,OAAO,UAAU,eAAe,KAAK,OAAO,SAAS,IAAI,GAC5D,MAAM,IAAI,sBACR,YAAY,OAAO,KAAK,YAAY,OAAO,KAAe,aAAa,MAAM,4BAA4B,KAAK,gBAC9G,EAAE,SAAS,EAAE,WAAW,KAAK,EAAE,CACjC;AAEJ;;;;;AAMA,SAAS,eACP,SAC+E;CAC/E,OACE,OAAO,YAAY,YACnB,YAAY,QACZ,WAAW,WACX,OAAQ,QAAgC,UAAU;AAEtD"}

package/esm/tool/executable-as-tool.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"executable-as-tool.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/tool/executable-as-tool.ts"],"mappings":";;;;;;;;;;AAK4D;;;;KASvD,kBAAA,YAA8B,UAAA;EACjC,IAAA,GAAO,OAAA;EACP,KAAA,GAAQ,OAAA;EACR,MAAA,EAAQ,UAAA;AAAA;;;;;;;;;;AAAU;AAsBpB;;;;;;;;;KAAY,cAAA;EAAA,SACD,IAAA;EAAA,SACA,WAAA;EAAA,SACA,WAAA,GAAc,gBAAA,CAAiB,MAAA;EACxC,OAAA,CAAQ,KAAA,EAAO,MAAA,EAAQ,OAAA,aAAoB,OAAA,CAAQ,kBAAA,CAAmB,OAAA;EACtE,MAAA;AAAA;;;;;;;KASU,cAAA,wCACR,YAAA,CAAa,MAAA,EAAQ,OAAA,IACrB,cAAA,CAAe,MAAA,EAAQ,OAAA;;;;;AAXnB;AASR;;iBA4BgB,gBAAA,CAAiB,KAAA,YAAiB,KAAA,IAAS,cAAc;;;;;;;;;;;;;;iBAuBzD,gBAAA,kBACd,UAAA,EAAY,cAAA,CAAe,MAAA,EAAQ,OAAA,IAClC,YAAA,CAAa,MAAA,EAAQ,OAAA;;;;AAnDU;AA0BlC;;;;;iBAmEgB,mBAAA,CACd,KAAA,EAAO,aAAA,CAAc,cAAA,gBACpB,YAAA"}
+{"version":3,"file":"executable-as-tool.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/tool/executable-as-tool.ts"],"mappings":";;;;;;;;;;AAK4D;;;;KASvD,kBAAA,YAA8B,UAAA;EACjC,IAAA,GAAO,OAAA;EACP,KAAA,GAAQ,OAAA;EACR,MAAA,EAAQ,UAAA;AAAA;;;;;;;;;;AAAU;AAsBpB;;;;;;;;;KAAY,cAAA;EAAA,SACD,IAAA;EAAA,SACA,WAAA;EAAA,SACA,WAAA,GAAc,gBAAA,CAAiB,MAAA;EACxC,OAAA,CAAQ,KAAA,EAAO,MAAA,EAAQ,OAAA,aAAoB,OAAA,CAAQ,kBAAA,CAAmB,OAAA;EACtE,MAAA;AAAA;;;;;;;KASU,cAAA,wCACR,YAAA,CAAa,MAAA,EAAQ,OAAA,IACrB,cAAA,CAAe,MAAA,EAAQ,OAAA;;;;;AAXnB;AASR;;iBA4BgB,gBAAA,CAAiB,KAAA,YAAiB,KAAA,IAAS,cAAc;;;;;;;;;;;;;;iBAuBzD,gBAAA,kBACd,UAAA,EAAY,cAAA,CAAe,MAAA,EAAQ,OAAA,IAClC,YAAA,CAAa,MAAA,EAAQ,OAAA;;;;AAnDU;AA0BlC;;;;;iBA0EgB,mBAAA,CACd,KAAA,EAAO,aAAA,CAAc,cAAA,gBACpB,YAAA"}

package/esm/tool/executable-as-tool.mjs

@@ -48,8 +48,8 @@ function executableToTool(executable) {
 		name: executable.name,
 		description: executable.description ?? `Invoke "${executable.name}" as a tool.`,
 		input: executable.inputSchema ?? passthroughSchema(),
-		execute: async (input) => {
-			const result = await executable.execute(input);
+		execute: async (input, ctx) => {
+			const result = await executable.execute(input, ctx?.signal ? { signal: ctx.signal } : void 0);
 			if (result.error) throw result.error;
 			return {
 				data: result.data,

package/esm/tool/executable-as-tool.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"executable-as-tool.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/tool/executable-as-tool.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport type { BaseReport } from \"../contracts/result/base-report.type\";\nimport type { BaseResult } from \"../contracts/result/base-result.type\";\nimport type { Usage } from \"../contracts/result/usage.type\";\nimport { AgentExecutionError, type AIError } from \"../errors\";\nimport { compositeAsTool, type ToolContract } from \"./tool\";\n\n/**\n * Envelope every executable's `execute()` resolves to. Agent, workflow,\n * and supervisor results all satisfy this shape — `data` / `error`\n * carry the outcome while `usage` and `report` are always present —\n * which is exactly what {@link compositeAsTool} needs to nest the inner\n * run under the outer tool-call node.\n */\ntype ExecutableEnvelope<TOutput> = BaseResult & {\n  data?: TOutput;\n  error?: AIError;\n  report: BaseReport;\n};\n\n/**\n * Structural view of an executable primitive (agent / workflow /\n * supervisor) when it is dropped straight into an agent's `tools: []`\n * array WITHOUT being wrapped via `.asTool()` first.\n *\n * Only the fields the auto-adapt path reads are declared:\n * - `name` — becomes the LLM tool name (required; anonymous executables\n *   are rejected at author time, mirroring `.asTool()`).\n * - `description` — the \"when would the model pick this?\" line.\n * - `inputSchema` — opt-in Standard Schema typing the tool's arguments.\n *   Surfaced on `WorkflowInstance` / `SupervisorContract` from the new\n *   optional `inputSchema` config field. Absent for agents (which take\n *   a plain string prompt).\n * - `execute` — the dispatch entry every `ExecutableContract` exposes.\n *\n * `invoke` is declared `never` so a `ToolContract` (which HAS `invoke`)\n * can never be mistaken for an executable by the {@link isExecutableTool}\n * guard.\n */\nexport type ExecutableTool<TInput = unknown, TOutput = unknown> = {\n  readonly name: string;\n  readonly description?: string;\n  readonly inputSchema?: StandardSchemaV1<TInput>;\n  execute(input: TInput, options?: unknown): Promise<ExecutableEnvelope<TOutput>>;\n  invoke?: never;\n};\n\n/**\n * Entry accepted in an agent's `tools: []` array — either an already-\n * built `ToolContract` (the `.asTool()` / `ai.tool()` path) or a raw\n * executable primitive the framework auto-adapts on the caller's\n * behalf.\n */\nexport type AgentToolEntry<TInput = unknown, TOutput = unknown> =\n  | ToolContract<TInput, TOutput>\n  | ExecutableTool<TInput, TOutput>;\n\n/**\n * Identity passthrough schema used when an executable is registered as\n * a tool without declaring an `inputSchema`. The model's raw arguments\n * flow straight to `execute()` unchanged — the executable validates\n * internally (workflows via their steps, supervisors/agents via their\n * own input handling).\n */\nfunction passthroughSchema<TInput>(): StandardSchemaV1<TInput> {\n  return {\n    \"~standard\": {\n      version: 1,\n      vendor: \"warlock-ai\",\n      validate: (value: unknown) => ({ value: value as TInput }),\n    },\n  };\n}\n\n/**\n * Type guard distinguishing a raw executable primitive from a built\n * `ToolContract`. An executable exposes `execute()` and no `invoke()`;\n * a `ToolContract` exposes `invoke()`. The `invoke` check is the\n * load-bearing discriminator — `.asTool()`-wrapped composites keep\n * their own `execute` too, so checking `execute` alone is insufficient.\n */\nexport function isExecutableTool(entry: unknown): entry is ExecutableTool {\n  if (!entry || typeof entry !== \"object\") {\n    return false;\n  }\n\n  const candidate = entry as { execute?: unknown; invoke?: unknown };\n\n  return typeof candidate.execute === \"function\" && typeof candidate.invoke !== \"function\";\n}\n\n/**\n * Adapt a raw executable primitive (agent / workflow / supervisor) into\n * a `ToolContract` so an agent can dispatch it inside its tool-call\n * loop WITHOUT the caller writing `.asTool()`. Derives the LLM tool\n * manifest from the executable's own `name` + `description` +\n * (optional) `inputSchema`, then dispatches through the executable's\n * `execute()` — the inner report nests under the outer tool-call node\n * exactly like an explicit `.asTool()` wrapper.\n *\n * Throws `AgentExecutionError` at author time when the executable lacks\n * a usable `name` — the agent's tool surface needs a stable id, the\n * same constraint `.asTool()` enforces.\n */\nexport function executableToTool<TInput, TOutput>(\n  executable: ExecutableTool<TInput, TOutput>,\n): ToolContract<TInput, TOutput> {\n  if (!executable.name || typeof executable.name !== \"string\") {\n    throw new AgentExecutionError(\n      \"tools[]: an executable (agent/workflow/supervisor) used as a tool must have a `name`\",\n      { context: { authoring: true } },\n    );\n  }\n\n  return compositeAsTool<TInput, TOutput>({\n    name: executable.name,\n    description: executable.description ?? `Invoke \"${executable.name}\" as a tool.`,\n    input: executable.inputSchema ?? passthroughSchema<TInput>(),\n    execute: async (input) => {\n      const result = await executable.execute(input);\n\n      if (result.error) {\n        // Surface the inner typed error so the surrounding\n        // `compositeAsTool` wrapper produces a `ToolExecutionError`\n        // with `cause` pointing back at the original subclass — the\n        // agent's tool-call loop sees one uniform error class\n        // regardless of which primitive failed.\n        throw result.error;\n      }\n\n      return {\n        data: result.data as TOutput,\n        usage: result.usage as Usage,\n        report: result.report,\n      };\n    },\n  });\n}\n\n/**\n * Normalize an agent's `tools: []` array into a uniform\n * `ToolContract[]` for the runtime. Already-built `ToolContract`s\n * (`.asTool()` / `ai.tool()`) pass through untouched; raw executable\n * primitives are auto-adapted via {@link executableToTool}.\n *\n * Returns `undefined` when no tools were supplied so the agent's\n * existing `config.tools ?? []` fallbacks stay byte-identical.\n */\nexport function normalizeAgentTools(\n  tools: ReadonlyArray<AgentToolEntry> | undefined,\n): ToolContract<unknown, unknown>[] | undefined {\n  if (!tools) {\n    return undefined;\n  }\n\n  return tools.map((entry) => {\n    if (isExecutableTool(entry)) {\n      return executableToTool(entry) as ToolContract<unknown, unknown>;\n    }\n\n    return entry as ToolContract<unknown, unknown>;\n  });\n}\n"],"mappings":";;;;;;;;;;;;AAgEA,SAAS,oBAAsD;CAC7D,OAAO,EACL,aAAa;EACX,SAAS;EACT,QAAQ;EACR,WAAW,WAAoB,EAAS,MAAgB;CAC1D,EACF;AACF;;;;;;;;AASA,SAAgB,iBAAiB,OAAyC;CACxE,IAAI,CAAC,SAAS,OAAO,UAAU,UAC7B,OAAO;CAGT,MAAM,YAAY;CAElB,OAAO,OAAO,UAAU,YAAY,cAAc,OAAO,UAAU,WAAW;AAChF;;;;;;;;;;;;;;AAeA,SAAgB,iBACd,YAC+B;CAC/B,IAAI,CAAC,WAAW,QAAQ,OAAO,WAAW,SAAS,UACjD,MAAM,IAAI,oBACR,wFACA,EAAE,SAAS,EAAE,WAAW,KAAK,EAAE,CACjC;CAGF,OAAO,gBAAiC;EACtC,MAAM,WAAW;EACjB,aAAa,WAAW,eAAe,WAAW,WAAW,KAAK;EAClE,OAAO,WAAW,eAAe,kBAA0B;EAC3D,SAAS,OAAO,UAAU;GACxB,MAAM,SAAS,MAAM,WAAW,QAAQ,KAAK;GAE7C,IAAI,OAAO,OAMT,MAAM,OAAO;GAGf,OAAO;IACL,MAAM,OAAO;IACb,OAAO,OAAO;IACd,QAAQ,OAAO;GACjB;EACF;CACF,CAAC;AACH;;;;;;;;;;AAWA,SAAgB,oBACd,OAC8C;CAC9C,IAAI,CAAC,OACH;CAGF,OAAO,MAAM,KAAK,UAAU;EAC1B,IAAI,iBAAiB,KAAK,GACxB,OAAO,iBAAiB,KAAK;EAG/B,OAAO;CACT,CAAC;AACH"}
+{"version":3,"file":"executable-as-tool.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/tool/executable-as-tool.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport type { BaseReport } from \"../contracts/result/base-report.type\";\nimport type { BaseResult } from \"../contracts/result/base-result.type\";\nimport type { Usage } from \"../contracts/result/usage.type\";\nimport { AgentExecutionError, type AIError } from \"../errors\";\nimport { compositeAsTool, type ToolContract } from \"./tool\";\n\n/**\n * Envelope every executable's `execute()` resolves to. Agent, workflow,\n * and supervisor results all satisfy this shape — `data` / `error`\n * carry the outcome while `usage` and `report` are always present —\n * which is exactly what {@link compositeAsTool} needs to nest the inner\n * run under the outer tool-call node.\n */\ntype ExecutableEnvelope<TOutput> = BaseResult & {\n  data?: TOutput;\n  error?: AIError;\n  report: BaseReport;\n};\n\n/**\n * Structural view of an executable primitive (agent / workflow /\n * supervisor) when it is dropped straight into an agent's `tools: []`\n * array WITHOUT being wrapped via `.asTool()` first.\n *\n * Only the fields the auto-adapt path reads are declared:\n * - `name` — becomes the LLM tool name (required; anonymous executables\n *   are rejected at author time, mirroring `.asTool()`).\n * - `description` — the \"when would the model pick this?\" line.\n * - `inputSchema` — opt-in Standard Schema typing the tool's arguments.\n *   Surfaced on `WorkflowInstance` / `SupervisorContract` from the new\n *   optional `inputSchema` config field. Absent for agents (which take\n *   a plain string prompt).\n * - `execute` — the dispatch entry every `ExecutableContract` exposes.\n *\n * `invoke` is declared `never` so a `ToolContract` (which HAS `invoke`)\n * can never be mistaken for an executable by the {@link isExecutableTool}\n * guard.\n */\nexport type ExecutableTool<TInput = unknown, TOutput = unknown> = {\n  readonly name: string;\n  readonly description?: string;\n  readonly inputSchema?: StandardSchemaV1<TInput>;\n  execute(input: TInput, options?: unknown): Promise<ExecutableEnvelope<TOutput>>;\n  invoke?: never;\n};\n\n/**\n * Entry accepted in an agent's `tools: []` array — either an already-\n * built `ToolContract` (the `.asTool()` / `ai.tool()` path) or a raw\n * executable primitive the framework auto-adapts on the caller's\n * behalf.\n */\nexport type AgentToolEntry<TInput = unknown, TOutput = unknown> =\n  | ToolContract<TInput, TOutput>\n  | ExecutableTool<TInput, TOutput>;\n\n/**\n * Identity passthrough schema used when an executable is registered as\n * a tool without declaring an `inputSchema`. The model's raw arguments\n * flow straight to `execute()` unchanged — the executable validates\n * internally (workflows via their steps, supervisors/agents via their\n * own input handling).\n */\nfunction passthroughSchema<TInput>(): StandardSchemaV1<TInput> {\n  return {\n    \"~standard\": {\n      version: 1,\n      vendor: \"warlock-ai\",\n      validate: (value: unknown) => ({ value: value as TInput }),\n    },\n  };\n}\n\n/**\n * Type guard distinguishing a raw executable primitive from a built\n * `ToolContract`. An executable exposes `execute()` and no `invoke()`;\n * a `ToolContract` exposes `invoke()`. The `invoke` check is the\n * load-bearing discriminator — `.asTool()`-wrapped composites keep\n * their own `execute` too, so checking `execute` alone is insufficient.\n */\nexport function isExecutableTool(entry: unknown): entry is ExecutableTool {\n  if (!entry || typeof entry !== \"object\") {\n    return false;\n  }\n\n  const candidate = entry as { execute?: unknown; invoke?: unknown };\n\n  return typeof candidate.execute === \"function\" && typeof candidate.invoke !== \"function\";\n}\n\n/**\n * Adapt a raw executable primitive (agent / workflow / supervisor) into\n * a `ToolContract` so an agent can dispatch it inside its tool-call\n * loop WITHOUT the caller writing `.asTool()`. Derives the LLM tool\n * manifest from the executable's own `name` + `description` +\n * (optional) `inputSchema`, then dispatches through the executable's\n * `execute()` — the inner report nests under the outer tool-call node\n * exactly like an explicit `.asTool()` wrapper.\n *\n * Throws `AgentExecutionError` at author time when the executable lacks\n * a usable `name` — the agent's tool surface needs a stable id, the\n * same constraint `.asTool()` enforces.\n */\nexport function executableToTool<TInput, TOutput>(\n  executable: ExecutableTool<TInput, TOutput>,\n): ToolContract<TInput, TOutput> {\n  if (!executable.name || typeof executable.name !== \"string\") {\n    throw new AgentExecutionError(\n      \"tools[]: an executable (agent/workflow/supervisor) used as a tool must have a `name`\",\n      { context: { authoring: true } },\n    );\n  }\n\n  return compositeAsTool<TInput, TOutput>({\n    name: executable.name,\n    description: executable.description ?? `Invoke \"${executable.name}\" as a tool.`,\n    input: executable.inputSchema ?? passthroughSchema<TInput>(),\n    execute: async (input, ctx) => {\n      // Relay the outer run's cancellation signal so a cancelled parent\n      // aborts this nested agent/workflow/supervisor (C2). Omit the\n      // options object entirely when there's no signal so primitives that\n      // treat any second arg as meaningful stay byte-identical.\n      const result = await executable.execute(\n        input,\n        ctx?.signal ? { signal: ctx.signal } : undefined,\n      );\n\n      if (result.error) {\n        // Surface the inner typed error so the surrounding\n        // `compositeAsTool` wrapper produces a `ToolExecutionError`\n        // with `cause` pointing back at the original subclass — the\n        // agent's tool-call loop sees one uniform error class\n        // regardless of which primitive failed.\n        throw result.error;\n      }\n\n      return {\n        data: result.data as TOutput,\n        usage: result.usage as Usage,\n        report: result.report,\n      };\n    },\n  });\n}\n\n/**\n * Normalize an agent's `tools: []` array into a uniform\n * `ToolContract[]` for the runtime. Already-built `ToolContract`s\n * (`.asTool()` / `ai.tool()`) pass through untouched; raw executable\n * primitives are auto-adapted via {@link executableToTool}.\n *\n * Returns `undefined` when no tools were supplied so the agent's\n * existing `config.tools ?? []` fallbacks stay byte-identical.\n */\nexport function normalizeAgentTools(\n  tools: ReadonlyArray<AgentToolEntry> | undefined,\n): ToolContract<unknown, unknown>[] | undefined {\n  if (!tools) {\n    return undefined;\n  }\n\n  return tools.map((entry) => {\n    if (isExecutableTool(entry)) {\n      return executableToTool(entry) as ToolContract<unknown, unknown>;\n    }\n\n    return entry as ToolContract<unknown, unknown>;\n  });\n}\n"],"mappings":";;;;;;;;;;;;AAgEA,SAAS,oBAAsD;CAC7D,OAAO,EACL,aAAa;EACX,SAAS;EACT,QAAQ;EACR,WAAW,WAAoB,EAAS,MAAgB;CAC1D,EACF;AACF;;;;;;;;AASA,SAAgB,iBAAiB,OAAyC;CACxE,IAAI,CAAC,SAAS,OAAO,UAAU,UAC7B,OAAO;CAGT,MAAM,YAAY;CAElB,OAAO,OAAO,UAAU,YAAY,cAAc,OAAO,UAAU,WAAW;AAChF;;;;;;;;;;;;;;AAeA,SAAgB,iBACd,YAC+B;CAC/B,IAAI,CAAC,WAAW,QAAQ,OAAO,WAAW,SAAS,UACjD,MAAM,IAAI,oBACR,wFACA,EAAE,SAAS,EAAE,WAAW,KAAK,EAAE,CACjC;CAGF,OAAO,gBAAiC;EACtC,MAAM,WAAW;EACjB,aAAa,WAAW,eAAe,WAAW,WAAW,KAAK;EAClE,OAAO,WAAW,eAAe,kBAA0B;EAC3D,SAAS,OAAO,OAAO,QAAQ;GAK7B,MAAM,SAAS,MAAM,WAAW,QAC9B,OACA,KAAK,SAAS,EAAE,QAAQ,IAAI,OAAO,IAAI,MACzC;GAEA,IAAI,OAAO,OAMT,MAAM,OAAO;GAGf,OAAO;IACL,MAAM,OAAO;IACb,OAAO,OAAO;IACd,QAAQ,OAAO;GACjB;EACF;CACF,CAAC;AACH;;;;;;;;;;AAWA,SAAgB,oBACd,OAC8C;CAC9C,IAAI,CAAC,OACH;CAGF,OAAO,MAAM,KAAK,UAAU;EAC1B,IAAI,iBAAiB,KAAK,GACxB,OAAO,iBAAiB,KAAK;EAG/B,OAAO;CACT,CAAC;AACH"}

package/esm/tool/tool.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"tool.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/tool/tool.ts"],"mappings":";;;;;;;;;;AAwCA;;;;;;;;;;;;;;;;;KAAY,gBAAA;EAQQ,iFANlB,IAAA,GAAO,OAAA,EAgBQ;EAdf,KAAA,GAAQ,OAAA,EAcmB;EAZ3B,KAAA,EAAO,KAAA,EAcP;EAZA,MAAA,EAAQ,UAAA;AAAA;;;;;;;;UAUO,YAAA,8CAA0D,UAAA,CACzE,MAAA,EACA,OAAA;EADA;;;;;;;;;;AAoB8E;AAuJhF;;;;;;EAvJE,MAAA,CAAO,QAAA,WAAmB,GAAA,GAAM,WAAA,GAAc,OAAA,CAAQ,gBAAA,CAAiB,OAAA;AAAA;AAAA,iBAuJzD,IAAA,kBACd,QAAA,EAAU,UAAA,CAAW,MAAA,EAAQ,OAAA,IAC5B,YAAA,CAAa,MAAA,EAAQ,OAAA"}
+{"version":3,"file":"tool.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/tool/tool.ts"],"mappings":";;;;;;;;;;AAwCA;;;;;;;;;;;;;;;;;KAAY,gBAAA;EAQQ,iFANlB,IAAA,GAAO,OAAA,EAgBQ;EAdf,KAAA,GAAQ,OAAA,EAcmB;EAZ3B,KAAA,EAAO,KAAA,EAcP;EAZA,MAAA,EAAQ,UAAA;AAAA;;;;;;;;UAUO,YAAA,8CAA0D,UAAA,CACzE,MAAA,EACA,OAAA;EADA;;;;;;;;;;AAoB8E;AA6JhF;;;;;;EA7JE,MAAA,CAAO,QAAA,WAAmB,GAAA,GAAM,WAAA,GAAc,OAAA,CAAQ,gBAAA,CAAiB,OAAA;AAAA;AAAA,iBA6JzD,IAAA,kBACd,QAAA,EAAU,UAAA,CAAW,MAAA,EAAQ,OAAA,IAC5B,YAAA,CAAa,MAAA,EAAQ,OAAA"}

package/esm/tool/tool.mjs

@@ -66,7 +66,7 @@ function compositeAsTool(contract) {
 		meta: contract.meta,
 		input: contract.input,
 		execute: publicExecute,
-		async invoke(rawInput, _ctx) {
+		async invoke(rawInput, ctx) {
 			const startedAtDate = /* @__PURE__ */ new Date();
 			const start = performance.now();
 			const runId = generateRunId("tool");
@@ -106,7 +106,7 @@ function compositeAsTool(contract) {
 				context: { toolName: contract.name }
 			}));
 			try {
-				const composite = await contract.execute(validationResult.value);
+				const composite = await contract.execute(validationResult.value, ctx);
 				return {
 					data: composite.data,
 					error: composite.error,

package/esm/tool/tool.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"tool.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/tool/tool.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport type { BaseReport } from \"../contracts/result/base-report.type\";\nimport type { Usage } from \"../contracts/result/usage.type\";\nimport type { ToolConfig, ToolContext } from \"../contracts/tool.contract\";\nimport { AIError, SchemaValidationError, ToolExecutionError } from \"../errors\";\nimport { generateRunId } from \"../utils/generate-run-id\";\n\n/**\n * Degraded `ToolContext` supplied when no caller threads one through\n * (`tool.invoke(input)` standalone, batch scripts, tests). Per\n * decisions §35 — mutations on the empty bag are harmless no-ops;\n * production paths under a supervisor receive a real ctx with the\n * iteration's shared bag.\n */\nfunction defaultToolContext(): ToolContext {\n  return { artifacts: {} };\n}\n\nconst EMPTY_USAGE: Usage = Object.freeze({ input: 0, output: 0, total: 0 });\n\n/**\n * Result returned by `ToolContract.invoke()`.\n *\n * **Canonical destructure:** `const { data, usage, report, error }` —\n * matches every other executable (`AgentResult`, `WorkflowResult`,\n * `SupervisorResult`) so parent agents can treat every tool dispatch\n * uniformly.\n *\n * **Shape.** `data` / `error` carry the outcome; `usage` and `report`\n * are always present. For leaf tools, `usage` is zero and `report`\n * is a framework-synthesized {@link BaseReport} (`type: \"tool\"`,\n * `children: []`, real timing) so parents never have to nil-check.\n * For composites wrapped via `asTool()`, `usage` and `report` mirror\n * the inner primitive's — the nested tree lives in `report.children`.\n *\n * @example\n * const result = await myTool.invoke({ city: \"Cairo\" });\n * if (result.error) console.error(result.error.message);\n * else console.log(result.data, result.report.duration);\n */\nexport type ToolInvokeResult<TOutput> = {\n  /** Successfully-returned output. Undefined if execution or validation failed. */\n  data?: TOutput;\n  /** Typed AI error produced by validation or execute(), if any. */\n  error?: AIError;\n  /** Rolled-up usage (zero for leaf tools, populated for composites). */\n  usage: Usage;\n  /** Recursive execution report — `report.children` carries nested executables. */\n  report: BaseReport;\n};\n\n/**\n * A `ToolConfig` augmented with a safe `invoke()` entry point for the agent runtime.\n *\n * @example\n * const wrapped: ToolContract<{ city: string }, { temp: number }> = tool(contract);\n * const result = await wrapped.invoke({ city: \"Cairo\" });\n */\nexport interface ToolContract<TInput = unknown, TOutput = unknown> extends ToolConfig<\n  TInput,\n  TOutput\n> {\n  /**\n   * Agent-runtime entry point. Validates raw input against the tool's schema,\n   * calls execute(), catches errors, and reports duration.\n   * Never throws — errors surface in the returned `error` field as\n   * typed `AIError` subclasses.\n   *\n   * The optional second argument is a `ToolContext` (Phase 5 /\n   * decisions §35) — when supplied, threaded into `execute(input, ctx)`\n   * so tools can write system-only side data into `ctx.artifacts`.\n   * Standalone callers may omit it; the framework supplies a\n   * degraded `{ artifacts: {} }` so single-arg legacy handlers keep\n   * working unchanged.\n   *\n   * @example\n   * const result = await myTool.invoke(rawLLMArgs);\n   * if (result.error) handleError(result.error);\n   */\n  invoke(rawInput: unknown, ctx?: ToolContext): Promise<ToolInvokeResult<TOutput>>;\n}\n\n/**\n * Wraps a raw `ToolConfig` and adds a safe `invoke()` method for the agent runtime.\n * The returned object preserves all original contract fields unchanged.\n *\n * Error categorization:\n * - Input schema rejects model args → `SchemaValidationError` (issues preserved).\n * - Schema's `validate()` itself throws → `SchemaValidationError` wrapping the cause.\n * - `execute()` throws → `ToolExecutionError` wrapping the cause.\n *\n * @example\n * const weatherTool = tool({\n *   name: \"getWeather\",\n *   description: \"Fetch current weather for a city\",\n *   input: z.object({ city: z.string() }),\n *   execute: async ({ city }) => ({ temp: 72 }),\n * });\n *\n * const result = await weatherTool.invoke({ city: \"Cairo\" });\n */\n/**\n * Internal factory for `asTool()` wrappers on composite primitives\n * (agent / workflow / supervisor). Unlike the public `tool()` factory\n * (which synthesizes a leaf `BaseReport` every time), this variant\n * lets the composite's own `ExecuteResult` flow through: the inner\n * primitive's `report` becomes the sole child of the outer tool-call\n * node, and the inner `usage` is surfaced so parents can roll it up.\n *\n * The caller supplies `execute()` returning `{ data, usage, report }`\n * from the composite's own `execute()` method. Validation failures\n * and thrown errors still produce a synthesized failed leaf report —\n * the inner-report propagation is strictly a success-path concern.\n *\n * Not exported from the package barrel — used by `agent.asTool()`,\n * `workflow.asTool()`, `supervisor.asTool()` only.\n */\nexport function compositeAsTool<TInput, TOutput>(contract: {\n  name: string;\n  description?: string;\n  version?: string;\n  meta?: ToolConfig[\"meta\"];\n  input: StandardSchemaV1<TInput>;\n  /** Runs the underlying composite and returns its full envelope. */\n  execute: (input: TInput) => Promise<{\n    data?: TOutput;\n    error?: AIError;\n    usage: Usage;\n    report: BaseReport;\n  }>;\n}): ToolContract<TInput, TOutput> {\n  // The underlying `ToolConfig<TInput, TOutput>.execute` is typed as\n  // `(input) => Promise<TOutput>`, but composite wrappers return an\n  // envelope object instead. Surface a contract-shaped view that\n  // extracts `.data` on demand for any code that still treats this\n  // like a plain tool.\n  const publicExecute = async (input: TInput): Promise<TOutput> => {\n    const envelope = await contract.execute(input);\n    if (envelope.error) throw envelope.error;\n    return envelope.data as TOutput;\n  };\n\n  return {\n    name: contract.name,\n    description: contract.description ?? `Composite tool \"${contract.name}\".`,\n    meta: contract.meta,\n    input: contract.input,\n    execute: publicExecute,\n\n    async invoke(rawInput: unknown, _ctx?: ToolContext): Promise<ToolInvokeResult<TOutput>> {\n      // Composite tools (asTool-wrapped agent/workflow/supervisor) do\n      // NOT relay the ctx into their inner execution — composites\n      // have their own state/scope; an inner supervisor gets a fresh\n      // artifacts bag. The parameter is accepted for signature parity\n      // with `tool()` so callers can use both interchangeably.\n      const startedAtDate = new Date();\n      const start = performance.now();\n      const runId = generateRunId(\"tool\");\n\n      const failLeaf = (error: AIError): ToolInvokeResult<TOutput> => {\n        const endedAt = new Date().toISOString();\n        const duration = performance.now() - start;\n        return {\n          error,\n          usage: EMPTY_USAGE,\n          report: {\n            runId,\n            rootRunId: runId,\n            name: contract.name,\n            version: contract.version,\n            type: \"tool\",\n            status: \"failed\",\n            startedAt: startedAtDate.toISOString(),\n            endedAt,\n            duration,\n            usage: EMPTY_USAGE,\n            children: [],\n          },\n        };\n      };\n\n      let validationResult: StandardSchemaV1.Result<TInput>;\n      try {\n        const schema = contract.input as StandardSchemaV1<TInput>;\n        validationResult = await schema[\"~standard\"].validate(rawInput);\n      } catch (thrown) {\n        const message = thrown instanceof Error ? thrown.message : String(thrown);\n        return failLeaf(\n          new SchemaValidationError(\n            `Schema validation threw for tool \"${contract.name}\": ${message}`,\n            { cause: thrown, context: { toolName: contract.name } },\n          ),\n        );\n      }\n\n      if (validationResult.issues) {\n        const summary = validationResult.issues.map((issue) => issue.message).join(\"; \");\n        return failLeaf(\n          new SchemaValidationError(`Validation failed: ${summary}`, {\n            issues: validationResult.issues,\n            context: { toolName: contract.name },\n          }),\n        );\n      }\n\n      try {\n        const composite = await contract.execute(validationResult.value);\n        // Surface the inner primitive's full envelope. The outer\n        // ToolInvokeResult carries the composite's usage and report\n        // verbatim; the agent runtime nests the report as a child of\n        // the tool-dispatch node it records.\n        return {\n          data: composite.data,\n          error: composite.error,\n          usage: composite.usage,\n          report: composite.report,\n        };\n      } catch (thrown) {\n        const message = thrown instanceof Error ? thrown.message : String(thrown);\n        return failLeaf(\n          new ToolExecutionError(message, {\n            cause: thrown,\n            toolName: contract.name,\n          }),\n        );\n      }\n    },\n  };\n}\n\nexport function tool<TInput, TOutput>(\n  contract: ToolConfig<TInput, TOutput>,\n): ToolContract<TInput, TOutput> {\n  return {\n    ...contract,\n\n    async invoke(rawInput: unknown, ctx?: ToolContext): Promise<ToolInvokeResult<TOutput>> {\n      const startedAtDate = new Date();\n      const start = performance.now();\n      const runId = generateRunId(\"tool\");\n      const handlerCtx = ctx ?? defaultToolContext();\n\n      const finish = (partial: { data?: TOutput; error?: AIError }): ToolInvokeResult<TOutput> => {\n        const endedAt = new Date().toISOString();\n        const duration = performance.now() - start;\n        const status: BaseReport[\"status\"] = partial.error ? \"failed\" : \"completed\";\n        const report: BaseReport = {\n          runId,\n          rootRunId: runId,\n          name: contract.name,\n          version: contract.version,\n          type: \"tool\",\n          status,\n          startedAt: startedAtDate.toISOString(),\n          endedAt,\n          duration,\n          usage: EMPTY_USAGE,\n          children: [],\n        };\n\n        return {\n          ...partial,\n          usage: EMPTY_USAGE,\n          report,\n        };\n      };\n\n      let validationResult: StandardSchemaV1.Result<TInput>;\n      if (contract.input) {\n        try {\n          validationResult = await contract.input[\"~standard\"].validate(rawInput);\n        } catch (thrown) {\n          const message = thrown instanceof Error ? thrown.message : String(thrown);\n\n          return finish({\n            error: new SchemaValidationError(\n              `Schema validation threw for tool \"${contract.name}\": ${message}`,\n              { cause: thrown, context: { toolName: contract.name } },\n            ),\n          });\n        }\n      } else {\n        // `input` is optional on ToolConfig — this is a no-argument tool\n        // (e.g. view_cart, checkout). With no schema there is nothing to\n        // validate, so pass the raw model args straight to execute()\n        // instead of dereferencing a missing schema's `~standard`.\n        validationResult = { value: rawInput as TInput };\n      }\n\n      if (validationResult.issues) {\n        const summary = validationResult.issues.map((issue) => issue.message).join(\"; \");\n\n        return finish({\n          error: new SchemaValidationError(`Validation failed: ${summary}`, {\n            issues: validationResult.issues,\n            context: { toolName: contract.name },\n          }),\n        });\n      }\n\n      try {\n        const output = await contract.execute(validationResult.value, handlerCtx);\n        return finish({ data: output });\n      } catch (thrown) {\n        const message = thrown instanceof Error ? thrown.message : String(thrown);\n\n        return finish({\n          error: new ToolExecutionError(message, {\n            cause: thrown,\n            toolName: contract.name,\n          }),\n        });\n      }\n    },\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"tool.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/tool/tool.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport type { BaseReport } from \"../contracts/result/base-report.type\";\nimport type { Usage } from \"../contracts/result/usage.type\";\nimport type { ToolConfig, ToolContext } from \"../contracts/tool.contract\";\nimport { AIError, SchemaValidationError, ToolExecutionError } from \"../errors\";\nimport { generateRunId } from \"../utils/generate-run-id\";\n\n/**\n * Degraded `ToolContext` supplied when no caller threads one through\n * (`tool.invoke(input)` standalone, batch scripts, tests). Per\n * decisions §35 — mutations on the empty bag are harmless no-ops;\n * production paths under a supervisor receive a real ctx with the\n * iteration's shared bag.\n */\nfunction defaultToolContext(): ToolContext {\n  return { artifacts: {} };\n}\n\nconst EMPTY_USAGE: Usage = Object.freeze({ input: 0, output: 0, total: 0 });\n\n/**\n * Result returned by `ToolContract.invoke()`.\n *\n * **Canonical destructure:** `const { data, usage, report, error }` —\n * matches every other executable (`AgentResult`, `WorkflowResult`,\n * `SupervisorResult`) so parent agents can treat every tool dispatch\n * uniformly.\n *\n * **Shape.** `data` / `error` carry the outcome; `usage` and `report`\n * are always present. For leaf tools, `usage` is zero and `report`\n * is a framework-synthesized {@link BaseReport} (`type: \"tool\"`,\n * `children: []`, real timing) so parents never have to nil-check.\n * For composites wrapped via `asTool()`, `usage` and `report` mirror\n * the inner primitive's — the nested tree lives in `report.children`.\n *\n * @example\n * const result = await myTool.invoke({ city: \"Cairo\" });\n * if (result.error) console.error(result.error.message);\n * else console.log(result.data, result.report.duration);\n */\nexport type ToolInvokeResult<TOutput> = {\n  /** Successfully-returned output. Undefined if execution or validation failed. */\n  data?: TOutput;\n  /** Typed AI error produced by validation or execute(), if any. */\n  error?: AIError;\n  /** Rolled-up usage (zero for leaf tools, populated for composites). */\n  usage: Usage;\n  /** Recursive execution report — `report.children` carries nested executables. */\n  report: BaseReport;\n};\n\n/**\n * A `ToolConfig` augmented with a safe `invoke()` entry point for the agent runtime.\n *\n * @example\n * const wrapped: ToolContract<{ city: string }, { temp: number }> = tool(contract);\n * const result = await wrapped.invoke({ city: \"Cairo\" });\n */\nexport interface ToolContract<TInput = unknown, TOutput = unknown> extends ToolConfig<\n  TInput,\n  TOutput\n> {\n  /**\n   * Agent-runtime entry point. Validates raw input against the tool's schema,\n   * calls execute(), catches errors, and reports duration.\n   * Never throws — errors surface in the returned `error` field as\n   * typed `AIError` subclasses.\n   *\n   * The optional second argument is a `ToolContext` (Phase 5 /\n   * decisions §35) — when supplied, threaded into `execute(input, ctx)`\n   * so tools can write system-only side data into `ctx.artifacts`.\n   * Standalone callers may omit it; the framework supplies a\n   * degraded `{ artifacts: {} }` so single-arg legacy handlers keep\n   * working unchanged.\n   *\n   * @example\n   * const result = await myTool.invoke(rawLLMArgs);\n   * if (result.error) handleError(result.error);\n   */\n  invoke(rawInput: unknown, ctx?: ToolContext): Promise<ToolInvokeResult<TOutput>>;\n}\n\n/**\n * Wraps a raw `ToolConfig` and adds a safe `invoke()` method for the agent runtime.\n * The returned object preserves all original contract fields unchanged.\n *\n * Error categorization:\n * - Input schema rejects model args → `SchemaValidationError` (issues preserved).\n * - Schema's `validate()` itself throws → `SchemaValidationError` wrapping the cause.\n * - `execute()` throws → `ToolExecutionError` wrapping the cause.\n *\n * @example\n * const weatherTool = tool({\n *   name: \"getWeather\",\n *   description: \"Fetch current weather for a city\",\n *   input: z.object({ city: z.string() }),\n *   execute: async ({ city }) => ({ temp: 72 }),\n * });\n *\n * const result = await weatherTool.invoke({ city: \"Cairo\" });\n */\n/**\n * Internal factory for `asTool()` wrappers on composite primitives\n * (agent / workflow / supervisor). Unlike the public `tool()` factory\n * (which synthesizes a leaf `BaseReport` every time), this variant\n * lets the composite's own `ExecuteResult` flow through: the inner\n * primitive's `report` becomes the sole child of the outer tool-call\n * node, and the inner `usage` is surfaced so parents can roll it up.\n *\n * The caller supplies `execute()` returning `{ data, usage, report }`\n * from the composite's own `execute()` method. Validation failures\n * and thrown errors still produce a synthesized failed leaf report —\n * the inner-report propagation is strictly a success-path concern.\n *\n * Not exported from the package barrel — used by `agent.asTool()`,\n * `workflow.asTool()`, `supervisor.asTool()` only.\n */\nexport function compositeAsTool<TInput, TOutput>(contract: {\n  name: string;\n  description?: string;\n  version?: string;\n  meta?: ToolConfig[\"meta\"];\n  input: StandardSchemaV1<TInput>;\n  /**\n   * Runs the underlying composite and returns its full envelope. The\n   * optional `ctx` relays the outer run's cancellation `signal` so a\n   * cancelled parent aborts the nested primitive instead of letting it\n   * outlive the cancellation (C2).\n   */\n  execute: (input: TInput, ctx?: ToolContext) => Promise<{\n    data?: TOutput;\n    error?: AIError;\n    usage: Usage;\n    report: BaseReport;\n  }>;\n}): ToolContract<TInput, TOutput> {\n  // The underlying `ToolConfig<TInput, TOutput>.execute` is typed as\n  // `(input) => Promise<TOutput>`, but composite wrappers return an\n  // envelope object instead. Surface a contract-shaped view that\n  // extracts `.data` on demand for any code that still treats this\n  // like a plain tool.\n  const publicExecute = async (input: TInput): Promise<TOutput> => {\n    const envelope = await contract.execute(input);\n    if (envelope.error) throw envelope.error;\n    return envelope.data as TOutput;\n  };\n\n  return {\n    name: contract.name,\n    description: contract.description ?? `Composite tool \"${contract.name}\".`,\n    meta: contract.meta,\n    input: contract.input,\n    execute: publicExecute,\n\n    async invoke(rawInput: unknown, ctx?: ToolContext): Promise<ToolInvokeResult<TOutput>> {\n      // Composite tools (asTool-wrapped agent/workflow/supervisor) run in\n      // their own state/scope — the ctx's `artifacts` bag is NOT shared\n      // into the inner primitive (an inner supervisor gets a fresh bag).\n      // The cancellation `signal`, however, IS relayed (below, into\n      // `contract.execute`) so a cancelled outer run aborts the nested\n      // primitive instead of letting it outlive the cancellation (C2).\n      const startedAtDate = new Date();\n      const start = performance.now();\n      const runId = generateRunId(\"tool\");\n\n      const failLeaf = (error: AIError): ToolInvokeResult<TOutput> => {\n        const endedAt = new Date().toISOString();\n        const duration = performance.now() - start;\n        return {\n          error,\n          usage: EMPTY_USAGE,\n          report: {\n            runId,\n            rootRunId: runId,\n            name: contract.name,\n            version: contract.version,\n            type: \"tool\",\n            status: \"failed\",\n            startedAt: startedAtDate.toISOString(),\n            endedAt,\n            duration,\n            usage: EMPTY_USAGE,\n            children: [],\n          },\n        };\n      };\n\n      let validationResult: StandardSchemaV1.Result<TInput>;\n      try {\n        const schema = contract.input as StandardSchemaV1<TInput>;\n        validationResult = await schema[\"~standard\"].validate(rawInput);\n      } catch (thrown) {\n        const message = thrown instanceof Error ? thrown.message : String(thrown);\n        return failLeaf(\n          new SchemaValidationError(\n            `Schema validation threw for tool \"${contract.name}\": ${message}`,\n            { cause: thrown, context: { toolName: contract.name } },\n          ),\n        );\n      }\n\n      if (validationResult.issues) {\n        const summary = validationResult.issues.map((issue) => issue.message).join(\"; \");\n        return failLeaf(\n          new SchemaValidationError(`Validation failed: ${summary}`, {\n            issues: validationResult.issues,\n            context: { toolName: contract.name },\n          }),\n        );\n      }\n\n      try {\n        const composite = await contract.execute(validationResult.value, ctx);\n        // Surface the inner primitive's full envelope. The outer\n        // ToolInvokeResult carries the composite's usage and report\n        // verbatim; the agent runtime nests the report as a child of\n        // the tool-dispatch node it records.\n        return {\n          data: composite.data,\n          error: composite.error,\n          usage: composite.usage,\n          report: composite.report,\n        };\n      } catch (thrown) {\n        const message = thrown instanceof Error ? thrown.message : String(thrown);\n        return failLeaf(\n          new ToolExecutionError(message, {\n            cause: thrown,\n            toolName: contract.name,\n          }),\n        );\n      }\n    },\n  };\n}\n\nexport function tool<TInput, TOutput>(\n  contract: ToolConfig<TInput, TOutput>,\n): ToolContract<TInput, TOutput> {\n  return {\n    ...contract,\n\n    async invoke(rawInput: unknown, ctx?: ToolContext): Promise<ToolInvokeResult<TOutput>> {\n      const startedAtDate = new Date();\n      const start = performance.now();\n      const runId = generateRunId(\"tool\");\n      const handlerCtx = ctx ?? defaultToolContext();\n\n      const finish = (partial: { data?: TOutput; error?: AIError }): ToolInvokeResult<TOutput> => {\n        const endedAt = new Date().toISOString();\n        const duration = performance.now() - start;\n        const status: BaseReport[\"status\"] = partial.error ? \"failed\" : \"completed\";\n        const report: BaseReport = {\n          runId,\n          rootRunId: runId,\n          name: contract.name,\n          version: contract.version,\n          type: \"tool\",\n          status,\n          startedAt: startedAtDate.toISOString(),\n          endedAt,\n          duration,\n          usage: EMPTY_USAGE,\n          children: [],\n        };\n\n        return {\n          ...partial,\n          usage: EMPTY_USAGE,\n          report,\n        };\n      };\n\n      let validationResult: StandardSchemaV1.Result<TInput>;\n      if (contract.input) {\n        try {\n          validationResult = await contract.input[\"~standard\"].validate(rawInput);\n        } catch (thrown) {\n          const message = thrown instanceof Error ? thrown.message : String(thrown);\n\n          return finish({\n            error: new SchemaValidationError(\n              `Schema validation threw for tool \"${contract.name}\": ${message}`,\n              { cause: thrown, context: { toolName: contract.name } },\n            ),\n          });\n        }\n      } else {\n        // `input` is optional on ToolConfig — this is a no-argument tool\n        // (e.g. view_cart, checkout). With no schema there is nothing to\n        // validate, so pass the raw model args straight to execute()\n        // instead of dereferencing a missing schema's `~standard`.\n        validationResult = { value: rawInput as TInput };\n      }\n\n      if (validationResult.issues) {\n        const summary = validationResult.issues.map((issue) => issue.message).join(\"; \");\n\n        return finish({\n          error: new SchemaValidationError(`Validation failed: ${summary}`, {\n            issues: validationResult.issues,\n            context: { toolName: contract.name },\n          }),\n        });\n      }\n\n      try {\n        const output = await contract.execute(validationResult.value, handlerCtx);\n        return finish({ data: output });\n      } catch (thrown) {\n        const message = thrown instanceof Error ? thrown.message : String(thrown);\n\n        return finish({\n          error: new ToolExecutionError(message, {\n            cause: thrown,\n            toolName: contract.name,\n          }),\n        });\n      }\n    },\n  };\n}\n"],"mappings":"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"}

package/esm/transcribe/audio-input.d.mts

@@ -0,0 +1,47 @@
+import { AudioInput } from "../contracts/transcription-model.contract.mjs";
+
+//#region ../@warlock.js/ai/src/transcribe/audio-input.d.ts
+/**
+ * Resolve the audio media type from a filename's extension, or
+ * `undefined` when the extension is unknown. Case-insensitive.
+ *
+ * @example
+ * audioMediaTypeForFilename("voice-note.opus"); // "audio/ogg"
+ */
+declare function audioMediaTypeForFilename(filename: string): string | undefined;
+/**
+ * Package raw audio bytes as an {@link AudioInput} for `ai.transcribe()`.
+ * Pure plumbing — no AI, no I/O. Use when you already hold the bytes
+ * (an upload buffer, a downloaded blob).
+ *
+ * @example
+ * const audio = audioFromBuffer(uploadBuffer, "audio/ogg", "note.ogg");
+ * const { data } = await ai.transcribe({ model: openai.transcribe({ name: "whisper-1" }), audio });
+ */
+declare function audioFromBuffer(data: Uint8Array, mediaType: string, filename?: string): AudioInput;
+/**
+ * Read an audio file from disk and package it as an {@link AudioInput}
+ * for `ai.transcribe()` — the one-line bridge from a file on disk
+ * (WhatsApp `.ogg`/`.opus`, a meeting `.m4a`, a `.wav`) to the
+ * transcription verb. **Pure utility — no AI here**; the actual text
+ * extraction is the AI step (`ai.transcribe`).
+ *
+ * The media type is inferred from the file extension (override via
+ * `options.mediaType` for extensionless or mislabeled files).
+ *
+ * @example
+ * // WhatsApp voice note → text, end to end:
+ * const audio = await audioFromFile("./voice-note.ogg");
+ * const { data, error } = await ai.transcribe({
+ *   model: openai.transcribe({ name: "whisper-1" }),
+ *   audio,
+ *   language: "en",
+ * });
+ * if (!error) console.log(data.text);
+ */
+declare function audioFromFile(filePath: string, options?: {
+  mediaType?: string;
+}): Promise<AudioInput>;
+//#endregion
+export { audioFromBuffer, audioFromFile, audioMediaTypeForFilename };
+//# sourceMappingURL=audio-input.d.mts.map

package/esm/transcribe/audio-input.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio-input.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/transcribe/audio-input.ts"],"mappings":";;;;;AAgCA;;;;AAA0D;iBAA1C,yBAAA,CAA0B,QAAgB;;;;;;;;;;iBAa1C,eAAA,CACd,IAAA,EAAM,UAAA,EACN,SAAA,UACA,QAAA,YACC,UAAU;AA4Bb;;;;;;;;;;AAGqB;;;;;;;;;;AAHrB,iBAAsB,aAAA,CACpB,QAAA,UACA,OAAA;EAAY,SAAA;AAAA,IACX,OAAO,CAAC,UAAA"}

package/esm/transcribe/audio-input.mjs

@@ -0,0 +1,84 @@
+import { readFile } from "node:fs/promises";
+import { basename, extname } from "node:path";
+
+//#region ../@warlock.js/ai/src/transcribe/audio-input.ts
+/**
+* File-extension → IANA audio media type map covering the formats the
+* common STT providers accept — including the **WhatsApp voice-note**
+* formats (`.ogg` / `.opus`, Opus-in-Ogg on Android; `.m4a` on iOS).
+*/
+const AUDIO_MEDIA_TYPES = {
+	".mp3": "audio/mpeg",
+	".mpeg": "audio/mpeg",
+	".mpga": "audio/mpeg",
+	".m4a": "audio/mp4",
+	".mp4": "audio/mp4",
+	".wav": "audio/wav",
+	".webm": "audio/webm",
+	".weba": "audio/webm",
+	".ogg": "audio/ogg",
+	".oga": "audio/ogg",
+	".opus": "audio/ogg",
+	".flac": "audio/flac",
+	".aac": "audio/aac"
+};
+/**
+* Resolve the audio media type from a filename's extension, or
+* `undefined` when the extension is unknown. Case-insensitive.
+*
+* @example
+* audioMediaTypeForFilename("voice-note.opus"); // "audio/ogg"
+*/
+function audioMediaTypeForFilename(filename) {
+	return AUDIO_MEDIA_TYPES[extname(filename).toLowerCase()];
+}
+/**
+* Package raw audio bytes as an {@link AudioInput} for `ai.transcribe()`.
+* Pure plumbing — no AI, no I/O. Use when you already hold the bytes
+* (an upload buffer, a downloaded blob).
+*
+* @example
+* const audio = audioFromBuffer(uploadBuffer, "audio/ogg", "note.ogg");
+* const { data } = await ai.transcribe({ model: openai.transcribe({ name: "whisper-1" }), audio });
+*/
+function audioFromBuffer(data, mediaType, filename) {
+	return {
+		base64: Buffer.from(data).toString("base64"),
+		mediaType,
+		...filename ? { filename } : {}
+	};
+}
+/**
+* Read an audio file from disk and package it as an {@link AudioInput}
+* for `ai.transcribe()` — the one-line bridge from a file on disk
+* (WhatsApp `.ogg`/`.opus`, a meeting `.m4a`, a `.wav`) to the
+* transcription verb. **Pure utility — no AI here**; the actual text
+* extraction is the AI step (`ai.transcribe`).
+*
+* The media type is inferred from the file extension (override via
+* `options.mediaType` for extensionless or mislabeled files).
+*
+* @example
+* // WhatsApp voice note → text, end to end:
+* const audio = await audioFromFile("./voice-note.ogg");
+* const { data, error } = await ai.transcribe({
+*   model: openai.transcribe({ name: "whisper-1" }),
+*   audio,
+*   language: "en",
+* });
+* if (!error) console.log(data.text);
+*/
+async function audioFromFile(filePath, options) {
+	const buffer = await readFile(filePath);
+	const filename = basename(filePath);
+	const mediaType = options?.mediaType ?? audioMediaTypeForFilename(filename) ?? "audio/mpeg";
+	return {
+		base64: buffer.toString("base64"),
+		mediaType,
+		filename
+	};
+}
+
+//#endregion
+export { audioFromBuffer, audioFromFile, audioMediaTypeForFilename };
+//# sourceMappingURL=audio-input.mjs.map

package/esm/transcribe/audio-input.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio-input.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/transcribe/audio-input.ts"],"sourcesContent":["import { readFile } from \"node:fs/promises\";\nimport { basename, extname } from \"node:path\";\nimport type { AudioInput } from \"../contracts/transcription-model.contract\";\n\n/**\n * File-extension → IANA audio media type map covering the formats the\n * common STT providers accept — including the **WhatsApp voice-note**\n * formats (`.ogg` / `.opus`, Opus-in-Ogg on Android; `.m4a` on iOS).\n */\nconst AUDIO_MEDIA_TYPES: Record<string, string> = {\n  \".mp3\": \"audio/mpeg\",\n  \".mpeg\": \"audio/mpeg\",\n  \".mpga\": \"audio/mpeg\",\n  \".m4a\": \"audio/mp4\",\n  \".mp4\": \"audio/mp4\",\n  \".wav\": \"audio/wav\",\n  \".webm\": \"audio/webm\",\n  \".weba\": \"audio/webm\",\n  \".ogg\": \"audio/ogg\",\n  \".oga\": \"audio/ogg\",\n  \".opus\": \"audio/ogg\",\n  \".flac\": \"audio/flac\",\n  \".aac\": \"audio/aac\",\n};\n\n/**\n * Resolve the audio media type from a filename's extension, or\n * `undefined` when the extension is unknown. Case-insensitive.\n *\n * @example\n * audioMediaTypeForFilename(\"voice-note.opus\"); // \"audio/ogg\"\n */\nexport function audioMediaTypeForFilename(filename: string): string | undefined {\n  return AUDIO_MEDIA_TYPES[extname(filename).toLowerCase()];\n}\n\n/**\n * Package raw audio bytes as an {@link AudioInput} for `ai.transcribe()`.\n * Pure plumbing — no AI, no I/O. Use when you already hold the bytes\n * (an upload buffer, a downloaded blob).\n *\n * @example\n * const audio = audioFromBuffer(uploadBuffer, \"audio/ogg\", \"note.ogg\");\n * const { data } = await ai.transcribe({ model: openai.transcribe({ name: \"whisper-1\" }), audio });\n */\nexport function audioFromBuffer(\n  data: Uint8Array,\n  mediaType: string,\n  filename?: string,\n): AudioInput {\n  return {\n    base64: Buffer.from(data).toString(\"base64\"),\n    mediaType,\n    ...(filename ? { filename } : {}),\n  };\n}\n\n/**\n * Read an audio file from disk and package it as an {@link AudioInput}\n * for `ai.transcribe()` — the one-line bridge from a file on disk\n * (WhatsApp `.ogg`/`.opus`, a meeting `.m4a`, a `.wav`) to the\n * transcription verb. **Pure utility — no AI here**; the actual text\n * extraction is the AI step (`ai.transcribe`).\n *\n * The media type is inferred from the file extension (override via\n * `options.mediaType` for extensionless or mislabeled files).\n *\n * @example\n * // WhatsApp voice note → text, end to end:\n * const audio = await audioFromFile(\"./voice-note.ogg\");\n * const { data, error } = await ai.transcribe({\n *   model: openai.transcribe({ name: \"whisper-1\" }),\n *   audio,\n *   language: \"en\",\n * });\n * if (!error) console.log(data.text);\n */\nexport async function audioFromFile(\n  filePath: string,\n  options?: { mediaType?: string },\n): Promise<AudioInput> {\n  const buffer = await readFile(filePath);\n  const filename = basename(filePath);\n  const mediaType = options?.mediaType ?? audioMediaTypeForFilename(filename) ?? \"audio/mpeg\";\n\n  return { base64: buffer.toString(\"base64\"), mediaType, filename };\n}\n"],"mappings":";;;;;;;;;AASA,MAAM,oBAA4C;CAChD,QAAQ;CACR,SAAS;CACT,SAAS;CACT,QAAQ;CACR,QAAQ;CACR,QAAQ;CACR,SAAS;CACT,SAAS;CACT,QAAQ;CACR,QAAQ;CACR,SAAS;CACT,SAAS;CACT,QAAQ;AACV;;;;;;;;AASA,SAAgB,0BAA0B,UAAsC;CAC9E,OAAO,kBAAkB,QAAQ,QAAQ,CAAC,CAAC,YAAY;AACzD;;;;;;;;;;AAWA,SAAgB,gBACd,MACA,WACA,UACY;CACZ,OAAO;EACL,QAAQ,OAAO,KAAK,IAAI,CAAC,CAAC,SAAS,QAAQ;EAC3C;EACA,GAAI,WAAW,EAAE,SAAS,IAAI,CAAC;CACjC;AACF;;;;;;;;;;;;;;;;;;;;;AAsBA,eAAsB,cACpB,UACA,SACqB;CACrB,MAAM,SAAS,MAAM,SAAS,QAAQ;CACtC,MAAM,WAAW,SAAS,QAAQ;CAClC,MAAM,YAAY,SAAS,aAAa,0BAA0B,QAAQ,KAAK;CAE/E,OAAO;EAAE,QAAQ,OAAO,SAAS,QAAQ;EAAG;EAAW;CAAS;AAClE"}

package/esm/transcribe/index.mjs

@@ -0,0 +1,4 @@
+import { audioFromBuffer, audioFromFile, audioMediaTypeForFilename } from "./audio-input.mjs";
+import { transcribe } from "./transcribe.mjs";
+
+export {  };

package/esm/transcribe/transcribe.d.mts

@@ -0,0 +1,64 @@
+import { BaseReport } from "../contracts/result/base-report.type.mjs";
+import { ExecuteResult } from "../contracts/result/execute-result.type.mjs";
+import { FlowObserveOption } from "../observe/resolve-observers.mjs";
+import { AudioInput, TranscriptionModelContract, TranscriptionSegment } from "../contracts/transcription-model.contract.mjs";
+
+//#region ../@warlock.js/ai/src/transcribe/transcribe.d.ts
+/** Parameters for {@link transcribe}. `model` comes from `sdk.transcribe({ name })`. */
+type TranscribeParams = {
+  /** The STT model to transcribe with. */model: TranscriptionModelContract; /** The audio to transcribe (inlined base64 bytes + media type). */
+  audio: AudioInput; /** BCP-47 language hint. */
+  language?: string; /** Optional priming prompt (spelling/style hints). */
+  prompt?: string; /** Provider response-format override (e.g. `"verbose_json"`). */
+  format?: string; /** Cancellation handle. */
+  signal?: AbortSignal; /** Observability routing — same `observe` seam as agents. */
+  observe?: FlowObserveOption; /** Groups this call into a session for flat cost/trace queries. */
+  sessionId?: string; /** Report node name (defaults to `"transcription"`). */
+  name?: string; /** Provider-specific options forwarded verbatim to the adapter. */
+  options?: Record<string, unknown>;
+};
+/** Success payload of a {@link transcribe} run. */
+type TranscriptionData = {
+  /** The full transcript text. */text: string; /** Timestamped segments when the provider returned them. */
+  segments?: TranscriptionSegment[];
+};
+/** The report node a {@link transcribe} run produces (`type: "transcription"`). */
+type TranscriptionReport = BaseReport & {
+  type: "transcription"; /** Identity of the STT model this run used. */
+  model: {
+    name: string;
+    provider: string;
+  }; /** Input audio duration in seconds, when the provider reported it. */
+  durationSeconds?: number;
+};
+/** Result envelope of {@link transcribe} — the uniform `{ data, error, usage, report }`. */
+type TranscriptionResult = ExecuteResult<TranscriptionData> & {
+  type: "transcription";
+  report: TranscriptionReport;
+};
+/**
+ * Transcribe audio to text — the speech-to-text verb of the
+ * output-modality track (Theme I), inverse of `ai.speech()`. Wraps a
+ * {@link TranscriptionModelContract} (from `openai.transcribe(...)`) in
+ * the uniform result contract:
+ *
+ * - **Never throws.** Provider failures surface as a typed `AIError` on
+ *   `result.error`.
+ * - **Cost-truth.** `result.usage.cost` is filled per-minute
+ *   (`whisper-1`) or per-token (`gpt-4o-transcribe`).
+ * - **Observable.** The completed {@link TranscriptionReport} routes to
+ *   any registered `Observer` via the `observe` seam.
+ *
+ * @example
+ * const openai = new OpenAISDK({ apiKey });
+ * const { data, error } = await ai.transcribe({
+ *   model: openai.transcribe({ name: "whisper-1" }),
+ *   audio: { base64, mediaType: "audio/mpeg", filename: "voicemail.mp3" },
+ *   language: "en",
+ * });
+ * if (!error) console.log(data.text);
+ */
+declare function transcribe(params: TranscribeParams): Promise<TranscriptionResult>;
+//#endregion
+export { TranscribeParams, TranscriptionData, TranscriptionReport, TranscriptionResult, transcribe };
+//# sourceMappingURL=transcribe.d.mts.map

package/esm/transcribe/transcribe.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcribe.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/transcribe/transcribe.ts"],"mappings":";;;;;;;KAoBY,gBAAA;EAAA,wCAEV,KAAA,EAAO,0BAAA;EAEP,KAAA,EAAO,UAAA,EAAA;EAEP,QAAA,WAQU;EANV,MAAA,WAYgB;EAVhB,MAAA,WARA;EAUA,MAAA,GAAS,WAAA,EART;EAUA,OAAA,GAAU,iBAAA,EARV;EAUA,SAAA,WANA;EAQA,IAAA,WANS;EAQT,OAAA,GAAU,MAAA;AAAA;;KAIA,iBAAA;EAJV,gCAMA,IAAA,UANgB;EAQhB,QAAA,GAAW,oBAAoB;AAAA;;KAIrB,mBAAA,GAAsB,UAAU;EAC1C,IAAA,mBAPA;EASA,KAAA;IAAS,IAAA;IAAc,QAAA;EAAA,GAHb;EAKV,eAAA;AAAA;;KAIU,mBAAA,GAAsB,aAAA,CAAc,iBAAA;EAC9C,IAAA;EACA,MAAA,EAAQ,mBAAA;AAAA;;;;AANO;AAIjB;;;;;;;;;;;;;;AAE6B;AAyB7B;;;iBAAsB,UAAA,CAAW,MAAA,EAAQ,gBAAA,GAAmB,OAAA,CAAQ,mBAAA"}

package/esm/transcribe/transcribe.mjs

@@ -0,0 +1,128 @@
+import { AIError } from "../errors/ai-error.mjs";
+import { ProviderError } from "../errors/provider-error.mjs";
+import { computeCost } from "../utils/compute-cost.mjs";
+import { generateRunId } from "../utils/generate-run-id.mjs";
+import { REPORT_SCHEMA_VERSION } from "../contracts/result/base-report.type.mjs";
+import { stampReportLineage } from "../utils/stamp-report-lineage.mjs";
+import { notifyObservers } from "../observe/resolve-observers.mjs";
+
+//#region ../@warlock.js/ai/src/transcribe/transcribe.ts
+/**
+* Transcribe audio to text — the speech-to-text verb of the
+* output-modality track (Theme I), inverse of `ai.speech()`. Wraps a
+* {@link TranscriptionModelContract} (from `openai.transcribe(...)`) in
+* the uniform result contract:
+*
+* - **Never throws.** Provider failures surface as a typed `AIError` on
+*   `result.error`.
+* - **Cost-truth.** `result.usage.cost` is filled per-minute
+*   (`whisper-1`) or per-token (`gpt-4o-transcribe`).
+* - **Observable.** The completed {@link TranscriptionReport} routes to
+*   any registered `Observer` via the `observe` seam.
+*
+* @example
+* const openai = new OpenAISDK({ apiKey });
+* const { data, error } = await ai.transcribe({
+*   model: openai.transcribe({ name: "whisper-1" }),
+*   audio: { base64, mediaType: "audio/mpeg", filename: "voicemail.mp3" },
+*   language: "en",
+* });
+* if (!error) console.log(data.text);
+*/
+async function transcribe(params) {
+	const { model, audio } = params;
+	const runId = generateRunId("transcription");
+	const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+	const startPerf = performance.now();
+	const usage = {
+		input: 0,
+		output: 0,
+		total: 0
+	};
+	let data;
+	let error;
+	let status = "completed";
+	let durationSeconds;
+	try {
+		const response = await model.transcribe(audio, {
+			language: params.language,
+			prompt: params.prompt,
+			format: params.format,
+			signal: params.signal,
+			...params.options
+		});
+		Object.assign(usage, response.usage);
+		durationSeconds = response.durationSeconds;
+		if (usage.cost === void 0) {
+			const cost = computeTranscriptionCost(usage, durationSeconds, model.pricing);
+			if (cost !== void 0) usage.cost = cost;
+		}
+		data = {
+			text: response.text,
+			...response.segments ? { segments: response.segments } : {}
+		};
+	} catch (thrown) {
+		error = thrown instanceof AIError ? thrown : new ProviderError(toMessage(thrown), { cause: thrown });
+		status = params.signal?.aborted ? "cancelled" : "failed";
+	}
+	const report = {
+		runId,
+		rootRunId: runId,
+		name: params.name ?? "transcription",
+		type: "transcription",
+		status,
+		error,
+		startedAt,
+		endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		duration: performance.now() - startPerf,
+		usage,
+		children: [],
+		model: {
+			name: model.name,
+			provider: model.provider
+		},
+		...durationSeconds !== void 0 ? { durationSeconds } : {},
+		reportSchemaVersion: 1
+	};
+	stampReportLineage(report, {
+		rootRunId: runId,
+		sessionId: params.sessionId
+	});
+	await notifyObservers(params.observe, report);
+	return {
+		type: "transcription",
+		data,
+		error,
+		usage,
+		report
+	};
+}
+/**
+* Price an STT run: `perMinute × (durationSeconds / 60)` (per-minute
+* metering, attributed to `cost.input`) wins when configured, otherwise
+* the standard token math. Returns `undefined` when no usable pricing
+* is present (e.g. per-minute pricing but the provider didn't report a
+* duration).
+*/
+function computeTranscriptionCost(usage, durationSeconds, pricing) {
+	if (!pricing) return;
+	if (pricing.perMinute !== void 0) {
+		if (durationSeconds === void 0) return;
+		return {
+			input: durationSeconds / 60 * pricing.perMinute,
+			output: 0
+		};
+	}
+	if (pricing.input !== void 0 && pricing.output !== void 0) return computeCost(usage, {
+		input: pricing.input,
+		output: pricing.output
+	});
+}
+/** Best-effort message for a non-`AIError` thrown value. */
+function toMessage(thrown) {
+	return thrown instanceof Error ? thrown.message : String(thrown);
+}
+
+//#endregion
+export { transcribe };
+//# sourceMappingURL=transcribe.mjs.map