opencandle 0.4.0 → 0.6.0

package/src/routing/route-manifest.ts

@@ -0,0 +1,309 @@
+import type { MemoryCategory } from "../memory/types.js";
+import type { RouterOutput, RouterRoute, RouterRouteKind, ToolBundleName } from "./router-types.js";
+import type { ExtractedEntities, WorkflowType } from "./types.js";
+
+export const ROUTE_KINDS: readonly RouterRouteKind[] = [
+  "workflow_dispatch",
+  "agent_task",
+  "clarification",
+  "pass_through",
+];
+
+export const TOOL_BUNDLE_TOOLS: Record<ToolBundleName, readonly string[]> = {
+  core_market: [
+    "search_ticker",
+    "get_stock_quote",
+    "get_stock_history",
+    "screen_stocks",
+    "get_crypto_price",
+    "get_crypto_history",
+    "get_company_overview",
+    "get_financials",
+    "get_earnings",
+    "compare_companies",
+    "compute_dcf",
+    "get_technical_indicators",
+    "backtest_strategy",
+    "analyze_risk",
+    "analyze_correlation",
+    "analyze_holdings_overlap",
+    "track_portfolio",
+    "manage_watchlist",
+    "track_prediction",
+    "manage_alerts",
+    "daily_watchlist_report",
+    "manage_notifications",
+    "search_web",
+  ],
+  options: ["get_option_chain", "get_stock_quote", "search_ticker", "search_web"],
+  macro: ["get_economic_data", "get_fear_greed", "search_web"],
+  sentiment: [
+    "get_reddit_sentiment",
+    "get_twitter_sentiment",
+    "get_web_sentiment",
+    "get_sentiment_trend",
+    "get_sentiment_summary",
+    "get_fear_greed",
+    "search_web",
+  ],
+  sec: ["get_sec_filings", "get_company_overview", "search_web"],
+  clarification: ["ask_user"],
+};
+
+export type PromptPlaybookId =
+  | "workflow_dispatch"
+  | "agent_task"
+  | "clarification"
+  | "pass_through";
+
+interface RouteCapability {
+  routeKind: RouterRouteKind;
+  legacyRoute: RouterRoute;
+  promptPlaybook: PromptPlaybookId;
+  toolBundles: ToolBundleName[];
+  memoryScopes: MemoryCategory[];
+  allowWorkflow: boolean;
+}
+
+interface WorkflowCapability {
+  workflow: Exclude<WorkflowType, "unclassified">;
+  dispatchable: boolean;
+  requiredSlots: string[];
+  toolBundles: ToolBundleName[];
+  memoryScopes: MemoryCategory[];
+  promptPlaybook: PromptPlaybookId;
+}
+
+export const ROUTE_CAPABILITY_MANIFEST: Record<RouterRouteKind, RouteCapability> = {
+  workflow_dispatch: {
+    routeKind: "workflow_dispatch",
+    legacyRoute: "workflow",
+    promptPlaybook: "workflow_dispatch",
+    toolBundles: ["core_market"],
+    memoryScopes: ["investor_profile", "workflow_history"],
+    allowWorkflow: true,
+  },
+  agent_task: {
+    routeKind: "agent_task",
+    legacyRoute: "fallback",
+    promptPlaybook: "agent_task",
+    toolBundles: ["core_market"],
+    memoryScopes: ["investor_profile", "workflow_history"],
+    allowWorkflow: false,
+  },
+  clarification: {
+    routeKind: "clarification",
+    legacyRoute: "fallback",
+    promptPlaybook: "clarification",
+    toolBundles: ["clarification"],
+    memoryScopes: ["investor_profile", "workflow_history"],
+    allowWorkflow: true,
+  },
+  pass_through: {
+    routeKind: "pass_through",
+    legacyRoute: "fallback",
+    promptPlaybook: "pass_through",
+    toolBundles: [],
+    memoryScopes: [],
+    allowWorkflow: false,
+  },
+};
+
+export const WORKFLOW_CAPABILITY_MANIFEST: Record<
+  Exclude<WorkflowType, "unclassified">,
+  WorkflowCapability
+> = {
+  portfolio_builder: {
+    workflow: "portfolio_builder",
+    dispatchable: true,
+    requiredSlots: ["budget"],
+    toolBundles: ["core_market", "macro", "sentiment", "clarification"],
+    memoryScopes: ["investor_profile", "interaction_feedback", "workflow_history"],
+    promptPlaybook: "workflow_dispatch",
+  },
+  options_screener: {
+    workflow: "options_screener",
+    dispatchable: true,
+    requiredSlots: ["symbol"],
+    toolBundles: ["core_market", "options", "sentiment", "clarification"],
+    memoryScopes: ["investor_profile", "interaction_feedback", "workflow_history"],
+    promptPlaybook: "workflow_dispatch",
+  },
+  compare_assets: {
+    workflow: "compare_assets",
+    dispatchable: true,
+    requiredSlots: ["symbols"],
+    toolBundles: ["core_market", "macro", "sentiment", "clarification"],
+    memoryScopes: ["investor_profile", "workflow_history"],
+    promptPlaybook: "workflow_dispatch",
+  },
+  single_asset_analysis: {
+    workflow: "single_asset_analysis",
+    dispatchable: false,
+    requiredSlots: ["symbol"],
+    toolBundles: ["core_market", "options", "sentiment", "sec", "clarification"],
+    memoryScopes: ["investor_profile", "workflow_history"],
+    promptPlaybook: "agent_task",
+  },
+  watchlist_or_tracking: {
+    workflow: "watchlist_or_tracking",
+    dispatchable: false,
+    requiredSlots: [],
+    toolBundles: ["core_market", "clarification"],
+    memoryScopes: ["investor_profile", "workflow_history"],
+    promptPlaybook: "agent_task",
+  },
+  general_finance_qa: {
+    workflow: "general_finance_qa",
+    dispatchable: false,
+    requiredSlots: [],
+    toolBundles: ["core_market", "macro", "sentiment", "sec", "clarification"],
+    memoryScopes: ["investor_profile", "workflow_history"],
+    promptPlaybook: "agent_task",
+  },
+};
+
+export function isRouteKind(value: string): value is RouterRouteKind {
+  return ROUTE_KINDS.includes(value as RouterRouteKind);
+}
+
+export function isToolBundleName(value: string): value is ToolBundleName {
+  return Object.hasOwn(TOOL_BUNDLE_TOOLS, value);
+}
+
+export function legacyRouteForRouteKind(routeKind: RouterRouteKind): RouterRoute {
+  return ROUTE_CAPABILITY_MANIFEST[routeKind].legacyRoute;
+}
+
+export function isDispatchableWorkflow(
+  workflow: Exclude<WorkflowType, "unclassified"> | undefined,
+): boolean {
+  if (!workflow) return false;
+  return WORKFLOW_CAPABILITY_MANIFEST[workflow]?.dispatchable === true;
+}
+
+export function routeKindFromLegacyRoute(
+  route: RouterRoute,
+  missingRequired: readonly string[] = [],
+): RouterRouteKind {
+  if (missingRequired.length > 0) return "clarification";
+  return route === "workflow" ? "workflow_dispatch" : "agent_task";
+}
+
+export function workflowRequiredSlots(
+  workflow: Exclude<WorkflowType, "unclassified"> | undefined,
+): string[] {
+  if (!workflow) return [];
+  return WORKFLOW_CAPABILITY_MANIFEST[workflow]?.requiredSlots ?? [];
+}
+
+export function computeMissingRequiredSlots(
+  workflow: Exclude<WorkflowType, "unclassified"> | undefined,
+  entities: ExtractedEntities,
+  slots: RouterOutput["slots"] = {},
+  existingMissing: readonly string[] = [],
+): string[] {
+  const missing = new Set<string>();
+  const existing = new Set(existingMissing);
+  for (const slot of workflowRequiredSlots(workflow)) {
+    if (slot === "budget" && entities.budget === undefined && !slotHasValue(slots.budget)) {
+      missing.add("budget");
+    }
+    if (slot === "symbol" && entities.symbols.length === 0 && !slotHasValue(slots.symbol)) {
+      missing.add("symbol");
+    }
+    if (
+      slot === "symbols" &&
+      entities.symbols.length < 2 &&
+      !slotHasSymbolListValue(slots.symbols, 2)
+    ) {
+      missing.add("symbols");
+    }
+    existing.delete(slot);
+  }
+  for (const slot of existing) {
+    if (!slotHasValue(slots[slot])) missing.add(slot);
+  }
+  return Array.from(missing);
+}
+
+function slotHasValue(slot: RouterOutput["slots"][string] | undefined): boolean {
+  if (!slot) return false;
+  if (Array.isArray(slot.value)) return slot.value.length > 0;
+  return slot.value !== undefined && slot.value !== null && slot.value !== "";
+}
+
+function slotHasSymbolListValue(
+  slot: RouterOutput["slots"][string] | undefined,
+  minLength: number,
+): boolean {
+  if (!slot) return false;
+  if (Array.isArray(slot.value))
+    return slot.value.filter((value) => typeof value === "string").length >= minLength;
+  return false;
+}
+
+export function selectToolBundles(
+  output: Pick<RouterOutput, "routeKind" | "workflow" | "entities">,
+): ToolBundleName[] {
+  if (output.routeKind === "pass_through") return [];
+  if (output.routeKind === "clarification") return ["clarification"];
+
+  const bundles = new Set<ToolBundleName>();
+  const routeBundles = ROUTE_CAPABILITY_MANIFEST[output.routeKind]?.toolBundles ?? [];
+  for (const bundle of routeBundles) {
+    bundles.add(bundle);
+  }
+
+  if (output.workflow) {
+    const workflow = WORKFLOW_CAPABILITY_MANIFEST[output.workflow];
+    if (workflow) {
+      for (const bundle of workflow.toolBundles) {
+        bundles.add(bundle);
+      }
+    }
+  }
+
+  const metrics = output.entities.compareMetrics ?? [];
+  const horizon = output.entities.timeHorizon ?? "";
+  if (
+    metrics.includes("macro_hedge") ||
+    metrics.includes("interest_rates") ||
+    /\b(?:macro|rate|inflation)\b/i.test(horizon)
+  ) {
+    bundles.add("macro");
+  }
+
+  if (output.entities.symbols.length > 0) {
+    bundles.add("core_market");
+  }
+  if (output.entities.optionStrategy) {
+    bundles.add("options");
+  }
+
+  return Array.from(bundles);
+}
+
+export function activeToolsForBundles(
+  bundles: readonly ToolBundleName[],
+  availableToolNames?: readonly string[],
+): string[] {
+  const selected = new Set<string>();
+  for (const bundle of bundles) {
+    for (const tool of TOOL_BUNDLE_TOOLS[bundle] ?? []) {
+      selected.add(tool);
+    }
+  }
+
+  if (!availableToolNames) return Array.from(selected);
+  const available = new Set(availableToolNames);
+  return Array.from(selected).filter((tool) => available.has(tool));
+}
+
+export function memoryScopesForRoute(
+  routeKind: RouterRouteKind,
+  workflow?: Exclude<WorkflowType, "unclassified">,
+): MemoryCategory[] {
+  if (workflow) return WORKFLOW_CAPABILITY_MANIFEST[workflow]?.memoryScopes ?? [];
+  return ROUTE_CAPABILITY_MANIFEST[routeKind]?.memoryScopes ?? [];
+}

package/src/routing/router-llm-client.ts

@@ -9,7 +9,9 @@ import type { RouterLlmClient } from "./router-types.js";
  * Zero tools are passed — the router operates on text alone. Temperature
  * is pinned low for structured-output stability.
  */
-export function createPiAiRouterClient(model: Model<"anthropic-messages"> | Model<any>): RouterLlmClient {
+export function createPiAiRouterClient(
+  model: Model<"anthropic-messages"> | Model<any>,
+): RouterLlmClient {
   return {
     async complete(prompt: string): Promise<string> {
       const response = await completeSimple(
@@ -33,9 +35,7 @@ export function createPiAiRouterClient(model: Model<"anthropic-messages"> | Mode
       );
 
       if (response.stopReason === "error" || response.stopReason === "aborted") {
-        throw new Error(
-          `router LLM call failed: ${response.errorMessage ?? response.stopReason}`,
-        );
+        throw new Error(`router LLM call failed: ${response.errorMessage ?? response.stopReason}`);
       }
 
       const text = response.content

package/src/routing/router-prompt.ts

@@ -1,3 +1,4 @@
+import { ROUTE_CAPABILITY_MANIFEST, WORKFLOW_CAPABILITY_MANIFEST } from "./route-manifest.js";
 import type { RouterInputContext } from "./router-types.js";
 
 /**
@@ -11,48 +12,32 @@ import type { RouterInputContext } from "./router-types.js";
  * `openspec/changes/router-context-and-observability/` for the follow-up.
  */
 
-/**
- * List of workflows the router may emit. Keep this in sync with
- * `WorkflowType` in `src/routing/types.ts` minus the `unclassified` sentinel.
- */
-const WORKFLOW_CATALOG = [
-  {
-    name: "portfolio_builder",
-    when: "user asks to build/allocate a portfolio, invest a budget across positions",
-    required: ["budget"],
-  },
-  {
-    name: "options_screener",
-    when: "user asks for options trades / calls / puts on a specific ticker",
-    required: ["symbol"],
-  },
-  {
-    name: "compare_assets",
-    when: "user asks to compare two or more symbols (vs / versus / which is better)",
-    required: ["symbols (>=2)"],
-  },
-  {
-    name: "single_asset_analysis",
-    when: "user asks for a full analysis / deep dive / 'is X attractive' on ONE symbol",
-    required: ["symbol"],
-  },
-  {
-    name: "watchlist_or_tracking",
-    when: "user manages or asks about their saved watchlist / prediction history",
-    required: [],
-  },
-  {
-    name: "general_finance_qa",
-    when: "definitional / conceptual 'what is X', 'explain Y' questions",
-    required: [],
-  },
-];
-
 function renderCatalog(): string {
-  return WORKFLOW_CATALOG.map(
-    (w) =>
-      `- "${w.name}": ${w.when}${w.required.length > 0 ? ` [required: ${w.required.join(", ")}]` : ""}`,
-  ).join("\n");
+  const descriptions: Record<string, string> = {
+    portfolio_builder: "user asks to build/allocate a portfolio, invest a budget across positions",
+    options_screener: "user asks for options trades / calls / puts on a specific ticker",
+    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",
+    general_finance_qa:
+      "definitional / conceptual questions plus broad market structure, sector, industry, monetary policy, and emerging markets research",
+  };
+
+  return Object.values(WORKFLOW_CAPABILITY_MANIFEST)
+    .map((w) => {
+      const required =
+        w.requiredSlots.length > 0 ? ` [required: ${w.requiredSlots.join(", ")}]` : "";
+      const mode = w.dispatchable ? "dispatchable workflow" : "agent-task workflow label";
+      return `- "${w.workflow}" (${mode}): ${descriptions[w.workflow]}${required}`;
+    })
+    .join("\n");
+}
+
+function renderRouteKinds(): string {
+  return Object.values(ROUTE_CAPABILITY_MANIFEST)
+    .map((route) => `- "${route.routeKind}" -> legacy route "${route.legacyRoute}"`)
+    .join("\n");
 }
 
 function renderProfile(profile: Record<string, unknown>): string {
@@ -61,13 +46,9 @@ function renderProfile(profile: Record<string, unknown>): string {
   return entries.map(([k, v]) => `- ${k}: ${JSON.stringify(v)}`).join("\n");
 }
 
-function renderPriorTurns(
-  turns: Array<{ role: "user" | "assistant"; text: string }>,
-): string {
+function renderPriorTurns(turns: Array<{ role: "user" | "assistant"; text: string }>): string {
   if (turns.length === 0) return "(none)";
-  return turns
-    .map((t) => `[${t.role}] ${t.text.replace(/\n+/g, " ").slice(0, 400)}`)
-    .join("\n");
+  return turns.map((t) => `[${t.role}] ${t.text.replace(/\n+/g, " ").slice(0, 400)}`).join("\n");
 }
 
 function renderRecentRuns(
@@ -90,6 +71,7 @@ function renderRecentRuns(
 const SCHEMA_SPEC = `You MUST respond with a SINGLE JSON object and nothing else (no markdown fences, no prose outside the JSON). The object MUST conform to this TypeScript interface exactly:
 
 interface RouterOutput {
+  routeKind: "workflow_dispatch" | "agent_task" | "clarification" | "pass_through";
   route: "workflow" | "fallback";
   workflow?: "portfolio_builder" | "options_screener" | "compare_assets" | "single_asset_analysis" | "watchlist_or_tracking" | "general_finance_qa";
   entities: {
@@ -100,10 +82,16 @@ interface RouterOutput {
     riskProfile?: string;            // "conservative" | "balanced" | "aggressive"
     direction?: "bullish" | "bearish";
     dteHint?: string;
+    optionStrategy?: "covered_call" | "protective_put";  // set when user explicitly asks for a known option strategy
+    heldSymbol?: string;              // for covered calls/protective puts: ticker the user owns/holds
+    catalystSymbols?: string[];        // tickers mentioned as event/catalyst context, not the option-chain underlying
+    costBasis?: number;                // per-share basis when user says "cost basis is $X"
+    shareQuantity?: number;            // number of shares owned when stated, e.g. "200 shares"
+    compareMetrics?: string[];        // optional compare focus tags, e.g. "sentiment", "macro_hedge"
   };
   slots: Record<string, {
     value: unknown;
-    source: "user" | "preference" | "default"; // user = stated this turn; preference = from profileSnapshot; default = workflow fallback
+    source: "user" | "preference" | "default" | "prior_context" | "memory";
     confidence: "high" | "medium" | "low";
   }>;
   preference_updates: Array<{
@@ -113,18 +101,27 @@ interface RouterOutput {
     source: "inferred";
   }>;
   missing_required: string[];         // required slot names the turn/profile/defaults did not fill
+  tool_bundles: Array<"core_market" | "options" | "macro" | "sentiment" | "sec" | "clarification">;
+  diagnostics: Array<{ code: string; message: string }>;
   reasoning: string;                  // one or two short sentences; used for debugging only
 }`;
 
 const ROUTING_RULES = `Routing rules:
-- Choose route = "workflow" ONLY when the turn clearly matches one of the workflows below AND required slots are filled (from the turn OR the profile snapshot).
-- Choose route = "fallback" for anything else — including simple data fetches like "AAPL quote", open-ended questions like "entry levels on ASTS for 6 months", or cases where required slots are missing.
-- DO NOT invent a "direct_tool" or "needs_clarification" route. Only "workflow" or "fallback" are valid.
-- If required slots are missing (e.g. options workflow needs a symbol, portfolio needs a budget), still pick the closest route but list the missing slot names in missing_required. The main agent will use ask_user to collect them.
+- Choose routeKind = "workflow_dispatch" ONLY when the turn clearly matches a dispatchable workflow (portfolio_builder, options_screener, or compare_assets) AND required slots are filled from the turn, trusted prior context, or profile snapshot.
+- For single_asset_analysis, watchlist_or_tracking, and general_finance_qa, set routeKind = "agent_task" even when you set the workflow label. These are workflow labels for prompt/tool policy, not structured workflow dispatch.
+- Choose routeKind = "agent_task" for in-scope finance work that should be answered by the main agent, including simple data fetches like "AAPL quote" and open-ended questions like "entry levels on ASTS for 6 months".
+- Choose routeKind = "clarification" when required slots are missing (e.g. options workflow needs a symbol, portfolio needs a budget). List specific slot names in missing_required. The main agent will use ask_user to collect them.
+- Choose routeKind = "pass_through" when the request is outside OpenCandle's finance task surface.
+- Set legacy route = "workflow" only for routeKind = "workflow_dispatch"; otherwise set legacy route = "fallback".
+- DO NOT invent a "direct_tool" route. Tool execution belongs to the main agent.
+- For covered call prompts, distinguish the owned underlying from catalyst tickers. Put the owned symbol first in symbols, set heldSymbol to the owned symbol, put event/context tickers in catalystSymbols, set workflow="options_screener", and preserve costBasis if stated.
+- For protective put prompts, treat the owned/held ticker as the option-chain underlying, set optionStrategy="protective_put", direction="bearish", and preserve shareQuantity if stated. This is a hedge on an existing long share position, not a bullish call screen.
 - Source attribution rules (per-slot source field):
   - source = "user": the value came from THIS turn's text.
   - source = "preference": the value came from profileSnapshot (not this turn).
   - source = "default": a sensible default was applied (workflow fallback).
+  - source = "prior_context": the value came from prior conversation turns.
+  - source = "memory": the value came from retrieved non-profile memory.
 - Preference updates:
   - Emit preference_updates ONLY for stable user-dispositions stated (or very strongly implied) in the current turn. E.g. "I'm aggressive" → risk_profile=aggressive, high.
   - Do NOT emit preference_updates that merely echo profileSnapshot.
@@ -134,6 +131,9 @@ const ROUTING_RULES = `Routing rules:
 export function buildRouterPrompt(input: RouterInputContext): string {
   return `You are OpenCandle's routing agent. Your job is to classify the user's turn into one of the known workflows (or fallback), extract entities + per-slot provenance, and surface any stable preferences the user expressed. Your output feeds the main analyst agent — it does NOT go to the user.
 
+ROUTE KINDS:
+${renderRouteKinds()}
+
 WORKFLOW CATALOG:
 ${renderCatalog()}
 

package/src/routing/router-types.ts

@@ -1,6 +1,15 @@
 import type { ExtractedEntities, SlotSource, WorkflowType } from "./types.js";
 
 export type RouterRoute = "workflow" | "fallback";
+export type RouterRouteKind = "workflow_dispatch" | "agent_task" | "clarification" | "pass_through";
+
+export type ToolBundleName =
+  | "core_market"
+  | "options"
+  | "macro"
+  | "sentiment"
+  | "sec"
+  | "clarification";
 
 export type RouterConfidence = "high" | "medium" | "low";
 
@@ -17,6 +26,12 @@ export interface RouterPreferenceUpdate {
   source: "inferred";
 }
 
+export interface RouterDiagnostic {
+  code: string;
+  message: string;
+  details?: Record<string, unknown>;
+}
+
 /**
  * Structured output from the LLM router. Mirrors existing types
  * (`ClassificationResult`, `ExtractedEntities`, `SlotSource`) so downstream
@@ -26,12 +41,15 @@ export interface RouterPreferenceUpdate {
  * routes, `workflow_type` at the storage layer is the sentinel `"fallback"`.
  */
 export interface RouterOutput {
+  routeKind: RouterRouteKind;
   route: RouterRoute;
   workflow?: Exclude<WorkflowType, "unclassified">;
   entities: ExtractedEntities;
   slots: Record<string, RouterSlot>;
   preference_updates: RouterPreferenceUpdate[];
   missing_required: string[];
+  tool_bundles: ToolBundleName[];
+  diagnostics: RouterDiagnostic[];
   reasoning: string;
 }