# pi-mono SDK Upgrade 0.73.0 → 0.74.0 (Package Scope Migration)

## Overview

Upgrade `@mariozechner/pi-coding-agent`, `@mariozechner/pi-ai`, and `@mariozechner/pi-agent-core` from `^0.73.0` to `^0.74.0`. The single substantive change in 0.74.0 is a package scope rename: `@mariozechner/*` → `@earendil-works/*`. The 0.74.0 release also rolls up the 0.73.1 bugfix release, none of which require code changes from Akmatori (HTML export XML stripping is automatic; OAuth-select / JSONC models.json / TUI fixes are not used by the agent-worker).

Verified against `/opt/pi-mono` at tag `v0.74.0`:
- `packages/coding-agent/package.json`: `"name": "@earendil-works/pi-coding-agent"`, version `0.74.0`
- `packages/ai/package.json`: `"name": "@earendil-works/pi-ai"`, version `0.74.0`
- `packages/agent/package.json`: `"name": "@earendil-works/pi-agent-core"`, version `0.74.0`
- Public API exports are unchanged except for two additive OAuth select types (`OAuthSelectOption`, `OAuthSelectPrompt`) not used by Akmatori
- `models.generated.ts` removed a few unused third-party model entries (k2p6, allenai/olmo-3.1, meta-llama/llama-3, mimo-v2-*) — none referenced in Akmatori's `MODEL_SUGGESTIONS`

Therefore this upgrade is purely mechanical: rename imports and dependency keys.

## Context

- Files involved (source):
  - `agent-worker/package.json` — rename three deps, bump to ^0.74.0
  - `agent-worker/package-lock.json` — regenerated by `npm install`
  - `agent-worker/src/agent-runner.ts` — two imports from `@mariozechner/pi-coding-agent` and `@mariozechner/pi-ai`, plus a `type-only` import in the `customTools` cast
  - `agent-worker/src/oneshot-llm.ts` — one import from `@mariozechner/pi-ai`
  - `agent-worker/src/gateway-tools.ts` — one import from `@mariozechner/pi-coding-agent`
  - `agent-worker/Dockerfile` — comment-only mention of `@mariozechner/pi-coding-agent SDK`
- Files involved (tests):
  - `agent-worker/tests/agent-runner.test.ts` — 1 `vi.mock` for coding-agent, 1 for pi-ai, plus ~10 dynamic `await import("@mariozechner/pi-coding-agent")` calls
  - `agent-worker/tests/oneshot-llm.test.ts` — 1 `vi.mock("@mariozechner/pi-ai")`
  - `agent-worker/tests/orchestrator.test.ts` — 2 `vi.mock` calls, plus ~8 dynamic `await import(...)` calls (coding-agent + pi-ai)
- Files involved (docs):
  - `CLAUDE.md` — SDK version reference `v0.73.0` → `v0.74.0`
- Related patterns:
  - Prior upgrade plan `docs/plans/completed/2026-05-05-pi-mono-upgrade-0.72.1-to-0.73.0.md` — same structure (bump, build, test)
  - Project memory: use `/opt/pi-mono` checked out at `v0.74.0` to inspect SDK shapes; do not pull from npm
- Dependencies: pi-mono `v0.74.0` tag is fetched and checked out locally at `/opt/pi-mono`. The npm packages `@earendil-works/pi-coding-agent@0.74.0`, `@earendil-works/pi-ai@0.74.0`, `@earendil-works/pi-agent-core@0.74.0` must be published on the registry (per release notes they are — published the same day as the rename PR)

## Development Approach

- Testing approach: Regular (code first, then tests). Each task ends with the relevant test command; do not move on until tests pass.
- Use `cd /opt/akmatori/agent-worker && npm run build` after dependency changes to catch type errors from the import rename.
- Use `git -C /opt/pi-mono show v0.74.0:packages/<pkg>/...` to verify SDK shapes — do not pull from npm.
- Mechanical rename: prefer `replace_all` in Edit/sed-style operations per file rather than per-line edits.
- CRITICAL: every task MUST include new/updated tests where behavior or imports change.
- CRITICAL: all tests must pass before starting next task.

## Implementation Steps

### Task 1: Bump pi-mono SDK deps to 0.74.0 with renamed scope

Files:
- Modify: `agent-worker/package.json`
- Regenerate: `agent-worker/package-lock.json`

- [x] Update `agent-worker/package.json` dependencies, replacing the three `@mariozechner/*` keys with their `@earendil-works/*` equivalents and bumping the version range:
  - remove `@mariozechner/pi-agent-core: ^0.73.0` → add `@earendil-works/pi-agent-core: ^0.74.0`
  - remove `@mariozechner/pi-ai: ^0.73.0` → add `@earendil-works/pi-ai: ^0.74.0`
  - remove `@mariozechner/pi-coding-agent: ^0.73.0` → add `@earendil-works/pi-coding-agent: ^0.74.0`
  - leave `typebox`, `undici`, `ws` unchanged
- [x] Run `cd /opt/akmatori/agent-worker && rm -rf node_modules && npm install` to refresh `node_modules` and regenerate `package-lock.json` cleanly under the new scope (avoids stale `@mariozechner/*` entries lingering in the lockfile)
- [x] Verify resolved versions with `cd /opt/akmatori/agent-worker && npm ls @earendil-works/pi-coding-agent @earendil-works/pi-ai @earendil-works/pi-agent-core` — all three must show `0.74.0`
- [x] Confirm no `@mariozechner/pi-*` SDK packages remain in `package-lock.json` (the `@mariozechner/clipboard` transitive dep may legitimately remain — that is a separate package owned by the same author and not part of the scope migration)

### Task 2: Rename SDK imports in agent-worker source

Files:
- Modify: `agent-worker/src/agent-runner.ts`
- Modify: `agent-worker/src/oneshot-llm.ts`
- Modify: `agent-worker/src/gateway-tools.ts`

- [x] In each of the three source files, replace `@mariozechner/pi-coding-agent` → `@earendil-works/pi-coding-agent` (replace_all)
- [x] In each of the three source files, replace `@mariozechner/pi-ai` → `@earendil-works/pi-ai` (replace_all)
- [x] In `agent-runner.ts`, also update the inline `import("@mariozechner/pi-coding-agent").ToolDefinition` cast on the `customTools` line to the new scope
- [x] No usage of `@mariozechner/pi-agent-core` exists in source today (it is only a transitive dep through `pi-coding-agent`), so no source change there — but if grep finds any, rename it too
- [x] Run `cd /opt/akmatori/agent-worker && npm run build` — must succeed with no TypeScript errors

### Task 3: Rename SDK imports in agent-worker tests

Files:
- Modify: `agent-worker/tests/agent-runner.test.ts`
- Modify: `agent-worker/tests/oneshot-llm.test.ts`
- Modify: `agent-worker/tests/orchestrator.test.ts`

- [x] In each test file, replace `@mariozechner/pi-coding-agent` → `@earendil-works/pi-coding-agent` (replace_all) — covers both `vi.mock(...)` calls and dynamic `await import(...)` lookups
- [x] In each test file, replace `@mariozechner/pi-ai` → `@earendil-works/pi-ai` (replace_all)
- [x] Run `cd /opt/akmatori/agent-worker && npm test` — all existing tests must pass without modification of assertions (no API surface changes affect Akmatori)
- [x] Run `make test-agent` from repo root as the canonical CI gate — must pass

### Task 4: Update Dockerfile and CLAUDE.md references

Files:
- Modify: `agent-worker/Dockerfile`
- Modify: `CLAUDE.md`

- [x] Update the header comment in `agent-worker/Dockerfile`: `@mariozechner/pi-coding-agent SDK` → `@earendil-works/pi-coding-agent SDK`
- [x] In `CLAUDE.md`, update the `Agent Worker` line that pins the SDK version: `pi-coding-agent` (`v0.73.0`) → `pi-coding-agent` (`v0.74.0`)
- [x] In `CLAUDE.md`, update the SDK Notes section if it references `@mariozechner/*` paths; add a one-line note that pi-mono packages have moved to the `@earendil-works/*` scope as of v0.74.0
- [x] Confirm `wc -c CLAUDE.md` is still under 30000 bytes (per the file's own rule)
- [x] No tests required — pure documentation

### Task 5: Verify acceptance criteria

- [x] Run `make verify` from repo root (Go vet + agent-worker tests + frontend tests) — must pass
- [x] Run `cd /opt/akmatori/agent-worker && npm run build` once more and confirm no leftover `@mariozechner/pi-*` references in `dist/`: `grep -r "@mariozechner/pi-" agent-worker/dist agent-worker/src` should match nothing
- [x] Run `grep -r "@mariozechner/pi-" agent-worker/{src,tests}` — must return zero matches (the `@mariozechner/clipboard` transitive dep does not live under `agent-worker/`)
- [x] Move this plan from `docs/plans/` to `docs/plans/completed/` after merge
