@vellumai/assistant 0.12.0-staging.1 → 0.12.0

package/src/activation/turn-hooks.test.ts

@@ -0,0 +1,246 @@
+/**
+ * Tests for the activation turn hooks.
+ *
+ * The hooks are fire-and-forget, so the contract under test is: they
+ * normalize what the agent loop hands them, they reach the store, and a
+ * store failure never escapes as a rejection.
+ */
+
+import { mkdtempSync, rmSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+
+// Mocking the publisher (one exported function) rather than the event hub
+// keeps the mock harmless for any sibling file bun runs in the same process.
+mock.module("../runtime/sync/sync-publisher.js", () => ({
+  publishSyncInvalidation: async (tags: string[]) => ({
+    type: "sync_changed",
+    tags,
+  }),
+}));
+
+const {
+  markActivationTurnComplete,
+  readActivationProgress,
+  resetActivationStepThrottleForTesting,
+  startActivationTask,
+} = await import("./progress-store.js");
+const {
+  collectActivationArtifacts,
+  onActivationToolCall,
+  onActivationTurnComplete,
+} = await import("./turn-hooks.js");
+
+let workspaceDir: string;
+let origWorkspaceDir: string | undefined;
+
+beforeEach(() => {
+  workspaceDir = mkdtempSync(join(tmpdir(), "vellum-activation-hooks-"));
+  origWorkspaceDir = process.env.VELLUM_WORKSPACE_DIR;
+  process.env.VELLUM_WORKSPACE_DIR = workspaceDir;
+  resetActivationStepThrottleForTesting(0);
+});
+
+afterEach(() => {
+  resetActivationStepThrottleForTesting();
+  if (origWorkspaceDir === undefined) {
+    delete process.env.VELLUM_WORKSPACE_DIR;
+  } else {
+    process.env.VELLUM_WORKSPACE_DIR = origWorkspaceDir;
+  }
+  rmSync(workspaceDir, { recursive: true, force: true });
+});
+
+async function waitFor(predicate: () => boolean): Promise<void> {
+  const deadline = Date.now() + 2_000;
+  while (Date.now() < deadline) {
+    if (predicate()) {
+      return;
+    }
+    await Bun.sleep(5);
+  }
+  throw new Error("Timed out waiting for condition");
+}
+
+describe("collectActivationArtifacts", () => {
+  test("prefers the explicit filename and falls back to the basename", () => {
+    expect(
+      collectActivationArtifacts([
+        {
+          path: join(workspaceDir, "notes", "plan.md"),
+          filename: "Weekly plan.md",
+          sourceType: "sandbox_file",
+        },
+        {
+          path: join(workspaceDir, "notes", "summary.md"),
+          filename: undefined,
+          sourceType: "sandbox_file",
+        },
+        { path: "  ", filename: "ignored", sourceType: "sandbox_file" },
+      ]),
+    ).toEqual([
+      { workspacePath: "notes/plan.md", displayName: "Weekly plan.md" },
+      { workspacePath: "notes/summary.md", displayName: "summary.md" },
+    ]);
+  });
+
+  test("stores a workspace file relative to the workspace", () => {
+    expect(
+      collectActivationArtifacts([
+        {
+          path: join(workspaceDir, "notes", "plan.md"),
+          filename: undefined,
+          sourceType: "sandbox_file",
+        },
+      ]),
+    ).toEqual([{ workspacePath: "notes/plan.md", displayName: "plan.md" }]);
+  });
+
+  test("drops a host file, whose path names the user's machine", () => {
+    expect(
+      collectActivationArtifacts([
+        {
+          path: join(homedir(), "Documents", "taxes.pdf"),
+          filename: "taxes.pdf",
+          sourceType: "host_file",
+        },
+        // Dropped on its source type alone: a host read that happens to
+        // land on a path shaped like a workspace one is still a host file.
+        {
+          path: join(workspaceDir, "notes", "taxes.pdf"),
+          filename: "taxes.pdf",
+          sourceType: "host_file",
+        },
+      ]),
+    ).toEqual([]);
+  });
+
+  test("drops a path that escapes the workspace", () => {
+    expect(
+      collectActivationArtifacts([
+        {
+          path: join(workspaceDir, "..", "elsewhere", "secret.md"),
+          filename: undefined,
+          sourceType: "sandbox_file",
+        },
+        { path: workspaceDir, filename: undefined, sourceType: "sandbox_file" },
+      ]),
+    ).toEqual([]);
+  });
+
+  test("returns an empty list when the turn attached nothing", () => {
+    expect(collectActivationArtifacts([])).toEqual([]);
+  });
+});
+
+describe("onActivationToolCall", () => {
+  test("moves the linked task's step count", async () => {
+    await startActivationTask({
+      taskId: "draft-email",
+      conversationId: "conv-1",
+    });
+
+    onActivationToolCall("conv-1");
+
+    await waitFor(
+      () => readActivationProgress().tasks["draft-email"].stepCount === 1,
+    );
+  });
+
+  test("does not throw for an unlinked conversation", async () => {
+    expect(() => onActivationToolCall("conv-unlinked")).not.toThrow();
+    await Bun.sleep(10);
+    expect(readActivationProgress().tasks).toEqual({});
+  });
+});
+
+describe("onActivationTurnComplete", () => {
+  test("completes the linked task with normalized artifacts", async () => {
+    await startActivationTask({
+      taskId: "draft-email",
+      conversationId: "conv-1",
+    });
+
+    onActivationTurnComplete({
+      conversationId: "conv-1",
+      toolCallCount: 3,
+      endedAwaitingUser: false,
+      attachedFiles: [
+        {
+          path: join(workspaceDir, "notes", "plan.md"),
+          filename: undefined,
+          sourceType: "sandbox_file",
+        },
+      ],
+    });
+
+    await waitFor(
+      () => readActivationProgress().tasks["draft-email"].status === "done",
+    );
+    expect(readActivationProgress().tasks["draft-email"]).toMatchObject({
+      stepCount: 3,
+      artifacts: [{ workspacePath: "notes/plan.md", displayName: "plan.md" }],
+    });
+  });
+
+  test("is a no-op for a conversation no task points at", async () => {
+    onActivationTurnComplete({
+      conversationId: "conv-unlinked",
+      toolCallCount: 2,
+      endedAwaitingUser: false,
+      attachedFiles: [],
+    });
+    await Bun.sleep(10);
+    expect(readActivationProgress().tasks).toEqual({});
+  });
+
+  test("a turn that ended waiting on the user leaves the task running", async () => {
+    await startActivationTask({
+      taskId: "draft-email",
+      conversationId: "conv-1",
+    });
+
+    onActivationTurnComplete({
+      conversationId: "conv-1",
+      toolCallCount: 1,
+      endedAwaitingUser: true,
+      attachedFiles: [],
+    });
+    await Bun.sleep(10);
+
+    expect(readActivationProgress().tasks["draft-email"].status).toBe(
+      "started",
+    );
+  });
+
+  test("a second terminal turn changes nothing", async () => {
+    await startActivationTask({
+      taskId: "draft-email",
+      conversationId: "conv-1",
+    });
+    await markActivationTurnComplete({
+      conversationId: "conv-1",
+      toolCallCount: 2,
+      endedAwaitingUser: false,
+      artifacts: [],
+    });
+    const done = readActivationProgress().tasks["draft-email"];
+
+    onActivationTurnComplete({
+      conversationId: "conv-1",
+      toolCallCount: 7,
+      endedAwaitingUser: false,
+      attachedFiles: [
+        {
+          path: join(workspaceDir, "notes", "other.md"),
+          filename: undefined,
+          sourceType: "sandbox_file",
+        },
+      ],
+    });
+    await Bun.sleep(10);
+
+    expect(readActivationProgress().tasks["draft-email"]).toEqual(done);
+  });
+});

package/src/activation/turn-hooks.ts

@@ -0,0 +1,126 @@
+/**
+ * Turn-boundary hooks that keep activation progress in step with the
+ * conversations the checklist launched.
+ *
+ * The agent loop calls these fire-and-forget: they own their own error
+ * handling and never reject, so a regression here cannot fail a turn.
+ * They take plain data rather than loop types, which keeps this module
+ * importable (and testable) on its own.
+ */
+
+import { basename, isAbsolute, relative, resolve, sep } from "node:path";
+
+import type { ActivationArtifact } from "../api/responses/activation.js";
+import type { AttachmentSourceType } from "../daemon/assistant-attachments.js";
+import { getLogger } from "../util/logger.js";
+import { getWorkspaceDir } from "../util/platform.js";
+import {
+  bumpActivationStepCount,
+  markActivationTurnComplete,
+} from "./progress-store.js";
+
+const log = getLogger("activation-turn-hooks");
+
+/**
+ * A file the assistant attached this turn, in the shape the loop already
+ * has on hand (`PersistedAttachmentFile`): where it was read from, the
+ * display name it was stored under, and which boundary the path belongs to.
+ */
+export interface ActivationAttachedFile {
+  path: string;
+  filename?: string | undefined;
+  sourceType: AttachmentSourceType;
+}
+
+/**
+ * The workspace-relative form of `path`, or `null` when it does not name a
+ * file inside the workspace. Relative paths are read as workspace-relative
+ * already. Separators are normalized to `/` so the stored path is the same
+ * on every platform the clients render it on.
+ */
+function toWorkspacePath(workspaceDir: string, path: string): string | null {
+  const trimmed = path.trim();
+  if (trimmed.length === 0) {
+    return null;
+  }
+  const absolute = isAbsolute(trimmed)
+    ? trimmed
+    : resolve(workspaceDir, trimmed);
+  const relativePath = relative(workspaceDir, absolute);
+  if (
+    relativePath.length === 0 ||
+    relativePath === ".." ||
+    relativePath.startsWith(`..${sep}`) ||
+    isAbsolute(relativePath)
+  ) {
+    return null;
+  }
+  return relativePath.split(sep).join("/");
+}
+
+/**
+ * Normalize this turn's attached files into checklist artifacts.
+ *
+ * Only files the assistant produced in its own workspace are recorded. A
+ * host file the user approved a read of is dropped outright: its path names
+ * a location on the user's machine, and the progress file is a synced
+ * resource every client of this assistant reads. Everything kept is stored
+ * workspace-relative for the same reason, so no absolute host path reaches
+ * `GET /v1/activation/progress`.
+ *
+ * The display name falls back to the path's basename, which is what the
+ * client renders on the file card.
+ */
+export function collectActivationArtifacts(
+  attached: readonly ActivationAttachedFile[],
+): ActivationArtifact[] {
+  const workspaceDir = getWorkspaceDir();
+  const artifacts: ActivationArtifact[] = [];
+  for (const file of attached) {
+    if (file.sourceType !== "sandbox_file") {
+      continue;
+    }
+    const workspacePath = toWorkspacePath(workspaceDir, file.path);
+    if (workspacePath === null) {
+      continue;
+    }
+    const displayName =
+      file.filename?.trim() || basename(workspacePath) || workspacePath;
+    artifacts.push({ workspacePath, displayName });
+  }
+  return artifacts;
+}
+
+/**
+ * Count one tool call against the activation task linked to this
+ * conversation. A no-op when no task points at it.
+ */
+export function onActivationToolCall(conversationId: string): void {
+  void bumpActivationStepCount(conversationId).catch((err: unknown) => {
+    log.warn({ err, conversationId }, "Activation step bump failed");
+  });
+}
+
+/**
+ * Mark the activation task linked to this conversation done. A no-op when
+ * no task points at it, and when the turn ended waiting on the user
+ * (`endedAwaitingUser`). Idempotent once a task is done.
+ */
+export function onActivationTurnComplete(params: {
+  conversationId: string;
+  toolCallCount: number;
+  attachedFiles: readonly ActivationAttachedFile[];
+  endedAwaitingUser: boolean;
+}): void {
+  void markActivationTurnComplete({
+    conversationId: params.conversationId,
+    toolCallCount: params.toolCallCount,
+    artifacts: collectActivationArtifacts(params.attachedFiles),
+    endedAwaitingUser: params.endedAwaitingUser,
+  }).catch((err: unknown) => {
+    log.warn(
+      { err, conversationId: params.conversationId },
+      "Activation turn completion failed",
+    );
+  });
+}

package/src/api/events/subagent-status-changed.ts

@@ -6,11 +6,13 @@
  * `error` message (typically present when transitioning into
  * `failed`), and an optional rolling `usage` snapshot.
  *
- * NOTE: no `conversationId` field. Like `subagent_spawned`, status
- * transitions route to the parent conversation's SSE stream via
- * `parentSendToClient` closure, not via conversation-scoped seq
- * stamping. The subagent is identified by `subagentId`; clients
- * already know the parent association from the prior `spawned` event.
+ * No `conversationId` field: the parent conversation is the envelope's,
+ * stamped by that conversation's sink (`conversationEventSink` in
+ * `daemon/conversation-event-sink.ts`), which is what the hub filters
+ * and seq-stamps on. Clients read the parent from the envelope. Adding
+ * it to this payload instead would be a breaking wire change, since
+ * this schema is `.strict()` and already-deployed clients reject an
+ * unknown key by dropping the whole event.
  *
  * Canonical wire-contract source. Daemon code imports the type
  * directly from this file; external consumers import via

package/src/api/responses/activation.ts

@@ -0,0 +1,136 @@
+/**
+ * Wire contract for the activation-checklist REST endpoints.
+ *
+ *   - `GET  /v1/activation/progress`             → `ActivationProgress`
+ *   - `POST /v1/activation/tasks/:taskId/start`  → `ActivationProgress`
+ *   - `POST /v1/activation/dismiss`              → `ActivationProgress`
+ *
+ * Holds the canonical progress shape shared by the on-disk store
+ * (`activation/progress-store.ts`), the route handlers, the OpenAPI
+ * generator, and every external client, so none of them can drift.
+ *
+ * Task ids and list ids are opaque to the daemon: the task catalog lives
+ * client-side and only its identifiers are persisted here.
+ */
+
+import { z } from "zod";
+
+/** Schema version of the on-disk progress file. */
+export const ACTIVATION_PROGRESS_VERSION = 1;
+
+/**
+ * Character class every activation task id and list id must match.
+ * Lowercase kebab-case, bounded so a hostile id cannot become a giant
+ * JSON key on disk.
+ */
+export const ACTIVATION_ID_PATTERN = /^[a-z0-9-]{1,64}$/;
+
+/**
+ * Upper bound on a stored conversation id. The daemon mints uuids, so this
+ * is generous headroom rather than a fit; it exists so a client cannot turn
+ * the field into an unbounded blob on disk, the same reason task and list
+ * ids are bounded.
+ */
+export const ACTIVATION_CONVERSATION_ID_MAX_LENGTH = 128;
+
+export const ActivationIdSchema = z
+  .string()
+  .regex(ACTIVATION_ID_PATTERN)
+  .describe("Opaque lowercase-kebab identifier, 1-64 characters");
+
+/** A file the assistant produced while working a task. */
+export const ActivationArtifactSchema = z.object({
+  workspacePath: z
+    .string()
+    .describe("Path of the produced file, as the assistant attached it"),
+  displayName: z.string().describe("Human-readable file name for the card"),
+});
+export type ActivationArtifact = z.infer<typeof ActivationArtifactSchema>;
+
+/** Per-task progress record. */
+export const ActivationTaskProgressSchema = z.object({
+  status: z
+    .enum(["started", "done"])
+    .describe("`started` while the linked conversation is working the task"),
+  conversationId: z
+    .string()
+    .max(ACTIVATION_CONVERSATION_ID_MAX_LENGTH)
+    .describe("Conversation the task was launched into"),
+  startedAt: z.string().describe("ISO timestamp of the launch"),
+  completedAt: z
+    .string()
+    .nullable()
+    .describe("ISO timestamp of the completing turn, null while started"),
+  stepCount: z
+    .number()
+    .int()
+    .nullable()
+    .describe("Tool calls observed in the linked conversation so far"),
+  artifacts: z
+    .array(ActivationArtifactSchema)
+    .describe("Files the completing turn attached"),
+});
+export type ActivationTaskProgress = z.infer<
+  typeof ActivationTaskProgressSchema
+>;
+
+/** Full activation progress resource. */
+export const ActivationProgressSchema = z.object({
+  version: z.literal(ACTIVATION_PROGRESS_VERSION).describe("Schema version"),
+  listId: z
+    .string()
+    .nullable()
+    .describe("Task list frozen on the first write, null before then"),
+  modalDismissedAt: z
+    .string()
+    .nullable()
+    .describe("ISO timestamp the welcome modal was dismissed"),
+  allDoneShownAt: z
+    .string()
+    .nullable()
+    .describe("ISO timestamp the celebration modal was dismissed"),
+  tasks: z
+    .record(z.string(), ActivationTaskProgressSchema)
+    .describe("Progress keyed by task id"),
+});
+export type ActivationProgress = z.infer<typeof ActivationProgressSchema>;
+
+export const ActivationTaskStartRequestSchema = z.object({
+  conversationId: z
+    .string()
+    .min(1)
+    .max(ACTIVATION_CONVERSATION_ID_MAX_LENGTH)
+    .describe("Conversation the task prompt was sent to"),
+  listId: ActivationIdSchema.optional().describe(
+    "List the task came from, stored only while no list is frozen",
+  ),
+});
+export type ActivationTaskStartRequest = z.infer<
+  typeof ActivationTaskStartRequestSchema
+>;
+
+export const ActivationDismissKindSchema = z
+  .enum(["modal", "all-done"])
+  .describe("Which surface was dismissed");
+export type ActivationDismissKind = z.infer<typeof ActivationDismissKindSchema>;
+
+export const ActivationDismissRequestSchema = z.object({
+  kind: ActivationDismissKindSchema,
+  listId: ActivationIdSchema.optional().describe(
+    "List the surface showed, stored only while no list is frozen",
+  ),
+});
+export type ActivationDismissRequest = z.infer<
+  typeof ActivationDismissRequestSchema
+>;
+
+/** Empty progress, returned before the store file exists. */
+export function emptyActivationProgress(): ActivationProgress {
+  return {
+    version: ACTIVATION_PROGRESS_VERSION,
+    listId: null,
+    modalDismissedAt: null,
+    allDoneShownAt: null,
+    tasks: {},
+  };
+}

package/src/apps/app-store.ts

@@ -34,6 +34,8 @@ import {
   resolve,
 } from "node:path";
 
+import { bridgeEmojiAppIcon } from "@vellumai/app-icons";
+
 import { resolveConversationLineage } from "../daemon/conversation-lineage.js";
 import { rawAll } from "../persistence/raw-query.js";
 import { isPluginDisabled } from "../plugins/disabled-state.js";
@@ -625,6 +627,9 @@ export function getApp(id: string): AppDefinition | null {
   }
   const raw = readFileSync(filePath, "utf-8");
   const app = JSON.parse(raw) as AppDefinition;
+  /* An emoji icon reads back as the registry name it maps to, so every client
+     draws the same glyph set. */
+  app.icon = bridgeEmojiAppIcon(app.icon);
 
   // Read htmlDefinition from {dirName}/index.html on disk
   const indexPath = join(appDir, "index.html");
@@ -674,6 +679,9 @@ export function listApps(): AppDefinition[] {
     try {
       const raw = readFileSync(filePath, "utf-8");
       const app = JSON.parse(raw) as AppDefinition;
+      /* An emoji from before the icon registry reads back as its registry name
+     (see app-icons.ts), so every client draws the same glyph set. */
+      app.icon = bridgeEmojiAppIcon(app.icon);
 
       apps.push(app);
     } catch {

package/src/cli/__tests__/catalog-search-help.test.ts

@@ -13,9 +13,9 @@ import { channelsHelp } from "../commands/channels/index.help.js";
 import { pluginsHelp } from "../commands/plugins.help.js";
 import { skillsHelp } from "../commands/skills.help.js";
 
-function searchHelp(
-  help: { subcommands?: Array<{ name: string; helpText?: string }> },
-): { name: string; helpText?: string } {
+function searchHelp(help: {
+  subcommands?: Array<{ name: string; helpText?: string }>;
+}): { name: string; helpText?: string } {
   const search = help.subcommands?.find((sub) => sub.name === "search");
   if (!search) {
     throw new Error("expected a search subcommand");
@@ -59,8 +59,10 @@ describe("catalog search help for setup-intent retrieval", () => {
     expect(list?.helpText).toBeDefined();
     expect(indexed).toContain("assistant plugins search <name>");
     expect(indexed).toContain("not listed");
-    expect(channelsHelp.description).toBe(
-      "Inspect and repair messaging channels",
+    // The description names the surface generically; a provider name in it
+    // would present the built-in set as the whole catalog.
+    expect(channelsHelp.description.toLowerCase()).toContain(
+      "messaging channels",
     );
     expect(channelsHelp.description.toLowerCase()).not.toContain("slack");
     expect(channelsHelp.description.toLowerCase()).not.toContain("telegram");

package/src/cli/commands/__tests__/cli-test-harness.ts

@@ -3,9 +3,10 @@
  * Commander program, runs it against captured output sinks, and returns what
  * the command emitted plus the resulting exit code.
  *
- * `process.stdout.write`, `console.log`, and `console.error` are captured for
- * the duration of the run, so command output lands in the result regardless of
- * which sink the command writes to; `process.exitCode` is reset afterwards.
+ * `process.stdout.write`, `process.stderr.write`, `console.log`, and
+ * `console.error` are captured for the duration of the run, so command output
+ * lands in the result regardless of which sink the command writes to;
+ * `process.exitCode` is reset afterwards.
  * The caller passes its own (possibly mock-backed) registration function, so
  * this helper imports nothing from `src/` beyond what any test file may
  * import itself (see the test-machinery isolation rules in assistant/CLAUDE.md).
@@ -26,6 +27,7 @@ export async function runCliCommand(
   args: string[],
 ): Promise<CliCommandRunResult> {
   const originalStdoutWrite = process.stdout.write.bind(process.stdout);
+  const originalStderrWrite = process.stderr.write.bind(process.stderr);
   const originalConsoleLog = console.log;
   const originalConsoleError = console.error;
   const stdoutChunks: string[] = [];
@@ -38,6 +40,12 @@ export async function runCliCommand(
     events.push(text);
     return true;
   }) as typeof process.stdout.write;
+  process.stderr.write = ((chunk: unknown) => {
+    const text = typeof chunk === "string" ? chunk : String(chunk);
+    stderrChunks.push(text);
+    events.push(text);
+    return true;
+  }) as typeof process.stderr.write;
   console.log = (...logArgs: unknown[]) => {
     const text = logArgs.map(String).join(" ") + "\n";
     stdoutChunks.push(text);
@@ -66,6 +74,7 @@ export async function runCliCommand(
     }
   } finally {
     process.stdout.write = originalStdoutWrite;
+    process.stderr.write = originalStderrWrite;
     console.log = originalConsoleLog;
     console.error = originalConsoleError;
   }

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

@@ -9,7 +9,9 @@ import { Command } from "commander";
 let mockCalls: Array<[string, Record<string, unknown> | undefined]> = [];
 let mockResponses: unknown[] = [];
 
+const actualCliClient = await import("../../../../ipc/cli-client.js");
 mock.module("../../../../ipc/cli-client.js", () => ({
+  ...actualCliClient,
   cliIpcCall: async (method: string, params?: Record<string, unknown>) => {
     mockCalls.push([method, params]);
     return mockResponses.shift() ?? { ok: true, result: { success: true } };