loop-sdk 0.1.0

package/dist/flow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow.js","sourceRoot":"","sources":["../src/flow.ts"],"names":[],"mappings":"AASA;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,IAAI,CACxB,GAAY,EACZ,KAAa,EACb,EAAsC,EACtC,EAAE,eAAe,GAAG,KAAK,KAAkB,EAAE;IAE7C,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,CAAC,CAAA;IAEhC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAA;QACzE,MAAM,QAAQ,GAAG,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAE/B,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,QAAQ,CAAC,CAAA;QACpB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,eAAe;gBAAE,MAAM,GAAG,CAAA;YAC/B,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;YAC5D,GAAG,CAAC,GAAG,CAAC,UAAU,KAAK,cAAc,GAAG,EAAE,CAAC,CAAA;QAC7C,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,GAAG,CACvB,GAAY,EACZ,IAAU,EACV,OAAgC,EAAE;IAElC,MAAM,QAAQ,GAAG,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAC/B,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAA;AAC/B,CAAC;AAUD,SAAS,WAAW,CAAC,KAAa;IAChC,MAAM,KAAK,GAAe,EAAE,CAAA;IAC5B,KAAK,MAAM,KAAK,IAAI,KAAK,EAAE,CAAC;QAC1B,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAA;QAC7B,CAAC;aAAM,IAAI,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;YAClC,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;gBACrC,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,CAAA;YAC3C,CAAC;QACH,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAA;QAClC,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+export { Loop, run } from './loop.js';
+export type { Plugin, StepOptions, RunOptions, RunLog, RunHandle, HandleStatus, StepFn, StepResult } from './loop.js';
+export { RetryPlugin } from './plugins/retry.js';
+export type { RetryPluginOptions } from './plugins/retry.js';
+export { Session } from './session.js';
+export type { ClickOptions, ScrollOptions } from './session.js';
+export { Context } from './context.js';
+export type { ContextOptions } from './context.js';
+export { Logger } from './logger.js';
+export type { RunStatus, StepStatus, RunDoc, StepRecord } from './logger.js';
+export { each, sub } from './flow.js';
+export type { Item, EachOptions } from './flow.js';
+export { agent } from './agent.js';
+export type { AgentOptions, AgentResult } from './agent.js';
+export { claudeCli } from './claude-cli.js';
+export type { ClaudeCliOptions, ClaudeCliResult } from './claude-cli.js';
+export { checkpointExists, deleteCheckpoint } from './checkpoint.js';
+export type { Checkpoint } from './checkpoint.js';
+export { loadLoop, loadLoopFile, parseLoopFile, runFile, runFileBackground } from './loopfile.js';
+export type { LoopFileMeta, LoopFileStep, LoopFileSchema, ActionRegistry } from './loopfile.js';
+export { Emitter } from './events.js';
+export type { LoopEvents, LoopStartEvent, LoopCompleteEvent, StepStartEvent, StepCompleteEvent, StepErrorEvent, StepSkipEvent, StepRetryEvent, CheckpointSavedEvent, } from './events.js';
+export { PlaywrightSession } from './providers/playwright.js';
+export { notify, notifyOn } from './notify.js';
+export type { NotifyOptions, NotifyOnOptions } from './notify.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,WAAW,CAAA;AACrC,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAErH,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAChD,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAE5D,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAE/D,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAElD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE5E,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,WAAW,CAAA;AACrC,YAAY,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAElD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE3D,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3C,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAExE,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AACpE,YAAY,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAEjD,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,aAAa,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AACjG,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAE/F,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AACrC,YAAY,EACV,UAAU,EACV,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,cAAc,EACd,oBAAoB,GACrB,MAAM,aAAa,CAAA;AAEpB,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAA;AAE7D,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAC9C,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA"}

package/dist/index.js

@@ -0,0 +1,14 @@
+export { Loop, run } from './loop.js';
+export { RetryPlugin } from './plugins/retry.js';
+export { Session } from './session.js';
+export { Context } from './context.js';
+export { Logger } from './logger.js';
+export { each, sub } from './flow.js';
+export { agent } from './agent.js';
+export { claudeCli } from './claude-cli.js';
+export { checkpointExists, deleteCheckpoint } from './checkpoint.js';
+export { loadLoop, loadLoopFile, parseLoopFile, runFile, runFileBackground } from './loopfile.js';
+export { Emitter } from './events.js';
+export { PlaywrightSession } from './providers/playwright.js';
+export { notify, notifyOn } from './notify.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,WAAW,CAAA;AAGrC,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAGhD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAGtC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAGtC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAGpC,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,WAAW,CAAA;AAGrC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAGlC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAG3C,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAGpE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,aAAa,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAGjG,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAarC,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAA;AAE7D,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA"}

package/dist/logger.d.ts

@@ -0,0 +1,37 @@
+export type StepStatus = 'ok' | 'error' | 'running';
+export type RunStatus = 'completed' | 'failed' | 'running' | 'cancelled';
+export interface StepRecord {
+    name: string;
+    status: StepStatus;
+    result?: unknown;
+    error?: string;
+    startedAt: string;
+    finishedAt?: string;
+}
+export interface RunDoc {
+    loop: string;
+    session: string;
+    startedAt: string;
+    finishedAt: string;
+    status: RunStatus;
+    steps: StepRecord[];
+}
+export declare class Logger {
+    readonly logFile: string | null;
+    private readonly loopName;
+    private readonly sessionId;
+    private readonly startedAt;
+    private readonly steps;
+    private currentStep;
+    constructor(logDir: string | null, loopName: string, sessionId: string);
+    write(_: {
+        msg: string;
+        data?: unknown;
+    }): void;
+    stepStart(name: string): void;
+    stepDone(result?: unknown): void;
+    stepError(err: Error): void;
+    finish(status: RunStatus): void;
+    private flush;
+}
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,OAAO,GAAG,SAAS,CAAA;AACnD,MAAM,MAAM,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,SAAS,GAAG,WAAW,CAAA;AAExE,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,UAAU,CAAA;IAClB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,SAAS,CAAA;IACjB,KAAK,EAAE,UAAU,EAAE,CAAA;CACpB;AAED,qBAAa,MAAM;IACjB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAQ;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAmB;IACzC,OAAO,CAAC,WAAW,CAA0B;gBAEjC,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;IAatE,KAAK,CAAC,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;IAI/C,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAK7B,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI;IAQhC,SAAS,CAAC,GAAG,EAAE,KAAK,GAAG,IAAI;IAQ3B,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI;IAI/B,OAAO,CAAC,KAAK;CAYd"}

package/dist/logger.js

@@ -0,0 +1,64 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export class Logger {
+    logFile;
+    loopName;
+    sessionId;
+    startedAt;
+    steps = [];
+    currentStep = null;
+    constructor(logDir, loopName, sessionId) {
+        this.loopName = loopName;
+        this.sessionId = sessionId;
+        this.startedAt = new Date().toISOString();
+        this.logFile = null;
+        if (logDir) {
+            fs.mkdirSync(logDir, { recursive: true });
+            const ts = this.startedAt.replace(/[:.]/g, '-').replace('T', '_').slice(0, 19);
+            this.logFile = path.join(logDir, `${ts}_${loopName}.json`);
+        }
+    }
+    write(_) {
+        // No-op: stdout output is handled by ctx.log(); structured data is captured in step records
+    }
+    stepStart(name) {
+        this.currentStep = { name, status: 'running', startedAt: new Date().toISOString() };
+        this.steps.push(this.currentStep);
+    }
+    stepDone(result) {
+        if (!this.currentStep)
+            return;
+        this.currentStep.status = 'ok';
+        this.currentStep.result = result ?? null;
+        this.currentStep.finishedAt = new Date().toISOString();
+        this.flush('running');
+    }
+    stepError(err) {
+        if (!this.currentStep)
+            return;
+        this.currentStep.status = 'error';
+        this.currentStep.error = err.message;
+        this.currentStep.finishedAt = new Date().toISOString();
+        this.flush('failed');
+    }
+    finish(status) {
+        this.flush(status);
+    }
+    flush(status) {
+        if (!this.logFile)
+            return;
+        const doc = {
+            loop: this.loopName,
+            session: this.sessionId,
+            startedAt: this.startedAt,
+            finishedAt: new Date().toISOString(),
+            status,
+            steps: this.steps,
+        };
+        try {
+            fs.writeFileSync(this.logFile, JSON.stringify(doc, null, 2));
+        }
+        catch { }
+    }
+}
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

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

package/dist/loop.d.ts

@@ -0,0 +1,199 @@
+import { Context } from './context.js';
+import { type RunStatus } from './logger.js';
+import type { Session } from './session.js';
+import { type LoopEvents } from './events.js';
+export type StepFn = (ctx: Context) => Promise<unknown>;
+export interface StepOptions {
+    /**
+     * Run this function if the step fails (after all retries are exhausted).
+     * If the fallback succeeds, the loop continues rather than aborting.
+     *
+     * @example
+     * loop.step('fetch-live', fetchLive, {
+     *   onError: async (err, ctx) => {
+     *     ctx.set('data', FALLBACK_DATA)
+     *   }
+     * })
+     */
+    onError?: (err: Error, ctx: Context) => Promise<unknown>;
+    /**
+     * Skip this step on failure and continue the loop instead of aborting.
+     * The step is recorded as 'skipped' in the run log.
+     *
+     * @example
+     * loop.step('post-metrics', postMetrics, { skipOnError: true })
+     */
+    skipOnError?: boolean;
+    /**
+     * Retry the step this many additional times before giving up.
+     * Combined with retryDelay / retryBackoff for pacing.
+     *
+     * @example
+     * loop.step('call-api', callApi, { retries: 3, retryDelay: 500, retryBackoff: 'exponential' })
+     */
+    retries?: number;
+    /** Milliseconds to wait before the first retry. Default: 0. */
+    retryDelay?: number;
+    /**
+     * How to scale the delay across retry attempts.
+     * - 'flat'        — same delay every time
+     * - 'linear'      — delay * attempt  (1x, 2x, 3x …)
+     * - 'exponential' — delay * 2^attempt  (1x, 2x, 4x …)
+     *
+     * Default: 'flat'
+     */
+    retryBackoff?: 'flat' | 'linear' | 'exponential';
+}
+export interface Plugin {
+    name: string;
+    hooks?: {
+        /**
+         * Called when a step throws. Return true to signal that the error was
+         * handled and the step should be retried once.
+         */
+        onStepError?: (err: Error, step: {
+            name: string;
+            index: number;
+        }, ctx: Context) => Promise<boolean | void>;
+    };
+}
+export type HandleStatus = 'running' | 'completed' | 'failed' | 'cancelled' | 'paused';
+/**
+ * A handle to a loop running in the background via loop.runBackground().
+ *
+ * @example
+ * const handle = loop.runBackground({ session })
+ *
+ * handle.status           // 'running'
+ * await handle.wait()     // resolves when done
+ * handle.cancel()         // stop — state discarded
+ * handle.pause()          // stop — state saved for resume
+ * handle.resume()         // returns a new handle for the continued run
+ */
+export interface RunHandle {
+    readonly id: string;
+    readonly status: HandleStatus;
+    /** Resolves with the RunLog on completion/cancellation. Rejects on unrecovered step failure. */
+    wait(): Promise<RunLog>;
+    /** Stop after the current step finishes. State is discarded — cannot be resumed. */
+    cancel(): void;
+    /** Stop after the current step finishes. State is saved — resume with handle.resume(). */
+    pause(): void;
+    /**
+     * Resume a paused loop from the last completed step.
+     * Returns a new RunHandle for the continued run.
+     * Throws if the handle is not in 'paused' state.
+     */
+    resume(): RunHandle;
+}
+export interface RunOptions {
+    session: Session;
+    vars?: Record<string, unknown>;
+    logDir?: string | null;
+    startAt?: number | null;
+    stopAt?: number | null;
+    /** AbortSignal to cancel the loop between steps. Use loop.runBackground() for a managed handle. */
+    signal?: AbortSignal | null;
+    checkpointFile?: string | null;
+    resumeFrom?: string | null;
+    keepCheckpointOnSuccess?: boolean;
+    /**
+     * Called when the loop fails — after all step-level retries, fallbacks, and
+     * plugin hooks are exhausted. Use for cleanup, alerting, or partial saves.
+     *
+     * Errors thrown inside onError are swallowed so they don't mask the original failure.
+     *
+     * @example
+     * loop.run({
+     *   session,
+     *   onError: async (err, ctx, failedStep) => {
+     *     await slack.send(`Loop failed at "${failedStep}": ${err.message}`)
+     *     await ctx.get('partialResults')?.save()
+     *   }
+     * })
+     */
+    onError?: (err: Error, ctx: Context, failedStep: string) => Promise<void>;
+}
+export interface StepResult {
+    name: string;
+    status: 'ok' | 'error' | 'skipped' | 'recovered';
+    error?: string;
+}
+export interface RunLog {
+    loop: string;
+    session: string;
+    startedAt: string;
+    finishedAt: string;
+    status: RunStatus;
+    resumedFrom?: string;
+    steps: StepResult[];
+}
+type KnownListener<K extends keyof LoopEvents> = (data: LoopEvents[K]) => void | Promise<void>;
+type AnyListener = (data: unknown) => void | Promise<void>;
+export declare class Loop {
+    readonly name: string;
+    private readonly _steps;
+    private readonly _plugins;
+    private readonly _emitter;
+    constructor(name: string);
+    step(name: string, fn: StepFn, opts?: StepOptions): this;
+    /**
+     * Add a parallel step — all named functions run concurrently.
+     * The step only completes when every sub-step resolves.
+     * Each sub-step's return value is stored in ctx under its name.
+     *
+     * @example
+     * loop.parallel('gather', {
+     *   'fetch-prices':  async (ctx) => { ctx.set('fetch-prices', await getPrice()) },
+     *   'fetch-reviews': async (ctx) => { ctx.set('fetch-reviews', await getReviews()) },
+     * })
+     *
+     * loop.step('summarize', async (ctx) => {
+     *   const prices  = ctx.get('fetch-prices')
+     *   const reviews = ctx.get('fetch-reviews')
+     * })
+     */
+    parallel(name: string, fns: Record<string, StepFn>, opts?: StepOptions): this;
+    /**
+     * Run multiple loops concurrently and return all results.
+     *
+     * @example
+     * const logs = await Loop.runAll([
+     *   { loop: researchLoop, session: sessionA },
+     *   { loop: reportLoop,   session: sessionB },
+     * ])
+     */
+    static runAll(jobs: Array<{
+        loop: Loop;
+    } & RunOptions>): Promise<RunLog[]>;
+    use(plugin: Plugin): this;
+    on<K extends keyof LoopEvents>(event: K, listener: KnownListener<K>): this;
+    on(event: string, listener: AnyListener): this;
+    off<K extends keyof LoopEvents>(event: K, listener: KnownListener<K>): this;
+    off(event: string, listener: AnyListener): this;
+    /** Run steps against an existing Context — used by sub() and each(). */
+    runWith(ctx: Context): Promise<void>;
+    /** Full run: create a fresh Context, execute all steps, return a run log. */
+    run({ session, vars, logDir, startAt, stopAt, checkpointFile, resumeFrom, keepCheckpointOnSuccess, onError, signal, }: RunOptions): Promise<RunLog>;
+    /**
+     * Start the loop in the background and return a RunHandle immediately.
+     * Auto-generates a checkpoint file so pause/resume works without any configuration.
+     *
+     * @example
+     * const handle = loop.runBackground({ session })
+     *
+     * // Pause after the current step, resume later
+     * handle.pause()
+     * const handle2 = handle.resume()
+     * await handle2.wait()
+     *
+     * // Parallel loops
+     * const [log1, log2] = await Promise.all([h1.wait(), h2.wait()])
+     */
+    runBackground(opts: RunOptions): RunHandle;
+    private _runErrorHooks;
+}
+/** Functional API — define and run a loop in one call. */
+export declare function run(name: string, session: Session, fn: StepFn, opts?: Omit<RunOptions, 'session'>): Promise<RunLog>;
+export {};
+//# sourceMappingURL=loop.d.ts.map

package/dist/loop.d.ts.map

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