loopengine 0.3.0 → 0.3.2

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/system-agents/workflow-planner.d.ts

@@ -1,5 +1,6 @@
 import type { ToolSchema } from '#core/agent-config.js';
 import type { WorkflowParameter } from '#core/workflows.js';
+import type { TriggerSender } from '#core/workflow-triggers.js';
 import type { ModelCall } from '#core/run-agent.js';
 import type { StarterTemplate, TemplateApp } from './templates.js';
 export type Decision = 'allow' | 'ask' | 'deny';
@@ -50,7 +51,8 @@ export interface WorkflowPlan {
     id: string;
     summary: string;
     trigger: {
-        kind: 'schedule' | 'on_request';
+        /** webhook: an outside service's events start runs (see `webhook`). */
+        kind: 'schedule' | 'on_request' | 'webhook';
         description: string;
         /** schedule only: "1h", "24h", "7d". */
         every?: string;
@@ -80,8 +82,13 @@ export interface WorkflowPlan {
     /** Values a run is given, filled into $name in the start message and
      * steps (core/workflows.ts). Empty when every run is the same. */
     parameters: Record<string, WorkflowParameter>;
-    /** Whether each scheduled run's result is sent to the person through
-     * the agent's messaging app, and why (shown on the review screen). */
+    /** A webhook that starts runs: set when the trigger is "webhook", and
+     * also when a scheduled workflow should run on an event too. Made on
+     * Create, turned off until the person adds the sender's signing secret. */
+    webhook?: PlannedWebhook;
+    /** Whether each scheduled or webhook-started run's result is sent to
+     * the person through the agent's messaging app, and why (shown on the
+     * review screen). */
     notify: {
         on: boolean;
         reason: string;
@@ -104,6 +111,25 @@ export interface WorkflowPlan {
      * use (filled in on Create, from mcpServers). */
     apps?: TemplateApp[];
 }
+export interface PlannedWebhook {
+    /** Whose events: the sender whose signature it checks. "custom" is the
+     * person's own app or any other service that signs the body. */
+    sender: TriggerSender;
+    /** "Stripe: new disputes". */
+    name: string;
+    /** custom only: the header the signature comes in, when known. */
+    header?: string;
+    /** Only these events start a run: a dot path into the payload and its values. */
+    filter?: {
+        path: string;
+        values: string[];
+    };
+    /** Workflow parameter → dot path into the payload. */
+    mapping?: Record<string, string>;
+    /** What to choose in the sender's own webhook settings, in plain words:
+     * "In Stripe, listen for charge.dispute.created." */
+    setup?: string;
+}
 export interface WorkflowPlannerTools {
     /** Every agent: its tools, installed abilities, rules and messaging. */
     listAgents(): Promise<unknown>;
@@ -125,13 +151,20 @@ export interface WorkflowPlannerTools {
     /** A server's tools, when it can be listed without a key (or with one already set). */
     mcpServerTools?(id: string): Promise<unknown>;
 }
-export declare const WORKFLOW_PLANNER_PROMPT = "You turn a workflow a person describes into a plan for a LoopEngine agent.\n\nLoopEngine agents call tools. Tools come from abilities (installable packages: public ones on npm, or the workspace's own private ones) or are built in. Each tool has a permission: allow (runs on its own), ask (waits for a person to approve, edit or deny it) or deny. When nobody is in Chat, questions and approvals go to the agent's messaging app (Slack, Telegram, Lark or email) and the run waits, for days if needed, then carries on.\n\nHow to plan:\n1. Look before you plan: list_agents (what exists, and what each agent's tools and rules are), list_workspace_abilities, search_public_abilities for each kind of step, ability_details for any ability you might use (its exact tool names and the settings it needs), and list_connections.\n2. Split the workflow into steps, in order. For each step:\n   - something to fetch or do: kind \"tool\", with the exact tool name and where it comes from. Pick the source in this order:\n     a. A tool the target agent already has (from list_agents): use it, nothing to install.\n     b. An ability: a workspace ability (list_workspace_abilities) or a public one (search_public_abilities, e.g. \"firecrawl\" or \"web search\" for searching and reading the web). Set \"ability\" to its install spec (the npm name, or a workspace ability's spec) and use the exact tool name from ability_details.\n     c. Only when no ability can do it, and search_mcp_servers is available: an app's MCP server. Search for the app (e.g. \"linear\", \"stripe\"), pick the app's own server (official), else a saved or verified one, then call mcp_server_tools. Set \"mcp\" to the server's id, and \"tool\" to its exact tool name when mcp_server_tools lists them (leave \"tool\" empty when it needs a key first, and say in \"detail\" what the step does). It's set up as a private ability when the workflow is created, which picks its tools and their permissions, so add no rules for MCP tools.\n   - the person chooses or answers (\"ask me which\", \"let me pick\"): kind \"ask\", tool \"system_ask_user\" (built in, no ability). Say what options are offered. It reaches them through the agent's messaging app by itself, so don't add a separate step to post to Slack or another chat first, and don't install a chat ability just to ask.\n   - the person reviews or approves before something happens (\"let me review it\", \"before it's sent\"): kind \"approval\", on the tool that does that thing; its rule becomes \"ask\".\n   - the agent's own work (writing, summarising, choosing): kind \"other\".\n   - nothing found can do it: set \"missing\" to what's needed, and add it to gaps.\n3. 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.\n4. 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.\n5. 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.\n6. 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.\n7. 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.\n8. 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.\n9. 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.\n\nThen 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 declare const WORKFLOW_PLANNER_PROMPT = "You turn a workflow a person describes into a plan for a LoopEngine agent.\n\nLoopEngine agents call tools. Tools come from abilities (installable packages: public ones on npm, or the workspace's own private ones) or are built in. Each tool has a permission: allow (runs on its own), ask (waits for a person to approve, edit or deny it) or deny. When nobody is in Chat, questions and approvals go to the agent's messaging app (Slack, Telegram, Lark or email) and the run waits, for days if needed, then carries on.\n\nHow to plan:\n1. Look before you plan: list_agents (what exists, and what each agent's tools and rules are), list_workspace_abilities, search_public_abilities for each kind of step, ability_details for any ability you might use (its exact tool names and the settings it needs), and list_connections.\n2. Split the workflow into steps, in order. For each step:\n   - something to fetch or do: kind \"tool\", with the exact tool name and where it comes from. Pick the source in this order:\n     a. A tool the target agent already has (from list_agents): use it, nothing to install.\n     b. An ability: a workspace ability (list_workspace_abilities) or a public one (search_public_abilities, e.g. \"firecrawl\" or \"web search\" for searching and reading the web). Set \"ability\" to its install spec (the npm name, or a workspace ability's spec) and use the exact tool name from ability_details.\n     c. Only when no ability can do it, and search_mcp_servers is available: an app's MCP server. Search for the app (e.g. \"linear\", \"stripe\"), pick the app's own server (official), else a saved or verified one, then call mcp_server_tools. Set \"mcp\" to the server's id, and \"tool\" to its exact tool name when mcp_server_tools lists them (leave \"tool\" empty when it needs a key first, and say in \"detail\" what the step does). It's set up as a private ability when the workflow is created, which picks its tools and their permissions, so add no rules for MCP tools.\n   - the person chooses or answers (\"ask me which\", \"let me pick\"): kind \"ask\", tool \"system_ask_user\" (built in, no ability). Say what options are offered. It reaches them through the agent's messaging app by itself, so don't add a separate step to post to Slack or another chat first, and don't install a chat ability just to ask.\n   - the person reviews or approves before something happens (\"let me review it\", \"before it's sent\"): kind \"approval\", on the tool that does that thing; its rule becomes \"ask\".\n   - the agent's own work (writing, summarising, choosing): kind \"other\".\n   - nothing found can do it: set \"missing\" to what's needed, and add it to gaps.\n3. 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.\n4. 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.\n5. Trigger: how a run starts. startMessage is what the agent receives when it starts.\n   - schedule: a time or interval (\"every Monday at 9\" is every \"7d\", at \"09:00\", weekday 1).\n   - webhook: when something happens in another service that can call a URL (\"when a Stripe dispute comes in\", \"when a GitHub issue is opened\", \"when a Shopify order is paid\", \"when our app sends a new signup\"). Fill in \"webhook\" (below). Prefer it over polling on a schedule whenever the service sends webhooks.\n   - on_request: started by a person, from Chat, a message, the Run button or an app's API call.\n   A workflow that runs on a schedule and on an event as well: trigger schedule, and fill in \"webhook\" too.\n   webhook: sender (\"stripe\", \"github\", \"shopify\", \"standard\" for Standard Webhooks senders such as Clerk, Resend or Svix, else \"custom\" for the person's own app or any other service); a short name (\"Stripe: new disputes\"); setup: one sentence on what to pick in the sender's webhook settings; filter: which events start a run; mapping: each parameter from a dot path in the payload. What senders send:\n   - Stripe: one endpoint can get many event types, so filter path \"type\", values the event names (charge.dispute.created, checkout.session.completed, invoice.payment_failed, customer.subscription.deleted). The object is at data.object: data.object.id, data.object.customer, data.object.amount, data.object.charge.\n   - GitHub: the event type is chosen in GitHub's settings (Issues, Pull requests, Pushes), so say it in setup; filter path \"action\", values such as opened, closed, created. Fields: issue.number, issue.title, pull_request.number, repository.full_name, sender.login.\n   - Shopify: one webhook per topic (orders/paid, orders/create, customers/create), chosen in Shopify, so say it in setup and use no filter. The body is the object itself: id, name (the order number, like #1001), email, total_price, financial_status.\n   - standard: filter path \"type\" (user.created, email.bounced); fields under data (data.id, data.email_addresses).\n   - custom: whatever the person's app sends; say in setup what to post (JSON with these fields) and use the paths you described. Set \"header\" when the person names the signature header.\n   Every required parameter should come from the payload through mapping; parameters are the only way event details reach the run.\n6. Notify (scheduled and webhook 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.\n7. 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.\n8. 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.\n9. 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.\n\nThen 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 declare function workflowPlannerTools(withMcp?: boolean): ToolSchema[];
 /** lowercase-hyphenated, 2–40 characters. */
 export declare function slugify(value: string, fallback?: string): string;
 /** A plan from the model's save_plan input, or undefined when it lacks a
  * name, steps, a skill or a new-agent prompt. Fills in what can be derived. */
 export declare function validateWorkflowPlan(raw: unknown): WorkflowPlan | undefined;
+/** A plan's webhook, tidied: a known sender, a filter with values, and a
+ * mapping only for parameters the workflow has. Undefined without a
+ * sender. Also used on a plan edited before Create. */
+export declare function planWebhook(raw: unknown, parameters: Record<string, WorkflowParameter>): PlannedWebhook | undefined;
+/** What the person should know about a planned webhook: required
+ * parameters nothing in the payload fills. */
+export declare function webhookNotes(webhook: PlannedWebhook, parameters: Record<string, WorkflowParameter>): string[];
 /** A plan's notify choice; off when the planner gave none. */
 export declare function planNotify(raw: unknown): WorkflowPlan['notify'];
 /** A plan's parameters, tidied: names made snake_case (or dropped), a

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

@@ -16,8 +16,19 @@ How to plan:
    - nothing found can do it: set "missing" to what's needed, and add it to gaps.
 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. 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.
+5. Trigger: how a run starts. startMessage is what the agent receives when it starts.
+   - schedule: a time or interval ("every Monday at 9" is every "7d", at "09:00", weekday 1).
+   - webhook: when something happens in another service that can call a URL ("when a Stripe dispute comes in", "when a GitHub issue is opened", "when a Shopify order is paid", "when our app sends a new signup"). Fill in "webhook" (below). Prefer it over polling on a schedule whenever the service sends webhooks.
+   - on_request: started by a person, from Chat, a message, the Run button or an app's API call.
+   A workflow that runs on a schedule and on an event as well: trigger schedule, and fill in "webhook" too.
+   webhook: sender ("stripe", "github", "shopify", "standard" for Standard Webhooks senders such as Clerk, Resend or Svix, else "custom" for the person's own app or any other service); a short name ("Stripe: new disputes"); setup: one sentence on what to pick in the sender's webhook settings; filter: which events start a run; mapping: each parameter from a dot path in the payload. What senders send:
+   - Stripe: one endpoint can get many event types, so filter path "type", values the event names (charge.dispute.created, checkout.session.completed, invoice.payment_failed, customer.subscription.deleted). The object is at data.object: data.object.id, data.object.customer, data.object.amount, data.object.charge.
+   - GitHub: the event type is chosen in GitHub's settings (Issues, Pull requests, Pushes), so say it in setup; filter path "action", values such as opened, closed, created. Fields: issue.number, issue.title, pull_request.number, repository.full_name, sender.login.
+   - Shopify: one webhook per topic (orders/paid, orders/create, customers/create), chosen in Shopify, so say it in setup and use no filter. The body is the object itself: id, name (the order number, like #1001), email, total_price, financial_status.
+   - standard: filter path "type" (user.created, email.bounced); fields under data (data.id, data.email_addresses).
+   - custom: whatever the person's app sends; say in setup what to post (JSON with these fields) and use the paths you described. Set "header" when the person names the signature header.
+   Every required parameter should come from the payload through mapping; parameters are the only way event details reach the run.
+6. Notify (scheduled and webhook 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.
@@ -59,7 +70,7 @@ export function workflowPlannerTools(withMcp = false) {
                     trigger: {
                         type: 'object',
                         properties: {
-                            kind: { type: 'string', enum: ['schedule', 'on_request'] },
+                            kind: { type: 'string', enum: ['schedule', 'webhook', 'on_request'] },
                             description: { type: 'string' },
                             every: { type: 'string' },
                             at: { type: 'string' },
@@ -74,9 +85,22 @@ export function workflowPlannerTools(withMcp = false) {
                     needsApprovals: { type: 'boolean' },
                     skill: { type: 'object', properties: { description: { type: 'string' }, body: { type: 'string' } }, required: ['description', 'body'] },
                     startMessage: { type: 'string' },
+                    webhook: {
+                        type: 'object',
+                        description: 'When an outside service\'s events start runs: its sender, which events, and the payload fields that fill each parameter.',
+                        properties: {
+                            sender: { type: 'string', enum: ['stripe', 'github', 'shopify', 'standard', 'custom'] },
+                            name: { type: 'string' },
+                            header: { type: 'string', description: 'custom only: the signature header, when known' },
+                            setup: { type: 'string', description: 'one sentence: what to pick in the sender\'s webhook settings' },
+                            filter: { type: 'object', properties: { path: { type: 'string' }, values: { type: 'array', items: { type: 'string' } } }, required: ['path', 'values'] },
+                            mapping: { type: 'object', description: 'parameter name -> dot path in the payload', additionalProperties: { type: 'string' } },
+                        },
+                        required: ['sender', 'name'],
+                    },
                     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.',
+                        description: 'Scheduled and webhook 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'],
                     },
@@ -144,7 +168,9 @@ export function validateWorkflowPlan(raw) {
             ...(typeof triggerRaw.at === 'string' && /^\d{1,2}:\d{2}$/.test(triggerRaw.at) ? { at: triggerRaw.at } : {}),
             ...(typeof triggerRaw.weekday === 'number' && triggerRaw.weekday >= 0 && triggerRaw.weekday <= 7 ? { weekday: triggerRaw.weekday } : {}),
         }
-        : { kind: 'on_request', description: str(triggerRaw.description, 200) ?? 'when asked' };
+        : triggerRaw.kind === 'webhook'
+            ? { kind: 'webhook', description: str(triggerRaw.description, 200) ?? 'when an event comes in' }
+            : { kind: 'on_request', description: str(triggerRaw.description, 200) ?? 'when asked' };
     // An MCP step's permissions are set when its server becomes an ability.
     const mcpTools = new Set(steps.flatMap((s) => (s.mcp && s.tool ? [s.tool] : [])));
     const rules = (Array.isArray(r.rules) ? r.rules : []).flatMap((x) => {
@@ -172,6 +198,15 @@ export function validateWorkflowPlan(raw) {
     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' });
+    const webhook = planWebhook(r.webhook, planned.parameters);
+    // A webhook described means events start it; a webhook start with none
+    // described is started by hand.
+    if (webhook && trigger.kind === 'on_request')
+        trigger.kind = 'webhook';
+    if (!webhook && trigger.kind === 'webhook')
+        trigger.kind = 'on_request';
+    if (webhook)
+        planned.notes.push(...webhookNotes(webhook, planned.parameters));
     return {
         name,
         id,
@@ -185,6 +220,7 @@ export function validateWorkflowPlan(raw) {
         skill: { description: str(skillRaw.description, 400) ?? summary, body: skillBody },
         startMessage,
         parameters: planned.parameters,
+        ...(webhook ? { webhook } : {}),
         notify: planNotify(r.notify),
         target: {
             kind: targetRaw.kind === 'existing' && str(targetRaw.agent, 80) ? 'existing' : 'new',
@@ -195,6 +231,44 @@ export function validateWorkflowPlan(raw) {
         gaps: [...gaps, ...planned.notes].slice(0, 12),
     };
 }
+const SENDERS = ['stripe', 'github', 'shopify', 'standard', 'custom'];
+/** A plan's webhook, tidied: a known sender, a filter with values, and a
+ * mapping only for parameters the workflow has. Undefined without a
+ * sender. Also used on a plan edited before Create. */
+export function planWebhook(raw, parameters) {
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    const w = raw;
+    if (!SENDERS.includes(w.sender))
+        return undefined;
+    const sender = w.sender;
+    const filterRaw = (w.filter ?? {});
+    const filterPath = str(filterRaw.path, 120);
+    const values = Array.isArray(filterRaw.values) ? filterRaw.values.flatMap((v) => (str(v, 120) ? [str(v, 120)] : [])).slice(0, 10) : [];
+    const mapping = {};
+    if (w.mapping && typeof w.mapping === 'object' && !Array.isArray(w.mapping)) {
+        for (const [param, path] of Object.entries(w.mapping)) {
+            const p = str(path, 200);
+            if (p && parameters[param] && /^[A-Za-z0-9_.-]+$/.test(p))
+                mapping[param] = p;
+        }
+    }
+    const header = sender === 'custom' ? str(w.header, 80) : undefined;
+    return {
+        sender,
+        name: str(w.name, 80) ?? `${sender === 'custom' ? 'App' : sender[0].toUpperCase() + sender.slice(1)} events`,
+        ...(header && /^[A-Za-z0-9-]{1,80}$/.test(header) ? { header } : {}),
+        ...(filterPath && values.length ? { filter: { path: filterPath, values } } : {}),
+        ...(Object.keys(mapping).length ? { mapping } : {}),
+        ...(str(w.setup, 300) ? { setup: str(w.setup, 300) } : {}),
+    };
+}
+/** What the person should know about a planned webhook: required
+ * parameters nothing in the payload fills. */
+export function webhookNotes(webhook, parameters) {
+    const unfilled = Object.entries(parameters).filter(([name, p]) => p.required && !webhook.mapping?.[name]).map(([name]) => name);
+    return unfilled.length ? [`Nothing in the webhook's payload fills ${unfilled.join(', ')}, so those runs would fail; map ${unfilled.length > 1 ? 'them' : 'it'} on the workflow's Webhooks after it's created.`] : [];
+}
 /** A plan's notify choice; off when the planner gave none. */
 export function planNotify(raw) {
     const n = raw && typeof raw === 'object' ? raw : {};

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