Skip to content

feat(codemode): add OpenAPI tool adapter#35192

Merged
rekram1-node merged 47 commits into
devfrom
codemode-openapi
Jul 4, 2026
Merged

feat(codemode): add OpenAPI tool adapter#35192
rekram1-node merged 47 commits into
devfrom
codemode-openapi

Conversation

@rekram1-node

@rekram1-node rekram1-node commented Jul 3, 2026

Copy link
Copy Markdown
Collaborator

Adds OpenAPI.fromSpec (exported as @opencode-ai/codemode/openapi): a basic OpenAPI 3.x document -> codemode tool subtree adapter, one tool per operation. The host places the subtree under a key in its tools tree; that key is the model-visible namespace.

Design

  • Auth is never model-visible. The adapter reads each operation's effective security (root default, operation override, security: [] / empty {} alternative = unauthenticated), picks the first satisfiable OR alternative (AND within one), and injects credentials from a host auth.resolve callback into the carrier the scheme declares. undefined from the resolver tries the next alternative; a failure aborts the call so an expired refresh token cannot fall through to unauthenticated.
  • Transport is an Effect service. Generated tools require HttpClient.HttpClient (effect/unstable/http) in R; hosts provide FetchHttpClient.layer or a custom/test layer. No new dependencies; the spec is a parsed document (hosts parse JSON/YAML themselves).
  • fromSpec is sync and total: returns { tools, skipped }. Operations it cannot represent (non-JSON request bodies, non-absolute server URLs) land in skipped with a reason instead of becoming broken tools.
  • Schemas: inputs group parameters by location (path/query/headers/body); outputs come from the first success (2xx/2XX) JSON response, no-content success -> null; #/components/schemas/* refs are shared as $defs so signatures expand referenced types. Reserved header parameters (Accept/Content-Type/Authorization) are ignored per the spec. Non-2xx responses become safe catchable tool failures carrying status + size-capped body summary.
  • Hardening: path parameters are URL-encoded with ./../empty rejected (URL retargeting), required query/header/body inputs fail before auth/network, operation names avoid CodeMode-blocked members, and record lookups keyed by spec/model-controlled names guard against prototype-inherited values.
  • Also extends the signature renderer with allOf (union members parenthesized) and teaches Services<Tools> to infer R from index-signature tool records.

Deliberately out of scope for a basic converter: YAML parsing, server URL templates/variables, path/operation-level server overrides, cookie parameters, multipart/binary bodies, and default-response schemas.

Verification

  • bun typecheck and bun test from packages/codemode (243 pass; 19 adapter tests covering auth semantics, carriers, resolver failure vs unavailability, unauthenticated alternatives, response-schema selection, naming sanitization/dedup/blocking, header precedence, required query/header preflight, path traversal rejection, and skipped reporting)
  • Reviewed by parallel focused agents (bugs, scope, comments, inlining, tests, Effect/API); findings addressed or explicitly descoped

@rekram1-node rekram1-node merged commit a8983bd into dev Jul 4, 2026
8 checks passed
@rekram1-node rekram1-node deleted the codemode-openapi branch July 4, 2026 21:17
Wiktor102 pushed a commit to Wiktor102/opencode that referenced this pull request Jul 5, 2026
drewr pushed a commit to drewr/opencode that referenced this pull request Jul 7, 2026
shaheislam pushed a commit to shaheislam/opencode-vim that referenced this pull request Jul 7, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant