loopengine 0.0.20 → 0.1.2

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

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

@@ -0,0 +1,21 @@
+import type { DurableApprover, Scope } from 'actauth';
+import type { DurableQuestionHandler } from '../agent-config.js';
+export declare class SlackNotifier implements DurableApprover, DurableQuestionHandler {
+    private readonly botToken;
+    private readonly channelId;
+    constructor(options: {
+        botToken: string;
+        channelId: 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: 'slack'` calls this directly with no
+     * `blocks` — a plain announcement, since there's nothing to resolve and
+     * so nothing to attach buttons to. */
+    postMessage(text: string, blocks?: unknown[]): void;
+}

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

@@ -0,0 +1,91 @@
+// The *sending* half of a Slack-backed DurableApprover/DurableQuestionHandler,
+// real, maintained core/ code so AgentConfig.httpNotifier
+// (core/http-notifier.ts) can construct one directly for `channel:
+// 'slack'`, the same way it already constructs actauth's own
+// WebhookApprover for `channel: 'webhook'`. Not "DurableSlackNotifier":
+// unlike the Web/Webhook pair, there's no live "SlackNotifier" this name
+// could collide with (Slack's own *live* approver, actauth's
+// `SlackChatApprover`, has an entirely different name already) — durable is
+// just what a Slack-backed notifier defaults to being, so the name
+// doesn't need to say so.
+//
+// The *receiving* side — verifying a Slack Interactivity payload really
+// came from Slack, then dispatching approve/deny/answer back into
+// loopengine's own resolve/answer routes — deliberately stays out of
+// core and out of this class: that's an HTTP endpoint only the host can
+// deploy (it needs a route, a public URL, Slack app configuration), the
+// same "sending built for you, receiving you deploy" split every other
+// durable channel in this repo has. See
+// examples/notifier-handler/slack.ts's own `SlackNotifierHandler` for
+// that half.
+//
+// One class for both concerns, not two: nothing about what a Slack
+// integration needs to send is approval-specific or question-specific,
+// it's Slack-specific (the bot token, the channel, the chat.postMessage
+// call shape).
+import { randomUUID } from 'node:crypto';
+export class SlackNotifier {
+    botToken;
+    channelId;
+    constructor(options) {
+        this.botToken = options.botToken;
+        this.channelId = options.channelId;
+    }
+    requestDurableApproval(tool, args, scope, reason) {
+        const pendingId = randomUUID();
+        this.postMessage(`Approval requested: ${tool} on ${scope.tenant}/${scope.environment}/${scope.agent}`, [
+            {
+                type: 'section',
+                text: {
+                    type: 'mrkdwn',
+                    text: `*Approval requested*\n*tool:* ${tool}\n*args:* \`${JSON.stringify(args)}\`\n*scope:* ${scope.tenant}/${scope.environment}/${scope.agent}\n*reason:* ${reason}`,
+                },
+            },
+            {
+                type: 'actions',
+                elements: [
+                    { type: 'button', text: { type: 'plain_text', text: 'Approve' }, style: 'primary', action_id: 'approve', value: pendingId },
+                    { type: 'button', text: { type: 'plain_text', text: 'Deny' }, style: 'danger', action_id: 'deny', value: pendingId },
+                ],
+            },
+        ]);
+        return { pendingId };
+    }
+    notifyPendingQuestion(question, options, agent, sessionId) {
+        const pendingId = randomUUID();
+        const optionButtons = (options ?? []).map((option) => ({
+            type: 'button',
+            text: { type: 'plain_text', text: option },
+            value: JSON.stringify({ pendingId, answer: option }),
+            action_id: 'answer_option',
+        }));
+        this.postMessage(`Question from ${agent}: ${question}`, [
+            { type: 'section', text: { type: 'mrkdwn', text: `*Question from ${agent}${sessionId ? ` (session ${sessionId})` : ''}:*\n${question}` } },
+            { type: 'actions', elements: [...optionButtons, { type: 'button', text: { type: 'plain_text', text: 'Other…' }, action_id: 'open_answer_modal', value: pendingId }] },
+        ]);
+        return { pendingId };
+    }
+    /** Public, not private: core/http-notifier.ts's own onRunStart/onRunFinish
+     * lifecycle sender for `channel: 'slack'` calls this directly with no
+     * `blocks` — a plain announcement, since there's nothing to resolve and
+     * so nothing to attach buttons to. */
+    postMessage(text, blocks) {
+        // Not awaited — both requestDurableApproval/notifyPendingQuestion
+        // above return immediately, by contract (see DurableApprover's own
+        // doc comment); a delivery failure here has no synchronous way to
+        // surface to either caller, so it's logged instead of thrown.
+        fetch('https://slack.com/api/chat.postMessage', {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${this.botToken}`, 'content-type': 'application/json; charset=utf-8' },
+            body: JSON.stringify({ channel: this.channelId, text, ...(blocks ? { blocks } : {}) }),
+        })
+            .then((res) => res.json())
+            .then((body) => {
+            if (!body.ok)
+                console.error('[loopengine] SlackNotifier: chat.postMessage failed:', body.error);
+        })
+            .catch((err) => {
+            console.error('[loopengine] SlackNotifier: chat.postMessage failed:', err);
+        });
+    }
+}

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

@@ -0,0 +1,27 @@
+import type { DurableApprover, Scope } from 'actauth';
+import type { DurableQuestionHandler } from '../agent-config.js';
+export declare class WebhookNotifier implements DurableApprover, DurableQuestionHandler {
+    private readonly webhookUrl;
+    private readonly signingSecret;
+    constructor(options: {
+        webhookUrl: string;
+        signingSecret: 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;
+    };
+    /** 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;

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

@@ -0,0 +1,94 @@
+// The generic-webhook channel's sending side, one class for both
+// concerns — same "it's channel-specific, not concern-specific" shape
+// slack.ts/lark.ts/email.ts already have, not the "two already-shipped
+// classes from two separate packages" split this file used to be (see
+// git history): approval-sending used to be actauth's own
+// `WebhookApprover`, question-sending loopengine's own
+// `WebhookQuestionHandler` (`core/system-tools/ask_user.ts`) — genuinely
+// separate classes, since `actauth`'s `Gate` has no concept of
+// `system_ask_user` questions at all (see HUMAN_IN_THE_LOOP.md's
+// "Durable questions" section). Nothing about *sending* a signed webhook
+// POST is actauth-specific, though, once you stop assuming the approval
+// half has to live in actauth's own package — both halves are the exact
+// same HMAC-SHA256-over-the-raw-body scheme, just under different
+// headers, so merging them removes real duplication (one class, one
+// constructor, one place either concern's own webhook target/secret is
+// held) rather than just looking simpler on paper.
+//
+// `actauth`'s own `WebhookApprover` still exists and is unaffected —
+// this is loopengine's own implementation of the same `DurableApprover`
+// interface, not a fork of actauth's class; a standalone actauth
+// consumer (no loopengine involved) still has and should use actauth's
+// own. loopengine no longer imports it anywhere, since everywhere it
+// used to (this file, and adapters/http.ts's own deployment-wide
+// default) now constructs one `WebhookNotifier` instead.
+//
+// The signed payloads below are wire-compatible with what actauth's
+// `WebhookApprover`/loopengine's former `WebhookQuestionHandler` already
+// sent — same fields, same `X-Actauth-Signature`/`X-Askuser-Signature`
+// headers — so an existing receiving-side deployment (this repo's own
+// `examples/notifier-handler/webhook.ts`, or a host's own) needs no
+// changes; only where the bytes come from moved.
+//
+// `postLifecycleWebhook` below is the third, genuinely new piece:
+// `onRunStart`/`onRunFinish` have no shipped class on either side, for
+// any channel (see this repo's own history — agents/customer-service/index.ts
+// used to hand-write this exact function before `AgentConfig.httpNotifier`
+// existed). Same signing scheme, under its own `X-Lifecycle-Signature`
+// header so a receiver can tell a lifecycle event apart from a
+// 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).
+import { createHmac, randomUUID } from 'node:crypto';
+export class WebhookNotifier {
+    webhookUrl;
+    signingSecret;
+    constructor(options) {
+        this.webhookUrl = options.webhookUrl;
+        this.signingSecret = options.signingSecret;
+    }
+    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);
+        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);
+        });
+    }
+}
+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);
+    });
+}

package/dist/core/loop-events.d.ts

@@ -1,31 +1,35 @@
-import type { CheckResult } from 'contextclip';
-import type { RecoveryAction } from 'reflowkit';
+import type { CheckResult } from './budget.js';
 import type { Decision, PendingApproval } from 'actauth';
 import type { PendingQuestion } from './system-tools/index.js';
-/** ContextClipper's own read-only budget check, run once per loop turn
+/** BudgetTracker's own read-only budget check, run once per loop turn
  * before the model call — reported unchanged (spread, not renamed) so
- * this never drifts from whatever contextclip's own CheckResult actually
+ * this never drifts from whatever budget.ts's own CheckResult actually
  * contains. */
-export type ContextClipCheckEvent = {
-    type: 'contextclip:check';
+export type BudgetCheckEvent = {
+    type: 'budget:check';
 } & CheckResult;
-/** ContextClip recovery kicked in because the prompt was rejected as too
- * large — `from`/`to` are message-array lengths (this turn's own
+/** compaction.ts's own recovery kicked in because the prompt was rejected as
+ * too large — `from`/`to` are message-array lengths (this turn's own
  * newMessages included), not token counts; see run-agent.ts's own
- * reflow.call onPromptTooLong hook. */
-export interface ReflowRecoverEvent {
-    type: 'reflow:recover';
+ * recovery.call onPromptTooLong hook. Named after *what triggered it and
+ * what happened* (the prompt was too long, so it got compacted), not
+ * after which module did the work — "compaction:recover" still didn't
+ * say this only ever fires for the prompt-too-long case specifically,
+ * same problem contextclip:check's own rename from a package name was
+ * fixing in the first place.
+ *
+ * No sibling event for recovery.ts's other two failure modes
+ * (media-too-large, truncated output) — neither has an onMediaTooLarge/
+ * onTruncated hook actually wired up in run-agent.ts today, so neither
+ * can currently fire at all. A prior 'recovery:summary' aggregate event
+ * covering all three was removed for being ~100% redundant with this one
+ * while that's true; it can come back once a second real recovery type
+ * exists to aggregate. */
+export interface PromptCompactionEvent {
+    type: 'prompt:compaction';
     from: number;
     to: number;
 }
-/** Ordered log of whatever reflowkit's own Reflow.call had to do to get a
- * usable response this turn (prompt-too-long retries, truncation
- * retries, ...) — empty-array case never fires this event at all (see
- * run-agent.ts: only logged when recoveries.length > 0). */
-export interface ReflowRecoveriesEvent {
-    type: 'reflow:recoveries';
-    recoveries: RecoveryAction[];
-}
 /** The model's own "I'll do X" preamble alongside a tool_use request —
  * the only *live* signal of assistant text mid-turn (the final answer
  * only ever arrives via 'loop:done'/'done', once, at the very end). */
@@ -77,10 +81,13 @@ export interface ToolLaneResultEvent {
     summary: string;
 }
 /** A `Skill` tool_use block was resolved to a real skill body via
- * SkillGarden — not gated by ActAuth (see run-agent.ts's own comment on
- * why Skill invocation isn't a real tool call). */
-export interface SkillGardenInvokeEvent {
-    type: 'skillgarden:invoke';
+ * SkillGarden's own lazy "index-now-load-later" design — not gated by
+ * ActAuth (see run-agent.ts's own comment on why Skill invocation isn't
+ * a real tool call). Named after what happened (the skill's full body
+ * got loaded), not after which library method was called — same
+ * reasoning budget:check's own rename from contextclip:check used. */
+export interface SkillLoadEvent {
+    type: 'skill:loaded';
     skill: string;
 }
 /** An approved call never ran because a sibling call in the same turn's
@@ -102,6 +109,26 @@ export interface LoopDeniedEvent {
     type: 'loop:denied';
     deniedTools: string[];
 }
+/** At least one requested tool call is durably pending a DurableApprover
+ * decision — the turn stops right there too, but unlike loop:denied this
+ * isn't a rejection: any already-approved sibling call in the same batch
+ * still ran (see run-agent.ts's own bucket-then-execute), and the turn
+ * resumes (via resumeAgent) once every pendingId here is resolved. See
+ * HUMAN_IN_THE_LOOP.md for the full design. */
+export interface PendingApprovalEvent {
+    type: 'loop:pending_approval';
+    pendingIds: string[];
+}
+/** The question-side sibling of PendingApprovalEvent above — at least one
+ * `system_ask_user` call is durably pending a DurableQuestionHandler
+ * (see HUMAN_IN_THE_LOOP.md's "Durable questions" section), fired only
+ * when nothing else in the same batch is a pending *approval* (a mixed
+ * batch reports PendingApprovalEvent instead — see
+ * RunAgentResult.stopReason's own doc comment for why). */
+export interface PendingQuestionEvent {
+    type: 'loop:pending_question';
+    pendingIds: string[];
+}
 /** The loop's own final answer — the model produced text with no more
  * tool_use blocks. Distinct from the adapter-level 'done' below: this
  * only ever means a genuine finish, never a synthetic max_turns/denied
@@ -113,7 +140,7 @@ export interface LoopDoneEvent {
 /** Every event runAgent() itself can emit via RunAgentOptions.onEvent —
  * not the adapter-synthesized ones below, which no caller of runAgent()
  * itself ever produces. */
-export type RunAgentLoopEvent = ContextClipCheckEvent | ReflowRecoverEvent | ReflowRecoveriesEvent | AssistantTextEvent | ActauthDecisionEvent | ToolStartedEvent | ToolResultEvent | ToolLaneResultEvent | SkillGardenInvokeEvent | LoopSkippedEvent | LoopMaxTurnsEvent | LoopDeniedEvent | LoopDoneEvent;
+export type RunAgentLoopEvent = BudgetCheckEvent | PromptCompactionEvent | AssistantTextEvent | ActauthDecisionEvent | ToolStartedEvent | ToolResultEvent | ToolLaneResultEvent | SkillLoadEvent | LoopSkippedEvent | LoopMaxTurnsEvent | LoopDeniedEvent | PendingApprovalEvent | PendingQuestionEvent | LoopDoneEvent;
 /** adapters/http.ts echoing back which session id this turn used — first
  * event of every streamed turn, so a caller that omitted sessionId can
  * capture what got generated. Not something runAgent() itself knows
@@ -136,14 +163,18 @@ export type ApprovalPendingEvent = {
 export type QuestionPendingEvent = {
     type: 'question:pending';
 } & PendingQuestion;
-/** The turn is over — covers a genuine finish and both synthetic
- * stopReasons (max_turns/denied) alike, the one event every caller can
- * treat as "nothing more is coming" regardless of which of the three it
- * was (see RunAgentResult.stopReason's own doc comment). */
+/** This turn/request is over — covers a genuine finish and all four
+ * synthetic stopReasons (max_turns/denied/pending_approval/pending_question)
+ * alike, the one event every caller can treat as "nothing more is coming
+ * on this response" regardless of which it was (see
+ * RunAgentResult.stopReason's own doc comment). pending_approval/
+ * pending_question, like denied, don't mean the conversation itself is
+ * over — only this turn; it resumes later via a separate resolve call,
+ * not by continuing to read this same response. */
 export interface DoneEvent {
     type: 'done';
     text: string;
-    stopReason?: 'max_turns' | 'denied';
+    stopReason?: 'max_turns' | 'denied' | 'pending_approval' | 'pending_question';
 }
 /** Something failed after the response was already committed (SSE
  * headers sent, or a background turn already running) — surfaced in-band