thestoryportal/arhugula-harness

1. What this repo is

This is a Python uv workspace for a multi-LLM agent harness called H_T. The repo is organized around four design axes — IS (information substrate), AS (action surface), CP (control plane), OD (observability/discipline) — plus a CXA cross-axis composition layer that stitches the axes together at runtime.

2. Top-level architectural split

The repo has two big kinds of content:

- Executable packages under harness-runtime/, harness-core/, harness-is/, harness-as/, harness-cp/, harness-od/, harness-cxa/

- Governance/design artifacts under design-substrate/ and .harness/

The design artifacts are not just docs; they define the contract boundaries that the runtime code and tests are enforcing.

3. Core runtime is the main orchestrator

harness-runtime/ is the central execution layer. It contains:

- bootstrap stages that assemble the system in sequence,

- lifecycle modules for dispatch, routing, pause/resume, HITL, tool execution, validation, and telemetry,

- CLI and admin entrypoints,

- configuration loading and runtime wiring.

This is the place where the axes become an operational harness.

4. Shared domain model lives in harness-core

harness-core/ holds the common enumerations and policy/domain primitives used across the workspace, such as workflow events, workload classes, persona tiers, sandbox decision policy, deployment surface, and identity. This package is the lowest-friction shared boundary so the axis packages do not duplicate semantic types.

5. Information substrate (harness-is)

harness-is/ is the durable state and artifact substrate. Its responsibilities include:

- path and artifact registries,

- state ledger read/write and JSONL event ledger lifecycle,

- git-tied checkpoint/rollback behavior,

- workload manifest and prompt manifest handling.

Architecturally, this is where the system persists and resolves “what exists” before the control plane decides “what should happen next.”

6. Action surface (harness-as)

harness-as/ defines the action-side policy and capability surface:

- sandbox tier/provider selection,

- secret fetching rules,

- MCP transport floors,

- engine-class composition,

- blast-radius and gate-level constraints,

- attribute and span namespace rules.

This layer governs what the harness is allowed to do when it reaches out to sandboxes, tools, model providers, or secrets.

7. Control plane (harness-cp)

harness-cp/ is the decision-making layer for workflow shape and routing:

- workflow drivers and topology patterns,

- routing layers and fallback chains,

- pause/resume protocols,

- HITL placement and tool-call rewriting,

- validator framework and fail taxonomy,

- workload-to-engine-class selection.

If IS is “state,” CP is “policy + routing logic” for the next action in a workflow.

8. Observability/disciplined execution (harness-od)

harness-od/ handles tracing, sampling, redaction, cost attribution, and audit plumbing:

- OTEL span store/processor components,

- redaction/token audit logic,

- cost formula and cost record serialization,

- multi-tenant trace separation,

- local collector and sampling mode logic.

This layer is the system’s telemetry and governance boundary; it ensures the harness can observe itself without leaking or collapsing tenant boundaries.

9. Cross-axis composition (harness-cxa)

harness-cxa/ is intentionally small and acts as the bridge between axes. It currently centers on CP audit conversion and seam exports, which suggests CXA is used to normalize or transform artifacts when one axis needs to interpret another axis’ output.

10. Runtime data flow

The typical path is:

- configuration and workflow manifests are loaded,

- bootstrap stages wire IS/AS/CP/OD into the runtime,

- the runtime selects a workflow topology and dispatch strategy,

- tool/LLM/MCP actions execute through sandbox and provider abstractions,

- state ledger, audit ledger, spans, and cost records are emitted,

- pause/resume, HITL, or validator escalation may interrupt and redirect the flow.

So the runtime is not a simple request/response app; it is a stateful orchestration loop with explicit policy checkpoints.

11. Execution environments and integrations

The repo supports multiple execution backends and deployment modes:

- local self-hosted Docker/compose stack in deploy/self-hosted-local/,

- managed-cloud deployment assets in deploy/managed-cloud/,

- sandbox/tool backends such as Docker, E2B, and gVisor-like execution paths,

- MCP server/client boundaries,

- OTEL collectors and Tempo/Grafana-style telemetry plumbing.

These are architectural boundaries because the harness is designed to route work differently depending on trust, sandbox tier, and deployment target.

12. Workflow and session governance

The repository contains substantial workflow-control material in .harness/, .claude/, and root governance files like CLAUDE.md, AGENTS.md, and Phase_7_*. This indicates the harness is operated through a disciplined session/process model, with explicit phase transitions, clearance artifacts, and roadmap/audit records rather than ad hoc development.

13. Validation strategy

Every package has strong unit coverage, and harness-runtime/ adds integration suites that exercise full bootstrap, routing, pause/resume, multi-server routing, memory backends, validator escalation, and live execution paths. There are also repo-level scripts and CI workflows under .github/ and tools/ for readiness probes, dashboard generation, and live environment checks.

14. How to draw the architecture

A useful diagram would place harness-runtime in the center, fed by configuration and workflow manifests from harness-is, constrained by policy/capability from harness-as and harness-cp, and instrumented by harness-od. Surround that with deployment/runtime backends, MCP/tool/sandbox providers, and a separate documentation/governance plane (design-substrate, .harness) that defines and audits the contract surface.