@vellumai/assistant 0.8.9-dev.202606091926.ebb2d62 → 0.8.9-dev.202606092047.e63da55

package/examples/plugins/echo/README.md

@@ -16,8 +16,8 @@ to eyeball which hooks fire during a conversation.
 
 For the full plugin authoring guide — manifest shape, every contribution
 surface, hook patterns, and conventions — see
-[`experimental/plugins/README.md`](../../../../experimental/plugins/README.md).
-[`simple-memory`](../../../../experimental/plugins/simple-memory/) is the
+[`plugins/README.md`](../../../../plugins/README.md).
+[`simple-memory`](../../../../plugins/simple-memory/) is the
 canonical reference implementation that exercises every wired surface.
 
 ## What it does
@@ -115,7 +115,7 @@ vellum restart
 
 ## Next steps
 
-- Read [`experimental/plugins/README.md`](../../../../experimental/plugins/README.md)
+- Read [`plugins/README.md`](../../../../plugins/README.md)
   for the full plugin authoring guide: manifest shape, every contribution
   surface, hook patterns (observe / transform), tool contributions, and
   conventions.

package/openapi.yaml

@@ -16251,6 +16251,8 @@ paths:
                               - name
                               - input
                             additionalProperties: false
+                          deprecated: true
+                          description: "Deprecated: superseded by contentBlocks (the tool_use variant). Flat list of tool calls."
                         surfaces:
                           type: array
                           items:
@@ -16302,6 +16304,8 @@ paths:
                               - surfaceType
                               - data
                             additionalProperties: false
+                          deprecated: true
+                          description: "Deprecated: superseded by contentBlocks (the surface variant). Flat list of surfaces."
                         textSegments:
                           type: array
                           items:
@@ -19471,11 +19475,11 @@ paths:
       operationId: plugins_install_post
       summary: Install a plugin
       description:
-        "Install a plugin by name from the canonical source — a whitelisted `experimental/plugins/marketplace.json`
-        entry, else the first-party `experimental/plugins/<name>/` convention. Always resolves against the curated
-        default git ref (no caller-supplied ref): installing from an unreviewed revision would bypass the
-        marketplace/first-party curation boundary and let attacker-controlled code be loaded. Materializes the plugin
-        under `<workspaceDir>/plugins/<name>/`; the assistant must be restarted to load it. Mirrors the CLI's `assistant
+        "Install a plugin by name from the canonical source — a whitelisted `plugins/marketplace.json` entry, else
+        the first-party `plugins/<name>/` convention. Always resolves against the curated default git ref (no
+        caller-supplied ref): installing from an unreviewed revision would bypass the marketplace/first-party curation
+        boundary and let attacker-controlled code be loaded. Materializes the plugin under
+        `<workspaceDir>/plugins/<name>/`; the assistant must be restarted to load it. Mirrors the CLI's `assistant
         plugins install <name>`. An already-installed name without `force` returns 409; a name that resolves to nothing
         returns 404. Sibling to `POST /v1/skills/install`."
       tags:
@@ -19537,9 +19541,9 @@ paths:
       operationId: plugins_search_get
       summary: Search the plugin catalog
       description:
-        List installable plugins from the canonical `vellum-ai/vellum-assistant` catalog at
-        `experimental/plugins/`. The query is an ECMAScript regex matched case-insensitively against the directory name
-        (e.g. `memory`, `^simple`). Empty query returns every entry. Mirrors the CLI's `assistant plugins search`.
+        List installable plugins from the canonical `vellum-ai/vellum-assistant` catalog at `plugins/`. The query
+        is an ECMAScript regex matched case-insensitively against the directory name (e.g. `memory`, `^simple`). Empty
+        query returns every entry. Mirrors the CLI's `assistant plugins search`.
       tags:
         - plugins
       responses:
@@ -19567,7 +19571,7 @@ paths:
                         path:
                           type: string
                           description:
-                            "Human-readable origin: a repo-relative path (`experimental/plugins/<name>`) for first-party plugins or a
+                            "Human-readable origin: a repo-relative path (`plugins/<name>`) for first-party plugins or a
                             `github:owner/repo@ref` locator for external ones."
                         description:
                           description: Short description, when known (external entries only today).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.8.9-dev.202606091926.ebb2d62",
+  "version": "0.8.9-dev.202606092047.e63da55",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/agent-loop-exit-reason.test.ts

@@ -39,18 +39,21 @@ import type {
 
 // The agent loop invokes the default post-compaction re-injection hook directly
 // when it compacts in place. Stub it so these unit tests can drive the
-// re-injection result without the daemon-level injector chain. Tests assign
-// `postCompactImpl` to observe the call or force a failure; when unset
-// the hook is a no-op that returns the history it was handed.
+// re-injection result without the daemon-level injector chain. The hook writes
+// the re-injected history back onto the context; tests assign `postCompactImpl`
+// to observe the call or force a failure; when unset the hook leaves the
+// history it was handed untouched.
 let postCompactImpl:
   | ((input: PostCompactContext) => Promise<Message[]>)
   | null = null;
 mock.module(
   "../plugins/defaults/memory-retrieval/hooks/post-compact.js",
   () => ({
-    default: async (input: PostCompactContext) => ({
-      messages: postCompactImpl ? await postCompactImpl(input) : input.history,
-    }),
+    default: async (input: PostCompactContext): Promise<void> => {
+      input.history = postCompactImpl
+        ? await postCompactImpl(input)
+        : input.history;
+    },
   }),
 );
 

package/src/__tests__/conversation-fork-crud.test.ts

@@ -922,6 +922,116 @@ describe("forkConversation", () => {
     expect(loadGraphMemoryState(fork.id)).toBeNull();
   });
 
+  test("truncated fork seeds everInjected from inherited memory attachments", async () => {
+    const source = createConversation("Truncated seed thread");
+    await addMessage(source.id, "user", "first turn", {
+      metadata: {
+        memoryInjectedBlock:
+          "# memory/concepts/topics/page-a.md\nSummary A\n\n# memory/concepts/topics/page-b.md\nSummary B",
+      },
+      skipIndexing: true,
+    });
+    await addMessage(source.id, "assistant", "first reply", {
+      skipIndexing: true,
+    });
+    const boundaryMessage = await addMessage(source.id, "user", "second turn", {
+      metadata: {
+        memoryInjectedBlock: "# memory/concepts/topics/page-c.md\nSummary C",
+      },
+      skipIndexing: true,
+    });
+    await addMessage(source.id, "assistant", "second reply", {
+      skipIndexing: true,
+    });
+    // Past the fork boundary — its attachment must NOT be claimed.
+    await addMessage(source.id, "user", "third turn", {
+      metadata: {
+        memoryInjectedBlock: "# memory/concepts/topics/page-d.md\nSummary D",
+      },
+      skipIndexing: true,
+    });
+
+    const db = getDb();
+    db.insert(activationState)
+      .values({
+        conversationId: source.id,
+        messageId: "parent-msg",
+        stateJson: JSON.stringify({ "topics/page-d": 0.9 }),
+        everInjectedJson: JSON.stringify([
+          { slug: "topics/page-a", turn: 1 },
+          { slug: "topics/page-b", turn: 1 },
+          { slug: "topics/page-c", turn: 2 },
+          { slug: "topics/page-d", turn: 3 },
+        ]),
+        currentTurn: 3,
+        updatedAt: 1_700_000_000_000,
+      })
+      .run();
+
+    const fork = forkConversation({
+      conversationId: source.id,
+      throughMessageId: boundaryMessage.id,
+    });
+
+    const childState = await hydrateActivationState(db, fork.id);
+    expect(childState).not.toBeNull();
+    // Exactly the slugs whose attachments live in the copied history —
+    // page-d (injected past the boundary) stays re-injectable.
+    expect(childState?.everInjected.map((e) => e.slug).sort()).toEqual([
+      "topics/page-a",
+      "topics/page-b",
+      "topics/page-c",
+    ]);
+    expect(childState?.everInjected.every((e) => e.turn === 0)).toBe(true);
+    // Activation scores and the turn counter start fresh, matching the
+    // graph tracker (also not copied for truncated forks).
+    expect(childState?.state).toEqual({});
+    expect(childState?.currentTurn).toBe(0);
+  });
+
+  test("truncated fork ignores attachments behind an inherited compaction boundary", async () => {
+    const source = createConversation("Compacted truncated thread");
+    await addMessage(source.id, "user", "compacted turn", {
+      metadata: {
+        memoryInjectedBlock:
+          "# memory/concepts/topics/page-compacted.md\nOld summary",
+      },
+      skipIndexing: true,
+    });
+    await addMessage(source.id, "assistant", "compacted reply", {
+      skipIndexing: true,
+    });
+    const boundaryMessage = await addMessage(source.id, "user", "live turn", {
+      metadata: {
+        memoryInjectedBlock: "# memory/concepts/topics/page-live.md\nSummary",
+      },
+      skipIndexing: true,
+    });
+    await addMessage(source.id, "assistant", "live reply", {
+      skipIndexing: true,
+    });
+    await addMessage(source.id, "user", "past boundary", {
+      skipIndexing: true,
+    });
+    // First two messages sit behind the compaction boundary: their
+    // attachments are not rendered, so the fork must not claim them.
+    getDb()
+      .update(conversations)
+      .set({ contextCompactedMessageCount: 2 })
+      .where(eq(conversations.id, source.id))
+      .run();
+
+    const fork = forkConversation({
+      conversationId: source.id,
+      throughMessageId: boundaryMessage.id,
+    });
+
+    const childState = await hydrateActivationState(getDb(), fork.id);
+    expect(childState?.everInjected.map((e) => e.slug)).toEqual([
+      "topics/page-live",
+    ]);
+  });
+
   test("defaults conversationType to standard and inherits the parent's group", async () => {
     const source = createConversation("Default inheritance thread");
     await addMessage(source.id, "user", "first message", {

package/src/__tests__/conversation-runtime-assembly.test.ts

@@ -64,6 +64,7 @@ mock.module("../daemon/date-context.js", () => ({
   formatTurnTimestamp: () => FIXED_TURN_TIMESTAMP,
 }));
 
+import { resolveCallSiteConfig } from "../config/llm-resolver.js";
 import { LLMSchema } from "../config/schemas/llm.js";
 import {
   clearConversations,
@@ -107,7 +108,9 @@ import {
   writeSlackMetadata,
 } from "../messaging/providers/slack/message-metadata.js";
 import { parentAlias } from "../messaging/providers/slack/render-transcript.js";
-import postCompact from "../plugins/defaults/memory-retrieval/hooks/post-compact.js";
+import postCompact, {
+  type PostCompactContext,
+} from "../plugins/defaults/memory-retrieval/hooks/post-compact.js";
 import {
   buildUnifiedTurnContextBlock,
   type UnifiedTurnContextOptions,
@@ -1029,16 +1032,17 @@ describe("applyRuntimeInjections — injection mode", () => {
     // only resolve when `applyRuntimeInjections` finds it by conversation id
     // AND the agent loop hands the post-compaction hook the turn-identity fields
     // flat (`requestId`, `conversationId`, `trust`)
-    const { messages: result } = await postCompact({
+    const postCompactCtx: PostCompactContext = {
       history: baseMessages,
       requestId: "reinject-req",
       conversationId: "injection-mode-conv",
       trust: { sourceChannel: "vellum", trustClass: "guardian" },
       isNonInteractive: false,
-      mode: "full",
-      modelProfile: null,
+      modelProfileKey: null,
       actorContext: null,
-    });
+    };
+    await postCompact(postCompactCtx);
+    const result = postCompactCtx.history;
     const allText = result[0].content
       .filter((b): b is { type: "text"; text: string } => b.type === "text")
       .map((b) => b.text)
@@ -1572,6 +1576,50 @@ describe("resolveTurnModelProfileLabel", () => {
     // THEN the raw key stands in for the missing label
     expect(label).toBe("deep (claude-opus-4)");
   });
+
+  /**
+   * A key naming a `mix` profile must announce the arm the turn's provider
+   * calls actually run on. The conversation id is threaded as the selection
+   * seed so the announced model is a deterministic function of the
+   * conversation, matching the seeded expansion the provider layer performs.
+   */
+  test("announces the seeded mix arm so it matches the turn's model", () => {
+    // GIVEN a mix profile routing between two models
+    const llm = LLMSchema.parse({
+      default: { provider: "anthropic", model: "claude-sonnet-4-7" },
+      profiles: {
+        a: { label: "Arm A", provider: "anthropic", model: "model-a" },
+        b: { label: "Arm B", provider: "anthropic", model: "model-b" },
+        ab: {
+          label: "AB",
+          mix: [
+            { profile: "a", weight: 50 },
+            { profile: "b", weight: 50 },
+          ],
+        },
+      },
+    });
+
+    // AND the model the provider calls resolve to for this conversation's seed
+    const seededModel = resolveCallSiteConfig("mainAgent", llm, {
+      overrideProfile: "ab",
+      selectionSeed: "conv-seed-1",
+    }).model;
+
+    // WHEN the label is resolved with the same conversation seed
+    const label = resolveTurnModelProfileLabel(
+      "ab",
+      "mainAgent",
+      llm,
+      "conv-seed-1",
+    );
+
+    // THEN the announced model is the seeded arm (deterministic, not re-rolled)
+    expect(label).toBe(`AB (${seededModel})`);
+    expect(
+      resolveTurnModelProfileLabel("ab", "mainAgent", llm, "conv-seed-1"),
+    ).toBe(label);
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/__tests__/external-plugin-loader.test.ts

@@ -533,7 +533,6 @@ describe("loadExternalPlugin — end-to-end @vellumai/simple-memory", () => {
       "..",
       "..",
       "..",
-      "experimental",
       "plugins",
       "simple-memory",
     );

package/src/__tests__/plugin-bootstrap.test.ts

@@ -399,11 +399,11 @@ describe("plugin bootstrap", () => {
     expect(initFired).toBe(true);
   });
 
-  test("requiresFlag disabled: init does not fire and no tools/routes/skills are registered", async () => {
+  test("requiresFlag disabled: init does not fire and no tools/routes are registered", async () => {
     setOverridesForTesting({ "plugin-gated-disabled": false });
 
     let initFired = false;
-    // Attach tool/route/skill contributions alongside init. If gating works,
+    // Attach tool/route contributions alongside init. If gating works,
     // none of them should land in their respective registries.
     const plugin = buildPlugin(
       "gated-off",
@@ -430,24 +430,14 @@ describe("plugin bootstrap", () => {
             handler: async () => new Response("ok"),
           },
         ],
-        skills: [
-          {
-            id: "gated-off/skill",
-            name: "gated-off-skill",
-            description: "should not be catalogued",
-            body: "# unused",
-          },
-        ],
       },
       { requiresFlag: ["plugin-gated-disabled"] },
     );
     registerPlugin(plugin);
 
-    // Grab tool / route / skill introspection helpers lazily so the import
+    // Grab tool / route introspection helpers lazily so the import
     // side effect happens after `mock.module` has taken effect.
     const { getTool } = await import("../tools/registry.js");
-    const { getPluginSkillRefCount } =
-      await import("../plugins/plugin-skill-contributions.js");
     const { matchSkillRoute } =
       await import("../runtime/skill-route-registry.js");
 
@@ -459,8 +449,6 @@ describe("plugin bootstrap", () => {
     expect(getTool("gated-off-tool")).toBeUndefined();
     // No route wired up — `matchSkillRoute` returns null when nothing matches.
     expect(matchSkillRoute("/_plugin/gated-off/status", "GET")).toBeNull();
-    // No skill catalogued under this plugin's name — ref count stays 0.
-    expect(getPluginSkillRefCount("gated-off")).toBe(0);
   });
 
   test("requiresFlag absent: plugin activates unconditionally", async () => {

package/src/__tests__/plugin-types.test.ts

@@ -78,14 +78,6 @@ describe("plugin core types", () => {
           handler: async () => new Response("ok", { status: 200 }),
         },
       ],
-      skills: [
-        {
-          id: "sample-skill",
-          name: "Sample Skill",
-          description: "Demo plugin-contributed skill",
-          body: "## Sample\n\nPlugin-provided skill body.",
-        },
-      ],
     } satisfies Plugin;
 
     // Minimal runtime check so the test body is non-empty.

package/src/__tests__/skills.test.ts

@@ -252,6 +252,129 @@ describe("workspace skills", () => {
   });
 });
 
+describe("plugin-resident skills", () => {
+  const pluginsDir = join(TEST_DIR, "plugins");
+
+  /**
+   * Materialize a skill on disk inside an installed plugin directory:
+   * `plugins/<plugin>/skills/<skillId>/SKILL.md`. A `package.json` is written
+   * for the plugin by default since that is the install gate the discovery
+   * scan keys on; pass `withPackageJson: false` to simulate a stray directory.
+   */
+  function writePluginSkill(
+    pluginName: string,
+    skillId: string,
+    name: string,
+    description: string,
+    body: string = "Plugin skill body",
+    {
+      withPackageJson = true,
+      packageName,
+    }: { withPackageJson?: boolean; packageName?: string } = {},
+  ): void {
+    const pluginDir = join(pluginsDir, pluginName);
+    mkdirSync(pluginDir, { recursive: true });
+    if (withPackageJson) {
+      writeFileSync(
+        join(pluginDir, "package.json"),
+        JSON.stringify({ name: packageName ?? pluginName, version: "1.0.0" }),
+      );
+    }
+    const skillDir = join(pluginDir, "skills", skillId);
+    mkdirSync(skillDir, { recursive: true });
+    writeFileSync(
+      join(skillDir, "SKILL.md"),
+      `---\nname: "${name}"\ndescription: "${description}"\n---\n\n${body}\n`,
+    );
+  }
+
+  beforeEach(() => {
+    mkdirSync(join(TEST_DIR, "skills"), { recursive: true });
+  });
+
+  afterEach(() => {
+    for (const dir of [join(TEST_DIR, "skills"), pluginsDir]) {
+      if (existsSync(dir)) rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("discovers skills shipped inside an installed plugin, attributed to it", () => {
+    writePluginSkill("caveman", "caveman", "Caveman", "Terse mode");
+
+    const skill = loadSkillCatalog().find((s) => s.id === "caveman");
+    expect(skill).toBeDefined();
+    expect(skill!.source).toBe("plugin");
+    expect(skill!.owner).toEqual({ kind: "plugin", id: "caveman" });
+  });
+
+  test("loadSkillBySelector loads a plugin-resident skill body", () => {
+    writePluginSkill(
+      "caveman",
+      "caveman",
+      "Caveman",
+      "Terse mode",
+      "Full plugin skill body",
+    );
+
+    const result = loadSkillBySelector("caveman");
+    expect(result.error).toBeUndefined();
+    expect(result.skill).toBeDefined();
+    expect(result.skill!.source).toBe("plugin");
+    expect(result.skill!.body).toBe("Full plugin skill body");
+    expect(result.skill!.owner).toEqual({ kind: "plugin", id: "caveman" });
+  });
+
+  test("ignores plugin directories without a package.json (staging/stray dirs)", () => {
+    writePluginSkill(
+      "half-installed",
+      "ghost",
+      "Ghost",
+      "Should be skipped",
+      "body",
+      { withPackageJson: false },
+    );
+
+    const skill = loadSkillCatalog().find((s) => s.id === "ghost");
+    expect(skill).toBeUndefined();
+  });
+
+  test("ignores plugin dirs whose package.json name mismatches the directory", () => {
+    // Mirrors the loader's recognition gate: an un-adapted clone whose
+    // package.json declares `caveman-installer` in a `caveman` dir is skipped.
+    writePluginSkill("caveman", "caveman", "Caveman", "Terse mode", "body", {
+      packageName: "caveman-installer",
+    });
+
+    const skill = loadSkillCatalog().find((s) => s.id === "caveman");
+    expect(skill).toBeUndefined();
+  });
+
+  test("workspace skill overrides a plugin-resident skill with the same id", () => {
+    const WORKSPACE_DIR = join(
+      tmpdir(),
+      `vellum-workspace-test-${crypto.randomUUID()}`,
+    );
+    const workspaceSkillsDir = join(WORKSPACE_DIR, ".vellum", "skills");
+    mkdirSync(join(workspaceSkillsDir, "shared-id"), { recursive: true });
+    writeFileSync(
+      join(workspaceSkillsDir, "shared-id", "SKILL.md"),
+      `---\nname: "Workspace Wins"\ndescription: "Workspace version"\n---\n\nbody\n`,
+    );
+    writePluginSkill("caveman", "shared-id", "Plugin Loses", "Plugin version");
+
+    try {
+      const skill = loadSkillCatalog(workspaceSkillsDir).find(
+        (s) => s.id === "shared-id",
+      );
+      expect(skill).toBeDefined();
+      expect(skill!.source).toBe("workspace");
+      expect(skill!.name).toBe("Workspace Wins");
+    } finally {
+      rmSync(WORKSPACE_DIR, { recursive: true, force: true });
+    }
+  });
+});
+
 describe("tool manifest detection", () => {
   beforeEach(() => {
     mkdirSync(join(TEST_DIR, "skills"), { recursive: true });

package/src/agent/loop.ts

@@ -23,7 +23,9 @@ import type {
 } from "../plugin-api/types.js";
 import { defaultCompact } from "../plugins/defaults/compaction/compact.js";
 import type { ContextWindowResult } from "../plugins/defaults/compaction/window-manager.js";
-import postCompact from "../plugins/defaults/memory-retrieval/hooks/post-compact.js";
+import postCompact, {
+  type PostCompactContext,
+} from "../plugins/defaults/memory-retrieval/hooks/post-compact.js";
 import { runHook } from "../plugins/pipeline.js";
 import type { CompactionCircuitEvent } from "../plugins/types.js";
 import { normalizeThinkingConfigForWire } from "../providers/thinking-config.js";
@@ -509,15 +511,14 @@ export interface AgentLoopRunOptions {
    */
   isNonInteractive?: boolean;
   /**
-   * The `model_profile:` turn-context label resolved once by the orchestrator
-   * at turn start, or `null` when the active inference profile is unchanged
-   * since the last notified one. Forwarded to
-   * {@link postCompact} so post-compaction re-injection
-   * re-emits the turn-start value rather than re-deriving the change-detected
-   * label (which flips once the notification is persisted mid-turn). Defaults to
-   * `null` when omitted.
+   * The turn's resolved inference-profile key, or `null` when the active
+   * profile is unchanged since the last notified one. Forwarded to
+   * {@link postCompact}, which renders the `model_profile:` label from it so
+   * post-compaction re-injection re-emits the turn-start profile rather than
+   * re-deriving the change-detected value (which flips once the notification is
+   * persisted mid-turn). Defaults to `null` when omitted.
    */
-  modelProfile?: string | null;
+  modelProfileKey?: string | null;
   /**
    * Inbound actor identity and trust fields for the unified `<turn_context>`
    * block, or `null` on guardian turns. Resolved once by the orchestrator at
@@ -715,7 +716,7 @@ export class AgentLoop {
     onEvent: (event: AgentEvent) => void | Promise<void>,
     overrideProfile: string | null,
     isNonInteractive: boolean,
-    modelProfile: string | null,
+    modelProfileKey: string | null,
     actorContext: InboundActorContext | null,
   ): Promise<Message[] | null> {
     await onEvent({ type: "context_compacting" });
@@ -767,18 +768,19 @@ export class AgentLoop {
     // Re-inject onto the same base the `compaction_completed` dispatch commits:
     // the compacted messages when the pipeline compacted, the stripped
     // pre-compaction history otherwise.
-    const injection = await postCompact({
+    const postCompactCtx: PostCompactContext = {
       history: compactResult.compacted ? compactResult.messages : rawHistory,
       requestId,
       conversationId: this.conversationId,
       trust,
       isNonInteractive,
-      // Mid-loop re-injection always runs at full injection volume.
-      mode: "full",
-      modelProfile,
+      modelProfileKey,
       actorContext,
-    });
-    return injection.messages;
+    };
+    // The hook writes the re-injected history back onto the context; read it
+    // from there once the hook settles.
+    await postCompact(postCompactCtx);
+    return postCompactCtx.history;
   }
 
   async run(options: AgentLoopRunOptions): Promise<AgentLoopRunResult> {
@@ -795,7 +797,7 @@ export class AgentLoop {
       resolveContextWindow,
       compactInPlace = false,
       isNonInteractive = false,
-      modelProfile = null,
+      modelProfileKey = null,
       actorContext = null,
     } = options;
     let history = [...messages];
@@ -923,7 +925,7 @@ export class AgentLoop {
                   onEvent,
                   resolveEffectiveOverrideProfile() ?? null,
                   isNonInteractive,
-                  modelProfile,
+                  modelProfileKey,
                   actorContext,
                 );
                 if (compacted) {

package/src/api/responses/conversation-message.ts

@@ -374,9 +374,40 @@ export const ConversationMessageSchema = z.object({
     .optional(),
   /** Display timestamp as an ISO-8601 string. */
   timestamp: z.string(),
+  /**
+   * Flat list of attachment metadata for the row. Not yet supersedable by
+   * `contentBlocks`: `renderHistoryContent` emits an `attachment` content
+   * block only for file-block refs with an inline placement, so orphan rows
+   * (unmatched ids, count mismatch, no DB rows — see `alignAttachments`) ship
+   * here alone. Kept non-deprecated until `contentBlocks` reaches attachment
+   * parity, so clients that migrate off the positional arrays don't drop those
+   * chips.
+   */
   attachments: z.array(ConversationMessageAttachmentSchema),
-  toolCalls: z.array(ConversationMessageToolCallSchema).optional(),
-  surfaces: z.array(ConversationMessageSurfaceSchema).optional(),
+  /**
+   * @deprecated Superseded by `contentBlocks` (the `tool_use` variant). Flat
+   * list of tool calls for the row.
+   */
+  toolCalls: z
+    .array(ConversationMessageToolCallSchema)
+    .meta({
+      deprecated: true,
+      description:
+        "Deprecated: superseded by contentBlocks (the tool_use variant). Flat list of tool calls.",
+    })
+    .optional(),
+  /**
+   * @deprecated Superseded by `contentBlocks` (the `surface` variant). Flat
+   * list of surfaces for the row.
+   */
+  surfaces: z
+    .array(ConversationMessageSurfaceSchema)
+    .meta({
+      deprecated: true,
+      description:
+        "Deprecated: superseded by contentBlocks (the surface variant). Flat list of surfaces.",
+    })
+    .optional(),
   /**
    * @deprecated Superseded by `contentBlocks`. Text split by tool-call
    * boundaries; positional sibling of `contentOrder`.