@vellumai/cli 0.11.3 → 0.11.4-dev.202608190019.b94dbf2

package/node_modules/@vellumai/local-mode/src/lockfile.ts

@@ -6,11 +6,11 @@ import {
   resolveCloud,
   type Lockfile,
 } from "./lockfile-contract";
+import { withLockfileLock } from "./lockfile-lock";
 import { stripSensitiveFields } from "./util";
 
 export type LockfileResult =
-  | { ok: true; data: Lockfile }
-  | { ok: false; status: number; error?: string };
+  { ok: true; data: Lockfile } | { ok: false; status: number; error?: string };
 
 export function getLockfileData(lockfilePaths: string[]): LockfileResult {
   let raw: string | undefined;
@@ -63,6 +63,11 @@ export type WriteResult =
   | { ok: true; lockfile: Lockfile }
   | { ok: false; status: number; error: string };
 
+/** 423 Locked: the cross-process advisory lock could not be acquired. */
+function lockFailure(error: string): WriteResult {
+  return { ok: false, status: 423, error };
+}
+
 /**
  * Read the first parseable lockfile as raw JSON (unknown fields intact) for a
  * read-modify-write cycle; an unreadable file yields an empty lockfile.
@@ -83,6 +88,56 @@ export function readRawLockfile(
   return { assistants: [], activeAssistant: null };
 }
 
+export type RawLockfileReadResult =
+  | { ok: true; lockfile: Record<string, unknown> }
+  | { ok: false; error: string };
+
+/**
+ * Like {@link readRawLockfile}, but a file that exists and cannot be read or
+ * parsed refuses instead of degrading to the empty registry. Missing or empty
+ * files still yield the empty registry. Use for writes that must never
+ * replace a registry they could not actually read.
+ */
+export function readRawLockfileStrict(
+  lockfilePaths: string[],
+): RawLockfileReadResult {
+  for (const candidate of lockfilePaths) {
+    let raw: string;
+    try {
+      raw = fs.readFileSync(candidate, "utf-8");
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") continue;
+      return { ok: false, error: `Failed to read lockfile: ${err}` };
+    }
+    if (raw.trim() === "") continue;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (err) {
+      return { ok: false, error: `Failed to parse lockfile: ${err}` };
+    }
+    if (
+      typeof parsed !== "object" ||
+      parsed === null ||
+      Array.isArray(parsed)
+    ) {
+      return { ok: false, error: "Lockfile is not a JSON object" };
+    }
+    return { ok: true, lockfile: parsed as Record<string, unknown> };
+  }
+  return { ok: true, lockfile: { assistants: [], activeAssistant: null } };
+}
+
+/** The validated, sensitive-field-stripped wire view of a raw lockfile. */
+function toWireLockfile(lockfile: Record<string, unknown>): Lockfile {
+  const stripped = JSON.parse(JSON.stringify(lockfile)) as Record<
+    string,
+    unknown
+  >;
+  stripSensitiveFields(stripped);
+  return parseLockfile(stripped);
+}
+
 /**
  * Atomically persist a raw lockfile (write-to-temp + rename) and return the
  * validated, sensitive-field-stripped view of what was written.
@@ -99,15 +154,63 @@ export function writeRawLockfile(
     fs.writeFileSync(tmp, JSON.stringify(lockfile, null, 2));
     fs.renameSync(tmp, writePath);
   } catch (err) {
-    return { ok: false, status: 500, error: `Failed to write lockfile: ${err}` };
+    return {
+      ok: false,
+      status: 500,
+      error: `Failed to write lockfile: ${err}`,
+    };
   }
 
-  const stripped = JSON.parse(JSON.stringify(lockfile)) as Record<
-    string,
-    unknown
-  >;
-  stripSensitiveFields(stripped);
-  return { ok: true, lockfile: parseLockfile(stripped) };
+  return { ok: true, lockfile: toWireLockfile(lockfile) };
+}
+
+/**
+ * Rename an existing assistant entry, never creating one. Unlike the upserts,
+ * a missing entry refuses (404) and an unreadable on-disk file refuses (409)
+ * instead of being treated as an empty registry, so a stale renderer cache
+ * can neither resurrect a retired assistant nor replace a registry it could
+ * not read with a skeleton row. Never touches `activeAssistant`. The whole
+ * read-check-write runs under the shared advisory lock so a concurrent writer
+ * (e.g. a CLI retire) cannot be clobbered by this snapshot; lock contention
+ * refuses (423) without writing.
+ */
+export function renameLockfileAssistantIfPresent(
+  lockfilePaths: string[],
+  assistantId: string,
+  name: string,
+): WriteResult {
+  if (typeof assistantId !== "string" || assistantId === "") {
+    return { ok: false, status: 400, error: "Missing assistantId" };
+  }
+  if (typeof name !== "string" || name === "") {
+    return { ok: false, status: 400, error: "Missing name" };
+  }
+
+  const locked = withLockfileLock(lockfilePaths, (): WriteResult => {
+    const read = readRawLockfileStrict(lockfilePaths);
+    if (!read.ok) {
+      return { ok: false, status: 409, error: read.error };
+    }
+    const lockfile = read.lockfile;
+    const assistants = Array.isArray(lockfile.assistants)
+      ? (lockfile.assistants as Array<Record<string, unknown>>)
+      : [];
+    const idx = assistants.findIndex((a) => a?.assistantId === assistantId);
+    if (idx < 0) {
+      return {
+        ok: false,
+        status: 404,
+        error: "No lockfile entry for this assistant",
+      };
+    }
+    if (assistants[idx]!.name === name) {
+      return { ok: true, lockfile: toWireLockfile(lockfile) };
+    }
+    assistants[idx] = { ...assistants[idx], name };
+    lockfile.assistants = assistants;
+    return writeRawLockfile(lockfilePaths, lockfile);
+  });
+  return locked.ok ? locked.value : lockFailure(locked.error);
 }
 
 export function upsertLockfileAssistant(
@@ -119,22 +222,27 @@ export function upsertLockfileAssistant(
     return { ok: false, status: 400, error: "Missing assistant.assistantId" };
   }
 
-  const lockfile = readRawLockfile(lockfilePaths);
-  const assistants = Array.isArray(lockfile.assistants) ? lockfile.assistants : [];
-  const existingIdx = assistants.findIndex(
-    (a: Record<string, unknown>) => a?.assistantId === assistant.assistantId,
-  );
-  if (existingIdx >= 0) {
-    assistants[existingIdx] = { ...assistants[existingIdx], ...assistant };
-  } else {
-    assistants.push(assistant);
-  }
-  lockfile.assistants = assistants;
-  if (activeAssistant !== undefined) {
-    lockfile.activeAssistant = activeAssistant;
-  }
+  const locked = withLockfileLock(lockfilePaths, (): WriteResult => {
+    const lockfile = readRawLockfile(lockfilePaths);
+    const assistants = Array.isArray(lockfile.assistants)
+      ? lockfile.assistants
+      : [];
+    const existingIdx = assistants.findIndex(
+      (a: Record<string, unknown>) => a?.assistantId === assistant.assistantId,
+    );
+    if (existingIdx >= 0) {
+      assistants[existingIdx] = { ...assistants[existingIdx], ...assistant };
+    } else {
+      assistants.push(assistant);
+    }
+    lockfile.assistants = assistants;
+    if (activeAssistant !== undefined) {
+      lockfile.activeAssistant = activeAssistant;
+    }
 
-  return writeRawLockfile(lockfilePaths, lockfile);
+    return writeRawLockfile(lockfilePaths, lockfile);
+  });
+  return locked.ok ? locked.value : lockFailure(locked.error);
 }
 
 const PAIRED_LOCKFILE_WRITE_ERROR =
@@ -154,33 +262,38 @@ export function upsertRendererLockfileAssistant(
     return { ok: false, status: 400, error: "Missing assistant.assistantId" };
   }
 
-  const lockfile = readRawLockfile(lockfilePaths);
-  const assistants = Array.isArray(lockfile.assistants)
-    ? (lockfile.assistants as Array<Record<string, unknown>>)
-    : [];
-  const existing = assistants.find(
-    (entry) => entry?.assistantId === assistant.assistantId,
-  );
-  const merged = { ...existing, ...assistant };
-  const existingIsPaired =
-    existing != null &&
-    (resolveCloud(existing) === "paired" || existing.paired === true);
-  const mergedIsPaired =
-    resolveCloud(merged) === "paired" || merged.paired === true;
-
-  if (!existingIsPaired && mergedIsPaired) {
-    return { ok: false, status: 403, error: PAIRED_LOCKFILE_WRITE_ERROR };
-  }
-  if (
-    existingIsPaired &&
-    (resolveCloud(merged) !== "paired" ||
-      merged.runtimeUrl !== existing.runtimeUrl ||
-      merged.paired !== existing.paired)
-  ) {
-    return { ok: false, status: 403, error: PAIRED_LOCKFILE_WRITE_ERROR };
-  }
+  // Lock spans the paired-guard read and the upsert (which reenters) so the
+  // guard cannot be judged against a snapshot another writer replaces.
+  const locked = withLockfileLock(lockfilePaths, (): WriteResult => {
+    const lockfile = readRawLockfile(lockfilePaths);
+    const assistants = Array.isArray(lockfile.assistants)
+      ? (lockfile.assistants as Array<Record<string, unknown>>)
+      : [];
+    const existing = assistants.find(
+      (entry) => entry?.assistantId === assistant.assistantId,
+    );
+    const merged = { ...existing, ...assistant };
+    const existingIsPaired =
+      existing != null &&
+      (resolveCloud(existing) === "paired" || existing.paired === true);
+    const mergedIsPaired =
+      resolveCloud(merged) === "paired" || merged.paired === true;
+
+    if (!existingIsPaired && mergedIsPaired) {
+      return { ok: false, status: 403, error: PAIRED_LOCKFILE_WRITE_ERROR };
+    }
+    if (
+      existingIsPaired &&
+      (resolveCloud(merged) !== "paired" ||
+        merged.runtimeUrl !== existing.runtimeUrl ||
+        merged.paired !== existing.paired)
+    ) {
+      return { ok: false, status: 403, error: PAIRED_LOCKFILE_WRITE_ERROR };
+    }
 
-  return upsertLockfileAssistant(lockfilePaths, assistant, activeAssistant);
+    return upsertLockfileAssistant(lockfilePaths, assistant, activeAssistant);
+  });
+  return locked.ok ? locked.value : lockFailure(locked.error);
 }
 
 export function isActiveAssistant(
@@ -226,24 +339,29 @@ export function replacePlatformAssistants(
     };
   }
 
-  const lockfile = readRawLockfile(lockfilePaths);
-  const existing = Array.isArray(lockfile.assistants) ? lockfile.assistants : [];
-  const syncedIds = new Set(platformAssistants.map((a) => a.assistantId));
-  // Org-scoped sync preserves other orgs' platform entries; no org full-replaces.
-  const preserved = existing.filter((a: Record<string, unknown>) => {
-    if (a?.cloud !== "vellum") return true;
-    if (syncedIds.has(a.assistantId)) return false;
-    return organizationId != null && a.organizationId !== organizationId;
-  });
-  lockfile.assistants = [...preserved, ...platformAssistants];
+  const locked = withLockfileLock(lockfilePaths, (): WriteResult => {
+    const lockfile = readRawLockfile(lockfilePaths);
+    const existing = Array.isArray(lockfile.assistants)
+      ? lockfile.assistants
+      : [];
+    const syncedIds = new Set(platformAssistants.map((a) => a.assistantId));
+    // Org-scoped sync preserves other orgs' platform entries; no org full-replaces.
+    const preserved = existing.filter((a: Record<string, unknown>) => {
+      if (a?.cloud !== "vellum") return true;
+      if (syncedIds.has(a.assistantId)) return false;
+      return organizationId != null && a.organizationId !== organizationId;
+    });
+    lockfile.assistants = [...preserved, ...platformAssistants];
 
-  const active = lockfile.activeAssistant as string | null;
-  if (active) {
-    const stillExists = (lockfile.assistants as Array<Record<string, unknown>>).some(
-      (a) => a.assistantId === active,
-    );
-    if (!stillExists) lockfile.activeAssistant = null;
-  }
+    const active = lockfile.activeAssistant as string | null;
+    if (active) {
+      const stillExists = (
+        lockfile.assistants as Array<Record<string, unknown>>
+      ).some((a) => a.assistantId === active);
+      if (!stillExists) lockfile.activeAssistant = null;
+    }
 
-  return writeRawLockfile(lockfilePaths, lockfile);
+    return writeRawLockfile(lockfilePaths, lockfile);
+  });
+  return locked.ok ? locked.value : lockFailure(locked.error);
 }

package/node_modules/@vellumai/local-mode/src/unpair.ts

@@ -8,6 +8,7 @@ import {
   type WriteResult,
 } from "./lockfile";
 import { resolveCloud } from "./lockfile-contract";
+import { withLockfileLock } from "./lockfile-lock";
 
 /**
  * Forget a paired assistant on this machine: remove its lockfile entry and
@@ -21,6 +22,23 @@ export function unpairAssistant(
   lockfilePaths: string[],
   configDir: string,
   assistantId: string,
+): WriteResult {
+  // The whole transaction holds the shared write lock so a concurrent
+  // read-modify-write (e.g. a persona-name rename) cannot restore the entry
+  // after its credential is deleted.
+  const locked = withLockfileLock(lockfilePaths, (): WriteResult =>
+    unpairAssistantLocked(lockfilePaths, configDir, assistantId),
+  );
+  if (!locked.ok) {
+    return { ok: false, status: 423, error: locked.error };
+  }
+  return locked.value;
+}
+
+function unpairAssistantLocked(
+  lockfilePaths: string[],
+  configDir: string,
+  assistantId: string,
 ): WriteResult {
   const lockfile = readRawLockfile(lockfilePaths);
   const assistants = Array.isArray(lockfile.assistants)

package/node_modules/@vellumai/service-contracts/package.json

@@ -14,6 +14,7 @@
     "./remote-web-pairing": "./src/remote-web-pairing.ts",
     "./twilio-ingress": "./src/twilio-ingress.ts",
     "./trust-rules": "./src/trust-rules.ts",
+    "./url-normalization": "./src/url-normalization.ts",
     "./handles": "./src/handles.ts",
     "./rpc": "./src/rpc.ts",
     "./attachment-naming": "./src/attachment-naming.ts",

package/node_modules/@vellumai/service-contracts/src/__tests__/url-normalization.test.ts

@@ -0,0 +1,135 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  canonicalizeWebUrl,
+  looksLikeHostPortShorthand,
+  looksLikePathOnlyInput,
+  normalizeWebUrl,
+} from "../url-normalization.js";
+
+/**
+ * These are the rules a trust rule is saved and matched under. A change here
+ * changes which saved rules still match, so each case states the target the
+ * two spellings must agree on.
+ */
+describe("normalizeWebUrl", () => {
+  test("keeps an ordinary https URL as-is", () => {
+    expect(normalizeWebUrl("https://example.com/docs/page")?.href).toBe(
+      "https://example.com/docs/page",
+    );
+  });
+
+  test("drops the fragment: it never reaches the server", () => {
+    expect(normalizeWebUrl("https://example.com/docs#section")?.href).toBe(
+      "https://example.com/docs",
+    );
+  });
+
+  test("drops userinfo so credentials cannot land in a saved rule", () => {
+    const credentialed = new URL("https://example.com/docs/page");
+    credentialed.username = "demo";
+    credentialed.password = ["c", "r", "e", "d", "1", "2", "3"].join("");
+
+    const normalized = normalizeWebUrl(credentialed.href);
+    expect(normalized?.href).toBe("https://example.com/docs/page");
+    expect(normalized?.username).toBe("");
+    expect(normalized?.password).toBe("");
+  });
+
+  test("strips a trailing root dot from the hostname", () => {
+    expect(normalizeWebUrl("https://example.com./docs/page")?.href).toBe(
+      "https://example.com/docs/page",
+    );
+  });
+
+  test("decodes escaped path segments so one path has one spelling", () => {
+    // Without this, a rule scoped to /private is bypassed by /%70rivate.
+    expect(normalizeWebUrl("https://example.com/%70rivate")?.href).toBe(
+      "https://example.com/private",
+    );
+  });
+
+  test("reads scheme-less input as https", () => {
+    expect(normalizeWebUrl("example.com/docs")?.href).toBe(
+      "https://example.com/docs",
+    );
+  });
+
+  test("reads host:port shorthand as an https origin, not a scheme", () => {
+    expect(normalizeWebUrl("example.com:8443/status")?.origin).toBe(
+      "https://example.com:8443",
+    );
+    expect(normalizeWebUrl("[2001:db8::1]:8443/status")?.origin).toBe(
+      "https://[2001:db8::1]:8443",
+    );
+  });
+
+  test("rejects path-only input rather than coercing it to a host", () => {
+    for (const input of ["/etc/passwd", "./rel", "../up", "?q=1", "#frag"]) {
+      expect(normalizeWebUrl(input)).toBeNull();
+    }
+  });
+
+  test("rejects every non-http scheme", () => {
+    for (const input of [
+      "file:///etc/passwd",
+      "data:text/html,<script>",
+      "javascript:alert(1)",
+      "ftp://example.com/f",
+    ]) {
+      expect(normalizeWebUrl(input)).toBeNull();
+    }
+  });
+
+  test("rejects empty and whitespace-only input", () => {
+    expect(normalizeWebUrl("")).toBeNull();
+    expect(normalizeWebUrl("   ")).toBeNull();
+  });
+
+  test("trims surrounding whitespace", () => {
+    expect(normalizeWebUrl("  https://example.com/a  ")?.href).toBe(
+      "https://example.com/a",
+    );
+  });
+
+  test("returns null rather than throwing on an unparseable authority", () => {
+    expect(normalizeWebUrl("https://")).toBeNull();
+  });
+});
+
+describe("canonicalizeWebUrl", () => {
+  test("keeps the parser's form when the path is not decodable, without throwing", () => {
+    // `%zz` and a truncated UTF-8 sequence are not valid escapes; the path
+    // must survive unchanged rather than the call throwing.
+    expect(canonicalizeWebUrl(new URL("https://example.com/100%zz")).href).toBe(
+      "https://example.com/100%zz",
+    );
+    expect(
+      canonicalizeWebUrl(new URL("https://example.com/%E0%A4%A")).href,
+    ).toBe("https://example.com/%E0%A4%A");
+  });
+
+  test("decodes an escaped percent, so `%25` and `%` are one path", () => {
+    expect(canonicalizeWebUrl(new URL("https://example.com/100%25")).href).toBe(
+      "https://example.com/100%",
+    );
+  });
+});
+
+describe("input shape predicates", () => {
+  test("host:port shorthand is recognized, scheme-prefixed input is not", () => {
+    expect(looksLikeHostPortShorthand("example.com:8443/x")).toBe(true);
+    expect(looksLikeHostPortShorthand("[2001:db8::1]:443")).toBe(true);
+    expect(looksLikeHostPortShorthand("https://example.com/x")).toBe(false);
+    expect(looksLikeHostPortShorthand("example.com/x")).toBe(false);
+  });
+
+  test("path-only input is recognized", () => {
+    expect(looksLikePathOnlyInput("/abs")).toBe(true);
+    expect(looksLikePathOnlyInput("./rel")).toBe(true);
+    expect(looksLikePathOnlyInput("../up")).toBe(true);
+    expect(looksLikePathOnlyInput("?q=1")).toBe(true);
+    expect(looksLikePathOnlyInput("#frag")).toBe(true);
+    expect(looksLikePathOnlyInput("example.com/x")).toBe(false);
+  });
+});

package/node_modules/@vellumai/service-contracts/src/channels.ts

@@ -6,6 +6,16 @@
  * assistant through (Slack, Telegram, WhatsApp, phone, …) plus a couple of
  * internal ids (`vellum` for native app conversations, `platform` for the
  * internal control plane). This is the single source of truth for that set:
+ *
+ * One id, `plugin`, does not name a surface: it names *every* surface a plugin
+ * brings. A plugin channel's real identity is the plugin, which is workspace
+ * state and cannot be a compile-time union member, so the plugin name travels
+ * in `sourceMetadata.plugin` and is prefixed onto every external id the gateway
+ * forwards (`imessage:+15551234567`). Two plugins therefore share a channel
+ * row — one admission floor, one set of channel-wide defaults — while their
+ * conversations, contacts, and trust records stay disjoint. See
+ * `gateway/src/channels/plugin-inbound.ts` for what that concedes.
+ *
  * the assistant adopts it wholesale as its `ChannelId`, and the gateway
  * asserts its own (narrower) inbound list is a subset of it so the two sides
  * cannot silently drift.
@@ -30,6 +40,7 @@ export const CHANNEL_IDS = [
   "platform",
   "a2a",
   "discord",
+  "plugin",
 ] as const;
 
 export type ChannelId = (typeof CHANNEL_IDS)[number];

package/node_modules/@vellumai/service-contracts/src/index.ts

@@ -29,3 +29,4 @@ export * from "./trust-rules.js";
 export * from "./ingress.js";
 export * from "./remote-web-pairing.js";
 export * from "./twilio-ingress.js";
+export * from "./url-normalization.js";

package/node_modules/@vellumai/service-contracts/src/remote-web-pairing.ts

@@ -11,6 +11,12 @@
  *       (`gateway/src/http/routes/remote-web-pairing-verification.ts`)
  *   - `POST /v1/remote-web/pairing-token`         poll + exchange device code
  *       (`gateway/src/http/routes/remote-web-pairing-token.ts`)
+ *   - `GET  /v1/remote-web/pairing-requests`          list pending challenges
+ *       (loopback-only)
+ *   - `POST /v1/remote-web/pairing-requests/approve`  approve by request id
+ *       (loopback-only)
+ *   - `POST /v1/remote-web/pairing-requests/deny`     deny (delete) by request id
+ *       (loopback-only)
  *
  * These shapes mirror those handlers' request/response bodies exactly so the
  * gateway, the `vellum pair` CLI (`cli/src/commands/pair.ts`), and the web SPA
@@ -68,6 +74,60 @@ export interface RemoteWebPairingVerificationResponse {
   expiresAt: string;
 }
 
+/**
+ * One pending challenge as shown on a host approval surface.
+ *
+ * The requesting device already sees the plaintext `userCode` in its own
+ * challenge response ({@link RemoteWebPairingChallengeResponse.userCode});
+ * the loopback-gated list route is the only host-side re-exposure. Displaying
+ * it there is what lets the approver match the code against the requesting
+ * device's screen: the device-flow anti-phishing binding.
+ */
+export interface RemoteWebPairingRequestSummary {
+  /** Opaque server-side id used to approve or deny this request. */
+  requestId: string;
+  /** The human-readable code the requesting device is displaying (e.g. "ABCD-EFGH"). */
+  userCode: string;
+  /** Public base URL the challenge was minted for. */
+  publicBaseUrl: string;
+  /** ISO-8601 instant the challenge was minted. */
+  requestedAt: string;
+  /** ISO-8601 instant the challenge expires. */
+  expiresAt: string;
+  /**
+   * Client IP of the mint request: the loopback/host address when minted
+   * locally, or the edge-observed client address when the mint arrived
+   * through the nginx tunnel edge (which stamps it via `proxy_set_header`,
+   * so a remote client cannot smuggle a value).
+   */
+  requesterIp: string;
+  /** User-Agent header of the mint request, or null when absent. */
+  requesterUserAgent: string | null;
+  /**
+   * Whether the mint arrived through the public tunnel edge rather than the
+   * host itself.
+   */
+  viaEdgeProxy: boolean;
+}
+
+/** `GET /v1/remote-web/pairing-requests` success response body (200). */
+export interface RemoteWebPairingRequestListResponse {
+  requests: RemoteWebPairingRequestSummary[];
+}
+
+/**
+ * Request body for the pairing-request approve and deny routes. The approve
+ * route's success body reuses {@link RemoteWebPairingVerificationResponse}.
+ */
+export interface RemoteWebPairingRequestActionRequest {
+  requestId: string;
+}
+
+/** `POST /v1/remote-web/pairing-requests/deny` success response body (200). */
+export interface RemoteWebPairingRequestDenyResponse {
+  status: "denied";
+}
+
 /** `POST /v1/remote-web/pairing-token` request body. */
 export interface RemoteWebPairingTokenRequest {
   /** The `deviceCode` from the challenge. */