@botbotgo/agent-harness 0.0.474 → 0.0.476

package/README.md

@@ -1,1246 +1,15 @@
-<p align="center">
-  <img
-    src="https://agent-harness.easynet.world/assets/readme-banner.png"
-    alt="botbotgo runtime banner"
-    width="1100"
-    height="495"
-  />
-</p>
-
-<p align="center">
-  <strong>English</strong> · <a href="./README.zh.md">中文</a>
-</p>
-
 # @botbotgo/agent-harness
 
-<p align="center">
-  <strong>Build enterprise-grade multi-agent runtimes that are ready to launch and ready to operate.</strong>
-</p>
-
-<p align="center">
-  <strong>Ship quickly: one workspace assembles into one production-ready product runtime.</strong>
-</p>
-
-<p align="center">
-  <a href="https://agent-harness.easynet.world/">Product website</a>
-  (static page in <code>docs/</code>, self-hosted docs site; EN / 中文 toggle)
-</p>
-
-<p align="center">
-  <a href="https://agent-harness.easynet.world/development/">Developer docs</a>
-  (<code>docs/development/</code>, English / 中文)
-</p>
-
-<p align="center">
-  <a href="./LICENSE">License</a> · <a href="./CONTRIBUTING.md">Contributing</a> ·
-  <a href="./SECURITY.md">Security</a> · <a href="./CODE_OF_CONDUCT.md">Code of Conduct</a>
-  · <a href="https://github.com/sponsors/botbotgo">Sponsorship</a>
-</p>
-
-<p align="center">
-  <em
-    >For AI solutions and help shipping a product idea, contact
-    <a href="mailto:info@easynet.world">info@easynet.world</a>.</em
-  >
-</p>
-
-<a id="readme-en-start"></a>
-
-## Start in a few lines
-
-You can boot an agent runtime in a few lines of code:
-
-```ts
-import { createAgentHarness, request, stop } from "@botbotgo/agent-harness";
-
-const runtime = await createAgentHarness("/absolute/path/to/workspace");
-
-try {
-  const result = await request(runtime, {
-    agentId: "auto",
-    input: "Explain what this workspace is for.",
-  });
-
-  console.log(result.output);
-} finally {
-  await stop(runtime);
-}
-```
-
-The goal is an **operable** runtime: approvals, recovery, inspection, and governance—ready for production operations.
-`agent-harness` adds the product runtime layer around your existing agents, tools, and workflows without forcing a
-rewrite of the execution stack behind them.
-
-The repository default also ships a starter runtime, not an empty shell:
-
-- one default host agent: `orchestra`
-- a workspace-local `resources/tools/` path for runtime-owned tools such as file inspection, runtime inspection, approvals, and schedules
-- no preloaded bootstrap memory or behavior skills on the default host, so first-run local chat stays responsive; add `memory:` files and `skills:` refs when your runtime really needs them
-
-If you want the fastest first-run demo, start the chat shell and try one of these:
-
-```bash
-botbotgo
-# or
-botbotgo "Inspect this workspace and explain the main entry points."
-# or
-agent-harness "Inspect this workspace and explain the main entry points."
-```
-
-- `Inspect this workspace and explain the main entry points.`
-- `Review this project structure before making any edits.`
-- `Update README.md to make the setup steps clearer.`
-- `Find the likeliest config issue in this workspace and propose the smallest fix.`
-
-When the runtime emits request-scoped `plan-state` updates and safe `progress.commentary` deltas, the chat shell now renders live todo-board and progress status updates directly in the terminal, so you can watch planning and execution status change during the run instead of waiting for the final response.
-Those progress callouts now stay tied to stable runtime surfaces such as plan-state, tool start/completion, memory recall, and agent delegation, so the operator sees Codex-style intermediate status without exposing private model reasoning.
-Streaming data listeners also receive structured `plan.state`, per-item `plan.step`, and normalized `execution.step` events, so applications can render every planning and execution transition without parsing assistant text or raw upstream debug events.
-The bundled runtime now also provides a generic `response-format/default-report` structured-output default for agents; workspaces can replace it through `Runtime.spec.defaults.agent.config.responseFormatRef`, individual agents can extend it with inline `responseFormat`, replace it with `responseFormatRef`, or set `responseFormat: null`.
-The repository default `orchestra` host is also instructed to start real multi-step execution from the task you already gave it, call `write_todos` before non-trivial tool work, and keep that todo board updated while it runs.
-Durable-memory writes now also retrieve related existing records through the configured vector store before model reconciliation, then merge those semantic hits with deterministic matching so updates and deletes can target the right knowledge identity instead of creating nearby duplicate facts.
-
-<a id="readme-en-docs-path"></a>
-
-## Documentation Paths
-
-Choose an entry point that matches what you need:
-
-- **Technology:** capability comparison, runtime model, protocol surfaces, API, recovery, approvals, and operator control
-- **Product:** what the stable runtime surface already is, which product scenarios it fits, and why it is not another agent framework
-- **Commercial:** pricing, engagement process, and scoped services for deployment help, launch hardening, and team handoff
-
-Recommended entry points:
-
-- [Developer docs portal](./docs/development/index.html)
-- [Side-by-side comparison](./docs/development/comparison.html)
-- [API reference](./docs/development/api-reference.html)
-- [Protocol surfaces](./docs/development/protocol-surfaces.html)
-- [Release notes](./docs/development/release-notes.html) (English: `RELEASE_NOTES.md`; Chinese: [`zh/release-notes`](./docs/development/zh/release-notes.html) / `RELEASE_NOTES.zh.md`)
-- [Commercial service offerings](./docs/commercial-pricing.md)
-- [Topical docs index](./docs/README.md) (all `docs/*.md` in one table)
-
-### How to use this README
-
-This file is both a quickstart and a long reference—you do not need to read it top to bottom.
-
-| If you have… | Read this first | Then |
-| --- | --- | --- |
-| **~5 minutes** | [Start in a few lines](#readme-en-start) and [Documentation Paths](#readme-en-docs-path) | Open [Getting started](./docs/development/getting-started.html) in the developer docs. |
-| **First real integration** | [Quick Start](#readme-en-quickstart) → [How To Configure](#readme-en-config) | [Workspace and YAML](./docs/development/workspace-and-yaml.html) · [Topic index](./docs/README.md) · feature guides under [`docs/`](./docs/) |
-| **Operations / governance** | [Runtime capabilities at a glance](#readme-en-runtime-glance) → [Primary use cases](#readme-en-use-cases) | [Runtime operations](./docs/development/runtime-operations.html) and [`docs/tool-execution-policy.md`](./docs/tool-execution-policy.md). |
-| **API lookup** | Skip to [API Summary](#readme-en-api-summary) | Use it as a bookmarked index; the [API reference](./docs/development/api-reference.html) has fuller detail. |
-
-## Repository Source Layout
-
-When you work on the open-source package itself, treat `src/` as a layered tree instead of one flat folder:
-
-- top-level `src/*.ts` files should stay as stable public entrypoints or compatibility shims
-- public API implementation belongs under `src/public/`
-- protocol servers and transports belong under `src/protocol/**`
-- terminal, projection, and rendering helpers belong under `src/surface/` or `src/cli/`
-- scaffolding and bootstrap generation belong under `src/scaffold/`
-- extension and tool-definition machinery belong under `src/tooling/`
-- runtime internals stay under `src/runtime/`, persistence under `src/persistence/`, and workspace assembly under `src/workspace/`
-
-For new code, prefer the domain folder first. Only add a new top-level `src/*.ts` file when it is intentionally part of the package entry surface.
-
-## License & Commercial Support
-
-This project is licensed under **Apache License 2.0**.
-[LICENSE](./LICENSE)
-
-Core runtime is open source: inspect and run it freely.
-Commercial support focuses on helping teams reach a production-ready handoff, including:
-
-- Deployment and integration guidance for your environment
-- Initial deployment setup and launch assistance
-- Priority issue triage and troubleshooting
-- Runtime governance, approval flow, and recovery hardening support
-- Custom tools, connectors, and protocol integrations
-- Operator runbooks and handoff guidance for your team
-
-Production operations, managed hosting, on-call coverage, and long-term run-the-system support are not included by default.
-If a team wants us to take on that responsibility, we scope it separately based on environment complexity and SLA expectations.
-
-If your team needs a scalable enterprise setup, please contact:
-**[info@easynet.world](mailto:info@easynet.world)**.
-
-Additional docs:
-
-- [Commercial service offerings](./docs/commercial-pricing.md)
-- [Commercial engagement process](./docs/enterprise-process.md)
-
-## Easy to start · Full runtime · Configure and extend
-
-**At a glance:** onboarding stays thin, the runtime ships as a full layer, and day-to-day work lives in **YAML** plus **extensions** (local tools, SKILL packages, MCP)—not bespoke runtime plumbing.
-
-- **Easy to start:** `createAgentHarness` → `request` → `stop`, plus inspection helpers such as `subscribe`, `listSessions`, `listApprovals`, and `resolveApproval`.
-- **Reusable client surface:** `createAgentHarnessClient` / `createInProcessHarnessClient` bind the same runtime-owned request, session, approval, and event APIs into one frontend-facing client contract that terminal shells, desktop apps, and other embedded UIs can share.
-- **ACP client path for out-of-process UIs:** `createAcpHarnessClient`, `createAcpStdioHarnessClient`, and `createAcpHttpHarnessClient` let a UI consume the same `HarnessClient` contract over ACP when the UI and runtime live in different processes, while keeping `request(...)` as the one request entrypoint for streamed state snapshots plus delta data.
-- **Configure:** routing, models, tools, stores, backends, MCP, recovery, and maintenance in declarative workspace YAML (see [Quick Start](#readme-en-quickstart) and [How To Configure](#readme-en-config)).
-- **Extend:** drop `tool({...})` modules and SKILL trees under `resources/`, wire shared tools and MCP in catalogs, and let agents whitelist what they use.
-- **Built into the runtime:** persisted `requests`, `sessions`, `approvals`, and `events`; recovery and queueing; streaming listeners; MCP in/out; and backend adapters—so you do not rebuild that layer per app.
-
-<a id="readme-en-runtime-glance"></a>
-
-## Runtime capabilities at a glance
-
-The public API spans a full product runtime—persistent records, memory and evidence, protocol surfaces, and governance—not only a thin bootstrap around YAML and tools.
-
-- **Core runtime API:** `createAgentHarness`, `request`, `subscribe`, `resolveApproval`, `recordArtifact`, inspection helpers, and stable persisted runtime records for `requests`, `sessions`, `approvals`, `events`, and artifacts.
-- **Frontend/client entrypoints:** `createAgentHarnessClient`, `createInProcessHarnessClient`, `createAcpHarnessClient`, `createAcpStdioHarnessClient`, `createAcpHttpHarnessClient`, and `HarnessClient` let product shells consume the runtime through one reusable client layer instead of re-binding runtime calls per UI. `request(...)` is the streamed request entrypoint; `subscribe(...)` is the runtime lifecycle observer surface.
-- **Runtime memory and evidence:** `memorize`, `recall`, `listMemories`, memory policy hooks, `recordArtifact`, `listArtifacts`, `getArtifact`, `exportEvaluationBundle`, `replayEvaluationBundle`, and request/session evidence export helpers.
-- **Protocol and transport surfaces:** `createAcpServer`, `createAcpStdioClient`, `serveAcpStdio`, `serveAcpHttp`, `serveA2aHttp`, `serveAgUiHttp`, and `createRuntimeMcpServer` / `serveRuntimeMcpOverStdio`.
-- **Governed workspace runtime:** YAML-owned routing, concurrency, maintenance, MCP policy, runtime governance bundles, and approval defaults for sensitive memory or MCP tools with declared write access.
-- **Policy-shaped approvals:** governed tools can stay on manual review, auto-approve, or auto-reject / deny-and-continue modes while the runtime keeps one inspectable governance decision surface.
-
-If you integrate external clients, treat `deepagents-acp` as the primary protocol direction: clients connect through that surface while `agent-harness` keeps persistence, recovery, approvals, and operator control on the runtime side.
-Keep the standard stack split explicit: MCP connects agents to resources and tools, A2A bridges task exchange between agent platforms, ACP is the client-to-runtime boundary, AG-UI is the UI event surface, and runtime MCP exposes the operator control plane.
-
-## The problem this solves
-
-In one line: `agent-harness` productizes the runtime work that usually appears after the demo.
-
-If your team already has agents, prompts, tools, and workflows, the missing layer is usually not more execution. The missing layer is the runtime that makes those pieces operable, inspectable, and recoverable in production.
-
-What you get on day one:
-
-- a runtime that keeps `requests`, `sessions`, `approvals`, and `events` as inspectable product records
-- a recovery path that survives interruption, restart, and operator decisions
-- stable request correlation and continuity metadata so operators can join one persisted request to logs, traces, and fallback transitions
-- approval defaults for sensitive durable memory writes and MCP tools with declared write access instead of relying on tool names or descriptions to imply governance
-- one workspace-shaped assembly model instead of app-specific runtime glue
-- one stable runtime contract even when execution backends change underneath
-
-AI makes it much easier to generate agent logic, tool calls, and workflow code. The harder problem shifts to operations.
-
-Once the demo works, the real software problem changes shape:
-
-- more generated logic creates more execution paths to inspect, interrupt, retry, and recover
-- natural-language entrypoints turn approvals and policy boundaries into runtime requirements
-- backend, prompt, and tool changes happen faster, but product-facing behavior still needs one stable control surface
-- MCP and provider-native tooling expand what agents can reach, which raises the bar for governance
-
-Teams still need clear answers to the runtime questions that appear after that shift:
-
-- how approvals are resolved and audited
-- how requests, sessions, and events stay inspectable
-- how execution recovers after interruption, failure, or restart
-- how routing, concurrency, and maintenance policy stay consistent
-- how backend churn does not leak into the product model
-
-`agent-harness` solves that layer. It keeps agent execution upstream while turning the application runtime into something teams can operate, recover, and govern.
-
-In short:
-
-- you bring the workspace, agents, tools, and prompts
-- `agent-harness` brings persisted `requests`, `sessions`, `approvals`, `events`, recovery, and operator visibility
-- your application gets one stable runtime contract instead of backend-specific runtime plumbing
-
-In concrete terms:
-
-- a product-facing approval and operator surface instead of backend-specific middleware state
-- persisted `requests`, `sessions`, `approvals`, and `events` as stable runtime records
-- runtime-owned inspection fields such as tracing correlation ids and continuity metadata instead of provider-private observability handles
-- restart-safe recovery and continuation as system-managed behavior
-- default runtime governance for high-risk memory and MCP side effects
-- YAML-owned routing, concurrency, maintenance, and recovery policy
-- adapter isolation so backend replacement does not redefine the public runtime model
-
-## Product Overview
-
-`@botbotgo/agent-harness` is a workspace-shaped application runtime for real multi-agent products.
-
-It is not a new agent framework. It is the runtime layer around your existing execution stack that turns one workspace into one operable application runtime.
-
-The positioning is simple:
-
-- Codex, Claude Code, and Cursor are products for people using agents
-- execution frameworks define agent execution semantics
-- `agent-harness` is the runtime product layer for operating, recovering, approving, and governing multi-agent applications
-
-The product boundary is strict:
-
-- execution backends own agent execution semantics
-- application-level orchestration and lifecycle management stays in the harness
-
-That means:
-
-- public API stays small
-- complex setup and operating policy live in YAML
-- runtime lifecycle stays stable even if backend implementations change
-- backend internals stay behind adapters
-
-The runtime provides:
-
-- `createAgentHarness(workspaceRoot)`, `request(...)`, `memorize(...)`, `recall(...)`, `listMemories(...)`, `updateMemory(...)`, `removeMemory(...)`, `resolveApproval(...)`, `subscribe(...)`, inspection methods, and `stop(...)`
-- YAML-defined workspace assembly for routing, models, tools, stores, backends, MCP, recovery, and maintenance
-- backend-adapted execution behind the runtime contract
-- local `resources/tools/` `tool({...})` modules and `resources/skills/` discovery
-- persisted sessions, requests, approvals, events, queue state, and recovery metadata
-
-In practice, the harness exists for the parts that are expensive and repetitive to rebuild inside every agent app:
-
-- approval inboxes and human decision flow
-- persisted requests, sessions, and inspectable event history
-- request correlation, continuity, and recovery inspection that still works after a stream fallback or restart
-- runtime-managed recovery after interrupts, failures, or process restart
-- queueing, concurrency, maintenance, and operational policy
-- stable runtime records that stay usable even if the backend changes
-
-The default workspace configuration shipped with the package is deliberately full-shaped. The bundled YAML keeps explicit defaults for important runtime and agent knobs so teams can start from concrete configuration instead of reverse-engineering adapter behavior from source.
-
-The default rule is:
-
-- if the execution backend already has the feature, map it in YAML and adapt it internally
-- do not add a new public runtime API unless the problem is truly runtime-owned
-
-Start with these user-facing docs:
-
-- `docs/development/index.html`
-- `docs/development/getting-started.html`
-- `docs/development/comparison.html`
-- `docs/development/api-reference.html`
-- `docs/development/protocol-surfaces.html`
-- `docs/development/cookbook.html`
-- `docs/development/release-notes.html`
-- `docs/runtime-inspection-contract.md`
-- `docs/tool-execution-policy.md`
-- `docs/long-running-coding.md`
-- `docs/long-term-memory.md`
-- `docs/memory-policy-reference.md`
-
-Deeper design notes and boundary discussions ship alongside the package for advanced readers; everyday integration and operations rely on the README, developer docs, and topical references above.
-
-`deepagents-acp` is the required external protocol direction when external tools need a standard runtime boundary. The harness should conform to `deepagents-acp` semantics at that boundary while keeping runtime lifecycle, persistence, recovery, and governance harness-owned.
-
-Recommended orchestration shape for long-running flows:
-
-- let callers select the host agent explicitly whenever possible
-- use `backend: deepagent` when you want high-level execution semantics with minimal application wiring
-- keep `backend: langchain-v1` for lighter direct-response or explicitly chosen V1 agent shapes
-
-## What Makes It Different
-
-- It treats `requests`, `sessions`, `approvals`, `events`, and recovery as first-class product records
-- It gives operators a runtime control surface instead of exposing raw backend internals
-- It keeps observability and governance runtime-owned with trace correlation, continuity metadata, and approval defaults for sensitive side effects
-- It keeps checkpoint resume system-managed instead of promoting checkpoint internals into the primary API
-- It lets YAML own assembly and operating policy while code keeps a small, stable surface
-- It goes deep on runtime concerns that upstream libraries do not fully productize
-
-<a id="readme-en-use-cases"></a>
-
-## Primary use cases
-
-These scenarios map most directly to what the runtime is built for:
-
-- Enterprise internal agent runtime: approvals, restart-safe recovery, operator evidence, and policy-owned MCP access.
-- Code modernization runtime: long-running coding flows, approval checkpoints, resumable requests, and exported evidence packages.
-- Agent-ops and remediation workflow runtime: parallel agent attempts, human review gates, durable evidence, and operator visibility for security or maintenance work.
-- Protocol bridge runtime: ACP, A2A, AG-UI, and runtime MCP on one stable control plane instead of bespoke per-surface glue.
-
-Typical runtime governance defaults now look like:
-
-```yaml
-governance:
-  remoteMcp:
-    denyTrustTiers: ["untrusted"]
-    denyTenantScopes: ["cross-tenant"]
-    denyPromptInjectionRisks: ["high"]
-    requireApprovalTransports: ["websocket"]
-```
-
-## When To Use It
-
-Use `agent-harness` when:
-
-- you already know your product needs agents, tools, prompts, or MCP access, but the missing layer is runtime operations
-- you need approvals, restart recovery, queueing, or inspectable request records as part of the shipped product
-- you want one workspace-shaped assembly model instead of hand-written runtime bootstrapping in every app
-- you want to keep backend execution semantics upstream while holding the product contract stable
-
-Do not reach for it when:
-
-- you only need a single short-lived agent call with no approvals, no persistence, and no operational control surface
-- you are looking for a workflow builder or low-code automation canvas
-- you want to replace the execution backend's semantics rather than operate around them
-
-<a id="readme-en-quickstart"></a>
-
-## Quick Start
-
 Install:
 
 ```bash
 npm install @botbotgo/agent-harness
 ```
 
-If you want the CLI on your `PATH`, install it globally and run it from your own workspace root:
+Usage:
 
 ```bash
-npm install -g @botbotgo/agent-harness
-cd /path/to/your-workspace
-botbotgo
-botbotgo "Inspect this workspace and explain the main entry points."
-botbotgo -w /path/to/another-workspace "Summarize this project."
-```
-
-`botbotgo` treats the current directory as the workspace root. You can now run it from any folder: if `./config/` is absent, the CLI falls back to the bundled system defaults and bundled resources; if `./config/` or `./resources/` exists, the runtime overlays your workspace-defined config and resources on top of those defaults.
-
-Development tip: repository-owned Ollama workspaces now default to `http://127.0.0.1:11434` for release-friendly local behavior. During development, point them at a shared remote Ollama by exporting `AGENT_HARNESS_OLLAMA_BASE_URL=https://ollama-rtx-4070.easynet.world` or `AGENT_HARNESS_OPENAI_COMPATIBLE_BASE_URL=https://ollama-rtx-4070.easynet.world/v1` before starting the runtime.
-
-For CPU-only hosts with large RAM, run `llama.cpp` as an OpenAI-compatible server and use the existing `openai-compatible` provider:
-
-```yaml
-apiVersion: agent-harness/v1alpha1
-kind: Models
-spec:
-  - name: default
-    provider: openai-compatible
-    model: local-model
-    baseUrl: ${env:AGENT_HARNESS_LLAMA_CPP_BASE_URL:-http://127.0.0.1:8080/v1}
-    apiKey: dummy
-    toolCallingMode: prompted-json
-```
-
-Start the model separately with `llama-server -m /path/to/model.gguf --host 127.0.0.1 --port 8080`. `apiKey: dummy` uses the existing OpenAI-compatible auth-omission path, so the runtime does not send bearer auth to local `llama-server`.
-
-Workspace layout:
-
-```text
-your-workspace/
-  config/
-    models.yaml
-    agent-context.md
-    runtime/
-      workspace.yaml
-      runtime-memory.yaml
-    catalogs/
-      embedding-models.yaml
-      vector-stores.yaml
-      stores.yaml
-      backends.yaml
-      tools.yaml
-      mcp.yaml
-    agents/
-      direct.yaml
-      orchestra.yaml
-  resources/
-    package.json
-    tools/
-    skills/
-```
-
-Minimal usage:
-
-```ts
-import { createAgentHarness, request, stop } from "@botbotgo/agent-harness";
-
-const runtime = await createAgentHarness("/absolute/path/to/workspace");
-
-try {
-  const result = await request(runtime, {
-    agentId: "auto",
-    input: "Explain what this workspace is for.",
-  });
-
-  console.log(result.output);
-} finally {
-  await stop(runtime);
-}
-```
-
-Three-minute mental model:
-
-1. Point `createAgentHarness(...)` at a workspace root.
-2. Call `request(runtime, { ... })` to execute one request.
-3. Inspect persisted runtime records instead of treating the final answer as the only product artifact.
-
-In brief:
-
-- your team builds the agent app
-- `agent-harness` makes that app operable
-
-If you want the shortest possible mental model:
-
-- one workspace becomes one runtime
-- YAML defines assembly and policy
-- `request(runtime, { ... })` executes requests against that runtime
-- the runtime owns lifecycle, inspection, and recovery
-
-## Feature List
-
-- Workspace runtime for multi-agent applications
-- Small public runtime contract
-- YAML-defined host routing and runtime policy
-- Backend adaptation behind one runtime contract
-- Auto-discovered local `tool({...})` tools and SKILL packages
-- provider-native tools, MCP tools, and workspace-local tool modules
-- persisted sessions, requests, approvals, lifecycle events, and queued requests
-- runtime-managed recovery and checkpoint maintenance
-- structured output and multimodal content preservation in request results
-- MCP bridge support for agent-declared MCP servers
-- MCP server support for exposing harness tools outward
-- optional `mem0` semantic recall augmentation over canonical SQLite durable memory
-
-### Runtime Strengths
-
-- Stable product-facing API even when backend details evolve
-- Strong separation between public runtime contract and backend adapter contract
-- Clear YAML ownership for routing, topology, policy, and infrastructure objects
-- Better fit for long-running, approval-heavy, multi-agent products than a thin agent loop wrapper
-
-## How To Use
-
-### Create A Runtime
-
-```ts
-import { AgentHarnessRuntime, createAgentHarness } from "@botbotgo/agent-harness";
-
-const runtime: AgentHarnessRuntime = await createAgentHarness("/absolute/path/to/workspace");
-```
-
-`createAgentHarness(...)` loads the workspace, resolves workspace sources, initializes persistence under `runtimeRoot`, and starts runtime maintenance.
-
-`runtime.spec.sources` is the primary public discovery surface for local tools, package tools, and skill packages.
-
-```yaml
-apiVersion: agent-harness/v1alpha1
-kind: Runtime
-metadata:
-  name: default
-spec:
-  sources:
-    tools:
-      - file://./resources/tools
-      - file://../shared-tools
-      - npm://@acme/agent-tools
-    skills:
-      - file://./resources/skills
-      - npm://@acme/agent-skills
-      - https://example.com/skills/review/SKILL.md
-```
-
-Tool-source rules:
-
-- `file://...` scans only the configured folder
-- `npm://...` resolves one package, auto-installs it when missing, and discovers tools from `package/tools/`
-- tool discovery never traverses `node_modules/**`
-
-Skill-source rules:
-
-- `file://...` accepts a skill collection folder, a single skill root, or a direct `SKILL.md` path
-- `npm://...` resolves one package, auto-installs it when missing, and discovers skills from `package/skills/`
-- `http://...` and `https://...` currently accept a single remote `SKILL.md`
-
-`runtime.spec.resources` remains supported as a compatibility path for attached resource packages.
-
-`createAgentHarness(..., { load })` accepts workspace loading controls.
-
-Merge order is deterministic:
-
-- framework defaults
-- each `overlayRoots` entry in order
-- workspace root
-
-Later values always override earlier values. Arrays are replaced, while plain objects are deep-merged.
-
-```ts
-import { createAgentHarness } from "@botbotgo/agent-harness";
-
-const runtime = await createAgentHarness("/path/to/workspace", {
-  load: {
-    overlayRoots: ["/path/to/framework-defaults", "/path/to/product-overrides"],
-    frameworkContractValidation: "warn",
-  },
-});
-```
-
-Framework contract validation modes:
-
-- `off` keeps startup behavior unchanged
-- `warn` loads the workspace and emits contract-quality warnings for workspace-owned agents, skills, and tools
-- `error` fails startup when those workspace-owned definitions drift away from the framework contract
-
-You can also control the same startup behavior with `AGENT_HARNESS_FRAMEWORK_CONTRACT_VALIDATION=warn|error|off`.
-
-### Run A Request
-
-```ts
-import { request } from "@botbotgo/agent-harness";
-
-const result = await request(runtime, {
-  agentId: "orchestra",
-  input: "Summarize the runtime design.",
-  invocation: {
-    context: {
-      requestId: "req-123",
-    },
-    inputs: {
-      visitCount: 1,
-    },
-    attachments: {
-      "/tmp/spec.md": { content: "draft" },
-    },
-  },
-});
+botbotgo --help
 ```
 
-`request(runtime, { ... })` creates or continues a persisted session and returns `sessionId`, `requestId`, `state`, and compact text `output`. Richer upstream result shapes stay available through `outputContent`, `contentBlocks`, and `structuredResponse`.
-
-Use `listRequests(runtime)` and `getRequest(runtime, requestId)` when a product needs a request-centric operations surface such as a review queue or execution dashboard.
-
-Use `invocation` as the runtime-facing request envelope:
-
-- `invocation.context` for request-scoped execution context
-- `invocation.inputs` for structured runtime inputs
-- `invocation.attachments` for auxiliary invocation-scoped attachment payloads that the active backend can interpret
-
-For multimodal chat turns, keep the user-visible content in `input`.
-
-- if the product would show the image or text in the chat transcript, it belongs in `input`
-- if the payload is auxiliary request-scoped data rather than the chat turn itself, it belongs in `invocation.attachments`
-- persistence, replay, and transcript inspection should treat `input` as the source of truth for user-visible multimodal chat content
-
-```ts
-import { normalizeUserChatInput, request } from "@botbotgo/agent-harness";
-
-const result = await request(
-  runtime,
-  {
-    agentId: "orchestra",
-    ...normalizeUserChatInput({
-      role: "user",
-      content: [
-        { type: "text", text: "Describe the image and call out any risks." },
-        { type: "image_url", image_url: "data:image/png;base64,..." },
-      ],
-    }),
-  },
-);
-```
-
-Use `normalizeUserChatInput(...)` when a product already has chat-style user messages and wants to project one user turn onto the stable `request(..., { input, invocation })` surface without introducing a separate harness-owned chat API.
-
-### Store And Recall Durable Runtime Memory
-
-```ts
-import { memorize, recall } from "@botbotgo/agent-harness";
-
-await memorize(runtime, {
-  sessionId: "session-123",
-  records: [
-    {
-      content: "The release checklist requires a smoke test before publish.",
-      summary: "Run a smoke test before publish",
-      scope: "workspace",
-      kind: "procedural",
-      sourceRef: "docs/release-checklist.md",
-    },
-  ],
-});
-
-const recalled = await recall(runtime, {
-  query: "What does the release checklist require?",
-  scopes: ["workspace"],
-});
-```
-
-Use `memorize(...)`, `recall(...)`, `listMemories(...)`, `updateMemory(...)`, and `removeMemory(...)` when an application needs a stable public runtime memory surface without importing internal `runtime/harness/system/*` modules.
-
-- `memorize(...)` returns stable `MemoryRecord` and `MemoryDecision` results while leaving merge, review, archive, and storage layout runtime-managed
-- `recall(...)` returns ranked `MemoryRecord` items filtered by runtime memory scope and kind
-- `listMemories(...)` returns stable `MemoryRecord` items for inspection and admin workflows, defaulting to `active` records unless status filters are provided
-- `updateMemory(...)` edits one durable memory record by `memoryId` without exposing internal store namespaces
-- `removeMemory(...)` deletes one durable memory record by `memoryId` and rebuilds runtime-managed projections
-- app-specific knowledge taxonomy, review UI, and admin surfaces still belong in the application layer
-
-### Let The Runtime Route
-
-```ts
-const result = await request(runtime, {
-  agentId: "auto",
-  input: "Inspect the repository and explain the release flow.",
-});
-```
-
-`agentId: "auto"` evaluates ordered routing rules in `config/runtime/workspace.yaml`, then `routing.defaultAgentId`, and otherwise falls back to the default runtime entry host.
-
-### Stream Output And Events
-
-```ts
-const result = await request(runtime, {
-  agentId: "orchestra",
-  input: "Inspect the workspace and explain the available tools.",
-  eventListener(snapshot) {
-    console.log(snapshot.state, snapshot.plan.items);
-  },
-  dataListener(event) {
-    if (event.type === "output.text.delta") {
-      process.stdout.write(event.text);
-    }
-    if (event.type === "tool.result") {
-      console.log(event.toolName, event.output);
-    }
-  },
-});
-```
-
-`eventListener(...)` receives the latest full request snapshot, including request state, the live todo board, approval state, and current output.
-`dataListener(...)` receives append-only deltas such as text output, progress commentary, content blocks, tool results, and upstream debug items.
-
-`subscribe(...)` is the read-only observer surface over stored lifecycle events.
-
-The runtime event stream includes:
-
-- `request.created`
-- `request.queued`
-- `request.dequeued`
-- `request.state.changed`
-- `approval.requested`
-- `approval.resolved`
-- `output.delta`
-
-### Inspect Sessions And Approvals
-
-```ts
-import {
-  deleteSession,
-  getSession,
-  getApproval,
-  listSessions,
-  listApprovals,
-  resolveApproval,
-} from "@botbotgo/agent-harness";
-
-const sessions = await listSessions(runtime);
-const session = await getSession(runtime, sessions[0]!.sessionId);
-const approvals = await listApprovals(runtime, { status: "pending" });
-const approval = approvals[0] ? await getApproval(runtime, approvals[0].approvalId) : null;
-
-if (approval) {
-  await resolveApproval(runtime, {
-    approvalId: approval.approvalId,
-    decision: "approve",
-  });
-}
-
-if (session && session.currentState === "completed") {
-  await deleteSession(runtime, session.sessionId);
-}
-```
-
-These methods return runtime-facing records, not raw checkpoint or backend objects.
-
-### Expose And Consume MCP
-
-Bridge MCP servers into agents:
-
-```yaml
-apiVersion: agent-harness/v1alpha1
-kind: Agent
-metadata:
-  name: orchestra
-spec:
-  backend: deepagent
-  modelRef: model/default
-  mcpServers:
-    - name: browser
-      command: node
-      args: ["./mcp-browser-server.mjs"]
-```
-
-Expose harness tools as an MCP server:
-
-```ts
-import { createToolMcpServer, serveToolsOverStdio } from "@botbotgo/agent-harness";
-
-const server = await createToolMcpServer(runtime, { agentId: "orchestra" });
-await serveToolsOverStdio(runtime, { agentId: "orchestra" });
-```
-
-### Stop The Runtime
-
-```ts
-import { stop } from "@botbotgo/agent-harness";
-
-await stop(runtime);
-```
-
-<a id="readme-en-config"></a>
-
-## How To Configure
-
-Use Kubernetes-style YAML:
-
-- collection files use `apiVersion`, plural `kind`, and `spec: []`
-- singleton files use `apiVersion`, singular `kind`, `metadata`, and `spec`
-
-Core workspace files:
-
-- `config/runtime/workspace.yaml`
-- `config/agent-context.md`
-- `config/models.yaml`
-- `config/catalogs/embedding-models.yaml`
-- `config/catalogs/vector-stores.yaml`
-- `config/catalogs/stores.yaml`
-- `config/knowledge/knowledge-runtime.yaml`
-- `config/knowledge/procedural-memory-runtime.yaml`
-- `config/runtime/runtime-memory.yaml`
-- `config/catalogs/backends.yaml`
-- `config/catalogs/tools.yaml`
-- `config/catalogs/mcp.yaml`
-- `config/agents/direct.yaml`
-- `config/agents/orchestra.yaml`
-- `resources/tools/`
-- `resources/skills/`
-
-Discovery rules:
-
-- every YAML document under `config/**` is discovered recursively; filenames and subfolders are organizational only
-- YAML object semantics come from `kind`, `metadata.name` or `id`, and object content rather than the file path
-- `Runtime.spec.sources.tools` defaults to `file://./resources/tools`
-- `Runtime.spec.sources.skills` defaults to `file://./resources/skills`
-- local file-based tools are auto-discovered from each configured tool folder when modules export `tool({...})`
-- file-based skills are auto-discovered from each configured skill source
-- a minimal workspace can start with only `config/models.yaml`; the repository defaults provide the `Runtime`, the default `orchestra` host, and runtime-managed durable memory with `enabled: true`
-- when you do not override runtime placement, harness-owned generated state is written under `./.botbotgo/`
-
-Example workspaces:
-
-- prefixes indicate complexity order, where `00_` is the simplest starting point
-- `examples/00_local-tools-and-skills/` is the Local Tools and Skills Example: the smallest local tool + skill workspace
-- `examples/01_multimodal-request/` is the Multimodal Request Example: the smallest image-plus-PDF request flow
-- `examples/02_subagent-planning/` is the Subagent Planning Example: a compact planning flow with one subagent, tools, and trace output
-- `examples/03_protocol-surfaces/` is the Protocol Surfaces Example: the same minimal direct agent wired to ACP, ACP stdio, A2A, AG-UI, and runtime MCP
-- `examples/04_local-model-tool-calling/` is the Local Model Tool Calling Example: one local GGUF-backed task loop plus one local tool
-- `examples/05_runtime-trace-export/` is the Runtime Trace Export Example: one real request plus Mermaid flow export from runtime and upstream events
-- `examples/06_repository-analysis/` is the Repository Analysis Example: repo analysis around one workspace-local tool plus embedding-backed indexing
-- `examples/07_multi-agent-research/` is the Multi-Agent Research Example: the most complete multi-agent research workspace with reusable backends, skills, and local tools
-- `examples/08_long-term-memory-learning/` is the Long-Term Memory Learning Example: repeated requests that store durable memory, inspect recall, and make later answers more context-aware
-- `examples/09_long-running-coding-harness/` is the Long-Running Coding Harness Example: a host agent plus app-owned planning/evaluation roles, Playwright MCP wiring, and evaluation-bundle export for long coding sessions
-- `examples/10_playwright-mcp-browser/` is the Playwright CLI Browser Example: the smallest browser-capable workspace that follows the official Playwright coding-agent recommendation with `playwright-cli` plus a local skill
-
-Workspace-local tool modules in `resources/tools/` should be exported with `tool({...})`.
-Any other local module shape is not supported, and unsupported shapes are rejected at load time.
-When a local function tool declares its schema in the module, runtime governance treats that module-defined schema as the source of truth; duplicating it into YAML `inputSchema.ref` is optional rather than required for schema-bound metadata.
-When local tools use Zod-authored schemas, keep the workspace or isolated `resources` package on `zod@^4` so raw-shape validators and runtime parsing stay on one supported major version.
-If you want runtime-owned product tools such as `list_files`, `search_files`, `run_command`, `schedule_task`, request inspection, or artifact inspection, author them as normal `resources/tools/*.mjs` modules and whitelist them from agent YAML like any other workspace tool.
-For DeepAgents-backed agents, the runtime still keeps an internal compatibility layer for the upstream helper tools that DeepAgents expects during long multi-step execution. That compatibility set currently includes `write_todos`, `read_todos`, `ls`, `read_file`, `write_file`, `edit_file`, `glob`, `grep`, `task`, and `execute` when the selected backend implements sandbox command execution. Treat those helper names as adapter-internal execution compatibility, not as the primary product-facing workspace tool surface.
-
-Default wiring guidance:
-
-- let `Runtime.spec.sources` declare the tool and skill roots the workspace owns
-- let workspace startup scan only those declared sources into one registry
-- let workspace startup scan local and attached `resources` packages into one registry when compatibility paths are still in use
-- let agents whitelist tools and skills by name
-- keep `config/catalogs/tools.yaml` for reusable shared tools
-- keep `config/catalogs/mcp.yaml` for shared MCP server definitions
-- let agents select MCP tools and apply per-usage MCP overrides where needed
-
-There are three main configuration layers:
-
-- runtime policy in `config/runtime/workspace.yaml`
-- reusable object catalogs in `config/catalogs/*.yaml`
-- agent assembly in `config/**/*.yaml`
-
-### Backend Guidance
-
-At the moment, the most stable path for complex production-style requests is `backend: deepagent`.
-
-Current temporary limits on the `backend: langchain-v1` path are:
-
-- approval-gated side-effect tools are less reliable on the lighter direct-response path under real remote models
-- long multi-agent or orchestration-heavy flows are not the recommended default path
-- the package now treats the planner-first backend as the default execution path for complex runtime coverage, and the lighter direct-response backend should be selected explicitly when a workspace truly wants that behavior
-
-Practical guidance:
-
-- use `backend: deepagent` for approvals, resume, multi-agent orchestration, rich memory flows, and heavier tool chains
-- keep `backend: langchain-v1` for lighter direct-response or explicitly chosen V1 agent shapes while this upstream behavior settles
-
-Local GGUF note:
-
-- `provider: node-llama-cpp` now exposes a LangChain-style tool-binding shim, so local GGUF models can enter the standard tool-calling path without an app-owned model wrapper
-- `provider: openai-compatible` targets an external `llama-server` endpoint when the model process should be tuned or supervised outside Node.js
-- `backend: langchain-v1` is the straightforward local GGUF path and is the currently verified default for `node-llama-cpp` tool use
-- `backend: deepagent` can also reach the same tool-calling path, but final reliability still depends on the selected model following upstream tool schemas correctly
-- `agent-harness` does not try to normalize every model-specific argument drift or malformed tool payload; once the runtime hands a call to upstream tools, schema fidelity is a model responsibility
-
-### `config/runtime/workspace.yaml`
-
-Use this file for workspace-wide runtime policy.
-
-Important fields:
-
-- `runtimeRoot`
-- `concurrency.maxConcurrentRequests`
-- `sources.tools`
-- `sources.skills`
-- `routing.defaultAgentId`
-- `routing.rules`
-- `toolModuleDiscovery.scope`
-- `maintenance.checkpoints`
-- `maintenance.records`
-- `recovery.enabled`
-- `recovery.resumeResumingRequestsOnStartup`
-- `recovery.maxRecoveryAttempts`
-
-`recovery.resumeResumingRequestsOnStartup` keeps checkpoint resume a runtime-owned lifecycle behavior instead of exposing checkpoint orchestration as public API.
-
-`maintenance.checkpoints` and `maintenance.records` are separate retention layers:
-
-- `maintenance.checkpoints` trims backend checkpoint state used for resume/recovery
-- `maintenance.records` trims harness-owned terminal session/request records stored in `runtime.sqlite`
-
-`sources.tools` controls which tool roots or packages participate in workspace discovery:
-
-- `file://...` for folder scanning
-- `npm://...` for package discovery under `tools/` plus auto-install when missing
-
-`sources.skills` controls which skill folders or skill documents participate in workspace discovery:
-
-- `file://...` for local folders, skill roots, or direct `SKILL.md`
-- `npm://...` for package discovery under `skills/` plus auto-install when missing
-- `http://...` / `https://...` for one remote `SKILL.md`
-
-`toolModuleDiscovery.scope` controls how local `resources/tools/`-style file discovery walks tool directories:
-
-- `recursive` is the default and keeps scanning nested folders
-- `top-level` limits module discovery to files directly under each tool root while leaving YAML catalogs recursive
-
-When libSQL reports an error against harness runtime persistence, the message is prefixed with the absolute path to `runtime.sqlite`. For constraint-class failures (or whenever you set `AGENT_HARNESS_RUNTIME_SQLITE_DEBUG=1`), the message also includes a truncated copy of the failing SQL so you can tell harness persistence apart from other SQLite databases in the same process.
-
-Example:
-
-```yaml
-apiVersion: agent-harness/v1alpha1
-kind: Runtime
-metadata:
-  name: default
-spec:
-  dataRoot: ./.botbotgo
-  toolModuleDiscovery:
-    scope: top-level
-  concurrency:
-    maxConcurrentRuns: 3
-  routing:
-    defaultAgentId: orchestra
-  maintenance:
-    checkpoints:
-      enabled: true
-    records:
-      enabled: false
-  recovery:
-    enabled: true
-    resumeResumingRequestsOnStartup: true
-    maxRecoveryAttempts: 3
-```
-
-### `config/agent-context.md`
-
-Use this file for shared bootstrap memory loaded at agent construction time.
-
-Keep stable project context here. Treat it as startup context, not mutable long-term memory.
-
-### Models Catalogs In `config/**`
-
-Use named chat-model presets:
-
-```yaml
-apiVersion: agent-harness/v1alpha1
-kind: Models
-spec:
-  - name: default
-    provider: openai
-    model: gpt-4.1
-    temperature: 0.2
-```
-
-These load as `model/default`.
-
-You can place `kind: Models` catalogs anywhere under `config/`; the repository default now keeps `models.yaml` at the `config/` root, and file paths remain organizational only.
-
-### Embedding Model Catalogs In `config/**`
-
-Use named embedding-model presets for retrieval-oriented tools.
-
-### `config/catalogs/vector-stores.yaml`
-
-Use named vector-store presets referenced by retrieval tools.
-
-### `config/catalogs/stores.yaml`
-
-Use reusable store and checkpointer presets:
-
-```yaml
-apiVersion: agent-harness/v1alpha1
-kind: Stores
-spec:
-  - kind: Store
-    name: default
-    storeKind: SqliteStore
-    path: store.sqlite
-  - kind: Checkpointer
-    name: default
-    checkpointerKind: SqliteSaver
-    path: runtime/checkpoints.sqlite
-```
-
-### `config/runtime/runtime-memory.yaml`
-
-Use this singleton file for runtime-owned durable long-term memory defaults.
-
-Keep bootstrap context in `config/agent-context.md`. Keep resumable execution state in the checkpointer. Use `RuntimeMemory` for durable memory policy and retrieval defaults.
-
-`RuntimeMemory` also carries LangMem-style formation defaults:
-
-- `formation.hotPath` for immediate write-time capture
-- `formation.manager` for rule-driven or model-driven candidate normalization before persistence
-- `formation.background` for reflection after request completion or approval resolution
-
-### `config/knowledge/knowledge-runtime.yaml`
-
-Use this singleton when the same durable-memory policy should also run outside `AgentHarnessRuntime`, such as a standalone knowledge worker or knowledge server.
-
-`KnowledgeRuntime` mirrors the durable policy shape on purpose. Keep `RuntimeMemory` for runtime-owned defaults, and keep `KnowledgeRuntime` as the externalizable mirror when a separate knowledge service needs the same memorize/recall policy. Use it for fast explicit writes plus background durable-knowledge formation and maintenance.
-
-### `config/knowledge/procedural-memory-runtime.yaml`
-
-Use this singleton when the workspace wants a separate background experience-memory layer, such as a ReMe-backed procedural memory pool.
-
-`ProceduralMemoryRuntime` is intentionally separate from `KnowledgeRuntime`:
-
-- keep `KnowledgeRuntime` for durable facts, preferences, rules, and confirmed decisions
-- keep `ProceduralMemoryRuntime` for workflows, debugging lessons, tactics, and reusable procedures
-- keep both stores under the same `knowledge/` directory, but do not force them into one logical store
-
-The default repository shape uses:
-
-- `KnowledgeRuntime`: hot path + background formation + long-term maintenance
-- `ProceduralMemoryRuntime`: background formation + scheduled or idle maintenance
-
-In the shipped runtime, explicit durable facts such as “remember I moved to the United States” still go to `KnowledgeRuntime` and land in `knowledge/knowledge.sqlite`. Background procedural learning writes its own store and state files under the same data root, such as `knowledge/procedural-memory.sqlite` and `knowledge/procedural-memory-state.json`.
-
-For DeepAgents-backed workspaces, keep upstream context compaction upstream-owned and use procedural memory only as a background learning layer.
-
-### `config/catalogs/backends.yaml`
-
-Use reusable backend presets so filesystem and `/memories/*` topology stays in YAML:
-
-```yaml
-apiVersion: agent-harness/v1alpha1
-kind: Backends
-spec:
-  - kind: Backend
-    name: default
-    backendKind: CompositeBackend
-    state:
-      kind: VfsSandbox
-      rootDir: .
-      virtualMode: true
-      timeout: 600
-    routes:
-      /memories/:
-        kind: StoreBackend
-```
-
-### `config/catalogs/tools.yaml`
-
-Use this file for reusable tool objects.
-
-Built-in tool families include function tools, backend tools, MCP tools, bundles, and provider-native tools. Provider-native tools are declared in YAML and resolved directly to upstream factories.
-
-Keep `config/catalogs/tools.yaml` for reusable shared tool objects rather than making it the default path for every local tool. Workspace-owned function tools should normally be discovered from `resources/tools/` and then whitelisted by name in each agent.
-
-### `config/catalogs/mcp.yaml`
-
-Use this file for named MCP server presets.
-
-MCP servers are usually heavier shared resources than local function tools. Keep shared MCP connection details here, then let each agent choose the remote tools it wants and apply per-usage overrides at the agent usage point.
-
-Example:
-
-```yaml
-apiVersion: agent-harness/v1alpha1
-kind: McpServers
-spec:
-  - name: browser
-    transport: stdio
-    command: node
-    args:
-      - ./mcp-browser-server.mjs
-```
-
-`spec[].kind` can be omitted here; catalog entries default to `McpServer`.
-
-### Agents In `config/**`
-
-Agents always use `kind: Agent` plus `spec.backend`.
-
-Agent YAML can live anywhere under `config/`; `config/agents/*.yaml` is the recommended layout, not a loader requirement.
-
-Use two sections:
-
-- `spec.runtime` for agent-specific runtime placement overrides such as `spec.runtime.runtimeRoot`
-- top-level `spec` fields for upstream execution semantics and adapter-facing config
-
-Example direct host:
-
-```yaml
-apiVersion: agent-harness/v1alpha1
-kind: Agent
-metadata:
-  name: direct
-spec:
-  backend: langchain-v1
-  modelRef: model/default
-  tools:
-    - write_file:
-        subprocess: true
-  skills:
-    - code-review
-  memory: []
-  subagents: []
-  mcpServers: []
-  config:
-    checkpointer: default
-    store: default
-    interruptOn: {}
-    filesystem:
-      rootDir: .
-      virtualMode: true
-      maxFileSizeMb: 10
-      sessionStorage:
-        enabled: true
-        rootDir: "{runtimeRoot}/sessions/{sessionId}/filesystem"
-    middleware: []
-    systemPrompt:
-      path: ../prompts/direct-system.md
-```
-
-Keep long prompts in checked-in prompt files such as `config/prompts/*.md` and point `systemPrompt` at them with a path relative to the agent YAML file. This keeps prompt text out of source code and makes prompt edits reviewable as normal content changes.
-
-When `config.filesystem.sessionStorage.enabled: true` is set for a LangChain binding, the runtime keeps one filesystem root per persisted session and reuses the same runnable cache entry for repeated work on that session instead of collapsing every request onto one shared workspace directory.
-
-Example orchestra host:
-
-```yaml
-apiVersion: agent-harness/v1alpha1
-kind: Agent
-metadata:
-  name: orchestra
-spec:
-  backend: deepagent
-  modelRef: model/default
-  memory:
-    - path: config/agent-context.md
-  tools:
-    - stock_snapshot
-  skills:
-    - stock-research
-  subagents: []
-  mcpServers: []
-  config:
-    store: default
-    checkpointer: default
-    backend: default
-    interruptOn: {}
-    middleware: []
-```
-
-For backend-specific options, prefer the upstream concept directly inside `spec.config`. Keep the public runtime contract in the main developer docs and API reference rather than relying only on informal comparison notes.
-
-## Design Notes
-
-- `agent-harness` is not a third agent framework
-- public runtime contract stays generic and small
-- application-level orchestration and lifecycle management stays in the harness
-- the external protocol boundary should strictly conform to `deepagents-acp` instead of a parallel harness-only protocol
-- upstream execution-backend concepts should be expressed as directly as possible in YAML
-- when a feature can be expressed in YAML, prefer YAML over expanding the public API
-- recovery, approvals, sessions, requests, and events are runtime concepts, not backend escape hatches
-- application task centers should be built on the existing store plus runtime ids instead of expanding the public runtime contract
-- new backend-specific config should land in YAML mapping and tests before adding public runtime APIs
-
-In short, the product model stays stable while the execution semantics remain upstream-owned.
-
-<a id="readme-en-api-summary"></a>
-
-## API Summary
-
-Primary exports:
-
-- `createAgentHarness`
-- `AgentHarnessRuntime`
-- `request`
-- `resolveApproval`
-- `subscribe`
-- `listRequests`
-- `getRequest`
-- `listSessions`
-- `getSession`
-- `deleteSession`
-- `listApprovals`
-- `getApproval`
-- `listArtifacts`
-- `getArtifact`
-- `listRequestEvents`
-- `listRequestTraceItems`
-- `exportRequestPackage`
-- `exportSessionPackage`
-- `exportEvaluationBundle`
-- `replayEvaluationBundle`
-- `createAcpServer`
-- `createAcpStdioClient`
-- `serveAcpHttp`
-- `serveAcpStdio`
-- `serveA2aHttp`
-- `serveAgUiHttp`
-- `createRuntimeMcpServer`
-- `serveRuntimeMcpOverStdio`
-- `createToolMcpServer`
-- `serveToolsOverStdio`
-- `stop`
-- `createUpstreamTimelineReducer`
-- `exportFlow`
-- `exportSequence`
-
-Inspection helpers:
-
-- `createUpstreamTimelineReducer()` reduces raw upstream model/tool/chain events into ordered step-like projections for inspection and visualization.
-- `listRequestTraceItems(runtime, { sessionId, requestId })` returns the persisted request trace items that back runtime diagrams and post-request inspection. Each trace item carries the normalized runtime surface record plus the source upstream event.
-- `exportFlow(runtime, { sessionId, requestId })` loads one persisted request record from the runtime and renders it as Mermaid flowchart text. It uses the built-in product view defaults for direction, grouping, and visible kinds so callers do not need to carry visualization options in normal product code.
-- `exportSequence(runtime, { sessionId, requestId })` loads the same persisted request record and renders it as a Mermaid sequence diagram for the same persisted trace-backed request.
-
-These helpers are visualization and inspection utilities. They do not introduce a canonical harness-owned execution protocol.
-
-ACP transport notes:
-
-- `serveAcpStdio(runtime)` exposes newline-delimited JSON-RPC over stdio for local IDE, CLI, or subprocess clients.
-- `serveAcpHttp(runtime)` exposes JSON-RPC over HTTP plus SSE runtime events so remote operator surfaces can connect without importing the runtime in-process.
-- ACP transport validation now covers the reference-client core flow: capability discovery, request submit, session lookup, request lookup, invalid-JSON handling, notification calls without response ids, stdio JSON-RPC, and HTTP plus SSE runtime notifications.
-- Cross-protocol conformance now has an explicit regression gate as well: ACP submission, A2A task lookup and continuation, and runtime MCP inspection must all project the same persisted `sessionId` / `requestId` runtime records instead of drifting into surface-specific identifiers or side stores.
-- For the thinnest editor or CLI starter, begin with `agent-harness acp serve --workspace . --transport stdio` and mirror the `examples/03_protocol-surfaces/app/acp-stdio/main.mjs` wire shape. Applications that want an in-process reference client can use `createAcpStdioClient(...)` to issue JSON-RPC requests and route runtime notifications without hand-rolling line parsing.
-- For the shortest local operator workflow, `botbotgo start --workspace .` now starts ACP, A2A, runtime MCP, and AG-UI together as managed local services, and `botbotgo stop --workspace .` stops the same set. `--services acp,mcp` narrows the set when one workspace only needs part of the local protocol surface.
-- When a local ACP HTTP endpoint should stay up beyond one foreground shell, use `botbotgo acp start --workspace . --host 127.0.0.1 --port 8787` and later `botbotgo acp stop --workspace .`. The CLI records the managed process under `.botbotgo/services/` so local operators can start and stop it without a second process manager.
-- `botbotgo` is the shortest local terminal entrypoint for a published install. It defaults the workspace to the current directory, so teams can `cd` into their own runtime workspace and run `botbotgo` or `botbotgo "..."` directly. `agent-harness` keeps the same implicit-chat behavior, and `-w/--workspace` still lets one shell point at another workspace when needed.
-- `agent-harness chat --workspace .` still acts as a local terminal shell over the shared `HarnessClient` contract when you want the explicit subcommand form: the default `stdio` path runs directly in-process against the workspace runtime, while `--transport http --host <host> --port <port>` can still target an already-running ACP HTTP endpoint. One-shot use can pass `--message`, while interactive mode supports `/context`, `/new`, `/agent <agentId>`, `/sessions`, `/requests`, `/resume <sessionId>`, `/approvals`, `/approve`, `/reject`, `/cancel`, `/events`, `/trace`, `/health`, `/overview`, `/session`, `/request [requestId]`, and `/exit`. `/resume` now validates the target session, restores its latest request id, and rehydrates the active agent context; `/request <requestId>` can switch the active request context to a persisted request; `/new` clears the current session/request context without leaving the shell. Terminal chat now keeps one operator-facing flow: it streams tool and progress events as they happen and still prints the full final answer, instead of switching to a separate request-tree-only mode.
-- Local repo usage differs from the published binary on purpose. After cloning the repo, use `npm run chat -- --workspace ./config` or `npm run agent-harness -- chat --workspace ./config`. The extra `--` matters: without it, npm treats `--workspace` as npm's own workspace flag. The standalone `agent-harness ...` command only works after the package has been installed or linked so the `bin` entry is on your `PATH`.
-- Interactive chat now opens with a large ASCII startup banner that prints the active workspace, transport, and current override context before the command help so the shell feels like a dedicated runtime console instead of a raw REPL.
-- When the workspace model/provider cannot be reached, chat now expands generic failures such as `runtime_error=fetch failed` into operator-facing diagnostics that include the configured provider, model, endpoint, and a concrete recovery hint, instead of leaving the shell at an opaque transport error.
-- Chat startup now also performs a lightweight workspace-model preflight for the local Ollama path. If the configured endpoint is unreachable or responds with `404 page not found`, the shell prints that warning before the first prompt so endpoint mismatches show up immediately instead of only after the first failed message.
-- The interactive prompt now carries the live `agent`, `session`, and short `request` identifier together, so after each reply and during shell-history navigation the user stays anchored to the current runtime turn instead of dropping back to a bare input prompt.
-- `serveA2aHttp(runtime)` exposes an A2A-compatible HTTP JSON-RPC bridge plus agent card discovery, mapping both existing methods such as `message/send` and A2A v1.0 PascalCase methods such as `SendMessage`, `SendStreamingMessage`, `GetTask`, `ListTasks`, `CancelTask`, `SubscribeToTask`, `GetAgentCard`, `GetExtendedAgentCard`, and task push-notification config methods onto the existing session/request runtime surface. The bridge now advertises both `1.0` and `0.3` JSON-RPC interfaces, answers `HEAD` / `OPTIONS` discovery on the agent-card path, sets supported-version discovery headers, can optionally expose registry URLs plus detached signed-card metadata for surrounding discovery systems, validates `A2A-Version`, records `A2A-Extensions` into runtime invocation metadata, publishes `TASK_STATE_*` statuses plus the `{ task }` `SendMessage` wrapper, streams an initial `{ task }` snapshot plus later `{ statusUpdate }` payloads over SSE for v1 streaming methods, and can send best-effort webhook task snapshots for configured push notification receivers.
-- For a managed local bridge, use `botbotgo a2a start --workspace . --host 127.0.0.1 --port 8080` and later `botbotgo a2a stop --workspace .`. This uses the same `.botbotgo/services/` state directory as ACP so both local protocol bridges follow one terminal-first workflow.
-- `serveAgUiHttp(runtime)` exposes an AG-UI-compatible HTTP SSE bridge that projects runtime lifecycle, safe progress commentary, text output, upstream thinking, step progress, and tool calls onto `RUN_*`, `STATUS_UPDATE`, `TEXT_MESSAGE_*`, `THINKING_TEXT_MESSAGE_*`, `STEP_*`, and `TOOL_CALL_*` events for UI clients. `botbotgo ag-ui start|stop` now manages that HTTP bridge in the same workspace-local service registry as ACP, A2A, and runtime MCP.
-- `createRuntimeMcpServer(runtime)`, `serveRuntimeMcpOverStdio(runtime)`, and `serveRuntimeMcpOverStreamableHttp(runtime)` expose the persisted runtime control surface itself as MCP tools, including sessions, requests, approvals, artifacts, events, and package export helpers. `botbotgo mcp serve --transport streamable-http --host 127.0.0.1 --port 8090` serves the same tool surface over Streamable HTTP, and `botbotgo mcp start|stop` manages that background endpoint for one workspace.
-- `listRequestEvents(...)`, `listRequestTraceItems(...)`, and `exportRequestPackage(...)` are the request-first inspection helpers.
-- `analyzeBoundaries(runtime)` returns a workspace boundary report covering agent, subagent, tool, and skill surfaces, including structural findings such as missing subagent references, unreferenced tools or skills, and skill allow-lists that do not match the owning agent's exposed tools.
-- `exportRequestPackage(...)` and `exportSessionPackage(...)` package stable runtime records, transcript, approvals, events, artifacts, and governance evidence for operator tooling without reaching into persistence internals.
-- `runtime/default.governance.remoteMcp` can now deny or allow specific MCP servers, raise approval requirements by transport, and stamp transport-based risk tiers into runtime governance bundles. MCP server catalogs can also declare trust tier, access mode, tenant scope, approval policy, prompt-injection risk, and OAuth scope metadata so governance bundles capture why one remote tool is treated as high-risk. Tool policy overrides can also set `decisionMode: manual | auto-approve | auto-reject | deny-and-continue` so operator evidence and execution behavior stay aligned.
-- Protocol responsibilities stay split on purpose: ACP is the primary editor/client runtime boundary, A2A is the streaming-capable agent-platform bridge with polling compatibility, AG-UI is the UI event surface, and runtime MCP is the operator-facing control plane exported as MCP tools.
-- `runtime/default.observability.tracing` can now describe exporter metadata such as OTLP endpoints and propagation mode, so frozen runtime snapshots keep trace-correlation plus operator-visible export context without exposing backend-private span internals.
-- `agent-harness runtime overview`, `agent-harness runtime boundaries`, `agent-harness runtime health`, `agent-harness runtime approvals list|watch`, `agent-harness runtime requests list|tail`, and `agent-harness runtime export request|session` provide a thin operator CLI over workspace boundary analysis, persisted runtime health, queue pressure, governance risk, approval queues, active request state, and audit-ready evidence packages.
-- detailed A2A adapter guidance lives in [`docs/a2a-bridge.md`](docs/a2a-bridge.md)
+Docs: https://agent-harness.easynet.world/