power-loop 3.0.0__tar.gz → 3.0.2__tar.gz

{power_loop-3.0.0 → power_loop-3.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: power-loop
-Version: 3.0.0
+Version: 3.0.2
 Summary: Embeddable agent execution kernel — LLM loop, hooks, events, tools, dynamic sub-agents.
 Author-email: zhangran <zhangran24@126.com>
 License: MIT
@@ -106,7 +106,7 @@ print((await loop.send("And my second-favorite?", session_id=sid)).final_text)
 pip install 'power-loop[openai]'      # or [anthropic] · add [postgres] / [mysql] for those backends
 ```
 
-> **1.0 — stable.** The public API is frozen under SemVer (a breaking change requires a major bump), machine-enforced by a baseline guard in CI. The **core has zero runtime dependencies** (pure stdlib; verified by a CI job that imports it with nothing else installed) — LLM transports *and database drivers* are optional extras. See [Stability](#stability--semver) and the [honest caveats](#honest-scope) — a young, single-maintainer project says so plainly.
+> **Stable since 1.0; now 3.x.** The public API is frozen under SemVer and machine-enforced by a baseline guard in CI — and the two major bumps since prove the discipline rather than undercut it: **2.0** moved storage to a pluggable async backend, **3.0** made context handling two orthogonal axes. Both were real breaking changes, so both got a major bump. The **core has zero runtime dependencies** (pure stdlib; verified by a CI job that imports it with nothing else installed) — LLM transports *and database drivers* are optional extras. Backed by **900+ unit tests**, a **live-LLM** suite, and a **3-backend conformance suite** (SQLite/PostgreSQL/MySQL). See [Stability](#stability--semver) and the [honest caveats](#honest-scope) — a young, single-maintainer project says so plainly.
 
 ---
 
@@ -116,7 +116,7 @@ pip install 'power-loop[openai]'      # or [anthropic] · add [postgres] / [mysq
 |---|---|
 | 🚀 **New** — show me the 5-minute version | [Getting Started](docs/en/getting-started.md) |
 | 🛠️ **Learning by building** | [Tutorials](docs/en/tutorials/index.md) — chatbot · tools · human-in-the-loop · multi-agent |
-| 🧩 **Browsing runnable code** | [40 examples](examples/README.md) — `00_hello_world.py` → full chatbot |
+| 🧩 **Browsing runnable code** | [43 examples](examples/README.md) — `00_hello_world.py` → full chatbot |
 | 📚 **Looking something up** | [User Guide](docs/en/user-guide/index.md) · [API reference](docs/en/api/index.md) |
 | 🤔 **Deciding if it fits** | [How it compares](#how-it-compares) · [Honest scope](#honest-scope) |
 
@@ -128,10 +128,11 @@ pip install 'power-loop[openai]'      # or [anthropic] · add [postgres] / [mysq
 
 Most "agent frameworks" ask you to build your app *inside* them. power-loop is the opposite: a **library you embed**. You keep your HTTP layer, your auth, your queues, your RAG, your UI, your deploy. It runs the agent loop — and lets you *engineer* it.
 
-- 🪶 **Featherweight & zero-dependency.** No `pydantic`, no LangChain, no graph DSL. A compact, pure-stdlib core (~20k lines) whose public surface is essentially one class — and **zero runtime dependencies**. LLM transports *and* the Postgres/MySQL drivers are pulled in only by the extra you install.
+- 🪶 **Featherweight & zero-dependency.** No `pydantic`, no LangChain, no graph DSL. A compact, pure-stdlib core (~24k lines) whose public surface is essentially one class — and **zero runtime dependencies**. LLM transports *and* the Postgres/MySQL drivers are pulled in only by the extra you install.
 - 🗄️ **Pluggable storage, zero-infra default.** Sessions, timers, sub-agent trees, workflow journals, the shared blackboard — one backend-neutral store written once against a tiny `Database`/`Dialect` port. The default is **one SQLite file** (copy the file, you've copied the state); point a DSN at **PostgreSQL or MySQL** when you want a real multi-writer server — same code, same conformance suite. Tables are auto-created, or **provisioned out-of-band** with a printed DDL script (see [Storage backends](docs/en/user-guide/storage-backends.md)).
 - ♻️ **Stateless, resumable loops.** A `StatefulAgentLoop` carries no authoritative state — all of it lives in the store. So a loop is cheap to create and trivially **restored from a DSN + a session id** (ideal for web handlers, workers, cold starts). It self-caches each session's active window (a rebuildable accelerator that never changes what the model sees) to skip re-reads on hot paths.
 - ⏱️ **Durable by default.** Crash mid-run and `resume()`. Agents schedule their own **durable timers** that survive restarts. Workflows **replay finished steps and re-run only the unfinished tail** after a process death. The store survives version upgrades (a portable, backend-neutral migration-version table) and can be **pruned, VACUUMed, and exported**.
+- 🧠 **Context engineering, not one fixed strategy.** How each finished send is *recorded/rendered* (**representation**: full **verbatim** or a terse per-send **projection**) and how older history is *compacted* once over budget (**fold strategy**: a single **LLM summary**, or an **agentic** pass that also writes durable notes) are two **orthogonal, config-driven axes** — any representation composes with any fold strategy, and both take your own `Representation` / `FoldStrategy` implementation. Folds always keep whole sends (never split a tool-call/result pair); `recall_send` / `recall_compacted` pull the original detail back from the immutable audit log.
 - 🧩 **Composable from one loop to a fleet.** Start with `send()`. Add tools. Spawn sub-agents. Fan out a deterministic **workflow** (`sequence`/`parallel`/`foreach`/`branch`). Run each leaf in its **own process and DB** behind a sandbox. Same primitives all the way up.
 - 🛡️ **Isolation seams where it counts.** Tool-level sandboxing via a `ShellBackend` (drop in gVisor/Docker for `bash`); process-level via a `WorkerLauncher` (wrap a whole sub-agent worker per leaf). power-loop stays sandbox-agnostic; you choose the policy.
 - 🔬 **Built to be observed.** Typed events for every stream chunk, tool call, round, and **individual LLM call** — each `seq`-ordered + monotonic-clock stamped. Pluggable sinks behind extras: durable **JSONL** (with `replay`), **Prometheus/StatsD** metrics, an **OpenTelemetry** span tree. Per-run + per-session token accounting and hard per-run budgets.
@@ -153,8 +154,8 @@ Most "agent frameworks" ask you to build your app *inside* them. power-loop is t
 | **Workflow resume** | Journals each step; after a crash, replays completed steps and re-runs only the tail | [Workflows](docs/en/user-guide/workflows.md) |
 | **Process sandboxing** | Each workflow leaf in its own OS process + own DB; wrap each in gVisor/Docker per leaf | [Sandboxing](docs/en/user-guide/sandboxing.md) |
 | **Durable timers** | Agents schedule their own wake-ups; survive restarts; one-shot or recurring | [Timers](docs/en/user-guide/timers.md) |
-| **Context compaction** | Auto-summarize old turns (never splits a tool-call pair); `recall_compacted` to pull originals back | [Compaction](docs/en/user-guide/compaction.md) |
-| **Send-context projection** | Opt-in: feed a per-send plain-text projection of finished sends (derived `pl_project_messages`) instead of verbatim history; `pl_messages` stays immutable; `recall_send` to re-expand | [Projection](docs/en/user-guide/send-context-projection.md) |
+| **Context — representation** | Record/render each finished send **verbatim** or as a terse per-send **projection** (derived `pl_project_messages`); `pl_messages` stays immutable; `recall_send` re-expands | [Projection](docs/en/user-guide/send-context-projection.md) |
+| **Context — fold strategy** | Compact older history once over budget: **LLM summary** or **agentic** (also writes notes); pluggable `FoldStrategy`; never splits a tool pair; `recall_compacted` re-expands | [Compaction](docs/en/user-guide/compaction.md) |
 | **Durability ops** | Portable migration-version table, retention/prune, VACUUM, `export_session`/`import_session`, graceful `aclose()` | [Sessions](docs/en/user-guide/sessions.md) |
 | **Observability** | Typed `seq`-ordered events → durable JSONL + `replay`, Prometheus/StatsD metrics, OpenTelemetry spans | [Observability](docs/en/user-guide/observability.md) |
 | **MCP tools** | Surface a Model Context Protocol server's tools as power-loop tools | [Extending](docs/en/user-guide/extending-tools.md) |
@@ -200,6 +201,28 @@ result = await loop.send(user_text, session_id=session_id)
 
 Under the hood the loop keeps a per-session **active-window cache** — but it caches only the *durable* projection, validated by a monotonic `next_seq` token, so it's a pure accelerator: a cold loop with an empty cache produces byte-for-byte the same prompts (proven by a warm-vs-cold conformance test, including the recall/compaction/prompt-edit edge cases).
 
+### Context engineering — two orthogonal axes you choose (and can implement yourself)
+
+Long conversations outgrow the window. Most libraries give you *one* fixed compaction behavior; power-loop (3.0) splits it into two independent, config-driven axes:
+
+- **Representation** — how each *finished send* is recorded & rendered: `VerbatimRepresentation` (full, byte-identical history) or `ProjectedRepresentation` (a terse per-send plain-text projection). The original detail always stays in the immutable `pl_messages` audit log.
+- **Fold strategy** — how *older* history is compacted once the rendered prefix crosses the budget: `LLMSummaryFold` (one summary call) or `AgenticFold` (a bounded tool loop that also persists durable facts as notes).
+
+```python
+from power_loop import (
+    StatefulAgentLoop, AgentLoopConfig,
+    ProjectedRepresentation, AgenticFold,   # mix & match either axis — or pass your own impl
+)
+
+cfg = AgentLoopConfig(
+    representation=ProjectedRepresentation(max_chars=300),  # terse projection (or VerbatimRepresentation)
+    fold_strategy=AgenticFold(keep_last_sends=4),           # summarize older sends + write notes
+)
+loop = StatefulAgentLoop(llm=llm, dsn="app.db", config=cfg)
+```
+
+Any representation composes with any fold strategy, and each axis is a small `Protocol` you can implement yourself. A fold always keeps **whole sends** (it never splits an atomic tool-call/result pair), and the model can call `recall_send(send_index=N)` / `recall_compacted()` to pull the full original detail back from the audit log. (The two classes above are public but **provisional** — added in 3.0, not yet frozen into `STABLE_API`; `AgentLoopConfig` itself is Stable.)
+
 ### Deterministic multi-agent workflows — that the model can author, and that survive a crash
 
 Sub-agent delegation is *model-driven* ("go do this"). When you want **code-driven, deterministic** orchestration — fan out over a list, branch on a result, run a pipeline — describe it as a `WorkflowSpec` and let the engine interpret it. The only LLM calls are the leaves; `sequence`/`parallel`/`foreach`/`branch` are plain code.
@@ -281,7 +304,7 @@ await register_mcp_tools(registry, client, prefix="fs.")   # MCP tools → power
 
 The seam is a tiny `MCPToolSource` Protocol, so the `mcp` SDK is optional and any client works.
 
-> More: hard token budgets, structured output, crash recovery, memory, the blackboard — see [`examples/`](examples/README.md) (40 runnable programs) and the [docs](docs/en/index.md).
+> More: hard token budgets, structured output, crash recovery, memory, the blackboard — see [`examples/`](examples/README.md) (43 runnable programs) and the [docs](docs/en/index.md).
 
 ---
 
@@ -289,7 +312,7 @@ The seam is a tiny `MCPToolSource` Protocol, so the `mcp` SDK is optional and an
 
 power-loop is a **kernel**, not a platform — that's the whole trade-off.
 
-- **vs. LangChain / LangGraph / LlamaIndex / CrewAI / AutoGen** — those are batteries-included frameworks with large ecosystems (connectors, vector stores, integrations) and heavy dependency trees. power-loop deliberately ships **none of that**: a compact (~20k-line) pure-stdlib core with zero runtime dependencies, and you bring your own tools (or an MCP server). You get durable sessions across SQLite/PG/MySQL, crash-resumable workflows, and real sandbox seams out of the box; you do **not** get a bundled RAG stack or 100 connectors.
+- **vs. LangChain / LangGraph / LlamaIndex / CrewAI / AutoGen** — those are batteries-included frameworks with large ecosystems (connectors, vector stores, integrations) and heavy dependency trees. power-loop deliberately ships **none of that**: a compact (~24k-line) pure-stdlib core with zero runtime dependencies, and you bring your own tools (or an MCP server). You get durable sessions across SQLite/PG/MySQL, crash-resumable workflows, and real sandbox seams out of the box; you do **not** get a bundled RAG stack or 100 connectors.
 - **Choose power-loop** when you want to *embed* an agent in an existing app, keep your dependency surface tiny, pick your own database, and care about durability + isolation + a stable contract.
 - **Choose a framework** when you want batteries included, a big integration catalog, and don't mind the weight.
 
@@ -321,7 +344,7 @@ Python 3.10+. See [Getting Started](docs/en/getting-started.md). Optional extras
 
 ## Stability & SemVer
 
-As of **1.0**, the **STABLE** API (listed in `power_loop.STABLE_API`) is under SemVer: a breaking change requires a major bump (`2.0.0`), enforced by a frozen-baseline test in CI — including the flagship `StatefulAgentLoop` *and the LLM contract needed to construct it*. Error `.code` strings are frozen too.
+Since **1.0**, the **STABLE** API (listed in `power_loop.STABLE_API`) is under SemVer: a breaking change requires a major bump, enforced by a frozen-baseline test in CI — including the flagship `StatefulAgentLoop` *and the LLM contract needed to construct it*. Error `.code` strings are frozen too. The two majors since (2.0 pluggable async storage, 3.0 orthogonal context axes) were exactly that policy in action — breaking changes earned a major bump, each documented in the [Changelog](CHANGELOG.md).
 
 | Tier | Meaning |
 |---|---|

{power_loop-3.0.0 → power_loop-3.0.2}/README.md

@@ -33,7 +33,7 @@ print((await loop.send("And my second-favorite?", session_id=sid)).final_text)
 pip install 'power-loop[openai]'      # or [anthropic] · add [postgres] / [mysql] for those backends
 ```
 
-> **1.0 — stable.** The public API is frozen under SemVer (a breaking change requires a major bump), machine-enforced by a baseline guard in CI. The **core has zero runtime dependencies** (pure stdlib; verified by a CI job that imports it with nothing else installed) — LLM transports *and database drivers* are optional extras. See [Stability](#stability--semver) and the [honest caveats](#honest-scope) — a young, single-maintainer project says so plainly.
+> **Stable since 1.0; now 3.x.** The public API is frozen under SemVer and machine-enforced by a baseline guard in CI — and the two major bumps since prove the discipline rather than undercut it: **2.0** moved storage to a pluggable async backend, **3.0** made context handling two orthogonal axes. Both were real breaking changes, so both got a major bump. The **core has zero runtime dependencies** (pure stdlib; verified by a CI job that imports it with nothing else installed) — LLM transports *and database drivers* are optional extras. Backed by **900+ unit tests**, a **live-LLM** suite, and a **3-backend conformance suite** (SQLite/PostgreSQL/MySQL). See [Stability](#stability--semver) and the [honest caveats](#honest-scope) — a young, single-maintainer project says so plainly.
 
 ---
 
@@ -43,7 +43,7 @@ pip install 'power-loop[openai]'      # or [anthropic] · add [postgres] / [mysq
 |---|---|
 | 🚀 **New** — show me the 5-minute version | [Getting Started](docs/en/getting-started.md) |
 | 🛠️ **Learning by building** | [Tutorials](docs/en/tutorials/index.md) — chatbot · tools · human-in-the-loop · multi-agent |
-| 🧩 **Browsing runnable code** | [40 examples](examples/README.md) — `00_hello_world.py` → full chatbot |
+| 🧩 **Browsing runnable code** | [43 examples](examples/README.md) — `00_hello_world.py` → full chatbot |
 | 📚 **Looking something up** | [User Guide](docs/en/user-guide/index.md) · [API reference](docs/en/api/index.md) |
 | 🤔 **Deciding if it fits** | [How it compares](#how-it-compares) · [Honest scope](#honest-scope) |
 
@@ -55,10 +55,11 @@ pip install 'power-loop[openai]'      # or [anthropic] · add [postgres] / [mysq
 
 Most "agent frameworks" ask you to build your app *inside* them. power-loop is the opposite: a **library you embed**. You keep your HTTP layer, your auth, your queues, your RAG, your UI, your deploy. It runs the agent loop — and lets you *engineer* it.
 
-- 🪶 **Featherweight & zero-dependency.** No `pydantic`, no LangChain, no graph DSL. A compact, pure-stdlib core (~20k lines) whose public surface is essentially one class — and **zero runtime dependencies**. LLM transports *and* the Postgres/MySQL drivers are pulled in only by the extra you install.
+- 🪶 **Featherweight & zero-dependency.** No `pydantic`, no LangChain, no graph DSL. A compact, pure-stdlib core (~24k lines) whose public surface is essentially one class — and **zero runtime dependencies**. LLM transports *and* the Postgres/MySQL drivers are pulled in only by the extra you install.
 - 🗄️ **Pluggable storage, zero-infra default.** Sessions, timers, sub-agent trees, workflow journals, the shared blackboard — one backend-neutral store written once against a tiny `Database`/`Dialect` port. The default is **one SQLite file** (copy the file, you've copied the state); point a DSN at **PostgreSQL or MySQL** when you want a real multi-writer server — same code, same conformance suite. Tables are auto-created, or **provisioned out-of-band** with a printed DDL script (see [Storage backends](docs/en/user-guide/storage-backends.md)).
 - ♻️ **Stateless, resumable loops.** A `StatefulAgentLoop` carries no authoritative state — all of it lives in the store. So a loop is cheap to create and trivially **restored from a DSN + a session id** (ideal for web handlers, workers, cold starts). It self-caches each session's active window (a rebuildable accelerator that never changes what the model sees) to skip re-reads on hot paths.
 - ⏱️ **Durable by default.** Crash mid-run and `resume()`. Agents schedule their own **durable timers** that survive restarts. Workflows **replay finished steps and re-run only the unfinished tail** after a process death. The store survives version upgrades (a portable, backend-neutral migration-version table) and can be **pruned, VACUUMed, and exported**.
+- 🧠 **Context engineering, not one fixed strategy.** How each finished send is *recorded/rendered* (**representation**: full **verbatim** or a terse per-send **projection**) and how older history is *compacted* once over budget (**fold strategy**: a single **LLM summary**, or an **agentic** pass that also writes durable notes) are two **orthogonal, config-driven axes** — any representation composes with any fold strategy, and both take your own `Representation` / `FoldStrategy` implementation. Folds always keep whole sends (never split a tool-call/result pair); `recall_send` / `recall_compacted` pull the original detail back from the immutable audit log.
 - 🧩 **Composable from one loop to a fleet.** Start with `send()`. Add tools. Spawn sub-agents. Fan out a deterministic **workflow** (`sequence`/`parallel`/`foreach`/`branch`). Run each leaf in its **own process and DB** behind a sandbox. Same primitives all the way up.
 - 🛡️ **Isolation seams where it counts.** Tool-level sandboxing via a `ShellBackend` (drop in gVisor/Docker for `bash`); process-level via a `WorkerLauncher` (wrap a whole sub-agent worker per leaf). power-loop stays sandbox-agnostic; you choose the policy.
 - 🔬 **Built to be observed.** Typed events for every stream chunk, tool call, round, and **individual LLM call** — each `seq`-ordered + monotonic-clock stamped. Pluggable sinks behind extras: durable **JSONL** (with `replay`), **Prometheus/StatsD** metrics, an **OpenTelemetry** span tree. Per-run + per-session token accounting and hard per-run budgets.
@@ -80,8 +81,8 @@ Most "agent frameworks" ask you to build your app *inside* them. power-loop is t
 | **Workflow resume** | Journals each step; after a crash, replays completed steps and re-runs only the tail | [Workflows](docs/en/user-guide/workflows.md) |
 | **Process sandboxing** | Each workflow leaf in its own OS process + own DB; wrap each in gVisor/Docker per leaf | [Sandboxing](docs/en/user-guide/sandboxing.md) |
 | **Durable timers** | Agents schedule their own wake-ups; survive restarts; one-shot or recurring | [Timers](docs/en/user-guide/timers.md) |
-| **Context compaction** | Auto-summarize old turns (never splits a tool-call pair); `recall_compacted` to pull originals back | [Compaction](docs/en/user-guide/compaction.md) |
-| **Send-context projection** | Opt-in: feed a per-send plain-text projection of finished sends (derived `pl_project_messages`) instead of verbatim history; `pl_messages` stays immutable; `recall_send` to re-expand | [Projection](docs/en/user-guide/send-context-projection.md) |
+| **Context — representation** | Record/render each finished send **verbatim** or as a terse per-send **projection** (derived `pl_project_messages`); `pl_messages` stays immutable; `recall_send` re-expands | [Projection](docs/en/user-guide/send-context-projection.md) |
+| **Context — fold strategy** | Compact older history once over budget: **LLM summary** or **agentic** (also writes notes); pluggable `FoldStrategy`; never splits a tool pair; `recall_compacted` re-expands | [Compaction](docs/en/user-guide/compaction.md) |
 | **Durability ops** | Portable migration-version table, retention/prune, VACUUM, `export_session`/`import_session`, graceful `aclose()` | [Sessions](docs/en/user-guide/sessions.md) |
 | **Observability** | Typed `seq`-ordered events → durable JSONL + `replay`, Prometheus/StatsD metrics, OpenTelemetry spans | [Observability](docs/en/user-guide/observability.md) |
 | **MCP tools** | Surface a Model Context Protocol server's tools as power-loop tools | [Extending](docs/en/user-guide/extending-tools.md) |
@@ -127,6 +128,28 @@ result = await loop.send(user_text, session_id=session_id)
 
 Under the hood the loop keeps a per-session **active-window cache** — but it caches only the *durable* projection, validated by a monotonic `next_seq` token, so it's a pure accelerator: a cold loop with an empty cache produces byte-for-byte the same prompts (proven by a warm-vs-cold conformance test, including the recall/compaction/prompt-edit edge cases).
 
+### Context engineering — two orthogonal axes you choose (and can implement yourself)
+
+Long conversations outgrow the window. Most libraries give you *one* fixed compaction behavior; power-loop (3.0) splits it into two independent, config-driven axes:
+
+- **Representation** — how each *finished send* is recorded & rendered: `VerbatimRepresentation` (full, byte-identical history) or `ProjectedRepresentation` (a terse per-send plain-text projection). The original detail always stays in the immutable `pl_messages` audit log.
+- **Fold strategy** — how *older* history is compacted once the rendered prefix crosses the budget: `LLMSummaryFold` (one summary call) or `AgenticFold` (a bounded tool loop that also persists durable facts as notes).
+
+```python
+from power_loop import (
+    StatefulAgentLoop, AgentLoopConfig,
+    ProjectedRepresentation, AgenticFold,   # mix & match either axis — or pass your own impl
+)
+
+cfg = AgentLoopConfig(
+    representation=ProjectedRepresentation(max_chars=300),  # terse projection (or VerbatimRepresentation)
+    fold_strategy=AgenticFold(keep_last_sends=4),           # summarize older sends + write notes
+)
+loop = StatefulAgentLoop(llm=llm, dsn="app.db", config=cfg)
+```
+
+Any representation composes with any fold strategy, and each axis is a small `Protocol` you can implement yourself. A fold always keeps **whole sends** (it never splits an atomic tool-call/result pair), and the model can call `recall_send(send_index=N)` / `recall_compacted()` to pull the full original detail back from the audit log. (The two classes above are public but **provisional** — added in 3.0, not yet frozen into `STABLE_API`; `AgentLoopConfig` itself is Stable.)
+
 ### Deterministic multi-agent workflows — that the model can author, and that survive a crash
 
 Sub-agent delegation is *model-driven* ("go do this"). When you want **code-driven, deterministic** orchestration — fan out over a list, branch on a result, run a pipeline — describe it as a `WorkflowSpec` and let the engine interpret it. The only LLM calls are the leaves; `sequence`/`parallel`/`foreach`/`branch` are plain code.
@@ -208,7 +231,7 @@ await register_mcp_tools(registry, client, prefix="fs.")   # MCP tools → power
 
 The seam is a tiny `MCPToolSource` Protocol, so the `mcp` SDK is optional and any client works.
 
-> More: hard token budgets, structured output, crash recovery, memory, the blackboard — see [`examples/`](examples/README.md) (40 runnable programs) and the [docs](docs/en/index.md).
+> More: hard token budgets, structured output, crash recovery, memory, the blackboard — see [`examples/`](examples/README.md) (43 runnable programs) and the [docs](docs/en/index.md).
 
 ---
 
@@ -216,7 +239,7 @@ The seam is a tiny `MCPToolSource` Protocol, so the `mcp` SDK is optional and an
 
 power-loop is a **kernel**, not a platform — that's the whole trade-off.
 
-- **vs. LangChain / LangGraph / LlamaIndex / CrewAI / AutoGen** — those are batteries-included frameworks with large ecosystems (connectors, vector stores, integrations) and heavy dependency trees. power-loop deliberately ships **none of that**: a compact (~20k-line) pure-stdlib core with zero runtime dependencies, and you bring your own tools (or an MCP server). You get durable sessions across SQLite/PG/MySQL, crash-resumable workflows, and real sandbox seams out of the box; you do **not** get a bundled RAG stack or 100 connectors.
+- **vs. LangChain / LangGraph / LlamaIndex / CrewAI / AutoGen** — those are batteries-included frameworks with large ecosystems (connectors, vector stores, integrations) and heavy dependency trees. power-loop deliberately ships **none of that**: a compact (~24k-line) pure-stdlib core with zero runtime dependencies, and you bring your own tools (or an MCP server). You get durable sessions across SQLite/PG/MySQL, crash-resumable workflows, and real sandbox seams out of the box; you do **not** get a bundled RAG stack or 100 connectors.
 - **Choose power-loop** when you want to *embed* an agent in an existing app, keep your dependency surface tiny, pick your own database, and care about durability + isolation + a stable contract.
 - **Choose a framework** when you want batteries included, a big integration catalog, and don't mind the weight.
 
@@ -248,7 +271,7 @@ Python 3.10+. See [Getting Started](docs/en/getting-started.md). Optional extras
 
 ## Stability & SemVer
 
-As of **1.0**, the **STABLE** API (listed in `power_loop.STABLE_API`) is under SemVer: a breaking change requires a major bump (`2.0.0`), enforced by a frozen-baseline test in CI — including the flagship `StatefulAgentLoop` *and the LLM contract needed to construct it*. Error `.code` strings are frozen too.
+Since **1.0**, the **STABLE** API (listed in `power_loop.STABLE_API`) is under SemVer: a breaking change requires a major bump, enforced by a frozen-baseline test in CI — including the flagship `StatefulAgentLoop` *and the LLM contract needed to construct it*. Error `.code` strings are frozen too. The two majors since (2.0 pluggable async storage, 3.0 orthogonal context axes) were exactly that policy in action — breaking changes earned a major bump, each documented in the [Changelog](CHANGELOG.md).
 
 | Tier | Meaning |
 |---|---|

{power_loop-3.0.0 → power_loop-3.0.2}/power_loop/__init__.py

@@ -15,7 +15,7 @@ Stability tiers
 无版本承诺，可随时变更或删除。
 """
 
-__version__ = "3.0.0"
+__version__ = "3.0.2"
 
 # Public LLM contract (SDK-free) re-exported so callers (e.g. writing llm.* hooks or
 # a custom LLMService) don't reach into the internal vendored transport package (H3.4).

{power_loop-3.0.0 → power_loop-3.0.2}/power_loop/agent/stateful_loop.py

@@ -774,6 +774,11 @@ class StatefulAgentLoop:
         sink = SQLiteSink(store, session_id)
         sink._unresolved = {str(tc.get("id") or "") for tc in tool_calls}
         sink._assistant_seq = pending.get("assistant_seq")
+        # Prime _tool_calls so a crash mid-abort (after some but not all <aborted> rows land)
+        # persists a CONSISTENT intermediate pending — on_message_appended rebuilds the still-pending
+        # tool_calls from self._tool_calls (sink.py:171-174); left empty it would write
+        # {tool_call_ids:[…], tool_calls:[]}, a self-inconsistent pending.
+        sink._tool_calls = list(tool_calls)
         for tc in tool_calls:
             cid = str(tc.get("id") or "")
             name = _tool_call_name(tc) if "function" in tc or "name" in tc else None
@@ -1056,7 +1061,13 @@ class StatefulAgentLoop:
         if pending.get("pending_interactions"):
             return
         round_index = int(pending.get("round_index") or 0)
-        tool_calls = pending.get("tool_calls") or []
+        # Fall back to tool_call_ids (as abort_pending / _prime_sink_from_pending do): a pending that
+        # carries only ids (e.g. a crash mid-abort left {tool_call_ids:[…], tool_calls:[]}) must
+        # still be resolved here, else resume() returns "completed" while the pending stays set and
+        # the session is permanently stranded.
+        tool_calls = pending.get("tool_calls") or [
+            {"id": cid} for cid in (pending.get("tool_call_ids") or [])
+        ]
         if not tool_calls:
             return
         # Initialize sink's in-memory unresolved set so auto-resolve works.
@@ -1064,6 +1075,19 @@ class StatefulAgentLoop:
         for tc in tool_calls:
             cid = str(tc.get("id") or "")
             name = _tool_call_name(tc)
+            if name is None:
+                # Reconstructed from ids only — no name/args to replay. Resolve the protocol with an
+                # aborted marker (clears unresolved → pending cleared) instead of stranding.
+                await sink.on_message_appended(
+                    {
+                        "role": "tool",
+                        "tool_call_id": cid,
+                        "name": None,
+                        "content": "<aborted: unrecoverable tool_call on resume>",
+                    },
+                    round_index=round_index,
+                )
+                continue
             args = _tool_call_args(tc)
             if self.tool_registry is None:
                 output, failed = (
@@ -1511,19 +1535,26 @@ class StatefulAgentLoop:
                     llm=self.llm, max_tokens=self.config.max_tokens,
                 ),
             )
+        fold_as_project: list[int] = []
         if folded is not None:
             from_send = 0 if note is not None else (min(fold) if fold else 0)
             compact_tuple = (folded.content, folded.rendered_text, from_send, folded.folded_to_send)
             migration_note_ops = list(folded.note_ops)
-        elif note is not None:
-            # Only the note, nothing foldable beyond keep → preserve the note as a standalone
-            # compact sitting just before the kept tail (or the current send).
-            to_send = (min(recent) - 1) if recent else (current_send_index - 1)
-            compact_tuple = ({"summary": note.content or ""}, None, 0, max(0, to_send))
+        else:
+            # The fold soft-failed (LLM error/timeout/empty) OR nothing was foldable. Do NOT write a
+            # compact that claims to COVER sends it never merged — the reader uses compact_to_send as
+            # the exclusion cutoff, so an over-claiming range silently drops real history (B4), and a
+            # marker-set no-op drops compression forever (B13). Instead preserve everything: keep the
+            # note as a standalone compact that covers NO real send (to_send=0), and write the
+            # would-be-folded sends as individual project rows. A later end-of-send fold compresses
+            # them (rolling this note compact forward) once over budget.
+            if note is not None:
+                compact_tuple = ({"summary": note.content or ""}, None, 0, 0)
+            fold_as_project = fold
 
         project_rows = [
             (si, pr.kind, pr.content, pr.rendered_text)
-            for si in recent
+            for si in (fold_as_project + recent)
             for pr in projected[si].rows
         ]
         # Mark migrated in the SAME transaction as the rows (atomic): a crash can't leave the

{power_loop-3.0.0 → power_loop-3.0.2}/power_loop/agent/types.py

@@ -35,7 +35,11 @@ def _fold_from_legacy_projector(proj: Any) -> FoldStrategy:
     admin-configured projection settings). Without this the mapped fold would silently use
     ``LLMSummaryFold`` defaults (4 / 0.75) and ignore the operator's config."""
     from power_loop.runtime.fold import LLMSummaryFold
-    keep = max(1, int(getattr(proj, "keep_last_sends", 4) or 4))
+    # Only a MISSING/None keep falls back to 4; an explicit 0 means "keep ~none" (fold aggressively)
+    # → clamp to the validator's floor of 1, NOT silently to 4 (B10). (A verbatim keep==0 projector is
+    # routed to never-fold in _map_legacy_axes and never reaches here.)
+    keep_raw = getattr(proj, "keep_last_sends", None)
+    keep = 4 if keep_raw is None else max(1, int(keep_raw))
     trigger = float(getattr(proj, "trigger_ratio", 0.75) or 0.75)
     return LLMSummaryFold(keep_last_sends=keep, trigger_ratio=trigger)
 
@@ -172,6 +176,17 @@ class AgentLoopConfig:
         # stray legacy compactor= must NOT silently disable it.
         if legacy_comp is not _UNSET and legacy_proj in (_UNSET, None) and fold_was_unset:
             object.__setattr__(self, "_legacy_verbatim_compactor", legacy_comp)
+        elif (
+            legacy_proj not in (_UNSET, None)
+            and fold_was_unset
+            and getattr(legacy_proj, "kind", None) == "verbatim"
+            and getattr(legacy_proj, "keep_last_sends", 1) == 0  # exact 0 (NOT `or 1`, which 0 defeats)
+        ):
+            # A legacy NEVER-FOLD projector (IdentityProjector: kind='verbatim', keep_last_sends==0)
+            # maps to never-fold (compactor=None) — NOT a folding fold_strategy. Else it would fold
+            # (the seeder coerces keep 0→positive) and, on the old projection path, drop the compact
+            # (B7 data loss). Routes via resolve_compactor's verbatim branch (kind=='verbatim').
+            object.__setattr__(self, "_legacy_verbatim_compactor", None)
         else:
             object.__setattr__(self, "_legacy_verbatim_compactor", _UNSET)
         if self.migrate_history_on_projection_switch is not _UNSET:

{power_loop-3.0.0 → power_loop-3.0.2}/power_loop/runtime/history_projector.py

@@ -173,6 +173,7 @@ class IdentityProjector:
     with this projector sees byte-identical history to the no-projector default. Useful to
     prove the projection seam itself introduces no behavior change."""
 
+    kind: str = "verbatim"  # routes to the safe in-place (verbatim) path, never the projection fold
     version: int = 1
     keep_last_sends: int = 0  # verbatim mode never folds
     trigger_ratio: float = 0.75  # unused (keep_last_sends==0 short-circuits folding); for Protocol parity
@@ -197,6 +198,14 @@ class IdentityProjector:
     def render(self, rows: list[ProjectMessageRow]) -> list[LoopMessage]:
         out: list[LoopMessage] = []
         for r in rows:
+            # Defensive: even though this projector never folds, a compact row could reach render
+            # via a mode switch / legacy mapping — render its summary instead of silently dropping it
+            # (the 3.0 invariant: every representation's render MUST handle kind=='compact').
+            if getattr(r, "kind", None) == "compact":
+                summary = (r.content or {}).get("summary")
+                if summary:
+                    out.append({"role": "user", "content": str(summary)})
+                continue
             out.extend((r.content or {}).get("messages") or [])
         return out
 

{power_loop-3.0.0 → power_loop-3.0.2}/power_loop/runtime/representation.py

@@ -260,15 +260,32 @@ class ProjectedRepresentation:
 
     # rendering ----------------------------------------------------------------
     def render(self, rows: list[ProjectMessageRow]) -> list[LoopMessage]:
+        # Each rendered send is tagged with its ``#N`` send_index so the model can call
+        # recall_send(send_index=N) on a folded/compacted earlier turn — the tool docstring and the
+        # host's RECALL_SEND_NOTE both tell it to use "the #N the summary shows", so render MUST
+        # actually emit them (else recall_send is undiscoverable). The folded compact carries its
+        # covered range.
         out: list[LoopMessage] = []
         for r in rows:
+            si = r.send_index
             if r.kind == "user":
                 humans = (r.content or {}).get("human") or []
-                out.append({"role": "user", "content": "\n".join(str(h) for h in humans)})
+                tag = f"[#{si}] " if si is not None else ""
+                out.append({"role": "user", "content": tag + "\n".join(str(h) for h in humans)})
             elif r.kind == "project":
-                out.append({"role": "assistant", "content": self._render_project(r.content)})
+                tag = f"#{si} " if si is not None else ""
+                out.append({"role": "assistant", "content": tag + self._render_project(r.content)})
             elif r.kind == "compact":
-                out.append(_render_compact_row(r))
+                msg = _render_compact_row(r)
+                lo, hi = r.compact_from_send, r.compact_to_send
+                if lo is not None and hi is not None and hi >= lo > 0:
+                    rng = f"#{lo}" if lo == hi else f"#{lo}–#{hi}"
+                    msg = {
+                        "role": "user",
+                        "content": f"[older sends {rng} folded — recall_send(send_index=N) to "
+                        f"expand]\n{msg['content']}",
+                    }
+                out.append(msg)
         return out
 
     def _render_tool(self, t: dict[str, Any]) -> str:

{power_loop-3.0.0 → power_loop-3.0.2}/power_loop/runtime/store/dialect.py

@@ -356,7 +356,7 @@ class MySQLDialect:
                 status VARCHAR(32) NOT NULL, return_code BIGINT, output_tail TEXT, output_path TEXT,
                 last_seen_at BIGINT NOT NULL DEFAULT 0, created_at BIGINT NOT NULL,
                 updated_at BIGINT NOT NULL, PRIMARY KEY (session_id, task_id),
-                KEY {p}idx_bgtasks_session_status (session_id, status, updated_at)) {opts}""",
+                KEY {p}idx_background_tasks_session_status (session_id, status, updated_at)) {opts}""",
             f"""CREATE TABLE IF NOT EXISTS {p}session_stats (
                 session_id VARCHAR(255) NOT NULL, sends BIGINT NOT NULL DEFAULT 0,
                 rounds BIGINT NOT NULL DEFAULT 0, llm_calls BIGINT NOT NULL DEFAULT 0,

{power_loop-3.0.0 → power_loop-3.0.2}/power_loop/runtime/store/schema.py

@@ -243,7 +243,16 @@ async def _column_exists(tx: Transaction, dialect_name: str, table: str, column:
         rows = await tx.fetchall(f"PRAGMA table_info({table})")
         return any(r["name"] == column for r in rows)
     if dialect_name in ("postgres", "mysql"):
-        scope = "AND table_schema=DATABASE() " if dialect_name == "mysql" else ""
+        # Scope to the CURRENT schema — otherwise a same-named table in ANOTHER schema (PG
+        # search_path / multi-schema deployments) makes the probe return True for a column the
+        # current-schema table lacks, so the ALTER … ADD COLUMN is skipped but the version is still
+        # stamped → every subsequent append referencing that column crashes. Mirrors _table_exists
+        # (PG to_regclass honors search_path; MySQL DATABASE()).
+        scope = (
+            "AND table_schema=current_schema() "
+            if dialect_name == "postgres"
+            else "AND table_schema=DATABASE() "
+        )
         row = await tx.fetchone(
             "SELECT 1 AS present FROM information_schema.columns "
             f"WHERE table_name=? {scope}AND column_name=?",

{power_loop-3.0.0 → power_loop-3.0.2}/power_loop/tools/default_tools.py

@@ -310,7 +310,14 @@ def _validate_bash_command_scope(command: str) -> str | None:
             "Error: Reading agent-home internals is blocked outside allowlisted paths (.cache/logs/skills). "
             "Use load_skill(name) for skill content instead of direct file reads."
         )
-    return None
+    # DEFAULT-DENY: the command references POWER_LOOP_HOME, is NOT under an allowlisted path, and
+    # matched none of the verb hints above — but the hint lists are not exhaustive (awk / base64 / od
+    # / python -c / dd of= / truncate / ln -s all reach agent-home undetected). Refuse rather than
+    # fall through to "allow", since the resolved target is provably an un-allowlisted home path.
+    return (
+        "Error: Accessing POWER_LOOP_HOME is blocked outside allowlisted paths (.cache/logs/skills). "
+        "Use workspace files or allowlisted agent paths only."
+    )
 
 
 def _dangerous_command_reason(command: str) -> str | None:

{power_loop-3.0.0 → power_loop-3.0.2}/power_loop/workflow/runner.py

@@ -249,18 +249,33 @@ def make_wake_guard(store: Any):
     once (timers are at-least-once). Ignores non-workflow timers. Async because the
     store is async; ``run_typed_async`` awaits it."""
 
+    from power_loop.runtime.store.store import MUTATE_SKIP
+
     async def guard(ctx: TimerFireCtx) -> None:
         run_id = _parse_run_id(ctx.note)
         if run_id is None:
             return  # not a workflow timer → CONTINUE
-        j = await store.get_runtime_state(ctx.session_id, journal.run_key(run_id), default=None)
-        if j is None:
-            return
-        if j.get("woke"):
-            ctx.directive = HookDirective.SKIP  # already delivered once
-            return
-        j["woke"] = True
-        await store.set_runtime_state(ctx.session_id, journal.run_key(run_id), j)
+        # Claim the wake ATOMICALLY: a bare get→set RMW races a concurrent journal write
+        # (journal.update / record_step funnel through mutate_runtime_state on the SAME run key) —
+        # the guard's set would clobber that write, and two concurrent fires could both observe
+        # woke=False → double-wake. mutate_runtime_state is row-locked, so the claim is exclusive.
+        seen = {"woke": False}
+
+        def _claim(cur: Any) -> Any:
+            if cur is None:
+                return MUTATE_SKIP  # no journal → CONTINUE (nothing to dedupe)
+            if cur.get("woke"):
+                seen["woke"] = True
+                return MUTATE_SKIP  # already delivered once
+            return {**cur, "woke": True}  # first delivery — set woke, preserve every other key
+
+        try:
+            await store.mutate_runtime_state(ctx.session_id, journal.run_key(run_id), _claim, default=None)
+        except ValueError:
+            return  # session/state row gone (a stale timer firing on a deleted session) → CONTINUE,
+            # matching the old get_runtime_state(default=None) tolerance; nothing to dedupe.
+        if seen["woke"]:
+            ctx.directive = HookDirective.SKIP
 
     return guard
 

{power_loop-3.0.0 → power_loop-3.0.2}/power_loop.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: power-loop
-Version: 3.0.0
+Version: 3.0.2
 Summary: Embeddable agent execution kernel — LLM loop, hooks, events, tools, dynamic sub-agents.
 Author-email: zhangran <zhangran24@126.com>
 License: MIT
@@ -106,7 +106,7 @@ print((await loop.send("And my second-favorite?", session_id=sid)).final_text)
 pip install 'power-loop[openai]'      # or [anthropic] · add [postgres] / [mysql] for those backends
 ```
 
-> **1.0 — stable.** The public API is frozen under SemVer (a breaking change requires a major bump), machine-enforced by a baseline guard in CI. The **core has zero runtime dependencies** (pure stdlib; verified by a CI job that imports it with nothing else installed) — LLM transports *and database drivers* are optional extras. See [Stability](#stability--semver) and the [honest caveats](#honest-scope) — a young, single-maintainer project says so plainly.
+> **Stable since 1.0; now 3.x.** The public API is frozen under SemVer and machine-enforced by a baseline guard in CI — and the two major bumps since prove the discipline rather than undercut it: **2.0** moved storage to a pluggable async backend, **3.0** made context handling two orthogonal axes. Both were real breaking changes, so both got a major bump. The **core has zero runtime dependencies** (pure stdlib; verified by a CI job that imports it with nothing else installed) — LLM transports *and database drivers* are optional extras. Backed by **900+ unit tests**, a **live-LLM** suite, and a **3-backend conformance suite** (SQLite/PostgreSQL/MySQL). See [Stability](#stability--semver) and the [honest caveats](#honest-scope) — a young, single-maintainer project says so plainly.
 
 ---
 
@@ -116,7 +116,7 @@ pip install 'power-loop[openai]'      # or [anthropic] · add [postgres] / [mysq
 |---|---|
 | 🚀 **New** — show me the 5-minute version | [Getting Started](docs/en/getting-started.md) |
 | 🛠️ **Learning by building** | [Tutorials](docs/en/tutorials/index.md) — chatbot · tools · human-in-the-loop · multi-agent |
-| 🧩 **Browsing runnable code** | [40 examples](examples/README.md) — `00_hello_world.py` → full chatbot |
+| 🧩 **Browsing runnable code** | [43 examples](examples/README.md) — `00_hello_world.py` → full chatbot |
 | 📚 **Looking something up** | [User Guide](docs/en/user-guide/index.md) · [API reference](docs/en/api/index.md) |
 | 🤔 **Deciding if it fits** | [How it compares](#how-it-compares) · [Honest scope](#honest-scope) |
 
@@ -128,10 +128,11 @@ pip install 'power-loop[openai]'      # or [anthropic] · add [postgres] / [mysq
 
 Most "agent frameworks" ask you to build your app *inside* them. power-loop is the opposite: a **library you embed**. You keep your HTTP layer, your auth, your queues, your RAG, your UI, your deploy. It runs the agent loop — and lets you *engineer* it.
 
-- 🪶 **Featherweight & zero-dependency.** No `pydantic`, no LangChain, no graph DSL. A compact, pure-stdlib core (~20k lines) whose public surface is essentially one class — and **zero runtime dependencies**. LLM transports *and* the Postgres/MySQL drivers are pulled in only by the extra you install.
+- 🪶 **Featherweight & zero-dependency.** No `pydantic`, no LangChain, no graph DSL. A compact, pure-stdlib core (~24k lines) whose public surface is essentially one class — and **zero runtime dependencies**. LLM transports *and* the Postgres/MySQL drivers are pulled in only by the extra you install.
 - 🗄️ **Pluggable storage, zero-infra default.** Sessions, timers, sub-agent trees, workflow journals, the shared blackboard — one backend-neutral store written once against a tiny `Database`/`Dialect` port. The default is **one SQLite file** (copy the file, you've copied the state); point a DSN at **PostgreSQL or MySQL** when you want a real multi-writer server — same code, same conformance suite. Tables are auto-created, or **provisioned out-of-band** with a printed DDL script (see [Storage backends](docs/en/user-guide/storage-backends.md)).
 - ♻️ **Stateless, resumable loops.** A `StatefulAgentLoop` carries no authoritative state — all of it lives in the store. So a loop is cheap to create and trivially **restored from a DSN + a session id** (ideal for web handlers, workers, cold starts). It self-caches each session's active window (a rebuildable accelerator that never changes what the model sees) to skip re-reads on hot paths.
 - ⏱️ **Durable by default.** Crash mid-run and `resume()`. Agents schedule their own **durable timers** that survive restarts. Workflows **replay finished steps and re-run only the unfinished tail** after a process death. The store survives version upgrades (a portable, backend-neutral migration-version table) and can be **pruned, VACUUMed, and exported**.
+- 🧠 **Context engineering, not one fixed strategy.** How each finished send is *recorded/rendered* (**representation**: full **verbatim** or a terse per-send **projection**) and how older history is *compacted* once over budget (**fold strategy**: a single **LLM summary**, or an **agentic** pass that also writes durable notes) are two **orthogonal, config-driven axes** — any representation composes with any fold strategy, and both take your own `Representation` / `FoldStrategy` implementation. Folds always keep whole sends (never split a tool-call/result pair); `recall_send` / `recall_compacted` pull the original detail back from the immutable audit log.
 - 🧩 **Composable from one loop to a fleet.** Start with `send()`. Add tools. Spawn sub-agents. Fan out a deterministic **workflow** (`sequence`/`parallel`/`foreach`/`branch`). Run each leaf in its **own process and DB** behind a sandbox. Same primitives all the way up.
 - 🛡️ **Isolation seams where it counts.** Tool-level sandboxing via a `ShellBackend` (drop in gVisor/Docker for `bash`); process-level via a `WorkerLauncher` (wrap a whole sub-agent worker per leaf). power-loop stays sandbox-agnostic; you choose the policy.
 - 🔬 **Built to be observed.** Typed events for every stream chunk, tool call, round, and **individual LLM call** — each `seq`-ordered + monotonic-clock stamped. Pluggable sinks behind extras: durable **JSONL** (with `replay`), **Prometheus/StatsD** metrics, an **OpenTelemetry** span tree. Per-run + per-session token accounting and hard per-run budgets.
@@ -153,8 +154,8 @@ Most "agent frameworks" ask you to build your app *inside* them. power-loop is t
 | **Workflow resume** | Journals each step; after a crash, replays completed steps and re-runs only the tail | [Workflows](docs/en/user-guide/workflows.md) |
 | **Process sandboxing** | Each workflow leaf in its own OS process + own DB; wrap each in gVisor/Docker per leaf | [Sandboxing](docs/en/user-guide/sandboxing.md) |
 | **Durable timers** | Agents schedule their own wake-ups; survive restarts; one-shot or recurring | [Timers](docs/en/user-guide/timers.md) |
-| **Context compaction** | Auto-summarize old turns (never splits a tool-call pair); `recall_compacted` to pull originals back | [Compaction](docs/en/user-guide/compaction.md) |
-| **Send-context projection** | Opt-in: feed a per-send plain-text projection of finished sends (derived `pl_project_messages`) instead of verbatim history; `pl_messages` stays immutable; `recall_send` to re-expand | [Projection](docs/en/user-guide/send-context-projection.md) |
+| **Context — representation** | Record/render each finished send **verbatim** or as a terse per-send **projection** (derived `pl_project_messages`); `pl_messages` stays immutable; `recall_send` re-expands | [Projection](docs/en/user-guide/send-context-projection.md) |
+| **Context — fold strategy** | Compact older history once over budget: **LLM summary** or **agentic** (also writes notes); pluggable `FoldStrategy`; never splits a tool pair; `recall_compacted` re-expands | [Compaction](docs/en/user-guide/compaction.md) |
 | **Durability ops** | Portable migration-version table, retention/prune, VACUUM, `export_session`/`import_session`, graceful `aclose()` | [Sessions](docs/en/user-guide/sessions.md) |
 | **Observability** | Typed `seq`-ordered events → durable JSONL + `replay`, Prometheus/StatsD metrics, OpenTelemetry spans | [Observability](docs/en/user-guide/observability.md) |
 | **MCP tools** | Surface a Model Context Protocol server's tools as power-loop tools | [Extending](docs/en/user-guide/extending-tools.md) |
@@ -200,6 +201,28 @@ result = await loop.send(user_text, session_id=session_id)
 
 Under the hood the loop keeps a per-session **active-window cache** — but it caches only the *durable* projection, validated by a monotonic `next_seq` token, so it's a pure accelerator: a cold loop with an empty cache produces byte-for-byte the same prompts (proven by a warm-vs-cold conformance test, including the recall/compaction/prompt-edit edge cases).
 
+### Context engineering — two orthogonal axes you choose (and can implement yourself)
+
+Long conversations outgrow the window. Most libraries give you *one* fixed compaction behavior; power-loop (3.0) splits it into two independent, config-driven axes:
+
+- **Representation** — how each *finished send* is recorded & rendered: `VerbatimRepresentation` (full, byte-identical history) or `ProjectedRepresentation` (a terse per-send plain-text projection). The original detail always stays in the immutable `pl_messages` audit log.
+- **Fold strategy** — how *older* history is compacted once the rendered prefix crosses the budget: `LLMSummaryFold` (one summary call) or `AgenticFold` (a bounded tool loop that also persists durable facts as notes).
+
+```python
+from power_loop import (
+    StatefulAgentLoop, AgentLoopConfig,
+    ProjectedRepresentation, AgenticFold,   # mix & match either axis — or pass your own impl
+)
+
+cfg = AgentLoopConfig(
+    representation=ProjectedRepresentation(max_chars=300),  # terse projection (or VerbatimRepresentation)
+    fold_strategy=AgenticFold(keep_last_sends=4),           # summarize older sends + write notes
+)
+loop = StatefulAgentLoop(llm=llm, dsn="app.db", config=cfg)
+```
+
+Any representation composes with any fold strategy, and each axis is a small `Protocol` you can implement yourself. A fold always keeps **whole sends** (it never splits an atomic tool-call/result pair), and the model can call `recall_send(send_index=N)` / `recall_compacted()` to pull the full original detail back from the audit log. (The two classes above are public but **provisional** — added in 3.0, not yet frozen into `STABLE_API`; `AgentLoopConfig` itself is Stable.)
+
 ### Deterministic multi-agent workflows — that the model can author, and that survive a crash
 
 Sub-agent delegation is *model-driven* ("go do this"). When you want **code-driven, deterministic** orchestration — fan out over a list, branch on a result, run a pipeline — describe it as a `WorkflowSpec` and let the engine interpret it. The only LLM calls are the leaves; `sequence`/`parallel`/`foreach`/`branch` are plain code.
@@ -281,7 +304,7 @@ await register_mcp_tools(registry, client, prefix="fs.")   # MCP tools → power
 
 The seam is a tiny `MCPToolSource` Protocol, so the `mcp` SDK is optional and any client works.
 
-> More: hard token budgets, structured output, crash recovery, memory, the blackboard — see [`examples/`](examples/README.md) (40 runnable programs) and the [docs](docs/en/index.md).
+> More: hard token budgets, structured output, crash recovery, memory, the blackboard — see [`examples/`](examples/README.md) (43 runnable programs) and the [docs](docs/en/index.md).
 
 ---
 
@@ -289,7 +312,7 @@ The seam is a tiny `MCPToolSource` Protocol, so the `mcp` SDK is optional and an
 
 power-loop is a **kernel**, not a platform — that's the whole trade-off.
 
-- **vs. LangChain / LangGraph / LlamaIndex / CrewAI / AutoGen** — those are batteries-included frameworks with large ecosystems (connectors, vector stores, integrations) and heavy dependency trees. power-loop deliberately ships **none of that**: a compact (~20k-line) pure-stdlib core with zero runtime dependencies, and you bring your own tools (or an MCP server). You get durable sessions across SQLite/PG/MySQL, crash-resumable workflows, and real sandbox seams out of the box; you do **not** get a bundled RAG stack or 100 connectors.
+- **vs. LangChain / LangGraph / LlamaIndex / CrewAI / AutoGen** — those are batteries-included frameworks with large ecosystems (connectors, vector stores, integrations) and heavy dependency trees. power-loop deliberately ships **none of that**: a compact (~24k-line) pure-stdlib core with zero runtime dependencies, and you bring your own tools (or an MCP server). You get durable sessions across SQLite/PG/MySQL, crash-resumable workflows, and real sandbox seams out of the box; you do **not** get a bundled RAG stack or 100 connectors.
 - **Choose power-loop** when you want to *embed* an agent in an existing app, keep your dependency surface tiny, pick your own database, and care about durability + isolation + a stable contract.
 - **Choose a framework** when you want batteries included, a big integration catalog, and don't mind the weight.
 
@@ -321,7 +344,7 @@ Python 3.10+. See [Getting Started](docs/en/getting-started.md). Optional extras
 
 ## Stability & SemVer
 
-As of **1.0**, the **STABLE** API (listed in `power_loop.STABLE_API`) is under SemVer: a breaking change requires a major bump (`2.0.0`), enforced by a frozen-baseline test in CI — including the flagship `StatefulAgentLoop` *and the LLM contract needed to construct it*. Error `.code` strings are frozen too.
+Since **1.0**, the **STABLE** API (listed in `power_loop.STABLE_API`) is under SemVer: a breaking change requires a major bump, enforced by a frozen-baseline test in CI — including the flagship `StatefulAgentLoop` *and the LLM contract needed to construct it*. Error `.code` strings are frozen too. The two majors since (2.0 pluggable async storage, 3.0 orthogonal context axes) were exactly that policy in action — breaking changes earned a major bump, each documented in the [Changelog](CHANGELOG.md).
 
 | Tier | Meaning |
 |---|---|