@botbotgo/agent-harness 0.0.37 → 0.0.39

package/README.md

@@ -2,33 +2,31 @@
 
 ## Product Overview
 
-`@botbotgo/agent-harness` helps developers build complex agent-based applications fast and keep them easy to maintain.
+`@botbotgo/agent-harness` solves the gap between an agent execution engine and a real multi-agent application runtime.
 
-It helps developers:
+The problem:
 
-- define agents in YAML
-- keep workspace behavior in `config/workspace.yaml`
-- keep shared bootstrap context in `config/agent-context.md`
-- discover tools and SKILL packages from `resources/`
-- bridge remote MCP servers into agent toolsets
-- expose harness-managed tools as an MCP server
-- run through either LangChain v1 or DeepAgents with one app-facing API
+- 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
 
-Why it works:
+What this package provides:
 
-- it helps developers move from idea to working complex agent application with less setup friction
-- it makes ongoing maintenance lighter, including maintenance flows that can be automated by the application itself
-- one workspace becomes the source of truth for agent topology, models, tools, and operating context
-- one API covers direct agents and orchestration flows
-- local resources stay portable and versionable
-- thread state, approvals, resumability, and maintenance are built in
+- 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
 
 Core API:
 
 - `createAgentHarness(...)`
 - `run(...)`
 - `subscribe(...)`
+- `listThreads(...)`
 - `getThread(...)`
+- `listApprovals(...)`
+- `getApproval(...)`
 - `stop(...)`
 
 ## Quick Start
@@ -39,7 +37,7 @@ Install the package:
 npm install @botbotgo/agent-harness
 ```
 
-Create a workspace:
+Workspace layout:
 
 ```text
 your-workspace/
@@ -56,109 +54,83 @@ your-workspace/
     skills/
 ```
 
-Use the standard layout only. Agent entry files must live under `config/agents/`; root-level files such as `agent.yaml`, `orchestra.yaml`, and `direct.yaml` are not loaded.
+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 harness = await createAgentHarness("/absolute/path/to/your-workspace");
+const runtime = await createAgentHarness("/absolute/path/to/your-workspace");
 
 try {
-  const result = await run(harness, {
-    agentId: "direct",
+  const result = await run(runtime, {
+    agentId: "auto",
     input: "Summarize what this workspace is for.",
   });
 
   console.log(result.output);
 } finally {
-  await stop(harness);
+  await stop(runtime);
 }
 ```
 
 ## Feature List
 
-- One workspace for agents, models, tools, and runtime behavior
-- One API for both LangChain v1 and DeepAgents
-- Built-in routing for direct and orchestration flows
+- 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: agent YAML can mount remote or local MCP servers as agent tools
-- MCP server support: expose harness-managed tools over stdio or an in-memory MCP server
-- Built-in thread state, approvals, resumable runs, and long-term memory
-- MCP server helpers plus background checkpoint maintenance
+- 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
+- Background checkpoint maintenance
 
 ## How To Use
 
-### Create A Harness
-
-Pass a workspace root:
+### Create A Runtime
 
 ```ts
-import { createAgentHarness } from "@botbotgo/agent-harness";
+import { AgentHarnessRuntime, createAgentHarness } from "@botbotgo/agent-harness";
 
-const harness = await createAgentHarness("/absolute/path/to/workspace");
+const runtime: AgentHarnessRuntime = await createAgentHarness("/absolute/path/to/workspace");
 ```
 
-Or pass a prebuilt `WorkspaceBundle`:
+Or:
 
 ```ts
-const harness = await createAgentHarness(workspaceBundle);
+const runtime = 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
+`createAgentHarness(workspaceRoot)` loads one `WorkspaceBundle`, resolves `resources/`, initializes persistence under `runRoot`, and starts runtime maintenance.
 
 ### Run A Request
 
 ```ts
 import { run } from "@botbotgo/agent-harness";
 
-const result = await run(harness, {
-  agentId: "direct",
+const result = await run(runtime, {
+  agentId: "orchestra",
   input: "Explain the available agents in this workspace.",
 });
 ```
 
-The result includes:
-
-- `threadId`
-- `runId`
-- `state`
-- `output`
-
-Runtime behavior:
+Each run creates or continues a persisted thread. The result includes `threadId`, `runId`, `state`, and `output`.
 
-- 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:
+### Let The Runtime Route
 
 ```ts
-const result = await run(harness, {
+const result = await run(runtime, {
   agentId: "auto",
   input: "Inspect this repository and explain the release flow.",
 });
 ```
 
-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
+`agentId: "auto"` evaluates ordered `routing.rules` first, then falls back to `routing.defaultAgentId`, and only uses model routing when `routing.modelRouting: true`.
 
 ### Stream Output And Events
 
 ```ts
-const result = await run(harness, {
+const result = await run(runtime, {
   agentId: "orchestra",
   input: "Inspect the workspace and explain the available tools.",
   listeners: {
@@ -172,12 +144,30 @@ const result = await run(harness, {
 });
 ```
 
+The runtime emits typed lifecycle events for output, state changes, approvals, and delegations. `subscribe(...)` is a read-only observer surface.
+
+### Query Threads And Approvals
+
+```ts
+import {
+  getApproval,
+  getThread,
+  listApprovals,
+  listThreads,
+} 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;
+```
+
+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.
 
-Point agent YAML at both:
-
 ```yaml
 spec:
   skills:
@@ -186,17 +176,10 @@ 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
+Tool modules are discovered from `resources/tools/*.js`, `resources/tools/*.mjs`, and `resources/tools/*.cjs`. The preferred format is exporting `tool({...})`.
 
 ### Bridge MCP Servers Into Agents
 
-Use `mcpServers:` inside agent YAML to bridge MCP servers into the agent's tool list:
-
 ```yaml
 spec:
   mcpServers:
@@ -209,82 +192,52 @@ spec:
       token: ${DOCS_MCP_TOKEN}
 ```
 
-The harness discovers MCP tools, filters them through the agent config, and exposes them to the runtime like any other tool.
+The runtime discovers MCP tools, filters them through agent config, and exposes them like any other tool.
 
-### Expose Harness Tools As An MCP Server
-
-Use the MCP server helpers when another client should connect to the harness as an MCP server:
+### Expose Runtime Tools As An MCP Server
 
 ```ts
 import { createToolMcpServer, serveToolsOverStdio } from "@botbotgo/agent-harness";
 
-const server = await createToolMcpServer(harness, { agentId: "orchestra" });
-await serveToolsOverStdio(harness, { agentId: "orchestra" });
+const server = await createToolMcpServer(runtime, { agentId: "orchestra" });
+await serveToolsOverStdio(runtime, { agentId: "orchestra" });
 ```
 
-If you omit `serverInfo`, the harness uses `agent-harness-<agentId>` as the MCP server name and the current package version as the server version.
-
-### Read Back Thread State
-
-```ts
-import { getThread } from "@botbotgo/agent-harness";
-
-const thread = await getThread(harness, result.threadId);
-console.log(thread?.messages.at(-1)?.content);
-```
-
-### Subscribe To Global Events
-
-```ts
-import { subscribe } from "@botbotgo/agent-harness";
-
-const unsubscribe = subscribe(harness, (event) => {
-  console.log(event.threadId, event.runId, event.eventType);
-});
-```
-
-### Stop The Harness
+### Stop The Runtime
 
 ```ts
 import { stop } from "@botbotgo/agent-harness";
 
-await stop(harness);
+await stop(runtime);
 ```
 
 ## How To Configure
 
 Core workspace files:
 
-- `config/workspace.yaml`: workspace-wide defaults such as `runRoot`, routing, and maintenance
+- `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`: lightweight host agent
-- `config/agents/orchestra.yaml`: default orchestration host agent
+- `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`
 
-Use this file for workspace-wide behavior such as:
+Use this file for:
 
 - `runRoot`
-- routing via `routing.systemPrompt`
-- background checkpoint maintenance via `maintenance.checkpoints.*`
-
-Implementation details:
+- ordered `routing.rules`
+- `routing.systemPrompt`
+- `maintenance.checkpoints.*`
 
-- 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
+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.
-
-If a runnable app workspace also includes `AGENTS.md`, treat that file as workspace-level operating guidance. It complements `config/agents/*.yaml`: `AGENTS.md` carries durable behavioral rules, while `config/agents/` defines agent topology and runtime configuration.
+Use this file for shared bootstrap context that agents read at construction time. Put stable project context here, not long-term mutable memory.
 
 ### Agent YAML
 
@@ -307,21 +260,10 @@ Use `resources/` for executable extensions:
 - `resources/tools/` for local tool modules
 - `resources/skills/` for SKILL packages
 
-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
+Keep runtime extension source under `resources/`. Keep tests outside the published source tree, for example under the repository `test/` folder.
 
 ### 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
+- 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

package/dist/api.d.ts

@@ -1,17 +1,20 @@
-import type { AgentHarnessHandle, RunOptions, RuntimeAdapterOptions, ThreadRecord, WorkspaceLoadOptions, WorkspaceBundle } from "./contracts/types.js";
-import { AgentHarness } from "./runtime/harness.js";
+import type { ApprovalRecord, RunOptions, RuntimeAdapterOptions, ThreadSummary, ThreadRecord, WorkspaceLoadOptions, WorkspaceBundle } from "./contracts/types.js";
+import { AgentHarnessRuntime } from "./runtime/harness.js";
 import type { ToolMcpServerOptions } from "./mcp.js";
+export { AgentHarnessRuntime } from "./runtime/harness.js";
 type CreateAgentHarnessOptions = {
     load?: WorkspaceLoadOptions;
     adapter?: RuntimeAdapterOptions;
 };
-export declare function createAgentHarness(): Promise<AgentHarnessHandle>;
-export declare function createAgentHarness(workspaceRoot: string, options?: CreateAgentHarnessOptions): Promise<AgentHarnessHandle>;
-export declare function createAgentHarness(workspace: WorkspaceBundle, options?: CreateAgentHarnessOptions): Promise<AgentHarnessHandle>;
-export declare function run(harness: AgentHarnessHandle, options: RunOptions): Promise<import("./contracts/types.js").RunResult>;
-export declare function subscribe(harness: AgentHarnessHandle, listener: Parameters<AgentHarness["subscribe"]>[0]): () => void;
-export declare function getThread(harness: AgentHarnessHandle, threadId: string): Promise<ThreadRecord | null>;
-export declare function stop(harness: AgentHarnessHandle): Promise<void>;
-export declare function createToolMcpServer(harness: AgentHarnessHandle, options: ToolMcpServerOptions): Promise<import("@modelcontextprotocol/sdk/server/mcp.js").McpServer>;
-export declare function serveToolsOverStdio(harness: AgentHarnessHandle, options: ToolMcpServerOptions): Promise<import("@modelcontextprotocol/sdk/server/mcp.js").McpServer>;
-export {};
+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[]>;
+export declare function getThread(runtime: AgentHarnessRuntime, threadId: string): Promise<ThreadRecord | null>;
+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 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,54 +1,38 @@
-import { AgentHarness } from "./runtime/harness.js";
-import { createToolMcpServerFromHarness, serveToolsOverStdioFromHarness } from "./mcp.js";
+import { AgentHarnessRuntime } from "./runtime/harness.js";
 import { loadWorkspace } from "./workspace/compile.js";
-const HARNESS_INSTANCE = Symbol.for("@botbotgo/agent-harness/instance");
-function registerHarness(harness) {
-    const handle = { kind: "AgentHarnessHandle" };
-    Object.defineProperty(handle, HARNESS_INSTANCE, {
-        value: harness,
-        enumerable: false,
-        configurable: false,
-        writable: false,
-    });
-    return Object.freeze(handle);
-}
-function requireHarness(handle) {
-    if (handle instanceof AgentHarness) {
-        return handle;
-    }
-    if (typeof handle === "object" && handle !== null && "run" in handle && "subscribe" in handle && "close" in handle) {
-        return handle;
-    }
-    const harness = handle[HARNESS_INSTANCE];
-    if (!harness) {
-        throw new Error("Unknown or stopped AgentHarnessHandle");
-    }
-    return harness;
-}
+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;
-    const harness = new AgentHarness(workspace, options.adapter ?? {});
+    const harness = new AgentHarnessRuntime(workspace, options.adapter ?? {});
     await harness.initialize();
-    return registerHarness(harness);
+    return harness;
+}
+export async function run(runtime, options) {
+    return runtime.run(options);
+}
+export function subscribe(runtime, listener) {
+    return runtime.subscribe(listener);
+}
+export async function listThreads(runtime, filter) {
+    return runtime.listThreads(filter);
 }
-export async function run(harness, options) {
-    return requireHarness(harness).run(options);
+export async function getThread(runtime, threadId) {
+    return runtime.getThread(threadId);
 }
-export function subscribe(harness, listener) {
-    return requireHarness(harness).subscribe(listener);
+export async function listApprovals(runtime, filter) {
+    return runtime.listApprovals(filter);
 }
-export async function getThread(harness, threadId) {
-    return requireHarness(harness).getThread(threadId);
+export async function getApproval(runtime, approvalId) {
+    return runtime.getApproval(approvalId);
 }
-export async function stop(harness) {
-    const instance = requireHarness(harness);
-    return instance.close();
+export async function stop(runtime) {
+    return runtime.stop();
 }
-export async function createToolMcpServer(harness, options) {
-    return createToolMcpServerFromHarness(requireHarness(harness), options);
+export async function createToolMcpServer(runtime, options) {
+    return runtime.createToolMcpServer(options);
 }
-export async function serveToolsOverStdio(harness, options) {
-    return serveToolsOverStdioFromHarness(requireHarness(harness), options);
+export async function serveToolsOverStdio(runtime, options) {
+    return runtime.serveToolsOverStdio(options);
 }

package/dist/config/embedding-model.yaml

@@ -25,5 +25,5 @@ spec:
   # ======================
   # agent-harness Features
   # ======================
-  # This object is packaged and referenced through retrieval-oriented builtin tools such as `builtin.build_rag_index`
-  # and `builtin.query_rag_index`, not through `agent.modelRef`.
+  # This object is packaged and referenced through retrieval-oriented workspace tools such as the RAG index builder
+  # and query tool, not through `agent.modelRef`.

package/dist/config/workspace.yaml

@@ -22,14 +22,48 @@ spec:
   # Value options: relative workspace path like `./.agent`, or an absolute filesystem path.
   runRoot: ./.agent
 
-  # agent-harness feature: optional host-router prompt override used when the framework chooses between
-  # top-level host agents such as `direct` and `orchestra`.
+  # 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.
   # 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.
+    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.
+    # The first matching rule wins. Use this when you want stable routing behavior in YAML instead of code.
+    #
+    # Supported match fields on each rule:
+    # - `equals`: exact request text match (string or list)
+    # - `startsWith`: request prefix match (string or list)
+    # - `contains`: substring match (string or list)
+    # - `regex`: regular-expression match (string or list)
+    # - `minLength` / `maxLength`: request text length bounds
+    # - `minLines` / `maxLines`: request line-count bounds
+    # - `hasThreadId`: require a new turn (`false`) or existing thread follow-up (`true`)
+    # - `caseSensitive`: default `false`
+    #
+    # Example:
+    # rules:
+    #   - agentId: research-lite
+    #     contains: ["latest", "today", "news", "最近", "最新", "新闻"]
+    #   - agentId: orchestra
+    #     regex:
+    #       - "\\b(create|build|implement|fix|review|debug|inspect|analy[sz]e|download|clone)\\b"
+    rules:
+      - agentId: research-lite
+        contains: ["latest", "recent", "today", "current", "news", "最新", "最近", "今天", "当前", "新闻", "头条", "研究", "调研"]
+      - agentId: orchestra
+        regex:
+          - "\\b(create|build|implement|fix|debug|refactor|review|test|ship|release|deploy|code|bug|repo|repository|file|files|download|clone|inspect|analy[sz]e|explore)\\b"
+          - "(写代码|实现|修复|排查|调试|重构|评审|测试|发布|部署|仓库|代码|文件|下载|克隆|分析|检查|探索)"
     systemPrompt: |-
       You are a routing classifier for an agent harness. Reply with exactly one agent id:
       {{primaryAgentId}} or {{secondaryAgentId}}.
@@ -47,7 +81,7 @@ spec:
       When uncertain, prefer {{secondaryAgentId}}.
 
   # agent-harness feature: optional workspace-level background maintenance policies.
-  # This is the framework-owned place to configure periodic housekeeping that should run without
+  # This is the runtime-owned place to configure periodic housekeeping that should run without
   # coupling cleanup to user-triggered checkpoint reads or writes.
   #
   # Current support:

package/dist/contracts/types.d.ts

@@ -183,7 +183,6 @@ export type CompiledAgentBinding = {
 export type WorkspaceBundle = {
     workspaceRoot: string;
     resourceSources: string[];
-    builtinSources?: string[];
     refs: Map<string, WorkspaceObject | ParsedAgentObject>;
     models: Map<string, ParsedModelObject>;
     embeddings: Map<string, ParsedEmbeddingModelObject>;
@@ -196,7 +195,6 @@ export type WorkspaceBundle = {
 export type WorkspaceLoadOptions = {
     overlayRoots?: string[];
     resourceSources?: string[];
-    builtinSources?: string[];
 };
 export type ThreadSummary = {
     agentId: string;
@@ -207,9 +205,11 @@ export type ThreadSummary = {
     status: RunState;
 };
 export type SessionRecord = ThreadSummary;
+export type KnownHarnessEventType = "run.created" | "run.state.changed" | "run.resumed" | "approval.requested" | "approval.resolved" | "artifact.created" | "output.delta" | "reasoning.delta" | "runtime.synthetic_fallback";
+export type HarnessEventType = KnownHarnessEventType | (string & {});
 export type HarnessEvent = {
     eventId: string;
-    eventType: string;
+    eventType: HarnessEventType;
     timestamp: string;
     threadId: string;
     runId: string;
@@ -217,6 +217,17 @@ export type HarnessEvent = {
     source: "runtime" | "policy" | "surface" | "worker";
     payload: Record<string, unknown>;
 };
+export type HarnessEventListener = (event: HarnessEvent) => void | Promise<void>;
+export type HarnessEventProjection = {
+    name?: string;
+    shouldHandle?: (event: HarnessEvent) => boolean;
+    handleEvent: HarnessEventListener;
+};
+export type RuntimeEventSink = {
+    publish: (event: HarnessEvent) => void;
+    subscribe: (listener: HarnessEventListener) => () => void;
+    registerProjection: (projection: HarnessEventProjection) => () => void;
+};
 export type RunResult = {
     threadId: string;
     runId: string;
@@ -236,6 +247,7 @@ export type RunListeners = {
     onToolResult?: (item: {
         toolName: string;
         output: unknown;
+        isError?: boolean;
     }) => void | Promise<void>;
 };
 export type MessageContentPart = {
@@ -289,6 +301,7 @@ export type HarnessStreamItem = {
     agentId: string;
     toolName: string;
     output: unknown;
+    isError?: boolean;
 };
 export type TranscriptMessage = {
     role: "user" | "assistant";
@@ -438,8 +451,5 @@ export type PolicyEvaluator = {
 };
 export type EventSubscriber = {
     kind: string;
-    onEvent: (event: HarnessEvent) => void | Promise<void>;
-};
-export type AgentHarnessHandle = {
-    readonly kind: "AgentHarnessHandle";
+    onEvent: HarnessEventListener;
 };

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { createAgentHarness, createToolMcpServer, getThread, run, serveToolsOverStdio, subscribe, stop } from "./api.js";
+export { AgentHarnessRuntime, createAgentHarness, createToolMcpServer, getApproval, getThread, listApprovals, listThreads, 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 { createAgentHarness, createToolMcpServer, getThread, run, serveToolsOverStdio, subscribe, stop } from "./api.js";
+export { AgentHarnessRuntime, createAgentHarness, createToolMcpServer, getApproval, getThread, listApprovals, listThreads, run, serveToolsOverStdio, subscribe, stop, } from "./api.js";
 export { tool } from "./tools.js";

package/dist/mcp.d.ts

@@ -1,5 +1,5 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import type { AgentHarness } from "./runtime/harness.js";
+import type { CompiledTool, ParsedToolObject } from "./contracts/types.js";
 export type ToolMcpServerOptions = {
     agentId: string;
     serverInfo?: {
@@ -8,5 +8,10 @@ export type ToolMcpServerOptions = {
     };
     includeToolNames?: string[];
 };
-export declare function createToolMcpServerFromHarness(harness: AgentHarness, options: ToolMcpServerOptions): Promise<McpServer>;
-export declare function serveToolsOverStdioFromHarness(harness: AgentHarness, options: ToolMcpServerOptions): Promise<McpServer>;
+export type ToolMcpServerTool = {
+    compiledTool: CompiledTool;
+    resolvedTool: unknown;
+    sourceTool?: ParsedToolObject;
+};
+export declare function createToolMcpServerFromTools(tools: ToolMcpServerTool[], options: ToolMcpServerOptions): Promise<McpServer>;
+export declare function serveToolsOverStdioFromHarness(tools: ToolMcpServerTool[], options: ToolMcpServerOptions): Promise<McpServer>;