The intent surface: journeys, grouping, budgets, and the agent skill

[SouravInsights]

Journeys, grouping, budgets, and the agent skill (0.9)

This PR changes what @webmcp-stack/codegen thinks its job is. It used to take an OpenAPI spec and emit one WebMCP tool per endpoint, then give you a dashboard to edit them by hand. That model broke for two reasons: nobody edits 75 tools by hand, and the person editing them isn't a person at all anymore. It's a coding agent with a lazy prompt. So the safe defaults became the product, and "how does your own agent learn the rules?" became the problem worth solving.

This PR answers that. The rules now ship into the repo the agent reads, the tool surface an agent picks from is a few intent-level tools instead of a 1:1 mirror of your routes, and those choices are locked in by CI. The built-in LLM layer, which existed to guess what the user's agent would do, is gone.

npx @webmcp-stack/codegen generate reads your OpenAPI spec, emits one .webmcp.ts file per endpoint (each one withheld by default: the file exists with its schema and hints baked in, but it isn't registered until you enable it), scaffolds a skill file your agent reads, and wires registration. Journeys sit on top: small TypeScript files you or your agent write that register step tools and a submit gate, composing the withheld endpoint tools' raw HTTP callers instead of re-implementing them. verify measures the whole surface and exits 1 on failure, so a sloppy hand edit breaks CI. The dashboard keeps its editing surface, writing overrides that survive regeneration.

What's in it

Journeys — the new concept, and the one to read closely. A journey file is a small TypeScript file in src/webmcp/journeys/ for goals that take a few calls with shared state: an agent can't invent a fully populated locationObject from scratch, and a paid action needs a human in the loop first:

// src/webmcp/journeys/document-trip.webmcp.ts
import { createJourney } from "../journey.webmcp";
import { getAutocompleteTool, fetchGetAutocomplete } from "../get-autocomplete.webmcp";
import { executeCreateTrip, type CreateTripInput } from "../create-trip.webmcp";

export const documentTrip = createJourney({
  name: "document-trip",
  goal: "Record a trip you've been on and open the editor to write its story",
  steps: {
    // A step that calls the real get-autocomplete tool (an endpoint you
    // already own). It stores the result on the draft; the input schema,
    // description, and annotations come from the generated tool definition.
    "search-places": {
      tool: getAutocompleteTool,
      call: (input, signal) => fetchGetAutocomplete(input as never, signal),
      store: (places) => ({ locationObject: places }),
      provides: ["locationObject"],
    },
    // A step that takes input and stores it, with no API call of its own.
    "set-details": {
      description: "Set the trip's title.",
      input: { type: "object", properties: { title: { type: "string" } }, required: ["title"] },
      provides: ["title"],
    },
  },
  // The gate. It refuses until every step's `provides` is filled on the
  // draft, prompts the human through the same confirmation flow writes
  // already use, then clears the draft. The agent can't skip it.
  submit: {
    description: "Create the trip and open it in the editor.",
    build: (draft) => draft as never as CreateTripInput,
    run: executeCreateTrip,
  },
});

The detail that makes this safe: journey.webmcp.ts is a file the generator owns and rewrites on every run, the same way the runtime is. Your journey files import createJourney from it, so you can't edit the gate logic out, because you don't get to touch the file that is the gate logic. The barrel auto-registers every journeys/*.webmcp.ts it finds, and verify enforces the journey rules: gate present, at most five steps, no direct fetch inside a step.

sequenceDiagram
    actor You as Human
    actor Agent as Your coding agent
    participant Browser as Page (WebMCP)
    participant App as Your backend

    Note over Browser: documentTrip.register() ran on load
    Browser->>Agent: tools registered: search-places, set-details, submit (+ the normal tools)
    Agent->>Browser: call document-trip-search-places(input)
    Browser->>App: callApi(getAutocompleteTool)
    App-->>Browser: places[]
    Browser->>Agent: "Still needed: document-trip-set-details"
    Note right of Agent: result stored on an in-memory draft
    Agent->>Browser: call document-trip-set-details({ title })
    Browser->>Agent: "Still needed: document-trip-submit"
    Agent->>Browser: call document-trip-submit()
    Browser->>You: confirm "Create trip 'Kyoto 2025'?"
    You-->>Browser: approve
    Browser->>App: executeCreateTrip(build(draft))
    App-->>Browser: trip created
    Browser-->>Agent: "Done. Trip trip_123 created."
    Note over Browser: draft cleared

Loading

Handshake grouping — one tool per endpoint works until your API splits a single user action across two calls. POST /v1/media/request-upload and POST /v1/media/uploads/{uploadId}/complete are one action (upload a file) that happen to need two HTTP calls. groupHandshakes detects begin/end pairs like that, threads the first response into the second call by exact name (a {uploadId} path param has to find a property named uploadId on the first response's schema, or the pair is skipped with a note), and appends a merged upload-media tool next to the pair as a withheld proposal. You enable it like any write tool; the members stay withheld. Fuzzy cases are skipped deterministically, because a decision you don't have to make is a decision the tool doesn't get wrong.

Chrome's character budgets, applied as guidance — names ≤30, parameter descriptions ≤150, tool descriptions ≤500, single tool output ≤1.5K. Chrome documents these; the spec itself only rejects an empty description or a name outside 1-128 chars, so this PR treats them as authoring guidance, not a rule. Machine-drafted text is composed to fit (sentence cuts at boundaries); author and spec text is never silently shortened; verify warns on an overrun rather than failing CI. The runtime still caps every toolResult at ~1.5K in the generator-owned layer where a hand edit can't remove it.

The agent skill file (.agents/skills/webmcp-tools/SKILL.md) — scaffolded like the runtime, rewritten on every generate, at the cross-client path agents already scan (AGENTS.md, Claude Code, the generic standards). It tells the agent: the character budgets, the description format (Side effect:/Reads from: lines), the confirmation requirement for writes, how to compose journey files (fetchX for data, execute for the agent-facing contract, never fetch inside the file), and the eval harness at packages/codegen/evals/skill/ with 9 cases and deterministic graders. node run.mjs --selftest passes; live agent runs need a CLI available (AGENT_CMD='codex exec --json "{PROMPT}"' node run.mjs).

Spec sync (97da8f5) — the spec evolved since codegen's first pass. We now emit title (the human label Chrome's UI shows), auto-set consequentialHint on destructive tools, and expose exposedTo (origin-scoping) as a config pass-through. References to Chrome 146 in three docs files were stale and are now at 149/150.

Deleted — --llm, --suggest, the provider flow, the config options, the llm.ts module. ~1,050 lines. The skill file is how rules reach models; the CLI itself never calls a model.

The assumptions baked in

If you're reading this from the Chrome team, or from WebMCP at large, this is the section that earns the review:

• Withheld-by-default is the posture. Every write-tier tool ships unregistered; the developer turns it on. The alternative (register everything, let the agent pick) is the failure mode this CLI exists to prevent.
• A journey's shared state is in-memory only. The draft object lives for the page load; a tab close or refresh wipes it. That's intentional, a half-finished journey should evaporate rather than linger. And it means two parallel journeys on one page will collide and overwrite each other, an accepted edge case, worth saying out loud.
• The gate is a registered tool, not a config. WebMCP today has no native journey construct, so the submit gate is a step tool with logic that lives in the file you don't get to edit. When the spec ships one (the skills/tool-groups thread is #161), the factory swaps its internals and user-written journey files don't change.
• The confirmation prompt is window.confirm, not a fancy native thing. Chrome's own guidance hints at a requestUserInteraction() API for this; it isn't in the spec yet. When it lands, the change is one file, the confirmation logic sits in the same owned region the gate sits in.
• Grouping is deterministic-only. Begin/end pairs merge when they match exact rules; fuzzy matches are skipped with a note. A clever guess is how plan-trip got written.
• A step composes a generated endpoint tool, never duplicates it. fetchGetAutocomplete (the raw caller) is exported explicitly so steps reuse one function. Reuse keeps the schema single-sourced.

What to review

Skim these first:

• packages/codegen/assets/journey.webmcp.ts — the factory; ~215 lines, no new deps.
• packages/codegen/src/group.ts and src/group.test.ts — the handshake detector and its pinned cases (the beenthere upload pair, the unthreadable pair, the cross-resource pair, the GETs-only negative).
• packages/codegen/src/verify.ts — the new checks.
• packages/codegen/assets/skill/SKILL.md and packages/codegen/evals/skill/run.mjs — the contract with the agent, and the graders.
• packages/codegen/src/outputs/tools-templates.ts — the generated region (titles, annotations, the fetchX raw callers, the gated execute).
• packages/codegen/src/outputs/generated-code.test.ts — parses every generated template output with the TypeScript compiler, the guard against the runtime bug below.
• site/content/docs/journeys.mdx and journeys-faq.mdx — the public walkthrough (rewritten around a booking example) and the plain-terms FAQ.
• site/content/docs/why-agent-tools.mdx, after-you-generate.mdx, working-with-your-agent.mdx, prompt-cookbook.mdx, tool-or-journey.mdx, testing.mdx — the new guides, and the agent-readable /llms.txt and /llms-full.txt feeds.

Updates after review

A review pass on this branch found one real bug and several docs that over-promised. All are fixed, in separate commits:

• The generated runtime did not parse. The 1.5K truncation notice was written as a "\n…" string inside the outer template literal, so the emitted runtime.webmcp.ts carried a real newline inside a double-quoted string. Every generated runtime was a syntax error. Fixed, and generated-code.test.ts now parses every template output so it cannot recur.
• Character budgets no longer silently shorten text. Author and spec text is kept in full, machine text is composed to fit, and verify warns instead of failing CI.
• Journey steps no longer claim read-only when the composed tool writes. The factory inherits the composed tool's readOnlyHint, resolves the WebMCP context at registration time, and composes step descriptions within budget.
• The surface check counts journey tools (steps plus the submit gate), which the docs claimed but the code did not do.
• Docs. The journeys guide was rewritten around a relatable example and an explicit mental model; the new pages above cover why it matters, what to do after generating, how to work with your coding agent, prompts, choosing a shape, and testing. The CLI and READMEs point at the new domain, https://webmcp.souravinsights.com.
• A changeset was added, which the first push was missing.

What landed

66 files changed, +5,934/−1,218. 229 tests pass (232 before the LLM removal: 12 removed with the deleted layer, 9 added for grouping, budgets, journeys, and generated-output parsing). tsc and biome clean. On a beenthere-shaped fixture spec the CLI prints: Grouped create-media-request-upload + complete-media-upload into upload-media. Verify reports: ✓ Journeys: 1 journey file, gates and budgets in order.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
webmcp-stack	Ready	Preview	Sep 12, 2026 9:06am UTC