@botbotgo/agent-harness 0.0.17 → 0.0.18

package/README.md

@@ -17,7 +17,7 @@ The public API stays intentionally small:
 
 ## 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.
+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:
 
@@ -48,10 +48,14 @@ Create a workspace with at least:
 your-workspace/
   AGENTS.md
   config/
-    model.yaml
+    models.yaml
     runtime.yaml
-    direct.yaml
-    orchestra.yaml
+    agents/
+      direct.yaml
+      orchestra.yaml
+  resources/
+    package.json
+    tools/
 ```
 
 Minimal usage:
@@ -111,7 +115,7 @@ 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.
+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";
@@ -356,7 +360,7 @@ try {
 
 ### 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.
+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.
 
 Run the example:
 
@@ -373,26 +377,28 @@ Agent Harness is workspace-first. The runtime is assembled from files on disk ra
 ### Core Files
 
 - `AGENTS.md`: durable instructions and operating rules loaded into agent memory where configured
-- `config/model.yaml`: default chat model
+- `config/models.yaml`: declared models
 - `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/agents/direct.yaml`: lightweight direct-response 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: Model
-metadata:
-  name: default
+kind: Models
 spec:
-  provider: ollama
-  model: gpt-oss:latest
-  init:
-    baseUrl: http://localhost:11434
-    temperature: 0.2
+  - name: default
+    provider: ollama
+    model: gpt-oss:latest
+    init:
+      baseUrl: http://localhost:11434
+      temperature: 0.2
 ```
 
 ### Runtime Routing
@@ -404,7 +410,7 @@ spec:
 
 ### Agent Config
 
-Agent objects are declarative YAML files. The package currently supports:
+Agent objects are declarative YAML files. The package supports:
 
 - `LangChainAgent`
 - `DeepAgent`
@@ -415,6 +421,8 @@ Typical fields include:
 - `metadata.description`
 - `spec.modelRef`
 - `spec.systemPrompt`
+- `spec.tools`
+- `spec.mcpServers`
 - `spec.checkpointer`
 - `spec.memory`
 - `spec.store`
@@ -422,19 +430,79 @@ Typical fields include:
 
 Use `LangChainAgent` for a fast direct path. Use `DeepAgent` when you need richer orchestration, tool-heavy execution, memory backends, and delegation.
 
+### Local Tool Authoring
+
+Local tools live under `resources/tools/` and are discovered automatically from `.js`, `.mjs`, and `.cjs` modules.
+
+`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.
+
+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`
+- `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
 
-Subagents can be discovered from configured roots. The discovery layer supports:
+Agents live under config roots such as `config/agents/`. 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.
+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.
 
 ### Add Skills
 
@@ -443,6 +511,30 @@ 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
@@ -459,12 +551,18 @@ your-workspace/
 
 Tools can come from:
 
-- resource packages
+- local modules under `resources/tools/`
 - external sources
 - builtin resources
-- declarative tool objects that bundle or reference other tools
+- 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:
 
-The example application demonstrates a clean pattern: keep app-specific tools under `resources/tools/` and keep one tool per module.
+- 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
 
@@ -486,19 +584,34 @@ The public API also accepts a prebuilt `WorkspaceBundle`, which lets you compile
 your-workspace/
   AGENTS.md
   config/
-    model.yaml
+    models.yaml
     runtime.yaml
-    direct.yaml
-    orchestra.yaml
+    agents/
+      direct.yaml
+      orchestra.yaml
     embedding-model.yaml
     vector-store.yaml
   resources/
-    agents/
+    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:
@@ -509,4 +622,4 @@ 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.
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.17",
+  "version": "0.0.18",
   "description": "Agent Harness framework package",
   "type": "module",
   "packageManager": "npm@10.9.2",