feat(opencode): add experimental HttpApi coverage

[Astro-Han]

Summary

Adds local Effect HttpApi declarations and handlers for ordinary experimental JSON routes: console, tool, resource, and worktree. The handlers reuse the existing Hono route Effect helpers so the service behavior stays shared.

Why

Related to #936. This expands local HttpApi migration coverage without switching the production server away from Hono. /experimental/session stays Hono-only in this PR because it owns pagination cursors, sort-specific next-cursor headers, and broader Session list internals that should be mirrored in a separate session-route slice.

Related Issue

Related to #936

Human Review Status

Pending

Review Focus

Please focus on whether the new HttpApi declarations exactly match the scoped experimental JSON routes, whether handlers preserve Hono body parsing and Worktree error status behavior, and whether the route inventory assertion is strong enough without touching automation, workspace, session, streaming, or websocket routes.

Risk Notes

/experimental/session is intentionally skipped because honest parity would broaden into Session pagination/cursor behavior beyond this PR. No visible UI or copy changed. No platform, packaging, docs, release notes, dependency, credential, generated-content, or local-file surface was touched.

How To Verify

bun test test/server/experimental-routes.test.ts: 9 pass
bun test test/server/route-inventory-harness.test.ts: 16 pass
git diff --check: pass
GOMAXPROCS=2 bun run typecheck: pass
Route inventory counts: Hono 128, local HttpApi 48, remaining Hono without local HttpApi 80

Screenshots or Recordings

Not applicable; no visible UI changes.

Checklist

• Type label — this PR carries exactly one of bug, enhancement, task, documentation. Type labels are author-added; the labeler bot does NOT assign them. Add the label in the GitHub UI, then tick this.
• Routing labels — this PR carries at least one of app, ui, platform, harness, ci. The labeler bot assigns these on PR open based on changed paths. Confirm the bot's choice (or override if wrong), then tick this.
• Priority label — this PR carries exactly one of P0, P1, P2, P3. The priority-triage bot suggests one on PR open. Confirm or override, then tick this.
• Human Review Status above is set to Pending, Approved by @<reviewer>, or Not required: <reason> (default is Pending; "not required" is restricted to bot-authored low-risk PRs).
• I linked the related issue, or stated in Summary why there is no issue.
• I described the review focus and any meaningful risks.
• I replaced the example block in How To Verify with the real verification steps and the key result for each.
• I did not introduce unrelated refactors, dependencies, generated files, or file changes beyond the stated scope.
• (conditional) I manually checked visible UI or copy changes when needed, with screenshots or recordings. Leave unticked only if no visible UI or copy changed.
• (conditional) I considered macOS and Windows impact for platform, packaging, updater, signing, paths, shell, or permissions changes. Leave unticked only if no platform/packaging surface was touched.
• (conditional) I called out docs, release notes, dependencies, permissions, credentials, deletion behavior, generated content, or local file changes when relevant. Leave unticked only if none of those surfaces was touched.
• I reviewed the final diff for unrelated changes and suspicious dependency changes.
• I am targeting dev, and my PR title and commit messages use Conventional Commits in English.

Summary by CodeRabbit

• New Features

  • Added experimental HTTP API endpoints for console operations (metadata, org switching).
  • Added experimental endpoints for tool discovery and listing.
  • Added experimental endpoints for managing git worktrees (create, list, remove, reset).
  • Added experimental endpoint for listing available resources.

• Tests

  • Added comprehensive test coverage for new experimental HTTP API routes and error handling.

[github-actions]

Suggested priority: P2 (includes non-doc, non-test paths outside the low-risk bucket).

P1/P0 are reserved for maintainer confirmation. Please relabel manually if this is a release blocker, security issue, data-loss risk, or updater/runtime failure.

[coderabbitai]

Warning

Review limit reached

@Astro-Han, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 44 minutes and 27 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, the refill rate gradually slows as usage increases. The highest same-day bursts are limited more strictly.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 095bacca-3cb0-4030-9848-e30520cf8e19

📥 Commits

Reviewing files that changed from the base of the PR and between 26ae6c4 and a8c926c.

📒 Files selected for processing (1)

• packages/opencode/src/server/routes/instance/httpapi/handlers/experimental.ts

📝 Walkthrough

Walkthrough

Ten instance-level handler functions in experimental.ts are changed from local to exported constants. A new ExperimentalApi HttpApi group is defined with path constants, schemas, and endpoint registrations. A corresponding experimentalHandlers module wires those endpoints to the exported handlers with JSON body parsing and error mapping. Tests are updated to use the HttpApi layer directly.

Changes

Experimental Routes HttpApi Migration

Layer / File(s)	Summary
Export instance-level handler functions packages/opencode/src/server/instance/experimental.ts	getConsoleState, listConsoleOrgs, switchConsoleOrg, listToolIDs, listTools, createWorktree, listWorktrees, removeWorktree, resetWorktree, and listResources are changed from local to exported named constants with no logic changes.
ExperimentalApi group: paths, schemas, and endpoints packages/opencode/src/server/routes/instance/httpapi/groups/experimental.ts	Defines ExperimentalPaths constants under /experimental, Schema types for console orgs/switching, tool queries/items, MCP resources, and worktree payloads, then registers all HTTP endpoints in ExperimentalApi with request/response schemas, BadRequestError, and OpenAPI annotations.
experimentalHandlers: body parsing, error mapping, and wiring packages/opencode/src/server/routes/instance/httpapi/handlers/experimental.ts	Defines Zod request body schemas, parseJsonBody helper returning 400 on malformed/invalid JSON, experimentalFailure mapping NamedError to 400/500 by error name prefix (Worktree* → 400), jsonResponse for uniform success serialization, and wires all endpoints via handleRaw.
HttpApi tests and route inventory coverage packages/opencode/test/server/experimental-routes.test.ts, packages/opencode/test/server/route-inventory-harness.test.ts	Adds requestExperimentalHttpApi test helper, updates OpenAPI spec assertion to use ExperimentalApi, adds happy-path endpoint tests, a regression test for DELETE /experimental/worktree returning 400 when session-bound, a malformed JSON test for POST /experimental/console/switch, and route inventory assertions that each experimental route has both hono and localHttpApi enabled.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• Astro-Han/pawwork#949: The route inventory harness test introduced in PR #949 is directly extended here with new assertions covering the experimental HttpApi endpoints.

Poem

🐇 Hop hop, the routes now shine,
Exported handlers in a line!
ExperimentalApi takes the stage,
With schemas writ on every page.
A 400 for the worktree bound,
And malformed JSON: errors found!
✨ The rabbit ships clean code tonight.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: adding experimental HttpApi coverage to the opencode package.
Description check	✅ Passed	The PR description follows the required template with all essential sections completed: Summary, Why, Related Issue, Human Review Status, Review Focus, Risk Notes, How To Verify, and a fully-ticked Checklist.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/i936-experimental-httpapi

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In
`@packages/opencode/src/server/routes/instance/httpapi/handlers/experimental.ts`:
- Line 26: The constant `WorktreeCreateBody` currently uses a Zod schema
reference (Worktree.CreateInput.optional()) but the file location requires
Effect Schema patterns per project guidelines. Replace the Zod schema definition
of `WorktreeCreateBody` with an Effect Schema equivalent that matches the
structure of `WorktreeCreatePayload` from groups/experimental.ts, ensuring it
includes the same optional fields for `name` and `startCommand`.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 7b0b721d-d3e9-4bc9-b6f2-4f6473f0ce50

📥 Commits

Reviewing files that changed from the base of the PR and between 84da0d9 and 26ae6c4.

📒 Files selected for processing (5)

• packages/opencode/src/server/instance/experimental.ts
• packages/opencode/src/server/routes/instance/httpapi/groups/experimental.ts
• packages/opencode/src/server/routes/instance/httpapi/handlers/experimental.ts
• packages/opencode/test/server/experimental-routes.test.ts
• packages/opencode/test/server/route-inventory-harness.test.ts