Schnittstellen

Prinzipien #

1. Dateien für die Datenebene, Tools für die Steuerungsebene. Bytes laufen über Mounts, Git und S3; Autorisierung, Freigabe, Gedächtnis, Suche und Erklärung laufen über MCP, HTTP und eine CLI.
2. Gateways sind zustandslos. Autorisiert wird an genau einer Stelle in der Trust-Schicht.
3. Jede Schnittstelle ist eine Projektion. Unterschiede in der Semantik werden durch ausdrückliche Fehlerabbildungen ausgedrückt (zum Beispiel wird „Gate ausstehend“ auf ein EACCES mit einer erklärenden Datei abgebildet), und bei S3 wird nicht so getan, als gäbe es Branches.
4. Eine schmale Tool-Oberfläche. Höchstens 10 MCP-Tools richten sich an Agenten; Aktionen für Menschen und Betreiber liegen in einer eigenen Betreiberschnittstelle.
5. Adapter isolieren Protokolländerungen. Versionswechsel bei MCP und A2A betreffen nur die Adapter.

Schnittstellenmatrix #

Die MCP-Tool-Oberfläche #

Nur neun Tools richten sich an Agenten:

Mount-Semantik #

• Ein Mount bindet einen Branch und eine Lease; läuft die Lease ab, wird der Mount schreibgeschützt und danach ausgehängt.
• Automatische Commits (entprellt, zum Beispiel nach 5 ruhigen Sekunden); fsync löst einen Commit aus.
• Pfade außerhalb der Lease erscheinen nicht in Verzeichnislisten: Das verringert das Durchsickern von Informationen und verkleinert die Angriffsfläche für Prompt Injection.
• Sandbox-freundlich: kein Root nötig; FUSE oder NFS, eines von beiden, ohne Kernelmodul; schreibgeschützte Mounts sind möglich.

Git #

• Run-Branches heißen <role>/<run_id>; main ist geschützt, und ein serverseitiger pre-receive-Hook lehnt direkte Pushes ab.
• nas propose erstellt einen Agent PR.
• Commits tragen automatisch Trailer wie Run:, Lease: und Principal:.

S3 #

• Ein Bucket entspricht einer Branch-Ansicht eines Trees; die Versions-ID eines Objekts ist ein Commit.
• Semantik, die S3 fehlt, etwa Branches, wird über ein Bucket-Präfix oder einen Request-Header (x-nas-branch) ausgedrückt. Das ist eine abgeschwächte Projektion: Datenpipelines können lesen und schreiben, bekommen aber nicht die volle Branch-Erfahrung.
• Leases werden als temporäre Zugangsdaten im STS-Stil übergeben.

A2A (optional) #

• Eingehende Aufgaben landen als Aufgabendateien in inbox/; Ergebnisse kommen nach outbox/.
• Die Agent Card erklärt die Skills der Rolle und die Leases, die sie braucht.
• Das NAS ist kein A2A-Teilnehmer; teilnehmen tut die Laufzeitumgebung, die für die Rolle handelt. Das NAS speichert nur Aufgaben und Ergebnisse, Übergabepakete und Leases.

Konventionen der HTTP-API #

• **Jeder Endpunkt nutzt POST, mit Parametern in einem JSON-Body;** Antwortfelder sind immer snake_case.
• Pfade sind versioniert: /v1/....
• Idempotenz: Schreiboperationen akzeptieren einen idempotency_key.
• Paginierung: cursor plus limit.
• Budgets und Ratenlimits werden in Antwort-Headern zurückgemeldet (verbleibende Bytes, verbleibende Anfragen), damit sich Laufzeitumgebungen selbst drosseln können.

Eine budgetierte Leseanfrage und ihre Antwort sehen ungefähr so aus:

POST /v1/files/read
{ "path": "/agents/cleo/memory/notes/customer-acme.md",
  "view": "outline", "budget_tokens": 400 }

200 OK
{ "view": "outline", "tokens": 212, "generated": false, "truncated": false,
  "content": "# Acme\n## Renewal (L12-L18)\n## Contacts (L19-L31)\n## Open issues (L32-L40)",
  "evidence": [
    { "pointer": "nas://home-box/agents/cleo/memory/notes/customer-acme.md@9f2c1de#L1-L40" }
  ] }

Fehler haben eine einheitliche Struktur:

{
  "error": {
    "code": "gate_required",
    "message": "This merge requires human approval.",
    "retryable": false,
    "request_id": "req_01JB7W2X4N",
    "details": { "gate_id": "gt_2Mx4" }
  }
}

Auffindbarkeit #

• Die maschinenlesbaren Einstiegspunkte entsprechen denen dieser Website: /.well-known/ai-catalog.json, die MCP Server Card und llms.txt.
• Ein Endpunkt, der nas://-Belegzeiger auflöst und prüft.
• MCP server/discover.