jharness-kernel 0.1.0__tar.gz

jharness_kernel-0.1.0/.gitignore

@@ -0,0 +1,45 @@
+# OS/editor noise
+.DS_Store
+Thumbs.db
+*.swp
+*.swo
+
+# Local AI assistant/workspace state
+.codex/
+.claude/
+.gemini/
+.aider*
+
+# Pinned specification snapshot generated by scripts/sync_spec.py
+.jharness-spec/
+
+# Python
+__pycache__/
+*.py[cod]
+.python-version
+.venv/
+venv/
+ENV/
+
+# Python tooling caches
+.pytest_cache/
+.ruff_cache/
+.pyright/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Packaging/build artifacts
+dist/
+build/
+*.egg-info/
+
+# Node/TypeScript SDK artifacts
+node_modules/
+coverage/
+.turbo/
+.next/
+*.tsbuildinfo
+
+# Logs
+*.log

jharness_kernel-0.1.0/LICENSE

@@ -0,0 +1,21 @@
++MIT License
+
+Copyright (c) 2026 JHarness contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jharness_kernel-0.1.0/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: jharness-kernel
+Version: 0.1.0
+Summary: JHarness model-neutral immutable runtime kernel
+Project-URL: Documentation, https://github.com/Ezio2000/jharness-python/tree/main/docs
+Project-URL: Homepage, https://github.com/Ezio2000/jharness-python
+Project-URL: Issues, https://github.com/Ezio2000/jharness-python/issues
+Project-URL: Repository, https://github.com/Ezio2000/jharness-python.git
+Author: JHarness contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,model,runtime,tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# jharness-kernel
+
+`jharness-kernel` is the dependency-free, model-neutral runtime distribution. It owns
+immutable run state, `Runtime` and `Invocation`, model and tool protocols,
+control, events, limits, atomic checkpoints, repository ports, and explicit
+wire codecs.
+
+Stable runtime concepts are imported from `jharness.kernel`. Portable codecs and
+diagnostics are opt-in namespaces:
+
+```bash
+uv add jharness-kernel
+```
+
+```python
+from jharness.kernel import Message, Runtime
+from jharness.kernel.diagnostics import build_trace, verify_trace
+from jharness.kernel.wire import decode_checkpoint, encode_checkpoint
+```
+
+See the repository
+[architecture](https://github.com/Ezio2000/jharness/blob/v0.1.0/docs/architecture.md),
+[state machine](https://github.com/Ezio2000/jharness/blob/v0.1.0/docs/state-machine.md), and
+[Python package boundaries](https://github.com/Ezio2000/jharness-python/blob/main/docs/python-package-boundaries.md).

jharness_kernel-0.1.0/README.md

@@ -0,0 +1,24 @@
+# jharness-kernel
+
+`jharness-kernel` is the dependency-free, model-neutral runtime distribution. It owns
+immutable run state, `Runtime` and `Invocation`, model and tool protocols,
+control, events, limits, atomic checkpoints, repository ports, and explicit
+wire codecs.
+
+Stable runtime concepts are imported from `jharness.kernel`. Portable codecs and
+diagnostics are opt-in namespaces:
+
+```bash
+uv add jharness-kernel
+```
+
+```python
+from jharness.kernel import Message, Runtime
+from jharness.kernel.diagnostics import build_trace, verify_trace
+from jharness.kernel.wire import decode_checkpoint, encode_checkpoint
+```
+
+See the repository
+[architecture](https://github.com/Ezio2000/jharness/blob/v0.1.0/docs/architecture.md),
+[state machine](https://github.com/Ezio2000/jharness/blob/v0.1.0/docs/state-machine.md), and
+[Python package boundaries](https://github.com/Ezio2000/jharness-python/blob/main/docs/python-package-boundaries.md).

jharness_kernel-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "jharness-kernel"
+version = "0.1.0"
+description = "JHarness model-neutral immutable runtime kernel"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "JHarness contributors" }]
+keywords = ["ai", "agent", "model", "runtime", "tools"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Documentation = "https://github.com/Ezio2000/jharness-python/tree/main/docs"
+Homepage = "https://github.com/Ezio2000/jharness-python"
+Issues = "https://github.com/Ezio2000/jharness-python/issues"
+Repository = "https://github.com/Ezio2000/jharness-python.git"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/jharness"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

jharness_kernel-0.1.0/src/jharness/kernel/__init__.py

@@ -0,0 +1,200 @@
+"""Model-neutral immutable execution kernel."""
+
+from jharness.kernel.approval import (
+    ApprovalAllow,
+    ApprovalDecision,
+    ApprovalDeny,
+    ApprovalPolicy,
+    ApprovalRequest,
+    ApprovalSuspend,
+)
+from jharness.kernel.checkpoint import (
+    Checkpoint,
+    ControlFact,
+    ConversationInsertFact,
+    Fact,
+    FailedControl,
+    HistoryRewriteFact,
+    LimitedControl,
+    ModelTurnFact,
+    ModelTurnResult,
+    ResumedFact,
+    StartedFact,
+    SuspendedControl,
+    SuspensionView,
+    ToolBatchFact,
+    ToolOutcomeKind,
+)
+from jharness.kernel.commands import SuspensionSelector
+from jharness.kernel.context import RunContext
+from jharness.kernel.errors import (
+    CommitError,
+    KernelError,
+    ModelError,
+    ModelErrorInfo,
+    ProtocolError,
+    RepositoryError,
+    RevisionConflict,
+    ToolError,
+)
+from jharness.kernel.events import Event, EventKind
+from jharness.kernel.history import HistoryReducer, HistoryRewrite
+from jharness.kernel.invocation import Invocation
+from jharness.kernel.json_values import (
+    JsonScalar,
+    JsonValue,
+    freeze_json_value,
+    thaw_json_value,
+)
+from jharness.kernel.limits import LimitReason, RunLimits
+from jharness.kernel.messages import ArtifactRef, ContentPart, ErrorInfo, Message, TaskRef, ToolCall
+from jharness.kernel.models import (
+    DeltaSink,
+    Model,
+    ModelCapabilities,
+    ModelContentDelta,
+    ModelDelta,
+    ModelOptions,
+    ModelReasoningDelta,
+    ModelRequest,
+    ModelResponse,
+    ModelToolCallDelta,
+    ModelUsage,
+    ModelUsageDelta,
+    ResponseFormat,
+    ToolChoice,
+)
+from jharness.kernel.repository import EphemeralRepository, RunRepository
+from jharness.kernel.runtime import Runtime
+from jharness.kernel.snapshot import RunSnapshot
+from jharness.kernel.state import (
+    ActiveState,
+    Completed,
+    Failed,
+    Limited,
+    Planning,
+    RunMetrics,
+    RunState,
+    Suspended,
+    Suspension,
+    ToolsPending,
+)
+from jharness.kernel.tools import (
+    BatchPolicy,
+    SettledOutcome,
+    SettledResult,
+    ToolAccepted,
+    ToolBatch,
+    ToolBinding,
+    ToolCatalog,
+    ToolCatalogProvider,
+    ToolContext,
+    ToolExecution,
+    ToolFailure,
+    ToolOutcome,
+    ToolResult,
+    ToolRisk,
+    ToolSpec,
+    ToolSuccess,
+    ToolWaiting,
+    WaitingResult,
+    tool_message,
+)
+
+__all__ = [
+    "ActiveState",
+    "ApprovalAllow",
+    "ApprovalDecision",
+    "ApprovalDeny",
+    "ApprovalPolicy",
+    "ApprovalRequest",
+    "ApprovalSuspend",
+    "ArtifactRef",
+    "BatchPolicy",
+    "Checkpoint",
+    "CommitError",
+    "Completed",
+    "ContentPart",
+    "ControlFact",
+    "ConversationInsertFact",
+    "DeltaSink",
+    "EphemeralRepository",
+    "ErrorInfo",
+    "Event",
+    "EventKind",
+    "Fact",
+    "Failed",
+    "FailedControl",
+    "HistoryReducer",
+    "HistoryRewrite",
+    "HistoryRewriteFact",
+    "Invocation",
+    "JsonScalar",
+    "JsonValue",
+    "KernelError",
+    "LimitReason",
+    "Limited",
+    "LimitedControl",
+    "Message",
+    "Model",
+    "ModelCapabilities",
+    "ModelContentDelta",
+    "ModelDelta",
+    "ModelError",
+    "ModelErrorInfo",
+    "ModelOptions",
+    "ModelReasoningDelta",
+    "ModelRequest",
+    "ModelResponse",
+    "ModelToolCallDelta",
+    "ModelTurnFact",
+    "ModelTurnResult",
+    "ModelUsage",
+    "ModelUsageDelta",
+    "Planning",
+    "ProtocolError",
+    "RepositoryError",
+    "ResponseFormat",
+    "ResumedFact",
+    "RevisionConflict",
+    "RunContext",
+    "RunLimits",
+    "RunMetrics",
+    "RunRepository",
+    "RunSnapshot",
+    "RunState",
+    "Runtime",
+    "SettledOutcome",
+    "SettledResult",
+    "StartedFact",
+    "Suspended",
+    "SuspendedControl",
+    "Suspension",
+    "SuspensionSelector",
+    "SuspensionView",
+    "TaskRef",
+    "ToolAccepted",
+    "ToolBatch",
+    "ToolBatchFact",
+    "ToolBinding",
+    "ToolCall",
+    "ToolCatalog",
+    "ToolCatalogProvider",
+    "ToolChoice",
+    "ToolContext",
+    "ToolError",
+    "ToolExecution",
+    "ToolFailure",
+    "ToolOutcome",
+    "ToolOutcomeKind",
+    "ToolResult",
+    "ToolRisk",
+    "ToolSpec",
+    "ToolSuccess",
+    "ToolWaiting",
+    "ToolsPending",
+    "WaitingResult",
+    "freeze_json_value",
+    "thaw_json_value",
+    "tool_message",
+]

jharness_kernel-0.1.0/src/jharness/kernel/_digest.py

@@ -0,0 +1,242 @@
+"""Small explicit digest writer for immutable kernel content."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from hashlib import sha256
+from typing import Protocol, cast
+
+from jharness.kernel.messages import ArtifactRef, ContentPart, ErrorInfo, Message, TaskRef, ToolCall
+from jharness.kernel.tools import ToolAccepted, ToolFailure, ToolOutcome, ToolWaiting
+
+
+class _Hash(Protocol):
+    def update(self, data: bytes, /) -> None: ...
+
+    def digest(self) -> bytes: ...
+
+
+class DigestWriter:
+    """Domain-separated, length-prefixed writer with explicit scalar types."""
+
+    __slots__ = ("_hash",)
+
+    def __init__(self, domain: str) -> None:
+        self._hash: _Hash = sha256()
+        self._chunk(b"d", domain.encode())
+
+    def field(self, name: str) -> None:
+        self._chunk(b"k", name.encode())
+
+    def none(self) -> None:
+        self._hash.update(b"n")
+
+    def boolean(self, value: bool) -> None:
+        self._hash.update(b"b1" if value else b"b0")
+
+    def integer(self, value: int) -> None:
+        self._chunk(b"i", str(value).encode())
+
+    def number(self, value: float) -> None:
+        self._chunk(b"f", value.hex().encode())
+
+    def string(self, value: str) -> None:
+        self._chunk(b"s", value.encode())
+
+    def bytes(self, value: bytes) -> None:
+        self._chunk(b"x", value)
+
+    def sequence(self, length: int) -> None:
+        self._chunk(b"q", str(length).encode())
+
+    def mapping(self, length: int) -> None:
+        self._chunk(b"m", str(length).encode())
+
+    def json(self, value: object) -> None:
+        """Write a validated JSON value with stable mapping order and scalar types."""
+
+        if value is None:
+            self.none()
+        elif isinstance(value, bool):
+            self.boolean(value)
+        elif isinstance(value, int):
+            self.integer(value)
+        elif isinstance(value, float):
+            self.number(value)
+        elif isinstance(value, str):
+            self.string(value)
+        elif isinstance(value, Mapping):
+            self._json_mapping(cast(Mapping[object, object], value))
+        elif isinstance(value, Sequence) and not isinstance(value, bytes | bytearray):
+            items = cast(Sequence[object], value)
+            self.sequence(len(items))
+            for item in items:
+                self.json(item)
+        else:
+            raise TypeError(f"unsupported JSON digest value: {type(value).__qualname__}")
+
+    def finish(self) -> bytes:
+        return self._hash.digest()
+
+    def _json_mapping(self, value: Mapping[object, object]) -> None:
+        if any(not isinstance(key, str) for key in value):
+            raise TypeError("JSON digest mapping keys must be strings")
+        items = cast(Mapping[str, object], value)
+        keys = sorted(items)
+        self.mapping(len(keys))
+        for key in keys:
+            self.string(key)
+            self.json(items[key])
+
+    def _chunk(self, tag: bytes, value: bytes) -> None:
+        self._hash.update(tag)
+        self._hash.update(len(value).to_bytes(8, "big"))
+        self._hash.update(value)
+
+
+def empty_history_digest() -> bytes:
+    return DigestWriter("jharness.kernel.history.empty.v0").finish()
+
+
+def append_history_digest(previous: bytes, message: Message) -> bytes:
+    writer = DigestWriter("jharness.kernel.history.append.v0")
+    writer.field("previous")
+    writer.bytes(previous)
+    writer.field("message")
+    write_message(writer, message)
+    return writer.finish()
+
+
+def write_message(writer: DigestWriter, value: Message) -> None:
+    writer.field("role")
+    writer.string(value.role)
+    writer.field("parts")
+    write_parts(writer, value.parts)
+    writer.field("tool_calls")
+    write_tool_calls(writer, value.tool_calls)
+    writer.field("tool_call_id")
+    write_optional_string(writer, value.tool_call_id)
+    writer.field("outcome")
+    if value.outcome is None:
+        writer.none()
+    else:
+        _write_tool_outcome(writer, value.outcome)
+    writer.field("metadata")
+    writer.json(value.metadata)
+
+
+def write_parts(writer: DigestWriter, values: tuple[ContentPart, ...]) -> None:
+    writer.sequence(len(values))
+    for value in values:
+        _write_content_part(writer, value)
+
+
+def _write_content_part(writer: DigestWriter, value: ContentPart) -> None:
+    writer.field("content_part")
+    writer.field("type")
+    writer.string(value.type)
+    writer.field("text")
+    write_optional_string(writer, value.text)
+    writer.field("uri")
+    write_optional_string(writer, value.uri)
+    writer.field("artifact")
+    if value.artifact is None:
+        writer.none()
+    else:
+        _write_artifact(writer, value.artifact)
+    writer.field("media_type")
+    write_optional_string(writer, value.media_type)
+    writer.field("name")
+    write_optional_string(writer, value.name)
+    writer.field("data")
+    writer.json(value.data)
+    writer.field("metadata")
+    writer.json(value.metadata)
+
+
+def _write_artifact(writer: DigestWriter, value: ArtifactRef) -> None:
+    writer.field("artifact_ref")
+    writer.field("ref")
+    writer.string(value.ref)
+    writer.field("media_type")
+    write_optional_string(writer, value.media_type)
+    writer.field("name")
+    write_optional_string(writer, value.name)
+    writer.field("size_bytes")
+    write_optional_integer(writer, value.size_bytes)
+    writer.field("sha256")
+    write_optional_string(writer, value.sha256)
+    writer.field("metadata")
+    writer.json(value.metadata)
+
+
+def write_tool_calls(writer: DigestWriter, values: tuple[ToolCall, ...]) -> None:
+    writer.sequence(len(values))
+    for value in values:
+        _write_tool_call(writer, value)
+
+
+def _write_tool_call(writer: DigestWriter, value: ToolCall) -> None:
+    writer.field("tool_call")
+    writer.field("id")
+    writer.string(value.id)
+    writer.field("name")
+    writer.string(value.name)
+    writer.field("arguments")
+    writer.json(value.arguments)
+
+
+def _write_tool_outcome(writer: DigestWriter, value: ToolOutcome) -> None:
+    writer.field("tool_outcome")
+    writer.field("kind")
+    writer.string(value.kind)
+    writer.field("parts")
+    write_parts(writer, value.parts)
+    writer.field("structured_content")
+    writer.json(value.structured_content)
+    if isinstance(value, ToolFailure):
+        writer.field("error")
+        write_error(writer, value.error)
+    elif isinstance(value, ToolAccepted):
+        writer.field("correlation_id")
+        writer.string(value.correlation_id)
+        writer.field("task")
+        _write_optional_task(writer, value.task)
+    elif isinstance(value, ToolWaiting):
+        writer.field("task")
+        _write_optional_task(writer, value.task)
+
+
+def _write_optional_task(writer: DigestWriter, value: TaskRef | None) -> None:
+    if value is None:
+        writer.none()
+        return
+    writer.field("task_ref")
+    writer.field("id")
+    writer.string(value.id)
+    writer.field("status")
+    writer.string(value.status)
+    writer.field("metadata")
+    writer.json(value.metadata)
+
+
+def write_error(writer: DigestWriter, value: ErrorInfo) -> None:
+    writer.field("error_info")
+    writer.field("code")
+    writer.string(value.code)
+    writer.field("message")
+    writer.string(value.message)
+
+
+def write_optional_string(writer: DigestWriter, value: str | None) -> None:
+    if value is None:
+        writer.none()
+    else:
+        writer.string(value)
+
+
+def write_optional_integer(writer: DigestWriter, value: int | None) -> None:
+    if value is None:
+        writer.none()
+    else:
+        writer.integer(value)

jharness_kernel-0.1.0/src/jharness/kernel/_engine/__init__.py

@@ -0,0 +1 @@
+"""Private execution engine."""