@noetaris/harness-types 0.7.0 → 0.8.0

package/README.md

@@ -19,8 +19,9 @@ This package defines the common TypeScript interfaces that all LLM adapter packa
 | `Tool` | `{ name: string; description: string; inputSchema: Record<string, unknown> }` |
 | `ToolCall` | `{ id: string; name: string; input: unknown }` |
 | `LLMResponse` | `{ text: string; toolCalls: ToolCall[]; stopReason: 'end' \| 'tool_use' \| 'max_tokens'; usage: { inputTokens: number; outputTokens: number; contextWindowSize?: number } }` — `usage` is always present; all adapters must populate it |
-| `LLMRequestEvent` | `"llm.request"` payload: `{ modelId: string; providerName: string; messages?: unknown; tools?: unknown; callId?: string }` (`messages`/`tools` opt-in; `callId` pairs the event with its `"llm.response"`) |
-| `LLMUsageEvent` | `"llm.response"` payload: `{ tokens: { input: number; output: number }; modelId: string; stopReason: LLMResponse['stopReason']; providerName: string; output?: unknown; contextWindowSize?: number }` |
+| `LLMRequestEvent` | `"llm.request"` payload: `{ callId: string; modelId: string; providerName: string; messages?: Message[]; tools?: Tool[] }` (`messages`/`tools` opt-in, the harness shapes passed to `invoke()`; `callId` pairs the event with its `"llm.response"` or `"llm.error"`) |
+| `LLMUsageEvent` | `"llm.response"` payload: `{ callId: string; tokens: { input: number; output: number }; modelId: string; stopReason: LLMResponse['stopReason']; providerName: string; output?: LLMResponse; contextWindowSize?: number }` (`output` opt-in) |
+| `LLMErrorEvent` | `"llm.error"` payload: `{ callId: string; modelId: string; providerName: string; error: unknown }` — emitted when the call throws after `"llm.request"`; `error` is the thrown value, which the adapter rethrows |
 | `ToolCallEvent` | `"tool.call"` payload: `{ toolName: string; toolCallId: string; input?: unknown }` (`input` opt-in) |
 | `ToolResultEvent` | `"tool.result"` payload: `{ toolName: string; toolCallId: string; durationMs: number; result?: unknown; error?: unknown }` (`result` opt-in; `error` is set whenever the tool threw) |
 | `ToolRunContext` | `{ emit(name, payload?): void; within<T>(type, payload, fn): Promise<T> }` — the part of a step `ctx` that `runTool` needs |
@@ -72,10 +73,11 @@ const outputs = await Promise.all(
 - `ctx` is the step's `ctx` from `@noetaris/harness` 0.7 or later, or any object with `emit` and
   `within` (see `ToolRunContext`). With an OTel observer, the tool's span is the active span while
   `fn` runs, so a sub agent or an instrumented HTTP call made by the tool nests under it. See the
-  [OTel bridge](https://github.com/noetaris-lab/harness-otel).
+  [OTel bridge](https://github.com/noetaris-lab/harness-otel) and its
+  [GenAI extension](https://github.com/noetaris-lab/harness-otel-genai), which opens the `execute_tool` span.
 - `options.captureIO` (default `false`) puts the call's `input` on `"tool.call"` and the tool's
-  result on `"tool.result"`. They may contain sensitive data. An OTel observer records them only
-  when its `captureToolIO` option is on as well.
+  result on `"tool.result"`. They may contain sensitive data. The GenAI extension records them
+  only when its `captureToolIO` option is on as well.
 - `"tool.result"` always carries `error` when the tool threw, whatever `captureIO` says; a thrown
   `undefined` is reported as `Error('tool threw undefined')`.
 - Calls made at the same time keep their own events, told apart by `toolCallId`.

package/dist/index.d.ts

@@ -128,32 +128,41 @@ interface LLMResponse {
  * Payload emitted by LLM adapters as an `"llm.request"` observer event,
  * immediately before the provider call is made.
  *
- * `messages` and `tools` are opt-in — they may contain sensitive data and are
- * typed as `unknown` because adapters pass their internal translated
- * representations; the framework never inspects this content.
+ * Each `invoke()` call that reaches this event is followed by exactly one of
+ * `"llm.response"` ({@link LLMUsageEvent}) or `"llm.error"` ({@link LLMErrorEvent}),
+ * carrying the same `callId`. A throw before this event emits nothing.
+ *
+ * `messages` and `tools` are opt-in — they may contain sensitive data. When present they
+ * are the normalized harness shapes passed to `invoke()`, not the provider-translated
+ * payloads. They are passed by reference; observers must not mutate them.
  */
 interface LLMRequestEvent {
-    modelId: string;
-    providerName: string;
-    messages?: unknown;
-    tools?: unknown;
     /**
      * Correlation id for this single `invoke()` call, minted per call by the adapter and
-     * carried on both the `"llm.request"` and the matching `"llm.response"` event, so an
-     * observer can pair them reliably even when concurrent fork branches interleave.
+     * carried on the `"llm.request"` event and on the matching `"llm.response"` or
+     * `"llm.error"` event, so an observer can pair them reliably even when concurrent
+     * fork branches interleave.
      */
-    callId?: string;
+    callId: string;
+    modelId: string;
+    providerName: string;
+    messages?: Message[];
+    tools?: Tool[];
 }
 /**
- * Token-usage payload emitted by LLM adapters as an `"llm.response"` observer event.
+ * Token-usage payload emitted by LLM adapters as an `"llm.response"` observer event,
+ * after a successful provider call.
  *
  * Adapters that cannot report real token counts (e.g. mock adapters) emit `{ input: 0, output: 0 }`.
  *
- * `output` is opt-in — it may contain sensitive data; adapters default to omitting it.
+ * `output` is opt-in — it may contain sensitive data; adapters default to omitting it. When
+ * present it is the normalized {@link LLMResponse} that `invoke()` returns, passed by reference.
  * `contextWindowSize` mirrors `LLMResponse.usage.contextWindowSize` — present when the
  * adapter can determine it; absent otherwise.
  */
 interface LLMUsageEvent {
+    /** Correlation id matching the `"llm.request"` event for the same `invoke()` call (see {@link LLMRequestEvent.callId}). */
+    callId: string;
     tokens: {
         input: number;
         output: number;
@@ -161,13 +170,21 @@ interface LLMUsageEvent {
     modelId: string;
     stopReason: LLMResponse['stopReason'];
     providerName: string;
-    output?: unknown;
+    output?: LLMResponse;
     contextWindowSize?: number;
-    /**
-     * Correlation id matching the `"llm.request"` event for the same `invoke()` call
-     * (see {@link LLMRequestEvent.callId}). Lets an observer pair request and response.
-     */
-    callId?: string;
+}
+/**
+ * Payload emitted by LLM adapters as an `"llm.error"` observer event, when anything throws
+ * after `"llm.request"` was emitted and before `"llm.response"` would be (the provider call,
+ * response normalization). The adapter then rethrows the same value.
+ */
+interface LLMErrorEvent {
+    /** Correlation id matching the `"llm.request"` event for the same `invoke()` call (see {@link LLMRequestEvent.callId}). */
+    callId: string;
+    modelId: string;
+    providerName: string;
+    /** The thrown value, unchanged; any value, including `undefined`. */
+    error: unknown;
 }
 /**
  * Payload emitted on `"tool.call"` before a tool is dispatched.
@@ -213,4 +230,4 @@ interface LLM {
     }): Promise<LLMResponse>;
 }
 
-export { type ContentBlock, type ImageBlock, type LLM, type LLMRequestEvent, type LLMResponse, type LLMUsageEvent, type Message, type RunToolOptions, type TextBlock, type Tool, type ToolCall, type ToolCallEvent, type ToolResultEvent, type ToolRunContext, runTool, toBlocks };
+export { type ContentBlock, type ImageBlock, type LLM, type LLMErrorEvent, type LLMRequestEvent, type LLMResponse, type LLMUsageEvent, type Message, type RunToolOptions, type TextBlock, type Tool, type ToolCall, type ToolCallEvent, type ToolResultEvent, type ToolRunContext, runTool, toBlocks };

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/run-tool.ts","../src/index.ts"],"sourcesContent":["import type { ToolCall, ToolCallEvent, ToolResultEvent } from './index.js'\n\n/**\n * The part of a step ctx {@link runTool} needs. The `@noetaris/harness` step ctx (0.7 and\n * later) satisfies it structurally.\n */\nexport interface ToolRunContext {\n  emit(name: string, payload?: unknown): void\n  within<T>(type: string, payload: unknown, fn: () => Promise<T>): Promise<T>\n}\n\nexport interface RunToolOptions {\n  /**\n   * Put the tool's `input` on `\"tool.call\"` and its `result` on `\"tool.result\"`. They may\n   * contain sensitive data. Default: `false`.\n   */\n  captureIO?: boolean\n}\n\n/**\n * Run one tool call and report it: emits `\"tool.call\"`, runs `fn` inside the observer's scope\n * for that event (`ctx.within('tool.call', { toolCallId })`), then emits `\"tool.result\"` with\n * `durationMs` — and `error` when `fn` threw, in which case the same value is rethrown.\n * Returns `fn`'s value.\n *\n * @example\n * ```ts\n * const outputs = await Promise.all(\n *   res.toolCalls.map(call => runTool(ctx, call, () => toolImpls[call.name](call.input))),\n * )\n * ```\n */\nexport async function runTool<T>(\n  ctx: ToolRunContext,\n  call: Pick<ToolCall, 'id' | 'name' | 'input'>,\n  fn: () => Promise<T>,\n  options?: RunToolOptions,\n): Promise<T> {\n  const captureIO = options?.captureIO === true\n  const base = { toolName: call.name, toolCallId: call.id }\n  const callEvent: ToolCallEvent = captureIO ? { ...base, input: call.input } : base\n  ctx.emit('tool.call', callEvent)\n\n  const start = Date.now()\n  let value: T\n  try {\n    value = await ctx.within('tool.call', { toolCallId: call.id }, fn)\n  } catch (error) {\n    const failed: ToolResultEvent = {\n      ...base,\n      durationMs: Date.now() - start,\n      // Consumers read `error !== undefined` as \"the tool failed\", so a thrown undefined is named.\n      error: error === undefined ? new Error('tool threw undefined') : error,\n    }\n    ctx.emit('tool.result', failed)\n    throw error\n  }\n  const succeeded: ToolResultEvent = captureIO\n    ? { ...base, durationMs: Date.now() - start, result: value }\n    : { ...base, durationMs: Date.now() - start }\n  ctx.emit('tool.result', succeeded)\n  return value\n}\n","/**\n * Shared LLM protocol types used by all harness LLM adapters.\n *\n * @packageDocumentation\n */\n\n/** A run of plain text inside a user message. */\nexport type TextBlock = { type: 'text'; text: string }\n\n/**\n * An image inside a user message.\n *\n * `data` is raw base64 with no `data:` prefix. `mediaType` is the MIME type\n * (e.g. `'image/png'`); Anthropic, OpenAI and Ollama throw on types they do not accept; Gemini passes any value through.\n */\nexport type ImageBlock = { type: 'image'; data: string; mediaType: string }\n\n/** One piece of user-message content. */\nexport type ContentBlock = TextBlock | ImageBlock\n\n/**\n * A single turn in a conversation.\n *\n * - `user` — input from the human side: a string, or blocks mixing text and images.\n *   An empty block array is allowed by the type but may be rejected by providers; don't send one.\n * - `assistant` — model reply, optionally carrying tool-call requests.\n * - `tool` — result returned to the model after a tool call.\n */\nexport type Message =\n  | { role: 'user'; content: string | ContentBlock[] }\n  | { role: 'assistant'; content?: string; toolCalls?: ToolCall[] }\n  | { role: 'tool'; toolCallId: string; content: string }\n\n/**\n * Normalize user-message content to blocks.\n *\n * A string becomes one text block (an empty string stays one empty text block).\n * An array is returned as-is, same reference, with no validation.\n */\nexport function toBlocks(content: string | ContentBlock[]): ContentBlock[] {\n  return typeof content === 'string' ? [{ type: 'text', text: content }] : content\n}\n\n/**\n * A tool the LLM may invoke during a conversation turn.\n *\n * `inputSchema` must be a valid JSON Schema object describing the tool's\n * input parameters (LLM adapters pass it to the provider as-is).\n */\nexport interface Tool {\n  name: string\n  description: string\n  inputSchema: Record<string, unknown>\n}\n\n/**\n * A single tool-call request emitted by the LLM in an assistant turn.\n *\n * `id` is provider-assigned and must be echoed back in the corresponding\n * `role: 'tool'` message so the model can correlate results.\n */\nexport interface ToolCall {\n  id: string\n  name: string\n  input: unknown\n}\n\n/**\n * Normalized response returned by every {@link LLM} adapter.\n *\n * `text` may be empty when `stopReason` is `'tool_use'`.\n * `toolCalls` is empty when `stopReason` is `'end'` or `'max_tokens'`.\n * `usage` is always present — all adapters must populate it.\n */\nexport interface LLMResponse {\n  text: string\n  toolCalls: ToolCall[]\n  stopReason: 'end' | 'tool_use' | 'max_tokens'\n  usage: {\n    /** Number of input tokens consumed by this call. */\n    inputTokens: number\n    /** Number of output tokens generated by this call. */\n    outputTokens: number\n    /**\n     * The model's total context window capacity in tokens.\n     * Present only when the adapter can determine it.\n     * Absent when the adapter cannot determine capacity.\n     */\n    contextWindowSize?: number\n  }\n}\n\n/**\n * Payload emitted by LLM adapters as an `\"llm.request\"` observer event,\n * immediately before the provider call is made.\n *\n * `messages` and `tools` are opt-in — they may contain sensitive data and are\n * typed as `unknown` because adapters pass their internal translated\n * representations; the framework never inspects this content.\n */\nexport interface LLMRequestEvent {\n  modelId:      string\n  providerName: string\n  messages?:    unknown   // opt-in; adapter's internal translated representation\n  tools?:       unknown   // opt-in; adapter's internal translated representation\n  /**\n   * Correlation id for this single `invoke()` call, minted per call by the adapter and\n   * carried on both the `\"llm.request\"` and the matching `\"llm.response\"` event, so an\n   * observer can pair them reliably even when concurrent fork branches interleave.\n   */\n  callId?:      string\n}\n\n/**\n * Token-usage payload emitted by LLM adapters as an `\"llm.response\"` observer event.\n *\n * Adapters that cannot report real token counts (e.g. mock adapters) emit `{ input: 0, output: 0 }`.\n *\n * `output` is opt-in — it may contain sensitive data; adapters default to omitting it.\n * `contextWindowSize` mirrors `LLMResponse.usage.contextWindowSize` — present when the\n * adapter can determine it; absent otherwise.\n */\nexport interface LLMUsageEvent {\n  tokens:            { input: number; output: number }\n  modelId:           string\n  stopReason:        LLMResponse['stopReason']\n  providerName:      string\n  output?:           unknown   // opt-in; normalized LLMResponse or raw provider output; may be sensitive\n  contextWindowSize?: number\n  /**\n   * Correlation id matching the `\"llm.request\"` event for the same `invoke()` call\n   * (see {@link LLMRequestEvent.callId}). Lets an observer pair request and response.\n   */\n  callId?:           string\n}\n\n/**\n * Payload emitted on `\"tool.call\"` before a tool is dispatched.\n *\n * `input` is opt-in — it may contain sensitive data; omit by default.\n */\nexport interface ToolCallEvent {\n  toolName:   string\n  toolCallId: string\n  input?:     unknown\n}\n\n/**\n * Payload emitted on `\"tool.result\"` after a tool completes or throws.\n *\n * `result` is opt-in — it may contain sensitive data; omit by default.\n * `error` is set whenever the tool threw (the thrown value) and absent on success; it is how\n * consumers tell a failed call from a successful one, so it is not gated.\n */\nexport interface ToolResultEvent {\n  toolName:   string\n  toolCallId: string\n  durationMs: number\n  result?:    unknown\n  error?:     unknown\n}\n\n/**\n * Core interface every LLM adapter must implement.\n *\n * @example\n * ```ts\n * const response = await llm.invoke(messages, { tools: [myTool] })\n * ```\n */\nexport interface LLM {\n  /**\n   * Send a message list to the LLM and return a normalized response.\n   *\n   * @param messages - Conversation history, oldest first.\n   * @param options.tools - Optional tools the model may invoke.\n   */\n  invoke(messages: Message[], options?: { tools?: Tool[] }): Promise<LLMResponse>\n}\n\nexport { runTool, type ToolRunContext, type RunToolOptions } from './run-tool.js'\n"],"mappings":";AAgCA,eAAsB,QACpB,KACA,MACA,IACA,SACY;AACZ,QAAM,YAAY,SAAS,cAAc;AACzC,QAAM,OAAO,EAAE,UAAU,KAAK,MAAM,YAAY,KAAK,GAAG;AACxD,QAAM,YAA2B,YAAY,EAAE,GAAG,MAAM,OAAO,KAAK,MAAM,IAAI;AAC9E,MAAI,KAAK,aAAa,SAAS;AAE/B,QAAM,QAAQ,KAAK,IAAI;AACvB,MAAI;AACJ,MAAI;AACF,YAAQ,MAAM,IAAI,OAAO,aAAa,EAAE,YAAY,KAAK,GAAG,GAAG,EAAE;AAAA,EACnE,SAAS,OAAO;AACd,UAAM,SAA0B;AAAA,MAC9B,GAAG;AAAA,MACH,YAAY,KAAK,IAAI,IAAI;AAAA;AAAA,MAEzB,OAAO,UAAU,SAAY,IAAI,MAAM,sBAAsB,IAAI;AAAA,IACnE;AACA,QAAI,KAAK,eAAe,MAAM;AAC9B,UAAM;AAAA,EACR;AACA,QAAM,YAA6B,YAC/B,EAAE,GAAG,MAAM,YAAY,KAAK,IAAI,IAAI,OAAO,QAAQ,MAAM,IACzD,EAAE,GAAG,MAAM,YAAY,KAAK,IAAI,IAAI,MAAM;AAC9C,MAAI,KAAK,eAAe,SAAS;AACjC,SAAO;AACT;;;ACvBO,SAAS,SAAS,SAAkD;AACzE,SAAO,OAAO,YAAY,WAAW,CAAC,EAAE,MAAM,QAAQ,MAAM,QAAQ,CAAC,IAAI;AAC3E;","names":[]}
+{"version":3,"sources":["../src/run-tool.ts","../src/index.ts"],"sourcesContent":["import type { ToolCall, ToolCallEvent, ToolResultEvent } from './index.js'\n\n/**\n * The part of a step ctx {@link runTool} needs. The `@noetaris/harness` step ctx (0.7 and\n * later) satisfies it structurally.\n */\nexport interface ToolRunContext {\n  emit(name: string, payload?: unknown): void\n  within<T>(type: string, payload: unknown, fn: () => Promise<T>): Promise<T>\n}\n\nexport interface RunToolOptions {\n  /**\n   * Put the tool's `input` on `\"tool.call\"` and its `result` on `\"tool.result\"`. They may\n   * contain sensitive data. Default: `false`.\n   */\n  captureIO?: boolean\n}\n\n/**\n * Run one tool call and report it: emits `\"tool.call\"`, runs `fn` inside the observer's scope\n * for that event (`ctx.within('tool.call', { toolCallId })`), then emits `\"tool.result\"` with\n * `durationMs` — and `error` when `fn` threw, in which case the same value is rethrown.\n * Returns `fn`'s value.\n *\n * @example\n * ```ts\n * const outputs = await Promise.all(\n *   res.toolCalls.map(call => runTool(ctx, call, () => toolImpls[call.name](call.input))),\n * )\n * ```\n */\nexport async function runTool<T>(\n  ctx: ToolRunContext,\n  call: Pick<ToolCall, 'id' | 'name' | 'input'>,\n  fn: () => Promise<T>,\n  options?: RunToolOptions,\n): Promise<T> {\n  const captureIO = options?.captureIO === true\n  const base = { toolName: call.name, toolCallId: call.id }\n  const callEvent: ToolCallEvent = captureIO ? { ...base, input: call.input } : base\n  ctx.emit('tool.call', callEvent)\n\n  const start = Date.now()\n  let value: T\n  try {\n    value = await ctx.within('tool.call', { toolCallId: call.id }, fn)\n  } catch (error) {\n    const failed: ToolResultEvent = {\n      ...base,\n      durationMs: Date.now() - start,\n      // Consumers read `error !== undefined` as \"the tool failed\", so a thrown undefined is named.\n      error: error === undefined ? new Error('tool threw undefined') : error,\n    }\n    ctx.emit('tool.result', failed)\n    throw error\n  }\n  const succeeded: ToolResultEvent = captureIO\n    ? { ...base, durationMs: Date.now() - start, result: value }\n    : { ...base, durationMs: Date.now() - start }\n  ctx.emit('tool.result', succeeded)\n  return value\n}\n","/**\n * Shared LLM protocol types used by all harness LLM adapters.\n *\n * @packageDocumentation\n */\n\n/** A run of plain text inside a user message. */\nexport type TextBlock = { type: 'text'; text: string }\n\n/**\n * An image inside a user message.\n *\n * `data` is raw base64 with no `data:` prefix. `mediaType` is the MIME type\n * (e.g. `'image/png'`); Anthropic, OpenAI and Ollama throw on types they do not accept; Gemini passes any value through.\n */\nexport type ImageBlock = { type: 'image'; data: string; mediaType: string }\n\n/** One piece of user-message content. */\nexport type ContentBlock = TextBlock | ImageBlock\n\n/**\n * A single turn in a conversation.\n *\n * - `user` — input from the human side: a string, or blocks mixing text and images.\n *   An empty block array is allowed by the type but may be rejected by providers; don't send one.\n * - `assistant` — model reply, optionally carrying tool-call requests.\n * - `tool` — result returned to the model after a tool call.\n */\nexport type Message =\n  | { role: 'user'; content: string | ContentBlock[] }\n  | { role: 'assistant'; content?: string; toolCalls?: ToolCall[] }\n  | { role: 'tool'; toolCallId: string; content: string }\n\n/**\n * Normalize user-message content to blocks.\n *\n * A string becomes one text block (an empty string stays one empty text block).\n * An array is returned as-is, same reference, with no validation.\n */\nexport function toBlocks(content: string | ContentBlock[]): ContentBlock[] {\n  return typeof content === 'string' ? [{ type: 'text', text: content }] : content\n}\n\n/**\n * A tool the LLM may invoke during a conversation turn.\n *\n * `inputSchema` must be a valid JSON Schema object describing the tool's\n * input parameters (LLM adapters pass it to the provider as-is).\n */\nexport interface Tool {\n  name: string\n  description: string\n  inputSchema: Record<string, unknown>\n}\n\n/**\n * A single tool-call request emitted by the LLM in an assistant turn.\n *\n * `id` is provider-assigned and must be echoed back in the corresponding\n * `role: 'tool'` message so the model can correlate results.\n */\nexport interface ToolCall {\n  id: string\n  name: string\n  input: unknown\n}\n\n/**\n * Normalized response returned by every {@link LLM} adapter.\n *\n * `text` may be empty when `stopReason` is `'tool_use'`.\n * `toolCalls` is empty when `stopReason` is `'end'` or `'max_tokens'`.\n * `usage` is always present — all adapters must populate it.\n */\nexport interface LLMResponse {\n  text: string\n  toolCalls: ToolCall[]\n  stopReason: 'end' | 'tool_use' | 'max_tokens'\n  usage: {\n    /** Number of input tokens consumed by this call. */\n    inputTokens: number\n    /** Number of output tokens generated by this call. */\n    outputTokens: number\n    /**\n     * The model's total context window capacity in tokens.\n     * Present only when the adapter can determine it.\n     * Absent when the adapter cannot determine capacity.\n     */\n    contextWindowSize?: number\n  }\n}\n\n/**\n * Payload emitted by LLM adapters as an `\"llm.request\"` observer event,\n * immediately before the provider call is made.\n *\n * Each `invoke()` call that reaches this event is followed by exactly one of\n * `\"llm.response\"` ({@link LLMUsageEvent}) or `\"llm.error\"` ({@link LLMErrorEvent}),\n * carrying the same `callId`. A throw before this event emits nothing.\n *\n * `messages` and `tools` are opt-in — they may contain sensitive data. When present they\n * are the normalized harness shapes passed to `invoke()`, not the provider-translated\n * payloads. They are passed by reference; observers must not mutate them.\n */\nexport interface LLMRequestEvent {\n  /**\n   * Correlation id for this single `invoke()` call, minted per call by the adapter and\n   * carried on the `\"llm.request\"` event and on the matching `\"llm.response\"` or\n   * `\"llm.error\"` event, so an observer can pair them reliably even when concurrent\n   * fork branches interleave.\n   */\n  callId:       string\n  modelId:      string\n  providerName: string\n  messages?:    Message[]   // opt-in; the messages passed to invoke()\n  tools?:       Tool[]      // opt-in; the tools passed to invoke()\n}\n\n/**\n * Token-usage payload emitted by LLM adapters as an `\"llm.response\"` observer event,\n * after a successful provider call.\n *\n * Adapters that cannot report real token counts (e.g. mock adapters) emit `{ input: 0, output: 0 }`.\n *\n * `output` is opt-in — it may contain sensitive data; adapters default to omitting it. When\n * present it is the normalized {@link LLMResponse} that `invoke()` returns, passed by reference.\n * `contextWindowSize` mirrors `LLMResponse.usage.contextWindowSize` — present when the\n * adapter can determine it; absent otherwise.\n */\nexport interface LLMUsageEvent {\n  /** Correlation id matching the `\"llm.request\"` event for the same `invoke()` call (see {@link LLMRequestEvent.callId}). */\n  callId:            string\n  tokens:            { input: number; output: number }\n  modelId:           string\n  stopReason:        LLMResponse['stopReason']\n  providerName:      string\n  output?:           LLMResponse   // opt-in; may be sensitive\n  contextWindowSize?: number\n}\n\n/**\n * Payload emitted by LLM adapters as an `\"llm.error\"` observer event, when anything throws\n * after `\"llm.request\"` was emitted and before `\"llm.response\"` would be (the provider call,\n * response normalization). The adapter then rethrows the same value.\n */\nexport interface LLMErrorEvent {\n  /** Correlation id matching the `\"llm.request\"` event for the same `invoke()` call (see {@link LLMRequestEvent.callId}). */\n  callId:       string\n  modelId:      string\n  providerName: string\n  /** The thrown value, unchanged; any value, including `undefined`. */\n  error:        unknown\n}\n\n/**\n * Payload emitted on `\"tool.call\"` before a tool is dispatched.\n *\n * `input` is opt-in — it may contain sensitive data; omit by default.\n */\nexport interface ToolCallEvent {\n  toolName:   string\n  toolCallId: string\n  input?:     unknown\n}\n\n/**\n * Payload emitted on `\"tool.result\"` after a tool completes or throws.\n *\n * `result` is opt-in — it may contain sensitive data; omit by default.\n * `error` is set whenever the tool threw (the thrown value) and absent on success; it is how\n * consumers tell a failed call from a successful one, so it is not gated.\n */\nexport interface ToolResultEvent {\n  toolName:   string\n  toolCallId: string\n  durationMs: number\n  result?:    unknown\n  error?:     unknown\n}\n\n/**\n * Core interface every LLM adapter must implement.\n *\n * @example\n * ```ts\n * const response = await llm.invoke(messages, { tools: [myTool] })\n * ```\n */\nexport interface LLM {\n  /**\n   * Send a message list to the LLM and return a normalized response.\n   *\n   * @param messages - Conversation history, oldest first.\n   * @param options.tools - Optional tools the model may invoke.\n   */\n  invoke(messages: Message[], options?: { tools?: Tool[] }): Promise<LLMResponse>\n}\n\nexport { runTool, type ToolRunContext, type RunToolOptions } from './run-tool.js'\n"],"mappings":";AAgCA,eAAsB,QACpB,KACA,MACA,IACA,SACY;AACZ,QAAM,YAAY,SAAS,cAAc;AACzC,QAAM,OAAO,EAAE,UAAU,KAAK,MAAM,YAAY,KAAK,GAAG;AACxD,QAAM,YAA2B,YAAY,EAAE,GAAG,MAAM,OAAO,KAAK,MAAM,IAAI;AAC9E,MAAI,KAAK,aAAa,SAAS;AAE/B,QAAM,QAAQ,KAAK,IAAI;AACvB,MAAI;AACJ,MAAI;AACF,YAAQ,MAAM,IAAI,OAAO,aAAa,EAAE,YAAY,KAAK,GAAG,GAAG,EAAE;AAAA,EACnE,SAAS,OAAO;AACd,UAAM,SAA0B;AAAA,MAC9B,GAAG;AAAA,MACH,YAAY,KAAK,IAAI,IAAI;AAAA;AAAA,MAEzB,OAAO,UAAU,SAAY,IAAI,MAAM,sBAAsB,IAAI;AAAA,IACnE;AACA,QAAI,KAAK,eAAe,MAAM;AAC9B,UAAM;AAAA,EACR;AACA,QAAM,YAA6B,YAC/B,EAAE,GAAG,MAAM,YAAY,KAAK,IAAI,IAAI,OAAO,QAAQ,MAAM,IACzD,EAAE,GAAG,MAAM,YAAY,KAAK,IAAI,IAAI,MAAM;AAC9C,MAAI,KAAK,eAAe,SAAS;AACjC,SAAO;AACT;;;ACvBO,SAAS,SAAS,SAAkD;AACzE,SAAO,OAAO,YAAY,WAAW,CAAC,EAAE,MAAM,QAAQ,MAAM,QAAQ,CAAC,IAAI;AAC3E;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noetaris/harness-types",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Shared LLM type contract for the @noetaris/harness ecosystem",
   "type": "module",
   "repository": {
@@ -38,6 +38,7 @@
       "esbuild"
     ]
   },
+  "dependencies": {},
   "devDependencies": {
     "@types/node": "^25.8.0",
     "tsup": "^8.5.1",