loopengine 0.0.7 → 0.0.14

package/README.md

@@ -2,9 +2,9 @@
 
 [![CI](https://github.com/evanyan22/loopengine/actions/workflows/ci.yml/badge.svg)](https://github.com/evanyan22/loopengine/actions/workflows/ci.yml)
 
-A minimal framework for defining and running tool-using AI agents. Write an
-agent as a plain config object — persona, tools, permission rules — and run
-it through one generic ReAct loop over the CLI, an HTTP API, or both. No
+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.
 
@@ -94,14 +94,21 @@ const result = await runAgent(config, myModelCall, "What's the weather in Boston
 console.log(result.text)
 ```
 
-The full exported surface: `runAgent`, `AgentConfig`/`ToolSchema`/`ToolDefinition`,
+The full exported surface: `runAgent`,
+`AgentConfig`/`AgentModelConfig`/`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`/
+directory for modules exporting `config` — a flat `.ts`/`.js` file, or a
+subdirectory with an `index.ts`/`index.js`, the same "a directory can be a
+module" convention Node's own `require()` already uses, for an agent whose
+own implementation outgrows one file, like `agents/customer-service/` —
+plus either that module's own `createModelCall` or an `AgentConfig.model`
+to synthesize one from, 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.
+`ModelCall`s — what `AgentConfig.model` builds under the hood). 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
@@ -115,18 +122,41 @@ build with the library, not as library API itself.
 
 ```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
+npx tsx adapters/cli.ts --agent file-agent "Summarize examples/file-agent/a.txt and examples/file-agent/b.txt into examples/file-agent/summary.txt."
+npx tsx adapters/cli.ts --agent customer-service "order A-1001 arrived broken and wants a refund"  # needs DEEPSEEK_API_KEY
+npx tsx adapters/cli.ts --agent rag-agent "How does ActAuth record human approval decisions?"
 ```
 
-All demo agents use a **simulated** model call (no `ANTHROPIC_API_KEY` is
-wired up) — see "Wiring a real model" below.
+`file-agent` and `rag-agent` still use a **simulated**, turn-counting model
+call (no API key needed) — see "Wiring a real model" below.
+`customer-service` declares `model: { provider: 'deepseek', ... }` and
+needs `DEEPSEEK_API_KEY` set in the environment.
 
 ## 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.
+list of tools, and ActAuth permission rules. There are two ways to add one
+under `agents/`, and `agent-registry.ts` (built on `discoverAgents`) finds
+either automatically at startup — by `AgentConfig.name`, not the filename
+or folder name. Nothing to edit, no import to add, no adapter change,
+either way:
+
+1. **A flat file**, `agents/<name>.ts` — the default; start here.
+   `agents/rag-agent.ts` is a complete, working example.
+2. **A folder**, `agents/<name>/index.ts` — for an agent whose
+   implementation outgrows one file. `discoverAgents` finds a
+   subdirectory's `index.ts`/`index.js` the same way it finds a flat
+   file, the same "a directory can be a module" convention Node's own
+   `require()` resolution already uses. `agents/customer-service/` and
+   `agents/file-agent/` are complete, working examples.
+
+Either way, the module must export `config`, plus either its own
+`createModelCall` or an `AgentConfig.model` for `discoverAgents` to
+synthesize one from (see "Wiring a real model" below) — `discoverAgents`
+throws at startup on a module in `agents/` that exports neither (a real,
+load-bearing check: a module you forgot to finish wiring up, or an
+unrelated `.ts` file that doesn't belong in `agents/` at all, should fail
+loudly here rather than silently not showing up):
 
 ```ts
 import type { AgentConfig } from './agent-config.js'
@@ -134,6 +164,7 @@ import type { AgentConfig } from './agent-config.js'
 export const config: AgentConfig = {
   name: 'my-agent',
   systemPrompt: 'You are ...',
+  model: { provider: 'anthropic', model: 'claude-sonnet-5' }, // reads ANTHROPIC_API_KEY from the env
   tools: [
     {
       name: 'do_thing',
@@ -152,13 +183,89 @@ export const config: AgentConfig = {
 }
 ```
 
-`agents/file-agent.ts` and `agents/customer-service-agent.ts` are two complete, working
-examples — same `runAgent` loop, entirely different personas and tools.
+`agents/file-agent/index.ts` and `agents/customer-service/index.ts` are two
+complete, working examples — same `runAgent` loop, entirely different
+personas and tools. `agents/customer-service/` shows the folder form fully
+filled in — everything specific to one agent lives under its own folder,
+not scattered across separate top-level trees connected only by a
+matching name (nothing enforces that staying in sync):
 
-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.
+```
+agents/customer-service/
+  index.ts                          AgentConfig assembly + tenant/session resolution (tenantFor, sessionIdFor)
+  actauth.yml                       ActAuth rules
+  tools/
+    index.ts                        Aggregates the tools below into AgentConfig.tools
+    lookup_order.ts                 One file per tool
+    get_shipment_details.ts
+    issue_refund.ts
+    send_email.ts
+    orders-store.ts                 Shared in-memory store the tools above read/write
+  skills/
+    firecrawl/SKILL.md              One <skill-name>/SKILL.md per skill (see "Skills" below)
+```
+
+`agents/file-agent/` follows the same shape, minus `orders-store.ts` —
+its one difference is a Composio-sourced GitHub tool, which isn't in
+`tools/` at all since it's fetched dynamically at runtime (see "External
+tool gateways" below), not static code.
+
+### Smart defaults
+
+`rules`, `tools`, and `skillsDirs` can all be omitted — each then defaults
+to a conventional path under this agent's own folder, `agents/<name>/…`,
+instead of something you write out:
+
+| Field | Omitted, defaults to | Missing there means |
+| --- | --- | --- |
+| `rules` | `agents/<name>/actauth.yml` | empty ruleset, **deny** everything (no permission story was ever written — stricter than the inline-array form's `'ask'` default) |
+| `tools` | import `agents/<name>/tools/index.{ts,js}`, use its exported `tools` | `[]` — same as an agent with no tools at all |
+| `skillsDirs` | `['agents/<name>/skills']` | no skills discovered, no `Skill` tool declared |
+
+None of these throw over a missing file/folder — only `rules` changes
+behavior when it's missing (deny-by-default, not "no rules apply"), since
+skipping every tool is safer than silently allowing them all. Pass an
+explicit empty value (`[]`, or a `rules` path that doesn't exist) instead
+of omitting the field to opt out of a default on purpose — an
+*explicitly* wrong path is a real configuration bug and still throws.
+
+The `actauth.yml` form is close to the shape `examples/actauth.yml` in the
+actauth package itself uses, but each rule's `scope` only needs
+*tenant/environment* (e.g. `"*/*"`, `"acme-corp/production"`) — no agent
+segment, since a loopengine actauth.yml is always one-file-per-agent by
+convention. `run-agent.ts` appends `/<name>` to every rule loaded from a
+YAML file automatically; writing the agent's own name into every single
+rule would be pure repetition. See `agents/customer-service/actauth.yml`.
+
+An agent that needs to merge tools in from somewhere else too —
+`agents/file-agent/index.ts`'s Composio-sourced ones — can't rely on the
+`tools` default and sets it explicitly instead.
+
+### Parallel tool execution
+
+When a model requests several tool calls in one turn, `ToolLane` decides
+which can run concurrently: mark a tool `safe: true` on its
+`ToolDefinition` (read-only, no side effects, no shared mutable state —
+`agents/customer-service/tools/lookup_order.ts`) and consecutive safe
+calls run together in a parallel lane; anything else gets its own solo
+lane. For per-call nuance beyond a tool's static definition (safety that
+depends on the specific call's arguments, or varies by agent), set
+`AgentConfig.isSafeTool: (call) => boolean` instead — it takes full
+precedence over every tool's own `safe` flag when set
+(`agents/file-agent/index.ts` uses this form). Neither set: every tool
+runs solo.
+
+### Human approval
+
+`AgentConfig.approver` — an `Approver` from `actauth` — is what an `ask`
+decision routes to; the default `ConsoleApprover` blocks on stdin, fine
+for the CLI but wrong for an unattended server (see
+`agents/customer-service/index.ts`'s own auto-approving demo `approver`,
+and swap in a real one, e.g. Slack-backed, for production).
+`AgentConfig.maxTurns` (default 25) caps model calls in one `runAgent()`
+turn — the only thing stopping a model stuck re-requesting the same tool
+forever; hitting it ends the turn with `RunAgentResult.stopReason` set to
+`'max_turns'`, a real result rather than a thrown error.
 
 ## Retrieval (RAG)
 
@@ -206,7 +313,7 @@ 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
+// every turn; see agents/file-agent/index.ts for the working example this is
 // drawn from.
 const composioTools = await connectComposioSource('composio', {
   slugs: ['GITHUB_LIST_REPOSITORIES_FOR_THE_AUTHENTICATED_USER'],
@@ -228,7 +335,7 @@ const config: AgentConfig = {
 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
+`agents/file-agent/index.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
@@ -252,7 +359,7 @@ curl -X POST localhost:8787/agents/customer-service/messages \
 ```
 
 `customerEmail` is specific to `customer-service` — it defines its own
-`AgentConfig.sessionIdFor` (see "Sessions and multi-tenancy" below). Other
+`AgentConfig.sessionIdFor` (see "Sessions" 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
@@ -269,6 +376,18 @@ curl -X POST localhost:8787/agents/file-agent/messages \
 anonymous session," since `customerEmail` is a real, meaningful identity
 for that agent, not an arbitrary key.
 
+`customer-service` also sets `AgentConfig.tenantFor` (see "Multi-tenancy"
+below), resolving tenant from an `x-api-key` header. The request above
+with no header behaves
+exactly as before — `issue_refund` still asks for approval. Add a
+trusted key and it doesn't:
+
+```bash
+curl -X POST localhost:8787/agents/customer-service/messages \
+  -H 'content-type: application/json' -H 'x-api-key: acme-trusted-key' \
+  -d '{"customerEmail":"a@example.com","message":"order A-1001 arrived broken"}'
+```
+
 **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
@@ -293,86 +412,101 @@ 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/`,
+## Sessions
+
+A session is one ongoing conversation — its message history persists
+between requests via a `SessionStore`, so a caller can send one message,
+get a reply, and come back later and continue where it left off.
+
+**Storage.** `SessionStore` exposes one method, `withSession(sessionId,
+fn)`: it loads that session's history, runs `fn` **exclusively** for that
+session (so two concurrent requests for the same conversation can't race
+on read-modify-write), and appends whatever new messages `fn` produced.
+History is an append-only [`sessionknit`](https://www.npmjs.com/package/sessionknit)
+log rather than a flat file rewritten every turn, which buys two things:
+
+- **Non-blocking, debounced writes** — a turn only appends, it never
+  rewrites what's already durable.
+- **Interruption detection** — a turn's assistant response (including any
+  tool calls) is saved *before* those tools run, then the results are
+  saved once they've all settled. If the process dies in between, the
+  next resume sees an unanswered tool call, flags the session as
+  resumed-after-interruption, and tells the model so in context — instead
+  of silently replaying a half-finished turn as if it were clean.
+
+Two implementations, same interface — `createSessionStore()` picks
+between them based on `REDIS_URL` (set it and you get Redis, otherwise
+the file store):
+
+- `FileSessionStore` — one JSONL 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.
+- `RedisSessionStore` — same log shape in a Redis list, with a real
+  distributed lock (safe across multiple server instances) that renews
+  itself for as long as a turn runs, instead of a flat TTL a long turn
+  could outlast.
+
+**Session keys.** Two questions decide which log a message lands in:
+*which conversation* is this, and *which agent's* conversation is it?
+
+- *Which conversation* — `AgentConfig.sessionIdFor(body)`. This is
+  business logic ("what counts as one conversation" depends on what the
+  agent is for), so it lives on the agent, not the adapter.
+  `agents/customer-service/index.ts` hashes `customerEmail` from the
+  request body into a session id, so different customers can never read
+  or write each other's history, and a request with no `customerEmail` is
+  rejected (`400`) rather than silently starting an anonymous session. An
+  agent that doesn't define `sessionIdFor` falls back to a plain
+  client-supplied `sessionId` field — or, if that's missing too, a
+  generated one, returned in the response so the caller can pass it back
+  in to continue that exact conversation later.
+- *Which agent* — `SessionStore` itself doesn't know or care which agent
+  is calling it, so both adapters prefix the id with the agent's name
+  before it ever reaches `SessionStore`. Without that, two different
+  agents handed the same raw session id (a client reusing one `sessionId`
+  value across agents) would read and write the exact same log.
+
+`adapters/http.ts` also folds the caller's tenant and environment into
+that key (see "Multi-tenancy" below) — without that, two different
+tenants whose `sessionIdFor` happens to produce the same raw id would
+collide on the same log too. Verified live: the same raw `sessionId` sent
+under two different tenants lands in two separate session files, not one.
+
+## Multi-tenancy
+
+ActAuth's permission rules are scoped by `tenant`/`environment`/`agent` —
+a support agent might allow more for a trusted tenant, or relax approval
+requirements outside production. `agent` is always `AgentConfig.name`;
+the other two work differently, because only one of them varies per request:
+
+- **`environment`** is a deployment-wide setting, not a per-agent or
+  per-request one — always `process.env.LOOPENGINE_ENV` (default
+  `'production'`), the same for every agent this process runs. There's no
+  `AgentConfig` field for it at all.
+- **`tenant`** varies by *who's calling*, so it's resolved per request
+  via `AgentConfig.tenantFor?: (headers, body) => string | undefined`.
+  Only `headers`, never `body` — tenant feeds permission decisions
+  directly, so it has to come from something verified (an
+  `Authorization`/API-key header checked against your own mapping), never
+  a client-asserted body field anyone could fake to claim another
+  tenant's permissions. Omit `tenantFor` entirely and every request is
+  the `'default'` tenant.
+
+Only `adapters/http.ts` actually calls `tenantFor`, via `resolveTenant`.
+Two rules govern the result:
+
+- Returning `undefined` is a real auth failure (`401`) — not "fall back
+  to `'default'`." If no header at all should mean `'default'` rather
+  than a rejection, the resolver must return `'default'` itself.
+- No `tenantFor` at all isn't a failure — it just means this agent has no
+  per-request tenants, so every request resolves to `'default'`.
+
+`run-agent.ts` never sees a request, so it can't call `tenantFor` either
+— the standalone/CLI paths that pass `config` to `runAgent` directly
+(skipping `adapters/http.ts`'s resolution) always get `'default'`, the
+same as `RunAgentOptions.tenant` being omitted. Verified live end to end:
+a header-derived tenant resolves to different ActAuth rules per tenant (a
+specific tenant's rule overrides a wildcard fallback), and an omitted
+`tenant` option resolves the same as an explicit `'default'`.
 
 ## Deployment
 
@@ -388,104 +522,111 @@ and any tool-specific secrets set as environment variables.
 
 ## Wiring a real model
 
-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:
+`agents/file-agent/index.ts` and `agents/rag-agent.ts` still use a canned,
+turn-counting `ModelCall` so the whole loop runs with no API key.
+`agents/customer-service/index.ts` is already wired to a real one — a
+working example, not just a snippet.
 
-```ts
-import { createAnthropicModelCall } from './anthropic-model-call.js'
-
-const modelCall = createAnthropicModelCall({ model: 'claude-sonnet-5' }) // reads ANTHROPIC_API_KEY from the env
-
-const result = await runAgent(config, modelCall, 'order A-1001 arrived broken', [])
-```
+**The easy way** — declare `AgentConfig.model` and skip `createModelCall`
+entirely; `discoverAgents` builds it for you:
 
 ```ts
-import { createOpenAIModelCall } from './openai-model-call.js'
-
-// 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' })
-
-const result = await runAgent(config, modelCall, 'order A-1001 arrived broken', [])
+export const config: AgentConfig = {
+  name: 'my-agent',
+  // ...
+  model: { provider: 'anthropic', model: 'claude-sonnet-5' }, // reads ANTHROPIC_API_KEY
+}
 ```
 
-```ts
-import { createDeepSeekModelCall } from './deepseek-model-call.js'
+| `provider` | env var read | `model` required? | example |
+| --- | --- | --- | --- |
+| `'anthropic'` | `ANTHROPIC_API_KEY` | no — defaults to `claude-sonnet-5` | `{ provider: 'anthropic' }` |
+| `'openai'` | `OPENAI_API_KEY` | yes — no safe hardcoded default | `{ provider: 'openai', model: 'gpt-4.1' }` |
+| `'deepseek'` | `DEEPSEEK_API_KEY` | yes — no safe hardcoded default | `{ provider: 'deepseek', model: 'deepseek-chat' }` |
+
+`agents/customer-service/index.ts` uses exactly this —
+`model: { provider: 'deepseek', model: 'deepseek-v4-pro' }`, nothing
+else. Built lazily, on first actual call, and memoized after that, not at
+module load: `discoverAgents()` imports every agent at startup, so
+building the real client eagerly would crash the whole server without
+`DEEPSEEK_API_KEY`, even just to run `file-agent`.
+
+**The manual way** — for anything the table above can't express (a
+canned/simulated `ModelCall` like `file-agent`/`rag-agent`'s own, a
+custom SDK client, a provider not listed), export `createModelCall`
+yourself and call the same factories `AgentConfig.model` uses under the
+hood:
 
-// 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' })
+```ts
+import { createAnthropicModelCall } from './model-calls/anthropic-model-call.js'
+// createOpenAIModelCall / createDeepSeekModelCall work the same way
 
-const result = await runAgent(config, modelCall, 'order A-1001 arrived broken', [])
+export function createModelCall(): ModelCall {
+  return createAnthropicModelCall({ model: 'claude-sonnet-5' })
+}
 ```
 
-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.
+Either way, nothing else in `run-agent.ts`, the adapters, or any
+`AgentConfig` needs to change — `ModelCall` is the only seam a real API
+call needs.
+
+All three factories translate loopengine's `Message`/`ModelResponse` to
+and from their provider's real request/response shape (verified against
+the real SDKs with a stubbed `fetch`, tool calls included).
+`model-calls/deepseek-model-call.ts` reuses `openai-model-call.ts`'s
+translation directly rather than reimplementing it, since DeepSeek's
+Chat Completions API is wire-compatible with OpenAI's.
 
 ## Skills
 
-Agents can discover and invoke `SKILL.md` files (see `skills/`), the same
-convention production coding agents use: a short frontmatter index (`name`,
+Agents can discover and invoke `SKILL.md` files, 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).
+whenever any skills are actually found, not just handled after the fact.
 
-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.
+`AgentConfig.skillsDirs` (an array of directory paths) controls where
+from — see "Smart defaults" above for what it defaults to when omitted.
+`SkillGarden` discovery recursively walks every directory it's given with
+**no per-agent filtering** — whatever `SKILL.md` files live under a
+`skillsDirs` path, the agent sees all of them, which is the whole reason
+the two kinds below live in different places.
+
+**Agent-specific** — a skill only one agent needs, under that agent's own
+folder, pointed at by only that agent's `skillsDirs`:
+
+```
+agents/customer-service/skills/
+  firecrawl/SKILL.md      Only customer-service's skillsDirs points here
+```
+
+**Global** — a skill genuinely meant to be shared, at the repo-root
+`skills/` (see `skills/README.md`), pointed at by every agent's
+`skillsDirs` that wants it:
+
+```
+skills/
+  README.md                Explains the convention; no shared skill exists yet
+  (some-shared-skill)/SKILL.md   Would be seen by every agent pointed here
+```
+
+Nothing lives in the global root today — every skill this repo ships is
+agent-specific. Don't point an agent at the global root *and* its own
+folder unless you mean for it to see both; and don't move a skill to the
+global root just because it feels reusable in theory — wait until a
+second agent actually needs the exact same one.
 
 To install one of SkillGarden's bundled skills (e.g. `firecrawl`) into an
-agent's own subdirectory, use its `add` CLI:
+agent-specific folder, pass `--agent` and no `--dir` — it defaults to
+`agents/<agent>/skills/<skill>/SKILL.md`, matching how every skill in this
+repo is actually laid out:
 
 ```bash
 npx skillgarden add firecrawl --agent file-agent
-# -> Added file-agent:firecrawl -> skills/file-agent/firecrawl/SKILL.md
+# -> Added file-agent:firecrawl -> agents/file-agent/skills/firecrawl/SKILL.md
 ```
 
-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.
-
 ## Project layout
 
 ```
@@ -496,15 +637,27 @@ vector-index.ts             Dependency-free embeddings + cosine-similarity searc
 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
+model-calls/anthropic-model-call.ts   createAnthropicModelCall — a real ModelCall this repo ships
+model-calls/openai-model-call.ts       createOpenAIModelCall — same seam, OpenAI's Chat Completions API
+model-calls/deepseek-model-call.ts     createDeepSeekModelCall — same seam, reuses openai-model-call.ts's translation
+agents/file-agent/index.ts               Example agent: summarizes text files
+agents/file-agent/tools/                 Its hand-written tools, one file per tool
+agents/file-agent/skills/                Its SKILL.md files
+agents/file-agent/actauth.yml            Its ActAuth rules
+agents/customer-service/index.ts         Example agent: order/shipment lookup, refund, email
+agents/customer-service/tools/           Its tools, one file per tool
+agents/customer-service/skills/          Its SKILL.md files
+agents/customer-service/actauth.yml      Its ActAuth rules
+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
+tools/README.md             Root tools/ — for a tool genuinely shared across agents; empty today
+skills/README.md            Root skills/ — same, for a shared SKILL.md; empty today
 examples/file-agent/        Sample input files + generated output for the file-agent demo
 Dockerfile, docker-compose.yml   Container build + local Redis for testing
 ```
+
+Every agent's own tools/skills live under `agents/<name>/` — the root
+`tools/`/`skills/` directories are reserved for something genuinely meant
+to be shared across every agent that opts in, which doesn't exist in this
+repo yet (see each directory's own `README.md`).