power-loop 7.3.1__tar.gz → 8.0.0__tar.gz

{power_loop-7.3.1 → power_loop-8.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: power-loop
-Version: 7.3.1
+Version: 8.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-7.3.1 → power_loop-8.0.0}/power_loop/__init__.py

@@ -15,7 +15,7 @@ Stability tiers
 无版本承诺，可随时变更或删除。
 """
 
-__version__ = "7.3.1"
+__version__ = "8.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).

{power_loop-7.3.1 → power_loop-8.0.0}/power_loop/agent/stateful_loop.py

@@ -1302,6 +1302,8 @@ class StatefulAgentLoop:
                              "title": str(w.get("workflow") or "")[:80],
                              "status": "running" if is_run_live(rid) else "orphaned",
                              "started_at": ts, "origin": _origin(ts)})
+        from power_loop.runtime.delegation import running_jobs
+        jobs.extend(running_jobs(store, session_id))
         for tm in await store.list_timers(session_id, statuses=("armed",)):
             jobs.append({"id": f"timer:{tm.timer_id}", "kind": "timer",
                          "title": str(tm.note or "")[:80], "status": "armed",
@@ -1343,6 +1345,9 @@ class StatefulAgentLoop:
                     result = "stopped"
         elif kind == "wf" and ref:
             result = await stop_run(ref, grace_s=pol.workflow_s, reason="stopped")
+        elif kind == "sub" and ref:
+            from power_loop.runtime.delegation import stop
+            result = await stop(store, session_id, ref, pol.workflow_s)
         elif kind == "timer" and ref.isdigit():
             result = "stopped" if await self.cancel_timer(session_id, int(ref)) else "finished"
         return {"id": job_id, "result": result}
@@ -2407,14 +2412,10 @@ class StatefulAgentLoop:
     ) -> 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
+        Includes child sessions regardless of their tool-context/fuse setting.
+        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
-                and self.config.tool_context is None):
-            return  # legacy behavior; policy-enabled children prepare their own context
         if status in ("waiting_for_input", "pending_tools"):
             return  # send not finished; the resume will re-finalize under the same send_index
         # 只取本 send 的行：这里要投影的就是这一个 send，从前是读全表再在 Python 里过滤，

{power_loop-7.3.1 → power_loop-8.0.0}/power_loop/core/pipeline.py

@@ -2338,8 +2338,13 @@ class AgentPipeline:
                                                     tool_call_id=call_id, failed=failed),
                            round_index=round_idx)
 
+                stored_output = _truncate_result(output, self.config.tool_result_max_chars)
+                if tool_name == "spawn_agent":
+                    from power_loop.runtime.delegation import result_view
+                    # Structured receipts/results cannot be cut through their metadata or JSON.
+                    stored_output = result_view(str(output), self.config.tool_result_max_chars or 20000) or stored_output
                 await self._append_message(
-                    {"role": "tool", "tool_call_id": call_id, "name": tool_name, "content": _truncate_result(output, self.config.tool_result_max_chars)},
+                    {"role": "tool", "tool_call_id": call_id, "name": tool_name, "content": stored_output},
                     round_index=round_idx,
                 )
 

power_loop-8.0.0/power_loop/runtime/delegation.py

@@ -0,0 +1,382 @@
+"""Asynchronous subagent sessions, durable results and serialized continuation.
+
+The host owns idle-parent wake routing. No notification callback starts a bare parent loop.
+Execution is process-local; records and undelivered inbox items survive the process.
+"""
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+import secrets
+import weakref
+from dataclasses import dataclass, field, replace
+from typing import Any
+
+from power_loop.agent.follow_up import InboxItem
+from power_loop.core.agent_context import get_session_id
+from power_loop.runtime.cancellation import CancellationToken
+from power_loop.runtime.recall import authorize, dumps
+from power_loop.runtime.spec import (
+    _ON_CHILD_SESSION,
+    _USAGE_SINK,
+    AgentSpec,
+    run_agent_spec,
+    workflow_continuation_loop,
+)
+
+log = logging.getLogger(__name__)
+RESULT_PREFIX = "[subagent_result]\n"
+
+
+@dataclass
+class Running:
+    run_id: str
+    task: asyncio.Task | None = None
+    token: Any = None
+    parent: str = ""
+    title: str = ""
+    suppress_wake: bool = False
+    phase: str = "running"
+    descendant_usage: dict = field(default_factory=dict)
+    projection_expected: bool = True
+
+
+_RUNNING: dict[tuple[int, str], Running] = {}
+_TASKS: set[asyncio.Task] = set()
+
+
+def _retain(task):
+    _TASKS.add(task)
+    task.add_done_callback(_TASKS.discard)
+
+
+async def _save_result(store, parent, sid, run, raw, after_seq, lifecycle):
+    messages = await store.history_bounds(sid)
+    messages = [max(after_seq + 1, messages[0]), messages[1]] if messages and messages[1] > after_seq else None
+    projection, projection_status = None, "empty"
+    try:
+        projection = await store.history_bounds(sid, source="projection", after_seq=after_seq)
+        projection_status = "ready" if projection else "failed" if run.projection_expected else "disabled"
+    except ValueError:
+        projection_status = "disabled"
+    usage = dict(raw.get("usage") or {})
+    for name, value in run.descendant_usage.items():
+        usage[name] = usage.get(name, 0) + value
+    result = {**raw, "usage": usage, "session_id": sid, "run_id": run.run_id, "messages": messages,
+              "projection": projection, "history_status": "available" if messages else "empty",
+              "projection_status": projection_status}
+    # Persist ownership/prepared result BEFORE any destructive cleanup.
+    key = "subagent:run:" + run.run_id
+    await store.set_runtime_state(parent, key, {"phase": "prepared", "result": result})
+    if lifecycle == "ephemeral" and raw.get("status") == "completed":
+        await store.close_session(sid, cascade=True)
+        result.update(messages=None, projection=None, history_status="deleted", projection_status="deleted")
+        await store.set_runtime_state(parent, "subagent:child:" + sid,
+                                      {"deleted": True, "lifecycle": lifecycle})
+    await store.set_runtime_state(parent, key, {"phase": "completed", "result": result, "notified": False})
+    return result
+
+
+async def _finish(loop, parent, sid, running, raw, after_seq, lifecycle, finalize, on_complete):
+    store = await loop.ensure_store()
+    running.phase = "settling"
+    children = [r.task for (key, _), r in list(_RUNNING.items())
+                if key == id(store) and r.parent == sid and r.task is not None]
+    if children:
+        await asyncio.gather(*children)
+    if finalize is not None:
+        raw = await finalize(sid, raw)
+    # A nudge racing finalization is already durable. Consume it in this run before returning.
+    continuation = None
+    while (await store.inbox_counts(sid))["pending"]:
+        if running.token.is_cancelled():
+            break
+        if continuation is None:
+            continuation = await workflow_continuation_loop(loop, sid)
+        with contextlib.ExitStack() as guards:
+            for _, guard in getattr(loop, "_child_run_guards", ()):
+                guards.enter_context(guard())
+            extra = await continuation.flush_follow_ups(sid, stop_event=running.token)
+        if extra is None:
+            break
+        raw["final_text"] = str(extra.final_text or "")
+        raw["status"] = extra.status
+        raw["rounds"] = int(raw.get("rounds", 0)) + int(extra.rounds)
+        usage = dict(raw.get("usage") or {})
+        for key, value in (extra.usage or {}).items():
+            usage[key] = usage.get(key, 0) + value
+        raw["usage"] = usage
+        if finalize is not None:
+            raw = await finalize(sid, raw)
+    # From the final pending check through cleanup, nudge uses our gate (below).
+    async with _gate(store, sid):
+        child_active = any(key == id(store) and r.parent == sid for (key, _), r in _RUNNING.items())
+        if ((await store.inbox_counts(sid))["pending"] or child_active) and not running.token.is_cancelled():
+            # Re-enter outside the gate; callers can enqueue without losing accepted input.
+            again = True
+        else:
+            again = False
+            result = await _save_result(store, parent, sid, running, raw, after_seq, lifecycle)
+            def accumulate(value):
+                totals = dict(value or {})
+                for name, count in result.get("usage", {}).items():
+                    if isinstance(count, (int, float)) and not isinstance(count, bool):
+                        totals[name] = totals.get(name, 0) + count
+                return totals
+            await store.mutate_runtime_state(parent, "subagent:usage:total", accumulate, default={})
+            parent_run = _RUNNING.get((id(store), parent))
+            if parent_run is not None:
+                for name, value in result.get("usage", {}).items():
+                    if isinstance(value, (int, float)) and not isinstance(value, bool):
+                        parent_run.descendant_usage[name] = parent_run.descendant_usage.get(name, 0) + value
+            _RUNNING.pop((id(store), sid), None)
+            _publish_completion(loop, parent, sid, result)
+    if again:
+        return await _finish(loop, parent, sid, running, raw, after_seq, lifecycle, finalize, on_complete)
+    try:
+        if running.suppress_wake:
+            return result
+        # Inbox delivery is durable and deduplicated before asking the host to wake an idle
+        # parent. A failed/skipped wake still leaves the result for its next normal send.
+        await loop.deliver(InboxItem(RESULT_PREFIX + completion_view(loop, result), kind="task_done",
+                                    item_id="subagent:" + running.run_id), parent, enqueue_only=True)
+        if on_complete is not None:
+            await on_complete(parent, result)
+        record = await store.get_runtime_state(parent, "subagent:run:" + running.run_id)
+        await store.set_runtime_state(parent, "subagent:run:" + running.run_id, {**record, "notified": True})
+    except Exception:
+        log.exception("subagent completion not delivered; durable result retained: %s", running.run_id)
+    return result
+
+
+_GATES: weakref.WeakValueDictionary = weakref.WeakValueDictionary()
+
+
+def _gate(store, sid):
+    return _GATES.setdefault((id(store), sid), asyncio.Lock())
+
+
+async def _complete(loop, parent, sid, run, raw, after_seq, lifecycle, finalize, on_complete):
+    """Finalization errors/cancellation must not leave an immortal running job."""
+    store = await loop.ensure_store()
+    try:
+        return await _finish(loop, parent, sid, run, raw, after_seq, lifecycle, finalize, on_complete)
+    except BaseException as exc:
+        failed = {**raw, "status": "cancelled" if isinstance(exc, asyncio.CancelledError) else "failed",
+                  "error": f"subagent finalization: {type(exc).__name__}: {exc}"}
+        try:
+            result = await _save_result(store, parent, sid, run, failed, after_seq, lifecycle)
+            _publish_completion(loop, parent, sid, result)
+            if not run.suppress_wake:
+                await loop.deliver(InboxItem(RESULT_PREFIX + completion_view(loop, result), kind="task_done",
+                                            item_id="subagent:" + run.run_id), parent, enqueue_only=True)
+                if on_complete is not None:
+                    await on_complete(parent, result)
+            return result
+        except Exception:
+            log.exception("subagent finalization failed; original records retained: %s", run.run_id)
+    finally:
+        if _RUNNING.get((id(store), sid)) is run:
+            _RUNNING.pop((id(store), sid), None)
+
+
+async def start(loop, spec: AgentSpec, task: str, *, on_complete=None, finalize=None,
+                admission: asyncio.Semaphore | None = None) -> dict[str, Any]:
+    parent = get_session_id()
+    if parent is None:
+        raise ValueError("spawn_agent requires an active parent session")
+    store = await loop.ensure_store()
+    parent_run = _RUNNING.get((id(store), parent))
+    ready = asyncio.get_running_loop().create_future()
+    run = Running(secrets.token_hex(8), token=CancellationToken(), parent=parent, title=spec.name)
+    if parent_run is not None:
+        run.token = parent_run.token.child()
+
+    admitted = False
+
+    async def created(sid):
+        nonlocal admitted
+        session = await store.get_session(sid)
+        run.projection_expected = session.config.get("context_projection", True)
+        _RUNNING[(id(store), sid)] = run
+        await store.set_runtime_state(parent, "subagent:child:" + sid,
+                                      {"deleted": False, "lifecycle": spec.lifecycle})
+        await store.set_runtime_state(parent, "subagent:run:" + run.run_id,
+                                      {"phase": "running", "session_id": sid, "run_id": run.run_id})
+        await store.merge_session_metadata(sid, {"standalone_subagent": True})
+        ready.set_result(sid)
+        if admission is not None:
+            run.phase = "queued"
+            await admission.acquire()
+            admitted = True
+            run.phase = "running"
+
+    async def execute():
+        token = _ON_CHILD_SESSION.set(created)
+        usage = _USAGE_SINK.set(None)
+        sid = None
+        try:
+            # Manager owns cleanup, after repair/projection/range collection.
+            raw = await run_agent_spec(replace(spec, lifecycle="linked", metadata={**spec.metadata, "managed_subagent": True}), task,
+                                       parent_loop=loop, stop_event=run.token)
+            sid = ready.result() if ready.done() and not ready.cancelled() else None
+            if sid is None:
+                raise ValueError(raw.get("final_text") or "child session was not created")
+        except BaseException as exc:
+            if not ready.done():
+                ready.set_exception(exc)
+                return
+            sid = ready.result()
+            raw = {"status": "cancelled" if isinstance(exc, asyncio.CancelledError) else "failed",
+                   "final_text": "", "rounds": 0, "usage": {}, "error": str(exc)}
+        finally:
+            _ON_CHILD_SESSION.reset(token)
+            _USAGE_SINK.reset(usage)
+            if admitted:
+                admission.release()
+        await _complete(loop, parent, sid, run, raw, 0, spec.lifecycle, finalize, on_complete)
+
+    run.task = asyncio.create_task(execute(), name="subagent-" + run.run_id)
+    _retain(run.task)
+    sid = await asyncio.shield(ready)
+    return {"session_id": sid, "run_id": run.run_id, "mode": "create", "status": "queued"}
+
+
+async def nudge(loop, sid: str, message: str, *, on_complete=None, finalize=None,
+                admission: asyncio.Semaphore | None = None) -> dict[str, Any]:
+    parent = get_session_id()
+    if parent is None:
+        raise ValueError("nudge requires an active parent session")
+    store = await loop.ensure_store()
+    _, unavailable = await authorize(store, parent, sid)
+    if unavailable:
+        return {"status": "unavailable", "reason": unavailable, "session_id": sid}
+    row = await store.get_session(sid)
+    if not row.metadata.get("standalone_subagent"):
+        raise ValueError("not a standalone subagent; use the owning workflow's nudge")
+    # Build using the saved child contract and current parent policy, never the parent's full tools.
+    child_loop = await workflow_continuation_loop(loop, sid)
+    async with _gate(store, sid):
+        running = _RUNNING.get((id(store), sid))
+        if running is not None:
+            await child_loop.deliver(InboxItem(message, mode="steer"), sid, enqueue_only=True)
+            return {"session_id": sid, "run_id": running.run_id, "mode": "steer", "status": "accepted"}
+        if child_loop._lock_for(sid).locked():
+            raise ValueError("session is owned by another execution; nudge was not accepted")
+        record = await store.get_runtime_state(parent, "subagent:child:" + sid)
+        lifecycle = record.get("lifecycle", "linked")
+        before = await store.history_bounds(sid)
+        after_seq = before[1] if before else 0
+        run = Running(secrets.token_hex(8), token=CancellationToken(), parent=parent, title=str(row.metadata.get("spec_name") or "subagent"))
+        run.projection_expected = child_loop.config.projection_representation is not None
+        parent_run = _RUNNING.get((id(store), parent))
+        if parent_run is not None:
+            run.token = parent_run.token.child()
+        _RUNNING[(id(store), sid)] = run
+        await store.set_runtime_state(parent, "subagent:run:" + run.run_id,
+                                      {"phase": "queued", "session_id": sid, "run_id": run.run_id})
+
+        async def execute():
+            from power_loop.contracts.event_payloads import SubagentTaskStartPayload
+            from power_loop.contracts.events import AgentEventType
+            from power_loop.runtime.spec import _publish_subagent_event
+            from power_loop.workflow.engine import InProcessExecutor
+            _publish_subagent_event(loop, parent, AgentEventType.SUBAGENT_TASK_START,
+                                   SubagentTaskStartPayload(task=message, preset=run.title,
+                                                           sub_session_id=sid, depth=row.spawn_depth))
+            admitted = False
+            try:
+                if admission is not None:
+                    run.phase = "queued"
+                    await admission.acquire()
+                    admitted = True
+                run.phase = "running"
+                raw = await InProcessExecutor().continue_agent(
+                    sid, message, parent_loop=loop, extra_rounds=child_loop.config.max_rounds,
+                    stop_event=run.token)
+            except BaseException as exc:
+                raw = {"status": "cancelled" if isinstance(exc, asyncio.CancelledError) else "failed",
+                       "final_text": "", "rounds": 0, "usage": {}, "error": str(exc)}
+            finally:
+                if admitted:
+                    admission.release()
+            await _complete(loop, parent, sid, run, raw, after_seq, lifecycle, finalize, on_complete)
+
+        run.task = asyncio.create_task(execute(), name="subagent-" + run.run_id)
+        _retain(run.task)
+        return {"session_id": sid, "run_id": run.run_id, "mode": "continue", "status": "queued"}
+
+
+def result_view(text: str, cap: int = 600) -> str | None:
+    """Tool-context rule: only final_text may change, never envelope metadata."""
+    import json
+    try:
+        value = json.loads(text)
+    except (ValueError, TypeError):
+        return None
+    if not isinstance(value, dict) or "session_id" not in value or not value.get("run_id"):
+        return None
+    if isinstance(value.get("final_text"), str) and len(value["final_text"]) > cap:
+        value["final_text"] = value["final_text"][:max(0, cap)] + "…[truncated]"
+    return dumps(value)
+
+
+def running_jobs(store, parent):
+    return [{"id": "sub:" + run.run_id, "kind": "subagent", "title": run.title,
+             "status": run.phase, "session_id": sid, "started_at": None, "origin": ""}
+            for (key, sid), run in _RUNNING.items() if key == id(store) and run.parent == parent]
+
+
+async def stop(store, parent, run_id, grace_s):
+    run = next((run for (key, _), run in _RUNNING.items()
+                if key == id(store) and run.parent == parent and run.run_id == run_id), None)
+    if run is None:
+        return "finished"
+    run.suppress_wake = True
+    run.token.cancel("stopped")
+    try:
+        await asyncio.wait_for(asyncio.shield(run.task), timeout=grace_s)
+        return "stopped"
+    except TimeoutError:
+        run.task.cancel()
+        return "forced"
+
+
+async def await_children(store, parent, stop_event=None, timeout_s=1800):
+    """Owning executors must collect asynchronous descendants before settling a leaf."""
+    deadline = asyncio.get_running_loop().time() + timeout_s
+    token = CancellationToken.from_any(stop_event)
+    while True:
+        runs = [run for (key, _), run in _RUNNING.items()
+                if key == id(store) and run.parent == parent and run.task is not None]
+        if not runs:
+            return
+        if token.is_cancelled():
+            for run in runs:
+                run.token.cancel("parent cancelled")
+            raise ValueError("cancelled while waiting for subagents")
+        if asyncio.get_running_loop().time() >= deadline:
+            raise ValueError("subagents still pending after completion wait")
+        await asyncio.wait([run.task for run in runs], timeout=0.1)
+
+
+def completion_view(loop, result):
+    config = getattr(loop, "config", None)
+    policy = getattr(config, "tool_context", None)
+    projection = getattr(getattr(config, "representation", None), "projection_cfg", {}) or {}
+    overrides = getattr(policy, "overrides", {}) or {}
+    cap = overrides.get("spawn_agent", {}).get("result_max_chars") or projection.get("final_text_cap") or 600
+    return result_view(dumps(result), int(cap))
+
+
+def _publish_completion(loop, parent, sid, result):
+    from power_loop.contracts.event_payloads import SubagentCompletedPayload, SubagentTextPayload
+    from power_loop.contracts.events import AgentEventType
+    from power_loop.runtime.spec import _publish_subagent_event
+    status = str(result.get("status") or "failed")
+    fields = {"sub_session_id": sid, "status": status, "rounds": int(result.get("rounds") or 0),
+              "final_text": str(result.get("final_text") or "")}
+    if status == "completed":
+        _publish_subagent_event(loop, parent, AgentEventType.SUBAGENT_TEXT, SubagentTextPayload(**fields))
+    _publish_subagent_event(loop, parent, AgentEventType.SUBAGENT_COMPLETED, SubagentCompletedPayload(**fields))

power_loop-8.0.0/power_loop/runtime/recall.py

@@ -0,0 +1,215 @@
+"""Bounded audit reads and exclusive JSONL exports; never runs recalled tools."""
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import os
+import re
+import tempfile
+from pathlib import Path
+from typing import Any
+
+
+def dumps(value: Any) -> str:
+    return json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+
+
+async def authorize(store: Any, parent: str, child: str | None) -> tuple[str, str | None]:
+    if child is None:
+        return parent, None
+    row = await store.get_session(child)
+    if row is not None:
+        if row.parent_session_id != parent:
+            raise ValueError("access_denied: sub_session must be your direct child")
+        return child, None
+    ownership = await store.get_runtime_state(parent, "subagent:child:" + child, default=None)
+    if isinstance(ownership, dict) and ownership.get("deleted"):
+        return child, "session_deleted"
+    raise ValueError("access_denied: no authorized child session")
+
+
+def _integer(value: Any, name: str, minimum: int, maximum: int) -> int:
+    if isinstance(value, bool) or not isinstance(value, int) or not minimum <= value <= maximum:
+        raise ValueError(f"{name} must be an integer in [{minimum},{maximum}]")
+    return value
+
+
+def _screen(value: Any) -> Any:
+    if isinstance(value, str):
+        return re.sub(r"data:[^\s\"']*?;base64,[A-Za-z0-9+/=]+", "[inline media omitted]", value)
+    if isinstance(value, dict):
+        return {k: _screen(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_screen(v) for v in value]
+    return value
+
+
+async def recall(
+    store: Any, parent: str, *, sub_session: str | None = None, source: str = "messages",
+    ids: list[int] | None = None, seq: int | None = None, id: int | None = None,
+    send_index: int | None = None, limit: int = 20, cursor: str | None = None,
+    char_offset: int | None = None, char_limit: int | None = None,
+    output_file: str | None = None,
+) -> str:
+    """Return valid JSON envelopes; cursor binds the selection and captured upper bound."""
+    try:
+        sid, unavailable = await authorize(store, parent, sub_session)
+        if unavailable:
+            return dumps({"status": "unavailable", "reason": unavailable, "session_id": sid})
+        if source not in {"messages", "projection"}:
+            raise ValueError("source must be messages or projection")
+        limit = _integer(limit, "limit", 1, 100)
+        offset = _integer(0 if char_offset is None else char_offset, "char_offset", 0, 2**63 - 1)
+        budget = _integer(8000 if char_limit is None else char_limit, "char_limit", 256, 32000)
+        if seq is not None and source != "messages" or id is not None and source != "projection":
+            raise ValueError("seq selects messages; id selects projection")
+        single = seq if source == "messages" else id
+        if ids is not None and (single is not None or send_index is not None):
+            raise ValueError("choose ids OR a single record OR send_index")
+        if ids is None and single is None and send_index is None:
+            raise ValueError("select ids=[lo,hi], seq (messages), id (projection), or send_index")
+        if send_index is not None:
+            _integer(send_index, "send_index", 1, 2**63 - 1)
+        lo, hi = 0, None
+        if ids is not None:
+            if not isinstance(ids, list) or len(ids) != 2:
+                raise ValueError("ids must be [inclusive_start,inclusive_end]")
+            lo, hi = [_integer(x, "ids", 1, 2**63 - 1) for x in ids]
+            if lo > hi:
+                raise ValueError("ids start exceeds end")
+        if single is not None:
+            lo = hi = _integer(single, "record coordinate", 1, 2**63 - 1)
+        elif offset:
+            raise ValueError("char_offset requires seq or id")
+        if output_file is not None and not str(output_file).strip():
+            raise ValueError("output_file must be a new workspace path")
+        if output_file is not None and (cursor is not None or char_offset is not None or char_limit is not None):
+            raise ValueError("output_file exports full records; omit cursor/char_offset/char_limit")
+        coord = "seq" if source == "messages" else "id"
+        selection = {"session_id": sid, "source": source, "ids": ids, "single": single,
+                     "send_index": send_index}
+        signature = hashlib.sha256(dumps(selection).encode()).hexdigest()
+        after = 0
+        if cursor:
+            try:
+                state = json.loads(base64.urlsafe_b64decode(cursor.encode()))
+                if state["selection"] != signature:
+                    raise ValueError
+                after = _integer(state["after"], "cursor", 0, 2**63 - 1)
+                hi = _integer(state["hi"], "cursor upper bound", 1, 2**63 - 1)
+                if ids is not None and hi > ids[1] or after < lo - 1:
+                    raise ValueError
+            except (ValueError, TypeError, KeyError, UnicodeError):
+                raise ValueError("invalid cursor for this session/selection") from None
+        else:
+            bounds = await store.history_bounds(sid, source=source)
+            if bounds is None:
+                return dumps({"status": "unavailable", "reason": "records_not_found"})
+            hi = min(hi, bounds[1]) if hi is not None else bounds[1]
+        rows = await store.history_records(sid, source=source, lo=lo, hi=hi, after=after,
+                                           limit=limit + 1, send_index=send_index)
+        if not rows:
+            return dumps({"status": "unavailable", "reason": "records_not_found"})
+        if output_file:
+            return await _export(store, sid, source, lo, hi, send_index, output_file)
+        if single is not None:
+            text = dumps(_screen(rows[0]))
+            def envelope(size):
+                piece = text[offset:offset + size]
+                end = offset + len(piece)
+                return dumps({"status": "ok", "session_id": sid, "source": source, coord: single,
+                              "format": "record_json_text", "text": piece, "total_chars": len(text),
+                              "next_char_offset": end if end < len(text) else None,
+                              "truncated": end < len(text)})
+            left, right = 0, min(budget, max(0, len(text) - offset))
+            while left < right:
+                middle = (left + right + 1) // 2
+                if len(envelope(middle)) <= budget:
+                    left = middle
+                else:
+                    right = middle - 1
+            if not left and offset < len(text):
+                raise ValueError("char_limit is too small for record metadata; increase it")
+            return envelope(left)
+        shown = []
+        # Reserve room for envelope/cursor. Each preview includes ALL large fields in its budget.
+        used = 0
+        for row in rows[:limit]:
+            item = {coord: row[coord], "send_index": row.get("send_index")}
+            for key in ("role", "kind", "source_seq_lo", "source_seq_hi", "projector_version"):
+                if key in row:
+                    item[key] = row[key]
+            text = dumps(_screen(row))
+            room = max(0, budget - used - len(dumps(item)) - 80)
+            if room < 80 and shown:
+                break
+            item.update(preview=text[:min(room, 500)], total_chars=len(text),
+                        truncated=len(text) > min(room, 500))
+            shown.append(item)
+            used += len(dumps(item))
+        while shown:
+            last = shown[-1][coord]
+            more = len(shown) < len(rows)
+            next_cursor = base64.urlsafe_b64encode(dumps(
+                {"selection": signature, "after": last, "hi": hi}).encode()).decode() if more else None
+            answer = dumps({"status": "ok", "session_id": sid, "source": source,
+                            "records": shown, "next_cursor": next_cursor})
+            if len(answer) <= budget:
+                return answer
+            if len(shown) == 1:
+                if shown[0]["preview"]:
+                    shown[0]["preview"] = ""
+                    shown[0]["truncated"] = True
+                    continue
+                raise ValueError("char_limit is too small for list metadata; increase it")
+            shown.pop()
+    except (ValueError, OSError) as exc:
+        return dumps({"status": "error", "error": str(exc)})
+
+
+async def _export(store, sid, source, lo, hi, send_index, output_file):
+    from power_loop.runtime.env import safe_path
+
+    directory, filename = os.path.split(output_file)
+    if not filename or filename in {".", ".."}:
+        raise ValueError("output_file must name a new file")
+    # Resolve/check the parent but preserve the final component: a dangling symlink is an
+    # existing target too, not permission to write through it to a different path.
+    target = safe_path(directory or ".", "w") / filename
+    safe_path(str(target), "w")
+    if target.exists() or target.is_symlink():
+        raise ValueError("output_file already exists; choose a new path")
+    target.parent.mkdir(parents=True, exist_ok=True)
+    fd, temporary = tempfile.mkstemp(prefix=".recall-", dir=target.parent)
+    stream = os.fdopen(fd, "wb")
+    count = size = 0
+    try:
+        # One read snapshot, no transaction spans an LLM/network request. Stream batches to disk.
+        async with store._db.transaction() as tx:
+            if store._db.dialect.name == "postgres":
+                await tx.execute("SET TRANSACTION ISOLATION LEVEL REPEATABLE READ READ ONLY")
+            with stream:
+                after = 0
+                while True:
+                    batch = await store.history_records(
+                        sid, source=source, lo=lo, hi=hi, after=after, limit=100,
+                        send_index=send_index, _fetchall=tx.fetchall)
+                    if not batch:
+                        break
+                    for row in batch:
+                        encoded = (dumps({"source": source, **row}) + "\n").encode("utf-8")
+                        stream.write(encoded)
+                        size += len(encoded)
+                        count += 1
+                    after = batch[-1]["seq" if source == "messages" else "id"]
+                stream.flush()
+                os.fsync(stream.fileno())
+        if not count:
+            raise ValueError("records_not_found")
+        # link is atomic and fails if another writer created the target; never replace it.
+        os.link(temporary, target)
+    finally:
+        stream.close()
+        Path(temporary).unlink(missing_ok=True)
+    return dumps({"status": "exported", "path": output_file, "records": count, "bytes": size})