@vellumai/assistant 0.4.41 → 0.4.42

package/src/cli/contacts.ts

@@ -2,12 +2,20 @@ import type { Command } from "commander";
 
 import {
   getAssistantContactMetadata,
+  getChannelById,
   getContact,
   listContacts,
   mergeContacts,
   searchContacts,
+  updateChannelStatus,
+  upsertContact,
 } from "../contacts/contact-store.js";
-import type { ContactRole } from "../contacts/types.js";
+import type {
+  ChannelPolicy,
+  ChannelStatus,
+  ContactRole,
+  ContactType,
+} from "../contacts/types.js";
 import { initializeDb } from "../memory/db.js";
 import {
   createIngressInvite,
@@ -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, sms, voice, 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,222 @@ 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)",
+      "contact",
+    )
+    .option(
+      "--contact-type <type>",
+      "Contact type: human or assistant (default: human)",
+      "human",
+    )
+    .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, sms, voice, 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");

package/src/config/bundled-skills/app-builder/SKILL.md

@@ -25,8 +25,17 @@ You are an expert app builder and visual designer. When the user asks you to cre
 
 **Make creative decisions on behalf of the user.** They want to be delighted, not consulted. Pick the accent color. Choose between a dark moody aesthetic or a light airy one. Decide if cards should have glassmorphism or layered shadows. Add a background pattern or gradient. These are YOUR decisions as the designer.
 
+<!-- feature:app-builder-multifile:start -->
+
 **Prefer multi-file TSX projects** for any non-trivial app. They give you component reuse, TypeScript safety, and cleaner organization. Fall back to single-file HTML only for the simplest one-off pages.
 
+<!-- feature:app-builder-multifile:end -->
+<!-- feature:app-builder-multifile:alt -->
+
+**Always build single-file HTML apps.** Write a complete, self-contained HTML document with all CSS in `<style>` and all JavaScript in `<script>`. Do not use multi-file projects or TSX.
+
+<!-- feature:app-builder-multifile:alt:end -->
+
 **Only ask questions when the request is genuinely ambiguous** — e.g., "build me an app" with no indication of what kind. Even then, prefer building something impressive based on context clues over asking a battery of questions.
 
 **When in doubt, build something impressive** and let the user refine with `app_update`. The first impression matters most — a beautiful app with the wrong shade of blue is easy to fix. A correct but ugly app is hard to come back from.
@@ -69,7 +78,11 @@ Example schema for a project tracker:
 
 ### 3. Build the App
 
-Apps are rendered inside a sandboxed WebView on macOS. You can build them in two formats: **multi-file TSX** (preferred) or **single-file HTML** (legacy).
+Apps are rendered inside a sandboxed WebView on macOS.
+
+<!-- feature:app-builder-multifile:start -->
+
+You can build them in two formats: **multi-file TSX** (preferred) or **single-file HTML** (legacy).
 
 #### Multi-file TSX projects (preferred)
 
@@ -198,10 +211,11 @@ app_file_write(app_id, "src/styles.css", `.app { padding: var(--v-spacing-lg); }
 - No external fonts, images, or resources — use system fonts and CSS/SVG for visuals
 - Design for 400-600px width with graceful resizing
 - The WebView blocks all navigation — links and form `action` attributes won't work
+<!-- feature:app-builder-multifile:end -->
 
-#### Single HTML file (legacy)
+#### Single HTML file
 
-Use this format only for the simplest one-off pages. Write a complete, self-contained HTML document.
+Write a complete, self-contained HTML document.
 
 **Technical constraints (single-file):**