@botbotgo/agent-harness 0.0.24 → 0.0.26

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.23";
+export declare const AGENT_HARNESS_VERSION = "0.0.25";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.23";
+export const AGENT_HARNESS_VERSION = "0.0.25";

package/dist/resource/resource-impl.js

@@ -1,9 +1,10 @@
-import { existsSync } from "node:fs";
+import { existsSync, mkdirSync } from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
 import { stat } from "node:fs/promises";
 import { readFile } from "node:fs/promises";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { CompositeBackend, LocalShellBackend, StateBackend, StoreBackend } from "deepagents";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
@@ -62,6 +63,113 @@ function createProviderBackendResolver(provider, workspace) {
     return (provider?.createResourceBackendResolver?.(workspace) ??
         provider?.createBuiltinBackendResolver?.(workspace));
 }
+class CompatibleCompositeBackend {
+    id;
+    execute;
+    composite;
+    constructor(defaultBackend, routes) {
+        this.composite = new CompositeBackend(defaultBackend, routes);
+        const sandboxLike = defaultBackend;
+        if (typeof sandboxLike.id === "string" && typeof sandboxLike.execute === "function") {
+            this.id = sandboxLike.id;
+            this.execute = (command) => this.composite.execute(command);
+        }
+    }
+    lsInfo(filePath) {
+        return this.composite.lsInfo(filePath);
+    }
+    read(filePath, offset, limit) {
+        return this.composite.read(filePath, offset, limit);
+    }
+    readRaw(filePath) {
+        return this.composite.readRaw(filePath);
+    }
+    grepRaw(pattern, filePath, glob) {
+        return this.composite.grepRaw(pattern, filePath ?? undefined, glob ?? undefined);
+    }
+    globInfo(pattern, filePath) {
+        return this.composite.globInfo(pattern, filePath);
+    }
+    write(filePath, content) {
+        return this.composite.write(filePath, content);
+    }
+    edit(filePath, oldString, newString, replaceAll) {
+        return this.composite.edit(filePath, oldString, newString, replaceAll);
+    }
+    uploadFiles(files) {
+        return this.composite.uploadFiles(files);
+    }
+    downloadFiles(paths) {
+        return this.composite.downloadFiles(paths);
+    }
+}
+function createInlineBackendResolver(workspace) {
+    return (binding) => {
+        const backendConfig = binding.deepAgentParams?.backend;
+        if (!backendConfig || typeof backendConfig !== "object") {
+            return undefined;
+        }
+        const resolveBackendRootDir = (configuredRootDir) => {
+            if (typeof configuredRootDir === "string" && configuredRootDir.trim().length > 0) {
+                return path.isAbsolute(configuredRootDir)
+                    ? configuredRootDir
+                    : path.resolve(workspace.workspaceRoot, configuredRootDir);
+            }
+            return workspace.workspaceRoot;
+        };
+        const createBackend = (kind, config, runtimeLike) => {
+            switch (kind) {
+                case "LocalShellBackend": {
+                    const rootDir = resolveBackendRootDir(config?.rootDir);
+                    mkdirSync(rootDir, { recursive: true });
+                    return new LocalShellBackend({
+                        rootDir,
+                        virtualMode: config?.virtualMode === 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.`);
+            }
+        };
+        return (runtimeLike) => {
+            const kind = typeof backendConfig.kind === "string" ? backendConfig.kind : "CompositeBackend";
+            switch (kind) {
+                case "LocalShellBackend":
+                    return createBackend("LocalShellBackend", backendConfig, runtimeLike);
+                case "StateBackend":
+                    return new StateBackend(runtimeLike);
+                case "StoreBackend":
+                    return new StoreBackend(runtimeLike);
+                case "CompositeBackend": {
+                    const stateConfig = typeof backendConfig.state === "object" && backendConfig.state
+                        ? backendConfig.state
+                        : { kind: "StateBackend" };
+                    const defaultBackendKind = typeof stateConfig.kind === "string" ? stateConfig.kind : "StateBackend";
+                    const routes = typeof backendConfig.routes === "object" && backendConfig.routes
+                        ? backendConfig.routes
+                        : { "/memories/": { kind: "StoreBackend" } };
+                    const mappedRoutes = Object.fromEntries(Object.entries(routes).map(([route, routeConfig]) => {
+                        const routeKind = typeof routeConfig?.kind === "string" ? routeConfig.kind : "StoreBackend";
+                        return [route, createBackend(routeKind, routeConfig, runtimeLike)];
+                    }));
+                    return new CompatibleCompositeBackend(createBackend(defaultBackendKind, stateConfig, runtimeLike), mappedRoutes);
+                }
+                default:
+                    throw new Error(`Unsupported DeepAgent backend kind "${kind}". Supported inline kinds: LocalShellBackend, StateBackend, StoreBackend, CompositeBackend.`);
+            }
+        };
+    };
+}
 function requireLocalResource(feature) {
     if (localResource) {
         return localResource;
@@ -385,7 +493,17 @@ export async function listResourceToolsForSource(source, workspaceRoot = process
 }
 export function createResourceBackendResolver(workspace) {
     const localResolver = createProviderBackendResolver(localResource, workspace);
-    return (binding) => localResolver?.(binding);
+    const remoteResolvers = (workspace.resourceSources ?? workspace.builtinSources ?? [])
+        .map((source) => remoteResourceCache.get(source))
+        .filter((provider) => Boolean(provider))
+        .map((provider) => createProviderBackendResolver(provider, workspace))
+        .filter((resolver) => Boolean(resolver));
+    const inlineResolver = createInlineBackendResolver(workspace);
+    return (binding) => {
+        const providerResolved = localResolver?.(binding) ??
+            remoteResolvers.map((resolver) => resolver(binding)).find((resolved) => resolved !== undefined);
+        return providerResolved ?? inlineResolver(binding);
+    };
 }
 export function createResourceToolResolver(workspace, options = {}) {
     const functionResolver = createFunctionToolResolver(workspace);

package/package.json

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