loopengine 0.3.1 → 0.3.2

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-triggers.d.ts

@@ -57,9 +57,12 @@ export interface WorkflowTrigger {
     /** 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. */
+/** A trigger as the console and API show it: no token hash, no secret,
+ * only whether one is set. */
 export type PublicTrigger = Omit<WorkflowTrigger, 'token_hash' | 'verify' | 'seen_ids'> & {
-    verify?: Omit<TriggerVerify, 'secret'>;
+    verify?: Omit<TriggerVerify, 'secret'> & {
+        secret_set: boolean;
+    };
 };
 export declare class TriggerError extends Error {
 }
@@ -96,8 +99,14 @@ export interface TriggerSettings {
     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). */
+ * what's wrong. With `existing` (a change), a setting left out keeps its
+ * value and null removes it, and a sender's secret is kept when only the
+ * sender is given again (the console never sees the secret).
+ *
+ * A trigger that checks a signature can be made turned off without its
+ * secret yet: the workflow planner makes one that way, for the person to
+ * add the secret the sender shows them. It can't be turned on until the
+ * secret is there. */
 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<{
@@ -113,7 +122,8 @@ export declare function rotateTrigger(id: string): Promise<{
 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. */
+/** Whether the sender's own signature on the raw body is right. Never
+ * with no secret: anyone can sign with an empty key. */
 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;

package/dist/core/workflow-triggers.js

@@ -96,16 +96,30 @@ 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 };
+    const { secret, ...shown } = verify;
+    return { ...rest, verify: { ...shown, secret_set: Boolean(secret) } };
 }
 /** 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). */
+ * what's wrong. With `existing` (a change), a setting left out keeps its
+ * value and null removes it, and a sender's secret is kept when only the
+ * sender is given again (the console never sees the secret).
+ *
+ * A trigger that checks a signature can be made turned off without its
+ * secret yet: the workflow planner makes one that way, for the person to
+ * add the secret the sender shows them. It can't be turned on until the
+ * secret is there. */
 export function checkTriggerSettings(input, workflow, existing) {
+    if (existing) {
+        const keys = ['verify', 'filter', 'mapping', 'payload_param', 'notify', 'callback_url'];
+        input = { ...input };
+        for (const key of keys)
+            if (input[key] === undefined && existing[key] !== undefined)
+                input[key] = existing[key];
+    }
     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');
+    const enabled = input.enabled === undefined ? existing?.enabled ?? true : input.enabled;
     let verify;
     if (input.verify !== undefined && input.verify !== null) {
         const v = input.verify;
@@ -113,10 +127,10 @@ export function checkTriggerSettings(input, workflow, existing) {
             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)
+        if (!secret && enabled)
             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))
+        if (v.sender === 'standard' && secret && !/^(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() : '';
@@ -169,7 +183,7 @@ export function checkTriggerSettings(input, workflow, existing) {
     const callbackUrl = input.callback_url ? checkCallbackUrl(input.callback_url) : undefined;
     return {
         name,
-        enabled: input.enabled === undefined ? existing?.enabled ?? true : input.enabled,
+        enabled,
         ...(verify ? { verify } : {}),
         ...(filter ? { filter } : {}),
         ...(mapping ? { mapping } : {}),
@@ -238,8 +252,11 @@ 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. */
+/** Whether the sender's own signature on the raw body is right. Never
+ * with no secret: anyone can sign with an empty key. */
 export function verifySenderSignature(verify, headers, raw, nowS = Math.floor(Date.now() / 1000)) {
+    if (!verify.secret)
+        return false;
     if (verify.sender === 'stripe') {
         const parts = (header(headers, 'stripe-signature') ?? '').split(',').map((p) => p.split('='));
         const t = Number(parts.find(([k]) => k === 't')?.[1]);