opencandle 0.1.1 → 0.3.0

package/dist/runtime/run-context.d.ts

@@ -0,0 +1,11 @@
+import type { ProviderTracker } from "./provider-tracker.js";
+interface RunContext {
+    providerTracker: ProviderTracker;
+}
+/** Set the active run context. Called by SessionCoordinator at workflow start. */
+export declare function setRunContext(ctx: RunContext): void;
+/** Clear the active run context. Called when a workflow ends or is cancelled. */
+export declare function clearRunContext(): void;
+/** Get the current run's ProviderTracker, or undefined outside a workflow. */
+export declare function getProviderTracker(): ProviderTracker | undefined;
+export {};

package/dist/runtime/run-context.js

@@ -0,0 +1,14 @@
+let activeContext = null;
+/** Set the active run context. Called by SessionCoordinator at workflow start. */
+export function setRunContext(ctx) {
+    activeContext = ctx;
+}
+/** Clear the active run context. Called when a workflow ends or is cancelled. */
+export function clearRunContext() {
+    activeContext = null;
+}
+/** Get the current run's ProviderTracker, or undefined outside a workflow. */
+export function getProviderTracker() {
+    return activeContext?.providerTracker;
+}
+//# sourceMappingURL=run-context.js.map

package/dist/runtime/run-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-context.js","sourceRoot":"","sources":["../../src/runtime/run-context.ts"],"names":[],"mappings":"AAMA,IAAI,aAAa,GAAsB,IAAI,CAAC;AAE5C,kFAAkF;AAClF,MAAM,UAAU,aAAa,CAAC,GAAe;IAC3C,aAAa,GAAG,GAAG,CAAC;AACtB,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,eAAe;IAC7B,aAAa,GAAG,IAAI,CAAC;AACvB,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,kBAAkB;IAChC,OAAO,aAAa,EAAE,eAAe,CAAC;AACxC,CAAC"}

package/dist/runtime/session-coordinator.d.ts

@@ -0,0 +1,47 @@
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { MemoryStorage } from "../memory/index.js";
+import { WorkflowRunner } from "./workflow-runner.js";
+import type { WorkflowDefinition } from "./prompt-step.js";
+type QueueContext = ExtensionCommandContext | {
+    isIdle(): boolean;
+    hasPendingMessages?(): boolean;
+    ui?: {
+        notify(message: string, level?: string): void;
+    };
+};
+/**
+ * Coordinates session lifecycle, memory, workflow execution,
+ * and prompt assembly. The extension delegates to this.
+ */
+export declare class SessionCoordinator {
+    private db;
+    private storage;
+    private memoryManager;
+    private eventLogger;
+    private runner;
+    private providerTracker;
+    private sessionId;
+    constructor();
+    getStorage(): MemoryStorage | null;
+    getRunner(): WorkflowRunner;
+    /** Initialize session: database, memory, event logger, workflow runner. */
+    initSession(sessionId: string): void;
+    /** Run setup flow. */
+    runSetup(pi: ExtensionAPI, ctx: ExtensionContext | ExtensionCommandContext, options: {
+        mode: "startup" | "manual";
+    }): Promise<"ready" | "shutdown" | "cancelled">;
+    /** Extract and persist user preferences from natural language. */
+    extractAndStorePreferences(text: string): void;
+    /** Record a workflow run in storage. */
+    recordWorkflowRun(workflowType: string, entities: object, resolved: object, defaultsUsed: unknown[]): void;
+    /** Build system prompt using composable sections. */
+    buildSystemPrompt(basePrompt: string, workflowType?: string): string;
+    /**
+     * Execute a workflow definition through the WorkflowRunner,
+     * sending prompts via Pi with settlement-based sequencing.
+     */
+    executeWorkflow(pi: ExtensionAPI, definition: WorkflowDefinition, ctx: QueueContext): void;
+    /** Cancel any active workflow. */
+    cancelActiveWorkflow(): void;
+}
+export {};

package/dist/runtime/session-coordinator.js

@@ -0,0 +1,171 @@
+import { initDefaultDatabase, MemoryStorage } from "../memory/index.js";
+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 } from "../prompts/context-builder.js";
+import { getAddonToolDescriptions } from "../tool-kit.js";
+import { toStepDefinitions, promptStepOutput } from "./prompt-step.js";
+const PROMPT_SETTLE_POLL_MS = 25;
+const IMMEDIATE_IDLE_GRACE_MS = 100;
+function hasPendingMessages(ctx) {
+    return ctx.hasPendingMessages?.() ?? false;
+}
+function isReadyForNextPrompt(ctx) {
+    return ctx.isIdle() && !hasPendingMessages(ctx);
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function waitForPromptSettlement(ctx, isCurrentRun) {
+    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 {
+    db = null;
+    storage = null;
+    memoryManager = null;
+    eventLogger = null;
+    runner;
+    providerTracker;
+    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() {
+        return this.storage;
+    }
+    getRunner() {
+        return this.runner;
+    }
+    /** Initialize session: database, memory, event logger, workflow runner. */
+    initSession(sessionId) {
+        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, ctx, options) {
+        return runOpenCandleSetup(pi, ctx, options);
+    }
+    /** Extract and persist user preferences from natural language. */
+    extractAndStorePreferences(text) {
+        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, entities, resolved, defaultsUsed) {
+        this.storage?.insertWorkflowRun({
+            sessionId: this.sessionId,
+            workflowType,
+            inputSlotsJson: JSON.stringify(entities),
+            resolvedSlotsJson: JSON.stringify(resolved),
+            defaultsUsedJson: JSON.stringify(defaultsUsed),
+        });
+    }
+    /** Build system prompt using composable sections. */
+    buildSystemPrompt(basePrompt, workflowType) {
+        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,
+        });
+        return `${basePrompt}\n\n${builder.build()}`;
+    }
+    /**
+     * Execute a workflow definition through the WorkflowRunner,
+     * sending prompts via Pi with settlement-based sequencing.
+     */
+    executeWorkflow(pi, definition, ctx) {
+        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() {
+        clearRunContext();
+        this.runner?.cancel();
+    }
+}
+//# sourceMappingURL=session-coordinator.js.map

package/dist/runtime/session-coordinator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-coordinator.js","sourceRoot":"","sources":["../../src/runtime/session-coordinator.ts"],"names":[],"mappings":"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"}

package/dist/runtime/validation.d.ts

@@ -0,0 +1,44 @@
+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 declare function emptyValidationResult(): ValidationResult;
+/** Check that market-sensitive evidence records have timestamps. */
+export declare function checkTimestamps(evidence: EvidenceRecord[], marketSensitiveLabels: Set<string>): ValidationEntry[];
+/** Check that options expiry dates are in the future. */
+export declare function checkOptionsExpiries(evidence: EvidenceRecord[], today: string): ValidationEntry[];
+/** Check that all required fields have evidence records. */
+export declare function checkRequiredFields(evidence: EvidenceRecord[], requiredLabels: string[]): ValidationEntry[];
+/** Default market-sensitive labels. */
+export declare const DEFAULT_MARKET_SENSITIVE_LABELS: Set<string>;
+/** 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 declare class RuntimeValidator {
+    private readonly config;
+    constructor(config?: ValidatorConfig);
+    /** Run all validation checks and return a combined result. */
+    validate(evidence: EvidenceRecord[]): ValidationResult;
+    /** Format validation results as a summary string for the LLM validation prompt. */
+    formatForLLM(result: ValidationResult): string;
+}
+/** Check that evidence values match expected tool result values. */
+export declare function checkNumberMatch(evidence: EvidenceRecord[], toolResults: Map<string, number>): ValidationEntry[];

package/dist/runtime/validation.js

@@ -0,0 +1,157 @@
+/** Create an empty validation result. */
+export function emptyValidationResult() {
+    return { passes: [], failures: [], warnings: [] };
+}
+/** Check that market-sensitive evidence records have timestamps. */
+export function checkTimestamps(evidence, marketSensitiveLabels) {
+    const warnings = [];
+    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, today) {
+    const failures = [];
+    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, requiredLabels) {
+    const present = new Set(evidence.map((e) => e.label));
+    const failures = [];
+    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",
+]);
+/**
+ * Orchestrates all deterministic validation checks on evidence records.
+ * Runs before LLM-based validation.
+ */
+export class RuntimeValidator {
+    config;
+    constructor(config = {}) {
+        this.config = config;
+    }
+    /** Run all validation checks and return a combined result. */
+    validate(evidence) {
+        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.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) {
+        const lines = ["## 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, toolResults) {
+    const results = [];
+    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;
+}
+//# sourceMappingURL=validation.js.map

package/dist/runtime/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/runtime/validation.ts"],"names":[],"mappings":"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"}

package/dist/runtime/workflow-events.d.ts

@@ -0,0 +1,21 @@
+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" | "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 declare class WorkflowEventLogger {
+    private readonly db;
+    constructor(db: Database.Database);
+    /** Append a workflow event. */
+    log(runId: string, stepIndex: number, eventType: WorkflowEventType, payload?: Record<string, unknown>): void;
+    /** Query all events for a given run ID, ordered by timestamp. */
+    getEventsByRunId(runId: string): WorkflowEvent[];
+}

package/dist/runtime/workflow-events.js

@@ -0,0 +1,31 @@
+/** Append-only workflow event logger backed by SQLite. */
+export class WorkflowEventLogger {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /** Append a workflow event. */
+    log(runId, stepIndex, eventType, payload) {
+        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) {
+        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);
+        return rows.map((r) => ({
+            id: r.id,
+            runId: r.run_id,
+            stepIndex: r.step_index,
+            eventType: r.event_type,
+            payloadJson: r.payload_json,
+            timestamp: r.timestamp,
+        }));
+    }
+}
+//# sourceMappingURL=workflow-events.js.map

package/dist/runtime/workflow-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-events.js","sourceRoot":"","sources":["../../src/runtime/workflow-events.ts"],"names":[],"mappings":"AA6BA,0DAA0D;AAC1D,MAAM,OAAO,mBAAmB;IACD;IAA7B,YAA6B,EAAqB;QAArB,OAAE,GAAF,EAAE,CAAmB;IAAG,CAAC;IAEtD,+BAA+B;IAC/B,GAAG,CACD,KAAa,EACb,SAAiB,EACjB,SAA4B,EAC5B,OAAiC;QAEjC,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACrC,MAAM,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAC7D,IAAI,CAAC,EAAE;aACJ,OAAO,CACN;gCACwB,CACzB;aACA,GAAG,CAAC,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,GAAG,CAAC,CAAC;IACxD,CAAC;IAED,iEAAiE;IACjE,gBAAgB,CAAC,KAAa;QAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE;aACjB,OAAO,CACN,sHAAsH,CACvH;aACA,GAAG,CAAC,KAAK,CAOR,CAAC;QAEL,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACtB,EAAE,EAAE,CAAC,CAAC,EAAE;YACR,KAAK,EAAE,CAAC,CAAC,MAAM;YACf,SAAS,EAAE,CAAC,CAAC,UAAU;YACvB,SAAS,EAAE,CAAC,CAAC,UAA+B;YAC5C,WAAW,EAAE,CAAC,CAAC,YAAY;YAC3B,SAAS,EAAE,CAAC,CAAC,SAAS;SACvB,CAAC,CAAC,CAAC;IACN,CAAC;CACF"}

package/dist/runtime/workflow-runner.d.ts

@@ -0,0 +1,36 @@
+import type { WorkflowRun, StepOutput, WorkflowStep } from "./workflow-types.js";
+import type { WorkflowEventLogger } from "./workflow-events.js";
+import type { ProviderTracker } from "./provider-tracker.js";
+import type { EvidenceRecord } from "./evidence.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;
+}
+/**
+ * Typed workflow execution engine with run IDs, step definitions,
+ * state transitions, cancellation, and event logging.
+ */
+export declare class WorkflowRunner {
+    private readonly eventLogger?;
+    private readonly providerTracker?;
+    private activeRun;
+    constructor(options?: WorkflowRunnerOptions);
+    /** Get the currently active run, if any. */
+    getActiveRun(): WorkflowRun | null;
+    /**
+     * Start a new workflow run. If a run is already active, it is cancelled first.
+     */
+    start(workflowType: string, stepDefinitions: Omit<WorkflowStep, "status">[], executor: StepExecutor): Promise<WorkflowRun>;
+    /** Cancel the active run. */
+    cancel(): void;
+    private executeSteps;
+    private logEvent;
+}