adolf/DESIGN-a2a-agents.md

DESIGN — Agap Agent Platform v2: the agent algebra

Status: v2, agreed with alvis 2026-07-21 (supersedes v1 draft 2499218c) Owner: alvis · Written with Claude

One design, two axioms, one verb. Everything alvis asked for — per-model queues, quota parking, Hindsight reflect as an async task, the Claude Code loop as a task puller, semantic/tier/direct routing — falls out as a special case rather than a rule. This document is the reference; the Kanboard A2A tasks implement it.

---

0. Glossary

• Task plane / "the fabric" — the task-passing substrate connecting all agents: Kanboard (the durable task store and queue — for humans and agents) + A2A protocol semantics (submit/status/result, Agent Cards, context-by-reference) + the conventions on top (claim/lease, priorities, parking, trust-class routing). Not a deployable component; the collective name, the way "the network" names cables + IP + routing.
• Card — an agent's self-description: capabilities, tier, cost class, trust class, availability. Maps 1:1 to an A2A Agent Card.
• Backbone — the concrete LLM an agent currently uses for reasoning.
• Context ref — a pointer (Hindsight bank id, git ref, KB task id, file path) passed instead of pasted content.

1. Why

Observed on the live stack:

• Duplicated LLM spend — an Adolf turn costs a ~32.8K-token reply call plus a ~22.8K-token background Hindsight extraction; ~425 tokens are the conversation.
• Tool bloat — one Adolf carries ~84 MCP tool schemas + ~26 built-in tools every turn (~22K tokens), relevant or not.
• Quota cliffs — Kimi's flat window (~60 msgs/5h, ~300/wk measured) makes Adolf go dark with no degradation path and no way to park work.
• Hardcoded background cognition — Hindsight reflect/consolidation call a fixed model directly: no scheduling, no priority, no quota awareness.
• No growth path — the ambition is autonomous research agents, remote llama nodes, more GPUs, more agents.

2. The algebra

Axiom 1 — everything that can receive work is an Agent

An agent is (identity, Card, Policy, State). The Card advertises capabilities, tier (model strength it offers or needs), cost class, trust class (§5), and an availability function a(t). Special cases:

Agent	Persona	Memory	Card highlights
LLM endpoint (kimi, gemma3:4b, …)	trivial (identity)	none	tier, cost, quota-shaped a(t)
Adolf	proactive auditor (SOUL.md)	Hindsight bank adolf	trusted; scoped core tools
claude-coder (Claude Code loop)	implementer	session + repo	trusted; pulls complex coding tasks
Torgash	marketplace analyst	own bank	sandboxed; marketplace tools only
researcher	autonomous researcher	own bank	sandboxed/untrusted inputs; own KB project
router	delegator	none	resolves constraints → agents
alvis (the human)	—	—	trust=human; a(t)=waking hours; inbox = KB "waiting-on-me"

The human being an agent is not a metaphor: approval gates, escalations and decisions are ordinary tasks submitted to his inbox. The KB column he already processes is that inbox.

Axiom 2 — one verb

submit(task, target) -> taskRef        # await(taskRef) optional => sync
task = (intent, context-refs, constraints, priority, deadline, provenance)
target ∈ { agent-id            # direct: “this backbone / this specialist”
         | constraint-set      # tier/capability: “any large model with tools”
         | auto }              # router decides by availability/quota/complexity

Context travels by reference, never by value — the single most important efficiency rule for inter-agent communication (A2A context-passing practice). sync vs async is not a second mechanism: sync = submit + await.

Theorems — the old rules become consequences

1. "Queues are per model, not per agent." Every agent has an inbox, but queues accumulate only where a(t) or throughput binds — at scarce agents: model-agents and the human. Persona agents transform-and-delegate, so their inboxes stay near-empty. The v1 rule is the scarcity special case.
2. Quota lifecycles are shapes of a(t). always-on: a(t)=1. quota-gated (Kimi): a(t)=0 when the window is spent — the queue parks, nothing fails, drains on reset. cost-gated: a(t)=0 past budget. on-demand (remote llama): a(t)=0 until woken. Four lifecycles, one function.
3. Hindsight reflect is just a submit — {intent: reflect, refs: bank+query, constraints: tier≥large}, async. Same for consolidation (low priority).
4. Backbone swap is a constraint edit. Persona agents name constraints, not endpoints; the backbone resolves per-submit. Adolf-on-Kimi today, Adolf-on-local tomorrow — no code change.
5. The Claude Code loop is an ordinary consumer — an agent whose policy is "pull complex coding tasks from the fabric". It was never special.
6. For free: escalation = re-submit with wider constraints (gated by policy, §5); approval = submit(…, target=alvis); proactivity/cron = delayed self-submission; the researcher = a low-priority self-submitting loop.

Granularity rule

A Task is a durable work item with a lifecycle worth auditing. A single LLM completion inside an agent's turn is not a Task — it is an implementation detail, observable in Langfuse, invisible to Kanboard. This keeps the KB-literal fabric free of micro-churn by construction.

3. Planes

┌─ Task plane (“the fabric”) ─────────────────────────────────────────┐
│ Kanboard = the queue + audit + human inboxes (KB-LITERAL: no        │
│ separate store). A2A semantics; claim/lease; priorities; parking.   │
└─────────────────────────────────────────────────────────────────────┘
┌─ Agent plane ───────────────────────────────────────────────────────┐
│ Registry of Cards (persona, memory bank, tool scope, trust class,   │
│ preferred tier, current backbone). Runtimes: OpenClaw (Adolf +      │
│ specialists), Claude Code CLI, thin workers.                        │
└─────────────────────────────────────────────────────────────────────┘
┌─ Model plane ───────────────────────────────────────────────────────┐
│ LiteLLM gateway (:4000). Auto Router v2 (2026-07-14) does the SYNC  │
│ routing natively: pinned model | tier pools | complexity/semantic   │
│ auto-routing (SIMPLE<MEDIUM<COMPLEX<REASONING), plus virtual keys,  │
│ budgets, 429-fallback. alvis's three routing modes map 1:1:         │
│   specific backbone → pinned model_name                             │
│   “tier” routing    → tier pool                                     │
│   automatic router  → auto_router/complexity_router                 │
│ The fabric owns everything LiteLLM cannot: ASYNC queueing, parking  │
│ across quota windows, leases, cross-agent budget arbitration.       │
└─────────────────────────────────────────────────────────────────────┘
┌─ Context stores ────────────────────────────────────────────────────┐
│ Hindsight banks (per-agent memory) · gitea (code, docs, this file)  │
│ · KB task bodies · files. Tasks point here; payloads never inline.  │
└─────────────────────────────────────────────────────────────────────┘

4. A2A: the protocol, adopted now

The algebra maps 1:1 onto A2A v1.0 (Jan 2026), which is why we implement the real protocol immediately rather than "patterns first":

Algebra	A2A
Card	Agent Card (/.well-known/agent.json)
submit / await	message/send (sync-ish) / tasks/get (async)
task lifecycle	submitted → working → input-required → completed/failed/canceled
notify	push notifications

Implementation: JSON-RPC 2.0 over HTTP on the LAN; each runtime (OpenClaw, Claude loop, workers) exposes/consumes A2A; Kanboard remains the durable state behind the endpoints. Scalability/extensibility later (remote nodes, third-party agents) then needs zero redesign.

5. Trust & sandboxing

Trust classes (on every Card):

human > trusted > sandboxed > untrusted

• trusted (Adolf, claude-coder): vault access yes; outward actions per existing ask-first rules.
• sandboxed (Torgash, researcher): no vault, no outward sends; scoped MCP allowlist; KB access project-scoped (researcher gets its own KB project(s)).
• untrusted = anything ingesting the open web: its outputs are tainted.

Taint / prompt-injection boundary: tainted output may be written only to the agent's own bank/notes/project. Promotion into a trusted agent's memory or into any action requires a gate (initially: a task to alvis's inbox; later possibly a reviewer-agent).

Escalation policy (initial): always-ask. A task that fails on its tier is not silently retried on a bigger model; it becomes a decision task in alvis's inbox. Revisit once behavior is observed (debugging phase by design).

Sandboxed coding — workspace lease: per task, not per agent: workspaces/<agent>/<task-id>/ = ephemeral gitea clone + branch; execution inside a container (no vault creds by default, network allowlist, resource caps); merge only via PR to gitea; autonomous agents never push to main. Reviewer = human, or later a reviewer-agent (just another persona).

Global budget governor: near the end of a quota window, interactive agents (Adolf) outrank background ones (researcher, consolidation) — arbitration lives in the fabric (priorities + a small governor rule), not in LiteLLM.

6. Executor — thin KB-polling workers

No Temporal/Hatchet: at homelab scale (dozens of tasks/day) a durable-execution platform would duplicate Kanboard as a second source of truth. Instead, one small worker daemon per model-queue (compose services, ~200 lines, shared lib):

loop:
  a(t) check        # quota/budget/health probe; if 0 → park (sleep, re-probe)
  poll KB view      # filtered: my queue, status=queued, by priority
  claim             # atomic: assign-to-self + column move + lease timestamp
  resolve refs      # fetch context by reference
  execute           # via LiteLLM (model-agents) / agent runtime (persona)
  write result ref  # to the shared store; never inline
  update status     # done | failed(retry policy) | input-required(→ inbox)

Leases + heartbeats make dead workers safe: an expired lease returns the task to queued. Two workers on one queue never double-run a task (claim is atomic). Idempotency keys on submission prevent duplicate proactive tasks. OpenClaw cron is the proactive submitter (Adolf's schedule); workers are the drainers.

7. Observability — Langfuse (kept), wired for real

Decision: keep Langfuse (already deployed; best-in-class self-hosted: traces + per-token cost + prompt management + evals, MIT). Grafana rejected for this role — generic metrics with no LLM semantics (the source of past dissatisfaction); Zabbix keeps infra monitoring. To do (it currently receives nothing): LiteLLM success/failure callbacks → Langfuse; tag every trace with agent, task-id, queue; per-agent cost dashboards; upgrade v2→v3. Every completion is traced here — this is where sub-Task granularity lives.

8. Growing the lab

• More GPUs / remote llama → new model-agent Cards with on-demand a(t) (health probe, wake hook, graceful absence). Routing skips absent nodes.
• More specialists → new Cards + scoped tools + own banks. The fabric and A2A don't change.
• Autonomous research agents → low-priority loops on always-on local queues, escalating (via always-ask, initially) for large-model synthesis; own KB project; tainted outputs until promoted.

9. Migration order

1. Registries: model Cards + agent Cards (schema + populate).
2. First thin worker end-to-end on an always-on local queue.
3. Quota-gated worker (Kimi park/resume). Claim/lease semantics.
4. A2A protocol surface (JSON-RPC + Agent Cards) over the fabric.
5. Cutovers: Hindsight reflect → fabric; consolidation → fabric (low prio); claude-coder + Adolf declared as registry agents (Adolf's tools shrink to scoped core).
6. Trust enforcement: capability grants (virtual keys + MCP allowlists), taint gate, budget governor, langfuse wiring.
7. Scale: Torgash, researcher (own KB project), on-demand nodes.

10. Decision log (2026-07-21, alvis)

1. Single completions are not Tasks (langfuse-only) → no micro-churn.
2. KB-literal: Kanboard is the queue, humans included; no separate store.
3. Trust classes as §5; vault = trusted only.
4. Escalation = always-ask initially.
5. Researcher: KB access allowed, own project(s), scope-limited.
6. Real A2A protocol now (JSON-RPC + Agent Cards).
7. Proactive schedules: OpenClaw cron → fabric.
8. Langfuse kept as the observability layer; Grafana rejected; Zabbix = infra.
9. Executor = thin KB-polling workers; no Hatchet/Temporal at this scale.
10. Sync routing = LiteLLM Auto Router v2; fabric owns async/parking.
11. Sandbox = per-task workspace lease + container + PR-only merges.