feat(fix): fetch the Agent SDK on the first fix, never fall back silently (UPT-108)

[lucasbraum]

UPT-108. npx uptide@0.15.1 fix never installed @anthropic-ai/claude-agent-sdk (an optional peer), so the Anthropic default quietly ran the patch executor while the notice and docs described the SDK (pilot round 3).

What changes

• The SDK is fetched on the first fix that needs it, not shipped. The package stays at 13.6 MB and keeps the SDK as an optional peer. Lookup order:
  1. An SDK resolvable next to uptide. The Action's install path is unchanged.
  2. <cache>/agent-sdk/<version>, using defaultCacheDir(), so UPTIDE_CACHE_DIR and XDG_CACHE_HOME apply.
  3. Otherwise the first fix that would use it runs npm install --prefix <temp> --no-save --include=optional @anthropic-ai/claude-agent-sdk@0.3.296. That goes through command(), so scripts are off and secrets are stripped from the env. The temp dir is renamed into place: the cache holds a complete install or nothing. One line reports it, with the size. Later runs reuse it. SDK_VERSION is pinned by a package test to the CLI's devDependency and peer range.
• Never a silent switch. If the SDK can't run (the install failed, it failed to load, or there's no Claude Code binary for the platform), the default uses the patch executor. It says so on the first line of stderr and at the top of the PR body, with the reason and how to get the SDK executor. --agent sdk without a usable SDK stops before any clone instead of failing mid-run.
• report.json gains llm.executor (sdk | patch, set whenever assisted fixes are on). llm.sdkMissing is now the reason string, where it used to be true.
• Notice: the privacy note names the SDK only when the SDK will run, and the LLM: line names the executor.
• Docs: fix.md, privacy.md and architecture.md, plus a new dated decision in ADR 0016 (the 2026-10-12 optional-peer decision is marked superseded). The changeset is minor.

What the first lines look like:

# first fix, nothing installed (node:22 container)
Agent SDK 0.3.296 is not installed: installing it once into /root/.cache/uptide/agent-sdk/0.3.296 … 295 MB, reused by later runs
uptide fix · zod · smoke-npm (npm)
LLM: anthropic / claude-sonnet-5-5 · executor sdk · budget $1.00

# install fails (@anthropic-ai scope pointed at an unreachable registry)
Agent SDK 0.3.296 is not installed: installing it once into /tmp/offline-cache/agent-sdk/0.3.296 … failed
warning: Assisted fixes use the patch executor, not the Agent SDK: @anthropic-ai/claude-agent-sdk is not installed, and installing @anthropic-ai/claude-agent-sdk@0.3.296 into /tmp/offline-cache/agent-sdk/0.3.296 failed (npm error code ECONNREFUSED). For the SDK executor, let Uptide reach the npm registry once to install it into its cache, or install @anthropic-ai/claude-agent-sdk@0.3.296 next to Uptide; --agent patch chooses the patch executor and drops this note.
uptide fix · zod · smoke-npm (npm)
LLM: anthropic / claude-sonnet-5-5 · executor patch · budget $1.00

The PR body of that run starts with the same note, after the title, as > ⚠️ ….

Sizes

node:22 on linux arm64, the packed CLI.

	before (main)	this PR
tarball	2,549,083 B	2,548,325 B
npm install of the tarball / plain npx uptide check	13.6 MB, 3 packages	13.6 MB, 3 packages, no SDK anywhere on disk
first fix that needs the SDK	none (silent patch fallback)	downloads into the cache once: 295 MB reported by Uptide (du: 310 MB)
later fix runs		0 B

I tried an optionalDependencies version first (77bfe7c, then reverted). Every install grew to 323.6 MB and 110 packages, check included: binary 250 MB, SDK 5.5 MB, its peers 36 MB. That's why it's fetched on demand.

Smoke (clean node:22 container, packed tarball, fake key, the npm smoke fixture)

The zod sites there are all mechanical, so no model call is made.

case	result
plain npx -y file:<tgz> check	exit 1 (breaking found, as expected); npx install 13.6 MB; no claude-agent-sdk* directory on disk, no agent-sdk cache
plain npx fix, first run	one install line (295 MB), executor sdk; report.json has executor: "sdk"; exit 0 in 13 s
plain npx fix, second run	no install line, executor sdk; exit 0 in 8 s
SDK installed next to uptide, empty cache	no install line, executor sdk, nothing written under agent-sdk
fetch fails (.npmrc sends @anthropic-ai to 127.0.0.1:9)	warning on the first line after the failed install line, executor patch; report.json has executor: "patch" and sdkMissing with the reason; PR body line 3 is the note; no partial cache left; exit 0
cache dir can't be created (UPTIDE_CACHE_DIR=/etc/passwd/cache)	loud fallback with ENOTDIR in the reason, no crash (df41ef8). The run then exits 2 because Uptide's registry cache can't be written either. That is pre-existing and unrelated.

An earlier round, on the optional-dependency build, also confirmed that npm, pnpm 10, yarn 1 and yarn 4 dlx resolve and run the SDK from where they install it.

pnpm turbo run typecheck test for uptide and @uptide/core passes. biome check . has only the pre-existing warning and info.

Pilot rerun: Uptide arm only, packed tarball via plain npx -y file:<tgz>

Same harness as round 3, claude-sonnet-5-5, $1 (--max-cost default), human references from round 3. All three runs report executor: sdk.

repo	run	executor	frozen install	types	lint	tests	build	fork CI	cost	wall	coverage vs human
calmcp, zod 3→4	this PR	sdk	ok	ok	ok	ok	ok	same as human: only npm audit (×2) and dependency-review fail, both environmental	$0.09	53 s	6/27
	0.15.1 (#169)	patch	ok	5 errors	ok	1 fail	fail	fail: env, plus Tool surface and docker	$0.03	52 s	1/27
dms-saas, stripe 18→22	this PR	sdk	ok	10 errors	ok	1 fail³	fail	fail at typecheck	$1.02	612 s	0/51
	0.15.1 (#169)	patch	ok	5 errors	ok	pass³	fail	fail at type-check	$0.18	242 s	6/51
enki, react 18→19	this PR	sdk	ok	ok	ok	ok (58/58)	ok	fails only at SonarQube Scan (no secret on forks, as human)	$0.18	164 s	10/29
	0.15.1 (#169)	patch	ok	4 errors	ok	ok	fail	fails only at SonarQube Scan	$0.06	158 s	9/29

³ The MongoMemoryServer flake: private-admission.test.ts timed out at 5 s.

• calmcp and enki: every local check now passes. Round 3 failed the type-check and build on both.
  • On enki, the session also replaced the undeclared @react-types/datepicker import with @entur/datepicker's own TimeValue. That was round 3's lockfile finding. The scorer counts those 2 hunks as "unrelated" only because the human left that file alone.
• dms-saas got worse, and not because of the executor's edits. Four SDK sessions ran (the site session plus 3 feedback rounds). The gate rejected the first three with tests fail: packages/dms-saas; the local check shows that same flaky test failing. The fourth stopped at the budget. Every edit was discarded, so the branch is only the version bump, the formatter and the lockfile. That gives 0/51 coverage and the full set of upstream type errors. The gate letting one known flaky test throw away correct-looking sessions is its own follow-up, not part of this PR.
• Cost: dms-saas ended $0.02 over the $1 limit. The last SDK session stopped at error_max_budget_usd after crossing it.
• Not rerun after the redesign: the pilot ran on the optional-dependency build (77bfe7c, tarball sha256 a2408063…). The executor path didn't change after that: same SDK 0.3.296, same binary, same session code. Only where the SDK is imported from changed, and the smoke above covers that.
• Fork PRs, uptide-bench only: calmcp#9, dms-saas#11, enki#8. The harness change (an UPTIDE_SPEC override, plus executor read from llm.executor) was applied to a copy of bench/, not committed.

For review

• Terms: ADR 0016 has an open question to Anthropic, "Is an npm dependency 'preinstalling' Claude Code in a product?". Installing the published package on first use is the same question in another form. The ADR records it as still open.
• Windows: the fetch spawns npm.cmd without a shell, which is untested. If it fails there, the run falls back loudly.
• Pre-existing, not touched: UPTIDE_CACHE_DIR under /proc makes check and fix spin forever before any output.

🤖 Generated with Claude Code