70 lines
3.4 KiB
Markdown
70 lines
3.4 KiB
Markdown
|
# INTENT
|
||
|
|
|
||
|
|
> This file explains why agent-harness exists — the problem it solves, the
|
||
|
|
> principle that governs its boundaries, and what it must never become.
|
||
|
|
> Established by DEC-2026-002 (binky-control DecisionQueue, resolved
|
||
|
|
> 2026-07-17) and ADR-001 in this repo.
|
||
|
|
|
||
|
|
## Why it exists
|
||
|
|
|
||
|
|
Agentic work in the ecosystem requires combining many rapidly evolving
|
||
|
|
ingredients: agent blueprints (kaizen-agentic), LLM compute (llm-connect),
|
||
|
|
scheduling (activity-core), credentials (OpenBao/ops-warden), policy gates
|
||
|
|
(net-kingdom/flex-auth), memory (phase-memory, `.kaizen/` state), and
|
||
|
|
reporting (Custodian State Hub). Without a shared runtime, every project
|
||
|
|
that wants unattended agents must re-wire all of this — and every base-
|
||
|
|
technology shift multiplies into N project upgrades. The first concrete
|
||
|
|
casualty: binky-control's daily rhythm depended on a workstation cron
|
||
|
|
bridge because no workstation-independent runtime existed.
|
||
|
|
|
||
|
|
agent-harness exists so that **any project can run governed, unattended
|
||
|
|
agent instances by committing a small declarative manifest — while all the
|
||
|
|
fast-evolving wiring lives, evolves, and is enforced in exactly one
|
||
|
|
place.**
|
||
|
|
|
||
|
|
## The governing principle: three layers
|
||
|
|
|
||
|
|
1. **Blueprint (class)** — owned by kaizen-agentic. Versioned, reusable,
|
||
|
|
centrally improved agent definitions.
|
||
|
|
2. **Instance** — owned by the consuming repo. Declarative state only:
|
||
|
|
which blueprints run, cadence, autonomy lane, named tool profile,
|
||
|
|
budget, plus `.kaizen/` memory and metrics. Never code, never
|
||
|
|
credentials, never tool wiring.
|
||
|
|
3. **Harness (runtime)** — this repo. The single shared, multi-tenant
|
||
|
|
runtime: consumes tasks emitted by activity-core, loads the blueprint
|
||
|
|
(ADR-005 `schedule prepare`), binds instance state, acquires
|
||
|
|
credentials, runs the bounded agentic session via llm-connect,
|
||
|
|
verifies the local commit, reports to the State Hub and to the
|
||
|
|
instance's kaizen metrics.
|
||
|
|
|
||
|
|
The harness is the **only credential holder and the only policy
|
||
|
|
enforcement point** for agent sessions. Instances declare policy; the
|
||
|
|
harness enforces it. Instances pin a harness major version; upgrades
|
||
|
|
happen centrally.
|
||
|
|
|
||
|
|
## Strategic role
|
||
|
|
|
||
|
|
This is the "federated execution" half of the hub-and-spoke AgentOps
|
||
|
|
model (agentic-resources intent): central standards and runtime, per-repo
|
||
|
|
instances. It closes the gap the other repos deliberately leave open —
|
||
|
|
activity-core answers when/what/where and *does not execute*;
|
||
|
|
kaizen-agentic declares and prepares and *does not invoke LLMs*;
|
||
|
|
llm-connect abstracts providers and *does not orchestrate*.
|
||
|
|
|
||
|
|
## What it must never become
|
||
|
|
|
||
|
|
- **Not a scheduler.** Triggering and task emission stay in
|
||
|
|
activity-core. The harness only consumes.
|
||
|
|
- **Not a blueprint author.** Agent definitions, measurement conventions,
|
||
|
|
and improvement loops stay in kaizen-agentic.
|
||
|
|
- **Not a per-project logic container.** Anything specific to one tenant
|
||
|
|
belongs in that tenant's manifest or blueprint — the harness stays
|
||
|
|
generic or the instance model has failed.
|
||
|
|
- **Not an LLM abstraction.** Provider handling stays in llm-connect.
|
||
|
|
- **Not a state store.** Run history, task lifecycle, and decisions live
|
||
|
|
in the State Hub; agent memory lives with the instance (and later
|
||
|
|
phase-memory profiles).
|
||
|
|
- **Not autonomous beyond its grant.** Sessions run under named tool
|
||
|
|
profiles with hard allow-lists; the harness never pushes beyond the
|
||
|
|
target repo grant and never widens its own permissions.
|