migrate-waniwani-sdk-0.23-to-0.24
Skill18 starsChanged 8 days agoMITView on GitHub
Migrate a project from @waniwani/sdk 0.23.x to 0.24.x and auto-apply its breaking change to flows: the tool listing no longer names state fields under stateUpdates, `start` merges no stateUpdates, and `continue` and `reset` merge only fields the run has asked through an interrupt question or a widget's `field`. A field the conversation writes without any question asking for it (sent by the model on start, extracted from an opener, sent back by a widget, or a second field filled from one question) is never set. The flow graph moved off the wire, so `flow.config._meta._flowGraph` is gone from the type and from tools/list. Covers computing such fields in a node or asking them with an interrupt, widget group fields, and the createFlowTestHarness `start(intent, known)` change. Trigger when the user is on @waniwani/sdk 0.23.x and wants to move to 0.24 (for 0.25 or later, use migrate-waniwani-sdk-0.24-to-0.25 instead), asks to migrate to 0.24, or after bumping sees any of: a flow asks again for something the user already said, a field the model used to send on start (a locale, a flag inferred from the user's intent) or a value computed on start is never set, a widget's answer is ignored, `reset` returns `Nothing to correct`, a type error on `_meta._flowGraph`, or tests that assert the `stateUpdates` schema or `_meta._flowGraph` in tools/list fail.
In this repository28 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- agent-browserSkill
- copySkill
- deploy-prodSkill
- linear-oneshotSkill
- project-planningSkill
- project-updateSkill
- pull-requestSkill
- wani-code-reviewSkill
- create-flow-appSkill
- frontend-designSkill
- knowledge-baseSkill
- release-migrationSkill
- transfer-to-kitSkill
- translationsSkill
- visualize-flowSkill
- audit-trackingSkill
- instrument-trackingSkill
- migrate-waniwani-sdk-0.15-to-0.16Skill
- migrate-waniwani-sdk-0.16-to-0.17Skill
- migrate-waniwani-sdk-0.17-to-0.18Skill
- migrate-waniwani-sdk-0.18-to-0.19Skill
- migrate-waniwani-sdk-0.19-to-0.20Skill
- migrate-waniwani-sdk-0.22-to-0.23Skill
- migrate-waniwani-sdk-0.24-to-0.25Skill
- migrate-waniwani-sdk-0.25-to-1.0Skill
- waniwani-sdkSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 0 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 91
1a. Compute it in a node: Add an action node right before the first node that reads the field.
- Very specific: line 93
1b. Ask it: Add the field as a question in an interrupt, in a node placed before the first node that reads it.
- Very specific: line 256
tools/listassertions: Read the graph from flow.flowGraph. - Very specific: line 276
Read the graph from the compiled flow, and stop setting the key by hand.
- Very specific: line 288
When you pass your own _meta, spread flow.config._meta into it.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Migrate @waniwani/sdk 0.23 → 0.24
A self-contained migration for the single hop from 0.23.x to 0.24.x. It covers only that jump; for other version boundaries use the matching migrate-waniwani-sdk-<from>-to-<to> skill, or the general procedure in the SDK's changelog.
Precondition: the project is on @waniwani/sdk@0.23.x. If it is on an older version, migrate up to 0.23 first; if it is already on 0.24+, run the procedure anyway, since most of this hop is invisible to tsc and a project can compile on 0.24 while its flows lose answers.
Projects with no createFlow call have nothing to migrate. Bump the dependency, run the completion check, and stop.
What 0.24 changes
In 0.23 a flow tool listed its whole Zod state schema under stateUpdates in tools/list, and any call could write any state field. A model told to "always include locale on start" set it, and so could text injected into the conversation, including fields the flow computes for itself, such as a vehicle id that decides what gets priced.
In 0.24 the listing names no field. Each interrupt or widget response names the fields it asks for, with their fieldSchema. The engine records the fields a run has asked (asked on the session record) and merges stateUpdates only for those. A question on a z.object group accepts every key inside it.
A value sent for a field the run has not asked yet is dropped. When the flow later asks that question, the model answers it from earlier messages with one silent continue, and the user is not asked again.
This skill covers 0.24.0 to 0.24.2. 0.25.0 sends every state field to the model once per conversation, in fields, and writes any declared field again. A project going from 0.23 straight to 0.25 skips this skill and runs migrate-waniwani-sdk-0.24-to-0.25, which covers that jump and does not need rewrites 1 to 3 below.
Breaking, and visible to tsc:
| 0.23 | 0.24 |
flow.config._meta._flowGraph is typed FlowGraph | flow.config._meta is Record<string, unknown>, so reading anything off _flowGraph fails to compile. Read the graph from flow.flowGraph |
Breaking, and not visible to tsc:
| Call | 0.23 | 0.24 |
start with stateUpdates | Merged into state, filled nodes skipped | Ignored |
continue with a field not asked yet | Merged | Dropped |
continue or reset with a field no question or widget ever asks | Merged | Dropped |
A widget's continue carrying keys other than its field | Merged | Dropped |
reset with no asked field | Merged, flow restarts | Error: Nothing to correct: "reset" takes fields the flow has asked for. |
A key that is not a state field is dropped.
Other behavior changes:
tools/list. A flow'sstateUpdatesis an untyped record, the same for every flow. The definition_metastill carries the flow graph and the redacted-fields list forwithWaniwani, wrapped in an object whosetoJSONreturnsundefined, so a serializing transport never sends them. Snapshot tests of the listing change.- Hand-set
_meta._flowGraph.withWaniwanistill reads it and moves it off the wire. It is deprecated. 0.25.0 still reads it. createFlowTestHarness.start(intent, known)no longer sendsknownasstateUpdates. It starts empty, then answers each question whose fieldknownholds with acontinue, until the flow asks somethingknownhas no value for. A value inknownfor a field no question asks is ignored.nextSteptext on interrupts. It now tells the model to answer questions the user already settled. Snapshot tests of it change.- Sessions in flight. A record written by 0.23 has no
asked, so its next call merges everything once. No action.
Untouched: node handlers and their return values (a value a node returns always writes state), the interrupt and showWidget signatures, validators, redacted(), intro, the state schema itself, and widget data.
Procedure
- Bump the dependency.
bun add @waniwani/sdk@^0.24.0 - Collect the call sites.
bun run typecheck rg -n "_flowGraph" --glob '!node_modules' rg -l "createFlow\(" --glob '!node_modules' rg -n "stateUpdates" --glob '!node_modules' rg -n -i "on start|in stateUpdates|always (include|send)|pre-?fill" --glob '!node_modules' rg -n "\.start\(|resetWith\(|listTools\(" --glob '*.test.*' Build a field table for every flow. For each key in
createFlow({ state }), record which of these write it:- an interrupt question (the key appears as
key: { question: ... }inside aninterrupt({ ... })call), - a widget (
showWidget({ field: "key" }), or az.objectgroup the widget'sfieldnames), - a node return value (
return { key: ... }from a node), - the conversation (the flow
descriptionor the field's.describe()tells the model to send it, a question'scontexttells the model to put a value in it, a widget sends it back, or a test sends it instateUpdates).
A field the conversation writes and that has no interrupt question and no widget field is a target. So is a field that only a node return writes but that a test seeds through
stateUpdates.- an interrupt question (the key appears as
- Apply rewrites 1 to 5 below to every target.
- Verify, which is the completion check.
bun run typecheck && bun test - Report each flow's targets, the rewrite applied to each, and whether the app is listed in a reviewed directory (see "Ship it").
Rewrite 1: a field the conversation writes and no question asks
Pick the branch by these checks, in order:
- A node already falls back to another source when the field is empty (
state.locale ?? localeFrom(meta)): use 1a with that source. - The value is a function of other state fields: use 1a.
- Anything else, such as the language the user writes in or a flag inferred from their intent: use 1b.
1a. Compute it in a node. Add an action node right before the first node that reads the field. It returns the field, computed from what the node has (state, meta, a lookup). Make the field .optional() and describe it as set by the flow.
1b. Ask it. Add the field as a question in an interrupt, in a node placed before the first node that reads it. When the model can answer it from the conversation, say so in the question's context.
In both branches, delete the sentence in description or .describe() that tells the model to send the field. A 1b question costs one silent model call when the user already gave the answer.
// Before
const flow = createFlow({
id: "rate_comparison",
title: "Compare electricity rates",
description:
"Compares the user's electricity tariff with current offers. On start, always include locale, transferAllowed and ageBand in stateUpdates.",
state: {
locale: z.enum(["es", "en"]).describe("Language the user writes in. Always send it on start."),
transferAllowed: z
.boolean()
.describe("True if the user is moving home or changing the contract holder"),
birthDate: z.string().describe("Date of birth, YYYY-MM-DD"),
ageBand: z.enum(["under_26", "26_plus"]).describe("Age band, from the birth date"),
},
})
.addNode("ask_birth_date", ({ interrupt }) =>
interrupt({ birthDate: { question: "What is your date of birth?" } }),
)
.addNode("show_offer", ({ state, showWidget }) =>
showWidget({
tool: "show_offer",
data: { locale: state.locale, transferAllowed: state.transferAllowed, ageBand: state.ageBand },
}),
)
.addEdge(START, "ask_birth_date")
.addEdge("ask_birth_date", "show_offer")
.addEdge("show_offer", END)
.compile({ store: new MemoryKvStore() });
// After
function ageBandOf(birthDate: string | undefined): "under_26" | "26_plus" {
const age = new Date().getFullYear() - Number(birthDate?.slice(0, 4));
return age < 26 ? "under_26" : "26_plus";
}
const flow = createFlow({
id: "rate_comparison",
title: "Compare electricity rates",
description: "Compares the user's electricity tariff with current offers.",
state: {
locale: z.enum(["es", "en"]).describe("Language the user writes in"),
transferAllowed: z
.boolean()
.describe("True if the user is moving home or changing the contract holder"),
birthDate: z.string().describe("Date of birth, YYYY-MM-DD"),
ageBand: z.enum(["under_26", "26_plus"]).optional().describe("Age band, set by the flow"),
},
})
.addNode("ask_context", ({ interrupt }) =>
interrupt({
locale: {
question: "Which language is the user writing in?",
context: "Answer from the conversation. Do not ask the user.",
},
transferAllowed: {
question: "Are you moving home or changing the contract holder?",
context: "Answer from the conversation if the user already said it.",
},
}),
)
.addNode("ask_birth_date", ({ interrupt }) =>
interrupt({ birthDate: { question: "What is your date of birth?" } }),
)
.addNode("derive_age_band", ({ state }) => ({ ageBand: ageBandOf(state.birthDate) }))
.addNode("show_offer", ({ state, showWidget }) =>
showWidget({
tool: "show_offer",
data: { locale: state.locale, transferAllowed: state.transferAllowed, ageBand: state.ageBand },
}),
)
.addEdge(START, "ask_context")
.addEdge("ask_context", "ask_birth_date")
.addEdge("ask_birth_date", "derive_age_band")
.addEdge("derive_age_band", "show_offer")
.addEdge("show_offer", END)
.compile({ store: new MemoryKvStore() });locale and transferAllowed take branch 1b. ageBand takes branch 1a, and a call that sends it is now ignored.
Rewrite 2: one question that fills several fields
A question whose context tells the model to split the answer into a second field ("put the last name in lastName") writes a field nothing asks. Add every field it fills as its own question in the same interrupt call. The model still asks them in one message.
// Before
interrupt({
firstName: {
question: "What is your name?",
context: "Put the first name in firstName and the last name in lastName.",
},
})
// After
interrupt({
firstName: { question: "What is your first name?" },
lastName: { question: "And your last name?" },
})Rewrite 3: a widget that sends back values
A widget's continue merges only the widget's field. Give every widget that sends values a field. When it sends more than one value, group them in one z.object state field, name the group as the widget's field, and copy the members out in an action node after the widget.
// Before
state: {
isManualFlow: z.boolean().describe("True when the user skips the upload"),
},
// ...
.addNode("show_upload", ({ showWidget }) => showWidget({ tool: "show_upload_card" }))
// the widget resumes the flow with { isManualFlow: true, uploadStartedAt: 1760000000000 }
// After
state: {
upload: z
.object({
status: z.enum(["uploaded", "manual"]),
startedAt: z.number().optional(),
})
.describe("What the upload card returned"),
isManualFlow: z.boolean().optional().describe("Set by the flow"),
},
// ...
.addNode("show_upload", ({ showWidget }) =>
showWidget({ tool: "show_upload_card", field: "upload" }),
)
.addNode("read_upload", ({ state }) => ({
isManualFlow: state.upload?.status === "manual",
}))
.addEdge("show_upload", "read_upload")
// the widget resumes the flow with { upload: { status: "manual", startedAt: 1760000000000 } }
// or with dot-paths: { "upload.status": "manual" }Update the widget's own code (or the instruction its tool response gives the model) so it sends the group key. A widget with a field is skipped when that field is already filled, so a widget that can show twice in one run needs the node after it to clear the group (upload: undefined).
Rewrite 4: tests
Apply each case that matches.
harness.start(intent, known) with a field no question asks. The value is ignored now. Put the inputs the node computes from in known and let the node run. For a value that comes from a lookup, stub the lookup.
// Before
const result = await harness.start("compare my rates", { birthDate: "2010-05-01", ageBand: "under_26" });
// After
const result = await harness.start("compare my rates", {
locale: "en",
transferAllowed: true,
birthDate: "2010-05-01",
});
expect(result.status).toBe("widget");A raw handler call that sends stateUpdates on start and expects nodes to be skipped. Replace it with harness.start(intent, known), or send one continue per question.
tools/list assertions. Read the graph from flow.flowGraph. Over InMemoryTransport the client receives the server-only wrappers as objects, so round-trip through JSON before asserting what a client would see.
// Before
expect(Object.keys(tool.inputSchema.properties.stateUpdates.properties)).toEqual(["birthDate", "locale"]);
expect(tool._meta._flowGraph.nodes).toHaveLength(4);
// After
const [listed] = JSON.parse(JSON.stringify((await client.listTools()).tools));
expect(listed.inputSchema.properties.stateUpdates.properties).toBeUndefined();
expect(JSON.stringify(listed._meta ?? {})).not.toContain("flowGraph");
expect(flow.flowGraph.nodes).toHaveLength(4);reset before the field was asked. It returns status: "error". Answer the question first, then call resetWith.
Snapshots of nextStep or of the listing. Regenerate them with bun test --update-snapshots and check the diff only touches those strings.
Rewrite 5: _meta._flowGraph
Read the graph from the compiled flow, and stop setting the key by hand. flow.config._meta already carries the graph for withWaniwani.
// Before
const nodes = flow.config._meta._flowGraph.nodes;
server.registerTool(flow.name, { ...flow.config, _meta: { ...flow.config._meta, _flowGraph: flow.flowGraph } }, flow.handler);
// After
const nodes = flow.flowGraph.nodes;
server.registerTool(flow.name, flow.config, flow.handler);When you pass your own _meta, spread flow.config._meta into it. A hand-set _flowGraph still works in 0.25.0, but it is deprecated.
No rewrite: openers that extract everything
A first node that asks one open question and tells the model to fill other fields from the answer keeps working when later nodes ask those fields. Each later node costs one silent continue. Fields in that opener that no later node asks are targets of rewrite 1.
Ship it
The flow tool's listing shrinks: stateUpdates names no field, description or enum value, and _meta sends no graph. A published app keeps working without resubmission, because the server keeps only the asked fields from whatever the old listing makes the model send. A directory that reviews apps (the ChatGPT app directory) shows the tool metadata from your last submission until you submit a new version, so resubmit to show reviewers the smaller listing, which no longer lists personal fields such as ID numbers or birth dates.
Common mistakes
- Asking a computed field with an interrupt. A lookup id or a price must stay unasked, or the conversation can set it again. Use rewrite 1a.
- Leaving "send X on start" in the flow description. The description is the consent card a ChatGPT user approves, and steering text there gets flagged. The question from rewrite 1b carries that instruction now.
- Expecting a widget's field to fill from an early answer. 0.24 does not do that. The widget shows and the user picks.
- Asserting
tools/list_metaoverInMemoryTransportwithout a JSON round trip. The wrappers are still there as objects. A real transport drops them. - Importing
neverPrefilled. It does not exist in 0.24.0 to 0.24.2. - Skipping the verify step. A clean
bun run typecheckplus greenbun testis the definition of done. A flow that compiles can still lose answers, so the tests need to drive each rewritten flow to the node that reads the moved field.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

