@botbotgo/agent-harness 0.0.42 → 0.0.44

package/README.md

@@ -15,7 +15,7 @@ What it provides:
 
 - 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
-- DeepAgents-first execution with LangChain v1 compatibility
+- 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, and resumable checkpoints
 
@@ -35,6 +35,9 @@ your-workspace/
     agent-context.md
     workspace.yaml
     models.yaml
+    stores.yaml
+    tools.yaml
+    mcp.yaml
     agents/
       direct.yaml
       orchestra.yaml
@@ -66,7 +69,7 @@ try {
 ## Feature List
 
 - Workspace runtime for multi-agent applications
-- DeepAgents-first execution with LangChain v1 compatibility
+- 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
@@ -107,13 +110,15 @@ const result = await run(runtime, {
 });
 ```
 
-Each run creates or continues a persisted thread and returns `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 upstream LangChain v1 or DeepAgents graph expects extra invocation data, the runtime passes it through directly instead of inventing a parallel harness abstraction:
+The preferred runtime-facing way to pass execution metadata is `invocation`:
 
-- `context` is forwarded as runtime context
-- `state` is merged into the invocation input
-- `files` is merged into the invocation input for state-backed DeepAgents files, memories, and skills
+- `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
 
@@ -161,7 +166,7 @@ const approvals = await listApprovals(runtime, { status: "pending" });
 const approval = approvals[0] ? await getApproval(runtime, approvals[0].approvalId) : null;
 ```
 
-These methods return runtime-facing records, not raw persistence or backend objects.
+These methods return runtime-facing records, not raw persistence or backend checkpoint objects.
 
 ### Bridge MCP Servers Into Agents
 
@@ -202,6 +207,9 @@ Core workspace files:
 - `config/workspace.yaml`
 - `config/agent-context.md`
 - `config/models.yaml`
+- `config/stores.yaml`
+- `config/tools.yaml`
+- `config/mcp.yaml`
 - `config/agents/direct.yaml`
 - `config/agents/orchestra.yaml`
 - `resources/package.json`
@@ -233,9 +241,26 @@ Put stable project context here. Do not use it as mutable long-term memory.
 
 ### `config/agents/*.yaml`
 
-Use agent YAML for upstream-facing agent assembly. Common fields include:
+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.
+```
+
+`kind: DeepAgent` and `kind: LangChainAgent` remain supported as compatibility forms, but `kind: Agent` is the recommended product-facing entry point.
+
+Common fields include:
 
 - `modelRef`
+- `execution.backend`
 - `systemPrompt`
 - `tools`
 - `skills`
@@ -262,7 +287,7 @@ Keep runtime extension source under `resources/`. Keep tests outside the publish
 
 ## Design Notes
 
-- `agent-harness` should express LangChain v1 and DeepAgents concepts as directly as possible
+- `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

package/dist/config/agents/direct.yaml

@@ -1,30 +1,31 @@
 # 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
-  # ======================
-  # 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.
+  execution:
+    # Current backend adapter for this host profile.
+    backend: langchain-v1
+  # =====================
+  # Runtime Agent Features
+  # =====================
+  # Upstream execution 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.
   modelRef: model/default
-  # Shared LangChain v1 / DeepAgents feature: checkpointer config passed into the runtime.
+  # Runtime execution feature: checkpointer config passed into the selected backend adapter.
   # Even the lightweight direct path can benefit from resumable state during interactive use.
   # Available `kind` options in this harness: `FileCheckpointer`, `MemorySaver`, `SqliteSaver`.
   # `path` is only used by `FileCheckpointer` and `SqliteSaver`; omit it for `MemorySaver`.
   checkpointer:
-    kind: MemorySaver
-  # LangChainAgent aligned feature: system prompt for the lightweight direct-response host.
+    ref: checkpointer/default
+  # Upstream execution feature: system prompt for the lightweight direct-response host.
   # This prompt should keep the agent focused on:
   # - answering simple requests in one turn
   # - staying lightweight instead of planning or orchestrating

package/dist/config/agents/orchestra.yaml

@@ -1,29 +1,31 @@
 # 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.
+  # agent-harness feature: stable object id used for refs and runtime naming.
   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
-  # ===================
-  # DeepAgents aligned feature: model ref for the underlying LLM used by `createDeepAgent(...)`.
+  execution:
+    # Current backend adapter for this host profile.
+    backend: deepagent
+  # =====================
+  # Runtime Agent Features
+  # =====================
+  # Upstream execution feature: model ref for the underlying LLM used by this execution host.
   modelRef: model/default
-  # Shared LangChain v1 / DeepAgents feature: checkpointer config passed into the upstream runtime.
+  # Runtime execution feature: checkpointer config passed into the selected backend adapter.
   # This persists resumable graph state for this agent.
   # Available `kind` options in this harness: `FileCheckpointer`, `MemorySaver`, `SqliteSaver`.
   # `path` is only used by `FileCheckpointer` and `SqliteSaver`; omit it for `MemorySaver`.
   checkpointer:
-    # kind: FileCheckpointer
-    kind: MemorySaver
+    # ref: checkpointer/sqlite
+    ref: checkpointer/default
   memory:
-    # DeepAgents aligned feature: bootstrap memory sources supplied to the deep agent at construction time.
+    # Upstream execution feature: bootstrap memory sources supplied to the selected backend at construction time.
     # These paths resolve relative to the workspace root unless they are already absolute.
     # Treat this as agent-owned startup context, not as a dynamic long-term memory sink:
     # - keep `systemPrompt` for stable role, boundaries, and hard behavioral rules
@@ -33,13 +35,12 @@ spec:
     # Updating these files changes future agent constructions, but they are still bootstrap inputs rather than
     # self-updating runtime memory.
     - path: config/agent-context.md
-  # DeepAgents aligned feature: store config passed into `createDeepAgent({ store })`.
-  # This is the LangGraph store used by `StoreBackend` routes inside the DeepAgents backend.
+  # Upstream execution feature: store config passed into the selected backend adapter.
+  # In the default deepagent adapter this is the LangGraph store used by `StoreBackend` routes.
   # Available `kind` options in this harness: `FileStore`, `InMemoryStore`, `RedisStore`, `PostgresStore`.
   store:
-    kind: FileStore
-    path: store.json
-  # DeepAgents aligned feature: backend config passed into `createDeepAgent({ backend })`.
+    ref: store/default
+  # Upstream execution feature: backend config passed into the selected backend adapter.
   # This directly defines the backend topology for this agent:
   # - workspace execution uses a lightweight VFS sandbox
   # - long-term memory under `/memories/*` uses `StoreBackend`
@@ -57,8 +58,8 @@ spec:
       /memories/:
         # Available route backend `kind` options today: `StoreBackend`.
         kind: StoreBackend
-  # DeepAgents aligned feature: system prompt for the orchestration deep agent.
-  # This becomes the top-level instruction block for the upstream DeepAgents runtime and should hold the
+  # Upstream execution feature: system prompt for the orchestration host.
+  # This becomes the top-level instruction block for the selected execution backend and should hold the
   # agent's durable role, priorities, and behavioral guardrails rather than bulky project facts.
   systemPrompt: |-
     You are the orchestra agent.

package/dist/config/mcp.yaml

@@ -0,0 +1,20 @@
+# agent-harness feature: schema version for reusable MCP server objects.
+apiVersion: agent-harness/v1alpha1
+# This first-layer catalog is the default place to register reusable McpServer objects and MCP-backed Tool objects.
+# Examples:
+# items:
+#   - kind: McpServer
+#     metadata:
+#       name: browser
+#     spec:
+#       command: node
+#       args: ["./mcp-browser-server.mjs"]
+#
+#   - kind: Tool
+#     metadata:
+#       name: browser_navigate
+#     spec:
+#       mcp:
+#         serverRef: mcp/browser
+#         tool: navigate
+items: []

package/dist/config/stores.yaml

@@ -0,0 +1,19 @@
+# agent-harness feature: schema version for reusable persistence presets.
+apiVersion: agent-harness/v1alpha1
+items:
+  # agent-harness feature: reusable store preset for agent backends that need a durable key-value store.
+  - kind: Store
+    metadata:
+      name: default
+      description: Default file-backed store preset for runtime-managed agent state.
+    spec:
+      storeKind: FileStore
+      path: store.json
+
+  # agent-harness feature: reusable checkpointer preset for resumable execution state.
+  - kind: Checkpointer
+    metadata:
+      name: default
+      description: Default in-memory checkpointer preset for lightweight local development.
+    spec:
+      checkpointerKind: MemorySaver

package/dist/config/tools.yaml

@@ -0,0 +1,13 @@
+# agent-harness feature: schema version for reusable tool objects.
+apiVersion: agent-harness/v1alpha1
+# This first-layer catalog is the default place to register reusable Tool objects that agents can reference.
+# Examples:
+# items:
+#   - kind: Tool
+#     metadata:
+#       name: repo_search
+#       description: Workspace-local repo search tool.
+#     spec:
+#       backend:
+#         operation: repo_search
+items: []

package/dist/config/workspace.yaml

@@ -23,21 +23,22 @@ spec:
   runRoot: ./.agent
 
   # agent-harness feature: optional host-router prompt override used when the runtime chooses between
-  # top-level host agents such as a main DeepAgent host and an optional low-latency side host.
+  # top-level host agents such as a main execution host and an optional low-latency side host.
   # Use placeholders so the same prompt can survive host renames:
   # - {{primaryAgentId}}
   # - {{primaryDescription}}
   # - {{secondaryAgentId}}
   # - {{secondaryDescription}}
   routing:
-    # agent-harness feature: DeepAgents-first default host selected when no explicit routing rule matches.
-    # Best practice is to point this at the main DeepAgent entry host and treat lighter agents as explicit opt-in.
+    # agent-harness feature: default host selected when no explicit routing rule matches.
+    # Best practice is to point this at the main execution host and treat lighter agents as explicit opt-in.
     defaultAgentId: orchestra
     # agent-harness feature: optional model-driven host classification fallback.
     # Keep this disabled unless you specifically need host-level model selection.
     modelRouting: false
     # agent-harness feature: ordered host-routing rules evaluated before model-driven classification.
-    # These rules only choose which host profile starts the run; DeepAgents still owns planning, tools, and long-running execution.
+    # These rules only choose which host profile starts the run; the selected backend still owns
+    # planning, tools, and long-running execution behavior after routing picks a host.
     # The first matching rule wins. Use this when you want stable routing behavior in YAML instead of code.
     #
     # Supported match fields on each rule:

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,6 +191,7 @@ export type CompiledAgentBinding = {
         runRoot: string;
         workspaceRoot?: string;
         hostFacing: boolean;
+        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[];
 };

package/dist/extensions.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { defaultResourceSkillsRoot } from "./resource/resource.js";
 import { isExternalSourceLocator, resolveExternalResourcePath } from "./resource/sources.js";
+import { hasAgentSystemPrompt } from "./workspace/support/agent-capabilities.js";
 const toolKindAdapters = new Map();
 const skillSourceResolvers = new Map();
 const skillInheritancePolicies = new Map();
@@ -231,9 +232,7 @@ registerSkillSourceResolver({
 registerSkillInheritancePolicy({
     kind: "default",
     apply({ agent, ownSkills, parentSkills }) {
-        const systemPrompt = agent.deepAgentConfig?.systemPrompt;
-        const hasSystemPrompt = typeof systemPrompt === "string" && systemPrompt.trim().length > 0;
-        if (hasSystemPrompt && agent.id.includes(".")) {
+        if (hasAgentSystemPrompt(agent) && agent.id.includes(".")) {
             return ownSkills;
         }
         return Array.from(new Set([...parentSkills, ...ownSkills]));

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.41";
+export declare const AGENT_HARNESS_VERSION = "0.0.43";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.41";
+export const AGENT_HARNESS_VERSION = "0.0.43";

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/presentation.d.ts

@@ -1,4 +1,18 @@
 export declare function escapeHtml(value: string): string;
+/** CSS class for anchors that should open in the host app embedded browser (Wallee). */
+export declare const WALLEE_OUTPUT_LINK_CLASS = "wallee-output-link";
+/** `data-wallee-url` — target URL for the embedded browser (http/https only). */
+export declare const WALLEE_BROWSER_URL_ATTR = "data-wallee-url";
+export declare function isAllowedWalleeBrowserUrl(url: string): boolean;
+/**
+ * Escape plain text and wrap http(s) URLs in Wallee output anchors (open in host embedded browser).
+ */
+export declare function linkifyPlainTextForWalleeBrowser(text: string): string;
+/**
+ * Like {@link markdownToHtml} but inline http(s) URLs and markdown links `[label](https://…)` render as
+ * Wallee embedded-browser anchors (`wallee-output-link` + `data-wallee-url`).
+ */
+export declare function markdownToWalleeOutputHtml(markdown: string): string;
 export declare function markdownToHtml(markdown: string): string;
 export declare function markdownToConsole(markdown: string): string;
 export declare function renderTemplate(data: Record<string, unknown>, template: string): string;