opencandle 0.7.0 → 0.9.0

package/src/infra/node-version.ts

@@ -1,12 +1,11 @@
-const SUPPORTED_NODE_RANGE = "20.19+, 22.12+, or 24.x-26.x";
+const SUPPORTED_NODE_RANGE = "22.19+ 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;
+  if (major === 22) return minor >= 19;
   return major >= 24 && major < 27;
 }
 
@@ -22,5 +21,3 @@ export function assertSupportedNodeVersion(version?: string): void {
   const message = getUnsupportedNodeVersionMessage(version);
   if (message) throw new Error(message);
 }
-
-assertSupportedNodeVersion();

package/src/monitor.ts

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
-import "./infra/node-version.js";
 import { parseArgs } from "node:util";
 import { loadEnv } from "./config.js";
+import { assertSupportedNodeVersion } from "./infra/node-version.js";
 import { runLocalAutomationHeartbeat } from "./market-state/local-automation-service.js";
 import { MarketStateService } from "./market-state/service.js";
 import { initDefaultDatabase } from "./memory/sqlite.js";
 
+assertSupportedNodeVersion();
+
 const DEFAULT_MONITOR_INTERVAL_MS = 60_000;
 const MIN_MONITOR_INTERVAL_MS = 5_000;
 const MONITOR_OWNER_ID = `monitor:${process.pid}`;

package/src/onboarding/provider-status.ts

@@ -1,4 +1,7 @@
-import { spawn } from "node:child_process";
+import {
+  type ExternalToolCommandResult,
+  runExternalToolCommand,
+} from "../providers/external-tool-command.js";
 import type { ProviderId } from "./providers.js";
 import {
   getCredentialSource,
@@ -14,11 +17,7 @@ const COMMAND_TIMEOUT_MS = 5_000;
 const PUBLIC_HTTP_TIMEOUT_MS = 3_000;
 const MAX_OUTPUT_CHARS = 32_000;
 
-export interface CommandResult {
-  readonly code: number | null;
-  readonly stdout: string;
-  readonly stderr: string;
-}
+export type CommandResult = ExternalToolCommandResult;
 
 export type CommandRunner = (
   command: string,
@@ -69,6 +68,7 @@ export type ProviderStatus =
 export interface ProbeProviderStatusOptions {
   readonly mode?: "install" | "session";
   readonly force?: boolean;
+  readonly respectSkipped?: boolean;
   readonly commandRunner?: CommandRunner;
   readonly fetchImpl?: typeof fetch;
   readonly now?: Date;
@@ -97,7 +97,7 @@ export async function probeProviderStatus(
     isExternalToolProvider(provider) &&
     loadOnboardingState().providers[providerId]?.status === "never_ask";
 
-  if (skippedByPreference && !options.force) {
+  if (skippedByPreference && (!options.force || options.respectSkipped)) {
     return {
       providerId,
       kind: "external-tool",
@@ -376,35 +376,7 @@ export function redactSensitiveOutput(input: string): string {
 }
 
 export const runCommand: CommandRunner = (command, args, options) =>
-  new Promise((resolve, reject) => {
-    const child = spawn(command, [...args], { stdio: ["ignore", "pipe", "pipe"] });
-    let stdout = "";
-    let stderr = "";
-    let settled = false;
-
-    const timeout = setTimeout(() => {
-      if (settled) return;
-      settled = true;
-      child.kill("SIGTERM");
-      reject(new Error(`${command} timed out after ${options?.timeoutMs ?? COMMAND_TIMEOUT_MS}ms`));
-    }, options?.timeoutMs ?? COMMAND_TIMEOUT_MS);
-
-    child.stdout.on("data", (chunk: Buffer) => {
-      stdout = (stdout + chunk.toString("utf8")).slice(0, MAX_OUTPUT_CHARS);
-    });
-    child.stderr.on("data", (chunk: Buffer) => {
-      stderr = (stderr + chunk.toString("utf8")).slice(0, MAX_OUTPUT_CHARS);
-    });
-    child.on("error", (err) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timeout);
-      reject(err);
-    });
-    child.on("close", (code) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timeout);
-      resolve({ code, stdout, stderr });
-    });
+  runExternalToolCommand(command, args, {
+    timeoutMs: options?.timeoutMs ?? COMMAND_TIMEOUT_MS,
+    maxOutputChars: MAX_OUTPUT_CHARS,
   });

package/src/pi/session-writer-lock.ts

@@ -0,0 +1,156 @@
+import {
+  closeSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+
+export type ProcessKind = "tui" | "gui";
+
+export interface WriterLock {
+  pid: number;
+  processKind: ProcessKind;
+  acquiredAt: string;
+  lastHeartbeat: string;
+}
+
+export interface AcquireOptions {
+  pid?: number;
+  staleGraceMs?: number;
+}
+
+export type AcquireResult =
+  | { role: "writer"; lock: WriterLock }
+  | { role: "follower"; lock: WriterLock };
+
+export interface SessionLockScopeSource {
+  getSessionFile(): string | undefined;
+  getSessionDir(): string;
+}
+
+const DEFAULT_STALE_GRACE_MS = 15_000;
+
+export async function acquireWriterLock(
+  scopePath: string,
+  processKind: ProcessKind,
+  options: AcquireOptions = {},
+): Promise<AcquireResult> {
+  mkdirSync(dirname(lockPath(scopePath)), { recursive: true });
+  const pid = options.pid ?? process.pid;
+  const staleGraceMs = options.staleGraceMs ?? DEFAULT_STALE_GRACE_MS;
+
+  const created = tryCreate(scopePath, processKind, pid);
+  if (created) return { role: "writer", lock: created };
+
+  const existing = readWriterLock(scopePath);
+  if (existing && isLockCurrent(existing, staleGraceMs)) {
+    return { role: "follower", lock: existing };
+  }
+
+  await sleep(staleGraceMs);
+  const afterGrace = readWriterLock(scopePath);
+  if (afterGrace && isLockCurrent(afterGrace, staleGraceMs)) {
+    return { role: "follower", lock: afterGrace };
+  }
+
+  try {
+    unlinkSync(lockPath(scopePath));
+  } catch {
+    // Missing or concurrently removed is fine; the next create decides ownership.
+  }
+
+  const recovered = tryCreate(scopePath, processKind, pid);
+  if (recovered) return { role: "writer", lock: recovered };
+
+  const current = readWriterLock(scopePath) ?? afterGrace ?? existing;
+  if (!current) throw new Error("Unable to determine active writer lock");
+  return { role: "follower", lock: current };
+}
+
+export function readWriterLock(scopePath: string): WriterLock | null {
+  try {
+    return JSON.parse(readFileSync(lockPath(scopePath), "utf8")) as WriterLock;
+  } catch {
+    return null;
+  }
+}
+
+export function refreshWriterLock(scopePath: string, pid = process.pid): void {
+  const lock = readWriterLock(scopePath);
+  if (!lock || lock.pid !== pid) return;
+  writeFileSync(
+    lockPath(scopePath),
+    JSON.stringify({ ...lock, lastHeartbeat: new Date().toISOString() }, null, 2),
+  );
+}
+
+export function releaseWriterLock(scopePath: string, pid = process.pid): void {
+  const lock = readWriterLock(scopePath);
+  if (!lock || lock.pid !== pid) return;
+  try {
+    unlinkSync(lockPath(scopePath));
+  } catch {
+    // Best effort shutdown cleanup.
+  }
+}
+
+export const acquireSessionWriterLock = acquireWriterLock;
+export const refreshSessionWriterLock = refreshWriterLock;
+export const releaseSessionWriterLock = releaseWriterLock;
+
+export function writerLockScopeForSession(sessionManager: SessionLockScopeSource): string {
+  return sessionManager.getSessionFile() ?? sessionManager.getSessionDir();
+}
+
+function tryCreate(scopePath: string, processKind: ProcessKind, pid: number): WriterLock | null {
+  const now = new Date().toISOString();
+  const lock: WriterLock = { pid, processKind, acquiredAt: now, lastHeartbeat: now };
+  try {
+    const fd = openSync(lockPath(scopePath), "wx");
+    try {
+      writeFileSync(fd, JSON.stringify(lock, null, 2));
+    } finally {
+      closeSync(fd);
+    }
+    return lock;
+  } catch {
+    return null;
+  }
+}
+
+function isPidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isLockCurrent(lock: WriterLock, staleGraceMs: number): boolean {
+  const heartbeat = Date.parse(lock.lastHeartbeat);
+  return (
+    isPidAlive(lock.pid) && Number.isFinite(heartbeat) && Date.now() - heartbeat <= staleGraceMs
+  );
+}
+
+function lockPath(scopePath: string): string {
+  return isFileScope(scopePath) ? `${scopePath}.writer.lock` : join(scopePath, "writer.lock");
+}
+
+function isFileScope(scopePath: string): boolean {
+  if (scopePath.endsWith(".jsonl")) return true;
+  try {
+    return statSync(scopePath).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/pi/session.ts

@@ -1,4 +1,3 @@
-import "../infra/node-version.js";
 import {
   type AuthStorage,
   type CreateAgentSessionResult,
@@ -10,6 +9,7 @@ import {
   type SettingsManager,
 } from "@earendil-works/pi-coding-agent";
 import { loadEnv } from "../config.js";
+import { assertSupportedNodeVersion } from "../infra/node-version.js";
 import type { AskUserHandler } from "../types/index.js";
 import openCandleExtension from "./opencandle-extension.js";
 
@@ -28,6 +28,7 @@ export interface CreateOpenCandleSessionOptions {
 export async function createOpenCandleSession(
   options: CreateOpenCandleSessionOptions = {},
 ): Promise<CreateAgentSessionResult> {
+  assertSupportedNodeVersion();
   loadEnv();
 
   const cwd = options.cwd ?? process.cwd();

package/src/prompts/policy-cards.ts

@@ -37,6 +37,14 @@ export interface PolicyCard {
   content: string;
 }
 
+const HIGH_RISK_SPECULATION_SECTION_LIST =
+  "Why the win story is misleading, Main risks, Why limited capital changes the answer, If you insist, and Better uses for the money";
+const VALUATION_METRIC_EDUCATION_SECTION_LIST =
+  "Bottom line, then a one-sentence Core mental model, then Practical workflow, Where it misleads, Cross-checks, and Quick checklist";
+const VALUATION_METRIC_START = "Bottom line and a one-sentence Core mental model";
+const OPTIONS_CURRENT_FACTS_GUARDRAIL =
+  "Do not name strikes, expirations, premiums, Greeks, or implied volatility as current facts without fetched evidence.";
+
 const POLICY_CARDS: Record<PromptPolicyCardId, PolicyCard> = {
   ticker_disambiguation: {
     id: "ticker_disambiguation",
@@ -141,7 +149,7 @@ For watchlist, portfolio tracking, alert management, daily-report, prediction re
     status: "implemented",
     capabilityGapIds: ["brokerage_comparison", "cash_yield_products", "fund_tax_efficiency"],
     content: `## Retail Finance Tradeoff Policy
-For brokerage, account, cash-parking, mortgage-vs-investing, robo-advisor, debt payoff, high-risk speculation, or retail financial-product prompts, use the retail tradeoff answer shape. Do not punt just because no dedicated live-data provider exists. Answer from durable public finance knowledge, disclose unavailable provider coverage, and label provider-site facts or current yield facts as facts the user should verify instead of fabricating them. For brokerage, robo-advisor, and product comparisons, start with a direct comparison table, cover fees, expense ratios, advisory fees, cash drag, cash sweep yields, fractional shares, fund minimums, tax-loss-harvesting support, transfer/account fees, mutual-fund versus ETF availability, support quality, recurring investment ease, ETF tax efficiency, and asset-location caveats for taxable accounts; explicitly tell the user to verify current fees, minimums, promotions, and cash allocations on provider sites. For cash parking, compare liquidity, FDIC/SIPC/Treasury risk, rate risk, taxes, minimums, access timing, and default 6-12 month cash hierarchy without inventing live yields. Debt payoff prompts should lead with avalanche when rates differ materially, compare snowball only as a behavioral alternative, show approximate monthly interest cost, mention emergency-fund floor, balance-transfer/refinance options, minimum payments, prepayment penalties, and the missing extra-payment amount needed for a precise timeline. High-risk speculation prompts such as penny stocks should answer suitability directly, especially with limited capital; lead with downside, survivorship bias, opportunity cost, liquidity/manipulation/dilution risk, and safer alternatives such as diversified ETFs or fractional shares. Do not use Practical workflow, Cross-checks, or Quick checklist for high-risk speculation; use direct sections such as Why the win story is misleading, Main risks, Why limited capital changes the answer, If you insist, and Better uses for the money. If the user insists, frame any workflow as harm reduction with a tiny play-money bucket, a 100% loss assumption, no averaging down, and a pre-set exit rule. For mortgage-vs-investing prompts that compare against index funds, fetch broad-market history when available, then compare the guaranteed after-tax return from the supplied debt rate against uncertain market returns, liquidity, emergency fund, taxes, risk tolerance, time horizon, hybrid payoff/investing splits, and the practical implications of the user's stated rate.`,
+For brokerage, account, cash-parking, mortgage-vs-investing, robo-advisor, debt payoff, high-risk speculation, or retail financial-product prompts, use the retail tradeoff answer shape. Do not punt just because no dedicated live-data provider exists. Answer from durable public finance knowledge, disclose unavailable provider coverage, and label provider-site facts or current yield facts as facts the user should verify instead of fabricating them. For brokerage, robo-advisor, and product comparisons, start with a direct comparison table, cover fees, expense ratios, advisory fees, cash drag, cash sweep yields, fractional shares, fund minimums, tax-loss-harvesting support, transfer/account fees, mutual-fund versus ETF availability, support quality, recurring investment ease, ETF tax efficiency, and asset-location caveats for taxable accounts; explicitly tell the user to verify current fees, minimums, promotions, and cash allocations on provider sites. For cash parking, compare liquidity, FDIC/SIPC/Treasury risk, rate risk, taxes, minimums, access timing, and default 6-12 month cash hierarchy without inventing live yields. Debt payoff prompts should lead with avalanche when rates differ materially, compare snowball only as a behavioral alternative, show approximate monthly interest cost, mention emergency-fund floor, balance-transfer/refinance options, minimum payments, prepayment penalties, and the missing extra-payment amount needed for a precise timeline. High-risk speculation prompts such as penny stocks should answer suitability directly, especially with limited capital; lead with downside, survivorship bias, opportunity cost, liquidity/manipulation/dilution risk, and safer alternatives such as diversified ETFs or fractional shares. Do not use Practical workflow, Cross-checks, or Quick checklist for high-risk speculation; use direct sections such as ${HIGH_RISK_SPECULATION_SECTION_LIST}. If the user insists, frame any workflow as harm reduction with a tiny play-money bucket, a 100% loss assumption, no averaging down, and a pre-set exit rule. For mortgage-vs-investing prompts that compare against index funds, fetch broad-market history when available, then compare the guaranteed after-tax return from the supplied debt rate against uncertain market returns, liquidity, emergency fund, taxes, risk tolerance, time horizon, hybrid payoff/investing splits, and the practical implications of the user's stated rate.`,
   },
   concept_explainer: {
     id: "concept_explainer",
@@ -149,7 +157,7 @@ For brokerage, account, cash-parking, mortgage-vs-investing, robo-advisor, debt
     status: "implemented",
     capabilityGapIds: [],
     content: `## Concept Explainer Policy
-For conceptual or educational finance prompts, use a decision-framework shape instead of a stock-analysis shape. Do not fetch live data unless the user asks for current examples, named securities, or live comparisons. Do not mention OpenCandle tool names unless the user asks how to apply the concept with OpenCandle. Do not append Analyst View, Commitment, Reasoning Chain, Confidence Band, or Invalidation Level sections. Lead with Bottom line and a plain-language Core mental model, then add a simple numerical example early when the concept has mechanics. For pure definition or interpretation prompts, explain the concept directly and do not force the Practical workflow, Cross-checks, or Quick checklist shape unless the user asks how to apply it. Adapt the sections to the concept instead of forcing every topic into a valuation-metric template. Include common misconception coverage, typical ranges or rules of thumb when stable, and a concise practical takeaway. For high-risk speculation education, directly address suitability, survivorship bias, opportunity cost for limited capital, safer alternatives such as diversified ETFs or fractional shares, and a tiny play-money bucket with a 100% loss assumption if the user insists; do not use Practical workflow, Cross-checks, or Quick checklist, and use direct sections such as Why the win story is misleading, Main risks, Why limited capital changes the answer, If you insist, and Better uses for the money. For volatility or risk-indicator education, explain options-implied annualized volatility as magnitude, not direction; include the daily expected-move rule VIX / sqrt(252); include a small range table for low, normal, elevated, and crisis-like readings; Use direct Q&A headings such as Key things to keep straight, What a high reading means, What a low reading means, and Does a spike mean a crash is coming; state that spikes often accompany rather than reliably precede selloffs, that very high readings can become contrarian on average, and that no single indicator predicts crashes; frame the indicator as a thermometer, not a forecast; mention term structure as a fuller volatility cross-check; end with Practical takeaways. For inflation, cash, savings, or purchasing-power education, explain nominal returns versus real returns, how inflation affects cash, bonds, stocks, and real assets, common protection tools such as TIPS or shorter-duration bonds, and the tax/time-horizon tradeoffs. For options education, use a simple analogy before mechanics, define jargon immediately, and include an explicit Main risks section covering capped upside, assignment risk, premium decay or limited protection, tax consequences, and behavioral risk. For valuation-metric education, start with Bottom line, then a one-sentence Core mental model, then Practical workflow, Where it misleads, Cross-checks, and Quick checklist. Frame metrics as screening tools or question generators, not verdicts; cover earnings-quality distortions, variants such as trailing, forward, normalized, or cyclically adjusted, and cross-checks such as cash flow or enterprise-value lenses.`,
+For conceptual or educational finance prompts, use a decision-framework shape instead of a stock-analysis shape. Do not fetch live data unless the user asks for current examples, named securities, or live comparisons. Do not mention OpenCandle tool names unless the user asks how to apply the concept with OpenCandle. Do not append Analyst View, Commitment, Reasoning Chain, Confidence Band, or Invalidation Level sections. Lead with Bottom line and a plain-language Core mental model, then add a simple numerical example early when the concept has mechanics. For pure definition or interpretation prompts, explain the concept directly and do not force the Practical workflow, Cross-checks, or Quick checklist shape unless the user asks how to apply it. Adapt the sections to the concept instead of forcing every topic into a valuation-metric template. Include common misconception coverage, typical ranges or rules of thumb when stable, and a concise practical takeaway. For high-risk speculation education, directly address suitability, survivorship bias, opportunity cost for limited capital, safer alternatives such as diversified ETFs or fractional shares, and a tiny play-money bucket with a 100% loss assumption if the user insists; do not use Practical workflow, Cross-checks, or Quick checklist, and use direct sections such as ${HIGH_RISK_SPECULATION_SECTION_LIST}. For volatility or risk-indicator education, explain options-implied annualized volatility as magnitude, not direction; include the daily expected-move rule VIX / sqrt(252); include a small range table for low, normal, elevated, and crisis-like readings; Use direct Q&A headings such as Key things to keep straight, What a high reading means, What a low reading means, and Does a spike mean a crash is coming; state that spikes often accompany rather than reliably precede selloffs, that very high readings can become contrarian on average, and that no single indicator predicts crashes; frame the indicator as a thermometer, not a forecast; mention term structure as a fuller volatility cross-check; end with Practical takeaways. For inflation, cash, savings, or purchasing-power education, explain nominal returns versus real returns, how inflation affects cash, bonds, stocks, and real assets, common protection tools such as TIPS or shorter-duration bonds, and the tax/time-horizon tradeoffs. For options education, use a simple analogy before mechanics, define jargon immediately, and include an explicit Main risks section covering capped upside, assignment risk, premium decay or limited protection, tax consequences, and behavioral risk. For valuation-metric education, start with ${VALUATION_METRIC_EDUCATION_SECTION_LIST}. Frame metrics as screening tools or question generators, not verdicts; cover earnings-quality distortions, variants such as trailing, forward, normalized, or cyclically adjusted, and cross-checks such as cash flow or enterprise-value lenses.`,
   },
   concept_options_education: {
     id: "concept_options_education",
@@ -157,7 +165,7 @@ For conceptual or educational finance prompts, use a decision-framework shape in
     status: "implemented",
     capabilityGapIds: [],
     content: `## Options Education Policy
-For no-symbol options education prompts, teach the concept without fetching live option chains unless the user asks for current tradable examples. Start with Bottom line and a simple analogy before mechanics, then define jargon immediately. Use distinct beginner-friendly headings or a simple table for How it works, What you give up, Main risks, and When it is not ideal. Explain the payoff shape, why the strategy exists, and the tradeoffs in plain language, especially for long-term holdings. Include a Main risks section covering capped upside, assignment risk, share-price downside that premium does not protect, tax consequences including possible wash-sale or holding-period complications, liquidity or bid/ask caveats, behavioral risk, and tax treatment complexity. For volatility strategies such as long strangles or straddles, include a hypothetical stock price, strike prices, premiums, total debit, and break-even points; explain IV crush, IV rank or percentile, Vega, Theta, and why long-volatility trades can have a low win rate despite large payoff potential. Add practical trade-management guidance: profit target, stop loss, time-based exit, position sizing, and paper trading for beginners. Include a strangle versus straddle comparison and a pre-trade checklist covering catalyst, implied move, current IV environment, liquidity, max loss, tax caveat, and exit plan. Treat premium decay as a mechanics point for sellers rather than overstating it as a seller risk. Do not name strikes, expirations, premiums, Greeks, or implied volatility as current facts without fetched evidence.`,
+For no-symbol options education prompts, teach the concept without fetching live option chains unless the user asks for current tradable examples. Start with Bottom line and a simple analogy before mechanics, then define jargon immediately. Use distinct beginner-friendly headings or a simple table for How it works, What you give up, Main risks, and When it is not ideal. Explain the payoff shape, why the strategy exists, and the tradeoffs in plain language, especially for long-term holdings. Include a Main risks section covering capped upside, assignment risk, share-price downside that premium does not protect, tax consequences including possible wash-sale or holding-period complications, liquidity or bid/ask caveats, behavioral risk, and tax treatment complexity. For volatility strategies such as long strangles or straddles, include a hypothetical stock price, strike prices, premiums, total debit, and break-even points; explain IV crush, IV rank or percentile, Vega, Theta, and why long-volatility trades can have a low win rate despite large payoff potential. Add practical trade-management guidance: profit target, stop loss, time-based exit, position sizing, and paper trading for beginners. Include a strangle versus straddle comparison and a pre-trade checklist covering catalyst, implied move, current IV environment, liquidity, max loss, tax caveat, and exit plan. Treat premium decay as a mechanics point for sellers rather than overstating it as a seller risk. ${OPTIONS_CURRENT_FACTS_GUARDRAIL}`,
   },
   concept_inflation_cash_education: {
     id: "concept_inflation_cash_education",
@@ -173,7 +181,7 @@ For no-symbol inflation, cash, savings, or purchasing-power education, explain n
     status: "implemented",
     capabilityGapIds: [],
     content: `## Valuation Metric Education Policy
-For valuation-metric education, start with Bottom line and a one-sentence Core mental model, then ground the idea with a simple analogy and numerical example. Explain how to use the metric as a set of considerations rather than a rigid step-by-step verdict: what the business earns, what investors pay for those earnings, and what growth or risk expectations are embedded. Include rules of thumb carefully, noting that growth companies, mature value companies, cyclicals, banks, and different industries can deserve very different ranges. Then explain Practical workflow, Where it misleads, Cross-checks, and a Quick checklist in beginner-friendly language. Frame P/E, P/S, EV/EBITDA, trailing, forward, normalized, or cyclically adjusted metrics as screening tools and question generators, not verdicts. Cover earnings-quality distortions, cyclicality, balance-sheet differences, capital intensity, growth quality, margin durability, accounting noise, and cross-checks such as cash flow, enterprise-value lenses, historical ranges, and peer context. Do not add entry levels, confidence bands, or invalidation boilerplate for pure education prompts.`,
+For valuation-metric education, start with ${VALUATION_METRIC_START}, then ground the idea with a simple analogy and numerical example. Explain how to use the metric as a set of considerations rather than a rigid step-by-step verdict: what the business earns, what investors pay for those earnings, and what growth or risk expectations are embedded. Include rules of thumb carefully, noting that growth companies, mature value companies, cyclicals, banks, and different industries can deserve very different ranges. Then explain Practical workflow, Where it misleads, Cross-checks, and a Quick checklist in beginner-friendly language. Frame P/E, P/S, EV/EBITDA, trailing, forward, normalized, or cyclically adjusted metrics as screening tools and question generators, not verdicts. Cover earnings-quality distortions, cyclicality, balance-sheet differences, capital intensity, growth quality, margin durability, accounting noise, and cross-checks such as cash flow, enterprise-value lenses, historical ranges, and peer context. Do not add entry levels, confidence bands, or invalidation boilerplate for pure education prompts.`,
   },
   general_fallback: placeholder("general_fallback", "general_fallback", []),
 };

package/src/prompts/workflow-prompts.ts

@@ -56,6 +56,13 @@ const DISPLAY_NAMES: Record<string, string> = {
   metrics: "metrics",
 };
 
+const ASSUMPTIONS_RESPONSE_INSTRUCTION =
+  "- Start with the assumptions block above exactly as written. Do not relabel source attribution anywhere else in your response.";
+
+function currentDateLine(date = todayStr()): string {
+  return `Current date: ${date}`;
+}
+
 /**
  * Build a deterministic assumption disclosure block from resolution.sources.
  * This is the single authoritative provenance representation.
@@ -172,7 +179,7 @@ export function buildPortfolioPrompt(resolution: SlotResolution<PortfolioSlots>)
 4. Use analyze_risk on each candidate for volatility, Sharpe, and max drawdown.
 5. Use analyze_correlation across all candidates to check diversification.`;
 
-  return `Current date: ${todayStr()}
+  return `${currentDateLine()}
 
 Build a draft portfolio under these parameters:
 - Budget: ${formatBudget(s.budget)}
@@ -194,7 +201,7 @@ Portfolio construction guardrails:
 ${disclosureBlock}
 
 Response format:
-- Start with the assumptions block above exactly as written. Do not relabel source attribution anywhere else in your response.
+${ASSUMPTIONS_RESPONSE_INSTRUCTION}
 - Then start the analysis with "Bottom line:" and directly say what portfolio you would build for the user.
 - Commit to the draft: give concrete percentages for each position, not ranges, and not "consider allocating X-Y%".
 - Present an allocation table: symbol, allocation %, dollar amount, current price used, estimated shares, role, and a one-line analyst rationale for each position (what the data showed and why it belongs in this portfolio).
@@ -315,7 +322,7 @@ Protective-put hedge guidance:
     ? `Explain why the top pick is ranked #1. For covered calls with a cost basis, include the effective assignment sale price (strike + premium collected) and compare it with the ${s.costBasis !== undefined ? formatBudget(s.costBasis) : "user's"} cost basis.`
     : "Explain why the top pick is ranked #1.";
 
-  return `Current date: ${dateStr}
+  return `${currentDateLine(dateStr)}
 Do NOT invent or assume a different current date.${expirationSection}
 
 Screen and rank options contracts for ${s.symbol}:
@@ -349,7 +356,7 @@ ${rankingConstraints}
 ${disclosureBlock}
 
 Response format:
-- Start with the assumptions block above exactly as written. Do not relabel source attribution anywhere else in your response.
+${ASSUMPTIONS_RESPONSE_INSTRUCTION}
 - ${isCoveredCallContext ? `Start with an Interpretation line: "Interpretation: Treating ${s.symbol} as the held ticker because you phrased it as an existing position. If you meant ${s.symbol} as memory exposure or another ticker, clarify before trading."` : isProtectivePutContext ? `Start with an Interpretation line: "Interpretation: Treating this as buying protective puts on an existing long ${s.symbol} share position."` : "State the interpretation only if the user's requested underlying is ambiguous."}
 - Present top 3-5 ranked contracts in a table: strike, expiry, premium, delta, gamma, theta, vega, rho, IV, OI, bid-ask spread${isProtectivePutContext ? ", hedge floor, premium % of position" : ""}.
 - ${topPickExplanation}
@@ -448,6 +455,19 @@ macro hedge decision guidance:
 - Prioritize the evidence that matters most over ${timeHorizon}: near-term catalysts, earnings/guidance, forward-looking valuation/estimates, sentiment, macro sensitivity, and company-specific risks.
 - Call out evidence that is missing or unavailable, especially forward-looking estimates or company-specific catalysts.`
     : "";
+  const actionPlanResponse = timeHorizon
+    ? `
+- REQUIRED ACTION SECTION: Immediately after the summary verdict and before caveats, include a section exactly titled "### Cautious action plan". Use bullets for preferred tilt, entry conditions, position-sizing caution, downside risk/invalidation trigger, and the missing data that would change the plan for the ${timeHorizon} horizon. If this section is missing, the answer is incomplete.`
+    : "";
+  const responseHeadingOrder = timeHorizon
+    ? `
+Use these response headings in this order:
+1. Assumptions
+2. Comparison table
+3. Summary Verdict
+4. Cautious action plan
+5. Caveats`
+    : "";
 
   const disclosureBlock = buildDisclosureBlock(
     {
@@ -460,7 +480,7 @@ macro hedge decision guidance:
     resolution.sources as Record<string, SlotSource | undefined>,
   );
 
-  return `Current date: ${todayStr()}
+  return `${currentDateLine()}
 
 Compare these assets side by side: ${symbolList}${horizonLine}${budgetLine}
 
@@ -475,8 +495,10 @@ ${overlapGuidance}
 ${disclosureBlock}
 
 Response format:
-- Start with the assumptions block above exactly as written. Do not relabel source attribution anywhere else in your response.
+${responseHeadingOrder}
+${ASSUMPTIONS_RESPONSE_INSTRUCTION}
 ${tableInstruction}
 - Provide a summary verdict: which is most attractive and why.
+${actionPlanResponse}
 - Note any caveats (different sectors, concentration, market cap disparity, unavailable fundamentals, unavailable forward-looking estimates, etc.).${horizonResponse}`;
 }

package/src/providers/external-tool-command.ts

@@ -0,0 +1,164 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, isAbsolute, join, sep } from "node:path";
+
+const DEFAULT_TIMEOUT_MS = 20_000;
+const DEFAULT_MAX_OUTPUT_CHARS = 2_000_000;
+
+export interface ExternalToolCommandResult {
+  readonly code: number | null;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+export interface ExternalToolCommandOptions {
+  readonly timeoutMs?: number;
+  readonly maxOutputChars?: number;
+}
+
+interface CandidateOptions {
+  readonly env?: NodeJS.ProcessEnv;
+  readonly homeDir?: string;
+  readonly platform?: NodeJS.Platform;
+}
+
+export function getExternalToolCommandCandidates(
+  command: string,
+  options: CandidateOptions = {},
+): string[] {
+  if (isPathLikeCommand(command)) return [command];
+
+  const env = options.env ?? process.env;
+  const platform = options.platform ?? process.platform;
+  const home = options.homeDir ?? homedir();
+  const candidates = [command];
+  const binDirs = [
+    env.OPENCANDLE_EXTERNAL_TOOL_BIN_DIR,
+    env.UV_TOOL_BIN_DIR,
+    env.XDG_BIN_HOME,
+    home ? join(home, ".local", "bin") : undefined,
+  ];
+
+  for (const dir of binDirs) {
+    if (!dir) continue;
+    for (const executable of commandNames(command, platform)) {
+      candidates.push(join(dir, executable));
+    }
+  }
+
+  return [...new Set(candidates)];
+}
+
+export async function runExternalToolCommand(
+  command: string,
+  args: readonly string[],
+  options: ExternalToolCommandOptions = {},
+): Promise<ExternalToolCommandResult> {
+  const uvToolBinDirs = await resolveUvToolBinDirs(options);
+  const candidates = [
+    ...getExternalToolCommandCandidates(command),
+    ...uvToolBinDirs.flatMap((dir) =>
+      commandNames(command, process.platform).map((executable) => join(dir, executable)),
+    ),
+  ].filter((candidate, index, all) => all.indexOf(candidate) === index);
+  const existingCandidates = candidates.filter(
+    (candidate) => candidate === command || existsSync(candidate),
+  );
+  return runCandidate(
+    existingCandidates.length > 0 ? existingCandidates : [command],
+    args,
+    options,
+  );
+}
+
+async function resolveUvToolBinDirs(
+  options: ExternalToolCommandOptions,
+): Promise<readonly string[]> {
+  try {
+    const result = await spawnCommand("uv", ["tool", "dir", "--bin"], {
+      timeoutMs: Math.min(options.timeoutMs ?? DEFAULT_TIMEOUT_MS, 2_000),
+      maxOutputChars: 4_000,
+    });
+    if (result.code !== 0) return [];
+    const binDir = result.stdout.trim();
+    return binDir ? [binDir] : [];
+  } catch {
+    return [];
+  }
+}
+
+function runCandidate(
+  candidates: readonly string[],
+  args: readonly string[],
+  options: ExternalToolCommandOptions,
+): Promise<ExternalToolCommandResult> {
+  const [command, ...fallbacks] = candidates;
+  return spawnCommand(command, args, options).catch((err: NodeJS.ErrnoException) => {
+    if (err.code === "ENOENT" && fallbacks.length > 0) {
+      return runCandidate(fallbacks, args, options);
+    }
+    throw err;
+  });
+}
+
+function spawnCommand(
+  command: string,
+  args: readonly string[],
+  options: ExternalToolCommandOptions,
+): Promise<ExternalToolCommandResult> {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const maxOutputChars = options.maxOutputChars ?? DEFAULT_MAX_OUTPUT_CHARS;
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, [...args], { stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+
+    const timeout = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      child.kill("SIGTERM");
+      reject(new Error(`${command} timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+
+    child.stdout.on("data", (chunk: Buffer) => {
+      stdout = (stdout + chunk.toString("utf8")).slice(0, maxOutputChars);
+    });
+    child.stderr.on("data", (chunk: Buffer) => {
+      stderr = (stderr + chunk.toString("utf8")).slice(0, maxOutputChars);
+    });
+    child.on("error", (err) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      reject(err);
+    });
+    child.on("close", (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      resolve({ code, stdout, stderr });
+    });
+  });
+}
+
+function isPathLikeCommand(command: string): boolean {
+  return (
+    isAbsolute(command) || command.includes("/") || command.includes("\\") || command.includes(sep)
+  );
+}
+
+function commandNames(command: string, platform: NodeJS.Platform): string[] {
+  if (platform !== "win32") return [command];
+
+  const names = [command];
+  const pathExt = process.env.PATHEXT?.split(delimiter) ?? [".EXE", ".CMD", ".BAT"];
+  for (const ext of pathExt) {
+    if (!command.toLowerCase().endsWith(ext.toLowerCase())) {
+      names.push(`${command}${ext.toLowerCase()}`);
+    }
+  }
+  return names;
+}