@vellumai/assistant 0.12.1 → 0.12.2-dev.202609162214.308bda0

package/src/acp/session-snapshot.ts

@@ -0,0 +1,260 @@
+import { desc, eq } from "drizzle-orm";
+
+import { getDb } from "../persistence/db-connection.js";
+import { acpSessionHistory } from "../persistence/schema/index.js";
+import { getLogger } from "../util/logger.js";
+import { acpAuthMarkerStillCurrent } from "./acp-auth-marker-store.js";
+import { getAcpSessionManager } from "./index.js";
+import type { AcpSessionManager } from "./session-manager.js";
+import type { AcpSessionState } from "./types.js";
+
+const log = getLogger("acp:session-snapshot");
+
+export interface AcpSessionSnapshot {
+  id: string;
+  agentId: string;
+  acpSessionId: string;
+  parentConversationId: string;
+  status: string;
+  startedAt: number;
+  completedAt?: number | null;
+  error?: string | null;
+  stopReason?: string | null;
+  task?: string;
+  parentToolUseId?: string;
+  authErrorCode?: string;
+  authErrorCredential?: string;
+  model?: string;
+  availableModels?: AcpSessionState["availableModels"];
+  modelRevisionEpoch?: string;
+  modelRevision?: number;
+  usedTokens?: number;
+  contextSize?: number;
+  costAmount?: number;
+  costCurrency?: string;
+  inputTokens?: number;
+  outputTokens?: number;
+  eventLog?: unknown[];
+  source: "live" | "history";
+  resumable: boolean;
+  cwd?: string | null;
+}
+
+export interface AcpSessionSnapshotPage {
+  sessions: AcpSessionSnapshot[];
+  sawEveryHistoryRow: boolean;
+}
+
+interface SnapshotOptions {
+  includeEventLog?: boolean;
+}
+
+function fromLiveState(
+  state: AcpSessionState,
+  manager: AcpSessionManager,
+  opts: SnapshotOptions,
+): AcpSessionSnapshot {
+  return {
+    id: state.id,
+    agentId: state.agentId,
+    acpSessionId: state.acpSessionId,
+    parentConversationId: state.parentConversationId,
+    status: state.status,
+    startedAt: state.startedAt,
+    completedAt: state.completedAt ?? null,
+    error: state.error ?? null,
+    stopReason: state.stopReason ?? null,
+    task: state.task,
+    parentToolUseId: state.parentToolUseId,
+    authErrorCode: state.authErrorCode,
+    authErrorCredential: state.authErrorCredential,
+    model: state.model,
+    availableModels: state.availableModels,
+    modelRevisionEpoch: state.modelRevisionEpoch,
+    modelRevision: state.modelRevision,
+    usedTokens: state.latestUsage?.usedTokens,
+    contextSize: state.latestUsage?.contextSize,
+    costAmount: state.latestUsage?.costAmount,
+    costCurrency: state.latestUsage?.costCurrency,
+    inputTokens: state.latestUsage?.inputTokens,
+    outputTokens: state.latestUsage?.outputTokens,
+    eventLog: opts.includeEventLog
+      ? manager.getBufferedUpdates(state.id)
+      : undefined,
+    source: "live",
+    resumable: false,
+  };
+}
+
+function isResumableHistoryRow(
+  row: typeof acpSessionHistory.$inferSelect,
+): boolean {
+  return Boolean(row.cwd && row.acpSessionId);
+}
+
+export function snapshotHistoryRow(
+  row: typeof acpSessionHistory.$inferSelect,
+  opts: SnapshotOptions = { includeEventLog: true },
+): AcpSessionSnapshot {
+  let eventLog: unknown[] | undefined;
+  if (opts.includeEventLog !== false) {
+    eventLog = [];
+    try {
+      const parsed = JSON.parse(row.eventLogJson) as unknown;
+      if (Array.isArray(parsed)) {
+        eventLog = parsed;
+      }
+    } catch (err) {
+      log.warn(
+        { id: row.id, err },
+        "Failed to parse event_log_json for ACP session history row",
+      );
+    }
+  }
+
+  return {
+    id: row.id,
+    agentId: row.agentId,
+    acpSessionId: row.acpSessionId,
+    parentConversationId: row.parentConversationId,
+    status: row.status,
+    startedAt: row.startedAt,
+    completedAt: row.completedAt,
+    error: row.error,
+    stopReason: row.stopReason,
+    task: row.task ?? undefined,
+    parentToolUseId: row.parentToolUseId ?? undefined,
+    authErrorCode: row.authErrorCode ?? undefined,
+    authErrorCredential: row.authErrorCredential ?? undefined,
+    usedTokens: row.usedTokens ?? undefined,
+    contextSize: row.contextSize ?? undefined,
+    costAmount: row.costAmount ?? undefined,
+    costCurrency: row.costCurrency ?? undefined,
+    inputTokens: row.inputTokens ?? undefined,
+    outputTokens: row.outputTokens ?? undefined,
+    eventLog,
+    source: "history",
+    resumable: isResumableHistoryRow(row),
+    cwd: row.cwd,
+  };
+}
+
+/**
+ * Blank `authErrorCode` on any session whose marker no longer describes the
+ * credential its agent would resolve.
+ *
+ * This comparison is what retires a Connect card: the marker no longer
+ * describing the credential in use. Applied after merging rather than inside
+ * the query, so live sessions and history rows are judged by the same rule.
+ *
+ * Resolved per agent and memoised across the batch, because precedence is per
+ * agent and each resolution costs a vault read.
+ */
+export async function withCurrentAuthMarkers<
+  T extends {
+    agentId: string;
+    authErrorCode?: string;
+    authErrorCredential?: string;
+  },
+>(
+  sessions: readonly T[],
+  resolvedFor: (agentId: string) => Promise<string | undefined>,
+): Promise<T[]> {
+  if (!sessions.some((session) => session.authErrorCode !== undefined)) {
+    return [...sessions];
+  }
+  const resolvedByAgent = new Map<string, string | undefined>();
+  const resolve = async (agentId: string) => {
+    if (!resolvedByAgent.has(agentId)) {
+      resolvedByAgent.set(agentId, await resolvedFor(agentId));
+    }
+    return resolvedByAgent.get(agentId);
+  };
+  const judged: T[] = [];
+  for (const session of sessions) {
+    if (session.authErrorCode === undefined) {
+      judged.push(session);
+      continue;
+    }
+    const current = acpAuthMarkerStillCurrent(
+      session.authErrorCredential,
+      await resolve(session.agentId),
+    );
+    judged.push(
+      current ? session : { ...session, authErrorCode: undefined },
+    );
+  }
+  return judged;
+}
+
+export function getAcpSessionSnapshot(
+  acpSessionId: string,
+  opts: SnapshotOptions = {},
+): AcpSessionSnapshot | undefined {
+  const manager = getAcpSessionManager();
+  const snapshotOptions = {
+    includeEventLog: opts.includeEventLog ?? true,
+  };
+  const live = (manager.getStatus() as AcpSessionState[]).find(
+    (state) => state.id === acpSessionId,
+  );
+  if (live) {
+    return fromLiveState(live, manager, snapshotOptions);
+  }
+
+  const row = getDb()
+    .select()
+    .from(acpSessionHistory)
+    .where(eq(acpSessionHistory.id, acpSessionId))
+    .get();
+  return row ? snapshotHistoryRow(row, snapshotOptions) : undefined;
+}
+
+export function listAcpSessionSnapshots(opts: {
+  limit: number;
+  conversationId?: string;
+  includeEventLog?: boolean;
+}): AcpSessionSnapshotPage {
+  const manager = getAcpSessionManager();
+  const inMemory = manager.getStatus() as AcpSessionState[];
+  const snapshotOptions = {
+    includeEventLog: opts.includeEventLog ?? true,
+  };
+
+  const merged = new Map<string, AcpSessionSnapshot>();
+  for (const state of inMemory) {
+    if (
+      opts.conversationId &&
+      state.parentConversationId !== opts.conversationId
+    ) {
+      continue;
+    }
+    merged.set(state.id, fromLiveState(state, manager, snapshotOptions));
+  }
+
+  const db = getDb();
+  const baseQuery = db.select().from(acpSessionHistory);
+  const filtered = opts.conversationId
+    ? baseQuery.where(
+        eq(acpSessionHistory.parentConversationId, opts.conversationId),
+      )
+    : baseQuery;
+  const historyLimit = opts.limit + merged.size;
+  const historyRows = filtered
+    .orderBy(desc(acpSessionHistory.startedAt))
+    .limit(historyLimit)
+    .all();
+
+  for (const row of historyRows) {
+    if (!merged.has(row.id)) {
+      merged.set(row.id, snapshotHistoryRow(row, snapshotOptions));
+    }
+  }
+
+  return {
+    sessions: Array.from(merged.values()).sort(
+      (a, b) => b.startedAt - a.startedAt,
+    ),
+    sawEveryHistoryRow: historyRows.length < historyLimit,
+  };
+}

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

@@ -1047,6 +1047,17 @@ export interface AgentLoopConstructorOptions {
   tools?: ToolDefinition[];
   toolExecutor?: LoopToolExecutor;
   resolveTools?: (history: Message[]) => ToolDefinition[];
+  /**
+   * Observer for the final tool array of each provider call, invoked
+   * immediately before the request leaves with exactly what goes on the wire
+   * (after any provider-native tool is appended, past the inter-call throttle
+   * and the pre-model hooks, and not at all once the run is aborted). This is
+   * the only point that sees the sent array: the dynamic `resolveTools`
+   * callback is also consulted out of band (token counting, compaction
+   * estimates), so a consumer that needs "what the last request sent"
+   * subscribes here rather than wrapping the resolver. Must not throw.
+   */
+  onToolsSent?: (tools: ToolDefinition[]) => void;
   /**
    * Conversation this loop drives. Scopes the loop-held compaction circuit
    * breaker and is the source of truth the loop's pipeline contexts and
@@ -1087,6 +1098,7 @@ export class AgentLoop {
   private config: AgentLoopConfig;
   private tools: ToolDefinition[];
   private resolveTools: ((history: Message[]) => ToolDefinition[]) | null;
+  private onToolsSent: ((tools: ToolDefinition[]) => void) | null;
   private toolExecutor: LoopToolExecutor | null;
 
   /**
@@ -1122,6 +1134,7 @@ export class AgentLoop {
       tools,
       toolExecutor,
       resolveTools,
+      onToolsSent,
       conversationId,
       resolveConversationDir,
       transformCompactedHistory,
@@ -1131,6 +1144,7 @@ export class AgentLoop {
     this.config = { ...DEFAULT_CONFIG, ...config };
     this.tools = tools ?? [];
     this.resolveTools = resolveTools ?? null;
+    this.onToolsSent = onToolsSent ?? null;
     this.toolExecutor = toolExecutor ?? null;
     this.conversationId = conversationId;
     this.resolveConversationDir = resolveConversationDir ?? null;
@@ -2241,6 +2255,11 @@ export class AgentLoop {
         // Latency: the request is about to leave for the provider. The span
         // from here to the first streamed token is time-to-first-token.
         latencyTracker?.mark("request_sent");
+        // Every await that could cancel the call is behind us; a run aborted
+        // during the throttle or a hook never reports an array it did not send.
+        if (!signal?.aborted) {
+          this.onToolsSent?.(currentTools);
+        }
         let response: ProviderResponse;
         try {
           response = await traceAsyncSection("agent-loop:provider-send", () =>
@@ -2485,6 +2504,7 @@ export class AgentLoop {
             contentBlocks: response.content.length,
             toolUseCount: modelToolUseBlocks.length,
             durationMs: providerDurationMs,
+            cacheReadInputTokens: response.usage.cacheReadInputTokens,
           },
           "LLM call complete",
         );

package/src/api/attachment-provenance.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, test } from "bun:test";
+
+import { AssistantOutboundAttachmentSchema } from "./events/assistant-outbound-attachment.js";
+import { ConversationMessageAttachmentSchema } from "./responses/conversation-message.js";
+
+const outboundFixture = {
+  id: "attachment-1",
+  filename: "screenshot.png",
+  mimeType: "image/png",
+  data: "c2NyZWVuc2hvdA==",
+  sourceType: "tool_block" as const,
+};
+
+const historyFixture = {
+  id: "attachment-1",
+  filename: "screenshot.png",
+  mimeType: "image/png",
+  sizeBytes: 10,
+  kind: "image",
+};
+
+describe("computer-use screenshot attachment provenance", () => {
+  test("new schemas accept the marker and its absence", () => {
+    expect(
+      AssistantOutboundAttachmentSchema.parse({
+        ...outboundFixture,
+        computerUseScreenshot: true,
+      }).computerUseScreenshot,
+    ).toBe(true);
+    expect(
+      AssistantOutboundAttachmentSchema.parse(outboundFixture)
+        .computerUseScreenshot,
+    ).toBeUndefined();
+
+    expect(
+      ConversationMessageAttachmentSchema.parse({
+        ...historyFixture,
+        computerUseScreenshot: true,
+      }).computerUseScreenshot,
+    ).toBe(true);
+    expect(
+      ConversationMessageAttachmentSchema.parse(historyFixture)
+        .computerUseScreenshot,
+    ).toBeUndefined();
+  });
+
+  test("legacy object parsers tolerate and strip the additive marker", () => {
+    const legacyOutbound = AssistantOutboundAttachmentSchema.omit({
+      computerUseScreenshot: true,
+    });
+    const legacyHistory = ConversationMessageAttachmentSchema.omit({
+      computerUseScreenshot: true,
+    });
+
+    expect(
+      legacyOutbound.parse({
+        ...outboundFixture,
+        computerUseScreenshot: true,
+      }),
+    ).toEqual(outboundFixture);
+    expect(
+      legacyHistory.parse({
+        ...historyFixture,
+        computerUseScreenshot: true,
+      }),
+    ).toEqual(historyFixture);
+  });
+});

package/src/api/computer-use-tool.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  isComputerUseToolCall,
+  resolveComputerUseToolName,
+} from "./computer-use-tool.js";
+
+describe("isComputerUseToolCall", () => {
+  test("recognizes direct and skill-wrapped computer-use calls", () => {
+    expect(isComputerUseToolCall("computer_use_click", {})).toBe(true);
+    expect(
+      isComputerUseToolCall("skill_execute", { tool: "computer_use_type" }),
+    ).toBe(true);
+  });
+
+  test("resolves the direct or wrapped computer-use tool name", () => {
+    expect(resolveComputerUseToolName("computer_use_click", {})).toBe(
+      "computer_use_click",
+    );
+    expect(
+      resolveComputerUseToolName("skill_execute", {
+        tool: "computer_use_scroll",
+      }),
+    ).toBe("computer_use_scroll");
+  });
+
+  test("rejects unrelated media tools and malformed skill input", () => {
+    expect(isComputerUseToolCall("browser_screenshot", {})).toBe(false);
+    expect(isComputerUseToolCall("file_read", {})).toBe(false);
+    expect(isComputerUseToolCall("image_generate", {})).toBe(false);
+    expect(isComputerUseToolCall("skill_execute", null)).toBe(false);
+    expect(isComputerUseToolCall("skill_execute", "computer_use_click")).toBe(
+      false,
+    );
+    expect(isComputerUseToolCall("skill_execute", { tool: 42 })).toBe(false);
+    expect(
+      isComputerUseToolCall("skill_execute", {
+        tool: "browser_screenshot",
+      }),
+    ).toBe(false);
+  });
+
+  test("does not classify raw-only recovered skill input", () => {
+    expect(
+      isComputerUseToolCall("skill_execute", {
+        _raw: '{"tool":"computer_use_click"}',
+      }),
+    ).toBe(false);
+    expect(
+      resolveComputerUseToolName("skill_execute", {
+        _raw: '{"tool":"computer_use_click"}',
+      }),
+    ).toBeUndefined();
+  });
+});

package/src/api/computer-use-tool.ts

@@ -0,0 +1,27 @@
+/**
+ * Resolve the host computer-use tool behind a direct or skill-wrapped call.
+ *
+ * Skills expose their selected tool in structured input. Calls recovered only
+ * from `_raw` retain their legacy behavior because this helper deliberately
+ * does not parse a second input representation.
+ */
+export function resolveComputerUseToolName(
+  name: string,
+  input: unknown,
+): string | undefined {
+  if (name.startsWith("computer_use_")) {
+    return name;
+  }
+  if (name !== "skill_execute" || input === null || typeof input !== "object") {
+    return undefined;
+  }
+  const tool = (input as Record<string, unknown>).tool;
+  return typeof tool === "string" && tool.startsWith("computer_use_")
+    ? tool
+    : undefined;
+}
+
+/** True when a tool call is backed by the host computer-use capability. */
+export function isComputerUseToolCall(name: string, input: unknown): boolean {
+  return resolveComputerUseToolName(name, input) !== undefined;
+}

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