Opencode Runtime

OpenCode runtime alignment

Keep Palot's declared OpenCode dependencies aligned without replacing the user's running service. Stable is the default; use Beta when requested. A release check is read-only. A dependency upgrade authorizes workspace changes, not a global CLI update, service restart, app installation or publication.

Use opencode for upstream API and architecture questions. Read ../../../docs/opencode-runtime.md for Palot's current runtime-selection and compatibility contract. Public desktop packages acquire OpenCode separately; they do not bundle its standalone executable.

Read-only comparison

1. Establish Palot's baseline from apps/desktop/package.json, bun.lock and SUPPORTED_OPENCODE_VERSION in apps/desktop/src/main/opencode-version.ts. Distinguish these from the installed CLI and connected service versions.

2. Check npm tags for all four published units:

   npm view @opencode/cli dist-tags --json
   npm view @opencode/client dist-tags --json
   npm view @opencode/protocol dist-tags --json
   npm view @opencode/schema dist-tags --json

   A candidate is aligned only when the selected tags resolve to the same exact version. Verify that latest is a supported stable major; the tag alone is not a compatibility guarantee. Use that exact version for subsequent reads, and report tag skew instead of mixing releases.

3. If the question concerns the setup/settings channel selector, also check the official opencode.ai/update/api/{latest|beta}/cli/opencode feeds. These can differ from npm tags. Report each source separately; do not substitute one channel mechanism for another.

4. Read publication dates, release notes and published package dependencies/types. For a routine stable patch, inspect the changed contracts and relevant Palot callers. Identical contracts need no integration audit. Escalate to a deeper source comparison for a new minor/major, changed public surface, unreviewed beta, ambiguous release notes or a requested feature's availability.

5. Report the checked date, baseline/candidate, important inherited fixes versus changes needing Palot work, evidence gaps and a recommendation. Do not install packages, execute downloaded binaries or call APIs that can start a service as part of a read-only check.

For a deeper comparison, map both exact published builds to upstream source. Use release tags or publish-run inputs; numbered betas map to publish workflow run_number, not the run database ID or nearest timestamp. Do not infer a source branch from a channel name. Paginate commit comparisons and state any incomplete retrieval. Source explains intent; the published package establishes availability. Use opencode-coverage only when operation/event adoption needs an audit.

Authorized dependency update

1. Select an aligned exact version. Inspect relevant exports, request/response types and event unions before changing Palot callers. Stable 2.x compatibility is the existing product policy, not a reason to skip checking upstream changes.

2. Update directly imported client/protocol packages with the pinned toolchain:

   # Run with apps/desktop as the working directory; VERSION is the exact selection.
   vp add -D -E "@opencode/client@$VERSION" "@opencode/protocol@$VERSION"

   Let Vite+ and Bun update the lockfile. Schema stays transitive unless Palot starts importing it. Keep exact pins. Do not add the legacy @opencode-ai/sdk.

3. Align SUPPORTED_OPENCODE_VERSION and current runtime defaults, fixtures and verification metadata. Search for the old version and review each match; preserve reviewed-beta compatibility and historical evidence. Inspect retained runtime manifests, source/notice declarations and hash checks before changing them. An external-package policy is not permission to leave a used exact-version verifier stale, nor a reason to reintroduce bundled binaries.

4. Verify actual desktop module resolution for client/protocol, and schema from the client's context, against the lockfile. Bun can leave obsolete nested packages shadowing root packages. If proven, move only those obsolete entries into a unique primary-checkout .local/ backup and recheck. Don't delete the whole dependency tree as a first response.

5. Force the desktop TypeScript build after dependency changes:

   bun run --cwd apps/desktop typecheck --force

   Format/lint touched files and run affected contract/service tests. Use ../../../docs/agent-development.md to select native E2E or packaging checks. API-adoption changes may need a feature-specific runtime gate. Do not raise a blanket connection minimum just because a newer package adds an API.