@vellumai/assistant 0.9.0 → 0.10.0-staging.2

package/src/__tests__/workspace-migration-drop-collect-usage-data.test.ts

@@ -0,0 +1,118 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+// ---------------------------------------------------------------------------
+// Mock state
+// ---------------------------------------------------------------------------
+
+const existsSyncFn = mock((_path: string): boolean => false);
+const readFileSyncFn = mock((_path: string, _encoding: string): string => "");
+const writeFileSyncFn = mock((_path: string, _data: string): void => undefined);
+
+// ---------------------------------------------------------------------------
+// Mock modules — before importing module under test
+// ---------------------------------------------------------------------------
+
+mock.module("node:fs", () => ({
+  existsSync: existsSyncFn,
+  readFileSync: readFileSyncFn,
+  writeFileSync: writeFileSyncFn,
+}));
+
+// Import after mocking
+import { dropCollectUsageDataMigration } from "../workspace/migrations/106-drop-collect-usage-data.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const WORKSPACE_DIR = "/tmp/test-workspace";
+const CONFIG_PATH = `${WORKSPACE_DIR}/config.json`;
+
+function setupConfigExists(config: unknown) {
+  existsSyncFn.mockImplementation((path: string) => path === CONFIG_PATH);
+  readFileSyncFn.mockImplementation(() => JSON.stringify(config));
+}
+
+function getWrittenConfig(): Record<string, unknown> {
+  expect(writeFileSyncFn).toHaveBeenCalledTimes(1);
+  const [path, data] = writeFileSyncFn.mock.calls[0] as [string, string];
+  expect(path).toBe(CONFIG_PATH);
+  return JSON.parse(data) as Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("106-drop-collect-usage-data migration", () => {
+  beforeEach(() => {
+    existsSyncFn.mockClear();
+    readFileSyncFn.mockClear();
+    writeFileSyncFn.mockClear();
+  });
+
+  test("no-op when config.json is absent", () => {
+    existsSyncFn.mockImplementation(() => false);
+
+    dropCollectUsageDataMigration.run(WORKSPACE_DIR);
+
+    expect(readFileSyncFn).not.toHaveBeenCalled();
+    expect(writeFileSyncFn).not.toHaveBeenCalled();
+  });
+
+  test("explicit opt-out is preserved as legacyTelemetryOptOut", () => {
+    setupConfigExists({ collectUsageData: false, someSetting: "value" });
+
+    dropCollectUsageDataMigration.run(WORKSPACE_DIR);
+
+    const written = getWrittenConfig();
+    expect(written.collectUsageData).toBeUndefined();
+    expect(written.legacyTelemetryOptOut).toBe(true);
+    expect(written.someSetting).toBe("value");
+  });
+
+  test("collectUsageData: true is removed without setting the marker", () => {
+    setupConfigExists({ collectUsageData: true });
+
+    dropCollectUsageDataMigration.run(WORKSPACE_DIR);
+
+    const written = getWrittenConfig();
+    expect(written.collectUsageData).toBeUndefined();
+    expect(written.legacyTelemetryOptOut).toBeUndefined();
+  });
+
+  test("non-false value is removed without setting the marker", () => {
+    setupConfigExists({ collectUsageData: "yes" });
+
+    dropCollectUsageDataMigration.run(WORKSPACE_DIR);
+
+    const written = getWrittenConfig();
+    expect(written.collectUsageData).toBeUndefined();
+    expect(written.legacyTelemetryOptOut).toBeUndefined();
+  });
+
+  test("no-op when collectUsageData is absent (no marker)", () => {
+    setupConfigExists({ someSetting: "value" });
+
+    dropCollectUsageDataMigration.run(WORKSPACE_DIR);
+
+    expect(writeFileSyncFn).not.toHaveBeenCalled();
+  });
+
+  test("malformed config is handled gracefully", () => {
+    existsSyncFn.mockImplementation((path: string) => path === CONFIG_PATH);
+    readFileSyncFn.mockImplementation(() => "not valid json {{{");
+
+    dropCollectUsageDataMigration.run(WORKSPACE_DIR);
+
+    expect(writeFileSyncFn).not.toHaveBeenCalled();
+  });
+
+  test("no-op when config is an array", () => {
+    setupConfigExists([1, 2, 3]);
+
+    dropCollectUsageDataMigration.run(WORKSPACE_DIR);
+
+    expect(writeFileSyncFn).not.toHaveBeenCalled();
+  });
+});

package/src/__tests__/workspace-migration-drop-send-diagnostics.test.ts

@@ -0,0 +1,118 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+// ---------------------------------------------------------------------------
+// Mock state
+// ---------------------------------------------------------------------------
+
+const existsSyncFn = mock((_path: string): boolean => false);
+const readFileSyncFn = mock((_path: string, _encoding: string): string => "");
+const writeFileSyncFn = mock((_path: string, _data: string): void => undefined);
+
+// ---------------------------------------------------------------------------
+// Mock modules — before importing module under test
+// ---------------------------------------------------------------------------
+
+mock.module("node:fs", () => ({
+  existsSync: existsSyncFn,
+  readFileSync: readFileSyncFn,
+  writeFileSync: writeFileSyncFn,
+}));
+
+// Import after mocking
+import { dropSendDiagnosticsMigration } from "../workspace/migrations/107-drop-send-diagnostics.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const WORKSPACE_DIR = "/tmp/test-workspace";
+const CONFIG_PATH = `${WORKSPACE_DIR}/config.json`;
+
+function setupConfigExists(config: unknown) {
+  existsSyncFn.mockImplementation((path: string) => path === CONFIG_PATH);
+  readFileSyncFn.mockImplementation(() => JSON.stringify(config));
+}
+
+function getWrittenConfig(): Record<string, unknown> {
+  expect(writeFileSyncFn).toHaveBeenCalledTimes(1);
+  const [path, data] = writeFileSyncFn.mock.calls[0] as [string, string];
+  expect(path).toBe(CONFIG_PATH);
+  return JSON.parse(data) as Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("107-drop-send-diagnostics migration", () => {
+  beforeEach(() => {
+    existsSyncFn.mockClear();
+    readFileSyncFn.mockClear();
+    writeFileSyncFn.mockClear();
+  });
+
+  test("no-op when config.json is absent", () => {
+    existsSyncFn.mockImplementation(() => false);
+
+    dropSendDiagnosticsMigration.run(WORKSPACE_DIR);
+
+    expect(readFileSyncFn).not.toHaveBeenCalled();
+    expect(writeFileSyncFn).not.toHaveBeenCalled();
+  });
+
+  test("explicit opt-out is preserved as legacyDiagnosticsOptOut", () => {
+    setupConfigExists({ sendDiagnostics: false, someSetting: "value" });
+
+    dropSendDiagnosticsMigration.run(WORKSPACE_DIR);
+
+    const written = getWrittenConfig();
+    expect(written.sendDiagnostics).toBeUndefined();
+    expect(written.legacyDiagnosticsOptOut).toBe(true);
+    expect(written.someSetting).toBe("value");
+  });
+
+  test("sendDiagnostics: true is removed without setting the marker", () => {
+    setupConfigExists({ sendDiagnostics: true });
+
+    dropSendDiagnosticsMigration.run(WORKSPACE_DIR);
+
+    const written = getWrittenConfig();
+    expect(written.sendDiagnostics).toBeUndefined();
+    expect(written.legacyDiagnosticsOptOut).toBeUndefined();
+  });
+
+  test("non-false value is removed without setting the marker", () => {
+    setupConfigExists({ sendDiagnostics: "yes" });
+
+    dropSendDiagnosticsMigration.run(WORKSPACE_DIR);
+
+    const written = getWrittenConfig();
+    expect(written.sendDiagnostics).toBeUndefined();
+    expect(written.legacyDiagnosticsOptOut).toBeUndefined();
+  });
+
+  test("no-op when sendDiagnostics is absent (no marker)", () => {
+    setupConfigExists({ someSetting: "value" });
+
+    dropSendDiagnosticsMigration.run(WORKSPACE_DIR);
+
+    expect(writeFileSyncFn).not.toHaveBeenCalled();
+  });
+
+  test("malformed config is handled gracefully", () => {
+    existsSyncFn.mockImplementation((path: string) => path === CONFIG_PATH);
+    readFileSyncFn.mockImplementation(() => "not valid json {{{");
+
+    dropSendDiagnosticsMigration.run(WORKSPACE_DIR);
+
+    expect(writeFileSyncFn).not.toHaveBeenCalled();
+  });
+
+  test("no-op when config is an array", () => {
+    setupConfigExists([1, 2, 3]);
+
+    dropSendDiagnosticsMigration.run(WORKSPACE_DIR);
+
+    expect(writeFileSyncFn).not.toHaveBeenCalled();
+  });
+});

package/src/a2a/__tests__/e2e-a2a-channel.test.ts

@@ -164,7 +164,6 @@ describe("e2e: trusted contact setup", () => {
         {
           type: "a2a",
           address: "assistant-b",
-          externalUserId: "assistant-b",
           status: "active",
           policy: "allow",
         },
@@ -367,7 +366,6 @@ describe("e2e: unknown sender blocked (ACL enforcement)", () => {
         {
           type: "a2a",
           address: "trusted-assistant",
-          externalUserId: "trusted-assistant",
           status: "active",
           policy: "allow",
         },
@@ -403,7 +401,6 @@ describe("e2e: unknown sender blocked (ACL enforcement)", () => {
         {
           type: "a2a",
           address: "blocked-assistant",
-          externalUserId: "blocked-assistant",
           status: "blocked",
           policy: "deny",
         },
@@ -518,7 +515,6 @@ describe("e2e: full A2A round-trip", () => {
         {
           type: "a2a",
           address: "assistant-b",
-          externalUserId: "assistant-b",
           status: "active",
           policy: "allow",
         },

package/src/agent/loop.ts

@@ -1,10 +1,9 @@
 import * as Sentry from "@sentry/node";
 
-import { isAssistantFeatureFlagEnabled } from "../config/assistant-feature-flags.js";
 import { getConfig } from "../config/loader.js";
+import { isMemoryV3Live } from "../config/memory-v3-gate.js";
 import type { LLMCallSite } from "../config/schemas/llm.js";
 import { recordEstimate } from "../context/estimator-calibration.js";
-import { stripInjectionsForCompaction } from "../context/strip-injections.js";
 import {
   estimatePromptTokensRaw,
   estimatePromptTokensWithTools,
@@ -333,12 +332,14 @@ export type AgentEvent =
        * `stripInjectionsForCompaction`.
        *
        * The daemon's event dispatcher commits the stripped pre-compaction
-       * base as the conversation's durable message state, so re-injection
-       * (the post-compaction hook) re-applies injections onto the stripped
-       * base rather than stacking on top of the still-injected messages.
-       * When `compacted` is set it additionally commits the durable
-       * compaction result (DB-record fields, graph-memory side effects, SSE)
-       * and projects Slack provenance from the pre-compaction base.
+       * base as the conversation's durable message state. Re-injection (the
+       * post-compaction hook) strips runtime injections before re-applying
+       * them, so it is idempotent whether the loop continues from the
+       * stripped compaction result or from the unchanged injected history.
+       * When `compacted` is set the dispatcher additionally commits the
+       * durable compaction result (DB-record fields, graph-memory side
+       * effects, SSE) and projects Slack provenance from the pre-compaction
+       * base.
        *
        * Treated as a critical event: a failed durable commit re-throws so the
        * turn aborts rather than re-injecting against half-applied state.
@@ -358,13 +359,14 @@ export type AgentEvent =
     } & ContextWindowResult)
   | {
       /**
-       * Emitted right after the loop strips runtime injections from the
-       * running history, before the compaction pipeline runs. The daemon's
-       * event dispatcher records the history-stripped marker — a Conversation
-       * DB-record field read back at load time to strip embedded injection
-       * prefixes from pre-strip messages. Best-effort: a transient marker
-       * write must not abort the turn, so unlike `compaction_completed` this
-       * event is not treated as critical.
+       * Emitted during the loop's compaction ceremony, before the pipeline
+       * runs. The daemon's event dispatcher commits the stripped
+       * pre-compaction base as the durable history and records the
+       * history-stripped marker — a Conversation DB-record field read back at
+       * load time to strip embedded injection prefixes from pre-strip
+       * messages. Best-effort: a transient marker write must not abort the
+       * turn, so unlike `compaction_completed` this event is not treated as
+       * critical.
        */
       type: "history_stripped";
     }
@@ -761,9 +763,12 @@ export class AgentLoop {
   /**
    * Compact the running history in place when the budget gate trips.
    *
-   * Calls the default compaction plugin on the stripped history, then
-   * re-applies injections via the supplied hooks. When `overflowSignal` is
-   * supplied the plugin routes through the manager's reduction ladder (which
+   * Calls the default compaction plugin, then re-applies injections via the
+   * supplied hooks. Both the budget and overflow paths hand the full injected
+   * `history` to the plugin (so the summary call reuses the agent's warm prefix
+   * cache); the POST_COMPACT hook owns re-injection idempotency so continuing
+   * from injected history does not double-stack blocks. When `overflowSignal`
+   * is supplied the plugin routes through the manager's reduction ladder (which
    * advances one rung per call and reports `exhausted` / `autoCompressApplied`
    * / `injectionMode`); otherwise it runs ordinary forced compaction. Returns
    * the re-injected history to continue from alongside the ladder's terminal
@@ -795,11 +800,9 @@ export class AgentLoop {
       startedAt,
       messages: history,
     });
-    // Strip runtime injections so the compactor summarizes the raw persistent
-    // messages.
-    const rawHistory = stripInjectionsForCompaction(history);
-    // Record the history-stripped marker right after stripping, before the
-    // pipeline runs.
+    // The durable pre-compaction base is stripped by the event dispatcher
+    // (re-derived from the start event), so record the history-stripped
+    // marker for this compaction before the pipeline runs.
     await onEvent({ type: "history_stripped" });
     // The compaction module owns the per-conversation manager; pass the
     // conversation id and let `defaultCompact` resolve it from the store.
@@ -812,7 +815,7 @@ export class AgentLoop {
     // routes the request through the reduction ladder when present.
     const compactResult = await defaultCompact({
       conversationId: this.conversationId,
-      messages: rawHistory,
+      messages: history,
       signal,
       force: true,
       actorTrustClass: trust.trustClass,
@@ -848,15 +851,17 @@ export class AgentLoop {
     if (overflowSignal == null && exhausted) {
       return { history: null, exhausted, autoCompressApplied };
     }
-    // Re-inject onto the same base the `compaction_completed` dispatch commits.
-    // The overflow ladder transforms the history on every rung (truncation /
+    // The POST_COMPACT hook strips runtime injections from this base and
+    // re-applies them, so continuing from injected history is safe. The
+    // overflow ladder transforms the history on every rung (truncation /
     // media stubbing / injection downgrade) regardless of whether the summary
     // ran, so continue from its reduced messages; the ordinary path continues
-    // from the compacted messages only when the pipeline actually compacted.
+    // from the compacted messages when the pipeline compacted, otherwise from
+    // the unchanged injected history.
     const base =
       overflowSignal != null || compactResult.compacted
         ? compactResult.messages
-        : rawHistory;
+        : history;
     const postCompactCtx: PostCompactContext = {
       history: base,
       requestId,
@@ -1266,7 +1271,7 @@ export class AgentLoop {
         // volatile latest one. Read here alongside the rest of the provider
         // config; only set when true so the wire/config stays byte-identical
         // when off.
-        if (isAssistantFeatureFlagEnabled("memory-v3-live", getConfig())) {
+        if (isMemoryV3Live(getConfig())) {
           providerConfig.mutableLatestUserMessage = true;
         }
 
@@ -1434,6 +1439,7 @@ export class AgentLoop {
             conversationId: this.conversationId,
             callSite: callSite ?? null,
             systemPrompt: providerOptions.systemPrompt ?? null,
+            modelProfile: effectiveOverrideProfile ?? null,
             deferAssistantOutput: false,
             logger: rlog,
           };
@@ -1443,6 +1449,20 @@ export class AgentLoop {
           );
           providerOptions.systemPrompt =
             finalPreModelCtx.systemPrompt ?? undefined;
+          // Route this call to the hook's chosen inference profile. The
+          // resolver layers `llm.profiles[overrideProfile]` at the top of
+          // precedence for the user-facing call, so a model router can pick
+          // the profile per message; clearing it drops any seeded override.
+          const hookModelProfile = finalPreModelCtx.modelProfile?.trim();
+          if (hookModelProfile) {
+            providerConfig.overrideProfile = hookModelProfile;
+            if (forceOverrideProfile) {
+              providerConfig.forceOverrideProfile = true;
+            }
+          } else {
+            delete providerConfig.overrideProfile;
+            delete providerConfig.forceOverrideProfile;
+          }
           // The hook owns the policy (it sees `callSite`/conversation and
           // self-gates); the loop honors whatever it decides.
           deferAssistantOutput = finalPreModelCtx.deferAssistantOutput;

package/src/api/README.md

@@ -7,7 +7,7 @@ the wire contracts the assistant exposes: schemas, types, and pure helpers.
 Internal assistant code imports the files in this directory via relative paths
 (e.g. `../../api/events/open-url.js`). External consumers import the
 materialized npm-style package `@vellumai/assistant-api`, regenerated into
-`apps/web/node_modules/` by `apps/web/scripts/postinstall.ts`.
+`clients/web/node_modules/` by `clients/web/scripts/postinstall.ts`.
 
 ## Architecture
 
@@ -72,7 +72,7 @@ a migrated event is the import and the union membership.
 
 ### 3. Cut over web consumers
 
-`apps/web/src/domains/chat/api/event-types.ts` no longer needs to list the
+`clients/web/src/domains/chat/api/event-types.ts` no longer needs to list the
 migrated event in its `AssistantEvent` union — `APIAssistantEvent` covers it.
 Drop the per-event member, leaving the union to peel off legacy entries one
 at a time as each event migrates.
@@ -85,7 +85,7 @@ import them straight from the canonical package.
 ### 4. Delete the legacy parser cases
 
 Remove the matching `case "my_event":` blocks from
-`apps/web/src/domains/chat/api/event-parser.ts`. Any per-event helper
+`clients/web/src/domains/chat/api/event-parser.ts`. Any per-event helper
 (`parseFooBase`, etc.) goes with them.
 
 ### 5. Tests
@@ -110,15 +110,15 @@ Handler-level tests in the consuming domain modules typically need no change
 Run before push, in order:
 
 ```bash
-# In apps/web — regenerate the @vellumai/assistant-api bundle
+# In clients/web — regenerate the @vellumai/assistant-api bundle
 bun run scripts/postinstall.ts
 
 # Type-check both packages
 ( cd assistant && bunx tsc --noEmit )
-( cd apps/web && bunx tsc --noEmit )
+( cd clients/web && bunx tsc --noEmit )
 
 # Targeted tests
-( cd apps/web && bun test src/domains/chat/api/event-parser.test.ts )
+( cd clients/web && bun test src/domains/chat/api/event-parser.test.ts )
 
 # Lint + format the touched files
 bunx eslint <files>

package/src/api/events/tool-result.ts

@@ -47,10 +47,15 @@ export const WebSearchProviderIdSchema = z.enum([
   "brave",
   "perplexity",
   "tavily",
+  "firecrawl",
 ]);
 
 export type WebSearchProviderId = z.infer<typeof WebSearchProviderIdSchema>;
 
+export const WebFetchProviderIdSchema = z.enum(["default", "firecrawl"]);
+
+export type WebFetchProviderId = z.infer<typeof WebFetchProviderIdSchema>;
+
 export const WebSearchResultItemSchema = z.object({
   rank: z.number(),
   title: z.string(),
@@ -78,6 +83,7 @@ export type WebSearchMetadata = z.infer<typeof WebSearchMetadataSchema>;
 export const WebFetchMetadataSchema = z.object({
   url: z.string(),
   finalUrl: z.string(),
+  provider: WebFetchProviderIdSchema.optional(),
   status: z.number(),
   contentType: z.string().optional(),
   byteCount: z.number(),

package/src/api/events/workflow-completed.ts

@@ -0,0 +1,53 @@
+/**
+ * `workflow_completed` SSE event.
+ *
+ * Server → client notification that a `run_workflow` run has reached a
+ * terminal state. Carries `runId`, the terminal `status`, cumulative
+ * `agentsSpawned`/`inputTokens`/`outputTokens` counters, and an optional
+ * human-readable `summary`.
+ *
+ * `conversationId` is present for a run launched from a conversation, so
+ * clients can route the event to that conversation's inline workflow card. It
+ * is omitted for a conversationless run (e.g. a scheduled workflow with no
+ * wake/origin conversation), which broadcasts unscoped for raw SSE listeners.
+ *
+ * Canonical wire-contract source. Daemon code imports the type
+ * directly from this file; external consumers import via
+ * `@vellumai/assistant-api`.
+ */
+
+import { z } from "zod";
+
+/**
+ * Lifecycle status of a `run_workflow` run. `running` is the live
+ * state; the remainder are terminal. `cap_exceeded` is reached when a
+ * run hits its configured agent/token cap; `interrupted` when the run
+ * is halted by an external signal.
+ */
+export const WorkflowRunStatusSchema = z.enum([
+  "running",
+  "completed",
+  "failed",
+  "aborted",
+  "cap_exceeded",
+  "interrupted",
+]);
+
+export type WorkflowRunStatus = z.infer<typeof WorkflowRunStatusSchema>;
+
+export const WorkflowCompletedEventSchema = z
+  .object({
+    type: z.literal("workflow_completed"),
+    runId: z.string(),
+    conversationId: z.string().optional(),
+    status: WorkflowRunStatusSchema,
+    agentsSpawned: z.number(),
+    inputTokens: z.number(),
+    outputTokens: z.number(),
+    summary: z.string().optional(),
+  })
+  .strict();
+
+export type WorkflowCompletedEvent = z.infer<
+  typeof WorkflowCompletedEventSchema
+>;

package/src/api/events/workflow-leaf-finished.ts

@@ -0,0 +1,38 @@
+/**
+ * `workflow_leaf_finished` SSE event.
+ *
+ * Server → client notification that a leaf agent within a
+ * `run_workflow` run has finished. Carries `runId`, the parent
+ * `conversationId`, the monotonic `seq` identifying the leaf within the
+ * run, the terminal `status`, optional `inputTokens`/`outputTokens`
+ * counters, and optional human-readable display fields (`label`,
+ * `resultSummary`).
+ *
+ * `conversationId` is present so clients can route the event to the
+ * originating conversation's inline workflow card and its live leaf
+ * tree.
+ *
+ * Canonical wire-contract source. Daemon code imports the type
+ * directly from this file; external consumers import via
+ * `@vellumai/assistant-api`.
+ */
+
+import { z } from "zod";
+
+export const WorkflowLeafFinishedEventSchema = z
+  .object({
+    type: z.literal("workflow_leaf_finished"),
+    runId: z.string(),
+    conversationId: z.string(),
+    seq: z.number().int(),
+    status: z.enum(["completed", "failed"]),
+    label: z.string().optional(),
+    inputTokens: z.number().optional(),
+    outputTokens: z.number().optional(),
+    resultSummary: z.string().optional(),
+  })
+  .strict();
+
+export type WorkflowLeafFinishedEvent = z.infer<
+  typeof WorkflowLeafFinishedEventSchema
+>;

package/src/api/events/workflow-leaf-started.ts

@@ -0,0 +1,35 @@
+/**
+ * `workflow_leaf_started` SSE event.
+ *
+ * Server → client notification that a leaf agent within a
+ * `run_workflow` run has started. Carries `runId`, the parent
+ * `conversationId`, the monotonic `seq` identifying the leaf within the
+ * run, and optional human-readable display fields (`label`, `phase`,
+ * `promptSummary`).
+ *
+ * `conversationId` is present so clients can route the event to the
+ * originating conversation's inline workflow card and its live leaf
+ * tree.
+ *
+ * Canonical wire-contract source. Daemon code imports the type
+ * directly from this file; external consumers import via
+ * `@vellumai/assistant-api`.
+ */
+
+import { z } from "zod";
+
+export const WorkflowLeafStartedEventSchema = z
+  .object({
+    type: z.literal("workflow_leaf_started"),
+    runId: z.string(),
+    conversationId: z.string(),
+    seq: z.number().int(),
+    label: z.string().optional(),
+    phase: z.string().optional(),
+    promptSummary: z.string().optional(),
+  })
+  .strict();
+
+export type WorkflowLeafStartedEvent = z.infer<
+  typeof WorkflowLeafStartedEventSchema
+>;

package/src/api/events/workflow-progress.ts

@@ -0,0 +1,32 @@
+/**
+ * `workflow_progress` SSE event.
+ *
+ * Server → client incremental progress update for an in-flight
+ * `run_workflow` run. Carries `runId`, the running `agentsSpawned` count,
+ * and optional human-readable display fields (`phase`, `label`, `message`).
+ *
+ * `conversationId` is present for a run launched from a conversation, so
+ * clients can route the event to that conversation's inline workflow card. It
+ * is omitted for a conversationless run (e.g. a scheduled workflow with no
+ * wake/origin conversation), which broadcasts unscoped for raw SSE listeners.
+ *
+ * Canonical wire-contract source. Daemon code imports the type
+ * directly from this file; external consumers import via
+ * `@vellumai/assistant-api`.
+ */
+
+import { z } from "zod";
+
+export const WorkflowProgressEventSchema = z
+  .object({
+    type: z.literal("workflow_progress"),
+    runId: z.string(),
+    conversationId: z.string().optional(),
+    agentsSpawned: z.number(),
+    phase: z.string().optional(),
+    label: z.string().optional(),
+    message: z.string().optional(),
+  })
+  .strict();
+
+export type WorkflowProgressEvent = z.infer<typeof WorkflowProgressEventSchema>;