@vellumai/assistant 0.10.8 → 0.10.9-dev.202607152225.ec6fdbf

package/src/cli/commands/usage.help.ts

@@ -0,0 +1,147 @@
+/** Declarative help for the `assistant usage` command. */
+
+import type { CliCommandHelp } from "../lib/cli-command-help.js";
+
+export const usageHelp: CliCommandHelp = {
+  name: "usage",
+  description: "Query LLM token usage and cost data",
+  helpText: `
+Queries LLM usage event data via the daemon to display token consumption
+and cost data. Requires the assistant to be running.
+
+Time range can be specified with --range presets (today, week, month, all)
+or explicit --from / --to epoch-millisecond timestamps.
+
+Examples:
+  $ assistant usage totals
+  $ assistant usage daily --range week
+  $ assistant usage breakdown --group-by provider
+  $ assistant usage totals --range all --json`,
+  subcommands: [
+    {
+      name: "totals",
+      isDefault: true,
+      description: "Aggregate totals for a time range",
+      options: [
+        {
+          flags: "-r, --range <preset>",
+          description: "Time range preset: today, week, month, all",
+          defaultValue: "today",
+        },
+        {
+          flags: "--from <epoch_ms>",
+          description: "Start of range (epoch ms)",
+        },
+        { flags: "--to <epoch_ms>", description: "End of range (epoch ms)" },
+        {
+          flags: "--schedule <id>",
+          description:
+            "Filter to a schedule id — run 'assistant schedules list' to find it; attributes usage by that schedule's cron run windows",
+        },
+        { flags: "--json", description: "Output raw JSON" },
+      ],
+      helpText: `
+Shows aggregate token counts and estimated cost across all LLM calls
+within the time range.
+
+Columns: estimated cost, LLM call count, input/output tokens, cache
+creation/read tokens, unpriced event count (if any).
+
+Pass --schedule <id> to restrict totals to a single schedule's cron run
+windows. Find schedule ids with 'assistant schedules list'.
+
+Examples:
+  $ assistant usage totals
+  $ assistant usage totals --range all
+  $ assistant usage totals --schedule sched-abc123
+  $ assistant usage totals --from 1709856000000 --to 1709942400000`,
+    },
+    {
+      name: "daily",
+      description: "Per-day token and cost breakdown",
+      options: [
+        {
+          flags: "-r, --range <preset>",
+          description: "Time range preset: today, week, month, all",
+          defaultValue: "today",
+        },
+        {
+          flags: "--from <epoch_ms>",
+          description: "Start of range (epoch ms)",
+        },
+        { flags: "--to <epoch_ms>", description: "End of range (epoch ms)" },
+        {
+          flags: "--schedule <id>",
+          description:
+            "Filter to a schedule id — run 'assistant schedules list' to find it; attributes usage by that schedule's cron run windows",
+        },
+        { flags: "--json", description: "Output raw JSON" },
+      ],
+      helpText: `
+Shows one row per day (UTC) with input tokens, output tokens, estimated
+cost, and LLM call count.
+
+Pass --schedule <id> to restrict the breakdown to a single schedule's cron
+run windows. Find schedule ids with 'assistant schedules list'.
+
+Examples:
+  $ assistant usage daily
+  $ assistant usage daily --range week
+  $ assistant usage daily --schedule sched-abc123
+  $ assistant usage daily --range month --json`,
+    },
+    {
+      name: "breakdown",
+      description:
+        "Grouped breakdown by task, profile, provider, model, or conversation",
+      options: [
+        {
+          flags: "-r, --range <preset>",
+          description: "Time range preset: today, week, month, all",
+          defaultValue: "today",
+        },
+        {
+          flags: "--from <epoch_ms>",
+          description: "Start of range (epoch ms)",
+        },
+        { flags: "--to <epoch_ms>", description: "End of range (epoch ms)" },
+        {
+          flags: "--schedule <id>",
+          description:
+            "Filter to a schedule id — run 'assistant schedules list' to find it; attributes usage by that schedule's cron run windows",
+        },
+        { flags: "--json", description: "Output raw JSON" },
+        {
+          flags: "-g, --group-by <dimension>",
+          description:
+            "Grouping dimension: call_site, inference_profile, provider, model, conversation, actor",
+          defaultValue: "model",
+        },
+      ],
+      helpText: `
+Grouping dimensions:
+  call_site          Groups by user-facing task (Main Agent, Memory Extraction,
+                     Conversation Title, etc.)
+  inference_profile  Groups by inference profile; unset historical rows are
+                     shown as Default / Unset
+  provider           Groups by LLM provider (anthropic, openai, etc.)
+  model              Groups by model name (claude-sonnet-4-20250514, etc.)
+  conversation       Groups by conversation ID
+  actor              Legacy/internal subsystem grouping (main_agent, etc.)
+
+Shows one row per group with input/output tokens, estimated cost, and
+call count. Rows are sorted by cost descending.
+
+Pass --schedule <id> to restrict the breakdown to a single schedule's cron
+run windows. Find schedule ids with 'assistant schedules list'.
+
+Examples:
+  $ assistant usage breakdown
+  $ assistant usage breakdown --group-by call_site
+  $ assistant usage breakdown --group-by inference_profile
+  $ assistant usage breakdown --group-by provider
+  $ assistant usage breakdown --schedule sched-abc123
+  $ assistant usage breakdown --group-by actor --range week`,
+    },
+  ],
+};

package/src/cli/commands/usage.ts

@@ -1,9 +1,11 @@
 import type { Command } from "commander";
 
 import { cliIpcCall, exitFromIpcResult } from "../../ipc/cli-client.js";
+import { applyCommandHelp, subcommand } from "../lib/cli-command-help.js";
 import { formatCostUsd } from "../lib/cli-output.js";
 import { registerCommand } from "../lib/register-command.js";
 import { log } from "../logger.js";
+import { usageHelp } from "./usage.help.js";
 
 // ── Formatting helpers ───────────────────────────────────────────
 
@@ -204,218 +206,97 @@ const VALID_GROUP_BY_DIMENSIONS = [
 
 export function registerUsageCommand(program: Command): void {
   registerCommand(program, {
-    name: "usage",
+    name: usageHelp.name,
     transport: "ipc",
-    description: "Query LLM token usage and cost data",
+    description: usageHelp.description,
     build: (usage) => {
-      usage.addHelpText(
-        "after",
-        `
-Queries LLM usage event data via the daemon to display token consumption
-and cost data. Requires the assistant to be running.
-
-Time range can be specified with --range presets (today, week, month, all)
-or explicit --from / --to epoch-millisecond timestamps.
-
-Examples:
-  $ assistant usage totals
-  $ assistant usage daily --range week
-  $ assistant usage breakdown --group-by provider
-  $ assistant usage totals --range all --json`,
+      applyCommandHelp(usage, usageHelp);
+
+      subcommand(usage, "totals").action(
+        async (opts: {
+          range: string;
+          from?: string;
+          to?: string;
+          schedule?: string;
+          json?: boolean;
+        }) => {
+          const { from, to } = resolveRange(opts);
+          const response = await cliIpcCall<UsageTotals>("usage_totals", {
+            queryParams: buildUsageQueryParams(from, to, opts.schedule),
+          });
+          if (!response.ok) {
+            return exitFromIpcResult(response);
+          }
+          const totals = response.result!;
+          if (opts.json) {
+            log.info(JSON.stringify(totals, null, 2));
+          } else {
+            printTotalsTable(totals);
+          }
+        },
       );
 
-      const rangeOption = [
-        "-r, --range <preset>",
-        "Time range preset: today, week, month, all",
-        "today",
-      ] as const;
-      const fromOption = [
-        "--from <epoch_ms>",
-        "Start of range (epoch ms)",
-      ] as const;
-      const toOption = ["--to <epoch_ms>", "End of range (epoch ms)"] as const;
-      const jsonOption = ["--json", "Output raw JSON"] as const;
-      const scheduleOption = [
-        "--schedule <id>",
-        "Filter to a schedule id — run 'assistant schedules list' to find it; attributes usage by that schedule's cron run windows",
-      ] as const;
-
-      usage
-        .command("totals", { isDefault: true })
-        .description("Aggregate totals for a time range")
-        .option(...rangeOption)
-        .option(...fromOption)
-        .option(...toOption)
-        .option(...scheduleOption)
-        .option(...jsonOption)
-        .addHelpText(
-          "after",
-          `
-Shows aggregate token counts and estimated cost across all LLM calls
-within the time range.
-
-Columns: estimated cost, LLM call count, input/output tokens, cache
-creation/read tokens, unpriced event count (if any).
-
-Pass --schedule <id> to restrict totals to a single schedule's cron run
-windows. Find schedule ids with 'assistant schedules list'.
-
-Examples:
-  $ assistant usage totals
-  $ assistant usage totals --range all
-  $ assistant usage totals --schedule sched-abc123
-  $ assistant usage totals --from 1709856000000 --to 1709942400000`,
-        )
-        .action(
-          async (opts: {
-            range: string;
-            from?: string;
-            to?: string;
-            schedule?: string;
-            json?: boolean;
-          }) => {
-            const { from, to } = resolveRange(opts);
-            const response = await cliIpcCall<UsageTotals>("usage_totals", {
-              queryParams: buildUsageQueryParams(from, to, opts.schedule),
-            });
-            if (!response.ok) {
-              return exitFromIpcResult(response);
-            }
-            const totals = response.result!;
-            if (opts.json) {
-              log.info(JSON.stringify(totals, null, 2));
-            } else {
-              printTotalsTable(totals);
-            }
-          },
-        );
-
-      usage
-        .command("daily")
-        .description("Per-day token and cost breakdown")
-        .option(...rangeOption)
-        .option(...fromOption)
-        .option(...toOption)
-        .option(...scheduleOption)
-        .option(...jsonOption)
-        .addHelpText(
-          "after",
-          `
-Shows one row per day (UTC) with input tokens, output tokens, estimated
-cost, and LLM call count.
-
-Pass --schedule <id> to restrict the breakdown to a single schedule's cron
-run windows. Find schedule ids with 'assistant schedules list'.
+      subcommand(usage, "daily").action(
+        async (opts: {
+          range: string;
+          from?: string;
+          to?: string;
+          schedule?: string;
+          json?: boolean;
+        }) => {
+          const { from, to } = resolveRange(opts);
+          const response = await cliIpcCall<{ buckets: UsageDayBucket[] }>(
+            "usage_daily",
+            { queryParams: buildUsageQueryParams(from, to, opts.schedule) },
+          );
+          if (!response.ok) {
+            return exitFromIpcResult(response);
+          }
+          const { buckets } = response.result!;
+          if (opts.json) {
+            log.info(JSON.stringify({ buckets }, null, 2));
+          } else {
+            printDailyTable(buckets);
+          }
+        },
+      );
 
-Examples:
-  $ assistant usage daily
-  $ assistant usage daily --range week
-  $ assistant usage daily --schedule sched-abc123
-  $ assistant usage daily --range month --json`,
-        )
-        .action(
-          async (opts: {
-            range: string;
-            from?: string;
-            to?: string;
-            schedule?: string;
-            json?: boolean;
-          }) => {
-            const { from, to } = resolveRange(opts);
-            const response = await cliIpcCall<{ buckets: UsageDayBucket[] }>(
-              "usage_daily",
-              { queryParams: buildUsageQueryParams(from, to, opts.schedule) },
+      subcommand(usage, "breakdown").action(
+        async (opts: {
+          range: string;
+          from?: string;
+          to?: string;
+          schedule?: string;
+          json?: boolean;
+          groupBy: string;
+        }) => {
+          const validDimensions = new Set<string>(VALID_GROUP_BY_DIMENSIONS);
+          if (!validDimensions.has(opts.groupBy)) {
+            log.error(
+              `Invalid --group-by value: '${opts.groupBy}'. Must be one of: ${VALID_GROUP_BY_DIMENSIONS.join(", ")}`,
             );
-            if (!response.ok) {
-              return exitFromIpcResult(response);
-            }
-            const { buckets } = response.result!;
-            if (opts.json) {
-              log.info(JSON.stringify({ buckets }, null, 2));
-            } else {
-              printDailyTable(buckets);
-            }
-          },
-        );
-
-      usage
-        .command("breakdown")
-        .description(
-          "Grouped breakdown by task, profile, provider, model, or conversation",
-        )
-        .option(...rangeOption)
-        .option(...fromOption)
-        .option(...toOption)
-        .option(...scheduleOption)
-        .option(...jsonOption)
-        .option(
-          "-g, --group-by <dimension>",
-          "Grouping dimension: call_site, inference_profile, provider, model, conversation, actor",
-          "model",
-        )
-        .addHelpText(
-          "after",
-          `
-Grouping dimensions:
-  call_site          Groups by user-facing task (Main Agent, Memory Extraction,
-                     Conversation Title, etc.)
-  inference_profile  Groups by inference profile; unset historical rows are
-                     shown as Default / Unset
-  provider           Groups by LLM provider (anthropic, openai, etc.)
-  model              Groups by model name (claude-sonnet-4-20250514, etc.)
-  conversation       Groups by conversation ID
-  actor              Legacy/internal subsystem grouping (main_agent, etc.)
-
-Shows one row per group with input/output tokens, estimated cost, and
-call count. Rows are sorted by cost descending.
-
-Pass --schedule <id> to restrict the breakdown to a single schedule's cron
-run windows. Find schedule ids with 'assistant schedules list'.
-
-Examples:
-  $ assistant usage breakdown
-  $ assistant usage breakdown --group-by call_site
-  $ assistant usage breakdown --group-by inference_profile
-  $ assistant usage breakdown --group-by provider
-  $ assistant usage breakdown --schedule sched-abc123
-  $ assistant usage breakdown --group-by actor --range week`,
-        )
-        .action(
-          async (opts: {
-            range: string;
-            from?: string;
-            to?: string;
-            schedule?: string;
-            json?: boolean;
-            groupBy: string;
-          }) => {
-            const validDimensions = new Set<string>(VALID_GROUP_BY_DIMENSIONS);
-            if (!validDimensions.has(opts.groupBy)) {
-              log.error(
-                `Invalid --group-by value: '${opts.groupBy}'. Must be one of: ${VALID_GROUP_BY_DIMENSIONS.join(", ")}`,
-              );
-              process.exit(1);
-            }
-            const { from, to } = resolveRange(opts);
-            const response = await cliIpcCall<{
-              breakdown: UsageGroupBreakdown[];
-            }>("usage_breakdown", {
-              queryParams: {
-                ...buildUsageQueryParams(from, to, opts.schedule),
-                groupBy: opts.groupBy,
-              },
-            });
-            if (!response.ok) {
-              return exitFromIpcResult(response);
-            }
-            const { breakdown } = response.result!;
-            if (opts.json) {
-              log.info(JSON.stringify({ breakdown }, null, 2));
-            } else {
-              printBreakdownTable(breakdown, opts.groupBy);
-            }
-          },
-        );
+            process.exit(1);
+          }
+          const { from, to } = resolveRange(opts);
+          const response = await cliIpcCall<{
+            breakdown: UsageGroupBreakdown[];
+          }>("usage_breakdown", {
+            queryParams: {
+              ...buildUsageQueryParams(from, to, opts.schedule),
+              groupBy: opts.groupBy,
+            },
+          });
+          if (!response.ok) {
+            return exitFromIpcResult(response);
+          }
+          const { breakdown } = response.result!;
+          if (opts.json) {
+            log.info(JSON.stringify({ breakdown }, null, 2));
+          } else {
+            printBreakdownTable(breakdown, opts.groupBy);
+          }
+        },
+      );
     },
   });
 }

package/src/cli/commands/watchers.help.ts

@@ -0,0 +1,211 @@
+/** Declarative help for the `assistant watchers` command. */
+
+import type { CliCommandHelp } from "../lib/cli-command-help.js";
+
+export const watchersHelp: CliCommandHelp = {
+  name: "watchers",
+  description: "Manage polling watchers that monitor external services",
+  helpText: `
+Watchers poll external services (Gmail, Google Calendar, GitHub, Linear,
+Outlook) on a configurable interval and process detected events via an
+action prompt sent to a background conversation. Each watcher targets a
+single provider and is identified by a UUID returned at creation time.
+
+Watchers can be paused/resumed with --enabled/--disabled on update, and
+recent activity is available via the digest subcommand.
+
+Examples:
+  $ assistant watchers create --name "My Gmail" --provider gmail --action-prompt "Summarize new emails"
+  $ assistant watchers list
+  $ assistant watchers list --id <watcherId>
+  $ assistant watchers digest --hours 8`,
+  subcommands: [
+    {
+      name: "list",
+      description: "List all watchers or show details for a specific watcher",
+      options: [
+        {
+          flags: "--id <watcherId>",
+          description:
+            "Show details for a specific watcher — run 'assistant watchers list' to find IDs",
+        },
+        { flags: "--enabled-only", description: "Only show enabled watchers" },
+        {
+          flags: "--json",
+          description: "Output result as machine-readable JSON",
+        },
+      ],
+      helpText: `
+Arguments:
+  --id <watcherId>   UUID of the watcher to inspect. Omit to list all
+                     watchers. Run 'assistant watchers list' to discover IDs.
+  --enabled-only     Filter to only enabled watchers.
+
+When --id is provided, returns detailed info including the watcher's
+configuration and its most recent events. Without --id, returns a
+summary table of all watchers.
+
+Examples:
+  $ assistant watchers list
+  $ assistant watchers list --enabled-only
+  $ assistant watchers list --id abc123-def4-5678-abcd-ef1234567890
+  $ assistant watchers list --json`,
+    },
+    {
+      name: "create",
+      description: "Create a new watcher",
+      options: [
+        { flags: "--name <name>", description: "Watcher name", required: true },
+        {
+          flags: "--provider <provider>",
+          description:
+            "Provider ID (gmail, google-calendar, github, linear, outlook, outlook-calendar)",
+          required: true,
+        },
+        {
+          flags: "--action-prompt <prompt>",
+          description: "Action prompt for the watcher",
+          required: true,
+        },
+        {
+          flags: "--poll-interval <ms>",
+          description:
+            "Poll interval in milliseconds (default: 60000, min: 15000)",
+        },
+        {
+          flags: "--config <json>",
+          description: "Provider-specific config as JSON string",
+        },
+        {
+          flags: "--credential-service <service>",
+          description: "Credential service override",
+        },
+        {
+          flags: "--json",
+          description: "Output result as machine-readable JSON",
+        },
+      ],
+      helpText: `
+Arguments:
+  --name <name>                Human-readable label (e.g. "Work Gmail")
+  --provider <provider>        Service to poll: gmail, google-calendar, github,
+                               linear, outlook, outlook-calendar
+  --action-prompt <prompt>     LLM instructions for processing detected events.
+                               Sent with event data to a background conversation.
+  --poll-interval <ms>         Milliseconds between polls. Default 60000 (1 min),
+                               minimum 15000 (15 sec).
+  --config <json>              Provider-specific settings as a JSON string.
+  --credential-service <svc>   Override the default credential service for the
+                               provider. Rarely needed.
+
+The watcher starts polling immediately after creation. Each provider
+requires appropriate OAuth credentials to be configured beforehand.
+
+Examples:
+  $ assistant watchers create --name "My Gmail" --provider gmail --action-prompt "Summarize new emails and notify me if anything is urgent"
+  $ assistant watchers create --name "PR Reviews" --provider github --action-prompt "Notify me of new review requests" --poll-interval 30000
+  $ assistant watchers create --name "Team Linear" --provider linear --action-prompt "Flag high-priority issues" --config '{"teamId":"TEAM-1"}'`,
+    },
+    {
+      name: "update",
+      args: "<watcherId>",
+      description: "Update an existing watcher",
+      options: [
+        { flags: "--name <name>", description: "New watcher name" },
+        {
+          flags: "--action-prompt <prompt>",
+          description: "New action prompt",
+        },
+        {
+          flags: "--poll-interval <ms>",
+          description: "New poll interval in milliseconds (min: 15000)",
+        },
+        { flags: "--enabled", description: "Enable the watcher" },
+        { flags: "--disabled", description: "Disable the watcher" },
+        {
+          flags: "--config <json>",
+          description: "New provider-specific config as JSON string",
+        },
+        {
+          flags: "--json",
+          description: "Output result as machine-readable JSON",
+        },
+      ],
+      helpText: `
+Arguments:
+  watcherId              UUID of the watcher to update — run 'assistant
+                         watchers list' to find IDs.
+
+Only the fields you specify are changed; omitted fields keep their
+current values. Use --enabled/--disabled to pause and resume polling
+without deleting the watcher.
+
+Examples:
+  $ assistant watchers update abc123 --action-prompt "Flag urgent emails and ignore newsletters"
+  $ assistant watchers update abc123 --disabled
+  $ assistant watchers update abc123 --enabled --poll-interval 120000`,
+    },
+    {
+      name: "delete",
+      args: "<watcherId>",
+      description: "Delete a watcher and all its event history",
+      options: [
+        {
+          flags: "--json",
+          description: "Output result as machine-readable JSON",
+        },
+      ],
+      helpText: `
+Arguments:
+  watcherId   UUID of the watcher to delete — run 'assistant watchers list'
+              to find IDs.
+
+Permanently removes the watcher and all its stored event history. This
+action is irreversible. Disable the watcher with 'assistant watchers
+update <id> --disabled' if you want to pause it instead.
+
+Examples:
+  $ assistant watchers delete abc123-def4-5678-abcd-ef1234567890
+  $ assistant watchers delete abc123 --json`,
+    },
+    {
+      name: "digest",
+      description: "Show recent watcher events grouped by watcher",
+      options: [
+        {
+          flags: "--id <watcherId>",
+          description:
+            "Filter to a single watcher — run 'assistant watchers list' to find IDs",
+        },
+        {
+          flags: "--hours <n>",
+          description: "Hours to look back (default: 24)",
+        },
+        {
+          flags: "--limit <n>",
+          description: "Maximum events to return (default: 50)",
+        },
+        {
+          flags: "--json",
+          description: "Output result as machine-readable JSON",
+        },
+      ],
+      helpText: `
+Arguments:
+  --id <watcherId>   UUID of a watcher to filter by. Omit to show events
+                     from all watchers. Run 'assistant watchers list' to
+                     discover IDs.
+  --hours <n>        Lookback window in hours. Defaults to 24.
+  --limit <n>        Maximum number of events returned. Defaults to 50.
+
+Events are grouped by watcher and sorted by creation time (newest first).
+Use this to review what your watchers have detected recently.
+
+Examples:
+  $ assistant watchers digest
+  $ assistant watchers digest --hours 8
+  $ assistant watchers digest --id abc123 --hours 4 --limit 10
+  $ assistant watchers digest --json`,
+    },
+  ],
+};