opencandle 0.1.1 → 0.3.0

package/dist/onboarding/degradation-accumulator.js

@@ -0,0 +1,55 @@
+// Per-turn accumulator for soft-tier provider degradations. When a soft
+// provider falls back to a keyless alternative (e.g. Brave → DuckDuckGo, Exa →
+// keyless MCP, Finnhub → cached/free source), the tool result content carries
+// a `[OPENCANDLE_SOFT_DEGRADED ...]` tag. The extension's `tool_result` hook
+// records the provider id in this accumulator WITHOUT mutating the tool
+// result; at `turn_end` the accumulator builds a single combined
+// `[OPENCANDLE_SKIPPED ...]`-style annotation that gets appended to the
+// session as a sidecar entry for observability.
+//
+// Per-provider state (never_ask / snoozed / completed) lives in the persistent
+// OnboardingState on disk — the accumulator stays pure and consults the
+// caller-supplied state snapshot at `buildCombinedAnnotation` time. This keeps
+// the accumulator trivially testable without mocking the filesystem.
+import { getProvider } from "./providers.js";
+import { buildSkippedTag } from "./tool-tags.js";
+export function createDegradationAccumulator() {
+    const recorded = new Set();
+    return {
+        record(provider) {
+            recorded.add(provider);
+        },
+        size() {
+            return recorded.size;
+        },
+        isEmpty() {
+            return recorded.size === 0;
+        },
+        buildCombinedAnnotation(state) {
+            if (recorded.size === 0)
+                return null;
+            const lines = [];
+            for (const provider of recorded) {
+                const descriptor = getProvider(provider);
+                const entry = state.providers[provider];
+                const silenced = entry?.status === "never_ask";
+                const alias = descriptor.aliases[0] ?? descriptor.id;
+                const baseRemediation = `run /connect ${alias} to unlock`;
+                const remediation = silenced
+                    ? `${baseRemediation} (silenced)`
+                    : baseRemediation;
+                lines.push(buildSkippedTag({
+                    provider,
+                    reason: "credential_not_provided",
+                    remediation,
+                    silenced: silenced || undefined,
+                }));
+            }
+            return lines.join("\n");
+        },
+        reset() {
+            recorded.clear();
+        },
+    };
+}
+//# sourceMappingURL=degradation-accumulator.js.map

package/dist/onboarding/degradation-accumulator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"degradation-accumulator.js","sourceRoot":"","sources":["../../src/onboarding/degradation-accumulator.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,+EAA+E;AAC/E,8EAA8E;AAC9E,6EAA6E;AAC7E,wEAAwE;AACxE,iEAAiE;AACjE,wEAAwE;AACxE,gDAAgD;AAChD,EAAE;AACF,+EAA+E;AAC/E,wEAAwE;AACxE,+EAA+E;AAC/E,qEAAqE;AAGrE,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAqBjD,MAAM,UAAU,4BAA4B;IAC1C,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAc,CAAC;IAEvC,OAAO;QACL,MAAM,CAAC,QAAoB;YACzB,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACzB,CAAC;QACD,IAAI;YACF,OAAO,QAAQ,CAAC,IAAI,CAAC;QACvB,CAAC;QACD,OAAO;YACL,OAAO,QAAQ,CAAC,IAAI,KAAK,CAAC,CAAC;QAC7B,CAAC;QACD,uBAAuB,CAAC,KAAsB;YAC5C,IAAI,QAAQ,CAAC,IAAI,KAAK,CAAC;gBAAE,OAAO,IAAI,CAAC;YACrC,MAAM,KAAK,GAAa,EAAE,CAAC;YAC3B,KAAK,MAAM,QAAQ,IAAI,QAAQ,EAAE,CAAC;gBAChC,MAAM,UAAU,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;gBACzC,MAAM,KAAK,GAAG,KAAK,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;gBACxC,MAAM,QAAQ,GAAG,KAAK,EAAE,MAAM,KAAK,WAAW,CAAC;gBAC/C,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,EAAE,CAAC;gBACrD,MAAM,eAAe,GAAG,gBAAgB,KAAK,YAAY,CAAC;gBAC1D,MAAM,WAAW,GAAG,QAAQ;oBAC1B,CAAC,CAAC,GAAG,eAAe,aAAa;oBACjC,CAAC,CAAC,eAAe,CAAC;gBACpB,KAAK,CAAC,IAAI,CACR,eAAe,CAAC;oBACd,QAAQ;oBACR,MAAM,EAAE,yBAAyB;oBACjC,WAAW;oBACX,QAAQ,EAAE,QAAQ,IAAI,SAAS;iBAChC,CAAC,CACH,CAAC;YACJ,CAAC;YACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;QACD,KAAK;YACH,QAAQ,CAAC,KAAK,EAAE,CAAC;QACnB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/onboarding/prompt-user.d.ts

@@ -0,0 +1,23 @@
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { AskUserHandler } from "../types/index.js";
+export interface PromptOptions {
+    question: string;
+    questionType: "select" | "text" | "confirm";
+    options?: string[];
+    placeholder?: string;
+    reason?: string;
+}
+export interface PromptResult {
+    answer: string | null;
+    cancelled: boolean;
+}
+/**
+ * Ask the user a structured question, routing to the appropriate UI primitive
+ * (`ctx.ui.select` / `ctx.ui.input` / `ctx.ui.confirm`).
+ *
+ * When an `askUserHandler` is injected (test harness, programmatic runs), the
+ * handler takes precedence over `ctx.ui` and provides the answer directly.
+ *
+ * When neither a handler nor a UI is available, returns `{answer: null, cancelled: true}`.
+ */
+export declare function promptUser(ctx: ExtensionContext, opts: PromptOptions, handler?: AskUserHandler): Promise<PromptResult>;

package/dist/onboarding/prompt-user.js

@@ -0,0 +1,61 @@
+// Shared prompt primitive used by both the `ask_user` tool and the
+// credential-interception handler in the Pi `tool_result` hook.
+//
+// The original `ask_user` tool embedded its UI routing in a closure inside
+// `execute()`. Extracting it here means the `tool_result` handler can call
+// the same logic without synthesizing a fake tool call (Pi has no "execute
+// a tool now" API), and the headless harness's `askUserHandler` injection
+// point is preserved for automated flows.
+/**
+ * Ask the user a structured question, routing to the appropriate UI primitive
+ * (`ctx.ui.select` / `ctx.ui.input` / `ctx.ui.confirm`).
+ *
+ * When an `askUserHandler` is injected (test harness, programmatic runs), the
+ * handler takes precedence over `ctx.ui` and provides the answer directly.
+ *
+ * When neither a handler nor a UI is available, returns `{answer: null, cancelled: true}`.
+ */
+export async function promptUser(ctx, opts, handler) {
+    // Priority: injected handler > UI > no-UI fallback.
+    if (handler) {
+        const result = await handler({
+            question: opts.question,
+            questionType: opts.questionType,
+            options: opts.options,
+            placeholder: opts.placeholder,
+            reason: opts.reason,
+        });
+        if (result.cancelled) {
+            return { answer: null, cancelled: true };
+        }
+        return { answer: result.answer ?? null, cancelled: false };
+    }
+    if (!ctx?.hasUI) {
+        return { answer: null, cancelled: true };
+    }
+    switch (opts.questionType) {
+        case "select": {
+            const options = opts.options ?? [];
+            if (options.length === 0) {
+                return { answer: null, cancelled: true };
+            }
+            const choice = await ctx.ui.select(opts.question, options);
+            if (choice === undefined) {
+                return { answer: null, cancelled: true };
+            }
+            return { answer: choice, cancelled: false };
+        }
+        case "text": {
+            const input = await ctx.ui.input(opts.question, opts.placeholder ?? "");
+            if (input === undefined || input.trim() === "") {
+                return { answer: null, cancelled: true };
+            }
+            return { answer: input.trim(), cancelled: false };
+        }
+        case "confirm": {
+            const confirmed = await ctx.ui.confirm(opts.question, opts.reason ?? "");
+            return { answer: confirmed ? "Yes" : "No", cancelled: false };
+        }
+    }
+}
+//# sourceMappingURL=prompt-user.js.map

package/dist/onboarding/prompt-user.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-user.js","sourceRoot":"","sources":["../../src/onboarding/prompt-user.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,gEAAgE;AAChE,EAAE;AACF,2EAA2E;AAC3E,2EAA2E;AAC3E,2EAA2E;AAC3E,0EAA0E;AAC1E,0CAA0C;AAkB1C;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,GAAqB,EACrB,IAAmB,EACnB,OAAwB;IAExB,oDAAoD;IACpD,IAAI,OAAO,EAAE,CAAC;QACZ,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC;YAC3B,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,MAAM,EAAE,IAAI,CAAC,MAAM;SACpB,CAAC,CAAC;QACH,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;YACrB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;QAC3C,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IAC7D,CAAC;IAED,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC;QAChB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IAC3C,CAAC;IAED,QAAQ,IAAI,CAAC,YAAY,EAAE,CAAC;QAC1B,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC;YACnC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACzB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;YAC3C,CAAC;YACD,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YAC3D,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBACzB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;YAC3C,CAAC;YACD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;QAC9C,CAAC;QAED,KAAK,MAAM,CAAC,CAAC,CAAC;YACZ,MAAM,KAAK,GAAG,MAAM,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC;YACxE,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;gBAC/C,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;YAC3C,CAAC;YACD,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;QACpD,CAAC;QAED,KAAK,SAAS,CAAC,CAAC,CAAC;YACf,MAAM,SAAS,GAAG,MAAM,GAAG,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;YACzE,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;QAChE,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/onboarding/providers.d.ts

@@ -0,0 +1,109 @@
+export type ProviderId = "alpha_vantage" | "fred" | "finnhub" | "brave" | "exa";
+export type ProviderCategory = "fundamentals" | "macro" | "news" | "web_search";
+export type ProviderTier = "hard" | "soft";
+export interface ProviderDescriptor {
+    readonly id: ProviderId;
+    readonly displayName: string;
+    readonly category: ProviderCategory;
+    /**
+     * `hard` providers pause the workflow with a just-in-time prompt when their
+     * credential is missing; they have no meaningful fallback.
+     *
+     * `soft` providers silently use a fallback path and surface a post-answer
+     * gap note in the final output.
+     */
+    readonly tier: ProviderTier;
+    /** Lowercase friendly aliases accepted by `/connect` in addition to the id. */
+    readonly aliases: readonly string[];
+    readonly signupUrl: string;
+    readonly freeTier: boolean;
+    readonly envVar: string;
+    /** Nested key path into `OpenCandleFileConfig` where the key is persisted. */
+    readonly configPath: readonly string[];
+    readonly unlocks: readonly string[];
+    /**
+     * Human copy describing the degraded experience when missing, or `null`
+     * when there is no fallback (hard tier).
+     */
+    readonly fallbackDescription: string | null;
+    readonly snoozeDurationDays: number;
+    readonly instructionsHint: string;
+}
+export declare const PROVIDERS: readonly [{
+    readonly id: "alpha_vantage";
+    readonly displayName: "Alpha Vantage";
+    readonly category: "fundamentals";
+    readonly tier: "hard";
+    readonly aliases: readonly ["financials", "fundamentals", "company-financials", "alphavantage"];
+    readonly signupUrl: "https://www.alphavantage.co/support/#api-key";
+    readonly freeTier: true;
+    readonly envVar: "ALPHA_VANTAGE_API_KEY";
+    readonly configPath: readonly ["providers", "alphaVantage", "apiKey"];
+    readonly unlocks: readonly ["company fundamentals", "income/balance/cashflow statements", "DCF valuation", "earnings history"];
+    readonly fallbackDescription: null;
+    readonly snoozeDurationDays: 7;
+    readonly instructionsHint: "Free, about 30 seconds, signup opens in your browser";
+}, {
+    readonly id: "fred";
+    readonly displayName: "FRED";
+    readonly category: "macro";
+    readonly tier: "hard";
+    readonly aliases: readonly ["economy", "macro", "economic-data", "st-louis-fed"];
+    readonly signupUrl: "https://fredaccount.stlouisfed.org/apikeys";
+    readonly freeTier: true;
+    readonly envVar: "FRED_API_KEY";
+    readonly configPath: readonly ["providers", "fred", "apiKey"];
+    readonly unlocks: readonly ["interest rates", "inflation data", "yield curve", "economic indicators"];
+    readonly fallbackDescription: null;
+    readonly snoozeDurationDays: 7;
+    readonly instructionsHint: "Free, about 30 seconds, requires a St. Louis Fed account";
+}, {
+    readonly id: "finnhub";
+    readonly displayName: "Finnhub";
+    readonly category: "news";
+    readonly tier: "soft";
+    readonly aliases: readonly ["news", "company-news", "finnhub-news"];
+    readonly signupUrl: "https://finnhub.io/register";
+    readonly freeTier: true;
+    readonly envVar: "FINNHUB_API_KEY";
+    readonly configPath: readonly ["providers", "finnhub", "apiKey"];
+    readonly unlocks: readonly ["ticker-tagged company news", "sentiment enrichment with a dedicated news source"];
+    readonly fallbackDescription: "Other sentiment sources (Reddit, Twitter, web search) continue to work without Finnhub";
+    readonly snoozeDurationDays: 7;
+    readonly instructionsHint: "Free, about 30 seconds, signup opens in your browser";
+}, {
+    readonly id: "brave";
+    readonly displayName: "Brave Search";
+    readonly category: "web_search";
+    readonly tier: "soft";
+    readonly aliases: readonly ["brave", "brave-search"];
+    readonly signupUrl: "https://brave.com/search/api/";
+    readonly freeTier: true;
+    readonly envVar: "BRAVE_API_KEY";
+    readonly configPath: readonly ["providers", "brave", "apiKey"];
+    readonly unlocks: readonly ["tier-2 web search with freshness control", "independent search index outside of DuckDuckGo"];
+    readonly fallbackDescription: "Web search continues to work via DuckDuckGo (free, no key needed, lower-quality freshness)";
+    readonly snoozeDurationDays: 7;
+    readonly instructionsHint: "Free tier available, signup opens in your browser";
+}, {
+    readonly id: "exa";
+    readonly displayName: "Exa";
+    readonly category: "web_search";
+    readonly tier: "soft";
+    readonly aliases: readonly ["exa", "exa-search"];
+    readonly signupUrl: "https://dashboard.exa.ai/";
+    readonly freeTier: false;
+    readonly envVar: "EXA_API_KEY";
+    readonly configPath: readonly ["providers", "exa", "apiKey"];
+    readonly unlocks: readonly ["tier-1 semantic web search", "full article text and highlights", "higher freshness accuracy than DuckDuckGo"];
+    readonly fallbackDescription: "Exa search continues to work via the keyless Exa MCP endpoint, which has lower rate limits but similar quality";
+    readonly snoozeDurationDays: 7;
+    readonly instructionsHint: "Paid with free tier, signup opens in your browser";
+}];
+export declare function listAllProviders(): readonly ProviderDescriptor[];
+export declare function getProvider(id: ProviderId): ProviderDescriptor;
+export declare function getProvidersByCategory(category: ProviderCategory): readonly ProviderDescriptor[];
+export declare function getProvidersByTier(tier: ProviderTier): readonly ProviderDescriptor[];
+export declare function hasCredential(id: ProviderId): boolean;
+export declare function getCredentialSource(id: ProviderId): "env" | "file" | "absent";
+export declare function resolveProviderFromArgument(arg: string): ProviderDescriptor | readonly ProviderDescriptor[] | undefined;

package/dist/onboarding/providers.js

@@ -0,0 +1,236 @@
+// Provider registry — single source of truth for OpenCandle's credentialed
+// third-party data providers. Every setup pathway iterates this registry:
+// first-run startup, the `/connect` command, the `tool_result` credential
+// interception handler, and the gap-note generator all read from here.
+//
+// Adding a new credentialed provider is a two-step change: add its `ProviderId`
+// to the literal union below, and add its descriptor to the `PROVIDERS` array.
+// The `satisfies` check ensures TypeScript fails the build if the union and
+// the array ever disagree.
+import { getConfig, loadFileConfig } from "../config.js";
+// Declaration order matters: picker display order, per-workflow prompt priority,
+// getProvidersByCategory/getProvidersByTier iteration order.
+export const PROVIDERS = [
+    {
+        id: "alpha_vantage",
+        displayName: "Alpha Vantage",
+        category: "fundamentals",
+        tier: "hard",
+        aliases: ["financials", "fundamentals", "company-financials", "alphavantage"],
+        signupUrl: "https://www.alphavantage.co/support/#api-key",
+        freeTier: true,
+        envVar: "ALPHA_VANTAGE_API_KEY",
+        configPath: ["providers", "alphaVantage", "apiKey"],
+        unlocks: [
+            "company fundamentals",
+            "income/balance/cashflow statements",
+            "DCF valuation",
+            "earnings history",
+        ],
+        fallbackDescription: null,
+        snoozeDurationDays: 7,
+        instructionsHint: "Free, about 30 seconds, signup opens in your browser",
+    },
+    {
+        id: "fred",
+        displayName: "FRED",
+        category: "macro",
+        tier: "hard",
+        aliases: ["economy", "macro", "economic-data", "st-louis-fed"],
+        signupUrl: "https://fredaccount.stlouisfed.org/apikeys",
+        freeTier: true,
+        envVar: "FRED_API_KEY",
+        configPath: ["providers", "fred", "apiKey"],
+        unlocks: [
+            "interest rates",
+            "inflation data",
+            "yield curve",
+            "economic indicators",
+        ],
+        fallbackDescription: null,
+        snoozeDurationDays: 7,
+        instructionsHint: "Free, about 30 seconds, requires a St. Louis Fed account",
+    },
+    {
+        id: "finnhub",
+        displayName: "Finnhub",
+        category: "news",
+        tier: "soft",
+        aliases: ["news", "company-news", "finnhub-news"],
+        signupUrl: "https://finnhub.io/register",
+        freeTier: true,
+        envVar: "FINNHUB_API_KEY",
+        configPath: ["providers", "finnhub", "apiKey"],
+        unlocks: [
+            "ticker-tagged company news",
+            "sentiment enrichment with a dedicated news source",
+        ],
+        // Finnhub is a soft enrichment source — sentiment-summary continues to work
+        // with Twitter/Reddit/web search when Finnhub is missing. The fallback is
+        // "the other sentiment sources still run".
+        fallbackDescription: "Other sentiment sources (Reddit, Twitter, web search) continue to work without Finnhub",
+        snoozeDurationDays: 7,
+        instructionsHint: "Free, about 30 seconds, signup opens in your browser",
+    },
+    {
+        id: "brave",
+        displayName: "Brave Search",
+        category: "web_search",
+        tier: "soft",
+        aliases: ["brave", "brave-search"],
+        signupUrl: "https://brave.com/search/api/",
+        freeTier: true,
+        envVar: "BRAVE_API_KEY",
+        configPath: ["providers", "brave", "apiKey"],
+        unlocks: [
+            "tier-2 web search with freshness control",
+            "independent search index outside of DuckDuckGo",
+        ],
+        fallbackDescription: "Web search continues to work via DuckDuckGo (free, no key needed, lower-quality freshness)",
+        snoozeDurationDays: 7,
+        instructionsHint: "Free tier available, signup opens in your browser",
+    },
+    {
+        id: "exa",
+        displayName: "Exa",
+        category: "web_search",
+        tier: "soft",
+        // Note: "search" is a multi-provider alias shared with Brave. The registry
+        // exposes it via resolveProviderFromArgument as a sub-picker case, not as a
+        // single-provider alias — so it intentionally does NOT appear in either
+        // provider's `aliases` array here. Keeping aliases unique-per-provider lets
+        // resolveProviderFromArgument cleanly distinguish the alias case from the
+        // sub-picker case.
+        aliases: ["exa", "exa-search"],
+        signupUrl: "https://dashboard.exa.ai/",
+        freeTier: false,
+        envVar: "EXA_API_KEY",
+        configPath: ["providers", "exa", "apiKey"],
+        unlocks: [
+            "tier-1 semantic web search",
+            "full article text and highlights",
+            "higher freshness accuracy than DuckDuckGo",
+        ],
+        fallbackDescription: "Exa search continues to work via the keyless Exa MCP endpoint, which has lower rate limits but similar quality",
+        snoozeDurationDays: 7,
+        instructionsHint: "Paid with free tier, signup opens in your browser",
+    },
+];
+// -----------------------------------------------------------------------------
+// Lookup helpers
+// -----------------------------------------------------------------------------
+// Lazy-built index — populated on first helper call so module import has no
+// side effects. The test `importing the registry does not read the filesystem`
+// relies on this.
+let providersById;
+function byId() {
+    if (!providersById) {
+        providersById = new Map(PROVIDERS.map((p) => [p.id, p]));
+    }
+    return providersById;
+}
+export function listAllProviders() {
+    return PROVIDERS;
+}
+export function getProvider(id) {
+    const found = byId().get(id);
+    if (!found) {
+        throw new Error(`Unknown provider id: "${id}"`);
+    }
+    return found;
+}
+export function getProvidersByCategory(category) {
+    return PROVIDERS.filter((p) => p.category === category);
+}
+export function getProvidersByTier(tier) {
+    return PROVIDERS.filter((p) => p.tier === tier);
+}
+// -----------------------------------------------------------------------------
+// Credential source helpers
+// -----------------------------------------------------------------------------
+function readConfigValueByPath(obj, path) {
+    let cursor = obj;
+    for (const segment of path) {
+        if (cursor && typeof cursor === "object" && segment in cursor) {
+            cursor = cursor[segment];
+        }
+        else {
+            return undefined;
+        }
+    }
+    return typeof cursor === "string" && cursor.length > 0 ? cursor : undefined;
+}
+// Provider-id → `Config` field mapping. `Config` (in src/config.ts) is the
+// canonical env-or-file resolved shape that tool implementations already use.
+// `hasCredential` reads from `getConfig()` so that tests mocking `getConfig`
+// see a consistent view; `getCredentialSource` reads `process.env` +
+// `loadFileConfig` directly because it needs to distinguish env from file.
+const CONFIG_FIELD_BY_ID = {
+    alpha_vantage: "alphaVantageApiKey",
+    fred: "fredApiKey",
+    finnhub: "finnhubApiKey",
+    brave: "braveApiKey",
+    exa: "exaApiKey",
+};
+export function hasCredential(id) {
+    const field = CONFIG_FIELD_BY_ID[id];
+    const value = getConfig()[field];
+    return typeof value === "string" && value.length > 0;
+}
+export function getCredentialSource(id) {
+    const descriptor = getProvider(id);
+    const envValue = process.env[descriptor.envVar];
+    if (envValue && envValue.length > 0)
+        return "env";
+    // Lazy file-config read — only invoked when env is absent.
+    const fileConfig = loadFileConfig();
+    const fileValue = readConfigValueByPath(fileConfig, descriptor.configPath);
+    if (fileValue)
+        return "file";
+    return "absent";
+}
+// -----------------------------------------------------------------------------
+// /connect argument resolution
+// -----------------------------------------------------------------------------
+export function resolveProviderFromArgument(arg) {
+    const needle = arg.trim().toLowerCase();
+    if (!needle)
+        return undefined;
+    // 1. Exact provider id match (case-insensitive).
+    for (const p of PROVIDERS) {
+        if (p.id === needle)
+            return p;
+    }
+    // 2. Exact alias match.
+    for (const p of PROVIDERS) {
+        if (p.aliases.includes(needle))
+            return p;
+    }
+    // 3. Category match: if the needle matches a category name, return the
+    //    providers in that category. One match → single descriptor. Multiple
+    //    matches → array (triggers the sub-picker in the /connect handler).
+    const categories = [
+        "fundamentals",
+        "macro",
+        "news",
+        "web_search",
+    ];
+    const normalizedCategory = needle.replace("-", "_");
+    if (categories.includes(normalizedCategory)) {
+        const group = getProvidersByCategory(normalizedCategory);
+        if (group.length === 1)
+            return group[0];
+        if (group.length > 1)
+            return group;
+    }
+    // 4. Special shared alias: "search" → both web_search providers.
+    if (needle === "search" || needle === "web" || needle === "web-search") {
+        const searchProviders = getProvidersByCategory("web_search");
+        if (searchProviders.length === 1)
+            return searchProviders[0];
+        if (searchProviders.length > 1)
+            return searchProviders;
+    }
+    return undefined;
+}
+//# sourceMappingURL=providers.js.map

package/dist/onboarding/providers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.js","sourceRoot":"","sources":["../../src/onboarding/providers.ts"],"names":[],"mappings":"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"}

package/dist/onboarding/state.d.ts

@@ -1,8 +1,37 @@
-export declare const ONBOARDING_VERSION = 1;
+import type { ProviderId } from "./providers.js";
+export declare const ONBOARDING_VERSION = 2;
+export type ProviderOnboardingEntry = {
+    status: "completed";
+    lastPromptAt: string;
+} | {
+    status: "snoozed";
+    lastPromptAt: string;
+    snoozeUntil: string;
+} | {
+    status: "never_ask";
+    lastPromptAt: string;
+};
 export interface OnboardingState {
     version: number;
-    financeSetupStatus?: "dismissed" | "completed";
+    /** ISO 8601 timestamp the welcome message was first seeded, or undefined if never. */
+    welcomeShownAt?: string;
+    providers: Partial<Record<ProviderId, ProviderOnboardingEntry>>;
 }
 export declare function getDefaultOnboardingState(): OnboardingState;
 export declare function loadOnboardingState(path?: string): OnboardingState;
 export declare function saveOnboardingState(state: OnboardingState, path?: string): void;
+export declare function markProviderCompleted(state: OnboardingState, id: ProviderId): OnboardingState;
+export declare function markProviderSnoozed(state: OnboardingState, id: ProviderId, days: number): OnboardingState;
+export declare function markProviderNeverAsk(state: OnboardingState, id: ProviderId): OnboardingState;
+export declare function markWelcomeShown(state: OnboardingState): OnboardingState;
+export declare function getProviderEntry(state: OnboardingState, id: ProviderId): ProviderOnboardingEntry | undefined;
+export interface ShouldPromptOptions {
+    /**
+     * When true, treats a `completed` entry as eligible for re-prompt. This is
+     * how stale credentials (401 after a previously-connected key) get a fresh
+     * offer.
+     */
+    stale?: boolean;
+}
+export declare function shouldPrompt(state: OnboardingState, id: ProviderId, now: Date, options?: ShouldPromptOptions): boolean;
+export declare function shouldShowWelcome(state: OnboardingState, hasUI: boolean): boolean;