loopengine 0.0.20 → 0.0.21

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.
+- **`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.
+
+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

@@ -403,6 +403,14 @@ 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 `ui-examples/react`/`ui-examples/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
@@ -433,8 +441,8 @@ 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 |
+| `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) |
 | [`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/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
@@ -113,7 +120,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 | 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

package/dist/core/model-calls/openai-model-call.js

@@ -13,7 +13,7 @@
 //
 // stop_reason is normalized to the vocabulary anthropic-model-call.ts
 // already established ('end_turn' / 'tool_use' / 'max_tokens') rather than
-// passed through as OpenAI's own finish_reason strings — reflowkit's
+// passed through as OpenAI's own finish_reason strings — recovery.ts's
 // defaultIsTruncated checks a translated ModelResponse for stop_reason ===
 // 'max_tokens', so a provider-agnostic caller wiring up onTruncated later
 // gets the same behavior regardless of which ModelCall is plugged in.

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

@@ -35,7 +35,7 @@ export interface ModelResponse {
     content: ModelContentBlock[];
 }
 /** loopengine's own conversation-message type — a superset of
- * ContextClip's `{role, content: string}`: `content` can also be a
+ * budget.ts's own `{role, content: string}`: `content` can also be a
  * `ModelContentBlock[]`, the same block shape `ModelResponse.content`
  * already used, so a model's tool_use requests and this loop's
  * tool_result replies round-trip with real per-call identity
@@ -109,7 +109,7 @@ export interface RunAgentResult {
      * the caller: store/transmit it, don't inspect or mutate it. */
     history: Message[];
     /** Exactly what this turn added — safe to durably append regardless of
-     * whether ContextClip recovery reshaped `history` mid-turn. A caller
+     * whether compaction.ts's own recovery reshaped `history` mid-turn. A caller
      * that persists conversations (see session-store.ts) should use this
      * instead of diffing `history` by length against what it loaded: that
      * only works if `history` only ever grows, which stops being true the

package/dist/core/run-agent.js

@@ -9,9 +9,10 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 import { Gate, RuleSet, ConsoleApprover } from 'actauth';
 import { SkillGarden } from 'skillgarden';
-import { ContextClipper } from 'contextclip';
+import { BudgetTracker } from './budget.js';
+import { Compactor } from './compaction.js';
 import { ToolLane } from 'toollane';
-import { Reflow } from 'reflowkit';
+import { Recovery } from './recovery.js';
 import { loadAgentModule } from './discover-agents.js';
 import { agentAsTool } from './agent-as-tool.js';
 import { loadGatewayToolsFromDir } from './gateway-tools.js';
@@ -48,11 +49,11 @@ export const systemSkillsDir = join(dirname(fileURLToPath(import.meta.url)), 'sy
 export function dedupeToolsByName(list) {
     return [...new Map(list.map((t) => [t.name, t])).values()];
 }
-/** ContextClip only ever needs a flat string per message to estimate
- * token usage — it doesn't need to understand tool_use/tool_result
+/** budget.ts/compaction.ts only ever need a flat string per message to
+ * estimate token usage — neither needs to understand tool_use/tool_result
  * structure, so this is a one-way, read-only projection, never something
  * that needs to be un-projected back. */
-function flattenForContextClip(message) {
+function flattenForBudget(message) {
     if (typeof message.content === 'string')
         return { role: message.role, content: message.content };
     const text = message.content
@@ -295,7 +296,14 @@ export async function runAgent(config, modelCall, userMessage, history = [], opt
     // Also the tail-preservation window recover() below relies on — kept as
     // one named constant so the two can never drift out of sync.
     const tailMessages = 4;
-    const contextClip = new ContextClipper({ budgetTokens: config.contextBudgetTokens ?? 8000, tailMessages });
+    // Two separate objects, not one — budget.ts's BudgetTracker (read-only
+    // check) and compaction.ts's Compactor (the actual recovery) are
+    // deliberately distinct capabilities now, constructed with the same
+    // budgetTokens/softThreshold so a nudge firing and compaction's own
+    // recovery target agree — see budget.ts's own BudgetTrackerOptions doc
+    // comment.
+    const budgetTracker = new BudgetTracker({ budgetTokens: config.contextBudgetTokens ?? 8000 });
+    const compactor = new Compactor({ budgetTokens: config.contextBudgetTokens ?? 8000, softThreshold: budgetTracker.softThreshold, tailMessages });
     const rules = loadRules(config);
     const gate = new Gate(rules, config.approver ?? options.approver ?? new ConsoleApprover());
     // No explicit isSafeTool: fall back to each called tool's own `safe`
@@ -315,21 +323,21 @@ export async function runAgent(config, modelCall, userMessage, history = [], opt
         messages.push(message);
         newMessages.push(message);
     }
-    const reflow = new Reflow({
+    const recovery = new Recovery({
         onPromptTooLong: async (currentMessages) => {
             // newMessages (this turn's own content — not durably stored
-            // anywhere else yet) must never be handed to ContextClip at all.
+            // anywhere else yet) must never be handed to the compactor at all.
             // An earlier version of this reconciliation tried to recover
-            // newMessages *after* compaction by reusing whatever ContextClip's
-            // synthetic head contained — that's unsound: ContextClip's cheap
+            // newMessages *after* compaction by reusing whatever the
+            // compactor's synthetic head contained — that's unsound: its cheap
             // "drain" stage doesn't produce a head at all, it just deletes old
             // messages outright, trusting there's a durable copy elsewhere.
             // That trust is only valid for the *prior* portion; only that
             // portion is safe to compact at all.
             const priorCount = currentMessages.length - newMessages.length;
             const priorPortion = currentMessages.slice(0, priorCount);
-            const result = await contextClip.recover(priorPortion.map(flattenForContextClip));
-            log({ type: 'reflow:recover', from: currentMessages.length, to: result.messages.length + newMessages.length });
+            const result = await compactor.recover(priorPortion.map(flattenForBudget));
+            log({ type: 'prompt:compaction', from: currentMessages.length, to: result.messages.length + newMessages.length });
             if (result.action === 'unchanged')
                 return currentMessages;
             // Same tail-preservation reuse as before, just scoped to
@@ -339,13 +347,13 @@ export async function runAgent(config, modelCall, userMessage, history = [], opt
             const structuredTail = priorPortion.slice(priorPortion.length - preservedTailCount);
             const newHead = result.messages.slice(0, result.messages.length - preservedTailCount);
             const recovered = [...newHead, ...structuredTail, ...newMessages];
-            // Reflow.call() only ever returns {value, recoveries, truncated} —
+            // Recovery.call() only ever returns {value, recoveries, truncated} —
             // it never hands back whatever `currentMessages` became after a
             // retry, so recovery would otherwise only ever affect the one
             // retried call. Reassigning the outer `messages` binding here (this
             // hook is the only place that has both the recovered array and a
             // reason to persist it) is what makes recovery durable: every
-            // subsequent contextClip.check() in this loop, and the `history`
+            // subsequent budgetTracker.check() in this loop, and the `history`
             // this function eventually returns, both see the compacted
             // conversation from this point on — not the original, ever-growing
             // one. newMessages itself needs no reconciliation at all — it was
@@ -413,13 +421,18 @@ export async function runAgent(config, modelCall, userMessage, history = [], opt
             log({ type: 'loop:max_turns', maxTurns });
             return { text, history: messages, newMessages, stopReason: 'max_turns' };
         }
-        const budget = contextClip.check(messages.map(flattenForContextClip));
-        log({ type: 'contextclip:check', ...budget });
+        const budget = budgetTracker.check(messages.map(flattenForBudget));
+        log({ type: 'budget:check', ...budget });
         if (budget.action === 'nudge' && budget.nudge)
             pushMessage(budget.nudge);
-        const { value: response, recoveries } = await reflow.call((msgs) => modelCall(msgs, systemPrompt, toolSchemas), messages);
-        if (recoveries.length > 0)
-            log({ type: 'reflow:recoveries', recoveries });
+        // recovery.call()'s own return also includes `recoveries` (which of
+        // its three failure modes fired this call) and `truncated` — not
+        // used here: prompt:compaction above already reports the one
+        // recovery type that's actually wired to a real hook (onPromptTooLong),
+        // and there's no second type yet to justify a second, more generic
+        // event just to aggregate it (see PromptCompactionEvent's own doc
+        // comment for the removed 'recovery:summary').
+        const { value: response } = await recovery.call((msgs) => modelCall(msgs, systemPrompt, toolSchemas), messages);
         // The model's full response — text and tool_use blocks alike, with
         // real ids — becomes this turn's assistant message verbatim. Every
         // tool_use block emitted here gets a matching tool_result pushed
@@ -464,7 +477,7 @@ export async function runAgent(config, modelCall, userMessage, history = [], opt
             // so it still needs a tool_result to answer it, same as any other.
             if (block.name === 'Skill' && skillGarden) {
                 const body = skillGarden.invoke(block.input.skill, block.input?.args);
-                log({ type: 'skillgarden:invoke', skill: block.input.skill });
+                log({ type: 'skill:loaded', skill: block.input.skill });
                 resultBlocks.push({ type: 'tool_result', tool_use_id: block.id, content: body });
                 continue;
             }

package/dist/core/session-store.d.ts

@@ -6,7 +6,7 @@ export interface SessionResult<T> {
      * This has to come from the caller explicitly (runAgent's own
      * RunAgentResult.newMessages) rather than being inferred by diffing a
      * returned `history` against what withSession loaded: that only works
-     * if history only ever grows, which isn't true once ContextClip
+     * if history only ever grows, which isn't true once compaction.ts's own
      * recovery can shrink/rewrite it mid-turn — see RunAgentResult's own
      * doc comment for the full reasoning. */
     newMessages: Message[];

package/dist/core/vector-index.js

@@ -3,7 +3,7 @@
 // plus cosine-similarity search. Real technique (the "hashing trick"),
 // just not a learned one — good enough to prove the retrieval mechanics
 // end-to-end without wiring up a live embedding model. Swap embed() for a
-// real one and VectorIndex works unchanged: same seam as ContextClip's
+// real one and VectorIndex works unchanged: same seam as compaction.ts's
 // Summarizer or ActAuth's Approver — a working default the rest of the
 // pipeline can be built and tested against.
 // Higher dimensions mean fewer hash collisions between unrelated tokens,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopengine",
-  "version": "0.0.20",
+  "version": "0.0.21",
   "type": "module",
   "description": "Runtime for tool-using AI agents with a transparent ReAct loop.",
   "license": "MIT",
@@ -48,6 +48,8 @@
     "dist/core/gateway-tools.d.ts",
     "dist/core/system-tools",
     "core/system-skills",
+    "protocol/loop-event.schema.json",
+    "PROTOCOL.md",
     "LICENSE"
   ],
   "scripts": {
@@ -59,11 +61,9 @@
   "dependencies": {
     "@anthropic-ai/sdk": "^0.116.0",
     "actauth": "^0.0.7",
-    "contextclip": "^0.0.1",
     "ioredis": "^6.0.0",
     "mcpplug": "^0.0.1",
     "openai": "^7.4.0",
-    "reflowkit": "^0.0.1",
     "sessionknit": "^0.0.2",
     "skillgarden": "^0.0.5",
     "toollane": "^0.0.1",

package/protocol/loop-event.schema.json

@@ -0,0 +1,257 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://loopengine.co/protocol/loop-event.schema.json",
+  "title": "LoopEvent",
+  "description": "The full wire vocabulary of a loopengine turn — mirrors core/loop-events.ts exactly. One object per event; `type` is both the JSON discriminant and, on the SSE transport, the literal `event:` field name. See /PROTOCOL.md for transport bindings and stability guarantees.",
+  "oneOf": [
+    { "$ref": "#/$defs/budgetCheck" },
+    { "$ref": "#/$defs/promptCompaction" },
+    { "$ref": "#/$defs/assistantText" },
+    { "$ref": "#/$defs/actauthDecision" },
+    { "$ref": "#/$defs/toolStarted" },
+    { "$ref": "#/$defs/toolResult" },
+    { "$ref": "#/$defs/toollaneResult" },
+    { "$ref": "#/$defs/skillLoad" },
+    { "$ref": "#/$defs/loopSkipped" },
+    { "$ref": "#/$defs/loopMaxTurns" },
+    { "$ref": "#/$defs/loopDenied" },
+    { "$ref": "#/$defs/loopDone" },
+    { "$ref": "#/$defs/session" },
+    { "$ref": "#/$defs/approvalPending" },
+    { "$ref": "#/$defs/questionPending" },
+    { "$ref": "#/$defs/done" },
+    { "$ref": "#/$defs/error" }
+  ],
+  "$defs": {
+    "scope": {
+      "type": "object",
+      "description": "ActAuth's own Scope — which rules apply.",
+      "required": ["tenant", "environment", "agent"],
+      "properties": {
+        "tenant": { "type": "string" },
+        "environment": { "type": "string" },
+        "agent": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+
+    "budgetCheck": {
+      "type": "object",
+      "description": "Engine. Read-only context-budget check, run once per model call.",
+      "required": ["type", "action", "usedTokens", "budgetTokens", "ratio"],
+      "properties": {
+        "type": { "const": "budget:check" },
+        "action": { "enum": ["ok", "nudge", "over_hard_limit"] },
+        "usedTokens": { "type": "number" },
+        "budgetTokens": { "type": "number" },
+        "ratio": { "type": "number" },
+        "nudge": {
+          "type": "object",
+          "description": "Present only when action is 'nudge'.",
+          "required": ["role", "content"],
+          "properties": { "role": { "type": "string" }, "content": { "type": "string" } }
+        }
+      },
+      "additionalProperties": false
+    },
+
+    "promptCompaction": {
+      "type": "object",
+      "description": "Engine. The prompt was rejected as too long, so compaction.ts's own recovery kicked in. from/to are message-array lengths, not token counts. The only recovery type with a dedicated event today — recovery.ts's other two failure modes (media-too-large, truncated output) have no hook wired up in run-agent.ts yet, so neither can currently fire.",
+      "required": ["type", "from", "to"],
+      "properties": {
+        "type": { "const": "prompt:compaction" },
+        "from": { "type": "number" },
+        "to": { "type": "number" }
+      },
+      "additionalProperties": false
+    },
+
+    "assistantText": {
+      "type": "object",
+      "description": "Engine. The model's own preamble alongside a tool_use request — the only live glimpse of assistant text before the turn's final answer.",
+      "required": ["type", "text"],
+      "properties": {
+        "type": { "const": "assistant:text" },
+        "text": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+
+    "actauthDecision": {
+      "type": "object",
+      "description": "Engine. One ActAuth Gate.evaluate() outcome per requested tool call. decision:'allow' can still mean a human was asked and said yes — see approval:pending for the live ask itself.",
+      "required": ["type", "tool", "decision", "reason"],
+      "properties": {
+        "type": { "const": "actauth:decision" },
+        "tool": { "type": "string" },
+        "decision": { "enum": ["allow", "ask", "deny"] },
+        "reason": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+
+    "toolStarted": {
+      "type": "object",
+      "description": "Engine. Fired the instant a call is decided, before it runs. Matched to its later tool:result by id.",
+      "required": ["type", "id", "tool", "args", "detailText"],
+      "properties": {
+        "type": { "const": "tool:started" },
+        "id": { "type": "string" },
+        "tool": { "type": "string" },
+        "args": { "type": "object" },
+        "detailText": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+
+    "toolResult": {
+      "type": "object",
+      "description": "Engine. A tool call's resolution — auto-allowed, interactively approved, denied, or skipped alike. args/detailText are omitted on some denied/skipped paths.",
+      "required": ["type", "id", "tool", "statusText"],
+      "properties": {
+        "type": { "const": "tool:result" },
+        "id": { "type": "string" },
+        "tool": { "type": "string" },
+        "args": { "type": "object" },
+        "detailText": { "type": "string" },
+        "statusText": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+
+    "toollaneResult": {
+      "type": "object",
+      "description": "Engine. ToolLane's own raw fulfil/reject outcome, logged alongside (not instead of) tool:result.",
+      "required": ["type", "name", "summary"],
+      "properties": {
+        "type": { "const": "toollane:result" },
+        "name": { "type": "string" },
+        "summary": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+
+    "skillLoad": {
+      "type": "object",
+      "description": "Engine. A Skill tool_use block was resolved to a real skill body via SkillGarden's own lazy load. Not gated by ActAuth — Skill invocation isn't a real tool call.",
+      "required": ["type", "skill"],
+      "properties": {
+        "type": { "const": "skill:loaded" },
+        "skill": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+
+    "loopSkipped": {
+      "type": "object",
+      "description": "Engine. An approved call never ran because a sibling call in the same batch was denied — the whole batch cancels together.",
+      "required": ["type", "name", "deniedTools"],
+      "properties": {
+        "type": { "const": "loop:skipped" },
+        "name": { "type": "string" },
+        "deniedTools": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    },
+
+    "loopMaxTurns": {
+      "type": "object",
+      "description": "Engine. Hit config.maxTurns without the model producing a final answer. Terminal for the turn — see 'done'.",
+      "required": ["type", "maxTurns"],
+      "properties": {
+        "type": { "const": "loop:max_turns" },
+        "maxTurns": { "type": "number" }
+      },
+      "additionalProperties": false
+    },
+
+    "loopDenied": {
+      "type": "object",
+      "description": "Engine. A human denied at least one requested tool call this turn — the whole turn stops right there. Terminal for the turn — see 'done'.",
+      "required": ["type", "deniedTools"],
+      "properties": {
+        "type": { "const": "loop:denied" },
+        "deniedTools": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    },
+
+    "loopDone": {
+      "type": "object",
+      "description": "Engine. A genuine finish — the model produced text with no more tool_use blocks. Terminal for the turn — see 'done'.",
+      "required": ["type", "text"],
+      "properties": {
+        "type": { "const": "loop:done" },
+        "text": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+
+    "session": {
+      "type": "object",
+      "description": "Adapter. First event of every streamed turn — echoes back which session id this turn used.",
+      "required": ["type", "sessionId"],
+      "properties": {
+        "type": { "const": "session" },
+        "sessionId": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+
+    "approvalPending": {
+      "type": "object",
+      "description": "Adapter. A tool call needs a live human 'ask' decision. Resolve via POST /approvals/:id/approve or /deny.",
+      "required": ["type", "id", "tool", "args", "scope", "reason", "requestedAt"],
+      "properties": {
+        "type": { "const": "approval:pending" },
+        "id": { "type": "string" },
+        "tool": { "type": "string" },
+        "args": { "type": "object" },
+        "scope": { "$ref": "#/$defs/scope" },
+        "reason": { "type": "string" },
+        "requestedAt": { "type": "string", "format": "date-time" }
+      },
+      "additionalProperties": false
+    },
+
+    "questionPending": {
+      "type": "object",
+      "description": "Adapter. The system ask_user tool raised a genuinely ambiguous question. Resolve via POST /questions/:id/answer.",
+      "required": ["type", "id", "question", "agent", "requestedAt"],
+      "properties": {
+        "type": { "const": "question:pending" },
+        "id": { "type": "string" },
+        "question": { "type": "string" },
+        "options": { "type": "array", "items": { "type": "string" } },
+        "agent": { "type": "string" },
+        "sessionId": { "type": "string" },
+        "requestedAt": { "type": "string", "format": "date-time" }
+      },
+      "additionalProperties": false
+    },
+
+    "done": {
+      "type": "object",
+      "description": "Adapter. The turn is over — covers loop:done, loop:max_turns, and loop:denied alike. The one event every consumer can treat as 'nothing more is coming'.",
+      "required": ["type", "text"],
+      "properties": {
+        "type": { "const": "done" },
+        "text": { "type": "string" },
+        "stopReason": { "enum": ["max_turns", "denied"] }
+      },
+      "additionalProperties": false
+    },
+
+    "error": {
+      "type": "object",
+      "description": "Adapter. Something failed after the response was already committed — surfaced in-band since it's too late for an HTTP status code.",
+      "required": ["type", "error"],
+      "properties": {
+        "type": { "const": "error" },
+        "error": { "type": "string" }
+      },
+      "additionalProperties": false
+    }
+  }
+}