@vellumai/assistant 0.4.41 → 0.4.43

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

@@ -2,21 +2,29 @@ import type { Command } from "commander";
 
 import {
   getAssistantContactMetadata,
+  getChannelById,
   getContact,
   listContacts,
   mergeContacts,
   searchContacts,
-} from "../contacts/contact-store.js";
-import type { ContactRole } from "../contacts/types.js";
-import { initializeDb } from "../memory/db.js";
+  updateChannelStatus,
+  upsertContact,
+} from "../../contacts/contact-store.js";
+import type {
+  ChannelPolicy,
+  ChannelStatus,
+  ContactRole,
+  ContactType,
+} 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
@@ -36,6 +44,7 @@ is the source of truth for identity resolution across all channels.
 Examples:
   $ assistant contacts list
   $ assistant contacts get abc-123
+  $ assistant contacts upsert --display-name "Alice"
   $ assistant contacts merge keep-id merge-id
   $ assistant contacts invites list`,
   );
@@ -46,6 +55,14 @@ Examples:
     .option("--role <role>", "Filter by role (default: contact)", "contact")
     .option("--limit <limit>", "Maximum number of contacts to return")
     .option("--query <query>", "Search query to filter contacts")
+    .option(
+      "--channel-address <address>",
+      "Search by channel address (email, phone, handle)",
+    )
+    .option(
+      "--channel-type <channelType>",
+      "Filter by channel type (email, telegram, phone, whatsapp, slack)",
+    )
     .addHelpText(
       "after",
       `
@@ -53,14 +70,20 @@ Lists contacts with optional filtering. The --role flag accepts: contact
 or guardian (defaults to contact). The --limit flag sets
 the maximum number of results (defaults to 50).
 
-When --query is provided, a full-text search is performed across contact
-names and linked external identifiers (phone numbers, emails, Telegram
-usernames). Without --query, returns all contacts matching the role filter.
+When --query, --channel-address, or --channel-type is provided, a search
+is performed. --query does full-text search across contact names and
+linked external identifiers. --channel-address matches phone numbers,
+emails, or handles. --channel-type filters by channel kind. These filters
+can be combined. Without any search params, returns all contacts matching
+the role filter.
 
 Examples:
   $ assistant contacts list
   $ assistant contacts list --role guardian
   $ assistant contacts list --query "john" --limit 10
+  $ assistant contacts list --channel-address "+15551234567"
+  $ assistant contacts list --channel-type telegram
+  $ assistant contacts list --query "alice" --channel-type email
   $ assistant contacts list --role guardian --json`,
     )
     .action(
@@ -69,6 +92,8 @@ Examples:
           role?: string;
           limit?: string;
           query?: string;
+          channelAddress?: string;
+          channelType?: string;
         },
         cmd: Command,
       ) => {
@@ -79,8 +104,16 @@ Examples:
 
           const effectiveLimit = limit ?? 50;
 
-          const results = opts.query
-            ? searchContacts({ query: opts.query, role, limit: effectiveLimit })
+          const hasSearchParams =
+            opts.query || opts.channelAddress || opts.channelType;
+          const results = hasSearchParams
+            ? searchContacts({
+                query: opts.query,
+                channelAddress: opts.channelAddress,
+                channelType: opts.channelType,
+                role,
+                limit: effectiveLimit,
+              })
             : listContacts(effectiveLimit, role);
 
           writeOutput(cmd, { ok: true, contacts: results });
@@ -166,6 +199,220 @@ Examples:
       },
     );
 
+  contacts
+    .command("upsert")
+    .description("Create or update a contact")
+    .requiredOption("--display-name <name>", "Display name for the contact")
+    .option("--id <id>", "Contact ID — provide to update an existing contact")
+    .option("--notes <notes>", "Free-text notes about the contact")
+    .option(
+      "--role <role>",
+      "Contact role: contact or guardian (default: contact for new contacts)",
+    )
+    .option(
+      "--contact-type <type>",
+      "Contact type: human or assistant (default: human for new contacts)",
+    )
+    .option(
+      "--channels <json>",
+      "JSON array of channel objects, each with type, address, and optional isPrimary, externalUserId, externalChatId, status, policy",
+    )
+    .addHelpText(
+      "after",
+      `
+Creates a new contact or updates an existing one. When --id is provided and
+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, phone, email, whatsapp) and "address" fields.
+Optional channel fields: isPrimary (boolean), externalUserId, externalChatId,
+status (active, revoked, blocked), policy (allow, deny).
+
+Examples:
+  $ assistant contacts upsert --display-name "Alice" --json
+  $ assistant contacts upsert --display-name "Alice" --id abc-123 --notes "Updated notes" --json
+  $ assistant contacts upsert --display-name "Bob" --role guardian --json
+  $ assistant contacts upsert --display-name "Bob" --channels '[{"type":"telegram","address":"12345","externalUserId":"12345","status":"active","policy":"allow"}]' --json`,
+    )
+    .action(
+      async (
+        opts: {
+          displayName: string;
+          id?: string;
+          notes?: string;
+          role?: string;
+          contactType?: string;
+          channels?: string;
+        },
+        cmd: Command,
+      ) => {
+        try {
+          initializeDb();
+
+          let channels: unknown[] | undefined;
+          if (opts.channels) {
+            try {
+              channels = JSON.parse(opts.channels);
+              if (!Array.isArray(channels)) {
+                writeOutput(cmd, {
+                  ok: false,
+                  error: "--channels must be a JSON array",
+                });
+                process.exitCode = 1;
+                return;
+              }
+            } catch {
+              writeOutput(cmd, {
+                ok: false,
+                error: `Invalid JSON for --channels: ${opts.channels}`,
+              });
+              process.exitCode = 1;
+              return;
+            }
+          }
+
+          const result = upsertContact({
+            id: opts.id,
+            displayName: opts.displayName,
+            notes: opts.notes,
+            role: opts.role as ContactRole | undefined,
+            contactType: opts.contactType as ContactType | undefined,
+            channels: channels as
+              | {
+                  type: string;
+                  address: string;
+                  isPrimary?: boolean;
+                  externalUserId?: string;
+                  externalChatId?: string;
+                  status?: ChannelStatus;
+                  policy?: ChannelPolicy;
+                }[]
+              | undefined,
+          });
+
+          writeOutput(cmd, { ok: true, contact: result });
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          writeOutput(cmd, { ok: false, error: message });
+          process.exitCode = 1;
+        }
+      },
+    );
+
+  const channelsCmds = contacts
+    .command("channels")
+    .description("Manage contact channels");
+
+  channelsCmds.addHelpText(
+    "after",
+    `
+Channels represent external communication endpoints linked to contacts —
+phone numbers, Telegram IDs, email addresses, etc. Each channel has a
+status (active, pending, revoked, blocked, unverified) and a policy
+(allow, deny, escalate) that controls how the assistant handles messages
+from that channel.
+
+Examples:
+  $ assistant contacts channels update-status <channelId> --status revoked --reason "No longer needed"
+  $ assistant contacts channels update-status <channelId> --policy deny`,
+  );
+
+  channelsCmds
+    .command("update-status <channelId>")
+    .description("Update a channel's status or policy")
+    .option(
+      "--status <status>",
+      "New channel status: active, revoked, or blocked",
+    )
+    .option("--policy <policy>", "New channel policy: allow, deny, or escalate")
+    .option("--reason <reason>", "Reason for the status change")
+    .addHelpText(
+      "after",
+      `
+Arguments:
+  channelId   UUID of the contact channel to update
+
+Updates the access-control fields on an existing channel. At least one of
+--status or --policy must be provided.
+
+When --status is "revoked", --reason is mapped to revokedReason on the
+channel record. When --status is "blocked", --reason is mapped to
+blockedReason. The --reason flag is ignored for other status values.
+
+Valid --status values: active, revoked, blocked
+Valid --policy values: allow, deny, escalate
+
+Examples:
+  $ assistant contacts channels update-status abc-123 --status revoked --reason "No longer needed" --json
+  $ assistant contacts channels update-status abc-123 --status blocked --reason "Spam" --json
+  $ assistant contacts channels update-status abc-123 --policy deny --json
+  $ assistant contacts channels update-status abc-123 --status active --policy allow --json`,
+    )
+    .action(
+      async (
+        channelId: string,
+        opts: {
+          status?: string;
+          policy?: string;
+          reason?: string;
+        },
+        cmd: Command,
+      ) => {
+        try {
+          if (!opts.status && !opts.policy) {
+            writeOutput(cmd, {
+              ok: false,
+              error: "At least one of --status or --policy must be provided",
+            });
+            process.exitCode = 1;
+            return;
+          }
+
+          initializeDb();
+
+          const existing = getChannelById(channelId);
+          if (!existing) {
+            writeOutput(cmd, {
+              ok: false,
+              error: `Channel not found: ${channelId}`,
+            });
+            process.exitCode = 1;
+            return;
+          }
+
+          const status = opts.status as ChannelStatus | undefined;
+          const policy = opts.policy as ChannelPolicy | undefined;
+
+          const revokedReason: string | null | undefined =
+            status !== undefined
+              ? status === "revoked"
+                ? (opts.reason ?? null)
+                : null
+              : undefined;
+          const blockedReason: string | null | undefined =
+            status !== undefined
+              ? status === "blocked"
+                ? (opts.reason ?? null)
+                : null
+              : undefined;
+
+          const result = updateChannelStatus(channelId, {
+            status,
+            policy,
+            revokedReason,
+            blockedReason,
+          });
+
+          writeOutput(cmd, { ok: true, channel: result });
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          writeOutput(cmd, { ok: false, error: message });
+          process.exitCode = 1;
+        }
+      },
+    );
+
   const invites = contacts
     .command("invites")
     .description("Manage contact invites");
@@ -174,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.
@@ -201,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 (
@@ -232,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")
@@ -254,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
@@ -269,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 (
@@ -425,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",

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

@@ -1,28 +1,20 @@
 import { execSync } from "node:child_process";
 import { existsSync, readFileSync, statSync } from "node:fs";
-import * as net from "node:net";
 
 import type { Command } from "commander";
 
-import { loadRawConfig } from "../config/loader.js";
+import { loadRawConfig } from "../../config/loader.js";
+import { shouldAutoStartDaemon } from "../../daemon/connection-policy.js";
 import {
-  hasSocketOverride,
-  shouldAutoStartDaemon,
-} from "../daemon/connection-policy.js";
-import { IpcError } from "../util/errors.js";
-import { getCliLogger } from "../util/logger.js";
-import {
-  getDataDir,
   getDbPath,
   getLogPath,
   getRootDir,
-  getSocketPath,
   getWorkspaceDir,
   getWorkspaceHooksDir,
   getWorkspaceSkillsDir,
-} from "../util/platform.js";
-
-const log = getCliLogger("cli");
+} from "../../util/platform.js";
+import { getHttpBaseUrl, httpHealthCheck } from "../http-client.js";
+import { log } from "../logger.js";
 
 export function registerDoctorCommand(program: Command): void {
   program
@@ -42,13 +34,13 @@ Output symbols:
 Diagnostic checks performed:
   1.  Bun is installed           Verifies bun is available in PATH
   2.  API key configured         Checks for a valid provider API key in config or env
-  3.  Assistant reachable         Connects to the assistant Unix socket
+  3.  Assistant reachable         HTTP health check against the assistant server
   4.  Database exists/readable   Opens the SQLite database and runs a test query
   5.  Directory structure        Verifies required ~/.vellum/ directories exist
   6.  Disk space                 Ensures at least 100MB free on the data partition
   7.  Log file size              Warns if the log file exceeds 50MB
   8.  Database integrity         Runs SQLite PRAGMA integrity_check
-  9.  Socket permissions         Verifies the assistant socket has 0600 or 0700 mode
+  9.  HTTP token permissions     Verifies the http-token file has 0600 or 0700 mode
   10. Trust rule syntax          Validates trust.json structure and rule fields
   11. WASM files                 Checks that tree-sitter WASM binaries are present
   12. Browser runtime            Verifies Playwright and Chromium availability
@@ -65,14 +57,9 @@ Examples:
       log.info("Vellum Doctor\n");
 
       // 0. Connection policy info
-      const socketPath = getSocketPath();
-      const isOverride = hasSocketOverride();
+      const httpUrl = getHttpBaseUrl();
       const autostart = shouldAutoStartDaemon();
-      log.info(
-        `  Socket:    ${socketPath}${
-          isOverride ? " (override via VELLUM_DAEMON_SOCKET)" : ""
-        }`,
-      );
+      log.info(`  HTTP:      ${httpUrl}`);
       log.info(`  Autostart: ${autostart ? "enabled" : "disabled"}\n`);
 
       // 1. Bun installed
@@ -114,35 +101,22 @@ Examples:
         );
       }
 
-      // 3. Daemon reachable
+      // 3. Daemon reachable (HTTP health check)
       try {
-        const sock = getSocketPath();
-        if (!existsSync(sock)) {
+        const healthy = await httpHealthCheck(2000);
+        if (healthy) {
+          pass("Assistant reachable");
+        } else {
           fail(
             "Assistant reachable",
-            "socket not found (is the assistant running?)",
+            "HTTP health check failed (is the assistant running?)",
           );
-        } else {
-          await new Promise<void>((resolve, reject) => {
-            const s = net.createConnection(sock);
-            const timer = setTimeout(() => {
-              s.destroy();
-              reject(new IpcError("timeout"));
-            }, 2000);
-            s.on("connect", () => {
-              clearTimeout(timer);
-              s.end();
-              resolve();
-            });
-            s.on("error", (err) => {
-              clearTimeout(timer);
-              reject(err);
-            });
-          });
-          pass("Assistant reachable");
         }
       } catch {
-        fail("Assistant reachable", "could not connect to assistant socket");
+        fail(
+          "Assistant reachable",
+          "could not connect to assistant HTTP server",
+        );
       }
 
       // 4. DB exists and readable
@@ -166,7 +140,7 @@ Examples:
 
       // 5. ~/.vellum/ directory structure (workspace layout)
       const rootDir = getRootDir();
-      const dataDir = getDataDir();
+      const dataDir = process.env.VELLUM_DATA_DIR!;
       const workspaceDir = getWorkspaceDir();
       const requiredDirs = [
         rootDir,
@@ -257,25 +231,27 @@ Examples:
         fail("Database integrity check", "database file not found");
       }
 
-      // 9. Socket permissions
-      const sockPath = getSocketPath();
-      if (existsSync(sockPath)) {
+      // 9. HTTP token
+      const tokenPath = `${rootDir}/http-token`;
+      if (existsSync(tokenPath)) {
         try {
-          const sockStat = statSync(sockPath);
-          const mode = sockStat.mode & 0o777;
+          const tokenStat = statSync(tokenPath);
+          const mode = tokenStat.mode & 0o777;
           if (mode === 0o600 || mode === 0o700) {
-            pass(`Socket permissions (${mode.toString(8).padStart(4, "0")})`);
+            pass(
+              `HTTP token permissions (${mode.toString(8).padStart(4, "0")})`,
+            );
           } else {
             fail(
-              "Socket permissions",
+              "HTTP token permissions",
               `expected 0600 or 0700, got 0${mode.toString(8)}`,
             );
           }
         } catch {
-          fail("Socket permissions", "could not stat socket");
+          fail("HTTP token permissions", "could not stat http-token file");
         }
       } else {
-        pass("Socket permissions (socket not present — assistant not running)");
+        pass("HTTP token (not present — assistant not running)");
       }
 
       // 10. Trust rule syntax
@@ -327,7 +303,7 @@ Examples:
       const missingWasm: string[] = [];
       for (const wasm of wasmFiles) {
         const dir = import.meta.dirname ?? __dirname;
-        let fullPath = `${dir}/../../node_modules/${wasm.pkg}/${wasm.file}`;
+        let fullPath = `${dir}/../../../node_modules/${wasm.pkg}/${wasm.file}`;
         // In compiled binaries, fall back to Resources/ or next to the binary
         if (!existsSync(fullPath) && dir.startsWith("/$bunfs/")) {
           const { dirname: pathDirname, join: pathJoin } =
@@ -345,11 +321,11 @@ Examples:
           try {
             const wasmStat = statSync(fullPath);
             if (wasmStat.size === 0) {
-              missingWasm.push(`${wasm} (empty)`);
+              missingWasm.push(`${wasm.file} (empty)`);
               wasmOk = false;
             }
           } catch {
-            missingWasm.push(`${wasm} (unreadable)`);
+            missingWasm.push(`${wasm.file} (unreadable)`);
             wasmOk = false;
           }
         }
@@ -362,7 +338,7 @@ Examples:
 
       // 12. Browser runtime (Playwright + Chromium)
       const { checkBrowserRuntime } =
-        await import("../tools/browser/runtime-check.js");
+        await import("../../tools/browser/runtime-check.js");
       const browserStatus = await checkBrowserRuntime();
       if (
         browserStatus.playwrightAvailable &&
@@ -380,7 +356,7 @@ Examples:
 
       // 13. Sandbox backend diagnostics
       const { runSandboxDiagnostics } =
-        await import("../tools/terminal/sandbox-diagnostics.js");
+        await import("../../tools/terminal/sandbox-diagnostics.js");
       const sandbox = runSandboxDiagnostics();
       log.info(
         `\n  Sandbox:   ${sandbox.config.enabled ? "enabled" : "disabled"}`,