meristem 4.0.0__tar.gz

meristem-4.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Knuckles Team
+
+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.

meristem-4.0.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: meristem
+Version: 4.0.0
+Summary: Meristem, the in-run agent harness for explicit dependency DAGs and received plans: the agent run loop, edit application, tool contracts, constraints, pre-emit gates, the developer workspace and the host ports arbora fills
+Author-email: Repository Maintainers <maintainers@knuckles.team>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic<2.15.0.dev0,>=2.14.1
+Requires-Dist: platformdirs>=4.13.3
+Requires-Dist: pydantic-ai-slim==2.57.0
+Requires-Dist: pydantic-graph==2.57.0
+Requires-Dist: pydantic-ai-harness<0.58.0,>=0.57.0
+Provides-Extra: openai
+Requires-Dist: pydantic-ai-slim[openai]==2.57.0; extra == "openai"
+Dynamic: license-file
+
+# Meristem
+
+**The in-run agent harness.** Meristem supports and guides agent execution
+through explicit dependency DAGs and received ordered plans. Inspired by
+espalier-trained growth, it provides structure for execution, not model-weight
+training. It applies the decisions it is given; it does not store, decide,
+serve or connect on its own.
+
+Meristem is distributed as `agent-utilities` and imported as `agent_utilities`.
+Repository, package, CLI and API identifiers remain unchanged.
+
+[![PyPI - Version](https://img.shields.io/pypi/v/agent-utilities)](https://pypi.org/project/agent-utilities/)
+[![Build](https://github.com/Knuckles-Team/agent-utilities/actions/workflows/release.yml/badge.svg)](https://github.com/Knuckles-Team/agent-utilities/actions/workflows/release.yml)
+
+*Version: 4.0.0*
+
+## What it contains
+
+| Module | What it does inside one run |
+|---|---|
+| `agent_utilities.graph` | Applies a received ordered plan or dependency DAG. It enforces task slots and shared budgets, and emits ordered execution events. |
+| `agent_utilities.rlm` | Runs recursive model queries with shared request and tool limits and bounded concurrent model requests. |
+| `agent_utilities.harness.edit_engine` | Parses model-proposed edits (search/replace blocks, unified diffs), applies them with graduated matching, and re-prompts on malformed or unmatched edits. |
+| `agent_utilities.harness.contract_validator` | Checks a tool call's pre-conditions and its output's schema and verifier. |
+| `agent_utilities.harness.constraint_engine` | Enforces hierarchical constraints on tool calls (prompt, tool description, middleware, implementation) and escalates repeated violations. |
+| `agent_utilities.harness.quality_gates` | The pre-emit gate: antipattern detection, a preflight checklist and a multi-dimensional critique, in warn or block mode. |
+| `agent_utilities.runtime` | The developer workspace: typed actions and observations, a stateful shell, local and container backends, a policy gate it is given, and the browser and computer-use tier ports. |
+| `agent_utilities.host_ports` | The protocols the host fills: native and remote toolsets, tool clients, outbound credentials, delegated identity, the fleet catalog and the session keepalive. Without a host every binding port fails closed. |
+| `agent_utilities.core.paths` | Resolves the platform config, data, cache and log directories (`ARBORA_CONFIG_DIR`, XDG). |
+
+## Where everything else lives
+
+- **[Medulla](https://github.com/Knuckles-Team/epistemic-graph)**: facts, records,
+  vocabulary, storage and queries, ingest, retrieval, reasoning, memory, decisions, and
+  learning (evaluation, harness evolution, reward and trace records).
+- **[arbora](https://github.com/Knuckles-Team/arbora)**: admission, auth, served
+  operations (MCP, REST, A2A), messaging front-ends, the registry and the multiplexer.
+  arbora hosts this harness and registers the `host_ports` providers.
+- **[Scion SDK](https://github.com/Knuckles-Team/agent-connector-sdk)**:
+  connector contracts, transports, the A2A protocol library and connector helpers.
+
+## Install and use
+
+```bash
+pip install agent-utilities
+```
+
+```python
+from agent_utilities.runtime import create_workspace
+from agent_utilities.runtime.events import CmdRunAction, TestRunAction
+
+async with create_workspace(run_id="r1", prefer_docker=False) as ws:
+    await ws.act(CmdRunAction(command="git status"))
+    result = await ws.act(TestRunAction(selector="tests"))
+```
+
+## Run measurements
+
+The graph run result and terminal event include `metrics` from a monotonic
+client clock: `run_elapsed_ms` and ordered `model_requests` with
+`client_request_elapsed_ms`, outcome, model/provider attribution and validated
+per-response token counts. The sample list is bounded; `coverage: "partial"`
+means some observed requests were omitted. Failed requests have no invented
+token counts. These measurements are emitted through the host event sink for
+shared backend consumption; AU stores no session totals.
+
+Run time includes planning, tools and retries. Client request time includes
+transport and provider waiting. Neither is provider generation time, and neither
+is used to derive generation TPS. Provider queue wait, generation duration and
+TTFT are absent unless a future adapter measures and identifies them explicitly.
+
+## Received dependency plans
+
+A host can pass `RunPlan(dependency_plan=DependencyPlan(...))` to the same
+`run` or `iterate_run` entry point. Do not also set serial `steps`.
+`DependencyPlan` contains ordered `RunTask(task_id, prompt, depends_on)` values,
+an `output_task_id`, a `max_concurrency` task cap and an optional `plan_id`.
+The host gets the plan from EG and admits it through Arbora. AU does not turn
+free text into a plan or authorize a task.
+
+A completed task frees a slot at once. A dependent task can start while an
+unrelated task still runs. Every prerequisite must succeed. Each task gets a
+fresh history with only its direct dependency outputs. The output task must
+be the sole sink. Failed or stopped plans never return a partial child answer
+as a completed parent result.
+
+The trusted host can pass prior measured consumption as `RunPlan.initial_usage`
+(a `pydantic_ai.usage.RunUsage`) and `initial_elapsed_seconds`. Both default to
+zero. Keep `RunBudget` at its original bounds; do not subtract this usage in
+the host or add it to AU's result again. AU snapshots the reported request,
+tool and token counters. It includes them once in terminal aggregate usage.
+It subtracts the elapsed time once from the execution deadline. Exhausted initial
+model bounds stop before model binding or child dispatch. Prior tool usage above
+the tool limit also stops. At the exact tool limit, model-only answers remain
+allowed, but additional tools do not. Invalid counters or time
+fail closed. Model proposals, request metadata and scaffold updates cannot
+set this host-only input. Unreported token usage remains zero, not an estimate.
+
+If measured host work fails before a plan can return, the decision provider can
+raise `RunPlanFailure(error, initial_usage=usage, initial_elapsed_seconds=elapsed)`.
+AU validates the same inputs and includes the counters once in the terminal
+event and result. It preserves the original failure or cancellation, without
+dispatching work or replacing a budget. Do not wrap a provider failure without
+a reported usage ledger or add these counters again in the host.
+
+`run()` returns a failed `RunResult`. `AgentRunExecutor.execute_agent()` raises
+`RunFailed`, a `RuntimeError` subclass with the same error message. Its immutable
+`result` snapshot retains that aggregate receipt, with `run_id` and `usage`
+properties. The allowed host facade `agent_utilities.runtime` lazily re-exports
+the same run executor, plans, tasks, bounds, stop rule and failure types.
+Hosts must check the exception type and expected run identity
+before copying these counters. Keep the outcome failed; do not publish a
+partial answer or add the counters again. Successful and stopped returns,
+cancellation, and empty unreported ledgers keep their existing behavior.
+
+Request and tool reservations are shared across tasks and validation retries.
+An unspecified parallel tool limit uses a finite fallback of fifty calls.
+Token limits use reported usage, including fallback attempts. In-flight token
+use is not known in advance. `RunBudget.max_concurrent_requests` also caps
+model requests (fallback: four); the task cap can be lower. On cancellation,
+AU drains child coroutines before invoking host-scope exit. Hosts own the
+cancellation safety of their asynchronous scope exits; repeated cancellation
+can interrupt that host cleanup. Host tools also own external work that cannot
+stop with their coroutine. No elapsed cleanup bound is promised for handlers
+that do not cooperate.
+
+`RLMConfig.max_concurrent_requests` and `tool_calls_limit` bound recursive
+model calls and tool fan-out (fallbacks: four and fifty). A parent releases its
+model-request slot before waiting for a child, including at capacity one.
+The parent model still chooses its next tool batch after the current batch
+returns. That model-choice boundary is not a declared dependency DAG.
+
+Public lifecycle events have a per-run `sequence` and stable `event_id`.
+Task events carry `task_id`, `parent_run_id`, `plan_id` and `depends_on`.
+They report execution state, not private model reasoning. Arbora owns their
+safe replay projection and access checks.
+
+A DAG driver owns the deadline after setup, using the same absolute deadline.
+A paused event reader cannot delay task dispatch or timeout cleanup. Consumers
+must finish or close the iterator. Pausing can delay the parent terminal event
+and host-scope release, even after all task work has stopped. Request handlers
+finish asynchronous cleanup before cancellation returns, including nested runs.
+
+## Develop
+
+```bash
+uv sync --group dev
+uv run ruff check . && uv run ruff format --check .
+uv run mypy agent_utilities
+uv run pytest -q
+```
+
+## License
+
+MIT, see [LICENSE](LICENSE).

meristem-4.0.0/README.md

@@ -0,0 +1,155 @@
+# Meristem
+
+**The in-run agent harness.** Meristem supports and guides agent execution
+through explicit dependency DAGs and received ordered plans. Inspired by
+espalier-trained growth, it provides structure for execution, not model-weight
+training. It applies the decisions it is given; it does not store, decide,
+serve or connect on its own.
+
+Meristem is distributed as `agent-utilities` and imported as `agent_utilities`.
+Repository, package, CLI and API identifiers remain unchanged.
+
+[![PyPI - Version](https://img.shields.io/pypi/v/agent-utilities)](https://pypi.org/project/agent-utilities/)
+[![Build](https://github.com/Knuckles-Team/agent-utilities/actions/workflows/release.yml/badge.svg)](https://github.com/Knuckles-Team/agent-utilities/actions/workflows/release.yml)
+
+*Version: 4.0.0*
+
+## What it contains
+
+| Module | What it does inside one run |
+|---|---|
+| `agent_utilities.graph` | Applies a received ordered plan or dependency DAG. It enforces task slots and shared budgets, and emits ordered execution events. |
+| `agent_utilities.rlm` | Runs recursive model queries with shared request and tool limits and bounded concurrent model requests. |
+| `agent_utilities.harness.edit_engine` | Parses model-proposed edits (search/replace blocks, unified diffs), applies them with graduated matching, and re-prompts on malformed or unmatched edits. |
+| `agent_utilities.harness.contract_validator` | Checks a tool call's pre-conditions and its output's schema and verifier. |
+| `agent_utilities.harness.constraint_engine` | Enforces hierarchical constraints on tool calls (prompt, tool description, middleware, implementation) and escalates repeated violations. |
+| `agent_utilities.harness.quality_gates` | The pre-emit gate: antipattern detection, a preflight checklist and a multi-dimensional critique, in warn or block mode. |
+| `agent_utilities.runtime` | The developer workspace: typed actions and observations, a stateful shell, local and container backends, a policy gate it is given, and the browser and computer-use tier ports. |
+| `agent_utilities.host_ports` | The protocols the host fills: native and remote toolsets, tool clients, outbound credentials, delegated identity, the fleet catalog and the session keepalive. Without a host every binding port fails closed. |
+| `agent_utilities.core.paths` | Resolves the platform config, data, cache and log directories (`ARBORA_CONFIG_DIR`, XDG). |
+
+## Where everything else lives
+
+- **[Medulla](https://github.com/Knuckles-Team/epistemic-graph)**: facts, records,
+  vocabulary, storage and queries, ingest, retrieval, reasoning, memory, decisions, and
+  learning (evaluation, harness evolution, reward and trace records).
+- **[arbora](https://github.com/Knuckles-Team/arbora)**: admission, auth, served
+  operations (MCP, REST, A2A), messaging front-ends, the registry and the multiplexer.
+  arbora hosts this harness and registers the `host_ports` providers.
+- **[Scion SDK](https://github.com/Knuckles-Team/agent-connector-sdk)**:
+  connector contracts, transports, the A2A protocol library and connector helpers.
+
+## Install and use
+
+```bash
+pip install agent-utilities
+```
+
+```python
+from agent_utilities.runtime import create_workspace
+from agent_utilities.runtime.events import CmdRunAction, TestRunAction
+
+async with create_workspace(run_id="r1", prefer_docker=False) as ws:
+    await ws.act(CmdRunAction(command="git status"))
+    result = await ws.act(TestRunAction(selector="tests"))
+```
+
+## Run measurements
+
+The graph run result and terminal event include `metrics` from a monotonic
+client clock: `run_elapsed_ms` and ordered `model_requests` with
+`client_request_elapsed_ms`, outcome, model/provider attribution and validated
+per-response token counts. The sample list is bounded; `coverage: "partial"`
+means some observed requests were omitted. Failed requests have no invented
+token counts. These measurements are emitted through the host event sink for
+shared backend consumption; AU stores no session totals.
+
+Run time includes planning, tools and retries. Client request time includes
+transport and provider waiting. Neither is provider generation time, and neither
+is used to derive generation TPS. Provider queue wait, generation duration and
+TTFT are absent unless a future adapter measures and identifies them explicitly.
+
+## Received dependency plans
+
+A host can pass `RunPlan(dependency_plan=DependencyPlan(...))` to the same
+`run` or `iterate_run` entry point. Do not also set serial `steps`.
+`DependencyPlan` contains ordered `RunTask(task_id, prompt, depends_on)` values,
+an `output_task_id`, a `max_concurrency` task cap and an optional `plan_id`.
+The host gets the plan from EG and admits it through Arbora. AU does not turn
+free text into a plan or authorize a task.
+
+A completed task frees a slot at once. A dependent task can start while an
+unrelated task still runs. Every prerequisite must succeed. Each task gets a
+fresh history with only its direct dependency outputs. The output task must
+be the sole sink. Failed or stopped plans never return a partial child answer
+as a completed parent result.
+
+The trusted host can pass prior measured consumption as `RunPlan.initial_usage`
+(a `pydantic_ai.usage.RunUsage`) and `initial_elapsed_seconds`. Both default to
+zero. Keep `RunBudget` at its original bounds; do not subtract this usage in
+the host or add it to AU's result again. AU snapshots the reported request,
+tool and token counters. It includes them once in terminal aggregate usage.
+It subtracts the elapsed time once from the execution deadline. Exhausted initial
+model bounds stop before model binding or child dispatch. Prior tool usage above
+the tool limit also stops. At the exact tool limit, model-only answers remain
+allowed, but additional tools do not. Invalid counters or time
+fail closed. Model proposals, request metadata and scaffold updates cannot
+set this host-only input. Unreported token usage remains zero, not an estimate.
+
+If measured host work fails before a plan can return, the decision provider can
+raise `RunPlanFailure(error, initial_usage=usage, initial_elapsed_seconds=elapsed)`.
+AU validates the same inputs and includes the counters once in the terminal
+event and result. It preserves the original failure or cancellation, without
+dispatching work or replacing a budget. Do not wrap a provider failure without
+a reported usage ledger or add these counters again in the host.
+
+`run()` returns a failed `RunResult`. `AgentRunExecutor.execute_agent()` raises
+`RunFailed`, a `RuntimeError` subclass with the same error message. Its immutable
+`result` snapshot retains that aggregate receipt, with `run_id` and `usage`
+properties. The allowed host facade `agent_utilities.runtime` lazily re-exports
+the same run executor, plans, tasks, bounds, stop rule and failure types.
+Hosts must check the exception type and expected run identity
+before copying these counters. Keep the outcome failed; do not publish a
+partial answer or add the counters again. Successful and stopped returns,
+cancellation, and empty unreported ledgers keep their existing behavior.
+
+Request and tool reservations are shared across tasks and validation retries.
+An unspecified parallel tool limit uses a finite fallback of fifty calls.
+Token limits use reported usage, including fallback attempts. In-flight token
+use is not known in advance. `RunBudget.max_concurrent_requests` also caps
+model requests (fallback: four); the task cap can be lower. On cancellation,
+AU drains child coroutines before invoking host-scope exit. Hosts own the
+cancellation safety of their asynchronous scope exits; repeated cancellation
+can interrupt that host cleanup. Host tools also own external work that cannot
+stop with their coroutine. No elapsed cleanup bound is promised for handlers
+that do not cooperate.
+
+`RLMConfig.max_concurrent_requests` and `tool_calls_limit` bound recursive
+model calls and tool fan-out (fallbacks: four and fifty). A parent releases its
+model-request slot before waiting for a child, including at capacity one.
+The parent model still chooses its next tool batch after the current batch
+returns. That model-choice boundary is not a declared dependency DAG.
+
+Public lifecycle events have a per-run `sequence` and stable `event_id`.
+Task events carry `task_id`, `parent_run_id`, `plan_id` and `depends_on`.
+They report execution state, not private model reasoning. Arbora owns their
+safe replay projection and access checks.
+
+A DAG driver owns the deadline after setup, using the same absolute deadline.
+A paused event reader cannot delay task dispatch or timeout cleanup. Consumers
+must finish or close the iterator. Pausing can delay the parent terminal event
+and host-scope release, even after all task work has stopped. Request handlers
+finish asynchronous cleanup before cancellation returns, including nested runs.
+
+## Develop
+
+```bash
+uv sync --group dev
+uv run ruff check . && uv run ruff format --check .
+uv run mypy agent_utilities
+uv run pytest -q
+```
+
+## License
+
+MIT, see [LICENSE](LICENSE).

meristem-4.0.0/agent_utilities/__init__.py

@@ -0,0 +1,32 @@
+"""agent-utilities: the in-run agent harness.
+
+The harness holds only the mechanism inside one agent run: applying edits,
+checking tool contracts and constraints, pre-emit gates, the developer
+workspace action/observation loop, the agent run loop
+(``agent_utilities.graph``, ``agent_utilities.rlm``) and the ``host_ports`` protocols through
+which the host (arbora) supplies tools, credentials, models and trace sinks.
+
+Facts, storage, retrieval, decisions and learning live in epistemic-graph;
+serving, admission and the registry live in arbora; connector contracts and
+transports live in agent-connector-sdk.
+"""
+
+from typing import Any
+
+from agent_utilities._version import __version__
+
+_GRAPH_EXPORTS = frozenset(
+    {"create_graph_agent", "execute_graph", "initialize_graph_from_workspace"}
+)
+
+
+def __getattr__(name: str) -> Any:
+    """Load the run-loop entry points on first use (keeps ``import`` light)."""
+    if name in _GRAPH_EXPORTS:
+        from agent_utilities import graph
+
+        return getattr(graph, name)
+    raise AttributeError(f"module 'agent_utilities' has no attribute {name!r}")
+
+
+__all__ = ["__version__", *sorted(_GRAPH_EXPORTS)]

meristem-4.0.0/agent_utilities/__main__.py

@@ -0,0 +1,15 @@
+"""``python -m agent_utilities``: print the harness version.
+
+Meristem is the in-run agent harness. It serves nothing on its own;
+arbora hosts it and serves its operations.
+"""
+
+from agent_utilities._version import __version__
+
+
+def main() -> None:
+    print(f"meristem {__version__} (in-run harness; hosted by arbora)")
+
+
+if __name__ == "__main__":
+    main()

meristem-4.0.0/agent_utilities/_version.py

@@ -0,0 +1,3 @@
+"""Authoritative package version for the meristem distribution."""
+
+__version__ = "4.0.0"

meristem-4.0.0/agent_utilities/core/__init__.py

@@ -0,0 +1 @@
+"""Core harness plumbing: the platform config/paths resolver."""