opencandle 0.1.1 → 0.3.0

package/dist/infra/rate-limiter.js.map

@@ -1 +1 @@
-{"version":3,"file":"rate-limiter.js","sourceRoot":"","sources":["../../src/infra/rate-limiter.ts"],"names":[],"mappings":"AAWA,MAAM,OAAO,WAAW;IACd,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;IAE5C,SAAS,CAAC,QAAgB,EAAE,SAAiB,EAAE,UAAkB;QAC/D,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE;YACzB,MAAM,EAAE,SAAS;YACjB,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE;YACtB,MAAM,EAAE,EAAE,SAAS,EAAE,UAAU,EAAE;SAClC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,QAAgB;QAC5B,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC1C,IAAI,CAAC,MAAM;YAAE,OAAO,CAAC,sBAAsB;QAE3C,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAEpB,IAAI,MAAM,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;YACvB,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC;YACnB,OAAO;QACT,CAAC;QAED,kCAAkC;QAClC,MAAM,MAAM,GAAG,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC;QACvE,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACvE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACpB,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC;IACrB,CAAC;IAEO,MAAM,CAAC,MAAc;QAC3B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,OAAO,GAAG,CAAC,GAAG,GAAG,MAAM,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC;QACjD,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CACtB,MAAM,CAAC,MAAM,CAAC,SAAS,EACvB,MAAM,CAAC,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,UAAU,CACnD,CAAC;QACF,MAAM,CAAC,UAAU,GAAG,GAAG,CAAC;IAC1B,CAAC;CACF;AAED,+CAA+C;AAC/C,MAAM,CAAC,MAAM,WAAW,GAAG,IAAI,WAAW,EAAE,CAAC;AAC7C,WAAW,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAW,UAAU;AAC1D,WAAW,CAAC,SAAS,CAAC,WAAW,EAAE,EAAE,EAAE,KAAK,CAAC,CAAC,CAAE,aAAa;AAC7D,WAAW,CAAC,SAAS,CAAC,cAAc,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,wBAAwB;AACzE,WAAW,CAAC,SAAS,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,CAAW,cAAc"}
+{"version":3,"file":"rate-limiter.js","sourceRoot":"","sources":["../../src/infra/rate-limiter.ts"],"names":[],"mappings":"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"}

package/dist/memory/index.d.ts

@@ -3,3 +3,6 @@ export { MemoryStorage } from "./storage.js";
 export type { WorkflowPreferences } from "./storage.js";
 export { buildMemoryContext } from "./retrieval.js";
 export { extractPreferences } from "./preference-extractor.js";
+export { MemoryManager } from "./manager.js";
+export type { MemoryCategory, MemoryEntry } from "./types.js";
+export { isStale, STALENESS_THRESHOLDS, NEVER_TRUST_FROM_MEMORY } from "./types.js";

package/dist/memory/index.js

@@ -2,4 +2,6 @@ export { initDatabase, initDefaultDatabase, getTableNames, getSchemaVersion } fr
 export { MemoryStorage } from "./storage.js";
 export { buildMemoryContext } from "./retrieval.js";
 export { extractPreferences } from "./preference-extractor.js";
+export { MemoryManager } from "./manager.js";
+export { isStale, STALENESS_THRESHOLDS, NEVER_TRUST_FROM_MEMORY } from "./types.js";
 //# sourceMappingURL=index.js.map

package/dist/memory/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/memory/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACjG,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/memory/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACjG,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,OAAO,EAAE,OAAO,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC"}

package/dist/memory/manager.d.ts

@@ -0,0 +1,19 @@
+import type { MemoryStorage } from "./storage.js";
+import type { MemoryEntry } from "./types.js";
+/**
+ * Selective, typed memory retrieval with staleness rules
+ * and override suppression.
+ */
+export declare class MemoryManager {
+    private readonly storage;
+    constructor(storage: MemoryStorage);
+    /**
+     * Retrieve memory entries relevant to the given workflow type,
+     * filtering by category, staleness, and overrides.
+     */
+    retrieve(workflowType: string, overriddenSlots?: string[], now?: Date): MemoryEntry[];
+    /**
+     * Build compact text context from retrieved memory entries.
+     */
+    buildContext(workflowType: string, overriddenSlots?: string[], now?: Date): string;
+}

package/dist/memory/manager.js

@@ -0,0 +1,132 @@
+import { KEY_TO_CATEGORY, WORKFLOW_RELEVANT_CATEGORIES, NEVER_TRUST_FROM_MEMORY, isStale, } from "./types.js";
+/** Slot name → preference key(s) mapping for suppression. */
+const SLOT_TO_PREF_KEYS = {
+    riskProfile: ["risk_profile"],
+    assetScope: ["asset_scope"],
+    timeHorizon: ["time_horizon"],
+    dteTarget: ["dte_target"],
+    moneynessPreference: ["moneyness_preference"],
+    liquidityMinimum: ["liquidity_minimum", "options_liquidity"],
+};
+const MAX_WORKFLOW_HISTORY_PER_TYPE = 3;
+const MAX_PREFERENCE_LINES = 15;
+/**
+ * Selective, typed memory retrieval with staleness rules
+ * and override suppression.
+ */
+export class MemoryManager {
+    storage;
+    constructor(storage) {
+        this.storage = storage;
+    }
+    /**
+     * Retrieve memory entries relevant to the given workflow type,
+     * filtering by category, staleness, and overrides.
+     */
+    retrieve(workflowType, overriddenSlots, now = new Date()) {
+        const relevantCategories = WORKFLOW_RELEVANT_CATEGORIES[workflowType] ??
+            WORKFLOW_RELEVANT_CATEGORIES["unclassified"];
+        // Build set of preference keys to suppress
+        const suppressedKeys = new Set();
+        if (overriddenSlots) {
+            for (const slot of overriddenSlots) {
+                const keys = SLOT_TO_PREF_KEYS[slot];
+                if (keys)
+                    keys.forEach((k) => suppressedKeys.add(k));
+            }
+        }
+        const entries = [];
+        // Preferences as investor_profile entries
+        if (relevantCategories.includes("investor_profile")) {
+            const prefs = this.storage.getPreferencesByNamespace("global");
+            for (const pref of prefs) {
+                const key = String(pref.key);
+                if (suppressedKeys.has(key))
+                    continue;
+                if (NEVER_TRUST_FROM_MEMORY.has(key))
+                    continue;
+                const category = KEY_TO_CATEGORY[key] ?? "investor_profile";
+                if (!relevantCategories.includes(category))
+                    continue;
+                const entry = {
+                    key,
+                    value: tryParseValue(String(pref.value_json ?? "")),
+                    category,
+                    recordedAt: String(pref.updated_at ?? pref.created_at ?? now.toISOString()),
+                    confidence: pref.confidence != null ? String(pref.confidence) : undefined,
+                    source: pref.source != null ? String(pref.source) : undefined,
+                };
+                if (!isStale(entry, now)) {
+                    entries.push(entry);
+                }
+            }
+        }
+        // Workflow history
+        if (relevantCategories.includes("workflow_history")) {
+            const runs = this.storage.getRecentWorkflowRuns(MAX_WORKFLOW_HISTORY_PER_TYPE * 4);
+            const countsByType = new Map();
+            for (const run of runs) {
+                const wfType = String(run.workflow_type);
+                const count = countsByType.get(wfType) ?? 0;
+                if (count >= MAX_WORKFLOW_HISTORY_PER_TYPE)
+                    continue;
+                countsByType.set(wfType, count + 1);
+                const recordedAt = String(run.created_at ?? now.toISOString());
+                const entry = {
+                    key: `workflow_run_${run.id}`,
+                    value: run.output_summary
+                        ? `${wfType}: ${run.output_summary}`
+                        : wfType,
+                    category: "workflow_history",
+                    recordedAt,
+                };
+                if (!isStale(entry, now)) {
+                    entries.push(entry);
+                }
+            }
+        }
+        return entries.slice(0, MAX_PREFERENCE_LINES + MAX_WORKFLOW_HISTORY_PER_TYPE * 4);
+    }
+    /**
+     * Build compact text context from retrieved memory entries.
+     */
+    buildContext(workflowType, overriddenSlots, now = new Date()) {
+        const entries = this.retrieve(workflowType, overriddenSlots, now);
+        if (entries.length === 0)
+            return "";
+        const sections = [];
+        // Group by category
+        const byCategory = new Map();
+        for (const entry of entries) {
+            const list = byCategory.get(entry.category) ?? [];
+            list.push(entry);
+            byCategory.set(entry.category, list);
+        }
+        const profileEntries = byCategory.get("investor_profile");
+        if (profileEntries && profileEntries.length > 0) {
+            const lines = profileEntries.map((e) => `- ${e.key}: ${e.value}`);
+            sections.push("User Preferences:\n" + lines.join("\n"));
+        }
+        const historyEntries = byCategory.get("workflow_history");
+        if (historyEntries && historyEntries.length > 0) {
+            const lines = historyEntries.map((e) => `- ${e.value} (${e.recordedAt})`);
+            sections.push("Recent Workflows:\n" + lines.join("\n"));
+        }
+        const feedbackEntries = byCategory.get("interaction_feedback");
+        if (feedbackEntries && feedbackEntries.length > 0) {
+            const lines = feedbackEntries.map((e) => `- ${e.key}: ${e.value}`);
+            sections.push("Feedback:\n" + lines.join("\n"));
+        }
+        return sections.join("\n\n");
+    }
+}
+function tryParseValue(json) {
+    try {
+        const parsed = JSON.parse(json);
+        return typeof parsed === "string" ? parsed : JSON.stringify(parsed);
+    }
+    catch {
+        return json;
+    }
+}
+//# sourceMappingURL=manager.js.map

package/dist/memory/manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.js","sourceRoot":"","sources":["../../src/memory/manager.ts"],"names":[],"mappings":"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"}

package/dist/memory/sqlite.js

@@ -2,7 +2,7 @@ import { mkdirSync } from "node:fs";
 import { dirname } from "node:path";
 import Database from "better-sqlite3";
 import { getStateDbPath } from "../infra/opencandle-paths.js";
-const CURRENT_SCHEMA_VERSION = 1;
+const CURRENT_SCHEMA_VERSION = 2;
 const CURRENT_SCHEMA = `
   CREATE TABLE IF NOT EXISTS schema_version (
     version INTEGER NOT NULL
@@ -40,6 +40,17 @@ const CURRENT_SCHEMA = `
     created_at TEXT NOT NULL,
     FOREIGN KEY (workflow_run_id) REFERENCES workflow_runs(id)
   );
+
+  CREATE TABLE IF NOT EXISTS workflow_events (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    run_id TEXT NOT NULL,
+    step_index INTEGER NOT NULL,
+    event_type TEXT NOT NULL,
+    payload_json TEXT,
+    timestamp TEXT NOT NULL
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_workflow_events_run_id ON workflow_events(run_id);
 `;
 export function initDatabase(path) {
     if (path !== ":memory:") {

package/dist/memory/sqlite.js.map

@@ -1 +1 @@
-{"version":3,"file":"sqlite.js","sourceRoot":"","sources":["../../src/memory/sqlite.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AACtC,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAE9D,MAAM,sBAAsB,GAAG,CAAC,CAAC;AAEjC,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqCtB,CAAC;AAEF,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,IAAI,IAAI,KAAK,UAAU,EAAE,CAAC;QACxB,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAChD,CAAC;IACD,MAAM,EAAE,GAAG,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC9B,EAAE,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;IAChC,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC;IAC/B,mBAAmB,CAAC,EAAE,CAAC,CAAC;IAExB,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,MAAM,UAAU,mBAAmB;IACjC,OAAO,YAAY,CAAC,cAAc,EAAE,CAAC,CAAC;AACxC,CAAC;AAED,SAAS,mBAAmB,CAAC,EAAqB;IAChD,MAAM,cAAc,GAAG,iBAAiB,CAAC,EAAE,CAAC,CAAC;IAC7C,IAAI,cAAc,KAAK,sBAAsB,EAAE,CAAC;QAC9C,WAAW,CAAC,EAAE,CAAC,CAAC;QAChB,OAAO;IACT,CAAC;IAED,EAAE,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;AAC1B,CAAC;AAED,SAAS,iBAAiB,CAAC,EAAqB;IAC9C,MAAM,KAAK,GAAG,EAAE;SACb,OAAO,CAAC,iFAAiF,CAAC;SAC1F,GAAG,EAAkC,CAAC;IACzC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,4CAA4C,CAAC,CAAC,GAAG,EAE3D,CAAC;IACd,OAAO,GAAG,EAAE,OAAO,IAAI,IAAI,CAAC;AAC9B,CAAC;AAED,SAAS,WAAW,CAAC,EAAqB;IACxC,EAAE,CAAC,IAAI,CAAC;;;;;GAKP,CAAC,CAAC;IACH,EAAE,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IACxB,EAAE,CAAC,OAAO,CAAC,iDAAiD,CAAC,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC;AAC5F,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,EAAqB;IACjD,MAAM,IAAI,GAAG,EAAE;SACZ,OAAO,CAAC,iEAAiE,CAAC;SAC1E,GAAG,EAA6B,CAAC;IACpC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,EAAqB;IACpD,MAAM,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,4CAA4C,CAAC,CAAC,GAAG,EAE3D,CAAC;IACd,OAAO,GAAG,EAAE,OAAO,IAAI,CAAC,CAAC;AAC3B,CAAC"}
+{"version":3,"file":"sqlite.js","sourceRoot":"","sources":["../../src/memory/sqlite.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AACtC,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAE9D,MAAM,sBAAsB,GAAG,CAAC,CAAC;AAEjC,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgDtB,CAAC;AAEF,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,IAAI,IAAI,KAAK,UAAU,EAAE,CAAC;QACxB,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAChD,CAAC;IACD,MAAM,EAAE,GAAG,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC9B,EAAE,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;IAChC,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC;IAC/B,mBAAmB,CAAC,EAAE,CAAC,CAAC;IAExB,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,MAAM,UAAU,mBAAmB;IACjC,OAAO,YAAY,CAAC,cAAc,EAAE,CAAC,CAAC;AACxC,CAAC;AAED,SAAS,mBAAmB,CAAC,EAAqB;IAChD,MAAM,cAAc,GAAG,iBAAiB,CAAC,EAAE,CAAC,CAAC;IAC7C,IAAI,cAAc,KAAK,sBAAsB,EAAE,CAAC;QAC9C,WAAW,CAAC,EAAE,CAAC,CAAC;QAChB,OAAO;IACT,CAAC;IAED,EAAE,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;AAC1B,CAAC;AAED,SAAS,iBAAiB,CAAC,EAAqB;IAC9C,MAAM,KAAK,GAAG,EAAE;SACb,OAAO,CAAC,iFAAiF,CAAC;SAC1F,GAAG,EAAkC,CAAC;IACzC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,4CAA4C,CAAC,CAAC,GAAG,EAE3D,CAAC;IACd,OAAO,GAAG,EAAE,OAAO,IAAI,IAAI,CAAC;AAC9B,CAAC;AAED,SAAS,WAAW,CAAC,EAAqB;IACxC,EAAE,CAAC,IAAI,CAAC;;;;;GAKP,CAAC,CAAC;IACH,EAAE,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IACxB,EAAE,CAAC,OAAO,CAAC,iDAAiD,CAAC,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC;AAC5F,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,EAAqB;IACjD,MAAM,IAAI,GAAG,EAAE;SACZ,OAAO,CAAC,iEAAiE,CAAC;SAC1E,GAAG,EAA6B,CAAC;IACpC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,EAAqB;IACpD,MAAM,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,4CAA4C,CAAC,CAAC,GAAG,EAE3D,CAAC;IACd,OAAO,GAAG,EAAE,OAAO,IAAI,CAAC,CAAC;AAC3B,CAAC"}

package/dist/memory/types.d.ts

@@ -0,0 +1,21 @@
+/** 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 declare const STALENESS_THRESHOLDS: Record<MemoryCategory, number>;
+/** Map preference keys to memory categories. */
+export declare const KEY_TO_CATEGORY: Record<string, MemoryCategory>;
+/** Categories relevant to each workflow type. */
+export declare const WORKFLOW_RELEVANT_CATEGORIES: Record<string, MemoryCategory[]>;
+/** Check whether a memory entry is stale. */
+export declare function isStale(entry: MemoryEntry, now?: Date): boolean;
+/** Keys whose values are market-sensitive and must never be trusted from memory. */
+export declare const NEVER_TRUST_FROM_MEMORY: Set<string>;

package/dist/memory/types.js

@@ -0,0 +1,47 @@
+/** Staleness thresholds in milliseconds per category. */
+export const STALENESS_THRESHOLDS = {
+    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 = {
+    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 = {
+    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"],
+    unclassified: ["investor_profile"],
+};
+/** Check whether a memory entry is stale. */
+export function isStale(entry, now = new Date()) {
+    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",
+]);
+//# sourceMappingURL=types.js.map

package/dist/memory/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/memory/types.ts"],"names":[],"mappings":"AAiBA,yDAAyD;AACzD,MAAM,CAAC,MAAM,oBAAoB,GAAmC;IAClE,gBAAgB,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,EAAK,UAAU;IACzD,oBAAoB,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,UAAU;IAC1D,gBAAgB,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,EAAO,SAAS;IACzD,UAAU,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,EAAY,UAAU;CAC3D,CAAC;AAEF,gDAAgD;AAChD,MAAM,CAAC,MAAM,eAAe,GAAmC;IAC7D,YAAY,EAAE,kBAAkB;IAChC,YAAY,EAAE,kBAAkB;IAChC,WAAW,EAAE,kBAAkB;IAC/B,cAAc,EAAE,kBAAkB;IAClC,uBAAuB,EAAE,kBAAkB;IAC3C,YAAY,EAAE,kBAAkB;IAChC,gBAAgB,EAAE,kBAAkB;IACpC,UAAU,EAAE,kBAAkB;IAC9B,SAAS,EAAE,kBAAkB;IAC7B,oBAAoB,EAAE,kBAAkB;IACxC,iBAAiB,EAAE,kBAAkB;CACtC,CAAC;AAEF,iDAAiD;AACjD,MAAM,CAAC,MAAM,4BAA4B,GAAqC;IAC5E,iBAAiB,EAAE,CAAC,kBAAkB,EAAE,sBAAsB,EAAE,kBAAkB,CAAC;IACnF,gBAAgB,EAAE,CAAC,kBAAkB,EAAE,sBAAsB,EAAE,kBAAkB,CAAC;IAClF,cAAc,EAAE,CAAC,kBAAkB,EAAE,kBAAkB,CAAC;IACxD,sBAAsB,EAAE,CAAC,kBAAkB,EAAE,kBAAkB,CAAC;IAChE,qBAAqB,EAAE,CAAC,kBAAkB,CAAC;IAC3C,kBAAkB,EAAE,CAAC,kBAAkB,CAAC;IACxC,YAAY,EAAE,CAAC,kBAAkB,CAAC;CACnC,CAAC;AAEF,6CAA6C;AAC7C,MAAM,UAAU,OAAO,CAAC,KAAkB,EAAE,MAAY,IAAI,IAAI,EAAE;IAChE,MAAM,SAAS,GAAG,oBAAoB,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IACvD,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,EAAE,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,OAAO,EAAE,CAAC;IACjE,OAAO,GAAG,GAAG,SAAS,CAAC;AACzB,CAAC;AAED,oFAAoF;AACpF,MAAM,CAAC,MAAM,uBAAuB,GAAG,IAAI,GAAG,CAAC;IAC7C,aAAa;IACb,cAAc;IACd,eAAe;IACf,cAAc;IACd,aAAa;IACb,WAAW;CACZ,CAAC,CAAC"}

package/dist/onboarding/connect.d.ts

@@ -0,0 +1,23 @@
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { type ProviderId } from "./providers.js";
+export type ConnectResult = {
+    status: "connected";
+} | {
+    status: "cancelled";
+} | {
+    status: "blocked_by_env";
+} | {
+    status: "invalid_key";
+    httpStatus?: number;
+    message?: string;
+};
+/**
+ * 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 declare function runProviderConnect(ctx: ExtensionContext, providerId: ProviderId): Promise<ConnectResult>;

package/dist/onboarding/connect.js

@@ -0,0 +1,107 @@
+// 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 { openInBrowser } from "../infra/open-url.js";
+import { loadFileConfig, saveFileConfig, loadConfig, } from "../config.js";
+import { getProvider, getCredentialSource, } from "./providers.js";
+import { loadOnboardingState, markProviderCompleted, saveOnboardingState, } from "./state.js";
+import { validateCredential } from "./validation.js";
+function writeNested(obj, path, value) {
+    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]
+            : {};
+        next[head] = writeNested(child, rest, value);
+    }
+    return next;
+}
+/**
+ * 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, providerId) {
+    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.
+    }
+    // Persist to file config. Merge into the existing structure, preserving
+    // any unrelated fields.
+    const existing = loadFileConfig();
+    const updated = writeNested(existing, descriptor.configPath, trimmed);
+    saveFileConfig(updated);
+    // Refresh the cached Config so the next tool call sees the new value.
+    loadConfig();
+    // Update onboarding state to completed.
+    const state = loadOnboardingState();
+    saveOnboardingState(markProviderCompleted(state, providerId));
+    ctx.ui.notify(`${descriptor.displayName} connected. Your key has been saved.`, "info");
+    return { status: "connected" };
+}
+//# sourceMappingURL=connect.js.map

package/dist/onboarding/connect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.js","sourceRoot":"","sources":["../../src/onboarding/connect.ts"],"names":[],"mappings":"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"}

package/dist/onboarding/credential-interceptor.d.ts

@@ -0,0 +1,44 @@
+import type { ProviderId } 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;
+};
+/**
+ * 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 declare function resolveCredentialRequired(input: InterceptInput): InterceptAction;

package/dist/onboarding/credential-interceptor.js

@@ -0,0 +1,72 @@
+// 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 { getProvider } from "./providers.js";
+function buildRemediation(providerId) {
+    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, silenced) {
+    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) {
+    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 };
+}
+//# sourceMappingURL=credential-interceptor.js.map

package/dist/onboarding/credential-interceptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-interceptor.js","sourceRoot":"","sources":["../../src/onboarding/credential-interceptor.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,0EAA0E;AAC1E,4EAA4E;AAC5E,2EAA2E;AAC3E,yEAAyE;AACzE,EAAE;AACF,uEAAuE;AAGvE,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAwC7C,SAAS,gBAAgB,CAAC,UAAsB;IAC9C,MAAM,UAAU,GAAG,WAAW,CAAC,UAAU,CAAC,CAAC;IAC3C,sEAAsE;IACtE,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC;IAClD,OAAO,gBAAgB,KAAK,YAAY,CAAC;AAC3C,CAAC;AAED,SAAS,IAAI,CACX,UAAsB,EACtB,QAAiB;IAEjB,OAAO;QACL,MAAM,EAAE,MAAM;QACd,QAAQ,EAAE,UAAU;QACpB,WAAW,EAAE,gBAAgB,CAAC,UAAU,CAAC;QACzC,QAAQ;KACT,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,yBAAyB,CACvC,KAAqB;IAErB,MAAM,EACJ,QAAQ,EACR,MAAM,EACN,KAAK,EACL,kBAAkB,EAClB,yBAAyB,EACzB,GAAG,GACJ,GAAG,KAAK,CAAC;IAEV,MAAM,UAAU,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;IACzC,MAAM,KAAK,GAAG,KAAK,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IAExC,4EAA4E;IAC5E,6BAA6B;IAC7B,IAAI,KAAK,EAAE,MAAM,KAAK,WAAW,EAAE,CAAC;QAClC,OAAO,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IAC9B,CAAC;IAED,4EAA4E;IAC5E,6EAA6E;IAC7E,8DAA8D;IAC9D,IAAI,KAAK,EAAE,MAAM,KAAK,WAAW,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QAC1D,OAAO,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAC/B,CAAC;IAED,yEAAyE;IACzE,2EAA2E;IAC3E,IAAI,kBAAkB,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;QACrC,OAAO,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAC/B,CAAC;IAED,0EAA0E;IAC1E,IAAI,yBAAyB,IAAI,UAAU,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QAC5D,OAAO,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAC/B,CAAC;IAED,wEAAwE;IACxE,0EAA0E;IAC1E,IAAI,KAAK,EAAE,MAAM,KAAK,SAAS,EAAE,CAAC;QAChC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;QAC5C,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,OAAO,EAAE,GAAG,KAAK,EAAE,CAAC;YAClD,OAAO,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QAC/B,CAAC;QACD,gDAAgD;IAClD,CAAC;IAED,yEAAyE;IACzE,2EAA2E;IAC3E,IAAI,KAAK,EAAE,MAAM,KAAK,WAAW,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;QACxD,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAChD,CAAC;IAED,sBAAsB;IACtB,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;AAChD,CAAC"}

package/dist/onboarding/degradation-accumulator.d.ts

@@ -0,0 +1,21 @@
+import type { ProviderId } from "./providers.js";
+import type { OnboardingState } from "./state.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 declare function createDegradationAccumulator(): DegradationAccumulator;