rein-aharness/docs/architecture.md

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. 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).