loop-sdk 0.1.0

package/dist/checkpoint.js

@@ -0,0 +1,20 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export function writeCheckpoint(file, data) {
+    fs.mkdirSync(path.dirname(path.resolve(file)), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(data, null, 2));
+}
+export function readCheckpoint(file) {
+    const raw = fs.readFileSync(file, 'utf8');
+    return JSON.parse(raw);
+}
+export function checkpointExists(file) {
+    return fs.existsSync(file);
+}
+export function deleteCheckpoint(file) {
+    try {
+        fs.unlinkSync(file);
+    }
+    catch { }
+}
+//# sourceMappingURL=checkpoint.js.map

package/dist/checkpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint.js","sourceRoot":"","sources":["../src/checkpoint.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAA;AACxB,OAAO,IAAI,MAAM,WAAW,CAAA;AAc5B,MAAM,UAAU,eAAe,CAAC,IAAY,EAAE,IAAgB;IAC5D,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IACnE,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAA;AACvD,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;IACzC,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAe,CAAA;AACtC,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAA;AAC5B,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,IAAI,CAAC;QAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAA;IAAC,CAAC;IAAC,MAAM,CAAC,CAAA,CAAC;AACtC,CAAC"}

package/dist/claude-cli.d.ts

@@ -0,0 +1,35 @@
+import type { Context } from './context.js';
+export interface ClaudeCliOptions {
+    /** Claude model name, passed as --model. Defaults to the CLI's configured default. */
+    model?: string;
+    /** Attach a screenshot of the current browser state before invoking claude. */
+    screenshot?: boolean;
+    /** Restrict the AI to specific MCP tool names. */
+    tools?: string[];
+    /** Subprocess timeout in milliseconds. Default: 240000 (4 min). */
+    timeout?: number;
+    /** Number of retry attempts on network errors. Default: 3. */
+    retries?: number;
+}
+export interface ClaudeCliResult {
+    ok: true;
+    output: string;
+}
+/**
+ * claudeCli — spawn `claude -p` as a loop step.
+ *
+ * Unlike agent(), which calls a provider directly, claudeCli() delegates the
+ * entire tool-use loop to the Claude Code CLI subprocess. Use this when you
+ * want Claude's built-in retry logic, permission model, and MCP handling.
+ *
+ * Requires `claude` to be installed and on PATH.
+ * If ctx.session.mcpUrl is set, claude gets browser tool access via --mcp-config.
+ *
+ * @example
+ * await claudeCli(ctx, 'Fill out the visible form fields.', {
+ *   screenshot: true,
+ *   model: 'claude-opus-4-8',
+ * })
+ */
+export declare function claudeCli(ctx: Context, prompt: string, { model, screenshot, tools, timeout, retries, }?: ClaudeCliOptions): Promise<ClaudeCliResult>;
+//# sourceMappingURL=claude-cli.d.ts.map

package/dist/claude-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-cli.d.ts","sourceRoot":"","sources":["../src/claude-cli.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAE3C,MAAM,WAAW,gBAAgB;IAC/B,sFAAsF;IACtF,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,+EAA+E;IAC/E,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,IAAI,CAAA;IACR,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,SAAS,CAC7B,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,MAAM,EACd,EACE,KAAK,EACL,UAAkB,EAClB,KAAU,EACV,OAAiB,EACjB,OAAW,GACZ,GAAE,gBAAqB,GACvB,OAAO,CAAC,eAAe,CAAC,CAyE1B"}

package/dist/claude-cli.js

@@ -0,0 +1,135 @@
+import { spawn } from 'node:child_process';
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+/**
+ * claudeCli — spawn `claude -p` as a loop step.
+ *
+ * Unlike agent(), which calls a provider directly, claudeCli() delegates the
+ * entire tool-use loop to the Claude Code CLI subprocess. Use this when you
+ * want Claude's built-in retry logic, permission model, and MCP handling.
+ *
+ * Requires `claude` to be installed and on PATH.
+ * If ctx.session.mcpUrl is set, claude gets browser tool access via --mcp-config.
+ *
+ * @example
+ * await claudeCli(ctx, 'Fill out the visible form fields.', {
+ *   screenshot: true,
+ *   model: 'claude-opus-4-8',
+ * })
+ */
+export async function claudeCli(ctx, prompt, { model, screenshot = false, tools = [], timeout = 240_000, retries = 3, } = {}) {
+    const finalPrompt = `${prompt}
+
+At the very end of your response, on its own line, write exactly one of:
+RESULT: ok
+RESULT: failed — <brief reason>
+
+Use "failed" if you could not complete the task.`;
+    const args = ['-p', finalPrompt, '--dangerously-skip-permissions'];
+    if (model)
+        args.push('--model', model);
+    if (tools.length)
+        args.push('--allowedTools', ...tools);
+    if (ctx.session?.mcpUrl) {
+        const mcpConfig = {
+            mcpServers: {
+                browser: { type: 'http', url: ctx.session.mcpUrl },
+            },
+        };
+        const configFile = join(tmpdir(), `loop-mcp-${ctx.session.id}-${Date.now()}.json`);
+        writeFileSync(configFile, JSON.stringify(mcpConfig));
+        args.push('--mcp-config', configFile);
+    }
+    if (screenshot && ctx.session?.screenshot) {
+        const imgBytes = await ctx.session.screenshot();
+        const shotFile = join(tmpdir(), `loop-shot-${ctx.session.id}-${Date.now()}.jpg`);
+        writeFileSync(shotFile, imgBytes);
+        args.push(shotFile);
+    }
+    let raw = '';
+    let lastError = '';
+    for (let attempt = 1; attempt <= retries; attempt++) {
+        if (ctx.signal?.aborted)
+            throw new Error('cancelled');
+        const result = await spawnAsync('claude', args, { timeout, cwd: tmpdir(), signal: ctx.signal });
+        if (result.aborted)
+            throw new Error('cancelled');
+        if (!result.error && result.exitCode === 0) {
+            raw = result.stdout.trim();
+            break;
+        }
+        const errMsg = result.error?.message ?? result.error?.code ?? `exit ${result.exitCode}`;
+        lastError = errMsg;
+        if (attempt < retries && isRetryable(errMsg)) {
+            ctx.log(`claudeCli: retry ${attempt}/${retries} — ${errMsg.slice(0, 80)}`);
+            await sleep(3000 * attempt);
+        }
+        else {
+            break;
+        }
+    }
+    if (!raw && lastError) {
+        throw new Error(`claude CLI failed (${lastError})`);
+    }
+    const statusLine = raw.match(/^RESULT:\s*(ok|failed.*)$/im);
+    if (statusLine?.[1] && !statusLine[1].toLowerCase().startsWith('ok')) {
+        throw new Error(`claude reported: ${statusLine[1].replace(/^failed\s*[-—]\s*/i, '')}`);
+    }
+    // Strip the RESULT: signal line before returning — it's a protocol marker, not content
+    const output = raw.replace(/\n*^RESULT:\s*(ok|failed.*)$/im, '').trim();
+    if (output)
+        ctx.log(`claude: ${output.split('\n')[0].slice(0, 120)}${output.includes('\n') ? ' …' : ''}`);
+    return { ok: true, output };
+}
+function isRetryable(msg) {
+    return ['fetch failed', 'ECONNRESET', 'ECONNREFUSED', 'ETIMEDOUT'].some(s => msg.includes(s));
+}
+function sleep(ms) {
+    return new Promise(r => setTimeout(r, ms));
+}
+function spawnAsync(cmd, args, opts) {
+    return new Promise(resolve => {
+        const proc = spawn(cmd, args, { cwd: opts.cwd });
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        let aborted = false;
+        const timeoutId = setTimeout(() => {
+            if (!settled) {
+                settled = true;
+                proc.kill('SIGTERM');
+                resolve({ stdout, stderr, exitCode: null, error: Object.assign(new Error('ETIMEDOUT'), { code: 'ETIMEDOUT' }), aborted: false });
+            }
+        }, opts.timeout);
+        const onAbort = () => {
+            if (!settled) {
+                settled = true;
+                aborted = true;
+                clearTimeout(timeoutId);
+                proc.kill('SIGTERM');
+                resolve({ stdout, stderr, exitCode: null, aborted: true });
+            }
+        };
+        opts.signal?.addEventListener('abort', onAbort, { once: true });
+        proc.stdout?.on('data', (d) => { stdout += d.toString(); });
+        proc.stderr?.on('data', (d) => { stderr += d.toString(); });
+        proc.on('error', (err) => {
+            if (!settled) {
+                settled = true;
+                clearTimeout(timeoutId);
+                opts.signal?.removeEventListener('abort', onAbort);
+                resolve({ stdout, stderr, exitCode: null, error: err, aborted });
+            }
+        });
+        proc.on('close', (code) => {
+            if (!settled) {
+                settled = true;
+                clearTimeout(timeoutId);
+                opts.signal?.removeEventListener('abort', onAbort);
+                resolve({ stdout, stderr, exitCode: code, aborted });
+            }
+        });
+    });
+}
+//# sourceMappingURL=claude-cli.js.map

package/dist/claude-cli.js.map

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

package/dist/context.d.ts

@@ -0,0 +1,53 @@
+import type { Session, ClickOptions, ScrollOptions } from './session.js';
+import type { Logger } from './logger.js';
+import type { Emitter } from './events.js';
+export interface ContextOptions {
+    session: Session;
+    vars?: Record<string, unknown>;
+    state?: Map<string, unknown>;
+    logger?: Logger | null;
+    checkpointFile?: string | null;
+    emitter?: Emitter | null;
+    signal?: AbortSignal | null;
+}
+export declare class Context {
+    readonly session: Session;
+    readonly vars: Record<string, unknown>;
+    readonly signal: AbortSignal | null;
+    private readonly _state;
+    private readonly _logger;
+    _emitter: Emitter | null;
+    /** Set by the Loop runner — enables ctx.saveCheckpoint(). */
+    _checkpointFile: string | null;
+    _loopName: string;
+    _completedSteps: string[];
+    _lastCompletedIndex: number;
+    constructor({ session, vars, state, logger, checkpointFile, emitter, signal, }: ContextOptions);
+    get<T = unknown>(key: string): T | undefined;
+    set(key: string, value: unknown): this;
+    has(key: string): boolean;
+    snapshot(): Record<string, unknown>;
+    /**
+     * Emit a custom event from inside a step. Listeners on the Loop will receive
+     * it and can block the step until they complete (useful for human-in-the-loop
+     * gates, approval flows, or metrics).
+     *
+     * @example
+     * loop.step('draft', async (ctx) => {
+     *   const text = await generateDraft(ctx)
+     *   await ctx.emit('draft:ready', { text })  // waits for approval listener
+     *   await publish(text)
+     * })
+     */
+    emit(event: string, data?: unknown): Promise<void>;
+    saveCheckpoint(): void;
+    log(msg: string, data?: Record<string, unknown>): void;
+    fork(vars?: Record<string, unknown>, session?: Session | null): Context;
+    navigate(url: string): Promise<void>;
+    click(opts: ClickOptions): Promise<void>;
+    type(text: string): Promise<void>;
+    key(key: string): Promise<void>;
+    scroll(opts: ScrollOptions): Promise<void>;
+    screenshot(): Promise<Buffer>;
+}
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AACxE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAG1C,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAA;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC9B,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC5B,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAA;IACxB,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,CAAA;CAC5B;AAED,qBAAa,OAAO;IAClB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACtC,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAA;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAC7C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAA;IAExB,6DAA6D;IAC7D,eAAe,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,SAAS,EAAE,MAAM,CAAK;IACtB,eAAe,EAAE,MAAM,EAAE,CAAK;IAC9B,mBAAmB,EAAE,MAAM,CAAK;gBAEpB,EACV,OAAO,EACP,IAAS,EACT,KAAiB,EACjB,MAAa,EACb,cAAqB,EACrB,OAAc,EACd,MAAa,GACd,EAAE,cAAc;IAYjB,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAI5C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAKtC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIzB,QAAQ,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAMnC;;;;;;;;;;;OAWG;IACG,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAMxD,cAAc,IAAI,IAAI;IAkBtB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAQtD,IAAI,CAAC,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EAAE,OAAO,GAAE,OAAO,GAAG,IAAW,GAAG,OAAO;IAcjF,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IACpC,KAAK,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IACxC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IACjC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAC/B,MAAM,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAC1C,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;CAC9B"}

package/dist/context.js

@@ -0,0 +1,95 @@
+import { writeCheckpoint } from './checkpoint.js';
+export class Context {
+    session;
+    vars;
+    signal;
+    _state;
+    _logger;
+    _emitter;
+    /** Set by the Loop runner — enables ctx.saveCheckpoint(). */
+    _checkpointFile;
+    _loopName = '';
+    _completedSteps = [];
+    _lastCompletedIndex = -1;
+    constructor({ session, vars = {}, state = new Map(), logger = null, checkpointFile = null, emitter = null, signal = null, }) {
+        this.session = session;
+        this.vars = vars;
+        this._state = state;
+        this._logger = logger;
+        this._checkpointFile = checkpointFile;
+        this._emitter = emitter;
+        this.signal = signal;
+    }
+    // ── state ────────────────────────────────────────────────────────────────────
+    get(key) {
+        return this._state.get(key);
+    }
+    set(key, value) {
+        this._state.set(key, value);
+        return this;
+    }
+    has(key) {
+        return this._state.has(key);
+    }
+    snapshot() {
+        return Object.fromEntries(this._state);
+    }
+    // ── events ────────────────────────────────────────────────────────────────────
+    /**
+     * Emit a custom event from inside a step. Listeners on the Loop will receive
+     * it and can block the step until they complete (useful for human-in-the-loop
+     * gates, approval flows, or metrics).
+     *
+     * @example
+     * loop.step('draft', async (ctx) => {
+     *   const text = await generateDraft(ctx)
+     *   await ctx.emit('draft:ready', { text })  // waits for approval listener
+     *   await publish(text)
+     * })
+     */
+    async emit(event, data) {
+        await this._emitter?.emit(event, data);
+    }
+    // ── checkpointing ─────────────────────────────────────────────────────────────
+    saveCheckpoint() {
+        if (!this._checkpointFile) {
+            throw new Error('saveCheckpoint() requires checkpointFile to be set in loop.run()');
+        }
+        const data = {
+            loop: this._loopName,
+            session: this.session.id,
+            savedAt: new Date().toISOString(),
+            completedSteps: [...this._completedSteps],
+            lastCompletedIndex: this._lastCompletedIndex,
+            state: this.snapshot(),
+        };
+        writeCheckpoint(this._checkpointFile, data);
+        this.log(`checkpoint saved → ${this._checkpointFile}`);
+    }
+    // ── logging ──────────────────────────────────────────────────────────────────
+    log(msg, data) {
+        const extra = data ? ` ${JSON.stringify(data)}` : '';
+        process.stdout.write(`  ${msg}${extra}\n`);
+        this._logger?.write({ msg, data });
+    }
+    // ── forking ──────────────────────────────────────────────────────────────────
+    fork(vars = {}, session = null) {
+        return new Context({
+            session: session ?? this.session,
+            vars: { ...this.vars, ...vars },
+            state: this._state,
+            logger: this._logger,
+            checkpointFile: this._checkpointFile,
+            emitter: this._emitter,
+            signal: this.signal,
+        });
+    }
+    // ── session convenience methods ───────────────────────────────────────────────
+    navigate(url) { return this.session.navigate(url); }
+    click(opts) { return this.session.click(opts); }
+    type(text) { return this.session.type(text); }
+    key(key) { return this.session.key(key); }
+    scroll(opts) { return this.session.scroll(opts); }
+    screenshot() { return this.session.screenshot(); }
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

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

package/dist/events.d.ts

@@ -0,0 +1,111 @@
+/**
+ * events.ts — typed event system for loop lifecycle and custom step events.
+ *
+ * The Loop fires built-in events at every lifecycle moment. Steps can emit
+ * custom events via ctx.emit(). Listeners can be async — the loop awaits all
+ * listeners before continuing, so a listener can pause execution (e.g. a
+ * human-in-the-loop gate that waits for approval).
+ *
+ * @example
+ * loop.on('step:complete', async ({ step, durationMs }) => {
+ *   await slack.send(`✓ ${step} finished in ${durationMs}ms`)
+ * })
+ *
+ * loop.on('loop:error', async ({ error }) => {
+ *   await pagerduty.alert(error.message)
+ * })
+ *
+ * // Custom event from inside a step:
+ * loop.step('review', async (ctx) => {
+ *   const result = await agent(ctx, 'Draft the email.')
+ *   await ctx.emit('draft:ready', { text: result.text })
+ * })
+ *
+ * loop.on('draft:ready', async ({ text }) => {
+ *   await humanReview(text)  // blocks until approved
+ * })
+ */
+export interface LoopStartEvent {
+    loop: string;
+    session: string;
+    totalSteps: number;
+    resumedFrom?: string;
+}
+export interface LoopCompleteEvent {
+    loop: string;
+    session: string;
+    status: 'completed' | 'failed' | 'cancelled';
+    durationMs: number;
+    stepsCompleted: number;
+}
+export interface StepStartEvent {
+    loop: string;
+    step: string;
+    index: number;
+    total: number;
+}
+export interface StepCompleteEvent {
+    loop: string;
+    step: string;
+    index: number;
+    durationMs: number;
+}
+export interface StepErrorEvent {
+    loop: string;
+    step: string;
+    index: number;
+    error: Error;
+    durationMs: number;
+}
+export interface StepSkipEvent {
+    loop: string;
+    step: string;
+    index: number;
+    reason: 'checkpoint' | 'range' | 'error';
+}
+export interface StepRetryEvent {
+    loop: string;
+    step: string;
+    index: number;
+    plugin: string;
+}
+export interface CheckpointSavedEvent {
+    loop: string;
+    file: string;
+    step: string;
+    completedCount: number;
+    totalSteps: number;
+}
+/** Map of all built-in event names → their payload types. */
+export interface LoopEvents {
+    'loop:start': LoopStartEvent;
+    'loop:complete': LoopCompleteEvent;
+    'step:start': StepStartEvent;
+    'step:complete': StepCompleteEvent;
+    'step:error': StepErrorEvent;
+    'step:skip': StepSkipEvent;
+    'step:retry': StepRetryEvent;
+    'checkpoint:saved': CheckpointSavedEvent;
+}
+type KnownListener<K extends keyof LoopEvents> = (data: LoopEvents[K]) => void | Promise<void>;
+type AnyListener = (data: unknown) => void | Promise<void>;
+export declare class Emitter {
+    private readonly _listeners;
+    /** Listen to a built-in lifecycle event (fully typed). */
+    on<K extends keyof LoopEvents>(event: K, listener: KnownListener<K>): this;
+    /** Listen to a custom event emitted via ctx.emit(). */
+    on(event: string, listener: AnyListener): this;
+    /** Remove a listener. */
+    off<K extends keyof LoopEvents>(event: K, listener: KnownListener<K>): this;
+    off(event: string, listener: AnyListener): this;
+    /**
+     * Fire an event. Awaits all listeners concurrently.
+     * Listener errors are caught and logged — they never crash the loop.
+     */
+    emit<K extends keyof LoopEvents>(event: K, data: LoopEvents[K]): Promise<void>;
+    emit(event: string, data: unknown): Promise<void>;
+    /** True if any listeners are registered for the given event. */
+    hasListeners(event: string): boolean;
+}
+export {};
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

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

package/dist/events.js

@@ -0,0 +1,53 @@
+/**
+ * events.ts — typed event system for loop lifecycle and custom step events.
+ *
+ * The Loop fires built-in events at every lifecycle moment. Steps can emit
+ * custom events via ctx.emit(). Listeners can be async — the loop awaits all
+ * listeners before continuing, so a listener can pause execution (e.g. a
+ * human-in-the-loop gate that waits for approval).
+ *
+ * @example
+ * loop.on('step:complete', async ({ step, durationMs }) => {
+ *   await slack.send(`✓ ${step} finished in ${durationMs}ms`)
+ * })
+ *
+ * loop.on('loop:error', async ({ error }) => {
+ *   await pagerduty.alert(error.message)
+ * })
+ *
+ * // Custom event from inside a step:
+ * loop.step('review', async (ctx) => {
+ *   const result = await agent(ctx, 'Draft the email.')
+ *   await ctx.emit('draft:ready', { text: result.text })
+ * })
+ *
+ * loop.on('draft:ready', async ({ text }) => {
+ *   await humanReview(text)  // blocks until approved
+ * })
+ */
+export class Emitter {
+    _listeners = new Map();
+    on(event, listener) {
+        if (!this._listeners.has(event))
+            this._listeners.set(event, new Set());
+        this._listeners.get(event).add(listener);
+        return this;
+    }
+    off(event, listener) {
+        this._listeners.get(event)?.delete(listener);
+        return this;
+    }
+    async emit(event, data) {
+        const listeners = this._listeners.get(event);
+        if (!listeners?.size)
+            return;
+        await Promise.all([...listeners].map(fn => Promise.resolve(fn(data)).catch(err => {
+            console.error(`  [event:${event}] listener error: ${err.message}`);
+        })));
+    }
+    /** True if any listeners are registered for the given event. */
+    hasListeners(event) {
+        return (this._listeners.get(event)?.size ?? 0) > 0;
+    }
+}
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAgFH,MAAM,OAAO,OAAO;IACD,UAAU,GAAG,IAAI,GAAG,EAA4B,CAAA;IAMjE,EAAE,CAAC,KAAa,EAAE,QAAqB;QACrC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC;YAAE,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,GAAG,EAAE,CAAC,CAAA;QACtE,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;QACzC,OAAO,IAAI,CAAA;IACb,CAAC;IAKD,GAAG,CAAC,KAAa,EAAE,QAAqB;QACtC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAA;QAC5C,OAAO,IAAI,CAAA;IACb,CAAC;IAQD,KAAK,CAAC,IAAI,CAAC,KAAa,EAAE,IAAa;QACrC,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;QAC5C,IAAI,CAAC,SAAS,EAAE,IAAI;YAAE,OAAM;QAC5B,MAAM,OAAO,CAAC,GAAG,CACf,CAAC,GAAG,SAAS,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CACtB,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE;YACpC,OAAO,CAAC,KAAK,CAAC,YAAY,KAAK,qBAAsB,GAAa,CAAC,OAAO,EAAE,CAAC,CAAA;QAC/E,CAAC,CAAC,CACH,CACF,CAAA;IACH,CAAC;IAED,gEAAgE;IAChE,YAAY,CAAC,KAAa;QACxB,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAA;IACpD,CAAC;CACF"}

package/dist/flow.d.ts

@@ -0,0 +1,36 @@
+import type { Context } from './context.js';
+import type { Loop } from './loop.js';
+export type Item = string | {
+    type: string;
+    subtypes?: string[];
+};
+export interface EachOptions {
+    continueOnError?: boolean;
+}
+/**
+ * each — iterate over a list of items, running a step function for each one.
+ *
+ * Each item receives a forked Context with per-item vars merged in:
+ *   ctx.vars.item    — the item value
+ *   ctx.vars.subtype — the subtype (if applicable)
+ *
+ * @example
+ * await each(ctx, ['https://a.com', 'https://b.com'], async (ctx) => {
+ *   await ctx.navigate(ctx.vars.item as string)
+ *   await agent(ctx, 'Summarize this page.', { model })
+ * })
+ */
+export declare function each(ctx: Context, items: Item[], fn: (ctx: Context) => Promise<unknown>, { continueOnError }?: EachOptions): Promise<void>;
+/**
+ * sub — run a Loop instance as a sub-step, sharing the current session.
+ *
+ * @example
+ * const loginLoop = new Loop('login')
+ * loginLoop.step('auth', async (ctx) => { ... })
+ *
+ * loop.step('login', async (ctx) => {
+ *   await sub(ctx, loginLoop, { loginUrl: '/login', username: 'admin' })
+ * })
+ */
+export declare function sub(ctx: Context, loop: Loop, vars?: Record<string, unknown>): Promise<void>;
+//# sourceMappingURL=flow.d.ts.map

package/dist/flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow.d.ts","sourceRoot":"","sources":["../src/flow.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAC3C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAErC,MAAM,MAAM,IAAI,GAAG,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAAA;AAEjE,MAAM,WAAW,WAAW;IAC1B,eAAe,CAAC,EAAE,OAAO,CAAA;CAC1B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,IAAI,CACxB,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,IAAI,EAAE,EACb,EAAE,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,EACtC,EAAE,eAAuB,EAAE,GAAE,WAAgB,GAC5C,OAAO,CAAC,IAAI,CAAC,CAef;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,GAAG,CACvB,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,IAAI,EACV,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACjC,OAAO,CAAC,IAAI,CAAC,CAGf"}

package/dist/flow.js

@@ -0,0 +1,62 @@
+/**
+ * each — iterate over a list of items, running a step function for each one.
+ *
+ * Each item receives a forked Context with per-item vars merged in:
+ *   ctx.vars.item    — the item value
+ *   ctx.vars.subtype — the subtype (if applicable)
+ *
+ * @example
+ * await each(ctx, ['https://a.com', 'https://b.com'], async (ctx) => {
+ *   await ctx.navigate(ctx.vars.item as string)
+ *   await agent(ctx, 'Summarize this page.', { model })
+ * })
+ */
+export async function each(ctx, items, fn, { continueOnError = false } = {}) {
+    const pairs = expandItems(items);
+    for (const vars of pairs) {
+        const label = vars.subtype ? `${vars.item} / ${vars.subtype}` : vars.item;
+        const childCtx = ctx.fork(vars);
+        try {
+            await fn(childCtx);
+        }
+        catch (err) {
+            if (!continueOnError)
+                throw err;
+            const msg = err instanceof Error ? err.message : String(err);
+            ctx.log(`each: "${label}" failed — ${msg}`);
+        }
+    }
+}
+/**
+ * sub — run a Loop instance as a sub-step, sharing the current session.
+ *
+ * @example
+ * const loginLoop = new Loop('login')
+ * loginLoop.step('auth', async (ctx) => { ... })
+ *
+ * loop.step('login', async (ctx) => {
+ *   await sub(ctx, loginLoop, { loginUrl: '/login', username: 'admin' })
+ * })
+ */
+export async function sub(ctx, loop, vars = {}) {
+    const childCtx = ctx.fork(vars);
+    return loop.runWith(childCtx);
+}
+function expandItems(items) {
+    const pairs = [];
+    for (const entry of items) {
+        if (typeof entry === 'string') {
+            pairs.push({ item: entry });
+        }
+        else if (entry.subtypes?.length) {
+            for (const subtype of entry.subtypes) {
+                pairs.push({ item: entry.type, subtype });
+            }
+        }
+        else {
+            pairs.push({ item: entry.type });
+        }
+    }
+    return pairs;
+}
+//# sourceMappingURL=flow.js.map