@botbotgo/agent-harness 0.0.56 → 0.0.58

package/README.md

@@ -1,15 +1,45 @@
+<p align="center">
+  <img src="./docs/assets/readme-banner.png" alt="botbotgo runtime banner" />
+</p>
+
+<p align="center">
+  <strong>English</strong> · <a href="./README.zh.md">中文</a>
+</p>
+
 # @botbotgo/agent-harness
 
+<p align="center">
+  <strong>A workspace-shaped runtime for agent systems that need to keep running after the demo.</strong>
+</p>
+
+<p align="center">
+  <a href="https://botbotgo.github.io/agent-harness/">Product website</a>
+  (static page in <code>docs/</code>, publish with GitHub Pages; EN / 中文 toggle)
+</p>
+
+<p align="center">
+  <em
+    >We specialize in AI solutions. If you have a product idea you want to ship,
+    <a href="mailto:info@easynet.world">info@easynet.world</a>.</em
+  >
+</p>
+
 ## Product Overview
 
 `@botbotgo/agent-harness` is a workspace-shaped application runtime for real agent products.
 
 It is not a new agent framework. It is the runtime layer around LangChain v1 and DeepAgents that turns one workspace into one operable application runtime.
 
+The point is simple:
+
+- Codex, Claude Code, and Cursor are products for people using agents
+- LangChain v1 and DeepAgents are frameworks for defining agent execution semantics
+- `agent-harness` is the runtime product layer for shipping, operating, recovering, and governing multi-agent applications
+
 The product boundary is strict:
 
 - LangChain v1 and DeepAgents own agent execution semantics
-- `agent-harness` owns application-level orchestration and lifecycle management stays in the harness
+- application-level orchestration and lifecycle management stays in the harness
 
 That means:
 
@@ -39,6 +69,27 @@ Boundary documents live in:
 - `docs/product-boundary.md`
 - `docs/feature-checklist.md`
 
+## Why This Exists
+
+Most agent demos stop at execution.
+
+Real products need a runtime that can answer harder questions:
+
+- Where do runs live?
+- How are approvals resolved?
+- What survives process restart?
+- How do you inspect threads and events without exposing raw backend state?
+- How do you swap backend implementations without rewriting the product model?
+
+`agent-harness` is the layer that answers those questions without turning your application API into a mirror of LangChain v1 or DeepAgents.
+
+## What Makes It Different
+
+- It treats `runs`, `threads`, `approvals`, `events`, and recovery as product concepts
+- It keeps checkpoint resume system-managed instead of promoting checkpoint internals into the primary API
+- It lets YAML own assembly complexity while code keeps a tiny surface
+- It goes deep on runtime concerns that upstream libraries do not fully productize
+
 ## Quick Start
 
 Install:
@@ -89,6 +140,13 @@ try {
 }
 ```
 
+If you want the shortest possible mental model:
+
+- one workspace becomes one runtime
+- YAML defines assembly and policy
+- `run(runtime, { ... })` executes requests against that runtime
+- the runtime owns lifecycle, inspection, and recovery
+
 ## Feature List
 
 - Workspace runtime for multi-agent applications
@@ -103,6 +161,13 @@ try {
 - MCP bridge support for agent-declared MCP servers
 - MCP server support for exposing harness tools outward
 
+### 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

package/README.zh.md

@@ -0,0 +1,574 @@
+<p align="center">
+  <img src="./docs/assets/readme-banner.png" alt="botbotgo runtime banner" />
+</p>
+
+<p align="center">
+  <a href="./README.md">English</a> · <strong>中文</strong>
+</p>
+
+# @botbotgo/agent-harness
+
+<p align="center">
+  <strong>面向「演示之后还要继续跑」的 agent 体系的工作区形态运行时。</strong>
+</p>
+
+<p align="center">
+  <a href="https://botbotgo.github.io/agent-harness/">产品网站</a>
+  （<code>docs/</code> 中的静态页，通过 GitHub Pages 发布；支持中英文切换）
+</p>
+
+<p align="center">
+  <em
+    >我们专注于 AI 解决方案。若有希望落地的产品想法，欢迎来信
+    <a href="mailto:info@easynet.world">info@easynet.world</a>。</em
+  >
+</p>
+
+## 产品概览
+
+`@botbotgo/agent-harness` 是面向真实 agent 产品的、工作区形态的应用运行时。
+
+它不是又一个 agent 框架，而是围绕 LangChain v1 与 DeepAgents 的运行时层：把一个工作区变成一套可运维的应用运行时。
+
+关系可以概括为：
+
+- Codex、Claude Code、Cursor 是「人用 agent」的产品
+- LangChain v1 与 DeepAgents 是定义 agent 执行语义的框架
+- `agent-harness` 是交付、运维、恢复与治理多 agent 应用的运行时产品层
+
+产品边界是清晰的：
+
+- LangChain v1 与 DeepAgents 拥有 agent 执行语义
+- 应用级编排与生命周期管理留在 harness 中
+
+因此：
+
+- 对外 API 保持精简
+- 复杂装配与运行策略放在 YAML
+- 后端实现可换时，运行时生命周期模型仍保持稳定
+- 后端细节藏在适配器之后
+
+运行时提供：
+
+- `createAgentHarness(workspaceRoot)`、`run(...)`、`resolveApproval(...)`、`subscribe(...)`、各类查询方法，以及 `stop(...)`
+- 以 YAML 描述的工作区装配：路由、模型、工具、存储、后端、MCP、恢复与维护等
+- 通过适配器对接当前的 LangChain v1 与 DeepAgents 执行
+- 本地 `resources/tools/` 与 `resources/skills/` 的发现
+- 持久化的线程、运行、审批、事件、队列状态与恢复元数据
+
+仓库自带的默认配置刻意做成「形状完整」。随仓库提供的 YAML 对重要的运行时与 agent 开关给出显式默认值，便于从具体配置起步，而不必从源码反推适配器行为。
+
+默认原则是：
+
+- 若 LangChain v1 或 DeepAgents 已有能力，则在 YAML 中映射并在内部适配
+- 除非问题确实属于运行时职责，否则不增加新的公共运行时 API
+
+边界说明见：
+
+- `docs/upstream-feature-matrix.md`
+- `docs/product-boundary.md`
+- `docs/feature-checklist.md`
+
+## 为何需要它
+
+多数 agent 演示停在「能跑」。
+
+真实产品需要能回答更难问题的运行时：
+
+- 运行（runs）存在哪里？
+- 审批如何闭环？
+- 进程重启后什么还在？
+- 如何在不暴露原始后端状态的前提下检查线程与事件？
+- 如何在不大改产品模型的前提下替换后端实现？
+
+`agent-harness` 在不把应用 API 变成 LangChain v1 / DeepAgents 翻版的前提下，回答这些问题。
+
+## 有何不同
+
+- 将 `runs`、`threads`、`approvals`、`events` 与恢复视为产品概念
+- 将 checkpoint 恢复作为系统管理的行为，而不是把 checkpoint 细节抬成主 API
+- 复杂装配交给 YAML，代码面保持极小
+- 在上游库未充分产品化的运行时时，做深做透
+
+## 快速开始
+
+安装：
+
+```bash
+npm install @botbotgo/agent-harness
+```
+
+工作区布局：
+
+```text
+your-workspace/
+  config/
+    workspace.yaml
+    agent-context.md
+    models.yaml
+    embedding-models.yaml
+    vector-stores.yaml
+    stores.yaml
+    backends.yaml
+    tools.yaml
+    mcp.yaml
+    agents/
+      direct.yaml
+      orchestra.yaml
+  resources/
+    package.json
+    tools/
+    skills/
+```
+
+最小用法：
+
+```ts
+import { createAgentHarness, run, stop } from "@botbotgo/agent-harness";
+
+const runtime = await createAgentHarness("/absolute/path/to/workspace");
+
+try {
+  const result = await run(runtime, {
+    agentId: "auto",
+    input: "Explain what this workspace is for.",
+  });
+
+  console.log(result.output);
+} finally {
+  await stop(runtime);
+}
+```
+
+最短心智模型：
+
+- 一个工作区对应一个运行时
+- YAML 定义装配与策略
+- `run(runtime, { ... })` 在该运行时上执行请求
+- 运行时负责生命周期、可观测性与恢复
+
+## 功能列表
+
+- 多 agent 应用的工作区运行时
+- 精简的公共运行时契约
+- YAML 定义的主机路由与运行时策略
+- LangChain v1 与 DeepAgents 后端适配
+- 自动发现本地工具与 SKILL 包
+- 原生 provider 工具、MCP 工具与工作区本地工具模块
+- 持久化线程、运行、审批、生命周期事件与排队运行
+- 运行时管理的恢复与 checkpoint 维护
+- 运行结果中的结构化输出与多模态内容保留
+- 将 agent 声明的 MCP 服务桥接进来
+- 将 harness 工具对外暴露为 MCP 服务
+
+### 运行时优势
+
+- 后端细节演进时，面向产品的 API 仍可保持稳定
+- 公共运行时契约与后端适配契约分离清晰
+- 路由、拓扑、策略与基础设施对象由 YAML 明确拥有
+- 相较薄封装 agent 循环，更适合长运行、重审批、多 agent 产品
+
+## 使用方式
+
+### 创建运行时
+
+```ts
+import { AgentHarnessRuntime, createAgentHarness } from "@botbotgo/agent-harness";
+
+const runtime: AgentHarnessRuntime = await createAgentHarness("/absolute/path/to/workspace");
+```
+
+`createAgentHarness(...)` 会加载工作区、解析 `resources/`、在 `runRoot` 下初始化持久化，并启动运行时维护任务。
+
+### 发起一次运行
+
+```ts
+import { run } from "@botbotgo/agent-harness";
+
+const result = await run(runtime, {
+  agentId: "orchestra",
+  input: "Summarize the runtime design.",
+  invocation: {
+    context: {
+      requestId: "req-123",
+    },
+    inputs: {
+      visitCount: 1,
+    },
+    attachments: {
+      "/tmp/spec.md": { content: "draft" },
+    },
+  },
+});
+```
+
+`run(runtime, { ... })` 会创建或延续持久化线程，并返回 `threadId`、`runId`、`state` 以及紧凑文本 `output`。更丰富的上游结果形态仍可通过 `outputContent`、`contentBlocks`、`structuredResponse` 等获得。
+
+将 `invocation` 作为面向运行时的请求信封：
+
+- `invocation.context`：请求级执行上下文
+- `invocation.inputs`：结构化运行时输入
+- `invocation.attachments`：当前后端可解释的类附件负载
+
+### 由运行时路由
+
+```ts
+const result = await run(runtime, {
+  agentId: "auto",
+  input: "Inspect the repository and explain the release flow.",
+});
+```
+
+`agentId: "auto"` 会按顺序评估 `config/workspace.yaml` 中的路由规则，再使用 `routing.defaultAgentId`，且仅当 `routing.modelRouting: true` 时才回退到模型路由。
+
+### 流式输出与事件
+
+```ts
+const result = await run(runtime, {
+  agentId: "orchestra",
+  input: "Inspect the workspace and explain the available tools.",
+  listeners: {
+    onChunk(chunk) {
+      process.stdout.write(chunk);
+    },
+    onContentBlocks(blocks) {
+      console.log(blocks);
+    },
+    onEvent(event) {
+      console.log(event.eventType, event.payload);
+    },
+  },
+});
+```
+
+`subscribe(...)` 是对已存储生命周期事件的只读观察者接口。
+
+运行时事件流包括：
+
+- `run.created`
+- `run.queued`
+- `run.dequeued`
+- `run.state.changed`
+- `approval.requested`
+- `approval.resolved`
+- `output.delta`
+
+### 检查线程与审批
+
+```ts
+import {
+  getApproval,
+  getThread,
+  listApprovals,
+  listThreads,
+  resolveApproval,
+} 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;
+
+if (approval) {
+  await resolveApproval(runtime, {
+    approvalId: approval.approvalId,
+    decision: "approve",
+  });
+}
+```
+
+这些方法返回面向运行时的记录，而非原始 checkpoint 或后端对象。
+
+### 接入与暴露 MCP
+
+将 MCP 服务桥接到 agent：
+
+```yaml
+apiVersion: agent-harness/v1alpha1
+kind: Agent
+metadata:
+  name: orchestra
+spec:
+  execution:
+    backend: deepagent
+    modelRef: model/default
+    mcpServers:
+      - name: browser
+        command: node
+        args: ["./mcp-browser-server.mjs"]
+```
+
+将 harness 工具作为 MCP 服务对外暴露：
+
+```ts
+import { createToolMcpServer, serveToolsOverStdio } from "@botbotgo/agent-harness";
+
+const server = await createToolMcpServer(runtime, { agentId: "orchestra" });
+await serveToolsOverStdio(runtime, { agentId: "orchestra" });
+```
+
+### 停止运行时
+
+```ts
+import { stop } from "@botbotgo/agent-harness";
+
+await stop(runtime);
+```
+
+## 如何配置
+
+使用 Kubernetes 风格的 YAML：
+
+- 集合类文件使用 `apiVersion`、复数 `kind` 与 `spec: []`
+- 单例文件使用 `apiVersion`、单数 `kind`、`metadata` 与 `spec`
+
+核心工作区文件：
+
+- `config/workspace.yaml`
+- `config/agent-context.md`
+- `config/models.yaml`
+- `config/embedding-models.yaml`
+- `config/vector-stores.yaml`
+- `config/stores.yaml`
+- `config/backends.yaml`
+- `config/tools.yaml`
+- `config/mcp.yaml`
+- `config/agents/direct.yaml`
+- `config/agents/orchestra.yaml`
+- `resources/tools/`
+- `resources/skills/`
+
+主要有三层配置：
+
+- `config/workspace.yaml` 中的运行时策略
+- `config/*.yaml` 中的可复用对象目录
+- `config/agents/*.yaml` 中的 agent 装配
+
+### `config/workspace.yaml`
+
+用于工作区范围的运行时策略。
+
+重要字段：
+
+- `runRoot`
+- `concurrency.maxConcurrentRuns`
+- `routing.defaultAgentId`
+- `routing.rules`
+- `routing.systemPrompt`
+- `routing.modelRouting`
+- `maintenance.checkpoints`
+- `recovery.enabled`
+- `recovery.resumeResumingRunsOnStartup`
+- `recovery.maxRecoveryAttempts`
+
+`recovery.resumeResumingRunsOnStartup` 将 checkpoint 恢复保持为运行时拥有的生命周期行为，而不是把 checkpoint 编排暴露为主 API。
+
+示例：
+
+```yaml
+apiVersion: agent-harness/v1alpha1
+kind: Runtime
+metadata:
+  name: default
+spec:
+  runRoot: ./.agent
+  concurrency:
+    maxConcurrentRuns: 3
+  routing:
+    defaultAgentId: orchestra
+    modelRouting: false
+  maintenance:
+    checkpoints:
+      enabled: true
+  recovery:
+    enabled: true
+    resumeResumingRunsOnStartup: true
+    maxRecoveryAttempts: 3
+```
+
+### `config/agent-context.md`
+
+用于在构建 agent 时加载的共享启动记忆。
+
+在此放置稳定的项目上下文；视为启动上下文，而非可变长期记忆。
+
+### `config/models.yaml`
+
+命名聊天模型预设：
+
+```yaml
+apiVersion: agent-harness/v1alpha1
+kind: Models
+spec:
+  - name: default
+    provider: openai
+    model: gpt-4.1
+    temperature: 0.2
+```
+
+加载为 `model/default`。
+
+### `config/embedding-models.yaml`
+
+面向检索类工具的命名嵌入模型预设。
+
+### `config/vector-stores.yaml`
+
+检索工具引用的命名向量库预设。
+
+### `config/stores.yaml`
+
+可复用的存储与 checkpointer 预设：
+
+```yaml
+apiVersion: agent-harness/v1alpha1
+kind: Stores
+spec:
+  - kind: Store
+    name: default
+    storeKind: FileStore
+    path: store.json
+  - kind: Checkpointer
+    name: default
+    checkpointerKind: MemorySaver
+  - kind: Checkpointer
+    name: sqlite
+    checkpointerKind: SqliteSaver
+    path: checkpoints.sqlite
+```
+
+### `config/backends.yaml`
+
+可复用的 DeepAgents 后端预设，使文件系统与 `/memories/*` 拓扑保留在 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/tools.yaml`
+
+可复用工具对象。
+
+内置工具族包括函数工具、后端工具、MCP 工具、bundle 与原生 provider 工具。原生 provider 工具在 YAML 中声明并直接解析到上游工厂。
+
+### `config/mcp.yaml`
+
+命名 MCP 服务预设。
+
+### `config/agents/*.yaml`
+
+Agent 始终使用 `kind: Agent` 以及 `spec.execution.backend`。
+
+两个嵌套区块：
+
+- `spec.runtime`：harness 侧运行时放置，例如 `spec.runtime.runRoot`
+- `spec.execution`：上游执行语义与面向适配器的配置
+
+direct 主机示例：
+
+```yaml
+apiVersion: agent-harness/v1alpha1
+kind: Agent
+metadata:
+  name: direct
+spec:
+  runtime:
+    runRoot: ./.agent
+  execution:
+    backend: langchain-v1
+    modelRef: model/default
+    tools: []
+    skills: []
+    memory: []
+    subagents: []
+    mcpServers: []
+    config:
+      checkpointer:
+        ref: checkpointer/default
+      store:
+        ref: store/default
+      interruptOn: {}
+      filesystem:
+        rootDir: .
+        virtualMode: true
+        maxFileSizeMb: 10
+      middleware: []
+      systemPrompt: Answer simple requests directly.
+```
+
+orchestra 主机示例：
+
+```yaml
+apiVersion: agent-harness/v1alpha1
+kind: Agent
+metadata:
+  name: orchestra
+spec:
+  runtime:
+    runRoot: ./.agent
+  execution:
+    backend: deepagent
+    modelRef: model/default
+    memory:
+      - path: config/agent-context.md
+    tools: []
+    skills: []
+    subagents: []
+    mcpServers: []
+    config:
+      store:
+        ref: store/default
+      checkpointer:
+        ref: checkpointer/default
+      backend:
+        ref: backend/default
+      interruptOn: {}
+      middleware: []
+      generalPurposeAgent: true
+      taskDescription: Complete delegated sidecar work and return concise results without bloating the parent context.
+```
+
+后端相关选项优先直接写在 `spec.execution.config` 中沿用上游概念。上游能力覆盖见 [docs/upstream-feature-matrix.md](docs/upstream-feature-matrix.md)。
+
+## 设计说明
+
+- `agent-harness` 不是第三个 agent 框架
+- 公共运行时契约保持通用且精简
+- 应用级编排与生命周期管理留在 harness 中
+- 应尽量在 YAML 中直接表达 LangChain v1 与 DeepAgents 的概念
+- 能用 YAML 表达的能力，优先 YAML 而非扩张公共 API
+- 恢复、审批、线程、运行与事件是运行时概念，不是后端逃生舱
+- 新的 LangChain v1 或 DeepAgents 配置应先落在 YAML 映射与测试中，再考虑公共运行时 API
+
+简言之：产品模型稳定，执行语义仍归上游。
+
+## API 摘要
+
+主要导出：
+
+- `createAgentHarness`
+- `AgentHarnessRuntime`
+- `run`
+- `resolveApproval`
+- `subscribe`
+- `listThreads`
+- `getThread`
+- `deleteThread`
+- `listApprovals`
+- `getApproval`
+- `createToolMcpServer`
+- `serveToolsOverStdio`
+- `stop`

package/dist/api.d.ts

@@ -1,5 +1,7 @@
 import type { ApprovalRecord, RunOptions, ResumeOptions, RuntimeAdapterOptions, ThreadSummary, ThreadRecord, WorkspaceLoadOptions } from "./contracts/types.js";
 import { AgentHarnessRuntime } from "./runtime/harness.js";
+import type { InventoryAgentRecord, InventorySkillRecord } from "./runtime/inventory.js";
+import type { RequirementAssessmentOptions } from "./runtime/skill-requirements.js";
 import type { ToolMcpServerOptions } from "./mcp.js";
 export { AgentHarnessRuntime } from "./runtime/harness.js";
 type CreateAgentHarnessOptions = {
@@ -15,6 +17,11 @@ export declare function getThread(runtime: AgentHarnessRuntime, threadId: string
 export declare function deleteThread(runtime: AgentHarnessRuntime, threadId: string): Promise<boolean>;
 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 listAgentSkills(runtime: AgentHarnessRuntime, agentId: string, options?: RequirementAssessmentOptions): InventorySkillRecord[];
+export declare function describeInventory(runtime: AgentHarnessRuntime, options?: RequirementAssessmentOptions): {
+    workspaceRoot: string;
+    agents: InventoryAgentRecord[];
+};
 export declare function resolveApproval(runtime: AgentHarnessRuntime, options: ResumeOptions): Promise<import("./contracts/types.js").RunResult>;
 export declare function stop(runtime: AgentHarnessRuntime): Promise<void>;
 export declare function createToolMcpServer(runtime: AgentHarnessRuntime, options: ToolMcpServerOptions): Promise<import("@modelcontextprotocol/sdk/server/mcp.js").McpServer>;

package/dist/api.js

@@ -28,6 +28,12 @@ export async function listApprovals(runtime, filter) {
 export async function getApproval(runtime, approvalId) {
     return runtime.getApproval(approvalId);
 }
+export function listAgentSkills(runtime, agentId, options) {
+    return runtime.listAgentSkills(agentId, options);
+}
+export function describeInventory(runtime, options) {
+    return runtime.describeWorkspaceInventory(options);
+}
 export async function resolveApproval(runtime, options) {
     return runtime.resume(options);
 }

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { AgentHarnessRuntime, createAgentHarness, createToolMcpServer, deleteThread, getApproval, getThread, listApprovals, listThreads, resolveApproval, run, serveToolsOverStdio, subscribe, stop, } from "./api.js";
+export { AgentHarnessRuntime, createAgentHarness, createToolMcpServer, deleteThread, describeInventory, getApproval, getThread, listAgentSkills, listApprovals, listThreads, resolveApproval, run, serveToolsOverStdio, subscribe, stop, } from "./api.js";
 export type { ToolMcpServerOptions } from "./mcp.js";
 export { tool } from "./tools.js";