@vellumai/assistant 0.9.0 → 0.10.0-staging.2

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,
@@ -385,6 +412,8 @@ export {
   FeedItemDetailPanelKindSchema,
   FeedItemDetailPanelSchema,
   FeedItemSchema,
+  type FeedItemSourceType,
+  FeedItemSourceTypeSchema,
   type FeedItemStatus,
   FeedItemStatusSchema,
   type FeedItemType,
@@ -441,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.
@@ -508,6 +543,11 @@ export const AssistantEventSchema = z.discriminatedUnion("type", [
   UsageProgressEventSchema,
   UsageUpdateEventSchema,
   UserMessageEchoEventSchema,
+  WorkflowCompletedEventSchema,
+  WorkflowLeafFinishedEventSchema,
+  WorkflowLeafStartedEventSchema,
+  WorkflowProgressEventSchema,
+  WorkflowStartedEventSchema,
 ]);
 
 /**

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

@@ -30,6 +30,7 @@ import {
   DirectoryScopeOptionSchema,
   ScopeOptionSchema,
 } from "../events/confirmation-request.js";
+import { QuestionEntrySchema } from "../events/question-request.js";
 import { ToolActivityMetadataSchema } from "../events/tool-result.js";
 
 // ---------------------------------------------------------------------------
@@ -104,6 +105,25 @@ export type PendingToolConfirmation = z.infer<
   typeof PendingToolConfirmationSchema
 >;
 
+/**
+ * In-flight `ask_question` prompt awaiting a user answer, mirrored onto the
+ * history tool call that raised it so a cold reconnect (or a conversation
+ * reopened after the event-buffer window has elapsed) can restore the inline
+ * question card without replaying the live `question_request` SSE event.
+ *
+ * Stamped at render time from the in-memory `pending-interactions` registry
+ * (the authoritative store of unresolved prompts) — not persisted to the
+ * database, so it appears only while the prompt is genuinely outstanding and
+ * disappears once the interaction resolves. `entries` mirrors the
+ * `question_request` event's `questions[]`, so both paths hydrate the same
+ * client state.
+ */
+export const PendingToolQuestionSchema = z.object({
+  requestId: z.string(),
+  entries: z.array(QuestionEntrySchema),
+});
+export type PendingToolQuestion = z.infer<typeof PendingToolQuestionSchema>;
+
 /**
  * Closed set of confirmation outcomes recorded for a tool call. The daemon
  * only ever persists one of these three values (the outcome map is gated to
@@ -190,6 +210,12 @@ export const ConversationMessageToolCallSchema = z.object({
    * Guaranteed present for outstanding prompts as of daemon v0.8.8.
    */
   pendingConfirmation: PendingToolConfirmationSchema.optional(),
+  /**
+   * In-flight `ask_question` prompt, present only while the tool call is
+   * awaiting a user answer (read from the `pending-interactions` registry at
+   * render time). Lets a cold reconnect restore the inline question card.
+   */
+  pendingQuestion: PendingToolQuestionSchema.optional(),
 });
 export type ConversationMessageToolCall = z.infer<
   typeof ConversationMessageToolCallSchema
@@ -390,10 +416,8 @@ export const ConversationMessageSchema = z.object({
   /**
    * @deprecated Superseded by `contentBlocks`. Flat plain-text body (joined
    * text segments). Redundant with `textSegments`/`contentOrder` for clients
-   * that render from the positional arrays (web, CLI), but the legacy Swift
-   * macOS client reads `content` directly and drops any history row missing it
-   * (its `HistoryReconstructionService` skips rows with empty text). The
-   * serializer always emits it — do not remove without updating that client.
+   * that render from the positional arrays (web, CLI). The serializer always
+   * emits it — do not remove without auditing clients that read it directly.
    */
   content: z
     .string()

package/src/api/responses/home.ts

@@ -12,10 +12,6 @@
  * generator, and the web/CLI clients all derive from one source and cannot
  * drift.
  *
- * A structurally compatible Swift mirror lives at
- * `clients/shared/Network/FeedItem.swift`. Any change to the feed-item
- * shape must be mirrored there.
- *
  * 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`.
@@ -59,6 +55,25 @@ export const FeedItemCategorySchema = z.enum([
 ]);
 export type FeedItemCategory = z.infer<typeof FeedItemCategorySchema>;
 
+/**
+ * Producer of a feed item's source conversation — lets clients filter the
+ * activity feed by what generated each notification: the periodic
+ * heartbeat, a memory-consolidation pass, a recurring schedule, an
+ * auto-analysis run, etc. Derived at read time from the source
+ * conversation's `source` column (see `home/feed-source-enrichment.ts`).
+ * Individual schedules are distinguished by `sourceKey`/`sourceLabel`, not
+ * this coarse type.
+ */
+export const FeedItemSourceTypeSchema = z.enum([
+  "heartbeat",
+  "memory_consolidation",
+  "schedule",
+  "auto_analysis",
+  "user",
+  "other",
+]);
+export type FeedItemSourceType = z.infer<typeof FeedItemSourceTypeSchema>;
+
 /**
  * A single action button attached to a feed item.
  *
@@ -124,6 +139,13 @@ export const FeedItemSchema = z.object({
   noteworthy: z.boolean().optional(),
   fromAssistant: z.boolean().optional(),
   metadata: z.record(z.string(), z.unknown()).optional(),
+  // Source-conversation classification, enriched at read time. `sourceKey`
+  // is the stable filter id — `schedule:<id>` for schedules so each filters
+  // separately, otherwise the `sourceType`. `sourceLabel` is the display
+  // string (a schedule's name, or a static label like "Heartbeat").
+  sourceType: FeedItemSourceTypeSchema.optional(),
+  sourceKey: z.string().optional(),
+  sourceLabel: z.string().optional(),
   createdAt: z.string(),
 });
 export type FeedItem = z.infer<typeof FeedItemSchema>;

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/approvals/guardian-card-withdrawal.ts

@@ -0,0 +1,145 @@
+/**
+ * Cross-surface withdrawal of guardian approval cards.
+ *
+ * A single guardian request is projected onto every surface it was delivered
+ * to — the in-app Vellum card, a Slack message, etc. When the request reaches a
+ * terminal status its cards must stop offering live actions on *all* surfaces,
+ * not just the one the guardian acted on. This is the withdrawal counterpart to
+ * the unified card *rendering* dispatcher (`notifications/approval-card-data.ts`):
+ * rendering projects `pending` onto each surface, withdrawal projects the
+ * terminal status back onto each surface.
+ *
+ * Withdrawal preserves the card's information and removes only the live
+ * affordances (it does not delete the message/card) so each surface keeps an
+ * audit trail of what was decided.
+ *
+ * It is driven off `canonical_guardian_deliveries` — the per-request registry of
+ * where each card was sent — so it stays correct as surfaces are added and is
+ * agnostic to which surface originated the decision.
+ *
+ * Best-effort by contract: the request is already resolved (CAS committed)
+ * before this runs, so a failed edit must never surface as a decision failure.
+ * Every surface is attempted independently; one failure never blocks the rest.
+ */
+
+import { completeSurfaceAndNotify } from "../daemon/conversation-surfaces.js";
+import {
+  type CanonicalGuardianDelivery,
+  type CanonicalGuardianRequest,
+  type CanonicalRequestStatus,
+  listCanonicalGuardianDeliveries,
+} from "../memory/canonical-guardian-store.js";
+import { withdrawSlackApprovalCard } from "../messaging/providers/slack/withdraw.js";
+import { approvalCardSurfaceId } from "../notifications/approval-card-data.js";
+import { getLogger } from "../util/logger.js";
+
+const log = getLogger("guardian-card-withdrawal");
+
+/** Completion-summary label shown on an in-app card for a resolved request. */
+const SURFACE_STATUS_LABELS: Partial<Record<CanonicalRequestStatus, string>> = {
+  approved: "Approved",
+  denied: "Denied",
+  expired: "Expired",
+  cancelled: "Cancelled",
+};
+
+export interface WithdrawGuardianCardsParams {
+  /** The request, already transitioned to its terminal status. */
+  request: CanonicalGuardianRequest;
+  /** Terminal status to reflect on each card. */
+  status: CanonicalRequestStatus;
+  /**
+   * Channel the decision originated on, when applicable.
+   *
+   * The acting in-app client completes its own card optimistically, so the
+   * in-app card is skipped when the decision originated in-app; it is withdrawn
+   * here only when the decision came from another surface. Omit (e.g. the expiry
+   * sweep) to withdraw every surface.
+   */
+  originChannel?: string;
+}
+
+/**
+ * Withdraw a resolved request's approval cards across all delivery surfaces.
+ * Never throws.
+ */
+export async function withdrawGuardianRequestCards(
+  params: WithdrawGuardianCardsParams,
+): Promise<void> {
+  const { request, status, originChannel } = params;
+
+  let deliveries: CanonicalGuardianDelivery[];
+  try {
+    deliveries = listCanonicalGuardianDeliveries(request.id);
+  } catch (err) {
+    log.warn(
+      { err, requestId: request.id },
+      "Failed to list deliveries for card withdrawal",
+    );
+    return;
+  }
+
+  for (const delivery of deliveries) {
+    try {
+      if (delivery.destinationChannel === "vellum") {
+        withdrawVellumCard(request, delivery, status, originChannel);
+      } else if (delivery.destinationChannel === "slack") {
+        await withdrawSlackCard(request, delivery, status);
+      }
+      // Telegram/WhatsApp direct delivery can't edit a message in place (it
+      // would post a new one), so their stale clicks are left to the existing
+      // "already resolved" reply until in-place edit support lands.
+    } catch (err) {
+      log.warn(
+        {
+          err,
+          requestId: request.id,
+          channel: delivery.destinationChannel,
+        },
+        "Failed to withdraw guardian card on surface (non-fatal)",
+      );
+    }
+  }
+}
+
+/**
+ * Withdraw the in-app approval card so it stops offering live actions while
+ * keeping its content. Skipped when the decision originated in-app — the acting
+ * client already completed the card itself.
+ */
+function withdrawVellumCard(
+  request: CanonicalGuardianRequest,
+  delivery: CanonicalGuardianDelivery,
+  status: CanonicalRequestStatus,
+  originChannel: string | undefined,
+): void {
+  if (originChannel === "vellum") return;
+  if (!delivery.destinationConversationId) return;
+  const surfaceId = approvalCardSurfaceId(request.kind, request.id);
+  if (!surfaceId) return;
+  completeSurfaceAndNotify(
+    delivery.destinationConversationId,
+    surfaceId,
+    SURFACE_STATUS_LABELS[status] ?? "Resolved",
+  );
+}
+
+/**
+ * Edit the Slack message in place to its resolved state — original card content
+ * preserved, action buttons removed, an outcome/decider/time line appended.
+ * No-ops when the channel-native message id was not captured at delivery time.
+ */
+async function withdrawSlackCard(
+  request: CanonicalGuardianRequest,
+  delivery: CanonicalGuardianDelivery,
+  status: CanonicalRequestStatus,
+): Promise<void> {
+  if (!delivery.destinationChatId || !delivery.destinationMessageId) return;
+  await withdrawSlackApprovalCard({
+    channel: delivery.destinationChatId,
+    messageTs: delivery.destinationMessageId,
+    status,
+    decidedByExternalUserId: request.decidedByExternalUserId ?? undefined,
+    decidedAtMs: request.updatedAt,
+  });
+}

package/src/approvals/guardian-decision-primitive.ts

@@ -48,6 +48,7 @@ import type { ApplyGuardianDecisionResult } from "../runtime/guardian-decision-t
 import { computeToolApprovalDigest } from "../security/tool-approval-digest.js";
 import { getLogger } from "../util/logger.js";
 import { mintGrantFromDecision } from "./approval-primitive.js";
+import { withdrawGuardianRequestCards } from "./guardian-card-withdrawal.js";
 import {
   type ActorContext,
   type ChannelDeliveryContext,
@@ -354,6 +355,7 @@ export type CanonicalDecisionResult =
         | "not_found"
         | "already_resolved"
         | "identity_mismatch"
+        | "request_misconfigured"
         | "invalid_action"
         | "expired";
       detail?: string;
@@ -426,18 +428,22 @@ export async function applyCanonicalGuardianDecision(
   // authorization gate — principal identity must always match.
 
   if (!request.guardianPrincipalId) {
-    log.warn(
+    // A decisionable request with no bound principal can never be authorized
+    // by anyone — it is stuck. This is a data-integrity fault (creation guards
+    // against it for decisionable kinds), not an authorization denial, so it
+    // must NOT be reported to the actor as "you don't have permission".
+    log.error(
       {
         event: "canonical_decision_missing_request_principal",
         requestId,
         kind: request.kind,
         sourceType: request.sourceType,
       },
-      "Canonical request missing guardianPrincipalId; rejecting decision",
+      "Canonical request missing guardianPrincipalId; request is undecidable",
     );
     return {
       applied: false,
-      reason: "identity_mismatch",
+      reason: "request_misconfigured",
       detail: "request missing guardianPrincipalId",
     };
   }
@@ -571,6 +577,23 @@ export async function applyCanonicalGuardianDecision(
     grantMinted = grantResult.minted;
   }
 
+  // 6. Project the terminal status onto the request's approval cards on every
+  // surface it was delivered to (in-app, Slack, ...). Fire-and-forget: the
+  // decision is already committed via CAS and withdrawal is a best-effort
+  // cosmetic projection, so awaiting its Slack round-trips would only add
+  // latency to the decision response that interactive callers wait on. The
+  // projector never throws; the `.catch` is a defensive backstop.
+  void withdrawGuardianRequestCards({
+    request: resolved,
+    status: targetStatus,
+    originChannel: actorContext.channel,
+  }).catch((err) => {
+    log.warn(
+      { err, requestId },
+      "Cross-surface card withdrawal failed (non-fatal)",
+    );
+  });
+
   log.info(
     {
       event: "canonical_decision_applied",