@vellumai/assistant 0.11.2 → 0.11.3-dev.202608080427.92f668a

package/src/channels/__tests__/plugin-channel-declarations.test.ts

@@ -0,0 +1,161 @@
+/**
+ * Channels that installed plugins bring.
+ *
+ * `getWorkspacePluginsDir` is mocked to a scratch directory so these read real
+ * files off disk without touching the machine's workspace.
+ */
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeEach, describe, expect, mock, test } from "bun:test";
+
+const workspacePluginsDir = mkdtempSync(join(tmpdir(), "plugin-channels-"));
+
+const realPlatform = await import("../../util/platform.js");
+
+mock.module("../../util/platform.js", () => ({
+  ...realPlatform,
+  getWorkspacePluginsDir: () => workspacePluginsDir,
+}));
+
+const { discoverPluginChannels } = await import(
+  "../plugin-channel-declarations.js"
+);
+
+interface PluginOptions {
+  /** Contents of `channels/ingress.json`; omit for a plugin with no ingress. */
+  ingress?: string;
+  manifest?: Record<string, unknown>;
+}
+
+const INGRESS = JSON.stringify({
+  routes: [{ path: "events", kind: "http", description: "inbound" }],
+});
+
+function writePlugin(name: string, options: PluginOptions = {}): string {
+  const dir = join(workspacePluginsDir, name);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(
+    join(dir, "package.json"),
+    JSON.stringify({ name, ...options.manifest }),
+  );
+  if (options.ingress !== undefined) {
+    mkdirSync(join(dir, "channels"), { recursive: true });
+    writeFileSync(join(dir, "channels", "ingress.json"), options.ingress);
+  }
+  return dir;
+}
+
+beforeEach(() => {
+  rmSync(workspacePluginsDir, { recursive: true, force: true });
+  mkdirSync(workspacePluginsDir, { recursive: true });
+});
+
+afterAll(() => {
+  rmSync(workspacePluginsDir, { recursive: true, force: true });
+});
+
+describe("discoverPluginChannels", () => {
+  test("a plugin is a channel because it declares ingress", async () => {
+    writePlugin("courier", {
+      ingress: INGRESS,
+      manifest: {
+        displayName: "Courier",
+        description: "Reach the assistant by carrier pigeon.",
+        icon: "send",
+      },
+    });
+
+    expect(await discoverPluginChannels()).toEqual([
+      {
+        id: "courier",
+        source: "plugin:courier",
+        label: "Courier",
+        subtitle: "Reach the assistant by carrier pigeon.",
+        icon: "send",
+        supportsVerification: false,
+        setupMessages: {
+          guardian: "I want to set up Courier. Can you help me?",
+          contact:
+            "I'd like to reach you on Courier. Can you help me get set up?",
+        },
+      },
+    ]);
+  });
+
+  test("ignores a plugin that declares no ingress", async () => {
+    // Presentation alone does not make a channel: reaching the assistant from
+    // outside is what one is, and ingress is where that is declared.
+    writePlugin("notes", { manifest: { displayName: "Notes", icon: "send" } });
+
+    expect(await discoverPluginChannels()).toEqual([]);
+  });
+
+  test("surfaces a channel whose ingress the gateway would reject", async () => {
+    // Validation belongs to the gateway, which owns the schema. A plugin with
+    // a broken declaration is a channel with broken ingress, and saying so
+    // beats dropping it off the page a guardian would look at.
+    writePlugin("courier", {
+      ingress: "{ not json",
+      manifest: { displayName: "Courier" },
+    });
+
+    expect((await discoverPluginChannels())[0]?.label).toBe("Courier");
+  });
+
+  test("skips a disabled plugin", async () => {
+    // Same source of truth the loader uses for hooks, tools and routes: a
+    // disabled plugin would otherwise offer a setup flow that cannot run.
+    const dir = writePlugin("courier", { ingress: INGRESS });
+    writeFileSync(join(dir, ".disabled"), "");
+
+    expect(await discoverPluginChannels()).toEqual([]);
+  });
+
+  test("refuses to let a plugin take a built-in channel's id", async () => {
+    // Two rows sharing an id would be ambiguous to any client keying on one,
+    // and letting the plugin win would let it impersonate a built-in.
+    writePlugin("slack", {
+      ingress: INGRESS,
+      manifest: { displayName: "Slack" },
+    });
+
+    expect(await discoverPluginChannels()).toEqual([]);
+  });
+
+  test("titles a plugin that names no display name", async () => {
+    // Presentation is best-effort, so a bare manifest costs a nicer title and
+    // never the row itself.
+    writePlugin("meeting-bot", { ingress: INGRESS });
+
+    expect(await discoverPluginChannels()).toMatchObject([
+      {
+        id: "meeting-bot",
+        source: "plugin:meeting-bot",
+        label: "Meeting Bot",
+        subtitle: "Provided by the Meeting Bot plugin",
+        icon: "message-square",
+      },
+    ]);
+  });
+
+  test("still lists a channel whose manifest cannot be read", async () => {
+    // The directory is the plugin's identity, so an unparseable manifest
+    // costs its presentation and not its existence.
+    const dir = writePlugin("courier", { ingress: INGRESS });
+    writeFileSync(join(dir, "package.json"), "{ not json");
+
+    expect((await discoverPluginChannels())[0]?.label).toBe("Courier");
+  });
+
+  test("never claims a plugin channel supports verification", async () => {
+    // There is no client-side verification flow for one, so clients render it
+    // display-only rather than pre-warming a status that cannot arrive.
+    writePlugin("courier", { ingress: INGRESS });
+
+    expect((await discoverPluginChannels())[0]?.supportsVerification).toBe(
+      false,
+    );
+  });
+});

package/src/channels/config.ts

@@ -75,8 +75,26 @@ const CHANNEL_POLICIES = {
   },
   discord: {
     notification: {
-      // Discord has no outbound transport, so enabling delivery would route
-      // notifications at a callback no transport owns.
+      // Replies to an inbound Discord message do not read this flag: they
+      // route by `replyCallbackUrl` through the channel transport. This gates
+      // proactive notification only, which needs a guardian binding to
+      // address and a destination resolver to reach it. Discord has neither,
+      // and `NotificationChannel` is derived from this flag, so enabling it
+      // early would let the decision engine pick a channel that resolves to
+      // nothing.
+      deliveryEnabled: false,
+      conversationStrategy: "continue_existing_conversation",
+    },
+  },
+  plugin: {
+    notification: {
+      // Every plugin-brought channel shares this row, so the answer has to
+      // hold for all of them. A reply to an inbound plugin message routes by
+      // `replyCallbackUrl` and does not read this flag; proactive notification
+      // does, and it needs a guardian binding plus a destination resolver to
+      // reach. Neither exists per-plugin, and `NotificationChannel` is derived
+      // from this flag, so enabling it would let the decision engine pick a
+      // channel that resolves to nothing for whichever plugin it landed on.
       deliveryEnabled: false,
       conversationStrategy: "continue_existing_conversation",
     },

package/src/channels/gateway-verification-sessions.ts

@@ -122,7 +122,8 @@ export async function createOutboundSession(
 
 /**
  * Guarded variant of `createOutboundSession` for callers passing an atomic
- * claim guard (`requireSourceSessionPending` / `ifNoneActive`). The gateway
+ * claim guard (`requireSourceSessionPending` /
+ * `ifNoneActiveForExternalUserId`). The gateway
  * evaluates the guard in the same synchronous section as the mint; a failed
  * guard returns a conflict marker instead of revoking the concurrent
  * winner's session. Throws when the gateway is unreachable (fail-closed).
@@ -160,10 +161,14 @@ export async function getPendingSession(
  */
 export async function findActiveSession(
   channel: string,
+  filter: {
+    expectedExternalUserId?: string;
+    verificationPurpose?: "guardian" | "trusted_contact";
+  } = {},
 ): Promise<VerificationSessionWire | null> {
   return callGateway(
     VERIFICATION_SESSIONS_IPC_METHODS.findActive,
-    { channel },
+    { channel, ...filter },
     SessionLookupIpcResponseSchema,
   );
 }

package/src/channels/plugin-channel-declarations.ts

@@ -0,0 +1,108 @@
+/**
+ * Channels that installed plugins bring.
+ *
+ * A plugin is a channel because it declares ingress: `channels/ingress.json`
+ * is the list of routes the outside world may reach it on, and reaching the
+ * assistant from outside is what being a channel means. There is no second
+ * file saying so, and nothing a plugin can set to claim the status without
+ * declaring the reach that constitutes it.
+ *
+ * What the gateway does with that file is a separate matter, and stays the
+ * gateway's: validating the routes, digesting them, holding them behind a
+ * guardian's approval. This reads its presence and nothing else, so a
+ * declaration the gateway rejects still surfaces here. That is the honest
+ * report, the plugin is a channel and its ingress is broken, and it keeps a
+ * schema this module does not own from deciding what a settings page lists.
+ *
+ * Presentation comes from the plugin's own manifest, where a plugin's title,
+ * description and icon already belong. All three are optional and none gate
+ * anything: a plugin with ingress and a bare `package.json` still appears,
+ * titled from its directory.
+ */
+
+import { statSync } from "node:fs";
+import { join } from "node:path";
+
+import { isPluginDisabled } from "../plugins/disabled-state.js";
+import { parsePluginPresentation } from "../plugins/external-plugin-loader.js";
+import { listInstalledPluginDirs } from "../plugins/installed-plugin-dirs.js";
+import { type AvailableChannel, isChannelId } from "./types.js";
+
+/**
+ * The declaration that makes a plugin a channel. Owned by the gateway, which
+ * parses it; named here only to test for it.
+ */
+export const PLUGIN_INGRESS_MANIFEST_RELPATH = "channels/ingress.json";
+
+/** Icon for a plugin naming none. The generic "a message arrives here" glyph. */
+const FALLBACK_ICON = "message-square";
+
+/**
+ * Title for a plugin with no `displayName`.
+ *
+ * Derived rather than defaulted to the raw directory name so `meeting-bot`
+ * reads as "Meeting Bot" beside "Slack" and "Telegram". A plugin whose casing
+ * matters sets `displayName` and this never runs.
+ */
+function titleFromDirectory(name: string): string {
+  return name
+    .split(/[-_]/)
+    .filter((part) => part.length > 0)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(" ");
+}
+
+/** True when the plugin declares ingress routes. */
+function declaresIngress(pluginDir: string): boolean {
+  return (
+    statSync(join(pluginDir, PLUGIN_INGRESS_MANIFEST_RELPATH), {
+      throwIfNoEntry: false,
+    })?.isFile() === true
+  );
+}
+
+/**
+ * Every channel brought by an installed, enabled plugin.
+ *
+ * A plugin whose directory name is one of the assistant's own channels is
+ * skipped: two rows sharing an id would be ambiguous to any client keying on
+ * one, and the resolution that lets a plugin win would let it impersonate a
+ * built-in channel. The assistant's keep the name.
+ *
+ * Disabled plugins are skipped too, matching the source of truth the loader
+ * uses for hooks, tools and routes: a disabled plugin holds no ingress either,
+ * and one that reappeared here would offer a setup flow that cannot run.
+ *
+ * Order follows the plugins directory, and is stable for a stable install set.
+ */
+export async function discoverPluginChannels(): Promise<AvailableChannel[]> {
+  const channels: AvailableChannel[] = [];
+
+  for (const { name, dir } of listInstalledPluginDirs()) {
+    if (isPluginDisabled(name) || isChannelId(name) || !declaresIngress(dir)) {
+      continue;
+    }
+    const presentation = await parsePluginPresentation(dir);
+    const label = presentation?.displayName ?? titleFromDirectory(name);
+    channels.push({
+      id: name,
+      source: `plugin:${name}`,
+      label,
+      subtitle: presentation?.description ?? `Provided by the ${label} plugin`,
+      icon: presentation?.icon ?? FALLBACK_ICON,
+      // No client-side verification flow exists for a plugin channel, so
+      // clients render it display-only and never pre-warm a status for it.
+      supportsVerification: false,
+      // Openers for a setup conversation, which is what this field is for.
+      // Deliberately not the verification copy the built-ins carry: there is
+      // no identity to verify here, and inventing that wording would send
+      // someone down a flow that does not exist.
+      setupMessages: {
+        guardian: `I want to set up ${label}. Can you help me?`,
+        contact: `I'd like to reach you on ${label}. Can you help me get set up?`,
+      },
+    });
+  }
+
+  return channels;
+}

package/src/channels/types.ts

@@ -51,6 +51,32 @@ export interface ChannelInfo {
   };
 }
 
+/**
+ * Source that contributes a channel, in the `<kind>[:<id>]` form the tool
+ * catalog and process tree already use: `default` for one the assistant ships,
+ * `plugin:<name>` for one an installed plugin brings.
+ *
+ * Composed from the plugin's install directory rather than from anything it
+ * declares, so a manifest cannot claim to be another source or pass itself off
+ * as built in.
+ */
+export type ChannelSource = "default" | `plugin:${string}`;
+
+/**
+ * A channel as `/v1/channels/available` reports it: the display metadata plus
+ * where it came from.
+ *
+ * `id` widens to a string here because a plugin channel's id is its plugin
+ * name, which is not a member of the closed {@link ChannelId} union. The union
+ * still governs everything the assistant routes, verifies and applies
+ * admission policy to; `source` is what tells a client which kind it is
+ * holding, so nothing has to infer it from the id.
+ */
+export interface AvailableChannel extends Omit<ChannelInfo, "id"> {
+  id: string;
+  source: ChannelSource;
+}
+
 /**
  * Per-channel display metadata for the channels the gateway can currently
  * surface to clients. Add an entry here when surfacing a new channel via
@@ -155,6 +181,10 @@ export const INTERFACE_IDS = [
   // device/service callbacks). Non-interactive — permission prompts route
   // through the guardian system, not an interactive client — and non-host-proxy.
   "route",
+  // Turns a plugin-brought channel delivered through the gateway. One id for
+  // every plugin, matching the `plugin` channel; which plugin it was is in
+  // `sourceMetadata.plugin`.
+  "plugin",
 ] as const;
 
 export type InterfaceId = (typeof INTERFACE_IDS)[number];
@@ -207,7 +237,13 @@ export function parseInterfaceId(value: unknown): InterfaceId | null {
  * than polluting the interface vocabulary. Drives only the per-turn
  * `client_os` context line (e.g. app-builder mobile-first for `ios`/`android`).
  */
-export const CLIENT_OS_VALUES = ["web", "ios", "macos", "android"] as const;
+export const CLIENT_OS_VALUES = [
+  "web",
+  "ios",
+  "macos",
+  "windows",
+  "android",
+] as const;
 
 export type ClientOs = (typeof CLIENT_OS_VALUES)[number];
 

package/src/cli/AGENTS.md

@@ -123,10 +123,13 @@ registerFooCommand(program);
    _synchronously_ at command registration (so it can't be a lazy
    `import()`) may stay hoisted behind a scoped
    `// eslint-disable-next-line cli/no-daemon-internals` with a comment
-   explaining why. The only current case is `browser/operation-meta`, in
+   explaining why. The current cases are `browser/operation-meta`, in
    `commands/browser.ts` (it drives synchronous subcommand generation and
    deliberately pulls no Playwright graph) and `commands/browser.help.ts`
-   (which derives the declarative help from the same contract).
+   (which derives the declarative help from the same contract); and
+   `providers/speech-to-text/provider-catalog`, in `commands/stt.help.ts`
+   (a literal map behind type-only imports, which the help text reads to
+   name the providers that serve the batch transcription boundary).
 
 2. **Lazy-import daemon functionality inside the action.** Running daemon
    logic in-process is encouraged where it avoids an IPC round-trip (which

package/src/cli/commands/__tests__/cache.test.ts

@@ -12,6 +12,7 @@
  */
 
 import * as nodeFs from "node:fs";
+import { fileURLToPath } from "node:url";
 import { beforeEach, describe, expect, mock, test } from "bun:test";
 
 import { Command } from "commander";
@@ -415,8 +416,9 @@ describe("cache set --value", () => {
 describe("cache set --file", () => {
   test("reads JSON from a file", async () => {
     mockIpcResult = { ok: true, result: { key: "file-key" } };
-    const pkgPath = new URL("../../../../package.json", import.meta.url)
-      .pathname;
+    const pkgPath = fileURLToPath(
+      new URL("../../../../package.json", import.meta.url),
+    );
 
     const { exitCode } = await runCommand(["cache", "set", "--file", pkgPath]);
 
@@ -442,8 +444,9 @@ describe("cache set --file", () => {
   test("works in TTY mode (no stdin required)", async () => {
     mockStdinIsTTY = true;
     mockIpcResult = { ok: true, result: { key: "file-tty-key" } };
-    const pkgPath = new URL("../../../../package.json", import.meta.url)
-      .pathname;
+    const pkgPath = fileURLToPath(
+      new URL("../../../../package.json", import.meta.url),
+    );
 
     const { exitCode } = await runCommand(["cache", "set", "--file", pkgPath]);
 

package/src/cli/commands/__tests__/cli-test-harness.ts

@@ -0,0 +1,82 @@
+/**
+ * Shared harness for CLI command tests: registers a command tree on a fresh
+ * Commander program, runs it against captured output sinks, and returns what
+ * the command emitted plus the resulting exit code.
+ *
+ * `process.stdout.write`, `console.log`, and `console.error` are captured for
+ * the duration of the run, so command output lands in the result regardless of
+ * which sink the command writes to; `process.exitCode` is reset afterwards.
+ * The caller passes its own (possibly mock-backed) registration function, so
+ * this helper imports nothing from `src/` beyond what any test file may
+ * import itself (see the test-machinery isolation rules in assistant/CLAUDE.md).
+ */
+
+import { Command } from "commander";
+
+export interface CliCommandRunResult {
+  stdout: string;
+  stderr: string;
+  /** stdout + stderr chunks in emission order, for cross-stream ordering. */
+  events: string[];
+  exitCode: number;
+}
+
+export async function runCliCommand(
+  register: (program: Command) => void,
+  args: string[],
+): Promise<CliCommandRunResult> {
+  const originalStdoutWrite = process.stdout.write.bind(process.stdout);
+  const originalConsoleLog = console.log;
+  const originalConsoleError = console.error;
+  const stdoutChunks: string[] = [];
+  const stderrChunks: string[] = [];
+  const events: string[] = [];
+
+  process.stdout.write = ((chunk: unknown) => {
+    const text = typeof chunk === "string" ? chunk : String(chunk);
+    stdoutChunks.push(text);
+    events.push(text);
+    return true;
+  }) as typeof process.stdout.write;
+  console.log = (...logArgs: unknown[]) => {
+    const text = logArgs.map(String).join(" ") + "\n";
+    stdoutChunks.push(text);
+    events.push(text);
+  };
+  console.error = (...logArgs: unknown[]) => {
+    const text = logArgs.map(String).join(" ") + "\n";
+    stderrChunks.push(text);
+    events.push(text);
+  };
+
+  process.exitCode = 0;
+
+  try {
+    const program = new Command();
+    program.exitOverride();
+    program.configureOutput({
+      writeErr: () => {},
+      writeOut: (str: string) => stdoutChunks.push(str),
+    });
+    register(program);
+    await program.parseAsync(["node", "assistant", ...args]);
+  } catch {
+    if (process.exitCode === 0) {
+      process.exitCode = 1;
+    }
+  } finally {
+    process.stdout.write = originalStdoutWrite;
+    console.log = originalConsoleLog;
+    console.error = originalConsoleError;
+  }
+
+  const exitCode = process.exitCode ?? 0;
+  process.exitCode = 0;
+
+  return {
+    stdout: stdoutChunks.join(""),
+    stderr: stderrChunks.join(""),
+    events,
+    exitCode,
+  };
+}

package/src/cli/commands/__tests__/conversations-wake.test.ts

@@ -1,8 +1,10 @@
 /**
- * CLI plumbing tests for untrusted-content input on `assistant conversations
- * wake`. Inline `--external-content` resolves to the fenced `externalContent`
- * body field and implies `--persist`. The route fences the resulting string
- * (see wake-conversation-routes.test.ts).
+ * CLI plumbing tests for `assistant conversations wake`. Inline
+ * `--external-content` resolves to the fenced `externalContent` body field and
+ * implies `--persist`; a script-mode schedule's environment resolves to the
+ * `cronRunId` and `scheduleId` body fields. The route fences the untrusted
+ * string and applies the schedule's pinned profile (see
+ * wake-conversation-routes.test.ts).
  */
 
 import * as nodeFs from "node:fs";
@@ -88,15 +90,19 @@ function lastBody(): Record<string, unknown> {
 }
 
 let savedRunId: string | undefined;
+let savedScheduleId: string | undefined;
 
 beforeEach(() => {
   lastIpcCall = null;
   loggerCalls.length = 0;
   process.exitCode = 0;
-  // The wake action reads __SCHEDULE_RUN_ID for cost attribution; clear it so
-  // it never leaks a cronRunId into the captured body.
+  // The wake action reads __SCHEDULE_RUN_ID for cost attribution and
+  // __SCHEDULE_ID for the schedule's pinned inference profile; clear both so
+  // they never leak into the captured body.
   savedRunId = process.env.__SCHEDULE_RUN_ID;
+  savedScheduleId = process.env.__SCHEDULE_ID;
   delete process.env.__SCHEDULE_RUN_ID;
+  delete process.env.__SCHEDULE_ID;
 });
 
 describe("conversations wake untrusted-content input", () => {
@@ -149,9 +155,48 @@ describe("conversations wake untrusted-content input", () => {
   });
 });
 
+describe("conversations wake schedule environment", () => {
+  test("script-mode env threads the run id and the schedule id", async () => {
+    process.env.__SCHEDULE_RUN_ID = "run-9";
+    process.env.__SCHEDULE_ID = "sched-9";
+    const code = await runWake([
+      "wake",
+      "conv-6",
+      "--hint",
+      "Digest ready",
+      "--json",
+    ]);
+    expect(code).toBe(0);
+    expect(lastBody()).toMatchObject({
+      cronRunId: "run-9",
+      scheduleId: "sched-9",
+    });
+  });
+
+  test("outside a script run neither field is sent", async () => {
+    const code = await runWake([
+      "wake",
+      "conv-7",
+      "--hint",
+      "Digest ready",
+      "--json",
+    ]);
+    expect(code).toBe(0);
+    expect(lastBody().cronRunId).toBeUndefined();
+    expect(lastBody().scheduleId).toBeUndefined();
+  });
+});
+
 afterEach(() => {
   if (savedRunId !== undefined) {
     process.env.__SCHEDULE_RUN_ID = savedRunId;
+  } else {
+    delete process.env.__SCHEDULE_RUN_ID;
+  }
+  if (savedScheduleId !== undefined) {
+    process.env.__SCHEDULE_ID = savedScheduleId;
+  } else {
+    delete process.env.__SCHEDULE_ID;
   }
   process.exitCode = 0;
 });

package/src/cli/commands/__tests__/inference-models.test.ts

@@ -72,6 +72,20 @@ describe("models list", () => {
     });
   });
 
+  test("bare `models` runs list", async () => {
+    await run(["models"]);
+    expect(lastIpcCall?.method).toBe("inference_models_list");
+    expect(lastIpcCall?.params).toEqual({ queryParams: {} });
+  });
+
+  test("bare `models --provider` runs list with the filter", async () => {
+    await run(["models", "--provider", "gemini"]);
+    expect(lastIpcCall?.method).toBe("inference_models_list");
+    expect(lastIpcCall?.params).toEqual({
+      queryParams: { provider: "gemini" },
+    });
+  });
+
   test("--json emits structured output", async () => {
     mockIpcResult = {
       ok: true,