@vellumai/assistant 0.11.1 → 0.11.2-staging.2

package/src/agent/loop.ts

@@ -1028,6 +1028,10 @@ export class AgentLoop {
     // rejection means the repair could not recover, so the error surfaces
     // instead of looping. Turn-scoped, so each turn recovers afresh.
     let orderingRepairAttempted = false;
+    // One resume per turn after a call dies mid-generation: a second
+    // interruption means re-issuing is not getting through, so the error
+    // surfaces instead of looping.
+    let interruptedCallResumed = false;
     let lastLlmCallTime = 0;
     let exitReason: ExitReason | null = null;
     // Armed at the end of a tool-use iteration so the budget gate runs at the
@@ -1176,6 +1180,12 @@ export class AgentLoop {
       // elsewhere in the turn body (tool execution, the success-path stop
       // chain, post-model-call hooks) must not re-enter the stop chain.
       let providerCallError: unknown;
+      // Set once the model streams its first token on this iteration's call.
+      // Two readers: latency instrumentation stamps time-to-first-token off
+      // its rising edge, and the outer catch reads it to tell a refused
+      // request from a generation that died mid-flight. Declared here so that
+      // catch can reach it.
+      let streamedTokens = false;
 
       try {
         // ── Pre-call budget gate ─────────────────────────────────────
@@ -1527,11 +1537,6 @@ export class AgentLoop {
         // the client would otherwise see nothing.
         let streamedVisibleText = false;
 
-        // Latency instrumentation: stamp the first streamed token (thinking or
-        // text) of THIS call exactly once, so each per-call segment carries its
-        // own time-to-first-token. Reset per provider call.
-        let firstTokenMarked = false;
-
         // The `onEvent` wrapping below applies sensitive-output placeholder
         // substitution to streamed text while forwarding every other event
         // type through unchanged.
@@ -1541,10 +1546,10 @@ export class AgentLoop {
           config: providerConfig,
           onEvent: (event) => {
             if (
-              !firstTokenMarked &&
+              !streamedTokens &&
               (event.type === "thinking_delta" || event.type === "text_delta")
             ) {
-              firstTokenMarked = true;
+              streamedTokens = true;
               latencyTracker?.markFirstToken(
                 event.type === "thinking_delta" ? "thinking" : "text",
               );
@@ -2498,6 +2503,30 @@ export class AgentLoop {
             newMessagesStart = history.length;
             continue;
           }
+
+          // Last: the call died mid-generation. `streamedTokens` means the
+          // provider accepted the request and started producing before it
+          // failed, so the request is fine and re-issuing it as-is is the
+          // recovery — nothing to repair, which is why no branch above claims
+          // it. A rejection that streamed nothing is the opposite case (the
+          // provider refused the request), and an identical resend would be
+          // refused identically, so those surface. Main-agent turns only:
+          // background call sites answer to callers that handle their own
+          // failures.
+          if (
+            streamedTokens &&
+            !interruptedCallResumed &&
+            callSite === "mainAgent" &&
+            postModelCallContinues < MAX_POST_MODEL_CALL_CONTINUES
+          ) {
+            interruptedCallResumed = true;
+            postModelCallContinues++;
+            rlog.warn(
+              { turn: toolUseTurns, messageCount: history.length, err },
+              "Model call died mid-generation, resuming the turn",
+            );
+            continue;
+          }
         }
 
         rlog.error(

package/src/api/events/context-window-usage.ts

@@ -0,0 +1,31 @@
+/**
+ * `context_window_usage` SSE event.
+ *
+ * Server → client push of a conversation's current context-window usage,
+ * measured with the provider's own tokenizer. Emitted by user-initiated
+ * compaction (`/compact`, "summarize up to here"), which recomputes the
+ * count outside any turn and so has no `usage_update` to carry it. Clients
+ * apply it to the context-window indicator, which otherwise only refreshes
+ * on the next LLM call.
+ *
+ * `tokens` and `maxTokens` are the same figures the compaction result card
+ * reports, so the indicator and the card always agree.
+ *
+ * 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 ContextWindowUsageEventSchema = z.object({
+  type: z.literal("context_window_usage"),
+  conversationId: z.string(),
+  /** Prompt tokens the conversation's context currently occupies. */
+  tokens: z.number(),
+  /** Input-token ceiling of the resolved context window. */
+  maxTokens: z.number(),
+});
+
+export type ContextWindowUsageEvent = z.infer<
+  typeof ContextWindowUsageEventSchema
+>;

package/src/api/events/notification-intent.ts

@@ -23,9 +23,17 @@ export const NotificationIntentEventSchema = z.object({
   title: z.string(),
   body: z.string(),
   deliveryId: z.string().optional(),
+  correlationId: z.string().optional(),
   deepLinkMetadata: z.record(z.string(), z.unknown()).optional(),
   targetGuardianPrincipalId: z.string().optional(),
   silent: z.boolean().optional(),
+  /**
+   * True when the platform (APNs) channel accepted a remote push for
+   * this delivery, so native clients can avoid double-bannering.
+   */
+  remotePushDispatched: z.boolean().optional(),
+  /** Native platforms that accepted this remote push. */
+  remotePushPlatforms: z.array(z.enum(["ios", "android"])).optional(),
 });
 
 export type NotificationIntentEvent = z.infer<

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

@@ -0,0 +1,35 @@
+/**
+ * `ui_surface_pending` SSE event.
+ *
+ * Server → client notice that a `ui_show` call whose input is still streaming
+ * will produce a surface of `surfaceType`, so the client can hold a
+ * placeholder for it. Authoring a `visual` fragment is the longest input
+ * stream the model produces, and until the call closes there is nothing on
+ * screen at all: the `ui_show` chip is suppressed (the surface renders in its
+ * place) and the surface itself does not exist yet.
+ *
+ * The daemon emits this at most once per tool call, as soon as the
+ * accumulated tool input names a surface type worth a placeholder. It carries
+ * no input: the fragment is large and the client only needs to know that one
+ * is coming.
+ *
+ * `toolUseId` is the id of the producing `ui_show` call, the correlation key
+ * the client uses to retire the placeholder when the call resolves.
+ * `messageId` is the assistant row the call belongs to when the daemon has
+ * already opened one.
+ *
+ * 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 UISurfacePendingEventSchema = z.object({
+  type: z.literal("ui_surface_pending"),
+  conversationId: z.string(),
+  surfaceType: z.literal("visual"),
+  toolUseId: z.string(),
+  messageId: z.string().optional(),
+});
+
+export type UISurfacePendingEvent = z.infer<typeof UISurfacePendingEventSchema>;

package/src/api/index.ts

@@ -25,6 +25,7 @@ import { ConfirmationStateChangedEventSchema } from "./events/confirmation-state
 import { ContactRequestEventSchema } from "./events/contact-request.js";
 import { ContactsChangedEventSchema } from "./events/contacts-changed.js";
 import { ContextCompactedEventSchema } from "./events/context-compacted.js";
+import { ContextWindowUsageEventSchema } from "./events/context-window-usage.js";
 import { ConversationErrorEventSchema } from "./events/conversation-error.js";
 import { ConversationInferenceProfileUpdatedEventSchema } from "./events/conversation-inference-profile-updated.js";
 import { ConversationListInvalidatedEventSchema } from "./events/conversation-list-invalidated.js";
@@ -119,6 +120,7 @@ import { ToolUsePreviewStartEventSchema } from "./events/tool-use-preview-start.
 import { ToolUseStartEventSchema } from "./events/tool-use-start.js";
 import { UISurfaceCompleteEventSchema } from "./events/ui-surface-complete.js";
 import { UISurfaceDismissEventSchema } from "./events/ui-surface-dismiss.js";
+import { UISurfacePendingEventSchema } from "./events/ui-surface-pending.js";
 import { UISurfaceShowEventSchema } from "./events/ui-surface-show.js";
 import { UISurfaceUndoResultEventSchema } from "./events/ui-surface-undo-result.js";
 import { UISurfaceUpdateEventSchema } from "./events/ui-surface-update.js";
@@ -270,6 +272,10 @@ export {
   type ContextCompactedEvent,
   ContextCompactedEventSchema,
 } from "./events/context-compacted.js";
+export {
+  type ContextWindowUsageEvent,
+  ContextWindowUsageEventSchema,
+} from "./events/context-window-usage.js";
 export {
   type ConversationErrorCode,
   ConversationErrorCodeSchema,
@@ -607,6 +613,10 @@ export {
   type UISurfaceDismissEvent,
   UISurfaceDismissEventSchema,
 } from "./events/ui-surface-dismiss.js";
+export {
+  type UISurfacePendingEvent,
+  UISurfacePendingEventSchema,
+} from "./events/ui-surface-pending.js";
 export {
   type SurfaceAction,
   SurfaceActionSchema,
@@ -836,6 +846,8 @@ export {
   TableRowSchema,
   type TableSurfaceData,
   TableSurfaceDataSchema,
+  type VisualSurfaceData,
+  VisualSurfaceDataSchema,
   type WorkResultDiff,
   WorkResultDiffSchema,
   type WorkResultItem,
@@ -895,6 +907,7 @@ export const AssistantEventSchema = z.discriminatedUnion("type", [
   ContactRequestEventSchema,
   ContactsChangedEventSchema,
   ContextCompactedEventSchema,
+  ContextWindowUsageEventSchema,
   ConversationErrorEventSchema,
   ConversationInferenceProfileUpdatedEventSchema,
   ConversationListInvalidatedEventSchema,
@@ -973,6 +986,7 @@ export const AssistantEventSchema = z.discriminatedUnion("type", [
   ToolUseStartEventSchema,
   UISurfaceCompleteEventSchema,
   UISurfaceDismissEventSchema,
+  UISurfacePendingEventSchema,
   UISurfaceShowEventSchema,
   UISurfaceUndoResultEventSchema,
   UISurfaceUpdateEventSchema,

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

@@ -415,7 +415,14 @@ export type ConversationSurfaceBlock = z.infer<
   typeof ConversationSurfaceBlockSchema
 >;
 
-/** A vellum attachment projection (no provider analog). */
+/**
+ * A vellum attachment projection (no provider analog).
+ *
+ * The inlined `attachment` is a metadata-only positional reference:
+ * `data`/`thumbnailData` are never populated here. The payload ships once,
+ * on the message's flat `attachments` array (joinable by `attachment.id`),
+ * or on demand via the attachment content endpoint.
+ */
 export const ConversationAttachmentBlockSchema = z.object({
   type: z.literal("attachment"),
   attachment: ConversationMessageAttachmentSchema,
@@ -491,10 +498,13 @@ export const ConversationMessageSchema = z.object({
   /** Display timestamp as an ISO-8601 string. */
   timestamp: z.string(),
   /**
-   * Flat list of attachment metadata for the row. Not yet supersedable by
-   * `contentBlocks`: `renderHistoryContent` emits an `attachment` content
+   * Flat list of attachment metadata for the row, and the sole carrier of
+   * inline attachment payloads: image rows populate `data`/`thumbnailData`
+   * here, while the `attachment` blocks in `contentBlocks` stay metadata-only
+   * references joinable by id. Not supersedable by `contentBlocks` for a
+   * second reason: `renderHistoryContent` emits an `attachment` content
    * block only for file-block refs with an inline placement, so orphan rows
-   * (unmatched ids, count mismatch, no DB rows — see `alignAttachments`) ship
+   * (unmatched ids, count mismatch, no DB rows; see `alignAttachments`) ship
    * here alone. Kept non-deprecated until `contentBlocks` reaches attachment
    * parity, so clients that migrate off the positional arrays don't drop those
    * chips.
@@ -586,6 +596,17 @@ export const ConversationMessageSchema = z.object({
    *  system notices — no avatar, no persona bubble — and never group them
    *  with adjacent assistant turns. */
   systemCard: z.boolean().optional(),
+  /** Present when this assistant row is a daemon-persisted provider-failure
+   *  notice (`metadata.messageKind === "provider_error"`); clients may render
+   *  a themed card instead of a persona bubble. `code` is the stable
+   *  classified error code (e.g. `"PROVIDER_BILLING"`), `category` the
+   *  classified category (e.g. `"credits_exhausted"`). */
+  providerError: z
+    .object({
+      code: z.string().optional(),
+      category: z.string().optional(),
+    })
+    .optional(),
   slackMessage: ConversationSlackMessageSchema.optional(),
   /**
    * Queue state for a user message that is still waiting in the daemon's

package/src/api/surfaces.ts

@@ -54,6 +54,38 @@ export function coerceSurfaceDataRecord(
   return {};
 }
 
+/**
+ * Describe why a `data` payload the caller double-encoded as a JSON object or
+ * array literal could not be decoded, or null when it decoded fine.
+ *
+ * {@link coerceSurfaceDataRecord} collapses an undecodable string to `{}`, which
+ * every downstream shape check then reads as "no fields were sent". Callers pair
+ * the two so a rejection names the encoding failure instead of blaming whichever
+ * field happened to be looked up first.
+ *
+ * Scoped to strings that open with `{` or `[`: those are an object payload that
+ * lost a quote or a brace on the way through. A string that never resembled one
+ * (`"delete it?"`) is a different mistake, and the surface's own shape doc says
+ * more about it than a parse error would.
+ */
+export function describeSurfaceDataStringParseFailure(
+  value: unknown,
+): string | null {
+  if (typeof value !== "string") {
+    return null;
+  }
+  const trimmed = value.trimStart();
+  if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) {
+    return null;
+  }
+  try {
+    JSON.parse(value);
+    return null;
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+}
+
 /** Optional string that drops (rather than rejects on) a non-string value. */
 const tolerantString = () => z.string().optional().catch(undefined);
 
@@ -458,6 +490,59 @@ export const WorkResultSurfaceDataSchema = z.object({
 });
 export type WorkResultSurfaceData = z.infer<typeof WorkResultSurfaceDataSchema>;
 
+/**
+ * Inline visual: a self-contained html fragment rendered in a sandboxed
+ * frame. Model-invokable via `ui_show`, which validates the fragment (no
+ * external resources, design-token styling) before emitting it — see
+ * `tools/ui-surface/visual-validation.ts`.
+ */
+export const VisualSurfaceDataSchema = z.object({
+  /** The visual's markup. Load-bearing: empty renders a blank box. */
+  html: z.string().catch(""),
+  /** Preferred render height in px. */
+  height: tolerantNumber(),
+});
+export type VisualSurfaceData = z.infer<typeof VisualSurfaceDataSchema>;
+
+/**
+ * Bounds for the caller's initial height estimate, in CSS pixels. The maximum
+ * matches the client renderer's clamp (`visual-surface.tsx`), so an estimate
+ * the frame would clip never reaches the wire.
+ */
+const VISUAL_MIN_HEIGHT = 80;
+const VISUAL_MAX_HEIGHT = 1400;
+
+/**
+ * Normalize a visual `ui_show` payload: recover `html`/`height` the model
+ * placed at the top level of the tool input instead of nesting inside `data`,
+ * clamp the height estimate, then parse through the canonical schema. Shared
+ * by the tool's validation guard and the daemon resolver so both layers see
+ * the same fragment.
+ */
+export function normalizeVisualShowData(
+  input: Record<string, unknown>,
+  data: Record<string, unknown>,
+): VisualSurfaceData {
+  const normalized: Record<string, unknown> = { ...data };
+  if (typeof normalized.html !== "string" && typeof input.html === "string") {
+    normalized.html = input.html;
+  }
+  if (normalized.height == null && input.height != null) {
+    normalized.height = input.height;
+  }
+  const parsed = VisualSurfaceDataSchema.parse(normalized);
+  if (parsed.height === undefined || parsed.height <= 0) {
+    return { html: parsed.html };
+  }
+  return {
+    html: parsed.html,
+    height: Math.min(
+      VISUAL_MAX_HEIGHT,
+      Math.max(VISUAL_MIN_HEIGHT, Math.round(parsed.height)),
+    ),
+  };
+}
+
 // === Surface type registry ===
 
 export const SURFACE_TYPES = [
@@ -477,6 +562,7 @@ export const SURFACE_TYPES = [
   "work_result",
   "skill_card",
   "call_summary",
+  "visual",
 ] as const;
 
 export const SurfaceTypeSchema = z.enum(SURFACE_TYPES);
@@ -534,7 +620,8 @@ export type SurfaceData =
   | DynamicPageSurfaceData
   | FileUploadSurfaceData
   | DocumentPreviewSurfaceData
-  | WorkResultSurfaceData;
+  | WorkResultSurfaceData
+  | VisualSurfaceData;
 
 /**
  * Per-type `data` payload shapes, keyed by surface type. This is the
@@ -568,6 +655,7 @@ export interface SurfaceDataByType {
   work_result: WorkResultSurfaceData;
   skill_card: Record<string, unknown>;
   call_summary: Record<string, unknown>;
+  visual: VisualSurfaceData;
 }
 
 /** Any surface `data` payload, including the opaque (non-renderable) types. */
@@ -600,6 +688,7 @@ export const SURFACE_DATA_SCHEMAS: {
   work_result: WorkResultSurfaceDataSchema,
   skill_card: z.record(z.string(), z.unknown()),
   call_summary: z.record(z.string(), z.unknown()),
+  visual: VisualSurfaceDataSchema,
 };
 
 /**

package/src/approvals/guardian-card-withdrawal.ts

@@ -32,39 +32,16 @@ import {
   markSurfaceCompleted,
 } from "../daemon/conversation-surfaces.js";
 import { withdrawSlackApprovalCard } from "../messaging/providers/slack/withdraw.js";
+import { withdrawTelegramApprovalCard } from "../messaging/providers/telegram-bot/withdraw.js";
 import { approvalCardSurfaceId } from "../notifications/approval-card-data.js";
 import {
   type ApprovalAction,
-  isParkAction,
-  PARK_STATUS_LABEL,
+  resolveDecisionStatusWord,
 } from "../runtime/channel-approval-types.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<GuardianRequestStatus, string>> = {
-  approved: "Approved",
-  denied: "Denied",
-  expired: "Expired",
-  cancelled: "Cancelled",
-};
-
-/**
- * The completion-summary label for a resolved card. A `denied` status reached by
- * a park action reads as the neutral {@link PARK_STATUS_LABEL} rather than
- * "Denied" — a parked contact was neither trusted nor kept out.
- */
-function resolveStatusLabel(
-  status: GuardianRequestStatus,
-  decidedAction: ApprovalAction | undefined,
-): string {
-  if (status === "denied" && isParkAction(decidedAction)) {
-    return PARK_STATUS_LABEL;
-  }
-  return SURFACE_STATUS_LABELS[status] ?? "Resolved";
-}
-
 /** The request fields withdrawal reads — structural subset of the wire row. */
 export interface WithdrawableGuardianRequest {
   id: string;
@@ -92,10 +69,20 @@ export interface WithdrawGuardianCardsParams {
    * The action the guardian took, when the terminal status came from a decision
    * (omitted for the expiry sweep). A `denied` status can mean either a neutral
    * park (`leave_unverified`) or an active rejection (`block`/`reject`); the
-   * action disambiguates them so a park renders neutrally as
-   * {@link PARK_STATUS_LABEL} instead of "Denied".
+   * action disambiguates them so a park renders neutrally as the park label
+   * (see {@link resolveDecisionStatusWord}) instead of "Denied".
    */
   decidedAction?: ApprovalAction;
+  /**
+   * True when the deciding flow delivers the resolver's own guardian-facing
+   * reply on the origin channel (the resolver returned `guardianReplyText`).
+   * Telegram's quoted status reply is suppressed only when the origin chat is
+   * Telegram AND that richer reply is coming; most resolvers (tool grants,
+   * tool approvals, questions) reply to the requester, not the guardian, so
+   * without this flag the withdrawal's status reply is the only durable
+   * outcome the guardian's chat gets.
+   */
+  hasOriginGuardianReply?: boolean;
 }
 
 /**
@@ -105,7 +92,13 @@ export interface WithdrawGuardianCardsParams {
 export async function withdrawGuardianRequestCards(
   params: WithdrawGuardianCardsParams,
 ): Promise<void> {
-  const { request, status, originChannel, decidedAction } = params;
+  const {
+    request,
+    status,
+    originChannel,
+    decidedAction,
+    hasOriginGuardianReply,
+  } = params;
 
   let deliveries: GuardianRequestDeliveryWire[];
   try {
@@ -130,9 +123,17 @@ export async function withdrawGuardianRequestCards(
         );
       } else if (delivery.destinationChannel === "slack") {
         await withdrawSlackCard(request, delivery, status, decidedAction);
+      } else if (delivery.destinationChannel === "telegram") {
+        await withdrawTelegramCard(
+          delivery,
+          status,
+          originChannel,
+          decidedAction,
+          hasOriginGuardianReply ?? false,
+        );
       }
-      // 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
+      // WhatsApp direct delivery can't edit a message in place (it would
+      // post a new one), so its stale clicks are left to the existing
       // "already resolved" reply until in-place edit support lands.
     } catch (err) {
       log.warn(
@@ -175,7 +176,7 @@ function withdrawVellumCard(
   if (!surfaceId) {
     return;
   }
-  const summary = resolveStatusLabel(status, decidedAction);
+  const summary = resolveDecisionStatusWord(status, decidedAction);
   if (originChannel === "vellum") {
     markSurfaceCompleted(
       { conversationId: delivery.destinationConversationId },
@@ -214,3 +215,37 @@ async function withdrawSlackCard(
     decidedAtMs: request.updatedAt,
   });
 }
+
+/**
+ * Withdraw the Telegram approval card: remove its inline keyboard in place
+ * and post a silent reply quoting the card with the terminal outcome.
+ * Telegram bots cannot re-read a message, so unlike Slack the outcome rides
+ * a quoted reply rather than an in-message edit; the card's own text is left
+ * untouched for the audit trail.
+ *
+ * The status reply is suppressed only when the decision was made on Telegram
+ * AND its flow delivers the resolver's own guardian-facing reply there
+ * (`hasOriginGuardianReply`), where a second notice would read as a
+ * duplicate. Most resolvers reply to the requester, not the guardian, so a
+ * Telegram-origin decision usually still needs this reply as its durable
+ * outcome. No-ops when the channel-native message id was not captured at
+ * delivery time.
+ */
+async function withdrawTelegramCard(
+  delivery: GuardianRequestDeliveryWire,
+  status: GuardianRequestStatus,
+  originChannel: string | undefined,
+  decidedAction: ApprovalAction | undefined,
+  hasOriginGuardianReply: boolean,
+): Promise<void> {
+  if (!delivery.destinationChatId || !delivery.destinationMessageId) {
+    return;
+  }
+  await withdrawTelegramApprovalCard({
+    chatId: delivery.destinationChatId,
+    messageId: delivery.destinationMessageId,
+    status,
+    ...(decidedAction ? { decidedAction } : {}),
+    postStatusReply: !(originChannel === "telegram" && hasOriginGuardianReply),
+  });
+}

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

@@ -532,6 +532,10 @@ export async function applyGuardianDecision(
     status: targetStatus,
     originChannel: actorContext.channel,
     decidedAction: cardAction,
+    // Tells the Telegram projection whether the origin chat is about to get
+    // the resolver's own guardian-facing reply (delivered by our caller), so
+    // it can skip its quoted status reply instead of duplicating it.
+    hasOriginGuardianReply: Boolean(resolverReplyText),
   }).catch((err) => {
     log.warn(
       { err, requestId },