@vellumai/cli 0.11.8 → 0.11.9-staging.1

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

@@ -182,12 +182,48 @@ export function renameLockfileAssistantIfPresent(
   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" };
   }
+  return patchLockfileAssistantIfPresent(lockfilePaths, assistantId, { name });
+}
+
+/**
+ * Record when an assistant finished first-run onboarding. Update-only, on the
+ * same terms as {@link renameLockfileAssistantIfPresent}. Keeps an existing
+ * stamp: the first completion is the real one, and a replayed funnel must not
+ * move it.
+ */
+export function stampLockfileAssistantOnboardedIfPresent(
+  lockfilePaths: string[],
+  assistantId: string,
+  onboardedAt: string,
+): WriteResult {
+  if (typeof onboardedAt !== "string" || onboardedAt === "") {
+    return { ok: false, status: 400, error: "Missing onboardedAt" };
+  }
+  return patchLockfileAssistantIfPresent(
+    lockfilePaths,
+    assistantId,
+    { onboardedAt },
+    (entry) => typeof entry.onboardedAt === "string" && entry.onboardedAt !== "",
+  );
+}
+
+/**
+ * The shared update-only write: read the on-disk registry under the lock,
+ * refuse a missing entry, and merge `patch` into it. `skip` short-circuits to
+ * a successful no-op for a field whose current value should win.
+ */
+function patchLockfileAssistantIfPresent(
+  lockfilePaths: string[],
+  assistantId: string,
+  patch: Record<string, unknown>,
+  skip?: (entry: Record<string, unknown>) => boolean,
+): WriteResult {
+  if (typeof assistantId !== "string" || assistantId === "") {
+    return { ok: false, status: 400, error: "Missing assistantId" };
+  }
 
   const locked = withLockfileLock(lockfilePaths, (): WriteResult => {
     const read = readRawLockfileStrict(lockfilePaths);
@@ -206,10 +242,14 @@ export function renameLockfileAssistantIfPresent(
         error: "No lockfile entry for this assistant",
       };
     }
-    if (assistants[idx]!.name === name) {
+    const entry = assistants[idx]!;
+    const converged =
+      skip?.(entry) ??
+      Object.entries(patch).every(([key, value]) => entry[key] === value);
+    if (converged) {
       return { ok: true, lockfile: toWireLockfile(lockfile) };
     }
-    assistants[idx] = { ...assistants[idx], name };
+    assistants[idx] = { ...entry, ...patch };
     lockfile.assistants = assistants;
     return writeRawLockfile(lockfilePaths, lockfile);
   });
@@ -354,7 +394,24 @@ export function replacePlatformAssistants(
       if (syncedIds.has(a.assistantId)) return false;
       return organizationId != null && a.organizationId !== organizationId;
     });
-    lockfile.assistants = [...preserved, ...platformAssistants];
+    // `onboardedAt` is recorded by the client and unknown to the platform, so
+    // the replacement rows never carry it. Without this it is erased by every
+    // routine session sync.
+    const priorOnboardedAt = new Map<string, unknown>();
+    for (const a of existing as Array<Record<string, unknown>>) {
+      if (typeof a?.assistantId === "string" && a.onboardedAt != null) {
+        priorOnboardedAt.set(a.assistantId, a.onboardedAt);
+      }
+    }
+    lockfile.assistants = [
+      ...preserved,
+      ...platformAssistants.map((a) => {
+        const prior = priorOnboardedAt.get(a.assistantId as string);
+        return a.onboardedAt == null && prior != null
+          ? { ...a, onboardedAt: prior }
+          : a;
+      }),
+    ];
 
     const active = lockfile.activeAssistant as string | null;
     if (active) {

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

@@ -22,7 +22,10 @@
     "./redacted-credential": "./src/redacted-credential.ts",
     "./secret-detection": "./src/secret-detection.ts",
     "./stripe-currency": "./src/stripe-currency.ts",
-    "./error": "./src/error.ts"
+    "./error": "./src/error.ts",
+    "./reactions": "./src/reactions.ts",
+    "./guardian-requests": "./src/guardian-requests.ts",
+    "./platform-credential": "./src/platform-credential.ts"
   },
   "scripts": {
     "typecheck": "bunx tsc --noEmit",

package/node_modules/@vellumai/service-contracts/src/guardian-requests.ts

@@ -0,0 +1,18 @@
+/**
+ * Canonical vocabulary for a guardian request's lifecycle status, shared by
+ * the gateway that owns the request rows, the daemon that decides and
+ * projects them, and the web that renders the projection.
+ */
+import { z } from "zod";
+
+export const GUARDIAN_REQUEST_STATUS_VALUES = [
+  "pending",
+  "approved",
+  "denied",
+  "expired",
+  "cancelled",
+] as const;
+export const GuardianRequestStatusSchema = z.enum(
+  GUARDIAN_REQUEST_STATUS_VALUES,
+);
+export type GuardianRequestStatus = z.infer<typeof GuardianRequestStatusSchema>;

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

@@ -28,6 +28,7 @@ export * from "./rpc.js";
 export * from "./trust-rules.js";
 export * from "./ingress.js";
 export * from "./no-response.js";
+export * from "./platform-credential.js";
 export * from "./remote-web-pairing.js";
 export * from "./twilio-ingress.js";
 export * from "./url-normalization.js";

package/node_modules/@vellumai/service-contracts/src/platform-credential.ts

@@ -0,0 +1,41 @@
+/**
+ * Wire contract for asking an assistant whether its stored platform-managed
+ * credential still authenticates.
+ *
+ * The daemon route is the authoritative serving side:
+ *   - `POST /v1/platform/verify-credential`
+ *       (`assistant/src/runtime/routes/platform-routes.ts`)
+ *
+ * The daemon's platform client produces the verdict, the route reports it,
+ * and the `vellum` CLI reads it before deciding whether a stored key can be
+ * re-injected (`cli/src/lib/assistant-api-key-resolution.ts`), so all three
+ * share one definition and cannot silently drift. The web app reads the same
+ * shape through its generated daemon client.
+ */
+import { z } from "zod";
+
+/**
+ * What the platform said about the stored credential, right now.
+ *
+ *   - `valid`: the platform accepted it.
+ *   - `rejected`: the platform refused it (unauthorized or forbidden); the
+ *     credential needs replacing.
+ *   - `unknown`: the check itself could not run (no credential stored, the
+ *     platform unreachable, a server error). Not evidence either way.
+ */
+export const PlatformCredentialVerificationStatusSchema = z.enum([
+  "valid",
+  "rejected",
+  "unknown",
+]);
+export type PlatformCredentialVerificationStatus = z.infer<
+  typeof PlatformCredentialVerificationStatusSchema
+>;
+
+/** `POST /v1/platform/verify-credential` response body. */
+export const PlatformVerifyCredentialResponseSchema = z.object({
+  status: PlatformCredentialVerificationStatusSchema,
+});
+export type PlatformVerifyCredentialResponse = z.infer<
+  typeof PlatformVerifyCredentialResponseSchema
+>;

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

@@ -0,0 +1,60 @@
+/**
+ * Canonical vocabulary for a reaction's emoji, shared by every service that
+ * handles one: the gateway that normalizes it, the daemon that stores and
+ * projects it, and the web that renders it.
+ *
+ * The kind is said by the channel rather than inferred from how the emoji
+ * is spelled. Modelled on Zulip's `reaction_type`, the one surveyed system
+ * that separates the namespace from the name.
+ *
+ * `shortcode` is a name in a channel's own namespace whose kind the channel
+ * does not disclose: Slack sends `+1` for the standard emoji and `blob_wave`
+ * for a workspace upload with nothing to tell them apart, and only the
+ * workspace token can resolve the second. It is a distinct kind from
+ * `unicode`, not a stand-in for an unknown one.
+ */
+import { z } from "zod";
+
+export const REACTION_EMOJI_KINDS = ["unicode", "shortcode", "custom"] as const;
+export type ReactionEmojiKind = (typeof REACTION_EMOJI_KINDS)[number];
+
+/**
+ * The typed emoji fields every schema that carries a reaction spreads in,
+ * so the wire contract, the stored envelopes, and the response projection
+ * describe one shape. Optional throughout: a persisted row or a replayed
+ * payload may carry only the spelling.
+ */
+export const ReactionEmojiFieldsSchema = z.object({
+  /** Which namespace the emoji was drawn from. */
+  emojiKind: z.enum(REACTION_EMOJI_KINDS).optional(),
+  /**
+   * The emoji's name in that namespace: the character itself for `unicode`,
+   * the bare name for `shortcode` and `custom`. Never a mention form.
+   */
+  emojiName: z.string().optional(),
+  /** The channel's id for a `custom` emoji, absent for every other kind. */
+  emojiId: z.string().optional(),
+  /** Whether a `custom` emoji animates. Absent for every other kind. */
+  emojiAnimated: z.boolean().optional(),
+});
+export type ReactionEmojiFields = z.infer<typeof ReactionEmojiFieldsSchema>;
+
+/**
+ * The typed emoji fields a source actually carries, with undefined ones
+ * omitted: an absent key and a present-but-undefined one serialize alike, but the
+ * stored envelope and the response should carry only what was declared. Every writer of a reaction shape (the wire
+ * payload, both stored envelopes, the response projection) copies the
+ * fields through this rather than restating the four-way pick.
+ */
+export function pickReactionEmojiFields(
+  source: ReactionEmojiFields,
+): ReactionEmojiFields {
+  return {
+    ...(source.emojiKind !== undefined ? { emojiKind: source.emojiKind } : {}),
+    ...(source.emojiName !== undefined ? { emojiName: source.emojiName } : {}),
+    ...(source.emojiId !== undefined ? { emojiId: source.emojiId } : {}),
+    ...(source.emojiAnimated !== undefined
+      ? { emojiAnimated: source.emojiAnimated }
+      : {}),
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.11.8",
+  "version": "0.11.9-staging.1",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/assistant-api-key-resolution.test.ts

@@ -0,0 +1,102 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import * as realPlatformClient from "../lib/platform-client.js";
+
+const calls: string[] = [];
+let verifyResult: "valid" | "rejected" | "unknown" | null = "valid";
+let readResult: { value: string | null; unreachable: boolean } = {
+  value: "stored-key",
+  unreachable: false,
+};
+
+mock.module("../lib/platform-client.js", () => ({
+  ...realPlatformClient,
+  verifyGatewayManagedCredential: mock(async () => {
+    calls.push("verify");
+    return verifyResult;
+  }),
+  readGatewayCredential: mock(async () => {
+    calls.push("read");
+    return readResult;
+  }),
+  reprovisionAssistantApiKey: mock(async () => {
+    calls.push("reprovision");
+    return { provisioning: { assistant_api_key: "fresh-key" } };
+  }),
+}));
+
+const { resolveAssistantApiKeyForInjection } =
+  await import("../lib/assistant-api-key-resolution.js");
+
+const ARGS = {
+  registrationApiKey: null,
+  runtimeUrl: "http://localhost:20101",
+  bearerToken: "actor",
+  token: "session",
+  organizationId: "org",
+  clientInstallationId: "install",
+  runtimeAssistantId: "qa-loopback-auth",
+  clientPlatform: "cli",
+};
+
+beforeEach(() => {
+  calls.length = 0;
+  verifyResult = "valid";
+  readResult = { value: "stored-key", unreachable: false };
+});
+
+describe("resolveAssistantApiKeyForInjection", () => {
+  test("a key the registration just issued wins without asking the gateway", async () => {
+    const resolved = await resolveAssistantApiKeyForInjection({
+      ...ARGS,
+      registrationApiKey: "registration-key",
+    });
+    expect(resolved).toEqual({
+      apiKey: "registration-key",
+      source: "registration",
+    });
+    expect(calls).toEqual([]);
+  });
+
+  // The verdict comes first and the key is read after it, so the value
+  // returned is the one the verdict covered, never one a concurrent repair
+  // has since replaced.
+  test("a stored key the platform accepts is read after the verdict", async () => {
+    const resolved = await resolveAssistantApiKeyForInjection(ARGS);
+    expect(resolved).toEqual({ apiKey: "stored-key", source: "stored" });
+    expect(calls).toEqual(["verify", "read"]);
+  });
+
+  test("a stored key the platform rejects is replaced without being read", async () => {
+    verifyResult = "rejected";
+    const resolved = await resolveAssistantApiKeyForInjection(ARGS);
+    expect(resolved).toEqual({ apiKey: "fresh-key", source: "reprovisioned" });
+    expect(calls).toEqual(["verify", "reprovision"]);
+  });
+
+  // An unsettled answer is not a rejection: the stored key stays in use.
+  test("an unsettled verdict keeps the stored key", async () => {
+    verifyResult = "unknown";
+    const resolved = await resolveAssistantApiKeyForInjection(ARGS);
+    expect(resolved).toEqual({ apiKey: "stored-key", source: "stored" });
+    expect(calls).not.toContain("reprovision");
+  });
+
+  // Rotating while the gateway is down would start the grace clock on a key
+  // the assistant still needs, with nowhere to store the replacement.
+  test("an unreachable gateway withholds rotation", async () => {
+    verifyResult = null;
+    readResult = { value: null, unreachable: true };
+    const resolved = await resolveAssistantApiKeyForInjection(ARGS);
+    expect(resolved).toEqual({ apiKey: null, source: "unavailable" });
+    expect(calls).not.toContain("reprovision");
+  });
+
+  test("a reachable assistant with no key stored is provisioned one", async () => {
+    verifyResult = "unknown";
+    readResult = { value: null, unreachable: false };
+    const resolved = await resolveAssistantApiKeyForInjection(ARGS);
+    expect(resolved).toEqual({ apiKey: "fresh-key", source: "reprovisioned" });
+    expect(calls).toEqual(["verify", "read", "reprovision"]);
+  });
+});

package/src/__tests__/constants.test.ts

@@ -21,10 +21,14 @@ describe("constants", () => {
 
   test("VALID_REMOTE_HOSTS includes expected hosts", () => {
     expect(VALID_REMOTE_HOSTS).toContain("local");
-    expect(VALID_REMOTE_HOSTS).toContain("gcp");
-    expect(VALID_REMOTE_HOSTS).toContain("aws");
     expect(VALID_REMOTE_HOSTS).toContain("docker");
     expect(VALID_REMOTE_HOSTS).toContain("custom");
+    expect(VALID_REMOTE_HOSTS).toContain("vellum");
+  });
+
+  test("VALID_REMOTE_HOSTS excludes cloud provisioning targets", () => {
+    expect(VALID_REMOTE_HOSTS).not.toContain("gcp");
+    expect(VALID_REMOTE_HOSTS).not.toContain("aws");
   });
 
   test("VALID_SPECIES includes expected species", () => {