@tyvm/knowhow 0.0.154 → 0.0.156

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tyvm/knowhow",
-  "version": "0.0.154",
+  "version": "0.0.156",
   "description": "ai cli with plugins and agents",
   "main": "ts_build/src/index.js",
   "bin": {

package/src/agents/base/base.ts

@@ -1660,6 +1660,20 @@ export abstract class BaseAgent implements IAgent {
     return null;
   }
 
+  extractContentFromMessages(messages: Message[]): string {
+    const content = messages
+      .filter((m) => typeof m.content === "string" && m.content.trim())
+      .map((m) => m.content);
+
+    const finalAnswer = messages
+      .filter((m) => m.tool_calls?.length)
+      .flatMap((t) => t.tool_calls)
+      .filter((t) => t.function.name === "finalAnswer")
+      .map((t) => t.function.arguments);
+
+    return [...content, ...finalAnswer].join("\n\n");
+  }
+
   async getTaskBreakdown(messages: Message[]) {
     if (this.taskBreakdown) {
       return this.taskBreakdown;
@@ -1686,28 +1700,21 @@ export abstract class BaseAgent implements IAgent {
     ] as Message[];
 
     const response = await this.createAgentCompletion({
-      model,
       messages: taskBreakdownMessages,
       tool_choice: "none",
-      long_ttl_cache: this.runTime() > 300_000,
-      ...(this.reasoningEffort !== undefined && {
-        reasoning_effort: this.reasoningEffort,
-      }),
-      ...(this.summarizeReasoning !== undefined && {
-        reasoning_summary: this.summarizeReasoning,
-      }),
     });
 
+    const breakdownContent = this.extractContentFromMessages(
+      response.choices?.map((c) => c.message)
+    );
     // The model may return null content (e.g. when it responds with tool calls
     // instead of text). Guard against storing a literal null so that template
     // strings don't render "null".
-    const breakdownContent = response.choices
-      .map((c) => c.message.content)
-      .filter((s): s is string => typeof s === "string" && s.trim().length > 0)
-      .join("\n\n");
-
     if (!breakdownContent) {
-      throw new Error("Compaction task-breakdown request returned no text content");
+      console.log(JSON.stringify(response.choices, null, 2));
+      throw new Error(
+        "Compaction task-breakdown request returned no text content"
+      );
     }
 
     this.taskBreakdown = breakdownContent;
@@ -1720,10 +1727,7 @@ export abstract class BaseAgent implements IAgent {
     // at the final assistant message keeps its tool calls, every tool response,
     // and any subsequent user messages together as one protocol-valid unit.
     let resumeIndex = messages.length - 1;
-    while (
-      resumeIndex >= 0 &&
-      messages[resumeIndex].role !== "assistant"
-    ) {
+    while (resumeIndex >= 0 && messages[resumeIndex].role !== "assistant") {
       resumeIndex--;
     }
     const compressionEnd = resumeIndex === -1 ? messages.length : resumeIndex;
@@ -1742,7 +1746,11 @@ export abstract class BaseAgent implements IAgent {
     3. Next Steps - what we're about to do next to continue the user's original request.
     4. Tasks remaining - what tasks are left from the initial task breakdown.
 
-    ${this.taskBreakdown ? `Our initial task breakdown: ${this.taskBreakdown}` : ""}
+    ${
+      this.taskBreakdown
+        ? `Our initial task breakdown: ${this.taskBreakdown}`
+        : ""
+    }
 
     This summary will replace the older history. The latest agent interaction will remain verbatim:
 
@@ -1761,23 +1769,33 @@ export abstract class BaseAgent implements IAgent {
       tool_choice: "none",
     });
 
-    const summaries = response.choices
-      .map((c) => c.message.content)
-      .filter((s): s is string => typeof s === "string" && s.trim().length > 0);
-    if (summaries.length === 0) {
+    const summary = this.extractContentFromMessages(
+      response.choices?.map((c) => c.message)
+    );
+
+    if (summary.length === 0) {
+      console.log(JSON.stringify(response.choices, null, 2));
       throw new Error("Compaction summary request returned no text content");
     }
 
-    this.summaries.push(...summaries);
+    this.summaries.push(summary);
 
     const startMessages = [
       {
         role: "user",
         content: `
-        ${this.taskBreakdown ? `Initial task breakdown:\n        ${this.taskBreakdown}` : "(No task breakdown available — summarize what you know from context above)"}
+        ${
+          this.taskBreakdown
+            ? `Initial task breakdown:\n        ${this.taskBreakdown}`
+            : "(No task breakdown available — summarize what you know from context above)"
+        }
 
         We have just compressed the conversation to save memory:
-        ${summaries.length > 0 ? JSON.stringify(summaries) : "(summary unavailable — please continue from the task breakdown above)"}
+        ${
+          summary.length > 0
+            ? JSON.stringify(summary)
+            : "(summary unavailable — please continue from the task breakdown above)"
+        }
 
         Please continue the task from where we left off
         `,

package/src/agents/base/prompt.ts

@@ -4,8 +4,9 @@ You use the tools to read and write code, to help the developer implement featur
 
 # Completing your work
 
-You always call finalAnswer once you have finished implementing or answering what is requested.
-As an agent you will receive multiple rounds of input until you call finalAnswer.
+You may answer questions and provide requested information directly in your assistant message content. Content responses are valid and visible to the user; you do not need to use a tool merely to answer a question.
+Call finalAnswer only once the overall task is complete and you are ready to end the agent run. Put your final result or completion summary in that tool call.
+As an agent you may receive multiple rounds of input before you call finalAnswer.
 You are not able to request feedback from the user, so proceed with your plans and the developer will contact you afterwards if they need more help.
 
 ## Modification Guidelines

package/src/agents/tools/index.ts

@@ -13,6 +13,7 @@ export * from "./readFile";
 export * from "./scanFile";
 export * from "./textSearch";
 export * from "./visionTool";
+export * from "./loadImageAsBase64";
 export * from "./writeFile";
 export * from "./fileSearch";
 export * from "./language";

package/src/agents/tools/list.ts

@@ -20,6 +20,7 @@ import {
   stopObservingDefinition,
 } from "./observe";
 import { skillsToolDefinitions } from "./skills";
+import { loadImageAsBase64Definition } from "./loadImageAsBase64";
 
 function getPluginNames(): string {
   try {
@@ -720,6 +721,7 @@ export const includedTools = [
       },
     },
   },
+  loadImageAsBase64Definition,
   googleSearchDefinition,
   startAgentTaskDefinition,
   replyToParentDefinition,

package/src/agents/tools/loadImageAsBase64.ts

@@ -0,0 +1,83 @@
+import fs from "fs";
+import path from "path";
+import { Tool } from "../../clients/types";
+
+const MAX_IMAGE_BYTES = 15 * 1024 * 1024;
+
+const MIME_TYPES: Record<string, string> = {
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  bmp: "image/bmp",
+  svg: "image/svg+xml",
+  avif: "image/avif",
+  ico: "image/x-icon",
+};
+
+function detectMimeType(buffer: Buffer, fallback: string): string {
+  if (buffer.length >= 3 && buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff) {
+    return "image/jpeg";
+  }
+  if (buffer.length >= 4 && buffer[0] === 0x89 && buffer[1] === 0x50 && buffer[2] === 0x4e && buffer[3] === 0x47) {
+    return "image/png";
+  }
+  if (buffer.length >= 4 && buffer.subarray(0, 4).toString("ascii") === "GIF8") {
+    return "image/gif";
+  }
+  if (
+    buffer.length >= 12 &&
+    buffer.subarray(0, 4).toString("ascii") === "RIFF" &&
+    buffer.subarray(8, 12).toString("ascii") === "WEBP"
+  ) {
+    return "image/webp";
+  }
+  return fallback;
+}
+
+/** Load a reasonably sized image from the worker filesystem for UI/AI preview. */
+export async function loadImageAsBase64(
+  filePath: string,
+  detail: "auto" | "low" | "high" = "auto"
+): Promise<string> {
+  const stats = await fs.promises.stat(filePath).catch(() => null);
+  if (!stats) throw new Error(`File not found: ${filePath}`);
+  if (!stats.isFile()) throw new Error(`Path is not a file: ${filePath}`);
+  if (stats.size > MAX_IMAGE_BYTES) {
+    throw new Error(`Image is too large to preview (${Math.ceil(stats.size / 1024 / 1024)} MB; maximum 15 MB)`);
+  }
+
+  const extension = path.extname(filePath).slice(1).toLowerCase();
+  const extensionMimeType = MIME_TYPES[extension];
+  if (!extensionMimeType) {
+    throw new Error(`Unsupported image format: ${extension || "unknown"}`);
+  }
+
+  const image = await fs.promises.readFile(filePath);
+  const mimeType = detectMimeType(image, extensionMimeType);
+  return JSON.stringify({
+    type: "image_url",
+    image_url: {
+      url: `data:${mimeType};base64,${image.toString("base64")}`,
+      detail,
+    },
+  });
+}
+
+export const loadImageAsBase64Definition: Tool = {
+  type: "function",
+  function: {
+    name: "loadImageAsBase64",
+    description: "Load an image from the worker filesystem and return it as a base64 data URL for previewing.",
+    parameters: {
+      type: "object",
+      positional: true,
+      properties: {
+        filePath: { type: "string", description: "Absolute or workspace-relative image path" },
+        detail: { type: "string", enum: ["auto", "low", "high"], description: "Image detail hint" },
+      },
+      required: ["filePath"],
+    },
+  },
+};

package/src/auth/keyAuth.ts

@@ -3,9 +3,13 @@ import os from "os";
 import path from "path";
 import http from "../utils/http";
 import { getCliUserAgent } from "./browserLogin";
-import { keyPairExists, loadKeyPair, signMessage } from "./keyManager";
+import {
+  getDefaultPrivateKeyPath,
+  keyPairExists,
+  loadKeyPair,
+  signMessage,
+} from "./keyManager";
 
-const JWT_FILE_PATH = path.join(process.cwd(), ".knowhow", ".jwt");
 const DEFAULT_API_URL = process.env.KNOWHOW_API_URL || "https://api.knowhow.tyvm.ai";
 
 /**
@@ -62,15 +66,42 @@ export async function exchangePublicKeyJwt(
   return response.data.jwt;
 }
 
+/**
+ * Try the configured identity first, then the default CLI identity. Project
+ * configs can outlive temporary/custom keys, while the globally registered
+ * default identity remains valid.
+ */
+export async function exchangeAvailablePublicKeyJwt(
+  orgId: string,
+  apiUrl: string = DEFAULT_API_URL,
+  preferredPrivateKeyPath?: string
+): Promise<string> {
+  const defaultPath = getDefaultPrivateKeyPath();
+  const candidates = Array.from(
+    new Set([preferredPrivateKeyPath, defaultPath].filter((value): value is string => Boolean(value)))
+  ).filter((candidate) => keyPairExists(candidate));
+  if (candidates.length === 0) throw new Error("CLI identity is unavailable");
+
+  let lastError: unknown;
+  for (const candidate of candidates) {
+    try {
+      return await exchangePublicKeyJwt(orgId, apiUrl, candidate);
+    } catch (error) {
+      lastError = error;
+    }
+  }
+  throw lastError;
+}
+
 export async function authenticateWithKey(
   orgId: string,
   apiUrl: string = DEFAULT_API_URL,
   privateKeyPath?: string
 ): Promise<boolean> {
-  if (!keyPairExists(privateKeyPath)) return false;
+  if (!keyPairExists(privateKeyPath) && !keyPairExists()) return false;
 
   try {
-    storeJwt(await exchangePublicKeyJwt(orgId, apiUrl, privateKeyPath));
+    storeJwt(await exchangeAvailablePublicKeyJwt(orgId, apiUrl, privateKeyPath));
     return true;
   } catch (error: unknown) {
     // The identity is not registered for this environment/org (or was revoked).
@@ -108,13 +139,14 @@ export async function registerPublicKey(
 }
 
 export function storeJwt(jwt: string): void {
-  const directory = path.dirname(JWT_FILE_PATH);
-  const temporaryPath = `${JWT_FILE_PATH}.${process.pid}.tmp`;
+  const jwtFilePath = path.join(process.cwd(), ".knowhow", ".jwt");
+  const directory = path.dirname(jwtFilePath);
+  const temporaryPath = `${jwtFilePath}.${process.pid}.tmp`;
   fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
   try {
     fs.writeFileSync(temporaryPath, jwt, { mode: 0o600, flag: "wx" });
-    fs.renameSync(temporaryPath, JWT_FILE_PATH);
-    fs.chmodSync(JWT_FILE_PATH, 0o600);
+    fs.renameSync(temporaryPath, jwtFilePath);
+    fs.chmodSync(jwtFilePath, 0o600);
   } finally {
     fs.rmSync(temporaryPath, { force: true });
   }

package/src/chat/modules/AgentModule.ts

@@ -67,6 +67,9 @@ export class AgentModule extends BaseChatModule {
   /** Whether to request a reasoning summary from supporting models */
   private summarizeReasoning: boolean = true;
 
+  /** Delayed finalAnswer output, cancelled when the task's done event arrives. */
+  private pendingFinalAnswers = new Map<string, ReturnType<typeof setTimeout>>();
+
   /** Stored wire params for rewireAgentRendering */
   private _wireAgentEvents: EventService | undefined;
   private _wireTaskId: string | undefined;
@@ -514,6 +517,28 @@ export class AgentModule extends BaseChatModule {
     this.activeAgentTaskId = id;
   }
 
+  private scheduleFinalAnswer(taskId: string, answer: unknown): void {
+    this.cancelFinalAnswer(taskId);
+    const renderedAnswer = typeof answer === "string"
+      ? answer
+      : JSON.stringify(answer) ?? String(answer);
+    const timeout = setTimeout(() => {
+      this.pendingFinalAnswers.delete(taskId);
+      console.log(Marked.parse(renderedAnswer));
+    }, 50);
+    this.pendingFinalAnswers.set(taskId, timeout);
+  }
+
+  private cancelFinalAnswer(taskId: string): void {
+    const timeout = this.pendingFinalAnswers.get(taskId);
+    if (!timeout) {
+      return;
+    }
+
+    clearTimeout(timeout);
+    this.pendingFinalAnswers.delete(taskId);
+  }
+
   /**
    * Wire up agentEvents to the renderer for a given task.
    * Uses setListener with stable keys so re-calling automatically replaces old listeners.
@@ -549,16 +574,27 @@ export class AgentModule extends BaseChatModule {
     if (eventTypes.toolUsed) {
       agentEvents.setListener(
         { key: "agentModule:render:toolUsed", event: eventTypes.toolUsed },
-        (data: any) =>
+        (data: any) => {
           this.renderer.render({
             type: "toolResult",
             taskId,
             agentName,
             toolCall: data.toolCall,
             result: data.functionResp,
-          })
+          });
+          // Give the done event a chance to render the same answer first. If the
+          // agent continues, the tool result becomes the fallback output.
+          const toolName: string = data.toolCall?.function?.name ?? "";
+          if (toolName === "finalAnswer" || toolName.endsWith("finalAnswer")) {
+            this.scheduleFinalAnswer(taskId, data.functionResp);
+          }
+        }
       );
     }
+    agentEvents.setListener(
+      { key: "agentModule:render:done", event: eventTypes.done },
+      () => this.cancelFinalAnswer(taskId)
+    );
     if (eventTypes.agentSay) {
       agentEvents.setListener(
         { key: "agentModule:render:agentSay", event: eventTypes.agentSay },
@@ -589,6 +625,9 @@ export class AgentModule extends BaseChatModule {
    * Clears the active task on the renderer.
    */
   public unwireAgentRendering(): void {
+    if (this._wireTaskId) {
+      this.cancelFinalAnswer(this._wireTaskId);
+    }
     if (this._wireAgentEvents) {
       this._wireAgentEvents.removeManagedListenersByPrefix(
         "agentModule:render:"
@@ -681,8 +720,14 @@ export class AgentModule extends BaseChatModule {
         console.error(`Session ${sessionId} not found.`);
         return;
       }
+      // Session files from older runs may not contain model/provider settings.
+      // Prefer task metadata, which is updated from the live agent on every
+      // thread update and is therefore the authoritative resume configuration.
+      const savedSettings = await this.loadTaskSettings(
+        session.taskId || sessionId
+      );
       console.log(`\n🔄 Resuming session: ${sessionId}`);
-      console.log(`Agent: ${session.agentName}`);
+      console.log(`Agent: ${savedSettings.agentName || session.agentName}`);
       console.log(`Original task: ${session.initialInput}`);
       console.log(`Status: ${session.status}`);
 
@@ -726,7 +771,8 @@ export class AgentModule extends BaseChatModule {
 
       console.log("🚀 Session resuming...");
       const context = this.chatService?.getContext();
-      const agentName = session.agentName || context.currentAgent;
+      const agentName =
+        savedSettings.agentName || session.agentName || context.currentAgent;
       const previousAgentMode = context?.agentMode;
 
       if (!agentName) {
@@ -738,7 +784,9 @@ export class AgentModule extends BaseChatModule {
       // not reject config-defined agents here before it gets that opportunity.
 
       // Start agent with Knowhow task context and restored message history
-      const remoteTaskId = asRemoteTaskId(session.knowhowTaskId);
+      const remoteTaskId = asRemoteTaskId(
+        savedSettings.remoteTaskId || session.knowhowTaskId
+      );
       const { agent, taskId } = await this.setupAgent({
         agentName,
         input: resumePrompt,
@@ -751,12 +799,12 @@ export class AgentModule extends BaseChatModule {
         taskId: session.taskId || sessionId,
         chatHistory: [],
         run: false, // Don't run yet, we need to set up event listeners first
-        // Restore the exact model/provider/reasoning the original run used.
-        model: session.model,
-        provider: session.provider,
-        reasoningEffort: session.reasoningEffort,
-        summarizeReasoning: session.summarizeReasoning,
-        enabledTools: session.enabledTools,
+        // Prefer authoritative task metadata over potentially incomplete sessions.
+        model: savedSettings.model || session.model,
+        provider: savedSettings.provider || session.provider,
+        reasoningEffort: savedSettings.reasoningEffort ?? session.reasoningEffort,
+        summarizeReasoning: savedSettings.summarizeReasoning ?? session.summarizeReasoning,
+        enabledTools: savedSettings.enabledTools || session.enabledTools,
       });
 
       // Match new interactive threads: local-only sessions get a fresh remote
@@ -871,6 +919,34 @@ export class AgentModule extends BaseChatModule {
       agent.restoreEnabledTools(options.enabledTools);
     }
 
+    // Restore persisted configuration before registering or saving this task.
+    // Otherwise the newly constructed agent's defaults can overwrite the
+    // original run settings during resume setup.
+    if (options.model) {
+      console.log("Setting model:", options.model);
+      agent.setModel(options.model);
+      agent.setModelPreferences([
+        { model: options.model, provider: options.provider as any },
+      ]);
+    }
+
+    if (options.provider) {
+      agent.setProvider(options.provider as any);
+    }
+
+    const effectiveReasoningEffort =
+      options.reasoningEffort !== undefined
+        ? options.reasoningEffort
+        : this.reasoningEffort;
+    if (effectiveReasoningEffort !== undefined) {
+      agent.setReasoningEffort(effectiveReasoningEffort);
+    }
+    agent.setSummarizeReasoning(
+      options.summarizeReasoning !== undefined
+        ? options.summarizeReasoning
+        : this.summarizeReasoning
+    );
+
     let done = false;
     let output = "Done";
     const taskId = options.taskId || this.sessionManager.generateTaskId(input);
@@ -907,6 +983,10 @@ export class AgentModule extends BaseChatModule {
         startTime: Date.now(),
         totalCost: 0,
         enabledTools: agent.getEnabledToolNames(),
+        model: agent.getModel(),
+        provider: agent.getProvider(),
+        reasoningEffort: agent.getReasoningEffort?.(),
+        summarizeReasoning: agent.getSummarizeReasoning?.(),
       };
 
       // Add to task registry
@@ -967,37 +1047,6 @@ export class AgentModule extends BaseChatModule {
         agent.setParentTaskId(options.parentTaskId);
       }
 
-      if (options.model) {
-        console.log("Setting model:", options.model);
-        agent.setModel(options.model);
-        agent.setModelPreferences([
-          { model: options.model, provider: options.provider as any },
-        ]);
-      }
-
-      // Restore the provider explicitly (e.g. on resume) so the agent talks to
-      // the same client the original run used, not the model's default provider.
-      if (options.provider) {
-        agent.setProvider(options.provider as any);
-      }
-
-      // Apply reasoning settings to the agent. Explicit per-task settings
-      // (e.g. restored from a resumed task's metadata) take precedence over
-      // the module-level CLI defaults so a /resume keeps the same reasoning
-      // effort the original run used.
-      const effectiveReasoningEffort =
-        options.reasoningEffort !== undefined
-          ? options.reasoningEffort
-          : this.reasoningEffort;
-      if (effectiveReasoningEffort !== undefined) {
-        agent.setReasoningEffort(effectiveReasoningEffort);
-      }
-      agent.setSummarizeReasoning(
-        options.summarizeReasoning !== undefined
-          ? options.summarizeReasoning
-          : this.summarizeReasoning
-      );
-
       // Set up message processors like in original startAgent
 
       // Register an override for askHuman to use CLI input method
@@ -1097,6 +1146,12 @@ export class AgentModule extends BaseChatModule {
           toolCall: data.toolCall,
           result: data.functionResp,
         });
+        // Give the done event a chance to render the same answer first. If the
+        // agent continues, the tool result becomes the fallback output.
+        const toolName: string = data.toolCall?.function?.name ?? "";
+        if (toolName === "finalAnswer" || toolName.endsWith("finalAnswer")) {
+          this.scheduleFinalAnswer(taskId, data.functionResp);
+        }
       };
       const agentSayHandler = (data: any) => {
         this.renderer.render({
@@ -1130,6 +1185,7 @@ export class AgentModule extends BaseChatModule {
       const taskCompleted = new Promise<string>((resolve) => {
         agent.agentEvents.once(agent.eventTypes.done, async (doneMsg) => {
           console.log("🎯 [AgentModule] Task Completed");
+          this.cancelFinalAnswer(taskId);
           done = true;
           output = doneMsg || "No response from the AI";
           // Remove threadUpdate listener to prevent cost sharing across tasks

package/src/clients/index.ts

@@ -28,8 +28,9 @@ import { GenericXAIClient } from "./xai";
 import { KnowhowGenericClient } from "./knowhow";
 import { HttpClient } from "./http";
 import { ModelProvider } from "../types";
-import { getConfig } from "../config";
+import { getConfig, getConfigSync } from "../config";
 import { loadKnowhowJwt, KNOWHOW_API_URL } from "../services/KnowhowClient";
+import { keyPairExists } from "../auth/keyManager";
 import { ContextLimits } from "./contextLimits";
 import { OpenAiTextPricing } from "./pricing/openai";
 import { AnthropicTextPricing } from "./pricing/anthropic";
@@ -108,9 +109,11 @@ const BUILT_IN_PROVIDER_REGISTRY: Record<string, ProviderRegistryEntry> = {
   qwen: { clientClass: GenericQwenClient },
   knowhow: {
     createClient: (entry: ModelProvider) => {
-      const jwt = loadKnowhowJwt();
-      if (!jwt) return null;
-      return new KnowhowGenericClient(KNOWHOW_API_URL, jwt);
+      if (!loadKnowhowJwt()) {
+        const config = getConfigSync();
+        if (!config.orgId || (!keyPairExists(config.cliIdentityPath) && !keyPairExists())) return null;
+      }
+      return new KnowhowGenericClient(KNOWHOW_API_URL);
     },
   },
 };

package/src/clients/openai.ts

@@ -495,13 +495,19 @@ export class GenericOpenAiClient implements GenericClient {
         include: ["reasoning.encrypted_content"],
       }),
       // Don't limit max_output_tokens for Responses API - codex truncates tool call arguments when limited
-      ...(OpenAiReasoningModels.includes(options.model) && !this.isReasoningDisabled(options) && {
-        max_output_tokens: Math.max(options.max_tokens || 0, 16000),
+      ...(OpenAiReasoningModels.includes(options.model) && {
         reasoning: {
-          effort: this.resolveReasoningEffortForModel(options),
-          ...(options.reasoning_summary && { summary: "auto" }),
+          ...(this.isReasoningDisabled(options)
+            ? { effort: "none" }
+            : {
+                effort: this.resolveReasoningEffortForModel(options),
+                ...(options.reasoning_summary && { summary: "auto" }),
+              }),
         },
       }),
+      ...(wantsReasoning && {
+        max_output_tokens: Math.max(options.max_tokens || 0, 16000),
+      }),
       ...(tools?.length && {
         tools,
         tool_choice: options.tool_choice ?? "auto",
@@ -582,6 +588,33 @@ export class GenericOpenAiClient implements GenericClient {
       }
     }
 
+    // Tool-only responses are valid agent turns. Warn only when the response
+    // contains neither visible text nor any callable output, and include enough
+    // provider metadata to diagnose incomplete or reasoning-only responses.
+    if (!textContent?.trim() && toolCalls.length === 0) {
+      const outputShape = response.output.map((item: any) => ({
+        type: item.type,
+        contentTypes: Array.isArray(item.content)
+          ? item.content.map((part: any) => part?.type ?? typeof part)
+          : [],
+      }));
+      const reasoningSummaryCount = response.output
+        .filter((item: any) => item.type === "reasoning")
+        .reduce(
+          (count: number, item: any) =>
+            count + (Array.isArray(item.summary) ? item.summary.length : 0),
+          0
+        );
+      console.warn("[Responses API] Response contained no text or tool calls", {
+        responseId: (response as any).id,
+        status: (response as any).status,
+        incompleteDetails: (response as any).incomplete_details,
+        outputShape,
+        reasoningSummaryCount,
+        usage: response.usage,
+      });
+    }
+
     return {
       choices: [
         {