opencandle 0.11.0 → 0.12.0

package/README.md

@@ -1,13 +1,15 @@
 # OpenCandle
 
+OpenCandle is an open source financial investigator: a terminal agent and local browser workbench for market research that starts from real provider data, shows source gaps, and keeps risk visible.
+
+Requires Node.js 22.19+ or 24–26. macOS and Linux are fully supported; Windows is best-effort (WSL recommended).
+
 ```bash
 npx opencandle
 # or
 npx opencandle gui
 ```
 
-OpenCandle is an open source financial investigator: a terminal agent and local browser workbench for market research that starts from real provider data, shows source gaps, and keeps risk visible.
-
 [![CI](https://github.com/Kahtaf/OpenCandle/actions/workflows/ci.yml/badge.svg)](https://github.com/Kahtaf/OpenCandle/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/opencandle)](https://www.npmjs.com/package/opencandle)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/Kahtaf/OpenCandle/blob/main/LICENSE)
@@ -18,15 +20,15 @@ OpenCandle is an open source financial investigator: a terminal agent and local
 
 ### Terminal UI
 
-[![OpenCandle terminal UI demo](https://cdn.jsdelivr.net/gh/Kahtaf/OpenCandle@main/assets/opencandle-tui-poster.png)](https://cdn.jsdelivr.net/gh/Kahtaf/OpenCandle@main/assets/opencandle-tui.mp4)
+[![OpenCandle terminal UI demo](https://cdn.jsdelivr.net/gh/Kahtaf/OpenCandle@v0.11.1/assets/opencandle-tui-poster.png)](https://cdn.jsdelivr.net/gh/Kahtaf/OpenCandle@v0.11.1/assets/opencandle-tui.mp4)
 
-[Watch the terminal UI demo](https://cdn.jsdelivr.net/gh/Kahtaf/OpenCandle@main/assets/opencandle-tui.mp4) | [Download MP4](https://github.com/Kahtaf/OpenCandle/raw/refs/heads/main/assets/opencandle-tui.mp4)
+[Watch the terminal UI demo](https://cdn.jsdelivr.net/gh/Kahtaf/OpenCandle@v0.11.1/assets/opencandle-tui.mp4) | [Download MP4](https://github.com/Kahtaf/OpenCandle/raw/refs/heads/main/assets/opencandle-tui.mp4)
 
 ### Local GUI
 
-[![OpenCandle local GUI demo](https://cdn.jsdelivr.net/gh/Kahtaf/OpenCandle@main/assets/opencandle-gui-poster.png)](https://cdn.jsdelivr.net/gh/Kahtaf/OpenCandle@main/assets/opencandle-gui.mp4)
+[![OpenCandle local GUI demo](https://cdn.jsdelivr.net/gh/Kahtaf/OpenCandle@v0.11.1/assets/opencandle-gui-poster.png)](https://cdn.jsdelivr.net/gh/Kahtaf/OpenCandle@v0.11.1/assets/opencandle-gui.mp4)
 
-[Watch the local GUI demo](https://cdn.jsdelivr.net/gh/Kahtaf/OpenCandle@main/assets/opencandle-gui.mp4) | [Download MP4](https://github.com/Kahtaf/OpenCandle/raw/refs/heads/main/assets/opencandle-gui.mp4)
+[Watch the local GUI demo](https://cdn.jsdelivr.net/gh/Kahtaf/OpenCandle@v0.11.1/assets/opencandle-gui.mp4) | [Download MP4](https://github.com/Kahtaf/OpenCandle/raw/refs/heads/main/assets/opencandle-gui.mp4)
 
 ## Why OpenCandle
 
@@ -46,24 +48,18 @@ OpenCandle is read-only research software. It does not place trades, route order
 
 | Capability | What it gives you |
 | --- | --- |
-| Terminal agent | Fast keyboard-driven research inside Pi's local TUI, with sessions, slash commands, model setup, and saved transcripts. |
+| Terminal agent | Fast keyboard-driven research inside the bundled [Pi](https://github.com/earendil-works/pi) local TUI, with sessions, slash commands, model setup, and saved transcripts. Pi is the bundled agent runtime; no separate Pi install is needed. |
 | Local browser GUI | Chat, session history, provider setup, tool discovery, workflow launches, and richer financial result cards at `http://127.0.0.1:14567`. |
 | Evidence-first answers | Tools fetch and format data; the model synthesizes only after evidence is gathered. |
 | Finance routing | Quote lookup, comparison, portfolio review, options strategy, filing checks, macro questions, sentiment reads, and educational prompts route differently. |
 | Provider transparency | Missing keys, degraded sources, stale cache, and unavailable data are surfaced instead of hidden. |
-| Local state | OpenCandle user state lives under `~/.opencandle/` unless `OPENCANDLE_HOME` is set; durable market state is stored in SQLite at `state.db`. |
+| Local state | OpenCandle user state lives under `~/.opencandle/` unless `OPENCANDLE_HOME` is set; durable market state is stored in SQLite at `~/.opencandle/state.db` (or `$OPENCANDLE_HOME/state.db`). |
 | Extensible tools | TypeScript tool APIs, provider boundaries, workflow builders, and package exports for add-on tools. |
 | Eval harness | Unit tests, live provider checks, CLI e2e, GUI browser smoke tests, and competitive finance evals. |
 
 ## Quick Start
 
-Requires Node.js `>=22.19.0 <27`.
-
-```bash
-npx opencandle
-```
-
-On first run, OpenCandle walks you through model setup. In the terminal, you can use Pi sign-in when available or provide a model API key. In the GUI, use the API-key setup panel or complete terminal `/setup` first and refresh the browser. Data-provider keys are separate and optional.
+On first run, OpenCandle walks you through model setup. [Pi](https://github.com/earendil-works/pi) is the bundled agent runtime that handles model setup, the terminal shell, and saved sessions; no separate Pi install is needed. In the terminal, you can use Pi sign-in when available or provide a model API key. In the GUI, use the API-key setup panel or complete terminal `/setup` first and refresh the browser. Data-provider keys are separate and optional.
 
 Start the GUI instead:
 
@@ -100,11 +96,11 @@ Useful slash commands:
 Health diagnostics run from your shell:
 
 ```bash
-opencandle doctor
-opencandle doctor --json
-opencandle doctor --sessions
-opencandle doctor --full
-opencandle doctor --enable twitter
+npx opencandle doctor
+npx opencandle doctor --json
+npx opencandle doctor --sessions
+npx opencandle doctor --full
+npx opencandle doctor --enable twitter
 ```
 
 The GUI also has a Diagnostics page at `/diagnostics` with the same health report, provider setup links, model setup actions, and an explicit browser-session check for Reddit and Twitter/X.
@@ -113,16 +109,16 @@ The GUI also has a Diagnostics page at `/diagnostics` with the same health repor
 
 | Area | Examples | Source |
 | --- | --- | --- |
-| Market data | Quotes, history, ticker search, crypto price and history | Yahoo Finance, Alpha Vantage fallback when configured, CoinGecko |
+| Market data | Quotes, history, ticker search, screeners, crypto price and history | Yahoo Finance, TradingView scanner, Alpha Vantage fallback when configured, CoinGecko |
 | Options | Chains, open interest, IV, locally computed Greeks | Yahoo Finance plus local calculations |
 | Fundamentals | Overview, financials, earnings, DCF, comparable companies | Alpha Vantage |
-| Macro | Rates, CPI, GDP, unemployment, crypto Fear & Greed | FRED, alternative.me |
+| Macro | Rates, CPI, GDP, unemployment, event probabilities, crypto Fear & Greed | FRED, Polymarket Gamma API, alternative.me |
 | Technical | Indicators and strategy backtests | Local calculations over market history |
 | Sentiment | Reddit, Twitter/X, Finnhub news, and web sentiment | `rdt-cli` and `twitter-cli` using your normal browser sessions, Finnhub, Exa, Brave, DuckDuckGo |
 | Filings | SEC filing search | SEC EDGAR |
 | Portfolio | Watchlists, holdings, correlation, risk | Local state plus market data |
 
-Yahoo Finance, CoinGecko, SEC EDGAR, DuckDuckGo search, and the alternative.me crypto Fear & Greed index do not require OpenCandle provider keys. Reddit sentiment requires `rdt-cli` (`uv tool install rdt-cli`) plus an active Reddit session in your normal browser. Twitter/X sentiment requires `twitter-cli` (`uv tool install twitter-cli`) plus an active x.com session in your normal browser. Alpha Vantage, FRED, Brave, Exa, and Finnhub unlock deeper coverage when configured.
+Yahoo Finance, TradingView scanner, Polymarket Gamma, CoinGecko, SEC EDGAR, DuckDuckGo search, and the alternative.me crypto Fear & Greed index do not require OpenCandle provider keys. Reddit sentiment requires `rdt-cli` (`uv tool install rdt-cli`) plus an active Reddit session in your normal browser. Twitter/X sentiment requires `twitter-cli` (`uv tool install twitter-cli`) plus an active x.com session in your normal browser. Alpha Vantage, FRED, Brave, Exa, and Finnhub unlock deeper coverage when configured.
 
 ## Configuration
 
@@ -165,7 +161,7 @@ npm run gui
 
 ## How It Fits Together
 
-![OpenCandle architecture diagram showing the user prompt flowing through OpenCandle routing, saved market state, finance data tools, evidence trace, a configured AI model, and external data sources.](assets/opencandle-architecture.png)
+![OpenCandle architecture diagram showing the user prompt flowing through OpenCandle routing, saved market state, finance data tools, evidence trace, a configured AI model, and external data sources.](https://cdn.jsdelivr.net/gh/Kahtaf/OpenCandle@main/assets/opencandle-architecture.png)
 
 ```text
 User prompt
@@ -220,9 +216,10 @@ npm run test:watch
 npm run test:e2e
 npm run test:e2e:cli
 npm run test:e2e:providers
-npm run test:evals
-npm run test:evals:product
-npm run test:evals:competitive
+npm run eval
+npm run eval -- cases
+npm run eval -- product
+npm run eval -- competitive
 ```
 
 Baseline check:
@@ -231,7 +228,7 @@ Baseline check:
 npm test
 ```
 
-The e2e, provider, and eval commands can hit live APIs, live model providers, or local agent CLIs. Run them intentionally; see [Testing and Evals](https://opencandle.app/docs/testing-and-evals.html).
+The e2e, provider, and eval commands can hit live APIs, live model providers, or local agent CLIs. `npm run eval` lists every eval suite; run suites through `npm run eval -- <suite>`. Run them intentionally; see [Testing and Evals](https://opencandle.app/docs/testing-and-evals.html).
 
 Repository rules that matter:
 

package/dist/analysts/contracts.js

@@ -145,4 +145,3 @@ export function collectEvidence(outputs) {
     }
     return evidence;
 }
-//# sourceMappingURL=contracts.js.map

package/dist/analysts/orchestrator.d.ts

@@ -1,8 +1,10 @@
 import type { WorkflowDefinition } from "../runtime/prompt-step.js";
+import type { AnalystOutput } from "../runtime/workflow-types.js";
 export type AnalystRole = "valuation" | "momentum" | "options" | "contrarian" | "risk";
 export declare function buildBullPrompt(symbol: string): string;
 export declare function buildBearPrompt(symbol: string): string;
 export declare function buildRebuttalPrompt(symbol: string): string;
+export declare function buildAnalystVoteTallyBlock(outputs: AnalystOutput[]): string | null;
 export declare function buildSynthesisPrompt(symbol: string): string;
 export declare function getInitialAnalysisPrompt(symbol: string): string;
 export declare function buildComprehensiveAnalysisDefinition(symbol: string): WorkflowDefinition;

package/dist/analysts/orchestrator.js

@@ -1,4 +1,5 @@
 import { promptStep } from "../runtime/prompt-step.js";
+import { isAnalystSplit, tallyVotes } from "./contracts.js";
 const SYMBOL_CAPTURE = "(\\$?[A-Za-z]{1,5}(?:[./-][A-Za-z]{1,2})?)";
 const NORMALIZED_SYMBOL_PATTERN = /^[A-Z]{1,5}(?:[./-][A-Z]{1,2})?$/;
 const VOTING_INSTRUCTION = `
@@ -95,7 +96,24 @@ End with this exact format:
 CONCESSIONS: [bullet list of points you concede]
 REMAINING CONVICTION: [1-10, where 10 = fully confident despite bear case]`;
 }
+export function buildAnalystVoteTallyBlock(outputs) {
+    if (outputs.length < 2)
+        return null;
+    const tally = tallyVotes(outputs);
+    const split = isAnalystSplit(outputs);
+    return `## Deterministic Analyst Vote Tally
+- Parsed analyst outputs: ${outputs.length}
+- BUY: ${tally.buy}
+- HOLD: ${tally.hold}
+- SELL: ${tally.sell}
+- Weighted average conviction: ${tally.weightedConviction}
+- Computed verdict: ${tally.verdict}
+- BUY+SELL split: ${split ? "yes" : "no"}`;
+}
 export function buildSynthesisPrompt(symbol) {
+    // The runtime tally block is injected at dispatch time by
+    // SessionCoordinator.prepareWorkflowPrompt, where parsed analyst outputs
+    // exist; this builder runs at workflow-definition time and stays static.
     return `**[Synthesis]** You have received five analyst signals with conviction scores for ${symbol}, a bull case arguing FOR the position, and a bear case arguing AGAINST.
 If a bull rebuttal with concessions appears above (not a line starting with "REBUTTAL SKIPPED"), treat the concessions as validated risks that must be addressed.
 
@@ -154,6 +172,7 @@ export function buildComprehensiveAnalysisDefinition(symbol) {
                 expectedOutputs: ["bear_thesis"],
             }),
             promptStep("debate_rebuttal", "Bull rebuttal (self-gating)", buildRebuttalPrompt(symbol), {
+                skippable: true,
                 requiredInputs: [...analystOutputs, "bull_thesis", "bear_thesis"],
                 expectedOutputs: ["rebuttal"],
             }),
@@ -190,4 +209,3 @@ export function normalizeSymbol(input) {
     const candidate = trimmed.replace(/\$/g, "").toUpperCase();
     return NORMALIZED_SYMBOL_PATTERN.test(candidate) ? candidate : undefined;
 }
-//# sourceMappingURL=orchestrator.js.map

package/dist/cli-main.js

@@ -1,5 +1,6 @@
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
@@ -98,9 +99,12 @@ async function handlePackageCommand(args, cwd, agentDir) {
 async function handleGuiCommand(args, cwd) {
     if (args[0] !== "gui")
         return false;
-    const tsxCli = require.resolve("tsx/cli");
-    const serverPath = resolve(packageRoot, "gui/server/server.ts");
-    const child = spawn(process.execPath, [tsxCli, serverPath, ...args.slice(1)], {
+    const compiledServerPath = resolve(packageRoot, "dist/gui/server/server.js");
+    const sourceServerPath = resolve(packageRoot, "gui/server/server.ts");
+    const commandArgs = existsSync(compiledServerPath)
+        ? [compiledServerPath, ...args.slice(1)]
+        : [require.resolve("tsx/cli"), sourceServerPath, ...args.slice(1)];
+    const child = spawn(process.execPath, commandArgs, {
         cwd,
         env: process.env,
         stdio: "inherit",
@@ -121,9 +125,12 @@ async function handleGuiCommand(args, cwd) {
 async function handleMonitorCommand(args, cwd) {
     if (args[0] !== "monitor")
         return false;
-    const tsxCli = require.resolve("tsx/cli");
-    const monitorPath = resolve(packageRoot, "src/monitor.ts");
-    const child = spawn(process.execPath, [tsxCli, monitorPath, ...args.slice(1)], {
+    const compiledMonitorPath = resolve(packageRoot, "dist/monitor.js");
+    const sourceMonitorPath = resolve(packageRoot, "src/monitor.ts");
+    const commandArgs = existsSync(compiledMonitorPath)
+        ? [compiledMonitorPath, ...args.slice(1)]
+        : [require.resolve("tsx/cli"), sourceMonitorPath, ...args.slice(1)];
+    const child = spawn(process.execPath, commandArgs, {
         cwd,
         env: process.env,
         stdio: "inherit",
@@ -454,4 +461,3 @@ function asRecord(value) {
         : {};
 }
 await main();
-//# sourceMappingURL=cli-main.js.map

package/dist/cli-options.d.ts

@@ -0,0 +1,4 @@
+type FrontDoorCommand = "help" | "version";
+export declare function frontDoorCommand(args: readonly string[]): FrontDoorCommand | undefined;
+export declare function renderFrontDoorCommand(command: FrontDoorCommand): string;
+export {};

package/dist/cli-options.js

@@ -0,0 +1,33 @@
+import { createRequire } from "node:module";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const require = createRequire(import.meta.url);
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+export function frontDoorCommand(args) {
+    if (args[0] === "--help" || args[0] === "-h")
+        return "help";
+    if (args[0] === "--version" || args[0] === "-v")
+        return "version";
+    return undefined;
+}
+export function renderFrontDoorCommand(command) {
+    if (command === "version")
+        return readPackageMetadata().version ?? "unknown";
+    return [
+        "Usage: opencandle [command]",
+        "",
+        "Commands:",
+        "  (default)                         Start the interactive terminal TUI",
+        "  gui                               Start the local GUI",
+        "  monitor [--once]                  Run local alert/report automation",
+        "  doctor [--json|--full|--sessions|--enable <provider>]",
+        "                                    Check OpenCandle health",
+        "  install <source> [-l]             Install a package",
+        "  remove|uninstall <source> [-l]    Remove a package",
+        "  list                              List installed packages",
+        "  update [source]                   Update packages",
+    ].join("\n");
+}
+function readPackageMetadata() {
+    return require(resolve(packageRoot, "package.json"));
+}

package/dist/cli.js

@@ -1,18 +1,23 @@
 #!/usr/bin/env node
+import { frontDoorCommand, renderFrontDoorCommand } from "./cli-options.js";
 import { ensureOpenCandleNativeDependencies } from "./infra/native-dependencies.js";
 import { assertSupportedNodeVersion } from "./infra/node-version.js";
-if (process.argv[2] === "doctor") {
+const args = process.argv.slice(2);
+const command = frontDoorCommand(args);
+if (command) {
+    console.log(renderFrontDoorCommand(command));
+}
+else if (args[0] === "doctor") {
     const [{ loadEnv }, { handleDoctorCommand }, { getAgentDir }] = await Promise.all([
         import("./config.js"),
         import("./doctor/cli-command.js"),
         import("@earendil-works/pi-coding-agent"),
     ]);
     loadEnv();
-    await handleDoctorCommand(process.argv.slice(2), process.cwd(), getAgentDir());
+    await handleDoctorCommand(args, process.cwd(), getAgentDir());
 }
 else {
     assertSupportedNodeVersion();
     await ensureOpenCandleNativeDependencies();
     await import("./cli-main.js");
 }
-//# sourceMappingURL=cli.js.map

package/dist/config.js

@@ -172,4 +172,3 @@ export function getConfig() {
 export function resetConfigCache() {
     cachedConfig = null;
 }
-//# sourceMappingURL=config.js.map

package/dist/doctor/cli-command.js

@@ -42,6 +42,8 @@ export async function handleDoctorCommand(args, cwd, agentDir) {
         modelSetup: buildCliModelSetupState(modelRegistry, settingsManager),
     });
     console.log(json ? JSON.stringify(report, null, 2) : renderDoctorReport(report));
+    if (report.status === "blocked")
+        process.exitCode = 1;
     return true;
 }
 function buildCliModelSetupState(modelRegistry, settingsManager) {
@@ -66,4 +68,3 @@ function buildCliModelSetupState(modelRegistry, settingsManager) {
         availableModels,
     };
 }
-//# sourceMappingURL=cli-command.js.map

package/dist/doctor/render.js

@@ -29,4 +29,3 @@ export function renderDoctorReport(report) {
 function isActionable(check) {
     return check.status !== "pass" && Boolean(check.remediation);
 }
-//# sourceMappingURL=render.js.map

package/dist/doctor/report.js

@@ -6,6 +6,7 @@ import { getUnsupportedNodeVersionMessage } from "../infra/node-version.js";
 import { getConfigPath, getOnboardingPath, getOpenCandleHomeDir, getStateDbPath, resolveOpenCandlePath, } from "../infra/opencandle-paths.js";
 import { probeAllProviderStatuses, probeProviderStatus, } from "../onboarding/provider-status.js";
 import { getProvider, isExternalToolProvider, listAllProviders, } from "../onboarding/providers.js";
+import { loadOnboardingState } from "../onboarding/state.js";
 export const DOCTOR_REPORT_SCHEMA_VERSION = 1;
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
 const require = createRequire(import.meta.url);
@@ -48,8 +49,8 @@ export function deriveDoctorStatus(checks) {
         return "blocked";
     }
     if (checks.some((candidate) => candidate.status === "warn" ||
-        candidate.status === "unknown" ||
-        (candidate.capability === "optional" && candidate.status === "fail"))) {
+        (candidate.capability === "optional" && candidate.status === "fail") ||
+        (candidate.capability === "core" && candidate.status === "unknown"))) {
         return "degraded";
     }
     return "ready";
@@ -301,16 +302,22 @@ function providerStatusCheck(status, modeOverride) {
         tier: provider.tier,
         kind: status.kind,
         state: status.state,
+        unlocks: provider.unlocks,
     };
     if (status.kind === "api-key") {
+        const configuredBefore = wasProviderConfigured(status.providerId);
+        const missing = status.state === "missing";
+        const neverConnected = missing && !configuredBefore;
         return {
             id: `provider.${status.providerId}.credential`,
             label: provider.displayName,
-            status: status.state === "configured" ? "pass" : "warn",
+            status: status.state === "configured" ? "pass" : neverConnected ? "skip" : "warn",
             capability,
             summary: status.state === "configured"
                 ? `Configured via ${status.credentialSource}`
-                : "Credential is missing",
+                : neverConnected
+                    ? "Not connected — optional."
+                    : "Credential is missing",
             remediation: status.state === "configured"
                 ? undefined
                 : `${provider.instructionsHint}. Run /connect ${provider.id}.`,
@@ -327,7 +334,7 @@ function providerStatusCheck(status, modeOverride) {
             summary: ok ? "Reachable" : `Not reachable (${status.state})`,
             remediation: ok
                 ? undefined
-                : "Check network connectivity and retry. Core quote and market-data workflows depend on Yahoo Finance reachability.",
+                : `Check network connectivity and retry. OpenCandle uses ${provider.displayName} through a public HTTP endpoint.`,
             metadata: { ...metadata, statusCode: status.statusCode ?? null },
         };
     }
@@ -344,6 +351,7 @@ function providerStatusCheck(status, modeOverride) {
         };
     }
     const installed = status.state === "installed";
+    const missingBeforeSetup = status.state === "missing" && !wasProviderConfigured(status.providerId);
     return {
         id: `provider.${status.providerId}.binary`,
         label: `${provider.displayName} CLI`,
@@ -352,10 +360,16 @@ function providerStatusCheck(status, modeOverride) {
             : status.state === "skipped"
                 ? "skip"
                 : status.state === "missing"
-                    ? "warn"
+                    ? missingBeforeSetup
+                        ? "skip"
+                        : "warn"
                     : "unknown",
         capability: "optional",
-        summary: installed ? "Installed" : (status.message ?? `CLI ${status.state}`),
+        summary: installed
+            ? "Installed"
+            : missingBeforeSetup
+                ? "Not connected — optional."
+                : (status.message ?? `CLI ${status.state}`),
         remediation: installed
             ? undefined
             : status.state === "skipped"
@@ -364,6 +378,9 @@ function providerStatusCheck(status, modeOverride) {
         metadata,
     };
 }
+function wasProviderConfigured(providerId) {
+    return loadOnboardingState().providers[providerId]?.status === "completed";
+}
 function sessionNotCheckedCheck(provider) {
     return {
         id: `provider.${provider.id}.session`,
@@ -385,7 +402,11 @@ async function buildGuiChecks(options) {
                 label: "GUI server",
                 status: reachable ? (role === "follower" ? "warn" : "pass") : "skip",
                 capability: "optional",
-                summary: reachable ? `GUI server is ${role}` : "GUI server is not running",
+                summary: reachable
+                    ? role === "writer"
+                        ? "GUI server is running and can run sessions"
+                        : `GUI server is ${role}`
+                    : "GUI server is not running",
                 remediation: role === "follower"
                     ? "Open the writer GUI process to perform setup mutations."
                     : reachable
@@ -415,7 +436,9 @@ async function buildGuiChecks(options) {
                 status: verified ? (role === "follower" ? "warn" : "pass") : "warn",
                 capability: "optional",
                 summary: verified
-                    ? `GUI server is ${role}`
+                    ? role === "writer"
+                        ? "GUI server is running and can run sessions"
+                        : `GUI server is ${role}`
                     : response.ok
                         ? "OpenCandle GUI health payload was not verified"
                         : `GUI health returned HTTP ${response.status}`,
@@ -449,8 +472,15 @@ function sessionRemediation(providerId, installCmd) {
     return installCmd ?? "Install and authenticate the external tool.";
 }
 function buildSummary(status, checks) {
-    if (status === "ready")
-        return "OpenCandle core health is ready.";
+    if (status === "ready") {
+        const unchecked = checks.filter((candidate) => candidate.status === "unknown");
+        if (unchecked.length === 0)
+            return "OpenCandle core health is ready.";
+        if (unchecked.every((candidate) => candidate.capability === "optional")) {
+            return `OpenCandle core health is ready with ${unchecked.length} optional ${unchecked.length === 1 ? "capability" : "capabilities"} unchecked.`;
+        }
+        return `OpenCandle is usable with ${unchecked.length} unchecked ${unchecked.length === 1 ? "capability" : "capabilities"}.`;
+    }
     const firstBlocking = checks.find((candidate) => candidate.capability === "core" && candidate.status === "fail");
     if (firstBlocking)
         return `OpenCandle is blocked: ${firstBlocking.summary}.`;
@@ -497,4 +527,3 @@ function canAccess(path, mode = constants.R_OK | constants.W_OK) {
         return false;
     }
 }
-//# sourceMappingURL=report.js.map

package/dist/gui/server/ask-user-bridge.d.ts

@@ -0,0 +1,19 @@
+import type { AskUserHandler } from "../../types/index.js";
+type AskUserParams = Parameters<AskUserHandler>[0];
+export interface GuiAskUserPrompt extends AskUserParams {
+    id: string;
+    sessionId: string;
+    status: "pending" | "answered" | "cancelled";
+    answer: string | null;
+}
+export declare function createAskUserBridge({ broadcast, getSessionId, }: {
+    broadcast: (message: unknown) => void;
+    getSessionId: () => string;
+}): {
+    ask: AskUserHandler;
+    askForSession: (sessionId: string) => AskUserHandler;
+    answer: (id: string, answer: string) => boolean;
+    cancel: (id: string) => boolean;
+    getPrompts: () => GuiAskUserPrompt[];
+};
+export {};

package/dist/gui/server/ask-user-bridge.js

@@ -0,0 +1,55 @@
+export function createAskUserBridge({ broadcast, getSessionId, }) {
+    let nextId = 1;
+    const prompts = new Map();
+    const pending = new Map();
+    const createAskHandler = (resolveSessionId) => async (params) => {
+        const id = `ask-user-${Date.now()}-${nextId++}`;
+        const prompt = {
+            id,
+            sessionId: resolveSessionId(),
+            question: params.question,
+            questionType: params.questionType,
+            options: params.options,
+            placeholder: params.placeholder,
+            reason: params.reason,
+            status: "pending",
+            answer: null,
+        };
+        prompts.set(id, prompt);
+        broadcast({ type: "ask_user.prompt", prompt });
+        return new Promise((resolve) => {
+            pending.set(id, { prompt, resolve });
+        });
+    };
+    const ask = createAskHandler(getSessionId);
+    const resolvePrompt = (id, result) => {
+        const item = pending.get(id);
+        if (!item)
+            return false;
+        pending.delete(id);
+        const prompt = {
+            ...item.prompt,
+            status: result.cancelled ? "cancelled" : "answered",
+            answer: result.cancelled ? null : (result.answer ?? null),
+        };
+        prompts.set(id, prompt);
+        broadcast({ type: "ask_user.resolved", prompt });
+        item.resolve(result);
+        return true;
+    };
+    return {
+        ask,
+        askForSession(sessionId) {
+            return createAskHandler(() => sessionId);
+        },
+        answer(id, answer) {
+            return resolvePrompt(id, { answer, cancelled: false });
+        },
+        cancel(id) {
+            return resolvePrompt(id, { answer: null, cancelled: true });
+        },
+        getPrompts() {
+            return [...prompts.values()];
+        },
+    };
+}

package/dist/gui/server/automation-heartbeat.d.ts

@@ -0,0 +1,25 @@
+import { runLocalAutomationHeartbeat } from "../../market-state/local-automation-service.js";
+import { initDefaultDatabase } from "../../memory/sqlite.js";
+export declare const DEFAULT_AUTOMATION_HEARTBEAT_MS = 60000;
+export declare const MIN_AUTOMATION_HEARTBEAT_MS = 5000;
+export declare function normalizeAutomationHeartbeatMs(raw: string | undefined): number;
+export declare function createAutomationHeartbeatRunner(run: (checkAlerts: boolean) => Promise<void>): (checkAlerts: boolean) => Promise<boolean>;
+type IntervalHandle = ReturnType<typeof setInterval>;
+type SetIntervalFn = (callback: () => void, ms: number) => IntervalHandle;
+type ClearIntervalFn = (handle: IntervalHandle) => void;
+export interface LocalAutomationHeartbeat {
+    start(): void;
+    stop(): void;
+}
+export interface LocalAutomationHeartbeatOptions {
+    role: string;
+    getSessionId: () => string;
+    intervalMs: number;
+    initDatabase?: typeof initDefaultDatabase;
+    runHeartbeat?: typeof runLocalAutomationHeartbeat;
+    setIntervalFn?: SetIntervalFn;
+    clearIntervalFn?: ClearIntervalFn;
+    warn?: (message: string) => void;
+}
+export declare function createLocalAutomationHeartbeat({ role, getSessionId, intervalMs, initDatabase, runHeartbeat, setIntervalFn, clearIntervalFn, warn, }: LocalAutomationHeartbeatOptions): LocalAutomationHeartbeat;
+export {};

package/dist/gui/server/automation-heartbeat.js

@@ -0,0 +1,61 @@
+import { runLocalAutomationHeartbeat } from "../../market-state/local-automation-service.js";
+import { initDefaultDatabase } from "../../memory/sqlite.js";
+export const DEFAULT_AUTOMATION_HEARTBEAT_MS = 60_000;
+export const MIN_AUTOMATION_HEARTBEAT_MS = 5_000;
+export function normalizeAutomationHeartbeatMs(raw) {
+    if (raw == null || raw.trim() === "")
+        return DEFAULT_AUTOMATION_HEARTBEAT_MS;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed < MIN_AUTOMATION_HEARTBEAT_MS)
+        return DEFAULT_AUTOMATION_HEARTBEAT_MS;
+    return Math.floor(parsed);
+}
+export function createAutomationHeartbeatRunner(run) {
+    let inFlight = false;
+    return async (checkAlerts) => {
+        if (inFlight)
+            return false;
+        inFlight = true;
+        try {
+            await run(checkAlerts);
+            return true;
+        }
+        finally {
+            inFlight = false;
+        }
+    };
+}
+export function createLocalAutomationHeartbeat({ role, getSessionId, intervalMs, initDatabase = initDefaultDatabase, runHeartbeat = runLocalAutomationHeartbeat, setIntervalFn = setInterval, clearIntervalFn = clearInterval, warn = (message) => console.warn(message), }) {
+    let automationHeartbeat = null;
+    async function executeGuiAutomationHeartbeat(checkAlerts) {
+        const db = initDatabase();
+        try {
+            await runHeartbeat(db, {
+                ownerId: `gui:${getSessionId()}`,
+                ownerKind: "writer",
+                ttlSeconds: Math.max(90, Math.ceil((intervalMs * 2) / 1000)),
+                checkAlerts,
+            });
+        }
+        catch (error) {
+            warn(`Local automation heartbeat failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        finally {
+            db.close();
+        }
+    }
+    const runGuiAutomationHeartbeat = createAutomationHeartbeatRunner(executeGuiAutomationHeartbeat);
+    function start() {
+        if (role !== "writer")
+            return;
+        void runGuiAutomationHeartbeat(true);
+        automationHeartbeat = setIntervalFn(() => void runGuiAutomationHeartbeat(true), intervalMs);
+    }
+    function stop() {
+        if (automationHeartbeat) {
+            clearIntervalFn(automationHeartbeat);
+            automationHeartbeat = null;
+        }
+    }
+    return { start, stop };
+}