@chengchenccc/oh-my-agent 0.2.0-rc.2 → 0.2.0-rc.3

package/dist/core/index.js

@@ -5,9 +5,10 @@
 // though every symbol it exports comes from a subdirectory (the loop lives in
 // ./runtime/, the stores in ./store/). Import from here so callers keep
 // one stable seam; read ./runtime/README.md for the loop's file map.
-// Honest scope: in-app consumers mostly import submodules directly; this
-// barrel serves the app's public `src/index.ts` re-exports and tests that
-// want the loop's whole contract in one import.
+// Honest scope: this barrel is mostly used BY core's own submodules (they
+// import `../index.js` to avoid deep relative paths) and by tests that want the
+// loop's whole contract in one import. `apps/oh-my-agent/src/index.ts` — the
+// app's public surface — imports the submodules directly, not this file.
 export { createOmaSession } from "./runtime/agent-loop.js";
 // Compaction + retry
 export { compactSession } from "./runtime/compaction.js";

package/dist/core/loops/condition.d.ts

@@ -0,0 +1,57 @@
+import type { BashSandbox } from "../tools/bash-sandbox.js";
+/** Deterministic continue-condition for loop mode: a shell command whose EXIT
+ *  STATUS decides whether the next iteration runs.
+ *
+ *  Exit status is authoritative and stdout is ignored. `echo false` exits 0,
+ *  so "boolean-ish output" and the exit code actively disagree on the same
+ *  command, and every predicate a user already reaches for (`test`, `grep -q`,
+ *  `git diff --quiet`, `&&`) speaks exit codes.
+ *
+ *  Exit 1 is the only "condition is false" status. Anything higher (127
+ *  command not found, 126 not executable, 2 syntax error) means the CONDITION
+ *  itself is broken and is surfaced as an error instead of being read as
+ *  "false" — otherwise a typo'd condition halts the loop looking exactly like
+ *  finished work, which is the failure mode this feature exists to avoid. */
+export interface LoopConditionConfig {
+    /** Shell command; its exit status decides. */
+    command: string;
+    /** true = `--until` (stop when the command succeeds); false = `--while`
+     *  (stop when it fails). */
+    until: boolean;
+}
+export type LoopConditionVerdict = 
+/** Another iteration should run. */
+{
+    kind: "continue";
+}
+/** The condition resolved cleanly and says stop. */
+ | {
+    kind: "halt";
+    message: string;
+}
+/** The condition command is broken or timed out: stop and say why. */
+ | {
+    kind: "error";
+    message: string;
+}
+/** Aborted mid-evaluation (Esc); the caller owns that UX. */
+ | {
+    kind: "aborted";
+};
+export interface LoopConditionOptions {
+    cwd: string;
+    /** Deadline for one evaluation; 0 disables it. */
+    timeoutMs: number;
+    signal?: AbortSignal;
+    /** Sandbox the condition runs under (absent = unconfined). Conditions are
+     *  the same trust class as a bash tool call, so a run that opted into the OS
+     *  sandbox keeps it here too. */
+    sandbox?: BashSandbox;
+}
+export declare const DEFAULT_CONDITION_TIMEOUT_MS = 120000;
+/** Human-readable form of the condition, for enable/status messages. */
+export declare function describeLoopCondition(condition: LoopConditionConfig): string;
+/** Run one evaluation and map the exit status onto a loop verdict. Never
+ *  throws: a condition that cannot even start is an error verdict. */
+export declare function evaluateLoopCondition(condition: LoopConditionConfig, options: LoopConditionOptions): Promise<LoopConditionVerdict>;
+//# sourceMappingURL=condition.d.ts.map

package/dist/core/loops/condition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"condition.d.ts","sourceRoot":"","sources":["../../../src/core/loops/condition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D;;;;;;;;;;;;6EAY6E;AAE7E,MAAM,WAAW,mBAAmB;IAClC,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB;gCAC4B;IAC5B,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,MAAM,oBAAoB;AAC9B,oCAAoC;AAClC;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE;AACtB,oDAAoD;GAClD;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE;AACnC,sEAAsE;GACpE;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE;AACpC,6DAA6D;GAC3D;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAExB,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;qCAEiC;IACjC,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB;AASD,eAAO,MAAM,4BAA4B,SAAU,CAAC;AAEpD,wEAAwE;AACxE,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,mBAAmB,GAAG,MAAM,CAE5E;AAwBD;sEACsE;AACtE,wBAAsB,qBAAqB,CACzC,SAAS,EAAE,mBAAmB,EAC9B,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,oBAAoB,CAAC,CAwE/B"}

package/dist/core/loops/condition.js

@@ -0,0 +1,153 @@
+export const DEFAULT_CONDITION_TIMEOUT_MS = 120_000;
+/** Human-readable form of the condition, for enable/status messages. */
+export function describeLoopCondition(condition) {
+    return `${condition.until ? "until" : "while"} ${quoteCommand(condition.command)} succeeds`;
+}
+function quoteCommand(command) {
+    const flat = command.replace(/\s+/g, " ").trim();
+    const bounded = flat.length > 60 ? `${flat.slice(0, 60)}…` : flat;
+    return `\`${bounded}\``;
+}
+/** First meaningful line of a failed condition's output, bounded. */
+function previewOutput(output) {
+    const line = output
+        .split("\n")
+        .map((l) => l.trim())
+        .find((l) => l.length > 0);
+    if (!line)
+        return "";
+    return line.length > 60 ? `${line.slice(0, 60)}…` : line;
+}
+function formatTimeout(timeoutMs) {
+    if (timeoutMs < 60_000)
+        return `${Math.round(timeoutMs / 1_000)}s`;
+    const minutes = Math.round(timeoutMs / 60_000);
+    return minutes === 1 ? "1 minute" : `${minutes} minutes`;
+}
+/** Run one evaluation and map the exit status onto a loop verdict. Never
+ *  throws: a condition that cannot even start is an error verdict. */
+export async function evaluateLoopCondition(condition, options) {
+    let proc;
+    let timer;
+    let timedOut = false;
+    let aborted = false;
+    const onAbort = () => {
+        aborted = true;
+        proc?.kill();
+    };
+    try {
+        proc = startCondition(condition, options);
+        // Start draining BEFORE awaiting the exit: a condition whose output fills
+        // the pipe buffer would otherwise block forever on the write side.
+        const drained = collect(proc);
+        options.signal?.addEventListener("abort", onAbort, { once: true });
+        const exitCode = await Promise.race([
+            proc.exited,
+            options.timeoutMs > 0
+                ? new Promise((resolve) => {
+                    timer = setTimeout(() => {
+                        timedOut = true;
+                        proc?.kill();
+                        resolve(124); // conventional timeout status
+                    }, options.timeoutMs);
+                })
+                : new Promise(() => { }),
+        ]);
+        // Timeout before abort: both can stop the process, and the distinction
+        // matters — a deadline is a broken condition, Esc is not.
+        if (timedOut) {
+            return {
+                kind: "error",
+                message: `loop condition ${quoteCommand(condition.command)} timed out after ${formatTimeout(options.timeoutMs)}`,
+            };
+        }
+        if (aborted)
+            return { kind: "aborted" };
+        const output = await drained;
+        if (exitCode === 0) {
+            if (!condition.until)
+                return { kind: "continue" };
+            return {
+                kind: "halt",
+                message: `loop condition ${quoteCommand(condition.command)} is now satisfied`,
+            };
+        }
+        if (exitCode === 1) {
+            if (condition.until)
+                return { kind: "continue" };
+            return {
+                kind: "halt",
+                message: `loop condition ${quoteCommand(condition.command)} no longer holds`,
+            };
+        }
+        // Exit >1 (or a signal death, which reports no status) is the condition
+        // breaking, not answering.
+        const preview = previewOutput(output);
+        const detail = preview ? `: ${preview}` : "";
+        const status = exitCode === null ? "no exit status" : `exit ${exitCode}`;
+        return {
+            kind: "error",
+            message: `loop condition ${quoteCommand(condition.command)} failed (${status})${detail}`,
+        };
+    }
+    catch (err) {
+        return {
+            kind: "error",
+            message: `loop condition ${quoteCommand(condition.command)} could not run: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    finally {
+        clearTimeout(timer);
+        options.signal?.removeEventListener("abort", onAbort);
+    }
+}
+/** The condition runs in its OWN process, never the interactive shell: a `cd`
+ *  inside a condition must not move the session's working directory, and
+ *  stdin is closed so a predicate can never block on the terminal. When the
+ *  run has an OS sandbox, the condition inherits it. */
+function startCondition(condition, options) {
+    if (options.sandbox) {
+        const spawned = options.sandbox.spawn(condition.command, { cwd: options.cwd });
+        return {
+            stdout: spawned.stdout,
+            stderr: spawned.stderr,
+            exited: spawned.exited,
+            kill: () => spawned.kill(),
+        };
+    }
+    const proc = Bun.spawn(["bash", "-c", condition.command], {
+        stdout: "pipe",
+        stderr: "pipe",
+        stdin: "ignore",
+        cwd: options.cwd,
+    });
+    return {
+        stdout: proc.stdout,
+        stderr: proc.stderr,
+        exited: proc.exited,
+        kill: () => proc.kill(),
+    };
+}
+/** Merge both pipes into one bounded string. Runs concurrently with the exit
+ *  await, so a chatty condition cannot deadlock on a full pipe. */
+async function collect(proc) {
+    const read = async (stream) => {
+        const reader = stream.getReader();
+        const decoder = new TextDecoder();
+        let out = "";
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            out += decoder.decode(value, { stream: true });
+            if (out.length > 8_000)
+                out = out.slice(-8_000); // bounded preview buffer
+        }
+        return out;
+    };
+    const [stdout, stderr] = await Promise.all([
+        read(proc.stdout).catch(() => ""),
+        read(proc.stderr).catch(() => ""),
+    ]);
+    return `${stdout}${stderr}`;
+}

package/dist/core/loops/index.d.ts

@@ -0,0 +1,9 @@
+/** Loop mode: re-submit the last prompt after every settled turn, optionally
+ *  bounded by an iteration count or a wall-clock duration. Limits + their
+ *  parsing live in limits.ts; the session-scoped state machine in
+ *  runtime.ts. */
+export { DEFAULT_CONDITION_TIMEOUT_MS, describeLoopCondition, evaluateLoopCondition, type LoopConditionConfig, type LoopConditionOptions, type LoopConditionVerdict, } from "./condition.js";
+export { consumeLoopLimitIteration, createLoopLimitRuntime, describeLoopLimit, describeLoopLimitRuntime, isLoopDurationExpired, LOOP_USAGE, type LoopLimitConfig, type LoopLimitRuntime, type ParsedLoopArgs, parseLoopArgs, } from "./limits.js";
+export { RALPH_PROTOCOL, RALPH_QUEUE, ralphCondition, seedRalphQueue } from "./ralph.js";
+export { type LoopAction, type LoopIterationDecision, LoopRuntime, type LoopStart, type LoopStatus, } from "./runtime.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/loops/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/loops/index.ts"],"names":[],"mappings":"AAAA;;;kBAGkB;AAElB,OAAO,EACL,4BAA4B,EAC5B,qBAAqB,EACrB,qBAAqB,EACrB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,GAC1B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,yBAAyB,EACzB,sBAAsB,EACtB,iBAAiB,EACjB,wBAAwB,EACxB,qBAAqB,EACrB,UAAU,EACV,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACzF,OAAO,EACL,KAAK,UAAU,EACf,KAAK,qBAAqB,EAC1B,WAAW,EACX,KAAK,SAAS,EACd,KAAK,UAAU,GAChB,MAAM,cAAc,CAAC"}

package/dist/core/loops/index.js

@@ -0,0 +1,8 @@
+/** Loop mode: re-submit the last prompt after every settled turn, optionally
+ *  bounded by an iteration count or a wall-clock duration. Limits + their
+ *  parsing live in limits.ts; the session-scoped state machine in
+ *  runtime.ts. */
+export { DEFAULT_CONDITION_TIMEOUT_MS, describeLoopCondition, evaluateLoopCondition, } from "./condition.js";
+export { consumeLoopLimitIteration, createLoopLimitRuntime, describeLoopLimit, describeLoopLimitRuntime, isLoopDurationExpired, LOOP_USAGE, parseLoopArgs, } from "./limits.js";
+export { RALPH_PROTOCOL, RALPH_QUEUE, ralphCondition, seedRalphQueue } from "./ralph.js";
+export { LoopRuntime, } from "./runtime.js";

package/dist/core/loops/limits.d.ts

@@ -0,0 +1,43 @@
+import type { LoopConditionConfig } from "./condition.js";
+/** Loop-mode argument grammar and limits.
+ *
+ *  `/loop [count|duration] [--while|--until <command>] [prompt]`: a leading
+ *  token that LOOKS like a limit (starts with a digit or sign) or a FLAG
+ *  (starts with `--`) is parsed as one, and a malformed one is a hard error;
+ *  anything else is prose, i.e. the loop prompt — so `/loop keep going` starts
+ *  an unbounded loop instead of erroring. */
+export type LoopLimitConfig = {
+    kind: "iterations";
+    iterations: number;
+} | {
+    kind: "duration";
+    durationMs: number;
+};
+export type LoopLimitRuntime = {
+    kind: "iterations";
+    initial: number;
+    remaining: number;
+} | {
+    kind: "duration";
+    durationMs: number;
+    deadlineMs: number;
+};
+export declare const LOOP_USAGE = "usage: /loop [count|duration] [prompt] \u2014 examples: /loop, /loop 10, /loop 10m, /loop 1h30m keep going";
+export interface ParsedLoopArgs {
+    /** Iteration/duration budget from the leading limit token, when present. */
+    limit?: LoopLimitConfig;
+    /** Continue-condition from `--while` / `--until`, re-evaluated before each
+     *  iteration; absent = unconditional. */
+    condition?: LoopConditionConfig;
+    /** Inline loop prompt: text after the limit and flags, or the whole
+     *  argument when neither was given. */
+    prompt?: string;
+}
+export declare function parseLoopArgs(args: string): ParsedLoopArgs | string;
+export declare function createLoopLimitRuntime(config: LoopLimitConfig | undefined, nowMs?: number): LoopLimitRuntime | undefined;
+/** Consume one iteration's budget. False = the limit is exhausted. */
+export declare function consumeLoopLimitIteration(limit: LoopLimitRuntime | undefined, nowMs?: number): boolean;
+export declare function isLoopDurationExpired(limit: LoopLimitRuntime | undefined, nowMs?: number): boolean;
+export declare function describeLoopLimit(config: LoopLimitConfig): string;
+export declare function describeLoopLimitRuntime(limit: LoopLimitRuntime): string;
+//# sourceMappingURL=limits.d.ts.map

package/dist/core/loops/limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../../../src/core/loops/limits.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAE1D;;;;;;6CAM6C;AAE7C,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7C,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAoBjE,eAAO,MAAM,UAAU,+GACkF,CAAC;AAE1G,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB;6CACyC;IACzC,SAAS,CAAC,EAAE,mBAAmB,CAAC;IAChC;2CACuC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,MAAM,CAcnE;AA8ID,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,eAAe,GAAG,SAAS,EACnC,KAAK,SAAa,GACjB,gBAAgB,GAAG,SAAS,CAM9B;AAED,sEAAsE;AACtE,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,gBAAgB,GAAG,SAAS,EACnC,KAAK,SAAa,GACjB,OAAO,CAMT;AAED,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,gBAAgB,GAAG,SAAS,EACnC,KAAK,SAAa,GACjB,OAAO,CAET;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAKjE;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAKxE"}

package/dist/core/loops/limits.js

@@ -0,0 +1,219 @@
+const TIME_UNITS_MS = new Map([
+    ["s", 1_000],
+    ["sec", 1_000],
+    ["secs", 1_000],
+    ["second", 1_000],
+    ["seconds", 1_000],
+    ["m", 60_000],
+    ["min", 60_000],
+    ["mins", 60_000],
+    ["minute", 60_000],
+    ["minutes", 60_000],
+    ["h", 3_600_000],
+    ["hr", 3_600_000],
+    ["hrs", 3_600_000],
+    ["hour", 3_600_000],
+    ["hours", 3_600_000],
+]);
+export const LOOP_USAGE = "usage: /loop [count|duration] [prompt] — examples: /loop, /loop 10, /loop 10m, /loop 1h30m keep going";
+export function parseLoopArgs(args) {
+    const trimmed = args.trim();
+    if (!trimmed)
+        return {};
+    const limitResult = takeLoopLimit(trimmed);
+    if (typeof limitResult === "string")
+        return limitResult;
+    const conditionResult = takeLoopCondition(limitResult.rest);
+    if (typeof conditionResult === "string")
+        return conditionResult;
+    const parsed = {};
+    if (limitResult.limit)
+        parsed.limit = limitResult.limit;
+    if (conditionResult.condition)
+        parsed.condition = conditionResult.condition;
+    if (conditionResult.rest)
+        parsed.prompt = conditionResult.rest;
+    return parsed;
+}
+/** Split an optional leading limit token off the argument string. */
+function takeLoopLimit(input) {
+    const firstSpace = input.search(/\s/);
+    const firstToken = firstSpace === -1 ? input : input.slice(0, firstSpace);
+    const rest = firstSpace === -1 ? "" : input.slice(firstSpace + 1).trim();
+    const token = firstToken.toLowerCase();
+    // Not a limit attempt (prose, or a leading condition flag).
+    if (!/^[+-]?\d/.test(token))
+        return { rest: input };
+    // Bare integer: iteration count, unless the next token is a time unit
+    // ("10 minutes").
+    if (/^\d+$/.test(token)) {
+        if (rest) {
+            const unitToken = /^\S+/.exec(rest)?.[0] ?? "";
+            const unitMs = TIME_UNITS_MS.get(unitToken.toLowerCase());
+            if (unitMs !== undefined) {
+                const limit = makeDuration(token, unitMs);
+                if (typeof limit === "string")
+                    return limit;
+                return { limit, rest: rest.slice(unitToken.length).trim() };
+            }
+        }
+        const limit = makeIterations(token);
+        if (typeof limit === "string")
+            return limit;
+        return { limit, rest };
+    }
+    // Compact / compound duration: "10m", "90s", "1h30m".
+    const duration = parseCompoundDuration(token);
+    if (duration !== undefined) {
+        if (typeof duration === "string")
+            return duration;
+        return { limit: duration, rest };
+    }
+    // Limit-shaped but unparseable ("-1", "1.5h", "10x10").
+    return LOOP_USAGE;
+}
+/** Split an optional leading `--while` / `--until` flag off the argument
+ *  string. A flag-shaped token that does not parse is a hard error, so a typo
+ *  surfaces instead of silently becoming prompt text. */
+function takeLoopCondition(input) {
+    let rest = input.trim();
+    let condition;
+    while (rest.startsWith("--")) {
+        const name = /^(--[a-z][a-z-]*)(?=[\s=]|$)/.exec(rest)?.[1];
+        const until = name === undefined ? undefined : CONDITION_FLAGS[name];
+        if (name === undefined || until === undefined) {
+            return `unknown /loop flag ${name ?? rest.split(/\s+/, 1)[0]}. ${LOOP_USAGE}`;
+        }
+        if (condition)
+            return "use only one of --while or --until";
+        const afterName = rest.slice(name.length);
+        const valueText = afterName.startsWith("=") ? afterName.slice(1) : afterName;
+        const value = readShellWord(valueText);
+        if (value === "unterminated")
+            return `${name} has an unterminated quote`;
+        if (value === undefined || !value.value.trim() || valueText.trim().startsWith("-")) {
+            return `${name} needs a shell command. Quote it when it contains spaces: /loop ${name} 'bun test'`;
+        }
+        condition = { command: value.value.trim(), until };
+        rest = value.rest;
+    }
+    return { condition, rest };
+}
+/** `--until` stops when the command SUCCEEDS; `--while` stops when it fails. */
+const CONDITION_FLAGS = { "--until": true, "--while": false };
+/** Read one shell word, honoring single/double quotes (the condition is a
+ *  command line, so it usually needs quoting). Returns "unterminated" for an
+ *  unbalanced quote rather than guessing. */
+function readShellWord(input) {
+    const trimmed = input.replace(/^\s+/, "");
+    if (trimmed === "")
+        return undefined;
+    let out = "";
+    let quote;
+    let i = 0;
+    for (; i < trimmed.length; i++) {
+        const ch = trimmed[i];
+        if (quote) {
+            if (ch === quote) {
+                quote = undefined;
+                continue;
+            }
+            out += ch;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            continue;
+        }
+        if (/\s/.test(ch))
+            break;
+        out += ch;
+    }
+    if (quote)
+        return "unterminated";
+    return { value: out, rest: trimmed.slice(i).trim() };
+}
+function makeIterations(amountText) {
+    const amount = Number(amountText);
+    if (!Number.isSafeInteger(amount) || amount <= 0) {
+        return "loop count must be a positive integer";
+    }
+    return { kind: "iterations", iterations: amount };
+}
+function makeDuration(amountText, unitMs) {
+    const amount = Number(amountText);
+    if (!Number.isSafeInteger(amount) || amount <= 0)
+        return "loop duration must be positive";
+    return { kind: "duration", durationMs: amount * unitMs };
+}
+/** `10m`, `90s`, `1h30m`. Undefined when the token is not duration-shaped; an
+ *  error string when it is shaped like one but uses an unknown unit. */
+function parseCompoundDuration(token) {
+    if (!/^(?:\d+[a-z]+)+$/.test(token))
+        return undefined;
+    const segments = token.match(/\d+[a-z]+/g);
+    if (!segments)
+        return undefined;
+    let totalMs = 0;
+    for (const segment of segments) {
+        const match = /^(\d+)([a-z]+)$/.exec(segment);
+        if (!match)
+            return LOOP_USAGE;
+        const unitMs = TIME_UNITS_MS.get(match[2]);
+        if (unitMs === undefined) {
+            return "loop duration unit must be seconds, minutes, or hours";
+        }
+        const amount = Number(match[1]);
+        if (!Number.isSafeInteger(amount) || amount <= 0)
+            return "loop duration must be positive";
+        totalMs += amount * unitMs;
+    }
+    if (totalMs <= 0)
+        return "loop duration must be positive";
+    return { kind: "duration", durationMs: totalMs };
+}
+export function createLoopLimitRuntime(config, nowMs = Date.now()) {
+    if (!config)
+        return undefined;
+    if (config.kind === "iterations") {
+        return { kind: "iterations", initial: config.iterations, remaining: config.iterations };
+    }
+    return { kind: "duration", durationMs: config.durationMs, deadlineMs: nowMs + config.durationMs };
+}
+/** Consume one iteration's budget. False = the limit is exhausted. */
+export function consumeLoopLimitIteration(limit, nowMs = Date.now()) {
+    if (!limit)
+        return true;
+    if (limit.kind === "duration")
+        return nowMs < limit.deadlineMs;
+    if (limit.remaining <= 0)
+        return false;
+    limit.remaining -= 1;
+    return true;
+}
+export function isLoopDurationExpired(limit, nowMs = Date.now()) {
+    return limit?.kind === "duration" && nowMs >= limit.deadlineMs;
+}
+export function describeLoopLimit(config) {
+    if (config.kind === "iterations") {
+        return `${config.iterations} iteration${config.iterations === 1 ? "" : "s"}`;
+    }
+    return formatDuration(config.durationMs);
+}
+export function describeLoopLimitRuntime(limit) {
+    if (limit.kind === "iterations") {
+        return `${limit.remaining}/${limit.initial} iterations left`;
+    }
+    return `${formatDuration(Math.max(0, limit.deadlineMs - Date.now()))} left`;
+}
+function formatDuration(ms) {
+    if (ms < 60_000)
+        return `${Math.round(ms / 1_000)}s`;
+    const minutes = Math.floor(ms / 60_000);
+    const seconds = Math.round((ms % 60_000) / 1_000);
+    if (minutes < 60)
+        return seconds > 0 ? `${minutes}m${seconds}s` : `${minutes}m`;
+    const hours = Math.floor(minutes / 60);
+    const rest = minutes % 60;
+    return rest > 0 ? `${hours}h${rest}m` : `${hours}h`;
+}

package/dist/core/loops/ralph.d.ts

@@ -0,0 +1,37 @@
+import type { LoopConditionConfig } from "./condition.js";
+/** The build loop ("ralph"): one work item per iteration, each iteration in a
+ *  fresh session, with the queue and the repo as the only memory between them.
+ *
+ *  The mechanism is loop mode's (`reset` already restarts the session); what
+ *  this file adds is the discipline that makes the restart survivable — a
+ *  queue on disk, a per-iteration protocol, and the stop condition derived
+ *  from that queue. */
+/** The work queue, relative to the workspace root. Project-scoped, NOT the
+ *  session-keyed plan drafts: every iteration runs in a fresh session, so a
+ *  session-keyed path would hand each iteration a different (empty) file and
+ *  the loop would lose its place — which is the entire point of the queue. */
+export declare const RALPH_QUEUE = ".oma/plan.md";
+/** Continue while an unchecked item remains. The condition runs with the
+ *  workspace root as its cwd; a missing queue exits 2, which the evaluator
+ *  reports as a broken condition rather than as "finished" — deleting the
+ *  queue mid-loop must not read as success. */
+export declare const RALPH_QUEUE_CHECK = "grep -q \"^- \\[ \\]\" .oma/plan.md";
+export declare function ralphQueuePath(workspaceRoot: string): string;
+/** The default stop condition: the queue decides, not the model's opinion of
+ *  its own progress. Overridable — `/loop --until 'bun test'` swaps the
+ *  authority to the verifier. */
+export declare function ralphCondition(): LoopConditionConfig;
+/** One iteration's instructions. The queue is the plan; the model's job is to
+ *  shrink it by exactly one item and leave the repo in a state it can be
+ *  resumed from, because the next iteration remembers nothing else. */
+export declare const RALPH_PROTOCOL = "You are one iteration of an autonomous build loop. You start with a fresh\ncontext every iteration: the repository and .oma/plan.md are the only memory.\nAnother iteration follows you, and it will not see this conversation.\n\n1. Read .oma/plan.md. It is a work queue: `- [ ]` is todo, `- [x]` is done.\n2. Pick the SINGLE most important unchecked item.\n3. Do only that item. Implement it properly; do not start a second one.\n4. Verify with the project's own checks (tests, typecheck, lint). Fix failures\n   before you finish. Never mark an item done while its verification fails.\n5. Mark it `- [x]` in .oma/plan.md. If the work revealed new work, append it\n   as a new `- [ ]` item instead of doing it now \u2014 that is how the queue stays\n   honest.\n6. Commit everything you changed: one commit, message says what the item was.\n   The queue goes in that commit when the project tracks it; if it is ignored,\n   leave it alone rather than forcing it in.\n7. Stop. Do not summarise, do not ask whether to continue.\n\nIf every item is already checked, change nothing and say the queue is empty.";
+/** Create the queue on first use. An existing queue is never touched — it is
+ *  the loop's memory, and rewriting it would discard the loop's progress.
+ *  `item` seeds a single concrete item instead of the "write the queue" stub,
+ *  which turns iteration one into the first build step rather than a planning
+ *  step. */
+export declare function seedRalphQueue(workspaceRoot: string, item?: string): {
+    path: string;
+    created: boolean;
+};
+//# sourceMappingURL=ralph.d.ts.map

package/dist/core/loops/ralph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ralph.d.ts","sourceRoot":"","sources":["../../../src/core/loops/ralph.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAE1D;;;;;;uBAMuB;AAEvB;;;8EAG8E;AAC9E,eAAO,MAAM,WAAW,iBAAiB,CAAC;AAE1C;;;+CAG+C;AAC/C,eAAO,MAAM,iBAAiB,wCAAwC,CAAC;AAEvE,wBAAgB,cAAc,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;iCAEiC;AACjC,wBAAgB,cAAc,IAAI,mBAAmB,CAEpD;AAED;;uEAEuE;AACvE,eAAO,MAAM,cAAc,olCAiBkD,CAAC;AAW9E;;;;YAIY;AACZ,wBAAgB,cAAc,CAC5B,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,MAAM,GACZ;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAQpC"}

package/dist/core/loops/ralph.js

@@ -0,0 +1,72 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+/** The build loop ("ralph"): one work item per iteration, each iteration in a
+ *  fresh session, with the queue and the repo as the only memory between them.
+ *
+ *  The mechanism is loop mode's (`reset` already restarts the session); what
+ *  this file adds is the discipline that makes the restart survivable — a
+ *  queue on disk, a per-iteration protocol, and the stop condition derived
+ *  from that queue. */
+/** The work queue, relative to the workspace root. Project-scoped, NOT the
+ *  session-keyed plan drafts: every iteration runs in a fresh session, so a
+ *  session-keyed path would hand each iteration a different (empty) file and
+ *  the loop would lose its place — which is the entire point of the queue. */
+export const RALPH_QUEUE = ".oma/plan.md";
+/** Continue while an unchecked item remains. The condition runs with the
+ *  workspace root as its cwd; a missing queue exits 2, which the evaluator
+ *  reports as a broken condition rather than as "finished" — deleting the
+ *  queue mid-loop must not read as success. */
+export const RALPH_QUEUE_CHECK = `grep -q "^- \\[ \\]" ${RALPH_QUEUE}`;
+export function ralphQueuePath(workspaceRoot) {
+    return join(workspaceRoot, RALPH_QUEUE);
+}
+/** The default stop condition: the queue decides, not the model's opinion of
+ *  its own progress. Overridable — `/loop --until 'bun test'` swaps the
+ *  authority to the verifier. */
+export function ralphCondition() {
+    return { command: RALPH_QUEUE_CHECK, until: false };
+}
+/** One iteration's instructions. The queue is the plan; the model's job is to
+ *  shrink it by exactly one item and leave the repo in a state it can be
+ *  resumed from, because the next iteration remembers nothing else. */
+export const RALPH_PROTOCOL = `You are one iteration of an autonomous build loop. You start with a fresh
+context every iteration: the repository and ${RALPH_QUEUE} are the only memory.
+Another iteration follows you, and it will not see this conversation.
+
+1. Read ${RALPH_QUEUE}. It is a work queue: \`- [ ]\` is todo, \`- [x]\` is done.
+2. Pick the SINGLE most important unchecked item.
+3. Do only that item. Implement it properly; do not start a second one.
+4. Verify with the project's own checks (tests, typecheck, lint). Fix failures
+   before you finish. Never mark an item done while its verification fails.
+5. Mark it \`- [x]\` in ${RALPH_QUEUE}. If the work revealed new work, append it
+   as a new \`- [ ]\` item instead of doing it now — that is how the queue stays
+   honest.
+6. Commit everything you changed: one commit, message says what the item was.
+   The queue goes in that commit when the project tracks it; if it is ignored,
+   leave it alone rather than forcing it in.
+7. Stop. Do not summarise, do not ask whether to continue.
+
+If every item is already checked, change nothing and say the queue is empty.`;
+const RALPH_STUB = `# Work queue
+
+\`- [ ]\` is todo, \`- [x]\` is done — one item per line, most important first.
+An iteration does exactly one item and then stops.
+
+- [ ] Study the repository and the request, then replace this file with a
+      prioritised queue of concrete, independently verifiable work items.
+`;
+/** Create the queue on first use. An existing queue is never touched — it is
+ *  the loop's memory, and rewriting it would discard the loop's progress.
+ *  `item` seeds a single concrete item instead of the "write the queue" stub,
+ *  which turns iteration one into the first build step rather than a planning
+ *  step. */
+export function seedRalphQueue(workspaceRoot, item) {
+    const path = ralphQueuePath(workspaceRoot);
+    if (existsSync(path))
+        return { path, created: false };
+    const seeded = item?.trim();
+    const body = seeded ? `# Work queue\n\n- [ ] ${seeded}\n` : RALPH_STUB;
+    mkdirSync(join(workspaceRoot, ".oma"), { recursive: true });
+    writeFileSync(path, body, "utf-8");
+    return { path, created: true };
+}