@fiber-pay/runtime 0.1.0-rc.1

package/README.md

@@ -0,0 +1,110 @@
+# @fiber-pay/runtime
+
+Runtime monitor + job orchestration for Fiber (`fnn v0.6.1`).
+
+## Quick start
+
+```bash
+fiber-pay runtime start --daemon --json
+fiber-pay runtime status --json
+```
+
+## Manual payment flow (runtime jobs)
+
+前置：`jq`、`curl`、两边 profile 已有资金（示例 `rt-a` / `rt-b`）。
+
+### 1) 启动两边节点（带 runtime proxy）
+
+```bash
+fiber-pay --profile rt-a config init --network testnet --proxy-port 9729
+fiber-pay --profile rt-b config init --network testnet --rpc-port 9827 --p2p-port 9828 --proxy-port 9829
+
+fiber-pay --profile rt-a node start --json
+fiber-pay --profile rt-b node start --json
+```
+
+### 2) 连接 peer
+
+```bash
+A_MULTIADDR="$(fiber-pay --profile rt-a node status --json | jq -r '.data.multiaddr')"
+B_MULTIADDR="$(fiber-pay --profile rt-b node status --json | jq -r '.data.multiaddr')"
+
+fiber-pay --profile rt-a peer connect "$B_MULTIADDR" --timeout 12 --json
+fiber-pay --profile rt-b peer connect "$A_MULTIADDR" --timeout 12 --json
+```
+
+### 3) 提交 job：open -> invoice -> payment -> shutdown
+
+```bash
+PROXY_A='http://127.0.0.1:9729'
+PROXY_B='http://127.0.0.1:9829'
+PEER_B="$(fiber-pay --profile rt-b node status --json | jq -r '.data.peerId')"
+
+wait_job() {
+  local proxy="$1"; local job_id="$2"
+  while true; do
+    local state="$(curl -fsS "$proxy/jobs/$job_id" | jq -r '.state')"
+    echo "job=$job_id state=$state"
+    case "$state" in succeeded|failed|cancelled) break;; esac
+    sleep 2
+  done
+}
+
+# open channel (200 CKB)
+OPEN_JOB_ID="$(curl -fsS -X POST "$PROXY_A/jobs/channel" -H 'content-type: application/json' \
+  -d "{\"params\":{\"action\":\"open\",\"openChannelParams\":{\"peer_id\":\"$PEER_B\",\"funding_amount\":\"0x2e90edd000\"},\"waitForReady\":true,\"pollIntervalMs\":1500},\"options\":{\"idempotencyKey\":\"manual-open-$(date +%s)\"}}" | jq -r '.id')"
+wait_job "$PROXY_A" "$OPEN_JOB_ID"
+CHANNEL_ID="$(curl -fsS "$PROXY_A/jobs/$OPEN_JOB_ID" | jq -r '.result.channelId')"
+
+# create invoice (5 CKB)
+INVOICE_JOB_ID="$(curl -fsS -X POST "$PROXY_B/jobs/invoice" -H 'content-type: application/json' \
+  -d "{\"params\":{\"action\":\"create\",\"newInvoiceParams\":{\"amount\":\"0x1dcd6500\",\"currency\":\"Fibt\"},\"waitForTerminal\":false,\"pollIntervalMs\":1500},\"options\":{\"idempotencyKey\":\"manual-invoice-$(date +%s)\"}}" | jq -r '.id')"
+wait_job "$PROXY_B" "$INVOICE_JOB_ID"
+INVOICE_ADDRESS="$(curl -fsS "$PROXY_B/jobs/$INVOICE_JOB_ID" | jq -r '.result.invoiceAddress')"
+
+# pay invoice
+PAYMENT_JOB_ID="$(curl -fsS -X POST "$PROXY_A/jobs/payment" -H 'content-type: application/json' \
+  -d "{\"params\":{\"invoice\":\"$INVOICE_ADDRESS\",\"sendPaymentParams\":{\"invoice\":\"$INVOICE_ADDRESS\"}},\"options\":{\"idempotencyKey\":\"manual-pay-$(date +%s)\"}}" | jq -r '.id')"
+wait_job "$PROXY_A" "$PAYMENT_JOB_ID"
+
+# shutdown channel
+SHUTDOWN_JOB_ID="$(curl -fsS -X POST "$PROXY_A/jobs/channel" -H 'content-type: application/json' \
+  -d "{\"params\":{\"action\":\"shutdown\",\"channelId\":\"$CHANNEL_ID\",\"shutdownChannelParams\":{\"channel_id\":\"$CHANNEL_ID\",\"force\":false},\"waitForClosed\":true,\"pollIntervalMs\":1500},\"options\":{\"idempotencyKey\":\"manual-close-$(date +%s)\"}}" | jq -r '.id')"
+wait_job "$PROXY_A" "$SHUTDOWN_JOB_ID"
+
+# inspect payment events
+curl -fsS "$PROXY_A/jobs/$PAYMENT_JOB_ID/events" | jq
+```
+
+## One-command regression (recommended)
+
+```bash
+pnpm e2e:runtime-jobs
+JOB_TIMEOUT_SEC=420 CHANNEL_CLEANUP_TIMEOUT_SEC=120 pnpm e2e:runtime-jobs -- --json
+```
+
+## Handy job commands
+
+```bash
+fiber-pay job list --json
+fiber-pay job get <jobId> --json
+fiber-pay job trace <jobId>
+fiber-pay job events <jobId> --json
+fiber-pay job events <jobId> --with-data
+fiber-pay job cancel <jobId> --json
+fiber-pay logs --source all --tail 80
+fiber-pay logs --source runtime --tail 50
+fiber-pay logs --source runtime --follow
+```
+
+## Persistent logs (for agent debugging)
+
+When started from `fiber-pay node start` or `fiber-pay runtime start`, runtime/fnn logs are persisted to:
+
+- `<data-dir>/logs/fnn.stdout.log`
+- `<data-dir>/logs/fnn.stderr.log`
+- `<data-dir>/logs/runtime.alerts.jsonl`
+
+`<data-dir>/runtime.meta.json` stores these paths so agents can read files directly during troubleshooting.
+
+You can view these files directly via CLI without `cat` using `fiber-pay logs` (alias: `fiber-pay log`).

package/dist/index.d.ts

@@ -0,0 +1,523 @@
+import { ChannelId, Channel, PaymentHash, PeerInfo, OpenChannelParams, ShutdownChannelParams, AcceptChannelParams, AbandonChannelParams, UpdateChannelParams, OpenChannelResult, AcceptChannelResult, NewInvoiceParams, CancelInvoiceParams, SettleInvoiceParams, GetInvoiceResult, SendPaymentParams, FiberRpcClient } from '@fiber-pay/sdk';
+import { EventEmitter } from 'node:events';
+
+type AlertPriority = 'critical' | 'high' | 'medium' | 'low';
+type AlertType = 'channel_state_changed' | 'new_inbound_channel_request' | 'channel_became_ready' | 'channel_closing' | 'incoming_payment_received' | 'invoice_expired' | 'invoice_cancelled' | 'outgoing_payment_completed' | 'outgoing_payment_failed' | 'channel_balance_changed' | 'new_pending_tlc' | 'peer_connected' | 'peer_disconnected' | 'node_offline' | 'node_online' | 'payment_job_started' | 'payment_job_retrying' | 'payment_job_succeeded' | 'payment_job_failed' | 'invoice_job_started' | 'invoice_job_retrying' | 'invoice_job_succeeded' | 'invoice_job_failed' | 'channel_job_started' | 'channel_job_retrying' | 'channel_job_succeeded' | 'channel_job_failed';
+declare const alertTypeValues: AlertType[];
+declare const alertPriorityOrder: Record<AlertPriority, number>;
+interface AlertFilter {
+    limit?: number;
+    minPriority?: AlertPriority;
+    type?: AlertType;
+    source?: string;
+}
+declare function isAlertPriority(value: string): value is AlertPriority;
+declare function isAlertType(value: string): value is AlertType;
+interface Alert<T = unknown> {
+    id: string;
+    type: AlertType;
+    priority: AlertPriority;
+    timestamp: string;
+    source: string;
+    data: T;
+}
+interface AlertInput<T = unknown> {
+    type: AlertType;
+    priority: AlertPriority;
+    source: string;
+    data: T;
+}
+interface TrackedInvoiceState {
+    paymentHash: PaymentHash;
+    status: string;
+    trackedAt: number;
+    updatedAt: number;
+    completedAt?: number;
+}
+interface TrackedPaymentState {
+    paymentHash: PaymentHash;
+    status: string;
+    trackedAt: number;
+    updatedAt: number;
+    completedAt?: number;
+}
+interface ChannelBalanceChangedData {
+    channelId: ChannelId;
+    localBalanceBefore: string;
+    localBalanceAfter: string;
+    remoteBalanceBefore: string;
+    remoteBalanceAfter: string;
+    channel: Channel;
+}
+interface PendingTlcChangedData {
+    channelId: ChannelId;
+    newPendingTlcCount: number;
+    previousPendingTlcCount: number;
+    channel: Channel;
+}
+interface ChannelStateChangedData {
+    channelId: ChannelId;
+    previousState: string;
+    currentState: string;
+    channel: Channel;
+}
+interface PeerEventData {
+    peer: PeerInfo;
+}
+interface RpcHealthData {
+    message: string;
+}
+interface PaymentJobAlertData {
+    jobId: string;
+    idempotencyKey: string;
+    retryCount: number;
+    error?: string;
+    fee?: string;
+}
+interface InvoiceJobAlertData {
+    jobId: string;
+    idempotencyKey: string;
+    retryCount: number;
+    action?: string;
+    status?: string;
+    paymentHash?: `0x${string}`;
+    error?: string;
+}
+interface ChannelJobAlertData {
+    jobId: string;
+    idempotencyKey: string;
+    retryCount: number;
+    action?: string;
+    channelId?: `0x${string}`;
+    error?: string;
+}
+interface AlertBackend {
+    start?(): Promise<void>;
+    send(alert: Alert): Promise<void>;
+    stop?(): Promise<void>;
+}
+
+type JobType = 'payment' | 'invoice' | 'channel';
+type JobState = 'queued' | 'executing' | 'inflight' | 'waiting_retry' | 'invoice_created' | 'invoice_active' | 'invoice_received' | 'invoice_settled' | 'invoice_expired' | 'invoice_cancelled' | 'channel_opening' | 'channel_accepting' | 'channel_abandoning' | 'channel_updating' | 'channel_awaiting_ready' | 'channel_ready' | 'channel_closing' | 'channel_closed' | 'succeeded' | 'failed' | 'cancelled';
+declare const TERMINAL_JOB_STATES: Set<JobState>;
+interface Job<TParams = unknown, TResult = unknown, TType extends JobType = JobType> {
+    id: string;
+    type: TType;
+    state: JobState;
+    params: TParams;
+    result?: TResult;
+    error?: ClassifiedError;
+    retryCount: number;
+    maxRetries: number;
+    nextRetryAt?: number;
+    /** For deduplication — derived from invoice payment_hash or caller-supplied */
+    idempotencyKey: string;
+    createdAt: number;
+    updatedAt: number;
+    completedAt?: number;
+}
+type JobEventType = 'created' | 'executing' | 'inflight' | 'invoice_created' | 'invoice_received' | 'invoice_settled' | 'invoice_expired' | 'invoice_cancelled' | 'channel_opening' | 'channel_accepting' | 'channel_abandoning' | 'channel_updating' | 'channel_awaiting_ready' | 'channel_ready' | 'channel_closing' | 'channel_closed' | 'retry_scheduled' | 'retrying' | 'succeeded' | 'failed' | 'cancelled';
+interface JobEvent {
+    id: string;
+    jobId: string;
+    eventType: JobEventType;
+    fromState?: JobState;
+    toState?: JobState;
+    data?: Record<string, unknown>;
+    createdAt: number;
+}
+interface PaymentJobParams {
+    /** Raw invoice string (if paying by invoice) */
+    invoice?: string;
+    /** SDK send_payment params — merged from invoice or supplied directly */
+    sendPaymentParams: SendPaymentParams;
+}
+interface PaymentJobResult {
+    paymentHash: string;
+    /** Final Fiber payment status: Success | Failed */
+    status: string;
+    /** Fee in shannon (hex string from Fiber) */
+    fee: string;
+    failedError?: string;
+}
+type PaymentJob = Job<PaymentJobParams, PaymentJobResult, 'payment'>;
+type InvoiceJobAction = 'create' | 'watch' | 'cancel' | 'settle';
+interface InvoiceJobParams {
+    action: InvoiceJobAction;
+    newInvoiceParams?: NewInvoiceParams;
+    getInvoicePaymentHash?: `0x${string}`;
+    cancelInvoiceParams?: CancelInvoiceParams;
+    settleInvoiceParams?: SettleInvoiceParams;
+    /** Wait for lifecycle transitions to complete before succeeding */
+    waitForTerminal?: boolean;
+    /** Poll interval while waiting for invoice state changes */
+    pollIntervalMs?: number;
+}
+interface InvoiceJobResult {
+    paymentHash?: `0x${string}`;
+    invoiceAddress?: string;
+    status?: GetInvoiceResult['status'];
+    invoice?: GetInvoiceResult['invoice'];
+}
+type InvoiceJob = Job<InvoiceJobParams, InvoiceJobResult, 'invoice'>;
+type ChannelJobAction = 'open' | 'shutdown' | 'accept' | 'abandon' | 'update';
+interface ChannelJobParams {
+    action: ChannelJobAction;
+    openChannelParams?: OpenChannelParams;
+    shutdownChannelParams?: ShutdownChannelParams;
+    acceptChannelParams?: AcceptChannelParams;
+    abandonChannelParams?: AbandonChannelParams;
+    updateChannelParams?: UpdateChannelParams;
+    /** Optional peer filter for locating channel after open */
+    peerId?: string;
+    /** Optional channel id to wait for */
+    channelId?: `0x${string}`;
+    waitForReady?: boolean;
+    waitForClosed?: boolean;
+    pollIntervalMs?: number;
+}
+interface ChannelJobResult {
+    temporaryChannelId?: OpenChannelResult['temporary_channel_id'];
+    acceptedChannelId?: AcceptChannelResult['channel_id'];
+    channelId?: `0x${string}`;
+    state?: string;
+}
+type ChannelJob = Job<ChannelJobParams, ChannelJobResult, 'channel'>;
+type RuntimeJob = PaymentJob | InvoiceJob | ChannelJob;
+type ErrorCategory = 'no_route' | 'insufficient_balance' | 'invoice_expired' | 'invoice_cancelled' | 'peer_offline' | 'timeout' | 'temporary_failure' | 'amount_too_large' | 'invalid_payment' | 'unknown';
+interface ClassifiedError {
+    category: ErrorCategory;
+    retryable: boolean;
+    message: string;
+    rawError?: string;
+}
+interface RetryPolicy {
+    maxRetries: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+    backoffMultiplier: number;
+    jitterMs: number;
+}
+interface JobFilter {
+    type?: JobType;
+    state?: JobState | JobState[];
+    limit?: number;
+    offset?: number;
+}
+
+interface StdoutAlertConfig {
+    type: 'stdout';
+}
+interface WebhookAlertConfig {
+    type: 'webhook';
+    url: string;
+    timeoutMs?: number;
+    headers?: Record<string, string>;
+}
+interface WebsocketAlertConfig {
+    type: 'websocket';
+    listen: string;
+}
+interface FileAlertConfig {
+    type: 'file';
+    path: string;
+}
+type AlertBackendConfig = StdoutAlertConfig | WebhookAlertConfig | WebsocketAlertConfig | FileAlertConfig;
+interface RuntimeConfig {
+    fiberRpcUrl: string;
+    channelPollIntervalMs: number;
+    invoicePollIntervalMs: number;
+    paymentPollIntervalMs: number;
+    peerPollIntervalMs: number;
+    healthPollIntervalMs: number;
+    includeClosedChannels: boolean;
+    completedItemTtlSeconds: number;
+    requestTimeoutMs: number;
+    alerts: AlertBackendConfig[];
+    proxy: {
+        enabled: boolean;
+        listen: string;
+    };
+    storage: {
+        stateFilePath: string;
+        flushIntervalMs: number;
+        maxAlertHistory: number;
+    };
+    jobs: {
+        /** Enable the payment job execution engine. Default: false */
+        enabled: boolean;
+        /** Path to the SQLite file for job persistence. Default: derived from storage.stateFilePath */
+        dbPath: string;
+        maxConcurrentJobs: number;
+        schedulerIntervalMs: number;
+        retryPolicy: RetryPolicy;
+    };
+}
+type RuntimeConfigInput = Omit<Partial<RuntimeConfig>, 'proxy' | 'storage' | 'jobs'> & {
+    proxy?: Partial<RuntimeConfig['proxy']>;
+    storage?: Partial<RuntimeConfig['storage']>;
+    jobs?: Partial<RuntimeConfig['jobs']>;
+};
+declare const defaultRuntimeConfig: RuntimeConfig;
+declare function createRuntimeConfig(input?: RuntimeConfigInput): RuntimeConfig;
+declare function parseListenAddress(listen: string): {
+    host: string;
+    port: number;
+};
+
+declare class FiberMonitorService extends EventEmitter {
+    private readonly config;
+    private readonly startedAt;
+    private readonly client;
+    private readonly store;
+    private readonly alerts;
+    private readonly monitors;
+    private readonly proxy;
+    private readonly jobStore;
+    private readonly jobManager;
+    private running;
+    constructor(configInput?: RuntimeConfigInput);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    getStatus(): {
+        startedAt: string;
+        proxyListen: string;
+        targetUrl: string;
+        running: boolean;
+    };
+    listAlerts(filters?: AlertFilter): Alert[];
+    listTrackedInvoices(): TrackedInvoiceState[];
+    listTrackedPayments(): TrackedPaymentState[];
+    trackInvoice(paymentHash: `0x${string}`): void;
+    trackPayment(paymentHash: `0x${string}`): void;
+    private createAlertBackends;
+    private wireJobAlerts;
+    private emitJobAlert;
+    private toJobAlertType;
+    private toJobAlertData;
+    private trackJobArtifacts;
+    private extractPaymentHash;
+    private extractInvoiceHash;
+    private extractChannelId;
+    private normalizeHash;
+}
+
+interface RuntimeBootstrap {
+    service: FiberMonitorService;
+    stop: () => Promise<void>;
+    waitForShutdownSignal: () => Promise<NodeJS.Signals>;
+}
+declare function startRuntimeService(configInput?: RuntimeConfigInput): Promise<RuntimeBootstrap>;
+
+interface RpcMonitorProxyConfig {
+    listen: string;
+    targetUrl: string;
+}
+interface RpcMonitorProxyStatus {
+    startedAt: string;
+    proxyListen: string;
+    targetUrl: string;
+    running: boolean;
+}
+interface RpcMonitorProxyDeps {
+    onInvoiceTracked: (paymentHash: string) => void;
+    onPaymentTracked: (paymentHash: string) => void;
+    listTrackedInvoices: () => TrackedInvoiceState[];
+    listTrackedPayments: () => TrackedPaymentState[];
+    listAlerts: (filters?: AlertFilter) => Alert[];
+    getStatus: () => RpcMonitorProxyStatus;
+    createPaymentJob?: (params: PaymentJobParams, options?: {
+        idempotencyKey?: string;
+        maxRetries?: number;
+    }) => Promise<RuntimeJob>;
+    createInvoiceJob?: (params: InvoiceJobParams, options?: {
+        idempotencyKey?: string;
+        maxRetries?: number;
+    }) => Promise<RuntimeJob>;
+    createChannelJob?: (params: ChannelJobParams, options?: {
+        idempotencyKey?: string;
+        maxRetries?: number;
+        reuseTerminal?: boolean;
+    }) => Promise<RuntimeJob>;
+    getJob?: (id: string) => RuntimeJob | undefined;
+    listJobs?: (filter?: JobFilter) => RuntimeJob[];
+    cancelJob?: (id: string) => void;
+    listJobEvents?: (jobId: string) => unknown[];
+}
+
+declare class RpcMonitorProxy {
+    private readonly config;
+    private readonly deps;
+    private server;
+    constructor(config: RpcMonitorProxyConfig, deps: RpcMonitorProxyDeps);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private handleRequest;
+}
+
+interface Store {
+    load(): Promise<void>;
+    flush(): Promise<void>;
+    startAutoFlush(): void;
+    stopAutoFlush(): void;
+    pruneCompleted(ttlMs: number): void;
+    getChannelSnapshot(): Channel[];
+    setChannelSnapshot(channels: Channel[]): void;
+    getPeerSnapshot(): PeerInfo[];
+    setPeerSnapshot(peers: PeerInfo[]): void;
+    addTrackedInvoice(hash: PaymentHash, status?: string): void;
+    listTrackedInvoices(): TrackedInvoiceState[];
+    getTrackedInvoice(hash: PaymentHash): TrackedInvoiceState | undefined;
+    updateTrackedInvoice(hash: PaymentHash, status: string): void;
+    addTrackedPayment(hash: PaymentHash, status?: string): void;
+    listTrackedPayments(): TrackedPaymentState[];
+    getTrackedPayment(hash: PaymentHash): TrackedPaymentState | undefined;
+    updateTrackedPayment(hash: PaymentHash, status: string): void;
+    addAlert(alert: Alert): void;
+    listAlerts(filters?: AlertFilter): Alert[];
+}
+
+interface MemoryStoreConfig {
+    stateFilePath: string;
+    flushIntervalMs: number;
+    maxAlertHistory: number;
+}
+declare class MemoryStore implements Store {
+    private readonly config;
+    private channelSnapshot;
+    private peerSnapshot;
+    private trackedInvoices;
+    private trackedPayments;
+    private alerts;
+    private flushTimer;
+    constructor(config: MemoryStoreConfig);
+    load(): Promise<void>;
+    flush(): Promise<void>;
+    startAutoFlush(): void;
+    stopAutoFlush(): void;
+    pruneCompleted(ttlMs: number): void;
+    getChannelSnapshot(): Channel[];
+    setChannelSnapshot(channels: Channel[]): void;
+    getPeerSnapshot(): PeerInfo[];
+    setPeerSnapshot(peers: PeerInfo[]): void;
+    addTrackedInvoice(hash: PaymentHash, status?: string): void;
+    listTrackedInvoices(): TrackedInvoiceState[];
+    getTrackedInvoice(hash: PaymentHash): TrackedInvoiceState | undefined;
+    updateTrackedInvoice(hash: PaymentHash, status: string): void;
+    addTrackedPayment(hash: PaymentHash, status?: string): void;
+    listTrackedPayments(): TrackedPaymentState[];
+    getTrackedPayment(hash: PaymentHash): TrackedPaymentState | undefined;
+    updateTrackedPayment(hash: PaymentHash, status: string): void;
+    addAlert(alert: Alert): void;
+    listAlerts(filters?: AlertFilter): Alert[];
+}
+
+declare class SqliteJobStore {
+    private readonly db;
+    constructor(dbPath: string);
+    private runMigrations;
+    createJob<P, R>(job: Omit<Job<P, R>, 'id' | 'createdAt' | 'updatedAt'>): Job<P, R>;
+    updateJob<P, R>(id: string, updates: Partial<Job<P, R>>): Job<P, R>;
+    getJob<P = unknown, R = unknown>(id: string): Job<P, R> | undefined;
+    getJobByIdempotencyKey<P = unknown, R = unknown>(key: string): Job<P, R> | undefined;
+    listJobs<P = unknown, R = unknown>(filter?: JobFilter): Job<P, R>[];
+    deleteJob(id: string): void;
+    /** Return jobs that are ready to be retried right now. */
+    getRetryableJobs<P = unknown, R = unknown>(now?: number): Job<P, R>[];
+    /** Return jobs in non-terminal states (for recovery after daemon restart). */
+    getInProgressJobs<P = unknown, R = unknown>(): Job<P, R>[];
+    addJobEvent(jobId: string, eventType: JobEventType, fromState?: JobState, toState?: JobState, data?: Record<string, unknown>): JobEvent;
+    listJobEvents(jobId: string): JobEvent[];
+    close(): void;
+    private rowToJob;
+}
+
+interface JobManagerEvents {
+    'job:created': [job: RuntimeJob];
+    'job:state_changed': [job: RuntimeJob, from: JobState];
+    'job:succeeded': [job: RuntimeJob];
+    'job:failed': [job: RuntimeJob];
+    'job:cancelled': [job: RuntimeJob];
+}
+interface JobManagerConfig {
+    schedulerIntervalMs?: number;
+    maxConcurrentJobs?: number;
+    retryPolicy?: RetryPolicy;
+}
+declare class JobManager extends EventEmitter<JobManagerEvents> {
+    private readonly rpc;
+    private readonly store;
+    private readonly retryPolicy;
+    private readonly schedulerIntervalMs;
+    private readonly maxConcurrentJobs;
+    private running;
+    private schedulerTimer;
+    private readonly active;
+    constructor(rpc: FiberRpcClient, store: SqliteJobStore, config?: JobManagerConfig);
+    ensurePayment(params: PaymentJobParams, options?: {
+        idempotencyKey?: string;
+        maxRetries?: number;
+    }): Promise<PaymentJob>;
+    manageInvoice(params: InvoiceJobParams, options?: {
+        idempotencyKey?: string;
+        maxRetries?: number;
+        reuseTerminal?: boolean;
+    }): Promise<InvoiceJob>;
+    manageChannel(params: ChannelJobParams, options?: {
+        idempotencyKey?: string;
+        maxRetries?: number;
+        reuseTerminal?: boolean;
+    }): Promise<ChannelJob>;
+    getJob(id: string): RuntimeJob | undefined;
+    listJobs(filter?: JobFilter): RuntimeJob[];
+    cancelJob(id: string): void;
+    start(): void;
+    stop(): Promise<void>;
+    private createOrReuseJob;
+    private tick;
+    private schedule;
+    private recover;
+    private execute;
+    private buildEventData;
+}
+
+type MachineEvent = 'send_issued' | 'payment_inflight' | 'payment_success' | 'payment_failed_retryable' | 'payment_failed_permanent' | 'invoice_created' | 'invoice_received' | 'invoice_settled' | 'invoice_expired' | 'invoice_cancelled' | 'channel_opening' | 'channel_accepting' | 'channel_abandoning' | 'channel_updating' | 'channel_closing' | 'channel_ready' | 'channel_closed' | 'channel_failed' | 'retry_delay_elapsed' | 'cancel';
+interface Transition {
+    from: JobState | JobState[];
+    event: MachineEvent;
+    to: JobState;
+}
+declare class JobStateMachine {
+    private readonly table;
+    constructor(transitions: Transition[]);
+    transition(current: JobState, event: MachineEvent): JobState | null;
+    isTerminal(state: JobState): boolean;
+}
+declare const paymentStateMachine: JobStateMachine;
+
+/**
+ * Classify an RPC / job failure into a structured error.
+ *
+ * `failedError` is the raw `failed_error` string from Fiber's `get_payment` response.
+ * `error` is any caught JS exception.
+ */
+declare function classifyRpcError(error: unknown, failedError?: string): ClassifiedError;
+
+declare const defaultPaymentRetryPolicy: RetryPolicy;
+/**
+ * Decide whether a job should be retried given its error and current retry count.
+ */
+declare function shouldRetry(error: ClassifiedError, retryCount: number, policy: RetryPolicy): boolean;
+/**
+ * Compute the next retry delay using exponential backoff with random jitter.
+ * retryCount is the number of retries already attempted (0-based before this retry).
+ */
+declare function computeRetryDelay(retryCount: number, policy: RetryPolicy): number;
+
+interface FormatRuntimeAlertOptions {
+    color?: 'auto' | 'always' | 'never';
+    prefix?: string;
+}
+declare function formatRuntimeAlert(alert: Alert, options?: FormatRuntimeAlertOptions): string;
+
+export { type Alert, type AlertBackend, type AlertBackendConfig, type AlertFilter, type AlertInput, type AlertPriority, type AlertType, type ChannelBalanceChangedData, type ChannelJob, type ChannelJobAction, type ChannelJobAlertData, type ChannelJobParams, type ChannelJobResult, type ChannelStateChangedData, type ClassifiedError, type ErrorCategory, FiberMonitorService, type FileAlertConfig, type InvoiceJob, type InvoiceJobAction, type InvoiceJobAlertData, type InvoiceJobParams, type InvoiceJobResult, type Job, type JobEvent, type JobEventType, type JobFilter, JobManager, type JobState, type JobType, MemoryStore, type PaymentJob, type PaymentJobAlertData, type PaymentJobParams, type PaymentJobResult, type PeerEventData, type PendingTlcChangedData, type RetryPolicy, type RpcHealthData, RpcMonitorProxy, type RuntimeConfig, type RuntimeConfigInput, type RuntimeJob, SqliteJobStore, type StdoutAlertConfig, TERMINAL_JOB_STATES, type TrackedInvoiceState, type TrackedPaymentState, type WebhookAlertConfig, type WebsocketAlertConfig, alertPriorityOrder, alertTypeValues, classifyRpcError, computeRetryDelay, createRuntimeConfig, defaultPaymentRetryPolicy, defaultRuntimeConfig, formatRuntimeAlert, isAlertPriority, isAlertType, parseListenAddress, paymentStateMachine, shouldRetry, startRuntimeService };