opencandle 0.11.1 → 0.13.0

package/src/runtime/session-title.ts

@@ -1,60 +0,0 @@
-/**
- * LLM-summarized session titles.
- *
- * Builds a strict short-title prompt from the user's first message (plus an
- * optional slice of the first assistant reply), delegates to an injected
- * completion function, and sanitizes the result. Returns null when the model
- * output is unusable (empty or rambling) so callers can keep the existing
- * placeholder name. Completion errors propagate to the caller.
- */
-
-const MAX_TITLE_CHARS = 60;
-const MAX_TITLE_WORDS = 12;
-
-export interface SessionTitleInput {
-  userText: string;
-  assistantText?: string;
-}
-
-export async function generateSessionTitle(
-  input: SessionTitleInput,
-  complete: (prompt: string) => Promise<string>,
-): Promise<string | null> {
-  const lines = [
-    "Write a 4-8 word title for this finance chat session.",
-    "No quotes, no punctuation at the end, no markdown. Return only the title.",
-    "",
-    `User: ${input.userText}`,
-  ];
-  if (input.assistantText !== undefined && input.assistantText.trim().length > 0) {
-    lines.push("", `Assistant: ${input.assistantText}`);
-  }
-  const raw = await complete(lines.join("\n"));
-  return sanitizeTitle(raw);
-}
-
-function sanitizeTitle(raw: string): string | null {
-  // First non-empty line only — discard any model commentary after a newline.
-  let title =
-    raw
-      .split("\n")
-      .map((line) => line.trim())
-      .find((line) => line.length > 0) ?? "";
-  // Strip markdown emphasis/heading/code characters.
-  title = title.replace(/[*_`#]/g, "");
-  // Strip surrounding quotes.
-  title = title.replace(/^["'“”‘’]+/, "").replace(/["'“”‘’]+$/, "");
-  // Strip trailing punctuation.
-  title = title.replace(/[.!?:;,]+$/, "");
-  // Collapse whitespace.
-  title = title.replace(/\s+/g, " ").trim();
-
-  if (title.length === 0) return null;
-  if (title.split(" ").length > MAX_TITLE_WORDS) return null;
-  if (title.length > MAX_TITLE_CHARS) {
-    const cut = title.slice(0, MAX_TITLE_CHARS);
-    const lastSpace = cut.lastIndexOf(" ");
-    title = (lastSpace > 0 ? cut.slice(0, lastSpace) : cut).trim();
-  }
-  return title;
-}

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

@@ -1,43 +0,0 @@
-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, ctx?: unknown) => {
-      const merged = mergeDefaults(defaults, params as Record<string, unknown>);
-      const executeWithContext = tool.execute as unknown as (
-        id: string,
-        params: unknown,
-        signal?: AbortSignal,
-        onUpdate?: unknown,
-        ctx?: unknown,
-      ) => ReturnType<typeof tool.execute>;
-      if (ctx === undefined) {
-        return executeWithContext(toolCallId, merged, signal, onUpdate);
-      }
-      return executeWithContext(toolCallId, merged, signal, onUpdate, ctx);
-    },
-  };
-}
-
-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

@@ -1,211 +0,0 @@
-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>,
-): Array<ValidationEntry & { type: "pass" | "failure" }> {
-  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;
-}

package/src/runtime/workflow-events.ts

@@ -1,77 +0,0 @@
-import type Database from "better-sqlite3";
-
-/** All workflow event types. */
-export type WorkflowEventType =
-  | "workflow_started"
-  | "slot_resolved"
-  | "clarification_asked"
-  | "clarification_answered"
-  | "step_started"
-  | "step_completed"
-  | "step_failed"
-  | "step_skipped"
-  | "tool_called"
-  | "tool_failed"
-  | "tally_injected"
-  | "tally_skipped"
-  | "validation_passed"
-  | "validation_failed"
-  | "workflow_completed"
-  | "workflow_cancelled";
-
-/** A persisted workflow event row. */
-export interface WorkflowEvent {
-  id: number;
-  runId: string;
-  stepIndex: number;
-  eventType: WorkflowEventType;
-  payloadJson: string | null;
-  timestamp: string;
-}
-
-/** Append-only workflow event logger backed by SQLite. */
-export class WorkflowEventLogger {
-  constructor(private readonly db: Database.Database) {}
-
-  /** Append a workflow event. */
-  log(
-    runId: string,
-    stepIndex: number,
-    eventType: WorkflowEventType,
-    payload?: Record<string, unknown>,
-  ): void {
-    const now = new Date().toISOString();
-    const payloadJson = payload ? JSON.stringify(payload) : null;
-    this.db
-      .prepare(
-        `INSERT INTO workflow_events (run_id, step_index, event_type, payload_json, timestamp)
-         VALUES (?, ?, ?, ?, ?)`,
-      )
-      .run(runId, stepIndex, eventType, payloadJson, now);
-  }
-
-  /** Query all events for a given run ID, ordered by timestamp. */
-  getEventsByRunId(runId: string): WorkflowEvent[] {
-    const rows = this.db
-      .prepare(
-        "SELECT id, run_id, step_index, event_type, payload_json, timestamp FROM workflow_events WHERE run_id = ? ORDER BY id",
-      )
-      .all(runId) as Array<{
-      id: number;
-      run_id: string;
-      step_index: number;
-      event_type: string;
-      payload_json: string | null;
-      timestamp: string;
-    }>;
-
-    return rows.map((r) => ({
-      id: r.id,
-      runId: r.run_id,
-      stepIndex: r.step_index,
-      eventType: r.event_type as WorkflowEventType,
-      payloadJson: r.payload_json,
-      timestamp: r.timestamp,
-    }));
-  }
-}

package/src/runtime/workflow-runner.ts

@@ -1,182 +0,0 @@
-import type { EvidenceRecord } from "./evidence.js";
-import type { ProviderTracker } from "./provider-tracker.js";
-import type { WorkflowEventLogger } from "./workflow-events.js";
-import type { StepOutput, WorkflowRun, WorkflowStep } from "./workflow-types.js";
-import { createWorkflowRun, transitionStepStatus } from "./workflow-types.js";
-
-/** Function that executes a single workflow step. */
-export type StepExecutor = (
-  step: WorkflowStep,
-  stepIndex: number,
-  priorEvidence: EvidenceRecord[],
-  context: StepExecutionContext,
-) => Promise<StepOutput>;
-
-/** Context passed to step executors. */
-export interface StepExecutionContext {
-  runId: string;
-  providerTracker: ProviderTracker;
-}
-
-/** Options for creating a WorkflowRunner. */
-export interface WorkflowRunnerOptions {
-  eventLogger?: WorkflowEventLogger;
-  providerTracker?: ProviderTracker;
-}
-
-let runCounter = 0;
-
-function generateRunId(): string {
-  runCounter += 1;
-  return `run_${Date.now()}_${runCounter}`;
-}
-
-/**
- * Typed workflow execution engine with run IDs, step definitions,
- * state transitions, cancellation, and event logging.
- */
-export class WorkflowRunner {
-  private readonly eventLogger?: WorkflowEventLogger;
-  private readonly providerTracker?: ProviderTracker;
-  private activeRun: WorkflowRun | null = null;
-
-  constructor(options: WorkflowRunnerOptions = {}) {
-    this.eventLogger = options.eventLogger;
-    this.providerTracker = options.providerTracker;
-  }
-
-  /** Get the currently active run, if any. */
-  getActiveRun(): WorkflowRun | null {
-    return this.activeRun;
-  }
-
-  /**
-   * Start a new workflow run. If a run is already active, it is cancelled first.
-   */
-  async start(
-    workflowType: string,
-    stepDefinitions: Omit<WorkflowStep, "status">[],
-    executor: StepExecutor,
-  ): Promise<WorkflowRun> {
-    // Cancel any active run
-    if (this.activeRun && this.activeRun.status === "running") {
-      this.cancel();
-    }
-
-    const runId = generateRunId();
-    const run = createWorkflowRun(runId, workflowType, stepDefinitions);
-    this.activeRun = run;
-    run.status = "running";
-
-    this.providerTracker?.resetAll();
-
-    this.logEvent(runId, 0, "workflow_started", {
-      workflowType,
-      stepCount: stepDefinitions.length,
-    });
-
-    // Execute steps
-    await this.executeSteps(run, executor);
-
-    return run;
-  }
-
-  /** Cancel the active run. */
-  cancel(): void {
-    const run = this.activeRun;
-    if (!run || run.status !== "running") return;
-
-    for (let i = run.currentStepIndex; i < run.steps.length; i++) {
-      const step = run.steps[i];
-      if (step.status === "pending" || step.status === "running") {
-        step.status = transitionStepStatus(step.status, "skipped");
-        this.logEvent(run.runId, i, "step_skipped", {
-          stepType: step.stepType,
-          reason: "cancelled",
-        });
-      }
-    }
-
-    run.status = "cancelled";
-    this.logEvent(run.runId, run.currentStepIndex, "workflow_cancelled", {
-      cancelledAtStep: run.currentStepIndex,
-    });
-  }
-
-  private async executeSteps(run: WorkflowRun, executor: StepExecutor): Promise<void> {
-    for (let i = 0; i < run.steps.length; i++) {
-      // Check if run was cancelled externally
-      if (run.status !== "running") return;
-
-      const step = run.steps[i];
-      run.currentStepIndex = i;
-
-      // Collect all prior evidence
-      const priorEvidence: EvidenceRecord[] = [];
-      for (const [, output] of run.stepOutputs) {
-        priorEvidence.push(...output.evidence);
-      }
-
-      // Transition to running
-      step.status = transitionStepStatus(step.status, "running");
-      this.logEvent(run.runId, i, "step_started", { stepType: step.stepType });
-
-      try {
-        const context: StepExecutionContext = {
-          runId: run.runId,
-          providerTracker: this.providerTracker!,
-        };
-
-        const output = await executor(step, i, priorEvidence, context);
-
-        // If run was cancelled during execution, stop without further transitions
-        if (run.status !== "running") return;
-
-        step.status = transitionStepStatus(step.status, "completed");
-        run.stepOutputs.set(i, output);
-
-        this.logEvent(run.runId, i, "step_completed", {
-          stepType: step.stepType,
-          evidenceCount: output.evidence.length,
-        });
-      } catch (error) {
-        // If run was cancelled during execution, stop without further transitions
-        if (run.status !== "running") return;
-
-        const message = error instanceof Error ? error.message : "unknown_error";
-
-        if (step.skippable) {
-          step.status = transitionStepStatus(step.status, "skipped");
-          this.logEvent(run.runId, i, "step_skipped", {
-            stepType: step.stepType,
-            reason: message,
-          });
-        } else {
-          step.status = transitionStepStatus(step.status, "failed");
-          this.logEvent(run.runId, i, "step_failed", {
-            stepType: step.stepType,
-            error: message,
-          });
-          run.status = "failed";
-          return;
-        }
-      }
-    }
-
-    if (run.status === "running") {
-      run.status = "completed";
-      this.logEvent(run.runId, run.steps.length - 1, "workflow_completed", {
-        workflowType: run.workflowType,
-      });
-    }
-  }
-
-  private logEvent(
-    runId: string,
-    stepIndex: number,
-    eventType: string,
-    payload: Record<string, unknown>,
-  ): void {
-    this.eventLogger?.log(runId, stepIndex, eventType as any, payload);
-  }
-}

package/src/runtime/workflow-types.ts

@@ -1,105 +0,0 @@
-import type { EvidenceRecord } from "./evidence.js";
-
-/** Status of a single workflow step. */
-export type StepStatus = "pending" | "running" | "completed" | "failed" | "skipped";
-
-/** Overall status of a workflow run. */
-export type RunStatus = "pending" | "running" | "completed" | "failed" | "cancelled";
-
-/** Valid step status transitions. */
-const VALID_STEP_TRANSITIONS: Record<StepStatus, StepStatus[]> = {
-  pending: ["running", "skipped"],
-  running: ["completed", "failed", "skipped"],
-  completed: [],
-  failed: [],
-  skipped: [],
-};
-
-/** Check whether a step status transition is valid. */
-export function isValidStepTransition(from: StepStatus, to: StepStatus): boolean {
-  return VALID_STEP_TRANSITIONS[from].includes(to);
-}
-
-/** Transition a step status, throwing on invalid transitions. */
-export function transitionStepStatus(from: StepStatus, to: StepStatus): StepStatus {
-  if (!isValidStepTransition(from, to)) {
-    throw new Error(`Invalid step transition: ${from} → ${to}`);
-  }
-  return to;
-}
-
-/** Definition of a single workflow step. */
-export interface WorkflowStep {
-  stepType: string;
-  description: string;
-  requiredInputs: string[];
-  expectedOutputs: string[];
-  skippable: boolean;
-  status: StepStatus;
-}
-
-/** Output produced by a completed workflow step. */
-export interface StepOutput {
-  stepIndex: number;
-  stepType: string;
-  evidence: EvidenceRecord[];
-  rawText?: string;
-  analystOutput?: AnalystOutput;
-  debateOutput?: DebateOutput;
-  parsed?: boolean;
-}
-
-/** Analyst signal direction. */
-export type AnalystSignal = "BUY" | "HOLD" | "SELL";
-
-/** Structured output from a single analyst role. */
-export interface AnalystOutput {
-  role: string;
-  signal: AnalystSignal;
-  conviction: number;
-  thesis: string;
-  evidence: EvidenceRecord[];
-  rawText?: string;
-}
-
-/** Debate side in bull/bear adversarial debate. */
-export type DebateSide = "bull" | "bear";
-
-/** Structured output from a debate step (eval/test only — not used in live path). */
-export interface DebateOutput {
-  side: DebateSide;
-  thesis: string;
-  keyRisk: string;
-  concessions: string[];
-  remainingConviction: number;
-  evidence: EvidenceRecord[];
-  rawText: string;
-}
-
-/** A complete workflow run definition and state. */
-export interface WorkflowRun {
-  runId: string;
-  workflowType: string;
-  steps: WorkflowStep[];
-  currentStepIndex: number;
-  status: RunStatus;
-  stepOutputs: Map<number, StepOutput>;
-  createdAt: string;
-}
-
-/** Create a new workflow run with all steps in pending state. */
-export function createWorkflowRun(
-  runId: string,
-  workflowType: string,
-  stepDefinitions: Omit<WorkflowStep, "status">[],
-): WorkflowRun {
-  return {
-    runId,
-    workflowType,
-    steps: stepDefinitions.map((def) => ({ ...def, status: "pending" as const })),
-    currentStepIndex: 0,
-    status: "pending",
-    stepOutputs: new Map(),
-    createdAt: new Date().toISOString(),
-  };
-}