@vellumai/assistant 0.6.5 → 0.7.0

package/src/config/assistant-feature-flags.ts

@@ -5,12 +5,9 @@
  * `meta/feature-flags/feature-flag-registry.json` and resolves the effective
  * enabled/disabled state for each declared assistant-scope flag by consulting
  * (in priority order):
- *   1. Override values from the gateway IPC socket (or local file fallback)
- *   2. Remote values from `feature-flags-remote.json` (platform-pushed,
- *      cached locally; only used in local mode — containerized mode gets
- *      remote values via the gateway)
- *   3. defaults registry `defaultEnabled`         (for declared keys)
- *   4. `true`                                     (for undeclared keys)
+ *   1. Override values from the gateway IPC socket
+ *   2. defaults registry `defaultEnabled`         (for declared keys)
+ *   3. `true`                                     (for undeclared keys)
  *
  * Key format:
  *   Canonical:  simple kebab-case string (e.g., "browser", "ces-tools")
@@ -20,7 +17,6 @@ import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 
 import { ipcGetFeatureFlags } from "../ipc/gateway-client.js";
-import { getProtectedDir } from "../util/platform.js";
 import type { AssistantConfig } from "./schema.js";
 
 // ---------------------------------------------------------------------------
@@ -128,59 +124,6 @@ let cachedOverrides: Record<string, boolean> | null = null;
  */
 let cachedOverridesFromGateway = false;
 
-/**
- * File format for the local feature-flags.json override file, matching the
- * gateway's feature-flag-store.ts schema.
- */
-interface FeatureFlagFileData {
-  version: 1;
-  values: Record<string, boolean>;
-}
-
-/**
- * Resolve the path to the feature flag overrides file.
- *
- * Docker: `GATEWAY_SECURITY_DIR/feature-flags.json`
- * Local:  `<protectedDir>/feature-flags.json` — resolved via `getProtectedDir()`
- *         so it honors `BASE_DATA_DIR` for per-instance setups.
- */
-function getFeatureFlagOverridesPath(): string {
-  const securityDir = process.env.GATEWAY_SECURITY_DIR;
-  if (securityDir) {
-    return join(securityDir, "feature-flags.json");
-  }
-  return join(getProtectedDir(), "feature-flags.json");
-}
-
-/**
- * Load override values from the local feature-flags.json file.
- * Returns an empty record if the file doesn't exist or is malformed.
- */
-function loadOverridesFromFile(): Record<string, boolean> {
-  const path = getFeatureFlagOverridesPath();
-  if (!existsSync(path)) return {};
-
-  try {
-    const raw = readFileSync(path, "utf-8");
-    const data = JSON.parse(raw) as FeatureFlagFileData;
-    if (data.version !== 1) return {};
-    if (
-      data.values &&
-      typeof data.values === "object" &&
-      !Array.isArray(data.values)
-    ) {
-      const filtered: Record<string, boolean> = {};
-      for (const [k, v] of Object.entries(data.values)) {
-        if (typeof v === "boolean") filtered[k] = v;
-      }
-      return filtered;
-    }
-    return {};
-  } catch {
-    return {};
-  }
-}
-
 /**
  * Fetch override values from the gateway via IPC (Unix domain socket).
  *
@@ -205,9 +148,8 @@ async function fetchOverridesFromGateway(): Promise<Record<string, boolean>> {
  * uses the gateway. In local mode, falls back to the local file when
  * the gateway is unreachable.
  *
- * On failure, the cache is left unset so subsequent sync calls fall
- * through to the file-based fallback rather than caching an empty map
- * that masks all overrides for the process lifetime.
+ * On failure, the cache is left unset so subsequent sync calls return an
+ * empty override map (registry defaults only).
  *
  * No-ops when the cache is already populated — callers that want to
  * refresh must call `clearFeatureFlagOverridesCache()` first. This lets
@@ -224,23 +166,18 @@ export async function initFeatureFlagOverrides(): Promise<void> {
     return;
   }
 
-  // Gateway returned empty or failed. If the cache was populated from the
-  // file fallback, leave it in place for the next sync read. Otherwise leave
-  // unset so `loadOverrides()` falls through to file on first sync read.
+  // Gateway returned empty or failed — leave cache unset so loadOverrides()
+  // returns an empty map on subsequent sync reads.
 }
 
 /**
  * Read cached overrides synchronously.
  *
- * If `initFeatureFlagOverrides()` was called at startup, this returns the
- * pre-populated cache. Otherwise falls back to the local file — this
- * ensures the resolver never blocks on a network call.
+ * Returns the gateway-populated cache if `initFeatureFlagOverrides()` was
+ * called at startup, or an empty record otherwise.
  */
 function loadOverrides(): Record<string, boolean> {
-  if (cachedOverrides != null) return cachedOverrides;
-
-  cachedOverrides = loadOverridesFromFile();
-  return cachedOverrides;
+  return cachedOverrides ?? {};
 }
 
 // ---------------------------------------------------------------------------
@@ -253,47 +190,15 @@ function loadOverrides(): Record<string, boolean> {
  */
 let cachedRemoteValues: Record<string, boolean> | null = null;
 
-/**
- * Load remote flag values from the `feature-flags-remote.json` file that
- * lives alongside the local overrides file. Returns an empty record if the
- * file doesn't exist or is malformed.
- *
- * In containerized mode, this file won't exist — the gateway already merges
- * remote values into its response — so we'll harmlessly return `{}`.
- */
-function loadRemoteValuesFromFile(): Record<string, boolean> {
-  const overridesPath = getFeatureFlagOverridesPath();
-  const remotePath = join(dirname(overridesPath), "feature-flags-remote.json");
-  if (!existsSync(remotePath)) return {};
-
-  try {
-    const raw = readFileSync(remotePath, "utf-8");
-    const data = JSON.parse(raw) as FeatureFlagFileData;
-    if (data.version !== 1) return {};
-    if (
-      data.values &&
-      typeof data.values === "object" &&
-      !Array.isArray(data.values)
-    ) {
-      const filtered: Record<string, boolean> = {};
-      for (const [k, v] of Object.entries(data.values)) {
-        if (typeof v === "boolean") filtered[k] = v;
-      }
-      return filtered;
-    }
-    return {};
-  } catch {
-    return {};
-  }
-}
-
 /**
  * Load remote values with module-level caching.
+ *
+ * Remote values are now always included in the gateway IPC response (merged
+ * server-side), so this only returns the injected test cache. In production,
+ * remote values flow through the overrides cache.
  */
 function loadRemoteValues(): Record<string, boolean> {
-  if (cachedRemoteValues != null) return cachedRemoteValues;
-  cachedRemoteValues = loadRemoteValuesFromFile();
-  return cachedRemoteValues;
+  return cachedRemoteValues ?? {};
 }
 
 /**
@@ -338,11 +243,9 @@ export function _setOverridesForTesting(
  * Resolve whether an assistant feature flag is enabled.
  *
  * Resolution order:
- *   1. Override from gateway IPC socket (or local file fallback)
- *   2. Remote value from `feature-flags-remote.json` (platform-pushed,
- *      cached locally)
- *   3. defaults registry `defaultEnabled`         (for declared assistant-scope keys)
- *   4. `true`                                     (for undeclared keys with no override)
+ *   1. Override from gateway IPC socket
+ *   2. defaults registry `defaultEnabled`         (for declared assistant-scope keys)
+ *   3. `true`                                     (for undeclared keys with no override)
  */
 export function isAssistantFeatureFlagEnabled(
   key: string,
@@ -367,30 +270,3 @@ export function isAssistantFeatureFlagEnabled(
   // 4. Undeclared keys with no persisted override default to enabled
   return true;
 }
-
-/**
- * Return the loaded defaults registry (for introspection/tooling).
- */
-export function getAssistantFeatureFlagDefaults(): FeatureFlagDefaultsRegistry {
-  return loadDefaultsRegistry();
-}
-
-// ---------------------------------------------------------------------------
-// Named flag helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Canonical key for the `home-feed` flag — gates the activity feed section on
- * the macOS Home page (nudges, digests, actions, threads). Requires the
- * `home-tab` flag to also be enabled. Declared in
- * `meta/feature-flags/feature-flag-registry.json` with scope `macos`.
- */
-export const HOME_FEED_FLAG = "home-feed";
-
-/**
- * Resolve whether the `home-feed` flag is enabled for the current assistant
- * config. Wraps `isAssistantFeatureFlagEnabled` with the canonical key.
- */
-export function isHomeFeedEnabled(config: AssistantConfig): boolean {
-  return isAssistantFeatureFlagEnabled(HOME_FEED_FLAG, config);
-}

package/src/config/bundled-skills/acp/SKILL.md

@@ -8,7 +8,7 @@ metadata:
     display-name: "ACP"
 ---
 
-ACP agent orchestration - spawn external coding agents (Claude Code, Codex, Gemini CLI, etc.) to work on tasks via the Agent Client Protocol.
+ACP agent orchestration - spawn external coding agents (Claude Code, Codex, etc.) to work on tasks via the Agent Client Protocol. Each agent runs as its own subprocess speaking ACP over stdio and streams results back into the conversation.
 
 ## Usage
 
@@ -20,22 +20,15 @@ When the user first tries to use ACP and it's not configured, set it up automati
 
 1. **Check if `claude-agent-acp` is installed** by running `which claude-agent-acp`. If not found, install it:
    ```bash
-   npm install -g @zed-industries/claude-agent-acp
+   npm i -g @agentclientprotocol/claude-agent-acp
    ```
 
-2. **Enable ACP in the workspace config** by editing the config file to add the `acp` section. The correct config is:
+2. **Enable ACP in the workspace config** by editing the config file to add the `acp` section. Default profiles for `claude` and `codex` ship out-of-box, so the minimal config is just:
    ```json
    {
      "acp": {
        "enabled": true,
-       "maxConcurrentSessions": 4,
-       "agents": {
-         "claude": {
-           "command": "claude-agent-acp",
-           "args": [],
-           "description": "Claude Code (via ACP adapter)"
-         }
-       }
+       "maxConcurrentSessions": 4
      }
    }
    ```
@@ -44,22 +37,57 @@ When the user first tries to use ACP and it's not configured, set it up automati
 
 4. Then retry the `acp_spawn` call. Do NOT run `vellum sleep && vellum wake` - that kills the conversation.
 
+## Codex setup
+
+To use Codex via ACP, both the `codex-acp` adapter and the underlying `codex` CLI must be on PATH:
+
+1. **Install the ACP adapter:**
+   ```bash
+   npm i -g @zed-industries/codex-acp
+   ```
+   This provides the `codex-acp` binary that the assistant spawns.
+
+2. **Install the Codex CLI** (version 0.111 or higher) via OpenAI's distribution channel of choice. The `codex-acp` adapter shells out to `codex` under the hood and will fail if it isn't on PATH.
+
+3. **Authenticate.** The `codex-acp` adapter inherits whatever auth the underlying `codex` CLI uses. Typical flows:
+   - `codex login` (OAuth)
+   - `CODEX_API_KEY` environment variable
+   - `OPENAI_API_KEY` environment variable
+
+If `codex-acp` isn't on PATH when the user asks for it, the assistant will surface the install hint via `acp_list_agents`.
+
 ## Critical: correct agent command
 
-- The command MUST be `claude-agent-acp` - this is the ACP adapter from `@zed-industries/claude-agent-acp`.
-- NEVER use `claude`, `claude -p`, `claude --acp`, or any other command. Only `claude-agent-acp` speaks the ACP JSON-RPC protocol.
-- NEVER change an existing ACP config to use a different command. If the config already has `claude-agent-acp`, leave it alone.
+- `claude-agent-acp` and `codex-acp` are the two supported adapter binaries today. They are what speak the ACP JSON-RPC protocol.
+- NEVER use `claude`, `claude -p`, `claude --acp`, the bare `codex` CLI, or any other command as the ACP `command`. Only the dedicated `*-acp` adapters speak the protocol.
+- Default profiles for `claude` and `codex` ship out-of-box. Users only need an `agents.<id>` entry in config if they want to override the defaults (e.g. point to a custom binary path or pass extra args).
+- NEVER change an existing ACP config to use a different command. If the config already has `claude-agent-acp` or `codex-acp`, leave it alone.
 
 ## Updating the adapter
 
-If `acp_spawn` reports that `claude-agent-acp` is outdated, ask the user before updating. To update:
+If `acp_spawn` reports that an adapter is outdated, ask the user before updating. To update:
 
 ```bash
-npm install -g @zed-industries/claude-agent-acp@latest
+npm i -g @agentclientprotocol/claude-agent-acp@latest
+# or
+npm i -g @zed-industries/codex-acp@latest
 ```
 
 Then retry the `acp_spawn` call.
 
+## When to use acp_steer vs acp_spawn
+
+- **`acp_steer` interrupts the in-flight prompt.** Use it to course-correct a running agent ("stop, do X instead"). It cancels whatever the agent is currently working on and replaces it with the new instruction.
+- **For follow-ups after the current task** ("also do Y when you're done"), do NOT use `acp_steer`. Wait for the `acp_session_completed` notification and call `acp_spawn` again with the new task. Queued follow-ups in the same session are not yet supported.
+
+## Discoverability
+
+Use `acp_list_agents` to see what's set up and what's missing. It returns each available agent profile, whether ACP is enabled, whether the agent's binary is on PATH, and an install hint if not. This is the right tool to call when deciding between `claude` and `codex`, or when the user asks "what coding agents do I have?"
+
+## Working directory
+
+Default to the conversation's current working directory when spawning an agent. For risky changes or parallel work where you don't want the agent touching the same checkout the user is editing, create a git worktree first via the shell tool and pass that worktree path as `cwd` to `acp_spawn`. That keeps the agent isolated from the user's in-progress work.
+
 ## Tips
 
 - The spawned agent runs autonomously with its own tools, file editing, and terminal access.

package/src/config/bundled-skills/acp/TOOLS.json

@@ -3,7 +3,7 @@
   "tools": [
     {
       "name": "acp_spawn",
-      "description": "Spawn an external coding agent (e.g. Claude Code, Codex, Gemini CLI) via ACP to work on a task. The agent runs as a subprocess and streams results back. Use this when you want to delegate a coding task to an external agent that has its own tools, file editing, and terminal access. If ACP is not enabled, follow the setup instructions in SKILL.md to install claude-agent-acp and configure it. The command MUST be 'claude-agent-acp' - NEVER use 'claude', 'claude -p', or 'claude --acp'.",
+      "description": "Spawn an external coding agent (e.g. Claude Code, Codex) via ACP to work on a task. Default profiles ship for `claude` (`claude-agent-acp`) and `codex` (`codex-acp`); the assistant resolves the agent id to the right adapter binary. The agent runs as a subprocess and streams results back. Use this when you want to delegate a coding task to an external agent that has its own tools, file editing, and terminal access. If a binary is missing, the call returns an actionable install hint — do NOT alter `agents.<id>.command` to swap binaries. If ACP is disabled, follow the setup instructions in SKILL.md.",
       "category": "orchestration",
       "risk": "high",
       "input_schema": {
@@ -74,6 +74,50 @@
       },
       "executor": "tools/acp-abort.ts",
       "execution_target": "host"
+    },
+    {
+      "name": "acp_steer",
+      "description": "**Interrupts** the in-flight prompt of a running ACP session and replaces it with `instruction`. Use to redirect the agent (e.g., 'stop, do X instead'). For follow-up work that should happen *after* the current task, do NOT use this — wait for `acp_session_completed` and `acp_spawn` again.",
+      "category": "orchestration",
+      "risk": "medium",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "acp_session_id": {
+            "type": "string",
+            "description": "The ID of the ACP session to steer."
+          },
+          "instruction": {
+            "type": "string",
+            "description": "The new instruction that replaces the in-flight prompt."
+          },
+          "activity": {
+            "type": "string",
+            "description": "Brief explanation of why this tool is being called"
+          }
+        },
+        "required": ["acp_session_id", "instruction"]
+      },
+      "executor": "tools/acp-steer.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "acp_list_agents",
+      "description": "Lists ACP coding agents available to spawn. Each entry includes whether ACP is enabled, whether the agent's binary is on PATH, and an install command if not. Use this to decide between 'claude' and 'codex' or to surface setup steps to the user.",
+      "category": "orchestration",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "activity": {
+            "type": "string",
+            "description": "Brief explanation of why this tool is being called"
+          }
+        },
+        "required": []
+      },
+      "executor": "tools/acp-list-agents.ts",
+      "execution_target": "host"
     }
   ]
 }

package/src/config/bundled-skills/{screen-watch/tools/start-screen-watch.ts → acp/tools/acp-list-agents.ts}

@@ -1,12 +1,12 @@
+import { executeAcpListAgents } from "../../../../tools/acp/list-agents.js";
 import type {
   ToolContext,
   ToolExecutionResult,
 } from "../../../../tools/types.js";
-import { screenWatchTool } from "../../../../tools/watch/screen-watch.js";
 
 export async function run(
   input: Record<string, unknown>,
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  return screenWatchTool.execute(input, context);
+  return executeAcpListAgents(input, context);
 }

package/src/config/bundled-skills/acp/tools/acp-steer.ts

@@ -0,0 +1,12 @@
+import { executeAcpSteer } from "../../../../tools/acp/steer.js";
+import type {
+  ToolContext,
+  ToolExecutionResult,
+} from "../../../../tools/types.js";
+
+export async function run(
+  input: Record<string, unknown>,
+  context: ToolContext,
+): Promise<ToolExecutionResult> {
+  return executeAcpSteer(input, context);
+}

package/src/config/bundled-skills/app-builder/SKILL.md

@@ -260,7 +260,7 @@ app_refresh(app_id)
 - Preact for UI (not React) - `import { render } from 'preact'`
 - TypeScript encouraged for all `.tsx`/`.ts` files
 - No external fonts, images, or resources - use system fonts and CSS/SVG for visuals
-- Design for 400-600px width with graceful resizing
+- Design responsively. Apps render at fluid, user-resizable widths — avoid fixed-pixel layouts
 - The WebView blocks all navigation - links and form `action` attributes won't work
 <!-- feature:app-builder-multifile:end -->
 
@@ -275,7 +275,7 @@ Write a complete, self-contained HTML document.
 - Single HTML string - no external files, CDNs, or imports
 - All CSS in `<style>` in `<head>`, all JavaScript in `<script>` before `</body>`
 - No external fonts, images, or resources - use system fonts and CSS/SVG for visuals
-- Design for 400-600px width with graceful resizing
+- Design responsively. Apps render at fluid, user-resizable widths — avoid fixed-pixel layouts
 - The WebView blocks all navigation - links and form `action` attributes won't work
 
 <!-- feature:app-builder-multifile:alt:end -->

package/src/config/bundled-skills/app-builder/references/WIDGETS.md

@@ -37,16 +37,16 @@ A CSS/JS widget library is auto-injected alongside the design system. Use these
 
 ## Content & landing page components
 
-| Widget                                           | Purpose                                             |
-| ------------------------------------------------ | --------------------------------------------------- |
-| `.v-hero` / `.v-hero-badge` / `.v-hero-subtitle` | Hero banner with gradient, trust badge, accent word |
-| `.v-section-header` / `.v-section-label`         | Section intro with label                            |
-| `.v-feature-grid` / `.v-feature-card`            | Feature showcase with hover lift                    |
-| `.v-pullquote`                                   | Blockquote with gradient accent border              |
-| `.v-comparison`                                  | Before/after cards (`.before`/`.after`)             |
-| `.v-page`                                        | Centered container (max-width 600px)                |
-| `.v-gradient-text`                               | Accent-colored gradient text                        |
-| `.v-animate-in`                                  | Staggered fade-in for children                      |
+| Widget                                           | Purpose                                                |
+| ------------------------------------------------ | ------------------------------------------------------ |
+| `.v-hero` / `.v-hero-badge` / `.v-hero-subtitle` | Hero banner with gradient, trust badge, accent word    |
+| `.v-section-header` / `.v-section-label`         | Section intro with label                               |
+| `.v-feature-grid` / `.v-feature-card`            | Feature showcase with hover lift                       |
+| `.v-pullquote`                                   | Blockquote with gradient accent border                 |
+| `.v-comparison`                                  | Before/after cards (`.before`/`.after`)                |
+| `.v-page`                                        | Centered flex-column container (fills available width) |
+| `.v-gradient-text`                               | Accent-colored gradient text                           |
+| `.v-animate-in`                                  | Staggered fade-in for children                         |
 
 ## Widget JavaScript utilities
 

package/src/config/bundled-skills/contacts/tools/contact-merge.ts

@@ -1,27 +1,11 @@
-import {
-  gatewayGet,
-  gatewayPost,
-  GatewayRequestError,
-} from "../../../../runtime/gateway-internal-client.js";
+import type { ContactWithChannels } from "../../../../contacts/types.js";
+import { cliIpcCall } from "../../../../ipc/cli-client.js";
+import { resolveGuardianName } from "../../../../prompts/user-reference.js";
 import type {
   ToolContext,
   ToolExecutionResult,
 } from "../../../../tools/types.js";
 
-interface ContactChannel {
-  type: string;
-  address: string;
-  isPrimary: boolean;
-}
-
-interface ContactResponse {
-  id: string;
-  displayName: string;
-  notes: string | null;
-  interactionCount: number;
-  channels: ContactChannel[];
-}
-
 export async function executeContactMerge(
   input: Record<string, unknown>,
   _context: ToolContext,
@@ -36,79 +20,74 @@ export async function executeContactMerge(
     return { content: "Error: merge_id is required", isError: true };
   }
 
-  try {
-    // Validate both contacts exist before merging
-    const [keepResult, mergeResult] = await Promise.allSettled([
-      gatewayGet<{ ok: boolean; contact: ContactResponse }>(
-        `/v1/contacts/${keepId}`,
-      ),
-      gatewayGet<{ ok: boolean; contact: ContactResponse }>(
-        `/v1/contacts/${mergeId}`,
-      ),
-    ]);
-
-    if (keepResult.status === "rejected") {
-      if (
-        keepResult.reason instanceof GatewayRequestError &&
-        keepResult.reason.statusCode === 404
-      ) {
-        return {
-          content: `Error: Contact "${keepId}" not found`,
-          isError: true,
-        };
-      }
-      throw keepResult.reason;
-    }
-    if (mergeResult.status === "rejected") {
-      if (
-        mergeResult.reason instanceof GatewayRequestError &&
-        mergeResult.reason.statusCode === 404
-      ) {
-        return {
-          content: `Error: Contact "${mergeId}" not found`,
-          isError: true,
-        };
-      }
-      throw mergeResult.reason;
-    }
+  // Validate both contacts exist before merging
+  const [keepRes, mergeRes] = await Promise.all([
+    cliIpcCall<{ contact: ContactWithChannels }>("getContact", {
+      pathParams: { id: keepId },
+    }),
+    cliIpcCall<{ contact: ContactWithChannels }>("getContact", {
+      pathParams: { id: mergeId },
+    }),
+  ]);
 
-    const keepContact = keepResult.value.contact;
-    const mergeContact = mergeResult.value.contact;
+  if (!keepRes.ok) {
+    return { content: `Error: ${keepRes.error}`, isError: true };
+  }
+  if (!mergeRes.ok) {
+    return { content: `Error: ${mergeRes.error}`, isError: true };
+  }
 
-    // Execute the merge
-    const { data: resultData } = await gatewayPost<{
-      ok: boolean;
-      contact: ContactResponse;
-    }>("/v1/contacts/merge", { keepId, mergeId });
-    const merged = resultData.contact;
+  const keepContact = keepRes.result!.contact;
+  const mergeContact = mergeRes.result!.contact;
 
-    const channelList = merged.channels
-      .map(
-        (ch) =>
-          `  - ${ch.type}: ${ch.address}${ch.isPrimary ? " (primary)" : ""}`,
-      )
-      .join("\n");
+  const mergeResult = await cliIpcCall<{
+    ok: boolean;
+    contact: ContactWithChannels;
+  }>("merge_contacts", {
+    body: { keepId, mergeId },
+  });
 
-    return {
-      content: [
-        `Merged "${mergeContact.displayName}" into "${keepContact.displayName}".`,
-        ``,
-        `Surviving contact (${merged.id}):`,
-        `  Name: ${merged.displayName}`,
-        `  Interactions: ${merged.interactionCount}`,
-        merged.notes ? `  Notes: ${merged.notes}` : null,
-        merged.channels.length > 0 ? `  Channels:\n${channelList}` : null,
-        ``,
-        `Deleted contact: ${mergeContact.displayName} (${mergeId})`,
-      ]
-        .filter(Boolean)
-        .join("\n"),
-      isError: false,
-    };
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    return { content: `Error: ${msg}`, isError: true };
+  if (!mergeResult.ok) {
+    return { content: `Error: ${mergeResult.error}`, isError: true };
   }
+
+  const merged = mergeResult.result!.contact;
+  const displayName =
+    merged.role === "guardian"
+      ? resolveGuardianName(merged.displayName)
+      : merged.displayName;
+  const keepName =
+    keepContact.role === "guardian"
+      ? resolveGuardianName(keepContact.displayName)
+      : keepContact.displayName;
+  const mergeName =
+    mergeContact.role === "guardian"
+      ? resolveGuardianName(mergeContact.displayName)
+      : mergeContact.displayName;
+
+  const channelList = merged.channels
+    .map(
+      (ch) =>
+        `  - ${ch.type}: ${ch.address}${ch.isPrimary ? " (primary)" : ""}`,
+    )
+    .join("\n");
+
+  return {
+    content: [
+      `Merged "${mergeName}" into "${keepName}".`,
+      ``,
+      `Surviving contact (${merged.id}):`,
+      `  Name: ${displayName}`,
+      `  Interactions: ${merged.interactionCount}`,
+      merged.notes ? `  Notes: ${merged.notes}` : null,
+      merged.channels.length > 0 ? `  Channels:\n${channelList}` : null,
+      ``,
+      `Deleted contact: ${mergeName} (${mergeId})`,
+    ]
+      .filter(Boolean)
+      .join("\n"),
+    isError: false,
+  };
 }
 
 export { executeContactMerge as run };