@botbotgo/agent-harness 0.0.22 → 0.0.24

package/README.md

@@ -9,7 +9,9 @@ It helps developers:
 - define agents in YAML
 - keep workspace behavior in `config/workspace.yaml`
 - keep shared bootstrap context in `config/agent-context.md`
-- discover tools and skills from `resources/`
+- discover tools and SKILL packages from `resources/`
+- bridge remote MCP servers into agent toolsets
+- expose harness-managed tools as an MCP server
 - run through either LangChain v1 or DeepAgents with one app-facing API
 
 Why it works:
@@ -54,6 +56,8 @@ your-workspace/
     skills/
 ```
 
+Use the standard layout only. Agent entry files must live under `config/agents/`; root-level files such as `agent.yaml`, `orchestra.yaml`, and `direct.yaml` are not loaded.
+
 Minimal usage:
 
 ```ts
@@ -78,7 +82,9 @@ try {
 - One workspace for agents, models, tools, and runtime behavior
 - One API for both LangChain v1 and DeepAgents
 - Built-in routing for direct and orchestration flows
-- Auto-discovered local tools and skills from `resources/tools/` and `resources/skills/`
+- Auto-discovered local tools and SKILL packages from `resources/tools/` and `resources/skills/`
+- MCP bridge support: agent YAML can mount remote or local MCP servers as agent tools
+- MCP server support: expose harness-managed tools over stdio or an in-memory MCP server
 - Built-in thread state, approvals, resumable runs, and long-term memory
 - MCP server helpers plus background checkpoint maintenance
 
@@ -146,6 +152,51 @@ const result = await run(harness, {
 });
 ```
 
+### Use Skills And Local Tools
+
+`agent-harness` treats `resources/skills/` as SKILL packages and `resources/tools/` as executable local tools.
+
+Point agent YAML at both:
+
+```yaml
+spec:
+  skills:
+    - path: resources/skills/reviewer
+  tools:
+    - ref: tool/local-toolset
+```
+
+### Bridge MCP Servers Into Agents
+
+Use `mcpServers:` inside agent YAML to bridge MCP servers into the agent's tool list:
+
+```yaml
+spec:
+  mcpServers:
+    - name: browser
+      command: node
+      args: ["./mcp-browser-server.mjs"]
+    - name: docs
+      transport: http
+      url: https://example.com/mcp
+      token: ${DOCS_MCP_TOKEN}
+```
+
+The harness discovers MCP tools, filters them through the agent config, and exposes them to the runtime like any other tool.
+
+### Expose Harness Tools As An MCP Server
+
+Use the MCP server helpers when another client should connect to the harness as an MCP server:
+
+```ts
+import { createToolMcpServer, serveToolsOverStdio } from "@botbotgo/agent-harness";
+
+const server = await createToolMcpServer(harness, { agentId: "orchestra" });
+await serveToolsOverStdio(harness, { agentId: "orchestra" });
+```
+
+If you omit `serverInfo`, the harness uses `agent-harness-<agentId>` as the MCP server name and the current package version as the server version.
+
 ### Read Back Thread State
 
 ```ts
@@ -221,6 +272,12 @@ Use `config/agents/*.yaml` to configure agents. Common fields include:
 Use `resources/` for executable extensions:
 
 - `resources/tools/` for local tool modules
-- `resources/skills/` for skill packages
+- `resources/skills/` for SKILL packages
 
 Each resource package should include its own `package.json`.
+
+### Skills And MCP
+
+- Use `resources/skills/` for SKILL packages that carry reusable instructions, templates, scripts, and metadata
+- Use `mcpServers:` in `config/agents/*.yaml` when you want the harness to bridge external MCP tools into an agent
+- Use `createToolMcpServer(...)` or `serveToolsOverStdio(...)` when you want the harness itself to act as an MCP server for another client

package/dist/config/models.yaml

@@ -0,0 +1,29 @@
+# agent-harness feature: schema version for this declarative config object.
+apiVersion: agent-harness/v1alpha1
+# agent-harness feature: object type for named model presets.
+kind: Models
+spec:
+  - name: default
+    # ====================
+    # LangChain v1 Features
+    # ====================
+    # LangChain aligned feature: provider family or integration namespace.
+    # Common options in this harness today include:
+    # - `ollama`
+    # - `openai`
+    # - `openai-compatible`
+    # - `anthropic`
+    # - `google` / `google-genai` / `gemini`
+    # The runtime adapter uses this to select the concrete LangChain chat model implementation.
+    provider: ollama
+    # LangChain aligned feature: concrete model identifier passed to the selected provider integration.
+    # Example values depend on `provider`, such as `gpt-oss:latest` for `ollama`.
+    model: gpt-oss:latest
+    init:
+      # LangChain aligned feature: provider-specific initialization options.
+      # Available keys are provider-specific; common examples include `baseUrl`, `temperature`, and auth/client settings.
+      # `baseUrl` configures the Ollama-compatible endpoint used by the model client.
+      # For `openai-compatible`, `baseUrl` is normalized into the ChatOpenAI `configuration.baseURL` field.
+      baseUrl: https://ollama-rtx-4070.easynet.world/
+      # LangChain aligned feature: provider/model initialization option controlling sampling temperature.
+      temperature: 0.2

package/dist/mcp.js

@@ -2,6 +2,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { pathToFileURL } from "node:url";
 import { z } from "zod";
+import { AGENT_HARNESS_VERSION } from "./package-version.js";
 import { loadToolModuleDefinition } from "./tool-modules.js";
 function asResolvedTool(value) {
     return typeof value === "object" && value !== null ? value : null;
@@ -86,7 +87,7 @@ function jsonSchemaToZod(schema) {
 export async function createToolMcpServerFromHarness(harness, options) {
     const server = new McpServer({
         name: options.serverInfo?.name ?? `agent-harness-${options.agentId}`,
-        version: options.serverInfo?.version ?? "0.0.16",
+        version: options.serverInfo?.version ?? AGENT_HARNESS_VERSION,
     });
     const allowedNames = options.includeToolNames ? new Set(options.includeToolNames) : null;
     for (const { compiledTool, resolvedTool } of harness.resolveAgentTools(options.agentId)) {

package/dist/package-version.d.ts

@@ -0,0 +1 @@
+export declare const AGENT_HARNESS_VERSION = "0.0.23";

package/dist/package-version.js

@@ -0,0 +1 @@
+export const AGENT_HARNESS_VERSION = "0.0.23";

package/dist/resource/resource-impl.js

@@ -9,6 +9,7 @@ import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { WebSocketClientTransport } from "@modelcontextprotocol/sdk/client/websocket.js";
+import { AGENT_HARNESS_VERSION } from "../package-version.js";
 import { isSupportedToolModulePath, loadToolModuleDefinition } from "../tool-modules.js";
 import { resolveIsolatedResourceModulePath } from "./isolation.js";
 import { ensureExternalResourceSource, ensureExternalSource, isExternalSourceLocator, parseExternalSourceLocator } from "./sources.js";
@@ -176,7 +177,7 @@ export async function getOrCreateMcpClient(config) {
     const loading = (async () => {
         const client = new Client({
             name: "agent-harness",
-            version: "0.0.16",
+            version: AGENT_HARNESS_VERSION,
         });
         const headers = {
             ...(config.headers ?? {}),

package/dist/runtime/harness.d.ts

@@ -44,6 +44,15 @@ export declare class AgentHarness {
         threadId?: string;
     }): Promise<string>;
     private emit;
+    private ensureThreadStarted;
+    private loadPriorHistory;
+    private appendAssistantMessage;
+    private invokeWithHistory;
+    private emitOutputDeltaAndCreateItem;
+    private emitRunCreated;
+    private setRunStateAndEmit;
+    private requestApprovalAndEmit;
+    private emitSyntheticFallback;
     private persistApproval;
     private resolveApprovalRecord;
     private isDecisionRun;

package/dist/runtime/harness.js

@@ -269,6 +269,95 @@ export class AgentHarness {
         this.eventBus.publish(event);
         return event;
     }
+    async ensureThreadStarted(selectedAgentId, binding, input, existingThreadId) {
+        const threadId = existingThreadId ?? createPersistentId();
+        const runId = createPersistentId();
+        const createdAt = new Date().toISOString();
+        if (!existingThreadId) {
+            await this.persistence.createThread({
+                threadId,
+                agentId: selectedAgentId,
+                runId,
+                status: "running",
+                createdAt,
+            });
+        }
+        await this.persistence.appendThreadMessage(threadId, {
+            role: "user",
+            content: input,
+            runId,
+            createdAt,
+        });
+        await this.persistence.createRun({
+            threadId,
+            runId,
+            agentId: binding.agent.id,
+            executionMode: binding.agent.executionMode,
+            createdAt,
+        });
+        return { threadId, runId, createdAt };
+    }
+    async loadPriorHistory(threadId, runId) {
+        const history = await this.persistence.listThreadMessages(threadId);
+        return history.filter((message) => message.runId !== runId);
+    }
+    async appendAssistantMessage(threadId, runId, content) {
+        if (!content) {
+            return;
+        }
+        await this.persistence.appendThreadMessage(threadId, {
+            role: "assistant",
+            content,
+            runId,
+            createdAt: new Date().toISOString(),
+        });
+    }
+    async invokeWithHistory(binding, input, threadId, runId, resumePayload) {
+        const priorHistory = await this.loadPriorHistory(threadId, runId);
+        return this.runtimeAdapter.invoke(binding, input, threadId, runId, resumePayload, priorHistory);
+    }
+    async emitOutputDeltaAndCreateItem(threadId, runId, agentId, content) {
+        await this.emit(threadId, runId, 3, "output.delta", {
+            content,
+        });
+        return {
+            type: "content",
+            threadId,
+            runId,
+            agentId,
+            content,
+        };
+    }
+    async emitRunCreated(threadId, runId, payload) {
+        return this.emit(threadId, runId, 1, "run.created", payload);
+    }
+    async setRunStateAndEmit(threadId, runId, sequence, state, options) {
+        await this.persistence.setRunState(threadId, runId, state, options.checkpointRef ?? null);
+        return this.emit(threadId, runId, sequence, "run.state.changed", {
+            previousState: options.previousState,
+            state,
+            checkpointRef: options.checkpointRef ?? null,
+            ...(options.error ? { error: options.error } : {}),
+        });
+    }
+    async requestApprovalAndEmit(threadId, runId, input, interruptContent, checkpointRef, sequence) {
+        const approval = await this.persistApproval(threadId, runId, checkpointRef, input, interruptContent);
+        const event = await this.emit(threadId, runId, sequence, "approval.requested", {
+            approvalId: approval.approvalId,
+            pendingActionId: approval.pendingActionId,
+            toolName: approval.toolName,
+            toolCallId: approval.toolCallId,
+            allowedDecisions: approval.allowedDecisions,
+            checkpointRef,
+        });
+        return { approval, event };
+    }
+    async emitSyntheticFallback(threadId, runId, selectedAgentId, error, sequence = 3) {
+        await this.emit(threadId, runId, sequence, "runtime.synthetic_fallback", {
+            reason: error instanceof Error ? error.message : String(error),
+            selectedAgentId,
+        });
+    }
     async persistApproval(threadId, runId, checkpointRef, input, interruptContent) {
         const approval = createPendingApproval(threadId, runId, checkpointRef, input, interruptContent);
         await this.persistence.createApproval(approval);
@@ -381,68 +470,25 @@ export class AgentHarness {
         if (!policyDecision.allowed) {
             throw new Error(`Policy evaluation blocked agent ${selectedAgentId}: ${policyDecision.reasons.join(", ")}`);
         }
-        const threadId = options.threadId ?? createPersistentId();
-        const runId = createPersistentId();
-        const createdAt = new Date().toISOString();
-        if (!options.threadId) {
-            await this.persistence.createThread({
-                threadId,
-                agentId: selectedAgentId,
-                runId,
-                status: "running",
-                createdAt,
-            });
-        }
-        await this.persistence.appendThreadMessage(threadId, {
-            role: "user",
-            content: options.input,
-            runId,
-            createdAt,
-        });
-        await this.persistence.createRun({
-            threadId,
-            runId,
-            agentId: binding.agent.id,
-            executionMode: binding.agent.executionMode,
-            createdAt,
-        });
-        await this.emit(threadId, runId, 1, "run.created", {
+        const { threadId, runId } = await this.ensureThreadStarted(selectedAgentId, binding, options.input, options.threadId);
+        await this.emitRunCreated(threadId, runId, {
             agentId: binding.agent.id,
             requestedAgentId: options.agentId ?? AUTO_AGENT_ID,
             selectedAgentId,
             executionMode: binding.agent.executionMode,
         });
         try {
-            const history = await this.persistence.listThreadMessages(threadId);
-            const priorHistory = history.filter((message) => message.runId !== runId);
-            const actual = await this.runtimeAdapter.invoke(binding, options.input, threadId, runId, undefined, priorHistory);
+            const actual = await this.invokeWithHistory(binding, options.input, threadId, runId);
             let approval;
-            if (actual.output) {
-                await this.persistence.appendThreadMessage(threadId, {
-                    role: "assistant",
-                    content: actual.output,
-                    runId,
-                    createdAt: new Date().toISOString(),
-                });
-            }
-            await this.persistence.setRunState(threadId, runId, actual.state, actual.state === "waiting_for_approval" ? `checkpoints/${threadId}/${runId}/cp-1` : null);
-            if (actual.state === "waiting_for_approval") {
-                const checkpointRef = `checkpoints/${threadId}/${runId}/cp-1`;
-                approval = await this.persistApproval(threadId, runId, checkpointRef, options.input, actual.interruptContent);
-                await this.emit(threadId, runId, 4, "approval.requested", {
-                    approvalId: approval.approvalId,
-                    pendingActionId: approval.pendingActionId,
-                    toolName: approval.toolName,
-                    toolCallId: approval.toolCallId,
-                    allowedDecisions: approval.allowedDecisions,
-                    checkpointRef,
-                });
-            }
-            await this.emit(threadId, runId, 3, "run.state.changed", {
+            await this.appendAssistantMessage(threadId, runId, actual.output);
+            const checkpointRef = actual.state === "waiting_for_approval" ? `checkpoints/${threadId}/${runId}/cp-1` : null;
+            await this.setRunStateAndEmit(threadId, runId, 3, actual.state, {
                 previousState: null,
-                state: actual.state,
-                checkpointRef: actual.state === "waiting_for_approval" ? `checkpoints/${threadId}/${runId}/cp-1` : null,
+                checkpointRef,
             });
+            if (actual.state === "waiting_for_approval") {
+                approval = (await this.requestApprovalAndEmit(threadId, runId, options.input, actual.interruptContent, checkpointRef, 4)).approval;
+            }
             return {
                 ...actual,
                 threadId,
@@ -453,15 +499,9 @@ export class AgentHarness {
             };
         }
         catch (error) {
-            await this.emit(threadId, runId, 3, "runtime.synthetic_fallback", {
-                reason: error instanceof Error ? error.message : String(error),
-                selectedAgentId,
-            });
-            await this.persistence.setRunState(threadId, runId, "failed");
-            await this.emit(threadId, runId, 4, "run.state.changed", {
+            await this.emitSyntheticFallback(threadId, runId, selectedAgentId, error);
+            await this.setRunStateAndEmit(threadId, runId, 4, "failed", {
                 previousState: null,
-                state: "failed",
-                checkpointRef: null,
                 error: error instanceof Error ? error.message : String(error),
             });
             return {
@@ -490,32 +530,8 @@ export class AgentHarness {
             return;
         }
         let emitted = false;
-        const threadId = options.threadId ?? createPersistentId();
-        const runId = createPersistentId();
-        const createdAt = new Date().toISOString();
-        if (!options.threadId) {
-            await this.persistence.createThread({
-                threadId,
-                agentId: selectedAgentId,
-                runId,
-                status: "running",
-                createdAt,
-            });
-        }
-        await this.persistence.appendThreadMessage(threadId, {
-            role: "user",
-            content: options.input,
-            runId,
-            createdAt,
-        });
-        await this.persistence.createRun({
-            threadId,
-            runId,
-            agentId: selectedAgentId,
-            executionMode: binding.agent.executionMode,
-            createdAt,
-        });
-        yield { type: "event", event: await this.emit(threadId, runId, 1, "run.created", {
+        const { threadId, runId } = await this.ensureThreadStarted(selectedAgentId, binding, options.input, options.threadId);
+        yield { type: "event", event: await this.emitRunCreated(threadId, runId, {
                 agentId: selectedAgentId,
                 requestedAgentId: options.agentId ?? AUTO_AGENT_ID,
                 selectedAgentId,
@@ -523,8 +539,7 @@ export class AgentHarness {
                 state: "running",
             }) };
         try {
-            const history = await this.persistence.listThreadMessages(threadId);
-            const priorHistory = history.filter((message) => message.runId !== runId);
+            const priorHistory = await this.loadPriorHistory(threadId, runId);
             let assistantOutput = "";
             for await (const chunk of this.runtimeAdapter.stream(binding, options.input, threadId, priorHistory)) {
                 if (chunk) {
@@ -535,26 +550,18 @@ export class AgentHarness {
                         : chunk;
                     if (normalizedChunk.kind === "interrupt") {
                         const checkpointRef = `checkpoints/${threadId}/${runId}/cp-1`;
-                        await this.persistence.setRunState(threadId, runId, "waiting_for_approval", checkpointRef);
-                        const approval = await this.persistApproval(threadId, runId, checkpointRef, options.input, normalizedChunk.content);
+                        const waitingEvent = await this.setRunStateAndEmit(threadId, runId, 4, "waiting_for_approval", {
+                            previousState: null,
+                            checkpointRef,
+                        });
+                        const approvalRequest = await this.requestApprovalAndEmit(threadId, runId, options.input, normalizedChunk.content, checkpointRef, 5);
                         yield {
                             type: "event",
-                            event: await this.emit(threadId, runId, 4, "run.state.changed", {
-                                previousState: null,
-                                state: "waiting_for_approval",
-                                checkpointRef,
-                            }),
+                            event: waitingEvent,
                         };
                         yield {
                             type: "event",
-                            event: await this.emit(threadId, runId, 5, "approval.requested", {
-                                approvalId: approval.approvalId,
-                                pendingActionId: approval.pendingActionId,
-                                toolName: approval.toolName,
-                                toolCallId: approval.toolCallId,
-                                allowedDecisions: approval.allowedDecisions,
-                                checkpointRef,
-                            }),
+                            event: approvalRequest.event,
                         };
                         return;
                     }
@@ -594,98 +601,46 @@ export class AgentHarness {
                     }
                     emitted = true;
                     assistantOutput += normalizedChunk.content;
-                    await this.emit(threadId, runId, 3, "output.delta", {
-                        content: normalizedChunk.content,
-                    });
-                    yield {
-                        type: "content",
-                        threadId,
-                        runId,
-                        agentId: selectedAgentId,
-                        content: normalizedChunk.content,
-                    };
+                    yield await this.emitOutputDeltaAndCreateItem(threadId, runId, selectedAgentId, normalizedChunk.content);
                 }
             }
             if (!assistantOutput) {
-                const actual = await this.runtimeAdapter.invoke(binding, options.input, threadId, runId, undefined, priorHistory);
+                const actual = await this.invokeWithHistory(binding, options.input, threadId, runId);
                 if (actual.output) {
                     assistantOutput = actual.output;
                     emitted = true;
-                    await this.emit(threadId, runId, 3, "output.delta", {
-                        content: actual.output,
-                    });
-                    yield {
-                        type: "content",
-                        threadId,
-                        runId,
-                        agentId: selectedAgentId,
-                        content: actual.output,
-                    };
+                    yield await this.emitOutputDeltaAndCreateItem(threadId, runId, selectedAgentId, actual.output);
                 }
             }
-            if (assistantOutput) {
-                await this.persistence.appendThreadMessage(threadId, {
-                    role: "assistant",
-                    content: assistantOutput,
-                    runId,
-                    createdAt: new Date().toISOString(),
-                });
-            }
-            await this.persistence.setRunState(threadId, runId, "completed");
-            yield { type: "event", event: await this.emit(threadId, runId, 4, "run.state.changed", {
+            await this.appendAssistantMessage(threadId, runId, assistantOutput);
+            yield { type: "event", event: await this.setRunStateAndEmit(threadId, runId, 4, "completed", {
                     previousState: null,
-                    state: "completed",
-                    checkpointRef: null,
                 }) };
             return;
         }
         catch (error) {
             if (emitted) {
-                await this.persistence.setRunState(threadId, runId, "failed");
-                yield { type: "event", event: await this.emit(threadId, runId, 4, "run.state.changed", {
+                yield { type: "event", event: await this.setRunStateAndEmit(threadId, runId, 4, "failed", {
                         previousState: null,
-                        state: "failed",
                         error: error instanceof Error ? error.message : String(error),
                     }) };
                 return;
             }
             try {
-                const history = await this.persistence.listThreadMessages(threadId);
-                const priorHistory = history.filter((message) => message.runId !== runId);
-                const actual = await this.runtimeAdapter.invoke(binding, options.input, threadId, runId, undefined, priorHistory);
+                const actual = await this.invokeWithHistory(binding, options.input, threadId, runId);
+                await this.appendAssistantMessage(threadId, runId, actual.output);
                 if (actual.output) {
-                    await this.persistence.appendThreadMessage(threadId, {
-                        role: "assistant",
-                        content: actual.output,
-                        runId,
-                        createdAt: new Date().toISOString(),
-                    });
-                    yield {
-                        type: "content",
-                        threadId,
-                        runId,
-                        agentId: selectedAgentId,
-                        content: actual.output,
-                    };
+                    yield await this.emitOutputDeltaAndCreateItem(threadId, runId, selectedAgentId, actual.output);
                 }
-                await this.persistence.setRunState(threadId, runId, actual.state);
-                yield { type: "event", event: await this.emit(threadId, runId, 4, "run.state.changed", {
+                yield { type: "event", event: await this.setRunStateAndEmit(threadId, runId, 4, actual.state, {
                         previousState: null,
-                        state: actual.state,
-                        checkpointRef: null,
                     }) };
                 return;
             }
             catch (invokeError) {
-                await this.emit(threadId, runId, 3, "runtime.synthetic_fallback", {
-                    reason: invokeError instanceof Error ? invokeError.message : String(invokeError),
-                    selectedAgentId,
-                });
-                await this.persistence.setRunState(threadId, runId, "failed");
-                yield { type: "event", event: await this.emit(threadId, runId, 4, "run.state.changed", {
+                await this.emitSyntheticFallback(threadId, runId, selectedAgentId, invokeError);
+                yield { type: "event", event: await this.setRunStateAndEmit(threadId, runId, 4, "failed", {
                         previousState: null,
-                        state: "failed",
-                        checkpointRef: null,
                         error: invokeError instanceof Error ? invokeError.message : String(invokeError),
                     }) };
                 yield {
@@ -737,14 +692,7 @@ export class AgentHarness {
             ? { decision: "edit", editedInput: options.editedInput }
             : (options.decision ?? "approve");
         const actual = await this.runtimeAdapter.invoke(binding, "", threadId, runId, resumeDecision, priorHistory);
-        if (actual.output) {
-            await this.persistence.appendThreadMessage(threadId, {
-                role: "assistant",
-                content: actual.output,
-                runId,
-                createdAt: new Date().toISOString(),
-            });
-        }
+        await this.appendAssistantMessage(threadId, runId, actual.output);
         await this.persistence.setRunState(threadId, runId, actual.state, actual.state === "waiting_for_approval" ? `checkpoints/${threadId}/${runId}/cp-1` : null);
         await this.emit(threadId, runId, 7, "run.state.changed", {
             previousState: "resuming",