loopengine 0.2.2 → 0.3.1

package/dist/core/system-agents/workflow-planner.js

@@ -17,8 +17,10 @@ How to plan:
 3. Rules: every tool the workflow uses gets one. Reading and searching: allow. Anything a person should see first (sending, publishing, paying, creating something others see): ask. Never set deny unless asked.
 4. Skill: the steps in order, as numbered instructions the agent follows, naming the tools and saying exactly when to stop and ask. Write it so the agent keeps going after each answer or decision.
 5. Trigger: a schedule ("every Monday at 9" is every "7d", at "09:00", weekday 1) or on_request (started from Chat or a message). startMessage is what the agent receives when it starts.
-6. Target: an existing agent only when it already has (or can install) the tools, none of the workflow's rules would change a decision it already has, and the same people would approve. Otherwise a new agent, with a short lowercase-hyphenated name and a system prompt saying who it is and what it's for. Give the reason either way.
-7. keys: the setting names its abilities need that list_connections or the agents don't show as set (from ability_details settings). Not for MCP servers: their keys are asked for on the plan.
+6. Notify (scheduled workflows): whether each run's result is sent to the person through the agent's messaging app. true when the result is for them and no step already delivers it ("tell me", "send me", "let me know", a summary or findings that no step posts or emails). false when a step already sends it (posting to a channel, emailing a report): it would arrive twice. false when the work itself is the outcome (answering emails, filing tasks), where a message every run is noise; questions and approvals reach them either way. Say why in one short sentence.
+7. Parameters: if the job is about something that changes from run to run (an order, a ticket, an alert, a customer, a date range), declare it as a parameter: a short snake_case name, a one-line description, and required when a run makes no sense without it. Write $name wherever its value goes, in startMessage and in the skill ("Check the refund request for order $order_number."). Apps and people fill them in when they start a run. A scheduled job that finds its own work ("check the inbox every 10 minutes", "last week's sales") needs none. Don't make fixed settings, such as the repository or the channel, parameters: write them into the skill.
+8. Target: an existing agent only when it already has (or can install) the tools, none of the workflow's rules would change a decision it already has, and the same people would approve. Otherwise a new agent, with a short lowercase-hyphenated name and a system prompt saying who it is and what it's for. Give the reason either way.
+9. keys: the setting names its abilities need that list_connections or the agents don't show as set (from ability_details settings). Not for MCP servers: their keys are asked for on the plan.
 
 Then call save_plan once, with the whole plan. Don't ask the person questions: if something is unclear, plan the most reasonable version and note the assumption in gaps.`;
 export function workflowPlannerTools(withMcp = false) {
@@ -72,6 +74,17 @@ export function workflowPlannerTools(withMcp = false) {
                     needsApprovals: { type: 'boolean' },
                     skill: { type: 'object', properties: { description: { type: 'string' }, body: { type: 'string' } }, required: ['description', 'body'] },
                     startMessage: { type: 'string' },
+                    notify: {
+                        type: 'object',
+                        description: 'Scheduled workflows: whether each run\'s result goes to the person through the agent\'s messaging app, and why in one short sentence.',
+                        properties: { on: { type: 'boolean' }, reason: { type: 'string' } },
+                        required: ['on', 'reason'],
+                    },
+                    parameters: {
+                        type: 'object',
+                        description: 'Values each run is given, by snake_case name; use $name in startMessage and the skill. Leave out when every run is the same.',
+                        additionalProperties: { type: 'object', properties: { description: { type: 'string' }, required: { type: 'boolean' } } },
+                    },
                     target: { type: 'object', properties: { kind: { type: 'string', enum: ['existing', 'new'] }, agent: { type: 'string' }, reason: { type: 'string' } }, required: ['kind', 'reason'] },
                     newAgent: { type: 'object', properties: { name: { type: 'string' }, systemPrompt: { type: 'string' } }, required: ['name', 'systemPrompt'] },
                     gaps: { type: 'array', items: { type: 'string' } },
@@ -156,6 +169,9 @@ export function validateWorkflowPlan(raw) {
         ])].filter((spec) => !steps.some((s) => s.connection === spec && s.ability !== spec));
     const targetRaw = (r.target ?? {});
     const id = slugify(str(r.id, 60) ?? name);
+    const startMessage = str(r.startMessage, 1000) ?? `Run the "${name}" workflow.`;
+    const gaps = Array.isArray(r.gaps) ? r.gaps.flatMap((g) => (str(g, 400) ? [str(g, 400)] : [])).slice(0, 10) : [];
+    const planned = planParameters(r.parameters, { startMessage, skillBody, scheduled: trigger.kind === 'schedule' });
     return {
         name,
         id,
@@ -167,16 +183,52 @@ export function validateWorkflowPlan(raw) {
         keys: Array.isArray(r.keys) ? [...new Set(r.keys.flatMap((k) => (str(k, 80) ? [str(k, 80)] : [])))] : [],
         needsApprovals: r.needsApprovals === true || steps.some((s) => s.kind === 'ask' || s.kind === 'approval'),
         skill: { description: str(skillRaw.description, 400) ?? summary, body: skillBody },
-        startMessage: str(r.startMessage, 1000) ?? `Run the "${name}" workflow.`,
+        startMessage,
+        parameters: planned.parameters,
+        notify: planNotify(r.notify),
         target: {
             kind: targetRaw.kind === 'existing' && str(targetRaw.agent, 80) ? 'existing' : 'new',
             ...(targetRaw.kind === 'existing' && str(targetRaw.agent, 80) ? { agent: str(targetRaw.agent, 80) } : {}),
             reason: str(targetRaw.reason, 600) ?? '',
         },
         newAgent: { name: slugify(str(agentRaw.name, 60) ?? id, id), systemPrompt },
-        gaps: Array.isArray(r.gaps) ? r.gaps.flatMap((g) => (str(g, 400) ? [str(g, 400)] : [])).slice(0, 10) : [],
+        gaps: [...gaps, ...planned.notes].slice(0, 12),
     };
 }
+/** A plan's notify choice; off when the planner gave none. */
+export function planNotify(raw) {
+    const n = raw && typeof raw === 'object' ? raw : {};
+    return { on: n.on === true, reason: typeof n.reason === 'string' ? n.reason.trim().slice(0, 200) : '' };
+}
+/** A plan's parameters, tidied: names made snake_case (or dropped), a
+ * $name the start message or skill uses but doesn't declare added as an
+ * optional one, and, for a scheduled workflow, required ones made
+ * optional (a schedule has no one to fill them in), with a note saying
+ * so. Also used on a plan edited before Create. */
+export function planParameters(raw, context) {
+    const parameters = {};
+    const notes = [];
+    if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+        for (const [rawName, spec] of Object.entries(raw)) {
+            const name = rawName.trim().toLowerCase().replace(/[^a-z0-9_]+/g, '_').replace(/^[^a-z_]+/, '').replace(/_+/g, '_').replace(/_$/, '').slice(0, 40);
+            if (!name || parameters[name])
+                continue;
+            const s = spec && typeof spec === 'object' ? spec : {};
+            parameters[name] = { description: typeof s.description === 'string' ? s.description.trim().slice(0, 300) : '', required: s.required === true };
+        }
+    }
+    for (const match of `${context.startMessage}\n${context.skillBody}`.matchAll(/\$([a-z_][a-z0-9_]*)/g)) {
+        parameters[match[1]] ??= { description: '', required: false };
+    }
+    if (context.scheduled) {
+        const required = Object.entries(parameters).filter(([, p]) => p.required);
+        for (const [, p] of required)
+            p.required = false;
+        if (required.length)
+            notes.push(`A schedule can't fill in ${required.map(([n]) => n).join(', ')}, so ${required.length > 1 ? 'they are' : 'it is'} optional; give ${required.length > 1 ? 'them' : 'it'} a value on the schedule, or start runs by hand or from an app.`);
+    }
+    return { parameters, notes };
+}
 /** Runs the planner on a description until it saves a plan. */
 export async function planWorkflowWithModel(modelCall, description, tools) {
     const messages = [{ role: 'user', content: `Plan this workflow:\n\n${description}` }];
@@ -284,7 +336,7 @@ export function workflowTemplate(plan) {
             skills: [{ id: plan.id, description: plan.skill.description, body: plan.skill.body }],
             rules: plan.rules.map((r) => ({ name: slugify(`${plan.id}-${r.tool}`, `${plan.id}-rule`), tool: r.tool, decision: r.decision })),
             ...(plan.trigger.kind === 'schedule' && plan.trigger.every
-                ? { schedule: { every: plan.trigger.every, ...(plan.trigger.at ? { at: plan.trigger.at } : {}), ...(plan.trigger.weekday !== undefined ? { weekday: plan.trigger.weekday } : {}), name: plan.name, message: plan.startMessage } }
+                ? { schedule: { every: plan.trigger.every, ...(plan.trigger.at ? { at: plan.trigger.at } : {}), ...(plan.trigger.weekday !== undefined ? { weekday: plan.trigger.weekday } : {}), name: plan.name, message: plan.startMessage, workflowId: plan.id, ...(plan.notify?.on ? { notify: true } : {}) } }
                 : {}),
             needsApprovals: plan.needsApprovals,
         },

package/dist/core/system-tools/schedule.d.ts

@@ -1,2 +1,6 @@
 import type { ToolDefinition } from '../agent-config.js';
-export declare function createScheduleTools(agentName: string): ToolDefinition[];
+/** `agentDir`: the agent's folder, where its workflows are listed
+ * (workflows.yml). Without it the agent can only schedule messages. */
+export declare function createScheduleTools(agentName: string, options?: {
+    agentDir?: string;
+}): ToolDefinition[];

package/dist/core/system-tools/schedule.js

@@ -1,5 +1,6 @@
 import { cancelScheduledTask, createScheduledTask, getScheduledTask, listScheduledTasks, } from '../scheduler.js';
 import { formatWallTime, workspaceTimeZone } from '../time-zone.js';
+import { readWorkflows, validateParams } from '../workflows.js';
 /** How many active (not done or cancelled) tasks one agent may create
  * through these tools — each run is a model call, so a runaway loop of
  * "schedule another one" stops here. The console and API aren't capped. */
@@ -16,7 +17,7 @@ function summary(t, timeZone) {
     return {
         task_id: t.task_id,
         task_name: t.task_name,
-        message: t.message,
+        ...(t.workflow_id ? { workflow_id: t.workflow_id, ...(t.params ? { params: t.params } : {}) } : { message: t.message }),
         schedule: t.schedule,
         status: t.status,
         next_run_at: t.next_run_at,
@@ -25,10 +26,18 @@ function summary(t, timeZone) {
         last_status: t.last_status,
     };
 }
-export function createScheduleTools(agentName) {
-    // Read once per run: the time zone is in the tool description, which
-    // should stay the same from call to call.
+/** `agentDir`: the agent's folder, where its workflows are listed
+ * (workflows.yml). Without it the agent can only schedule messages. */
+export function createScheduleTools(agentName, options = {}) {
+    // Read once per run: the time zone and the workflows are in the tool
+    // description, which should stay the same from call to call.
     const timeZone = workspaceTimeZone();
+    const workflows = options.agentDir ? readWorkflows(options.agentDir) : [];
+    const paramList = (w) => {
+        const names = Object.entries(w.parameters).map(([name, p]) => `${name}${p.required ? '' : '?'}`);
+        return names.length ? `; params: ${names.join(', ')}` : '';
+    };
+    const workflowList = workflows.map((w) => `"${w.id}" (${w.title}: ${w.description}${paramList(w)})`).join('; ');
     async function ownTask(taskId, tool) {
         const task = await getScheduledTask(taskId);
         // Another agent's task reads exactly like a missing one.
@@ -38,14 +47,24 @@ export function createScheduleTools(agentName) {
     }
     const scheduleTask = {
         name: 'system_schedule_task',
-        description: 'Schedule a message to yourself for later — once at a set time, or repeatedly on an interval — like setting a reminder or a cron job. When it fires you receive the message as a new conversation (none of the current one carries over, so make the message self-contained) and handle it with your tools as usual, with no person live. A tool call that needs approval goes wherever your approval requests are sent and waits; if nowhere is set, it is denied. Use only when the user asks for something to happen later or regularly, never on your own initiative. Times are in this workspace\'s time zone, ' + timeZone + ', unless you give an offset, so when the user means another time zone, give its offset. Prefer the longest interval that serves them since each run is a model call, and confirm the schedule back in plain words. Returns task_id, next_run_at and next_run_local (the workspace\'s time).',
+        description: 'Schedule a message to yourself for later — once at a set time, or repeatedly on an interval — like setting a reminder or a cron job.' +
+            (workflows.length
+                ? ' To run one of your workflows on a schedule, give its workflow_id instead of a message, and its params (names ending in ? are optional): each run then starts with that workflow\'s start message and steps as they are at the time, so later edits to the workflow apply. Your workflows: ' + workflowList + '.'
+                : '') +
+            ' When it fires you receive the message as a new conversation (none of the current one carries over, so make the message self-contained) and handle it with your tools as usual, with no person live. A tool call that needs approval goes wherever your approval requests are sent and waits; if nowhere is set, it is denied. Use only when the user asks for something to happen later or regularly, never on your own initiative. Times are in this workspace\'s time zone, ' + timeZone + ', unless you give an offset, so when the user means another time zone, give its offset. Prefer the longest interval that serves them since each run is a model call, and confirm the schedule back in plain words. Returns task_id, next_run_at and next_run_local (the workspace\'s time).',
         input_schema: {
             type: 'object',
             properties: {
                 message: {
                     type: 'string',
-                    description: 'What you will receive when the task fires, written as an instruction to your future self with every detail it needs, e.g. "Check whether order 4417 has shipped and email the customer at a@example.com if it has."',
+                    description: 'What you will receive when the task fires, written as an instruction to your future self with every detail it needs, e.g. "Check whether order 4417 has shipped and email the customer at a@example.com if it has." Leave it out when giving workflow_id.',
                 },
+                ...(workflows.length
+                    ? {
+                        workflow_id: { type: 'string', enum: workflows.map((w) => w.id), description: 'One of your workflows, to run it on this schedule instead of a message.' },
+                        params: { type: 'object', description: 'The workflow\'s parameters for every run, e.g. { "region": "US" }.', additionalProperties: { type: 'string' } },
+                    }
+                    : {}),
                 schedule: {
                     type: 'object',
                     description: 'Either { "run_at": "<ISO 8601 timestamp>" } for once, or { "every": "<interval>", ... } to repeat until cancelled — a number plus s/m/h/d, e.g. "30m", "1h", "1d"; 30s at the shortest. A timestamp without an offset, like "2026-11-02T09:00", is in the workspace\'s time zone (' + timeZone + '). A repeating task keeps its first slot: started at 10:07 with "1h", it fires at 11:07, 12:07, ... For a time of day or day of week, add "at" (24-hour "HH:MM") and for weekly "weekday": "every day at 9am" is { "every": "1d", "at": "09:00" }; "every Monday at 9am" is { "every": "7d", "at": "09:00", "weekday": "monday" }. Daily and weekly tasks keep their time of day when the clocks change. Or give "start_at", a timestamp, for the first run.',
@@ -54,26 +73,42 @@ export function createScheduleTools(agentName) {
                 task_name: { type: 'string', description: 'Optional short label, shown when listing tasks and in the console.' },
                 notify: { type: 'boolean', description: 'Optional — also send each run\'s result through your notifier (where your approval requests go), so a person sees it.' },
             },
-            required: ['message', 'schedule'],
+            required: ['schedule'],
         },
         execute: async (input) => {
             const active = (await listScheduledTasks({ agent: agentName })).filter((t) => t.status !== 'done' && t.status !== 'cancelled');
             if (active.length >= maxActivePerAgent()) {
                 throw new Error(`system_schedule_task: you already have ${active.length} active scheduled tasks (the limit is ${maxActivePerAgent()}); cancel one you no longer need first`);
             }
+            const workflowId = typeof input.workflow_id === 'string' && input.workflow_id ? input.workflow_id : undefined;
+            const workflow = workflowId ? workflows.find((w) => w.id === workflowId) : undefined;
+            if (workflowId && !workflow) {
+                throw new Error(`system_schedule_task: you have no workflow "${workflowId}"${workflows.length ? `; yours are ${workflows.map((w) => `"${w.id}"`).join(', ')}` : ''}`);
+            }
+            let params;
+            if (workflow) {
+                try {
+                    params = validateParams(workflow, input.params);
+                }
+                catch (err) {
+                    throw new Error(`system_schedule_task: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
             const task = await createScheduledTask({
                 agent: agentName,
-                message: String(input.message ?? ''),
+                message: workflowId ? undefined : String(input.message ?? ''),
+                workflow_id: workflowId,
+                ...(params && Object.keys(params).length ? { params } : {}),
                 schedule: (input.schedule ?? {}),
                 task_name: typeof input.task_name === 'string' ? input.task_name : undefined,
                 notify: input.notify === true,
             });
-            return JSON.stringify({ task_id: task.task_id, next_run_at: task.next_run_at, next_run_local: nextRunLocal(task, timeZone), schedule: task.schedule });
+            return JSON.stringify({ task_id: task.task_id, ...(workflowId ? { workflow_id: workflowId } : {}), next_run_at: task.next_run_at, next_run_local: nextRunLocal(task, timeZone), schedule: task.schedule });
         },
     };
     const listTasks = {
         name: 'system_list_scheduled_tasks',
-        description: 'List your own scheduled tasks (task_id, name, message, schedule, status, next_run_at, run_count, last_status). Check this before scheduling something recurring, so you don\'t create a duplicate. status "awaiting_approval" means a run is waiting on someone to approve or answer.',
+        description: 'List your own scheduled tasks (task_id, name, message or workflow_id, schedule, status, next_run_at, run_count, last_status). Check this before scheduling something recurring, so you don\'t create a duplicate. status "awaiting_approval" means a run is waiting on someone to approve or answer.',
         input_schema: {
             type: 'object',
             properties: {

package/dist/core/workflow-runs.d.ts

@@ -0,0 +1,131 @@
+import type { CallbackDelivery } from './run-callbacks.js';
+export type WorkflowRunStatus = 'running' | 'awaiting_approval' | 'done' | 'error';
+export interface WorkflowRun {
+    run_id: string;
+    agent: string;
+    workflow_id: string;
+    params?: Record<string, string>;
+    /** Who started it: the console's Run now, an app over the API, a
+     * schedule, or an outside service through a webhook trigger. */
+    source: 'console' | 'api' | 'schedule' | 'webhook';
+    /** The webhook trigger that started it, for source "webhook"
+     * (core/workflow-triggers.ts). */
+    trigger_id?: string;
+    /** The schedule that started it, for source "schedule". */
+    task_id?: string;
+    task_name?: string;
+    status: WorkflowRunStatus;
+    started_at: string;
+    finished_at?: string;
+    /** The message it started with: the workflow's start message and steps. */
+    message: string;
+    session_id: string;
+    /** The agent's final reply, when done. */
+    result?: string;
+    error?: string;
+    /** The approvals or questions it is waiting on. */
+    pending_ids?: string[];
+    /** Send its result through the agent's notifier when it ends. */
+    notify?: boolean;
+    /** Where its record is posted when it ends or stops for a decision
+     * (core/run-callbacks.ts). */
+    callback_url?: string;
+    /** Each callback delivery, oldest first (the latest 10). */
+    callbacks?: CallbackDelivery[];
+}
+export type RunOutcome = {
+    kind: 'done';
+    text: string;
+} | {
+    kind: 'pending';
+    pendingIds: string[];
+};
+/** Runs the agent once: what a scheduled task's fire does. */
+export type ExecuteRun = (agent: string, message: string, sessionId: string) => Promise<RunOutcome>;
+export declare class RunError extends Error {
+}
+export interface RunStore {
+    list(): Promise<WorkflowRun[]>;
+    get(runId: string): Promise<WorkflowRun | undefined>;
+    put(run: WorkflowRun): Promise<void>;
+    remove(runId: string): Promise<void>;
+    update(runId: string, fn: (run: WorkflowRun | undefined) => WorkflowRun | undefined): Promise<WorkflowRun | undefined>;
+}
+/** One JSON file per run under `<dir>/runs/` — one server process. */
+export declare class FileRunStore implements RunStore {
+    private readonly dir;
+    constructor(dir: string);
+    private file;
+    list(): Promise<WorkflowRun[]>;
+    get(runId: string): Promise<WorkflowRun | undefined>;
+    put(run: WorkflowRun): Promise<void>;
+    remove(runId: string): Promise<void>;
+    update(runId: string, fn: (run: WorkflowRun | undefined) => WorkflowRun | undefined): Promise<WorkflowRun | undefined>;
+}
+/** The process-wide store: `runs/` in the scheduler's folder. */
+export declare function getRunStore(): RunStore;
+export declare function setRunStore(next: RunStore): void;
+/** An agent's runs, newest first; of one workflow when `workflowId` is given. */
+export declare function listRuns(agent: string, filter?: {
+    workflowId?: string;
+    limit?: number;
+}): Promise<WorkflowRun[]>;
+/** One of an agent's runs; undefined for another agent's. */
+export declare function getRun(agent: string, runId: string): Promise<WorkflowRun | undefined>;
+export declare function isUnderWay(run: WorkflowRun): boolean;
+export interface StartRunInput {
+    agent: string;
+    workflow_id: string;
+    params?: Record<string, string>;
+    source: WorkflowRun['source'];
+    message: string;
+    notify?: boolean;
+    callback_url?: string;
+    trigger_id?: string;
+}
+export declare class WorkflowRunner {
+    private readonly execute;
+    private readonly maxFinishedPerAgent;
+    private readonly onChange?;
+    private readonly inFlight;
+    /** `onChange`: called with the run each time it finishes, fails or
+     * stops for a decision (the server sends its notify and callback). */
+    constructor(options: {
+        execute: ExecuteRun;
+        maxFinishedPerAgent?: number;
+        onChange?: (run: WorkflowRun) => void | Promise<void>;
+    });
+    private changed;
+    /** Records a run and starts it; returns at once with the record. */
+    start(input: StartRunInput): Promise<WorkflowRun>;
+    /** A schedule firing one of its agent's workflows (the scheduler's fire,
+     * for a workflow task): recorded as a run of the workflow, then run the
+     * usual way. Returns the outcome for the scheduler, and throws what the
+     * run threw, so the schedule's own history records it too. */
+    runForSchedule(input: {
+        agent: string;
+        workflow_id: string;
+        params?: Record<string, string>;
+        task_id: string;
+        task_name?: string;
+        message: string;
+        session_id: string;
+    }): Promise<RunOutcome>;
+    /** Waits for the runs this process has started (tests, shutdown). */
+    idle(): Promise<void>;
+    /** How many runs are executing right now (for idle-shutdown checks). */
+    get running(): number;
+    private run;
+    private finish;
+    /** A paused run resumed after a decision (the server calls this from
+     * its resolve path, for every resumed session): settle it, or record
+     * what it's waiting on now. */
+    settleFromResume(sessionId: string, outcome: {
+        text: string;
+        pendingIds?: string[];
+    }): Promise<void>;
+    /** On startup: a run a restart cut off can't continue, so it's an
+     * error. One waiting on a decision is kept: its checkpoint survives. */
+    recover(): Promise<void>;
+    private prune;
+}

package/dist/core/workflow-runs.js

@@ -0,0 +1,229 @@
+// Workflow runs: started by hand or by an app (Run now in the console, or
+// POST /agents/:name/workflows/:id/run), or by a schedule that runs the
+// workflow. Each is a record of its own here, so a workflow has one
+// history of every run whatever started it, the Schedules tab only lists
+// what is set to run, and each run can be looked up by its id afterwards
+// (GET /agents/:name/runs/:id).
+//
+// A run executes the same way a scheduled task fires (supplied by the
+// server, adapters/http.ts): an unattended agent turn whose approvals and
+// questions go to the agent's messaging app and wait durably. A run that
+// pauses there is settled by settleFromResume once someone decides.
+//
+// Stored like scheduled tasks: one JSON file per run under
+// `<LOOPENGINE_SCHEDULER_DIR or .scheduler>/runs/`. Each agent keeps its
+// latest MAX_FINISHED_PER_AGENT finished runs; older ones are removed as
+// new runs start.
+import { randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { KeyedMutex } from './session-store.js';
+const MAX_FINISHED_PER_AGENT = 500;
+const SESSION_PREFIX = 'run-';
+/** A scheduled task's sessions (core/scheduler.ts). */
+const SCHEDULE_SESSION_PREFIX = 'sched-';
+export class RunError extends Error {
+}
+const fileMutex = new KeyedMutex();
+/** One JSON file per run under `<dir>/runs/` — one server process. */
+export class FileRunStore {
+    dir;
+    constructor(dir) {
+        this.dir = path.join(dir, 'runs');
+    }
+    file(runId) {
+        if (!/^[A-Za-z0-9_-]+$/.test(runId))
+            throw new RunError(`invalid run id "${runId}"`);
+        return path.join(this.dir, `${runId}.json`);
+    }
+    async list() {
+        if (!existsSync(this.dir))
+            return [];
+        const runs = [];
+        for (const name of readdirSync(this.dir)) {
+            if (!name.endsWith('.json'))
+                continue;
+            try {
+                runs.push(JSON.parse(readFileSync(path.join(this.dir, name), 'utf8')));
+            }
+            catch {
+                // A file being written, or not a run: skip it.
+            }
+        }
+        return runs.sort((a, b) => b.started_at.localeCompare(a.started_at));
+    }
+    async get(runId) {
+        const file = this.file(runId);
+        return existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : undefined;
+    }
+    async put(run) {
+        mkdirSync(this.dir, { recursive: true });
+        const file = this.file(run.run_id);
+        writeFileSync(file + '.tmp', JSON.stringify(run, null, 2));
+        renameSync(file + '.tmp', file);
+    }
+    async remove(runId) {
+        rmSync(this.file(runId), { force: true });
+    }
+    async update(runId, fn) {
+        return fileMutex.run(runId, async () => {
+            const next = fn(await this.get(runId));
+            if (next)
+                await this.put(next);
+            return next;
+        });
+    }
+}
+let store;
+/** The process-wide store: `runs/` in the scheduler's folder. */
+export function getRunStore() {
+    store ??= new FileRunStore(process.env.LOOPENGINE_SCHEDULER_DIR || path.join(process.cwd(), '.scheduler'));
+    return store;
+}
+export function setRunStore(next) {
+    store = next;
+}
+// ---------- reading ----------
+/** An agent's runs, newest first; of one workflow when `workflowId` is given. */
+export async function listRuns(agent, filter = {}) {
+    const runs = (await getRunStore().list()).filter((r) => r.agent === agent && (!filter.workflowId || r.workflow_id === filter.workflowId));
+    return filter.limit ? runs.slice(0, filter.limit) : runs;
+}
+/** One of an agent's runs; undefined for another agent's. */
+export async function getRun(agent, runId) {
+    if (!/^[A-Za-z0-9_-]+$/.test(runId))
+        return undefined;
+    const run = await getRunStore().get(runId);
+    return run && run.agent === agent ? run : undefined;
+}
+export function isUnderWay(run) {
+    return run.status === 'running' || run.status === 'awaiting_approval';
+}
+export class WorkflowRunner {
+    execute;
+    maxFinishedPerAgent;
+    onChange;
+    inFlight = new Set();
+    /** `onChange`: called with the run each time it finishes, fails or
+     * stops for a decision (the server sends its notify and callback). */
+    constructor(options) {
+        this.execute = options.execute;
+        this.maxFinishedPerAgent = options.maxFinishedPerAgent ?? MAX_FINISHED_PER_AGENT;
+        this.onChange = options.onChange;
+    }
+    changed(run) {
+        if (!run || !this.onChange)
+            return;
+        void Promise.resolve()
+            .then(() => this.onChange(run))
+            .catch((err) => console.error(`[loopengine] reporting run ${run.run_id} failed:`, err));
+    }
+    /** Records a run and starts it; returns at once with the record. */
+    async start(input) {
+        const runId = randomUUID();
+        const run = {
+            run_id: runId,
+            agent: input.agent,
+            workflow_id: input.workflow_id,
+            ...(input.params && Object.keys(input.params).length ? { params: input.params } : {}),
+            source: input.source,
+            ...(input.notify ? { notify: true } : {}),
+            ...(input.callback_url ? { callback_url: input.callback_url } : {}),
+            ...(input.trigger_id ? { trigger_id: input.trigger_id } : {}),
+            status: 'running',
+            started_at: new Date().toISOString(),
+            message: input.message,
+            session_id: `${SESSION_PREFIX}${runId.slice(0, 8)}-${Date.now().toString(36)}`,
+        };
+        await getRunStore().put(run);
+        await this.prune(input.agent);
+        const job = this.run(run).finally(() => this.inFlight.delete(job));
+        this.inFlight.add(job);
+        return run;
+    }
+    /** A schedule firing one of its agent's workflows (the scheduler's fire,
+     * for a workflow task): recorded as a run of the workflow, then run the
+     * usual way. Returns the outcome for the scheduler, and throws what the
+     * run threw, so the schedule's own history records it too. */
+    async runForSchedule(input) {
+        const run = {
+            run_id: randomUUID(),
+            agent: input.agent,
+            workflow_id: input.workflow_id,
+            ...(input.params && Object.keys(input.params).length ? { params: input.params } : {}),
+            source: 'schedule',
+            task_id: input.task_id,
+            ...(input.task_name ? { task_name: input.task_name } : {}),
+            status: 'running',
+            started_at: new Date().toISOString(),
+            message: input.message,
+            session_id: input.session_id,
+        };
+        await getRunStore().put(run);
+        await this.prune(input.agent);
+        try {
+            const outcome = await this.execute(run.agent, run.message, run.session_id);
+            if (outcome.kind === 'pending')
+                this.changed(await getRunStore().update(run.run_id, (r) => r && { ...r, status: 'awaiting_approval', pending_ids: outcome.pendingIds }));
+            else
+                await this.finish(run.run_id, { status: 'done', result: outcome.text });
+            return outcome;
+        }
+        catch (err) {
+            await this.finish(run.run_id, { status: 'error', error: err instanceof Error ? err.message : String(err) });
+            throw err;
+        }
+    }
+    /** Waits for the runs this process has started (tests, shutdown). */
+    async idle() {
+        await Promise.all([...this.inFlight]);
+    }
+    /** How many runs are executing right now (for idle-shutdown checks). */
+    get running() {
+        return this.inFlight.size;
+    }
+    async run(run) {
+        try {
+            const outcome = await this.execute(run.agent, run.message, run.session_id);
+            if (outcome.kind === 'pending') {
+                this.changed(await getRunStore().update(run.run_id, (r) => r && { ...r, status: 'awaiting_approval', pending_ids: outcome.pendingIds }));
+                return;
+            }
+            await this.finish(run.run_id, { status: 'done', result: outcome.text });
+        }
+        catch (err) {
+            await this.finish(run.run_id, { status: 'error', error: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    async finish(runId, end) {
+        this.changed(await getRunStore().update(runId, (r) => r && { ...r, ...end, pending_ids: undefined, finished_at: new Date().toISOString() }));
+    }
+    /** A paused run resumed after a decision (the server calls this from
+     * its resolve path, for every resumed session): settle it, or record
+     * what it's waiting on now. */
+    async settleFromResume(sessionId, outcome) {
+        if (!sessionId.startsWith(SESSION_PREFIX) && !sessionId.startsWith(SCHEDULE_SESSION_PREFIX))
+            return;
+        const run = (await getRunStore().list()).find((r) => r.session_id === sessionId);
+        if (!run)
+            return;
+        if (outcome.pendingIds?.length) {
+            this.changed(await getRunStore().update(run.run_id, (r) => r && { ...r, status: 'awaiting_approval', pending_ids: outcome.pendingIds }));
+            return;
+        }
+        await this.finish(run.run_id, { status: 'done', result: outcome.text });
+    }
+    /** On startup: a run a restart cut off can't continue, so it's an
+     * error. One waiting on a decision is kept: its checkpoint survives. */
+    async recover() {
+        for (const run of await getRunStore().list()) {
+            if (run.status === 'running')
+                await this.finish(run.run_id, { status: 'error', error: 'The server restarted while this run was in progress.' });
+        }
+    }
+    async prune(agent) {
+        const finished = (await listRuns(agent)).filter((r) => !isUnderWay(r));
+        for (const old of finished.slice(this.maxFinishedPerAgent))
+            await getRunStore().remove(old.run_id);
+    }
+}