@qoder-ai/qoder-agent-sdk 1.0.56 → 1.0.58

package/README.md

@@ -23,48 +23,38 @@ installed if your application uses SDK tools or MCP integration.
 
 ## Runtime Behavior
 
-The npm package uses `WorkerTransport.default` for `query()` by default. During
-`npm install`, its postinstall script downloads the Worker runtime selected by
-the package's pinned CLI version into `dist/_worker`. It does not download the
-process CLI unless `QODER_INSTALL_BUNDLED_CLI=1` is set.
-
-You can still select a transport explicitly on the same `query()` entry:
-
-```ts
-import {
-  qodercliAuth,
-  query,
-  WorkerTransport,
-} from "@qoder-ai/qoder-agent-sdk";
-
-const q = query({
-  prompt: "Summarize this repository.",
-  options: {
-    auth: qodercliAuth(),
-    transport: WorkerTransport.default,
-  },
-});
-```
-
-The worker transport uses the runtime installed at
-`dist/_worker/qoder-worker-runtime.obf.mjs`. To use another Worker runtime,
-pass its path explicitly with
-`new WorkerTransport({ pathToQoderWorkerRuntime })`. Environment variables do
-not override the Worker runtime entry.
-
-The package includes a `dist/runtime-manifest.json` that records the default
-runtime and the URL template for qodercli Worker runtime artifacts. At
-installation time, the SDK resolves exactly one artifact for its own brand,
-the current operating system, and the current architecture. It does not fall
-back to the universal artifact. The SDK package itself does not need to host a
-copy of the archive. The presence of `dist/_worker` is used as an integrity
-check after installation, not as the mode selector.
-
-The installed Worker runtime is self-contained. Platform packages include the
-matching native keychain, PTY, image-processing, and ripgrep assets. Linux
-packages retain both glibc and musl image-processing bindings. OpenHarmony does
-not have an install-delivered platform artifact and must use an explicitly
-supplied runtime source.
+`query()` always runs through a process-wide qodercli daemon. The first query
+starts that daemon and reuses it for later queries in the same process; pass
+`options.daemon` to bind a query to a daemon you started yourself with
+`startDaemon()`. The daemon owns the CLI process boundary, so the SDK does not
+spawn a separate CLI per query. Call `shutdownDaemon()` before your host
+process exits to stop the shared daemon.
+
+During `npm install`, the postinstall script downloads the CLI binary selected
+by the package's pinned CLI version into `dist/_bundled`; worker packages also
+deliver the worker runtime into `dist/_worker`.
+
+The daemon launches qodercli either as a native process carrier or as a Node
+worker runtime. `startDaemon()` / `initDaemon()` accept
+`launchMode: 'process' | 'worker'`; without it, the first query's
+`options.transport` (`ProcessTransport` or `WorkerTransport`) selects the
+carrier, otherwise the package's `DEFAULT_RUNTIME_TRANSPORT` applies. Worker
+mode launches the bundled `dist/_worker` runtime, or the runtime passed through
+`pathToQoderWorkerRuntime`; when no worker runtime is available the daemon
+falls back to the process carrier. A later query whose launch mode differs from
+the ready daemon is rejected with `DaemonConfigurationConflictError`.
+
+The process carrier uses `pathToQoderCLIExecutable` when provided, then
+`QODERCLI_PATH`, then the bundled CLI, then a locally installed `qodercli`.
+JavaScript CLI entries run through `executable` (or the SDK host's Node binary).
+
+`Options.transport`, `ProcessTransport`, and `WorkerTransport` remain
+available: selecting either transport no longer spawns a per-query process or
+worker, it selects the shared daemon's carrier. Query options that configure
+the CLI process, such as `pathToQoderCLIExecutable`, `executable`,
+`executableArgs`, `env`, `proxy`, `vpcEndpoint`, and `auth`, configure the
+shared daemon instead. Because the daemon is shared, every query in one process
+must pass compatible daemon-level options.
 
 If your environment blocks install scripts or network downloads, skip postinstall
 runtime downloads:
@@ -73,27 +63,13 @@ runtime downloads:
 QODER_SKIP_DOWNLOAD=1 npm install @qoder-ai/qoder-agent-sdk zod
 ```
 
-`QODER_SKIP_DOWNLOAD` only affects install-time downloads. It does not change the
-package's default runtime. Then point the process transport at an existing
-`qodercli`:
+`QODER_SKIP_DOWNLOAD` only affects install-time downloads. Point the daemon at
+an existing `qodercli` with:
 
 ```bash
 export QODERCLI_PATH=/absolute/path/to/qodercli
 ```
 
-To use an existing Worker runtime, pass its absolute path through
-`new WorkerTransport({ pathToQoderWorkerRuntime })`.
-
-`query()` is the only query entry point and defaults to Worker. Pass
-`transport: ProcessTransport.default`,
-`transport: WorkerTransport.default`, or a custom transport provider when a
-single call needs to override the package default.
-
-`pathToQoderCLIExecutable` accepts either local runtime form. Native binaries
-and ordinary CLI `.js`/`.mjs` entries use the process transport; recognized
-`qoder-worker-runtime*.mjs` entries use the Worker transport. An explicit
-`transport` provider always takes precedence over automatic path selection.
-
 ## Authentication
 
 Every SDK query needs an explicit authentication option.
@@ -452,8 +428,8 @@ non-fatal `system/mirror_error` messages. Each append batch is submitted once:
 the SDK does not retry a mutation whose commit outcome may be unknown.
 `loadTimeoutMs` defaults to 60,000 ms.
 Session storage cannot be combined with `persistSession: false`, file
-checkpointing, custom transports, or the Cloud Agent runtime. Session storage
-supports the built-in Process and Worker transports. Use
+checkpointing, or the Cloud Agent runtime. It works on daemon-backed queries.
+Use
 `importSessionToStore(sessionId, store, options)` to copy an existing local main
 transcript, child-agent transcripts, and metadata into a store.
 

package/dist/core/default-runtime.d.ts

@@ -2,7 +2,9 @@ export type DefaultRuntimeTransport = 'process' | 'worker';
 /**
  * The default transport baked into the packaged SDK bundle.
  *
- * Development / plain `tsc` builds default to `process`. Release bundles replace
- * `__QODER_DEFAULT_RUNTIME_TRANSPORT__` through esbuild `define`.
+ * Development / plain `tsc` builds default to `process`. Legacy bundles may
+ * replace `__QODER_DEFAULT_RUNTIME_TRANSPORT__` through esbuild `define`; the
+ * value is retained for integrations that read it, while every Query now
+ * executes through the process-wide daemon.
  */
 export declare const DEFAULT_RUNTIME_TRANSPORT: DefaultRuntimeTransport;

package/dist/core/errors.d.ts

@@ -2,6 +2,18 @@
  * Custom error types for the Qoder Agent SDK.
  */
 import type { SDKResultMessage } from '../protocol/messages.js';
+export declare class QoderCliProcessError extends Error {
+    readonly code: "QODER_CLI_PROCESS_ERROR";
+    readonly exitCode?: number | null;
+    readonly signal?: NodeJS.Signals | null;
+    readonly stderr?: string;
+    constructor(message: string, options?: {
+        exitCode?: number | null;
+        signal?: NodeJS.Signals | null;
+        stderr?: string;
+        cause?: unknown;
+    });
+}
 /** JSONL 帧超过传输预算；输入与输出使用不同错误码，避免把执行端输出问题归因于用户输入。 */
 export declare class FrameTooLargeError extends Error {
     readonly direction: 'input' | 'output';

package/dist/core/process-transport.d.ts

@@ -1,40 +1,22 @@
 /**
- * ProcessTransport — Spawns qodercli as a child process and
- * manages stdin/stdout communication using JSONL (JSON Lines) format.
+ * ProcessTransport compatibility surface.
  *
- * This is the primary transport for Node.js environments. It:
- * 1. Builds CLI arguments from the provided options
- * 2. Spawns the CLI process (or delegates to a custom spawner)
- * 3. Reads stdout line-by-line, parsing each as JSON
- * 4. Writes to stdin as JSON + newline
- * 5. Handles graceful shutdown: close stdin → wait → SIGTERM → wait → SIGKILL
+ * The child-process implementation is gone: selecting this transport now runs
+ * the Query through the process-wide daemon. The exported types and members
+ * stay so existing integrations keep compiling and keep the same behavior.
  */
 import type { QueryTransportProvider, Transport } from './transport.js';
-import type { StdoutMessage } from '../types/control.js';
 import type { SdkPluginConfig, ToolConfig } from '../types/common.js';
 import type { PermissionMode } from '../types/permissions.js';
 import type { McpServerConfigForProcessTransport, McpServerToolPolicy } from '../types/mcp.js';
 import type { InternalAuthOptions } from '../types/auth.js';
 import type { SecurityScanOptions, SpawnedProcess, SpawnOptions, SettingSource } from '../types/options.js';
 import type { DiagnosticsSink } from './sdk-diagnostics.js';
-export declare class QoderCliProcessError extends Error {
-    readonly code: "QODER_CLI_PROCESS_ERROR";
-    readonly exitCode?: number | null;
-    readonly signal?: NodeJS.Signals | null;
-    readonly stderr?: string;
-    constructor(message: string, options?: {
-        exitCode?: number | null;
-        signal?: NodeJS.Signals | null;
-        stderr?: string;
-        cause?: unknown;
-    });
-}
-/**
- * Options for configuring the ProcessTransport.
- *
- * These map 1:1 to the CLI flags and environment variables that the
- * qodercli understands.
- */
+export { QoderCliProcessError } from './errors.js';
+type ToolsOption = string[] | {
+    type: 'preset';
+    preset: 'qodercli';
+};
 export interface ProcessTransportOptions {
     /** Path to the Qoder CLI executable (binary or script) */
     pathToQoderCLIExecutable?: string;
@@ -120,95 +102,7 @@ export interface ProcessTransportOptions {
      */
     onAuthExpired?: () => void;
 }
-type ToolsOption = string[] | {
-    type: 'preset';
-    preset: 'qodercli';
-};
-export declare class ProcessTransport implements Transport, QueryTransportProvider<ProcessTransportOptions> {
+export declare class ProcessTransport implements QueryTransportProvider<ProcessTransportOptions> {
     static readonly default: ProcessTransport;
-    private process;
-    private customHandle;
-    private options;
-    private ready;
-    private closed;
-    private shutdownStarted;
-    private initializePromise;
-    private authExpiredFired;
-    private pendingInput;
-    private diagnostics?;
-    private processExitError;
-    private processStopped;
-    private closeTimer;
-    private killTimer;
-    private stderrTail;
-    private launchOptionsBuilder;
-    constructor(options?: ProcessTransportOptions);
     create(options: ProcessTransportOptions): Transport;
-    /**
-     * Build CLI arguments, resolve the executable, spawn the process,
-     * and mark the transport as ready.
-     */
-    initialize(): Promise<void>;
-    private _doInitialize;
-    /** Write a JSON line to stdin. */
-    write(data: string): void;
-    private writeReadyLine;
-    private flushPendingInput;
-    /** Whether the transport is ready to send/receive. */
-    isReady(): boolean;
-    /** Signal that no more input will be sent (close stdin). */
-    endInput(): void;
-    private endReadyInput;
-    /**
-     * Async generator that yields parsed JSON messages from stdout.
-     *
-     * Uses readline to split stdout into lines. Each non-empty line is
-     * expected to be a complete JSON object (JSONL format).
-     *
-     * The generator completes when:
-     * - The readline interface closes (process exited or stdout ended)
-     * - The transport is closed
-     */
-    readMessages(): AsyncGenerator<StdoutMessage, void, unknown>;
-    /**
-     * Close the transport with graceful shutdown:
-     *
-     * 1. Close stdin (signal to CLI that no more input is coming)
-     * 2. Wait CLOSE_GRACE_MS for the process to exit on its own
-     * 3. Send SIGTERM
-     * 4. Wait KILL_GRACE_MS for the process to exit
-     * 5. Send SIGKILL if still running
-     */
-    close(): void;
-    /** 回收进程资源，不改变调用方主动关闭状态；异常仍由读取循环传播。 */
-    private shutdownProcess;
-    private hasProcessStopped;
-    private finishProcess;
-    private observeProcess;
-    /**
-     * Get the underlying process PID, if available.
-     */
-    get pid(): number | undefined;
-    /**
-     * Get the stdout stream from the process or custom handle.
-     */
-    private getStdout;
-    private appendStderr;
-    private createSpawnError;
-    private createProcessExitError;
-    private getStderrTail;
-    private waitForProcessExit;
-    /**
-     * Resolve the executable command and arguments.
-     *
-     * If the CLI path is a script file (.js/.mjs/.ts/.tsx/.jsx), we need
-     * an interpreter (node/bun/deno). Otherwise the path is a native binary
-     * and is used directly as the command.
-     */
-    private resolveExecutable;
-    /** 清理 runtime 已消费或不再可能消费的启动制品。 */
-    private cleanupLaunchArtifacts;
-    /** Fire `onAuthExpired` at most once per session. */
-    private fireAuthExpired;
-}
-export {};
+}

package/dist/core/query-transport.d.ts

@@ -1,6 +1,16 @@
-import { type ProcessTransportOptions } from './process-transport.js';
+import type { ProcessTransportOptions } from './process-transport.js';
+import type { RuntimeLaunchOptions } from './runtime-launch-options.js';
 import type { QueryTransportProvider, Transport } from './transport.js';
+/** SDK-internal options for the daemon session transport provider. */
+export interface DaemonQueryTransportOptions extends RuntimeLaunchOptions {
+    /** SDK-internal: config root created by SessionStore materialization. */
+    materializedSessionConfigDir?: string;
+}
+/**
+ * Options a custom transport provider receives. Kept as the historical
+ * `ProcessTransportOptions` shape so existing providers keep compiling.
+ */
 export type QueryTransportCreateOptions = ProcessTransportOptions;
 export type QueryTransportProviderOption = QueryTransportProvider<QueryTransportCreateOptions>;
 export declare function isQueryTransportProvider(value: unknown): value is QueryTransportProviderOption;
-export declare function createQueryTransport(provider: QueryTransportProviderOption, options: QueryTransportCreateOptions): Transport;
+export declare function createQueryTransport<T extends object>(provider: QueryTransportProvider<T>, options: T): Transport;

package/dist/core/worker-transport.d.ts

@@ -1,16 +1,14 @@
 /**
- * WorkerTransport — runs qoder-worker-runtime inside a Node worker thread.
+ * WorkerTransport compatibility surface.
  *
- * This transport keeps the existing SDK stream-json protocol but replaces the
- * child-process boundary with worker stdin/stdout/stderr streams. It is meant
- * for hosts that already own a Node runtime, including Node SEA hosts, and want
- * to avoid spawning a second qoder SEA process.
+ * The worker-thread implementation is gone: selecting this transport now runs
+ * the Query through the process-wide daemon. The exported classes, helpers and
+ * option types stay so existing integrations keep compiling and running.
  */
 import type { QueryTransportProvider, Transport } from './transport.js';
 import type { ProcessTransportOptions } from './process-transport.js';
-import type { StdoutMessage } from '../types/control.js';
 import type { DiagnosticsSink } from './sdk-diagnostics.js';
-import { type RuntimeLaunchOptions } from './runtime-launch-options.js';
+import type { RuntimeLaunchOptions } from './runtime-launch-options.js';
 import { hasResolvableQoderWorkerRuntime, resolveQoderWorkerRuntimePath } from './worker-runtime-path.js';
 export { hasResolvableQoderWorkerRuntime, resolveQoderWorkerRuntimePath };
 export declare class QoderWorkerRuntimeError extends Error {
@@ -49,52 +47,10 @@ export interface WorkerRuntimeTransportOptions extends RuntimeLaunchOptions, Wor
     onAuthExpired?: () => void;
 }
 export declare class WorkerTransport implements QueryTransportProvider<ProcessTransportOptions> {
-    static readonly default: WorkerTransport;
     private readonly options;
+    static readonly default: WorkerTransport;
     constructor(options?: WorkerTransportOptions);
+    /** query() 用它把 worker 选择映射成 daemon 的宿主形态。 */
+    getPathToQoderWorkerRuntime(): string | undefined;
     create(options: ProcessTransportOptions): Transport;
-}
-export declare class WorkerRuntimeTransport implements Transport {
-    private worker;
-    private options;
-    private ready;
-    private closed;
-    private initializePromise;
-    private authExpiredFired;
-    private pendingInput;
-    private diagnostics?;
-    private workerExitError;
-    private stderrTail;
-    private observedExitCode;
-    private launchOptionsBuilder;
-    private closeTimer;
-    private closePromise;
-    private abortSignal?;
-    private abortListener?;
-    constructor(options?: WorkerRuntimeTransportOptions);
-    initialize(): Promise<void>;
-    private _doInitialize;
-    write(data: string): void;
-    isReady(): boolean;
-    endInput(): void;
-    readMessages(): AsyncGenerator<StdoutMessage, void, unknown>;
-    close(): Promise<void>;
-    private performClose;
-    get threadId(): number | undefined;
-    private writeReadyLine;
-    private flushPendingInput;
-    private endReadyInput;
-    private destroyWorkerStreams;
-    private appendStderr;
-    private createWorkerError;
-    private createWorkerExitError;
-    private getStderrTail;
-    private recordWorkerExit;
-    private recordSuppressedWorkerExit;
-    private formatStderrTailForDiagnostics;
-    private waitForWorkerExit;
-    private clearCloseTimer;
-    private cleanupAbortListener;
-    private cleanupLaunchArtifacts;
-    private fireAuthExpired;
 }

package/dist/daemon/daemon-connection.d.ts

@@ -7,12 +7,15 @@ import type { DiagnosticsSink } from "../core/sdk-diagnostics.js";
 export declare const SESSION_STORE_FILE_CHECKPOINTING_CAPABILITY = "session_store_file_checkpointing_v1";
 export declare const SESSION_STORE_FORK_BARRIER_CAPABILITY = "session_store_fork_barrier_v1";
 /**
- * 心跳判死阈值：30s 无任何入站帧即判 daemon 失活。与 CLI 仓
- * DAEMON_KEEP_ALIVE_INTERVAL_MS（5s 发送周期，本值 = 6 周期）镜像；能力常量
+ * 心跳判死阈值：120s 无任何入站字节即判 daemon 失活。与 CLI 仓
+ * DAEMON_KEEP_ALIVE_INTERVAL_MS（5s 发送周期，本值 = 24 周期）镜像；能力常量
  * DAEMON_KEEP_ALIVE_CAPABILITY 同为两仓镜像，靠握手协商门控——组合不匹配时
  * 最多不武装看门狗，不会误判。
+ *
+ * 阈值取 120s 而不是 30s：daemon 是共享进程，AI 代码统计等可选后台工作可能在
+ * 主线程上产生数十秒的计算停顿；30s 会把「忙」误判成「死」，连带终止全部会话。
  */
-export declare const DAEMON_HEARTBEAT_TIMEOUT_MS = 30000;
+export declare const DAEMON_HEARTBEAT_TIMEOUT_MS = 120000;
 export declare const DAEMON_KEEP_ALIVE_CAPABILITY = "daemon_keep_alive_v1";
 /**
  * daemon 会话 close 改成「关信道即回包、后台排干 teardown」的能力位（CLI 仓镜像）。
@@ -117,7 +120,12 @@ export interface DaemonSessionIdClaim {
 export declare class DaemonHeartbeatTimeoutError extends Error {
     readonly code = "DAEMON_HEARTBEAT_TIMEOUT";
     readonly elapsedMs: number;
-    constructor(elapsedMs: number);
+    /**
+     * 判死时是否正处在一条未收完的帧中间：区分「daemon 完全静默」与「大帧传到一半
+     * 停住」。两者都是连接级失败；该字段只用于现场归因，不改变判定与传播路径。
+     */
+    readonly partialFrame: boolean;
+    constructor(elapsedMs: number, partialFrame?: boolean);
 }
 export declare class DaemonConnection {
     private readonly input;
@@ -162,11 +170,20 @@ export declare class DaemonConnection {
     private readonly describeUnexpectedClose;
     private readonly diagnostics;
     /**
-     * 心跳看门狗：最近一次入站帧的单调钟时刻（任意入站帧都刷新——有正常会话流量
-     * 时天然免检，keep_alive 只是空闲期保底节拍）。单调钟使机器睡眠/唤醒后差值仍小，
-     * 不误杀。看门狗定时器与阈值见 armHeartbeatWatchdog。
+     * 心跳看门狗：最近一次**入站字节**的单调钟时刻（每个 chunk 都刷新——有正常会话
+     * 流量时天然免检，keep_alive 只是空闲期保底节拍）。
+     *
+     * 不能等整行收完再刷新：一条大帧（单个 tool 结果可达数 MiB）在慢速管道上可能连续
+     * 传输超过阈值，期间字节一直在到达、事件循环也正常，只是换行符还没出现。以行为
+     * 单位会把它误判成「daemon 失活」，进而 fail() 整条连接、连带杀掉全部会话。
+     * 单调钟使机器睡眠/唤醒后差值仍小，不误杀。看门狗定时器与阈值见 armHeartbeatWatchdog。
      */
     private lastInboundAt;
+    /**
+     * 是否正处在一条尚未收完的 NDJSON 帧中间。只用于判死时的诊断：区分「daemon 完全
+     * 静默」与「大帧传到一半停住」，不参与是否判死的判定（后者只看字节进展）。
+     */
+    private inboundFrameInProgress;
     private heartbeatWatchdog;
     private readonly heartbeatTimeoutMs;
     constructor(options: DaemonConnectionOptions);
@@ -263,6 +280,7 @@ export declare class DaemonConnection {
     private readOutput;
     private acceptFrame;
     private rememberTimedOutRequestId;
+    private abandonSessionFromLateResponse;
     private routeSessionMessage;
     private acceptControlResponse;
     private hasPendingSessionRequest;

package/dist/daemon/global-daemon.d.ts

@@ -1,4 +1,6 @@
 import type { InternalAuthOptions } from '../types/auth.js';
+import type { QueryTransportProvider } from '../core/transport.js';
+import type { DaemonQueryTransportOptions } from '../core/query-transport.js';
 import { type Daemon } from './start-daemon.js';
 export interface InitDaemonOptions {
     auth: InternalAuthOptions;
@@ -13,6 +15,10 @@ export interface InitDaemonOptions {
     /** 语义同 `StartDaemonOptions.vpcEndpoint`。 */
     vpcEndpoint?: string;
     env?: Record<string, string | undefined>;
+    /** 宿主形态：process=spawn CLI 二进制；worker=Node 跑 worker runtime。缺省 process。 */
+    launchMode?: 'process' | 'worker';
+    /** worker 形态下覆盖 worker runtime 产物路径。 */
+    pathToQoderWorkerRuntime?: string;
     /** 语义同 `StartDaemonOptions.stderr`：daemon 子进程 stderr 的实时回调。 */
     stderr?: (data: string) => void;
     /** 语义同 `StartDaemonOptions.debug`。 */
@@ -20,16 +26,24 @@ export interface InitDaemonOptions {
     /** 语义同 `StartDaemonOptions.debugFile`。 */
     debugFile?: string;
 }
-export type DaemonFallbackReason = 'protocol_version_mismatch' | 'daemon_unavailable';
-export type DaemonInitResult = {
-    mode: 'daemon';
+export interface GlobalDaemonHandle {
+    /**
+     * A daemon-shaped handle that resolves every call against the initialization
+     * started by `acquireGlobalDaemon`. It is usable before the handshake
+     * completes; asynchronous members wait for readiness instead of failing.
+     */
     daemon: Daemon;
-} | {
-    mode: 'direct';
-    reason: DaemonFallbackReason;
-};
+    transportProvider: QueryTransportProvider<DaemonQueryTransportOptions>;
+}
 export declare class DaemonConfigurationConflictError extends Error {
     constructor();
 }
-export declare function initDaemon(options: InitDaemonOptions): Promise<DaemonInitResult>;
+export declare function initDaemon(options: InitDaemonOptions): Promise<Daemon>;
+/**
+ * Start a query handle backed by the process-wide daemon. The daemon starts
+ * immediately, and each Query's session transport waits for that same
+ * initialization; a failure rejects the Query instead of falling back to a
+ * direct CLI transport.
+ */
+export declare function acquireGlobalDaemon(options: InitDaemonOptions): GlobalDaemonHandle;
 export declare function shutdownDaemon(): Promise<void>;

package/dist/daemon/legacy-transport-compat.d.ts

@@ -0,0 +1,13 @@
+import type { ProcessTransportOptions } from '../core/process-transport.js';
+import type { Transport } from '../core/transport.js';
+/**
+ * Built-in Process/Worker transport selections keep their public surface but
+ * execute through the process-wide daemon. This adapter is used when a caller
+ * invokes the legacy provider's `create()` directly; `query()` routes the same
+ * selections without reaching the provider.
+ */
+export interface LegacyDaemonLaunch {
+    readonly launchMode: 'process' | 'worker';
+    readonly pathToQoderWorkerRuntime?: string;
+}
+export declare function createLegacyDaemonTransport(options: ProcessTransportOptions, launch: LegacyDaemonLaunch): Transport;

package/dist/daemon/start-daemon.d.ts

@@ -1,6 +1,6 @@
 import type { InternalAuthOptions } from '../types/auth.js';
-import type { ProcessTransportOptions } from '../core/process-transport.js';
 import type { QueryTransportProvider } from '../core/transport.js';
+import type { DaemonQueryTransportOptions } from '../core/query-transport.js';
 import type { DaemonGetModelsParams, DaemonValidateByokModelParams } from './protocol.js';
 import type { BYOKProviderInfo, ByokConfigCheckResult, ByokConfigInfo, ByokConfigReference, CheckByokConfigInput, CreateByokConfigInput, DeleteByokConfigInput, UpdateByokConfigInput } from '../protocol/control.js';
 import type { AccountInfo, ModelInfo, UsageInfo } from '../protocol/common.js';
@@ -39,7 +39,20 @@ export interface StartDaemonOptions {
      * at any later point, whenever something first triggers the landing.
      */
     initializeTimeoutMs?: number;
+    /**
+     * 心跳看门狗阈值（ms）：超过这段时间没有任何入站字节即判 daemon 失活。
+     * 缺省 120s；0 关闭看门狗（逃生口）。只在 CLI 协商出 `daemon_keep_alive_v1` 后生效。
+     * 宿主一般不需要调整；测试与受限环境用它缩短判定窗口。
+     */
+    heartbeatTimeoutMs?: number;
     pathToQoderCLIExecutable?: string;
+    /**
+     * 宿主形态：`process` spawn CLI 二进制；`worker` 用 Node 跑 worker runtime
+     * （老 Windows 无法运行 Bun 二进制时使用）。缺省 `process`。
+     */
+    launchMode?: 'process' | 'worker';
+    /** worker 形态下覆盖 worker runtime 产物路径；缺省用随包/已安装产物。 */
+    pathToQoderWorkerRuntime?: string;
     /**
      * 运行 CLI 脚本入口的解释器（node/bun/deno 等），语义与 `query()` 的
      * `Options.executable` 一致：只在解析出的 CLI 入口是脚本文件（.js/.mjs/.ts/...）
@@ -228,7 +241,7 @@ interface InternalDaemonRuntime {
      * when unset, or when the CLI does not support bypass updates).
      */
     noProxy: string | null;
-    readonly transportProvider: QueryTransportProvider<ProcessTransportOptions>;
+    readonly transportProvider: QueryTransportProvider<DaemonQueryTransportOptions>;
 }
 export declare function getDaemonRuntime(daemon: Daemon): InternalDaemonRuntime | undefined;
 export declare function startDaemon(options: StartDaemonOptions): Promise<Daemon>;

package/dist/index.d.ts

@@ -56,14 +56,14 @@ export { startup } from './query/startup.js';
 export type { StartupParams, WarmQuery } from './query/startup.js';
 export { resolveSettings } from './settings/resolve-settings.js';
 export { initDaemon, shutdownDaemon } from './daemon/global-daemon.js';
-export type { DaemonFallbackReason, DaemonInitResult, InitDaemonOptions, } from './daemon/global-daemon.js';
+export type { InitDaemonOptions } from './daemon/global-daemon.js';
 export { startDaemon } from './daemon/start-daemon.js';
+export { DEFAULT_RUNTIME_TRANSPORT } from './core/default-runtime.js';
+export { ProcessTransport, QoderCliProcessError } from './core/process-transport.js';
+export { hasResolvableQoderWorkerRuntime, QoderWorkerRuntimeError, WorkerTransport, resolveQoderWorkerRuntimePath, } from './core/worker-transport.js';
 export type { Daemon, DaemonState, DaemonSessionInfo, SessionRuntimeState, StartDaemonOptions, } from './daemon/start-daemon.js';
 export type { DaemonGetModelsParams, DaemonValidateByokModelParams, DaemonValidatePluginsParams, DaemonSetProxyParams, } from './daemon/protocol.js';
 export { DAEMON_PROXY_BYPASS_CAPABILITY, DAEMON_PROXY_CAPABILITY, DAEMON_VALIDATE_PLUGINS_CAPABILITY, } from './daemon/protocol.js';
-export { DEFAULT_RUNTIME_TRANSPORT, } from './core/default-runtime.js';
-export { ProcessTransport, QoderCliProcessError, } from './core/process-transport.js';
-export { hasResolvableQoderWorkerRuntime, QoderWorkerRuntimeError, WorkerTransport, resolveQoderWorkerRuntimePath, } from './core/worker-transport.js';
 export { DEFAULT_ACCESS_TOKEN_ENV_VAR, DEFAULT_SERVICE_ACCOUNT_ENV_VAR, accessToken, accessTokenFromEnv, jobToken, qodercliAuth, serviceAccount, serviceAccountFromEnv, } from './auth.js';
 export { createSdkMcpServer, tool } from './mcp/sdk-mcp-server.js';
 export type { AnyZodRawShape, InferShape, SdkMcpToolDefinition, ToolExtras, CreateSdkMcpServerOptions, } from './mcp/sdk-mcp-server.js';
@@ -96,11 +96,11 @@ export type { AccessTokenInput, AuthOptions, FetchServiceAccountToken, ServiceAc
  */
 export type { FetchJobToken, JobTokenAuthOptions, JobTokenRequest, JobTokenResult, } from './types/auth.js';
 export type { Base64ImageSource, UrlImageSource, URLImageSource, ImageSource, ImageContentBlock, ImageBlockParam, ContentBlock, MessageParam, AccountInfo, UsageAddOnQuotaBucket, UsageInfo, UsageOrgResourcePackage, UsageQuotaBucket, SessionCreditsUsage, ApiKeySource, ExitReason, FastModeState, ConfigScope, SettingSource, SDKAssistantMessageError, SDKStatus, EffortLevel, ThinkingAdaptive, ThinkingEnabled, ThinkingDisabled, ThinkingConfig, ModelInfo, ModelSource, ServerModelJson, ServerModelJsonValue, ModelStrategy, ModelPromotion, LocalizedModelText, ModelContextConfig, ModelContextWindowEntry, ModelEffortEntry, ModelThinkingConfig, ModelThinkingDisabled, ModelThinkingEnabled, ModelUsage, NonNullableUsage, SlashCommand, ToolConfig, SdkPluginConfig, } from './types/common.js';
-export type { SDKMessage, SDKAssistantMessage, SDKToolNonExecutionKind, SDKToolResultMeta, SDKMessageOrigin, SDKSelectedSkill, SDKArtifactInfo, SDKArtifactUpdateMessage, SDKAvailableModelsUpdateMessage, SDKCommandsChangedMessage, SDKUserMessage, SDKUserMessageReplay, SDKResultMessage, SDKResultSuccess, SDKResultError, SDKSystemMessage, SDKSystemInitMessage, SDKSystemMessageSubtype, SDKSystemMessageBySubtype, SDKPartialAssistantMessage, SDKCompactBoundaryMessage, SDKStatusMessage, SDKAPIRetryMessage, SDKModelQueueStatusMessage, SDKControlRequestProgressMessage, SDKCommandLifecycleMessage, SDKToolProgressMessage, SDKHookStartedMessage, SDKHookProgressMessage, SDKHookResponseMessage, SDKPermissionDeniedMessage, SDKMirrorErrorMessage, SDKTaskNotificationMessage, SDKTaskStartedMessage, SDKTaskProgressMessage, SDKTaskUpdatedMessage, SDKBackgroundTasksChangedMessage, SDKSessionStateChangedMessage, SDKPlanModeChangedMessage, SDKSessionTitleChangedMessage, SDKFilesPersistedEvent, SDKElicitationCompleteMessage, SDKPromptSuggestionMessage, SDKCloudAgentEventMessage, SDKMemoryGenerationMessage, SDKMemoryConsumptionMessage, SDKSkillEvolutionMessage, SDKAgentsMdSizeWarningMessage, SDKPermissionDenial, } from './types/messages.js';
+export type { SDKMessage, SDKAssistantMessage, SDKToolNonExecutionKind, SDKToolResultMeta, SDKMessageOrigin, SDKSelectedSkill, SDKArtifactInfo, SDKArtifactUpdateMessage, SDKAvailableModelsUpdateMessage, SDKCommandsChangedMessage, SDKUserMessage, SDKUserMessageReplay, SDKResultMessage, SDKResultSuccess, SDKResultError, SDKSystemMessage, SDKSystemInitMessage, SDKSystemMessageSubtype, SDKSystemMessageBySubtype, SDKPartialAssistantMessage, SDKCompactBoundaryMessage, SDKStatusMessage, SDKAPIRetryMessage, SDKModelQueueStatusMessage, SDKControlRequestProgressMessage, SDKCommandLifecycleMessage, SDKToolProgressMessage, SDKHookDiagnosticsMessage, SDKHookStartedMessage, SDKHookProgressMessage, SDKHookResponseMessage, SDKPermissionDeniedMessage, SDKMirrorErrorMessage, SDKTaskNotificationMessage, SDKTaskStartedMessage, SDKTaskProgressMessage, SDKTaskUpdatedMessage, SDKBackgroundTasksChangedMessage, SDKSessionStateChangedMessage, SDKPlanModeChangedMessage, SDKSessionTitleChangedMessage, SDKFilesPersistedEvent, SDKElicitationCompleteMessage, SDKPromptSuggestionMessage, SDKCloudAgentEventMessage, SDKMemoryGenerationMessage, SDKMemoryConsumptionMessage, SDKSkillEvolutionMessage, SDKAgentsMdSizeWarningMessage, SDKPermissionDenial, } from './types/messages.js';
 export type { DefaultRuntimeTransport, } from './core/default-runtime.js';
-export type { QueryTransportCreateOptions, QueryTransportProviderOption, } from './core/query-transport.js';
 export type { ProcessTransportOptions } from './core/process-transport.js';
 export type { WorkerRuntimeTransportOptions, WorkerTransportOptions, } from './core/worker-transport.js';
+export type { QueryTransportCreateOptions, QueryTransportProviderOption, } from './core/query-transport.js';
 export type { QueryTransportProvider, Transport, } from './core/transport.js';
 export type { Options, QueryTransportOptions, Query, RemoteProjectionEnableOptions, RemoteProjectionCheckpoint, SpawnOptions, SpawnedProcess, ElicitationRequest, ElicitationResult, OnElicitation, PromptRequest, PromptRequestOption, PromptResponse, CanUseTool, SecurityScanOptions, } from './types/options.js';
 export type { ArtifactGroup, SessionArtifactBase, SessionArtifact, ResolveSessionArtifactsResult, ResolveSessionArtifacts, } from './types/artifacts.js';