@cognipeer/agent-sdk 0.8.8 → 0.8.10

package/dist/index.d.cts

@@ -719,7 +719,8 @@ type ReflectionConfig = {
     onReflection?: (record: ReflectionRecord, ctx: ReflectionHookContext) => void;
 };
 type NativeReasoningConfig = {
-    effort?: "minimal" | "low" | "medium" | "high";
+    /** `none` is OFF — a value that gets SENT. See ReasoningEffort in providers/types.ts. */
+    effort?: "none" | "minimal" | "low" | "medium" | "high";
     budgetTokens?: number;
     includeThoughts?: boolean;
     providerExtras?: Record<string, any>;
@@ -2481,6 +2482,8 @@ declare class StructuredOutputManager<T> {
     /**
      * Build a nudge message for when the model didn't produce structured output.
      * Used by the agent loop when it needs to retry.
+     * User role is intentional: OpenAI-compatible chat templates such as Qwen
+     * reject system messages anywhere except the beginning of the conversation.
      */
     buildNudgeMessage(isLastAttempt: boolean): {
         role: string;
@@ -2916,7 +2919,18 @@ type ChatCompletionRequest = {
      */
     reasoning?: ReasoningRequestConfig;
 };
-type ReasoningEffort = "minimal" | "low" | "medium" | "high";
+/**
+ * `none` is OFF, and it is a value rather than the absence of one.
+ *
+ * On a thinking-by-default model — every Qwen3 under vLLM, gpt-5.1 and newer on
+ * OpenAI — sending no reasoning field leaves the model thinking. So "do not
+ * think" is an instruction that has to travel: `reasoning_effort:"none"` on
+ * OpenAI, `thinkingBudget:0` on Gemini, and no thinking block at all on
+ * Anthropic (where thinking is opt-in and the absence IS off). Omitting
+ * `effort` still means "say nothing about reasoning", which is the different
+ * and equally necessary state.
+ */
+type ReasoningEffort = "none" | "minimal" | "low" | "medium" | "high";
 type ReasoningRequestConfig = {
     /** Qualitative effort hint (mapped per-provider). */
     effort?: ReasoningEffort;
@@ -2979,6 +2993,28 @@ type OpenAIProviderConfig = {
     defaultModel?: string;
     defaultHeaders?: Record<string, string>;
     retry?: ProviderRetryConfig;
+    /**
+     * WHICH API a reasoning-carrying request is addressed to.
+     *
+     *  auto    (default, and today's behaviour) route to the Responses API when
+     *          the request carries `reasoning` AND the model name looks like an
+     *          o-series/gpt-5 reasoning model.
+     *  never   always Chat Completions. `reasoning` is still mapped, as
+     *          `reasoning_effort` plus any `providerExtras`.
+     *  always  always Responses, whatever the model is called.
+     *
+     * `auto` is a name-based guess, and it decides far more than where reasoning
+     * goes: Responses is a different request shape (`input` not `messages`,
+     * `text.format` not `response_format`, flat tool objects) and a different
+     * response parse. A caller with its own measurements of the Chat Completions
+     * body — a gateway, a proxy, an on-prem server that serves one and not the
+     * other, or anything that has tuned `extra` — must be able to say so, rather
+     * than discover that asking for less thinking silently changed the transport.
+     *
+     * Applies to any OpenAI-shaped endpoint, which is also why the guess is weak
+     * where it matters most: a self-hosted model is named by whoever served it.
+     */
+    responsesApi?: "auto" | "never" | "always";
 };
 type AnthropicProviderConfig = {
     provider: "anthropic";
@@ -3083,10 +3119,17 @@ declare class OpenAIProvider extends BaseProvider {
     protected readonly baseURL: string;
     protected readonly defaultModel: string;
     protected readonly defaultHeaders: Record<string, string>;
+    protected readonly responsesApi: "auto" | "never" | "always";
     constructor(config: OpenAIProviderConfig);
-    /** True when the request targets a reasoning model (o-series / gpt-5) so we
-     * should route through the Responses API, which exposes `reasoning.effort`
-     * and reasoning summaries. Chat Completions silently drops these. */
+    /** True when this request should go to the Responses API rather than Chat
+     * Completions — which exposes `reasoning.effort` and reasoning summaries that
+     * Chat Completions silently drops.
+     *
+     * `auto` (the default) keeps the historical rule: only when the request
+     * carries a reasoning config AND the model name looks like an o-series/gpt-5
+     * model. `never`/`always` let a caller state the answer instead, because the
+     * name check is a guess and the two APIs differ in far more than reasoning —
+     * see `responsesApi` in OpenAIProviderConfig. */
     protected useResponsesApi(request: ChatCompletionRequest): boolean;
     complete(request: ChatCompletionRequest): Promise<ChatCompletionResponse>;
     completeStream(request: ChatCompletionRequest): AsyncGenerator<ChatCompletionChunk, void, unknown>;

package/dist/index.d.ts

@@ -719,7 +719,8 @@ type ReflectionConfig = {
     onReflection?: (record: ReflectionRecord, ctx: ReflectionHookContext) => void;
 };
 type NativeReasoningConfig = {
-    effort?: "minimal" | "low" | "medium" | "high";
+    /** `none` is OFF — a value that gets SENT. See ReasoningEffort in providers/types.ts. */
+    effort?: "none" | "minimal" | "low" | "medium" | "high";
     budgetTokens?: number;
     includeThoughts?: boolean;
     providerExtras?: Record<string, any>;
@@ -2481,6 +2482,8 @@ declare class StructuredOutputManager<T> {
     /**
      * Build a nudge message for when the model didn't produce structured output.
      * Used by the agent loop when it needs to retry.
+     * User role is intentional: OpenAI-compatible chat templates such as Qwen
+     * reject system messages anywhere except the beginning of the conversation.
      */
     buildNudgeMessage(isLastAttempt: boolean): {
         role: string;
@@ -2916,7 +2919,18 @@ type ChatCompletionRequest = {
      */
     reasoning?: ReasoningRequestConfig;
 };
-type ReasoningEffort = "minimal" | "low" | "medium" | "high";
+/**
+ * `none` is OFF, and it is a value rather than the absence of one.
+ *
+ * On a thinking-by-default model — every Qwen3 under vLLM, gpt-5.1 and newer on
+ * OpenAI — sending no reasoning field leaves the model thinking. So "do not
+ * think" is an instruction that has to travel: `reasoning_effort:"none"` on
+ * OpenAI, `thinkingBudget:0` on Gemini, and no thinking block at all on
+ * Anthropic (where thinking is opt-in and the absence IS off). Omitting
+ * `effort` still means "say nothing about reasoning", which is the different
+ * and equally necessary state.
+ */
+type ReasoningEffort = "none" | "minimal" | "low" | "medium" | "high";
 type ReasoningRequestConfig = {
     /** Qualitative effort hint (mapped per-provider). */
     effort?: ReasoningEffort;
@@ -2979,6 +2993,28 @@ type OpenAIProviderConfig = {
     defaultModel?: string;
     defaultHeaders?: Record<string, string>;
     retry?: ProviderRetryConfig;
+    /**
+     * WHICH API a reasoning-carrying request is addressed to.
+     *
+     *  auto    (default, and today's behaviour) route to the Responses API when
+     *          the request carries `reasoning` AND the model name looks like an
+     *          o-series/gpt-5 reasoning model.
+     *  never   always Chat Completions. `reasoning` is still mapped, as
+     *          `reasoning_effort` plus any `providerExtras`.
+     *  always  always Responses, whatever the model is called.
+     *
+     * `auto` is a name-based guess, and it decides far more than where reasoning
+     * goes: Responses is a different request shape (`input` not `messages`,
+     * `text.format` not `response_format`, flat tool objects) and a different
+     * response parse. A caller with its own measurements of the Chat Completions
+     * body — a gateway, a proxy, an on-prem server that serves one and not the
+     * other, or anything that has tuned `extra` — must be able to say so, rather
+     * than discover that asking for less thinking silently changed the transport.
+     *
+     * Applies to any OpenAI-shaped endpoint, which is also why the guess is weak
+     * where it matters most: a self-hosted model is named by whoever served it.
+     */
+    responsesApi?: "auto" | "never" | "always";
 };
 type AnthropicProviderConfig = {
     provider: "anthropic";
@@ -3083,10 +3119,17 @@ declare class OpenAIProvider extends BaseProvider {
     protected readonly baseURL: string;
     protected readonly defaultModel: string;
     protected readonly defaultHeaders: Record<string, string>;
+    protected readonly responsesApi: "auto" | "never" | "always";
     constructor(config: OpenAIProviderConfig);
-    /** True when the request targets a reasoning model (o-series / gpt-5) so we
-     * should route through the Responses API, which exposes `reasoning.effort`
-     * and reasoning summaries. Chat Completions silently drops these. */
+    /** True when this request should go to the Responses API rather than Chat
+     * Completions — which exposes `reasoning.effort` and reasoning summaries that
+     * Chat Completions silently drops.
+     *
+     * `auto` (the default) keeps the historical rule: only when the request
+     * carries a reasoning config AND the model name looks like an o-series/gpt-5
+     * model. `never`/`always` let a caller state the answer instead, because the
+     * name check is a guess and the two APIs differ in far more than reasoning —
+     * see `responsesApi` in OpenAIProviderConfig. */
     protected useResponsesApi(request: ChatCompletionRequest): boolean;
     complete(request: ChatCompletionRequest): Promise<ChatCompletionResponse>;
     completeStream(request: ChatCompletionRequest): AsyncGenerator<ChatCompletionChunk, void, unknown>;

package/dist/index.mjs

@@ -4289,7 +4289,7 @@ var LEVEL_DEFAULTS = {
 };
 var VALID_LEVELS = ["minimal", "low", "medium", "high"];
 var VALID_CADENCES = ["off", "every_turn", "after_tool", "on_branch", "initial_then_after_tool"];
-var VALID_EFFORTS = ["minimal", "low", "medium", "high"];
+var VALID_EFFORTS = ["none", "minimal", "low", "medium", "high"];
 function validateReasoningConfig(input) {
   if (!input) return;
   if (input.level !== void 0 && !VALID_LEVELS.includes(input.level)) {
@@ -4875,11 +4875,13 @@ var StructuredOutputManager = class {
   /**
    * Build a nudge message for when the model didn't produce structured output.
    * Used by the agent loop when it needs to retry.
+   * User role is intentional: OpenAI-compatible chat templates such as Qwen
+   * reject system messages anywhere except the beginning of the conversation.
    */
   buildNudgeMessage(isLastAttempt) {
     if (this.strategy.kind === "native") {
       return {
-        role: "system",
+        role: "user",
         content: [
           "A structured output schema is active.",
           "You MUST respond with valid JSON matching the schema.",
@@ -4889,7 +4891,7 @@ var StructuredOutputManager = class {
       };
     }
     return {
-      role: "system",
+      role: "user",
       content: [
         "A structured output schema is active.",
         "You MUST now call tool `response` with the final JSON object that matches the schema.",
@@ -4907,7 +4909,7 @@ var StructuredOutputManager = class {
       const fieldIssues = error.fieldErrors.map((f) => `- "${f.path}": ${f.message} (received: ${JSON.stringify(f.received)})`).join("\n");
       const action = this.strategy.kind === "native" ? "Please output corrected JSON matching the schema." : "Please call `response` again with corrected values matching the schema.";
       return {
-        role: "system",
+        role: "user",
         content: [
           "Your previous structured output had validation errors:",
           fieldIssues,
@@ -8781,12 +8783,19 @@ function parseSSEBlock(block) {
 
 // src/providers/utils/reasoning.ts
 var ANTHROPIC_EFFORT_BUDGET = {
+  // 0 = off. `applyAnthropicReasoning` bails on a falsy budget and emits no
+  // thinking block, which on Anthropic IS off — thinking there is opt-in.
+  none: 0,
   minimal: 1024,
   low: 2048,
   medium: 8192,
   high: 16384
 };
 var GEMINI_EFFORT_BUDGET = {
+  // 0 is Gemini's own documented spelling for "do not think", and unlike
+  // Anthropic it has to be SENT — hence `applyGeminiReasoning` testing for null
+  // rather than falsiness.
+  none: 0,
   minimal: 512,
   low: 1024,
   medium: 4096,
@@ -8862,14 +8871,15 @@ function clampBudget(budget, maxTokens) {
 }
 function normalizeEffort(effort) {
   if (!effort) return void 0;
-  const allowed = ["minimal", "low", "medium", "high"];
+  const allowed = ["none", "minimal", "low", "medium", "high"];
   return allowed.includes(effort) ? effort : void 0;
 }
 function resolveBudget(reasoning, effortBudget) {
+  const effort = normalizeEffort(reasoning.effort);
+  if (effort === "none") return 0;
   if (typeof reasoning.budgetTokens === "number" && reasoning.budgetTokens > 0) {
     return Math.floor(reasoning.budgetTokens);
   }
-  const effort = normalizeEffort(reasoning.effort);
   if (effort && effortBudget[effort]) return effortBudget[effort];
   return void 0;
 }
@@ -8958,12 +8968,21 @@ var OpenAIProvider = class extends BaseProvider {
       ...config.defaultHeaders,
       ...config.organization ? { "OpenAI-Organization": config.organization } : {}
     };
+    this.responsesApi = config.responsesApi ?? "auto";
     if (config.retry) this.retryPolicy = { ...this.retryPolicy, ...config.retry };
   }
-  /** True when the request targets a reasoning model (o-series / gpt-5) so we
-   * should route through the Responses API, which exposes `reasoning.effort`
-   * and reasoning summaries. Chat Completions silently drops these. */
+  /** True when this request should go to the Responses API rather than Chat
+   * Completions — which exposes `reasoning.effort` and reasoning summaries that
+   * Chat Completions silently drops.
+   *
+   * `auto` (the default) keeps the historical rule: only when the request
+   * carries a reasoning config AND the model name looks like an o-series/gpt-5
+   * model. `never`/`always` let a caller state the answer instead, because the
+   * name check is a guess and the two APIs differ in far more than reasoning —
+   * see `responsesApi` in OpenAIProviderConfig. */
   useResponsesApi(request) {
+    if (this.responsesApi === "never") return false;
+    if (this.responsesApi === "always") return true;
     if (!request.reasoning) return false;
     return isReasoningModel(request.model || this.defaultModel);
   }
@@ -10826,7 +10845,7 @@ function fromNativeProvider(provider, options) {
     if (tools?.length) req.tools = tools;
     if (opts?.extra) req.extra = opts.extra;
     const reasoningOverride = invokeOptions?.reasoning;
-    const reasoningCfg = reasoningOverride ?? opts?.reasoning;
+    const reasoningCfg = mergeReasoning(opts?.reasoning, reasoningOverride);
     if (reasoningCfg) req.reasoning = reasoningCfg;
     const tc = invokeOptions?.tool_choice ?? invokeOptions?.toolChoice;
     if (tc && tools?.length) {
@@ -10855,6 +10874,15 @@ function fromNativeProvider(provider, options) {
     return req;
   }
 }
+function mergeReasoning(base, override) {
+  if (!base) return override;
+  if (!override) return base;
+  const merged = { ...base, ...override };
+  if (base.providerExtras || override.providerExtras) {
+    merged.providerExtras = { ...base.providerExtras, ...override.providerExtras };
+  }
+  return merged;
+}
 function toUnifiedMessage(msg) {
   const unified = {
     role: msg.role,