@vellumai/assistant 0.12.1 → 0.12.2-staging.1

package/src/calls/voice-triage-escalate.ts

@@ -27,7 +27,10 @@
  */
 
 import { NON_LATIN_SENTENCE_ENDING_PUNCTUATION } from "../tts/speakable-segments.js";
-import { localizedOrDefault } from "../util/language-subtag.js";
+import {
+  fixedPhraseLanguage,
+  localizedOrDefault,
+} from "../util/language-subtag.js";
 import {
   ESCALATE_VERDICT_TOKEN,
   HOLD_VERDICT_TOKEN,
@@ -103,6 +106,36 @@ export function fallbackEscalationBridgeFor(language?: string): string {
  */
 export const MIN_SPOKEN_BRIDGE_CHARS = 3;
 
+/**
+ * The phrase spoken across an escalation hand-off, for both voice drivers:
+ * the front-door leg's own capped bridge when it is a real bridge, else the
+ * canned fallback in the caller's language. `usesFallback` marks the canned
+ * phrase as audio-only: the model never produced it, so no transcript row
+ * carries it (the bridge's hygiene pass deletes the leg's row), and the
+ * driver keeps it out of the turn's recorded text. `language` is the TTS
+ * hint the phrase must carry: "en" when the canned table has no entry for
+ * the caller's language (the phrase is English text then), undefined when
+ * the phrase rides the turn's own language.
+ */
+export function resolveSpokenEscalationBridge(
+  cappedBridge: string,
+  language?: string,
+): { spokenBridge: string; usesFallback: boolean; language?: string } {
+  const usesFallback = cappedBridge.length < MIN_SPOKEN_BRIDGE_CHARS;
+  if (!usesFallback) {
+    return { spokenBridge: cappedBridge, usesFallback };
+  }
+  const fixedLanguage = fixedPhraseLanguage(
+    FALLBACK_ESCALATION_BRIDGE_BY_LANGUAGE,
+    language,
+  );
+  return {
+    spokenBridge: fallbackEscalationBridgeFor(language),
+    usesFallback,
+    ...(fixedLanguage !== undefined ? { language: fixedLanguage } : {}),
+  };
+}
+
 /**
  * Hard cap on the spoken escalation bridge. The bridge is supposed to be a
  * single short sentence; the cap bounds the hand-off delay (and the audio)
@@ -159,14 +192,20 @@ export function isEscalationBridgeComplete(rawBridge: string): boolean {
  * output leads with {@link ESCALATE_VERDICT_TOKEN} (a stray token later in
  * an answer is not an escalation under the verdict-first protocol), else
  * the capped bridge that followed the token. Used by transcript hygiene to
- * reconstruct what the caller heard from a persisted row.
+ * reconstruct what the caller heard from a persisted row, by running the
+ * same verdict machine the live stream ran through.
  */
 export function spokenBridgeText(frontDoorText: string): string {
-  const leading = frontDoorText.trimStart();
-  if (!leading.startsWith(ESCALATE_VERDICT_TOKEN)) {
+  const machine = createFrontDoorVerdictMachine(false);
+  const step = machine.push(frontDoorText);
+  if (step.kind !== "escalate") {
     return "";
   }
-  return capEscalationBridge(leading.slice(ESCALATE_VERDICT_TOKEN.length));
+  if (step.bridge !== null) {
+    return step.bridge;
+  }
+  const finished = machine.finish();
+  return finished.kind === "bridge" ? finished.bridge : "";
 }
 
 /**
@@ -224,107 +263,187 @@ export function classifyFrontDoorLeading(
 }
 
 /**
- * Verdict-first gate over a front-door leg's delta stream: given the leg's
- * raw deltas in order, it releases only the text the caller actually hears.
- * A front-door leg's raw stream is a control plane, not assistant speech,
- * until its leading tokens classify, so anything downstream of the model
- * that shows text to a person reads the stream through this gate.
+ * One step of a front-door leg's stream under the verdict-first protocol,
+ * as returned by {@link FrontDoorVerdictMachine.push}.
+ */
+export type FrontDoorStep =
+  /** The leading tokens could still become a verdict token: keep buffering. */
+  | { readonly kind: "pending" }
+  /** Hold verdict: the leg is discarded and listening continues. */
+  | { readonly kind: "hold" }
+  /**
+   * The leg's output is the answer. `text` is the raw text this delta
+   * released; on the transition it includes the leading text held while the
+   * verdict was pending.
+   */
+  | { readonly kind: "answer"; readonly text: string }
+  /**
+   * Escalate verdict, decided by this delta. `bridge` is the capped holding
+   * phrase when this delta already completed it, else null while the phrase
+   * keeps streaming.
+   */
+  | { readonly kind: "escalate"; readonly bridge: string | null }
+  /** Post-verdict text still buffering toward the capped bridge. */
+  | { readonly kind: "bridging" }
+  /** The capped bridge is complete: hand off to the escalated leg. */
+  | { readonly kind: "bridge"; readonly bridge: string }
+  /** The leg already held, handed off, or finished; nothing more happens. */
+  | { readonly kind: "done" };
+
+/**
+ * The verdict-first state machine over a front-door leg's delta stream. One
+ * implementation drives every consumer of that stream: the live-voice
+ * session (which acts on the steps), the conversation-hub stream gate
+ * (which releases only the text the caller hears), and transcript hygiene
+ * (which replays a persisted row through it).
  *
- * `push` returns the text released by that delta (empty while the gate is
- * holding). `finish` is called when the leg completes normally and releases
- * a bridge that stopped short of a sentence terminator. A leg that is
- * cancelled instead spoke nothing past what `push` already released, so it
- * simply never calls `finish`.
+ * `push` feeds one delta and reports what it decided. `finish` is called
+ * when the leg completes normally: a bridge that stopped short of a
+ * sentence terminator hands off with what arrived. A leg that is cancelled
+ * instead never calls `finish`.
  */
-export interface FrontDoorStreamGate {
-  push(deltaText: string): string;
-  finish(): string;
+export interface FrontDoorVerdictMachine {
+  push(deltaText: string): FrontDoorStep;
+  finish(): FrontDoorStep;
 }
 
+const PENDING_STEP: FrontDoorStep = { kind: "pending" };
+const HOLD_STEP: FrontDoorStep = { kind: "hold" };
+const BRIDGING_STEP: FrontDoorStep = { kind: "bridging" };
+const DONE_STEP: FrontDoorStep = { kind: "done" };
+
 /**
- * Build a {@link FrontDoorStreamGate}. `holdEnabled` mirrors
+ * Build a {@link FrontDoorVerdictMachine}. `holdEnabled` mirrors
  * {@link classifyFrontDoorLeading}: true only for speculative (unified
  * front-door) legs, whose decision rule is the only one that teaches the
  * hold token.
  *
- * The three verdicts release differently, matching what the caller hears:
- *
- * - `hold`: the leg is discarded and its row deleted, so nothing is ever
- *   released.
- * - `escalate`: the only spoken text is the capped holding phrase, released
- *   in one piece once the bridge is complete (exactly what
- *   {@link capEscalationBridge} yields, so the released text, the audio, and
- *   the persisted row agree). The verdict token and anything streamed past
- *   the cap are dropped. A bridge shorter than
- *   {@link MIN_SPOKEN_BRIDGE_CHARS} releases nothing at all: the session
- *   substitutes an audio-only canned fallback for it, so there is no
- *   displayed text for the gate to agree with.
- * - `answer`: the leg's output IS the reply, so every delta passes through,
- *   including the leading text held back while the verdict was pending.
+ * The bridge handed off is exactly what {@link capEscalationBridge} yields,
+ * so the audio, the released text, the persisted row, and the phrase quoted
+ * to the escalated leg all agree. The verdict token and anything streamed
+ * past the cap are never released.
  */
-export function createFrontDoorStreamGate(
+export function createFrontDoorVerdictMachine(
   holdEnabled: boolean,
-): FrontDoorStreamGate {
+): FrontDoorVerdictMachine {
   let raw = "";
   let stage: "deciding" | "answer" | "bridging" | "done" = "deciding";
   let bridgeRaw = "";
   let releasedChars = 0;
 
-  const releaseBridge = (): string => {
+  const completeBridge = (): Extract<FrontDoorStep, { kind: "bridge" }> => {
     stage = "done";
-    const capped = capEscalationBridge(bridgeRaw);
-    // Below the spoken threshold the session throws the model's bridge away
-    // and plays a canned fallback that is audio-only, deleting the row rather
-    // than persisting a phrase the model never really produced (see
-    // `usesFallbackBridge` in `live-voice-session.ts`). Releasing the capped
-    // text here would put words on a subscriber's screen that the caller never
-    // heard, which is the same spoken/displayed divergence this gate exists to
-    // prevent.
-    return capped.length < MIN_SPOKEN_BRIDGE_CHARS ? "" : capped;
+    return { kind: "bridge", bridge: capEscalationBridge(bridgeRaw) };
   };
 
   return {
-    push(deltaText: string): string {
+    push(deltaText: string): FrontDoorStep {
       raw += deltaText;
       if (stage === "done") {
-        return "";
+        return DONE_STEP;
       }
       if (stage === "bridging") {
         bridgeRaw += deltaText;
-        return isEscalationBridgeComplete(bridgeRaw) ? releaseBridge() : "";
+        return isEscalationBridgeComplete(bridgeRaw)
+          ? completeBridge()
+          : BRIDGING_STEP;
       }
       if (stage === "deciding") {
         const verdict = classifyFrontDoorLeading(raw.trimStart(), holdEnabled);
         if (verdict === "pending") {
-          return "";
+          return PENDING_STEP;
         }
         if (verdict === "hold") {
           stage = "done";
-          return "";
+          return HOLD_STEP;
         }
         if (verdict === "escalate") {
           stage = "bridging";
           bridgeRaw = raw.trimStart().slice(ESCALATE_VERDICT_TOKEN.length);
-          return isEscalationBridgeComplete(bridgeRaw) ? releaseBridge() : "";
+          return {
+            kind: "escalate",
+            bridge: isEscalationBridgeComplete(bridgeRaw)
+              ? completeBridge().bridge
+              : null,
+          };
         }
         stage = "answer";
       }
       // Answer stage: release everything not yet released, which on the
       // transition includes the leading text the pending verdict held.
-      const chunk = raw.slice(releasedChars);
+      const text = raw.slice(releasedChars);
       releasedChars = raw.length;
-      return chunk;
+      return { kind: "answer", text };
     },
-    finish(): string {
+    finish(): FrontDoorStep {
       if (stage === "bridging") {
-        return releaseBridge();
+        return completeBridge();
       }
       stage = "done";
-      return "";
+      return DONE_STEP;
     },
   };
 }
 
+/**
+ * Verdict-first gate over a front-door leg's delta stream: given the leg's
+ * raw deltas in order, it releases only the text the caller actually hears.
+ * A front-door leg's raw stream is a control plane, not assistant speech,
+ * until its leading tokens classify, so anything downstream of the model
+ * that shows text to a person reads the stream through this gate.
+ *
+ * `push` returns the text released by that delta (empty while the gate is
+ * holding). `finish` is called when the leg completes normally and releases
+ * a bridge that stopped short of a sentence terminator. A leg that is
+ * cancelled instead spoke nothing past what `push` already released, so it
+ * simply never calls `finish`.
+ */
+export interface FrontDoorStreamGate {
+  push(deltaText: string): string;
+  finish(): string;
+}
+
+/**
+ * Build a {@link FrontDoorStreamGate} over a {@link FrontDoorVerdictMachine}.
+ *
+ * The three verdicts release differently, matching what the caller hears:
+ *
+ * - `hold`: the leg is discarded and its row deleted, so nothing is ever
+ *   released.
+ * - `escalate`: the only spoken text is the capped holding phrase, released
+ *   in one piece once the bridge is complete. A bridge shorter than
+ *   {@link MIN_SPOKEN_BRIDGE_CHARS} releases nothing at all: the session
+ *   substitutes an audio-only canned fallback for it (see
+ *   `usesFallbackBridge` in `live-voice-session.ts`) and deletes the row
+ *   rather than persisting a phrase the model never really produced, so
+ *   there is no displayed text for the gate to agree with.
+ * - `answer`: the leg's output IS the reply, so every delta passes through,
+ *   including the leading text held back while the verdict was pending.
+ */
+export function createFrontDoorStreamGate(
+  holdEnabled: boolean,
+): FrontDoorStreamGate {
+  const machine = createFrontDoorVerdictMachine(holdEnabled);
+  const releasable = (bridge: string): string =>
+    bridge.length < MIN_SPOKEN_BRIDGE_CHARS ? "" : bridge;
+  const release = (step: FrontDoorStep): string => {
+    switch (step.kind) {
+      case "answer":
+        return step.text;
+      case "escalate":
+        return step.bridge === null ? "" : releasable(step.bridge);
+      case "bridge":
+        return releasable(step.bridge);
+      default:
+        return "";
+    }
+  };
+  return {
+    push: (deltaText) => release(machine.push(deltaText)),
+    finish: () => release(machine.finish()),
+  };
+}
+
 /**
  * The escalated leg runs as its own voice turn. Rather than re-persist the
  * caller's utterance (it is already in history from the front-door leg), the

package/src/cli/commands/__tests__/apps.test.ts

@@ -0,0 +1,245 @@
+/**
+ * Tests for `assistant apps inspect` and `assistant apps refresh`.
+ */
+
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+
+import { createApp, getAppDirPath } from "../../../apps/app-store.js";
+import { writeAppSourceFingerprint } from "../../../apps/source-fingerprint.js";
+import { getWorkspacePluginsDir } from "../../../util/platform.js";
+import { runCliCommand } from "./cli-test-harness.js";
+
+let lastIpcCall: {
+  method: string;
+  params?: Record<string, unknown>;
+} | null = null;
+
+let mockIpcResult: {
+  ok: boolean;
+  result?: unknown;
+  error?: string;
+  statusCode?: number;
+} = { ok: true, result: { ok: true, compiled: true } };
+
+mock.module("../../../ipc/cli-client.js", () => ({
+  cliIpcCall: async (method: string, params?: Record<string, unknown>) => {
+    lastIpcCall = { method, params };
+    return mockIpcResult;
+  },
+  exitCodeFromIpcResult: (r: { statusCode?: number }) => {
+    if (r.statusCode === undefined) {
+      return 10;
+    }
+    if (r.statusCode >= 500) {
+      return 3;
+    }
+    if (r.statusCode >= 400) {
+      return 2;
+    }
+    return 1;
+  },
+}));
+
+const { registerAppsCommand } = await import("../apps.js");
+
+let workspaceDir: string;
+let previousWorkspaceDir: string | undefined;
+
+function freshWorkspace(): string {
+  return join(
+    tmpdir(),
+    `vellum-apps-cli-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+  );
+}
+
+function uniqueAppName(prefix: string): string {
+  return `${prefix} ${Math.random().toString(36).slice(2, 8)}`;
+}
+
+beforeEach(() => {
+  previousWorkspaceDir = process.env.VELLUM_WORKSPACE_DIR;
+  workspaceDir = freshWorkspace();
+  process.env.VELLUM_WORKSPACE_DIR = workspaceDir;
+  lastIpcCall = null;
+  mockIpcResult = {
+    ok: true,
+    result: {
+      ok: true,
+      appId: "app-1",
+      name: "Budget",
+      compiled: true,
+      compile_duration_ms: 12,
+    },
+  };
+});
+
+afterEach(() => {
+  rmSync(workspaceDir, { recursive: true, force: true });
+  if (previousWorkspaceDir === undefined) {
+    delete process.env.VELLUM_WORKSPACE_DIR;
+  } else {
+    process.env.VELLUM_WORKSPACE_DIR = previousWorkspaceDir;
+  }
+});
+
+function parseJson(stdout: string): Record<string, unknown> {
+  return JSON.parse(stdout.trim()) as Record<string, unknown>;
+}
+
+describe("assistant apps inspect", () => {
+  test("reports never_compiled for a new workspace app", async () => {
+    const name = uniqueAppName("Inspect Fresh");
+    const created = createApp({
+      name,
+      schemaJson: "{}",
+      htmlDefinition: "<h1>Budget</h1>",
+    });
+
+    const result = await runCliCommand(registerAppsCommand, [
+      "apps",
+      "inspect",
+      created.id,
+      "--json",
+    ]);
+
+    expect(result.exitCode).toBe(0);
+    const body = parseJson(result.stdout);
+    expect(body.ok).toBe(true);
+    const compile = body.compile as { status: string };
+    expect(compile.status).toBe("never_compiled");
+  });
+
+  test("reports stale after source changes since the last fingerprint", async () => {
+    const name = uniqueAppName("Inspect Stale");
+    const created = createApp({
+      name,
+      schemaJson: "{}",
+      htmlDefinition: "<h1>Budget</h1>",
+    });
+    const appDir = getAppDirPath(created.id);
+    expect(appDir.length).toBeGreaterThan(0);
+    mkdirSync(join(appDir, "src"), { recursive: true });
+    writeFileSync(join(appDir, "src", "main.tsx"), "export const n = 1;\n");
+    mkdirSync(join(appDir, "dist"), { recursive: true });
+    writeFileSync(join(appDir, "dist", "index.html"), "<html></html>");
+    writeAppSourceFingerprint(appDir, join(appDir, "dist"));
+    writeFileSync(join(appDir, "src", "main.tsx"), "export const n = 2;\n");
+
+    const result = await runCliCommand(registerAppsCommand, [
+      "apps",
+      "inspect",
+      created.id,
+      "--json",
+    ]);
+
+    expect(result.exitCode).toBe(0);
+    const body = parseJson(result.stdout);
+    const app = body.app as { id: string; source: string };
+    expect(app.id).toBe(created.id);
+    expect(app.source).toBe(appDir);
+    const compile = body.compile as {
+      status: string;
+      modified: string[];
+    };
+    expect(compile.status).toBe("stale");
+    expect(compile.modified).toEqual(["src/main.tsx"]);
+  });
+
+  test("exits 1 for an unknown app", async () => {
+    const result = await runCliCommand(registerAppsCommand, [
+      "apps",
+      "inspect",
+      "missing",
+      "--json",
+    ]);
+    expect(result.exitCode).toBe(1);
+    const body = parseJson(result.stdout);
+    expect(body.ok).toBe(false);
+    expect(String(body.error)).toContain("assistant apps list");
+  });
+});
+
+describe("assistant apps refresh", () => {
+  test("sends apps_refresh IPC for a workspace app", async () => {
+    const name = uniqueAppName("Refresh");
+    const created = createApp({
+      name,
+      schemaJson: "{}",
+      htmlDefinition: "<h1>Budget</h1>",
+    });
+
+    const result = await runCliCommand(registerAppsCommand, [
+      "apps",
+      "refresh",
+      created.id,
+      "--json",
+    ]);
+
+    expect(result.exitCode).toBe(0);
+    expect(lastIpcCall).toEqual({
+      method: "apps_refresh",
+      params: { pathParams: { id: created.id } },
+    });
+    const body = parseJson(result.stdout);
+    expect(body.compiled).toBe(true);
+  });
+
+  test("sends apps_refresh IPC for a plugin app", async () => {
+    const pluginName = `charts-${Math.random().toString(36).slice(2, 8)}`;
+    const pluginDir = join(getWorkspacePluginsDir(), pluginName);
+    mkdirSync(pluginDir, { recursive: true });
+    writeFileSync(
+      join(pluginDir, "package.json"),
+      JSON.stringify({ name: pluginName, version: "1.0.0" }),
+    );
+    mkdirSync(join(pluginDir, "apps", "viewer"), { recursive: true });
+    writeFileSync(join(pluginDir, "apps", "viewer", "index.html"), "<h1></h1>");
+
+    const result = await runCliCommand(registerAppsCommand, [
+      "apps",
+      "refresh",
+      "viewer",
+      "--json",
+    ]);
+
+    expect(result.exitCode).toBe(0);
+    expect(lastIpcCall).toEqual({
+      method: "apps_refresh",
+      params: { pathParams: { id: `plugins~${pluginName}~viewer` } },
+    });
+  });
+
+  test("exits 1 when compile fails", async () => {
+    const name = uniqueAppName("Refresh Fail");
+    const created = createApp({
+      name,
+      schemaJson: "{}",
+      htmlDefinition: "<h1>Budget</h1>",
+    });
+    mockIpcResult = {
+      ok: true,
+      result: {
+        ok: true,
+        appId: created.id,
+        name,
+        compiled: false,
+        compile_duration_ms: 8,
+        compile_errors: [{ text: "Could not resolve foo" }],
+      },
+    };
+
+    const result = await runCliCommand(registerAppsCommand, [
+      "apps",
+      "refresh",
+      created.id,
+      "--json",
+    ]);
+
+    expect(result.exitCode).toBe(1);
+    const body = parseJson(result.stdout);
+    expect(body.compiled).toBe(false);
+  });
+});

package/src/cli/commands/__tests__/bash.test.ts

@@ -0,0 +1,53 @@
+/**
+ * Tests for `assistant bash`: local sanitized spawn, no IPC round-trip.
+ */
+
+import { describe, expect, mock, test } from "bun:test";
+
+import { runCliCommand } from "./cli-test-harness.js";
+
+const ipcCalls: Array<{ method: string }> = [];
+
+mock.module("../../../ipc/cli-client.js", () => ({
+  cliIpcCall: async (method: string) => {
+    ipcCalls.push({ method });
+    return { ok: false, error: "IPC should not be used" };
+  },
+}));
+
+mock.module("../../logger.js", () => ({
+  log: {
+    info: () => {},
+    warn: () => {},
+    error: (message: string) => {
+      process.stderr.write(`${message}\n`);
+    },
+    debug: () => {},
+  },
+}));
+
+const { registerBashCommand } = await import("../bash.js");
+
+describe("assistant bash", () => {
+  test("spawns locally and prints stdout without IPC", async () => {
+    ipcCalls.length = 0;
+    const result = await runCliCommand(registerBashCommand, [
+      "bash",
+      "echo hello",
+    ]);
+    expect(ipcCalls).toEqual([]);
+    expect(result.stdout.trim()).toBe("hello");
+    expect(result.exitCode).toBe(0);
+  });
+
+  test("rejects a non-positive timeout", async () => {
+    const result = await runCliCommand(registerBashCommand, [
+      "bash",
+      "echo hello",
+      "--timeout",
+      "0",
+    ]);
+    expect(result.stderr).toContain("Invalid timeout value");
+    expect(result.exitCode).toBe(1);
+  });
+});

package/src/cli/commands/__tests__/roadmap.help.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, test } from "bun:test";
+
+import { roadmapHelp } from "../roadmap.help.js";
+
+const DISCORD_URL = "https://vellum.ai/community";
+
+describe("roadmap help is feature-proposal-only", () => {
+  test("top-level help describes feature proposals and routes bugs to Discord", () => {
+    const description = roadmapHelp.description;
+    const helpText = roadmapHelp.helpText ?? "";
+    const combined = `${description}\n${helpText}`.toLowerCase();
+
+    expect(combined).toMatch(/feature proposals?/);
+    expect(description.split(DISCORD_URL)).toHaveLength(2);
+    expect(helpText).toContain(DISCORD_URL);
+    expect(combined).toContain("instruct the user");
+    expect(combined).not.toMatch(/support@|github\.com|share feedback/);
+  });
+});