@qoder-ai/qoder-agent-sdk 1.0.23 → 1.0.25

package/dist/types/memory.d.ts

@@ -0,0 +1,74 @@
+import type { MemoryConsumptionFile, MemoryConsumptionResult, MemoryGenerationGateInput, MemoryGenerationGateResult, MemoryGenerationResult, MemoryRoot } from '../protocol/memory.js';
+export type { EffectiveMemoryConfig, MemoryConsumptionFile, MemoryConsumptionResult, MemoryGenerationGateInput, MemoryGenerationGateResult, MemoryGenerationResult, MemoryGenerationFailedFile, MemoryMode, MemoryRoot, MemoryRootAccess, SerializableMemoryConfig, SerializableMemoryConsumptionOptions, SerializableMemoryGenerationOptions, } from '../protocol/memory.js';
+/** Product-side decision invoked before TurnComplete memory generation starts. */
+export type MemoryShouldGenerate = (input: MemoryGenerationGateInput, options: {
+    signal: AbortSignal;
+}) => Promise<MemoryGenerationGateResult>;
+export type MemoryGenerationOptions = {
+    /** Enables automatic and active memory generation. Defaults to true. */
+    enabled?: boolean;
+    /** Memory directories available to the main agent and background memory agent. CLI defaults are used when omitted. */
+    roots?: MemoryRoot[];
+    /** Generation instructions. The CLI-owned default prompt is used when omitted. */
+    prompt?: string;
+    /** Controls generation started from the real CLI TurnComplete event. */
+    turnComplete?: {
+        /** Defaults to true when generation is enabled. */
+        enabled?: boolean;
+        /** Product-side gate called before the background memory agent starts. Omit to use only CLI built-in guards. */
+        shouldGenerate?: MemoryShouldGenerate;
+        /** Maximum time allowed for shouldGenerate. The CLI default is 10 seconds. */
+        timeoutMs?: number;
+        /** Whether callback errors/timeouts produce a skipped or failed generation result. Defaults to "skip". */
+        onGateError?: 'skip' | 'report_failed';
+    };
+    /** Called for every completed generation attempt, including saved, partial, no-change, skipped, and failed outcomes. */
+    onResult?: (result: MemoryGenerationResult) => void | Promise<void>;
+};
+export type MemoryConsumptionOptions = {
+    /** Enables memory consumption. Defaults to true. */
+    enabled?: boolean;
+    /** Explicit files to inject in array order. They replace CLI native auto-memory; static instructions remain. CLI native auto-memory is used when omitted. */
+    files?: MemoryConsumptionFile[];
+    /** Shared token budget for all explicit files. Omit for no explicit SDK budget. */
+    maxTokens?: number;
+    /** Behavior when explicit file content exceeds maxTokens. Defaults to "truncate". */
+    overflow?: 'truncate' | 'fail_query';
+    /** Read-failure behavior. Only required files fail the query in "fail_query" mode. Defaults to "best_effort". */
+    failureMode?: 'best_effort' | 'fail_query';
+    /** Receives per-file load status after initialization and explicit refreshes. */
+    onResult?: (result: MemoryConsumptionResult) => void | Promise<void>;
+};
+export type MemoryOptions = {
+    /** An empty object disables SDK memory, equivalent to omitting options.memory. */
+    mode?: never;
+    projectScope?: never;
+    userScope?: never;
+    generation?: never;
+    consumption?: never;
+} | {
+    /** Uses CLI-native generation and consumption; only scope switches and result callbacks are configurable. */
+    mode: 'native';
+    /** Enables or disables the CLI PROJECT scope for this Query. Defaults to `true`. */
+    projectScope?: boolean;
+    /** Enables or disables the CLI USER scope for this Query. Defaults to `true`. */
+    userScope?: boolean;
+    generation?: Pick<MemoryGenerationOptions, 'onResult'>;
+    consumption?: Pick<MemoryConsumptionOptions, 'onResult'>;
+} | {
+    /** Applies supplied overrides and inherits omitted behavior from the CLI. */
+    mode: 'custom';
+    /** Enables or disables the CLI PROJECT scope for inherited native behavior. Defaults to `true`. */
+    projectScope?: boolean;
+    /** Enables or disables the CLI USER scope for inherited native behavior. Defaults to `true`. */
+    userScope?: boolean;
+    /** Memory generation overrides. Omit to use CLI generation defaults. */
+    generation?: MemoryGenerationOptions;
+    /** Memory consumption overrides. Omit to use CLI consumption defaults. */
+    consumption?: MemoryConsumptionOptions;
+};
+export type MemoryRuntimeCallbacks = {
+    shouldGenerateCallbacks: ReadonlyMap<string, MemoryShouldGenerate>;
+    onGenerationResult?: MemoryGenerationOptions['onResult'];
+    onConsumptionResult?: MemoryConsumptionOptions['onResult'];
+};

package/dist/types/messages.d.ts

@@ -9,11 +9,12 @@ import type { SDKMessage as ProtocolSDKMessage, SDKStatusMessage as ProtocolSDKS
 import type { MessageParam, UUID } from './common.js';
 import type { PermissionMode } from './permissions.js';
 import type { SessionKey } from '../session/session-store.js';
-export type { SDKAssistantMessage, SDKResultSuccess, SDKResultError, SDKResultMessage, SDKPartialAssistantMessage, SDKCompactBoundaryMessage, SDKAPIRetryMessage, SDKHookStartedMessage, SDKHookProgressMessage, SDKHookResponseMessage, SDKTaskNotificationMessage, SDKTaskStartedMessage, SDKTaskProgressMessage, SDKTaskUpdatedMessage, SDKBackgroundTasksChangedMessage, SDKSessionStateChangedMessage, SDKSessionTitleChangedMessage, SDKFilesPersistedEvent, SDKElicitationCompleteMessage, SDKPromptSuggestionMessage, SDKCloudAgentEventMessage, SDKPermissionDenial, SDKToolNonExecutionKind, SDKToolResultMeta, } from '../protocol/index.js';
+export type { SDKAssistantMessage, SDKResultSuccess, SDKResultError, SDKResultMessage, SDKPartialAssistantMessage, SDKCompactBoundaryMessage, SDKAPIRetryMessage, SDKModelQueueStatusMessage, SDKControlRequestProgressMessage, SDKHookStartedMessage, SDKHookProgressMessage, SDKHookResponseMessage, SDKTaskNotificationMessage, SDKTaskStartedMessage, SDKTaskProgressMessage, SDKTaskUpdatedMessage, SDKBackgroundTasksChangedMessage, SDKSessionStateChangedMessage, SDKSessionTitleChangedMessage, SDKFilesPersistedEvent, SDKElicitationCompleteMessage, SDKPromptSuggestionMessage, SDKCloudAgentEventMessage, SDKMemoryGenerationMessage, SDKMemoryConsumptionMessage, SDKPermissionDenial, SDKToolNonExecutionKind, SDKToolResultMeta, } from '../protocol/index.js';
 export type SDKUserMessage = {
     type: 'user';
     message: MessageParam;
     parent_tool_use_id: string | null;
+    custom_context?: Record<string, string>;
     isSynthetic?: boolean;
     tool_use_result?: unknown;
     /** CLI-stamped display metadata for tool results that did not execute. */

package/dist/types/options.d.ts

@@ -8,7 +8,7 @@ import type { HookCallbackMatcher, HookEvent } from './hooks.js';
 import type { McpServerConfig, McpServerStatus, McpSetServersResult, OAuthToken } from './mcp.js';
 import type { SDKMessage, SDKUserMessage } from './messages.js';
 import type { Settings } from './settings.js';
-import type { SDKControlInterruptResponse, SDKControlInitializeResponse, SDKControlGetContextUsageResponse, SDKControlGenerateSessionTitleResponse, SDKControlAddDirectoriesResponse, SDKControlReloadPluginsResponse, StdoutMessage } from './control.js';
+import type { SDKControlInterruptResponse, SDKControlInitializeResponse, SDKControlGetContextUsageResponse, SDKControlGenerateSessionTitleResponse, AskSideQuestionOptions, SideQuestionResult, SDKControlAddDirectoriesResponse, SDKControlReloadPluginsResponse, StdoutMessage } from './control.js';
 import type { ModelPolicyProvider } from './model-policy-provider.js';
 import type { BYOKModelValidationInput, BYOKProviderInfo } from './byok.js';
 import type { RewindFilesResult, RewindResult, RewindScope } from './session.js';
@@ -17,6 +17,8 @@ import type { QueryTransportProviderOption } from '../core/query-transport.js';
 import type { PluginDetails } from './plugins.js';
 import type { SessionStore, SessionStoreFlush } from '../session/session-store.js';
 import type { ModelPromptPatches } from '../protocol/model-prompt-patches.js';
+import type { MemoryOptions } from './memory.js';
+import type { SDKGoalSnapshot, SDKGoalStatus } from '../protocol/control.js';
 export type { CanUseTool };
 export type { AuthOptions };
 export type ElicitationRequest = {
@@ -50,6 +52,15 @@ export type PromptResponse = {
 };
 export type SettingSource = 'user' | 'project' | 'local';
 export type QueryTransportOptions = QueryTransportProviderOption;
+/** Built-in code security capabilities. All switches default to false. */
+export type SecurityScanOptions = {
+    /** Run the static security check after supported file edits. */
+    l1StaticCheck?: boolean;
+    /** Allow lightweight repository security scans. */
+    l2LightweightScan?: boolean;
+    /** Allow deep repository security scans. */
+    l3DeepScan?: boolean;
+};
 export type Options = {
     /**
      * Optional controller for defining when the host ends the session. Calling
@@ -80,6 +91,18 @@ export type Options = {
      */
     auth?: InternalAuthOptions;
     additionalDirectories?: string[];
+    /**
+     * Opaque business identifiers forwarded to every local qodercli inference
+     * request unless a user message supplies its own `custom_context`.
+     *
+     * Backend-enforced limits are 1–8 string entries, keys up to 32 Unicode code
+     * points, values up to 128 Unicode code points, and at most 1024 UTF-8 bytes
+     * for the serialized JSON object. Do not include tokens, Service Account
+     * keys, email addresses, phone numbers, other credentials, or sensitive
+     * personal data. Backend acceptance requires Service Account authentication
+     * and a qoder VPC deployment.
+     */
+    customContext?: Record<string, string>;
     /**
      * @experimental
      * @unstable Cloud Agent runtime is experimental and may change without
@@ -132,6 +155,22 @@ export type Options = {
      * environment.
      */
     proxy?: string;
+    /**
+     * VPC private-deployment endpoint for the qodercli child process (CN
+     * deployments only).
+     *
+     * Accepts either a bare instance name (`acme`) or a full VPC domain
+     * (`acme.vpc.qoder.com.cn`, `acme-gateway.vpc.qoder.com.cn`,
+     * `acme-openapi.vpc.qoder.com.cn`). When set, the SDK writes this value to
+     * the `QODERCN_VPC_ENDPOINT` (CN) / `QODER_VPC_ENDPOINT` (Global)
+     * environment variable, which the CLI reads at highest priority — above any
+     * `vpcInstanceName` in `settings.json` — to derive its inference, OpenAPI,
+     * and base endpoints locally without remote endpoint election.
+     *
+     * VPC mode only activates in CN builds of the CLI; the value is ignored by
+     * Global builds.
+     */
+    vpcEndpoint?: string;
     env?: {
         [envVar: string]: string | undefined;
     };
@@ -161,6 +200,11 @@ export type Options = {
      */
     resumeDropsTurn?: string;
     hooks?: Partial<Record<HookEvent, HookCallbackMatcher[]>>;
+    /**
+     * Configure QoderCLI-owned memory generation and consumption for this query.
+     * Functions stay in the SDK process and are bridged through control requests.
+     */
+    memory?: MemoryOptions;
     onElicitation?: OnElicitation;
     /**
      * Called when the SDK detects that authentication has expired or
@@ -226,6 +270,11 @@ export type Options = {
     loadTimeoutMs?: number;
     sessionId?: string;
     settings?: string | Settings;
+    /**
+     * Enables built-in code security capabilities for this SDK session.
+     * Omitted switches are disabled. This option is authoritative when provided.
+     */
+    securityScan?: SecurityScanOptions;
     settingSources?: SettingSource[];
     stderr?: (data: string) => void;
     strictMcpConfig?: boolean;
@@ -338,6 +387,22 @@ export interface Query extends AsyncGenerator<SDKMessage, void> {
      * eligible foreground executions are targeted.
      */
     backgroundTasks(toolUseId?: string): Promise<boolean>;
+    /**
+     * Create, redirect, transition, or re-budget the session goal. Omitted
+     * fields are left unchanged; `creditsBudget: null` explicitly clears the
+     * budget. Setting `status: 'active'` while the session is idle starts the
+     * goal loop. Requires the CLI `goal_v1` capability. Only present on the
+     * local CLI transport; absent on cloud-agent queries.
+     */
+    setGoal?(params: {
+        objective?: string;
+        status?: SDKGoalStatus;
+        creditsBudget?: number | null;
+    }): Promise<SDKGoalSnapshot | null>;
+    /** Read the current goal, or null when the session has none. */
+    getGoal?(): Promise<SDKGoalSnapshot | null>;
+    /** Clear the session goal; returns whether a goal was cleared. */
+    clearGoal?(): Promise<boolean>;
     setPermissionMode(mode: PermissionMode): Promise<void>;
     setModel(model?: string): Promise<void>;
     /**
@@ -358,6 +423,11 @@ export interface Query extends AsyncGenerator<SDKMessage, void> {
     generateSessionTitle(description: string, options?: {
         persist?: boolean;
     }): Promise<SDKControlGenerateSessionTitleResponse['title']>;
+    /**
+     * Ask a one-off question using the current conversation context without
+     * interrupting or mutating the main agent turn.
+     */
+    askSideQuestion?(question: string, options?: AskSideQuestionOptions): Promise<SideQuestionResult | null>;
     /**
      * Add directories to the running session's workspace context.
      *
@@ -417,6 +487,10 @@ export interface Query extends AsyncGenerator<SDKMessage, void> {
         dryRun?: boolean;
     }): Promise<RewindResult>;
     seedReadState(path: string, mtime: number): Promise<void>;
+    /** Wait until pending TurnComplete memory generation has finished. */
+    flushMemory(): Promise<void>;
+    /** Reload configured memory consumption files without changing config. */
+    refreshMemory(): Promise<void>;
     /**
      * 主动驱动 MCP OAuth：拉起 OAuth 流程，返回授权 URL 让 host 引导用户跳转。
      *

package/dist/types/plugins.d.ts

@@ -1,4 +1,15 @@
 import type { PluginInfo } from '../protocol/common.js';
+/** Plugin installation scopes that can be changed through the CLI. */
+export type PluginScope = 'user' | 'project' | 'local';
+export type PluginToggleOptions = {
+    /** Directory used to resolve project and local plugin state. */
+    cwd?: string;
+    /** Omit to let qodercli infer the installed plugin's scope. */
+    scope?: PluginScope;
+    /** Optional qodercli executable or qoder Worker runtime entry override. */
+    cliPath?: string;
+    env?: Record<string, string>;
+};
 export type PluginResources = {
     skills: {
         name: string;
@@ -97,6 +108,7 @@ export type PluginValidationReport = {
     resources?: PluginResources;
 };
 export type ValidatePluginOptions = {
+    /** Optional qodercli executable or qoder Worker runtime entry override. */
     cliPath?: string;
     env?: Record<string, string>;
     signal?: AbortSignal;

package/dist/types/session.d.ts

@@ -36,6 +36,12 @@ export type SessionMessage = {
     isApiErrorMessage?: true;
     /** CLI-stamped display metadata for tool results that did not execute. */
     tool_result_meta?: SDKToolResultMeta[];
+    /**
+     * Structured tool result persisted by qodercli alongside a user
+     * `tool_result` message. When one transcript entry contains multiple
+     * `tool_result` blocks, this is an array aligned with those blocks by index.
+     */
+    tool_use_result?: unknown;
     /**
      * ISO 8601 timestamp of when this transcript entry was written to the
      * jsonl file. Mirrors the on-disk `timestamp` field. Optional because

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qoder-ai/qoder-agent-sdk",
-  "version": "1.0.23",
+  "version": "1.0.25",
   "description": "TypeScript SDK for building Qoder-powered coding agents.",
   "type": "module",
   "main": "dist/index.js",
@@ -50,7 +50,7 @@
   "peerDependencies": {
     "zod": "^3.25.0 || ^4.0.0"
   },
-  "qoderCliVersion": "1.1.23",
+  "qoderCliVersion": "1.1.26",
   "qoderSdkBrand": "global",
   "license": "SEE LICENSE IN LICENSE"
 }