@vellumai/cli 0.8.12-staging.2 → 0.9.0-staging.1

package/src/commands/teleport.ts

@@ -391,9 +391,8 @@ async function exportFromAssistant(
     // daemon, the CLI is updated separately).
     let sourceRuntimeVersion: string;
     try {
-      const identity = await callRuntimeWithAuthRetry(
-        entry,
-        async (token) => localRuntimeIdentity(entry, token),
+      const identity = await callRuntimeWithAuthRetry(entry, async (token) =>
+        localRuntimeIdentity(entry, token),
       );
       sourceRuntimeVersion = identity.version;
     } catch (err) {
@@ -427,16 +426,13 @@ async function exportFromAssistant(
     let jobId: string;
     let accessToken: string;
     try {
-      const result = await callRuntimeWithAuthRetry(
-        entry,
-        async (token) => {
-          const r = await localRuntimeExportToGcs(entry, token, {
-            uploadUrl,
-            description: "teleport export",
-          });
-          return { jobId: r.jobId, token };
-        },
-      );
+      const result = await callRuntimeWithAuthRetry(entry, async (token) => {
+        const r = await localRuntimeExportToGcs(entry, token, {
+          uploadUrl,
+          description: "teleport export",
+        });
+        return { jobId: r.jobId, token };
+      });
       jobId = result.jobId;
       accessToken = result.token;
     } catch (err) {
@@ -734,9 +730,8 @@ async function importToAssistant(
     // target can't actually load) whenever the two drift apart.
     let targetRuntimeVersion: string;
     try {
-      const identity = await callRuntimeWithAuthRetry(
-        entry,
-        (token) => localRuntimeIdentity(entry, token),
+      const identity = await callRuntimeWithAuthRetry(entry, (token) =>
+        localRuntimeIdentity(entry, token),
       );
       targetRuntimeVersion = identity.version;
     } catch (err) {
@@ -779,15 +774,12 @@ async function importToAssistant(
     let jobId: string;
     let accessToken: string;
     try {
-      const result = await callRuntimeWithAuthRetry(
-        entry,
-        async (token) => {
-          const r = await localRuntimeImportFromGcs(entry, token, {
-            bundleUrl,
-          });
-          return { jobId: r.jobId, token };
-        },
-      );
+      const result = await callRuntimeWithAuthRetry(entry, async (token) => {
+        const r = await localRuntimeImportFromGcs(entry, token, {
+          bundleUrl,
+        });
+        return { jobId: r.jobId, token };
+      });
       jobId = result.jobId;
       accessToken = result.token;
     } catch (err) {
@@ -910,17 +902,12 @@ export async function resolveOrHatchTarget(
 
   if (targetEnv === "docker") {
     const beforeIds = new Set(loadAllAssistants().map((e) => e.assistantId));
-    await hatchDocker(
-      "vellum",
-      false,
-      targetName ?? null,
-      false,
-      {},
-      {},
-      {
-        setupProviderCredentials: false,
-      },
-    );
+    await hatchDocker({
+      species: "vellum",
+      detached: false,
+      name: targetName ?? null,
+      setupProviderCredentials: false,
+    });
     const entry = targetName
       ? findAssistantByName(targetName)
       : (loadAllAssistants().find((e) => !beforeIds.has(e.assistantId)) ??

package/src/commands/tunnel.ts

@@ -1,7 +1,12 @@
 import { join } from "path";
 
-import { resolveAssistant } from "../lib/assistant-config";
+import { resolveAssistant, type AssistantEntry } from "../lib/assistant-config";
 import { runCloudflareTunnel } from "../lib/cloudflare-tunnel.js";
+import { GATEWAY_PORT } from "../lib/constants.js";
+import {
+  isAssistantFeatureFlagEnabled,
+  WEB_REMOTE_INGRESS_FLAG,
+} from "../lib/feature-flags.js";
 import { runNgrokTunnel } from "../lib/ngrok";
 
 const VALID_PROVIDERS = ["vellum", "ngrok", "cloudflare", "tailscale"] as const;
@@ -88,6 +93,46 @@ function parseArgs(): TunnelArgs {
   return { assistantName, provider };
 }
 
+function parsePortFromUrl(url: unknown): number | undefined {
+  if (typeof url !== "string" || !url.trim()) return undefined;
+  try {
+    const port = Number(new URL(url).port);
+    return Number.isInteger(port) && port > 0 && port <= 65535
+      ? port
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function resolveEntryGatewayPort(entry: AssistantEntry): number {
+  return (
+    entry.resources?.gatewayPort ??
+    parsePortFromUrl(entry.localUrl) ??
+    parsePortFromUrl(entry.runtimeUrl) ??
+    GATEWAY_PORT
+  );
+}
+
+async function shouldPreferNginxIngress(
+  assistantId: string,
+  gatewayPort: number,
+): Promise<boolean> {
+  try {
+    return await isAssistantFeatureFlagEnabled(
+      assistantId,
+      WEB_REMOTE_INGRESS_FLAG,
+      { runtimeUrl: `http://127.0.0.1:${gatewayPort}` },
+    );
+  } catch (err) {
+    throw new Error(
+      `Could not verify the \`${WEB_REMOTE_INGRESS_FLAG}\` feature flag before starting the tunnel. Is the assistant running? Try \`vellum wake\` and retry. ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+  }
+}
+
 export async function tunnel(): Promise<void> {
   const { assistantName, provider } = parseArgs();
 
@@ -104,21 +149,34 @@ export async function tunnel(): Promise<void> {
     process.exit(1);
   }
 
+  const resources = entry.resources;
+  const gatewayPort = resolveEntryGatewayPort(entry);
+  const baseTunnelOpts = {
+    port: gatewayPort,
+    ...(resources
+      ? { workspaceDir: join(resources.instanceDir, ".vellum", "workspace") }
+      : {}),
+  };
+
   if (provider === "ngrok") {
-    await runNgrokTunnel();
+    await runNgrokTunnel({
+      ...baseTunnelOpts,
+      preferNginxIngress: await shouldPreferNginxIngress(
+        entry.assistantId,
+        gatewayPort,
+      ),
+    });
     return;
   }
 
   if (provider === "cloudflare") {
-    const resources = entry.resources;
-    await runCloudflareTunnel(
-      resources
-        ? {
-            port: resources.gatewayPort,
-            workspaceDir: join(resources.instanceDir, ".vellum", "workspace"),
-          }
-        : {},
-    );
+    await runCloudflareTunnel({
+      ...baseTunnelOpts,
+      preferNginxIngress: await shouldPreferNginxIngress(
+        entry.assistantId,
+        gatewayPort,
+      ),
+    });
     return;
   }
 

package/src/commands/upgrade.ts

@@ -6,7 +6,6 @@ import {
   findAssistantByName,
   getActiveAssistant,
   loadAllAssistants,
-  normalizeVersion,
   resolveCloud,
   saveAssistantEntry,
   type AssistantEntry,
@@ -496,7 +495,6 @@ async function upgradeDocker(
       previousContainerInfo: entry.containerInfo,
       previousDbMigrationVersion: preMigrationState.dbVersion,
       previousWorkspaceMigrationId: preMigrationState.lastWorkspaceMigrationId,
-      version: normalizeVersion(versionTag),
       // Preserve the backup path so `vellum rollback` can restore it later
       preUpgradeBackupPath: backupPath ?? undefined,
     };

package/src/commands/wake.ts

@@ -9,7 +9,6 @@ import {
 import { dockerResourceNames, wakeContainers } from "../lib/docker.js";
 import {
   leaseGuardianToken,
-  loadGuardianToken,
   resetGuardianBootstrap,
   seedGuardianTokenFromSiblingEnv,
 } from "../lib/guardian-token.js";
@@ -43,7 +42,7 @@ export async function wake(): Promise<void> {
       "  --foreground   Run assistant in foreground with logs printed to terminal",
     );
     console.log(
-      "  --repair-guardian  Re-provision the guardian token if missing (resets the\n" +
+      "  --repair-guardian  Force-re-provision the guardian token (resets the\n" +
         "                     gateway bootstrap and re-leases — REVOKES other device-bound\n" +
         "                     tokens, so only use deliberately, never from auto-repair)",
     );
@@ -238,8 +237,11 @@ export async function wake(): Promise<void> {
     console.log("   Seeded guardian token from sibling environment.");
   }
 
-  // Last-resort recovery (explicit `--repair-guardian` only): if no guardian
-  // token exists for this env even after sibling seeding, re-provision one. The
+  // Last-resort recovery (explicit `--repair-guardian` only): force a
+  // re-provision. Token health can't be judged locally — a connect can 401
+  // off a token whose local expiry looks fine (revoked, mis-seeded, wrong
+  // principal) — and the user explicitly confirmed the destructive repair,
+  // so guessing "looks healthy, skip" just recreates the no-op loop. The
   // single-use bootstrap secret may already be spent — a prior connect can
   // lease a token that's then lost, or the gateway marks the secret consumed
   // before the client persists it — which otherwise bricks connect into a
@@ -248,7 +250,7 @@ export async function wake(): Promise<void> {
   // by the lockfile secret — mirrors the macOS client's forceReBootstrap), then
   // re-lease. Gated behind the flag because the re-lease revokes other
   // device-bound tokens; it must never run from the automatic repair path.
-  if (repairGuardian && !loadGuardianToken(entry.assistantId)) {
+  if (repairGuardian) {
     const loopbackUrl = `http://127.0.0.1:${resources.gatewayPort}`;
     const maxAttempts = 3;
     for (let attempt = 1; attempt <= maxAttempts; attempt++) {

package/src/commands/workflows.ts

@@ -0,0 +1,301 @@
+import { extractAssistantFlag, extractValueFlag } from "../lib/arg-utils.js";
+import { AssistantClient } from "../lib/assistant-client.js";
+import {
+  formatAssistantLookupError,
+  lookupAssistantByIdentifier,
+} from "../lib/assistant-config.js";
+
+/**
+ * Client-side mirror of the server's wire-run projection
+ * (`WorkflowRunWire` from `assistant/src/runtime/routes/workflow-routes.ts`).
+ * The CLI is an independent build unit and deliberately does NOT import from
+ * `assistant/` (see `cli/src/shared/provider-env-vars.ts`), so the shape is
+ * mirrored here. Only the fields the CLI renders are declared — the server may
+ * send a superset. Keep in sync with `workflowRunSchema`.
+ */
+type WorkflowRun = {
+  id: string;
+  name: string | null;
+  status: string;
+  agentsSpawned: number;
+  inputTokens: number;
+  outputTokens: number;
+  error: string | null;
+  createdAt: number | null;
+  finishedAt: number | null;
+};
+
+type SavedWorkflow = {
+  name: string;
+  description: string;
+  path: string;
+};
+
+function pad(s: string, w: number): string {
+  return s + " ".repeat(Math.max(0, w - s.length));
+}
+
+function fmtTime(ms: number | null): string {
+  return ms == null ? "-" : new Date(ms).toISOString();
+}
+
+function printRunsTable(runs: WorkflowRun[]): void {
+  const headers = {
+    id: "ID",
+    name: "NAME",
+    status: "STATUS",
+    agents: "AGENTS",
+    created: "CREATED",
+  };
+  const rows = runs.map((r) => ({
+    id: r.id,
+    name: r.name ?? "-",
+    status: r.status,
+    agents: String(r.agentsSpawned),
+    created: fmtTime(r.createdAt),
+  }));
+  const all = [headers, ...rows];
+  const w = {
+    id: Math.max(...all.map((r) => r.id.length)),
+    name: Math.max(...all.map((r) => r.name.length)),
+    status: Math.max(...all.map((r) => r.status.length)),
+    agents: Math.max(...all.map((r) => r.agents.length)),
+    created: Math.max(...all.map((r) => r.created.length)),
+  };
+  const formatRow = (r: typeof headers) =>
+    `${pad(r.id, w.id)}  ${pad(r.name, w.name)}  ${pad(r.status, w.status)}  ${pad(r.agents, w.agents)}  ${r.created}`;
+  console.log(formatRow(headers));
+  console.log(
+    `${"-".repeat(w.id)}  ${"-".repeat(w.name)}  ${"-".repeat(w.status)}  ${"-".repeat(w.agents)}  ${"-".repeat(w.created)}`,
+  );
+  for (const row of rows) console.log(formatRow(row));
+}
+
+function printSavedTable(workflows: SavedWorkflow[]): void {
+  const headers = { name: "NAME", description: "DESCRIPTION" };
+  const rows = workflows.map((w) => ({
+    name: w.name,
+    description: w.description,
+  }));
+  const all = [headers, ...rows];
+  const w = {
+    name: Math.max(...all.map((r) => r.name.length)),
+    description: Math.max(...all.map((r) => r.description.length)),
+  };
+  const formatRow = (r: typeof headers) =>
+    `${pad(r.name, w.name)}  ${r.description}`;
+  console.log(formatRow(headers));
+  console.log(`${"-".repeat(w.name)}  ${"-".repeat(w.description)}`);
+  for (const row of rows) console.log(formatRow(row));
+}
+
+function printHelp(): void {
+  console.log("Usage: vellum workflows <subcommand> [options]");
+  console.log("");
+  console.log("Inspect and control workflow runs on the active assistant.");
+  console.log("");
+  console.log("Subcommands:");
+  console.log("  list              List saved (named) workflows");
+  console.log("  runs              List recent workflow runs");
+  console.log("  show <run-id>     Show details for a single run");
+  console.log("  abort <run-id>    Abort an in-flight run");
+  console.log(
+    "  resume <run-id>   Resume an interrupted run (orphaned by a restart)",
+  );
+  console.log("");
+  console.log("Options:");
+  console.log(
+    "  --assistant <name>  Target a specific assistant (display name or ID)",
+  );
+  console.log("  --limit <n>         (runs) Max runs to list");
+  console.log("  --status <status>   (runs) Filter by run status");
+  console.log("  --help, -h          Show this help");
+}
+
+function createClient(assistantName?: string): AssistantClient {
+  let assistantId: string | undefined;
+  if (assistantName) {
+    const result = lookupAssistantByIdentifier(assistantName);
+    if (result.status !== "found") {
+      throw new Error(formatAssistantLookupError(assistantName, result));
+    }
+    assistantId = result.entry.assistantId;
+  }
+  try {
+    return new AssistantClient(assistantId ? { assistantId } : undefined);
+  } catch {
+    throw new Error(
+      assistantName
+        ? `No assistant found matching '${assistantName}'.`
+        : "No assistant found. Hatch one with 'vellum hatch' first.",
+    );
+  }
+}
+
+function rethrowFetchError(err: unknown): never {
+  if (
+    err instanceof TypeError &&
+    (err.message.includes("fetch") || err.message.includes("connect"))
+  ) {
+    throw new Error(
+      "Could not reach the assistant. Is it running? Try 'vellum wake'.",
+    );
+  }
+  throw err;
+}
+
+async function requestJson<T>(
+  client: AssistantClient,
+  method: "get" | "post",
+  path: string,
+  query?: Record<string, string>,
+): Promise<T> {
+  let res: Response;
+  try {
+    res =
+      method === "get"
+        ? await client.get(path, query ? { query } : undefined)
+        : await client.post(path, undefined);
+  } catch (err) {
+    rethrowFetchError(err);
+  }
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new Error(`Request failed: HTTP ${res.status} ${body}`.trim());
+  }
+  return (await res.json()) as T;
+}
+
+async function listSaved(assistantName?: string): Promise<void> {
+  const client = createClient(assistantName);
+  const data = await requestJson<{ workflows: SavedWorkflow[] }>(
+    client,
+    "get",
+    "/workflows",
+  );
+  if (data.workflows.length === 0) {
+    console.log("No saved workflows found.");
+    return;
+  }
+  printSavedTable(data.workflows);
+}
+
+async function listRuns(
+  opts: { limit?: string; status?: string },
+  assistantName?: string,
+): Promise<void> {
+  const client = createClient(assistantName);
+  const query: Record<string, string> = {};
+  if (opts.limit) query.limit = opts.limit;
+  if (opts.status) query.status = opts.status;
+  const data = await requestJson<{ runs: WorkflowRun[] }>(
+    client,
+    "get",
+    "/workflows/runs",
+    Object.keys(query).length ? query : undefined,
+  );
+  if (data.runs.length === 0) {
+    console.log("No workflow runs found.");
+    return;
+  }
+  printRunsTable(data.runs);
+}
+
+async function showRun(runId: string, assistantName?: string): Promise<void> {
+  const client = createClient(assistantName);
+  const run = await requestJson<WorkflowRun>(
+    client,
+    "get",
+    `/workflows/runs/${runId}`,
+  );
+  console.log(`ID:             ${run.id}`);
+  console.log(`Name:           ${run.name ?? "(unnamed)"}`);
+  console.log(`Status:         ${run.status}`);
+  console.log(`Agents spawned: ${run.agentsSpawned}`);
+  console.log(
+    `Tokens:         ${run.inputTokens} in / ${run.outputTokens} out`,
+  );
+  console.log(`Created:        ${fmtTime(run.createdAt)}`);
+  console.log(`Finished:       ${fmtTime(run.finishedAt)}`);
+  if (run.error) console.log(`Error:          ${run.error}`);
+}
+
+async function abortRun(runId: string, assistantName?: string): Promise<void> {
+  const client = createClient(assistantName);
+  await requestJson<{ ok: boolean; runId: string }>(
+    client,
+    "post",
+    `/workflows/runs/${runId}/abort`,
+  );
+  console.log(`Abort signalled for workflow run ${runId}.`);
+}
+
+async function resumeRun(runId: string, assistantName?: string): Promise<void> {
+  const client = createClient(assistantName);
+  await requestJson<{ ok: boolean; runId: string }>(
+    client,
+    "post",
+    `/workflows/runs/${runId}/resume`,
+  );
+  console.log(
+    `Resumed workflow run ${runId}. It replays its completed steps and continues from where it was interrupted.`,
+  );
+}
+
+export async function workflows(): Promise<void> {
+  const args = process.argv.slice(3);
+
+  if (args.includes("--help") || args.includes("-h")) {
+    printHelp();
+    return;
+  }
+
+  const assistantName = extractAssistantFlag(args);
+  const limit = extractValueFlag(args, "limit");
+  const status = extractValueFlag(args, "status");
+  const subcommand = args[0];
+
+  if (!subcommand || subcommand === "list") {
+    await listSaved(assistantName);
+    return;
+  }
+
+  if (subcommand === "runs") {
+    await listRuns({ limit, status }, assistantName);
+    return;
+  }
+
+  if (subcommand === "show") {
+    const runId = args[1];
+    if (!runId) {
+      console.error("Usage: vellum workflows show <run-id>");
+      process.exit(1);
+    }
+    await showRun(runId, assistantName);
+    return;
+  }
+
+  if (subcommand === "abort") {
+    const runId = args[1];
+    if (!runId) {
+      console.error("Usage: vellum workflows abort <run-id>");
+      process.exit(1);
+    }
+    await abortRun(runId, assistantName);
+    return;
+  }
+
+  if (subcommand === "resume") {
+    const runId = args[1];
+    if (!runId) {
+      console.error("Usage: vellum workflows resume <run-id>");
+      process.exit(1);
+    }
+    await resumeRun(runId, assistantName);
+    return;
+  }
+
+  console.error(`Unknown subcommand: ${subcommand}`);
+  printHelp();
+  process.exit(1);
+}

package/src/index.ts

@@ -16,6 +16,7 @@ import { hatch } from "./commands/hatch";
 import { login, logout, whoami } from "./commands/login";
 import { logs } from "./commands/logs";
 import { message } from "./commands/message";
+import { nginxIngress } from "./commands/nginx-ingress";
 import { pair } from "./commands/pair";
 import { ps } from "./commands/ps";
 import { recover } from "./commands/recover";
@@ -33,6 +34,7 @@ import { unpair } from "./commands/unpair";
 import { upgrade } from "./commands/upgrade";
 import { use } from "./commands/use";
 import { wake } from "./commands/wake";
+import { workflows } from "./commands/workflows";
 import { resolveAssistant, setActiveAssistant } from "./lib/assistant-config";
 import { loadGuardianToken } from "./lib/guardian-token";
 import { checkHealth } from "./lib/health-check";
@@ -54,6 +56,7 @@ const commands = {
   logout,
   logs,
   message,
+  "nginx-ingress": nginxIngress,
   pair,
   ps,
   recover,
@@ -72,6 +75,7 @@ const commands = {
   use,
   wake,
   whoami,
+  workflows,
 } as const;
 
 type CommandName = keyof typeof commands;
@@ -96,6 +100,9 @@ function printHelp(): void {
   console.log("  flags    Show and toggle feature flags");
   console.log("  gateway  Gateway management commands");
   console.log("  hatch    Create a new assistant instance");
+  console.log(
+    "  nginx-ingress  Manage the nginx proxy fronting the gateway for web access [beta]",
+  );
   console.log("  logs     View logs from an assistant instance");
   console.log("  login    Log in to the Vellum platform");
   console.log("  logout   Log out of the Vellum platform");
@@ -126,6 +133,7 @@ function printHelp(): void {
   console.log("  use      Set the active assistant for commands");
   console.log("  wake     Start the assistant and gateway");
   console.log("  whoami   Show current logged-in user");
+  console.log("  workflows Inspect and control workflow runs");
   console.log("");
   console.log("Options:");
   console.log(

package/src/lib/arg-utils.ts

@@ -11,3 +11,51 @@ export function extractFlag(
   const remaining = [...args.slice(0, idx), ...args.slice(idx + 2)];
   return [value, remaining];
 }
+
+/**
+ * Strip `--<name> <value>` from argv and return the captured value.
+ *
+ * Mutates the input array so positional parsing downstream sees a clean shape.
+ * Returns `undefined` if the flag is absent. Error-reports a missing value (and
+ * exits) so the user gets a clear message rather than the flag being silently
+ * swallowed as a positional.
+ */
+export function extractValueFlag(
+  args: string[],
+  name: string,
+): string | undefined {
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] !== `--${name}`) continue;
+    const value = args[i + 1];
+    if (!value || value.startsWith("-")) {
+      console.error(`Missing value for --${name} <value>`);
+      process.exit(1);
+    }
+    args.splice(i, 2);
+    return value;
+  }
+  return undefined;
+}
+
+/**
+ * Strip `--assistant <name>` from argv and return the captured value.
+ *
+ * Mutates the input array so positional parsing downstream sees a clean shape
+ * (subcommand + key + value). Returns `undefined` if the flag is absent.
+ * Error-reports a missing value so the user gets a clear message rather than
+ * the flag being silently swallowed as a positional. (Kept distinct from
+ * {@link extractValueFlag} only for its `<name>` wording in the error string.)
+ */
+export function extractAssistantFlag(args: string[]): string | undefined {
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] !== "--assistant") continue;
+    const value = args[i + 1];
+    if (!value || value.startsWith("-")) {
+      console.error("Missing value for --assistant <name>");
+      process.exit(1);
+    }
+    args.splice(i, 2);
+    return value;
+  }
+  return undefined;
+}

package/src/lib/assistant-client.ts

@@ -26,6 +26,7 @@ const FALLBACK_RUNTIME_URL = `http://127.0.0.1:${GATEWAY_PORT}`;
 
 export interface AssistantClientOpts {
   assistantId?: string;
+  runtimeUrl?: string;
   /**
    * When provided alongside `orgId`, the client authenticates with a
    * session token instead of a guardian token.  The session token is
@@ -73,6 +74,7 @@ export class AssistantClient {
     }
 
     this.runtimeUrl = (
+      opts?.runtimeUrl ||
       entry.localUrl ||
       entry.runtimeUrl ||
       FALLBACK_RUNTIME_URL

package/src/lib/assistant-config.ts

@@ -97,8 +97,6 @@ export interface AssistantEntry {
   sshUser?: string;
   zone?: string;
   hatchedAt?: string;
-  /** Installed service-group release version (no `v` prefix), written at hatch/upgrade/rollback. */
-  version?: string;
   /** Per-instance resource config. Present for local entries in multi-instance setups. */
   resources?: LocalInstanceResources;
   /** PID of the file watcher process for docker instances hatched with --watch. */
@@ -586,11 +584,6 @@ export function extractHostFromUrl(url: string): string {
   }
 }
 
-/** Strip a leading `v` so stored versions match the healthz `version` format. */
-export function normalizeVersion(version: string): string {
-  return version.replace(/^v/, "");
-}
-
 export function saveAssistantEntry(entry: AssistantEntry): void {
   const entries = readAssistants().filter(
     (e) => e.assistantId !== entry.assistantId,