opencandle 0.3.0 → 0.5.0

package/src/memory/storage.ts

@@ -0,0 +1,205 @@
+import type Database from "better-sqlite3";
+
+interface PreferenceInput {
+  namespace?: string;
+  key: string;
+  valueJson: string;
+  confidence?: string;
+  source?: string;
+}
+
+export interface WorkflowPreferences {
+  riskProfile?: string;
+  timeHorizon?: string;
+  assetScope?: string;
+  positionCount?: number;
+  maxSinglePositionPct?: number;
+  dteTarget?: string;
+  objective?: string;
+  moneynessPreference?: string;
+  liquidityMinimum?: string;
+}
+
+interface WorkflowRunInput {
+  sessionId: string;
+  workflowType: string;
+  inputSlotsJson: string;
+  resolvedSlotsJson: string;
+  defaultsUsedJson: string;
+  outputSummary?: string;
+  /**
+   * Router route verbatim. Legacy rows contain `"workflow"` or `"fallback"`;
+   * typed-router rows may contain canonical route kinds. Defaults to
+   * `"workflow"` at the schema layer so legacy callers (rules-mode cascade)
+   * don't need to pass anything. Router-mode callers MUST pass this explicitly.
+   */
+  turnType?: string;
+}
+
+interface RecommendationInput {
+  workflowRunId: number;
+  recommendationType: string;
+  symbol?: string;
+  payloadJson?: string;
+}
+
+export class MemoryStorage {
+  constructor(private readonly db: Database.Database) {}
+
+  // --- Preferences ---
+
+  upsertPreference(input: PreferenceInput): void {
+    const now = new Date().toISOString();
+    const ns = input.namespace ?? "global";
+    const confidence = input.confidence ?? "medium";
+    const source = input.source ?? "explicit";
+
+    this.db
+      .prepare(
+        `INSERT INTO user_preferences (namespace, key, value_json, confidence, source, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT(namespace, key) DO UPDATE SET
+           value_json = excluded.value_json,
+           confidence = excluded.confidence,
+           source = excluded.source,
+           updated_at = excluded.updated_at`,
+      )
+      .run(ns, input.key, input.valueJson, confidence, source, now, now);
+  }
+
+  getPreference(
+    namespace: string,
+    key: string,
+  ): Record<string, string | number | null> | null {
+    return (
+      (this.db
+        .prepare("SELECT * FROM user_preferences WHERE namespace = ? AND key = ?")
+        .get(namespace, key) as Record<string, string | number | null>) ?? null
+    );
+  }
+
+  getPreferencesByNamespace(
+    namespace: string,
+  ): Array<Record<string, string | number | null>> {
+    return this.db
+      .prepare("SELECT * FROM user_preferences WHERE namespace = ?")
+      .all(namespace) as Array<Record<string, string | number | null>>;
+  }
+
+  getWorkflowPreferences(namespace: string = "global"): WorkflowPreferences {
+    const prefs = this.getPreferencesByNamespace(namespace);
+    const out: WorkflowPreferences = {};
+
+    for (const pref of prefs) {
+      const key = String(pref.key);
+      const raw = pref.value_json == null ? undefined : safeParseJson(String(pref.value_json));
+
+      switch (key) {
+        case "risk_profile":
+          if (typeof raw === "string") out.riskProfile = raw;
+          break;
+        case "time_horizon":
+          if (typeof raw === "string") out.timeHorizon = raw;
+          break;
+        case "asset_scope":
+          if (typeof raw === "string") out.assetScope = raw;
+          break;
+        case "position_count":
+          if (typeof raw === "number") out.positionCount = raw;
+          break;
+        case "max_single_position_pct":
+          if (typeof raw === "number") out.maxSinglePositionPct = raw;
+          break;
+        case "dte_target":
+          if (typeof raw === "string") out.dteTarget = raw;
+          break;
+        case "objective":
+          if (typeof raw === "string") out.objective = raw;
+          break;
+        case "moneyness_preference":
+          if (typeof raw === "string") out.moneynessPreference = raw;
+          break;
+        case "options_liquidity":
+        case "liquidity_minimum":
+          if (typeof raw === "string") {
+            out.liquidityMinimum =
+              raw === "high" ? "high_open_interest_and_tight_spread" : raw;
+          }
+          break;
+      }
+    }
+
+    return out;
+  }
+
+  // --- Workflow Runs ---
+
+  insertWorkflowRun(input: WorkflowRunInput): number {
+    const now = new Date().toISOString();
+    const result = this.db
+      .prepare(
+        `INSERT INTO workflow_runs (session_id, workflow_type, input_slots_json, resolved_slots_json, defaults_used_json, output_summary, created_at, turn_type)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+      )
+      .run(
+        input.sessionId,
+        input.workflowType,
+        input.inputSlotsJson,
+        input.resolvedSlotsJson,
+        input.defaultsUsedJson,
+        input.outputSummary ?? null,
+        now,
+        input.turnType ?? "workflow",
+      );
+    return Number(result.lastInsertRowid);
+  }
+
+  getRecentWorkflowRuns(
+    limit: number,
+  ): Array<Record<string, string | number | null>> {
+    return this.db
+      .prepare("SELECT * FROM workflow_runs ORDER BY id DESC LIMIT ?")
+      .all(limit) as Array<Record<string, string | number | null>>;
+  }
+
+  updateWorkflowRunOutputSummary(workflowRunId: number, outputSummary: string): void {
+    this.db
+      .prepare("UPDATE workflow_runs SET output_summary = ? WHERE id = ?")
+      .run(outputSummary, workflowRunId);
+  }
+
+  // --- Recommendations ---
+
+  insertRecommendation(input: RecommendationInput): number {
+    const now = new Date().toISOString();
+    const result = this.db
+      .prepare(
+        `INSERT INTO recommendations (workflow_run_id, recommendation_type, symbol, payload_json, created_at)
+         VALUES (?, ?, ?, ?, ?)`,
+      )
+      .run(
+        input.workflowRunId,
+        input.recommendationType,
+        input.symbol ?? null,
+        input.payloadJson ?? null,
+        now,
+      );
+    return Number(result.lastInsertRowid);
+  }
+
+  getRecommendationsByRun(
+    workflowRunId: number,
+  ): Array<Record<string, string | number | null>> {
+    return this.db
+      .prepare("SELECT * FROM recommendations WHERE workflow_run_id = ? ORDER BY id")
+      .all(workflowRunId) as Array<Record<string, string | number | null>>;
+  }
+}
+
+function safeParseJson(json: string): unknown {
+  try {
+    return JSON.parse(json);
+  } catch {
+    return json;
+  }
+}

package/src/memory/tool-defaults.ts

@@ -0,0 +1,87 @@
+import { initDefaultDatabase } from "./sqlite.js";
+
+export type ToolDefaults = Record<string, unknown>;
+type SqliteDb = ReturnType<typeof initDefaultDatabase>;
+
+export function getDefaults(toolName: string, db: SqliteDb = initDefaultDatabase()): ToolDefaults {
+  const rows = db
+    .prepare(
+      `SELECT param_path, value_json FROM tool_defaults WHERE tool_name = ? ORDER BY param_path`,
+    )
+    .all(toolName) as Array<{ param_path: string; value_json: string }>;
+
+  const defaults: ToolDefaults = {};
+  for (const row of rows) {
+    setPath(defaults, row.param_path, parseStoredValue(row.value_json));
+  }
+  return defaults;
+}
+
+export function getAllDefaults(db: SqliteDb = initDefaultDatabase()): Map<string, ToolDefaults> {
+  const rows = db
+    .prepare(
+      `SELECT tool_name, param_path, value_json FROM tool_defaults ORDER BY tool_name, param_path`,
+    )
+    .all() as Array<{ tool_name: string; param_path: string; value_json: string }>;
+
+  const groups = new Map<string, ToolDefaults>();
+  for (const row of rows) {
+    const defaults = groups.get(row.tool_name) ?? {};
+    setPath(defaults, row.param_path, parseStoredValue(row.value_json));
+    groups.set(row.tool_name, defaults);
+  }
+  return groups;
+}
+
+export function setDefault(
+  toolName: string,
+  paramPath: string,
+  value: unknown,
+  db: SqliteDb = initDefaultDatabase(),
+): void {
+  db.prepare(
+    `INSERT INTO tool_defaults (tool_name, param_path, value_json, set_at)
+     VALUES (?, ?, ?, ?)
+     ON CONFLICT(tool_name, param_path) DO UPDATE SET
+       value_json = excluded.value_json,
+       set_at = excluded.set_at`,
+  ).run(toolName, paramPath, JSON.stringify(value), new Date().toISOString());
+}
+
+export function clearDefault(
+  toolName: string,
+  paramPath: string,
+  db: SqliteDb = initDefaultDatabase(),
+): void {
+  db.prepare(`DELETE FROM tool_defaults WHERE tool_name = ? AND param_path = ?`).run(
+    toolName,
+    paramPath,
+  );
+}
+
+function parseStoredValue(valueJson: string): unknown {
+  try {
+    return JSON.parse(valueJson);
+  } catch {
+    return valueJson;
+  }
+}
+
+function setPath(target: ToolDefaults, path: string, value: unknown): void {
+  const parts = path.split(".").filter(Boolean);
+  if (parts.length === 0) return;
+
+  let cursor: Record<string, unknown> = target;
+  for (const part of parts.slice(0, -1)) {
+    const existing = cursor[part];
+    if (!isPlainObject(existing)) {
+      cursor[part] = {};
+    }
+    cursor = cursor[part] as Record<string, unknown>;
+  }
+  cursor[parts[parts.length - 1]] = value;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/memory/types.ts

@@ -0,0 +1,71 @@
+/** Memory categories for typed, selective retrieval. */
+export type MemoryCategory =
+  | "investor_profile"
+  | "interaction_feedback"
+  | "workflow_history"
+  | "references";
+
+/** A memory entry with category and freshness metadata. */
+export interface MemoryEntry {
+  key: string;
+  value: string;
+  category: MemoryCategory;
+  recordedAt: string;
+  confidence?: string;
+  source?: string;
+}
+
+/** Staleness thresholds in milliseconds per category. */
+export const STALENESS_THRESHOLDS: Record<MemoryCategory, number> = {
+  investor_profile: 90 * 24 * 60 * 60 * 1000,    // 90 days
+  interaction_feedback: 14 * 24 * 60 * 60 * 1000, // 14 days
+  workflow_history: 7 * 24 * 60 * 60 * 1000,      // 7 days
+  references: 30 * 24 * 60 * 60 * 1000,           // 30 days
+};
+
+/** Map preference keys to memory categories. */
+export const KEY_TO_CATEGORY: Record<string, MemoryCategory> = {
+  risk_profile: "investor_profile",
+  time_horizon: "investor_profile",
+  asset_scope: "investor_profile",
+  position_count: "investor_profile",
+  max_single_position_pct: "investor_profile",
+  account_type: "investor_profile",
+  income_vs_growth: "investor_profile",
+  dte_target: "investor_profile",
+  objective: "investor_profile",
+  moneyness_preference: "investor_profile",
+  liquidity_minimum: "investor_profile",
+};
+
+/** Categories relevant to each workflow type. */
+export const WORKFLOW_RELEVANT_CATEGORIES: Record<string, MemoryCategory[]> = {
+  portfolio_builder: ["investor_profile", "interaction_feedback", "workflow_history"],
+  options_screener: ["investor_profile", "interaction_feedback", "workflow_history"],
+  compare_assets: ["investor_profile", "workflow_history"],
+  comprehensive_analysis: ["investor_profile", "workflow_history"],
+  single_asset_analysis: ["investor_profile"],
+  general_finance_qa: ["investor_profile"],
+  workflow_dispatch: ["investor_profile", "workflow_history"],
+  agent_task: ["investor_profile", "workflow_history"],
+  clarification: ["investor_profile", "workflow_history"],
+  pass_through: [],
+  unclassified: ["investor_profile"],
+};
+
+/** Check whether a memory entry is stale. */
+export function isStale(entry: MemoryEntry, now: Date = new Date()): boolean {
+  const threshold = STALENESS_THRESHOLDS[entry.category];
+  const age = now.getTime() - new Date(entry.recordedAt).getTime();
+  return age > threshold;
+}
+
+/** Keys whose values are market-sensitive and must never be trusted from memory. */
+export const NEVER_TRUST_FROM_MEMORY = new Set([
+  "stock_price",
+  "crypto_price",
+  "market_thesis",
+  "target_price",
+  "entry_price",
+  "stop_loss",
+]);

package/src/onboarding/connect.ts

@@ -0,0 +1,184 @@
+// Shared `runProviderConnect` function — the actual side-effectful flow that
+// opens a browser, collects a pasted API key, validates it against the
+// provider's API, persists it to `~/.opencandle/config.json`, and refreshes
+// the cached Config so the next tool call sees the new credential.
+//
+// Called from two places:
+//   1. The Pi `tool_result` extension handler when the user picks "Connect now"
+//      in the just-in-time prompt (Task Group 10).
+//   2. The `/connect` Pi command (Task Group 13).
+//
+// Validation (Task Group 8 final pass): before persisting, the pasted key is
+// validated via `validateCredential`, which makes a single cheap request to
+// the provider's canonical API and classifies the response. A hard
+// auth failure (401/403 or a provider-specific error-in-200-body) is
+// returned as `invalid_key` WITHOUT persisting the bad value; a transient
+// failure (timeout, 5xx, network error) warns the user but still persists
+// the key so they aren't blocked on a provider outage — the next real tool
+// call will surface any lingering issue via the credential-required tag.
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { openInBrowser } from "../infra/open-url.js";
+import {
+  loadFileConfig,
+  saveFileConfig,
+  loadConfig,
+  type OpenCandleFileConfig,
+} from "../config.js";
+import {
+  getProvider,
+  getCredentialSource,
+  type ProviderId,
+} from "./providers.js";
+import {
+  loadOnboardingState,
+  markProviderCompleted,
+  saveOnboardingState,
+} from "./state.js";
+import { validateCredential } from "./validation.js";
+
+export type ConnectResult =
+  | { status: "connected" }
+  | { status: "cancelled" }
+  | { status: "blocked_by_env" }
+  | { status: "invalid_key"; httpStatus?: number; message?: string };
+
+function writeNested(
+  obj: Record<string, unknown>,
+  path: readonly string[],
+  value: string,
+): Record<string, unknown> {
+  if (path.length === 0) return obj;
+  const [head, ...rest] = path;
+  const next = { ...obj };
+  if (rest.length === 0) {
+    next[head] = value;
+  } else {
+    const child =
+      next[head] && typeof next[head] === "object"
+        ? (next[head] as Record<string, unknown>)
+        : {};
+    next[head] = writeNested(child, rest, value);
+  }
+  return next;
+}
+
+/**
+ * Persist an already-validated provider credential.
+ *
+ * Writes the key into `~/.opencandle/config.json` (preserving sibling fields),
+ * refreshes the cached `Config` so the next tool call sees the new value, and
+ * marks the provider as completed in the onboarding state.
+ *
+ * Shared by the TUI `/connect` flow (`runProviderConnect`) and the GUI
+ * provider-setup form. Validation is the caller's responsibility — both
+ * call sites run `validateCredential` before invoking this helper.
+ */
+export function persistProviderCredential(
+  providerId: ProviderId,
+  key: string,
+): void {
+  const descriptor = getProvider(providerId);
+  const existing = loadFileConfig() as unknown as Record<string, unknown>;
+  const updated = writeNested(
+    existing,
+    descriptor.configPath,
+    key,
+  ) as OpenCandleFileConfig;
+  saveFileConfig(updated);
+  loadConfig();
+  const state = loadOnboardingState();
+  saveOnboardingState(markProviderCompleted(state, providerId));
+}
+
+/**
+ * Run the connect flow for a single provider.
+ *
+ * Env-precedence short-circuit: if the provider's configured credential
+ * already comes from an environment variable, the file-config write would
+ * be invisible to the next tool call (env vars win in `resolveConfig`).
+ * Notify the user explicitly and return `blocked_by_env` — do not open
+ * the browser or collect a pasted value.
+ */
+export async function runProviderConnect(
+  ctx: ExtensionContext,
+  providerId: ProviderId,
+): Promise<ConnectResult> {
+  const descriptor = getProvider(providerId);
+
+  // Env-precedence check.
+  if (getCredentialSource(providerId) === "env") {
+    ctx.ui.notify(
+      `${descriptor.displayName} is currently set via the ${descriptor.envVar} environment variable. ` +
+        `To change it from here, unset that variable first and reopen /connect ${descriptor.aliases[0] ?? descriptor.id}. ` +
+        `Otherwise, update ${descriptor.envVar} directly in your shell profile.`,
+      "warning",
+    );
+    return { status: "blocked_by_env" };
+  }
+
+  // Open the signup URL in the user's browser. We ignore errors here — if
+  // the browser can't be opened, the user can still paste a key they
+  // already have, so we continue rather than bailing.
+  await openInBrowser(descriptor.signupUrl).catch(() => {});
+  ctx.ui.notify(
+    `Opening ${descriptor.displayName} signup in your browser...`,
+    "info",
+  );
+
+  // Prompt for the key. Uses the provider's instructionsHint as the
+  // placeholder text to remind the user what they're pasting.
+  const pasted = await ctx.ui.input(
+    `Paste your ${descriptor.displayName} API key`,
+    descriptor.instructionsHint,
+  );
+  if (!pasted) {
+    return { status: "cancelled" };
+  }
+  const trimmed = pasted.trim();
+  if (trimmed.length === 0) {
+    return { status: "cancelled" };
+  }
+
+  // Validate the key with the provider BEFORE persisting. Hard auth failures
+  // short-circuit here without writing anything; transient failures warn
+  // but proceed to persist so users don't get stuck on a provider outage.
+  ctx.ui.notify(`Verifying your ${descriptor.displayName} key...`, "info");
+  const validation = await validateCredential(providerId, trimmed);
+
+  if (validation.status === "invalid") {
+    const statusHint =
+      validation.httpStatus !== undefined ? ` (HTTP ${validation.httpStatus})` : "";
+    const messageHint = validation.message ? ` — ${validation.message}` : "";
+    ctx.ui.notify(
+      `${descriptor.displayName} rejected the key${statusHint}${messageHint}. ` +
+        `Your existing configuration was not changed. Re-run /connect ${
+          descriptor.aliases[0] ?? descriptor.id
+        } to try a different key.`,
+      "error",
+    );
+    return {
+      status: "invalid_key",
+      httpStatus: validation.httpStatus,
+      message: validation.message,
+    };
+  }
+
+  if (validation.status === "transient") {
+    ctx.ui.notify(
+      `Couldn't reach ${descriptor.displayName} to verify the key (${validation.reason}). ` +
+        `Saving it anyway — the next request will surface any issue.`,
+      "warning",
+    );
+    // Fall through to persist.
+  }
+
+  persistProviderCredential(providerId, trimmed);
+
+  ctx.ui.notify(
+    `${descriptor.displayName} connected. Your key has been saved.`,
+    "info",
+  );
+
+  return { status: "connected" };
+}

package/src/onboarding/credential-interceptor.ts

@@ -0,0 +1,134 @@
+// Pure decision function for handling `[OPENCANDLE_CREDENTIAL_REQUIRED ...]`
+// tool results. This module has NO Pi dependencies so it can be tested in
+// isolation — the Pi extension `tool_result` handler is a thin wrapper that
+// calls this function, inspects the returned `InterceptAction`, and drives
+// the appropriate side effects (promptUser, state mutation, tool rerun).
+//
+// Decision table — see design.md Decision 3 for the canonical version.
+
+import type { ProviderId } from "./providers.js";
+import { getProvider } from "./providers.js";
+import type { OnboardingState } from "./state.js";
+import type { CredentialRequiredReason } from "./tool-tags.js";
+
+export interface InterceptInput {
+  /** The provider id parsed from the tagged tool-result content. */
+  provider: ProviderId;
+  /** Why the credential was flagged as required. */
+  reason: CredentialRequiredReason;
+  /** Current persistent onboarding state (providers map, welcome flag). */
+  state: OnboardingState;
+  /** Providers already prompted at least once in this session (across workflows). */
+  sessionPromptedSet: ReadonlySet<ProviderId>;
+  /**
+   * Whether a hard-tier provider has already fired a prompt earlier in the
+   * current workflow invocation. When true, subsequent hard-provider prompts
+   * in the same workflow SHALL be silenced per the "at most one prompt per
+   * workflow" requirement in `conversational-provider-setup.spec.md`.
+   */
+  hardPromptFiredInWorkflow: boolean;
+  /** Injected clock for deterministic snooze-expiry tests. */
+  now: Date;
+}
+
+/** Outcome of the interception decision. */
+export type InterceptAction =
+  | {
+      action: "prompt";
+      provider: ProviderId;
+      reason: CredentialRequiredReason;
+    }
+  | {
+      action: "skip";
+      provider: ProviderId;
+      remediation: string;
+      /** True when the skip is due to explicit never_ask — downstream gap-note
+       *  synthesis should suppress the `/connect` remediation in that case. */
+      silenced: boolean;
+    };
+
+function buildRemediation(providerId: ProviderId): string {
+  const descriptor = getProvider(providerId);
+  // Prefer the first alias as the friendly target; fall back to the id.
+  const alias = descriptor.aliases[0] ?? providerId;
+  return `run /connect ${alias} to unlock`;
+}
+
+function skip(
+  providerId: ProviderId,
+  silenced: boolean,
+): InterceptAction {
+  return {
+    action: "skip",
+    provider: providerId,
+    remediation: buildRemediation(providerId),
+    silenced,
+  };
+}
+
+/**
+ * Pure decision function — given an `InterceptInput`, return either a
+ * `prompt` action (the extension handler should pause and call `promptUser`)
+ * or a `skip` action (the handler should replace the tool result with a
+ * `[OPENCANDLE_SKIPPED ...]` placeholder).
+ *
+ * No side effects. No Pi imports. Trivially unit-testable.
+ */
+export function resolveCredentialRequired(
+  input: InterceptInput,
+): InterceptAction {
+  const {
+    provider,
+    reason,
+    state,
+    sessionPromptedSet,
+    hardPromptFiredInWorkflow,
+    now,
+  } = input;
+
+  const descriptor = getProvider(provider);
+  const entry = state.providers[provider];
+
+  // 1. Never-ask: always skip, marked silenced so the gap-note copy drops the
+  //    `/connect` remediation.
+  if (entry?.status === "never_ask") {
+    return skip(provider, true);
+  }
+
+  // 2. Completed + missing (defensive — shouldn't normally happen because the
+  //    tool layer only emits `missing` when `hasCredential` returns false, and
+  //    a completed state implies the credential was persisted).
+  if (entry?.status === "completed" && reason === "missing") {
+    return skip(provider, false);
+  }
+
+  // 3. Session-level dedup: a previous prompt this session already settled
+  //    the user's answer for this provider. Don't re-ask until next session.
+  if (sessionPromptedSet.has(provider)) {
+    return skip(provider, false);
+  }
+
+  // 4. Per-workflow cap: at most one hard-provider prompt per workflow run.
+  if (hardPromptFiredInWorkflow && descriptor.tier === "hard") {
+    return skip(provider, false);
+  }
+
+  // 5. Active snooze: skip without decrementing the session set (the user
+  //    will see the prompt again if they try a workflow after snoozeUntil).
+  if (entry?.status === "snoozed") {
+    const until = Date.parse(entry.snoozeUntil);
+    if (!Number.isNaN(until) && now.getTime() < until) {
+      return skip(provider, false);
+    }
+    // snoozed but expired → fall through to prompt.
+  }
+
+  // 6. Completed + stale: re-prompt. This is the ONE stale-credential path
+  //    this change ships — the full failure-as-invitation story is deferred.
+  if (entry?.status === "completed" && reason === "stale") {
+    return { action: "prompt", provider, reason };
+  }
+
+  // 7. Default: prompt.
+  return { action: "prompt", provider, reason };
+}