@vellumai/assistant 0.8.0 → 0.8.2

package/src/calls/types.ts

@@ -33,6 +33,7 @@ export type CallEventType =
   | "inbound_acl_name_capture_started"
   | "inbound_acl_name_captured"
   | "inbound_acl_name_capture_timeout"
+  | "inbound_acl_unverified_caller"
   | "inbound_acl_access_approved"
   | "inbound_acl_access_denied"
   | "inbound_acl_access_timeout"

package/src/calls/voice-session-bridge.ts

@@ -293,7 +293,11 @@ export async function startVoiceTurn(
     onMessageComplete: (msg) => {
       opts.onComplete?.();
       opts.callbacks?.message_complete?.(msg);
-      if (msg.type === "message_complete" && msg.messageId) {
+      if (
+        msg.type === "message_complete" &&
+        msg.messageId &&
+        msg.source !== "aux"
+      ) {
         try {
           opts.callbacks?.persisted_assistant_message_id?.(msg.messageId);
         } catch (err) {
@@ -314,7 +318,9 @@ export async function startVoiceTurn(
 
   // Phone voice has no interactive permission/secret UI, so apply explicit
   // per-role policies by default. Local live voice opts into the normal
-  // client approval path instead.
+  // client approval path instead. Side-effect double-defense
+  // (forcePromptSideEffects) is wired inside the agent-loop IIFE so it
+  // is always paired with cleanup() in the IIFE's finally.
   const trustClass = opts.trustContext?.trustClass;
   const isGuardian = trustClass === "guardian";
   const approvalMode = opts.approvalMode ?? "phone-call";
@@ -386,28 +392,57 @@ export async function startVoiceTurn(
     }
   }
 
-  // Configure conversation for this voice turn
-  conversation.setAssistantId(opts.assistantId ?? DAEMON_INTERNAL_ASSISTANT_ID);
-  conversation.callSessionId = voiceSessionId;
-  conversation.setTrustContext(opts.trustContext ?? null);
-  conversation.setCommandIntent(null);
-  conversation.setTurnChannelContext(turnChannelContext);
-  conversation.setTurnInterfaceContext?.(turnInterfaceContext);
-  conversation.setChannelCapabilities(
-    resolveChannelCapabilities(
-      turnChannelContext.userMessageChannel,
-      turnInterfaceContext.userMessageInterface,
-    ),
-  );
-  conversation.setVoiceCallControlPrompt(voiceCallControlPrompt);
+  // Hoisted so the catch below can clear partially-applied turn state
+  // when a setter or `persistUserMessage` throws — otherwise `trustContext`,
+  // `callSessionId`, etc. leak into subsequent non-voice turns on the same
+  // conversation. The client callback is only reset when this turn actually
+  // installed it (tracked via `clientCallbackInstalled`); otherwise cleanup
+  // would detach an active sender installed by a prior turn.
+  let clientCallbackInstalled = false;
+  const cleanup = () => {
+    conversation.setChannelCapabilities(null);
+    conversation.setTrustContext(null);
+    conversation.setCommandIntent(null);
+    conversation.setAssistantId("self");
+    conversation.setVoiceCallControlPrompt(null);
+    conversation.callSessionId = undefined;
+    conversation.forcePromptSideEffects = false;
+    if (clientCallbackInstalled) {
+      // Reset the client callback to a no-op so the stale closure doesn't
+      // intercept events from future turns on the same conversation.
+      conversation.updateClient(() => {}, true);
+    }
+  };
 
   const requestId = crypto.randomUUID();
   const turnId = crypto.randomUUID();
-  const messageId = await conversation.persistUserMessage(
-    persistedContent,
-    [],
-    requestId,
-  );
+  let messageId: string;
+  try {
+    conversation.setAssistantId(
+      opts.assistantId ?? DAEMON_INTERNAL_ASSISTANT_ID,
+    );
+    conversation.callSessionId = voiceSessionId;
+    conversation.setTrustContext(opts.trustContext ?? null);
+    conversation.setCommandIntent(null);
+    conversation.setTurnChannelContext(turnChannelContext);
+    conversation.setTurnInterfaceContext?.(turnInterfaceContext);
+    conversation.setChannelCapabilities(
+      resolveChannelCapabilities(
+        turnChannelContext.userMessageChannel,
+        turnInterfaceContext.userMessageInterface,
+      ),
+    );
+    conversation.setVoiceCallControlPrompt(voiceCallControlPrompt);
+
+    messageId = await conversation.persistUserMessage(
+      persistedContent,
+      [],
+      requestId,
+    );
+  } catch (err) {
+    cleanup();
+    throw err;
+  }
   try {
     opts.callbacks?.persisted_user_message_id?.(messageId);
   } catch (err) {
@@ -528,7 +563,14 @@ export async function startVoiceTurn(
         return;
       }
     } else if (msg.type === "secret_request") {
-      // Voice has no secret-entry UI, so resolve immediately
+      if (usesLocalInteractiveApprovals) {
+        // Local live voice runs alongside the desktop client, which has a
+        // secret-entry UI (SecretPromptManager). Forward the broadcast and
+        // let the prompter's existing registration handle the response.
+        broadcastMessage(msg);
+        return;
+      }
+      // Phone voice has no secret-entry UI, so resolve immediately.
       log.info(
         { turnId, service: msg.service, field: msg.field },
         "Auto-resolving secret request for voice turn (no secret-entry UI)",
@@ -538,24 +580,20 @@ export async function startVoiceTurn(
     }
     broadcastMessage(msg);
   });
+  clientCallbackInstalled = true;
 
   // Fire-and-forget the agent loop
-  const cleanup = () => {
-    // Reset channel capabilities so a subsequent desktop session on the
-    // same conversation is not incorrectly treated as a voice client.
-    conversation.setChannelCapabilities(null);
-    conversation.setTrustContext(null);
-    conversation.setCommandIntent(null);
-    conversation.setAssistantId("self");
-    conversation.setVoiceCallControlPrompt(null);
-    conversation.callSessionId = undefined;
-    // Reset the conversation's client callback to a no-op so the stale
-    // closure doesn't intercept events from future turns on the same conversation.
-    conversation.updateClient(() => {}, true);
-  };
-
   void (async () => {
     try {
+      // Non-guardian phone voice forces side-effect tools to prompt so the
+      // auto-deny handler above reliably sees a confirmation_request. Without
+      // this, a broad allow trust rule (e.g. wildcard bash) would let
+      // side-effect tools execute without ever emitting an event for the
+      // auto-deny / scoped-grant handler to intercept. Set inside the
+      // try/finally so a failed setup before this point cannot leak the
+      // flag into subsequent non-voice turns on the same conversation.
+      conversation.forcePromptSideEffects =
+        !isGuardian && !usesLocalInteractiveApprovals;
       await conversation.runAgentLoop(
         persistedContent,
         messageId,

package/src/channels/config.ts

@@ -11,7 +11,8 @@ import type { ChannelId } from "./types.js";
 export type ConversationStrategy =
   | "start_new_conversation"
   | "continue_existing_conversation"
-  | "not_deliverable";
+  | "not_deliverable"
+  | "push_only";
 
 export interface ChannelInvitePolicy {
   /** Whether inbound invite code redemption is supported on this channel. */
@@ -72,6 +73,18 @@ const CHANNEL_POLICIES = {
       codeRedemptionEnabled: true,
     },
   },
+  platform: {
+    notification: {
+      deliveryEnabled: true,
+      // Platform is a push-only relay — conversations are owned by the vellum
+      // channel. push_only skips pairDeliveryWithConversation without implying
+      // the channel is non-deliverable (which not_deliverable would).
+      conversationStrategy: "push_only",
+    },
+    invite: {
+      codeRedemptionEnabled: false,
+    },
+  },
   phone: {
     notification: {
       deliveryEnabled: false,

package/src/channels/types.ts

@@ -5,6 +5,7 @@ export const CHANNEL_IDS = [
   "whatsapp",
   "slack",
   "email",
+  "platform",
 ] as const;
 
 export type ChannelId = (typeof CHANNEL_IDS)[number];
@@ -26,6 +27,114 @@ export interface TurnChannelContext {
   assistantMessageChannel: ChannelId;
 }
 
+/**
+ * Display metadata for a channel, returned alongside the channel id from
+ * `/v1/channels/available`. Owning this in the gateway (rather than letting
+ * each client carry its own icon/label/copy switch) keeps the Contacts /
+ * Channels UI consistent across macOS, web, and any future surface, and
+ * lets us add or rename a channel without shipping new client builds.
+ */
+export interface ChannelInfo {
+  id: ChannelId;
+  /** Title shown on the channel card, e.g. "Slack". */
+  label: string;
+  /** One-line description shown under the title. */
+  subtitle: string;
+  /**
+   * Lucide icon name without the `lucide-` prefix, e.g. `"mail"` or
+   * `"hash"`. macOS clients resolve to `VIcon(rawValue: "lucide-\(icon)")`;
+   * web clients import the matching component from `lucide-react`.
+   */
+  icon: string;
+  /**
+   * Whether this channel has a client-side verification flow (the
+   * `ChannelVerificationFlowView` on macOS, equivalent on web). When
+   * `false`, clients skip pre-warming verification status and render the
+   * card in display-only mode.
+   */
+  supportsVerification: boolean;
+  /** Suggested first-turn user messages that open the conversation that drives setup. */
+  setupMessages: {
+    guardian: string;
+    contact: string;
+  };
+}
+
+/**
+ * Per-channel display metadata for the channels the gateway can currently
+ * surface to clients. Add an entry here when surfacing a new channel via
+ * `/v1/channels/available`. `Partial` because unsurfaced channels (e.g.
+ * `vellum`, `platform`) deliberately have no metadata — keep this map
+ * minimal until there's a real surface to feed.
+ */
+export const CHANNEL_METADATA: Partial<Record<ChannelId, ChannelInfo>> = {
+  slack: {
+    id: "slack",
+    label: "Slack",
+    subtitle: "Message your assistant from Slack",
+    icon: "hash",
+    supportsVerification: true,
+    setupMessages: {
+      guardian:
+        "I'd like to verify my identity as your guardian on Slack. Can you help me set that up?",
+      contact:
+        "I'd like to verify a contact's Slack identity. Can you walk me through it?",
+    },
+  },
+  telegram: {
+    id: "telegram",
+    label: "Telegram",
+    subtitle: "Message your assistant from Telegram",
+    icon: "send",
+    supportsVerification: true,
+    setupMessages: {
+      guardian:
+        "I'd like to verify my identity as your guardian on Telegram. Can you help me set that up?",
+      contact:
+        "I'd like to verify a contact's Telegram identity. Can you walk me through it?",
+    },
+  },
+  phone: {
+    id: "phone",
+    label: "Phone Calling",
+    subtitle: "Call or text your assistant via phone",
+    icon: "phone",
+    supportsVerification: true,
+    setupMessages: {
+      guardian:
+        "I'd like to verify my identity as your guardian for phone calls. Can you help me set that up?",
+      contact:
+        "I'd like to verify a contact's phone number. Can you help me set that up?",
+    },
+  },
+  email: {
+    id: "email",
+    label: "Email",
+    subtitle: "Reach your assistant by email",
+    icon: "mail",
+    supportsVerification: false,
+    setupMessages: {
+      guardian:
+        "I'd like to set up email as a way for me to reach you. Can you walk me through it?",
+      contact:
+        "I'd like to set up email as a way to reach this contact. Can you walk me through it?",
+    },
+  },
+  whatsapp: {
+    id: "whatsapp",
+    label: "WhatsApp",
+    subtitle: "Message your assistant on WhatsApp",
+    icon: "message-square",
+    supportsVerification: false,
+    setupMessages: {
+      guardian:
+        "I'd like to verify my identity as your guardian on WhatsApp. Can you help me set that up?",
+      contact:
+        "I'd like to verify a contact's WhatsApp identity. Can you walk me through it?",
+    },
+  },
+};
+
 export const INTERFACE_IDS = [
   "macos",
   "ios",

package/src/cli/AGENTS.md

@@ -22,13 +22,173 @@ Examples: `config`, `contacts`, `memory`, `autonomy`, `conversations` belong her
 - Use `getCliLogger("cli")` for output (not raw `console.log`).
 - When adding/removing/renaming assistant CLI commands or subcommands, update the gateway bash risk registry coverage in `gateway/src/risk/command-registry/commands/assistant.ts` (supported command paths + risk overrides) so permission prompts stay correct.
 
-## Service calls — no gateway proxying
+## Service calls — transport-based dispatch
 
-CLI commands must call the service/store layer directly — the same functions that the HTTP route handlers in `runtime/routes/` call. Do not proxy through the gateway HTTP API.
+CLI commands use one of two transport patterns depending on whether they need a running daemon:
 
-Both the gateway routes and the CLI are thin wrappers around the same shared business logic. For example, `runtime/routes/invite-routes.ts` delegates to `runtime/invite-service.ts`, and `runtime/routes/contact-routes.ts` delegates to `contacts/contact-store.ts`. CLI commands should import and call those same service modules directly.
+- **`ipc`-tagged commands** call `cliIpcCall` from `../../ipc/cli-client.js`. They are thin wrappers that forward requests to the daemon over the IPC socket and never import daemon-internal modules.
+- **`local`-tagged commands** read or write workspace files directly (config, autonomy, completions, etc.) using the same config/store helpers the daemon uses internally. They do not require the daemon to be running.
 
-This avoids a dependency on the gateway process being running and removes an unnecessary network hop.
+Both transport classes avoid proxying through the gateway HTTP API. `ipc` commands reach the daemon directly via the socket; `local` commands bypass the daemon entirely. The transport tag is declared via `registerCommand({ transport, ... })` — see the "Transport tagging" section below.
+
+## Transport tagging
+
+Every command file declares its transport class via `registerCommand({ transport, ... })`
+from `../lib/register-command.ts`. The three transport classes are:
+
+| Class | Rule | When to use |
+|---|---|---|
+| `ipc` | Wraps exactly one IPC method per subcommand. No daemon-internal imports. | Commands that call the daemon |
+| `local` | Touches only static workspace files / shell artifacts. | Commands that work without a running daemon |
+| `bootstrap` | Runs before the daemon is up (e.g. `assistant config init`). | Pre-daemon setup |
+
+The ESLint rule `cli/no-daemon-internals` enforces import allowlists per class.
+
+## Anatomy of an `ipc` command
+
+The thin-wrapper pattern. Every `ipc`-tagged subcommand action does three
+things: parse argv → call one IPC method → format output. The business
+logic lives in the daemon route, not the CLI.
+
+### Required shape
+
+```ts
+// assistant/src/cli/commands/foo.ts
+import type { Command } from "commander";
+
+import { cliIpcCall, exitFromIpcResult } from "../../ipc/cli-client.js";
+import { registerCommand } from "../lib/register-command.js";
+import { writeOutput } from "../output.js";
+
+interface FooBarResponse {
+  bars: { id: string; name: string }[];
+}
+
+export function registerFooCommand(program: Command): void {
+  registerCommand(program, {
+    name: "foo",
+    transport: "ipc",
+    description: "Manage foos",
+    build: (foo) => {
+      foo
+        .command("bar")
+        .description("List bars")
+        .option("--baz <n>", "Filter by baz")
+        .action(async (opts, cmd) => {
+          const r = await cliIpcCall<FooBarResponse>("foo_bar", {
+            baz: opts.baz,
+          });
+          if (!r.ok) return exitFromIpcResult(r);
+          writeOutput(cmd, r.result);
+        });
+    },
+  });
+}
+```
+
+Then wire it from `program.ts` inside `buildCliProgram()`:
+
+```ts
+import { registerFooCommand } from "./commands/foo.js";
+// ...
+registerFooCommand(program);
+```
+
+### Rules
+
+1. **One `registerCommand` call per file.** The options object MUST be
+   passed inline as an object literal; `name` and `transport` MUST be
+   string literals. Hoisted variables and `as const` casts break the
+   static analysis tools rely on.
+
+2. **No daemon-internal imports.** An `ipc` command file can import:
+
+   - the IPC client (`../../ipc/cli-client`)
+   - the Commander framework + Node stdlib (`commander`, `node:*`)
+   - shared CLI helpers (`../logger`, `../output`, `../lib/*`,
+     `../../utils/*`)
+   - sibling subcommand modules (`./connect`, etc. — for namespace
+     parents like `oauth/index.ts`)
+
+   It **cannot** import anything under `runtime/`, `services/`,
+   `agents/`, `llm/`, `skills/`, or any other daemon-internal namespace.
+   The `cli/no-daemon-internals` ESLint rule enforces this at `"error"`
+   severity. See `assistant/eslint-rules/cli-no-daemon-internals.js` for
+   the per-transport allowlist (including per-command escape hatches for
+   things like the `keys` security helpers and `credential-execution`
+   bridge).
+
+3. **One IPC call per subcommand action.** A thin wrapper does not
+   compose multiple IPC methods, does not validate beyond Commander's
+   argument parsing, and does not reshape the daemon response.
+   Composition belongs on the daemon side, in a route.
+
+4. **Always check `r.ok` before reading `r.result`.** `cliIpcCall`
+   returns `CliIpcCallResult<T>` — either `{ ok: true, result }` or
+   `{ ok: false, error, statusCode?, errorCode?, errorDetails? }`. Use
+   `exitFromIpcResult(r)` to surface failure: it writes the error to
+   stderr and exits with a code derived from the daemon-side
+   `statusCode` (10 connect failure, 3 5xx, 2 4xx, 1 other).
+
+5. **Output via `writeOutput(cmd, payload)`.** The shared helper writes
+   JSON to stdout — compact with `--json`, pretty otherwise — and
+   respects `--json` inherited from parent commands. Don't
+   `console.log` results directly; that bypasses the convention and
+   breaks downstream scripting.
+
+### Anti-patterns
+
+- ❌ `import { something } from "../../runtime/foo.js"` from an
+  `ipc`-tagged command. The ESLint rule rejects this at `"error"`.
+- ❌ `registerCommand(program, opts)` where `opts` is a hoisted
+  variable. Inline the literal so the transport tag is statically
+  visible.
+- ❌ Multiple `registerCommand` calls in one file.
+- ❌ Reshaping `r.result` to differ from what the route returns. If the
+  CLI shape needs to diverge from the daemon response, change the
+  route — the CLI is just a transport.
+- ❌ Bypassing `exitFromIpcResult` to format your own error output.
+  The shared helper gives consistent exit codes across the surface so
+  scripts can branch on them.
+- ❌ Calling the gateway HTTP API (`fetch`, `axios`) from a CLI
+  command. All daemon work goes through IPC; the gateway is for
+  external clients.
+
+## IPC operation IDs and routes
+
+Every `ipc`-tagged subcommand action maps to exactly one operation
+served by the daemon's IPC server. Two route surfaces exist:
+
+- **Shared routes (`assistant/src/runtime/routes/`).** Served over both
+  HTTP and IPC via the shared `ROUTES` array. Most domain routes live
+  here — dual exposure is by design so the gateway can call the daemon
+  over IPC instead of HTTP. See `assistant/AGENTS.md` for the routes /
+  dispatch architecture.
+- **IPC-only routes (`assistant/src/ipc/routes/`).** CLI/tool-specific
+  methods with no HTTP counterpart (e.g. `wake_conversation`,
+  `upsert_contact`). Use this surface only when the operation
+  shouldn't be exposed over HTTP — when in doubt, default to the
+  shared surface.
+
+Operation IDs are snake_case. The conventional shape is
+`<command>_<subcommand>` (`pending_list`, `oauth_connect`,
+`cache_get`), but verb-first names are also used where they read more
+naturally (`upsert_contact`, `wake_conversation`, `conversations_import`).
+Pick the form that makes the operation obvious from the ID alone.
+
+The route owns the request schema (zod), the business logic, and the
+response shape. The CLI just forwards arguments and renders the
+response. When you add a new CLI verb you're almost always also adding
+(or extending) a route — see the PR template's CLI verb checklist.
+
+## Canonical example
+
+`commands/pending.ts` is the reference implementation. Read it first
+when migrating a legacy command or unsure about a pattern.
+- Clean error handling via `exitFromIpcResult`
+- No daemon-internal imports
+
+When migrating a legacy command, start by reading `pending.ts`.
 
 ## Help Text Standards
 

package/src/cli/__tests__/notifications.test.ts

@@ -214,6 +214,60 @@ describe("notifications send", () => {
     expect(ipcCalls).toHaveLength(0);
   });
 
+  test("send --conversation-id pins the vellum affinity hint", async () => {
+    const { parsed, exitCode } = await runCommand([
+      "send",
+      "--source-channel",
+      "assistant_tool",
+      "--source-event-name",
+      "user.send_notification",
+      "--message",
+      "Hi",
+      "--conversation-id",
+      "conv-123",
+    ]);
+
+    expect(exitCode).toBe(0);
+    expect(parsed.ok).toBe(true);
+
+    const callBody = ipcCalls[0].params?.body as Record<string, unknown>;
+    expect(callBody.conversationAffinityHint).toEqual({ vellum: "conv-123" });
+  });
+
+  test("send omits conversationAffinityHint when --conversation-id not passed", async () => {
+    await runCommand([
+      "send",
+      "--source-channel",
+      "assistant_tool",
+      "--source-event-name",
+      "user.send_notification",
+      "--message",
+      "Hi",
+    ]);
+
+    const callBody = ipcCalls[0].params?.body as Record<string, unknown>;
+    expect(callBody.conversationAffinityHint).toBeUndefined();
+  });
+
+  test("send rejects empty --conversation-id", async () => {
+    const { parsed, exitCode } = await runCommand([
+      "send",
+      "--source-channel",
+      "assistant_tool",
+      "--source-event-name",
+      "user.send_notification",
+      "--message",
+      "Hi",
+      "--conversation-id",
+      "   ",
+    ]);
+
+    expect(exitCode).toBe(1);
+    expect(parsed.ok).toBe(false);
+    expect(parsed.error).toBe("Conversation ID must be a non-empty string");
+    expect(ipcCalls).toHaveLength(0);
+  });
+
   test("send surfaces IPC error response", async () => {
     ipcResponse = {
       ok: false,

package/src/cli/__tests__/unknown-command.test.ts

@@ -1,5 +1,7 @@
 import { describe, expect, it } from "bun:test";
 
+import { detectUnknownCommand } from "../lib/unknown-command.js";
+import { buildCliProgram } from "../program.js";
 import { runAssistantCommandFull } from "./run-assistant-command.js";
 
 describe("unknown command handling", () => {
@@ -30,4 +32,26 @@ describe("unknown command handling", () => {
     expect(stderr).toContain("unknown command 'xyzzy'");
     expect(stderr).not.toContain("Did you mean");
   });
+
+  // The `--help` flag triggers Commander's help short-circuit before any
+  // action or hook runs, so the in-action detection in default-action.ts
+  // can't catch it. The entrypoint pre-scans argv via detectUnknownCommand
+  // to surface the error before Commander handles --help. This test guards
+  // that path against regression.
+  it("detects an unknown subcommand even when --help is passed", async () => {
+    const program = await buildCliProgram();
+    expect(detectUnknownCommand(program, ["invalid", "--help"])).toEqual({
+      token: "invalid",
+    });
+    expect(detectUnknownCommand(program, ["confg", "--help"])).toEqual({
+      token: "confg",
+      suggestion: "config",
+    });
+  });
+
+  it("does not flag known commands when --help is passed", async () => {
+    const program = await buildCliProgram();
+    expect(detectUnknownCommand(program, ["status", "--help"])).toBeNull();
+    expect(detectUnknownCommand(program, ["config", "list", "--help"])).toBeNull();
+  });
 });