@vellumai/assistant 0.8.0 → 0.8.2

package/src/cli/lib/list-installed-plugins.ts

@@ -0,0 +1,137 @@
+/**
+ * Enumerate plugins materialized under `<workspaceDir>/plugins/`.
+ *
+ * The CLI command `assistant plugins list` is a thin wrapper. Downstream
+ * callers (the daemon's diagnostics surface, a future TUI, scripted
+ * audits) can call {@link listInstalledPlugins} directly without going
+ * through commander.
+ *
+ * Designed to be lenient: a malformed `package.json` is reported as an
+ * error on that one entry rather than failing the whole listing. The
+ * daemon makes the same call on boot via `external-plugin-loader.ts`
+ * and we want both surfaces to agree on what's present.
+ */
+
+import {
+  existsSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+} from "node:fs";
+import { join } from "node:path";
+
+import { getWorkspacePluginsDir } from "../../util/platform.js";
+
+/** Minimal manifest fields surfaced to the CLI. */
+export interface PluginPackageMetadata {
+  readonly name?: string;
+  readonly version?: string;
+  readonly description?: string;
+  readonly peerDependencies?: Record<string, string>;
+}
+
+/** One installed plugin entry. */
+export interface InstalledPluginInfo {
+  /** Directory name under `<workspaceDir>/plugins/`. */
+  readonly name: string;
+  /** Absolute path to the plugin directory. */
+  readonly target: string;
+  /** Parsed `package.json` content, when present and parseable. */
+  readonly packageJson: PluginPackageMetadata | null;
+  /**
+   * Non-fatal issues with this entry (missing `package.json`, malformed
+   * JSON, unexpected type, etc.). Empty when the entry parses cleanly.
+   */
+  readonly issues: readonly string[];
+}
+
+/** Options accepted by {@link listInstalledPlugins}. */
+export interface ListInstalledPluginsOptions {
+  /** Override the workspace plugins directory. Falls back to {@link getWorkspacePluginsDir}. */
+  readonly workspacePluginsDir?: string;
+}
+
+/**
+ * Return one entry per directory under the workspace plugins directory,
+ * sorted alphabetically by name. Hidden entries (`.`-prefixed) and
+ * non-directory entries are skipped silently — the daemon's loader does
+ * the same. Returns `[]` if the plugins directory does not exist.
+ */
+export function listInstalledPlugins(
+  opts: ListInstalledPluginsOptions = {},
+): InstalledPluginInfo[] {
+  const pluginsDir = opts.workspacePluginsDir ?? getWorkspacePluginsDir();
+  if (!existsSync(pluginsDir)) return [];
+
+  const entries = readdirSync(pluginsDir, { withFileTypes: true })
+    .filter((e) => !e.name.startsWith("."))
+    .filter((e) => {
+      if (e.isDirectory()) return true;
+      if (!e.isSymbolicLink()) return false;
+      // Resolve the symlink and only keep it if it points to a directory.
+      try {
+        return statSync(join(pluginsDir, e.name)).isDirectory();
+      } catch {
+        return false;
+      }
+    })
+    .map((e) => e.name)
+    .sort();
+
+  return entries.map((name) => readPluginEntry(pluginsDir, name));
+}
+
+function readPluginEntry(
+  pluginsDir: string,
+  name: string,
+): InstalledPluginInfo {
+  const target = join(pluginsDir, name);
+  const pkgJsonPath = join(target, "package.json");
+  const issues: string[] = [];
+
+  if (!existsSync(pkgJsonPath)) {
+    issues.push("missing package.json");
+    return { name, target, packageJson: null, issues };
+  }
+
+  let raw: string;
+  try {
+    raw = readFileSync(pkgJsonPath, "utf8");
+  } catch (err) {
+    issues.push(
+      `package.json unreadable: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return { name, target, packageJson: null, issues };
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    issues.push(
+      `package.json invalid JSON: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return { name, target, packageJson: null, issues };
+  }
+
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    issues.push("package.json is not an object");
+    return { name, target, packageJson: null, issues };
+  }
+
+  const meta = parsed as Record<string, unknown>;
+  const packageJson: PluginPackageMetadata = {
+    name: typeof meta.name === "string" ? meta.name : undefined,
+    version: typeof meta.version === "string" ? meta.version : undefined,
+    description:
+      typeof meta.description === "string" ? meta.description : undefined,
+    peerDependencies:
+      typeof meta.peerDependencies === "object" &&
+      meta.peerDependencies !== null &&
+      !Array.isArray(meta.peerDependencies)
+        ? (meta.peerDependencies as Record<string, string>)
+        : undefined,
+  };
+
+  return { name, target, packageJson, issues };
+}

package/src/cli/lib/nested-value.ts

@@ -0,0 +1,44 @@
+/**
+ * Dotted-path get/set helpers for the CLI.
+ *
+ * These two functions are byte-for-byte equivalent to the implementations in
+ * `config/loader.ts` (see `getNestedValue` / `setNestedValue` there). They
+ * are inlined here so the IPC-tagged `config` command can walk dotted paths
+ * without importing `config/loader.js`, which has module-level side effects
+ * (config cache, file watcher, etc.) inappropriate for the CLI process.
+ *
+ * Loader and CLI both call `setNestedValue("a.b.c", v)`-style helpers - if
+ * the behavior needs to change in one place, change it in both.
+ */
+
+export function getNestedValue(
+  obj: Record<string, unknown>,
+  path: string,
+): unknown {
+  const keys = path.split(".");
+  let current: unknown = obj;
+  for (const key of keys) {
+    if (current == null || typeof current !== "object") {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[key];
+  }
+  return current;
+}
+
+export function setNestedValue(
+  obj: Record<string, unknown>,
+  path: string,
+  value: unknown,
+): void {
+  const keys = path.split(".");
+  let current = obj;
+  for (let i = 0; i < keys.length - 1; i++) {
+    const key = keys[i]!;
+    if (current[key] == null || typeof current[key] !== "object") {
+      current[key] = {};
+    }
+    current = current[key] as Record<string, unknown>;
+  }
+  current[keys[keys.length - 1]!] = value;
+}

package/src/cli/lib/open-browser.ts

@@ -0,0 +1,36 @@
+/**
+ * CLI-side helper that opens a URL on the user's host machine.
+ *
+ * Writes an `open_url` event to the `signals/emit-event` file so that the
+ * daemon's ConfigWatcher picks it up and publishes it to connected clients
+ * (e.g. the Swift macOS app) via the assistant event hub.
+ *
+ * Uses only `node:` imports so it's safe for `ipc`-tagged CLI commands.
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+function getWorkspaceDir(): string {
+  return (
+    process.env.VELLUM_WORKSPACE_DIR ??
+    join(
+      process.env.HOME ?? process.env.USERPROFILE ?? "/tmp",
+      ".vellum",
+      "workspace",
+    )
+  );
+}
+
+export function openInHostBrowser(url: string): void {
+  try {
+    const signalsDir = join(getWorkspaceDir(), "signals");
+    mkdirSync(signalsDir, { recursive: true });
+    writeFileSync(
+      join(signalsDir, "emit-event"),
+      JSON.stringify({ type: "open_url", url }),
+    );
+  } catch {
+    // Best-effort — caller will display the URL as a fallback
+  }
+}

package/src/cli/lib/register-command.ts

@@ -0,0 +1,19 @@
+import type { Command } from "commander";
+
+export type CommandTransport = "ipc" | "local" | "bootstrap";
+
+interface RegisterCommandOpts {
+  name: string;
+  transport: CommandTransport;
+  description: string;
+  build: (cmd: Command) => void;
+}
+
+export function registerCommand(
+  parent: Command,
+  opts: RegisterCommandOpts,
+): Command {
+  const cmd = parent.command(opts.name).description(opts.description);
+  opts.build(cmd);
+  return cmd;
+}

package/src/cli/lib/time-ago.ts

@@ -0,0 +1,34 @@
+/**
+ * Relative-time formatter for CLI output.
+ *
+ * Pure function with no daemon-internal imports — safe for IPC-tagged commands.
+ */
+export function timeAgo(timestamp: number): string {
+  const seconds = Math.floor((Date.now() - timestamp) / 1000);
+  if (seconds < 60) return "just now";
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  if (days === 1) return "yesterday";
+  if (days < 14) return `${days}d ago`;
+  const weeks = Math.floor(days / 7);
+  if (weeks < 8) return `${weeks}w ago`;
+  const date = new Date(timestamp);
+  const months = [
+    "Jan",
+    "Feb",
+    "Mar",
+    "Apr",
+    "May",
+    "Jun",
+    "Jul",
+    "Aug",
+    "Sep",
+    "Oct",
+    "Nov",
+    "Dec",
+  ];
+  return `${months[date.getMonth()]} ${date.getDate()}`;
+}

package/src/cli/lib/uninstall-plugin.ts

@@ -0,0 +1,82 @@
+/**
+ * Remove a plugin previously materialized under `<workspaceDir>/plugins/`.
+ *
+ * Symmetric to {@link ./install-from-github.installPlugin}. The CLI
+ * command `assistant plugins uninstall <name>` is a thin wrapper that
+ * supplies the live workspace directory and formats the result.
+ *
+ * The operation is destructive — a successful return means the plugin
+ * directory and everything beneath it have been removed from disk.
+ * Callers needing a confirmation prompt should run it before invoking
+ * this function (the CLI command does this via `--force`).
+ */
+
+import { existsSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+import { getWorkspacePluginsDir } from "../../util/platform.js";
+import {
+  InvalidPluginNameError,
+  sanitizePluginName,
+} from "./install-from-github.js";
+
+/** Plugin is not present in the workspace plugins directory. */
+export class PluginNotInstalledError extends Error {
+  constructor(
+    readonly pluginName: string,
+    readonly target: string,
+  ) {
+    super(`Plugin "${pluginName}" is not installed at ${target}.`);
+    this.name = "PluginNotInstalledError";
+  }
+}
+
+/** Options accepted by {@link uninstallPlugin}. */
+export interface UninstallPluginOptions {
+  readonly name: string;
+  /** Override the workspace plugins directory. Falls back to {@link getWorkspacePluginsDir}. */
+  readonly workspacePluginsDir?: string;
+}
+
+/** Result of a successful uninstall. */
+export interface UninstallPluginResult {
+  readonly name: string;
+  /** Absolute path that was removed. */
+  readonly target: string;
+}
+
+/**
+ * Validate the name, confirm the plugin exists, then recursively remove
+ * the install target. Throws {@link InvalidPluginNameError} if the name
+ * fails sanitization or {@link PluginNotInstalledError} if no directory
+ * (or symlink to a directory) is present at the resolved target.
+ *
+ * The name check is performed up front so an attacker-supplied
+ * `../../etc/passwd` style argument never reaches `rmSync` — even
+ * though commander typically prevents it at the argv level, defense in
+ * depth.
+ */
+export function uninstallPlugin(
+  opts: UninstallPluginOptions,
+): UninstallPluginResult {
+  const name = sanitizePluginName(opts.name);
+  const pluginsDir = opts.workspacePluginsDir ?? getWorkspacePluginsDir();
+  const target = join(pluginsDir, name);
+
+  if (!existsSync(target)) {
+    throw new PluginNotInstalledError(name, target);
+  }
+
+  // `existsSync` follows symlinks; guard against a stray file with the
+  // plugin's name (which would be surprising rather than dangerous —
+  // we'd refuse to delete it).
+  const stats = statSync(target);
+  if (!stats.isDirectory()) {
+    throw new PluginNotInstalledError(name, target);
+  }
+
+  rmSync(target, { recursive: true, force: true });
+  return { name, target };
+}
+
+export { InvalidPluginNameError };

package/src/cli/lib/unknown-command.ts

@@ -0,0 +1,111 @@
+import type { Command } from "commander";
+
+/**
+ * Result of detecting an unknown top-level subcommand. `suggestion` is set
+ * when a near-match is found (Levenshtein distance ≤ 40% of the longer name).
+ */
+export interface UnknownCommandHit {
+  readonly token: string;
+  readonly suggestion?: string;
+}
+
+/**
+ * Collect every top-level subcommand name and alias registered on `program`.
+ */
+export function knownCommandNames(program: Command): Set<string> {
+  const names = new Set<string>();
+  for (const cmd of program.commands) {
+    names.add(cmd.name());
+    for (const alias of cmd.aliases()) {
+      names.add(alias);
+    }
+  }
+  return names;
+}
+
+/**
+ * Pre-parse scan: returns the first positional argv token that doesn't match
+ * any known subcommand/alias, or null when the args look valid.
+ *
+ * Commander processes `--help` / `--version` before any action or hook runs,
+ * so `assistant invalid --help` would otherwise dump the root help instead of
+ * surfacing the unknown command. Callers should run this before `parse()` so
+ * the error wins over the help short-circuit.
+ *
+ * The first non-flag token is treated as the subcommand candidate. Flags are
+ * skipped wholesale; the root program has no value-taking options today.
+ */
+export function detectUnknownCommand(
+  program: Command,
+  argv: readonly string[],
+): UnknownCommandHit | null {
+  const firstPositional = argv.find((token) => !token.startsWith("-"));
+  if (!firstPositional) return null;
+
+  const known = knownCommandNames(program);
+  if (known.has(firstPositional)) return null;
+
+  const suggestion = findClosestCommand(firstPositional, [...known]);
+  return suggestion ? { token: firstPositional, suggestion } : { token: firstPositional };
+}
+
+/**
+ * Format the unknown-command error as a multi-line message. Kept as a pure
+ * function so it can be reused by `default-action`'s in-parse path (when the
+ * user runs `assistant invalid` with no `--help`) and by the pre-parse path.
+ */
+export function formatUnknownCommandMessage(hit: UnknownCommandHit): string {
+  const lines = [`unknown command '${hit.token}'`];
+  if (hit.suggestion) {
+    lines.push(`(Did you mean '${hit.suggestion}'?)`);
+  }
+  lines.push(`Run 'assistant --help' to see a list of available commands.`);
+  return lines.join("\n");
+}
+
+/**
+ * Find the closest matching command name using Levenshtein distance.
+ * Returns the best match if the distance is ≤ 40% of the longer string's
+ * length, otherwise returns undefined.
+ */
+export function findClosestCommand(
+  input: string,
+  candidates: readonly string[],
+): string | undefined {
+  let best: string | undefined;
+  let bestDist = Infinity;
+  const lowered = input.toLowerCase();
+
+  for (const name of candidates) {
+    const dist = levenshtein(lowered, name.toLowerCase());
+    if (dist < bestDist) {
+      bestDist = dist;
+      best = name;
+    }
+  }
+
+  const maxLen = Math.max(input.length, best?.length ?? 0);
+  if (best && bestDist <= Math.ceil(maxLen * 0.4)) {
+    return best;
+  }
+  return undefined;
+}
+
+function levenshtein(a: string, b: string): number {
+  const m = a.length;
+  const n = b.length;
+  const dp: number[][] = Array.from({ length: m + 1 }, () =>
+    Array(n + 1).fill(0),
+  );
+  for (let i = 0; i <= m; i++) dp[i][0] = i;
+  for (let j = 0; j <= n; j++) dp[0][j] = j;
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      dp[i][j] =
+        a[i - 1] === b[j - 1]
+          ? dp[i - 1][j - 1]
+          : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+    }
+  }
+  return dp[m][n];
+}

package/src/cli/program.ts

@@ -5,17 +5,18 @@ import { Command } from "commander";
 import { initFeatureFlagOverrides } from "../config/assistant-feature-flags.js";
 import { getConfigReadOnly } from "../config/loader.js";
 import { isEmailEnabled } from "../email/feature-gate.js";
+import { isExternalPluginsEnabled } from "../plugins/feature-gate.js";
 import { getWorkspaceDir } from "../util/platform.js";
 import { APP_VERSION } from "../version.js";
 import { registerAttachmentCommand } from "./commands/attachment.js";
 import { registerAuditCommand } from "./commands/audit.js";
 import { registerAuthCommand } from "./commands/auth.js";
-import { registerAutonomyCommand } from "./commands/autonomy.js";
 import { registerAvatarCommand } from "./commands/avatar.js";
 import { registerBackupCommand } from "./commands/backup.js";
 import { registerBashCommand } from "./commands/bash.js";
 import { registerBrowserCommand } from "./commands/browser.js";
 import { registerCacheCommand } from "./commands/cache.js";
+import { registerChangelogCommand } from "./commands/changelog.js";
 import { registerChannelVerificationSessionsCommand } from "./commands/channel-verification-sessions.js";
 import { registerClientsCommand } from "./commands/clients.js";
 import { registerCompletionsCommand } from "./commands/completions.js";
@@ -32,24 +33,27 @@ import { registerImageGenerationCommand } from "./commands/image-generation.js";
 import { registerInferenceCommand } from "./commands/inference.js";
 import { registerKeysCommand } from "./commands/keys.js";
 import { registerMcpCommand } from "./commands/mcp.js";
-import { registerMemoryCommand } from "./commands/memory.js";
 import { registerMemoryV2Command } from "./commands/memory-v2.js";
 import { registerNotificationsCommand } from "./commands/notifications.js";
 import { registerOAuthCommand } from "./commands/oauth/index.js";
 import { registerPendingCommand } from "./commands/pending.js";
 import { registerPlatformCommand } from "./commands/platform/index.js";
+import { registerPluginsCommand } from "./commands/plugins.js";
 import { registerRoutesCommand } from "./commands/routes.js";
+import { registerSchedulesCommand } from "./commands/schedules.js";
 import { registerSequenceCommand } from "./commands/sequence.js";
 import { registerSkillsCommand } from "./commands/skills.js";
 import { registerStatusCommand } from "./commands/status.js";
 import { registerSttCommand } from "./commands/stt.js";
 import { registerTaskCommand } from "./commands/task.js";
+import { registerTelemetryCommand } from "./commands/telemetry.js";
 import { registerTrustCommand } from "./commands/trust.js";
 import { registerTtsCommand } from "./commands/tts.js";
 import { registerUiCommand } from "./commands/ui.js";
 import { registerUsageCommand } from "./commands/usage.js";
 import { registerWatchersCommand } from "./commands/watchers.js";
 import { registerWebhooksCommand } from "./commands/webhooks.js";
+import { red } from "./lib/cli-colors.js";
 import { log } from "./logger.js";
 
 /**
@@ -66,6 +70,13 @@ export async function buildCliProgram(): Promise<Command> {
     .version(APP_VERSION)
     .allowExcessArguments(true);
 
+  // Color Commander-emitted error output red (unknown options, missing args,
+  // cmd.error() calls). Plain success output and --help text are untouched.
+  // The `red` helper is a no-op when stderr isn't a TTY or NO_COLOR is set.
+  program.configureOutput({
+    outputError: (str, write) => write(red(str)),
+  });
+
   program.addHelpText(
     "after",
     `
@@ -80,12 +91,12 @@ Examples:
   registerAttachmentCommand(program);
   registerAuditCommand(program);
   registerAuthCommand(program);
-  registerAutonomyCommand(program);
   registerAvatarCommand(program);
   registerBackupCommand(program);
   registerBashCommand(program);
   registerBrowserCommand(program);
   registerCacheCommand(program);
+  registerChangelogCommand(program);
   registerChannelVerificationSessionsCommand(program);
   registerClientsCommand(program);
   registerCompletionsCommand(program);
@@ -103,18 +114,22 @@ Examples:
   registerInferenceCommand(program);
   registerKeysCommand(program);
   registerMcpCommand(program);
-  registerMemoryCommand(program);
   registerMemoryV2Command(program);
   registerNotificationsCommand(program);
   registerOAuthCommand(program);
   registerPendingCommand(program);
   registerPlatformCommand(program);
+  if (isExternalPluginsEnabled(getConfigReadOnly())) {
+    registerPluginsCommand(program);
+  }
   registerRoutesCommand(program);
+  registerSchedulesCommand(program);
   registerSequenceCommand(program);
   registerStatusCommand(program);
   registerSkillsCommand(program);
   registerSttCommand(program);
   registerTaskCommand(program);
+  registerTelemetryCommand(program);
   registerTrustCommand(program);
   registerTtsCommand(program);
   registerUiCommand(program);
@@ -128,9 +143,28 @@ Examples:
   // remain available even without a workspace.
   // Workspace-independent commands are exempt:
   //   completions — pure shell-script generation, no workspace files needed
-  const workspaceExemptCommands = new Set(["completions", "status"]);
+  //   status     — diagnostic; should run even when the workspace is broken
+  //   changelog  — pure read-only network surface backed by GitHub Releases;
+  //                its on-disk cache is best-effort and tolerates a missing
+  //                workspace dir (see changelog.ts:writeCache)
+  const workspaceExemptCommands = new Set([
+    "completions",
+    "status",
+    "changelog",
+  ]);
+  // An action command's `.name()` returns the leaf (e.g. "show" for
+  // `changelog show <ver>`), so we walk up the parent chain to see whether
+  // any ancestor — typically the top-level subcommand — is exempt.
+  const isExemptFromWorkspaceCheck = (command: Command): boolean => {
+    let current: Command | null | undefined = command;
+    while (current && current !== program) {
+      if (workspaceExemptCommands.has(current.name())) return true;
+      current = current.parent;
+    }
+    return false;
+  };
   program.hook("preAction", (_thisCommand, actionCommand) => {
-    if (workspaceExemptCommands.has(actionCommand.name())) {
+    if (isExemptFromWorkspaceCheck(actionCommand)) {
       return;
     }
     const workspaceDir = getWorkspaceDir();

package/src/cli/utils/__tests__/conversation-id.test.ts

@@ -0,0 +1,66 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import { resolveConversationId } from "../conversation-id.js";
+
+const FAILURE_HELP = "No conversation ID. Provide one explicitly.";
+
+let savedConvId: string | undefined;
+let savedSkillCtx: string | undefined;
+
+beforeEach(() => {
+  savedConvId = process.env.__CONVERSATION_ID;
+  savedSkillCtx = process.env.__SKILL_CONTEXT_JSON;
+  delete process.env.__CONVERSATION_ID;
+  delete process.env.__SKILL_CONTEXT_JSON;
+});
+
+afterEach(() => {
+  if (savedConvId !== undefined) {
+    process.env.__CONVERSATION_ID = savedConvId;
+  } else {
+    delete process.env.__CONVERSATION_ID;
+  }
+  if (savedSkillCtx !== undefined) {
+    process.env.__SKILL_CONTEXT_JSON = savedSkillCtx;
+  } else {
+    delete process.env.__SKILL_CONTEXT_JSON;
+  }
+});
+
+describe("resolveConversationId", () => {
+  test("explicit provided → returns it", () => {
+    const result = resolveConversationId({
+      explicit: "conv-explicit-123",
+      failureHelp: FAILURE_HELP,
+    });
+    expect(result).toBe("conv-explicit-123");
+  });
+
+  test("explicit absent, __SKILL_CONTEXT_JSON has conversationId → returns it", () => {
+    process.env.__SKILL_CONTEXT_JSON = JSON.stringify({
+      conversationId: "conv-from-skill-ctx",
+    });
+    const result = resolveConversationId({ failureHelp: FAILURE_HELP });
+    expect(result).toBe("conv-from-skill-ctx");
+  });
+
+  test("both envs absent → throws with provided failureHelp", () => {
+    expect(() =>
+      resolveConversationId({ failureHelp: FAILURE_HELP }),
+    ).toThrow(FAILURE_HELP);
+  });
+
+  test("malformed __SKILL_CONTEXT_JSON → falls through to __CONVERSATION_ID", () => {
+    process.env.__SKILL_CONTEXT_JSON = "not-valid-json{{{";
+    process.env.__CONVERSATION_ID = "conv-from-env";
+    const result = resolveConversationId({ failureHelp: FAILURE_HELP });
+    expect(result).toBe("conv-from-env");
+  });
+
+  test("__SKILL_CONTEXT_JSON without conversationId field → falls through to __CONVERSATION_ID", () => {
+    process.env.__SKILL_CONTEXT_JSON = JSON.stringify({ other: "value" });
+    process.env.__CONVERSATION_ID = "conv-from-env-fallback";
+    const result = resolveConversationId({ failureHelp: FAILURE_HELP });
+    expect(result).toBe("conv-from-env-fallback");
+  });
+});