chivgent 0.6.0

package/README.zh-CN.md

@@ -0,0 +1,345 @@
+# chivgent
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+> 一个小巧、易读的 Coding Agent CLI，用来理解 Agent Harness 的真实工作原理。
+
+![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20-339933?logo=nodedotjs&logoColor=white)
+![TypeScript](https://img.shields.io/badge/TypeScript-ESM-3178C6?logo=typescript&logoColor=white)
+[![CI](https://github.com/chivopic/chivgent/actions/workflows/ci.yml/badge.svg)](https://github.com/chivopic/chivgent/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+![Status](https://img.shields.io/badge/status-MVP-orange)
+
+`chivgent` 将 Provider 无关的 Agent Loop 与 LLM API、工具和工作区边界连接起来。
+当前 MVP 可以先发现文件、搜索源码并分段读取内容，再使用 OpenAI、DeepSeek 或
+任意兼容 Chat Completions 的 API 回答代码问题。
+
+这个项目刻意保持精简：先让 Tool Calling、Conversation State、Provider Adapter
+和循环终止条件容易理解，再逐步加入成熟 Agent Harness 所需的工程复杂度。
+
+## 功能
+
+- 完整的多轮 Agent Loop：模型 -> Tool Call -> Tool Result -> 模型。
+- Provider 无关的运行时消息和工具契约。
+- 通过 Responses API 支持 OpenAI。
+- 通过通用 OpenAI-compatible Chat Completions 客户端支持 DeepSeek。
+- 无需修改代码即可配置自定义 OpenAI-compatible API。
+- 既可以进入带斜杠命令的交互式会话，也可以单次提问后退出。
+- Session 以 JSON Lines 持久化，可以在之后的进程中恢复。
+- 提供 `--json` 事件流，便于脚本和其他前端消费。
+- 基于类型化运行时事件流的流式输出。
+- 可中断的运行：Ctrl+C 结束当前运行，且不会丢失已产生的 transcript。
+- Provider 调用具备单次超时和有上限的指数退避重试。
+- 通过 `list_files` 和字面量 `search_text` 确定性地发现项目内容。
+- 支持带续读提示的分段 `read_file`，所有工具结果都有容量上限。
+- 安全、只读的工作区访问，阻止路径穿越和符号链接逃逸。
+- 支持根 `.gitignore`、生成目录和敏感路径过滤。
+- 工具参数验证、明确的工具错误和最多八轮的安全限制。
+- 可打包安装的 Node.js CLI，不依赖 Agent 框架。
+- 默认测试不调用真实 API，不消耗模型额度。
+
+## 快速开始
+
+### 环境要求
+
+- Node.js 20 或更高版本
+- npm
+- OpenAI、DeepSeek 或其他兼容供应商的 API Key
+
+### 从 npm 安装
+
+```bash
+npm install -g chivgent
+chivgent --version
+```
+
+如果希望安装当前源码版本：
+
+```bash
+git clone https://github.com/chivopic/chivgent.git
+cd chivgent
+npm install
+npm run build
+npm install -g .
+```
+
+### 分析一个项目
+
+进入你希望 Agent 分析的项目目录，然后运行 `chivgent`。
+
+使用 OpenAI：
+
+```bash
+export OPENAI_API_KEY="your-api-key"
+chivgent "src/agent.ts 是做什么的？"
+```
+
+使用 DeepSeek：
+
+```bash
+export DEEPSEEK_API_KEY="your-api-key"
+chivgent --provider deepseek "解释 src/ 目录的架构"
+```
+
+使用任意 OpenAI-compatible Chat Completions API：
+
+```bash
+export OPENAI_API_KEY="your-provider-api-key"
+export OPENAI_BASE_URL="https://api.vendor.example/v1"
+export OPENAI_MODEL="vendor-model"
+
+chivgent --provider openai-compatible "解释 src/ 目录的架构"
+```
+
+不带问题直接运行 `chivgent` 会进入交互式会话：
+
+```bash
+chivgent
+› src/agent.ts 在做什么？
+› 这个循环在哪里测试？
+› /exit
+```
+
+会话会跨多轮保留上下文，因此追问不需要重复之前的信息。之后可以用
+`chivgent --continue`（或 `chivgent --resume <id>`）恢复；`chivgent --sessions`
+可以列出已记录的会话。
+
+答案会随模型生成实时写入 stdout，因此 stdout 仍然可以直接管道使用。工具活动、
+重试和运行状态写入 stderr；Provider 错误会返回非零退出码。使用 `--no-stream`
+可改为一次性输出完整答案，`--quiet` 可隐藏工具活动。
+
+## CLI 参考
+
+```text
+chivgent [选项] "问题"            回答一次后退出
+chivgent [选项]                   进入交互式会话
+
+选项：
+  --provider NAME  openai、deepseek 或 openai-compatible（默认：openai）
+  --model MODEL    覆盖 Provider 模型
+  --max-turns N    工具调用轮次上限（默认：8）
+  --no-stream      关闭流式输出，等待完整答案
+  -q, --quiet      不在 stderr 打印工具活动
+  --json           以 JSON Lines 输出整次运行，而不是渲染文本
+  -c, --continue   恢复当前工作区最近的一次 Session
+  --resume ID      恢复指定 Session
+  --sessions       列出已记录的 Session 并退出
+  --no-session     不记录本次运行
+  -h, --help       显示帮助
+  -v, --version    显示版本
+```
+
+交互式会话中 `/help` 会列出全部斜杠命令：`/session`、`/tools`、`/clear` 和
+`/exit`。Ctrl+C 只中断当前回答，不会退出会话；Ctrl+D 才会离开。
+
+退出码：`0` 正常回答，`1` 配置或 Provider 失败，`2` 达到轮次上限，`130` 被
+Ctrl+C 中断。
+
+### Provider 配置
+
+| Provider | API Key | 模型环境变量 | 默认模型 | API 形式 |
+| --- | --- | --- | --- | --- |
+| OpenAI | `OPENAI_API_KEY` | `OPENAI_MODEL` | `gpt-5.6` | Responses API |
+| DeepSeek | `DEEPSEEK_API_KEY` | `DEEPSEEK_MODEL` | `deepseek-v4-flash` | OpenAI-compatible Chat Completions |
+| 自定义兼容供应商 | `OPENAI_API_KEY` | `OPENAI_MODEL` | 必填 | OpenAI-compatible Chat Completions |
+
+显式传入的 `--model` 优先于 Provider 对应的模型环境变量。自定义兼容供应商还必须
+配置 `OPENAI_BASE_URL`。Session 记录在 `CHIVGENT_HOME`（默认 `~/.chivgent`）下。
+
+```bash
+chivgent --provider openai --model gpt-5.6 "解释 package.json"
+chivgent --provider deepseek --model deepseek-v4-pro "解释 package.json"
+chivgent --provider openai-compatible --model vendor-model "解释 package.json"
+```
+
+## 架构
+
+```text
+                                  +-> OpenAI Responses API
+用户 -> CLI -> Agent -> LLMClient |
+                 |                +-> OpenAI-compatible Chat -> DeepSeek / 自定义
+                 |
+                 +-> Tool Registry -> list_files / search_text / read_file -> Workspace
+```
+
+Agent Runtime 拥有自己的消息模型。Provider 特有的数据结构只在 `LLMClient` 边界
+进行转换：
+
+```text
+Agent Message[] -> Provider Adapter -> Provider Request
+                                      <- Provider Response
+AssistantMessage <- Normalized Result
+```
+
+因此 Agent、工具和 CLI 不会依赖任何单一供应商的消息格式。
+
+### 运行时事件
+
+Agent Loop 自己不打印任何内容，而是通过类型化的事件流对外汇报。一次运行会产生：
+
+```text
+agent_start
+  turn_start -> message_start -> message_update* -> message_end
+    tool_execution_start -> tool_execution_end   (每个 Tool Call 一次)
+  turn_end
+  ...
+agent_end (completed | max_turns | aborted | error)
+```
+
+`message_update` 只携带增量，不携带累计快照，因此事件流的体积与答案长度保持线性
+关系。事件都是可结构化克隆的，且每个监听者拿到的是副本，渲染层无法修改
+transcript。`src/render.ts` 中的 CLI 渲染器只是其中一个消费者，日志、JSON 流或
+TUI 同样可以消费。
+
+`LLMClient.stream` 是可选的。Provider 未实现时，Agent 会退回 `complete`，事件序列
+不变，只是没有增量事件。
+
+### OpenAI-compatible 供应商
+
+兼容供应商可以通过修改 `baseURL`、凭据和模型名称，复用官方 `openai` npm 包。
+CLI 用户无需修改代码：
+
+```bash
+export OPENAI_API_KEY="your-provider-api-key"
+export OPENAI_BASE_URL="https://api.vendor.example/v1"
+export OPENAI_MODEL="vendor-model"
+
+chivgent --provider openai-compatible "src/agent.ts 是做什么的？"
+```
+
+`OPENAI_BASE_URL` 必须指向供应商的 OpenAI-compatible API 根地址。供应商至少需要
+实现 `POST /chat/completions` 和 Function Tool Calling。
+
+如果要在源码中增加一个具名 Provider，可以复用相同的 Adapter：
+
+```ts
+const client = new OpenAICompatibleChatClient({
+  apiKey: process.env.VENDOR_API_KEY!,
+  baseURL: "https://api.vendor.example/v1",
+  model: "vendor-model",
+  continuationTag: "vendor-chat",
+});
+```
+
+`DeepSeekChatClient` 就是共享客户端之上的轻量配置包装器。兼容层还会把 DeepSeek
+的 `reasoning_content` 等 Provider 私有字段保存在不透明的 continuation state 中。
+
+修改 `baseURL` 不代表所有能力都能完全兼容。不同供应商的模型名称、鉴权方式、
+工具 Schema、Strict Mode、推理字段、流式事件和错误结构都可能不同。供应商差异
+应保留在轻量 Provider Adapter 内，而不是泄漏到 Agent Loop。
+
+## 项目结构
+
+```text
+src/
+  cli.ts                         CLI 入口与进程边界
+  cli-options.ts                 参数和 Provider 配置
+  agent.ts                       Agent Loop 与运行状态
+  events.ts                      运行时事件模型
+  render.ts                      运行时事件的终端渲染
+  llm.ts                         Provider 无关的 LLM 契约
+  retry.ts                       Provider 超时与重试装饰器
+  messages.ts                    运行时消息模型
+  session.ts                     会话状态与事件分发
+  session-store.ts               JSONL 会话日志与恢复
+  repl.ts                        交互式输入与斜杠命令
+  workspace.ts                   安全的本地工作区访问
+  providers/
+    openai.ts                    OpenAI Responses Adapter
+    openai-compatible-chat.ts    通用 Chat Completions Adapter
+    deepseek.ts                  DeepSeek 配置包装器
+  tools/
+    tool.ts                      Tool 契约
+    output.ts                    共享的 64 KiB 工具输出边界
+    list-files.ts                确定性的项目树发现工具
+    search-text.ts               有界的源码字面量搜索工具
+    read-file.ts                 分段文本读取工具
+tests/                           Provider、Agent Loop 和 Workspace 测试
+docs/                            架构与学习文档
+```
+
+## 开发
+
+```bash
+npm install
+npm run check
+npm test
+npm run build
+```
+
+运行完整的发布检查（包含 npm tarball dry run）：
+
+```bash
+npm run release:check
+```
+
+构建一个可以在本地安装的 tarball：
+
+```bash
+npm pack
+npm install -g ./chivgent-0.6.0.tgz
+```
+
+测试使用脚本化或 Mock LLM Client。真实 API Smoke Test 需要手工执行，因此默认
+测试不会消耗 API 额度。
+
+## 安全模型
+
+- API Key 只从环境变量读取，绝不能提交到仓库。
+- 自定义 `OPENAI_BASE_URL` 会收到配置的 API Key 和提示词，只能使用可信端点。
+- 当前所有工作区工具都是只读工具。
+- 文件路径必须位于当前工作区内。
+- Real Path 检查会阻止 `..` 路径穿越和符号链接逃逸。
+- 文件大小和二进制内容检查会限制不安全的读取。
+- 自动发现遵循根 `.gitignore` 和固定的生成目录忽略规则。
+- 所有工具统一禁止常见凭据、私钥和敏感配置路径。
+- 工具结果限制为 64 KiB，读取、扫描、深度和结果数量都有硬上限。
+- 工具输入是不可信数据，执行前必须验证。
+- Agent 会在有限的模型轮数后终止。
+- `~/.chivgent/sessions` 下的会话日志包含提问、回答和工具结果（含文件片段）。
+  在敏感项目中请使用 `--no-session`，并像对待项目本身一样对待该目录。
+- Session id 在拼接成文件路径前会先做校验。
+
+这是一个用于学习的 MVP，并不是经过加固的 Sandbox。在为它增加写文件或 Shell
+工具，并允许其访问敏感项目之前，请先审查代码和威胁模型。
+
+## 路线图
+
+- [x] 最小 Tool Calling Agent Loop
+- [x] 安全的 `read_file` 工具
+- [x] OpenAI 和 DeepSeek Provider
+- [x] 通用 OpenAI-compatible Chat Completions Adapter
+- [x] 自定义 OpenAI-compatible CLI Provider
+- [x] 项目发现工具：`list_files`、`search_text` 和分段 `read_file`
+- [x] 流式输出和运行时事件
+- [x] 持久化多轮 Session
+- [ ] Context Window 管理和压缩
+- [ ] 需要权限确认的 `write_file`、`edit_file` 和 Shell 工具
+- [ ] Provider Registry 和用户配置文件
+- [ ] TUI、Extensions、Telemetry 和 Evals
+
+## 文档
+
+- [Stage 1：Minimal Agent 设计](docs/stage-1-minimal-agent.md)
+- [DeepSeek Provider 设计](docs/deepseek-provider.md)
+- [Stage 2：Project Discovery 实现设计](docs/stage-2-project-discovery.md)
+- [Stage 3：Runtime Events 与流式输出设计](docs/stage-3-runtime-events.md)
+- [Stage 4：Session 与交互模式设计](docs/stage-4-sessions.md)
+- [发布流程](docs/releasing.md)
+
+## 参与贡献
+
+欢迎提交 Issue 和范围明确的 Pull Request。提交修改前请运行：
+
+```bash
+npm run check
+npm test
+npm run build
+```
+
+请将 Provider 特有的类型保留在 `src/providers/` 中，并确保核心 Agent Runtime
+不依赖供应商 SDK 的数据结构。
+
+## 许可证
+
+本项目使用 [MIT License](LICENSE)。

package/dist/agent.d.ts

@@ -0,0 +1,58 @@
+import { type AgentEventListener } from "./events.js";
+import { type LLMClient } from "./llm.js";
+import type { AssistantMessage, Message } from "./messages.js";
+import type { Tool } from "./tools/tool.js";
+import type { Workspace } from "./workspace.js";
+export interface AgentOptions {
+    readonly systemPrompt: string;
+    readonly maxTurns: number;
+    readonly llm: LLMClient;
+    readonly tools: readonly Tool[];
+    readonly workspace: Workspace;
+    /** Receives runtime events synchronously, in emission order. */
+    readonly onEvent?: AgentEventListener;
+    /** Use the Provider's streaming API when it offers one. Defaults to true. */
+    readonly streaming?: boolean;
+}
+export interface AgentRunOptions {
+    /** Cancels the run between turns, during a Provider call, and between tools. */
+    readonly signal?: AbortSignal;
+    /**
+     * Messages that precede this prompt. The Agent never mutates the array it is
+     * given; a session owns its transcript and passes a snapshot in.
+     */
+    readonly history?: readonly Message[];
+}
+export type AgentRunResult = {
+    readonly status: "completed";
+    readonly finalMessage: AssistantMessage;
+    readonly messages: readonly Message[];
+    readonly turnCount: number;
+} | {
+    readonly status: "max_turns" | "aborted";
+    readonly messages: readonly Message[];
+    readonly turnCount: number;
+};
+export declare class AgentProtocolError extends Error {
+    constructor(message: string);
+}
+export declare class Agent {
+    private readonly systemPrompt;
+    private readonly maxTurns;
+    private readonly llm;
+    private readonly registry;
+    private readonly toolDefinitions;
+    private readonly workspace;
+    private readonly onEvent?;
+    private readonly streaming;
+    constructor(options: AgentOptions);
+    get toolNames(): readonly string[];
+    run(userInput: string, options?: AgentRunOptions): Promise<AgentRunResult>;
+    private loop;
+    private requestAssistantMessage;
+    private assertUniqueToolCallIds;
+    private executeToolCall;
+    private emit;
+    private emitEnd;
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,kBAAkB,EAExB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAgB,KAAK,SAAS,EAAwB,MAAM,UAAU,CAAC;AAC9E,OAAO,KAAK,EACV,gBAAgB,EAChB,OAAO,EAGR,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,IAAI,EAA8B,MAAM,iBAAiB,CAAC;AACxE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,gEAAgE;IAChE,QAAQ,CAAC,OAAO,CAAC,EAAE,kBAAkB,CAAC;IACtC,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,eAAe;IAC9B,gFAAgF;IAChF,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;CACvC;AAED,MAAM,MAAM,cAAc,GACtB;IACE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,gBAAgB,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B,GACD;IACE,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B,CAAC;AASN,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAED,qBAAa,KAAK;IAChB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAY;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4B;IACrD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA4B;IAC5D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAqB;IAC9C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAU;IAEpC,YAAY,OAAO,EAAE,YAAY,EAmBhC;IAED,IAAI,SAAS,IAAI,SAAS,MAAM,EAAE,CAEjC;IAEK,GAAG,CACP,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,cAAc,CAAC,CAqCzB;YAEa,IAAI;YAuDJ,uBAAuB;IA2BrC,OAAO,CAAC,uBAAuB;YAcjB,eAAe;IA0D7B,OAAO,CAAC,IAAI;IAIZ,OAAO,CAAC,OAAO;CAahB"}

package/dist/agent.js

@@ -0,0 +1,281 @@
+import { emitEvent, } from "./events.js";
+import { isAbortError } from "./llm.js";
+export class AgentProtocolError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AgentProtocolError";
+    }
+}
+export class Agent {
+    systemPrompt;
+    maxTurns;
+    llm;
+    registry;
+    toolDefinitions;
+    workspace;
+    onEvent;
+    streaming;
+    constructor(options) {
+        if (!Number.isSafeInteger(options.maxTurns) || options.maxTurns <= 0) {
+            throw new TypeError("maxTurns must be a positive safe integer.");
+        }
+        this.systemPrompt = options.systemPrompt;
+        this.maxTurns = options.maxTurns;
+        this.llm = options.llm;
+        this.workspace = options.workspace;
+        this.registry = createToolRegistry(options.tools);
+        this.toolDefinitions = [...this.registry.values()].map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            inputSchema: structuredClone(tool.inputSchema),
+        }));
+        if (options.onEvent !== undefined) {
+            this.onEvent = options.onEvent;
+        }
+        this.streaming = options.streaming ?? true;
+    }
+    get toolNames() {
+        return [...this.registry.keys()];
+    }
+    async run(userInput, options = {}) {
+        if (userInput.trim().length === 0) {
+            throw new TypeError("User input must not be empty.");
+        }
+        const state = {
+            messages: [
+                ...structuredClone(options.history ?? []),
+                { role: "user", content: userInput },
+            ],
+            seenToolCallIds: new Set(),
+            turnCount: 0,
+        };
+        const signal = options.signal;
+        this.emit({
+            type: "agent_start",
+            prompt: userInput,
+            maxTurns: this.maxTurns,
+        });
+        try {
+            const result = await this.loop(state, signal);
+            this.emitEnd(result.status, state);
+            return result;
+        }
+        catch (error) {
+            if (isAbortError(error) || isAborted(signal)) {
+                this.emitEnd("aborted", state);
+                return abortedResult(state);
+            }
+            this.emitEnd("error", state, error instanceof Error ? error.message : "Unknown error");
+            throw error;
+        }
+    }
+    async loop(state, signal) {
+        while (state.turnCount < this.maxTurns) {
+            if (isAborted(signal)) {
+                return abortedResult(state);
+            }
+            state.turnCount += 1;
+            const turn = state.turnCount;
+            this.emit({ type: "turn_start", turn });
+            this.emit({ type: "message_start", turn });
+            const response = await this.requestAssistantMessage(state, turn, signal);
+            const assistant = validateAndCloneAssistantMessage(response.message);
+            this.assertUniqueToolCallIds(assistant.toolCalls, state.seenToolCallIds);
+            state.messages.push(assistant);
+            state.continuation = response.continuation;
+            this.emit({ type: "message_end", turn, message: assistant });
+            if (assistant.toolCalls.length === 0) {
+                this.emit({
+                    type: "turn_end",
+                    turn,
+                    message: assistant,
+                    toolResults: [],
+                });
+                return {
+                    status: "completed",
+                    finalMessage: assistant,
+                    messages: snapshotMessages(state.messages),
+                    turnCount: state.turnCount,
+                };
+            }
+            const toolResults = [];
+            for (const toolCall of assistant.toolCalls) {
+                if (isAborted(signal)) {
+                    return abortedResult(state);
+                }
+                const result = await this.executeToolCall(toolCall, turn, signal);
+                toolResults.push(result);
+                state.messages.push(result);
+            }
+            this.emit({ type: "turn_end", turn, message: assistant, toolResults });
+        }
+        return {
+            status: "max_turns",
+            messages: snapshotMessages(state.messages),
+            turnCount: state.turnCount,
+        };
+    }
+    async requestAssistantMessage(state, turn, signal) {
+        const request = {
+            systemPrompt: this.systemPrompt,
+            messages: snapshotMessages(state.messages),
+            tools: this.toolDefinitions,
+            ...(state.continuation === undefined
+                ? {}
+                : { continuation: state.continuation }),
+            ...(signal === undefined ? {} : { signal }),
+        };
+        if (this.streaming && this.llm.stream !== undefined) {
+            return this.llm.stream(request, {
+                onTextDelta: (delta) => {
+                    if (delta.length > 0) {
+                        this.emit({ type: "message_update", turn, delta });
+                    }
+                },
+            });
+        }
+        return this.llm.complete(request);
+    }
+    assertUniqueToolCallIds(toolCalls, seenIds) {
+        for (const toolCall of toolCalls) {
+            if (seenIds.has(toolCall.id)) {
+                throw new AgentProtocolError(`Provider returned a duplicate tool call id: ${toolCall.id}`);
+            }
+            seenIds.add(toolCall.id);
+        }
+    }
+    async executeToolCall(toolCall, turn, signal) {
+        this.emit({
+            type: "tool_execution_start",
+            turn,
+            toolCallId: toolCall.id,
+            toolName: toolCall.name,
+            arguments: toolCall.arguments,
+        });
+        const tool = this.registry.get(toolCall.name);
+        let output;
+        if (tool === undefined) {
+            output = {
+                content: `Unknown tool: ${toolCall.name}`,
+                isError: true,
+            };
+        }
+        else {
+            try {
+                output = validateToolOutput(await tool.execute(toolCall.arguments, {
+                    workspace: this.workspace,
+                    ...(signal === undefined ? {} : { signal }),
+                }));
+            }
+            catch (error) {
+                if (isAbortError(error)) {
+                    throw error;
+                }
+                output = {
+                    content: `Tool execution failed: ${toolCall.name}`,
+                    isError: true,
+                };
+            }
+        }
+        this.emit({
+            type: "tool_execution_end",
+            turn,
+            toolCallId: toolCall.id,
+            toolName: toolCall.name,
+            content: output.content,
+            isError: output.isError,
+        });
+        return {
+            role: "tool",
+            toolCallId: toolCall.id,
+            toolName: toolCall.name,
+            content: output.content,
+            isError: output.isError,
+        };
+    }
+    emit(event) {
+        emitEvent(this.onEvent, event);
+    }
+    emitEnd(status, state, error) {
+        this.emit({
+            type: "agent_end",
+            status,
+            turnCount: state.turnCount,
+            messages: snapshotMessages(state.messages),
+            ...(error === undefined ? {} : { error }),
+        });
+    }
+}
+/** Kept as a call so narrowing never hides a signal that aborts mid-run. */
+function isAborted(signal) {
+    return signal !== undefined && signal.aborted;
+}
+function abortedResult(state) {
+    return {
+        status: "aborted",
+        messages: snapshotMessages(state.messages),
+        turnCount: state.turnCount,
+    };
+}
+function createToolRegistry(tools) {
+    const registry = new Map();
+    for (const tool of tools) {
+        if (tool.name.length === 0) {
+            throw new TypeError("Tool names must not be empty.");
+        }
+        if (registry.has(tool.name)) {
+            throw new TypeError(`Duplicate tool name: ${tool.name}`);
+        }
+        registry.set(tool.name, tool);
+    }
+    return registry;
+}
+function validateAndCloneAssistantMessage(value) {
+    if (typeof value !== "object" || value === null) {
+        throw new AgentProtocolError("Provider returned an invalid assistant message.");
+    }
+    const candidate = value;
+    if (candidate.role !== "assistant" ||
+        typeof candidate.content !== "string" ||
+        !Array.isArray(candidate.toolCalls)) {
+        throw new AgentProtocolError("Provider returned an invalid assistant message.");
+    }
+    const toolCalls = candidate.toolCalls.map((toolCall) => {
+        if (typeof toolCall !== "object" ||
+            toolCall === null ||
+            typeof toolCall.id !== "string" ||
+            toolCall.id.length === 0 ||
+            typeof toolCall.name !== "string" ||
+            toolCall.name.length === 0) {
+            throw new AgentProtocolError("Provider returned an invalid tool call.");
+        }
+        return {
+            id: toolCall.id,
+            name: toolCall.name,
+            arguments: structuredClone(toolCall.arguments),
+        };
+    });
+    if (candidate.content.length === 0 && toolCalls.length === 0) {
+        throw new AgentProtocolError("Provider returned an assistant message with no text or tool calls.");
+    }
+    return {
+        role: "assistant",
+        content: candidate.content,
+        toolCalls,
+    };
+}
+function validateToolOutput(value) {
+    if (typeof value !== "object" ||
+        value === null ||
+        !("content" in value) ||
+        !("isError" in value) ||
+        typeof value.content !== "string" ||
+        typeof value.isError !== "boolean") {
+        throw new TypeError("Tool returned an invalid output.");
+    }
+    return { content: value.content, isError: value.isError };
+}
+function snapshotMessages(messages) {
+    return structuredClone(messages);
+}
+//# sourceMappingURL=agent.js.map