jharness-kernel 0.2.2__tar.gz → 0.3.0__tar.gz

{jharness_kernel-0.2.2 → jharness_kernel-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jharness-kernel
-Version: 0.2.2
+Version: 0.3.0
 Summary: Durable model and tool execution kernel for JHarness
 Project-URL: Documentation, https://github.com/Ezio2000/jharness/tree/main/docs
 Project-URL: Repository, https://github.com/Ezio2000/jharness.git
@@ -25,12 +25,15 @@ The dependency-free JHarness runtime kernel, including lifecycle values, executi
 checkpoints, diagnostics, extension ports, and portable wire codecs.
 
 ```bash
-pip install jharness-kernel
+uv add jharness-kernel
 ```
 
 ```python
 from jharness.kernel import Message, Runtime
 ```
 
+Kernel owns persistent `RunHistory`, incremental `DurableCommit`, cursor-based pending
+tool calls, and complete-history model requests. It has no runtime dependency.
+
 The source, contracts, and release process are maintained in the
 [JHarness repository](https://github.com/Ezio2000/jharness).

{jharness_kernel-0.2.2 → jharness_kernel-0.3.0}/README.md

@@ -4,12 +4,15 @@ The dependency-free JHarness runtime kernel, including lifecycle values, executi
 checkpoints, diagnostics, extension ports, and portable wire codecs.
 
 ```bash
-pip install jharness-kernel
+uv add jharness-kernel
 ```
 
 ```python
 from jharness.kernel import Message, Runtime
 ```
 
+Kernel owns persistent `RunHistory`, incremental `DurableCommit`, cursor-based pending
+tool calls, and complete-history model requests. It has no runtime dependency.
+
 The source, contracts, and release process are maintained in the
 [JHarness repository](https://github.com/Ezio2000/jharness).

{jharness_kernel-0.2.2 → jharness_kernel-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "jharness-kernel"
-version = "0.2.2"
+version = "0.3.0"
 description = "Durable model and tool execution kernel for JHarness"
 readme = "README.md"
 requires-python = ">=3.11"

{jharness_kernel-0.2.2 → jharness_kernel-0.3.0}/src/jharness/kernel/__init__.py

@@ -39,7 +39,7 @@ from jharness.kernel.errors import (
     ToolError,
 )
 from jharness.kernel.events import Event, EventKind
-from jharness.kernel.history import HistoryReducer, HistoryRewrite
+from jharness.kernel.history import HistoryReducer, HistoryRewrite, RunHistory
 from jharness.kernel.invocation import Invocation
 from jharness.kernel.json_values import (
     MAX_JSON_NESTING_DEPTH,
@@ -66,7 +66,17 @@ from jharness.kernel.models import (
     ResponseFormat,
     ToolChoice,
 )
-from jharness.kernel.repository import EphemeralRepository, RunRepository
+from jharness.kernel.repository import (
+    DurableCommit,
+    EphemeralRepository,
+    HistoryAppend,
+    HistoryChange,
+    HistoryReplace,
+    HistoryUnchanged,
+    InitialHistory,
+    RunRepository,
+    checkpoint_digest,
+)
 from jharness.kernel.runtime import Runtime
 from jharness.kernel.snapshot import RunSnapshot
 from jharness.kernel.state import (
@@ -74,6 +84,7 @@ from jharness.kernel.state import (
     Completed,
     Failed,
     Limited,
+    PendingToolCalls,
     Planning,
     RunMetrics,
     RunState,
@@ -121,6 +132,7 @@ __all__ = [
     "ControlFact",
     "ConversationInsertFact",
     "DeltaSink",
+    "DurableCommit",
     "EphemeralRepository",
     "ErrorInfo",
     "Event",
@@ -128,9 +140,14 @@ __all__ = [
     "Fact",
     "Failed",
     "FailedControl",
+    "HistoryAppend",
+    "HistoryChange",
     "HistoryReducer",
+    "HistoryReplace",
     "HistoryRewrite",
     "HistoryRewriteFact",
+    "HistoryUnchanged",
+    "InitialHistory",
     "Invocation",
     "JsonScalar",
     "JsonValue",
@@ -154,6 +171,7 @@ __all__ = [
     "ModelTurnResult",
     "ModelUsage",
     "ModelUsageDelta",
+    "PendingToolCalls",
     "Planning",
     "ProtocolError",
     "RepositoryError",
@@ -162,6 +180,7 @@ __all__ = [
     "ResumedFact",
     "RevisionConflict",
     "RunContext",
+    "RunHistory",
     "RunLimits",
     "RunMetrics",
     "RunRepository",
@@ -198,6 +217,7 @@ __all__ = [
     "ToolWaiting",
     "ToolsPending",
     "WaitingResult",
+    "checkpoint_digest",
     "freeze_json_value",
     "thaw_json_value",
     "tool_message",

{jharness_kernel-0.2.2 → jharness_kernel-0.3.0}/src/jharness/kernel/_digest.py

@@ -107,6 +107,39 @@ def append_history_digest(previous: bytes, message: Message) -> bytes:
     return writer.finish()
 
 
+def empty_tool_call_suffix_digest() -> bytes:
+    return DigestWriter("jharness.kernel.tool_calls.suffix.empty.v1").finish()
+
+
+def prepend_tool_call_digest(suffix: bytes, call: ToolCall) -> bytes:
+    writer = DigestWriter("jharness.kernel.tool_calls.suffix.prepend.v1")
+    writer.field("call")
+    write_tool_call(writer, call)
+    writer.field("suffix")
+    writer.bytes(suffix)
+    return writer.finish()
+
+
+def empty_call_id_suffix_digest() -> bytes:
+    return DigestWriter("jharness.kernel.tool_call_ids.suffix.empty.v1").finish()
+
+
+def prepend_call_id_digest(suffix: bytes, call_id: str) -> bytes:
+    writer = DigestWriter("jharness.kernel.tool_call_ids.suffix.prepend.v1")
+    writer.field("call_id")
+    writer.string(call_id)
+    writer.field("suffix")
+    writer.bytes(suffix)
+    return writer.finish()
+
+
+def compose_call_id_digest(prefix: Sequence[str], suffix: bytes) -> bytes:
+    digest = suffix
+    for call_id in reversed(prefix):
+        digest = prepend_call_id_digest(digest, call_id)
+    return digest
+
+
 def write_message(writer: DigestWriter, value: Message) -> None:
     writer.field("role")
     writer.string(value.role)
@@ -173,10 +206,10 @@ def _write_artifact(writer: DigestWriter, value: ArtifactRef) -> None:
 def write_tool_calls(writer: DigestWriter, values: tuple[ToolCall, ...]) -> None:
     writer.sequence(len(values))
     for value in values:
-        _write_tool_call(writer, value)
+        write_tool_call(writer, value)
 
 
-def _write_tool_call(writer: DigestWriter, value: ToolCall) -> None:
+def write_tool_call(writer: DigestWriter, value: ToolCall) -> None:
     writer.field("tool_call")
     writer.field("id")
     writer.string(value.id)

{jharness_kernel-0.2.2 → jharness_kernel-0.3.0}/src/jharness/kernel/_engine/change.py

@@ -16,6 +16,7 @@ from jharness.kernel.checkpoint import (
     SuspendedControl,
 )
 from jharness.kernel.control import Insert
+from jharness.kernel.history import RunHistory
 from jharness.kernel.limits import LimitReason
 from jharness.kernel.messages import ErrorInfo, Message
 from jharness.kernel.models import ModelUsage
@@ -39,7 +40,7 @@ class Change:
     fact: Fact
     state: RunState
     append: tuple[Message, ...] = ()
-    replace: tuple[Message, ...] | None = None
+    replace: RunHistory | None = None
     planning_steps: int = 0
     tool_calls: int = 0
     usage: ModelUsage | None = None
@@ -50,13 +51,11 @@ class Change:
         if not isinstance(cast(object, self.state), RunState):
             raise TypeError("change state must be a RunState")
         append = expect_instance_tuple(self.append, Message, "change append")
-        replace = (
-            None
-            if self.replace is None
-            else expect_instance_tuple(self.replace, Message, "change replacement")
-        )
-        if replace is not None and (not replace or append):
-            raise ValueError("change replacement must be non-empty and exclusive with append")
+        replace = self.replace
+        if replace is not None:
+            expect_instance(replace, RunHistory, "change replacement")
+        if replace is not None and append:
+            raise ValueError("change replacement must be exclusive with append")
         object.__setattr__(self, "append", append)
         object.__setattr__(self, "replace", replace)
 

{jharness_kernel-0.2.2 → jharness_kernel-0.3.0}/src/jharness/kernel/_engine/commit.py

@@ -9,7 +9,15 @@ from jharness.kernel._engine.change import Change, reduce
 from jharness.kernel._validation import expect_instance
 from jharness.kernel.checkpoint import Checkpoint
 from jharness.kernel.errors import CommitError
-from jharness.kernel.repository import RunRepository
+from jharness.kernel.repository import (
+    DurableCommit,
+    HistoryAppend,
+    HistoryChange,
+    HistoryReplace,
+    HistoryUnchanged,
+    InitialHistory,
+    RunRepository,
+)
 
 
 class WorkCommitDeadlineReached(Exception):
@@ -35,7 +43,11 @@ class Committer:
         if checkpoint.snapshot.revision != 0:
             raise ValueError("start checkpoint revision must be 0")
         return await self._persist(
-            checkpoint,
+            DurableCommit(
+                checkpoint,
+                None,
+                InitialHistory(checkpoint.snapshot.history),
+            ),
             previous=None,
             work_timeout_seconds=work_timeout_seconds,
         )
@@ -50,14 +62,18 @@ class Committer:
         previous = expect_instance(previous, Checkpoint, "previous checkpoint")
         checkpoint = reduce(previous.snapshot, change, checkpoint_id=str(uuid4()))
         return await self._persist(
-            checkpoint,
+            DurableCommit(
+                checkpoint,
+                previous.id,
+                _history_change(previous, change, checkpoint),
+            ),
             previous=previous,
             work_timeout_seconds=work_timeout_seconds,
         )
 
     async def _persist(
         self,
-        checkpoint: Checkpoint,
+        commit: DurableCommit,
         *,
         previous: Checkpoint | None,
         work_timeout_seconds: float | None = None,
@@ -72,11 +88,25 @@ class Committer:
             raise WorkCommitDeadlineReached
         try:
             async with asyncio.timeout(timeout):
-                await self._repository.commit(checkpoint)
+                await self._repository.commit(commit)
         except TimeoutError as exc:
             if work_limited:
                 raise WorkCommitDeadlineReached from exc
             raise CommitError("repository commit timed out", last_checkpoint=previous) from exc
         except Exception as exc:
             raise CommitError(str(exc) or exc.__class__.__name__, last_checkpoint=previous) from exc
-        return checkpoint
+        return commit.checkpoint
+
+
+def _history_change(
+    previous: Checkpoint,
+    change: Change,
+    checkpoint: Checkpoint,
+) -> HistoryChange:
+    base_count = len(previous.snapshot.history)
+    base_digest = previous.snapshot._history_digest()  # pyright: ignore[reportPrivateUsage]
+    if change.replace is not None:
+        return HistoryReplace(base_count, base_digest, checkpoint.snapshot.history)
+    if change.append:
+        return HistoryAppend(base_count, base_digest, change.append)
+    return HistoryUnchanged(base_count, base_digest)

{jharness_kernel-0.2.2 → jharness_kernel-0.3.0}/src/jharness/kernel/_engine/planning.py

@@ -35,7 +35,13 @@ from jharness.kernel.models import (
     ToolChoice,
 )
 from jharness.kernel.snapshot import RunSnapshot
-from jharness.kernel.state import Completed, Limited, Planning, ToolsPending
+from jharness.kernel.state import (
+    Completed,
+    Limited,
+    PendingToolCalls,
+    Planning,
+    ToolsPending,
+)
 from jharness.kernel.tools import ToolCatalog
 
 _TEXT_LIKE = frozenset({"text", "reasoning", "thinking", "redacted_thinking", "refusal"})
@@ -85,7 +91,7 @@ class PlanningStep:
         self, snapshot: RunSnapshot, *, deadline: Deadline, inbox: ControlInbox
     ) -> Change:
         request = ModelRequest(
-            snapshot.history,
+            tuple(snapshot.history),
             self._catalog.specs(),
             self._options,
             self._tool_choice,
@@ -155,7 +161,7 @@ class PlanningStep:
         if over_tokens:
             state = Limited(LimitReason.MAX_TOTAL_TOKENS)
         elif response.tool_calls:
-            state = ToolsPending(response.tool_calls)
+            state = ToolsPending(PendingToolCalls(response.tool_calls))
         else:
             state = Completed(response.parts)
         return Change(

{jharness_kernel-0.2.2 → jharness_kernel-0.3.0}/src/jharness/kernel/_engine/tooling.py

@@ -4,12 +4,13 @@ from __future__ import annotations
 
 import asyncio
 from collections import deque
-from collections.abc import Awaitable, Callable, Mapping
+from collections.abc import Awaitable, Callable, Mapping, Sequence
 from contextlib import suppress
 from dataclasses import dataclass
 from time import time
 from typing import Any, Protocol, TypeAlias, cast
 
+from jharness.kernel._digest import empty_call_id_suffix_digest
 from jharness.kernel._engine.change import Change, failed, limited, suspend
 from jharness.kernel._engine.deadline import Deadline, WorkDeadlineReached
 from jharness.kernel.approval import (
@@ -27,7 +28,7 @@ from jharness.kernel.events import EventKind
 from jharness.kernel.limits import LimitReason, RunLimits
 from jharness.kernel.messages import ToolCall
 from jharness.kernel.snapshot import RunSnapshot
-from jharness.kernel.state import Planning, Suspended, Suspension, ToolsPending
+from jharness.kernel.state import PendingToolCalls, Planning, Suspended, Suspension, ToolsPending
 from jharness.kernel.tools import (
     BatchPolicy,
     SettledResult,
@@ -89,7 +90,12 @@ class ToolStep:
         if capacity <= 0:
             return ToolStepOutcome(limited(LimitReason.MAX_TOOL_CALLS))
         try:
-            batch = self._select(pending.pending[:capacity])
+            selectable = pending.pending.limit(min(capacity, self._limits.max_tool_batch_size))
+            batch = self._select(selectable)
+            await self._emit(
+                EventKind.TOOL_BATCH_SELECTED,
+                selection_data(pending.pending, batch),
+            )
             prepared = self._bind(batch)
             approved = await self._approve(prepared, batch, deadline)
         except WorkDeadlineReached:
@@ -118,13 +124,15 @@ class ToolStep:
         deferred.extend(inserts)
         return _outcome(pending, batch, results, boundary_pause, deferred)
 
-    def _select(self, selectable: tuple[ToolCall, ...]) -> ToolBatch:
+    def _select(self, selectable: Sequence[ToolCall]) -> ToolBatch:
         batch = self._policy.select(selectable, self._catalog, self._limits)
         if not isinstance(cast(object, batch), ToolBatch):
             raise ToolError("batch policy returned an invalid batch")
         if len(batch.calls) > self._limits.max_tool_batch_size:
             raise ToolError("batch exceeds max_tool_batch_size")
-        if batch.calls != selectable[: len(batch.calls)]:
+        if len(batch.calls) > len(selectable) or any(
+            call != selectable[index] for index, call in enumerate(batch.calls)
+        ):
             raise ToolError("batch policy must select an exact pending prefix")
         if batch.parallel and any(
             (spec := self._catalog.spec(call.name)) is None or not spec.parallel_safe
@@ -481,8 +489,8 @@ def _outcome(
     pause: Pause | None,
     deferred: list[Insert],
 ) -> ToolStepOutcome:
-    remaining = pending.pending[len(batch.calls) :]
-    next_active = ToolsPending(remaining) if remaining else Planning()
+    remaining = pending.pending.advance(len(batch.calls))
+    next_active = ToolsPending(remaining) if remaining is not None else Planning()
     waiting = next((result for result in results if isinstance(result, WaitingResult)), None)
     suspension = (
         waiting.suspension if waiting is not None else (pause.suspension if pause else None)
@@ -516,6 +524,19 @@ def suspension_view(suspension: Suspension) -> SuspensionView:
     )
 
 
+def selection_data(pending: PendingToolCalls, batch: ToolBatch) -> Mapping[str, Any]:
+    remaining = pending.advance(len(batch.calls))
+    return {
+        "batch_id": batch.id,
+        "call_ids": [call.id for call in batch.calls],
+        "parallel": batch.parallel,
+        "remaining_count": 0 if remaining is None else remaining.pending_count,
+        "remaining_call_id_digest": (
+            empty_call_id_suffix_digest() if remaining is None else remaining.call_id_digest
+        ).hex(),
+    }
+
+
 async def _await_deadline(awaitable: Awaitable[Any], deadline: Deadline) -> Any:
     remaining = deadline.remaining()
     if remaining is not None and remaining <= 0:

{jharness_kernel-0.2.2 → jharness_kernel-0.3.0}/src/jharness/kernel/_engine/verification.py

@@ -5,6 +5,10 @@ from __future__ import annotations
 from collections.abc import Mapping, Sequence
 from typing import Any, cast
 
+from jharness.kernel._digest import (
+    compose_call_id_digest,
+    empty_call_id_suffix_digest,
+)
 from jharness.kernel.checkpoint import (
     ControlFact,
     ConversationInsertFact,
@@ -118,7 +122,11 @@ def state_view(state: object) -> dict[str, Any]:
     if isinstance(state, Planning):
         return {"kind": "planning"}
     if isinstance(state, ToolsPending):
-        return {"kind": "tools_pending", "call_ids": [call.id for call in state.pending]}
+        return {
+            "kind": "tools_pending",
+            "pending_count": state.pending.pending_count,
+            "call_id_digest": state.pending.call_id_digest.hex(),
+        }
     if isinstance(state, Suspended):
         suspension = state.suspension
         return {
@@ -147,14 +155,18 @@ def verify_change(
 ) -> None:
     """Verify one compact durable transition without replaying effects."""
 
-    expected = _advance_view(before, fact)
+    expected = _advance_view(before, fact, after)
     if expected["revision"] != after.get("revision"):
         raise ValueError("revision_gap")
     if expected != dict(after):
         raise ValueError("change_mismatch")
 
 
-def _advance_view(before: Mapping[str, Any] | None, fact: Mapping[str, Any]) -> dict[str, Any]:
+def _advance_view(
+    before: Mapping[str, Any] | None,
+    fact: Mapping[str, Any],
+    after: Mapping[str, Any],
+) -> dict[str, Any]:
     kind = fact["kind"]
     data = cast(Mapping[str, Any], fact["data"])
     if kind == "started":
@@ -167,16 +179,18 @@ def _advance_view(before: Mapping[str, Any] | None, fact: Mapping[str, Any]) ->
     handlers = {
         "resumed": _resumed,
         "model_turn": _model_turn,
-        "tool_batch": _tool_batch,
         "conversation_insert": _conversation_insert,
         "history_rewrite": _history_rewrite,
         "control": _control,
     }
-    try:
-        handler = handlers[cast(str, kind)]
-    except KeyError as exc:
-        raise ValueError("unsupported_fact") from exc
-    handler(base, before, data)
+    if kind == "tool_batch":
+        _tool_batch(base, before, data, after)
+    else:
+        try:
+            handler = handlers[cast(str, kind)]
+        except KeyError as exc:
+            raise ValueError("unsupported_fact") from exc
+        handler(base, before, data)
     return base
 
 
@@ -231,27 +245,62 @@ def _model_turn(result: dict[str, Any], before: Mapping[str, Any], data: Mapping
     if outcome == "completed":
         result["state"] = {"kind": "completed", "part_count": data["part_count"]}
     elif outcome == "tools_pending":
-        result["state"] = {"kind": "tools_pending", "call_ids": data["tool_call_ids"]}
+        call_ids = cast(Sequence[str], data["tool_call_ids"])
+        result["state"] = {
+            "kind": "tools_pending",
+            "pending_count": len(call_ids),
+            "call_id_digest": compose_call_id_digest(
+                call_ids,
+                empty_call_id_suffix_digest(),
+            ).hex(),
+        }
     else:
         result["state"] = {"kind": "limited", "reason": data["limit_reason"]}
 
 
-def _tool_batch(result: dict[str, Any], before: Mapping[str, Any], data: Mapping[str, Any]) -> None:
+def _tool_batch(
+    result: dict[str, Any],
+    before: Mapping[str, Any],
+    data: Mapping[str, Any],
+    after: Mapping[str, Any],
+) -> None:
     state = cast(Mapping[str, Any], before["state"])
     if state.get("kind") != "tools_pending":
         raise ValueError("tool_batch_requires_pending")
-    pending = list(cast(Sequence[str], state["call_ids"]))
     calls = list(cast(Sequence[str], data["call_ids"]))
-    if pending[: len(calls)] != calls:
+    pending_count = cast(int, state["pending_count"])
+    if len(calls) > pending_count:
         raise ValueError("tool_batch_not_prefix")
     result["history_count"] = cast(int, result["history_count"]) + len(calls)
     metrics = cast(dict[str, Any], result["metrics"])
     metrics["tool_calls"] = cast(int, metrics["tool_calls"]) + len(calls)
-    remaining = pending[len(calls) :]
-    active: dict[str, Any] = (
-        {"kind": "tools_pending", "call_ids": remaining} if remaining else {"kind": "planning"}
-    )
+    remaining = pending_count - len(calls)
     suspension = data["suspension"]
+    after_state = cast(Mapping[str, Any], after["state"])
+    after_active = (
+        cast(Mapping[str, Any], after_state.get("resume_to"))
+        if suspension is not None and after_state.get("kind") == "suspended"
+        else after_state
+    )
+    if remaining:
+        if (
+            after_active.get("kind") != "tools_pending"
+            or after_active.get("pending_count") != remaining
+        ):
+            raise ValueError("tool_batch_pending_count_mismatch")
+        suffix = _view_digest(after_active.get("call_id_digest"))
+        active: dict[str, Any] = {
+            "kind": "tools_pending",
+            "pending_count": remaining,
+            "call_id_digest": suffix.hex(),
+        }
+    else:
+        if after_active.get("kind") != "planning":
+            raise ValueError("tool_batch_pending_count_mismatch")
+        suffix = empty_call_id_suffix_digest()
+        active = {"kind": "planning"}
+    if compose_call_id_digest(calls, suffix) != _view_digest(state.get("call_id_digest")):
+        raise ValueError("tool_batch_not_prefix")
     result["state"] = (
         active
         if suspension is None
@@ -259,6 +308,18 @@ def _tool_batch(result: dict[str, Any], before: Mapping[str, Any], data: Mapping
     )
 
 
+def _view_digest(value: object) -> bytes:
+    if not isinstance(value, str) or len(value) != 64:
+        raise ValueError("invalid_pending_digest")
+    try:
+        digest = bytes.fromhex(value)
+    except ValueError as exc:
+        raise ValueError("invalid_pending_digest") from exc
+    if len(digest) != 32 or digest.hex() != value:
+        raise ValueError("invalid_pending_digest")
+    return digest
+
+
 def _conversation_insert(
     result: dict[str, Any], before: Mapping[str, Any], data: Mapping[str, Any]
 ) -> None: