Das sind die Record-Channel-Tools, die eine Codex-CLI-Verbindung von osFoundry bekommt, so wie der öffentliche MCP-Endpoint sie auflistet. Abgerufen wurden sie am 2026-11-09 mit einem nicht authentifizierten tools/list und auf die Felder gekürzt, um die es hier geht:
{"name": "list_record_items",
"description": "List the schema and a bounded page of item previews from one granted record channel. Use read_record_item for the complete values.",
"inputSchema": {"required": ["record_channel_id"],
"properties": {"record_channel_id": {"type": "string"}, "before_id": {"type": "string"},
"limit": {"type": "integer", "minimum": 1, "maximum": 50}}},
"annotations": {"readOnlyHint": true}}
{"name": "read_record_item",
"description": "Read one item by ID from a granted record channel and return its current version.",
"inputSchema": {"required": ["record_channel_id", "item_id"]}}
{"name": "edit_record_item",
"description": "Update validated fields in one record item. Supply the version from read_record_item; concurrent changes are rejected.",
"inputSchema": {"required": ["record_channel_id", "item_id", "values", "expected_version", "idempotency_key"],
"properties": {"values": {"type": "object"}}},
"annotations": {"readOnlyHint": false, "destructiveHint": true},
"securitySchemes": [{"type": "oauth2", "scopes": ["osfoundry:write"]}]}
Man beachte values. Das ist {"type": "object"} und sonst nichts. Das Tool-Schema kann nicht sagen, welche Keys ein Channel hat, welche davon Select-Felder sind oder was in Points stehen darf, denn das unterscheidet sich von Channel zu Channel und ändert sich, sobald jemand den Schema-Tab bearbeitet. Erfahren kann Codex das nur aus der ersten Zeile der Beschreibung des List-Tools: Das Schema kommt mit der Seite zurück. Der Rest dieses Posts misst an einem Nachbau, was das bringt, und dazu zwei weitere Entscheidungen in denselben vier Tools: einen before_id-Cursor statt eines Offsets und ein Event-Log, zu dem man zurückkehren kann.
Was ist ein gültiger Wert?
Die Feldtypen sind fest. packages/shared/src/types/record.ts im osFoundry-Frontend definiert RecordChannelFieldType mit 16 Typen: text, number, date, boolean, email, phone, url, select, multi_select, currency, percentage, rating, relation, file, json und formula. Jedes Feld hat is_required, is_unique und eine typspezifische config: max_length für text, min/max für number, max_stars für rating, options für die beiden Select-Typen, expression für formula.
Select ist der Typ, über den Agenten stolpern. Eine Option ist {value, label, color}. Gespeichert wird der Value, das Label sehen die Leute. RecordDataGrid.tsx rendert eine Select-Zelle mit options.find((o) => o.value === params.value) und fällt auf String(params.value) in einem gedämpften Chip zurück, wenn nichts passt. Würde eine nachsichtige Prüfung also "In progress" in ein Feld lassen, dessen Wert in_progress ist, zeigte das Grid etwas, das richtig aussieht und falsch ist: keine Farbe, und unsichtbar für alles, was nach Wert gruppiert oder filtert. Ein Modell, das nur die Labels im Grid oder die Nachricht einer Person gesehen hat, wird Labels schicken. Irgendwer muss Nein sagen.
Wie sollte eine Ablehnung aussehen?
Die Record-API von osFoundry beantwortet einen fehlgeschlagenen Aufruf mit {ok: false, error: {message}}. Die eigenen Record-Tools der Desktop-App für In-App-Agenten (src-tauri/src/record_tools.rs) reichen diese Nachricht unverändert an das Modell weiter, und der Kommentar sagt, warum: Die Nachricht der API "names the field that failed validation, which is usually enough for a self-correcting retry." Der Unit-Test nutzt values.status is not a valid option als Beispiel.
"Usually enough" lässt sich messen. Der Nachbau probiert vier Detailstufen in einer Ablehnung aus:
- terse:
{"error": "validation_failed"} - field: welche Keys fehlgeschlagen sind
- values: Keys, Grund und die erlaubten Optionswerte oder der Bereich
- labels: dasselbe, plus das Label jeder Option
Hier die Stufe "values", wörtlich aus dem Lauf:
{"error": "validation_failed", "fields": [
{"key": "status", "message": "values.status must be one of the option values, got \"In progress\"",
"allowed": ["new", "triaged", "in_progress", "fixed", "wont_fix"]},
{"key": "owner", "message": "values.owner must be one of the option values, got \"Aiko\"",
"allowed": ["aiko", "mika", "ren"]},
{"key": "points", "message": "values.points must be between 0 and 13, got 20", "min": 0, "max": 13},
{"key": "due", "message": "values.due must be a date as YYYY-MM-DD, got \"Friday\""},
{"key": "age_days", "message": "values.age_days is a formula field and is computed, not written"}]}
Diese Strings stammen aus dem Nachbau. Nur die Benennung values.<key> folgt osFoundry.
Der Nachbau
Hier läuft kein Codex-Binary. record_store.py implementiert list_record_items, read_record_item, edit_record_item und poll_resource_events auf In-Memory-sqlite, mit denselben Tool-Namen, Argumentnamen und Limits wie live. Die Feldtypen und Config-Keys kommen aus record.ts. Die Preview-Länge (120 Zeichen), die Form der Ergebnisse und jede Validierungsregel sind Eigenbau. Ein Edit läuft in BEGIN IMMEDIATE: Idempotenz-Lookup, Versionsvergleich, Validierung, Merge, Versionserhöhung, Event-Append, Commit. Jedes Problem rollt den gesamten Edit zurück.
triage.py ist ein geskripteter Codex. Er arbeitet auf einem Bugtracker mit 11 Feldern (Beispiel: ticket, title, description, status, owner, severity, points, area, due, reporter, age_days), 200 New-Items pro Lauf, Seeds 1–5. Jedes Item bekommt eine Triage-Absicht in den Worten einer Person: "In progress", "Aiko", "S2 Major" oder nur "major", Points aus {1, 2, 3, 5, 8, 13, 20}, due "Friday" oder ein ISO-Datum, eine Area. Der Agent schickt die Worte entweder so, wie sie sind, oder mappt sie vorher über das Schema, indem er Labels Values zuordnet. Bei einer Ablehnung korrigiert er, was die Ablehnung korrigieren lässt, lässt weg, was er nicht korrigieren kann, und markiert dieses Feld für eine Person. Eine Zahl kappt er nie. Python 3.9.6, Apple M1.
Spielt das Schema in der Seite eine Rolle?
1,000 Items, je 6 beabsichtigte Felder:
| Agent hat das Schema gelesen | Ablehnung sagt | Gespeicherte Felder (von 6,000) | Bleibt für eine Person | Edit-Aufrufe pro Item |
|---|---|---|---|---|
| nein | nichts | 1,363 (22.7%) | 4,637 | 7.00 |
| nein | welches Feld | 1,363 (22.7%) | 4,637 | 2.00 |
| nein | Feld, Grund, erlaubte Werte | 5,361 (89.3%) | 639 | 2.00 |
| nein | Feld, Grund, Werte und Labels | 5,857 (97.6%) | 143 | 2.00 |
| ja | nichts | 5,857 (97.6%) | 143 | 1.86 |
| ja | welches Feld | 5,857 (97.6%) | 143 | 1.14 |
| ja | Werte, oder Werte und Labels | 5,857 (97.6%) | 143 | 1.14 |
97.6% ist die Obergrenze. Die übrigen 143 sind die Items, bei denen die Person 20 Points gesagt hat und das Feld bei 13 endet. Die sollen abgelehnt werden, und das wurden sie in jeder Zeile.
Ein Agent, der das Schema gelesen hatte, erreichte die Obergrenze, egal was die Ablehnung sagte. Sein erster Edit scheiterte nur an den 143 Points außerhalb des Bereichs. Ohne Schema scheiterte jeder erste Edit: status, owner, severity und area waren Labels, und die Hälfte der due-Daten war "Friday". Ab da hängt die Erholung komplett vom Fehler ab. "Welches Feld" nützt ohne die erlaubten Werte nichts: Der Agent weiß, dass status falsch ist, aber nicht, was richtig ist, also lässt er es weg. Erlaubte Werte ohne Labels kommen auf 89.3%. Die 639 Fehlschläge sind "Won't fix" gegen wont_fix und "major" gegen s2. Beides lässt sich aus einer Werteliste nicht zuordnen. Mit Labels in der Ablehnung holt der Agent ohne Schema auf, mit einem zusätzlichen Aufruf pro Item. Ein knapper Fehler ohne Schema brachte den Agenten dazu, jeden Edit in sechs Ein-Feld-Edits aufzuteilen, 7 Aufrufe pro Item, und trotzdem speicherte er weniger als ein Viertel.
Das Schema ist also die Hälfte des Validierungsdesigns. Die Prüfung auf dem Server hält schlechte Werte auf. Das Schema, das mit jeder Seite mitfährt, sorgt dafür, dass der erste Versuch stimmt. Es kostet in diesem Channel 1,705 Bytes pro Seite, etwa 10% einer 16.7-KiB-Seite mit 50 Previews.
Warum Previews, und warum höchstens 50?
Eine Seite mit 50 Previews hatte 16.7 KiB. Diese 50 Items komplett zu lesen waren 124.6 KiB, weil die Beschreibungen hier 300–4,000 Zeichen lang sind. Für die Triage reicht eine Preview, um zu entscheiden, was man öffnet: der Status, das Ticket, der Anfang des Titels. Codex öffnet die, die es ändern wird. Eine begrenzte Seite verhindert außerdem, dass ein großer Channel den Kontext flutet. Die Tool-Beschreibung sagt "bounded", und das Schema sagt maximum: 50.
Warum before_id statt eines Offsets?
Während Codex liest, legen Leute weiter Bugs an. Der Nachbau blättert 600 Items in 50er-Schritten durch, neueste zuerst, und ändert den Channel nach jeder Seite. Fünf Läufe:
| Änderung nach jeder Seite | Paging | Seiten | Item-Lesevorgänge | Doppelt gelesen | Nie gesehen |
|---|---|---|---|---|---|
| 2 neue Bugs angelegt | offset | 65 | 3,120 | 120 | 0 |
| 2 neue Bugs angelegt | before_id |
60 | 3,000 | 0 | 0 |
| 2 bereits gelesene Items gelöscht | offset | 60 | 2,890 | 0 | 110 |
| 2 bereits gelesene Items gelöscht | before_id |
60 | 3,000 | 0 | 0 |
Neue Items am Anfang schieben alles nach unten, also überlappen sich Offset-Seiten und Codex triagiert manche Items doppelt. Wird etwas bereits Gelesenes gelöscht, rutscht alles nach oben, und die nächste Offset-Seite beginnt hinter Items, die niemand gelesen hat. 110 Bugs, die von Anfang bis Ende existierten, wurden nie gesehen. Ein Cursor benennt das zuletzt gelesene Item, und ein Insert oder Delete an anderer Stelle kann ihn nicht verschieben. Items, die während des Durchlaufs angelegt werden, tauchen auf keiner Seite auf. Dafür ist das Event-Log da.
Wie findet Codex, was sich seit dem letzten Durchlauf geändert hat?
Nach einem Durchlauf über 400 Items haben Leute 30 Items bearbeitet, 12 angelegt und 3 gelöscht. Zwei Wege, diese 45 zu finden:
| Strategie | Aufrufe | Zurückgegebene Daten | Gefunden |
|---|---|---|---|
| alle Seiten neu auflisten, Versionen vergleichen | 9.0 | 135.8 KiB | 45 von 45 |
poll_resource_events ab der gespeicherten Sequenz |
1.0 | 4.6 KiB | 45 von 45 |
Das Skript prüft per Assert, dass beide genau die 45 gefunden haben. Polling kostet so viel, wie sich geändert hat. Neu auflisten kostet jedes Mal die Größe des Channels. Der Zustand, den man zwischen Läufen aufheben muss, ist ein einziger Integer, die letzte Sequenz.
Und die Versionsprüfung?
Kurz, weil sie genauso funktioniert wie bei Notes und Knowledge Bases. Bei 1,000 Edits, bei denen eine Person 1 von 8 Items zwischen Lesen und Schreiben von Codex verändert hat, ergab eine Version aus dem Lesevorgang 131 Konflikte und überschrieb 0 Änderungen der Person. Die Version direkt vor dem Schreiben neu zu lesen ergab 0 Konflikte und überschrieb alle 131. Nach einem Konflikt liest der geskriptete Codex neu, sieht, dass das Item schon in progress ist, und ergänzt nur noch severity.
Was kostet die Validierung?
2,000 gültige Edits mit sechs Feldern, drei Läufe: Median 72.8–75.1 µs pro Edit mit Validierung, 41.9–42.4 µs mit ausgestubbtem validate(). Der Unterschied sind die Schema-Abfrage und die Prüfungen pro Feld innerhalb der Transaktion. Gegenüber einem Modell-Turn von mehreren Sekunden fällt das nicht ins Gewicht.
Wenn du das selbst verdrahtest
- Gib das Schema mit dem Listing zurück, auf jeder Seite, nicht über einen separaten Aufruf, den der Agent auslassen könnte. Der gemessene Unterschied ist ein abgelehnter Edit pro Item.
- Pack die erlaubten Optionswerte und ihre Labels in die Ablehnung. Mit einem Feldnamen allein kann der Agent nichts reparieren.
- Lehne den ganzen Edit ab, wenn irgendein Feld scheitert, und sag, welche Felder. Ein teilweises Speichern, das Erfolg meldet, versteckt das Feld, das der Agent falsch hatte.
- Wandle auf dem Server nie Labels um und kappe nie Zahlen. "major" und "20 points" sind Fragen für eine Person, nicht für einen Matcher.
- Blättere mit einem Cursor auf einer stabilen ID und gib dem Agenten eine Event-Sequenz für den nächsten Lauf.
- Halte Schemaänderungen, Creates und Deletes aus den Tools des Agenten heraus, bis du sie brauchst. Validierung bedeutet nur etwas, wenn der Agent das Feld nicht erweitern kann.
Die Kurzdefinition des darunterliegenden Protokolls von osFoundry steht in seinem Glossareintrag zu MCP. Den Record-Channel-Screen, aus dem das Schema stammt, gibt es auf der Records-Seite.
Top comments (0)