opencandle 0.5.0 → 0.7.0

package/src/onboarding/providers.ts

@@ -1,32 +1,33 @@
-// Provider registry — single source of truth for OpenCandle's credentialed
-// third-party data providers. Every setup pathway iterates this registry:
+// Provider registry — single source of truth for OpenCandle's third-party
+// data providers. Every setup/status 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.
+// interception handler, GUI provider rows, doctor checks, and gap-note
+// generation 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.
+// Adding a new provider is a two-step change: add its id to the relevant
+// literal union below, and add its descriptor to the `PROVIDERS` array. The
+// `satisfies` and exhaustiveness checks keep the registry and id unions aligned.
 
 import { getConfig, loadFileConfig } from "../config.js";
 
-export type ProviderId =
-  | "alpha_vantage"
-  | "fred"
-  | "finnhub"
-  | "brave"
-  | "exa";
+export type ApiKeyProviderId = "alpha_vantage" | "fred" | "finnhub" | "brave" | "exa";
+export type ExternalToolProviderId = "twitter" | "reddit";
+export type PublicHttpProviderId = "yahoo";
+export type ProviderId = ApiKeyProviderId | ExternalToolProviderId | PublicHttpProviderId;
 
 export type ProviderCategory =
   | "fundamentals"
   | "macro"
   | "news"
-  | "web_search";
+  | "web_search"
+  | "sentiment"
+  | "market";
 
 export type ProviderTier = "hard" | "soft";
 
-export interface ProviderDescriptor {
+interface BaseProviderDescriptor {
   readonly id: ProviderId;
+  readonly kind: "api-key" | "external-tool" | "public-http";
   readonly displayName: string;
   readonly category: ProviderCategory;
   /**
@@ -39,11 +40,6 @@ export interface ProviderDescriptor {
   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`
@@ -54,11 +50,43 @@ export interface ProviderDescriptor {
   readonly instructionsHint: string;
 }
 
+export interface ApiKeyProviderDescriptor extends BaseProviderDescriptor {
+  readonly id: ApiKeyProviderId;
+  readonly kind: "api-key";
+  readonly signupUrl: string;
+  readonly freeTier: boolean;
+  readonly envVar: string;
+  /** Nested key path into `OpenCandleFileConfig` where the key is persisted. */
+  readonly configPath: readonly string[];
+}
+
+export interface ExternalToolProviderDescriptor extends BaseProviderDescriptor {
+  readonly id: ExternalToolProviderId;
+  readonly kind: "external-tool";
+  readonly binary: string;
+  readonly installCmd: string;
+  readonly sessionSource: "browser-cookies";
+  readonly supportedBrowsers?: readonly string[];
+  readonly sessionProbeArgs?: readonly string[];
+}
+
+export interface PublicHttpProviderDescriptor extends BaseProviderDescriptor {
+  readonly id: PublicHttpProviderId;
+  readonly kind: "public-http";
+  readonly probeUrl: string;
+}
+
+export type ProviderDescriptor =
+  | ApiKeyProviderDescriptor
+  | ExternalToolProviderDescriptor
+  | PublicHttpProviderDescriptor;
+
 // Declaration order matters: picker display order, per-workflow prompt priority,
 // getProvidersByCategory/getProvidersByTier iteration order.
 export const PROVIDERS = [
   {
     id: "alpha_vantage",
+    kind: "api-key",
     displayName: "Alpha Vantage",
     category: "fundamentals",
     tier: "hard",
@@ -79,6 +107,7 @@ export const PROVIDERS = [
   },
   {
     id: "fred",
+    kind: "api-key",
     displayName: "FRED",
     category: "macro",
     tier: "hard",
@@ -87,18 +116,14 @@ export const PROVIDERS = [
     freeTier: true,
     envVar: "FRED_API_KEY",
     configPath: ["providers", "fred", "apiKey"],
-    unlocks: [
-      "interest rates",
-      "inflation data",
-      "yield curve",
-      "economic indicators",
-    ],
+    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",
+    kind: "api-key",
     displayName: "Finnhub",
     category: "news",
     tier: "soft",
@@ -107,10 +132,7 @@ export const PROVIDERS = [
     freeTier: true,
     envVar: "FINNHUB_API_KEY",
     configPath: ["providers", "finnhub", "apiKey"],
-    unlocks: [
-      "ticker-tagged company news",
-      "sentiment enrichment with a dedicated news source",
-    ],
+    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".
@@ -121,6 +143,7 @@ export const PROVIDERS = [
   },
   {
     id: "brave",
+    kind: "api-key",
     displayName: "Brave Search",
     category: "web_search",
     tier: "soft",
@@ -140,6 +163,7 @@ export const PROVIDERS = [
   },
   {
     id: "exa",
+    kind: "api-key",
     displayName: "Exa",
     category: "web_search",
     tier: "soft",
@@ -164,8 +188,64 @@ export const PROVIDERS = [
     snoozeDurationDays: 7,
     instructionsHint: "Paid with free tier, signup opens in your browser",
   },
+  {
+    id: "yahoo",
+    kind: "public-http",
+    displayName: "Yahoo Finance",
+    category: "market",
+    tier: "hard",
+    aliases: ["yahoo", "yahoo-finance", "market-data", "options"],
+    probeUrl: "https://query1.finance.yahoo.com/v8/finance/chart/SPY?interval=1d&range=1d",
+    unlocks: ["quotes", "historical prices", "option chains", "market data"],
+    fallbackDescription: null,
+    snoozeDurationDays: 7,
+    instructionsHint: "No account needed; OpenCandle checks public Yahoo Finance reachability",
+  },
+  {
+    id: "twitter",
+    kind: "external-tool",
+    displayName: "X / Twitter",
+    category: "sentiment",
+    tier: "soft",
+    aliases: ["twitter", "x", "x-sentiment", "twitter-sentiment"],
+    binary: "twitter",
+    installCmd: "uv tool install twitter-cli",
+    sessionSource: "browser-cookies",
+    sessionProbeArgs: ["feed", "--max", "1", "--json"],
+    supportedBrowsers: ["Chrome", "Arc", "Edge", "Firefox", "Brave"],
+    unlocks: ["X/Twitter sentiment", "recent ticker mentions", "social engagement context"],
+    fallbackDescription:
+      "Sentiment summaries continue with Reddit, web search, and news when X is unavailable",
+    snoozeDurationDays: 7,
+    instructionsHint: "Install twitter-cli and stay logged into x.com in a supported browser",
+  },
+  {
+    id: "reddit",
+    kind: "external-tool",
+    displayName: "Reddit",
+    category: "sentiment",
+    tier: "soft",
+    aliases: ["reddit", "reddit-sentiment", "subreddit"],
+    binary: "rdt",
+    installCmd: "uv tool install rdt-cli",
+    sessionSource: "browser-cookies",
+    supportedBrowsers: ["Chrome", "Arc", "Edge", "Firefox", "Brave"],
+    sessionProbeArgs: ["status", "--json"],
+    unlocks: ["Reddit sentiment", "ticker discussion context", "retail investor discussion"],
+    fallbackDescription:
+      "Sentiment summaries continue with X/Twitter, web search, and news when Reddit is unavailable",
+    snoozeDurationDays: 7,
+    instructionsHint: "Install rdt-cli and stay logged into reddit.com in a supported browser",
+  },
 ] as const satisfies readonly ProviderDescriptor[];
 
+const _providerIdExhaustivenessCheck: Record<
+  | Exclude<ProviderId, (typeof PROVIDERS)[number]["id"]>
+  | Exclude<(typeof PROVIDERS)[number]["id"], ProviderId>,
+  never
+> = {};
+void _providerIdExhaustivenessCheck;
+
 // -----------------------------------------------------------------------------
 // Lookup helpers
 // -----------------------------------------------------------------------------
@@ -186,6 +266,28 @@ export function listAllProviders(): readonly ProviderDescriptor[] {
   return PROVIDERS;
 }
 
+export function isApiKeyProvider(
+  provider: ProviderDescriptor,
+): provider is ApiKeyProviderDescriptor {
+  return provider.kind === "api-key";
+}
+
+export function isExternalToolProvider(
+  provider: ProviderDescriptor,
+): provider is ExternalToolProviderDescriptor {
+  return provider.kind === "external-tool";
+}
+
+export function isPublicHttpProvider(
+  provider: ProviderDescriptor,
+): provider is PublicHttpProviderDescriptor {
+  return provider.kind === "public-http";
+}
+
+export function listApiKeyProviders(): readonly ApiKeyProviderDescriptor[] {
+  return (PROVIDERS as readonly ProviderDescriptor[]).filter(isApiKeyProvider);
+}
+
 export function getProvider(id: ProviderId): ProviderDescriptor {
   const found = byId().get(id);
   if (!found) {
@@ -194,15 +296,11 @@ export function getProvider(id: ProviderId): ProviderDescriptor {
   return found;
 }
 
-export function getProvidersByCategory(
-  category: ProviderCategory,
-): readonly ProviderDescriptor[] {
+export function getProvidersByCategory(category: ProviderCategory): readonly ProviderDescriptor[] {
   return PROVIDERS.filter((p) => p.category === category);
 }
 
-export function getProvidersByTier(
-  tier: ProviderTier,
-): readonly ProviderDescriptor[] {
+export function getProvidersByTier(tier: ProviderTier): readonly ProviderDescriptor[] {
   return PROVIDERS.filter((p) => p.tier === tier);
 }
 
@@ -230,7 +328,7 @@ function readConfigValueByPath(
 // `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>> = {
+const CONFIG_FIELD_BY_ID: Record<ApiKeyProviderId, keyof ReturnType<typeof getConfig>> = {
   alpha_vantage: "alphaVantageApiKey",
   fred: "fredApiKey",
   finnhub: "finnhubApiKey",
@@ -239,14 +337,14 @@ const CONFIG_FIELD_BY_ID: Record<ProviderId, keyof ReturnType<typeof getConfig>>
 };
 
 export function hasCredential(id: ProviderId): boolean {
-  const field = CONFIG_FIELD_BY_ID[id];
+  const descriptor = getProvider(id);
+  if (!isApiKeyProvider(descriptor)) return false;
+  const field = CONFIG_FIELD_BY_ID[descriptor.id];
   const value = getConfig()[field];
   return typeof value === "string" && value.length > 0;
 }
 
-export function getCredentialSource(
-  id: ProviderId,
-): "env" | "file" | "absent" {
+export function getCredentialSource(id: ProviderId): "env" | "file" | "absent" {
   return getCredential(id).source;
 }
 
@@ -254,6 +352,8 @@ export function getCredential(
   id: ProviderId,
 ): { source: "env" | "file"; value: string } | { source: "absent"; value?: undefined } {
   const descriptor = getProvider(id);
+  if (!isApiKeyProvider(descriptor)) return { source: "absent" };
+
   const envValue = process.env[descriptor.envVar];
   if (envValue && envValue.length > 0) return { source: "env", value: envValue };
 
@@ -271,10 +371,7 @@ export function getCredential(
 
 export function resolveProviderFromArgument(
   arg: string,
-):
-  | ProviderDescriptor
-  | readonly ProviderDescriptor[]
-  | undefined {
+): ProviderDescriptor | readonly ProviderDescriptor[] | undefined {
   const needle = arg.trim().toLowerCase();
   if (!needle) return undefined;
 
@@ -296,6 +393,8 @@ export function resolveProviderFromArgument(
     "macro",
     "news",
     "web_search",
+    "sentiment",
+    "market",
   ];
   const normalizedCategory = needle.replace("-", "_");
   if ((categories as readonly string[]).includes(normalizedCategory)) {

package/src/onboarding/state.ts

@@ -53,9 +53,7 @@ function parseEntry(raw: unknown): ProviderOnboardingEntry | undefined {
   return { status: "never_ask", lastPromptAt };
 }
 
-function parseProvidersMap(
-  raw: unknown,
-): Partial<Record<ProviderId, ProviderOnboardingEntry>> {
+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>)) {
@@ -96,10 +94,7 @@ export function loadOnboardingState(path = getOnboardingPath()): OnboardingState
   return { version, welcomeShownAt, providers };
 }
 
-export function saveOnboardingState(
-  state: OnboardingState,
-  path = getOnboardingPath(),
-): void {
+export function saveOnboardingState(state: OnboardingState, path = getOnboardingPath()): void {
   ensureParentDir(path);
   // Strip undefined fields for cleaner on-disk output.
   const serializable: Record<string, unknown> = {
@@ -120,10 +115,7 @@ function nowIso(): string {
   return new Date().toISOString();
 }
 
-export function markProviderCompleted(
-  state: OnboardingState,
-  id: ProviderId,
-): OnboardingState {
+export function markProviderCompleted(state: OnboardingState, id: ProviderId): OnboardingState {
   return {
     ...state,
     providers: {
@@ -153,10 +145,7 @@ export function markProviderSnoozed(
   };
 }
 
-export function markProviderNeverAsk(
-  state: OnboardingState,
-  id: ProviderId,
-): OnboardingState {
+export function markProviderNeverAsk(state: OnboardingState, id: ProviderId): OnboardingState {
   return {
     ...state,
     providers: {
@@ -166,6 +155,15 @@ export function markProviderNeverAsk(
   };
 }
 
+export function clearProviderOnboardingEntry(
+  state: OnboardingState,
+  id: ProviderId,
+): OnboardingState {
+  const providers = { ...state.providers };
+  delete providers[id];
+  return { ...state, providers };
+}
+
 export function markWelcomeShown(state: OnboardingState): OnboardingState {
   return { ...state, welcomeShownAt: nowIso() };
 }

package/src/onboarding/tool-helpers.ts

@@ -14,10 +14,7 @@
 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";
+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
@@ -100,11 +97,7 @@ export async function withCredentialCheck<T>(
     return await fn();
   } catch (error) {
     if (error instanceof ProviderCredentialError) {
-      return buildCredentialRequiredResult(
-        error.provider,
-        error.reason,
-        error.httpStatus,
-      );
+      return buildCredentialRequiredResult(error.provider, error.reason, error.httpStatus);
     }
     throw error;
   }

package/src/onboarding/tool-tags.ts

@@ -22,6 +22,7 @@ import type { ProviderId } from "./providers.js";
 // -----------------------------------------------------------------------------
 
 export type CredentialRequiredReason = "missing" | "stale";
+export type ExternalToolRequiredReason = "not_installed" | "session_missing" | "session_stale";
 
 export interface CredentialRequiredTagFields {
   provider: ProviderId;
@@ -48,11 +49,20 @@ export interface ConnectedTagFields {
   provider: ProviderId;
 }
 
+export interface ExternalToolRequiredTagFields {
+  provider: ProviderId;
+  reason: ExternalToolRequiredReason;
+  installCmd: string;
+  loginCmd?: string;
+  fallback: string | null;
+}
+
 export type ParsedTag =
   | ({ kind: "credential_required" } & CredentialRequiredTagFields)
   | ({ kind: "soft_degraded" } & SoftDegradedTagFields)
   | ({ kind: "skipped" } & SkippedTagFields)
-  | ({ kind: "connected" } & ConnectedTagFields);
+  | ({ kind: "connected" } & ConnectedTagFields)
+  | ({ kind: "external_tool_required" } & ExternalToolRequiredTagFields);
 
 // -----------------------------------------------------------------------------
 // Builders
@@ -81,12 +91,12 @@ export function buildCredentialRequiredTag(fields: CredentialRequiredTagFields):
 }
 
 export function buildSoftDegradedTag(fields: SoftDegradedTagFields): string {
-  return [
+  return `${[
     "[OPENCANDLE_SOFT_DEGRADED",
     formatField("provider", fields.provider),
     formatField("fallback", fields.fallback),
     `remediation=${quote(fields.remediation)}`,
-  ].join(" ") + "]";
+  ].join(" ")}]`;
 }
 
 export function buildSkippedTag(fields: SkippedTagFields): string {
@@ -106,19 +116,32 @@ export function buildConnectedTag(fields: ConnectedTagFields): string {
   return `[OPENCANDLE_CONNECTED provider=${fields.provider}]`;
 }
 
+export function buildExternalToolRequiredTag(fields: ExternalToolRequiredTagFields): string {
+  const parts: string[] = [
+    "[OPENCANDLE_EXTERNAL_TOOL_REQUIRED",
+    formatField("provider", fields.provider),
+    formatField("reason", fields.reason),
+    `installCmd=${quote(fields.installCmd)}`,
+    formatField("fallback", fields.fallback ?? "none"),
+  ];
+  if (fields.loginCmd) parts.push(`loginCmd=${quote(fields.loginCmd)}`);
+  return `${parts.join(" ")}]`;
+}
+
 // -----------------------------------------------------------------------------
 // Parser
 // -----------------------------------------------------------------------------
 
 const TAG_LINE_REGEX =
-  /\[OPENCANDLE_(CREDENTIAL_REQUIRED|SOFT_DEGRADED|SKIPPED|CONNECTED)([^\]]*)\]/;
+  /\[OPENCANDLE_(CREDENTIAL_REQUIRED|SOFT_DEGRADED|SKIPPED|CONNECTED|EXTERNAL_TOOL_REQUIRED)([^\]]*)\]/;
 
 function parseFields(raw: string): Record<string, string> {
   // Split on `key=value` pairs, respecting quoted values.
   const fields: Record<string, string> = {};
   const pattern = /(\w+)=("((?:[^"\\]|\\.)*)"|([^\s\]]+))/g;
-  let match: RegExpExecArray | null;
-  while ((match = pattern.exec(raw)) !== null) {
+  while (true) {
+    const match = pattern.exec(raw);
+    if (!match) break;
     const key = match[1];
     const value = match[3] !== undefined ? match[3].replace(/\\"/g, '"') : match[4];
     fields[key] = value;
@@ -147,8 +170,7 @@ export function parseToolTag(text: string): ParsedTag | undefined {
         .split(",")
         .map((s) => s.trim())
         .filter((s) => s.length > 0);
-      const fallback =
-        fallbackRaw === undefined || fallbackRaw === "none" ? null : fallbackRaw;
+      const fallback = fallbackRaw === undefined || fallbackRaw === "none" ? null : fallbackRaw;
       const parsed: ParsedTag = {
         kind: "credential_required",
         provider: provider as ProviderId,
@@ -195,6 +217,27 @@ export function parseToolTag(text: string): ParsedTag | undefined {
       return { kind: "connected", provider: provider as ProviderId };
     }
 
+    case "EXTERNAL_TOOL_REQUIRED": {
+      const { provider, reason, installCmd, loginCmd, fallback } = fields;
+      if (
+        !provider ||
+        (reason !== "not_installed" &&
+          reason !== "session_missing" &&
+          reason !== "session_stale") ||
+        !installCmd
+      ) {
+        return undefined;
+      }
+      return {
+        kind: "external_tool_required",
+        provider: provider as ProviderId,
+        reason,
+        installCmd,
+        loginCmd,
+        fallback: fallback === undefined || fallback === "none" ? null : fallback,
+      };
+    }
+
     default:
       return undefined;
   }

package/src/onboarding/validation.ts

@@ -20,7 +20,7 @@
 // All validators share a 5-second timeout via `AbortSignal.timeout` so the
 // connect flow cannot hang if a provider is unreachable.
 
-import type { ProviderId } from "./providers.js";
+import type { ApiKeyProviderId } from "./providers.js";
 
 const VALIDATION_TIMEOUT_MS = 5_000;
 
@@ -89,7 +89,7 @@ function classifyAlphaVantageBody(body: string): ValidationResult | undefined {
     if (typeof errorMessage === "string" && errorMessage.length > 0) {
       return { status: "invalid", message: errorMessage };
     }
-    const information = parsed["Information"];
+    const information = parsed.Information;
     if (typeof information === "string" && /invalid api/i.test(information)) {
       return { status: "invalid", message: information };
     }
@@ -107,7 +107,7 @@ function classifyAlphaVantageBody(body: string): ValidationResult | undefined {
  * touch the config file, onboarding state, or any in-memory cache.
  */
 export async function validateCredential(
-  providerId: ProviderId,
+  providerId: ApiKeyProviderId,
   key: string,
 ): Promise<ValidationResult> {
   switch (providerId) {
@@ -131,28 +131,22 @@ export async function validateCredential(
       );
 
     case "brave":
-      return validateWithFetch(
-        "https://api.search.brave.com/res/v1/web/search?q=test&count=1",
-        {
-          method: "GET",
-          headers: {
-            "X-Subscription-Token": key,
-            Accept: "application/json",
-          },
+      return validateWithFetch("https://api.search.brave.com/res/v1/web/search?q=test&count=1", {
+        method: "GET",
+        headers: {
+          "X-Subscription-Token": key,
+          Accept: "application/json",
         },
-      );
+      });
 
     case "exa":
-      return validateWithFetch(
-        "https://api.exa.ai/search",
-        {
-          method: "POST",
-          headers: {
-            "Content-Type": "application/json",
-            "x-api-key": key,
-          },
-          body: JSON.stringify({ query: "test", numResults: 1 }),
+      return validateWithFetch("https://api.exa.ai/search", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-api-key": key,
         },
-      );
+        body: JSON.stringify({ query: "test", numResults: 1 }),
+      });
   }
 }