| name | upgrading-runtime-dependencies |
| description | Guides strategic analysis of agent runtime dependency upgrades — changelog categorization, codebase impact assessment, and feature adoption decisions. Use when upgrading SDK-level dependencies that sit behind an abstraction boundary. |
| user-invocable | false |
Upgrading Runtime Dependencies
This skill teaches the judgment calls needed when upgrading dependencies that power agent runtimes. Unlike routine dependency bumps, runtime SDK upgrades require understanding what new capabilities to adopt, not just what breaks.
Core Principle
Runtime dependencies sit behind abstraction boundaries (e.g., the AgentRuntime interface). Changes to the SDK affect a confined set of files, but the implications ripple outward through the features those files enable. Your job is to trace both the direct code impact and the strategic value.
Changelog Categorization
Ambiguous Entries
Changelog entries are often vague. Use these heuristics:
| Entry Pattern | Likely Category | Why |
|---|
| "refactored X internals" | internal | Unless X is a public API you call |
| "improved X performance" | performance | But check if our usage pattern benefits |
| "updated X types" | Could be breaking | Type changes can break compilation |
| "X now accepts Y" | feature | Additive API change |
| "X no longer does Y" | breaking | Subtractive behavior change |
| "deprecated X in favor of Y" | deprecated | Even if X still works |
| "fixed X when Y" | fix | Check if we hit condition Y |
Version Significance
Not all versions deserve equal attention:
- Major bumps (0.x → 1.0, 1.x → 2.0): Read every entry. These are intentional breaking points.
- Minor bumps with many changes: Skim for features and deprecations. These accumulate API surface.
- Patch bumps: Only scan for fixes that match known issues or workarounds in our code.
- Pre-1.0 minors (0.2 → 0.3): Treat like majors. SemVer allows breaking changes before 1.0.
Cross-Referencing Sources
When multiple sources exist (GitHub releases, CHANGELOG.md, npm metadata):
- GitHub releases are authoritative for intent — maintainers write these for humans
- CHANGELOG.md is authoritative for completeness — often auto-generated from commits
- npm metadata is authoritative for version timeline —
time field shows exact publish dates
- If sources conflict, prefer GitHub releases for categorization, CHANGELOG.md for exhaustiveness
Impact Assessment Judgment
Mapping SDK Changes to the Abstraction Boundary
For the Claude Agent SDK specifically, the AgentRuntime interface is the abstraction boundary (enforced by ADR-0089 via ESLint). Know the mapping:
| SDK Surface | DorkOS Module | Impact Scope |
|---|
query() function signature | message-sender.ts | Core messaging pipeline |
SDKMessage types | sdk-event-mapper.ts | Event streaming |
Options type | message-sender.ts, plugin-activation.ts | Session configuration |
Session management (renameSession, forkSession) | claude-code-runtime.ts | Session lifecycle |
| MCP server config types | context-builder.ts | Tool/context injection |
| Permission modes | message-sender.ts | Security boundary (ADR-0240) |
Plugin system (options.plugins) | plugin-activation.ts | Marketplace integration (ADR-0239) |
| Error types/categories | sdk-event-mapper.ts | Error handling (ADR-0143) |
| CLI path resolution | sdk-utils.ts | Dependency checking |
| Model/subagent metadata | runtime-cache.ts | Cached metadata |
| Slash command discovery | command-registry.ts | Command system |
Assessing Feature Relevance
Ask these questions for each new SDK feature:
- Does this touch something we already wrap? If yes → high relevance (we're already invested)
- Does this enable a requested DorkOS feature? Check specs, Linear issues → high relevance
- Does this improve reliability/performance of current usage? → medium relevance
- Does this add a capability we haven't considered? → medium relevance (evaluate the opportunity)
- Does this serve a use case we explicitly don't support? → low/none relevance
Effort Estimation
Be honest about effort. A "trivial" SDK API change can have non-trivial implications:
| Change Type | Seems Like | Actually Is |
|---|
New optional parameter on query() | Trivial | Trivial — just pass it through |
New required parameter on query() | Moderate | Could be significant if it needs user-facing config |
New event type in SDKMessage | Trivial | Moderate — needs mapper entry, may need UI support |
| Changed error category taxonomy | Moderate | Significant — touches error handling, may need UI updates |
New Options field | Trivial | Depends — if it needs per-session config, touches session store |
| Removed/renamed export | Breaking | Usually moderate — confined by ESLint boundary |
ADR Conflict Detection
Before recommending an adoption approach, verify it doesn't violate existing ADRs:
- ADR-0089 (SDK Import Confinement, now Hard Rule #2 per runtime): every runtime SDK's imports must stay inside its own adapter directory:
@anthropic-ai/claude-agent-sdk → services/runtimes/claude-code/, @openai/codex-sdk → services/runtimes/codex/, @opencode-ai/sdk → services/runtimes/opencode/. If a new feature needs to surface data outside that boundary, it must go through the AgentRuntime interface.
- ADR-0239 (Plugin Activation): Plugin runtime integration uses
options.plugins. If the SDK changes how plugins work, the activation pipeline needs updating.
- ADR-0240 (Permission Passthrough): Permission modes pass through to the SDK. Changes to SDK permission handling need careful review.
- ADR-0143 (Retry over Circuit Breaker): We use retry depth, not circuit breakers. SDK error handling changes must fit this model.
Spec Generation Guidelines
When to Create a Separate Spec
Create a separate spec (not included in the upgrade spec) when a feature:
- Requires new UI (user-facing changes beyond the runtime boundary)
- Requires new API routes or new service methods
- Requires schema changes (config, database)
- Has its own test surface (not just updating existing tests)
- Would take more than ~2 hours to implement
- Has dependencies beyond the SDK upgrade (e.g., needs a new MCP tool)
When to Include in the Upgrade Spec
Include in the main upgrade spec when a change is:
- A direct API migration (old call → new call, same behavior)
- A type update (new field in an existing type)
- A configuration passthrough (new option that maps directly)
- Test-only (updating test mocks/scenarios for new SDK behavior)
- Completable in under 30 minutes
Upgrade Spec Quality
A good upgrade spec:
- Links to research: Always reference the changelog and impact assessment documents
- Separates "must" from "should" from "nice to have": Breaking changes are non-negotiable; deprecation migrations are recommended; trivial feature adoptions are optional
- Orders tasks by dependency: Version bump first, then breaking change fixes, then deprecation migrations, then feature adoptions
- Includes rollback criteria: Under what conditions should we revert?
- Notes ADR implications: If the upgrade requires an ADR update, call it out explicitly
The Three Production Runtime SDKs
The Claude Agent SDK table above is the worked example; the same discipline applies to all three runtime SDKs, each with its own upgrade personality:
| SDK | Adapter | What makes its upgrades different |
|---|
@anthropic-ai/claude-agent-sdk | runtimes/claude-code | Richest surface (see table above); native-binary packaging changed at 0.2.113, so path resolution is version-sensitive |
@openai/codex-sdk | runtimes/codex | Versions track the Codex CLI train; active alpha dist-tag; event-mapper never exhaustiveness checks are the intended tripwire for new ThreadEvent/ThreadItem members (ADR-0309) |
@opencode-ai/sdk | runtimes/opencode | Client-only SDK that version-couples with the separately-shipped opencode-ai sidecar binary (ADR-0308); server-side release notes can matter more than client type changes; ignore snapshot tags |
Two gates are universal regardless of SDK:
- The conformance suite: every runtime must pass
runtimeConformance (@dorkos/test-utils) after a bump: run the adapter's suite (pnpm vitest run apps/server/src/services/runtimes/<runtime>) before calling any upgrade validated.
- The bump checklist:
contributing/adding-a-runtime.md (section: Bumping a pinned SDK) is the canonical validation sequence; the config's per-package upgrade_notes point to it and add package-specific judgment.
The same principles generalize to any future runtime dependency behind an abstraction boundary:
- Identify the boundary: What interface or module confines this dependency?
- Map the surface: Which files import from this dependency?
- Categorize changes: Breaking, deprecated, feature, fix, internal
- Assess through the boundary: How do changes inside the boundary affect code outside it?
- Separate upgrade from adoption: Bumping the version is one spec; adopting new features may be others
The .claude/config/runtime-deps.json file maps each runtime dependency to its boundary, codebase root, changelog sources, SDK surface map, related ADRs, and upgrade notes. Consult it before starting analysis, and keep it true when the integration surface changes.
