lark-remote 0.1.5 → 0.1.6

package/dist/runner/codex/app-server/protocol-types.d.ts

@@ -0,0 +1,527 @@
+/**
+ * Codex App Server JSON-RPC Protocol Types
+ *
+ * Aligned with the real `codex app-server` protocol (v2, generated via
+ * `codex app-server generate-json-schema --experimental`). Method names and
+ * field names use the wire format exactly: camelCase paths for methods
+ * (`item/agentMessage/delta`) and snake_case only where the server requires it
+ * (e.g. permission profile fields).
+ */
+export interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id: number | string;
+    method: string;
+    params?: unknown;
+}
+export interface JsonRpcNotification {
+    jsonrpc: '2.0';
+    method: string;
+    params?: unknown;
+}
+export interface JsonRpcSuccessResponse {
+    jsonrpc: '2.0';
+    id: number | string;
+    result: unknown;
+}
+export interface JsonRpcErrorResponse {
+    jsonrpc: '2.0';
+    id: number | string | null;
+    error: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+export type ServerMessage = JsonRpcRequest | JsonRpcNotification | JsonRpcSuccessResponse | JsonRpcErrorResponse;
+/** Standard JSON-RPC error codes. */
+export declare const RpcErrorCode: {
+    readonly PARSE_ERROR: -32700;
+    readonly INVALID_REQUEST: -32600;
+    readonly METHOD_NOT_FOUND: -32601;
+    readonly INVALID_PARAMS: -32602;
+    readonly INTERNAL_ERROR: -32603;
+    /** Timeout error (custom, not standard JSON-RPC). */
+    readonly TIMEOUT_ERROR: -32000;
+    /** Connection lost / transport error (custom). */
+    readonly CONNECTION_LOST: -32001;
+};
+export interface ClientInfo {
+    name: string;
+    version: string;
+}
+export interface InitializeParams {
+    clientInfo: ClientInfo;
+    capabilities?: Record<string, unknown>;
+}
+export interface InitializeResult {
+    serverInfo?: {
+        name?: string;
+        version?: string;
+    };
+    protocolVersion?: string;
+    capabilities?: Record<string, unknown>;
+}
+export type SandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access';
+/** Response-side sandbox policy object (the request side uses `SandboxMode`
+ *  strings; the response reports the active policy as a structured object). */
+export interface SandboxPolicy {
+    type: 'dangerFullAccess' | 'readOnly' | 'externalSandbox' | 'workspaceWrite';
+    networkAccess?: boolean;
+    writableRoots?: string[];
+    [key: string]: unknown;
+}
+export type AskForApproval = 'untrusted' | 'on-request' | 'never' | {
+    granular: {
+        mcp_elicitations: boolean;
+        rules: boolean;
+        sandbox_approval: boolean;
+        request_permissions?: boolean;
+        skill_approval?: boolean;
+    };
+};
+export interface ThreadStartParams {
+    cwd?: string | null;
+    model?: string | null;
+    modelProvider?: string | null;
+    approvalPolicy?: AskForApproval;
+    sandbox?: SandboxMode;
+    permissions?: string | null;
+    config?: Record<string, unknown> | null;
+}
+export interface ThreadStartResponse {
+    thread: Thread;
+    cwd: string;
+    model: string;
+    modelProvider: string;
+    approvalPolicy: AskForApproval;
+    sandbox?: SandboxPolicy | null;
+}
+/** Real wire shape: ThreadStatus is a discriminated object, not a string. */
+export type ThreadStatus = {
+    type: 'notLoaded';
+} | {
+    type: 'idle';
+} | {
+    type: 'systemError';
+} | {
+    type: 'active';
+    activeFlags: unknown[];
+};
+export interface ThreadResumeParams {
+    threadId: string;
+    cwd?: string | null;
+    model?: string | null;
+    modelProvider?: string | null;
+    approvalPolicy?: AskForApproval;
+    sandbox?: SandboxMode;
+}
+export interface ThreadResumeResponse {
+    thread: Thread;
+    cwd: string;
+    model: string;
+    modelProvider: string;
+}
+export interface ThreadCompactStartParams {
+    threadId: string;
+}
+export interface Thread {
+    id: string;
+    sessionId: string;
+    status: ThreadStatus;
+    cwd: string;
+    preview: string;
+    turns: Turn[];
+    createdAt: number;
+    updatedAt: number;
+    modelProvider: string;
+    cliVersion: string;
+    ephemeral: boolean;
+    name?: string | null;
+    forkedFromId?: string | null;
+    parentThreadId?: string | null;
+}
+export interface UserInput {
+    type: 'text';
+    text: string;
+    text_elements?: unknown[];
+}
+export interface TurnStartParams {
+    threadId: string;
+    input: UserInput[];
+    model?: string | null;
+    effort?: string | null;
+    cwd?: string | null;
+    approvalPolicy?: AskForApproval;
+    sandboxPolicy?: SandboxMode;
+}
+export interface TurnStartResponse {
+    turn: Turn;
+}
+export interface TurnInterruptParams {
+    threadId: string;
+    turnId: string;
+}
+export type TurnStatus = 'inProgress' | 'completed' | 'failed' | 'interrupted';
+export interface TurnError {
+    message: string;
+    additionalDetails?: string | null;
+    codexErrorInfo?: unknown;
+}
+export interface Turn {
+    id: string;
+    items: ThreadItem[];
+    status: TurnStatus;
+    error?: TurnError | null;
+    startedAt?: number | null;
+    completedAt?: number | null;
+    durationMs?: number | null;
+}
+export interface AgentMessageItem {
+    type: 'agentMessage';
+    id: string;
+    text: string;
+    phase?: string | null;
+}
+export interface ReasoningItem {
+    type: 'reasoning';
+    id: string;
+    content?: string[];
+    summary?: string[];
+}
+export interface CommandExecutionItem {
+    type: 'commandExecution';
+    id: string;
+    command: string;
+    cwd?: string | null;
+    aggregatedOutput?: string | null;
+    status?: string | null;
+}
+export interface PlanItem {
+    type: 'plan';
+    id: string;
+    text: string;
+}
+export interface FileChangeItem {
+    type: 'fileChange';
+    id: string;
+    changes: FileUpdateChange[];
+    status: string;
+}
+export interface FileUpdateChangeKind {
+    type: 'add' | 'delete' | 'update';
+    /** Present only on `update` kind — the move destination, if any. */
+    move_path?: string | null;
+}
+export interface FileUpdateChange {
+    path: string;
+    kind: FileUpdateChangeKind;
+    diff: string;
+}
+export interface ObservationItem {
+    type: 'observation';
+    id: string;
+    content: string;
+    timestamp: number;
+}
+export interface DiffItem {
+    type: 'diff';
+    id: string;
+    diff: string;
+    timestamp: number;
+}
+export type ThreadItem = AgentMessageItem | ReasoningItem | CommandExecutionItem | PlanItem | FileChangeItem | ObservationItem | DiffItem | {
+    type: 'userMessage';
+    id: string;
+    content: unknown[];
+} | {
+    type: 'contextCompaction';
+    id: string;
+    [key: string]: unknown;
+} | {
+    type: string;
+    id: string;
+    [key: string]: unknown;
+};
+export interface PlanStep {
+    id?: string;
+    title: string;
+    subtitle?: string;
+    status?: 'pending' | 'in_progress' | 'completed' | 'error';
+}
+export declare const NotificationMethod: {
+    readonly TURN_STARTED: "turn/started";
+    readonly TURN_COMPLETED: "turn/completed";
+    readonly TURN_DIFF_UPDATED: "turn/diff/updated";
+    readonly TURN_PLAN_UPDATED: "turn/plan/updated";
+    readonly ITEM_STARTED: "item/started";
+    readonly ITEM_COMPLETED: "item/completed";
+    readonly AGENT_MESSAGE_DELTA: "item/agentMessage/delta";
+    readonly REASONING_SUMMARY_TEXT_DELTA: "item/reasoning/summaryTextDelta";
+    readonly REASONING_SUMMARY_PART_ADDED: "item/reasoning/summaryPartAdded";
+    readonly REASONING_TEXT_DELTA: "item/reasoning/textDelta";
+    readonly COMMAND_EXECUTION_OUTPUT_DELTA: "item/commandExecution/outputDelta";
+    readonly FILE_CHANGE_OUTPUT_DELTA: "item/fileChange/outputDelta";
+    readonly PLAN_DELTA: "item/plan/delta";
+    readonly TOKEN_USAGE_UPDATED: "thread/tokenUsage/updated";
+    readonly SERVER_REQUEST_RESOLVED: "serverRequest/resolved";
+    readonly ERROR: "error";
+    readonly WARNING: "warning";
+    readonly THREAD_STARTED: "thread/started";
+    readonly THREAD_STATUS_CHANGED: "thread/status/changed";
+    readonly THREAD_COMPACTED: "thread/compacted";
+    readonly MODEL_REROUTED: "model/rerouted";
+};
+export interface TurnStartedNotification {
+    method: 'turn/started';
+    params: {
+        threadId: string;
+        turn: Turn;
+    };
+}
+export interface TurnCompletedNotification {
+    method: 'turn/completed';
+    params: {
+        threadId: string;
+        turn: Turn;
+    };
+}
+export interface ItemStartedNotification {
+    method: 'item/started';
+    params: {
+        threadId: string;
+        turnId: string;
+        item: ThreadItem;
+        startedAtMs: number;
+    };
+}
+export interface ItemCompletedNotification {
+    method: 'item/completed';
+    params: {
+        threadId: string;
+        turnId: string;
+        item: ThreadItem;
+        completedAtMs: number;
+    };
+}
+export interface AgentMessageDeltaNotification {
+    method: 'item/agentMessage/delta';
+    params: {
+        threadId: string;
+        turnId: string;
+        itemId: string;
+        delta: string;
+    };
+}
+export interface ReasoningSummaryTextDeltaNotification {
+    method: 'item/reasoning/summaryTextDelta';
+    params: {
+        threadId: string;
+        turnId: string;
+        itemId: string;
+        delta: string;
+    };
+}
+export interface ReasoningSummaryPartAddedNotification {
+    method: 'item/reasoning/summaryPartAdded';
+    params: {
+        threadId: string;
+        turnId: string;
+        itemId: string;
+        summaryIndex: number;
+    };
+}
+export interface ReasoningTextDeltaNotification {
+    method: 'item/reasoning/textDelta';
+    params: {
+        threadId: string;
+        turnId: string;
+        itemId: string;
+        delta: string;
+        contentIndex: number;
+    };
+}
+export interface CommandExecutionOutputDeltaNotification {
+    method: 'item/commandExecution/outputDelta';
+    params: {
+        threadId: string;
+        turnId: string;
+        itemId: string;
+        delta: string;
+    };
+}
+export interface PlanDeltaNotification {
+    method: 'item/plan/delta';
+    params: {
+        threadId: string;
+        turnId: string;
+        itemId: string;
+        /** EXPERIMENTAL — plain-text plan delta; do not assume concatenation
+         *  matches the completed plan item content. */
+        delta: string;
+    };
+}
+export interface FileChangeOutputDeltaNotification {
+    method: 'item/fileChange/outputDelta';
+    params: {
+        threadId: string;
+        turnId: string;
+        itemId: string;
+        delta: string;
+    };
+}
+export interface TokenUsageBreakdown {
+    inputTokens: number;
+    outputTokens: number;
+    cachedInputTokens?: number;
+    totalTokens?: number;
+    cacheReadTokens?: number;
+    cacheCreationTokens?: number;
+}
+export interface ThreadTokenUsage {
+    last: TokenUsageBreakdown;
+    total: TokenUsageBreakdown;
+    /** 当前模型 context window 上限（v2 schema 中与 last/total 平级；
+     *  app-server 模式下唯一携带该信息的通道，CLI token_count 无此字段）。 */
+    modelContextWindow?: number;
+}
+export interface ThreadTokenUsageUpdatedNotification {
+    method: 'thread/tokenUsage/updated';
+    params: {
+        threadId: string;
+        turnId: string;
+        tokenUsage: ThreadTokenUsage;
+    };
+}
+export interface ServerRequestResolvedNotification {
+    method: 'serverRequest/resolved';
+    params: {
+        threadId: string;
+        requestId: number | string;
+    };
+}
+export interface ErrorNotification {
+    method: 'error';
+    params: {
+        error: TurnError;
+        threadId: string;
+        turnId: string;
+        willRetry: boolean;
+    };
+}
+export interface WarningNotification {
+    method: 'warning';
+    params: {
+        threadId?: string;
+        turnId?: string;
+        code: string;
+        message: string;
+        timestamp?: string;
+    };
+}
+export interface ThreadStatusChangedNotification {
+    method: 'thread/status/changed';
+    params: {
+        threadId: string;
+        status: string;
+        timestamp?: string;
+    };
+}
+export interface ModelReroutedNotification {
+    method: 'model/rerouted';
+    params: {
+        threadId: string;
+        turnId?: string;
+        model: string;
+        reason?: string;
+        timestamp?: string;
+    };
+}
+export declare const ServerRequestMethod: {
+    readonly COMMAND_EXECUTION_APPROVAL: "item/commandExecution/requestApproval";
+    readonly FILE_CHANGE_APPROVAL: "item/fileChange/requestApproval";
+    readonly PERMISSIONS_APPROVAL: "item/permissions/requestApproval";
+};
+export interface NetworkApprovalContext {
+    host: string;
+    protocol: string;
+    port?: number | null;
+}
+export interface CommandExecutionRequestApprovalParams {
+    threadId: string;
+    turnId: string;
+    itemId: string;
+    startedAtMs: number;
+    command?: string | null;
+    cwd?: string | null;
+    reason?: string | null;
+    availableDecisions?: CommandExecutionApprovalDecision[] | null;
+    networkApprovalContext?: NetworkApprovalContext | null;
+    approvalId?: string | null;
+}
+export interface NetworkPolicyAmendment {
+    host: string;
+    action: 'allow' | 'deny';
+}
+/** Real wire shape: plain-string decisions plus structured decisions. */
+export type CommandExecutionApprovalDecision = 'accept' | 'acceptForSession' | 'decline' | 'cancel' | {
+    acceptWithExecpolicyAmendment: {
+        execpolicy_amendment: string[];
+    };
+} | {
+    applyNetworkPolicyAmendment: {
+        network_policy_amendment: NetworkPolicyAmendment;
+    };
+};
+export interface CommandExecutionRequestApprovalResponse {
+    decision: CommandExecutionApprovalDecision;
+}
+export interface FileChangeRequestApprovalParams {
+    threadId: string;
+    turnId: string;
+    itemId: string;
+    startedAtMs: number;
+    grantRoot?: string | null;
+    reason?: string | null;
+}
+export type FileChangeApprovalDecision = 'accept' | 'acceptForSession' | 'decline' | 'cancel';
+export interface FileChangeRequestApprovalResponse {
+    decision: FileChangeApprovalDecision;
+}
+export type FileSystemAccessMode = 'read' | 'write' | 'deny';
+export interface FileSystemSandboxEntry {
+    path: string;
+    access: FileSystemAccessMode;
+}
+/** Real wire shape: `read`/`write` are legacy string arrays; `entries` is the
+ *  current structured form (`[{ path, access }]`). */
+export interface AdditionalFileSystemPermissions {
+    entries?: FileSystemSandboxEntry[] | null;
+    read?: string[] | null;
+    write?: string[] | null;
+}
+export interface AdditionalNetworkPermissions {
+    enabled?: boolean | null;
+}
+export interface RequestPermissionProfile {
+    fileSystem?: AdditionalFileSystemPermissions | null;
+    network?: AdditionalNetworkPermissions | null;
+}
+export interface GrantedPermissionProfile {
+    fileSystem?: AdditionalFileSystemPermissions | null;
+    network?: AdditionalNetworkPermissions | null;
+}
+export interface PermissionsRequestApprovalParams {
+    threadId: string;
+    turnId: string;
+    itemId: string;
+    startedAtMs: number;
+    cwd: string;
+    permissions: RequestPermissionProfile;
+    reason?: string | null;
+}
+export interface PermissionsRequestApprovalResponse {
+    permissions: GrantedPermissionProfile;
+    scope?: 'turn' | 'session';
+}
+/** Unsupported / ignored server request methods. */
+export declare const UNSUPPORTED_SERVER_REQUEST_METHODS: Set<string>;

package/dist/runner/codex/app-server/protocol-types.js

@@ -0,0 +1,67 @@
+/**
+ * Codex App Server JSON-RPC Protocol Types
+ *
+ * Aligned with the real `codex app-server` protocol (v2, generated via
+ * `codex app-server generate-json-schema --experimental`). Method names and
+ * field names use the wire format exactly: camelCase paths for methods
+ * (`item/agentMessage/delta`) and snake_case only where the server requires it
+ * (e.g. permission profile fields).
+ */
+/** Standard JSON-RPC error codes. */
+export const RpcErrorCode = {
+    PARSE_ERROR: -32700,
+    INVALID_REQUEST: -32600,
+    METHOD_NOT_FOUND: -32601,
+    INVALID_PARAMS: -32602,
+    INTERNAL_ERROR: -32603,
+    /** Timeout error (custom, not standard JSON-RPC). */
+    TIMEOUT_ERROR: -32000,
+    /** Connection lost / transport error (custom). */
+    CONNECTION_LOST: -32001,
+};
+// =============================================================================
+// Notifications (server → client)
+// =============================================================================
+export const NotificationMethod = {
+    TURN_STARTED: 'turn/started',
+    TURN_COMPLETED: 'turn/completed',
+    TURN_DIFF_UPDATED: 'turn/diff/updated',
+    TURN_PLAN_UPDATED: 'turn/plan/updated',
+    ITEM_STARTED: 'item/started',
+    ITEM_COMPLETED: 'item/completed',
+    AGENT_MESSAGE_DELTA: 'item/agentMessage/delta',
+    REASONING_SUMMARY_TEXT_DELTA: 'item/reasoning/summaryTextDelta',
+    REASONING_SUMMARY_PART_ADDED: 'item/reasoning/summaryPartAdded',
+    REASONING_TEXT_DELTA: 'item/reasoning/textDelta',
+    COMMAND_EXECUTION_OUTPUT_DELTA: 'item/commandExecution/outputDelta',
+    FILE_CHANGE_OUTPUT_DELTA: 'item/fileChange/outputDelta',
+    PLAN_DELTA: 'item/plan/delta',
+    TOKEN_USAGE_UPDATED: 'thread/tokenUsage/updated',
+    SERVER_REQUEST_RESOLVED: 'serverRequest/resolved',
+    ERROR: 'error',
+    WARNING: 'warning',
+    THREAD_STARTED: 'thread/started',
+    THREAD_STATUS_CHANGED: 'thread/status/changed',
+    THREAD_COMPACTED: 'thread/compacted',
+    MODEL_REROUTED: 'model/rerouted',
+};
+// =============================================================================
+// Server Requests (approval)
+// =============================================================================
+export const ServerRequestMethod = {
+    COMMAND_EXECUTION_APPROVAL: 'item/commandExecution/requestApproval',
+    FILE_CHANGE_APPROVAL: 'item/fileChange/requestApproval',
+    PERMISSIONS_APPROVAL: 'item/permissions/requestApproval',
+};
+/** Unsupported / ignored server request methods. */
+export const UNSUPPORTED_SERVER_REQUEST_METHODS = new Set([
+    'item/tool/requestUserInput',
+    'mcpServer/elicitation/request',
+    'item/tool/call',
+    'account/chatgptAuthTokens/refresh',
+    'attestation/generate',
+    'currentTime/read',
+    'applyPatchApproval',
+    'execCommandApproval',
+]);
+//# sourceMappingURL=protocol-types.js.map

package/dist/runner/codex/app-server/runner.d.ts

@@ -0,0 +1,121 @@
+/**
+ * CodexAppServerRunner: workspace-lifetime runner using the Codex App Server
+ * protocol (`codex app-server`, JSON-RPC over stdio).
+ *
+ * Flow per run: acquire persistent connection → thread/start or thread/resume
+ * → turn/start → consume notifications (agent message deltas, approval server
+ * requests, …) until turn/completed → synthesize ResultEvent.
+ */
+import type { AgentKind, AgentSessionReader, AgentEvent, AgentRunner, AgentStatusInfo, SpawnOptions } from '../../types.js';
+import { type AskForApproval, type SandboxMode } from './protocol-types.js';
+export interface CodexAppServerRunnerOptions {
+    kind: AgentKind;
+    sessionReader: AgentSessionReader;
+    /** Path to the codex binary. Defaults to `codex`. */
+    binary?: string;
+    /** Environment variables. */
+    env?: Record<string, string | undefined>;
+    /** Args to spawn the app server with. Defaults to `['app-server', '--stdio']`. */
+    appServerArgs?: string[];
+    /** Request timeout in milliseconds. */
+    requestTimeoutMs?: number;
+    /** Idle TTL for connection manager. */
+    idleTtlMs?: number;
+    /** How long to wait for turn output before failing. Defaults to 10 min. */
+    turnTimeoutMs?: number;
+    model?: string;
+    modelProvider?: string;
+    reasoningEffort?: string;
+    /** Configured sandbox mode (Codex 官方 SandboxMode 标准值). */
+    sandbox?: SandboxMode;
+    /** Configured approval policy (Codex 官方 AskForApproval 标准值). */
+    approvalPolicy?: AskForApproval;
+}
+export declare class CodexAppServerRunner implements AgentRunner {
+    readonly kind: AgentKind;
+    readonly sessionReader: AgentSessionReader;
+    readonly lifetime: "workspace";
+    private connectionManager;
+    private currentClient;
+    private currentTranslator;
+    private currentThreadId;
+    private currentTurnId;
+    private lastEventAt;
+    private _isRunning;
+    private model?;
+    private modelProvider?;
+    private reasoningEffort?;
+    private sandboxConfig?;
+    private approvalPolicyConfig?;
+    private readonly turnTimeoutMs;
+    /** Pending approval requests: requestId (JSON-RPC id) → kind + view. */
+    private pendingApprovals;
+    /** Notification queue consumed by the active run generator. */
+    private notificationQueue;
+    private waitResolve;
+    private forceFinish;
+    /** stop() 在 turn/start 响应前到达时置位，turn/start 完成后补发 interrupt。 */
+    private stopRequested;
+    constructor(opts: CodexAppServerRunnerOptions);
+    get isRunning(): boolean;
+    /**
+     * Run a message in the current thread.
+     *
+     * 进程容错：若 app-server 子进程被外部误杀或自身异常退出（连接丢失），
+     * 自动重拉进程并重试一次 setup（thread/start 或按 sessionId thread/resume
+     * 继续处理），保证消费用户消息时进程挂了也能恢复。
+     */
+    run(message: string, opts: SpawnOptions): AsyncGenerator<AgentEvent>;
+    /**
+     * Acquire the connection and set up the turn: thread/start（新会话）或
+     * thread/resume（按 sessionId 恢复既有线程）→ turn/start。
+     */
+    private setupTurn;
+    /**
+     * Run a compact operation on the current thread.
+     */
+    runCompact(_message: string, opts: SpawnOptions): AsyncGenerator<AgentEvent>;
+    /**
+     * Stop the current turn by interrupting it.
+     */
+    stop(_opts?: {
+        immediate?: boolean;
+    }): Promise<void>;
+    /**
+     * Respond to an approval server request. `response` is the bridge
+     * ApprovalAction (`{ action: 'accept' | 'accept_for_session' | 'decline' | 'cancel' }`).
+     */
+    respondApproval(requestId: number | string, response: unknown): Promise<void>;
+    /**
+     * Dispose the runner: release the connection.
+     */
+    dispose(): Promise<void>;
+    getUsageAuthority(): 'live';
+    killOrphan(): void;
+    registerExitHandlers(): void;
+    unregisterExitHandlers(): void;
+    getStatusInfo(): AgentStatusInfo;
+    private buildThreadParams;
+    private buildTurnParams;
+    /**
+     * Consume the notification queue until a result event arrives or the turn
+     * times out / is interrupted.
+     */
+    private consumeTurn;
+    /**
+     * Compute the current idle deadline. 0 disables the idle timeout; otherwise
+     * the deadline is based on the last received event, not the turn start time.
+     */
+    private nextTurnIdleDeadline;
+    private interruptCurrentTurn;
+    private waitForEvents;
+    private handleNotification;
+    private handleServerRequest;
+    private pushEvents;
+    private wakeWaiters;
+    private failTurn;
+    private resetRunState;
+    private buildGrantedPermissions;
+    /** 拒绝权限审批：空 fileSystem + 关闭网络（真实 GrantedPermissionProfile）。 */
+    private denyAllPermissions;
+}