@bubblebrain-ai/bubble 0.0.37 → 0.0.39

package/dist/agent/internal-reminder-sanitizer.js

@@ -167,6 +167,10 @@ const INTERNAL_REASONING_REFERENCE_PATTERNS = [
     /Subagent lifecycle truth/i,
     /Count unique agent_id values only/i,
     /Do not describe a subagent as running or still working/i,
+    /Background task truth/i,
+    /Never re-run work a finished task already did/i,
+    /Large-change checkpoint/i,
+    /delegation only adds merge risk/i,
 ];
 function consumeInternalBlockAtStart(text, final) {
     if (text.startsWith(INTERNAL_TAG_PREFIX)) {

package/dist/agent/profiles.d.ts

@@ -56,6 +56,12 @@ export interface AgentProfileDiagnostic {
 export type AgentProfileScope = "user" | "project" | "both";
 export declare function discoverAgentProfiles(cwd: string, scope?: AgentProfileScope): DiscoverAgentProfilesResult;
 export declare function builtinAgentProfiles(): AgentProfile[];
+/**
+ * The delegation nudge only fires when a write-capable spawn surface exists
+ * (large-task-delegation design §3): defense in depth for hosts that strip
+ * or override the builtin profiles.
+ */
+export declare function hasWriteWorktreeProfile(profiles: AgentProfile[]): boolean;
 export declare function findAgentProfile(profiles: AgentProfile[], name: string): AgentProfile | undefined;
 export declare function assignAgentNickname(profile: AgentProfile, activeNicknames?: Iterable<string>): string;
 /**

package/dist/agent/profiles.js

@@ -134,8 +134,40 @@ export function builtinAgentProfiles() {
         toProfile("security_investigation"),
         toProfile("evidence_correlation"),
         toProfile("general_readonly"),
+        // The write-capable builtin (large-task-delegation design §3): before
+        // this, write_worktree was reachable only via user-authored profile
+        // frontmatter, so the delegation nudge would have recommended a surface
+        // that does not exist in a stock session.
+        {
+            name: "implementer",
+            description: "Write-capable implementation subagent (isolated git worktree)",
+            source: "builtin",
+            mode: "write_worktree",
+            model: "inherit",
+            tools: {
+                preset: "explicit",
+                include: ["read", "glob", "grep", "edit", "write", "bash", "lsp", "todo_write"],
+                exclude: [],
+            },
+            approval: "fail",
+            nicknameCandidates: DEFAULT_NICKNAME_CANDIDATES,
+            prompt: [
+                "You are an implementer subagent working in your own isolated git worktree — the parent tree is never touched.",
+                "Your worktree forks from the last commit; changes the parent made after that commit are NOT present unless included in your briefing.",
+                "Make the smallest coherent edits that complete your assigned group. Stay strictly inside the file set you were given; if a needed change falls outside it, report that instead of editing.",
+                "Verify your changes narrowly (targeted tests or typecheck) when possible, and end with a concise summary of files changed and verification results — the parent reviews and applies your worktree.",
+            ].join("\n"),
+        },
     ];
 }
+/**
+ * The delegation nudge only fires when a write-capable spawn surface exists
+ * (large-task-delegation design §3): defense in depth for hosts that strip
+ * or override the builtin profiles.
+ */
+export function hasWriteWorktreeProfile(profiles) {
+    return profiles.some((profile) => profile.mode === "write_worktree");
+}
 export function findAgentProfile(profiles, name) {
     return profiles.find((profile) => profile.name === name)
         ?? profiles.find((profile) => profile.name === `builtin:${name}`);

package/dist/agent/task-lifecycle-reminder.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Background-task lifecycle reminder (background-tasks design §2.3a).
+ *
+ * Emission is STATE-CHANGE gated, never per-model-call: the reminder channel
+ * is append-only (each injection is a persistent meta message that survives
+ * pruning and compaction), so the caller compares the manager's task state
+ * version and builds a reminder only when the owned task set changed since
+ * the last emission. This mirrors the subagent lifecycle reminder's activity
+ * gate rather than firing while tasks are merely alive.
+ *
+ * Because compaction preserves meta messages but drops session markers, this
+ * reminder is also how the model recovers task ids after /compact.
+ */
+import type { BackgroundTaskInfo } from "../tasks/manager.js";
+export interface TaskReminderInput {
+    tasks: BackgroundTaskInfo[];
+    outputTail: (id: string) => string | undefined;
+    /**
+     * The task tools are already unlocked (the spawn path calls
+     * unlockDeferredTools). When true the tool_search hint is dropped — field
+     * test 2026-07-19 showed the unconditional hint makes the model burn a
+     * tool_search call for tools it already has.
+     */
+    toolsAvailable?: boolean;
+}
+export declare function buildTaskLifecycleReminder({ tasks, outputTail, toolsAvailable }: TaskReminderInput): string | undefined;

package/dist/agent/task-lifecycle-reminder.js

@@ -0,0 +1,59 @@
+/**
+ * Background-task lifecycle reminder (background-tasks design §2.3a).
+ *
+ * Emission is STATE-CHANGE gated, never per-model-call: the reminder channel
+ * is append-only (each injection is a persistent meta message that survives
+ * pruning and compaction), so the caller compares the manager's task state
+ * version and builds a reminder only when the owned task set changed since
+ * the last emission. This mirrors the subagent lifecycle reminder's activity
+ * gate rather than firing while tasks are merely alive.
+ *
+ * Because compaction preserves meta messages but drops session markers, this
+ * reminder is also how the model recovers task ids after /compact.
+ */
+const OUTPUT_TAIL_CHARS = 2000;
+export function buildTaskLifecycleReminder({ tasks, outputTail, toolsAvailable }) {
+    if (tasks.length === 0)
+        return undefined;
+    const running = tasks.filter((task) => task.status === "running");
+    const finishedUndelivered = tasks.filter((task) => task.status !== "running" && task.deliveredAt === undefined);
+    const finishedDelivered = tasks.filter((task) => task.status !== "running" && task.deliveredAt !== undefined);
+    if (running.length === 0 && finishedUndelivered.length === 0 && finishedDelivered.length === 0) {
+        return undefined;
+    }
+    const lines = ["Background task truth:"];
+    for (const task of running) {
+        const elapsed = Math.round((Date.now() - task.startedAt) / 1000);
+        lines.push(`- running: ${task.id} (${label(task)}, ${elapsed}s elapsed)`);
+    }
+    for (const task of finishedUndelivered) {
+        const elapsed = Math.round(((task.endedAt ?? Date.now()) - task.startedAt) / 1000);
+        lines.push(`- finished since last update: ${task.id} (${label(task)}) ${task.status}${task.exitCode != null ? ` exit ${task.exitCode}` : ""} in ${elapsed}s`);
+        const tail = outputTail(task.id)?.trim();
+        if (tail) {
+            lines.push(`  output tail:`);
+            lines.push(...clampTail(tail).split("\n").map((line) => `    ${line}`));
+            lines.push("  Call task_output only if you need more of the output.");
+        }
+    }
+    // Delivered final results already reached the model in full — id + status
+    // only, never the output again (mirrors the subagent delivered demotion).
+    for (const task of finishedDelivered) {
+        lines.push(`- delivered: ${task.id} ${task.status}${task.exitCode != null ? ` (exit ${task.exitCode})` : ""}`);
+    }
+    lines.push(toolsAvailable
+        ? "- Check tasks with task_output; stop them with kill_task. Both are already in your tool list — do NOT call tool_search for them."
+        : "- Check tasks with task_output; stop them with kill_task (deferred: load via tool_search with query 'select:task_output,kill_task' if not yet available).");
+    lines.push("- Never re-run work a finished task already did; never poll with foreground sleep.");
+    return lines.join("\n");
+}
+function label(task) {
+    return task.description?.trim() || truncate(task.command, 60);
+}
+function clampTail(tail) {
+    return tail.length <= OUTPUT_TAIL_CHARS ? tail : `…${tail.slice(-OUTPUT_TAIL_CHARS)}`;
+}
+function truncate(value, max) {
+    const oneLine = value.replace(/\s+/g, " ").trim();
+    return oneLine.length <= max ? oneLine : `${oneLine.slice(0, max - 1)}…`;
+}

package/dist/agent.d.ts

@@ -101,6 +101,25 @@ export declare class Agent {
     messages: Message[];
     private provider;
     private sessionID?;
+    /**
+     * Bridge to the unified process manager's background tasks, wired by the
+     * host (main.ts) when the host supports them (background-tasks design
+     * §2.3a). list() is pre-filtered to the agent's bound session.
+     */
+    backgroundTasks?: {
+        list: () => import("./tasks/manager.js").BackgroundTaskInfo[];
+        version: () => number;
+        outputTail: (id: string) => string | undefined;
+    };
+    private lastTaskReminderVersion;
+    /**
+     * Once-per-session latch for the large-task delegation nudge
+     * (large-task-delegation design §2): goal-loop continuations rebuild
+     * TurnHookState every run, so a per-turn latch would nag on every turn.
+     * If the model read the nudge once and chose not to delegate, repeating
+     * it is noise.
+     */
+    largeTaskNudgeConsumed: boolean;
     private _providerId;
     private _model;
     private tools;
@@ -165,6 +184,21 @@ export declare class Agent {
      * the prompt's tool list.
      */
     injectDeferredToolsReminder(): void;
+    /**
+     * Rebinds the agent to a new session (TUI session switch). Keeps
+     * ownerSessionId on newly spawned background tasks and managed servers
+     * accurate (background-tasks design §2.2c).
+     */
+    setSessionID(sessionID: string | undefined): void;
+    getSessionID(): string | undefined;
+    /**
+     * Background-task reminder, state-change gated (design §2.3a): returns a
+     * reminder only when the owned task set changed since the last emission
+     * (started/finished/killed). The reminder channel is append-only, so
+     * emitting on every model call while tasks are merely alive would stack
+     * persistent duplicates that neither pruning nor compaction removes.
+     */
+    consumeBackgroundTaskReminder(): string | undefined;
     private runExternalHook;
     private injectHookModelContext;
     /** Whether a tool is registered on this agent (e.g. delegation tools on parents). */
@@ -269,6 +303,15 @@ export declare class Agent {
         abortSignal?: AbortSignal;
     }): Promise<SubagentThreadSnapshot>;
     closeSubAgent(agentId: string): Promise<SubagentThreadSnapshot>;
+    /**
+     * Live (non-final) children only — the delegation-nudge gate
+     * (large-task-delegation design §2). listSubAgents() is a grows-only
+     * session history (finished + resumed children stay forever), so it must
+     * never be used to answer "am I currently delegating?".
+     */
+    activeSubAgentCount(): number;
+    /** run_workflow children are workflowInternal and invisible to listSubAgents. */
+    hasRunningWorkflow(): boolean;
     listSubAgents(): SubagentThreadSnapshot[];
     /**
      * Dynamic workflow (option C): runs an LLM-authored JS orchestration script in

package/dist/agent.js

@@ -19,6 +19,8 @@ import { buildDeferredToolsReminder, buildToolFreezeReminder, reminderForMode }
 import { HookBus } from "./orchestrator/hooks.js";
 import { normalizeHookInput, truncateHookText, } from "./hooks/index.js";
 import { createDefaultHooks } from "./orchestrator/default-hooks.js";
+import { buildTaskLifecycleReminder } from "./agent/task-lifecycle-reminder.js";
+import { classifyTask } from "./agent/task-classifier.js";
 import { mergeAgentCategories, parseThinkingLevel, resolveModelRoute, resolveSubagentRoute } from "./agent/categories.js";
 import { DEFAULT_AGENT_ROUTING, nearModelMatches, sanitizeAgentRouting, tierContextFromSnapshot } from "./agent/routing-catalog.js";
 import { buildModelRoutingPrompt } from "./prompt/routing.js";
@@ -100,6 +102,21 @@ export class Agent {
     messages = [];
     provider;
     sessionID;
+    /**
+     * Bridge to the unified process manager's background tasks, wired by the
+     * host (main.ts) when the host supports them (background-tasks design
+     * §2.3a). list() is pre-filtered to the agent's bound session.
+     */
+    backgroundTasks;
+    lastTaskReminderVersion = -1;
+    /**
+     * Once-per-session latch for the large-task delegation nudge
+     * (large-task-delegation design §2): goal-loop continuations rebuild
+     * TurnHookState every run, so a per-turn latch would nag on every turn.
+     * If the model read the nudge once and chose not to delegate, repeating
+     * it is noise.
+     */
+    largeTaskNudgeConsumed = false;
     _providerId;
     _model;
     tools = new Map();
@@ -261,6 +278,37 @@ export class Agent {
             this.injectSystemReminder(buildDeferredToolsReminder(deferredNames));
         }
     }
+    /**
+     * Rebinds the agent to a new session (TUI session switch). Keeps
+     * ownerSessionId on newly spawned background tasks and managed servers
+     * accurate (background-tasks design §2.2c).
+     */
+    setSessionID(sessionID) {
+        this.sessionID = sessionID;
+    }
+    getSessionID() {
+        return this.sessionID;
+    }
+    /**
+     * Background-task reminder, state-change gated (design §2.3a): returns a
+     * reminder only when the owned task set changed since the last emission
+     * (started/finished/killed). The reminder channel is append-only, so
+     * emitting on every model call while tasks are merely alive would stack
+     * persistent duplicates that neither pruning nor compaction removes.
+     */
+    consumeBackgroundTaskReminder() {
+        if (!this.backgroundTasks)
+            return undefined;
+        const version = this.backgroundTasks.version();
+        if (version === this.lastTaskReminderVersion)
+            return undefined;
+        this.lastTaskReminderVersion = version;
+        return buildTaskLifecycleReminder({
+            tasks: this.backgroundTasks.list(),
+            outputTail: (id) => this.backgroundTasks?.outputTail(id),
+            toolsAvailable: this.unlockedDeferred?.has("task_output") ?? false,
+        });
+    }
     async runExternalHook(request, abortSignal) {
         const events = [];
         if (!this.externalHooks) {
@@ -509,6 +557,15 @@ export class Agent {
                 events.push(...hook.events);
                 this.injectHookModelContext(hook.result);
                 this.appendMessage({ role: "user", content: input.content });
+                // Large-task detector (large-task-delegation design §1): a steer
+                // redirects the task — stale breadth evidence must not fire a nudge
+                // about the pre-steer task, and the classifier should reason about
+                // the redirected one.
+                hookState.exploredFiles?.clear();
+                hookState.largeTaskCheckpointDone = false;
+                if (typeof input.content === "string" && input.content.trim()) {
+                    hookState.taskType = classifyTask(input.content);
+                }
                 events.push({
                     type: "input_applied",
                     id: input.id,
@@ -1636,6 +1693,19 @@ export class Agent {
         this.subagentStore.notifyWaiters(record);
         return this.snapshotSubagent(record);
     }
+    /**
+     * Live (non-final) children only — the delegation-nudge gate
+     * (large-task-delegation design §2). listSubAgents() is a grows-only
+     * session history (finished + resumed children stay forever), so it must
+     * never be used to answer "am I currently delegating?".
+     */
+    activeSubAgentCount() {
+        return this.subagentStore.activeCount();
+    }
+    /** run_workflow children are workflowInternal and invisible to listSubAgents. */
+    hasRunningWorkflow() {
+        return [...this.workflowRuns.values()].some((record) => record.status === "running");
+    }
     listSubAgents() {
         return this.subagentStore.values()
             .filter((record) => !record.workflowInternal)

package/dist/approval/controller.d.ts

@@ -33,7 +33,9 @@ export interface ApprovalControllerOptions {
  *
  *   deny rule match              → reject (applies even under bypassPermissions)
  *   bypassPermissions            → auto-approve, no prompt
- *   default + edit|write         → auto-approve
+ *   default + edit|write         → auto-approve (workspace paths only; a
+ *                                  path outside the workspace falls through
+ *                                  to allow rules / the interactive prompt)
  *   plan                         → reject with instructions to use exit_plan_mode
  *   allow rule match             → auto-approve
  *   bash in session allowlist    → auto-approve

package/dist/approval/controller.js

@@ -5,7 +5,9 @@ import { truncateHookText } from "../hooks/index.js";
  *
  *   deny rule match              → reject (applies even under bypassPermissions)
  *   bypassPermissions            → auto-approve, no prompt
- *   default + edit|write         → auto-approve
+ *   default + edit|write         → auto-approve (workspace paths only; a
+ *                                  path outside the workspace falls through
+ *                                  to allow rules / the interactive prompt)
  *   plan                         → reject with instructions to use exit_plan_mode
  *   allow rule match             → auto-approve
  *   bash in session allowlist    → auto-approve
@@ -46,7 +48,8 @@ export class PermissionAwareApprovalController {
         if (mode === "bypassPermissions") {
             return finalize({ action: "approve" });
         }
-        if (mode === "default" && (req.type === "edit" || req.type === "write" || req.type === "patch")) {
+        const outsideWorkspace = (req.type === "edit" || req.type === "write") && req.outsideWorkspace === true;
+        if (mode === "default" && !outsideWorkspace && (req.type === "edit" || req.type === "write" || req.type === "patch")) {
             return finalize({ action: "approve" });
         }
         // Project profile trust is a user decision, not a destructive action:

package/dist/approval/tool-helper.js

@@ -16,7 +16,16 @@ export async function gateToolAction(approval, req) {
     const message = feedback
         ? `${label} was rejected by the user. User feedback: ${feedback}`
         : `${label} was rejected by the user.`;
-    return { approved: false, result: { content: message, isError: true } };
+    return {
+        approved: false,
+        result: {
+            content: message,
+            isError: true,
+            // Surfaces the rejection reason in subagent tool notes (which prefer
+            // metadata.reason over the truncated first content line).
+            metadata: { kind: "security", reason: feedback || message },
+        },
+    };
 }
 function approvalRequestLabel(req) {
     switch (req.type) {

package/dist/approval/types.d.ts

@@ -12,6 +12,12 @@ export interface EditApprovalRequest {
     /** Unified patch (with context lines) to show the user. */
     diff: string;
     fileExists: boolean;
+    /**
+     * The path resolves outside the session workspace. Escalates the request
+     * past default-mode auto-approval so the user explicitly confirms it
+     * (bypassPermissions still auto-approves, consistent with bash).
+     */
+    outsideWorkspace?: boolean;
 }
 export interface WriteApprovalRequest {
     type: "write";
@@ -21,6 +27,8 @@ export interface WriteApprovalRequest {
     /** Unified patch from existing contents to pending contents. */
     diff?: string;
     fileExists: boolean;
+    /** See EditApprovalRequest.outsideWorkspace. */
+    outsideWorkspace?: boolean;
 }
 export interface PatchApprovalRequest {
     type: "patch";
@@ -39,6 +47,13 @@ export interface BashApprovalRequest {
     type: "bash";
     command: string;
     cwd: string;
+    /**
+     * The command will run as a background task that outlives the turn
+     * (background-tasks design §2.4). Shown in the approval dialog and passed
+     * to permission hooks so org policy can discriminate; allow rules, the
+     * session allowlist, and bypass approve it like foreground by design.
+     */
+    background?: boolean;
 }
 export interface LspApprovalRequest {
     type: "lsp";

package/dist/cli.d.ts

@@ -11,6 +11,8 @@ export interface CliArgs {
     resume?: boolean;
     sessionName?: string;
     print?: boolean;
+    /** Print-mode output: plain (default) or a single JSON object on stdout. */
+    outputFormat?: "plain" | "json";
     prompt?: string;
     thinkingLevel?: ThinkingLevel;
     mode?: PermissionMode;

package/dist/cli.js

@@ -55,6 +55,15 @@ export function parseArgs(argv) {
             case "-p":
                 args.print = true;
                 break;
+            case "--output-format": {
+                const value = argv[++i];
+                if (value !== "plain" && value !== "json") {
+                    console.error(`Invalid --output-format: ${value ?? "(missing)"}. Expected plain or json.`);
+                    process.exit(1);
+                }
+                args.outputFormat = value;
+                break;
+            }
             case "--plan":
                 args.mode = "plan";
                 break;
@@ -108,6 +117,8 @@ Options (default):
   --dangerously-skip-permissions
                            Enable bypass mode (auto-approve EVERY tool; disables all safety prompts)
   -p, --print              Non-interactive mode (single prompt)
+  --output-format <fmt>    Print-mode output: plain (default) or json
+                           (one JSON object on stdout: text, usage, num_turns)
   -v, --version            Print the installed version and exit
   -h, --help               Show this help
 

package/dist/config.d.ts

@@ -35,6 +35,10 @@ export interface UserConfigData {
     /** Subagent model-routing knobs: autoTier (default true), allowCrossProvider (default true). */
     agentRouting?: Partial<AgentRoutingConfig>;
     subagents?: SubagentsUserConfig;
+    /** Background tasks (design §2.3b): autoResume defaults ON; false keeps notices + reminders only. */
+    tasks?: {
+        autoResume?: boolean;
+    };
 }
 export interface SubagentsUserConfig {
     /** Global cap on concurrently running children. Default 8. */
@@ -50,6 +54,8 @@ export declare class UserConfig {
     getDefaultThinkingLevel(): ThinkingLevel | undefined;
     setDefaultThinkingLevel(level: ThinkingLevel): void;
     getRecentModels(): string[];
+    /** Auto-resume on background-task completion (design §2.3b). Default ON. */
+    getTasksAutoResume(): boolean;
     pushRecentModel(model: string): void;
     getApiKey(): string | undefined;
     setApiKey(key: string): void;

package/dist/config.js

@@ -139,6 +139,10 @@ export class UserConfig {
     getRecentModels() {
         return sanitizeRecentModels(this.data.recentModels)?.slice() ?? [];
     }
+    /** Auto-resume on background-task completion (design §2.3b). Default ON. */
+    getTasksAutoResume() {
+        return this.data.tasks?.autoResume !== false;
+    }
     pushRecentModel(model) {
         if (isHiddenProviderId(modelProviderId(model))) {
             return;

package/dist/loop/engine.d.ts

@@ -0,0 +1,29 @@
+/**
+ * /loop — recurring prompts (background-tasks design §2.6).
+ *
+ * Pure decision logic kept out of the TUI, mirroring goal/engine.ts: the TUI
+ * owns a 1s ticker and calls decideLoopFiring per loop; this module owns
+ * parsing, caps, and the defer-not-stack rule (a firing due while a turn is
+ * running reschedules with a notice instead of piling up).
+ */
+export interface LoopState {
+    id: number;
+    prompt: string;
+    intervalMs: number;
+    nextFireAt: number;
+    fires: number;
+}
+export declare const MAX_ACTIVE_LOOPS = 5;
+export declare const MIN_LOOP_INTERVAL_MS = 60000;
+export interface ParsedLoopCommand {
+    action: "start" | "list" | "stop" | "help";
+    intervalMs?: number;
+    prompt?: string;
+    stopId?: number;
+    error?: string;
+}
+export declare function parseLoopCommand(raw: string): ParsedLoopCommand;
+export type LoopFiringDecision = "fire" | "defer" | "wait";
+export declare function decideLoopFiring(loop: LoopState, now: number, turnRunning: boolean): LoopFiringDecision;
+export declare function formatLoopList(loops: LoopState[], now: number): string;
+export declare function formatInterval(intervalMs: number): string;

package/dist/loop/engine.js

@@ -0,0 +1,63 @@
+/**
+ * /loop — recurring prompts (background-tasks design §2.6).
+ *
+ * Pure decision logic kept out of the TUI, mirroring goal/engine.ts: the TUI
+ * owns a 1s ticker and calls decideLoopFiring per loop; this module owns
+ * parsing, caps, and the defer-not-stack rule (a firing due while a turn is
+ * running reschedules with a notice instead of piling up).
+ */
+export const MAX_ACTIVE_LOOPS = 5;
+export const MIN_LOOP_INTERVAL_MS = 60_000;
+export function parseLoopCommand(raw) {
+    const rest = raw.trim().replace(/^\/loop\s*/, "").trim();
+    if (!rest)
+        return { action: "help" };
+    if (rest === "list")
+        return { action: "list" };
+    const stop = rest.match(/^stop(?:\s+(\d+))?$/);
+    if (stop) {
+        return { action: "stop", stopId: stop[1] ? Number(stop[1]) : undefined };
+    }
+    const match = rest.match(/^(\d+)([smh])\s+(.+)$/s);
+    if (!match) {
+        return {
+            action: "start",
+            error: "Usage: /loop <interval> <prompt> — interval like 90s, 5m, 1h (min 60s). Also: /loop list, /loop stop [id].",
+        };
+    }
+    const value = Number(match[1]);
+    const unit = match[2];
+    const multiplier = unit === "s" ? 1000 : unit === "m" ? 60_000 : 3_600_000;
+    const intervalMs = Math.max(MIN_LOOP_INTERVAL_MS, value * multiplier);
+    const prompt = match[3].trim();
+    if (!prompt) {
+        return { action: "start", error: "Usage: /loop <interval> <prompt> — the prompt is required." };
+    }
+    return { action: "start", intervalMs, prompt };
+}
+export function decideLoopFiring(loop, now, turnRunning) {
+    if (now < loop.nextFireAt)
+        return "wait";
+    return turnRunning ? "defer" : "fire";
+}
+export function formatLoopList(loops, now) {
+    if (loops.length === 0)
+        return "No active loops. Start one with /loop <interval> <prompt>.";
+    return loops
+        .map((loop) => {
+        const nextIn = Math.max(0, Math.round((loop.nextFireAt - now) / 1000));
+        return `#${loop.id} every ${formatInterval(loop.intervalMs)} · fired ${loop.fires}x · next in ${nextIn}s · ${truncate(loop.prompt, 60)}`;
+    })
+        .join("\n");
+}
+export function formatInterval(intervalMs) {
+    if (intervalMs % 3_600_000 === 0)
+        return `${intervalMs / 3_600_000}h`;
+    if (intervalMs % 60_000 === 0)
+        return `${intervalMs / 60_000}m`;
+    return `${Math.round(intervalMs / 1000)}s`;
+}
+function truncate(value, max) {
+    const oneLine = value.replace(/\s+/g, " ").trim();
+    return oneLine.length <= max ? oneLine : `${oneLine.slice(0, max - 1)}…`;
+}