@pi-agents/loop 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ArtemisAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,93 @@
+# @pi-agents/loop
+
+Recurring prompt scheduling and cron job management for [pi-coding-agent](https://github.com/badlogic/pi-mono).
+
+## Features
+
+- **`/loop` command** — Quick recurring prompts: `/loop 5m check the deploy`
+- **Cron tools** — LLM-callable `cron_create`, `cron_delete`, `cron_list` for programmatic scheduling
+- **Idle gating** — Prompts only fire when the agent is idle, never interrupting in-progress work
+- **Durable tasks** — Optionally persist schedules across sessions via `.pi-loop.json`
+- **Anti-thundering-herd** — Deterministic jitter prevents multiple tasks from firing simultaneously
+- **Auto-expiry** — Recurring tasks expire after 7 days by default
+
+## Install
+
+```bash
+npm install @pi-agents/loop
+```
+
+Add to your pi-agent settings (`~/.pi/agent/settings.json`):
+
+```json
+{
+  "extensions": ["npm:@pi-agents/loop"]
+}
+```
+
+## Usage
+
+### Slash Commands
+
+| Command | Description |
+|---------|-------------|
+| `/loop [interval] <prompt>` | Start a recurring loop (default 10m) |
+| `/loop-list` | List all active loops |
+| `/loop-kill <id>` | Cancel a loop by ID |
+
+**Examples:**
+```
+/loop 5m check the deploy
+/loop check tests every 15m
+/loop-kill a1b2c3d4
+```
+
+### LLM Tools
+
+The extension registers three tools the LLM can call directly:
+
+| Tool | Description |
+|------|-------------|
+| `cron_create` | Schedule a prompt on a 5-field cron expression |
+| `cron_delete` | Cancel a scheduled task by ID |
+| `cron_list` | List all active scheduled tasks |
+
+### Cron Format
+
+Standard 5-field cron in local time: `minute hour day-of-month month day-of-week`
+
+| Pattern | Meaning |
+|---------|---------|
+| `*/5 * * * *` | Every 5 minutes |
+| `0 */2 * * *` | Every 2 hours |
+| `30 14 * * *` | Daily at 2:30 PM |
+| `0 9 * * 1-5` | Weekdays at 9 AM |
+
+### Durable vs Session Tasks
+
+- **Session tasks** (default) — Live only for the current session. Lost when the agent exits.
+- **Durable tasks** (`durable: true`) — Persisted to `.pi-loop.json` and restored on next session start.
+
+## Configuration
+
+Default configuration in `config/default.json`:
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `maxJobs` | 50 | Maximum concurrent scheduled tasks |
+| `recurringMaxAgeDays` | 7 | Auto-expiry for recurring tasks |
+| `recurringJitterFrac` | 0.1 | Jitter as fraction of cron gap |
+| `recurringJitterCapMinutes` | 15 | Maximum jitter cap |
+| `checkIntervalMs` | 1000 | Scheduler tick interval |
+
+## Development
+
+```bash
+npm run build    # Compile TypeScript
+npm run lint     # Type-check without emitting
+npm run dev      # Run with pi-agent in dev mode
+```
+
+## License
+
+MIT

package/config/default.json

@@ -0,0 +1,11 @@
+{
+  "maxJobs": 50,
+  "recurringMaxAgeDays": 7,
+  "recurringJitterFrac": 0.1,
+  "recurringJitterCapMinutes": 15,
+  "oneShotJitterMaxSeconds": 90,
+  "oneShotJitterFloorSeconds": 0,
+  "oneShotJitterMinuteMod": 30,
+  "checkIntervalMs": 1000,
+  "durableFilePath": ".pi-loop.json"
+}

package/dist/cron.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 5-field cron parser and next-run calculator.
+ * All evaluation is in the user's local timezone.
+ *
+ * Format: minute hour day-of-month month day-of-week
+ */
+interface CronField {
+    values: Set<number>;
+}
+interface ParsedCron {
+    minute: CronField;
+    hour: CronField;
+    dayOfMonth: CronField;
+    month: CronField;
+    dayOfWeek: CronField;
+}
+export declare function parseCronExpression(cron: string): ParsedCron | null;
+/**
+ * Compute next cron run after `from`. Returns null if no match within 1 year.
+ */
+export declare function computeNextCronRun(parsed: ParsedCron, from: Date): Date | null;
+/**
+ * Convenience: parse cron string and compute next run in epoch ms.
+ */
+export declare function nextCronRunMs(cron: string, fromMs: number): number | null;
+/**
+ * Convert cron expression to human-readable string.
+ */
+export declare function cronToHuman(cron: string): string;
+/**
+ * Convert a human interval string (e.g. "5m", "2h", "1d") to a cron expression.
+ */
+export declare function intervalToCron(interval: string): string | null;
+/**
+ * Compute the gap between consecutive fires for a cron expression (in ms).
+ * Used for jitter calculation.
+ */
+export declare function cronGapMs(cron: string, fromMs: number): number | null;
+export {};

package/dist/cron.js

@@ -0,0 +1,189 @@
+/**
+ * 5-field cron parser and next-run calculator.
+ * All evaluation is in the user's local timezone.
+ *
+ * Format: minute hour day-of-month month day-of-week
+ */
+const FIELD_RANGES = [
+    [0, 59], // minute
+    [0, 23], // hour
+    [1, 31], // day of month
+    [1, 12], // month
+    [0, 6], // day of week (0=Sunday)
+];
+function parseField(field, min, max) {
+    const values = new Set();
+    for (const part of field.split(",")) {
+        const stepMatch = part.match(/^(.+)\/(\d+)$/);
+        const step = stepMatch ? parseInt(stepMatch[2], 10) : 1;
+        const range = stepMatch ? stepMatch[1] : part;
+        if (step < 1)
+            return null;
+        if (range === "*") {
+            for (let i = min; i <= max; i += step)
+                values.add(i);
+        }
+        else {
+            const dashMatch = range.match(/^(\d+)-(\d+)$/);
+            if (dashMatch) {
+                const lo = parseInt(dashMatch[1], 10);
+                const hi = parseInt(dashMatch[2], 10);
+                if (lo < min || hi > max || lo > hi)
+                    return null;
+                for (let i = lo; i <= hi; i += step)
+                    values.add(i);
+            }
+            else {
+                const val = parseInt(range, 10);
+                if (isNaN(val) || val < min || val > max)
+                    return null;
+                values.add(val);
+            }
+        }
+    }
+    return values.size > 0 ? { values } : null;
+}
+export function parseCronExpression(cron) {
+    const parts = cron.trim().split(/\s+/);
+    if (parts.length !== 5)
+        return null;
+    const fields = [];
+    for (let i = 0; i < 5; i++) {
+        const field = parseField(parts[i], FIELD_RANGES[i][0], FIELD_RANGES[i][1]);
+        if (!field)
+            return null;
+        fields.push(field);
+    }
+    return {
+        minute: fields[0],
+        hour: fields[1],
+        dayOfMonth: fields[2],
+        month: fields[3],
+        dayOfWeek: fields[4],
+    };
+}
+/**
+ * Compute next cron run after `from`. Returns null if no match within 1 year.
+ */
+export function computeNextCronRun(parsed, from) {
+    const d = new Date(from.getTime());
+    // Start from the next minute
+    d.setSeconds(0, 0);
+    d.setMinutes(d.getMinutes() + 1);
+    const limit = new Date(from.getTime() + 366 * 24 * 60 * 60 * 1000);
+    while (d < limit) {
+        if (!parsed.month.values.has(d.getMonth() + 1)) {
+            d.setMonth(d.getMonth() + 1, 1);
+            d.setHours(0, 0, 0, 0);
+            continue;
+        }
+        if (!parsed.dayOfMonth.values.has(d.getDate()) ||
+            !parsed.dayOfWeek.values.has(d.getDay())) {
+            d.setDate(d.getDate() + 1);
+            d.setHours(0, 0, 0, 0);
+            continue;
+        }
+        if (!parsed.hour.values.has(d.getHours())) {
+            d.setHours(d.getHours() + 1, 0, 0, 0);
+            continue;
+        }
+        if (!parsed.minute.values.has(d.getMinutes())) {
+            d.setMinutes(d.getMinutes() + 1, 0, 0);
+            continue;
+        }
+        return d;
+    }
+    return null;
+}
+/**
+ * Convenience: parse cron string and compute next run in epoch ms.
+ */
+export function nextCronRunMs(cron, fromMs) {
+    const parsed = parseCronExpression(cron);
+    if (!parsed)
+        return null;
+    const next = computeNextCronRun(parsed, new Date(fromMs));
+    return next ? next.getTime() : null;
+}
+/**
+ * Convert cron expression to human-readable string.
+ */
+export function cronToHuman(cron) {
+    const parts = cron.trim().split(/\s+/);
+    if (parts.length !== 5)
+        return cron;
+    const [min, hour, dom, mon, dow] = parts;
+    // Every N minutes
+    const everyMinMatch = min.match(/^\*\/(\d+)$/);
+    if (everyMinMatch && hour === "*" && dom === "*" && mon === "*" && dow === "*") {
+        const n = parseInt(everyMinMatch[1], 10);
+        return n === 1 ? "every minute" : `every ${n} minutes`;
+    }
+    // Every N hours
+    const everyHourMatch = hour.match(/^\*\/(\d+)$/);
+    if (min === "0" && everyHourMatch && dom === "*" && mon === "*" && dow === "*") {
+        const n = parseInt(everyHourMatch[1], 10);
+        return n === 1 ? "every hour" : `every ${n} hours`;
+    }
+    // Every N days
+    const everyDayMatch = dom.match(/^\*\/(\d+)$/);
+    if (min === "0" && hour === "0" && everyDayMatch && mon === "*" && dow === "*") {
+        const n = parseInt(everyDayMatch[1], 10);
+        return n === 1 ? "every day at midnight" : `every ${n} days at midnight`;
+    }
+    // Specific time
+    if (/^\d+$/.test(min) && /^\d+$/.test(hour) && dom === "*" && mon === "*" && dow === "*") {
+        const h = parseInt(hour, 10);
+        const m = parseInt(min, 10);
+        const period = h >= 12 ? "PM" : "AM";
+        const h12 = h === 0 ? 12 : h > 12 ? h - 12 : h;
+        return `daily at ${h12}:${m.toString().padStart(2, "0")} ${period}`;
+    }
+    return cron;
+}
+/**
+ * Convert a human interval string (e.g. "5m", "2h", "1d") to a cron expression.
+ */
+export function intervalToCron(interval) {
+    const match = interval.match(/^(\d+)([smhd])$/);
+    if (!match)
+        return null;
+    let n = parseInt(match[1], 10);
+    const unit = match[2];
+    if (n <= 0)
+        return null;
+    switch (unit) {
+        case "s":
+            // Cron minimum is 1 minute; round up
+            n = Math.max(1, Math.ceil(n / 60));
+            return `*/${n} * * * *`;
+        case "m":
+            if (n <= 59)
+                return `*/${n} * * * *`;
+            // Round to hours
+            const hours = Math.max(1, Math.round(n / 60));
+            return `0 */${hours} * * *`;
+        case "h":
+            if (n <= 23)
+                return `0 */${n} * * *`;
+            return `0 0 */${Math.ceil(n / 24)} * *`;
+        case "d":
+            return `0 0 */${n} * *`;
+        default:
+            return null;
+    }
+}
+/**
+ * Compute the gap between consecutive fires for a cron expression (in ms).
+ * Used for jitter calculation.
+ */
+export function cronGapMs(cron, fromMs) {
+    const first = nextCronRunMs(cron, fromMs);
+    if (first === null)
+        return null;
+    const second = nextCronRunMs(cron, first);
+    if (second === null)
+        return null;
+    return second - first;
+}
+//# sourceMappingURL=cron.js.map

package/dist/cron.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * pi-loop — recurring prompt execution and cron scheduling for pi-agent.
+ *
+ * Registers:
+ * - /loop, /loop-list, /loop-kill commands
+ * - cron_create, cron_delete, cron_list LLM-callable tools
+ * - Scheduler engine with idle gating
+ */
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+export default function piLoop(pi: ExtensionAPI): void;

package/dist/index.js

@@ -0,0 +1,175 @@
+/**
+ * pi-loop — recurring prompt execution and cron scheduling for pi-agent.
+ *
+ * Registers:
+ * - /loop, /loop-list, /loop-kill commands
+ * - cron_create, cron_delete, cron_list LLM-callable tools
+ * - Scheduler engine with idle gating
+ */
+import { intervalToCron, cronToHuman, nextCronRunMs } from "./cron.js";
+import { parseLoopArgs } from "./parse-args.js";
+import { LoopScheduler } from "./scheduler.js";
+import { addTask, removeTask, getAllTasks, getTaskCount, generateTaskId, loadDurableTasks, writeDurableTasks, acquireLock, releaseLock, } from "./store.js";
+import { registerCronTools } from "./tools/cron-tools.js";
+import { DEFAULT_CONFIG } from "./types.js";
+export default function piLoop(pi) {
+    const config = { ...DEFAULT_CONFIG };
+    let cwd = process.cwd();
+    let scheduler = null;
+    let hasLock = false;
+    // --- Commands ---
+    pi.registerCommand("loop", {
+        description: "Run a prompt on a recurring interval (e.g. /loop 5m check the deploy). Defaults to 10m.",
+        getArgumentCompletions(prefix) {
+            const suggestions = ["5m ", "10m ", "15m ", "30m ", "1h ", "2h "];
+            return suggestions
+                .filter((s) => s.startsWith(prefix))
+                .map((s) => ({ value: s, label: s.trim() }));
+        },
+        async handler(args, ctx) {
+            const parsed = parseLoopArgs(args);
+            if (!parsed) {
+                if (ctx.hasUI) {
+                    ctx.ui.notify("Usage: /loop [interval] <prompt>\n" +
+                        "Examples: /loop 5m check the deploy, /loop check tests every 15m", "warning");
+                }
+                return;
+            }
+            const cron = intervalToCron(parsed.interval);
+            if (!cron) {
+                if (ctx.hasUI) {
+                    ctx.ui.notify(`Invalid interval: "${parsed.interval}". Use format: 5s, 10m, 2h, 1d`, "error");
+                }
+                return;
+            }
+            if (getTaskCount() >= config.maxJobs) {
+                if (ctx.hasUI) {
+                    ctx.ui.notify(`Maximum of ${config.maxJobs} loops reached. Use /loop-kill to remove some.`, "error");
+                }
+                return;
+            }
+            const task = {
+                id: generateTaskId(),
+                cron,
+                prompt: parsed.prompt,
+                createdAt: Date.now(),
+                recurring: true,
+                durable: false,
+            };
+            addTask(task);
+            scheduler?.refreshStatus();
+            const human = cronToHuman(cron);
+            const nextRun = nextCronRunMs(cron, Date.now());
+            const nextStr = nextRun ? new Date(nextRun).toLocaleString() : "soon";
+            const expiryDays = Math.round(config.recurringMaxAgeMs / (24 * 60 * 60 * 1000));
+            if (ctx.hasUI) {
+                ctx.ui.notify(`Loop ${task.id} created: ${human}\n` +
+                    `Next fire: ${nextStr}\n` +
+                    `Auto-expires in ${expiryDays} days. Cancel: /loop-kill ${task.id}`, "info");
+            }
+            // Immediately execute the prompt (don't wait for first cron fire)
+            pi.sendUserMessage(parsed.prompt);
+        },
+    });
+    pi.registerCommand("loop-list", {
+        description: "List all active loop tasks",
+        async handler(_args, ctx) {
+            const tasks = getAllTasks();
+            if (tasks.length === 0) {
+                if (ctx.hasUI) {
+                    ctx.ui.notify("No active loops.", "info");
+                }
+                return;
+            }
+            const now = Date.now();
+            const lines = tasks.map((t) => {
+                const human = cronToHuman(t.cron);
+                const next = nextCronRunMs(t.cron, t.lastFiredAt ?? t.createdAt);
+                const nextStr = next ? new Date(next).toLocaleString() : "unknown";
+                const flags = [
+                    t.recurring ? "recurring" : "one-shot",
+                    t.durable ? "durable" : "session",
+                ].join(", ");
+                return `  [${t.id}] ${human} — ${t.prompt.slice(0, 50)} (next: ${nextStr}, ${flags})`;
+            });
+            if (ctx.hasUI) {
+                ctx.ui.notify(`${tasks.length} active loop${tasks.length === 1 ? "" : "s"}:\n${lines.join("\n")}`, "info");
+            }
+        },
+    });
+    pi.registerCommand("loop-kill", {
+        description: "Cancel a loop task by ID",
+        getArgumentCompletions(prefix) {
+            return getAllTasks()
+                .filter((t) => t.id.startsWith(prefix))
+                .map((t) => {
+                const label = `${t.id} — ${cronToHuman(t.cron)}: ${t.prompt.slice(0, 30)}`;
+                return { value: t.id, label };
+            });
+        },
+        async handler(args, ctx) {
+            const id = args.trim();
+            if (!id) {
+                if (ctx.hasUI) {
+                    ctx.ui.notify("Usage: /loop-kill <task-id>", "warning");
+                }
+                return;
+            }
+            const removed = removeTask(id);
+            if (!removed) {
+                if (ctx.hasUI) {
+                    ctx.ui.notify(`No loop found with ID "${id}".`, "error");
+                }
+                return;
+            }
+            // Persist if we had durable tasks
+            writeDurableTasks(cwd, config).catch(() => { });
+            scheduler?.refreshStatus();
+            if (ctx.hasUI) {
+                ctx.ui.notify(`Loop ${id} cancelled.`, "info");
+            }
+        },
+    });
+    // --- LLM-callable tools ---
+    // Deferred to session_start so scheduler is initialized
+    // --- Lifecycle events ---
+    pi.on("session_start", async (_event, ctx) => {
+        cwd = ctx.cwd;
+        // Initialize scheduler
+        scheduler = new LoopScheduler(pi, config, cwd);
+        scheduler.setContext(ctx);
+        // Register LLM tools (needs scheduler reference)
+        registerCronTools(pi, scheduler, config, () => cwd);
+        // Load durable tasks
+        hasLock = await acquireLock(cwd, config);
+        if (hasLock) {
+            const durableTasks = await loadDurableTasks(cwd, config);
+            for (const task of durableTasks) {
+                addTask(task);
+            }
+        }
+        // Start the scheduler tick loop
+        scheduler.start();
+        scheduler.refreshStatus();
+        if (ctx.hasUI) {
+            const count = getTaskCount();
+            if (count > 0) {
+                ctx.ui.notify(`pi-loop: ${count} task${count === 1 ? "" : "s"} loaded`, "info");
+            }
+        }
+    });
+    pi.on("session_shutdown", async () => {
+        scheduler?.stop();
+        if (hasLock) {
+            await releaseLock(cwd, config);
+        }
+    });
+    // --- Idle gate ---
+    pi.on("agent_start", () => {
+        scheduler?.setBusy();
+    });
+    pi.on("agent_end", () => {
+        scheduler?.setIdle();
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/jitter.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Deterministic jitter system.
+ *
+ * Ported from Claude Code's cron jitter design:
+ * - Recurring tasks: forward delay (spread fires over a window)
+ * - One-shot tasks: backward lead (fire slightly early to avoid pile-ups)
+ */
+import type { LoopConfig, LoopTask } from "./types.js";
+/**
+ * Deterministic fraction [0, 1) from task ID.
+ * The ID is an 8-hex-char string; we parse it as a u32 and divide.
+ */
+export declare function jitterFrac(taskId: string): number;
+/**
+ * Compute jitter delay for a recurring task (forward delay in ms).
+ *
+ * nextFire = baseFire + frac * jitterFrac * gap
+ * Capped at recurringJitterCapMs.
+ */
+export declare function recurringJitterMs(task: LoopTask, gapMs: number, config: LoopConfig): number;
+/**
+ * Compute jitter for a one-shot task (backward lead in ms).
+ *
+ * Only applies if fire minute is on a boundary (e.g. :00 or :30).
+ * Returns a negative offset (subtract from fire time).
+ * Never fires before task creation time.
+ */
+export declare function oneShotJitterMs(task: LoopTask, fireTimeMs: number, config: LoopConfig): number;

package/dist/jitter.js

@@ -0,0 +1,50 @@
+/**
+ * Deterministic jitter system.
+ *
+ * Ported from Claude Code's cron jitter design:
+ * - Recurring tasks: forward delay (spread fires over a window)
+ * - One-shot tasks: backward lead (fire slightly early to avoid pile-ups)
+ */
+/**
+ * Deterministic fraction [0, 1) from task ID.
+ * The ID is an 8-hex-char string; we parse it as a u32 and divide.
+ */
+export function jitterFrac(taskId) {
+    const frac = parseInt(taskId.slice(0, 8), 16) / 0x100000000;
+    return Number.isFinite(frac) ? frac : 0;
+}
+/**
+ * Compute jitter delay for a recurring task (forward delay in ms).
+ *
+ * nextFire = baseFire + frac * jitterFrac * gap
+ * Capped at recurringJitterCapMs.
+ */
+export function recurringJitterMs(task, gapMs, config) {
+    const frac = jitterFrac(task.id);
+    const raw = frac * config.recurringJitterFrac * gapMs;
+    return Math.min(raw, config.recurringJitterCapMs);
+}
+/**
+ * Compute jitter for a one-shot task (backward lead in ms).
+ *
+ * Only applies if fire minute is on a boundary (e.g. :00 or :30).
+ * Returns a negative offset (subtract from fire time).
+ * Never fires before task creation time.
+ */
+export function oneShotJitterMs(task, fireTimeMs, config) {
+    const fireDate = new Date(fireTimeMs);
+    const fireMinute = fireDate.getMinutes();
+    // Only jitter fires on minute boundaries
+    if (fireMinute % config.oneShotJitterMinuteMod !== 0)
+        return 0;
+    const frac = jitterFrac(task.id);
+    const lead = config.oneShotJitterFloorMs +
+        frac * (config.oneShotJitterMaxMs - config.oneShotJitterFloorMs);
+    // Never fire before creation
+    const earliest = task.createdAt;
+    const jittered = fireTimeMs - lead;
+    if (jittered < earliest)
+        return fireTimeMs - earliest;
+    return lead;
+}
+//# sourceMappingURL=jitter.js.map

package/dist/jitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jitter.js","sourceRoot":"","sources":["../src/jitter.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,MAAc;IACvC,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,WAAW,CAAC;IAC5D,OAAO,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAc,EACd,KAAa,EACb,MAAkB;IAElB,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjC,MAAM,GAAG,GAAG,IAAI,GAAG,MAAM,CAAC,mBAAmB,GAAG,KAAK,CAAC;IACtD,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,oBAAoB,CAAC,CAAC;AACpD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAC7B,IAAc,EACd,UAAkB,EAClB,MAAkB;IAElB,MAAM,QAAQ,GAAG,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC;IACtC,MAAM,UAAU,GAAG,QAAQ,CAAC,UAAU,EAAE,CAAC;IAEzC,yCAAyC;IACzC,IAAI,UAAU,GAAG,MAAM,CAAC,sBAAsB,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAE/D,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjC,MAAM,IAAI,GACR,MAAM,CAAC,oBAAoB;QAC3B,IAAI,GAAG,CAAC,MAAM,CAAC,kBAAkB,GAAG,MAAM,CAAC,oBAAoB,CAAC,CAAC;IAEnE,6BAA6B;IAC7B,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC;IAChC,MAAM,QAAQ,GAAG,UAAU,GAAG,IAAI,CAAC;IACnC,IAAI,QAAQ,GAAG,QAAQ;QAAE,OAAO,UAAU,GAAG,QAAQ,CAAC;IAEtD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/parse-args.d.ts

@@ -0,0 +1,13 @@
+/**
+ * /loop argument parser.
+ *
+ * Priority:
+ * 1. Leading interval token: "5m check the deploy"
+ * 2. Trailing "every" clause: "check the deploy every 20m"
+ * 3. Default 10m
+ */
+export interface ParsedLoopArgs {
+    interval: string;
+    prompt: string;
+}
+export declare function parseLoopArgs(args: string): ParsedLoopArgs | null;