@tyvm/knowhow 0.0.155 → 0.0.157

package/src/clients/openrouter.ts

@@ -1,4 +1,5 @@
-import { HttpClient } from "./http";
+import { HttpClient, HttpClientOptions } from "./http";
+import { withKnowhowAttribution } from "./attribution";
 import { OpenRouterTextPricing } from "./pricing/openrouter";
 
 /**
@@ -9,8 +10,14 @@ import { OpenRouterTextPricing } from "./pricing/openrouter";
  * Set env var OPENROUTER_API_KEY to enable.
  */
 export class GenericOpenRouterClient extends HttpClient {
-  constructor(apiKey = process.env.OPENROUTER_API_KEY) {
-    super("https://openrouter.ai/api");
+  constructor(
+    apiKey = process.env.OPENROUTER_API_KEY,
+    transportOptions: HttpClientOptions = {}
+  ) {
+    super("https://openrouter.ai/api", {
+      ...transportOptions,
+      headers: withKnowhowAttribution(transportOptions.headers),
+    });
     if (apiKey) this.setJwt(apiKey);
     this.setPrices(OpenRouterTextPricing);
   }

package/src/clients/pricing/openai.ts

@@ -231,7 +231,21 @@ export const OpenAiSearchModels: string[] = [
 
 export const OpenAiTextPricing: Record<string, ModelPricing> = {
   // gpt-5.6 series — short context / long context pricing
-  [OpenAiModels.GPT_56_Sol]:   { input: 5.0, cached_input: 0.5,  cache_write: 6.25,  output: 30.0, input_gt_200k: 10.0, output_gt_200k: 45.0 },
+  [OpenAiModels.GPT_56_Sol]: {
+    input: 4.0,
+    cached_input: 0.40,
+    cache_write: 5.00,
+    output: 30.0,
+    input_gt_200k: 10.0,
+    output_gt_200k: 30.0,
+    changelog: [
+      {
+        date: "2026-08-01",
+        note: "Launch pricing — promotional rates available through November 21, 2026",
+        pricing: { input: 5.0, cached_input: 0.5, cache_write: 6.25, output: 30.0, input_gt_200k: 10.0, output_gt_200k: 45.0 },
+      },
+    ],
+  },
   [OpenAiModels.GPT_56_Terra]: { input: 2.0, cached_input: 0.20, cache_write: 2.5,   output: 12.0, input_gt_200k: 4.0,  output_gt_200k: 18.0 },
   [OpenAiModels.GPT_56_Luna]:  { input: 0.2, cached_input: 0.02, cache_write: 0.25,  output: 1.2,  input_gt_200k: 0.4,  output_gt_200k: 1.8  },
   [OpenAiModels.GPT_55]: { input: 5.0, cached_input: 0.5, output: 30.0 },

package/src/clients/pricing/types.ts

@@ -1,3 +1,16 @@
+/**
+ * A historical record of a model's pricing at a point in time.
+ * Use this to track price changes over time.
+ */
+export interface PricingChangelogEntry {
+  /** ISO date string when this pricing became effective (e.g. "2025-04-01") */
+  date: string;
+  /** Optional human-readable note about the change (e.g. "Promotional pricing announcement") */
+  note?: string;
+  /** The pricing values that were in effect from this date */
+  pricing: Omit<ModelPricing, "deprecated" | "deprecationDate" | "limitedAvailability" | "replacedBy" | "reasoningLevels" | "useResponsesApi" | "changelog">;
+}
+
 export type ModelType =
   | "completion"
   | "embedding"
@@ -30,6 +43,8 @@ export interface ModelPricing {
   reasoningLevels?: string[];
   /** If true, this model must be called via the Responses API (/v1/responses) instead of /v1/chat/completions */
   useResponsesApi?: boolean;
+  /** Optional changelog of historical pricing entries, ordered from oldest to newest */
+  changelog?: PricingChangelogEntry[];
 }
 
 export interface ModelCatalogEntry {

package/src/clients/responseMetadata.ts

@@ -0,0 +1,221 @@
+import {
+  ProviderRateLimitMetadata,
+  ProviderResponseMetadata,
+  RetryOptions,
+} from "./types";
+
+const MAX_HEADER_VALUE_LENGTH = 256;
+const MAX_HEADERS = 24;
+const MAX_TOTAL_HEADER_CHARS = 4096;
+const SAFE_HEADER_NAMES = new Set([
+  "retry-after",
+  "ratelimit-limit",
+  "ratelimit-remaining",
+  "ratelimit-reset",
+  "request-id",
+  "x-request-id",
+  "cf-ray",
+  "x-amzn-requestid",
+  "x-amz-request-id",
+]);
+const SAFE_HEADER_PREFIXES = ["x-ratelimit-", "anthropic-ratelimit-"];
+
+type HeaderSource =
+  | Headers
+  | Record<string, unknown>
+  | Iterable<[string, unknown]>
+  | undefined;
+
+function isSafeHeader(name: string) {
+  return (
+    SAFE_HEADER_NAMES.has(name) ||
+    SAFE_HEADER_PREFIXES.some((prefix) => name.startsWith(prefix))
+  );
+}
+
+function entriesFor(headers: HeaderSource): Iterable<[string, unknown]> {
+  if (!headers) return [];
+  if (Symbol.iterator in Object(headers)) {
+    return headers as Iterable<[string, unknown]>;
+  }
+  if (typeof (headers as Headers).forEach === "function") {
+    const entries: Array<[string, unknown]> = [];
+    (headers as Headers).forEach((value, name) => entries.push([name, value]));
+    return entries;
+  }
+  return Object.entries(headers as Record<string, unknown>);
+}
+
+function nonNegativeNumber(value: string | undefined) {
+  if (value === undefined || value.trim() === "") return undefined;
+  const number = Number(value);
+  return Number.isFinite(number) && number >= 0 ? number : undefined;
+}
+
+function resetAt(value: string | undefined, now: Date) {
+  if (!value) return undefined;
+  const seconds = nonNegativeNumber(value);
+  if (seconds !== undefined)
+    return new Date(now.getTime() + seconds * 1000).toISOString();
+
+  // OpenAI-compatible APIs commonly return compact durations such as `6m0s`.
+  const duration = [...value.trim().matchAll(/(\d+(?:\.\d+)?)(ms|s|m|h|d)/gi)];
+  if (
+    duration.length &&
+    duration.map((part) => part[0]).join("") === value.trim()
+  ) {
+    const milliseconds = duration.reduce((total, [, amount, unit]) => {
+      const multiplier = {
+        ms: 1,
+        s: 1_000,
+        m: 60_000,
+        h: 3_600_000,
+        d: 86_400_000,
+      }[unit.toLowerCase()];
+      return total + Number(amount) * multiplier;
+    }, 0);
+    return new Date(now.getTime() + milliseconds).toISOString();
+  }
+
+  const timestamp = Date.parse(value);
+  return Number.isNaN(timestamp)
+    ? undefined
+    : new Date(timestamp).toISOString();
+}
+
+function retryAfterSeconds(value: string | undefined, now: Date) {
+  const seconds = nonNegativeNumber(value);
+  if (seconds !== undefined) return seconds;
+  if (!value) return undefined;
+  const timestamp = Date.parse(value);
+  return Number.isNaN(timestamp)
+    ? undefined
+    : Math.max(0, (timestamp - now.getTime()) / 1000);
+}
+
+/**
+ * Derives one JSON-safe shape from standard, OpenAI-compatible, and Anthropic
+ * rate-limit headers. Callers receive this even when a provider supplied none.
+ */
+export function normalizeRateLimitMetadata(
+  headers: Record<string, string>,
+  now = new Date()
+): ProviderRateLimitMetadata {
+  const header = (...names: string[]) =>
+    names.map((name) => headers[name]).find((value) => value !== undefined);
+  const limit = nonNegativeNumber(
+    header(
+      "anthropic-ratelimit-requests-limit",
+      "ratelimit-limit",
+      "x-ratelimit-limit-requests",
+      "x-ratelimit-limit"
+    )
+  );
+  const remaining = nonNegativeNumber(
+    header(
+      "anthropic-ratelimit-requests-remaining",
+      "ratelimit-remaining",
+      "x-ratelimit-remaining-requests",
+      "x-ratelimit-remaining"
+    )
+  );
+  const requestResetAt = resetAt(
+    header(
+      "anthropic-ratelimit-requests-reset",
+      "ratelimit-reset",
+      "x-ratelimit-reset-requests",
+      "x-ratelimit-reset"
+    ),
+    now
+  );
+  const tokenLimit = nonNegativeNumber(
+    header("anthropic-ratelimit-tokens-limit", "x-ratelimit-limit-tokens")
+  );
+  const tokenRemaining = nonNegativeNumber(
+    header(
+      "anthropic-ratelimit-tokens-remaining",
+      "x-ratelimit-remaining-tokens"
+    )
+  );
+  const tokenResetAt = resetAt(
+    header("anthropic-ratelimit-tokens-reset", "x-ratelimit-reset-tokens"),
+    now
+  );
+  const retryAfter = retryAfterSeconds(header("retry-after"), now);
+  return {
+    ...(limit !== undefined && { limit }),
+    ...(remaining !== undefined && { remaining }),
+    ...(requestResetAt && { resetAt: requestResetAt }),
+    ...(retryAfter !== undefined && { retryAfterSeconds: retryAfter }),
+    ...(tokenLimit !== undefined && { tokenLimit }),
+    ...(tokenRemaining !== undefined && { tokenRemaining }),
+    ...(tokenResetAt && { tokenResetAt }),
+  };
+}
+
+/**
+ * Converts provider headers to the deliberately small telemetry-safe surface.
+ * This function never returns request bodies, credentials, cookies, or arbitrary
+ * provider headers.
+ */
+export function normalizeResponseMetadata(input: {
+  statusCode?: number;
+  headers?: HeaderSource;
+  requestId?: string | null;
+  observedAt?: Date;
+}): ProviderResponseMetadata {
+  const headers: Record<string, string> = {};
+  let totalChars = 0;
+
+  for (const [rawName, rawValue] of entriesFor(input.headers)) {
+    const name = String(rawName).toLowerCase();
+    if (
+      !isSafeHeader(name) ||
+      Object.prototype.hasOwnProperty.call(headers, name)
+    )
+      continue;
+    const value = String(rawValue).slice(0, MAX_HEADER_VALUE_LENGTH);
+    if (
+      Object.keys(headers).length >= MAX_HEADERS ||
+      totalChars + name.length + value.length > MAX_TOTAL_HEADER_CHARS
+    )
+      break;
+    headers[name] = value;
+    totalChars += name.length + value.length;
+  }
+
+  const requestId =
+    input.requestId ??
+    headers["request-id"] ??
+    headers["x-request-id"] ??
+    headers["x-amzn-requestid"] ??
+    headers["x-amz-request-id"];
+  return {
+    ...(typeof input.statusCode === "number" && {
+      statusCode: input.statusCode,
+    }),
+    rateLimit: normalizeRateLimitMetadata(headers, input.observedAt),
+    ...(Object.keys(headers).length > 0 && { headers }),
+    ...(requestId && {
+      requestId: String(requestId).slice(0, MAX_HEADER_VALUE_LENGTH),
+    }),
+  };
+}
+
+/** Emits one visible HTTP response synchronously and isolates observer failures. */
+export function emitResponseMetadata(
+  options: Pick<RetryOptions, "onResponseMetadata"> | undefined,
+  input: {
+    statusCode?: number;
+    headers?: HeaderSource;
+    requestId?: string | null;
+  }
+) {
+  const observer = options?.onResponseMetadata;
+  if (!observer) return;
+  try {
+    observer(normalizeResponseMetadata(input));
+  } catch {
+    // Observability must never affect a provider request or its original error.
+  }
+}

package/src/clients/types.ts

@@ -104,6 +104,36 @@ export interface Tool {
   };
 }
 
+/**
+ * Provider-neutral rate-limit information derived from response headers.
+ * Reset values are ISO-8601 strings so callback payloads remain JSON-safe.
+ */
+export interface ProviderRateLimitMetadata {
+  limit?: number;
+  remaining?: number;
+  resetAt?: string;
+  retryAfterSeconds?: number;
+  tokenLimit?: number;
+  tokenRemaining?: number;
+  tokenResetAt?: string;
+}
+
+/**
+ * Safe telemetry details for one provider response. `rateLimit` is normalized
+ * by the client for every observed response. `headers`, when present, contains
+ * only the bounded allowlisted raw headers used to derive it.
+ */
+export interface ProviderResponseMetadata {
+  statusCode?: number;
+  rateLimit: ProviderRateLimitMetadata;
+  headers?: Record<string, string>;
+  requestId?: string;
+}
+
+export type ProviderResponseMetadataObserver = (
+  metadata: ProviderResponseMetadata
+) => void;
+
 export interface ToolCall {
   id: string;
   type: "function";
@@ -134,6 +164,11 @@ export interface RetryOptions {
    * attempt is cancelled immediately and no further retries are made.
    */
   signal?: AbortSignal;
+  /**
+   * Synchronous observer invoked once for each provider HTTP response visible to
+   * this client, including errors and streaming handshakes.
+   */
+  onResponseMetadata?: ProviderResponseMetadataObserver;
 }
 
 /**
@@ -150,10 +185,13 @@ export const REASONING_EFFORTS = [
   "xhigh",
   "max",
 ] as const;
-export type ReasoningEffort = (typeof REASONING_EFFORTS)[number];
+export type ReasoningEffort = typeof REASONING_EFFORTS[number];
 
 export function isReasoningEffort(value: unknown): value is ReasoningEffort {
-  return typeof value === "string" && REASONING_EFFORTS.includes(value as ReasoningEffort);
+  return (
+    typeof value === "string" &&
+    REASONING_EFFORTS.includes(value as ReasoningEffort)
+  );
 }
 
 export interface CompletionOptions extends RetryOptions {
@@ -438,7 +476,9 @@ export interface GenericClient {
   setKey(key: string): void;
   createChatCompletion(options: CompletionOptions): Promise<CompletionResponse>;
   /** Optional streaming variant — yields incremental tokens then a final done chunk. */
-  createChatCompletionStream?(options: CompletionOptions): AsyncGenerator<StreamChunk>;
+  createChatCompletionStream?(
+    options: CompletionOptions
+  ): AsyncGenerator<StreamChunk>;
   createEmbedding(options: EmbeddingOptions): Promise<EmbeddingResponse>;
   createAudioTranscription?(
     options: AudioTranscriptionOptions
@@ -482,5 +522,10 @@ export interface GenericClient {
    * Returns undefined for a specific model if no pricing is known.
    * Only implemented by HttpClient-based providers that have been given a pricing map via setPrices().
    */
-  getPricing?(model?: string): import("./pricing/types").ModelPricing | Record<string, import("./pricing/types").ModelPricing> | undefined;
+  getPricing?(
+    model?: string
+  ):
+    | import("./pricing/types").ModelPricing
+    | Record<string, import("./pricing/types").ModelPricing>
+    | undefined;
 }

package/src/commands/services.ts

@@ -69,32 +69,37 @@ export async function setupServices() {
 
   Agents.setAgentContext(agentContext);
 
-  console.log("🔌 Connecting to MCP...");
-  try {
-    await Mcp.connectToConfigured(Tools);
-  } catch (mcpError) {
-    const msg = mcpError instanceof Error ? mcpError.message : String(mcpError);
-    console.warn(
-      `⚠ Some MCP servers failed to connect (continuing without them): ${msg}`
-    );
-  }
-  // Attempt silent JWT refresh via SSH identity before registering models.
-  // This handles the case where the JWT has expired but the user has a valid
-  // SSH identity registered — they shouldn't need to run `knowhow login` again
-  // unless they want to switch organizations.
+  // Refresh authentication before MCP transports, model clients, or remote
+  // sync modules can read the project JWT file.
   try {
     const startupConfig = getConfigSync();
     if (startupConfig.orgId && !process.env.KNOWHOW_JWT) {
-      await authenticateWithKey(
+      const refreshed = await authenticateWithKey(
         startupConfig.orgId,
         process.env.KNOWHOW_API_URL || "https://api.knowhow.tyvm.ai",
         startupConfig.cliIdentityPath
       );
+      if (!refreshed) {
+        console.warn(
+          `⚠ Could not renew the Knowhow session: no available CLI identity is registered ` +
+          `for configured organization ${startupConfig.orgId}. Run \`knowhow login\` to select ` +
+          `an organization and register the global identity.`
+        );
+      }
     }
-  } catch (_err) {
-    // Non-fatal: if SSH refresh fails (no key, revoked, network issue), we
-    // continue with the existing JWT (or no JWT). The user will see model
-    // warnings if no valid JWT is available.
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn(`⚠ Could not renew the Knowhow session before startup: ${message}`);
+  }
+
+  console.log("🔌 Connecting to MCP...");
+  try {
+    await Mcp.connectToConfigured(Tools);
+  } catch (mcpError) {
+    const msg = mcpError instanceof Error ? mcpError.message : String(mcpError);
+    console.warn(
+      `⚠ Some MCP servers failed to connect (continuing without them): ${msg}`
+    );
   }
 
   console.log("Connecting to clients...");

package/src/login.ts

@@ -1,12 +1,13 @@
 import http from "./utils/http";
 import fs from "fs";
+import os from "os";
 import path from "path";
 import { ask } from "./utils";
 import { getConfig, updateConfig } from "./config";
 import { KNOWHOW_API_URL } from "./services/KnowhowClient";
 import { BrowserLoginService } from "./auth/browserLogin";
 import { authenticateWithKey, hasKeyPair, registerPublicKey } from "./auth/keyAuth";
-import { getOrCreatePublicKey } from "./auth/keyManager";
+import { getDefaultPrivateKeyPath, getOrCreatePublicKey } from "./auth/keyManager";
 
 /**
  * Log in to Knowhow.
@@ -40,18 +41,19 @@ export async function login(jwtFlag?: boolean, identityPath?: string): Promise<v
     fs.chmodSync(jwtFile, 0o600);
     console.log("JWT updated successfully.");
   } else {
+    const selectedIdentityPath = identityPath ?? getDefaultPrivateKeyPath();
     const config = await getConfig();
     const orgId = config.orgId;
 
     // A local key is not proof of registration. Let the selected environment
     // check it, but only when an organization is available to bind the attempt.
-    if (orgId && hasKeyPair(identityPath)) {
+    if (orgId && hasKeyPair(selectedIdentityPath)) {
       console.log("Found CLI identity — authenticating with public key...");
       try {
-        const success = await authenticateWithKey(orgId, KNOWHOW_API_URL, identityPath);
+        const success = await authenticateWithKey(orgId, KNOWHOW_API_URL, selectedIdentityPath);
         if (success) {
           console.log("✅ Successfully authenticated via public key!");
-          return await postLoginConfigUpdate(identityPath);
+          return await postLoginConfigUpdate(selectedIdentityPath);
         }
         console.warn("Key authentication returned no JWT, falling back to browser login...");
       } catch (error: unknown) {
@@ -61,7 +63,8 @@ export async function login(jwtFlag?: boolean, identityPath?: string): Promise<v
     }
 
     // Fall back when no org/key is configured or when key auth is unavailable.
-    await doBrowserLogin(identityPath);
+    await doBrowserLogin(selectedIdentityPath);
+    identityPath = selectedIdentityPath;
   }
 
   await postLoginConfigUpdate(identityPath);
@@ -101,6 +104,15 @@ async function doBrowserLogin(identityPath?: string): Promise<void> {
   }
 }
 
+function isTemporaryIdentityPath(identityPath: string): boolean {
+  const resolvedIdentity = path.resolve(identityPath);
+  const temporaryRoots = new Set([os.tmpdir(), "/tmp", "/var/tmp"]);
+  return Array.from(temporaryRoots).some((temporaryRoot) => {
+    const relativePath = path.relative(path.resolve(temporaryRoot), resolvedIdentity);
+    return relativePath !== "" && !relativePath.startsWith("..") && !path.isAbsolute(relativePath);
+  });
+}
+
 /** After any successful login, update the local config with the current user/org. */
 async function postLoginConfigUpdate(identityPath?: string): Promise<void> {
   try {
@@ -129,8 +141,12 @@ async function postLoginConfigUpdate(identityPath?: string): Promise<void> {
       config.orgId = orgId;
     }
 
-    if (identityPath) {
+    if (identityPath && !isTemporaryIdentityPath(identityPath)) {
       config.cliIdentityPath = path.resolve(identityPath);
+    } else if (
+      config.cliIdentityPath && isTemporaryIdentityPath(config.cliIdentityPath)
+    ) {
+      delete config.cliIdentityPath;
     }
 
     await updateConfig(config);

package/src/processors/Base64ImageDetector.ts

@@ -316,25 +316,26 @@ export class Base64ImageProcessor {
 
   createProcessor(): MessageProcessorFunction {
     return (originalMessages: Message[], modifiedMessages: Message[]) => {
-      // Only process the last (newest) message for hint injection.
-      // Processing all historical messages on every call would re-append hints
-      // to already-processed messages, causing the hint to multiply and busting
-      // Anthropic's prefix cache (which requires byte-identical prior messages).
       const lastIndex = modifiedMessages.length - 1;
       if (lastIndex < 0) return;
 
       const lastMessage = modifiedMessages[lastIndex];
 
-      // Process user messages (images from user input)
-      if (lastMessage.role === "user") {
-        this.processMessageContent(lastMessage);
+      // Every request starts with a fresh clone of the persisted thread. Normalize
+      // all images: parallel calls can place another tool result after an image,
+      // while historical image results remain persisted as JSON strings.
+      for (const message of modifiedMessages) {
+        if (message.role === "user") {
+          this.processMessageContent(message);
+        }
+        if (message.role === "tool") {
+          this.processToolMessageContent(message);
+        }
       }
 
-      // Process tool messages (images from loadImageAsBase64 tool)
-      // Tool responses come back as JSON strings that need to be parsed
-      // and converted to proper image content before the agent sees them
+      // Add path hints only to the newest message. Re-appending hints to history
+      // would multiply them and invalidate the provider's prompt cache.
       if (lastMessage.role === "tool") {
-        this.processToolMessageContent(lastMessage);
         // After processing tool content (which may not convert to image if it's plain text
         // describing a screenshot path), add hints for any image file paths found in the text.
         this.applyImagePathHintsToMessage(lastMessage);

package/src/tunnel.ts

@@ -14,8 +14,9 @@ const PROD_TUNNEL_WORKER_DOMAIN = "worker.tyvm-apps.com";
 
 /**
  * Resolve the tunnel domain and protocol from the environment and API URL.
- * TUNNEL_WORKER_DOMAIN takes precedence. Otherwise dev API URLs use the dev
- * tunnel domain and all other API URLs use the production tunnel domain.
+ * TUNNEL_WORKER_DOMAIN takes precedence. Otherwise localhost API URLs use the
+ * local tunnel proxy, dev API URLs use the dev tunnel domain, and all other API
+ * URLs use the production tunnel domain.
  */
 export function extractTunnelDomain(apiUrl: string): {
   domain: string;
@@ -26,10 +27,19 @@ export function extractTunnelDomain(apiUrl: string): {
     const useHttps = url.protocol === "https:";
     const configuredDomain = process.env.TUNNEL_WORKER_DOMAIN?.trim();
 
+    const isLocalApi =
+      url.hostname === "localhost" ||
+      url.hostname.endsWith(".localhost") ||
+      url.hostname === "127.0.0.1" ||
+      url.hostname === "[::1]";
     const isDevApi = url.hostname.split(".").includes("dev");
     const domain =
       configuredDomain ||
-      (isDevApi ? `worker.dev.tyvm-apps.com` : PROD_TUNNEL_WORKER_DOMAIN);
+      (isLocalApi
+        ? `worker.localhost:${url.port || (useHttps ? "443" : "80")}`
+        : isDevApi
+          ? `worker.dev.tyvm-apps.com`
+          : PROD_TUNNEL_WORKER_DOMAIN);
 
     return { domain, useHttps };
   } catch (err) {

package/tests/processors/Base64ImageDetector.test.ts

@@ -220,6 +220,38 @@ describe("Base64ImageDetector", () => {
       expect(content[0].image_url.url).toBe(imageDataUrl);
     });
 
+    it("should process an image result that is not the newest parallel tool result", () => {
+      const imageDataUrl =
+        "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==";
+      const modifiedMessages: Message[] = [
+        {
+          role: "tool",
+          content: JSON.stringify({
+            type: "image_url",
+            image_url: { url: imageDataUrl, detail: "high" },
+          }),
+          tool_call_id: "call_image",
+        },
+        {
+          role: "tool",
+          content: "A later readFile result",
+          tool_call_id: "call_file",
+        },
+        {
+          role: "user",
+          content: "A pending workflow update",
+        },
+      ];
+
+      detector.createProcessor()([], modifiedMessages);
+
+      expect(Array.isArray(modifiedMessages[0].content)).toBe(true);
+      expect((modifiedMessages[0].content as any[])[0]).toEqual({
+        type: "image_url",
+        image_url: { url: imageDataUrl, detail: "high" },
+      });
+    });
+
     it("should not promote a compressed image URL placeholder to image content", () => {
       const toolResponseJson = JSON.stringify({
         type: "image_url",

package/tests/unit/agents/tools/loadImageAsBase64.test.ts

@@ -0,0 +1,44 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import {
+  loadImageAsBase64,
+  loadImageAsBase64Definition,
+} from "../../../../src/agents/tools/loadImageAsBase64";
+import { Base64ImageProcessor } from "../../../../src/processors/Base64ImageDetector";
+import { ToolsService } from "../../../../src/services/Tools";
+
+describe("loadImageAsBase64 tool", () => {
+  it("returns an image data URL with a MIME type detected from its bytes", async () => {
+    const directory = await fs.promises.mkdtemp(path.join(os.tmpdir(), "knowhow-image-"));
+    const filePath = path.join(directory, "incorrectly-named.jpg");
+
+    try {
+      await fs.promises.writeFile(filePath, Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]));
+      const result = JSON.parse(await loadImageAsBase64(filePath));
+
+      expect(result).toMatchObject({
+        type: "image_url",
+        image_url: { detail: "auto" },
+      });
+      expect(result.image_url.url).toMatch(/^data:image\/png;base64,/);
+    } finally {
+      await fs.promises.rm(directory, { recursive: true, force: true });
+    }
+  });
+
+  it("can also be registered by the image message processor without duplication", () => {
+    const toolsService = new ToolsService();
+    toolsService.defineTools(
+      [loadImageAsBase64Definition],
+      { loadImageAsBase64 }
+    );
+
+    new Base64ImageProcessor(toolsService);
+
+    expect(
+      toolsService.getToolNames().filter((name) => name === "loadImageAsBase64")
+    ).toHaveLength(1);
+    expect(typeof toolsService.getFunction("loadImageAsBase64")).toBe("function");
+  });
+});