tegwick
66ccd4fa01
Add intake client mapping emissions to TaskSpec, CLI poll and run --from-issue-core, keep --task-file for local dev. Completes HARNESS-WP-0001 workplan.
84 lines
5 KiB
Markdown
84 lines
5 KiB
Markdown
# 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 |
|
|
|---|---|---|---|
|
|
| Instance manifest | `manifest.py` | extends `.kaizen/schedule.yml`; `validate` CLI | unchanged contract; tenant onboarding |
|
|
| Tool profiles | `profiles.py` | `green-commit-only`, `blue-mail-triage` registry | additional named profiles as needed |
|
|
| Task intake | `intake.py` + `taskspec.py` | issue-core GET/PATCH poll+claim; JSON task-file for local dev | NATS when activity-core migrates |
|
|
| Persona | `persona.py` | `kaizen-agentic schedule prepare` (ADR-005) | unchanged, plus phase-memory profile hook |
|
|
| Session | `adapter.py` | `AgenticClaudeCodeAdapter` (cwd-pinned, profile allow-list) | + hosted adapters |
|
|
| Orchestration | `runner.py` | profile/budget → session → commit → metrics → hub | activity-core intake |
|
|
| Metrics | `metrics.py` | ADR-004 `.kaizen/metrics` write per run | correlate with Helix fleet metrics |
|
|
| 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 + token event | unchanged |
|
|
|
|
## Contracts
|
|
|
|
**Instance manifest** — `.kaizen/schedule.yml` (ADR-005 base + harness
|
|
extensions). Full contract: [instance-manifest.md](instance-manifest.md).
|
|
Fields: blueprint, cadence, `enabled`, `lane` (green/blue),
|
|
`tool_profile` (named), `budget` (tokens/run), `harness` (pinned major).
|
|
|
|
**Tool profiles** are named allow-lists defined centrally in the harness
|
|
(`profiles.py`), referenced by name from manifests — instances never
|
|
enumerate tools. Seed: `green-commit-only`, `blue-mail-triage`. No push,
|
|
no network, no arbitrary shell. Unknown profile = refuse to run.
|
|
|
|
**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).
|