@vellumai/assistant 0.12.1 → 0.12.2-staging.2

package/src/acp/types.ts

@@ -4,14 +4,20 @@
 
 import type { StopReason } from "@agentclientprotocol/sdk";
 
+import type { AcpAgentConfig as ConfiguredAcpAgent } from "../config/acp-schema.js";
+import type { AcpModelOption } from "./model-config.js";
+
 /**
- * Configuration for a single ACP agent process.
+ * A configured ACP agent plus what the daemon learns about it at spawn time.
+ * The configured half is the schema's own inferred type, so a new config leaf
+ * is declared once, in `config/acp-schema.ts`.
  */
-export interface AcpAgentConfig {
+export interface AcpAgentConfig extends ConfiguredAcpAgent {
+  /**
+   * Always set on a resolved agent: the resolver fills in a bundled profile's
+   * command when the config entry omits it.
+   */
   command: string;
-  args: string[];
-  description?: string;
-  env?: Record<string, string>;
   /**
    * Identity of the Claude token `prepareAgentEnv` resolved into `env`,
    * whichever source it came from. Recorded on the history row when Claude
@@ -51,6 +57,32 @@ export interface AcpSessionState {
   authErrorCredential?: string;
   /** Latest context-window usage gauge, from the most recent `usage_update`. */
   latestUsage?: AcpUsageSnapshot;
+  /**
+   * Model the session is running on, as the adapter reports it. Absent while
+   * the adapter advertises no model selector, which is how the feature stays
+   * invisible for agents that cannot switch models.
+   */
+  model?: string;
+  /** Models the adapter offers this session, flattened from its selector. */
+  availableModels?: AcpModelOption[];
+  /** Time-ordered identifier of the assistant process issuing revisions. */
+  modelRevisionEpoch?: string;
+  /** Monotonic revision within `modelRevisionEpoch`. */
+  modelRevision?: number;
+}
+
+/**
+ * Statuses a session is still live in. One list for every place that asks the
+ * question: the boot sweep over persisted rows, the in-memory liveness guard,
+ * `close()`, and the delete route's conflict guard.
+ */
+export const ACP_LIVE_STATUSES = ["running", "initializing"] as const;
+
+/** Whether a status is one a session can still move from. */
+export function isLiveAcpStatus(
+  status: AcpSessionState["status"],
+): status is (typeof ACP_LIVE_STATUSES)[number] {
+  return ACP_LIVE_STATUSES.some((live) => live === status);
 }
 
 /** Context-window usage snapshot tracked from ACP `usage_update`. */
@@ -64,3 +96,16 @@ export interface AcpUsageSnapshot {
   /** Cumulative output tokens across all turns, from `PromptResponse.usage`. */
   outputTokens?: number;
 }
+
+/**
+ * The adapter answered `session/set_config_option` with an error: the value
+ * was refused. Raised only for the adapter's own answer to that request, so a
+ * closed connection, an exited process, or a failed authentication is never
+ * mistaken for a refusal.
+ */
+export class AcpConfigOptionRefusedError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "AcpConfigOptionRefusedError";
+  }
+}

package/src/agent/loop.ts

@@ -2485,6 +2485,7 @@ export class AgentLoop {
             contentBlocks: response.content.length,
             toolUseCount: modelToolUseBlocks.length,
             durationMs: providerDurationMs,
+            cacheReadInputTokens: response.usage.cacheReadInputTokens,
           },
           "LLM call complete",
         );

package/src/api/events/acp-session-model-update.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, test } from "bun:test";
+
+import { AcpSessionModelUpdateEventSchema } from "./acp-session-model-update.js";
+
+const MODEL_REVISION_EPOCH = "01900000-0000-7000-8000-000000000001";
+
+describe("AcpSessionModelUpdateEventSchema", () => {
+  test("parses an event carrying the selection and grouped options", () => {
+    const event = {
+      type: "acp_session_model_update" as const,
+      acpSessionId: "acp-session-abc",
+      modelRevisionEpoch: MODEL_REVISION_EPOCH,
+      modelRevision: 7,
+      model: "opus",
+      availableModels: [
+        { value: "opus", label: "Opus", description: "Most capable" },
+        { value: "sonnet", label: "Sonnet", group: "Recommended" },
+      ],
+    };
+
+    const result = AcpSessionModelUpdateEventSchema.safeParse(event);
+
+    expect(result.success).toBe(true);
+    expect(result.success && result.data).toEqual(event);
+  });
+
+  test("parses an adapter with no selection and no options", () => {
+    const event = {
+      type: "acp_session_model_update" as const,
+      acpSessionId: "acp-session-abc",
+      modelRevisionEpoch: MODEL_REVISION_EPOCH,
+      modelRevision: 8,
+      availableModels: [],
+    };
+
+    const result = AcpSessionModelUpdateEventSchema.safeParse(event);
+
+    expect(result.success).toBe(true);
+    expect(result.success && result.data).toEqual(event);
+  });
+
+  test("rejects a missing availableModels array", () => {
+    const result = AcpSessionModelUpdateEventSchema.safeParse({
+      type: "acp_session_model_update",
+      acpSessionId: "acp-session-abc",
+      modelRevisionEpoch: MODEL_REVISION_EPOCH,
+      modelRevision: 9,
+      model: "opus",
+    });
+
+    expect(result.success).toBe(false);
+  });
+
+  test("rejects a missing model revision", () => {
+    const result = AcpSessionModelUpdateEventSchema.safeParse({
+      type: "acp_session_model_update",
+      acpSessionId: "acp-session-abc",
+      modelRevisionEpoch: MODEL_REVISION_EPOCH,
+      availableModels: [],
+    });
+
+    expect(result.success).toBe(false);
+  });
+
+  test("rejects a missing model revision epoch", () => {
+    const result = AcpSessionModelUpdateEventSchema.safeParse({
+      type: "acp_session_model_update",
+      acpSessionId: "acp-session-abc",
+      modelRevision: 10,
+      availableModels: [],
+    });
+
+    expect(result.success).toBe(false);
+  });
+
+  test("rejects an unrecognized field under .strict()", () => {
+    const result = AcpSessionModelUpdateEventSchema.safeParse({
+      type: "acp_session_model_update",
+      acpSessionId: "acp-session-abc",
+      modelRevisionEpoch: MODEL_REVISION_EPOCH,
+      modelRevision: 11,
+      availableModels: [],
+      unexpected: true,
+    });
+
+    expect(result.success).toBe(false);
+  });
+});

package/src/api/events/acp-session-model-update.ts

@@ -0,0 +1,46 @@
+/**
+ * `acp_session_model_update` SSE event.
+ *
+ * Server to client snapshot of an ACP session's model selection, derived from
+ * the adapter's `configOptions`. `model` is the currently selected value (absent
+ * when the adapter reports none) and `availableModels` is the flattened set of
+ * values the adapter offers, empty when it advertises no model selector.
+ * `modelRevisionEpoch` scopes `modelRevision` to one assistant process, and
+ * the pair orders this snapshot against the same session state returned by
+ * `GET /v1/acp/sessions`. A side gauge, not part of the ordered update
+ * timeline: carries no `seq`.
+ *
+ * `.strict()` like the other ACP events, for the reason spelled out in
+ * `acp-auth-required.ts`: an older packaged client rejects an event carrying a
+ * field it does not know, so additive signals get their own event type.
+ *
+ * Canonical wire-contract source. Re-exported to external consumers via
+ * `@vellumai/assistant-api` (the `api/index.ts` barrel).
+ */
+
+import { z } from "zod";
+
+export const AcpSessionModelUpdateEventSchema = z
+  .object({
+    type: z.literal("acp_session_model_update"),
+    acpSessionId: z.string(),
+    modelRevisionEpoch: z.string().uuid(),
+    modelRevision: z.number().int().nonnegative(),
+    model: z.string().optional(),
+    availableModels: z.array(
+      z.object({
+        /** Adapter-reported value to pass back when selecting this model. */
+        value: z.string(),
+        /** Human-readable label from the adapter. */
+        label: z.string(),
+        description: z.string().optional(),
+        /** Name of the adapter's option group, when the options were grouped. */
+        group: z.string().optional(),
+      }),
+    ),
+  })
+  .strict();
+
+export type AcpSessionModelUpdateEvent = z.infer<
+  typeof AcpSessionModelUpdateEventSchema
+>;

package/src/api/events/app-files-changed.ts

@@ -1,9 +1,10 @@
 /**
  * `app_files_changed` SSE event.
  *
- * Broadcast when an app's source files change on disk — emitted when a new
- * app is created and by the app source watcher on edits — so connected
- * clients re-read the app (refresh preview, reload the running surface).
+ * Broadcast after an app is created, compiled, or otherwise updated so
+ * connected clients re-read the app (refresh preview, reload the running
+ * surface). Workspace compiles go through `assistant apps refresh` or
+ * `app_refresh`; file edits do not emit this on their own.
  *
  * Canonical wire-contract source. Daemon code imports the type
  * directly from this file; external consumers import via

package/src/api/events/notification-intent.ts

@@ -20,6 +20,8 @@ import { z } from "zod";
 export const NotificationIntentEventSchema = z.object({
   type: z.literal("notification_intent"),
   sourceEventName: z.string(),
+  /** Verified assistant name supplied by the assistant when available. */
+  assistantName: z.string().optional(),
   title: z.string(),
   body: z.string(),
   deliveryId: z.string().optional(),

package/src/api/events/user-message-echo.ts

@@ -1,7 +1,7 @@
 /**
  * `user_message_echo` SSE event.
  *
- * Emitted when a user message is persisted to a conversation — direct
+ * Emitted when a user message is persisted to a conversation: direct
  * sends, slash/canned/compaction turns, and synthetic surface-action
  * prompts. Carries the user's outbound `text` so clients that did not
  * originate the send (passive viewers, other devices) can render the
@@ -15,6 +15,11 @@
  * 202 response. `requestId` correlates with `message_queued` /
  * `message_dequeued` for the same turn.
  *
+ * `cameraFrame` is present only on standalone ambient camera-frame echoes,
+ * before `sync_changed` refetches hydrate their images. Photos and spoken
+ * turns omit it. Older strict parsers drop marked echoes and recover the
+ * persisted rows through the following `sync_changed` invalidation.
+ *
  * Canonical wire-contract source. Daemon code imports the type directly
  * from this file; external consumers import via `@vellumai/assistant-api`.
  */
@@ -29,6 +34,7 @@ export const UserMessageEchoEventSchema = z
     messageId: z.string().optional(),
     requestId: z.string().optional(),
     clientMessageId: z.string().optional(),
+    cameraFrame: z.literal(true).optional(),
   })
   .strict();
 

package/src/api/index.ts

@@ -3,6 +3,7 @@ import { z } from "zod";
 import { AcpAuthRequiredEventSchema } from "./events/acp-auth-required.js";
 import { AcpSessionCompletedEventSchema } from "./events/acp-session-completed.js";
 import { AcpSessionErrorEventSchema } from "./events/acp-session-error.js";
+import { AcpSessionModelUpdateEventSchema } from "./events/acp-session-model-update.js";
 import { AcpSessionSpawnedEventSchema } from "./events/acp-session-spawned.js";
 import { AcpSessionUpdateEventSchema } from "./events/acp-session-update.js";
 import { AcpSessionUsageEventSchema } from "./events/acp-session-usage.js";
@@ -186,6 +187,10 @@ export {
   type AcpSessionErrorEvent,
   AcpSessionErrorEventSchema,
 } from "./events/acp-session-error.js";
+export {
+  type AcpSessionModelUpdateEvent,
+  AcpSessionModelUpdateEventSchema,
+} from "./events/acp-session-model-update.js";
 export {
   type AcpSessionSpawnedEvent,
   AcpSessionSpawnedEventSchema,
@@ -964,6 +969,7 @@ export const AssistantEventSchema = z.discriminatedUnion("type", [
   AcpAuthRequiredEventSchema,
   AcpSessionCompletedEventSchema,
   AcpSessionErrorEventSchema,
+  AcpSessionModelUpdateEventSchema,
   AcpSessionSpawnedEventSchema,
   AcpSessionUpdateEventSchema,
   AcpSessionUsageEventSchema,

package/src/api/responses/conversation-message.ts

@@ -615,6 +615,11 @@ export const ConversationMessageSchema = z.object({
    *  sentinel text, and treat the row as the turn's reply so nothing keeps
    *  waiting for one. */
   noResponse: z.boolean().optional(),
+  /** Set only on standalone ambient camera-frame rows, derived from
+   *  `messageMetadataIsAmbientSightKeep`. Clients may fold consecutive frames
+   *  into the following user message. Absent on shutter photos, spoken turns
+   *  carrying parked frames, and every other row. */
+  cameraFrame: z.literal(true).optional(),
   /** How this assistant row's plain text reached the user, set only on a turn
    *  that routed its reply through the `send_user_message` tool. `"private"`
    *  means the row's text blocks are the model's working notes and the text

package/src/apps/app-store.ts

@@ -114,7 +114,7 @@ export function resolveEffectiveAppHtmlFromDir(sourceDir: string): string {
   if (isLegacySingleFileDir(sourceDir)) {
     return UNSUPPORTED_LEGACY_APP_HTML;
   }
-  return `<p>App compilation failed. Edit a source file to trigger a rebuild.</p>`;
+  return `<p>App compilation failed. Run <code>assistant apps refresh</code> to rebuild.</p>`;
 }
 
 /**

package/src/apps/resolve-app.ts

@@ -0,0 +1,81 @@
+/**
+ * Resolve a user-facing app query (display name, slug, or id) to an
+ * enumerated app. Used by `assistant apps inspect` / `refresh`.
+ */
+
+import { basename } from "node:path";
+
+import { type EnumeratedApp, listAllApps } from "./app-store.js";
+
+export type ResolveAppQueryResult =
+  | { readonly ok: true; readonly app: EnumeratedApp }
+  | { readonly ok: false; readonly reason: "not_found"; readonly query: string }
+  | {
+      readonly ok: false;
+      readonly reason: "ambiguous";
+      readonly query: string;
+      readonly matches: readonly EnumeratedApp[];
+    };
+
+function matchesQuery(app: EnumeratedApp, query: string): boolean {
+  if (app.id === query) {
+    return true;
+  }
+  const lowered = query.toLowerCase();
+  if (app.name.toLowerCase() === lowered) {
+    return true;
+  }
+  const dirName = basename(app.sourcePath);
+  return dirName.toLowerCase() === lowered;
+}
+
+/**
+ * Resolve `query` against every surfaced app. Matching is exact on id, and
+ * case-insensitive on display name and directory slug. Multiple distinct apps
+ * that match yield `ambiguous` rather than picking a winner.
+ */
+export function resolveAppQuery(query: string): ResolveAppQueryResult {
+  const trimmed = query.trim();
+  if (trimmed.length === 0) {
+    return { ok: false, reason: "not_found", query };
+  }
+
+  const matches: EnumeratedApp[] = [];
+  const seen = new Set<string>();
+  for (const app of listAllApps()) {
+    if (!matchesQuery(app, trimmed) || seen.has(app.id)) {
+      continue;
+    }
+    seen.add(app.id);
+    matches.push(app);
+  }
+
+  if (matches.length === 1) {
+    return { ok: true, app: matches[0] };
+  }
+  if (matches.length > 1) {
+    return { ok: false, reason: "ambiguous", query: trimmed, matches };
+  }
+  return { ok: false, reason: "not_found", query: trimmed };
+}
+
+export function formatAppMatch(app: EnumeratedApp): string {
+  const origin =
+    app.origin.kind === "plugin"
+      ? `plugin ${app.origin.pluginName}`
+      : "workspace";
+  return `${app.name} (${origin}, ${app.id})`;
+}
+
+export function appNotFoundMessage(query: string): string {
+  return `App "${query}" not found. Run 'assistant apps list' to see available apps.`;
+}
+
+export function appAmbiguousMessage(
+  query: string,
+  matches: readonly EnumeratedApp[],
+): string {
+  const listed = matches.map((app) => `  ${formatAppMatch(app)}`).join("\n");
+  return `Ambiguous app name "${query}". Matches:\n${listed}\nRun 'assistant apps list' and pass a unique name, slug, or id.`;
+}
+

package/src/apps/source-fingerprint.ts

@@ -0,0 +1,266 @@
+/**
+ * Content fingerprint of an app's source tree, recorded at compile time so
+ * later inspects can tell whether source has drifted from the last successful
+ * build.
+ *
+ * The fingerprint is a one-way per-file digest map written into
+ * `dist/.source-fingerprint.json` after a successful compile. It answers "did
+ * this change?" and "which files?", not a reconstructable diff.
+ */
+
+import { createHash } from "node:crypto";
+import {
+  existsSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+
+/** Digest algorithm recorded alongside the file map, for forward compatibility. */
+export type FingerprintAlgorithm = "sha256";
+
+/** Filename written into `dist/` next to compiled output. */
+export const SOURCE_FINGERPRINT_FILENAME = ".source-fingerprint.json";
+
+/** Directory names skipped at the app root only (compile output and records). */
+const ROOT_SKIP_DIRS: ReadonlySet<string> = new Set(["dist", "records"]);
+
+/** Directory names skipped at any depth. */
+const SKIP_DIRS_ANY_DEPTH: ReadonlySet<string> = new Set([
+  "node_modules",
+  ".git",
+]);
+
+/**
+ * Per-file content digest of an app source tree. Keys are POSIX-style
+ * (forward-slash) paths relative to the app directory; values are lowercase
+ * hex SHA-256 digests of each file's bytes.
+ */
+export interface AppSourceFingerprint {
+  readonly algorithm: FingerprintAlgorithm;
+  readonly files: Readonly<Record<string, string>>;
+  /** ISO-8601 timestamp of the compile that produced this baseline, when known. */
+  readonly compiledAt?: string;
+}
+
+/**
+ * Difference between a recorded fingerprint and the current on-disk source.
+ * Paths are POSIX-relative. A rename surfaces as one `removed` plus one `added`.
+ */
+export interface FingerprintComparison {
+  readonly modified: readonly string[];
+  readonly added: readonly string[];
+  readonly removed: readonly string[];
+  readonly clean: boolean;
+}
+
+export type AppSourceInspectStatus =
+  | "clean"
+  | "stale"
+  | "never_compiled"
+  | "unknown_baseline";
+
+export interface AppSourceInspectResult {
+  readonly status: AppSourceInspectStatus;
+  readonly compiledAt: string | null;
+  readonly modified: readonly string[];
+  readonly added: readonly string[];
+  readonly removed: readonly string[];
+}
+
+function hashFile(absPath: string): string | null {
+  try {
+    return createHash("sha256").update(readFileSync(absPath)).digest("hex");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Walk `appDir` and digest every regular source file. Skips `dist/` and
+ * `records/` at the app root, and `node_modules` / `.git` at any depth.
+ * Symlinks are neither visited nor followed.
+ */
+export function computeAppSourceFingerprint(
+  appDir: string,
+): AppSourceFingerprint {
+  const files: Record<string, string> = {};
+
+  const walk = (relDir: string): void => {
+    const absDir = relDir ? join(appDir, relDir) : appDir;
+    let entries;
+    try {
+      entries = readdirSync(absDir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (relDir === "" && ROOT_SKIP_DIRS.has(entry.name)) {
+        continue;
+      }
+      if (entry.isSymbolicLink()) {
+        continue;
+      }
+      if (entry.isDirectory() && SKIP_DIRS_ANY_DEPTH.has(entry.name)) {
+        continue;
+      }
+      const rel = relDir ? `${relDir}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        walk(rel);
+      } else if (entry.isFile()) {
+        const digest = hashFile(join(absDir, entry.name));
+        if (digest !== null) {
+          files[rel] = digest;
+        }
+      }
+    }
+  };
+
+  walk("");
+  return { algorithm: "sha256", files };
+}
+
+export function compareAppSourceFingerprint(
+  appDir: string,
+  baseline: AppSourceFingerprint,
+): FingerprintComparison {
+  const current = computeAppSourceFingerprint(appDir).files;
+  const modified: string[] = [];
+  const added: string[] = [];
+  const removed: string[] = [];
+
+  for (const [path, digest] of Object.entries(current)) {
+    const recorded = baseline.files[path];
+    if (recorded === undefined) {
+      added.push(path);
+    } else if (recorded !== digest) {
+      modified.push(path);
+    }
+  }
+  for (const path of Object.keys(baseline.files)) {
+    if (current[path] === undefined) {
+      removed.push(path);
+    }
+  }
+
+  modified.sort();
+  added.sort();
+  removed.sort();
+  return {
+    modified,
+    added,
+    removed,
+    clean: modified.length === 0 && added.length === 0 && removed.length === 0,
+  };
+}
+
+/**
+ * Parse a fingerprint from already-decoded JSON. Lenient: any shape problem
+ * yields `null` so a missing or hand-edited sidecar reports "no baseline"
+ * rather than throwing.
+ */
+export function parseAppSourceFingerprint(
+  value: unknown,
+): AppSourceFingerprint | null {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return null;
+  }
+  const obj = value as Record<string, unknown>;
+  if (obj.algorithm !== "sha256") {
+    return null;
+  }
+  const rawFiles = obj.files;
+  if (
+    typeof rawFiles !== "object" ||
+    rawFiles === null ||
+    Array.isArray(rawFiles)
+  ) {
+    return null;
+  }
+  const files: Record<string, string> = {};
+  for (const [path, digest] of Object.entries(rawFiles)) {
+    if (typeof digest !== "string") {
+      return null;
+    }
+    files[path] = digest;
+  }
+  const compiledAt =
+    typeof obj.compiledAt === "string" ? obj.compiledAt : undefined;
+  return compiledAt === undefined
+    ? { algorithm: "sha256", files }
+    : { algorithm: "sha256", files, compiledAt };
+}
+
+export function readAppSourceFingerprint(
+  appDir: string,
+): AppSourceFingerprint | null {
+  const path = join(appDir, "dist", SOURCE_FINGERPRINT_FILENAME);
+  if (!existsSync(path)) {
+    return null;
+  }
+  try {
+    return parseAppSourceFingerprint(JSON.parse(readFileSync(path, "utf-8")));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write a source fingerprint into `distDir`. Pass the snapshot taken
+ * before compile so inspect compares against the tree that produced this
+ * dist, even if source changes during the build.
+ */
+export function writeAppSourceFingerprint(
+  appDir: string,
+  distDir: string,
+  fingerprint: AppSourceFingerprint = computeAppSourceFingerprint(appDir),
+): void {
+  const payload: AppSourceFingerprint = {
+    algorithm: fingerprint.algorithm,
+    compiledAt: fingerprint.compiledAt ?? new Date().toISOString(),
+    files: fingerprint.files,
+  };
+  writeFileSync(
+    join(distDir, SOURCE_FINGERPRINT_FILENAME),
+    `${JSON.stringify(payload)}\n`,
+    "utf-8",
+  );
+}
+
+/**
+ * Compare current app source against the fingerprint recorded at last
+ * successful compile.
+ */
+export function inspectAppSource(appDir: string): AppSourceInspectResult {
+  const compiled = existsSync(join(appDir, "dist", "index.html"));
+  if (!compiled) {
+    return {
+      status: "never_compiled",
+      compiledAt: null,
+      modified: [],
+      added: [],
+      removed: [],
+    };
+  }
+
+  const baseline = readAppSourceFingerprint(appDir);
+  if (baseline === null) {
+    return {
+      status: "unknown_baseline",
+      compiledAt: null,
+      modified: [],
+      added: [],
+      removed: [],
+    };
+  }
+
+  const comparison = compareAppSourceFingerprint(appDir, baseline);
+  return {
+    status: comparison.clean ? "clean" : "stale",
+    compiledAt: baseline.compiledAt ?? null,
+    modified: comparison.modified,
+    added: comparison.added,
+    removed: comparison.removed,
+  };
+}