Relationships
#4606 Swampify: candidate set and comparison contracts in @swamp/agent-sessions
Opened by skunk-ape · 11/10/2026· Shipped 11/10/2026
Part of Swampify onboarding. Builds on agent sessions (#4154, #4178, #4156, #4157, #4158).
A new user who already has Claude Code or Codex history can start from it instead of typing a task. Their agent assesses those sessions, offers three to five repeated chores worth automating, builds the one the user picks, and reports what that chore cost raw against what it costs with swamp. Swamp hosts no model: the mining is deterministic, and every judgement call is made by the user's own agent.
Later issues add:
- an
assessmethod that writes a candidate set; - a
comparemethod that writes comparisons; - a Swampify skill shipped with the extension;
- a
swamp startoption that launches that skill; - a read-only dashboard panel in core.
This issue defines the two data contracts they all share. The extension owns them, which reverses how the session record works.
Repo: swamp-extensions (@swamp/agent-sessions).
Goal
Add versioned, strict schemas for a candidate set and a comparison to @swamp/agent-sessions, with a reader that never throws, generated JSON Schema, and a design doc.
Candidate set (SwampifyCandidateSet v1)
One data item per assessment run, of type swampify-candidates. Re-running writes a new version of the same item.
- Run:
schemaVersion;generatedAt;importerVersion;- the window (
since,until); - the scope: harnesses read, directories included and excluded.
- Candidates, each with:
- a stable
id: a hash of its kind and normalised key, so a re-run keeps ids; kind:prompt-repeat,call-sequence,covered-cliorheadless-job;invocation:interactiveorheadless;- a deterministic
label; - counts: occurrences, sessions, directories;
firstSeen,lastSeen;- per-occurrence cost as ranges (min / median / max): tokens (input, output, cache read, cache write), tool calls, active time;
- failure rate;
- the session ids it was seen in, bounded;
- for
call-sequence, the normalised steps; forcovered-cli, the program; - short evidence excerpts, bounded and redacted.
- a stable
Comparison (SwampifyComparison v1)
One data item per candidate that was swamped, of type swampify-comparison, named from the candidate id.
- the candidate id;
- the target:
behaviororworkflow, and its name; - build cost: tokens and active time of the session that built it;
- history: past occurrences, with per-occurrence cost as a range. The low end counts the chore's own calls only; the high end counts the whole turns that contained it;
- swamp run: wall-clock, model tokens, outcome;
- forward: since when, occurrences still done raw, occurrences done through the behavior or workflow, and per-occurrence cost of each;
- break-even: the occurrences needed to recover the build cost.
Tokens are the primary unit. Any money figure is optional and labelled an estimate. Replay of a past occurrence is out of scope for v1.
Rules
Follow the session record's conventions (AGENT_SESSION_LIMITS, readAgentSessionRecord):
- Every object is strict.
- Every string and list is bounded, with a cap on candidates per set.
- The reader never throws. It reports a record as
newer,olderorinvalid, naming field paths, never values. - A new field is a new version.
- Tags carry what a list needs without loading the body (
generatedAt, a compact summary), asagentSessionTagsdoes.
Privacy
Session records stay prompt-free, as #4156 decided. A candidate set is a separate item. It does keep short excerpts from transcripts (prompts that repeat) as evidence, run through the importer's existing redaction. The README and skill say so plainly. Where the data then goes (local, a datastore, swamp serve) is the user's choice, as for any repo data.
Design doc
swampify.md in the extension:
- the journey;
- both contracts;
- what is read from the machine and what is stored;
- how core's dashboard panel reads v1. Core keeps a copy of the JSON Schema with a drift test, mirroring how the extension copies the session record today.
Out of scope
The mining, the comparison maths, the skill, swamp start, and the core panel. Each has its own issue.
Done when
- Zod schemas and generated JSON Schema are checked in to the extension, and a test fails when they drift.
- The reader has unit tests for each skip reason.
- Property tests cover round-trips and the bounds.
swampify.mdis written.
Shipped
Click a lifecycle step above to view its details.
system commented 11/10/2026, 7:48:17 PM
Classified automatically when this issue was filed.
- Source: Extensions
If you feel this classification is incorrect, add a ripple to tell us so.
Sign in to post a ripple.