loopengine 0.1.66 → 0.1.68

package/README.md

@@ -171,6 +171,34 @@ export const config: AgentConfig = {
 }
 ```
 
+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. 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: paste a bot token,
+pick a channel, save; each approval arrives with an "Open to approve or
+deny" link.
+
+For a third-party app calling an agent over plain HTTP:
+
+1. `POST /agents/<name>/messages` → when a call needs approval, the reply
+   has `stopReason: "pending_approval"` and a `pending` list, each item
+   with its `pendingId` and `resolvePath`.
+2. The webhook carries the same `pendingId`, `resolvePath` (and a full
+   `resolveUrl` when `LOOPENGINE_PUBLIC_URL` is set), signed with
+   `X-Actauth-Signature`. Failed deliveries are retried.
+3. `POST <resolvePath>` with `{"decision":"approve"}` (or `"deny"`) runs
+   the tool, resumes the turn, and returns the agent's reply.
+   `GET /agents/<name>/pending` lists what's waiting, for apps that poll
+   instead of receiving webhooks.
+
 Reference implementations for the receiving side (verifying a Slack
 click, a webhook HMAC signature, a magic-link token) ship under
 `examples/notifier-handler/` for the four channels that need one. See

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[];
 } | {

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

@@ -31,6 +31,9 @@ export interface TurnCheckpoint {
      * and is what DurableApprover.requestDurableApproval handed out. */
     outstanding: Record<string, OutstandingItem>;
     closed: boolean;
+    /** When the turn paused. Optional only because checkpoints written
+     * before this field existed don't have it. */
+    createdAt?: string;
 }
 export interface CreateCheckpointInput {
     sessionId: string;
@@ -58,6 +61,14 @@ export interface CheckpointStore {
         checkpoint: TurnCheckpoint | undefined;
         result: T;
     }>): Promise<T>;
+    /** Every checkpoint still waiting on at least one decision, oldest
+     * 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
@@ -75,6 +86,8 @@ 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>;
 }
 /** Redis-backed store for multi-instance deployments. Unlike
@@ -98,6 +111,8 @@ 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>;
 }
 /** Same REDIS_URL-gated pattern as session-store.ts's own

package/dist/core/durable-approvals.js

@@ -10,10 +10,13 @@
 // does (see HUMAN_IN_THE_LOOP.md's own "request + raw resolve only"
 // division of labor).
 import { randomUUID } from 'node:crypto';
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { Redis } from 'ioredis';
 import { KeyedMutex } from './session-store.js';
+function sortOldestFirst(list) {
+    return list.sort((a, b) => (a.createdAt ?? '').localeCompare(b.createdAt ?? ''));
+}
 const fileMutex = new KeyedMutex();
 /** One JSON file per checkpoint under `<dir>/checkpoints/`, plus one
  * small pendingId -> checkpointId pointer file per outstanding item under
@@ -35,7 +38,7 @@ export class FileCheckpointStore {
         return path.join(this.indexDir, pendingId);
     }
     async create(input) {
-        const checkpoint = { id: randomUUID(), closed: false, ...input };
+        const checkpoint = { id: randomUUID(), closed: false, createdAt: new Date().toISOString(), ...input };
         writeFileSync(this.checkpointPath(checkpoint.id), JSON.stringify(checkpoint));
         for (const pendingId of Object.keys(checkpoint.outstanding)) {
             writeFileSync(this.indexPath(pendingId), checkpoint.id);
@@ -69,6 +72,32 @@ 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)) {
+            if (!name.endsWith('.json'))
+                continue;
+            try {
+                const checkpoint = JSON.parse(readFileSync(path.join(this.checkpointsDir, name), 'utf8'));
+                if (!checkpoint.closed && Object.keys(checkpoint.outstanding).length)
+                    open.push(checkpoint);
+            }
+            catch {
+                // A checkpoint mid-write or removed between readdir and read.
+            }
+        }
+        return sortOldestFirst(open);
+    }
     async close() { }
 }
 /** Redis-backed store for multi-instance deployments. Unlike
@@ -117,7 +146,7 @@ export class RedisCheckpointStore {
         }
     }
     async create(input) {
-        const checkpoint = { id: randomUUID(), closed: false, ...input };
+        const checkpoint = { id: randomUUID(), closed: false, createdAt: new Date().toISOString(), ...input };
         await this.redis.set(this.checkpointKey(checkpoint.id), JSON.stringify(checkpoint));
         for (const pendingId of Object.keys(checkpoint.outstanding)) {
             await this.redis.set(this.indexKey(pendingId), checkpoint.id);
@@ -145,6 +174,35 @@ 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';
+        do {
+            // checkpoint:<id> only — checkpoint-lock:/checkpoint-pending-index:
+            // keys use a hyphen, so this pattern never matches them.
+            const [next, keys] = await this.redis.scan(cursor, 'MATCH', 'checkpoint:*', 'COUNT', 200);
+            cursor = next;
+            for (const key of keys) {
+                const raw = await this.redis.get(key);
+                if (!raw)
+                    continue;
+                const checkpoint = JSON.parse(raw);
+                if (!checkpoint.closed && Object.keys(checkpoint.outstanding).length)
+                    open.push(checkpoint);
+            }
+        } while (cursor !== '0');
+        return sortOldestFirst(open);
+    }
     async close() {
         await this.redis.quit();
     }

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

@@ -1,10 +1,25 @@
 import { type Approver } from 'actauth';
-import type { AgentConfig, QuestionHandler } from './agent-config.js';
+import type { AgentConfig, HttpNotifierConfig, QuestionHandler } from './agent-config.js';
+import { type NotifierFile } from './notifier-file.js';
 interface ResolvedHttpNotifier {
     approver?: Approver;
     questionHandler?: QuestionHandler;
     onRunStart?: NonNullable<AgentConfig['onRunStart']>;
     onRunFinish?: NonNullable<AgentConfig['onRunFinish']>;
 }
+/** Where an agent's durable approvals/questions go, for the console:
+ * `code` (AgentConfig.httpNotifier), `file` (agents/<name>/notifier.yml),
+ * or `none`. A file whose secret isn't set yet is reported, not used. */
+export declare function describeNotifier(config: AgentConfig): {
+    source: 'code' | 'file' | 'none';
+    channel?: HttpNotifierConfig['channel'];
+    events?: string[];
+    file?: NotifierFile;
+    missingSecret?: string;
+    error?: string;
+};
+/** AgentConfig.httpNotifier when the agent sets one in code; otherwise
+ * its agents/<name>/notifier.yml (see core/notifier-file.ts), re-read on
+ * every call so a console edit applies to the very next turn. */
 export declare function resolveHttpNotifier(config: AgentConfig): ResolvedHttpNotifier;
 export {};

package/dist/core/http-notifier.js

@@ -4,6 +4,8 @@ import { LarkNotifier } from './http-notify-triggers/lark.js';
 import { EmailNotifier } from './http-notify-triggers/email.js';
 import { DatabaseApprover } from './http-notify-triggers/database.js';
 import { RedisQueueApprover } from './http-notify-triggers/redis.js';
+import { agentDirFor, createAgentEnv } from './agent-env.js';
+import { notifierConfigFromFile, readNotifierFile } from './notifier-file.js';
 const EMPTY = {};
 // Keyed by the AgentConfig object itself, not its httpNotifier field
 // alone — resolveHttpNotifier is called on every runAgent()/resumeAgent()
@@ -29,22 +31,64 @@ function formatChatLifecycleMessage(event, context) {
 function formatEmailLifecycleSubject(event, context) {
     return event === 'run_start' ? `${context.agent} started` : `${context.agent} finished`;
 }
+/** Where an agent's durable approvals/questions go, for the console:
+ * `code` (AgentConfig.httpNotifier), `file` (agents/<name>/notifier.yml),
+ * or `none`. A file whose secret isn't set yet is reported, not used. */
+export function describeNotifier(config) {
+    if (config.httpNotifier)
+        return { source: 'code', channel: config.httpNotifier.channel, events: [...config.httpNotifier.events] };
+    const dir = agentDirFor(config);
+    let file;
+    try {
+        file = readNotifierFile(dir);
+    }
+    catch (err) {
+        return { source: 'none', error: `notifier.yml is invalid: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    if (!file)
+        return { source: 'none' };
+    const { missingSecret } = notifierConfigFromFile(file, createAgentEnv(config.name, dir));
+    return { source: missingSecret ? 'none' : 'file', channel: file.channel, events: file.events, file, missingSecret };
+}
+/** AgentConfig.httpNotifier when the agent sets one in code; otherwise
+ * its agents/<name>/notifier.yml (see core/notifier-file.ts), re-read on
+ * every call so a console edit applies to the very next turn. */
 export function resolveHttpNotifier(config) {
     const httpNotifier = config.httpNotifier;
     if (!httpNotifier)
-        return EMPTY;
+        return resolveFromFile(config);
     const cached = cache.get(config);
     if (cached)
         return cached;
+    const resolved = buildResolved(httpNotifier);
+    cache.set(config, resolved);
+    return resolved;
+}
+function resolveFromFile(config) {
+    const dir = agentDirFor(config);
+    let file;
+    try {
+        file = readNotifierFile(dir);
+    }
+    catch (err) {
+        console.error(`[loopengine] ignoring agents/${config.name}/notifier.yml:`, err instanceof Error ? err.message : err);
+        return EMPTY;
+    }
+    if (!file)
+        return EMPTY;
+    const { config: httpNotifier } = notifierConfigFromFile(file, createAgentEnv(config.name, dir));
+    return httpNotifier ? buildResolved(httpNotifier) : EMPTY;
+}
+function buildResolved(httpNotifier) {
     const events = new Set(httpNotifier.events);
     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,
@@ -54,13 +98,13 @@ export function resolveHttpNotifier(config) {
             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,
@@ -111,6 +155,5 @@ export function resolveHttpNotifier(config) {
             break;
         }
     }
-    cache.set(config, resolved);
     return resolved;
 }

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;
     };
@@ -19,3 +31,12 @@ export declare class SlackNotifier implements DurableApprover, DurableQuestionHa
      * so nothing to attach buttons to. */
     postMessage(text: string, blocks?: unknown[]): void;
 }
+/** One plain chat.postMessage, awaited, reporting whether Slack accepted
+ * it — backs the console's "Send test" for a Slack notifier, where
+ * SlackNotifier.postMessage's fire-and-forget contract would hide the
+ * answer (a bad token, a channel the bot isn't in). */
+export declare function sendTestSlackMessage(botToken: string, channelId: string, text: string): Promise<{
+    ok: boolean;
+    status?: number;
+    error?: 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 };
     }
@@ -89,3 +110,21 @@ export class SlackNotifier {
         });
     }
 }
+/** One plain chat.postMessage, awaited, reporting whether Slack accepted
+ * it — backs the console's "Send test" for a Slack notifier, where
+ * SlackNotifier.postMessage's fire-and-forget contract would hide the
+ * answer (a bad token, a channel the bot isn't in). */
+export async function sendTestSlackMessage(botToken, channelId, text) {
+    try {
+        const res = await fetch('https://slack.com/api/chat.postMessage', {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${botToken}`, 'content-type': 'application/json; charset=utf-8' },
+            body: JSON.stringify({ channel: channelId, text }),
+        });
+        const body = (await res.json());
+        return body.ok ? { ok: true, status: res.status } : { ok: false, status: res.status, error: body.error ?? `HTTP ${res.status}` };
+    }
+    catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}

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

@@ -1,11 +1,26 @@
 import type { DurableApprover, Scope } from 'actauth';
 import type { DurableQuestionHandler } from '../agent-config.js';
+export interface DeliveryResult {
+    ok: boolean;
+    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;
@@ -13,15 +28,9 @@ export declare class WebhookNotifier implements DurableApprover, DurableQuestion
     notifyPendingQuestion(question: string, options: string[] | undefined, agent: string, sessionId: string | undefined): {
         pendingId: string;
     };
-    /** Shared by both methods above — the one place either used to
-     * independently build the same signed fetch() call. Not awaited by its
-     * own callers, same fire-and-forget contract each had on its own: both
-     * requestDurableApproval/notifyPendingQuestion return immediately, by
-     * contract (see DurableApprover/DurableQuestionHandler's own doc
-     * comments), so a delivery failure here has no synchronous way to
-     * surface to the caller — logged instead of thrown, since throwing
-     * would blow up a decision that has already, correctly, been recorded
-     * as pending. */
-    private post;
 }
 export declare function postLifecycleWebhook(webhookUrl: string, webhookSecret: string, event: 'run_start' | 'run_finish', context: Record<string, unknown>): void;
+/** One signed `{event: "test"}` POST (lifecycle signature header), no
+ * retries, awaited — backs the console's "Send test" button so an
+ * operator sees right away whether the receiver accepts it. */
+export declare function sendTestWebhook(webhookUrl: string, webhookSecret: string, agent: string): Promise<DeliveryResult>;