Bump an agentic-tool SDK
Packaged installs never load an agent SDK from agor-live. agor install --sync installs the
version-aligned wrapper @agor-live/<tool>@<agor-live version> from npm, and that wrapper pins
the SDK exactly. A published wrapper version is immutable, so an SDK bump reaches packaged users
only through a new agor-live release. Plan the bump as a release PR (step 5) unless the
maintainers explicitly want it to ride a later release.
1. Pick and verify the version
npm view <sdk> time --json | tail— confirm the version is published. For the Claude Agent SDK and OpenCode, confirm every platform package (<sdk>-darwin-arm64@<v>, …) is published too.- Read the SDK changelog or diff
sdk.d.tsbetween the old and new tarballs (npm pack <sdk>@<v>) for breaking API changes.
2. Update every pin
Find all of them with git grep -n "<old version>" -- ':!pnpm-lock.yaml' ':!CHANGELOG.md'.
| Tool | Wrapper runtime pin (exact) | Other owners that must match |
|---|---|---|
| Claude | packages/agor-claude → @anthropic-ai/claude-agent-sdk |
devDependencies in packages/core, packages/executor, apps/agor-daemon; packages/executor/src/sdk-watchdog.ts |
| Codex | packages/agor-codex → @openai/codex-sdk |
devDependencies in packages/core, packages/executor; sdk-watchdog.ts; version-specific comments (for example runtime-diagnostics.ts) |
| Gemini | packages/agor-gemini → @google/gemini-cli-core |
devDependency copies; sdk-watchdog.ts |
| OpenCode | packages/agor-opencode → opencode-ai and @opencode-ai/sdk |
packages/agentic-tool-opencode (devDependency, OPENCODE_VERSION, OPENCODE_INTEGRATION.sdkVersion), docker/Dockerfile global install |
| Copilot | packages/agor-copilot → @github/copilot-sdk |
sdk-watchdog.ts |
| Cursor | packages/agor-cursor → @cursor/sdk |
— |
Also update minimumReleaseAgeExclude in pnpm-workspace.yaml for the SDK and its platform
packages. No check enforces this list; stale entries break installs where an operator's pnpm
enforces minimumReleaseAge.
Then run pnpm install and confirm the pnpm-lock.yaml diff touches only the bumped packages.
For OpenCode, then run pnpm --filter @agor-live/opencode generate:hosted-providers to refresh the
hosted provider snapshot (packages/agentic-tool-opencode/src/daemon/hosted-providers.generated.ts);
its test fails until the snapshot matches OPENCODE_VERSION.
3. Prove the runtime does what the bump is for
If adding a model, also follow the owner map and model checklist in Publishing Agor.
Tests mock the SDK, so they cannot show that a new model or fix works. For a model bump:
- Check the bundled runtime knows the model:
npm pack <sdk>-darwin-arm64@<v>, thenstrings package/claude | grep -o '{id:"<model-id>",family.\{0,1400\}'shows its catalog entry (context window,native_1m,1m_suffix, default effort). Use this to decide registry shape, such as whether a[1m]variant exists. - Run one real turn through the SDK from
packages/executorwith the model, and compare with the old version. Record what changed (for example, Claude Code 2.1.280 accepted Sonnet 5.5 but capped it at 200k context; 2.1.284 reports 1M).
4. Validate
node scripts/check-agentic-tool-packages.mjs— exact pins, devDependency and watchdog alignment, wrapper versions, OpenCode version owners.node scripts/sync-agor-live-deps.mjs --check- Targeted tests for the tool's SDK handler (for Claude:
vitest run src/sdk-handlers/claudeinpackages/executor) and the model registry tests if models changed.
These checks do not detect a wrapper whose dependencies changed while its version stayed the same. Step 5 is what prevents that drift.
5. Ship it as a release
Follow Publishing Agor for the aligned version bump and
changelog, post-merge tag, protected npm environment approval, and registry
verification before upgrading and running agor install --sync. Manual workflow
dispatch is a non-publishing preflight. A build or publishing approval alone is not
proof that the exact wrapper versions are available to installers.
Agor Cloud rollout is separate; use the runbook in its private repository. Keep private cloud deployment details out of this skill and the public release guide.
Precedents: #2830 (Opus 5.5 runtime, 0.26.6) and #2915 (Sonnet 5.5, 0.26.8).
