loopengine 0.3.0 → 0.3.1

package/dist/core/run-callbacks.d.ts

@@ -0,0 +1,39 @@
+export declare class CallbackUrlError extends Error {
+}
+export type RunCallbackEvent = 'run.done' | 'run.failed' | 'run.awaiting_approval';
+/** Whether an IP address is private, loopback, link-local or otherwise
+ * not on the public internet. */
+export declare function isPrivateAddress(address: string): boolean;
+/** Checks a callback URL as given; returns it normalised. Throws
+ * CallbackUrlError saying what's wrong. */
+export declare function checkCallbackUrl(raw: unknown): string;
+/** The workspace's callback secret: LOOPENGINE_CALLBACK_SECRET, or one
+ * made once and kept in the scheduler's folder. */
+export declare function callbackSecret(): string;
+/** The signature header for a body sent at `timestamp` (unix seconds). */
+export declare function signCallback(body: string, timestamp: number, secret?: string): string;
+export interface CallbackDelivery {
+    event: RunCallbackEvent;
+    delivered: boolean;
+    attempts: number;
+    status_code?: number;
+    error?: string;
+    at: string;
+}
+export interface DeliverOptions {
+    /** Waits between attempts, in ms; its length + 1 is the attempts made. */
+    backoffMs?: number[];
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+}
+/** Posts `payload` to `url` for `event`, retrying a failed attempt (an
+ * error, or a status other than 2xx) after each wait in backoffMs. The
+ * host is looked up first, and a private address is refused (unless
+ * local callbacks are allowed), so a public name can't lead inward. */
+export declare function deliverCallback(url: string, event: RunCallbackEvent, payload: unknown, options?: DeliverOptions): Promise<CallbackDelivery>;
+/** What a run's callback carries: the event and the run's record, without
+ * its session id, its first message or past callback deliveries. */
+export declare function runCallbackPayload(event: RunCallbackEvent, run: object): {
+    event: RunCallbackEvent;
+    run: Record<string, unknown>;
+};

package/dist/core/run-callbacks.js

@@ -0,0 +1,125 @@
+// Callbacks for workflow runs started over the API: a run started with
+// "callback_url" has its record posted there when it finishes, fails, or
+// stops for an approval or a question (core/workflow-runs.ts calls
+// deliverRunCallback for each of those).
+//
+// Each POST carries
+//   X-LoopEngine-Event: run.done | run.failed | run.awaiting_approval
+//   X-LoopEngine-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<body>">
+// signed with the workspace's callback secret: LOOPENGINE_CALLBACK_SECRET,
+// or one made once and kept in the scheduler's folder
+// (GET /runs/callback-secret shows it). A receiver checks the signature
+// and that t is recent.
+//
+// Only https URLs on public addresses are accepted, so a run can't be
+// pointed at the workspace's own network. LOOPENGINE_ALLOW_LOCAL_CALLBACKS=1
+// also allows http and local addresses, for development.
+import { createHmac, randomBytes } from 'node:crypto';
+import { lookup } from 'node:dns/promises';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { isIP } from 'node:net';
+import path from 'node:path';
+export class CallbackUrlError extends Error {
+}
+function allowLocal() {
+    return process.env.LOOPENGINE_ALLOW_LOCAL_CALLBACKS === '1';
+}
+/** Whether an IP address is private, loopback, link-local or otherwise
+ * not on the public internet. */
+export function isPrivateAddress(address) {
+    const ip = address.toLowerCase().replace(/^\[|\]$/g, '');
+    const v4 = ip.startsWith('::ffff:') ? ip.slice(7) : ip;
+    if (isIP(v4) === 4) {
+        const [a, b] = v4.split('.').map(Number);
+        return a === 0 || a === 10 || a === 127 || (a === 100 && b >= 64 && b <= 127) || (a === 169 && b === 254) ||
+            (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || a >= 224;
+    }
+    if (isIP(ip) === 6) {
+        return ip === '::' || ip === '::1' || /^f[cd]/.test(ip) || /^fe[89ab]/.test(ip) || ip.startsWith('ff');
+    }
+    return false;
+}
+/** Checks a callback URL as given; returns it normalised. Throws
+ * CallbackUrlError saying what's wrong. */
+export function checkCallbackUrl(raw) {
+    if (typeof raw !== 'string' || !raw.trim())
+        throw new CallbackUrlError('callback_url must be a URL, e.g. "https://example.com/hooks/loopengine"');
+    let url;
+    try {
+        url = new URL(raw.trim());
+    }
+    catch {
+        throw new CallbackUrlError(`callback_url "${raw}" isn't a URL`);
+    }
+    const host = url.hostname.toLowerCase();
+    const local = host === 'localhost' || host.endsWith('.localhost') || host.endsWith('.internal') || host.endsWith('.local') || isPrivateAddress(host);
+    if (url.protocol !== 'https:' && !(allowLocal() && url.protocol === 'http:'))
+        throw new CallbackUrlError('callback_url must use https');
+    if (local && !allowLocal())
+        throw new CallbackUrlError('callback_url must be a public address, not a local or private one');
+    if (url.username || url.password)
+        throw new CallbackUrlError('callback_url must not carry a username or password; check the signature instead');
+    return url.toString();
+}
+/** The workspace's callback secret: LOOPENGINE_CALLBACK_SECRET, or one
+ * made once and kept in the scheduler's folder. */
+export function callbackSecret() {
+    if (process.env.LOOPENGINE_CALLBACK_SECRET)
+        return process.env.LOOPENGINE_CALLBACK_SECRET;
+    const dir = process.env.LOOPENGINE_SCHEDULER_DIR || path.join(process.cwd(), '.scheduler');
+    const file = path.join(dir, 'callback-secret');
+    if (existsSync(file))
+        return readFileSync(file, 'utf8').trim();
+    mkdirSync(dir, { recursive: true });
+    const secret = randomBytes(32).toString('hex');
+    writeFileSync(file, secret + '\n', { mode: 0o600 });
+    return secret;
+}
+/** The signature header for a body sent at `timestamp` (unix seconds). */
+export function signCallback(body, timestamp, secret = callbackSecret()) {
+    return `t=${timestamp},v1=${createHmac('sha256', secret).update(`${timestamp}.${body}`).digest('hex')}`;
+}
+/** Posts `payload` to `url` for `event`, retrying a failed attempt (an
+ * error, or a status other than 2xx) after each wait in backoffMs. The
+ * host is looked up first, and a private address is refused (unless
+ * local callbacks are allowed), so a public name can't lead inward. */
+export async function deliverCallback(url, event, payload, options = {}) {
+    const backoff = options.backoffMs ?? [2_000, 10_000, 30_000];
+    const doFetch = options.fetch ?? fetch;
+    const body = JSON.stringify(payload);
+    let last = { event, delivered: false, attempts: 0, at: new Date().toISOString() };
+    for (let attempt = 0; attempt <= backoff.length; attempt++) {
+        if (attempt > 0)
+            await new Promise((r) => setTimeout(r, backoff[attempt - 1]));
+        const at = new Date().toISOString();
+        try {
+            if (!allowLocal()) {
+                const addresses = await lookup(new URL(url).hostname, { all: true });
+                if (addresses.some((a) => isPrivateAddress(a.address))) {
+                    return { event, delivered: false, attempts: attempt + 1, error: 'The callback address leads to a private network.', at };
+                }
+            }
+            const timestamp = Math.floor(Date.now() / 1000);
+            const response = await doFetch(url, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json', 'x-loopengine-event': event, 'x-loopengine-signature': signCallback(body, timestamp), 'user-agent': 'LoopEngine-Callback/1' },
+                body,
+                signal: AbortSignal.timeout(options.timeoutMs ?? 10_000),
+                redirect: 'manual',
+            });
+            last = { event, delivered: response.ok, attempts: attempt + 1, status_code: response.status, at, ...(response.ok ? {} : { error: `It answered ${response.status}.` }) };
+            if (response.ok)
+                return last;
+        }
+        catch (err) {
+            last = { event, delivered: false, attempts: attempt + 1, error: err instanceof Error ? err.message : String(err), at };
+        }
+    }
+    return last;
+}
+/** What a run's callback carries: the event and the run's record, without
+ * its session id, its first message or past callback deliveries. */
+export function runCallbackPayload(event, run) {
+    const { session_id: _session, message: _message, callbacks: _callbacks, ...rest } = run;
+    return { event, run: rest };
+}

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);
+    }
+}

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

@@ -0,0 +1,130 @@
+import type { Workflow } from './workflows.js';
+/** Whose signature scheme a trigger checks. "standard" is Standard
+ * Webhooks (Svix: used by Clerk, Resend, OpenAI and others); "custom" is
+ * an HMAC of the raw body in a header the sender names (Typeform, Linear,
+ * Sentry, Intercom and most others that sign the body). */
+export type TriggerSender = 'stripe' | 'github' | 'shopify' | 'standard' | 'custom';
+export type SignatureAlgorithm = 'sha256' | 'sha1' | 'sha512';
+export interface TriggerVerify {
+    sender: TriggerSender;
+    /** The signing secret the sender gives (Stripe's whsec_…, GitHub's,
+     * Shopify's, a Standard Webhooks whsec_…, or a custom one). */
+    secret: string;
+    /** custom only: the header the signature is in, e.g. "Linear-Signature". */
+    header?: string;
+    /** custom only: the HMAC's hash (default sha256). */
+    algorithm?: SignatureAlgorithm;
+    /** custom only: how the signature is written (default hex). */
+    encoding?: 'hex' | 'base64';
+    /** custom only: text before the signature, e.g. "sha256=". */
+    prefix?: string;
+}
+export interface TriggerFilter {
+    /** Where in the payload, as a dot path: "type", "action", "data.object.status". */
+    path: string;
+    /** Run only when the value there is one of these. */
+    values: string[];
+}
+export type TriggerOutcome = 'started' | 'filtered' | 'duplicate' | 'busy' | 'rejected' | 'invalid' | 'error';
+export interface TriggerDelivery {
+    at: string;
+    outcome: TriggerOutcome;
+    delivery_id?: string;
+    run_id?: string;
+    detail?: string;
+}
+export interface WorkflowTrigger {
+    trigger_id: string;
+    agent: string;
+    workflow_id: string;
+    name: string;
+    /** SHA-256 of the URL's token. */
+    token_hash: string;
+    /** The token's start, to tell triggers apart: "whk_8f3k…". */
+    token_hint: string;
+    enabled: boolean;
+    created_at: string;
+    verify?: TriggerVerify;
+    filter?: TriggerFilter;
+    /** Workflow parameter → dot path in the payload. */
+    mapping?: Record<string, string>;
+    /** A parameter that gets the whole payload, as JSON. */
+    payload_param?: string;
+    notify?: boolean;
+    callback_url?: string;
+    /** The latest deliveries, newest first (20). */
+    deliveries: TriggerDelivery[];
+    /** Delivery ids already handled (the latest 200), for retries. */
+    seen_ids: string[];
+}
+/** A trigger as the console and API show it: no token hash, no secret. */
+export type PublicTrigger = Omit<WorkflowTrigger, 'token_hash' | 'verify' | 'seen_ids'> & {
+    verify?: Omit<TriggerVerify, 'secret'>;
+};
+export declare class TriggerError extends Error {
+}
+export interface TriggerStore {
+    list(): Promise<WorkflowTrigger[]>;
+    get(id: string): Promise<WorkflowTrigger | undefined>;
+    put(trigger: WorkflowTrigger): Promise<void>;
+    remove(id: string): Promise<void>;
+    update(id: string, fn: (t: WorkflowTrigger | undefined) => WorkflowTrigger | undefined): Promise<WorkflowTrigger | undefined>;
+}
+/** One JSON file per trigger under `<dir>/triggers/` — one server process. */
+export declare class FileTriggerStore implements TriggerStore {
+    private readonly dir;
+    constructor(dir: string);
+    private file;
+    list(): Promise<WorkflowTrigger[]>;
+    get(id: string): Promise<WorkflowTrigger | undefined>;
+    put(trigger: WorkflowTrigger): Promise<void>;
+    remove(id: string): Promise<void>;
+    update(id: string, fn: (t: WorkflowTrigger | undefined) => WorkflowTrigger | undefined): Promise<WorkflowTrigger | undefined>;
+}
+export declare function getTriggerStore(): TriggerStore;
+export declare function setTriggerStore(next: TriggerStore): void;
+export declare function publicTrigger(t: WorkflowTrigger): PublicTrigger;
+/** The settings a trigger can have, checked against its workflow. */
+export interface TriggerSettings {
+    name?: unknown;
+    enabled?: unknown;
+    verify?: unknown;
+    filter?: unknown;
+    mapping?: unknown;
+    payload_param?: unknown;
+    notify?: unknown;
+    callback_url?: unknown;
+}
+/** Checks settings for a trigger of `workflow`; throws TriggerError saying
+ * what's wrong. `existing` keeps a sender's secret when only the sender
+ * is given again (the console never sees the secret). */
+export declare function checkTriggerSettings(input: TriggerSettings, workflow: Workflow, existing?: WorkflowTrigger): Pick<WorkflowTrigger, 'name' | 'enabled' | 'verify' | 'filter' | 'mapping' | 'payload_param' | 'notify' | 'callback_url'>;
+/** Makes a trigger for a workflow; returns it with its token (shown once). */
+export declare function createTrigger(agent: string, workflow: Workflow, input: TriggerSettings): Promise<{
+    trigger: WorkflowTrigger;
+    token: string;
+}>;
+export declare function updateTrigger(id: string, workflow: Workflow, input: TriggerSettings): Promise<WorkflowTrigger>;
+/** A new URL for a trigger; the old one stops working. */
+export declare function rotateTrigger(id: string): Promise<{
+    trigger: WorkflowTrigger;
+    token: string;
+}>;
+export declare function listTriggers(agent: string, workflowId?: string): Promise<WorkflowTrigger[]>;
+/** The trigger a URL's token belongs to. */
+export declare function findTriggerByToken(token: string): Promise<WorkflowTrigger | undefined>;
+/** Whether the sender's own signature on the raw body is right. */
+export declare function verifySenderSignature(verify: TriggerVerify, headers: Record<string, string | string[] | undefined>, raw: Buffer, nowS?: number): boolean;
+/** The payload: JSON, a form, or plain text (as { body }). */
+export declare function parsePayload(raw: Buffer, contentType: string | undefined): unknown;
+/** The value at a dot path: "data.object.id", "items.0.sku". */
+export declare function valueAt(payload: unknown, dotPath: string): unknown;
+/** The sender's id for this delivery, if it gives one: what a retry
+ * repeats. */
+export declare function deliveryId(headers: Record<string, string | string[] | undefined>, payload: unknown): string | undefined;
+/** Whether the filter keeps this payload. */
+export declare function passesFilter(filter: TriggerFilter | undefined, payload: unknown): boolean;
+/** The workflow's parameters from the payload. */
+export declare function paramsFromPayload(trigger: Pick<WorkflowTrigger, 'mapping' | 'payload_param'>, payload: unknown): Record<string, string>;
+/** Notes a delivery on its trigger, and its id as handled. */
+export declare function recordDelivery(id: string, delivery: TriggerDelivery, seenId?: string): Promise<void>;

package/dist/core/workflow-triggers.js

@@ -0,0 +1,361 @@
+// Webhook triggers: a secret URL per workflow that an outside service
+// (Stripe, GitHub, Shopify, a form or monitoring tool) can post its own
+// events to, to start a run, with no API key and no body format of ours:
+//
+//   POST /hooks/workflows/<token>
+//
+// The token in the URL is the credential (it's kept here only as a
+// SHA-256 hash, so the full URL is shown once, when it's made or
+// rotated). A trigger can also check the sender's own signature, keep
+// only some events (filter), and fill the workflow's parameters from the
+// payload (mapping, or the whole payload as one parameter). A delivery a
+// sender retries is recognised by its id and starts no second run.
+//
+// Stored like runs and schedules: one JSON file per trigger under
+// `<LOOPENGINE_SCHEDULER_DIR or .scheduler>/triggers/`.
+import { createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } 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';
+import { checkCallbackUrl } from './run-callbacks.js';
+export class TriggerError extends Error {
+}
+const MAX_DELIVERIES = 20;
+const MAX_SEEN = 200;
+const MAX_PAYLOAD_PARAM = 20_000;
+const SENDERS = ['stripe', 'github', 'shopify', 'standard', 'custom'];
+const ALGORITHMS = ['sha256', 'sha1', 'sha512'];
+/** How old a signed timestamp (Stripe, Standard Webhooks) may be. */
+const SIGNATURE_TOLERANCE_S = 300;
+const fileMutex = new KeyedMutex();
+/** One JSON file per trigger under `<dir>/triggers/` — one server process. */
+export class FileTriggerStore {
+    dir;
+    constructor(dir) {
+        this.dir = path.join(dir, 'triggers');
+    }
+    file(id) {
+        if (!/^[A-Za-z0-9_-]+$/.test(id))
+            throw new TriggerError(`invalid trigger id "${id}"`);
+        return path.join(this.dir, `${id}.json`);
+    }
+    async list() {
+        if (!existsSync(this.dir))
+            return [];
+        const triggers = [];
+        for (const name of readdirSync(this.dir)) {
+            if (!name.endsWith('.json'))
+                continue;
+            try {
+                triggers.push(JSON.parse(readFileSync(path.join(this.dir, name), 'utf8')));
+            }
+            catch {
+                // A file being written, or not a trigger: skip it.
+            }
+        }
+        return triggers.sort((a, b) => a.created_at.localeCompare(b.created_at));
+    }
+    async get(id) {
+        const file = this.file(id);
+        return existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : undefined;
+    }
+    async put(trigger) {
+        mkdirSync(this.dir, { recursive: true });
+        const file = this.file(trigger.trigger_id);
+        writeFileSync(file + '.tmp', JSON.stringify(trigger, null, 2), { mode: 0o600 });
+        renameSync(file + '.tmp', file);
+    }
+    async remove(id) {
+        rmSync(this.file(id), { force: true });
+    }
+    async update(id, fn) {
+        return fileMutex.run(id, async () => {
+            const next = fn(await this.get(id));
+            if (next)
+                await this.put(next);
+            return next;
+        });
+    }
+}
+let store;
+export function getTriggerStore() {
+    store ??= new FileTriggerStore(process.env.LOOPENGINE_SCHEDULER_DIR || path.join(process.cwd(), '.scheduler'));
+    return store;
+}
+export function setTriggerStore(next) {
+    store = next;
+}
+// ---------- making and finding ----------
+function hashToken(token) {
+    return createHash('sha256').update(token).digest('hex');
+}
+function newToken() {
+    return `whk_${randomBytes(24).toString('base64url')}`;
+}
+export function publicTrigger(t) {
+    const { token_hash: _hash, verify, seen_ids: _seen, ...rest } = t;
+    if (!verify)
+        return rest;
+    const { secret: _secret, ...shown } = verify;
+    return { ...rest, verify: shown };
+}
+/** Checks settings for a trigger of `workflow`; throws TriggerError saying
+ * what's wrong. `existing` keeps a sender's secret when only the sender
+ * is given again (the console never sees the secret). */
+export function checkTriggerSettings(input, workflow, existing) {
+    const name = typeof input.name === 'string' && input.name.trim() ? input.name.trim().slice(0, 80) : existing?.name ?? 'Webhook';
+    if (input.enabled !== undefined && typeof input.enabled !== 'boolean')
+        throw new TriggerError('enabled must be true or false');
+    let verify;
+    if (input.verify !== undefined && input.verify !== null) {
+        const v = input.verify;
+        if (typeof v !== 'object' || !SENDERS.includes(v.sender))
+            throw new TriggerError(`verify.sender must be one of ${SENDERS.join(', ')}`);
+        const kept = existing?.verify && existing.verify.sender === v.sender ? existing.verify.secret : '';
+        const secret = typeof v.secret === 'string' && v.secret.trim() ? v.secret.trim() : kept;
+        if (!secret)
+            throw new TriggerError(`Give the signing secret ${v.sender === 'custom' ? 'the sender' : v.sender} shows for this webhook, so its signature can be checked.`);
+        verify = { sender: v.sender, secret };
+        if (v.sender === 'standard' && !/^(whsec_)?[A-Za-z0-9+/]+=*$/.test(secret))
+            throw new TriggerError('A Standard Webhooks secret looks like "whsec_" followed by base64 text.');
+        if (v.sender === 'custom') {
+            const headerName = typeof v.header === 'string' ? v.header.trim() : '';
+            if (!/^[A-Za-z0-9-]{1,80}$/.test(headerName))
+                throw new TriggerError('Give the header the signature arrives in, e.g. "Linear-Signature" (letters, digits and dashes).');
+            const algorithm = (v.algorithm ?? 'sha256');
+            if (!ALGORITHMS.includes(algorithm))
+                throw new TriggerError(`algorithm must be one of ${ALGORITHMS.join(', ')}`);
+            const encoding = v.encoding ?? 'hex';
+            if (encoding !== 'hex' && encoding !== 'base64')
+                throw new TriggerError('encoding must be hex or base64');
+            const prefix = typeof v.prefix === 'string' ? v.prefix.trim() : '';
+            if (prefix.length > 20)
+                throw new TriggerError('prefix is too long: keep it under 20 characters, e.g. "sha256="');
+            verify = { ...verify, header: headerName.toLowerCase(), algorithm, encoding, ...(prefix ? { prefix } : {}) };
+        }
+    }
+    let filter;
+    if (input.filter !== undefined && input.filter !== null) {
+        const f = input.filter;
+        const values = Array.isArray(f.values) ? f.values.filter((x) => typeof x === 'string' && x.trim()).map((x) => x.trim()) : [];
+        if (typeof f.path !== 'string' || !f.path.trim() || !values.length)
+            throw new TriggerError('filter needs a path, e.g. "type", and at least one value, e.g. ["charge.dispute.created"]');
+        filter = { path: f.path.trim(), values };
+    }
+    const declared = Object.keys(workflow.parameters);
+    let mapping;
+    if (input.mapping !== undefined && input.mapping !== null) {
+        if (typeof input.mapping !== 'object' || Array.isArray(input.mapping))
+            throw new TriggerError('mapping must be an object of parameter names to payload paths');
+        mapping = {};
+        for (const [param, p] of Object.entries(input.mapping)) {
+            if (typeof p !== 'string' || !p.trim())
+                continue;
+            if (!declared.includes(param))
+                throw new TriggerError(`mapping: ${workflow.title} has no parameter "${param}"${declared.length ? ` (its parameters: ${declared.join(', ')})` : ''}`);
+            mapping[param] = p.trim();
+        }
+        if (!Object.keys(mapping).length)
+            mapping = undefined;
+    }
+    let payloadParam;
+    if (typeof input.payload_param === 'string' && input.payload_param) {
+        if (!declared.includes(input.payload_param))
+            throw new TriggerError(`payload_param: ${workflow.title} has no parameter "${input.payload_param}"`);
+        payloadParam = input.payload_param;
+    }
+    if (input.notify !== undefined && typeof input.notify !== 'boolean')
+        throw new TriggerError('notify must be true or false');
+    const callbackUrl = input.callback_url ? checkCallbackUrl(input.callback_url) : undefined;
+    return {
+        name,
+        enabled: input.enabled === undefined ? existing?.enabled ?? true : input.enabled,
+        ...(verify ? { verify } : {}),
+        ...(filter ? { filter } : {}),
+        ...(mapping ? { mapping } : {}),
+        ...(payloadParam ? { payload_param: payloadParam } : {}),
+        ...(input.notify === true ? { notify: true } : {}),
+        ...(callbackUrl ? { callback_url: callbackUrl } : {}),
+    };
+}
+/** Makes a trigger for a workflow; returns it with its token (shown once). */
+export async function createTrigger(agent, workflow, input) {
+    const settings = checkTriggerSettings(input, workflow);
+    const token = newToken();
+    const trigger = {
+        trigger_id: randomUUID(),
+        agent,
+        workflow_id: workflow.id,
+        ...settings,
+        token_hash: hashToken(token),
+        token_hint: `${token.slice(0, 8)}…`,
+        created_at: new Date().toISOString(),
+        deliveries: [],
+        seen_ids: [],
+    };
+    await getTriggerStore().put(trigger);
+    return { trigger, token };
+}
+export async function updateTrigger(id, workflow, input) {
+    const existing = await getTriggerStore().get(id);
+    if (!existing)
+        throw new TriggerError(`no trigger ${id}`);
+    const settings = checkTriggerSettings(input, workflow, existing);
+    const { verify: _v, filter: _f, mapping: _m, payload_param: _p, notify: _n, callback_url: _c, ...kept } = existing;
+    const next = { ...kept, ...settings };
+    await getTriggerStore().put(next);
+    return next;
+}
+/** A new URL for a trigger; the old one stops working. */
+export async function rotateTrigger(id) {
+    const token = newToken();
+    const trigger = await getTriggerStore().update(id, (t) => t && { ...t, token_hash: hashToken(token), token_hint: `${token.slice(0, 8)}…` });
+    if (!trigger)
+        throw new TriggerError(`no trigger ${id}`);
+    return { trigger, token };
+}
+export async function listTriggers(agent, workflowId) {
+    return (await getTriggerStore().list()).filter((t) => t.agent === agent && (!workflowId || t.workflow_id === workflowId));
+}
+/** The trigger a URL's token belongs to. */
+export async function findTriggerByToken(token) {
+    if (!/^whk_[A-Za-z0-9_-]{16,}$/.test(token))
+        return undefined;
+    const hash = Buffer.from(hashToken(token), 'hex');
+    return (await getTriggerStore().list()).find((t) => {
+        const other = Buffer.from(t.token_hash, 'hex');
+        return other.length === hash.length && timingSafeEqual(other, hash);
+    });
+}
+// ---------- a delivery ----------
+const hmacHex = (secret, data) => createHmac('sha256', secret).update(data).digest('hex');
+const sameText = (a, b) => {
+    const x = Buffer.from(a);
+    const y = Buffer.from(b);
+    return x.length === y.length && timingSafeEqual(x, y);
+};
+const header = (headers, name) => {
+    const v = headers[name];
+    return Array.isArray(v) ? v[0] : v;
+};
+/** Whether the sender's own signature on the raw body is right. */
+export function verifySenderSignature(verify, headers, raw, nowS = Math.floor(Date.now() / 1000)) {
+    if (verify.sender === 'stripe') {
+        const parts = (header(headers, 'stripe-signature') ?? '').split(',').map((p) => p.split('='));
+        const t = Number(parts.find(([k]) => k === 't')?.[1]);
+        if (!Number.isFinite(t) || Math.abs(nowS - t) > SIGNATURE_TOLERANCE_S)
+            return false;
+        const expected = hmacHex(verify.secret, Buffer.concat([Buffer.from(`${t}.`), raw]));
+        return parts.some(([k, v]) => k === 'v1' && typeof v === 'string' && sameText(v, expected));
+    }
+    if (verify.sender === 'github') {
+        const sig = header(headers, 'x-hub-signature-256') ?? '';
+        return sig.startsWith('sha256=') && sameText(sig.slice(7), hmacHex(verify.secret, raw));
+    }
+    if (verify.sender === 'shopify') {
+        const sig = header(headers, 'x-shopify-hmac-sha256') ?? '';
+        return Boolean(sig) && sameText(sig, createHmac('sha256', verify.secret).update(raw).digest('base64'));
+    }
+    if (verify.sender === 'standard') {
+        // webhook-* headers, or Svix's own svix-* names for the same thing.
+        const id = header(headers, 'webhook-id') ?? header(headers, 'svix-id');
+        const t = Number(header(headers, 'webhook-timestamp') ?? header(headers, 'svix-timestamp'));
+        const sigs = header(headers, 'webhook-signature') ?? header(headers, 'svix-signature') ?? '';
+        if (!id || !Number.isFinite(t) || Math.abs(nowS - t) > SIGNATURE_TOLERANCE_S)
+            return false;
+        const key = Buffer.from(verify.secret.replace(/^whsec_/, ''), 'base64');
+        const expected = createHmac('sha256', key).update(Buffer.concat([Buffer.from(`${id}.${t}.`), raw])).digest('base64');
+        return sigs.split(' ').some((part) => {
+            const [version, sig] = part.split(',');
+            return version === 'v1' && typeof sig === 'string' && sameText(sig, expected);
+        });
+    }
+    // custom: an HMAC of the raw body, in the header the sender names.
+    const got = (header(headers, verify.header ?? '') ?? '').trim();
+    const prefix = verify.prefix ?? '';
+    if (!got || (prefix && !got.startsWith(prefix)))
+        return false;
+    const expected = createHmac(verify.algorithm ?? 'sha256', verify.secret).update(raw).digest(verify.encoding ?? 'hex');
+    const value = got.slice(prefix.length);
+    return verify.encoding === 'base64' ? sameText(value, expected) : sameText(value.toLowerCase(), expected);
+}
+/** The payload: JSON, a form, or plain text (as { body }). */
+export function parsePayload(raw, contentType) {
+    const text = raw.toString('utf8');
+    if (/application\/x-www-form-urlencoded/i.test(contentType ?? '')) {
+        const form = Object.fromEntries(new URLSearchParams(text));
+        // Slack-style and some tools put JSON in a "payload" field.
+        if (typeof form.payload === 'string') {
+            try {
+                return JSON.parse(form.payload);
+            }
+            catch {
+                // Leave it as a form.
+            }
+        }
+        return form;
+    }
+    try {
+        return text.trim() ? JSON.parse(text) : {};
+    }
+    catch {
+        return { body: text };
+    }
+}
+/** The value at a dot path: "data.object.id", "items.0.sku". */
+export function valueAt(payload, dotPath) {
+    let value = payload;
+    for (const key of dotPath.split('.')) {
+        if (value === null || value === undefined || typeof value !== 'object')
+            return undefined;
+        value = value[key];
+    }
+    return value;
+}
+function asText(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    return JSON.stringify(value);
+}
+/** The sender's id for this delivery, if it gives one: what a retry
+ * repeats. */
+export function deliveryId(headers, payload) {
+    for (const name of ['x-github-delivery', 'x-shopify-webhook-id', 'idempotency-key', 'x-delivery-id', 'x-request-id']) {
+        const v = header(headers, name);
+        if (v)
+            return v.slice(0, 200);
+    }
+    const id = valueAt(payload, 'id');
+    return typeof id === 'string' && id ? id.slice(0, 200) : undefined;
+}
+/** Whether the filter keeps this payload. */
+export function passesFilter(filter, payload) {
+    if (!filter)
+        return true;
+    const value = asText(valueAt(payload, filter.path));
+    return value !== undefined && filter.values.includes(value);
+}
+/** The workflow's parameters from the payload. */
+export function paramsFromPayload(trigger, payload) {
+    const params = {};
+    for (const [param, dotPath] of Object.entries(trigger.mapping ?? {})) {
+        const value = asText(valueAt(payload, dotPath));
+        if (value !== undefined && value !== '')
+            params[param] = value.slice(0, MAX_PAYLOAD_PARAM);
+    }
+    if (trigger.payload_param)
+        params[trigger.payload_param] = JSON.stringify(payload).slice(0, MAX_PAYLOAD_PARAM);
+    return params;
+}
+/** Notes a delivery on its trigger, and its id as handled. */
+export async function recordDelivery(id, delivery, seenId) {
+    await getTriggerStore().update(id, (t) => t && {
+        ...t,
+        deliveries: [delivery, ...t.deliveries].slice(0, MAX_DELIVERIES),
+        seen_ids: seenId ? [...t.seen_ids.filter((s) => s !== seenId), seenId].slice(-MAX_SEEN) : t.seen_ids,
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopengine",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "type": "module",
   "description": "Runtime for tool-using AI agents with a transparent ReAct loop.",
   "license": "MIT",
@@ -124,6 +124,12 @@
     "dist/core/durable-approvals.d.ts",
     "dist/core/workflows.js",
     "dist/core/workflows.d.ts",
+    "dist/core/workflow-runs.js",
+    "dist/core/workflow-runs.d.ts",
+    "dist/core/run-callbacks.js",
+    "dist/core/run-callbacks.d.ts",
+    "dist/core/workflow-triggers.js",
+    "dist/core/workflow-triggers.d.ts",
     "dist/web",
     "protocol/loop-event.schema.json",
     "PROTOCOL.md",