opencandle 0.3.0 → 0.5.0

package/src/onboarding/degradation-accumulator.ts

@@ -0,0 +1,79 @@
+// 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 type { ProviderId } from "./providers.js";
+import { getProvider } from "./providers.js";
+import type { OnboardingState } from "./state.js";
+import { buildSkippedTag } from "./tool-tags.js";
+
+export interface DegradationAccumulator {
+  /** Record that a soft-tier provider fell back during this turn. Idempotent. */
+  record(provider: ProviderId): void;
+  /** Number of distinct providers recorded since the last reset. */
+  size(): number;
+  /** True when nothing has been recorded since the last reset. */
+  isEmpty(): boolean;
+  /**
+   * Build a newline-delimited list of `[OPENCANDLE_SKIPPED ...]` tags — one
+   * per distinct recorded provider. Providers whose `state.providers[id]`
+   * entry has `status: "never_ask"` get the `(silenced)` suffix in their
+   * remediation so the system prompt instruction suppresses the `/connect`
+   * link in the final answer. Returns `null` when no providers are recorded.
+   */
+  buildCombinedAnnotation(state: OnboardingState): string | null;
+  /** Clear all recorded providers. Call this at turn_start. */
+  reset(): void;
+}
+
+export function createDegradationAccumulator(): DegradationAccumulator {
+  const recorded = new Set<ProviderId>();
+
+  return {
+    record(provider: ProviderId): void {
+      recorded.add(provider);
+    },
+    size(): number {
+      return recorded.size;
+    },
+    isEmpty(): boolean {
+      return recorded.size === 0;
+    },
+    buildCombinedAnnotation(state: OnboardingState): string | null {
+      if (recorded.size === 0) return null;
+      const lines: string[] = [];
+      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(): void {
+      recorded.clear();
+    },
+  };
+}

package/src/onboarding/prompt-user.ts

@@ -0,0 +1,85 @@
+// 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.
+
+import type { ExtensionContext } from "@earendil-works/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 async function promptUser(
+  ctx: ExtensionContext,
+  opts: PromptOptions,
+  handler?: AskUserHandler,
+): Promise<PromptResult> {
+  // 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 };
+    }
+  }
+}

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;
+}