@qoder-ai/qoder-agent-sdk 1.0.14 → 1.0.16

package/README.md

@@ -306,6 +306,101 @@ workflows that need state across multiple turns. Runtime helpers include
 `q.streamInput(...)`, `q.interrupt()`, `q.setPermissionMode(...)`,
 `q.mcpAuthenticate(...)`, and `q.mcpSubmitOAuthCallbackUrl(...)`.
 
+Streaming user messages support three delivery priorities:
+
+- `priority: "now"` stops the current response and handles the message immediately.
+- `priority: "next"` is the default and handles the message at the next suitable point.
+- `priority: "later"` waits until the current response finishes.
+
+`shouldQuery: false` adds the message to the conversation without starting a
+response by itself. Its processing time still follows `priority`.
+
+Assign `uuid` to messages that need delivery tracking or cancellation.
+Do not reuse UUIDs within a session. `await q.interrupt()` stops the current
+response without closing the session. `await q.cancelAsyncMessage(uuid)` returns
+`true` when the queued message is cancelled and `false` when it can no longer
+be cancelled.
+
+## External Session Storage
+
+Queries persist their local session by default. Set `persistSession: false` for
+an ephemeral query that must not create resumable session state. Ephemeral
+queries cannot use `sessionStore` because mirroring starts from locally
+committed transcript entries.
+
+Use `sessionStore` when a host needs durable transcripts outside the local
+machine. The SDK mirrors entries after qodercli commits them locally. A later
+process can restore the same session before qodercli starts:
+
+```text
+qodercli commit -> SDK append(key, entries) -> external store
+external store -> SDK load(key) -> temporary QODER_CONFIG_DIR -> qodercli resume
+```
+
+```ts
+import {
+  InMemorySessionStore,
+  qodercliAuth,
+  query,
+} from "@qoder-ai/qoder-agent-sdk";
+
+const sessionStore = new InMemorySessionStore();
+
+const first = query({
+  prompt: "Inspect this project.",
+  options: {
+    auth: qodercliAuth(),
+    cwd: "/path/to/project",
+    sessionStore,
+  },
+});
+
+for await (const message of first) {
+  console.dir(message, { depth: null });
+}
+
+const resumed = query({
+  prompt: "Continue the analysis.",
+  options: {
+    auth: qodercliAuth(),
+    cwd: "/path/to/project",
+    resume: "11111111-1111-4111-8111-111111111111",
+    sessionStore,
+  },
+});
+```
+
+Every store implements `append(key, entries)` and `load(key)`. Implement
+`listSessions(projectKey)` for `continue: true` and session listing,
+`listSubkeys(key)` to restore and inspect child-agent transcripts, and
+`delete(key)` for deletion. Entries are opaque JSON objects and must remain in
+append order. A child transcript uses an opaque `subpath` such as
+`subagents/agent-<id>`; the key does not include the on-disk `.jsonl`
+extension.
+
+When `load()` returns `null` or an empty array for an explicit `resume`, the SDK
+falls back to the same local session ID. Store-backed `continue` starts a new
+session when `listSessions()` has no restorable session. Unsafe subpaths are
+ignored, and missing or empty child transcripts do not prevent restoration of
+the main session.
+
+`sessionStoreFlush: "batched"` is the default. `"eager"` starts each append
+without waiting for the result boundary. Final append failures are emitted as
+non-fatal `system/mirror_error` messages. `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
+`importSessionToStore(sessionId, store, options)` to copy an existing local main
+transcript, child-agent transcripts, and metadata into a store.
+
+### Production stores
+
+The SDK exports the `SessionStore` interface but does not ship a
+production-ready external storage implementation. Implement the interface
+against shared storage operated by your application, then validate its
+append/load ordering, project isolation, subkey handling, and deletion behavior
+with the shared conformance suite under `examples/session-stores/`.
+
 ## Custom Tools
 
 You can expose JavaScript or TypeScript functions to Qoder Agent as in-process
@@ -344,6 +439,39 @@ const q = query({
 });
 ```
 
+For stdio, SSE, and Streamable HTTP MCP servers, set `timeout` to the hard
+wall-clock limit for each tool call. The value is in milliseconds, progress
+notifications do not extend it, and values below 1,000 ms are ignored.
+
+An effective server `timeout` overrides `MCP_TOOL_TIMEOUT`. If neither is set,
+the CLI uses 100,000,000 ms (about 27.8 hours). Connection and discovery
+requests are independent: they use `MCP_TIMEOUT`, which defaults to 30,000 ms.
+
+```ts
+const q = query({
+  prompt: "Run the long report.",
+  options: {
+    auth: qodercliAuth(),
+    mcpServers: {
+      reports: {
+        type: "stdio",
+        command: "report-mcp-server",
+        timeout: 1_800_000,
+      },
+    },
+    allowedTools: ["mcp__reports__run_report"],
+  },
+});
+```
+
+The CLI also protects silent tool calls with an idle timeout: 30 minutes for
+stdio and 5 minutes for remote transports. Progress resets the idle timer but
+not the hard timeout. Set `QODER_MCP_TOOL_IDLE_TIMEOUT` to adjust the global
+idle baseline, or to `0` to disable it; a valid server `timeout` can extend the
+idle limit up to the hard timeout. In-process servers returned by
+`createSdkMcpServer()` do not expose a server-level `timeout` field and do not
+use the idle watchdog.
+
 ## Hooks
 
 Hooks are deterministic callbacks invoked at specific points in the agent loop.

package/dist/core/constants.d.ts

@@ -6,7 +6,7 @@
 /**
  * Hook events supported by the public SDK hook registration API.
  */
-export declare const HOOK_EVENTS: readonly ["PreToolUse", "PostToolUse", "PostToolUseFailure", "UserPromptSubmit", "SessionStart", "SessionEnd", "Stop", "SubagentStart", "SubagentStop", "PreCompact", "PostCompact", "CwdChanged", "InstructionsLoaded", "FileChanged", "PermissionRequest"];
+export declare const HOOK_EVENTS: readonly ["PreToolUse", "PostToolUse", "PostToolUseFailure", "UserPromptSubmit", "SessionStart", "SessionEnd", "Stop", "SubagentStart", "SubagentStop", "PreCompact", "PostCompact", "CwdChanged", "InstructionsLoaded", "FileChanged", "PermissionRequest", "PermissionDenied"];
 /**
  * All supported exit reasons for session termination.
  */
@@ -24,7 +24,7 @@ export declare const KILL_GRACE_MS = 5000;
 /**
  * Current SDK version, sent to CLI as QODER_AGENT_SDK_VERSION environment variable.
  */
-export declare const SDK_VERSION = "1.0.14";
+export declare const SDK_VERSION = "1.0.16";
 /**
  * Value for the `--permission-prompt-tool` CLI flag.
  *

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

@@ -0,0 +1,23 @@
+import type { StdoutMessage } from '../types/control.js';
+import type { Transport } from './transport.js';
+export declare class DeferredTransport implements Transport {
+    private readonly bootstrap;
+    private transport;
+    private bootstrapPromise;
+    private readonly pending;
+    private closed;
+    constructor(bootstrap: () => Promise<{
+        transport: Transport;
+        cleanup?: () => Promise<void>;
+    }>);
+    private cleanup;
+    private cleanupPromise;
+    initialize(): Promise<void>;
+    write(data: string): void;
+    close(): void;
+    isReady(): boolean;
+    readMessages(): AsyncGenerator<StdoutMessage, void, unknown>;
+    endInput(): void;
+    private getTransport;
+    private runCleanup;
+}

package/dist/core/errors.d.ts

@@ -8,14 +8,6 @@
 export declare class AbortError extends Error {
     constructor(message?: string);
 }
-/**
- * Thrown when a direct-connect transport encounters an error.
- * Direct-connect is an alternative transport that connects to a
- * running qodercli server via network rather than spawning a subprocess.
- */
-export declare class DirectConnectError extends Error {
-    constructor(message: string);
-}
 /**
  * Thrown when the CLI's wire protocol version is incompatible with the
  * version this SDK was built against (cross-major mismatch).

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

@@ -70,6 +70,7 @@ export interface ProcessTransportOptions {
     continue?: boolean;
     resume?: string;
     forkSession?: boolean;
+    persistSession?: boolean;
     maxTurns?: number;
     permissionMode?: PermissionMode;
     allowDangerouslySkipPermissions?: boolean;
@@ -78,6 +79,8 @@ export interface ProcessTransportOptions {
     canUseTool?: boolean;
     includePartialMessages?: boolean;
     includeHookEvents?: boolean;
+    /** Request SDK-internal post-commit transcript frames from qodercli. */
+    sessionMirror?: boolean;
     allowedTools?: string[];
     disallowedTools?: string[];
     tools?: ToolsOption;

package/dist/core/runtime-launch-options.d.ts

@@ -2,7 +2,8 @@ import type { DiagnosticsSink } from './sdk-diagnostics.js';
 import type { SdkPluginConfig, ToolConfig } from '../types/common.js';
 import type { InternalAuthOptions } from '../types/auth.js';
 import type { PermissionMode } from '../types/permissions.js';
-import type { McpServerConfigForProcessTransport, McpServerToolPolicy } from '../types/mcp.js';
+import type { McpServerConfigForProcessTransport } from '../protocol/mcp.js';
+import type { McpServerToolPolicy } from '../types/mcp.js';
 import type { SettingSource } from '../types/options.js';
 export declare class AuthAccessTokenEnvVarError extends Error {
     readonly code: "auth_access_token_env_var_not_configured";
@@ -24,6 +25,7 @@ export interface RuntimeLaunchOptions {
     continue?: boolean;
     resume?: string;
     forkSession?: boolean;
+    persistSession?: boolean;
     maxTurns?: number;
     permissionMode?: PermissionMode;
     allowDangerouslySkipPermissions?: boolean;
@@ -31,6 +33,7 @@ export interface RuntimeLaunchOptions {
     canUseTool?: boolean;
     includePartialMessages?: boolean;
     includeHookEvents?: boolean;
+    sessionMirror?: boolean;
     allowedTools?: string[];
     disallowedTools?: string[];
     tools?: ToolsOption;

package/dist/core/transport.d.ts

@@ -4,10 +4,8 @@
  * A Transport abstracts the bidirectional communication channel between
  * the SDK and the CLI. All transports must implement this interface.
  *
- * Implementations:
- * - ProcessTransport: spawns CLI as a subprocess, uses stdin/stdout (Node.js)
- * - WebSocketTransport: connects via WebSocket (browser environments)
- * - DirectConnectTransport: connects to a direct-connect server
+ * The default implementation spawns qodercli as a subprocess and uses
+ * stdin/stdout. Custom transports can implement this interface.
  */
 import type { StdoutMessage } from '../types/control.js';
 export interface Transport {

package/dist/index.d.ts

@@ -60,16 +60,19 @@ export { createSdkMcpServer, tool } from './mcp/sdk-mcp-server.js';
 export type { AnyZodRawShape, InferShape, SdkMcpToolDefinition, ToolExtras, CreateSdkMcpServerOptions, } from './mcp/sdk-mcp-server.js';
 export type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 export type { ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
-export { listSessions, getSessionInfo, getSessionMessages, getSubagentMessages, listSubagents, renameSession, tagSession, } from './session/session-manager.js';
+export { listSessions, getSessionInfo, getSessionMessages, getSubagentMessages, listSubagents, renameSession, tagSession, deleteSession, } from './session/session-manager.js';
 export { forkSession } from './session/session-fork.js';
+export { InMemorySessionStore } from './session/session-store.js';
+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 } from './global/plugins.js';
 export type { PluginDetails, PluginResources, InstallPluginResult, UninstallPluginResult } from './types/plugins.js';
 export { submitFeedback } from './feedback.js';
 export type { SubmitFeedbackParams, SubmitFeedbackOptions, IntegrationMode, } from './feedback.js';
-export { AbortError, DirectConnectError, ModelPolicyTimeoutError, ProtocolVersionMismatchError, } from './core/errors.js';
+export { AbortError, ModelPolicyTimeoutError, ProtocolVersionMismatchError, } from './core/errors.js';
 export { WIRE_PROTOCOL_VERSION } from './protocol/version.js';
-export { DirectConnectTransport } from './direct-connect/direct-connect-transport.js';
-export { parseDirectConnectUrl } from './direct-connect/url-parser.js';
+export type { ModelPromptPatch, ModelPromptPatches, } from './protocol/model-prompt-patches.js';
 export { HOOK_EVENTS, EXIT_REASONS } from './core/constants.js';
 import * as coreTypes from './types/index.js';
 export { coreTypes };
@@ -78,8 +81,8 @@ export type { AccessTokenInput, AuthOptions } from './types/auth.js';
  * @internal Internal auth types for first-party host integration, not general public use.
  */
 export type { FetchJobToken, JobTokenAuthOptions, JobTokenRequest, JobTokenResult, } from './types/auth.js';
-export type { AccountInfo, UsageAddOnQuotaBucket, UsageInfo, UsageOrgResourcePackage, UsageQuotaBucket, ApiKeySource, ExitReason, FastModeState, ConfigScope, SettingSource, SDKAssistantMessageError, SDKStatus, EffortLevel, ThinkingAdaptive, ThinkingEnabled, ThinkingDisabled, ThinkingConfig, OutputFormatType, JsonSchemaOutputFormat, OutputFormat, BaseOutputFormat, 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, SDKUserMessage, SDKUserMessageReplay, SDKResultMessage, SDKResultSuccess, SDKResultError, SDKSystemMessage, SDKSystemInitMessage, SDKSystemMessageSubtype, SDKSystemMessageBySubtype, SDKPartialAssistantMessage, SDKCompactBoundaryMessage, SDKStatusMessage, SDKAPIRetryMessage, SDKLocalCommandOutputMessage, SDKHookStartedMessage, SDKHookProgressMessage, SDKHookResponseMessage, SDKPermissionDeniedMessage, SDKTaskNotificationMessage, SDKTaskStartedMessage, SDKTaskProgressMessage, SDKSessionStateChangedMessage, SDKSessionTitleChangedMessage, SDKBridgeStateMessage, SDKFilesPersistedEvent, SDKElicitationCompleteMessage, SDKPromptSuggestionMessage, SDKCloudAgentEventMessage, SDKPermissionDenial, } from './types/messages.js';
+export type { AccountInfo, UsageAddOnQuotaBucket, UsageInfo, UsageOrgResourcePackage, UsageQuotaBucket, 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, SDKUserMessage, SDKUserMessageReplay, SDKResultMessage, SDKResultSuccess, SDKResultError, SDKSystemMessage, SDKSystemInitMessage, SDKSystemMessageSubtype, SDKSystemMessageBySubtype, SDKPartialAssistantMessage, SDKCompactBoundaryMessage, SDKStatusMessage, SDKAPIRetryMessage, SDKHookStartedMessage, SDKHookProgressMessage, SDKHookResponseMessage, SDKPermissionDeniedMessage, SDKMirrorErrorMessage, SDKTaskNotificationMessage, SDKTaskStartedMessage, SDKTaskProgressMessage, SDKSessionStateChangedMessage, SDKSessionTitleChangedMessage, SDKFilesPersistedEvent, SDKElicitationCompleteMessage, SDKPromptSuggestionMessage, SDKCloudAgentEventMessage, 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';
@@ -96,12 +99,8 @@ export type { SDKSessionInfo, SessionMessage, ListSessionsOptions, GetSessionInf
 export type { Settings, ResolvedSettings, ResolvedSettingsSource, } from './types/settings.js';
 export { filterEscalatingDefaultMode } from './types/settings.js';
 export type { QoderModelPurpose } from './types/control.js';
-export type { SDKControlRequest, SDKControlResponse, SDKControlInitializeResponse, SDKControlGetContextUsageResponse, SDKControlGetUsageInfoRequest, SDKControlGetUsageInfoResponse, SDKControlAddDirectoriesResponse, SDKControlReloadPluginsResponse, } from './types/control.js';
+export type { SDKControlRequest, SDKControlResponse, SDKControlInterruptResponse, SDKControlInitializeResponse, SDKControlGetContextUsageResponse, SDKControlGetUsageInfoRequest, SDKControlGetUsageInfoResponse, SDKControlAddDirectoriesResponse, SDKControlReloadPluginsResponse, } from './types/control.js';
 export type { SDKControlGetModelPolicyRequest, SDKControlGetModelPolicyResponse, SDKCapabilities, ModelPolicyContext, ModelPolicyResult, ModelPolicyProvider, } from './types/model-policy-provider.js';
 export type { SDKControlGetByokConfigRequest, SDKControlGetByokConfigResponse, SDKControlValidateByokModelRequest, SDKControlValidateByokModelResponse, BYOKModelValidationInput, BYOKProviderInfo, BYOKModelTypeInfo, BYOKModelInfo, CustomModel, } from './types/byok.js';
-export type { SessionState, BridgeSessionHandle, AttachBridgeSessionOptions, RemoteCredentials, } from './types/bridge.js';
-export type { OAuthCredential, AuthMessage, WebSocketOptions, BrowserQueryOptions, } from './types/browser.js';
 export type { AgentInput, AgentOutput, BashInput, FileReadInput, FileReadOutput, FileEditInput, FileWriteInput, GlobInput, GrepInput, WebFetchInput, WebSearchInput, AskUserQuestionInput, NotebookEditInput, ExitPlanModeInput, TodoWriteInput, ToolInputSchemas, ToolOutputSchemas, } from './types/tools.js';
-export type { DirectConnectOptions } from './direct-connect/direct-connect-transport.js';
-export type { DirectConnectUrlResult } from './direct-connect/url-parser.js';
 export type { FeedbackResult } from './types/account.js';