opencandle 0.3.0 → 0.4.0

package/src/runtime/session-coordinator.ts

@@ -0,0 +1,406 @@
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext, SessionEntry } from "@earendil-works/pi-coding-agent";
+import { getAllDefaults, initDefaultDatabase, MemoryStorage } from "../memory/index.js";
+
+/**
+ * Alias for the session-manager handle extensions receive via
+ * `ExtensionContext`. `ReadonlySessionManager` is defined inside pi-coding-
+ * agent but is not re-exported from the package's `.` entry, so we derive
+ * the shape we need from the public `ExtensionContext` type.
+ */
+type ReadonlySessionManager = ExtensionContext["sessionManager"];
+import { MemoryManager } from "../memory/manager.js";
+import { extractPreferences } from "../memory/preference-extractor.js";
+import { runOpenCandleSetup } from "../pi/setup.js";
+import { WorkflowEventLogger } from "./workflow-events.js";
+import { ProviderTracker } from "./provider-tracker.js";
+import { WorkflowRunner } from "./workflow-runner.js";
+import { setRunContext, clearRunContext } from "./run-context.js";
+import { PromptContextBuilder, type FallbackContext } from "../prompts/context-builder.js";
+import { getAddonToolDescriptions } from "../tool-kit.js";
+import type { WorkflowDefinition } from "./prompt-step.js";
+import { toStepDefinitions, promptStepOutput } from "./prompt-step.js";
+import type Database from "better-sqlite3";
+
+const PROMPT_SETTLE_POLL_MS = 25;
+const IMMEDIATE_IDLE_GRACE_MS = 100;
+
+function parseMaybeJson(raw: unknown): Record<string, unknown> | undefined {
+  if (typeof raw !== "string" || raw.length === 0) return undefined;
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+type QueueContext = ExtensionCommandContext | {
+  isIdle(): boolean;
+  hasPendingMessages?(): boolean;
+  ui?: { notify(message: string, level?: string): void };
+};
+
+function hasPendingMessages(ctx: QueueContext): boolean {
+  return ctx.hasPendingMessages?.() ?? false;
+}
+
+function isReadyForNextPrompt(ctx: QueueContext): boolean {
+  return ctx.isIdle() && !hasPendingMessages(ctx);
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function waitForPromptSettlement(
+  ctx: QueueContext,
+  isCurrentRun: () => boolean,
+): Promise<boolean> {
+  let sawBusyOrPending = !isReadyForNextPrompt(ctx);
+  const startedAt = Date.now();
+
+  while (isCurrentRun()) {
+    const ready = isReadyForNextPrompt(ctx);
+    if (!ready) {
+      sawBusyOrPending = true;
+    }
+
+    if (sawBusyOrPending && ready) {
+      return true;
+    }
+
+    if (!sawBusyOrPending && ready && Date.now() - startedAt >= IMMEDIATE_IDLE_GRACE_MS) {
+      return true;
+    }
+
+    await sleep(PROMPT_SETTLE_POLL_MS);
+  }
+
+  return false;
+}
+
+/**
+ * Coordinates session lifecycle, memory, workflow execution,
+ * and prompt assembly. The extension delegates to this.
+ */
+export class SessionCoordinator {
+  private db: Database.Database | null = null;
+  private storage: MemoryStorage | null = null;
+  private memoryManager: MemoryManager | null = null;
+  private eventLogger: WorkflowEventLogger | null = null;
+  private runner: WorkflowRunner;
+  private providerTracker: ProviderTracker;
+  private sessionId = "unknown";
+
+  constructor() {
+    // Runner is always available — event logger is optional and added after session init
+    this.providerTracker = new ProviderTracker();
+    this.runner = new WorkflowRunner({ providerTracker: this.providerTracker });
+  }
+
+  getStorage(): MemoryStorage | null {
+    return this.storage;
+  }
+
+  getRunner(): WorkflowRunner {
+    return this.runner;
+  }
+
+  /** Initialize session: database, memory, event logger, workflow runner. */
+  initSession(sessionId: string): void {
+    this.db = initDefaultDatabase();
+    this.storage = new MemoryStorage(this.db);
+    this.memoryManager = new MemoryManager(this.storage);
+    this.eventLogger = new WorkflowEventLogger(this.db);
+    this.providerTracker = new ProviderTracker();
+    this.runner = new WorkflowRunner({
+      eventLogger: this.eventLogger,
+      providerTracker: this.providerTracker,
+    });
+    this.sessionId = sessionId;
+  }
+
+  /** Run setup flow. */
+  async runSetup(
+    pi: ExtensionAPI,
+    ctx: ExtensionContext | ExtensionCommandContext,
+    options: { mode: "startup" | "manual" },
+  ): Promise<"ready" | "shutdown" | "cancelled"> {
+    return runOpenCandleSetup(pi, ctx, options);
+  }
+
+  /** Extract and persist user preferences from natural language. */
+  extractAndStorePreferences(text: string): void {
+    if (!this.storage) return;
+    for (const pref of extractPreferences(text)) {
+      this.storage.upsertPreference({
+        key: pref.key,
+        valueJson: JSON.stringify(pref.value),
+        confidence: pref.confidence,
+        source: "inferred",
+      });
+    }
+  }
+
+  /** Record a workflow run in storage. */
+  recordWorkflowRun(
+    workflowType: string,
+    entities: object,
+    resolved: object,
+    defaultsUsed: unknown[],
+    turnType: "workflow" | "fallback" = "workflow",
+  ): void {
+    this.storage?.insertWorkflowRun({
+      sessionId: this.sessionId,
+      workflowType,
+      inputSlotsJson: JSON.stringify(entities),
+      resolvedSlotsJson: JSON.stringify(resolved),
+      defaultsUsedJson: JSON.stringify(defaultsUsed),
+      turnType,
+    });
+  }
+
+  /**
+   * Extract the last `max` user/assistant turns from the session branch as
+   * `{role, text}` pairs, oldest→newest. Walks `sessionManager.getBranch()`
+   * (root→leaf order) and filters per the intent-routing spec:
+   *
+   * - Keep only `type === "message"` entries whose `message.role` is
+   *   `"user"` or `"assistant"`. Compaction, branch_summary, custom, label,
+   *   thinking_level_change, model_change, and session_info entries are
+   *   skipped. Tool-result messages (`role === "toolResult"`) are skipped.
+   * - Extract concatenated text-block content. User `content` may be a
+   *   plain string; assistant `content` is always an array of blocks, from
+   *   which only `type === "text"` blocks contribute.
+   * - Drop entries whose resulting text is empty or whitespace-only
+   *   (handles aborted assistant turns and tool-only assistant turns).
+   * - Slice to the last `max` qualifying entries.
+   *
+   * Privacy note: conversational text in priorTurns is NOT filtered by
+   * `NEVER_TRUST_FROM_MEMORY` (which governs structured memory keys). A
+   * future `/forget` command is the designated scrubbing primitive — see
+   * `openspec/changes/router-context-and-observability/` for the follow-up.
+   */
+  buildPriorTurns(
+    sessionManager: ReadonlySessionManager,
+    max = 5,
+  ): Array<{ role: "user" | "assistant"; text: string }> {
+    const branch = sessionManager.getBranch();
+    const turns: Array<{ role: "user" | "assistant"; text: string }> = [];
+
+    for (const entry of branch) {
+      if (entry.type !== "message") continue;
+      const msg = (entry as SessionEntry & { type: "message" }).message;
+      if (!msg || typeof msg !== "object") continue;
+      const role = (msg as { role?: unknown }).role;
+      if (role !== "user" && role !== "assistant") continue;
+
+      const rawContent = (msg as { content?: unknown }).content;
+      let text = "";
+      if (typeof rawContent === "string") {
+        text = rawContent;
+      } else if (Array.isArray(rawContent)) {
+        for (const block of rawContent) {
+          if (
+            block &&
+            typeof block === "object" &&
+            (block as { type?: unknown }).type === "text" &&
+            typeof (block as { text?: unknown }).text === "string"
+          ) {
+            text += (block as { text: string }).text;
+          }
+        }
+      }
+
+      if (text.trim().length === 0) continue;
+      turns.push({ role, text });
+    }
+
+    return turns.slice(-max);
+  }
+
+  /**
+   * Expose prior turns + recent runs + profile snapshot for the router
+   * input context. Fixed-window per design.md §7 (last 5 turns, 3 runs).
+   * `priorTurns` is derived from the session branch at call time; see
+   * `buildPriorTurns` for the filter rules.
+   */
+  buildRouterContextBase(sessionManager: ReadonlySessionManager): {
+    profileSnapshot: Record<string, unknown>;
+    recentWorkflowRuns: Array<{
+      workflowType: string;
+      turnType: string;
+      resolvedSlots?: Record<string, unknown>;
+      createdAt: string;
+    }>;
+    priorTurns: Array<{ role: "user" | "assistant"; text: string }>;
+  } {
+    const priorTurns = this.buildPriorTurns(sessionManager);
+    if (!this.storage) {
+      return { profileSnapshot: {}, recentWorkflowRuns: [], priorTurns };
+    }
+    const prefs = this.storage.getPreferencesByNamespace("global");
+    const profileSnapshot: Record<string, unknown> = {};
+    for (const p of prefs) {
+      const key = String(p.key);
+      const rawValue = p.value_json;
+      if (typeof rawValue === "string") {
+        try {
+          profileSnapshot[key] = JSON.parse(rawValue);
+        } catch {
+          profileSnapshot[key] = rawValue;
+        }
+      }
+    }
+    const runs = this.storage.getRecentWorkflowRuns(3).map((r) => ({
+      workflowType: String(r.workflow_type ?? ""),
+      turnType: String(r.turn_type ?? "workflow"),
+      resolvedSlots: parseMaybeJson(r.resolved_slots_json),
+      createdAt: String(r.created_at ?? ""),
+    }));
+    return { profileSnapshot, recentWorkflowRuns: runs, priorTurns };
+  }
+
+  /** Build system prompt using composable sections. */
+  buildSystemPrompt(
+    basePrompt: string,
+    workflowType?: string,
+    fallbackContext?: FallbackContext,
+  ): string {
+    const builder = new PromptContextBuilder();
+
+    const addonTools = getAddonToolDescriptions();
+    const addonDescriptions = addonTools.length > 0
+      ? addonTools.map((t) => `${t.name}: ${t.description}`)
+      : undefined;
+
+    const memoryContext = this.memoryManager
+      ? this.memoryManager.buildContext(workflowType ?? "unclassified")
+      : undefined;
+
+    builder.populateFromOptions({
+      workflowType,
+      memoryContext: memoryContext || undefined,
+      addonToolDescriptions: addonDescriptions,
+      fallbackContext,
+    });
+
+    const toolDefaults = formatToolDefaultsForPrompt();
+    const defaultsSection = toolDefaults.length > 0
+      ? `\n\n## User Tool Defaults\n${toolDefaults.join("\n")}`
+      : "";
+
+    return `${basePrompt}\n\n${builder.build()}${defaultsSection}`;
+  }
+
+  /**
+   * Stash a pending fallback context so the very next `before_agent_start`
+   * hook can slot it into the system prompt. Cleared after consumption so
+   * subsequent turns do not inherit stale fallback directives.
+   */
+  private pendingFallbackContext: FallbackContext | null = null;
+
+  setPendingFallbackContext(ctx: FallbackContext | null): void {
+    this.pendingFallbackContext = ctx;
+  }
+
+  consumePendingFallbackContext(): FallbackContext | null {
+    const ctx = this.pendingFallbackContext;
+    this.pendingFallbackContext = null;
+    return ctx;
+  }
+
+  /**
+   * Execute a workflow definition through the WorkflowRunner,
+   * sending prompts via Pi with settlement-based sequencing.
+   */
+  executeWorkflow(
+    pi: ExtensionAPI,
+    definition: WorkflowDefinition,
+    ctx: QueueContext,
+  ): void {
+    if (definition.steps.length === 0) return;
+
+    const runner = this.runner;
+    const runRef = { active: true };
+
+    // Send the first prompt immediately
+    const [firstStep, ...restSteps] = definition.steps;
+    const startedBusy = !isReadyForNextPrompt(ctx);
+
+    if (startedBusy) {
+      pi.sendUserMessage(firstStep.prompt, { deliverAs: "followUp" });
+      ctx.ui?.notify?.("Analysis queued as follow-up.", "info");
+    } else {
+      pi.sendUserMessage(firstStep.prompt);
+    }
+
+    // Make the run's ProviderTracker accessible to tools during execution
+    setRunContext({ providerTracker: this.providerTracker });
+
+    // Start the runner in the background for state tracking
+    const stepDefs = toStepDefinitions(definition.steps);
+    void runner.start(definition.workflowType, stepDefs, async (step, stepIndex) => {
+      // First step was already sent above — just wait for settlement
+      if (stepIndex > 0) {
+        const settled = await waitForPromptSettlement(ctx, () => runRef.active);
+        if (!settled || !runRef.active) {
+          throw new Error("run_cancelled");
+        }
+        pi.sendUserMessage(definition.steps[stepIndex].prompt);
+      } else {
+        // For the first step, just wait for it to settle
+        const settled = await waitForPromptSettlement(ctx, () => runRef.active);
+        if (!settled || !runRef.active) {
+          throw new Error("run_cancelled");
+        }
+      }
+      return promptStepOutput(stepIndex, step.stepType);
+    }).finally(() => {
+      clearRunContext();
+    });
+  }
+
+  /** Cancel any active workflow. */
+  cancelActiveWorkflow(): void {
+    clearRunContext();
+    this.runner?.cancel();
+  }
+}
+
+function formatToolDefaultsForPrompt(): string[] {
+  try {
+    return [...getAllDefaults()]
+      .filter(([, defaults]) => Object.keys(defaults).some((key) => key !== "__enabled"))
+      .map(([toolName, defaults]) => {
+        const pairs = flattenDefaults(defaults)
+          .filter(([key]) => key !== "__enabled")
+          .map(([key, value]) => `${key}: ${String(value)}`);
+        return `- User has set defaults for \`${toolName}\` (${pairs.join(", ")}). You may override when the user's request requires it.`;
+      });
+  } catch {
+    return [];
+  }
+}
+
+function flattenDefaults(
+  defaults: Record<string, unknown>,
+  prefix = "",
+): Array<[string, unknown]> {
+  const out: Array<[string, unknown]> = [];
+  for (const [key, value] of Object.entries(defaults)) {
+    const path = prefix ? `${prefix}.${key}` : key;
+    if (isPlainObject(value)) {
+      out.push(...flattenDefaults(value, path));
+    } else {
+      out.push([path, value]);
+    }
+  }
+  return out;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/runtime/tool-defaults-wrapper.ts

@@ -0,0 +1,35 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import type { TSchema } from "@sinclair/typebox";
+
+export function wrapWithDefaults<TParams extends TSchema, TDetails>(
+  tool: AgentTool<TParams, TDetails>,
+  defaults: Record<string, unknown>,
+): AgentTool<TParams, TDetails> {
+  return {
+    ...tool,
+    execute: async (toolCallId, params, signal, onUpdate) => {
+      const merged = mergeDefaults(defaults, params as Record<string, unknown>);
+      return tool.execute(toolCallId, merged as typeof params, signal, onUpdate);
+    },
+  };
+}
+
+function mergeDefaults(
+  defaults: Record<string, unknown>,
+  args: Record<string, unknown>,
+): Record<string, unknown> {
+  if (Object.keys(defaults).length === 0) return args;
+
+  const out: Record<string, unknown> = { ...defaults };
+  for (const [key, value] of Object.entries(args)) {
+    const base = out[key];
+    out[key] = isPlainObject(base) && isPlainObject(value)
+      ? mergeDefaults(base, value)
+      : value;
+  }
+  return out;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/runtime/validation.ts

@@ -0,0 +1,214 @@
+import type { EvidenceRecord } from "./evidence.js";
+
+/** A single validation check result. */
+export interface ValidationEntry {
+  message: string;
+  evidenceLabel?: string;
+  detail?: string;
+}
+
+/** Result of running all deterministic validation checks. */
+export interface ValidationResult {
+  passes: ValidationEntry[];
+  failures: ValidationEntry[];
+  warnings: ValidationEntry[];
+}
+
+/** Create an empty validation result. */
+export function emptyValidationResult(): ValidationResult {
+  return { passes: [], failures: [], warnings: [] };
+}
+
+/** Check that market-sensitive evidence records have timestamps. */
+export function checkTimestamps(
+  evidence: EvidenceRecord[],
+  marketSensitiveLabels: Set<string>,
+): ValidationEntry[] {
+  const warnings: ValidationEntry[] = [];
+  for (const record of evidence) {
+    if (
+      marketSensitiveLabels.has(record.label) &&
+      record.provenance.source === "fetched" &&
+      !record.provenance.timestamp
+    ) {
+      warnings.push({
+        message: `Market-sensitive value '${record.label}' has no timestamp`,
+        evidenceLabel: record.label,
+      });
+    }
+  }
+  return warnings;
+}
+
+/** Check that options expiry dates are in the future. */
+export function checkOptionsExpiries(
+  evidence: EvidenceRecord[],
+  today: string,
+): ValidationEntry[] {
+  const failures: ValidationEntry[] = [];
+  for (const record of evidence) {
+    if (
+      record.label.toLowerCase().includes("expir") &&
+      typeof record.value === "string" &&
+      record.value < today
+    ) {
+      failures.push({
+        message: `Options expiry ${record.value} is in the past`,
+        evidenceLabel: record.label,
+        detail: `Today is ${today}`,
+      });
+    }
+  }
+  return failures;
+}
+
+/** Check that all required fields have evidence records. */
+export function checkRequiredFields(
+  evidence: EvidenceRecord[],
+  requiredLabels: string[],
+): ValidationEntry[] {
+  const present = new Set(evidence.map((e) => e.label));
+  const failures: ValidationEntry[] = [];
+  for (const label of requiredLabels) {
+    if (!present.has(label)) {
+      failures.push({
+        message: `Required field '${label}' has no evidence record`,
+        evidenceLabel: label,
+      });
+    }
+  }
+  return failures;
+}
+
+/** Default market-sensitive labels. */
+export const DEFAULT_MARKET_SENSITIVE_LABELS = new Set([
+  "Stock Price",
+  "Volume",
+  "Market Cap",
+  "52-Week High",
+  "52-Week Low",
+  "Bid",
+  "Ask",
+  "Day High",
+  "Day Low",
+  "Open",
+  "Previous Close",
+  "Crypto Price",
+  "Crypto Volume",
+]);
+
+/** Configuration for the runtime validator. */
+export interface ValidatorConfig {
+  marketSensitiveLabels?: Set<string>;
+  requiredFields?: string[];
+  toolResults?: Map<string, number>;
+  today?: string;
+}
+
+/**
+ * Orchestrates all deterministic validation checks on evidence records.
+ * Runs before LLM-based validation.
+ */
+export class RuntimeValidator {
+  private readonly config: ValidatorConfig;
+
+  constructor(config: ValidatorConfig = {}) {
+    this.config = config;
+  }
+
+  /** Run all validation checks and return a combined result. */
+  validate(evidence: EvidenceRecord[]): ValidationResult {
+    const result = emptyValidationResult();
+
+    // Timestamp checks
+    const timestampWarnings = checkTimestamps(
+      evidence,
+      this.config.marketSensitiveLabels ?? DEFAULT_MARKET_SENSITIVE_LABELS,
+    );
+    result.warnings.push(...timestampWarnings);
+
+    // Options expiry checks
+    const today = this.config.today ?? new Date().toISOString().slice(0, 10);
+    const expiryFailures = checkOptionsExpiries(evidence, today);
+    result.failures.push(...expiryFailures);
+
+    // Required field checks
+    if (this.config.requiredFields) {
+      const fieldFailures = checkRequiredFields(evidence, this.config.requiredFields);
+      result.failures.push(...fieldFailures);
+    }
+
+    // Number match checks
+    if (this.config.toolResults) {
+      const numberEntries = checkNumberMatch(evidence, this.config.toolResults);
+      for (const entry of numberEntries) {
+        if ((entry as any).type === "pass") {
+          result.passes.push(entry);
+        } else {
+          result.failures.push(entry);
+        }
+      }
+    }
+
+    return result;
+  }
+
+  /** Format validation results as a summary string for the LLM validation prompt. */
+  formatForLLM(result: ValidationResult): string {
+    const lines: string[] = ["## Deterministic Validation Results"];
+
+    if (result.failures.length > 0) {
+      lines.push(`\n### Failures (${result.failures.length})`);
+      for (const f of result.failures) {
+        lines.push(`- ${f.message}`);
+      }
+    }
+
+    if (result.warnings.length > 0) {
+      lines.push(`\n### Warnings (${result.warnings.length})`);
+      for (const w of result.warnings) {
+        lines.push(`- ${w.message}`);
+      }
+    }
+
+    if (result.passes.length > 0) {
+      lines.push(`\n### Verified (${result.passes.length})`);
+      for (const p of result.passes) {
+        lines.push(`- ${p.message}`);
+      }
+    }
+
+    if (result.failures.length === 0 && result.warnings.length === 0) {
+      lines.push("\nAll deterministic checks passed.");
+    }
+
+    return lines.join("\n");
+  }
+}
+
+/** Check that evidence values match expected tool result values. */
+export function checkNumberMatch(
+  evidence: EvidenceRecord[],
+  toolResults: Map<string, number>,
+): ValidationEntry[] {
+  const results: (ValidationEntry & { type: "pass" | "failure" })[] = [];
+  for (const record of evidence) {
+    if (typeof record.value !== "number") continue;
+    const expected = toolResults.get(record.label);
+    if (expected === undefined) continue;
+    if (record.value === expected) {
+      results.push({
+        type: "pass",
+        message: `${record.label}: ${record.value} matches tool result`,
+        evidenceLabel: record.label,
+      });
+    } else {
+      results.push({
+        type: "failure",
+        message: `${record.label} mismatch: evidence says ${record.value}, tool returned ${expected}`,
+        evidenceLabel: record.label,
+      });
+    }
+  }
+  return results;
+}