loopengine 0.1.67 → 0.1.69

package/README.md

@@ -171,11 +171,25 @@ export const config: AgentConfig = {
 }
 ```
 
-Or skip the code: in the console, **Permissions → Approvals** sets a
+Or skip the code: in the console, the Permissions tab's **Where approval
+requests and questions are sent** section sets a
 webhook, Slack or Lark target for one agent (saved to
 `agents/<name>/notifier.yml`, with its secret in the agent's own `.env`),
 sends a test, shows recent deliveries, and lists every decision still
-waiting with Approve/Deny buttons.
+waiting with Approve/Deny buttons. The tab warns you when an agent has
+`ask` rules but nobody would be told.
+
+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: 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

@@ -185,6 +185,7 @@ export type HttpNotifierConfig = {
     config: {
         webhookUrl: string;
         webhookSecret: string;
+        publicUrl?: string;
     };
     events: HttpNotifierEvent[];
 } | {
@@ -192,6 +193,8 @@ export type HttpNotifierConfig = {
     config: {
         botToken: string;
         channelId: string;
+        publicUrl?: string;
+        buttons?: boolean;
     };
     events: HttpNotifierEvent[];
 } | {
@@ -200,6 +203,8 @@ export type HttpNotifierConfig = {
         appId: string;
         appSecret: string;
         chatId: string;
+        publicUrl?: string;
+        buttons?: boolean;
     };
     events: HttpNotifierEvent[];
 } | {

package/dist/core/approval-links.d.ts

@@ -0,0 +1,16 @@
+export type DecisionKind = 'approval' | 'question';
+/** How long a link works: 7 days, or LOOPENGINE_LINK_TTL_HOURS. */
+export declare function decisionLinkTtlMs(): number;
+export declare function createDecisionToken(pendingId: string, kind: DecisionKind, nowMs?: number): string;
+/** The pendingId and kind a token names, or null for a malformed,
+ * tampered or expired one. */
+export declare function verifyDecisionToken(token: string, nowMs?: number): {
+    pendingId: string;
+    kind: DecisionKind;
+    expiresAt: number;
+} | null;
+export declare function decidePath(pendingId: string, kind: DecisionKind): string;
+/** Builds full decision links against `baseUrl` — undefined when there's
+ * no base URL to build them against. */
+export type DecideLinkMaker = (pendingId: string, kind: DecisionKind) => string | undefined;
+export declare function decideLinkMaker(baseUrl: string | undefined): DecideLinkMaker;

package/dist/core/approval-links.js

@@ -0,0 +1,76 @@
+// Decision links: a signed, expiring URL for one waiting approval or
+// question (/decide/<token>) that opens a small page where whoever has
+// the link can approve, deny or answer — no admin login, no app of your
+// own, no Slack interactivity setup. Every notifier that knows where this
+// server is reachable puts one in its message.
+//
+// The token only names the pendingId, its kind and an expiry, signed
+// with HMAC-SHA256. It's single-use by construction: once the decision
+// is made the pending item no longer exists, so the same link just shows
+// "already decided."
+//
+// The signing secret is LOOPENGINE_LINK_SECRET when set (required for a
+// deployment with more than one server, which must share it), otherwise
+// one generated on first use and kept in .checkpoints/link-secret next to
+// the paused turns it unlocks, so links keep working across restarts.
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** How long a link works: 7 days, or LOOPENGINE_LINK_TTL_HOURS. */
+export function decisionLinkTtlMs() {
+    const hours = Number(process.env.LOOPENGINE_LINK_TTL_HOURS);
+    return (Number.isFinite(hours) && hours > 0 ? hours : 24 * 7) * 3_600_000;
+}
+let generatedSecret;
+function linkSecret() {
+    if (process.env.LOOPENGINE_LINK_SECRET)
+        return process.env.LOOPENGINE_LINK_SECRET;
+    if (generatedSecret)
+        return generatedSecret;
+    const dir = join(process.cwd(), '.checkpoints');
+    const path = join(dir, 'link-secret');
+    if (existsSync(path)) {
+        generatedSecret = readFileSync(path, 'utf8').trim();
+    }
+    else {
+        generatedSecret = randomBytes(32).toString('hex');
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(path, generatedSecret + '\n', { mode: 0o600 });
+    }
+    return generatedSecret;
+}
+function sign(body) {
+    return createHmac('sha256', linkSecret()).update(body).digest('base64url');
+}
+export function createDecisionToken(pendingId, kind, nowMs = Date.now()) {
+    const body = Buffer.from(JSON.stringify({ p: pendingId, k: kind, exp: nowMs + decisionLinkTtlMs() })).toString('base64url');
+    return `${body}.${sign(body)}`;
+}
+/** The pendingId and kind a token names, or null for a malformed,
+ * tampered or expired one. */
+export function verifyDecisionToken(token, nowMs = Date.now()) {
+    const [body, signature] = token.split('.');
+    if (!body || !signature)
+        return null;
+    const expected = Buffer.from(sign(body));
+    const actual = Buffer.from(signature);
+    if (expected.length !== actual.length || !timingSafeEqual(expected, actual))
+        return null;
+    try {
+        const payload = JSON.parse(Buffer.from(body, 'base64url').toString('utf8'));
+        if (typeof payload.p !== 'string' || (payload.k !== 'approval' && payload.k !== 'question') || typeof payload.exp !== 'number')
+            return null;
+        if (nowMs > payload.exp)
+            return null;
+        return { pendingId: payload.p, kind: payload.k, expiresAt: payload.exp };
+    }
+    catch {
+        return null;
+    }
+}
+export function decidePath(pendingId, kind) {
+    return `/decide/${createDecisionToken(pendingId, kind)}`;
+}
+export function decideLinkMaker(baseUrl) {
+    return (pendingId, kind) => (baseUrl ? baseUrl.replace(/\/+$/, '') + decidePath(pendingId, kind) : undefined);
+}

package/dist/core/durable-approvals.d.ts

@@ -65,6 +65,10 @@ export interface CheckpointStore {
      * first — backs GET /agents/:name/pending. Reads without locking: a
      * snapshot for display, not something to act on without withCheckpoint. */
     listOpen(): Promise<TurnCheckpoint[]>;
+    /** The open checkpoint `pendingId` belongs to, read without locking —
+     * for showing a decision page, not for acting on it (use
+     * withCheckpoint for that). undefined once it's decided or unknown. */
+    get(pendingId: string): Promise<TurnCheckpoint | undefined>;
     close(): Promise<void>;
 }
 /** One JSON file per checkpoint under `<dir>/checkpoints/`, plus one
@@ -82,6 +86,7 @@ export declare class FileCheckpointStore implements CheckpointStore {
         checkpoint: TurnCheckpoint | undefined;
         result: T;
     }>): Promise<T>;
+    get(pendingId: string): Promise<TurnCheckpoint | undefined>;
     listOpen(): Promise<TurnCheckpoint[]>;
     close(): Promise<void>;
 }
@@ -106,6 +111,7 @@ export declare class RedisCheckpointStore implements CheckpointStore {
         checkpoint: TurnCheckpoint | undefined;
         result: T;
     }>): Promise<T>;
+    get(pendingId: string): Promise<TurnCheckpoint | undefined>;
     listOpen(): Promise<TurnCheckpoint[]>;
     close(): Promise<void>;
 }

package/dist/core/durable-approvals.js

@@ -72,6 +72,16 @@ export class FileCheckpointStore {
             return result;
         });
     }
+    async get(pendingId) {
+        const indexPath = this.indexPath(pendingId);
+        if (!existsSync(indexPath))
+            return undefined;
+        const checkpointPath = this.checkpointPath(readFileSync(indexPath, 'utf8'));
+        if (!existsSync(checkpointPath))
+            return undefined;
+        const checkpoint = JSON.parse(readFileSync(checkpointPath, 'utf8'));
+        return !checkpoint.closed && checkpoint.outstanding[pendingId] ? checkpoint : undefined;
+    }
     async listOpen() {
         const open = [];
         for (const name of readdirSync(this.checkpointsDir)) {
@@ -164,6 +174,16 @@ export class RedisCheckpointStore {
             return result;
         });
     }
+    async get(pendingId) {
+        const checkpointId = await this.redis.get(this.indexKey(pendingId));
+        if (!checkpointId)
+            return undefined;
+        const raw = await this.redis.get(this.checkpointKey(checkpointId));
+        if (!raw)
+            return undefined;
+        const checkpoint = JSON.parse(raw);
+        return !checkpoint.closed && checkpoint.outstanding[pendingId] ? checkpoint : undefined;
+    }
     async listOpen() {
         const open = [];
         let cursor = '0';

package/dist/core/http-notifier.js

@@ -84,11 +84,11 @@ function buildResolved(httpNotifier) {
     let resolved;
     switch (httpNotifier.channel) {
         case 'webhook': {
-            const { webhookUrl, webhookSecret } = httpNotifier.config;
+            const { webhookUrl, webhookSecret, publicUrl } = httpNotifier.config;
             // One shared instance for both concerns, same "it's channel-
             // specific, not concern-specific" reasoning every other channel's
             // own file already has — see WebhookNotifier's own doc comment.
-            const webhook = new WebhookNotifier({ webhookUrl, signingSecret: webhookSecret });
+            const webhook = new WebhookNotifier({ webhookUrl, signingSecret: webhookSecret, publicUrl });
             resolved = {
                 approver: events.has('approval') ? webhook : undefined,
                 questionHandler: events.has('question') ? webhook : undefined,
@@ -98,13 +98,13 @@ function buildResolved(httpNotifier) {
             break;
         }
         case 'slack': {
-            const { botToken, channelId } = httpNotifier.config;
+            const { botToken, channelId, publicUrl, buttons } = httpNotifier.config;
             // One shared instance for every concern this httpNotifier actually
             // covers — same "it's Slack-specific, not approval/question/
             // lifecycle-specific" reasoning SlackNotifier's own doc
             // comment works out; cheap to construct (holds two strings, does no
             // I/O itself) so there's no reason to build one per event kind.
-            const slack = new SlackNotifier({ botToken, channelId });
+            const slack = new SlackNotifier({ botToken, channelId, publicUrl, buttons });
             resolved = {
                 approver: events.has('approval') ? slack : undefined,
                 questionHandler: events.has('question') ? slack : undefined,
@@ -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/http-notify-triggers/slack.d.ts

@@ -3,10 +3,22 @@ import type { DurableQuestionHandler } from '../agent-config.js';
 export declare class SlackNotifier implements DurableApprover, DurableQuestionHandler {
     private readonly botToken;
     private readonly channelId;
+    private readonly publicUrl?;
+    private readonly buttons;
+    /** `publicUrl`: where this server is reachable (LOOPENGINE_PUBLIC_URL
+     * wins when set) — when known, each message links to a decision page
+     * (core/approval-links.ts) anyone in the channel can open. `buttons`:
+     * whether to add interactive Approve/Deny buttons, which only work with
+     * a Slack interactivity endpoint deployed (examples/notifier-handler/
+     * slack.ts); default true, false for a console-configured notifier,
+     * which relies on the link instead. */
     constructor(options: {
         botToken: string;
         channelId: 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/slack.js

@@ -24,12 +24,29 @@
 // it's Slack-specific (the bot token, the channel, the chat.postMessage
 // call shape).
 import { randomUUID } from 'node:crypto';
+import { decidePath } from '../approval-links.js';
+import { publicBaseUrl } from './webhook.js';
 export class SlackNotifier {
     botToken;
     channelId;
+    publicUrl;
+    buttons;
+    /** `publicUrl`: where this server is reachable (LOOPENGINE_PUBLIC_URL
+     * wins when set) — when known, each message links to a decision page
+     * (core/approval-links.ts) anyone in the channel can open. `buttons`:
+     * whether to add interactive Approve/Deny buttons, which only work with
+     * a Slack interactivity endpoint deployed (examples/notifier-handler/
+     * slack.ts); default true, false for a console-configured notifier,
+     * which relies on the link instead. */
     constructor(options) {
         this.botToken = options.botToken;
         this.channelId = options.channelId;
+        this.publicUrl = options.publicUrl;
+        this.buttons = options.buttons ?? true;
+    }
+    decideLine(pendingId, kind) {
+        const base = publicBaseUrl(this.publicUrl);
+        return base ? `\n<${base}${decidePath(pendingId, kind)}|${kind === 'approval' ? 'Open to approve or deny' : 'Open to answer'}>` : '';
     }
     requestDurableApproval(tool, args, scope, reason) {
         const pendingId = randomUUID();
@@ -38,16 +55,18 @@ export class SlackNotifier {
                 type: 'section',
                 text: {
                     type: 'mrkdwn',
-                    text: `*Approval requested*\n*tool:* ${tool}\n*args:* \`${JSON.stringify(args)}\`\n*scope:* ${scope.tenant}/${scope.environment}/${scope.agent}\n*reason:* ${reason}`,
+                    text: `*Approval requested*\n*tool:* ${tool}\n*args:* \`${JSON.stringify(args)}\`\n*scope:* ${scope.tenant}/${scope.environment}/${scope.agent}\n*reason:* ${reason}${this.decideLine(pendingId, 'approval')}`,
                 },
             },
-            {
-                type: 'actions',
-                elements: [
-                    { type: 'button', text: { type: 'plain_text', text: 'Approve' }, style: 'primary', action_id: 'approve', value: pendingId },
-                    { type: 'button', text: { type: 'plain_text', text: 'Deny' }, style: 'danger', action_id: 'deny', value: pendingId },
-                ],
-            },
+            ...(this.buttons
+                ? [{
+                        type: 'actions',
+                        elements: [
+                            { type: 'button', text: { type: 'plain_text', text: 'Approve' }, style: 'primary', action_id: 'approve', value: pendingId },
+                            { type: 'button', text: { type: 'plain_text', text: 'Deny' }, style: 'danger', action_id: 'deny', value: pendingId },
+                        ],
+                    }]
+                : []),
         ]);
         return { pendingId };
     }
@@ -60,8 +79,10 @@ export class SlackNotifier {
             action_id: 'answer_option',
         }));
         this.postMessage(`Question from ${agent}: ${question}`, [
-            { type: 'section', text: { type: 'mrkdwn', text: `*Question from ${agent}${sessionId ? ` (session ${sessionId})` : ''}:*\n${question}` } },
-            { type: 'actions', elements: [...optionButtons, { type: 'button', text: { type: 'plain_text', text: 'Other…' }, action_id: 'open_answer_modal', value: pendingId }] },
+            { type: 'section', text: { type: 'mrkdwn', text: `*Question from ${agent}${sessionId ? ` (session ${sessionId})` : ''}:*\n${question}${this.decideLine(pendingId, 'question')}` } },
+            ...(this.buttons
+                ? [{ type: 'actions', elements: [...optionButtons, { type: 'button', text: { type: 'plain_text', text: 'Other…' }, action_id: 'open_answer_modal', value: pendingId }] }]
+                : []),
         ]);
         return { pendingId };
     }

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

@@ -5,14 +5,22 @@ export interface DeliveryResult {
     status?: number;
     error?: string;
 }
+/** Where this server is reachable: LOOPENGINE_PUBLIC_URL (e.g.
+ * https://acme.loopengine.app) when set, read per call so a change takes
+ * effect without a restart, else `fallback` (a notifier.yml's own
+ * publicUrl, remembered from the console). undefined when neither is
+ * known, in which case payloads carry only relative paths. */
+export declare function publicBaseUrl(fallback?: string): string | undefined;
 export declare class WebhookNotifier implements DurableApprover, DurableQuestionHandler {
     private readonly webhookUrl;
     private readonly signingSecret;
     private readonly retryDelaysMs;
+    private readonly publicUrl?;
     constructor(options: {
         webhookUrl: string;
         signingSecret: string;
         retryDelaysMs?: number[];
+        publicUrl?: string;
     });
     requestDurableApproval(tool: string, args: Record<string, unknown>, scope: Scope, reason: string): {
         pendingId: string;

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

@@ -48,18 +48,24 @@
 // working unchanged.
 import { createHmac, randomUUID } from 'node:crypto';
 import { recordDelivery } from '../notifier-deliveries.js';
+import { decidePath } from '../approval-links.js';
 /** Waits before each retry after the first attempt — four tries in all,
  * spread over about 40 seconds. */
 const RETRY_DELAYS_MS = [2_000, 10_000, 30_000];
 function sign(body, secret) {
     return `sha256=${createHmac('sha256', secret).update(body).digest('hex')}`;
 }
-/** LOOPENGINE_PUBLIC_URL (e.g. https://acme.loopengine.app), read per
- * call so a change takes effect without a restart; undefined when unset,
- * in which case payloads carry only the relative path. */
-function publicUrl(path) {
-    const base = process.env.LOOPENGINE_PUBLIC_URL;
-    return base ? base.replace(/\/+$/, '') + path : undefined;
+/** Where this server is reachable: LOOPENGINE_PUBLIC_URL (e.g.
+ * https://acme.loopengine.app) when set, read per call so a change takes
+ * effect without a restart, else `fallback` (a notifier.yml's own
+ * publicUrl, remembered from the console). undefined when neither is
+ * known, in which case payloads carry only relative paths. */
+export function publicBaseUrl(fallback) {
+    const base = process.env.LOOPENGINE_PUBLIC_URL || fallback;
+    return base ? base.replace(/\/+$/, '') : undefined;
+}
+function absolute(base, path) {
+    return base ? base + path : undefined;
 }
 async function attemptOnce(url, body, headers) {
     try {
@@ -91,18 +97,24 @@ export class WebhookNotifier {
     webhookUrl;
     signingSecret;
     retryDelaysMs;
+    publicUrl;
     constructor(options) {
         this.webhookUrl = options.webhookUrl;
         this.signingSecret = options.signingSecret;
         this.retryDelaysMs = options.retryDelaysMs ?? RETRY_DELAYS_MS;
+        this.publicUrl = options.publicUrl;
     }
     requestDurableApproval(tool, args, scope, reason) {
         const pendingId = randomUUID();
         const requestedAt = new Date().toISOString();
         const resolvePath = `/pending-approvals/${pendingId}/resolve`;
+        const decide = decidePath(pendingId, 'approval');
+        const base = publicBaseUrl(this.publicUrl);
         const body = JSON.stringify({
             pendingId, tool, args, scope, reason, requestedAt,
-            kind: 'approval', agent: scope.agent, resolvePath, resolveUrl: publicUrl(resolvePath),
+            kind: 'approval', agent: scope.agent, resolvePath, resolveUrl: absolute(base, resolvePath),
+            // A signed link a person can open to decide, no login needed.
+            decidePath: decide, decideUrl: absolute(base, decide),
         });
         void deliver(this.webhookUrl, body, { 'X-Actauth-Signature': sign(body, this.signingSecret) }, { agent: scope.agent, kind: 'approval', pendingId }, this.retryDelaysMs);
         return { pendingId };
@@ -111,9 +123,12 @@ export class WebhookNotifier {
         const pendingId = randomUUID();
         const requestedAt = new Date().toISOString();
         const answerPath = `/pending-questions/${pendingId}/answer`;
+        const decide = decidePath(pendingId, 'question');
+        const base = publicBaseUrl(this.publicUrl);
         const body = JSON.stringify({
             pendingId, question, options, agent, sessionId, requestedAt,
-            kind: 'question', answerPath, answerUrl: publicUrl(answerPath),
+            kind: 'question', answerPath, answerUrl: absolute(base, answerPath),
+            decidePath: decide, decideUrl: absolute(base, decide),
         });
         void deliver(this.webhookUrl, body, { 'X-Askuser-Signature': sign(body, this.signingSecret) }, { agent, kind: 'question', pendingId }, this.retryDelaysMs);
         return { pendingId };

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

@@ -10,9 +10,17 @@ export interface NotifierFile {
     /** lark: app id and chat to post into. */
     appId?: string;
     chatId?: string;
+    /** Where this server is reachable, for the links in each message —
+     * remembered from the console's own address when saving.
+     * LOOPENGINE_PUBLIC_URL, when set, wins over it. */
+    publicUrl?: string;
 }
 /** 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

@@ -1,6 +1,6 @@
 // agents/<name>/notifier.yml — where an agent's "ask" approvals and
 // questions go when nobody is watching a live chat, set from the console
-// (Permissions → Approvals) instead of in code. Only consulted when the
+// (Permissions → "Where approval requests and questions are sent") instead of in code. Only consulted when the
 // agent's own AgentConfig.httpNotifier is unset; code always wins.
 //
 // The file holds only non-secret settings. The one secret each channel
@@ -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 {
@@ -38,6 +42,12 @@ export function validateNotifierFile(input) {
     }
     const str = (key) => (typeof raw[key] === 'string' && raw[key].trim() ? raw[key].trim() : undefined);
     const file = { channel, events: events };
+    const publicUrl = str('publicUrl');
+    if (publicUrl) {
+        if (!/^https?:\/\/[^/]+/.test(publicUrl))
+            throw new NotifierFileError('publicUrl must be an http(s) URL');
+        file.publicUrl = publicUrl.replace(/\/+$/, '');
+    }
     if (channel === 'webhook') {
         const url = str('url');
         if (!url || !/^https?:\/\//.test(url))
@@ -69,8 +79,8 @@ export function readNotifierFile(dir) {
 }
 export function writeNotifierFile(dir, input) {
     const file = validateNotifierFile(input);
-    const header = '# Where this agent sends "ask" approvals and questions when nobody is in a live chat.\n' +
-        `# Edited from the console (Permissions > Approvals). The secret lives in this agent's env as ${NOTIFIER_SECRET_VARS[file.channel]}.\n`;
+    const header = '# Where this agent sends approval requests and questions when it is called over HTTP.\n' +
+        `# Edited from the console (Permissions tab). The secret lives in this agent's env as ${NOTIFIER_SECRET_VARS[file.channel]}.\n`;
     writeFileSync(notifierFilePath(dir), header + stringifyYaml(file));
     return file;
 }
@@ -87,10 +97,21 @@ export function notifierConfigFromFile(file, env) {
         return { missingSecret: secretVar };
     switch (file.channel) {
         case 'webhook':
-            return { config: { channel: 'webhook', config: { webhookUrl: file.url, webhookSecret: secret }, events: file.events } };
+            return { config: { channel: 'webhook', config: { webhookUrl: file.url, webhookSecret: secret, publicUrl: file.publicUrl }, events: file.events } };
         case 'slack':
-            return { config: { channel: 'slack', config: { botToken: secret, channelId: file.channelId }, 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 } };
     }
 }