@vellumai/assistant 0.11.7 → 0.11.8-staging.1

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

@@ -2,6 +2,10 @@
 
 import type { CliCommandHelp } from "../lib/cli-command-help.js";
 
+/** Shared tail for the three commands that park on a form in the app. */
+const FORM_NOTE = `The form opens in the guardian's desktop or web app. With no app connected
+nobody can answer, and the command exits when the wait elapses.`;
+
 export const contactsHelp: CliCommandHelp = {
   name: "contacts",
   description: "Manage and query the contact graph",
@@ -15,9 +19,21 @@ can be linked to external identifiers — phone numbers,
 Telegram IDs, email addresses — via channel memberships. The contact graph
 is the source of truth for identity resolution across all channels.
 
+Writes are split in two, and both need the guardian at the app:
+
+  create/update/delete  the record: who someone is (name, notes). Opens a
+                        form in the guardian's app; nothing is written until
+                        they submit it. A record has no channel, so it grants
+                        no access on its own.
+  prompt                the channel: an address the guardian types, bound to
+                        a contact. This is what makes someone reachable.
+
+Granting someone access to message the assistant is 'contacts invites create'.
+
 Examples:
   $ assistant contacts list
   $ assistant contacts get abc-123
+  $ assistant contacts create --name "Alice"
   $ assistant contacts invites list`,
   subcommands: [
     {
@@ -83,10 +99,139 @@ assistant metadata is included.
 Examples:
   $ assistant contacts get 7a3b1c2d-4e5f-6789-abcd-ef0123456789
   $ assistant contacts get abc-123 --json`,
+    },
+    {
+      name: "create",
+      description: "Propose a new contact for the guardian to confirm",
+      options: [
+        {
+          flags: "--name <name>",
+          description: "Proposed display name, prefilled into the form",
+        },
+        {
+          flags: "--notes <notes>",
+          description: "Proposed notes, prefilled into the form",
+        },
+        {
+          flags: "--label <label>",
+          description: "Display label shown on the form",
+        },
+        {
+          flags: "--description <description>",
+          description: "Longer description shown on the form",
+        },
+        {
+          flags: "--timeout <ms>",
+          description:
+            "How long the form stays open (ms). The command waits for it to close.",
+          defaultValue: String(300_000),
+        },
+      ],
+      helpText: `
+Opens an add-contact form in the guardian's app, prefilled with --name and
+--notes. The guardian can edit either field before submitting, and the values
+they submit are what gets written. Nothing is written if they dismiss the form.
+
+The new contact has no channels, so it cannot message the assistant and the
+assistant cannot reach it. It is a name to hang notes on and to address an
+invite to. Use 'contacts prompt' to bind an address, or
+'contacts invites create' to let someone bind their own.
+
+${FORM_NOTE}
+
+Examples:
+  $ assistant contacts create --name "Alice"
+  $ assistant contacts create --name "Alice" --notes "Dentist, referred by Bob"
+  $ assistant contacts create --name "Alice" --json`,
+    },
+    {
+      name: "update",
+      args: "<id>",
+      description: "Propose a contact edit for the guardian to confirm",
+      options: [
+        {
+          flags: "--name <name>",
+          description: "Proposed display name, prefilled into the form",
+        },
+        {
+          flags: "--notes <notes>",
+          description: "Proposed notes, prefilled into the form",
+        },
+        {
+          flags: "--label <label>",
+          description: "Display label shown on the form",
+        },
+        {
+          flags: "--description <description>",
+          description: "Longer description shown on the form",
+        },
+        {
+          flags: "--timeout <ms>",
+          description:
+            "How long the form stays open (ms). The command waits for it to close.",
+          defaultValue: String(300_000),
+        },
+      ],
+      helpText: `
+Arguments:
+  id   UUID of the contact to edit. Run 'assistant contacts list' to find IDs.
+
+Opens an edit form in the guardian's app showing the contact's current name
+alongside the proposed change. At least one of --name or --notes is required.
+The guardian can edit either field before submitting; what they submit is what
+gets written.
+
+Edits the record only. Channel access is unaffected: use
+'contacts channels update-status' to revoke or block a channel.
+
+${FORM_NOTE}
+
+Examples:
+  $ assistant contacts update 7a3b1c2d-4e5f-6789-abcd-ef0123456789 --name "Alice Chen"
+  $ assistant contacts update abc-123 --notes "Moved to Berlin"`,
+    },
+    {
+      name: "delete",
+      args: "<id>",
+      description: "Propose deleting a contact for the guardian to confirm",
+      options: [
+        {
+          flags: "--label <label>",
+          description: "Display label shown on the confirmation",
+        },
+        {
+          flags: "--description <description>",
+          description: "Longer description shown on the confirmation",
+        },
+        {
+          flags: "--timeout <ms>",
+          description:
+            "How long the confirmation stays open (ms). The command waits for it to close.",
+          defaultValue: String(300_000),
+        },
+      ],
+      helpText: `
+Arguments:
+  id   UUID of the contact to delete. Run 'assistant contacts list' to find IDs.
+
+Opens a confirmation in the guardian's app showing the contact and its
+channels. Nothing is deleted unless they confirm.
+
+Deleting a contact deletes its channels with it, so anyone reaching the
+assistant through those channels loses access. A guardian contact cannot be
+deleted. To merge a duplicate instead of deleting it, use the contact_merge
+tool, which keeps the surviving contact's channels.
+
+${FORM_NOTE}
+
+Examples:
+  $ assistant contacts delete 7a3b1c2d-4e5f-6789-abcd-ef0123456789
+  $ assistant contacts delete abc-123 --json`,
     },
     {
       name: "prompt",
-      description: "Prompt user to register a contact channel via the app UI",
+      description:
+        "Ask the guardian to enter a channel address and bind it to a contact",
       options: [
         {
           flags: "--channel <channel>",
@@ -118,27 +263,44 @@ Examples:
         {
           flags: "--timeout <ms>",
           description:
-            "How long to wait for the user to submit (ms). Defaults to match the server-side prompt timeout.",
-          defaultValue: String(310_000),
+            "How long the form stays open (ms). The command waits for it to close.",
+          defaultValue: String(300_000),
         },
         {
           flags: "--verify",
           description:
-            "Mark the submitted channel verified (same attest as Contacts Verify me)",
+            "Pre-check the form's 'mark verified' box. The guardian decides: unchecked, the channel stays unverified.",
         },
       ],
       helpText: `
-Opens a contact address prompt in the user's app. The user enters a channel
-address (phone number, email, Telegram ID, etc.). The address is saved with
-status "unverified" unless --verify is set, which attests the channel the
-same way Contacts Verify me does.
+Opens an address form in the guardian's app. They enter a channel address
+(phone number, email, Telegram ID, etc.) and it is bound as a channel.
+
+Which contact it binds to depends on --role:
+
+  --role guardian    Binds to the guardian contact. An address already bound
+                     to a different contact is rejected as a conflict.
+  anything else      Looks up the submitted (channel type, address). A match
+                     reuses that contact and channel; no match creates a new
+                     contact named after the address. Other --role values are
+                     form hints only: the contact is created with role
+                     "contact" either way.
+
+This cannot add a channel to an arbitrary existing contact. To name a contact
+first, run 'contacts create'; to let someone bind their own address, use
+'contacts invites create'.
+
+The channel is saved unverified unless the guardian leaves the form's "mark
+verified" box checked, which attests it the same way Contacts Verify me does.
+An attested channel is admitted, so --verify only proposes the box state.
+
+${FORM_NOTE}
 
 Examples:
   $ assistant contacts prompt --channel phone --role guardian
+  $ assistant contacts prompt --channel email --label "Alice's email address"
   $ assistant contacts prompt --channel imessage --role guardian --verify \\
-      --label "Your iMessage number" --placeholder "+15551234567"
-
-Run \`assistant contacts prompt --help\` for full option details.`,
+      --label "Your iMessage number" --placeholder "+15555550142"`,
     },
     {
       name: "channels",

package/src/cli/commands/contacts.ts

@@ -1,6 +1,11 @@
 import type { Command } from "commander";
 
 import { cliIpcCall, exitFromIpcResult } from "../../ipc/cli-client.js";
+import {
+  GUARDIAN_FORM_DEFAULT_TIMEOUT_MS,
+  GUARDIAN_FORM_MAX_TIMEOUT_MS,
+  guardianFormCallBudgetMs,
+} from "../../util/guardian-form-timeouts.js";
 import { applyCommandHelp, subcommand } from "../lib/cli-command-help.js";
 import { registerCommand } from "../lib/register-command.js";
 import { shouldOutputJson, writeError, writeOutput } from "../output.js";
@@ -30,7 +35,9 @@ interface ContactWithChannels {
   displayName: string;
   role?: string;
   contactType: string;
-  notes?: string;
+  // Nullable on the wire (`contactSchema`, and the gateway's ContactRead):
+  // a contact with no notes reads as null, not as an absent field.
+  notes?: string | null;
   principalId?: string;
   createdAt: string | number;
   updatedAt: string | number;
@@ -51,6 +58,8 @@ interface ContactPromptResult {
   address?: string;
   channelId?: string;
   contactId?: string;
+  /** Whether the channel is attested, as the guardian's checkbox left it. */
+  verified?: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -156,6 +165,213 @@ function formatContactDetail(
   return lines.join("\n");
 }
 
+/**
+ * Parse `--timeout`, which bounds how long the form stays open. Returns null
+ * (after reporting) when the value is out of range, so a bad number fails here
+ * rather than as a schema rejection after the round trip.
+ */
+function parseFormTimeout(
+  raw: string | undefined,
+  cmd: Command,
+): number | null {
+  if (raw === undefined) {
+    return GUARDIAN_FORM_DEFAULT_TIMEOUT_MS;
+  }
+  // The whole token has to be digits: parseInt takes a valid prefix, so
+  // "1e3" would pass as 1 and "100.5" as 100, quietly giving a form a
+  // fraction of the wait it was asked for.
+  const parsed = /^\d+$/.test(raw.trim()) ? Number(raw.trim()) : Number.NaN;
+  if (!Number.isSafeInteger(parsed) || parsed <= 0) {
+    writeError(
+      cmd,
+      `Invalid --timeout "${raw}": expected a positive whole number of milliseconds`,
+    );
+    process.exitCode = 1;
+    return null;
+  }
+  if (parsed > GUARDIAN_FORM_MAX_TIMEOUT_MS) {
+    writeError(
+      cmd,
+      `Invalid --timeout "${raw}": the longest a form stays open is ${GUARDIAN_FORM_MAX_TIMEOUT_MS}ms`,
+    );
+    process.exitCode = 1;
+    return null;
+  }
+  return parsed;
+}
+
+interface ContactRecordPromptBody {
+  operation: "create" | "update" | "delete";
+  contactId?: string;
+  currentDisplayName?: string;
+  currentNotes?: string;
+  channels?: Array<{ type: string; address: string }>;
+  displayName?: string;
+  notes?: string;
+  notesProposed?: boolean;
+  label?: string;
+  description?: string;
+}
+
+/**
+ * Read a contact before proposing a write against it, so a bad id fails here
+ * rather than after the guardian has answered a form about the wrong person.
+ * The read is the gateway-relayed one, so it reflects the source of truth.
+ */
+async function readContactForPrompt(
+  id: string,
+  cmd: Command,
+  /**
+   * Whether a contact the read cannot see should still reach the form. A
+   * dual-write gap can leave a contact in the assistant mirror that this
+   * gateway-backed read misses, and deleting one of those is supported, so a
+   * delete carries on with a bare record rather than refusing an id the
+   * guardian can see. An update cannot: it needs the stored values to know
+   * what the guardian actually changed.
+   */
+  allowUnreadable = false,
+): Promise<ContactWithChannels | null> {
+  const r = await cliIpcCall<{ ok: boolean; contact: ContactWithChannels }>(
+    "getContact",
+    { pathParams: { id } },
+  );
+  if (r.ok) {
+    return r.result!.contact;
+  }
+  if (allowUnreadable && r.statusCode === 404) {
+    return {
+      id,
+      displayName: id,
+      contactType: "human",
+      createdAt: 0,
+      updatedAt: 0,
+      interactionCount: null,
+      channels: [],
+    };
+  }
+
+  exitFromIpcResult(
+    r as { ok: false; error?: string; statusCode?: number },
+    cmd,
+  );
+  return null;
+}
+
+/**
+ * Park on the guardian's answer to a contact-record form, then report what was
+ * actually written. The submitted values can differ from the proposed ones, so
+ * the result is re-read rather than echoed back from the request.
+ */
+async function runRecordPrompt(
+  body: ContactRecordPromptBody,
+  timeout: string | undefined,
+  cmd: Command,
+): Promise<void> {
+  const timeoutMs = parseFormTimeout(timeout, cmd);
+  if (timeoutMs === null) {
+    return;
+  }
+  const r = await cliIpcCall<{
+    ok: boolean;
+    error?: string;
+    contactId?: string;
+    notesSaved?: boolean;
+    nothingWritten?: boolean;
+  }>(
+    "contacts_record_prompt",
+    { body: { ...body, timeoutMs } },
+    { timeoutMs: guardianFormCallBudgetMs(timeoutMs) },
+  );
+
+  if (!r.ok) {
+    return exitFromIpcResult(
+      r as { ok: false; error?: string; statusCode?: number },
+      cmd,
+    );
+  }
+
+  if (!r.result?.ok) {
+    writeError(cmd, r.result?.error ?? "Contact form failed");
+    process.exitCode = 1;
+    return;
+  }
+
+  const contactId = r.result.contactId;
+  // Notes are stored apart from the rest of the record, so they can be the one
+  // part that does not land. Whether that leaves nothing behind is the
+  // gateway's to say: the guardian submits only the fields they changed, so
+  // what this command proposed is no guide to what was written.
+  const notesLost = r.result.notesSaved === false;
+  const nothingWritten = r.result.nothingWritten === true;
+
+  if (body.operation === "delete") {
+    const deleted = body.currentDisplayName ?? contactId ?? body.contactId;
+    if (shouldOutputJson(cmd)) {
+      writeOutput(cmd, { ok: true, deleted: true, contactId });
+    } else {
+      process.stdout.write(`Deleted contact: ${deleted} (${body.contactId})\n`);
+    }
+    return;
+  }
+
+  if (!contactId) {
+    writeError(cmd, "Contact form returned no contact id");
+    process.exitCode = 1;
+    return;
+  }
+
+  const verb = body.operation === "create" ? "Created" : "Updated";
+
+  // The write is already done and the guardian has already answered. This read
+  // is only for what to print, so a failure here reports the write with less
+  // detail rather than reporting the command as failed: an exit code that says
+  // otherwise invites a retry, and retrying a create makes a second contact.
+  const read = await cliIpcCall<{ ok: boolean; contact: ContactWithChannels }>(
+    "getContact",
+    { pathParams: { id: contactId } },
+  );
+  const written = read.ok ? read.result?.contact : undefined;
+
+  if (nothingWritten) {
+    // Nothing the caller asked for landed, so this is a failure however it is
+    // read: one object, and a nonzero exit.
+    if (shouldOutputJson(cmd)) {
+      writeOutput(cmd, {
+        ok: false,
+        error: "The contact's notes could not be saved",
+        contactId,
+        notesSaved: false,
+      });
+    } else {
+      writeError(cmd, "The contact's notes could not be saved");
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  if (shouldOutputJson(cmd)) {
+    // One object, whatever happened: a second one saying otherwise reads as a
+    // failure to anything parsing this, and a retried create makes a duplicate.
+    writeOutput(cmd, {
+      ok: true,
+      ...(written ? { contact: written } : { contactId }),
+      ...(notesLost ? { notesSaved: false } : {}),
+    });
+    return;
+  }
+
+  if (written) {
+    process.stdout.write(`${verb} contact:\n`);
+    process.stdout.write(formatContactDetail(written) + "\n");
+  } else {
+    process.stdout.write(`${verb} contact: ${contactId}\n`);
+    writeError(cmd, "Could not read the contact back to display it");
+  }
+  if (notesLost) {
+    writeError(cmd, "The contact was saved, but its notes were not");
+  }
+}
+
 export function registerContactsCommand(program: Command): void {
   registerCommand(program, {
     name: contactsHelp.name,
@@ -250,6 +466,123 @@ export function registerContactsCommand(program: Command): void {
         },
       );
 
+      // -----------------------------------------------------------------------
+      // create / update / delete
+      //
+      // Each opens a form in the guardian's app and blocks on their answer.
+      // The daemon writes nothing: the guardian's client posts the confirmed
+      // record straight to the gateway, so an unattended assistant cannot
+      // change the contact graph.
+      // -----------------------------------------------------------------------
+
+      subcommand(contacts, "create").action(
+        async (
+          opts: {
+            name?: string;
+            notes?: string;
+            label?: string;
+            description?: string;
+            timeout?: string;
+          },
+          cmd: Command,
+        ) => {
+          await runRecordPrompt(
+            {
+              operation: "create",
+              displayName: opts.name,
+              notes: opts.notes,
+              label: opts.label,
+              description: opts.description,
+            },
+            opts.timeout,
+            cmd,
+          );
+        },
+      );
+
+      subcommand(contacts, "update").action(
+        async (
+          id: string,
+          opts: {
+            name?: string;
+            notes?: string;
+            label?: string;
+            description?: string;
+            timeout?: string;
+          },
+          cmd: Command,
+        ) => {
+          if (!opts.name && opts.notes === undefined) {
+            writeError(
+              cmd,
+              "At least one of --name or --notes must be provided",
+            );
+            process.exitCode = 1;
+            return;
+          }
+          const current = await readContactForPrompt(id, cmd);
+          if (!current) {
+            return;
+          }
+          await runRecordPrompt(
+            {
+              operation: "update",
+              contactId: id,
+              currentDisplayName: current.displayName,
+              // What is stored, so the form can tell an accepted proposal from
+              // a field the guardian left alone.
+              currentNotes: current.notes ?? undefined,
+              displayName: opts.name,
+              // Seed the form's notes field with what the contact already has,
+              // so a name-only edit does not show an empty box the guardian
+              // then submits over their notes. `??` keeps an explicit
+              // `--notes ""` as the deliberate clear it is, and collapses the
+              // null a notes-less contact reads as into an omitted field.
+              notes: opts.notes ?? current.notes ?? undefined,
+              // An explicit --notes is a change the guardian confirms, even
+              // when it matches what is stored: comparison alone cannot tell
+              // that from stored notes the read could not see.
+              notesProposed: opts.notes !== undefined,
+              label: opts.label,
+              description: opts.description,
+            },
+            opts.timeout,
+            cmd,
+          );
+        },
+      );
+
+      subcommand(contacts, "delete").action(
+        async (
+          id: string,
+          opts: { label?: string; description?: string; timeout?: string },
+          cmd: Command,
+        ) => {
+          const current = await readContactForPrompt(id, cmd, true);
+          if (!current) {
+            return;
+          }
+          await runRecordPrompt(
+            {
+              operation: "delete",
+              contactId: id,
+              currentDisplayName: current.displayName,
+              // Two contacts can share a name, and deleting one takes its
+              // channels with it. The confirmation has to say which contact
+              // this is and what access is about to be lost.
+              channels: current.channels.map((ch) => ({
+                type: ch.type,
+                address: ch.address,
+              })),
+              label: opts.label,
+              description: opts.description,
+            },
+            opts.timeout,
+            cmd,
+          );
+        },
+      );
+
       // -----------------------------------------------------------------------
       // prompt
       // -----------------------------------------------------------------------
@@ -268,7 +601,10 @@ export function registerContactsCommand(program: Command): void {
           },
           cmd: Command,
         ) => {
-          const timeoutMs = opts.timeout ? parseInt(opts.timeout, 10) : 310_000;
+          const timeoutMs = parseFormTimeout(opts.timeout, cmd);
+          if (timeoutMs === null) {
+            return;
+          }
           const r = await cliIpcCall<ContactPromptResult>(
             "contacts_prompt",
             {
@@ -280,9 +616,10 @@ export function registerContactsCommand(program: Command): void {
                 label: opts.label,
                 description: opts.description,
                 verify: opts.verify === true,
+                timeoutMs,
               },
             },
-            { timeoutMs },
+            { timeoutMs: guardianFormCallBudgetMs(timeoutMs) },
           );
 
           if (!r.ok) {
@@ -306,7 +643,9 @@ export function registerContactsCommand(program: Command): void {
               `Registered ${result.channelType} channel: ${result.address}\n` +
                 `  Channel ID: ${result.channelId}\n` +
                 `  Contact ID: ${result.contactId}\n` +
-                `  Status:     ${opts.verify ? "verified" : "unverified"}\n`,
+                // The guardian's checkbox decides this, so report what the
+                // channel is rather than what the flag asked for.
+                `  Status:     ${result.verified ? "verified" : "unverified"}\n`,
             );
           }
         },

package/src/cli/commands/db/refresh.ts

@@ -48,6 +48,7 @@ function findHoldingPids(paths: string[]): number[] {
         encoding: "utf8",
         timeout: 5000,
         stdio: ["pipe", "pipe", "pipe"],
+        windowsHide: true,
       });
       for (const line of output.trim().split("\n")) {
         const pid = parseInt(line, 10);

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

@@ -778,8 +778,10 @@ form for any service other than the provider's default.
 
 The body (-d) is JSON by default. Give a non-JSON Content-Type and the body
 travels to the provider exactly as written, which is what multipart, XML, and
-form-encoded payloads need. Body files (-d @<path>) are read as UTF-8 text, so
-a payload that is not valid UTF-8 cannot be sent this way.
+form-encoded payloads need. Body files (-d @<path>) and stdin (-d @-) are
+read as raw bytes. Valid UTF-8 stays text (or JSON when the Content-Type is
+JSON). Anything else, including PDFs and other binary files, is sent to the
+provider byte for byte.
 
 Note: The Authorization header is set automatically. User-supplied
 -H "Authorization: ..." will be overridden by the OAuth bearer token.
@@ -790,7 +792,8 @@ Examples:
   $ assistant oauth request --provider twitter -X POST -d '{"text":"Hello"}' https://api.x.com/2/tweets
   $ assistant oauth request --provider google https://www.googleapis.com/calendar/v3/calendars/primary/events
   $ assistant oauth request --provider slack -H "Content-Type: application/json" -d '{"channel":"C123"}' /api/chat.postMessage --json
-  $ assistant oauth request --provider google -X POST -H "Content-Type: multipart/related; boundary=b" -d @upload.txt "https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart"`,
+  $ assistant oauth request --provider google -X POST -H "Content-Type: multipart/related; boundary=b" -d @upload.txt "https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart"
+  $ assistant oauth request --provider google -X POST -H "Content-Type: application/pdf" -d @report.pdf "https://www.googleapis.com/upload/drive/v3/files?uploadType=media"`,
     },
     {
       name: "disconnect",