mosoo-agent-driver

<div align="center"> <img src="./assets/logo.svg" alt="Mosoo" width="138" height="138" /> <h1>mosoo-agent-driver</h1> <strong>单一驱动内核，多代理后端。</strong> <br /> Mosoo 代理驱动程序 — 在 Mosoo 中驱动沙箱托管代理会话的运行时。 <br /> <br /> <!-- Static badges below render cleanly before the package is published to npm. Once the first npm release exists, swap in the dynamic versions: build: https://img.shields.io/github/actions/workflow/status/langgenius/mosoo-agent-driver/ci.yml?branch=main&label=build version: https://img.shields.io/npm/v/agent-driver?label=version downloads: https://img.shields.io/npm/dm/agent-driver?label=downloads --> [](#checks) [](./package.json) [](./LICENSE.txt) [](https://github.com/langgenius) [](https://x.com/mosooagent) </div> --- `mosoo-agent-driver` 是用于沙箱托管代理会话的独立运行时驱动程序。它在沙箱内运行，并驱动单个代理会话从启动到停止。核心产品是 **驱动内核**：运行时中立的命令、事件、主机端口、提供者后端和提供者注册表。软件包清单使用名称 `agent-driver`，但该软件包尚未发布到 npm。 在驱动内核上，通过投影层叠了一个实验性的、非支持的、类似 CMA 的库适配器。它不是兼容性或一致性声明，也不是 Mosoo 生产 API 的一部分。提供者后端发出驱动运行时事件并消耗驱动命令；它们不直接发出 CMA 事件。 ## 当前 Mosoo 拓扑 ```mermaid flowchart LR Runtime["Mosoo Runtime"] Boot["私有启动负载文件<br/>controlUrl + 一次性令牌 + 跟踪上下文"] Driver["agent-driver<br/>在沙箱内"] Ingress["API 工作器<br/>/api/driver/socket"] DriverDO["驱动连接绑定<br/>驱动实例持久对象"] Backend["选定的后端<br/>OpenAI 应用服务器 / Claude 代理 SDK / ACP 备用"] Runtime -->|"写入文件并启动进程，附带<br/>MOSOO_DRIVER_BOOT_PAYLOAD_FILE"| Boot Boot -->|"读取并删除"| Driver Driver -->|"外出认证 WebSocket"| Ingress Ingress -->|"升级交接"| DriverDO Driver <-->|"ORPC：hello、ready、heartbeat、<br/>命令、事件和日志"| DriverDO Driver -->|"启动和监督"| Backend ``` 驱动程序不打开沙箱本地控制监听器。在 Mosoo 的生产路径中，运行时写入私有启动负载，传递其路径在 `MOSOO_DRIVER_BOOT_PAYLOAD_FILE` 中，并启动 `agent-driver`；启动配置不通过标准输入注入。驱动程序读取并删除该文件，将负载的 `controlUrl` 转换为 `ws:` 或 `wss:`，并主动拨号 `/api/driver/socket`。API 工作器将升级路由到由匹配的 `DriverInstance` 持久对象支持的 `DriverConnection` 绑定。该对象验证并声明一次性启动令牌，并拥有 ORPC 命令、就绪、heartbeat、事件和日志生命周期。 ## 为什么使用 agent-driver 不同的模型供应商提供不同的代理运行时 — Claude 代理 SDK、OpenAI 的应用服务器协议和基于 ACP 的代理 — 每个都使用其自己的事件词汇。`agent-driver` 在内核级别统一它们，因此主机集成 **一个** 协议而不是三个。 - **内核级统一。** 三个可启动的传输 — `openai-app-server`（OpenAI 运行时）、`claude-agent-sdk` 和 `acp-fallback` — 投影到单个驱动事件协议上。主机针对一组命令和事件编写，而不管会话后面的哪个后端是。容器当前配置 OpenCode 为默认 ACP 进程，而 ACP 命令仍然可配置。 - **运行时中立的设计。** 驱动内核拥有命令调度、运行时事件发出、提供者生命周期、权限流和诊断。主机拥有凭证、文件、技能、MCP、策略、日志记录、持久性和传输， 通过明确定义的 host 端口。库是安全的导入，并且从不自行启动进程运行器。 - **实验性的类似 CMA 的适配器。** 库导出一个 HTTP 处理程序、薄客户端、投影和用于 CMA 形状路由和事件的内存存储。这是一个预览版，不受支持：它没有兼容性、一致性、完整性或稳定性保证，Mosoo 也不将其作为生产 API 安装。 - **类型化的公共条目。** 每个公共条目都附带一个匹配的声明文件，位于 `dist/types` 下，软件包携带 **无** `@mosoo/*` 运行时依赖项 — 它是自包含且可移植的。 ## 软件包条目 - 命令 `agent-driver`：Bun 进程运行器，构建到 `dist/driver.mjs`；在 Mosoo 中，它使用私有启动负载并拨号 API 控制套接字。 - 软件包根目录 `agent-driver`：驱动内核、提供者注册表、主机端口、命令、事件、诊断、CMA 存储和 CMA 投影导出。 - `agent-driver/boot`：进程启动负载、协议版本、启动环境名称和主机快照合约。 - `agent-driver/runtime`：运行时中立的运行时、传输和本地恢复合约。 - `agent-driver/paths`：主机集成共享的沙箱路径常量和路径规范化助手。 - `agent-driver/events`：规范的驱动事件信封合约。 - `agent-driver/orpc`：驱动程序到 `DriverInstance` 的 ORPC 线输入/输出合约。 - `agent-driver/cma-http`：实验性的、非支持的、类似 CMA 的 HTTP 处理程序。 - `agent-driver/cma-sdk`：实验性的、非支持的、类似 CMA 的客户端。 每个公共条目都有一个匹配的声明文件，位于 `dist/types` 下。 ## 快速入门 `agent-driver` 针对 [Bun](https://bun.sh)。它当前不可从 npm 获得；从此存储库检出，安装依赖项并运行测试套件： ```sh bun install --frozen-lockfile bun test ``` 最小的库示例将实验性的类似 CMA 的 HTTP 处理程序连接到内存存储，并使用捆绑的客户端与其通信 — 无需网络套接字。 将以下内容放入 `tests/quickstart.test.ts` 并运行 `bun test tests/quickstart.test.ts`： ```ts import { expect, test } from "bun:test"; import { createCmaMemoryStore } from "agent-driver"; import { createCmaHttpHandler } from "agent-driver/cma-http"; import { createCmaSdkClient } from "agent-driver/cma-sdk"; test("在 CMA 接口上创建代理、环境和会话", async () => { // 1. 内存存储代替主机的持久性端口。 const store = createCmaMemoryStore(); // 2. CMA 形状的 HTTP 处理程序将支持的预览请求转换为驱动程序 // 命令。 dispatchDriverCommand 是主机将命令 // 交给沙箱托管的驱动内核的地方。 const handler = createCmaHttpHandler({ store, dispatchDriverCommand: async () => undefined, }); // 3. 客户端通过 fetch 直接与处理程序通信 — 将 // baseUrl 指向显式嵌入此预览的服务器。 默认 beta 头 // （anthropic-beta：managed-agents-2026-04-01）会自动发送。 const client = createCmaSdkClient({ baseUrl: "https://driver.local", fetch: async (input, init) => handler(new Request(input, init)), }); const environment = await client.createEnvironment({ id: "env-1", name: "Main" }); const agent = await client.createAgent({ id: "agent-1", name: "Reviewer" }); const session = await client.createSession({ id: "session-1", agentId: agent.id, environmentId: environment.id, }); expect(session).toMatchObject({ id: "session-1", agentId: "agent-1" }); }); ``` 此操作练习了实现的 `/v1/environments`、`/v1/agents` 和 `/v1/sessions` 预览路由。 它不建立 CMA 兼容性，Mosoo 也不安装此处理程序。 嵌入式应用程序必须提供自己的授权、持久存储、网络服务器和驱动程序命令调度程序。 ### Mosoo 中如何使用它 `agent-driver` 是 **Mosoo 代理运行时的运行时内核**。 当 Mosoo 启动代理会话时，它写入私有启动负载，在沙箱中启动此驱动程序，并等待匹配的 `DriverInstance` 持久对象。 驱动程序拨出，选择提供者后端，驱动会话，并通过 ORPC 发送其运行时中立的驱动程序协议。 主机通过主机端口提供凭证、文件、技能、MCP、策略和持久性。 [Mosoo](https://github.com/langgenius/mosoo) 和此驱动程序仓库已经公开。 Mosoo 通过 [公共线程 API](https://github.com/langgenius/mosoo/blob/main/docs/prd/public-thread-api-surface.md) 在 `/api/v1` 下公开其生产客户端合同，而不是通过实验性的类似 CMA 的适配器。 `agent-driver` npm 软件包尚未发布。 ## 命令 ```sh bun install --frozen-lockfile bun run lint bun run tc bun run test bun run build bun run docker:build ``` `bun run docker:build` 生成一个本地 `agent-driver:local` 镜像，并在镜像 `PATH` 上安装 `dist/driver.mjs` 作为 `agent-driver`。 ## 边界 - 驱动内核拥有命令调度、运行时事件发出、提供者生命周期、权限流、诊断和主机端口合约。 - 主机应用程序拥有凭证、文件、技能、MCP、策略、日志记录、持久性和传输实现。 - 提供者后端仅依赖于驱动程序合约和主机端口。 - 库根目录安全可导入，并且不得启动进程运行器。 - 软件包不得在运行时依赖 Mosoo 工作区软件包。 - Mosoo 控制流量使用外出 ORPC WebSocket 到 `DriverInstance`；驱动程序不公开沙箱本地控制监听器。 - CMA 形状的导出是实验性的库适配器，而不是 Mosoo 生产端点或兼容性保证。 ## 检查 - `bun run lint` - `bun run tc` - `bun run test` - `bun run build` - `bun run docker:build` - `package.json` 中没有 `@mosoo/*` 运行时依赖项 - 公共条目包括类型化导出 - 实时提供者烟雾测试由环境凭证控制 ## 许可证 在 [Apache License 2.0](./LICENSE.txt) 下许可。