opencandle 0.2.0 → 0.4.0

package/src/onboarding/providers.ts

@@ -0,0 +1,315 @@
+// 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";
+
+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;
+}
+
+// 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",
+  },
+] as const satisfies readonly ProviderDescriptor[];
+
+// -----------------------------------------------------------------------------
+// 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: Map<ProviderId, ProviderDescriptor> | undefined;
+
+function byId(): Map<ProviderId, ProviderDescriptor> {
+  if (!providersById) {
+    providersById = new Map(PROVIDERS.map((p) => [p.id, p]));
+  }
+  return providersById;
+}
+
+export function listAllProviders(): readonly ProviderDescriptor[] {
+  return PROVIDERS;
+}
+
+export function getProvider(id: ProviderId): ProviderDescriptor {
+  const found = byId().get(id);
+  if (!found) {
+    throw new Error(`Unknown provider id: "${id}"`);
+  }
+  return found;
+}
+
+export function getProvidersByCategory(
+  category: ProviderCategory,
+): readonly ProviderDescriptor[] {
+  return PROVIDERS.filter((p) => p.category === category);
+}
+
+export function getProvidersByTier(
+  tier: ProviderTier,
+): readonly ProviderDescriptor[] {
+  return PROVIDERS.filter((p) => p.tier === tier);
+}
+
+// -----------------------------------------------------------------------------
+// Credential source helpers
+// -----------------------------------------------------------------------------
+
+function readConfigValueByPath(
+  obj: Record<string, unknown>,
+  path: readonly string[],
+): string | undefined {
+  let cursor: unknown = obj;
+  for (const segment of path) {
+    if (cursor && typeof cursor === "object" && segment in (cursor as object)) {
+      cursor = (cursor as Record<string, unknown>)[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: Record<ProviderId, keyof ReturnType<typeof getConfig>> = {
+  alpha_vantage: "alphaVantageApiKey",
+  fred: "fredApiKey",
+  finnhub: "finnhubApiKey",
+  brave: "braveApiKey",
+  exa: "exaApiKey",
+};
+
+export function hasCredential(id: ProviderId): boolean {
+  const field = CONFIG_FIELD_BY_ID[id];
+  const value = getConfig()[field];
+  return typeof value === "string" && value.length > 0;
+}
+
+export function getCredentialSource(
+  id: ProviderId,
+): "env" | "file" | "absent" {
+  return getCredential(id).source;
+}
+
+export function getCredential(
+  id: ProviderId,
+): { source: "env" | "file"; value: string } | { source: "absent"; value?: undefined } {
+  const descriptor = getProvider(id);
+  const envValue = process.env[descriptor.envVar];
+  if (envValue && envValue.length > 0) return { source: "env", value: envValue };
+
+  // Lazy file-config read — only invoked when env is absent.
+  const fileConfig = loadFileConfig() as unknown as Record<string, unknown>;
+  const fileValue = readConfigValueByPath(fileConfig, descriptor.configPath);
+  if (fileValue) return { source: "file", value: fileValue };
+
+  return { source: "absent" };
+}
+
+// -----------------------------------------------------------------------------
+// /connect argument resolution
+// -----------------------------------------------------------------------------
+
+export function resolveProviderFromArgument(
+  arg: string,
+):
+  | ProviderDescriptor
+  | readonly ProviderDescriptor[]
+  | undefined {
+  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 as readonly string[]).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: readonly ProviderCategory[] = [
+    "fundamentals",
+    "macro",
+    "news",
+    "web_search",
+  ];
+  const normalizedCategory = needle.replace("-", "_");
+  if ((categories as readonly string[]).includes(normalizedCategory)) {
+    const group = getProvidersByCategory(normalizedCategory as ProviderCategory);
+    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;
+}

package/src/onboarding/state.ts

@@ -0,0 +1,218 @@
+// Onboarding state schema and pure helpers.
+//
+// Shape: one flag for the welcome message (`welcomeShownAt`) plus a partial
+// per-provider map with a proper discriminated union for status + snooze.
+//
+// All transition helpers are PURE — they return a new state object rather
+// than mutating. The caller is responsible for persisting via saveOnboardingState.
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { ensureParentDir, getOnboardingPath } from "../infra/opencandle-paths.js";
+import type { ProviderId } from "./providers.js";
+
+export 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;
+  /** ISO 8601 timestamp the welcome message was first seeded, or undefined if never. */
+  welcomeShownAt?: string;
+  providers: Partial<Record<ProviderId, ProviderOnboardingEntry>>;
+}
+
+export function getDefaultOnboardingState(): OnboardingState {
+  return { version: ONBOARDING_VERSION, providers: {} };
+}
+
+// -----------------------------------------------------------------------------
+// Load / save
+// -----------------------------------------------------------------------------
+
+const STATUS_VALUES: ReadonlySet<string> = new Set(["completed", "snoozed", "never_ask"]);
+
+function parseEntry(raw: unknown): ProviderOnboardingEntry | undefined {
+  if (!raw || typeof raw !== "object") return undefined;
+  const obj = raw as Record<string, unknown>;
+  const status = obj.status;
+  if (typeof status !== "string" || !STATUS_VALUES.has(status)) return undefined;
+  const lastPromptAt = obj.lastPromptAt;
+  if (typeof lastPromptAt !== "string") return undefined;
+
+  if (status === "snoozed") {
+    const snoozeUntil = obj.snoozeUntil;
+    if (typeof snoozeUntil !== "string") return undefined;
+    return { status: "snoozed", lastPromptAt, snoozeUntil };
+  }
+  if (status === "completed") {
+    return { status: "completed", lastPromptAt };
+  }
+  return { status: "never_ask", lastPromptAt };
+}
+
+function parseProvidersMap(
+  raw: unknown,
+): Partial<Record<ProviderId, ProviderOnboardingEntry>> {
+  if (!raw || typeof raw !== "object") return {};
+  const result: Partial<Record<ProviderId, ProviderOnboardingEntry>> = {};
+  for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {
+    const entry = parseEntry(value);
+    if (entry) result[key as ProviderId] = entry;
+  }
+  return result;
+}
+
+export function loadOnboardingState(path = getOnboardingPath()): OnboardingState {
+  if (!existsSync(path)) {
+    return getDefaultOnboardingState();
+  }
+
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf-8");
+  } catch {
+    return getDefaultOnboardingState();
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return getDefaultOnboardingState();
+  }
+
+  if (!parsed || typeof parsed !== "object") {
+    return getDefaultOnboardingState();
+  }
+
+  const obj = parsed as Record<string, unknown>;
+  const version = typeof obj.version === "number" ? obj.version : ONBOARDING_VERSION;
+  const welcomeShownAt = typeof obj.welcomeShownAt === "string" ? obj.welcomeShownAt : undefined;
+  const providers = parseProvidersMap(obj.providers);
+
+  return { version, welcomeShownAt, providers };
+}
+
+export function saveOnboardingState(
+  state: OnboardingState,
+  path = getOnboardingPath(),
+): void {
+  ensureParentDir(path);
+  // Strip undefined fields for cleaner on-disk output.
+  const serializable: Record<string, unknown> = {
+    version: state.version,
+    providers: state.providers,
+  };
+  if (state.welcomeShownAt !== undefined) {
+    serializable.welcomeShownAt = state.welcomeShownAt;
+  }
+  writeFileSync(path, `${JSON.stringify(serializable, null, 2)}\n`, "utf-8");
+}
+
+// -----------------------------------------------------------------------------
+// Pure transitions
+// -----------------------------------------------------------------------------
+
+function nowIso(): string {
+  return new Date().toISOString();
+}
+
+export function markProviderCompleted(
+  state: OnboardingState,
+  id: ProviderId,
+): OnboardingState {
+  return {
+    ...state,
+    providers: {
+      ...state.providers,
+      [id]: { status: "completed", lastPromptAt: nowIso() },
+    },
+  };
+}
+
+export function markProviderSnoozed(
+  state: OnboardingState,
+  id: ProviderId,
+  days: number,
+): OnboardingState {
+  const now = new Date();
+  const snoozeUntil = new Date(now.getTime() + days * 24 * 3600 * 1000);
+  return {
+    ...state,
+    providers: {
+      ...state.providers,
+      [id]: {
+        status: "snoozed",
+        lastPromptAt: now.toISOString(),
+        snoozeUntil: snoozeUntil.toISOString(),
+      },
+    },
+  };
+}
+
+export function markProviderNeverAsk(
+  state: OnboardingState,
+  id: ProviderId,
+): OnboardingState {
+  return {
+    ...state,
+    providers: {
+      ...state.providers,
+      [id]: { status: "never_ask", lastPromptAt: nowIso() },
+    },
+  };
+}
+
+export function markWelcomeShown(state: OnboardingState): OnboardingState {
+  return { ...state, welcomeShownAt: nowIso() };
+}
+
+// -----------------------------------------------------------------------------
+// Pure queries
+// -----------------------------------------------------------------------------
+
+export function getProviderEntry(
+  state: OnboardingState,
+  id: ProviderId,
+): ProviderOnboardingEntry | undefined {
+  return state.providers[id];
+}
+
+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 function shouldPrompt(
+  state: OnboardingState,
+  id: ProviderId,
+  now: Date,
+  options: ShouldPromptOptions = {},
+): boolean {
+  const entry = state.providers[id];
+  if (!entry) return true;
+
+  switch (entry.status) {
+    case "never_ask":
+      return false;
+    case "completed":
+      return options.stale === true;
+    case "snoozed": {
+      const until = Date.parse(entry.snoozeUntil);
+      if (Number.isNaN(until)) return true;
+      return now.getTime() >= until;
+    }
+  }
+}
+
+export function shouldShowWelcome(state: OnboardingState, hasUI: boolean): boolean {
+  if (!hasUI) return false;
+  return state.welcomeShownAt === undefined;
+}

package/src/onboarding/tool-helpers.ts

@@ -0,0 +1,111 @@
+// Tool-boundary helpers for credentialed providers.
+//
+// `withCredentialCheck` is the single-entry helper that OpenCandle tools use
+// to wrap their provider calls. It centralizes:
+//   1. The upfront "credential missing" check via the registry.
+//   2. The catch-and-convert logic for `ProviderCredentialError` thrown from
+//      providers on 401/403 (stale credential after HTTP call).
+//   3. The tagged `[OPENCANDLE_CREDENTIAL_REQUIRED ...]` content emission that
+//      the Pi `tool_result` extension hook intercepts.
+//
+// Non-credential errors (network timeouts, parse errors, etc.) are re-thrown
+// unchanged so existing error handling in `wrapProvider` continues to work.
+
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import { ProviderCredentialError } from "../providers/provider-credential-error.js";
+import { getProvider, hasCredential, type ProviderId } from "./providers.js";
+import {
+  buildCredentialRequiredTag,
+  type CredentialRequiredReason,
+} from "./tool-tags.js";
+
+// Metadata carried on `details` for UI / test assertion. This is NOT the
+// LLM-facing contract — that lives in `content` as the tagged line. Pi
+// provider adapters serialize `content`, not `details`, into the model's
+// conversation.
+export interface CredentialRequiredDetails {
+  credentialRequired: {
+    provider: ProviderId;
+    reason: CredentialRequiredReason;
+    httpStatus?: number;
+  };
+}
+
+function buildCredentialRequiredResult(
+  provider: ProviderId,
+  reason: CredentialRequiredReason,
+  httpStatus?: number,
+): AgentToolResult<CredentialRequiredDetails> {
+  const descriptor = getProvider(provider);
+  const tag = buildCredentialRequiredTag({
+    provider,
+    reason,
+    unlocks: descriptor.unlocks,
+    fallback: descriptor.fallbackDescription,
+    httpStatus,
+  });
+  // The second line is natural language describing what's missing. Users won't
+  // see it directly — the model sees it and uses the information to synthesize
+  // a gap note in its final answer. The tagged first line is the machine-
+  // readable signal the `tool_result` interception handler keys off of.
+  const narrative =
+    reason === "missing"
+      ? `${descriptor.displayName} was not fetched for this request because no API key is configured. It unlocks ${descriptor.unlocks.join(", ")}.`
+      : `${descriptor.displayName} rejected the configured API key (HTTP ${httpStatus ?? "auth error"}). It may be expired or revoked.`;
+
+  return {
+    content: [{ type: "text", text: `${tag}\n\n${narrative}` }],
+    details: {
+      credentialRequired: {
+        provider,
+        reason,
+        ...(httpStatus !== undefined ? { httpStatus } : {}),
+      },
+    },
+  };
+}
+
+/**
+ * Wrap a tool's provider-calling logic with a credential-check layer.
+ *
+ * Usage:
+ * ```
+ * async execute(_, args) {
+ *   return withCredentialCheck("alpha_vantage", async () => {
+ *     const apiKey = getConfig().alphaVantageApiKey!;
+ *     const result = await wrapProvider("alphavantage", () => getFinancials(args.symbol, apiKey));
+ *     // ... format success result ...
+ *     return { content: [...], details: [...] };
+ *   });
+ * }
+ * ```
+ *
+ * On missing credential (upfront): `fn` is NOT called. A tagged tool result
+ * is returned directly.
+ *
+ * On `ProviderCredentialError` thrown during `fn`: the error is caught and a
+ * tagged tool result is returned.
+ *
+ * Any other thrown value (plain Error, string, etc.) is re-thrown unchanged.
+ */
+export async function withCredentialCheck<T>(
+  providerId: ProviderId,
+  fn: () => Promise<AgentToolResult<T>>,
+): Promise<AgentToolResult<T> | AgentToolResult<CredentialRequiredDetails>> {
+  if (!hasCredential(providerId)) {
+    return buildCredentialRequiredResult(providerId, "missing");
+  }
+
+  try {
+    return await fn();
+  } catch (error) {
+    if (error instanceof ProviderCredentialError) {
+      return buildCredentialRequiredResult(
+        error.provider,
+        error.reason,
+        error.httpStatus,
+      );
+    }
+    throw error;
+  }
+}