@vellumai/cli 0.11.6 → 0.11.7-staging.2

package/node_modules/@vellumai/local-mode/src/devices.test.ts

@@ -49,6 +49,8 @@ describe("runDevicesList", () => {
               issuedAt: 1000,
               expiresAt: 2000,
               lastUsedAt: 1500,
+              pairingUserAgent: "Vellum/1.0 iOS",
+              clientReportedName: "Alice's iPhone",
             },
           ],
         }),
@@ -65,6 +67,8 @@ describe("runDevicesList", () => {
           issuedAt: 1000,
           expiresAt: 2000,
           lastUsedAt: 1500,
+          pairingUserAgent: "Vellum/1.0 iOS",
+          clientReportedName: "Alice's iPhone",
         },
       ],
     });
@@ -103,6 +107,64 @@ describe("runDevicesList", () => {
           issuedAt: null,
           expiresAt: null,
           lastUsedAt: null,
+          pairingUserAgent: null,
+          clientReportedName: null,
+        },
+      ],
+    });
+  });
+
+  test("non-string pairingUserAgent and clientReportedName parse to null without failing the record", async () => {
+    const pending = runDevicesList(invocation, "asst-42");
+    lastChild.stdout.emit(
+      "data",
+      Buffer.from(
+        JSON.stringify({
+          devices: [
+            {
+              hashedDeviceId: "hash-c",
+              platform: "android",
+              issuedAt: 1000,
+              expiresAt: 2000,
+              lastUsedAt: 1500,
+              pairingUserAgent: 42,
+              clientReportedName: { nested: true },
+            },
+            {
+              hashedDeviceId: "hash-d",
+              platform: "android",
+              issuedAt: 1000,
+              expiresAt: 2000,
+              lastUsedAt: 1500,
+              pairingUserAgent: null,
+              clientReportedName: null,
+            },
+          ],
+        }),
+      ),
+    );
+    lastChild.emit("close", 0);
+
+    expect(await pending).toEqual({
+      ok: true,
+      devices: [
+        {
+          hashedDeviceId: "hash-c",
+          platform: "android",
+          issuedAt: 1000,
+          expiresAt: 2000,
+          lastUsedAt: 1500,
+          pairingUserAgent: null,
+          clientReportedName: null,
+        },
+        {
+          hashedDeviceId: "hash-d",
+          platform: "android",
+          issuedAt: 1000,
+          expiresAt: 2000,
+          lastUsedAt: 1500,
+          pairingUserAgent: null,
+          clientReportedName: null,
         },
       ],
     });

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

@@ -16,6 +16,10 @@ export interface DeviceRecord {
   issuedAt: number | null;
   expiresAt: number | null;
   lastUsedAt: number | null;
+  /** Raw User-Agent observed when this device paired, or null. */
+  pairingUserAgent?: string | null;
+  /** Name the device reported for itself when pairing, or null. */
+  clientReportedName?: string | null;
   /** True when this row is the hosting machine's own guardian credential. */
   isCurrentHost?: boolean;
 }
@@ -104,6 +108,10 @@ function toTimestamp(value: unknown): number | null {
   return typeof value === "number" && Number.isFinite(value) ? value : null;
 }
 
+function toText(value: unknown): string | null {
+  return typeof value === "string" ? value : null;
+}
+
 function parseDeviceRecords(stdout: string): DeviceRecord[] | null {
   let parsed: unknown;
   try {
@@ -130,6 +138,8 @@ function parseDeviceRecords(stdout: string): DeviceRecord[] | null {
       issuedAt,
       expiresAt,
       lastUsedAt,
+      pairingUserAgent,
+      clientReportedName,
       isCurrentHost,
     } = entry as Record<string, unknown>;
     if (typeof hashedDeviceId !== "string" || typeof platform !== "string") {
@@ -141,6 +151,8 @@ function parseDeviceRecords(stdout: string): DeviceRecord[] | null {
       issuedAt: toTimestamp(issuedAt),
       expiresAt: toTimestamp(expiresAt),
       lastUsedAt: toTimestamp(lastUsedAt),
+      pairingUserAgent: toText(pairingUserAgent),
+      clientReportedName: toText(clientReportedName),
       // Tolerant passthrough: only a literal `true` survives.
       ...(isCurrentHost === true ? { isCurrentHost: true } : {}),
     });

package/node_modules/@vellumai/local-mode/src/guardian-token.ts

@@ -2,6 +2,11 @@ import { spawn } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 
+import {
+  isDnsIndependentLoopbackUrl,
+  isLoopbackPublicUrl,
+} from "@vellumai/service-contracts/remote-web-pairing";
+
 import { guardianTokenPath, resolveConfigDirPaths } from "./config";
 import type { CliInvocation } from "./util";
 
@@ -51,54 +56,42 @@ export function saveGuardianToken(
 
 /**
  * The guardian refresh token is long-lived and replayable, so it is only
- * transmitted over a confidential channel: HTTPS, or a loopback host (local
- * dev, or a same-host reverse proxy / tunnel agent). Refreshing against a
- * non-loopback plaintext `http://` URL is refused; an on-path attacker could
- * otherwise capture the refresh token and rotate it into fresh credentials.
+ * transmitted over a confidential channel: HTTPS, or a host that stays on this
+ * machine whatever DNS answers (local dev, or a same-host reverse proxy /
+ * tunnel agent). Refreshing against any other plaintext `http://` URL is
+ * refused; an on-path attacker could otherwise capture the refresh token and
+ * rotate it into fresh credentials.
  *
  * A user-chosen malicious `https://` destination is intentionally out of
  * scope: HTTPS protects the channel, and the access token already goes
  * wherever the configured URL points. This guard targets the
  * plaintext-interception vector.
  */
-function isLoopbackHostname(hostname: string): boolean {
-  // Strip URL brackets so IPv6 forms compare on the bare address.
-  const h = hostname.toLowerCase().replace(/^\[|\]$/g, "");
-  return (
-    h === "localhost" ||
-    h === "::1" ||
-    h === "0:0:0:0:0:0:0:1" ||
-    /^127(?:\.\d{1,3}){3}$/.test(h) ||
-    // Wildcard hosts reach a local listener when dialed (0.0.0.0 / ::), so
-    // they count as local for both the refresh-channel and pairing guards.
-    h === "0.0.0.0" ||
-    h === "0" ||
-    h === "::" ||
-    h === "0:0:0:0:0:0:0:0" ||
-    // IPv4-mapped loopback and wildcard, in dotted and hex encodings.
-    /^(?:0:0:0:0:0|:):ffff:127(?:\.\d{1,3}){3}$/.test(h) ||
-    /^(?:0:0:0:0:0|:):ffff:7f[0-9a-f]{2}:[0-9a-f]{1,4}$/.test(h) ||
-    /^(?:0:0:0:0:0|:):ffff:0\.0\.0\.0$/.test(h) ||
-    /^(?:0:0:0:0:0|:):ffff:0:0$/.test(h)
-  );
-}
-
 export function isConfidentialRefreshUrl(gatewayUrl: string): boolean {
   try {
-    const url = new URL(gatewayUrl);
-    return url.protocol === "https:" || isLoopbackHostname(url.hostname);
+    return (
+      new URL(gatewayUrl).protocol === "https:" ||
+      // The narrow loopback set, not {@link isLoopbackUrl}: this grants a
+      // plaintext channel the trust of an encrypted one, and a reserved
+      // `*.localhost` name resolves to whatever DNS says on a resolver that
+      // does not implement RFC 6761, which would put the refresh token on the
+      // wire to an arbitrary address.
+      isDnsIndependentLoopbackUrl(gatewayUrl)
+    );
   } catch {
     return false;
   }
 }
 
-/** Whether a URL's host is loopback; false for unparseable URLs. */
+/**
+ * Whether a URL's host is loopback, judged wide; false for unparseable URLs.
+ * Delegates to the shared pairing predicate so this package's refusals and the
+ * address checks in `@vellumai/service-contracts` judge a host by the same
+ * rules. Callers refuse what this matches; a caller granting loopback a
+ * privilege reads `isDnsIndependentLoopbackUrl` instead.
+ */
 export function isLoopbackUrl(url: string): boolean {
-  try {
-    return isLoopbackHostname(new URL(url).hostname);
-  } catch {
-    return false;
-  }
+  return isLoopbackPublicUrl(url);
 }
 
 function isAccessTokenExpired(data: GuardianTokenData): boolean {

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

@@ -4,8 +4,9 @@
  * hatch/retire/wake lifecycle ops) over a loopback HTTP boundary. Consumed by the
  * CLI `client` server and the web app's dev-server middleware so the local
  * endpoint behaviour is defined exactly once instead of one host reaching into
- * another's source tree. `@vellumai/environments` is its only workspace
- * dependency.
+ * another's source tree. `@vellumai/environments`,
+ * `@vellumai/service-contracts`, and the source-only
+ * `@vellumai/avatar-manifest` are its only workspace dependencies.
  */
 export {
   stripSensitiveFields,
@@ -59,7 +60,28 @@ export type { HatchResult } from "./hatch";
 export { runRetire } from "./retire";
 export type { RetireOptions, RetireResult } from "./retire";
 export { unpairAssistant } from "./unpair";
-export { decodePairBundle, pairAssistant, connectImport } from "./pair";
+export {
+  pairAssistant,
+  checkPairedAssistantName,
+  pairingStart,
+  pairingPoll,
+  pairingCancel,
+  connectImport,
+} from "./pair";
+export type {
+  PairedAssistantCredentials,
+  PairOptions,
+  PairResult,
+  PairRefusal,
+  PairingFailure,
+  PairingFailureReason,
+  PairingStarted,
+  PairingStartResult,
+  PairingPollOptions,
+  PairingPollResult,
+  ConnectImportOptions,
+  ConnectImportResult,
+} from "./pair";
 export { runSleep } from "./sleep";
 export type { SleepResult } from "./sleep";
 export { runWake } from "./wake";
@@ -73,6 +95,7 @@ export type {
 export { runUpgrade, isValidReleaseVersion } from "./upgrade";
 export type { UpgradeOptions, UpgradeResult } from "./upgrade";
 export { getLocalAssistantStatus } from "./status";
+export { readLockfileAssistantAvatar } from "./avatar";
 export type {
   LocalAssistantRuntimeState,
   LocalAssistantStatusResult,

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

@@ -190,7 +190,7 @@ export const LockfileAssistantSchema = z.object({
   /**
    * Public https URL a `vellum tunnel` provider recorded for this assistant
    * (mirrored from the workspace ingress config). A public address, so it is
-   * renderer-safe: remote-web pairing surfaces (the CLI `--qr` flow, the web
+   * renderer-safe: remote-web pairing surfaces (the `vellum pair` flow, the web
    * "Pair a device" card) default to it instead of asking the user to retype it.
    */
   ingressUrl: z.string().optional(),

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

@@ -41,6 +41,7 @@ describe("getLockfileData", () => {
     expect(result).toEqual({
       ok: true,
       data: { assistants: [], activeAssistant: null },
+      raw: { assistants: [], activeAssistant: null },
     });
   });
 

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

@@ -9,8 +9,10 @@ import {
 import { withLockfileLock } from "./lockfile-lock";
 import { stripSensitiveFields } from "./util";
 
+/** `raw` is the authoritative file's parsed JSON (unknown fields intact). */
 export type LockfileResult =
-  { ok: true; data: Lockfile } | { ok: false; status: number; error?: string };
+  | { ok: true; data: Lockfile; raw: Record<string, unknown> }
+  | { ok: false; status: number; error?: string };
 
 export function getLockfileData(lockfilePaths: string[]): LockfileResult {
   let raw: string | undefined;
@@ -26,7 +28,8 @@ export function getLockfileData(lockfilePaths: string[]): LockfileResult {
   }
 
   if (!raw) {
-    return { ok: true, data: { assistants: [], activeAssistant: null } };
+    const empty = { assistants: [], activeAssistant: null };
+    return { ok: true, data: empty, raw: empty };
   }
 
   let data: Record<string, unknown>;
@@ -36,7 +39,7 @@ export function getLockfileData(lockfilePaths: string[]): LockfileResult {
     return { ok: false, status: 500 };
   }
   stripSensitiveFields(data);
-  return { ok: true, data: parseLockfile(data) };
+  return { ok: true, data: parseLockfile(data), raw: data };
 }
 
 /**