opencandle 0.6.0 → 0.8.0

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",
@@ -68,7 +76,7 @@ For "today", "right now", "this morning", "after close", or "why did it move" pr
     status: "implemented",
     capabilityGapIds: ["sentiment_sample_depth"],
     content: `## Sentiment Snapshot Policy
-For sentiment-only prompts, include the direction and strength of the sentiment signal, the score scale when available, missing sources, why missing sources matter for the user's question, source-coverage risk, low sample counts, and how those gaps downgrade confidence. For ticker-specific sentiment prompts, compare sentiment with fetched price action and state whether sentiment diverges from price action. Treat sentiment as supporting evidence, not a standalone buy/sell verdict. Disclose sparse source coverage, unavailable Twitter/X sessions, provider gaps, or low sample depth instead of implying full-market sentiment coverage.`,
+For sentiment-only prompts, include the direction and strength of the sentiment signal, the score scale when available, the key positive and negative drivers behind the signal, representative source evidence, missing sources, why missing sources matter for the user's question, source-coverage risk, low sample counts, and how those gaps downgrade confidence. For ticker-specific sentiment prompts, compare sentiment with fetched price action and state whether sentiment diverges from price action; if quote data is unavailable, say price-action divergence could not be evaluated. Treat sentiment as supporting evidence, not a standalone buy/sell verdict. Disclose sparse source coverage, unavailable Twitter/X sessions, provider gaps, or low sample depth instead of implying full-market sentiment coverage.`,
   },
   filing_thesis_review: {
     id: "filing_thesis_review",
@@ -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}
@@ -460,7 +467,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,7 +482,7 @@ ${overlapGuidance}
 ${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}
 ${tableInstruction}
 - Provide a summary verdict: which is most attractive and why.
 - 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;
+}

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

@@ -0,0 +1,20 @@
+export class ExternalToolError extends Error {
+  constructor(
+    public readonly toolName: string,
+    message: string,
+    public readonly code?: string,
+  ) {
+    super(message);
+    this.name = "ExternalToolError";
+  }
+}
+
+export class ExternalToolNotInstalled extends Error {
+  constructor(
+    public readonly toolName: string,
+    public readonly installCmd: string,
+  ) {
+    super(`${toolName} is not installed. Install it with: ${installCmd}`);
+    this.name = "ExternalToolNotInstalled";
+  }
+}

package/src/providers/reddit-cli.ts

@@ -0,0 +1,286 @@
+import { type ExternalToolCommandResult, runExternalToolCommand } from "./external-tool-command.js";
+import { ExternalToolError, ExternalToolNotInstalled } from "./external-tool-error.js";
+import type { RedditComment } from "./reddit.js";
+
+const RDT_BINARY = "rdt";
+const RDT_INSTALL_CMD = "uv tool install rdt-cli";
+const COMMAND_TIMEOUT_MS = 20_000;
+const MAX_OUTPUT_CHARS = 2_000_000;
+
+interface RdtEnvelope<T> {
+  readonly ok: boolean;
+  readonly schema_version: string;
+  readonly data?: T;
+  readonly error?: {
+    readonly code?: string;
+    readonly message?: string;
+  };
+}
+
+export interface RdtPost {
+  readonly id: string;
+  readonly title: string;
+  readonly selftext: string;
+  readonly author: string;
+  readonly score: number;
+  readonly comments: number;
+  readonly subreddit?: string;
+  readonly url: string;
+  readonly permalink?: string;
+  readonly created: string;
+}
+
+interface RawRdtPost {
+  readonly id?: unknown;
+  readonly title?: unknown;
+  readonly selftext?: unknown;
+  readonly author?: unknown;
+  readonly score?: unknown;
+  readonly num_comments?: unknown;
+  readonly subreddit?: unknown;
+  readonly url?: unknown;
+  readonly permalink?: unknown;
+  readonly created_utc?: unknown;
+}
+
+interface RawRdtComment {
+  readonly id?: unknown;
+  readonly body?: unknown;
+  readonly author?: unknown;
+  readonly score?: unknown;
+  readonly permalink?: unknown;
+}
+
+interface RdtListingChild<T> {
+  readonly kind?: string;
+  readonly data?: T;
+}
+
+interface RdtListing<T> {
+  readonly data?: {
+    readonly children?: Array<RdtListingChild<T>>;
+  };
+}
+
+type RdtCommandRunner = (
+  command: string,
+  args: readonly string[],
+) => Promise<ExternalToolCommandResult>;
+
+let commandRunner: RdtCommandRunner = runCommand;
+
+export function setRdtCommandRunnerForTests(runner: RdtCommandRunner): void {
+  commandRunner = runner;
+}
+
+export function resetRdtCommandRunnerForTests(): void {
+  commandRunner = runCommand;
+}
+
+export async function searchRedditPosts(
+  query: string,
+  opts: { subreddit?: string; limit: number },
+): Promise<RdtPost[]> {
+  const args = ["search", query];
+  if (opts.subreddit) {
+    args.push("--subreddit", opts.subreddit);
+  }
+  args.push("--json", "--compact", "-n", String(opts.limit));
+  const data = await runRdt<RawRdtPost[]>(args);
+  if (!Array.isArray(data)) {
+    throw new ExternalToolError(RDT_BINARY, "rdt-cli returned invalid search data");
+  }
+  return data.map(adaptPost).filter((post) => post.id.length > 0);
+}
+
+export async function listSubredditPosts(
+  subreddit: string,
+  opts: { limit: number },
+): Promise<RdtPost[]> {
+  const data = await runRdt<RawRdtPost[]>([
+    "sub",
+    subreddit,
+    "--json",
+    "--compact",
+    "-n",
+    String(opts.limit),
+  ]);
+  if (!Array.isArray(data)) {
+    throw new ExternalToolError(RDT_BINARY, "rdt-cli returned invalid subreddit data");
+  }
+  return data.map((raw) => adaptPost({ ...raw, subreddit })).filter((post) => post.id.length > 0);
+}
+
+export async function readRedditPost(
+  postId: string,
+  opts: { limit: number },
+): Promise<{ post: RdtPost; comments: RedditComment[] }> {
+  const data = await runRdt<Array<RdtListing<RawRdtPost | RawRdtComment>>>([
+    "read",
+    postId,
+    "--json",
+    "-n",
+    String(opts.limit),
+  ]);
+  if (!Array.isArray(data)) {
+    throw new ExternalToolError(RDT_BINARY, "rdt-cli returned invalid read data");
+  }
+
+  const rawPost = data[0]?.data?.children?.find((child) => child.kind === "t3")?.data;
+  if (!rawPost) {
+    throw new ExternalToolError(RDT_BINARY, "rdt-cli read output did not include a post");
+  }
+
+  const post = adaptPost(rawPost as RawRdtPost);
+  const commentListing = data[1]?.data?.children ?? [];
+  const comments = commentListing
+    .filter((child): child is RdtListingChild<RawRdtComment> => child.kind === "t1")
+    .map((child) => adaptComment(child.data, post.permalink))
+    .filter((comment): comment is RedditComment => comment !== null)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, opts.limit);
+
+  return { post, comments };
+}
+
+async function runRdt<T>(args: readonly string[]): Promise<T> {
+  let result: ExternalToolCommandResult;
+  try {
+    result = await commandRunner(RDT_BINARY, args);
+  } catch (err) {
+    const nodeError = err as NodeJS.ErrnoException;
+    if (nodeError.code === "ENOENT") {
+      throw new ExternalToolNotInstalled(RDT_BINARY, RDT_INSTALL_CMD);
+    }
+    throw new ExternalToolError(
+      RDT_BINARY,
+      redactSensitiveOutput(err instanceof Error ? err.message : String(err)),
+    );
+  }
+
+  if (result.code !== 0) {
+    const envelopeError = parseCliErrorEnvelope(result.stdout);
+    if (envelopeError) {
+      throw new ExternalToolError(
+        RDT_BINARY,
+        redactSensitiveOutput(envelopeError.message),
+        envelopeError.code,
+      );
+    }
+    throw new ExternalToolError(
+      RDT_BINARY,
+      redactSensitiveOutput(result.stderr.trim() || `rdt-cli exited with code ${result.code}`),
+    );
+  }
+
+  let envelope: RdtEnvelope<T>;
+  try {
+    envelope = JSON.parse(result.stdout) as RdtEnvelope<T>;
+  } catch {
+    throw new ExternalToolError(
+      RDT_BINARY,
+      `rdt-cli returned non-JSON output: ${redactSensitiveOutput(result.stdout.slice(0, 200))}`,
+    );
+  }
+
+  if (!envelope.ok) {
+    throw new ExternalToolError(
+      RDT_BINARY,
+      redactSensitiveOutput(envelope.error?.message ?? "rdt-cli returned an error"),
+      envelope.error?.code,
+    );
+  }
+  if (envelope.data === undefined) {
+    throw new ExternalToolError(RDT_BINARY, "rdt-cli returned no data");
+  }
+  return envelope.data;
+}
+
+function parseCliErrorEnvelope(stdout: string): { code?: string; message: string } | null {
+  try {
+    const parsed = JSON.parse(stdout) as {
+      ok?: unknown;
+      error?: { code?: unknown; message?: unknown };
+    };
+    if (parsed.ok !== false || typeof parsed.error?.message !== "string") return null;
+    return {
+      code: typeof parsed.error.code === "string" ? parsed.error.code : undefined,
+      message: parsed.error.message,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function adaptPost(raw: RawRdtPost): RdtPost {
+  const permalink = stringValue(raw.permalink);
+  const url = stringValue(raw.url) || (permalink ? `https://reddit.com${permalink}` : "");
+  return {
+    id: stringValue(raw.id),
+    title: stringValue(raw.title),
+    selftext: stringValue(raw.selftext),
+    author: stringValue(raw.author) || "unknown",
+    score: numberValue(raw.score),
+    comments: numberValue(raw.num_comments),
+    subreddit: stringValue(raw.subreddit) || undefined,
+    url,
+    permalink: permalink || undefined,
+    created: normalizeCreatedAt(raw.created_utc),
+  };
+}
+
+function adaptComment(
+  raw: RawRdtComment | undefined,
+  postPermalink?: string,
+): RedditComment | null {
+  if (!raw || typeof raw.body !== "string" || raw.body.length === 0) return null;
+  const permalink = stringValue(raw.permalink) || postPermalink || "";
+  return {
+    id: stringValue(raw.id),
+    body: raw.body,
+    author: stringValue(raw.author) || "unknown",
+    score: numberValue(raw.score),
+    permalink: permalink ? `https://reddit.com${permalink}` : "",
+  };
+}
+
+function normalizeCreatedAt(value: unknown): string {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    const millis = value > 1_000_000_000_000 ? value : value * 1000;
+    return new Date(millis).toISOString();
+  }
+  if (typeof value === "string" && value.length > 0) {
+    const millis = Date.parse(value);
+    if (!Number.isNaN(millis)) return new Date(millis).toISOString();
+  }
+  return new Date(0).toISOString();
+}
+
+function stringValue(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+function numberValue(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
+export function redactSensitiveOutput(input: string): string {
+  return input
+    .slice(0, MAX_OUTPUT_CHARS)
+    .replace(
+      /\b([a-z0-9_]*(?:cookie|session|token)[a-z0-9_]*)\b\s*[:=]\s*[^;\s,)]+/gi,
+      "$1=[redacted]",
+    )
+    .replace(/\b([a-z0-9_]*(?:cookie|session|token)[a-z0-9_]*)=([^;\s,)]+)/gi, "$1=[redacted]")
+    .replace(
+      /(?:~|\/Users\/[^/\s]+|\/home\/[^/\s]+)?\/\.config\/rdt-cli\/credential\.json/g,
+      "[redacted-credential-path]",
+    );
+}
+
+function runCommand(command: string, args: readonly string[]): Promise<ExternalToolCommandResult> {
+  return runExternalToolCommand(command, args, {
+    timeoutMs: COMMAND_TIMEOUT_MS,
+    maxOutputChars: MAX_OUTPUT_CHARS,
+  });
+}