@vellumai/assistant 0.11.3 → 0.11.4-dev.202608190019.b94dbf2

package/src/runtime/routes/__tests__/schedule-routes-disarm-reason.test.ts

@@ -0,0 +1,215 @@
+/**
+ * The schedule list and detail routes say why a plugin-sourced schedule is
+ * off, so a client never has to show an unexplained disabled row.
+ *
+ * The reason is derived from the row plus the plugin's files, so the fixtures
+ * here write real plugin directories under the per-test-process workspace
+ * plugins dir and converge them against the real schedule store.
+ */
+
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { beforeEach, describe, expect, test } from "bun:test";
+
+import { setOverridesForTesting } from "../../../__tests__/feature-flag-test-helpers.js";
+import { getDb } from "../../../persistence/db-connection.js";
+import { initializeDb } from "../../../persistence/db-init.js";
+import {
+  createSchedule,
+  setUserEnabled,
+  upsertDeclaredSchedule,
+} from "../../../schedule/schedule-store.js";
+import { getWorkspacePluginsDir } from "../../../util/platform.js";
+import { ROUTES } from "../schedule-routes.js";
+
+await initializeDb();
+
+const pluginsDir = getWorkspacePluginsDir();
+
+function routeHandler(operationId: string) {
+  const route = ROUTES.find((r) => r.operationId === operationId);
+  if (!route) {
+    throw new Error(`${operationId} route not found`);
+  }
+  return route.handler;
+}
+
+const listHandler = routeHandler("listSchedules");
+const getHandler = routeHandler("getSchedule");
+
+interface SerializedSchedule {
+  id: string;
+  sourceKey: string | null;
+  enabled: boolean;
+  disarmReason: string | null;
+}
+
+async function listed(id: string): Promise<SerializedSchedule> {
+  const { schedules } = (await listHandler({ queryParams: {} })) as {
+    schedules: SerializedSchedule[];
+  };
+  const found = schedules.find((s) => s.id === id);
+  if (!found) {
+    throw new Error(`schedule ${id} missing from the list response`);
+  }
+  return found;
+}
+
+async function fetched(id: string): Promise<SerializedSchedule> {
+  const { schedule } = (await getHandler({ pathParams: { id } })) as {
+    schedule: SerializedSchedule;
+  };
+  return schedule;
+}
+
+/** Write a plugin dir holding one `schedules/<name>/` declaration. */
+function writePlugin(
+  pluginName: string,
+  options: { declaration?: string; disabled?: boolean } = {},
+): void {
+  const dir = join(pluginsDir, pluginName);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(
+    join(dir, "package.json"),
+    JSON.stringify({ name: pluginName, version: "1.0.0" }),
+  );
+  if (options.declaration) {
+    const declarationDir = join(dir, "schedules", options.declaration);
+    mkdirSync(declarationDir, { recursive: true });
+    writeFileSync(
+      join(declarationDir, "config.json"),
+      JSON.stringify({ expression: "* * * * *" }),
+    );
+    writeFileSync(join(declarationDir, "index.md"), "Summarize the day.\n");
+  }
+  if (options.disabled) {
+    writeFileSync(join(dir, ".disabled"), "");
+  }
+}
+
+/** A declared row for `plugin:<pluginName>/digest`, armed or not. */
+async function declaredRow(
+  pluginName: string,
+  enabled: boolean,
+): Promise<string> {
+  const job = await upsertDeclaredSchedule(`plugin:${pluginName}/digest`, {
+    name: `${pluginName}-digest`,
+    description: "Daily digest",
+    syntax: "cron",
+    expression: "* * * * *",
+    message: "Summarize the day.",
+    mode: "execute",
+    enabled,
+    definitionHash: `hash-${pluginName}`,
+  });
+  return job.id;
+}
+
+/** Stamp the engine's exhaust latch onto a row: off, spent, and last run. */
+function latchAsCompleted(id: string): void {
+  getDb().run(
+    `UPDATE cron_jobs SET enabled = 0, next_run_at = 0, last_run_at = ${Date.now()} WHERE id = '${id}'`,
+  );
+}
+
+beforeEach(() => {
+  getDb().run("DELETE FROM cron_runs");
+  getDb().run("DELETE FROM cron_jobs");
+  rmSync(pluginsDir, { recursive: true, force: true });
+  // The feature ships off, so every case states the flag it runs under rather
+  // than inheriting the registry default.
+  setOverridesForTesting({ "plugin-schedules": true });
+});
+
+describe("schedule serialization: disarmReason", () => {
+  test("a user's own override outranks whatever the plugin's files say", async () => {
+    writePlugin("news", { declaration: "digest" });
+    const id = await declaredRow("news", true);
+    await setUserEnabled(id, false);
+
+    expect((await listed(id)).disarmReason).toBe("user_disabled");
+    expect((await fetched(id)).disarmReason).toBe("user_disabled");
+  });
+
+  test("a plugin that is gone from disk reads as removed", async () => {
+    const id = await declaredRow("news", false);
+
+    expect((await listed(id)).disarmReason).toBe("plugin_removed");
+    expect((await fetched(id)).disarmReason).toBe("plugin_removed");
+  });
+
+  test("a plugin carrying the .disabled sentinel reads as disabled", async () => {
+    writePlugin("news", { declaration: "digest", disabled: true });
+    const id = await declaredRow("news", false);
+
+    expect((await listed(id)).disarmReason).toBe("plugin_disabled");
+    expect((await fetched(id)).disarmReason).toBe("plugin_disabled");
+  });
+
+  test("a declaration dropped from a plugin that is still installed", async () => {
+    writePlugin("news");
+    const id = await declaredRow("news", false);
+
+    expect((await listed(id)).disarmReason).toBe("declaration_removed");
+    expect((await fetched(id)).disarmReason).toBe("declaration_removed");
+  });
+
+  test("a declaration still on disk means the plugin's files turned it off", async () => {
+    writePlugin("news", { declaration: "digest" });
+    const id = await declaredRow("news", false);
+
+    expect((await listed(id)).disarmReason).toBe("declaration_disabled");
+    expect((await fetched(id)).disarmReason).toBe("declaration_disabled");
+  });
+
+  test("an armed plugin row has no reason to give", async () => {
+    writePlugin("news", { declaration: "digest" });
+    const id = await declaredRow("news", true);
+
+    const row = await listed(id);
+    expect(row.enabled).toBe(true);
+    expect(row.disarmReason).toBeNull();
+    expect((await fetched(id)).disarmReason).toBeNull();
+  });
+
+  test("a run-to-completion row reads as finished, not paused", async () => {
+    writePlugin("news", { declaration: "digest" });
+    const id = await declaredRow("news", true);
+    latchAsCompleted(id);
+
+    const row = await listed(id);
+    expect(row.enabled).toBe(false);
+    expect(row.disarmReason).toBeNull();
+    expect((await fetched(id)).disarmReason).toBeNull();
+  });
+
+  test("the kill switch being off is not a per-row cause", async () => {
+    writePlugin("news", { declaration: "digest" });
+    const id = await declaredRow("news", false);
+    setOverridesForTesting({ "plugin-schedules": false });
+
+    const row = await listed(id);
+    expect(row.enabled).toBe(false);
+    expect(row.disarmReason).toBeNull();
+    expect((await fetched(id)).disarmReason).toBeNull();
+  });
+
+  test("a user-created schedule never carries one, off or on", async () => {
+    const job = await createSchedule({
+      name: "wt-imperative",
+      description: "d",
+      message: "do the thing",
+      mode: "execute",
+      enabled: false,
+      timezone: null,
+      expression: "* * * * *",
+      syntax: "cron",
+    });
+
+    const row = await listed(job.id);
+    expect(row.sourceKey).toBeNull();
+    expect(row.enabled).toBe(false);
+    expect(row.disarmReason).toBeNull();
+    expect((await fetched(job.id)).disarmReason).toBeNull();
+  });
+});

package/src/runtime/routes/__tests__/stt-routes.test.ts

@@ -288,6 +288,31 @@ describe("stt-routes", () => {
     expect(err.message).toContain("not available");
   });
 
+  test("surfaces a typed resolver error verbatim instead of the generic copy", async () => {
+    // A streaming-only provider IS configured, so the "nothing configured"
+    // and "not available" strings would both send the caller looking for a
+    // problem that does not exist.
+    const reason =
+      'Deepgram Flux is streaming-only. Batch transcription requires the deepgram provider: set services.stt.provider to "deepgram".';
+    mockResolveError = new SttError("provider-error", reason, {
+      userFacing: true,
+    });
+
+    const { handler } = getRoute("stt/transcribe");
+    const err = await expectRouteError(
+      () =>
+        handler(
+          makeArgs({
+            audioBase64: toBase64("audio-data"),
+            mimeType: "audio/wav",
+          }),
+        ),
+      503,
+      "SERVICE_UNAVAILABLE",
+    );
+    expect(err.message).toBe(reason);
+  });
+
   // -- Timeout --------------------------------------------------------------
 
   test("throws 504 when transcription times out", async () => {

package/src/runtime/routes/__tests__/surface-action-routes.test.ts

@@ -26,6 +26,10 @@ interface StubConversation {
   handleSurfaceUndoCalled?: boolean;
   handleSurfaceUndoThrows?: Error;
   trustContext?: { trustClass: string; sourceChannel: string };
+  /** Drives `isProcessing()`; the route must not stamp trust either way. */
+  processing?: boolean;
+  /** Trust the route threaded into `handleSurfaceAction`. */
+  lastRequesterTrustContext?: { trustClass: string; sourceChannel: string };
   surfaceActionCalls: Array<{
     surfaceId: string;
     actionId: string;
@@ -160,7 +164,9 @@ function makeStub(id: string): StubConversation {
       actionId: string,
       data: unknown,
       sourceActorPrincipalId?: string,
+      requesterTrustContext?: { trustClass: string; sourceChannel: string },
     ) => {
+      stub.lastRequesterTrustContext = requesterTrustContext;
       stub.surfaceActionCalls.push({
         surfaceId,
         actionId,
@@ -181,6 +187,7 @@ function makeStub(id: string): StubConversation {
     setTrustContext: (ctx: { trustClass: string; sourceChannel: string }) => {
       stub.trustContext = ctx;
     },
+    isProcessing: () => stub.processing === true,
   });
   return stub;
 }
@@ -487,8 +494,8 @@ describe("triggerSurfaceAction trust context", () => {
       headers: { "x-vellum-actor-principal-id": GUARDIAN_PRINCIPAL },
     });
 
-    expect(live.trustContext?.trustClass).toBe("guardian");
-    expect(live.trustContext?.sourceChannel).toBe("vellum");
+    expect(live.lastRequesterTrustContext?.trustClass).toBe("guardian");
+    expect(live.lastRequesterTrustContext?.sourceChannel).toBe("vellum");
     // First-pass resolve already granted guardian, so the drift helper is skipped.
     expect(reResolveCalls).toEqual([]);
   });
@@ -506,7 +513,7 @@ describe("triggerSurfaceAction trust context", () => {
     });
 
     expect(reResolveCalls).toEqual([VELLUM_PRINCIPAL_OLD]);
-    expect(live.trustContext?.trustClass).toBe("unknown");
+    expect(live.lastRequesterTrustContext?.trustClass).toBe("unknown");
   });
 
   test("reset drift: helper returns guardian → route adopts it", async () => {
@@ -522,7 +529,7 @@ describe("triggerSurfaceAction trust context", () => {
     });
 
     expect(reResolveCalls).toEqual([VELLUM_PRINCIPAL_OLD]);
-    expect(live.trustContext?.trustClass).toBe("guardian");
+    expect(live.lastRequesterTrustContext?.trustClass).toBe("guardian");
   });
 
   test("dev-bypass resolves the real guardian principal from the gateway, helper not called", async () => {
@@ -539,7 +546,7 @@ describe("triggerSurfaceAction trust context", () => {
 
     // The synthetic dev-bypass principal is translated to the real guardian,
     // yielding a guardian trust context without consulting the drift helper.
-    expect(live.trustContext?.trustClass).toBe("guardian");
+    expect(live.lastRequesterTrustContext?.trustClass).toBe("guardian");
     expect(reResolveCalls).toEqual([]);
   });
 
@@ -559,7 +566,49 @@ describe("triggerSurfaceAction trust context", () => {
       headers: { "x-vellum-actor-principal-id": "dev-bypass" },
     });
 
-    expect(live.trustContext?.trustClass).toBe("unknown");
+    expect(live.lastRequesterTrustContext?.trustClass).toBe("unknown");
+  });
+
+  test("idle conversation: the requester is threaded to the action and the slot is left to the dispatch", async () => {
+    mockGuardianList = [guardianDelivery(GUARDIAN_PRINCIPAL)];
+    const live = makeStub("conv-idle");
+    live.processing = false;
+    memoryBySurface = live;
+
+    const handler = findHandler("triggerSurfaceAction");
+    await handler({
+      body: { surfaceId: "surf-idle", actionId: "act-idle" },
+      headers: { "x-vellum-actor-principal-id": GUARDIAN_PRINCIPAL },
+    });
+
+    expect(live.lastRequesterTrustContext?.trustClass).toBe("guardian");
+    // The route resolves; `handleSurfaceAction` stamps, and only where it
+    // commits to running the turn. Stamping here would repoint the actor of a
+    // turn that starts between this call and the dispatch.
+    expect(live.trustContext).toBeUndefined();
+  });
+
+  test("busy conversation: the running turn's actor is left alone and the click still travels as its own actor", async () => {
+    mockGuardianList = [guardianDelivery(GUARDIAN_PRINCIPAL)];
+    const live = makeStub("conv-busy");
+    // A turn is already running under a different actor.
+    const runningTurnActor = {
+      trustClass: "untrusted",
+      sourceChannel: "sms",
+    };
+    live.trustContext = runningTurnActor;
+    live.processing = true;
+    memoryBySurface = live;
+
+    const handler = findHandler("triggerSurfaceAction");
+    await handler({
+      body: { surfaceId: "surf-busy", actionId: "act-busy" },
+      headers: { "x-vellum-actor-principal-id": GUARDIAN_PRINCIPAL },
+    });
+
+    // Identical object, so a re-write of an equal value still fails this.
+    expect(live.trustContext).toBe(runningTurnActor);
+    expect(live.lastRequesterTrustContext?.trustClass).toBe("guardian");
   });
 });
 

package/src/runtime/routes/__tests__/user-route-dispatcher-host.test.ts

@@ -3,7 +3,10 @@ import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
 
 import type { RouteInvokeParams } from "../../../routes/route-host-protocol.js";
-import { getWorkspaceRoutesDir } from "../../../util/platform.js";
+import {
+  getWorkspacePluginsDir,
+  getWorkspaceRoutesDir,
+} from "../../../util/platform.js";
 
 // The dispatcher constructs the route host client inline and reads the enabled
 // flag from config, so both are mocked here (there is no injection seam).
@@ -58,6 +61,16 @@ function writeHandler(name: string, content: string): void {
   writeFileSync(join(getWorkspaceRoutesDir(), name), content);
 }
 
+function writePluginHandler(
+  pluginName: string,
+  name: string,
+  content: string,
+): void {
+  const dir = join(getWorkspacePluginsDir(), pluginName, "routes");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, name), content);
+}
+
 function jsonResponse(status: number, value: unknown): RouteInvokeResponse {
   return {
     status,
@@ -75,6 +88,7 @@ beforeEach(() => {
 
 afterEach(() => {
   rmSync(getWorkspaceRoutesDir(), { recursive: true, force: true });
+  rmSync(getWorkspacePluginsDir(), { recursive: true, force: true });
 });
 
 describe("UserRouteDispatcher — route host delegation", () => {
@@ -101,6 +115,43 @@ describe("UserRouteDispatcher — route host delegation", () => {
     expect(invokeCalls[0].params.url).toContain("/v1/x/foo");
   });
 
+  test("names the owning plugin so the host executes in its context", async () => {
+    // The host marks this plugin as in context for the handler, so
+    // plugin-scoped host APIs behave the same in the host and in-thread.
+    writePluginHandler(
+      "my-plugin",
+      "status.ts",
+      `export function GET() { return new Response(); }`,
+    );
+    hostEnabled = true;
+    const dispatcher = makeDispatcher();
+
+    await dispatcher.dispatch(
+      "plugins/my-plugin/status",
+      new Request("http://localhost/v1/x/plugins/my-plugin/status", {
+        method: "GET",
+      }),
+    );
+
+    expect(invokeCalls[0].params.pluginName).toBe("my-plugin");
+  });
+
+  test("leaves a workspace route unowned", async () => {
+    writeHandler(
+      "plain.ts",
+      `export function GET() { return new Response(); }`,
+    );
+    hostEnabled = true;
+    const dispatcher = makeDispatcher();
+
+    await dispatcher.dispatch(
+      "plain",
+      new Request("http://localhost/v1/x/plain", { method: "GET" }),
+    );
+
+    expect(invokeCalls[0].params.pluginName).toBeUndefined();
+  });
+
   test("runs in-band when disabled (host never called)", async () => {
     writeHandler(
       "bar.ts",

package/src/runtime/routes/__tests__/user-route-dispatcher.test.ts

@@ -1,5 +1,5 @@
 import { mkdirSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 
 // ---------------------------------------------------------------------------
@@ -56,6 +56,15 @@ function writePluginHandler(
   return fullPath;
 }
 
+/**
+ * Absolute specifier for the plugin execution context, so a handler written to
+ * a temp routes directory imports the same module instance this process holds.
+ */
+const PLUGIN_CONTEXT_MODULE = new URL(
+  "../../../plugins/plugin-execution-context.ts",
+  import.meta.url,
+).href;
+
 async function readErrorBody(
   response: Response,
 ): Promise<{ error: { code: string; message: string } }> {
@@ -466,6 +475,71 @@ describe("plugin routes", () => {
     expect(body.plugin).toBe(true);
   });
 
+  test("executes the handler as the plugin that owns the namespace", async () => {
+    // Plugin-scoped host APIs (resolveCredential, indexDocument) read the
+    // execution context to decide what the caller may touch. A route handler
+    // that ran outside it would fall through to their unscoped branch and
+    // reach every plugin's credentials.
+    writePluginHandler(
+      "my-plugin",
+      "whoami.ts",
+      `import { getCurrentPluginName } from ${JSON.stringify(PLUGIN_CONTEXT_MODULE)};
+       export function GET(request) {
+        return Response.json({ plugin: getCurrentPluginName() ?? null });
+      }`,
+    );
+
+    const dispatcher = makeDispatcher();
+    const res = await dispatcher.dispatch(
+      "plugins/my-plugin/whoami",
+      makeRequest("GET"),
+    );
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.plugin).toBe("my-plugin");
+  });
+
+  test("evaluates the route module in the plugin's context too", async () => {
+    // A module can reach a scoped host API at import time, and the import
+    // happens once per mtime. A load left outside the context would take the
+    // unscoped branch and never be re-run scoped, so the context has to cover
+    // module evaluation and not just the handler call.
+    writePluginHandler(
+      "my-plugin",
+      "at-import.ts",
+      `import { getCurrentPluginName } from ${JSON.stringify(PLUGIN_CONTEXT_MODULE)};
+       const atImport = getCurrentPluginName() ?? null;
+       export function GET(request) {
+        return Response.json({ atImport });
+      }`,
+    );
+
+    const dispatcher = makeDispatcher();
+    const res = await dispatcher.dispatch(
+      "plugins/my-plugin/at-import",
+      makeRequest("GET"),
+    );
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.atImport).toBe("my-plugin");
+  });
+
+  test("leaves a workspace route outside any plugin context", async () => {
+    writeHandler(
+      "whoami.ts",
+      `import { getCurrentPluginName } from ${JSON.stringify(PLUGIN_CONTEXT_MODULE)};
+       export function GET(request) {
+        return Response.json({ plugin: getCurrentPluginName() ?? null });
+      }`,
+    );
+
+    const dispatcher = makeDispatcher();
+    const res = await dispatcher.dispatch("whoami", makeRequest("GET"));
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.plugin).toBeNull();
+  });
+
   test("resolves nested paths and the index (namespace root)", async () => {
     writePluginHandler(
       "my-plugin",
@@ -574,4 +648,62 @@ describe("plugin routes", () => {
     );
     expect(other.status).toBe(404);
   });
+
+  test("a new route export is not bound to a stale helper after upgrade", async () => {
+    // Reproduces the browser plugin 500: `/frame` loaded `src/http.ts`
+    // first, then an upgrade added `requireNumber` to http.ts and a new
+    // `/input` that imports it. Cache-busting only the entry file rebound
+    // input.ts to the cached http.ts, which had no such export.
+    const plugin = "stale-helper";
+    const helperPath = join(getWorkspacePluginsDir(), plugin, "src", "http.ts");
+    mkdirSync(dirname(helperPath), { recursive: true });
+    writeFileSync(helperPath, `export function label() { return "v1"; }\n`);
+    writePluginHandler(
+      plugin,
+      "frame.ts",
+      `import { label } from "../src/http.js";
+       export function GET() { return Response.json({ label: label() }); }`,
+    );
+    writePluginHandler(
+      plugin,
+      "input.ts",
+      `import { label } from "../src/http.js";
+       export function POST() { return Response.json({ label: label() }); }`,
+    );
+
+    const dispatcher = makeDispatcher();
+    const frame1 = await dispatcher.dispatch(
+      `plugins/${plugin}/frame`,
+      makeRequest("GET"),
+    );
+    expect(frame1.status).toBe(200);
+    expect((await frame1.json()).label).toBe("v1");
+
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    writeFileSync(
+      helperPath,
+      `export function label() { return "v2"; }
+       export function extra() { return true; }\n`,
+    );
+    writePluginHandler(
+      plugin,
+      "input.ts",
+      `import { extra } from "../src/http.js";
+       export function POST() { return Response.json({ extra: extra() }); }`,
+    );
+
+    const input = await dispatcher.dispatch(
+      `plugins/${plugin}/input`,
+      makeRequest("POST"),
+    );
+    expect(input.status).toBe(200);
+    expect((await input.json()).extra).toBe(true);
+
+    const frame2 = await dispatcher.dispatch(
+      `plugins/${plugin}/frame`,
+      makeRequest("GET"),
+    );
+    expect(frame2.status).toBe(200);
+    expect((await frame2.json()).label).toBe("v2");
+  });
 });

package/src/runtime/routes/channel-availability-routes.ts

@@ -4,11 +4,11 @@
  * GET /v1/channels/available — return the channels this assistant can
  * surface to clients (Contacts / GuardianChannels views, etc.) along with
  * their display metadata (label, subtitle, icon, verification capability,
- * setup-message copy). Today this is a fixed base list plus `email` when
- * an inbox is registered; eventually the list will be driven by
- * plugins/skills the assistant has loaded. Clients should treat the
- * response as authoritative and stop carrying their own per-channel
- * switches.
+ * setup-message copy). A fixed base list, plus `email` when an inbox is
+ * registered, plus the channels installed plugins bring by declaring
+ * ingress. One list, because a plugin channel is a channel; each row's
+ * `source` says who contributes it. Clients should treat the response as
+ * authoritative and stop carrying their own per-channel switches.
  *
  * Distinct from `/v1/channels/readiness` (which answers "is this channel
  * configured and working?"). Availability answers "could this channel be
@@ -18,8 +18,9 @@
 import { z } from "zod";
 
 import { isA2AEnabled } from "../../a2a/feature-gate.js";
+import { discoverPluginChannels } from "../../channels/plugin-channel-declarations.js";
 import {
-  CHANNEL_IDS,
+  type AvailableChannel,
   CHANNEL_METADATA,
   type ChannelId,
   type ChannelInfo,
@@ -73,7 +74,7 @@ async function hasRegisteredInbox(): Promise<boolean> {
 
 async function handleGetChannelAvailability(
   _args: RouteHandlerArgs,
-): Promise<{ channels: ChannelInfo[] }> {
+): Promise<{ channels: AvailableChannel[] }> {
   const ids: ChannelId[] = [...BASE_AVAILABLE_CHANNELS];
   if (await hasRegisteredInbox()) {
     ids.push("email");
@@ -86,14 +87,26 @@ async function handleGetChannelAvailability(
   // contains channels that BASE_AVAILABLE_CHANNELS / the email branch
   // explicitly chose, so the lookup is always defined — filter to satisfy
   // the type system without a non-null assertion.
-  const channels = ids
+  const builtIn: AvailableChannel[] = ids
     .map((id) => CHANNEL_METADATA[id])
-    .filter((info): info is ChannelInfo => info !== undefined);
-  return { channels };
+    .filter((info): info is ChannelInfo => info !== undefined)
+    .map((info) => ({ ...info, source: "default" as const }));
+  // One list, because a plugin channel is a channel: what differs is who
+  // contributes it, which is what `source` says. Built-ins lead, so a client
+  // rendering in order gets a stable list that plugin installs append to.
+  return { channels: [...builtIn, ...(await discoverPluginChannels())] };
 }
 
 const channelInfoSchema = z.object({
-  id: z.enum(CHANNEL_IDS),
+  // A string rather than the channel enum: a plugin channel's id is its
+  // plugin name, and `source` is what says which kind a row is.
+  id: z.string(),
+  source: z
+    .string()
+    .describe(
+      "`default` for a channel the assistant ships, `plugin:<name>` for one " +
+        "an installed plugin brings",
+    ),
   label: z.string(),
   subtitle: z.string(),
   icon: z.string(),
@@ -117,14 +130,19 @@ export const ROUTES: RouteDefinition[] = [
     description:
       "Return the channels this assistant can surface to clients, with " +
       "display metadata (label, icon, verification capability, setup " +
-      "copy). Today this is a fixed base list plus `email` when an inbox " +
-      "is registered; will become plugin/skill-driven in future.",
+      "copy). A fixed base list plus `email` when an inbox is registered, " +
+      "plus the channels installed plugins bring by declaring ingress " +
+      "routes. Each carries a `source` saying which of those it is.",
     tags: ["channels"],
     handler: handleGetChannelAvailability,
     responseBody: z.object({
       channels: z
         .array(channelInfoSchema)
-        .describe("Available channels in display order"),
+        .describe(
+          "Available channels in display order: the ones the assistant " +
+            "ships, then the ones installed plugins bring by declaring " +
+            "ingress routes. `source` distinguishes them.",
+        ),
     }),
   },
 ];