@vellumai/assistant 0.8.12-staging.1 → 0.8.12

package/src/acp/agent-process.ts

@@ -10,6 +10,8 @@ import { Readable, Writable } from "node:stream";
 
 import type {
   Agent,
+  AuthMethod,
+  AuthMethodEnvVar,
   Client,
   InitializeResponse,
   NewSessionResponse,
@@ -22,6 +24,31 @@ import type { AcpAgentConfig } from "./types.js";
 
 const log = getLogger("acp");
 
+/**
+ * JSON-RPC error code agents use to signal that authentication is required
+ * (matches the SDK's RequestError.authRequired()).
+ */
+const AUTH_REQUIRED_CODE = -32000;
+
+/**
+ * Detects the ACP auth-required error. Checks the `code` property rather than
+ * `instanceof acp.RequestError` so plain JSON-RPC error objects are also
+ * recognized.
+ */
+function isAuthRequiredError(err: unknown): boolean {
+  return (
+    typeof err === "object" &&
+    err !== null &&
+    (err as { code?: unknown }).code === AUTH_REQUIRED_CODE
+  );
+}
+
+function isEnvVarMethod(
+  method: AuthMethod,
+): method is AuthMethodEnvVar & { type: "env_var" } {
+  return "type" in method && method.type === "env_var";
+}
+
 /**
  * Factory function type for creating ACP client handlers.
  * PR 5 will provide the real VellumAcpClientHandler implementation.
@@ -35,6 +62,12 @@ export class AcpAgentProcess {
   private proc: ChildProcess | null = null;
   private connection: acp.ClientSideConnection | null = null;
   private initializeResponse: InitializeResponse | null = null;
+  /**
+   * Merged env captured at spawn() so auth satisfiability checks match the
+   * env the child process actually received, even if process.env changes
+   * afterwards.
+   */
+  private spawnedEnv: NodeJS.ProcessEnv | null = null;
 
   constructor(
     public readonly agentId: string,
@@ -51,10 +84,11 @@ export class AcpAgentProcess {
       "Spawning ACP agent process",
     );
 
+    this.spawnedEnv = { ...process.env, ...this.config.env };
     this.proc = spawn(this.config.command, this.config.args, {
       cwd,
       stdio: ["pipe", "pipe", "pipe"],
-      env: { ...process.env, ...this.config.env },
+      env: this.spawnedEnv,
     });
 
     const stream = acp.ndJsonStream(
@@ -94,13 +128,11 @@ export class AcpAgentProcess {
    * Initializes the ACP connection by negotiating protocol version and capabilities.
    */
   async initialize(): Promise<InitializeResponse> {
-    if (!this.connection) {
-      throw new Error(`ACP agent "${this.agentId}" is not spawned`);
-    }
+    const connection = this.requireConnection();
 
     log.info({ agentId: this.agentId }, "Initializing ACP connection");
 
-    const response = await this.connection.initialize({
+    const response = await connection.initialize({
       protocolVersion: acp.PROTOCOL_VERSION,
       clientInfo: { name: "vellum", version: "1.0.0" },
       clientCapabilities: {
@@ -133,20 +165,119 @@ export class AcpAgentProcess {
   }
 
   /**
-   * Creates a new ACP session in the specified working directory.
-   * Returns the session ID.
+   * Authentication methods the agent advertised at initialize.
+   * Returns an empty array before initialize() resolves.
    */
-  async createSession(cwd: string): Promise<string> {
+  private get authMethods(): AuthMethod[] {
+    return this.initializeResponse?.authMethods ?? [];
+  }
+
+  /**
+   * Selects the first advertised env_var auth method whose required variables
+   * are all present (non-empty) in the env the agent process was spawned with.
+   *
+   * Terminal-type and agent-driven (untyped) methods are never selected:
+   * auto-triggering an interactive login would hang the headless daemon.
+   */
+  private selectEnvVarAuthMethod(): AuthMethod | undefined {
+    const env = this.spawnedEnv;
+    if (!env) return undefined;
+
+    return this.authMethods.find((method) => {
+      if (!isEnvVarMethod(method)) return false;
+
+      // `vars` is required by the SDK type, but agent responses aren't
+      // runtime-validated — tolerate an out-of-spec agent omitting it so the
+      // caller gets the friendly auth error instead of a TypeError.
+      const requiredVars = (method.vars ?? []).filter((v) => !v.optional);
+      if (requiredVars.length === 0) return false;
+
+      return requiredVars.every((v) => {
+        const value = env[v.name];
+        return typeof value === "string" && value.length > 0;
+      });
+    });
+  }
+
+  /**
+   * Returns the live connection, throwing the standard not-spawned error if
+   * the agent was never spawned or its process has since exited.
+   */
+  private requireConnection(): acp.ClientSideConnection {
     if (!this.connection) {
       throw new Error(`ACP agent "${this.agentId}" is not spawned`);
     }
+    return this.connection;
+  }
+
+  /**
+   * Runs an operation, and if the agent rejects with the ACP auth-required
+   * error, authenticates via a satisfiable env_var auth method and retries
+   * the operation exactly once.
+   */
+  private async withAuthRetry<T>(op: () => Promise<T>): Promise<T> {
+    try {
+      return await op();
+    } catch (err) {
+      if (!isAuthRequiredError(err)) throw err;
+
+      // The agent may have exited between the auth_required rejection and
+      // this retry path; fail with the standard not-spawned error.
+      const connection = this.requireConnection();
+
+      const method = this.selectEnvVarAuthMethod();
+      if (!method) {
+        throw new Error(
+          `ACP agent "${this.agentId}" requires authentication. ` +
+            `Advertised methods: ${this.describeAuthMethods()}. ` +
+            "Set the required env var under acp.agents.<id>.env in config.json, " +
+            "store it via 'assistant credentials set --service acp --field <field>', " +
+            "or complete the agent's own login flow in the workspace.",
+        );
+      }
+
+      log.info(
+        { agentId: this.agentId, methodId: method.id },
+        "ACP agent returned auth_required; authenticating with env_var method",
+      );
 
+      await connection.authenticate({ methodId: method.id });
+      return await op();
+    }
+  }
+
+  /**
+   * Renders the agent's advertised auth methods for error messages, e.g.
+   * `"Login with ChatGPT" (chatgpt), "Use OPENAI_API_KEY" (env var OPENAI_API_KEY)`.
+   */
+  private describeAuthMethods(): string {
+    if (this.authMethods.length === 0) return "none";
+
+    return this.authMethods
+      .map((method) => {
+        // `vars ?? []`: tolerate out-of-spec agents omitting the field —
+        // this renders inside the friendly auth error, which must not
+        // itself throw a TypeError.
+        const varNames = isEnvVarMethod(method)
+          ? (method.vars ?? []).map((v) => v.name).join(", ")
+          : "";
+        return varNames
+          ? `"${method.name}" (env var ${varNames})`
+          : `"${method.name}" (${method.id})`;
+      })
+      .join(", ");
+  }
+
+  /**
+   * Creates a new ACP session in the specified working directory.
+   * Returns the session ID.
+   */
+  async createSession(cwd: string): Promise<string> {
     log.info({ agentId: this.agentId, cwd }, "Creating ACP session");
 
-    const result: NewSessionResponse = await this.connection.newSession({
-      cwd,
-      mcpServers: [],
-    });
+    const result: NewSessionResponse = await this.withAuthRetry(() =>
+      this.requireConnection().newSession({ cwd, mcpServers: [] }),
+    );
 
     return result.sessionId;
   }
@@ -160,13 +291,11 @@ export class AcpAgentProcess {
    * VellumAcpClientHandler.beginReplaySuppression).
    */
   async loadSession(sessionId: string, cwd: string): Promise<void> {
-    if (!this.connection) {
-      throw new Error(`ACP agent "${this.agentId}" is not spawned`);
-    }
-
     log.info({ agentId: this.agentId, sessionId, cwd }, "Loading ACP session");
 
-    await this.connection.loadSession({ sessionId, cwd, mcpServers: [] });
+    await this.withAuthRetry(() =>
+      this.requireConnection().loadSession({ sessionId, cwd, mcpServers: [] }),
+    );
   }
 
   /**
@@ -177,13 +306,15 @@ export class AcpAgentProcess {
    * (see supportsSessionResume).
    */
   async resumeSession(sessionId: string, cwd: string): Promise<void> {
-    if (!this.connection) {
-      throw new Error(`ACP agent "${this.agentId}" is not spawned`);
-    }
-
     log.info({ agentId: this.agentId, sessionId, cwd }, "Resuming ACP session");
 
-    await this.connection.resumeSession({ sessionId, cwd, mcpServers: [] });
+    await this.withAuthRetry(() =>
+      this.requireConnection().resumeSession({
+        sessionId,
+        cwd,
+        mcpServers: [],
+      }),
+    );
   }
 
   /**
@@ -191,35 +322,31 @@ export class AcpAgentProcess {
    * Returns the prompt response (includes stopReason).
    */
   async prompt(sessionId: string, text: string): Promise<PromptResponse> {
-    if (!this.connection) {
-      throw new Error(`ACP agent "${this.agentId}" is not spawned`);
-    }
-
     log.info(
       { agentId: this.agentId, sessionId },
       "Sending prompt to ACP agent",
     );
 
-    return this.connection.prompt({
-      sessionId,
-      prompt: [{ type: "text", text }],
-    });
+    return this.withAuthRetry(() =>
+      this.requireConnection().prompt({
+        sessionId,
+        prompt: [{ type: "text", text }],
+      }),
+    );
   }
 
   /**
    * Cancels an ongoing prompt in the specified session.
    */
   async cancel(sessionId: string): Promise<void> {
-    if (!this.connection) {
-      throw new Error(`ACP agent "${this.agentId}" is not spawned`);
-    }
+    const connection = this.requireConnection();
 
     log.info(
       { agentId: this.agentId, sessionId },
       "Cancelling ACP session prompt",
     );
 
-    await this.connection.cancel({ sessionId });
+    await connection.cancel({ sessionId });
   }
 
   /**
@@ -234,6 +361,7 @@ export class AcpAgentProcess {
     }
     this.connection = null;
     this.initializeResponse = null;
+    this.spawnedEnv = null;
   }
 
   /**
@@ -265,5 +393,6 @@ export class AcpAgentProcess {
     this.proc = null;
     this.connection = null;
     this.initializeResponse = null;
+    this.spawnedEnv = null;
   }
 }

package/src/acp/prepare-agent-env.ts

@@ -93,6 +93,32 @@ async function injectCredential(
   return result.success ? undefined : result.reason;
 }
 
+/**
+ * Inject an OPTIONAL credential: skip when the env var is already set
+ * (config.json override wins), and treat a vault miss as non-fatal — the
+ * adapter has its own login fallback, so spawning without the key is fine.
+ */
+async function injectOptionalCredential(
+  env: Record<string, string>,
+  field: string,
+  envVar: string,
+  usageDescription: string,
+): Promise<void> {
+  if (env[envVar]) return;
+  const missReason = await injectCredential(
+    env,
+    field,
+    envVar,
+    usageDescription,
+  );
+  if (missReason !== undefined) {
+    log.debug(
+      { reason: missReason },
+      `${envVar} unavailable from the vault; spawning without it`,
+    );
+  }
+}
+
 /**
  * Returns a NEW config with any required credentials merged into `env`.
  * Does NOT mutate the input. Throws `FailedDependencyError` if a required
@@ -123,6 +149,13 @@ async function injectCredential(
  * ways (config.json override wins, vault field `gemini_api_key` second),
  * but it is OPTIONAL: the Gemini CLI supports its own OAuth login, so a
  * vault miss proceeds without the key instead of failing the spawn.
+ *
+ * For `codex-acp` the env vars are `OPENAI_API_KEY` (vault field
+ * `acp/openai_api_key`) and `CODEX_API_KEY` (vault field
+ * `acp/codex_api_key`), provisioned the same two ways (config.json
+ * override wins, vault second). Both are OPTIONAL: codex also supports
+ * ChatGPT login (`codex login` pre-seeding `auth.json` in the workspace),
+ * so a vault miss proceeds without the key instead of failing the spawn.
  */
 export async function prepareAgentEnv(
   agentConfig: AcpAgentConfig,
@@ -150,22 +183,29 @@ export async function prepareAgentEnv(
       );
     }
   } else if (adapterCommand === "gemini") {
-    if (!env.GEMINI_API_KEY) {
-      const missReason = await injectCredential(
+    await injectOptionalCredential(
+      env,
+      "gemini_api_key",
+      "GEMINI_API_KEY",
+      "Gemini API key for ACP agent authentication",
+    );
+  } else if (adapterCommand === "codex-acp") {
+    // The two reads target independent vault fields and write disjoint env
+    // keys, so running them concurrently is safe.
+    await Promise.all([
+      injectOptionalCredential(
         env,
-        "gemini_api_key",
-        "GEMINI_API_KEY",
-        "Gemini API key for ACP agent authentication",
-      );
-      if (missReason !== undefined) {
-        // Optional credential: Gemini CLI can authenticate via its own
-        // OAuth login, so a vault miss must not fail the spawn.
-        log.debug(
-          { reason: missReason },
-          "Gemini API key unavailable from the vault; spawning without GEMINI_API_KEY",
-        );
-      }
-    }
+        "openai_api_key",
+        "OPENAI_API_KEY",
+        "OpenAI API key for Codex ACP agent authentication",
+      ),
+      injectOptionalCredential(
+        env,
+        "codex_api_key",
+        "CODEX_API_KEY",
+        "Codex API key for Codex ACP agent authentication",
+      ),
+    ]);
   }
 
   return { ...agentConfig, env };

package/src/bundler/app-compiler.ts

@@ -454,6 +454,14 @@ async function runCompile(appDir: string): Promise<CompileResult> {
   if (existsSync(htmlSrc)) {
     let html = await readFile(htmlSrc, "utf-8");
 
+    // Strip source-file script tags (e.g. <script src="/src/main.tsx">) that
+    // models often write in Vite style; browsers cannot load raw TSX/TS/JSX.
+    // The compiled main.js tag is injected below instead.
+    html = html.replace(
+      /<script\b[^>]*\bsrc=["'][^"']*\.(?:tsx|ts|jsx)["'][^>]*>\s*<\/script>\s*/gi,
+      "",
+    );
+
     // Check if CSS output was produced
     const distFiles = await readdir(distDir);
     const hasCss = distFiles.some((f) => f.endsWith(".css"));

package/src/cli/lib/__tests__/upgrade-plugin.test.ts

@@ -21,7 +21,11 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 
-import type { FetchLike, GitRunner } from "../install-from-github.js";
+import {
+  type FetchLike,
+  type GitRunner,
+  PluginSourceUnavailableError,
+} from "../install-from-github.js";
 import { PluginNotInstalledError } from "../uninstall-plugin.js";
 import { PluginNotUpgradableError, upgradePlugin } from "../upgrade-plugin.js";
 
@@ -262,19 +266,21 @@ describe("upgradePlugin", () => {
     ).rejects.toBeInstanceOf(PluginNotUpgradableError);
   });
 
-  test("throws PluginNotUpgradableError when the marketplace is unreachable", async () => {
+  test("throws PluginSourceUnavailableError when the marketplace is unreachable", async () => {
     // GIVEN an installed copy and a marketplace fetch that fails transiently
     installCopy(pluginsDir, "level-up", { commit: SHA_A });
     const fetch = makeFetch({ manifestStatus: 500 });
 
     // WHEN an upgrade is attempted
-    // THEN the latest pin cannot be determined, so it refuses
+    // THEN the outage is surfaced as a retryable source-unavailable error
+    // (distinct from the permanent no-marketplace-entry conflict), since the
+    // same request can succeed once the catalog recovers
     await expect(
       upgradePlugin(
         { name: "level-up" },
         { fetch, runGit: unusedGitRunner, workspacePluginsDir: pluginsDir },
       ),
-    ).rejects.toBeInstanceOf(PluginNotUpgradableError);
+    ).rejects.toBeInstanceOf(PluginSourceUnavailableError);
   });
 
   test("preserves the existing install when the re-install clone fails", async () => {

package/src/cli/lib/upgrade-plugin.ts

@@ -37,6 +37,7 @@ import {
   type FetchLike,
   type GitRunner,
   installPlugin,
+  PluginSourceUnavailableError,
   type PostinstallRunner,
   sanitizePluginName,
 } from "./install-from-github.js";
@@ -116,10 +117,11 @@ function pluginTarget(name: string, deps: UpgradePluginDeps): string {
  * Move an installed plugin to the marketplace's current pin.
  *
  * Throws {@link PluginNotInstalledError} when no copy is installed,
- * {@link PluginNotUpgradableError} when the install has no marketplace pin to
- * advance to (no catalog entry, or the catalog was unreachable), and
- * propagates {@link installPlugin}'s errors (e.g. source unavailable,
- * postinstall failure) when the re-install itself fails.
+ * {@link PluginNotUpgradableError} when the install has no marketplace entry to
+ * advance to, {@link PluginSourceUnavailableError} when the marketplace catalog
+ * is temporarily unreachable (a retryable outage, distinct from the permanent
+ * no-entry case), and propagates {@link installPlugin}'s errors (e.g. source
+ * unavailable, postinstall failure) when the re-install itself fails.
  */
 export async function upgradePlugin(
   opts: UpgradePluginOptions,
@@ -150,9 +152,13 @@ export async function upgradePlugin(
         "it has no marketplace entry to upgrade from",
       );
     case "remote-unavailable":
-      throw new PluginNotUpgradableError(
-        name,
-        `the marketplace could not be reached (${inspection.remoteError ?? "unknown error"})`,
+      // A transient catalog outage is not a permanent "cannot upgrade" state:
+      // the same request can succeed once the marketplace source recovers, so
+      // surface it as a retryable source-unavailable error rather than a
+      // conflict.
+      throw new PluginSourceUnavailableError(
+        `Plugin "${name}" cannot be upgraded: the marketplace could not be reached (${inspection.remoteError ?? "unknown error"}).`,
+        503,
       );
   }
 

package/src/config/seed-inference-profiles.ts

@@ -74,23 +74,19 @@ const MANAGED_PROFILE_TEMPLATES: Record<string, ManagedProfileTemplate> = {
     thinking: { enabled: false, streamThinking: false },
     contextWindow: { maxInputTokens: DEFAULT_CONTEXT_WINDOW_MAX_INPUT_TOKENS },
   },
-  // Open-weight economy option: Kimi K2.6 served by Fireworks via managed
-  // platform inference. Carries the `suppress-cjk` logit-bias preset to
-  // discourage the model from spontaneously emitting Chinese in English
-  // output; the preset is profile-scoped and only forwarded on the Fireworks
-  // path (see `providers/inference/logit-bias.ts`).
+  // Open-weight economy option: MiniMax M3 served by Fireworks via managed
+  // platform inference.
   "balanced-economy": {
     intent: "balanced",
     provider: "fireworks",
     connectionName: "fireworks-managed",
     source: "managed",
     label: "Balanced Economy",
-    description: "Strong open model (Kimi K2.6) at a lower price point",
-    maxTokens: 16000,
+    description: "Strong open model (MiniMax M3) at a lower price point",
+    maxTokens: 32000,
     effort: "high",
     thinking: { enabled: true, streamThinking: true },
     contextWindow: { maxInputTokens: DEFAULT_CONTEXT_WINDOW_MAX_INPUT_TOKENS },
-    logitBias: "suppress-cjk",
   },
 };
 

package/src/events/tool-audit-listener.ts

@@ -3,6 +3,7 @@ import {
   recordToolInvocation,
   type ToolInvocationRecord,
 } from "../memory/tool-usage-store.js";
+import { redactJsonStringLeaves } from "../security/redact-json.js";
 import { redactSecrets } from "../security/secret-scanner.js";
 import {
   stringifyToolInput,
@@ -43,11 +44,14 @@ function toInvocationRecord(
 ): ToolInvocationRecord | null {
   switch (event.type) {
     case "executed": {
-      const input = stringifyToolInput(event.input);
+      const rawInput = stringifyToolInput(event.input);
       return {
         conversationId: event.conversationId,
         toolName: event.toolName,
-        input,
+        // Inputs can carry secrets the model typed verbatim (e.g.
+        // `export OPENAI_API_KEY=...` in a bash command) — redact before
+        // the row reaches the audit store, like results below.
+        input: redactToolInput(event.input, rawInput),
         result: redactSecrets(event.result.content).slice(
           0,
           RESULT_PREVIEW_LIMIT,
@@ -63,18 +67,18 @@ function toInvocationRecord(
         // don't stamp.
         ...telemetryColumns(
           event,
-          input,
+          rawInput,
           event.resultBytes ?? Buffer.byteLength(event.result.content, "utf8"),
         ),
       };
     }
     case "error": {
-      const input = stringifyToolInput(event.input);
+      const rawInput = stringifyToolInput(event.input);
       const result = `error: ${event.errorMessage}`;
       return {
         conversationId: event.conversationId,
         toolName: event.toolName,
-        input,
+        input: redactToolInput(event.input, rawInput),
         result,
         decision: "error",
         riskLevel: event.riskLevel,
@@ -83,7 +87,7 @@ function toInvocationRecord(
         // The error result string is built right here and never goes
         // through sensitive-output sanitization, so sizing it directly is
         // already raw — no executor stamp exists or is needed.
-        ...telemetryColumns(event, input, Buffer.byteLength(result, "utf8")),
+        ...telemetryColumns(event, rawInput, Buffer.byteLength(result, "utf8")),
       };
     }
     case "permission_denied":
@@ -92,7 +96,7 @@ function toInvocationRecord(
       return {
         conversationId: event.conversationId,
         toolName: event.toolName,
-        input: stringifyToolInput(event.input),
+        input: redactToolInput(event.input, stringifyToolInput(event.input)),
         result: formatDeniedResult(event.reason),
         decision: "denied",
         riskLevel: event.riskLevel,
@@ -105,6 +109,33 @@ function toInvocationRecord(
   }
 }
 
+/**
+ * Redact secrets from a tool input while keeping the stored audit string
+ * parseable JSON. The redaction marker (`<redacted type="..." />`) contains
+ * double quotes, so redacting the serialized string would corrupt it —
+ * instead, walk the input's string leaves BEFORE stringification so the
+ * marker lands inside a JSON string value (with its quotes escaped).
+ *
+ * `rawInput` is the canonical pre-redaction serialization (also used for
+ * the `argBytes` telemetry fallback — byte sizes must reflect the full
+ * payload before truncation and redaction). It is returned untouched when
+ * nothing matched, keeping benign inputs byte-identical, and is redacted as
+ * plain text if the input can't be walked or re-serialized (e.g. cyclic
+ * structures).
+ */
+function redactToolInput(
+  input: Record<string, unknown>,
+  rawInput: string,
+): string {
+  try {
+    const { value, changed } = redactJsonStringLeaves(input);
+    if (!changed) return rawInput;
+    return JSON.stringify(value);
+  } catch {
+    return redactSecrets(rawInput);
+  }
+}
+
 type TelemetryColumns = Pick<ToolInvocationRecord, "argBytes" | "resultBytes"> &
   UsageAttributionColumns;
 
@@ -134,12 +165,12 @@ const NULL_TELEMETRY_COLUMNS: TelemetryColumns = {
  */
 function telemetryColumns(
   event: Extract<ToolLifecycleEvent, { type: "executed" | "error" }>,
-  input: string,
+  rawInput: string,
   resultBytes: number,
 ): TelemetryColumns {
   if (!getConfig().collectUsageData) return NULL_TELEMETRY_COLUMNS;
   return {
-    argBytes: event.inputBytes ?? Buffer.byteLength(input, "utf8"),
+    argBytes: event.inputBytes ?? Buffer.byteLength(rawInput, "utf8"),
     resultBytes,
     ...toAttributionColumns(event.attribution),
   };

package/src/providers/__tests__/unparseable-tool-args.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  isUnparseableToolArgs,
+  unparseableToolArgsMessage,
+  wrapUnparseableToolArgs,
+} from "../unparseable-tool-args.js";
+
+describe("unparseable tool args marker", () => {
+  test("wrap/detect roundtrip", () => {
+    const wrapped = wrapUnparseableToolArgs(
+      '{"surface_type": "card", "data": ',
+    );
+    expect(isUnparseableToolArgs(wrapped)).toBe(true);
+  });
+
+  test("detects empty raw string", () => {
+    expect(isUnparseableToolArgs(wrapUnparseableToolArgs(""))).toBe(true);
+  });
+
+  test("does not match input with additional keys", () => {
+    expect(isUnparseableToolArgs({ _raw: "x", other: 1 })).toBe(false);
+  });
+
+  test("does not match non-string _raw", () => {
+    expect(isUnparseableToolArgs({ _raw: { nested: true } })).toBe(false);
+  });
+
+  test("does not match ordinary tool input", () => {
+    expect(isUnparseableToolArgs({ command: "ls" })).toBe(false);
+    expect(isUnparseableToolArgs({})).toBe(false);
+  });
+
+  test("message includes tool name, raw preview, and retry instruction", () => {
+    const msg = unparseableToolArgsMessage("ui_show", '{"surface_type": ');
+    expect(msg).toContain('"ui_show"');
+    expect(msg).toContain('{"surface_type": ');
+    expect(msg).toContain("NOT executed");
+    expect(msg).toContain("Retry");
+  });
+
+  test("message truncates long raw args", () => {
+    const raw = "a".repeat(1000);
+    const msg = unparseableToolArgsMessage("bash", raw);
+    expect(msg).not.toContain(raw);
+    expect(msg).toContain("a".repeat(200) + "…");
+  });
+
+  test("message handles empty raw args", () => {
+    const msg = unparseableToolArgsMessage("bash", "");
+    expect(msg).toContain("(empty)");
+  });
+});