@animalabs/connectome-host 0.3.5 → 0.3.8

package/src/modules/web-ui-module.ts

@@ -41,6 +41,7 @@ import { createHash, timingSafeEqual } from 'node:crypto';
 import type { Recipe } from '../recipe.js';
 import type { SessionManager } from '../session-manager.js';
 import type { BranchState } from '../commands.js';
+import type { CallLedger } from '../call-ledger.js';
 import { handleCommand } from '../commands.js';
 import { AgentTreeReducer, type AgentTreeSnapshot } from '../state/agent-tree-reducer.js';
 import { FleetTreeAggregator } from '../state/fleet-tree-aggregator.js';
@@ -54,6 +55,7 @@ import {
   type WelcomeMessageEntry,
   type RequestHistoryMessage,
   type TokenUsage,
+  type CallLedgerSnapshot,
   type McplListMessage,
   type LessonsListMessage,
 } from '../web/protocol.js';
@@ -128,6 +130,8 @@ export interface WebUiModuleConfig {
    * scope mask. With no grants the webui behaves exactly as before.
    */
   observersPath?: string;
+  /** Content-free recent provider-call ledger for spend/cache diagnostics. */
+  callLedger?: CallLedger;
 }
 
 /** Data stashed on the Bun WS upgrade. */
@@ -389,6 +393,9 @@ interface SharedServerState {
    *  every usage:updated event so the welcome and live UsageMessage frames
    *  carry consistent values. */
   latestPerAgentCost: import('../web/protocol.js').PerAgentCost[];
+  /** Recent per-call cache diagnostics, updated directly by the adapter. */
+  latestCallLedger?: CallLedgerSnapshot;
+  callLedgerDetacher: (() => void) | null;
   /** Currently-bound app, refreshed on every setApp() call. WS handlers read
    *  from here so the singleton always points at the live framework regardless
    *  of which WebUiModule instance is "active". */
@@ -464,6 +471,8 @@ export class WebUiModule implements Module {
       parentUsage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
       childUsage: new Map(),
       latestPerAgentCost: [],
+      latestCallLedger: this.config.callLedger?.snapshot(),
+      callLedgerDetacher: null,
       pendingFleetRequests: new Map(),
       childRecipeCache: new Map(),
       app: null,
@@ -495,6 +504,19 @@ export class WebUiModule implements Module {
     }
     sharedServer = state;
 
+    // Provider calls include auxiliary compression requests that never emit a
+    // framework usage trace, so subscribe at the adapter ledger itself. This
+    // keeps the panel live for both conversational and memory-maintenance
+    // calls without polling the JSONL log.
+    state.callLedgerDetacher = this.config.callLedger?.onUpdate((ledger) => {
+      state.latestCallLedger = ledger;
+      const msg: WebUiServerMessage = { type: 'call-ledger', ledger };
+      for (const client of state.clients.values()) {
+        if (!client.welcomed) continue;
+        if (client.scopes === null || client.scopes.has('health')) this.send(client, msg);
+      }
+    }) ?? null;
+
     console.log(`[webui] listening on http://${host}:${boundPort}`);
   }
 
@@ -961,8 +983,14 @@ export class WebUiModule implements Module {
       // `new WebSocket(...)` the way they do on fetch, so without an
       // explicit check, any tab the operator opens could connect here.
       if (!this.checkOrigin(req)) return new Response('Forbidden', { status: 403 });
-      const basicOk = this.checkAuth(req);
-      // Without basic auth the upgrade is allowed only when observer grants
+      // Full authority = basic auth OR a full session cookie (minted by
+      // /auth/basic). The cookie path exists because browsers reliably send
+      // cookies on WS upgrades but Chrome does NOT send cached basic-auth
+      // credentials — without it, password sign-in bounced back to the
+      // observer gate in a loop.
+      const wsSession = sharedServer!.observerSessions.lookup(sessionTokenFromRequest(req));
+      const basicOk = this.checkAuth(req) || (wsSession?.full ?? false);
+      // Without full auth the upgrade is allowed only when observer grants
       // exist — and then NOTHING is sent until a signed observer-hello
       // verifies (in-band auth; see onWsOpen/onWsMessage).
       if (!basicOk && !observersActive) return this.unauthorized();
@@ -980,19 +1008,29 @@ export class WebUiModule implements Module {
     // when observers are active the static app shell is public — it carries
     // no data, and key-only devices must be able to load the SPA to
     // authenticate at all.
-    const basicOk = this.checkAuth(req);
-    const sessionScopes = basicOk
-      ? null
-      : sharedServer!.observerSessions.lookup(sessionTokenFromRequest(req));
+    const session = sharedServer!.observerSessions.lookup(sessionTokenFromRequest(req));
+    const basicOk = this.checkAuth(req) || (session?.full ?? false);
+    const sessionScopes = basicOk ? null : session?.scopes ?? null;
     const httpAllowed = (scope: ObserverScope): boolean =>
       basicOk || (sessionScopes?.has(scope) ?? false);
     // /auth/basic: deliberate basic-auth challenge point. fetch() never
     // triggers the browser's native credential prompt, but a top-level
     // navigation here does — the SPA's "sign in with password" fallback for
-    // devices without an observer grant. Once credentials are cached for
-    // the realm, the WS upgrade carries them and the client is 'full'.
+    // devices without an observer grant. On success it mints a FULL session
+    // cookie: the subsequent WS upgrade authenticates via that cookie
+    // (browsers send cookies on upgrades; Chrome does not send cached basic
+    // credentials, which used to loop users back to the gate).
     if (url.pathname === '/auth/basic') {
-      if (basicOk) return new Response(null, { status: 302, headers: { location: '/' } });
+      if (basicOk) {
+        const token = sharedServer!.observerSessions.mint(new Set(), { full: true });
+        return new Response(null, {
+          status: 302,
+          headers: {
+            location: '/',
+            'set-cookie': `fkm_obs=${token}; Path=/; HttpOnly; SameSite=Lax; Max-Age=${12 * 3600}`,
+          },
+        });
+      }
       return this.unauthorized();
     }
     const isStatic = !url.pathname.startsWith('/debug/')
@@ -1055,7 +1093,44 @@ export class WebUiModule implements Module {
       if (typeof fw.healthSnapshot !== 'function') {
         return Response.json({ error: 'framework lacks healthSnapshot()' }, { status: 501 });
       }
-      return Response.json(fw.healthSnapshot());
+      const snapshot = fw.healthSnapshot();
+      // Compression quarantine is a guaranteed-eventual-outage state (raw
+      // spans accumulate until the picker cannot fit the window). Surface it
+      // here so the fleet hub and connectome-doctor can alarm on it — it
+      // must never be observable only in agent.log.
+      try {
+        const quarantine: Record<string, unknown> = {};
+        for (const agent of app.framework.getAllAgents()) {
+          const strategy = (agent.getContextManager() as unknown as {
+            getStrategy?: () => { getCompressionQuarantineStatus?: () => unknown };
+          }).getStrategy?.();
+          const status = strategy?.getCompressionQuarantineStatus?.();
+          if (status) quarantine[(agent as unknown as { name: string }).name] = status;
+        }
+        (snapshot as Record<string, unknown>).compressionQuarantine = quarantine;
+      } catch {
+        // Health reads never throw.
+      }
+      // Per-agent runtime settings (context budget, tail, transition pace +
+      // convergence state) — the same numbers `agent_settings get` returns,
+      // exposed externally so the fleet hub / connectome-doctor can watch
+      // budget convergence without an agent turn.
+      try {
+        const fw2 = app.framework as unknown as {
+          getAgentRuntimeSettings?: (name: string) => unknown;
+        };
+        if (typeof fw2.getAgentRuntimeSettings === 'function') {
+          const settings: Record<string, unknown> = {};
+          for (const agent of app.framework.getAllAgents()) {
+            const name = (agent as unknown as { name: string }).name;
+            settings[name] = fw2.getAgentRuntimeSettings(name);
+          }
+          (snapshot as Record<string, unknown>).runtimeSettings = settings;
+        }
+      } catch {
+        // Health reads never throw.
+      }
+      return Response.json(snapshot);
     }
 
     // Workspace file passthrough: /files/<mount>/<path...>
@@ -2486,6 +2561,9 @@ export class WebUiModule implements Module {
       ...(sharedServer!.latestPerAgentCost.length > 0
         ? { perAgentCost: sharedServer!.latestPerAgentCost }
         : {}),
+      ...(sharedServer!.latestCallLedger
+        ? { callLedger: sharedServer!.latestCallLedger }
+        : {}),
     };
   }
 

package/src/modules/web-ui-observers.ts

@@ -210,23 +210,36 @@ export class ObserverRegistry {
 
 const SESSION_TTL_MS = 12 * 60 * 60_000;
 
+export interface ObserverSession {
+  scopes: Set<ObserverScope>;
+  /**
+   * Full sessions carry OPERATOR authority (equivalent to basic auth): the
+   * WS upgrade treats the connection as a full client, not a read-only
+   * observer. Minted only by /auth/basic after a successful password
+   * challenge. Exists because browsers reliably attach cookies to WebSocket
+   * upgrades but (Chrome, notably) do NOT attach cached basic-auth
+   * credentials — without this, password sign-in loops back to the gate.
+   */
+  full: boolean;
+}
+
 export class ObserverSessions {
-  private sessions = new Map<string, { scopes: Set<ObserverScope>; expiresAt: number }>();
+  private sessions = new Map<string, ObserverSession & { expiresAt: number }>();
 
-  mint(scopes: Set<ObserverScope>): string {
-    // Opportunistic sweep — the map stays tiny (one entry per WS auth).
+  mint(scopes: Set<ObserverScope>, opts?: { full?: boolean }): string {
+    // Opportunistic sweep — the map stays tiny (one entry per auth event).
     const now = Date.now();
     for (const [t, s] of this.sessions) if (s.expiresAt < now) this.sessions.delete(t);
     const token = randomBytes(32).toString('hex');
-    this.sessions.set(token, { scopes, expiresAt: now + SESSION_TTL_MS });
+    this.sessions.set(token, { scopes, full: opts?.full ?? false, expiresAt: now + SESSION_TTL_MS });
     return token;
   }
 
-  lookup(token: string | null | undefined): Set<ObserverScope> | null {
+  lookup(token: string | null | undefined): ObserverSession | null {
     if (!token) return null;
     const s = this.sessions.get(token);
     if (!s || s.expiresAt < Date.now()) return null;
-    return s.scopes;
+    return { scopes: s.scopes, full: s.full };
   }
 }
 
@@ -283,12 +296,25 @@ export function filterEntryForScopes(
 /** Project a welcome through an observer's scope mask. Without 'messages'
  *  the entire conversation payload (entries + agent trees, which carry
  *  streaming buffers) is emptied — a health/ops observer like the fleet hub
- *  gets structure and usage, never content. */
+ *  gets structure and usage, never content. Without 'health' the telemetry
+ *  fields (usage / perAgentCost / callLedger) are masked too: their live
+ *  frames (`usage`, `call-ledger`) are gated on 'health', and the welcome
+ *  must refuse exactly what the stream refuses — otherwise a messages-only
+ *  observer reads model IDs, per-call costs, and raw provider errors on
+ *  connect that it is denied a second later. */
 export function scopeWelcome(welcome: WelcomeMessage, scopes: Set<ObserverScope>): WelcomeMessage {
   const emptyTree = { asOfTs: Date.now(), nodes: [], callIdIndex: {} };
+  const scoped: WelcomeMessage = { ...welcome };
+  if (!scopes.has('health')) {
+    delete scoped.callLedger;
+    delete scoped.perAgentCost;
+    // `usage` is required by the wire type, so it is zeroed rather than
+    // dropped (matches the emptied-not-deleted style of the fields below).
+    scoped.usage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+  }
   if (!scopes.has('messages')) {
     return {
-      ...welcome,
+      ...scoped,
       messages: [],
       history: { startIndex: welcome.history.totalCount, totalCount: welcome.history.totalCount },
       localTree: emptyTree,
@@ -296,7 +322,7 @@ export function scopeWelcome(welcome: WelcomeMessage, scopes: Set<ObserverScope>
     };
   }
   return {
-    ...welcome,
+    ...scoped,
     messages: welcome.messages
       .map((e) => filterEntryForScopes(e, scopes))
       .filter((e): e is WelcomeMessageEntry => e !== null),

package/src/recipe.ts

@@ -35,6 +35,13 @@ export interface RecipeStrategy {
   // for what the recipe loader accepts under `agent.strategy`.
   enforceBudget?: boolean;
   maxSpeculativeL1s?: number;
+  /** Number of coverage-equivalent recall curves to try after the canonical
+   * autobiographical compression request is explicitly refused. Zero disables
+   * fallback while retaining the canonical attempt. */
+  compressionRefusalCurveFallbacks?: number;
+  /** Complete provider-request admission ceiling for compression fallbacks,
+   * including the output reserve. */
+  compressionContextBudgetTokens?: number;
   positionedRecallPairs?: boolean;
   recallHeaderTemplate?: string;
   targetChunkTokens?: number;
@@ -75,6 +82,10 @@ export interface RecipeStrategy {
 export interface RecipeAgent {
   name?: string;
   model?: string;
+  /** IANA zone used when rendering wall-clock times to the agent. */
+  timezone?: string;
+  /** Provider transport. Omitted preserves the historical Anthropic default. */
+  provider?: 'anthropic' | 'openai-responses';
   systemPrompt: string;
   maxTokens?: number;
   /**
@@ -86,10 +97,14 @@ export interface RecipeAgent {
   /** Per-agent context compile budget (input tokens). When unset, the
    *  ContextManager default (100k) applies. Raise for large-context models. */
   contextBudgetTokens?: number;
-  /** Prompt-cache TTL ('5m' | '1h') forwarded to the provider. Set '1h' for
-   *  agents whose reply cadence is slower than 5 minutes — avoids re-writing
-   *  the full context to cache after every gap. Unset: provider default (5m). */
+  /** Prompt-cache TTL ('5m' | '1h') forwarded to the provider. Defaults to
+   *  '1h'; set '5m' explicitly for high-frequency, sub-5-minute workloads. */
   cacheTtl?: '5m' | '1h';
+  /**
+   * Same-round routing policy for ordinary text emitted beside think().
+   * Omitted preserves the compatibility carry-forward in Agent Framework.
+   */
+  sameRoundThinkTextPolicy?: 'public' | 'private';
   strategy?: RecipeStrategy;
   /**
    * Native extended thinking. When `enabled: true`, the agent's API requests
@@ -100,6 +115,14 @@ export interface RecipeAgent {
     enabled: boolean;
     budgetTokens?: number;
   };
+  /** Stateless OpenAI Responses settings. Only used with
+   * `provider: "openai-responses"`. */
+  responses?: {
+    reasoningEffort?: 'none' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+    reasoningContext?: 'current_turn' | 'all_turns';
+    serviceTier?: string;
+    compactThreshold?: number;
+  };
   /**
    * Content-refusal handling. When `autoRewind` is on, a `stop_reason: refusal`
    * turn triggers an automatic rewind of the triggering turn + retry (keeping
@@ -109,6 +132,11 @@ export interface RecipeAgent {
     autoRewind?: boolean;
     maxRewinds?: number;
     announceHumanTurns?: boolean;
+    primarySummaryFallback?: {
+      enabled?: boolean;
+      maxNewSummaries?: number;
+      requestBudgetTokens?: number;
+    };
   };
 }
 
@@ -144,9 +172,8 @@ export interface RecipeMcpServer {
   /** Ceiling for the exponential reconnect backoff. Default: 5 minutes. */
   reconnectMaxIntervalMs?: number;
   /**
-   * Channel auto-open policy. 'auto' (default) opens everything the server
-   * registers; 'manual' opens nothing (agent calls channel_open as needed);
-   * a string[] is an allow-list of channel ids.
+   * @deprecated One-time migration input for legacy recipes. Runtime channel
+   * desired state is Chronicle-backed and changed with channel_open/close.
    */
   channelSubscription?: 'auto' | 'manual' | string[];
   /**
@@ -500,6 +527,7 @@ export const DEFAULT_RECIPE: Recipe = {
   description: 'General-purpose assistant with tool access',
   agent: {
     name: 'agent',
+    cacheTtl: '1h',
     systemPrompt: [
       'You are a helpful assistant. You have access to tools provided by connected MCP servers.',
       'Use them to help the user with their tasks.',
@@ -678,6 +706,42 @@ export function validateRecipe(raw: unknown): Recipe {
     throw new Error('Recipe agent must have a "systemPrompt" string');
   }
 
+  if (agent.provider !== undefined && agent.provider !== 'anthropic' && agent.provider !== 'openai-responses') {
+    throw new Error(`Recipe agent.provider must be 'anthropic' or 'openai-responses', got ${JSON.stringify(agent.provider)}.`);
+  }
+
+  if (agent.timezone !== undefined) {
+    if (typeof agent.timezone !== 'string' || !agent.timezone.trim()) {
+      throw new Error('Recipe agent.timezone must be a non-empty IANA time zone string.');
+    }
+    try {
+      new Intl.DateTimeFormat('en-US', { timeZone: agent.timezone }).format(new Date(0));
+    } catch {
+      throw new Error(`Recipe agent.timezone is not a valid IANA time zone: ${JSON.stringify(agent.timezone)}.`);
+    }
+  }
+
+  if (agent.responses !== undefined) {
+    if (!agent.responses || typeof agent.responses !== 'object' || Array.isArray(agent.responses)) {
+      throw new Error('Recipe agent.responses must be an object.');
+    }
+    const responses = agent.responses as Record<string, unknown>;
+    const efforts = ['none', 'low', 'medium', 'high', 'xhigh', 'max'];
+    if (responses.reasoningEffort !== undefined && !efforts.includes(String(responses.reasoningEffort))) {
+      throw new Error(`Invalid agent.responses.reasoningEffort ${JSON.stringify(responses.reasoningEffort)}.`);
+    }
+    if (responses.reasoningContext !== undefined && responses.reasoningContext !== 'current_turn' && responses.reasoningContext !== 'all_turns') {
+      throw new Error(`Invalid agent.responses.reasoningContext ${JSON.stringify(responses.reasoningContext)}.`);
+    }
+    if (responses.serviceTier !== undefined && (typeof responses.serviceTier !== 'string' || !responses.serviceTier.trim())) {
+      throw new Error('Recipe agent.responses.serviceTier must be a non-empty string.');
+    }
+    if (responses.compactThreshold !== undefined &&
+        (typeof responses.compactThreshold !== 'number' || responses.compactThreshold <= 0)) {
+      throw new Error('Recipe agent.responses.compactThreshold must be a positive number.');
+    }
+  }
+
   if (agent.maxStreamTokens !== undefined && (typeof agent.maxStreamTokens !== 'number' || agent.maxStreamTokens <= 0)) {
     throw new Error('Recipe agent.maxStreamTokens must be a positive number.');
   }
@@ -687,6 +751,17 @@ export function validateRecipe(raw: unknown): Recipe {
   if (agent.cacheTtl !== undefined && agent.cacheTtl !== '5m' && agent.cacheTtl !== '1h') {
     throw new Error(`Recipe agent.cacheTtl must be '5m' or '1h', got ${JSON.stringify(agent.cacheTtl)}.`);
   }
+  agent.cacheTtl ??= '1h';
+
+  if (
+    agent.sameRoundThinkTextPolicy !== undefined &&
+    agent.sameRoundThinkTextPolicy !== 'public' &&
+    agent.sameRoundThinkTextPolicy !== 'private'
+  ) {
+    throw new Error(
+      `Recipe agent.sameRoundThinkTextPolicy must be 'public' or 'private', got ${JSON.stringify(agent.sameRoundThinkTextPolicy)}.`,
+    );
+  }
 
   // Validate agent.thinking if present. Catches typos and constraint
   // violations (notably max_tokens > budget_tokens) at recipe-load time
@@ -725,6 +800,58 @@ export function validateRecipe(raw: unknown): Recipe {
         `Invalid strategy type "${strategy.type}". Must be "autobiographical", "passthrough", or "frontdesk".`,
       );
     }
+    if (
+      strategy.compressionRefusalCurveFallbacks !== undefined
+      && (
+        typeof strategy.compressionRefusalCurveFallbacks !== 'number'
+        || !Number.isSafeInteger(strategy.compressionRefusalCurveFallbacks)
+        || strategy.compressionRefusalCurveFallbacks < 0
+      )
+    ) {
+      throw new Error('Recipe agent.strategy.compressionRefusalCurveFallbacks must be a non-negative safe integer.');
+    }
+    if (
+      strategy.compressionContextBudgetTokens !== undefined
+      && (
+        typeof strategy.compressionContextBudgetTokens !== 'number'
+        || !Number.isSafeInteger(strategy.compressionContextBudgetTokens)
+        || strategy.compressionContextBudgetTokens <= 0
+      )
+    ) {
+      throw new Error('Recipe agent.strategy.compressionContextBudgetTokens must be a positive safe integer.');
+    }
+  }
+
+  const refusalHandling = agent.refusalHandling as Record<string, unknown> | undefined;
+  const primarySummaryFallback = refusalHandling?.primarySummaryFallback;
+  if (primarySummaryFallback !== undefined) {
+    if (!primarySummaryFallback || typeof primarySummaryFallback !== 'object' || Array.isArray(primarySummaryFallback)) {
+      throw new Error('Recipe agent.refusalHandling.primarySummaryFallback must be an object.');
+    }
+    const fallback = primarySummaryFallback as Record<string, unknown>;
+    if (fallback.enabled !== undefined && typeof fallback.enabled !== 'boolean') {
+      throw new Error('Recipe agent.refusalHandling.primarySummaryFallback.enabled must be a boolean.');
+    }
+    if (
+      fallback.maxNewSummaries !== undefined &&
+      (
+        typeof fallback.maxNewSummaries !== 'number' ||
+        !Number.isSafeInteger(fallback.maxNewSummaries) ||
+        fallback.maxNewSummaries < 0
+      )
+    ) {
+      throw new Error('Recipe agent.refusalHandling.primarySummaryFallback.maxNewSummaries must be a non-negative safe integer.');
+    }
+    if (
+      fallback.requestBudgetTokens !== undefined &&
+      (
+        typeof fallback.requestBudgetTokens !== 'number' ||
+        !Number.isSafeInteger(fallback.requestBudgetTokens) ||
+        fallback.requestBudgetTokens <= 0
+      )
+    ) {
+      throw new Error('Recipe agent.refusalHandling.primarySummaryFallback.requestBudgetTokens must be a positive safe integer.');
+    }
   }
 
   // Validate mcpServers entries if present

package/src/state/agent-tree-reducer.ts

@@ -202,10 +202,13 @@ const EVENT_HANDLERS: Record<string, EventHandler> = {
     node.lastEventAt = ts;
   },
 
-  // inference:exhausted = budget exhaustion / stream-side cancel / reboot-
+  // inference:exhausted = retries exhausted / genuine stream cancel / reboot-
   // induced. Postmortem 2026-05-28 P1 #3: not strictly a fault — flip both
   // fields to the dedicated 'cancelled' terminal state so the renderer can
-  // distinguish "stopped on purpose" from "errored out".
+  // distinguish "stopped on purpose" from "errored out". (AF PR #55 / ≥ 0.6.5
+  // stopped emitting this for endTurn and context-budget restarts — those are
+  // no longer terminal at all — but user cancels and reboots still land here,
+  // and older AF still sends the endTurn-trailing one.)
   'inference:exhausted': (r, e, ts) => {
     if (!e.agentName) return;
     const node = r._ensureNode(e.agentName);
@@ -236,9 +239,20 @@ const EVENT_HANDLERS: Record<string, EventHandler> = {
     r._ensureNode(e.agentName).lastEventAt = ts;
   },
 
+  // endTurn tool result: the agent deliberately ended its turn — a successful
+  // terminal, same family as inference:completed. This event must be terminal
+  // in its own right: agent-framework PR #55 (≥ 0.6.5) settles endTurn from
+  // the state machine and no longer follows it with the spurious
+  // inference:exhausted that used to flip these nodes to 'cancelled'. On
+  // older AF the trailing exhausted still arrives and (harmlessly)
+  // re-terminates the node as cancelled one event later.
   'inference:turn_ended': (r, e, ts) => {
     if (!e.agentName) return;
-    r._ensureNode(e.agentName).lastEventAt = ts;
+    const node = r._ensureNode(e.agentName);
+    node.phase = 'done';
+    node.status = 'completed';
+    node.completedAt = ts;
+    node.lastEventAt = ts;
   },
 
   'tool:started': (r, e, ts) => {

package/src/strategies/frontdesk-strategy.ts

@@ -9,6 +9,7 @@ import type {
   SummaryEntry,
 } from '@animalabs/context-manager';
 import type { ContentBlock } from '@animalabs/membrane';
+import { formatZonedTime, resolveTimeZone } from '@animalabs/agent-framework';
 
 // Structural mirror of AutobiographicalStrategy's internal Chunk.
 // Kept inline because @animalabs/context-manager does not currently export it.
@@ -24,7 +25,7 @@ interface Chunk {
   phaseType?: string;
 }
 
-export type FrontdeskStrategyOptions = Partial<AutobiographicalConfig>;
+export type FrontdeskStrategyOptions = Partial<AutobiographicalConfig> & { timeZone?: string };
 
 /**
  * Chatbot-flavoured context strategy for agents that receive messages via
@@ -43,6 +44,13 @@ export class FrontdeskStrategy extends AutobiographicalStrategy {
   override readonly name: string = 'frontdesk';
 
   private salientSourceIds: Set<string> = new Set();
+  private readonly timeZone: string;
+
+  constructor(options: FrontdeskStrategyOptions = {}) {
+    const { timeZone, ...strategyOptions } = options;
+    super(strategyOptions);
+    this.timeZone = resolveTimeZone(timeZone);
+  }
 
   override select(
     store: MessageStoreView,
@@ -115,15 +123,15 @@ export class FrontdeskStrategy extends AutobiographicalStrategy {
     if (ts) parts.push(ts);
 
     if (meta.messageId !== undefined && meta.messageId !== null && meta.messageId !== '') {
-      const mid = String(meta.messageId);
-      const short = mid.length > 12 ? mid.slice(0, 12) : mid;
-      parts.push(`msg ${short}`);
+      // Render the FULL id — truncating (an old token-saving trim) corrupts
+      // Discord snowflakes, so every reply_message/fetch_around/add_reaction
+      // call the agent copies from its own context 404s with Unknown message.
+      parts.push(`msg ${String(meta.messageId)}`);
     }
 
     const threadId = meta.threadId !== undefined && meta.threadId !== null ? String(meta.threadId) : '';
     if (threadId && threadId !== topic) {
-      const short = threadId.length > 12 ? threadId.slice(0, 12) : threadId;
-      parts.push(`thread ${short}`);
+      parts.push(`thread ${threadId}`);
     }
 
     if (parts.length === 0) return null;
@@ -146,9 +154,7 @@ export class FrontdeskStrategy extends AutobiographicalStrategy {
     }
     if (!d && msgTs instanceof Date && !isNaN(msgTs.getTime())) d = msgTs;
     if (!d) return null;
-    const hh = String(d.getHours()).padStart(2, '0');
-    const mm = String(d.getMinutes()).padStart(2, '0');
-    return `${hh}:${mm}`;
+    return formatZonedTime(d, this.timeZone);
   }
 
   // ==========================================================================

package/src/web/protocol.ts

@@ -93,6 +93,9 @@ export interface WelcomeMessage {
   /** Per-agent cost breakdown for the parent process, present when the
    *  framework's usage tracker has data. Empty during cold start. */
   perAgentCost?: PerAgentCost[];
+  /** Recent provider calls with cache verdicts. Present when the host's
+   *  provider adapter exposes the call ledger. */
+  callLedger?: CallLedgerSnapshot;
 }
 
 /**
@@ -164,6 +167,91 @@ export interface UsageMessage {
   perAgentCost?: PerAgentCost[];
 }
 
+/** Live replacement snapshot emitted after each provider call. */
+export interface CallLedgerMessage {
+  type: 'call-ledger';
+  ledger: CallLedgerSnapshot;
+}
+
+export type CallLedgerVerdict =
+  | 'HIT'
+  | 'hit+extend'
+  | 'uncached'
+  | 'rewrite:expired'
+  | 'rewrite:prefix-mutated'
+  | 'rewrite:prefix-truncated'
+  | 'rewrite:unexplained'
+  | 'first-write'
+  | 'ERROR'
+  | 'empty'
+  | 'unknown';
+
+export interface CallLedgerRow {
+  id: string;
+  timestamp: string;
+  kind: 'complete' | 'stream';
+  /** Honest call-class estimate; `~` means the trigger plumbing did not
+   *  provide a definitive origin. */
+  originEstimate: 'turn~' | 'aux~';
+  model: string;
+  messages: number;
+  durationMs: number;
+  tokens: { input: number; output: number; cacheRead: number; cacheWrite: number };
+  cost?: CallCostBreakdown;
+  cache: {
+    /** Undefined for older compact logs that predate marker summaries. */
+    breakpoints?: number;
+    ttls: string[];
+    effectiveTtl: '5m' | '1h';
+  };
+  verdict: CallLedgerVerdict;
+  cause: string;
+  stopReason?: string;
+  error?: string;
+}
+
+export interface CallCostBreakdown {
+  input: number;
+  cacheWrite5m: number;
+  cacheWrite1h: number;
+  cacheRead: number;
+  output: number;
+  total: number;
+  currency: 'USD';
+  /** `billing` means every charged usage bucket and pricing modifier was
+   *  known. Unknown/mixed buckets are left unpriced rather than estimated. */
+  grade: 'billing';
+  pricingVersion: string;
+  rates: {
+    inputPerMillion: number;
+    outputPerMillion: number;
+    cacheWrite5mPerMillion: number;
+    cacheWrite1hPerMillion: number;
+    cacheReadPerMillion: number;
+  };
+}
+
+export interface CallLedgerSnapshot {
+  /** Oldest to newest; clients may reverse for display. */
+  rows: CallLedgerRow[];
+  summary: {
+    calls: number;
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    cacheHitRatio: number;
+    cost?: {
+      total: number;
+      currency: 'USD';
+      pricedCalls: number;
+      unpricedCalls: number;
+      pricingVersion: string;
+    };
+    byVerdict: Partial<Record<CallLedgerVerdict, number>>;
+  };
+}
+
 export interface TokenUsage {
   input: number;
   output: number;
@@ -352,6 +440,7 @@ export type WebUiServerMessage =
   | ChildEventMessage
   | CommandResultMessage
   | UsageMessage
+  | CallLedgerMessage
   | BranchChangedMessage
   | SessionChangedMessage
   | PeekMessage