@vellumai/assistant 0.9.0-dev.202606181513.fd39213 → 0.9.0-dev.202606181735.ae6e1d8

package/openapi.yaml

@@ -27773,6 +27773,88 @@ paths:
                 additionalProperties: false
         "404":
           description: Run not found
+  /v1/workflows/runs/{id}/journal:
+    get:
+      operationId: workflows_runs_by_id_journal_get
+      summary: Get workflow run journal
+      description: Return a workflow run's leaf journal as bounded per-leaf summaries (one entry per finished leaf).
+      tags:
+        - workflows
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  runId:
+                    type: string
+                  status:
+                    type: string
+                    enum:
+                      - running
+                      - completed
+                      - failed
+                      - aborted
+                      - cap_exceeded
+                      - interrupted
+                  agentsSpawned:
+                    type: number
+                  inputTokens:
+                    type: number
+                  outputTokens:
+                    type: number
+                  phase:
+                    type: string
+                  leaves:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        seq:
+                          type: number
+                        kind:
+                          type: string
+                          enum:
+                            - agent
+                            - workflow
+                        label:
+                          type: string
+                        phase:
+                          type: string
+                        promptSummary:
+                          type: string
+                        status:
+                          type: string
+                        resultSummary:
+                          type: string
+                        inputTokens:
+                          type: number
+                        outputTokens:
+                          type: number
+                        createdAt:
+                          anyOf:
+                            - type: number
+                            - type: "null"
+                      required:
+                        - seq
+                        - kind
+                        - status
+                        - createdAt
+                      additionalProperties: false
+                required:
+                  - runId
+                  - leaves
+                additionalProperties: false
+        "404":
+          description: Run not found
   /v1/workflows/runs/{id}/resume:
     post:
       operationId: workflows_runs_by_id_resume_post

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.9.0-dev.202606181513.fd39213",
+  "version": "0.9.0-dev.202606181735.ae6e1d8",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/plugin-tool-contribution.test.ts

@@ -190,13 +190,16 @@ describe("plugin tool contributions", () => {
     registerPlugin(plugin);
 
     await bootstrapPlugins();
-    // No tool should have been registered.
-    expect(getAllTools()).toHaveLength(0);
+    // `bootstrapPlugins` also registers the first-party defaults (the advisor
+    // default contributes the `advisor` tool), so the global tool set is not
+    // empty. What matters here is that the no-tools plugin contributed nothing
+    // of its own — its tool refcount stays at zero.
+    expect(getPluginRefCount("no-tools")).toBe(0);
 
     // Shutdown must also be safe — `unregisterPluginTools` is idempotent for
     // plugins that never contributed any tools.
     await runShutdownHooks("test-shutdown");
-    expect(getAllTools()).toHaveLength(0);
+    expect(getPluginRefCount("no-tools")).toBe(0);
   });
 
   test("tools declared before init() runs are only visible after bootstrap", async () => {

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>;

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

@@ -0,0 +1,31 @@
+/**
+ * `workflow_started` SSE event.
+ *
+ * Server → client notification that a `run_workflow` run has begun.
+ * Carries `runId`, the parent `conversationId`, an optional anchoring
+ * `toolUseId`, and an optional human-readable `label`.
+ *
+ * `conversationId` is present so clients can route the event to the
+ * originating conversation's inline workflow card. `toolUseId` (the
+ * `skill_execute` block id that launched the run) anchors that inline
+ * card to the exact spawn tool call, mirroring
+ * `subagent_spawned.parentToolUseId`.
+ *
+ * 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 WorkflowStartedEventSchema = z
+  .object({
+    type: z.literal("workflow_started"),
+    runId: z.string(),
+    conversationId: z.string(),
+    toolUseId: z.string().optional(),
+    label: z.string().optional(),
+  })
+  .strict();
+
+export type WorkflowStartedEvent = z.infer<typeof WorkflowStartedEventSchema>;

package/src/api/index.ts

@@ -52,6 +52,11 @@ import { UISurfaceUpdateEventSchema } from "./events/ui-surface-update.js";
 import { UsageProgressEventSchema } from "./events/usage-progress.js";
 import { UsageUpdateEventSchema } from "./events/usage-update.js";
 import { UserMessageEchoEventSchema } from "./events/user-message-echo.js";
+import { WorkflowCompletedEventSchema } from "./events/workflow-completed.js";
+import { WorkflowLeafFinishedEventSchema } from "./events/workflow-leaf-finished.js";
+import { WorkflowLeafStartedEventSchema } from "./events/workflow-leaf-started.js";
+import { WorkflowProgressEventSchema } from "./events/workflow-progress.js";
+import { WorkflowStartedEventSchema } from "./events/workflow-started.js";
 
 export {
   CALL_SITE_COMPACTION_AGENT,
@@ -326,6 +331,28 @@ export {
   type UserMessageEchoEvent,
   UserMessageEchoEventSchema,
 } from "./events/user-message-echo.js";
+export {
+  type WorkflowCompletedEvent,
+  WorkflowCompletedEventSchema,
+  type WorkflowRunStatus,
+  WorkflowRunStatusSchema,
+} from "./events/workflow-completed.js";
+export {
+  type WorkflowLeafFinishedEvent,
+  WorkflowLeafFinishedEventSchema,
+} from "./events/workflow-leaf-finished.js";
+export {
+  type WorkflowLeafStartedEvent,
+  WorkflowLeafStartedEventSchema,
+} from "./events/workflow-leaf-started.js";
+export {
+  type WorkflowProgressEvent,
+  WorkflowProgressEventSchema,
+} from "./events/workflow-progress.js";
+export {
+  type WorkflowStartedEvent,
+  WorkflowStartedEventSchema,
+} from "./events/workflow-started.js";
 export {
   type DictationContext,
   DictationContextSchema,
@@ -443,6 +470,12 @@ export {
   type SubagentDetailResponse,
   SubagentDetailResponseSchema,
 } from "./responses/subagent-detail.js";
+export {
+  type WorkflowJournalResponse,
+  WorkflowJournalResponseSchema,
+  type WorkflowLeaf,
+  WorkflowLeafSchema,
+} from "./responses/workflow-journal.js";
 
 /**
  * Canonical SSE event schema for the assistant runtime.
@@ -510,6 +543,11 @@ export const AssistantEventSchema = z.discriminatedUnion("type", [
   UsageProgressEventSchema,
   UsageUpdateEventSchema,
   UserMessageEchoEventSchema,
+  WorkflowCompletedEventSchema,
+  WorkflowLeafFinishedEventSchema,
+  WorkflowLeafStartedEventSchema,
+  WorkflowProgressEventSchema,
+  WorkflowStartedEventSchema,
 ]);
 
 /**

package/src/api/responses/workflow-journal.ts

@@ -0,0 +1,53 @@
+/**
+ * Wire contract for the workflow-journal REST endpoint. Returns a
+ * `run_workflow` run's live status, cumulative usage/agent counters,
+ * current phase, and the ordered list of leaf agents spawned by the
+ * run.
+ *
+ * Reuses the canonical `WorkflowRunStatusSchema` defined alongside the
+ * `workflow_completed` SSE event so the polled REST journal and the
+ * streamed lifecycle events share one status shape.
+ *
+ * Canonical wire-contract source. Assistant code imports the types
+ * directly from this file via relative paths; external consumers
+ * (web client, gateway, evals) import via `@vellumai/assistant-api`.
+ */
+
+import { z } from "zod";
+
+import { WorkflowRunStatusSchema } from "../events/workflow-completed.js";
+
+/**
+ * A single leaf within a workflow run. `kind` distinguishes a leaf
+ * agent from a nested workflow; `status` is an open string rather than
+ * a closed enum since it covers both lifecycle states and terminal
+ * results.
+ */
+export const WorkflowLeafSchema = z.object({
+  seq: z.number().int(),
+  kind: z.enum(["agent", "workflow"]),
+  label: z.string().optional(),
+  phase: z.string().optional(),
+  promptSummary: z.string().optional(),
+  status: z.string(),
+  resultSummary: z.string().optional(),
+  inputTokens: z.number().optional(),
+  outputTokens: z.number().optional(),
+  createdAt: z.number().nullable(),
+});
+
+export type WorkflowLeaf = z.infer<typeof WorkflowLeafSchema>;
+
+export const WorkflowJournalResponseSchema = z.object({
+  runId: z.string(),
+  status: WorkflowRunStatusSchema.optional(),
+  agentsSpawned: z.number().optional(),
+  inputTokens: z.number().optional(),
+  outputTokens: z.number().optional(),
+  phase: z.string().optional(),
+  leaves: z.array(WorkflowLeafSchema),
+});
+
+export type WorkflowJournalResponse = z.infer<
+  typeof WorkflowJournalResponseSchema
+>;

package/src/daemon/message-types/workflows.ts

@@ -18,6 +18,13 @@ import type { WorkflowRunStatus } from "../../workflows/journal-store.js";
 export interface WorkflowProgress {
   type: "workflow_progress";
   runId: string;
+  /**
+   * Originating conversation id, when launched from one; lets `broadcastMessage`
+   * auto-scope + seq-stamp the event to that conversation's SSE stream. Omitted
+   * for a conversationless run (e.g. a scheduled workflow), which broadcasts
+   * unscoped for raw SSE listeners and the DB record.
+   */
+  conversationId?: string;
   /** Latest phase title, when this emission came from a `phase(...)` call. */
   phase?: string;
   /** Run label (the workflow's `meta.name`), for client display. */
@@ -36,6 +43,13 @@ export interface WorkflowProgress {
 export interface WorkflowCompleted {
   type: "workflow_completed";
   runId: string;
+  /**
+   * Originating conversation id, when launched from one; lets `broadcastMessage`
+   * auto-scope + seq-stamp the event to that conversation's SSE stream. Omitted
+   * for a conversationless run (e.g. a scheduled workflow), which broadcasts
+   * unscoped for raw SSE listeners and the DB record.
+   */
+  conversationId?: string;
   status: WorkflowRunStatus;
   agentsSpawned: number;
   inputTokens: number;
@@ -44,6 +58,74 @@ export interface WorkflowCompleted {
   summary?: string;
 }
 
+/**
+ * A workflow run has started. Emitted once at launch, before any leaf events.
+ */
+export interface WorkflowStarted {
+  type: "workflow_started";
+  runId: string;
+  /**
+   * Originating conversation id; lets `broadcastMessage` auto-scope +
+   * seq-stamp the event to the conversation's SSE stream.
+   */
+  conversationId: string;
+  /**
+   * Tool-use id of the `skill_execute` block that launched this run, for
+   * anchoring the inline workflow card to the exact spawn tool call.
+   */
+  toolUseId?: string;
+  /** Run label (the workflow's `meta.name`), for client display. */
+  label?: string;
+}
+
+/**
+ * A leaf agent within a workflow run has started. `seq` orders leaves within
+ * the run for stable client-side tree placement.
+ */
+export interface WorkflowLeafStarted {
+  type: "workflow_leaf_started";
+  runId: string;
+  /**
+   * Originating conversation id; lets `broadcastMessage` auto-scope +
+   * seq-stamp the event to the conversation's SSE stream.
+   */
+  conversationId: string;
+  seq: number;
+  /** Leaf label, for client display. */
+  label?: string;
+  /** Phase the leaf belongs to, when the workflow declares phases. */
+  phase?: string;
+  /** Short summary of the leaf's prompt, for client display. */
+  promptSummary?: string;
+}
+
+/**
+ * A leaf agent within a workflow run has finished. `seq` matches the
+ * corresponding `workflow_leaf_started` event.
+ */
+export interface WorkflowLeafFinished {
+  type: "workflow_leaf_finished";
+  runId: string;
+  /**
+   * Originating conversation id; lets `broadcastMessage` auto-scope +
+   * seq-stamp the event to the conversation's SSE stream.
+   */
+  conversationId: string;
+  seq: number;
+  status: "completed" | "failed";
+  /** Leaf label, for client display. */
+  label?: string;
+  inputTokens?: number;
+  outputTokens?: number;
+  /** Short summary of the leaf's result, for client display. */
+  resultSummary?: string;
+}
+
 // --- Domain-level union aliases (consumed by the barrel file) ---
 
-export type _WorkflowsServerMessages = WorkflowProgress | WorkflowCompleted;
+export type _WorkflowsServerMessages =
+  | WorkflowProgress
+  | WorkflowCompleted
+  | WorkflowStarted
+  | WorkflowLeafStarted
+  | WorkflowLeafFinished;

package/src/memory/db-init.ts

@@ -224,6 +224,7 @@ import {
   migrateUsageLlmCallCount,
   migrateVoiceInviteColumns,
   migrateVoiceInviteDisplayMetadata,
+  migrateWorkflowJournalLeafTokens,
   migrateWorkflowRuns,
   migrateWorkflowRunTrust,
   recoverCrashedMigrations,
@@ -523,6 +524,7 @@ export function initializeDb(): void {
     migrateScheduleCapabilities,
     migrateContactChannelsRenormalizeAddresses,
     migrateScheduleDefaultNoReuseConversation,
+    migrateWorkflowJournalLeafTokens,
   ];
 
   // Run each migration step, catching and logging individual failures so one

package/src/memory/migrations/293-workflow-journal-leaf-tokens.ts

@@ -0,0 +1,32 @@
+import type { DrizzleDb } from "../db-connection.js";
+import { getSqliteFrom } from "../db-connection.js";
+
+/**
+ * Add nullable `input_tokens` / `output_tokens` columns to `workflow_journal`.
+ *
+ * Persists per-leaf token usage so the journal route can attribute usage to each
+ * leaf. The client then computes run-level token metrics from the per-leaf sum
+ * (a single source of truth), counting each leaf exactly once regardless of
+ * whether its usage arrives via a live `leaf_finished` event or a journal
+ * backfill — which avoids the undercount that arose when a mid-run journal
+ * aggregate counted a leaf the journal could not itself attribute.
+ *
+ * Nullable — legacy rows and non-completed leaves (failures, nested
+ * `workflow`-kind entries) stay NULL and contribute zero to the sum.
+ *
+ * Idempotent — each ALTER is wrapped so a re-run (column already present) is a
+ * no-op.
+ */
+export function migrateWorkflowJournalLeafTokens(database: DrizzleDb): void {
+  const raw = getSqliteFrom(database);
+  try {
+    raw.exec(`ALTER TABLE workflow_journal ADD COLUMN input_tokens INTEGER`);
+  } catch {
+    /* Column already exists */
+  }
+  try {
+    raw.exec(`ALTER TABLE workflow_journal ADD COLUMN output_tokens INTEGER`);
+  } catch {
+    /* Column already exists */
+  }
+}

package/src/memory/migrations/index.ts

@@ -284,6 +284,7 @@ export { migrateContactChannelsUniqueExtUser } from "./289-contact-channels-uniq
 export { migrateScheduleCapabilities } from "./290-schedule-capabilities.js";
 export { migrateContactChannelsRenormalizeAddresses } from "./291-contact-channels-renormalize-addresses.js";
 export { migrateScheduleDefaultNoReuseConversation } from "./292-schedule-default-no-reuse-conversation.js";
+export { migrateWorkflowJournalLeafTokens } from "./293-workflow-journal-leaf-tokens.js";
 export {
   MIGRATION_REGISTRY,
   type MigrationRegistryEntry,

package/src/plugins/defaults/advisor/__tests__/advisor-state-store.test.ts

@@ -0,0 +1,43 @@
+import { afterEach, describe, expect, test } from "bun:test";
+
+import type { Message } from "../../../../providers/types.js";
+import {
+  getCapture,
+  recordMessages,
+  recordSystemPrompt,
+  resetAdvisorStateForTests,
+  seedCapture,
+} from "../advisor-state-store.js";
+
+const userMsg = (t: string): Message => ({
+  role: "user",
+  content: [{ type: "text", text: t }],
+});
+
+afterEach(() => {
+  resetAdvisorStateForTests();
+});
+
+describe("advisor state store", () => {
+  test("records system prompt and messages independently per conversation", () => {
+    recordSystemPrompt("c1", "system A");
+    recordMessages("c1", [userMsg("hello")]);
+    recordSystemPrompt("c2", "system B");
+
+    expect(getCapture("c1")?.systemPrompt).toBe("system A");
+    expect(getCapture("c1")?.messages).toEqual([userMsg("hello")]);
+    expect(getCapture("c2")?.systemPrompt).toBe("system B");
+    expect(getCapture("c2")?.messages).toEqual([]);
+  });
+
+  test("seedCapture snapshots (copies) the array", () => {
+    const live: Message[] = [userMsg("one")];
+    seedCapture("c1", live);
+    live.push(userMsg("two"));
+    expect(getCapture("c1")?.messages).toEqual([userMsg("one")]);
+  });
+
+  test("getCapture returns undefined for an unseen conversation", () => {
+    expect(getCapture("nope")).toBeUndefined();
+  });
+});