loop-sdk 0.1.0

package/dist/loopfile.js

@@ -0,0 +1,235 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import yaml from 'js-yaml';
+import { Loop } from './loop.js';
+import { claudeCli } from './claude-cli.js';
+import { notifyOn } from './notify.js';
+// ── Parser ────────────────────────────────────────────────────────────────────
+export function parseLoopFile(content) {
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+    if (!match)
+        throw new Error('.loop file must begin with a YAML front-matter block (---)');
+    const meta = yaml.load(match[1]);
+    if (!meta?.name)
+        throw new Error('.loop front-matter must include a "name" field');
+    const body = match[2];
+    const sections = body.split(/\n(?=## )/).map(s => s.trim()).filter(Boolean);
+    const steps = [];
+    for (const section of sections) {
+        const lines = section.split('\n');
+        const name = lines[0].replace(/^##\s*/, '').trim();
+        const rest = lines.slice(1).join('\n').trim();
+        if (!rest)
+            throw new Error(`Step "${name}" has no configuration`);
+        const stepConfig = yaml.load(rest);
+        if (!stepConfig?.action)
+            throw new Error(`Step "${name}" must have an "action" field`);
+        steps.push({ name, ...stepConfig });
+    }
+    if (steps.length === 0)
+        throw new Error('.loop file has no steps defined');
+    return { meta, steps };
+}
+export function loadLoopFile(filePath) {
+    const content = fs.readFileSync(filePath, 'utf8');
+    return parseLoopFile(content);
+}
+/**
+ * Load a .loop file and return a configured Loop instance ready to run.
+ *
+ * Built-in actions: claudeCli, navigate, screenshot, log, sub, each
+ * Pass `actions` to register custom action handlers.
+ */
+export function loadLoop(filePath, actions = {}) {
+    const schema = loadLoopFile(filePath);
+    const basePath = path.dirname(path.resolve(filePath));
+    const loop = buildLoopFromSteps(schema.meta.name, schema.steps, schema.meta, basePath, actions);
+    // Auto-apply notify config so sub-loops honor their own notification settings
+    const n = schema.meta.notify;
+    if (n) {
+        notifyOn(loop, {
+            title: schema.meta.name ?? loop.name,
+            onStart: Boolean(n.onStart ?? false),
+            onComplete: Boolean(n.onComplete ?? true),
+            onError: Boolean(n.onError ?? true),
+            onStepError: Boolean(n.onStepError ?? false),
+            sound: Boolean(n.sound ?? false),
+        });
+    }
+    return loop;
+}
+/**
+ * Load and run a .loop file in one call.
+ *
+ * @example
+ * await runFile('./research.loop', new PlaywrightSession('run-1'))
+ */
+export async function runFile(filePath, session, opts = {}, actions = {}) {
+    const loop = loadLoop(filePath, actions);
+    return loop.run({ session, ...opts });
+}
+/**
+ * Load and run a .loop file in the background, returning a RunHandle immediately.
+ *
+ * @example
+ * const handle = runFileBackground('./research.loop', session)
+ * const handle2 = runFileBackground('./report.loop', session2)
+ *
+ * const [log1, log2] = await Promise.all([handle.wait(), handle2.wait()])
+ */
+export function runFileBackground(filePath, session, opts = {}, actions = {}) {
+    const loop = loadLoop(filePath, actions);
+    return loop.runBackground({ session, ...opts });
+}
+// ── Internal builders ─────────────────────────────────────────────────────────
+function buildLoopFromSteps(name, steps, meta, basePath, actions) {
+    const loop = new Loop(name);
+    for (const step of steps) {
+        loop.step(step.name, buildStepFn(step, meta, basePath, actions), {
+            retries: step.retries,
+            retryDelay: step.retryDelay,
+            retryBackoff: step.retryBackoff,
+            skipOnError: step.skipOnError || step.onError === 'skip',
+        });
+    }
+    return loop;
+}
+function buildStepFn(step, meta, basePath, actions) {
+    return async (ctx) => {
+        switch (step.action) {
+            case 'claudeCli': {
+                if (!step.prompt)
+                    throw new Error(`Step "${step.name}": claudeCli requires a prompt`);
+                const prompt = interpolate(step.prompt, ctx);
+                const result = await claudeCli(ctx, prompt, { model: step.model ?? meta.model });
+                ctx.set(step.name, result.output);
+                break;
+            }
+            case 'navigate': {
+                const url = interpolate(step.url ?? step.prompt ?? '', ctx);
+                if (!url)
+                    throw new Error(`Step "${step.name}": navigate requires a url or prompt`);
+                await ctx.navigate(url);
+                break;
+            }
+            case 'screenshot': {
+                const buf = await ctx.screenshot();
+                ctx.set(step.name, buf);
+                break;
+            }
+            case 'log': {
+                const msg = interpolate(step.message ?? step.prompt ?? '', ctx);
+                ctx.log(msg);
+                break;
+            }
+            // ── parallel: run inline steps concurrently, wait for all ─────────────
+            case 'parallel': {
+                if (!step.steps?.length) {
+                    throw new Error(`Step "${step.name}": parallel requires inline "steps"`);
+                }
+                await Promise.all(step.steps.map(subStep => buildStepFn(subStep, meta, basePath, actions)(ctx)));
+                break;
+            }
+            // ── sub: run a .loop file as a nested step, sharing context ────────────
+            case 'sub': {
+                if (!step.loop)
+                    throw new Error(`Step "${step.name}": sub requires a "loop" file path`);
+                const loopPath = path.resolve(basePath, step.loop);
+                const subLoop = loadLoop(loopPath, actions);
+                // Resolve any {{ref}} in var values from the parent context before forking
+                const resolvedVars = {};
+                for (const [k, v] of Object.entries(step.vars ?? {})) {
+                    resolvedVars[k] = typeof v === 'string' ? interpolate(v, ctx) : v;
+                }
+                const childCtx = ctx.fork(resolvedVars);
+                await subLoop.runWith(childCtx);
+                break;
+            }
+            // ── each: iterate over items, run a loop per item ───────────────────────
+            case 'each': {
+                const items = resolveItems(step, ctx);
+                const asVar = step.as ?? 'item';
+                // Build the per-item loop (file reference or inline steps)
+                let itemLoop;
+                let lastStepName;
+                if (step.loop) {
+                    const loopPath = path.resolve(basePath, step.loop);
+                    const schema = loadLoopFile(loopPath);
+                    itemLoop = loadLoop(loopPath, actions);
+                    lastStepName = step.output ?? schema.steps[schema.steps.length - 1].name;
+                }
+                else if (step.steps?.length) {
+                    itemLoop = buildLoopFromSteps(`${step.name}-each`, step.steps, meta, basePath, actions);
+                    lastStepName = step.output ?? step.steps[step.steps.length - 1].name;
+                }
+                else {
+                    throw new Error(`Step "${step.name}": each requires a "loop" file path or inline "steps"`);
+                }
+                // Iterate — collect each item's output into an array
+                const results = [];
+                for (let i = 0; i < items.length; i++) {
+                    const item = items[i];
+                    const childCtx = ctx.fork({ [asVar]: item, _index: i, _total: items.length });
+                    try {
+                        await itemLoop.runWith(childCtx);
+                        results.push(childCtx.get(lastStepName));
+                    }
+                    catch (err) {
+                        if (!step.continueOnError)
+                            throw err;
+                        const msg = err instanceof Error ? err.message : String(err);
+                        ctx.log(`each[${i}]: failed — ${msg}`);
+                        results.push(null);
+                    }
+                }
+                ctx.set(step.name, results);
+                break;
+            }
+            default: {
+                const handler = actions[step.action];
+                if (!handler) {
+                    throw new Error(`Step "${step.name}": unknown action "${step.action}". Register it in the actions map passed to loadLoop().`);
+                }
+                const result = await handler(ctx, step);
+                if (result !== undefined)
+                    ctx.set(step.name, result);
+                break;
+            }
+        }
+    };
+}
+// ── Helpers ───────────────────────────────────────────────────────────────────
+function resolveItems(step, ctx) {
+    const raw = step.items;
+    if (Array.isArray(raw))
+        return raw;
+    if (typeof raw === 'string') {
+        const refMatch = raw.match(/^\{\{([\w-]+)\}\}$/);
+        const key = refMatch ? refMatch[1] : raw;
+        const val = ctx.get(key);
+        if (Array.isArray(val))
+            return val;
+        // claudeCli often returns JSON arrays as strings — auto-parse
+        if (typeof val === 'string') {
+            const trimmed = val.trim();
+            if (trimmed.startsWith('[')) {
+                try {
+                    return JSON.parse(trimmed);
+                }
+                catch { }
+            }
+        }
+        throw new Error(`each "${step.name}": "{{${key}}}" must be an array or a JSON array string (got ${typeof val})`);
+    }
+    throw new Error(`Step "${step.name}": each requires an "items" field ({{step-name}} reference or YAML array)`);
+}
+function interpolate(template, ctx) {
+    return template.replace(/\{\{([\w-]+)\}\}/g, (_, key) => {
+        // Check state first (prior step outputs), then vars (per-iteration values from fork())
+        const val = ctx.get(key) ?? ctx.vars[key];
+        if (val == null)
+            return `{{${key}}}`;
+        return typeof val === 'object' ? JSON.stringify(val) : String(val);
+    });
+}
+//# sourceMappingURL=loopfile.js.map

package/dist/loopfile.js.map

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

package/dist/mcp/server.d.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+/**
+ * loop-sdk MCP server — exposes tools that let an AI agent author .loop files.
+ *
+ * Run via stdio transport (compatible with `claude -p --mcp-config`):
+ *   node dist/mcp/server.js
+ *
+ * MCP config example:
+ *   {
+ *     "mcpServers": {
+ *       "loop": {
+ *         "command": "node",
+ *         "args": ["./dist/mcp/server.js"],
+ *         "env": { "LOOP_DIR": "./loops" }
+ *       }
+ *     }
+ *   }
+ *
+ * Tools exposed:
+ *   write_loop   — write a .loop file to disk
+ *   read_loop    — read an existing .loop file
+ *   list_loops   — list .loop files in a directory
+ *   validate_loop — parse a .loop file and report any errors
+ */
+export {};
+//# sourceMappingURL=server.d.ts.map

package/dist/mcp/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;GAsBG"}

package/dist/mcp/server.js

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+/**
+ * loop-sdk MCP server — exposes tools that let an AI agent author .loop files.
+ *
+ * Run via stdio transport (compatible with `claude -p --mcp-config`):
+ *   node dist/mcp/server.js
+ *
+ * MCP config example:
+ *   {
+ *     "mcpServers": {
+ *       "loop": {
+ *         "command": "node",
+ *         "args": ["./dist/mcp/server.js"],
+ *         "env": { "LOOP_DIR": "./loops" }
+ *       }
+ *     }
+ *   }
+ *
+ * Tools exposed:
+ *   write_loop   — write a .loop file to disk
+ *   read_loop    — read an existing .loop file
+ *   list_loops   — list .loop files in a directory
+ *   validate_loop — parse a .loop file and report any errors
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { parseLoopFile } from '../loopfile.js';
+const LOOP_DIR = process.env.LOOP_DIR ?? '.loop';
+const server = new Server({ name: 'loop-sdk', version: '0.1.0' }, { capabilities: { tools: {} } });
+// ── Tool definitions ──────────────────────────────────────────────────────────
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: 'write_loop',
+            description: 'Write a .loop file to disk. Use this to create or update agentic loop definitions. The content must be a valid .loop file (YAML front-matter + ## step sections).',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    filename: {
+                        type: 'string',
+                        description: 'Filename for the .loop file, e.g. "research.loop". Will be created in the LOOP_DIR.',
+                    },
+                    content: {
+                        type: 'string',
+                        description: 'Full .loop file content including YAML front-matter and ## step sections.',
+                    },
+                },
+                required: ['filename', 'content'],
+            },
+        },
+        {
+            name: 'read_loop',
+            description: 'Read the contents of a .loop file.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    filename: { type: 'string', description: 'Filename of the .loop file to read.' },
+                },
+                required: ['filename'],
+            },
+        },
+        {
+            name: 'list_loops',
+            description: 'List all .loop files available in the loop directory.',
+            inputSchema: {
+                type: 'object',
+                properties: {},
+            },
+        },
+        {
+            name: 'validate_loop',
+            description: 'Parse a .loop file and report any syntax or schema errors without running it.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    filename: { type: 'string', description: 'Filename of the .loop file to validate.' },
+                },
+                required: ['filename'],
+            },
+        },
+    ],
+}));
+// ── Tool handlers ─────────────────────────────────────────────────────────────
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const { name, arguments: args } = req.params;
+    const a = (args ?? {});
+    try {
+        switch (name) {
+            case 'write_loop': {
+                const filePath = resolveLoop(a.filename);
+                // Validate before writing
+                parseLoopFile(a.content);
+                fs.mkdirSync(path.dirname(filePath), { recursive: true });
+                fs.writeFileSync(filePath, a.content, 'utf8');
+                return text(`Written: ${filePath}\n\nParsed steps: ${parseLoopFile(a.content).steps.map(s => `  • ${s.name} (${s.action})`).join('\n')}`);
+            }
+            case 'read_loop': {
+                const filePath = resolveLoop(a.filename);
+                if (!fs.existsSync(filePath))
+                    return text(`File not found: ${filePath}`);
+                return text(fs.readFileSync(filePath, 'utf8'));
+            }
+            case 'list_loops': {
+                if (!fs.existsSync(LOOP_DIR))
+                    return text(`Loop directory does not exist: ${LOOP_DIR}`);
+                const files = fs.readdirSync(LOOP_DIR).filter(f => f.endsWith('.loop'));
+                if (files.length === 0)
+                    return text('No .loop files found.');
+                const summaries = files.map(f => {
+                    try {
+                        const schema = parseLoopFile(fs.readFileSync(path.join(LOOP_DIR, f), 'utf8'));
+                        const steps = schema.steps.map(s => `${s.name}(${s.action})`).join(' → ');
+                        return `${f}  [${schema.meta.name}]  ${steps}`;
+                    }
+                    catch {
+                        return `${f}  (parse error)`;
+                    }
+                });
+                return text(summaries.join('\n'));
+            }
+            case 'validate_loop': {
+                const filePath = resolveLoop(a.filename);
+                if (!fs.existsSync(filePath))
+                    return text(`File not found: ${filePath}`);
+                const content = fs.readFileSync(filePath, 'utf8');
+                try {
+                    const schema = parseLoopFile(content);
+                    const lines = [
+                        `✓ Valid — "${schema.meta.name}" (${schema.steps.length} steps)`,
+                        ...schema.steps.map((s, i) => `  ${i + 1}. ${s.name}  action=${s.action}${s.retries ? `  retries=${s.retries}` : ''}${s.skipOnError ? '  skipOnError' : ''}`)
+                    ];
+                    return text(lines.join('\n'));
+                }
+                catch (err) {
+                    return text(`✗ Invalid: ${err.message}`);
+                }
+            }
+            default:
+                return text(`Unknown tool: ${name}`);
+        }
+    }
+    catch (err) {
+        return text(`Error: ${err.message}`);
+    }
+});
+// ── Helpers ───────────────────────────────────────────────────────────────────
+function resolveLoop(filename) {
+    const safe = path.basename(filename); // prevent path traversal
+    return path.resolve(LOOP_DIR, safe.endsWith('.loop') ? safe : `${safe}.loop`);
+}
+function text(content) {
+    return { content: [{ type: 'text', text: content }] };
+}
+// ── Start ─────────────────────────────────────────────────────────────────────
+const transport = new StdioServerTransport();
+await server.connect(transport);
+//# sourceMappingURL=server.js.map

package/dist/mcp/server.js.map

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

package/dist/notify.d.ts

@@ -0,0 +1,43 @@
+import type { Loop } from './loop.js';
+export interface NotifyOptions {
+    /** Notification title. Default: 'loop-sdk'. */
+    title?: string;
+    /** Subtitle shown below the title. */
+    subtitle?: string;
+    /** Play the default notification sound. Default: false. */
+    sound?: boolean;
+}
+/**
+ * Send a macOS notification via osascript. No-op on non-macOS platforms.
+ *
+ * @example
+ * notify('Loop completed in 12.3s', { title: 'My Loop', sound: true })
+ */
+export declare function notify(message: string, opts?: NotifyOptions): void;
+export interface NotifyOnOptions {
+    /** Notify when the loop starts. Default: false. */
+    onStart?: boolean;
+    /** Notify when the loop completes successfully. Default: true. */
+    onComplete?: boolean;
+    /** Notify when the loop fails. Default: true. */
+    onError?: boolean;
+    /** Notify when a step fails (in addition to the loop-level error). Default: false. */
+    onStepError?: boolean;
+    /** Notification title. Default: loop name. */
+    title?: string;
+    /** Play the default notification sound on completion. Default: false. */
+    sound?: boolean;
+}
+/**
+ * Attach macOS notification listeners to a loop. Call before loop.run().
+ *
+ * @example
+ * import { notifyOn } from 'loop-sdk/notify'
+ *
+ * const loop = new Loop('research')
+ * notifyOn(loop, { onComplete: true, onError: true, title: 'Research Loop' })
+ *
+ * await loop.run({ session })
+ */
+export declare function notifyOn(loop: Loop, opts?: NotifyOnOptions): void;
+//# sourceMappingURL=notify.d.ts.map

package/dist/notify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notify.d.ts","sourceRoot":"","sources":["../src/notify.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAGrC,MAAM,WAAW,aAAa;IAC5B,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,aAAkB,GAAG,IAAI,CAYtE;AAID,MAAM,WAAW,eAAe;IAC9B,mDAAmD;IACnD,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,kEAAkE;IAClE,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,iDAAiD;IACjD,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,sFAAsF;IACtF,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,8CAA8C;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,yEAAyE;IACzE,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,GAAE,eAAoB,GAAG,IAAI,CAuCrE"}

package/dist/notify.js

@@ -0,0 +1,68 @@
+import { spawnSync } from 'node:child_process';
+/**
+ * Send a macOS notification via osascript. No-op on non-macOS platforms.
+ *
+ * @example
+ * notify('Loop completed in 12.3s', { title: 'My Loop', sound: true })
+ */
+export function notify(message, opts = {}) {
+    if (process.platform !== 'darwin')
+        return;
+    const title = opts.title ?? 'loop-sdk';
+    const subtitle = opts.subtitle ?? '';
+    const sound = opts.sound ?? false;
+    let script = `display notification ${osa(message)} with title ${osa(title)}`;
+    if (subtitle)
+        script += ` subtitle ${osa(subtitle)}`;
+    if (sound)
+        script += ` sound name "default"`;
+    spawnSync('osascript', ['-e', script], { stdio: 'ignore' });
+}
+/**
+ * Attach macOS notification listeners to a loop. Call before loop.run().
+ *
+ * @example
+ * import { notifyOn } from 'loop-sdk/notify'
+ *
+ * const loop = new Loop('research')
+ * notifyOn(loop, { onComplete: true, onError: true, title: 'Research Loop' })
+ *
+ * await loop.run({ session })
+ */
+export function notifyOn(loop, opts = {}) {
+    const title = opts.title ?? loop.name;
+    const onStart = opts.onStart ?? false;
+    const onComplete = opts.onComplete ?? true;
+    const onError = opts.onError ?? true;
+    const onStepError = opts.onStepError ?? false;
+    const sound = opts.sound ?? false;
+    if (onStart) {
+        loop.on('loop:start', ({ totalSteps }) => {
+            notify(`Starting — ${totalSteps} step${totalSteps === 1 ? '' : 's'}`, { title, subtitle: 'Started' });
+        });
+    }
+    if (onComplete) {
+        loop.on('loop:complete', ({ status, durationMs, stepsCompleted }) => {
+            if (status !== 'completed')
+                return;
+            notify(`Finished in ${(durationMs / 1000).toFixed(1)}s — ${stepsCompleted} steps`, { title, subtitle: 'Completed', sound });
+        });
+    }
+    if (onError) {
+        loop.on('loop:complete', ({ status, durationMs }) => {
+            if (status !== 'failed')
+                return;
+            notify(`Failed after ${(durationMs / 1000).toFixed(1)}s`, { title, subtitle: 'Failed', sound: true });
+        });
+    }
+    if (onStepError) {
+        loop.on('step:error', ({ step, error }) => {
+            notify(error.message, { title, subtitle: `Step failed: ${step}`, sound: true });
+        });
+    }
+}
+// ── helpers ───────────────────────────────────────────────────────────────────
+function osa(s) {
+    return `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, ' ')}"`;
+}
+//# sourceMappingURL=notify.js.map

package/dist/notify.js.map

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

package/dist/plugins/retry.d.ts

@@ -0,0 +1,41 @@
+import type { Plugin } from '../loop.js';
+export interface RetryPluginOptions {
+    /**
+     * Total number of attempts per step (including the first).
+     * e.g. attempts: 3 means 1 initial + 2 retries. Default: 3.
+     */
+    attempts?: number;
+    /** Milliseconds to wait before each retry. Default: 1000. */
+    delay?: 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'
+     */
+    backoff?: 'flat' | 'linear' | 'exponential';
+    /** Only retry if this predicate returns true. Default: always retry. */
+    retryIf?: (err: Error) => boolean;
+}
+/**
+ * Global retry plugin — retries every failing step up to `attempts` times.
+ *
+ * For per-step retry control, use the `retries` / `retryDelay` / `retryBackoff`
+ * options on `loop.step()` instead. Both can coexist: step-level retries run
+ * first, then the plugin gets a chance if the step is still failing.
+ *
+ * @example
+ * import { RetryPlugin } from 'loop-sdk/plugins'
+ *
+ * loop.use(RetryPlugin({ attempts: 3, delay: 1000, backoff: 'exponential' }))
+ *
+ * // Only retry network errors:
+ * loop.use(RetryPlugin({
+ *   attempts: 5,
+ *   delay: 2000,
+ *   retryIf: (err) => err.message.includes('fetch failed'),
+ * }))
+ */
+export declare function RetryPlugin(opts?: RetryPluginOptions): Plugin;
+//# sourceMappingURL=retry.d.ts.map

package/dist/plugins/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/plugins/retry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAExC,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,aAAa,CAAA;IAC3C,wEAAwE;IACxE,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,OAAO,CAAA;CAClC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,WAAW,CAAC,IAAI,GAAE,kBAAuB,GAAG,MAAM,CAwCjE"}