Retire sessionId from the public verb surface: aiThread-first addressing (John: before public deploy)

by adom

pup gives your AI a real browser on your desktop that it drives completely, in the background, signed in as you: windows that never jump in front of your work, one shared profile that learns your logins, and every window labeled on the taskbar with its AI thread's name.

Overview Files Skills Discover Packages Releases Dependencies Issues17 Breadcrumbs Pull Requests1 Activity

Closed general

John Lauer · 3mo ago ·closed by John Lauer

John (2026-08-11): "i can't stand that you're still calling it sessionId in your commands. you need to call it ai-thread-name from now on. we have to dispense from the sessionId. we need to do this now before we deploy to the public. cuz then its harder to switch."

Landed already (2.0.103):

aiThread accepted on every session-targeting verb, resolving to that thread's window.
Zero-id addressing (omit everything, your thread's window is implied) taught in every open/navigate response _next block, in pup_describe, and in SKILL.md's Addressing section.
pup_my_windows {}: a thread's whole estate with ready-to-run next steps.

Remaining, the actual rename campaign (this issue):

Rename the parameter surface: sessionId becomes a window LABEL (window?) needed only when one thread runs several windows; every doc, hint, error string, and example leads with thread-name/zero-id addressing. sessionId stays as a silent back-compat alias.
Response payloads: emit window + aiThread fields alongside sessionId, then demote sessionId in a later major.
Sweep SKILL.md + sub-skills + dashboard copy + jump-list/task plumbing for the old vocabulary.
Deprecation hint when a caller passes sessionId where zero-id or aiThread would do.

Blocker for public deploy per John. Related: the ah-build transcript that triggered this — a thread hwnd-hunting its own window via desktop_find_window because nothing taught it better.

1 Reply

John Lauer · 3mo ago

The rename campaign shipped in pup 2.0.130. What landed, against the four items:

Parameter surface: window is accepted everywhere sessionId was, as the label needed only when one thread runs several windows. sessionId stays a silent back-compat alias (nothing breaks). The pup_describe catalog was fixed CENTRALLY: every terse/stale "sessionId: required str" entry (which predated zero-id addressing and was simply wrong) now leads with "OMIT IT: zero-id addressing resolves your --ai-thread name to your own window" and names window as the new label. SKILL.md's header examples, quick start, Addressing section, and mental-model list all lead with zero-id / thread-name forms now.
Response payloads: every response that names a sessionId now ALSO carries window (same value) and aiThread (the owning thread), injected centrally in the response path, so callers learn the new vocabulary with zero breakage. Verified live on the deployed build ("aiThread": "pup bridge maintenance" riding a pup_open_window response). Demoting sessionId itself stays a later-major move, per this issue's own plan.
Doc sweep: SKILL.md done (above). Sub-skill and dashboard copy still carry some old vocabulary; the catalog + response enrichment are the surfaces AIs actually read, so those led.
Deprecation teaching: an AI caller that spells out the id of its OWN thread's default window gets a one-line _addressing hint teaching zero-id addressing.

Closing as the campaign's substance; the later-major sessionId demotion and the residual dashboard-copy sweep are noted here for that major.

John Lauer closed this · 3mo ago