# agent-harness

The single shared runtime for unattended agent instances in the Coulomb /
Operational Knowledge ecosystem. Projects declare agents (manifest +
`.kaizen/` state); this harness runs them — blueprint via kaizen-agentic,
tasks via activity-core, compute via llm-connect, credentials via
OpenBao/ops-warden, reporting to the Custodian State Hub.

- Why and boundaries: [INTENT.md](INTENT.md)
- Decision + architecture: [docs/adr/ADR-001](docs/adr/ADR-001-agent-harness-architecture.md),
  [docs/architecture.md](docs/architecture.md)
- Current work: [workplans/](workplans/)

## Usage

```
# Validate a consuming repo's instance manifest (.kaizen/schedule.yml)
agent-harness validate --target ~/binky-control
agent-harness validate --target ~/binky-control --strict   # require harness fields

# List named tool profiles
agent-harness profiles

# Run exactly one task (local JSON task-file path)
agent-harness run --task-file examples/task-hello-sandbox.json [--no-hub] [--no-metrics]

# Deterministic mailbox scan (no LLM session)
agent-harness mail-scan --target-repo ~/binky-control
```

Each `run` resolves the agent's tool profile + budget from the target
repo's instance manifest (default `green-commit-only`), loads a persona
bundle (`kaizen-agentic schedule prepare`), runs a bounded agentic
session (cwd-pinned, hard allow-list, never pushes), verifies a local
commit, writes `.kaizen/metrics`, and posts a State Hub progress event.

Instance manifest contract: [docs/instance-manifest.md](docs/instance-manifest.md).
Example: [examples/schedule.harness.yml](examples/schedule.harness.yml).

Tests: `PYTHONPATH=".:$HOME/llm-connect" python3 -m pytest tests/ -q`