@vellumai/assistant 0.8.2 → 0.8.3

package/src/context/compactor.ts

@@ -439,6 +439,44 @@ function resolveTailStartIndex(
   return null;
 }
 
+/**
+ * Walk a model-chosen tail index backward until it lands on a user message
+ * that does not contain client-side `tool_result` blocks. Prevents the
+ * orphan-`tool_result` failure where the matching assistant `tool_use` sits
+ * in the discarded prefix and Anthropic rejects the next call with
+ * `unexpected tool_use_id found in tool_result blocks`.
+ *
+ * Walking back (rather than forward) preserves the recent context the model
+ * deliberately chose to keep; the tail just expands by the few messages
+ * needed to re-anchor the orphaned `tool_result` against its `tool_use`.
+ *
+ * Returns 0 when the walk falls off the front — the caller treats this as
+ * "nothing to compact" via the existing `tailIndex === 0` branch.
+ *
+ * Only `type === "tool_result"` blocks count. Server-side tools
+ * (`server_tool_use` / `web_search_tool_result`) are self-paired inside an
+ * assistant message and never trigger an adjustment.
+ */
+export function adjustTailIndexForToolPairing(
+  messages: Message[],
+  tailIndex: number,
+): number {
+  let k = tailIndex;
+  while (k > 0) {
+    const m = messages[k];
+    if (
+      m.role === "user" &&
+      // guard:allow-tool-result-only — server-side web_search_tool_result is
+      // self-paired inside its assistant message and never spans user turns.
+      !m.content.some((block) => block.type === "tool_result")
+    ) {
+      return k;
+    }
+    k--;
+  }
+  return 0;
+}
+
 // ---------------------------------------------------------------------------
 // Retained-image hydration
 // ---------------------------------------------------------------------------
@@ -655,8 +693,12 @@ export async function runAssistantDrivenCompaction(
   }
 
   const timestamps = buildTimestampIndex(args.messages);
-  const tailIndex = resolveTailStartIndex(args.messages, timestamps, parsed);
-  if (tailIndex == null) {
+  const resolvedTailIndex = resolveTailStartIndex(
+    args.messages,
+    timestamps,
+    parsed,
+  );
+  if (resolvedTailIndex == null) {
     log.warn(
       {
         timestamp: parsed.tailStartTimestamp,
@@ -680,6 +722,22 @@ export async function runAssistantDrivenCompaction(
     };
   }
 
+  const tailIndex = adjustTailIndexForToolPairing(
+    args.messages,
+    resolvedTailIndex,
+  );
+  if (tailIndex !== resolvedTailIndex) {
+    log.info(
+      {
+        conversationId: args.conversationId,
+        originalTailIndex: resolvedTailIndex,
+        tailIndex,
+        walkedBy: resolvedTailIndex - tailIndex,
+      },
+      "Adjusted compaction tail backward to preserve tool_use/tool_result pairing",
+    );
+  }
+
   if (tailIndex === 0) {
     return {
       ...emptyResult(
@@ -762,6 +820,9 @@ export async function runAssistantDrivenCompaction(
       compactedMessages: compactableMessages.length,
       compactedPersistedMessages,
       tailIndex,
+      ...(tailIndex !== resolvedTailIndex
+        ? { originalTailIndex: resolvedTailIndex }
+        : {}),
       retainedImages: resolved.length,
       summaryChars: summaryText.length,
     },
@@ -885,10 +946,12 @@ export async function runEmergencyCompaction(
 
   const splitIndex = findLastToolPairStart(args.messages);
   if (splitIndex == null || splitIndex === 0) {
-    log.info(
-      "Emergency compaction: no tool pair found — falling through",
+    log.info("Emergency compaction: no tool pair found — falling through");
+    return emptyResult(
+      args,
+      thresholdTokens,
+      "no tool pair for emergency split",
     );
-    return emptyResult(args, thresholdTokens, "no tool pair for emergency split");
   }
 
   const keptTail = stripInjectionsForCompaction(
@@ -904,8 +967,7 @@ export async function runEmergencyCompaction(
   const prefixBudget = args.maxInputTokens - instructionBudget - outputBudget;
 
   let prefixEstimate = estimatePromptTokens(prefix, args.systemPrompt, {
-    providerName:
-      args.provider.tokenEstimationProvider ?? args.provider.name,
+    providerName: args.provider.tokenEstimationProvider ?? args.provider.name,
   });
 
   if (prefixEstimate > prefixBudget && prefix.length > 1) {
@@ -920,10 +982,7 @@ export async function runEmergencyCompaction(
     // Drop messages from the front until we fit. Keep at least the first
     // message (may be an existing summary) and try to preserve recent context.
     let dropCount = 0;
-    while (
-      prefixEstimate > prefixBudget &&
-      dropCount < prefix.length - 1
-    ) {
+    while (prefixEstimate > prefixBudget && dropCount < prefix.length - 1) {
       dropCount++;
       const truncated = prefix.slice(dropCount);
       prefixEstimate = estimatePromptTokens(truncated, args.systemPrompt, {
@@ -1015,7 +1074,8 @@ export async function runEmergencyCompaction(
       compactedMessages: compactedCount,
       keptTailMessages: keptTail.length,
       summaryChars: summaryText.length,
-      prefixTruncated: prefix[0]?.content?.[0]?.type === "text" &&
+      prefixTruncated:
+        prefix[0]?.content?.[0]?.type === "text" &&
         (prefix[0].content[0] as { text: string }).text.includes("truncated"),
     },
     "Applied emergency mid-turn compaction",

package/src/context/token-estimator.ts

@@ -33,18 +33,24 @@ const OTHER_BLOCK_TOKENS = 16;
 const SYSTEM_PROMPT_OVERHEAD_TOKENS = 8;
 const GEMINI_INLINE_FILE_MIME_TYPES = new Set(["application/pdf"]);
 
-// Anthropic scales images to fit within 1568x1568 maintaining aspect ratio,
-// then charges ~(width * height) / 750 tokens.
-const ANTHROPIC_IMAGE_MAX_DIMENSION = 1568;
-// Anthropic caps images at ~1.2 megapixels in addition to the 1568px dimension limit.
-// Images exceeding this are further scaled down. The docs state images above ~1,600 tokens
-// are resized. 1,200,000 / 750 = 1,600 tokens, matching the documented threshold.
-// Reference table (max sizes that won't be resized):
+// Dimension-based image token estimate, used as a universal default for every
+// provider. The formula and constants below come from Anthropic's published
+// vision spec — scale to a 1568x1568 bounding box, then charge
+// ~(width * height) / 750 tokens, with a ~1.2-megapixel cap that lands at
+// ~1,600 tokens per image. Reference table (max sizes that won't be resized):
 //   1:1 → 1092x1092 (~1,590 tokens)   1:2 → 784x1568 (~1,639 tokens)
 // See: https://platform.claude.com/docs/en/build-with-claude/vision#evaluate-image-size
-const ANTHROPIC_IMAGE_MAX_PIXELS = 1_200_000;
-const ANTHROPIC_IMAGE_TOKENS_PER_PIXEL = 1 / 750;
-const ANTHROPIC_IMAGE_MAX_TOKENS = 1_600;
+//
+// Other multimodal providers (OpenAI/GPT-4V tile pricing, Moonshot/Kimi,
+// Gemini fixed-cost, OpenRouter pass-through) price differently in detail,
+// but every published rate lands in the same hundreds-to-low-thousands range
+// per image. Using this formula as the default gets compaction within ~2-3x
+// of reality instead of the ~30-100x over-counting produced by treating the
+// raw base64 payload as if it were text.
+const IMAGE_MAX_DIMENSION = 1568;
+const IMAGE_MAX_PIXELS = 1_200_000;
+const IMAGE_TOKENS_PER_PIXEL = 1 / 750;
+const IMAGE_MAX_TOKENS = 1_600;
 
 // Anthropic renders each PDF page as an image (~1,568 tokens at standard
 // resolution) plus any extracted text. Typical PDF pages are 50-150 KB.
@@ -103,45 +109,37 @@ function estimateFileDataTokens(
   return 0;
 }
 
-function estimateAnthropicImageTokens(width: number, height: number): number {
+function estimateImageTokensByDimensions(
+  width: number,
+  height: number,
+): number {
   // Step 1: Scale to fit within 1568px bounding box
-  const dimScale = Math.min(
-    1,
-    ANTHROPIC_IMAGE_MAX_DIMENSION / Math.max(width, height),
-  );
+  const dimScale = Math.min(1, IMAGE_MAX_DIMENSION / Math.max(width, height));
   let scaledWidth = Math.round(width * dimScale);
   let scaledHeight = Math.round(height * dimScale);
 
   // Step 2: Scale further if exceeds megapixel budget
   const pixels = scaledWidth * scaledHeight;
-  if (pixels > ANTHROPIC_IMAGE_MAX_PIXELS) {
-    const mpScale = Math.sqrt(ANTHROPIC_IMAGE_MAX_PIXELS / pixels);
+  if (pixels > IMAGE_MAX_PIXELS) {
+    const mpScale = Math.sqrt(IMAGE_MAX_PIXELS / pixels);
     scaledWidth = Math.round(scaledWidth * mpScale);
     scaledHeight = Math.round(scaledHeight * mpScale);
   }
 
-  return Math.ceil(
-    scaledWidth * scaledHeight * ANTHROPIC_IMAGE_TOKENS_PER_PIXEL,
-  );
+  return Math.ceil(scaledWidth * scaledHeight * IMAGE_TOKENS_PER_PIXEL);
 }
 
 function estimateImageTokens(
   block: Extract<ContentBlock, { type: "image" }>,
-  options?: TokenEstimatorOptions,
 ): number {
-  if (options?.providerName === "anthropic") {
-    const dims = parseImageDimensions(
-      block.source.data,
-      block.source.media_type,
-    );
-    if (dims) {
-      return estimateAnthropicImageTokens(dims.width, dims.height);
-    }
-    // Fallback: if dimensions can't be parsed, use Anthropic's max
-    return ANTHROPIC_IMAGE_MAX_TOKENS;
+  const dims = parseImageDimensions(block.source.data, block.source.media_type);
+  if (dims) {
+    return estimateImageTokensByDimensions(dims.width, dims.height);
   }
-  // Non-Anthropic: keep existing base64-size heuristic
-  return estimateTextTokens(block.source.data);
+  // Dimensions unparseable (corrupt header, exotic format): use the per-image
+  // cap rather than the raw base64 length, which over-counts by 30-100x for
+  // non-Anthropic providers and trips spurious compaction.
+  return IMAGE_MAX_TOKENS;
 }
 
 export function estimateContentBlockTokens(
@@ -188,7 +186,7 @@ export function estimateContentBlockTokens(
       return (
         IMAGE_BLOCK_OVERHEAD_TOKENS +
         estimateTextTokens(block.source.media_type) +
-        estimateImageTokens(block, options)
+        estimateImageTokens(block)
       );
     case "file":
       return (

package/src/daemon/__tests__/conversation-lifecycle-auto-analyze.test.ts

@@ -97,7 +97,6 @@ mock.module("../../memory/auto-analysis-enqueue.js", () => ({
   },
 }));
 
-let memoryRetroEnabled = false;
 const memoryRetroCalls: Array<{
   conversationId: string;
   trigger: string;
@@ -108,7 +107,6 @@ mock.module("../../memory/memory-retrospective-enqueue.js", () => ({
     conversationId: string;
     trigger: string;
   }) => {
-    if (!memoryRetroEnabled) return;
     memoryRetroCalls.push(args);
   },
   // Also export sibling functions other modules import from this file, so
@@ -205,7 +203,6 @@ describe("disposeConversation — auto-analysis enqueue", () => {
     autoAnalyzeCalls.length = 0;
     memoryRetroCalls.length = 0;
     autoAnalyzeEnabled = true;
-    memoryRetroEnabled = false;
     autoAnalysisConversations.clear();
     v2Enabled = false;
   });
@@ -390,13 +387,11 @@ describe("disposeConversation — memory-retrospective lifecycle safety net", ()
     autoAnalyzeCalls.length = 0;
     memoryRetroCalls.length = 0;
     autoAnalyzeEnabled = false;
-    memoryRetroEnabled = false;
     autoAnalysisConversations.clear();
     v2Enabled = false;
   });
 
-  test("guardian conversation + flag on — enqueues memory-retrospective with trigger 'lifecycle'", () => {
-    memoryRetroEnabled = true;
+  test("guardian conversation — enqueues memory-retrospective with trigger 'lifecycle'", () => {
     const ctx = makeDisposeContext({
       conversationId: "conv-retro",
       trustClass: "guardian",
@@ -411,20 +406,7 @@ describe("disposeConversation — memory-retrospective lifecycle safety net", ()
     });
   });
 
-  test("flag off — no memory-retrospective enqueue", () => {
-    memoryRetroEnabled = false;
-    const ctx = makeDisposeContext({
-      conversationId: "conv-retro-off",
-      trustClass: "guardian",
-    });
-
-    disposeConversation(ctx);
-
-    expect(memoryRetroCalls).toHaveLength(0);
-  });
-
-  test("untrusted actor — no memory-retrospective enqueue even when flag is on", () => {
-    memoryRetroEnabled = true;
+  test("untrusted actor — no memory-retrospective enqueue", () => {
     const ctx = makeDisposeContext({
       conversationId: "conv-retro-untrusted",
       trustClass: "unknown",
@@ -443,8 +425,7 @@ describe("disposeConversation — memory-retrospective lifecycle safety net", ()
   // outside the `!isAutoAnalysis` guard, so it fired even for auto-analysis
   // conversations. Mirrors the indexer-time gate in `indexer.ts` and
   // matches the existing graph_extract recursion-guard semantics.
-  test("auto-analysis conversation — does NOT enqueue memory-retrospective even with flag on", () => {
-    memoryRetroEnabled = true;
+  test("auto-analysis conversation — does NOT enqueue memory-retrospective", () => {
     autoAnalysisConversations.add("conv-auto-retro");
     const ctx = makeDisposeContext({
       conversationId: "conv-auto-retro",

package/src/daemon/conversation-agent-loop-handlers.ts

@@ -23,7 +23,9 @@ import {
 } from "../memory/conversation-crud.js";
 import {
   backfillMessageIdOnLogs,
+  buildProviderErrorResponsePayload,
   recordRequestLog,
+  setAgentLoopExitReasonOnLatestLog,
 } from "../memory/llm-request-log-store.js";
 import { backfillMemoryRecallLogMessageId } from "../memory/memory-recall-log-store.js";
 import { backfillMemoryV2ActivationMessageId } from "../memory/memory-v2-activation-log-store.js";
@@ -1166,6 +1168,52 @@ function handleUsage(
   state.llmCallStartedEmitted = false;
 }
 
+/**
+ * Persist a provider-rejected LLM call as an `llm_request_logs` row.
+ *
+ * Mirrors `handleUsage`'s recording side-effect for the failure path: the
+ * loop only reaches the success branch (and emits `usage`) when the
+ * provider returns a response, so without this handler a rejected call
+ * leaves nothing in the inspector — only a pino line saying "The AI
+ * provider rejected the request." The row's `messageId` is left null
+ * here and linked via one of two backfill paths, depending on how the
+ * turn unwinds:
+ *
+ *   - Multi-call turn where a later call also produces a real assistant
+ *     response: `handleMessageComplete` -> `backfillMessageIdOnLogs`
+ *     sweeps this row with the rest, same as a successful-call row.
+ *   - Pure provider-failure turn (no real assistant response): the
+ *     synthetic error-message branch in `conversation-agent-loop.ts`
+ *     persists a stand-in assistant message and calls
+ *     `backfillMessageIdOnLogs` itself, since `message_complete` is
+ *     never emitted on that path. Closing the orphan window inside the
+ *     same synchronous turn prevents a later turn's sweep from wrong-
+ *     attaching this row to an unrelated assistant message.
+ *
+ * Failures inside the recording itself are logged and swallowed — this
+ * mirrors `handleUsage`'s non-fatal stance so a DB hiccup never escalates
+ * a provider rejection into a dispatcher-level throw.
+ */
+function handleProviderError(
+  deps: EventHandlerDeps,
+  event: Extract<AgentEvent, { type: "provider_error" }>,
+): void {
+  try {
+    recordRequestLog(
+      deps.ctx.conversationId,
+      JSON.stringify(event.rawRequest),
+      JSON.stringify(buildProviderErrorResponsePayload(event.error)),
+      undefined,
+      event.actualProvider,
+    );
+  } catch (err) {
+    deps.rlog.warn(
+      { err },
+      "Failed to persist provider-error LLM request log (non-fatal)",
+    );
+  }
+}
+
 // ── Dispatcher ───────────────────────────────────────────────────────
 
 /** Routes an AgentEvent to the appropriate handler. */
@@ -1254,12 +1302,42 @@ export async function dispatchAgentEvent(
       case "error":
         handleError(state, deps, event);
         break;
+      case "provider_error":
+        handleProviderError(deps, event);
+        break;
       case "message_complete":
         await handleMessageComplete(state, deps, event);
         break;
       case "usage":
         handleUsage(state, deps, event);
         break;
+      case "agent_loop_exit":
+        // Stamp the exit reason onto the most-recent llm_request_logs
+        // row for this conversation. The final `usage` event of the run
+        // lands its row immediately before this event arrives (in the
+        // normal-dispatch path; the wake path handles ordering
+        // explicitly via `pendingExitReason`).
+        //
+        // Wrapped in try/catch so a DB hiccup here can't tear down the
+        // surrounding dispatch — the outer try/catch already swallows
+        // errors, but logging here gives the diagnosis hook a clear
+        // attribution to the exit handler specifically.
+        try {
+          setAgentLoopExitReasonOnLatestLog(
+            deps.ctx.conversationId,
+            event.reason,
+          );
+        } catch (err) {
+          log.warn(
+            {
+              err,
+              conversationId: deps.ctx.conversationId,
+              reason: event.reason,
+            },
+            "Failed to persist agent_loop_exit_reason (non-fatal)",
+          );
+        }
+        break;
     }
   } catch (err) {
     log.error(

package/src/daemon/conversation-agent-loop.ts

@@ -71,7 +71,9 @@ import {
   isReplaceableTitle,
   queueRegenerateConversationTitle,
 } from "../memory/conversation-title-service.js";
+import { isBackgroundConversationType } from "../memory/conversation-types.js";
 import type { ConversationGraphMemory } from "../memory/graph/conversation-graph-memory.js";
+import { backfillMessageIdOnLogs } from "../memory/llm-request-log-store.js";
 import { recordMemoryRecallLog } from "../memory/memory-recall-log-store.js";
 import { enqueueMemoryRetrospectiveOnCompaction } from "../memory/memory-retrospective-enqueue.js";
 import { PKB_WORKSPACE_SCOPE } from "../memory/pkb/types.js";
@@ -109,6 +111,7 @@ import type {
   MemoryResult,
   OverflowReduceArgs,
   OverflowReduceResult,
+  PersistAddResult,
   PersistArgs,
   PersistResult,
   TurnContext as PluginTurnContext,
@@ -1616,6 +1619,9 @@ export async function runAgentLoopImpl(
       transportHints: ctx.transportHints ?? null,
       slackRuntimeContextNotice: ctx.slackRuntimeContextNotice ?? null,
       isNonInteractive: !isInteractiveResolved,
+      isBackgroundConversation: isBackgroundConversationType(
+        turnStartConversation?.conversationType,
+      ),
       subagentStatusBlock,
       slackChronologicalMessages,
       slackActiveThreadFocusBlock,
@@ -2942,7 +2948,7 @@ export async function runAgentLoopImpl(
       const errorAssistantMessage = createAssistantMessage(
         state.providerErrorUserMessage,
       );
-      await runPipeline<PersistArgs, PersistResult>(
+      const errorPersistResult = (await runPipeline<PersistArgs, PersistResult>(
         "persistence",
         getMiddlewaresFor("persistence"),
         defaultPersistenceTerminal,
@@ -2955,9 +2961,30 @@ export async function runAgentLoopImpl(
         },
         buildPluginTurnContext(ctx, reqId),
         DEFAULT_TIMEOUTS.persistence,
-      );
+      )) as PersistAddResult;
       persistedErrorAssistantMessage = true;
       newMessages.push(errorAssistantMessage);
+      // Pipe the just-assigned message id into any orphaned LLM request log
+      // row(s) for this turn. The success path links rows via
+      // `handleMessageComplete` -> `backfillMessageIdOnLogs`, but provider-
+      // failure turns never fire `message_complete` (the synthetic assistant
+      // message is persisted directly above), so without this call the rows
+      // from `handleProviderError` stay with `message_id IS NULL` and a
+      // later turn's backfill sweep would wrong-attach them to that turn's
+      // assistant message. Scope is per-conversation, so concurrent runs on
+      // other conversations cannot collide. Non-fatal — a DB hiccup must
+      // not escalate a provider rejection into a turn-level throw.
+      try {
+        backfillMessageIdOnLogs(
+          ctx.conversationId,
+          errorPersistResult.message.id,
+        );
+      } catch (err) {
+        rlog.warn(
+          { err },
+          "Failed to backfill message_id on provider-error LLM request logs (non-fatal)",
+        );
+      }
       // Do NOT send assistant_text_delta here — handleProviderError already
       // emitted a conversation_error event for this same error text, and the
       // client renders it as an InlineChatErrorAlert. Sending a text delta

package/src/daemon/conversation-runtime-assembly.ts

@@ -1652,6 +1652,7 @@ const RUNTIME_INJECTION_PREFIXES = [
   "<interface_turn_context>", // backward-compat: strip legacy separate interface blocks
   // NOTE: <turn_context> is intentionally NOT stripped — unified turn context
   // blocks persist in history so the assistant retains temporal/actor grounding.
+  "<background_turn>",
   "<memory_context __injected>",
   "<memory_context>", // backward-compat: strip legacy blocks from pre-__injected history
   // The static `memory-v2-static` block (opens `<memory>\n…`) IS stripped
@@ -1966,6 +1967,13 @@ export interface RuntimeInjectionOptions {
   nowScratchpad?: string | null;
   subagentStatusBlock?: string | null;
   isNonInteractive?: boolean;
+  /**
+   * True when the active conversation's type is "background" or "scheduled".
+   * Forwarded to {@link TurnInjectionInputs.isBackgroundConversation} so the
+   * `background-turn` injector can wrap the tail user message with the
+   * configured reminder.
+   */
+  isBackgroundConversation?: boolean;
   transportHints?: string[] | null;
   slackRuntimeContextNotice?: string | null;
   /**
@@ -2056,6 +2064,7 @@ function buildTurnInjectionInputs(
     voiceCallControlPrompt: options.voiceCallControlPrompt,
     transportHints: options.transportHints,
     isNonInteractive: options.isNonInteractive,
+    isBackgroundConversation: options.isBackgroundConversation,
     activeDocuments: options.activeDocuments,
   };
 }

package/src/daemon/conversation.ts

@@ -54,7 +54,6 @@ import {
   getConversationOriginChannel,
   getConversationOverrideProfileFromRow,
 } from "../memory/conversation-crud.js";
-import { isBackgroundConversationType } from "../memory/conversation-types.js";
 import { ConversationGraphMemory } from "../memory/graph/conversation-graph-memory.js";
 import { shouldExposePersonalMemory } from "../memory/v2/static-context.js";
 import { PermissionPrompter } from "../permissions/prompter.js";
@@ -489,9 +488,6 @@ export class Conversation {
                 channelPersona: persona.channelPersona,
                 userSlug: persona.userSlug,
                 onboardingContext: this.getOnboardingContext(),
-                isBackgroundConversation: isBackgroundConversationType(
-                  getConversation(this.conversationId)?.conversationType,
-                ),
               });
             })(),
       };
@@ -583,9 +579,6 @@ export class Conversation {
             channelPersona: persona.channelPersona,
             userSlug: persona.userSlug,
             onboardingContext: this.getOnboardingContext(),
-            isBackgroundConversation: isBackgroundConversationType(
-              getConversation(this.conversationId)?.conversationType,
-            ),
           });
         })();
     const tools = buildToolDefinitions();

package/src/daemon/date-context.ts

@@ -326,6 +326,46 @@ function formatLocalDate(date: Date, timeZone: string): string {
   ).padStart(2, "0")}`;
 }
 
+const localTimestampFormatterCache = new Map<string, Intl.DateTimeFormat>();
+
+function getLocalTimestampFormatter(timeZone: string): Intl.DateTimeFormat {
+  let fmt = localTimestampFormatterCache.get(timeZone);
+  if (!fmt) {
+    fmt = new Intl.DateTimeFormat("en-CA", {
+      timeZone,
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+      hour: "2-digit",
+      minute: "2-digit",
+      second: "2-digit",
+      hourCycle: "h23",
+    });
+    localTimestampFormatterCache.set(timeZone, fmt);
+  }
+  return fmt;
+}
+
+/**
+ * Format an epoch-millis instant as `YYYY-MM-DD HH:MM:SS` in the given
+ * IANA timezone. When `timeZone` is omitted or `"UTC"`, falls back to a
+ * pure-UTC `toISOString` slice so callers can opt in incrementally.
+ *
+ * The internal `Intl.DateTimeFormat` is memoized by `timeZone` because
+ * constructing it is ~1ms in V8 — material when rendering long transcripts.
+ */
+export function formatLocalTimestamp(ms: number, timeZone?: string): string {
+  if (!timeZone || timeZone === "UTC") {
+    return new Date(ms).toISOString().replace("T", " ").slice(0, 19);
+  }
+  const parts = getLocalTimestampFormatter(timeZone).formatToParts(
+    new Date(ms),
+  );
+  const v: Record<string, string> = {};
+  for (const p of parts) v[p.type] = p.value;
+  return `${v.year}-${v.month}-${v.day} ${v.hour}:${v.minute}:${v.second}`;
+}
+
 export function resolveTurnTimezoneContext(
   options: TemporalContextOptions = {},
 ): TurnTimezoneContext {