pi-web/relays/issue-62-authstorage/charter.md

Relay charter — issue-62-authstorage

Relay identity

• Name: issue-62-authstorage
• Root path: relays/issue-62-authstorage/ (in the repo, on branch fix/issue-62-authstorage, worktree /srv/dev/pi-web-issue-62)
• Packet files: charter.md, status.md, log.md (this directory).

Background (read once, do not re-derive)

The full technical assessment lives at the worktree root: ASSESSMENT-issue-62.md. Read it once at the start of your leg for the API migration details; do not re-investigate the SDK from scratch. Short version: Pi @earendil-works/pi-coding-agent 0.80.8 removed the AuthStorage export and replaced the auth/model plumbing with an async ModelRuntime + pi-ai CredentialStore model. Pi Web imports AuthStorage statically and crashes at module load with any Pi 0.80.8+. The agreed fix is a clean migration to the new ModelRuntime API (no dual-version shim) plus dependency-range correction, tests, and a changeset. Rationale and the per-file migration shape are in ASSESSMENT-issue-62.md §5.

Goal / finish line

Pi Web builds, typechecks, lints, and passes its full test suite against Pi @earendil-works/pi-coding-agent 0.80.8+ (target the installed 0.80.8/0.80.10 line), with:

1. No remaining import or use of the removed AuthStorage export (and no reliance on ModelRegistry.create(authStorage) / .inMemory(authStorage) / modelRegistry.authStorage).
2. Auth, OAuth login, API-key save/logout, provider enumeration, and the Anthropic subscription warning all working through the new ModelRuntime / readStoredCredential / pi-ai CredentialStore APIs.
3. package.json peerDependencies and devDependencies for the three @earendil-works/* packages corrected so npm cannot resolve an unsupported release (target range >=0.80.8 <0.81; devDeps on a matching ^0.80.8).
4. A .changeset/*.md fragment describing the user-visible fix (no direct CHANGELOG.md edit).
5. npm run verify (typecheck + lint + knip + test) passing.

Finish line reached = all of the above true and committed on the branch. Do not open a PR (out of scope for this relay).

Sizing — one leg

One leg = one coherent slice from the plan below that leaves the tree in a committed, describable state. Prefer the pre-broken-out slices in status.md. A leg does not have to leave npm run verify fully green (the migration is interdependent), but it MUST:

• leave a clear, honest status.md describing what compiles/what doesn't yet,
• commit its work with a clear message,
• not expand scope beyond its slice ("just a bit more" is the main failure mode here — the auth surfaces are interconnected; resist rewriting everything in one leg).

If a slice turns out bigger than expected, split it and hand off mid-plan with an updated status.md — that is expected and fine.

Suggested slice breakdown (task selection default)

Follow status.md's named next task. If none is named, pick the lowest-numbered incomplete slice here:

0. Bootstrap: npm install in the worktree pinning the three @earendil-works/* packages to 0.80.8+ (e.g. npm i -D @earendil-works/[email protected] @earendil-works/[email protected] @earendil-works/[email protected]), and correct the peerDependencies range to >=0.80.8 <0.81. Confirm the crash reproduces / the new exports resolve. Commit. (Install in the worktree, NOT /tmp — /tmp has a disk quota problem, see assessment §8.)
1. authService.ts core migration: move to ModelRuntime (async construction via ModelRuntime.create({ authPath, modelsPath })), migrate saveApiKey/logout/refresh/credential access. Propagate async construction to sessiond.ts. (Session-daemon path — see restart note.)
2. authProviderOptions.ts migration: rederive login/logout provider options from runtime.getProviders() + listCredentials() / getProviderAuthStatus(); update its structural interface + test double.
3. oauthLoginFlowService.ts migration: reimplement against pi-ai AuthInteraction (prompt/notify) instead of OAuthLoginCallbacks; wire runtime.login(providerId, "oauth", interaction). (Riskiest slice — verify prompt/select/device-code/auth_url mapping.)
4. piSessionService.ts migration: pass modelRuntime to createAgentSessionServices; update PiAgentSession type; switch anthropicSubscriptionWarning to readStoredCredential.
5. Tests + testSupport: migrate all test doubles to InMemoryCredentialStore
   • ModelRuntime.create; get npm run verify green. Follow the testing-guide skill.
6. Changeset + final verify + cleanup: add .changeset/*.md; run full npm run verify; remove scratch (ASSESSMENT stays, /srv/dev/pi-inspect is outside the repo). Confirm goal, hand off to a final confirmation/stop.

Slices may merge or split. 1–4 depend on 0. Slice 5 finalizes; slice 6 closes.

Handover

When handing off, spawn_session once with a prompt whose first line is: Relay "issue-62-authstorage" leg <N> begins now. followed by the standard Relay handoff body pointing at:

• relays/issue-62-authstorage/charter.md
• relays/issue-62-authstorage/status.md

Tell the next runner not to read log.md end-to-end. Make all work durable (update status.md, append log.md, commit) before spawning.

Intervention signal — stop and get the human when:

• The new SDK API does not actually provide an operation the migration needs (e.g. no viable credential persistence path for API-key save), i.e. the assessment's assumed mapping is wrong.
• A slice would require changing the charter's goal or the agreed "clean migration, no shim" decision.
• npm install / registry access fails and cannot be resolved in-leg.
• Charter churn: if you find yourself needing to edit this charter to proceed, stop and involve the human instead. To raise it: set a clear ## BLOCKED section at the top of status.md, append a log.md entry explaining the blocker and what decision is needed, do not spawn the next leg, and end your run.

Reading discipline

Read, in order: this charter.md, then status.md, then ASSESSMENT-issue-62.md (once), then only the specific src/server/sessions/* files your slice touches. Do not read log.md end-to-end — only targeted entries if status.md points you there. Do not re-extract SDK tarballs unless the assessment is contradicted by reality.

Standing constraints (project conventions)

• Session-daemon changes (sessiond.ts, session runtime / auth construction loaded by the daemon) require the human to manually restart the sessiond service to take effect. Call this out in status.md/handoff whenever a leg changes that path so the human knows a restart is pending.
• Follow the skills: code-quality-architecture (DI, async boundaries, testable seams), testing-guide (test layers, no over-mocking), and changeset-changelog (changeset not CHANGELOG edit).
• Keep changes scoped to the fix; do not opportunistically refactor unrelated code.