tegwick
cfc1b75157
- INTENT.md: three-layer model (blueprint/instance/harness), single shared runtime, never-become boundaries - ADR-001 (accepted): DEC-2026-002 resolution — one harness repo for all projects; instances are declarative state in consuming repos - docs/architecture.md: components, contracts (manifest, tool profiles, completion events, credential lanes), deployment shape - agent_harness/: executor-worker prototype adopted and renamed (6/6 tests green); HARNESS-WP-0001 initial workplan (7 tasks) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
69 lines
3.4 KiB
Markdown
69 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.
|