@openharness/core 0.1.0

package/README.md

@@ -0,0 +1,267 @@
+# OpenHarness
+
+Claude Code, Codex, OpenCode et al. are amazing general purpose agent harnesses that go far beyond just software development.
+
+And while Anthropic offers the Claude Agent SDK, OpenAI now offers the Codex App Server, and OpenCode has a client to connect to an OpenCode instance, these harnesses are very "heavy" to use programmatically.
+
+OpenHarness is an open source project based on Vercel's AI SDK that aims to provide the building blocks to build very capable, general-purpose agents in code. It is inspired by all of the aforementioned coding agents.
+
+## Agents
+
+The `Agent` class is the core primitive. An agent wraps a language model, a set of tools, and a multi-step execution loop into a single object that you can `run()` with a prompt.
+
+```typescript
+import { Agent } from "@openharness/core";
+import { openai } from "@ai-sdk/openai";
+import { fsTools } from "@openharness/core/tools/fs";
+import { bash } from "@openharness/core/tools/bash";
+
+const agent = new Agent({
+  name: "dev",
+  model: openai("gpt-5.2"),
+  systemPrompt: "You are a helpful coding assistant.",
+  tools: { ...fsTools, bash },
+  maxSteps: 20,
+});
+```
+
+### Running an agent
+
+`agent.run()` is an async generator that yields a stream of typed events as the agent works. You iterate over these events to build any UI you want — a CLI, a web app, a log file, or nothing at all.
+
+```typescript
+for await (const event of agent.run("Refactor the auth module to use JWTs")) {
+  switch (event.type) {
+    case "text.delta":
+      process.stdout.write(event.text);
+      break;
+    case "tool.start":
+      console.log(`Calling ${event.toolName}...`);
+      break;
+    case "tool.done":
+      console.log(`${event.toolName} finished`);
+      break;
+    case "done":
+      console.log(`Result: ${event.result}, tokens: ${event.totalUsage.totalTokens}`);
+      break;
+  }
+}
+```
+
+The agent maintains conversation history across `run()` calls, so you can use it in a loop for multi-turn interactions.
+
+### Events
+
+The full set of events emitted by `run()`:
+
+| Event | Description |
+| --- | --- |
+| `text.delta` | Streamed text chunk from the model |
+| `text.done` | Full text for the current step is complete |
+| `reasoning.delta` | Streamed reasoning/thinking chunk (if the model supports it) |
+| `reasoning.done` | Full reasoning text for the step is complete |
+| `tool.start` | A tool call has been initiated |
+| `tool.done` | A tool call completed successfully |
+| `tool.error` | A tool call failed |
+| `step.start` | A new agentic step is starting |
+| `step.done` | A step completed (includes token usage and finish reason) |
+| `error` | An error occurred during execution |
+| `done` | The agent has finished. `result` is one of `"complete"`, `"stopped"`, `"max_steps"`, or `"error"` |
+
+### Configuration
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `name` | (required) | Agent name, used in logging and subagent selection |
+| `model` | (required) | Any Vercel AI SDK `LanguageModel` |
+| `systemPrompt` | — | System prompt prepended to every request |
+| `tools` | — | AI SDK `ToolSet` — the tools the agent can call |
+| `maxSteps` | `100` | Maximum agentic steps before stopping |
+| `temperature` | — | Sampling temperature |
+| `maxTokens` | — | Max output tokens per step |
+| `instructions` | `true` | Whether to load `AGENTS.md` / `CLAUDE.md` from the project directory |
+| `approve` | — | Callback for tool call approval (see [Permissions](#permissions)) |
+| `subagents` | — | Child agents available via the `task` tool (see [Subagents](#subagents)) |
+| `mcpServers` | — | MCP servers to connect to (see [MCP Servers](#mcp-servers)) |
+
+## Tools
+
+Tools use the Vercel AI SDK `tool()` helper with Zod schemas. OpenHarness ships a set of built-in tools that you can use as-is, compose, or replace entirely.
+
+### Filesystem tools (`@openharness/core/tools/fs`)
+
+| Tool | Description |
+| --- | --- |
+| `readFile` | Read file contents (supports line offset/limit) |
+| `writeFile` | Write content to a file (creates parent dirs) |
+| `editFile` | Find-and-replace within a file |
+| `listFiles` | List files/directories (optionally recursive) |
+| `grep` | Regex search across files (skips `node_modules`, `.git`) |
+| `deleteFile` | Delete a file or directory |
+
+All are exported individually and also grouped as `fsTools`.
+
+### Bash tool (`@openharness/core/tools/bash`)
+
+Runs arbitrary shell commands via `bash -c`. Configurable timeout (default 30s, max 5min) and automatic output truncation.
+
+### Custom tools
+
+Any AI SDK-compatible tool works. Just define it with `tool()` from the `ai` package:
+
+```typescript
+import { tool } from "ai";
+import { z } from "zod";
+
+const myTool = tool({
+  description: "Do something useful",
+  inputSchema: z.object({ query: z.string() }),
+  execute: async ({ query }) => {
+    return { result: `You asked: ${query}` };
+  },
+});
+
+const agent = new Agent({
+  name: "my-agent",
+  model: openai("gpt-5.2"),
+  tools: { myTool },
+});
+```
+
+## Permissions
+
+By default, all tool calls are allowed. To gate tool execution — for example, prompting a user for confirmation — pass an `approve` callback:
+
+```typescript
+const agent = new Agent({
+  name: "safe-agent",
+  model: openai("gpt-5.2"),
+  tools: { ...fsTools, bash },
+  approve: async ({ toolName, toolCallId, input }) => {
+    // Return true to allow, false to deny
+    const answer = await askUser(`Allow ${toolName}?`);
+    return answer === "yes";
+  },
+});
+```
+
+When a tool call is denied, a `ToolDeniedError` is thrown and surfaced to the model as a tool error, so it can adjust its approach.
+
+The callback receives a `ToolCallInfo` object:
+
+```typescript
+interface ToolCallInfo {
+  toolName: string;
+  toolCallId: string;
+  input: unknown;
+}
+```
+
+The callback can be async — you can prompt a user in a terminal, show a modal in a web UI, or call an external approval service.
+
+## Subagents
+
+Agents can delegate work to other agents. When you pass a `subagents` array, a `task` tool is automatically generated that lets the parent agent spawn child agents by name.
+
+```typescript
+const explore = new Agent({
+  name: "explore",
+  description: "Read-only codebase exploration. Use for searching and reading files.",
+  model: openai("gpt-5.2"),
+  tools: { readFile, listFiles, grep },
+  maxSteps: 30,
+});
+
+const agent = new Agent({
+  name: "dev",
+  model: openai("gpt-5.2"),
+  tools: { ...fsTools, bash },
+  subagents: [explore],
+});
+```
+
+The parent model sees a `task` tool with a description listing the available subagents and their descriptions. It can call `task` with an `agent` name and a `prompt`, and the subagent runs to completion autonomously.
+
+Key behaviors:
+
+- **Fresh instance per task** — each `task` call creates a new agent with no shared conversation state
+- **No approval** — subagents run autonomously without prompting for permission
+- **No nesting** — subagents cannot themselves have subagents
+- **Abort propagation** — the parent's abort signal is forwarded to the child
+- **Concurrent execution** — the model can call `task` multiple times in one response to run subagents in parallel
+
+### Live subagent events
+
+To observe what subagents are doing in real time, pass an `onSubagentEvent` callback:
+
+```typescript
+const agent = new Agent({
+  name: "dev",
+  model: openai("gpt-5.2"),
+  tools: { ...fsTools, bash },
+  subagents: [explore],
+  onSubagentEvent: (agentName, event) => {
+    if (event.type === "tool.done") {
+      console.log(`[${agentName}] ${event.toolName} completed`);
+    }
+  },
+});
+```
+
+The callback receives the same `AgentEvent` types as the parent's `run()` generator.
+
+## AGENTS.md
+
+OpenHarness supports the [AGENTS.md](https://agents.md) spec. On first run, the agent walks up from the current directory to the filesystem root looking for `AGENTS.md` or `CLAUDE.md`. The first file found is loaded and prepended to the system prompt.
+
+This is enabled by default. Set `instructions: false` to disable it.
+
+## MCP Servers
+
+Agents can connect to [Model Context Protocol](https://modelcontextprotocol.io) servers. Tools from MCP servers are merged into the agent's toolset alongside any static tools.
+
+```typescript
+const agent = new Agent({
+  name: "dev",
+  model: openai("gpt-5.2"),
+  tools: { ...fsTools, bash },
+  mcpServers: {
+    github: {
+      type: "stdio",
+      command: "npx",
+      args: ["-y", "@modelcontextprotocol/server-github"],
+      env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN },
+    },
+    weather: {
+      type: "http",
+      url: "https://weather-mcp.example.com/mcp",
+      headers: { Authorization: "Bearer ..." },
+    },
+  },
+});
+
+// MCP connections are established lazily on first run()
+for await (const event of agent.run("What PRs are open?")) { ... }
+
+// Clean up MCP connections when done
+await agent.close();
+```
+
+Three transport types are supported:
+
+| Transport | Use case |
+| --- | --- |
+| `stdio` | Local servers — spawns a child process, communicates over stdin/stdout |
+| `http` | Remote servers via Streamable HTTP (recommended for production) |
+| `sse` | Remote servers via Server-Sent Events (legacy) |
+
+When multiple MCP servers are configured, tools are namespaced as `serverName_toolName` to avoid collisions. With a single server, tool names are used as-is.
+
+## Example CLI
+
+[`example/cli.ts`](example/cli.ts) is a fully working agent CLI that ties everything together — tool approval prompts, ora spinners, streamed output, and live subagent display. It's a good reference for how to wire up all the primitives into an interactive application.
+
+```bash
+# requires a .env file with OPENAI_API_KEY
+pnpm cli
+```

package/dist/agent.d.ts

@@ -0,0 +1,122 @@
+import { type LanguageModel, type ToolSet, type ModelMessage } from "ai";
+import { type MCPServerConfig } from "./mcp.js";
+export interface TokenUsage {
+    inputTokens: number | undefined;
+    outputTokens: number | undefined;
+    totalTokens: number | undefined;
+}
+export type AgentEvent = {
+    type: "text.delta";
+    text: string;
+} | {
+    type: "text.done";
+    text: string;
+} | {
+    type: "reasoning.delta";
+    text: string;
+} | {
+    type: "reasoning.done";
+    text: string;
+} | {
+    type: "tool.start";
+    toolCallId: string;
+    toolName: string;
+    input: unknown;
+} | {
+    type: "tool.done";
+    toolCallId: string;
+    toolName: string;
+    output: unknown;
+} | {
+    type: "tool.error";
+    toolCallId: string;
+    toolName: string;
+    error: string;
+} | {
+    type: "step.start";
+    stepNumber: number;
+} | {
+    type: "step.done";
+    stepNumber: number;
+    usage: TokenUsage;
+    finishReason: string;
+} | {
+    type: "error";
+    error: Error;
+} | {
+    type: "done";
+    result: "complete" | "stopped" | "max_steps" | "error";
+    messages: ModelMessage[];
+    totalUsage: TokenUsage;
+};
+export interface ToolCallInfo {
+    toolName: string;
+    toolCallId: string;
+    input: unknown;
+}
+/**
+ * Called before each tool execution. Return `true` to allow, `false` to deny.
+ * Can be async — e.g. to prompt a user in a custom UI.
+ */
+export type ApproveFn = (toolCall: ToolCallInfo) => boolean | Promise<boolean>;
+/** Called for every event emitted by a subagent during a task tool call. */
+export type SubagentEventFn = (agentName: string, event: AgentEvent) => void;
+export declare class Agent {
+    readonly name: string;
+    readonly description?: string;
+    readonly model: LanguageModel;
+    readonly systemPrompt?: string;
+    readonly maxSteps: number;
+    readonly temperature?: number;
+    readonly maxTokens?: number;
+    readonly instructions: boolean;
+    readonly approve?: ApproveFn;
+    readonly onSubagentEvent?: SubagentEventFn;
+    /** Static tools provided at construction time. */
+    readonly tools?: ToolSet;
+    /** MCP server configs — connected lazily on first run. */
+    private mcpServerConfigs?;
+    private mcpConnection;
+    private messages;
+    private cachedInstructions;
+    constructor(options: {
+        name: string;
+        /** Short description of this agent's purpose. Used in the task tool for subagent selection. */
+        description?: string;
+        model: LanguageModel;
+        systemPrompt?: string;
+        tools?: ToolSet;
+        maxSteps?: number;
+        temperature?: number;
+        maxTokens?: number;
+        /** Load AGENTS.md / CLAUDE.md from the project directory. Defaults to true. */
+        instructions?: boolean;
+        /**
+         * Called before each tool execution. Return `true` to allow, `false` to deny.
+         * When omitted, all tool calls are allowed.
+         */
+        approve?: ApproveFn;
+        /** Agents available as subagents via the auto-generated `task` tool. */
+        subagents?: Agent[];
+        /** Called for every event emitted by a subagent during a task tool call. */
+        onSubagentEvent?: SubagentEventFn;
+        /**
+         * MCP servers to connect to. Tools from these servers are merged into
+         * the agent's toolset. Connections are established lazily on first run.
+         *
+         * Keys are server names (used to namespace tools when multiple servers are configured).
+         */
+        mcpServers?: Record<string, MCPServerConfig>;
+    });
+    /**
+     * Close all MCP server connections. Call this when the agent is no longer needed.
+     */
+    close(): Promise<void>;
+    run(input: string | ModelMessage[], options?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<AgentEvent>;
+}
+export declare class ToolDeniedError extends Error {
+    constructor(toolName: string);
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}

package/dist/agent.js

@@ -0,0 +1,279 @@
+import { tool, streamText, stepCountIs, } from "ai";
+import { z } from "zod";
+import { loadInstructions } from "./instructions.js";
+import { connectMCPServers, closeMCPClients, } from "./mcp.js";
+// ── Agent ────────────────────────────────────────────────────────────
+export class Agent {
+    name;
+    description;
+    model;
+    systemPrompt;
+    maxSteps;
+    temperature;
+    maxTokens;
+    instructions;
+    approve;
+    onSubagentEvent;
+    /** Static tools provided at construction time. */
+    tools;
+    /** MCP server configs — connected lazily on first run. */
+    mcpServerConfigs;
+    mcpConnection = null;
+    messages = [];
+    cachedInstructions = null; // null = not loaded yet
+    constructor(options) {
+        this.name = options.name;
+        this.description = options.description;
+        this.model = options.model;
+        this.systemPrompt = options.systemPrompt;
+        this.maxSteps = options.maxSteps ?? 100;
+        this.temperature = options.temperature;
+        this.maxTokens = options.maxTokens;
+        this.instructions = options.instructions ?? true;
+        this.approve = options.approve;
+        this.onSubagentEvent = options.onSubagentEvent;
+        this.mcpServerConfigs = options.mcpServers;
+        // Merge the task tool into the toolset when subagents are provided
+        if (options.subagents?.length) {
+            this.tools = {
+                ...(options.tools ?? {}),
+                task: createTaskTool(options.subagents, this.onSubagentEvent),
+            };
+        }
+        else {
+            this.tools = options.tools;
+        }
+    }
+    /**
+     * Close all MCP server connections. Call this when the agent is no longer needed.
+     */
+    async close() {
+        if (this.mcpConnection) {
+            await closeMCPClients(this.mcpConnection.clients);
+            this.mcpConnection = null;
+        }
+    }
+    async *run(input, options) {
+        if (typeof input === "string") {
+            this.messages.push({ role: "user", content: input });
+        }
+        else {
+            this.messages.push(...input);
+        }
+        // Load AGENTS.md once per agent lifetime
+        if (this.instructions && this.cachedInstructions === null) {
+            this.cachedInstructions = await loadInstructions();
+        }
+        // Connect MCP servers once per agent lifetime
+        if (this.mcpServerConfigs && !this.mcpConnection) {
+            this.mcpConnection = await connectMCPServers(this.mcpServerConfigs);
+        }
+        const systemParts = [this.systemPrompt, this.cachedInstructions].filter(Boolean);
+        const system = systemParts.length > 0 ? systemParts.join("\n\n") : undefined;
+        // Merge static tools with MCP tools
+        const allTools = {
+            ...(this.tools ?? {}),
+            ...(this.mcpConnection?.tools ?? {}),
+        };
+        const tools = this.approve && Object.keys(allTools).length > 0
+            ? wrapToolsWithApproval(allTools, this.approve)
+            : Object.keys(allTools).length > 0
+                ? allTools
+                : undefined;
+        const stream = streamText({
+            model: this.model,
+            system,
+            messages: this.messages,
+            tools,
+            stopWhen: stepCountIs(this.maxSteps),
+            temperature: this.temperature,
+            maxOutputTokens: this.maxTokens,
+            abortSignal: options?.signal,
+        });
+        let stepNumber = 0;
+        let stepText = "";
+        let stepReasoning = "";
+        try {
+            for await (const part of stream.fullStream) {
+                switch (part.type) {
+                    case "start-step":
+                        stepNumber++;
+                        stepText = "";
+                        stepReasoning = "";
+                        yield { type: "step.start", stepNumber };
+                        break;
+                    case "text-delta":
+                        stepText += part.text;
+                        yield { type: "text.delta", text: part.text };
+                        break;
+                    case "text-end":
+                        if (stepText) {
+                            yield { type: "text.done", text: stepText };
+                        }
+                        break;
+                    case "reasoning-delta":
+                        stepReasoning += part.text;
+                        yield { type: "reasoning.delta", text: part.text };
+                        break;
+                    case "reasoning-end":
+                        if (stepReasoning) {
+                            yield { type: "reasoning.done", text: stepReasoning };
+                        }
+                        break;
+                    case "tool-call":
+                        yield {
+                            type: "tool.start",
+                            toolCallId: part.toolCallId,
+                            toolName: part.toolName,
+                            input: part.input,
+                        };
+                        break;
+                    case "tool-result":
+                        yield {
+                            type: "tool.done",
+                            toolCallId: part.toolCallId,
+                            toolName: part.toolName,
+                            output: part.output,
+                        };
+                        break;
+                    case "tool-error":
+                        yield {
+                            type: "tool.error",
+                            toolCallId: part.toolCallId,
+                            toolName: part.toolName,
+                            error: String(part.error),
+                        };
+                        break;
+                    case "finish-step":
+                        yield {
+                            type: "step.done",
+                            stepNumber,
+                            usage: toTokenUsage(part.usage),
+                            finishReason: part.finishReason,
+                        };
+                        break;
+                    case "error":
+                        yield {
+                            type: "error",
+                            error: part.error instanceof Error ? part.error : new Error(String(part.error)),
+                        };
+                        break;
+                    case "finish": {
+                        const result = part.finishReason === "stop"
+                            ? "complete"
+                            : part.finishReason === "tool-calls"
+                                ? "max_steps"
+                                : part.finishReason === "error"
+                                    ? "error"
+                                    : "stopped";
+                        const response = await stream.response;
+                        this.messages.push(...response.messages);
+                        yield {
+                            type: "done",
+                            result,
+                            messages: this.messages,
+                            totalUsage: toTokenUsage(part.totalUsage),
+                        };
+                        break;
+                    }
+                }
+            }
+        }
+        catch (error) {
+            yield {
+                type: "error",
+                error: error instanceof Error ? error : new Error(String(error)),
+            };
+            yield {
+                type: "done",
+                result: "error",
+                messages: this.messages,
+                totalUsage: { inputTokens: undefined, outputTokens: undefined, totalTokens: undefined },
+            };
+        }
+    }
+}
+// ── Subagent task tool ───────────────────────────────────────────────
+function createTaskTool(subagents, onSubagentEvent) {
+    const names = subagents.map((a) => a.name);
+    const byName = new Map(subagents.map((a) => [a.name, a]));
+    const listing = subagents.map((a) => `- ${a.name}: ${a.description ?? a.name}`).join("\n");
+    return tool({
+        description: [
+            "Spawn a subagent to handle a task autonomously.",
+            "The subagent runs with its own tools, completes the work, and returns the result.",
+            "Launch multiple agents concurrently when possible by calling this tool multiple times in one response.",
+            "",
+            "Available agents:",
+            listing,
+        ].join("\n"),
+        inputSchema: z.object({
+            agent: z.enum(names).describe("Which agent to use"),
+            prompt: z.string().describe("Detailed task description for the subagent"),
+        }),
+        execute: async ({ agent: agentName, prompt }, { abortSignal }) => {
+            const template = byName.get(agentName);
+            // Fresh agent instance for each task — no shared state
+            const child = new Agent({
+                name: template.name,
+                model: template.model,
+                systemPrompt: template.systemPrompt,
+                tools: template.tools,
+                maxSteps: template.maxSteps,
+                temperature: template.temperature,
+                maxTokens: template.maxTokens,
+                instructions: template.instructions,
+                // No approve — subagents run autonomously
+                // No subagents — prevent recursive nesting
+            });
+            let lastText = "";
+            for await (const event of child.run(prompt, { signal: abortSignal })) {
+                onSubagentEvent?.(agentName, event);
+                if (event.type === "text.done") {
+                    lastText = event.text;
+                }
+            }
+            return `<task_result>\n${lastText || "(no output)"}\n</task_result>`;
+        },
+    });
+}
+// ── Helpers ──────────────────────────────────────────────────────────
+function toTokenUsage(usage) {
+    return {
+        inputTokens: usage.inputTokens,
+        outputTokens: usage.outputTokens,
+        totalTokens: usage.totalTokens,
+    };
+}
+function wrapToolsWithApproval(tools, approve) {
+    const wrapped = {};
+    for (const [name, t] of Object.entries(tools)) {
+        if (!t.execute) {
+            wrapped[name] = t;
+            continue;
+        }
+        const originalExecute = t.execute;
+        wrapped[name] = {
+            ...t,
+            execute: async (input, options) => {
+                const allowed = await approve({
+                    toolName: name,
+                    toolCallId: options.toolCallId,
+                    input,
+                });
+                if (!allowed) {
+                    throw new ToolDeniedError(name);
+                }
+                return originalExecute(input, options);
+            },
+        };
+    }
+    return wrapped;
+}
+export class ToolDeniedError extends Error {
+    constructor(toolName) {
+        super(`Tool call to "${toolName}" was denied.`);
+        this.name = "ToolDeniedError";
+    }
+}
+//# sourceMappingURL=agent.js.map