loopengine 0.0.10 → 0.0.16

package/README.md

@@ -2,40 +2,35 @@
 
 [![CI](https://github.com/evanyan22/loopengine/actions/workflows/ci.yml/badge.svg)](https://github.com/evanyan22/loopengine/actions/workflows/ci.yml)
 
-LoopEngine is a runtime for defining and running multiple AI agents through a
-transparent ReAct loop. Write an agent as a plain config object — persona,
-tools, permission rules — and run it over the CLI, an HTTP API, or both. No
-chain DSL, no hidden control flow: `run-agent.ts` is a single readable
-function you can step through top to bottom.
+LoopEngine is a runtime for building AI agents: a persona, a set of tools,
+and permission rules, run through a transparent ReAct loop. No chain DSL,
+no hidden control flow — `run-agent.ts` is a single function you can read
+top to bottom. Run agents over a CLI, an HTTP API, or both.
+
+Once you define an agent, the loop turns it into something you can put in
+front of real users or real systems:
+
+- **Callable over CLI or HTTP** — a script you run locally, or a real
+  service other apps can hit.
+- **Does real work, safely** — tools can hit a database, send emails, call
+  GitHub/Slack, anything with an `execute` function. Permission rules gate
+  what happens without a human: safe reads auto-run, risky actions (a
+  refund, a send) get approval or are denied outright, so you can wire up
+  powerful tools without trusting the model blindly.
+- **Remembers** — conversations persist across requests, so a caller can
+  send one message, get a reply, and continue later.
+- **Multi-tenant out of the box** — the same deployed agent can serve
+  different customers/orgs with different permission levels, with no
+  forking required.
+- **Composable into bigger agents** — drop one agent's folder under
+  another's `subagents/` and it becomes a tool the parent can delegate
+  to, own tools/rules/loop intact. No chain DSL for orchestration either:
+  the parent's model just decides when to call it, like any other tool.
+
+So the payoff: you write one `AgentConfig`, and get a deployable,
+persistent, permission-safe service — not just a prompt-and-response demo.
 
-It's built on six small, independently-published packages that each solve
-one piece of the agent-loop problem:
-
-| Package | Responsibility |
-|---|---|
-| [`actauth`](https://www.npmjs.com/package/actauth) | Rule-based permission gating (allow/ask/deny) with human-approval hooks |
-| [`contextclip`](https://www.npmjs.com/package/contextclip) | Context-window budget tracking with staged recovery |
-| [`reflowkit`](https://www.npmjs.com/package/reflowkit) | Retries prompt-too-long / truncated-output failures |
-| [`sessionknit`](https://www.npmjs.com/package/sessionknit) | Durable, DAG-shaped session log with crash-interruption detection |
-| [`skillgarden`](https://www.npmjs.com/package/skillgarden) | `SKILL.md`-based skill discovery and lazy loading |
-| [`toollane`](https://www.npmjs.com/package/toollane) | Schedules approved tool calls into parallel/solo execution lanes |
-
-`run-agent.ts` wires the first five together — `sessionknit` sits one layer
-out, in `session-store.ts`, since it persists what `run-agent.ts` produces
-rather than participating in the loop itself. Everything else in this repo
-— agent definitions, channel adapters — is built on top of those.
-
-A seventh package, [`mcpplug`](https://www.npmjs.com/package/mcpplug), sits
-one layer further out still: it's not part of the loop either, just a
-`ToolSource` an agent's own config can draw from — `loadTools()` returns
-`ToolDefinition[]`, the exact shape `AgentConfig.tools` already expects, so
-its output merges straight in with no adapter code. See "External tool
-gateways" below.
-
-## Creating a new project
-
-The fastest way to get a running agent server, in your own repo, is
-[`create-loopengine`](https://www.npmjs.com/package/create-loopengine):
+## Quick start
 
 ```bash
 npx create-loopengine@latest my-agents
@@ -45,466 +40,354 @@ cp .env.example .env   # fill in ANTHROPIC_API_KEY
 npm run dev             # HTTP server on :8787
 ```
 
-That scaffolds a real, standalone project — its own `package.json`
-depending on `loopengine` (not a clone of this repo), an HTTP + CLI
-adapter, and one starter agent — rather than a bare library import. `npm
-install loopengine` alone (below) only gets you the library; the server,
-adapters, and a runnable example are deliberately not part of that
-package, which is the gap `create-loopengine` fills. See
-[`create-loopengine`'s own README](https://github.com/evanyan22/create-loopengine)
-for what the generated project looks like.
+This scaffolds a standalone project — its own repo, with `loopengine` as
+a dependency, a starter agent, and CLI + HTTP adapters already wired up.
+That's the intended way to use LoopEngine: an independent project you own
+and build agents in, not a library you import into an existing app.
 
-## Using loopengine as a library
-
-This repo is two things in one: a small library (the loop itself) and a
-reference app built on top of it (demo agents, a CLI, an HTTP server). Only
-the library half ships to npm:
+### Define your first agent
 
 ```bash
-npm install loopengine
+npx loopengine add-agent weather-agent
+# -> Created agents/weather-agent/index.ts
 ```
 
-`actauth`, `contextclip`, `reflowkit`, `toollane`, `skillgarden`, and the
-rest are regular dependencies of `loopengine` itself — installing it alone
-already pulls them into `node_modules`, fully resolvable for both imports
-and TypeScript types. Install one of them directly only if you want to use
-it standalone, outside `runAgent` (e.g. just `toollane`'s parallel/solo
-scheduling in your own loop).
-
-```ts
-import { runAgent, type AgentConfig, type ToolDefinition } from 'loopengine'
+That's the fastest way to start: it generates `agents/<name>/index.ts`
+with a working `AgentConfig` stub, so you don't have to memorize the
+folder shape by hand. Or write it yourself — an agent is just an
+`AgentConfig`: `name`, `systemPrompt`, `tools`, `rules`, and a `model`.
+Drop it in a folder under `agents/` — `agents/<name>/index.ts` — and it's
+picked up automatically, no registry to edit, no import to add.
 
-const getWeather: ToolDefinition = {
-  name: 'get_weather',
-  description: 'Look up the weather for a city',
-  input_schema: { type: 'object', properties: { city: { type: 'string' } }, required: ['city'] },
-  execute: async (input) => `Sunny in ${input.city}`,
-}
+Most fields don't even need to be written out — they default to a
+conventional path under the agent's own folder:
 
-const config: AgentConfig = {
-  name: 'weather-agent',
-  systemPrompt: 'You answer questions about the weather.',
-  tools: [getWeather],
-  rules: [{ scopePattern: 'default/production/weather-agent', tool: 'get_weather', decision: 'allow' }],
-  defaultDecision: 'ask',
-}
+| Field | Defaults to |
+| --- | --- |
+| `rules` | `agents/<name>/actauth.yml` (missing → deny everything) |
+| `tools` | `agents/<name>/tools/index.ts`'s exported `tools` (missing → no tools) |
+| `skillsDirs` | `agents/<name>/skills` (missing → no skills) |
 
-// bring your own ModelCall, or use the one below
-const result = await runAgent(config, myModelCall, "What's the weather in Boston?", [])
-console.log(result.text)
-```
+There's no `subagents` field to omit — `agents/<name>/subagents/*` is its
+own folder convention, always merged into `tools` on top of whatever the
+table above resolves to. See "Subagents" below.
 
-The full exported surface: `runAgent`, `AgentConfig`/`ToolSchema`/`ToolDefinition`,
-`FileSessionStore`/`RedisSessionStore`/`createSessionStore`, `VectorIndex`/
-`embed`/`cosineSimilarity` (for RAG — see below), `discoverAgents` (scans a
-directory for `config`/`createModelCall` modules and builds a name → entry
-map, keyed by `AgentConfig.name` — see `agent-registry.ts` for the ~15-line
-wrapper this repo's own adapters use), and `createAnthropicModelCall`/
-`createOpenAIModelCall`/`createDeepSeekModelCall` (real, ready-to-use
-`ModelCall`s). See `index.ts` for the exact list.
-
-**Not** part of the package: `agents/*.ts` (this repo's own demo agents),
-`agent-registry.ts` (this repo's own name → config lookup table, built on
-`discoverAgents` — build your own the same way), `adapters/cli.ts`/
-`adapters/http.ts` (one specific CLI/HTTP wiring choice, not imposed on
-every consumer), and the `Dockerfile`. Everything below this point
-describes that reference app — read it as a worked example of what to
-build with the library, not as library API itself.
+`rules` is how you gate what a tool can do without approval — see
+"Tool permission and multi-tenancy" below.
 
-## Quick start
-
-```bash
-npm install
-npx tsx agents/file-agent.ts             # run the file-summarizer demo agent
-npx tsx agents/customer-service-agent.ts # run the customer-service demo agent
-npx tsx agents/rag-agent.ts              # run the retrieval-augmented demo agent
-```
-
-All demo agents use a **simulated** model call (no `ANTHROPIC_API_KEY` is
-wired up) — see "Wiring a real model" below.
-
-## Defining your own agent
-
-An agent is an `AgentConfig` (`agent-config.ts`): a name, a system prompt, a
-list of tools, and ActAuth permission rules.
+The simplest possible agent, `agents/weather-agent/index.ts` — `tools`,
+`rules`, and `skillsDirs` all omitted, so they default to
+`agents/weather-agent/tools/`, `actauth.yml`, and `skills/`:
 
 ```ts
-import type { AgentConfig } from './agent-config.js'
+import type { AgentConfig } from '../../agent-config.js'
 
 export const config: AgentConfig = {
-  name: 'my-agent',
-  systemPrompt: 'You are ...',
-  tools: [
-    {
-      name: 'do_thing',
-      description: 'What the model sees when deciding to call this',
-      input_schema: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
-      execute: async (input) => {
-        // real implementation — DB call, HTTP request, whatever
-        return { ok: true }
-      },
-    },
-  ],
-  rules: [
-    { scopePattern: 'default/production/my-agent', tool: 'do_thing', decision: 'allow' },
-  ],
-  defaultDecision: 'ask', // anything not covered by a rule requires approval
+  name: 'weather-agent',
+  systemPrompt: 'You answer questions about the weather.',
+  model: { provider: 'anthropic', model: 'claude-sonnet-5' }, // reads ANTHROPIC_API_KEY
 }
 ```
 
-`agents/file-agent.ts` and `agents/customer-service-agent.ts` are two complete, working
-examples — same `runAgent` loop, entirely different personas and tools.
-
-A file exporting `config` and `createModelCall` and saved into `agents/` is
-runnable through both adapters immediately — `agent-registry.ts` finds it
-automatically (by `AgentConfig.name`, not the filename) at startup.
-Nothing to edit, no import to add, no adapter change.
+See `agents/customer-service/` and `agents/file-agent/` for complete,
+working examples.
+
+## Core concepts
+
+### 1. The Loop
+
+`run-agent.ts` is the whole engine — a single, readable ReAct loop with no
+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).
+3. Approved calls execute and their results feed back into the
+   conversation.
+4. Repeat from step 1 — until the model stops requesting tools
+   (`end_turn`) or `AgentConfig.maxTurns` (default 25) is hit, which ends
+   the turn with `RunAgentResult.stopReason: 'max_turns'`, a real result
+   rather than a thrown error.
+
+`runAgent` itself does no I/O — callers own conversation history and the
+model call — which is what lets the same loop serve a one-shot CLI call,
+a long-lived HTTP chat session, and a fully simulated test, unchanged.
+
+### 2. Agents — convention over configuration
+
+Beyond the `AgentConfig` shape and folder convention shown in "Define
+your first agent" above, the discovery mechanism is what makes this
+convention-over-configuration: `discoverAgents` scans `agents/` at
+startup, keyed by each module's own `AgentConfig.name` — not the
+filename or folder name — and builds the name → config lookup every
+adapter uses. Nothing to register by hand; a module that exports neither
+`config` nor a way to build a model call fails loudly at startup instead
+of silently not showing up.
+
+### 3. Skills and tools: agent-specific vs. global
+
+Both skills and tools follow the same rule: **default to agent-specific,
+promote to global only once something is genuinely shared.**
+
+- **Agent-specific** (the default) — lives under that agent's own folder,
+  seen only by that agent:
+  ```
+  agents/<name>/skills/<skill>/SKILL.md
+  agents/<name>/tools/<tool>.ts
+  ```
+- **Global** — lives at the repo root, seen by every agent that opts in:
+  ```
+  skills/<skill>/SKILL.md      # pointed at by any agent whose skillsDirs includes it
+  tools/<tool>.ts              # imported explicitly into any agent's tools array
+  ```
+
+Skills are discovered via `AgentConfig.skillsDirs` (an array of
+directories, `SKILL.md`-based: a short description stays in context, the
+full body loads only when the model invokes it). Tools have no
+auto-discovery — an agent's `tools` array just imports whichever tool
+files it wants, agent-specific or global.
+
+Both root directories (`tools/`, `skills/`) are empty today — every skill
+and tool in this repo is agent-specific. Move something there only when a
+second agent actually needs the exact same one, not because it feels
+reusable in theory.
+
+**Opting an agent into a global skill or tool** is explicit either way —
+nothing scans the root for you:
 
-## Retrieval (RAG)
+```ts
+// Global skill: add the root path alongside the agent's own
+skillsDirs: ['agents/my-agent/skills', 'skills']
 
-RAG is just another tool — the model decides when to call it, `run-agent.ts`
-doesn't know or care that "executing" this particular tool means a vector
-search instead of a plain HTTP call:
+// Global tool: tools has no auto-discovery, so import it and merge it
+// into the agent's own array by hand
+import { sharedTool } from '../../tools/shared-tool.js'
+import { tools as ownTools } from './tools/index.js'
 
-```ts
-const searchDocs: ToolDefinition = {
-  name: 'search_docs',
-  description: 'Search the knowledge base for relevant passages',
-  input_schema: { type: 'object', properties: { query: { type: 'string' } }, required: ['query'] },
-  execute: async (input) => {
-    const hits = index.search(input.query as string, 3) // top-3 chunks
-    return hits.map((h) => h.text).join('\n\n')
-  },
-}
+tools: [...ownTools, sharedTool]
 ```
 
-`agents/rag-agent.ts` is a complete example, backed by `vector-index.ts` — a
-small, dependency-free in-memory vector index (feature-hashing embeddings,
-cosine-similarity search) good enough to prove the retrieval mechanics
-end-to-end without wiring up a real embedding API. Swap `embed()` for a real
-embedding model, or swap `VectorIndex` for a real vector DB client, and the
-`search_docs` tool works unchanged — same "host provides the real
-implementation, the package proves the pipeline" pattern as ContextClip's
-`Summarizer` or ActAuth's `Approver`. The retrieved text comes back as an
-ordinary tool result, subject to the same ActAuth gating, ToolLane
-scheduling, and ContextClip budget tracking as any other tool call.
-
-## External tool gateways
-
-A hand-written tool needs an `execute` function you write yourself; an
-external SaaS action (list GitHub repos, send a Slack message) needs
-someone to own that vendor's auth. Connecting straight to a vendor's own
-MCP server means owning its OAuth flow (authorization code, PKCE, token
-storage/refresh) yourself, repeated per vendor. Routing through a gateway
-like [Composio](https://composio.dev) avoids that — it already holds the
-OAuth relationship with 1000+ apps — and [`mcpplug`](https://www.npmjs.com/package/mcpplug)
-wraps that gateway behind the same `ToolDefinition` shape as everything
-else:
+Tools don't have to be hand-written either. For SaaS actions (GitHub,
+Slack, etc.) where you'd rather not own the vendor's OAuth flow yourself,
+[`mcpplug`](https://www.npmjs.com/package/mcpplug) connects through
+[Composio](https://composio.dev), which already holds the OAuth
+relationship with 1000+ apps, and returns tools in the same
+`ToolDefinition` shape — so they drop into `tools` right alongside your
+own:
 
 ```ts
 import { connectComposioSource } from 'mcpplug'
 
-// Resolved once, at module-eval time — not per runAgent() call. A gateway
-// connection is exactly the kind of setup cost runAgent() shouldn't pay on
-// every turn; see agents/file-agent.ts for the working example this is
-// drawn from.
 const composioTools = await connectComposioSource('composio', {
   slugs: ['GITHUB_LIST_REPOSITORIES_FOR_THE_AUTHENTICATED_USER'],
 }).then((source) => source.loadTools())
 
 const config: AgentConfig = {
   name: 'my-agent',
-  systemPrompt: 'You are ...',
   tools: [...handWrittenTools, ...composioTools],
-  rules: [
-    // mcpplug namespaces each tool `${sourceName}_${slug}` — falls
-    // through to defaultDecision unless a rule names it explicitly.
-    { scopePattern: 'default/production/my-agent', tool: 'composio_GITHUB_LIST_REPOSITORIES_FOR_THE_AUTHENTICATED_USER', decision: 'allow' },
-  ],
+  rules: [{ scopePattern: 'default/production/my-agent', tool: 'composio_GITHUB_LIST_REPOSITORIES_FOR_THE_AUTHENTICATED_USER', decision: 'allow' }],
   defaultDecision: 'ask',
 }
 ```
 
-Same ActAuth gating, ToolLane scheduling, and ContextClip budget tracking
-as any other tool call — `runAgent` has no idea one `execute` shells out
-through Composio instead of touching the filesystem or a vector index.
-`agents/file-agent.ts` is a complete, working example, verified end-to-end
-against a real linked GitHub account. `slugs` is explicit, not
-auto-discovered — an agent should only see the Composio actions its own
-config actually lists; find them with the `composio` CLI's
-`composio tools list <toolkit>` or `composio search "<use case>"`.
+Either kind of tool goes through the same permission gating, parallel
+scheduling, and context-budget tracking. See `agents/file-agent/index.ts`
+for a working example.
 
-## Running an agent
+### 4. Subagents — an agent as another agent's tool
 
-**CLI:**
+Drop a folder under `agents/<name>/subagents/<child>/` and `child` becomes
+one of `name`'s tools automatically — no import, no `AgentConfig.tools`
+edit, nothing to register by hand:
 
-```bash
-npx tsx adapters/cli.ts --agent customer-service --session s1 "order A-1001 arrived broken"
+```
+agents/support-orchestrator/
+  index.ts                        # the orchestrator's own AgentConfig
+  subagents/
+    billing-agent/index.ts        # a full AgentConfig, same shape as a top-level agent
+    refunds-agent/index.ts
 ```
 
-**HTTP:**
+Scaffold one directly:
 
 ```bash
-npx tsx adapters/http.ts
-curl -X POST localhost:8787/agents/customer-service/messages \
-  -H 'content-type: application/json' \
-  -d '{"customerEmail":"a@example.com","message":"order A-1001 arrived broken"}'
+npx loopengine add-subagent support-orchestrator billing-agent
+# -> Created agents/support-orchestrator/subagents/billing-agent/index.ts
 ```
 
-`customerEmail` is specific to `customer-service` — it defines its own
-`AgentConfig.sessionIdFor` (see "Sessions and multi-tenancy" below). Other
-agents take a plain `sessionId` field instead — and it's optional: omit it
-for a fresh, one-off session (a generated id, echoed back in the response
-as `sessionId` so you can pass it in explicitly to continue that same
-conversation on a later request):
+A subagent is a normal `AgentConfig` plus one required field —
+`toolDescription`, the text the *parent's* model reads to decide when to
+delegate to it (its own `systemPrompt` is instructions for itself, not a
+pitch to a caller deciding whether to invoke it):
 
-```bash
-curl -X POST localhost:8787/agents/file-agent/messages \
-  -H 'content-type: application/json' \
-  -d '{"message":"Summarize a.txt and b.txt into summary.txt."}'
+```ts
+export const config: AgentConfig = {
+  name: 'billing-agent',
+  systemPrompt: 'You answer billing questions.',
+  toolDescription: 'Call this for any billing-related question.',
+  model: { provider: 'anthropic', model: 'claude-sonnet-5' },
+}
 ```
 
-`customer-service` is the exception here too — a request with no
-`customerEmail` is a genuine validation error (`400`), not "start me an
-anonymous session," since `customerEmail` is a real, meaningful identity
-for that agent, not an arbitrary key.
+Calling that tool runs the subagent's whole ReAct loop — its own tools,
+rules, permissions — to completion, and only its final text comes back;
+the parent never sees the subagent's turns or tool calls. Orchestration
+needs no separate concept on top of this: an "orchestrator" is just an
+agent whose tools happen to be other agents, and the model decides which
+to call, in what order, the same as any other tool — no chain DSL.
 
-**HTTP, streamed:** same request, `/stream` suffix, one Server-Sent Event per
-loop step instead of a single response after the whole thing finishes —
-a `session` event first (announcing whatever `sessionId` got used, generated
-or not), then `contextclip:check`, `actauth:decision`, `toollane:result`,
-..., a final `done` with the answer:
+Subagents nest — a subagent's own `subagents/` folder works the same way,
+one level down, addressed by joining names with `/`:
 
 ```bash
-curl -N -X POST localhost:8787/agents/customer-service/messages/stream \
-  -H 'content-type: application/json' \
-  -d '{"customerEmail":"a@example.com","message":"order A-1001 arrived broken"}'
+npx loopengine add-subagent support-orchestrator/billing-agent disputes-agent
 ```
 
-Both adapters are thin: they own request parsing and session persistence,
-and call the same `runAgent(config, modelCall, message, history)` underneath.
-`runAgent` itself does no I/O — callers own conversation history, which is
-what lets it serve a one-shot CLI call and a long-lived chat session with no
-code difference. The streaming route isn't a separate code path through
-`runAgent` either — it forwards the same `onEvent` hook the non-streaming
-route just discards, over SSE instead of into a log. What this streams is
-loop *steps* (tool calls, permission decisions, budget checks), not model
-output tokens — no `ModelCall` implementation here (fake or
-`createAnthropicModelCall`) streams partial text from the model itself, so
-there's nothing at the token level to forward yet.
-
-## Sessions and multi-tenancy
-
-`session-store.ts` exposes one method, `withSession(sessionId, fn)`, that
-resumes history, runs `fn` **exclusively** for that session, and appends
-whatever new messages `fn` produced — this is what stops two concurrent
-requests for the same conversation from racing on read-modify-write.
-
-History itself is a [`sessionknit`](https://www.npmjs.com/package/sessionknit)
-log, not a flat file rewritten whole on every turn: each message is one
-entry in an append-only, parent-linked chain, so a turn only ever appends,
-never rewrites what's already durable. That buys two things a flat
-rewrite can't:
-
-- **Non-blocking, debounced writes** instead of a full read-modify-write of
-  the entire session every turn.
-- **Interruption detection.** `run-agent.ts` pushes the assistant's full
-  response — tool_use blocks included — as one message before any tool
-  runs, then one message bundling every tool_result once they've all
-  settled. If the process dies in that window, the next `resume()` sees an
-  assistant message with an unanswered tool_use block, flags the session
-  as resumed-after-interruption, and injects a note into context saying so
-  — instead of silently resending an incomplete turn as if it were clean.
-
-Two implementations, same `SessionStore` interface:
-
-- `FileSessionStore` — one JSONL entry log per session under `.sessions/`,
-  locked in-process. Fine for local dev and the CLI.
-- `RedisSessionStore` — same log shape (a Redis list of entries, one
-  `RPUSH` per append), with a real distributed lock, safe across multiple
-  server instances. The lock renews itself (`lockTtlMs / 3` by default)
-  for as long as a turn runs, instead of a flat TTL that a long turn (a
-  real model call plus several tool round-trips) could outlast — if
-  renewal ever confirms the lock was lost anyway (not just a failed
-  renewal attempt — a network blip there isn't proof of loss), the turn's
-  result is rejected rather than silently returned as if mutual exclusion
-  held the whole time.
-
-`createSessionStore()` picks between them based on `REDIS_URL` — set it and
-you get Redis, otherwise it falls back to the file store. Either way,
-turn-level exclusivity (no two concurrent turns for the same session
-interleaving) is still this module's job, not SessionKnit's — SessionKnit's
-own topology repair (reattaching sibling branches under a shared
-`parentId`) is a defensive read-side repair for crash/corruption recovery,
-not something normal operation exercises. `run-agent.ts` bundles a whole
-turn's `tool_use`/`tool_result` blocks into one message each, and
-`withSession` appends new messages sequentially, so even a turn with
-several parallel tool calls only ever produces a linear chain in the
-durable log — not races between two full concurrent turns, which is what
-the lock above actually prevents.
-
-Session-key derivation is `AgentConfig.sessionIdFor(body)` — deliberately
-not the HTTP adapter's call, since what counts as "one conversation" is
-business logic specific to what the agent is for, not a transport concern.
-`customer-service-agent.ts` defines its own, hashing `customerEmail` so raw
-addresses never end up in storage keys — different customers can never
-read or write each other's history, and concurrent messages from the same
-customer are serialized rather than dropped. A missing `customerEmail` is a
-real validation failure for that agent (`400`), not something to paper over.
-
-An agent that doesn't define `sessionIdFor` falls back to a plain
-client-supplied `sessionId` field (`adapters/http.ts`'s
-`defaultSessionIdFor`) — the same shape `adapters/cli.ts`'s `--session`
-flag already uses — and if that's missing too, one gets generated rather
-than the request being rejected, mirroring what omitting `--session` now
-does for the CLI: a fresh, isolated, one-off session rather than an error
-or (worse) a shared bucket every untagged caller collides into. The
-generated id comes back in the response (`sessionId` in the JSON body, a
-`session` SSE event first for the streamed route) so a caller that wants to
-continue that exact conversation can pass it in explicitly next time.
-
-`SessionStore` itself is agent-agnostic — nothing in `session-store.ts` or
-`sessionknit` knows which agent is calling `withSession`, so both adapters
-namespace the *actual* key by agent name before it ever reaches
-`SessionStore`: `` `${agentName}:${sessionIdFor(...)}` `` in
-`adapters/http.ts`, `` `${agent}:${session}` `` in `adapters/cli.ts`.
-Without that, two different agents given the same session identifier (a
-client reusing one `sessionId`/`--session` value across agents, most
-likely) would read and write the exact same underlying log — one agent's
-tool calls and results spliced straight into another's conversation as if
-it had always been there.
-
-## Deployment
-
-```bash
-docker compose up --build
+A few things worth knowing before reaching for this:
+
+- **The call blocks.** Every tool call in the loop is awaited before the
+  next model turn, so a slow subagent blocks its parent's turn — and if
+  the parent is itself a subagent of another agent, that blocks too.
+  There's no background/async or streaming pattern here.
+- **Permissions don't inherit.** Each agent's own `actauth.yml` governs
+  only its own tools; delegating to a subagent neither grants nor
+  inherits permissions in either direction.
+- **`maxTurns` compounds.** A request that reaches a grandchild subagent
+  spends turns at every level (default 25 each) — a "simple" answer can
+  cost far more than any one agent's own turn budget suggests.
+
+### 5. Tool permission and multi-tenancy
+
+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).
+
+A real agent's rules live in `agents/<name>/actauth.yml`:
+
+```yaml
+default_decision: deny
+
+rules:
+  - name: weather-lookup-always-allowed
+    scope: "*/*"
+    tool: get_weather
+    decision: allow
 ```
 
-builds the HTTP adapter into a container (`Dockerfile`, multi-stage:
-`npm ci` + `tsc`, then a slim runtime image) and starts it alongside a Redis
-container (`docker-compose.yml`). For a real deployment, push the same
-image to any container platform (Cloud Run, Fargate, Fly.io) with `REDIS_URL`
-and any tool-specific secrets set as environment variables.
+`scope` is `tenant/environment` — `"*/*"` here means "every tenant, every
+environment." Rules are matched most-specific-scope-first, so an agent
+that needs different behavior per tenant just adds a more specific rule
+(e.g. `acme-corp/production`) alongside the wildcard fallback.
+
+That `scope` is what makes rules multi-tenant: the same agent can behave
+differently for different customers. `environment` is a deployment-wide
+setting (`LOOPENGINE_ENV`, default `production`). `tenant` is resolved per
+request via `AgentConfig.tenantFor?: (headers, body) => string |
+undefined` — from headers only, never the request body, since it feeds
+permission decisions directly. No `tenantFor` means every request is the
+`'default'` tenant.
+
+### 6. Sessions
+
+A session is one ongoing conversation. Message history persists between
+requests automatically — send a message, get a reply, come back later with
+the same `sessionId` and continue where you left off. Two storage backends,
+picked automatically: a local file store, or Redis if `REDIS_URL` is set
+(needed for multiple server instances).
+
+An agent can define `AgentConfig.sessionIdFor(body)` to control what
+counts as "one conversation" for its own domain (e.g. `customer-service`
+hashes `customerEmail`, so a request with no email is rejected rather than
+starting an anonymous session). Without it, the caller just supplies a
+`sessionId`, or gets one generated for them.
 
-## Wiring a real model
+## Running an agent
 
-Every example agent (`agents/file-agent.ts`, `agents/customer-service-agent.ts`,
-`agents/rag-agent.ts`) still uses a canned, turn-counting `ModelCall` so the
-whole loop is runnable and testable with no API key. To go live, swap it for
-one of the two real `ModelCall` implementations this repo ships:
+**CLI:**
 
-```ts
-import { createAnthropicModelCall } from './anthropic-model-call.js'
+```bash
+npx tsx adapters/cli.ts --agent customer-service --session s1 "order A-1001 arrived broken"
+```
 
-const modelCall = createAnthropicModelCall({ model: 'claude-sonnet-5' }) // reads ANTHROPIC_API_KEY from the env
+**HTTP:**
 
-const result = await runAgent(config, modelCall, 'order A-1001 arrived broken', [])
+```bash
+npx tsx adapters/http.ts
+curl -X POST localhost:8787/agents/customer-service/messages \
+  -H 'content-type: application/json' \
+  -d '{"customerEmail":"a@example.com","message":"order A-1001 arrived broken"}'
 ```
 
-```ts
-import { createOpenAIModelCall } from './openai-model-call.js'
+Add `/stream` to the URL for a Server-Sent Events response — one event per
+loop step (tool call, permission decision, budget check) instead of a
+single reply at the end.
+
+Three small browser pages, all cross-linked, share one look
+(`adapters/dev-ui-styles.ts`), and never need a build step — each is a
+self-contained HTML string served straight out of `adapters/http.ts`:
+
+**Agents list:** open `http://localhost:8787/agents` in a browser (the
+same route returns plain `{agents: [...]}` JSON to a non-browser client —
+content-negotiated on the `Accept` header, so nothing that already calls
+it as an API needs to change) to see every registered agent with links
+into the playground and config page below.
+
+**Dev playground:** open `http://localhost:8787/playground` (optionally
+`?agent=<name>` to preselect one) — pick an agent, chat with it, and watch
+that same loop-step event stream render live instead of reading raw SSE
+frames. Same `/messages/stream` route underneath.
+
+**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
+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`.
 
-// model is required (no built-in default) — OpenAI's current flagship
-// name changes too often to hardcode safely; reads OPENAI_API_KEY from the env
-const modelCall = createOpenAIModelCall({ model: 'gpt-4.1' })
+## Wiring a real model
 
-const result = await runAgent(config, modelCall, 'order A-1001 arrived broken', [])
-```
+Declare `AgentConfig.model` and the runtime builds a real `ModelCall` for
+you, using the matching API key from the environment:
 
-```ts
-import { createDeepSeekModelCall } from './deepseek-model-call.js'
+| `provider` | env var | `model` required? |
+| --- | --- | --- |
+| `'anthropic'` | `ANTHROPIC_API_KEY` | no — defaults to `claude-sonnet-5` |
+| `'openai'` | `OPENAI_API_KEY` | yes |
+| `'deepseek'` | `DEEPSEEK_API_KEY` | yes |
 
-// model is required, same reasoning as OpenAI's; reads DEEPSEEK_API_KEY
-// from the env — throws immediately, with a DeepSeek-specific message, if
-// neither that nor apiKey is set, rather than the OpenAI SDK's own
-// constructor silently accepting OPENAI_API_KEY instead.
-const modelCall = createDeepSeekModelCall({ model: 'deepseek-chat' })
-
-const result = await runAgent(config, modelCall, 'order A-1001 arrived broken', [])
-```
+For anything else (a custom SDK client, a canned/simulated model for
+testing), export your own `createModelCall(): ModelCall` instead.
 
-Nothing else in `run-agent.ts`, the adapters, or any `AgentConfig` needs to
-change — `ModelCall` is the only seam a real API call needs.
-
-loopengine's own `Message` type carries real block-native history: `content`
-is either a plain string or a `ModelContentBlock[]` — the same 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
-(`tool_use_id`) rather than being flattened into prose. That's what makes
-parallel tool calls unambiguous (a result links back to the exact call that
-requested it, not just "a call to this tool name") and lets a denied or
-failed call carry `is_error: true`, which Claude is specifically trained to
-react to. `anthropic-model-call.ts` translates directly to and from
-Anthropic's native `TextBlockParam`/`ToolUseBlockParam`/`ToolResultBlockParam`
-types — no flattening step in between. This was verified against the real
-SDK (with a stubbed `fetch`, not a live call) — request shape, tool schemas,
-and response mapping all round-trip correctly end to end.
-
-`openai-model-call.ts` translates to and from OpenAI's Chat Completions
-shape instead, verified the same way (stubbed `fetch`, real SDK, full
-`runAgent` round trip including a tool call). The one structural mismatch:
-loopengine bundles a whole turn's `tool_result` blocks into a single
-user-role message (mirroring Anthropic's shape); OpenAI has no equivalent —
-each becomes its own top-level `role: 'tool'` message, so one loopengine
-`Message` can expand into several OpenAI messages, never the reverse.
-
-`deepseek-model-call.ts` reuses `openai-model-call.ts`'s translation
-verbatim (exported, not duplicated) rather than reimplementing it —
-DeepSeek's Chat Completions API is wire-compatible with OpenAI's (verified
-against DeepSeek's own docs), down to the same `tool_calls` response
-shape. The one real difference: DeepSeek documents `max_tokens`, not the
-newer `max_completion_tokens` OpenAI's endpoint expects, so only the
-request-building call site differs, not the shared message/response
-translation functions.
-
-## Skills
-
-Agents can discover and invoke `SKILL.md` files (see `skills/`), the same
-convention production coding agents use: a short frontmatter index (`name`,
-`description`) stays in context at all times, and the full body is loaded
-only when the model actually invokes that skill — through a real `Skill`
-tool schema (`{skill: string, args?: string}`) declared to the model
-whenever `skillsDirs` is set, not just handled after the fact. Set
-`skillsDirs` on an `AgentConfig` to enable it; omit it for agents that
-don't need skills (`agents/rag-agent.ts` doesn't).
-
-Point `skillsDirs` at a subdirectory scoped to that agent
-(`skills/file-agent/`, not the shared `skills/` root) — `SkillGarden`'s
-discovery recursively walks whatever root it's given with no per-agent
-filtering, so two agents both pointed at `skills/` would each see every
-skill under it, not just their own.
-
-To install one of SkillGarden's bundled skills (e.g. `firecrawl`) into an
-agent's own subdirectory, use its `add` CLI:
+## Built on
 
-```bash
-npx skillgarden add firecrawl --agent file-agent
-# -> Added file-agent:firecrawl -> skills/file-agent/firecrawl/SKILL.md
-```
+| 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 |
+| [`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 |
+| [`mcpplug`](https://www.npmjs.com/package/mcpplug) | Gateway tool sourcing (e.g. Composio) |
 
-That writes `skills/file-agent/firecrawl/SKILL.md`, which discovery then
-surfaces as `file-agent:firecrawl` — no code change needed beyond having
-already set `skillsDirs: 'skills/file-agent'` on that agent's config.
+Installing `loopengine` pulls all of these in as regular dependencies —
+install one directly only if you want to use it standalone.
 
-## Project layout
+## Deployment
 
+```bash
+docker compose up --build
 ```
-index.ts                    Public API surface — what actually ships to npm
-agent-config.ts            AgentConfig type — the thing you fill in to define an agent
-run-agent.ts                The generic ReAct loop every agent and adapter runs through
-vector-index.ts             Dependency-free embeddings + cosine-similarity search, for RAG
-discover-agents.ts          discoverAgents — scans a directory, builds {name -> {config, createModelCall}}
-agent-registry.ts          This repo's ~15-line wrapper: discoverAgents('agents/') + listAgents()/getEntry()
-session-store.ts           SessionStore: FileSessionStore, RedisSessionStore, createSessionStore()
-anthropic-model-call.ts    createAnthropicModelCall — a real ModelCall this repo ships
-openai-model-call.ts        createOpenAIModelCall — same seam, OpenAI's Chat Completions API
-deepseek-model-call.ts      createDeepSeekModelCall — same seam, reuses openai-model-call.ts's translation
-agents/file-agent.ts               Example agent: summarizes text files
-agents/customer-service-agent.ts  Example agent: order/shipment lookup, refund, email
-agents/rag-agent.ts                Example agent: retrieves from an in-memory vector index
-adapters/cli.ts             Channel adapter: command line
-adapters/http.ts            Channel adapter: HTTP API
-skills/                     SKILL.md files discoverable by agents, scoped per agent subdirectory
-examples/file-agent/        Sample input files + generated output for the file-agent demo
-Dockerfile, docker-compose.yml   Container build + local Redis for testing
-```
+
+Builds the HTTP adapter into a container and starts it alongside Redis.
+For production, push the image to any container platform with `REDIS_URL`
+and your model/tool API keys set as environment variables.