Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
Python agentagent-osaiai-agentsai-partnerchatopsclaudeclaude-codecodexdevtoolsdiscord-botlark-botllmlocal-firstlong-term-memoryopencodeslack-botvibe-codingvibeywechat
refactor(agent-core): run C-9's checkpoint turn as a C-10 side turn (#2420)
Call White6e1a7fafd86d
diff --git a/core/agent_core/agent/checkpoint.py b/core/agent_core/agent/checkpoint.pydeleted file mode 100644index 5ab0662c0..000000000--- a/core/agent_core/agent/checkpoint.py+++ /dev/null@@ -1,109 +0,0 @@-"""The checkpoint turn's tool policy (C-9 ``context.md`` sections 6 and 10).--"Dreaming": a checkpoint turn may think with the tools that only look, and-write only into its own scratch space; anything that acts on the world is-denied and never executed. The loop's checkpoint tool pipeline asks it once-per call, after the turn's budget (``open``). Scratch is flat and is reached-only through the root's directory descriptor, which the policy opens when the-turn starts (``agent.scratch``): a write or edit is authorized only for a-single name directly inside the root, and runs relative to that descriptor.-"""--from __future__ import annotations--import os-from dataclasses import dataclass-from types import MappingProxyType-from typing import Literal, Mapping, Optional--from core.agent_core.agent.scratch import ScratchRoot, valid_name-from core.agent_core.messages import ToolCallBlock-from core.agent_core.tools.args import ToolInputError, str_arg-from core.agent_core.tools.base import ToolResult-from core.agent_core.tools.edit import prepare_edit_arguments-from core.agent_core.tools.paths import resolve_to_cwd--Rule = Literal["allow", "scratch"]--#: Tools a checkpoint turn may call; every other tool is denied.-CHECKPOINT_TOOL_POLICY: Mapping[str, Rule] = MappingProxyType(- {- "read": "allow",- "write": "scratch",- "edit": "scratch",- # Memory-read tools join here as "allow" once they exist.- }-)--#: Each ends by saying where the checkpoint belongs: a model denied a file write may otherwise keep trying one.-DENIED = (- "This is a checkpoint turn: tools that act outside your own scratch space are unavailable. "- "Write the checkpoint as your reply text, not into a file."-)-BUDGET_USED = (- "This is a checkpoint turn and its tool budget is used up. Write the checkpoint as your reply text, not into a file."-)---@dataclass(frozen=True)-class Decision:- """The table's answer for one call: a denial text, or allowed (``scratch``: the name in the scratch root)."""-- denial: Optional[str] = None- scratch: Optional[str] = None---class CheckpointPolicy:- """The table for one checkpoint turn; ``open`` is the turn's budget, which the loop closes.-- Opening the policy opens the scratch root; ``close`` releases it when the turn ends.- """-- def __init__(- self, *, cwd: str, scratch_dir: Optional[str], table: Mapping[str, Rule] = CHECKPOINT_TOOL_POLICY- ) -> None:- self._cwd = cwd- self._table = table- self._root = ScratchRoot.open(scratch_dir) if scratch_dir else None- # How a call may address the root: the configured path, or the real path it named when it was opened.- self._addresses = (- {os.path.normpath(os.path.abspath(scratch_dir)), os.path.realpath(scratch_dir)}- if self._root is not None- else set()- )- self.open = True-- def decide(self, call: ToolCallBlock) -> Decision:- """The table on ``call``'s arguments (the budget is the pipeline's first check, not this)."""- rule = self._table.get(call.name)- if rule == "allow":- return Decision()- name = self._scratch_name(call) if rule == "scratch" else None- return Decision(scratch=name) if name is not None else Decision(denial=DENIED)-- def run(self, call: ToolCallBlock, name: str) -> ToolResult:- """An authorized scratch ``write`` or ``edit``, relative to the root's descriptor."""- assert self._root is not None- return self._root.write(name, call.arguments) if call.name == "write" else self._root.edit(name, call.arguments)-- def close(self) -> None:- if self._root is not None:- self._root.close()- self._root = None-- def _scratch_name(self, call: ToolCallBlock) -> Optional[str]:- """The single file name a call addresses directly inside the scratch root, or None."""- if self._root is None:- return None- try:- arguments = prepare_edit_arguments(call.arguments) if call.name == "edit" else call.arguments- raw = str_arg(arguments, "path")- target = resolve_to_cwd(raw, self._cwd)- except (ToolInputError, ValueError):- return None- name = os.path.basename(target)- # Lexical only: nothing is resolved, because the write never goes through this pathname.- if os.path.dirname(target) not in self._addresses or not valid_name(name):- return None- last = raw.replace(os.altsep or os.sep, os.sep).rstrip(os.sep).rsplit(os.sep, 1)[-1]- return name if last == name else Nonediff --git a/core/agent_core/agent/fork.py b/core/agent_core/agent/fork.pynew file mode 100644index 000000000..d67d8c9ae--- /dev/null+++ b/core/agent_core/agent/fork.py@@ -0,0 +1,196 @@+"""The side turn (C-10 ``agent-core-contracts/fork.md`` sections 6, 7, and 15).++A side turn is a fork that lives inside its caller's run: the caller's request+through a cut of its current view, then a prompt, under a ``ForkPolicy`` that+names the tools it may run. Nothing it produces is context or shown; its+caller's ``fold`` decides what of its reply enters the caller's context, and+it leaves one ``fork_turn`` audit. C-9's checkpoint turn is the first one.++The policy is data. ``PolicyGate`` is one turn's policy in force: it asks the+table once per call, after the turn's budget (``open``). Scratch is flat and is+reached only through the root's directory descriptor, which the gate opens+when the turn starts (``agent.scratch``): a write or edit is authorized only+for a single name directly inside the root, and runs relative to that+descriptor.+"""++from __future__ import annotations++import os+from dataclasses import dataclass+from types import MappingProxyType+from typing import Awaitable, Callable, Literal, Mapping, Optional++from core.agent_core.agent.scratch import ScratchRoot, valid_name+from core.agent_core.ai.provider import ModelCapabilities+from core.agent_core.harness.store import ContextEntry+from core.agent_core.messages import AssistantMessage, ToolCallBlock, Usage, UserMessage+from core.agent_core.tools.args import ToolInputError, str_arg+from core.agent_core.tools.base import ToolResult+from core.agent_core.tools.edit import prepare_edit_arguments+from core.agent_core.tools.paths import resolve_to_cwd++Rule = Literal["allow", "scratch"]+++@dataclass(frozen=True)+class ForkPolicy:+ """What a side turn may run (section 6): a tool ``tools`` does not name is denied with ``denied`` and never runs.++ Its budget: at most ``max_rounds`` tool rounds, each call only while the window leaves ``room_floor``; a result is+ cut to the room less ``room_slack``. Past the budget every call is answered with ``budget_used``.+ """++ name: str+ tools: Mapping[str, Rule]+ denied: str+ budget_used: str+ max_rounds: int+ room_floor: int+ room_slack: int+++#: C-9's checkpoint turn (context.md section 6): it may think with the tools that only look, and write only into its+#: own scratch space. Each text ends by saying where the checkpoint belongs: a model denied a file write may otherwise+#: keep trying one.+DREAMING = ForkPolicy(+ name="dreaming",+ tools=MappingProxyType(+ {+ "read": "allow",+ "write": "scratch",+ "edit": "scratch",+ # Memory-read tools join here as "allow" once they exist.+ }+ ),+ denied=(+ "This is a checkpoint turn: tools that act outside your own scratch space are unavailable. "+ "Write the checkpoint as your reply text, not into a file."+ ),+ budget_used=(+ "This is a checkpoint turn and its tool budget is used up. Write the checkpoint as your reply text, not into a file."+ ),+ max_rounds=5,+ room_floor=4_000,+ room_slack=1_000,+)+++@dataclass(frozen=True)+class Decision:+ """The table's answer for one call: a denial text, or allowed (``scratch``: the name in the scratch root)."""++ denial: Optional[str] = None+ scratch: Optional[str] = None+++class PolicyGate:+ """One side turn's policy in force; ``open`` is the turn's budget, which the loop closes.++ Opening the gate opens the scratch root; ``close`` releases it when the turn ends.+ """++ def __init__(self, policy: ForkPolicy, *, cwd: str, scratch_dir: Optional[str]) -> None:+ self.policy = policy+ self._cwd = cwd+ self._root = ScratchRoot.open(scratch_dir) if scratch_dir else None+ # How a call may address the root: the configured path, or the real path it named when it was opened.+ self._addresses = (+ {os.path.normpath(os.path.abspath(scratch_dir)), os.path.realpath(scratch_dir)}+ if self._root is not None+ else set()+ )+ self.open = True++ def decide(self, call: ToolCallBlock) -> Decision:+ """The table on ``call``'s arguments (the budget is the pipeline's first check, not this)."""+ rule = self.policy.tools.get(call.name)+ if rule == "allow":+ return Decision()+ name = self._scratch_name(call) if rule == "scratch" else None+ return Decision(scratch=name) if name is not None else Decision(denial=self.policy.denied)++ def run(self, call: ToolCallBlock, name: str) -> ToolResult:+ """An authorized scratch ``write`` or ``edit``, relative to the root's descriptor."""+ assert self._root is not None+ return self._root.write(name, call.arguments) if call.name == "write" else self._root.edit(name, call.arguments)++ def close(self) -> None:+ if self._root is not None:+ self._root.close()+ self._root = None++ def _scratch_name(self, call: ToolCallBlock) -> Optional[str]:+ """The single file name a call addresses directly inside the scratch root, or None."""+ if self._root is None:+ return None+ try:+ arguments = prepare_edit_arguments(call.arguments) if call.name == "edit" else call.arguments+ raw = str_arg(arguments, "path")+ target = resolve_to_cwd(raw, self._cwd)+ except (ToolInputError, ValueError):+ return None+ name = os.path.basename(target)+ # Lexical only: nothing is resolved, because the write never goes through this pathname.+ if os.path.dirname(target) not in self._addresses or not valid_name(name):+ return None+ last = raw.replace(os.altsep or os.sep, os.sep).rstrip(os.sep).rsplit(os.sep, 1)[-1]+ return name if last == name else None+++@dataclass(frozen=True)+class SideReply:+ """A side turn's reply: a response that stopped with ``stop`` and called no tool."""++ message: AssistantMessage+ rounds: int+ usage: Optional[Usage]+++@dataclass(frozen=True)+class Folded:+ """What the caller's fold committed, if anything; a fold that failed (``error``) fails the turn."""++ row: Optional[ContextEntry]+ error: Optional[str] = None+++@dataclass(frozen=True)+class CheckpointDetail:+ """A checkpoint side turn's purpose fields (C-9 section 6)."""++ reason: Literal["threshold", "overflow"]+ mode: Literal["normal", "rolling"]+++#: Each purpose's ``detail`` type; every ``fork_turn`` audit records one.+_DETAILS: Mapping[str, type] = MappingProxyType({"checkpoint": CheckpointDetail})+++@dataclass(frozen=True)+class SideTurn:+ """One side turn (section 7). ``units``: the caller's current view, all of it (None) or its first ``units``."""++ purpose: Literal["checkpoint"]+ detail: CheckpointDetail+ units: Optional[int]+ prompt: UserMessage+ policy: ForkPolicy+ max_tokens: Callable[[ModelCapabilities], int]+ fold: Callable[[SideReply], Awaitable[Folded]]++ def __post_init__(self) -> None:+ expected = _DETAILS.get(self.purpose)+ if expected is None:+ raise ValueError(f"not a side-turn purpose: {self.purpose!r}")+ if not isinstance(self.detail, expected):+ raise TypeError(f"a {self.purpose} side turn needs a {expected.__name__} detail, not {self.detail!r}")+++@dataclass(frozen=True)+class SideTurnResult:+ outcome: Literal["completed", "failed"]+ folded: Optional[ContextEntry]+ error: Optional[str]+ #: Its request could not fit, or the provider refused it as overflow.+ overflow: bool = Falsediff --git a/core/agent_core/agent/loop.py b/core/agent_core/agent/loop.pyindex 5185e9df8..c33e07fe0 100644--- a/core/agent_core/agent/loop.py+++ b/core/agent_core/agent/loop.py@@ -3,8 +3,9 @@Queue semantics informed by Pi (MIT), packages/agent/src/agent-loop.ts, and thebare-loop control experiment. This is an Avibe implementation, not a port.With a ``ContextConfig`` the loop also applies C-9 before every model request:-clearing, the forked checkpoint turn, and the overflow ladder-(``agent-core-contracts/context.md``).+clearing, the checkpoint turn, and the overflow ladder+(``agent-core-contracts/context.md``). The checkpoint turn is a side turn+(``agent-core-contracts/fork.md`` section 7), which ``Agent.side_turn`` runs."""from __future__ import annotations@@ -16,10 +17,9 @@ import timefrom collections import dequefrom contextlib import asynccontextmanager, suppressfrom copy import deepcopy-from dataclasses import dataclass, replace+from dataclasses import asdict, dataclass, replacefrom typing import Any, AsyncIterator, Awaitable, Callable, Literal, Mapping, Optional, Sequence, TypeVar-from core.agent_core.agent.checkpoint import BUDGET_USED, DENIED, CheckpointPolicy, Decisionfrom core.agent_core.agent.events import (AgentError,AgentEvent,@@ -52,6 +52,16 @@ from core.agent_core.agent.hooks import (SkipTools,Snapshot,)+from core.agent_core.agent.fork import (+ DREAMING,+ CheckpointDetail,+ Decision,+ Folded,+ PolicyGate,+ SideReply,+ SideTurn,+ SideTurnResult,+)from core.agent_core.agent.jobs import TrackingJobHostfrom core.agent_core.agent.lifecycle import RunAborted as _Aborted, RunScopefrom core.agent_core.agent.models import ModelRouter, ModelSelection, RetryPolicy@@ -66,9 +76,6 @@ from core.agent_core.ai.provider import ()from core.agent_core.cancel import CancelTokenfrom core.agent_core.harness.context import (- CHECKPOINT_TOOL_FLOOR,- CHECKPOINT_TOOL_ROUNDS,- CHECKPOINT_TOOL_SLACK,CLEAR_SOFT_RATIO,DEFAULT_MAX_OUTPUT_TOKENS,INEFFECTIVE_RATIO,@@ -162,12 +169,8 @@ class _Exhausted(Exception):_CHECKPOINT_REQUEST = checkpoint_request()-#: The most a checkpoint-turn call that does not run adds: one of the policy's two fixed texts (never cut).-_FIXED_RESULT_TOKENS = max(text_tokens(DENIED), text_tokens(BUDGET_USED))--async def _silent(*_: Any, **__: Any) -> None:- """The checkpoint turn's emit: it shows nothing (C-9 section 6)."""+ """A side turn's emit: it shows nothing (C-10 section 7)."""@dataclass@@ -190,7 +193,7 @@ class _Attempt:row; ``audited``: its usage went to a ``ModelAttempt`` audit row (context.md section 10, invariant 4)."""- purpose: Literal["conversation", "checkpoint"]+ purpose: Literal["conversation", "side_turn"]request: ModelRequestmessage: Optional[AssistantMessage]error: Optional[ProviderError] = None@@ -204,8 +207,8 @@ class _Outcome:overflow: bool = False-class _ForkTooLarge(Exception):- """A checkpoint request that cannot fit the window; it is never sent."""+class _SideTurnTooLarge(Exception):+ """A side turn's request that cannot fit the window; it is never sent."""class Agent:@@ -429,7 +432,7 @@ class Agent:self._turn_inputs.add(row.context_seq)def _validate_response(self, message: AssistantMessage, *, after: Sequence[Message] = ()) -> None:- """A response is valid after the committed rows and then ``after`` (a checkpoint turn's own messages)."""+ """A response is valid after the committed rows and then ``after`` (a side turn's own messages)."""entries = list(self._rows)seq = max((entry.context_seq for entry in entries), default=0)for item in after:@@ -655,7 +658,7 @@ class Agent:selected: Optional[ModelSelection] = None,*,compose: Optional[Callable[[ModelSelection], Awaitable[tuple[ModelRequest, dict[str, Tool]]]]] = None,- purpose: Literal["conversation", "checkpoint"] = "conversation",+ purpose: Literal["conversation", "side_turn"] = "conversation",after: Sequence[Message] = (),) -> AsyncIterator[tuple[Done | ProviderError, dict[str, Tool]]]:"""One model request with its transient retries.@@ -663,11 +666,11 @@ class Agent:``compose(selection)`` is the request pipeline: it returns the final request, which is sent unchanged.A conversation request's pipeline is ``_compose``. Every attempt enters the run's attempt ledger. Aconversation request the provider rejects as overflow goes back through the pipeline with the ladder- told to shrink (C-9 section 8). A checkpoint attempt is never context.+ told to shrink (C-9 section 8). A side turn's attempt is never context.Admission is here, for every purpose: the response the caller receives (or a partial with content) is- valid after the committed rows and ``after``, the messages the request carried beyond them (a checkpoint- turn's request and its own turn), or ``ProviderProtocolViolation`` is raised before anyone acts on it.+ valid after the committed rows and ``after``, the messages the request carried beyond them (a side turn's+ prompt and its own turn), or ``ProviderProtocolViolation`` is raised before anyone acts on it."""ladder = _Ladder()if compose is None:@@ -1120,10 +1123,10 @@ class Agent:# --- C-9 context management (agent-core-contracts/context.md) ---------------## The ordering and ownership invariants are context.md section 10 (1-6), the one statement of them. Their- # owners here: ``_compose``, ``_fork``, and ``_minimal`` (1, requests composed and budgeted; ``_compaction`` is- # the one builder of checkpoint rows), ``_checkpoint_tool`` (2), ``_commit_context`` (3), ``self._attempts``- # with ``_settle_attempts`` and ``_checkpoint``'s one audit (4), ``harness.context.budget`` (5), and ``_model``- # (6, admission).+ # owners here: ``_compose``, ``_side_request``, and ``_minimal`` (1, requests composed and budgeted;+ # ``_compaction`` is the one builder of checkpoint rows), ``_side_tool`` (2, the side turn's tool pipeline,+ # C-10 section 7), ``_commit_context`` (3), ``self._attempts`` with ``_settle_attempts`` and ``side_turn``'s+ # one audit (4), ``harness.context.budget`` (5), and ``_model`` (6, admission).def _cache_cold(self) -> bool:"""No model request for longer than the provider cache TTL (section 3)."""@@ -1190,12 +1193,11 @@ class Agent:cut = normal_cut(view.units, plan.keep, turn_inputs=self._turn_inputs, pinned=view.pinned)if cut is not None:ladder.compacted = True- if not self._fork_fits(system, selected, view, "normal", cut):+ turn = self._checkpoint_turn(request, view, plan, cut, mode="normal", reason="threshold")+ if not self.side_turn_fits(turn, selected, system=system):shrink = True # no fork can take the whole context: the ladder from (b)else:- outcome = await self._checkpoint(- system, selected, request, view, plan, cut, mode="normal", reason="threshold", emit=emit- )+ outcome = await self._checkpoint(system, selected, turn, emit)if outcome.ok:return True# A checkpoint request that overflowed means the whole context cannot fit a fork (b).@@ -1277,37 +1279,6 @@ class Agent:return True # nothing to carryreturn (await self._minimal(system, selected, request, view, plan, carry=True))[1].can_fit- def _fork_base(self, view: ContextView, mode: str, cut: int) -> tuple[Message, ...]:- """What a fork carries before the checkpoint request: the whole context, or for a rolling fork its prefix."""- return tuple(view.messages) if mode == "normal" else view.prefix(cut)-- def _fork(- self,- system: str,- route: ModelSelection,- base: Sequence[Message],- prompt: UserMessage,- turn: Sequence[Message],- anchor: Optional[Anchor],- ) -> tuple[ModelRequest, dict[str, Tool], Budget]:- """A checkpoint turn's request on ``route`` (section 6) and its budget: ``base``, the checkpoint request,- and the turn so far. The stage's dry run and the turn itself compose it here, so they cannot differ."""- transcript = (*base, prompt, *turn)- request, tools = self._built(- system,- route,- messages=(*self._rehydrated(), *transcript),- max_tokens=checkpoint_max_tokens(route.capabilities, self.max_tokens),- )- return request, tools, budget(request, route.capabilities, transcript=transcript, anchor=anchor)-- def _fork_fits(self, system: str, selected: ModelSelection, view: ContextView, mode: str, cut: int) -> bool:- """A dry compose of the first request the checkpoint turn would send, budgeted: a choice, not admission."""- fork = self._fork(- system, selected, self._fork_base(view, mode, cut), _CHECKPOINT_REQUEST, (), last_anchor(self._rows, view)- )- return fork[2].can_fit-async def _shrink(self,system: str,@@ -1332,18 +1303,24 @@ class Agent:if not ladder.summary_failed and not ladder.compacted:ladder.compacted = Truecut = normal_cut(units, plan.keep, turn_inputs=self._turn_inputs, pinned=view.pinned)- if cut is not None and self._fork_fits(system, selected, view, "normal", cut):- outcome = await self._checkpoint(- system, selected, request, view, plan, cut, mode="normal", reason="overflow", emit=emit- )+ turn = (+ None+ if cut is None+ else self._checkpoint_turn(request, view, plan, cut, mode="normal", reason="overflow")+ )+ if turn is not None and self.side_turn_fits(turn, selected, system=system):+ outcome = await self._checkpoint(system, selected, turn, emit)if outcome.ok:return Trueladder.summary_failed = not outcome.overflowcontinueif not ladder.summary_failed and ladder.rolls < MAX_ROLLS:+ def rolling(cut: int) -> SideTurn:+ return self._checkpoint_turn(request, view, plan, cut, mode="rolling", reason="overflow")+cut = rolling_cut(units,- lambda cut: self._fork_fits(system, selected, view, "rolling", cut),+ lambda cut: self.side_turn_fits(rolling(cut), selected, system=system),turn_inputs=self._turn_inputs,pinned=view.pinned,)@@ -1351,9 +1328,7 @@ class Agent:ladder.rolls = MAX_ROLLScontinueladder.rolls += 1- outcome = await self._checkpoint(- system, selected, request, view, plan, cut, mode="rolling", reason="overflow", emit=emit- )+ outcome = await self._checkpoint(system, selected, rolling(cut), emit)if outcome.ok:return Trueladder.summary_failed = True@@ -1459,57 +1434,143 @@ class Agent:return _Exhausted(plan.input_limit, tuple(parts), kind)async def _checkpoint(- self,- system: str,- selected: ModelSelection,- request: ModelRequest,- view: ContextView,- plan: Budget,- cut: int,- *,- mode: str,- reason: str,- emit: Callable[..., Awaitable[None]],+ self, system: str, selected: ModelSelection, turn: SideTurn, emit: Callable[..., Awaitable[None]]) -> _Outcome:- """Sections 6 and 7: a forked checkpoint turn; on success its row joins the context."""+ """Sections 6 and 7: a checkpoint turn, the side turn ``_checkpoint_turn`` built; on success its row joins+ the context. The events and the run's bound are the checkpoint's; the turn is ``side_turn``'s."""+ reason, mode = turn.detail.reason, turn.detail.modeawait emit(CompactionStarted, reason=reason)- prompt = _CHECKPOINT_REQUEST- base = self._fork_base(view, mode, cut)+ result = await self.side_turn(turn, selected, system=system)+ if result.outcome == "failed":+ self._unproductive += 1+ await emit(CompactionFailed, reason=reason, error=result.error)+ return _Outcome(False, result.overflow)+ row = result.folded+ assert row is not None # a checkpoint's fold commits its row or fails+ if mode == "normal" and row.payload["tokens_after_estimate"] >= INEFFECTIVE_RATIO * row.payload["threshold"]:+ self._unproductive += 1 # it made too little room to count as progress+ await emit(+ CompactionFinished,+ event_id=row.row_id,+ reason=reason,+ mode=mode,+ tokens_before=row.payload["tokens_before"],+ tokens_after_estimate=row.payload["tokens_after_estimate"],+ )+ return _Outcome(True)++ def _checkpoint_turn(+ self, request: ModelRequest, view: ContextView, plan: Budget, cut: int, *, mode: str, reason: str+ ) -> SideTurn:+ """The checkpoint turn for ``cut`` as a side turn (C-10 section 12): the whole view, or for a rolling one its+ prefix, then the checkpoint request, under ``DREAMING``; its fold commits the checkpoint row."""++ async def fold(reply: SideReply) -> Folded:+ checkpoint = checkpoint_text(reply.message)+ if not checkpoint:+ return Folded(None, "The checkpoint turn ended without checkpoint text.")+ problem = checkpoint_problem(checkpoint)+ if problem is not None:+ # Not a checkpoint (a meta note, a partial one): it fails, and its text stays in the audit only; the+ # old context is kept (section 6).+ return Folded(None, f"The checkpoint turn's reply is not a checkpoint: {problem}.")+ origin = reply.message.origin+ summarizer = {+ "origin": {"provider": origin.provider, "api": origin.api, "model": origin.model},+ "prompt_version": PROMPT_VERSION,+ "rounds": reply.rounds,+ }+ try:+ hosted = await self._hosted(view, cut)+ except (_Aborted, asyncio.CancelledError):+ raise+ except Exception as failure:+ # Only the host's part after the model answered (state, lookup) is a failed checkpoint, counted; an+ # error building the row itself ends the run, like any engine error.+ return Folded(+ None, f"The checkpoint row could not be built: the host failed: {type(failure).__name__}: {failure}"+ )+ payload, _ = await self._compaction(+ request,+ view,+ plan,+ cut,+ mode=mode,+ reason=reason,+ checkpoint=checkpoint,+ summarizer=summarizer,+ usage=reply.usage,+ hosted=hosted,+ )+ (row,) = await self._commit_context([("compaction", payload)])+ return Folded(row)++ return SideTurn(+ purpose="checkpoint",+ detail=CheckpointDetail(reason=reason, mode=mode),+ units=None if mode == "normal" else cut,+ prompt=_CHECKPOINT_REQUEST,+ policy=DREAMING,+ max_tokens=lambda capabilities: checkpoint_max_tokens(capabilities, self.max_tokens),+ fold=fold,+ )++ # --- C-10 side turn (agent-core-contracts/fork.md section 7) ----------------++ def side_turn_fits(self, turn: SideTurn, route: ModelSelection, *, system: str) -> bool:+ """A dry compose of the first request ``turn`` would send on ``route``, budgeted: a choice, not admission."""+ view = context_view(self._rows)+ return self._side_request(system, route, turn, view, (), last_anchor(self._rows, view))[2].can_fit++ async def side_turn(self, turn: SideTurn, route: ModelSelection, *, system: str) -> SideTurnResult:+ """``turn`` inside the caller's run, first on ``route``, with the run's ``system`` (section 7).++ It goes through the run's model call, silently, and its calls through ``_side_tool``. A response that stops+ with ``stop`` and calls no tool is its reply, which ``turn.fold`` folds into the context; anything else fails+ it. One ``fork_turn`` audit on every exit but an abort (F7). v1 runs it only while a run is active, the+ Session's one writer; a side turn while idle is reserved.+ """+ view = context_view(self._rows)anchor = last_anchor(self._rows, view)- policy = CheckpointPolicy(cwd=self.cwd, scratch_dir=self.context.scratch_dir)- turn: list[Message] = [] # what the turn's next request carries after the checkpoint request+ point = {"as_of": view.context_seq, "units": turn.units}+ policy = turn.policy+ scratch_dir = self.context.scratch_dir if self.context is not None else None+ gate = PolicyGate(policy, cwd=self.cwd, scratch_dir=scratch_dir)+ # The most a call that does not run adds: one of the policy's two fixed texts (never cut).+ fixed = max(text_tokens(policy.denied), text_tokens(policy.budget_used))+ so_far: list[Message] = [] # what the turn's next request carries after its promptproduced: list[Message] = [] # the audit: every attempt's message from the ledger, and the tool resultsstart = mark = len(self._attempts)measured: list[Budget] = [] # the budget of the turn's latest request, as sentrounds = 0error: Optional[str] = Noneoverflow = False- checkpoint = ""- origin = None- selection: Optional[ModelSelection] = selected-- async def compose(route: ModelSelection) -> tuple[ModelRequest, dict[str, Tool]]:- fork, tools, fork_plan = self._fork(system, route, base, prompt, turn, anchor)- if not fork_plan.can_fit:- raise _ForkTooLarge()- measured[:] = [fork_plan]- return fork, tools-- finished: dict[str, Any] = {"outcome": "failed", "error": None, "compaction_event_id": None}+ reply: Optional[SideReply] = None+ selection: Optional[ModelSelection] = route++ async def compose(selected: ModelSelection) -> tuple[ModelRequest, dict[str, Tool]]:+ request, tools, plan = self._side_request(system, selected, turn, view, so_far, anchor)+ if not plan.can_fit:+ raise _SideTurnTooLarge()+ measured[:] = [plan]+ return request, tools++ finished: dict[str, Any] = {"outcome": "failed", "error": None, "folded_event_id": None}aborted = Falsetry:try:while True:try:async with self._model(- system, _silent, selection, compose=compose, purpose="checkpoint", after=(prompt, *turn)+ system, _silent, selection, compose=compose, purpose="side_turn", after=(turn.prompt, *so_far)) as (terminal, tools):selection = None- except _ForkTooLarge:- overflow, error = True, "overflow: the checkpoint request does not fit the model's input limit."+ except _SideTurnTooLarge:+ overflow = True+ error = f"overflow: the {turn.purpose} request does not fit the model's input limit."breakexcept ProviderProtocolViolation as violation:- # Not admitted: a failed checkpoint, and none of its calls runs.+ # Not admitted: a failed side turn, and none of its calls runs.error = str(violation)breakfinally:@@ -1521,25 +1582,17 @@ class Agent:breakmessage = terminal.messageself._scope.check()- turn.append(message)- origin = message.origin+ so_far.append(message)if message.stop_reason == "stop" and not message.tool_calls:- checkpoint = checkpoint_text(message)- problem = checkpoint_problem(checkpoint) if checkpoint else None- if not checkpoint:- error = "The checkpoint turn ended without checkpoint text."- elif problem is not None:- # Not a checkpoint (a meta note, a partial one): it fails, and its text stays in the- # audit only; the old context is kept (section 6).- checkpoint, error = "", f"The checkpoint turn's reply is not a checkpoint: {problem}."+ reply = SideReply(message, rounds, self._turn_usage(start))breakif message.stop_reason != "tool_use" or not message.tool_calls:- # Only a stop with text and no call is a checkpoint, and only a tool-use stop carries calls.- error = f"The checkpoint turn stopped with {message.stop_reason} and no usable checkpoint."+ # Only a stop with no call is a reply, and only a tool-use stop carries calls.+ error = f"The {turn.purpose} turn stopped with {message.stop_reason} and no usable {turn.purpose}."break- if not policy.open:- # Its earlier calls were already answered with BUDGET_USED.- error = "The checkpoint turn kept calling tools after its tool budget was used up."+ if not gate.open:+ # Its earlier calls were already answered with the policy's budget text.+ error = f"The {turn.purpose} turn kept calling tools after its tool budget was used up."breakrounds += 1sent = measured[0]@@ -1549,85 +1602,73 @@ class Agent:self._scope.check()# The bound is the window of the turn's route: a tool runs only while the next request can# still grow by the floor, after the fixed-text results every later call of the batch may- # need are reserved (section 6).- reserved = (len(calls) - index - 1) * _FIXED_RESULT_TOKENS+ # need are reserved (C-9 section 6).+ reserved = (len(calls) - index - 1) * fixedroom = sent.input_limit - grown - sent.output - reserved- policy.open = policy.open and rounds <= CHECKPOINT_TOOL_ROUNDS and room >= CHECKPOINT_TOOL_FLOOR- result = await self._checkpoint_tool(call, tools, policy, limit=room - CHECKPOINT_TOOL_SLACK)- turn.append(result)+ gate.open = gate.open and rounds <= policy.max_rounds and room >= policy.room_floor+ result = await self._side_tool(call, tools, gate, limit=room - policy.room_slack)+ so_far.append(result)produced.append(result)grown += message_tokens(result)finally:- policy.close() # the scratch root's descriptor lives for this turn only- payload = None- if checkpoint:- summarizer = {- "origin": {"provider": origin.provider, "api": origin.api, "model": origin.model},- "prompt_version": PROMPT_VERSION,- "rounds": rounds,- }- try:- hosted = await self._hosted(view, cut)- except (_Aborted, asyncio.CancelledError):- raise- except Exception as failure:- # Only the host's part after the model answered (state, lookup) is a failed checkpoint,- # counted; an error building the row itself ends the run, like any engine error.- error = f"The checkpoint row could not be built: the host failed: {type(failure).__name__}: {failure}"- else:- payload, _ = await self._compaction(- request,- view,- plan,- cut,- mode=mode,- reason=reason,- checkpoint=checkpoint,- summarizer=summarizer,- usage=self._turn_usage(start),- hosted=hosted,- )- if payload is None:+ gate.close() # the scratch root's descriptor lives for this turn only+ folded = None+ if reply is not None:+ outcome = await turn.fold(reply)+ folded, error = outcome.row, outcome.error+ if reply is None or error is not None:finished["error"] = error- self._unproductive += 1- await emit(CompactionFailed, reason=reason, error=error)- return _Outcome(False, overflow)- (row,) = await self._commit_context([("compaction", payload)])- if mode == "normal" and payload["tokens_after_estimate"] >= INEFFECTIVE_RATIO * payload["threshold"]:- self._unproductive += 1 # it made too little room to count as progress- finished.update(outcome="completed", compaction_event_id=row.row_id)- await emit(- CompactionFinished,- event_id=row.row_id,- reason=reason,- mode=mode,- tokens_before=row.payload["tokens_before"],- tokens_after_estimate=row.payload["tokens_after_estimate"],- )- return _Outcome(True)+ return SideTurnResult("failed", None, error, overflow)+ finished.update(outcome="completed", folded_event_id=folded.row_id if folded is not None else None)+ return SideTurnResult("completed", folded, None)except (_Aborted, asyncio.CancelledError):aborted = True # the cancelled run scope admits no further store writeraiseexcept BaseException as failure:if finished["outcome"] != "completed" and finished["error"] is None:- finished["error"] = f"{type(failure).__name__}: {failure}" # a failed commit, or a failed compose+ finished["error"] = f"{type(failure).__name__}: {failure}" # a failed fold, or a failed composeraisefinally:if not aborted:- # Invariant 4 for checkpoint turns: one audit, from the ledger, on every exit but an abort.- await self._record_turn(self._turn_record(reason, mode, produced, start, finished))+ await self._audit("fork_turn", self._side_record(turn, point, rounds, produced, start, finished))++ def _side_request(+ self,+ system: str,+ route: ModelSelection,+ turn: SideTurn,+ view: ContextView,+ so_far: Sequence[Message],+ anchor: Optional[Anchor],+ ) -> tuple[ModelRequest, dict[str, Tool], Budget]:+ """A side turn's request on ``route`` and its budget (section 7 step 1): after the caller's rehydrated+ messages, its view through the turn's units, the turn's prompt, and the turn so far. The dry run and the+ turn itself compose it here, so they cannot differ."""+ base = view.prefix(len(view.units) if turn.units is None else turn.units)+ transcript = (*base, turn.prompt, *so_far)+ request, tools = self._built(+ system, route, messages=(*self._rehydrated(), *transcript), max_tokens=turn.max_tokens(route.capabilities)+ )+ return request, tools, budget(request, route.capabilities, transcript=transcript, anchor=anchor)def _turn_usage(self, start: int) -> Optional[Usage]:- """The usage every attempt of a checkpoint turn reported, from the ledger."""+ """The usage every attempt of a side turn reported, from the ledger."""usage = Nonefor item in self._attempts[start:]:usage = add_usage(usage, item.message.usage if item.message is not None else None)return usage- def _turn_record(- self, reason: str, mode: str, produced: Sequence[Message], start: int, finished: Mapping[str, Any]+ def _side_record(+ self,+ turn: SideTurn,+ point: Mapping[str, Any],+ rounds: int,+ produced: Sequence[Message],+ start: int,+ finished: Mapping[str, Any],) -> dict[str, Any]:- """A checkpoint turn's audit (``CheckpointTurn``, section 6): its messages, usage, and outcome."""+ """A side turn's audit (``ForkTurn``, section 15): its purpose, policy, point, detail, messages, usage, and+ outcome."""messages = []for message in produced:try:@@ -1635,38 +1676,46 @@ class Agent:except (ValueError, RecursionError) as invalid:# Arguments a provider sent that are not JSON: refused at admission (the turn's error names# them), and no JSON row can hold them either.- self._outcome.diagnostic(type(invalid).__name__, f"Checkpoint audit left out a message: {invalid}")- record: dict[str, Any] = {"version": 1, "reason": reason, "mode": mode, "messages": messages}+ self._outcome.diagnostic(type(invalid).__name__, f"Side turn audit left out a message: {invalid}")+ record: dict[str, Any] = {+ "version": 1,+ "purpose": turn.purpose,+ "policy": turn.policy.name,+ "point": dict(point),+ "detail": asdict(turn.detail),+ "rounds": rounds,+ "messages": messages,+ }usage = self._turn_usage(start)if usage is not None:record["usage"] = usage_to_dict(usage)return {**record, **finished}- async def _checkpoint_tool(- self, original: ToolCallBlock, tools: Mapping[str, Tool], policy: CheckpointPolicy, *, limit: int+ async def _side_tool(+ self, original: ToolCallBlock, tools: Mapping[str, Tool], gate: PolicyGate, *, limit: int) -> ToolResultMessage:- """The checkpoint turn's tool pipeline (invariant 2); nothing it produces is committed.+ """The side turn's tool pipeline (section 7 step 3); nothing it produces is committed.- The budget first, then the table, then execution (a scratch write or edit through the root's- descriptor), then the bound on whatever result came out. No user hook runs under C-9 (v1).+ The budget first, then the policy, then execution (a scratch write or edit through the root's+ descriptor), then the bound on whatever result came out. No user hook runs in a side turn (v1)."""call = deepcopy(original)- decision = policy.decide(call) if policy.open else Decision(denial=BUDGET_USED)+ decision = gate.decide(call) if gate.open else Decision(denial=gate.policy.budget_used)if decision.denial is not None:# The policy's fixed texts are short and never cut: a truncation note would invite another call.return ToolResultMessage(call.id, call.name, (text(decision.denial),), True)if decision.scratch is not None:# Relative to the scratch root's descriptor: no pathname is resolved again. Joined, never interrupted:- # the worker thread outlives a cancelled await, and the root closes only after it is done (section 6).+ # the worker thread outlives a cancelled await, and the root closes only after it is done (C-9 section 6).result = await self._scope.call(- lambda: to_thread_joined(policy.run, call, decision.scratch), interruptible=False+ lambda: to_thread_joined(gate.run, call, decision.scratch), interruptible=False)elif (tool := tools.get(call.name)) is None:result = ToolResult((text(f"Tool {call.name} is not available."),), is_error=True)else:- # A checkpoint turn's call has no committed response, so no instance: it starts no job.+ # A side turn's call has no committed response, so no instance: it starts no job (F4).result = await self._execute(tool, call, None, _silent)- # Every other result that enters the turn is bounded to the room the window leaves (section 6).+ # Every other result that enters the turn is bounded to the room the window leaves (C-9 section 6).return ToolResultMessage(call.id, call.name, fit_result(result.content, limit), result.is_error)async def _drop(@@ -1770,11 +1819,7 @@ class Agent:self._committed_state, self._committed_state_json = state, representationreturn tuple(row for row in committed if row.kind != "agent_state")- async def _record_turn(self, payload: Mapping[str, Any]) -> None:- """The checkpoint turn's audit row (section 6)."""- await self._audit("checkpoint_turn", payload)-- async def _audit(self, kind: Literal["checkpoint_turn", "attempt"], payload: Mapping[str, Any]) -> None:+ async def _audit(self, kind: Literal["fork_turn", "attempt"], payload: Mapping[str, Any]) -> None:"""A non-context audit row; never context, so losing it never fails the run."""try:await self._scope.call(diff --git a/core/agent_core/harness/context.py b/core/agent_core/harness/context.pyindex 97ec56fe2..4db52b986 100644--- a/core/agent_core/harness/context.py+++ b/core/agent_core/harness/context.py@@ -78,11 +78,6 @@ CLEARED_PLACEHOLDER = ()CHECKPOINT_MAX_TOKENS = 16_000-CHECKPOINT_TOOL_ROUNDS = 5-#: A checkpoint turn's tool runs only while the window leaves this much room (context.md section 6).-CHECKPOINT_TOOL_FLOOR = 4_000-#: Room a tool result leaves for the checkpoint request's growth.-CHECKPOINT_TOOL_SLACK = 1_000CHECKPOINT_TRUNCATED = ("[Output truncated to fit this checkpoint turn: showing about {shown} of {total} tokens. ""Read a smaller range if you need more.]"diff --git a/core/agent_core/harness/store.py b/core/agent_core/harness/store.pyindex 5cfec7071..0d82a816e 100644--- a/core/agent_core/harness/store.py+++ b/core/agent_core/harness/store.py@@ -72,7 +72,7 @@ class TranscriptStore(Protocol):...async def append_audit(- self, session_id: str, kind: Literal["checkpoint_turn", "attempt"], payload: Mapping[str, Any]+ self, session_id: str, kind: Literal["fork_turn", "attempt"], payload: Mapping[str, Any]) -> str:- """An audit row outside the context (C-9 ``CheckpointTurn`` or ``ModelAttempt``); its id."""+ """An audit row outside the context (C-10 ``ForkTurn`` or C-9 ``ModelAttempt``); its id."""...diff --git a/core/agent_core/tools/base.py b/core/agent_core/tools/base.pyindex 6054603af..f10a8aa65 100644--- a/core/agent_core/tools/base.py+++ b/core/agent_core/tools/base.py@@ -46,7 +46,7 @@ class CallInstance:class ToolContext:session_id: strtool_call_id: str- #: The call's instance when a committed response made it; ``None`` for a checkpoint turn's call (C-9),+ #: The call's instance when a committed response made it; ``None`` for a side turn's call (C-10 F4),#: which starts no job.call: Optional[CallInstance]cwd: strdiff --git a/docs/plans/agent-core-contracts/fork.md b/docs/plans/agent-core-contracts/fork.mdindex 2278ef1da..49ae6bd18 100644--- a/docs/plans/agent-core-contracts/fork.md+++ b/docs/plans/agent-core-contracts/fork.md@@ -47,7 +47,7 @@ because identity is what an effect beyond the turn needs.**Why identity separates them.** A command is a job keyed by its call instance: the committed response that made thecall, in a Session (`core/agent_core/tools/base.py:28-42`). Watches, T2 recovery, approvals, and the user's access-all hang off a Session. A side turn commits no response, so its calls have no instance (`agent/loop.py:1667`), and+all hang off a Session. A side turn commits no response, so its calls have no instance (`Agent._side_tool`), and`bash` refuses to start (`tools/bash.py:213-215`). So anything that may act beyond its own turn needs a Session, andanything that only thinks does not. Borrowing the caller's identity is also what keeps a side turn's prefixcache-warm (§3).@@ -274,7 +274,7 @@ Any tool the policy does not name is denied with the policy's text and never run- An allowed tool must finish within the call and need no call instance. That rules out `bash`, which starts jobs,and anything that asks the user, since a side turn has nowhere to ask.- Policies are code. The contract that consumes a policy owns it, and this file lists it.-- v1 has one policy, `dreaming` (C-9 §6, `agent/checkpoint.py:29-35`): `read` is allowed, and `write` and `edit` go+- v1 has one policy, `dreaming` (C-9 §6, `DREAMING` in `agent/fork.py`): `read` is allowed, and `write` and `edit` goto scratch.- A tool missing from the caller's request cannot be granted, because the request is the caller's.@@ -540,8 +540,8 @@ already provide, plus work outside fork.middle range while keeping the head needs a range checkpoint row in C-5 and C-9 projection, not a change to fork.- **Memory.**- How it uses fork: a side turn with a `memory` policy, under which memory tools are allowed and the rest denied- (C-9 already reserves that row, `checkpoint.py:34`). It sends a consolidation prompt and uses a fold that commits- nothing: its effect is the memory tools' writes.+ (`DREAMING`'s table already reserves that row, `agent/fork.py`). It sends a consolidation prompt and uses a+ fold that commits nothing: its effect is the memory tools' writes.- Those writes must be idempotent upserts, because a crash loses the turn.- Needs: the memory tools, and side turns while the Session is idle (§7).diff --git a/modules/agents/vibey/store.py b/modules/agents/vibey/store.pyindex 8d7340988..c4bcfd47a 100644--- a/modules/agents/vibey/store.py+++ b/modules/agents/vibey/store.py@@ -153,7 +153,7 @@ class AdapterTranscriptStore:return committedasync def append_audit(- self, session_id: str, kind: Literal["attempt", "checkpoint_turn"], payload: Mapping[str, Any]+ self, session_id: str, kind: Literal["attempt", "fork_turn"], payload: Mapping[str, Any]) -> str:return await self._store.append_audit(session_id, kind, payload, agent_name=self._agents.get(session_id))diff --git a/storage/agent_transcript.py b/storage/agent_transcript.pyindex 16eb45973..1f1029054 100644--- a/storage/agent_transcript.py+++ b/storage/agent_transcript.py@@ -93,8 +93,8 @@ FINAL_TYPES = ("result", "error")RESPONSE_TYPES = ("assistant", *FINAL_TYPES)CONTEXT_VISIBILITY = "context"AUDIT_VISIBILITY = "audit"-AuditKind = Literal["attempt", "checkpoint_turn"]-_AUDIT_EVENT_TYPE: dict[str, str] = {"attempt": "model_attempt", "checkpoint_turn": "context_checkpoint_turn"}+AuditKind = Literal["attempt", "fork_turn"]+_AUDIT_EVENT_TYPE: dict[str, str] = {"attempt": "model_attempt", "fork_turn": "fork_turn"}# Only Vibey writes context rows; the Session's routed backend may change mid-Turn.CONTEXT_WRITER = "vibey"PAYLOAD_VERSION = 1@@ -304,7 +304,7 @@ class SQLiteTranscriptStore:async def append_audit(self, session_id: str, kind: AuditKind, payload: Mapping[str, Any], *, agent_name: Optional[str] = None) -> str:- """A non-context audit row (C-9 ``ModelAttempt`` or ``CheckpointTurn``); its id. Never loaded as context."""+ """A non-context audit row (C-9 ``ModelAttempt`` or C-10 ``ForkTurn``); its id. Never loaded as context."""if kind not in _AUDIT_EVENT_TYPE:raise ValueError(f"not an audit kind: {kind!r}")data = _canonical(dict(payload), f"{kind} audit")diff --git a/tests/agent_core/agent/test_compaction.py b/tests/agent_core/agent/test_compaction.pyindex a66df38d8..44132651c 100644--- a/tests/agent_core/agent/test_compaction.py+++ b/tests/agent_core/agent/test_compaction.py@@ -18,7 +18,7 @@ from dataclasses import replaceimport pytest-from core.agent_core.agent.checkpoint import BUDGET_USED, DENIED, CheckpointPolicy, Decision+from core.agent_core.agent.fork import DREAMING, Decision, PolicyGatefrom core.agent_core.agent.scratch import ScratchRootfrom core.agent_core.agent.events import (AgentError,@@ -73,6 +73,8 @@ from tests.agent_core.fakes import (input_row,)+DENIED, BUDGET_USED = DREAMING.denied, DREAMING.budget_used+#: The engine tests' route: a 64,000-token window read through a 32,000-token input limit, so M = 8,000 and#: T = 19,904 (section 1), the numbers every test here is sized against.SELECTION = ModelSelection(ENDPOINT, replace(FAKE_SELECTION.capabilities, context_window=64_000, input_limit=32_000))@@ -256,7 +258,7 @@ async def test_a_threshold_checkpoint_forks_the_exact_prefix_and_leaves_checkpoiassert len([event for event in events if isinstance(event, MessageCommitted)]) == 5assert events[-1] == RunEnded("input", events[-1].seq, "completed")(session_id, _, audit), = agent.store.audits- assert (audit["outcome"], audit["compaction_event_id"]) == ("completed", compaction.row_id)+ assert (audit["outcome"], audit["folded_event_id"]) == ("completed", compaction.row_id)assert [message["role"] for message in audit["messages"]] == ["assistant"]# Append-only: every row before the checkpoint is exactly what was committed before it.assert all(row.kind != "compaction" for row in before) and rows.index(compaction) == len(before)@@ -393,8 +395,8 @@ async def test_a_target_the_platform_cannot_compare_with_the_scratch_dir_is_denidef other_drive(paths):raise ValueError("Paths don't have the same drive")- policy = CheckpointPolicy(cwd=str(tmp_path), scratch_dir=str(tmp_path / "scratch"))- monkeypatch.setattr("core.agent_core.agent.checkpoint.os.path.commonpath", other_drive)+ policy = PolicyGate(DREAMING, cwd=str(tmp_path), scratch_dir=str(tmp_path / "scratch"))+ monkeypatch.setattr("core.agent_core.agent.fork.os.path.commonpath", other_drive)write = ToolCallBlock("w", "write", {"path": str(tmp_path / "elsewhere"), "content": "no"})assert policy.decide(write) == Decision(denial=DENIED)@@ -1415,7 +1417,7 @@ async def _drain(stream):@pytest.mark.parametrize("swap", ["root", "target"])async def test_a_scratch_write_never_lands_outside_after_a_swap_between_policy_and_execution(tmp_path, monkeypatch, swap):scratch, outside = flat_scratch(tmp_path)- decide = CheckpointPolicy.decide+ decide = PolicyGate.decidedef decide_then_swap(policy, call):decision = decide(policy, call)@@ -1427,7 +1429,7 @@ async def test_a_scratch_write_never_lands_outside_after_a_swap_between_policy_a(scratch / "plan.md").symlink_to(outside / "plan.md")return decision- monkeypatch.setattr(CheckpointPolicy, "decide", decide_then_swap)+ monkeypatch.setattr(PolicyGate, "decide", decide_then_swap)calls = [ToolCallBlock("w", "write", {"path": "state/scratch/session/plan.md", "content": "plan"})]results = await _scratch_checkpoint(tmp_path, scratch, calls, [WriteTool()])assert not os.listdir(outside) # nothing outside: no content, no temp file, no directorydiff --git a/tests/agent_core/agent/test_fork.py b/tests/agent_core/agent/test_fork.pyindex aa95654ab..39b903d6d 100644--- a/tests/agent_core/agent/test_fork.py+++ b/tests/agent_core/agent/test_fork.py@@ -1,13 +1,37 @@-"""C-10 fork point as pure functions (``agent-core-contracts/fork.md`` section 2)."""+"""C-10 fork: the fork point as pure functions (``agent-core-contracts/fork.md`` section 2), and the side turn+(sections 7 and 15)."""++import json+from dataclasses import replace+from pathlib import Pathimport pytest+from jsonschema import Draft7Validator+from referencing import Registry, Resource+from core.agent_core.agent.fork import DREAMING, CheckpointDetail, Folded, SideTurn+from core.agent_core.agent.models import ModelSelection+from core.agent_core.ai.provider import Donefrom core.agent_core.harness.fork import ForkPoint, ForkPointError, fork_point, fork_prefix, latest_cut, settled-from core.agent_core.harness.projection import project+from core.agent_core.harness.projection import context_view, projectfrom core.agent_core.harness.store import ContextEntryfrom core.agent_core.messages import ToolCallBlock, ToolResultMessage, text+from tests.agent_core.agent.test_compaction import (+ CHECKPOINT,+ ROOMY,+ SELECTION,+ Model,+ after_checkpoint,+ call,+ cross,+ history,+ make_agent,+ reader,+ run,+ tokens,+)from tests.agent_core.agent.test_projection import _checkpoint_payload-from tests.agent_core.fakes import assistant, user+from tests.agent_core.fakes import ENDPOINT, FakeTool, InMemoryTranscriptStore, assistant, userclass Rows:@@ -116,3 +140,95 @@ def test_the_prefix_is_the_view_at_the_cut_and_a_later_checkpoint_does_not_exist"second answer",]assert fork_prefix(rows.rows, ForkPoint(4, units=2)) == project(rows.rows, fork_point=2).messages+++# --- the side turn (fork.md sections 7 and 15) ------------------------------------------------------------------+++def _side_turn(**fields) -> SideTurn:+ async def fold(reply):+ return Folded(None)++ defaults = dict(+ purpose="checkpoint",+ detail=CheckpointDetail("threshold", "normal"),+ units=None,+ prompt=user("checkpoint"),+ policy=DREAMING,+ max_tokens=lambda capabilities: 1_000,+ fold=fold,+ )+ return SideTurn(**{**defaults, **fields})+++def test_a_side_turn_is_built_only_with_its_purposes_detail():+ # Every fork_turn audit records its detail, so a side turn cannot be built without the one its purpose needs.+ assert _side_turn().detail == CheckpointDetail("threshold", "normal")+ with pytest.raises(TypeError):+ _side_turn(detail=None)+ with pytest.raises(TypeError):+ _side_turn(detail={"reason": "threshold", "mode": "normal"})+ with pytest.raises(ValueError):+ _side_turn(purpose="memory")+ with pytest.raises(TypeError):+ SideTurn("checkpoint", units=None, prompt=user("p"), policy=DREAMING, max_tokens=len, fold=None)+++def _fork_turn_validator() -> Draft7Validator:+ contracts = Path(__file__).resolve().parents[3] / "docs" / "plans" / "agent-core-contracts"+ resources = {}+ for path in contracts.glob("*.schema.json"):+ value = json.loads(path.read_text())+ resources[value["$id"]] = Resource.from_contents(value)+ return Draft7Validator(+ {"$ref": "agent-core/transcript-rows.schema.json#/definitions/ForkTurn"},+ registry=Registry().with_resources(resources.items()),+ )+++async def test_every_side_turn_leaves_one_fork_turn_audit_with_its_purpose_policy_point_and_detail():+ # F7 and section 15, on C-9's overflow-then-roll case: a normal checkpoint over the whole view reads once, then+ # its next request cannot fit a smaller route and fails; a rolling one over a prefix of the view completes.+ small = ModelSelection(ENDPOINT, replace(SELECTION.capabilities, context_window=8_000, input_limit=None))+ store = InMemoryTranscriptStore()+ await run(make_agent(Model(history()), store=store, tools=[reader(tokens(3_000))], selection=ROOMY))+ model = Model([[Done(assistant("after"))]], [call("read", "first", path="f"), [Done(assistant(CHECKPOINT))]])+ agent = make_agent(model, store=store, tools=[reader(tokens(3_000))], selection=(ROOMY, small))+ await cross(agent)++ rows = await store.load("session")+ compaction = next(row for row in rows if row.kind == "compaction")+ before = [row for row in rows if row.context_seq < compaction.context_seq]+ latest = before[-1].context_seq # the caller's latest point when both turns ran: neither wrote context+ normal, rolling = (audit for _, _, audit in store.audits)+ validator = _fork_turn_validator()+ validator.validate(normal)+ validator.validate(rolling)+ assert {key: normal[key] for key in ("purpose", "policy", "point", "detail", "rounds", "outcome")} == {+ "purpose": "checkpoint",+ "policy": "dreaming",+ "point": {"as_of": latest, "units": None},+ "detail": {"reason": "threshold", "mode": "normal"},+ "rounds": 1,+ "outcome": "failed",+ }+ assert normal["folded_event_id"] is None and normal["error"].startswith("overflow: the checkpoint request")+ assert rolling["detail"] == {"reason": "overflow", "mode": "rolling"}+ assert rolling["point"]["as_of"] == latest and 0 < rolling["point"]["units"] < len(context_view(before).units)+ assert (rolling["outcome"], rolling["folded_event_id"], rolling["error"]) == ("completed", compaction.row_id, None)+++async def test_a_side_turn_call_has_no_instance_even_when_its_policy_allows_the_tool(monkeypatch):+ # F4: a side turn starts nothing. Its calls have no committed response, so no call instance, whatever the+ # policy lets run.+ monkeypatch.setattr(+ "core.agent_core.agent.loop.DREAMING", replace(DREAMING, tools={**DREAMING.tools, "bash": "allow"})+ )+ bash = FakeTool("bash")+ model = Model(after_checkpoint(), [call("bash", "side", command="sleep 600"), [Done(assistant(CHECKPOINT))]])+ agent = make_agent(model, tools=[reader(tokens(3_000)), bash], selection=ROOMY)+ await run(agent)+ assert (await cross(agent))[-1].reason == "completed"++ ((arguments, ctx),) = bash.calls+ assert arguments == {"command": "sleep 600"} and ctx.call is Nonediff --git a/tests/agent_core/fakes.py b/tests/agent_core/fakes.pyindex 4e788b14c..2525f5903 100644--- a/tests/agent_core/fakes.py+++ b/tests/agent_core/fakes.py@@ -167,12 +167,12 @@ class InMemoryTranscriptStore:return committedasync def append_audit(self, session_id, kind, payload: Mapping) -> str:- if kind not in ("attempt", "checkpoint_turn"):+ if kind not in ("attempt", "fork_turn"):raise ValueError(f"not an audit kind: {kind!r}")self._next_id += 1row_id = f"audit_{self._next_id}"record = (session_id, row_id, deepcopy(dict(payload)))- (self.audits if kind == "checkpoint_turn" else self.attempts).append(record)+ (self.audits if kind == "fork_turn" else self.attempts).append(record)return row_iddiff --git a/tests/test_agent_transcript.py b/tests/test_agent_transcript.pyindex 53fe95acc..0b6a123ee 100644--- a/tests/test_agent_transcript.py+++ b/tests/test_agent_transcript.py@@ -279,7 +279,7 @@ async def test_rows_outside_the_context_never_load(engine) -> None:assert conn.execute(select(messages.c.context_seq).where(messages.c.id == queued)).scalar() is None[email protected]("kind,event_type", [("attempt", "model_attempt"), ("checkpoint_turn", "context_checkpoint_turn")])[email protected]("kind,event_type", [("attempt", "model_attempt"), ("fork_turn", "fork_turn")])async def test_an_audit_row_is_kept_outside_the_context(engine, kind, event_type) -> None:with engine.begin() as conn:home = _scope(conn, "C-home")diff --git a/tests/test_transcript_store_contract.py b/tests/test_transcript_store_contract.pyindex 7fa8a95b0..f97c6239e 100644--- a/tests/test_transcript_store_contract.py+++ b/tests/test_transcript_store_contract.py@@ -55,7 +55,7 @@ from tests.agent_core.fakes import (NOW = "2026-10-04T00:00:00.000000Z"SESSION = "session"-_AUDIT_KINDS = {"model_attempt": "attempt", "context_checkpoint_turn": "checkpoint_turn"}+_AUDIT_KINDS = {"model_attempt": "attempt", "fork_turn": "fork_turn"}class _Fake:@@ -71,7 +71,7 @@ class _Fake:self.store.fork(Snapshot(source, anchor.context_seq, {}), session_id=child)def audits(self) -> list[tuple[str, dict]]:- return [("checkpoint_turn", payload) for _, _, payload in self.store.audits] + [+ return [("fork_turn", payload) for _, _, payload in self.store.audits] + [("attempt", payload) for _, _, payload in self.store.attempts]@@ -253,12 +253,12 @@ async def test_audit_rows_are_kept_outside_the_context(backend):before = [await _started(backend)]attempt = {"version": 1, "usage": {"input_tokens": 5, "output_tokens": 2}, "error": "rate_limit: busy"}turn = {"version": 1, "reason": "threshold", "mode": "normal", "messages": []}- ids = [await store.append_audit(SESSION, "attempt", attempt), await store.append_audit(SESSION, "checkpoint_turn", turn)]+ ids = [await store.append_audit(SESSION, "attempt", attempt), await store.append_audit(SESSION, "fork_turn", turn)]assert all(isinstance(row_id, str) and row_id for row_id in ids) and len(set(ids)) == 2with pytest.raises(ValueError):await store.append_audit(SESSION, "compaction", {"version": 1})assert list(await store.load(SESSION)) == before- assert sorted(backend.audits(), key=repr) == sorted([("attempt", attempt), ("checkpoint_turn", turn)], key=repr)+ assert sorted(backend.audits(), key=repr) == sorted([("attempt", attempt), ("fork_turn", turn)], key=repr)async def test_consuming_an_input_again_returns_its_entry_and_never_rewrites_it(backend):