lark-remote 0.5.5 → 0.5.7

package/dist/runner/dsh/exit-cancel.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Synchronous `session/cancel` for the process-exit path.
+ *
+ * A DSH turn does not live in a local child process: it runs inside the shared
+ * `dsh web` host (`DshDaemon`). So the usual "kill my spawned child" exit
+ * cleanup does nothing for it, and a bridge that exits mid-turn leaves the
+ * turn running with no subscriber — an orphan turn that keeps consuming tokens
+ * and mutating the workspace invisibly (2026-10-19: one ran 2h21m / 345 steps
+ * after its bridge died).
+ *
+ * `process.on('exit')` cannot await, so this path uses the same synchronous
+ * curl transport the session reader already uses: bounded by `timeoutMs` and
+ * never throws.
+ */
+/** Upper bound on the exit-path cancel:退出不能被一个卡住的 host 拖住。 */
+export declare const EXIT_CANCEL_TIMEOUT_MS = 2000;
+export interface SyncCancelOptions {
+    baseUrl: string;
+    sessionId: string;
+    /** Configured `agents.dsh.dshHome` (selects `.credentials.yaml`). */
+    dshHome?: string;
+    /** Explicit credentials file; wins over `dshHome`/`$DSH_HOME`. */
+    credentialsFile?: string;
+    timeoutMs?: number;
+}
+/**
+ * Fire one `session/cancel` synchronously. Never throws: a failed cancel must
+ * not block the exit path or mask the real exit reason.
+ *
+ * @returns true when the host accepted the request.
+ */
+export declare function cancelSessionSync(opts: SyncCancelOptions): boolean;

package/dist/runner/dsh/exit-cancel.js

@@ -0,0 +1,72 @@
+/**
+ * Synchronous `session/cancel` for the process-exit path.
+ *
+ * A DSH turn does not live in a local child process: it runs inside the shared
+ * `dsh web` host (`DshDaemon`). So the usual "kill my spawned child" exit
+ * cleanup does nothing for it, and a bridge that exits mid-turn leaves the
+ * turn running with no subscriber — an orphan turn that keeps consuming tokens
+ * and mutating the workspace invisibly (2026-10-19: one ran 2h21m / 345 steps
+ * after its bridge died).
+ *
+ * `process.on('exit')` cannot await, so this path uses the same synchronous
+ * curl transport the session reader already uses: bounded by `timeoutMs` and
+ * never throws.
+ */
+import { getLogger } from '../../logger/index.js';
+import { isWin32 } from '../../platform/select.js';
+import { spawnProcessSync } from '../../platform/spawn.js';
+import { DSH_COOKIE_LIFETIME_MS, mintDshBrowserCookie, readDshBrowserSecretSync, resolveDshCredentialsFile, } from './auth.js';
+/** Upper bound on the exit-path cancel:退出不能被一个卡住的 host 拖住。 */
+export const EXIT_CANCEL_TIMEOUT_MS = 2_000;
+/**
+ * Fire one `session/cancel` synchronously. Never throws: a failed cancel must
+ * not block the exit path or mask the real exit reason.
+ *
+ * @returns true when the host accepted the request.
+ */
+export function cancelSessionSync(opts) {
+    const logger = getLogger();
+    const timeoutMs = opts.timeoutMs ?? EXIT_CANCEL_TIMEOUT_MS;
+    let cookie;
+    try {
+        const file = opts.credentialsFile?.trim() || resolveDshCredentialsFile(process.env, opts.dshHome);
+        cookie = mintDshBrowserCookie(opts.baseUrl, readDshBrowserSecretSync(file), Date.now(), DSH_COOKIE_LIFETIME_MS);
+    }
+    catch (err) {
+        // 没有持久密钥就签不出 cookie；此时只能记一笔，放弃取消（启动 token 的
+        // /connect 换 cookie 是异步的，退出路径上等不起）。
+        logger.warn(`[dsh] exit-cancel skipped: cannot mint cookie (${err.message})`);
+        return false;
+    }
+    const body = JSON.stringify({
+        type: 'client-request',
+        rpcId: `rpc-exit-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+        method: 'session/cancel',
+        payload: { args: { request: { sessionId: opts.sessionId } } },
+    });
+    const res = spawnProcessSync('curl', [
+        '-s',
+        '-o',
+        isWin32() ? 'NUL' : '/dev/null',
+        '-w',
+        '%{http_code}',
+        '-X',
+        'POST',
+        `${opts.baseUrl.replace(/\/$/, '')}/api/session/cancel`,
+        '-H',
+        'content-type: application/json',
+        '-H',
+        `Cookie: ${cookie}`,
+        '--max-time',
+        String(Math.max(1, Math.ceil(timeoutMs / 1000))),
+        '--data',
+        body,
+    ], { encoding: 'utf-8', timeout: timeoutMs, maxBuffer: 1024 * 1024 });
+    const status = String(res.stdout ?? '').trim();
+    const ok = status === '200';
+    if (!ok) {
+        logger.warn(`[dsh] exit-cancel failed for ${opts.sessionId}: ${res.error?.message ?? `http ${status || 'n/a'}`}`);
+    }
+    return ok;
+}
+//# sourceMappingURL=exit-cancel.js.map

package/dist/runner/dsh/inflight.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Durable record of DSH prompts that may outlive the bridge process.
+ *
+ * A DSH turn runs inside the shared `dsh web` host, not in a child process. If
+ * the bridge dies (SIGKILL, crash) the turn keeps running with no subscriber —
+ * the 2026-10-19 incident ran 2h21m / 345 steps after its bridge exited. The
+ * runner writes one entry when it submits a prompt and removes it once the run
+ * (or a verified stop) accounts for that prompt; the next startup reconciles
+ * anything left behind:
+ *
+ *  1. a still-pending prompt (identified by `source.rpcId`) is removed from the
+ *     host inbox, so it can never start a turn nobody is watching;
+ *  2. a session that still reports an open turn is reported to the owner once —
+ *     we deliberately do not cancel it, because the open turn may belong to the
+ *     DSH Web UI rather than to the dead bridge.
+ *
+ * This is a best-effort safety net, never a correctness dependency: every
+ * method swallows storage errors so a broken state file cannot block a run.
+ */
+import type { DshClient } from './client.js';
+/** Single source for the marker file shared by the runner and startup reconcile. */
+export declare function dshInflightPath(configDir: string): string;
+export interface DshInflightEntry {
+    sessionId: string;
+    promptRequestId: string;
+    baseUrl: string;
+    cwd?: string;
+    updatedAt: number;
+}
+export declare class DshInflightStore {
+    private readonly filePath;
+    constructor(filePath: string);
+    list(): DshInflightEntry[];
+    record(entry: Omit<DshInflightEntry, 'updatedAt'>): void;
+    clear(sessionId: string, promptRequestId: string): void;
+    private write;
+}
+export interface DshInflightReconcileOptions {
+    store: DshInflightStore;
+    client: Pick<DshClient, 'baseUrl' | 'findPendingPrompt' | 'removeQueuedPrompt' | 'openTurnState'>;
+    /** Owner notification; omitted when no p2p recipient is known yet. */
+    notify?: (text: string) => Promise<void>;
+    timeoutMs?: number;
+}
+export interface DshInflightReconcileResult {
+    /** Pending prompts removed from the host inbox. */
+    removed: number;
+    /** Sessions that still reported an open turn (or an unreadable state). */
+    open: number;
+    /** True when the host was unreachable; entries are kept for the next start. */
+    skipped: boolean;
+}
+/**
+ * Reconcile entries left by a previous process.
+ *
+ * Only entries for the currently configured host are considered; entries for
+ * another host are kept untouched. On a transport failure the remaining
+ * entries are left in the file so a later startup can retry.
+ */
+export declare function reconcileInflightDshRuns(opts: DshInflightReconcileOptions): Promise<DshInflightReconcileResult>;
+/** One short owner-facing notice; session ids are truncated, not paths. */
+export declare function formatInflightWarning(entries: DshInflightEntry[]): string;

package/dist/runner/dsh/inflight.js

@@ -0,0 +1,140 @@
+/**
+ * Durable record of DSH prompts that may outlive the bridge process.
+ *
+ * A DSH turn runs inside the shared `dsh web` host, not in a child process. If
+ * the bridge dies (SIGKILL, crash) the turn keeps running with no subscriber —
+ * the 2026-10-19 incident ran 2h21m / 345 steps after its bridge exited. The
+ * runner writes one entry when it submits a prompt and removes it once the run
+ * (or a verified stop) accounts for that prompt; the next startup reconciles
+ * anything left behind:
+ *
+ *  1. a still-pending prompt (identified by `source.rpcId`) is removed from the
+ *     host inbox, so it can never start a turn nobody is watching;
+ *  2. a session that still reports an open turn is reported to the owner once —
+ *     we deliberately do not cancel it, because the open turn may belong to the
+ *     DSH Web UI rather than to the dead bridge.
+ *
+ * This is a best-effort safety net, never a correctness dependency: every
+ * method swallows storage errors so a broken state file cannot block a run.
+ */
+import path from 'node:path';
+import { getLogger } from '../../logger/index.js';
+import { atomicWriteJson } from '../../persistence/atomic-write.js';
+import { loadJsonFile } from '../../persistence/load-json-file.js';
+/** Single source for the marker file shared by the runner and startup reconcile. */
+export function dshInflightPath(configDir) {
+    return path.join(configDir, 'dsh-inflight.json');
+}
+/** Keep the file bounded; stale entries are pruned by age and count. */
+const MAX_ENTRIES = 50;
+/** A turn cannot plausibly live this long; drop the record instead of nagging. */
+const MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+function isEntry(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const entry = value;
+    return (typeof entry.sessionId === 'string' &&
+        entry.sessionId.length > 0 &&
+        typeof entry.promptRequestId === 'string' &&
+        entry.promptRequestId.length > 0 &&
+        typeof entry.baseUrl === 'string' &&
+        entry.baseUrl.length > 0 &&
+        typeof entry.updatedAt === 'number');
+}
+function sameEntry(left, right) {
+    return left.sessionId === right.sessionId && left.promptRequestId === right.promptRequestId;
+}
+export class DshInflightStore {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    list() {
+        const parsed = loadJsonFile(this.filePath, undefined);
+        const raw = Array.isArray(parsed?.entries) ? parsed.entries : [];
+        const now = Date.now();
+        return raw
+            .filter(isEntry)
+            .filter((entry) => now - entry.updatedAt <= MAX_AGE_MS)
+            .slice(-MAX_ENTRIES);
+    }
+    record(entry) {
+        const next = this.list().filter((existing) => !sameEntry(existing, entry));
+        next.push({ ...entry, updatedAt: Date.now() });
+        this.write(next);
+    }
+    clear(sessionId, promptRequestId) {
+        const next = this.list().filter((entry) => !sameEntry(entry, { sessionId, promptRequestId }));
+        this.write(next);
+    }
+    write(entries) {
+        try {
+            atomicWriteJson(this.filePath, { entries: entries.slice(-MAX_ENTRIES) });
+        }
+        catch (err) {
+            // The marker is a safety net; losing it must never fail the run.
+            getLogger().warn(`[dsh] inflight marker write failed: ${err.message}`);
+        }
+    }
+}
+/**
+ * Reconcile entries left by a previous process.
+ *
+ * Only entries for the currently configured host are considered; entries for
+ * another host are kept untouched. On a transport failure the remaining
+ * entries are left in the file so a later startup can retry.
+ */
+export async function reconcileInflightDshRuns(opts) {
+    const timeoutMs = opts.timeoutMs ?? 3_000;
+    const entries = opts.store.list().filter((entry) => entry.baseUrl === opts.client.baseUrl);
+    if (entries.length === 0)
+        return { removed: 0, open: 0, skipped: false };
+    let removed = 0;
+    const open = [];
+    for (const entry of entries.slice(0, 10)) {
+        try {
+            const itemId = await opts.client.findPendingPrompt(entry.sessionId, entry.promptRequestId, {
+                timeoutMs,
+            });
+            if (itemId) {
+                const ok = await opts.client.removeQueuedPrompt(entry.sessionId, itemId, { timeoutMs });
+                if (ok)
+                    removed++;
+            }
+            const state = await opts.client.openTurnState(entry.sessionId, { timeoutMs });
+            if (state !== 'closed')
+                open.push(entry);
+            // Handled once: do not nag on every later startup.
+            opts.store.clear(entry.sessionId, entry.promptRequestId);
+        }
+        catch (err) {
+            getLogger().warn(`[dsh] inflight reconcile skipped (host unreachable?): ${err.message}`);
+            return { removed, open: open.length, skipped: true };
+        }
+    }
+    if (open.length > 0) {
+        getLogger().warn(`[dsh] inflight reconcile: ${open.length} session(s) may still have an open turn`);
+        if (opts.notify) {
+            try {
+                await opts.notify(formatInflightWarning(open));
+            }
+            catch (err) {
+                getLogger().warn(`[dsh] inflight notice failed: ${err.message}`);
+            }
+        }
+    }
+    return { removed, open: open.length, skipped: false };
+}
+/** One short owner-facing notice; session ids are truncated, not paths. */
+export function formatInflightWarning(entries) {
+    const lines = entries.slice(0, 3).map((entry) => {
+        const id = entry.sessionId.length > 8 ? entry.sessionId.slice(0, 8) : entry.sessionId;
+        return `- session ${id}（${entry.cwd ?? '未知目录'}）`;
+    });
+    if (entries.length > 3)
+        lines.push(`- …另有 ${entries.length - 3} 个`);
+    return (`⚠️ 上次退出时可能留下了未结束的 DSH turn（${entries.length} 个）：\n` +
+        `${lines.join('\n')}\n` +
+        '请到 DSH Web UI 检查并终止；本机的 /stop 只能停止当前由 lark-remote 发起的 run。');
+}
+//# sourceMappingURL=inflight.js.map

package/dist/runner/dsh/runner.d.ts

@@ -6,13 +6,18 @@
  * alignment → synthetic system/init (DSH has no init event) → session/prompt
  * (mode:'queue') → consume `session/follow` + `$events` until turn/end.
  *
- * stop() → session/cancel + abort the mux subscription. killOrphan /
- * registerExitHandlers are no-ops (no local process). DSH approvals are
+ * stop() → session/cancel + abort the mux subscription. killOrphan is a no-op
+ * (no local process); registerExitHandlers cancels the in-flight turn
+ * synchronously on process exit, because the turn lives in the shared host and
+ * would otherwise keep running with no subscriber. DSH approvals are
  * two-channel: durable `approval/asked` / `approval/decided` drive the Feishu
  * card, while the answerable `$events` waterfall supplies eventId/clientId.
- * If `$events` is unavailable, the runner falls back to the Web UI prompt.
+ * `ask_user_question` prompts arrive only as a `user-questions/request`
+ * waterfall (no durable event); they are rendered as a `kind:'question'`
+ * approval on the same card. If `$events` is unavailable, the runner falls
+ * back to the Web UI prompt.
  */
-import type { AgentEvent, AgentSessionReader, AgentStatusInfo, SpawnOptions } from '../types.js';
+import type { AgentEvent, AgentSessionReader, AgentStatusInfo, SpawnOptions, StopOutcome } from '../types.js';
 import type { AgentRunner } from '../types.js';
 import { DshClient, type WebSocketFactory } from './client.js';
 import type { DshDaemon } from './daemon.js';
@@ -45,6 +50,18 @@ export interface DshRunnerOptions {
     webSocketImpl?: WebSocketFactory;
     /** Unary request timeout in ms (default 60s); 0 disables. */
     requestTimeoutMs?: number;
+    /**
+     * 退出路径上取消在途 turn 的传输实现（测试注入）。
+     * 默认走同步 curl（`cancelSessionSync`）：`process.on('exit')` 里不能 await。
+     */
+    cancelOnExit?: (info: {
+        baseUrl: string;
+        sessionId: string;
+    }) => void;
+    /**
+     * 在途 prompt 的持久化记录文件（启动对账用）。省略 = 不记录（测试、临时实例）。
+     */
+    inflightPath?: string;
 }
 export declare class DshRunner implements AgentRunner {
     readonly kind: "dsh";
@@ -68,6 +85,19 @@ export declare class DshRunner implements AgentRunner {
     private activeAbort;
     private activeSessionId;
     private running;
+    /** This run's prompt identity (`source.rpcId`); null outside a submitted prompt. */
+    private activePromptRequestId;
+    /** Whether the current prompt request was accepted by the host. */
+    private promptAdmitted;
+    /**
+     * Releases the next run's prompt only after this stop's withdraw/cancel has
+     * been applied. Aborting the local mux lets the queue advance immediately;
+     * without the gate the successor's prompt can reach the host before the
+     * cancel, and a session-scoped cancel would then hit the *new* turn.
+     */
+    private pendingStopGate;
+    private pendingStopSessionId;
+    private readonly inflight;
     private readonly daemon;
     /**
      * 已对齐模型的 session 集合：同一 session 二次 run 不再重发 selectModel
@@ -80,10 +110,19 @@ export declare class DshRunner implements AgentRunner {
     private readonly permissionAlignedSessions;
     /** `$events` approval waterfall state for the current run. */
     private readonly approvalTracker;
+    /**
+     * eventId → 待回答的 DSH `ask_user_question` waterfall。
+     *
+     * 提问没有 durable 审计事件，eventId 本身就是卡片 requestId；这里保存应答
+     * 所需的 clientId 与题面（DSH 回编按题目 id）。每轮 run 清空。
+     */
+    private readonly pendingQuestions;
     /** callId → tool call, used to render the command in the approval card. */
     private readonly toolCalls;
     /** False after `$events` is unavailable; approval/asked then falls back to text. */
     private approvalChannelAvailable;
+    /** 退出路径的取消实现（默认同步 curl，见 `cancelSessionSync`）。 */
+    private readonly cancelOnExit;
     constructor(opts: DshRunnerOptions);
     get isRunning(): boolean;
     getStatusInfo(): AgentStatusInfo;
@@ -102,6 +141,16 @@ export declare class DshRunner implements AgentRunner {
      * stream keeps either transport from starving the other.
      */
     private runTurn;
+    /**
+     * 收尾时仍在跑的后台任务。
+     *
+     * 只保留非终态（running/stopping）：已完成的任务由 agent 自己的 output 呈
+     * 现，卡片列出来只会误导"还没跑完"。`job/list` 拿不到时返回空数组——没有
+     * 任务列表不等于有任务在跑。
+     */
+    private collectBackgroundJobs;
+    /** Kill one background job of this runner's session (card button path). */
+    killJob(sessionId: string, jobId: string): Promise<boolean>;
     /** Apply the configured permission preset once per session, before prompt. */
     private alignPermissionPreset;
     /** Hot-update the configured preset; the next run aligns it. */
@@ -109,11 +158,25 @@ export declare class DshRunner implements AgentRunner {
         permissionPreset?: string;
     }): Promise<void>;
     /**
-     * Answer one DSH approval. `accept` / `decline` are the only user decisions
-     * exposed by the DSH Web UI; `cancel` stops the turn through session/cancel.
+     * Answer one DSH approval or `ask_user_question` prompt.
+     *
+     * Approvals: `accept` / `decline` are the only user decisions exposed by the
+     * DSH Web UI; `cancel` stops the turn through session/cancel.
+     *
+     * Questions: `answer` / `decline`（跳过回答）resolve the `user-questions/request`
+     * waterfall with an answer batch; `cancel`（飞书卡超时）只把这一路交回
+     * `next`，让 DSH Web UI 仍可回答，不取消 turn。
      */
     respondApproval(requestId: number | string, response: unknown): Promise<void>;
+    /** Resolve one pending `ask_user_question` waterfall from a card action. */
+    private respondQuestion;
     private buildApprovalRequested;
+    /**
+     * Render one `user-questions/request` waterfall as a `kind:'question'`
+     * approval area. The card renderer is agent-agnostic: it draws options,
+     * the Other input, multi-select submit and skip from this view alone.
+     */
+    private buildQuestionRequested;
     private approvalResolved;
     private approvalFallbackText;
     /**
@@ -136,10 +199,57 @@ export declare class DshRunner implements AgentRunner {
     private awaitOrAbort;
     /** Send session/cancel with a short bound; never throws (cleanup path). */
     private cancelSessionQuietly;
+    /**
+     * Stop this run's work in the shared host.
+     *
+     * Two distinct things can be running, and DSH needs a different call for each:
+     *
+     * 1. A prompt that was accepted but not claimed yet still sits in the host
+     *    inbox. `session/cancel` would NOT drop it (`keepInbox`), so the turn would
+     *    start later with no subscriber — an orphan. Withdraw it by `rpcId` via
+     *    `session/updateQueue` instead, and leave the (foreign) active turn alone.
+     * 2. An already-claimed turn (or a compact) can only be stopped with
+     *    `session/cancel`. Since that request is session-scoped and only an
+     *    acknowledgement, verify the session went idle before reporting success.
+     *
+     * The gate is held until the host-side action has landed. For a cancel that
+     * includes the verification (and possible retry), because a retry cancel is
+     * session-scoped and would otherwise hit the successor's new turn.
+     */
     stop(_opts?: {
         immediate?: boolean;
-    }): Promise<void>;
+    }): Promise<StopOutcome>;
+    /** Wait for a concurrent stop to reach the host before submitting a new prompt. */
+    private awaitStopGate;
+    private performStop;
+    /**
+     * Locate this run's unclaimed prompt.
+     *
+     * An already-admitted prompt is visible immediately. A request still in
+     * flight can be admitted after stop aborted it, so poll the inbox briefly —
+     * that is the only client-side protection against a late orphan turn.
+     */
+    private findPendingPromptWithin;
+    private removePendingPrompt;
+    /** One cancel attempt, then one retry (the request is idempotent when idle). */
+    private cancelWithRetry;
+    private cancelOnce;
+    /** Poll the host until the session reports idle, or the budget runs out. */
+    private waitForClosed;
+    /** Sleep, but never past the stop deadline. Returns false when out of budget. */
+    private sleepWithin;
+    private stopProbeTimeout;
     killOrphan(): void;
+    /**
+     * 退出前取消在途 turn。
+     *
+     * turn 跑在常驻共享的 `dsh web` host 里，不在本进程的子进程树上；所以
+     * "杀自己的子进程"这套退出清理对它无效，桥接一退出，turn 继续无人接收地跑
+     * （2026-10-19 实测：一个孤儿 turn 在桥接死后又跑了 2h21m / 345 个 step）。
+     * 这里复用进程级退出分发器，用同步 curl 发一次 `session/cancel`。
+     */
     registerExitHandlers(): void;
     unregisterExitHandlers(): void;
+    /** Exit dispatcher hook: cancel the in-flight turn, bounded and never throwing. */
+    cleanupOnExit(): void;
 }