feat: support cross-platform SDK paths

[somus]

Pull Request

Summary

• Add cross-platform SDK path resolution for store roots and default source adapters.
• Add explicit path overrides for Claude Code, Codex, Pi, and OpenCode adapters.
• Thread adapter path options through sessions defaults and add docs, changeset, and cross-platform CI coverage.

Related Issue

• N/A. Maintainer-directed change from this thread; no Linear issue was provided.

Public Impact

• No public contract change
• Spec or schema change
• Public package API change
• Changeset added or explicitly not needed
• CLI behavior change
• Public URL or docs behavior change

Impact description:

• @agent-trail/store now supports resolveStoreRoot({ storeRoot?, env?, platform? }) while preserving resolveStoreRoot(string).
• @agent-trail/adapters exposes adapter options for custom source paths.
• @agent-trail/sessions forwards the same default adapter option types.

Verification

• rtk bun test packages/store/src/tests/paths.test.ts
• rtk bun test packages/adapters/src/codex/tests/index.test.ts packages/adapters/src/pi/tests/index.test.ts
• rtk bun run build:declarations
• rtk bun test packages/store/src/tests/paths.test.ts packages/adapters/src/codex/tests/index.test.ts packages/adapters/src/opencode/tests/index.test.ts packages/adapters/src/claude-code/tests/index.test.ts packages/adapters/src/pi/tests/index.test.ts packages/sessions/src/tests/sessions.test.ts
• rtk mise run check:actions
• rtk mise x -- bun run check:changesets
• CI=true rtk mise run check
• GitHub checks passed: guardrails, preview, Continuous Releases, and cross-platform path tests on Ubuntu, macOS, and Windows.

Reviewer Notes

• First local full check without CI=true hit opt-in real-session smoke-test timeouts from local environment. CI-mode full check passes and hard-skips those real-session smoke tests as designed.

[stage-review]

Ready to review this PR? Stage has broken it down into 9 individual chapters for you:

	Title
1	Implement shared platform path utilities
2	Enable cross-platform store root resolution
3	Update Claude Code adapter path resolution
4	Update Codex adapter path resolution
5	Update Pi adapter path resolution
6	Update OpenCode adapter path resolution
7	Thread adapter options through sessions package
8	Finalize documentation and CI configuration
9	Other changes

_{Chapters generated by Stage for commit 1c134bd on Jun 16, 2026 10:01am UTC.}

[pkg-pr-new]

Open in StackBlitz

@agent-trail/adapter-kit

bun add https://pkg.pr.new/agent-trail/typescript-sdk/@agent-trail/adapter-kit@25

npm i https://pkg.pr.new/agent-trail/typescript-sdk/@agent-trail/adapter-kit@25

@agent-trail/adapters

bun add https://pkg.pr.new/agent-trail/typescript-sdk/@agent-trail/adapters@25

npm i https://pkg.pr.new/agent-trail/typescript-sdk/@agent-trail/adapters@25

@agent-trail/catalog

bun add https://pkg.pr.new/agent-trail/typescript-sdk/@agent-trail/catalog@25

npm i https://pkg.pr.new/agent-trail/typescript-sdk/@agent-trail/catalog@25

@agent-trail/core

bun add https://pkg.pr.new/agent-trail/typescript-sdk/@agent-trail/core@25

npm i https://pkg.pr.new/agent-trail/typescript-sdk/@agent-trail/core@25

@agent-trail/redact

bun add https://pkg.pr.new/agent-trail/typescript-sdk/@agent-trail/redact@25

npm i https://pkg.pr.new/agent-trail/typescript-sdk/@agent-trail/redact@25

@agent-trail/render-model

bun add https://pkg.pr.new/agent-trail/typescript-sdk/@agent-trail/render-model@25

npm i https://pkg.pr.new/agent-trail/typescript-sdk/@agent-trail/render-model@25

@agent-trail/schema

bun add https://pkg.pr.new/agent-trail/typescript-sdk/@agent-trail/schema@25

npm i https://pkg.pr.new/agent-trail/typescript-sdk/@agent-trail/schema@25

@agent-trail/sessions

bun add https://pkg.pr.new/agent-trail/typescript-sdk/@agent-trail/sessions@25

npm i https://pkg.pr.new/agent-trail/typescript-sdk/@agent-trail/sessions@25

@agent-trail/source-schemas

bun add https://pkg.pr.new/agent-trail/typescript-sdk/@agent-trail/source-schemas@25

npm i https://pkg.pr.new/agent-trail/typescript-sdk/@agent-trail/source-schemas@25

@agent-trail/store

bun add https://pkg.pr.new/agent-trail/typescript-sdk/@agent-trail/store@25

npm i https://pkg.pr.new/agent-trail/typescript-sdk/@agent-trail/store@25

@agent-trail/types

bun add https://pkg.pr.new/agent-trail/typescript-sdk/@agent-trail/types@25

npm i https://pkg.pr.new/agent-trail/typescript-sdk/@agent-trail/types@25

commit: 1c134bd

[kody-ai]

PR standard violation identified due to the missing Linear issue link and verification commands in the description. Populate the 'Related Issue' and 'Verification' sections as required by .github/PULL_REQUEST_TEMPLATE.md.

Kody rule violation: Follow Pull Request Standards

[somus]

Review loop complete.

Addressed findings:

• Fixed raw env vs path-option ambiguity in Codex and Pi path helpers, with regression coverage.
• Added adapter path resolution docs and updated the parser source matrix.
• Added a changeset for the public API additions.
• Added cross-platform path CI on Ubuntu, macOS, and Windows.
• Fixed Windows portability in store path tests and Pi fixture path tests.
• Restored PR template sections after the bot summary replaced the description.

Verification:

• rtk bun test packages/store/src/tests/paths.test.ts
• rtk bun test packages/adapters/src/codex/tests/index.test.ts packages/adapters/src/pi/tests/index.test.ts
• rtk bun test packages/adapters/src/pi/tests/index.test.ts
• rtk bun run build:declarations
• rtk bun test packages/store/src/tests/paths.test.ts packages/adapters/src/codex/tests/index.test.ts packages/adapters/src/opencode/tests/index.test.ts packages/adapters/src/claude-code/tests/index.test.ts packages/adapters/src/pi/tests/index.test.ts packages/sessions/src/tests/sessions.test.ts
• rtk mise run check:actions
• rtk mise x -- bun run check:changesets
• CI=true rtk mise run check
• GitHub checks passed on head 93511c6: guardrails, preview, Continuous Releases, and cross-platform path tests on Ubuntu, macOS, and Windows.

No remaining blocking review findings.

[kody-ai]

Kody Review Complete

Great news! 🎉
No issues were found that match your current review configurations.

Keep up the excellent work! 🚀

Kody Guide: Usage and Configuration

Interacting with Kody

• Request a Review: Ask Kody to review your PR manually by adding a comment with the @kody start-review command at the root of your PR.

• Validate Business Logic: Ask Kody to validate your code against business rules by adding a comment with the @kody -v business-logic command.

• Provide Feedback: Help Kody learn and improve by reacting to its comments with a 👍 for helpful suggestions or a 👎 if improvements are needed.

Current Kody Configuration

Review Options

The following review options are enabled or disabled:

Options	Enabled
Bug	✅
Performance	✅
Security	✅
Business Logic	✅

Access your configuration settings here.

​

[kody-ai]

PR standard violation in CLAUDE.md results from the missing Linear issue link. The rule 'Enforce pre-commit checks and PR standards' requires this reference regardless of the maintainer-directed origin.

[kody-ai]

Pull Request Standards violation occurs because the PR lacks the mandatory Linear issue link required by CLAUDE.md. Compliance requires an associated Linear issue even for maintainer-directed changes.

Kody rule violation: Follow Pull Request Standards