@qoder-ai/qoder-agent-sdk 1.0.54 → 1.0.55

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

@@ -1,10 +1,25 @@
 import type { Readable, Writable } from "node:stream";
 import { type DaemonCommandResultMap, type DaemonCommandParamsMap, type DaemonControlRequestFrame, type DaemonQueryMethod, type DaemonWireSessionMessage, type JsonObject, type JsonValue, type OpenSessionParams, type RenameSessionResult } from "./protocol.js";
 import type { SdkAuthPayload } from "../types/auth.js";
+import type { PluginValidationReport } from "../types/plugins.js";
 import { DaemonSessionTransport, type DaemonSessionTransportOptions } from "./daemon-session-transport.js";
 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 周期）镜像；能力常量
+ * DAEMON_KEEP_ALIVE_CAPABILITY 同为两仓镜像，靠握手协商门控——组合不匹配时
+ * 最多不武装看门狗，不会误判。
+ */
+export declare const DAEMON_HEARTBEAT_TIMEOUT_MS = 30000;
+export declare const DAEMON_KEEP_ALIVE_CAPABILITY = "daemon_keep_alive_v1";
+/**
+ * daemon 会话 close 改成「关信道即回包、后台排干 teardown」的能力位（CLI 仓镜像）。
+ * 会话 initialize 回包声明它时，QueryRunner.close 不再隐式等 memory / evolution
+ * flush；旧 CLI 不声明则保持原有等待语义（版本错配保护）。
+ */
+export declare const DAEMON_ASYNC_SESSION_TEARDOWN_CAPABILITY = "daemon_async_session_teardown_v1";
 export interface DaemonConnectionOptions {
     input: Writable;
     output: Readable;
@@ -27,6 +42,11 @@ export interface DaemonConnectionOptions {
      * 只打协议元数据（方法名、id、耗时、字节数），绝不打帧原文、凭据与 prompt 正文。
      */
     diagnostics?: DiagnosticsSink;
+    /**
+     * 心跳看门狗阈值（ms），缺省 DAEMON_HEARTBEAT_TIMEOUT_MS；0 = 关闭（逃生口）。
+     * 仅握手协商出 daemon_keep_alive_v1 时武装；单调钟判定，机器睡眠/唤醒不误杀。
+     */
+    heartbeatTimeoutMs?: number;
 }
 export interface DaemonInitializeOptions {
     /** Advertised in addition to the capability this SDK cannot work without. */
@@ -38,6 +58,11 @@ export interface DaemonInitializeOptions {
      * without it. Carries a plaintext credential — never log it.
      */
     auth?: SdkAuthPayload;
+    /**
+     * Process-wide proxy applied during the handshake (`daemon_proxy_v1`).
+     * An empty string clears a previously configured proxy.
+     */
+    proxy?: string;
 }
 export type DaemonRequestHandler = (request: DaemonControlRequestFrame) => Promise<JsonValue>;
 export declare class DaemonRpcError extends Error {
@@ -62,13 +87,50 @@ export declare class DaemonRequestError extends Error {
         details?: JsonObject;
     });
 }
+/**
+ * A second concurrent Query declared a session id that is already opening or
+ * open on this daemon connection. Thrown synchronously from `query()` so the
+ * caller sees the conflict before any frame is sent.
+ */
+export declare class DaemonSessionAlreadyOpenError extends Error {
+    readonly sessionId: string;
+    readonly state: "opening" | "open";
+    readonly code = "SESSION_ALREADY_OPEN";
+    constructor(sessionId: string, state: "opening" | "open");
+}
+/** `close` 进行中的 id 不会拒绝新 Query；凭据里的 ready 在 close 出清后兑现。 */
+export interface DaemonSessionIdClaim {
+    readonly sessionId: string;
+    readonly ready: Promise<void>;
+}
+/**
+ * 心跳看门狗判死：daemon「活着但静默」（事件循环卡死、管道半开、OOM 挂持）时
+ * 唯一的判定手段。message 以错误码开头——app 侧按约定取 message 前 120 字符做
+ * failureCode，码在开头才可检索。
+ */
+export declare class DaemonHeartbeatTimeoutError extends Error {
+    readonly code = "DAEMON_HEARTBEAT_TIMEOUT";
+    readonly elapsedMs: number;
+    constructor(elapsedMs: number);
+}
 export declare class DaemonConnection {
     private readonly input;
-    private readonly requestHandler;
+    /**
+     * Daemon-level reverse-request handler (the `daemon.auth.*` host-callback bridge).
+     * Mutable: `Daemon.auth(payload)` can rebind it when a later payload switches the
+     * host-callback arm (jobToken / serviceAccount-token-provider), so the daemon's
+     * token fetch for the *new* credentials reaches the right host callback.
+     */
+    private requestHandler;
     private readonly pendingRequests;
     private readonly timedOutRequestIds;
     private readonly activeInboundRequestIds;
     private readonly sessions;
+    /**
+     * 声明 id 的占用表：query() 创建 transport 时同步占位，回包前就能拦住第二个
+     * 同 id Query。close 期间到达的 Query 排队等 close 出清，不误杀顺序重开。
+     */
+    private readonly sessionSlots;
     private readonly closedSessionIds;
     /**
      * 每个 daemon-bound 会话 open 时携带的工作目录（sessionId → cwd）。daemon 已无 cwd
@@ -93,10 +155,46 @@ export declare class DaemonConnection {
     private readonly failureListeners;
     private readonly describeUnexpectedClose;
     private readonly diagnostics;
+    /**
+     * 心跳看门狗：最近一次入站帧的单调钟时刻（任意入站帧都刷新——有正常会话流量
+     * 时天然免检，keep_alive 只是空闲期保底节拍）。单调钟使机器睡眠/唤醒后差值仍小，
+     * 不误杀。看门狗定时器与阈值见 armHeartbeatWatchdog。
+     */
+    private lastInboundAt;
+    private heartbeatWatchdog;
+    private readonly heartbeatTimeoutMs;
     constructor(options: DaemonConnectionOptions);
     initialize(sdkVersion: string, options?: DaemonInitializeOptions): Promise<void>;
     createSessionTransport(options: DaemonSessionTransportOptions): DaemonSessionTransport;
     supportsCapability(capability: string): boolean;
+    /**
+     * Switches the daemon-level (process-wide) proxy, or clears it with
+     * `undefined` / `null` / an empty string. Returns the normalized value.
+     */
+    setProxy(proxy?: string | null): Promise<string | null>;
+    /**
+     * 同步占用一个声明 id。opening/open 直接抛冲突；closing 则排队，ready 在
+     * 前一次 close 出清后兑现。未声明 id（daemon 现 mint）不会撞，调用方不占用。
+     */
+    claimSessionId(sessionId: string): DaemonSessionIdClaim;
+    markSessionOpen(sessionId: string): void;
+    markSessionClosing(sessionId: string): void;
+    /** open 失败/放弃时出清占位；不向等待者交接（close 才有资格交接）。 */
+    releaseSessionClaim(sessionId: string): void;
+    private completeSessionClose;
+    private advanceSessionSlot;
+    /**
+     * Statically validates local plugins inside the daemon. Gated on
+     * `daemon_validate_plugins_v1` so an older CLI rejects here instead of
+     * answering `METHOD_NOT_FOUND`; the caller falls back to the Worker path.
+     */
+    validatePlugins(paths: readonly string[], configDir?: string): Promise<PluginValidationReport[]>;
+    /**
+     * Rebinds the daemon-level reverse-request handler. Used by `Daemon.auth(payload)`
+     * when the new credentials carry a host-callback arm, so the daemon's token fetch
+     * for the overridden credentials is answered by the matching host callback.
+     */
+    setRequestHandler(handler: DaemonRequestHandler | undefined): void;
     onFailure(listener: (error: Error) => void): () => void;
     openSession(params: OpenSessionParams, transport: DaemonSessionTransport): Promise<string>;
     listSessions(cwd?: string): Promise<import("./protocol.js").DaemonSessionInfo[]>;
@@ -113,6 +211,20 @@ export declare class DaemonConnection {
      * fails that one query, not the connection.
      */
     query<Method extends DaemonQueryMethod>(method: Method, params: DaemonCommandParamsMap[Method]): Promise<DaemonCommandResultMap[Method]>;
+    /**
+     * Explicitly triggers the daemon's on-demand credential landing
+     * (`daemon.authenticate`). The handshake only validated the payload (and auth is
+     * optional there), so this is the host-facing way to land credentials up front.
+     *
+     * `payload` omitted → authenticate with the credentials the daemon already holds.
+     * `payload` present → override the held credentials, then authenticate. Idempotent
+     * on the CLI side for the no-payload form.
+     *
+     * Gated on `daemon_queries_v1` (always advertised by a CLI that speaks this
+     * protocol); an old CLI that lacks the method rejects here with a clear protocol
+     * error instead of a bare METHOD_NOT_FOUND frame.
+     */
+    authenticate(payload?: SdkAuthPayload): Promise<DaemonCommandResultMap["authenticate"]>;
     shutdown(timeoutMs?: number): Promise<void>;
     /**
      * EOF 落定前问一次进程侧：对端是不是已经退了、为什么退。
@@ -120,6 +232,14 @@ export declare class DaemonConnection {
      */
     private resolveUnexpectedClose;
     fail(error: unknown, notifyListeners?: boolean): void;
+    /**
+     * 心跳看门狗：每 5s 检查一次距最近入站帧的单调钟差值，超阈值即判 daemon 失活。
+     * 判定后走既有 fail() 全量传播（在途请求 reject、在途会话流 error 终止、后续调用
+     * 立即 reject、failureListeners 通知）——「对外抛错」不需要新机制。
+     * 定时器 unref：看门狗是宿主的判定器，不该替宿主保活进程。
+     */
+    private armHeartbeatWatchdog;
+    private disarmHeartbeatWatchdog;
     private request;
     private readOutput;
     private acceptFrame;

package/dist/daemon/daemon-session-transport.d.ts

@@ -1,12 +1,14 @@
 import type { Transport } from '../core/transport.js';
 import type { StdoutMessage } from '../types/control.js';
 import type { DaemonWireSessionMessage } from './protocol.js';
-import type { DaemonConnection } from './daemon-connection.js';
+import type { DaemonConnection, DaemonSessionIdClaim } from './daemon-connection.js';
 import type { DiagnosticsSink } from '../core/sdk-diagnostics.js';
 export type DaemonSessionTransportOptions = {
     workerArgs: string[];
     cwd?: string;
     configDir?: string;
+    /** query() 创建时按声明 id 占到的位置；close 进行中时先等 ready。 */
+    claim?: DaemonSessionIdClaim;
     cleanup?: () => void;
     /**
      * 由 DaemonConnection.createSessionTransport 注入，调用方不需要传。

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

@@ -2,11 +2,14 @@ import type { InternalAuthOptions } from '../types/auth.js';
 import { type Daemon } from './start-daemon.js';
 export interface InitDaemonOptions {
     auth: InternalAuthOptions;
-    /** Idle Worker timeout in milliseconds. Set to 0 to disable reclamation. */
-    workerIdleTimeoutMs?: number;
-    cwd?: string;
     pathToQoderCLIExecutable?: string;
+    /** 语义同 `StartDaemonOptions.executable`。 */
+    executable?: string;
+    /** 语义同 `StartDaemonOptions.executableArgs`。 */
+    executableArgs?: string[];
     proxy?: string;
+    /** 语义同 `StartDaemonOptions.vpcEndpoint`。 */
+    vpcEndpoint?: string;
     env?: Record<string, string | undefined>;
     /** 语义同 `StartDaemonOptions.stderr`：daemon 子进程 stderr 的实时回调。 */
     stderr?: (data: string) => void;

package/dist/daemon/protocol.d.ts

@@ -5,15 +5,29 @@
  */
 import type { BYOKModelValidationInput, BYOKProviderInfo, ByokConfigCheckResult, ByokConfigInfo, ByokConfigReference, CheckByokConfigInput, CreateByokConfigInput, DeleteByokConfigInput, UpdateByokConfigInput } from "../protocol/control.js";
 import type { AccountInfo, ModelInfo, SessionCreditsUsage, UsageInfo } from "../protocol/common.js";
-import type { PluginDetails } from "../types/plugins.js";
+import type { PluginDetails, PluginValidationReport } from "../types/plugins.js";
 import type { SdkAuthPayload } from "../types/auth.js";
 export declare const DAEMON_PROTOCOL_VERSION: 2;
 /**
  * Reported by the daemon in its initialize result once it accepted an `auth`
- * payload, i.e. when the account-level query plane is usable on this
- * connection. Absent for a daemon that only manages Sessions.
+ * payload, i.e. when the account-level query plane (and the explicit
+ * `daemon.authenticate` trigger) is available on this connection. Acceptance is
+ * shape validation only — the credentials land on demand, so queries before the
+ * first landing may answer `AUTH_REQUIRED`. Absent for a daemon that only
+ * manages Sessions.
  */
 export declare const DAEMON_QUERIES_CAPABILITY = "daemon_queries_v1";
+/**
+ * The daemon can statically validate local plugins in-process
+ * (`daemon.validate_plugins`), so the SDK can skip spawning a Worker for
+ * plugin validation. Absent on older CLIs; callers must fall back.
+ */
+export declare const DAEMON_VALIDATE_PLUGINS_CAPABILITY = "daemon_validate_plugins_v1";
+/**
+ * The daemon can apply a process-wide proxy during the handshake (`initialize`)
+ * and switch it later via `daemon.setproxy`.
+ */
+export declare const DAEMON_PROXY_CAPABILITY = "daemon_proxy_v1";
 export type JsonPrimitive = string | number | boolean | null;
 export type JsonValue = JsonPrimitive | JsonValue[] | {
     [key: string]: JsonValue;
@@ -83,6 +97,11 @@ export type InitializeDaemonParams = {
      * message.
      */
     auth?: SdkAuthPayload;
+    /**
+     * Process-wide proxy applied during the handshake (`daemon_proxy_v1`). An
+     * empty string clears a previously configured proxy.
+     */
+    proxy?: string;
 };
 export type InitializeDaemonResult = {
     daemon_protocol_version: typeof DAEMON_PROTOCOL_VERSION;
@@ -138,6 +157,31 @@ export type DeleteSessionParams = {
     cwd?: string;
 };
 export type ShutdownParams = Record<string, never>;
+/**
+ * Explicit auth trigger (`daemon.authenticate`, surfaced as `Daemon.auth(payload?)`).
+ * The initialize handshake only validates the credential payload (and auth is now
+ * optional there); the CLI lands it on demand — the first auth-needing consumer
+ * (this method, an account-level query, or a session's inference readiness) starts
+ * the login.
+ *
+ * `auth` is optional:
+ * - omitted → authenticate with the credentials the daemon already holds (from
+ *   `startDaemon`); rejected with `AUTH_PAYLOAD_REQUIRED` if it holds none.
+ * - present → **override** the held credentials with this payload, then authenticate
+ *   (supports supplying credentials to a daemon started without auth, and switching
+ *   accounts on an already-authenticated daemon).
+ */
+export type DaemonAuthenticateParams = {
+    auth?: SdkAuthPayload;
+};
+export type DaemonAuthenticateResult = {
+    /**
+     * False is a non-fatal "no credential" outcome (e.g. the read-only borrow of
+     * the local qodercli login found nothing). Rejected credentials arrive as an
+     * error frame instead, never as `authenticated: false`.
+     */
+    authenticated: boolean;
+};
 /**
  * Account-level query plane (`daemon_queries_v1`).
  *
@@ -202,6 +246,24 @@ export type DaemonListPluginsParams = Record<string, never>;
 export type DaemonListPluginsResult = {
     plugins: PluginDetails[];
 };
+/**
+ * Static, session-less plugin validation. `config_dir` is the base directory
+ * for relative paths, mirroring the Worker path's `QODER_CONFIG_DIR` context.
+ */
+export type DaemonValidatePluginsParams = {
+    paths: string[];
+    config_dir?: string;
+};
+export type DaemonValidatePluginsResult = {
+    reports: PluginValidationReport[];
+};
+export type DaemonSetProxyParams = {
+    /** `null` clears the daemon-level proxy. */
+    proxy: string | null;
+};
+export type DaemonSetProxyResult = {
+    proxy: string | null;
+};
 export type DaemonGetUsageInfoParams = Record<string, never>;
 export type DaemonGetUsageInfoResult = {
     usage: UsageInfo | null;
@@ -213,7 +275,7 @@ export type DaemonAccountInfoParams = Record<string, never>;
 export type DaemonAccountInfoResult = {
     account: AccountInfo;
 };
-export type DaemonCommandMethod = "initialize" | "open_session" | "list_sessions" | "rename_session" | "close_session" | "delete_session" | "shutdown" | DaemonQueryMethod;
+export type DaemonCommandMethod = "initialize" | "open_session" | "list_sessions" | "rename_session" | "close_session" | "delete_session" | "shutdown" | "authenticate" | "validate_plugins" | "setproxy" | DaemonQueryMethod;
 export interface DaemonCommandParamsMap {
     initialize: InitializeDaemonParams;
     open_session: OpenSessionParams;
@@ -222,6 +284,7 @@ export interface DaemonCommandParamsMap {
     close_session: CloseSessionParams;
     delete_session: DeleteSessionParams;
     shutdown: ShutdownParams;
+    authenticate: DaemonAuthenticateParams;
     get_models: DaemonGetModelsParams;
     get_byok_config: DaemonGetByokConfigParams;
     validate_byok_model: DaemonValidateByokModelParams;
@@ -231,10 +294,12 @@ export interface DaemonCommandParamsMap {
     delete_byok_config: DaemonDeleteByokConfigParams;
     check_byok_config: DaemonCheckByokConfigParams;
     list_plugins: DaemonListPluginsParams;
+    validate_plugins: DaemonValidatePluginsParams;
+    setproxy: DaemonSetProxyParams;
     get_usage_info: DaemonGetUsageInfoParams;
     account_info: DaemonAccountInfoParams;
 }
-export type DaemonCommandRequest = DaemonControlRequestFrame<"initialize", InitializeDaemonParams> | DaemonControlRequestFrame<"open_session", OpenSessionParams> | DaemonControlRequestFrame<"list_sessions", ListSessionsParams> | DaemonControlRequestFrame<"rename_session", RenameSessionParams> | DaemonControlRequestFrame<"close_session", CloseSessionParams> | DaemonControlRequestFrame<"delete_session", DeleteSessionParams> | DaemonControlRequestFrame<"shutdown", ShutdownParams> | DaemonControlRequestFrame<"get_models", DaemonGetModelsParams> | DaemonControlRequestFrame<"get_byok_config", DaemonGetByokConfigParams> | DaemonControlRequestFrame<"validate_byok_model", DaemonValidateByokModelParams> | DaemonControlRequestFrame<"list_byok_configs", DaemonListByokConfigsParams> | DaemonControlRequestFrame<"create_byok_config", DaemonCreateByokConfigParams> | DaemonControlRequestFrame<"update_byok_config", DaemonUpdateByokConfigParams> | DaemonControlRequestFrame<"delete_byok_config", DaemonDeleteByokConfigParams> | DaemonControlRequestFrame<"check_byok_config", DaemonCheckByokConfigParams> | DaemonControlRequestFrame<"list_plugins", DaemonListPluginsParams> | DaemonControlRequestFrame<"get_usage_info", DaemonGetUsageInfoParams> | DaemonControlRequestFrame<"account_info", DaemonAccountInfoParams>;
+export type DaemonCommandRequest = DaemonControlRequestFrame<"initialize", InitializeDaemonParams> | DaemonControlRequestFrame<"open_session", OpenSessionParams> | DaemonControlRequestFrame<"list_sessions", ListSessionsParams> | DaemonControlRequestFrame<"rename_session", RenameSessionParams> | DaemonControlRequestFrame<"close_session", CloseSessionParams> | DaemonControlRequestFrame<"delete_session", DeleteSessionParams> | DaemonControlRequestFrame<"shutdown", ShutdownParams> | DaemonControlRequestFrame<"authenticate", DaemonAuthenticateParams> | DaemonControlRequestFrame<"get_models", DaemonGetModelsParams> | DaemonControlRequestFrame<"get_byok_config", DaemonGetByokConfigParams> | DaemonControlRequestFrame<"validate_byok_model", DaemonValidateByokModelParams> | DaemonControlRequestFrame<"list_byok_configs", DaemonListByokConfigsParams> | DaemonControlRequestFrame<"create_byok_config", DaemonCreateByokConfigParams> | DaemonControlRequestFrame<"update_byok_config", DaemonUpdateByokConfigParams> | DaemonControlRequestFrame<"delete_byok_config", DaemonDeleteByokConfigParams> | DaemonControlRequestFrame<"check_byok_config", DaemonCheckByokConfigParams> | DaemonControlRequestFrame<"list_plugins", DaemonListPluginsParams> | DaemonControlRequestFrame<"validate_plugins", DaemonValidatePluginsParams> | DaemonControlRequestFrame<"setproxy", DaemonSetProxyParams> | DaemonControlRequestFrame<"get_usage_info", DaemonGetUsageInfoParams> | DaemonControlRequestFrame<"account_info", DaemonAccountInfoParams>;
 export interface DaemonCommandResultMap {
     initialize: InitializeDaemonResult;
     open_session: OpenSessionResult;
@@ -243,6 +308,7 @@ export interface DaemonCommandResultMap {
     close_session: null;
     delete_session: null;
     shutdown: null;
+    authenticate: DaemonAuthenticateResult;
     get_models: DaemonGetModelsResult;
     get_byok_config: DaemonGetByokConfigResult;
     validate_byok_model: DaemonValidateByokModelResult;
@@ -252,6 +318,8 @@ export interface DaemonCommandResultMap {
     delete_byok_config: null;
     check_byok_config: DaemonCheckByokConfigResult;
     list_plugins: DaemonListPluginsResult;
+    validate_plugins: DaemonValidatePluginsResult;
+    setproxy: DaemonSetProxyResult;
     get_usage_info: DaemonGetUsageInfoResult;
     account_info: DaemonAccountInfoResult;
 }

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

@@ -4,7 +4,7 @@ import type { QueryTransportProvider } from '../core/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';
-import type { PluginDetails } from '../types/plugins.js';
+import type { PluginDetails, PluginValidationReport } from '../types/plugins.js';
 export type DaemonState = 'ready' | 'stopping' | 'stopped' | 'failed';
 export type SessionRuntimeState = 'pending' | 'ready' | 'inactive' | 'failed';
 export interface DaemonSessionInfo {
@@ -16,21 +16,52 @@ export interface DaemonSessionInfo {
     updatedAt: string;
 }
 export interface StartDaemonOptions {
-    auth: InternalAuthOptions;
-    /** Idle Worker timeout in milliseconds. Set to 0 to disable reclamation. */
-    workerIdleTimeoutMs?: number;
+    /**
+     * Credentials for the daemon's own account plane and its in-process Sessions.
+     *
+     * **Optional.** When omitted the daemon starts in the "no credentials" state:
+     * the handshake does no identity work, and auth-needing calls answer
+     * `AUTH_PAYLOAD_REQUIRED` until you supply credentials via `daemon.auth(payload)`.
+     * When provided it is validated (shape) at the handshake and landed lazily on the
+     * first auth-needing consumer — never blocking `startDaemon` on the login network.
+     */
+    auth?: InternalAuthOptions;
     /**
      * Budget for the `daemon.initialize` round trip; defaults to 30s.
      *
-     * The CLI lands the in-band credentials while handling initialize — token
-     * exchange, user info, a possible host callback for the first token, and the
-     * account tier prefill — so the wall time follows the host's network and the
-     * CLI's own startup cost. Raise this when either is slow; initialize only
-     * resolves once that work is complete.
+     * The handshake only validates the credential payload (when `auth` is given at
+     * all — it is optional) and installs the session plane; no auth network happens
+     * inside it. The CLI lands the credentials **on demand**: the first auth-needing
+     * call (an account-level query, a session's first inference, or an explicit
+     * `daemon.auth()`) starts the login. This budget therefore covers CLI startup and
+     * the handshake I/O only. Note that host-callback credential requests
+     * (`daemon.auth.fetch_job_token` / `fetch_service_account_token`) can arrive
+     * at any later point, whenever something first triggers the landing.
      */
     initializeTimeoutMs?: number;
     pathToQoderCLIExecutable?: string;
+    /**
+     * 运行 CLI 脚本入口的解释器（node/bun/deno 等），语义与 `query()` 的
+     * `Options.executable` 一致：只在解析出的 CLI 入口是脚本文件（.js/.mjs/.ts/...）
+     * 时生效，原生二进制忽略它。缺省用宿主 SDK 的 `process.execPath`——原生平台
+     * 把随包 Node 传在这里（`executable: runtime.interpreterPath` 配
+     * `pathToQoderCLIExecutable: runtime.executablePath`）。
+     */
+    executable?: string;
+    /** 解释器参数，插在 CLI 脚本路径之前；语义同 `Options.executableArgs`。 */
+    executableArgs?: string[];
+    /**
+     * daemon 进程级代理：握手时随 `daemon.initialize` 写入，作用于该 daemon 的
+     * 账号面与所有会话（`daemon_proxy_v1`）。运行期可用 `daemon.setProxy()` 切换。
+     */
     proxy?: string;
+    /**
+     * VPC private-deployment endpoint for the daemon process (CN deployments only).
+     * Written to `QODERCN_VPC_ENDPOINT` / `QODER_VPC_ENDPOINT` before spawn; the CLI
+     * reads that environment variable ahead of `settings.json`'s vpcInstanceName.
+     * Sessions share the daemon process, so this is not a per-Query option.
+     */
+    vpcEndpoint?: string;
     env?: Record<string, string | undefined>;
     /**
      * daemon 子进程 stderr 的实时回调。
@@ -53,6 +84,11 @@ export interface StartDaemonOptions {
 }
 export interface Daemon {
     readonly state: DaemonState;
+    /**
+     * 订阅连接/进程级失败（与 DaemonImpl 内部 acceptDaemonFailure 同源）。全局槽位靠它
+     * 感知「活跃 daemon 已死」并触发重建；普通调用方不需要订阅。返回取消订阅句柄。
+     */
+    onFailure(listener: (error: Error) => void): () => void;
     /**
      * 列出会话。`cwd` 给定时只列该工作目录名下的会话；缺省时返回所有目录的全部会话
      * （daemon 无 cwd 概念，「不传目录」即「不过滤」，由 CLI 侧全量扫盘）。
@@ -66,10 +102,51 @@ export interface Daemon {
     /** 删除会话。`cwd` 语义同 renameSession。 */
     deleteSession(localSessionId: string, cwd?: string): Promise<void>;
     /**
-     * Account-level queries, answered from the credentials the daemon was
-     * started with — never from a Session's. They require a daemon that accepted
-     * `StartDaemonOptions.auth` and reported `daemon_queries_v1`; otherwise they
-     * reject.
+     * Set or clear the daemon-level (process-wide) proxy for every Session.
+     * `undefined` / `null` / an empty string clears it. Requires
+     * `daemon_proxy_v1`; resolves with the normalized proxy (or null).
+     */
+    setProxy(proxy?: string | null): Promise<string | null>;
+    /**
+     * The daemon-level proxy currently in effect (`null` when unset/cleared, or
+     * when the CLI does not support `daemon_proxy_v1`).
+     */
+    getProxy(): string | null;
+    /**
+     * Explicitly lands credentials and reports whether the daemon is authenticated.
+     *
+     * The `daemon.initialize` handshake only *validates* the credential payload (and
+     * `StartDaemonOptions.auth` is optional); the CLI lands it **on demand** — the
+     * first auth-needing call (an account-level query, or a session's first inference)
+     * triggers the login implicitly.
+     *
+     * - `auth()` (no argument): authenticate with the credentials the daemon already
+     *   holds (from `startDaemon`). Rejects with `AUTH_PAYLOAD_REQUIRED` if it holds
+     *   none. Idempotent: concurrent and repeated calls share one landing.
+     * - `auth(payload)`: **override** the held credentials with `payload`, then
+     *   authenticate. Use it to supply credentials to a daemon started without auth,
+     *   or to switch accounts on an already-authenticated daemon. A host-callback arm
+     *   (`jobToken` / `serviceAccount` token provider) rebinds the reverse-request
+     *   bridge so the daemon's token fetch reaches the new callback. The override also
+     *   updates the credentials a later `query({ daemon })` reuses.
+     *
+     * Resolves `false` for a non-fatal "no credential" outcome (e.g. the read-only
+     * borrow of the local qodercli login found nothing). Rejected credentials reject
+     * this promise with a `DaemonRpcError` carrying the CLI's error code — never a
+     * silent `false`.
+     */
+    auth(payload?: InternalAuthOptions): Promise<boolean>;
+    /**
+     * Account-level queries, answered from the daemon's own credentials — never
+     * from a Session's. `daemon_queries_v1` is always negotiated, so these are
+     * always callable; each answer depends on the daemon's auth state:
+     * authenticated → the data; pending (holds credentials, not yet landed) →
+     * triggers the landing then answers; no credentials → `AUTH_PAYLOAD_REQUIRED`
+     * (call `auth(payload)` first).
+     *
+     * Auth-needing queries trigger the credential landing on demand, so the first
+     * one may be as slow as a login; `getModels`' cache path answers without
+     * credentials and does not trigger it.
      *
      * Unlike the per-`Query` equivalents these do not swallow failures into
      * `null`: capability is already negotiated here, so a rejection is a real
@@ -84,6 +161,19 @@ export interface Daemon {
     deleteByokConfig(target: DeleteByokConfigInput): Promise<void>;
     checkByokConfig(input: CheckByokConfigInput): Promise<ByokConfigCheckResult>;
     listPlugins(): Promise<PluginDetails[]>;
+    /**
+     * Whether the daemon advertised `capability` in the initialize result.
+     * Capabilities are negotiated once per connection and never change.
+     */
+    supportsCapability(capability: string): boolean;
+    /**
+     * Statically validates local plugins in-process (no Session, no auth).
+     * Requires `daemon_validate_plugins_v1`; older daemons reject with a
+     * `DaemonProtocolError` and callers should fall back to the Worker path.
+     */
+    validatePlugins(paths: readonly string[], options?: {
+        configDir?: string;
+    }): Promise<PluginValidationReport[]>;
     getUsageInfo(): Promise<UsageInfo | null>;
     accountInfo(): Promise<AccountInfo>;
     stop(): Promise<void>;
@@ -95,7 +185,19 @@ interface InternalDaemonRuntime {
         cliPath?: string;
         env?: Record<string, string | undefined>;
     };
-    readonly auth: InternalAuthOptions;
+    /**
+     * Credentials a daemon-bound `query()` reuses for its Session. Optional: a daemon
+     * started without auth has none until `daemon.auth(payload)` supplies them — that
+     * call updates this field so a later `query({ daemon })` sees the credentials
+     * instead of tripping query()'s "auth is required" client-side gate. Mutable for
+     * exactly that reason.
+     */
+    auth?: InternalAuthOptions;
+    /**
+     * The daemon-level proxy currently applied by the CLI (`null` when unset or
+     * when the CLI ignored the handshake proxy). Updated by `setProxy`.
+     */
+    proxy: string | null;
     readonly transportProvider: QueryTransportProvider<ProcessTransportOptions>;
 }
 export declare function getDaemonRuntime(daemon: Daemon): InternalDaemonRuntime | undefined;

package/dist/index.d.ts

@@ -59,7 +59,8 @@ export { initDaemon, shutdownDaemon } from './daemon/global-daemon.js';
 export type { DaemonFallbackReason, DaemonInitResult, InitDaemonOptions, } from './daemon/global-daemon.js';
 export { startDaemon } from './daemon/start-daemon.js';
 export type { Daemon, DaemonState, DaemonSessionInfo, SessionRuntimeState, StartDaemonOptions, } from './daemon/start-daemon.js';
-export type { DaemonGetModelsParams, DaemonValidateByokModelParams, } from './daemon/protocol.js';
+export type { DaemonGetModelsParams, DaemonValidateByokModelParams, DaemonValidatePluginsParams, DaemonSetProxyParams, } from './daemon/protocol.js';
+export { 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';
@@ -75,13 +76,14 @@ export { importSessionToStore } from './session/session-import.js';
 export type { ImportSessionToStoreOptions } from './session/session-import.js';
 export type { SessionKey, SessionStore, SessionStoreEntry, SessionStoreFlush, } from './session/session-store.js';
 export { listPlugins, enablePlugin, disablePlugin, installPlugin, uninstallPlugin, validatePlugin, } from './global/plugins.js';
-export type { PluginScope, ListPluginsOptions, PluginToggleOptions, InstallPluginOptions, UninstallPluginOptions, PluginDetails, PluginResources, InstallPluginResult, UninstallPluginResult, PluginValidationSeverity, PluginValidationPhase, PluginValidationPosition, PluginValidationLocation, PluginValidationDiagnostic, PluginValidationReport, ValidatePluginOptions, } from './types/plugins.js';
+export type { PluginScope, ListPluginsOptions, PluginToggleOptions, InstallPluginOptions, UninstallPluginOptions, PluginDetails, PluginResources, InstallPluginResult, UninstallPluginResult, PluginValidationSeverity, PluginValidationPhase, PluginValidationPosition, PluginValidationLocation, PluginValidationDiagnostic, PluginValidationReport, PluginValidationDaemon, ValidatePluginOptions, } from './types/plugins.js';
 export { submitFeedback } from './feedback.js';
 export type { SubmitFeedbackParams, SubmitFeedbackOptions, IntegrationMode, } from './feedback.js';
 export type { HostActionOptions, HostActionParams } from './types/host-action.js';
 export type { HostAction, HostActionEvent, } from './protocol/feedback.js';
 export { AbortError, ControlRequestError, CONTROL_REQUEST_TIMEOUT_CODE, FrameTooLargeError, QoderCliInitializationError, ModelPolicyTimeoutError, ProtocolVersionMismatchError, UnsupportedCliCapabilityError, } from './core/errors.js';
-export { DaemonRpcError } from './daemon/daemon-connection.js';
+export { DaemonRpcError, DaemonSessionAlreadyOpenError, } from './daemon/daemon-connection.js';
+export { DaemonHeartbeatTimeoutError, DAEMON_HEARTBEAT_TIMEOUT_MS, } from './daemon/daemon-connection.js';
 export { AuthAccessTokenEnvVarError, AuthServiceAccountEnvVarError, } from './core/runtime-launch-options.js';
 export { WIRE_PROTOCOL_VERSION } from './protocol/version.js';
 export type { ModelPromptPatch, ModelPromptPatches, } from './protocol/model-prompt-patches.js';