@vellumai/cli 0.8.8-dev.202606082058.447e3b6 → 0.8.8-dev.202606082236.8dbacc9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.8.8-dev.202606082058.447e3b6",
+  "version": "0.8.8-dev.202606082236.8dbacc9",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/assistant-client-refresh.test.ts

@@ -27,8 +27,15 @@ import { loadGuardianToken, saveGuardianToken } from "../lib/guardian-token.js";
 
 const RUNTIME = "https://gw.example.com";
 const FUTURE = new Date(Date.now() + 90 * 24 * 60 * 60 * 1000).toISOString();
+const PAST = new Date(Date.now() - 60_000).toISOString();
 
-function seedPaired(refreshToken: string): void {
+/**
+ * Seed a paired assistant + guardian token. `due` (default true) controls
+ * whether the access token has reached its renewal point — the reactive
+ * 401-refresh only fires for a due token.
+ */
+function seedPaired(refreshToken: string, opts?: { due?: boolean }): void {
+  const due = opts?.due ?? true;
   saveAssistantEntry({
     assistantId: "px",
     name: "Paired",
@@ -40,10 +47,10 @@ function seedPaired(refreshToken: string): void {
   saveGuardianToken("px", {
     guardianPrincipalId: "imported",
     accessToken: "old-acc",
-    accessTokenExpiresAt: FUTURE,
+    accessTokenExpiresAt: due ? PAST : FUTURE,
     refreshToken,
     refreshTokenExpiresAt: refreshToken ? FUTURE : 0,
-    refreshAfter: "",
+    refreshAfter: due ? PAST : FUTURE,
     isNew: false,
     deviceId: "dev",
     leasedAt: new Date().toISOString(),
@@ -179,4 +186,58 @@ describe("AssistantClient 401 -> refresh -> retry", () => {
     expect(assistantAttempts).toBe(2); // original + one retry, no more
     expect(calls.filter((c) => isRefresh(c.url))).toHaveLength(1);
   });
+
+  test("does NOT refresh on a 401 when the stored token is not due for renewal", async () => {
+    // A forged/synthetic 401 on a still-valid token must not coax out the
+    // long-lived refresh credential.
+    seedPaired("refresh-tok", { due: false });
+    let assistantAttempts = 0;
+    const calls = stubFetch((url) => {
+      if (isRefresh(url)) return refreshResponse();
+      assistantAttempts++;
+      return new Response("", { status: 401 });
+    });
+
+    const client = new AssistantClient({ assistantId: "px" });
+    const res = await client.get("/messages/");
+
+    expect(res.status).toBe(401);
+    expect(assistantAttempts).toBe(1); // no retry
+    expect(calls.filter((c) => isRefresh(c.url))).toHaveLength(0); // refresh not attempted
+  });
+
+  test("adopts a token rotated by another process on a 401 (no refresh sent)", async () => {
+    // Construct the client capturing the current ("old-acc") token, then
+    // simulate a concurrent process (e.g. `vellum events`) rotating + persisting
+    // a fresh, not-due token. A 401 must pick up the fresh local token and retry
+    // WITHOUT sending the refresh credential.
+    seedPaired("refresh-tok", { due: false });
+    const client = new AssistantClient({ assistantId: "px" });
+    saveGuardianToken("px", {
+      guardianPrincipalId: "imported",
+      accessToken: "fresh-acc",
+      accessTokenExpiresAt: FUTURE,
+      refreshToken: "refresh-tok",
+      refreshTokenExpiresAt: FUTURE,
+      refreshAfter: FUTURE, // fresh — not due for renewal
+      isNew: false,
+      deviceId: "dev",
+      leasedAt: new Date().toISOString(),
+    });
+
+    const calls = stubFetch((url, log) => {
+      if (isRefresh(url)) return refreshResponse();
+      const auth = log[log.length - 1].headers["Authorization"];
+      return new Response("", {
+        status: auth === "Bearer fresh-acc" ? 200 : 401,
+      });
+    });
+
+    const res = await client.get("/messages/");
+
+    expect(res.status).toBe(200);
+    expect(calls.filter((c) => isRefresh(c.url))).toHaveLength(0); // no refresh sent
+    const assistantCalls = calls.filter((c) => !isRefresh(c.url));
+    expect(assistantCalls[1].headers["Authorization"]).toBe("Bearer fresh-acc");
+  });
 });

package/src/__tests__/guardian-token.test.ts

@@ -13,6 +13,7 @@ import { dirname, join } from "node:path";
 
 import {
   getOrCreatePersistedDeviceId,
+  guardianTokenDueForRenewal,
   loadGuardianToken,
   refreshGuardianToken,
   saveGuardianToken,
@@ -416,3 +417,59 @@ describe("refreshGuardianToken", () => {
     expect(called).toBe(false);
   });
 });
+
+describe("guardianTokenDueForRenewal", () => {
+  const FUTURE = new Date(Date.now() + 60 * 60 * 1000).toISOString();
+  const PAST = new Date(Date.now() - 60_000).toISOString();
+
+  function token(over: Partial<GuardianTokenData>): GuardianTokenData {
+    return {
+      guardianPrincipalId: "p",
+      accessToken: "a",
+      accessTokenExpiresAt: FUTURE,
+      refreshToken: "r",
+      refreshTokenExpiresAt: FUTURE,
+      refreshAfter: "",
+      isNew: false,
+      deviceId: "d",
+      leasedAt: new Date().toISOString(),
+      ...over,
+    };
+  }
+
+  test("past refreshAfter → due", () => {
+    expect(guardianTokenDueForRenewal(token({ refreshAfter: PAST }))).toBe(
+      true,
+    );
+  });
+
+  test("future refreshAfter → not due", () => {
+    expect(guardianTokenDueForRenewal(token({ refreshAfter: FUTURE }))).toBe(
+      false,
+    );
+  });
+
+  test("empty refreshAfter falls back to accessTokenExpiresAt (past → due)", () => {
+    expect(
+      guardianTokenDueForRenewal(
+        token({ refreshAfter: "", accessTokenExpiresAt: PAST }),
+      ),
+    ).toBe(true);
+  });
+
+  test("empty refreshAfter falls back to accessTokenExpiresAt (future → not due)", () => {
+    expect(
+      guardianTokenDueForRenewal(
+        token({ refreshAfter: "", accessTokenExpiresAt: FUTURE }),
+      ),
+    ).toBe(false);
+  });
+
+  test("unparseable timestamp → not due", () => {
+    expect(
+      guardianTokenDueForRenewal(
+        token({ refreshAfter: "not-a-date", accessTokenExpiresAt: "nope" }),
+      ),
+    ).toBe(false);
+  });
+});

package/src/__tests__/tui-midsession-refresh.test.ts

@@ -20,6 +20,7 @@ import { saveGuardianToken } from "../lib/guardian-token";
 
 const RUNTIME = "https://gw.example.com";
 const future = () => new Date(Date.now() + 60 * 60 * 1000).toISOString();
+const past = () => new Date(Date.now() - 60_000).toISOString();
 
 function seedEntry(cloud: string, localUrl?: string): void {
   saveAssistantEntry({
@@ -33,14 +34,19 @@ function seedEntry(cloud: string, localUrl?: string): void {
   });
 }
 
-function seedToken(accessToken: string, refreshToken: string): void {
+function seedToken(
+  accessToken: string,
+  refreshToken: string,
+  opts?: { due?: boolean },
+): void {
+  const due = opts?.due ?? true;
   saveGuardianToken("px", {
     guardianPrincipalId: "imported",
     accessToken,
-    accessTokenExpiresAt: future(),
+    accessTokenExpiresAt: due ? past() : future(),
     refreshToken,
     refreshTokenExpiresAt: refreshToken ? future() : 0,
-    refreshAfter: "",
+    refreshAfter: due ? past() : future(),
     isNew: false,
     deviceId: "dev",
     leasedAt: new Date().toISOString(),
@@ -202,4 +208,18 @@ describe("maybeRefreshAuthHeaders", () => {
     expect(ok).toBe(false);
     expect(auth.Authorization).toBe("Bearer old-acc");
   });
+
+  test("does NOT refresh when the stored token is not due for renewal", async () => {
+    // A forged 401 on a still-valid token must not coax out the refresh token.
+    seedEntry("paired");
+    seedToken("old-acc", "ref", { due: false });
+    const refresh = stubRefresh(true);
+    const auth = { Authorization: "Bearer old-acc" };
+
+    const ok = await maybeRefreshAuthHeaders(RUNTIME, "px", auth);
+
+    expect(ok).toBe(false);
+    expect(auth.Authorization).toBe("Bearer old-acc"); // unchanged
+    expect(refresh.hit()).toBe(false); // refresh not attempted
+  });
 });

package/src/commands/client.ts

@@ -16,7 +16,11 @@ import {
   GATEWAY_PORT,
   type Species,
 } from "../lib/constants";
-import { loadGuardianToken, refreshGuardianToken } from "../lib/guardian-token";
+import {
+  loadGuardianToken,
+  refreshGuardianToken,
+  guardianTokenDueForRenewal,
+} from "../lib/guardian-token";
 import { normalizeRuntimeUrl, trustedRefreshUrl } from "../lib/runtime-url";
 import {
   CLI_INTERFACE_ID,
@@ -876,11 +880,8 @@ export async function resolveFreshBearerToken(
     return bearerToken;
   }
 
-  // new Date() handles both ISO strings and epoch-ms numbers; Date.parse of an
-  // epoch-ms string would be NaN.
-  const renewAtRaw = stored.refreshAfter || stored.accessTokenExpiresAt;
-  const renewAt = new Date(renewAtRaw).getTime();
-  if (!Number.isFinite(renewAt) || renewAt > Date.now()) return bearerToken;
+  // Only refresh once the stored token is actually due for renewal.
+  if (!guardianTokenDueForRenewal(stored)) return bearerToken;
 
   // SECURITY: bind the refresh to the entry's persisted URL. `--url`/`-u` can
   // override `runtimeUrl` while still reusing this stored guardian token, so a

package/src/components/DefaultMainScreen.tsx

@@ -12,7 +12,11 @@ import { Box, render as inkRender, Text, useInput, useStdout } from "ink";
 import { SPECIES_CONFIG, type Species } from "../lib/constants";
 import { lookupAssistantByIdentifier } from "../lib/assistant-config";
 import { checkHealth } from "../lib/health-check";
-import { loadGuardianToken, refreshGuardianToken } from "../lib/guardian-token";
+import {
+  guardianTokenDueForRenewal,
+  loadGuardianToken,
+  refreshGuardianToken,
+} from "../lib/guardian-token";
 import { trustedRefreshUrl } from "../lib/runtime-url";
 import { appendHistory, loadHistory } from "../lib/input-history";
 import { tuiLog } from "../lib/tui-log";
@@ -232,6 +236,9 @@ export async function maybeRefreshAuthHeaders(
   if (!stored || stored.accessToken !== bearer || !stored.refreshToken) {
     return false;
   }
+  // Only refresh once the token is actually due for renewal, so a forged 401
+  // on a still-valid token can't coax out the long-lived refresh credential.
+  if (!guardianTokenDueForRenewal(stored)) return false;
   const refreshed = await refreshGuardianToken(refreshUrl, assistantId);
   if (!refreshed?.accessToken) return false;
   auth["Authorization"] = `Bearer ${refreshed.accessToken}`;

package/src/lib/assistant-client.ts

@@ -14,7 +14,11 @@
 
 import { resolveAssistant } from "./assistant-config.js";
 import { GATEWAY_PORT } from "./constants.js";
-import { loadGuardianToken, refreshGuardianToken } from "./guardian-token.js";
+import {
+  loadGuardianToken,
+  refreshGuardianToken,
+  guardianTokenDueForRenewal,
+} from "./guardian-token.js";
 
 const DEFAULT_TIMEOUT_MS = 30_000;
 const FALLBACK_RUNTIME_URL = `http://127.0.0.1:${GATEWAY_PORT}`;
@@ -219,21 +223,35 @@ export class AssistantClient {
 
     const response = await doFetch();
 
-    // Reactive auto-refresh: a paired/local guardian access token that has
-    // expired comes back 401. Refresh it once via the stored refresh credential
-    // and retry. Self-gating — refreshGuardianToken returns null unless a usable
-    // refresh token is stored, so ephemeral (`--token`) and access-only sessions
-    // just see the original 401. The platform session-auth path is never
-    // refreshed here (its token is managed by the Vellum platform).
+    // Reactive auto-refresh on a 401 for the guardian (non-session) path.
+    // Ephemeral (`--token`) and access-only sessions have no stored refresh
+    // credential and just see the original 401; the platform session-auth path
+    // is never refreshed here (its token is managed by the Vellum platform).
     if (response.status === 401 && !this.isSessionAuth) {
-      const refreshed = await refreshGuardianToken(
-        this.runtimeUrl,
-        this._assistantId,
-      );
-      if (refreshed?.accessToken) {
-        this.token = refreshed.accessToken;
+      const stored = loadGuardianToken(this._assistantId);
+
+      // Another process may have already rotated and persisted a fresh access
+      // token (e.g. a concurrent `vellum events`). Adopt it and retry — this
+      // sends no refresh credential, just picks up the newer local token.
+      if (stored?.accessToken && stored.accessToken !== this.token) {
+        this.token = stored.accessToken;
         return doFetch();
       }
+
+      // Otherwise only disclose the long-lived refresh token when our access
+      // token is actually due for renewal. A 401 on a still-valid token (e.g. a
+      // forged 401 from an impostor endpoint trying to coax out the refresh
+      // credential) is surfaced as-is, not refreshed.
+      if (stored?.refreshToken && guardianTokenDueForRenewal(stored)) {
+        const refreshed = await refreshGuardianToken(
+          this.runtimeUrl,
+          this._assistantId,
+        );
+        if (refreshed?.accessToken) {
+          this.token = refreshed.accessToken;
+          return doFetch();
+        }
+      }
     }
 
     return response;

package/src/lib/guardian-token.ts

@@ -285,6 +285,19 @@ function isConfidentialRefreshUrl(gatewayUrl: string): boolean {
   }
 }
 
+/**
+ * True when a stored guardian token has reached its renewal point — now is
+ * at/after `refreshAfter` (preferred) or `accessTokenExpiresAt`. Used to gate
+ * refresh so a forged/synthetic 401 on a still-valid token can't coax out the
+ * long-lived refresh credential. Unparseable timestamps → not due.
+ */
+export function guardianTokenDueForRenewal(token: GuardianTokenData): boolean {
+  const raw = token.refreshAfter || token.accessTokenExpiresAt;
+  const at = new Date(raw).getTime();
+  if (!Number.isFinite(at)) return false;
+  return at <= Date.now();
+}
+
 export async function refreshGuardianToken(
   gatewayUrl: string,
   assistantId: string,