Skip to main content
← Back to list
01Issue
FeatureShippedSwamp CLIPublic
Assigneesskunk-ape

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.get needs 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 assess ranks 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, beside session_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 like scripts/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;
    • schemaVersion is 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, older or invalid), 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 assess already ranks by.
  • Each candidate adds its score and its rank, 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-code or codex, as session records name them;
    • the model the user chose, a bounded string;
    • how many candidates and sessions were read.
  • options: one to five, each with:
    • an id, stable across versions of this offer;
    • the agent's name and a one-line why;
    • becomes: behavior or workflow;
    • an optional registryType;
    • an optional outline of at most 8 short steps;
    • candidateIds: one or more, since merged candidates are one option.
  • considered: candidates read and not offered, each with a reason (not-a-chore, merged or low-value), bounded.
  • state is offered, picked, built or declined:
    • picked carries the option id and when it was picked;
    • built adds the target (behavior or workflow, and its name) and when it was built;
    • declined means the user picked nothing.
  • Rules only Zod checks:
    • option ids and candidate ids are unique within the offer;
    • picked and built name an option that exists;
    • built implies picked.
  • 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 optionId and candidateIds, and is named swampify-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 new swampify.ts beside record.ts), and extend dashboard_core_import_rules_test.ts to 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 start and compare.

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.
02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 5 MOREREVIEW+ 8 MOREPR_LINKED+ 2 MORESESSION_SUMMARIZED

Shipped

11/11/2026, 6:53:41 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
skunk-ape assigned skunk-ape11/11/2026, 5:44:37 PM

Sign in to post a ripple.