/**
 * Programmatic entry: load trading recipe and start runtime. Returns handle with stop().
 */
import type { McpTransport } from "../senpi/types.js";
import type { RuntimeHealthStatus, RuntimeSystemState } from "../health/index.js";
import type { ScannerDataProviders } from "../scanners/engine/data-providers.js";
import type { ExternalScannerIngestRequest, ExternalScannerIngestResult } from "../scanners/external-scanner-receiver.js";
import type { ScannerSupervisionSource } from "../scanners/supervision.js";
import type { DslPlugin } from "../dsl/plugin/index.js";
import type { ActionExecutionRecord, ActionFilter, ActionLatestState, ReadActionHistoryOptions } from "../actions/store/index.js";
import type { AuditQueryArgs, AuditQueryResult } from "./audit-query.types.js";
import type { RuntimeConfig } from "./runtime-schema.js";
export interface RunOptions {
    fromPath?: boolean;
    stateDir?: string;
    mcpTransport?: McpTransport;
    apiKey?: string;
    scannerProviders?: ScannerDataProviders;
    /**
     * Stable UUID identifying this runtime install (from the plugin registry).
     * Stamped on spans / propagated to OpenClaw via X-Senpi-Runtime-Id so
     * telemetry can disambiguate multiple installs of the same recipe.
     */
    runtimeId?: string;
}
export interface RuntimeHandle {
    stop(): Promise<void>;
    dsl: DslPlugin | null;
    /**
     * Swap this runtime onto a new recipe in place, without restarting it.
     *
     * State on disk survives — DSL position files, scanner stores, action history — which is the
     * entire reason an update is worth having over a delete-and-recreate. Throws if the new recipe
     * cannot be built; the runtime rolls itself back to the previous one first, except in the case
     * that raises `RuntimeRebuildRollbackFailedError`.
     */
    applyUpdatedConfig(next: RuntimeConfig): Promise<void>;
    /** Wallet address from the recipe's strategy block. */
    wallet: string;
    /**
     * Accept one external scanner ingest request for the handle's bound runtime.
     * The request may update signals, retained context, or both depending on the
     * target scanner's declared outputs.
     */
    ingestExternalScannerData(request: ExternalScannerIngestRequest): Promise<ExternalScannerIngestResult>;
    /**
     * Record a scaffold-reported tick failure for one of this runtime's push-driven
     * external scanners into run telemetry. The scaffold already ran scan() and it
     * failed (threw / timed out / could not persist state), so no signal is ingested
     * — the failed run is accounted so consecutiveErrorCount/lastRunStatus reflect
     * it. Resolves by the configured scanner NAME (the handle owns the address);
     * returns false for an unknown/ineligible scanner or a not-yet-started runtime.
     */
    recordExternalScannerError(scannerName: string, error: {
        type: string;
        error_type?: string;
        message?: string;
        tick_id?: string;
    }): boolean;
    /**
     * Attach the external-scanner supervision fact source (intake liveness clock +
     * process supervisor) for the handle's bound runtime. The scanner module joins
     * these facts onto its health/state rows. Replaces any previously attached source.
     */
    attachSupervisionSource(source: ScannerSupervisionSource): void;
    getHealthStatus(): Promise<RuntimeHealthStatus | null>;
    getSystemState(): Promise<RuntimeSystemState | null>;
    /**
     * Cancel exchange SLs and archive DSL state for all strategies before
     * deleting a runtime.
     */
    teardownDslForRuntimeDeletion(): Promise<void>;
    /**
     * Run an MCP `audit_query` through this runtime's persistent MCP client,
     * scoped to the runtime's own strategy. Resolves wallet → strategyId the
     * first time it is called and caches the result on the handle.
     *
     * @param args  Filters passed straight to the MCP `audit_query` tool.
     *              `resource_type` and `resource_id` are set by the
     *              implementation — caller-supplied values are silently
     *              overwritten. `user_ids` and `usernames` are
     *              server-controlled (defaulting to the API-key user).
     * @param opts  `signal` ties the call to a Fastify request lifetime.
     *              When the signal aborts, the underlying MCP call is
     *              cancelled.
     * @returns     Pass-through MCP `audit_query` response
     *              (`entries[]`, `count`, `total`, `has_more`).
     * @throws      {@link AuditQueryError} with `code: "NOT_FOUND"` when
     *              `listStrategies` returns 0 matches; `code: "UPSTREAM"`
     *              for other MCP failures; `code: "ABORTED"` if the
     *              caller aborts via `opts.signal`.
     */
    auditQuery(args: AuditQueryArgs, opts?: {
        signal?: AbortSignal;
    }): Promise<AuditQueryResult>;
    /**
     * In-memory read of the runtime's internal signal queue depth. Sync —
     * `GET /health` calls it on every probe and must not pay an async
     * round-trip.
     *
     * @returns Number of `scanner:run:complete` items currently waiting in
     *          the FIFO signal queue (single-consumer).
     */
    getSignalQueueDepth(): number;
    /**
     * Return the cached strategy id resolved from this runtime's wallet, or
     * `null` if {@link auditQuery} has not yet been called (or if the first
     * call ended in `NOT_FOUND`).
     *
     * This is synchronous and allocation-free — it reads from the Runtime's
     * in-memory cache set during the first successful {@link auditQuery}.
     * Used by the `/audit` HTTP handler to include `strategyId` in the
     * response without re-issuing a `listStrategies` MCP call.
     *
     * @returns Cached strategy UUID, or `null` if not yet resolved.
     */
    getStrategyId(): string | null;
    /**
     * Latest persisted snapshots for actions registered under this runtime.
     *
     * Backs the `senpi.listActions` gateway method (driven by
     * `openclaw senpi action list`). Reads `latest.json` files for each
     * action instance from the runtime's state directory. Resolves with an
     * empty array when no snapshots exist yet (a fresh runtime that has not
     * executed any action). Filtering is applied by the underlying store.
     *
     * @param filter  Optional `address` and/or `actionName` constraints. When
     *                omitted, every action under the runtime is returned.
     */
    listActionLatestStates(filter?: ActionFilter): Promise<ActionLatestState[]>;
    /**
     * Latest persisted snapshot for a single action instance.
     *
     * Backs the `senpi.getActionState` gateway method (driven by
     * `openclaw senpi action inspect`). Resolves with `null` when no
     * snapshot has been persisted for the given `(address, actionName)` —
     * this is the normal state before the action has executed once.
     */
    getActionLatestState(address: string, actionName: string): Promise<ActionLatestState | null>;
    /**
     * Rolling JSONL execution history for a single action.
     *
     * Backs the `senpi.getActionHistory` gateway method (driven by
     * `openclaw senpi action history` and `action decisions`). Returns the
     * most recent execution records up to `opts.limit`, ordered newest-first
     * by `startedAt`.
     *
     * Use `opts.outcomeFilter = "with_decision"` to keep only rows where the
     * decision engine ran — used by `senpi action decisions` to surface LLM
     * reasoning without paging through pure-rule executions.
     */
    getActionExecutionHistory(address: string, actionName: string, opts?: ReadActionHistoryOptions): Promise<ActionExecutionRecord[]>;
}
/**
 * Load trading recipe from path or content, create Runtime, start it, and return a handle with stop().
 * Programmatic API used by the OpenClaw adapter and standalone CLI.
 */
export declare function run(recipePathOrContent: string, options?: RunOptions): Promise<RuntimeHandle>;
//# sourceMappingURL=run.d.ts.map