lark-remote 0.5.19 → 0.5.21

package/dist/runner/common/jsonl-stream.js

@@ -1,5 +1,132 @@
 import { getLogger } from '../../logger/index.js';
 import { StringDecoder } from 'node:string_decoder';
+function notify(state) {
+    if (state.resolveNext) {
+        state.resolveNext();
+        state.resolveNext = null;
+    }
+}
+/** Flush trailing partial line and mark the stream finished (end/close/error 共用). */
+function flushAndFinish(state) {
+    // decoder.end() 吐出被 chunk 边界切开的最后一个多字节字符的残余字节
+    //（无残尾时返回空串）：不加这句，末尾被切开的字符会凭空丢失。
+    const tail = state.decoder.end();
+    if (tail)
+        state.partialFragments.push(tail);
+    if (state.partialFragments.length > 0) {
+        const trimmed = state.partialFragments.join('').trim();
+        if (trimmed)
+            state.lineQueue.push(trimmed);
+        state.partialFragments.length = 0;
+        state.partialBytes = 0;
+    }
+    state.done = true;
+    notify(state);
+}
+/** 超长 partial line 当坏行经 onParseError 上报并清空，避免无换行流吃满内存。 */
+function flushOversizePartial(state) {
+    if (state.partialFragments.length === 0)
+        return;
+    const line = state.partialFragments.join('');
+    state.partialFragments.length = 0;
+    state.partialBytes = 0;
+    const trimmed = line.trim();
+    if (!trimmed)
+        return;
+    if (state.options?.onParseError) {
+        state.options.onParseError(trimmed);
+    }
+    else {
+        getLogger().warn(`[jsonl-stream] dropped oversize partial line (${line.length} bytes)`);
+    }
+}
+function maybePause(state) {
+    if (state.pauseThreshold > 0 && !state.paused && state.lineQueue.length > state.pauseThreshold) {
+        state.paused = true;
+        state.stdout.pause();
+    }
+}
+function maybeResume(state) {
+    if (state.paused && state.lineQueue.length <= state.resumeThreshold) {
+        state.paused = false;
+        state.stdout.resume();
+    }
+}
+/** 把本 chunk 产出的完整行移入 lineQueue（跳过空白行）。 */
+function enqueueCompleteLines(state) {
+    for (const line of state.completeLines) {
+        const trimmed = line.trim();
+        if (trimmed)
+            state.lineQueue.push(trimmed);
+    }
+    state.completeLines.length = 0;
+}
+/** 无换行 chunk：整块作为 partial fragment，超限则按坏行冲掉。 */
+function handleChunkWithoutNewline(state, text) {
+    state.partialFragments.push(text);
+    state.partialBytes += text.length;
+    if (state.partialBytes > state.partialByteLimit)
+        flushOversizePartial(state);
+}
+/** 有换行 chunk：首段补完 pending 行、中段为完整行、末段为新的 partial tail。 */
+function handleChunkWithNewline(state, segments) {
+    state.partialFragments.push(segments[0]);
+    state.partialBytes += segments[0].length;
+    state.completeLines.push(state.partialFragments.join(''));
+    state.partialFragments.length = 0;
+    state.partialBytes = 0;
+    for (let i = 1; i < segments.length - 1; i++) {
+        state.completeLines.push(segments[i]);
+    }
+    state.partialFragments.push(segments[segments.length - 1]);
+    state.partialBytes = segments[segments.length - 1].length;
+    // 单个 >10MB 且内部无换行的 chunk，其尾部 partial 自身也可能超限。
+    if (state.partialBytes > state.partialByteLimit)
+        flushOversizePartial(state);
+}
+function onDataChunk(state, chunk) {
+    // StringDecoder 按字节边界解码：多字节字符被 chunk 边界切开时裸 toString
+    // 会产出不可逆的 U+FFFD（同族修复见 jsonrpc/transport.ts）。
+    const text = state.decoder.write(chunk);
+    const segments = text.split('\n');
+    if (segments.length === 1) {
+        handleChunkWithoutNewline(state, segments[0]);
+    }
+    else {
+        handleChunkWithNewline(state, segments);
+    }
+    enqueueCompleteLines(state);
+    notify(state);
+    maybePause(state);
+}
+function onStdoutError(state, err) {
+    getLogger().warn(`[jsonl-stream] stdout error: ${err.message}`);
+    flushAndFinish(state);
+}
+async function* jsonlGenerator(state) {
+    while (true) {
+        while (state.lineQueue.length > 0) {
+            const line = state.lineQueue.shift();
+            try {
+                yield JSON.parse(line);
+            }
+            catch {
+                if (state.options?.onParseError) {
+                    state.options.onParseError(line);
+                }
+                else {
+                    getLogger().warn(`[jsonl-stream] failed to parse JSONL: ${line.slice(0, 100)}`);
+                }
+            }
+            maybeResume(state);
+        }
+        if (state.done)
+            return;
+        await new Promise((r) => {
+            state.resolveNext = r;
+        });
+    }
+}
 /**
  * Parse JSONL (newline-delimited JSON) from a readable stream.
  *
@@ -22,193 +149,33 @@ import { StringDecoder } from 'node:string_decoder';
  * (统一方案：所有 runner 自己生成 timestamp).
  */
 export function createJSONLStream(stdout, options) {
-    const lineQueue = [];
-    // accumulate partial-line fragments in an array instead of repeatedly
-    // string-concatenating a growing `partialLine`. A huge single JSON line
-    // (large tool_result / text_end) spanning many chunks caused O(n²) copies:
-    // each chunk rebuilt `partialLine + text` over the whole accumulated prefix.
-    // With a fragment array, we join only once per chunk (at the line boundary)
-    // and push complete lines; the residual tail stays as array fragments until
-    // the next newline or stream end. Net allocation: O(n) instead of O(n²).
-    const partialFragments = [];
-    // 跨 chunk 多字节字符的边界安全解码器（见 stdout 'data' 处理）。
-    const decoder = new StringDecoder('utf8');
-    // accumulated byte length of partialFragments. Backpressure (above)
-    // only counts COMPLETE lines in lineQueue; a never-newline stream (malformed
-    // output, binary garbage) accumulates fragments without ever completing a
-    // line, so pause never fires and memory grows unbounded. Cap the partial
-    // line at 10MB: once exceeded, flush it as a bad line via onParseError and
-    // reset the buffer, bounding peak memory for a single pathological line.
-    const PARTIAL_BYTE_LIMIT = 10 * 1024 * 1024;
-    let partialBytes = 0;
-    const completeLines = [];
-    let done = false;
-    let resolveNext = null;
-    // backpressure thresholds. Default matches production (100).
     const pauseThreshold = options?.pauseThreshold ?? 100;
-    // Default low-water mark is half the high-water mark for meaningful hysteresis
-    // (avoids per-line pause/resume thrashing when callers don't set it explicitly).
-    let resumeThreshold = options?.resumeThreshold ?? Math.max(0, Math.floor(pauseThreshold / 2));
-    // Clamp misconfiguration: resumeThreshold > pauseThreshold would resume at queue
-    // high water then immediately re-pause on the next line → thrash (nit).
-    if (resumeThreshold > pauseThreshold)
-        resumeThreshold = pauseThreshold;
-    let paused = false;
-    function notify() {
-        if (resolveNext) {
-            resolveNext();
-            resolveNext = null;
-        }
-    }
-    // Flush any trailing partial line and mark the stream finished. Shared by the
-    // 'end'/'close'/'error' handlers so flush logic lives in one place (nit).
-    function flushAndFinish() {
-        // decoder.end() 吐出被 chunk 边界切开的最后一个多字节字符的残余字节
-        //（无残尾时返回空串）：不加这句，末尾被切开的字符会凭空丢失。
-        const tail = decoder.end();
-        if (tail)
-            partialFragments.push(tail);
-        if (partialFragments.length > 0) {
-            const trimmed = partialFragments.join('').trim();
-            if (trimmed)
-                lineQueue.push(trimmed);
-            partialFragments.length = 0;
-            partialBytes = 0;
-        }
-        done = true;
-        notify();
-    }
-    // flush an oversize partial line as a bad line. When partialFragments
-    // exceeds the byte cap, the partial line is treated as malformed (a single
-    // JSON line should never reach 10MB) and reported via onParseError rather
-    // than accumulated indefinitely. Resets the buffer so a pathological stream
-    // cannot leak memory line after line.
-    function flushOversizePartial() {
-        if (partialFragments.length === 0)
-            return;
-        const line = partialFragments.join('');
-        partialFragments.length = 0;
-        partialBytes = 0;
-        const trimmed = line.trim();
-        if (!trimmed)
-            return;
-        if (options?.onParseError) {
-            options.onParseError(trimmed);
-        }
-        else {
-            getLogger().warn(`[jsonl-stream] dropped oversize partial line (${line.length} bytes)`);
-        }
-    }
-    // Apply backpressure after pushing new lines: pause stdout when the queue
-    // exceeds the high-water mark so the producer stops feeding until the
-    // consumer drains it.bounds memory in long runs.
-    function maybePause() {
-        if (pauseThreshold > 0 && !paused && lineQueue.length > pauseThreshold) {
-            paused = true;
-            stdout.pause();
-        }
-    }
-    // Release backpressure after consuming a line: resume stdout once the queue
-    // drains to the low-water mark so the producer can feed again.
-    function maybeResume() {
-        if (paused && lineQueue.length <= resumeThreshold) {
-            paused = false;
-            stdout.resume();
-        }
-    }
-    stdout.on('data', (chunk) => {
-        // StringDecoder 按字节边界解码：多字节字符（中文/emoji）被 chunk 边界
-        // 切开时，裸 toString 会产出不可逆的 U+FFFD（同族修复见
-        // jsonrpc/transport.ts，claude 的中文输出走本流）。
-        const text = decoder.write(chunk);
-        // split on newlines. The first segment continues the pending partial
-        // line (joined with accumulated fragments — one join per chunk, not per
-        // byte); subsequent segments are complete lines. The last segment is the
-        // new partial tail (kept as a single fragment).
-        const segments = text.split('\n');
-        if (segments.length === 1) {
-            // No newline in this chunk: the whole chunk is a partial fragment.
-            partialFragments.push(segments[0]);
-            partialBytes += segments[0].length;
-            // cap the partial line. A never-newline stream would otherwise
-            // accumulate fragments without bound (backpressure only counts complete
-            // lines). Flush as a bad line once the byte cap is exceeded.
-            if (partialBytes > PARTIAL_BYTE_LIMIT) {
-                flushOversizePartial();
-            }
-        }
-        else {
-            // First segment completes the pending line.
-            partialFragments.push(segments[0]);
-            partialBytes += segments[0].length;
-            completeLines.push(partialFragments.join(''));
-            partialFragments.length = 0;
-            partialBytes = 0;
-            // Middle segments are each complete lines.
-            for (let i = 1; i < segments.length - 1; i++) {
-                completeLines.push(segments[i]);
-            }
-            // Last segment is the new partial tail.
-            partialFragments.push(segments[segments.length - 1]);
-            partialBytes = segments[segments.length - 1].length;
-            // the trailing partial tail can itself exceed the cap if a single
-            // chunk is larger than 10MB with no internal newline.
-            if (partialBytes > PARTIAL_BYTE_LIMIT) {
-                flushOversizePartial();
-            }
-        }
-        // Push complete lines into the queue (skipping blank/whitespace-only).
-        for (const line of completeLines) {
-            const trimmed = line.trim();
-            if (trimmed)
-                lineQueue.push(trimmed);
-        }
-        completeLines.length = 0;
-        notify();
-        maybePause();
-    });
-    stdout.on('end', () => {
-        flushAndFinish();
-    });
-    stdout.on('close', () => {
-        flushAndFinish();
-    });
-    // handle stdout 'error' so the generator terminates instead of
-    // hanging forever on the `await new Promise` below. Without this, a stdout
-    // error (e.g. broken pipe, runner crash) leaves the consumer awaiting a
-    // notify that never comes → bridge serial queue blocks permanently. We do
-    // not re-throw the error through the generator (the runner's `try/catch`
-    // around `for await` and the proc 'close' path already surface failures via
-    // the unified result event); we only guarantee the generator ends. The error
-    // is logged for diagnosis.
-    stdout.on('error', (err) => {
-        getLogger().warn(`[jsonl-stream] stdout error: ${err.message}`);
-        flushAndFinish();
-    });
-    async function* generator() {
-        while (true) {
-            while (lineQueue.length > 0) {
-                const line = lineQueue.shift();
-                try {
-                    yield JSON.parse(line);
-                }
-                catch {
-                    if (options?.onParseError) {
-                        options.onParseError(line);
-                    }
-                    else {
-                        getLogger().warn(`[jsonl-stream] failed to parse JSONL: ${line.slice(0, 100)}`);
-                    }
-                }
-                maybeResume();
-            }
-            if (done)
-                return;
-            await new Promise((r) => {
-                resolveNext = r;
-            });
-        }
-    }
-    return generator();
+    const state = {
+        lineQueue: [],
+        partialFragments: [],
+        decoder: new StringDecoder('utf8'),
+        completeLines: [],
+        done: false,
+        resolveNext: null,
+        partialBytes: 0,
+        pauseThreshold,
+        // 默认低水位为高水位一半，避免逐行 pause/resume 抖动（调用方未显式设置时）。
+        resumeThreshold: options?.resumeThreshold ?? Math.max(0, Math.floor(pauseThreshold / 2)),
+        paused: false,
+        // 单条 never-newline 流的 fragment 上限（10MB），防内存无界增长。
+        partialByteLimit: 10 * 1024 * 1024,
+        stdout,
+        options,
+    };
+    // 误配（resumeThreshold > pauseThreshold）会在高水位立刻 re-pause，钳到高水位。
+    if (state.resumeThreshold > state.pauseThreshold)
+        state.resumeThreshold = state.pauseThreshold;
+    stdout.on('data', (chunk) => onDataChunk(state, chunk));
+    stdout.on('end', () => flushAndFinish(state));
+    stdout.on('close', () => flushAndFinish(state));
+    // stdout error 只保证 generator 结束并记日志，不向 generator 重抛（runner
+    // 的 try/catch 与 proc close 路径已统一上报失败）；否则 consumer 会永久挂住。
+    stdout.on('error', (err) => onStdoutError(state, err));
+    return jsonlGenerator(state);
 }
 //# sourceMappingURL=jsonl-stream.js.map

package/dist/runner/common/jsonrpc/client.d.ts

@@ -19,6 +19,35 @@ export declare class RpcTimeoutError extends Error {
 export declare class ConnectionLostError extends Error {
     constructor(message?: string);
 }
+/** Minimal shape of a pending request entry shared by JSON-line RPC clients. */
+export interface RpcPendingEntry {
+    timer: ReturnType<typeof setTimeout>;
+    reject: (err: Error) => void;
+}
+/** Reject + clear all in-flight requests (dispose / transport-close path). */
+export declare function rejectAllPending<K, V extends RpcPendingEntry>(pending: Map<K, V>, err: Error): void;
+/** Per-client inputs for the shared dispose sequence. */
+export interface RpcDisposeContext<K, V extends RpcPendingEntry> {
+    alreadyDisposed: boolean;
+    markDisposed(): void;
+    pending: Map<K, V>;
+    close(): Promise<void>;
+    disposedMessage: string;
+}
+/**
+ * Shared dispose sequence: no-op when already disposed, else mark
+ * disposed + not-ready, reject pending, and close the transport. The pi RPC
+ * client reuses this; only the disposed error message differs per client.
+ */
+export declare function disposeRpcClient<K, V extends RpcPendingEntry>(ctx: RpcDisposeContext<K, V>): Promise<void>;
+/**
+ * Dispose a client instance from its shared lifecycle shape. JsonRpcClient and
+ * PiRpcClient both delegate here so the dispose sequence has a single
+ * implementation; only the pending map and the disposed message differ.
+ * `client` is typed as object because the two classes keep `_disposed` /
+ * `_ready` private — the shape is asserted locally.
+ */
+export declare function disposeRpcClientInstance<K, V extends RpcPendingEntry>(client: object, pending: Map<K, V>, close: () => Promise<void>, disposedMessage?: string): Promise<void>;
 export interface ClientHooks {
     onNotification(method: string, params: unknown): void;
     onServerRequest(id: number | string, method: string, params: unknown): void;

package/dist/runner/common/jsonrpc/client.js

@@ -33,6 +33,46 @@ export class ConnectionLostError extends Error {
         this.name = 'ConnectionLostError';
     }
 }
+/** Reject + clear all in-flight requests (dispose / transport-close path). */
+export function rejectAllPending(pending, err) {
+    for (const entry of pending.values()) {
+        clearTimeout(entry.timer);
+        entry.reject(err);
+    }
+    pending.clear();
+}
+/**
+ * Shared dispose sequence: no-op when already disposed, else mark
+ * disposed + not-ready, reject pending, and close the transport. The pi RPC
+ * client reuses this; only the disposed error message differs per client.
+ */
+export async function disposeRpcClient(ctx) {
+    if (ctx.alreadyDisposed)
+        return;
+    ctx.markDisposed();
+    rejectAllPending(ctx.pending, new ConnectionLostError(ctx.disposedMessage));
+    await ctx.close();
+}
+/**
+ * Dispose a client instance from its shared lifecycle shape. JsonRpcClient and
+ * PiRpcClient both delegate here so the dispose sequence has a single
+ * implementation; only the pending map and the disposed message differ.
+ * `client` is typed as object because the two classes keep `_disposed` /
+ * `_ready` private — the shape is asserted locally.
+ */
+export function disposeRpcClientInstance(client, pending, close, disposedMessage = 'client disposed') {
+    const state = client;
+    return disposeRpcClient({
+        alreadyDisposed: state._disposed,
+        markDisposed: () => {
+            state._disposed = true;
+            state._ready = false;
+        },
+        pending,
+        close,
+        disposedMessage,
+    });
+}
 // =============================================================================
 // Client
 // =============================================================================
@@ -184,13 +224,8 @@ export class JsonRpcClient {
     /**
      * Dispose the client: cancel pending requests and close transport.
      */
-    async dispose() {
-        if (this._disposed)
-            return;
-        this._disposed = true;
-        this._ready = false;
-        this.failPending(new ConnectionLostError('client disposed'));
-        await this.transport.close();
+    dispose() {
+        return disposeRpcClientInstance(this, this.pendingRequests, () => this.transport.close());
     }
     // =========================================================================
     // Internal
@@ -238,11 +273,7 @@ export class JsonRpcClient {
         getLogger().warn(`[jsonrpc-client] unknown message type: ${JSON.stringify(message).slice(0, 200)}`);
     }
     failPending(err) {
-        for (const [_id, pending] of this.pendingRequests) {
-            clearTimeout(pending.timer);
-            pending.reject(err);
-        }
-        this.pendingRequests.clear();
+        rejectAllPending(this.pendingRequests, err);
     }
 }
 //# sourceMappingURL=client.js.map

package/dist/runner/common/jsonrpc/connection-manager.d.ts

@@ -151,8 +151,8 @@ export declare class ConnectionManager<TClient extends ConnectionClient = JsonRp
      * 定时器回调带 **slot 身份校验**：武装之后 slot 可能已被替换——进程自退走
      * baseOnClose（删 slot 但不经过 disposeSlot）、或同 cwd 已 acquire 了新连接。
      * 这两种情况下本定时器都已过期，不得回收「当时恰好挂在该 cwd 上」的连接：
-     * 2026-10-24 线上事故即一条泄漏的过期 TTL 杀掉继任连接的在途 turn，卡片
-     * 误报 "Codex app-server connection closed"。
+     * 一条泄漏的过期 TTL 会杀掉继任连接的在途 turn，卡片误报
+     * "Codex app-server connection closed"。
      */
     notifyIdle(cwd: string): void;
     private createClient;

package/dist/runner/common/jsonrpc/connection-manager.js

@@ -197,8 +197,8 @@ export class ConnectionManager {
      * 定时器回调带 **slot 身份校验**：武装之后 slot 可能已被替换——进程自退走
      * baseOnClose（删 slot 但不经过 disposeSlot）、或同 cwd 已 acquire 了新连接。
      * 这两种情况下本定时器都已过期，不得回收「当时恰好挂在该 cwd 上」的连接：
-     * 2026-10-24 线上事故即一条泄漏的过期 TTL 杀掉继任连接的在途 turn，卡片
-     * 误报 "Codex app-server connection closed"。
+     * 一条泄漏的过期 TTL 会杀掉继任连接的在途 turn，卡片误报
+     * "Codex app-server connection closed"。
      */
     notifyIdle(cwd) {
         if (this.idleTtlMs <= 0)
@@ -245,8 +245,8 @@ export class ConnectionManager {
                 if (current?.client === client) {
                     // 进程自退（codex app-server 偶发 exit 0，非本程序发起，不经
                     // disposeSlot）也要撤掉挂在旧 slot 上的 idle TTL：定时器不随 slot
-                    // 删除而取消，到期时会按 cwd 误杀继任连接的在途 turn（2026-10-24
-                    // 线上事故，见 notifyIdle 的身份校验与对应回归测试）。
+                    // 删除而取消，到期时会按 cwd 误杀继任连接的在途 turn（见 notifyIdle
+                    // 的身份校验与对应回归测试）。
                     this.clearIdleTimer(current);
                     this.slots.delete(cwd);
                     this.onConnectionLost?.(cwd);

package/dist/runner/common/spawning-runner.d.ts

@@ -4,7 +4,7 @@ import { type Terminator } from '../../platform/terminator.js';
 import { SpawnHeartbeat } from './spawn-heartbeat.js';
 import type { SpawnOptions } from '../types.js';
 /**
- * 进程级退出监听单例分发（修复，2026-08-02）。
+ * 进程级退出监听单例分发。
  *
  * 背景：各 agent runner 的 registerExitHandlers 曾是同构复制，每个实例
  * process.on('exit'|'SIGINT'|'SIGTERM') 注册 3 个永不移除的闭包（捕获整个
@@ -27,6 +27,11 @@ interface ExitCleanupHandler {
 }
 /** Register a process-exit cleanup handler (installs listeners at most once). */
 export declare function registerExitCleanup(handler: ExitCleanupHandler): void;
+/**
+ * 子进程存活性判定（SpawningRunner 与 BashProcessRunner 的 `isRunning` 共用）。
+ * 两边曾是逐字相同的一段表达式，抽到共同依赖模块避免漂移。
+ */
+export declare function isChildProcessRunning(proc: ChildProcess | null): boolean;
 /**
  * pid 文件名的 workspace 后缀：`-<消毒 cwd>-<cwd hash>`。
  *

package/dist/runner/common/spawning-runner.js

@@ -54,6 +54,13 @@ export function registerExitCleanup(handler) {
     installExitListenersOnce();
     registeredRunners.add(handler);
 }
+/**
+ * 子进程存活性判定（SpawningRunner 与 BashProcessRunner 的 `isRunning` 共用）。
+ * 两边曾是逐字相同的一段表达式，抽到共同依赖模块避免漂移。
+ */
+export function isChildProcessRunning(proc) {
+    return proc !== null && proc.exitCode === null && proc.signalCode === null;
+}
 /**
  * FNV-1a 32 位哈希（hex，平台无关确定性）：pid 文件后缀的消歧段。
  */
@@ -154,9 +161,7 @@ export class SpawningRunner {
         this.spawnHeartbeat = new SpawnHeartbeat(opts.spawnHeartbeatMs ?? 30_000, this.logTag);
     }
     get isRunning() {
-        return (this.currentProcess !== null &&
-            this.currentProcess.exitCode === null &&
-            this.currentProcess.signalCode === null);
+        return isChildProcessRunning(this.currentProcess);
     }
     // --- Hooks (subclasses override as needed) ---
     /**
@@ -357,7 +362,7 @@ export class SpawningRunner {
             // matchMode 'agent-invocation'（不是默认的 'executable'）：agent CLI 普遍是
             // `#!/usr/bin/env node` 脚本，ps 看到的是 `node <安装路径>/…/cli.js`，名字只在
             // 路径段里（pi → @earendil-works/pi-coding-agent/…）。用默认档会恒判 mismatch
-            // → 这些 agent 的孤儿永远回收不掉（2026-09-20 实测安装形态）。
+            // → 这些 agent 的孤儿永远回收不掉。
             const verdict = verifyPidIdentityVerdictSync(pid, {
                 expectedBinary,
                 matchMode: 'agent-invocation',

package/dist/runner/common/turn-started.d.ts

@@ -1,2 +1,10 @@
 import type { TurnStartedEvent } from '../types.js';
 export declare function makeTurnStartedEvent(sessionId: string, turnId: string, operationKind: 'turn' | 'compact'): TurnStartedEvent;
+/**
+ * 自产 turn_started 事件的完整序列：先让调用方记录 per-turn 状态，再构造事件。
+ *
+ * ACP（`BaseAcpTranslator`）与 pi（`PiRpcTranslator`）的 `produceTurnStarted`
+ * 曾是逐字同形的两段；唯一差异是记录的字段（currentTurnId / sessionId），
+ * 由 `recordState` 注入，共同序列收编在此，避免两处方法体漂移。
+ */
+export declare function produceTurnStartedEvent(sessionId: string, turnId: string, operationKind: 'turn' | 'compact', recordState: (sessionId: string, turnId: string) => void): TurnStartedEvent;

package/dist/runner/common/turn-started.js

@@ -7,4 +7,15 @@ export function makeTurnStartedEvent(sessionId, turnId, operationKind) {
         timestamp: new Date().toISOString(),
     };
 }
+/**
+ * 自产 turn_started 事件的完整序列：先让调用方记录 per-turn 状态，再构造事件。
+ *
+ * ACP（`BaseAcpTranslator`）与 pi（`PiRpcTranslator`）的 `produceTurnStarted`
+ * 曾是逐字同形的两段；唯一差异是记录的字段（currentTurnId / sessionId），
+ * 由 `recordState` 注入，共同序列收编在此，避免两处方法体漂移。
+ */
+export function produceTurnStartedEvent(sessionId, turnId, operationKind, recordState) {
+    recordState(sessionId, turnId);
+    return makeTurnStartedEvent(sessionId, turnId, operationKind);
+}
 //# sourceMappingURL=turn-started.js.map