@botbotgo/agent-harness 0.0.25 → 0.0.27

package/README.md

@@ -106,6 +106,13 @@ Or pass a prebuilt `WorkspaceBundle`:
 const harness = await createAgentHarness(workspaceBundle);
 ```
 
+Implementation details:
+
+- `createAgentHarness(workspaceRoot)` loads and compiles one `WorkspaceBundle` before the runtime starts
+- the loader reads `config/workspace.yaml`, `config/models.yaml`, `config/agent-context.md`, and every `config/agents/*.yaml` entry file, then validates the final topology
+- local resource refs are hydrated after config load, so `resources/tools/`, `resources/skills/`, and agent-declared MCP servers are resolved before the harness accepts runs
+- after compilation, the harness initializes persistence under the resolved `runRoot`, wires the runtime adapter, starts thread-memory syncing, and starts checkpoint maintenance when configured
+
 ### Run A Request
 
 ```ts
@@ -124,6 +131,13 @@ The result includes:
 - `state`
 - `output`
 
+Runtime behavior:
+
+- every `run(...)` call creates or continues a persisted thread under `runRoot`
+- the harness stores thread metadata, run lifecycle, streamed events, approvals, delegations, and artifacts on disk so `getThread(...)` can reconstruct the session later
+- when a store is configured, the harness also mirrors thread status and open approvals into `/memories/threads/<threadId>/`
+- `stop(...)` should always be called so background persistence and maintenance loops shut down cleanly
+
 ### Let The Harness Choose The Host Agent
 
 Use `agentId: "auto"` when your workspace defines routing:
@@ -135,6 +149,12 @@ const result = await run(harness, {
 });
 ```
 
+Implementation details:
+
+- `agentId: "auto"` asks the runtime adapter to classify between the primary and secondary host bindings discovered from the workspace
+- when the run belongs to an existing thread, the router includes recent conversation turns so follow-up requests can stay on the correct lane
+- if no model-driven routing prompt is configured, the harness falls back to heuristic routing for obvious research or implementation-style requests
+
 ### Stream Output And Events
 
 ```ts
@@ -166,6 +186,13 @@ spec:
     - ref: tool/local-toolset
 ```
 
+Tool implementation details:
+
+- tool modules are discovered from `resources/tools/*.js`, `resources/tools/*.mjs`, and `resources/tools/*.cjs`
+- the preferred format is exporting `tool({...})`; the harness also accepts exported functions plus `nameSchema`, `nameSchemaShape`, or generic `schema` metadata
+- when a module exports exactly one tool function, generic `schema` or `schemaShape` metadata can describe that function
+- keep runtime dependencies for local tools in `resources/package.json`, because the resource package is the execution boundary for those modules
+
 ### Bridge MCP Servers Into Agents
 
 Use `mcpServers:` inside agent YAML to bridge MCP servers into the agent's tool list:
@@ -245,6 +272,12 @@ Use this file for workspace-wide behavior such as:
 - routing via `routing.systemPrompt`
 - background checkpoint maintenance via `maintenance.checkpoints.*`
 
+Implementation details:
+
+- if `runRoot` is omitted, the harness defaults to `<workspace-root>/run-data`
+- the resolved `runRoot` stores thread indexes, per-thread transcripts, per-run events, approvals, delegations, artifacts, and checkpoint references
+- checkpoint maintenance only starts when `maintenance.checkpoints.enabled: true`; for SQLite checkpoints, cleanup policies can sweep old rows and optionally `VACUUM` the database
+
 ### `config/agent-context.md`
 
 Use this file for shared bootstrap context that agents read at construction time.
@@ -276,8 +309,19 @@ Use `resources/` for executable extensions:
 
 Each resource package should include its own `package.json`.
 
+Implementation details:
+
+- keep runtime extension source under `resources/`; keep tests outside the published source tree, for example under the repository `test/` folder
+- `resources/package.json` is the module resolution boundary used when local tools import third-party packages or skill-local scripts
+- SKILL packages stay file-based, so prompts, templates, helper scripts, and metadata can ship together without extra registration steps
+
 ### Skills And MCP
 
 - Use `resources/skills/` for SKILL packages that carry reusable instructions, templates, scripts, and metadata
 - Use `mcpServers:` in `config/agents/*.yaml` when you want the harness to bridge external MCP tools into an agent
 - Use `createToolMcpServer(...)` or `serveToolsOverStdio(...)` when you want the harness itself to act as an MCP server for another client
+
+Implementation details:
+
+- agent-declared `mcpServers:` entries are hydrated into concrete MCP tool refs during workspace compilation, then validated against the collected MCP server definitions
+- `createToolMcpServer(...)` exposes the selected agent toolset through one MCP server surface; `serveToolsOverStdio(...)` is the stdio transport wrapper around that same server construction

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.24";
+export declare const AGENT_HARNESS_VERSION = "0.0.26";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.24";
+export const AGENT_HARNESS_VERSION = "0.0.26";

package/dist/resource/resource-impl.js

@@ -133,12 +133,26 @@ function createInlineBackendResolver(workspace) {
                         inheritEnv: config?.inheritEnv !== false,
                     });
                 }
+                case "VfsSandbox": {
+                    const rootDir = resolveBackendRootDir(config?.rootDir);
+                    mkdirSync(rootDir, { recursive: true });
+                    return new LocalShellBackend({
+                        rootDir,
+                        virtualMode: config?.virtualMode === false ? false : true,
+                        timeout: typeof config?.timeout === "number" ? config.timeout : undefined,
+                        maxOutputBytes: typeof config?.maxOutputBytes === "number" ? config.maxOutputBytes : undefined,
+                        env: typeof config?.env === "object" && config.env
+                            ? Object.fromEntries(Object.entries(config.env).filter((entry) => typeof entry[1] === "string"))
+                            : undefined,
+                        inheritEnv: config?.inheritEnv !== false,
+                    });
+                }
                 case "StateBackend":
                     return new StateBackend(runtimeLike);
                 case "StoreBackend":
                     return new StoreBackend(runtimeLike);
                 default:
-                    throw new Error(`Unsupported DeepAgent backend kind "${kind}". Supported inline kinds: LocalShellBackend, StateBackend, StoreBackend, CompositeBackend.`);
+                    throw new Error(`Unsupported DeepAgent backend kind "${kind}". Supported inline kinds: LocalShellBackend, VfsSandbox, StateBackend, StoreBackend, CompositeBackend.`);
             }
         };
         return (runtimeLike) => {
@@ -146,6 +160,8 @@ function createInlineBackendResolver(workspace) {
             switch (kind) {
                 case "LocalShellBackend":
                     return createBackend("LocalShellBackend", backendConfig, runtimeLike);
+                case "VfsSandbox":
+                    return createBackend("VfsSandbox", backendConfig, runtimeLike);
                 case "StateBackend":
                     return new StateBackend(runtimeLike);
                 case "StoreBackend":
@@ -165,7 +181,7 @@ function createInlineBackendResolver(workspace) {
                     return new CompatibleCompositeBackend(createBackend(defaultBackendKind, stateConfig, runtimeLike), mappedRoutes);
                 }
                 default:
-                    throw new Error(`Unsupported DeepAgent backend kind "${kind}". Supported inline kinds: LocalShellBackend, StateBackend, StoreBackend, CompositeBackend.`);
+                    throw new Error(`Unsupported DeepAgent backend kind "${kind}". Supported inline kinds: LocalShellBackend, VfsSandbox, StateBackend, StoreBackend, CompositeBackend.`);
             }
         };
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.25",
+  "version": "0.0.27",
   "description": "Agent Harness framework package",
   "type": "module",
   "packageManager": "npm@10.9.2",
@@ -29,7 +29,6 @@
     }
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.0",
     "@langchain/anthropic": "^1.1.0",
     "@langchain/community": "^1.1.24",
     "@langchain/core": "^1.1.33",
@@ -39,7 +38,8 @@
     "@langchain/ollama": "^1.2.6",
     "@langchain/openai": "^1.1.0",
     "@libsql/client": "^0.17.0",
-    "@llamaindex/ollama": "^0.1.24",
+    "@llamaindex/ollama": "^0.1.23",
+    "@modelcontextprotocol/sdk": "^1.12.0",
     "deepagents": "1.8.4",
     "langchain": "1.2.34",
     "llamaindex": "^0.12.1",
@@ -50,7 +50,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/resource-isolation.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 test/runtime-adapter-regressions.test.ts test/tool-extension-gaps.test.ts test/checkpoint-maintenance.test.ts",
+    "test": "vitest run test/public-api.test.ts test/resource-optional-provider.test.ts test/resource-isolation.test.ts test/stock-research-app-load-harness.test.ts test/stock-research-app-run.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 test/runtime-adapter-regressions.test.ts test/tool-extension-gaps.test.ts test/checkpoint-maintenance.test.ts test/llamaindex-dependency-compat.test.ts",
     "release:prepare": "npm version patch --no-git-tag-version && node ./scripts/sync-example-version.mjs",
     "release:pack": "npm pack --dry-run",
     "release:publish": "npm publish --access public --registry https://registry.npmjs.org/"