loopengine 0.0.20 → 0.1.2

package/dist/core/budget.d.ts

@@ -0,0 +1,42 @@
+export interface Message {
+    role: string;
+    content: string;
+}
+export type CheckAction = 'ok' | 'nudge' | 'over_hard_limit';
+export interface CheckResult {
+    action: CheckAction;
+    usedTokens: number;
+    budgetTokens: number;
+    ratio: number;
+    /** Present only when action is 'nudge' — the host decides whether and
+     * how to inject it. */
+    nudge?: Message;
+}
+/** ~4 chars/token — a common rough heuristic, good enough for a budget
+ * gate rather than exact accounting. Same heuristic used across the
+ * sibling ActAuth/SkillGarden projects for consistency. */
+export declare function estimateTokens(text: string): number;
+export interface BudgetTrackerOptions {
+    budgetTokens: number;
+    /** Fraction of budget that triggers a nudge. Default 0.7. Also the
+     * recovery target compaction.ts's own Compactor uses — the two are
+     * constructed with the same threshold so a caller's "start wrapping
+     * up" and "how far compaction tries to shrink" agree, not two
+     * independently-configured numbers that could drift apart. */
+    softThreshold?: number;
+    /** Fraction of budget that requires recovery. Default 0.92. */
+    hardThreshold?: number;
+}
+/** Tracks budget usage over a generic message array — read-only, never
+ * mutates or recovers. See compaction.ts's Compactor for what a caller
+ * does once this reports over_hard_limit. */
+export declare class BudgetTracker {
+    readonly budgetTokens: number;
+    readonly softThreshold: number;
+    private readonly hardThreshold;
+    constructor(options: BudgetTrackerOptions);
+    estimateUsage(messages: Message[]): number;
+    /** Returns a nudge message for the host to inject if usage has crossed
+     * the soft threshold but not yet the hard one. */
+    check(messages: Message[]): CheckResult;
+}

package/dist/core/budget.js

@@ -0,0 +1,39 @@
+/** ~4 chars/token — a common rough heuristic, good enough for a budget
+ * gate rather than exact accounting. Same heuristic used across the
+ * sibling ActAuth/SkillGarden projects for consistency. */
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+const NUDGE_MESSAGE = {
+    role: 'system',
+    content: 'The conversation is approaching its context budget. Wrap up the current step concisely.',
+};
+/** Tracks budget usage over a generic message array — read-only, never
+ * mutates or recovers. See compaction.ts's Compactor for what a caller
+ * does once this reports over_hard_limit. */
+export class BudgetTracker {
+    budgetTokens;
+    softThreshold;
+    hardThreshold;
+    constructor(options) {
+        this.budgetTokens = options.budgetTokens;
+        this.softThreshold = options.softThreshold ?? 0.7;
+        this.hardThreshold = options.hardThreshold ?? 0.92;
+    }
+    estimateUsage(messages) {
+        return messages.reduce((sum, m) => sum + estimateTokens(`${m.role}: ${m.content}`), 0);
+    }
+    /** Returns a nudge message for the host to inject if usage has crossed
+     * the soft threshold but not yet the hard one. */
+    check(messages) {
+        const usedTokens = this.estimateUsage(messages);
+        const ratio = usedTokens / this.budgetTokens;
+        if (ratio >= this.hardThreshold) {
+            return { action: 'over_hard_limit', usedTokens, budgetTokens: this.budgetTokens, ratio };
+        }
+        if (ratio >= this.softThreshold) {
+            return { action: 'nudge', usedTokens, budgetTokens: this.budgetTokens, ratio, nudge: NUDGE_MESSAGE };
+        }
+        return { action: 'ok', usedTokens, budgetTokens: this.budgetTokens, ratio };
+    }
+}

package/dist/core/compaction.d.ts

@@ -0,0 +1,43 @@
+import { type Message } from './budget.js';
+export interface Summarizer {
+    summarize(messages: Message[]): Promise<Message>;
+}
+/** A real, working default — no model call. Concatenates and truncates
+ * rather than genuinely summarizing, so the whole recovery pipeline is
+ * testable without wiring up an LLM. Swap in a real Summarizer (an LLM
+ * call, host-provided) for actual compression quality — this module
+ * doesn't bundle one, same as ActAuth doesn't bundle a Slack client. */
+export declare class TruncatingSummarizer implements Summarizer {
+    private readonly maxChars;
+    constructor(maxChars?: number);
+    summarize(messages: Message[]): Promise<Message>;
+}
+export type RecoverAction = 'unchanged' | 'drained' | 'summarized';
+export interface RecoverResult {
+    messages: Message[];
+    action: RecoverAction;
+    usedTokens: number;
+    budgetTokens: number;
+}
+export interface CompactorOptions {
+    budgetTokens: number;
+    /** Recovery target, as a fraction of budgetTokens — pass the same
+     * value as the BudgetTracker's own softThreshold so "how far
+     * compaction tries to shrink" agrees with "when a nudge fires"
+     * instead of being independently configured. Default 0.7. */
+    softThreshold?: number;
+    /** Most-recent messages never drained or summarized. Default 4. */
+    tailMessages?: number;
+    summarizer?: Summarizer;
+}
+/** Recovers in two stages, never touching the most recent tailMessages:
+ * a cheap deterministic drain first, a pluggable Summarizer second. */
+export declare class Compactor {
+    private readonly budgetTokens;
+    private readonly softThreshold;
+    private readonly tailMessages;
+    private readonly summarizer;
+    constructor(options: CompactorOptions);
+    private estimateUsage;
+    recover(messages: Message[]): Promise<RecoverResult>;
+}

package/dist/core/compaction.js

@@ -0,0 +1,70 @@
+// Vendored from the contextclip npm package (MIT license) and split in
+// two — see budget.ts's own header comment for why. This half is the
+// actual tail-preserving compaction: two staged, escalating recovery for
+// when budget.ts's own BudgetTracker.check() reports over_hard_limit.
+import { estimateTokens } from './budget.js';
+/** A real, working default — no model call. Concatenates and truncates
+ * rather than genuinely summarizing, so the whole recovery pipeline is
+ * testable without wiring up an LLM. Swap in a real Summarizer (an LLM
+ * call, host-provided) for actual compression quality — this module
+ * doesn't bundle one, same as ActAuth doesn't bundle a Slack client. */
+export class TruncatingSummarizer {
+    maxChars;
+    constructor(maxChars = 500) {
+        this.maxChars = maxChars;
+    }
+    async summarize(messages) {
+        const combined = messages.map((m) => `[${m.role}] ${m.content}`).join('\n');
+        const truncated = combined.length > this.maxChars ? `${combined.slice(0, this.maxChars)}…` : combined;
+        return { role: 'system', content: `[compacted ${messages.length} earlier message(s)]\n${truncated}` };
+    }
+}
+/** Recovers in two stages, never touching the most recent tailMessages:
+ * a cheap deterministic drain first, a pluggable Summarizer second. */
+export class Compactor {
+    budgetTokens;
+    softThreshold;
+    tailMessages;
+    summarizer;
+    constructor(options) {
+        this.budgetTokens = options.budgetTokens;
+        this.softThreshold = options.softThreshold ?? 0.7;
+        this.tailMessages = options.tailMessages ?? 4;
+        this.summarizer = options.summarizer ?? new TruncatingSummarizer();
+    }
+    estimateUsage(messages) {
+        return messages.reduce((sum, m) => sum + estimateTokens(`${m.role}: ${m.content}`), 0);
+    }
+    async recover(messages) {
+        const tailStart = Math.max(0, messages.length - this.tailMessages);
+        const tail = messages.slice(tailStart);
+        const head = messages.slice(0, tailStart);
+        const target = this.budgetTokens * this.softThreshold;
+        if (this.estimateUsage(messages) <= target) {
+            return { messages, action: 'unchanged', usedTokens: this.estimateUsage(messages), budgetTokens: this.budgetTokens };
+        }
+        // Stage 1: drain — cheap, no model call. Capped at half of `head` so
+        // there's always something left for stage 2 to compress instead of
+        // deleting everything outright.
+        const drainCap = Math.ceil(head.length / 2);
+        const remainingHead = head.slice(drainCap);
+        const drainedCount = head.length - remainingHead.length;
+        const afterDrain = [...remainingHead, ...tail];
+        if (this.estimateUsage(afterDrain) <= target) {
+            return {
+                messages: afterDrain,
+                action: drainedCount > 0 ? 'drained' : 'unchanged',
+                usedTokens: this.estimateUsage(afterDrain),
+                budgetTokens: this.budgetTokens,
+            };
+        }
+        // Stage 2: still over budget — summarize whatever's left of head.
+        // The tail is never touched.
+        let finalMessages = afterDrain;
+        if (remainingHead.length > 0) {
+            const summary = await this.summarizer.summarize(remainingHead);
+            finalMessages = [summary, ...tail];
+        }
+        return { messages: finalMessages, action: 'summarized', usedTokens: this.estimateUsage(finalMessages), budgetTokens: this.budgetTokens };
+    }
+}

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

@@ -0,0 +1,10 @@
+import { type Approver } from 'actauth';
+import type { AgentConfig, QuestionHandler } from './agent-config.js';
+interface ResolvedHttpNotifier {
+    approver?: Approver;
+    questionHandler?: QuestionHandler;
+    onRunStart?: NonNullable<AgentConfig['onRunStart']>;
+    onRunFinish?: NonNullable<AgentConfig['onRunFinish']>;
+}
+export declare function resolveHttpNotifier(config: AgentConfig): ResolvedHttpNotifier;
+export {};

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;
+}