loopengine 0.0.21 → 0.1.3

package/PROTOCOL.md

@@ -235,9 +235,9 @@ language with a validator, not just JavaScript.
 - **`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.
-- **`ui-examples/react/`**, **`ui-examples/vue/`** — a hook/composable
-  and a chat component each, built on `core/client.ts`, rendering
-  `approval:pending`/`question:pending` as real UI.
+- **`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

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`:
 
@@ -408,16 +440,18 @@ 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 `ui-examples/react`/`ui-examples/vue` hooks are
-reference implementations of it.
+`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`.
@@ -440,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 |
+| [`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`),
@@ -69,11 +295,15 @@ export interface AgentConfig {
      * Omit entirely and it defaults to importing
      * `agents/<name>/tools/index.{ts,js}` and using its exported `tools` —
      * this repo's own aggregation-file convention (see
-     * `agents/customer-service/tools/index.ts`), resolved next to
-     * `run-agent.ts` itself (not `process.cwd()`, unlike `skillsDirs`/
-     * `rules` — that file is real compiled code, not data, so it has to be
-     * found next to whichever build of `run-agent.ts` is actually running).
-     * A missing file there is just `[]`, not an error — same
+     * `agents/customer-service/tools/index.ts`). Tried first next to
+     * `run-agent.ts` itself, since that file is real compiled code, not
+     * data — right when `agents/` is built alongside `core/` into the same
+     * `dist/` tree (this repo's own reference agents); falls back to
+     * `process.cwd()`, same as `skillsDirs`/`rules`, when nothing's built
+     * there — right for a project that only depends on the published
+     * package, whose own `agents/<name>/tools/` was never compiled into
+     * `node_modules/loopengine` at all.
+     * A missing file either place is just `[]`, not an error — same
      * missing-is-fine treatment `skillsDirs` gets. An agent that needs to
      * merge in tools from somewhere else too (e.g.
      * `agents/file-agent/index.ts`'s Composio-sourced ones) can't rely on
@@ -111,8 +341,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

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