@vellumai/assistant 0.4.42 → 0.4.43

package/src/cli/commands/channel-verification-sessions.ts

@@ -0,0 +1,442 @@
+import type { Command } from "commander";
+
+import {
+  CHANNEL_IDS,
+  type ChannelId,
+  isChannelId,
+} from "../../channels/types.js";
+import {
+  createInboundChallenge,
+  getVerificationStatus,
+  revokeVerificationForChannel,
+  verifyTrustedContact,
+} from "../../daemon/handlers/config-channels.js";
+import { DAEMON_INTERNAL_ASSISTANT_ID } from "../../runtime/assistant-scope.js";
+import { revokePendingSessions } from "../../runtime/channel-verification-service.js";
+import {
+  cancelOutbound,
+  normalizeTelegramDestination,
+  resendOutbound,
+  startOutbound,
+} from "../../runtime/verification-outbound-actions.js";
+import { verificationRateLimiter } from "../../runtime/verification-rate-limiter.js";
+import { normalizePhoneNumber } from "../../util/phone.js";
+import { initializeDb } from "../db.js";
+import { writeOutput } from "../output.js";
+
+/**
+ * Validate the --channel option. Returns the validated ChannelId or writes an
+ * error and returns `false`. When `required` is false an absent value is fine
+ * (returns `undefined`).
+ */
+function validateChannelOpt(
+  raw: string | undefined,
+  cmd: Command,
+  required: true,
+): ChannelId | false;
+function validateChannelOpt(
+  raw: string | undefined,
+  cmd: Command,
+  required?: false,
+): ChannelId | undefined | false;
+function validateChannelOpt(
+  raw: string | undefined,
+  cmd: Command,
+  required?: boolean,
+): ChannelId | undefined | false {
+  if (raw === undefined) {
+    if (required) {
+      writeOutput(cmd, {
+        ok: false,
+        error: `The "channel" option is required. Valid values: ${CHANNEL_IDS.join(", ")}`,
+      });
+      process.exitCode = 1;
+      return false;
+    }
+    return undefined;
+  }
+  if (!isChannelId(raw)) {
+    writeOutput(cmd, {
+      ok: false,
+      error: `Invalid channel "${raw}". Valid values: ${CHANNEL_IDS.join(", ")}`,
+    });
+    process.exitCode = 1;
+    return false;
+  }
+  return raw;
+}
+
+export function registerChannelVerificationSessionsCommand(
+  program: Command,
+): void {
+  const cvs = program
+    .command("channel-verification-sessions")
+    .description("Manage channel verification sessions")
+    .option("--json", "Machine-readable compact JSON output");
+
+  cvs.addHelpText(
+    "after",
+    `
+Verification sessions are used to verify guardian bindings and trusted
+contacts across channels (telegram, phone, slack). Three flows exist:
+
+  1. Inbound challenge — the assistant generates a secret code and waits
+     for the guardian to send it back on the channel. Used when the
+     guardian can already message the assistant.
+
+  2. Outbound verification — the assistant sends a verification code to
+     a destination (Telegram handle, phone number, Slack user ID) and
+     waits for confirmation. Used when bootstrapping a new channel.
+
+  3. Trusted contact verification — verifies a contact channel that
+     already exists in the contact graph, sending a code to the channel
+     address on file.
+
+Examples:
+  $ assistant channel-verification-sessions create --channel telegram
+  $ assistant channel-verification-sessions create --channel phone --destination "+15551234567"
+  $ assistant channel-verification-sessions create --purpose trusted_contact --contact-channel-id abc-123
+  $ assistant channel-verification-sessions status --channel telegram`,
+  );
+
+  // ---------------------------------------------------------------------------
+  // create
+  // ---------------------------------------------------------------------------
+
+  cvs
+    .command("create")
+    .description("Create a new verification session")
+    .option("--channel <channel>", "Channel type (telegram, phone, slack)")
+    .option(
+      "--destination <destination>",
+      "Destination address for outbound verification (handle, phone number, or user ID)",
+    )
+    .option("--rebind", "Replace existing guardian binding")
+    .option("--session-id <sessionId>", "Session ID for inbound challenges")
+    .option(
+      "--origin-conversation-id <id>",
+      "Origin conversation ID for routing",
+    )
+    .option(
+      "--purpose <purpose>",
+      'Verification purpose: "guardian" (default) or "trusted_contact"',
+    )
+    .option(
+      "--contact-channel-id <id>",
+      "Contact channel ID (required when purpose is trusted_contact)",
+    )
+    .addHelpText(
+      "after",
+      `
+Routes between three creation modes based on the provided options:
+
+  1. Trusted contact: --purpose trusted_contact --contact-channel-id <id>
+     Verifies an existing contact channel. Sends a verification code to
+     the channel address on file.
+
+  2. Outbound: --channel <ch> --destination <dest>
+     Sends a verification code to the given destination. Supports telegram
+     (handle or chat ID), phone (E.164 number), and slack (user ID).
+     Use --rebind to replace an existing guardian binding.
+
+  3. Inbound: --channel <ch> (no --destination)
+     Generates a challenge secret for the guardian to send back on the
+     channel. Defaults to telegram if --channel is omitted.
+
+Examples:
+  $ assistant channel-verification-sessions create --purpose trusted_contact --contact-channel-id abc-123
+  $ assistant channel-verification-sessions create --channel telegram --destination "@guardian_handle"
+  $ assistant channel-verification-sessions create --channel phone --destination "+15551234567" --rebind
+  $ assistant channel-verification-sessions create --channel telegram --session-id sess-123`,
+    )
+    .action(
+      async (
+        opts: {
+          channel?: string;
+          destination?: string;
+          rebind?: boolean;
+          sessionId?: string;
+          originConversationId?: string;
+          purpose?: string;
+          contactChannelId?: string;
+        },
+        cmd: Command,
+      ) => {
+        try {
+          initializeDb();
+
+          const purpose = opts.purpose ?? "guardian";
+          const channel = validateChannelOpt(opts.channel, cmd);
+          if (channel === false) return;
+
+          // --- Trusted contact path ---
+          if (purpose === "trusted_contact") {
+            if (!opts.contactChannelId) {
+              writeOutput(cmd, {
+                ok: false,
+                error:
+                  "contactChannelId is required for trusted_contact purpose",
+              });
+              process.exitCode = 1;
+              return;
+            }
+            const result = await verifyTrustedContact(
+              opts.contactChannelId,
+              DAEMON_INTERNAL_ASSISTANT_ID,
+            );
+            writeOutput(cmd, result);
+            if (!result.success) {
+              process.exitCode = 1;
+            }
+            return;
+          }
+
+          // --- Outbound path ---
+          if (opts.destination) {
+            if (!channel) {
+              writeOutput(cmd, {
+                ok: false,
+                error:
+                  'The "channel" option is required for outbound verification.',
+              });
+              process.exitCode = 1;
+              return;
+            }
+
+            // Normalize destination for rate limiting
+            let rateLimitKey: string | undefined = opts.destination;
+            if (rateLimitKey) {
+              if (channel === "phone") {
+                rateLimitKey =
+                  normalizePhoneNumber(rateLimitKey) ?? rateLimitKey;
+              } else if (channel === "telegram") {
+                rateLimitKey = normalizeTelegramDestination(rateLimitKey);
+              }
+            }
+
+            if (
+              rateLimitKey &&
+              verificationRateLimiter.isBlocked(rateLimitKey)
+            ) {
+              writeOutput(cmd, {
+                ok: false,
+                error:
+                  "Too many verification attempts for this identity. Please try again later.",
+              });
+              process.exitCode = 1;
+              return;
+            }
+
+            const result = await startOutbound({
+              channel,
+              destination: opts.destination,
+              rebind: opts.rebind,
+              originConversationId: opts.originConversationId,
+            });
+
+            if (!result.success && rateLimitKey) {
+              verificationRateLimiter.recordFailure(rateLimitKey);
+            }
+
+            writeOutput(cmd, result);
+            if (!result.success) {
+              process.exitCode = 1;
+            }
+            return;
+          }
+
+          // --- Inbound challenge path ---
+          const result = createInboundChallenge(
+            channel,
+            opts.rebind,
+            opts.sessionId,
+          );
+          writeOutput(cmd, result);
+          if (!result.success) {
+            process.exitCode = 1;
+          }
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          writeOutput(cmd, { ok: false, error: message });
+          process.exitCode = 1;
+        }
+      },
+    );
+
+  // ---------------------------------------------------------------------------
+  // status
+  // ---------------------------------------------------------------------------
+
+  cvs
+    .command("status")
+    .description("Get verification status for a channel")
+    .option(
+      "--channel <channel>",
+      "Channel type (telegram, phone). Defaults to telegram.",
+    )
+    .addHelpText(
+      "after",
+      `
+Returns the current verification state for a channel, including whether a
+guardian is bound, pending challenge status, and any active outbound session
+details (session ID, expiry, send count).
+
+Defaults to telegram if --channel is omitted.
+
+Examples:
+  $ assistant channel-verification-sessions status
+  $ assistant channel-verification-sessions status --channel phone
+  $ assistant channel-verification-sessions status --channel telegram --json`,
+    )
+    .action(async (opts: { channel?: string }, cmd: Command) => {
+      try {
+        initializeDb();
+        const channel = validateChannelOpt(opts.channel, cmd);
+        if (channel === false) return;
+        const result = getVerificationStatus(channel);
+        writeOutput(cmd, result);
+        if (!result.success) {
+          process.exitCode = 1;
+        }
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        writeOutput(cmd, { ok: false, error: message });
+        process.exitCode = 1;
+      }
+    });
+
+  // ---------------------------------------------------------------------------
+  // resend
+  // ---------------------------------------------------------------------------
+
+  cvs
+    .command("resend")
+    .description("Resend the verification code for an active outbound session")
+    .requiredOption(
+      "--channel <channel>",
+      "Channel type (telegram, phone, slack)",
+    )
+    .option(
+      "--origin-conversation-id <id>",
+      "Origin conversation ID for routing",
+    )
+    .addHelpText(
+      "after",
+      `
+Resends the verification code for the active outbound session on the
+specified channel. Subject to per-session and per-destination rate limits.
+
+The --channel flag is required and must match the channel of the active session.
+
+Examples:
+  $ assistant channel-verification-sessions resend --channel telegram
+  $ assistant channel-verification-sessions resend --channel phone --origin-conversation-id conv-123`,
+    )
+    .action(
+      async (
+        opts: { channel: string; originConversationId?: string },
+        cmd: Command,
+      ) => {
+        try {
+          initializeDb();
+          const channel = validateChannelOpt(opts.channel, cmd, true);
+          if (channel === false) return;
+          const result = resendOutbound({
+            channel,
+            originConversationId: opts.originConversationId,
+          });
+          writeOutput(cmd, result);
+          if (!result.success) {
+            process.exitCode = 1;
+          }
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          writeOutput(cmd, { ok: false, error: message });
+          process.exitCode = 1;
+        }
+      },
+    );
+
+  // ---------------------------------------------------------------------------
+  // cancel
+  // ---------------------------------------------------------------------------
+
+  cvs
+    .command("cancel")
+    .description("Cancel all active verification sessions for a channel")
+    .requiredOption(
+      "--channel <channel>",
+      "Channel type (telegram, phone, slack)",
+    )
+    .addHelpText(
+      "after",
+      `
+Cancels both active outbound sessions and pending inbound challenges for
+the specified channel. Does not revoke an existing guardian binding — use
+the "revoke" subcommand for that.
+
+The --channel flag is required.
+
+Examples:
+  $ assistant channel-verification-sessions cancel --channel telegram
+  $ assistant channel-verification-sessions cancel --channel phone --json`,
+    )
+    .action(async (opts: { channel: string }, cmd: Command) => {
+      try {
+        initializeDb();
+        const channel = validateChannelOpt(opts.channel, cmd, true);
+        if (channel === false) return;
+        cancelOutbound({ channel });
+        revokePendingSessions(channel);
+        writeOutput(cmd, { success: true, channel });
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        writeOutput(cmd, { ok: false, error: message });
+        process.exitCode = 1;
+      }
+    });
+
+  // ---------------------------------------------------------------------------
+  // revoke
+  // ---------------------------------------------------------------------------
+
+  cvs
+    .command("revoke")
+    .description(
+      "Revoke the guardian binding and cancel all sessions for a channel",
+    )
+    .option(
+      "--channel <channel>",
+      "Channel type. Defaults to telegram if omitted.",
+    )
+    .addHelpText(
+      "after",
+      `
+Performs a complete teardown: cancels any active outbound sessions, revokes
+pending inbound challenges, and revokes the guardian binding itself. The
+guardian's contact channel is also revoked.
+
+Defaults to telegram if --channel is omitted, matching the API behavior.
+
+Examples:
+  $ assistant channel-verification-sessions revoke
+  $ assistant channel-verification-sessions revoke --channel phone
+  $ assistant channel-verification-sessions revoke --channel telegram --json`,
+    )
+    .action(async (opts: { channel?: string }, cmd: Command) => {
+      try {
+        initializeDb();
+        const channel = validateChannelOpt(opts.channel, cmd);
+        if (channel === false) return;
+        const result = revokeVerificationForChannel(channel);
+        writeOutput(cmd, result);
+        if (!result.success) {
+          process.exitCode = 1;
+        }
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        writeOutput(cmd, { ok: false, error: message });
+        process.exitCode = 1;
+      }
+    });
+}

package/src/cli/{completions.ts → commands/completions.ts}

@@ -1,8 +1,6 @@
 import type { Command } from "commander";
 
-import { getCliLogger } from "../util/logger.js";
-
-const log = getCliLogger("cli");
+import { log } from "../logger.js";
 
 export function registerCompletionsCommand(program: Command): void {
   program

package/src/cli/{config.ts → commands/config.ts}

@@ -6,10 +6,8 @@ import {
   saveRawConfig,
   setNestedValue,
   syncConfigToLockfile,
-} from "../config/loader.js";
-import { getCliLogger } from "../util/logger.js";
-
-const log = getCliLogger("cli");
+} from "../../config/loader.js";
+import { log } from "../logger.js";
 
 /**
  * Flatten a nested config object into dotted key paths.
@@ -192,7 +190,7 @@ Examples:
     .action(() => {
       const { validateAllowlistFile } =
         // eslint-disable-next-line @typescript-eslint/no-require-imports
-        require("../security/secret-allowlist.js") as typeof import("../security/secret-allowlist.js");
+        require("../../security/secret-allowlist.js") as typeof import("../../security/secret-allowlist.js");
       try {
         const errors = validateAllowlistFile();
         if (errors == null) {

package/src/cli/{contacts.ts → commands/contacts.ts}

@@ -9,22 +9,22 @@ import {
   searchContacts,
   updateChannelStatus,
   upsertContact,
-} from "../contacts/contact-store.js";
+} from "../../contacts/contact-store.js";
 import type {
   ChannelPolicy,
   ChannelStatus,
   ContactRole,
   ContactType,
-} from "../contacts/types.js";
-import { initializeDb } from "../memory/db.js";
+} from "../../contacts/types.js";
 import {
   createIngressInvite,
   listIngressInvites,
   redeemIngressInvite,
   redeemVoiceInviteCode,
   revokeIngressInvite,
-} from "../runtime/invite-service.js";
-import { writeOutput } from "./integrations.js";
+} from "../../runtime/invite-service.js";
+import { initializeDb } from "../db.js";
+import { writeOutput } from "../output.js";
 
 export function registerContactsCommand(program: Command): void {
   const contacts = program
@@ -61,7 +61,7 @@ Examples:
     )
     .option(
       "--channel-type <channelType>",
-      "Filter by channel type (email, telegram, sms, voice, whatsapp, slack)",
+      "Filter by channel type (email, telegram, phone, whatsapp, slack)",
     )
     .addHelpText(
       "after",
@@ -207,13 +207,11 @@ Examples:
     .option("--notes <notes>", "Free-text notes about the contact")
     .option(
       "--role <role>",
-      "Contact role: contact or guardian (default: contact)",
-      "contact",
+      "Contact role: contact or guardian (default: contact for new contacts)",
     )
     .option(
       "--contact-type <type>",
-      "Contact type: human or assistant (default: human)",
-      "human",
+      "Contact type: human or assistant (default: human for new contacts)",
     )
     .option(
       "--channels <json>",
@@ -227,7 +225,7 @@ matches an existing contact, that contact is updated. When --id is omitted,
 a new contact is created with a generated UUID.
 
 The --channels flag accepts a JSON array of channel objects. Each object must
-have "type" (e.g. telegram, sms, voice, email, whatsapp) and "address" fields.
+have "type" (e.g. telegram, phone, email, whatsapp) and "address" fields.
 Optional channel fields: isPrimary (boolean), externalUserId, externalChatId,
 status (active, revoked, blocked), policy (allow, deny).
 
@@ -423,7 +421,7 @@ Examples:
     "after",
     `
 Invites are tokens that grant channel access when redeemed. Each invite is
-tied to a source channel (telegram, voice, sms, email, whatsapp) and can
+tied to a source channel (telegram, phone, email, whatsapp) and can
 optionally have usage limits, expiration, and notes. When redeemed, the
 invite creates a channel membership linking a contact to an external
 identifier on the source channel.
@@ -450,7 +448,7 @@ Examples:
   $ assistant contacts invites list
   $ assistant contacts invites list --source-channel telegram
   $ assistant contacts invites list --status active
-  $ assistant contacts invites list --source-channel voice --json`,
+  $ assistant contacts invites list --source-channel phone --json`,
     )
     .action(
       async (
@@ -481,7 +479,7 @@ Examples:
     .description("Create a new invite")
     .requiredOption(
       "--source-channel <channel>",
-      "Source channel (e.g. telegram, voice, sms, email, whatsapp)",
+      "Source channel (e.g. telegram, phone, email, whatsapp)",
     )
     .option("--note <note>", "Optional note")
     .option("--max-uses <n>", "Max redemptions")
@@ -503,7 +501,7 @@ Examples:
       "after",
       `
 Creates a new invite token for the specified source channel. The --source-channel
-flag is required and must be one of: telegram, voice, sms, email, whatsapp.
+flag is required and must be one of: telegram, phone, email, whatsapp.
 
 Optional fields:
   --note                        Free-text note attached to the invite
@@ -518,7 +516,7 @@ Voice invites require three additional fields:
 
 Examples:
   $ assistant contacts invites create --source-channel telegram --note "For Alice" --max-uses 1
-  $ assistant contacts invites create --source-channel voice --expected-external-user-id "+15551234567" --friend-name "Alice" --guardian-name "Bob" --contact-name "Alice Smith"`,
+  $ assistant contacts invites create --source-channel phone --expected-external-user-id "+15551234567" --friend-name "Alice" --guardian-name "Bob" --contact-name "Alice Smith"`,
     )
     .action(
       async (
@@ -674,7 +672,7 @@ Examples:
             const result = redeemVoiceInviteCode({
               code: opts.code,
               callerExternalUserId: opts.callerExternalUserId,
-              sourceChannel: "voice",
+              sourceChannel: "phone",
               ...(opts.assistantId ? { assistantId: opts.assistantId } : {}),
             });
             if (result.ok) {

package/src/cli/{credentials.ts → commands/credentials.ts}

@@ -4,7 +4,7 @@ import {
   deleteSecureKeyAsync,
   getSecureKey,
   setSecureKeyAsync,
-} from "../security/secure-keys.js";
+} from "../../security/secure-keys.js";
 import {
   assertMetadataWritable,
   type CredentialMetadata,
@@ -13,11 +13,9 @@ import {
   getCredentialMetadataById,
   listCredentialMetadata,
   upsertCredentialMetadata,
-} from "../tools/credentials/metadata-store.js";
-import { getCliLogger } from "../util/logger.js";
-import { shouldOutputJson, writeOutput } from "./integrations.js";
-
-const log = getCliLogger("cli");
+} from "../../tools/credentials/metadata-store.js";
+import { log } from "../logger.js";
+import { shouldOutputJson, writeOutput } from "../output.js";
 
 // ---------------------------------------------------------------------------
 // Shared helpers
@@ -68,7 +66,6 @@ function buildCredentialOutput(
     usageDescription: metadata.usageDescription ?? null,
     allowedTools: metadata.allowedTools,
     allowedDomains: metadata.allowedDomains,
-    accountInfo: metadata.accountInfo ?? null,
     grantedScopes: metadata.grantedScopes ?? null,
     expiresAt: metadata.expiresAt
       ? new Date(metadata.expiresAt).toISOString()
@@ -103,7 +100,6 @@ function printCredentialHuman(output: Record<string, unknown>): void {
     log.info(
       `    Domains:     ${(output.allowedDomains as string[]).join(", ")}`,
     );
-  if (output.accountInfo) log.info(`    Account:     ${output.accountInfo}`);
   if (output.grantedScopes)
     log.info(
       `    Scopes:      ${(output.grantedScopes as string[]).join(", ")}`,
@@ -258,7 +254,11 @@ Examples:
       async (
         name: string,
         value: string,
-        opts: { label?: string; description?: string; allowedTools?: string },
+        opts: {
+          label?: string;
+          description?: string;
+          allowedTools?: string;
+        },
         cmd: Command,
       ) => {
         try {
@@ -463,7 +463,6 @@ Examples:
             usageDescription: null,
             allowedTools: [],
             allowedDomains: [],
-            accountInfo: null,
             grantedScopes: null,
             expiresAt: null,
             createdAt: null,

package/src/cli/{default-action.ts → commands/default-action.ts}

@@ -1,8 +1,8 @@
 import type { Command } from "commander";
 
-import { startCli } from "../cli.js";
-import { shouldAutoStartDaemon } from "../daemon/connection-policy.js";
-import { ensureDaemonRunning } from "../daemon/lifecycle.js";
+import { startCli } from "../../cli.js";
+import { shouldAutoStartDaemon } from "../../daemon/connection-policy.js";
+import { ensureDaemonRunning } from "../../daemon/lifecycle.js";
 
 export function registerDefaultAction(program: Command): void {
   program.action(async () => {

package/src/cli/{dev.ts → commands/dev.ts}

@@ -3,10 +3,8 @@ import { join } from "node:path";
 
 import type { Command } from "commander";
 
-import { getDaemonStatus, stopDaemon } from "../daemon/lifecycle.js";
-import { getCliLogger } from "../util/logger.js";
-
-const log = getCliLogger("cli");
+import { getDaemonStatus, stopDaemon } from "../../daemon/lifecycle.js";
+import { log } from "../logger.js";
 
 export function registerDevCommand(program: Command): void {
   program
@@ -97,7 +95,7 @@ Examples:
         }
       }
 
-      const mainPath = `${import.meta.dirname}/../daemon/main.ts`;
+      const mainPath = `${import.meta.dirname}/../../daemon/main.ts`;
 
       const useWatch = opts.watch === true;
       log.info(
@@ -106,7 +104,7 @@ Examples:
         } (Ctrl+C to stop)`,
       );
 
-      const repoRoot = join(import.meta.dirname, "..", "..", "..");
+      const repoRoot = join(import.meta.dirname, "..", "..", "..", "..");
       const args = useWatch ? ["--watch", "run", mainPath] : ["run", mainPath];
       const child = spawn("bun", args, {
         stdio: "inherit",