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

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>>;
@@ -170,10 +171,9 @@ export type Options = {
     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`.
+     * 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
@@ -182,6 +182,13 @@ export type Options = {
      * 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，
@@ -323,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
@@ -341,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;
     /**
@@ -474,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/openai/shim.d.ts

@@ -62,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;
@@ -200,5 +202,6 @@ export declare function createOpenAIShimClient(options: {
     timeout?: number;
     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

@@ -16,6 +16,7 @@ export type ReasoningEffort = 'none' | 'minimal' | 'low' | 'medium' | 'high' | '
  *   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` →
@@ -48,6 +49,7 @@ export declare const QUERY_ENV_KEY_TRANSPORT_OVERRIDE = "__OPENCOW_TRANSPORT_OVE
 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;

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/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

@@ -8,17 +8,14 @@ import type { ProviderTransport, ReasoningEffort } 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. */
@@ -32,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>;