opencandle 0.12.0 → 0.13.0

package/dist/tools/index.d.ts

@@ -10,6 +10,7 @@ export { fearGreedTool } from "./macro/fear-greed.js";
 export { fredDataTool } from "./macro/fred-data.js";
 export { cryptoHistoryTool } from "./market/crypto-history.js";
 export { cryptoPriceTool } from "./market/crypto-price.js";
+export { priceComparisonTool } from "./market/price-comparison.js";
 export { screenStocksTool } from "./market/screen-stocks.js";
 export { searchTickerTool } from "./market/search-ticker.js";
 export { stockHistoryTool } from "./market/stock-history.js";
@@ -65,7 +66,7 @@ export declare function getAllTools(options?: {
     credentialRequired: unknown;
 } | null> | import("@earendil-works/pi-agent-core").AgentTool<import("@sinclair/typebox").TObject<{
     symbol: import("@sinclair/typebox").TString;
-    period: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"6mo" | "1y" | "2y">[]>>;
+    period: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"1y" | "2y" | "6mo">[]>>;
 }>, import("../types/portfolio.js").RiskMetrics | null> | import("@earendil-works/pi-agent-core").AgentTool<import("@sinclair/typebox").TObject<{
     id: import("@sinclair/typebox").TString;
     days: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
@@ -74,6 +75,14 @@ export declare function getAllTools(options?: {
 }>, (import("../types/market.js").CryptoPrice & {
     freshness: import("../infra/freshness.js").FreshnessStamp;
 }) | null> | import("@earendil-works/pi-agent-core").AgentTool<import("@sinclair/typebox").TObject<{
+    symbol: import("@sinclair/typebox").TString;
+    range: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"10y" | "1d" | "1mo" | "1y" | "2y" | "3mo" | "5d" | "5y" | "6mo" | "max" | "ytd">[]>>;
+    interval: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"15m" | "1d" | "1h" | "1m" | "1mo" | "1wk" | "5m">[]>>;
+}>, import("../types/market.js").OHLCV[] | import("./market/stock-history.js").StaleStockHistoryDetails> | import("@earendil-works/pi-agent-core").AgentTool<import("@sinclair/typebox").TObject<{
+    symbols: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>;
+    range: import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"10y" | "1d" | "1mo" | "1y" | "2y" | "3mo" | "5d" | "5y" | "6mo" | "max" | "ytd">[]>;
+    interval: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"15m" | "1d" | "1h" | "1m" | "1mo" | "1wk" | "5m">[]>>;
+}>, import("./market/price-comparison.js").PriceComparisonDetails> | import("@earendil-works/pi-agent-core").AgentTool<import("@sinclair/typebox").TObject<{
     market: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     columns: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
     filter: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
@@ -90,10 +99,6 @@ export declare function getAllTools(options?: {
     query: import("@sinclair/typebox").TString;
 }>, any> | import("@earendil-works/pi-agent-core").AgentTool<import("@sinclair/typebox").TObject<{
     symbol: import("@sinclair/typebox").TString;
-    range: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"6mo" | "1d" | "ytd" | "5d" | "1mo" | "3mo" | "1y" | "2y" | "5y" | "10y" | "max">[]>>;
-    interval: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"1d" | "1mo" | "1wk" | "1m" | "5m" | "15m" | "1h">[]>>;
-}>, import("../types/market.js").OHLCV[]> | import("@earendil-works/pi-agent-core").AgentTool<import("@sinclair/typebox").TObject<{
-    symbol: import("@sinclair/typebox").TString;
 }>, (import("../types/market.js").StockQuote & {
     freshness: import("../infra/freshness.js").FreshnessStamp;
 }) | null> | import("@earendil-works/pi-agent-core").AgentTool<import("@sinclair/typebox").TObject<{

package/dist/tools/index.js

@@ -9,6 +9,7 @@ import { fearGreedTool } from "./macro/fear-greed.js";
 import { fredDataTool } from "./macro/fred-data.js";
 import { cryptoHistoryTool } from "./market/crypto-history.js";
 import { cryptoPriceTool } from "./market/crypto-price.js";
+import { priceComparisonTool } from "./market/price-comparison.js";
 import { screenStocksTool } from "./market/screen-stocks.js";
 import { searchTickerTool } from "./market/search-ticker.js";
 import { stockHistoryTool } from "./market/stock-history.js";
@@ -41,6 +42,7 @@ export { fearGreedTool } from "./macro/fear-greed.js";
 export { fredDataTool } from "./macro/fred-data.js";
 export { cryptoHistoryTool } from "./market/crypto-history.js";
 export { cryptoPriceTool } from "./market/crypto-price.js";
+export { priceComparisonTool } from "./market/price-comparison.js";
 export { screenStocksTool } from "./market/screen-stocks.js";
 export { searchTickerTool } from "./market/search-ticker.js";
 export { stockHistoryTool } from "./market/stock-history.js";
@@ -67,6 +69,7 @@ export function getAllTools(options = {}) {
         searchTickerTool,
         stockQuoteTool,
         stockHistoryTool,
+        priceComparisonTool,
         screenStocksTool,
         cryptoPriceTool,
         cryptoHistoryTool,

package/dist/tools/market/price-comparison.d.ts

@@ -0,0 +1,30 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { type FreshnessStamp } from "../../infra/freshness.js";
+import type { OHLCV } from "../../types/market.js";
+import { HISTORY_INTERVALS, HISTORY_RANGES } from "./stock-history.js";
+type HistoryRange = (typeof HISTORY_RANGES)[number];
+type HistoryInterval = (typeof HISTORY_INTERVALS)[number];
+export interface PriceComparisonSeries {
+    symbol: string;
+    bars: OHLCV[];
+    indexed: number[];
+    provider?: string;
+    providerTimestamp: string;
+    cached: boolean;
+    stale: boolean;
+}
+export interface PriceComparisonDetails {
+    range: HistoryRange;
+    interval: HistoryInterval;
+    baseDate: string;
+    series: PriceComparisonSeries[];
+    unavailableSymbols: string[];
+    freshness: FreshnessStamp;
+}
+declare const params: import("@sinclair/typebox").TObject<{
+    symbols: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>;
+    range: import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"10y" | "1d" | "1mo" | "1y" | "2y" | "3mo" | "5d" | "5y" | "6mo" | "max" | "ytd">[]>;
+    interval: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"15m" | "1d" | "1h" | "1m" | "1mo" | "1wk" | "5m">[]>>;
+}>;
+export declare const priceComparisonTool: AgentTool<typeof params, PriceComparisonDetails>;
+export {};

package/dist/tools/market/price-comparison.js

@@ -0,0 +1,202 @@
+import { Type } from "@sinclair/typebox";
+import { buildFreshnessStamp, formatAsOfLine } from "../../infra/freshness.js";
+import { fetchHistoryWithFallback, HISTORY_INTERVALS, HISTORY_RANGES } from "./stock-history.js";
+const DATE_ALIGNED_INTERVALS = new Set(["1d", "1wk", "1mo"]);
+const params = Type.Object({
+    symbols: Type.Array(Type.String({ description: "Ticker symbol" }), {
+        minItems: 2,
+        maxItems: 6,
+        description: "Ticker symbols to compare",
+    }),
+    range: Type.Union(HISTORY_RANGES.map((range) => Type.Literal(range)), {
+        description: "History range",
+    }),
+    interval: Type.Optional(Type.Union(HISTORY_INTERVALS.map((interval) => Type.Literal(interval)), { description: "Data interval. Default: 1d" })),
+});
+export const priceComparisonTool = {
+    name: "get_price_comparison",
+    label: "Price Comparison",
+    description: "Get aligned indexed price history for multiple ticker symbols",
+    parameters: params,
+    async execute(_toolCallId, args) {
+        const symbols = args.symbols.map((symbol) => symbol.toUpperCase());
+        const interval = args.interval ?? "1d";
+        const fetched = await Promise.all(symbols.map(async (symbol) => ({
+            symbol,
+            result: await fetchHistoryWithFallback(symbol, args.range, interval),
+        })));
+        const available = fetched.flatMap(({ symbol, result }) => result.status === "ok" && result.data.length > 0
+            ? [
+                {
+                    symbol,
+                    bars: result.data,
+                    provider: result.provider,
+                    providerTimestamp: result.timestamp,
+                    cached: result.cached === true,
+                    stale: result.stale === true,
+                },
+            ]
+            : []);
+        let unavailableSymbols = fetched.flatMap(({ symbol, result }) => result.status === "unavailable" || result.data.length === 0 ? [symbol] : []);
+        if (available.length < 2) {
+            const freshness = buildFreshnessStamp({});
+            const unavailableText = unavailableSymbols.join(", ") || symbols.join(", ");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `Price comparison unavailable: fewer than 2 series.`,
+                            `Unavailable symbols: ${unavailableText}`,
+                            formatAsOfLine(freshness),
+                        ].join("\n"),
+                    },
+                ],
+                details: {
+                    range: args.range,
+                    interval,
+                    baseDate: "",
+                    series: [],
+                    unavailableSymbols,
+                    freshness,
+                },
+            };
+        }
+        let survivingAvailable = available;
+        let commonKeys = intersectAlignmentKeys(survivingAvailable, interval);
+        while (survivingAvailable.length >= 2 && commonKeys.size > 0) {
+            const invalidBaselineSymbols = survivingAvailable.flatMap(({ symbol, bars }) => {
+                const baseClose = bars.find((bar) => {
+                    const key = alignmentKey(bar, interval);
+                    return key !== undefined && commonKeys.has(key);
+                })?.close;
+                return typeof baseClose !== "number" || !Number.isFinite(baseClose) || baseClose <= 0
+                    ? [symbol]
+                    : [];
+            });
+            if (invalidBaselineSymbols.length === 0)
+                break;
+            unavailableSymbols = [...new Set([...unavailableSymbols, ...invalidBaselineSymbols])];
+            const invalid = new Set(invalidBaselineSymbols);
+            survivingAvailable = survivingAvailable.filter(({ symbol }) => !invalid.has(symbol));
+            commonKeys = intersectAlignmentKeys(survivingAvailable, interval);
+        }
+        if (survivingAvailable.length < 2) {
+            return unavailableComparison(args.range, interval, unavailableSymbols);
+        }
+        if (commonKeys.size === 0) {
+            unavailableSymbols = [
+                ...new Set([...unavailableSymbols, ...survivingAvailable.map(({ symbol }) => symbol)]),
+            ];
+            return unavailableComparison(args.range, interval, unavailableSymbols);
+        }
+        const series = survivingAvailable.map(({ symbol, bars, provider, providerTimestamp, cached, stale }) => {
+            const alignedBars = bars.filter((bar) => {
+                const key = alignmentKey(bar, interval);
+                return key !== undefined && commonKeys.has(key);
+            });
+            const baseClose = alignedBars[0].close;
+            return {
+                symbol,
+                bars: alignedBars,
+                indexed: alignedBars.map((bar) => (bar.close / baseClose) * 100),
+                provider,
+                providerTimestamp,
+                cached,
+                stale,
+            };
+        });
+        const baseDate = series[0]?.bars[0]?.date ?? "";
+        const latestDate = series[0]?.bars.at(-1)?.date;
+        const staleSeries = series.filter((item) => item.stale);
+        const freshness = buildFreshnessStamp({
+            asOf: latestDate,
+            cached: series.some((item) => item.cached),
+            stale: staleSeries.length > 0,
+            cachedAt: staleSeries.map((item) => item.providerTimestamp).sort()[0],
+        });
+        const rows = series.map(({ symbol, bars, indexed }) => {
+            const first = bars[0]?.close ?? 0;
+            const last = bars.at(-1)?.close ?? 0;
+            const change = (indexed.at(-1) ?? 100) - 100;
+            return `${symbol} | ${first.toFixed(2)} | ${last.toFixed(2)} | ${change.toFixed(2)}%`;
+        });
+        const alignmentLosses = survivingAvailable.flatMap(({ symbol, bars }) => {
+            const dropped = bars.length - commonKeys.size;
+            return dropped / bars.length > 0.3
+                ? [`${symbol} (${dropped}/${bars.length} dates dropped)`]
+                : [];
+        });
+        const alignmentLine = alignmentLosses.length > 0 ? [`Reduced aligned window: ${alignmentLosses.join(", ")}`] : [];
+        const unavailableLine = unavailableSymbols.length > 0
+            ? [`Unavailable symbols: ${unavailableSymbols.join(", ")}`]
+            : [];
+        const staleLine = staleSeries.length > 0
+            ? [
+                `Stale series: ${staleSeries
+                    .map((item) => `${item.symbol} (${item.provider ?? "unknown provider"})`)
+                    .join(", ")}`,
+            ]
+            : [];
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        ...rows,
+                        ...alignmentLine,
+                        ...unavailableLine,
+                        ...staleLine,
+                        formatAsOfLine(freshness),
+                    ].join("\n"),
+                },
+            ],
+            details: {
+                range: args.range,
+                interval,
+                baseDate,
+                series,
+                unavailableSymbols,
+                freshness,
+            },
+        };
+    },
+};
+function intersectAlignmentKeys(series, interval) {
+    const commonKeys = new Set(series[0]?.bars.flatMap((bar) => {
+        const key = alignmentKey(bar, interval);
+        return key === undefined ? [] : [key];
+    }) ?? []);
+    for (const candidate of series.slice(1)) {
+        const candidateKeys = new Set(candidate.bars.flatMap((bar) => {
+            const key = alignmentKey(bar, interval);
+            return key === undefined ? [] : [key];
+        }));
+        for (const key of commonKeys) {
+            if (!candidateKeys.has(key))
+                commonKeys.delete(key);
+        }
+    }
+    return commonKeys;
+}
+function alignmentKey(bar, interval) {
+    if (DATE_ALIGNED_INTERVALS.has(interval))
+        return bar.date;
+    return Number.isFinite(bar.timestamp) ? bar.timestamp : undefined;
+}
+function unavailableComparison(range, interval, unavailableSymbols) {
+    const freshness = buildFreshnessStamp({});
+    return {
+        content: [
+            {
+                type: "text",
+                text: [
+                    "Price comparison unavailable: fewer than 2 usable aligned series.",
+                    `Unavailable symbols: ${unavailableSymbols.join(", ")}`,
+                    formatAsOfLine(freshness),
+                ].join("\n"),
+            },
+        ],
+        details: { range, interval, baseDate: "", series: [], unavailableSymbols, freshness },
+    };
+}

package/dist/tools/market/stock-history.d.ts

@@ -1,9 +1,24 @@
 import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { type FreshnessStamp } from "../../infra/freshness.js";
+import type { ProviderResult } from "../../runtime/evidence.js";
 import type { OHLCV } from "../../types/market.js";
+export declare const HISTORY_RANGES: readonly ["1d", "5d", "1mo", "3mo", "6mo", "ytd", "1y", "2y", "5y", "10y", "max"];
+export declare const HISTORY_INTERVALS: readonly ["1m", "5m", "15m", "1h", "1d", "1wk", "1mo"];
+export declare function hasIntradayHistoryFallback(interval: (typeof HISTORY_INTERVALS)[number]): boolean;
+export declare function fetchHistoryWithFallback(symbol: string, range: (typeof HISTORY_RANGES)[number], interval: (typeof HISTORY_INTERVALS)[number]): Promise<ProviderResult<OHLCV[]>>;
+type HistoryRange = (typeof HISTORY_RANGES)[number];
+export declare function historyRangeToStart(range: HistoryRange, now?: Date): string | undefined;
 declare const params: import("@sinclair/typebox").TObject<{
     symbol: import("@sinclair/typebox").TString;
-    range: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"6mo" | "1d" | "ytd" | "5d" | "1mo" | "3mo" | "1y" | "2y" | "5y" | "10y" | "max">[]>>;
-    interval: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"1d" | "1mo" | "1wk" | "1m" | "5m" | "15m" | "1h">[]>>;
+    range: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"10y" | "1d" | "1mo" | "1y" | "2y" | "3mo" | "5d" | "5y" | "6mo" | "max" | "ytd">[]>>;
+    interval: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"15m" | "1d" | "1h" | "1m" | "1mo" | "1wk" | "5m">[]>>;
 }>;
-export declare const stockHistoryTool: AgentTool<typeof params, OHLCV[]>;
+export interface StaleStockHistoryDetails {
+    bars: OHLCV[];
+    provider?: string;
+    providerTimestamp: string;
+    stale: true;
+    freshness: FreshnessStamp;
+}
+export declare const stockHistoryTool: AgentTool<typeof params, OHLCV[] | StaleStockHistoryDetails>;
 export {};

package/dist/tools/market/stock-history.js

@@ -1,11 +1,15 @@
 import { Type } from "@sinclair/typebox";
 import { getConfig } from "../../config.js";
+import { buildFreshnessStamp, formatAsOfLine } from "../../infra/freshness.js";
+import { isOverSoftThreshold } from "../../infra/lse-byte-budget.js";
 import { getDailyHistory } from "../../providers/alpha-vantage.js";
+import { getLseCandles, toLseTimeframe } from "../../providers/lse.js";
+import { ProviderCredentialError } from "../../providers/provider-credential-error.js";
 import { withFallback } from "../../providers/with-fallback.js";
 import { wrapProvider } from "../../providers/wrap-provider.js";
 import { getHistory } from "../../providers/yahoo-finance.js";
 const DAILY_INTERVALS = new Set(["1d", "1wk", "1mo"]);
-const HISTORY_RANGES = [
+export const HISTORY_RANGES = [
     "1d",
     "5d",
     "1mo",
@@ -18,7 +22,112 @@ const HISTORY_RANGES = [
     "10y",
     "max",
 ];
-const HISTORY_INTERVALS = ["1m", "5m", "15m", "1h", "1d", "1wk", "1mo"];
+export const HISTORY_INTERVALS = ["1m", "5m", "15m", "1h", "1d", "1wk", "1mo"];
+function lseFallbackEligible(interval) {
+    return (toLseTimeframe(interval) !== undefined && !!getConfig().lseApiKey && !isOverSoftThreshold());
+}
+export function hasIntradayHistoryFallback(interval) {
+    return !DAILY_INTERVALS.has(interval) && lseFallbackEligible(interval);
+}
+export async function fetchHistoryWithFallback(symbol, range, interval) {
+    const apiKey = getConfig().alphaVantageApiKey;
+    const lseTimeframe = toLseTimeframe(interval);
+    const lseEligible = lseTimeframe !== undefined && lseFallbackEligible(interval);
+    const getLseHistory = async (timeframe) => {
+        let rows;
+        try {
+            const start = historyRangeToStart(range);
+            rows = await getLseCandles(symbol, timeframe, {
+                ...(start === undefined ? {} : { start }),
+                order: "asc",
+            });
+        }
+        catch (error) {
+            if (error instanceof ProviderCredentialError && error.provider === "lse") {
+                throw new Error(`LSE credential ${error.reason}`);
+            }
+            throw error;
+        }
+        return rows.map((row) => {
+            // Verified UTC from a live 2026-07-14 1h capture: naive 08:00–23:00 bars
+            // match the 04:00–19:00 ET extended session. Treat naive values as UTC.
+            const utcTimestamp = /(?:Z|[+-]\d{2}:\d{2})$/i.test(row.ts) ? row.ts : `${row.ts}Z`;
+            const timestamp = Date.parse(utcTimestamp) / 1_000;
+            return {
+                date: row.ts.slice(0, 10),
+                ...(Number.isFinite(timestamp) ? { timestamp } : {}),
+                open: row.open,
+                high: row.high,
+                low: row.low,
+                close: row.close,
+                volume: row.volume,
+            };
+        });
+    };
+    if (DAILY_INTERVALS.has(interval)) {
+        const yahooEntry = {
+            provider: "yahoo",
+            fn: () => getHistory(symbol, range, interval),
+        };
+        const entries = [yahooEntry];
+        if (apiKey) {
+            entries.push({
+                provider: "alphavantage",
+                fn: () => getDailyHistory(symbol, apiKey, range),
+            });
+        }
+        if (lseEligible && lseTimeframe !== undefined) {
+            entries.push({ provider: "lse", fn: () => getLseHistory(lseTimeframe) });
+        }
+        return entries.length === 1
+            ? wrapProvider(yahooEntry.provider, yahooEntry.fn)
+            : withFallback(entries);
+    }
+    if (lseEligible && lseTimeframe !== undefined) {
+        return withFallback([
+            { provider: "yahoo", fn: () => getHistory(symbol, range, interval) },
+            { provider: "lse", fn: () => getLseHistory(lseTimeframe) },
+        ]);
+    }
+    return wrapProvider("yahoo", () => getHistory(symbol, range, interval));
+}
+export function historyRangeToStart(range, now = new Date()) {
+    if (range === "max")
+        return undefined;
+    const start = new Date(now);
+    switch (range) {
+        case "1d":
+            start.setUTCDate(start.getUTCDate() - 1);
+            break;
+        case "5d":
+            start.setUTCDate(start.getUTCDate() - 5);
+            break;
+        case "1mo":
+            start.setUTCMonth(start.getUTCMonth() - 1);
+            break;
+        case "3mo":
+            start.setUTCMonth(start.getUTCMonth() - 3);
+            break;
+        case "6mo":
+            start.setUTCMonth(start.getUTCMonth() - 6);
+            break;
+        case "ytd":
+            return `${start.getUTCFullYear()}-01-01`;
+        case "1y":
+            start.setUTCFullYear(start.getUTCFullYear() - 1);
+            break;
+        case "2y":
+            start.setUTCFullYear(start.getUTCFullYear() - 2);
+            break;
+        case "5y":
+            start.setUTCFullYear(start.getUTCFullYear() - 5);
+            break;
+        case "10y":
+            start.setUTCFullYear(start.getUTCFullYear() - 10);
+            break;
+    }
+    return start.toISOString().slice(0, 10);
+}
 const params = Type.Object({
     symbol: Type.String({ description: "Stock ticker symbol (e.g. AAPL, MSFT)" }),
     range: Type.Optional(Type.Union(HISTORY_RANGES.map((range) => Type.Literal(range)), {
@@ -37,21 +146,9 @@ export const stockHistoryTool = {
         const symbol = args.symbol.toUpperCase();
         const range = args.range ?? "6mo";
         const interval = args.interval ?? "1d";
-        const apiKey = getConfig().alphaVantageApiKey;
-        let result;
-        if (DAILY_INTERVALS.has(interval) && apiKey) {
-            // Daily or above — can fall back to Alpha Vantage
-            result = await withFallback([
-                { provider: "yahoo", fn: () => getHistory(symbol, range, interval) },
-                { provider: "alphavantage", fn: () => getDailyHistory(symbol, apiKey, range) },
-            ]);
-        }
-        else {
-            // Intraday — no cross-provider fallback
-            result = await wrapProvider("yahoo", () => getHistory(symbol, range, interval));
-        }
+        const result = await fetchHistoryWithFallback(symbol, range, interval);
         if (result.status === "unavailable") {
-            const intradayNote = !DAILY_INTERVALS.has(interval)
+            const intradayNote = !DAILY_INTERVALS.has(interval) && !hasIntradayHistoryFallback(interval)
                 ? ` No alternate source for ${interval} data.`
                 : "";
             return {
@@ -65,9 +162,16 @@ export const stockHistoryTool = {
             };
         }
         const bars = result.data;
+        const freshness = buildFreshnessStamp({
+            asOf: bars.at(-1)?.timestamp ?? bars.at(-1)?.date,
+            stale: result.stale,
+            cached: result.cached,
+            cachedAt: result.stale ? result.timestamp : undefined,
+        });
         const summary = [
             `${symbol} — ${bars.length} bars (${range}, ${interval})`,
             `Period: ${bars[0]?.date} to ${bars[bars.length - 1]?.date}`,
+            ...(result.stale ? [`Data status: Stale cache. ${formatAsOfLine(freshness)}`] : []),
         ];
         // Include last 10 bars as sample
         const recent = bars.slice(-10);
@@ -75,6 +179,17 @@ export const stockHistoryTool = {
             .map((b) => `${b.date} | O:${b.open.toFixed(2)} H:${b.high.toFixed(2)} L:${b.low.toFixed(2)} C:${b.close.toFixed(2)} V:${b.volume.toLocaleString()}`)
             .join("\n");
         const text = [...summary, "", "Recent bars:", table].join("\n");
-        return { content: [{ type: "text", text }], details: bars };
+        return {
+            content: [{ type: "text", text }],
+            details: result.stale
+                ? {
+                    bars,
+                    provider: result.provider,
+                    providerTimestamp: result.timestamp,
+                    stale: true,
+                    freshness,
+                }
+                : bars,
+        };
     },
 };

package/dist/tools/portfolio/correlation.d.ts

@@ -4,7 +4,7 @@ export declare function computeCorrelation(returnsA: number[], returnsB: number[
 export declare function alignReturnsByDate(historiesBySymbol: Map<string, OHLCV[]>, minOverlap?: number): Map<string, number[]>;
 declare const params: import("@sinclair/typebox").TObject<{
     symbols: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>;
-    period: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"6mo" | "1y" | "2y">[]>>;
+    period: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"1y" | "2y" | "6mo">[]>>;
 }>;
 export declare const correlationTool: AgentTool<typeof params>;
 export {};

package/dist/tools/portfolio/risk-analysis.d.ts

@@ -2,7 +2,7 @@ import type { AgentTool } from "@earendil-works/pi-agent-core";
 import type { RiskMetrics } from "../../types/portfolio.js";
 declare const params: import("@sinclair/typebox").TObject<{
     symbol: import("@sinclair/typebox").TString;
-    period: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"6mo" | "1y" | "2y">[]>>;
+    period: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"1y" | "2y" | "6mo">[]>>;
 }>;
 export declare const riskAnalysisTool: AgentTool<typeof params, RiskMetrics | null>;
 export declare function computeRiskMetrics(symbol: string, closes: number[]): RiskMetrics;

package/dist/types/market.d.ts

@@ -24,6 +24,8 @@ export interface StockQuote {
 }
 export interface OHLCV {
     date: string;
+    /** UTC epoch seconds; present when the provider supplies per-bar timestamps. */
+    timestamp?: number;
     open: number;
     high: number;
     low: number;