@botbotgo/agent-harness 0.0.18 → 0.0.20

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 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,14 +31,14 @@ Install the package:
 npm install @botbotgo/agent-harness
 ```
 
-Create a workspace with at least:
+Create a workspace:
 
 ```text
 your-workspace/
-  AGENTS.md
   config/
+    agent-context.md
+    workspace.yaml
     models.yaml
-    runtime.yaml
     agents/
       direct.yaml
       orchestra.yaml
@@ -77,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.
-
-#### SDK Surface
+## Feature List
 
-The SDK is intentionally small:
+- 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`
 
-- `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";
@@ -107,519 +90,133 @@ 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 compiles a workspace in code, or you want tighter control in tests, you can pass a `WorkspaceBundle` directly.
-
-```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.
-
-```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.
+### Subscribe To Global Events
 
 ```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-harness/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 workspace files:
 
-### Core Files
-
-- `AGENTS.md`: durable instructions and operating rules loaded into agent memory where configured
-- `config/models.yaml`: declared models
-- `config/runtime.yaml`: workspace-wide runtime defaults such as `runRoot` and host routing
-- `config/agents/direct.yaml`: lightweight direct-response host agent
+- `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
-- `config/embedding-model.yaml`: embeddings preset for retrieval flows
-- `config/vector-store.yaml`: vector store preset for retrieval flows
-- `resources/package.json`: resource package boundary for local tools and skills
-- `resources/tools/`: local code-authored tools discovered automatically
-- `resources/skills/`: local skills and skill-local assets
-
-### Minimal Model Config
-
-```yaml
-apiVersion: agent-harness/v1alpha1
-kind: Models
-spec:
-  - name: default
-    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
+- `resources/package.json`: resource package boundary
+- `resources/tools/`: local tool modules
+- `resources/skills/`: local skills
 
-### Agent Config
+### `config/workspace.yaml`
 
-Agent objects are declarative YAML files. The package supports:
+Use this file for workspace-wide behavior such as:
 
-- `LangChainAgent`
-- `DeepAgent`
+- `runRoot`
+- routing via `routing.systemPrompt`
+- background checkpoint maintenance via `maintenance.checkpoints.*`
 
-Typical fields include:
+### `config/agent-context.md`
 
-- `metadata.name`
-- `metadata.description`
-- `spec.modelRef`
-- `spec.systemPrompt`
-- `spec.tools`
-- `spec.mcpServers`
-- `spec.checkpointer`
-- `spec.memory`
-- `spec.store`
-- `spec.backend`
+Use this file for shared bootstrap context that agents should read at construction time.
 
-Use `LangChainAgent` for a fast direct path. Use `DeepAgent` when you need richer orchestration, tool-heavy execution, memory backends, and delegation.
+Put stable project context here, not long-term mutable memory.
 
-### Local Tool Authoring
+If a runnable app workspace also includes `AGENTS.md`, treat that file as workspace-level operating guidance. It complements `config/agents/*.yaml` rather than replacing it: `AGENTS.md` carries durable behavioral rules, while `config/agents/` defines agent topology and runtime configuration.
 
-Local tools live under `resources/tools/` and are discovered automatically from `.js`, `.mjs`, and `.cjs` modules.
+### Agent YAML
 
-`resources/package.json` is not only metadata. It defines the dependency boundary for local tools and skill-local scripts. Tool modules are loaded with `resources/` as their package root, so dependencies should be declared under `resources/package.json` rather than relying on the app root package.
+Use `config/agents/*.yaml` to configure agents. Common fields include:
 
-Recommended authoring style:
-
-```js
-import { z } from "zod";
-import { tool } from "@botbotgo/agent-harness/tools";
-
-export const stock_lookup = tool({
-  description: "Lookup a ticker.",
-  schema: {
-    ticker: z.string().min(1),
-  },
-  async invoke(input) {
-    return input.ticker.toUpperCase();
-  },
-});
-```
-
-Then reference the tool from the agent:
-
-```yaml
-spec:
-  tools:
-    - tool/stock_lookup
-```
-
-### MCP Servers On Agents
-
-MCP servers are configured directly on the agent. The framework connects to each server, lists its remote tools, and automatically exposes the selected ones on that agent.
-
-```yaml
-spec:
-  modelRef: model/default
-  mcpServers:
-    - name: chrome-devtools
-      command: npx
-      args:
-        - chrome-devtools-mcp@latest
-      toolFilter:
-        - ^page_
-        - ^network_
-      excludeToolFilter:
-        - _deprecated$
-```
-
-Supported MCP fields:
-
-- `name`
-- `command`, `args`, `env`, `cwd`
-- `transport`, `url`, `token`, `headers`
+- `modelRef`
+- `systemPrompt`
 - `tools`
-- `excludeTools`
-- `toolFilter` or `toolFilters`
-- `excludeToolFilter` or `excludeToolFilters`
-
-## How To Extend
-
-The extension model is filesystem-based. You extend the harness by adding new config objects, new discovery roots, or new resource packages.
-
-### Add More Agents
-
-Agents live under config roots such as `config/agents/`. The discovery layer supports:
-
-- local filesystem paths
-- external resource sources
-- builtin discovery paths
+- `skills`
+- `memory`
+- `checkpointer`
+- `store`
+- `backend`
+- `subagents`
 
-The harness scans YAML files under the discovered agent roots and adds them to the workspace graph. `resources/` is for executable assets such as tools and skills, not agent YAML.
+### Resource Package
 
-### Add Skills
+Use `resources/` for executable extensions:
 
-Skills are discovered from roots that contain either:
-
-- a direct `SKILL.md`
-- child directories where each directory contains its own `SKILL.md`
-
-`SKILL.md` should use YAML frontmatter. The harness reads `name` and the standard `stack` field from frontmatter, then exposes that metadata through runtime inventory helpers such as `listAgentSkills(...)` and `builtin.list_available_skills`.
-
-Example:
-
-```md
----
-name: code-review
-description: Review code changes for correctness and regression risk.
-stack:
-  - typescript
-  - vitest
----
-
-# Code Review
-
-Use this skill when the user wants a correctness-focused review of a patch.
-```
-
-Notes:
-
-- `name` should be stable and unique within the discovered skill set
-- `stack` should be a list of technologies, frameworks, or platforms the skill is designed for
-- if `stack` is omitted, the runtime treats it as an empty list
-
-A practical layout looks like this:
-
-```text
-your-workspace/
-  resources/
-    skills/
-      code-review/
-        SKILL.md
-      release-check/
-        SKILL.md
-```
-
-### Add Tools
-
-Tools can come from:
-
-- local modules under `resources/tools/`
-- external sources
-- builtin resources
-- MCP servers declared on an agent under `spec.mcpServers`
-
-The example application demonstrates the local pattern: keep app-specific tools under `resources/tools/` and keep one tool per module.
-
-Dependency rule:
-
-- declare tool runtime dependencies in `resources/package.json`
-- do not rely on the app root `package.json` for modules imported by files under `resources/tools/`
-- keep reusable helper modules for tools under `resources/` so they stay inside the same package boundary
-
-### 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/
-    models.yaml
-    runtime.yaml
-    agents/
-      direct.yaml
-      orchestra.yaml
-    embedding-model.yaml
-    vector-store.yaml
-  resources/
-    package.json
-    skills/
-    tools/
-  .agent/
-```
-
-## Release Flow
-
-Publishing is automated from `master`.
-
-When a commit lands on `master`, the GitHub `Release` workflow:
-
-1. runs `npm ci`, `npm run build`, `npm run check`, and `npm test`
-2. bumps the package with `npm version patch --no-git-tag-version`
-3. syncs `examples/stock-research-app/package.json` to the new package version
-4. commits the version change back to `master` and creates a matching `v*` tag
-5. verifies the tarball and publishes to npm
-
-That means normal feature and fix commits should not manually edit the package version. Version bumps are owned by the release workflow.
-
-## 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-harness/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`.