zhuye 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,80 @@
-# Temporary Holding Version
+# zhuye (TypeScript SDK)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+让脚本项目(同样适用于 TS 服务端)直接驱动 ZhuYe Agent 的轻量 SDK。底层通过 spawn `zhuye serve` 子进程、走 JSONL stdio 协议,**零原生编译、零原生依赖**。
+
+## 安装
+
+```bash
+npm install zhuye
+```
+
+需要本机有 `zhuye` 二进制在 PATH(或通过 `ZHUYE_BIN` 指向)。从 [GitHub Releases](https://github.com/Asketisch/ZhuYe/releases) 下载,或从本仓库 `make build` 产出 `target/release/zhuye`。
+
+## 用法
+
+```ts
+import { ZhuyeAgent } from 'zhuye';
+
+const agent = await ZhuyeAgent.spawn();
+
+// 1) 注册客户端自定义工具(LLM 调用时由本地函数返回结果)
+await agent.registerTool(
+  'get_weather',
+  '查询指定城市的天气',
+  {
+    type: 'object',
+    properties: { city: { type: 'string' } },
+    required: ['city'],
+  },
+  async ({ city }) => ({
+    content: [{ type: 'text', text: `${city} 今天晴 26℃` }],
+    is_error: false,
+    metadata: {},
+    elapsed_ms: 0,
+  }),
+);
+
+// 2) 提交 prompt,流式接收事件
+const text = await agent.prompt('北京天气如何?');
+console.log(text); // "北京 今天晴 26℃"
+
+// 3) 也可手动遍历事件:
+for await (const ev of await agent.submit('第二轮')) {
+  if (ev.msg.type === 'agent_message_delta') process.stdout.write(ev.msg.delta);
+  if (ev.msg.type === 'turn_complete') break;
+}
+
+await agent.close();
+```
+
+## 全局事件
+
+`nextGlobalEvent({ timeoutMs })` 读取 `id=""` 的会话事件(`approval_request` /
+`token_count` / `permission_mode_changed` 等),与 `submit()` 的按 submission
+路由的事件迭代器独立。超时抛错,进程 stdout 关闭后返回 `null`;未知变体
+原样返回。
+
+```ts
+const handshake = await agent.nextGlobalEvent({ timeoutMs: 5000 });
+```
+
+## 环境变量
+
+| 变量 | 作用 |
+|------|------|
+| `ZHUYE_BIN` | `zhuye` 二进制路径(默认搜索 PATH)。 |
+| `ZHUYE_MODEL` | 模型名(spec,例如 `mock/mock-1` 用于离线 SDK 测试)。 |
+| `ZHUYE_REMOTE_TOOL_TIMEOUT_SECS` | 远程工具等待客户端回执的上限,默认 120s。 |
+
+## 协议
+
+SDK 与 `zhuye serve` 之间的 wire 协议见 `../PROTOCOL.md`(同仓库 `sdks/PROTOCOL.md`)。Rust 核心新增协议变体时,SDK 自动降为 `UnknownEventMsg`,不会中断下游。
+
+## 测试
+
+```bash
+npm install
+npm test           # 跑协议层 vitest(无需 zhuye 二进制)
+```
+
+完整的端到端测试(包含 `zhuye serve` 子进程)需先在仓库根 `cargo build -p zhuye-cli`,再把 `target/debug/zhuye` 暴露到 PATH 或 `ZHUYE_BIN`。

package/dist/agent.d.ts

@@ -0,0 +1,100 @@
+import { ChildProcessWithoutNullStreams } from 'node:child_process';
+import { Readable, Writable } from 'node:stream';
+import { Event, Op, ReviewDecision, ToolOutput } from './protocol.js';
+/** 单次工具执行的本地 handler(远程工具回执内容)。 */
+export type ToolHandler = (args: Record<string, unknown>) => Promise<ToolOutput> | ToolOutput;
+/** ZhuyeAgent 启动选项。 */
+export interface ZhuyeAgentOptions {
+    /** `zhuye` 二进制路径。默认读 env `ZHUYE_BIN` → PATH 上的 `zhuye`。 */
+    bin?: string;
+    /** 工作目录(传给 serve 的 env)。 */
+    cwd?: string;
+    /** 透传给 serve 进程的 env(如 `ZHUYE_MODEL=mock`)。 */
+    env?: NodeJS.ProcessEnv;
+    /** 反射 spawn options(覆盖/补充默认的 cwd / env)。 */
+    spawnOptions?: Omit<SpawnOptions, 'bin' | 'args' | 'env' | 'cwd'>;
+    /** `session_configured` 握手超时(ms)。默认 30s。 */
+    handshakeTimeoutMs?: number;
+}
+interface SpawnOptions {
+    bin: string;
+    args: string[];
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * 主类:启动并维护一个常驻 `zhuye serve` 子进程,把 JSONL 协议包装
+ * 成 Promise / AsyncIterable 给 TS 用户。
+ */
+export declare class ZhuyeAgent {
+    private readonly proc;
+    private readonly tools;
+    private readonly pending;
+    private readonly ready;
+    private readonly _closeListeners;
+    private closesHandled;
+    private closed;
+    private onceSessionConfigured;
+    private constructor();
+    /** 启动一个 `zhuye serve` 子进程,等到 `session_configured` 即视为就绪。 */
+    static spawn(options?: ZhuyeAgentOptions): Promise<ZhuyeAgent>;
+    /** 测试 / mock 注入用:用现成的 stdio 流替代 spawn(单测走这条路)。 */
+    static fromStdio(stdin: Writable, stdout: Readable, handshakeTimeoutMs?: number): Promise<ZhuyeAgent>;
+    /** 注册客户端自定义工具(`ZhuyeAgent` 启动后任何时刻可调用)。 */
+    registerTool(name: string, description: string, parameters: Record<string, unknown>, handler: ToolHandler): Promise<void>;
+    /** 提交一条用户 prompt;返回该 submission 的事件 AsyncIterable。 */
+    submit(text: string): Promise<AsyncIterable<Event>>;
+    /** 提交一条任意 Op(用于 shutdown / interrupt / approval / 等等)。 */
+    submit(op: Op, opts?: {
+        submissionId?: string;
+    }): Promise<AsyncIterable<Event>>;
+    /** 便捷:`prompt(text)` → 最终 assistant 文本(聚合所有 delta)。 */
+    prompt(text: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<string>;
+    /** 中断当前 turn。 */
+    interrupt(childId?: string): Promise<void>;
+    /**
+     * 响应 `ApprovalRequest` 或 `HookApprovalRequest`。
+     *
+     * `decision` 是 wire 形态的 `ReviewDecision`(serde snake_case):
+     * `"approve"` / `"approve_for_session"`,或
+     * `{ deny: { reason: string } }`。与 Python SDK 一致 —— 透传 wire
+     * 值,不做形状转换(旧版发 `{type:'approve'}` 无法被服务端反序列化,
+     * 审批会永久挂起,已修)。
+     */
+    approve(id: string, decision: ReviewDecision): Promise<void>;
+    /**
+     * 读取一条全局事件(`id=""`:approval_request / ask_user_question /
+     * token_count / permission_mode_changed 等,含握手的
+     * `session_configured` 本身),与 submit() 的事件迭代器相互独立;
+     * 未知事件原样返回。
+     *
+     * stdout EOF / close 之后返回 `null`;`timeoutMs` 到点抛错 ——
+     * 与 Python SDK 的 `next_global_event` 语义对齐(超时抛 `queue.Empty`,
+     * EOF 返回 None)。
+     */
+    nextGlobalEvent(opts?: {
+        timeoutMs?: number;
+    }): Promise<Event | null>;
+    /** 优雅关闭:发 Shutdown → 等 ShutdownComplete → 杀进程。 */
+    close(): Promise<void>;
+    /** 暴露当前进程句柄(测试需要直接操作 stdin / kill 时用)。 */
+    get childProcess(): ChildProcessWithoutNullStreams | undefined;
+    /** 子进程意外退出时通知所有 close 监听者。 */
+    private handleServeExit;
+    private consumeStdout;
+    private handleToolRequest;
+    private eventListeners;
+    /** 全局事件(`id=""`)缓冲:nextGlobalEvent() 的队列 + 挂起等待者。 */
+    private globalQueue;
+    private globalWaiters;
+    private globalEof;
+    private dispatchEvent;
+    /** 全局事件入队;`ev === null` 表示 EOF:标记收尾并唤醒等待者。 */
+    private pushGlobalEvent;
+    private filterEventsById;
+    private writeSubmission;
+    private writeSubmissionUnchecked;
+}
+export {};

package/dist/agent.js

@@ -0,0 +1,533 @@
+//! ZhuyeAgent —— TS SDK 主类。
+//!
+//! 用法:
+//! ```ts
+//! const agent = await ZhuyeAgent.spawn();
+//! await agent.registerTool('get_weather', '查询天气', {
+//!   type: 'object', properties: { city: { type: 'string' } }, required: ['city']
+//! }, async ({ city }) => ({ content: [{ type: 'text', text: `晴 26℃` }] }));
+//! for await (const ev of agent.submit('北京天气如何')) {
+//!   if (ev.msg.type === 'agent_message_delta') process.stdout.write(ev.msg.delta);
+//! }
+//! await agent.close();
+//! ```
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+const ZHUYE_BIN_ENV = 'ZHUYE_BIN';
+const DEFAULT_BIN = 'zhuye';
+const READLINE_LIMIT = 16 * 1024 * 1024;
+const STDIN_HANDSHAKE_TIMEOUT_MS = 30_000;
+/**
+ * 主类:启动并维护一个常驻 `zhuye serve` 子进程,把 JSONL 协议包装
+ * 成 Promise / AsyncIterable 给 TS 用户。
+ */
+export class ZhuyeAgent {
+    proc;
+    tools = new Map();
+    pending = new Map();
+    ready;
+    _closeListeners = [];
+    closesHandled = false;
+    closed = false;
+    onceSessionConfigured = () => { };
+    constructor(proc, ready) {
+        this.proc = proc;
+        this.ready = ready;
+        // 后台消费 stdout:按 type 分发到等待中的本地 handler(若已注册)
+        // 或作为 turn 事件交给 submit() 的消费者。
+        this.consumeStdout().catch((err) => {
+            if (!this.closed)
+                throw err;
+        });
+    }
+    /** 启动一个 `zhuye serve` 子进程,等到 `session_configured` 即视为就绪。 */
+    static async spawn(options = {}) {
+        // env 合并而非替换:保留 HOME / PATH 等(替换会让 zhuye 连
+        // config 目录都定位不到),options.env 只做增量覆盖。
+        const env = { ...process.env, ...options.env };
+        const spawnOpts = {
+            bin: options.bin ?? process.env[ZHUYE_BIN_ENV] ?? DEFAULT_BIN,
+            args: ['serve'],
+            cwd: options.cwd,
+            env,
+        };
+        const child = spawn(spawnOpts.bin, spawnOpts.args, {
+            cwd: spawnOpts.cwd,
+            env: spawnOpts.env,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        // 子进程 stderr → 当前进程 stderr(让 tracing 日志透传)。
+        child.stderr.on('data', (chunk) => {
+            process.stderr.write(chunk);
+        });
+        const proc = {
+            child,
+            stdin: child.stdin,
+            stdoutLine: lineStream(child.stdout),
+        };
+        // ready 在构造前组装:构造期 handshake 同步需要,放外面。
+        let readyResolve;
+        let readyReject;
+        const ready = new Promise((res, rej) => {
+            readyResolve = res;
+            readyReject = rej;
+        });
+        const agent = new ZhuyeAgent(proc, ready);
+        // 子进程意外退出 → 通知所有 close 监听者(submit / prompt 等
+        // 仍 await 中的 promise 借此抛错 / 收尾)。
+        child.on('exit', (code, signal) => {
+            agent.handleServeExit(new Error(`zhuye serve exited unexpectedly (code=${code} signal=${signal ?? 'none'})`));
+        });
+        // spawn 失败(典型:二进制路径不存在,ENOENT):ChildProcess 的
+        // error 事件没有监听者会以 uncaught exception 打爆宿主进程;这里
+        // 转为握手失败(ready 尚未 settle 时立即拒绝,否则等握手超时)。
+        child.on('error', (err) => {
+            const failure = new Error(`zhuye serve failed to start: ${err.message}`);
+            readyReject(failure);
+            agent.handleServeExit(failure);
+        });
+        const handshakeMs = options.handshakeTimeoutMs ?? STDIN_HANDSHAKE_TIMEOUT_MS;
+        const timer = setTimeout(() => {
+            readyReject(new Error(`zhuye serve handshake timed out after ${handshakeMs}ms`));
+        }, handshakeMs);
+        timer.unref?.();
+        // 在握手阶段消费 stdout,直到见到 session_configured 后再切给
+        // 业务消费者 —— 简单做法:让后台 consumer 自己处理,ready 在
+        // session_configured 时 resolve。
+        agent.onceSessionConfigured = () => {
+            clearTimeout(timer);
+            readyResolve();
+        };
+        return agent;
+    }
+    /** 测试 / mock 注入用:用现成的 stdio 流替代 spawn(单测走这条路)。 */
+    static async fromStdio(stdin, stdout, handshakeTimeoutMs = STDIN_HANDSHAKE_TIMEOUT_MS) {
+        const proc = {
+            // child 字段仅类型占位;内部不会触发 spawn 路径。
+            child: undefined,
+            stdin,
+            stdoutLine: lineStream(stdout),
+        };
+        let readyResolve;
+        let readyReject;
+        const ready = new Promise((res, rej) => {
+            readyResolve = res;
+            readyReject = rej;
+        });
+        const agent = new ZhuyeAgent(proc, ready);
+        const timer = setTimeout(() => {
+            readyReject(new Error(`fromStdio handshake timed out after ${handshakeTimeoutMs}ms`));
+        }, handshakeTimeoutMs);
+        timer.unref?.();
+        agent.onceSessionConfigured = () => {
+            clearTimeout(timer);
+            readyResolve();
+        };
+        return agent;
+    }
+    /** 注册客户端自定义工具(`ZhuyeAgent` 启动后任何时刻可调用)。 */
+    async registerTool(name, description, parameters, handler) {
+        await this.ready;
+        const spec = { name, description, parameters };
+        this.tools.set(name, { spec, handler });
+        const sub = {
+            id: randomUUID(),
+            op: { type: 'register_tools', tools: [spec] },
+        };
+        await this.writeSubmission(sub);
+    }
+    async submit(input, opts = {}) {
+        await this.ready;
+        const id = opts.submissionId ?? randomUUID();
+        const op = typeof input === 'string'
+            ? {
+                type: 'user_input',
+                items: [{ type: 'text', text: input }],
+            }
+            : input;
+        const sub = { id, op };
+        await this.writeSubmission(sub);
+        return this.filterEventsById(id);
+    }
+    /** 便捷:`prompt(text)` → 最终 assistant 文本(聚合所有 delta)。 */
+    async prompt(text, opts = {}) {
+        let result = '';
+        for await (const ev of await this.submit(text)) {
+            const msg = ev.msg;
+            if (msg.type === 'agent_message_delta')
+                result += msg.delta;
+            else if (msg.type === 'agent_message')
+                result += msg.text;
+            else if (msg.type === 'turn_complete')
+                break;
+            else if (msg.type === 'turn_aborted') {
+                // 对齐 Python SDK:turn_aborted 不是正常完成,返回部分文本
+                // 容易被调用方误认为完整答案 —— 抛错强制处理。
+                throw new Error(`zhuye turn aborted: ${JSON.stringify(msg.reason)}`);
+            }
+            else if (msg.type === 'error') {
+                throw new Error(`zhuye error: ${msg.code}: ${msg.message}`);
+            }
+        }
+        return result;
+    }
+    /** 中断当前 turn。 */
+    async interrupt(childId) {
+        await this.writeSubmission({
+            id: randomUUID(),
+            op: { type: 'interrupt', child_id: childId ?? null },
+        });
+    }
+    /**
+     * 响应 `ApprovalRequest` 或 `HookApprovalRequest`。
+     *
+     * `decision` 是 wire 形态的 `ReviewDecision`(serde snake_case):
+     * `"approve"` / `"approve_for_session"`,或
+     * `{ deny: { reason: string } }`。与 Python SDK 一致 —— 透传 wire
+     * 值,不做形状转换(旧版发 `{type:'approve'}` 无法被服务端反序列化,
+     * 审批会永久挂起,已修)。
+     */
+    async approve(id, decision) {
+        await this.writeSubmission({
+            id: randomUUID(),
+            op: {
+                type: 'tool_approval', // Hook 审批也用同一个 decision 形态;serve 层自行分发
+                id,
+                decision,
+            },
+        });
+    }
+    /**
+     * 读取一条全局事件(`id=""`:approval_request / ask_user_question /
+     * token_count / permission_mode_changed 等,含握手的
+     * `session_configured` 本身),与 submit() 的事件迭代器相互独立;
+     * 未知事件原样返回。
+     *
+     * stdout EOF / close 之后返回 `null`;`timeoutMs` 到点抛错 ——
+     * 与 Python SDK 的 `next_global_event` 语义对齐(超时抛 `queue.Empty`,
+     * EOF 返回 None)。
+     */
+    async nextGlobalEvent(opts = {}) {
+        const queued = this.globalQueue.shift();
+        if (queued)
+            return queued;
+        if (this.globalEof)
+            return null;
+        return new Promise((resolve, reject) => {
+            let timer;
+            const waiter = (ev) => {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                resolve(ev);
+            };
+            this.globalWaiters.push(waiter);
+            if (opts.timeoutMs !== undefined) {
+                timer = setTimeout(() => {
+                    const idx = this.globalWaiters.indexOf(waiter);
+                    if (idx >= 0)
+                        this.globalWaiters.splice(idx, 1);
+                    reject(new Error(`zhuye nextGlobalEvent timed out after ${opts.timeoutMs}ms`));
+                }, opts.timeoutMs);
+                timer.unref?.();
+            }
+        });
+    }
+    /** 优雅关闭:发 Shutdown → 等 ShutdownComplete → 杀进程。 */
+    async close() {
+        if (this.closed)
+            return;
+        // 先置 closed(同步挡住并发 close 与后续 writeSubmission),再发
+        // shutdown。共享 stdin 可能已被别处(另一个 agent / 外部)end 掉,
+        // 此时跳过写入与 end,直接走进程收尾。
+        this.closed = true;
+        this.closesHandled = true;
+        const stdinUsable = !this.proc.stdin.destroyed && !this.proc.stdin.writableEnded;
+        if (stdinUsable) {
+            try {
+                await this.writeSubmissionUnchecked({ id: randomUUID(), op: { type: 'shutdown' } });
+            }
+            catch {
+                // stdin 已关,忽略
+            }
+            this.proc.stdin.end();
+        }
+        await new Promise((resolve) => {
+            if (!this.proc.child) {
+                resolve();
+                return;
+            }
+            this.proc.child.once('exit', () => resolve());
+            setTimeout(() => {
+                try {
+                    this.proc.child?.kill();
+                }
+                catch {
+                    // ignore
+                }
+                resolve();
+                // 2s 对齐 Python SDK(agent.close 的 wait(timeout=2.0))。
+            }, 2000).unref?.();
+        });
+    }
+    /** 暴露当前进程句柄(测试需要直接操作 stdin / kill 时用)。 */
+    get childProcess() {
+        return this.proc.child;
+    }
+    /** 子进程意外退出时通知所有 close 监听者。 */
+    handleServeExit(err) {
+        if (this.closesHandled)
+            return;
+        for (const cb of this._closeListeners)
+            cb(err);
+    }
+    // ── 内部:握手 / 事件分发 / 写 Submission ─────────────────────────
+    async consumeStdout() {
+        for await (const line of this.proc.stdoutLine) {
+            let ev;
+            try {
+                ev = JSON.parse(line);
+            }
+            catch {
+                process.stderr.write(`[zhuye-sdk] unparseable line: ${line.slice(0, 200)}\n`);
+                continue;
+            }
+            // 握手阶段:见 session_configured 就 resolve ready。
+            if (!this.onceSessionConfigured && ev.msg.type === 'session_configured') {
+                // onceSessionConfigured 已被 fromStdio/spawn 重新赋值,这里只是兜底。
+            }
+            if (ev.msg.type === 'session_configured') {
+                const cb = this.onceSessionConfigured;
+                this.onceSessionConfigured = () => { };
+                cb();
+            }
+            // 远程工具请求 → 调用本地 handler → 回执。
+            if (ev.msg.type === 'tool_execution_request') {
+                const req = ev.msg;
+                void this.handleToolRequest(req.call_id, req.tool, req.args);
+                continue;
+            }
+            // 其他事件交给按 submission id 过滤的消费者。
+            this.dispatchEvent(ev);
+        }
+        // stdout EOF(子进程退出):唤醒所有仍挂起的 submission 迭代器
+        // 与全局事件等待者 —— 对齐 Python `_on_eof`:连接断开即按流末尾
+        // 收尾,而不是永久挂起。
+        for (const cb of [...this.eventListeners.values()])
+            cb(null);
+        this.eventListeners.clear();
+        this.pushGlobalEvent(null);
+    }
+    async handleToolRequest(callId, tool, args) {
+        const entry = this.tools.get(tool);
+        if (!entry) {
+            // 没注册 → 回执失败(让 LLM 看到错误)。
+            await this.writeSubmission({
+                id: randomUUID(),
+                op: {
+                    type: 'tool_execution_response',
+                    call_id: callId,
+                    output: errorOutput(`tool '${tool}' not registered in this SDK`),
+                },
+            });
+            return;
+        }
+        try {
+            const output = await entry.handler(args);
+            await this.writeSubmission({
+                id: randomUUID(),
+                op: { type: 'tool_execution_response', call_id: callId, output },
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            await this.writeSubmission({
+                id: randomUUID(),
+                op: {
+                    type: 'tool_execution_response',
+                    call_id: callId,
+                    output: errorOutput(message),
+                },
+            });
+        }
+    }
+    eventListeners = new Map();
+    /** 全局事件(`id=""`)缓冲:nextGlobalEvent() 的队列 + 挂起等待者。 */
+    globalQueue = [];
+    globalWaiters = [];
+    globalEof = false;
+    dispatchEvent(ev) {
+        if (ev.id) {
+            const cb = this.eventListeners.get(ev.id);
+            if (cb) {
+                cb(ev);
+                // 终态事件(turn_complete / turn_aborted / shutdown_complete /
+                // submission_closed)视为 stream 末尾,清掉监听者。
+                if (isTerminal(ev.msg))
+                    this.eventListeners.delete(ev.id);
+            }
+        }
+        else {
+            // 全局事件(含握手的 session_configured)入会话级队列,由
+            // nextGlobalEvent() 消费 —— 不入任何 submission 的迭代器。
+            this.pushGlobalEvent(ev);
+        }
+    }
+    /** 全局事件入队;`ev === null` 表示 EOF:标记收尾并唤醒等待者。 */
+    pushGlobalEvent(ev) {
+        if (ev === null)
+            this.globalEof = true;
+        const waiter = this.globalWaiters.shift();
+        if (waiter) {
+            waiter(ev);
+            return;
+        }
+        if (ev !== null)
+            this.globalQueue.push(ev);
+    }
+    filterEventsById(submissionId) {
+        const queue = [];
+        const pending = [];
+        let closed = false;
+        // ev === null 表示 stdout EOF / 连接断开:按流末尾收尾(效果与
+        // 收到终态事件一致),对齐 Python `_on_eof` 唤醒全部监听者。
+        const onEvent = (ev) => {
+            if (ev === null) {
+                cleanup();
+                return;
+            }
+            const next = pending.shift();
+            if (next)
+                next(ev);
+            else
+                queue.push(ev);
+        };
+        this.eventListeners.set(submissionId, onEvent);
+        const cleanup = () => {
+            closed = true;
+            this.eventListeners.delete(submissionId);
+            // 唤醒剩余 pending 等待者,让他们抛错或退出。
+            while (pending.length) {
+                const next = pending.shift();
+                next?.(null);
+            }
+        };
+        return {
+            [Symbol.asyncIterator]() {
+                return {
+                    next: async () => {
+                        if (queue.length > 0) {
+                            const ev = queue.shift();
+                            if (isTerminal(ev.msg))
+                                cleanup();
+                            return { value: ev, done: false };
+                        }
+                        if (closed)
+                            return { value: undefined, done: true };
+                        return new Promise((resolve) => {
+                            pending.push((ev) => {
+                                if (ev === null)
+                                    resolve({ value: undefined, done: true });
+                                else {
+                                    if (isTerminal(ev.msg))
+                                        cleanup();
+                                    resolve({ value: ev, done: false });
+                                }
+                            });
+                        });
+                    },
+                    return: async () => {
+                        cleanup();
+                        return { value: undefined, done: true };
+                    },
+                };
+            },
+        };
+    }
+    async writeSubmission(sub) {
+        // close() 之后(end 掉 stdin)仍可能有异步路径想写 —— 典型是挂起的
+        // 工具 handler 回执。静默丢弃:连接已关,回执无处可去;抛"write
+        // after end"反而变成 uncaught exception 打爆宿主进程。
+        if (this.closed || this.proc.stdin.destroyed || this.proc.stdin.writableEnded) {
+            return;
+        }
+        return this.writeSubmissionUnchecked(sub);
+    }
+    writeSubmissionUnchecked(sub) {
+        return new Promise((resolve, reject) => {
+            const payload = JSON.stringify(sub) + '\n';
+            this.proc.stdin.write(payload, (err) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve();
+            });
+        });
+    }
+}
+function errorOutput(message) {
+    return {
+        content: [{ type: 'text', text: `error: ${message}` }],
+        is_error: true,
+        metadata: {},
+        elapsed_ms: 0,
+    };
+}
+function isTerminal(msg) {
+    // `submission_closed` 是 serve 在某条 submission 的 per-turn 通道排空后
+    // 发出的收尾标记(挂该 submission id)。非 turn 操作(compact / rewind /
+    // set_permission_mode 等)没有 turn_complete 之类终态事件,迭代器靠它
+    // 收尾;turn 类操作先被 turn_complete / turn_aborted 终结,本事件届时
+    // 已无监听者,被无害忽略。
+    return (msg.type === 'turn_complete' ||
+        msg.type === 'turn_aborted' ||
+        msg.type === 'shutdown_complete' ||
+        msg.type === 'submission_closed');
+}
+/**
+ * 把 Readable 流切成按行产生的 AsyncIterable。超长行(> 16 MiB)
+ * 抛错并跳过 —— 对应 `zhuye serve` 不应输出如此长的 JSONL 行。
+ */
+function lineStream(stream) {
+    // Node 的 Readable 默认 paused,data 事件不会自动 emit。.resume() 切
+    // 到 flowing 模式,iter.next() 才有数据。
+    stream.resume();
+    const iter = stream[Symbol.asyncIterator]();
+    let buffer = '';
+    const MAX_LINE = READLINE_LIMIT;
+    return {
+        [Symbol.asyncIterator]() {
+            return {
+                next: async () => {
+                    while (true) {
+                        const nl = buffer.indexOf('\n');
+                        if (nl >= 0) {
+                            const line = buffer.slice(0, nl);
+                            buffer = buffer.slice(nl + 1);
+                            return { value: line, done: false };
+                        }
+                        if (buffer.length > MAX_LINE) {
+                            const over = buffer.slice(0, 256);
+                            buffer = '';
+                            process.stderr.write(`[zhuye-sdk] line > ${MAX_LINE} bytes, dropping: ${over}\n`);
+                            continue;
+                        }
+                        const { value, done } = await iter.next();
+                        if (done) {
+                            if (buffer.length === 0)
+                                return { value: undefined, done: true };
+                            const tail = buffer;
+                            buffer = '';
+                            return { value: tail, done: false };
+                        }
+                        buffer += String(value);
+                    }
+                },
+                return: async () => {
+                    await iter.return?.();
+                    buffer = '';
+                    return { value: undefined, done: true };
+                },
+            };
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './protocol.js';
+export { ZhuyeAgent, ToolHandler, ZhuyeAgentOptions, } from './agent.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+//! `zhuye` —— TS SDK 公共入口。
+export * from './protocol.js';
+export { ZhuyeAgent, } from './agent.js';

package/dist/protocol.d.ts

@@ -0,0 +1,438 @@
+/**
+ * Submission 是 client → serve 的一条命令。`id` 用于把随之产生的事件
+ * (`Event.id`)关联回原始 Submission。
+ */
+export interface Submission {
+    id: string;
+    op: Op;
+    client_user_message_id?: string;
+}
+/**
+ * Op —— 客户端可向 core 提交的操作。`type` 字段是判别符,与 Rust
+ * `#[serde(tag = "type", rename_all = "snake_case")]` 一致。
+ */
+export type Op = {
+    type: 'user_input';
+    items: UserInputItem[];
+    thread_settings?: ThreadSettings;
+} | {
+    type: 'compact';
+} | {
+    type: 'interrupt';
+    child_id?: string | null;
+} | {
+    type: 'rewind';
+    to_turn_id?: string | null;
+} | {
+    type: 'shutdown';
+} | {
+    type: 'tool_approval';
+    id: string;
+    decision: ReviewDecision;
+} | {
+    type: 'hook_approval';
+    id: string;
+    decision: ReviewDecision;
+} | {
+    type: 'enter_plan_mode';
+    task: string;
+} | {
+    type: 'exit_plan_mode';
+} | {
+    type: 'plan_approval';
+    id: string;
+    choice: PlanApprovalChoice;
+} | {
+    type: 'set_effort';
+    effort: ReasoningEffort;
+} | {
+    type: 'ask_user_question_response';
+    id: string;
+    answers: AskUserAnswer;
+} | {
+    type: 'ask_user_input_response';
+    id: string;
+    text: string;
+} | {
+    type: 'set_permission_mode';
+    mode: PermissionMode;
+} | {
+    type: 'cycle_permission_mode';
+} | {
+    type: 'enter_goal_mode';
+    goal: string;
+    verify_command?: string | null;
+    token_budget?: number | null;
+} | {
+    type: 'exit_goal_mode';
+}
+/** v1.3 SDK:注册客户端自定义工具(实现留在客户端进程)。 */
+ | {
+    type: 'register_tools';
+    tools: RemoteToolSpec[];
+}
+/** v1.3 SDK:对 `EventMsg::ToolExecutionRequest` 的回执。 */
+ | {
+    type: 'tool_execution_response';
+    call_id: string;
+    output: ToolOutput;
+};
+export interface UserInputItem {
+    type: 'text' | 'image';
+    text?: string;
+}
+export interface ThreadSettings {
+    effort?: ReasoningEffort | null;
+    permission_mode?: PermissionMode | null;
+    model?: string | null;
+}
+export type ReasoningEffort = 'low' | 'medium' | 'high';
+export type PermissionMode = 'auto' | 'prompt' | 'plan' | 'deny' | 'bubble';
+export type PlanApprovalChoice = 'auto_mode' | 'manual_approve' | 'revise';
+/**
+ * `ReviewDecision` 的 wire 形态(serde snake_case)。
+ *
+ * 注意是**扁平**结构而非 tagged 对象:`Approve` 序列化为裸字符串
+ * `"approve"`,`Deny` 序列化为 `{"deny":{"reason":...}}`。旧版误写成
+ * `{type:'approve'}`,服务端无法反序列化,审批会永久挂起(v1.3 修复)。
+ */
+export type ReviewDecision = 'approve' | 'approve_for_session' | {
+    deny: {
+        reason: string;
+    };
+};
+export interface AskUserAnswer {
+    answers: Answer[];
+}
+export interface Answer {
+    selected: number[];
+    custom?: string | null;
+}
+/** v1.3 SDK:客户端自定义工具声明。 */
+export interface RemoteToolSpec {
+    name: string;
+    description: string;
+    /** JSON Schema 对象。 */
+    parameters: Record<string, unknown>;
+}
+/** v1.3 SDK:远程工具执行结果(回执 wire 格式)。 */
+export interface ToolOutput {
+    content: ContentBlock[];
+    is_error: boolean;
+    metadata?: Record<string, unknown>;
+    elapsed_ms?: number;
+}
+export interface ContentBlock {
+    type: 'text';
+    text: string;
+}
+/**
+ * Event —— core → client 的状态单元。`id` 与 `Submission.id` 对齐;
+ * 不绑定 Submission 时(如 `session_configured` / `shutdown_complete`)
+ * 取 `EVENT_ID_NONE`(空字符串)。
+ */
+export interface Event {
+    id: string;
+    msg: EventMsg;
+}
+export declare const EVENT_ID_NONE = "";
+/**
+ * 已知 EventMsg 变体的联合。未知变体降为 `UnknownEventMsg`(让 Rust
+ * 核心新增变体时下游仍能解析)。
+ */
+export type EventMsg = SessionConfigured | TurnStarted | TurnComplete | TurnAborted | TurnRewound | ShutdownComplete | SubmissionClosed | AgentMessage | AgentMessageDelta | ThinkingDelta | TokenCount | ToolCallBegin | ToolCallArgsDelta | ToolCallOutputDelta | ToolCallEnd | ToolExecutionRequest | ApprovalRequest | AskUserQuestion | AskUserInput | PermissionBubble | ContextCompacted | ErrorEvent | StreamError | ConfigReloaded | CollabStarted | CollabMessage | CollabFinished | McpServerStarted | McpServerFailed | McpToolInvoked | LspServerStarted | LspServerFailed | PlanRequest | PlanReady | PlanApproved | PlanRejected | PermissionModeChanged | PlanDraftUpdated | PlanStep | PluginLoaded | QuotaExhausted | Routing | UnknownEventMsg;
+export interface SessionConfigured {
+    type: 'session_configured';
+    session_id: string;
+    model: string;
+    provider: string;
+    approval_policy: 'auto' | 'prompt';
+    sandbox_policy: 'workspace_only' | 'full_access';
+    context_window_size?: number | null;
+}
+export interface TurnStarted {
+    type: 'turn_started';
+    turn_id: string;
+    user_message_id: string;
+}
+export interface TurnComplete {
+    type: 'turn_complete';
+    turn_id: string;
+    status: 'success' | 'max_iterations' | 'stopped' | 'token_budget_exceeded';
+    usage: TokenUsage;
+}
+export interface TurnAborted {
+    type: 'turn_aborted';
+    turn_id: string;
+    reason: AbortReason;
+}
+export type AbortReason = {
+    type: 'user_interrupt';
+} | {
+    type: 'shutdown';
+} | {
+    type: 'error';
+    code: string;
+    message: string;
+};
+export interface TurnRewound {
+    type: 'turn_rewound';
+    to_turn_id: string | null;
+    truncated_after: number;
+}
+export interface ShutdownComplete {
+    type: 'shutdown_complete';
+}
+/**
+ * v1.3 SDK:某条 submission 的 per-turn 通道已排空(该 submission 在
+ * core 处理完毕,不会再有任何事件)。`Event.id` 携带对应 submission id。
+ * serve 在 drain task 结束时发出;非 turn 操作(compact / rewind / 权限
+ * 模式切换 / goal 等)没有 `turn_complete` 之类的终态事件,`submit()`
+ * 迭代器靠本事件收尾,否则会永久挂起。
+ */
+export interface SubmissionClosed {
+    type: 'submission_closed';
+}
+export interface AgentMessage {
+    type: 'agent_message';
+    text: string;
+}
+export interface AgentMessageDelta {
+    type: 'agent_message_delta';
+    delta: string;
+}
+export interface ThinkingDelta {
+    type: 'thinking_delta';
+    delta: string;
+}
+export interface TokenCount {
+    type: 'token_count';
+    input_tokens: number;
+    output_tokens: number;
+    cached_tokens?: number;
+    cache_write_tokens?: number;
+    total_tokens?: number;
+    provider?: string;
+    credential_label?: string;
+}
+export interface TokenUsage {
+    input_tokens: number;
+    output_tokens: number;
+    cached_tokens?: number;
+    cache_write_tokens?: number;
+}
+export interface ToolCallBegin {
+    type: 'tool_call_begin';
+    call_id: string;
+    tool_name: string;
+    args: Record<string, unknown>;
+    child_id?: string | null;
+}
+/**
+ * v1.5:模型生成工具参数期间的原始 JSON 片段(逐段转发)。
+ *
+ * 与 `tool_call_begin` 的 `call_id` 对应同一通调用;客户端把各片段按
+ * 到达顺序拼接即得完整参数 JSON。additive 变体 —— 老客户端按未知
+ * `type` 忽略即可。
+ */
+export interface ToolCallArgsDelta {
+    type: 'tool_call_args_delta';
+    call_id: string;
+    delta: string;
+}
+/** 工具执行期间的输出预览,最终结果以 tool_call_end 为准。 */
+export interface ToolCallOutputDelta {
+    type: 'tool_call_output_delta';
+    call_id: string;
+    delta: string;
+    is_stderr: boolean;
+}
+export interface ToolCallEnd {
+    type: 'tool_call_end';
+    call_id: string;
+    output: ToolOutput;
+    is_error: boolean;
+    elapsed_ms: number;
+    child_id?: string | null;
+}
+/** v1.3 SDK:请求客户端执行其注册的远程工具。 */
+export interface ToolExecutionRequest {
+    type: 'tool_execution_request';
+    call_id: string;
+    tool: string;
+    args: Record<string, unknown>;
+}
+export interface ApprovalRequest {
+    type: 'approval_request';
+    request_id: string;
+    kind: ApprovalKind;
+    risk: 'low' | 'medium' | 'high';
+}
+export type ApprovalKind = {
+    type: 'tool';
+    tool_name: string;
+    args: Record<string, unknown>;
+} | {
+    type: 'hook';
+    hook_name: string;
+    decision_preview: string;
+};
+export interface AskUserQuestion {
+    type: 'ask_user_question';
+    request_id: string;
+    questions: Question[];
+}
+export interface Question {
+    header: string;
+    question: string;
+    options: QuestionOption[];
+    multi_select?: boolean;
+}
+export interface QuestionOption {
+    label: string;
+    description: string;
+    preview?: string;
+}
+export interface AskUserInput {
+    type: 'ask_user';
+    request_id: string;
+    prompt: string;
+    secret?: boolean;
+    placeholder?: string | null;
+}
+export interface PermissionBubble {
+    type: 'permission_bubble';
+    tool_name: string;
+    args_preview?: string | null;
+    risk: 'low' | 'medium' | 'high';
+}
+export interface ContextCompacted {
+    type: 'context_compacted';
+    strategy: 'truncate' | 'summarize';
+    before_tokens?: number;
+    after_tokens?: number;
+}
+export interface ErrorEvent {
+    type: 'error';
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+export interface StreamError {
+    type: 'stream_error';
+    code: string;
+    message: string;
+    retry_in_ms: number;
+    provider?: string;
+    credential_label?: string;
+}
+export interface ConfigReloaded {
+    type: 'config_reloaded';
+    sections_changed?: string[];
+}
+export interface CollabStarted {
+    type: 'collab_started';
+    discussion_id: string;
+    topic: string;
+}
+export interface CollabMessage {
+    type: 'collab_message';
+    discussion_id: string;
+    participant: string;
+    text: string;
+    token_usage?: TokenUsage;
+}
+export interface CollabFinished {
+    type: 'collab_finished';
+    discussion_id: string;
+    result?: string | null;
+}
+export interface McpServerStarted {
+    type: 'mcp_server_started';
+    server: string;
+    tool_count: number;
+    tool_names?: string[];
+    transport?: string;
+}
+export interface McpServerFailed {
+    type: 'mcp_server_failed';
+    server: string;
+    reason: string;
+    will_retry: boolean;
+}
+export interface McpToolInvoked {
+    type: 'mcp_tool_invoked';
+    server: string;
+    tool: string;
+    elapsed_ms: number;
+    is_error: boolean;
+}
+export interface LspServerStarted {
+    type: 'lsp_server_started';
+    server: string;
+    methods: string[];
+    language_ids: string[];
+}
+export interface LspServerFailed {
+    type: 'lsp_server_failed';
+    server: string;
+    reason: string;
+}
+export interface PlanRequest {
+    type: 'plan_request';
+    task: string;
+}
+export interface PlanReady {
+    type: 'plan_ready';
+    plan_id: string;
+    markdown: string;
+}
+export interface PlanApproved {
+    type: 'plan_approved';
+    plan_id: string;
+    choice: PlanApprovalChoice;
+}
+export interface PlanRejected {
+    type: 'plan_rejected';
+    plan_id: string;
+    reason?: string | null;
+}
+export interface PermissionModeChanged {
+    type: 'permission_mode_changed';
+    from: PermissionMode;
+    to: PermissionMode;
+}
+export interface PlanDraftUpdated {
+    type: 'plan_draft_updated';
+    draft_id: string;
+    markdown: string;
+}
+export interface PlanStep {
+    type: 'plan_step';
+    plan_id: string;
+    index: number;
+    total: number;
+    status: 'pending' | 'in_progress' | 'completed' | 'failed';
+    step: string;
+}
+export interface PluginLoaded {
+    type: 'plugin_loaded';
+    plugin: string;
+    skill_count: number;
+    command_count: number;
+}
+export interface QuotaExhausted {
+    type: 'quota_exhausted';
+    credential: string;
+    cooldown_until?: string | null;
+}
+export interface Routing {
+    type: 'routing';
+    role: string;
+    kind: string;
+    detail?: string;
+}
+export interface UnknownEventMsg {
+    type: string;
+    [k: string]: unknown;
+}

package/dist/protocol.js

@@ -0,0 +1,5 @@
+//! ZhuYe 协议 v0 —— SDK 与 `zhuye serve` 子命令之间的 wire 格式。
+//!
+//! 协议冻结,新增变体属 non-breaking addition;SDK 解析未知事件时
+//! 退到 `UnknownEventMsg` 不抛错,让 Rust 核心升级不破坏下游。
+export const EVENT_ID_NONE = '';

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "zhuye",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "ZhuYe Agent SDK for TypeScript: spawn `zhuye serve` and drive it over JSONL stdio.",
+  "author": "ZhuYe Agent Contributors",
+  "homepage": "https://github.com/Asketisch/ZhuYe#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Asketisch/ZhuYe.git"
+  },
+  "bugs": "https://github.com/Asketisch/ZhuYe/issues",
+  "keywords": [
+    "ai",
+    "agent",
+    "llm",
+    "jsonl",
+    "subprocess"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  }
 }