lark-remote 0.1.5 → 0.1.7

package/dist/runner/pi/rpc/protocol-types.js

@@ -0,0 +1,21 @@
+/**
+ * Pi RPC protocol types.
+ *
+ * pi's `--mode rpc` is a headless JSON-lines protocol over stdio (NOT JSON-RPC):
+ *   - client → stdin:  commands `{ type, id, ... }`
+ *   - server → stdout: responses `{ id, type:"response", command, success, data|error }`
+ *                     and events (session lifecycle / message / compaction) as bare
+ *                     JSON objects (no envelope).
+ *
+ * Turn semantics (verified live against pi 0.84.1, 2026-08-18):
+ *   - `prompt` returns an ack (`success:true`) immediately; the turn then streams
+ *     events and completes with an `agent_settled` event.
+ *   - `compact` runs synchronously and returns its response at completion; it also
+ *     streams `compaction_start` / `compaction_end` events.
+ *   - `abort` cancels the current operation.
+ *   - `get_state` returns the bound session id (`data.sessionId`) — pi binds the
+ *     session at spawn via `--session-id`, so this is how a new session's id is
+ *     discovered.
+ */
+export {};
+//# sourceMappingURL=protocol-types.js.map

package/dist/runner/pi/rpc/runner.d.ts

@@ -0,0 +1,80 @@
+/**
+ * PiRpcRunner: workspace-lifetime runner driving pi in `--mode rpc`
+ * (JSON-lines protocol over stdio).
+ *
+ * Flow per run: acquire persistent connection → resolve session id (via
+ * `get_state`, or the spawn-bound `--session-id`) → synthetic init → send
+ * `prompt` (fire-and-ack) → consume pi events until `agent_settled` → result.
+ *
+ * Compact flow: acquire → `compact` command → consume `compaction_*` events →
+ * result from the compact response (completion signal).
+ *
+ * Structurally aligned with KimiAcpRunner / OpencodeAcpRunner via the shared
+ * ConnectionBasedRunner base (notification queue, forceFinish/stopRequested,
+ * turn idle watchdog, connection-lost retry). Differences:
+ *   - pi binds the session at spawn via `--session-id` (no RPC resume-by-id);
+ *     the PiRpcConnectionManager respawns when the requested session changes.
+ *   - no approval server-requests (pi RPC exposes none in this scope) →
+ *     respondApproval is a no-op.
+ *   - `prompt` ack ≠ turn completion; the turn ends on `agent_settled`.
+ */
+import type { AgentSessionReader, AgentEvent, AgentStatusInfo, SpawnOptions } from '../../types.js';
+import { ConnectionBasedRunner } from '../../common/connection-based-runner.js';
+import { PiRpcClient } from './client.js';
+import { type PiRpcTranslatorEvent } from './translator.js';
+export interface PiRpcRunnerOptions {
+    /** LLM provider, e.g. 'Volcano'. */
+    provider?: string;
+    /** Model id or alias, e.g. 'glm-5.2'. */
+    model?: string;
+    /** Thinking level: off/minimal/low/medium/high/xhigh/max. */
+    thinking?: string;
+    /** Tool allowlist. */
+    tools?: string[];
+    workspace: string;
+    sessionReader: AgentSessionReader;
+    /** Path to the pi binary. Defaults to `pi`. */
+    binary?: string;
+    /** Environment variables to pass to the pi process. */
+    env?: Record<string, string | undefined>;
+    requestTimeoutMs?: number;
+    idleTtlMs?: number;
+    turnIdleTimeoutMs?: number;
+}
+export declare class PiRpcRunner extends ConnectionBasedRunner<PiRpcClient, PiRpcTranslatorEvent> {
+    private readonly manager;
+    private currentTranslator;
+    private activeSessionId;
+    private promptSettled;
+    private readonly defaultModel;
+    private readonly provider;
+    private readonly thinking;
+    constructor(opts: PiRpcRunnerOptions);
+    protected get logTag(): string;
+    protected get turnTimeoutErrorMessage(): string;
+    protected get turnInterruptedErrorMessage(): string;
+    protected currentSessionId(): string | null;
+    protected shouldDeferStop(): boolean;
+    protected cancelCurrentTurn(): Promise<void>;
+    protected clearTurnState(): void;
+    protected releaseConnection(cwd: string): Promise<void>;
+    protected notifyIdle(cwd: string): void;
+    protected disposeConnections(): Promise<void>;
+    getStatusInfo(): AgentStatusInfo;
+    /**
+     * Normal turn: acquire → resolve session id → prompt (fire-and-ack) → the
+     * `agent_settled` event produces the result.
+     */
+    protected setupTurn(message: string, opts: SpawnOptions): Promise<void>;
+    /**
+     * Compact the current session. The `compact` command returns a response at
+     * completion (the completion signal); `compaction_*` events stream meanwhile.
+     */
+    runCompact(_message: string, opts: SpawnOptions): AsyncGenerator<AgentEvent>;
+    /**
+     * Approvals are out of scope for pi RPC (no server requests surface in this
+     * integration); the bridge's duck-typed respondApproval call is a no-op.
+     */
+    respondApproval(_requestId: number | string, _response: unknown): Promise<void>;
+    private handleEvent;
+}

package/dist/runner/pi/rpc/runner.js

@@ -0,0 +1,199 @@
+/**
+ * PiRpcRunner: workspace-lifetime runner driving pi in `--mode rpc`
+ * (JSON-lines protocol over stdio).
+ *
+ * Flow per run: acquire persistent connection → resolve session id (via
+ * `get_state`, or the spawn-bound `--session-id`) → synthetic init → send
+ * `prompt` (fire-and-ack) → consume pi events until `agent_settled` → result.
+ *
+ * Compact flow: acquire → `compact` command → consume `compaction_*` events →
+ * result from the compact response (completion signal).
+ *
+ * Structurally aligned with KimiAcpRunner / OpencodeAcpRunner via the shared
+ * ConnectionBasedRunner base (notification queue, forceFinish/stopRequested,
+ * turn idle watchdog, connection-lost retry). Differences:
+ *   - pi binds the session at spawn via `--session-id` (no RPC resume-by-id);
+ *     the PiRpcConnectionManager respawns when the requested session changes.
+ *   - no approval server-requests (pi RPC exposes none in this scope) →
+ *     respondApproval is a no-op.
+ *   - `prompt` ack ≠ turn completion; the turn ends on `agent_settled`.
+ */
+import { ConnectionBasedRunner } from '../../common/connection-based-runner.js';
+import { ConnectionManager } from '../../common/jsonrpc/connection-manager.js';
+import { getLogger } from '../../../logger/index.js';
+import { PiRpcClient } from './client.js';
+import { PiRpcTranslator } from './translator.js';
+export class PiRpcRunner extends ConnectionBasedRunner {
+    manager;
+    currentTranslator = null;
+    activeSessionId = null;
+    promptSettled = false;
+    defaultModel;
+    provider;
+    thinking;
+    constructor(opts) {
+        super({
+            kind: 'pi',
+            sessionReader: opts.sessionReader,
+            turnIdleTimeoutMs: opts.turnIdleTimeoutMs,
+        });
+        this.defaultModel = opts.model ?? 'glm-5.2';
+        this.provider = opts.provider ?? 'Volcano';
+        this.thinking = opts.thinking ?? 'medium';
+        const tools = (opts.tools ?? ['read', 'bash', 'edit', 'write', 'grep', 'find', 'ls']).join(',');
+        this.manager = new ConnectionManager({
+            binary: opts.binary ?? 'pi',
+            buildArgs: (req) => buildPiArgs(this.provider, this.defaultModel, this.thinking, tools, req.sessionId),
+            clientFactory: ({ transport, baseOnClose, requestTimeoutMs }) => new PiRpcClient(transport, baseOnClose, requestTimeoutMs),
+            shouldReuse: ({ client, req, boundSessionId }) => req.sessionId !== undefined &&
+                boundSessionId === req.sessionId &&
+                client.ready &&
+                client.healthy,
+            env: opts.env,
+            requestTimeoutMs: opts.requestTimeoutMs,
+            idleTtlMs: opts.idleTtlMs,
+            logTag: 'pi-rpc-connection-manager',
+        });
+    }
+    get logTag() {
+        return 'pi-rpc-runner';
+    }
+    get turnTimeoutErrorMessage() {
+        return 'Pi RPC turn timed out';
+    }
+    get turnInterruptedErrorMessage() {
+        return 'Pi RPC turn interrupted';
+    }
+    currentSessionId() {
+        return this.activeSessionId;
+    }
+    shouldDeferStop() {
+        return !this.promptSettled;
+    }
+    async cancelCurrentTurn() {
+        if (!this.currentClient || !this.activeSessionId)
+            return;
+        try {
+            this.currentClient.notify({ type: 'abort' });
+        }
+        catch (err) {
+            getLogger().warn(`[${this.logTag}] abort failed: ${err.message}`);
+        }
+    }
+    clearTurnState() {
+        this.currentTranslator = null;
+        this.promptSettled = false;
+        this.activeSessionId = null;
+    }
+    async releaseConnection(cwd) {
+        await this.manager.release(cwd);
+    }
+    notifyIdle(cwd) {
+        this.manager.notifyIdle(cwd);
+    }
+    async disposeConnections() {
+        await this.manager.disposeAll();
+    }
+    getStatusInfo() {
+        return {
+            kind: 'pi',
+            model: this.defaultModel,
+            provider: this.provider,
+            reasoning: this.thinking,
+            extras: { mode: 'rpc' },
+        };
+    }
+    /**
+     * Normal turn: acquire → resolve session id → prompt (fire-and-ack) → the
+     * `agent_settled` event produces the result.
+     */
+    async setupTurn(message, opts) {
+        const client = await this.manager.acquire(opts.cwd, { sessionId: opts.sessionId });
+        this.manager.notifyActivity(opts.cwd);
+        this.currentClient = client;
+        client.setHooks({
+            onEvent: (evt) => this.handleEvent(evt),
+            onClose: () => this.failTurn('Pi RPC connection closed'),
+        });
+        let sessionId = opts.sessionId;
+        if (!sessionId) {
+            const state = await client.request({ type: 'get_state' });
+            if (state.success && state.data) {
+                sessionId = state.data.sessionId;
+            }
+            if (!sessionId)
+                throw new Error('pi RPC did not report a session id');
+            // Bind the discovered id so a following run resumes the SAME session on
+            // this live connection instead of respawning it.
+            this.manager.bindSession(opts.cwd, sessionId);
+        }
+        this.activeSessionId = sessionId;
+        const translator = new PiRpcTranslator();
+        translator.setSessionId(sessionId);
+        this.currentTranslator = translator;
+        const turnId = `turn-${Date.now()}`;
+        this.currentTurnId = turnId;
+        this.pushEvents([translator.produceTurnStarted(sessionId, turnId)]);
+        this.promptSettled = false;
+        await client.request({ type: 'prompt', message });
+        this.promptSettled = true;
+    }
+    /**
+     * Compact the current session. The `compact` command returns a response at
+     * completion (the completion signal); `compaction_*` events stream meanwhile.
+     */
+    async *runCompact(_message, opts) {
+        yield* this.executeTurn(opts, async () => {
+            if (!opts.sessionId) {
+                throw new Error('compact requires a sessionId');
+            }
+            const client = await this.manager.acquire(opts.cwd, { sessionId: opts.sessionId });
+            this.manager.notifyActivity(opts.cwd);
+            this.currentClient = client;
+            client.setHooks({
+                onEvent: (evt) => this.handleEvent(evt),
+                onClose: () => this.failTurn('Pi RPC connection closed'),
+            });
+            this.activeSessionId = opts.sessionId;
+            const translator = new PiRpcTranslator();
+            translator.setSessionId(opts.sessionId);
+            translator.setOperationKind('compact');
+            this.currentTranslator = translator;
+            const turnId = `compact-${Date.now()}`;
+            this.currentTurnId = turnId;
+            this.pushEvents([translator.produceTurnStarted(opts.sessionId, turnId)]);
+            this.promptSettled = false;
+            const response = await client.request({ type: 'compact' });
+            this.promptSettled = true;
+            // Guard: a stop may have already ended this turn (deferred-stop during
+            // compaction) — don't push a stale result into a (possibly reused) queue.
+            if (this.stopRequested || !this._isRunning)
+                return;
+            this.pushEvents([translator.produceCompactResult(opts.sessionId, response)]);
+        });
+    }
+    /**
+     * Approvals are out of scope for pi RPC (no server requests surface in this
+     * integration); the bridge's duck-typed respondApproval call is a no-op.
+     */
+    async respondApproval(_requestId, _response) {
+        // no-op
+    }
+    handleEvent(evt) {
+        const events = this.currentTranslator?.handleEvent(evt) ?? [];
+        this.pushEvents(events);
+    }
+}
+/** Build pi `--mode rpc` spawn args. `sessionId` is bound at spawn (pi has no
+ *  RPC resume-by-id command); omitting it spawns a brand-new session. */
+function buildPiArgs(provider, model, thinking, tools, sessionId) {
+    const args = ['--mode', 'rpc', '--provider', provider, '--model', model];
+    if (thinking && thinking !== 'off')
+        args.push('--thinking', thinking);
+    if (tools)
+        args.push('--tools', tools);
+    if (sessionId)
+        args.push('--session-id', sessionId);
+    return args;
+}
+//# sourceMappingURL=runner.js.map

package/dist/runner/pi/rpc/translator.d.ts

@@ -0,0 +1,55 @@
+/**
+ * PiRpcTranslator: maps pi RPC events into AgentEvents for the PiRpcRunner.
+ *
+ * Content mapping accumulates pi's incremental message_start/update/end events
+ * into assistant/user events with text/thinking/tool content, and drives the
+ * turn lifecycle differently:
+ *   - `prompt` is fire-and-ack, so the runner produces a `result` on the
+ *     `agent_settled` event (turn completion), not on a prompt response.
+ *   - `compact` returns a response at completion; the runner produces the
+ *     `result` from that response.
+ *   - `agent_settled` is ignored for compaction turns (no double result).
+ */
+import type { AgentEvent, ResultEvent } from '../../types.js';
+import { type PiRpcEvent, type PiRpcResponse } from './protocol-types.js';
+export interface PiRpcTurnStartedEvent {
+    type: 'turn_started';
+    threadId: string;
+    turnId: string;
+    operationKind: 'turn' | 'compaction';
+    timestamp?: string;
+}
+export type PiRpcTranslatorEvent = AgentEvent | PiRpcTurnStartedEvent;
+export declare class PiRpcTranslator {
+    private content;
+    private currentContentIndex;
+    private sessionId;
+    private operationKind;
+    private currentTurnId;
+    private accInput;
+    private accOutput;
+    private accCacheRead;
+    private accCacheCreation;
+    private lastTotalTokens;
+    private hasUsage;
+    /** Provider failure (stopReason="error") on the final assistant message. */
+    private lastAssistantStopReason;
+    private lastAssistantErrorMessage;
+    getSessionId(): string;
+    setSessionId(id: string): void;
+    setOperationKind(kind: 'turn' | 'compact'): void;
+    getUsage(): ResultEvent['usage'] | undefined;
+    /** Translate an incoming pi RPC event into AgentEvents to push. */
+    handleEvent(evt: PiRpcEvent): PiRpcTranslatorEvent[];
+    /** Self-produced turn_started (no wire equivalent). */
+    produceTurnStarted(sessionId: string, turnId: string): PiRpcTurnStartedEvent;
+    /** Result for a completed normal turn (agent_settled). */
+    produceResultFromSettled(): AgentEvent;
+    /** Result from a compact command response (completion signal for compaction). */
+    produceCompactResult(sessionId: string, response: PiRpcResponse): AgentEvent;
+    /** Error result (for setup/request failures). */
+    produceErrorResult(sessionId: string, errorMessage: string): AgentEvent;
+    private handleMessageEnd;
+    private addUsage;
+    private applyUpdate;
+}

package/dist/runner/pi/rpc/translator.js

@@ -0,0 +1,258 @@
+/**
+ * PiRpcTranslator: maps pi RPC events into AgentEvents for the PiRpcRunner.
+ *
+ * Content mapping accumulates pi's incremental message_start/update/end events
+ * into assistant/user events with text/thinking/tool content, and drives the
+ * turn lifecycle differently:
+ *   - `prompt` is fire-and-ack, so the runner produces a `result` on the
+ *     `agent_settled` event (turn completion), not on a prompt response.
+ *   - `compact` returns a response at completion; the runner produces the
+ *     `result` from that response.
+ *   - `agent_settled` is ignored for compaction turns (no double result).
+ */
+export class PiRpcTranslator {
+    content = [];
+    currentContentIndex = -1;
+    sessionId = '';
+    operationKind = 'turn';
+    currentTurnId = '';
+    // ccusage-aligned usage accumulation (per-message, summed across the turn).
+    accInput = 0;
+    accOutput = 0;
+    accCacheRead = 0;
+    accCacheCreation = 0;
+    lastTotalTokens;
+    hasUsage = false;
+    /** Provider failure (stopReason="error") on the final assistant message. */
+    lastAssistantStopReason;
+    lastAssistantErrorMessage;
+    getSessionId() {
+        return this.sessionId;
+    }
+    setSessionId(id) {
+        this.sessionId = id;
+    }
+    setOperationKind(kind) {
+        this.operationKind = kind;
+    }
+    getUsage() {
+        if (!this.hasUsage &&
+            this.accInput === 0 &&
+            this.accOutput === 0 &&
+            this.accCacheRead === 0 &&
+            this.accCacheCreation === 0 &&
+            this.lastTotalTokens === undefined) {
+            return undefined;
+        }
+        return {
+            input_tokens: this.accInput,
+            output_tokens: this.accOutput,
+            cache_read_tokens: this.accCacheRead,
+            cache_creation_tokens: this.accCacheCreation,
+            ...(this.lastTotalTokens != null ? { total_tokens: this.lastTotalTokens } : {}),
+        };
+    }
+    /** Translate an incoming pi RPC event into AgentEvents to push. */
+    handleEvent(evt) {
+        switch (evt.type) {
+            case 'session': {
+                const s = evt;
+                this.sessionId = s.id;
+                return [
+                    {
+                        type: 'system',
+                        subtype: 'init',
+                        session_id: s.id,
+                        cwd: s.cwd,
+                        model: s.model ?? '',
+                        timestamp: new Date().toISOString(),
+                    },
+                ];
+            }
+            case 'message_start': {
+                const m = evt.message;
+                if (m.role === 'assistant') {
+                    this.content = [];
+                    this.currentContentIndex = -1;
+                }
+                return [];
+            }
+            case 'message_update': {
+                this.applyUpdate(evt.assistantMessageEvent);
+                return [];
+            }
+            case 'message_end': {
+                return this.handleMessageEnd(evt);
+            }
+            case 'agent_settled': {
+                // Normal-turn completion signal. Compaction turns finish via the
+                // compact response, not agent_settled.
+                if (this.operationKind === 'turn') {
+                    return [this.produceResultFromSettled()];
+                }
+                return [];
+            }
+            default:
+                // turn_start/turn_end, agent_start/agent_end, compaction_start/end,
+                // tool_execution_*, and unknown types are ignored.
+                return [];
+        }
+    }
+    /** Self-produced turn_started (no wire equivalent). */
+    produceTurnStarted(sessionId, turnId) {
+        this.sessionId = sessionId;
+        this.currentTurnId = turnId;
+        return {
+            type: 'turn_started',
+            threadId: sessionId,
+            turnId,
+            operationKind: this.operationKind === 'compact' ? 'compaction' : 'turn',
+            timestamp: new Date().toISOString(),
+        };
+    }
+    /** Result for a completed normal turn (agent_settled). */
+    produceResultFromSettled() {
+        const usage = this.getUsage();
+        return {
+            type: 'result',
+            subtype: this.lastAssistantStopReason === 'error' ? 'error' : 'success',
+            session_id: this.sessionId,
+            ...(this.lastAssistantStopReason === 'error'
+                ? { errorMessage: this.lastAssistantErrorMessage?.trim() || 'pi reported an error' }
+                : {}),
+            ...(usage ? { usage } : {}),
+        };
+    }
+    /** Result from a compact command response (completion signal for compaction). */
+    produceCompactResult(sessionId, response) {
+        if (response.success) {
+            return {
+                type: 'result',
+                subtype: 'success',
+                session_id: sessionId,
+            };
+        }
+        return {
+            type: 'result',
+            subtype: 'error',
+            session_id: sessionId,
+            errorMessage: response.error,
+        };
+    }
+    /** Error result (for setup/request failures). */
+    produceErrorResult(sessionId, errorMessage) {
+        return {
+            type: 'result',
+            subtype: 'error',
+            session_id: sessionId,
+            errorMessage,
+        };
+    }
+    // =========================================================================
+    // Internal
+    // =========================================================================
+    handleMessageEnd(evt) {
+        const m = evt.message;
+        if (m.role === 'assistant') {
+            this.lastAssistantStopReason = m.stopReason;
+            this.lastAssistantErrorMessage = m.stopReason === 'error' ? m.errorMessage : undefined;
+            if (m.usage)
+                this.addUsage(m.usage);
+            const event = {
+                type: 'assistant',
+                message: { content: this.content },
+                timestamp: new Date().toISOString(),
+            };
+            this.content = [];
+            this.currentContentIndex = -1;
+            return [event];
+        }
+        if (m.role === 'toolResult') {
+            return [
+                {
+                    type: 'user',
+                    message: {
+                        content: [
+                            {
+                                type: 'tool_result',
+                                tool_use_id: m.toolCallId ?? '',
+                                content: m.content ?? '',
+                                is_error: m.isError ?? false,
+                            },
+                        ],
+                    },
+                    timestamp: new Date().toISOString(),
+                },
+            ];
+        }
+        return [];
+    }
+    addUsage(u) {
+        this.hasUsage = true;
+        this.accInput += u.input ?? 0;
+        this.accOutput += u.output ?? 0;
+        this.accCacheRead += u.cacheRead ?? 0;
+        this.accCacheCreation += u.cacheWrite ?? 0;
+        if (u.totalTokens != null)
+            this.lastTotalTokens = u.totalTokens;
+    }
+    applyUpdate(evt) {
+        switch (evt.type) {
+            case 'text_start':
+                this.content.push({ type: 'text', text: '' });
+                this.currentContentIndex++;
+                break;
+            case 'text_delta':
+                if (this.currentContentIndex >= 0 &&
+                    this.content[this.currentContentIndex]?.type === 'text') {
+                    this.content[this.currentContentIndex].text += evt.delta ?? '';
+                }
+                break;
+            case 'text_end':
+                if (this.currentContentIndex >= 0 &&
+                    this.content[this.currentContentIndex]?.type === 'text' &&
+                    evt.content) {
+                    this.content[this.currentContentIndex].text = evt.content;
+                }
+                break;
+            case 'thinking_start':
+                this.content.push({ type: 'thinking', thinking: '' });
+                this.currentContentIndex++;
+                break;
+            case 'thinking_delta':
+                if (this.currentContentIndex >= 0 &&
+                    this.content[this.currentContentIndex]?.type === 'thinking') {
+                    this.content[this.currentContentIndex].thinking +=
+                        evt.delta ?? '';
+                }
+                break;
+            case 'thinking_end':
+                if (this.currentContentIndex >= 0 &&
+                    this.content[this.currentContentIndex]?.type === 'thinking' &&
+                    evt.content) {
+                    this.content[this.currentContentIndex].thinking = evt.content;
+                }
+                break;
+            case 'toolcall_start':
+                this.content.push({ type: 'tool_use', id: '', name: '', input: {} });
+                this.currentContentIndex++;
+                break;
+            case 'toolcall_end':
+                if (this.currentContentIndex >= 0 &&
+                    this.content[this.currentContentIndex]?.type === 'tool_use' &&
+                    evt.toolCall) {
+                    this.content[this.currentContentIndex] = {
+                        type: 'tool_use',
+                        id: evt.toolCall.id,
+                        name: evt.toolCall.name,
+                        input: evt.toolCall.arguments,
+                    };
+                }
+                break;
+            default:
+                // toolcall_delta: pi provides complete arguments at toolcall_end, ignore.
+                break;
+        }
+    }
+}
+//# sourceMappingURL=translator.js.map

package/dist/runner/registry.d.ts

@@ -1,13 +1,12 @@
-import type { AgentKind, AgentRunner } from './index.js';
+import type { AgentKind, Runner } from './index.js';
 /**
  * Registry of agent factories, keyed by `AgentKind`. `index.ts` registers one
  * factory per available agent at startup; `Bridge.getRunner(workspace)` looks
  * up `config.defaultAgent` here to pick the concrete runner.
  *
- * Singleton caching: the factory MAY cache its instance internally. All
- * current agents (claude, codex, opencode, pi, kimi) are spawn-per-message,
- * so per-workspace instantiation has no cost; each factory returns a fresh
- * runner per call.
+ * Singleton caching: the factory MAY cache its instance internally. Most
+ * current agents (claude, opencode, pi, kimi) are spawn-per-message; codex is
+ * workspace-lifetime (app-server). Each factory returns a runner per call.
  *
  * Dynamic config reload: factory can read latest config via registry's
  * configContainer, enabling runtime config changes to take effect.
@@ -17,7 +16,7 @@ export declare class AgentRegistry {
     private readonly displayNames;
     /** Container for runtime config updates (pi provider dynamic reload). */
     private configContainer?;
-    register(kind: AgentKind, factory: (workspace: string) => AgentRunner): void;
+    register(kind: AgentKind, factory: (workspace: string) => Runner): void;
     /**
      * 注册 agent 的显示名。应在 register(kind, factory) 后调用。
      * 用于 agentDisplayName 等全局查询，实现单点真相。
@@ -31,7 +30,7 @@ export declare class AgentRegistry {
      * 设置全局 registry 实例，供 agentDisplayName 等全局函数使用。
      * 在 index.ts 初始化所有 agents 后调用。
      */
-    static setGlobalInstance(reg: AgentRegistry): void;
+    static setGlobalInstance(reg: AgentRegistry | undefined): void;
     /**
      * 获取全局 registry 实例。
      */
@@ -50,5 +49,5 @@ export declare class AgentRegistry {
     getConfigContainer(): {
         current: unknown;
     } | undefined;
-    get(kind: AgentKind, workspace: string): AgentRunner;
+    get(kind: AgentKind, workspace: string): Runner;
 }

package/dist/runner/registry.js

@@ -8,10 +8,9 @@ let globalRegistry;
  * factory per available agent at startup; `Bridge.getRunner(workspace)` looks
  * up `config.defaultAgent` here to pick the concrete runner.
  *
- * Singleton caching: the factory MAY cache its instance internally. All
- * current agents (claude, codex, opencode, pi, kimi) are spawn-per-message,
- * so per-workspace instantiation has no cost; each factory returns a fresh
- * runner per call.
+ * Singleton caching: the factory MAY cache its instance internally. Most
+ * current agents (claude, opencode, pi, kimi) are spawn-per-message; codex is
+ * workspace-lifetime (app-server). Each factory returns a runner per call.
  *
  * Dynamic config reload: factory can read latest config via registry's
  * configContainer, enabling runtime config changes to take effect.