loopengine 0.0.20 → 0.1.2

package/PROTOCOL.md

@@ -0,0 +1,245 @@
+# The loopengine event protocol
+
+**Status:** v1 · **Schema:** [`protocol/loop-event.schema.json`](protocol/loop-event.schema.json)
+
+One `runAgent()` turn emits an ordered sequence of typed `LoopEvent`
+objects. That sequence — not any particular transport — is the actual
+contract. The SSE stream, the plain HTTP response, and the CLI's `--json`
+mode are three different ways of delivering the exact same objects; a
+client written against one of them can switch to another without
+changing how it interprets a single event.
+
+This document specifies that sequence: every event's shape, when it
+fires, what's guaranteed about ordering, and how each transport carries
+it. If you're building a UI or integration against loopengine in any
+language — not just TypeScript — this is what to implement against
+instead of reverse-engineering `core/loop-events.ts`.
+
+## Stability
+
+This is v1. Within v1:
+
+- **Additive is safe to rely on being additive.** A new event `type` may
+  be introduced; a new optional field may be added to an existing event.
+  A consumer that ignores unrecognized `type` values and unrecognized
+  fields will never break.
+- **These are breaking changes**, and won't happen inside v1: renaming or
+  removing an event `type`; renaming, removing, or changing the meaning
+  of an existing field; turning an optional field required; changing an
+  established transport's framing (SSE's `event: <type>\ndata: <json>`,
+  the plain response's `events` array, or `--json`'s one-object-per-line
+  NDJSON).
+- A breaking change ships as v2, documented as a new section here, not a
+  silent edit to this one.
+
+## Lifecycle
+
+Every event has a `type` field, which doubles as the discriminant and,
+on the SSE transport, the literal frame name. Two families:
+
+- **Engine events** — emitted by `runAgent()` itself, identically
+  regardless of which transport is carrying them.
+- **Adapter events** — synthesized by the HTTP/CLI adapter around a turn
+  (`session`, `approval:pending`, `question:pending`, `done`, `error`).
+  `runAgent()` itself has no notion of sessions or HTTP-level failures;
+  these exist because a real caller needs them.
+
+A turn always starts with `session` (streamed) and always ends with
+exactly one `done`. The only real branch is the ActAuth Gate's decision
+on each requested tool call:
+
+```
+session → budget:check → assistant:text? → actauth:decision
+                                                       │
+                              ┌────────────────────────┴───────────────────────┐
+                              │ allow                                          │ deny
+                              ▼                                                ▼
+                   [approval:pending first,             tool:result (statusText: "Denied.")
+                    if the rule said "ask"]              — no execution, no tool:started.
+                              │                           Any sibling call already approved
+                              ▼                           in the same batch gets loop:skipped
+                        tool:started                      + its own tool:result ("Skipped.")
+                              ▼                                                │
+                       toollane:result                                        │
+                              ▼                                                │
+                     tool:result (Approved./Error.)                           │
+                              │                                                │
+                              └─────────────────┬──────────────────────────────┘
+                                                 ▼
+                          loops back to budget:check for the
+                          next tool call, or the model's next turn,
+                          until exactly one of:
+                          loop:done / loop:max_turns / loop:denied
+                                                 ▼
+                                               done
+```
+
+`approval:pending`/`question:pending` are the only events without a
+fixed position in that diagram — they can arrive at any point a tool call
+is being evaluated. At most one is ever pending at a time (the Gate
+evaluates one call before starting the next), so a consumer never needs
+to track more than one open decision per turn.
+
+## Event catalog
+
+### Engine — emitted by `runAgent()`
+
+| `type` | Fires | Fields |
+|---|---|---|
+| `budget:check` | Once per model call, before it | `action: 'ok'\|'nudge'\|'over_hard_limit'`, `usedTokens`, `budgetTokens`, `ratio`, `nudge?` |
+| `prompt:compaction` | A prompt was rejected as too large | `from`, `to` (message-array lengths, not tokens) |
+| `assistant:text` | The model's "I'll do X" preamble alongside a tool call | `text` |
+| `actauth:decision` | Once per requested tool call | `tool`, `decision: 'allow'\|'ask'\|'deny'`, `reason` |
+| `tool:started` | The instant a call is decided, before it runs | `id`, `tool`, `args`, `detailText` |
+| `tool:result` | A call resolves — allowed, denied, or skipped | `id`, `tool`, `args?`, `detailText?`, `statusText` |
+| `toollane:result` | ToolLane's own raw outcome, alongside `tool:result` | `name`, `summary` |
+| `skill:loaded` | A `Skill` block resolved to a real skill body | `skill` |
+| `loop:skipped` | A sibling call never ran because another was denied | `name`, `deniedTools` |
+| `loop:max_turns` | Hit `config.maxTurns` with no final answer | `maxTurns` |
+| `loop:denied` | A human denied a call — the turn stops | `deniedTools` |
+| `loop:done` | A genuine finish — no more tool calls | `text` |
+
+### Adapter — synthesized around a turn
+
+| `type` | Fires | Fields |
+|---|---|---|
+| `session` | First event of every streamed turn | `sessionId` |
+| `approval:pending` | A tool call needs a live human decision | `id`, `tool`, `args`, `scope: {tenant,environment,agent}`, `reason`, `requestedAt` |
+| `question:pending` | The `ask_user` tool raised a real question | `id`, `question`, `options?`, `agent`, `sessionId?`, `requestedAt` |
+| `done` | The turn is over — wraps `loop:done`/`max_turns`/`denied` | `text`, `stopReason?: 'max_turns'\|'denied'` |
+| `error` | Something failed after the response was already committed | `error` |
+
+Full field types, `required` vs optional, and `additionalProperties: false`
+enforcement live in [`protocol/loop-event.schema.json`](protocol/loop-event.schema.json)
+— the table above is a summary, the schema is the source of truth.
+
+## Transports
+
+### SSE stream — live, frame by frame
+
+```
+POST /agents/:name/messages/stream
+content-type: application/json
+
+{"message": "order A-1001 arrived broken, can you refund it?"}
+```
+
+Each frame is `event: <type>\ndata: <json>\n\n`, `<json>` being the whole
+event object (`type` included, redundantly with the frame name — parse
+whichever is more convenient):
+
+```
+event: tool:started
+data: {"type":"tool:started","id":"call_1","tool":"issue_refund","args":{"orderId":"A-1001"},"detailText":"matched rule 'refunds-need-approval'"}
+
+event: approval:pending
+data: {"type":"approval:pending","id":"3f9c...","tool":"issue_refund","args":{"orderId":"A-1001"},"scope":{"tenant":"default","environment":"production","agent":"customer-service"},"reason":"matched rule 'refunds-need-approval'","requestedAt":"2026-08-28T01:34:32.193Z"}
+```
+
+### Plain HTTP — one request, the full array
+
+```
+POST /agents/:name/messages
+content-type: application/json
+
+{"message": "..."}
+```
+
+Two response shapes, both carrying the identical `events` array a
+streamed version of the same turn would have delivered live:
+
+**200 — the turn finished:**
+
+```json
+{
+  "text": "Refunded $42.00 to your original payment method.",
+  "sessionId": "5a83c6b4-...",
+  "events": [ /* every LoopEvent this turn produced, in order */ ],
+  "stopReason": "max_turns"
+}
+```
+
+`stopReason` is present only for a synthetic finish (`max_turns`/`denied`).
+
+**202 — the turn needs a decision right now:**
+
+```json
+{
+  "pending": true,
+  "type": "approval",
+  "id": "3f9c...",
+  "sessionId": "5a83c6b4-...",
+  "tool": "issue_refund",
+  "args": { "orderId": "A-1001" },
+  "scope": { "tenant": "default", "environment": "production", "agent": "customer-service" },
+  "reason": "matched rule 'refunds-need-approval'",
+  "approveUrl": "/approvals/3f9c.../approve",
+  "denyUrl": "/approvals/3f9c.../deny",
+  "events": [ /* everything so far */ ],
+  "statusUrl": "/agents/customer-service/sessions/5a83c6b4-..."
+}
+```
+
+(`type: "question"` carries `question`/`options`/`answerUrl` instead.)
+
+### CLI — one JSON object per line
+
+```
+loopengine run customer-service --json "order A-1001 arrived broken, can you refund it?"
+```
+
+```
+{"type":"session","sessionId":"5a83c6b4-..."}
+{"type":"budget:check","action":"ok","usedTokens":2,"budgetTokens":8000,"ratio":0.00025}
+{"type":"tool:started","id":"call_1","tool":"issue_refund", ...}
+{"type":"done","text":"Refunded $42.00..."}
+```
+
+Every line is a complete `LoopEvent`, pipeable straight into `jq` or
+anything else that reads NDJSON. Without `--json`, stdout stays
+human-readable (just the final answer) and events go to stderr instead.
+
+### Resolving a pending item
+
+```
+POST /approvals/:id/approve      POST /approvals/:id/deny
+POST /questions/:id/answer   {"answer": "..."}
+```
+
+All three return the exact same two-shape family as plain
+`POST /messages` above (200 done, or 202 the *next* pending item, if the
+turn needed another decision) — a caller can treat send → approve/deny/
+answer → approve/deny/answer → ... as one uniform loop regardless of
+which endpoint produced the response.
+
+## Validating against the schema
+
+```js
+import Ajv2020 from 'ajv/dist/2020.js'
+import addFormats from 'ajv-formats' // schema uses format: 'date-time'
+import schema from './protocol/loop-event.schema.json' with { type: 'json' }
+
+const ajv = new Ajv2020({ strict: true })
+addFormats(ajv)
+const validate = ajv.compile(schema)
+validate(event) // true/false; validate.errors on failure
+```
+
+The schema is hand-maintained alongside `core/loop-events.ts`, not
+generated from it — a PR that changes one without the other is
+incomplete. It's plain JSON Schema (draft 2020-12), so it works from any
+language with a validator, not just JavaScript.
+
+## Reference implementations
+
+- **`core/client.ts`** — the framework-agnostic TypeScript client this
+  spec was extracted from: SSE parsing, the plain-request helpers,
+  approve/deny/answer. Re-exported through the package's own entry point.
+- **`examples/chatbox/react/`**, **`examples/chatbox/vue/`** — a
+  hook/composable and a chat component each, built on `core/client.ts`,
+  rendering `approval:pending`/`question:pending` as real UI.
+
+Implementing this protocol in another language means reproducing what
+`core/client.ts` does: parse whichever transport you chose into
+`LoopEvent` objects per this schema, and drive your own UI or logic off
+`type`.

package/README.md

@@ -102,8 +102,10 @@ hidden control flow: call the model, act on what it asks for, repeat.
 1. Call the model with the conversation so far.
 2. If it responds with tool calls, each one is checked against
    `AgentConfig.rules` — allowed calls run, denied calls are refused,
-   "ask" calls wait on `AgentConfig.approver` (see "Tool permission and
-   multi-tenancy" below).
+   "ask" calls go to whatever approver applies for the call's own channel
+   (see "Tool permission and multi-tenancy" below) — a live approver is
+   awaited right there; a durable one returns instantly and the call is
+   resolved later instead.
 3. Approved calls execute and their results feed back into the
    conversation.
 4. Repeat from step 1 — until the model stops requesting tools
@@ -293,9 +295,39 @@ adding a source (or use the page's permission dropdown) to seed an
 Every tool call is gated by [`actauth`](https://www.npmjs.com/package/actauth):
 each rule in `AgentConfig.rules` maps a `scope` (tenant/environment) + tool
 name to `allow` / `ask` / `deny`. Anything not covered falls through to
-`defaultDecision`. An `ask` decision routes to `AgentConfig.approver`
-(defaults to blocking on stdin — swap in a real one, e.g. Slack-backed,
-for production).
+`defaultDecision`. An `ask` decision routes to whichever approver applies
+for the call's own channel: `cli`/`http_stream` always get the library's
+own live default (`ConsoleApprover`, blocking on stdin, for `cli`; a live
+approval popup for `http_stream`) — nothing to configure there — and
+`http` gets a durable one whenever `AgentConfig.httpNotifier` is
+configured for it (see below), falling back to the same kind of live
+default otherwise.
+
+`ask` approvers come in two shapes. A **live** one (`WebchatApprover`,
+`SlackChatApprover`, `ConsoleApprover`) is awaited directly — the turn stays
+suspended until a human decides, which only makes sense when someone's
+actually there right now (a terminal, an open chat connection). A
+**durable** one (`WebhookApprover`) fires a signed webhook and returns
+instantly instead — the turn ends with `stopReason: 'pending_approval'`,
+durably resumable minutes or days later via
+`POST /pending-approvals/:pendingId/resolve`, without holding any
+process open in between. See `HUMAN_IN_THE_LOOP.md` for the full design.
+
+The system `ask_user` tool (a model asking a human a genuinely ambiguous
+clarifying question mid-turn) gets the same live/durable split, via
+`RunAgentOptions.questionHandler` (or `AgentConfig.httpNotifier`'s own
+`'question'` event, for the `http` channel specifically): live by default
+(blocks on the channel it's raised on), or durable — a
+`DurableQuestionHandler` (e.g. `core/http-notify-triggers/webhook.ts`'s
+`WebhookNotifier`) instead ends the turn with `stopReason:
+'pending_question'`, resumable via
+`POST /pending-questions/:pendingId/answer`. See `HUMAN_IN_THE_LOOP.md`'s
+own "Durable questions" section.
+
+For the practical "what do I actually need to build" version of all of
+this — live chat setup, durable setup, and reference implementations for
+Slack/Lark/email/generic-webhook notification channels — see
+[`HUMAN_IN_THE_LOOP.md`](HUMAN_IN_THE_LOOP.md).
 
 A real agent's rules live in `agents/<name>/actauth.yml`:
 
@@ -403,13 +435,23 @@ into the playground and config page below.
 that same loop-step event stream render live instead of reading raw SSE
 frames. Same `/messages/stream` route underneath.
 
+**Building your own client:** the playground is one UI on top of a typed
+event protocol, not the only way to consume a turn — see
+[`PROTOCOL.md`](PROTOCOL.md) for the full `LoopEvent` catalog, the SSE/
+plain-HTTP/CLI transport bindings, and a JSON Schema
+(`protocol/loop-event.schema.json`) any language can validate against.
+`core/client.ts` and the `examples/chatbox/react`/`examples/chatbox/vue`
+hooks are reference implementations of it.
+
 **Agent config page:** open `http://localhost:8787/agents/config`
 (optionally `?agent=<name>`) to browse every registered agent's resolved
 config — system prompt, model, tools (with their JSON schemas and
 parallel-safety), the actual ActAuth rules that would be enforced (source,
 default decision, per-rule scope/tool/decision/`when`), and whether
-`sessionIdFor`/`tenantFor`/`isSafeTool`/`approver` are custom or
-defaulted. Backed by `GET /agents/:name/config`, which reuses the same
+`sessionIdFor`/`tenantFor`/`isSafeTool` are custom or defaulted, and
+whether the `http` channel's approver is custom (`httpNotifier` covers
+`'approval'`) or the library's own default. Backed
+by `GET /agents/:name/config`, which reuses the same
 rule/tool resolution `runAgent()` itself uses, so it can't drift out of
 sync with what a real request actually gets. Never returns
 `AgentModelConfig.apiKey`.
@@ -432,9 +474,10 @@ testing), export your own `createModelCall(): ModelCall` instead.
 
 | Package | Responsibility |
 |---|---|
-| [`actauth`](https://www.npmjs.com/package/actauth) | Permission gating (allow/ask/deny) with human-approval hooks |
-| [`contextclip`](https://www.npmjs.com/package/contextclip) | Context-window budget tracking |
-| [`reflowkit`](https://www.npmjs.com/package/reflowkit) | Retries prompt-too-long / truncated-output failures |
+| [`actauth`](https://www.npmjs.com/package/actauth) | Permission gating (allow/ask/deny/pending) with live and durable human-approval hooks |
+| `core/budget.ts` / `core/compaction.ts` | Context-window budget tracking and tail-preserving compaction (vendored in-repo, not an external dependency) |
+| `core/recovery.ts` | Retries prompt-too-long / truncated-output failures (vendored in-repo, not an external dependency) |
+| `core/durable-approvals.ts` | `TurnCheckpoint`/`CheckpointStore` (file/Redis) backing durable, resumable `ask` decisions — see `HUMAN_IN_THE_LOOP.md` |
 | [`sessionknit`](https://www.npmjs.com/package/sessionknit) | Durable session log with crash-interruption detection |
 | [`skillgarden`](https://www.npmjs.com/package/skillgarden) | `SKILL.md` discovery and lazy loading |
 | [`toollane`](https://www.npmjs.com/package/toollane) | Parallel/solo tool-call scheduling |

package/dist/core/agent-config.d.ts

@@ -1,5 +1,231 @@
-import type { Rule, Decision, Approver } from 'actauth';
+import type { Rule, Decision, Scope } from 'actauth';
+import type { Redis } from 'ioredis';
 import type { SafetyClassifier } from 'toollane';
+/** Which channel a runAgent() call is on — the value RunAgentOptions.channel
+ * carries, checked against directly by AgentConfig.httpNotifier's own
+ * resolution (see its own doc comment for why it only ever matches
+ * `'http'`). `cli`/`http_stream` always get the library's own live
+ * defaults (`ConsoleApprover`, `CliQuestionHandler`, or whatever live
+ * approver/questionHandler the adapter itself passes as
+ * `RunAgentOptions.approver`/`questionHandler`) — there's no
+ * AgentConfig-level way to override either for those two channels
+ * specifically; only `http` has one, via `httpNotifier`. */
+export type ApproverChannel = 'cli' | 'http' | 'http_stream';
+/** A pending system_ask_user question — defined here, not in
+ * core/system-tools/ask_user.ts, purely so LiveQuestionHandler/
+ * DurableQuestionHandler below can reference it without a circular import
+ * (ask_user.ts already imports from this file for
+ * ToolDefinition/DurableQuestionHandler); ask_user.ts re-exports this same
+ * type for its own module's callers. */
+export interface PendingQuestion {
+    id: string;
+    question: string;
+    /** Suggested answers, if the model gave any — never the only allowed
+     * answer, a human can still respond with free text either way. */
+    options?: string[];
+    /** Which agent raised this — always known (config.name), so listing can
+     * always at least be scoped per-agent even without a session id. */
+    agent: string;
+    /** Which conversation raised this, if the caller has one (see
+     * RunAgentOptions.sessionId's own doc comment for when it doesn't). */
+    sessionId?: string;
+    requestedAt: string;
+}
+/** The question-side sibling of actauth's own `DurableApprover` — fires a
+ * notification and returns a `pendingId` immediately, never awaited for
+ * the actual answer (see HUMAN_IN_THE_LOOP.md's "Durable questions"
+ * section). Lives here, in loopengine, rather than in actauth: unlike a
+ * tool-call approval, `system_ask_user` (core/system-tools/ask_user.ts)
+ * is loopengine's own system tool — it never goes through actauth's
+ * `Gate` at all (see that file's own doc comment on why it can't be
+ * gated), so actauth has no reason to know it exists. Positional args,
+ * mirroring `DurableApprover.requestDurableApproval(tool, args, scope,
+ * reason)`'s own shape. The built-in implementations are
+ * `core/http-notify-triggers/webhook.ts`'s `WebhookNotifier` and its
+ * slack.ts/lark.ts/email.ts siblings. */
+export interface DurableQuestionHandler {
+    notifyPendingQuestion(question: string, options: string[] | undefined, agent: string, sessionId: string | undefined): {
+        pendingId: string;
+    };
+}
+/** The question-side sibling of actauth's own `LiveApprover` — awaited
+ * directly for the human's actual answer, same call shape
+ * `DurableQuestionHandler.notifyPendingQuestion` has except this one
+ * blocks and returns the real answer instead of a `pendingId`. `onPending`
+ * mirrors `WebchatApprover`'s own notification hook, but stays a per-call
+ * argument here rather than a constructor option — see
+ * `WebchatQuestionHandler`'s own doc comment (core/system-tools/ask_user.ts)
+ * for why a question, unlike an approval, only ever needs one shared
+ * registry, not a fresh instance per turn. The two built-in
+ * implementations are `WebchatQuestionHandler` and `CliQuestionHandler`
+ * (both core/system-tools/ask_user.ts). */
+export interface LiveQuestionHandler {
+    requestQuestion(question: string, options: string[] | undefined, agent: string, sessionId: string | undefined, onPending?: (question: PendingQuestion) => void): Promise<string>;
+}
+/** `RunAgentOptions.questionHandler`'s own type — mirrors actauth's own
+ * `Approver = LiveApprover | DurableApprover` union exactly, resolved the
+ * same `http`-only-fallback way `httpNotifier` resolves an approver, and
+ * duck-typed (`core/system-tools/ask_user.ts`'s `isDurableQuestionHandler`)
+ * the identical way `Gate` distinguishes a live from a durable `Approver`. */
+export type QuestionHandler = LiveQuestionHandler | DurableQuestionHandler;
+/** Which of the four durable/lifecycle concerns an HttpNotifierConfig
+ * should cover — 'approval'/'question' make that concern durable on the
+ * `http` channel (a signed webhook standing in for a live human),
+ * 'run_start'/'run_finish' wire `onRunStart`/`onRunFinish` to the same
+ * webhook instead of requiring them written out by hand. Listing only
+ * some of the four is deliberate, not partial config — an agent that
+ * wants durable approvals but a live (blocking) question flow lists just
+ * `['approval']`. */
+export type HttpNotifierEvent = 'approval' | 'question' | 'run_start' | 'run_finish';
+/** `channel: 'database'`/`'redis'`'s own narrower `events` — both are
+ * approval-only backends (a row/queue entry, not a notification to
+ * anyone), with no `DurableQuestionHandler` or lifecycle-sender
+ * equivalent at all — see `core/http-notify-triggers/database.ts`'s own
+ * doc comment for why. Listing `'question'`/`'run_start'`/`'run_finish'`
+ * for either channel wouldn't be a type error under the plain
+ * `HttpNotifierEvent[]` these two used before, just silently inert; this
+ * narrower type catches that at the config-authoring boundary instead. */
+export type ApprovalOnlyHttpNotifierEvent = 'approval';
+/** A `sendEmail` function, passed in rather than a hardcoded provider —
+ * see `core/http-notify-triggers/email.ts`'s own doc comment for why
+ * (an SMTP client/provider SDK is a dependency this package deliberately
+ * doesn't carry). */
+export type SendEmail = (to: string, subject: string, html: string) => Promise<void>;
+/** One row `channel: 'database'` (`core/http-notify-triggers/database.ts`)
+ * inserts per pending approval — implement `insert()` against whatever
+ * real database/ORM you already have (a single INSERT, a Prisma/Drizzle
+ * create call, anything); `DatabaseApprover` needs nothing else
+ * from it. */
+export interface PendingApprovalRow {
+    pendingId: string;
+    tool: string;
+    args: Record<string, unknown>;
+    scope: Scope;
+    reason: string;
+    requestedAt: string;
+}
+export interface PendingApprovalsRepository {
+    insert(row: PendingApprovalRow): Promise<void>;
+}
+/** The `http` channel's one notification config — replaces what used to
+ * be up to three separate fields (a channel-keyed `approvers.http`
+ * override, `onRunStart`, `onRunFinish`) with the single shape almost
+ * every real deployment actually wants: one webhook, receiving whichever
+ * of approvals/questions/lifecycle events it asks for. Resolved by
+ * `core/http-notifier.ts`'s `resolveHttpNotifier` — see that module for
+ * the actual `WebhookNotifier`/signed-POST construction.
+ *
+ * Only ever consulted for the `http` channel, and only as a fallback
+ * *there*: `RunAgentOptions.approver`/`questionHandler` (an adapter's own
+ * per-call default — `adapters/http.ts`'s plain route always passes one)
+ * still loses to this when it's set, the same "the agent's own explicit
+ * choice for this channel wins outright over whatever the adapter would
+ * otherwise default to" precedent a channel-keyed override always had
+ * here — but an explicit `AgentConfig.onRunStart`/`onRunFinish`, if also
+ * set, still wins outright over this field's own derived hooks (no
+ * per-call value competes with those the way `options.approver` does).
+ *
+ * `cli`/`http_stream` never consult this at all, not even as a fallback
+ * — they keep the library's own live defaults (`ConsoleApprover`,
+ * `CliQuestionHandler`, or whatever live approver the adapter passes as
+ * `RunAgentOptions.approver`) automatically, with nothing to configure.
+ * This isn't a limitation to work around: a durable webhook stands in
+ * for a human who isn't there to answer live, which is exactly what
+ * `http` (no open connection to block on) needs and `cli`/`http_stream`
+ * (a real human already attached, live, right now) don't. There's also
+ * no more AgentConfig-level way to give `cli`/`http_stream` their own
+ * custom *live* approver, the way a former `approvers.cli`/
+ * `approvers.http_stream` entry could — see `RunAgentOptions.approver`'s
+ * own doc comment if a specific call genuinely needs one; a whole demo
+ * agent auto-approving on every channel (this repo used to have two)
+ * turned out to be exactly the "config re-deriving the same webhook
+ * settings a real approver already has" duplication this field exists
+ * to remove, not a use case worth keeping a separate field alive for.
+ *
+ * Six channels ship today, `resolveHttpNotifier` (`core/http-notifier.ts`)
+ * switches on which — each one's own sending-side class lives under
+ * `core/http-notify-triggers/`:
+ *   - `'webhook'` — a signed HMAC-SHA256 POST, via
+ *     `http-notify-triggers/webhook.ts`'s `WebhookNotifier` (one
+ *     instance for both concerns, same shape as `'slack'`/`'lark'`/
+ *     `'email'` below — not actauth's own `WebhookApprover` plus a
+ *     separate loopengine question class anymore; see that file's own
+ *     doc comment for why they merged) — plus the lifecycle sender
+ *     neither approvals nor questions needed on their own.
+ *   - `'slack'` — bot-token `chat.postMessage`, via
+ *     `http-notify-triggers/slack.ts`'s `SlackNotifier`.
+ *   - `'lark'` — Lark/Feishu's own card API, via
+ *     `http-notify-triggers/lark.ts`'s `LarkNotifier` (lower
+ *     confidence on exact card-schema field names — see that file's own
+ *     header comment).
+ *   - `'email'` — a `sendEmail` callback plus a signed, expiring
+ *     magic-link token per approval/question, via
+ *     `http-notify-triggers/email.ts`'s `EmailNotifier`.
+ *   - `'database'`/`'redis'` — not a notification channel at all (see
+ *     `ApprovalOnlyHttpNotifierEvent`'s own doc comment): a row insert or
+ *     a queue push for a separate worker/dashboard to poll, via
+ *     `http-notify-triggers/database.ts`'s `DatabaseApprover`/
+ *     `http-notify-triggers/redis.ts`'s `RedisQueueApprover`.
+ *     `'approval'` is the only event either ever does anything with.
+ *
+ * `'webhook'`/`'slack'`/`'lark'`/`'email'` post an interactive message
+ * (buttons, a card, or a link) for `'approval'`/`'question'`, and a plain
+ * announcement (no buttons — nothing to resolve) for
+ * `'run_start'`/`'run_finish'`. The discriminated union shape (`channel`
+ * plus a matching `config`) is what lets a future kind be added later as
+ * another member, not another AgentConfig field. For anything none of
+ * these cover (a channel not listed above, a live `QuestionHandler` on
+ * `http`, ...) set `onRunStart`/`onRunFinish` directly instead, or pass a
+ * custom `RunAgentOptions.approver`/`questionHandler` from your own
+ * adapter — this field is sugar over the common cases, never a
+ * replacement for everything those can express. */
+export type HttpNotifierConfig = {
+    channel: 'webhook';
+    config: {
+        webhookUrl: string;
+        webhookSecret: string;
+    };
+    events: HttpNotifierEvent[];
+} | {
+    channel: 'slack';
+    config: {
+        botToken: string;
+        channelId: string;
+    };
+    events: HttpNotifierEvent[];
+} | {
+    channel: 'lark';
+    config: {
+        appId: string;
+        appSecret: string;
+        chatId: string;
+    };
+    events: HttpNotifierEvent[];
+} | {
+    channel: 'email';
+    config: {
+        to: string;
+        sendEmail: SendEmail;
+        resolveBaseUrl: string;
+        answerBaseUrl: string;
+        signingSecret: string;
+        linkTtlMs?: number;
+    };
+    events: HttpNotifierEvent[];
+} | {
+    channel: 'database';
+    config: {
+        repository: PendingApprovalsRepository;
+    };
+    events: ApprovalOnlyHttpNotifierEvent[];
+} | {
+    channel: 'redis';
+    config: {
+        redis: Redis;
+        queueKey?: string;
+    };
+    events: ApprovalOnlyHttpNotifierEvent[];
+};
 /** Declares which real ModelCall an agent module wants built for it, so
  * the module doesn't have to export its own `createModelCall` —
  * `discoverAgents` synthesizes one instead (see `discover-agents.ts`),
@@ -111,8 +337,61 @@ export interface AgentConfig {
     /** Decision when no rule matches, for the inline-array `rules` form only.
      * Default 'ask' — new tools are opt-in, not silently allowed. */
     defaultDecision?: Decision;
-    /** Default ConsoleApprover (blocks on stdin) — pass e.g. a Slack-backed Approver for unattended agents. */
-    approver?: Approver;
+    /** The `http` channel's notification config — see
+     * `HttpNotifierConfig`'s own doc comment for the full precedence rules
+     * and why it only ever touches that one channel. There's no equivalent
+     * for `cli`/`http_stream`: both always get the library's own live
+     * defaults, with nothing to configure. */
+    httpNotifier?: HttpNotifierConfig;
+    /** Fires once, fire-and-forget, at the start of every `runAgent()`/
+     * `resumeAgent()` call on the `http` channel (or no channel at all —
+     * see below) — the "someone triggered this agent" signal, for
+     * visibility into unattended/cron-triggered runs specifically. Never
+     * fires for `cli`/`http_stream`: both already deliver the "it started"
+     * signal to whoever's waiting synchronously, as part of that channel's
+     * own normal response (a terminal that just ran the command; an SSE
+     * connection carrying its own `session` event on the same stream) — a
+     * second, redundant copy of information the caller already has, so
+     * loopengine itself skips it there rather than leaving every
+     * implementation to notice and filter it out. A caller with no
+     * `channel` at all (a bespoke script) still fires, since there's no
+     * such guaranteed synchronous delivery to assume for it either way.
+     * `trigger` distinguishes a fresh message from a durable resume (a
+     * human just answered/approved something) — an implementation that
+     * only cares about the former (the common "announce a new
+     * cron-triggered run started" case) checks that field itself;
+     * loopengine doesn't guess which one you care about. Never awaited: an
+     * implementation that returns a Promise has its rejection caught and
+     * logged, not surfaced to the loop — a failed announcement shouldn't
+     * fail the turn that triggered it. See `HUMAN_IN_THE_LOOP.md` for the
+     * problem this and `onRunFinish` below solve. */
+    onRunStart?: (context: {
+        agent: string;
+        tenant: string;
+        sessionId?: string;
+        channel?: ApproverChannel;
+        trigger: 'message' | 'resolution';
+    }) => void | Promise<void>;
+    /** Fires once, fire-and-forget, whenever a turn reaches a genuine
+     * terminal outcome — `loop:done`, `max_turns`, or `denied` — never for
+     * `pending_approval`/`pending_question` (those are paused, not
+     * finished), and never for `cli`/`http_stream` for the exact same
+     * "that channel already delivered this synchronously" reasoning
+     * `onRunStart` above has (an SSE connection's own `done` event *is*
+     * this signal, already). This is `onRunFinish`, not `onRunStart`'s own
+     * mirror by accident: the actual gap it closes is durability-specific —
+     * the caller that sent the original message may be long disconnected
+     * by the time a durably-paused turn resumes and finishes (see
+     * `HUMAN_IN_THE_LOOP.md`'s own section on this). Same never-awaited
+     * contract as `onRunStart` above. */
+    onRunFinish?: (context: {
+        agent: string;
+        tenant: string;
+        sessionId?: string;
+        channel?: ApproverChannel;
+        text: string;
+        stopReason?: 'max_turns' | 'denied';
+    }) => void | Promise<void>;
     /** Resolves the ActAuth tenant for a request, from headers (never the
      * body: tenant feeds permission decisions directly, so it has to come
      * from something verified — an Authorization/API-key header checked