@noetaris/harness-types 0.1.0

package/README.md

@@ -0,0 +1,51 @@
+# @noetaris/harness-types
+
+Shared LLM type contract for the [@noetaris/harness](../core) ecosystem.
+
+This package defines the common TypeScript interfaces that all LLM adapter packages implement. The core harness never imports these types — they are an ecosystem convention that lets adapters be structurally interchangeable.
+
+## Overview
+
+`@noetaris/harness-types` is a types-only package with zero runtime code and zero dependencies. It provides the canonical definitions for messages, tools, and the `LLM` interface — the surface that all adapters (Anthropic, OpenAI, Gemini, etc.) must satisfy.
+
+## Types
+
+| Type | Description |
+|------|-------------|
+| `Message` | Discriminated union: `{ role: 'user'; content: string }` \| `{ role: 'assistant'; content?: string; toolCalls?: ToolCall[] }` \| `{ role: 'tool'; toolCallId: string; content: string }` |
+| `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' }` |
+| `LLMUsageEvent` | `{ tokens: { input: number; output: number }; modelId: string; stopReason: LLMResponse['stopReason'] }` |
+| `LLM` | `{ invoke(messages: Message[], options?: { tools?: Tool[] }): Promise<LLMResponse> }` |
+
+## Installation
+
+```sh
+pnpm add @noetaris/harness-types
+```
+
+Requires Node.js ≥ 22.
+
+## Usage
+
+```ts
+import type { LLM, Message, LLMResponse, Tool } from '@noetaris/harness-types'
+
+class MyAdapter implements LLM {
+  async invoke(messages: Message[], options?: { tools?: Tool[] }): Promise<LLMResponse> {
+    // ...
+  }
+}
+```
+
+## Related Packages
+
+- [`@noetaris/harness`](https://github.com/noetaris-lab/harness) — core execution engine
+- [`@noetaris/harness-anthropic`](https://github.com/noetaris-lab/harness-anthropic) — Anthropic Claude adapter
+- [`@noetaris/harness-openai`](https://github.com/noetaris-lab/harness-openai) — OpenAI adapter
+- [`@noetaris/harness-google`](https://github.com/noetaris-lab/harness-google) — Google Gemini adapter
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Shared LLM protocol types used by all harness LLM adapters.
+ *
+ * @packageDocumentation
+ */
+/**
+ * A single turn in a conversation.
+ *
+ * - `user` — text input from the human side.
+ * - `assistant` — model reply, optionally carrying tool-call requests.
+ * - `tool` — result returned to the model after a tool call.
+ */
+type Message = {
+    role: 'user';
+    content: string;
+} | {
+    role: 'assistant';
+    content?: string;
+    toolCalls?: ToolCall[];
+} | {
+    role: 'tool';
+    toolCallId: string;
+    content: string;
+};
+/**
+ * A tool the LLM may invoke during a conversation turn.
+ *
+ * `inputSchema` must be a valid JSON Schema object describing the tool's
+ * input parameters (LLM adapters pass it to the provider as-is).
+ */
+interface Tool {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+/**
+ * A single tool-call request emitted by the LLM in an assistant turn.
+ *
+ * `id` is provider-assigned and must be echoed back in the corresponding
+ * `role: 'tool'` message so the model can correlate results.
+ */
+interface ToolCall {
+    id: string;
+    name: string;
+    input: unknown;
+}
+/**
+ * Normalized response returned by every {@link LLM} adapter.
+ *
+ * `text` may be empty when `stopReason` is `'tool_use'`.
+ * `toolCalls` is empty when `stopReason` is `'end'` or `'max_tokens'`.
+ */
+interface LLMResponse {
+    text: string;
+    toolCalls: ToolCall[];
+    stopReason: 'end' | 'tool_use' | 'max_tokens';
+}
+/**
+ * Token-usage payload emitted by LLM adapters as an `llm.response` observer event.
+ *
+ * Adapters that cannot report real token counts (e.g. mock adapters) emit `{ input: 0, output: 0 }`.
+ */
+interface LLMUsageEvent {
+    tokens: {
+        input: number;
+        output: number;
+    };
+    modelId: string;
+    stopReason: LLMResponse['stopReason'];
+}
+/**
+ * Core interface every LLM adapter must implement.
+ *
+ * @example
+ * ```ts
+ * const response = await llm.invoke(messages, { tools: [myTool] })
+ * ```
+ */
+interface LLM {
+    /**
+     * Send a message list to the LLM and return a normalized response.
+     *
+     * @param messages - Conversation history, oldest first.
+     * @param options.tools - Optional tools the model may invoke.
+     */
+    invoke(messages: Message[], options?: {
+        tools?: Tool[];
+    }): Promise<LLMResponse>;
+}
+
+export type { LLM, LLMResponse, LLMUsageEvent, Message, Tool, ToolCall };

package/dist/index.js

@@ -0,0 +1 @@
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@noetaris/harness-types",
+  "version": "0.1.0",
+  "description": "Shared LLM type contract for the @noetaris/harness ecosystem",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/noetaris-lab/harness-types.git"
+  },
+  "homepage": "https://github.com/noetaris-lab/harness-types#readme",
+  "bugs": {
+    "url": "https://github.com/noetaris-lab/harness-types/issues"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "pnpm build && pnpm test",
+    "publish:npm": "pnpm publish --access public --no-git-checks"
+  },
+  "files": [
+    "dist"
+  ],
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
+  },
+  "devDependencies": {
+    "@types/node": "^25.8.0",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6"
+  }
+}