@opencow-ai/opencow-agent-sdk 0.4.26 → 0.4.28

package/dist/constants/oauth.d.ts

@@ -27,13 +27,5 @@ type OauthConfig = {
     MCP_PROXY_URL: string;
     MCP_PROXY_PATH: string;
 };
-/**
- * Client ID Metadata Document URL for MCP OAuth (CIMD / SEP-991).
- * When an MCP auth server advertises client_id_metadata_document_supported: true,
- * Claude Code uses this URL as its client_id instead of Dynamic Client Registration.
- * The URL must point to a JSON document hosted by Anthropic.
- * See: https://datatracker.ietf.org/doc/html/draft-ietf-oauth-client-id-metadata-document-00
- */
-export declare const MCP_CLIENT_METADATA_URL = "https://claude.ai/oauth/claude-code-client-metadata";
 export declare function getOauthConfig(): OauthConfig;
 export {};

package/dist/controller/compact/compact.d.ts

@@ -3,7 +3,7 @@ import type { QuerySource } from '../../constants/querySource.js';
 import type { CanUseToolFn } from '../../types/canUseTool.js';
 import type { ToolUseContext } from '../../Tool.js';
 import type { AgentId } from '../../types/ids.js';
-import type { AssistantMessage, AttachmentMessage, HookResultMessage, Message, PartialCompactDirection, SystemCompactBoundaryMessage, SystemMessage, UserMessage } from '../../types/message.js';
+import type { AssistantMessage, AttachmentMessage, HookResultMessage, Message, PartialCompactDirection, SystemCompactBoundaryMessage, UserMessage } from '../../types/message.js';
 import { type CacheSafeParams } from '../../session/forkedAgent.js';
 import { getTokenUsage } from '../../session/tokens.js';
 export declare const POST_COMPACT_MAX_FILES_TO_RESTORE = 5;
@@ -53,7 +53,7 @@ export declare const ERROR_MESSAGE_PROMPT_TOO_LONG = "Conversation too long. Pre
 export declare const ERROR_MESSAGE_USER_ABORT = "API Error: Request was aborted.";
 export declare const ERROR_MESSAGE_INCOMPLETE_RESPONSE = "Compaction interrupted \u00B7 This may be due to network issues \u2014 please try again.";
 export interface CompactionResult {
-    boundaryMarker: SystemMessage;
+    boundaryMarker: SystemCompactBoundaryMessage;
     summaryMessages: UserMessage[];
     attachments: AttachmentMessage[];
     hookResults: HookResultMessage[];
@@ -82,6 +82,12 @@ export type RecompactionInfo = {
  * Order: boundaryMarker, summaryMessages, messagesToKeep, attachments, hookResults
  */
 export declare function buildPostCompactMessages(result: CompactionResult): Message[];
+/**
+ * Attach the complete post-compact context to the public boundary metadata.
+ * The snapshot is built before the boundary is annotated so its embedded copy
+ * cannot reference itself.
+ */
+export declare function attachContextSnapshot(result: CompactionResult): CompactionResult;
 /**
  * Annotate a compact boundary with relink metadata for messagesToKeep.
  * Preserved messages keep their original parentUuids on disk (dedup-skipped);

package/dist/controller/dispatch/toolHooks.d.ts

@@ -13,9 +13,10 @@ export declare function runPostToolUseFailureHooks<Input extends AnyObject>(tool
 /**
  * Resolve a PreToolUse hook's permission result into a final PermissionDecision.
  *
- * Encapsulates the invariant that hook 'allow' does NOT bypass settings.json
- * deny/ask rules — checkRuleBasedPermissions still applies (inc-4788 analog).
- * Also handles the requiresUserInteraction/requireCanUseTool guards and the
+ * Encapsulates the invariant that hook 'allow' is advisory: the host's
+ * canUseTool still decides, so a hook can never bypass the host's gate nor
+ * settings.json deny/ask rules. The only exemption is an interactive tool whose
+ * answers were supplied by the hook itself (updatedInput). Also handles the
  * 'ask' forceDecision passthrough.
  *
  * Shared by toolExecution.ts (main query loop) and REPLTool/toolWrappers.ts

package/dist/controller/loop.d.ts

@@ -28,7 +28,8 @@ export declare function adjustParamsForNonStreaming<T extends {
 export type Options = {
     /**
      * 内部：由 replayStreamOnTransportError 置位。为 true 时，读流阶段的可重放传输错误
-     * （且尚无完整消息送出）作为异常抛给调用方重放，而不是转成 assistant 错误消息。
+     * （且尚无完整消息送出）优先作为异常抛给调用方重放，而不是先走 non-streaming
+     * fallback 或转成 assistant 错误消息；预算用尽后该标记为 false，恢复原路径。
      */
     streamReplayEscape?: boolean;
     getToolPermissionContext: () => Promise<ToolPermissionContext>;

package/dist/entrypoints/sdk/controlSchemas.d.ts

@@ -63,6 +63,7 @@ export declare const SDKControlInitializeRequestSchema: () => z.ZodObject<{
             command: z.ZodString;
             args: z.ZodOptional<z.ZodArray<z.ZodString>>;
             env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            cwd: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>, z.ZodObject<{
             type: z.ZodLiteral<"sse">;
             url: z.ZodString;
@@ -298,6 +299,7 @@ export declare const SDKControlMcpStatusResponseSchema: () => z.ZodObject<{
             command: z.ZodString;
             args: z.ZodOptional<z.ZodArray<z.ZodString>>;
             env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            cwd: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>, z.ZodObject<{
             type: z.ZodLiteral<"sse">;
             url: z.ZodString;
@@ -948,6 +950,7 @@ export declare const SDKControlMcpSetServersRequestSchema: () => z.ZodObject<{
         command: z.ZodString;
         args: z.ZodOptional<z.ZodArray<z.ZodString>>;
         env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        cwd: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"sse">;
         url: z.ZodString;
@@ -1004,6 +1007,7 @@ export declare const SDKControlReloadPluginsResponseSchema: () => z.ZodObject<{
             command: z.ZodString;
             args: z.ZodOptional<z.ZodArray<z.ZodString>>;
             env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            cwd: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>, z.ZodObject<{
             type: z.ZodLiteral<"sse">;
             url: z.ZodString;
@@ -1252,6 +1256,7 @@ export declare const SDKControlRequestInnerSchema: () => z.ZodUnion<readonly [z.
             command: z.ZodString;
             args: z.ZodOptional<z.ZodArray<z.ZodString>>;
             env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            cwd: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>, z.ZodObject<{
             type: z.ZodLiteral<"sse">;
             url: z.ZodString;
@@ -1822,6 +1827,7 @@ export declare const SDKControlRequestInnerSchema: () => z.ZodUnion<readonly [z.
         command: z.ZodString;
         args: z.ZodOptional<z.ZodArray<z.ZodString>>;
         env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        cwd: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"sse">;
         url: z.ZodString;
@@ -2020,6 +2026,7 @@ export declare const SDKControlRequestSchema: () => z.ZodObject<{
                 command: z.ZodString;
                 args: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+                cwd: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>, z.ZodObject<{
                 type: z.ZodLiteral<"sse">;
                 url: z.ZodString;
@@ -2590,6 +2597,7 @@ export declare const SDKControlRequestSchema: () => z.ZodObject<{
             command: z.ZodString;
             args: z.ZodOptional<z.ZodArray<z.ZodString>>;
             env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            cwd: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>, z.ZodObject<{
             type: z.ZodLiteral<"sse">;
             url: z.ZodString;
@@ -2798,6 +2806,7 @@ export declare const ControlErrorResponseSchema: () => z.ZodObject<{
                     command: z.ZodString;
                     args: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+                    cwd: z.ZodOptional<z.ZodString>;
                 }, z.core.$strip>, z.ZodObject<{
                     type: z.ZodLiteral<"sse">;
                     url: z.ZodString;
@@ -3368,6 +3377,7 @@ export declare const ControlErrorResponseSchema: () => z.ZodObject<{
                 command: z.ZodString;
                 args: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+                cwd: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>, z.ZodObject<{
                 type: z.ZodLiteral<"sse">;
                 url: z.ZodString;
@@ -3578,6 +3588,7 @@ export declare const SDKControlResponseSchema: () => z.ZodObject<{
                         command: z.ZodString;
                         args: z.ZodOptional<z.ZodArray<z.ZodString>>;
                         env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+                        cwd: z.ZodOptional<z.ZodString>;
                     }, z.core.$strip>, z.ZodObject<{
                         type: z.ZodLiteral<"sse">;
                         url: z.ZodString;
@@ -4148,6 +4159,7 @@ export declare const SDKControlResponseSchema: () => z.ZodObject<{
                     command: z.ZodString;
                     args: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+                    cwd: z.ZodOptional<z.ZodString>;
                 }, z.core.$strip>, z.ZodObject<{
                     type: z.ZodLiteral<"sse">;
                     url: z.ZodString;
@@ -4377,6 +4389,11 @@ export declare const StdoutMessageSchema: () => z.ZodUnion<readonly [z.ZodUnion<
         }>;
         pre_tokens: z.ZodNumber;
         post_tokens: z.ZodOptional<z.ZodNumber>;
+        context_snapshot: z.ZodOptional<z.ZodObject<{
+            schemaVersion: z.ZodLiteral<1>;
+            messages: z.ZodArray<z.ZodUnknown>;
+            baselineTokens: z.ZodNumber;
+        }, z.core.$strip>>;
         preserved_segment: z.ZodOptional<z.ZodObject<{
             head_uuid: z.ZodString;
             anchor_uuid: z.ZodString;
@@ -4801,6 +4818,7 @@ export declare const StdoutMessageSchema: () => z.ZodUnion<readonly [z.ZodUnion<
                         command: z.ZodString;
                         args: z.ZodOptional<z.ZodArray<z.ZodString>>;
                         env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+                        cwd: z.ZodOptional<z.ZodString>;
                     }, z.core.$strip>, z.ZodObject<{
                         type: z.ZodLiteral<"sse">;
                         url: z.ZodString;
@@ -5371,6 +5389,7 @@ export declare const StdoutMessageSchema: () => z.ZodUnion<readonly [z.ZodUnion<
                     command: z.ZodString;
                     args: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+                    cwd: z.ZodOptional<z.ZodString>;
                 }, z.core.$strip>, z.ZodObject<{
                     type: z.ZodLiteral<"sse">;
                     url: z.ZodString;
@@ -5571,6 +5590,7 @@ export declare const StdoutMessageSchema: () => z.ZodUnion<readonly [z.ZodUnion<
                 command: z.ZodString;
                 args: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+                cwd: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>, z.ZodObject<{
                 type: z.ZodLiteral<"sse">;
                 url: z.ZodString;
@@ -6141,6 +6161,7 @@ export declare const StdoutMessageSchema: () => z.ZodUnion<readonly [z.ZodUnion<
             command: z.ZodString;
             args: z.ZodOptional<z.ZodArray<z.ZodString>>;
             env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            cwd: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>, z.ZodObject<{
             type: z.ZodLiteral<"sse">;
             url: z.ZodString;
@@ -6359,6 +6380,7 @@ export declare const StdinMessageSchema: () => z.ZodUnion<readonly [z.ZodObject<
                 command: z.ZodString;
                 args: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+                cwd: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>, z.ZodObject<{
                 type: z.ZodLiteral<"sse">;
                 url: z.ZodString;
@@ -6929,6 +6951,7 @@ export declare const StdinMessageSchema: () => z.ZodUnion<readonly [z.ZodObject<
             command: z.ZodString;
             args: z.ZodOptional<z.ZodArray<z.ZodString>>;
             env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            cwd: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>, z.ZodObject<{
             type: z.ZodLiteral<"sse">;
             url: z.ZodString;
@@ -7137,6 +7160,7 @@ export declare const StdinMessageSchema: () => z.ZodUnion<readonly [z.ZodObject<
                         command: z.ZodString;
                         args: z.ZodOptional<z.ZodArray<z.ZodString>>;
                         env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+                        cwd: z.ZodOptional<z.ZodString>;
                     }, z.core.$strip>, z.ZodObject<{
                         type: z.ZodLiteral<"sse">;
                         url: z.ZodString;
@@ -7707,6 +7731,7 @@ export declare const StdinMessageSchema: () => z.ZodUnion<readonly [z.ZodObject<
                     command: z.ZodString;
                     args: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+                    cwd: z.ZodOptional<z.ZodString>;
                 }, z.core.$strip>, z.ZodObject<{
                     type: z.ZodLiteral<"sse">;
                     url: z.ZodString;

package/dist/entrypoints/sdk/coreSchemas.d.ts

@@ -65,6 +65,7 @@ export declare const McpStdioServerConfigSchema: () => z.ZodObject<{
     command: z.ZodString;
     args: z.ZodOptional<z.ZodArray<z.ZodString>>;
     env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    cwd: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const McpSSEServerConfigSchema: () => z.ZodObject<{
     type: z.ZodLiteral<"sse">;
@@ -85,6 +86,7 @@ export declare const McpServerConfigForProcessTransportSchema: () => z.ZodUnion<
     command: z.ZodString;
     args: z.ZodOptional<z.ZodArray<z.ZodString>>;
     env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    cwd: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"sse">;
     url: z.ZodString;
@@ -107,6 +109,7 @@ export declare const McpServerStatusConfigSchema: () => z.ZodUnion<readonly [z.Z
     command: z.ZodString;
     args: z.ZodOptional<z.ZodArray<z.ZodString>>;
     env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    cwd: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"sse">;
     url: z.ZodString;
@@ -142,6 +145,7 @@ export declare const McpServerStatusSchema: () => z.ZodObject<{
         command: z.ZodString;
         args: z.ZodOptional<z.ZodArray<z.ZodString>>;
         env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        cwd: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"sse">;
         url: z.ZodString;
@@ -2054,6 +2058,7 @@ export declare const AgentMcpServerSpecSchema: () => z.ZodUnion<readonly [z.ZodS
     command: z.ZodString;
     args: z.ZodOptional<z.ZodArray<z.ZodString>>;
     env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    cwd: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"sse">;
     url: z.ZodString;
@@ -2077,6 +2082,7 @@ export declare const AgentDefinitionSchema: () => z.ZodObject<{
         command: z.ZodString;
         args: z.ZodOptional<z.ZodArray<z.ZodString>>;
         env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        cwd: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"sse">;
         url: z.ZodString;
@@ -2503,6 +2509,11 @@ export declare const SDKCompactBoundaryMessageSchema: () => z.ZodObject<{
         }>;
         pre_tokens: z.ZodNumber;
         post_tokens: z.ZodOptional<z.ZodNumber>;
+        context_snapshot: z.ZodOptional<z.ZodObject<{
+            schemaVersion: z.ZodLiteral<1>;
+            messages: z.ZodArray<z.ZodUnknown>;
+            baselineTokens: z.ZodNumber;
+        }, z.core.$strip>>;
         preserved_segment: z.ZodOptional<z.ZodObject<{
             head_uuid: z.ZodString;
             anchor_uuid: z.ZodString;
@@ -2912,6 +2923,11 @@ export declare const SDKMessageSchema: () => z.ZodUnion<readonly [z.ZodObject<{
         }>;
         pre_tokens: z.ZodNumber;
         post_tokens: z.ZodOptional<z.ZodNumber>;
+        context_snapshot: z.ZodOptional<z.ZodObject<{
+            schemaVersion: z.ZodLiteral<1>;
+            messages: z.ZodArray<z.ZodUnknown>;
+            baselineTokens: z.ZodNumber;
+        }, z.core.$strip>>;
         preserved_segment: z.ZodOptional<z.ZodObject<{
             head_uuid: z.ZodString;
             anchor_uuid: z.ZodString;

package/dist/entrypoints/sdk/runtimeTypes.d.ts

@@ -1,6 +1,8 @@
 import type { ChildProcessWithoutNullStreams } from 'node:child_process';
 import type { ModelProviders } from '../../providers/shared/routing.js';
 import type { UploadMediaFn } from '../../types/toolRuntime.js';
+import type { SDKContextSnapshot } from '../../types/contextSnapshot.js';
+export type { SDKContextSnapshot } from '../../types/contextSnapshot.js';
 export type { ModelProviders, ModelProviderConfig, } from '../../providers/shared/routing.js';
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { CallToolResult, ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
@@ -62,6 +64,8 @@ export type McpStdioServerConfig = {
     command: string;
     args?: string[];
     env?: Record<string, string>;
+    /** Working directory the server process is spawned in. */
+    cwd?: string;
 };
 export type McpSSEServerConfig = {
     type: 'sse';
@@ -159,6 +163,12 @@ export type SdkManagedPlugin = {
 export type SdkPluginSnapshot = {
     revision: string;
     plugins: readonly SdkManagedPlugin[];
+    /**
+     * Host-defined `${NAME}` values substituted into managed plugin skill and
+     * command bodies when they are invoked (e.g. host-specific directories).
+     * Names must match `[A-Z][A-Z0-9_]*`; unknown placeholders stay literal.
+     */
+    contentVariables?: Readonly<Record<string, string>>;
 };
 export type SdkPluginDiagnostic = {
     severity: 'warning' | 'error';
@@ -519,6 +529,17 @@ export type Options = {
      */
     spawnClaudeCodeProcess?: (opts: SpawnOptions) => SpawnedProcess;
     initialMessages?: unknown[];
+    /**
+     * Opaque canonical post-compact context returned by a previous
+     * `compact_metadata.context_snapshot`. Hosts persist it unchanged and pass
+     * it back after restart. When both this and `initialMessages` are provided,
+     * the snapshot is restored first and `initialMessages` are appended as the
+     * tail (normally events recorded after the snapshot).
+     *
+     * Invalid snapshots throw instead of silently falling back to a smaller
+     * context.
+     */
+    initialContextSnapshot?: SDKContextSnapshot;
     /**
      * Controls whether the SDK performs ANY filesystem reads of its own
      * during session execution.

package/dist/providers/shared/retry.d.ts

@@ -10,7 +10,19 @@ export declare const BASE_DELAY_MS = 500;
  * 只认传输特征（cause 带系统错误码或固定文案），普通 TypeError 仍按程序错误处理。
  */
 export declare function wrapBodyTransportError(error: unknown): unknown;
-/** 读流阶段的传输中断（对端关闭、socket 断开、空闲看门狗中止）可以整条请求重放；其余不行。 */
+/**
+ * 已收到 message_start、但流在任何完整 content block / stop_reason 之前结束。
+ * 这类空流可能由代理瞬断造成，且尚未提交任何模型输出，可以安全地整条请求重放。
+ * 没有 message_start 的 200 空响应不归入此类：它更像网关不兼容 SSE，保留
+ * non-streaming fallback（见 controller/loop.ts）。
+ *
+ * 重放前可能已经向消费方 yield 过半截 stream_event。消费方必须在新的
+ * message_start 到达时重置未完成的流式内容；SDK 不保证撤回已经展示的部分。
+ */
+export declare class EmptyStreamError extends Error {
+    constructor(message?: string);
+}
+/** 读流阶段的传输中断（对端关闭、socket 断开、空闲看门狗中止、空流）可以整条请求重放；其余不行。 */
 export declare function toReplayableStreamError(error: unknown): APIConnectionError | null;
 /**
  * 流式响应读到一半断开、且还没有任何完整消息送出时，整个流式请求重放。