Relationships
#4650 Swampify: contracts move into core and are revised for their readers (candidate set v2, offer v1, comparison v2)
Opened by skunk-ape · 11/11/2026· Shipped 11/11/2026
Part of Swampify onboarding. This must ship before #4642 (the skill) and #4643 (the dashboard panel) go further.
Repo: swamp (core).
Why
#4606 put the Swampify contracts in @swamp/agent-sessions and designed them from the writer's side. Triage of #4642 and #4643 showed that their readers can't use them without workarounds:
- The list can't be opened. The list select gives no owning behavior, and
data.getneeds one. - No rule for several sets. Nothing says which item a reader shows when there are several.
- The ranking figure isn't stored. The figure
assessranks by isn't in the data, so a reader would have to recompute it. - The pick has nowhere to live. It would ride in message text.
- Core copies the wrong way. Core would keep a copy of a module another repo owns, guarded by a drift test and a pinned hash.
The session record already works the other way round: core owns the contract (src/domain/agent_sessions/session_record.ts), and the extension copies it. Swampify follows the same pattern.
Goal
Swampify's contracts move into core and are revised before anything else reads them:
- candidate set v2;
- comparison v2;
- a new offer item, v1.
The dashboard imports them through packages/dashboard/src/lib/agent_sessions/, the same door the record uses. The extension copies them, which is a separate issue. The mining, the skill and the extension's methods stay in the extension.
Module
- Location.
src/domain/agent_sessions/swampify.ts, besidesession_record.ts. It imports nothing but zod and uses no Deno or Node APIs, so the dashboard can bundle it. - JSON Schemas. Generate them into
design/surfaces/beside the record's, with a script likescripts/generate_agent_session_schema.ts. A test fails when any of them drifts. - The record's rules apply to every item:
- every object is strict;
- every string and list is bounded;
schemaVersionis on every item;- a new field is a new version;
- each item has a reader that never throws and returns the item or a skip (
newer,olderorinvalid), whose note names field paths, never values; - tags carry what a list needs, and each summary tag has its own reader.
- Starting point. Begin from the extension's current module (
agent-sessions/extensions/models/_lib/contract/swampify.ts, written for #4606) and its tests, then apply the changes below.
Changes from the extension's v1
Every list. The list select includes the owner, {"name": name, "modelName": modelName, "tags": tags}, as AGENT_SESSION_LIST_SELECT does.
Which item a reader shows. A reader shows the newest item by generatedAt (or updatedAt for an offer) and names the behavior that owns it. By convention, Swampify writes through one behavior called swampify, which swamp start creates. Write this rule into the contract's doc so every reader applies it the same way.
Candidate set v2. v1 is read as older, and running assess again rebuilds the set, so nothing needs migrating.
- Per-occurrence cost adds a weighted-tokens range: input + output + cache writes + a tenth of cache reads. This is the figure
assessalready ranks by. - Each candidate adds its
scoreand itsrank, so a reader can show the ranking without recomputing it. - The summary tag adds
thin(a boolean), so a list can say a set is thin without opening it.
Offer v1 (new). One item per assessment, named swampify-offer, with the type tag swampify-offer. The skill writes a new version of it at each step, through an extension method, so every write passes the schema.
- Header:
schemaVersion,createdAt,updatedAt,writerVersion;- the candidate set it was built from: its
generatedAt, with the same owner.
reading:- the harness that read the example sessions:
claude-codeorcodex, as session records name them; - the model the user chose, a bounded string;
- how many candidates and sessions were read.
- the harness that read the example sessions:
options: one to five, each with:- an
id, stable across versions of this offer; - the agent's
nameand a one-linewhy; becomes:behaviororworkflow;- an optional
registryType; - an optional outline of at most 8 short steps;
candidateIds: one or more, since merged candidates are one option.
- an
considered: candidates read and not offered, each with a reason (not-a-chore,mergedorlow-value), bounded.stateisoffered,picked,builtordeclined:pickedcarries the option id and when it was picked;builtadds the target (behaviororworkflow, and its name) and when it was built;declinedmeans the user picked nothing.
- Rules only Zod checks:
- option ids and candidate ids are unique within the offer;
pickedandbuiltname an option that exists;builtimpliespicked.
- Tags:
updatedAt, plus a summary of the state, the option count, the picked option id and the target.
Comparison v2. No writer ever wrote v1.
- It is keyed by the offer option, not a single candidate, because an option can stand for several merged candidates. It carries
optionIdandcandidateIds, and is namedswampify-comparison-<option id>. - Everything else stays as in v1: target, build cost, history ranges (the chore's own calls up to whole turns), swamp run, forward, break-even, and an optional labelled money estimate.
- Its history is summed over all of the option's candidates.
Dashboard door
- Export the names the panel needs from
packages/dashboard/src/lib/agent_sessions/(a newswampify.tsbesiderecord.ts), and extenddashboard_core_import_rules_test.tsto pin it. - No panel UI here. That is #4643.
Design doc
Add a Swampify section to design/surfaces/agent-sessions.md, or a sibling swampify.md in design/surfaces/:
- the journey in brief;
- the three items, what each holds, and who writes it;
- the rule for which item a reader shows;
- what is read from the machine and what is stored. Candidate sets and offers hold short redacted excerpts and agent-written names, while session records stay prompt-free. Where the data goes is the user's choice.
Out of scope
- The extension adopting the contract (a separate issue).
- The skill (#4642), the panel (#4643),
swamp startandcompare.
Done when
- The module, the generated JSON Schemas and their drift test are checked in.
- Unit tests cover every skip reason for each reader and each summary reader, and every rule only Zod checks.
- Property tests cover round-trips and bounds for all three items.
- The dashboard door exports the names, and the import rule is extended.
- The design doc section is written.
Shipped
Click a lifecycle step above to view its details.
Sign in to post a ripple.