agenttaskflow 0.0.1 → 0.4.2

package/README.md

@@ -1,5 +1,264 @@
-# agenttaskflow
+# AgentTaskFlow
 
-Persistent task workflows inside your existing Claude Code or Codex session.
+## atf 命令行
 
-This package name is reserved. The first release is coming soon.
+包名是 `agenttaskflow`，命令名是 **`atf`**。npm 上的 `atf` 已是另一个 CSS 工具，不能用 `npm install -g atf` 安装本项目。
+
+本地安装当前开发版本（Node.js 22.15+）：
+
+```bash
+cd /Users/maple/workbench/agenttaskflow
+nvm use
+npm run build
+npm install -g .
+atf examples/simple.ts
+atf examples/multi-fields.ts
+atf examples/smoke.ts --command cxh --rounds 5
+```
+
+从 npm 安装：`npm install -g agenttaskflow`（需要 Node.js 22.15+）。
+
+`atf 文件.ts` 执行普通 TS/JS 文件，保留当前工作目录，文件名之后的参数原样交给流程。支持相对 import、顶层 await 和导出的 `main(args)` 入口；`main` 若存在会在文件加载完成后调用一次。直接调用 `flow(...)` 的现有脚本无需改写。不做类型检查，需要时运行项目自己的 `tsc`。执行器通过 esbuild 编译 TS，没有新造流程语言。
+
+独立文件可以直接 `import { flow } from 'agenttaskflow'`；优先使用项目本地依赖，找不到时回退到 atf 安装中的 AgentTaskFlow 和 Zod。其它业务依赖仍由项目正常安装。`atf --help` 查看用法，`atf --version` 查看版本。
+
+用普通 TypeScript 脚本控制 Codex 和 Claude Code。**没有 DSL、没有 `.flow` 文件、没有自定义语法。默认同步 API 不需要 `async/await`。**
+
+`step()` 等当前步骤完成后返回结果。一次 flow 只启动一个 CLI 进程，循环、分支和格式补答都复用它。终端按顺序显示：**当前步骤 → 实际输入 → agent 实时输出 → 完成/失败**。
+
+```ts
+import { flow } from 'agenttaskflow';
+
+flow('cxh', step => {
+  // 先生成方案。
+  step('设计一个本地待办工具，只给方案，不修改文件。');
+
+  // 审查通过才继续，最多三轮。
+  for (let i = 0; i < 3; i++) {
+    if (step.check('方案是否满足全部要求？')) break;
+    if (i === 2) throw new Error('三轮后仍未通过');
+    step('根据审查意见修订方案');
+  }
+
+  // 汇总已经通过审查的方案。
+  step('总结最终方案');
+});
+```
+
+不需要声明类型、schema、async/await，也不用手动启动和关闭。步骤名称自动取提示词第一行。完整示例见 `examples/simple.ts`，在项目目录执行 `npm run simple`。
+
+需要一次返回多个字段时，运行 `npm run multi-fields`（使用 cxh）。`examples/multi-fields.ts` 演示通过 `step.data` 获取 `passed`、`score`、`problems`、`suggestion` 四个字段，打印结果并按审查意见修订，最多三轮。提示词直接写在示例文件中。
+
+更多可运行流程位于 `test/`，说明见 `test/README.md`。执行 `npm run flows -- --list` 列出流程，`npm run flows -- branches loop` 测试指定流程，`npm run flows -- all` 依次运行全部六个真实 agent 测试。
+
+| 调用 | 返回值 |
+| --- | --- |
+| `step('执行任务')` | 回答文本 |
+| `step.check('是否满足要求？')` | `true` / `false` |
+| `step.choose('评估风险', ['low', 'high'])` | 选项之一 |
+| `step.data('提取结果', schema)` | 自定义结构化结果 |
+
+`check` 和 `choose` 自动要求结构化输出、校验并在格式错误时提示补答。它们返回模型的判断；涉及文件、测试等可核实事实时，还应由脚本验证实际证据。配置 Claude Code 使用 `flow({ provider: 'claude', command: 'claude' }, step => { /* 流程 */ })`。
+
+## 直接运行
+
+需要 Node.js 22+，以及已经安装、登录的 Codex 或 Claude Code CLI。
+
+```bash
+cd /Users/maple/workbench/agenttaskflow
+nvm use
+npm run smoke -- --provider codex --command cxh --rounds 5
+```
+
+等价于直接执行普通 TypeScript：
+
+```bash
+npx tsx examples/smoke.ts --provider codex --command cxh --rounds 5
+```
+
+Claude Code：
+
+```bash
+npm run smoke -- --provider claude --command claude --rounds 5
+```
+
+本地依赖和构建产物已准备好。新检出环境执行 `npm install && npm run build`。
+
+示例先交给 agent 一个随机标记，然后五次回忆。后续输入不再携带标记，脚本检查标记、轮数和 PID。每一轮会调用真实模型，但不要求 agent 读写业务文件。
+
+首次启动 `cxh` 仍可能花时间：包装脚本会预热后端，本机 Node 加载也可能较慢。**默认只预热一次，不会每一步重来。** 示例每步超时默认 600 秒，可用 `--timeout 600` 调整；每 15 秒显示等待状态。若已确认后端就绪，可以使用包装脚本自己的 `CXH_NO_WARM=1` 开关，这不等于修复后端问题。
+
+## 需要更多控制时
+
+需要自定义步骤名、详细结果或 checkpoint 时，使用 `withAgent`。它与 `flow` 使用同一套会话和执行能力：
+
+```ts
+import { z } from 'zod';
+import { withAgent } from 'agenttaskflow';
+
+const REVIEW = `审查当前方案。返回 verdict（pass 或 revise）和 reason。`;
+const REVISE = `根据上一轮审查意见修订方案，并报告真实修改。`;
+const Review = z.strictObject({
+  verdict: z.enum(['pass', 'revise']),
+  reason: z.string(),
+});
+
+withAgent({ command: 'cxh' }, agent => {
+  // 先生成方案，让后续审查使用同一个上下文。
+  agent.run('设计一个本地待办工具，只给方案，不修改文件。', { name: '生成方案' });
+
+  // 审查通过就结束；否则修订，最多三轮。
+  for (let round = 1; round <= 3; round++) {
+    const result = agent.run(REVIEW, { name: `审查 ${round}`, schema: Review });
+    if (result.verdict === 'pass') break;
+    if (round === 3) throw new Error('三轮后仍未通过');
+    agent.run(REVISE, { name: `修订 ${round}` });
+  }
+});
+```
+
+`withAgent` 在正常结束或抛错后关闭进程。也可以手动管理：
+
+```ts
+import { Agent } from 'agenttaskflow';
+
+const agent = new Agent({ command: 'cxh' });
+try {
+  const answer = agent.run('说明你的任务', { name: '开始' });
+  console.log(answer); // string，不是 Promise
+} finally {
+  agent.close();
+}
+```
+
+业务流程由 TypeScript 的 `if/else`、`for/while`、函数、`try/catch`、`import` 控制，不使用 `next` 变量模拟 goto。
+
+**提示词直接写在 `.ts` 文件中的字符串常量或函数里。共享内容放到公共 `.ts` 模块，用正常 import 复用。不要把各种文字拆成一堆小文本文件，不要让 agent 每一步去读提示词文件。** 主流程每个阶段前加一句说明目的的注释。
+
+## 命令和配置
+
+```ts
+new Agent({ provider: 'codex', command: 'cxh' });
+new Agent({ provider: 'codex', command: ['/path/to/cx', 'fixed-argument'] });
+new Agent({ provider: 'claude', command: 'claude', cwd: '/path/to/project' });
+```
+
+`provider` 是协议，`command` 是可执行命令或 argv 数组。不会从 `cxh` 名字猜测协议，也不会把字符串当 shell 代码执行。alias/function 需要用户提供可执行包装脚本，通过 `"$@"` 原样转发参数。
+
+示例命令行的固定参数用重复的 `--command-arg VALUE` 传入。一般 `cxh` 不需要额外参数。
+
+| 配置 | 默认值 | 作用 |
+| --- | --- | --- |
+| `provider` | `codex` | `codex` 或 `claude` |
+| `command` | provider 对应名称 | 自定义命令或 argv |
+| `cwd` | 当前目录 | agent 工作目录 |
+| `timeoutMs` | `3600000` | 每步总超时，包含补答；示例设为 600000 |
+| `idleTimeoutMs` | 不启用 | stdout/stderr 无新输出超时 |
+| `progressIntervalMs` | `15000` | 等待提示间隔，设 null 关闭 |
+| `maxCorrections` | `2` | 格式不合格时最多补答次数 |
+| `nativeSchema` | `false` | 显式启用时向 Codex 发送原生 outputSchema；默认只约束最终回答并在本地校验，避免兼容后端限制工具调用 |
+| `display` | `new Console()` | 设 false 关闭终端展示 |
+| `onEvent` | 无 | 接收事件的同步回调 |
+| `extraArgs` | `[]` | 模型等 CLI 选项；会话和协议参数由库管理 |
+| `env` | `{}` | 合并到子进程环境的显式变量 |
+| `runId` | 自动生成 | 显式恢复同一逻辑运行 |
+| `workflowVersion` | `1` | 流程版本，修改流程时递增 |
+| `stateDir` | `<cwd>/.agenttaskflow` | 状态与日志目录 |
+| `sessionId` | 无 | 首次打开时绑定已有外部会话 |
+
+调用 `agent.run(prompt, { name, schema })`。不提供 schema 就返回字符串；提供 Zod schema 后返回其推导出的类型。建议使用 `z.strictObject`、枚举和明确字段。`z.number()` 不会把数字字符串当数字，但用户显式使用 `z.coerce` 时遵循该 schema 的规则。
+
+## 常驻会话与结果校验
+
+Codex 只启动一次 `app-server`，初始化并创建/续接一个 thread，再逐轮发送 `turn/start`。Claude Code 只启动一次双向 `stream-json` 进程，持续发送 user 消息。`agent.pid` 在多步之间保持不变。
+
+Codex 的 schema 随轮次变化。Claude 常驻模式用每一步的 prompt 约束格式，在本地验证，避免进程级固定 schema 限制不同步骤。即使 `nativeSchema: false`，仍发送 prompt 格式要求并本地校验。
+
+正常完成但输出不符合 schema 时，在**同一进程、同一会话**发送补答 prompt，明确不要重复已完成操作；补答次数耗尽后抛出 `ResultValidationError`。自定义 Zod refinement 在调用方执行，也能触发补答。schema 必须可以转换为 JSON Schema；异步 refinement 请使用适合的异步业务逻辑，不在默认同步 API 中执行。
+
+进程失败、通信异常或超时不会自动重启或重发任务。完成依赖当前轮次的明确完成事件，不等待进程退出，也不靠“几秒没有输出”猜测。Codex 过滤 thread/turn ID，防止旧轮次的延迟事件成为新答案。
+
+CLI 的既有权限设置仍然生效。库不主动添加跳过权限检查的参数。若 CLI 要求宿主批准工具或回答其他交互请求，本版会拒绝未经批准的动作并报错，不静默授权。
+
+## 同步 API 为什么还能实时显示
+
+流程线程在 `run()` 中等待，独立工作线程继续处理 agent 的输入输出。事件会在等待期间交给调用方展示，故不需要流程作者写 async/await。默认 Console 使用直接写入终端的方式，隐藏的协议事件不会把流式文字切成多行。
+
+这不会把所有 JavaScript API 变成同步 API：你自己调用 `fetch()` 等仍应遵循它们的接口。默认同步方式适合独立的顺序工作流；Web 服务、GUI、同一主线程需要同时处理其他工作时使用可选异步 API：
+
+```ts
+import { withAsyncAgent } from 'agenttaskflow';
+
+await withAsyncAgent({ command: 'cxh' }, async agent => {
+  const answer = await agent.run('hello');
+});
+```
+
+同步事件回调不能重新调用当前 Agent 方法，否则会形成嵌套等待。回调请保持简短。显示回调异常会在当前请求处理结束后抛出；不要把显示回调当作任务取消接口。异步 API 可传 `AbortSignal`。
+
+`close()` 会关闭连接并清理进程。macOS/Linux 有独立生命周期监视进程，工作流被 Ctrl+C 或意外退出时清理对应 agent 进程组。Windows 未验证，仅直接子进程清理，不保证完整后代清理。
+
+同步模式下普通主线程 timer/Promise 回调不会在阻塞等待中执行；进程通信、超时和锁的心跳在工作线程运行。不要安装一个依赖主线程继续执行才能生效的 SIGINT 处理器来代替默认 Ctrl+C。
+
+## 显式 checkpoint
+
+```ts
+withAgent({ command: 'cxh', runId: 'research-001', workflowVersion: 'v1' }, agent => {
+  const inputs = { topic: 'example', promptVersion: 1 };
+  let state = agent.loadCheckpoint<{ answer: string }>('outline', inputs);
+  if (!state) {
+    const answer = agent.run('生成提纲', { name: '提纲' });
+    state = { answer };
+    agent.saveCheckpoint('outline', state, inputs);
+  }
+  console.log(state.answer);
+});
+```
+
+同一个 runId 自动读取保存的会话 ID。工作目录、命令、provider、显式环境、额外参数或流程版本变化时，拒绝复用旧状态；checkpoint 输入变化也会拒绝复用。
+
+**不恢复 TypeScript 的调用栈，不自动跳过任何 run，不自动重放任务。** 恢复位置由普通 TypeScript 判断。中断前外部操作可能已完成，应先检查产物再决定重做。
+
+同一运行使用跨进程锁，正常 close 释放；进程崩溃留下的锁在停止心跳至少 30 秒后才可被下一次调用识别为过期。不要手动删除仍在使用的锁。不同 run 可以使用不同 agent 并发，不能主动操纵同一个外部 session。
+
+## 日志与排错
+
+交互终端中，步骤标题为紫色粗体，输入为青色并带边框，agent 回答为绿色，运行状态淡化显示，警告为黄色，失败为红色。重定向到文件时默认不带颜色；设置 `NO_COLOR=1` 可禁用，或通过 `new Console({ color: false })` 关闭。
+
+```ts
+import { Console } from 'agenttaskflow';
+new Agent({ command: 'cxh', display: new Console({ showInputs: false }) });
+```
+
+默认 `.agenttaskflow/<runId>/`：
+
+```text
+state.json                    配置指纹、会话 ID、checkpoint
+steps/<stepId>/status.json     步骤状态、结果或错误
+steps/<stepId>/events.jsonl    原始事件与规范化事件、时间戳
+steps/<stepId>/0.input.txt    实际发送的输入；补答递增编号
+steps/<stepId>/0.output.txt   当前回答
+steps/<stepId>/schema.json    结果 schema（如有）
+```
+
+进程突然退出可能留下 `running` 记录，它不证明任务还在运行，也不证明未产生副作用。需要结合 CLI/产物核实。
+
+错误导出：`AgentTaskFlowError`、`AgentProcessError`、`ProtocolError`、`AgentTimeoutError`、`ResultValidationError`、`StateError`、`CancelledError`。
+
+日志含提示词和工具输出，可能包含业务数据；不要提交运行目录。provider 自身的上下文窗口和压缩机制仍然有效，不保证无限记忆。
+
+## 开发和归档
+
+```bash
+npm run check
+npm test
+npm pack --dry-run
+```
+
+- `src/`：TypeScript 库。
+- `examples/`：普通 TypeScript 流程，无自定义解释器。
+- `docs/workflow-authoring.md`：其他 agent 编写流程的指南。
+- `archive/python-v0.2.0/`：完整 Python 实现、测试、文档、环境和运行记录。
+- `archive/agentflow/`：更早的 DSL/终端版完整归档。
+
+旧版全部保留；当前 npm 发布包只包含 dist、示例和文档，不包含归档或运行数据。现有 `explore/docs/flow` 研究流程未迁移。

package/dist/agent.d.ts

@@ -0,0 +1,69 @@
+import { z } from 'zod';
+import { type Provider } from './connection.js';
+import { Console, type EventSink } from './events.js';
+export interface AgentOptions {
+    provider?: Provider;
+    command?: string | string[];
+    cwd?: string;
+    extraArgs?: string[];
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+    idleTimeoutMs?: number;
+    progressIntervalMs?: number | null;
+    maxCorrections?: number;
+    nativeSchema?: boolean;
+    display?: Console | EventSink | false;
+    onEvent?: EventSink;
+    runId?: string;
+    sessionId?: string;
+    stateDir?: string;
+    workflowVersion?: string;
+    signal?: AbortSignal;
+}
+export interface RunOptions<S extends z.ZodType = z.ZodType> {
+    name?: string;
+    schema?: S;
+    signal?: AbortSignal;
+}
+export interface ResultCodec {
+    jsonSchema: unknown;
+    validate(value: unknown): Promise<{
+        success: boolean;
+        data?: unknown;
+        issues?: unknown;
+    }>;
+}
+/** A single persistent agent session. Control flow belongs entirely to TypeScript. */
+export declare class Agent {
+    readonly runId: string;
+    readonly provider: Provider;
+    readonly cwd: string;
+    private options;
+    private state?;
+    private connection?;
+    private closed;
+    private tail;
+    private closePromise?;
+    private lifetime;
+    private command;
+    private display;
+    constructor(options?: AgentOptions);
+    get pid(): number | undefined;
+    get sessionId(): string | undefined;
+    private store;
+    saveCheckpoint(key: string, value: unknown, input: unknown): void;
+    loadCheckpoint<T = unknown>(key: string, input: unknown): T | undefined;
+    run<S extends z.ZodType>(prompt: string, options: RunOptions<S> & {
+        schema: S;
+    }): Promise<z.output<S>>;
+    run(prompt: string, options?: RunOptions & {
+        schema?: undefined;
+    }): Promise<string>;
+    /** Internal bridge for the synchronous facade; validators execute on its caller thread. */
+    runValidated(prompt: string, options: RunOptions, codec: ResultCodec): Promise<unknown>;
+    private execute;
+    close(): Promise<void>;
+    private shutdown;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+export declare function withAgent<T>(options: AgentOptions, workflow: (agent: Agent) => Promise<T>): Promise<T>;

package/dist/agent.js

@@ -0,0 +1,189 @@
+import { randomUUID } from 'node:crypto';
+import { appendFileSync, existsSync, mkdirSync, statSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { z } from 'zod';
+import { Connection } from './connection.js';
+import { AgentTimeoutError, CancelledError, ResultValidationError, StateError } from './errors.js';
+import { Console } from './events.js';
+import { State, writeJson } from './state.js';
+/** A single persistent agent session. Control flow belongs entirely to TypeScript. */
+export class Agent {
+    runId;
+    provider;
+    cwd;
+    options;
+    state;
+    connection;
+    closed = false;
+    tail = Promise.resolve();
+    closePromise;
+    lifetime = new AbortController();
+    command;
+    display;
+    constructor(options = {}) {
+        this.options = { ...options, extraArgs: [...(options.extraArgs ?? [])], env: { ...options.env } };
+        this.provider = options.provider ?? 'codex';
+        if (!['codex', 'claude'].includes(this.provider))
+            throw new TypeError('provider must be codex or claude');
+        this.command = typeof options.command === 'string' ? [options.command] : [...(options.command ?? [this.provider])];
+        if (!this.command.length || this.command.some(v => !v || typeof v !== 'string' || v.includes('\0'))) {
+            throw new TypeError('command must be an executable name or argv array');
+        }
+        const reserved = ['--resume', '--continue', '--last', '--session-id', '--ephemeral', '--no-session-persistence',
+            '--output-format', '--input-format', '--json', '--json-schema', '--output-schema', '--listen', '--stdio',
+            '--permission-prompt-tool', '--permission-prompts'];
+        if (options.extraArgs?.some(a => reserved.includes(a.split('=')[0])))
+            throw new TypeError('Session/protocol flags are managed by AgentTaskFlow');
+        for (const value of [options.timeoutMs, options.idleTimeoutMs, options.progressIntervalMs]) {
+            if (value != null && (!Number.isFinite(value) || value <= 0))
+                throw new TypeError('Timeout/interval must be positive');
+        }
+        if (options.maxCorrections != null && (!Number.isInteger(options.maxCorrections) || options.maxCorrections < 0)) {
+            throw new TypeError('maxCorrections must be a nonnegative integer');
+        }
+        this.cwd = resolve(options.cwd ?? '.');
+        if (!existsSync(this.cwd) || !statSync(this.cwd).isDirectory())
+            throw new TypeError(`Workspace missing: ${this.cwd}`);
+        this.runId = options.runId ?? randomUUID();
+        if (!/^[A-Za-z0-9_-]{1,128}$/.test(this.runId))
+            throw new TypeError('Invalid runId');
+        this.display = options.display === false ? false : typeof options.display === 'function' ? options.display : (options.display ?? new Console()).emit;
+    }
+    get pid() { return this.connection?.pid; }
+    get sessionId() { return this.state?.sessionId ?? this.options.sessionId; }
+    store() {
+        if (this.closed)
+            throw new StateError('Agent is closed');
+        if (!this.state) {
+            this.state = new State(resolve(this.options.stateDir ?? join(this.cwd, '.agenttaskflow')), this.runId, {
+                provider: this.provider, command: this.command, cwd: this.cwd, extraArgs: this.options.extraArgs,
+                env: this.options.env, workflowVersion: this.options.workflowVersion ?? '1',
+            });
+            try {
+                if (this.options.sessionId)
+                    this.state.bind(this.options.sessionId);
+            }
+            catch (error) {
+                this.state.close();
+                this.state = undefined;
+                throw error;
+            }
+        }
+        this.state.assertOwned();
+        return this.state;
+    }
+    saveCheckpoint(key, value, input) { this.store().saveCheckpoint(key, value, input); }
+    loadCheckpoint(key, input) { return this.store().loadCheckpoint(key, input); }
+    run(prompt, options = {}) {
+        if (typeof prompt !== 'string' || !prompt.trim())
+            return Promise.reject(new TypeError('prompt must be nonempty text'));
+        // One queue per Agent; independent Agents may run concurrently.
+        const task = this.tail.then(() => this.execute(prompt, options));
+        this.tail = task.then(() => { }, () => { });
+        return task;
+    }
+    /** Internal bridge for the synchronous facade; validators execute on its caller thread. */
+    runValidated(prompt, options, codec) {
+        const task = this.tail.then(() => this.execute(prompt, { ...options, codec }));
+        this.tail = task.then(() => { }, () => { });
+        return task;
+    }
+    async execute(prompt, options) {
+        const state = this.store();
+        const stepId = randomUUID(), name = options.name ?? 'step';
+        const directory = join(state.directory, 'steps', stepId);
+        mkdirSync(directory, { recursive: true, mode: 0o700 });
+        const statusFile = join(directory, 'status.json');
+        let attempt = 0;
+        const emit = event => {
+            const enriched = { ...event, timestamp: new Date().toISOString(), provider: this.provider,
+                runId: this.runId, stepId, stepName: name, attempt };
+            appendFileSync(join(directory, 'events.jsonl'), JSON.stringify(enriched) + '\n', { mode: 0o600 });
+            if (this.display)
+                this.display(enriched);
+            this.options.onEvent?.(enriched);
+        };
+        const record = (status, detail = {}) => writeJson(statusFile, { stepId, name, status, ...detail });
+        record('running');
+        const began = Date.now();
+        const timeoutMs = this.options.timeoutMs ?? 3_600_000;
+        const signals = [this.lifetime.signal, this.options.signal, options.signal].filter((s) => Boolean(s));
+        const signal = AbortSignal.any(signals);
+        try {
+            emit({ kind: 'step_started', text: name });
+            const schema = options.schema ? z.toJSONSchema(options.schema) : options.codec?.jsonSchema;
+            if (schema)
+                writeJson(join(directory, 'schema.json'), schema);
+            let input = prompt + (schema ? '\n\nExecute this step using tools as needed before answering. The JSON requirement applies only to your final answer, not to tool calls or intermediate work. After completing the work, return one JSON object matching the schema, without Markdown fences. Report actual results; do not invent success.\n' + JSON.stringify(schema) : '');
+            for (attempt = 0; attempt <= (this.options.maxCorrections ?? 2); attempt++) {
+                state.assertOwned();
+                writeFileSync(join(directory, `${attempt}.input.txt`), input, { mode: 0o600 });
+                emit({ kind: 'input', text: input });
+                this.connection ??= new Connection({ provider: this.provider, command: this.command, cwd: this.cwd,
+                    extraArgs: this.options.extraArgs ?? [], env: { ...process.env, ...this.options.env }, sessionId: state.sessionId });
+                const remaining = timeoutMs - (Date.now() - began);
+                if (remaining <= 0) {
+                    await this.connection.close();
+                    throw new AgentTimeoutError('Step timeout');
+                }
+                const answer = await this.connection.run(input, this.options.nativeSchema === true ? schema : undefined, emit, id => state.bind(id), { timeoutMs: remaining, idleTimeoutMs: this.options.idleTimeoutMs,
+                    progressIntervalMs: this.options.progressIntervalMs === undefined ? 15_000 : this.options.progressIntervalMs, signal });
+                writeFileSync(join(directory, `${attempt}.output.txt`), answer.hasStructured ? JSON.stringify(answer.structured) : answer.text, { mode: 0o600 });
+                if (!options.schema && !options.codec) {
+                    record('completed', { result: answer.text });
+                    emit({ kind: 'step_completed', text: name });
+                    return answer.text;
+                }
+                let parsed;
+                let problem;
+                try {
+                    parsed = answer.hasStructured ? answer.structured : JSON.parse(answer.text);
+                }
+                catch {
+                    problem = 'Final answer is not valid JSON';
+                }
+                const validated = problem ? undefined : options.codec ? await options.codec.validate(parsed) : options.schema.safeParse(parsed);
+                if (validated?.success) {
+                    record('completed', { result: validated.data });
+                    emit({ kind: 'step_completed', text: name });
+                    return validated.data;
+                }
+                problem ??= JSON.stringify(validated && !validated.success ? ('error' in validated ? validated.error.issues : validated.issues) : 'Invalid result');
+                if (attempt === (this.options.maxCorrections ?? 2))
+                    throw new ResultValidationError(`${name}: invalid result after ${attempt + 1} answers. Logs: ${directory}\n${problem}`);
+                emit({ kind: 'correction', text: `${name}：请求第 ${attempt + 1} 次补答` });
+                input = 'Your previous final answer is invalid. Do not repeat completed actions. Use the work already performed in this conversation. Return ONLY a JSON object matching the schema.\nValidation errors:\n' + problem + '\nSchema:\n' + JSON.stringify(schema);
+            }
+            throw new ResultValidationError('No valid result');
+        }
+        catch (error) {
+            const interrupted = error instanceof CancelledError || error instanceof AgentTimeoutError;
+            record(interrupted ? 'interrupted' : 'failed', { error: String(error) });
+            emit({ kind: interrupted ? 'step_interrupted' : 'step_failed', text: `${name}: ${String(error)}` });
+            throw error;
+        }
+    }
+    close() { return this.closePromise ??= this.shutdown(); }
+    async shutdown() {
+        this.closed = true;
+        this.lifetime.abort();
+        await this.tail;
+        try {
+            await this.connection?.close();
+        }
+        finally {
+            this.state?.close();
+        }
+    }
+    async [Symbol.asyncDispose]() { await this.close(); }
+}
+export async function withAgent(options, workflow) {
+    const agent = new Agent(options);
+    try {
+        return await workflow(agent);
+    }
+    finally {
+        await agent.close();
+    }
+}
+//# sourceMappingURL=agent.js.map

package/dist/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { resolve } from 'node:path';
+import { statSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { constants } from 'node:os';
+const args = process.argv.slice(2);
+if (!args.length || ['--help', '-h'].includes(args[0])) {
+    console.log(`用法：atf <文件.ts|文件.js> [传给流程的参数...]
+
+例如：
+  atf examples/simple.ts
+  atf examples/smoke.ts --command cxh --rounds 5
+  atf /path/to/pilot.ts --project projects/my-project --command cxh
+
+执行普通 TypeScript/JavaScript；支持相对 import。
+文件可直接调用 flow，也可导出 main(args)，由 atf 在加载后调用。
+--version  显示版本
+--help     显示帮助`);
+}
+else if (['--version', '-v'].includes(args[0])) {
+    console.log(JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version);
+}
+else {
+    const [major, minor] = process.versions.node.split('.').map(Number);
+    if (major < 22 || (major === 22 && minor < 15)) {
+        console.error('atf 需要 Node.js 22.15+。');
+        process.exitCode = 1;
+    }
+    else {
+        const file = resolve(args[0]);
+        try {
+            if (!statSync(file).isFile())
+                throw new Error('路径不是文件');
+            const child = spawn(process.execPath, [
+                '--import', fileURLToPath(new URL('./loader.js', import.meta.url)),
+                fileURLToPath(new URL('./runner.js', import.meta.url)), file, ...args.slice(1),
+            ], { stdio: 'inherit' });
+            const signals = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+            // 同终端进程组的 Ctrl+C 也会传给子进程；转发确保单独终止 atf 时不遗留工作流。
+            const handlers = signals.map(signal => { const handler = () => child.kill(signal); process.on(signal, handler); return handler; });
+            child.once('error', error => { console.error(`atf: ${error.message}`); process.exitCode = 1; });
+            child.once('exit', (code, signal) => {
+                signals.forEach((name, i) => process.off(name, handlers[i]));
+                process.exitCode = code ?? (signal ? 128 + constants.signals[signal] : 1);
+            });
+        }
+        catch (error) {
+            console.error(`atf: 无法执行 ${file}: ${error.message}`);
+            process.exitCode = 1;
+        }
+    }
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/connection.d.ts

@@ -0,0 +1,37 @@
+import type { EventSink } from './events.js';
+import { Transport } from './transport.js';
+export type Provider = 'codex' | 'claude';
+export interface ConnectionOptions {
+    provider: Provider;
+    command: string[];
+    cwd: string;
+    extraArgs: string[];
+    env: NodeJS.ProcessEnv;
+    sessionId?: string;
+}
+export interface TurnResult {
+    text: string;
+    structured?: unknown;
+    hasStructured: boolean;
+}
+export declare class Connection {
+    private options;
+    readonly transport: Transport;
+    private ready;
+    private counter;
+    private pending;
+    private sessionId?;
+    constructor(options: ConnectionOptions);
+    get pid(): number | undefined;
+    close(): Promise<void>;
+    private read;
+    private stash;
+    private rpc;
+    private initialize;
+    run(prompt: string, schema: unknown, emit: EventSink, bind: (id: string) => void, limits: {
+        timeoutMs: number;
+        idleTimeoutMs?: number;
+        progressIntervalMs: number | null;
+        signal?: AbortSignal;
+    }): Promise<TurnResult>;
+}