loopengine 0.1.66 → 0.1.67

package/README.md

@@ -171,6 +171,25 @@ export const config: AgentConfig = {
 }
 ```
 
+Or skip the code: in the console, **Permissions → Approvals** 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.
+
+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/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,10 @@ 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[]>;
     close(): Promise<void>;
 }
 /** One JSON file per checkpoint under `<dir>/checkpoints/`, plus one
@@ -75,6 +82,7 @@ export declare class FileCheckpointStore implements CheckpointStore {
         checkpoint: TurnCheckpoint | undefined;
         result: T;
     }>): Promise<T>;
+    listOpen(): Promise<TurnCheckpoint[]>;
     close(): Promise<void>;
 }
 /** Redis-backed store for multi-instance deployments. Unlike
@@ -98,6 +106,7 @@ export declare class RedisCheckpointStore implements CheckpointStore {
         checkpoint: TurnCheckpoint | undefined;
         result: T;
     }>): Promise<T>;
+    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,22 @@ export class FileCheckpointStore {
             return result;
         });
     }
+    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 +136,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 +164,25 @@ export class RedisCheckpointStore {
             return result;
         });
     }
+    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,13 +31,55 @@ 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) {
@@ -111,6 +155,5 @@ export function resolveHttpNotifier(config) {
             break;
         }
     }
-    cache.set(config, resolved);
     return resolved;
 }

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

@@ -19,3 +19,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

@@ -89,3 +89,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,18 @@
 import type { DurableApprover, Scope } from 'actauth';
 import type { DurableQuestionHandler } from '../agent-config.js';
+export interface DeliveryResult {
+    ok: boolean;
+    status?: number;
+    error?: string;
+}
 export declare class WebhookNotifier implements DurableApprover, DurableQuestionHandler {
     private readonly webhookUrl;
     private readonly signingSecret;
+    private readonly retryDelaysMs;
     constructor(options: {
         webhookUrl: string;
         signingSecret: string;
+        retryDelaysMs?: number[];
     });
     requestDurableApproval(tool: string, args: Record<string, unknown>, scope: Scope, reason: string): {
         pendingId: string;
@@ -13,15 +20,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>;

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

@@ -39,56 +39,94 @@
 // pending-approval/pending-question one hitting the same URL (see
 // examples/notifier-handler/webhook.ts's own `verifyWebhookNotifier` for
 // the receiving side of all three).
+// Delivery is retried (RETRY_DELAYS_MS, a non-2xx answer counts as a
+// failure), every attempt is recorded for the console's delivery log
+// (core/notifier-deliveries.ts), and each payload carries where to send
+// the decision back (`resolvePath`/`answerPath`, plus a full
+// `resolveUrl`/`answerUrl` when LOOPENGINE_PUBLIC_URL says where this
+// server is reachable) — all additive fields, so existing receivers keep
+// working unchanged.
 import { createHmac, randomUUID } from 'node:crypto';
+import { recordDelivery } from '../notifier-deliveries.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;
+}
+async function attemptOnce(url, body, headers) {
+    try {
+        const res = await fetch(url, { method: 'POST', headers: { 'content-type': 'application/json', ...headers }, body });
+        return res.ok ? { ok: true, status: res.status } : { ok: false, status: res.status, error: `HTTP ${res.status}` };
+    }
+    catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/** Sends one signed POST, retrying on a network error or non-2xx answer,
+ * and records every attempt. Resolves with the last attempt's result —
+ * callers that must return right away (a pending decision is already
+ * recorded either way) don't await it. */
+async function deliver(url, body, headers, meta, retryDelaysMs) {
+    let result = { ok: false };
+    for (let attempt = 1; attempt <= retryDelaysMs.length + 1; attempt++) {
+        if (attempt > 1)
+            await new Promise((resolve) => setTimeout(resolve, retryDelaysMs[attempt - 2]));
+        result = await attemptOnce(url, body, headers);
+        recordDelivery({ at: new Date().toISOString(), url, attempt, ...meta, ...result });
+        if (result.ok)
+            return result;
+    }
+    console.error(`[loopengine] webhook delivery to ${url} failed after ${retryDelaysMs.length + 1} attempts (${meta.kind}${meta.pendingId ? ` ${meta.pendingId}` : ''}): ${result.error}`);
+    return result;
+}
 export class WebhookNotifier {
     webhookUrl;
     signingSecret;
+    retryDelaysMs;
     constructor(options) {
         this.webhookUrl = options.webhookUrl;
         this.signingSecret = options.signingSecret;
+        this.retryDelaysMs = options.retryDelaysMs ?? RETRY_DELAYS_MS;
     }
     requestDurableApproval(tool, args, scope, reason) {
         const pendingId = randomUUID();
         const requestedAt = new Date().toISOString();
-        const body = JSON.stringify({ pendingId, tool, args, scope, reason, requestedAt });
-        this.post(body, 'X-Actauth-Signature', pendingId);
+        const resolvePath = `/pending-approvals/${pendingId}/resolve`;
+        const body = JSON.stringify({
+            pendingId, tool, args, scope, reason, requestedAt,
+            kind: 'approval', agent: scope.agent, resolvePath, resolveUrl: publicUrl(resolvePath),
+        });
+        void deliver(this.webhookUrl, body, { 'X-Actauth-Signature': sign(body, this.signingSecret) }, { agent: scope.agent, kind: 'approval', pendingId }, this.retryDelaysMs);
         return { pendingId };
     }
     notifyPendingQuestion(question, options, agent, sessionId) {
         const pendingId = randomUUID();
         const requestedAt = new Date().toISOString();
-        const body = JSON.stringify({ pendingId, question, options, agent, sessionId, requestedAt });
-        this.post(body, 'X-Askuser-Signature', pendingId);
-        return { pendingId };
-    }
-    /** 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. */
-    post(body, signatureHeader, pendingId) {
-        const signature = `sha256=${createHmac('sha256', this.signingSecret).update(body).digest('hex')}`;
-        fetch(this.webhookUrl, {
-            method: 'POST',
-            headers: { 'content-type': 'application/json', [signatureHeader]: signature },
-            body,
-        }).catch((err) => {
-            console.error(`[loopengine] WebhookNotifier: webhook delivery failed for pendingId '${pendingId}':`, err);
+        const answerPath = `/pending-questions/${pendingId}/answer`;
+        const body = JSON.stringify({
+            pendingId, question, options, agent, sessionId, requestedAt,
+            kind: 'question', answerPath, answerUrl: publicUrl(answerPath),
         });
+        void deliver(this.webhookUrl, body, { 'X-Askuser-Signature': sign(body, this.signingSecret) }, { agent, kind: 'question', pendingId }, this.retryDelaysMs);
+        return { pendingId };
     }
 }
 export function postLifecycleWebhook(webhookUrl, webhookSecret, event, context) {
     const payload = JSON.stringify({ event, ...context, occurredAt: new Date().toISOString() });
-    const signature = `sha256=${createHmac('sha256', webhookSecret).update(payload).digest('hex')}`;
-    fetch(webhookUrl, {
-        method: 'POST',
-        headers: { 'content-type': 'application/json', 'X-Lifecycle-Signature': signature },
-        body: payload,
-    }).catch((err) => {
-        console.error(`[loopengine] httpNotifier ${event} webhook delivery failed:`, err);
-    });
+    void deliver(webhookUrl, payload, { 'X-Lifecycle-Signature': sign(payload, webhookSecret) }, { agent: String(context.agent ?? ''), kind: event }, RETRY_DELAYS_MS);
+}
+/** 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 function sendTestWebhook(webhookUrl, webhookSecret, agent) {
+    const payload = JSON.stringify({ event: 'test', agent, occurredAt: new Date().toISOString() });
+    return deliver(webhookUrl, payload, { 'X-Lifecycle-Signature': sign(payload, webhookSecret) }, { agent, kind: 'test' }, []);
 }

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

@@ -0,0 +1,18 @@
+export type NotifierDeliveryKind = 'approval' | 'question' | 'run_start' | 'run_finish' | 'test';
+export interface NotifierDelivery {
+    at: string;
+    agent: string;
+    kind: NotifierDeliveryKind;
+    url: string;
+    pendingId?: string;
+    /** 1 for the first try, 2+ for retries. */
+    attempt: number;
+    ok: boolean;
+    /** The receiver's HTTP status, when it answered at all. */
+    status?: number;
+    error?: string;
+}
+export declare function recordDelivery(delivery: NotifierDelivery): void;
+/** Newest first. */
+export declare function listDeliveries(agent: string): NotifierDelivery[];
+export declare function clearDeliveries(): void;

package/dist/core/notifier-deliveries.js

@@ -0,0 +1,22 @@
+// A short, in-memory record of recent webhook deliveries per agent — what
+// the console's Approvals section shows so an operator can see whether a
+// notification actually reached the app on the other end (and why not).
+// Deliberately not persisted: it's a debugging aid that resets with the
+// process, not an audit log; the pending decision itself is what's
+// durable (core/durable-approvals.ts).
+const MAX_PER_AGENT = 50;
+const byAgent = new Map();
+export function recordDelivery(delivery) {
+    const list = byAgent.get(delivery.agent) ?? [];
+    list.unshift(delivery);
+    if (list.length > MAX_PER_AGENT)
+        list.length = MAX_PER_AGENT;
+    byAgent.set(delivery.agent, list);
+}
+/** Newest first. */
+export function listDeliveries(agent) {
+    return [...(byAgent.get(agent) ?? [])];
+}
+export function clearDeliveries() {
+    byAgent.clear();
+}

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

@@ -0,0 +1,31 @@
+import type { AgentEnv, HttpNotifierConfig, HttpNotifierEvent } from '#core/agent-config.js';
+export type NotifierFileChannel = 'webhook' | 'slack' | 'lark';
+export interface NotifierFile {
+    channel: NotifierFileChannel;
+    events: HttpNotifierEvent[];
+    /** webhook: where to POST. */
+    url?: string;
+    /** slack: channel to post into. */
+    channelId?: string;
+    /** lark: app id and chat to post into. */
+    appId?: string;
+    chatId?: string;
+}
+/** The env var each channel's secret is read from, per agent. */
+export declare const NOTIFIER_SECRET_VARS: Record<NotifierFileChannel, string>;
+export declare class NotifierFileError extends Error {
+}
+export declare function notifierFilePath(dir: string): string;
+/** Throws NotifierFileError naming the first problem. */
+export declare function validateNotifierFile(input: unknown): NotifierFile;
+/** undefined when the agent has no notifier.yml. */
+export declare function readNotifierFile(dir: string): NotifierFile | undefined;
+export declare function writeNotifierFile(dir: string, input: unknown): NotifierFile;
+export declare function removeNotifierFile(dir: string): void;
+/** The HttpNotifierConfig a notifier.yml describes, with its secret read
+ * from `env` — or which secret is missing, so nothing is sent unsigned
+ * or unauthenticated. */
+export declare function notifierConfigFromFile(file: NotifierFile, env: AgentEnv): {
+    config?: HttpNotifierConfig;
+    missingSecret?: string;
+};

package/dist/core/notifier-file.js

@@ -0,0 +1,96 @@
+// 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
+// agent's own AgentConfig.httpNotifier is unset; code always wins.
+//
+// The file holds only non-secret settings. The one secret each channel
+// needs (a webhook signing secret, a Slack bot token, a Lark app secret)
+// lives in the agent's own env (agents/<name>/.env by default, through
+// core/secret-store.ts) under a fixed name, so it's never written into a
+// file that might get committed.
+import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+/** The env var each channel's secret is read from, per agent. */
+export const NOTIFIER_SECRET_VARS = {
+    webhook: 'LOOPENGINE_NOTIFIER_WEBHOOK_SECRET',
+    slack: 'LOOPENGINE_NOTIFIER_SLACK_BOT_TOKEN',
+    lark: 'LOOPENGINE_NOTIFIER_LARK_APP_SECRET',
+};
+const CHANNELS = ['webhook', 'slack', 'lark'];
+const EVENTS = ['approval', 'question', 'run_start', 'run_finish'];
+export class NotifierFileError extends Error {
+}
+export function notifierFilePath(dir) {
+    return join(dir, 'notifier.yml');
+}
+/** Throws NotifierFileError naming the first problem. */
+export function validateNotifierFile(input) {
+    if (!input || typeof input !== 'object')
+        throw new NotifierFileError('notifier settings must be an object');
+    const raw = input;
+    const channel = raw.channel;
+    if (!CHANNELS.includes(channel))
+        throw new NotifierFileError(`channel must be one of: ${CHANNELS.join(', ')}`);
+    const events = Array.isArray(raw.events) ? raw.events : [];
+    if (!events.length || events.some((e) => !EVENTS.includes(e))) {
+        throw new NotifierFileError(`events must be a non-empty list of: ${EVENTS.join(', ')}`);
+    }
+    const str = (key) => (typeof raw[key] === 'string' && raw[key].trim() ? raw[key].trim() : undefined);
+    const file = { channel, events: events };
+    if (channel === 'webhook') {
+        const url = str('url');
+        if (!url || !/^https?:\/\//.test(url))
+            throw new NotifierFileError('url must be an http(s) URL');
+        file.url = url;
+    }
+    else if (channel === 'slack') {
+        const channelId = str('channelId');
+        if (!channelId)
+            throw new NotifierFileError('channelId is required for slack');
+        file.channelId = channelId;
+    }
+    else {
+        const appId = str('appId');
+        const chatId = str('chatId');
+        if (!appId || !chatId)
+            throw new NotifierFileError('appId and chatId are required for lark');
+        file.appId = appId;
+        file.chatId = chatId;
+    }
+    return file;
+}
+/** undefined when the agent has no notifier.yml. */
+export function readNotifierFile(dir) {
+    const path = notifierFilePath(dir);
+    if (!existsSync(path))
+        return undefined;
+    return validateNotifierFile(parseYaml(readFileSync(path, 'utf8')));
+}
+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`;
+    writeFileSync(notifierFilePath(dir), header + stringifyYaml(file));
+    return file;
+}
+export function removeNotifierFile(dir) {
+    rmSync(notifierFilePath(dir), { force: true });
+}
+/** The HttpNotifierConfig a notifier.yml describes, with its secret read
+ * from `env` — or which secret is missing, so nothing is sent unsigned
+ * or unauthenticated. */
+export function notifierConfigFromFile(file, env) {
+    const secretVar = NOTIFIER_SECRET_VARS[file.channel];
+    const secret = env.get(secretVar);
+    if (!secret)
+        return { missingSecret: secretVar };
+    switch (file.channel) {
+        case 'webhook':
+            return { config: { channel: 'webhook', config: { webhookUrl: file.url, webhookSecret: secret }, events: file.events } };
+        case 'slack':
+            return { config: { channel: 'slack', config: { botToken: secret, channelId: file.channelId }, events: file.events } };
+        case 'lark':
+            return { config: { channel: 'lark', config: { appId: file.appId, appSecret: secret, chatId: file.chatId }, events: file.events } };
+    }
+}

package/dist/index.d.ts

@@ -7,6 +7,11 @@ export { createAgentEnv, agentDirFor, envScopeOf, type EnvScope } from '#core/ag
 export { FileSecretStore, setSecretStore, getSecretStore, type SecretStore } from '#core/secret-store.js';
 export { signProxyIdentity, verifyProxyIdentity, TRUSTED_PROXY_IDENTITY_HEADER, type ProxyIdentity } from '#core/trusted-proxy.js';
 export { setUsageSink, recordUsage, type UsageEvent, type UsageSink } from '#core/usage.js';
+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 { sendTestWebhook } from '#core/http-notify-triggers/webhook.js';
+export { describeAgentNotifier, saveAgentNotifier, removeAgentNotifier, testAgentNotifier, listAgentPending, 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

@@ -9,6 +9,11 @@ export { createAgentEnv, agentDirFor, envScopeOf } from '#core/agent-env.js';
 export { FileSecretStore, setSecretStore, getSecretStore } from '#core/secret-store.js';
 export { signProxyIdentity, verifyProxyIdentity, TRUSTED_PROXY_IDENTITY_HEADER } from '#core/trusted-proxy.js';
 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 { sendTestWebhook } from '#core/http-notify-triggers/webhook.js';
+export { describeAgentNotifier, saveAgentNotifier, removeAgentNotifier, testAgentNotifier, listAgentPending } 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

@@ -889,7 +889,9 @@ ${consoleShellScript}
   // opened. ----
 
   function renderActauthTabPlaceholder() {
-    return '<section id="actauthSection"><div id="actauthContent"><p class="hint">Loading&hellip;</p></div></section>';
+    return '<div id="pendingContent"></div>' +
+      '<section id="actauthSection"><div id="actauthContent"><p class="hint">Loading&hellip;</p></div></section>' +
+      '<div id="approvalsContent"><p class="hint">Loading&hellip;</p></div>';
   }
 
   function renderActauthRuleRow(r) {
@@ -953,6 +955,198 @@ ${consoleShellScript}
         '</form></section>';
   }
 
+  // ---- Permissions → Approvals: where "ask" decisions go when nobody is
+  // in Chat (web/notifier-admin.ts behind GET/PUT/DELETE .../notifier),
+  // the decisions still waiting (GET .../pending), and recent webhook
+  // deliveries. Reloaded every time the tab opens, so the waiting list is
+  // current. ----
+
+  var NOTIFIER_EVENTS = [
+    ['approval', 'Approvals'], ['question', 'Questions'], ['run_finish', 'Run finished'], ['run_start', 'Run started']
+  ];
+
+  function approvalsContentEl() {
+    return detail.querySelector('#approvalsContent');
+  }
+
+  function renderPendingTable(pending) {
+    if (!pending.length) return '<p class="hint">Nothing is waiting for a decision.</p>';
+    return '<div class="le-table-wrap"><table><thead><tr><th>Waiting</th><th>Details</th><th>Session</th><th></th></tr></thead><tbody>' +
+      pending.map(function (p) {
+        var details = p.kind === 'question'
+          ? escapeHtml((p.args && p.args.question) || p.reason)
+          : '<code>' + escapeHtml(p.tool) + '</code> <span class="hint">' + escapeHtml(JSON.stringify(p.args)) + '</span>';
+        var actions = p.kind === 'question'
+          ? '<form class="pending-answer" data-id="' + escapeHtml(p.pendingId) + '" style="display:flex;gap:6px"><input name="answer" placeholder="Answer" required style="min-width:0"><button type="submit">Answer</button></form>'
+          : '<div style="display:flex;gap:6px"><button type="button" class="primary pending-decide" data-id="' + escapeHtml(p.pendingId) + '" data-decision="approve">Approve</button>' +
+            '<button type="button" class="pending-decide" data-id="' + escapeHtml(p.pendingId) + '" data-decision="deny">Deny</button></div>';
+        return '<tr><td><span class="le-pill ' + (p.kind === 'question' ? 'accent' : 'ask') + '">' + (p.kind === 'question' ? 'question' : 'approval') + '</span>' +
+          (p.createdAt ? '<div class="hint">' + escapeHtml(new Date(p.createdAt).toLocaleString()) + '</div>' : '') + '</td>' +
+          '<td>' + details + '</td><td><code>' + escapeHtml(p.sessionId) + '</code></td><td>' + actions + '</td></tr>';
+      }).join('') + '</tbody></table></div>';
+  }
+
+  function renderNotifierStatus(n) {
+    if (n.source === 'code') return 'Set in this agent&#39;s <code>index.ts</code> (<code>httpNotifier</code>, ' + escapeHtml(n.channel) + '). Edit it there; code always wins over the form below.';
+    if (n.source === 'file') return 'Sending to <strong>' + escapeHtml(n.channel) + '</strong> for: ' + escapeHtml((n.events || []).join(', ')) + '.';
+    if (n.missingSecret) return 'Saved, but not sending yet: set the secret below (<code>' + escapeHtml(n.missingSecret) + '</code>).';
+    if (n.source === 'default') return 'Using the project-wide default webhook (<code>LOOPENGINE_DEFAULT_WEBHOOK_URL</code>, ' + escapeHtml(n.defaultWebhookUrl) + '). Set one below to use a different target for this agent.';
+    return 'Not set up. A call that needs approval only reaches someone in Chat; set a webhook or Slack channel so apps calling this agent over HTTP can get approvals.';
+  }
+
+  function renderNotifierForm(n) {
+    var f = n.file || { channel: 'webhook', events: ['approval', 'question'] };
+    var events = f.events || [];
+    function field(channel, html) {
+      return '<div class="notifier-fields" data-channel="' + channel + '"' + (f.channel === channel ? '' : ' hidden') + '>' + html + '</div>';
+    }
+    function secretField(channel, label) {
+      var isSet = n.secretsSet && n.secretsSet[channel];
+      return '<label>' + label + ' <span class="hint">(' + (isSet ? 'set &mdash; leave blank to keep it' : 'not set') + '; stored in this agent&#39;s env as ' + escapeHtml(n.secretVars[channel]) + ')</span>' +
+        '<span style="display:flex;gap:6px"><input type="password" name="secret_' + channel + '" autocomplete="off" style="flex:1;min-width:0">' +
+        (channel === 'webhook' ? '<button type="button" class="notifier-generate">Generate</button>' : '') + '</span></label>';
+    }
+    return '<form class="add-source" id="notifierForm" style="max-width:560px">' +
+      '<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('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')) +
+      '<div class="body-field">Send<div style="display:flex;gap:14px;flex-wrap:wrap">' +
+        NOTIFIER_EVENTS.map(function (e) {
+          return '<label class="tool-picker-item" style="border:0;padding:0;justify-content:flex-start"><input type="checkbox" name="events" value="' + e[0] + '"' + (events.indexOf(e[0]) !== -1 ? ' checked' : '') + '> ' + e[1] + '</label>';
+        }).join('') + '</div></div>' +
+      '<div style="display:flex;gap:8px;flex-wrap:wrap"><button type="submit">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">Your app checks the <code>X-Actauth-Signature</code> header (HMAC-SHA256 of the body with the signing secret). Each payload carries <code>pendingId</code> and <code>resolvePath</code>; your app sends <code>{"decision":"approve"}</code> or <code>{"decision":"deny"}</code> there.' +
+        (n.publicUrl ? '' : ' Set <code>LOOPENGINE_PUBLIC_URL</code> to include a full <code>resolveUrl</code> too.') + '</p>' +
+      '</form>';
+  }
+
+  function renderDeliveries(list) {
+    if (!list.length) return '<p class="hint">No deliveries since the server started.</p>';
+    return '<div class="le-table-wrap"><table><thead><tr><th>When</th><th>What</th><th>Attempt</th><th>Result</th></tr></thead><tbody>' +
+      list.slice(0, 15).map(function (d) {
+        return '<tr><td>' + escapeHtml(new Date(d.at).toLocaleTimeString()) + '</td><td>' + escapeHtml(d.kind) + '</td><td>' + d.attempt + '</td>' +
+          '<td>' + (d.ok ? '<span class="le-pill good">' + (d.status || 'ok') + '</span>' : '<span class="le-pill bad">' + escapeHtml(d.error || 'failed') + '</span>') + '</td></tr>';
+      }).join('') + '</tbody></table></div>';
+  }
+
+  // Shown at the top of the tab, and only when something is waiting.
+  function renderPendingHtml(pending) {
+    if (!pending.length) return '';
+    return '<section><h3>Waiting for a decision (' + pending.length + ')</h3>' + renderPendingTable(pending) + '</section>';
+  }
+
+  function renderApprovalsHtml(n) {
+    return '<section><h3>Approvals when nobody is in Chat</h3><p class="muted" style="margin:0 0 12px">' + renderNotifierStatus(n) + '</p>' +
+        (n.error ? '<p class="error">' + escapeHtml(n.error) + '</p>' : '') +
+        (n.source === 'code' ? '' : renderNotifierForm(n)) + '</section>' +
+      '<section><h3>Recent deliveries</h3>' + renderDeliveries(n.deliveries || []) + '</section>';
+  }
+
+  function wirePendingHandlers(name) {
+    var content = detail.querySelector('#pendingContent');
+    if (!content) return;
+    var decideBtns = content.querySelectorAll('.pending-decide');
+    for (var i = 0; i < decideBtns.length; i++) {
+      decideBtns[i].addEventListener('click', function (ev) {
+        var btn = ev.currentTarget;
+        btn.disabled = true;
+        fetchJsonRetryOnce('/pending-approvals/' + encodeURIComponent(btn.dataset.id) + '/resolve', {
+          method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ decision: btn.dataset.decision }),
+        }).then(function () { loadApprovalsSection(name); });
+      });
+    }
+    var answerForms = content.querySelectorAll('.pending-answer');
+    for (var j = 0; j < answerForms.length; j++) {
+      answerForms[j].addEventListener('submit', function (ev) {
+        ev.preventDefault();
+        var form = ev.currentTarget;
+        fetchJsonRetryOnce('/pending-questions/' + encodeURIComponent(form.dataset.id) + '/answer', {
+          method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ answer: new FormData(form).get('answer') }),
+        }).then(function () { loadApprovalsSection(name); });
+      });
+    }
+  }
+
+  function wireApprovalsHandlers(name) {
+    var content = approvalsContentEl();
+    if (!content) return;
+    var form = content.querySelector('#notifierForm');
+    if (!form) return;
+    var result = content.querySelector('#notifierResult');
+    content.querySelector('#notifierChannel').addEventListener('change', function (ev) {
+      var groups = form.querySelectorAll('.notifier-fields');
+      for (var k = 0; k < groups.length; k++) groups[k].hidden = groups[k].dataset.channel !== ev.currentTarget.value;
+    });
+    var generate = form.querySelector('.notifier-generate');
+    if (generate) {
+      generate.addEventListener('click', function () {
+        var bytes = new Uint8Array(24);
+        crypto.getRandomValues(bytes);
+        var input = form.querySelector('input[name="secret_webhook"]');
+        input.type = 'text';
+        input.value = Array.prototype.map.call(bytes, function (b) { return ('0' + b.toString(16)).slice(-2); }).join('');
+        result.textContent = 'Copy this secret into your app before saving; it is not shown again.';
+      });
+    }
+    form.addEventListener('submit', function (ev) {
+      ev.preventDefault();
+      var data = new FormData(form);
+      var channel = data.get('channel');
+      var body = { channel: channel, events: data.getAll('events'), url: data.get('url'), channelId: data.get('channelId'), appId: data.get('appId'), chatId: data.get('chatId') };
+      var secret = data.get('secret_' + channel);
+      if (secret) body.secret = secret;
+      result.textContent = 'Saving…';
+      fetchJsonRetryOnce('/agents/' + encodeURIComponent(name) + '/notifier', {
+        method: 'PUT', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body),
+      }).then(function (r) {
+        if (!r.ok) { result.textContent = r.body.error || 'Could not save'; return; }
+        loadApprovalsSection(name, 'Saved.');
+      });
+    });
+    content.querySelector('#notifierTestBtn').addEventListener('click', function () {
+      result.textContent = 'Sending…';
+      fetchJsonRetryOnce('/agents/' + encodeURIComponent(name) + '/notifier/test', { method: 'POST' }).then(function (r) {
+        var t = r.body;
+        loadApprovalsSection(name, t.ok ? 'Test delivered (' + (t.status || 'ok') + ').' : 'Test failed: ' + (t.error || 'unknown error'));
+      });
+    });
+    var removeBtn = content.querySelector('#notifierRemoveBtn');
+    if (removeBtn) {
+      removeBtn.addEventListener('click', function () {
+        if (removeBtn.dataset.confirming !== '1') { removeBtn.dataset.confirming = '1'; removeBtn.textContent = 'Click again to remove'; return; }
+        fetchJsonRetryOnce('/agents/' + encodeURIComponent(name) + '/notifier', { method: 'DELETE' }).then(function () { loadApprovalsSection(name, 'Removed.'); });
+      });
+    }
+  }
+
+  function loadApprovalsSection(name, message) {
+    var content = approvalsContentEl();
+    if (!content) return;
+    Promise.all([
+      fetchJsonRetryOnce('/agents/' + encodeURIComponent(name) + '/notifier'),
+      fetchJsonRetryOnce('/agents/' + encodeURIComponent(name) + '/pending'),
+    ]).then(function (results) {
+      if (currentName !== name) return;
+      if (!results[0].ok) throw new Error(results[0].body.error || 'request failed');
+      content.innerHTML = renderApprovalsHtml(results[0].body);
+      wireApprovalsHandlers(name);
+      var pendingEl = detail.querySelector('#pendingContent');
+      if (pendingEl) {
+        pendingEl.innerHTML = renderPendingHtml((results[1].ok && results[1].body.pending) || []);
+        wirePendingHandlers(name);
+      }
+      if (message) { var r = content.querySelector('#notifierResult'); if (r) r.textContent = message; }
+    }).catch(function (err) {
+      if (currentName !== name) return;
+      content.innerHTML = '<p class="error">Could not load approvals: ' + escapeHtml(err.message) + '</p>';
+    });
+  }
+
   function actauthContentEl() {
     return detail.querySelector('#actauthContent');
   }
@@ -2448,6 +2642,7 @@ ${consoleShellScript}
     if (tab === 'actauth' && actauthLoadedFor !== currentName) {
       loadActauthTab(currentName);
     }
+    if (tab === 'actauth') loadApprovalsSection(currentName);
     if (tab === 'env' && envLoadedFor !== currentName) {
       loadEnvTab(currentName);
     }
@@ -2609,7 +2804,9 @@ ${consoleShellScript}
   currentTab = CONFIG_TABS.indexOf(initialParams.get('tab')) === -1 ? 'overview' : initialParams.get('tab');
   leShell.ready.then(function (agents) {
     if (!agents.length) {
-      empty.innerHTML = 'No agents yet. <a href="/agents?new=1">Create one</a> or add a folder under agents/.';
+      empty.innerHTML = leShell.loadError()
+        ? 'Could not load agents: ' + escapeHtml(leShell.loadError()) + '. Reload the page to try again.'
+        : 'No agents yet. <a href="/agents?new=1">Create one</a> or add a folder under agents/.';
       return;
     }
     var requested = initialParams.get('agent');

package/dist/web/console-shell.js

@@ -98,15 +98,23 @@ export const consoleShellScript = `<script>
     });
   }
 
-  var ready = fetch('/agents')
-    .then(function (r) { return r.json(); })
+  var loadError = null;
+  var ready = fetch('/agents', { headers: { accept: 'application/json' } })
+    .then(function (r) {
+      if (!r.ok) throw new Error(r.status === 401 ? 'sign-in required (HTTP 401)' : 'HTTP ' + r.status);
+      return r.json();
+    })
     .then(function (data) {
       agents = data.agents || [];
       renderList();
       loadToSet();
       return agents;
     })
-    .catch(function () { return []; });
+    .catch(function (err) {
+      loadError = err.message;
+      if (list) list.innerHTML = '<li class="le-agent-item"><span></span><span class="le-meta">Could not load agents: ' + esc(err.message) + '</span><span></span></li>';
+      return [];
+    });
 
   // opts: { name, prompt, chips: [{ text, mono }], tab, counts: { tools, skills, abilities, actauth } }
   function renderHead(opts) {
@@ -160,6 +168,6 @@ export const consoleShellScript = `<script>
     if (app.classList.contains('nav-open') && !ev.target.closest('.le-sidebar')) app.classList.remove('nav-open');
   });
 
-  window.leShell = { ready: ready, renderHead: renderHead, setTab: setTab, setActive: setActive, esc: esc, tabHref: tabHref, envCountHtml: envCountHtml, setCount: setCount };
+  window.leShell = { loadError: function () { return loadError; }, ready: ready, renderHead: renderHead, setTab: setTab, setActive: setActive, esc: esc, tabHref: tabHref, envCountHtml: envCountHtml, setCount: setCount };
 })();
 </script>`;

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

@@ -0,0 +1,61 @@
+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';
+/** 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. */
+export interface DefaultWebhook {
+    webhookUrl: string;
+    webhookSecret: string;
+}
+export declare function describeAgentNotifier(config: AgentConfig, defaultWebhook?: DefaultWebhook): {
+    source: string;
+    defaultWebhookUrl: string | null;
+    publicUrl: string | null;
+    secretVars: Record<NotifierFileChannel, string>;
+    secretsSet: {
+        [k: string]: boolean;
+    };
+    deliveries: import("../core/notifier-deliveries.js").NotifierDelivery[];
+    channel?: import("../core/agent-config.js").HttpNotifierConfig["channel"];
+    events?: string[];
+    file?: import("../core/notifier-file.js").NotifierFile;
+    missingSecret?: string;
+    error?: string;
+};
+/** Writes agents/<name>/notifier.yml from the console form and, when the
+ * 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>;
+/** 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;
+/** Sends a test through whichever notifier applies to this agent —
+ * webhook or Slack; reports what the receiver answered. */
+export declare function testAgentNotifier(config: AgentConfig, defaultWebhook?: DefaultWebhook): Promise<DeliveryResult & {
+    channel?: string;
+}>;
+/** Every decision still waiting for this agent, oldest first, each with
+ * where to send the answer. */
+export declare function listAgentPending(store: CheckpointStore, agentName: string): Promise<({
+    answerPath: string;
+    pendingId: string;
+    kind: "approval" | "question";
+    tool: string;
+    args: Record<string, unknown>;
+    reason: string;
+    sessionId: string;
+    tenant: string;
+    createdAt: string | null;
+} | {
+    resolvePath: string;
+    pendingId: string;
+    kind: "approval" | "question";
+    tool: string;
+    args: Record<string, unknown>;
+    reason: string;
+    sessionId: string;
+    tenant: string;
+    createdAt: string | null;
+})[]>;

package/dist/web/notifier-admin.js

@@ -0,0 +1,88 @@
+import { agentDirFor, createAgentEnv } from '../core/agent-env.js';
+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 { setAgentEnvVar } from './env-admin.js';
+export function describeAgentNotifier(config, defaultWebhook) {
+    const described = describeNotifier(config);
+    const env = createAgentEnv(config.name, agentDirFor(config));
+    const secretsSet = Object.fromEntries(Object.keys(NOTIFIER_SECRET_VARS).map((channel) => [channel, env.get(NOTIFIER_SECRET_VARS[channel]) !== undefined]));
+    const source = described.source === 'none' && defaultWebhook ? 'default' : described.source;
+    return {
+        ...described,
+        source,
+        defaultWebhookUrl: defaultWebhook?.webhookUrl ?? null,
+        publicUrl: process.env.LOOPENGINE_PUBLIC_URL ?? null,
+        secretVars: NOTIFIER_SECRET_VARS,
+        secretsSet,
+        deliveries: listDeliveries(config.name),
+    };
+}
+/** Writes agents/<name>/notifier.yml from the console form and, when the
+ * form includes one, the channel's secret into the agent's own env.
+ * Throws NotifierFileError for an invalid form. */
+export async function saveAgentNotifier(config, body) {
+    const file = writeNotifierFile(agentDirFor(config), body);
+    if (typeof body.secret === 'string' && body.secret.trim()) {
+        await setAgentEnvVar(config.name, NOTIFIER_SECRET_VARS[file.channel], body.secret.trim());
+    }
+}
+/** Removes notifier.yml; the stored secret is left alone, so turning the
+ * notifier back on doesn't need it re-entered. */
+export function removeAgentNotifier(config) {
+    removeNotifierFile(agentDirFor(config));
+}
+/** Sends a test through whichever notifier applies to this agent —
+ * webhook or Slack; reports what the receiver answered. */
+export async function testAgentNotifier(config, defaultWebhook) {
+    let target = config.httpNotifier;
+    if (!target) {
+        const dir = agentDirFor(config);
+        const file = readNotifierFile(dir);
+        if (file) {
+            const { config: fromFile, missingSecret } = notifierConfigFromFile(file, createAgentEnv(config.name, dir));
+            if (!fromFile)
+                return { ok: false, channel: file.channel, error: `${missingSecret} is not set for this agent` };
+            target = fromFile;
+        }
+    }
+    if (!target && defaultWebhook) {
+        return { channel: 'webhook', ...(await sendTestWebhook(defaultWebhook.webhookUrl, defaultWebhook.webhookSecret, config.name)) };
+    }
+    if (!target)
+        return { ok: false, error: 'This agent has no notifier set up' };
+    if (target.channel === 'webhook') {
+        return { channel: 'webhook', ...(await sendTestWebhook(target.config.webhookUrl, target.config.webhookSecret, config.name)) };
+    }
+    if (target.channel === 'slack') {
+        return { channel: 'slack', ...(await sendTestSlackMessage(target.config.botToken, target.config.channelId, `Test from LoopEngine: approvals for ${config.name} will be posted here.`)) };
+    }
+    return { ok: false, channel: target.channel, error: `Send test isn't supported for ${target.channel} yet` };
+}
+/** Every decision still waiting for this agent, oldest first, each with
+ * where to send the answer. */
+export async function listAgentPending(store, agentName) {
+    const open = await store.listOpen();
+    const pending = [];
+    for (const checkpoint of open) {
+        if (checkpoint.agent !== agentName)
+            continue;
+        for (const [pendingId, item] of Object.entries(checkpoint.outstanding)) {
+            const kind = item.kind ?? 'approval';
+            pending.push({
+                pendingId,
+                kind,
+                tool: item.tool,
+                args: item.args,
+                reason: item.reason,
+                sessionId: checkpoint.sessionId,
+                tenant: checkpoint.tenant,
+                createdAt: checkpoint.createdAt ?? null,
+                ...(kind === 'question' ? { answerPath: `/pending-questions/${pendingId}/answer` } : { resolvePath: `/pending-approvals/${pendingId}/resolve` }),
+            });
+        }
+    }
+    return pending;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopengine",
-  "version": "0.1.66",
+  "version": "0.1.67",
   "type": "module",
   "description": "Runtime for tool-using AI agents with a transparent ReAct loop.",
   "license": "MIT",
@@ -44,6 +44,10 @@
     "dist/core/trusted-proxy.d.ts",
     "dist/core/usage.js",
     "dist/core/usage.d.ts",
+    "dist/core/notifier-file.js",
+    "dist/core/notifier-file.d.ts",
+    "dist/core/notifier-deliveries.js",
+    "dist/core/notifier-deliveries.d.ts",
     "dist/core/session-store.js",
     "dist/core/session-store.d.ts",
     "dist/core/vector-index.js",