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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: power-loop
-Version: 2.2.0
+Version: 3.0.0
 Summary: Embeddable agent execution kernel — LLM loop, hooks, events, tools, dynamic sub-agents.
 Author-email: zhangran <zhangran24@126.com>
 License: MIT

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

@@ -15,7 +15,7 @@ Stability tiers
 无版本承诺，可随时变更或删除。
 """
 
-__version__ = "2.2.0"
+__version__ = "3.0.0"
 
 # 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).
@@ -145,13 +145,13 @@ from power_loop.runtime.exec_backend import (
     LocalShellBackend,
     ShellBackend,
 )
-from power_loop.runtime.history_projector import (
-    DefaultDeterministicProjector,
-    HistoryProjector,
-    IdentityProjector,
-    ProjectedCompact,
-    ProjectedRow,
-    ProjectedSend,
+from power_loop.runtime.fold import (
+    AgenticFold,
+    FoldContext,
+    FoldResult,
+    FoldStrategy,
+    LLMSummaryFold,
+    NoteOp,
 )
 from power_loop.runtime.human_input import HumanInputRequired, request_user_input
 from power_loop.runtime.memory import MemoryProvider, MemorySnapshot, tag_as_memory
@@ -167,6 +167,13 @@ from power_loop.runtime.provider import (
     create_llm_service_from_config,
     create_llm_service_from_env,
 )
+from power_loop.runtime.representation import (
+    ProjectedRepresentation,
+    ProjectedRow,
+    ProjectedSend,
+    Representation,
+    VerbatimRepresentation,
+)
 from power_loop.runtime.retry import LLMRetryPolicy, with_retry
 from power_loop.runtime.runtime_state import (
     BackgroundRuntimeProjector,
@@ -320,12 +327,17 @@ __all__ = [
 	"BackgroundRuntimeProjector",
 	"default_runtime_projectors",
 	"get_tool_runtime_context",
-	"HistoryProjector",
-	"IdentityProjector",
-	"DefaultDeterministicProjector",
+	"Representation",
+	"VerbatimRepresentation",
+	"ProjectedRepresentation",
+	"FoldStrategy",
+	"FoldContext",
+	"FoldResult",
+	"NoteOp",
+	"LLMSummaryFold",
+	"AgenticFold",
 	"ProjectedSend",
 	"ProjectedRow",
-	"ProjectedCompact",
 	"ProjectMessageRow",
 	"CancellationToken",
 	"CancellationLike",

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

@@ -69,7 +69,7 @@ from power_loop.runtime.store.types import (
 from power_loop.tools.registry import ToolRegistry
 
 if TYPE_CHECKING:
-    from power_loop.runtime.history_projector import HistoryProjector
+    from power_loop.runtime.representation import Representation
 
 logger = logging.getLogger(__name__)
 
@@ -1113,7 +1113,10 @@ class StatefulAgentLoop:
         system_prompt: str | None = None,
     ) -> StatefulResult:
         store = await self._ensure_store()
-        projector = self.config.history_projector
+        # 3.0: projection-style representation drives the derived-layer path; verbatim → None
+        # (in-place compactor path). The fold trigger/keep come from config.fold_strategy.
+        projector = self.config.projection_representation
+        fold_strategy = self.config.fold_strategy
         # The current send's authoritative index (set by _persist_user_input; inherited by
         # resume()/follow-up). Read up-front so projection mode can partition history by it.
         si = await store.get_runtime_state(sid, "send_index", default=0)
@@ -1149,10 +1152,10 @@ class StatefulAgentLoop:
                     "history_mode": current_mode,
                     "projector_version": int(getattr(projector, "version", 0) or 0) if projector else None,
                     "projector_trigger_ratio": (
-                        float(getattr(projector, "trigger_ratio", 0) or 0) if projector else None
+                        float(getattr(fold_strategy, "trigger_ratio", 0) or 0) if projector else None
                     ),
                     "projector_keep_last_sends": (
-                        int(getattr(projector, "keep_last_sends", 0) or 0) if projector else None
+                        int(getattr(fold_strategy, "keep_last_sends", 0) or 0) if projector else None
                     ),
                 })
             elif recorded != current_mode:
@@ -1178,7 +1181,7 @@ class StatefulAgentLoop:
                     "send_index — resume before any send); best-effort.", sid,
                 )
                 projection_active = False
-            elif not migrated and self.config.migrate_history_on_projection_switch:
+            elif not migrated and self.config.migrate_history_on_switch:
                 # One-time migration: a session with prior NON-projection history opened in
                 # projection mode. Fold that prior history into the projection table so it becomes
                 # projection-native (a compact + the recent keep_last_sends as project rows) rather
@@ -1443,7 +1446,7 @@ class StatefulAgentLoop:
         self,
         store: SessionStore,
         sid: str,
-        projector: HistoryProjector,
+        projector: Representation,
         *,
         current_send_index: int,
         active_rows: list[Any],
@@ -1452,12 +1455,12 @@ class StatefulAgentLoop:
         projection table so it becomes projection-native (starts with a ``compact`` covering the
         old sends, plus the most-recent ``keep_last_sends`` as individual project rows). Handles
         both a clean default→projection switch (no projection rows yet) and a session the in-place
-        compactor had folded (its ``compact_note`` summary seeds the projection compact). Uses
-        ``projector.compact`` for the fold, so it auto-uses whatever projector is configured. Never
-        raises (the caller swallows + sets the migrated marker only on success)."""
+        compactor had folded (its ``compact_note`` summary seeds the projection compact). Folds via
+        the configured ``fold_strategy`` (bounded by ``fold_timeout_s``, OUTSIDE the migration write
+        lock). Never raises (the caller swallows + sets the migrated marker only on success)."""
         from power_loop.runtime.store.types import ProjectMessageRow
 
-        keep = max(int(getattr(projector, "keep_last_sends", 0) or 0), 0)
+        keep = max(int(getattr(self.config.fold_strategy, "keep_last_sends", 0) or 0), 0)
         version = int(getattr(projector, "version", 0) or 0)
         note = next((r for r in active_rows if r.name == "compact_note"), None)
         by_send: dict[int, list[Any]] = {}
@@ -1485,7 +1488,7 @@ class StatefulAgentLoop:
             )
 
         # Build the seed compact: the in-place compactor's note (if any) rolled forward + the
-        # folded sends, via projector.compact (deterministic for the default projector).
+        # folded sends, via the configured fold_strategy (run below with the fold timeout).
         to_compact: list[ProjectMessageRow] = []
         if note is not None:
             to_compact.append(_pm(0, "compact", {"summary": note.content or ""}))
@@ -1493,14 +1496,25 @@ class StatefulAgentLoop:
             for pr in projected[si].rows:
                 to_compact.append(_pm(si, pr.kind, pr.content))
         compact_tuple: tuple[Any, str | None, int, int] | None = None
-        folded = (
-            projector.compact(to_compact)
-            if any(r.kind in ("user", "project") for r in to_compact)
-            else None
-        )
+        migration_note_ops: list[Any] = []
+        folded = None
+        if any(r.kind in ("user", "project") for r in to_compact):
+            from power_loop.runtime.fold import FoldContext
+
+            # Same fold-timeout guard as the end-of-send path (this runs OUTSIDE the migration's
+            # write lock — write_projection_migration is called afterwards with the result).
+            folded = await self._run_fold_with_timeout(
+                self.config.fold_strategy,
+                to_compact,
+                FoldContext(
+                    session_id=sid, round_index=0, representation=projector,
+                    llm=self.llm, max_tokens=self.config.max_tokens,
+                ),
+            )
         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, max(fold))
+            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).
@@ -1518,6 +1532,14 @@ class StatefulAgentLoop:
             sid, project_rows=project_rows, compact=compact_tuple, projector_version=version,
             metadata_patch={"projection_migrated": current_send_index},
         )
+        for op in migration_note_ops:  # agentic-fold facts from the migrated history (best-effort)
+            try:
+                if getattr(op, "op", None) == "add":
+                    await store.add_note(sid, op.content or "", pinned=bool(op.pinned))
+                elif getattr(op, "op", None) == "update":
+                    await store.update_note(sid, op.note_id, content=op.content, pinned=op.pinned)
+            except Exception:
+                logger.exception("session %s: migration note op failed (continuing)", sid)
 
     async def _write_send_projection(
         self,
@@ -1527,7 +1549,7 @@ class StatefulAgentLoop:
         send_index: int,
         status: str,
         session_row: SessionRow | None,
-        projector: HistoryProjector,
+        projector: Representation,
         tool_registry: ToolRegistry | None,
     ) -> None:
         """Project the just-finished send's ``pl_messages`` rows into ``pl_project_messages`` (v2).
@@ -1550,70 +1572,105 @@ class StatefulAgentLoop:
         version = int(getattr(projector, "version", 0) or 0)
         proj_rows_to_write = [(pr.kind, pr.content, pr.rendered_text) for pr in projected.rows]
 
-        def plan_compaction(
-            prior: ProjectMessageRow | None, after_rows: list[ProjectMessageRow]
-        ) -> tuple[Any, str | None, int, int] | None:
-            """Projection-layer compaction decision — PURE (no I/O); runs inside the store's
-            locked transaction. Once the rendered projected prefix reaches ``max_tokens ×
-            trigger_ratio`` (mirrors DefaultCompactor's token-driven policy), fold the OLDEST
-            uncompacted sends — always keeping the most-recent ``keep_last_sends`` — into one
-            ``compact`` row, rolling any prior compact forward so nothing is lost. The folded
-            user/project rows REMAIN (recoverable via recall_send); pl_messages is untouched.
-
-            Wrapped so a misbehaving projector (render/compact/trigger raising) degrades to
-            "rows written, NO fold" instead of aborting the whole locked write — the send's
-            per-send projection rows still commit, and pl_messages stays the source of truth."""
-            try:
-                keep = int(getattr(projector, "keep_last_sends", 0) or 0)
-                if keep <= 0:
-                    return None
-                live_sends = sorted(
-                    {r.send_index for r in after_rows if r.kind in ("user", "project")}
-                )
-                if len(live_sends) <= keep:
-                    return None  # nothing foldable beyond the keep-recent floor
-                trigger_ratio = float(getattr(projector, "trigger_ratio", 0.75) or 0.75)
-                threshold = int((self.config.max_tokens or 8000) * trigger_ratio)
-                rendered_prefix = projector.render(
-                    ([prior] if prior is not None else []) + after_rows
-                )
-                if estimate_tokens(rendered_prefix) < threshold:
-                    return None  # below threshold — small per-send projections just accumulate
-                fold_sends = set(live_sends[: len(live_sends) - keep])
-                fold_rows = [
-                    r
-                    for r in after_rows
-                    if r.kind in ("user", "project") and r.send_index in fold_sends
-                ]
-                to_compact = ([prior] if prior is not None else []) + fold_rows  # roll prior fwd
-                folded = projector.compact(to_compact)
-                if folded is None:
-                    return None
-                from_send = (
-                    prior.compact_from_send
-                    if (prior is not None and prior.compact_from_send is not None)
-                    else min(fold_sends)
-                )
-                return (folded.content, folded.rendered_text, from_send, max(fold_sends))
-            except Exception:
-                logger.exception(
-                    "projection fold planning failed for %s (skipping fold; rows still written)",
-                    sid,
-                )
-                return None
-
-        # One atomic, session-locked write: all of this send's projection rows + the optional fold
-        # commit together (no half-projected send), and the read-decide-write of the fold is
-        # serialized against a concurrent loop sharing this store (no double-compaction clobber).
-        await store.write_send_projection_locked(
-            sid,
-            send_index=send_index,
-            rows=proj_rows_to_write,
-            source_seq_lo=projected.source_seq_lo,
-            source_seq_hi=projected.source_seq_hi,
+        # power-loop 3.0, THREE phases so the (multi-second / possibly-hung) LLM fold never runs
+        # inside a DB transaction or under the session lock:
+        #   1) write this send's projection rows under a SHORT lock + snapshot the live rows;
+        #   2) decide + run the fold OUTSIDE the lock (bounded by fold_timeout_s, soft-fails);
+        #   3) commit the compact under a SHORT lock with optimistic concurrency (skip if a
+        #      concurrent loop already advanced the compact cursor).
+        prior, snapshot = await store.write_send_projection_rows(
+            sid, send_index=send_index, rows=proj_rows_to_write,
+            source_seq_lo=projected.source_seq_lo, source_seq_hi=projected.source_seq_hi,
             projector_version=version,
-            plan_compaction=plan_compaction,
         )
+        plan, note_ops = await self._plan_and_run_projection_fold(sid, projector, prior, snapshot)
+        if plan is None:
+            return
+        content, rendered_text, from_send, to_send = plan
+        committed = await store.commit_projection_fold(
+            sid, content=content, rendered_text=rendered_text, from_send=from_send,
+            to_send=to_send, projector_version=version,
+            expected_prior_to_send=(prior.compact_to_send if prior is not None else None),
+        )
+        if committed:
+            await self._apply_fold_notes(store, sid, note_ops)
+
+    async def _plan_and_run_projection_fold(
+        self, sid: str, projector: Representation,
+        prior: ProjectMessageRow | None, snapshot: list[ProjectMessageRow],
+    ) -> tuple[tuple[Any, str | None, int, int] | None, tuple[Any, ...]]:
+        """Decide whether to fold (token threshold + keep-recent floor) and, if so, run the
+        configured ``fold_strategy`` OUTSIDE any lock (bounded by ``fold_timeout_s``). Always keeps
+        the most-recent ``keep_last_sends`` whole sends (never splits an atomic tool pair). Rolls any
+        prior compact forward so nothing is lost; the folded rows REMAIN (recall_send). Returns
+        ``((content, rendered_text, from_send, to_send), note_ops)`` or ``(None, ())``. Soft-fails
+        (no fold, rows already written) on any error/timeout — pl_messages stays the source of truth."""
+        fold_strategy = self.config.fold_strategy
+        try:
+            keep = int(getattr(fold_strategy, "keep_last_sends", 0) or 0)
+            if keep <= 0:
+                return None, ()
+            live_sends = sorted({r.send_index for r in snapshot if r.kind in ("user", "project")})
+            if len(live_sends) <= keep:
+                return None, ()  # nothing foldable beyond the keep-recent floor
+            trigger_ratio = float(getattr(fold_strategy, "trigger_ratio", 0.75) or 0.75)
+            threshold = int((self.config.max_tokens or 8000) * trigger_ratio)
+            rendered_prefix = projector.render(([prior] if prior is not None else []) + snapshot)
+            if estimate_tokens(rendered_prefix) < threshold:
+                return None, ()  # below threshold — small per-send projections just accumulate
+            fold_sends = set(live_sends[: len(live_sends) - keep])
+            fold_rows = [
+                r for r in snapshot
+                if r.kind in ("user", "project") and r.send_index in fold_sends
+            ]
+            to_compact = ([prior] if prior is not None else []) + fold_rows  # roll prior fwd
+            from_send = (
+                prior.compact_from_send
+                if (prior is not None and prior.compact_from_send is not None)
+                else min(fold_sends)
+            )
+            from power_loop.runtime.fold import FoldContext
+
+            ctx = FoldContext(
+                session_id=sid, round_index=0, representation=projector,
+                llm=self.llm, max_tokens=self.config.max_tokens,
+            )
+            fr = await self._run_fold_with_timeout(fold_strategy, to_compact, ctx)
+            if fr is None:
+                return None, ()
+            return (fr.content, fr.rendered_text, from_send, fr.folded_to_send), tuple(fr.note_ops)
+        except Exception:
+            logger.exception(
+                "projection fold planning failed for %s (skipping fold; rows still written)", sid,
+            )
+            return None, ()
+
+    async def _run_fold_with_timeout(self, fold_strategy: Any, rows: Any, ctx: Any) -> Any | None:
+        """Await ``fold_strategy.fold`` bounded by ``config.fold_timeout_s`` (None disables). A
+        timeout soft-fails to None (no fold this send; rows already committed)."""
+        timeout = self.config.fold_timeout_s
+        try:
+            if timeout is not None and timeout > 0:
+                return await asyncio.wait_for(fold_strategy.fold(rows, context=ctx), timeout)
+            return await fold_strategy.fold(rows, context=ctx)
+        except (TimeoutError, asyncio.TimeoutError):
+            logger.warning(
+                "projection fold timed out after %ss for %s (skipping fold this send)",
+                timeout, ctx.session_id,
+            )
+            return None
+
+    async def _apply_fold_notes(self, store: SessionStore, sid: str, note_ops: tuple[Any, ...]) -> None:
+        """Apply an agentic fold's captured NoteOps (best-effort, additive memory — NOT
+        transactional with the compact; a rare crash here loses a note, never corrupts context)."""
+        for op in note_ops:
+            try:
+                if getattr(op, "op", None) == "add":
+                    await store.add_note(sid, op.content or "", pinned=bool(op.pinned))
+                elif getattr(op, "op", None) == "update":
+                    await store.update_note(sid, op.note_id, content=op.content, pinned=op.pinned)
+            except Exception:
+                logger.exception("session %s: applying fold note op failed (continuing)", sid)
 
     async def _prime_sink_from_pending(self, sid: str, sink: SQLiteSink) -> None:
         store = await self._ensure_store()

power_loop-3.0.0/power_loop/agent/types.py

@@ -0,0 +1,279 @@
+from __future__ import annotations
+
+import warnings
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Literal
+
+#: Distinguishes "caller passed nothing" from an explicit None on the deprecated 2.x kwargs.
+_UNSET: Any = object()
+
+if TYPE_CHECKING:
+    from power_loop.runtime.fold import FoldStrategy
+    from power_loop.runtime.memory import MemoryProvider
+    from power_loop.runtime.notes import NotesPolicy
+    from power_loop.runtime.representation import Representation
+    from power_loop.runtime.retry import LLMRetryPolicy
+    from power_loop.runtime.runtime_state import RuntimeProjector
+
+LoopStatus = Literal["completed", "pending_tools", "waiting_for_input", "cancelled", "hit_round_limit", "budget_exceeded", "degraded"]
+LoopMessage = dict[str, Any]
+
+
+def _default_representation() -> Representation:
+    from power_loop.runtime.representation import VerbatimRepresentation
+    return VerbatimRepresentation()
+
+
+def _default_fold_strategy() -> FoldStrategy:
+    from power_loop.runtime.fold import LLMSummaryFold
+    return LLMSummaryFold()
+
+
+def _fold_from_legacy_projector(proj: Any) -> FoldStrategy:
+    """Seed the default LLM fold from a DEPRECATED ``history_projector``'s knobs so a legacy
+    projector's ``keep_last_sends`` / ``trigger_ratio`` keep taking effect (e.g. DeepTalk's
+    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))
+    trigger = float(getattr(proj, "trigger_ratio", 0.75) or 0.75)
+    return LLMSummaryFold(keep_last_sends=keep, trigger_ratio=trigger)
+
+
+def _default_runtime_projectors() -> tuple[RuntimeProjector, ...]:
+    from power_loop.runtime.runtime_state import default_runtime_projectors
+    return default_runtime_projectors()
+
+
+@dataclass
+class AgentLoopConfig:
+    """Configuration for the agent loop."""
+
+    system_prompt: str | None = None
+    max_rounds: int = 24
+    temperature: float | None = 0.0
+    max_tokens: int | None = 8000
+    #: Per-loop model override. When set, every LLM request of this loop carries
+    #: it (the provider uses ``request.model`` over its own configured model), so
+    #: a sub-agent / workflow step can run on a different model than the global
+    #: one. ``None`` → use the LLM service's configured model.
+    model: str | None = None
+    #: OpenAI-compatible ``response_format`` (e.g. a json_schema dict from
+    #: ``StructuredOutputSpec.to_openai_response_format()``), forwarded on the
+    #: main generation call so the provider returns structured output. ``None``
+    #: → free-form text.
+    response_format: dict[str, Any] | None = None
+    #: Hard per-run token budget (prompt + completion summed over the whole
+    #: run, real provider usage — see ``ContextManager.usage_totals``). Checked
+    #: at round boundaries: the round that crosses the budget still finishes
+    #: (so no tool_calls are left dangling), then the loop stops with
+    #: status="budget_exceeded". ``None`` disables.
+    max_tokens_per_run: int | None = None
+    #: Context handling = REPRESENTATION × FOLD_STRATEGY (power-loop 3.0), two orthogonal axes.
+    #:
+    #: ``representation`` — how each finished send is recorded/rendered:
+    #:   * ``VerbatimRepresentation`` (default): full messages, byte-identical history.
+    #:   * ``ProjectedRepresentation``: a per-send terse plain-text projection (send-context
+    #:     projection), original detail kept in ``pl_messages`` (recall_send re-expands).
+    #: Custom representations implement the ``Representation`` Protocol.
+    representation: Representation = _UNSET  # resolved in __post_init__ (default or legacy-mapped)
+    #: ``fold_strategy`` — how older history is compacted (N records → 1 compact) once over budget:
+    #:   * ``LLMSummaryFold`` (default): one LLM summary call, no side effects.
+    #:   * ``AgenticFold``: LLM + a bounded tool loop that persists durable facts as notes.
+    #:   * custom: any ``FoldStrategy`` Protocol impl.
+    #: Works under EITHER representation. Folds are always LLM-backed (no deterministic/never-fold).
+    #: Trigger + keep-recent come from the strategy (``trigger_ratio`` / ``keep_last_sends``);
+    #: the fold always keeps whole sends (never splits an atomic tool-call/result pair).
+    fold_strategy: FoldStrategy = _UNSET  # resolved in __post_init__ (default or legacy-mapped)
+    #: Wall-clock bound (seconds) on a single fold's LLM/agentic call. The fold runs OUTSIDE the
+    #: store lock, but a hung provider would still stall the end-of-send path; on timeout the fold
+    #: soft-fails (rows committed, no compact this send — retried next send). None disables.
+    fold_timeout_s: float | None = 120.0
+    #: On a representation/fold change for an existing session, fold the prior history into the new
+    #: form ONCE (best-effort, never throws). Default True.
+    migrate_history_on_switch: bool = True
+    # ── deprecated 2.x kwargs (accepted + mapped onto the two axes in __post_init__) ──
+    # The public API is representation × fold_strategy; these keep existing call sites + DeepTalk
+    # working until migrated. A future major drops them.
+    compactor: Any = _UNSET
+    history_projector: Any = _UNSET
+    migrate_history_on_projection_switch: Any = _UNSET
+    #: History-repair backstop (the always-on prompt sanitizer in `align_tool_calls` realigns
+    #: tool-call/result pairing before every LLM call regardless). When True, the orphan
+    #: tool-result rows that sanitizer drops are ALSO physically deactivated in the store
+    #: (state=DROPPED), so the corruption is repaired durably and not re-sanitized every load.
+    #: Default False to keep `pl_messages` immutable; the prompt is kept valid either way.
+    repair_corrupt_history: bool = False
+    retry_policy: LLMRetryPolicy | None = None
+    memory: MemoryProvider | None = None
+    memory_budget_tokens: int = 1500
+    # Bounds for the note_add/note_update/note_delete tools (agent-authored
+    # notes). None → DEFAULT_NOTES_POLICY. See power_loop.runtime.notes.
+    notes_policy: NotesPolicy | None = None
+    skills_dir: str | None = None
+    runtime_projectors: tuple[RuntimeProjector, ...] = field(default_factory=_default_runtime_projectors)
+
+    # ── Tool catalog auto-injection (M1.10) ──
+    #
+    # When ``inject_tool_descriptions`` is True (default), the pipeline
+    # automatically appends a human-readable tool catalog to the resolved
+    # system prompt.  The catalog is generated from the live
+    # ``ToolRegistry`` so the agent always knows which tools are
+    # available — even when the user-supplied system prompt does not
+    # mention them.
+    #
+    # The catalog lives inside ``self.system_prompt`` (a plain string
+    # attribute on the pipeline), NOT in ``self.history``, so the
+    # compactor never touches it.
+    inject_tool_descriptions: bool = True
+    tool_catalog_header: str = "# Available Tools"
+
+    def __post_init__(self) -> None:
+        self._map_legacy_axes()
+        self._validate_context_config()
+        # Mark init complete so __setattr__ starts re-validating reassignments (the dataclass
+        # is mutable; a post-hoc reassignment of an axis or max_tokens must stay valid).
+        object.__setattr__(self, "_initialized", True)
+
+    def _map_legacy_axes(self) -> None:
+        """Resolve representation/fold_strategy, mapping the deprecated 2.x ``history_projector`` /
+        ``compactor`` / ``migrate_history_on_projection_switch`` kwargs onto them (NEW fields win
+        when explicitly set). A legacy ``compactor`` (incl. ``None`` = no compaction) under verbatim
+        is preserved EXACTLY via ``_legacy_verbatim_compactor`` so old behavior is unchanged; a
+        legacy projector becomes the projection representation (its fold is now the fold_strategy)."""
+        legacy_proj = self.history_projector
+        legacy_comp = self.compactor
+        fold_was_unset = self.fold_strategy is _UNSET
+        if legacy_proj is not _UNSET or legacy_comp is not _UNSET or (
+            self.migrate_history_on_projection_switch is not _UNSET
+        ):
+            warnings.warn(
+                "AgentLoopConfig: history_projector / compactor / "
+                "migrate_history_on_projection_switch are deprecated; use representation / "
+                "fold_strategy / migrate_history_on_switch.",
+                DeprecationWarning,
+                stacklevel=3,
+            )
+        if self.representation is _UNSET:
+            rep = legacy_proj if legacy_proj not in (_UNSET, None) else _default_representation()
+            object.__setattr__(self, "representation", rep)
+        if fold_was_unset:
+            # Seed the fold from a legacy projector's knobs so its keep_last_sends / trigger_ratio
+            # keep taking effect (DeepTalk admin config); else the library default.
+            fs = (
+                _fold_from_legacy_projector(legacy_proj)
+                if legacy_proj not in (_UNSET, None)
+                else _default_fold_strategy()
+            )
+            object.__setattr__(self, "fold_strategy", fs)
+        # A legacy verbatim compactor (incl. an explicit None = no compaction) is preserved exactly
+        # via resolve_compactor — but ONLY on the pure-legacy path (no projector AND no explicit
+        # new fold_strategy). If the caller set fold_strategy explicitly, the new axis wins and a
+        # 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)
+        else:
+            object.__setattr__(self, "_legacy_verbatim_compactor", _UNSET)
+        if self.migrate_history_on_projection_switch is not _UNSET:
+            object.__setattr__(
+                self, "migrate_history_on_switch",
+                bool(self.migrate_history_on_projection_switch),
+            )
+        # Clear the deprecated fields so they never leak into fingerprints / re-validation.
+        object.__setattr__(self, "compactor", _UNSET)
+        object.__setattr__(self, "history_projector", _UNSET)
+        object.__setattr__(self, "migrate_history_on_projection_switch", _UNSET)
+
+    def _validate_context_config(self) -> None:
+        if self.representation is None or self.fold_strategy is None:
+            raise ValueError("AgentLoopConfig: representation and fold_strategy are required")
+        # max_tokens drives the fold trigger (max_tokens × trigger_ratio); a non-positive value
+        # would make the fold misbehave (always/never fold), so reject it up front.
+        if self.max_tokens is not None and self.max_tokens <= 0:
+            raise ValueError(
+                f"AgentLoopConfig: max_tokens must be > 0 (drives the fold trigger); "
+                f"got {self.max_tokens!r}"
+            )
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        if name in ("representation", "fold_strategy", "max_tokens") and getattr(
+            self, "_initialized", False
+        ):
+            old = getattr(self, name)
+            super().__setattr__(name, value)
+            try:
+                self._validate_context_config()
+            except Exception:
+                # A rejected reassignment must not leave the config in the invalid state it was
+                # about to enter (mutate-then-validate would otherwise corrupt it) — roll back.
+                super().__setattr__(name, old)
+                raise
+        else:
+            super().__setattr__(name, value)
+
+    # ── internal resolution (3.0): map the two axes onto the loop's two mechanisms ──
+    # Projection-style representations drive the derived-layer path (fold via fold_strategy at
+    # end-of-send); verbatim drives the in-place compactor path (fold_strategy mapped to a
+    # Compactor whose span selection already keeps atomic tool pairs / keep_last_n intact).
+    @property
+    def projection_representation(self) -> Any | None:
+        """The representation when it's projection-style (renders per-send projections), else None
+        (verbatim → in-place fold path)."""
+        rep = self.representation
+        return rep if getattr(rep, "kind", "projection") != "verbatim" else None
+
+    def resolve_compactor(self) -> Any | None:
+        """Verbatim mode → an in-place ``Compactor`` mapped from ``fold_strategy``; projection mode
+        → ``None`` (projection folds at end-of-send via ``fold_strategy``). Constructed fresh per
+        call (cheap)."""
+        # Projection folds at end-of-send via fold_strategy — never an in-place compactor. Checked
+        # FIRST so a post-init switch to a projection representation can't leave a stale legacy
+        # verbatim compactor active (which would double-fold alongside the derived-layer fold).
+        if getattr(self.representation, "kind", "projection") != "verbatim":
+            return None
+        # A deprecated verbatim ``compactor=`` (incl. None) is honored verbatim, so legacy
+        # call sites keep their EXACT old compaction behavior.
+        legacy = getattr(self, "_legacy_verbatim_compactor", _UNSET)
+        if legacy is not _UNSET:
+            return legacy
+        from power_loop.runtime.fold import AgenticFold, LLMSummaryFold
+
+        fs = self.fold_strategy
+        if isinstance(fs, AgenticFold):
+            from power_loop.runtime.compact import AgenticMemoryCompactor
+
+            return AgenticMemoryCompactor(
+                keep_last_n=fs.keep_last_sends,
+                trigger_ratio=fs.trigger_ratio,
+                summary_max_tokens=fs.summary_max_tokens,
+                max_rounds=fs.max_rounds,
+            )
+        if isinstance(fs, LLMSummaryFold):
+            from power_loop.runtime.compact import DefaultCompactor
+
+            return DefaultCompactor(
+                keep_last_n=fs.keep_last_sends,
+                trigger_ratio=fs.trigger_ratio,
+                summary_max_tokens=fs.summary_max_tokens,
+            )
+        # A custom FoldStrategy under verbatim → adapt it onto the in-place Compactor interface
+        # (DefaultCompactor's span selection keeps atomic tool pairs / keep_last_n intact).
+        from power_loop.runtime.fold_adapter import FoldStrategyCompactor
+
+        return FoldStrategyCompactor(fs, max_tokens=self.max_tokens)
+
+
+@dataclass
+class AgentLoopResult:
+    status: LoopStatus
+    final_text: str = ""
+    rounds: int = 0
+    pending_tool_calls: list[dict[str, Any]] = field(default_factory=list)
+    pending_interactions: list[dict[str, Any]] = field(default_factory=list)
+    messages: list[LoopMessage] = field(default_factory=list)
+    #: Cumulative token usage across every LLM call of this run:
+    #: {prompt_tokens, completion_tokens, cache_read_tokens, reasoning_tokens,
+    #:  total_tokens, calls}. Empty dict when the run never reached the LLM.
+    usage: dict[str, int] = field(default_factory=dict)
+    #: Tool invocations executed during this run.
+    tool_calls: int = 0