@botbotgo/agent-harness 0.0.53 → 0.0.55

package/README.md

@@ -6,21 +6,27 @@
 
 It is not a new agent framework. It is the runtime layer around LangChain v1 and DeepAgents that turns one workspace into one operable application runtime.
 
-The boundary is strict:
+The product boundary is strict:
 
 - LangChain v1 and DeepAgents own agent execution semantics
-- `agent-harness` owns application-level orchestration and lifecycle management
+- `agent-harness` owns application-level orchestration and lifecycle management stays in the harness
 
 That means:
 
 - public API stays small
 - complex setup and operating policy live in YAML
-- application-level orchestration and lifecycle management stays in the harness
 - runtime lifecycle stays stable even if backend implementations change
+- backend internals stay behind adapters
+
+The repository also keeps two boundary documents current:
+
+- `docs/upstream-feature-matrix.md`
+- `docs/product-boundary.md`
+- `docs/feature-checklist.md`
 
 What the runtime provides:
 
-- `createAgentHarness(...)`, `run(...)`, `subscribe(...)`, inspection methods, and `stop(...)`
+- `createAgentHarness(workspaceRoot)`, `run(...)`, `resolveApproval(...)`, `subscribe(...)`, inspection methods, and `stop(...)`
 - YAML-defined workspace assembly for routing, models, tools, stores, backends, MCP, recovery, and maintenance
 - backend-adapted execution with current LangChain v1 and DeepAgents adapters
 - local `resources/tools/` and `resources/skills/` discovery
@@ -90,6 +96,14 @@ try {
 - MCP bridge support for agent-declared MCP servers
 - MCP server support for exposing harness tools outward
 
+## Design Notes
+
+- `agent-harness` is not a third agent framework
+- LangChain v1 and DeepAgents own agent execution semantics
+- `agent-harness` owns workspace assembly, runtime lifecycle, approvals, inspection, recovery, and operations
+- when upstream already has the feature, prefer passthrough or light YAML adaptation over a new harness abstraction
+- when a feature can be expressed in YAML, prefer YAML over expanding the public API
+
 ## How To Use
 
 ### Create A Runtime
@@ -124,12 +138,12 @@ const result = await run(runtime, {
 });
 ```
 
-`run(runtime, { ... })` creates or continues a persisted thread and returns `threadId`, `runId`, `state`, and a simple text `output`. When upstream returns richer output, the runtime also preserves `outputContent`, `contentBlocks`, and `structuredResponse` without making the basic API larger.
+`run(runtime, { ... })` creates or continues a persisted thread and returns `threadId`, `runId`, `state`, and a compact text `output`. Richer upstream results remain available through `outputContent`, `contentBlocks`, and `structuredResponse` without expanding the main facade.
 
 Use `invocation` as the runtime-facing request envelope:
 
 - `invocation.context` for request-scoped execution context
-- `invocation.inputs` for additional structured runtime inputs
+- `invocation.inputs` for structured runtime inputs
 - `invocation.attachments` for attachment-like payloads that the active backend can interpret
 
 ### Let The Runtime Route
@@ -141,7 +155,7 @@ const result = await run(runtime, {
 });
 ```
 
-`agentId: "auto"` evaluates ordered `routing.rules`, then `routing.defaultAgentId`, and only falls back to model routing when `routing.modelRouting: true`.
+`agentId: "auto"` evaluates ordered routing rules in `config/workspace.yaml`, then `routing.defaultAgentId`, and only falls back to model routing when `routing.modelRouting: true`.
 
 ### Stream Output And Events
 
@@ -183,12 +197,20 @@ import {
   getThread,
   listApprovals,
   listThreads,
+  resolveApproval,
 } from "@botbotgo/agent-harness";
 
 const threads = await listThreads(runtime);
 const thread = await getThread(runtime, threads[0]!.threadId);
 const approvals = await listApprovals(runtime, { status: "pending" });
 const approval = approvals[0] ? await getApproval(runtime, approvals[0].approvalId) : null;
+
+if (approval) {
+  await resolveApproval(runtime, {
+    approvalId: approval.approvalId,
+    decision: "approve",
+  });
+}
 ```
 
 These methods return runtime-facing records, not raw persistence or backend checkpoint objects.
@@ -279,8 +301,6 @@ Primary fields:
 
 If `runRoot` is omitted, the runtime defaults to `<workspace-root>/run-data`.
 
-Queued runs are persisted under `runRoot` and continue after process restart. `running` runs are only replayed on startup when the bound tools are retryable.
-
 ### `config/agent-context.md`
 
 Use this file for shared bootstrap context loaded into agents at construction time.
@@ -301,7 +321,7 @@ spec:
     temperature: 0.2
 ```
 
-These load as `model/<name>`.
+These load as `model/default`.
 
 ### `config/embedding-models.yaml`
 
@@ -332,19 +352,6 @@ spec:
     path: checkpoints.sqlite
 ```
 
-Built-in store kinds today:
-
-- `FileStore`
-- `InMemoryStore`
-
-Built-in checkpointer kinds today:
-
-- `MemorySaver`
-- `FileCheckpointer`
-- `SqliteSaver`
-
-If you need other store or checkpointer implementations, inject them through runtime resolvers instead of treating them as built-in harness features.
-
 ### `config/backends.yaml`
 
 Use reusable DeepAgent backend presets so filesystem and long-term memory topology stays in YAML instead of application code:
@@ -370,17 +377,9 @@ spec:
 
 Use this file for reusable tool objects.
 
-Supported tool families in the built-in runtime include:
-
-- function tools
-- backend tools
-- MCP tools
-- provider-native tools
-- bundles
-
-Provider-native tools are declared in YAML and resolved directly to upstream provider tool factories such as OpenAI and Anthropic tool objects.
+Supported tool families in the built-in runtime include function tools, backend tools, MCP tools, provider-native tools, and bundles.
 
-Use `retryable` carefully. Mark a tool retryable only when repeated execution is safe or intentionally idempotent.
+Provider-native tools are declared in YAML and resolved directly to upstream provider tool factories.
 
 ### `config/mcp.yaml`
 
@@ -457,36 +456,7 @@ spec:
       taskDescription: Complete delegated sidecar work and return concise results.
 ```
 
-Client-configurable agent fields include:
-
-- `metadata.name`
-- `metadata.description`
-- `spec.execution.backend`
-- `spec.runtime.runRoot`
-- `spec.execution.modelRef`
-- `spec.execution.tools`
-- `spec.execution.skills`
-- `spec.execution.memory`
-- `spec.execution.subagents`
-- `spec.execution.mcpServers`
-- `spec.execution.config.systemPrompt`
-- `spec.execution.config.checkpointer`
-- `spec.execution.config.store`
-- `spec.execution.config.backend`
-- `spec.execution.config.middleware`
-- `spec.execution.config.responseFormat`
-- `spec.execution.config.contextSchema`
-- `spec.execution.config.stateSchema`
-- `spec.execution.config.interruptOn`
-- `spec.execution.config.filesystem`
-- `spec.execution.config.taskDescription`
-- `spec.execution.config.generalPurposeAgent`
-- `spec.execution.config.includeAgentName`
-- `spec.execution.config.version`
-
-For backend-specific agent options, prefer passing the upstream concept directly inside `spec.execution.config`. The loader keeps a small stable product shape, but it also preserves adapter-facing passthrough fields so new LangChain v1 or DeepAgents parameters can flow into adapters without expanding the public API surface.
-
-Upstream feature coverage is tracked in [docs/upstream-feature-matrix.md](docs/upstream-feature-matrix.md).
+For backend-specific agent options, prefer the upstream concept directly inside `spec.execution.config`. Upstream feature coverage is tracked in [docs/upstream-feature-matrix.md](docs/upstream-feature-matrix.md).
 
 ### `resources/`
 
@@ -497,10 +467,6 @@ Use `resources/` for executable local extensions:
 
 Tool modules are discovered from `resources/tools/*.js`, `resources/tools/*.mjs`, and `resources/tools/*.cjs`.
 
-The preferred tool module format is exporting `tool({...})`.
-
-SKILL packages are discovered from `resources/skills/` and attached to agents through YAML.
-
 ## Design Notes
 
 - public runtime contract stays generic and small
@@ -518,6 +484,7 @@ Primary exports:
 
 - `createAgentHarness`
 - `run`
+- `resolveApproval`
 - `subscribe`
 - `listThreads`
 - `getThread`

package/dist/api.d.ts

@@ -1,4 +1,4 @@
-import type { ApprovalRecord, RunOptions, RuntimeAdapterOptions, ThreadSummary, ThreadRecord, WorkspaceLoadOptions, WorkspaceBundle } from "./contracts/types.js";
+import type { ApprovalRecord, RunOptions, ResumeOptions, RuntimeAdapterOptions, ThreadSummary, ThreadRecord, WorkspaceLoadOptions } from "./contracts/types.js";
 import { AgentHarnessRuntime } from "./runtime/harness.js";
 import type { ToolMcpServerOptions } from "./mcp.js";
 export { AgentHarnessRuntime } from "./runtime/harness.js";
@@ -8,7 +8,6 @@ type CreateAgentHarnessOptions = {
 };
 export declare function createAgentHarness(): Promise<AgentHarnessRuntime>;
 export declare function createAgentHarness(workspaceRoot: string, options?: CreateAgentHarnessOptions): Promise<AgentHarnessRuntime>;
-export declare function createAgentHarness(workspace: WorkspaceBundle, options?: CreateAgentHarnessOptions): Promise<AgentHarnessRuntime>;
 export declare function run(runtime: AgentHarnessRuntime, options: RunOptions): Promise<import("./contracts/types.js").RunResult>;
 export declare function subscribe(runtime: AgentHarnessRuntime, listener: Parameters<AgentHarnessRuntime["subscribe"]>[0]): () => void;
 export declare function listThreads(runtime: AgentHarnessRuntime, filter?: Parameters<AgentHarnessRuntime["listThreads"]>[0]): Promise<ThreadSummary[]>;
@@ -16,6 +15,7 @@ export declare function getThread(runtime: AgentHarnessRuntime, threadId: string
 export declare function deleteThread(runtime: AgentHarnessRuntime, threadId: string): Promise<boolean>;
 export declare function listApprovals(runtime: AgentHarnessRuntime, filter?: Parameters<AgentHarnessRuntime["listApprovals"]>[0]): Promise<ApprovalRecord[]>;
 export declare function getApproval(runtime: AgentHarnessRuntime, approvalId: string): Promise<ApprovalRecord | null>;
+export declare function resolveApproval(runtime: AgentHarnessRuntime, options: ResumeOptions): Promise<import("./contracts/types.js").RunResult>;
 export declare function stop(runtime: AgentHarnessRuntime): Promise<void>;
 export declare function createToolMcpServer(runtime: AgentHarnessRuntime, options: ToolMcpServerOptions): Promise<import("@modelcontextprotocol/sdk/server/mcp.js").McpServer>;
 export declare function serveToolsOverStdio(runtime: AgentHarnessRuntime, options: ToolMcpServerOptions): Promise<import("@modelcontextprotocol/sdk/server/mcp.js").McpServer>;

package/dist/api.js

@@ -1,10 +1,8 @@
 import { AgentHarnessRuntime } from "./runtime/harness.js";
 import { loadWorkspace } from "./workspace/compile.js";
 export { AgentHarnessRuntime } from "./runtime/harness.js";
-export async function createAgentHarness(input = process.cwd(), options = {}) {
-    const workspace = typeof input === "string"
-        ? await loadWorkspace(input, options.load ?? {})
-        : input;
+export async function createAgentHarness(workspaceRoot = process.cwd(), options = {}) {
+    const workspace = await loadWorkspace(workspaceRoot, options.load ?? {});
     const harness = new AgentHarnessRuntime(workspace, options.adapter ?? {});
     await harness.initialize();
     return harness;
@@ -30,6 +28,9 @@ export async function listApprovals(runtime, filter) {
 export async function getApproval(runtime, approvalId) {
     return runtime.getApproval(approvalId);
 }
+export async function resolveApproval(runtime, options) {
+    return runtime.resume(options);
+}
 export async function stop(runtime) {
     return runtime.stop();
 }

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { AgentHarnessRuntime, createAgentHarness, createToolMcpServer, deleteThread, getApproval, getThread, listApprovals, listThreads, run, serveToolsOverStdio, subscribe, stop, } from "./api.js";
+export { AgentHarnessRuntime, createAgentHarness, createToolMcpServer, deleteThread, getApproval, getThread, listApprovals, listThreads, resolveApproval, run, serveToolsOverStdio, subscribe, stop, } from "./api.js";
 export type { ToolMcpServerOptions } from "./mcp.js";
 export { tool } from "./tools.js";

package/dist/index.js

@@ -1,2 +1,2 @@
-export { AgentHarnessRuntime, createAgentHarness, createToolMcpServer, deleteThread, getApproval, getThread, listApprovals, listThreads, run, serveToolsOverStdio, subscribe, stop, } from "./api.js";
+export { AgentHarnessRuntime, createAgentHarness, createToolMcpServer, deleteThread, getApproval, getThread, listApprovals, listThreads, resolveApproval, run, serveToolsOverStdio, subscribe, stop, } from "./api.js";
 export { tool } from "./tools.js";

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.52";
+export declare const AGENT_HARNESS_VERSION = "0.0.54";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.52";
+export const AGENT_HARNESS_VERSION = "0.0.54";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.53",
+  "version": "0.0.55",
   "description": "Workspace runtime for multi-agent applications",
   "type": "module",
   "packageManager": "npm@10.9.2",
@@ -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/stock-research-app-run.test.ts test/stock-research-app-config.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/runtime-capabilities.test.ts test/runtime-recovery.test.ts test/tool-extension-gaps.test.ts test/checkpoint-maintenance.test.ts test/llamaindex-dependency-compat.test.ts test/skill-standard.test.ts test/routing-config.test.ts test/workspace-compat-regressions.test.ts test/upstream-compat-regressions.test.ts test/yaml-format.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/stock-research-app-config.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/product-boundary-docs.test.ts test/runtime-adapter-regressions.test.ts test/runtime-capabilities.test.ts test/runtime-recovery.test.ts test/tool-extension-gaps.test.ts test/checkpoint-maintenance.test.ts test/llamaindex-dependency-compat.test.ts test/skill-standard.test.ts test/routing-config.test.ts test/workspace-compat-regressions.test.ts test/upstream-compat-regressions.test.ts test/yaml-format.test.ts",
     "test:real-providers": "vitest run test/real-provider-harness.test.ts",
     "release:prepare": "npm version patch --no-git-tag-version && node ./scripts/sync-example-version.mjs",
     "release:pack": "npm pack --dry-run",