@botbotgo/agent-harness 0.0.9 → 0.0.10

package/README.md

@@ -0,0 +1,269 @@
+# @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.
+
+```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.10",
   "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/"
   },