@opencow-ai/opencow-agent-sdk 0.4.7 → 0.4.8

package/dist/constants/envVars.d.ts

@@ -106,6 +106,7 @@ export declare const ENV_VARS: {
     readonly ENABLE_TASKS: EnvVarSpec;
     readonly ENABLE_TELEMETRY: EnvVarSpec;
     readonly ENABLE_TOKEN_USAGE_ATTACHMENT: EnvVarSpec;
+    readonly ENABLE_TOOL_SEARCH: EnvVarSpec;
     readonly ENABLE_XAA: EnvVarSpec;
     readonly ENHANCED_TELEMETRY_BETA: EnvVarSpec;
     readonly ENTRYPOINT: EnvVarSpec;

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

@@ -2,7 +2,8 @@ import type { QuerySource } from '../../constants/querySource.js';
 import type { ToolRuntimeContext } from '../../types/toolRuntime.js';
 import type { Message } from '../../types/message.js';
 import type { CacheSafeParams } from '../../session/forkedAgent.js';
-import { type CompactionResult } from './compact.js';
+import { type CompactionResult, compactConversation } from './compact.js';
+import { trySessionMemoryCompaction } from './sessionMemoryCompact.js';
 export declare function getEffectiveContextWindowSize(model: string, opts?: {
     contextWindow?: number;
     maxOutputTokens?: number;
@@ -41,3 +42,18 @@ export declare function autoCompactIfNeeded(messages: Message[], toolUseContext:
     compactionResult?: CompactionResult;
     consecutiveFailures?: number;
 }>;
+/**
+ * host 主动触发的手动压缩（用户的 `/compact`）。与 autoCompactIfNeeded 不同：
+ * 不看 token 阈值——总是立即压缩；并以非自动方式运行（isAutoCompact=false），
+ * 从而尊重自定义指令。其余策略与自动压缩一致：无指令时先试 session-memory 压缩
+ * （它不支持自定义指令），不可用再退回完整摘要压缩。
+ *
+ * deps 可注入，便于在不驱动真实摘要模型的前提下测试编排逻辑（沿用本仓 QueryDeps 思路）。
+ */
+export declare function manualCompact(messages: Message[], toolUseContext: ToolRuntimeContext, cacheSafeParams: CacheSafeParams, instructions?: string, deps?: {
+    compactConversation: typeof compactConversation;
+    trySessionMemoryCompaction: typeof trySessionMemoryCompaction;
+}): Promise<{
+    wasCompacted: boolean;
+    compactionResult?: CompactionResult;
+}>;

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

@@ -0,0 +1,52 @@
+/**
+ * Reactive（撞墙后）上下文压缩 —— 413 "Prompt is too long" / 媒体过大的兜底。
+ *
+ * 主动压缩（autoCompact）在每轮开头按 token 阈值预判；但大 tool 输出能在同一 agent
+ * loop 内、两次检查之间把上下文顶爆 → 下一次 API 调用直接被上游拒（413/400
+ * "prompt is too long"）。窗口估错（后端虚报 / openai 模型退回 200k 默认）时主动压缩
+ * 更是抓不住。本模块在 query loop 的流式阶段「withhold」住这类可恢复错误，turn 结束后由
+ * tryReactiveCompact 压缩 + 重试（单发防自旋：本 turn 试过一次就放弃，让错误浮现）。
+ *
+ * 复用 compactConversation（同主动压缩的摘要引擎，会 strip 图片 + 摘要旧消息），所以
+ * 媒体过大错误压缩后也能在重试时消失。query.ts 已接好 withhold/recovery/retry 状态机，
+ * 本模块只负责：判定可恢复 + 执行一次压缩。
+ */
+import type { AssistantMessage, Message } from '../../types/message.js';
+import type { QuerySource } from '../../constants/querySource.js';
+import type { CacheSafeParams } from '../../session/forkedAgent.js';
+import { type CompactionResult, compactConversation } from './compact.js';
+type WithholdableMessage = AssistantMessage | {
+    type?: string;
+} | null | undefined;
+/**
+ * Reactive 压缩是否启用。沿用用户的自动压缩开关：关掉自动压缩 = 连兜底也不做
+ * （尊重 DISABLE_AUTO_COMPACT / autoCompactEnabled=false 的「不要任何自动行为」语义）。
+ */
+export declare function isReactiveCompactEnabled(): boolean;
+/** 流式阶段：这条消息是否是可兜底的 prompt-too-long（应 withhold 等待恢复）。 */
+export declare function isWithheldPromptTooLong(message: WithholdableMessage): boolean;
+/** 流式阶段：这条消息是否是可兜底的媒体过大错误（压缩 strip 图片后重试可恢复）。 */
+export declare function isWithheldMediaSizeError(message: WithholdableMessage): boolean;
+export interface TryReactiveCompactParams {
+    /** 本 turn 是否已经 reactive 压缩过一次（单发防自旋）。 */
+    hasAttempted: boolean;
+    querySource: QuerySource | undefined;
+    aborted: boolean;
+    messages: Message[];
+    cacheSafeParams: CacheSafeParams;
+}
+interface TryReactiveCompactDeps {
+    compactConversation: typeof compactConversation;
+    isReactiveCompactEnabled: typeof isReactiveCompactEnabled;
+}
+/**
+ * 撞墙后压缩一次并返回结果供 query loop 重试；不可恢复时返回 null（错误浮现）。
+ *
+ * 单发：hasAttempted=true（本 turn 已试过）或已 abort 直接 null，避免「压缩→仍超→
+ * 再压缩」死循环。复用 compactConversation：suppress 提问、无自定义指令、isAutoCompact
+ * 语义（它会 strip 图片 + 摘要旧消息，使 413/媒体过大在重试时消失）。
+ *
+ * deps 可注入，便于在不驱动真实摘要模型的前提下测试编排逻辑（沿用本仓 manualCompact 思路）。
+ */
+export declare function tryReactiveCompact(params: TryReactiveCompactParams, deps?: TryReactiveCompactDeps): Promise<CompactionResult | null>;
+export {};

package/dist/controller/query/deps.d.ts

@@ -1,10 +1,11 @@
 import { queryModelWithStreaming } from '../loop.js';
-import { autoCompactIfNeeded } from '../compact/autoCompact.js';
+import { autoCompactIfNeeded, manualCompact } from '../compact/autoCompact.js';
 import { microcompactMessages } from '../compact/microCompact.js';
 export type QueryDeps = {
     callModel: typeof queryModelWithStreaming;
     microcompact: typeof microcompactMessages;
     autocompact: typeof autoCompactIfNeeded;
+    manualCompact: typeof manualCompact;
     uuid: () => string;
 };
 export declare function productionDeps(): QueryDeps;

package/dist/controller/toolSearch.d.ts

@@ -46,6 +46,17 @@ export declare function getToolSearchMode(): ToolSearchMode;
  */
 export declare function modelSupportsToolReference(model: string): boolean;
 export declare function isToolSearchEnabledOptimistic(): boolean;
+/**
+ * Whether the current request may use the NATIVE tool-search wire shapes:
+ * `tool_reference` content blocks + `defer_loading: true` on tool
+ * definitions + the tool-search beta header. These are Anthropic beta
+ * shapes — only the direct first-party Anthropic endpoint reliably
+ * accepts them. Proxies (custom ANTHROPIC_BASE_URL) and the OpenAI /
+ * Gemini families get the client-side EMULATION instead: ToolSearchTool
+ * results carry plain-text `<discovered-tool name="X" />` markers and
+ * discovered tools are sent with their FULL schema (no defer_loading).
+ */
+export declare function isNativeToolReferenceWire(): boolean;
 /**
  * Check if ToolSearchTool is available in the provided tools list.
  * If ToolSearchTool is not available (e.g., disallowed via disallowedTools),
@@ -81,6 +92,15 @@ export declare function isToolSearchEnabled(model: string, tools: Tools, getTool
  * tool_reference is a beta feature not in the SDK types, so we need runtime checks.
  */
 export declare function isToolReferenceBlock(obj: unknown): boolean;
+/**
+ * Marker emitted by ToolSearchTool under the emulation wire (non-native
+ * providers). One line per discovered tool. Kept attribute-style so a
+ * model quoting it verbatim in prose is unlikely to collide.
+ * Emitter lives in ToolSearchTool.ts (mapToolResultToToolResultBlockParam)
+ * — keep the two in sync. Has the `g` flag for matchAll — do NOT call
+ * .test()/.exec() on this export (stateful lastIndex).
+ */
+export declare const DISCOVERED_TOOL_MARKER_RE: RegExp;
 /**
  * Extract tool names from tool_reference blocks in message history.
  *

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

@@ -4376,6 +4376,7 @@ export declare const StdoutMessageSchema: () => z.ZodUnion<readonly [z.ZodUnion<
             auto: "auto";
         }>;
         pre_tokens: z.ZodNumber;
+        post_tokens: z.ZodOptional<z.ZodNumber>;
         preserved_segment: z.ZodOptional<z.ZodObject<{
             head_uuid: z.ZodString;
             anchor_uuid: z.ZodString;

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

@@ -2502,6 +2502,7 @@ export declare const SDKCompactBoundaryMessageSchema: () => z.ZodObject<{
             auto: "auto";
         }>;
         pre_tokens: z.ZodNumber;
+        post_tokens: z.ZodOptional<z.ZodNumber>;
         preserved_segment: z.ZodOptional<z.ZodObject<{
             head_uuid: z.ZodString;
             anchor_uuid: z.ZodString;
@@ -2910,6 +2911,7 @@ export declare const SDKMessageSchema: () => z.ZodUnion<readonly [z.ZodObject<{
             auto: "auto";
         }>;
         pre_tokens: z.ZodNumber;
+        post_tokens: z.ZodOptional<z.ZodNumber>;
         preserved_segment: z.ZodOptional<z.ZodObject<{
             head_uuid: z.ZodString;
             anchor_uuid: z.ZodString;

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

@@ -160,6 +160,14 @@ export type Options = {
      * Values < 10_000 or > 5_000_000 are dropped + warn-logged (table fallback).
      */
     contextWindow?: number;
+    /**
+     * 本回合手动压缩上下文（对应 host 的 /compact）。设置后 SDK 复用 auto-compact
+     * 机制（isAutoCompact=false + 这些指令）压缩当前消息、发出 system/compact_boundary，
+     * 随后结束本回合而不调用模型。单次信号——仅作用于携带它的那次 query()。
+     */
+    compact?: {
+        instructions?: string;
+    };
     includePartialMessages?: boolean;
     replayUserMessages?: boolean;
     permissionMode?: string;
@@ -228,6 +236,17 @@ export type Options = {
      */
     agents?: readonly unknown[];
     disallowedTools?: string[];
+    /**
+     * Tool names hidden from sub-agents (Agent/Task spawns) only — the main
+     * loop keeps them. Use this for MCP tools a sub-agent must not see (e.g. an
+     * interactive form/question capability): native UI tools like AskUserQuestion
+     * and EnterPlanMode are ALREADY excluded from every sub-agent, but MCP tools
+     * are not, so list them here. Matched with the same rules as `disallowedTools`,
+     * so MCP server-prefix (`mcp__server`) and wildcard (`mcp__server__*`) work.
+     * Unlike `disallowedTools` (a session-wide deny), this does NOT affect the
+     * main conversation.
+     */
+    subagentDisallowedTools?: string[];
     hooks?: Partial<Record<HookEvent, HookCallbackMatcher[]>>;
     /**
      * Pre-execute lifecycle hook. Invoked SYNCHRONOUSLY (the SDK awaits the

package/dist/permissions/permissions.d.ts

@@ -19,6 +19,21 @@ export declare function getAllowRules(context: ToolPermissionContext): Permissio
  */
 export declare function createPermissionRequestMessage(toolName: string, decisionReason?: PermissionDecisionReason): string;
 export declare function getDenyRules(context: ToolPermissionContext): PermissionRule[];
+/**
+ * 把禁用工具名烘焙进权限上下文,作为 session 级 deny 规则。SDK 模式借此让
+ * Options.disallowedTools 经由共享的 deny 规则过滤,作用到每一处工具池组装——
+ * 主循环、子代理、fork。子代理会从它继承的权限上下文重建自己的工具池,所以仅在
+ * 主池上事后过滤的名字,否则会泄漏进子代理(并能通过 ToolSearch 被检索到)。
+ * 与 CLI 把 --disallowedTools 路由进 alwaysDenyRules 的做法一致。
+ */
+export declare function denySessionTools(context: ToolPermissionContext, toolNames: readonly string[] | undefined): ToolPermissionContext;
+/**
+ * 过滤掉「仅对子代理隐藏」的工具(Options.subagentDisallowedTools)。复用与
+ * disallowedTools 同一套 deny 规则匹配,因此 MCP server 前缀('mcp__server')和
+ * 通配符('mcp__server__*')都能命中整组工具——不像裸 `Set.has(tool.name)` 只认精确全名。
+ * 在每个子代理工具池组装后调用(runAgent),主循环不调用,故对主循环无影响。
+ */
+export declare function filterSubagentDisallowedTools<T extends Pick<ToolRuntime, 'name' | 'mcpInfo'>>(tools: readonly T[], subagentDisallowedTools: readonly string[] | undefined): readonly T[];
 export declare function getAskRules(context: ToolPermissionContext): PermissionRule[];
 /**
  * Check if the entire tool is listed in the always allow rules

package/dist/providers/codex/shim.d.ts

@@ -125,6 +125,14 @@ export declare function performCodexRequest(options: {
     /** Host-provided Responses-protocol-specific fields (merged into body). */
     providerSpecific?: ResponsesProviderSpecific;
 }): Promise<Response>;
+/**
+ * 上游 `response.failed` 的错误若是「prompt 太长 / 上下文超限」，必须用非重试态 400 抛出。
+ * 否则 shouldRetry 把它当 5xx 服务端错误重试 MAX_RETRIES 次——同样超长的 prompt 原样重发
+ * 必然再失败，纯属浪费；且要等重试耗尽才轮到 query loop 的 reactive 压缩。400 让它即时浮现，
+ * 第一次就触发一次压缩重试（formatAPIError 仍按消息归一为 PROMPT_TOO_LONG_ERROR_MESSAGE，
+ * reactive 据此识别）。其余失败保持 500（可能是真·瞬时服务端错误，该重试）。
+ */
+export declare function codexFailureStatus(errorMessage: string): number;
 export declare function collectCodexCompletedResponse(response: Response): Promise<Record<string, any>>;
 export declare function codexStreamToAnthropic(response: Response, model: string): AsyncGenerator<AnthropicStreamEvent>;
 export declare function convertCodexResponseToAnthropicMessage(data: Record<string, any>, model: string): Record<string, unknown>;

package/dist/providers/openai/shim.d.ts

@@ -21,7 +21,7 @@
  *   OPENAI_MODEL                     — optional; use github:copilot or openai/gpt-4.1 style IDs
  */
 import type { ProviderOverride } from '../shared/routing.js';
-import { type AnthropicStreamEvent, type ShimCreateParams } from '../../providers/codex/shim.js';
+import { type AnthropicStreamEvent, type AnthropicUsage, type ShimCreateParams } from '../../providers/codex/shim.js';
 interface OpenAIMessage {
     role: 'system' | 'user' | 'assistant' | 'tool';
     content?: string | null | Array<{
@@ -68,6 +68,21 @@ export declare function convertTools(tools: Array<{
     input_schema?: Record<string, unknown>;
 }>, model?: string): OpenAITool[];
 export declare function makeMessageId(): string;
+/**
+ * 把 OpenAI(chat_completions)usage 折算成 Anthropic 语义的 usage。
+ *
+ * 关键：OpenAI 的 `prompt_tokens` 已包含缓存命中（`cached_tokens` 是它的子集）；而
+ * Anthropic 语义里 input_tokens / cache_read / cache_creation 互不相交、三者之和才是
+ * 完整输入上下文。所以 input_tokens 必须取「非缓存」部分 = prompt_tokens − cached，否则
+ * 上层（messageMapper 占用环、成本核算）把 input + cache_read 求和会把缓存算两遍。
+ */
+export declare function openaiUsageToAnthropicUsage(usage: {
+    prompt_tokens?: number;
+    completion_tokens?: number;
+    prompt_tokens_details?: {
+        cached_tokens?: number;
+    };
+} | undefined): AnthropicUsage;
 /**
  * Async generator that transforms an OpenAI SSE stream into
  * Anthropic-format BetaRawMessageStreamEvent objects.
@@ -172,12 +187,7 @@ export declare function convertOpenAIResponseToAnthropic(data: {
     model: string;
     stop_reason: string;
     stop_sequence: any;
-    usage: {
-        input_tokens: number;
-        output_tokens: number;
-        cache_creation_input_tokens: number;
-        cache_read_input_tokens: number;
-    };
+    usage: AnthropicUsage;
 };
 /**
  * @internal γ.6c

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

@@ -5,9 +5,9 @@ import type { EffortLevel } from 'src/lib/effort.js';
 import type { PermissionMode } from 'src/permissions/PermissionMode.js';
 import { type Span } from 'src/audit/telemetry/sessionTracing.js';
 import type { NonNullableUsage } from '../../entrypoints/sdk/sdkUtilityTypes.js';
-import { EMPTY_USAGE } from './usage.js';
+import { EMPTY_USAGE, contextWindowTokens } from './usage.js';
 export type { NonNullableUsage };
-export { EMPTY_USAGE };
+export { EMPTY_USAGE, contextWindowTokens };
 export type GlobalCacheStrategy = 'tool_based' | 'system_prompt' | 'none';
 export declare function logAPIQuery({ model, messagesLength, temperature, betas, permissionMode, querySource, queryTracking, thinkingType, effortValue, fastMode, previousRequestId, }: {
     model: string;

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

@@ -19,5 +19,10 @@ export declare function getAPIProviderForStatsig(): AnalyticsMetadata_I_VERIFIED
  * Check if ANTHROPIC_BASE_URL is a first-party Anthropic API URL.
  * Returns true if not set (default API) or points to api.anthropic.com
  * (or api-staging.anthropic.com for ant users).
+ *
+ * Reads the session-aware env (Options.env → process.env fallback): in-process
+ * hosts put the proxy base URL ONLY in createSession({env}), so a raw
+ * process.env read would misclassify their sessions as first-party and leak
+ * beta wire shapes (tool_reference / defer_loading) to the proxy.
  */
 export declare function isFirstPartyAnthropicBaseUrl(): boolean;

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

@@ -5,3 +5,14 @@ import type { NonNullableUsage } from '../../entrypoints/sdk/sdkUtilityTypes.js'
  * api/errors.ts → utils/messages.ts → BashTool.tsx → the world.
  */
 export declare const EMPTY_USAGE: Readonly<NonNullableUsage>;
+/**
+ * Tokens currently occupying the context window for a single API response.
+ *
+ * Context occupancy is a point-in-time snapshot = the input side of the most
+ * recent message: input_tokens + cache_read_input_tokens +
+ * cache_creation_input_tokens. output_tokens are excluded — they only enter
+ * the window on the *next* request. Callers must pass per-message usage, not a
+ * turn-cumulative total (summing every message's input over-counts the window
+ * because each tool round re-sends the growing context).
+ */
+export declare function contextWindowTokens(usage: NonNullableUsage): number;

package/dist/query.d.ts

@@ -24,6 +24,9 @@ export type QueryParams = {
     taskBudget?: {
         total: number;
     };
+    compactRequest?: {
+        instructions?: string;
+    };
     deps?: QueryDeps;
 };
 export declare function query(params: QueryParams): AsyncGenerator<StreamEvent | RequestStartEvent | Message | TombstoneMessage | ToolUseSummaryMessage, Terminal>;