opencandle 0.9.0 → 0.11.0

package/src/pi/tui-session-coordinator.ts

@@ -0,0 +1,351 @@
+import { randomBytes } from "node:crypto";
+import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
+import type { AddressInfo } from "node:net";
+import type { AgentSession, SessionManager } from "@earendil-works/pi-coding-agent";
+import {
+  clearPendingSessionAction,
+  hasAcceptedSessionAction,
+  hasPendingSessionAction,
+  recordAcceptedSessionAction,
+  recordPendingSessionAction,
+} from "./session-action-dedupe.js";
+
+interface TuiSessionCoordinatorOptions {
+  getSession: () => AgentSession;
+  getSessionManager: () => SessionManager;
+  getModelUnavailableMessage: () => string | null;
+  syncWriterLockScope?: () => void;
+  now?: () => number;
+}
+
+export interface TuiSessionCoordinatorServer {
+  endpoint: string;
+  secret: string;
+  close(): Promise<void>;
+}
+
+interface AcceptedAction {
+  expiresAt: number;
+}
+
+const DEDUPE_RETENTION_MS = 10 * 60 * 1000;
+
+export async function startTuiSessionCoordinatorServer(
+  options: TuiSessionCoordinatorOptions,
+): Promise<TuiSessionCoordinatorServer> {
+  const now = options.now ?? Date.now;
+  const secret = randomBytes(32).toString("base64url");
+  const acceptedActions = new Map<string, AcceptedAction>();
+  const activeRunSessions = new Set<string>();
+
+  const server = createServer((req, res) => {
+    void handleRequest(req, res).catch((error) => {
+      const message = error instanceof Error ? error.message : String(error);
+      writeJson(res, { error: message }, 500);
+    });
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      server.off("error", reject);
+      resolve();
+    });
+  });
+
+  const address = server.address() as AddressInfo;
+  const endpoint = `http://127.0.0.1:${address.port}`;
+
+  return {
+    endpoint,
+    secret,
+    close: () =>
+      new Promise<void>((resolve, reject) => {
+        server.close((error) => (error ? reject(error) : resolve()));
+      }),
+  };
+
+  async function handleRequest(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    const url = new URL(req.url ?? "/", endpoint);
+    if (url.pathname !== "/api/local-coordinator/chat-run" || req.method !== "POST") {
+      writeJson(res, { error: "Not found" }, 404);
+      return;
+    }
+
+    if (
+      !isLoopbackAddress(req.socket.remoteAddress) ||
+      req.headers["x-opencandle-coordinator-secret"] !== secret
+    ) {
+      writeJson(res, { error: "Local coordinator request was not authorized." }, 403);
+      return;
+    }
+
+    const body = asRecord(await readJsonBody(req));
+    const prompt = String(body.prompt ?? "").trim();
+    const requestedSessionId = String(body.sessionId ?? "").trim();
+    const actionId = String(body.actionId ?? "").trim() || `legacy-tui-chat-${now()}`;
+    const sessionManager = options.getSessionManager();
+    const sessionId = sessionManager.getSessionId();
+    if (!prompt) {
+      writeJson(res, { error: "prompt is required" }, 400);
+      return;
+    }
+    if (requestedSessionId && requestedSessionId !== sessionId) {
+      writeJson(
+        res,
+        { error: "Session route and request body disagree", code: "session_changed" },
+        409,
+      );
+      return;
+    }
+    try {
+      options.syncWriterLockScope?.();
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      writeJson(res, { error: message, code: "syncing" }, 409);
+      return;
+    }
+
+    pruneExpiredActions();
+    const actionKey = `${sessionId}:${actionId}`;
+    if (acceptedActions.has(actionKey) || hasAcceptedSessionAction(sessionManager, actionId)) {
+      writeJson(res, { ok: true, duplicate: true });
+      return;
+    }
+    if (hasPendingSessionAction(sessionManager, actionId)) {
+      writeJson(
+        res,
+        { error: "OpenCandle is reconnecting to this session.", code: "syncing" },
+        409,
+      );
+      return;
+    }
+    let session: AgentSession;
+    try {
+      session = options.getSession();
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      writeJson(res, { error: message, code: "session_starting" }, 409);
+      return;
+    }
+    if (
+      activeRunSessions.has(sessionId) ||
+      session.isStreaming ||
+      session.pendingMessageCount > 0
+    ) {
+      writeJson(
+        res,
+        {
+          error: "OpenCandle is still working in this session. Try again when it finishes.",
+          code: "session_busy",
+        },
+        409,
+      );
+      return;
+    }
+
+    activeRunSessions.add(sessionId);
+    try {
+      recordPendingSessionAction(sessionManager, actionId);
+      let actionAccepted = false;
+      const recordAcceptedAction = () => {
+        if (actionAccepted) return;
+        recordAcceptedSessionAction(sessionManager, actionId);
+        options.syncWriterLockScope?.();
+        acceptedActions.set(actionKey, { expiresAt: now() + DEDUPE_RETENTION_MS });
+        actionAccepted = true;
+      };
+      let completed: boolean;
+      try {
+        completed = await streamPromptRun(res, prompt, sessionId, recordAcceptedAction);
+      } catch (error) {
+        if (!actionAccepted) clearPendingSessionAction(sessionManager, actionId);
+        throw error;
+      }
+      if (completed) {
+        recordAcceptedAction();
+      } else if (!actionAccepted) {
+        clearPendingSessionAction(sessionManager, actionId);
+      }
+    } finally {
+      activeRunSessions.delete(sessionId);
+    }
+  }
+
+  async function streamPromptRun(
+    res: ServerResponse,
+    prompt: string,
+    sessionId: string,
+    onPromptAdmitted: () => void,
+  ): Promise<boolean> {
+    options.syncWriterLockScope?.();
+    const session = options.getSession();
+    const sessionManager = options.getSessionManager();
+    const beforeEntries = sessionManager.getEntries();
+    const beforeCount = beforeEntries.length;
+    let seq = 1;
+    const runId = `tui-run-${now()}`;
+
+    res.writeHead(200, {
+      "content-type": "text/event-stream; charset=utf-8",
+      "cache-control": "no-cache, no-transform",
+      connection: "keep-alive",
+    });
+    writeSse(res, { type: "run.started", runId, sessionId, seq: seq++ });
+    res.flushHeaders?.();
+
+    try {
+      const modelUnavailableMessage = options.getModelUnavailableMessage();
+      if (!prompt.startsWith("/") && modelUnavailableMessage) {
+        sessionManager.appendMessage({ role: "user", content: prompt, timestamp: now() });
+        onPromptAdmitted();
+        options.syncWriterLockScope?.();
+        sessionManager.appendCustomMessageEntry(
+          "opencandle-model-setup",
+          modelUnavailableMessage,
+          true,
+          {
+            source: "tui",
+          },
+        );
+      } else {
+        const unsubscribe = subscribeToPromptAdmission(session, prompt, onPromptAdmitted);
+        try {
+          await session.prompt(prompt);
+          options.syncWriterLockScope?.();
+          await waitForTurnSettlement(session);
+        } finally {
+          unsubscribe?.();
+        }
+      }
+      const newEntries = sessionManager.getEntries().slice(beforeCount);
+      for (const event of entriesToChatEvents(newEntries, sessionId, seq)) {
+        writeSse(res, event);
+        seq = event.seq + 1;
+      }
+      writeSse(res, { type: "run.completed", runId, sessionId, seq });
+      return true;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      writeSse(res, { type: "run.failed", runId, sessionId, error: { message }, seq });
+      return false;
+    } finally {
+      res.end();
+    }
+  }
+
+  function pruneExpiredActions(): void {
+    const currentTime = now();
+    for (const [actionKey, accepted] of acceptedActions) {
+      if (accepted.expiresAt <= currentTime) acceptedActions.delete(actionKey);
+    }
+  }
+
+  function subscribeToPromptAdmission(
+    session: AgentSession,
+    prompt: string,
+    onPromptAdmitted: () => void,
+  ): (() => void) | undefined {
+    if (prompt.startsWith("/")) return undefined;
+    const maybeSession = session as AgentSession & {
+      subscribe?: (handler: (event: unknown) => void) => () => void;
+    };
+    if (typeof maybeSession.subscribe !== "function") return undefined;
+    return maybeSession.subscribe((event) => {
+      const record = asRecord(event);
+      if (record.type !== "message_start") return;
+      const message = asRecord(record.message);
+      if (message.role !== "user") return;
+      if (messageTextFromContent(message.content).trim() === prompt.trim()) onPromptAdmitted();
+    });
+  }
+}
+
+async function waitForTurnSettlement(session: AgentSession): Promise<void> {
+  const startedAt = Date.now();
+  while (session.isStreaming || session.pendingMessageCount > 0) {
+    if (Date.now() - startedAt > 120_000) {
+      throw new Error("Timed out waiting for session turn to settle");
+    }
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+}
+
+function entriesToChatEvents(
+  entries: unknown[],
+  sessionId: string,
+  startSeq: number,
+): Array<Record<string, unknown> & { seq: number }> {
+  let seq = startSeq;
+  const events: Array<Record<string, unknown> & { seq: number }> = [];
+  for (const entry of entries) {
+    const record = asRecord(entry);
+    const message = asRecord(record.message);
+    const source = Object.keys(message).length > 0 ? message : record;
+    const role =
+      typeof source.role === "string"
+        ? source.role
+        : record.type === "custom_message"
+          ? "assistant"
+          : undefined;
+    const content = normalizeContent(source.content);
+    if (!role || content.length === 0) continue;
+    events.push({
+      type: "message.completed",
+      sessionId,
+      messageId: String(record.id ?? `tui-entry-${seq}`),
+      role,
+      content,
+      seq: seq++,
+    });
+  }
+  return events;
+}
+
+function normalizeContent(content: unknown): Array<Record<string, unknown>> {
+  if (typeof content === "string") return [{ type: "text", text: content }];
+  if (Array.isArray(content)) return content.map(asRecord).filter((item) => item.type);
+  const record = asRecord(content);
+  if (typeof record.text === "string") return [{ type: "text", text: record.text }];
+  return [];
+}
+
+function messageTextFromContent(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .map((part) =>
+      typeof part === "object" && part !== null && "text" in part && typeof part.text === "string"
+        ? part.text
+        : "",
+    )
+    .join("");
+}
+
+function writeJson(res: ServerResponse, value: unknown, status = 200): void {
+  res.writeHead(status, { "content-type": "application/json" });
+  res.end(JSON.stringify(value));
+}
+
+function writeSse(res: ServerResponse, event: unknown): void {
+  res.write(`data: ${JSON.stringify(event)}\n\n`);
+}
+
+async function readJsonBody(req: IncomingMessage): Promise<unknown> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of req) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  if (chunks.length === 0) return {};
+  return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+}
+
+function isLoopbackAddress(address: string | undefined): boolean {
+  return address === "127.0.0.1" || address === "::1" || address === "::ffff:127.0.0.1";
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}

package/src/prompts/context-builder.ts

@@ -291,7 +291,7 @@ const TOOL_CATALOG = `## Available Tools
 - **Sentiment**: get_reddit_sentiment, get_twitter_sentiment, get_web_sentiment, get_sentiment_trend, get_sentiment_summary — retail and news sentiment from Reddit, Twitter/X, and web sources with historical trends and cross-source divergence detection
 - **Web Search**: search_web — breaking news, earnings context, company events, regulatory developments. Supported freshness values are hours, day, week, and month; use category general with freshness month for broad industry context; never pass unsupported values such as all, year, 3mo, quarter, or custom date ranges. When a dedicated tool can answer the question (quotes, fundamentals, earnings, macro, SEC filings, sentiment), use that tool instead — do not add search_web as a supplementary source for data available through dedicated tools
 - **Options**: get_option_chain — full options chain with strikes, bids/asks, volume, OI, IV, and computed Greeks (delta, gamma, theta, vega, rho)
-- **Portfolio**: track_portfolio, analyze_risk, manage_watchlist, analyze_correlation, analyze_holdings_overlap, track_prediction, manage_alerts, daily_watchlist_report, manage_notifications — position tracking, P&L, Sharpe ratio, VaR, watchlist tracking, durable local alerts, daily watchlist reports, notification history, correlation matrix, ETF/fund holdings overlap, and prediction tracking with accuracy scoring
+- **Portfolio**: track_portfolio, analyze_risk, manage_watchlist, analyze_correlation, analyze_holdings_overlap, manage_alerts, daily_watchlist_report, manage_notifications — position tracking, P&L, Sharpe ratio, VaR, watchlist tracking, durable local alerts, daily watchlist reports, notification history, correlation matrix, and ETF/fund holdings overlap
 - **User Interaction**: ask_user — ask the user a clarification question when their request is ambiguous or missing key details`;
 
 function buildToolCatalog(addonDescriptions?: string[]): string {

package/src/prompts/policy-cards.ts

@@ -141,7 +141,7 @@ For strategy backtest prompts, use backtest_strategy evidence before judging whe
     status: "implemented",
     capabilityGapIds: [],
     content: `## Stateful Tracking Update Policy
-For watchlist, portfolio tracking, alert management, daily-report, prediction recording, and prediction-check prompts, use the state tool that owns the change or lookup: manage_watchlist, track_prediction, track_portfolio, manage_alerts, or daily_watchlist_report. Do not confirm a saved change from prose alone. Confirm the persisted state update with the symbol, action, direction, entry price, target, stop, conviction, timeframe, or check result that the tool accepted. If the user asks to create an alert and check it now in the same request, call manage_alerts with the matching create action and check_after_create=true. If required fields for a state mutation are missing, ask the smallest clarification question instead of inventing values. For check or list operations, summarize the saved state and say clearly when no records exist. Do not turn a state update into a buy/sell recommendation unless the user separately asks for market analysis.`,
+For watchlist, portfolio tracking, alert management, and daily-report prompts, use the state tool that owns the change or lookup: manage_watchlist, track_portfolio, manage_alerts, or daily_watchlist_report. Do not confirm a saved change from prose alone. Confirm the persisted state update with the symbol, action, quantity, cost, target, stop, or check result that the tool accepted. If the user asks to create an alert and check it now in the same request, call manage_alerts with the matching create action and check_after_create=true. If required fields for a state mutation are missing, ask the smallest clarification question instead of inventing values. For check or list operations, summarize the saved state and say clearly when no records exist. Do not turn a state update into a buy/sell recommendation unless the user separately asks for market analysis.`,
   },
   retail_finance_tradeoff: {
     id: "retail_finance_tradeoff",

package/src/routing/classify-intent.ts

@@ -136,9 +136,9 @@ const RULES: Rule[] = [
       return hasOptionKeywordsInText(lower) && entities.symbols.length >= 1;
     },
   },
-  // Stateful portfolio/watchlist/alert/prediction mutations must not be
-  // mistaken for compare or portfolio-construction workflows just because a
-  // cost basis, target, or currency token is present.
+  // Stateful portfolio/watchlist/alert mutations must not be mistaken for
+  // compare or portfolio-construction workflows just because a cost basis,
+  // target, or currency token is present.
   {
     workflow: "watchlist_or_tracking",
     confidence: 0.95,
@@ -184,7 +184,6 @@ const RULES: Rule[] = [
       const lower = input.toLowerCase();
       return (
         /\bwatchlist\b/.test(lower) ||
-        /\bprediction/i.test(lower) ||
         /\bshow\s+my\s+portfolio\b/.test(lower) ||
         /\bmy\s+portfolio\b/.test(lower) ||
         /\btrack\b/.test(lower)
@@ -314,7 +313,7 @@ function isStatefulTrackingRequest(input: string): boolean {
       lower,
     );
   const hasStateObject =
-    /\b(?:watchlist|portfolio|holding|holdings|position|positions|prediction|predictions|alert|alerts|daily\s+report|watchlist\s+report|report\s+history)\b/.test(
+    /\b(?:watchlist|portfolio|holding|holdings|position|positions|alert|alerts|daily\s+report|watchlist\s+report|report\s+history)\b/.test(
       lower,
     );
   const hasPortfolioLotShape =

package/src/routing/route-manifest.ts

@@ -29,7 +29,6 @@ export const TOOL_BUNDLE_TOOLS: Record<ToolBundleName, readonly string[]> = {
     "analyze_holdings_overlap",
     "track_portfolio",
     "manage_watchlist",
-    "track_prediction",
     "manage_alerts",
     "daily_watchlist_report",
     "manage_notifications",

package/src/routing/router-prompt.ts

@@ -19,7 +19,7 @@ function renderCatalog(): string {
     compare_assets: "user asks to compare two or more symbols (vs / versus / which is better)",
     single_asset_analysis:
       "user asks for a full analysis / deep dive / 'is X attractive' on ONE symbol",
-    watchlist_or_tracking: "user manages or asks about their saved watchlist / prediction history",
+    watchlist_or_tracking: "user manages or asks about their saved watchlist or tracked positions",
     general_finance_qa:
       "definitional / conceptual questions plus broad market structure, sector, industry, monetary policy, and emerging markets research",
   };

package/src/routing/router.ts

@@ -12,6 +12,7 @@ import {
   legacyRouteForRouteKind,
   routeKindFromLegacyRoute,
   selectToolBundles,
+  workflowRequiredSlots,
 } from "./route-manifest.js";
 import { buildRouterPrompt } from "./router-prompt.js";
 import type {
@@ -127,7 +128,7 @@ export function validateRouterOutput(raw: string): RouterOutput {
   }
 
   const entities = validateEntities(obj.entities);
-  const slots = validateSlots(obj.slots);
+  const slots = canonicalizeSymbolSlots(workflow, validateSlots(obj.slots));
   const preference_updates = validatePreferenceUpdates(obj.preference_updates);
   const missing_required = rawMissingRequired;
   const tool_bundles = validateToolBundles(obj.tool_bundles);
@@ -659,7 +660,7 @@ function isStatefulTrackingRequest(text: string): boolean {
       lower,
     );
   const hasStateObject =
-    /\b(?:watchlist|portfolio|holding|holdings|position|positions|prediction|predictions|alert|alerts|daily\s+report|watchlist\s+report|report\s+history)\b/.test(
+    /\b(?:watchlist|portfolio|holding|holdings|position|positions|alert|alerts|daily\s+report|watchlist\s+report|report\s+history)\b/.test(
       lower,
     );
   const hasPortfolioLotShape =
@@ -816,7 +817,8 @@ function validateSlots(raw: unknown): Record<string, RouterSlot> {
     if (!VALID_CONFIDENCE.has(s.confidence as string)) {
       throw new Error(`slot ${key} has invalid confidence: ${JSON.stringify(s.confidence)}`);
     }
-    out[key] = {
+    const canonicalKey = canonicalSlotKey(key);
+    out[canonicalKey] = {
       value: s.value,
       source: s.source as RouterSlot["source"],
       confidence: s.confidence as RouterSlot["confidence"],
@@ -825,6 +827,40 @@ function validateSlots(raw: unknown): Record<string, RouterSlot> {
   return out;
 }
 
+// The slot contract uses snake_case keys; non-Claude router models sometimes
+// emit camelCase (timeHorizon, riskProfile). Canonicalize deterministically so
+// downstream slot resolution and missing-required checks match.
+function canonicalSlotKey(key: string): string {
+  return key.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase();
+}
+
+// Models also drift between scalar `symbol` and one-element `symbols` slot
+// shapes. Canonicalize toward the workflow's manifest-declared required slot
+// name when the conversion is unambiguous.
+function canonicalizeSymbolSlots(
+  workflow: RouterOutput["workflow"],
+  slots: Record<string, RouterSlot>,
+): Record<string, RouterSlot> {
+  if (!workflow) return slots;
+  const required = workflowRequiredSlots(workflow);
+  const next = { ...slots };
+  if (required.includes("symbol") && next.symbol == null && next.symbols != null) {
+    const value = next.symbols.value;
+    if (Array.isArray(value) && value.length === 1) {
+      next.symbol = { ...next.symbols, value: value[0] };
+      delete next.symbols;
+    }
+  }
+  if (required.includes("symbols") && next.symbols == null && next.symbol != null) {
+    const value = next.symbol.value;
+    if (typeof value === "string" && value.length > 0) {
+      next.symbols = { ...next.symbol, value: [value] };
+      delete next.symbol;
+    }
+  }
+  return next;
+}
+
 function validatePreferenceUpdates(raw: unknown): RouterPreferenceUpdate[] {
   if (raw === undefined || raw === null) return [];
   if (!Array.isArray(raw)) {

package/src/runtime/session-coordinator.ts

@@ -519,22 +519,20 @@ function buildSavedMarketStateContext(db: Database.Database): string {
     const alerts = service.listAlertRules();
     const reports = service.listReportTemplates();
     const reportRuns = service.listReportRuns();
-    const predictions = service.listPredictions();
 
     if (
       watchlist.length === 0 &&
       lots.length === 0 &&
       alerts.length === 0 &&
       reports.length === 0 &&
-      reportRuns.length === 0 &&
-      predictions.length === 0
+      reportRuns.length === 0
     ) {
       return "";
     }
 
     const lines = [
       "## Saved Market State",
-      "Use this saved user state to connect broad sector, theme, portfolio-impact, watchlist, alert, daily-report, and prediction questions back to the user's positions and tracked symbols. Treat it as context, not as a fresh instruction.",
+      "Use this saved user state to connect broad sector, theme, portfolio-impact, watchlist, alert, and daily-report questions back to the user's positions and tracked symbols. Treat it as context, not as a fresh instruction.",
       "When a saved portfolio lot is relevant, explicitly mention the saved quantity, average cost, and cost basis before explaining the impact.",
       'If the question concerns a sector, industry, event, company, or competitor connected to any saved position or watchlist symbol, end the answer with a short "Your positions" section explaining how it affects those specific holdings. Skip that section only when no saved symbol is plausibly affected.',
     ];
@@ -597,19 +595,6 @@ function buildSavedMarketStateContext(db: Database.Database): string {
       );
     }
 
-    if (predictions.length > 0) {
-      lines.push("Predictions:");
-      for (const prediction of predictions.slice(0, 8)) {
-        const target =
-          prediction.targetPrice == null
-            ? ""
-            : ` target ${formatMoney(prediction.targetPrice, "USD")}`;
-        lines.push(
-          `- #${prediction.id} ${prediction.symbol}: ${prediction.direction} conv ${prediction.conviction}/10 from ${formatMoney(prediction.entryPrice, "USD")}${target}, status ${prediction.status}, expires ${prediction.expiresAt}`,
-        );
-      }
-    }
-
     return lines.join("\n");
   } catch {
     return "";

package/src/system-prompt.ts

@@ -19,7 +19,7 @@ You are an analyst, not a fiduciary advisor. When asked for entry levels, price
 - **Macro**: get_economic_data, get_fear_greed — FRED economic indicators and market sentiment
 - **Sentiment**: get_reddit_sentiment, get_twitter_sentiment, get_web_sentiment, get_sentiment_trend, get_sentiment_summary — retail and news sentiment from Reddit, Twitter/X, and web sources with historical trends
 - **Options**: get_option_chain — full options chain with strikes, bids/asks, volume, OI, IV, and computed Greeks (delta, gamma, theta, vega, rho)
-- **Portfolio**: track_portfolio, analyze_risk, manage_watchlist, analyze_correlation, track_prediction, manage_alerts, daily_watchlist_report, manage_notifications — position tracking, P&L, Sharpe ratio, VaR, watchlist tracking, durable local alerts, daily watchlist reports, notification history, correlation matrix, and prediction tracking with accuracy scoring
+- **Portfolio**: track_portfolio, analyze_risk, manage_watchlist, analyze_correlation, manage_alerts, daily_watchlist_report, manage_notifications — position tracking, P&L, Sharpe ratio, VaR, watchlist tracking, durable local alerts, daily watchlist reports, notification history, and correlation matrix
 - **User Interaction**: ask_user — ask clarification questions and setup confirmations
 
 ## Analytical Framework

package/src/tools/AGENTS.md

@@ -10,7 +10,7 @@ src/tools/
 ├── options/       # Options chains, Greeks computation
 ├── macro/         # FRED economic data, fear & greed index
 ├── sentiment/     # Reddit sentiment, news sentiment
-├── portfolio/     # Tracker, risk analysis, watchlist, correlation, predictions
+├── portfolio/     # Tracker, risk analysis, watchlist, correlation
 ├── market/        # Stock quotes, history, crypto, ticker search
 └── index.ts       # getAllTools() registry — add new tools here
 ```

package/src/tools/fundamentals/dcf.ts

@@ -45,6 +45,14 @@ export function computeDCF(params: DCFParams): DCFResult {
     sharesOutstanding,
   } = params;
 
+  // Gordon Growth requires discount > terminal growth; a non-positive spread
+  // divides by zero or flips the terminal value's sign.
+  if (discountRate <= terminalGrowth) {
+    throw new Error(
+      `Gordon Growth constraint violated: terminal growth (${(terminalGrowth * 100).toFixed(1)}%) must be below the discount rate (${(discountRate * 100).toFixed(1)}%).`,
+    );
+  }
+
   // Project future cash flows (mid-year convention: discount at year-0.5)
   const projectedCashFlows: Array<{ year: number; fcf: number; presentValue: number }> = [];
   for (let y = 1; y <= years; y++) {
@@ -152,12 +160,11 @@ function computeDCFSimple(
   return (sumPV + pvTV - debt) / shares;
 }
 
-export function computeNetDebt(f: FinancialStatement): number {
+export function computeNetDebt(f: FinancialStatement): number | null {
   if (f.totalDebt != null && f.cashAndEquivalents != null) {
     return f.totalDebt - f.cashAndEquivalents;
   }
-  // Fallback: totalLiabilities - totalAssets (negative means net cash position)
-  return f.totalLiabilities - f.totalAssets;
+  return null;
 }
 
 const params = Type.Object({
@@ -243,10 +250,45 @@ export const dcfTool: AgentTool<typeof params> = {
 
       const discountRate = args.discount_rate ?? 0.1;
       const terminalGrowth = args.terminal_growth ?? 0.03;
+      if (discountRate <= terminalGrowth) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `⚠ Invalid DCF assumptions for ${symbol}: terminal growth (${(terminalGrowth * 100).toFixed(1)}%) must be below the discount rate (${(discountRate * 100).toFixed(1)}%) for the Gordon Growth terminal value to be meaningful. Lower terminal_growth or raise discount_rate.`,
+            },
+          ],
+          details: null,
+        };
+      }
+
       const years = args.projection_years ?? 5;
-      const marketCap = overview?.marketCap ?? 0;
-      const sharesOutstanding = quote.price > 0 && marketCap > 0 ? marketCap / quote.price : 1;
-      const netDebt = financials[0] ? computeNetDebt(financials[0]) : 0;
+      // Prefer the overview market cap; fall back to the quote's market cap.
+      // Never substitute a placeholder share count — a fabricated
+      // per-share value is worse than an honest refusal.
+      const marketCap =
+        overview?.marketCap && overview.marketCap > 0
+          ? overview.marketCap
+          : quote.marketCap > 0
+            ? quote.marketCap
+            : 0;
+      if (quote.price <= 0 || marketCap <= 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `⚠ Cannot compute a per-share DCF for ${symbol}: shares outstanding cannot be derived because ${quote.price <= 0 ? "the current quote price is unavailable" : "market capitalization is unavailable from the overview and quote providers"}. Per-share intrinsic value requires a real share count.`,
+            },
+          ],
+          details: null,
+        };
+      }
+      const sharesOutstanding = marketCap / quote.price;
+      // Signed on purpose: net cash (negative net debt) adds to equity value.
+      // Omit the adjustment if debt/cash fields are missing; assets minus
+      // liabilities is book equity, not a net-cash proxy.
+      const computedNetDebt = financials[0] ? computeNetDebt(financials[0]) : null;
+      const netDebt = computedNetDebt ?? 0;
 
       const result = computeDCF({
         freeCashFlow: latestFCF,
@@ -254,9 +296,14 @@ export const dcfTool: AgentTool<typeof params> = {
         discountRate,
         terminalGrowth,
         years,
-        netDebt: Math.max(0, netDebt),
+        netDebt,
         sharesOutstanding,
       });
+      if (computedNetDebt == null) {
+        result.warnings.push(
+          "Net debt adjustment omitted because total debt and cash equivalents were unavailable.",
+        );
+      }
 
       const marginOfSafety = (result.intrinsicValue - quote.price) / result.intrinsicValue;
       const upside = (result.intrinsicValue - quote.price) / quote.price;
@@ -286,6 +333,9 @@ export const dcfTool: AgentTool<typeof params> = {
         ``,
         `**Sensitivity Table** (Intrinsic Value at different Growth/Discount rates)`,
         ...formatSensitivityTable(result.sensitivityTable),
+        ...(result.warnings.length > 0
+          ? ["", "**Warnings**", ...result.warnings.map((warning) => `- ${warning}`)]
+          : []),
       ];
 
       return {