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