loopengine 0.1.68 → 0.1.69

package/README.md

@@ -182,9 +182,14 @@ waiting with Approve/Deny buttons. The tab warns you when an agent has
 Every notification links to a **decision page**: a signed, single-use
 link (`/decide/<token>`, valid 7 days) where whoever got the message can
 approve, deny, edit the arguments or answer a question, with no login and
-no app of your own. So the quickest setup is Slack: paste a bot token,
-pick a channel, save; each approval arrives with an "Open to approve or
-deny" link.
+no app of your own. So the quickest setup is Slack: create the Slack app
+from the manifest the console shows, paste its bot token, pick a channel
+from the list, save; each approval arrives with an "Open to approve or
+deny" link. Add the app's signing secret too and the message also gets
+Approve/Deny buttons, handled by LoopEngine itself at
+`/hooks/slack/<agent>`, with no handler to deploy. Lark cards carry the
+same link. Links and buttons need the server to be reachable from where
+people click (a public HTTPS address or a tunnel).
 
 For a third-party app calling an agent over plain HTTP:
 

package/dist/core/agent-config.d.ts

@@ -203,6 +203,8 @@ export type HttpNotifierConfig = {
         appId: string;
         appSecret: string;
         chatId: string;
+        publicUrl?: string;
+        buttons?: boolean;
     };
     events: HttpNotifierEvent[];
 } | {

package/dist/core/http-notifier.js

@@ -114,8 +114,8 @@ function buildResolved(httpNotifier) {
             break;
         }
         case 'lark': {
-            const { appId, appSecret, chatId } = httpNotifier.config;
-            const lark = new LarkNotifier({ appId, appSecret, chatId });
+            const { appId, appSecret, chatId, publicUrl, buttons } = httpNotifier.config;
+            const lark = new LarkNotifier({ appId, appSecret, chatId, publicUrl, buttons });
             resolved = {
                 approver: events.has('approval') ? lark : undefined,
                 questionHandler: events.has('question') ? lark : undefined,

package/dist/core/http-notify-triggers/lark.d.ts

@@ -9,11 +9,20 @@ export declare class LarkNotifier implements DurableApprover, DurableQuestionHan
     private readonly appId;
     private readonly appSecret;
     private readonly chatId;
+    private readonly publicUrl?;
+    private readonly buttons;
+    /** `publicUrl` / `buttons`: same meaning as SlackNotifier's — a decision
+     * link in each card when the server's address is known, and whether to
+     * add card buttons, which only work with a card-callback handler
+     * deployed (examples/notifier-handler/lark.ts). */
     constructor(options: {
         appId: string;
         appSecret: string;
         chatId: string;
+        publicUrl?: string;
+        buttons?: boolean;
     });
+    private decideLine;
     requestDurableApproval(tool: string, args: Record<string, unknown>, scope: Scope, reason: string): {
         pendingId: string;
     };

package/dist/core/http-notify-triggers/lark.js

@@ -38,6 +38,8 @@
 // sending and receiving ever run in different processes), deliberately
 // not the approach used here.
 import { randomUUID } from 'node:crypto';
+import { decidePath } from '../approval-links.js';
+import { publicBaseUrl } from './webhook.js';
 /** Fixed id for the question form card's own input field — used both
  * when *building* the card (notifyPendingQuestion below) and when
  * *reading* the human's answer back out of the callback payload (the
@@ -62,10 +64,22 @@ export class LarkNotifier {
     appId;
     appSecret;
     chatId;
+    publicUrl;
+    buttons;
+    /** `publicUrl` / `buttons`: same meaning as SlackNotifier's — a decision
+     * link in each card when the server's address is known, and whether to
+     * add card buttons, which only work with a card-callback handler
+     * deployed (examples/notifier-handler/lark.ts). */
     constructor(options) {
         this.appId = options.appId;
         this.appSecret = options.appSecret;
         this.chatId = options.chatId;
+        this.publicUrl = options.publicUrl;
+        this.buttons = options.buttons ?? true;
+    }
+    decideLine(pendingId, kind) {
+        const base = publicBaseUrl(this.publicUrl);
+        return base ? `\n[${kind === 'approval' ? 'Open to approve or deny' : 'Open to answer'}](${base}${decidePath(pendingId, kind)})` : '';
     }
     requestDurableApproval(tool, args, scope, reason) {
         const pendingId = randomUUID();
@@ -80,16 +94,18 @@ export class LarkNotifier {
                             tag: 'div',
                             text: {
                                 tag: 'lark_md',
-                                content: `**tool:** ${tool}\n**args:** \`${JSON.stringify(args)}\`\n**scope:** ${scope.tenant}/${scope.environment}/${scope.agent}\n**reason:** ${reason}`,
+                                content: `**tool:** ${tool}\n**args:** \`${JSON.stringify(args)}\`\n**scope:** ${scope.tenant}/${scope.environment}/${scope.agent}\n**reason:** ${reason}${this.decideLine(pendingId, 'approval')}`,
                             },
                         },
-                        {
-                            tag: 'action',
-                            actions: [
-                                { tag: 'button', text: { tag: 'plain_text', content: 'Approve' }, type: 'primary', value: { pendingId, decision: 'approve' } },
-                                { tag: 'button', text: { tag: 'plain_text', content: 'Deny' }, type: 'danger', value: { pendingId, decision: 'deny' } },
-                            ],
-                        },
+                        ...(this.buttons
+                            ? [{
+                                    tag: 'action',
+                                    actions: [
+                                        { tag: 'button', text: { tag: 'plain_text', content: 'Approve' }, type: 'primary', value: { pendingId, decision: 'approve' } },
+                                        { tag: 'button', text: { tag: 'plain_text', content: 'Deny' }, type: 'danger', value: { pendingId, decision: 'deny' } },
+                                    ],
+                                }]
+                            : []),
                     ],
                 };
                 await this.sendCard(token, card, pendingId);
@@ -114,19 +130,23 @@ export class LarkNotifier {
                     config: { wide_screen_mode: true },
                     header: { title: { tag: 'plain_text', content: `Question from ${agent}` } },
                     elements: [
-                        { tag: 'div', text: { tag: 'lark_md', content: question + (sessionId ? `\n_(session ${sessionId})_` : '') } },
-                        ...(optionButtons.length ? [{ tag: 'action', actions: optionButtons }] : []),
-                        {
-                            tag: 'form',
-                            name: 'answer_form',
-                            elements: [
-                                { tag: 'input', name: LARK_ANSWER_FIELD_TAG, placeholder: { tag: 'plain_text', content: 'Or type your own answer…' } },
+                        { tag: 'div', text: { tag: 'lark_md', content: question + (sessionId ? `\n_(session ${sessionId})_` : '') + this.decideLine(pendingId, 'question') } },
+                        ...(this.buttons
+                            ? [
+                                ...(optionButtons.length ? [{ tag: 'action', actions: optionButtons }] : []),
                                 {
-                                    tag: 'action',
-                                    actions: [{ tag: 'button', text: { tag: 'plain_text', content: 'Send' }, type: 'primary', action_type: 'form_submit', value: { pendingId } }],
+                                    tag: 'form',
+                                    name: 'answer_form',
+                                    elements: [
+                                        { tag: 'input', name: LARK_ANSWER_FIELD_TAG, placeholder: { tag: 'plain_text', content: 'Or type your own answer…' } },
+                                        {
+                                            tag: 'action',
+                                            actions: [{ tag: 'button', text: { tag: 'plain_text', content: 'Send' }, type: 'primary', action_type: 'form_submit', value: { pendingId } }],
+                                        },
+                                    ],
                                 },
-                            ],
-                        },
+                            ]
+                            : []),
                     ],
                 };
                 await this.sendCard(token, card, pendingId);

package/dist/core/notifier-file.d.ts

@@ -17,6 +17,10 @@ export interface NotifierFile {
 }
 /** The env var each channel's secret is read from, per agent. */
 export declare const NOTIFIER_SECRET_VARS: Record<NotifierFileChannel, string>;
+/** Optional: a Slack app's signing secret, per agent. Set, it turns on
+ * Approve/Deny buttons in Slack, handled by the server itself at
+ * POST /hooks/slack/<agent>; unset, messages carry only the decision link. */
+export declare const NOTIFIER_SLACK_SIGNING_SECRET_VAR = "LOOPENGINE_NOTIFIER_SLACK_SIGNING_SECRET";
 export declare class NotifierFileError extends Error {
 }
 export declare function notifierFilePath(dir: string): string;

package/dist/core/notifier-file.js

@@ -17,6 +17,10 @@ export const NOTIFIER_SECRET_VARS = {
     slack: 'LOOPENGINE_NOTIFIER_SLACK_BOT_TOKEN',
     lark: 'LOOPENGINE_NOTIFIER_LARK_APP_SECRET',
 };
+/** Optional: a Slack app's signing secret, per agent. Set, it turns on
+ * Approve/Deny buttons in Slack, handled by the server itself at
+ * POST /hooks/slack/<agent>; unset, messages carry only the decision link. */
+export const NOTIFIER_SLACK_SIGNING_SECRET_VAR = 'LOOPENGINE_NOTIFIER_SLACK_SIGNING_SECRET';
 const CHANNELS = ['webhook', 'slack', 'lark'];
 const EVENTS = ['approval', 'question', 'run_start', 'run_finish'];
 export class NotifierFileError extends Error {
@@ -95,10 +99,19 @@ export function notifierConfigFromFile(file, env) {
         case 'webhook':
             return { config: { channel: 'webhook', config: { webhookUrl: file.url, webhookSecret: secret, publicUrl: file.publicUrl }, events: file.events } };
         case 'slack':
-            // No interactive buttons: a console-configured Slack notifier has
-            // no interactivity endpoint behind it; the decision link replaces them.
-            return { config: { channel: 'slack', config: { botToken: secret, channelId: file.channelId, publicUrl: file.publicUrl, buttons: false }, events: file.events } };
+            // Buttons only once the agent has a signing secret, i.e. the Slack
+            // app's interactivity points at /hooks/slack/<agent>; otherwise the
+            // decision link does the job.
+            return {
+                config: {
+                    channel: 'slack',
+                    config: { botToken: secret, channelId: file.channelId, publicUrl: file.publicUrl, buttons: Boolean(env.get(NOTIFIER_SLACK_SIGNING_SECRET_VAR)) },
+                    events: file.events,
+                },
+            };
         case 'lark':
-            return { config: { channel: 'lark', config: { appId: file.appId, appSecret: secret, chatId: file.chatId }, events: file.events } };
+            // No card buttons: nothing built in handles Lark's card callbacks yet,
+            // so a console-configured Lark notifier relies on the decision link.
+            return { config: { channel: 'lark', config: { appId: file.appId, appSecret: secret, chatId: file.chatId, publicUrl: file.publicUrl, buttons: false }, events: file.events } };
     }
 }

package/dist/core/slack-interactions.d.ts

@@ -0,0 +1,59 @@
+export declare const SLACK_ANSWER_BLOCK_ID = "answer_block";
+export declare const SLACK_ANSWER_ACTION_ID = "answer_input";
+/** https://api.slack.com/authentication/verifying-requests-from-slack —
+ * rejects anything older than five minutes, so a captured request can't
+ * be replayed later. */
+export declare function verifySlackRequest(rawBody: string, timestamp: string | undefined, signature: string | undefined, signingSecret: string, nowMs?: number): boolean;
+export type SlackInteraction = {
+    type: 'decide';
+    pendingId: string;
+    decision: 'approve' | 'deny';
+    responseUrl?: string;
+    user?: string;
+} | {
+    type: 'answer';
+    pendingId: string;
+    answer: string;
+    responseUrl?: string;
+    user?: string;
+} | {
+    type: 'open_answer';
+    pendingId: string;
+    triggerId: string;
+} | {
+    type: 'ignore';
+};
+/** Reads Slack's form-encoded `payload=<json>` body into the one thing
+ * it asks for. Anything unrecognized is `ignore`. */
+export declare function parseSlackInteraction(rawBody: string): SlackInteraction;
+/** Opens the free-text answer modal for "Other…". Slack's trigger_id
+ * expires three seconds after the click, so call this before anything slow. */
+export declare function openSlackAnswerModal(botToken: string, triggerId: string, pendingId: string): Promise<void>;
+/** Replaces the original message (its buttons included) with what
+ * happened, so nobody clicks a decision that's already made. */
+export declare function replyInSlack(responseUrl: string, text: string): Promise<void>;
+/** What to say in Slack after a decision, from the resolve route's own
+ * response body. */
+export declare function slackOutcomeText(kind: 'approve' | 'deny' | 'answer', status: number, body: {
+    alreadyResolved?: boolean;
+    resolved?: boolean;
+    text?: string;
+    error?: string;
+    pending?: unknown[];
+}, user?: string): string;
+export interface SlackChannel {
+    id: string;
+    name: string;
+    isPrivate: boolean;
+    isMember: boolean;
+}
+/** Channels the bot can see — needs the channels:read (and, for private
+ * channels, groups:read) scope. */
+export declare function listSlackChannels(botToken: string): Promise<SlackChannel[]>;
+/** A Slack app manifest for one agent's notifier: a bot that can post and
+ * read the channel list, with interactivity pointed at this server.
+ * Paste it into api.slack.com/apps → Create New App → From a manifest. */
+export declare function slackAppManifest(options: {
+    agentName: string;
+    interactivityUrl: string;
+}): Record<string, unknown>;

package/dist/core/slack-interactions.js

@@ -0,0 +1,168 @@
+// What the server needs to handle Slack button clicks itself (POST
+// /hooks/slack/<agent> in adapters/http.ts), so a Slack notifier's
+// Approve/Deny and answer buttons work with no handler of your own to
+// deploy: request verification, reading the interaction payload, the
+// "Other…" answer modal, replying in the original message, listing
+// channels for the console's channel picker, and the app manifest the
+// console shows for creating the Slack app.
+//
+// Same button contract SlackNotifier (core/http-notify-triggers/slack.ts)
+// sends: action_id approve|deny with the pendingId as value,
+// answer_option with {pendingId, answer}, open_answer_modal with the
+// pendingId, and the modal's answer under ANSWER_BLOCK_ID/ANSWER_ACTION_ID.
+import { createHmac, timingSafeEqual } from 'node:crypto';
+export const SLACK_ANSWER_BLOCK_ID = 'answer_block';
+export const SLACK_ANSWER_ACTION_ID = 'answer_input';
+/** https://api.slack.com/authentication/verifying-requests-from-slack —
+ * rejects anything older than five minutes, so a captured request can't
+ * be replayed later. */
+export function verifySlackRequest(rawBody, timestamp, signature, signingSecret, nowMs = Date.now()) {
+    if (!timestamp || !signature)
+        return false;
+    const age = Math.abs(nowMs / 1000 - Number(timestamp));
+    if (!Number.isFinite(age) || age > 60 * 5)
+        return false;
+    const expected = Buffer.from(`v0=${createHmac('sha256', signingSecret).update(`v0:${timestamp}:${rawBody}`).digest('hex')}`);
+    const actual = Buffer.from(signature);
+    return expected.length === actual.length && timingSafeEqual(expected, actual);
+}
+/** Reads Slack's form-encoded `payload=<json>` body into the one thing
+ * it asks for. Anything unrecognized is `ignore`. */
+export function parseSlackInteraction(rawBody) {
+    const raw = new URLSearchParams(rawBody).get('payload');
+    if (!raw)
+        return { type: 'ignore' };
+    let payload;
+    try {
+        payload = JSON.parse(raw);
+    }
+    catch {
+        return { type: 'ignore' };
+    }
+    const user = payload.user?.id;
+    if (payload.type === 'view_submission' && payload.view?.private_metadata) {
+        const answer = payload.view.state?.values?.[SLACK_ANSWER_BLOCK_ID]?.[SLACK_ANSWER_ACTION_ID]?.value ?? '';
+        return { type: 'answer', pendingId: payload.view.private_metadata, answer, user };
+    }
+    if (payload.type !== 'block_actions')
+        return { type: 'ignore' };
+    const action = payload.actions?.[0];
+    if (!action?.value)
+        return { type: 'ignore' };
+    switch (action.action_id) {
+        case 'approve':
+        case 'deny':
+            return { type: 'decide', pendingId: action.value, decision: action.action_id, responseUrl: payload.response_url, user };
+        case 'answer_option': {
+            try {
+                const { pendingId, answer } = JSON.parse(action.value);
+                return pendingId && typeof answer === 'string' ? { type: 'answer', pendingId, answer, responseUrl: payload.response_url, user } : { type: 'ignore' };
+            }
+            catch {
+                return { type: 'ignore' };
+            }
+        }
+        case 'open_answer_modal':
+            return payload.trigger_id ? { type: 'open_answer', pendingId: action.value, triggerId: payload.trigger_id } : { type: 'ignore' };
+        default:
+            return { type: 'ignore' };
+    }
+}
+/** Opens the free-text answer modal for "Other…". Slack's trigger_id
+ * expires three seconds after the click, so call this before anything slow. */
+export async function openSlackAnswerModal(botToken, triggerId, pendingId) {
+    const res = await fetch('https://slack.com/api/views.open', {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${botToken}`, 'content-type': 'application/json; charset=utf-8' },
+        body: JSON.stringify({
+            trigger_id: triggerId,
+            view: {
+                type: 'modal',
+                callback_id: 'answer_modal',
+                private_metadata: pendingId,
+                title: { type: 'plain_text', text: 'Your answer' },
+                submit: { type: 'plain_text', text: 'Send' },
+                blocks: [
+                    {
+                        type: 'input',
+                        block_id: SLACK_ANSWER_BLOCK_ID,
+                        label: { type: 'plain_text', text: 'Answer' },
+                        element: { type: 'plain_text_input', action_id: SLACK_ANSWER_ACTION_ID, multiline: true },
+                    },
+                ],
+            },
+        }),
+    });
+    const body = (await res.json());
+    if (!body.ok)
+        throw new Error(`views.open failed: ${body.error}`);
+}
+/** Replaces the original message (its buttons included) with what
+ * happened, so nobody clicks a decision that's already made. */
+export async function replyInSlack(responseUrl, text) {
+    await fetch(responseUrl, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ replace_original: true, text }),
+    });
+}
+/** What to say in Slack after a decision, from the resolve route's own
+ * response body. */
+export function slackOutcomeText(kind, status, body, user) {
+    const who = user ? ` by <@${user}>` : '';
+    if (status >= 400)
+        return `:warning: Couldn't record that: ${body.error ?? `HTTP ${status}`}`;
+    if (body.alreadyResolved)
+        return 'Already decided elsewhere.';
+    const what = kind === 'approve' ? ':white_check_mark: Approved' : kind === 'deny' ? ':no_entry: Denied' : ':speech_balloon: Answered';
+    if (body.resolved)
+        return `${what}${who}. Still waiting on another decision in the same turn.`;
+    if (body.pending?.length)
+        return `${what}${who}. The agent needs another decision; a new message is on its way.`;
+    return `${what}${who}.${body.text ? `\n>${body.text.replace(/\n/g, '\n>')}` : ''}`;
+}
+/** Channels the bot can see — needs the channels:read (and, for private
+ * channels, groups:read) scope. */
+export async function listSlackChannels(botToken) {
+    const channels = [];
+    let cursor = '';
+    for (let page = 0; page < 10; page++) {
+        const params = new URLSearchParams({ types: 'public_channel,private_channel', exclude_archived: 'true', limit: '200' });
+        if (cursor)
+            params.set('cursor', cursor);
+        const res = await fetch(`https://slack.com/api/conversations.list?${params}`, { headers: { Authorization: `Bearer ${botToken}` } });
+        const body = (await res.json());
+        if (!body.ok) {
+            const reasons = {
+                missing_scope: 'The bot token is missing the channels:read scope; reinstall the app from the manifest',
+                invalid_auth: 'Slack rejected the bot token; copy the Bot User OAuth Token (xoxb-...) again',
+                not_authed: 'Enter the bot token first',
+                token_revoked: 'This bot token was revoked; reinstall the app and copy the new one',
+            };
+            throw new Error(reasons[body.error ?? ''] ?? `Slack said: ${body.error}`);
+        }
+        for (const c of body.channels ?? [])
+            channels.push({ id: c.id, name: c.name, isPrivate: Boolean(c.is_private), isMember: Boolean(c.is_member) });
+        cursor = body.response_metadata?.next_cursor ?? '';
+        if (!cursor)
+            break;
+    }
+    return channels.sort((a, b) => Number(b.isMember) - Number(a.isMember) || a.name.localeCompare(b.name));
+}
+/** A Slack app manifest for one agent's notifier: a bot that can post and
+ * read the channel list, with interactivity pointed at this server.
+ * Paste it into api.slack.com/apps → Create New App → From a manifest. */
+export function slackAppManifest(options) {
+    const name = `LoopEngine ${options.agentName}`.slice(0, 35);
+    return {
+        display_information: { name, description: `Approval requests and questions from the ${options.agentName} agent` },
+        features: { bot_user: { display_name: name, always_online: true } },
+        oauth_config: { scopes: { bot: ['chat:write', 'channels:read', 'groups:read'] } },
+        settings: {
+            interactivity: { is_enabled: true, request_url: options.interactivityUrl },
+            org_deploy_enabled: false,
+            socket_mode_enabled: false,
+            token_rotation_enabled: false,
+        },
+    };
+}

package/dist/index.d.ts

@@ -10,10 +10,12 @@ export { setUsageSink, recordUsage, type UsageEvent, type UsageSink } from '#cor
 export { readNotifierFile, writeNotifierFile, removeNotifierFile, validateNotifierFile, notifierConfigFromFile, NotifierFileError, NOTIFIER_SECRET_VARS, type NotifierFile } from '#core/notifier-file.js';
 export { listDeliveries, recordDelivery, type NotifierDelivery } from '#core/notifier-deliveries.js';
 export { describeNotifier } from '#core/http-notifier.js';
+export { verifySlackRequest, parseSlackInteraction, openSlackAnswerModal, replyInSlack, slackOutcomeText, listSlackChannels, slackAppManifest, type SlackInteraction, type SlackChannel } from '#core/slack-interactions.js';
+export { NOTIFIER_SLACK_SIGNING_SECRET_VAR } from '#core/notifier-file.js';
 export { createDecisionToken, verifyDecisionToken, decidePath, decideLinkMaker, decisionLinkTtlMs, type DecisionKind } from '#core/approval-links.js';
 export { renderDecidePage, renderDecideGonePage, renderDecideInvalidPage, type DecidePageItem } from './web/decide-page.js';
 export { sendTestWebhook } from '#core/http-notify-triggers/webhook.js';
-export { describeAgentNotifier, saveAgentNotifier, removeAgentNotifier, testAgentNotifier, listAgentPending, type DefaultWebhook } from './web/notifier-admin.js';
+export { describeAgentNotifier, saveAgentNotifier, removeAgentNotifier, testAgentNotifier, listAgentPending, slackCredentialsFor, listAgentSlackChannels, type DefaultWebhook } from './web/notifier-admin.js';
 export type * from './core/loop-events.js';
 export { streamMessage, streamMessageWithCallbacks, sendMessage, approveCall, denyCall, answerQuestion, getSessionHistory, } from './core/client.js';
 export type { RequestOptions, SendMessageResult, PendingApprovalResult, PendingQuestionResult, PendingResult, MessageResult, StreamMessageCallbacks, } from './core/client.js';

package/dist/index.js

@@ -12,10 +12,12 @@ export { setUsageSink, recordUsage } from '#core/usage.js';
 export { readNotifierFile, writeNotifierFile, removeNotifierFile, validateNotifierFile, notifierConfigFromFile, NotifierFileError, NOTIFIER_SECRET_VARS } from '#core/notifier-file.js';
 export { listDeliveries, recordDelivery } from '#core/notifier-deliveries.js';
 export { describeNotifier } from '#core/http-notifier.js';
+export { verifySlackRequest, parseSlackInteraction, openSlackAnswerModal, replyInSlack, slackOutcomeText, listSlackChannels, slackAppManifest } from '#core/slack-interactions.js';
+export { NOTIFIER_SLACK_SIGNING_SECRET_VAR } from '#core/notifier-file.js';
 export { createDecisionToken, verifyDecisionToken, decidePath, decideLinkMaker, decisionLinkTtlMs } from '#core/approval-links.js';
 export { renderDecidePage, renderDecideGonePage, renderDecideInvalidPage } from './web/decide-page.js';
 export { sendTestWebhook } from '#core/http-notify-triggers/webhook.js';
-export { describeAgentNotifier, saveAgentNotifier, removeAgentNotifier, testAgentNotifier, listAgentPending } from './web/notifier-admin.js';
+export { describeAgentNotifier, saveAgentNotifier, removeAgentNotifier, testAgentNotifier, listAgentPending, slackCredentialsFor, listAgentSlackChannels } from './web/notifier-admin.js';
 // The framework-agnostic browser client for adapters/http.ts's own wire
 // protocol (see client.ts's own header comment) — this, not a deep
 // subpath import, is how a consumer's React/Vue/etc. chat UI is meant to

package/dist/web/agents-config-page.js

@@ -962,6 +962,7 @@ ${consoleShellScript}
   // deliveries. Reloaded every time the tab opens, so the waiting list is
   // current. ----
 
+  var lastNotifier = null;
   var NOTIFIER_EVENTS = [
     ['approval', 'Approvals'], ['question', 'Questions'], ['run_finish', 'Run finished'], ['run_start', 'Run started']
   ];
@@ -1017,8 +1018,27 @@ ${consoleShellScript}
       '<label>Send to<select name="channel" id="notifierChannel">' +
         ['webhook', 'slack', 'lark'].map(function (c) { return '<option value="' + c + '"' + (f.channel === c ? ' selected' : '') + '>' + { webhook: 'Webhook (your app)', slack: 'Slack channel', lark: 'Lark / Feishu chat' }[c] + '</option>'; }).join('') +
       '</select></label>' +
-      field('webhook', '<label>Webhook URL<input type="url" name="url" placeholder="https://your-app.example.com/hooks/loopengine" value="' + escapeHtml(f.url || '') + '"></label>' + secretField('webhook', 'Signing secret')) +
-      field('slack', '<label>Channel ID<input name="channelId" placeholder="C0123ABC456" value="' + escapeHtml(f.channelId || '') + '"></label>' + secretField('slack', 'Bot token')) +
+      field('webhook', '<label>Webhook URL<input type="url" name="url" placeholder="https://your-app.example.com/hooks/loopengine" value="' + escapeHtml(f.url || '') + '"></label>' + secretField('webhook', 'Signing secret') +
+        '<p class="hint" style="margin:0">Your app checks the <code>X-Actauth-Signature</code> header (HMAC-SHA256 of the body with the signing secret). Each payload carries a <code>decideUrl</code> it can simply forward to a person, or it can decide itself by sending <code>{"decision":"approve"}</code> or <code>{"decision":"deny"}</code> to <code>resolveUrl</code>.</p>') +
+      field('slack',
+        '<details class="slack-step"' + (n.secretsSet && n.secretsSet.slack ? '' : ' open') + '><summary>Create the Slack app (once)</summary>' +
+          '<ol class="hint" style="margin:6px 0;padding-left:18px">' +
+            '<li>Open <a href="https://api.slack.com/apps?new_app=1" target="_blank" rel="noopener">Slack apps</a> &rarr; Create New App &rarr; From a manifest, and pick your workspace.</li>' +
+            '<li>Paste the manifest below, create the app, then Install to Workspace.</li>' +
+            '<li>Copy the <strong>Bot User OAuth Token</strong> (starts with xoxb-) from OAuth &amp; Permissions into the field below.</li>' +
+          '</ol>' +
+          '<textarea id="slackManifest" readonly rows="8" style="font-family:var(--font-mono);font-size:11.5px"></textarea>' +
+          '<button type="button" id="slackManifestCopy" style="margin-top:6px">Copy manifest</button>' +
+        '</details>' +
+        secretField('slack', 'Bot token') +
+        '<label>Channel <span class="hint">(invite the bot to a private channel first: /invite @its-name)</span>' +
+          '<span style="display:flex;gap:6px"><select id="slackChannelSelect" style="flex:1;min-width:0"><option value="">' + (f.channelId ? 'Saved: ' + escapeHtml(f.channelId) : 'Load channels to pick one') + '</option></select>' +
+          '<button type="button" id="slackLoadChannels">Load channels</button></span></label>' +
+        '<label>Channel ID <span class="hint">(filled in when you pick a channel)</span><input name="channelId" placeholder="C0123ABC456" value="' + escapeHtml(f.channelId || '') + '"></label>' +
+        '<label>Signing secret <span class="hint">(optional, from Basic Information; ' +
+          (n.slack && n.slack.signingSecretSet ? 'set &mdash; Approve/Deny buttons are on' : 'adds Approve/Deny buttons inside Slack; without it, messages carry the approval link') + ')</span>' +
+          '<input type="password" name="signingSecret" autocomplete="off"></label>' +
+        '<p class="hint" style="margin:0">Buttons send their clicks to <code id="slackInteractivityUrl"></code> (the manifest already points there).</p>') +
       field('lark', '<label>App ID<input name="appId" value="' + escapeHtml(f.appId || '') + '"></label><label>Chat ID<input name="chatId" value="' + escapeHtml(f.chatId || '') + '"></label>' + secretField('lark', 'App secret')) +
       '<label>Link address <span class="hint">(messages link here so people can approve without logging in; use an address they can reach)</span>' +
         '<input type="url" name="publicUrl" id="notifierPublicUrl" value="' + escapeHtml(n.publicUrl || f.publicUrl || location.origin) + '"' + (n.publicUrl ? ' disabled title="Set by LOOPENGINE_PUBLIC_URL"' : '') + '></label>' +
@@ -1031,7 +1051,7 @@ ${consoleShellScript}
       '<div style="display:flex;gap:8px;flex-wrap:wrap"><button type="submit"' + (n.canSave === false ? ' disabled' : '') + '>Save</button><button type="button" id="notifierTestBtn">Send test</button>' +
         (n.file ? '<button type="button" class="delete-btn" id="notifierRemoveBtn">Remove</button>' : '') + '</div>' +
       '<div id="notifierResult" class="hint"></div>' +
-      '<p class="hint" style="margin:0">For a webhook: your app checks the <code>X-Actauth-Signature</code> header (HMAC-SHA256 of the body with the signing secret). Each payload carries a <code>decideUrl</code> it can simply forward to a person, or it can decide itself by sending <code>{"decision":"approve"}</code> or <code>{"decision":"deny"}</code> to <code>resolveUrl</code>.</p>' +
+
       '</form>';
   }
 
@@ -1142,6 +1162,51 @@ ${consoleShellScript}
         result.textContent = 'Copy this secret into your app before saving; it is not shown again.';
       });
     }
+    // Slack: manifest follows the link address; Load channels fills the picker.
+    var n0 = lastNotifier;
+    var manifestEl = form.querySelector('#slackManifest');
+    var linkInput = form.querySelector('#notifierPublicUrl');
+    function refreshSlackManifest() {
+      if (!manifestEl || !n0 || !n0.slack) return;
+      var url = (linkInput.value || location.origin).replace(/[/]+$/, '') + n0.slack.interactivityPath;
+      manifestEl.value = JSON.stringify(n0.slack.manifestTemplate, null, 2).replace('__INTERACTIVITY_URL__', url);
+      var urlEl = form.querySelector('#slackInteractivityUrl');
+      if (urlEl) urlEl.textContent = url;
+    }
+    if (linkInput) linkInput.addEventListener('input', refreshSlackManifest);
+    refreshSlackManifest();
+    var copyManifest = form.querySelector('#slackManifestCopy');
+    if (copyManifest) {
+      copyManifest.addEventListener('click', function () {
+        manifestEl.select();
+        var done = function () { copyManifest.textContent = 'Copied'; setTimeout(function () { copyManifest.textContent = 'Copy manifest'; }, 1500); };
+        if (navigator.clipboard) navigator.clipboard.writeText(manifestEl.value).then(done, done); else done();
+      });
+    }
+    var loadChannels = form.querySelector('#slackLoadChannels');
+    var channelSelect = form.querySelector('#slackChannelSelect');
+    if (loadChannels) {
+      loadChannels.addEventListener('click', function () {
+        loadChannels.disabled = true;
+        result.textContent = 'Loading channels' + String.fromCharCode(8230);
+        var token = form.querySelector('input[name="secret_slack"]').value;
+        fetchJsonRetryOnce('/agents/' + encodeURIComponent(name) + '/notifier/slack-channels', {
+          method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ botToken: token }),
+        }).then(function (r) {
+          loadChannels.disabled = false;
+          if (!r.ok) { result.textContent = r.body.error || 'Could not load channels'; return; }
+          var current = form.querySelector('input[name="channelId"]').value;
+          channelSelect.innerHTML = '<option value="">Pick a channel</option>' + r.body.channels.map(function (c) {
+            return '<option value="' + escapeHtml(c.id) + '"' + (c.id === current ? ' selected' : '') + '>' + (c.isPrivate ? '&#128274; ' : '#') + escapeHtml(c.name) + (c.isMember ? '' : ' (bot not in channel yet)') + '</option>';
+          }).join('');
+          result.textContent = r.body.channels.length + ' channels found.';
+        });
+      });
+      channelSelect.addEventListener('change', function () {
+        if (channelSelect.value) form.querySelector('input[name="channelId"]').value = channelSelect.value;
+      });
+    }
+
     form.addEventListener('submit', function (ev) {
       ev.preventDefault();
       var data = new FormData(form);
@@ -1149,6 +1214,7 @@ ${consoleShellScript}
       var body = { channel: channel, events: data.getAll('events'), url: data.get('url'), channelId: data.get('channelId'), appId: data.get('appId'), chatId: data.get('chatId'), publicUrl: data.get('publicUrl') };
       var secret = data.get('secret_' + channel);
       if (secret) body.secret = secret;
+      if (channel === 'slack' && data.get('signingSecret')) body.signingSecret = data.get('signingSecret');
       result.textContent = 'Saving…';
       fetchJsonRetryOnce('/agents/' + encodeURIComponent(name) + '/notifier', {
         method: 'PUT', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body),
@@ -1182,6 +1248,7 @@ ${consoleShellScript}
     ]).then(function (results) {
       if (currentName !== name) return;
       if (!results[0].ok) throw new Error(results[0].body.error || 'request failed');
+      lastNotifier = results[0].body;
       content.innerHTML = renderApprovalsHtml(results[0].body);
       wireApprovalsHandlers(name);
       var pendingEl = detail.querySelector('#pendingContent');

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

@@ -2,6 +2,7 @@ import type { AgentConfig } from '../core/agent-config.js';
 import type { CheckpointStore } from '../core/durable-approvals.js';
 import { type DeliveryResult } from '../core/http-notify-triggers/webhook.js';
 import { type NotifierFileChannel } from '../core/notifier-file.js';
+import { type SlackChannel } from '../core/slack-interactions.js';
 /** The deployment-wide default webhook (LOOPENGINE_DEFAULT_WEBHOOK_URL /
  * _SECRET), which applies to the plain /messages route when an agent has
  * no notifier of its own. */
@@ -17,6 +18,12 @@ export declare function describeAgentNotifier(config: AgentConfig, defaultWebhoo
     secretsSet: {
         [k: string]: boolean;
     };
+    slack: {
+        signingSecretVar: string;
+        signingSecretSet: boolean;
+        interactivityPath: string;
+        manifestTemplate: Record<string, unknown>;
+    };
     deliveries: import("../core/notifier-deliveries.js").NotifierDelivery[];
     channel?: import("../core/agent-config.js").HttpNotifierConfig["channel"];
     events?: string[];
@@ -28,6 +35,17 @@ export declare function describeAgentNotifier(config: AgentConfig, defaultWebhoo
  * form includes one, the channel's secret into the agent's own env.
  * Throws NotifierFileError for an invalid form. */
 export declare function saveAgentNotifier(config: AgentConfig, body: Record<string, unknown>): Promise<void>;
+/** The bot token and signing secret behind an agent's Slack notifier —
+ * from AgentConfig.httpNotifier when it's Slack, else from the agent's
+ * env (the console-saved ones). The signing secret always comes from the
+ * agent env. */
+export declare function slackCredentialsFor(config: AgentConfig): {
+    botToken?: string;
+    signingSecret?: string;
+};
+/** Channels for the console's picker, with the token being typed in or,
+ * when none is given, the one already saved. */
+export declare function listAgentSlackChannels(config: AgentConfig, botToken?: string): Promise<SlackChannel[]>;
 /** Removes notifier.yml; the stored secret is left alone, so turning the
  * notifier back on doesn't need it re-entered. */
 export declare function removeAgentNotifier(config: AgentConfig): void;

package/dist/web/notifier-admin.js

@@ -4,7 +4,8 @@ import { describeNotifier } from '../core/http-notifier.js';
 import { sendTestSlackMessage } from '../core/http-notify-triggers/slack.js';
 import { sendTestWebhook } from '../core/http-notify-triggers/webhook.js';
 import { listDeliveries } from '../core/notifier-deliveries.js';
-import { NOTIFIER_SECRET_VARS, notifierConfigFromFile, readNotifierFile, removeNotifierFile, writeNotifierFile } from '../core/notifier-file.js';
+import { NOTIFIER_SECRET_VARS, NOTIFIER_SLACK_SIGNING_SECRET_VAR, notifierConfigFromFile, readNotifierFile, removeNotifierFile, writeNotifierFile } from '../core/notifier-file.js';
+import { listSlackChannels, slackAppManifest } from '../core/slack-interactions.js';
 import { setAgentEnvVar } from './env-admin.js';
 export function describeAgentNotifier(config, defaultWebhook) {
     const described = describeNotifier(config);
@@ -18,6 +19,15 @@ export function describeAgentNotifier(config, defaultWebhook) {
         publicUrl: process.env.LOOPENGINE_PUBLIC_URL ?? null,
         secretVars: NOTIFIER_SECRET_VARS,
         secretsSet,
+        slack: {
+            signingSecretVar: NOTIFIER_SLACK_SIGNING_SECRET_VAR,
+            signingSecretSet: env.get(NOTIFIER_SLACK_SIGNING_SECRET_VAR) !== undefined,
+            // Where the Slack app's Interactivity Request URL should point.
+            interactivityPath: `/hooks/slack/${encodeURIComponent(config.name)}`,
+            // The console swaps __INTERACTIVITY_URL__ for the link address +
+            // interactivityPath as you type.
+            manifestTemplate: slackAppManifest({ agentName: config.name, interactivityUrl: '__INTERACTIVITY_URL__' }),
+        },
         deliveries: listDeliveries(config.name),
     };
 }
@@ -29,6 +39,26 @@ export async function saveAgentNotifier(config, body) {
     if (typeof body.secret === 'string' && body.secret.trim()) {
         await setAgentEnvVar(config.name, NOTIFIER_SECRET_VARS[file.channel], body.secret.trim());
     }
+    if (file.channel === 'slack' && typeof body.signingSecret === 'string' && body.signingSecret.trim()) {
+        await setAgentEnvVar(config.name, NOTIFIER_SLACK_SIGNING_SECRET_VAR, body.signingSecret.trim());
+    }
+}
+/** The bot token and signing secret behind an agent's Slack notifier —
+ * from AgentConfig.httpNotifier when it's Slack, else from the agent's
+ * env (the console-saved ones). The signing secret always comes from the
+ * agent env. */
+export function slackCredentialsFor(config) {
+    const env = createAgentEnv(config.name, agentDirFor(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) };
+}
+/** Channels for the console's picker, with the token being typed in or,
+ * when none is given, the one already saved. */
+export async function listAgentSlackChannels(config, botToken) {
+    const token = botToken?.trim() || slackCredentialsFor(config).botToken;
+    if (!token)
+        throw new Error('Enter the bot token first');
+    return listSlackChannels(token);
 }
 /** Removes notifier.yml; the stored secret is left alone, so turning the
  * notifier back on doesn't need it re-entered. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopengine",
-  "version": "0.1.68",
+  "version": "0.1.69",
   "type": "module",
   "description": "Runtime for tool-using AI agents with a transparent ReAct loop.",
   "license": "MIT",
@@ -50,6 +50,8 @@
     "dist/core/notifier-deliveries.d.ts",
     "dist/core/approval-links.js",
     "dist/core/approval-links.d.ts",
+    "dist/core/slack-interactions.js",
+    "dist/core/slack-interactions.d.ts",
     "dist/core/session-store.js",
     "dist/core/session-store.d.ts",
     "dist/core/vector-index.js",