feat: build_pathway over MCP, and a richer widget-to-agent channel

[adamstankiewicz]

What & why

Pathways reach MCP hosts two ways, matching how agents actually work: build_pathway runs the full pipeline as one tool call (~30s), persists the session under a minted learner id, and returns the /learn/{sessionId} student link plus a structured plan summary — honest when storage or verification is absent, with the ownerId returned because the edit endpoint gates on it. The connector instructions also teach the conversational mode explicitly: the agent is the sequencer (show_widget → read evidence → next activity).

The evidence channel back to the agent gains two things: completion reports carry a structured widget_result block alongside the prose sentence (the shape the universal WidgetResult converges on), and a single early struggle signal after consecutive wrong checks with no visible progress — so an agent can help before the finish line, not only after it.

The tools take an audience, not a grade. gradeHint forced every caller to describe a learner as a K-12 student; a deployment against ABET criteria, a cert blueprint or an internal competency model had nothing honest to put there, and the argument is free text steering standard selection — nothing about it needs to be a grade. build_pathway is new here so it is named right at birth; show_widget ships on main, so it gains audience as the documented argument and keeps gradeHint as an accepted alias.

Type of change

• Contract change (new tool + a structured model-context reporting convention)

Breaking or contract changes

Additive: one new tool; ui/update-model-context messages gain an optional fenced-JSON second content block (size-capped, over-fenced so payload text can't escape into prose). Existing single-block consumers are unaffected.

show_widget's input schema changes — additively, but on a tool that is already deployed: it gains audience and retains gradeHint, which now documents itself as a deprecated alias. Callers written against the shipped tool keep working unchanged; the alias is pinned by a test so a later cleanup can't silently drop it. Worth a reviewer's eye since this is the one contract here that third parties already program against.

How it was verified

• pnpm lint and rm -rf .next && npx tsc --noEmit
• Tool surface pinned through tools/list with real Requests: the three tools expose audience, the two new ones never carried the old name, and show_widget's alias is asserted
• pnpm mcp:build and committed the shell
• Review-pass findings fixed and dispositioned (see comment): honest save failures, ownerId returned, actual-vs-planned widget kinds, progress-aware struggle heuristic, per-widget counter reset, fence safety
• One manual connector test before merge: point Claude at a deployment, call build_pathway, open the returned link — the only live path not yet exercised end-to-end

Merge note: #75 has merged, so that conflict is resolved; this branch carries the audience rename forward from it. Still rebases after #86 (which drops this branch's committed-shell blob — the shell regenerates from source).

Authorship

• I understand every line of this diff
• Agent-assisted or agent-authored: authored by Claude working interactively with @adamstankiewicz; multi-agent review findings + dispositions in the PR comment
• No package.json / pnpm-lock.yaml changes

🤖 Generated with Claude Code

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
interactive-learning-experiences	Ready	Preview	Aug 31, 2026 12:39am

[adamstankiewicz]

Pre-merge review pass (multi-agent finders + verification) — findings and dispositions, so the review here can focus on the deltas:

Fixed in 179e7a3:

• Persistence failures no longer discard a 30s build behind a wrong "no persistent storage" message — save is separately guarded and the real reason is returned with the intact plan summary.
• The minted ownerId is now returned in structuredContent (the edit endpoint gates on it; discarding it made MCP-built pathways permanently uneditable by anyone).
• Per-step widgetKind reports the kind actually built; the planned kind + substitution note ride along when generation fell back — the caller can no longer describe widgets that aren't in the pathway.
• Struggle signal: consecutive-wrong streak with a progress heuristic (multi-part widgets like crossword emit correct:false while advancing — that's progress, not struggle); counters reset when the host hands the frame a new spec.
• Model-context detail blocks are size-capped and over-fenced (payload text containing ``` can't break into prose); dedupe includes the structured detail.
• runPathway passes through teacherNote/lessonPlanExcerpt (the assign route carries a third copy of this collect loop and can now converge), collects substitution notes, and drops a dead in-band error branch.

Deferred, deliberately:

• AbortSignal threading through streamPathway (disconnected clients still bill the full pipeline) — pre-existing, shared with /api/pathway and /api/assign; wants one repo-wide fix.
• Converging /api/assign onto runPathway — mechanical follow-up, not this PR.
• The progress heuristic's durable replacement is completion-semantics metadata on the registry entry (registry-owned-semantics refactor).

🤖 Generated with Claude Code