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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: power-loop
-Version: 2.1.0
+Version: 2.2.0
 Summary: Embeddable agent execution kernel — LLM loop, hooks, events, tools, dynamic sub-agents.
 Author-email: zhangran <zhangran24@126.com>
 License: MIT
@@ -154,6 +154,7 @@ Most "agent frameworks" ask you to build your app *inside* them. power-loop is t
 | **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) |
 | **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) |

{power_loop-2.1.0 → power_loop-2.2.0}/README.md

@@ -81,6 +81,7 @@ Most "agent frameworks" ask you to build your app *inside* them. power-loop is t
 | **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) |
 | **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) |

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

@@ -15,7 +15,7 @@ Stability tiers
 无版本承诺，可随时变更或删除。
 """
 
-__version__ = "2.1.0"
+__version__ = "2.2.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,6 +145,14 @@ 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.human_input import HumanInputRequired, request_user_input
 from power_loop.runtime.memory import MemoryProvider, MemorySnapshot, tag_as_memory
 from power_loop.runtime.notes import (
@@ -186,6 +194,7 @@ from power_loop.runtime.store.store import (
 from power_loop.runtime.store.types import (
     MessageRow,
     MessageState,
+    ProjectMessageRow,
     SessionKind,
     SessionRow,
     SessionStatsRow,
@@ -311,6 +320,13 @@ __all__ = [
 	"BackgroundRuntimeProjector",
 	"default_runtime_projectors",
 	"get_tool_runtime_context",
+	"HistoryProjector",
+	"IdentityProjector",
+	"DefaultDeterministicProjector",
+	"ProjectedSend",
+	"ProjectedRow",
+	"ProjectedCompact",
+	"ProjectMessageRow",
 	"CancellationToken",
 	"CancellationLike",
 	"RuntimeEnv",

{power_loop-2.1.0 → power_loop-2.2.0}/power_loop/agent/sink.py

@@ -158,6 +158,8 @@ class SQLiteSink:
                 tool_call_id=tool_call_id,
                 name=message.get("name"),
                 round_index=round_index,
+                meta=message.get("meta"),
+                send_index=message.get("send_index"),
             )
             self._history_seqs.append(seq)
             self._history_ord.append(seq)
@@ -199,6 +201,8 @@ class SQLiteSink:
                 content=_as_text(message.get("content")),
                 tool_calls=list(tool_calls) if tool_calls else None,
                 round_index=round_index,
+                meta=message.get("meta"),
+                send_index=message.get("send_index"),
             )
             self._history_seqs.append(seq)
             self._history_ord.append(seq)
@@ -212,6 +216,8 @@ class SQLiteSink:
             content=_as_text(message.get("content")),
             name=message.get("name"),
             round_index=round_index,
+            meta=message.get("meta"),
+            send_index=message.get("send_index"),
         )
         self._history_seqs.append(seq)
         self._history_ord.append(seq)

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

@@ -25,7 +25,7 @@ import threading
 from collections import OrderedDict
 from collections.abc import Coroutine, Sequence
 from dataclasses import dataclass, field, replace
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from power_loop._vendor.llm_client.interface import LLMService
 from power_loop.agent.follow_up import FollowUpQueued, merge_follow_up_inputs
@@ -48,7 +48,9 @@ from power_loop.core.pipeline import (
     _truncate_result,
 )
 from power_loop.core.runner import AgentRunner
+from power_loop.runtime.budget import estimate_tokens
 from power_loop.runtime.cancellation import CancellationLike
+from power_loop.runtime.history_sanitize import align_tool_calls
 from power_loop.runtime.skills import SkillLoader
 from power_loop.runtime.store.schema import SchemaPolicy
 from power_loop.runtime.store.store import (
@@ -60,10 +62,15 @@ from power_loop.runtime.store.store import (
 from power_loop.runtime.store.types import (
     MessageRow,
     MessageState,
+    ProjectMessageRow,
+    SessionRow,
     SubagentLifecycle,
 )
 from power_loop.tools.registry import ToolRegistry
 
+if TYPE_CHECKING:
+    from power_loop.runtime.history_projector import HistoryProjector
+
 logger = logging.getLogger(__name__)
 
 
@@ -1014,17 +1021,27 @@ class StatefulAgentLoop:
             role = str(user_input.get("role", "user"))
             content = _as_text(user_input.get("content"))
             name = user_input.get("name")
-        seq = await store.append_message(sid, role=role, content=content, name=name)
+        # Allocate the next monotonic SEND index for this session (atomic RMW under the
+        # session_state row lock — never resets, unlike round_index). This is the single
+        # send-begin point (exactly one user row per send; resume()/follow-up drains do
+        # NOT pass through here, so they correctly inherit the in-flight send's index).
+        # Stamped into meta so the transcript can delimit sends authoritatively.
+        send_index = await store.mutate_runtime_state(
+            sid, "send_index", lambda v: int(v or 0) + 1, default=0
+        )
+        seq = await store.append_message(
+            sid, role=role, content=content, name=name, send_index=send_index
+        )
         # Keep a live cache entry current with the loop's OWN append (no reload): the next
         # send's next_seq token will then match and reuse the cached window. No-op if this
         # session isn't cached. The row mirrors what append_message persisted (only
-        # seq/role/content/name are consumed when rebuilding the working history).
+        # seq/role/content/name/send_index are consumed when rebuilding the working history).
         self._cache_append(
             sid,
             MessageRow(
                 session_id=sid, seq=seq, role=role, name=name, content=content,
                 tool_calls=None, tool_call_id=None, round_index=None,
-                state=MessageState.ACTIVE, meta={}, created_at=0,
+                state=MessageState.ACTIVE, meta={}, created_at=0, send_index=send_index,
             ),
             new_next_seq=seq + 1,
         )
@@ -1096,43 +1113,246 @@ class StatefulAgentLoop:
         system_prompt: str | None = None,
     ) -> StatefulResult:
         store = await self._ensure_store()
+        projector = self.config.history_projector
+        # 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)
+        # send_index is allocated >= 1 by _persist_user_input and persists across resume();
+        # 0 is the unallocated/legacy default. Treat ONLY a real allocation (>= 1) as the current
+        # send — explicit (matches the `is not None` convention used below), never conflating the
+        # unallocated 0 with a (hypothetical) explicit send 0. Coerce defensively: a corrupted
+        # runtime_state value (non-numeric / inf / nan) must degrade to "unallocated", never crash
+        # the reader with int()'s ValueError/OverflowError.
+        try:
+            si_int = int(si)
+        except (TypeError, ValueError, OverflowError):
+            si_int = 0
+        current_send_index = si_int if si_int >= 1 else None
         # Cache only the plain-send path: resume()/submit_input() pass a pre-primed sink built
         # from pending state (NOT a full init_history_seqs), so they must neither read from nor
         # write to the window cache — they self-invalidate via the next_seq bump from their own
-        # appended tool rows. Capture eligibility BEFORE constructing the default sink.
-        cache_eligible = sink is None and self._session_cache_size > 0
+        # appended tool rows. Projection mode bypasses the window cache too (it caches verbatim
+        # rows, but projected history != verbatim). Capture eligibility BEFORE the default sink.
+        cache_eligible = sink is None and self._session_cache_size > 0 and projector is None
         sink = sink if sink is not None else SQLiteSink(store, sid)
-        # The async store offloads its own blocking I/O (SQLite → threadpool; PG/MySQL → real
-        # async). When this session's window cache is current (token = session_state.next_seq,
-        # already advanced by the just-persisted user input), reuse it and skip the O(active-
-        # history) load entirely; otherwise load in full and (re)populate the cache.
-        active_rows: list[MessageRow] | None = None
-        cache_token: tuple[int, int] | None = None
-        if cache_eligible:
-            state = await store.get_state(sid)
-            if state is not None:
-                cache_token = (state.next_seq, state.last_compact_seq)
-                active_rows = self._cache_get(sid, state.next_seq, state.last_compact_seq)
-        if active_rows is None:
+        # Record the session's ORIGINAL history mode + projector config ONCE, in the session
+        # METADATA (inspectable, and the baseline for switch-detection). A later mode switch never
+        # fails the run — it logs a warning and renders best-effort (the config-level
+        # projector/compactor exclusion can't catch a cross-RUN switch). Loaded here once and
+        # reused below for the system-prompt precedence.
+        session_row = await store.get_session(sid)
+        current_mode = "projection" if projector is not None else "default"
+        try:
+            recorded = session_row.metadata.get("history_mode") if session_row is not None else None
+            if recorded is None:
+                await store.merge_session_metadata(sid, {
+                    "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
+                    ),
+                    "projector_keep_last_sends": (
+                        int(getattr(projector, "keep_last_sends", 0) or 0) if projector else None
+                    ),
+                })
+            elif recorded != current_mode:
+                logger.warning(
+                    "session %s: running in %r history mode but it was originally %r — rendering "
+                    "best-effort (prior-mode history shown verbatim or compacted).",
+                    sid, current_mode, recorded,
+                )
+        except Exception:
+            logger.exception("session %s: history-mode bookkeeping failed (continuing)", sid)
+
+        projection_active = projector is not None
+        active_rows: list[Any] | None = None
+        if projection_active:
             active_rows = await store.load_active_messages(sid)
-            if cache_eligible and cache_token is not None:
-                self._cache_put(sid, cache_token[0], active_rows, cache_token[1])
-        history = [_row_to_loop_message(r) for r in active_rows]
-        # Mirror loaded seqs into the sink so the compactor can translate
-        # in-memory indices back to store rows when it folds messages. Pass the
-        # parallel logical positions too: a compact_note's identity seq is high,
-        # but it sits at its logical ``ord`` (set when it was folded) — load order
-        # and the sink's index map must agree on that, or the next fold mis-maps.
-        sink.init_history_seqs(
-            [r.seq for r in active_rows],
-            [
+            migrated = (
+                session_row is not None and session_row.metadata.get("projection_migrated") is not None
+            )
+            if current_send_index is None:
+                # resume()/submit_input() before any send() — no in-flight send to partition by.
+                logger.warning(
+                    "session %s: projection mode degrading to verbatim rendering (no allocated "
+                    "send_index — resume before any send); best-effort.", sid,
+                )
+                projection_active = False
+            elif not migrated and self.config.migrate_history_on_projection_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
+                # than rendering it verbatim forever. Only when the projection table is EMPTY (a
+                # genuine switch / in-place-compacted / never-projected session) — an incidental
+                # missing/stale row on an already-projected session is left to the verbatim
+                # fallback below.
+                has_note = any(r.name == "compact_note" for r in active_rows)
+                has_prior = any(
+                    r.send_index is not None and r.send_index < current_send_index
+                    and r.name != "compact_note"
+                    for r in active_rows
+                )
+                if has_note or has_prior:
+                    if await store.load_project_messages(sid):
+                        # Already projection-native (normal session, or a version bump handled by
+                        # the verbatim fallback) — mark resolved so we don't re-check every send.
+                        try:
+                            await store.merge_session_metadata(sid, {"projection_migrated": 0})
+                        except Exception:
+                            logger.exception("session %s: migration bookkeeping failed", sid)
+                        migrated = True
+                    else:
+                        try:
+                            # Writes the rows AND the projection_migrated marker in one tx (atomic).
+                            await self._migrate_prior_history_to_projection(
+                                store, sid, projector,
+                                current_send_index=current_send_index, active_rows=active_rows,
+                            )
+                            migrated = True
+                            logger.info(
+                                "session %s: migrated prior history into the projection table "
+                                "(mode switch).", sid,
+                            )
+                        except Exception:
+                            # Best-effort: fall back to verbatim this send (and retry next send).
+                            logger.exception(
+                                "session %s: projection migration failed (continuing best-effort)",
+                                sid,
+                            )
+            # A compact_note that migration did NOT fold in (migration off/failed) can't be
+            # send_index-partitioned → degrade to verbatim. Once migrated, the note is represented
+            # by the projection compact and is excluded from the partition below.
+            if (
+                projection_active
+                and not migrated
+                and any(r.name == "compact_note" for r in active_rows)
+            ):
+                logger.warning(
+                    "session %s: projection mode degrading to verbatim rendering (in-place "
+                    "compaction history present, not migrated); best-effort.", sid,
+                )
+                projection_active = False
+
+        if projection_active:
+            # ── Projection mode (v2): history = rendered projections of FINISHED sends + the
+            # in-flight send's structured rows. pl_messages is NEVER compacted here (compactor is
+            # None, enforced by AgentLoopConfig), so it stays in seq order; we partition by the
+            # send_index stamped on every row. (active_rows loaded above; current_send_index set.)
+            assert current_send_index is not None and active_rows is not None
+            # Rows predating the projection era (pre-v2 / export→import) carry send_index=NULL —
+            # render them VERBATIM as a temporally-first prefix (never dropped, never lumped into
+            # the current send). compact_note rows are in-place-compactor artifacts: in projection
+            # mode they are represented by the projection compact (after migration) and must never
+            # be rendered verbatim, so they are excluded from both the prefix and the partition.
+            legacy_rows = [
+                r for r in active_rows if r.send_index is None and r.name != "compact_note"
+            ]
+            current_rows = [
+                r for r in active_rows
+                if r.send_index == current_send_index and r.name != "compact_note"
+            ]
+            # pl_messages is the immutable audit log and is NEVER compacted in projection mode, so
+            # every past send's rows are still present here — the FALLBACK source whenever a send's
+            # projection row is missing (a best-effort end-of-send projection write failed/crashed)
+            # or was written by a DIFFERENT projector version (the user changed the projector).
+            # Without this fallback such a send would be silently dropped from context forever.
+            version = int(getattr(projector, "version", 0) or 0)
+            active_by_send: dict[int, list[Any]] = {}
+            for r in active_rows:
+                if r.send_index is not None and r.name != "compact_note":
+                    active_by_send.setdefault(r.send_index, []).append(r)
+
+            def _verbatim(send_idx: int) -> list[LoopMessage]:
+                return [_row_to_loop_message(m) for m in active_by_send.get(send_idx, [])]
+
+            compact = await store.latest_project_compact(sid)
+            cutoff = compact.compact_to_send if compact is not None else None
+            proj_rows = [
+                r
+                for r in await store.load_project_messages(sid, after_send_index=cutoff)
+                if r.send_index < current_send_index
+            ]
+            # Only rows written by the CURRENT projector version are faithfully renderable by it;
+            # rows from another version fall back to verbatim (below), keyed per send.
+            cur_proj_by_send: dict[int, list[Any]] = {}
+            for r in proj_rows:
+                if int(r.projector_version or 0) == version:
+                    cur_proj_by_send.setdefault(r.send_index, []).append(r)
+
+            prefix_msgs: list[LoopMessage] = []
+            # (1) folded-history compact: render via the projector when it matches the current
+            # version, else render its covered send range verbatim from the audit log.
+            if compact is not None:
+                if int(compact.projector_version or 0) == version:
+                    prefix_msgs.extend(projector.render([compact]))
+                else:
+                    for si2 in range(compact.compact_from_send or 0, (compact.compact_to_send or 0) + 1):
+                        prefix_msgs.extend(_verbatim(si2))
+            # (2) each uncompacted past send in order: projected when a current-version row exists,
+            # else verbatim fallback (missing or stale projection).
+            lo = cutoff or 0
+            for si2 in sorted(s for s in active_by_send if lo < s < current_send_index):
+                rows_for_send = cur_proj_by_send.get(si2)
+                prefix_msgs.extend(projector.render(rows_for_send) if rows_for_send else _verbatim(si2))
+
+            legacy_msgs = [_row_to_loop_message(r) for r in legacy_rows]
+            current_msgs = [_row_to_loop_message(r) for r in current_rows]
+            history = legacy_msgs + prefix_msgs + current_msgs
+            # Sink index↔seq map: legacy + in-flight rows carry real seqs; the rendered prefix
+            # (projected OR verbatim-fallback) has no foldable DB row (None). Compaction is off in
+            # projection mode, so this map is only kept aligned for the appends, never used to fold.
+            hist_seqs: list[int | None] = (
+                [r.seq for r in legacy_rows]
+                + [None] * len(prefix_msgs)
+                + [r.seq for r in current_rows]
+            )
+            hist_ords: list[int | None] = list(hist_seqs)
+        else:
+            # ── Default / degraded-verbatim mode: full verbatim history (+ window cache + in-place
+            # compactor). When degrading from projection, active_rows is already loaded above and
+            # the cache is bypassed (cache_eligible is False whenever a projector is configured). ──
+            cache_token: tuple[int, int] | None = None
+            if cache_eligible:
+                state = await store.get_state(sid)
+                if state is not None:
+                    cache_token = (state.next_seq, state.last_compact_seq)
+                    active_rows = self._cache_get(sid, state.next_seq, state.last_compact_seq)
+            if active_rows is None:
+                active_rows = await store.load_active_messages(sid)
+                if cache_eligible and cache_token is not None:
+                    self._cache_put(sid, cache_token[0], active_rows, cache_token[1])
+            history = [_row_to_loop_message(r) for r in active_rows]
+            # Mirror loaded seqs into the sink so the compactor can translate in-memory indices
+            # back to store rows when it folds. Pass the parallel logical positions too: a
+            # compact_note's identity seq is high, but it sits at its logical ``ord``.
+            hist_seqs = [r.seq for r in active_rows]
+            hist_ords = [
                 int(r.meta["ord"]) if r.name == "compact_note" and r.meta.get("ord") is not None
                 else r.seq
                 for r in active_rows
-            ],
+            ]
+
+        # ── Robustness backstop (mode-agnostic, always on): repair tool-call/result misalignment
+        # in the assembled prompt so a corrupt row (crash mid-tool, bad import/edit, projection
+        # mismatch) can't make the provider reject the history and brick the session forever. No-op
+        # on a healthy history. With repair_corrupt_history=True, the dropped orphan rows are also
+        # deactivated in the store so the fix is durable (else the prompt is just re-sanitized). ──
+        history, hist_seqs, hist_ords, dropped_seqs, synthesized = align_tool_calls(
+            history, hist_seqs, hist_ords
         )
-        session_row = await store.get_session(sid)
-        # System prompt precedence: per-call > session > config.
+        if dropped_seqs or synthesized:
+            logger.warning(
+                "session %s: repaired malformed tool-call pairing in the prompt "
+                "(dropped %d orphan result(s) seqs=%s, synthesized %d placeholder result(s))",
+                sid, len(dropped_seqs), dropped_seqs, synthesized,
+            )
+        if dropped_seqs and self.config.repair_corrupt_history:
+            try:
+                await store.deactivate_messages(sid, dropped_seqs)
+            except Exception:
+                logger.exception("session %s: durable history repair (deactivate) failed", sid)
+        sink.init_history_seqs(hist_seqs, hist_ords)
+        # System prompt precedence: per-call > session > config. (session_row loaded above.)
         effective_sp = system_prompt
         if effective_sp is None and session_row is not None and session_row.system_prompt:
             effective_sp = session_row.system_prompt
@@ -1160,6 +1380,11 @@ class StatefulAgentLoop:
                     store=store,
                     drain_follow_ups=_drain_follow_ups,
                 )
+                # Every row this run appends (assistant/tool/system, plus follow-up and
+                # trailing-notice rows drained mid-run) inherits the current send index, so
+                # the whole send shares one index. _persist_user_input bumped it for a fresh
+                # send; resume()/submit_input() leave it, correctly attaching to the prior send.
+                pipeline.send_index = current_send_index
                 try:
                     result: AgentLoopResult = await pipeline.run(history)
                 except Exception as exc:
@@ -1191,6 +1416,18 @@ class StatefulAgentLoop:
             )
         except Exception:
             logger.exception("session_stats bump failed for %s (continuing)", sid)
+        # Send-context projection (v2): at end-of-send, project the finished send's pl_messages
+        # rows into pl_project_messages so the NEXT send reads them as plain-text history. Derived
+        # + best-effort: a failure never affects the send result (pl_messages is the source of truth).
+        # Skipped when projection degraded to verbatim this run (projection_active=False).
+        if projection_active and current_send_index is not None:
+            try:
+                await self._write_send_projection(
+                    store, sid, send_index=current_send_index, status=result.status,
+                    session_row=session_row, projector=projector, tool_registry=effective_registry,
+                )
+            except Exception:
+                logger.exception("send-context projection write failed for %s (continuing)", sid)
         return StatefulResult(
             session_id=sid,
             status=result.status,
@@ -1202,6 +1439,182 @@ class StatefulAgentLoop:
             tool_calls=result.tool_calls,
         )
 
+    async def _migrate_prior_history_to_projection(
+        self,
+        store: SessionStore,
+        sid: str,
+        projector: HistoryProjector,
+        *,
+        current_send_index: int,
+        active_rows: list[Any],
+    ) -> None:
+        """One-time best-effort migration: fold a session's prior NON-projection history into the
+        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)."""
+        from power_loop.runtime.store.types import ProjectMessageRow
+
+        keep = max(int(getattr(projector, "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]] = {}
+        for r in active_rows:
+            if r.send_index is not None and r.send_index < current_send_index and r.name != "compact_note":
+                by_send.setdefault(r.send_index, []).append(r)
+        prior = sorted(by_send)
+        if not prior and note is None:
+            return  # nothing to migrate
+
+        projected = {si: projector.project_send(by_send[si], send_index=si, tool_registry=None) for si in prior}
+        # Fold all but the most-recent `keep` prior sends; keep the rest as individual project rows.
+        if keep > 0 and len(prior) > keep:
+            fold, recent = prior[:-keep], prior[-keep:]
+        elif keep == 0:
+            fold, recent = prior, []
+        else:
+            fold, recent = [], prior
+
+        def _pm(si: int, kind: str, content: Any) -> ProjectMessageRow:
+            return ProjectMessageRow(
+                session_id=sid, send_index=si, kind=kind, content=content, rendered_text=None,
+                source_seq_lo=None, source_seq_hi=None, compact_from_send=None,
+                compact_to_send=None, projector_version=version, token_estimate=None, created_at=0,
+            )
+
+        # 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).
+        to_compact: list[ProjectMessageRow] = []
+        if note is not None:
+            to_compact.append(_pm(0, "compact", {"summary": note.content or ""}))
+        for si in fold:
+            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
+        )
+        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))
+        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))
+
+        project_rows = [
+            (si, pr.kind, pr.content, pr.rendered_text)
+            for si in recent
+            for pr in projected[si].rows
+        ]
+        # Mark migrated in the SAME transaction as the rows (atomic): a crash can't leave the
+        # migration written with an unset marker.
+        await store.write_projection_migration(
+            sid, project_rows=project_rows, compact=compact_tuple, projector_version=version,
+            metadata_patch={"projection_migrated": current_send_index},
+        )
+
+    async def _write_send_projection(
+        self,
+        store: SessionStore,
+        sid: str,
+        *,
+        send_index: int,
+        status: str,
+        session_row: SessionRow | None,
+        projector: HistoryProjector,
+        tool_registry: ToolRegistry | None,
+    ) -> None:
+        """Project the just-finished send's ``pl_messages`` rows into ``pl_project_messages`` (v2).
+
+        Skips sub-agent CHILD sessions (their transcript lives in their own pl_session) by
+        ``parent_session_id`` — NOT ``scope``, which ``_finalize`` hardcodes to ``'main'`` even
+        for children. Defers on a still-in-flight status (the resume re-finalizes under the SAME
+        ``send_index``; the idempotent UPSERT then overwrites). Best-effort — the caller swallows
+        failures, since ``pl_messages`` remains the source of truth."""
+        if session_row is not None and session_row.parent_session_id is not None:
+            return  # a spawned sub-agent run, not a top-level send
+        if status in ("waiting_for_input", "pending_tools"):
+            return  # send not finished; the resume will re-finalize under the same send_index
+        rows = [
+            r for r in await store.load_active_messages(sid) if r.send_index == send_index
+        ]
+        if not rows:
+            return
+        projected = projector.project_send(rows, send_index=send_index, tool_registry=tool_registry)
+        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,
+            projector_version=version,
+            plan_compaction=plan_compaction,
+        )
+
     async def _prime_sink_from_pending(self, sid: str, sink: SQLiteSink) -> None:
         store = await self._ensure_store()
         state = await store.get_state(sid)