opencandle 0.11.1 → 0.13.0

package/dist/gui/server/model-setup.js

@@ -0,0 +1,154 @@
+import { ModelRegistry } from "@earendil-works/pi-coding-agent";
+import { persistProviderCredential } from "../../onboarding/connect.js";
+import { getCredentialSource, isApiKeyProvider, PROVIDERS, } from "../../onboarding/providers.js";
+import { validateModelKey, } from "../../onboarding/validate-model-key.js";
+import { validateCredential } from "../../onboarding/validation.js";
+export const modelSetupProviders = [
+    {
+        id: "google",
+        label: "Google Gemini",
+        envVar: "GEMINI_API_KEY",
+        defaultProvider: "google",
+        defaultModel: "gemini-2.5-flash",
+        signupUrl: "https://aistudio.google.com/app/apikey",
+    },
+    {
+        id: "openai",
+        label: "OpenAI",
+        envVar: "OPENAI_API_KEY",
+        defaultProvider: "openai",
+        defaultModel: "gpt-5-mini",
+        signupUrl: "https://platform.openai.com/api-keys",
+    },
+    {
+        id: "anthropic",
+        label: "Anthropic",
+        envVar: "ANTHROPIC_API_KEY",
+        defaultProvider: "anthropic",
+        defaultModel: "claude-haiku-4-5",
+        signupUrl: "https://console.anthropic.com/settings/keys",
+    },
+];
+export function buildModelSetupState(registry, currentModel) {
+    registry.refresh();
+    const availableModels = sortModels(registry.getAvailable()).map((model) => ({
+        provider: model.provider,
+        id: model.id,
+        label: `${model.provider}/${model.id}`,
+    }));
+    const requirement = currentModel && registry.hasConfiguredAuth(currentModel)
+        ? "ready"
+        : availableModels.length > 0
+            ? "select_model"
+            : "connect_auth";
+    return {
+        requirement,
+        // A fresh session still carries a placeholder model with no usable
+        // credentials; reporting it would render its raw id as the composer label.
+        currentModel: currentModel && registry.hasConfiguredAuth(currentModel)
+            ? `${currentModel.provider}/${currentModel.id}`
+            : undefined,
+        providers: modelSetupProviders,
+        availableModels,
+    };
+}
+export function findPreferredModel(registry, provider) {
+    const available = sortModels(registry.getAvailable(), provider.defaultProvider);
+    return (available.find((model) => model.provider === provider.defaultProvider && model.id === provider.defaultModel) ?? available.find((model) => model.provider === provider.defaultProvider));
+}
+export function sortModels(models, preferredProvider) {
+    return [...models].sort((a, b) => {
+        const aPreferred = preferredProvider && a.provider === preferredProvider ? -1 : 0;
+        const bPreferred = preferredProvider && b.provider === preferredProvider ? -1 : 0;
+        if (aPreferred !== bPreferred)
+            return aPreferred - bPreferred;
+        const byProvider = a.provider.localeCompare(b.provider);
+        return byProvider !== 0 ? byProvider : a.id.localeCompare(b.id);
+    });
+}
+export function createModelSetupController({ role, getSession, getSessionManager, broadcastState, }) {
+    function ensureWriter() {
+        if (role !== "writer")
+            throw new Error("Read-only follower mode");
+    }
+    function buildCurrentModelSetupState() {
+        const session = getSession();
+        return buildModelSetupState(new ModelRegistry(session.modelRuntime), session.model);
+    }
+    async function handleSaveModelApiKey(providerId, apiKey) {
+        ensureWriter();
+        const provider = modelSetupProviders.find((candidate) => candidate.id === providerId);
+        if (!provider)
+            throw new Error(`Unknown model provider: ${providerId}`);
+        const trimmed = apiKey.trim();
+        if (!trimmed)
+            throw new Error(`Paste a ${provider.label} API key first.`);
+        const validation = await validateModelKey(provider.id, trimmed);
+        if (validation.status === "invalid") {
+            throw new Error(`Key was rejected by ${validation.providerLabel}. The existing configuration was not changed.`);
+        }
+        const session = getSession();
+        await session.modelRuntime.login(provider.id, "api_key", {
+            prompt: async () => trimmed,
+            notify: () => { },
+        });
+        const modelRegistry = new ModelRegistry(session.modelRuntime);
+        const model = findPreferredModel(modelRegistry, provider);
+        if (!model) {
+            throw new Error(`Saved the ${provider.label} key, but no ${provider.label} models are available yet.`);
+        }
+        await session.setModel(model);
+        await session.settingsManager.flush();
+        getSessionManager().appendCustomMessageEntry("opencandle-model-setup", validation.status === "transient"
+            ? `Saved — couldn't verify (network issue). Connected ${provider.label} and selected ${model.provider}/${model.id}.`
+            : `Connected ${provider.label} and selected ${model.provider}/${model.id}.`, true, { source: "gui", provider: provider.id, model: `${model.provider}/${model.id}` });
+        broadcastState();
+    }
+    async function handleSaveProviderApiKey(providerId, apiKey) {
+        ensureWriter();
+        const descriptor = PROVIDERS.find((candidate) => candidate.id === providerId);
+        if (!descriptor)
+            throw new Error(`Unknown provider: ${providerId}`);
+        if (!isApiKeyProvider(descriptor)) {
+            throw new Error(`${descriptor.displayName} is not configured with an API key.`);
+        }
+        if (getCredentialSource(descriptor.id) === "env") {
+            throw new Error(`${descriptor.displayName} is set via the ${descriptor.envVar} environment variable. Unset it to override here.`);
+        }
+        const trimmed = apiKey.trim();
+        if (!trimmed)
+            throw new Error(`Paste a ${descriptor.displayName} API key first.`);
+        const validation = await validateCredential(descriptor.id, trimmed);
+        if (validation.status === "invalid") {
+            const statusHint = validation.httpStatus !== undefined ? ` (HTTP ${validation.httpStatus})` : "";
+            const messageHint = validation.message ? ` — ${validation.message}` : "";
+            throw new Error(`${descriptor.displayName} rejected the key${statusHint}${messageHint}. The existing configuration was not changed.`);
+        }
+        persistProviderCredential(descriptor.id, trimmed);
+        const verifiedNote = validation.status === "transient"
+            ? `Saved ${descriptor.displayName} key but couldn't verify it (${validation.reason}). The next request will surface any issue.`
+            : `Connected ${descriptor.displayName}. Key saved to ~/.opencandle/config.json.`;
+        getSessionManager().appendCustomMessageEntry("opencandle-provider-setup", verifiedNote, true, {
+            source: "gui",
+            provider: descriptor.id,
+            status: validation.status,
+        });
+        broadcastState();
+    }
+    async function handleSelectModel(provider, modelId) {
+        ensureWriter();
+        const session = getSession();
+        await session.modelRuntime.refresh();
+        const model = session.modelRuntime.getModel(provider, modelId);
+        if (!model)
+            throw new Error(`Unknown model: ${provider}/${modelId}`);
+        await session.setModel(model);
+        await session.settingsManager.flush();
+    }
+    return {
+        buildCurrentModelSetupState,
+        handleSaveModelApiKey,
+        handleSaveProviderApiKey,
+        handleSelectModel,
+    };
+}

package/dist/gui/server/private-api-access.d.ts

@@ -0,0 +1,6 @@
+import type { IncomingHttpHeaders } from "node:http";
+export declare function isLoopbackAddress(remoteAddress: string | undefined): boolean;
+export declare function isTrustedPrivateApiRequest(headers: IncomingHttpHeaders, sessionToken: string, remoteAddress: string | undefined, options?: {
+    allowRemote?: boolean;
+}): boolean;
+export declare function privateApiCookieHeader(sessionToken: string): string;

package/dist/gui/server/private-api-access.js

@@ -0,0 +1,53 @@
+const PRIVATE_API_COOKIE = "opencandle_gui_session";
+export function isLoopbackAddress(remoteAddress) {
+    if (remoteAddress == null || remoteAddress === "")
+        return false;
+    return (remoteAddress === "::1" ||
+        remoteAddress === "localhost" ||
+        remoteAddress.startsWith("127.") ||
+        remoteAddress.startsWith("::ffff:127."));
+}
+export function isTrustedPrivateApiRequest(headers, sessionToken, remoteAddress, options = {}) {
+    if (!options.allowRemote && !isLoopbackAddress(remoteAddress))
+        return false;
+    if (cookieValue(headers.cookie, PRIVATE_API_COOKIE) !== sessionToken)
+        return false;
+    const fetchSite = headerValue(headers["sec-fetch-site"]);
+    if (fetchSite != null && fetchSite !== "same-origin" && fetchSite !== "none")
+        return false;
+    const origin = headerValue(headers.origin);
+    const host = headerValue(headers.host);
+    if (origin != null && host != null) {
+        try {
+            if (new URL(origin).host !== host)
+                return false;
+        }
+        catch {
+            return false;
+        }
+    }
+    return true;
+}
+export function privateApiCookieHeader(sessionToken) {
+    return `${PRIVATE_API_COOKIE}=${encodeURIComponent(sessionToken)}; Path=/; HttpOnly; SameSite=Strict`;
+}
+function cookieValue(header, name) {
+    const value = Array.isArray(header) ? header.join("; ") : header;
+    if (value == null)
+        return undefined;
+    for (const part of value.split(";")) {
+        const [rawKey, ...rawValue] = part.trim().split("=");
+        if (rawKey === name) {
+            try {
+                return decodeURIComponent(rawValue.join("="));
+            }
+            catch {
+                return undefined;
+            }
+        }
+    }
+    return undefined;
+}
+function headerValue(value) {
+    return Array.isArray(value) ? value[0] : value;
+}

package/dist/gui/server/projector.d.ts

@@ -0,0 +1,49 @@
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+export interface DashboardState {
+    knownSymbols: string[];
+    watchlist: Array<{
+        symbol: string;
+        quote: Record<string, unknown> | null;
+        pinned: boolean;
+        lastSeen: string;
+    }>;
+    activeAnalyses: Array<{
+        workflowId: string;
+        workflow: string;
+        symbol?: string;
+        analystsTotal: number;
+        analystsDone: number;
+        startedAt: string;
+    }>;
+    recentResearch: Array<{
+        sessionId: string;
+        workflow: string;
+        symbol?: string;
+        completedAt: string;
+    }>;
+    dataQuality: {
+        softGaps: Array<{
+            provider: string;
+            lastSeen: string;
+        }>;
+        hardSkips: Array<{
+            provider: string;
+            lastSeen: string;
+        }>;
+    };
+    lastTurn?: {
+        routeKind: string;
+        workflow?: string;
+        symbols: string[];
+        slotSources: Record<string, number>;
+        priorTurnCount: number;
+        savedStateIncluded?: boolean;
+        attachmentCount?: number;
+        validation?: {
+            passed: boolean;
+            mismatchCount: number;
+        };
+    };
+}
+export declare function createEmptyDashboardState(): DashboardState;
+export declare function projectDashboard(entries: SessionEntry[], sessionId?: string, savedSymbols?: string[]): DashboardState;

package/dist/gui/server/projector.js

@@ -0,0 +1,296 @@
+const DIRECT_TOOL_GAP_PROVIDERS = {
+    get_company_overview: "alpha_vantage",
+    get_financials: "alpha_vantage",
+    get_earnings: "alpha_vantage",
+    compute_dcf: "alpha_vantage",
+    compare_companies: "alpha_vantage",
+    get_economic_data: "fred",
+    get_twitter_sentiment: "twitter",
+    get_reddit_sentiment: "reddit",
+};
+export function createEmptyDashboardState() {
+    return {
+        knownSymbols: [],
+        watchlist: [],
+        activeAnalyses: [],
+        recentResearch: [],
+        dataQuality: { softGaps: [], hardSkips: [] },
+    };
+}
+export function projectDashboard(entries, sessionId = "local", savedSymbols = []) {
+    const state = createEmptyDashboardState();
+    let pendingAttachmentCount;
+    let pendingAttachmentUserSeen = false;
+    for (const entry of entries) {
+        if (entry.type === "message") {
+            projectMessage(state, entry.message, entry.timestamp, sessionId);
+            const message = entry.message;
+            if (pendingAttachmentCount !== undefined) {
+                if (message.role === "user")
+                    pendingAttachmentUserSeen = true;
+                else if (pendingAttachmentUserSeen) {
+                    pendingAttachmentCount = undefined;
+                    pendingAttachmentUserSeen = false;
+                }
+            }
+            continue;
+        }
+        if (entry.type === "custom" && entry.customType === "opencandle-workflow") {
+            const data = asRecord(entry.data);
+            const workflow = stringValue(data.workflow) ?? stringValue(data.workflowType) ?? "workflow";
+            const slots = asRecord(data.resolvedSlots);
+            const symbol = stringValue(slots.symbol) ?? firstString(slots.symbols);
+            state.activeAnalyses.push({
+                workflowId: stringValue(data.runId) ?? entry.id,
+                workflow,
+                symbol,
+                analystsTotal: numberValue(data.analystsTotal) ?? 0,
+                analystsDone: 0,
+                startedAt: entry.timestamp,
+            });
+            continue;
+        }
+        if (entry.type === "custom" && entry.customType === "opencandle-user-input") {
+            const attachments = asArray(asRecord(entry.data).attachments);
+            pendingAttachmentCount = attachments.length > 0 ? attachments.length : undefined;
+            pendingAttachmentUserSeen = false;
+            if (state.lastTurn) {
+                if (pendingAttachmentCount !== undefined)
+                    state.lastTurn.attachmentCount = pendingAttachmentCount;
+                else
+                    delete state.lastTurn.attachmentCount;
+            }
+            continue;
+        }
+        if (entry.type === "custom" && entry.customType === "opencandle-route-context") {
+            state.lastTurn = projectRouteContext(entry.data, pendingAttachmentCount);
+            addKnownSymbols(state, asArray(asRecord(asRecord(entry.data).entities).symbols));
+            pendingAttachmentCount = undefined;
+            pendingAttachmentUserSeen = false;
+            continue;
+        }
+        if (pendingAttachmentUserSeen) {
+            pendingAttachmentCount = undefined;
+            pendingAttachmentUserSeen = false;
+        }
+        if (entry.type === "custom" && entry.customType === "opencandle-validation") {
+            if (state.lastTurn) {
+                const data = asRecord(entry.data);
+                state.lastTurn.validation = {
+                    passed: Boolean(data.passed),
+                    mismatchCount: asArray(data.mismatches).length,
+                };
+            }
+            continue;
+        }
+        if (entry.type === "custom" && entry.customType === "opencandle-analyst-step") {
+            // debate_* stages share this entry type but are not analysts.
+            const stage = stringValue(asRecord(entry.data).stage) ?? "";
+            const active = state.activeAnalyses[state.activeAnalyses.length - 1];
+            if (active && stage.startsWith("analyst_")) {
+                const nextDone = active.analystsDone + 1;
+                active.analystsDone =
+                    active.analystsTotal > 0 ? Math.min(nextDone, active.analystsTotal) : nextDone;
+            }
+            continue;
+        }
+        if (entry.type === "custom" && entry.customType === "opencandle-turn-gap") {
+            // The accumulator writes a single combined annotation string with one
+            // [OPENCANDLE_SKIPPED ... provider=X ...] tag per fallback provider.
+            // Older shapes may carry { softGaps: [...] } or { provider } directly —
+            // accept either to stay forward/backward compatible.
+            const data = asRecord(entry.data);
+            const annotation = stringValue(data.annotation);
+            if (annotation) {
+                for (const provider of parseSkippedProviders(annotation)) {
+                    upsertProviderGap(state.dataQuality.softGaps, provider, entry.timestamp);
+                }
+            }
+            for (const gap of asArray(data.softGaps)) {
+                const provider = stringValue(asRecord(gap).provider);
+                if (provider)
+                    upsertProviderGap(state.dataQuality.softGaps, provider, entry.timestamp);
+            }
+            const provider = stringValue(data.provider);
+            if (provider)
+                upsertProviderGap(state.dataQuality.softGaps, provider, entry.timestamp);
+        }
+        if (entry.type === "custom" && entry.customType === "opencandle-quote-refresh") {
+            const data = asRecord(entry.data);
+            projectQuote(state, stringValue(data.symbol), asRecord(data.value), asArray(data.content), entry.timestamp);
+        }
+    }
+    addKnownSymbols(state, savedSymbols);
+    return state;
+}
+function projectRouteContext(data, attachmentCount) {
+    const record = asRecord(data);
+    const entities = asRecord(record.entities);
+    const routeKind = stringValue(record.routeKind) ?? "unknown";
+    const workflow = stringValue(record.workflow);
+    const slots = asRecord(record.slots);
+    const slotSources = {};
+    for (const slot of Object.values(slots)) {
+        const source = stringValue(asRecord(slot).source);
+        if (!source)
+            continue;
+        slotSources[source] = (slotSources[source] ?? 0) + 1;
+    }
+    const symbols = stringArray(entities.symbols);
+    const priorTurnCount = asArray(record.priorTurns).length;
+    return {
+        routeKind,
+        ...(workflow ? { workflow } : {}),
+        symbols,
+        slotSources,
+        priorTurnCount,
+        ...(typeof record.savedStateIncluded === "boolean"
+            ? { savedStateIncluded: record.savedStateIncluded }
+            : {}),
+        ...(attachmentCount !== undefined ? { attachmentCount } : {}),
+    };
+}
+function projectMessage(state, message, timestamp, sessionId) {
+    if (message.role === "toolResult") {
+        projectToolResult(state, message, timestamp);
+        return;
+    }
+    if (message.role === "assistant" && message.stopReason === "stop") {
+        const active = state.activeAnalyses.shift();
+        if (active) {
+            state.recentResearch.unshift({
+                sessionId,
+                workflow: active.workflow,
+                symbol: active.symbol,
+                completedAt: timestamp,
+            });
+        }
+    }
+}
+function projectToolResult(state, message, timestamp) {
+    if (message.toolName === "get_stock_quote") {
+        const rawDetails = asRecord(message.details);
+        const nestedValue = asRecord(rawDetails.value);
+        const details = Object.keys(nestedValue).length > 0 ? nestedValue : rawDetails;
+        projectQuote(state, stringValue(details.symbol), details, message.content, timestamp);
+    }
+    const text = message.content
+        .filter((part) => part.type === "text")
+        .map((part) => part.text)
+        .join("\n");
+    for (const provider of parseSoftGapProviders(text)) {
+        upsertProviderGap(state.dataQuality.softGaps, provider, timestamp);
+    }
+    for (const provider of parseCredentialRequiredProviders(text)) {
+        upsertProviderGap(state.dataQuality.hardSkips, provider, timestamp);
+    }
+    const provider = inferDirectToolGapProvider(message.toolName, text);
+    if (provider)
+        upsertProviderGap(state.dataQuality.softGaps, provider, timestamp);
+}
+function upsertProviderGap(gaps, provider, lastSeen) {
+    const existing = gaps.find((gap) => gap.provider === provider);
+    if (!existing) {
+        gaps.push({ provider, lastSeen });
+        return;
+    }
+    const existingTime = Date.parse(existing.lastSeen);
+    const nextTime = Date.parse(lastSeen);
+    if (!Number.isFinite(existingTime) || (Number.isFinite(nextTime) && nextTime > existingTime)) {
+        existing.lastSeen = lastSeen;
+    }
+}
+function projectQuote(state, symbolHint, details, content, timestamp) {
+    const symbol = symbolHint ?? inferSymbolFromContent(content);
+    if (!symbol)
+        return;
+    const normalizedSymbol = normalizeSymbol(symbol);
+    if (!normalizedSymbol)
+        return;
+    addKnownSymbols(state, [normalizedSymbol]);
+    const existing = state.watchlist.find((row) => row.symbol === normalizedSymbol);
+    const row = {
+        symbol: normalizedSymbol,
+        quote: Object.keys(details).length > 0 ? details : null,
+        pinned: existing?.pinned ?? false,
+        lastSeen: timestamp,
+    };
+    if (existing)
+        Object.assign(existing, row);
+    else
+        state.watchlist.push(row);
+}
+function parseCredentialRequiredProviders(text) {
+    const providers = [];
+    const re = /\[OPENCANDLE_CREDENTIAL_REQUIRED[^\]]*provider=([a-z0-9_-]+)/gi;
+    while (true) {
+        const match = re.exec(text);
+        if (!match)
+            break;
+        providers.push(match[1]);
+    }
+    return providers;
+}
+function parseSkippedProviders(text) {
+    return parseSoftGapProviders(text);
+}
+function parseSoftGapProviders(text) {
+    const providers = [];
+    const re = /\[OPENCANDLE_(?:SKIPPED|SOFT_DEGRADED|EXTERNAL_TOOL_REQUIRED)[^\]]*provider=([a-z0-9_-]+)/gi;
+    while (true) {
+        const match = re.exec(text);
+        if (!match)
+            break;
+        providers.push(match[1]);
+    }
+    return providers;
+}
+function inferDirectToolGapProvider(toolName, text) {
+    if (!toolName || !/(?:⚠|unavailable|No .*data found|EXTERNAL_TOOL_SETUP)/i.test(text)) {
+        return undefined;
+    }
+    return DIRECT_TOOL_GAP_PROVIDERS[toolName];
+}
+function inferSymbolFromContent(content) {
+    const text = content.find((part) => part.type === "text")?.text;
+    const match = text?.match(/^([A-Z]{1,8})\b/);
+    return match?.[1];
+}
+function addKnownSymbols(state, values) {
+    for (const value of values) {
+        const symbol = normalizeSymbol(value);
+        if (!symbol || state.knownSymbols.includes(symbol))
+            continue;
+        if (state.knownSymbols.length >= 100)
+            return;
+        state.knownSymbols.push(symbol);
+    }
+}
+function normalizeSymbol(value) {
+    if (typeof value !== "string")
+        return null;
+    const normalized = value.trim().toUpperCase();
+    return normalized ? normalized : null;
+}
+function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : {};
+}
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function stringValue(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function firstString(value) {
+    return Array.isArray(value) ? value.find((item) => typeof item === "string") : undefined;
+}
+function stringArray(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === "string")
+        : [];
+}
+function numberValue(value) {
+    return typeof value === "number" ? value : undefined;
+}

package/dist/gui/server/prompt-observation.d.ts

@@ -0,0 +1,8 @@
+import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+export interface PromptObservation {
+    userTexts: string[];
+    sawAssistantOrTool: boolean;
+}
+export declare function createPromptObservation(): PromptObservation;
+export declare function observePromptEvent(observation: PromptObservation, event: AgentSessionEvent): void;
+export declare function selectReplayPrompt(observation: PromptObservation, originalPrompt: string): string | undefined;

package/dist/gui/server/prompt-observation.js

@@ -0,0 +1,43 @@
+export function createPromptObservation() {
+    return {
+        userTexts: [],
+        sawAssistantOrTool: false,
+    };
+}
+export function observePromptEvent(observation, event) {
+    if (event.type === "message_start") {
+        const message = event.message;
+        if (message.role === "user") {
+            observation.userTexts.push(messageTextFromContent(message.content));
+            return;
+        }
+        if (message.role === "assistant") {
+            observation.sawAssistantOrTool = true;
+        }
+        return;
+    }
+    if (event.type === "tool_execution_start") {
+        observation.sawAssistantOrTool = true;
+    }
+}
+export function selectReplayPrompt(observation, originalPrompt) {
+    if (observation.sawAssistantOrTool)
+        return undefined;
+    const original = originalPrompt.trim();
+    const text = [...observation.userTexts]
+        .reverse()
+        .map((candidate) => candidate.trim())
+        .find((candidate) => candidate.length > 0 && candidate !== original);
+    return text || undefined;
+}
+function messageTextFromContent(content) {
+    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("");
+}

package/dist/gui/server/quote-snapshot-store.d.ts

@@ -0,0 +1,14 @@
+import type { MarketStateQuoteSnapshot } from "./market-state-api.js";
+export declare class QuoteSnapshotStore {
+    private readonly build;
+    private readonly maxAgeMs;
+    private readonly now;
+    private snapshot;
+    private fetchedAtMs;
+    private inFlight;
+    private invalidationVersion;
+    constructor(build: () => Promise<MarketStateQuoteSnapshot>, maxAgeMs?: number, now?: () => number);
+    get(): Promise<MarketStateQuoteSnapshot>;
+    invalidate(): void;
+    private refresh;
+}

package/dist/gui/server/quote-snapshot-store.js

@@ -0,0 +1,49 @@
+export class QuoteSnapshotStore {
+    build;
+    maxAgeMs;
+    now;
+    snapshot = null;
+    fetchedAtMs = 0;
+    inFlight = null;
+    invalidationVersion = 0;
+    constructor(build, maxAgeMs = 60_000, now = Date.now) {
+        this.build = build;
+        this.maxAgeMs = maxAgeMs;
+        this.now = now;
+    }
+    async get() {
+        if (this.snapshot == null)
+            return this.refresh();
+        if (this.now() - this.fetchedAtMs >= this.maxAgeMs) {
+            // Stale-while-revalidate: serve the old snapshot now, refresh in the background.
+            this.refresh().catch(() => { });
+        }
+        return this.snapshot;
+    }
+    invalidate() {
+        this.invalidationVersion += 1;
+        this.snapshot = null;
+        this.fetchedAtMs = 0;
+        this.inFlight = null;
+    }
+    refresh() {
+        if (this.inFlight)
+            return this.inFlight;
+        const version = this.invalidationVersion;
+        const inFlight = this.build()
+            .then((snapshot) => {
+            if (version === this.invalidationVersion) {
+                this.snapshot = snapshot;
+                this.fetchedAtMs = this.now();
+            }
+            return snapshot;
+        })
+            .finally(() => {
+            if (this.inFlight === inFlight) {
+                this.inFlight = null;
+            }
+        });
+        this.inFlight = inFlight;
+        return this.inFlight;
+    }
+}

package/dist/gui/server/server.d.ts

@@ -0,0 +1 @@
+export {};