opencandle 0.10.0 → 0.11.1

package/src/pi/tui-session-coordinator.ts

@@ -0,0 +1,351 @@
+import { randomBytes } from "node:crypto";
+import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
+import type { AddressInfo } from "node:net";
+import type { AgentSession, SessionManager } from "@earendil-works/pi-coding-agent";
+import {
+  clearPendingSessionAction,
+  hasAcceptedSessionAction,
+  hasPendingSessionAction,
+  recordAcceptedSessionAction,
+  recordPendingSessionAction,
+} from "./session-action-dedupe.js";
+
+interface TuiSessionCoordinatorOptions {
+  getSession: () => AgentSession;
+  getSessionManager: () => SessionManager;
+  getModelUnavailableMessage: () => string | null;
+  syncWriterLockScope?: () => void;
+  now?: () => number;
+}
+
+export interface TuiSessionCoordinatorServer {
+  endpoint: string;
+  secret: string;
+  close(): Promise<void>;
+}
+
+interface AcceptedAction {
+  expiresAt: number;
+}
+
+const DEDUPE_RETENTION_MS = 10 * 60 * 1000;
+
+export async function startTuiSessionCoordinatorServer(
+  options: TuiSessionCoordinatorOptions,
+): Promise<TuiSessionCoordinatorServer> {
+  const now = options.now ?? Date.now;
+  const secret = randomBytes(32).toString("base64url");
+  const acceptedActions = new Map<string, AcceptedAction>();
+  const activeRunSessions = new Set<string>();
+
+  const server = createServer((req, res) => {
+    void handleRequest(req, res).catch((error) => {
+      const message = error instanceof Error ? error.message : String(error);
+      writeJson(res, { error: message }, 500);
+    });
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      server.off("error", reject);
+      resolve();
+    });
+  });
+
+  const address = server.address() as AddressInfo;
+  const endpoint = `http://127.0.0.1:${address.port}`;
+
+  return {
+    endpoint,
+    secret,
+    close: () =>
+      new Promise<void>((resolve, reject) => {
+        server.close((error) => (error ? reject(error) : resolve()));
+      }),
+  };
+
+  async function handleRequest(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    const url = new URL(req.url ?? "/", endpoint);
+    if (url.pathname !== "/api/local-coordinator/chat-run" || req.method !== "POST") {
+      writeJson(res, { error: "Not found" }, 404);
+      return;
+    }
+
+    if (
+      !isLoopbackAddress(req.socket.remoteAddress) ||
+      req.headers["x-opencandle-coordinator-secret"] !== secret
+    ) {
+      writeJson(res, { error: "Local coordinator request was not authorized." }, 403);
+      return;
+    }
+
+    const body = asRecord(await readJsonBody(req));
+    const prompt = String(body.prompt ?? "").trim();
+    const requestedSessionId = String(body.sessionId ?? "").trim();
+    const actionId = String(body.actionId ?? "").trim() || `legacy-tui-chat-${now()}`;
+    const sessionManager = options.getSessionManager();
+    const sessionId = sessionManager.getSessionId();
+    if (!prompt) {
+      writeJson(res, { error: "prompt is required" }, 400);
+      return;
+    }
+    if (requestedSessionId && requestedSessionId !== sessionId) {
+      writeJson(
+        res,
+        { error: "Session route and request body disagree", code: "session_changed" },
+        409,
+      );
+      return;
+    }
+    try {
+      options.syncWriterLockScope?.();
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      writeJson(res, { error: message, code: "syncing" }, 409);
+      return;
+    }
+
+    pruneExpiredActions();
+    const actionKey = `${sessionId}:${actionId}`;
+    if (acceptedActions.has(actionKey) || hasAcceptedSessionAction(sessionManager, actionId)) {
+      writeJson(res, { ok: true, duplicate: true });
+      return;
+    }
+    if (hasPendingSessionAction(sessionManager, actionId)) {
+      writeJson(
+        res,
+        { error: "OpenCandle is reconnecting to this session.", code: "syncing" },
+        409,
+      );
+      return;
+    }
+    let session: AgentSession;
+    try {
+      session = options.getSession();
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      writeJson(res, { error: message, code: "session_starting" }, 409);
+      return;
+    }
+    if (
+      activeRunSessions.has(sessionId) ||
+      session.isStreaming ||
+      session.pendingMessageCount > 0
+    ) {
+      writeJson(
+        res,
+        {
+          error: "OpenCandle is still working in this session. Try again when it finishes.",
+          code: "session_busy",
+        },
+        409,
+      );
+      return;
+    }
+
+    activeRunSessions.add(sessionId);
+    try {
+      recordPendingSessionAction(sessionManager, actionId);
+      let actionAccepted = false;
+      const recordAcceptedAction = () => {
+        if (actionAccepted) return;
+        recordAcceptedSessionAction(sessionManager, actionId);
+        options.syncWriterLockScope?.();
+        acceptedActions.set(actionKey, { expiresAt: now() + DEDUPE_RETENTION_MS });
+        actionAccepted = true;
+      };
+      let completed: boolean;
+      try {
+        completed = await streamPromptRun(res, prompt, sessionId, recordAcceptedAction);
+      } catch (error) {
+        if (!actionAccepted) clearPendingSessionAction(sessionManager, actionId);
+        throw error;
+      }
+      if (completed) {
+        recordAcceptedAction();
+      } else if (!actionAccepted) {
+        clearPendingSessionAction(sessionManager, actionId);
+      }
+    } finally {
+      activeRunSessions.delete(sessionId);
+    }
+  }
+
+  async function streamPromptRun(
+    res: ServerResponse,
+    prompt: string,
+    sessionId: string,
+    onPromptAdmitted: () => void,
+  ): Promise<boolean> {
+    options.syncWriterLockScope?.();
+    const session = options.getSession();
+    const sessionManager = options.getSessionManager();
+    const beforeEntries = sessionManager.getEntries();
+    const beforeCount = beforeEntries.length;
+    let seq = 1;
+    const runId = `tui-run-${now()}`;
+
+    res.writeHead(200, {
+      "content-type": "text/event-stream; charset=utf-8",
+      "cache-control": "no-cache, no-transform",
+      connection: "keep-alive",
+    });
+    writeSse(res, { type: "run.started", runId, sessionId, seq: seq++ });
+    res.flushHeaders?.();
+
+    try {
+      const modelUnavailableMessage = options.getModelUnavailableMessage();
+      if (!prompt.startsWith("/") && modelUnavailableMessage) {
+        sessionManager.appendMessage({ role: "user", content: prompt, timestamp: now() });
+        onPromptAdmitted();
+        options.syncWriterLockScope?.();
+        sessionManager.appendCustomMessageEntry(
+          "opencandle-model-setup",
+          modelUnavailableMessage,
+          true,
+          {
+            source: "tui",
+          },
+        );
+      } else {
+        const unsubscribe = subscribeToPromptAdmission(session, prompt, onPromptAdmitted);
+        try {
+          await session.prompt(prompt);
+          options.syncWriterLockScope?.();
+          await waitForTurnSettlement(session);
+        } finally {
+          unsubscribe?.();
+        }
+      }
+      const newEntries = sessionManager.getEntries().slice(beforeCount);
+      for (const event of entriesToChatEvents(newEntries, sessionId, seq)) {
+        writeSse(res, event);
+        seq = event.seq + 1;
+      }
+      writeSse(res, { type: "run.completed", runId, sessionId, seq });
+      return true;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      writeSse(res, { type: "run.failed", runId, sessionId, error: { message }, seq });
+      return false;
+    } finally {
+      res.end();
+    }
+  }
+
+  function pruneExpiredActions(): void {
+    const currentTime = now();
+    for (const [actionKey, accepted] of acceptedActions) {
+      if (accepted.expiresAt <= currentTime) acceptedActions.delete(actionKey);
+    }
+  }
+
+  function subscribeToPromptAdmission(
+    session: AgentSession,
+    prompt: string,
+    onPromptAdmitted: () => void,
+  ): (() => void) | undefined {
+    if (prompt.startsWith("/")) return undefined;
+    const maybeSession = session as AgentSession & {
+      subscribe?: (handler: (event: unknown) => void) => () => void;
+    };
+    if (typeof maybeSession.subscribe !== "function") return undefined;
+    return maybeSession.subscribe((event) => {
+      const record = asRecord(event);
+      if (record.type !== "message_start") return;
+      const message = asRecord(record.message);
+      if (message.role !== "user") return;
+      if (messageTextFromContent(message.content).trim() === prompt.trim()) onPromptAdmitted();
+    });
+  }
+}
+
+async function waitForTurnSettlement(session: AgentSession): Promise<void> {
+  const startedAt = Date.now();
+  while (session.isStreaming || session.pendingMessageCount > 0) {
+    if (Date.now() - startedAt > 120_000) {
+      throw new Error("Timed out waiting for session turn to settle");
+    }
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+}
+
+function entriesToChatEvents(
+  entries: unknown[],
+  sessionId: string,
+  startSeq: number,
+): Array<Record<string, unknown> & { seq: number }> {
+  let seq = startSeq;
+  const events: Array<Record<string, unknown> & { seq: number }> = [];
+  for (const entry of entries) {
+    const record = asRecord(entry);
+    const message = asRecord(record.message);
+    const source = Object.keys(message).length > 0 ? message : record;
+    const role =
+      typeof source.role === "string"
+        ? source.role
+        : record.type === "custom_message"
+          ? "assistant"
+          : undefined;
+    const content = normalizeContent(source.content);
+    if (!role || content.length === 0) continue;
+    events.push({
+      type: "message.completed",
+      sessionId,
+      messageId: String(record.id ?? `tui-entry-${seq}`),
+      role,
+      content,
+      seq: seq++,
+    });
+  }
+  return events;
+}
+
+function normalizeContent(content: unknown): Array<Record<string, unknown>> {
+  if (typeof content === "string") return [{ type: "text", text: content }];
+  if (Array.isArray(content)) return content.map(asRecord).filter((item) => item.type);
+  const record = asRecord(content);
+  if (typeof record.text === "string") return [{ type: "text", text: record.text }];
+  return [];
+}
+
+function messageTextFromContent(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .map((part) =>
+      typeof part === "object" && part !== null && "text" in part && typeof part.text === "string"
+        ? part.text
+        : "",
+    )
+    .join("");
+}
+
+function writeJson(res: ServerResponse, value: unknown, status = 200): void {
+  res.writeHead(status, { "content-type": "application/json" });
+  res.end(JSON.stringify(value));
+}
+
+function writeSse(res: ServerResponse, event: unknown): void {
+  res.write(`data: ${JSON.stringify(event)}\n\n`);
+}
+
+async function readJsonBody(req: IncomingMessage): Promise<unknown> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of req) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  if (chunks.length === 0) return {};
+  return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+}
+
+function isLoopbackAddress(address: string | undefined): boolean {
+  return address === "127.0.0.1" || address === "::1" || address === "::ffff:127.0.0.1";
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}

package/src/prompts/context-builder.ts

@@ -291,7 +291,7 @@ const TOOL_CATALOG = `## Available Tools
 - **Sentiment**: get_reddit_sentiment, get_twitter_sentiment, get_web_sentiment, get_sentiment_trend, get_sentiment_summary — retail and news sentiment from Reddit, Twitter/X, and web sources with historical trends and cross-source divergence detection
 - **Web Search**: search_web — breaking news, earnings context, company events, regulatory developments. Supported freshness values are hours, day, week, and month; use category general with freshness month for broad industry context; never pass unsupported values such as all, year, 3mo, quarter, or custom date ranges. When a dedicated tool can answer the question (quotes, fundamentals, earnings, macro, SEC filings, sentiment), use that tool instead — do not add search_web as a supplementary source for data available through dedicated tools
 - **Options**: get_option_chain — full options chain with strikes, bids/asks, volume, OI, IV, and computed Greeks (delta, gamma, theta, vega, rho)
-- **Portfolio**: track_portfolio, analyze_risk, manage_watchlist, analyze_correlation, analyze_holdings_overlap, track_prediction, manage_alerts, daily_watchlist_report, manage_notifications — position tracking, P&L, Sharpe ratio, VaR, watchlist tracking, durable local alerts, daily watchlist reports, notification history, correlation matrix, ETF/fund holdings overlap, and prediction tracking with accuracy scoring
+- **Portfolio**: track_portfolio, analyze_risk, manage_watchlist, analyze_correlation, analyze_holdings_overlap, manage_alerts, daily_watchlist_report, manage_notifications — position tracking, P&L, Sharpe ratio, VaR, watchlist tracking, durable local alerts, daily watchlist reports, notification history, correlation matrix, and ETF/fund holdings overlap
 - **User Interaction**: ask_user — ask the user a clarification question when their request is ambiguous or missing key details`;
 
 function buildToolCatalog(addonDescriptions?: string[]): string {

package/src/prompts/policy-cards.ts

@@ -141,7 +141,7 @@ For strategy backtest prompts, use backtest_strategy evidence before judging whe
     status: "implemented",
     capabilityGapIds: [],
     content: `## Stateful Tracking Update Policy
-For watchlist, portfolio tracking, alert management, daily-report, prediction recording, and prediction-check prompts, use the state tool that owns the change or lookup: manage_watchlist, track_prediction, track_portfolio, manage_alerts, or daily_watchlist_report. Do not confirm a saved change from prose alone. Confirm the persisted state update with the symbol, action, direction, entry price, target, stop, conviction, timeframe, or check result that the tool accepted. If the user asks to create an alert and check it now in the same request, call manage_alerts with the matching create action and check_after_create=true. If required fields for a state mutation are missing, ask the smallest clarification question instead of inventing values. For check or list operations, summarize the saved state and say clearly when no records exist. Do not turn a state update into a buy/sell recommendation unless the user separately asks for market analysis.`,
+For watchlist, portfolio tracking, alert management, and daily-report prompts, use the state tool that owns the change or lookup: manage_watchlist, track_portfolio, manage_alerts, or daily_watchlist_report. Do not confirm a saved change from prose alone. Confirm the persisted state update with the symbol, action, quantity, cost, target, stop, or check result that the tool accepted. If the user asks to create an alert and check it now in the same request, call manage_alerts with the matching create action and check_after_create=true. If required fields for a state mutation are missing, ask the smallest clarification question instead of inventing values. For check or list operations, summarize the saved state and say clearly when no records exist. Do not turn a state update into a buy/sell recommendation unless the user separately asks for market analysis.`,
   },
   retail_finance_tradeoff: {
     id: "retail_finance_tradeoff",

package/src/providers/alpha-vantage.ts

@@ -234,6 +234,7 @@ export async function getGlobalQuote(symbol: string, apiKey: string): Promise<St
       week52High: 0, // Not available from GLOBAL_QUOTE
       week52Low: 0, // Not available from GLOBAL_QUOTE
       timestamp: Date.now(),
+      asOf: dateOnlyValue(gq["07. latest trading day"]),
     };
 
     cache.set(cacheKey, result, TTL.QUOTE);
@@ -246,6 +247,11 @@ export async function getGlobalQuote(symbol: string, apiKey: string): Promise<St
   }
 }
 
+function dateOnlyValue(value: string | undefined): string | undefined {
+  if (!value || !/^\d{4}-\d{2}-\d{2}$/.test(value)) return undefined;
+  return value;
+}
+
 export async function getDailyHistory(
   symbol: string,
   apiKey: string,

package/src/providers/coingecko.ts

@@ -19,6 +19,7 @@ interface CoinGeckoDetailResponse {
     low_24h: { usd: number };
     ath: { usd: number };
     ath_date: { usd: string };
+    last_updated?: string;
     circulating_supply: number;
     total_supply: number | null;
   };
@@ -52,6 +53,7 @@ export async function getCryptoPrice(id: string): Promise<CryptoPrice> {
       circulatingSupply: md.circulating_supply,
       totalSupply: md.total_supply,
       timestamp: Date.now(),
+      asOf: md.last_updated,
     };
 
     cache.set(cacheKey, result, TTL.QUOTE);

package/src/providers/polymarket.ts

@@ -0,0 +1,214 @@
+import { cache, STALE_LIMIT, TTL } from "../infra/cache.js";
+import { httpGet } from "../infra/http-client.js";
+import { rateLimiter } from "../infra/rate-limiter.js";
+import type { PredictionMarketQuote } from "../types/prediction-markets.js";
+
+const BASE_URL = "https://gamma-api.polymarket.com";
+const POLYMARKET_URL = "https://polymarket.com";
+
+interface GammaSearchResponse {
+  events?: GammaEvent[];
+  markets?: GammaMarket[];
+}
+
+interface GammaEvent {
+  id?: string | number;
+  slug?: string;
+  title?: string;
+  description?: string;
+  resolutionSource?: string;
+  endDate?: string;
+  volume?: unknown;
+  liquidity?: unknown;
+  updatedAt?: string;
+  markets?: GammaMarket[];
+}
+
+interface GammaMarket {
+  id?: string | number;
+  question?: string;
+  slug?: string;
+  description?: string;
+  resolutionSource?: string;
+  outcomes?: unknown;
+  outcomePrices?: unknown;
+  volume?: unknown;
+  volumeNum?: unknown;
+  liquidity?: unknown;
+  liquidityNum?: unknown;
+  endDate?: string;
+  endDateIso?: string;
+  updatedAt?: string;
+  active?: unknown;
+  closed?: unknown;
+}
+
+interface MarketWithEvent {
+  event?: GammaEvent;
+  market: GammaMarket;
+}
+
+export async function searchPredictionMarkets(
+  query: string,
+  limit: number = 8,
+): Promise<PredictionMarketQuote[]> {
+  const normalizedQuery = query.trim();
+  const normalizedLimit = normalizeLimit(limit);
+  if (!normalizedQuery) return [];
+
+  const cacheKey = `polymarket:search:${normalizedQuery.toLowerCase()}:${normalizedLimit}`;
+  const cached = cache.get<PredictionMarketQuote[]>(cacheKey);
+  if (cached) return cached;
+
+  try {
+    await rateLimiter.acquire("polymarket");
+    const url = `${BASE_URL}/public-search?q=${encodeURIComponent(normalizedQuery)}&limit=${normalizedLimit}`;
+    const response = await httpGet<GammaSearchResponse>(url, {
+      headers: { Accept: "application/json" },
+      maxRetries: 0,
+    });
+    const quotes = decodeSearchResponse(response).slice(0, normalizedLimit);
+    cache.set(cacheKey, quotes, TTL.PREDICTION_MARKETS);
+    return quotes;
+  } catch (error) {
+    const stale = cache.getStale<PredictionMarketQuote[]>(cacheKey, STALE_LIMIT.PREDICTION_MARKETS);
+    if (stale) return stale.value;
+    throw error;
+  }
+}
+
+function decodeSearchResponse(response: GammaSearchResponse): PredictionMarketQuote[] {
+  const markets: MarketWithEvent[] = [
+    ...(response.events ?? []).flatMap((event) =>
+      (event.markets ?? []).map((market) => ({ event, market })),
+    ),
+    ...(response.markets ?? []).map((market) => ({ market })),
+  ];
+  return markets.flatMap(({ event, market }) =>
+    isOpenMarket(market) ? marketToQuotes(market, event) : [],
+  );
+}
+
+function marketToQuotes(market: GammaMarket, event?: GammaEvent): PredictionMarketQuote[] {
+  const marketId = market.id === undefined ? undefined : String(market.id);
+  const title = stringValue(market.question) ?? stringValue(event?.title);
+  if (!marketId || !title) return [];
+
+  const outcomes = parseStringArray(market.outcomes);
+  const prices = parseNumberArray(market.outcomePrices);
+  if (outcomes.length === 0 || prices.length === 0) return [];
+
+  const resolutionCriteria = firstNonEmpty(market.description, market.resolutionSource);
+  const volumeUsd =
+    numberValue(market.volumeNum) ?? numberValue(market.volume) ?? numberValue(event?.volume);
+  const liquidityUsd =
+    numberValue(market.liquidityNum) ??
+    numberValue(market.liquidity) ??
+    numberValue(event?.liquidity);
+  const closeDate =
+    stringValue(market.endDate) ?? normalizeDateOnly(market.endDateIso ?? event?.endDate);
+  const url = marketUrl(market, event);
+  const asOf = stringValue(market.updatedAt) ?? stringValue(event?.updatedAt);
+
+  return outcomes.flatMap((outcome, index) => {
+    const probability = prices[index];
+    if (probability === undefined || probability < 0 || probability > 1) return [];
+    return [
+      {
+        source: "polymarket" as const,
+        marketId,
+        title,
+        outcome,
+        probability,
+        ...(volumeUsd !== undefined && { volumeUsd }),
+        ...(liquidityUsd !== undefined && { liquidityUsd }),
+        ...(closeDate && { closeDate }),
+        ...(resolutionCriteria && { resolutionCriteria }),
+        url,
+        ...(asOf && { asOf }),
+      },
+    ];
+  });
+}
+
+function isOpenMarket(market: GammaMarket): boolean {
+  if (booleanValue(market.closed) === true) return false;
+  if (booleanValue(market.active) === false) return false;
+  const endDate = stringValue(market.endDate) ?? stringValue(market.endDateIso);
+  if (!endDate) return true;
+  const parsed = new Date(endDate);
+  return Number.isNaN(parsed.getTime()) || parsed.getTime() > Date.now();
+}
+
+function normalizeLimit(limit: number): number {
+  if (!Number.isFinite(limit)) return 8;
+  return Math.min(50, Math.max(1, Math.floor(limit)));
+}
+
+function parseStringArray(value: unknown): string[] {
+  const parsed = parseJsonArray(value);
+  return parsed.flatMap((item) => {
+    const text = stringValue(item);
+    return text ? [text] : [];
+  });
+}
+
+function parseNumberArray(value: unknown): Array<number | undefined> {
+  const parsed = parseJsonArray(value);
+  return parsed.map((item) => numberValue(item));
+}
+
+function parseJsonArray(value: unknown): unknown[] {
+  if (Array.isArray(value)) return value;
+  if (typeof value !== "string") return [];
+  try {
+    const parsed = JSON.parse(value);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+function numberValue(value: unknown): number | undefined {
+  const number =
+    typeof value === "number" ? value : typeof value === "string" ? Number(value) : NaN;
+  return Number.isFinite(number) ? number : undefined;
+}
+
+function stringValue(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function booleanValue(value: unknown): boolean | undefined {
+  if (typeof value === "boolean") return value;
+  if (typeof value !== "string") return undefined;
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "true") return true;
+  if (normalized === "false") return false;
+  return undefined;
+}
+
+function firstNonEmpty(...values: unknown[]): string | undefined {
+  for (const value of values) {
+    const text = stringValue(value);
+    if (text) return text;
+  }
+  return undefined;
+}
+
+function normalizeDateOnly(value: string | undefined): string | undefined {
+  if (!value) return undefined;
+  return /^\d{4}-\d{2}-\d{2}$/.test(value) ? `${value}T00:00:00Z` : value;
+}
+
+function marketUrl(market: GammaMarket, event?: GammaEvent): string {
+  const marketSlug = stringValue(market.slug);
+  const eventSlug = stringValue(event?.slug);
+  if (eventSlug && marketSlug) {
+    return `${POLYMARKET_URL}/event/${encodeURIComponent(eventSlug)}/${encodeURIComponent(marketSlug)}`;
+  }
+  if (marketSlug) return `${POLYMARKET_URL}/event/${encodeURIComponent(marketSlug)}`;
+  return POLYMARKET_URL;
+}

package/src/providers/wrap-provider.ts

@@ -37,12 +37,14 @@ export async function wrapProvider<T>(
   }
 
   try {
-    const { value: data, stale } = await runWithStaleMetadata(fn);
+    const { value: data, cache } = await runWithStaleMetadata(fn);
+    const timestamp = cache ? new Date(cache.cachedAt).toISOString() : new Date().toISOString();
     return {
       status: "ok",
       data,
-      timestamp: stale ? new Date(stale.cachedAt).toISOString() : new Date().toISOString(),
-      stale: stale ? true : undefined,
+      timestamp,
+      cached: cache?.status === "cached" ? true : undefined,
+      stale: cache?.status === "stale" ? true : undefined,
     };
   } catch (error) {
     // Credential errors are re-thrown so the tool-layer `withCredentialCheck`