@botbotgo/agent-harness 0.0.17 → 0.0.19

package/README.md

@@ -1,11 +1,19 @@
 # @botbotgo/agent-harness
 
-`@botbotgo/agent-harness` is a TypeScript framework for running local agent workspaces with declarative config, reusable tools, reusable skills, and configurable host-agent routing.
+## Slogan
 
-It is designed for two common use cases:
+Declarative agent workspaces for LangChain v1 and DeepAgents.
 
-- build a reusable agent runtime package and publish it to npm
-- build an application workspace that ships its own agents, tools, skills, and model config
+## Product Overview
+
+`@botbotgo/agent-harness` is a TypeScript framework for loading a local workspace from disk, compiling it into runnable agent bindings, and executing requests through either a LangChain v1 path or a DeepAgent path.
+
+The framework is workspace-first:
+
+- agents are declared in YAML
+- tools and skills are discovered from `resources/`
+- workspace-wide behavior is declared in `config/workspace.yaml`
+- agent bootstrap context is declared in `config/agent-context.md`
 
 The public API stays intentionally small:
 
@@ -15,25 +23,6 @@ The public API stays intentionally small:
 - `getThread(...)`
 - `stop(...)`
 
-## Product Overview
-
-Agent Harness loads a workspace from disk, compiles its config into runnable agent bindings, and executes requests through either a lightweight LangChain v1 path or a DeepAgent path.
-
-Out of the box, the framework supports:
-
-- workspace loading from a directory root
-- declarative `Model`, `EmbeddingModel`, `VectorStore`, `LangChainAgent`, `DeepAgent`, and `Runtime` objects
-- host-agent routing between a direct path and an orchestration path
-- tool loading from resource packages and external sources
-- skill discovery from filesystem roots
-- subagent discovery from filesystem roots
-- thread persistence, run history, and resumable state
-
-The default package config in this repo shows the intended model:
-
-- `direct`: low-latency host for simple one-step requests
-- `orchestra`: default host for multi-step work, tools, skills, and delegation
-
 ## Quick Start
 
 Install the package:
@@ -42,16 +31,20 @@ Install the package:
 npm install @botbotgo/agent-harness
 ```
 
-Create a workspace with at least:
+Create a workspace:
 
 ```text
 your-workspace/
-  AGENTS.md
   config/
-    model.yaml
-    runtime.yaml
-    direct.yaml
-    orchestra.yaml
+    agent-context.md
+    workspace.yaml
+    models.yaml
+    agents/
+      direct.yaml
+      orchestra.yaml
+  resources/
+    package.json
+    tools/
 ```
 
 Minimal usage:
@@ -73,29 +66,23 @@ try {
 }
 ```
 
-If you want the framework to choose the host agent automatically, pass `agentId: "auto"` when your workspace has runtime routing configured.
-
-## How To Use
-
-There are two common ways to use the framework.
-
-### 1. Use It As A Library
-
-Load a workspace from disk and run requests through the public API.
+## Feature List
 
-#### SDK Surface
+- Declarative `Model`, `EmbeddingModel`, `VectorStore`, `LangChainAgent`, `DeepAgent`, and `Runtime` objects
+- Workspace loading from disk with framework defaults and workspace overrides
+- LangChain v1 agents for lightweight tool-calling flows
+- DeepAgents for planning, filesystem-backed execution, subagents, skills, and long-term memory
+- Resource package loading from `resources/tools/` and `resources/skills/`
+- Host-agent routing between a direct lane and an orchestration lane
+- Persistent thread state, approvals, run history, and resumable execution
+- Store-backed `/memories/*` long-term memory
+- Background checkpoint maintenance for `SqliteSaver`
 
-The SDK is intentionally small:
-
-- `createAgentHarness(...)`: load a workspace and initialize the runtime
-- `run(...)`: start a new run or answer an approval request
-- `subscribe(...)`: observe runtime events for logging or UI updates
-- `getThread(...)`: fetch persisted thread state and messages
-- `stop(...)`: release runtime resources when your process is done
+## How To Use
 
-#### Create A Harness From A Workspace Path
+### Create A Harness
 
-This is the standard entry point. Pass the workspace root and let the harness load `AGENTS.md`, `config/`, resource sources, skills, tools, and agent bindings from disk.
+Pass a workspace root:
 
 ```ts
 import { createAgentHarness } from "@botbotgo/agent-harness";
@@ -103,410 +90,131 @@ import { createAgentHarness } from "@botbotgo/agent-harness";
 const harness = await createAgentHarness("/absolute/path/to/workspace");
 ```
 
-If you omit the path, the SDK uses `process.cwd()`:
+Or pass a prebuilt `WorkspaceBundle`:
 
 ```ts
-const harness = await createAgentHarness();
-```
-
-#### Create A Harness From A Prebuilt WorkspaceBundle
-
-If your application already compiled a workspace, or you want tighter control in tests, you can pass a `WorkspaceBundle` directly instead of a filesystem path.
-
-```ts
-import { createAgentHarness } from "@botbotgo/agent-harness";
-
 const harness = await createAgentHarness(workspaceBundle);
 ```
 
-#### Run A Simple Request
-
-Use `run(...)` with an `agentId` and plain-text `input`. The return value includes:
-
-- `threadId`: stable conversation id
-- `runId`: the current execution id
-- `state`: final state such as `completed` or `waiting_for_approval`
-- `output`: final visible model output
+### Run A Request
 
 ```ts
-import { createAgentHarness, run, stop } from "@botbotgo/agent-harness";
+import { run } from "@botbotgo/agent-harness";
 
-const harness = await createAgentHarness("/absolute/path/to/workspace");
+const result = await run(harness, {
+  agentId: "direct",
+  input: "Explain the available agents in this workspace.",
+});
+```
 
-try {
-  const result = await run(harness, {
-    agentId: "direct",
-    input: "Summarize what this workspace is for.",
-  });
+The result includes:
 
-  console.log(result.threadId);
-  console.log(result.runId);
-  console.log(result.state);
-  console.log(result.output);
-} finally {
-  await stop(harness);
-}
-```
+- `threadId`
+- `runId`
+- `state`
+- `output`
 
-#### Let The Harness Choose The Host Agent
+### Let The Harness Choose The Host Agent
 
-If your workspace defines runtime routing, use `agentId: "auto"` to let the harness choose between host agents such as `direct` and `orchestra`.
+Use `agentId: "auto"` when your workspace defines routing:
 
 ```ts
 const result = await run(harness, {
   agentId: "auto",
-  input: "Inspect this repository and explain how the release flow works.",
+  input: "Inspect this repository and explain the release flow.",
 });
 ```
 
-Use this mode when your application should not hardcode the host agent choice.
-
-#### Stream Chunks And Runtime Events
-
-`run(...)` accepts listeners for streamed output and runtime activity. This is the main SDK path for CLIs, chat UIs, and debug logging.
+### Stream Output And Events
 
 ```ts
 const result = await run(harness, {
   agentId: "orchestra",
-  input: "Inspect the workspace and explain the available agents.",
+  input: "Inspect the workspace and explain the available tools.",
   listeners: {
     onChunk(chunk) {
       process.stdout.write(chunk);
     },
     onEvent(event) {
-      console.log("event:", event.eventType, event.payload);
-    },
-    onStep(step) {
-      console.log("step:", step);
-    },
-    onToolResult(item) {
-      console.log("tool:", item.toolName, item.output);
+      console.log(event.eventType, event.payload);
     },
   },
 });
 ```
 
-Listener usage by type:
-
-- `onChunk`: streamed user-visible response text
-- `onEvent`: raw runtime events
-- `onStep`: higher-level execution step messages
-- `onToolResult`: completed tool outputs
-- `onReasoning`: reasoning-channel text when available from the runtime
-
-#### Subscribe To Global Harness Events
-
-Use `subscribe(...)` when you want a process-wide event feed rather than per-run listeners.
-
-```ts
-import { subscribe } from "@botbotgo/agent-harness";
-
-const unsubscribe = subscribe(harness, (event) => {
-  console.log(event.threadId, event.runId, event.eventType);
-});
-
-// later
-unsubscribe();
-```
-
-This is useful when one process is handling multiple runs or updating a central UI.
-
-#### Continue An Existing Thread
-
-Pass an existing `threadId` to keep the conversation on the same persisted thread.
-
-```ts
-const first = await run(harness, {
-  agentId: "direct",
-  input: "Remember that the release branch is master.",
-});
-
-const second = await run(harness, {
-  agentId: "direct",
-  threadId: first.threadId,
-  input: "What did I just tell you about the release branch?",
-});
-```
-
-#### Read Back Thread State
-
-Use `getThread(...)` to fetch persisted thread data after a run completes.
+### Read Back Thread State
 
 ```ts
 import { getThread } from "@botbotgo/agent-harness";
 
 const thread = await getThread(harness, result.threadId);
-
-console.log(thread?.threadId);
 console.log(thread?.messages.at(-1)?.content);
 ```
 
-Use this when your app needs to reopen a conversation, render history, or inspect the latest assistant message.
-
-#### Handle Approval Or Interrupt Flows
-
-Some runs can pause with `state: "waiting_for_approval"`. In that case, call `run(...)` again with the thread or approval decision payload instead of starting a new request.
+### Subscribe To Global Events
 
 ```ts
-const pending = await run(harness, {
-  agentId: "orchestra",
-  input: "Run the protected action if approval is required.",
-});
-
-if (pending.state === "waiting_for_approval" && pending.approvalId) {
-  const resumed = await run(harness, {
-    threadId: pending.threadId,
-    runId: pending.runId,
-    approvalId: pending.approvalId,
-    decision: "approve",
-  });
-
-  console.log(resumed.output);
-}
-```
-
-Use `decision: "edit"` plus `editedInput` when your application exposes approval-time parameter editing.
-
-#### Always Stop The Harness
-
-Call `stop(...)` before process exit so the runtime can close adapters and flush state cleanly.
-
-```ts
-await stop(harness);
-```
-
-For most applications, the safe pattern is `try/finally`.
-
-#### Complete SDK CLI Example
-
-The following example shows a small CLI-style integration that:
-
-- loads a workspace from disk
-- starts a first run with streaming output
-- continues the same thread
-- reads the saved thread state back
-- shuts the harness down cleanly
-
-```ts
-import { createAgentHarness, getThread, run, stop } from "@botbotgo/agent-harness";
-
-const workspaceRoot = "/absolute/path/to/workspace";
-const harness = await createAgentHarness(workspaceRoot);
-
-try {
-  const first = await run(harness, {
-    agentId: "auto",
-    input: "Explain what agents and tools are available in this workspace.",
-    listeners: {
-      onChunk(chunk) {
-        process.stdout.write(chunk);
-      },
-      onStep(step) {
-        console.log("\n[step]", step);
-      },
-    },
-  });
-
-  console.log("\nfirst run:", first.runId, first.state);
-
-  const second = await run(harness, {
-    agentId: "auto",
-    threadId: first.threadId,
-    input: "Now give me the shortest possible summary in 3 bullets.",
-  });
-
-  console.log("\nsecond run output:\n", second.output);
-
-  const thread = await getThread(harness, first.threadId);
-  console.log("\nthread message count:", thread?.messages.length ?? 0);
-} finally {
-  await stop(harness);
-}
-```
-
-For a real CLI entrypoint, wrap this in an async `main()` and feed the prompt from `process.argv`.
-
-```ts
-import { createAgentHarness, getThread, run, subscribe, stop } from "@botbotgo/agent-harness";
-
-const harness = await createAgentHarness("/absolute/path/to/workspace");
+import { subscribe } from "@botbotgo/agent-harness";
 
 const unsubscribe = subscribe(harness, (event) => {
-  console.log(event.eventType, event.payload);
+  console.log(event.threadId, event.runId, event.eventType);
 });
-
-try {
-  const firstRun = await run(harness, {
-    agentId: "orchestra",
-    input: "Inspect the workspace and explain the available agents.",
-    listeners: {
-      onChunk(chunk) {
-        process.stdout.write(chunk);
-      },
-    },
-  });
-
-  const thread = await getThread(harness, firstRun.threadId);
-  console.log(thread?.messages.at(-1)?.content);
-} finally {
-  unsubscribe();
-  await stop(harness);
-}
 ```
 
-### 2. Use It Inside An App Workspace
-
-The example app in [`examples/stock-research-app`](/Users/boqiang.liang/900-project/agent-harness3/examples/stock-research-app/README.md) is the reference shape for an application workspace. It keeps the framework package separate from app-specific agents, tools, and skills.
+### Stop The Harness
 
-Run the example:
+```ts
+import { stop } from "@botbotgo/agent-harness";
 
-```bash
-cd examples/stock-research-app
-npm install
-npm run start -- "Investigate NVDA and produce a balanced stock research brief."
+await stop(harness);
 ```
 
 ## How To Configure
 
-Agent Harness is workspace-first. The runtime is assembled from files on disk rather than from a large constructor API.
-
-### Core Files
-
-- `AGENTS.md`: durable instructions and operating rules loaded into agent memory where configured
-- `config/model.yaml`: default chat model
-- `config/runtime.yaml`: workspace-wide runtime defaults such as `runRoot` and host routing
-- `config/direct.yaml`: lightweight direct-response host agent
-- `config/orchestra.yaml`: default orchestration host agent
-- `config/embedding-model.yaml`: embeddings preset for retrieval flows
-- `config/vector-store.yaml`: vector store preset for retrieval flows
-
-### Minimal Model Config
-
-```yaml
-apiVersion: agent-harness/v1alpha1
-kind: Model
-metadata:
-  name: default
-spec:
-  provider: ollama
-  model: gpt-oss:latest
-  init:
-    baseUrl: http://localhost:11434
-    temperature: 0.2
-```
-
-### Runtime Routing
-
-`config/runtime.yaml` controls shared runtime behavior. In this repo it defines:
-
-- `runRoot`: where thread state, run artifacts, approvals, and indexes are stored
-- `routing.systemPrompt`: how the harness chooses between the primary and secondary host agents when `agentId: "auto"` is used
-
-### Agent Config
-
-Agent objects are declarative YAML files. The package currently supports:
+Core workspace files:
 
-- `LangChainAgent`
-- `DeepAgent`
+- `config/workspace.yaml`: workspace-wide defaults such as `runRoot`, routing, and maintenance
+- `config/agent-context.md`: shared bootstrap context for agents
+- `config/models.yaml`: named model presets
+- `config/agents/direct.yaml`: lightweight host agent
+- `config/agents/orchestra.yaml`: default orchestration host agent
+- `resources/package.json`: resource package boundary
+- `resources/tools/`: local tool modules
+- `resources/skills/`: local skills
 
-Typical fields include:
+### `config/workspace.yaml`
 
-- `metadata.name`
-- `metadata.description`
-- `spec.modelRef`
-- `spec.systemPrompt`
-- `spec.checkpointer`
-- `spec.memory`
-- `spec.store`
-- `spec.backend`
+Use this file for workspace-wide behavior such as:
 
-Use `LangChainAgent` for a fast direct path. Use `DeepAgent` when you need richer orchestration, tool-heavy execution, memory backends, and delegation.
+- `runRoot`
+- routing via `routing.systemPrompt`
+- background checkpoint maintenance via `maintenance.checkpoints.*`
 
-## How To Extend
+### `config/agent-context.md`
 
-The extension model is filesystem-based. You extend the harness by adding new config objects, new discovery roots, or new resource packages.
+Use this file for shared bootstrap context that agents should read at construction time.
 
-### Add More Agents
+Put stable project context here, not long-term mutable memory.
 
-Subagents can be discovered from configured roots. The discovery layer supports:
+### Agent YAML
 
-- local filesystem paths
-- external resource sources
-- builtin discovery paths
-
-The harness scans YAML files under the discovered agent roots and adds them to the workspace graph.
-
-### Add Skills
-
-Skills are discovered from roots that contain either:
-
-- a direct `SKILL.md`
-- child directories where each directory contains its own `SKILL.md`
-
-A practical layout looks like this:
-
-```text
-your-workspace/
-  resources/
-    skills/
-      code-review/
-        SKILL.md
-      release-check/
-        SKILL.md
-```
+Use `config/agents/*.yaml` to configure agents. Common fields include:
 
-### Add Tools
+- `modelRef`
+- `systemPrompt`
+- `tools`
+- `skills`
+- `memory`
+- `checkpointer`
+- `store`
+- `backend`
+- `subagents`
 
-Tools can come from:
+### Resource Package
 
-- resource packages
-- external sources
-- builtin resources
-- declarative tool objects that bundle or reference other tools
+Use `resources/` for executable extensions:
 
-The example application demonstrates a clean pattern: keep app-specific tools under `resources/tools/` and keep one tool per module.
-
-### Add Retrieval
-
-If your workspace needs RAG-style behavior:
-
-1. add an `EmbeddingModel`
-2. add a `VectorStore`
-3. point retrieval-oriented tools at those refs
-
-This repo already includes `config/embedding-model.yaml` and `config/vector-store.yaml` as the default pattern.
-
-### Extend The Runtime In Code
-
-The public API also accepts a prebuilt `WorkspaceBundle`, which lets you compile or inject workspace data yourself before creating the harness. That path is useful when you need tighter control in tests or in a higher-level product.
-
-## Suggested Workspace Layout
-
-```text
-your-workspace/
-  AGENTS.md
-  config/
-    model.yaml
-    runtime.yaml
-    direct.yaml
-    orchestra.yaml
-    embedding-model.yaml
-    vector-store.yaml
-  resources/
-    agents/
-    skills/
-    tools/
-  .agent/
-```
-
-## Development
-
-Build and test this package locally:
-
-```bash
-npm run build
-npm run check
-npm test
-```
+- `resources/tools/` for local tool modules
+- `resources/skills/` for skill packages
 
-The example workspace under [`examples/stock-research-app`](/Users/boqiang.liang/900-project/agent-harness3/examples/stock-research-app/README.md) is the fastest way to understand how an app should package its own agents, tools, and skills around this framework.
+Each resource package should include its own `package.json`.

package/dist/api.d.ts

@@ -1,5 +1,6 @@
 import type { AgentHarnessHandle, RunOptions, RuntimeAdapterOptions, ThreadRecord, WorkspaceLoadOptions, WorkspaceBundle } from "./contracts/types.js";
 import { AgentHarness } from "./runtime/harness.js";
+import type { ToolMcpServerOptions } from "./mcp.js";
 type CreateAgentHarnessOptions = {
     load?: WorkspaceLoadOptions;
     adapter?: RuntimeAdapterOptions;
@@ -11,4 +12,6 @@ export declare function run(harness: AgentHarnessHandle, options: RunOptions): P
 export declare function subscribe(harness: AgentHarnessHandle, listener: Parameters<AgentHarness["subscribe"]>[0]): () => void;
 export declare function getThread(harness: AgentHarnessHandle, threadId: string): Promise<ThreadRecord | null>;
 export declare function stop(harness: AgentHarnessHandle): Promise<void>;
+export declare function createToolMcpServer(harness: AgentHarnessHandle, options: ToolMcpServerOptions): Promise<import("@modelcontextprotocol/sdk/server/mcp.js").McpServer>;
+export declare function serveToolsOverStdio(harness: AgentHarnessHandle, options: ToolMcpServerOptions): Promise<import("@modelcontextprotocol/sdk/server/mcp.js").McpServer>;
 export {};

package/dist/api.js

@@ -1,4 +1,5 @@
 import { AgentHarness } from "./runtime/harness.js";
+import { createToolMcpServerFromHarness, serveToolsOverStdioFromHarness } from "./mcp.js";
 import { loadWorkspace } from "./workspace/compile.js";
 const HARNESS_INSTANCE = Symbol.for("@botbotgo/agent-harness/instance");
 function registerHarness(harness) {
@@ -45,3 +46,9 @@ export async function stop(harness) {
     const instance = requireHarness(harness);
     return instance.close();
 }
+export async function createToolMcpServer(harness, options) {
+    return createToolMcpServerFromHarness(requireHarness(harness), options);
+}
+export async function serveToolsOverStdio(harness, options) {
+    return serveToolsOverStdioFromHarness(requireHarness(harness), options);
+}

package/dist/config/agent-context.md

@@ -0,0 +1,8 @@
+# Agent Context
+
+This file is the default shared bootstrap context for agents in this workspace.
+
+- Put stable workspace conventions here.
+- Put durable project background here.
+- Keep role and hard behavioral rules in `systemPrompt`.
+- Put long-term, runtime-learned knowledge in `/memories/*`, not here.

package/dist/config/orchestra.yaml

@@ -24,13 +24,15 @@ spec:
     kind: MemorySaver
   memory:
     # DeepAgents aligned feature: bootstrap memory sources supplied to the deep agent at construction time.
-    # These source paths resolve to static files that prime the agent before tool execution begins.
-    # This is distinct from long-term memory:
-    # - `memory:` here provides startup context files to `createDeepAgent(...)`
-    # - `store` below provides the LangGraph store consumed by `StoreBackend`
-    # - `backend` below controls `/memories/*` routing and other filesystem backend behavior
-    # - the harness checkpointer persists resumable graph state separately under the run root
-    - path: AGENTS.md
+    # These paths resolve relative to the workspace root unless they are already absolute.
+    # Treat this as agent-owned startup context, not as a dynamic long-term memory sink:
+    # - keep `systemPrompt` for stable role, boundaries, and hard behavioral rules
+    # - use `memory:` for stable project knowledge, operating conventions, and shared or agent-specific context files
+    # - use `/memories/*` via the backend/store below for durable knowledge learned from prior runs
+    # - use the harness checkpointer for resumable graph state for an in-flight run
+    # Updating these files changes future agent constructions, but they are still bootstrap inputs rather than
+    # self-updating runtime memory.
+    - path: config/agent-context.md
   # DeepAgents aligned feature: store config passed into `createDeepAgent({ store })`.
   # This is the LangGraph store used by `StoreBackend` routes inside the DeepAgents backend.
   # Available `kind` options in this harness: `FileStore`, `InMemoryStore`, `RedisStore`, `PostgresStore`.
@@ -56,7 +58,8 @@ spec:
         # Available route backend `kind` options today: `StoreBackend`.
         kind: StoreBackend
   # DeepAgents aligned feature: system prompt for the orchestration deep agent.
-  # This becomes the top-level instruction block for the upstream DeepAgents runtime.
+  # This becomes the top-level instruction block for the upstream DeepAgents runtime and should hold the
+  # agent's durable role, priorities, and behavioral guardrails rather than bulky project facts.
   systemPrompt: |-
     You are the orchestra agent.