agentleFS
WaniWani-AIWaniWani-AI/sdk/skills/migrate-waniwani-sdk-0.23-to-0.24/SKILL.md

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.

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
  1. Very specific:

    1a. Compute it in a node: Add an action node right before the first node that reads the field.

    line 91
  2. Very specific:

    1b. Ask it: Add the field as a question in an interrupt, in a node placed before the first node that reads it.

    line 93
  3. Very specific:

    tools/list assertions: Read the graph from flow.flowGraph.

    line 256
  4. Very specific:

    Read the graph from the compiled flow, and stop setting the key by hand.

    line 276
  5. Very specific:

    When you pass your own _meta, spread flow.config._meta into it.

    line 288

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.230.24
flow.config._meta._flowGraph is typed FlowGraphflow.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:

Call0.230.24
start with stateUpdatesMerged into state, filled nodes skippedIgnored
continue with a field not asked yetMergedDropped
continue or reset with a field no question or widget ever asksMergedDropped
A widget's continue carrying keys other than its fieldMergedDropped
reset with no asked fieldMerged, flow restartsError: 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's stateUpdates is an untyped record, the same for every flow. The definition _meta still carries the flow graph and the redacted-fields list for withWaniwani, wrapped in an object whose toJSON returns undefined, so a serializing transport never sends them. Snapshot tests of the listing change.
  • Hand-set _meta._flowGraph. withWaniwani still reads it and moves it off the wire. It is deprecated. 0.25.0 still reads it.
  • createFlowTestHarness. start(intent, known) no longer sends known as stateUpdates. It starts empty, then answers each question whose field known holds with a continue, until the flow asks something known has no value for. A value in known for a field no question asks is ignored.
  • nextStep text 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

  1. Bump the dependency.
    bun add @waniwani/sdk@^0.24.0
  2. 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.*'
  3. 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 an interrupt({ ... }) call),
    • a widget (showWidget({ field: "key" }), or a z.object group the widget's field names),
    • a node return value (return { key: ... } from a node),
    • the conversation (the flow description or the field's .describe() tells the model to send it, a question's context tells the model to put a value in it, a widget sends it back, or a test sends it in stateUpdates).

    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.

  4. Apply rewrites 1 to 5 below to every target.
  5. Verify, which is the completion check.
    bun run typecheck && bun test
  6. 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:

  1. A node already falls back to another source when the field is empty (state.locale ?? localeFrom(meta)): use 1a with that source.
  2. The value is a function of other state fields: use 1a.
  3. 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 _meta over InMemoryTransport without 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 typecheck plus green bun test is 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.