opencandle 0.6.0 → 0.7.0

package/src/onboarding/tool-tags.ts

@@ -22,6 +22,7 @@ import type { ProviderId } from "./providers.js";
 // -----------------------------------------------------------------------------
 
 export type CredentialRequiredReason = "missing" | "stale";
+export type ExternalToolRequiredReason = "not_installed" | "session_missing" | "session_stale";
 
 export interface CredentialRequiredTagFields {
   provider: ProviderId;
@@ -48,11 +49,20 @@ export interface ConnectedTagFields {
   provider: ProviderId;
 }
 
+export interface ExternalToolRequiredTagFields {
+  provider: ProviderId;
+  reason: ExternalToolRequiredReason;
+  installCmd: string;
+  loginCmd?: string;
+  fallback: string | null;
+}
+
 export type ParsedTag =
   | ({ kind: "credential_required" } & CredentialRequiredTagFields)
   | ({ kind: "soft_degraded" } & SoftDegradedTagFields)
   | ({ kind: "skipped" } & SkippedTagFields)
-  | ({ kind: "connected" } & ConnectedTagFields);
+  | ({ kind: "connected" } & ConnectedTagFields)
+  | ({ kind: "external_tool_required" } & ExternalToolRequiredTagFields);
 
 // -----------------------------------------------------------------------------
 // Builders
@@ -106,12 +116,24 @@ export function buildConnectedTag(fields: ConnectedTagFields): string {
   return `[OPENCANDLE_CONNECTED provider=${fields.provider}]`;
 }
 
+export function buildExternalToolRequiredTag(fields: ExternalToolRequiredTagFields): string {
+  const parts: string[] = [
+    "[OPENCANDLE_EXTERNAL_TOOL_REQUIRED",
+    formatField("provider", fields.provider),
+    formatField("reason", fields.reason),
+    `installCmd=${quote(fields.installCmd)}`,
+    formatField("fallback", fields.fallback ?? "none"),
+  ];
+  if (fields.loginCmd) parts.push(`loginCmd=${quote(fields.loginCmd)}`);
+  return `${parts.join(" ")}]`;
+}
+
 // -----------------------------------------------------------------------------
 // Parser
 // -----------------------------------------------------------------------------
 
 const TAG_LINE_REGEX =
-  /\[OPENCANDLE_(CREDENTIAL_REQUIRED|SOFT_DEGRADED|SKIPPED|CONNECTED)([^\]]*)\]/;
+  /\[OPENCANDLE_(CREDENTIAL_REQUIRED|SOFT_DEGRADED|SKIPPED|CONNECTED|EXTERNAL_TOOL_REQUIRED)([^\]]*)\]/;
 
 function parseFields(raw: string): Record<string, string> {
   // Split on `key=value` pairs, respecting quoted values.
@@ -195,6 +217,27 @@ export function parseToolTag(text: string): ParsedTag | undefined {
       return { kind: "connected", provider: provider as ProviderId };
     }
 
+    case "EXTERNAL_TOOL_REQUIRED": {
+      const { provider, reason, installCmd, loginCmd, fallback } = fields;
+      if (
+        !provider ||
+        (reason !== "not_installed" &&
+          reason !== "session_missing" &&
+          reason !== "session_stale") ||
+        !installCmd
+      ) {
+        return undefined;
+      }
+      return {
+        kind: "external_tool_required",
+        provider: provider as ProviderId,
+        reason,
+        installCmd,
+        loginCmd,
+        fallback: fallback === undefined || fallback === "none" ? null : fallback,
+      };
+    }
+
     default:
       return undefined;
   }

package/src/onboarding/validation.ts

@@ -20,7 +20,7 @@
 // All validators share a 5-second timeout via `AbortSignal.timeout` so the
 // connect flow cannot hang if a provider is unreachable.
 
-import type { ProviderId } from "./providers.js";
+import type { ApiKeyProviderId } from "./providers.js";
 
 const VALIDATION_TIMEOUT_MS = 5_000;
 
@@ -107,7 +107,7 @@ function classifyAlphaVantageBody(body: string): ValidationResult | undefined {
  * touch the config file, onboarding state, or any in-memory cache.
  */
 export async function validateCredential(
-  providerId: ProviderId,
+  providerId: ApiKeyProviderId,
   key: string,
 ): Promise<ValidationResult> {
   switch (providerId) {

package/src/pi/opencandle-extension.ts

@@ -44,7 +44,6 @@ import type {
 import { SessionCoordinator } from "../runtime/session-coordinator.js";
 import { generateSessionTitle } from "../runtime/session-title.js";
 import { registerAskUserTool } from "../tools/interaction/ask-user.js";
-import { registerTwitterLoginTool } from "../tools/interaction/twitter-login.js";
 import type { AskUserHandler } from "../types/index.js";
 import {
   buildCompareAssetsWorkflowDefinition,
@@ -105,11 +104,10 @@ export default function openCandleExtension(
   let sessionTitleAttempted = false;
 
   // Register tools
-  for (const tool of getOpenCandleToolDefinitions()) {
+  for (const tool of getOpenCandleToolDefinitions({ askUserHandler: options?.askUserHandler })) {
     pi.registerTool(tool);
   }
   registerAskUserTool(pi, options?.askUserHandler);
-  registerTwitterLoginTool(pi);
 
   // /analyze command
   pi.registerCommand("analyze", {
@@ -144,11 +142,10 @@ export default function openCandleExtension(
   // `/connect <alias|id|category>` routes to a specific provider (or a
   // sub-picker for multi-provider categories like "search").
   pi.registerCommand("connect", {
-    description: "Connect a data provider (Alpha Vantage, FRED, Finnhub, Brave, Exa)",
+    description: "Connect an API-key data provider (Alpha Vantage, FRED, Finnhub, Brave, Exa)",
     handler: async (args, ctx) => {
-      const { listAllProviders, resolveProviderFromArgument, hasCredential } = await import(
-        "../onboarding/providers.js"
-      );
+      const { listApiKeyProviders, resolveProviderFromArgument, hasCredential, isApiKeyProvider } =
+        await import("../onboarding/providers.js");
 
       const formatState = (id: ProviderId): string => {
         const state = loadOnboardingState().providers[id];
@@ -178,11 +175,11 @@ export default function openCandleExtension(
 
       if (trimmed === "") {
         // Bare /connect → full picker.
-        targetId = await pickProvider(listAllProviders());
+        targetId = await pickProvider(listApiKeyProviders());
       } else {
         const resolved = resolveProviderFromArgument(trimmed);
         if (!resolved) {
-          const all = listAllProviders()
+          const all = listApiKeyProviders()
             .map((p) => `  ${p.displayName} (${p.aliases.join(", ")})`)
             .join("\n");
           ctx.ui.notify(`Unknown provider: "${trimmed}". Available:\n${all}`, "warning");
@@ -190,9 +187,25 @@ export default function openCandleExtension(
         }
         if (Array.isArray(resolved)) {
           // Multi-provider category — show a sub-picker.
-          targetId = await pickProvider(resolved as readonly ReturnType<typeof getProvider>[]);
+          const apiKeyProviders = resolved.filter(isApiKeyProvider);
+          if (apiKeyProviders.length === 0) {
+            ctx.ui.notify(
+              `"${trimmed}" does not use API-key setup. Run opencandle doctor for setup status.`,
+              "warning",
+            );
+            return;
+          }
+          targetId = await pickProvider(apiKeyProviders);
         } else {
-          targetId = (resolved as ReturnType<typeof getProvider>).id;
+          const descriptor = resolved as ReturnType<typeof getProvider>;
+          if (!isApiKeyProvider(descriptor)) {
+            ctx.ui.notify(
+              `${descriptor.displayName} does not use API-key setup. Run opencandle doctor for setup status.`,
+              "warning",
+            );
+            return;
+          }
+          targetId = descriptor.id;
         }
       }
 
@@ -389,15 +402,100 @@ export default function openCandleExtension(
       }
     }
 
-    // Second pass: look for a credential-required tag; on match, run the
-    // interception decision and either replace the tool result or prompt
-    // the user. Only the first credential_required tag in the content list
-    // is acted on — subsequent hard-tier prompts are silenced by the
-    // per-workflow cap at the decision-function level.
+    // Second pass: look for setup-required tags; on match, run the interception
+    // decision and either replace the tool result or prompt the user. Only the
+    // first setup tag in the content list is acted on.
     for (const block of event.content) {
       if (block.type !== "text") continue;
       const parsed = parseToolTag(block.text);
-      if (!parsed || parsed.kind !== "credential_required") continue;
+      if (
+        !parsed ||
+        (parsed.kind !== "credential_required" && parsed.kind !== "external_tool_required")
+      ) {
+        continue;
+      }
+
+      if (parsed.kind === "external_tool_required") {
+        const state = loadOnboardingState();
+        const descriptor = getProvider(parsed.provider);
+        if (state.providers[parsed.provider]?.status === "never_ask") {
+          return {
+            content: [
+              {
+                type: "text",
+                text:
+                  `${buildSkippedTag({
+                    provider: parsed.provider,
+                    reason: "credential_not_provided",
+                    remediation: `run ${parsed.installCmd} and ${parsed.loginCmd ?? "rdt login"} to enable ${descriptor.displayName} (silenced)`,
+                    silenced: true,
+                  })}\n\n` +
+                  `${descriptor.displayName} data was not fetched because you previously asked not to be reminded about this provider.`,
+              },
+            ],
+          };
+        }
+        const setupLabel =
+          parsed.reason === "not_installed"
+            ? `Continue after installing ${descriptor.displayName}`
+            : `Continue after logging in to ${descriptor.displayName}`;
+        const skipLabel = `Skip ${descriptor.displayName} once`;
+        const neverLabel = `Always skip ${descriptor.displayName}`;
+        const installOrLogin =
+          parsed.reason === "not_installed"
+            ? `Install command: ${parsed.installCmd}.`
+            : `Login command: ${parsed.loginCmd ?? "rdt login"}.`;
+        const questionBody =
+          `${descriptor.displayName} requires a local external tool before this data can be fetched. ` +
+          `${installOrLogin} How would you like to proceed?`;
+
+        sessionPromptedSet.add(parsed.provider);
+        const promptResult = await promptUser(
+          ctx,
+          {
+            question: questionBody,
+            questionType: "select",
+            options: [setupLabel, skipLabel, neverLabel],
+          },
+          options?.askUserHandler,
+        );
+
+        const answer = promptResult.cancelled ? skipLabel : (promptResult.answer ?? skipLabel);
+        if (answer.startsWith("Always")) {
+          saveOnboardingState(markProviderNeverAsk(state, parsed.provider));
+        }
+
+        if (answer.startsWith("Continue")) {
+          return {
+            content: [
+              {
+                type: "text",
+                text:
+                  `${buildConnectedTag({ provider: parsed.provider })}\n\n` +
+                  `${descriptor.displayName} setup was acknowledged. Re-run the original ${descriptor.displayName} request now; if setup is still unavailable, continue without ${descriptor.displayName} and disclose the source gap.`,
+              },
+            ],
+          };
+        }
+
+        const silenced = answer.startsWith("Always");
+        const remediation = silenced
+          ? `run ${parsed.installCmd} and ${parsed.loginCmd ?? "rdt login"} to enable ${descriptor.displayName} (silenced)`
+          : `run ${parsed.installCmd} and ${parsed.loginCmd ?? "rdt login"} to enable ${descriptor.displayName}`;
+        return {
+          content: [
+            {
+              type: "text",
+              text: `${buildSkippedTag({
+                provider: parsed.provider,
+                reason: "credential_not_provided",
+                remediation,
+                silenced,
+              })}\n\n${descriptor.displayName} data was omitted per your choice.`,
+            },
+          ],
+        };
+      }
 
       const state = loadOnboardingState();
       const action = resolveCredentialRequired({

package/src/pi/tool-adapter.ts

@@ -4,6 +4,7 @@ import type { TSchema } from "@sinclair/typebox";
 import { getDefaults } from "../memory/tool-defaults.js";
 import { wrapWithDefaults } from "../runtime/tool-defaults-wrapper.js";
 import { getAllTools } from "../tools/index.js";
+import type { AskUserHandler } from "../types/index.js";
 
 export function agentToolToPiTool<TParams extends TSchema, TDetails>(
   tool: AgentTool<TParams, TDetails>,
@@ -14,14 +15,23 @@ export function agentToolToPiTool<TParams extends TSchema, TDetails>(
     description: tool.description,
     promptSnippet: `${tool.name}: ${tool.description}`,
     parameters: tool.parameters,
-    execute: async (toolCallId, params, signal, onUpdate) => {
-      return tool.execute(toolCallId, params, signal, onUpdate);
+    execute: async (toolCallId, params, signal, onUpdate, ctx) => {
+      const executeWithContext = tool.execute as unknown as (
+        id: string,
+        params: unknown,
+        signal: AbortSignal | undefined,
+        onUpdate: unknown,
+        ctx: unknown,
+      ) => ReturnType<typeof tool.execute>;
+      return executeWithContext(toolCallId, params, signal, onUpdate, ctx);
     },
   };
 }
 
-export function getOpenCandleToolDefinitions(): ToolDefinition[] {
-  return getAllTools()
+export function getOpenCandleToolDefinitions(
+  options: { askUserHandler?: AskUserHandler } = {},
+): ToolDefinition[] {
+  return getAllTools(options)
     .map((tool) => ({ tool, defaults: safeGetDefaults(tool.name) }))
     .filter(({ defaults }) => defaults.__enabled !== false)
     .map(({ tool, defaults }) => {

package/src/prompts/context-builder.ts

@@ -251,7 +251,7 @@ const SAFETY_RULES = `## Guidelines
 - For crypto position-sizing prompts, start with a concrete allocation range and dollar amount, then show drawdown impact on the user's portfolio, a sleep test, dollar-cost averaging, rebalancing rules, position caps, tax tracking, reputable custody/exchange considerations, and emergency-fund/high-interest-debt prerequisites. Cite the crypto tool-output date or history period and label sparse or unavailable history instead of implying unsupported precision.
 - For rate-cut market-pricing questions, use get_economic_data for the current Fed funds backdrop and search_web for CME FedWatch / Federal Funds futures probabilities before naming what the market is pricing. Distinguish historical Fed rates from futures-implied expectations.
 - For backtest_strategy results, report strategy return, buy-and-hold return, outperformance, trade count, win rate, and max drawdown. Include risk-adjusted metrics such as Sharpe or Sortino when available; otherwise say they were unavailable. Explain why the strategy worked or failed in the tested regime and discuss trading costs/slippage when the user asks whether the edge is practical. Do not reduce a backtest answer to return-only.
-- For sentiment-only prompts, final answer must include the direction and strength of the sentiment signal, the score scale when available, missing sources, why those missing sources matter for the user's question, the source-coverage risk, low sample counts, and how those gaps downgrade confidence. For ticker-specific sentiment prompts, call get_stock_quote before the final answer and state whether sentiment diverges from price action.
+- For sentiment-only prompts, final answer must 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 those missing sources matter for the user's question, the source-coverage risk, low sample counts, and how those gaps downgrade confidence. For ticker-specific sentiment prompts, call get_stock_quote before the final answer and state whether sentiment diverges from price action; if quote data is unavailable, say price-action divergence could not be evaluated.
 - Commit to specifics when asked for entries, targets, stops, allocations, or position sizes. Refusal is not an acceptable output shape.
 - Each committal response carries FOUR things: the specific number or range, a reasoning chain naming the data points you used, a confidence band, and an invalidation level (what would break the thesis).
 - Conceptual education prompts are not committal responses. Do not append "Analyst View", "Commitment", "Reasoning Chain", "Confidence Band", or "Invalidation Level" sections when the user asked for an explanation, definition, or learning framework rather than a trade, allocation, or recommendation.

package/src/prompts/policy-cards.ts

@@ -68,7 +68,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",

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,317 @@
+import { spawn } from "node:child_process";
+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>>;
+  };
+}
+
+interface CommandResult {
+  readonly code: number | null;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+type RdtCommandRunner = (command: string, args: readonly string[]) => Promise<CommandResult>;
+
+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: CommandResult;
+  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<CommandResult> {
+  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 ${COMMAND_TIMEOUT_MS}ms`));
+    }, 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 });
+    });
+  });
+}