@botbotgo/agent-harness 0.0.41 → 0.0.43

package/README.md

@@ -2,36 +2,26 @@
 
 ## Product Overview
 
-`@botbotgo/agent-harness` solves the gap between an agent execution engine and a real multi-agent application runtime.
+`@botbotgo/agent-harness` is a workspace-shaped application runtime for real agent products.
 
-The problem:
+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.
 
-- agent logic, tools, MCP, routing, memory, and approvals usually end up scattered across code and scripts
-- execution frameworks can run agents, but they do not give you a workspace-shaped product runtime by themselves
-- applications need persisted threads, resumability, approvals, and operational control, not just model calls
+The package is built for the gap between:
 
-What this package provides:
+- agent execution semantics owned by LangChain v1 and DeepAgents
+- application runtime concerns such as persisted threads, approvals, recovery, routing, maintenance, and local resource loading
 
-- a workspace runtime for multi-agent applications
-- YAML-defined agents, models, routing, and maintenance policy
-- local tools and SKILL packages loaded from `resources/`
-- DeepAgents-first execution with LangChain v1 compatibility
-- feature-level runtime APIs for runs, threads, approvals, and events
+What it provides:
 
-Core API:
-
-- `createAgentHarness(...)`
-- `run(...)`
-- `subscribe(...)`
-- `listThreads(...)`
-- `getThread(...)`
-- `listApprovals(...)`
-- `getApproval(...)`
-- `stop(...)`
+- 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 current DeepAgents-first defaults and LangChain v1 compatibility
+- local `resources/tools/` and `resources/skills/` loading
+- persisted runs, threads, approvals, events, and resumable checkpoints
 
 ## Quick Start
 
-Install the package:
+Install:
 
 ```bash
 npm install @botbotgo/agent-harness
@@ -54,19 +44,17 @@ your-workspace/
     skills/
 ```
 
-Use the standard layout only. Agent entry files must live under `config/agents/`.
-
 Minimal usage:
 
 ```ts
 import { createAgentHarness, run, stop } from "@botbotgo/agent-harness";
 
-const runtime = await createAgentHarness("/absolute/path/to/your-workspace");
+const runtime = await createAgentHarness("/absolute/path/to/workspace");
 
 try {
   const result = await run(runtime, {
     agentId: "auto",
-    input: "Summarize what this workspace is for.",
+    input: "Explain what this workspace is for.",
   });
 
   console.log(result.output);
@@ -77,13 +65,16 @@ try {
 
 ## Feature List
 
-- Workspace runtime with DeepAgents-first execution and LangChain v1 compatibility
-- YAML-defined host routing through `config/workspace.yaml`
-- Auto-discovered local tools and SKILL packages from `resources/tools/` and `resources/skills/`
-- MCP bridge support for agent-declared servers
-- MCP server support for exposing an agent toolset to other clients
-- Persisted threads, approvals, run lifecycle, and resumable checkpoints
+- Workspace runtime for multi-agent applications
+- Generic runtime contract with backend-adapted execution
+- YAML-defined host routing
+- Auto-discovered local tools and SKILL packages
+- 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
 
 ## How To Use
 
@@ -95,13 +86,9 @@ import { AgentHarnessRuntime, createAgentHarness } from "@botbotgo/agent-harness
 const runtime: AgentHarnessRuntime = await createAgentHarness("/absolute/path/to/workspace");
 ```
 
-Or:
+You can also create a runtime from a precompiled `WorkspaceBundle`.
 
-```ts
-const runtime = await createAgentHarness(workspaceBundle);
-```
-
-`createAgentHarness(workspaceRoot)` loads one `WorkspaceBundle`, resolves `resources/`, initializes persistence under `runRoot`, and starts runtime maintenance.
+`createAgentHarness(...)` loads one workspace, resolves `resources/`, initializes persistence under `runRoot`, and starts runtime maintenance.
 
 ### Run A Request
 
@@ -110,7 +97,7 @@ import { run } from "@botbotgo/agent-harness";
 
 const result = await run(runtime, {
   agentId: "orchestra",
-  input: "Explain the available agents in this workspace.",
+  input: "Summarize the runtime design.",
   context: {
     requestId: "req-123",
   },
@@ -120,24 +107,26 @@ const result = await run(runtime, {
 });
 ```
 
-Each run creates or continues a persisted thread. The result includes `threadId`, `runId`, `state`, and `output`.
+Each run creates or continues a persisted thread and returns `threadId`, `runId`, `state`, and the final user-facing output text.
 
-When the underlying LangChain or DeepAgents graph expects extra invocation data, `run(...)` can pass it through without inventing a parallel harness abstraction:
+The preferred runtime-facing way to pass execution metadata is `invocation`:
 
-- `context`: forwarded as LangChain v1 runtime context
-- `state`: merged into the agent invocation input for stateful graphs
-- `files`: merged into the agent invocation input so DeepAgents state-backed skills or memories can be provided at call time
+- `invocation.context` for request-scoped 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
 const result = await run(runtime, {
   agentId: "auto",
-  input: "Inspect this repository and explain the release flow.",
+  input: "Inspect the repository and explain the release flow.",
 });
 ```
 
-`agentId: "auto"` evaluates ordered `routing.rules` first, then falls back to `routing.defaultAgentId`, and only uses model routing when `routing.modelRouting: true`.
+`agentId: "auto"` evaluates ordered `routing.rules`, then `routing.defaultAgentId`, and only falls back to model routing when `routing.modelRouting: true`.
 
 ### Stream Output And Events
 
@@ -156,9 +145,9 @@ const result = await run(runtime, {
 });
 ```
 
-The runtime emits typed lifecycle events for output, state changes, approvals, and delegations. `subscribe(...)` is a read-only observer surface.
+`subscribe(...)` is a read-only observer surface over stored lifecycle events.
 
-### Query Threads And Approvals
+### Inspect Threads And Approvals
 
 ```ts
 import {
@@ -174,21 +163,7 @@ const approvals = await listApprovals(runtime, { status: "pending" });
 const approval = approvals[0] ? await getApproval(runtime, approvals[0].approvalId) : null;
 ```
 
-These methods return stored runtime data, not raw persistence, workspace, or backend instances.
-
-### Use Skills And Local Tools
-
-`agent-harness` treats `resources/skills/` as SKILL packages and `resources/tools/` as executable local tools.
-
-```yaml
-spec:
-  skills:
-    - path: resources/skills/reviewer
-  tools:
-    - ref: tool/local-toolset
-```
-
-Tool modules are discovered from `resources/tools/*.js`, `resources/tools/*.mjs`, and `resources/tools/*.cjs`. The preferred format is exporting `tool({...})`.
+These methods return runtime-facing records, not raw persistence or backend checkpoint objects.
 
 ### Bridge MCP Servers Into Agents
 
@@ -201,10 +176,9 @@ spec:
     - name: docs
       transport: http
       url: https://example.com/mcp
-      token: ${DOCS_MCP_TOKEN}
 ```
 
-The runtime discovers MCP tools, filters them through agent config, and exposes them like any other tool.
+The runtime discovers MCP tools, filters them through agent configuration, and exposes them like other tools.
 
 ### Expose Runtime Tools As An MCP Server
 
@@ -227,35 +201,60 @@ await stop(runtime);
 
 Core workspace files:
 
-- `config/workspace.yaml`: runtime defaults such as `runRoot`, routing, and maintenance
-- `config/agent-context.md`: shared bootstrap context for agents
-- `config/models.yaml`: named model presets
-- `config/agents/direct.yaml`: optional lightweight side-path host
-- `config/agents/orchestra.yaml`: default DeepAgent execution host
-- `resources/package.json`: resource package boundary
-- `resources/tools/`: local tool modules
-- `resources/skills/`: local skills
+- `config/workspace.yaml`
+- `config/agent-context.md`
+- `config/models.yaml`
+- `config/agents/direct.yaml`
+- `config/agents/orchestra.yaml`
+- `resources/package.json`
+- `resources/tools/`
+- `resources/skills/`
 
 ### `config/workspace.yaml`
 
-Use this file for:
+Use this file for runtime-level policy:
 
 - `runRoot`
-- ordered `routing.rules`
+- `routing.rules`
+- `routing.defaultAgentId`
 - `routing.systemPrompt`
+- `routing.modelRouting`
+- `concurrency.maxConcurrentRuns`
+- `recovery.enabled`
+- `recovery.resumeOnStartup`
+- `recovery.maxRecoveryAttempts`
 - `maintenance.checkpoints.*`
 
 If `runRoot` is omitted, the runtime defaults to `<workspace-root>/run-data`.
 
 ### `config/agent-context.md`
 
-Use this file for shared bootstrap context that agents read at construction time. Put stable project context here, not long-term mutable memory.
+Use this file for shared startup context loaded into agents at construction time.
+
+Put stable project context here. Do not use it as mutable long-term memory.
+
+### `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.
+```
 
-### Agent YAML
+`kind: DeepAgent` and `kind: LangChainAgent` remain supported as compatibility forms, but `kind: Agent` is the recommended product-facing entry point.
 
-Use `config/agents/*.yaml` to configure agents. Common fields include:
+Common fields include:
 
 - `modelRef`
+- `execution.backend`
 - `systemPrompt`
 - `tools`
 - `skills`
@@ -263,19 +262,39 @@ Use `config/agents/*.yaml` to configure agents. Common fields include:
 - `checkpointer`
 - `store`
 - `backend`
+- `middleware`
 - `subagents`
+- `mcpServers`
 
-### Resource Package
+### `resources/`
 
-Use `resources/` for executable extensions:
+Use `resources/` for executable local extensions:
 
-- `resources/tools/` for local tool modules
+- `resources/tools/` for tool modules
 - `resources/skills/` for SKILL packages
 
-Keep runtime extension source under `resources/`. Keep tests outside the published source tree, for example under the repository `test/` folder.
+Tool modules are discovered from `resources/tools/*.js`, `resources/tools/*.mjs`, and `resources/tools/*.cjs`.
+
+The preferred tool module format is exporting `tool({...})`.
+
+Keep runtime extension source under `resources/`. Keep tests outside the published source tree, for example under repository `test/`.
 
-### Skills And MCP
+## Design Notes
 
-- Use `resources/skills/` for reusable skill packages
-- Use `mcpServers:` in `config/agents/*.yaml` to bridge external MCP tools into an agent
-- Use `createToolMcpServer(...)` or `serveToolsOverStdio(...)` when you want the runtime to act as an MCP server for another client
+- `agent-harness` should keep the public runtime contract generic while mapping cleanly onto current backend capabilities
+- agent-level execution behavior stays upstream
+- 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
+
+## API Summary
+
+- `createAgentHarness(...)`
+- `run(...)`
+- `subscribe(...)`
+- `listThreads(...)`
+- `getThread(...)`
+- `listApprovals(...)`
+- `getApproval(...)`
+- `createToolMcpServer(...)`
+- `serveToolsOverStdio(...)`
+- `stop(...)`

package/dist/config/agents/direct.yaml

@@ -1,19 +1,20 @@
 # agent-harness feature: schema version for this declarative config object.
 apiVersion: agent-harness/v1alpha1
 # agent-harness feature: object type discriminator.
-# Available options today: `DeepAgent`, `LangChainAgent`.
-# `LangChainAgent` means this file compiles to the lightweight LangChain v1 execution path
-# rather than the upstream `createDeepAgent(...)` runtime.
-kind: LangChainAgent
+# Prefer the generic `Agent` form and select the concrete execution backend under `spec.execution`.
+kind: Agent
 metadata:
   # agent-harness feature: stable object id used for refs and host-agent selection.
   name: direct
   # agent-harness feature: human-readable summary for inventory and UI.
   description: Manual low-latency host for direct answers and lightweight inventory lookup. Do not use it as the default executor for tool-heavy or specialist-shaped tasks.
 spec:
-  # ======================
-  # LangChainAgent Features
-  # ======================
+  execution:
+    # Current backend adapter for this host profile.
+    backend: langchain-v1
+  # =====================
+  # Runtime Agent Features
+  # =====================
   # Shared LangChain v1 / DeepAgents feature: model ref for the underlying LLM used by the
   # direct-response agent. This should point at a cheap, fast, general-purpose chat model,
   # because `direct` is intended to be the low-latency path for simple requests.

package/dist/config/agents/orchestra.yaml

@@ -1,18 +1,20 @@
 # agent-harness feature: schema version for this declarative config object.
 apiVersion: agent-harness/v1alpha1
 # agent-harness feature: object type discriminator.
-# Available options today: `DeepAgent`, `LangChainAgent`.
-# `DeepAgent` means this file compiles to `createDeepAgent(...)` rather than the LangChain v1 agent path.
-kind: DeepAgent
+# Prefer the generic `Agent` form and select the concrete execution backend under `spec.execution`.
+kind: Agent
 metadata:
   # agent-harness feature: stable object id used for refs and default DeepAgents name inference.
   name: orchestra
   # agent-harness feature: human-readable summary for inventory and UI.
   description: Default execution host. Answer directly when possible, use local tools and skills first, and delegate only when a specialist is a better fit. Not a reflex delegation-only planner.
 spec:
-  # ===================
-  # DeepAgents Features
-  # ===================
+  execution:
+    # Current backend adapter for this host profile.
+    backend: deepagent
+  # =====================
+  # Runtime Agent Features
+  # =====================
   # DeepAgents aligned feature: model ref for the underlying LLM used by `createDeepAgent(...)`.
   modelRef: model/default
   # Shared LangChain v1 / DeepAgents feature: checkpointer config passed into the upstream runtime.

package/dist/contracts/types.d.ts

@@ -1,9 +1,14 @@
 export type ExecutionMode = "deepagent" | "langchain-v1";
 export declare const AUTO_AGENT_ID = "auto";
+export type RuntimeCapabilities = {
+    delegation?: boolean;
+    memory?: boolean;
+};
 export type RunState = "running" | "waiting_for_approval" | "resuming" | "completed" | "failed";
 export type ParsedAgentObject = {
     id: string;
     executionMode: ExecutionMode;
+    capabilities?: RuntimeCapabilities;
     description: string;
     modelRef: string;
     runRoot?: string;
@@ -175,6 +180,10 @@ export type CompiledTool = {
 };
 export type CompiledAgentBinding = {
     agent: ParsedAgentObject;
+    adapter?: {
+        kind: string;
+        config: Record<string, unknown>;
+    };
     langchainAgentParams?: LangChainAgentParams;
     directAgentParams?: LangChainAgentParams;
     deepAgentParams?: DeepAgentParams;
@@ -182,7 +191,8 @@ export type CompiledAgentBinding = {
         runRoot: string;
         workspaceRoot?: string;
         hostFacing: boolean;
-        checkpointer?: Record<string, unknown>;
+        capabilities?: RuntimeCapabilities;
+        checkpointer?: Record<string, unknown> | boolean;
         store?: Record<string, unknown>;
     };
 };
@@ -239,11 +249,14 @@ export type RunResult = {
     runId: string;
     state: RunState;
     output: string;
+    finalMessageText?: string;
     interruptContent?: string;
     agentId?: string;
     approvalId?: string;
     pendingActionId?: string;
     delegationId?: string;
+    artifacts?: ArtifactRecord[];
+    metadata?: Record<string, unknown>;
 };
 export type RunListeners = {
     onChunk?: (chunk: string) => void | Promise<void>;
@@ -264,10 +277,17 @@ export type MessageContentPart = {
     image_url: string;
 };
 export type MessageContent = string | MessageContentPart[];
+export type InvocationEnvelope = {
+    context?: Record<string, unknown>;
+    inputs?: Record<string, unknown>;
+    attachments?: Record<string, unknown>;
+    capabilities?: Record<string, unknown>;
+};
 export type RunStartOptions = {
     agentId?: string;
     input: MessageContent;
     threadId?: string;
+    invocation?: InvocationEnvelope;
     context?: Record<string, unknown>;
     state?: Record<string, unknown>;
     files?: Record<string, unknown>;
@@ -285,6 +305,9 @@ export type RunOptions = RunStartOptions | RunDecisionOptions;
 export type HarnessStreamItem = {
     type: "event";
     event: HarnessEvent;
+} | {
+    type: "result";
+    result: RunResult;
 } | {
     type: "content";
     threadId: string;
@@ -322,6 +345,7 @@ export type ThreadRunRecord = {
     runId: string;
     agentId: string;
     executionMode: string;
+    adapterKind?: string;
     createdAt: string;
     updatedAt: string;
     state: RunState;
@@ -362,13 +386,15 @@ export type ApprovalRecord = {
     pendingActionId: string;
     threadId: string;
     runId: string;
-    toolCallId: string;
     toolName: string;
     status: "pending" | "approved" | "edited" | "rejected" | "expired";
     requestedAt: string;
     resolvedAt: string | null;
     allowedDecisions: Array<"approve" | "edit" | "reject">;
     inputPreview: Record<string, unknown>;
+};
+export type InternalApprovalRecord = ApprovalRecord & {
+    toolCallId: string;
     checkpointRef: string;
     eventRefs: string[];
 };
@@ -405,6 +431,12 @@ export type RuntimeModelResolver = (modelId: string) => unknown;
 export type RuntimeEmbeddingModelResolver = (embeddingModelId: string) => unknown;
 export type RuntimeVectorStoreResolver = (vectorStoreId: string) => unknown;
 export type RuntimeMiddlewareResolver = (binding: CompiledAgentBinding) => unknown[];
+export type RuntimeDeclaredMiddlewareResolver = (input: {
+    kind: string;
+    config: Record<string, unknown>;
+    binding?: CompiledAgentBinding;
+    resolveModel: (model: CompiledModel) => Promise<unknown>;
+}) => unknown | unknown[] | null | undefined | Promise<unknown | unknown[] | null | undefined>;
 export type RuntimeCheckpointerResolver = (binding: CompiledAgentBinding) => unknown;
 export type RuntimeStoreResolver = (binding: CompiledAgentBinding) => unknown;
 export type RuntimeBackendResolver = (binding: CompiledAgentBinding) => unknown;
@@ -414,6 +446,7 @@ export type RuntimeAdapterOptions = {
     embeddingModelResolver?: RuntimeEmbeddingModelResolver;
     vectorStoreResolver?: RuntimeVectorStoreResolver;
     middlewareResolver?: RuntimeMiddlewareResolver;
+    declaredMiddlewareResolver?: RuntimeDeclaredMiddlewareResolver;
     checkpointerResolver?: RuntimeCheckpointerResolver;
     storeResolver?: RuntimeStoreResolver;
     backendResolver?: RuntimeBackendResolver;

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.40";
+export declare const AGENT_HARNESS_VERSION = "0.0.42";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.40";
+export const AGENT_HARNESS_VERSION = "0.0.42";

package/dist/persistence/file-store.d.ts

@@ -1,4 +1,4 @@
-import type { ApprovalRecord, ArtifactListing, ArtifactRecord, DelegationRecord, HarnessEvent, RunState, ThreadSummary, ThreadRunRecord, TranscriptMessage } from "../contracts/types.js";
+import type { ArtifactListing, ArtifactRecord, DelegationRecord, HarnessEvent, InternalApprovalRecord, RunState, ThreadSummary, ThreadRunRecord, TranscriptMessage } from "../contracts/types.js";
 type ThreadMeta = {
     threadId: string;
     workspaceId: string;
@@ -13,6 +13,7 @@ type RunMeta = {
     threadId: string;
     agentId: string;
     executionMode: string;
+    adapterKind?: string;
     createdAt: string;
     updatedAt: string;
 };
@@ -56,6 +57,7 @@ export declare class FilePersistence {
         runId: string;
         agentId: string;
         executionMode: string;
+        adapterKind?: string;
         createdAt: string;
     }): Promise<void>;
     setRunState(threadId: string, runId: string, state: RunState, checkpointRef?: string | null): Promise<void>;
@@ -66,14 +68,14 @@ export declare class FilePersistence {
     getThreadMeta(threadId: string): Promise<ThreadMeta | null>;
     listThreadRuns(threadId: string): Promise<ThreadRunRecord[]>;
     listRunEvents(threadId: string, runId: string): Promise<HarnessEvent[]>;
-    listApprovals(): Promise<ApprovalRecord[]>;
-    getApproval(approvalId: string): Promise<ApprovalRecord | null>;
-    getRunApprovals(threadId: string, runId: string): Promise<ApprovalRecord[]>;
+    listApprovals(): Promise<InternalApprovalRecord[]>;
+    getApproval(approvalId: string): Promise<InternalApprovalRecord | null>;
+    getRunApprovals(threadId: string, runId: string): Promise<InternalApprovalRecord[]>;
     getRunMeta(threadId: string, runId: string): Promise<RunMeta>;
     getRunLifecycle(threadId: string, runId: string): Promise<Lifecycle>;
     listDelegations(): Promise<DelegationRecord[]>;
-    createApproval(record: ApprovalRecord): Promise<void>;
-    resolveApproval(threadId: string, runId: string, approvalId: string, status: ApprovalRecord["status"]): Promise<ApprovalRecord>;
+    createApproval(record: InternalApprovalRecord): Promise<void>;
+    resolveApproval(threadId: string, runId: string, approvalId: string, status: InternalApprovalRecord["status"]): Promise<InternalApprovalRecord>;
     createDelegation(record: DelegationRecord): Promise<void>;
     updateDelegation(threadId: string, runId: string, delegationId: string, patch: Partial<DelegationRecord>): Promise<DelegationRecord>;
     createArtifact(threadId: string, runId: string, artifact: ArtifactRecord, content: unknown): Promise<ArtifactRecord>;

package/dist/persistence/file-store.js

@@ -54,6 +54,7 @@ export class FilePersistence {
             threadId: input.threadId,
             agentId: input.agentId,
             executionMode: input.executionMode,
+            adapterKind: input.adapterKind ?? input.executionMode,
             createdAt: input.createdAt,
             updatedAt: input.createdAt,
         };
@@ -218,6 +219,7 @@ export class FilePersistence {
                 runId: meta.runId,
                 agentId: meta.agentId,
                 executionMode: meta.executionMode,
+                adapterKind: meta.adapterKind ?? meta.executionMode,
                 createdAt: meta.createdAt,
                 updatedAt: meta.updatedAt,
                 state: lifecycle.state,

package/dist/runtime/agent-runtime-adapter.d.ts

@@ -15,7 +15,6 @@ declare class RuntimeOperationTimeoutError extends Error {
 export declare class AgentRuntimeAdapter {
     private readonly options;
     constructor(options?: RuntimeAdapterOptions);
-    private canUseSimpleDeepAgentFastPath;
     private resolveBindingTimeout;
     private resolveStreamIdleTimeout;
     private withTimeout;
@@ -28,6 +27,7 @@ export declare class AgentRuntimeAdapter {
     private buildToolNameMapping;
     private buildAgentMessages;
     private buildInvocationRequest;
+    private buildStateSnapshot;
     private buildRawModelMessages;
     private resolveTools;
     private normalizeInterruptPolicy;