Skip to content

armgit / avibe

Public Imported from GitHub
0

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.

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.py
deleted file mode 100644
index 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 None
diff --git a/core/agent_core/agent/fork.py b/core/agent_core/agent/fork.py
new file mode 100644
index 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 = False
diff --git a/core/agent_core/agent/loop.py b/core/agent_core/agent/loop.py
index 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 the
bare-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 time
from collections import deque
from contextlib import asynccontextmanager, suppress
from copy import deepcopy
-from dataclasses import dataclass, replace
+from dataclasses import asdict, dataclass, replace
from typing import Any, AsyncIterator, Awaitable, Callable, Literal, Mapping, Optional, Sequence, TypeVar
-from core.agent_core.agent.checkpoint import BUDGET_USED, DENIED, CheckpointPolicy, Decision
from 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 TrackingJobHost
from core.agent_core.agent.lifecycle import RunAborted as _Aborted, RunScope
from 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 CancelToken
from 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: ModelRequest
message: 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. A
conversation 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 carry
return (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 = True
cut = 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 True
ladder.summary_failed = not outcome.overflow
continue
if 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_ROLLS
continue
ladder.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 True
ladder.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.mode
await 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 prompt
produced: list[Message] = [] # the audit: every attempt's message from the ledger, and the tool results
start = mark = len(self._attempts)
measured: list[Budget] = [] # the budget of the turn's latest request, as sent
rounds = 0
error: Optional[str] = None
overflow = 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 = False
try:
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."
break
except 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)
break
finally:
@@ -1521,25 +1582,17 @@ class Agent:
break
message = terminal.message
self._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))
break
if 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."
break
rounds += 1
sent = 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) * fixed
room = 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 write
raise
except 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 compose
raise
finally:
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 = None
for 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, representation
return 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.py
index 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_000
CHECKPOINT_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.py
index 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.py
index 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: str
tool_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: str
diff --git a/docs/plans/agent-core-contracts/fork.md b/docs/plans/agent-core-contracts/fork.md
index 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 the
call, 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, and
anything that only thinks does not. Borrowing the caller's identity is also what keeps a side turn's prefix
cache-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` go
to 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.py
index 8d7340988..c4bcfd47a 100644
--- a/modules/agents/vibey/store.py
+++ b/modules/agents/vibey/store.py
@@ -153,7 +153,7 @@ class AdapterTranscriptStore:
return committed
async 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.py
index 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.py
index 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 replace
import pytest
-from core.agent_core.agent.checkpoint import BUDGET_USED, DENIED, CheckpointPolicy, Decision
+from core.agent_core.agent.fork import DREAMING, Decision, PolicyGate
from core.agent_core.agent.scratch import ScratchRoot
from 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_checkpoi
assert len([event for event in events if isinstance(event, MessageCommitted)]) == 5
assert 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_deni
def 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.decide
def 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 directory
diff --git a/tests/agent_core/agent/test_fork.py b/tests/agent_core/agent/test_fork.py
index 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 Path
import 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 Done
from 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, project
from core.agent_core.harness.store import ContextEntry
from 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, user
class 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 None
diff --git a/tests/agent_core/fakes.py b/tests/agent_core/fakes.py
index 4e788b14c..2525f5903 100644
--- a/tests/agent_core/fakes.py
+++ b/tests/agent_core/fakes.py
@@ -167,12 +167,12 @@ class InMemoryTranscriptStore:
return committed
async 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 += 1
row_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_id
diff --git a/tests/test_agent_transcript.py b/tests/test_agent_transcript.py
index 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.py
index 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)) == 2
with 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):