@noetaris/harness-types 0.5.0 → 0.6.0

package/dist/index.d.ts

@@ -107,6 +107,12 @@ interface LLMRequestEvent {
     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.
+     */
+    callId?: string;
 }
 /**
  * Token-usage payload emitted by LLM adapters as an `"llm.response"` observer event.
@@ -127,6 +133,11 @@ interface LLMUsageEvent {
     providerName: string;
     output?: unknown;
     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 on `"tool.call"` before a tool is dispatched.

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\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\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\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` and `error` are opt-in — they may contain sensitive data; omit by default.\n * Set `error` when the tool threw; leave it absent on success.\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"],"mappings":";AAuCO,SAAS,SAAS,SAAkD;AACzE,SAAO,OAAO,YAAY,WAAW,CAAC,EAAE,MAAM,QAAQ,MAAM,QAAQ,CAAC,IAAI;AAC3E;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\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` and `error` are opt-in — they may contain sensitive data; omit by default.\n * Set `error` when the tool threw; leave it absent on success.\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"],"mappings":";AAuCO,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.5.0",
+  "version": "0.6.0",
   "description": "Shared LLM type contract for the @noetaris/harness ecosystem",
   "type": "module",
   "repository": {