Relationships
#4642 Swampify: @swamp/agent-sessions adopts core's contracts, and its skill reads past sessions with the user's chosen model, records the offer and pick, hands the pick to getting-started
Opened by skunk-ape · 11/11/2026· Shipped 11/11/2026
Part of Swampify onboarding. Depends on #4650, which moves the Swampify contracts into swamp core (src/domain/agent_sessions/swampify.ts): candidate set v2, offer v1 and comparison v2. This issue also covers the extension's adoption of those contracts, which was #4651.
Repo: swamp-extensions (@swamp/agent-sessions, and @swamp/agent-runner for the two arguments below).
Goal
Ship a Swampify skill with @swamp/agent-sessions. It turns a candidate set into one thing the user actually automates. The skill runs import and assess, has a model the user picks read the top candidates, offers three to five, records the offer and the pick in the data, and hands the pick to getting-started's existing create, run and inspect steps.
Swamp still hosts no model. Every judgement call is made by the user's own agent, on the user's own harness and login.
First: adopt core's contracts
@swamp/agent-sessions stops owning the Swampify contracts and copies core's, the same way it already copies the agent session record.
- Replace the owned contract. Swap
extensions/models/_lib/contract/swampify.ts, its generator and its four JSON Schemas for a copy of core's module and core's checked-in JSON Schemas.- The copy changes only its zod import specifier.
- A test fails when the copy disagrees with the copied JSON Schemas, as the session record copy's test does.
- Remove
deno task swampify-schema.
assesswrites v2. Fill the weighted-tokens range per occurrence and each candidate'sscoreandrank, whichrank.tsalready computes, and addthinto the summary tag. Ids and ranking stay as they are.- Cut down
swampify.md. Keep only what the extension does: howassessmines, what it reads, and the thin and registry rules. Point to core's design doc for the contracts. - Bump the model version with an upgrade entry. An existing v1 set reads as
older, and runningassessagain rebuilds it.
Where it runs
swamp start bootstraps Swampify in a later core issue. It creates the swampify workspace, pulls @swamp/agent-sessions (which installs this skill), creates the swampify behavior, writes an assess brief and launches the user's chosen harness, Claude Code or Codex.
So the skill assumes it runs in a swamp repo with the extension pulled. It makes no workspace offer and has no fresh-directory path. An extension's skills install only on pull, so a fresh directory couldn't reach it anyway.
Where it lives
- The skill. A new skill beside the existing
agent-sessionsskill, listed underskillsin the manifest, e.g..claude/skills/swampify/SKILL.md. Each skill points to the other. - An
offermethod on@swamp/agent-sessions. It writes the offer item (offer v1). Each call writes a new version ofswampify-offer, checked against the schema. The skill never writes the item by hand and never carries ids in message text. - A shipped workflow for the reading. For example
@swamp/agent-sessions/swampify-understand, with@swamp/agent-runneras a dependency.
Entry points
- An
assessbrief. Atasks/<date>-<slug>.mdfile whose<!-- swamp start brief v1 -->header haskind: assess, with the window and scope. The skill reads it and skips the scope questions. - Asked directly in a repo that has the extension, e.g. "what should I automate?", "what should I swamp?", "swampify my sessions".
States
disclosed. Before reading anything, say what is read and what is stored:assessreads transcript text, prompts and replies included, on this machine;- it stores counts, costs and short redacted excerpts;
- the offer stores the agent's names and verdicts;
- session records stay prompt-free;
- where the repo's data goes after that is the user's choice.
Then confirm the window and scope, unless the brief already gives them.
assessed. Runimportand thenassessthrough theswampifybehavior. Read the set with the contract's reader.- Empty set: say so, and offer a typed first task through getting-started.
- Thin set (the summary's
thin): say so, and offer to widen the window before going on.
understood. Ask the user which harness reads the example sessions, Claude Code or Codex (the two whose sessions are supported), and which model. Default to the harness this session runs on, with a cheaper model offered.- Tell the user how many sessions will be read: about 10 candidates, the 3 latest
sessionRefseach. Ask before going on. - The workflow runs one
@swamp/agent-runnerrunper candidate, read-only, with only read tools allowed and the transcript roots added. It finds a transcript by session id under~/.claude/projectsor Codex's sessions directory. - Each run returns a structured verdict and never transcript text: is it a chore, merge with which candidates, a name, a one-line why, what it becomes (behavior or workflow), an optional registry type, and an optional outline.
- If the chosen harness can't run, the main agent reads with the same caps and returns the same verdicts.
- Tell the user how many sessions will be read: about 10 candidates, the 3 latest
offered. Merge and filter by the verdicts, then show three to five options, fewer if fewer survive. Each option shows:- its name, and what it would become;
- how often it happened: occurrences, sessions, first and last seen;
- its median weighted tokens per occurrence, its tool calls and its failure rate, as
assessmeasured them; - one or two redacted excerpts.
Tokens are the unit. Money, if shown, is labelled an estimate. Write the offer (
state: offered), with the reading harness, the model, the options and the candidates considered but not offered.option_picked. When the user picks an option, write the offer again withstate: picked, then hand off to getting-started at its create step, with the option's evidence as the task. If the user picks nothing, writestate: declinedand stop.built. After getting-started's first run, writestate: builtwith the target (behaviororworkflow, and its name).graduated. Offer the next option from the same offer, or stop.
A compared state comes with compare. Leave room for it in the checklist, but don't add it here.
@swamp/agent-runner
Add two optional run arguments, with their own version bump:
outputSchema(Claude Code's--json-schema, or Codex's equivalent), so verdicts come back structured;persistSession: false, so a reading leaves no session behind that would show up in the nextimportorassess.
Rules
- Never paste transcript text beyond the redacted excerpts the candidate set holds, and never write it to files in the repo.
- Name the commands the skill runs.
Out of scope
swamp startbootstrap (core).- The panel (#4643).
compareand thecomparedstate.- Replay and telemetry.
Done when
- The contract copy and its drift test are checked in, and the owned module and its generator are gone. The
assesstests and golden output are updated for v2, and the property tests still hold. - The skill passes
tessl reviewat 90% or above. - Trigger and routing evals pass. The skill doesn't take "import my sessions" from
agent-sessions, or "getting started" from core's getting-started skill. - Unit tests cover the
offermethod's validation and its state moves, and the workflow's verdict parsing, including one retry on a verdict that doesn't parse. - Until
swamp startbootstraps it, a manual run in a repo prepared by hand works end to end, with both Claude Code and Codex as the reading harness. The repo is prepared by creating the workspace, pulling the extension and creating theswampifybehavior. The run goes from "what should I automate?" to a built behavior or workflow, with the offer item reachingbuilt. The implementer checks this locally, and no transcript content goes in the PR.
Shipped
Click a lifecycle step above to view its details.
system commented 11/11/2026, 3:14:22 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.