@opencow-ai/opencow-agent-sdk 0.4.12 → 0.4.14

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/logTypes.d.ts

@@ -112,8 +112,10 @@ export interface SdkDiagnosticEvent {
  * across all providers).
  *
  * `source` mirrors the `source` argument that `buildFetch` already
- * accepts (e.g. `'main_loop'`, `'token_count'`) — lets the host
- * distinguish main-loop API calls from auxiliary ones.
+ * accepts (e.g. `'main_loop'`, `'count_tokens'`, `'agent:custom'`) —
+ * lets the host distinguish main-loop API calls from auxiliary and
+ * subagent ones. `endpoint` is a normalized route family such as
+ * `'messages'`, `'count_tokens'`, or `'responses'`.
  *
  * @stable
  */
@@ -123,18 +125,47 @@ export type SdkHttpEvent = {
     readonly method: string;
     readonly url: string;
     readonly source: string | undefined;
+    readonly endpoint?: string;
+    readonly attempt?: number;
+    readonly maxAttempts?: number;
     readonly timestamp: number;
 } | {
     readonly type: 'response_start';
     readonly requestId: string;
     readonly status: number;
     readonly durationMs: number;
+    readonly source?: string;
+    readonly endpoint?: string;
+    readonly attempt?: number;
+    readonly maxAttempts?: number;
+    readonly willRetry?: boolean;
+    readonly retryDelayMs?: number;
+    readonly failureReason?: string;
     readonly timestamp: number;
 } | {
     readonly type: 'error';
     readonly requestId: string;
     readonly error: Error;
     readonly durationMs: number;
+    readonly source?: string;
+    readonly endpoint?: string;
+    readonly attempt?: number;
+    readonly maxAttempts?: number;
+    readonly willRetry?: boolean;
+    readonly retryDelayMs?: number;
+    readonly failureReason?: string;
+    readonly status?: number;
+    readonly timestamp: number;
+} | {
+    readonly type: 'retry';
+    readonly requestId?: string;
+    readonly source?: string;
+    readonly endpoint?: string;
+    readonly attempt: number;
+    readonly maxAttempts?: number;
+    readonly retryDelayMs: number;
+    readonly status?: number;
+    readonly failureReason: string;
     readonly timestamp: number;
 };
 /**

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

@@ -6,6 +6,7 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { CallToolResult, ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
 import type { z } from 'zod/v4';
 import type { ExitReason, HookEvent, HookInput, SDKMessage, SDKResultMessage, SDKSessionInfo, SDKUserMessage, SyncHookJSONOutput } from './coreTypes.js';
+export type { SDKMessage, SDKUserMessage } from './coreTypes.js';
 export type EffortLevel = 'low' | 'medium' | 'high' | 'xhigh' | 'max';
 export type AnyZodRawShape = z.ZodRawShape;
 export type InferShape<Shape extends AnyZodRawShape = AnyZodRawShape> = z.infer<z.ZodObject<Shape>>;
@@ -125,7 +126,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;
@@ -148,6 +149,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
@@ -161,6 +169,26 @@ 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: providers serialize it into their native request shape,
+     * such as OpenAI Chat Completions `reasoning_effort` or OpenAI Responses
+     * `reasoning.effort`.
+     *
+     * 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;
+    /**
+     * Low-level request-body extension. Snake-case mirrors OpenAI-style clients
+     * that expose an `extra_body` escape hatch. Provider shims decide how to
+     * merge it into their wire body; the SDK does not validate provider-specific
+     * nested schemas here.
+     */
+    extra_body?: ExtraBody;
     /**
      * 本回合手动压缩上下文（对应 host 的 /compact）。设置后 SDK 复用 auto-compact
      * 机制（isAutoCompact=false + 这些指令）压缩当前消息、发出 system/compact_boundary，
@@ -302,10 +330,9 @@ export type Options = {
      * Explicit wire-level transport selection. When provided, overrides the
      * default base-URL / model-alias sniff in `resolveProviderTransport`.
      *
-     * Hosts that proxy upstream providers through their own backend (e.g.
-     * desktop-evose proxies api.openai.com via {host}/sdk/v1/responses)
-     * MUST set this explicitly because the proxy URL does not match the
-     * SDK's built-in Codex base URL detector.
+     * Hosts that proxy upstream providers through their own backend MUST set
+     * this explicitly because the proxy URL usually does not match the SDK's
+     * built-in provider detectors.
      *
      * - `'auto'` (default) — sniff baseUrl then model alias (legacy behavior)
      * - `'chat_completions'` — POST {baseUrl}/chat/completions (OpenAI Chat
@@ -320,12 +347,9 @@ export type Options = {
     /**
      * Host model → provider-route catalog, keyed by model id. Consulted AFTER
      * subagent model resolution (tier aliases / Agent tool `model` param), so
-     * a subagent whose model lives on a different wire or endpoint than the
-     * main session routes to its own baseURL/key/transport instead of
-     * inheriting the session's (which 404s for cross-protocol tier models).
-     * Models absent from the catalog use the session provider config as
-     * before. Entries may carry `providerSpecific.openaiResponses` extras
-     * applied when that model's request uses the openai_responses wire.
+     * a host can override a subagent model's baseURL/key/transport/reasoning
+     * defaults without changing the main session provider. Models absent from
+     * the catalog use the session provider config as before.
      */
     modelProviders?: ModelProviders;
     /**
@@ -341,8 +365,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
@@ -357,7 +381,7 @@ export type Options = {
             metadata?: Record<string, string>;
             responseFormat?: unknown;
             reasoning?: {
-                effort?: 'minimal' | 'low' | 'medium' | 'high';
+                effort?: ReasoningEffort;
                 summary?: 'auto' | 'concise' | 'detailed' | null;
             };
         };
@@ -453,6 +477,7 @@ export type InternalOptions = Options;
 export type SessionMutationOptions = {
     dir?: string;
 };
+export type ExtraBody = Record<string, unknown>;
 export type GetSessionInfoOptions = SessionMutationOptions;
 export type ListSessionsOptions = SessionMutationOptions & {
     limit?: number;

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<{
@@ -61,7 +62,9 @@ export declare function convertMessages(messages: Array<{
         content?: unknown;
     };
     content?: unknown;
-}>, system: unknown): OpenAIMessage[];
+}>, system: unknown, options?: {
+    replayReasoningContent?: boolean;
+}): OpenAIMessage[];
 export declare function convertTools(tools: Array<{
     name: string;
     description?: string;
@@ -98,24 +101,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 +124,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 +200,8 @@ export declare function createOpenAIShimClient(options: {
     defaultHeaders?: Record<string, string>;
     maxRetries?: number;
     timeout?: number;
-    reasoningEffort?: 'low' | 'medium' | 'high' | 'xhigh';
+    reasoningEffort?: ReasoningEffort;
     providerOverride?: ProviderOverride;
+    source?: string;
 }): unknown;
 export {};

package/dist/providers/provider.d.ts

@@ -86,7 +86,7 @@ export interface Provider {
     /**
      * Construct the HTTP-level client that `services/api/claude.ts`
      * drives in its request pipeline. The returned object exposes the
-     * Anthropic SDK's `beta.messages.create(...)` surface so
+     * Anthropic SDK's `messages.create(...)` surface so
      * `withRetry` and the main agent loop consume a uniform shape
      * regardless of Provider family.
      *

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`.
  *
@@ -16,6 +16,7 @@ type ReasoningEffort = 'low' | 'medium' | 'high' | 'xhigh';
  *   wire format. Renamed from `'codex_responses'` in 0.2.0 (alias retained
  *   one version). ChatGPT-Codex vendor identity (isCodexBaseUrl /
  *   CODEX_ALIAS_MODELS / DEFAULT_CODEX_BASE_URL) is orthogonal and preserved.
+ *
  */
 export type ProviderTransport = 'chat_completions' | 'openai_responses';
 /**
@@ -25,15 +26,15 @@ export type ProviderTransport = 'chat_completions' | 'openai_responses';
 export type DeprecatedProviderTransportName = 'codex_responses';
 /**
  * ALS-scoped env-var keys used to forward public `Options.transport` /
- * `Options.providerSpecific.openaiResponses` from `runSdkQueryRuntime` to
- * provider-side resolvers (`resolveProviderRequest`, `performCodexRequest`)
- * without threading new parameters through the deep call chain.
+ * `Options.providerSpecific.openaiResponses` / `Options.extra_body` from
+ * `runSdkQueryRuntime` to provider-side resolvers/shims without threading new
+ * parameters through the deep call chain.
  *
  * Pattern: identical to how `OPENAI_BASE_URL` is consumed via
  * `getQueryEnvVar` from inside `resolveProviderTransport`. The double
  * underscore prefix marks them as SDK-internal — hosts MUST NOT set these
  * directly in `Options.env`; use the typed `Options.transport` /
- * `Options.providerSpecific` fields instead.
+ * `Options.providerSpecific` / `Options.extra_body` fields instead.
  *
  * Why env-injection (vs signature plumbing): the call chain
  * `runSdkQueryRuntime` → `QueryEngine.ask` → `getNormalizedClient` →
@@ -45,7 +46,10 @@ 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 declare const QUERY_ENV_KEY_EXTRA_BODY = "__OPENCOW_EXTRA_BODY";
 export type ResolvedProviderRequest = {
     transport: ProviderTransport;
     requestedModel: string;
@@ -139,7 +143,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 +185,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/httpObservability.d.ts

@@ -0,0 +1,5 @@
+import type { SdkHttpEvent } from '../../entrypoints/sdk/logTypes.js';
+export declare function classifyModelHttpEndpoint(url: string): string;
+export declare function errorToFailureReason(error: unknown): string;
+export declare function responseBodyToFailureReason(status: number, body: string): string;
+export declare function emitSdkHttp(event: SdkHttpEvent): void;

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/requestSideChannels.d.ts

@@ -0,0 +1 @@
+export declare function mergeOpenAICompatibleExtraBodyParams(body: Record<string, unknown>, params: Record<string, unknown>): void;

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
@@ -8,19 +8,18 @@ import type { ProviderTransport } from './config.js';
 export interface ProviderOverride {
     /** Model name to send to the API (e.g. "deepseek-chat", "gpt-4o") */
     model: string;
-    /** Base URL. Optional — falls back to the session's OPENAI_BASE_URL env. */
+    /** Base URL. Optional — falls back to the session's provider env. */
     baseURL?: string;
     /** API key. Optional — falls back to the session's env credential chain. */
     apiKey?: string;
     /**
      * Wire transport for this override. Without it the session-level
-     * transport/sniff applies — which is exactly the cross-protocol subagent
-     * bug: a tier model living on a different wire (e.g. openai_responses)
-     * than the main session (chat_completions) hits the wrong endpoint and
-     * 404s. 'anthropic' routes to the native Anthropic client instead of the
-     * OpenAI shim.
+     * transport/sniff applies. 'anthropic' routes to the native Anthropic
+     * client; other values route to their matching 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>;
@@ -30,9 +29,9 @@ export interface ProviderOverride {
  * Host-supplied model → provider-route catalog (`Options.modelProviders`).
  * Key is the model id as it appears after subagent model resolution (tier
  * env values / Agent tool `model` param). The host owns the model catalog
- * (which channel/protocol each model lives on); the SDK consults this AFTER
- * resolving a subagent's model so any resolution path — tier alias, explicit
- * model param, inherit — lands on the right wire.
+ * (which endpoint/defaults each model should use); the SDK consults this
+ * AFTER resolving a subagent's model so any resolution path — tier alias,
+ * explicit model param, inherit — can land on the right provider config.
  */
 export type ModelProviderConfig = Omit<ProviderOverride, 'model'>;
 export type ModelProviders = Record<string, ModelProviderConfig>;

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?: {