opencandle 0.3.0 → 0.5.0

package/src/config.ts

@@ -0,0 +1,245 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { ensureParentDir, getConfigPath } from "./infra/opencandle-paths.js";
+import type { PlanningBehaviorMode, TaskFamily } from "./routing/planning.js";
+
+export interface SentimentConfig {
+  retentionDays: number;
+  defaultSubreddits: string[];
+  commentsPerPost: number;
+  divergenceThreshold: number;
+}
+
+export type RouterMode = "rules" | "llm";
+export type ToolScopeMode = "observe" | "enforce";
+export type PlanningMigrationStatuses = Partial<Record<TaskFamily, PlanningBehaviorMode>>;
+
+export interface Config {
+  alphaVantageApiKey?: string;
+  fredApiKey?: string;
+  braveApiKey?: string;
+  exaApiKey?: string;
+  finnhubApiKey?: string;
+  /** Enable adversarial bull/bear debate in comprehensive analysis. Default: true. */
+  debate?: boolean;
+  /**
+   * Intent-router mode. `"llm"` (default) runs the LLM router ahead of prompt
+   * assembly. `"rules"` is the explicit legacy rule-router rollback path
+   * (`classifyIntent` + `extractPreferences`). Controlled by
+   * `OPENCANDLE_ROUTER_MODE`.
+   */
+  routerMode: RouterMode;
+  /**
+   * Route-selected tool scope mode. `"observe"` (default) records selected
+   * bundles and active-tool candidates. `"enforce"` applies Pi active tools
+   * for the turn via `pi.setActiveTools`.
+   */
+  toolScopeMode: ToolScopeMode;
+  /**
+   * Per-task planning behavior rollback/activation overrides. Controlled by
+   * `OPENCANDLE_PLANNING_MIGRATION_STATUSES`, e.g.
+   * `asset_compare=dual_run,single_asset_decision=observe_only`.
+   */
+  planningMigrationStatuses?: PlanningMigrationStatuses;
+  sentiment?: SentimentConfig;
+}
+
+export interface OpenCandleFileConfig {
+  providers?: {
+    alphaVantage?: {
+      apiKey?: string;
+    };
+    fred?: {
+      apiKey?: string;
+    };
+    brave?: {
+      apiKey?: string;
+    };
+    exa?: {
+      apiKey?: string;
+    };
+    finnhub?: {
+      apiKey?: string;
+    };
+  };
+  /** Enable adversarial bull/bear debate in comprehensive analysis. Default: true. */
+  debate?: boolean;
+  sentiment?: {
+    retentionDays?: number;
+    defaultSubreddits?: string[];
+    commentsPerPost?: number;
+    divergenceThreshold?: number;
+  };
+}
+
+export function loadEnv(path = ".env"): void {
+  let content: string;
+  try {
+    content = readFileSync(path, "utf-8");
+  } catch {
+    return;
+  }
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eqIndex = trimmed.indexOf("=");
+    if (eqIndex === -1) continue;
+    const key = trimmed.slice(0, eqIndex).trim();
+    const value = trimmed.slice(eqIndex + 1).trim();
+    if (key && value) {
+      process.env[key] = value;
+    }
+  }
+}
+
+let cachedConfig: Config | null = null;
+
+const SENTIMENT_DEFAULTS: SentimentConfig = {
+  retentionDays: 30,
+  defaultSubreddits: ["wallstreetbets", "stocks", "investing", "options"],
+  commentsPerPost: 5,
+  divergenceThreshold: 0.4,
+};
+
+const PLANNING_TASK_FAMILIES = [
+  "single_asset_decision",
+  "asset_compare",
+  "portfolio_build",
+  "portfolio_review",
+  "macro_allocation_review",
+  "options_strategy",
+  "current_event_explanation",
+  "ticker_disambiguation",
+  "filing_thesis_review",
+  "sentiment_snapshot",
+  "concept_explainer",
+  "retail_finance_tradeoff",
+  "stateful_tracking_update",
+  "backtest_review",
+  "general_fallback",
+] as const satisfies readonly TaskFamily[];
+
+const PLANNING_BEHAVIOR_MODES = [
+  "observe_only",
+  "dual_run",
+  "replacement_active",
+] as const satisfies readonly PlanningBehaviorMode[];
+
+function resolveRouterMode(): RouterMode {
+  const raw = process.env.OPENCANDLE_ROUTER_MODE;
+  if (raw === undefined || raw === "") return "llm";
+  if (raw === "rules" || raw === "llm") return raw;
+  throw new Error(
+    `Invalid OPENCANDLE_ROUTER_MODE="${raw}". Allowed values: "llm" (default) or "rules".`,
+  );
+}
+
+function resolveToolScopeMode(): ToolScopeMode {
+  const raw = process.env.OPENCANDLE_TOOL_SCOPE_MODE;
+  if (raw === undefined || raw === "") return "observe";
+  if (raw === "observe" || raw === "enforce") return raw;
+  throw new Error(
+    `Invalid OPENCANDLE_TOOL_SCOPE_MODE="${raw}". Allowed values: "observe" (default) or "enforce".`,
+  );
+}
+
+function resolvePlanningMigrationStatuses(): PlanningMigrationStatuses | undefined {
+  const raw = process.env.OPENCANDLE_PLANNING_MIGRATION_STATUSES;
+  if (raw === undefined || raw.trim() === "") return undefined;
+
+  const statuses: PlanningMigrationStatuses = {};
+  for (const entry of raw.split(",")) {
+    const trimmed = entry.trim();
+    if (!trimmed) continue;
+
+    const parts = trimmed.split("=");
+    const taskFamily = parts[0]?.trim();
+    const behaviorMode = parts[1]?.trim();
+    if (
+      parts.length !== 2 ||
+      !isPlanningTaskFamily(taskFamily) ||
+      !isPlanningBehaviorMode(behaviorMode)
+    ) {
+      throw new Error(`Invalid OPENCANDLE_PLANNING_MIGRATION_STATUSES entry "${trimmed}".`);
+    }
+    statuses[taskFamily] = behaviorMode;
+  }
+
+  return Object.keys(statuses).length > 0 ? statuses : undefined;
+}
+
+function isPlanningTaskFamily(value: string | undefined): value is TaskFamily {
+  return PLANNING_TASK_FAMILIES.includes(value as TaskFamily);
+}
+
+function isPlanningBehaviorMode(value: string | undefined): value is PlanningBehaviorMode {
+  return PLANNING_BEHAVIOR_MODES.includes(value as PlanningBehaviorMode);
+}
+
+function resolveConfig(fileConfig: OpenCandleFileConfig): Config {
+  const debateEnv = process.env.OPENCANDLE_DEBATE;
+  const fileSentiment = fileConfig.sentiment;
+  return {
+    alphaVantageApiKey:
+      process.env.ALPHA_VANTAGE_API_KEY ?? fileConfig.providers?.alphaVantage?.apiKey,
+    fredApiKey: process.env.FRED_API_KEY ?? fileConfig.providers?.fred?.apiKey,
+    braveApiKey: process.env.BRAVE_API_KEY ?? fileConfig.providers?.brave?.apiKey,
+    exaApiKey: process.env.EXA_API_KEY ?? fileConfig.providers?.exa?.apiKey,
+    finnhubApiKey: process.env.FINNHUB_API_KEY ?? fileConfig.providers?.finnhub?.apiKey,
+    debate: debateEnv !== undefined ? debateEnv !== "false" && debateEnv !== "0" : fileConfig.debate ?? true,
+    routerMode: resolveRouterMode(),
+    toolScopeMode: resolveToolScopeMode(),
+    planningMigrationStatuses: resolvePlanningMigrationStatuses(),
+    sentiment: {
+      retentionDays: fileSentiment?.retentionDays ?? SENTIMENT_DEFAULTS.retentionDays,
+      defaultSubreddits: fileSentiment?.defaultSubreddits ?? SENTIMENT_DEFAULTS.defaultSubreddits,
+      commentsPerPost: fileSentiment?.commentsPerPost ?? SENTIMENT_DEFAULTS.commentsPerPost,
+      divergenceThreshold: fileSentiment?.divergenceThreshold ?? SENTIMENT_DEFAULTS.divergenceThreshold,
+    },
+  };
+}
+
+export function loadFileConfig(path = getConfigPath()): OpenCandleFileConfig {
+  if (!existsSync(path)) {
+    return {};
+  }
+
+  let content: string;
+  try {
+    content = readFileSync(path, "utf-8");
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Unable to read OpenCandle config at ${path}: ${message}`);
+  }
+
+  try {
+    const parsed = JSON.parse(content) as OpenCandleFileConfig;
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Invalid OpenCandle config at ${path}: ${message}`);
+  }
+}
+
+export function saveFileConfig(config: OpenCandleFileConfig, path = getConfigPath()): void {
+  ensureParentDir(path);
+  writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, "utf-8");
+}
+
+export function loadConfig(): Config {
+  loadEnv();
+  cachedConfig = resolveConfig(loadFileConfig());
+
+  return cachedConfig;
+}
+
+export function getConfig(): Config {
+  if (!cachedConfig) {
+    return loadConfig();
+  }
+  return cachedConfig;
+}
+
+/** Test-only: clear the memoized config so the next `getConfig()` re-reads env. */
+export function resetConfigCache(): void {
+  cachedConfig = null;
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export { createOpenCandleSession, type CreateOpenCandleSessionOptions } from "./pi/session.js";
+export { default as openCandleExtension } from "./pi/opencandle-extension.js";
+export { agentToolToPiTool, getOpenCandleToolDefinitions } from "./pi/tool-adapter.js";
+export { registerTools } from "./tool-kit.js";
+export { getAllTools } from "./tools/index.js";

package/src/infra/browser.ts

@@ -0,0 +1,111 @@
+/**
+ * Shared stealth browser infrastructure using Camoufox (anti-detection Firefox).
+ * Provides a singleton browser instance that any tool can use for scraping.
+ *
+ * Usage:
+ *   import { StealthBrowser } from "../infra/browser.js";
+ *   const data = await StealthBrowser.fetchJson<MyType>(url);
+ *   const result = await StealthBrowser.evaluate(url, () => document.title);
+ */
+import "./node-version.js";
+import { Camoufox } from "camoufox-js";
+import type { Browser, Page } from "playwright-core";
+
+let browser: Browser | null = null;
+let page: Page | null = null;
+let launching: Promise<void> | null = null;
+let pageQueue: Promise<void> = Promise.resolve();
+
+async function ensureBrowser(): Promise<Page> {
+  if (page && browser?.isConnected()) return page;
+
+  // Prevent concurrent launches
+  if (launching) {
+    await launching;
+    if (page && browser?.isConnected()) return page;
+  }
+
+  launching = (async () => {
+    const b = await Camoufox({ headless: true });
+    browser = b;
+    page = await b.newPage();
+  })();
+
+  await launching;
+  launching = null;
+  return page!;
+}
+
+async function withPage<T>(fn: (p: Page) => Promise<T>): Promise<T> {
+  let resolve!: () => void;
+  const next = new Promise<void>((r) => { resolve = r; });
+  const prev = pageQueue;
+  pageQueue = next;
+  await prev;
+  try {
+    const p = await ensureBrowser();
+    return await fn(p);
+  } finally {
+    resolve();
+  }
+}
+
+export const StealthBrowser = {
+  /**
+   * Navigate to a URL, run a JS function in the page context, and return the result.
+   */
+  async evaluate<T>(url: string, fn: () => T | Promise<T>): Promise<T> {
+    return withPage(async (p) => {
+      await p.goto(url, { waitUntil: "domcontentloaded", timeout: 15000 });
+      return p.evaluate(fn);
+    });
+  },
+
+  /**
+   * Fetch JSON from a URL using the browser's session (cookies, TLS fingerprint).
+   * Useful for APIs that block Node.js fetch but allow real browsers.
+   */
+  async fetchJson<T>(url: string): Promise<T> {
+    return withPage(async (p) => {
+      const result = await p.evaluate(async (fetchUrl: string) => {
+        const res = await fetch(fetchUrl, { credentials: "include" });
+        if (!res.ok) throw new Error(`HTTP ${res.status}`);
+        return res.json();
+      }, url);
+      return result as T;
+    });
+  },
+
+  /**
+   * Run a custom async function in the browser page context.
+   * The page must already be on a relevant domain for cookies to work.
+   */
+  async run<T>(fn: (page: Page) => Promise<T>): Promise<T> {
+    return withPage(async (p) => fn(p));
+  },
+
+  /**
+   * Navigate to a URL and establish session cookies for that domain.
+   */
+  async initSession(url: string): Promise<void> {
+    return withPage(async (p) => {
+      await p.goto(url, { waitUntil: "domcontentloaded", timeout: 15000 });
+    });
+  },
+
+  /**
+   * Close the browser. It will be re-launched on next use.
+   */
+  async close(): Promise<void> {
+    if (browser) {
+      await browser.close().catch(() => {});
+      browser = null;
+      page = null;
+    }
+  },
+};
+
+// Clean up on process exit
+process.on("exit", () => {
+  browser?.close().catch(() => {});
+});

package/src/infra/cache.ts

@@ -0,0 +1,103 @@
+interface CacheEntry<T> {
+  value: T;
+  expiresAt: number;
+  cachedAt: number;
+}
+
+export interface StaleResult<T> {
+  value: T;
+  stale: true;
+  cachedAt: number;
+}
+
+export class Cache {
+  private store = new Map<string, CacheEntry<unknown>>();
+  private lastStaleHit = false;
+  private lastStaleCachedAt = 0;
+
+  get<T>(key: string): T | undefined {
+    const entry = this.store.get(key);
+    if (!entry) return undefined;
+    if (Date.now() > entry.expiresAt) return undefined;
+    return entry.value as T;
+  }
+
+  /**
+   * Return an expired entry if it exists and is within the stale limit.
+   * Unlike get(), this does not require the entry to be within its TTL.
+   * Entries beyond the stale limit are deleted.
+   */
+  getStale<T>(key: string, staleLimitMs: number): StaleResult<T> | undefined {
+    const entry = this.store.get(key);
+    if (!entry) return undefined;
+
+    if (Date.now() > entry.cachedAt + staleLimitMs) {
+      this.store.delete(key);
+      return undefined;
+    }
+
+    this.lastStaleHit = true;
+    this.lastStaleCachedAt = entry.cachedAt;
+    return { value: entry.value as T, stale: true, cachedAt: entry.cachedAt };
+  }
+
+  /**
+   * Consume the stale flag set by the last getStale() hit.
+   * Returns { stale: true, cachedAt } if the last getStale() found data,
+   * then resets the flag. Used by wrapProvider to propagate stale metadata.
+   */
+  consumeStaleFlag(): { stale: boolean; cachedAt: number } {
+    const result = { stale: this.lastStaleHit, cachedAt: this.lastStaleCachedAt };
+    this.lastStaleHit = false;
+    this.lastStaleCachedAt = 0;
+    return result;
+  }
+
+  set<T>(key: string, value: T, ttlMs: number): void {
+    this.store.set(key, { value, expiresAt: Date.now() + ttlMs, cachedAt: Date.now() });
+  }
+
+  invalidate(pattern: string): void {
+    for (const key of this.store.keys()) {
+      if (key.includes(pattern)) {
+        this.store.delete(key);
+      }
+    }
+  }
+
+  clear(): void {
+    this.store.clear();
+  }
+
+  get size(): number {
+    return this.store.size;
+  }
+}
+
+// Shared cache instance
+export const cache = new Cache();
+
+// Default TTLs
+export const TTL = {
+  QUOTE: 60_000,         // 1 minute
+  HISTORY: 3_600_000,    // 1 hour
+  FUNDAMENTALS: 86_400_000, // 24 hours
+  MACRO: 3_600_000,      // 1 hour
+  SENTIMENT: 300_000,    // 5 minutes
+  OPTIONS_CHAIN: 120_000, // 2 minutes
+  CRUMB: 900_000,        // 15 minutes
+  WEB_SEARCH: 300_000,   // 5 minutes
+  FINNHUB_NEWS: 300_000, // 5 minutes
+} as const;
+
+// Stale limits — how long past TTL expiry a cached value is still useful as fallback
+export const STALE_LIMIT = {
+  QUOTE: 15 * 60_000,             // 15 minutes
+  HISTORY: 24 * 3_600_000,        // 24 hours
+  FUNDAMENTALS: 7 * 86_400_000,   // 7 days
+  MACRO: 24 * 3_600_000,          // 24 hours
+  SENTIMENT: 3_600_000,           // 1 hour
+  OPTIONS_CHAIN: 30 * 60_000,     // 30 minutes
+  WEB_SEARCH: 3_600_000,          // 1 hour
+  FINNHUB_NEWS: 3_600_000,        // 1 hour
+} as const;

package/src/infra/http-client.ts

@@ -0,0 +1,68 @@
+export interface HttpClientOptions {
+  timeoutMs?: number;
+  maxRetries?: number;
+  retryDelayMs?: number;
+  headers?: Record<string, string>;
+}
+
+const DEFAULT_OPTIONS: Required<HttpClientOptions> = {
+  timeoutMs: 10_000,
+  maxRetries: 2,
+  retryDelayMs: 1_000,
+  headers: {},
+};
+
+export class HttpError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly statusText: string,
+    public readonly body: string,
+  ) {
+    super(`HTTP ${status} ${statusText}`);
+    this.name = "HttpError";
+  }
+}
+
+export async function httpGet<T>(
+  url: string,
+  options: HttpClientOptions = {},
+): Promise<T> {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  let lastError: Error | undefined;
+
+  for (let attempt = 0; attempt <= opts.maxRetries; attempt++) {
+    if (attempt > 0) {
+      await sleep(opts.retryDelayMs * attempt);
+    }
+
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), opts.timeoutMs);
+
+    try {
+      const response = await fetch(url, {
+        signal: controller.signal,
+        headers: opts.headers,
+      });
+
+      if (!response.ok) {
+        const body = await response.text().catch(() => "");
+        throw new HttpError(response.status, response.statusText, body);
+      }
+
+      return (await response.json()) as T;
+    } catch (error) {
+      lastError = error as Error;
+      if (error instanceof HttpError && error.status >= 400 && error.status < 500) {
+        throw error; // Don't retry client errors
+      }
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  throw lastError!;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/infra/index.ts

@@ -0,0 +1,18 @@
+export { Cache, cache, TTL } from "./cache.js";
+export { RateLimiter, rateLimiter } from "./rate-limiter.js";
+export { httpGet, HttpError, type HttpClientOptions } from "./http-client.js";
+export { StealthBrowser } from "./browser.js";
+export {
+  getOpenCandleHomeDir,
+  ensureOpenCandleHomeDir,
+  resolveOpenCandlePath,
+  ensureParentDir,
+  getWatchlistPath,
+  getPortfolioPath,
+  getPredictionsPath,
+  getConfigPath,
+  getOnboardingPath,
+  getStateDbPath,
+  getLogsDir,
+  getBrowserProfileDir,
+} from "./opencandle-paths.js";

package/src/infra/native-dependencies.ts

@@ -0,0 +1,12 @@
+export function getNativeDependencyErrorMessage(error: unknown, dependencyName: string): string | null {
+  const message = error instanceof Error ? error.message : String(error);
+  if (
+    !message.includes("NODE_MODULE_VERSION") &&
+    !message.includes("was compiled against a different Node.js version")
+  ) {
+    return null;
+  }
+
+  return `${dependencyName} native binding was built for a different Node ABI than the active Node ${process.versions.node}. ` +
+    `Run \`npm rebuild ${dependencyName}\` or reinstall dependencies under the active Node with \`npm install\`.`;
+}

package/src/infra/node-version.ts

@@ -0,0 +1,24 @@
+const SUPPORTED_NODE_RANGE = "20.19+, 22.12+, or 24.x-26.x";
+
+function isSupportedNodeVersion(version: string): boolean {
+  const [majorRaw, minorRaw] = version.split(".");
+  const major = Number(majorRaw);
+  const minor = Number(minorRaw);
+
+  if (major === 20) return minor >= 19;
+  if (major === 22) return minor >= 12;
+  return major >= 24 && major < 27;
+}
+
+export function getUnsupportedNodeVersionMessage(version: string = process.versions.node): string | null {
+  if (isSupportedNodeVersion(version)) return null;
+
+  return `OpenCandle supports Node ${SUPPORTED_NODE_RANGE}. Current Node is ${version}. Use Node ${SUPPORTED_NODE_RANGE}; the repo default is Node 22.22.0 via \`nvm use\`. After switching Node versions, reinstall dependencies under the active Node with \`npm install\` or rebuild native modules with \`npm rebuild better-sqlite3\`.`;
+}
+
+export function assertSupportedNodeVersion(version?: string): void {
+  const message = getUnsupportedNodeVersionMessage(version);
+  if (message) throw new Error(message);
+}
+
+assertSupportedNodeVersion();

package/src/infra/open-url.ts

@@ -0,0 +1,28 @@
+import { execFile } from "node:child_process";
+
+export function openInBrowser(url: string): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    let command: string;
+    let args: string[];
+
+    if (process.platform === "darwin") {
+      command = "open";
+      args = [url];
+    } else if (process.platform === "win32") {
+      command = "cmd";
+      args = ["/c", "start", "", url];
+    } else {
+      command = "xdg-open";
+      args = [url];
+    }
+
+    const child = execFile(command, args, { timeout: 5000 }, (error) => {
+      if (error) {
+        reject(error);
+      } else {
+        resolve();
+      }
+    });
+    child.unref();
+  });
+}

package/src/infra/opencandle-paths.ts

@@ -0,0 +1,64 @@
+import { existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+
+const OPENCANDLE_HOME_ENV = "OPENCANDLE_HOME";
+
+function ensureDir(path: string): void {
+  if (!existsSync(path)) {
+    mkdirSync(path, { recursive: true });
+  }
+}
+
+export function getOpenCandleHomeDir(): string {
+  const override = process.env[OPENCANDLE_HOME_ENV];
+  return override ? resolve(override) : join(homedir(), ".opencandle");
+}
+
+export function ensureOpenCandleHomeDir(): string {
+  const home = getOpenCandleHomeDir();
+  ensureDir(home);
+  return home;
+}
+
+export function resolveOpenCandlePath(...segments: string[]): string {
+  return join(getOpenCandleHomeDir(), ...segments);
+}
+
+export function ensureParentDir(path: string): string {
+  const parent = dirname(path);
+  ensureDir(parent);
+  return parent;
+}
+
+export function getWatchlistPath(): string {
+  return resolveOpenCandlePath("watchlist.json");
+}
+
+export function getPortfolioPath(): string {
+  return resolveOpenCandlePath("portfolio.json");
+}
+
+export function getPredictionsPath(): string {
+  return resolveOpenCandlePath("predictions.json");
+}
+
+export function getConfigPath(): string {
+  return resolveOpenCandlePath("config.json");
+}
+
+export function getOnboardingPath(): string {
+  return resolveOpenCandlePath("onboarding.json");
+}
+
+export function getStateDbPath(): string {
+  return resolveOpenCandlePath("state.db");
+}
+
+export function getLogsDir(): string {
+  return resolveOpenCandlePath("logs");
+}
+
+export function getBrowserProfileDir(): string {
+  return resolveOpenCandlePath("browser-profile");
+}