@vellumai/assistant 0.8.12 → 0.9.0-staging.1

package/src/prompts/__tests__/system-prompt.test.ts

@@ -6,7 +6,7 @@
  * user-message injection that replaced it.
  */
 
-import { copyFileSync, mkdirSync, readFileSync } from "node:fs";
+import { copyFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { beforeEach, describe, expect, mock, test } from "bun:test";
 
@@ -73,6 +73,105 @@ describe("buildSystemPrompt — tool routing guidance", () => {
   });
 });
 
+describe("buildSystemPrompt — persona override", () => {
+  const DEFAULT_SENTINEL = "Sentinel: default persona body.";
+  const ALICE_SENTINEL = "Sentinel: alice persona body.";
+  const TELEGRAM_SENTINEL = "Sentinel: telegram channel persona body.";
+
+  beforeEach(() => {
+    mkdirSync(join(TEST_DIR, "users"), { recursive: true });
+    mkdirSync(join(TEST_DIR, "channels"), { recursive: true });
+    writeFileSync(join(TEST_DIR, "users", "default.md"), DEFAULT_SENTINEL);
+    writeFileSync(join(TEST_DIR, "users", "alice.md"), ALICE_SENTINEL);
+    writeFileSync(join(TEST_DIR, "channels", "telegram.md"), TELEGRAM_SENTINEL);
+  });
+
+  test("personaOverride renders the given user + channel persona sections", () => {
+    const result = buildSystemPrompt({
+      personaOverride: { userSlug: "alice", channelSlug: "telegram" },
+    });
+
+    expect(result).toContain(ALICE_SENTINEL);
+    expect(result).toContain(TELEGRAM_SENTINEL);
+    expect(result).not.toContain(DEFAULT_SENTINEL);
+  });
+
+  test("no override → trust-context-derived resolution (default persona, vellum channel)", () => {
+    // No trust context and no resolvable guardian contact in this test env,
+    // so the user persona falls back to users/default.md and the channel
+    // section resolves channels/vellum.md (absent → omitted).
+    const result = buildSystemPrompt({});
+
+    expect(result).toContain(DEFAULT_SENTINEL);
+    expect(result).not.toContain(ALICE_SENTINEL);
+    expect(result).not.toContain(TELEGRAM_SENTINEL);
+  });
+
+  test("partial override: userSlug alone leaves channel resolution untouched", () => {
+    const result = buildSystemPrompt({
+      personaOverride: { userSlug: "alice" },
+    });
+
+    expect(result).toContain(ALICE_SENTINEL);
+    expect(result).not.toContain(TELEGRAM_SENTINEL);
+  });
+
+  test("override userSlug with no matching file falls back to users/default.md", () => {
+    const result = buildSystemPrompt({
+      personaOverride: { userSlug: "missing-user" },
+    });
+
+    expect(result).toContain(DEFAULT_SENTINEL);
+  });
+});
+
+describe("buildSystemPrompt — hasNoClient pin", () => {
+  // Marker unique to the `{{^hasNoClient}}` branch of 05-access-preference:
+  // host fallbacks only render when a client is connected.
+  const WITH_CLIENT_MARKER = "`host_bash` with CLIs";
+
+  beforeEach(() => {
+    mkdirSync(TEST_DIR, { recursive: true });
+  });
+
+  test("hasNoClient renders divergent access-preference text", () => {
+    expect(buildSystemPrompt({ hasNoClient: false })).toContain(
+      WITH_CLIENT_MARKER,
+    );
+    expect(buildSystemPrompt({ hasNoClient: true })).not.toContain(
+      WITH_CLIENT_MARKER,
+    );
+  });
+
+  test("personaOverride.hasNoClient pins the flag over the conversation-derived option", () => {
+    // Fork-retrospective case: the fork is hydrated clientless
+    // (hasNoClient: true) but pins the source's live-turn value (false) so
+    // the prompt byte-matches the source's cached prefix.
+    expect(
+      buildSystemPrompt({
+        hasNoClient: true,
+        personaOverride: { hasNoClient: false },
+      }),
+    ).toContain(WITH_CLIENT_MARKER);
+    // And the pin wins in the other direction too.
+    expect(
+      buildSystemPrompt({
+        hasNoClient: false,
+        personaOverride: { hasNoClient: true },
+      }),
+    ).not.toContain(WITH_CLIENT_MARKER);
+  });
+
+  test("a personaOverride without the pin leaves the conversation-derived flag untouched", () => {
+    expect(
+      buildSystemPrompt({ hasNoClient: true, personaOverride: {} }),
+    ).not.toContain(WITH_CLIENT_MARKER);
+    expect(
+      buildSystemPrompt({ hasNoClient: false, personaOverride: {} }),
+    ).toContain(WITH_CLIENT_MARKER);
+  });
+});
+
 describe("maybeReseedBootstrap — content-automation template", () => {
   const templatesDir = join(import.meta.dirname!, "..", "templates");
 

package/src/prompts/__tests__/task-progress-hint-section.test.ts

@@ -1,5 +1,5 @@
 /**
- * Tests for the task_progress hint in the 01-parallel-tool-calls workspace
+ * Tests for the task_progress hint in the 01-progress-surface workspace
  * system prompt section.
  *
  * Verifies that the task_progress guidance renders unconditionally in the
@@ -54,11 +54,10 @@ mock.module("../../config/loader.js", () => ({
   setNestedValue: () => {},
 }));
 
-const { buildSystemPrompt, ensurePromptFiles } = await import(
-  "../system-prompt.js"
-);
+const { buildSystemPrompt, ensurePromptFiles } =
+  await import("../system-prompt.js");
 
-describe("task_progress hint in parallel-tool-calls section", () => {
+describe("task_progress hint in progress-surface section", () => {
   beforeEach(() => {
     ensurePromptFiles();
   });
@@ -66,7 +65,7 @@ describe("task_progress hint in parallel-tool-calls section", () => {
   test("buildSystemPrompt() includes task_progress guidance", () => {
     const result = buildSystemPrompt();
     expect(result).toContain("task_progress");
-    expect(result).toContain("No exceptions");
+    expect(result).toContain("Show Progress on Long Turns");
   });
 
   test("renders unconditionally — no options required", () => {
@@ -85,5 +84,4 @@ describe("task_progress hint in parallel-tool-calls section", () => {
     expect(withoutClientFlag).toContain("task_progress");
     expect(withExcludePrefix).toContain("task_progress");
   });
-
 });

package/src/prompts/normalize-onboarding.ts

@@ -82,6 +82,7 @@ export function normalizePriorAssistants(assistants: string[]): string[] {
 
 export interface NormalizedOnboarding {
   preferredName?: string;
+  occupation?: string;
   commonWork: string[];
   dailyTools: string[];
   tone?: string;
@@ -123,6 +124,7 @@ export function normalizeOnboardingContext(
 ): NormalizedOnboarding {
   return {
     preferredName: ctx.userName?.trim() || undefined,
+    occupation: ctx.occupation?.trim() || undefined,
     commonWork: normalizeTasks(ctx.tasks),
     dailyTools: normalizeTools(ctx.tools),
     tone: ctx.tone,

package/src/prompts/persona-resolver.ts

@@ -348,6 +348,9 @@ function buildOnboardingSection(normalized: NormalizedOnboarding): string {
   if (normalized.preferredName) {
     lines.push(`- **Preferred name:** ${normalized.preferredName}`);
   }
+  if (normalized.occupation) {
+    lines.push(`- **Role:** ${normalized.occupation}`);
+  }
   if (normalized.commonWork.length > 0) {
     lines.push(`- **Common work:** ${normalized.commonWork.join("; ")}`);
   }

package/src/prompts/system-prompt.ts

@@ -304,6 +304,33 @@ export function applyBootstrapTemplate(
   }
 }
 
+/**
+ * Explicit prompt-build override for builds that run outside the
+ * inbound-turn pipeline (agent wakes). Each field, when present, takes
+ * precedence over the corresponding derivation in {@link buildSystemPrompt}.
+ * Prompt-build selection only — trust class and approval semantics are
+ * unaffected.
+ */
+export interface SystemPromptPersonaOverride {
+  /** Renders `users/<slug>.md` as the user persona section. */
+  userSlug?: string;
+  /** Renders `channels/<slug>.md` as the channel persona section. */
+  channelSlug?: string;
+  /**
+   * Pins the `hasNoClient` flag for the prompt build, taking precedence over
+   * the top-level `BuildSystemPromptOptions.hasNoClient` (which mirrors the
+   * conversation's live client state). The `05-access-preference` section
+   * renders different text under the flag — early in the prompt, so a
+   * mismatch breaks byte-parity with a cached prefix even when persona and
+   * profile match. Used by fork-based memory retrospectives: the fork is
+   * hydrated clientless (`hasNoClient = true`) while the source's live turns
+   * ran under the source's own client state (`false` for interactive
+   * interfaces, `true` for channel-routed sources) — the pin carries that
+   * live-turn value.
+   */
+  hasNoClient?: boolean;
+}
+
 export interface BuildSystemPromptOptions {
   hasNoClient?: boolean;
   excludeBootstrap?: boolean;
@@ -311,6 +338,15 @@ export interface BuildSystemPromptOptions {
   trustContext?: TrustContext;
   channelCapabilities?: ChannelCapabilities;
   onboardingContext?: OnboardingContext;
+  /**
+   * Explicit persona/channel slugs, taking precedence over the
+   * trust-context-derived `userSlug` and capabilities-derived `channelSlug`.
+   * Used by fork-based memory retrospectives so the fork's prompt renders the
+   * SOURCE conversation's persona sections (review quality + byte-parity with
+   * the source's cached system-prompt prefix) even though the wake itself
+   * carries an internal guardian trust context with no requester identity.
+   */
+  personaOverride?: SystemPromptPersonaOverride;
   /**
    * Conversation this prompt is being built for. Optional because several
    * callers build a prompt outside a conversation (e.g. home greeting,
@@ -344,8 +380,20 @@ export function buildSystemPrompt(options?: BuildSystemPromptOptions): string {
   // `users/<slug>.md → users/default.md` fallback lives in the
   // section's `workspacePath` array.  `channelSlug` is the channel
   // identifier from `channelCapabilities`, defaulting to "vellum".
-  const userSlug = resolveUserSlug(options?.trustContext) ?? "default";
-  const channelSlug = options?.channelCapabilities?.channel ?? "vellum";
+  // An explicit `personaOverride` slug wins over either derivation.
+  const userSlug =
+    options?.personaOverride?.userSlug ??
+    resolveUserSlug(options?.trustContext) ??
+    "default";
+  const channelSlug =
+    options?.personaOverride?.channelSlug ??
+    options?.channelCapabilities?.channel ??
+    "vellum";
+  // The override's `hasNoClient` pin wins over the conversation-derived
+  // top-level option (see the interface doc); placed after the `...options`
+  // spread below so it overrides the spread-in value.
+  const hasNoClient =
+    options?.personaOverride?.hasNoClient ?? options?.hasNoClient;
 
   // Section render context.  Workspace section frontmatter `enabled:`
   // predicates, `{{key}}` / `{{#flag}}...{{/flag}}` body interpolation,
@@ -358,6 +406,7 @@ export function buildSystemPrompt(options?: BuildSystemPromptOptions): string {
   // no explicit normalization needed; `...options` is enough.
   const ctx = {
     ...options,
+    hasNoClient,
     isContainerized: getIsContainerized(),
     workspaceDir: getWorkspaceDir(),
     userSlug,

package/src/prompts/templates/BOOTSTRAP-ACTIVATION-RAIL.md

@@ -35,6 +35,8 @@ Surface the outcome as a clickable component, strongest first. The component is
 
 DONE: you cannot exit Propose without emitting at least one `ui_show` offer surface (card / choice). A proposal in prose is not a proposal.
 
+Thin signal still ships a proposal. Weak findings mean you make the smallest defensible offer and name the confidence in a clause ("low confidence, but —") — they do not mean you skip the move. Never resolve Propose into a critique of why the signal's too thin: "not enough here to suggest anything" is a stall, not a move. The least-wrong job for someone who looks like them beats an honest shrug, every time.
+
 **Run.** Do it. Real tools, real data. The user watches something happen.
 
 DONE: a real tool ran against real data and the user can see the result.
@@ -69,7 +71,7 @@ These are enforcement rules, not advice.
 
 **Self-check before final emit.** If this turn contains an offer or a follow-up, render it via `ui_show`, not prose.
 
-**Long turns show progress.** Any post-submit / post-skill-load turn must render a `task_progress` card within ~5s, or fall back to streaming text. Bind "long turn" → "task_progress emitted": a long-running turn that produces neither a progress card nor streaming text didn't satisfy this move.
+**Long turns show progress.** Any post-submit / post-skill-load turn must render a `task_progress` card within ~5s, or fall back to streaming text. Bind "long turn" → "task_progress emitted": a long-running turn that produces neither a progress card nor streaming text didn't satisfy this move. Progress is the card, not a play-by-play. Tool selection, routing, retries, and failures ("search blocked, trying the browser…", "that captcha'd, falling back to —") belong in thinking, never in visible prose: the card shows progress, the result surface shows outcome, and the mechanics in between stay out of the user's view.
 
 **Action Trust-Guarantee.** Sibling to the OAuth Trust-Guarantee. Before a bulk write / delete / destructive op, render a `ui_show` preview — a table surface showing total count, breakdown, sample rows, and the categories to confirm. The user commits or refines on that surface; only then do you execute. Single-item actions use the natural draft instead. Threshold for the preview gate: bulk _and_ low recoverability. One of the two alone doesn't trip it.
 

package/src/prompts/templates/system-sections.ts

@@ -269,9 +269,14 @@ Batch independent tool calls into the same response. An extra LLM round trip cos
 Before emitting a single tool call, ask whether your next turn would be another tool call that doesn't consume this one's output — if so, they belong together. Serialized tool calls without a real data dependency are a bug.
 
 For non-trivial independent workstreams — research, coding, multi-step investigations — delegate to subagents (load the \`subagent\` skill) and spawn them early and in parallel; an unnecessary subagent is cheaper than serialized work.
-
-**Before your first tool call**, check: does this turn involve a web search, file operations, multi-step work, or anything that will take more than a few seconds? If yes, call ui_show with surface_type "card" and template "task_progress" first, then update steps via ui_update as work progresses. No exceptions.
 </use_parallel_tool_calls>
+`,
+  },
+  {
+    id: "01-progress-surface",
+    body: `## Show Progress on Long Turns
+
+When a turn will take more than a few seconds — web searches, multi-step file work, research — show the user a progress card early: call ui_show with surface_type "card" and template "task_progress", then flip each step pending → in_progress → completed via ui_update as you go. Coarse steps are fine; a rough "Working on X" beats no signal at all. You can add or revise steps as the work takes shape — you are not committed to your first list. Skip the card when the turn is quick or you are already wrapping up; never let it get in the way of doing the actual work.
 `,
   },
   {
@@ -332,7 +337,7 @@ Priority: (1) sandbox \`bash\` - install tools yourself, only fall back to host
     id: "06-credential-security",
     body: `## Credential Security
 
-Never ask users to share secrets (API keys, tokens, passwords, webhook secrets) in chat — secret messages may be blocked at ingress. Use the \`credential_store\` tool with \`action: "prompt"\` instead; it collects secrets through a secure UI that never exposes the value in the conversation. Non-secret values (Client IDs, Account SIDs, usernames) may be collected conversationally.
+Never ask users to share secrets (API keys, tokens, passwords, webhook secrets) in chat — secret messages may be blocked at ingress. Run \`assistant credentials prompt\` (via the bash tool) instead; it collects secrets through a secure UI that never exposes the value in the conversation. This command blocks until the user submits the secret, so set the bash tool's \`timeout_seconds\` to at least 330 — the default (120s) cuts the prompt off before the user can respond. Non-secret values (Client IDs, Account SIDs, usernames) may be collected conversationally.
 `,
   },
   {

package/src/providers/call-site-routing.ts

@@ -141,13 +141,16 @@ export class CallSiteRoutingProvider implements Provider {
     if (!callSite) return this.defaultProvider;
 
     const overrideProfile = options?.config?.overrideProfile;
-    // Forward the per-conversation mix seed so transport selection picks the
-    // same mix arm as wire-param normalization in `retry.ts` — otherwise a mix
-    // spanning providers could route the transport to a different arm than the
+    // Forward `forceOverrideProfile` and the per-conversation mix seed so
+    // transport selection resolves the same profile/arm as wire-param
+    // normalization in `retry.ts` — otherwise a forced profile (or a mix)
+    // spanning providers could route the transport differently than the
     // request params.
+    const forceOverrideProfile = options?.config?.forceOverrideProfile;
     const selectionSeed = options?.config?.selectionSeed;
     const resolved = resolveCallSiteConfig(callSite, getConfig().llm, {
       overrideProfile,
+      forceOverrideProfile,
       selectionSeed,
     });
 

package/src/providers/fireworks/client.ts

@@ -35,6 +35,9 @@ export class FireworksProvider extends OpenAIChatCompletionsProvider {
       // {@link resolveMaxReasoningEffort}.
       maxReasoningEffort: "high",
       assistantReasoningField: "reasoning_content",
+      // minimax-m3's function-call serialization collapses object-typed tool
+      // args to `{}` on the wire; present them as JSON strings and decode back.
+      coerceObjectArgsToJsonString: /minimax/i.test(model),
     });
   }
 

package/src/providers/inference/auth.ts

@@ -18,26 +18,28 @@ import { PROVIDER_CATALOG } from "../model-catalog.js";
  * Schema-accepted variants (runtime rejects with a clear "not yet shipped" error):
  *   - service_account: service-account credentials (Vertex AI, Bedrock).
  */
-export const AuthSchema = z.discriminatedUnion("type", [
-  z.object({
-    type: z.literal("api_key"),
-    credential: z.string().min(1),
-  }),
-  z.object({
-    type: z.literal("platform"),
-  }),
-  z.object({
-    type: z.literal("none"),
-  }),
-  z.object({
-    type: z.literal("oauth_subscription"),
-    credential: z.string().min(1),
-  }),
-  z.object({
-    type: z.literal("service_account"),
-    credential: z.string().min(1),
-  }),
-]);
+export const AuthSchema = z
+  .discriminatedUnion("type", [
+    z.object({
+      type: z.literal("api_key"),
+      credential: z.string().min(1),
+    }),
+    z.object({
+      type: z.literal("platform"),
+    }),
+    z.object({
+      type: z.literal("none"),
+    }),
+    z.object({
+      type: z.literal("oauth_subscription"),
+      credential: z.string().min(1),
+    }),
+    z.object({
+      type: z.literal("service_account"),
+      credential: z.string().min(1),
+    }),
+  ])
+  .meta({ id: "Auth" });
 
 export type Auth = z.infer<typeof AuthSchema>;
 
@@ -75,42 +77,46 @@ export const VALID_CONNECTION_PROVIDERS: readonly string[] =
 
 export type ConnectionProvider = string;
 
-export const ConnectionProviderSchema = z.enum(
-  VALID_CONNECTION_PROVIDERS as readonly [string, ...string[]],
-);
+export const ConnectionProviderSchema = z
+  .enum(VALID_CONNECTION_PROVIDERS as readonly [string, ...string[]])
+  .meta({ id: "ConnectionProvider" });
 
 // ---------------------------------------------------------------------------
 // Per-connection model entries (openai-compatible)
 // ---------------------------------------------------------------------------
 
-export const ConnectionModelSchema = z.object({
-  id: z.string().min(1),
-  displayName: z.string().min(1).optional(),
-});
+export const ConnectionModelSchema = z
+  .object({
+    id: z.string().min(1),
+    displayName: z.string().min(1).optional(),
+  })
+  .meta({ id: "ConnectionModel" });
 export type ConnectionModel = z.infer<typeof ConnectionModelSchema>;
 
 // ---------------------------------------------------------------------------
 // Full connection shape used by CRUD layer
 // ---------------------------------------------------------------------------
 
-export const ProviderConnectionSchema = z.object({
-  name: z.string().min(1),
-  provider: ConnectionProviderSchema,
-  auth: AuthSchema,
-  label: z.string().min(1).nullable(),
-  baseUrl: z.string().url().nullable(),
-  models: z.array(ConnectionModelSchema).nullable(),
-  createdAt: z.number().int(),
-  updatedAt: z.number().int(),
-  /**
-   * Whether this row is a Vellum-managed connection (`anthropic-managed`,
-   * `openai-managed`, `gemini-managed`). Derived from
-   * `MANAGED_CONNECTION_NAMES` in `connections.ts` at serialize time; the
-   * DB column does not exist. Clients use this to render the read-only
-   * "Vellum" badge + view-only editor and to disable the delete affordance
-   * without mirroring the canonical name list locally.
-   */
-  isManaged: z.boolean(),
-});
+export const ProviderConnectionSchema = z
+  .object({
+    name: z.string().min(1),
+    provider: ConnectionProviderSchema,
+    auth: AuthSchema,
+    label: z.string().min(1).nullable(),
+    baseUrl: z.string().url().nullable(),
+    models: z.array(ConnectionModelSchema).nullable(),
+    createdAt: z.number().int(),
+    updatedAt: z.number().int(),
+    /**
+     * Whether this row is a Vellum-managed connection (`anthropic-managed`,
+     * `openai-managed`, `gemini-managed`). Derived from
+     * `MANAGED_CONNECTION_NAMES` in `connections.ts` at serialize time; the
+     * DB column does not exist. Clients use this to render the read-only
+     * "Vellum" badge + view-only editor and to disable the delete affordance
+     * without mirroring the canonical name list locally.
+     */
+    isManaged: z.boolean(),
+  })
+  .meta({ id: "ProviderConnection" });
 
 export type ProviderConnection = z.infer<typeof ProviderConnectionSchema>;

package/src/providers/model-intents.ts

@@ -13,7 +13,7 @@ const PROVIDER_MODEL_INTENTS: Record<string, Record<ModelIntent, string>> = {
   anthropic: {
     balanced: "claude-sonnet-4-6",
     "latency-optimized": "claude-haiku-4-5-20251001",
-    "quality-optimized": "claude-fable-5",
+    "quality-optimized": "claude-opus-4-8",
     "vision-optimized": "claude-opus-4-6",
   },
   openai: {
@@ -43,7 +43,7 @@ const PROVIDER_MODEL_INTENTS: Record<string, Record<ModelIntent, string>> = {
   openrouter: {
     balanced: "anthropic/claude-sonnet-4.6",
     "latency-optimized": "anthropic/claude-haiku-4.5",
-    "quality-optimized": "anthropic/claude-fable-5",
+    "quality-optimized": "anthropic/claude-opus-4.8",
     "vision-optimized": "anthropic/claude-opus-4.6",
   },
 };

package/src/providers/openai/__tests__/coerce-object-args.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  coerceObjectParamsToJsonString,
+  decodeCoercedObjectArgs,
+} from "../coerce-object-args.js";
+
+const SKILL_EXECUTE_SCHEMA = {
+  type: "object",
+  properties: {
+    tool: { type: "string", description: "The skill tool name" },
+    input: { type: "object", description: "Tool-specific parameters" },
+    activity: { type: "string", description: "Progress update" },
+  },
+  required: ["tool", "input", "activity"],
+};
+
+describe("coerceObjectParamsToJsonString", () => {
+  test("rewrites object params to strings and reports the keys", () => {
+    const { parameters, objectKeys } =
+      coerceObjectParamsToJsonString(SKILL_EXECUTE_SCHEMA);
+
+    expect(objectKeys).toEqual(["input"]);
+    const props = (
+      parameters as { properties: Record<string, { type: string }> }
+    ).properties;
+    expect(props.input.type).toBe("string");
+    // Scalars are left untouched.
+    expect(props.tool.type).toBe("string");
+    expect(props.activity.type).toBe("string");
+    // The required list is preserved.
+    expect((parameters as { required: string[] }).required).toEqual([
+      "tool",
+      "input",
+      "activity",
+    ]);
+  });
+
+  test("leaves array and scalar params alone (no coercion)", () => {
+    const schema = {
+      type: "object",
+      properties: {
+        query: { type: "string" },
+        sources: { type: "array", items: { type: "string" } },
+      },
+    };
+    const { parameters, objectKeys } = coerceObjectParamsToJsonString(schema);
+    expect(objectKeys).toEqual([]);
+    expect(parameters).toEqual(schema);
+  });
+
+  test("handles type unions that include object", () => {
+    const schema = {
+      type: "object",
+      properties: { data: { type: ["object", "null"] } },
+    };
+    const { objectKeys } = coerceObjectParamsToJsonString(schema);
+    expect(objectKeys).toEqual(["data"]);
+  });
+});
+
+describe("decodeCoercedObjectArgs", () => {
+  test("round-trips a JSON-string object back into an object", () => {
+    const { objectKeys } = coerceObjectParamsToJsonString(SKILL_EXECUTE_SCHEMA);
+    // What minimax would send once `input` is a string param.
+    const onWire = {
+      tool: "app_delete",
+      input: '{"app_id": "5ee3d2d5-46e8-4a79-928f-00a7471d340b"}',
+      activity: "Delete placeholder",
+    };
+    const { input, failedKey } = decodeCoercedObjectArgs(onWire, objectKeys);
+    expect(failedKey).toBeUndefined();
+    expect(input.input).toEqual({
+      app_id: "5ee3d2d5-46e8-4a79-928f-00a7471d340b",
+    });
+    // Scalars pass through unchanged.
+    expect(input.tool).toBe("app_delete");
+  });
+
+  test("empty string decodes to an empty object", () => {
+    const { input } = decodeCoercedObjectArgs({ input: "" }, ["input"]);
+    expect(input.input).toEqual({});
+  });
+
+  test("is idempotent when the value is already an object", () => {
+    const args = { input: { app_id: "x" } };
+    const { input, failedKey } = decodeCoercedObjectArgs(args, ["input"]);
+    expect(failedKey).toBeUndefined();
+    expect(input.input).toEqual({ app_id: "x" });
+  });
+
+  test("reports failedKey on invalid JSON instead of throwing", () => {
+    const { failedKey } = decodeCoercedObjectArgs(
+      { input: "{not valid json" },
+      ["input"],
+    );
+    expect(failedKey).toBe("input");
+  });
+
+  test("no-op when there are no coerced keys", () => {
+    const args = { tool: "x", input: "{}" };
+    const { input } = decodeCoercedObjectArgs(args, []);
+    expect(input).toEqual(args);
+  });
+});