@vellumai/cli 0.11.8 → 0.11.9-staging.2

package/README.md

@@ -54,18 +54,17 @@ vellum hatch [species] [options]
 
 #### Options
 
-| Option              | Description                                                                                                        |
-| ------------------- | ------------------------------------------------------------------------------------------------------------------ |
-| `-d`                | Detached mode. Start the instance in the background without watching startup progress.                             |
-| `--name <name>`     | Use a specific instance name instead of an auto-generated one.                                                     |
-| `--remote <target>` | Where to provision the instance. One of: `local`, `docker`, `vellum`, `gcp`, `aws`, `custom`. Defaults to `local`. |
+| Option              | Description                                                                                          |
+| ------------------- | ---------------------------------------------------------------------------------------------------- |
+| `-d`                | Detached mode. Start the instance in the background without watching startup progress.               |
+| `--name <name>`     | Use a specific instance name instead of an auto-generated one.                                       |
+| `--remote <target>` | Where to provision the instance. One of: `local`, `docker`, `vellum`, `custom`. Defaults to `local`. |
 
 #### Remote Targets
 
 - **`local`** -- Starts the local assistant and local gateway. Gateway source resolution order is: repo source tree, then installed `@vellumai/vellum-gateway` package.
 - **`docker`** -- Starts the assistant, gateway, and credential service in Docker containers.
 - **`vellum`** -- Hatches an assistant on the Vellum platform.
-- **`gcp`** and **`aws`** -- Recognized but not supported as provisioning targets yet. The CLI exits before creating cloud resources. To self-host on AWS/GCP, SSH into the VM and run `vellum hatch` or `vellum hatch --remote docker` there.
 - **`custom`** -- Recognized but not yet implemented.
 
 #### Environment Variables
@@ -87,7 +86,7 @@ vellum hatch --remote docker
 vellum hatch --name my-assistant --remote docker
 ```
 
-AWS and GCP hatch targets are recognized so users receive an explicit unsupported-target error instead of an unknown-option error. They currently exit without creating cloud resources; self-hosting on an AWS/GCP VM still works by running `vellum hatch` from inside that machine.
+To self-host on a cloud VM (AWS, GCP, or any other provider), SSH into the machine and run `vellum hatch` or `vellum hatch --remote docker` from inside it. The CLI does not provision cloud instances for you.
 
 ### `terminal`
 

package/knip.json

@@ -2,7 +2,6 @@
   "entry": [
     "src/**/*.test.ts",
     "src/**/__tests__/**/*.ts",
-    "src/adapters/openclaw-http-server.ts",
     "src/lib/version-compat.ts",
     "src/lib/platform-releases.ts",
     "src/lib/cli-error.ts"

package/node_modules/@vellumai/local-mode/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/local-mode/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/local-mode/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/local-mode/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/local-mode/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/node_modules/@vellumai/local-mode/src/__tests__/guardian-token-refresh.test.ts

@@ -1,17 +1,11 @@
 import { afterEach, beforeAll, beforeEach, describe, expect, mock, test } from "bun:test";
-import { EventEmitter } from "node:events";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
 import type { CliInvocation } from "../util";
 import type { GuardianTokenData } from "../guardian-token";
-
-class FakeChild extends EventEmitter {
-  stdout = new EventEmitter();
-  stderr = new EventEmitter();
-  kill = mock(() => true);
-}
+import { FakeChild, mockChildProcessSpawn } from "./helpers/child-process-mock";
 
 let lastChild: FakeChild;
 const spawnMock = mock((_command: string, _args: string[]) => {
@@ -19,7 +13,7 @@ const spawnMock = mock((_command: string, _args: string[]) => {
   return lastChild;
 });
 
-mock.module("node:child_process", () => ({ spawn: spawnMock }));
+await mockChildProcessSpawn(spawnMock);
 
 let getGuardianAccessToken: typeof import("../guardian-token").getGuardianAccessToken;
 let saveGuardianToken: typeof import("../guardian-token").saveGuardianToken;

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

@@ -1,13 +1,7 @@
 import { afterEach, beforeAll, describe, expect, mock, test } from "bun:test";
-import { EventEmitter } from "node:events";
 
 import type { CliInvocation } from "../util";
-
-class FakeChild extends EventEmitter {
-  stdout = new EventEmitter();
-  stderr = new EventEmitter();
-  kill = mock(() => true);
-}
+import { FakeChild, mockChildProcessSpawn } from "./helpers/child-process-mock";
 
 let lastChild: FakeChild;
 const spawnArgs: Array<[string, string[]]> = [];
@@ -17,7 +11,7 @@ const spawnMock = mock((command: string, args: string[]) => {
   return lastChild;
 });
 
-mock.module("node:child_process", () => ({ spawn: spawnMock }));
+await mockChildProcessSpawn(spawnMock);
 
 let runHatch: typeof import("../hatch").runHatch;
 

package/node_modules/@vellumai/local-mode/src/__tests__/helpers/child-process-mock.ts

@@ -0,0 +1,55 @@
+import { EventEmitter } from "node:events";
+import { mock } from "bun:test";
+
+/**
+ * Stand-in for the `ChildProcess` a mocked `spawn` returns. Tests drive it by
+ * emitting `"close"` / `"error"` on the instance and `"data"` on its streams.
+ */
+export class FakeChild extends EventEmitter {
+  stdout = new EventEmitter();
+  stderr = new EventEmitter();
+  kill = mock(() => true);
+}
+
+/** Any stand-in for `spawn`; each suite records the arguments it asserts on. */
+type SpawnReplacement = (...args: never[]) => unknown;
+
+/**
+ * Replace `spawn` in `node:child_process` while leaving every other export of
+ * the module intact.
+ *
+ * `mock.module()` is process-global, and a registration that lands before
+ * anything in the process has loaded `node:child_process` installs the
+ * factory's object as the entire module. A factory returning only `{ spawn }`
+ * therefore strips `spawnSync` and the rest for every module linked
+ * afterwards. `src/lockfile-lock.test.ts` imports `spawnSync` at module scope
+ * and fails to link with "Export named 'spawnSync' not found in module
+ * 'node:child_process'" once that happens, and since bun runs a package's test
+ * files in one process, whether it happens depends on file ordering.
+ *
+ * Two things keep the namespace whole:
+ *
+ * 1. Awaiting the real module materializes it before `mock.module()`
+ *    registers. Bun patches that live namespace in place, so the exports the
+ *    factory does not name keep their real values. This is the property that
+ *    prevents the link error.
+ * 2. The factory returns a plain copy of the namespace captured before
+ *    registration, so the replacement is complete on its own terms and never
+ *    reads back through the namespace being patched. Spreading a live,
+ *    already-mocked namespace inside a factory is the shape that
+ *    `cli/src/__tests__/helpers/os-mock.ts` documents as recursing forever.
+ *
+ * Every `node:child_process` spawn mock in this package routes through here so
+ * both hold for all of them at once. Call it once at module scope, with
+ * `await`, before the module under test is imported.
+ */
+export async function mockChildProcessSpawn(
+  spawnMock: SpawnReplacement,
+): Promise<void> {
+  const realChildProcess = await import("node:child_process");
+  const realChildProcessSnapshot = { ...realChildProcess };
+  mock.module("node:child_process", () => ({
+    ...realChildProcessSnapshot,
+    spawn: spawnMock,
+  }));
+}

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

@@ -1,13 +1,7 @@
 import { afterEach, beforeAll, describe, expect, mock, test } from "bun:test";
-import { EventEmitter } from "node:events";
 
 import type { CliInvocation } from "../util";
-
-class FakeChild extends EventEmitter {
-  stdout = new EventEmitter();
-  stderr = new EventEmitter();
-  kill = mock(() => true);
-}
+import { FakeChild, mockChildProcessSpawn } from "./helpers/child-process-mock";
 
 let lastChild: FakeChild;
 const spawnArgs: Array<
@@ -25,7 +19,7 @@ const spawnMock = mock(
   },
 );
 
-mock.module("node:child_process", () => ({ spawn: spawnMock }));
+await mockChildProcessSpawn(spawnMock);
 
 let runRetire: typeof import("../retire").runRetire;
 

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

@@ -1,13 +1,7 @@
 import { afterEach, beforeAll, describe, expect, mock, test } from "bun:test";
-import { EventEmitter } from "node:events";
 
 import type { CliInvocation } from "../util";
-
-class FakeChild extends EventEmitter {
-  stdout = new EventEmitter();
-  stderr = new EventEmitter();
-  kill = mock(() => true);
-}
+import { FakeChild, mockChildProcessSpawn } from "./helpers/child-process-mock";
 
 let lastChild: FakeChild;
 const spawnArgs: Array<
@@ -25,7 +19,7 @@ const spawnMock = mock(
   },
 );
 
-mock.module("node:child_process", () => ({ spawn: spawnMock }));
+await mockChildProcessSpawn(spawnMock);
 
 let runUpgrade: typeof import("../upgrade").runUpgrade;
 let isValidReleaseVersion: typeof import("../upgrade").isValidReleaseVersion;

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

@@ -1,13 +1,7 @@
 import { afterEach, beforeAll, describe, expect, mock, test } from "bun:test";
-import { EventEmitter } from "node:events";
 
 import type { CliInvocation } from "../util";
-
-class FakeChild extends EventEmitter {
-  stdout = new EventEmitter();
-  stderr = new EventEmitter();
-  kill = mock(() => true);
-}
+import { FakeChild, mockChildProcessSpawn } from "./helpers/child-process-mock";
 
 let lastChild: FakeChild;
 const spawnArgs: Array<[string, string[]]> = [];
@@ -17,7 +11,7 @@ const spawnMock = mock((command: string, args: string[]) => {
   return lastChild;
 });
 
-mock.module("node:child_process", () => ({ spawn: spawnMock }));
+await mockChildProcessSpawn(spawnMock);
 
 let runWake: typeof import("../wake").runWake;
 

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

@@ -1,13 +1,10 @@
 import { afterEach, beforeAll, describe, expect, mock, test } from "bun:test";
-import { EventEmitter } from "node:events";
 
 import type { CliInvocation } from "./util";
-
-class FakeChild extends EventEmitter {
-  stdout = new EventEmitter();
-  stderr = new EventEmitter();
-  kill = mock(() => true);
-}
+import {
+  FakeChild,
+  mockChildProcessSpawn,
+} from "./__tests__/helpers/child-process-mock";
 
 let lastChild: FakeChild;
 const spawnArgs: Array<[string, string[], { stdio?: unknown; windowsHide?: boolean }]> = [];
@@ -19,7 +16,7 @@ const spawnMock = mock(
   },
 );
 
-mock.module("node:child_process", () => ({ spawn: spawnMock }));
+await mockChildProcessSpawn(spawnMock);
 
 let runDevicesList: typeof import("./devices").runDevicesList;
 let runDevicesRevoke: typeof import("./devices").runDevicesRevoke;

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

@@ -44,6 +44,7 @@ export {
 export {
   getLockfileData,
   renameLockfileAssistantIfPresent,
+  stampLockfileAssistantOnboardedIfPresent,
   upsertLockfileAssistant,
   upsertRendererLockfileAssistant,
   replacePlatformAssistants,

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

@@ -179,6 +179,12 @@ export const LockfileAssistantSchema = z.object({
   runtimeUrl: z.string().optional(),
   species: z.string().optional(),
   hatchedAt: z.string().optional(),
+  /**
+   * When this assistant finished first-run onboarding. Absent for entries that
+   * predate the record, which fall back to hatch age (see the web client's
+   * `onboarded-assistant.ts`).
+   */
+  onboardedAt: z.string().optional(),
   /** Owning org for platform assistants; absent for local ones. */
   organizationId: z.string().optional(),
   /** Platform assistant UUID for a self-hosted local assistant registration. */

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

@@ -7,6 +7,7 @@ import {
   getLockfileData,
   isPairedLockfileEntry,
   renameLockfileAssistantIfPresent,
+  stampLockfileAssistantOnboardedIfPresent,
   replacePlatformAssistants,
   upsertLockfileAssistant,
   upsertRendererLockfileAssistant,
@@ -280,6 +281,87 @@ describe("upsertLockfileAssistant", () => {
   });
 });
 
+describe("stampLockfileAssistantOnboardedIfPresent", () => {
+  const entry = {
+    assistantId: "asst_1",
+    cloud: "local",
+    name: "Credence",
+    signingKey: "sk-on-disk-secret",
+  };
+  const AT = "2026-08-31T00:00:00.000Z";
+
+  test("stamps the entry preserving its other fields and activeAssistant", () => {
+    writeOnDisk({ activeAssistant: "asst_other", assistants: [entry] });
+
+    const result = stampLockfileAssistantOnboardedIfPresent(
+      [lockfilePath],
+      "asst_1",
+      AT,
+    );
+
+    expect(result.ok).toBe(true);
+    const onDisk = readOnDisk();
+    expect(onDisk.activeAssistant).toBe("asst_other");
+    expect(onDisk.assistants).toEqual([{ ...entry, onboardedAt: AT }]);
+  });
+
+  // Update-only: a completion racing a CLI retire must not resurrect the row.
+  test("refuses a missing entry without writing the file", () => {
+    const result = stampLockfileAssistantOnboardedIfPresent(
+      [lockfilePath],
+      "asst_gone",
+      AT,
+    );
+
+    expect(result).toEqual({
+      ok: false,
+      status: 404,
+      error: "No lockfile entry for this assistant",
+    });
+    expect(fs.existsSync(lockfilePath)).toBe(false);
+  });
+
+  test("keeps an existing stamp: the first completion is the real one", () => {
+    const stamped = { ...entry, onboardedAt: "2026-08-01T00:00:00.000Z" };
+    writeOnDisk({ activeAssistant: null, assistants: [stamped] });
+
+    const result = stampLockfileAssistantOnboardedIfPresent(
+      [lockfilePath],
+      "asst_1",
+      AT,
+    );
+
+    expect(result.ok).toBe(true);
+    expect(readOnDisk().assistants).toEqual([stamped]);
+  });
+
+  test("refuses a corrupt on-disk file without clobbering it", () => {
+    fs.writeFileSync(lockfilePath, "{ not json");
+
+    const result = stampLockfileAssistantOnboardedIfPresent(
+      [lockfilePath],
+      "asst_1",
+      AT,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.status).toBe(409);
+    }
+    expect(fs.readFileSync(lockfilePath, "utf-8")).toBe("{ not json");
+  });
+
+  test("rejects a missing id or timestamp", () => {
+    expect(
+      stampLockfileAssistantOnboardedIfPresent([lockfilePath], "", AT).ok,
+    ).toBe(false);
+    expect(
+      stampLockfileAssistantOnboardedIfPresent([lockfilePath], "asst_1", "").ok,
+    ).toBe(false);
+    expect(fs.existsSync(lockfilePath)).toBe(false);
+  });
+});
+
 describe("renameLockfileAssistantIfPresent", () => {
   const entry = {
     assistantId: "asst_1",
@@ -596,6 +678,89 @@ describe("replacePlatformAssistants", () => {
     });
   });
 
+  // `onboardedAt` is recorded by the client and unknown to the platform, so the
+  // rows a sync builds from the API never carry it. Dropping it here would let
+  // a routine session refresh erase the completion record.
+  test("carries an existing onboardedAt onto the replacement row", () => {
+    writeOnDisk({
+      activeAssistant: "asst_p",
+      assistants: [
+        {
+          assistantId: "asst_p",
+          cloud: "vellum",
+          runtimeUrl: "http://old",
+          onboardedAt: "2026-08-01T00:00:00.000Z",
+        },
+      ],
+    });
+
+    const result = replacePlatformAssistants(
+      [lockfilePath],
+      [{ assistantId: "asst_p", cloud: "vellum", runtimeUrl: "http://new" }],
+    );
+
+    expect(result.ok).toBe(true);
+    expect(readOnDisk().assistants).toEqual([
+      {
+        assistantId: "asst_p",
+        cloud: "vellum",
+        runtimeUrl: "http://new",
+        onboardedAt: "2026-08-01T00:00:00.000Z",
+      },
+    ]);
+  });
+
+  test("an incoming onboardedAt wins over the stored one", () => {
+    writeOnDisk({
+      activeAssistant: null,
+      assistants: [
+        {
+          assistantId: "asst_p",
+          cloud: "vellum",
+          onboardedAt: "2026-08-01T00:00:00.000Z",
+        },
+      ],
+    });
+
+    replacePlatformAssistants(
+      [lockfilePath],
+      [
+        {
+          assistantId: "asst_p",
+          cloud: "vellum",
+          onboardedAt: "2026-08-31T00:00:00.000Z",
+        },
+      ],
+    );
+
+    expect(
+      (readOnDisk().assistants as Array<Record<string, unknown>>)[0]
+        ?.onboardedAt,
+    ).toBe("2026-08-31T00:00:00.000Z");
+  });
+
+  test("a retired-then-recreated id does not inherit a stale stamp from another entry", () => {
+    writeOnDisk({
+      activeAssistant: null,
+      assistants: [
+        {
+          assistantId: "asst_a",
+          cloud: "vellum",
+          onboardedAt: "2026-08-01T00:00:00.000Z",
+        },
+      ],
+    });
+
+    replacePlatformAssistants(
+      [lockfilePath],
+      [{ assistantId: "asst_b", cloud: "vellum" }],
+    );
+
+    expect(readOnDisk().assistants).toEqual([
+      { assistantId: "asst_b", cloud: "vellum" },
+    ]);
+  });
+
   test("replaces platform assistants while keeping local ones and unknown fields", () => {
     writeOnDisk({
       schemaVersion: 99,