@vellumai/assistant 0.12.0 → 0.12.1-staging.1

package/src/cli/commands/apps.ts

@@ -1,8 +1,13 @@
 import type { Command } from "commander";
 
+import {
+  cliIpcCall,
+  exitCodeFromIpcResult,
+} from "../../ipc/cli-client.js";
 import { applyCommandHelp, subcommand } from "../lib/cli-command-help.js";
 import { registerCommand } from "../lib/register-command.js";
 import { log } from "../logger.js";
+import { shouldOutputJson, writeError, writeOutput } from "../output.js";
 import { appsHelp } from "./apps.help.js";
 
 interface AppListEntry {
@@ -10,6 +15,36 @@ interface AppListEntry {
   source: string;
 }
 
+interface AppsRefreshResponse {
+  ok: true;
+  appId: string;
+  name: string;
+  compiled: boolean;
+  compile_duration_ms: number;
+  compile_errors?: Array<{
+    text: string;
+    location?: { file: string; line: number; column: number };
+  }>;
+  compile_warnings?: Array<{
+    text: string;
+    location?: { file: string; line: number; column: number };
+  }>;
+}
+
+function refreshHint(appId: string): string {
+  return `Run 'assistant apps refresh ${appId}' to compile.`;
+}
+
+function formatDiagnostic(diag: {
+  text: string;
+  location?: { file: string; line: number; column: number };
+}): string {
+  if (!diag.location) {
+    return diag.text;
+  }
+  return `${diag.location.file}:${diag.location.line}: ${diag.text}`;
+}
+
 export function registerAppsCommand(program: Command): void {
   registerCommand(program, {
     name: appsHelp.name,
@@ -46,6 +81,154 @@ export function registerAppsCommand(program: Command): void {
           log.info(`  ${e.name.padEnd(nameWidth)}  ${e.source}`);
         }
       });
+
+      subcommand(apps, "inspect").action(
+        async (appName: string, opts: { json?: boolean }, cmd: Command) => {
+          const { resolveAppQuery, appNotFoundMessage, appAmbiguousMessage } =
+            await import("../../apps/resolve-app.js");
+          const { inspectAppSource } = await import(
+            "../../apps/source-fingerprint.js"
+          );
+
+          const resolved = resolveAppQuery(appName);
+          if (!resolved.ok) {
+            const message =
+              resolved.reason === "ambiguous"
+                ? appAmbiguousMessage(resolved.query, resolved.matches)
+                : appNotFoundMessage(resolved.query);
+            writeError(cmd, message);
+            process.exitCode = 1;
+            return;
+          }
+
+          const { app } = resolved;
+          const inspect = inspectAppSource(app.sourcePath);
+          const origin =
+            app.origin.kind === "plugin"
+              ? { kind: "plugin" as const, plugin: app.origin.pluginName }
+              : { kind: "workspace" as const };
+
+          if (opts.json || shouldOutputJson(cmd)) {
+            writeOutput(cmd, {
+              ok: true,
+              app: {
+                id: app.id,
+                name: app.name,
+                source: app.sourcePath,
+                origin,
+              },
+              compile: inspect,
+            });
+            return;
+          }
+
+          const originLabel =
+            origin.kind === "plugin"
+              ? `plugin ${origin.plugin}`
+              : "workspace";
+          log.info(`App: ${app.name} (${originLabel})`);
+          log.info(`Id: ${app.id}`);
+          log.info(`Source: ${app.sourcePath}`);
+
+          if (inspect.status === "clean") {
+            const when = inspect.compiledAt
+              ? ` (compiled ${inspect.compiledAt})`
+              : "";
+            log.info(`Compile: up to date${when}`);
+            return;
+          }
+          if (inspect.status === "never_compiled") {
+            log.info("Compile: never compiled");
+            log.info(refreshHint(app.id));
+            return;
+          }
+          if (inspect.status === "unknown_baseline") {
+            log.info(
+              "Compile: compiled, but no source fingerprint is recorded.",
+            );
+            log.info(
+              `Run 'assistant apps refresh ${app.id}' to record one and rebuild.`,
+            );
+            return;
+          }
+
+          const when = inspect.compiledAt
+            ? ` (last compiled ${inspect.compiledAt})`
+            : "";
+          log.info(`Compile: source changed since last compile${when}`);
+          if (inspect.modified.length > 0) {
+            log.info("Modified:");
+            for (const path of inspect.modified) {
+              log.info(`  ${path}`);
+            }
+          }
+          if (inspect.added.length > 0) {
+            log.info("Added:");
+            for (const path of inspect.added) {
+              log.info(`  ${path}`);
+            }
+          }
+          if (inspect.removed.length > 0) {
+            log.info("Removed:");
+            for (const path of inspect.removed) {
+              log.info(`  ${path}`);
+            }
+          }
+          log.info(refreshHint(app.id));
+        },
+      );
+
+      subcommand(apps, "refresh").action(
+        async (appName: string, opts: { json?: boolean }, cmd: Command) => {
+          const { resolveAppQuery, appNotFoundMessage, appAmbiguousMessage } =
+            await import("../../apps/resolve-app.js");
+
+          const resolved = resolveAppQuery(appName);
+          if (!resolved.ok) {
+            const message =
+              resolved.reason === "ambiguous"
+                ? appAmbiguousMessage(resolved.query, resolved.matches)
+                : appNotFoundMessage(resolved.query);
+            writeError(cmd, message);
+            process.exitCode = 1;
+            return;
+          }
+
+          const result = await cliIpcCall<AppsRefreshResponse>("apps_refresh", {
+            pathParams: { id: resolved.app.id },
+          });
+
+          if (!result.ok || !result.result) {
+            writeError(cmd, result.error ?? "Refresh failed");
+            process.exitCode = exitCodeFromIpcResult(result);
+            return;
+          }
+
+          const payload = result.result;
+          if (opts.json || shouldOutputJson(cmd)) {
+            writeOutput(cmd, payload);
+            if (!payload.compiled) {
+              process.exitCode = 1;
+            }
+            return;
+          }
+
+          if (!payload.compiled) {
+            log.error(
+              `Compile failed for "${payload.name}" (${payload.compile_duration_ms}ms).`,
+            );
+            for (const diag of payload.compile_errors ?? []) {
+              log.error(`  ${formatDiagnostic(diag)}`);
+            }
+            process.exitCode = 1;
+            return;
+          }
+
+          log.info(
+            `Compiled "${payload.name}" in ${payload.compile_duration_ms}ms.`,
+          );
+        },
+      );
     },
   });
 }

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

@@ -0,0 +1,218 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+// The command is a door onto the daemon's one send implementation, so what
+// matters is the request it hands the route and what it does with the
+// answer. IPC is stubbed to capture that request; the exit-code helper
+// stays real, so the tests assert the mapping that ships.
+
+const ipcCalls: Array<{
+  method: string;
+  params: Record<string, unknown>;
+  opts?: Record<string, unknown>;
+}> = [];
+let ipcResult: Record<string, unknown> = {
+  ok: true,
+  result: {
+    channel: "slack",
+    chatId: "C0123456789",
+    messageIds: ["1700000000.000100"],
+    lastMessageId: "1700000000.000100",
+    recordedIn: "conv-home",
+  },
+};
+
+const actualCliClient = await import("../../../../ipc/cli-client.js");
+mock.module("../../../../ipc/cli-client.js", () => ({
+  ...actualCliClient,
+  cliIpcCall: async (
+    method: string,
+    params: Record<string, unknown>,
+    opts?: Record<string, unknown>,
+  ) => {
+    ipcCalls.push({ method, params, ...(opts ? { opts } : {}) });
+    return ipcResult;
+  },
+}));
+
+// Imported after the mock is installed, so the command module under test
+// binds the stubbed IPC call rather than the real one.
+const { runCliCommand } = await import("../../__tests__/cli-test-harness.js");
+const { registerChannelsCommand } = await import("../index.js");
+
+beforeEach(() => {
+  ipcCalls.length = 0;
+  ipcResult = {
+    ok: true,
+    result: {
+      channel: "slack",
+      chatId: "C0123456789",
+      messageIds: ["1700000000.000100"],
+      lastMessageId: "1700000000.000100",
+      recordedIn: "conv-home",
+    },
+  };
+});
+
+// The shipped registration as-is: `send` declares its own `--json`, which is
+// why the program's global leaf-option pass skips it.
+function runSend(args: string[]) {
+  return runCliCommand(registerChannelsCommand, ["channels", "send", ...args]);
+}
+
+/** The body the command handed the route on its one call. */
+function sentBody(): Record<string, unknown> {
+  expect(ipcCalls).toHaveLength(1);
+  expect(ipcCalls[0]!.method).toBe("channels_send_post");
+  return ipcCalls[0]!.params.body as Record<string, unknown>;
+}
+
+describe("the request the command makes", () => {
+  test("names the chat and asks for the channel's rich rendering", async () => {
+    const r = await runSend([
+      "slack",
+      "C0123456789",
+      "--text",
+      "deploy is green",
+    ]);
+    expect(r.exitCode).toBe(0);
+    expect(sentBody()).toEqual({
+      channel: "slack",
+      target: { kind: "chat", chatId: "C0123456789" },
+      text: "deploy is green",
+      renderRichly: true,
+    });
+  });
+
+  test("carries a named thread as the target's thread", async () => {
+    await runSend([
+      "slack",
+      "C0123456789",
+      "--thread",
+      "1700000000.000001",
+      "--text",
+      "and the smoke tests passed",
+    ]);
+    expect(sentBody().target).toEqual({
+      kind: "chat",
+      chatId: "C0123456789",
+      threadId: "1700000000.000001",
+    });
+  });
+
+  test("--plain asks for the text verbatim", async () => {
+    await runSend(["telegram", "123456789", "--text", "morning", "--plain"]);
+    const body = sentBody();
+    expect(body.renderRichly).toBeUndefined();
+    expect(body.channel).toBe("telegram");
+  });
+
+  test("sends the text as the caller wrote it, whitespace included", async () => {
+    await runSend([
+      "slack",
+      "C0123456789",
+      "--text",
+      "  indented  ",
+      "--plain",
+    ]);
+    expect(sentBody().text).toBe("  indented  ");
+  });
+
+  test("waits longer than the IPC default, since the send itself retries", async () => {
+    await runSend(["slack", "C0123456789", "--text", "hi"]);
+    expect(ipcCalls[0]!.opts).toMatchObject({ timeoutMs: 120_000 });
+  });
+
+  test("refuses an empty text before it sends anything", async () => {
+    for (const args of [
+      ["slack", "C0123456789"],
+      ["slack", "C0123456789", "--text", "   "],
+    ]) {
+      ipcCalls.length = 0;
+      const r = await runSend(args);
+      expect(r.exitCode).toBe(1);
+      expect(r.stderr).toContain("--text is required");
+      expect(ipcCalls).toEqual([]);
+    }
+  });
+});
+
+describe("what the command reports", () => {
+  test("names where the post landed and the conversation it was recorded in", async () => {
+    const r = await runSend(["slack", "C0123456789", "--text", "hello"]);
+    expect(r.stdout).toContain("C0123456789");
+    expect(r.stdout).toContain("1700000000.000100");
+    expect(r.stdout).toContain("conv-home");
+  });
+
+  test("says so when the channel split the text", async () => {
+    ipcResult = {
+      ok: true,
+      result: {
+        channel: "telegram",
+        chatId: "123456789",
+        messageIds: ["10", "11", "12"],
+        lastMessageId: "12",
+      },
+    };
+    const r = await runSend(["telegram", "123456789", "--text", "a long one"]);
+    expect(r.stdout).toContain("3 posts");
+  });
+
+  test("--json answers with the route's own result", async () => {
+    const r = await runSend([
+      "slack",
+      "C0123456789",
+      "--text",
+      "hello",
+      "--json",
+    ]);
+    expect(JSON.parse(r.stdout)).toEqual({
+      channel: "slack",
+      chatId: "C0123456789",
+      messageIds: ["1700000000.000100"],
+      lastMessageId: "1700000000.000100",
+      recordedIn: "conv-home",
+    });
+  });
+
+  test("a refused send reports the route's reason and its exit code", async () => {
+    ipcResult = {
+      ok: false,
+      error: 'Channel "email" is not addressable',
+      statusCode: 400,
+    };
+    const r = await runSend(["email", "someone", "--text", "hello"]);
+    expect(r.exitCode).toBe(
+      actualCliClient.exitCodeFromIpcResult({ statusCode: 400 }),
+    );
+    expect(r.stderr).toContain("not addressable");
+  });
+
+  test("a timeout is reported as an unknown outcome, not a failure to retry", async () => {
+    ipcResult = { ok: false, error: "Request timed out", timedOut: true };
+    const r = await runSend(["slack", "C0123456789", "--text", "hello"]);
+    expect(r.stderr).toContain("may still be in flight");
+    expect(r.stderr).toContain("before sending again");
+    expect(r.stderr).not.toContain("The send failed");
+  });
+
+  test("a refusal in --json mode is a JSON error envelope", async () => {
+    ipcResult = {
+      ok: false,
+      error: 'Channel "slack" did not acknowledge the send',
+      statusCode: 502,
+    };
+    const r = await runSend([
+      "slack",
+      "C0123456789",
+      "--text",
+      "hello",
+      "--json",
+    ]);
+    expect(JSON.parse(r.stdout)).toEqual({
+      ok: false,
+      error: 'Channel "slack" did not acknowledge the send',
+    });
+    expect(r.exitCode).toBe(3);
+  });
+});

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

@@ -36,9 +36,14 @@ 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'.
 
+To say something in a chat, use 'send' rather than 'request': it goes
+through the channel's transport, so the post is threaded and rendered like
+every other message the assistant sends there, and it is recorded.
+
 Examples:
   $ assistant channels list
   $ assistant channels get slack
+  $ assistant channels send slack C0123456789 --text 'deploy is green'
   $ assistant channels request slack /auth.test --json
   $ assistant channels request slack -X POST \\
       -d '{"channel":"D0123456789","limit":20}' /conversations.history --json`,
@@ -65,8 +70,9 @@ 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.
+message, use 'assistant channels send', which posts through the channel's
+transport and records what it sent; a message posted through this command
+reaches the platform directly and leaves no record of what was said.
 
 Arguments:
   <channel>  One of: ${BOT_CHANNELS}. A channel with no bot credential of
@@ -86,6 +92,68 @@ Examples:
   $ assistant channels request slack -X POST \\
       -d '{"channel":"D0123456789","limit":100}' /conversations.history --json
   $ assistant channels request discord /users/@me --json`,
+    },
+    {
+      name: "send",
+      description:
+        "Post text to a chat on the channel, as the assistant's bot, recorded",
+      arguments: [
+        {
+          name: "<channel>",
+          description: `Channel to post on. One with a transport that can be addressed from a named chat; anything else is refused before the send.`,
+        },
+        {
+          name: "<chat-id>",
+          description:
+            "The chat in the channel's own id space (a Slack channel or DM id, a Telegram chat id, a Discord channel id, a WhatsApp number).",
+        },
+      ],
+      options: [
+        {
+          flags: "--text <text>",
+          description: "The message text. Required.",
+        },
+        {
+          flags: "--thread <id>",
+          description:
+            "Post inside this thread or topic, in the channel's own id space. Omit to post to the chat itself.",
+        },
+        {
+          flags: "--plain",
+          description:
+            "Send the text verbatim instead of the channel's rich rendering.",
+        },
+        {
+          flags: "--json",
+          description: "Machine-readable compact JSON output",
+        },
+      ],
+      helpText: `
+Posts one message through the channel's own transport, the same path a
+reply takes. Once the channel acknowledges it, the daemon records it in
+the chat's conversation, which is what lets the assistant see later what
+it said here and lets a reaction or an edit naming that post resolve back
+to it. Recording is best effort and never fails a send that already went
+out, so the result names the conversation only when the record was
+written.
+
+This sends a message people will read, so it is classified high risk and
+asks for approval like any other action with effects nobody can take back.
+
+The send fails, and records nothing, when the channel does not acknowledge
+it or names no message id for it. A channel the assistant cannot address
+from a named chat is refused before anything is sent. If the daemon does
+not answer in time, the message may still go out: that is reported as an
+unknown outcome rather than a failure, so check the chat before sending
+again.
+
+Attachments are not sent from here.
+
+Examples:
+  $ assistant channels send slack C0123456789 --text 'deploy is green'
+  $ assistant channels send slack C0123456789 --thread 1700000000.000100 \
+      --text 'and the smoke tests passed'
+  $ assistant channels send telegram 123456789 --text 'morning' --json`,
     },
     {
       name: "list",

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

@@ -1,9 +1,10 @@
 /**
  * `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
- *   request <channel> <url>  : call the channel's platform API as its bot
+ *   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
+ *   send <channel> <chat-id>      : post text to a chat, recorded
  *
  * `get` always re-runs remote probes (it invalidates the readiness cache
  * before reading), so the CLI answer matches the live source-of-truth.
@@ -12,6 +13,11 @@
  * channel's bot credential and makes the same authenticated request
  * `oauth request` makes, without the caller naming a provider.
  *
+ * `send` is the send door (see ./send.ts): it runs the daemon's one send
+ * implementation for the channel, so the post is threaded, rendered, and
+ * recorded like every other message the assistant sends there. Posting
+ * through `request` instead reaches the platform API and leaves no record.
+ *
  * A mutating `refresh` verb (for reconnecting channels, e.g. supplying
  * fresh Slack tokens) is intentionally not part of this group.
  */
@@ -26,6 +32,7 @@ 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";
+import { registerChannelsSendCommand } from "./send.js";
 
 // ---------------------------------------------------------------------------
 // Snapshot shape
@@ -211,6 +218,12 @@ export function registerChannelsCommand(program: Command): void {
       // -----------------------------------------------------------------------
 
       registerChannelsRequestCommand(channels);
+
+      // -----------------------------------------------------------------------
+      // send: post text to a chat, through the channel's transport
+      // -----------------------------------------------------------------------
+
+      registerChannelsSendCommand(channels);
     },
   });
 }

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

@@ -0,0 +1,128 @@
+/**
+ * `assistant channels send`: post text to a chat on a channel, as the
+ * assistant's own bot.
+ *
+ * The send door. It runs the daemon function the messaging tool runs
+ * (`sendChannelText`, over `POST /v1/channels/send`), so a send from the
+ * command line reaches the chat through the channel's transport and leaves
+ * the same record: threaded where a thread is named, rendered the way the
+ * channel renders a reply, and written to the chat's conversation only once
+ * the channel has acknowledged it.
+ *
+ * Posting the same text through `channels request` reaches the platform API
+ * directly and leaves no record of what was said, which is why this command
+ * exists beside it. Both act as the bot and both carry the same rating: the
+ * effect is a message either way.
+ *
+ * A channel whose transport cannot be addressed from a named chat is
+ * refused by the route before anything is sent.
+ */
+
+import type { Command } from "commander";
+
+import { cliIpcCall, exitCodeFromIpcResult } from "../../../ipc/cli-client.js";
+import { subcommand } from "../../lib/cli-command-help.js";
+import { log } from "../../logger.js";
+import { shouldOutputJson, writeError, writeOutput } from "../../output.js";
+
+/** What the channel acknowledged, and where the post was recorded. */
+interface ChannelSendResponse {
+  channel: string;
+  chatId: string;
+  threadId?: string;
+  messageIds: string[];
+  lastMessageId: string;
+  recordedIn?: string;
+}
+
+interface ChannelSendOptions {
+  text?: string;
+  thread?: string;
+  plain?: boolean;
+}
+
+/**
+ * How long to wait for the daemon before giving up on an answer.
+ *
+ * Longer than the IPC default because the work behind this call is a
+ * platform request that retries: a rate-limited Slack send sleeps for the
+ * `Retry-After` Slack names and tries again up to three times
+ * (`MAX_RATE_LIMIT_RETRIES`, providers/slack/web-api-transport.ts), and the
+ * other channels back off similarly. Waiting past that is better than
+ * abandoning a send that is still being made, because giving up tells the
+ * caller nothing about whether the message went out.
+ */
+const SEND_CALL_TIMEOUT_MS = 120_000;
+
+export function registerChannelsSendCommand(channels: Command): void {
+  subcommand(channels, "send").action(
+    async (
+      channel: string,
+      chatId: string,
+      opts: ChannelSendOptions,
+      cmd: Command,
+    ) => {
+      // Trimmed only to reject a blank message: the text goes out as the
+      // caller wrote it, which `--plain` in particular promises.
+      const text = opts.text;
+      if (!text?.trim()) {
+        writeError(cmd, "--text is required and cannot be empty.");
+        process.exitCode = 1;
+        return;
+      }
+
+      const threadId = opts.thread?.trim();
+      const r = await cliIpcCall<ChannelSendResponse>(
+        "channels_send_post",
+        {
+          body: {
+            channel,
+            target: {
+              kind: "chat",
+              chatId,
+              ...(threadId ? { threadId } : {}),
+            },
+            text,
+            // Rich unless asked otherwise, so a send from here reads like
+            // the assistant's other posts in that chat rather than like a
+            // different sender.
+            ...(opts.plain ? {} : { renderRichly: true }),
+          },
+        },
+        { timeoutMs: SEND_CALL_TIMEOUT_MS },
+      );
+      if (!r.ok) {
+        // A timeout is not a failure: closing the client socket does not
+        // stop the daemon, so the message may still go out. Saying so is
+        // what keeps a retry from posting it twice.
+        const message = r.timedOut
+          ? `The daemon did not answer within ${Math.round(SEND_CALL_TIMEOUT_MS / 1000)}s. The send may still be in flight, so it may or may not have gone out. Check the chat before sending again.`
+          : (r.error ?? "The send failed.");
+        // Reported rather than exited, so `--json` gets an error envelope
+        // like every other answer this command gives.
+        writeError(cmd, message);
+        process.exitCode = exitCodeFromIpcResult({
+          statusCode: r.statusCode,
+        });
+        return;
+      }
+
+      const sent = r.result!;
+      if (shouldOutputJson(cmd)) {
+        writeOutput(cmd, sent);
+        return;
+      }
+
+      const where = sent.threadId
+        ? `${sent.chatId}, thread ${sent.threadId}`
+        : sent.chatId;
+      log.info(`Sent to ${channel} ${where} (id: ${sent.lastMessageId})`);
+      if (sent.messageIds.length > 1) {
+        log.info(`The channel split it into ${sent.messageIds.length} posts`);
+      }
+      if (sent.recordedIn) {
+        log.info(`Recorded in conversation ${sent.recordedIn}`);
+      }
+    },
+  );
+}