@vellumai/assistant 0.12.0-staging.1 → 0.12.0

package/src/cli/commands/channels/__tests__/request.test.ts

@@ -0,0 +1,191 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+// The command runs the authenticated-request route in-process, as `oauth
+// request` does. The route is stubbed so the tests see exactly what provider
+// key and request shape the command hands it; IPC is stubbed to prove the
+// command never takes that path. The exit-code helpers stay real, so the
+// tests assert the mapping that ships.
+const ipcCalls: string[] = [];
+const handleRequestCalls: Array<{ body: Record<string, unknown> }> = [];
+
+const actualCliClient = await import("../../../../ipc/cli-client.js");
+mock.module("../../../../ipc/cli-client.js", () => ({
+  ...actualCliClient,
+  cliIpcCall: async (method: string) => {
+    ipcCalls.push(method);
+    return { ok: false, error: `Unexpected IPC method ${method}` };
+  },
+}));
+
+mock.module("../../../../runtime/routes/oauth-commands-routes.js", () => ({
+  handleRequest: async (args: { body: Record<string, unknown> }) => {
+    handleRequestCalls.push(args);
+    return {
+      ok: true,
+      status: 200,
+      headers: { "content-type": "application/json" },
+      body: { ok: true, user_id: "U0BOT" },
+    };
+  },
+}));
+
+import { botProviderForChannel } from "@vellumai/service-contracts/channels";
+import type { Command } from "commander";
+
+import { runCliCommand } from "../../__tests__/cli-test-harness.js";
+import { registerChannelsCommand } from "../index.js";
+import { REQUESTABLE_CHANNELS } from "../request.js";
+
+const { exitCodeFromIpcResult } = actualCliClient;
+
+beforeEach(() => {
+  ipcCalls.length = 0;
+  handleRequestCalls.length = 0;
+});
+
+/**
+ * The shipped registration, plus the `--json` leaf option the program
+ * normally attaches after every command is registered.
+ */
+function registerChannels(program: Command): void {
+  registerChannelsCommand(program);
+  program.commands
+    .find((c) => c.name() === "channels")
+    ?.commands.find((c) => c.name() === "request")
+    ?.option("--json");
+}
+
+function runChannelsRequest(args: string[]) {
+  return runCliCommand(registerChannels, ["channels", "request", ...args]);
+}
+
+describe("channel to bot provider", () => {
+  test("names the bot credential's provider for every built-in bot channel", () => {
+    // The map is the contract's, not a copy: the command answers exactly what
+    // CHANNEL_BOT_PROVIDER says, including telegram, whose bot key carries no
+    // suffix because Telegram has no user-identity integration.
+    expect(botProviderForChannel("slack")).toBe("slack_channel");
+    expect(botProviderForChannel("discord")).toBe("discord_channel");
+    expect(botProviderForChannel("telegram")).toBe("telegram");
+    expect([...REQUESTABLE_CHANNELS].sort()).toEqual([
+      "discord",
+      "slack",
+      "telegram",
+    ]);
+  });
+
+  test("a channel without a bot credential resolves to nothing", () => {
+    expect(botProviderForChannel("phone")).toBeUndefined();
+    expect(botProviderForChannel("vellum")).toBeUndefined();
+    expect(botProviderForChannel("not-a-channel")).toBeUndefined();
+  });
+
+  test("an inherited object property is not a channel", () => {
+    expect(botProviderForChannel("constructor")).toBeUndefined();
+    expect(botProviderForChannel("toString")).toBeUndefined();
+    expect(botProviderForChannel("__proto__")).toBeUndefined();
+  });
+});
+
+describe("assistant channels request", () => {
+  test("requests as the channel's bot, in-process, never over IPC", async () => {
+    const { stdout, exitCode } = await runChannelsRequest([
+      "slack",
+      "-s",
+      "/auth.test",
+    ]);
+
+    expect(exitCode).toBe(0);
+    expect(ipcCalls).toEqual([]);
+    expect(handleRequestCalls).toEqual([
+      { body: { provider: "slack_channel", url: "/auth.test" } },
+    ]);
+    expect(stdout).toContain("U0BOT");
+  });
+
+  test("forwards method and JSON body the way oauth request does", async () => {
+    await runChannelsRequest([
+      "slack",
+      "-s",
+      "-X",
+      "POST",
+      "-d",
+      '{"channel":"D0123456789","limit":20}',
+      "/conversations.history",
+    ]);
+
+    expect(handleRequestCalls).toEqual([
+      {
+        body: {
+          provider: "slack_channel",
+          url: "/conversations.history",
+          method: "POST",
+          parsed_data: { channel: "D0123456789", limit: 20 },
+        },
+      },
+    ]);
+  });
+
+  test("never offers the person's OAuth integration for a bot channel", async () => {
+    await runChannelsRequest(["discord", "-s", "/users/@me"]);
+
+    expect(handleRequestCalls[0]?.body.provider).toBe("discord_channel");
+    expect(handleRequestCalls[0]?.body).not.toHaveProperty("account");
+    expect(handleRequestCalls[0]?.body).not.toHaveProperty("client_id");
+  });
+
+  test("a channel with no bot credential is refused before any request", async () => {
+    const { stderr, exitCode } = await runChannelsRequest([
+      "phone",
+      "/anything",
+    ]);
+
+    expect(exitCode).toBe(1);
+    expect(handleRequestCalls).toEqual([]);
+    expect(stderr).toContain('Channel "phone" has no bot credential');
+    expect(stderr).toContain("plugins search");
+  });
+
+  test("names the channel command, not the OAuth one, in its diagnostics hint", async () => {
+    mock.module("../../../../runtime/routes/oauth-commands-routes.js", () => ({
+      handleRequest: async () => {
+        throw new Error("boom");
+      },
+    }));
+
+    const { stderr, exitCode } = await runChannelsRequest([
+      "slack",
+      "/auth.test",
+    ]);
+
+    expect(exitCode).toBe(1);
+    expect(stderr).toContain("assistant channels get slack");
+    expect(stderr).not.toContain("oauth providers get");
+  });
+
+  test("a structured route failure keeps the JSON envelope and the hint", async () => {
+    const { RouteError } = await import("../../../../runtime/routes/errors.js");
+    mock.module("../../../../runtime/routes/oauth-commands-routes.js", () => ({
+      handleRequest: async () => {
+        throw new RouteError(
+          "Provider not configured: slack_channel",
+          "NOT_FOUND",
+          404,
+        );
+      },
+    }));
+
+    const { stdout, exitCode } = await runChannelsRequest([
+      "slack",
+      "--json",
+      "/auth.test",
+    ]);
+
+    // The exit code is the one the route's status maps to for every command.
+    expect(exitCode).toBe(exitCodeFromIpcResult({ statusCode: 404 }));
+    const envelope = JSON.parse(stdout.trim());
+    expect(envelope.ok).toBe(false);
+    expect(envelope.error).toContain("Provider not configured");
+    expect(envelope.error).toContain("assistant channels get slack");
+  });
+});

package/src/cli/commands/channels/index.help.ts

@@ -1,40 +1,92 @@
 /** Declarative help for the `assistant channels` command. */
 
+import {
+  CHANNEL_BOT_PROVIDER,
+  CHANNEL_IDS,
+} from "@vellumai/service-contracts/channels";
+
 import type { CliCommandHelp } from "../../lib/cli-command-help.js";
 
-/** All channel IDs the readiness service knows about. Mirrors channels/types.ts. */
-export const KNOWN_CHANNELS = [
-  "telegram",
-  "phone",
-  "vellum",
-  "whatsapp",
-  "slack",
-  "email",
-  "platform",
-  "a2a",
-] as const;
+/**
+ * The channel ids the readiness route accepts: the canonical vocabulary. A
+ * channel with no built-in probe reports as unsupported rather than being
+ * refused, so the list is the contract's, not a copy kept here.
+ */
+export const KNOWN_CHANNELS: readonly string[] = CHANNEL_IDS;
+
+/** The channels whose bot the assistant can act as. */
+const BOT_CHANNELS = Object.keys(CHANNEL_BOT_PROVIDER).join(", ");
 
 export const CHANNELS_PLUGIN_SEARCH_HINT =
   "If the channel you are looking for is not listed, search the plugin marketplace with 'assistant plugins search <name>'.";
 
 export const channelsHelp: CliCommandHelp = {
   name: "channels",
-  description: "Inspect and repair messaging channels",
+  description: "Inspect messaging channels and act as their bots",
   helpText: `
-Channels are the messaging surfaces the assistant talks over. Built-in
-readiness probes cover slack, telegram, whatsapp, email, phone, vellum,
-platform, and a2a.
+Channels are the messaging surfaces the assistant talks over. Channel ids:
+${KNOWN_CHANNELS.join(", ")}. A channel without a built-in readiness probe
+reports as unsupported.
 
 ${CHANNELS_PLUGIN_SEARCH_HINT} Plugins can bundle additional channels
 from other Vellum users.
 
-  list                    Overview of every channel + ready state
-  get <channel>           Live snapshot of one channel (always re-probes)
+Two identities can reach a channel's platform. 'request' acts as the
+assistant's own bot on that channel (${BOT_CHANNELS}), resolving the bot
+credential from the channel id so no token is handled. Acting as a person
+through their OAuth integration is 'assistant oauth request'.
 
 Examples:
   $ assistant channels list
-  $ assistant channels get slack`,
+  $ assistant channels get slack
+  $ assistant channels request slack /auth.test --json
+  $ assistant channels request slack -X POST \\
+      -d '{"channel":"D0123456789","limit":20}' /conversations.history --json`,
   subcommands: [
+    {
+      name: "request",
+      args: "<channel> <url>",
+      description:
+        "Call the channel's platform API as the assistant's own bot on that channel (curl-like interface)",
+      // The request-shaping options (-X, -H, -d, -G, -I, -o, -s, -v, -i) are
+      // registered imperatively in request.ts: the repeatable "-H, --header"
+      // flag needs a Commander collect parser the declarative contract cannot
+      // express, and the options must keep their registration order around
+      // it.
+      helpText: `
+Makes one authenticated request to the channel's platform API as the
+assistant's bot. The bot credential is the one the channel's setup wizard
+stored; it is resolved from the channel and sent from inside the assistant,
+never printed or passed on the command line. Acting as a person through
+their OAuth integration is a different identity and stays on
+'assistant oauth request --provider <key>'.
+
+This command can do anything the bot's API allows, including sending,
+editing, deleting, uploading, and reacting, so it is classified high risk
+and asks for approval like any action with irreversible effects. Reads are
+not distinguished from writes: the effect is the endpoint's. To send a
+message, use the messaging tool, which records what it sent; do not post
+through this command.
+
+Arguments:
+  <channel>  One of: ${BOT_CHANNELS}. A channel with no bot credential of
+             its own (phone, vellum) is refused.
+  <url>      The API method path, relative to the platform's API host
+             (for Slack, '/conversations.history'; for Discord, '/users/@me';
+             for Telegram, '/getMe'). The provider supplies the host.
+
+Options:
+  -X <method>      HTTP method (default: GET; POST when -d is given).
+  -H 'Key: Value'  Request header, repeatable.
+  -d <data>        Request body: inline JSON, @file, or @- for stdin.
+  --json           Machine-readable envelope: ok, status, headers, body.
+
+Examples:
+  $ assistant channels request slack /auth.test --json
+  $ assistant channels request slack -X POST \\
+      -d '{"channel":"D0123456789","limit":100}' /conversations.history --json
+  $ assistant channels request discord /users/@me --json`,
+    },
     {
       name: "list",
       description: "Show readiness state for every configured channel",

package/src/cli/commands/channels/index.ts

@@ -1,15 +1,19 @@
 /**
- * `assistant channels` — inspect messaging channels.
+ * `assistant channels`: inspect messaging channels, and act as their bots.
  *
- *   list                     — overview of every channel + ready state
- *   get <channel>            — detailed live snapshot of a single channel
+ *   list                     : overview of every channel + ready state
+ *   get <channel>            : detailed live snapshot of a single channel
+ *   request <channel> <url>  : call the channel's platform API as its bot
  *
  * `get` always re-runs remote probes (it invalidates the readiness cache
  * before reading), so the CLI answer matches the live source-of-truth.
  *
- * A mutating `refresh` verb (for reconnecting channels — e.g. supplying
- * fresh Slack tokens) is intentionally not shipped here; it will land in
- * its own PR.
+ * `request` is the bot-identity door (see ./request.ts): it resolves the
+ * channel's bot credential and makes the same authenticated request
+ * `oauth request` makes, without the caller naming a provider.
+ *
+ * A mutating `refresh` verb (for reconnecting channels, e.g. supplying
+ * fresh Slack tokens) is intentionally not part of this group.
  */
 
 import type { Command } from "commander";
@@ -21,6 +25,7 @@ import { registerCommand } from "../../lib/register-command.js";
 import { log } from "../../logger.js";
 import { shouldOutputJson, writeOutput } from "../../output.js";
 import { CHANNELS_PLUGIN_SEARCH_HINT, channelsHelp } from "./index.help.js";
+import { registerChannelsRequestCommand } from "./request.js";
 
 // ---------------------------------------------------------------------------
 // Snapshot shape
@@ -200,6 +205,12 @@ export function registerChannelsCommand(program: Command): void {
           }
         },
       );
+
+      // -----------------------------------------------------------------------
+      // request: call the channel's platform API as its bot
+      // -----------------------------------------------------------------------
+
+      registerChannelsRequestCommand(channels);
     },
   });
 }

package/src/cli/commands/channels/request.ts

@@ -0,0 +1,66 @@
+/**
+ * `assistant channels request`: call a channel's platform API as the
+ * assistant's own bot on that channel.
+ *
+ * This is the bot-identity door. A channel's bot credential (the token the
+ * setup wizard stored) and a person's OAuth integration for the same brand
+ * are different identities that reach different things, and the provider
+ * keys do not say which is which (`slack_channel` is the bot, `slack` is the
+ * person; `telegram` is the bot). Keying the request on the channel id
+ * resolves the bot credential through the one map that owns that fact,
+ * `CHANNEL_BOT_PROVIDER`, so a caller names the channel and never chooses a
+ * provider. Acting as the person is `oauth request`.
+ *
+ * The request itself is the same authenticated request `oauth request`
+ * makes: the route resolves the provider's connection and injects the
+ * credential, so no token is ever handled here. A channel this map does not
+ * name has no bot credential of its own (phone, vellum, platform) or is not
+ * built in, and the command says so rather than guessing a provider.
+ */
+
+import {
+  botProviderForChannel,
+  CHANNEL_BOT_PROVIDER,
+} from "@vellumai/service-contracts/channels";
+import type { Command } from "commander";
+
+import { subcommand } from "../../lib/cli-command-help.js";
+import { writeError } from "../../output.js";
+import {
+  attachRequestOptions,
+  type AuthenticatedRequestOptions,
+  runAuthenticatedRequest,
+} from "../oauth/request.js";
+import { CHANNELS_PLUGIN_SEARCH_HINT } from "./index.help.js";
+
+/** The channels whose bot credential this command can act with. */
+export const REQUESTABLE_CHANNELS: readonly string[] =
+  Object.keys(CHANNEL_BOT_PROVIDER);
+
+export function registerChannelsRequestCommand(channels: Command): void {
+  attachRequestOptions(subcommand(channels, "request")).action(
+    async (
+      channel: string,
+      url: string,
+      opts: AuthenticatedRequestOptions,
+      cmd: Command,
+    ) => {
+      const providerKey = botProviderForChannel(channel);
+      if (!providerKey) {
+        writeError(
+          cmd,
+          `Channel "${channel}" has no bot credential to request with. Channels with one: ${REQUESTABLE_CHANNELS.join(", ")}. ${CHANNELS_PLUGIN_SEARCH_HINT}`,
+        );
+        process.exitCode = 1;
+        return;
+      }
+      await runAuthenticatedRequest({
+        providerKey,
+        url,
+        opts,
+        diagnosticsHint: `For channel diagnostics, run 'assistant channels get ${channel}'.`,
+        cmd,
+      });
+    },
+  );
+}

package/src/cli/commands/oauth/request.test.ts

@@ -33,6 +33,8 @@ mock.module("../../../ipc/cli-client.js", () => ({
   exitFromIpcResult: (r: { error?: string }) => {
     throw new Error(r.error ?? "IPC error");
   },
+  exitCodeFromIpcResult: (r: { statusCode?: number }) =>
+    r.statusCode === undefined ? 10 : r.statusCode >= 500 ? 3 : 1,
 }));
 
 mock.module("../../../runtime/routes/oauth-commands-routes.js", () => ({