@vellumai/assistant 0.10.0 → 0.10.1-dev.202606240317.ea25efe

package/src/agent/loop.ts

@@ -391,6 +391,17 @@ export type AgentEvent =
        */
       type: "agent_loop_exit";
       reason: AgentLoopExitReason;
+    }
+  | {
+      /**
+       * Emitted when the `pre-model-call` hook chain mutates the system
+       * prompt for the current call — i.e. `finalPreModelCtx.systemPrompt`
+       * differs from the value the loop handed the hook. Carries the
+       * post-hook string so consumers can observe exactly what the provider
+       * received.
+       */
+      type: "system_prompt_changed";
+      systemPrompt: string;
     };
 
 const DEFAULT_CONFIG: AgentLoopConfig = {
@@ -482,12 +493,6 @@ export function shouldCaptureAgentLoopError(err: Error): boolean {
   return true;
 }
 
-export interface ResolvedSystemPrompt {
-  systemPrompt: string;
-  maxTokens?: number;
-  model?: string;
-}
-
 export interface AgentLoopRunOptions {
   /** Input history the run starts from; the loop appends its output onto a copy. */
   messages: Message[];
@@ -495,6 +500,12 @@ export interface AgentLoopRunOptions {
   onEvent: (event: AgentEvent) => void | Promise<void>;
   signal?: AbortSignal;
   requestId: string;
+  /**
+   * Explicit model override (provider/model string) for every LLM call in
+   * this run. When omitted, the model is resolved through the normal
+   * call-site / profile resolution path.
+   */
+  model?: string;
   onCheckpoint?: (
     checkpoint: CheckpointInfo,
   ) => CheckpointDecision | Promise<CheckpointDecision>;
@@ -614,6 +625,20 @@ export type LoopToolExecutor = (
   activityMetadata?: ToolActivityMetadata;
 }>;
 
+/**
+ * The benign result returned for a sibling tool call that was deferred because
+ * an exclusive tool ran in the same turn. Phrased so the model treats it as a
+ * "not run yet" signal — read the exclusive tool's output, then re-issue this
+ * call if it is still the right next step.
+ */
+function deferredForExclusiveMessage(exclusiveToolName: string): string {
+  return (
+    `(not run: \`${exclusiveToolName}\` was called this turn and runs first, on its own, ` +
+    `so the rest of your tool calls were held back. Read its output, then call this tool ` +
+    `again if it is still the right next step.)`
+  );
+}
+
 export interface AgentLoopConstructorOptions {
   /** LLM provider the loop issues every call through. */
   provider: Provider;
@@ -623,7 +648,14 @@ export interface AgentLoopConstructorOptions {
   tools?: ToolDefinition[];
   toolExecutor?: LoopToolExecutor;
   resolveTools?: (history: Message[]) => ToolDefinition[];
-  resolveSystemPrompt?: (history: Message[]) => ResolvedSystemPrompt;
+  /**
+   * Decide whether a tool runs exclusively in its turn (see
+   * {@link ToolDefinition.exclusive}). When it returns true for a tool present
+   * in a multi-call turn, the loop runs only that tool and defers the siblings
+   * un-run. Injected by the conversation wiring, which can read the tool
+   * registry; lightweight loops that omit it never defer.
+   */
+  isExclusiveTool?: (toolName: string) => boolean;
   /**
    * Conversation this loop drives. Scopes the loop-held compaction circuit
    * breaker and is the source of truth the loop's pipeline contexts and
@@ -648,10 +680,8 @@ export class AgentLoop {
   private config: AgentLoopConfig;
   private tools: ToolDefinition[];
   private resolveTools: ((history: Message[]) => ToolDefinition[]) | null;
-  private resolveSystemPrompt:
-    | ((history: Message[]) => ResolvedSystemPrompt)
-    | null;
   private toolExecutor: LoopToolExecutor | null;
+  private isExclusiveTool: ((toolName: string) => boolean) | null;
 
   /**
    * Conversation this loop drives. Source of truth for the `conversationId`
@@ -681,7 +711,7 @@ export class AgentLoop {
       tools,
       toolExecutor,
       resolveTools,
-      resolveSystemPrompt,
+      isExclusiveTool,
       conversationId,
       resolveConversationDir,
     } = options;
@@ -690,8 +720,8 @@ export class AgentLoop {
     this.config = { ...DEFAULT_CONFIG, ...config };
     this.tools = tools ?? [];
     this.resolveTools = resolveTools ?? null;
-    this.resolveSystemPrompt = resolveSystemPrompt ?? null;
     this.toolExecutor = toolExecutor ?? null;
+    this.isExclusiveTool = isExclusiveTool ?? null;
     this.conversationId = conversationId;
     this.resolveConversationDir = resolveConversationDir ?? null;
     this.compactionCircuit = new CompactionCircuit(this.conversationId);
@@ -899,7 +929,14 @@ export class AgentLoop {
       compactInPlace = false,
       isNonInteractive = false,
       modelProfileKey = null,
+      model: runModel,
     } = options;
+    // Snapshot the system prompt once per run. The instance field is mutable
+    // (the conversation may update it between turns), but a single run must
+    // use one consistent prompt — an aborted run left detached after the
+    // watchdog rejects must not pick up a later turn's prompt on its next
+    // provider call.
+    const runSystemPrompt = this.systemPrompt;
     let history = [...messages];
     // Index into `history` where this run's appended output begins. It starts
     // after the input and resets to the new base whenever the loop rewrites the
@@ -1207,15 +1244,8 @@ export class AgentLoop {
           ? this.resolveTools(history)
           : this.tools;
 
-        // Resolve system prompt, per-turn maxTokens, and model
-        const resolved = this.resolveSystemPrompt
-          ? this.resolveSystemPrompt(history)
-          : null;
-        const turnSystemPrompt = resolved?.systemPrompt ?? this.systemPrompt;
-        const turnModel = resolved?.model;
-
         // Field precedence (highest wins):
-        //   1. Per-turn explicit (`resolved.maxTokens` / `resolved.model`)
+        //   1. Per-run explicit (`runModel`)
         //   2. Call-site resolved values (filled by
         //      `RetryProvider.normalizeSendMessageOptions` from
         //      `resolveCallSiteConfig(callSite, llm)`)
@@ -1233,14 +1263,12 @@ export class AgentLoop {
         // they always come from `this.config` regardless of `callSite`.
         const providerConfig: Record<string, unknown> = {};
 
-        if (resolved?.maxTokens !== undefined) {
-          providerConfig.max_tokens = resolved.maxTokens;
-        } else if (!callSite) {
+        if (!callSite) {
           providerConfig.max_tokens = this.config.maxTokens;
         }
 
-        if (turnModel) {
-          providerConfig.model = turnModel;
+        if (runModel) {
+          providerConfig.model = runModel;
         }
 
         if (!callSite) {
@@ -1334,7 +1362,7 @@ export class AgentLoop {
           currentTools.length > 0 ? estimateToolsTokens(currentTools) : 0;
         const preSendEstimatedTokens = estimatePromptTokensRaw(
           history,
-          turnSystemPrompt,
+          runSystemPrompt,
           {
             providerName: getCalibrationProviderKey(this.provider),
             toolTokenBudget,
@@ -1366,7 +1394,7 @@ export class AgentLoop {
         // type through unchanged.
         const providerOptions: SendMessageOptions = {
           tools: currentTools.length > 0 ? currentTools : undefined,
-          systemPrompt: turnSystemPrompt,
+          systemPrompt: runSystemPrompt,
           config: providerConfig,
           onEvent: (event) => {
             if (event.type === "text_delta") {
@@ -1447,6 +1475,21 @@ export class AgentLoop {
             HOOKS.PRE_MODEL_CALL,
             preModelCtx,
           );
+          // Emit a changed event when the hook mutated the prompt. Compare
+          // against the pre-hook value from providerOptions, not
+          // preModelCtx — the hook may mutate the context object in place,
+          // which would make preModelCtx.systemPrompt already reflect the
+          // change and hide the diff.
+          const preHookSystemPrompt = providerOptions.systemPrompt ?? null;
+          if (
+            typeof finalPreModelCtx.systemPrompt === "string" &&
+            finalPreModelCtx.systemPrompt !== preHookSystemPrompt
+          ) {
+            await onEvent({
+              type: "system_prompt_changed",
+              systemPrompt: finalPreModelCtx.systemPrompt,
+            });
+          }
           providerOptions.systemPrompt =
             finalPreModelCtx.systemPrompt ?? undefined;
           // Route this call to the hook's chosen inference profile. The
@@ -1865,8 +1908,39 @@ export class AgentLoop {
           "Tool execution start",
         );
 
+        // When an exclusive tool (e.g. the advisor) is among this turn's calls,
+        // it must run alone: the model should incorporate its output before
+        // acting on anything else. Run only the first exclusive call and defer
+        // the siblings with a benign, un-run result so the model re-issues them
+        // next turn if still needed. Every tool_use still gets a matching
+        // tool_result, so history stays well-formed.
+        const exclusiveBlock = this.isExclusiveTool
+          ? toolUseBlocks.find((block) => this.isExclusiveTool!(block.name))
+          : undefined;
+        const deferSiblings =
+          exclusiveBlock !== undefined && toolUseBlocks.length > 1;
+        if (deferSiblings) {
+          rlog.info(
+            {
+              turn: toolUseTurns,
+              exclusiveTool: exclusiveBlock!.name,
+              deferred: toolUseBlocks
+                .filter((block) => block !== exclusiveBlock)
+                .map((block) => block.name),
+            },
+            "Exclusive tool present — running it alone and deferring sibling tool calls this turn",
+          );
+        }
+
         const toolExecutionPromise = Promise.all(
           toolUseBlocks.map(async (toolUse) => {
+            if (deferSiblings && toolUse !== exclusiveBlock) {
+              const result: Awaited<ReturnType<LoopToolExecutor>> = {
+                content: deferredForExclusiveMessage(exclusiveBlock!.name),
+                isError: false,
+              };
+              return { toolUse, result };
+            }
             const result = await this.toolExecutor!(
               toolUse.name,
               toolUse.input,

package/src/api/constants/sse-replay.ts

@@ -0,0 +1,41 @@
+/**
+ * Maximum number of events the daemon's per-process SSE replay ring
+ * retains for `Last-Event-ID` resume. This is the ring's count bound; the
+ * ring is also bounded by total bytes and entry age (whichever limit is
+ * hit first wins), so the live ring can hold *fewer* than this many
+ * events, never more. The daemon-side definition and eviction live in
+ * `assistant/src/runtime/assistant-stream-state.ts`.
+ *
+ * Exposed on the API surface so the web client's SSE consumer can size
+ * its seq-gap tolerance against the same number the daemon buffers
+ * against, instead of hard-coding a duplicate.
+ *
+ * A live seq gap smaller than this is benign: the global per-assistant
+ * `seq` counter is stamped before fanout, but the hub deliberately
+ * withholds some events from a given subscriber — self-echo-suppressed
+ * `sync_changed` (a client's own mutation echo) and capability-targeted
+ * host-proxy events — so a subscriber legitimately sees its cursor skip a
+ * few seqs it was never going to receive. Such a hole is not data loss
+ * and must not trigger a destructive authoritative snapshot heal. Only a
+ * gap that meets or exceeds this count proves the live suffix fell
+ * outside the ring entirely and is genuinely non-contiguous.
+ */
+export const SSE_REPLAY_RING_COUNT_LIMIT = 200;
+
+/**
+ * Maximum age (in milliseconds) an event may reach in the daemon's SSE
+ * replay ring before it is evicted, regardless of count or byte usage.
+ * The daemon-side definition and eviction live in
+ * `assistant/src/runtime/assistant-stream-state.ts`.
+ *
+ * Exposed alongside the count bound so the web client can reason about
+ * the age dimension of the ring too. A small live seq gap is only safe to
+ * treat as benign when the client has been continuously receiving events
+ * — live delivery is concurrent with stamping, so a connected subscriber
+ * never relies on the ring. Once the connection has been quiet for longer
+ * than this window (a disconnect/resume), events the client missed may
+ * have aged out of the ring and become unrecoverable by replay, so even a
+ * small seq gap must trigger an authoritative reconcile rather than be
+ * waved through.
+ */
+export const SSE_REPLAY_RING_AGE_LIMIT_MS = 30_000;

package/src/api/events/ui-surface-show.ts

@@ -5,9 +5,14 @@
  * form, list, table, confirmation, dynamic_page, file_upload,
  * document_preview, task_preferences) inside the chat view. The
  * concrete `data` shape depends on `surfaceType` and is owned by the
- * surface-data subsystem in `daemon/message-types/surfaces.ts`; the
- * canonical schema treats `data` as opaque on the wire so this file
- * doesn't have to mirror eight nested-payload schemas.
+ * surface-data subsystem in `daemon/message-types/surfaces.ts`
+ * (`CardSurfaceDataSchema` et al.). `data` is intentionally opaque on the
+ * wire — not for brevity, but because (1) this event is a member of the
+ * `type`-discriminated `AssistantEventSchema`, and (2) the stream parser
+ * drops any event that fails validation, so a strict per-`surfaceType`
+ * payload schema would silently vanish renderable-but-messy LLM surfaces.
+ * Consumers narrow `data` by parsing it with the canonical per-type schema
+ * (all-optional, so it never rejects a real surface) at their boundary.
  *
  * Lifecycle: a surface progresses `show` → (zero or more `update`s) →
  * (`dismiss` for cancellation OR `complete` with a `summary` /

package/src/api/index.ts

@@ -44,7 +44,6 @@ import { ToolResultEventSchema } from "./events/tool-result.js";
 import { ToolUsePreviewStartEventSchema } from "./events/tool-use-preview-start.js";
 import { ToolUseStartEventSchema } from "./events/tool-use-start.js";
 import { TraceEventSchema } from "./events/trace-event.js";
-import { TurnProfileAutoRoutedEventSchema } from "./events/turn-profile-auto-routed.js";
 import { UISurfaceCompleteEventSchema } from "./events/ui-surface-complete.js";
 import { UISurfaceDismissEventSchema } from "./events/ui-surface-dismiss.js";
 import { UISurfaceShowEventSchema } from "./events/ui-surface-show.js";
@@ -62,6 +61,10 @@ export {
   CALL_SITE_COMPACTION_AGENT,
   CALL_SITE_SYNTHETIC_AGENT_ERROR_MESSAGE,
 } from "./constants/call-sites.js";
+export {
+  SSE_REPLAY_RING_AGE_LIMIT_MS,
+  SSE_REPLAY_RING_COUNT_LIMIT,
+} from "./constants/sse-replay.js";
 export { DEFAULT_TOOL_EXECUTION_TIMEOUT_SEC } from "./constants/tool-execution.js";
 export {
   type AssistantActivityAnchor,
@@ -297,10 +300,6 @@ export {
   type TraceEventStatus,
   TraceEventStatusSchema,
 } from "./events/trace-event.js";
-export {
-  type TurnProfileAutoRoutedEvent,
-  TurnProfileAutoRoutedEventSchema,
-} from "./events/turn-profile-auto-routed.js";
 export {
   type UISurfaceCompleteEvent,
   UISurfaceCompleteEventSchema,
@@ -435,6 +434,8 @@ export {
   LlmContextResponseSchema,
 } from "./responses/llm-context-response.js";
 export {
+  type LLMCallError,
+  LLMCallErrorSchema,
   type LLMCallSummary,
   LLMCallSummarySchema,
   type LLMContextSection,
@@ -476,6 +477,7 @@ export {
   type WorkflowLeaf,
   WorkflowLeafSchema,
 } from "./responses/workflow-journal.js";
+export { type CardSurfaceData, CardSurfaceDataSchema } from "./surfaces.js";
 
 /**
  * Canonical SSE event schema for the assistant runtime.
@@ -535,7 +537,6 @@ export const AssistantEventSchema = z.discriminatedUnion("type", [
   ToolUsePreviewStartEventSchema,
   ToolUseStartEventSchema,
   TraceEventSchema,
-  TurnProfileAutoRoutedEventSchema,
   UISurfaceCompleteEventSchema,
   UISurfaceDismissEventSchema,
   UISurfaceShowEventSchema,

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

@@ -225,6 +225,10 @@ export type ConversationMessageToolCall = z.infer<
 // Surface
 // ---------------------------------------------------------------------------
 
+// Intentionally more permissive than the canonical SurfaceActionSchema in
+// api/events/ui-surface-show.ts: the write-path schema uses z.enum for style
+// so new surfaces only emit known values; this read-path schema uses z.string
+// so historical surfaces with non-standard style values still parse.
 const SurfaceActionSchema = z.object({
   id: z.string(),
   label: z.string(),

package/src/api/responses/llm-request-log-entry.ts

@@ -67,6 +67,30 @@ export const LLMContextSectionSchema = z.object({
 
 export type LLMContextSection = z.infer<typeof LLMContextSectionSchema>;
 
+/**
+ * Structured provider/transport error recorded when an LLM call was
+ * rejected before producing a response. Mirrors the on-disk
+ * `responsePayload.error` shape written by
+ * `buildProviderErrorResponsePayload` — the inspector branches on the
+ * presence of this field to render a failed call distinctly (failure
+ * banner in the Response tab, $0.00 cost in the rail, etc.) instead of
+ * the generic "section rendering unavailable" fallback.
+ *
+ * Every field is optional because the serializer degrades a plain
+ * `Error` down to just `{ name, message }`; only the wrapper object is
+ * guaranteed.
+ */
+export const LLMCallErrorSchema = z.object({
+  name: z.string().nullish(),
+  message: z.string().nullish(),
+  code: z.string().nullish(),
+  provider: z.string().nullish(),
+  statusCode: z.number().nullish(),
+  retryAfterMs: z.number().nullish(),
+});
+
+export type LLMCallError = z.infer<typeof LLMCallErrorSchema>;
+
 /**
  * One LLM request log row.
  *
@@ -88,6 +112,7 @@ export const LLMRequestLogEntrySchema = z.object({
   responseSections: z.array(LLMContextSectionSchema).nullish(),
   agentLoopExitReason: z.string().nullish(),
   callSite: z.string().nullish(),
+  error: LLMCallErrorSchema.nullish(),
 });
 
 export type LLMRequestLogEntry = z.infer<typeof LLMRequestLogEntrySchema>;

package/src/api/responses/subagent-detail.ts

@@ -31,6 +31,23 @@ export const SubagentDetailEventSchema = z.object({
   toolName: z.string().optional(),
   isError: z.boolean().optional(),
   messageId: z.string().optional(),
+  /**
+   * Tool-call id — the `tool_use.id` on a tool-call event and the referencing
+   * `tool_use_id` on its tool-result event, in the daemon's canonical
+   * content-block format. That format is provider-agnostic: every provider
+   * (Anthropic, OpenAI, Gemini, …) normalizes its native tool calls into these
+   * `tool_use`/`tool_result` blocks (see `providers/types.ts`), so this id is
+   * present regardless of which model produced the call. Lets the web client
+   * pair a result with its call and key the nested tool-detail view, so tool
+   * pills on reloaded/history subagents are clickable (not just live ones).
+   */
+  toolUseId: z.string().optional(),
+  /**
+   * Raw tool input object on tool-call events. (`content` also carries a
+   * JSON-stringified copy for back-compat / label derivation.) Surfaced in the
+   * tool-detail view's input section.
+   */
+  input: z.record(z.string(), z.unknown()).optional(),
 });
 
 export type SubagentDetailEvent = z.infer<typeof SubagentDetailEventSchema>;

package/src/api/surfaces.ts

@@ -0,0 +1,33 @@
+/**
+ * Canonical surface-data wire payloads.
+ *
+ * The `ui_surface_*` events and the conversation-message response all carry a
+ * surface `data` object whose shape depends on `surfaceType`. The wire keeps
+ * `data` opaque (`z.record`) — see `events/ui-surface-show.ts` for why — so
+ * consumers narrow it by parsing with the canonical per-type schema here. The
+ * schemas are deliberately tolerant (every field optional, Zod strip mode): a
+ * parse miss makes a renderable surface silently vanish, so they must never
+ * reject a real payload. The schema also defines what the daemon's `ui_show`
+ * normalizer *supports* — anything the model sends outside these fields is
+ * dropped (and logged) there, which is how we learn the shapes to recover.
+ *
+ * Card is the first surface type migrated to a canonical schema; the remaining
+ * types still live as hand-written interfaces in
+ * `daemon/message-types/surfaces.ts` pending migration.
+ */
+
+import { z } from "zod";
+
+export const CardSurfaceDataSchema = z.object({
+  title: z.string().optional(),
+  subtitle: z.string().optional(),
+  body: z.string().optional(),
+  metadata: z
+    .array(z.object({ label: z.coerce.string(), value: z.coerce.string() }))
+    .optional(),
+  /** Optional template name for specialized rendering (e.g. "weather_forecast"). */
+  template: z.string().optional(),
+  /** Arbitrary data consumed by the template renderer. Shape depends on template. */
+  templateData: z.record(z.string(), z.unknown()).optional(),
+});
+export type CardSurfaceData = z.infer<typeof CardSurfaceDataSchema>;

package/src/approvals/AGENTS.md

@@ -5,8 +5,7 @@
 - **Rich delivery failures must degrade gracefully.** If delivering a rich approval prompt (e.g., Telegram inline buttons) fails, fall back to plain text with instructions (e.g., `Reply "yes" to approve`) — never auto-deny.
 - **Non-rich channels** (http-api) receive plain-text approval prompts. The conversational approval engine handles free-text responses.
 - **Race conditions:** Always check whether a decision has already been resolved before delivering the engine's optimistic reply. If `handleChannelDecision` returns `applied: false`, deliver an "already resolved" notice and return `stale_ignored`.
-- **Requester self-cancel:** A requester with a pending guardian approval must be able to cancel their own request (but not self-approve).
-- **Unified guardian decision primitive:** All guardian decision paths (callback buttons, conversational engine, requester self-cancel) must route through `applyGuardianDecision()` in `assistant/src/approvals/guardian-decision-primitive.ts`. Do not inline decision logic (approval record updates, grant minting) at individual callsites.
+- **Unified guardian decision primitive:** All guardian decision paths (callback buttons, conversational engine, channel reactions and text) must route through `applyCanonicalGuardianDecision()` in `assistant/src/approvals/guardian-decision-primitive.ts`. Do not inline decision logic (CAS resolution, resolver dispatch, grant minting) at individual callsites.
 
 ## Single-Guardian Invariant