@botbotgo/agent-harness 0.0.48 → 0.0.50

package/README.md

@@ -4,20 +4,26 @@
 
 `@botbotgo/agent-harness` is a workspace-shaped application runtime for real agent products.
 
-It is not a new agent framework. It is the layer that sits around LangChain v1 and DeepAgents so an application can be assembled, configured, operated, and recovered as one runtime.
+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 package is built for the gap between:
+The product boundary is:
 
-- agent execution semantics owned by LangChain v1 and DeepAgents
-- application runtime concerns such as persisted threads, approvals, recovery, routing, maintenance, and local resource loading
+- LangChain v1 and DeepAgents own agent execution semantics
+- `agent-harness` owns application runtime semantics
 
-What it provides:
+That means:
 
-- a small runtime API centered on `createAgentHarness(...)`, `run(...)`, `subscribe(...)`, inspection methods, and `stop(...)`
-- YAML-defined runtime assembly for hosts, models, routing, recovery, concurrency, MCP, and maintenance policy
-- backend-adapted execution with a generic runtime contract and current LangChain v1 / DeepAgents adapters
-- local `resources/tools/` and `resources/skills/` loading
-- persisted runs, threads, approvals, events, queued tasks, and resumable checkpoints
+- public API stays small
+- complex assembly and policy live in YAML
+- runtime lifecycle stays stable even if the backend implementation changes
+
+What the runtime provides:
+
+- `createAgentHarness(...)`, `run(...)`, `subscribe(...)`, inspection methods, and `stop(...)`
+- YAML-defined workspace assembly for routing, models, tools, stores, MCP, recovery, and maintenance
+- backend-adapted execution with current LangChain v1 and DeepAgents adapters
+- local `resources/tools/` and `resources/skills/` discovery
+- persisted threads, runs, approvals, events, queue state, and recovery metadata
 
 ## Quick Start
 
@@ -32,8 +38,8 @@ Workspace layout:
 ```text
 your-workspace/
   config/
-    agent-context.md
     workspace.yaml
+    agent-context.md
     models.yaml
     embedding-models.yaml
     vector-stores.yaml
@@ -71,15 +77,16 @@ try {
 ## Feature List
 
 - Workspace runtime for multi-agent applications
-- Generic runtime contract with backend-adapted execution
-- YAML-defined host routing
+- Small public runtime contract
+- YAML-defined host routing and runtime policy
+- LangChain v1 and DeepAgents backend adaptation
 - Auto-discovered local tools and SKILL packages
+- provider-native tools, MCP tools, and workspace-local tool modules
+- persisted threads, runs, approvals, lifecycle events, and queued runs
+- runtime-managed recovery and checkpoint maintenance
+- structured output and multimodal content preservation in run results
 - MCP bridge support for agent-declared MCP servers
 - MCP server support for exposing harness tools outward
-- Persisted threads, runs, approvals, and lifecycle events
-- Recovery policy and resumable checkpoints
-- Background checkpoint maintenance
-- Runtime-level concurrency control and queued-run persistence
 
 ## How To Use
 
@@ -91,8 +98,6 @@ import { AgentHarnessRuntime, createAgentHarness } from "@botbotgo/agent-harness
 const runtime: AgentHarnessRuntime = await createAgentHarness("/absolute/path/to/workspace");
 ```
 
-You can also create a runtime from a precompiled `WorkspaceBundle`.
-
 `createAgentHarness(...)` loads one workspace, resolves `resources/`, initializes persistence under `runRoot`, and starts runtime maintenance.
 
 ### Run A Request
@@ -103,25 +108,28 @@ import { run } from "@botbotgo/agent-harness";
 const result = await run(runtime, {
   agentId: "orchestra",
   input: "Summarize the runtime design.",
-  context: {
-    requestId: "req-123",
-  },
-  state: {
-    visitCount: 1,
+  invocation: {
+    context: {
+      requestId: "req-123",
+    },
+    inputs: {
+      visitCount: 1,
+    },
+    attachments: {
+      "/tmp/spec.md": { content: "draft" },
+    },
   },
 });
 ```
 
-Each run creates or continues a persisted thread and returns `threadId`, `runId`, `state`, and the final user-facing output text.
+`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.
 
-The preferred runtime-facing way to pass execution metadata is `invocation`:
+Use `invocation` as the runtime-facing request envelope:
 
-- `invocation.context` for request-scoped context
+- `invocation.context` for request-scoped execution context
 - `invocation.inputs` for additional structured runtime inputs
 - `invocation.attachments` for attachment-like payloads that the active backend can interpret
 
-For compatibility, `context`, `state`, and `files` are still accepted as existing aliases and are normalized into the same runtime invocation envelope.
-
 ### Let The Runtime Route
 
 ```ts
@@ -143,6 +151,9 @@ const result = await run(runtime, {
     onChunk(chunk) {
       process.stdout.write(chunk);
     },
+    onContentBlocks(blocks) {
+      console.log(blocks);
+    },
     onEvent(event) {
       console.log(event.eventType, event.payload);
     },
@@ -152,7 +163,7 @@ const result = await run(runtime, {
 
 `subscribe(...)` is a read-only observer surface over stored lifecycle events.
 
-The event stream includes:
+The runtime event stream includes:
 
 - `run.created`
 - `run.queued`
@@ -183,14 +194,18 @@ These methods return runtime-facing records, not raw persistence or backend chec
 ### Bridge MCP Servers Into Agents
 
 ```yaml
+apiVersion: agent-harness/v1alpha1
+kind: Agent
+metadata:
+  name: orchestra
 spec:
+  execution:
+    backend: deepagent
+  modelRef: model/default
   mcpServers:
     - name: browser
       command: node
       args: ["./mcp-browser-server.mjs"]
-    - name: docs
-      transport: http
-      url: https://example.com/mcp
 ```
 
 The runtime discovers MCP tools, filters them through agent configuration, and exposes them like other tools.
@@ -214,6 +229,11 @@ await stop(runtime);
 
 ## How To Configure
 
+Use Kubernetes-style YAML:
+
+- collection files use `apiVersion`, plural `kind`, and `spec: []`
+- single-object files use `apiVersion`, singular `kind`, `metadata`, and `spec`
+
 Core workspace files:
 
 - `config/workspace.yaml`
@@ -226,24 +246,12 @@ Core workspace files:
 - `config/mcp.yaml`
 - `config/agents/direct.yaml`
 - `config/agents/orchestra.yaml`
-- `resources/package.json`
 - `resources/tools/`
 - `resources/skills/`
 
-Use Kubernetes-style YAML:
-
-- collection files use `apiVersion`, plural `kind`, and `spec: []`
-- single-object files use `apiVersion`, singular `kind`, `metadata`, and `spec`
+There are three configuration layers:
 
-Use distinct names for named objects such as models, stores, checkpointers, tools, and MCP servers.
-
-### Client-Configurable YAML Reference
-
-This section is the client-facing explanation of what can be configured in YAML today and what each field changes at runtime.
-
-There are three layers of client configuration:
-
-- runtime-level policy in `config/workspace.yaml`
+- runtime policy in `config/workspace.yaml`
 - reusable object catalogs in `config/*.yaml`
 - agent assembly in `config/agents/*.yaml`
 
@@ -253,92 +261,30 @@ Use this file for runtime-level policy shared by the whole workspace.
 
 Primary fields:
 
-- `runRoot`: root directory where the runtime stores thread indexes, runs, approvals, artifacts, queued requests, and default local persistence
-- `routing.defaultAgentId`: default host selected when no explicit routing rule matches
-- `routing.rules`: ordered YAML routing rules evaluated before backend routing
-- `routing.systemPrompt`: optional model-classifier prompt used only when model routing is enabled
-- `routing.modelRouting`: opt in to model-driven host classification fallback
-- `concurrency.maxConcurrentRuns`: maximum number of active runs; extra runs enter the persistent queue
-- `recovery.enabled`: enables runtime-managed startup recovery
-- `recovery.resumeOnStartup`: compatibility alias for resuming interrupted approval-driven runs on startup
-- `recovery.resumeResumingRunsOnStartup`: explicit control for resuming interrupted approval-driven runs on startup
-- `recovery.maxRecoveryAttempts`: upper bound for startup recovery retries
-- `maintenance.checkpoints.enabled`: turns on background checkpoint cleanup
-- `maintenance.checkpoints.schedule.intervalSeconds`: maintenance loop interval
-- `maintenance.checkpoints.schedule.runOnStartup`: run checkpoint cleanup during startup
-- `maintenance.checkpoints.policies.maxAgeSeconds`: age-based checkpoint cleanup
-- `maintenance.checkpoints.policies.maxBytes`: size-based checkpoint cleanup
-- `maintenance.checkpoints.sqlite.sweepBatchSize`: batch size for SQLite cleanup scans
-- `maintenance.checkpoints.sqlite.vacuum`: vacuum SQLite after deletions
+- `runRoot`
+- `concurrency.maxConcurrentRuns`
+- `routing.defaultAgentId`
+- `routing.rules`
+- `routing.systemPrompt`
+- `routing.modelRouting`
+- `maintenance.checkpoints`
+- `recovery.enabled`
+- `recovery.resumeResumingRunsOnStartup`
+- `recovery.maxRecoveryAttempts`
 
 If `runRoot` is omitted, the runtime defaults to `<workspace-root>/run-data`.
 
-Example:
-
-```yaml
-apiVersion: agent-harness/v1alpha1
-kind: Runtime
-metadata:
-  name: default
-spec:
-  runRoot: ./.agent
-  concurrency:
-    maxConcurrentRuns: 3
-  routing:
-    defaultAgentId: orchestra
-    modelRouting: false
-    rules:
-      - agentId: orchestra
-        contains: ["latest", "recent", "today", "news"]
-      - agentId: orchestra
-        regex:
-          - "\\b(create|build|implement|fix|debug|review|inspect)\\b"
-  maintenance:
-    checkpoints:
-      enabled: true
-      schedule:
-        intervalSeconds: 3600
-        runOnStartup: true
-      policies:
-        maxAgeSeconds: 604800
-      sqlite:
-        sweepBatchSize: 200
-        vacuum: false
-  recovery:
-    enabled: true
-    resumeResumingRunsOnStartup: true
-    maxRecoveryAttempts: 3
-```
-
-Notes:
-
-- `routing.rules` only choose the starting host agent; they do not replace backend planning semantics
-- queued runs are persisted under `runRoot` and continue after process restart
-- `running` runs are only replayed on startup when the bound tools are retryable
+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 startup context loaded into agents at construction time.
+Use this file for shared bootstrap context loaded into agents at construction time.
 
 Put stable project context here. Do not use it as mutable long-term memory.
 
-Good uses:
-
-- product positioning
-- codebase conventions
-- stable domain vocabulary
-- organization-specific rules
-
-Bad uses:
-
-- transient scratch notes
-- per-run execution state
-- approval packets
-- long-term memory that should live in the store
-
 ### `config/models.yaml`
 
-Use one file for multiple named models:
+Use named chat-model presets:
 
 ```yaml
 apiVersion: agent-harness/v1alpha1
@@ -348,80 +294,21 @@ spec:
     provider: openai
     model: gpt-4.1
     temperature: 0.2
-  - name: planner
-    provider: openai
-    model: gpt-4.1-mini
 ```
 
-These load as `model/default` and `model/planner`.
-
-Client-configurable model fields:
-
-- `name`: catalog name referenced by `model/<name>`
-- `provider`: provider family such as `openai`, `openai-compatible`, `ollama`, `anthropic`, or `google`
-- `model`: provider model id
-- top-level provider init fields such as `temperature`, `baseUrl`, API-specific settings, and client options
-- `clientRef`: optional external client reference
-- `fallbacks`: optional fallback model refs
-- `metadata`: optional model metadata
+These load as `model/<name>`.
 
 ### `config/embedding-models.yaml`
 
-Use this file for named embedding model presets used by retrieval-oriented tools.
-
-```yaml
-apiVersion: agent-harness/v1alpha1
-kind: EmbeddingModels
-spec:
-  - name: default
-    provider: ollama
-    model: nomic-embed-text
-    baseUrl: http://localhost:11434
-```
-
-Client-configurable embedding fields:
-
-- `name`
-- `provider`
-- `model`
-- top-level provider init fields such as `baseUrl`
-- `clientRef`
-- `metadata`
-
-These load as `embedding-model/default`.
+Use named embedding-model presets for retrieval-oriented tools.
 
 ### `config/vector-stores.yaml`
 
-Use this file for named vector store presets referenced by retrieval tools.
-
-```yaml
-apiVersion: agent-harness/v1alpha1
-kind: VectorStores
-spec:
-  - name: default
-    storeKind: LibSQLVectorStore
-    url: file:.agent/vector-store.db
-    table: rag_chunks
-    column: embedding
-    embeddingModelRef: embedding-model/default
-```
-
-Client-configurable vector store fields:
-
-- `name`
-- `storeKind`
-- `url`
-- `authToken`
-- `table`
-- `column`
-- `embeddingModelRef`
-- `metadata`
-
-These load as `vector-store/default`.
+Use named vector-store presets referenced by retrieval tools.
 
 ### `config/stores.yaml`
 
-Use one file for named persistence presets:
+Use reusable store and checkpointer presets:
 
 ```yaml
 apiVersion: agent-harness/v1alpha1
@@ -436,119 +323,31 @@ spec:
     checkpointerKind: MemorySaver
 ```
 
-These load as `store/default` and `checkpointer/default`.
-
-Client-configurable store fields:
-
-- `kind: Store` for backend stores
-- `kind: Checkpointer` for resumable execution state
-- `name` for refs
-- `storeKind` such as `FileStore`, `InMemoryStore`, `RedisStore`, `PostgresStore`
-- `checkpointerKind` such as `MemorySaver`, `FileCheckpointer`, `SqliteSaver`
-- storage-specific fields such as `path`, connection strings, auth, and provider options
-
 ### `config/tools.yaml`
 
-Use this file for reusable tool presets and tool bundles.
-
-Minimal collection form:
+Use this file for reusable tool objects.
 
-```yaml
-apiVersion: agent-harness/v1alpha1
-kind: Tools
-spec:
-  - kind: Tool
-    name: fetch_docs
-    type: function
-    description: Fetch a documentation page.
-```
+Supported tool families in the built-in runtime include:
 
-Client-configurable tool fields:
+- function tools
+- backend tools
+- MCP tools
+- provider-native tools
+- bundles
 
-- `name`
-- `type`: `function`, `backend`, `mcp`, or `bundle`
-- `description`
-- `implementationName` for local JS tool modules
-- `inputSchema.ref`
-- `backend.operation`
-- `mcp.ref` or `mcp.tool`
-- `refs` for bundle composition
-- `hitl.enabled` and `hitl.allow` for approval-gated tools
-- `retryable: true` for tools that are safe to replay during startup recovery
-- `config` for tool-specific options
+Provider-native tools are declared in YAML and resolved directly to upstream provider tool factories such as OpenAI and Anthropic tool objects.
 
 Use `retryable` carefully. Mark a tool retryable only when repeated execution is safe or intentionally idempotent.
 
 ### `config/mcp.yaml`
 
-Use this file for reusable MCP server definitions and MCP-backed tool presets.
-
-```yaml
-apiVersion: agent-harness/v1alpha1
-kind: McpServers
-spec:
-  - name: docs
-    transport: http
-    url: https://example.com/mcp
-  - name: local-browser
-    transport: stdio
-    command: node
-    args: ["./mcp-browser-server.mjs"]
-```
-
-Client-configurable MCP fields:
-
-- `name`
-- `transport`: `stdio`, `http`, `sse`, or `websocket`
-- `command`, `args`, `env`, `cwd` for stdio servers
-- `url`, `token`, `headers` for network servers
-
-These load as `mcp/<name>`.
+Use this file for named MCP server presets.
 
 ### `config/agents/*.yaml`
 
-Prefer the generic agent form and declare the current execution backend explicitly:
-
-```yaml
-apiVersion: agent-harness/v1alpha1
-kind: Agent
-metadata:
-  name: orchestra
-spec:
-  modelRef: model/default
-  execution:
-    backend: deepagent
-  systemPrompt: Coordinate the request.
-```
-
-Only `kind: Agent` is supported for agent objects. Select the concrete backend with `spec.execution.backend`.
-
-Common client-configurable agent fields:
-
-- `metadata.name`
-- `metadata.description`
-- `spec.execution.backend`
-- `spec.modelRef`
-- `spec.systemPrompt`
-- `spec.tools`
-- `spec.skills`
-- `spec.memory`
-- `spec.checkpointer`
-- `spec.store`
-- `spec.backend`
-- `spec.middleware`
-- `spec.subagents`
-- `spec.mcpServers`
-- `spec.responseFormat`
-- `spec.contextSchema`
-
-Typical patterns:
-
-- use `direct` as a lightweight host for simple one-turn requests
-- use `orchestra` as the main execution host for tools, multi-step work, and delegation
-- keep routing policy in `config/workspace.yaml`, not buried in prompts
+Agents are always declared with `kind: Agent` and `spec.execution.backend`.
 
-Example direct agent:
+Example lightweight host:
 
 ```yaml
 apiVersion: agent-harness/v1alpha1
@@ -561,12 +360,10 @@ spec:
   modelRef: model/default
   checkpointer:
     ref: checkpointer/default
-  systemPrompt: |-
-    You are the direct agent.
-    Answer simple requests directly.
+  systemPrompt: Answer simple requests directly.
 ```
 
-Example orchestra agent:
+Example main execution host:
 
 ```yaml
 apiVersion: agent-harness/v1alpha1
@@ -593,6 +390,27 @@ spec:
         kind: StoreBackend
 ```
 
+Client-configurable agent fields include:
+
+- `metadata.name`
+- `metadata.description`
+- `spec.execution.backend`
+- `spec.modelRef`
+- `spec.systemPrompt`
+- `spec.tools`
+- `spec.skills`
+- `spec.memory`
+- `spec.checkpointer`
+- `spec.store`
+- `spec.backend`
+- `spec.middleware`
+- `spec.subagents`
+- `spec.mcpServers`
+- `spec.responseFormat`
+- `spec.contextSchema`
+
+For backend-specific agent options, prefer passing the upstream concept directly in YAML. The loader keeps a small stable product shape, but it also preserves agent-level passthrough fields so new LangChain v1 or DeepAgents parameters can flow into adapters without expanding the public API surface.
+
 ### `resources/`
 
 Use `resources/` for executable local extensions:
@@ -604,43 +422,33 @@ Tool modules are discovered from `resources/tools/*.js`, `resources/tools/*.mjs`
 
 The preferred tool module format is exporting `tool({...})`.
 
-Example:
-
-```js
-import { z } from "zod";
-import { tool } from "@botbotgo/agent-harness/tools";
-
-export const local_lookup = tool({
-  description: "Lookup a ticker from a local tool module.",
-  retryable: true,
-  schema: {
-    ticker: z.string().min(1),
-  },
-  async invoke(input) {
-    return input.ticker.toUpperCase();
-  },
-});
-```
-
-Keep runtime extension source under `resources/`. Keep tests outside the published source tree, for example under repository `test/`.
+SKILL packages are discovered from `resources/skills/` and attached to agents through YAML.
 
 ## Design Notes
 
-- `agent-harness` should keep the public runtime contract generic while mapping cleanly onto current backend capabilities
-- agent-level execution behavior stays upstream
+- public runtime contract stays generic and small
 - application-level orchestration and lifecycle management stays in the harness
-- checkpoint resume is treated as a system-managed runtime behavior, not a primary public abstraction
-- public runtime contract generic does not mean backend-agnostic implementation internals; it means client-facing semantics stay stable even when adapters change
+- upstream LangChain v1 and DeepAgents concepts should be expressed as directly as possible in YAML
+- recovery, approvals, threads, runs, and events are runtime concepts, not backend-specific escape hatches
+- backend implementation details should stay internal unless product requirements force exposure
+- application-level orchestration and lifecycle management stays in the harness
+
+In short: `agent-harness` is a public runtime contract generic enough to survive backend changes, while the deep execution semantics stay upstream.
 
 ## API Summary
 
-- `createAgentHarness(...)`
-- `run(runtime, {...})`
-- `subscribe(...)`
-- `listThreads(...)`
-- `getThread(...)`
-- `listApprovals(...)`
-- `getApproval(...)`
-- `createToolMcpServer(...)`
-- `serveToolsOverStdio(...)`
-- `stop(...)`
+Primary exports:
+
+- `createAgentHarness`
+- `run`
+- `subscribe`
+- `listThreads`
+- `getThread`
+- `deleteThread`
+- `listApprovals`
+- `getApproval`
+- `createToolMcpServer`
+- `serveToolsOverStdio`
+- `stop`
+
+`AgentHarnessRuntime` is the concrete runtime class behind the public facade.

package/dist/contracts/types.d.ts

@@ -96,6 +96,12 @@ export type LangChainAgentParams = {
     responseFormat?: unknown;
     contextSchema?: unknown;
     middleware?: Array<Record<string, unknown>>;
+    passthrough?: Record<string, unknown>;
+    subagents?: CompiledSubAgent[];
+    memory?: string[];
+    skills?: string[];
+    generalPurposeAgent?: boolean;
+    taskDescription?: string;
     includeAgentName?: "inline";
     version?: "v1" | "v2";
     name?: string;
@@ -113,6 +119,7 @@ export type CompiledSubAgent = {
     responseFormat?: unknown;
     contextSchema?: unknown;
     middleware?: Array<Record<string, unknown>>;
+    passthrough?: Record<string, unknown>;
 };
 export type DeepAgentParams = {
     model: CompiledModel;
@@ -121,6 +128,7 @@ export type DeepAgentParams = {
     responseFormat?: unknown;
     contextSchema?: unknown;
     middleware?: Array<Record<string, unknown>>;
+    passthrough?: Record<string, unknown>;
     description: string;
     subagents: CompiledSubAgent[];
     interruptOn?: Record<string, boolean | object>;
@@ -252,6 +260,9 @@ export type RunResult = {
     state: RunState;
     output: string;
     finalMessageText?: string;
+    outputContent?: unknown;
+    contentBlocks?: unknown[];
+    structuredResponse?: unknown;
     interruptContent?: string;
     agentId?: string;
     approvalId?: string;
@@ -262,6 +273,7 @@ export type RunResult = {
 };
 export type RunListeners = {
     onChunk?: (chunk: string) => void | Promise<void>;
+    onContentBlocks?: (blocks: unknown[]) => void | Promise<void>;
     onEvent?: (event: HarnessEvent) => void | Promise<void>;
     onReasoning?: (chunk: string) => void | Promise<void>;
     onStep?: (step: string) => void | Promise<void>;
@@ -290,9 +302,6 @@ export type RunStartOptions = {
     input: MessageContent;
     threadId?: string;
     invocation?: InvocationEnvelope;
-    context?: Record<string, unknown>;
-    state?: Record<string, unknown>;
-    files?: Record<string, unknown>;
     listeners?: RunListeners;
 };
 export type RunDecisionOptions = {
@@ -316,6 +325,12 @@ export type HarnessStreamItem = {
     runId: string;
     agentId: string;
     content: string;
+} | {
+    type: "content-blocks";
+    threadId: string;
+    runId: string;
+    agentId: string;
+    contentBlocks: unknown[];
 } | {
     type: "reasoning";
     threadId: string;