@opencow-ai/opencow-agent-sdk 0.4.2 → 0.4.4

package/dist/lib/schemaSanitizer.d.ts

@@ -1,3 +1,39 @@
+/**
+ * 把一个属性 schema 标记为「可空」。用于 OpenAI/Codex strict 模式下被强制列入
+ * `required` 的「原本可选」字段：strict 模式要求每个属性都出现在 `required`，
+ * 否则 400。这会逼模型给本应省略的可选字段编造一个占位值（典型即空串 `""`），
+ * 下游再因这个空值报错（issue #79：Read 的 `pages: ""` → Invalid pages parameter；
+ * issue #77：gpt 用 read 工具频繁出错）。让字段可空后，模型可以用 `null` 明确表达
+ * 「未提供」，再由入参解析层把 `null` 还原为缺省。
+ *
+ * 可空的两种写法没有「最大公约数」，必须按目标 provider 选择：
+ *   - `'union'`（默认）：`type: [T, "null"]`。OpenAI / Codex 的 **strict 结构化输出
+ *     只接受这种**（`nullable` 是 OpenAPI 扩展，不在其 JSON-Schema 子集里，会被
+ *     strict 校验拒绝 400）；DeepSeek / Kimi / Qwen 同样接受。
+ *   - `'nullable'`：`nullable: true`。Gemini / Vertex 只接受这种，拒绝 type 数组。
+ *
+ * 注意 OpenAI chat（非 strict）会忽略 `nullable`，从而丢掉「可传 null」的提示，
+ * 退回 issue #77 的形态——所以对 OpenAI 路径必须用 `'union'`。Gemini 路径由调用方
+ * （normalizeSchemaForOpenAI）传 `'nullable'`，或经 splitTypeArrayToAnyOf 转换。
+ *
+ * 带 `enum`/`const` 的字段保持不动（避免自相矛盾）；
+ * 无明确 `type` 的字段也保持不动（零回归）。
+ */
+export declare function makeSchemaNullable(schema: Record<string, unknown>, style?: 'union' | 'nullable'): Record<string, unknown>;
+/**
+ * 把 type 数组改写为 **Gemini/Vertex** 能接受的形式——仅在目标是 Gemini 时调用
+ * （见 normalizeSchemaForOpenAI 的 geminiTarget 门控）。OpenAI/DeepSeek/Kimi 等接受
+ * type 数组、且对 OpenAI 而言 `nullable` 会被忽略，故对它们不应调用本函数。
+ *
+ * Gemini 侧约束：拒绝 type 数组，拒绝 anyOf + null，只接受 nullable: true。
+ *
+ * 转换策略：
+ *   - `type: ["T", "null"]` → `{ type: "T", nullable: true, ...结构性关键字 }`
+ *   - `type: ["T1", "T2", ...]`（>1 种非 null 类型）→ 拆为 anyOf，null 以 nullable 表达
+ *
+ * 不递归——由调用方（normalizeSchemaForOpenAI）的递归遍历负责嵌套层级。
+ */
+export declare function splitTypeArrayToAnyOf(schema: Record<string, unknown>): Record<string, unknown>;
 /**
  * Sanitize JSON Schema into a shape OpenAI-compatible providers and Codex
  * strict-mode tooling are more likely to accept. This strips provider-rejected

package/dist/lib/toolInputNullCoercion.d.ts

@@ -0,0 +1,20 @@
+import type { z } from 'zod/v4';
+/**
+ * 解析工具入参，并对 strict provider 把可选字段强制为 nullable 后模型回传的 `null`
+ * 做兜底还原。
+ *
+ * 背景：OpenAI/Codex strict 模式要求每个属性都出现在 `required`，可选字段会被
+ * `makeSchemaNullable` 标成可空（见 lib/schemaSanitizer.ts），模型遂用 `null` 表达
+ * 「未提供」。但工具的 Zod inputSchema 多用 `.optional()`（不接受 `null`），若直接
+ * `safeParse` 会得到 InputValidationError —— 这正是「① 让 wire schema 可空」必须搭配的
+ * 入参侧兜底（issue #79/#77）。
+ *
+ * 策略：先按原始 schema 解析；仅当「解析失败 且 顶层含 null 值」时，去掉这些 null 键
+ * 再解析一次，且只有重试成功才采用重试结果。由此：
+ *   - 真正接受 null 的 `.nullable()` 字段：原始即可解析 → 不触发重试 → `null` 保留；
+ *   - 与 null 无关的真实校验错误：去 null 后仍失败 → 返回原始错误，不掩盖；
+ *   - 可选非空字段被强制塞入的 `null`：去掉后变缺省，`.optional()` 通过。
+ *
+ * 仅处理顶层 null，与 `makeSchemaNullable` 仅顶层可空的范围对齐。
+ */
+export declare function safeParseToolInputWithNullCoercion<T extends z.ZodType>(schema: T, input: unknown): ReturnType<T['safeParse']>;

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

@@ -1,4 +1,12 @@
 import type { ModelOutputTokenCap, ProviderFeature } from '../types.js';
+/**
+ * 判断最终目标是否为 Gemini/Vertex 系列。
+ *
+ * 这是 Gemini 专属适配(关闭并行工具调用、schema 用 nullable:true 而非 type 数组)的
+ * 统一判定入口。后端纯透传时 SDK 侧 family 恒为 openai,无法据此识别最终 provider,
+ * 因此依据 CLAUDE_CODE_USE_GEMINI 环境标志 + model 名两路信号判断。
+ */
+export declare function isGeminiTarget(model: string): boolean;
 export declare function getOpenAICompatMaxOutputTokens(model: string): ModelOutputTokenCap | null;
 export declare function getOpenAICompatContextWindow(model: string): number | null;
 export declare function openAICompatSupports(feature: ProviderFeature, model: string): boolean;

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

@@ -1 +1 @@
-export { sanitizeSchemaForOpenAICompat } from '../../lib/schemaSanitizer.js';
+export { sanitizeSchemaForOpenAICompat, makeSchemaNullable, } from '../../lib/schemaSanitizer.js';

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

@@ -23,7 +23,7 @@
 import { type AnthropicStreamEvent, type ShimCreateParams } from '../../providers/codex/shim.js';
 interface OpenAIMessage {
     role: 'system' | 'user' | 'assistant' | 'tool';
-    content?: string | Array<{
+    content?: string | null | Array<{
         type: string;
         text?: string;
         image_url?: {
@@ -65,7 +65,7 @@ export declare function convertTools(tools: Array<{
     name: string;
     description?: string;
     input_schema?: Record<string, unknown>;
-}>): OpenAITool[];
+}>, model?: string): OpenAITool[];
 export declare function makeMessageId(): string;
 /**
  * Async generator that transforms an OpenAI SSE stream into
@@ -146,6 +146,13 @@ export declare function convertOpenAIResponseToAnthropic(data: {
                 };
                 extra_content?: Record<string, unknown>;
             }>;
+            reasoning_content?: string | null;
+            reasoning?: string | null;
+            reasoning_details?: Array<{
+                type?: string;
+                content?: string;
+                summary?: string;
+            }> | null;
         };
         finish_reason?: string;
     }>;