yvgude--lean-ctx/docs/contracts/a2a-contract-v1.md

A2A Contract v1

GitLab: #2319

Ziel

Ein versionierter Agent↔Agent Vertrag (A2A), der Multi‑Agent‑Koordination als Infrastruktur absichert:

• bounded: Outputs/Stores wachsen nicht unkontrolliert.
• deterministisch: stable ordering + klare Semantik für Sichtbarkeit/TTL/Transitions.
• privacy-safe: Private Messages sind nur Sender/Empfänger sichtbar; Exports sind redaction-safe.
• auditable: Export‑Artefakte werden im Evidence Ledger referenziert.

Version (SSOT)

• leanctx.contract.a2a_snapshot_v1.schema_version=1
  • SSOT: CONTRACTS.md
  • Runtime: rust/src/core/contracts.rs

Datenmodelle (Runtime)

Messages / Scratchpad

• Runtime structs:
  • rust/src/core/a2a/message.rs (A2AMessage — Privacy/Priority/TTL Semantik)
  • rust/src/core/agents.rs (ScratchpadEntry als persisted Scratchpad)

Type Alignment (seit v1.1):

ScratchpadEntry und A2AMessage sind feld-kompatibel mit bidirektionalen From-Konvertierungen:

ScratchpadEntry	A2AMessage	Mapping
message: String	content: String	message ↔ content
category: String	category: MessageCategory	String ↔ MessageCategory::parse_str() / .to_string()
task_id: Option<String>	task_id: Option<String>	direkt
project_root: Option<String>	project_root: Option<String>	direkt
expires_at: Option<DateTime>	expires_at: Option<DateTime>	direkt

Alle neuen Felder sind #[serde(default)] für backward compatibility.

MUST Semantik:

• Privacy:
  • public / team ⇒ sichtbar (subject to routing)
  • private ⇒ sichtbar nur für Sender oder expliziten Empfänger
  • Private Messages müssen ein to_agent besitzen (keine private broadcasts).
• TTL:
  • ttl_hours>=1 ⇒ expires_at wird gesetzt.
  • Expired Messages sind nicht sichtbar und werden bei Reads/Posts deterministisch bereinigt.
• Project Scope:
  • Wenn ein Project Root im Tool‑Kontext aktiv ist, sind nur Messages mit exakt passendem project_root sichtbar.

Tasks

• Runtime: rust/src/core/a2a/task.rs
• MUST:
  • TaskState ist eine State Machine; ungültige Transitions werden abgelehnt.
  • Terminal states: completed|failed|canceled.

Cost Attribution (local-first)

• Runtime: rust/src/core/a2a/cost_attribution.rs
• MUST:
  • Costs werden pro Agent und pro Tool aggregiert.
  • cached_tokens werden unterstützt (separat aggregiert und im Pricing berücksichtigt, wenn vorhanden).

Rate Limiting (fairness)

• Runtime: rust/src/core/a2a/rate_limiter.rs
• MUST:
  • token-bucket Limits auf global, agent, tool Ebene.
  • Bei Limit wird retry_after_ms zurückgegeben.

Env Overrides (optional):

• LEAN_CTX_RATE_LIMIT_GLOBAL_PER_MIN (alias: LCTX_RATE_LIMIT_GLOBAL_PER_MIN)
• LEAN_CTX_RATE_LIMIT_AGENT_PER_MIN (alias: LCTX_RATE_LIMIT_AGENT_PER_MIN)
• LEAN_CTX_RATE_LIMIT_TOOL_PER_MIN (alias: LCTX_RATE_LIMIT_TOOL_PER_MIN)

Tool Surface

ctx_agent

• Runtime: rust/src/tools/ctx_agent.rs
• Dispatcher: rust/src/server/dispatch/session_tools.rs

Post (Messages):

• action=post
• Optional: privacy=public|team|private, priority=low|normal|high|critical, ttl_hours=<u64>
• privacy=private erfordert to_agent.

Read:

• action=read liest nur project-scoped, privacy‑enforced unread Messages.

Export (A2A Snapshot v1):

• action=export
• format=text|json (default: json)
• write=true schreibt .lean-ctx/proofs/a2a-snapshot-v1_<ts>.json
• privacy=redacted|full
  • full ist nur möglich, wenn Redaction für die aktive Role deaktiviert ist (Admin‑Semantik).

ctx_task

• Runtime: rust/src/tools/ctx_task.rs
• Actions: create|update|list|get|cancel|message|info

Export Artefakte & Evidence

• Artefakt: .lean-ctx/proofs/a2a-snapshot-v1_<ts>.json
• Evidence ledger key: proof:a2a-snapshot-v1
• Redaction: Exports sind standardmäßig redacted.

Selektives Routing (Phase 1)

• TopicFilter: Agents können Events nach kinds, actors, min_consistency, und agent_id filtern.
• Directed Events: Events mit target_agents sind nur für gelistete Agents sichtbar.
• Filtered Subscriptions: subscribe_filtered() liefert nur passende Events (spart Tokens).
• Runtime: rust/src/core/context_os/context_bus.rs (TopicFilter, FilteredSubscription)
• Poll-Endpoint: ctx_agent(action=poll_events) — cursor-basiertes Polling mit Filtern.

Transport Layer (Phase 2)

• TransportEnvelopeV1: Versioniertes, signiertes Wrapper-Format für Cross-Machine Transport.
  • HMAC-SHA256 Signatur für Integrität
  • AgentIdentityV1 mit daemon_fingerprint
  • Content Types: handoff_bundle, context_package, a2a_message, a2a_task
• Runtime: rust/src/core/a2a_transport.rs
• CLI: lean-ctx pack send/receive für file- und HTTP-basiertes Senden/Empfangen.
• HTTP Endpoints:
  • POST /v1/a2a/handoff — Empfängt TransportEnvelope
  • GET /v1/a2a/agent-card — Agent Card für Discovery
  • GET /.well-known/agent.json — Standard-Pfad (A2A v1.0)
  • POST /a2a — JSON-RPC 2.0 Endpoint

Google A2A Kompatibilität (Phase 3)

• Agent Card v1.0: Publiziert unter /.well-known/agent.json mit provider, documentationUrl, skills mit inputModes/outputModes.
• JSON-RPC 2.0: tasks/send, tasks/get, tasks/cancel gemapped auf interne TaskStore.
• Runtime: rust/src/core/a2a/a2a_compat.rs

Security & Privacy

• Redaction‑Pipeline gilt für alle Exports/Proof‑Artefakte.
• A2A Snapshot ist bounded (agents/messages/tasks/diary capped) und project-scoped.
• TransportEnvelope unterstützt HMAC-SHA256 Signatur für Integrität.
• Private Messages erfordern to_agent (keine private broadcasts).
• Directed Events sind nur für gelistete Agents sichtbar.