loopengine 0.0.21 → 0.1.3

package/dist/core/http-notifier.js

@@ -0,0 +1,116 @@
+import { WebhookNotifier, postLifecycleWebhook } from './http-notify-triggers/webhook.js';
+import { SlackNotifier } from './http-notify-triggers/slack.js';
+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';
+const EMPTY = {};
+// Keyed by the AgentConfig object itself, not its httpNotifier field
+// alone — resolveHttpNotifier is called on every runAgent()/resumeAgent()
+// call (see run-agent.ts's buildTurnContext), so without this a fresh
+// sender would be constructed per turn for no reason; a config object is
+// created once per agent module and reused for its whole process
+// lifetime, the same assumption discoverAgents' own memoized
+// createModelCall already relies on.
+const cache = new WeakMap();
+/** Chat channels (Slack/Lark) have no signed-payload equivalent to react
+ * to for a lifecycle event — nothing to resolve, so just a plain,
+ * human-readable announcement string. Shared between the two since the
+ * message itself doesn't need to be platform-specific, only how it's
+ * sent does. */
+function formatChatLifecycleMessage(event, context) {
+    if (event === 'run_start') {
+        const trigger = context.trigger === 'resolution' ? 'resumed' : 'started';
+        return `${context.agent} ${trigger}${context.sessionId ? ` (session ${context.sessionId})` : ''}`;
+    }
+    const stopReason = typeof context.stopReason === 'string' ? ` (${context.stopReason})` : '';
+    return `${context.agent} finished${stopReason}: ${context.text ?? ''}`;
+}
+function formatEmailLifecycleSubject(event, context) {
+    return event === 'run_start' ? `${context.agent} started` : `${context.agent} finished`;
+}
+export function resolveHttpNotifier(config) {
+    const httpNotifier = config.httpNotifier;
+    if (!httpNotifier)
+        return EMPTY;
+    const cached = cache.get(config);
+    if (cached)
+        return cached;
+    const events = new Set(httpNotifier.events);
+    let resolved;
+    switch (httpNotifier.channel) {
+        case 'webhook': {
+            const { webhookUrl, webhookSecret } = 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 });
+            resolved = {
+                approver: events.has('approval') ? webhook : undefined,
+                questionHandler: events.has('question') ? webhook : undefined,
+                onRunStart: events.has('run_start') ? (context) => postLifecycleWebhook(webhookUrl, webhookSecret, 'run_start', context) : undefined,
+                onRunFinish: events.has('run_finish') ? (context) => postLifecycleWebhook(webhookUrl, webhookSecret, 'run_finish', context) : undefined,
+            };
+            break;
+        }
+        case 'slack': {
+            const { botToken, channelId } = 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 });
+            resolved = {
+                approver: events.has('approval') ? slack : undefined,
+                questionHandler: events.has('question') ? slack : undefined,
+                onRunStart: events.has('run_start') ? (context) => slack.postMessage(formatChatLifecycleMessage('run_start', context)) : undefined,
+                onRunFinish: events.has('run_finish') ? (context) => slack.postMessage(formatChatLifecycleMessage('run_finish', context)) : undefined,
+            };
+            break;
+        }
+        case 'lark': {
+            const { appId, appSecret, chatId } = httpNotifier.config;
+            const lark = new LarkNotifier({ appId, appSecret, chatId });
+            resolved = {
+                approver: events.has('approval') ? lark : undefined,
+                questionHandler: events.has('question') ? lark : undefined,
+                onRunStart: events.has('run_start') ? (context) => lark.postMessage(formatChatLifecycleMessage('run_start', context)) : undefined,
+                onRunFinish: events.has('run_finish') ? (context) => lark.postMessage(formatChatLifecycleMessage('run_finish', context)) : undefined,
+            };
+            break;
+        }
+        case 'email': {
+            const { to, sendEmail, resolveBaseUrl, answerBaseUrl, signingSecret, linkTtlMs } = httpNotifier.config;
+            const email = new EmailNotifier({ to, sendEmail, resolveBaseUrl, answerBaseUrl, signingSecret, linkTtlMs });
+            resolved = {
+                approver: events.has('approval') ? email : undefined,
+                questionHandler: events.has('question') ? email : undefined,
+                onRunStart: events.has('run_start')
+                    ? (context) => email.sendAnnouncement(formatEmailLifecycleSubject('run_start', context), formatChatLifecycleMessage('run_start', context))
+                    : undefined,
+                onRunFinish: events.has('run_finish')
+                    ? (context) => email.sendAnnouncement(formatEmailLifecycleSubject('run_finish', context), formatChatLifecycleMessage('run_finish', context))
+                    : undefined,
+            };
+            break;
+        }
+        case 'database': {
+            // Approval-only by construction (AgentConfig.ApprovalOnlyHttpNotifierEvent) —
+            // no questionHandler/lifecycle sender exists for this channel at
+            // all, see DatabaseApprover's own doc comment for why.
+            resolved = { approver: events.has('approval') ? new DatabaseApprover(httpNotifier.config.repository) : undefined };
+            break;
+        }
+        case 'redis': {
+            resolved = {
+                approver: events.has('approval')
+                    ? new RedisQueueApprover({ redis: httpNotifier.config.redis, queueKey: httpNotifier.config.queueKey })
+                    : undefined,
+            };
+            break;
+        }
+    }
+    cache.set(config, resolved);
+    return resolved;
+}

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

@@ -0,0 +1,19 @@
+import type { DurableApprover, Scope } from 'actauth';
+import type { PendingApprovalRow, PendingApprovalsRepository } from '../agent-config.js';
+export declare class DatabaseApprover implements DurableApprover {
+    private readonly repository;
+    constructor(repository: PendingApprovalsRepository);
+    requestDurableApproval(tool: string, args: Record<string, unknown>, scope: Scope, reason: string): {
+        pendingId: string;
+    };
+}
+/** Illustrative stand-in for a real database — swap for your own
+ * Postgres/MySQL/SQLite/whatever client implementing the same insert()
+ * signature. Exists so this file (and AgentConfig.httpNotifier's
+ * `channel: 'database'`) is genuinely runnable/testable without standing
+ * up a real database first, the same reason actauth's own ConsoleApprover
+ * exists — not something meant for production use. */
+export declare class InMemoryPendingApprovalsRepository implements PendingApprovalsRepository {
+    readonly rows: PendingApprovalRow[];
+    insert(row: PendingApprovalRow): Promise<void>;
+}

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

@@ -0,0 +1,53 @@
+// A DurableApprover backed by a database row instead of a notification —
+// the "writing straight to a database" option AgentConfig.httpNotifier's
+// `channel: 'database'` constructs. Deliberately not a notification
+// channel at all: nothing gets told anything — a human finds this row by
+// querying it (a cron job, an admin dashboard) — so there's no
+// DurableQuestionHandler sibling or lifecycle sender to merge in the way
+// webhook/Slack/Lark/email have (see AgentConfig.ApprovalOnlyHttpNotifierEvent's
+// own doc comment).
+//
+// Deliberately driver-agnostic — no Postgres/MySQL/SQLite client is a
+// dependency here, so PendingApprovalsRepository (AgentConfig.ts) is the
+// seam: implement insert() against whatever real database/ORM you
+// already have (a single INSERT, a Prisma/Drizzle create call, anything),
+// and DatabaseApprover needs nothing else from it.
+//
+// Whatever eventually reads this table (a cron job, an admin dashboard
+// query) still has to end up calling POST
+// /pending-approvals/:pendingId/resolve to actually decide it — this
+// class, like WebhookApprover, only owns creating the pending record;
+// "what happens next" is the same checkpoint/resolve machinery
+// regardless of which DurableApprover produced the pendingId.
+import { randomUUID } from 'node:crypto';
+export class DatabaseApprover {
+    repository;
+    constructor(repository) {
+        this.repository = repository;
+    }
+    requestDurableApproval(tool, args, scope, reason) {
+        const pendingId = randomUUID();
+        const row = { pendingId, tool, args, scope, reason, requestedAt: new Date().toISOString() };
+        // Not awaited — same contract WebhookApprover follows (see its own
+        // doc comment): requestDurableApproval returns immediately, by
+        // design, so an insert failure here can only be logged, not thrown —
+        // the decision has already, correctly, been recorded as pending
+        // regardless of whether this write succeeds.
+        this.repository.insert(row).catch((err) => {
+            console.error(`[loopengine] DatabaseApprover: insert failed for pendingId '${pendingId}':`, err);
+        });
+        return { pendingId };
+    }
+}
+/** Illustrative stand-in for a real database — swap for your own
+ * Postgres/MySQL/SQLite/whatever client implementing the same insert()
+ * signature. Exists so this file (and AgentConfig.httpNotifier's
+ * `channel: 'database'`) is genuinely runnable/testable without standing
+ * up a real database first, the same reason actauth's own ConsoleApprover
+ * exists — not something meant for production use. */
+export class InMemoryPendingApprovalsRepository {
+    rows = [];
+    async insert(row) {
+        this.rows.push(row);
+    }
+}

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

@@ -0,0 +1,44 @@
+import type { DurableApprover, Scope } from 'actauth';
+import type { DurableQuestionHandler, SendEmail } from '../agent-config.js';
+export interface EmailLinkPayload {
+    pendingId: string;
+    /** Present for an approval link (`'approve' | 'deny'`) or a
+     * suggested-option question link (the option text itself, resolves on
+     * click, no form needed); absent for a question's "type your own
+     * answer" link (the receiving side renders a form instead). */
+    decision?: 'approve' | 'deny';
+    answer?: string;
+    exp: number;
+}
+/** Returns the decoded payload, or null for a missing/tampered/expired
+ * token — graceful, distinguishable failure, not a thrown exception for
+ * the merely-expired case. Exported for the receiving-side example (see
+ * this file's own header comment for why it imports this instead of
+ * reimplementing it). */
+export declare function verifyMagicLink(token: string, signingSecret: string): EmailLinkPayload | null;
+export declare class EmailNotifier implements DurableApprover, DurableQuestionHandler {
+    private readonly to;
+    private readonly sendEmail;
+    private readonly resolveBaseUrl;
+    private readonly answerBaseUrl;
+    private readonly signingSecret;
+    private readonly linkTtlMs;
+    constructor(options: {
+        to: string;
+        sendEmail: SendEmail;
+        resolveBaseUrl: string;
+        answerBaseUrl: string;
+        signingSecret: string;
+        linkTtlMs?: number;
+    });
+    requestDurableApproval(tool: string, args: Record<string, unknown>, scope: Scope, reason: string): {
+        pendingId: string;
+    };
+    notifyPendingQuestion(question: string, options: string[] | undefined, agent: string, sessionId: string | undefined): {
+        pendingId: string;
+    };
+    /** Public: core/http-notifier.ts's own onRunStart/onRunFinish lifecycle
+     * sender for `channel: 'email'` calls this directly — a plain
+     * announcement, no magic link, since there's nothing to resolve. */
+    sendAnnouncement(subject: string, text: string): void;
+}

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

@@ -0,0 +1,126 @@
+// The *sending* half of an email-backed DurableApprover/DurableQuestionHandler,
+// real, maintained core/ code so AgentConfig.httpNotifier
+// (core/http-notifier.ts) can construct one directly for `channel:
+// 'email'`. Takes a `sendEmail` function (AgentConfig.SendEmail) rather
+// than hardcoding one provider — real email needs an SMTP client or
+// provider SDK, a dependency this package deliberately doesn't carry; a
+// minimal Resend-backed one is in
+// examples/notifier-handler/email.ts's own createExampleResendSendEmail,
+// illustrative only.
+//
+// The *receiving* side — turning a clicked link (or submitted form) back
+// into a `POST /pending-approvals/:id/resolve`/`POST /pending-questions/:id/answer`
+// call — deliberately stays out of core: that's an HTTP endpoint only the
+// host can deploy. See examples/notifier-handler/email.ts's own
+// `handleEmailApprovalClick`/`handleEmailQuestionAnswerPage`/
+// `handleEmailQuestionAnswerSubmit` for that half — those import
+// `verifyMagicLink` from *this* file rather than reimplementing it, since
+// unlike Slack/Lark (where the platform itself signs the callback), email
+// has no such mechanism: this file's own `signMagicLink` and the
+// receiving side's verification have to agree on one exact algorithm, not
+// two copies that could drift.
+//
+// The one thing that makes email a genuinely different integration than
+// Slack/Lark, not just "a different send API": a clicked email link is a
+// plain browser GET request — there's no interactivity payload, no
+// signature header a chat platform would attach, nothing stopping a
+// copied or forwarded link from being replayed. `pendingId` alone isn't
+// enough for a link that might sit in an inbox for days — this is exactly
+// the "signed, expiring token per link, with real revocation... still
+// unbuilt" gap HUMAN_IN_THE_LOOP.md's own open questions list — so this
+// file builds one: a small HMAC-signed, expiring token embedded in the
+// link itself, verified before ever touching loopengine's own
+// resolve/answer routes.
+import { createHmac, randomUUID, timingSafeEqual } from 'node:crypto';
+function signMagicLink(payload, expiresInMs, signingSecret) {
+    const body = Buffer.from(JSON.stringify({ ...payload, exp: Date.now() + expiresInMs })).toString('base64url');
+    const signature = createHmac('sha256', signingSecret).update(body).digest('base64url');
+    return `${body}.${signature}`;
+}
+/** Returns the decoded payload, or null for a missing/tampered/expired
+ * token — graceful, distinguishable failure, not a thrown exception for
+ * the merely-expired case. Exported for the receiving-side example (see
+ * this file's own header comment for why it imports this instead of
+ * reimplementing it). */
+export function verifyMagicLink(token, signingSecret) {
+    const [body, signature] = token.split('.');
+    if (!body || !signature)
+        return null;
+    const expected = createHmac('sha256', signingSecret).update(body).digest('base64url');
+    const expectedBuf = Buffer.from(expected);
+    const actualBuf = Buffer.from(signature);
+    if (expectedBuf.length !== actualBuf.length || !timingSafeEqual(expectedBuf, actualBuf))
+        return null;
+    const payload = JSON.parse(Buffer.from(body, 'base64url').toString('utf8'));
+    if (Date.now() > payload.exp)
+        return null;
+    return payload;
+}
+/** Both the outbound email body here and the receiving side's own
+ * confirmation pages interpolate values that ultimately trace back to
+ * the model or a human (tool args, a reason, a resumed turn's own reply
+ * text) — escaped before ever reaching an HTML template, same as any
+ * other untrusted-input-into-HTML boundary. */
+function escapeHtml(s) {
+    return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+}
+export class EmailNotifier {
+    to;
+    sendEmail;
+    resolveBaseUrl; // e.g. https://yourapp.com/email/approvals — YOUR route, not loopengine's own address
+    answerBaseUrl; // e.g. https://yourapp.com/email/questions — YOUR route, not loopengine's own address
+    signingSecret;
+    linkTtlMs;
+    constructor(options) {
+        this.to = options.to;
+        this.sendEmail = options.sendEmail;
+        this.resolveBaseUrl = options.resolveBaseUrl;
+        this.answerBaseUrl = options.answerBaseUrl;
+        this.signingSecret = options.signingSecret;
+        this.linkTtlMs = options.linkTtlMs ?? 3 * 24 * 60 * 60_000; // 3 days — long enough for someone to actually check email, short enough that a leaked link doesn't stay live forever
+    }
+    requestDurableApproval(tool, args, scope, reason) {
+        const pendingId = randomUUID();
+        const approveLink = `${this.resolveBaseUrl}?token=${signMagicLink({ pendingId, decision: 'approve' }, this.linkTtlMs, this.signingSecret)}`;
+        const denyLink = `${this.resolveBaseUrl}?token=${signMagicLink({ pendingId, decision: 'deny' }, this.linkTtlMs, this.signingSecret)}`;
+        // Not awaited — requestDurableApproval returns immediately, by
+        // contract (see DurableApprover's own doc comment). Logged instead of
+        // thrown on failure.
+        this.sendEmail(this.to, `Approval requested: ${tool}`, `<p><b>Tool:</b> ${escapeHtml(tool)}</p>` +
+            `<p><b>Args:</b> ${escapeHtml(JSON.stringify(args))}</p>` +
+            `<p><b>Scope:</b> ${escapeHtml(`${scope.tenant}/${scope.environment}/${scope.agent}`)}</p>` +
+            `<p><b>Reason:</b> ${escapeHtml(reason)}</p>` +
+            `<p><a href="${approveLink}">Approve</a> &nbsp;|&nbsp; <a href="${denyLink}">Deny</a></p>` +
+            `<p style="color:#888;font-size:12px">This link expires in ${Math.round(this.linkTtlMs / 3_600_000)} hours.</p>`).catch((err) => {
+            console.error(`[loopengine] EmailNotifier: sendEmail failed for pendingId '${pendingId}':`, err);
+        });
+        return { pendingId };
+    }
+    notifyPendingQuestion(question, options, agent, sessionId) {
+        const pendingId = randomUUID();
+        const optionLinks = (options ?? [])
+            .map((option) => {
+            const token = signMagicLink({ pendingId, answer: option }, this.linkTtlMs, this.signingSecret);
+            return `<a href="${this.answerBaseUrl}?token=${token}">${escapeHtml(option)}</a>`;
+        })
+            .join(' &nbsp;|&nbsp; ');
+        const freeTextToken = signMagicLink({ pendingId }, this.linkTtlMs, this.signingSecret);
+        const freeTextLink = `${this.answerBaseUrl}?token=${freeTextToken}`;
+        this.sendEmail(this.to, `Question from ${agent}`, `<p>${escapeHtml(question)}</p>` +
+            (sessionId ? `<p style="color:#888;font-size:12px">Session: ${escapeHtml(sessionId)}</p>` : '') +
+            (optionLinks ? `<p>${optionLinks}</p>` : '') +
+            `<p><a href="${freeTextLink}">${optionLinks ? 'Or answer in your own words' : 'Answer'}</a></p>` +
+            `<p style="color:#888;font-size:12px">This link expires in ${Math.round(this.linkTtlMs / 3_600_000)} hours.</p>`).catch((err) => {
+            console.error(`[loopengine] EmailNotifier: sendEmail failed for pendingId '${pendingId}':`, err);
+        });
+        return { pendingId };
+    }
+    /** Public: core/http-notifier.ts's own onRunStart/onRunFinish lifecycle
+     * sender for `channel: 'email'` calls this directly — a plain
+     * announcement, no magic link, since there's nothing to resolve. */
+    sendAnnouncement(subject, text) {
+        this.sendEmail(this.to, subject, `<p>${escapeHtml(text)}</p>`).catch((err) => {
+            console.error('[loopengine] EmailNotifier: sendEmail failed for lifecycle announcement:', err);
+        });
+    }
+}

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

@@ -0,0 +1,28 @@
+import type { DurableApprover, Scope } from 'actauth';
+import type { DurableQuestionHandler } from '../agent-config.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
+ * receiving-side example); must match exactly. */
+export declare const LARK_ANSWER_FIELD_TAG = "answer_input";
+export declare class LarkNotifier implements DurableApprover, DurableQuestionHandler {
+    private readonly appId;
+    private readonly appSecret;
+    private readonly chatId;
+    constructor(options: {
+        appId: string;
+        appSecret: string;
+        chatId: string;
+    });
+    requestDurableApproval(tool: string, args: Record<string, unknown>, scope: Scope, reason: string): {
+        pendingId: string;
+    };
+    notifyPendingQuestion(question: string, options: string[] | undefined, agent: string, sessionId: string | undefined): {
+        pendingId: string;
+    };
+    /** Public, not private: core/http-notifier.ts's own onRunStart/onRunFinish
+     * lifecycle sender for `channel: 'lark'` calls this directly — a plain
+     * text announcement, no buttons, since there's nothing to resolve. */
+    postMessage(text: string): void;
+    private sendCard;
+}

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

@@ -0,0 +1,168 @@
+// The *sending* half of a Lark/Feishu-backed DurableApprover/DurableQuestionHandler,
+// real, maintained core/ code so AgentConfig.httpNotifier
+// (core/http-notifier.ts) can construct one directly for `channel:
+// 'lark'`, the same way it already does for `channel: 'slack'`
+// (./slack.ts's own SlackNotifier — read that file first, this one
+// mirrors its reasoning for why approval/question/lifecycle concerns
+// merge into one class rather than staying split).
+//
+// The *receiving* side — verifying a Lark card-callback payload really
+// came from your app, then dispatching approve/deny/answer back into
+// loopengine's own resolve/answer routes — deliberately stays out of
+// core: that's an HTTP endpoint only the host can deploy. See
+// examples/notifier-handler/lark.ts's own `handleLarkInteraction` for
+// that half.
+//
+// Confidence note, stated plainly rather than glossed over: Lark's Open
+// Platform API has had more than one card-callback convention over time
+// (a plain `verification_token` string check is the longest-standing,
+// most widely documented one — see the receiving-side example for where
+// that check actually happens). Verify which your app is configured for
+// at https://open.feishu.cn/document before relying on this in
+// production; the request shapes below (tenant_access_token, the
+// im/v1/messages call, the button value round-trip) are stable regardless
+// of which verification method you end up using on the receiving side.
+//
+// The free-text answer (for a question) is the one genuinely tricky
+// part, worth being honest about: Slack's own answer (a modal, opened via
+// a separate API call keyed off a one-time trigger_id) has no direct Lark
+// equivalent used here. This uses a "form" card (an `input` element
+// inside an `action`/`form` container, submitted as one callback with all
+// field values together) — lower confidence than the rest of this file:
+// Lark's card schema has changed across versions, so verify the exact
+// `tag`/field names below against https://open.feishu.cn/document for
+// your app's configured card version before relying on this. The other
+// real option — replying in-thread, captured via the
+// `im.message.receive_v1` event — needs your own durable
+// message_id -> pendingId mapping (an in-memory Map is NOT enough if
+// sending and receiving ever run in different processes), deliberately
+// not the approach used here.
+import { randomUUID } from 'node:crypto';
+/** 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
+ * receiving-side example); must match exactly. */
+export const LARK_ANSWER_FIELD_TAG = 'answer_input';
+let cachedToken;
+async function getTenantAccessToken(appId, appSecret) {
+    if (cachedToken && cachedToken.expiresAt > Date.now() + 30_000)
+        return cachedToken.token;
+    const res = await fetch('https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ app_id: appId, app_secret: appSecret }),
+    });
+    const body = (await res.json());
+    if (body.code !== 0)
+        throw new Error(`getTenantAccessToken failed: ${body.msg}`);
+    cachedToken = { token: body.tenant_access_token, expiresAt: Date.now() + body.expire * 1000 };
+    return cachedToken.token;
+}
+export class LarkNotifier {
+    appId;
+    appSecret;
+    chatId;
+    constructor(options) {
+        this.appId = options.appId;
+        this.appSecret = options.appSecret;
+        this.chatId = options.chatId;
+    }
+    requestDurableApproval(tool, args, scope, reason) {
+        const pendingId = randomUUID();
+        void (async () => {
+            try {
+                const token = await getTenantAccessToken(this.appId, this.appSecret);
+                const card = {
+                    config: { wide_screen_mode: true },
+                    header: { title: { tag: 'plain_text', content: 'Approval requested' } },
+                    elements: [
+                        {
+                            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}`,
+                            },
+                        },
+                        {
+                            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);
+            }
+            catch (err) {
+                console.error(`[loopengine] LarkNotifier: send message failed for pendingId '${pendingId}':`, err);
+            }
+        })();
+        return { pendingId };
+    }
+    notifyPendingQuestion(question, options, agent, sessionId) {
+        const pendingId = randomUUID();
+        const optionButtons = (options ?? []).map((option) => ({
+            tag: 'button',
+            text: { tag: 'plain_text', content: option },
+            value: { pendingId, answer: option },
+        }));
+        void (async () => {
+            try {
+                const token = await getTenantAccessToken(this.appId, this.appSecret);
+                const card = {
+                    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: 'action',
+                                    actions: [{ tag: 'button', text: { tag: 'plain_text', content: 'Send' }, type: 'primary', action_type: 'form_submit', value: { pendingId } }],
+                                },
+                            ],
+                        },
+                    ],
+                };
+                await this.sendCard(token, card, pendingId);
+            }
+            catch (err) {
+                console.error(`[loopengine] LarkNotifier: send message failed for pendingId '${pendingId}':`, err);
+            }
+        })();
+        return { pendingId };
+    }
+    /** Public, not private: core/http-notifier.ts's own onRunStart/onRunFinish
+     * lifecycle sender for `channel: 'lark'` calls this directly — a plain
+     * text announcement, no buttons, since there's nothing to resolve. */
+    postMessage(text) {
+        void (async () => {
+            try {
+                const token = await getTenantAccessToken(this.appId, this.appSecret);
+                const card = {
+                    config: { wide_screen_mode: true },
+                    elements: [{ tag: 'div', text: { tag: 'lark_md', content: text } }],
+                };
+                await this.sendCard(token, card, 'lifecycle');
+            }
+            catch (err) {
+                console.error('[loopengine] LarkNotifier: send message failed for lifecycle announcement:', err);
+            }
+        })();
+    }
+    async sendCard(token, card, pendingId) {
+        const res = await fetch('https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=chat_id', {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${token}`, 'content-type': 'application/json; charset=utf-8' },
+            body: JSON.stringify({ receive_id: this.chatId, msg_type: 'interactive', content: JSON.stringify(card) }),
+        });
+        const body = (await res.json());
+        if (body.code !== 0)
+            console.error(`[loopengine] LarkNotifier: send message failed for pendingId '${pendingId}':`, body.msg);
+    }
+}

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

@@ -0,0 +1,33 @@
+import type { Redis } from 'ioredis';
+import type { DurableApprover, Scope } from 'actauth';
+export interface QueuedApproval {
+    pendingId: string;
+    tool: string;
+    args: Record<string, unknown>;
+    scope: Scope;
+    reason: string;
+    requestedAt: string;
+}
+export interface RedisQueueApproverOptions {
+    redis: Redis;
+    /** Default 'durable-approvals:queue' — override if you're running more
+     * than one of these against the same Redis instance and want separate
+     * queues (e.g. one per agent, or per severity). */
+    queueKey?: string;
+}
+export declare class RedisQueueApprover implements DurableApprover {
+    private readonly redis;
+    private readonly queueKey;
+    constructor(options: RedisQueueApproverOptions);
+    requestDurableApproval(tool: string, args: Record<string, unknown>, scope: Scope, reason: string): {
+        pendingId: string;
+    };
+}
+/** Worker-side companion — drains the queue this approver pushes onto,
+ * one entry at a time, blocking (BLPOP) rather than polling. Illustrative
+ * only: a real worker would take each QueuedApproval here and do
+ * something with it (post to Slack, send an email, write a row somewhere
+ * an admin UI reads from) before the human eventually hits
+ * POST /pending-approvals/:pendingId/resolve — this function only gets
+ * you the queued entries themselves, not a notification channel. */
+export declare function consumePendingApprovals(redis: Redis, queueKey?: string): AsyncGenerator<QueuedApproval>;

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

@@ -0,0 +1,54 @@
+// A DurableApprover backed by a Redis list instead of a notification —
+// the "pushing to a queue" option AgentConfig.httpNotifier's `channel:
+// 'redis'` constructs. Uses `ioredis`, already a real dependency here
+// (core/session-store.ts's own RedisSessionStore), so no new dependency
+// to add. Approval-only, deliberately — see ./database.ts's own header
+// comment for why this isn't a "notification channel" with a
+// question-handler/lifecycle-sender sibling to merge in.
+//
+// Whatever drains the queue (consumePendingApprovals below, or your own
+// worker) still has to end up calling POST
+// /pending-approvals/:pendingId/resolve to actually decide it — this
+// class, like WebhookApprover, only owns creating the pending record
+// and one notification side effect; "what happens next" is the same
+// checkpoint/resolve machinery regardless of which DurableApprover
+// produced the pendingId.
+import { randomUUID } from 'node:crypto';
+export class RedisQueueApprover {
+    redis;
+    queueKey;
+    constructor(options) {
+        this.redis = options.redis;
+        this.queueKey = options.queueKey ?? 'durable-approvals:queue';
+    }
+    requestDurableApproval(tool, args, scope, reason) {
+        const pendingId = randomUUID();
+        const entry = { pendingId, tool, args, scope, reason, requestedAt: new Date().toISOString() };
+        // Not awaited — same contract WebhookApprover follows (see its own
+        // doc comment): requestDurableApproval returns immediately, by
+        // design, so a delivery failure here can only be logged, not thrown
+        // — the decision has already, correctly, been recorded as pending
+        // regardless of whether this push succeeds.
+        this.redis.rpush(this.queueKey, JSON.stringify(entry)).catch((err) => {
+            console.error(`[loopengine] RedisQueueApprover: rpush failed for pendingId '${pendingId}':`, err);
+        });
+        return { pendingId };
+    }
+}
+/** Worker-side companion — drains the queue this approver pushes onto,
+ * one entry at a time, blocking (BLPOP) rather than polling. Illustrative
+ * only: a real worker would take each QueuedApproval here and do
+ * something with it (post to Slack, send an email, write a row somewhere
+ * an admin UI reads from) before the human eventually hits
+ * POST /pending-approvals/:pendingId/resolve — this function only gets
+ * you the queued entries themselves, not a notification channel. */
+export async function* consumePendingApprovals(redis, queueKey = 'durable-approvals:queue') {
+    for (;;) {
+        // 0 = block forever. BLPOP's own reply is [key, value] | null (null
+        // only on a client-side timeout, which never happens here).
+        const result = await redis.blpop(queueKey, 0);
+        if (!result)
+            continue;
+        yield JSON.parse(result[1]);
+    }
+}