loopengine 0.3.0 → 0.3.2

package/dist/web/notifier-admin.js

@@ -1,3 +1,11 @@
+// Backs the console's Messaging tab: where an agent's durable
+// approvals/questions go (core/http-notifier.ts's describeNotifier plus
+// the deployment-wide default webhook), whether it answers replies there,
+// editing its agents/<name>/messaging.yml, a test send and recent
+// deliveries — and the decisions still waiting, shown in Permissions. Plain functions over loopengine's own modules
+// so adapters/http.ts (and the scaffolded copy create-loopengine ships)
+// only needs thin route handlers.
+import { randomBytes } from 'node:crypto';
 import { agentDirFor, createAgentEnv } from '../core/agent-env.js';
 import { decidePath } from '../core/approval-links.js';
 import { describeNotifier } from '../core/http-notifier.js';
@@ -7,8 +15,9 @@ import { SlackNotifier } from '../core/http-notify-triggers/slack.js';
 import { LarkNotifier } from '../core/http-notify-triggers/lark.js';
 import { TelegramNotifier, sendTestTelegramMessage } from '../core/http-notify-triggers/telegram.js';
 import { listDeliveries } from '../core/notifier-deliveries.js';
-import { NOTIFIER_CHANNELS, NOTIFIER_SECRET_VARS, PRIMARY_CHANNELS, NOTIFIER_SLACK_SIGNING_SECRET_VAR, NotifierFileError, notifierConfigFromFile, readActiveConnections, readMessagingConnections, readNotifierFile, removeMessagingConnection, removeNotifierFile, setPrimaryConnection, writeNotifierFile } from '../core/notifier-file.js';
+import { NOTIFIER_CHANNELS, NOTIFIER_SECRET_VARS, PRIMARY_CHANNELS, NOTIFIER_SLACK_SIGNING_SECRET_VAR, NOTIFIER_TELEGRAM_WEBHOOK_SECRET_VAR, NotifierFileError, notifierConfigFromFile, readActiveConnections, readMessagingConnections, readNotifierFile, removeMessagingConnection, removeNotifierFile, setPrimaryConnection, writeNotifierFile } from '../core/notifier-file.js';
 import { listSlackChannelMembers, listSlackChannels, slackAppManifest } from '../core/messaging/connectors/slack/index.js';
+import { telegramBotUsername, telegramPeople, setTelegramWebhook, telegramWebhookInfo } from '../core/messaging/connectors/telegram/index.js';
 import { setAgentEnvVar } from './env-admin.js';
 export function describeAgentNotifier(config, defaultWebhook) {
     const described = describeNotifier(config);
@@ -49,6 +58,11 @@ export function describeAgentNotifier(config, defaultWebhook) {
             // interactivityPath as you type.
             manifestTemplate: slackAppManifest({ agentName: config.name, interactivityUrl: '__INTERACTIVITY_URL__' }),
         },
+        telegram: {
+            // Set once the bot's webhook points here (setupAgentTelegramWebhook).
+            webhookSet: env.get(NOTIFIER_TELEGRAM_WEBHOOK_SECRET_VAR) !== undefined,
+            webhookPath: `/hooks/telegram/${encodeURIComponent(config.name)}`,
+        },
         deliveries: listDeliveries(config.name),
     };
 }
@@ -89,49 +103,131 @@ export function slackCredentialsFor(config) {
     const botToken = config.httpNotifier?.channel === 'slack' ? config.httpNotifier.config.botToken : env.get(NOTIFIER_SECRET_VARS.slack);
     return { botToken, signingSecret: env.get(NOTIFIER_SLACK_SIGNING_SECRET_VAR) };
 }
-/** Whether replies in a Slack request's thread are answered: on unless
- * the Messaging tab turned Conversations off. An agent whose Slack
- * notifier is set in code always answers. */
+const APP_NAMES = { slack: 'Slack', telegram: 'Telegram' };
+/** Whether replies in an app's request threads are answered: on unless
+ * that app's section of the Messaging tab turned Conversations off. An
+ * agent whose notifier is set in code answers in that app only. */
+export function conversationsOn(config, app) {
+    if (config.httpNotifier)
+        return config.httpNotifier.channel === app;
+    const file = savedConnection(config, app);
+    return Boolean(file) && file.conversations !== false;
+}
 export function slackConversationsOn(config) {
+    return conversationsOn(config, 'slack');
+}
+/** Whether a DM to the agent's bot in `app`, or a mention of it, starts a
+ * job (core/messaging/jobs.ts). Off unless turned on in that app's
+ * section; never for a notifier set in code. */
+export function jobsOn(config, app) {
     if (config.httpNotifier)
-        return config.httpNotifier.channel === 'slack';
-    try {
-        return readNotifierFile(agentDirFor(config))?.conversations !== false;
-    }
-    catch {
         return false;
-    }
+    return savedConnection(config, app)?.jobs === true;
 }
-/** The people who can decide this agent's requests from Slack: from
- * messaging.yml; none when the Slack notifier is set in code. */
-export function agentApprovers(config) {
+/** The people who can decide this agent's requests from `app`: from that
+ * app's connection in messaging.yml; none when the notifier is set in
+ * code. */
+export function agentApprovers(config, app = 'slack') {
     if (config.httpNotifier)
         return [];
-    try {
-        return readNotifierFile(agentDirFor(config))?.approvers ?? [];
-    }
-    catch {
-        return [];
-    }
+    return savedConnection(config, app)?.approvers ?? [];
 }
-/** Whether a Slack user's button click counts: anyone's does while the
- * agent has no approvers (as before approvers existed), only theirs once
- * it has some. `message` says who can, for a refused click. */
-export function slackClickAllowed(config, user) {
-    const approvers = agentApprovers(config);
+function approverList(app, approvers) {
+    return approvers.map((a) => (app === 'slack' ? `<@${a.user}>` : a.name ?? a.user)).join(', ');
+}
+/** Whether a person's button click counts: anyone's does while the
+ * agent has no approvers in that app (as before approvers existed), only
+ * theirs once it has some. `message` says who can, for a refused click. */
+export function clickAllowed(config, app, user) {
+    const approvers = agentApprovers(config, app);
     if (!approvers.length || (user && approvers.some((a) => a.user === user)))
         return { allowed: true };
-    return { allowed: false, message: `Only approvers can decide this: ${approvers.map((a) => `<@${a.user}>`).join(', ')}.` };
+    return { allowed: false, message: `Only approvers can decide this: ${approverList(app, approvers)}.` };
 }
-/** Replaces the approver list on the agent's saved Slack connection,
- * primary or not. Throws NotifierFileError when there's no Slack
- * connection to add them to. */
-export function setAgentApprovers(config, approvers) {
-    const file = savedConnection(config, 'slack');
+export function slackClickAllowed(config, user) {
+    return clickAllowed(config, 'slack', user);
+}
+/** Whether a person may start a job from a message, or continue one: an
+ * approver, once the app has any; with none, anyone in the agent's own
+ * channel or chat, but nobody by DM. */
+export function jobAllowed(config, app, message) {
+    const approvers = agentApprovers(config, app);
+    if (approvers.length) {
+        if (approvers.some((a) => a.user === message.user))
+            return { allowed: true };
+        return { allowed: false, message: `Only approvers can give me jobs here: ${approverList(app, approvers)}.` };
+    }
+    const file = savedConnection(config, app);
+    const home = app === 'slack' ? file?.channelId : file?.chatId;
+    if (!message.direct && home && home === message.conversation)
+        return { allowed: true };
+    return { allowed: false, message: `Jobs by direct message need approvers: add yourself in this agent's Messaging tab in LoopEngine (${APP_NAMES[app]} section).` };
+}
+/** Replaces the approver list on the agent's saved connection for `app`,
+ * primary or not. Throws NotifierFileError when there's no connection
+ * for that app to add them to. */
+export function setAgentApprovers(config, approvers, app = 'slack') {
+    const file = savedConnection(config, app);
     if (!file)
-        throw new NotifierFileError('Save a Slack connection first');
+        throw new NotifierFileError(`Save a ${APP_NAMES[app]} connection first`);
     return writeNotifierFile(agentDirFor(config), { ...file, approvers: Array.isArray(approvers) ? approvers : [] }).approvers ?? [];
 }
+/** The bot token behind an agent's Telegram notifier and the secret its
+ * webhook was set up with, like slackCredentialsFor. */
+export function telegramCredentialsFor(config) {
+    const env = createAgentEnv(config.name, agentDirFor(config));
+    const botToken = config.httpNotifier?.channel === 'telegram' ? config.httpNotifier.config.botToken : env.get(NOTIFIER_SECRET_VARS.telegram);
+    return { botToken, webhookSecret: env.get(NOTIFIER_TELEGRAM_WEBHOOK_SECRET_VAR) };
+}
+/** The address remembered for links when the app's connection was saved. */
+export function connectionPublicUrl(config, app) {
+    return savedConnection(config, app)?.publicUrl;
+}
+/** The Telegram chat the agent posts requests in, if any. */
+export function telegramHomeChat(config) {
+    return config.httpNotifier?.channel === 'telegram' ? config.httpNotifier.config.chatId : savedConnection(config, 'telegram')?.chatId;
+}
+/** People who have written to the agent's Telegram bot, newest first,
+ * for picking approvers: the Bot API can't list a chat's members. */
+export function listAgentTelegramPeople(config) {
+    return telegramPeople(agentDirFor(config));
+}
+/** Points the agent's Telegram bot at POST /hooks/telegram/<agent> on
+ * `baseUrl` (LOOPENGINE_PUBLIC_URL wins), with a secret made once and
+ * kept in the agent's env. From then on requests get buttons and replies
+ * reach the agent. */
+export async function setupAgentTelegramWebhook(config, baseUrl) {
+    const { botToken, webhookSecret } = telegramCredentialsFor(config);
+    if (!botToken)
+        throw new Error('Save the Telegram bot token first');
+    const base = (process.env.LOOPENGINE_PUBLIC_URL || baseUrl).replace(/\/+$/, '');
+    if (!/^https:\/\//.test(base))
+        throw new Error('Telegram only sends updates to an https address; set LOOPENGINE_PUBLIC_URL to this server\'s https address');
+    const secret = webhookSecret ?? randomBytes(24).toString('hex');
+    const url = `${base}/hooks/telegram/${encodeURIComponent(config.name)}`;
+    const set = await setTelegramWebhook(botToken, url, secret);
+    if (!set.ok)
+        throw new Error(set.error);
+    if (!webhookSecret)
+        await setAgentEnvVar(config.name, NOTIFIER_TELEGRAM_WEBHOOK_SECRET_VAR, secret);
+    return { url, ...(set.botUsername ? { botUsername: set.botUsername } : {}) };
+}
+/** Where the agent's Telegram bot sends its updates now. */
+export async function agentTelegramWebhookInfo(config) {
+    const { botToken } = telegramCredentialsFor(config);
+    if (!botToken)
+        throw new Error('Save the Telegram bot token first');
+    const info = await telegramWebhookInfo(botToken);
+    if (!info.ok)
+        throw new Error(info.error);
+    const botUsername = await telegramBotUsername(botToken);
+    return {
+        ...(info.url ? { url: info.url } : {}),
+        ...(info.lastError ? { lastError: info.lastError } : {}),
+        pointsHere: Boolean(info.url?.endsWith(`/hooks/telegram/${encodeURIComponent(config.name)}`)),
+        ...(botUsername ? { botUsername } : {}),
+    };
+}
 /** The people in the agent's Slack channel, for picking approvers. */
 export async function listAgentSlackMembers(config) {
     const { botToken } = slackCredentialsFor(config);

package/dist/web/workflow-admin.d.ts

@@ -1,5 +1,6 @@
 import { type CreatedTemplateAgent, type TemplateChecklistItem, type TemplateCreateDeps } from './templates-admin.js';
 import { type WorkflowPlan, type WorkflowPlannerTools } from '../core/system-agents/workflow-planner.js';
+import { type PublicTrigger } from '../core/workflow-triggers.js';
 import { type GeneratedMcpAbility, type McpAbilityRequest } from '../core/mcp-ability-generator.js';
 import type { McpDirectoryServer } from '../core/mcp-directory.js';
 import { type Workflow } from '../core/workflows.js';
@@ -126,6 +127,15 @@ export interface CreatedWorkflow {
     checklist: TemplateChecklistItem[];
     schedule?: CreatedTemplateAgent['schedule'];
     scheduleError?: string;
+    /** The plan's webhook, made turned off until its signing secret is
+     * added. `token` makes its URL, shown once (the server turns it into
+     * `url`). */
+    webhook?: {
+        trigger: PublicTrigger;
+        token: string;
+        setup?: string;
+    };
+    webhookError?: string;
     loadError?: string;
 }
 export interface WorkflowCreateDeps extends TemplateCreateDeps {

package/dist/web/workflow-admin.js

@@ -10,7 +10,8 @@ import { addActauthRule, readActauthConfig } from './actauth-admin.js';
 import { writeSkill } from './skills-admin.js';
 import { createFromTemplateObject, installFailureReason, templateChecklist } from './templates-admin.js';
 import { templateScheduleStart } from '../core/system-agents/templates.js';
-import { planParameters, planWorkflowWithModel, slugify, workflowTemplate } from '../core/system-agents/workflow-planner.js';
+import { planParameters, planWebhook, planWorkflowWithModel, slugify, workflowTemplate } from '../core/system-agents/workflow-planner.js';
+import { createTrigger, publicTrigger } from '../core/workflow-triggers.js';
 import { mcpAbilityNames } from '../core/mcp-ability-generator.js';
 import { clearWorkflowFields, migrateWorkflowsFile, readWorkflow, readWorkflows, setWorkflowFields, validateParams, workflowRunMessage } from '../core/workflows.js';
 import { isUnderWay, listRuns } from '../core/workflow-runs.js';
@@ -291,6 +292,38 @@ export function getPlanJob(id) {
     const { at: _at, ...view } = job;
     return view;
 }
+const SENDER_NAMES = { stripe: 'Stripe', github: 'GitHub', shopify: 'Shopify', standard: 'the sender', custom: 'your app' };
+/** Makes the plan's webhook for the created workflow: turned off, since
+ * the sender's signing secret comes from the sender, after the URL is
+ * pasted there. */
+async function makePlannedWebhook(plan, agent, agentDir) {
+    const workflow = readWorkflow(agentDir, plan.id);
+    const webhook = workflow && planWebhook(plan.webhook, workflow.parameters);
+    if (!plan.webhook)
+        return { checklist: [] };
+    if (!workflow || !webhook)
+        return { webhookError: 'The webhook could not be set up from the plan; add it on the workflow’s Webhooks.', checklist: [] };
+    try {
+        const { trigger, token } = await createTrigger(agent, workflow, {
+            name: webhook.name,
+            enabled: false,
+            verify: { sender: webhook.sender, ...(webhook.header ? { header: webhook.header } : {}) },
+            ...(webhook.filter ? { filter: webhook.filter } : {}),
+            ...(webhook.mapping ? { mapping: webhook.mapping } : {}),
+            ...(plan.notify?.on && plan.trigger.kind === 'webhook' ? { notify: true } : {}),
+        });
+        return {
+            webhook: { trigger: publicTrigger(trigger), token, ...(webhook.setup ? { setup: webhook.setup } : {}) },
+            checklist: [{
+                    label: `Turn on the ${webhook.name} webhook: paste its URL into ${SENDER_NAMES[webhook.sender]}'s webhook settings, then add the signing secret ${webhook.sender === 'custom' ? 'your app signs with' : 'it shows'}`,
+                    href: `/agents/config?agent=${encodeURIComponent(agent)}&tab=overview`,
+                }],
+        };
+    }
+    catch (err) {
+        return { webhookError: err instanceof Error ? err.message : String(err), checklist: [] };
+    }
+}
 /** A to-do for each step nothing could be found for, first in the list. */
 function withMissingSteps(plan, agent, checklist) {
     const href = `/agents/config?agent=${encodeURIComponent(agent)}&tab=abilities`;
@@ -321,13 +354,16 @@ export async function createWorkflow(input, deps) {
         const connected = copyConnectedTools(plan, created.name, agents, deps.agentDir);
         const loadError = created.loadError;
         markWorkflow(deps.agentDir(created.name));
+        const hook = await makePlannedWebhook(plan, created.name, deps.agentDir(created.name));
         return {
             agent: created.name,
             newAgent: true,
             workflow: plan.name,
             abilities: { installed: [...created.abilities.installed, ...connected.copied], failed: [...mcp.failed, ...created.abilities.failed, ...connected.failed] },
             keptDecisions: [],
-            checklist: withMissingSteps(plan, created.name, created.checklist),
+            checklist: [...withMissingSteps(plan, created.name, created.checklist), ...hook.checklist],
+            ...(hook.webhook ? { webhook: hook.webhook } : {}),
+            ...(hook.webhookError ? { webhookError: hook.webhookError } : {}),
             ...(created.schedule ? { schedule: created.schedule } : {}),
             ...(created.scheduleError ? { scheduleError: created.scheduleError } : {}),
             ...(loadError ? { loadError } : {}),
@@ -433,13 +469,16 @@ export async function createWorkflow(input, deps) {
         }
     }
     markWorkflow(deps.agentDir(agent.name));
+    const hook = await makePlannedWebhook(plan, agent.name, deps.agentDir(agent.name));
     return {
         agent: agent.name,
         newAgent: false,
         workflow: plan.name,
         abilities: { installed, failed },
         keptDecisions: check.conflicts,
-        checklist: withMissingSteps(plan, agent.name, templateChecklist(template, agent.name, deps, failed, appsToConnect)),
+        checklist: [...withMissingSteps(plan, agent.name, templateChecklist(template, agent.name, deps, failed, appsToConnect)), ...hook.checklist],
+        ...(hook.webhook ? { webhook: hook.webhook } : {}),
+        ...(hook.webhookError ? { webhookError: hook.webhookError } : {}),
         ...(schedule ? { schedule } : {}),
         ...(scheduleError ? { scheduleError } : {}),
         ...(loadError ? { loadError } : {}),

package/dist/web/workflow-page.js

@@ -30,6 +30,11 @@ export const workflowPageHtml = `<!doctype html>
   .wf-target label { display: flex; gap: 8px; align-items: center; font-size: 13.5px; }
   .wf-notify { display: flex; gap: 8px; align-items: center; font-size: 13.5px; }
   .wf-notify input { margin: 0; }
+  .wf-hook { border: 1px solid var(--line); border-radius: var(--radius); padding: 10px 12px; display: grid; gap: 4px; background: var(--surface); font-size: 13px; }
+  .wf-hook ul { margin: 2px 0 0; padding-left: 18px; }
+  .wf-hook input[type="text"], .wf-hook input:not([type]) { font: inherit; padding: 6px 8px; border: 1px solid var(--line); border-radius: 6px; background: var(--bg); color: var(--ink); width: 100%; box-sizing: border-box; }
+  .wf-hook-row { display: flex; gap: 6px; flex-wrap: wrap; align-items: center; }
+  .wf-hook-row input { flex: 1; min-width: 220px; }
   .wf-params { display: grid; gap: 6px; }
   .wf-param { display: flex; gap: 8px; align-items: center; flex-wrap: wrap; font-size: 13px; }
   .wf-param .wf-param-name { width: 160px; font-family: var(--mono, monospace); }
@@ -73,8 +78,10 @@ ${consoleShellScript}
   var EXAMPLES = [
     ['Blog post', 'Every Monday morning, browse the web for timely blog post ideas about our product area. Ask me on Slack to pick one of the ideas. Then draft the post and let me review it before it is created.'],
     ['Weekly digest', 'Every Friday afternoon, search the web for news about our competitors and summarise the important changes. Send me the summary for review before it goes to the team channel.'],
-    ['Refund requests', 'When asked, look up the customer' + String.fromCharCode(8217) + 's order and check our refund policy. If a refund fits the policy, prepare it and ask me to approve it before it is issued.']
+    ['Refund requests', 'When asked, look up the customer' + String.fromCharCode(8217) + 's order and check our refund policy. If a refund fits the policy, prepare it and ask me to approve it before it is issued.'],
+    ['Stripe disputes', 'When a Stripe dispute comes in, look up the order and its delivery, write the evidence for Stripe, and ask me before submitting it.']
   ];
+  var SENDERS = { stripe: 'Stripe', github: 'GitHub', shopify: 'Shopify', standard: 'Standard Webhooks', custom: 'your app' };
   var state = { description: '', planned: null, agents: [], ready: false, canInstall: false };
 
   function esc(s) {
@@ -228,6 +235,24 @@ ${consoleShellScript}
     return { parameters: parameters };
   }
 
+  // The webhook the plan makes: whose events, which ones, and what each
+  // parameter is filled from. Made turned off; its signing secret comes
+  // from the sender, after Create.
+  function webhookPlanHtml(p) {
+    var w = p.webhook;
+    if (!w) return '';
+    var who = SENDERS[w.sender] || w.sender;
+    var lines = [];
+    if (w.filter) lines.push('Runs for ' + esc(w.filter.path) + ' ' + esc(w.filter.values.join(' or ')));
+    Object.keys(w.mapping || {}).forEach(function (param) { lines.push('<code>' + esc(param) + '</code> ' + String.fromCharCode(8592) + ' <code>' + esc(w.mapping[param]) + '</code> in the payload'); });
+    return '<div class="wf-hook">' +
+      '<label class="wf-notify"><input type="checkbox" id="wfWebhook" checked> <strong>' + (p.trigger.kind === 'schedule' ? 'Also start it from a webhook: ' : 'Webhook: ') + esc(w.name) + '</strong></label>' +
+      '<span class="hint">' + esc(who) + ' calls a private URL and each event starts a run. It' + String.fromCharCode(8217) + 's made turned off; after Create you paste the URL into ' + esc(w.sender === 'custom' ? 'your app' : who) + ' and add the signing secret.</span>' +
+      (lines.length ? '<ul class="hint">' + lines.map(function (l) { return '<li>' + l + '</li>'; }).join('') + '</ul>' : '') +
+      (w.setup ? '<span class="hint">' + esc(w.setup) + '</span>' : '') +
+      '</div>';
+  }
+
   function renderPlan(error) {
     var p = state.planned.plan;
     var suggested = p.target.kind === 'existing' && p.target.agent ? p.target.agent : '';
@@ -236,7 +261,8 @@ ${consoleShellScript}
       '<div class="wf-card">' +
         '<h2>' + esc(p.name) + '</h2><p style="margin:0">' + esc(p.summary) + '</p>' +
         '<p class="hint" style="margin:0"><strong>Starts:</strong> ' + esc(p.trigger.description) + (p.trigger.kind === 'schedule' ? ' (created paused; you turn it on)' : '') + '</p>' +
-        (p.trigger.kind === 'schedule'
+        webhookPlanHtml(p) +
+        (p.trigger.kind === 'schedule' || p.trigger.kind === 'webhook'
           ? '<label class="wf-notify"><input type="checkbox" id="wfNotify"' + (p.notify && p.notify.on ? ' checked' : '') + '> Send each run' + String.fromCharCode(8217) + 's result to you through the agent' + String.fromCharCode(8217) + 's messaging app</label>' +
             (p.notify && p.notify.reason ? '<p class="hint" style="margin:0 0 0 24px">' + esc(p.notify.reason) + '</p>' : '')
           : '') +
@@ -279,6 +305,11 @@ ${consoleShellScript}
       p.parameters = edited.parameters;
       var notifyBox = document.getElementById('wfNotify');
       if (notifyBox) p.notify = { on: notifyBox.checked, reason: (p.notify && p.notify.reason) || '' };
+      var webhookBox = document.getElementById('wfWebhook');
+      if (webhookBox && !webhookBox.checked) {
+        delete p.webhook;
+        if (p.trigger.kind === 'webhook') p.trigger.kind = 'on_request';
+      }
       var chosen = page.querySelector('input[name="wfTarget"]:checked');
       var target = chosen.value === 'new' ? { kind: 'new' } : { kind: 'existing', agent: chosen.value === 'other' ? document.getElementById('wfOther').value : chosen.dataset.agent };
       var btn = document.getElementById('wfCreate');
@@ -303,6 +334,7 @@ ${consoleShellScript}
       '<p style="margin:0">' + (c.newAgent ? 'Created as a new agent, <code>' + esc(c.agent) + '</code>.' : 'Added to <code>' + esc(c.agent) + '</code>.') + '</p>' +
       (c.schedule ? '<p class="hint" style="margin:0">Its schedule (' + esc(c.schedule.description) + ') is paused: turn it on in the agent' + String.fromCharCode(8217) + 's Schedules tab when you' + String.fromCharCode(8217) + 're ready.</p>' : '') +
       (c.scheduleError ? '<p class="error">The schedule could not be created: ' + esc(c.scheduleError) + '</p>' : '') +
+      webhookDoneHtml(c) +
       (c.loadError ? '<p class="error">The agent did not load: ' + esc(c.loadError) + '</p>' : '') +
       (c.abilities.failed.length ? '<p class="error">Not installed: ' + c.abilities.failed.map(function (f) { return esc(f.name) + ' (' + esc(f.error) + ')'; }).join('; ') + '</p>' : '') +
       (c.keptDecisions.length ? '<p class="hint" style="margin:0"><strong>Kept as they were:</strong> ' + c.keptDecisions.map(function (k) { return '<code>' + esc(k.tool) + '</code> stays ' + esc(LABELS[k.has]) + ' (the workflow wanted ' + esc(LABELS[k.wants]) + ')'; }).join('; ') + '. Change them in Permissions if you want.</p>' : '') +
@@ -311,6 +343,65 @@ ${consoleShellScript}
         '<button type="button" class="wf-btn plain" id="wfAnother">Describe another</button></div>' +
       '</div>';
     document.getElementById('wfAnother').addEventListener('click', function () { state.description = ''; state.planned = null; renderDescribe(); });
+    wireWebhookDone(c);
+  }
+
+  // The webhook made with the workflow: its URL (shown this once), where
+  // to paste it, and the signing secret that turns it on.
+  function webhookDoneHtml(c) {
+    if (c.webhookError) return '<p class="error">The webhook could not be made: ' + esc(c.webhookError) + '</p>';
+    if (!c.webhook) return '';
+    var t = c.webhook.trigger;
+    var who = SENDERS[t.verify.sender] || t.verify.sender;
+    var custom = t.verify.sender === 'custom';
+    return '<div class="wf-hook" id="wfHookDone">' +
+      '<strong>Turn on the webhook: ' + esc(t.name) + '</strong>' +
+      '<span>1. Copy this URL into ' + esc(custom ? 'your app' : who + String.fromCharCode(8217) + 's webhook settings') + '. It' + String.fromCharCode(8217) + 's shown only this once; make a new one on the workflow if it' + String.fromCharCode(8217) + 's lost.</span>' +
+      '<div class="wf-hook-row"><input id="wfHookUrl" readonly value="' + esc(c.webhook.url) + '"><button type="button" class="wf-btn plain" id="wfHookCopy">Copy</button></div>' +
+      (c.webhook.setup ? '<span class="hint">' + esc(c.webhook.setup) + '</span>' : '') +
+      '<span>2. ' + (custom
+        ? 'Choose a signing secret. Your app signs each request body with it (HMAC-SHA256, hex) in the <code>' + esc(t.verify.header || 'X-Signature') + '</code> header.'
+        : 'Paste the signing secret ' + esc(who) + ' shows for this webhook.') + '</span>' +
+      (custom && !t.verify.header ? '<div class="wf-hook-row"><input id="wfHookHeader" placeholder="Signature header, e.g. X-Signature" value="X-Signature"></div>' : '') +
+      '<div class="wf-hook-row"><input id="wfHookSecret" type="password" autocomplete="off" placeholder="Signing secret"><button type="button" class="wf-btn" id="wfHookOn">Turn it on</button></div>' +
+      '<span class="hint" id="wfHookStatus">Until then it' + String.fromCharCode(8217) + 's off: nothing that reaches the URL starts a run.</span>' +
+      '</div>';
+  }
+
+  function wireWebhookDone(c) {
+    if (!c.webhook) return;
+    var t = c.webhook.trigger;
+    var status = document.getElementById('wfHookStatus');
+    document.getElementById('wfHookCopy').addEventListener('click', function () {
+      var input = document.getElementById('wfHookUrl');
+      input.select();
+      if (navigator.clipboard) navigator.clipboard.writeText(input.value);
+      status.textContent = 'Copied.';
+    });
+    document.getElementById('wfHookOn').addEventListener('click', function () {
+      var secret = document.getElementById('wfHookSecret').value.trim();
+      if (!secret) { status.textContent = 'Paste the signing secret first.'; return; }
+      var verify = { sender: t.verify.sender, secret: secret };
+      if (t.verify.sender === 'custom') {
+        var headerInput = document.getElementById('wfHookHeader');
+        verify.header = headerInput ? headerInput.value.trim() : t.verify.header;
+        verify.algorithm = t.verify.algorithm || 'sha256';
+        verify.encoding = t.verify.encoding || 'hex';
+        if (t.verify.prefix) verify.prefix = t.verify.prefix;
+      }
+      var btn = document.getElementById('wfHookOn');
+      btn.disabled = true;
+      status.textContent = 'Turning it on' + ELLIPSIS;
+      fetch('/agents/' + encodeURIComponent(c.agent) + '/workflows/' + encodeURIComponent(t.workflow_id) + '/triggers/' + encodeURIComponent(t.trigger_id), {
+        method: 'PUT', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ verify: verify, enabled: true }),
+      }).then(function (r) { return r.json().then(function (b) { return { ok: r.ok, body: b }; }); }).then(function (r) {
+        btn.disabled = false;
+        if (!r.ok) { status.textContent = r.body.error || 'Could not turn it on.'; return; }
+        document.getElementById('wfHookSecret').value = '';
+        status.textContent = 'On. ' + (t.filter ? 'Each ' + t.filter.values.join(' or ') + ' event' : 'Each event') + ' that reaches the URL now starts a run; deliveries show on the workflow' + String.fromCharCode(8217) + 's Webhooks.';
+        btn.textContent = 'Update the secret';
+      }).catch(function (err) { btn.disabled = false; status.textContent = err.message; });
+    });
   }
 
   fetch('/workflows', { cache: 'no-store' })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopengine",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "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",