Harness foundation: INTENT, ADR-001, architecture, prototype adoption
- 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>
This commit is contained in:
parent
87ae78c56a
commit
cfc1b75157
18 changed files with 1204 additions and 1 deletions
57
docs/adr/ADR-001-agent-harness-architecture.md
Normal file
57
docs/adr/ADR-001-agent-harness-architecture.md
Normal file
|
|
@ -0,0 +1,57 @@
|
|||
---
|
||||
id: ADR-001
|
||||
title: Single shared agent harness; instances are declarative state in consuming repos
|
||||
status: accepted
|
||||
date: "2026-07-17"
|
||||
---
|
||||
|
||||
# ADR-001 — Single shared agent harness
|
||||
|
||||
## Status
|
||||
|
||||
Accepted (DEC-2026-002, binky-control DecisionQueue, resolved by Bernd
|
||||
2026-07-17; hub decision `63620255-59d0-4109-bdee-4d0644c450e5`).
|
||||
|
||||
## Context
|
||||
|
||||
Unattended agentic work needs blueprints (kaizen-agentic), compute
|
||||
(llm-connect), scheduling (activity-core), credentials, policy, memory,
|
||||
and reporting — a complex, rapidly evolving combination. The candidate
|
||||
homes for the execution runtime all had disqualifying boundaries in their
|
||||
ratified INTENT files: activity-core "does not execute the work";
|
||||
kaizen-agentic does no scheduling and no LLM invocation; llm-connect is
|
||||
an interface layer. Per-project executor repos would multiply glue code
|
||||
and upgrades linearly with agent count. The concrete trigger: binky-
|
||||
control's operating rhythm depended on a workstation cron bridge
|
||||
(BINKY-WP-0004).
|
||||
|
||||
## Decision
|
||||
|
||||
1. **One new repo — `agent-harness` — is the single shared agent runtime
|
||||
for all projects.** No further runtime repos per agent or per project.
|
||||
2. **Agent instances live in consuming repos as declarative state only**
|
||||
(manifest + `.kaizen/` memory/metrics): blueprint reference, cadence,
|
||||
lane, named tool profile, budget, pinned harness major. No code, no
|
||||
credentials, no tool enumerations.
|
||||
3. **Blueprints stay in kaizen-agentic; scheduling stays in
|
||||
activity-core; provider abstraction stays in llm-connect.** The
|
||||
harness consumes all three and is the only credential holder and
|
||||
policy enforcement point for agent sessions.
|
||||
4. The 2026-07-17 executor-worker prototype is adopted as the harness
|
||||
seed (`agent_harness/` package). binky-control is tenant #1.
|
||||
|
||||
Details: [docs/architecture.md](../architecture.md).
|
||||
|
||||
## Consequences
|
||||
|
||||
- Adding an agent to any project = editing that project's manifest;
|
||||
onboarding a project = committing one manifest.
|
||||
- Base-technology evolution (adapters, tool policies, credential
|
||||
mechanics) lands once, here — instances upgrade by version bump.
|
||||
- The harness becomes a critical shared service: it needs its own
|
||||
versioning discipline, conformance tests, and kaizen measurement.
|
||||
- BINKY-WP-0004-T06 (cron-bridge cutover) now gates on this repo's
|
||||
Railiance deployment instead of a binky-specific worker.
|
||||
- Repo-boundary discipline continues: any pressure to add scheduling,
|
||||
blueprint authoring, or tenant-specific logic here is a signal to
|
||||
extend the neighbor repo or the instance model instead.
|
||||
82
docs/architecture.md
Normal file
82
docs/architecture.md
Normal file
|
|
@ -0,0 +1,82 @@
|
|||
# agent-harness Architecture
|
||||
|
||||
> Status: v0.1, 2026-07-17. Companion to ADR-001 and INTENT.md.
|
||||
> The code in `agent_harness/` is the prototype seed (formerly
|
||||
> `~/executor-worker`, built for BINKY-WP-0004-T04); this document
|
||||
> describes both what exists and the target shape.
|
||||
|
||||
## The three-layer model
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ CONSUMING REPO (e.g. binky-control) [instance] │
|
||||
│ .kaizen/schedule.yml + agent manifest ← declarative only│
|
||||
│ .kaizen/agents/<name>/memory.md, metrics │
|
||||
└──────────────▲──────────────────────────────────────────────┘
|
||||
│ reads instance state ┌──────────────┐
|
||||
┌──────────────┴──────────────┐ blueprint via │kaizen-agentic│
|
||||
│ AGENT-HARNESS [runtime]│◄───────────────┤ [blueprint] │
|
||||
│ task intake → persona bind │ schedule └──────────────┘
|
||||
│ → credential acquisition │ prepare
|
||||
│ → bounded agentic session │
|
||||
│ → commit verification │ ┌───────────────┐
|
||||
│ → hub + kaizen reporting │◄───────┤ activity-core │ emits tasks
|
||||
└───┬──────────┬──────────┬───┘ │ [scheduler] │ (cron/event)
|
||||
│ │ │ └───────────────┘
|
||||
llm-connect OpenBao State Hub
|
||||
(adapters) (ops-warden (REST: progress,
|
||||
lanes) tasks, decisions)
|
||||
```
|
||||
|
||||
## Components (current prototype → target)
|
||||
|
||||
| Component | File | Today | Target |
|
||||
|---|---|---|---|
|
||||
| Task intake | `taskspec.py` | JSON task-spec file | poll issue-core sink / TaskExecutorWorkflow |
|
||||
| Persona | `persona.py` | `kaizen-agentic schedule prepare` (ADR-005) | unchanged, plus phase-memory profile hook |
|
||||
| Session | `adapter.py` | `AgenticClaudeCodeAdapter` (llm-connect subclass, cwd-pinned, hard allow-list) | + hosted adapters; tool profiles (below) |
|
||||
| Orchestration | `runner.py` | HEAD snapshot → session → commit check → report | + budget enforcement, kaizen metrics write |
|
||||
| Mail lane | `mailscan.py` | deterministic credentialed pre-step outside the session | pattern generalizes to other credentialed pre-steps |
|
||||
| Hub reporting | `hub.py` | REST progress event + task close | unchanged |
|
||||
|
||||
## Contracts
|
||||
|
||||
**Instance manifest** (in the consuming repo; `.kaizen/schedule.yml` today,
|
||||
extended per-agent fields as the manifest spec lands in HARNESS-WP-0001):
|
||||
blueprint name, cadence, `enabled`, plus target additions: `lane`
|
||||
(green/blue), `tool_profile` (named, defined here), `budget`
|
||||
(tokens/run), `harness` (pinned major version).
|
||||
|
||||
**Tool profiles** are named allow-lists defined centrally in the harness,
|
||||
referenced by name from manifests — instances never enumerate tools.
|
||||
Seed profile `green-commit-only` = Read/Write/Edit/Glob/Grep + local git
|
||||
add/commit/status/log/diff. No push, no network, no arbitrary shell.
|
||||
|
||||
**Completion events** are the idempotence currency: each run posts a
|
||||
progress event (e.g. `binky_daily_brief`, `binky_mail_intake`) with
|
||||
`detail.repo`; activity-core's `binky_rhythm_status`-style resolvers read
|
||||
them to decide dueness. Failures post generic failure events so slots
|
||||
stay due.
|
||||
|
||||
**Credentials** are acquired per run, held only in process memory/child
|
||||
env, never logged: LLM key via the llm-connect OpenBao lane, git push via
|
||||
per-repo forgejo deploy keys, tenant secrets (e.g. IMAP) via
|
||||
non-interactive AppRole. See binky-control
|
||||
`integrations/executor-worker-secrets.md` for the provisioned lanes.
|
||||
|
||||
## Regulation and evolution
|
||||
|
||||
- **Regulation:** manifest declares, harness enforces. flex-auth gates
|
||||
apply at credential acquisition; ops-warden catalogs every lane; each
|
||||
instance runs under a named hub identity (`agt-…`).
|
||||
- **Evolution:** the harness emits `.kaizen/metrics` per run so the
|
||||
kaizen optimization loop covers both blueprints and the harness itself.
|
||||
Harness releases are versioned; instances pin majors; blueprint
|
||||
conformance tests run before rollout.
|
||||
|
||||
## Deployment
|
||||
|
||||
One deployment on Railiance (single-tenant-host, multi-tenant-repos).
|
||||
State Hub reachable at `:18000` via ops-bridge from remote hosts. The
|
||||
workstation may run the harness ad hoc for development; production runs
|
||||
must not depend on it (that dependence is the problem this repo solves).
|
||||
Loading…
Add table
Add a link
Reference in a new issue