@vellumai/assistant 0.10.2 → 0.10.3-dev.202606252046.9075fd5

package/src/agent/loop-native-web-search.test.ts

@@ -0,0 +1,200 @@
+/**
+ * Verifies the agent loop's provider-native web-search gate (used by the
+ * tool-less advisor consult): when `enableNativeWebSearch` is set, the loop
+ * appends a `web_search`-named SERVER tool to the outbound request and forces
+ * `tool_choice: auto` — but ONLY when the provider/model the call ACTUALLY
+ * routes to reports native-search support. A non-native target gets nothing,
+ * and the consult stays tool-less (no client `web_search` tool surfaced).
+ *
+ * The gate prefers the routing-aware `supportsNativeWebSearchFor(options)` (the
+ * routed (provider, model)'s capability) over the construction-time
+ * `supportsNativeWebSearch` snapshot. The advisor's `advisorProfile` can route
+ * `subagentSpawn` to a provider/model whose native-search support DIFFERS from
+ * the default, so the routed capability — not the default's — must drive the
+ * decision in both directions. Drives the REAL loop, mocking only the provider
+ * boundary.
+ */
+import { describe, expect, test } from "bun:test";
+
+import { createMockProvider } from "../__tests__/helpers/mock-provider.js";
+import type {
+  Provider,
+  ProviderResponse,
+  SendMessageOptions,
+} from "../providers/types.js";
+import { AgentLoop } from "./loop.js";
+
+const endTurn = (text: string): ProviderResponse => ({
+  content: [{ type: "text", text }],
+  model: "mock-model",
+  usage: { inputTokens: 1, outputTokens: 1 },
+  stopReason: "end_turn",
+});
+
+const baseRun = {
+  requestId: "req-web",
+  onEvent: () => {},
+  callSite: "subagentSpawn" as const,
+  trust: { sourceChannel: "vellum" as const, trustClass: "unknown" as const },
+};
+
+const userMessages = [
+  {
+    role: "user" as const,
+    content: [{ type: "text" as const, text: "advise" }],
+  },
+];
+
+/** Build a tool-less loop (mirrors the advisor consult) with the given flag. */
+function buildAdvisorLoop(
+  provider: Provider,
+  enableNativeWebSearch: boolean,
+): AgentLoop {
+  return new AgentLoop({
+    provider,
+    systemPrompt: "advisor system",
+    conversationId: "advisor-1",
+    // Tool-less for client tools — exactly the advisor role's empty allowlist.
+    config: { enableNativeWebSearch },
+  });
+}
+
+describe("AgentLoop — provider-native web search gate", () => {
+  test("attaches the native web_search server tool when the provider supports it", async () => {
+    const { provider, calls } = createMockProvider([endTurn("guidance")]);
+    (
+      provider as { supportsNativeWebSearch?: boolean }
+    ).supportsNativeWebSearch = true;
+
+    const loop = buildAdvisorLoop(provider, true);
+    await loop.run({ ...baseRun, messages: userMessages });
+
+    expect(calls).toHaveLength(1);
+    const sent = calls[0];
+    // The native web_search SERVER tool is the only tool surfaced.
+    expect(sent.tools?.map((t) => t.name)).toEqual(["web_search"]);
+    // tool_choice is forced to auto so the model may invoke the search.
+    expect(sent.options?.config?.tool_choice).toEqual({ type: "auto" });
+  });
+
+  test("attaches nothing on a non-native provider (consult stays tool-less)", async () => {
+    const { provider, calls } = createMockProvider([endTurn("guidance")]);
+    // supportsNativeWebSearch is absent (falsy) — a non-native provider.
+
+    const loop = buildAdvisorLoop(provider, true);
+    await loop.run({ ...baseRun, messages: userMessages });
+
+    expect(calls).toHaveLength(1);
+    const sent = calls[0];
+    // No web_search tool surfaced — no client tool the one-shot consult can't run.
+    expect(sent.tools).toBeUndefined();
+    // No tool_choice forced when nothing is attached.
+    expect(sent.options?.config?.tool_choice).toBeUndefined();
+  });
+
+  test("attaches nothing when the flag is off, even on a native provider", async () => {
+    const { provider, calls } = createMockProvider([endTurn("guidance")]);
+    (
+      provider as { supportsNativeWebSearch?: boolean }
+    ).supportsNativeWebSearch = true;
+
+    const loop = buildAdvisorLoop(provider, false);
+    await loop.run({ ...baseRun, messages: userMessages });
+
+    expect(calls).toHaveLength(1);
+    const sent = calls[0];
+    expect(sent.tools).toBeUndefined();
+    expect(sent.options?.config?.tool_choice).toBeUndefined();
+  });
+
+  test("does not duplicate web_search when a tool of that name is already present", async () => {
+    const { provider, calls } = createMockProvider([endTurn("guidance")]);
+    (
+      provider as { supportsNativeWebSearch?: boolean }
+    ).supportsNativeWebSearch = true;
+
+    // A loop that already exposes a `web_search` client tool (e.g. researcher
+    // role). The gate must not append a second `web_search` entry.
+    const loop = new AgentLoop({
+      provider,
+      systemPrompt: "sys",
+      conversationId: "advisor-dup",
+      config: { enableNativeWebSearch: true },
+      tools: [
+        {
+          name: "web_search",
+          description: "",
+          input_schema: { type: "object" },
+        },
+      ],
+    });
+    await loop.run({ ...baseRun, messages: userMessages });
+
+    const sent = calls[0];
+    expect(sent.tools?.filter((t) => t.name === "web_search")).toHaveLength(1);
+  });
+
+  // ── Routed capability drives the decision (not the static default) ────────
+
+  test("false positive: static flag is native but the ROUTED target is not — attaches nothing", async () => {
+    const { provider, calls } = createMockProvider([endTurn("guidance")]);
+    // The construction-time default supports native search…
+    (
+      provider as { supportsNativeWebSearch?: boolean }
+    ).supportsNativeWebSearch = true;
+    // …but the advisorProfile routes `subagentSpawn` to a provider/model that
+    // does NOT. The routing-aware probe wins, so no unexecutable client tool is
+    // surfaced to the otherwise tool-less advisor.
+    (
+      provider as {
+        supportsNativeWebSearchFor?: (o?: SendMessageOptions) => boolean;
+      }
+    ).supportsNativeWebSearchFor = () => false;
+
+    const loop = buildAdvisorLoop(provider, true);
+    await loop.run({ ...baseRun, messages: userMessages });
+
+    const sent = calls[0];
+    expect(sent.tools).toBeUndefined();
+    expect(sent.options?.config?.tool_choice).toBeUndefined();
+  });
+
+  test("false negative: static flag is non-native but the ROUTED target is — attaches the tool", async () => {
+    const { provider, calls } = createMockProvider([endTurn("guidance")]);
+    // The construction-time default lacks native search (flag absent/falsy)…
+    // …but the advisorProfile routes to a provider/model that has it.
+    (
+      provider as {
+        supportsNativeWebSearchFor?: (o?: SendMessageOptions) => boolean;
+      }
+    ).supportsNativeWebSearchFor = () => true;
+
+    const loop = buildAdvisorLoop(provider, true);
+    await loop.run({ ...baseRun, messages: userMessages });
+
+    const sent = calls[0];
+    expect(sent.tools?.map((t) => t.name)).toEqual(["web_search"]);
+    expect(sent.options?.config?.tool_choice).toEqual({ type: "auto" });
+  });
+
+  test("the routing probe receives the loop's callSite", async () => {
+    const { provider, calls } = createMockProvider([endTurn("guidance")]);
+    const probeOptions: (SendMessageOptions | undefined)[] = [];
+    (
+      provider as {
+        supportsNativeWebSearchFor?: (o?: SendMessageOptions) => boolean;
+      }
+    ).supportsNativeWebSearchFor = (o) => {
+      probeOptions.push(o);
+      return true;
+    };
+
+    const loop = buildAdvisorLoop(provider, true);
+    await loop.run({ ...baseRun, messages: userMessages });
+
+    expect(calls).toHaveLength(1);
+    // The probe is resolved against the same callSite the dispatch uses
+    // (`subagentSpawn` per `baseRun`), so the routed (provider, model) matches.
+    expect(probeOptions[0]?.config?.callSite).toBe("subagentSpawn");
+  });
+});

package/src/agent/loop.ts

@@ -95,6 +95,74 @@ export interface AgentLoopConfig {
   minTurnIntervalMs?: number;
   /** Override the default prompt cache TTL sent to the provider (e.g. "5m" for short-lived subagents). */
   cacheTtl?: "5m" | "1h";
+  /**
+   * Give every LLM call provider-native (server-side) web search, gated on the
+   * native-search capability of the (provider, model) the call routes to —
+   * {@link Provider.supportsNativeWebSearchFor} when the provider exposes it,
+   * else the static {@link Provider.supportsNativeWebSearch} flag.
+   * When both are true, the loop appends a `web_search`-named tool to the
+   * outbound request — which Anthropic/OpenAI substitute for their server-side
+   * search tool, running the search inline and returning results without a
+   * client tool round-trip — and forces `tool_choice: auto` so the model may
+   * call it. Non-native providers get nothing.
+   *
+   * This is a SERVER tool the provider runs itself, distinct from the client
+   * tool list (`tools` / `resolveTools`): it is never executed by
+   * {@link AgentLoopConstructorOptions.toolExecutor} and does not require any
+   * client-tool allowlist entry. Used by the tool-less advisor consult to
+   * ground its guidance with live web access while staying one-shot for client
+   * tools. Defaults to false — existing behavior.
+   */
+  enableNativeWebSearch?: boolean;
+}
+
+/**
+ * The `web_search`-named tool the loop appends when
+ * {@link AgentLoopConfig.enableNativeWebSearch} is set on a native provider.
+ * Anthropic/OpenAI intercept a tool with this name and substitute their own
+ * server-side web search (run inline, no client execution), so the exact
+ * `input_schema` is informational — the provider supplies the real schema.
+ */
+const NATIVE_WEB_SEARCH_TOOL: ToolDefinition = {
+  name: "web_search",
+  description:
+    "Search the web for current information to ground your response.",
+  input_schema: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "The search query." },
+    },
+    required: ["query"],
+  },
+};
+
+/**
+ * Build the minimal `SendMessageOptions` a routing-aware provider needs to
+ * report the native web-search capability of the (provider, model) THIS turn
+ * routes to. Mirrors the call-site fields the loop plumbs onto the actual send
+ * (`callSite` + `overrideProfile`/`forceOverrideProfile` + per-conversation
+ * `selectionSeed`) so the capability probe and the dispatch resolve the same
+ * arm. Returns `undefined` when there is no `callSite` (the legacy
+ * default-provider path); `selectionSeed` is omitted for standalone loops with
+ * no conversation id, matching the dispatch path's own guard.
+ */
+function buildNativeWebSearchProbeOptions(
+  callSite: LLMCallSite | undefined,
+  overrideProfile: string | undefined,
+  forceOverrideProfile: boolean,
+  conversationId: string | undefined,
+): SendMessageOptions | undefined {
+  if (!callSite) return undefined;
+  return {
+    config: {
+      callSite,
+      ...(overrideProfile ? { overrideProfile } : {}),
+      ...(overrideProfile && forceOverrideProfile
+        ? { forceOverrideProfile: true }
+        : {}),
+      ...(conversationId ? { selectionSeed: conversationId } : {}),
+    },
+  };
 }
 
 export interface CheckpointInfo {
@@ -625,6 +693,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;
@@ -634,6 +716,14 @@ export interface AgentLoopConstructorOptions {
   tools?: ToolDefinition[];
   toolExecutor?: LoopToolExecutor;
   resolveTools?: (history: Message[]) => ToolDefinition[];
+  /**
+   * 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
@@ -659,6 +749,7 @@ export class AgentLoop {
   private tools: ToolDefinition[];
   private resolveTools: ((history: Message[]) => ToolDefinition[]) | null;
   private toolExecutor: LoopToolExecutor | null;
+  private isExclusiveTool: ((toolName: string) => boolean) | null;
 
   /**
    * Conversation this loop drives. Source of truth for the `conversationId`
@@ -688,6 +779,7 @@ export class AgentLoop {
       tools,
       toolExecutor,
       resolveTools,
+      isExclusiveTool,
       conversationId,
       resolveConversationDir,
     } = options;
@@ -697,6 +789,7 @@ export class AgentLoop {
     this.tools = tools ?? [];
     this.resolveTools = resolveTools ?? null;
     this.toolExecutor = toolExecutor ?? null;
+    this.isExclusiveTool = isExclusiveTool ?? null;
     this.conversationId = conversationId;
     this.resolveConversationDir = resolveConversationDir ?? null;
     this.compactionCircuit = new CompactionCircuit(this.conversationId);
@@ -1215,10 +1308,44 @@ export class AgentLoop {
 
         // Resolve tools for this turn: use the dynamic resolver if provided,
         // otherwise fall back to the static tool list.
-        const currentTools = this.resolveTools
+        const resolvedTools = this.resolveTools
           ? this.resolveTools(history)
           : this.tools;
 
+        // Provider-native web search: append a `web_search`-named tool that the
+        // provider substitutes for its server-side search (run inline, no client
+        // execution), gated STRICTLY on the capability of the provider/model
+        // this call ACTUALLY routes to so a non-native provider never sees an
+        // unexecutable client tool. The advisor consult's `advisorProfile` can
+        // route `subagentSpawn` to a provider/model whose native-search support
+        // differs from the construction-time default, so the gate resolves the
+        // routed target (callSite + overrideProfile) via
+        // `supportsNativeWebSearchFor` rather than the static
+        // `this.provider.supportsNativeWebSearch` snapshot; providers without
+        // the routing-aware probe fall back to the static flag. This is a SERVER
+        // tool — it bypasses the client allowlist and the tool executor — so the
+        // tool-less advisor consult can ground its guidance with live web access
+        // while staying one-shot for client tools. Skip when a `web_search` tool
+        // is already present so we never duplicate the name.
+        const supportsRoutedNativeWebSearch = this.provider
+          .supportsNativeWebSearchFor
+          ? this.provider.supportsNativeWebSearchFor(
+              buildNativeWebSearchProbeOptions(
+                callSite,
+                resolveEffectiveOverrideProfile(),
+                forceOverrideProfile,
+                this.conversationId,
+              ),
+            )
+          : this.provider.supportsNativeWebSearch === true;
+        const attachNativeWebSearch =
+          this.config.enableNativeWebSearch === true &&
+          supportsRoutedNativeWebSearch &&
+          !resolvedTools.some((t) => t.name === NATIVE_WEB_SEARCH_TOOL.name);
+        const currentTools = attachNativeWebSearch
+          ? [...resolvedTools, NATIVE_WEB_SEARCH_TOOL]
+          : resolvedTools;
+
         // Field precedence (highest wins):
         //   1. Per-run explicit (`runModel`)
         //   2. Call-site resolved values (filled by
@@ -1261,6 +1388,11 @@ export class AgentLoop {
 
         if (this.config.toolChoice) {
           providerConfig.tool_choice = this.config.toolChoice;
+        } else if (attachNativeWebSearch) {
+          // The native web-search tool is the only tool on this turn (the
+          // advisor consult is otherwise tool-less). Let the model decide
+          // whether to search rather than forcing it.
+          providerConfig.tool_choice = { type: "auto" };
         }
 
         if (this.config.cacheTtl) {
@@ -1883,8 +2015,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/conversation-notice.ts

@@ -0,0 +1,26 @@
+/**
+ * `conversation_notice` SSE event.
+ *
+ * Non-terminal, conversation-scoped notice for actionable runtime conditions
+ * that should not mark the turn as failed. The client may render CTA UI from
+ * this event while preserving the current assistant response.
+ */
+
+import { z } from "zod";
+
+import { ConversationErrorCodeSchema } from "./conversation-error.js";
+
+export const ConversationNoticeSourceSchema = z.enum(["memory_v3"]);
+
+export const ConversationNoticeEventSchema = z.object({
+  type: z.literal("conversation_notice"),
+  conversationId: z.string(),
+  source: ConversationNoticeSourceSchema,
+  code: ConversationErrorCodeSchema,
+  userMessage: z.string(),
+  errorCategory: z.string().optional(),
+});
+
+export type ConversationNoticeEvent = z.infer<
+  typeof ConversationNoticeEventSchema
+>;

package/src/api/index.ts

@@ -11,6 +11,7 @@ import { ConfirmationRequestEventSchema } from "./events/confirmation-request.js
 import { ContactRequestEventSchema } from "./events/contact-request.js";
 import { ConversationErrorEventSchema } from "./events/conversation-error.js";
 import { ConversationListInvalidatedEventSchema } from "./events/conversation-list-invalidated.js";
+import { ConversationNoticeEventSchema } from "./events/conversation-notice.js";
 import { ConversationTitleUpdatedEventSchema } from "./events/conversation-title-updated.js";
 import { DiskPressureStatusChangedEventSchema } from "./events/disk-pressure-status-changed.js";
 import { DocumentCommentCreatedEventSchema } from "./events/document-comment-created.js";
@@ -61,6 +62,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,
@@ -134,6 +139,11 @@ export {
   type ConversationListInvalidatedReason,
   ConversationListInvalidatedReasonSchema,
 } from "./events/conversation-list-invalidated.js";
+export {
+  type ConversationNoticeEvent,
+  ConversationNoticeEventSchema,
+  ConversationNoticeSourceSchema,
+} from "./events/conversation-notice.js";
 export {
   type ConversationTitleUpdatedEvent,
   ConversationTitleUpdatedEventSchema,
@@ -430,6 +440,8 @@ export {
   LlmContextResponseSchema,
 } from "./responses/llm-context-response.js";
 export {
+  type LLMCallError,
+  LLMCallErrorSchema,
   type LLMCallSummary,
   LLMCallSummarySchema,
   type LLMContextSection,
@@ -471,7 +483,12 @@ export {
   type WorkflowLeaf,
   WorkflowLeafSchema,
 } from "./responses/workflow-journal.js";
-export { type CardSurfaceData, CardSurfaceDataSchema } from "./surfaces.js";
+export {
+  type CardSurfaceData,
+  CardSurfaceDataSchema,
+  type FileUploadSurfaceData,
+  FileUploadSurfaceDataSchema,
+} from "./surfaces.js";
 
 /**
  * Canonical SSE event schema for the assistant runtime.
@@ -498,6 +515,7 @@ export const AssistantEventSchema = z.discriminatedUnion("type", [
   ContactRequestEventSchema,
   ConversationErrorEventSchema,
   ConversationListInvalidatedEventSchema,
+  ConversationNoticeEventSchema,
   ConversationTitleUpdatedEventSchema,
   DiskPressureStatusChangedEventSchema,
   DocumentCommentCreatedEventSchema,

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

@@ -67,6 +67,34 @@ 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(),
+  apiErrorCode: z.string().nullish(),
+  apiErrorType: z.string().nullish(),
+  apiErrorParam: z.string().nullish(),
+  requestId: z.string().nullish(),
+});
+
+export type LLMCallError = z.infer<typeof LLMCallErrorSchema>;
+
 /**
  * One LLM request log row.
  *
@@ -88,6 +116,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

@@ -11,9 +11,9 @@
  * 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.
+ * Card and file_upload use canonical schemas; the remaining types are
+ * hand-written interfaces in `daemon/message-types/surfaces.ts` pending
+ * migration.
  */
 
 import { z } from "zod";
@@ -31,3 +31,39 @@ export const CardSurfaceDataSchema = z.object({
   templateData: z.record(z.string(), z.unknown()).optional(),
 });
 export type CardSurfaceData = z.infer<typeof CardSurfaceDataSchema>;
+
+/**
+ * Accepted MIME-type / extension patterns for a `file_upload` surface.
+ *
+ * The renderer consumes this as a `string[]` — it calls `.join`/`.some`/
+ * `.length` on the value — but the model may emit a single comma-joined string
+ * ("image/*, application/pdf") or a bare string. Coercing every shape to a
+ * clean `string[]` keeps that array invariant intact: a string is split on
+ * commas; array entries are stringified and trimmed; blanks and any non-array
+ * value collapse to `undefined` (no restriction).
+ */
+const FileUploadAcceptedTypesSchema = z.preprocess((value) => {
+  const items =
+    typeof value === "string"
+      ? value.split(",")
+      : Array.isArray(value)
+        ? value
+        : [];
+  const cleaned = items
+    .map((item) =>
+      typeof item === "string" || typeof item === "number"
+        ? String(item).trim()
+        : "",
+    )
+    .filter((item) => item.length > 0);
+  return cleaned.length > 0 ? cleaned : undefined;
+}, z.array(z.string()).optional());
+
+export const FileUploadSurfaceDataSchema = z.object({
+  prompt: z.coerce.string().optional(),
+  acceptedTypes: FileUploadAcceptedTypesSchema,
+  /** A non-positive or non-numeric value is dropped rather than rejecting the surface. */
+  maxFiles: z.coerce.number().int().positive().optional().catch(undefined),
+  maxSizeBytes: z.coerce.number().positive().optional().catch(undefined),
+});
+export type FileUploadSurfaceData = z.infer<typeof FileUploadSurfaceDataSchema>;