lark-remote 0.5.6 → 0.5.7

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

@@ -6,8 +6,10 @@
  * 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.
  * `ask_user_question` prompts arrive only as a `user-questions/request`
@@ -15,7 +17,7 @@
  * 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';
@@ -48,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";
@@ -71,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
@@ -94,6 +121,8 @@ export declare class DshRunner implements AgentRunner {
     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;
@@ -112,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. */
@@ -160,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;
 }