lark-remote 0.1.5 → 0.1.6

package/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.6] - 2026-08-14
+
+### 新增
+
+- Codex App Server 集成：通过 stdio JSON-RPC 持久连接 Codex CLI，支持审批流（文件读写/命令执行）、Compact 上下文压缩、空闲超时自动断开
+- Approval 审批系统：`approval-coordinator` 协调超时/取消/回复，`approval-render` 渲染审批按钮卡片
+- Codex runner 工厂：自动选择直连模式或 App Server 模式
+- `rollout-reader`：Codex App Server rollout 开关读取
+- Run card 审批区域渲染 + context limit 百分比显示
+- 架构文档：`codex-app-server-integration.md`
+
+### 修复
+
+- `/update` 命令移除自动重启逻辑
+- Codex 配置枚举回归官方标准值
+
 ## [0.1.5] - 2026-08-14
 
 ### 新增
@@ -136,3 +152,4 @@ Initial release.
 [0.1.3]: https://github.com/bungabungawoda/lark-remote/releases/tag/v0.1.3
 [0.1.4]: https://github.com/bungabungawoda/lark-remote/releases/tag/v0.1.4
 [0.1.5]: https://github.com/bungabungawoda/lark-remote/releases/tag/v0.1.5
+[0.1.6]: https://github.com/bungabungawoda/lark-remote/releases/tag/v0.1.6

package/README.en.md

@@ -153,10 +153,6 @@ Full docs under [`docs/`](docs/):
 
 > This package is a CLI tool only — no programmatic API is exposed.
 
-## Acknowledgments
-
-This project was inspired by [lark-coding-agent-bridge](https://github.com/zarazhangrui/lark-coding-agent-bridge) — thanks for demonstrating the feasibility of bridging Feishu with local coding agents.
-
 ## License
 
 [MIT](LICENSE) © bungabungawoda

package/README.md

@@ -152,10 +152,6 @@ FEISHU_LIVE_TEST=1 bun run test tests/feishu-reaction-emoji-live.test.ts
 
 > 本包为纯 CLI 工具，不提供编程 API。
 
-## 致谢
-
-本项目受到了 [lark-coding-agent-bridge](https://github.com/zarazhangrui/lark-coding-agent-bridge) 的启发，感谢该项目展示了飞书与本地 Coding Agent 桥接的可行性。
-
 ## License
 
 [MIT](LICENSE) © bungabungawoda

package/dist/bridge/approval-coordinator.d.ts

@@ -0,0 +1,108 @@
+/**
+ * ApprovalCoordinator: tracks and manages approval requests for a single run.
+ *
+ * Handles the lifecycle of command/file/permissions approval requests:
+ * - onRequested: add to tracking, arm timeout timer
+ * - onResolved: update state, clear timer
+ * - submit: validate → atomic state transition → async respond
+ * - togglePerm: flip permission item selection
+ * - onTurnEnded / onConnectionLost: mark all as expired
+ */
+import type { ApprovalRequestedEvent, ApprovalView, AgentEvent } from '../runner/types.js';
+export type ApprovalState = 'pending' | 'submitting' | 'resolved' | 'failed' | 'expired';
+export interface TrackedApproval {
+    requestId: number | string;
+    kind: 'command' | 'file' | 'permissions';
+    state: ApprovalState;
+    view: ApprovalView;
+    createdAt: number;
+    timeoutTimer: ReturnType<typeof setTimeout> | null;
+}
+export type ApprovalResponder = (requestId: number | string, response: unknown) => Promise<void>;
+export type ApprovalAction = {
+    action: 'accept';
+} | {
+    action: 'accept_for_session';
+} | {
+    action: 'accept_with_execpolicy_amendment';
+} | {
+    action: 'decline';
+} | {
+    action: 'cancel';
+};
+export interface ApprovalToggleAction {
+    permId: string;
+    selected: boolean;
+}
+export declare class ApprovalCoordinator {
+    private approvals;
+    /** 已提交过的 nonce（按 requestId）：同一按钮连点/飞书重投递只生效一次。 */
+    private submittedNonces;
+    private readonly runId;
+    private readonly userId;
+    private readonly chatId;
+    private readonly workspace;
+    private readonly approvalTimeoutMs;
+    private readonly responder;
+    private readonly interruptTurn;
+    private readonly pushToCard;
+    constructor(opts: {
+        runId: string;
+        userId: string;
+        chatId: string;
+        workspace: string;
+        approvalTimeoutMs: number;
+        responder: ApprovalResponder;
+        interruptTurn: () => Promise<void>;
+        pushToCard: (events: AgentEvent[]) => Promise<void>;
+    });
+    /**
+     * Handle an approval_requested event.
+     */
+    onRequested(event: ApprovalRequestedEvent): void;
+    /**
+     * Handle an approval_resolved event.
+     */
+    onResolved(requestId: number | string): void;
+    /**
+     * Handle turn ended — mark all pending approvals as expired.
+     */
+    onTurnEnded(): void;
+    /**
+     * Handle connection lost — same as onTurnEnded.
+     */
+    onConnectionLost(): void;
+    /**
+     * Submit an approval decision.
+     * Returns a promise that resolves when the response is sent.
+     */
+    submit(action: ApprovalAction, ctx: {
+        requestId: number | string;
+        nonce?: string;
+    }): Promise<string>;
+    /**
+     * Toggle a permission item's selected state.
+     */
+    togglePerm(action: ApprovalToggleAction, ctx: {
+        requestId: number | string;
+    }): Promise<string>;
+    /**
+     * Update a pending approval's view (out-of-order item/started arrives late).
+     * Only applies while the approval is still pending — resolved/expired
+     * approvals must not be resurrected or rewritten.
+     */
+    updateView(requestId: number | string, view: ApprovalView): void;
+    /**
+     * Get the number of pending approvals.
+     */
+    pendingCount(): number;
+    /**
+     * Get the head (oldest pending) approval, or undefined.
+     */
+    head(): TrackedApproval | undefined;
+    private clearTimer;
+    private expireApproval;
+    private actionToDecision;
+}
+/** Map a card decision string to the ApprovalAction used across the bridge. */
+export declare function decisionToApprovalAction(decision: string): ApprovalAction;

package/dist/bridge/approval-coordinator.js

@@ -0,0 +1,258 @@
+/**
+ * ApprovalCoordinator: tracks and manages approval requests for a single run.
+ *
+ * Handles the lifecycle of command/file/permissions approval requests:
+ * - onRequested: add to tracking, arm timeout timer
+ * - onResolved: update state, clear timer
+ * - submit: validate → atomic state transition → async respond
+ * - togglePerm: flip permission item selection
+ * - onTurnEnded / onConnectionLost: mark all as expired
+ */
+import { getLogger } from '../logger/index.js';
+// =============================================================================
+// Coordinator
+// =============================================================================
+export class ApprovalCoordinator {
+    approvals = new Map();
+    /** 已提交过的 nonce（按 requestId）：同一按钮连点/飞书重投递只生效一次。 */
+    submittedNonces = new Map();
+    runId;
+    userId;
+    chatId;
+    workspace;
+    approvalTimeoutMs;
+    responder;
+    interruptTurn;
+    pushToCard;
+    constructor(opts) {
+        this.runId = opts.runId;
+        this.userId = opts.userId;
+        this.chatId = opts.chatId;
+        this.workspace = opts.workspace;
+        this.approvalTimeoutMs = opts.approvalTimeoutMs;
+        this.responder = opts.responder;
+        this.interruptTurn = opts.interruptTurn;
+        this.pushToCard = opts.pushToCard;
+    }
+    /**
+     * Handle an approval_requested event.
+     */
+    onRequested(event) {
+        const existing = this.approvals.get(event.requestId);
+        if (existing) {
+            // Already tracked — update state
+            existing.state = 'pending';
+            existing.view = event.view;
+            return;
+        }
+        const timer = setTimeout(() => {
+            this.expireApproval(event.requestId);
+        }, this.approvalTimeoutMs);
+        const tracked = {
+            requestId: event.requestId,
+            kind: event.kind,
+            state: 'pending',
+            view: event.view,
+            createdAt: Date.now(),
+            timeoutTimer: timer,
+        };
+        this.approvals.set(event.requestId, tracked);
+    }
+    /**
+     * Handle an approval_resolved event.
+     */
+    onResolved(requestId) {
+        const tracked = this.approvals.get(requestId);
+        if (!tracked)
+            return;
+        tracked.state = 'resolved';
+        this.clearTimer(tracked);
+    }
+    /**
+     * Handle turn ended — mark all pending approvals as expired.
+     */
+    onTurnEnded() {
+        for (const [, tracked] of this.approvals) {
+            if (tracked.state === 'pending') {
+                tracked.state = 'expired';
+                this.clearTimer(tracked);
+            }
+        }
+    }
+    /**
+     * Handle connection lost — same as onTurnEnded.
+     */
+    onConnectionLost() {
+        this.onTurnEnded();
+    }
+    /**
+     * Submit an approval decision.
+     * Returns a promise that resolves when the response is sent.
+     */
+    async submit(action, ctx) {
+        const tracked = this.approvals.get(ctx.requestId);
+        if (!tracked) {
+            throw new Error(`Approval request ${ctx.requestId} not found`);
+        }
+        // nonce 去重：同一张卡片渲染出的按钮连续点击（或飞书重投递）携带相同
+        // nonce，只允许生效一次；不同渲染的按钮 nonce 不同，状态机（pending →
+        // submitting）仍然兜底防二次提交。
+        if (ctx.nonce !== undefined) {
+            const seen = this.submittedNonces.get(ctx.requestId) ?? new Set();
+            if (seen.has(ctx.nonce)) {
+                throw new Error(`Approval request ${ctx.requestId} already submitted (duplicate nonce)`);
+            }
+            seen.add(ctx.nonce);
+            this.submittedNonces.set(ctx.requestId, seen);
+        }
+        if (tracked.state !== 'pending') {
+            throw new Error(`Approval request ${ctx.requestId} is no longer pending (state=${tracked.state})`);
+        }
+        // Validate action against available decisions. decline/cancel are always
+        // allowed as a safety override: denying/interrupting is a universal human
+        // affordance even when the server's list omits them (observed in practice).
+        const decision = this.actionToDecision(action);
+        const safetyOverride = decision === 'decline' || decision === 'cancel';
+        if (!tracked.view.availableDecisions.includes(decision) && !safetyOverride) {
+            throw new Error(`Decision "${decision}" not in available decisions: ${tracked.view.availableDecisions.join(', ')}`);
+        }
+        // Atomic state transition: pending → submitting（同步，无 await）
+        tracked.state = 'submitting';
+        this.clearTimer(tracked);
+        // Send response via the responder
+        try {
+            await this.responder(ctx.requestId, action);
+            tracked.state = 'resolved';
+        }
+        catch {
+            tracked.state = 'failed';
+        }
+        return `Approval ${tracked.requestId} (${tracked.kind}): ${decision}`;
+    }
+    /**
+     * Toggle a permission item's selected state.
+     */
+    async togglePerm(action, ctx) {
+        const tracked = this.approvals.get(ctx.requestId);
+        if (!tracked) {
+            throw new Error(`Approval request ${ctx.requestId} not found`);
+        }
+        if (tracked.kind !== 'permissions') {
+            throw new Error(`Approval request ${ctx.requestId} is not a permissions request`);
+        }
+        if (tracked.state !== 'pending') {
+            throw new Error(`Approval request ${ctx.requestId} is no longer pending`);
+        }
+        const items = tracked.view.permissions?.items;
+        if (!items) {
+            throw new Error(`Approval request ${ctx.requestId} has no permissions items`);
+        }
+        const item = items.find((i) => i.id === action.permId);
+        if (!item) {
+            throw new Error(`Permission item ${action.permId} not found in request ${ctx.requestId}`);
+        }
+        item.selected = action.selected;
+        return `Permission ${action.permId}: ${action.selected ? 'granted' : 'denied'}`;
+    }
+    /**
+     * Update a pending approval's view (out-of-order item/started arrives late).
+     * Only applies while the approval is still pending — resolved/expired
+     * approvals must not be resurrected or rewritten.
+     */
+    updateView(requestId, view) {
+        const tracked = this.approvals.get(requestId);
+        if (!tracked || tracked.state !== 'pending')
+            return;
+        tracked.view = view;
+    }
+    /**
+     * Get the number of pending approvals.
+     */
+    pendingCount() {
+        let count = 0;
+        for (const [, tracked] of this.approvals) {
+            if (tracked.state === 'pending')
+                count++;
+        }
+        return count;
+    }
+    /**
+     * Get the head (oldest pending) approval, or undefined.
+     */
+    head() {
+        let oldest;
+        let oldestTime = Infinity;
+        for (const [, tracked] of this.approvals) {
+            if (tracked.state === 'pending' && tracked.createdAt < oldestTime) {
+                oldest = tracked;
+                oldestTime = tracked.createdAt;
+            }
+        }
+        return oldest;
+    }
+    // =========================================================================
+    // Internal
+    // =========================================================================
+    clearTimer(tracked) {
+        if (tracked.timeoutTimer !== null) {
+            clearTimeout(tracked.timeoutTimer);
+            tracked.timeoutTimer = null;
+        }
+    }
+    expireApproval(requestId) {
+        const tracked = this.approvals.get(requestId);
+        if (!tracked || tracked.state !== 'pending')
+            return;
+        tracked.state = 'expired';
+        this.clearTimer(tracked);
+        // 闭环：审批过期时向 server 发送 cancel（真实协议决策空间中的「停止等待」语义），
+        // 避免 server 无限等待审批响应。decline 仅是本桥 UI 安全兜底，不在真实协议内。
+        // 此前只改本地状态，server 只能等 runner 的 turn 超时兜底（用户「点了允许还超时」）。
+        void this.responder(requestId, { action: 'cancel' }).catch((err) => {
+            getLogger().warn(`[approval-coordinator] expiry cancel failed requestId=${requestId}: ${err instanceof Error ? err.message : String(err)}`);
+            // 响应失败不是「正常过期」：状态升级为 failed，避免误判为已正常通知
+            // server（spec R1：responder 抛错时状态置 failed）。
+            tracked.state = 'failed';
+            // 兜底：cancel 未能送达时主动中断 turn，避免 server 无限等待审批响应。
+            void this.interruptTurn().catch((interruptErr) => {
+                getLogger().warn(`[approval-coordinator] expiry interrupt failed requestId=${requestId}: ${interruptErr instanceof Error ? interruptErr.message : String(interruptErr)}`);
+            });
+        });
+        // 通知卡片进入过期态（run-renderer 渲染「⏰ 审批已过期」并隐藏按钮）。
+        void this.pushToCard([{ type: 'approval_expired', requestId }]).catch((err) => {
+            getLogger().warn(`[approval-coordinator] expiry card event failed requestId=${requestId}: ${err instanceof Error ? err.message : String(err)}`);
+        });
+    }
+    actionToDecision(action) {
+        switch (action.action) {
+            case 'accept':
+                return 'accept';
+            case 'accept_for_session':
+                return 'acceptForSession';
+            case 'accept_with_execpolicy_amendment':
+                return 'acceptWithExecpolicyAmendment';
+            case 'decline':
+                return 'decline';
+            case 'cancel':
+                return 'cancel';
+        }
+    }
+}
+/** Map a card decision string to the ApprovalAction used across the bridge. */
+export function decisionToApprovalAction(decision) {
+    switch (decision) {
+        case 'accept':
+            return { action: 'accept' };
+        case 'acceptForSession':
+            return { action: 'accept_for_session' };
+        case 'acceptWithExecpolicyAmendment':
+            return { action: 'accept_with_execpolicy_amendment' };
+        case 'decline':
+            return { action: 'decline' };
+        case 'cancel':
+            return { action: 'cancel' };
+        default:
+            return { action: 'decline' };
+    }
+}
+//# sourceMappingURL=approval-coordinator.js.map

package/dist/bridge/index.d.ts

@@ -25,6 +25,7 @@ interface BridgeChannel extends RunCardChannel {
     reconnect(): Promise<void>;
     sendFile(chatId: string, filePath: string): Promise<string>;
     addReaction(messageId: string, emoji: string): Promise<void>;
+    removeReactionByEmoji(messageId: string, emoji: string): Promise<void>;
 }
 /** Caller context for a bridge operation. */
 interface BridgeContext {
@@ -118,6 +119,13 @@ export declare class Bridge {
     private queueManager;
     /** Active runs per workspace (cwd). Multiple workspaces can run in parallel. */
     private activeRuns;
+    /** Approval coordinators keyed by runId. */
+    private approvalCoordinators;
+    /**
+     * 最近一次已完成的 codex app-server run（按 cwd）。run 结束后 activeRuns
+     * 已清空，Compact 需要它来校验 runId 并提供 sessionId。
+     */
+    private lastCompactableCodexRun;
     /**
      * Active `!` bash runs, keyed by runId (NOT cwd). Bash runs bypass the serial
      * queue and may run in parallel with claude runs / other bash runs in the same
@@ -324,6 +332,60 @@ export declare class Bridge {
      * find and return to this session without scrolling up.
      */
     private sendCompletionNotificationCard;
+    /**
+     * Handle an approval response from a card button click.
+     * Routes to the ApprovalCoordinator for the given run.
+     */
+    handleApprovalRespond(opts: {
+        runId: string;
+        requestId: number | string;
+        decision: string;
+        scope?: 'turn' | 'session';
+        nonce: string;
+    }): Promise<void>;
+    /**
+     * Handle a permission toggle from a card button click.
+     * Routes to the ApprovalCoordinator for the given run.
+     */
+    handleApprovalToggle(opts: {
+        runId: string;
+        requestId: number | string;
+        permId: string;
+        nonce: string;
+        selected?: boolean;
+    }): Promise<void>;
+    /**
+     * Handle codex.compact card action — trigger a Codex compaction request.
+     * Validates the run exists and is in a terminal state, then calls
+     * the app-server runner's runCompact().
+     */
+    handleCodexCompact(value: {
+        runId?: string;
+    }, ctx: BridgeContext): Promise<void>;
+    /**
+     * Stream a Codex compaction to a card: start a RunCardSession with
+     * operationKind='compaction' (no recursive Compact button), consume
+     * runner.runCompact() events, read authoritative jsonl usage, and finish
+     * the card. Shared by handleCodexCompact (run card button) and
+     * handleResumeCompact (resume cards) so both flows stay in sync.
+     *
+     * Precondition: callers have already validated that `runner` implements
+     * runCompact and that the session exists in `cwd`.
+     */
+    private streamCodexCompact;
+    /**
+     * Handle resume.compact card action — compact a session directly from a
+     * resume card (auto-resume / `/resume <id>`), without a runId.
+     *
+     * Unlike handleCodexCompact (which validates against the last finished run's
+     * runId), the resume card carries the sessionId + agent it was rendered for.
+     * Validation: the session must exist in the current cwd (same rule as
+     * cmdResume / resume.use) and the runner must implement runCompact.
+     */
+    handleResumeCompact(value: {
+        sessionId?: string;
+        agent?: string;
+    }, ctx: BridgeContext): Promise<void>;
     /**
      * Execute a bash command and stream output to a card.
      * `!` commands bypass the serial queue entirely (see body comment + §9.6):