@zhushanwen/pi-subagent-cli 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,784 @@
+import { ToolCall, AgentFailureKind, ReplayRecordView, AgentEvent, UiRequest, UiResponse, HostStreamDeltaParams, HostRoundLifecycleParams, EngineStream, InteractResult, EnginePort, EngineCapabilities, ProbeReport, EngineAgentCallOpts, RunContext, EngineHandle, AgentOutcome, InteractAction, SessionView, ReverseRequestClock, ToolCallResult, UiRequestHandler } from '@zhushanwen/subagent-engine-sdk';
+export { ParsedChannel, parseChannel } from '@zhushanwen/subagent-engine-sdk';
+import { ChildProcess } from 'node:child_process';
+
+/** spawn 调用描述符：command + args（透传给 spawnEngineChild）。 */
+interface PiInvocation {
+    /** 可执行文件路径（node/bun/pi 二进制）。 */
+    command: string;
+    /** 命令行参数（可能含 [scriptPath, ...userArgs] 或直接 [...userArgs]）。 */
+    args: string[];
+}
+/** getPiInvocation 可选项。 */
+interface PiInvocationOptions {
+    /**
+     * false = 强制直连 spawn 真实 pi（不经 relay 代理）。唯一现役消费点是 probe
+     * ——探针意图是 pi 本体可解析性，经 relay 探到的是 runtime 健康，语义错位。
+     */
+    relay?: boolean;
+}
+declare function getPiInvocation(userArgs: string[], opts?: PiInvocationOptions): PiInvocation;
+
+/**
+ * 镜像 flag 集合：从主进程 argv 解析出的可透传给子进程的 flag。
+ * 面向 buildSpawnArgs 的入参形态（解析后）。undefined 字段语义与解析为空一致。
+ */
+interface MirrorFlags {
+    noExtensions: boolean;
+    approve: boolean;
+    extensionPaths: string[];
+    noContextFiles: boolean;
+}
+declare function mirrorMainProcessFlags(argv: readonly string[]): MirrorFlags;
+
+/**
+ * Stale context 检测模式（P1-5；W4b 对齐 pi 0.84.x 真实文案）。
+ * 命中时分诊 failureKind="stale_context"——重试只会再次失败。
+ */
+declare const STALE_CONTEXT_PATTERNS: readonly ["ctx is stale", "stale after session replacement", "context canceled", "aborted"];
+/** 判断错误信息是否表示 stale/canceled pi session context。 */
+declare function isStaleContextErrorMsg(msg: string | undefined): boolean;
+/**
+ * [MF-1] 确定性 schema 失败标记（error 文本前缀，产出方 = 本模块的
+ * describeMissingParsedOutput）。标记词与 stale 词表零交集（防归因污染）。
+ */
+declare const DETERMINISTIC_SCHEMA_FAILURE_PREFIX = "Structured output failed deterministically:";
+/** [MF-1] 判断错误信息是否为确定性 schema 失败（命中标记前缀）。 */
+declare function isDeterministicSchemaFailureMsg(msg: string | undefined): boolean;
+/**
+ * [D5-③] 错误文案 → 结构化失败分诊标签（产出侧唯一识别点，stale 在前）。
+ * 未命中任何词表 → unknown——消费侧默认退避重试（语义守恒）。
+ */
+declare function classifyFailureKind(msg: string | undefined): AgentFailureKind | undefined;
+/** collectOutcome 的入参（session 身份 + 执行控制字段，执行内容从 record 读）。 */
+interface CollectResultArgs {
+    startTime: number;
+    success: boolean;
+    error: string | undefined;
+    sessionId: string;
+    sessionFile: string | undefined;
+    /**
+     * [F-1] 本次执行是否要求结构化产出（schema 或 schemaEnv 任一存在）。
+     * true 且 run 结束仍无有效 parsedOutput 时：结果不得静默 success。
+     */
+    schemaExpected?: boolean;
+}
+/**
+ * 从 toolCalls 提取 structured-output 的 result.details（schema 模式产出）。
+ * isError:true 的调用一律跳过（失败调用的 details 不是通过校验的产出）。
+ */
+declare function extractParsedOutput(toolCalls: ToolCall[]): unknown;
+/**
+ * [F-R1] 中和动态错误摘要中的 stale-context 命中词（大小写不敏感子串替换为
+ * "[redacted]"——防拼接结果被 classifyFailureKind 误诊 stale_context）。
+ */
+declare function neutralizeStalePatterns(text: string): string;
+/**
+ * schema 模式下无有效 parsedOutput 时的三态失败归因（F-1）。
+ * 三态判定优先级：校验失败（有 isError 调用）> 从未调用 SO tool > 调用过但无 details。
+ */
+declare function describeMissingParsedOutput(toolCalls: ToolCall[]): string | undefined;
+/** 引擎侧 run 收集结果（AgentOutcome 的载荷装配点）。 */
+interface CollectedOutcome {
+    content: string;
+    turns: number;
+    durationMs: number;
+    success: boolean;
+    error: string | undefined;
+    sessionId: string;
+    sessionFile: string | undefined;
+    toolCalls: ToolCall[];
+    parsedOutput: unknown;
+    usage: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        cost?: number;
+    } | undefined;
+    failureKind: AgentFailureKind | undefined;
+}
+/**
+ * 从 ReplayRecordView + args 组装引擎侧结果。
+ *
+ * success 双来源判定（调用方传入）：
+ *   ① 子进程 spawn/执行失败 → args.success=false
+ *   ② 执行成功但 record.lastError 非空（message_end stopReason=error）→ success=false
+ */
+declare function collectOutcome(record: ReplayRecordView, args: CollectResultArgs): CollectedOutcome;
+
+/** 按 record 取活跃子进程（undefined = 无句柄，对齐 getChildByRecord 语义）。 */
+declare function getActiveChild(recordId: string): ChildProcess | undefined;
+/** 全量收割（dispose）：SIGTERM + 30s SIGKILL 升级；返回收割数。 */
+declare function killAllActiveChildren(signal?: NodeJS.Signals): number;
+
+/** run 的宿主回调面（server.ts 注入：协议通知 + host/* 反向请求）。 */
+interface SpawnRunCallbacks {
+    /** AgentEvent 出口（→ `event` 通知，runId + 单调 seq 由 server 层组装）。 */
+    onEvent: (event: AgentEvent) => void;
+    /** sessionFile/sessionId 就绪回填（→ host/handleReady）。 */
+    onHandleReady?: (partial: {
+        sessionRef: Record<string, string>;
+        poolKey: string;
+    }) => void;
+    /** 一次性子进程 pid 上报（→ host/childSpawned）。 */
+    onChildSpawned?: (pid: number, recordId: string) => void;
+    /** 子进程状态变更（→ host/childStateChanged；killed 必含）。 */
+    onChildStateChanged?: (p: {
+        pid: number;
+        recordId: string;
+        state: "running" | "exited";
+        killed: boolean;
+        exitCode?: number;
+        signal?: string;
+    }) => void;
+    /** host/askUser 两阶段等待体（handler 缺失时队列自动 cancelled 降级）。 */
+    askUser?: (request: UiRequest) => Promise<UiResponse>;
+    /** text_delta 分流出口（→ host/streamDelta）。 */
+    onDelta?: (delta: string) => void;
+    /**
+     * [chatMode] agent_end（非 willRetry，队列排空）到达：本轮收敛。不 kill 子进程
+     * （长驻），由调用方（chat-session）上报 roundLifecycle settled 相位。
+     */
+    onChatRoundEnd?: () => void;
+    /**
+     * [chatMode] agent_settled（真空闲边界）到达：run 在此 resolve（exit 0 口径），
+     * 进程保活。调用方（chat-session）据此上报 idle 相位（usage + anchor）。
+     */
+    onChatAgentSettled?: () => void;
+}
+/** runSpawnOnce 的入参（协议 RunParams 的引擎侧还原形态）。 */
+interface SpawnRunParams {
+    /** record 锚（= run.params.runId；镜像键 / relay RECORD_ID 重写源）。 */
+    recordId: string;
+    /** 完整 task 文本（含 schema 指令——协议 task.prompt）。 */
+    task: string;
+    /** agent 名（slug 派生 + prompt 临时文件名）。 */
+    agentName: string;
+    /** canonical "provider/id"（缺省回落 pi 自身解析）。 */
+    model: string | undefined;
+    /** thinking level 白名单字面量（协议 ctx 透传）。 */
+    thinkingLevel?: string;
+    /** subagent session 目录（--session-dir）。 */
+    sessionDir: string;
+    /** spawn cwd。 */
+    cwd: string;
+    /** schema env JSON 字符串（PI_WORKFLOW_SCHEMA 注入）。 */
+    schemaEnv?: string;
+    /** hard turn limit。 */
+    maxTurns?: number;
+    /** soft limit 后宽限轮数（默认 2）。 */
+    graceTurns?: number;
+    /** 中断信号（协议 cancel → server 层 AbortController）。 */
+    signal?: AbortSignal;
+    /** 根 session id（relay SESSION_ID 重写源，协议 ctx 还原）。 */
+    sessionRootId?: string;
+    /** 追加 system prompt 片段（agent body 之外的调用方片段）。 */
+    appendSystemPrompt?: string[];
+    /** skill 路径（--skill 多值）。 */
+    skillPaths?: string[];
+    /** agent 工具白名单（--tools）。 */
+    agentTools?: string[];
+    /** fork 源 session 文件（--fork）。 */
+    forkSource?: string;
+    /** 镜像 flag 覆盖（缺省自动镜像主进程 argv）。 */
+    mirrorFlags?: MirrorFlags;
+    /** resume 目标 session 文件（冷续写：--session 续写原文件）。 */
+    resumeSessionFile?: string;
+    /**
+     * [v1.x chat 会话形态] 长驻模式：agent_end（非 willRetry）不 kill 子进程（轮收敛
+     * 交 callbacks.onChatRoundEnd 上报），agent_settled（真空闲）resolve run（exit 0
+     * 口径，进程保活——对齐 inproc chatMode「进程长驻」语义）。缺省 = 一次性 run。
+     */
+    chatMode?: boolean;
+}
+/** runSpawnOnce 的产物。 */
+interface SpawnRunResult extends Omit<CollectedOutcome, "sessionId"> {
+    /** 会话头身份（header / get_state 握手回填；全 miss 时 undefined）。 */
+    sessionId: string | undefined;
+}
+declare function runSpawnOnce(params: SpawnRunParams, callbacks: SpawnRunCallbacks): Promise<SpawnRunResult>;
+
+/** 引擎 → 宿主反向通道发射面（server 构造后注入；roundLifecycle/streamDelta 为 v1.x 新面）。 */
+interface ChatHostChannels {
+    /** host/streamDelta（续聊轮 recordId 键形态；首轮 runId 键经 server 既有 run wiring）。 */
+    streamDelta(params: HostStreamDeltaParams): void;
+    /** host/roundLifecycle（三相位；键形态由会话状态决定：首轮 runId / 续聊 recordId）。 */
+    roundLifecycle(params: HostRoundLifecycleParams): void;
+    /** host/askUser（chat 会话跨 run 存活，runId 固定为 spawn 轮的 runId——W3 消费注意）。 */
+    askUser(runId: string, request: UiRequest): Promise<UiResponse>;
+}
+/** startRound 的宿主回调面（server 注入：首轮事件通知 + run 键 delta + handle 回填）。 */
+interface ChatRoundStartOptions {
+    /** spawn 轮的 runId（首轮 roundLifecycle/streamDelta 关联键 + askUser 关联键）。 */
+    runId: string;
+    /** 首轮 AgentEvent 出口（→ `event` 通知，runId + seq 由 server 层组装）。 */
+    onEvent(event: AgentEvent): void;
+    /** 首轮 text_delta 出口（runId 键——经 server 既有 stream wiring）。 */
+    stream?: EngineStream;
+    onHandleReady?(partial: {
+        sessionRef: Record<string, string>;
+        poolKey: string;
+    }): void;
+    onChildSpawned?(pid: number, recordId: string): void;
+}
+/** 会话 spawn 执行器（缺省 runSpawnOnce chatMode 形态；测试注入 fake）。 */
+type ChatSpawnExecutor = (params: SpawnRunParams, callbacks: SpawnRunCallbacks) => Promise<SpawnRunResult>;
+/** ChatSessionRegistry 构造依赖。 */
+interface ChatSessionRegistryDeps {
+    spawnRunner?: ChatSpawnExecutor;
+}
+/**
+ * chat 会话注册表（引擎进程内的长驻会话状态面）。
+ *
+ * 生命周期：startRound（首轮/冷续 spawn）建立会话 → 首轮 agent_settled 后 run 应答、
+ * 进程保活 → interact message 续聊轮（recordId 键事件）→ interact close / cancel /
+ * 子进程退出消亡。dispose 收割由 spawn-runner 的 killAllActiveChildren 兜底（PiEngine
+ * dispose 调用），会话条目随子进程 close 事件自清。
+ */
+declare class ChatSessionRegistry {
+    private readonly executor;
+    private channels;
+    private readonly sessions;
+    constructor(deps?: ChatSessionRegistryDeps);
+    /** server 构造后注入反向通道发射面（未注入 = 无宿主面：帧丢弃 + askUser 自动 cancelled）。 */
+    bindHostChannels(channels: ChatHostChannels | undefined): void;
+    /** recordId 是否有活会话（interact 路由判据；不建立会话）。 */
+    has(recordId: string): boolean;
+    /**
+     * run 会话形态入口（首轮 + 冷续）：spawn 长驻子进程 + 首轮 prompt，本轮 agent_settled
+     * （真空闲）时 resolve（exit 0 口径，进程保活——对齐 inproc chatMode 首轮 resolve 语义）。
+     * resume 锚点存在 = 冷续（--session 续写原文件），不存在 = 首轮新建。
+     */
+    startRound(params: SpawnRunParams, opts: ChatRoundStartOptions): Promise<SpawnRunResult>;
+    /**
+     * interact message 热路径：prompt + streamingBehavior 直写 stdin（pi 权威裁决
+     * busy/idle：busy 时 followUp 入队 / steer 抢占，idle 时开新 turn——pi 上游语义，
+     * abort 不清 followUp 队列）。冷路径（无活进程）→ engine_session_not_resumable +
+     * 冷续指引（宿主发新 run chat+resume 接续，D1-A）。
+     */
+    deliverMessage(recordId: string, text: string, interrupt: boolean): InteractResult;
+    /**
+     * interact close：force = 立即杀链收割（在途轮 → failed aborted）；缺省 = 优雅关闭
+     * （在途轮标记 closeAfterRound，agent_settled 收口后收割——对齐 inproc closeSubagent
+     * 的 force 分流）；idle 态（无在途轮）立即收割（对齐 closeChatIdle 的进程回收）。
+     */
+    close(recordId: string, force: boolean): InteractResult;
+    /**
+     * interact cancel（D3 协议层收敛语义，对齐 run 域 cancel 形态）：
+     * 受理（SIGTERM——run 域 AbortController→SIGTERM 同构）→ 等待目标轮次终态相位
+     * （roundLifecycle settled/idle/failed）→ 超 CANCEL_SETTLE_GRACE_MS 未收敛走与
+     * run 域同构的杀链升级（SIGTERM → grace → SIGKILL）。应答在收敛/升级完成后返回
+     * （协议层收敛语义）；无在途轮时无收敛对象，受理即返回（进程回收经 close 事件收口）。
+     */
+    cancel(recordId: string): Promise<InteractResult>;
+    /** agent_end（非 willRetry，队列排空）：本轮收敛 → settled 相位（带本轮用量）。 */
+    private handleRoundEnd;
+    /** agent_settled（真空闲）：idle 相位（usage + anchor 回填）+ 优雅关闭收割。 */
+    private handleAgentSettled;
+    /** 子进程退出：会话消亡；在途轮 → failed 相位（引擎主动杀 = aborted / 否则 crashed）。 */
+    private handleChildExited;
+    /**
+     * 相位发射（关联键 = 首轮 runId / 续聊 recordId）+ 轮终等待体逐一 resolve。
+     * superseded 会话抑制宿主发射（S5，守卫放单一咽喉点而非仅 handleChildExited）：
+     * 同 recordId 冷续 run 已重建会话，旧会话残留终态帧（killChain 杀死在途轮的 failed、
+     * SIGTERM 优雅收口竞态下的 settled+idle——pi trap 语义先收口再退）以 recordId 键发射
+     * 会与新会话在途轮同键串扰，core 可能把旧轮终态误配到新轮（误终态化）。superseded
+     * 信号本身 = 新 run 的 start（宿主主动发起），core 无需旧会话帧。等待体仍逐一
+     * resolve：cancel 等待中 killReason 被后续冷续覆写为 superseded 的极端时序下收敛
+     * 不悬挂。
+     *
+     * [F-4 S6 引擎半边] 旧轮的 idle 相位（agent_settled 空闲边界）在 settled→idle 间隙
+     * 宿主已投递新轮时抑制宿主发射（`armedSeq !== settledSeq` = settled 以来有新轮 arm，
+     * 该 idle 帧属旧轮——时序恒晚于新轮投递）。与 S6 的 armedSeq 守卫（handleAgentSettled
+     * 保 settled 相位、不清新轮 roundActive）同模式：旧 idle 帧若放行，core 的
+     * handleChatRoundPhase(idle) 无轮次身份可判——disarmRoundFromProtocol 拆掉新轮中段
+     * 守护 + armChatIdleTimer 挂 5min idle timer → 新轮进行中超 5min 被误杀。新轮的
+     * idle 由新轮自身 agent_settled 发射（其 armedSeq === settledSeq）。等待体仍逐一
+     * resolve（在途 cancel 的收敛兜底语义不变）。
+     */
+    private emitPhase;
+    /** message_end 用量累加（轮内增量；interact 轮无 event 通知通道，用量经相位帧回填）。 */
+    private accumulateUsage;
+    /** 轮终等待（cancel 收敛判据；超时 resolve false——不清理其他等待体）。 */
+    private waitForRoundTerminal;
+}
+
+/** PiEngine 构造依赖。 */
+interface PiEngineDeps {
+    /**
+     * 数据根（协议 initialize 的 hostInfo.dataRoot；subagent session 目录相对它推导）。
+     * 缺省读 env XYZ_AGENT_DATA_DIR——两者皆无时 probe 报错（resolveEngineDataDir 语义，
+     * 显式报 engine_not_found 附期望路径，不猜 cwd）。
+     */
+    dataDir?: string;
+    /** 版本探测执行器（测试注入 fake 避免真实子进程）。 */
+    probeVersion?: (invocation: PiInvocation) => Promise<string | undefined>;
+    /** spawn 执行器（测试注入 fake；缺省 runSpawnOnce）。 */
+    spawnRunner?: (params: Parameters<typeof runSpawnOnce>[0], callbacks: SpawnRunCallbacks) => Promise<SpawnRunResult>;
+}
+/** pi 引擎适配器（EnginePort 实现，协议服务器的驱动对象）。 */
+declare class PiEngine implements EnginePort {
+    readonly id = "pi";
+    private readonly deps;
+    private probeCache;
+    /** [v1.x] chat 会话注册表（长驻会话状态面——见 chat-session.ts 文件头）。 */
+    private readonly chatSessions;
+    constructor(deps?: PiEngineDeps);
+    /** pi 链路实际接通的能力（与 core PiEngine.capabilities() 逐位一致——manifest 同源）。 */
+    capabilities(): EngineCapabilities;
+    /** 探针（D7）：invocation 可解析（二进制/脚本存在）+ 版本解析。relay:false 显式
+     *  直连——探针测 pi 本体可解析性，经 relay 探到的是 runtime 健康，语义错位。 */
+    probe(opts?: {
+        force?: boolean;
+    }): Promise<ProbeReport>;
+    /** run 的引擎侧实现：协议 RunParams → spawn-runner 单次执行。
+     *
+     * run 期间事件经 ctx.onEvent（server 层 → `event` 通知）；session 身份经
+     * ctx.onHandleReady（→ host/handleReady）；子进程 pid/状态经镜像回调上报。
+     * 抛错语义（core PiEngine.run ①）：prepare 期失败 reject，不产生 handle。
+     *
+     * [v1.x] ctx.chat 存在 = chat 会话形态（首轮/冷续）：委托 chat-session 长驻执行
+     * （agent_end 不 kill、agent_settled resolve——本轮收口进程保活，续聊经 interact）。 */
+    run(task: EngineAgentCallOpts, ctx: RunContext): Promise<{
+        handle: EngineHandle;
+        outcome: AgentOutcome;
+    }>;
+    /**
+     * [v1.x] run 会话形态主体（首轮/冷续，chat-domain 设计 §3.2 D1-A）：spawn 长驻子进程
+     * + 首轮 prompt，本轮 agent_settled（真空闲）resolve（进程保活）。record 锚定键 =
+     * chat.recordId（区别于一次性 run 的 runId 锚定——interact/roundLifecycle 据此定位）；
+     * resume 锚点存在 = 冷续（--session 续写原文件），不存在 = 首轮新建。
+     */
+    private runChatRound;
+    /**
+     * D1 交互控制面。[v1.x] chat 会话（chat-session 命中）优先路由：
+     *   - message：热路径 sendPromptCommand + streamingBehavior（interrupt=steer 抢占/
+     *     缺省 followUp 排队——pi 上游语义）+ EPIPE 兜底（耗尽 → roundLifecycle failed）；
+     *     冷路径（进程死）→ engine_session_not_resumable + 冷续指引（宿主发新 run chat+resume）；
+     *   - close：force=杀链立即收割 / 缺省=优雅（轮收口后收割）；
+     *   - cancel：D3 收敛语义（受理 → 等轮终相位 → 超 CANCEL_SETTLE_GRACE_MS 杀链升级）。
+     *
+     * 未命中（一次性 run 的活跃子进程 / 冷句柄）走下方既有路径：message 热路径直写、
+     * close = SIGTERM、cancel = SIGTERM（无收敛等待——run 域 cancel 帧另有 AbortController
+     * 通道，收敛由 run 应答承载）。
+     */
+    interact(handle: EngineHandle, action: InteractAction): Promise<InteractResult>;
+    /** chat 会话命中分支（长驻）：cancel/close/message 直派 chat-session
+     *  （close force=杀链立即收割 / 缺省=优雅；message streamingBehavior 由 interrupt 决定）。 */
+    private interactChatSession;
+    /** 未命中分支：一次性 run 的活跃子进程 / 冷句柄——message 热路径直写 stdin、
+     *  close/cancel = SIGTERM（run 域 cancel 帧另有 AbortController 通道，收敛由 run 应答承载）。 */
+    private interactRunDomain;
+    /** message 热路径（进程活）sendPromptCommand 直写 stdin + EPIPE 兜底
+     *  （连续失败达阈值 → 抛错升级为 engine_interact_failed；未达 → not_resumable 降级）。 */
+    private deliverHotPathMessage;
+    /**
+     * read 三级降级（协议化形态）：②级 journal 重放（SDK journal-replay 纯投影）
+     * → ③级 outcome-only。①级 pi 原生读取（session-reconstructor）按 §2.7 保持
+     * core，不随迁（deviations 登记）。
+     */
+    read(handle: EngineHandle): Promise<SessionView>;
+    /** dispose：全量收割活跃子进程 + 清 EPIPE 计数（幂等）。 */
+    dispose(): Promise<void>;
+    private askUserHandler;
+    /** server 层注入 host/askUser 两阶段等待体（ui-request-queue 消费）。 */
+    bindAskUser(handler: ((req: UiRequest) => Promise<UiResponse>) | undefined): void;
+    /**
+     * server 层注入 [v1.x] chat 会话的反向通道发射面（host/roundLifecycle、recordId 键
+     * host/streamDelta、会话级 host/askUser）。会话跨 run 存活，绑定是引擎进程生命周期
+     * 级（区别于一次性 run 的 per-run askUser 绑定）。
+     */
+    bindHostChannels(channels: ChatHostChannels | undefined): void;
+}
+
+/** 出站帧写入面（main.ts 注入 process.stdout；测试注入内存缓冲）。 */
+type FrameWriter = (frame: unknown) => void;
+/** 入站帧来源（readline 已拆行的请求帧 + 反向请求应答帧混流）。 */
+interface EngineProtocolServerOptions {
+    /** stdout 写入面（每帧一行 JSON）。 */
+    write: FrameWriter;
+    /** 引擎实例（缺省 createDefaultPiEngine——测试注入 fake/DI 实例）。 */
+    engine?: EnginePort & {
+        bindAskUser?(handler: ((req: UiRequest) => Promise<UiResponse>) | undefined): void;
+        /** [v1.x] chat 会话反向通道发射面绑定（roundLifecycle / recordId 键 streamDelta）。 */
+        bindHostChannels?(channels: ChatHostChannels | undefined): void;
+    };
+    /** 反向请求计时面（armEngineSelfDestruct 产物；缺省不计时——测试用）。 */
+    reverseClock?: ReverseRequestClock;
+    /** 应答等待缺省超时（反向请求两阶段等待上限兜底；默认 REVERSE_TIMEOUT_DEFAULT_MS）。 */
+    reverseTimeoutMs?: number;
+}
+/** 构造缺省 pi 引擎（main.ts 的 server 构造缺省值；测试注入 fake）。 */
+declare function createDefaultPiEngine(): PiEngine;
+/**
+ * 引擎协议服务器。生命周期 = 进程生命周期（单引擎实例，无重建面——崩溃重建归
+ * core EngineClient：杀进程再 spawn）。dispose 方法释放引擎常驻资源但进程不退出。
+ */
+declare class EngineProtocolServer {
+    private readonly write;
+    private readonly engine;
+    private readonly reverseClock;
+    private readonly reverseTimeoutMs;
+    private readonly activeRuns;
+    private readonly reversePending;
+    /** 10 正向方法 → EnginePort 装配表（构造期冻结；表驱动分发）。 */
+    private readonly dispatchTable;
+    private revSeq;
+    private initialized;
+    constructor(opts: EngineProtocolServerOptions);
+    /** 入站帧消费（请求帧 + 反向请求应答帧；main.ts 的行解析器拆行后喂入）。 */
+    handleFrame(frame: unknown): void;
+    /** 10 正向方法 → EnginePort 装配表（协议载荷 cast 收敛在各方法适配行）。 */
+    private buildDispatchTable;
+    /** 10 正向方法分发（表驱动；未知方法 → engine_protocol_unknown_method）。 */
+    private dispatch;
+    private initialize;
+    private run;
+    /** run.chat 帧校验 + chat 能力位 gate（A6 方向防御）：recordId 非空 + conversation
+     *  位 unsupported 同步拒——判据单源 = SDK assertChatConversationSupported（与 core
+     *  capability-gate 同一能力位，防两侧判据漂移）。本引擎 manifest 声明 native，
+     *  此处仅防御 manifest/实装漂移。 */
+    private assertChatRunFrame;
+    /** RunContext 装配（协议 ctx 还原 + host/* 反向通道接线；事件 seq 由 emitEvent 计数）。 */
+    private buildRunContext;
+    private cancel;
+    private interact;
+    private read;
+    private validateModel;
+    private emitEvent;
+    /** 反向请求发送（公开面：main.ts 的 host/log 桥接消费；内部 run 通道同路）。 */
+    reverseRequest(method: string, params: unknown): Promise<unknown>;
+    private reverseRequestInternal;
+    /** 反向请求应答落位。
+     *
+     * ack 两阶段（R9-2）：人机交互通道（host/askUser / host/permission）宿主先回
+     * `{ack:true}`——只 ack 计时面（移出 in-flight 自灭计时），**不终结等待**；最终
+     * 结果帧才 settle。数据面通道宿主直接回终态（{ok:true} 等），ack 即 settle。 */
+    private settleReverse;
+}
+
+/** pi 引擎的 registry key（D9：缺省引擎 = 'pi'）。 */
+declare const PI_ENGINE_ID = "pi";
+/** pi 适配器版本（handle.adapterVersion 数据源——golden 样本对齐排查锚点）。 */
+declare const PI_ADAPTER_VERSION = "1.0.0";
+/** pi 无隔离池（PI_CODING_AGENT_DIR 全局一份，设计 §3.3.9），poolKey 恒 'shared'。 */
+declare const PI_POOL_KEY = "shared";
+
+/**
+ * pi stdout 的 SdkEvent 形态（core execution/types.ts SdkEvent 的结构子集——
+ * spawn-runner 的翻译 switch 只消费这些字段；SDK 契约类型未收该类型，包内自持）。
+ */
+interface SdkEvent {
+    type: string;
+    toolCallId?: string;
+    toolName?: string;
+    args?: unknown;
+    result?: ToolCallResult;
+    isError?: boolean;
+    message?: {
+        usage?: {
+            input?: number;
+            output?: number;
+            cacheRead?: number;
+            cacheWrite?: number;
+            cost?: {
+                total: number;
+            };
+        };
+        stopReason?: string;
+        errorMessage?: string;
+    };
+    reason?: string;
+    assistantMessageEvent?: {
+        type?: string;
+        delta?: string;
+    };
+    [key: string]: unknown;
+}
+/** pi stdout header 行（session 元信息）。type 固定为 "session"。 */
+interface SpawnSessionHeader {
+    readonly type: "session";
+    readonly id: string;
+    readonly timestamp: string;
+    readonly cwd: string;
+    readonly parentSession?: string;
+    readonly version?: number;
+}
+/** Pi 原生 extension_ui_request 的方法特定字段（按 method 平铺）。
+ *  与 Pi rpc-types.ts L230-265 的 RpcExtensionUIRequest 1:1 对应。 */
+type ExtensionUiRequest = {
+    method: "select";
+    title: string;
+    options: string[];
+    timeout?: number;
+} | {
+    method: "confirm";
+    title: string;
+    message: string;
+    timeout?: number;
+} | {
+    method: "input";
+    title: string;
+    placeholder?: string;
+    timeout?: number;
+} | {
+    method: "editor";
+    title: string;
+    prefill?: string;
+} | {
+    method: "notify";
+    message: string;
+    notifyType?: "info" | "warning" | "error";
+} | {
+    method: "setStatus";
+    statusKey: string;
+    statusText: string | undefined;
+} | {
+    method: "setWidget";
+    widgetKey: string;
+    widgetLines: string[] | undefined;
+    widgetPlacement?: "aboveEditor" | "belowEditor";
+} | {
+    method: "setTitle";
+    title: string;
+} | {
+    method: "set_editor_text";
+    text: string;
+} | {
+    method: string;
+    raw: Record<string, unknown>;
+};
+/** parseSpawnLine 的分类结果。 */
+type ParsedSpawnLine = {
+    kind: "header";
+    header: SpawnSessionHeader;
+} | {
+    kind: "event";
+    event: SdkEvent;
+} | {
+    kind: "response";
+    id?: string;
+    command: string;
+    success: boolean;
+    data?: unknown;
+    error?: string;
+} | {
+    kind: "extension_ui_request";
+    id: string;
+    request: ExtensionUiRequest;
+} | {
+    kind: "invalid";
+    raw: string;
+    error: string;
+};
+/**
+ * 解析 pi stdout 的一行。
+ *
+ * 分类规则（判定顺序关键——extension_ui_request 必须在 event 之前判定）：
+ *   - 空白行 → null；合法 JSON 按 type 值分派 header/ui_request/response/event
+ *   - 非法 JSON / 无 type → invalid（记录 error，不抛——单行损坏不中断流）
+ */
+declare function parseSpawnLine(line: string): ParsedSpawnLine | null;
+/**
+ * 从已收集的 header + 事件流推导子进程的 session 文件路径。
+ *
+ * pi session 文件命名规则（session-manager.ts:846）：
+ *   `${fileTimestamp}_${sessionId}.jsonl`，fileTimestamp = header.timestamp 的
+ *   冒号/点替换为连字符。
+ */
+declare function deriveSessionFilePath(header: SpawnSessionHeader, sessionDir: string): string;
+/**
+ * 在 sessionDir 中按 sessionId 后缀匹配查找实际存在的 session 文件（命名规则
+ * 变化时的兜底）。@returns 匹配到的文件绝对路径，或 undefined。
+ */
+declare function findSessionFileByHeaderId(sessionDir: string, sessionId: string): string | undefined;
+
+/** pi CLI 认可的 thinking level 后缀白名单。 */
+type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "max";
+/**
+ * spawn 侧已裁决的模型身份：`--model` 值恒为 `${provider}/${id}`（+ 可选白名单
+ * `:level` 后缀）。解析自协议 ctx.model 的 canonical "provider/id" 词形。
+ */
+interface SpawnModelRef {
+    provider: string;
+    id: string;
+}
+/** "provider/id" canonical 词形 → SpawnModelRef（无斜杠/畸形 → undefined）。 */
+declare function parseSpawnModelRef(ref: string | undefined): SpawnModelRef | undefined;
+/**
+ * 组装 pi CLI 参数（不含 task 本身——task 由 spawn 后 sendPromptCommand 写 stdin）。
+ *
+ * [单写者不变量] session JSONL 完整性依赖「每 session 单写进程」：子进程写独立
+ * subagent sessionDir，任何改动不得让两个进程指向同一 session 文件写路径。
+ */
+declare function buildSpawnArgs(params: {
+    modelRef: SpawnModelRef;
+    thinkingLevel: ThinkingLevel | undefined;
+    agentTools: string[] | undefined;
+    appendSystemPromptPath: string | undefined;
+    sessionDir: string;
+    /** resume 目标 session 文件路径（--session 续写原文件而非新建）。 */
+    sessionFile?: string;
+    forkSource: string | undefined;
+    skillPaths: string[] | undefined;
+    /** 镜像自主进程 argv 的 flag（--no-extensions/--approve/--extension/--no-context-files）。 */
+    mirrorFlags?: MirrorFlags;
+}): string[];
+/**
+ * 将 schemaEnv 注入 childEnv。
+ *
+ * [SO-DATA-4] 注入前按 UTF-8 字节长度校验，超 SCHEMA_ENV_MAX_BYTES（256KiB）
+ * fail-fast 拒绝：env 值过大叠加全量继承的 process.env 可能触发 execve 的 E2BIG。
+ *
+ * @throws Error schemaEnv 序列化后超过 SCHEMA_ENV_MAX_BYTES
+ */
+declare function applySchemaEnvToChildEnv(childEnv: Record<string, string | undefined>, schemaEnv?: string): void;
+/**
+ * 构建环境信息块（P7 防注入：环境数据标记为 data，非指令）。
+ * git branch 异步获取（execFile），失败静默为空（非 git 目录 / git 缺失是高频正常路径）。
+ *
+ * @param forkDepth 当前 fork 链深度（undefined=非 fork session，视为 0）
+ * @param nestingDepth 通用嵌套深度（undefined=顶层）
+ */
+declare function buildEnvBlock(cwd: string, forkDepth?: number, nestingDepth?: number): Promise<string>;
+/**
+ * 把 pi assistantMessageEvent 分流为 text_delta / thinking_delta AgentEvent。
+ * toolcall_delta 等其他带 delta 的事件不混入 text stream。
+ */
+declare function mapAssistantMessageDelta(ame: {
+    type?: string;
+    delta?: string;
+}): {
+    type: "text_delta";
+    delta: string;
+} | {
+    type: "thinking_delta";
+    delta: string;
+} | null;
+
+/** 连续 EPIPE 失败阈值：达到即不再尝试 resume（避免无限 spawn → EPIPE → resume 循环）。 */
+declare const EPIPE_FAILURE_THRESHOLD = 2;
+/** 递增 recordId 的 EPIPE 连续失败计数，返回递增后的新计数。 */
+declare function recordEpipeFailure(recordId: string): number;
+/** 成功写入时清零某 record 的 EPIPE 连续失败计数（热路径成功 → 重置）。 */
+declare function clearEpipeFailure(recordId: string): void;
+/** dispose 时清空所有 EPIPE 计数（防跨 session 泄漏）。 */
+declare function resetAllEpipeFailures(): void;
+/**
+ * 按 UiResponse 形状构造 Pi 原生 extension_ui_response 并写 stdin。
+ *
+ * SR-5：ack（fire-and-forget）不写 stdin——Pi 对 fire-and-forget method 不期待响应。
+ * 其他三种 shape（value/confirmed/cancelled）按对应字段写。
+ *
+ * [R1] 背压检查：write 返回 false 时记 warn（不阻塞，内核缓冲会随后排空）。
+ * [R2] 序列化失败（循环引用/BigInt）降级 cancelled——宁可取消单次 dialog 也不崩进程。
+ */
+declare function respond(child: ChildProcess, id: string, out: UiResponse, signal?: AbortSignal): void;
+/**
+ * spawn 后向 rpc 子进程 stdin 写 prompt 命令，驱动 agent 开始处理 task。
+ *
+ * pi 的 runRpcMode 只通过 stdin RpcCommand 驱动——positional task arg / -p flag
+ * 在 rpc mode 下被 resolveAppMode 无视，必须在 spawn 后主动喂 prompt 命令。
+ *
+ * [V2 决策 3] chatMode 续聊热路径用 prompt + streamingBehavior 统一投递，pi 权威
+ * 裁决 busy/idle：busy 时 followUp 入队/steer 抢占；idle 时开新 turn。省略
+ * streamingBehavior 时行为不变（首帧 prompt）。
+ */
+declare function sendPromptCommand(child: ChildProcess, task: string, options?: {
+    streamingBehavior?: "followUp" | "steer";
+}): void;
+/**
+ * 向子进程 stdin 写 get_state 命令，查询 sessionFile/sessionId（FR-4 RPC 握手）。
+ *
+ * @returns 请求 id（用于匹配 response）
+ */
+declare function sendGetStateCommand(child: ChildProcess): string;
+
+/** 队列依赖（引擎侧形态：host/askUser 反向请求的应答回调由 server 注入）。 */
+interface UiRequestQueueDeps {
+    /**
+     * UI 请求处理回调（= host/askUser 反向请求的两阶段等待体）。未设置时不再
+     * 静默忽略——本地去重告警 + respond(cancelled)（子进程不永久挂起）。
+     */
+    uiRequestHandler?: UiRequestHandler;
+}
+/**
+ * 创建 UI 请求队列。返回 enqueue 函数，调用方将 extension_ui_request 入队。
+ *
+ * 多个 extension_ui_request 并发到达时，队列保证 FIFO 串行处理。
+ *
+ * 设计：队列是 run 生命周期内的闭包状态（非模块级），每个子进程实例独立队列，
+ * 无跨 session 泄漏。
+ *
+ * @param child 子进程（stdin 写入 extension_ui_response）
+ * @param deps 队列依赖（含 uiRequestHandler 回调）
+ * @returns enqueue 函数：(id, request) => void
+ */
+declare function createUiRequestQueue(child: ChildProcess, deps: UiRequestQueueDeps): (id: string, request: ExtensionUiRequest) => void;
+
+/**
+ * 预防性 wrap-up 提示（启动时注入 --append-system-prompt）。
+ *
+ * rpc steer 通道未接通时的短期补偿（见 spawn-runner limiter 注释）。
+ */
+declare const WRAP_UP_HINT: string;
+/** turn limiter 配置。 */
+interface TurnLimiterOptions {
+    maxTurns: number;
+    graceTurns: number;
+    steer: (msg: string) => void;
+    abort: () => void;
+}
+/**
+ * soft/hard turn 限制。
+ *
+ *   onTurnEnd(currentTurns):
+ *     已 aborted 或 maxTurns<=0（禁用）→ 直接 return
+ *     currentTurns >= maxTurns 且未 steer → steer(WRAP_UP_MESSAGE)（仅一次）
+ *     已 steer 且 currentTurns >= maxTurns + graceTurns → abort()（仅一次）
+ */
+interface TurnLimiter {
+    /** 每次 turn_end 调用。 */
+    onTurnEnd(currentTurns: number): void;
+    /** 重置 steered/aborted 标志（新一轮开始）。 */
+    reset(): void;
+    /** 是否已发过 steer（诊断用）。 */
+    readonly didSteer: boolean;
+    /** 是否已 abort（诊断用）。 */
+    readonly didAbort: boolean;
+}
+/** 工厂函数。 */
+declare function createTurnLimiter(opts: TurnLimiterOptions): TurnLimiter;
+
+/** get_state 握手结果。 */
+interface GetStateResult {
+    sessionFile?: string;
+    sessionId?: string;
+}
+/** get_state response 监听器注册函数形态（stdout pump / 测试注入）。 */
+type AddGetStateResponseListener = (id: string, resolver: (data: unknown) => void) => void | (() => void);
+/**
+ * FR-4: 通过 get_state RPC 查询子进程获取 sessionFile/sessionId。
+ *
+ * 最多重试 GET_STATE_MAX_RETRIES 次，单次超时 GET_STATE_TIMEOUT_MS 后等待
+ * GET_STATE_RETRY_INTERVAL_MS 再发起下一次重试。
+ */
+declare function performGetStateHandshake(child: ChildProcess, addResponseListener: AddGetStateResponseListener): Promise<GetStateResult>;
+/**
+ * [T1/RC-1] 单次 get_state 请求（agent_end 决策点惰性回补专用）。
+ *
+ * 不做重试循环、不 share 握手语义：调用方在子进程 idle 时现场补一次查询，
+ * 超时/失败即放弃，由调用方走既有保守分支。永不 reject——stdin 已断的同步写
+ * 失败按「回补失败」处理 resolve 空对象。
+ */
+declare function requestGetStateOnce(child: ChildProcess, addResponseListener: AddGetStateResponseListener, timeoutMs: number): Promise<GetStateResult>;
+
+/**
+ * 从 handle 自描述的 journalPath 重放会话视图。
+ *
+ * @returns undefined = journalPath 缺失 / 文件不存在 / 无有效事件（降级链落 ③级）
+ */
+declare function replayJournalToSessionView(handle: EngineHandle, engineId: string): SessionView | undefined;
+
+export { type ChatHostChannels, type ChatRoundStartOptions, ChatSessionRegistry, type ChatSessionRegistryDeps, type ChatSpawnExecutor, DETERMINISTIC_SCHEMA_FAILURE_PREFIX, EPIPE_FAILURE_THRESHOLD, EngineProtocolServer, type GetStateResult, type MirrorFlags, PI_ADAPTER_VERSION, PI_ENGINE_ID, PI_POOL_KEY, PiEngine, type PiEngineDeps, type PiInvocation, STALE_CONTEXT_PATTERNS, type SpawnModelRef, type SpawnRunCallbacks, type SpawnRunParams, type SpawnRunResult, type ThinkingLevel, type UiRequestQueueDeps, WRAP_UP_HINT, applySchemaEnvToChildEnv, buildEnvBlock, buildSpawnArgs, classifyFailureKind, clearEpipeFailure, collectOutcome, createDefaultPiEngine, createTurnLimiter, createUiRequestQueue, deriveSessionFilePath, describeMissingParsedOutput, extractParsedOutput, findSessionFileByHeaderId, getActiveChild, getPiInvocation, isDeterministicSchemaFailureMsg, isStaleContextErrorMsg, killAllActiveChildren, mapAssistantMessageDelta, mirrorMainProcessFlags, neutralizeStalePatterns, parseSpawnLine, parseSpawnModelRef, performGetStateHandshake, recordEpipeFailure, replayJournalToSessionView, requestGetStateOnce, resetAllEpipeFailures, respond, runSpawnOnce, sendGetStateCommand, sendPromptCommand };