@migor/agentia 0.10.3 → 0.10.4

package/README.en.md

@@ -1,6 +1,6 @@
 # Agentia
 
-[![CI](https://github.com/retrychx/agentia/actions/workflows/ci.yml/badge.svg)](https://github.com/retrychx/agentia/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/@migor/agentia)](https://www.npmjs.com/package/@migor/agentia) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![CI](https://github.com/migoric/agentia/actions/workflows/ci.yml/badge.svg)](https://github.com/migoric/agentia/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/@migor/agentia)](https://www.npmjs.com/package/@migor/agentia) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
 [中文 README](./README.md) · **English**
 
@@ -8,25 +8,23 @@
 with decorators + DI and a main agent orchestrates them; every run yields structured output and an
 observable call tree (trace, cost, metrics).
 
-**1 package · ≈2 MB · 0 runtime dependencies · 90+ guards** — the answer to the first question when
-choosing a library (how big is the install?): `npm i @migor/agentia` puts exactly **one** package into
-`node_modules` and pulls in no vendor SDK. These numbers are recomputed by
-`tests/docs/scoreboard.test.ts` on every run; hand-written figures rot.
+**1 package · ≈2 MB · 0 runtime dependencies · 90+ guards** — recomputed by
+`tests/docs/scoreboard.test.ts` on every run.
 
-> This is a **summary**. The [website](https://agentia-web.pages.dev/en) is **bilingual** — the English
-> pages mirror the Chinese ones section by section — but the authoritative and always-current
-> **long-form** documentation is Chinese:
-> [`docs/usage-guide.md`](./docs/usage-guide.md) (API reference, type wiring, known limits; the same
-> text is served verbatim at `/llms-full.txt`). We keep this file short on purpose — a hand-maintained
-> full translation drifts.
+> This is a **summary**, kept short on purpose (a hand-maintained full translation drifts). The
+> [website](https://agentia-web.pages.dev/en) is bilingual, but the authoritative long-form
+> documentation is Chinese: [`docs/usage-guide.md`](./docs/usage-guide.md) (also served verbatim at
+> `/llms-full.txt`).
 
 ## Requirements
 
-Node.js **≥ 18** (the only `engines` requirement). CI covers **18 / 20 / 24** — the `import-floor`
-matrix pins the floor declared in `engines`, every other job follows the current LTS. Deno and edge
-runtimes are **not** validated. The only store touching a Node builtin is `SqliteTaskStore` (needs
-Node ≥ 22.5 for `node:sqlite`) — it fails with a readable error at construction time, and never breaks
-importing the package.
+Node.js **≥ 18** (the only `engines` requirement); CI covers **18 / 20 / 24**. Designed and tested on
+Node; **Bun and Deno are verified runnable** (four-step check — import → assemble → HTTP → side
+effects — plus minimal mounting code per host and the measured versions, in
+[`docs/frameworks.md`](./docs/frameworks.md); the front page deliberately carries no version numbers —
+they rot); **edge runtimes remain unverified**.
+`SqliteTaskStore` needs Node ≥ 22.5 (`node:sqlite`) and fails with a
+readable error at construction — importing the package still works.
 
 ## Install
 
@@ -34,26 +32,34 @@ importing the package.
 npm i @migor/agentia          # the framework
 npm i -g @migor/cli           # CLI: scaffold / generate / dev inspector
 
-agentia create my-app         # scaffold ships .env / .env.example
-$EDITOR my-app/.env           # put ANTHROPIC_API_KEY here (export works too — real env wins)
+agentia create my-app --minimal  # single entry file + a bare tool; ships .env / .env.example
+cd my-app && npm install
+$EDITOR .env                     # put ANTHROPIC_API_KEY here (export works too — real env wins)
+npm run dev -- "your question"   # tsx src/main.ts: one run, then exit
 # optional: ANTHROPIC_BASE_URL (compatible gateways), AGENTIA_MODEL (default claude-opus-5)
 ```
 
-> The framework does **not** read `.env` on its own: the scaffolded `src/main.ts` calls
-> `loadEnvFile()` on its first line. Real environment variables always win over the file
-> (CI / docker / command line), unless you pass `loadEnvFile({ override: true })`.
+> The framework does **not** read `.env` on its own: the template entry calls `loadEnvFile()`.
+> Real environment variables win over the file unless you pass `{ override: true }`.
 
 ## Quick start
 
 ### A. CLI
 
+Start with `--minimal` to exercise the model and a bare tool without learning decorators, DI or the HTTP
+host first. For the inspector, four capability directories and a production service, use the **default
+full template without `--minimal`** (unchanged):
+
 ```bash
-agentia create my-app
-cd my-app && npm install
+agentia create my-service
+cd my-service && npm install
 agentia g tool weather          # create src/tools/weather/index.ts and register it
 agentia dev                     # local inspector panel (drive a run, pick capabilities/workdir)
 ```
 
+In the full template, `src/main.ts` starts the HTTP service and `src/batch.ts` is the one-shot
+`npm run start:batch` entry.
+
 Four self-describing directories hold capabilities — the directory name **is** the kind:
 `src/tools/` · `src/skills/` · `src/prompts/` · `src/subagents/`; the registry is `src/registry.ts`.
 
@@ -91,6 +97,21 @@ console.log(result.trace);     // call tree + per-step tokens/cost (traceId ===
 Or point `createApp` at the directories instead of passing providers:
 `createApp({ discover: ['src/tools', 'src/skills', 'src/prompts', 'src/subagents'], system })`.
 
+### C. Existing service? Add one endpoint
+
+Don't scaffold a new project, and don't rewrite the one you have. Wrap an existing function as a
+`@Tool`, then add **one branch** in your existing `createServer`: business routes first (your code
+stays untouched), everything else goes to `createHttpHandler` (`/run`, `/tasks`, `/healthz`).
+Auth is **the same function** for both, and `drain()` hooks into the SIGTERM flow you already have.
+
+Six steps, roughly 30 lines of glue. Runnable example:
+[`examples/agent-endpoint/`](./examples/agent-endpoint/) — an order service that already ships
+`GET /api/orders/:id`, with the agent endpoint added alongside; `src/orders.ts` is unchanged.
+
+> Three deliberate calls: **one auth path** (the framework gives you the seam, not the policy);
+> **RAG is your tool** (wrap your own `pg.query` / vector client in a `@Tool` — the framework won't
+> ship one); **no budget knobs = no fuse** (the example sets all three).
+
 ## The four capability kinds
 
 The model picks from one shared "menu" by `description`; the decorator decides **who controls the flow**:
@@ -133,6 +154,19 @@ One run == one trace (`traceId === runId`), **built in from turn 0** — not a b
 - **Models** — `createAnthropicClient()` (default) and `createOpenAIClient()` for any OpenAI-compatible
   endpoint (DeepSeek, **Ollama**, gateways). You never need to touch a vendor SDK: pass
   `createAnthropicClient({ baseURL })` / `createOpenAIClient({ baseURL })`.
+- **Web framework hosts** — `createHttpHandler` returns a plain `(req, res) => void`, so anything that
+  can mount a raw node handler can mount it, with no adapter layer:
+
+  | Host | Minimal mounting | Required config |
+  |---|---|---|
+  | `node:http` | `createServer(createHttpHandler(app, { runner }))` | none |
+  | NestJS 12 (CJS / ESM) | `nestApp.use('/agent', handler)` — 3 lines | CJS mode needs Node ≥ 22.12 (or `await import()`) |
+  | Egg 4 | middleware + `ctx.respond = false` | two `ignore` entries (CSRF / bodyParser) — the string form crashes the worker at startup |
+  | Bun / Deno | identical to `node:http`, zero changes | Deno's `--allow-net/read/write/run` |
+
+  Under cluster / multi-instance the task store **must** be shared — one in-memory store per worker
+  makes polling the same taskId alternate `404 200`. Conclusion table, minimal code and Egg's three
+  pitfalls: [`docs/frameworks.md`](./docs/frameworks.md).
 - **MCP** — `createStdioMcpConnector()` / `createStreamableHttpMcpConnector()` ship with the framework
   (stdlib only: `node:child_process` + global `fetch`); `mcpTools()` bridges the server's tools into the
   menu. The framework never imports the MCP SDK, and the `McpClientLike` seam stays open
@@ -142,12 +176,36 @@ One run == one trace (`traceId === runId`), **built in from turn 0** — not a b
 - **Platforms** — send traces to Langfuse / Phoenix / etc. via OTLP or a tiny custom `TraceSink`
   (see [`docs/observability.md`](./docs/observability.md) §2.6)
 
+## API at a glance
+
+| Export | Purpose |
+|---|---|
+| `createApp` / `discoverProviders` | assemble an app / scan capability directories |
+| `defineModule` | capability package (providers + middleware, distributable) |
+| `Tool` / `Skill` / `SubAgent` / `Prompt` | the four capability decorators |
+| `CapabilityMiddleware` (the `middleware` option) | interceptor chain around capability calls |
+| `asset` | read a text asset inside a capability folder |
+| `SystemPrompt` | compose the system prompt (adds the cache breakpoint) |
+| `RunContext.current()` | blackboard / runId for the current run |
+| `AsyncRunner` / `Scheduler` / `runSync` / `createHttpHandler` | async / scheduled / sync / HTTP triggering |
+| `FileTaskStore` / `SqliteTaskStore` / `RedisTaskStore` / `InMemoryTaskStore` | task record stores |
+| `createBudgetPolicy` | long-context budget guard |
+| `createAnthropicClient` | default ModelClient (Anthropic) |
+| `createOpenAIClient` | any OpenAI-compatible endpoint |
+| `InMemoryMemoryStore` (the `memory` option) | cross-run memory hydration / write-back |
+| `createOtlpExporter` | export traces over OTLP |
+| `traceToMessages` | replay a finished trace as model messages |
+| `fromZod` | zod schema adapter (optional peer) |
+| `runAgent` / `executeRun` | bare engine entry (no assembly) |
+
 ## Documentation
 
 | | |
 |---|---|
 | Usage guide (authoritative, zh) | [`docs/usage-guide.md`](./docs/usage-guide.md) |
 | Production observability recipes | [`docs/observability.md`](./docs/observability.md) |
+| Database integration (inject your pool / implement `TaskStore` for MySQL) | [`docs/database.md`](./docs/database.md) |
+| Framework compatibility (measured: NestJS / Egg / Bun / Deno) | [`docs/frameworks.md`](./docs/frameworks.md) |
 | Examples (complete app / minimal deploy / observability) | [`examples/`](./examples/) |
 | Design spec & roadmap | [`docs/spec.md`](./docs/spec.md) · [`docs/roadmap.md`](./docs/roadmap.md) |
 | Website · Playground | [agentia-web.pages.dev/en](https://agentia-web.pages.dev/en) · [playground](https://agentia-web.pages.dev/en/playground) |
@@ -163,19 +221,17 @@ stating what **you** have to change.
 grep -nE '^#{3,4} .*(迁移|破坏性)' CHANGELOG.md    # every "you must act" section
 ```
 
-> Honest caveat: this discipline was **tightened over time** — early versions (`0.7.1`, a type-level
-> change) put the action in the entry's leading blockquote instead of its own section. The command
-> above is a **lower bound**, not the whole set. And this README deliberately prints **no**
-> "N releases / M migrations" count: hand-written counts rot, so we ship the command instead.
+> The command above is a **lower bound**, not the whole set — early versions didn't follow this format.
+> Counts ("N releases / M migrations") are deliberately not printed: they rot.
 
-**What is covered by the compatibility promise:** the **named exports** of `@migor/agentia`
-(`src/index.ts` is the source of truth) and the `@migor/cli` command surface, plus the Node range in
-`engines.node` — CI runs the full chain on every version in that range. **Not covered:** deep imports
-(`dist/**`) — **sealed by the `exports` field** in `package.json` (guarded by
-`tests/architecture/package-exports.test.ts`; before `exports` existed they really did resolve) —
-internal module paths, `packages/*`, `examples/*`, Deno / Bun / edge runtimes (unvalidated),
-and anything a release does not spell out in its migration note. Runtime third-party dependencies are
-**zero** — enforced by `tests/architecture/no-runtime-deps.test.ts`, not by promise.
+**Covered by the compatibility promise:** the **named exports** of `@migor/agentia` (`src/index.ts` is
+the source of truth) and the `@migor/cli` command surface, plus the Node range in `engines.node` (CI
+runs the full chain on every version in it). **Not covered:** deep imports (`dist/**`) — sealed by the
+`exports` field in `package.json`, guarded by `package-exports.test.ts` — internal module paths,
+`packages/*`, `examples/*`, edge runtimes, and anything a release doesn't spell out in its
+migration note. Bun / Deno are **verified runnable but outside the `engines` promise**
+([`docs/frameworks.md`](./docs/frameworks.md)). Runtime third-party dependencies are **zero**, enforced by
+`no-runtime-deps.test.ts`, not by promise.
 
 **What 1.0 waits for** (all three are checkable): every open item in `docs/spec.md` §11 is either
 shipped or explicitly struck out; `docs/guards.md` §2 ("awaiting a guard") is empty; and the public
@@ -199,9 +255,8 @@ cost you pay under which condition, and what a different implementation could re
 > load; copying them as an SLA will be wrong. What is actually constant is the **shape** (how many
 > times larger, how many round trips, what scales with what).
 >
-> The five benchmarks are **deliberately not in CI** (timing benchmarks only add noise on CI machines;
-> `docs/plans/2026-09-22-dev-debug-loop.md` settled on "run them when you want to look") ⇒ nothing
-> guards the numbers below — re-run the command in the last column.
+> The five benchmarks are **deliberately not in CI** (timing benchmarks only add noise) ⇒ nothing
+> guards these numbers; re-run the command in the last column.
 
 ## Contributing