@qoder-ai/qoder-agent-sdk 1.0.51 → 1.0.53

package/dist/core/bounded-line-transform.d.ts

@@ -1,16 +1,10 @@
 import { Transform, type TransformCallback } from 'node:stream';
 export declare const DEFAULT_MAX_JSONL_FRAME_BYTES: number;
-export declare class FrameTooLargeError extends Error {
-    readonly direction: string;
-    readonly limit: number;
-    readonly code = "DAEMON_FRAME_TOO_LARGE";
-    constructor(direction: string, limit: number);
-}
 export declare class BoundedLineTransform extends Transform {
     private readonly maxLineBytes;
-    private readonly direction;
+    private readonly source;
     private bytesSinceNewline;
-    constructor(maxLineBytes?: number, direction?: string);
+    constructor(maxLineBytes?: number, source?: string);
     _transform(chunk: Buffer | string, encoding: BufferEncoding, callback: TransformCallback): void;
 }
-export declare function assertBoundedSerializedFrame(serializedFrame: string, maxFrameBytes?: number, direction?: string): void;
+export declare function assertBoundedSerializedFrame(serializedFrame: string, maxFrameBytes?: number, source?: string, inputMessageUuid?: string): void;

package/dist/core/close-diagnostics.d.ts

@@ -0,0 +1,4 @@
+import type { CloseDiagnosticEvent } from '../types/close-diagnostics.js';
+import type { DiagnosticsSink } from './sdk-diagnostics.js';
+/** 观测不能改变原关闭操作的完成、失败或等待语义。 */
+export declare function observeCloseStage<T>(diagnostics: DiagnosticsSink | undefined, component: CloseDiagnosticEvent['component'], stage: CloseDiagnosticEvent['stage'], operation: () => T | PromiseLike<T>): Promise<T>;

package/dist/core/errors.d.ts

@@ -1,6 +1,26 @@
 /**
  * Custom error types for the Qoder Agent SDK.
  */
+import type { SDKResultMessage } from '../protocol/messages.js';
+/** JSONL 帧超过传输预算；输入与输出使用不同错误码，避免把执行端输出问题归因于用户输入。 */
+export declare class FrameTooLargeError extends Error {
+    readonly direction: 'input' | 'output';
+    readonly limit: number;
+    readonly actualBytes: number;
+    readonly source: string;
+    /** 写入前被拒绝的用户输入 UUID；输出帧或控制帧不提供此字段。 */
+    readonly inputMessageUuid?: string | undefined;
+    readonly code: 'SDK_INPUT_TOO_LARGE' | 'SDK_OUTPUT_TOO_LARGE';
+    constructor(direction: 'input' | 'output', limit: number, actualBytes: number, source: string, 
+    /** 写入前被拒绝的用户输入 UUID；输出帧或控制帧不提供此字段。 */
+    inputMessageUuid?: string | undefined);
+}
+/** CLI 在初始化完成前返回失败结果时抛出，保留原始提示、错误码和结果。 */
+export declare class QoderCliInitializationError extends Error {
+    readonly code: number | string | undefined;
+    readonly result: SDKResultMessage;
+    constructor(result: SDKResultMessage);
+}
 /**
  * Thrown when an operation is aborted, typically via an AbortSignal.
  * Mirrors the built-in DOMException AbortError semantics.

package/dist/core/sdk-diagnostics.d.ts

@@ -1,8 +1,11 @@
+import type { CloseDiagnosticEvent } from '../types/close-diagnostics.js';
 /** Minimal internal diagnostics sink used by query runtimes. */
 export interface DiagnosticsSink {
     record(message: string, error?: unknown): void;
+    recordClose?(event: Omit<CloseDiagnosticEvent, 'correlationId'>): void;
 }
 export type SdkDiagnosticsOptions = {
+    onCloseDiagnostic?: (event: CloseDiagnosticEvent) => void;
     debug?: boolean;
     debugFile?: string;
     stderr?: (data: string) => void;
@@ -10,11 +13,15 @@ export type SdkDiagnosticsOptions = {
 export declare function isSdkDiagnosticsEnabled(options: SdkDiagnosticsOptions): boolean;
 export declare function resolveSdkDiagnosticsFilePath(options: SdkDiagnosticsOptions): string | undefined;
 export declare class SdkDiagnostics implements DiagnosticsSink {
+    private readonly correlationId;
+    private readonly onCloseDiagnostic?;
     private readonly enabled;
     private readonly debugFile?;
     private readonly stderr?;
     constructor(options?: SdkDiagnosticsOptions);
     record(message: string, error?: unknown): void;
+    /** 独立于 debug/stderr 的安全通道，适用于禁用原始诊断的 BYOK 宿主。 */
+    recordClose(event: Omit<CloseDiagnosticEvent, 'correlationId'>): void;
     get filePath(): string | undefined;
     private writeToFile;
     private writeToStderr;

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

@@ -2,6 +2,7 @@ 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 { 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";
 export interface DaemonConnectionOptions {
@@ -9,6 +10,23 @@ export interface DaemonConnectionOptions {
     output: Readable;
     requestHandler?: DaemonRequestHandler;
     maxFrameBytes?: number;
+    /**
+     * 对端为什么没了——由持有子进程的一侧回答。
+     *
+     * stdout EOF 与子进程 'exit' 是两个独立事件，先后顺序不确定，而 `fail()` 是
+     * 「第一个失败者获胜」（`if (this.failure) return`）。若让裸的 EOF 先落定，
+     * 退出码与 stderr 尾巴就永久丢失，宿主只拿到一句 "Daemon connection closed"——
+     * 这正是联调时最难排查的形态：daemon 明明在 stderr 上写清了原因。
+     * 所以 EOF 路径先向进程侧要一次退出上下文；要得到就用它带来的错误落定。
+     * 返回 undefined 表示进程确实还活着（真正的半开管道），此时才退回笼统文案。
+     */
+    describeUnexpectedClose?: () => Promise<Error | undefined>;
+    /**
+     * SDK 侧诊断输出。daemon 是多会话共用的单进程，一条连接上的请求必须靠
+     * `request_id` + `session_id` 才能归属，所以这里每个记录点都带这两个字段。
+     * 只打协议元数据（方法名、id、耗时、字节数），绝不打帧原文、凭据与 prompt 正文。
+     */
+    diagnostics?: DiagnosticsSink;
 }
 export interface DaemonInitializeOptions {
     /** Advertised in addition to the capability this SDK cannot work without. */
@@ -52,6 +70,13 @@ export declare class DaemonConnection {
     private readonly activeInboundRequestIds;
     private readonly sessions;
     private readonly closedSessionIds;
+    /**
+     * 每个 daemon-bound 会话 open 时携带的工作目录（sessionId → cwd）。daemon 已无 cwd
+     * 概念，rename/delete 的磁盘定位目录只能来自请求；宿主调用 renameSession/deleteSession
+     * 通常不再显式传 cwd，故这里记住会话自己的 cwd，发请求时自动补上。会话关闭后仍保留，
+     * 因为「关掉后再改名/删除历史会话」是正常路径（此时 CLI 侧已无在世 cwd 可回落）。
+     */
+    private readonly sessionCwds;
     private readonly pendingSessionMessages;
     private readonly pendingSessionMessageBytes;
     private pendingSessionMessageFrameCount;
@@ -66,17 +91,19 @@ export declare class DaemonConnection {
     private stopping;
     private failure;
     private readonly failureListeners;
+    private readonly describeUnexpectedClose;
+    private readonly diagnostics;
     constructor(options: DaemonConnectionOptions);
     initialize(sdkVersion: string, options?: DaemonInitializeOptions): Promise<void>;
     createSessionTransport(options: DaemonSessionTransportOptions): DaemonSessionTransport;
     supportsCapability(capability: string): boolean;
     onFailure(listener: (error: Error) => void): () => void;
     openSession(params: OpenSessionParams, transport: DaemonSessionTransport): Promise<string>;
-    listSessions(): Promise<import("./protocol.js").DaemonSessionInfo[]>;
-    renameSession(sessionId: string, title: string): Promise<RenameSessionResult>;
+    listSessions(cwd?: string): Promise<import("./protocol.js").DaemonSessionInfo[]>;
+    renameSession(sessionId: string, title: string, cwd?: string): Promise<RenameSessionResult>;
     sendSessionMessage(message: DaemonWireSessionMessage): Promise<void>;
     closeSession(sessionId: string): Promise<void>;
-    deleteSession(localSessionId: string): Promise<void>;
+    deleteSession(localSessionId: string, cwd?: string): Promise<void>;
     /**
      * Sends one account-level query (`daemon_queries_v1`).
      *
@@ -87,6 +114,11 @@ export declare class DaemonConnection {
      */
     query<Method extends DaemonQueryMethod>(method: Method, params: DaemonCommandParamsMap[Method]): Promise<DaemonCommandResultMap[Method]>;
     shutdown(timeoutMs?: number): Promise<void>;
+    /**
+     * EOF 落定前问一次进程侧：对端是不是已经退了、为什么退。
+     * 提供者自己带 grace 超时，所以这里不会无限等；它抛错或答不上来就退回笼统文案。
+     */
+    private resolveUnexpectedClose;
     fail(error: unknown, notifyListeners?: boolean): void;
     private request;
     private readOutput;

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

@@ -2,11 +2,17 @@ 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 { DiagnosticsSink } from '../core/sdk-diagnostics.js';
 export type DaemonSessionTransportOptions = {
     workerArgs: string[];
     cwd?: string;
     configDir?: string;
     cleanup?: () => void;
+    /**
+     * 由 DaemonConnection.createSessionTransport 注入，调用方不需要传。
+     * 会话级记录一律带 sessionId——daemon 是多会话共用一条连接，不带归属的日志无法用。
+     */
+    diagnostics?: DiagnosticsSink;
 };
 export declare class DaemonSessionTransport implements Transport {
     private readonly connection;
@@ -35,6 +41,8 @@ export declare class DaemonSessionTransport implements Transport {
     fail(error: unknown): void;
     private open;
     private failAndRelease;
+    /** 会话级记录一律带 sessionId；daemon 多会话共用一条连接，不带归属无法排查。 */
+    private record;
     private startRelease;
     private releaseSessionOnce;
     private releaseSession;
@@ -44,5 +52,7 @@ export declare class DaemonSessionTransport implements Transport {
     private observeCommandLifecycle;
     private maybeCloseAfterResult;
     private performClose;
+    /** 幂等地置 closed 并跑一次 cleanup；performClose 的成功与失败两条出口共用。 */
+    private markClosed;
     private cleanup;
 }

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

@@ -8,6 +8,12 @@ export interface InitDaemonOptions {
     pathToQoderCLIExecutable?: string;
     proxy?: string;
     env?: Record<string, string | undefined>;
+    /** 语义同 `StartDaemonOptions.stderr`：daemon 子进程 stderr 的实时回调。 */
+    stderr?: (data: string) => void;
+    /** 语义同 `StartDaemonOptions.debug`。 */
+    debug?: boolean;
+    /** 语义同 `StartDaemonOptions.debugFile`。 */
+    debugFile?: string;
 }
 export type DaemonFallbackReason = 'protocol_version_mismatch' | 'daemon_unavailable';
 export type DaemonInitResult = {

package/dist/daemon/protocol.d.ts

@@ -106,12 +106,24 @@ export type DaemonSessionInfo = {
     created_at: string;
     updated_at: string;
 };
-export type ListSessionsParams = Record<string, never>;
+export type ListSessionsParams = {
+    /**
+     * 目录过滤：给定时 daemon 只列该工作目录名下的磁盘会话；缺省时全量扫盘、返回所有
+     * 目录的会话。daemon 不再持有 cwd 概念，因此「不传目录」的语义是「不过滤」，而不是
+     * 「回落到 daemon 启动目录」——后者会让非 daemon 目录下的会话离线不可发现。
+     */
+    cwd?: string;
+};
 export type ListSessionsResult = {
     sessions: DaemonSessionInfo[];
 };
 export type RenameSessionParams = {
     title: string;
+    /**
+     * 会话所在工作目录。daemon 不再有 cwd，磁盘定位目录只能来自请求；SDK 侧对 daemon-bound
+     * 会话会自动带上该会话 open 时的 cwd，宿主也可显式指定以定位任意目录下的历史会话。
+     */
+    cwd?: string;
 };
 export type RenameSessionResult = {
     session: DaemonSessionInfo;
@@ -119,6 +131,11 @@ export type RenameSessionResult = {
 export type CloseSessionParams = Record<string, never>;
 export type DeleteSessionParams = {
     local_session_id: string;
+    /**
+     * 会话所在工作目录。同 rename：daemon 无 cwd，磁盘定位目录只能来自请求；SDK 对
+     * daemon-bound 会话自动带上其 open 时的 cwd。
+     */
+    cwd?: string;
 };
 export type ShutdownParams = Record<string, never>;
 /**

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

@@ -29,16 +29,42 @@ export interface StartDaemonOptions {
      * resolves once that work is complete.
      */
     initializeTimeoutMs?: number;
-    cwd?: string;
     pathToQoderCLIExecutable?: string;
     proxy?: string;
     env?: Record<string, string | undefined>;
+    /**
+     * daemon 子进程 stderr 的实时回调。
+     *
+     * `query()` 的 `Options.stderr` 一直有这个通道，daemon 侧此前没有——于是 daemon
+     * 写在 stderr 上的一切宿主都收不到，只能等进程死后从错误对象里捡一个截断的尾巴。
+     * 联调时最需要的恰恰是实时看到 daemon 说了什么，所以补上。
+     * 与 `QoderCliProcessError.stderr` 互补：这个是流式的、完整的；那个是事后截断的。
+     * 回调抛错不影响 daemon，也不会中断 stderr 采集。
+     */
+    stderr?: (data: string) => void;
+    /**
+     * 打开 SDK 侧诊断日志，语义与 `query()` 的 `Options.debug` 一致；
+     * 环境变量 `QODER_AGENT_SDK_DEBUG` 也能打开。此前 daemon 链路完全没有诊断输出，
+     * 而它是唯一承载多会话的进程，出问题时最需要这条通道。
+     */
+    debug?: boolean;
+    /** 诊断日志落盘路径。给了它就隐含打开诊断，且不再走 stderr 回调。 */
+    debugFile?: string;
 }
 export interface Daemon {
     readonly state: DaemonState;
-    listSessions(): Promise<DaemonSessionInfo[]>;
-    renameSession(localSessionId: string, title: string): Promise<DaemonSessionInfo>;
-    deleteSession(localSessionId: string): Promise<void>;
+    /**
+     * 列出会话。`cwd` 给定时只列该工作目录名下的会话；缺省时返回所有目录的全部会话
+     * （daemon 无 cwd 概念，「不传目录」即「不过滤」，由 CLI 侧全量扫盘）。
+     */
+    listSessions(cwd?: string): Promise<DaemonSessionInfo[]>;
+    /**
+     * 重命名会话。`cwd` 用于在磁盘上定位会话目录；daemon-bound 会话可省略——SDK 会自动
+     * 带上该会话 open 时的 cwd。仅当重命名一个并非经本 daemon 打开的历史会话时才需显式传。
+     */
+    renameSession(localSessionId: string, title: string, cwd?: string): Promise<DaemonSessionInfo>;
+    /** 删除会话。`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
@@ -68,11 +94,30 @@ interface InternalDaemonRuntime {
         proxy?: string;
         cliPath?: string;
         env?: Record<string, string | undefined>;
-        cwd?: string;
     };
     readonly auth: InternalAuthOptions;
     readonly transportProvider: QueryTransportProvider<ProcessTransportOptions>;
 }
 export declare function getDaemonRuntime(daemon: Daemon): InternalDaemonRuntime | undefined;
 export declare function startDaemon(options: StartDaemonOptions): Promise<Daemon>;
+/**
+ * 宿主什么都没配时的默认诊断落盘位置。
+ *
+ * 联调场景里客户只是正常使用，不会去设 `QODER_AGENT_SDK_DEBUG`，也不会在代码里传
+ * `debug`/`debugFile`——而 SdkDiagnostics 三者全无时是彻底静默的，于是 SDK 侧那半条
+ * 链路（spawn、握手、请求往返、会话开关）对客户完全不可见。默认落到文件补上这一段。
+ *
+ * 三个刻意的选择：
+ * - **写文件而不是 stderr**：daemon 侧默认往 process.stderr 写会污染宿主输出，
+ *   而宿主可能正把 stderr 当协议通道或展示给用户。文件是安全的默认。
+ * - **放在 CLI 日志同一个 logs/ 目录下**：`getConfigDir()` 与 CLI 的日志根同源
+ *   （同样认 QODER_CONFIG_DIR 与品牌目录），排障时两侧日志在一处，不用猜路径。
+ * - **文件名带 pid 与时间戳**：一个宿主进程可能反复起停 daemon，共用一个追加文件
+ *   会无限增长且多实例互相插话；按次分文件后单个文件的生命周期等于一个 daemon。
+ *
+ * 显式传了 `debug: true`（意图是走 stderr 回调）时不覆盖宿主的选择不返回默认路径。
+ */
+export declare function defaultDaemonDiagnosticsFile(options: {
+    debug?: boolean;
+}): string | undefined;
 export {};

package/dist/index.d.ts

@@ -80,7 +80,7 @@ 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, ModelPolicyTimeoutError, ProtocolVersionMismatchError, UnsupportedCliCapabilityError, } from './core/errors.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 { AuthAccessTokenEnvVarError, AuthServiceAccountEnvVarError, } from './core/runtime-launch-options.js';
 export { WIRE_PROTOCOL_VERSION } from './protocol/version.js';
@@ -120,4 +120,5 @@ export type { SDKControlGetModelPolicyRequest, SDKControlGetModelPolicyResponse,
 export type { SDKControlGetByokConfigRequest, SDKControlGetByokConfigResponse, SDKControlValidateByokModelRequest, SDKControlValidateByokModelResponse, SDKControlListByokConfigsRequest, SDKControlListByokConfigsResponse, SDKControlCreateByokConfigRequest, SDKControlCreateByokConfigResponse, SDKControlUpdateByokConfigRequest, SDKControlDeleteByokConfigRequest, SDKControlCheckByokConfigRequest, SDKControlCheckByokConfigResponse, BYOKModelValidationInput, BYOKLocalizedName, BYOKProviderInfo, BYOKModelTypeInfo, BYOKModelInfo, ByokProtocol, ByokModelConfigInfo, CustomByokProviderConfigInfo, ByokConfigInfo, ByokModelConfigInput, CustomByokProviderThinkingMode, CustomByokProviderReasoningEffortLevel, CustomByokProviderThinkingCapabilitiesInput, CustomByokProviderModelCapabilitiesInput, CustomByokProviderModelInput, CustomByokProviderConfigInput, CreateByokConfigInput, UpdateByokModelConfigInput, UpdateCustomByokProviderConfigInput, UpdateByokConfigInput, DeleteByokConfigInput, CheckByokConfigInput, ByokConfigReference, ByokConfigCheckResult, CustomModel, } from './types/byok.js';
 export { isBashToolBackgroundLaunchResult } from './types/tools.js';
 export type { AgentInput, AgentOutput, AgentToolCompletionResult, AgentToolBackgroundLaunchResult, AgentToolTeammateSpawnedResult, BashInput, BashToolBackgroundLaunchResult, FileReadInput, FileReadOutput, FileEditInput, FileWriteInput, GlobInput, GrepInput, WebFetchInput, WebSearchInput, AskUserQuestionInput, NotebookEditInput, TaskCreateInput, TaskCreateOutput, TaskGetInput, TaskGetOutput, TaskUpdateInput, TaskUpdateOutput, TaskListInput, TaskListOutput, ExitPlanModeInput, TodoWriteInput, ToolInputSchemas, ToolOutputSchemas, } from './types/tools.js';
-export type { FeedbackResult } from './types/account.js';
+export type { FeedbackResult } from './types/account.js';
+export type { CloseDiagnosticEvent } from './types/close-diagnostics.js';