@opencow-ai/opencow-agent-sdk 0.4.11 → 0.4.13

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

@@ -7,6 +7,7 @@ import { trySessionMemoryCompaction } from './sessionMemoryCompact.js';
 export declare function getEffectiveContextWindowSize(model: string, opts?: {
     contextWindow?: number;
     maxOutputTokens?: number;
+    maxOutputTokensLimit?: number;
 }): number;
 export type AutoCompactTrackingState = {
     compacted: boolean;
@@ -21,10 +22,12 @@ export declare const MANUAL_COMPACT_BUFFER_TOKENS = 3000;
 export declare function getAutoCompactThreshold(model: string, opts?: {
     contextWindow?: number;
     maxOutputTokens?: number;
+    maxOutputTokensLimit?: number;
 }): number;
 export declare function calculateTokenWarningState(tokenUsage: number, model: string, opts?: {
     contextWindow?: number;
     maxOutputTokens?: number;
+    maxOutputTokensLimit?: number;
 }): {
     percentLeft: number;
     isAboveWarningThreshold: boolean;
@@ -36,6 +39,7 @@ export declare function isAutoCompactEnabled(): boolean;
 export declare function shouldAutoCompact(messages: Message[], model: string, querySource?: QuerySource, snipTokensFreed?: number, opts?: {
     contextWindow?: number;
     maxOutputTokens?: number;
+    maxOutputTokensLimit?: number;
 }): Promise<boolean>;
 export declare function autoCompactIfNeeded(messages: Message[], toolUseContext: ToolRuntimeContext, cacheSafeParams: CacheSafeParams, querySource?: QuerySource, tracking?: AutoCompactTrackingState, snipTokensFreed?: number): Promise<{
     wasCompacted: boolean;

package/dist/controller/loop.d.ts

@@ -32,6 +32,7 @@ export type Options = {
     isNonInteractiveSession: boolean;
     extraToolSchemas?: BetaToolUnion[];
     maxOutputTokensOverride?: number;
+    maxOutputTokensLimitOverride?: number;
     fallbackModel?: string;
     onStreamingFallback?: () => void;
     querySource: QuerySource;

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

@@ -1,5 +1,6 @@
 import type { ChildProcessWithoutNullStreams } from 'node:child_process';
 import type { ModelProviders } from '../../providers/shared/routing.js';
+import type { UploadMediaFn } from '../../types/toolRuntime.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';
@@ -124,7 +125,7 @@ export type SettingSource = 'user' | 'project' | 'local';
 import type { SdkTool } from '../../capabilities/SdkTool.js';
 import type { LayoutProfile } from '../../session/layout/LayoutProfile.js';
 import type { SdkRule } from '../../session/rules/SdkRule.js';
-import type { ProviderTransport, DeprecatedProviderTransportName } from '../../providers/shared/config.js';
+import type { ProviderTransport, DeprecatedProviderTransportName, ReasoningEffort } from '../../providers/shared/config.js';
 import type { FileHistoryChangeListener, FileHistoryState } from '../../session/fileHistory.js';
 export type Options = {
     cwd?: string;
@@ -147,6 +148,13 @@ export type Options = {
      * values are clamped + warn-logged, never thrown.
      */
     maxOutputTokens?: number;
+    /**
+     * Optional host-authoritative upper bound for `maxOutputTokens`. Use this
+     * when the selected model is a custom gateway/deployment id whose native
+     * output cap is known by the host model catalog but not by the SDK's built-in
+     * model table. When unset, SDK built-in per-model limits are used.
+     */
+    maxOutputTokensLimit?: number;
     /**
      * Per-session context window override (input tokens). Used by autoCompact
      * threshold computation and any other code path that calls
@@ -160,6 +168,20 @@ export type Options = {
      * Values < 10_000 or > 5_000_000 are dropped + warn-logged (table fallback).
      */
     contextWindow?: number;
+    /**
+     * Host-provided default reasoning effort for the selected model. This is
+     * protocol-neutral: OpenAI Chat Completions serializes it as
+     * `reasoning_effort`, while OpenAI Responses serializes it as
+     * `reasoning.effort` and can still merge protocol-specific fields such as
+     * `reasoning.summary`.
+     *
+     * Leave unset to preserve SDK/model defaults. Pass `null` on a per-turn
+     * override to clear inherited or descriptor defaults. Hosts with an
+     * authoritative model catalog should pass that model's default here, and
+     * user-selected effort can override the catalog default before it reaches
+     * the SDK.
+     */
+    reasoningEffort?: ReasoningEffort | null;
     /**
      * 本回合手动压缩上下文（对应 host 的 /compact）。设置后 SDK 复用 auto-compact
      * 机制（isAutoCompact=false + 这些指令）压缩当前消息、发出 system/compact_boundary，
@@ -278,6 +300,21 @@ export type Options = {
         toolInput: Record<string, unknown>;
         toolUseId: string;
     }) => void | Promise<void>;
+    /**
+     * Host-injected media uploader. When supplied, media-producing built-in
+     * tools (FileReadTool reading an image) upload the **compressed** bytes
+     * (post token-budget) and emit `{type:'image', source:{type:'url', url}}`
+     * in the tool_result instead of inline base64 — keeping the bytes out of
+     * every subsequent turn's request and letting the host materialize them.
+     * Media-neutral: the same port serves image / PDF / page-image tool output,
+     * driven by `mediaType`.
+     *
+     * Returns a fetchable URL, or `null` when upload is unavailable; the SDK
+     * also treats a thrown error as "unavailable". Either way it falls back to
+     * inline base64, so standalone SDK/CLI runs (no uploader) are byte-for-byte
+     * unchanged.
+     */
+    uploadMedia?: UploadMediaFn;
     jsonSchema?: Record<string, unknown>;
     betas?: string[];
     settingSources?: SettingSource[];
@@ -325,8 +362,8 @@ export type Options = {
      *   - `metadata` — string-keyed map attached to the request
      *   - `responseFormat` — JSON schema enforcement
      *   - `reasoning` — reasoning configuration override. `effort` controls
-     *     how hard the model thinks (minimal/low/medium/high; default model-
-     *     specific). `summary` controls whether human-readable reasoning
+     *     how hard the model thinks (none/minimal/low/medium/high/xhigh;
+     *     default model-specific). `summary` controls whether human-readable reasoning
      *     summary is returned in the SSE stream ('auto'/'concise'/'detailed';
      *     when unset, upstream returns only encrypted reasoning items —
      *     useful for state preservation but invisible in UI). Merges with
@@ -341,7 +378,7 @@ export type Options = {
             metadata?: Record<string, string>;
             responseFormat?: unknown;
             reasoning?: {
-                effort?: 'minimal' | 'low' | 'medium' | 'high';
+                effort?: ReasoningEffort;
                 summary?: 'auto' | 'concise' | 'detailed' | null;
             };
         };

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

@@ -1,4 +1,4 @@
-import type { ResolvedCodexCredentials, ResolvedProviderRequest } from '../../providers/shared/config.js';
+import type { ResolvedCodexCredentials, ResolvedProviderRequest, ReasoningEffort } from '../../providers/shared/config.js';
 export interface AnthropicUsage {
     input_tokens: number;
     output_tokens: number;
@@ -53,7 +53,7 @@ export interface ResponsesProviderSpecific {
      * reasoning (Codex aliases or `?reasoning=high` model suffix) per-key.
      *
      * - `effort`: how hard the model thinks. Without it, model-specific
-     *   default applies (gpt-5 default = 'medium').
+     *   default applies.
      * - `summary`: whether human-readable reasoning summary is streamed via
      *   `response.reasoning_summary_text.delta` events. WITHOUT this set,
      *   the upstream returns only encrypted_content reasoning items —
@@ -62,7 +62,7 @@ export interface ResponsesProviderSpecific {
      *   chain-of-thought text.
      */
     reasoning?: {
-        effort?: 'minimal' | 'low' | 'medium' | 'high';
+        effort?: ReasoningEffort;
         summary?: 'auto' | 'concise' | 'detailed' | null;
     };
 }

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

@@ -22,6 +22,7 @@
  */
 import type { ProviderOverride } from '../shared/routing.js';
 import { type AnthropicStreamEvent, type AnthropicUsage, type ShimCreateParams } from '../../providers/codex/shim.js';
+import { type ReasoningEffort } from '../../providers/shared/config.js';
 interface OpenAIMessage {
     role: 'system' | 'user' | 'assistant' | 'tool';
     content?: string | null | Array<{
@@ -98,24 +99,12 @@ export declare function openaiUsageToAnthropicUsage(usage: {
  * responsibilities.
  */
 /**
- * Convert an SDK-internal reasoning-effort tier to the value accepted by
- * OpenAI's chat_completions `reasoning_effort` parameter.
- *
- * Two vocabularies meet here:
- *   - SDK vocab:              `'low' | 'medium' | 'high' | 'xhigh'`
- *                             (`'xhigh'` is the SDK-internal "Max" tier,
- *                             surfaced as "max" in the CLI — see
- *                             `lib/effort.ts`.)
- *   - OpenAI chat wire vocab: `'low' | 'medium' | 'high'`
- *                             (Spec: platform.openai.com/docs/api-reference/chat/create)
- *
- * `'xhigh'` is clamped down to `'high'` rather than rejected: the SDK
- * semantic is "as much reasoning as the provider will give" and `'high'`
- * is the upper bound on this wire. Sending `'xhigh'` raw would 400 on
- * strict proxies. The Responses API (codex) has its own serialisation
- * and does NOT go through this function — see `codex/shim.ts`.
+ * Convert an SDK reasoning-effort tier to the value accepted by OpenAI Chat
+ * Completions `reasoning_effort`. The current OpenAI wire accepts the same
+ * vocabulary as the SDK; model-specific legality is enforced by the host
+ * catalog / upstream provider, not by this transport boundary.
  */
-export declare function toOpenAIChatReasoningEffort(effort: 'low' | 'medium' | 'high' | 'xhigh'): 'low' | 'medium' | 'high';
+export declare function toOpenAIChatReasoningEffort(effort: ReasoningEffort): ReasoningEffort;
 export declare function buildOpenAIRequestBody(params: ShimCreateParams, ctx: {
     resolvedModel: string;
     baseUrl: string;
@@ -133,7 +122,7 @@ export declare function buildOpenAIRequestBody(params: ShimCreateParams, ctx: {
      * transports serialise differently on the wire.
      */
     reasoning?: {
-        effort: 'low' | 'medium' | 'high' | 'xhigh';
+        effort: ReasoningEffort;
     };
 }): Record<string, unknown>;
 export declare function openaiStreamToAnthropic(response: Response, model: string): AsyncGenerator<AnthropicStreamEvent>;
@@ -209,7 +198,7 @@ export declare function createOpenAIShimClient(options: {
     defaultHeaders?: Record<string, string>;
     maxRetries?: number;
     timeout?: number;
-    reasoningEffort?: 'low' | 'medium' | 'high' | 'xhigh';
+    reasoningEffort?: ReasoningEffort;
     providerOverride?: ProviderOverride;
 }): unknown;
 export {};

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

@@ -2,7 +2,7 @@ export declare const DEFAULT_OPENAI_BASE_URL = "https://api.openai.com/v1";
 export declare const DEFAULT_CODEX_BASE_URL = "https://chatgpt.com/backend-api/codex";
 /** Default GitHub Models API model when user selects copilot / github:copilot */
 export declare const DEFAULT_GITHUB_MODELS_API_MODEL = "openai/gpt-4.1";
-type ReasoningEffort = 'low' | 'medium' | 'high' | 'xhigh';
+export type ReasoningEffort = 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
 /**
  * Wire-level transport selected by `resolveProviderTransport`.
  *
@@ -45,6 +45,8 @@ export type DeprecatedProviderTransportName = 'codex_responses';
  * CLAUDE_CODE_USE_GITHUB, OPENCOW_DEBUG_REASONING).
  */
 export declare const QUERY_ENV_KEY_TRANSPORT_OVERRIDE = "__OPENCOW_TRANSPORT_OVERRIDE";
+export declare const QUERY_ENV_KEY_REASONING_EFFORT_OVERRIDE = "__OPENCOW_REASONING_EFFORT_OVERRIDE";
+export declare const QUERY_ENV_VALUE_REASONING_EFFORT_CLEAR = "__OPENCOW_CLEAR_REASONING_EFFORT__";
 export declare const QUERY_ENV_KEY_PROVIDER_SPECIFIC_OPENAI_RESPONSES = "__OPENCOW_PROVIDER_SPECIFIC_OPENAI_RESPONSES";
 export type ResolvedProviderRequest = {
     transport: ProviderTransport;
@@ -139,7 +141,7 @@ export declare function resolveProviderRequest(options?: {
     model?: string;
     baseUrl?: string;
     fallbackModel?: string;
-    reasoningEffortOverride?: ReasoningEffort;
+    reasoningEffortOverride?: ReasoningEffort | null;
     /**
      * Optional explicit transport override forwarded to
      * `resolveProviderTransport`. When unset, callers can still rely on the
@@ -181,4 +183,3 @@ export declare function parseChatgptAccountId(token: string | undefined): string
 export declare function resolveOpenAIResponsesCredentials(): ResolvedCodexCredentials;
 export declare function resolveCodexApiCredentials(env?: NodeJS.ProcessEnv): ResolvedCodexCredentials;
 export declare function getReasoningEffortForModel(model: string): ReasoningEffort | undefined;
-export {};

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

@@ -1,3 +1,4 @@
 export declare function getMaxOutputTokensForModel(model: string, opts?: {
     override?: number;
+    upperLimitOverride?: number;
 }): number;

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

@@ -1,5 +1,5 @@
 import type { SettingsJson } from '../../session/settings/types.js';
-import type { ProviderTransport } from './config.js';
+import type { ProviderTransport, ReasoningEffort } from './config.js';
 /**
  * Provider override resolved for a specific agent/model.
  * When present, the API client uses these instead of the session-global
@@ -21,6 +21,8 @@ export interface ProviderOverride {
      * OpenAI shim.
      */
     transport?: ProviderTransport | 'anthropic';
+    /** Default reasoning effort for this model route; null clears session default. */
+    reasoningEffort?: ReasoningEffort | null;
     /** Per-wire extras (e.g. openai-responses reasoning summary config). */
     providerSpecific?: {
         openaiResponses?: Record<string, unknown>;

package/dist/query.d.ts

@@ -19,6 +19,7 @@ export type QueryParams = {
     fallbackModel?: string;
     querySource: QuerySource;
     maxOutputTokensOverride?: number;
+    maxOutputTokensLimitOverride?: number;
     maxTurns?: number;
     skipCacheWrite?: boolean;
     taskBudget?: {