@botbotgo/agent-harness 0.0.9 → 0.0.11

package/README.md

@@ -0,0 +1,512 @@
+# @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.
+
+It is designed for two common use cases:
+
+- 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
+
+The public API stays intentionally small:
+
+- `createAgentHarness(...)`
+- `run(...)`
+- `subscribe(...)`
+- `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:
+
+```bash
+npm install @botbotgo/agent-harness
+```
+
+Create a workspace with at least:
+
+```text
+your-workspace/
+  AGENTS.md
+  config/
+    model.yaml
+    runtime.yaml
+    direct.yaml
+    orchestra.yaml
+```
+
+Minimal usage:
+
+```ts
+import { createAgentHarness, run, stop } from "@botbotgo/agent-harness";
+
+const harness = await createAgentHarness("/absolute/path/to/your-workspace");
+
+try {
+  const result = await run(harness, {
+    agentId: "direct",
+    input: "Summarize what this workspace is for.",
+  });
+
+  console.log(result.output);
+} finally {
+  await stop(harness);
+}
+```
+
+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
+
+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
+
+#### Create A Harness From A Workspace Path
+
+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.
+
+```ts
+import { createAgentHarness } from "@botbotgo/agent-harness";
+
+const harness = await createAgentHarness("/absolute/path/to/workspace");
+```
+
+If you omit the path, the SDK uses `process.cwd()`:
+
+```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
+
+```ts
+import { createAgentHarness, run, stop } from "@botbotgo/agent-harness";
+
+const harness = await createAgentHarness("/absolute/path/to/workspace");
+
+try {
+  const result = await run(harness, {
+    agentId: "direct",
+    input: "Summarize what this workspace is for.",
+  });
+
+  console.log(result.threadId);
+  console.log(result.runId);
+  console.log(result.state);
+  console.log(result.output);
+} finally {
+  await stop(harness);
+}
+```
+
+#### 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`.
+
+```ts
+const result = await run(harness, {
+  agentId: "auto",
+  input: "Inspect this repository and explain how the release flow works.",
+});
+```
+
+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.
+
+```ts
+const result = await run(harness, {
+  agentId: "orchestra",
+  input: "Inspect the workspace and explain the available agents.",
+  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);
+    },
+  },
+});
+```
+
+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.
+
+```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.
+
+```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");
+
+const unsubscribe = subscribe(harness, (event) => {
+  console.log(event.eventType, event.payload);
+});
+
+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.
+
+Run the example:
+
+```bash
+cd examples/stock-research-app
+npm install
+npm run start -- "Investigate NVDA and produce a balanced stock research brief."
+```
+
+## 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:
+
+- `LangChainAgent`
+- `DeepAgent`
+
+Typical fields include:
+
+- `metadata.name`
+- `metadata.description`
+- `spec.modelRef`
+- `spec.systemPrompt`
+- `spec.checkpointer`
+- `spec.memory`
+- `spec.store`
+- `spec.backend`
+
+Use `LangChainAgent` for a fast direct path. Use `DeepAgent` when you need richer orchestration, tool-heavy execution, memory backends, and delegation.
+
+## 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
+
+Subagents can be discovered from configured roots. The discovery layer supports:
+
+- 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
+```
+
+### Add Tools
+
+Tools can come from:
+
+- resource packages
+- external sources
+- builtin resources
+- declarative tool objects that bundle or reference other tools
+
+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
+```
+
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "description": "Agent Harness framework package",
   "type": "module",
   "packageManager": "npm@10.9.2",
@@ -44,7 +44,7 @@
   "scripts": {
     "build": "rm -rf dist tsconfig.tsbuildinfo && tsc -p tsconfig.json && cp -R config dist/",
     "check": "tsc -p tsconfig.json --noEmit",
-    "test": "vitest run test/public-api.test.ts test/resource-optional-provider.test.ts test/stock-research-app-load-harness.test.ts test/release-workflow.test.ts test/release-version.test.ts test/gitignore.test.ts test/package-lock.test.ts",
+    "test": "vitest run test/public-api.test.ts test/resource-optional-provider.test.ts test/stock-research-app-load-harness.test.ts test/release-workflow.test.ts test/release-version.test.ts test/gitignore.test.ts test/package-lock.test.ts test/readme.test.ts",
     "release:pack": "npm pack --dry-run",
     "release:publish": "npm publish --access public --registry https://registry.npmjs.org/"
   },