feat(codemode): add OpenAPI tool adapter (#35362)

packages/codemode/AGENTS.md

@@ -5,6 +5,14 @@
 - Keep Code Mode unaware of host session, channel, and conversation models. The hosting application supplies trusted execution scope around it.
 - Tool schemas are the model-facing Interface. Keep arguments minimal and natural to the operation; never add unrelated IDs as ambient capability tokens.
 
+## OpenAPI
+
+- Generate an operation only when its transport semantics are supported; otherwise return a precise `skipped` reason.
+- Never guess parameter serialization or malformed security semantics. Unsupported serialization is skipped and malformed security fails closed.
+- Render unresolved schema constructs as `unknown`, never as invented TypeScript names.
+- Keep network reads bounded and map expected encoding, transport, and decoding failures to model-safe `ToolError` values.
+- Test supported behavior directly; do not reproduce adapter algorithms in tests.
+
 ## Future Design Notes
 
 - If a captured user-visible output channel returns (an earlier `output.text`/`output.file`/`output.image` API was removed from v1), keep `output` as its name, distinct from the program return value: `return` stays the structured result for the model, while `output.*` describes artifacts the host may render into a conversation or UI after execution. Keep this host-neutral and let applications decide how captured output is delivered. In v1, hosts collect media host-side (outside the sandbox) instead.

packages/codemode/README.md

@@ -152,6 +152,33 @@ interface ExecuteFailure {
 
 `onToolCallEnd` receives `{ index, name, input, durationMs, outcome, message? }` when an admitted call settles. `outcome` is `"success"` or `"failure"`; `message` is the model-safe failure message and is present only on failure. Interrupted calls (for example when the execution timeout fires) do not produce an end event. Both hooks are Effect-returning and must not fail.
 
+### OpenAPI tools
+
+`OpenAPI.fromSpec` turns an OpenAPI 3.x document into a tool subtree - one tool per operation. Dotted `operationId` values form namespaces such as `v2.session.get`. Missing IDs receive a flat method/path fallback such as `getUsersById`; names are sanitized and deduplicated. The host places the subtree under a key in its `tools` tree; that key is the model-visible namespace.
+
+```ts
+import { CodeMode, OpenAPI } from "@opencode-ai/codemode"
+import { Effect } from "effect"
+import { FetchHttpClient } from "effect/unstable/http"
+
+const api = OpenAPI.fromSpec({
+  spec: await Bun.file("openapi.json").json(), // parsed document (no YAML)
+  auth: {
+    resolve: ({ name, scopes, operation }) =>
+      name === "BearerAuth"
+        ? Effect.succeed({ type: "bearer", token })
+        : Effect.succeed(undefined),
+  },
+})
+
+const runtime = CodeMode.make({ tools: { opencode: api.tools } })
+const result = await Effect.runPromise(runtime.execute(code).pipe(Effect.provide(FetchHttpClient.layer)))
+```
+
+`fromSpec` is synchronous and returns `{ tools, skipped }`. The initial adapter supports query `form`/`deepObject`, path/header `simple`, JSON request bodies, JSON responses, and text responses; unsupported parameter encodings, non-JSON request bodies, binary responses, and streaming operations land in `skipped` instead of producing broken tools. Operation and path servers take precedence over document servers unless `baseUrl` explicitly overrides all of them. Tool inputs flatten path, query, header, and closed object-body fields into one model-facing object while retaining their HTTP locations internally. Cross-location name collisions receive a location prefix such as `path_id` and `query_id`; composed, nullable, dictionary, conditionally-required, and non-object JSON bodies remain under `body`. Auth is never model-visible. Responses are limited to 50 MiB, and non-2xx responses become safe tool failures carrying the status and a size-capped body summary. Deferred capabilities are tracked in `src/openapi/TODO.md`.
+
+Supported bearer, basic, header, and query authentication follows OpenAPI `security` semantics and is resolved host-side via `auth.resolve` - credential storage, OAuth flows, and token refresh never enter the compiler. Cookie authentication alternatives are discarded; an operation is skipped when it has no supported alternative. See the option docstrings in `src/openapi/types.ts` for the full semantics. Generated tools require `HttpClient.HttpClient` (from `effect/unstable/http`) in the Effect environment - provide `FetchHttpClient.layer` or a custom/test client layer at execution. The supplied client owns redirect policy; credentialed hosts should reject redirects or strip credentials when the origin changes.
+
 ## Discovery
 
 The agent-tool instructions use a budgeted catalog. Every tool namespace is always listed with its tool count regardless of budget, and as many complete tool signatures (each with a one-line description) as fit an estimated-token budget are inlined. Selection is round-robin across namespaces for fairness: in each round (namespaces alphabetical), every namespace still holding un-inlined tools attempts to place its next-cheapest signature line against the shared budget, and a namespace whose next line does not fit drops out while the others keep going - so every namespace gets some representation before any namespace gets everything. The instructions state exactly how comprehensive the list is, both overall (`COMPLETE list` vs `PARTIAL - N of M shown`) and per namespace (`(3 tools)`, `(3 tools, 1 shown)`, `(3 tools, none shown)`).

packages/codemode/src/index.ts

@@ -1,5 +1,6 @@
 export { ToolError, CodeMode, ExecuteInputSchema, ExecuteResultSchema, toolError } from "./codemode.js"
 export { Tool } from "./tool.js"
+export * as OpenAPI from "./openapi/index.js"
 export type { Definition as ToolDefinition, JsonSchema, ToolSchema } from "./tool.js"
 export type { ToolCallEnded, ToolCallHooks } from "./tool-runtime.js"
 export type {

packages/codemode/src/openapi/TODO.md

@@ -0,0 +1,19 @@
+# OpenAPI Follow-ups
+
+The initial adapter intentionally skips operations it cannot execute correctly. Future work may add:
+
+- Cookie parameters, authentication, and cookie-header merging.
+- Matrix, label, space-delimited, pipe-delimited, `allowReserved`, and parameter `content` serialization.
+- External references and complete nested `$defs` support.
+- Relative or templated server URLs and server variables.
+- Base URLs containing query strings or fragments.
+- Runtime response-schema validation and full content negotiation.
+- Binary response values and explicit byte-oriented return types.
+- Request/response projection for `readOnly` and `writeOnly` properties.
+- SSE, WebSocket, and other streaming transports.
+- Recovery of responses rejected by a status-filtering `HttpClient`.
+- Configurable request and response size limits.
+- Adapter-enforced redirect policy independent of the supplied `HttpClient`.
+- Strict UTF-8 and empty-body validation for JSON responses.
+- Compile-time rejection of parameter schemas with nested values unsupported by their serialization style; runtime rejects them before auth resolution.
+- Complete malformed-security-scheme validation and broader auth-combination coverage.

packages/codemode/src/openapi/index.ts

@@ -0,0 +1,130 @@
+import { HttpClient } from "effect/unstable/http"
+import { Tool, type Definition } from "../tool.js"
+import { invoke } from "./runtime.js"
+import {
+  componentDefinitions,
+  inputSchema,
+  isRecord,
+  methods,
+  nonEmptyString,
+  operationInput,
+  operationOutput,
+  operationPath,
+  operationSecurityRequirements,
+  securityRequirements,
+  securitySchemes,
+  specServerUrl,
+  validateBaseUrl,
+} from "./spec.js"
+import type { Operation, Options, Result, Skipped, Tools } from "./types.js"
+
+export type {
+  AuthResolver,
+  Credential,
+  Document,
+  Operation,
+  Options,
+  Result,
+  SecurityScheme,
+  Skipped,
+  Tools,
+} from "./types.js"
+
+/**
+ * Builds a CodeMode tool subtree from an OpenAPI 3.x document, one tool per
+ * operation. Auth is resolved host-side via `auth.resolve` and never
+ * model-visible. Tools require `HttpClient.HttpClient`; unrepresentable
+ * operations land in `skipped`.
+ */
+export const fromSpec = (options: Options): Result => {
+  const document = options.spec
+  const schemes = securitySchemes(document)
+  const defaultSecurity = securityRequirements(document.security)
+  const definitions = componentDefinitions(document)
+  const paths = isRecord(document.paths) ? document.paths : {}
+  const used = new Set<string>()
+  const namespaces = new Set<string>()
+  const skipped: Array<Skipped> = []
+  const tools = Object.create(null) as Tools
+
+  for (const [path, pathValue] of Object.entries(paths)) {
+    if (!isRecord(pathValue)) continue
+    for (const [method, operationValue] of Object.entries(pathValue)) {
+      if (!methods.has(method) || !isRecord(operationValue)) continue
+      const segments = operationPath(method, path, operationValue, used, namespaces)
+      const operation: Operation = {
+        operationId: nonEmptyString(operationValue.operationId),
+        method: method.toUpperCase(),
+        path,
+        summary: nonEmptyString(operationValue.summary),
+        description: nonEmptyString(operationValue.description),
+      }
+      const output = operationOutput(document, operationValue, definitions)
+      if (!output.ok) {
+        skipped.push({ method: operation.method, path, reason: output.reason })
+        continue
+      }
+
+      const resolvedBaseUrl = (() => {
+        if (options.baseUrl !== undefined) return validateBaseUrl(options.baseUrl)
+        if (operationValue.servers !== undefined) return specServerUrl(operationValue)
+        if (pathValue.servers !== undefined) return specServerUrl(pathValue)
+        return specServerUrl(document)
+      })()
+      if (!resolvedBaseUrl.ok) {
+        skipped.push({ method: operation.method, path, reason: resolvedBaseUrl.reason })
+        continue
+      }
+      const parsedInput = operationInput(document, pathValue, operationValue)
+      if (!parsedInput.ok) {
+        skipped.push({ method: operation.method, path, reason: parsedInput.reason })
+        continue
+      }
+      const input = parsedInput.value
+
+      const security = operationSecurityRequirements(operationValue.security, defaultSecurity, schemes)
+      if (!security.ok) {
+        skipped.push({ method: operation.method, path, reason: security.reason })
+        continue
+      }
+      const plan = {
+        operation,
+        url: `${resolvedBaseUrl.value.replace(/\/+$/, "")}${path}`,
+        fields: input.fields,
+        body: input.body,
+        security: security.value,
+        schemes,
+        auth: options.auth,
+        headers: options.headers ?? {},
+      }
+      used.add(segments.join("."))
+      for (const index of segments.slice(0, -1).keys()) namespaces.add(segments.slice(0, index + 1).join("."))
+      setTool(
+        tools,
+        segments,
+        Tool.make({
+          description: operation.description ?? operation.summary ?? `${operation.method} ${path}`,
+          input: inputSchema(input.fields, definitions),
+          output: output.value,
+          run: (input) => invoke(plan, input),
+        }),
+      )
+    }
+  }
+
+  return { tools, skipped }
+}
+
+const setTool = (tools: Tools, path: ReadonlyArray<string>, definition: Definition<HttpClient.HttpClient>): void => {
+  const [head, ...rest] = path
+  if (head === undefined) return
+  if (rest.length === 0) {
+    tools[head] = definition
+    return
+  }
+  const child = tools[head]
+  if (child === undefined || !isRecord(child) || child._tag === "CodeModeTool") {
+    tools[head] = Object.create(null) as Tools
+  }
+  setTool(tools[head] as Tools, rest, definition)
+}

packages/codemode/src/openapi/runtime.ts

@@ -0,0 +1,324 @@
+import { Effect, Option, Schema, Stream } from "effect"
+import { HttpClient, HttpClientRequest, HttpClientResponse, type HttpMethod } from "effect/unstable/http"
+import { ToolError, toolError } from "../tool-error.js"
+import { isRecord, own } from "./spec.js"
+import type { AppliedAuth, Credential, Plan, SecurityScheme } from "./types.js"
+
+const decodeJson = Schema.decodeUnknownOption(Schema.UnknownFromJsonString)
+const maxErrorBodyChars = 1_024
+const maxResponseBodyBytes = 50 * 1024 * 1024
+
+export const invoke = (plan: Plan, input: unknown): Effect.Effect<unknown, unknown, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const value = isRecord(input) ? input : {}
+
+    let request = yield* buildRequest(plan, value)
+
+    const auth = yield* resolveAuth(plan)
+    for (const [name, item] of Object.entries(auth.query)) {
+      request = HttpClientRequest.setUrlParam(request, name, item)
+    }
+    request = HttpClientRequest.setHeaders(request, auth.headers)
+
+    const client = yield* HttpClient.HttpClient
+    const response = yield* client
+      .execute(request)
+      .pipe(
+        Effect.catch((cause) =>
+          Effect.fail(toolError(`${plan.operation.method} ${plan.operation.path} failed: transport error`, cause)),
+        ),
+      )
+    const text = yield* readResponseBody(response, plan)
+    const mediaType = response.headers["content-type"]?.split(";")[0]?.trim().toLowerCase()
+    const json = mediaType === "application/json" || mediaType?.endsWith("+json") === true
+    const decoded = text === "" ? Option.some(null) : json ? decodeJson(text) : Option.none()
+    const parsed = json ? Option.getOrElse(decoded, () => text) : text === "" ? null : text
+    if (response.status < 200 || response.status >= 300) {
+      const rendered = typeof parsed === "string" ? parsed : (JSON.stringify(parsed) ?? "")
+      const summary =
+        rendered === "" || rendered === "null"
+          ? "no response body"
+          : rendered.length > maxErrorBodyChars
+            ? `${rendered.slice(0, maxErrorBodyChars)}...`
+            : rendered
+      return yield* Effect.fail(
+        toolError(`${plan.operation.method} ${plan.operation.path} failed with HTTP ${response.status}: ${summary}`),
+      )
+    }
+    if (json && Option.isNone(decoded)) {
+      return yield* Effect.fail(
+        toolError(`${plan.operation.method} ${plan.operation.path} returned malformed JSON.`),
+      )
+    }
+    return parsed
+  })
+
+const buildRequest = (
+  plan: Plan,
+  input: Readonly<Record<string, unknown>>,
+): Effect.Effect<HttpClientRequest.HttpClientRequest, ToolError> =>
+  Effect.gen(function* () {
+    // Validate every model-controlled value before auth resolution, which may refresh tokens.
+    const url = buildUrl(plan, input)
+    if (url instanceof ToolError) return yield* Effect.fail(url)
+    const missing = plan.fields.find(
+      (field) => field.required && field.location !== "path" && own(input, field.inputName) === undefined,
+    )
+    if (missing !== undefined) {
+      const label = missing.location === "body" ? "body field" : `${missing.location} parameter`
+      return yield* Effect.fail(toolError(`Missing required ${label} '${missing.inputName}'.`))
+    }
+
+    let request = HttpClientRequest.make(plan.operation.method as HttpMethod.HttpMethod)(url)
+    for (const field of plan.fields) {
+      if (field.location !== "query") continue
+      const item = own(input, field.inputName)
+      if (item === undefined) continue
+      const serialized = serializeQuery(request, field, item)
+      if (serialized instanceof ToolError) return yield* Effect.fail(serialized)
+      request = serialized
+    }
+
+    // Host headers first, then declared header parameters.
+    request = HttpClientRequest.setHeaders(request, plan.headers)
+    for (const field of plan.fields) {
+      if (field.location !== "header") continue
+      const item = own(input, field.inputName)
+      if (item === undefined) continue
+      const serialized = serializeSimple(field, item, String)
+      if (serialized instanceof ToolError) return yield* Effect.fail(serialized)
+      request = HttpClientRequest.setHeader(request, field.name, serialized)
+    }
+
+    const setBody = (value: unknown, mediaType: string) =>
+      HttpClientRequest.bodyJson(request, value).pipe(
+        Effect.map((next) => HttpClientRequest.setHeader(next, "content-type", mediaType)),
+        Effect.mapError((cause) =>
+          toolError(`Invalid JSON body for ${plan.operation.method} ${plan.operation.path}.`, cause),
+        ),
+      )
+    if (plan.body?.mode === "value") {
+      const field = plan.fields.find((field) => field.location === "body")
+      const body = field === undefined ? undefined : own(input, field.inputName)
+      if (body !== undefined) request = yield* setBody(body, plan.body.mediaType)
+    }
+    if (plan.body?.mode === "object") {
+      const entries = plan.fields.flatMap((field) => {
+        if (field.location !== "body") return []
+        const item = own(input, field.inputName)
+        return item === undefined ? [] : [[field.name, item] as const]
+      })
+      if (plan.body.required || entries.length > 0) {
+        request = yield* setBody(Object.fromEntries(entries), plan.body.mediaType)
+      }
+    }
+    return request
+  })
+
+const resolveAuth = (plan: Plan): Effect.Effect<AppliedAuth, unknown> =>
+  Effect.gen(function* () {
+    const none: AppliedAuth = { headers: {}, query: {} }
+    if (plan.security.length === 0) return none
+
+    const unavailable: Array<string> = []
+    alternatives: for (const requirement of plan.security) {
+      const names = Object.keys(requirement)
+      if (names.length === 0) return none
+      const credentials: Array<readonly [string, SecurityScheme, Credential]> = []
+      for (const name of names) {
+        const scheme = own(plan.schemes, name)
+        if (scheme === undefined || plan.auth === undefined) {
+          unavailable.push(name)
+          continue alternatives
+        }
+        const credential = yield* plan.auth.resolve({
+          name,
+          definition: scheme,
+          scopes: requirement[name] ?? [],
+          operation: plan.operation,
+        })
+        if (credential === undefined) {
+          unavailable.push(name)
+          continue alternatives
+        }
+        credentials.push([name, scheme, credential])
+      }
+      const applied = applyCredentials(credentials)
+      return applied instanceof ToolError ? yield* Effect.fail(applied) : applied
+    }
+
+    return yield* Effect.fail(
+      toolError(
+        `${plan.operation.method} ${plan.operation.path} requires authentication; no credential available for: ${[...new Set(unavailable)].join(", ")}.`,
+      ),
+    )
+  })
+
+const applyCredentials = (
+  credentials: ReadonlyArray<readonly [string, SecurityScheme, Credential]>,
+): AppliedAuth | ToolError => {
+  const headers = new Map<string, string>()
+  const query = new Map<string, string>()
+  const add = (carrier: "header" | "query", name: string, value: string): ToolError | undefined => {
+    const target = carrier === "header" ? headers : query
+    if (target.has(name)) return toolError(`Authentication resolves multiple credentials for ${carrier} '${name}'.`)
+    target.set(name, value)
+  }
+  for (const [name, definition, credential] of credentials) {
+    if (credential.type === "bearer") {
+      const duplicate = add("header", "authorization", `Bearer ${credential.token}`)
+      if (duplicate !== undefined) return duplicate
+      continue
+    }
+    if (credential.type === "basic") {
+      // Buffer instead of btoa: btoa throws on non-Latin-1 credentials.
+      const duplicate = add(
+        "header",
+        "authorization",
+        `Basic ${Buffer.from(`${credential.username}:${credential.password}`, "utf8").toString("base64")}`,
+      )
+      if (duplicate !== undefined) return duplicate
+      continue
+    }
+    if (credential.type === "header") {
+      const duplicate = add("header", credential.name.toLowerCase(), credential.value)
+      if (duplicate !== undefined) return duplicate
+      continue
+    }
+    // apiKey: the carrier comes from the scheme declaration.
+    if (definition.type !== "apiKey") {
+      return toolError(
+        `Security scheme '${name}' is not an apiKey scheme; resolve a bearer, basic, or header credential for it.`,
+      )
+    }
+    if (definition.in === "cookie") return toolError(`Cookie authentication '${name}' is not supported.`)
+    const parameter = definition.in === "header" ? definition.name.toLowerCase() : definition.name
+    const duplicate = add(definition.in, parameter, credential.value)
+    if (duplicate !== undefined) return duplicate
+  }
+  return { headers: Object.fromEntries(headers), query: Object.fromEntries(query) }
+}
+
+const buildUrl = (plan: Plan, input: Readonly<Record<string, unknown>>): string | ToolError => {
+  let url = plan.url
+  for (const field of plan.fields) {
+    if (field.location !== "path") continue
+    const item = own(input, field.inputName)
+    if (item === undefined) {
+      return toolError(`Missing required path parameter '${field.inputName}'.`)
+    }
+    const fieldValue = serializeSimple(field, item, (value) =>
+      encodeURIComponent(value).replace(/[!'()*]/g, (character) =>
+        `%${character.charCodeAt(0).toString(16).toUpperCase()}`,
+      ),
+    )
+    if (fieldValue instanceof ToolError) return fieldValue
+    // '.'/'..' survive encoding and URL normalization collapses them, letting a
+    // model-supplied value retarget the request to a different endpoint.
+    if (fieldValue === "" || fieldValue === "." || fieldValue === "..") {
+      return toolError(`Invalid path parameter '${field.inputName}'.`)
+    }
+    url = url.replaceAll(`{${field.name}}`, fieldValue)
+  }
+  const unresolved = url.match(/\{[^{}]+\}/)
+  if (unresolved !== null) return toolError(`Unresolved path parameter ${unresolved[0]}.`)
+  return url
+}
+
+const serializeSimple = (
+  field: Plan["fields"][number],
+  value: unknown,
+  encode: (value: string) => string,
+): string | ToolError => {
+  const scalar = (item: unknown): string | ToolError =>
+    item !== null && typeof item !== "string" && typeof item !== "number" && typeof item !== "boolean"
+      ? toolError(`Parameter '${field.inputName}' contains an unsupported nested value.`)
+      : encode(String(item))
+  if (Array.isArray(value)) {
+    const items = value.map(scalar)
+    const invalid = items.find((item): item is ToolError => item instanceof ToolError)
+    return invalid ?? items.join(",")
+  }
+  if (!isRecord(value)) return scalar(value)
+  const entries = Object.entries(value).flatMap<string | ToolError>(([name, item]) => {
+    const rendered = scalar(item)
+    if (rendered instanceof ToolError) return [rendered]
+    return field.explode ? [`${encode(name)}=${rendered}`] : [encode(name), rendered]
+  })
+  const invalid = entries.find((item): item is ToolError => item instanceof ToolError)
+  return invalid ?? entries.join(",")
+}
+
+const serializeQuery = (
+  request: HttpClientRequest.HttpClientRequest,
+  field: Plan["fields"][number],
+  value: unknown,
+): HttpClientRequest.HttpClientRequest | ToolError => {
+  if (field.style === "deepObject") {
+    if (!isRecord(value)) return toolError(`Deep-object parameter '${field.inputName}' must be an object.`)
+    return Object.entries(value).reduce<HttpClientRequest.HttpClientRequest | ToolError>((current, [name, item]) => {
+      if (current instanceof ToolError) return current
+      if (item === undefined || (item !== null && typeof item === "object")) {
+        return toolError(`Deep-object parameter '${field.inputName}' contains an unsupported nested value.`)
+      }
+      return HttpClientRequest.appendUrlParam(current, `${field.name}[${name}]`, String(item))
+    }, request)
+  }
+  if (Array.isArray(value)) {
+    const rendered = serializeSimple(field, value, String)
+    if (rendered instanceof ToolError) return rendered
+    if (!field.explode) return HttpClientRequest.appendUrlParam(request, field.name, rendered)
+    if (value.some((item) => item === undefined || (item !== null && typeof item === "object"))) {
+      return toolError(`Query parameter '${field.inputName}' contains an unsupported nested value.`)
+    }
+    return value.reduce(
+      (current, item) => HttpClientRequest.appendUrlParam(current, field.name, String(item)),
+      request,
+    )
+  }
+  if (isRecord(value) && field.explode) {
+    return Object.entries(value).reduce<HttpClientRequest.HttpClientRequest | ToolError>((current, [name, item]) => {
+      if (current instanceof ToolError) return current
+      if (item === undefined || (item !== null && typeof item === "object")) {
+        return toolError(`Query parameter '${field.inputName}' contains an unsupported nested value.`)
+      }
+      return HttpClientRequest.appendUrlParam(current, name, String(item))
+    }, request)
+  }
+  const rendered = serializeSimple(field, value, String)
+  return rendered instanceof ToolError ? rendered : HttpClientRequest.appendUrlParam(request, field.name, rendered)
+}
+
+const readResponseBody = (response: HttpClientResponse.HttpClientResponse, plan: Plan): Effect.Effect<string, ToolError> =>
+  Effect.gen(function* () {
+    const contentLength = response.headers["content-length"]
+    const parsedSize = contentLength === undefined ? undefined : Number.parseInt(contentLength, 10)
+    const declaredSize = parsedSize !== undefined && Number.isSafeInteger(parsedSize) && parsedSize >= 0 ? parsedSize : undefined
+    if (declaredSize !== undefined && declaredSize > maxResponseBodyBytes) {
+      return yield* Effect.fail(toolError(`${plan.operation.method} ${plan.operation.path} response exceeds 50 MiB.`))
+    }
+    let body = Buffer.allocUnsafe(Math.min(maxResponseBodyBytes, declaredSize ?? 64 * 1024))
+    let size = 0
+    yield* Stream.runForEach(response.stream, (chunk) => {
+      if (size + chunk.byteLength > maxResponseBodyBytes) {
+        return Effect.fail(toolError(`${plan.operation.method} ${plan.operation.path} response exceeds 50 MiB.`))
+      }
+      if (size + chunk.byteLength > body.byteLength) {
+        const grown = Buffer.allocUnsafe(Math.min(maxResponseBodyBytes, Math.max(size + chunk.byteLength, body.byteLength * 2)))
+        body.copy(grown, 0, 0, size)
+        body = grown
+      }
+      body.set(chunk, size)
+      size += chunk.byteLength
+      return Effect.void
+    }).pipe(
+      Effect.catch((cause) => {
+        if (cause instanceof ToolError) return Effect.fail(cause)
+        if (cause.reason._tag === "EmptyBodyError") return Effect.void
+        return Effect.fail(
+          toolError(`${plan.operation.method} ${plan.operation.path} failed while reading the response body.`, cause),
+        )
+      }),
+    )
+    return new TextDecoder().decode(body.subarray(0, size))
+  })

packages/codemode/src/openapi/spec.ts

@@ -0,0 +1,507 @@
+import { fromSchemaOpenApi3_0, fromSchemaOpenApi3_1 } from "effect/JsonSchema"
+import type { JsonSchema } from "../tool.js"
+import { isBlockedMember } from "../tool-runtime.js"
+import type {
+  Body,
+  Document,
+  InputField,
+  OperationInput,
+  Parsed,
+  SecurityRequirement,
+  SecurityScheme,
+} from "./types.js"
+
+export const methods = new Set(["get", "put", "post", "delete", "options", "head", "patch", "trace"])
+const parameterLocations = ["path", "query", "header"] as const
+const ignoredHeaderParameters = new Set(["accept", "content-type", "authorization"])
+
+export const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value)
+
+const asArray = (value: unknown): ReadonlyArray<unknown> => (Array.isArray(value) ? value : [])
+
+export const nonEmptyString = (value: unknown): string | undefined =>
+  typeof value === "string" && value !== "" ? value : undefined
+
+// Guards record lookups keyed by spec- or model-controlled names against
+// prototype-inherited values (e.g. a parameter named `toString`).
+export const own = <T>(record: Readonly<Record<string, T>>, key: string): T | undefined =>
+  Object.hasOwn(record, key) ? record[key] : undefined
+
+export const resolve = (document: Document, value: unknown): unknown => {
+  const next = (current: unknown, seen: ReadonlySet<string>): unknown => {
+    if (!isRecord(current)) return current
+    const ref = nonEmptyString(current.$ref)
+    if (ref === undefined || !ref.startsWith("#/") || seen.has(ref)) return current
+    const target = ref
+      .slice(2)
+      .split("/")
+      .map((segment) => segment.replaceAll("~1", "/").replaceAll("~0", "~"))
+      .reduce<unknown>((item, segment) => (isRecord(item) ? own(item, segment) : undefined), document)
+    return target === undefined ? current : next(target, new Set([...seen, ref]))
+  }
+  return next(value, new Set())
+}
+
+const projectSchema = (document: Document, value: unknown): JsonSchema => {
+  if (!isRecord(value)) return {}
+  const normalized = nonEmptyString(document.openapi)?.startsWith("3.0")
+    ? fromSchemaOpenApi3_0(value)
+    : fromSchemaOpenApi3_1(value)
+  return Object.keys(normalized.definitions).length === 0
+    ? normalized.schema
+    : { ...normalized.schema, $defs: normalized.definitions }
+}
+
+export const componentDefinitions = (document: Document): Readonly<Record<string, JsonSchema>> => {
+  const components = isRecord(document.components) ? document.components : {}
+  const schemas = isRecord(components.schemas) ? components.schemas : {}
+  return Object.fromEntries(Object.entries(schemas).map(([name, value]) => [name, projectSchema(document, value)]))
+}
+
+const withDefinitions = (schema: JsonSchema, definitions: Readonly<Record<string, JsonSchema>>): JsonSchema => {
+  if (Object.keys(definitions).length === 0) return schema
+  const local = isRecord(schema.$defs) ? schema.$defs : {}
+  return { ...schema, $defs: { ...definitions, ...local } }
+}
+
+const isJsonMediaType = (mediaType: string): boolean => {
+  const normalized = mediaType.split(";")[0]?.trim().toLowerCase() ?? ""
+  return normalized === "application/json" || normalized.endsWith("+json")
+}
+
+const isBinaryMediaType = (document: Document, mediaType: string, value: unknown): boolean => {
+  const normalized = mediaType.split(";")[0]?.trim().toLowerCase() ?? ""
+  if (!isJsonMediaType(normalized) && !normalized.startsWith("text/")) return true
+  if (!isRecord(value)) return false
+  const schema = resolve(document, value.schema)
+  return isRecord(schema) && schema.format === "binary"
+}
+
+const jsonContent = (content: Record<string, unknown>): { readonly mediaType: string; readonly schema: unknown } | undefined => {
+  const entry = Object.entries(content).find(([mediaType]) => isJsonMediaType(mediaType))
+  return entry !== undefined && isRecord(entry[1]) ? { mediaType: entry[0], schema: entry[1].schema } : undefined
+}
+
+const isFlattenableObjectBody = (
+  schema: unknown,
+  requestRequired: boolean,
+): schema is Record<string, unknown> & { readonly properties: Record<string, unknown> } =>
+  isRecord(schema) &&
+  requestRequired &&
+  schema.type === "object" &&
+  isRecord(schema.properties) &&
+  schema.additionalProperties === false &&
+  schema.nullable !== true &&
+  schema.allOf === undefined &&
+  schema.anyOf === undefined &&
+  schema.oneOf === undefined
+
+type PlannedField = Omit<InputField, "inputName">
+
+const operationParameters = (
+  document: Document,
+  pathItem: Record<string, unknown>,
+  operation: Record<string, unknown>,
+): Parsed<ReadonlyArray<PlannedField>> => {
+  // Operation-level parameters override path-level ones sharing (location, name).
+  const declared = new Map<
+    string,
+    { readonly name: string; readonly location: string; readonly parameter: Record<string, unknown> }
+  >()
+  for (const raw of [...asArray(pathItem.parameters), ...asArray(operation.parameters)]) {
+    const resolved = resolve(document, raw)
+    if (!isRecord(resolved)) return { ok: false, reason: "parameter declaration is invalid or unresolved" }
+    const name = nonEmptyString(resolved.name)
+    const location = nonEmptyString(resolved.in)
+    if (name === undefined || location === undefined)
+      return { ok: false, reason: "parameter declaration is missing name or location" }
+    declared.set(`${location}:${name}`, { name, location, parameter: resolved })
+  }
+  const unordered: Array<PlannedField> = []
+  for (const item of declared.values()) {
+    const name = item.name
+    const location = item.location
+    const resolved = item.parameter
+    if (location === "cookie") return { ok: false, reason: `cookie parameter '${name}' is not supported` }
+    if (location !== "path" && location !== "query" && location !== "header") {
+      return { ok: false, reason: `parameter '${name}' uses unsupported location '${location}'` }
+    }
+    if (location === "header" && ignoredHeaderParameters.has(name.toLowerCase())) continue
+    if (resolved.schema === undefined && resolved.content === undefined) {
+      return { ok: false, reason: `parameter '${name}' declares neither schema nor content` }
+    }
+    if (resolved.content !== undefined)
+      return { ok: false, reason: `parameter '${name}' uses unsupported content encoding` }
+    if (resolved.style !== undefined && nonEmptyString(resolved.style) === undefined) {
+      return { ok: false, reason: `parameter '${name}' has an invalid style` }
+    }
+    if (resolved.explode !== undefined && typeof resolved.explode !== "boolean") {
+      return { ok: false, reason: `parameter '${name}' has an invalid explode value` }
+    }
+    if (resolved.allowReserved !== undefined && typeof resolved.allowReserved !== "boolean") {
+      return { ok: false, reason: `parameter '${name}' has an invalid allowReserved value` }
+    }
+    if (resolved.allowReserved === true)
+      return { ok: false, reason: `parameter '${name}' uses unsupported allowReserved encoding` }
+    const declaredStyle = nonEmptyString(resolved.style) ?? (location === "query" ? "form" : "simple")
+    if (location === "query" && declaredStyle !== "form" && declaredStyle !== "deepObject") {
+      return { ok: false, reason: `query parameter '${name}' uses unsupported style '${declaredStyle}'` }
+    }
+    if (location !== "query" && declaredStyle !== "simple") {
+      return { ok: false, reason: `${location} parameter '${name}' uses unsupported style '${declaredStyle}'` }
+    }
+    const style = declaredStyle === "deepObject" ? "deepObject" : declaredStyle === "form" ? "form" : "simple"
+    const explode = typeof resolved.explode === "boolean" ? resolved.explode : style === "form"
+    if (style === "deepObject" && !explode) {
+      return { ok: false, reason: `query parameter '${name}' uses deepObject with explode=false` }
+    }
+    const base = projectSchema(document, resolved.schema)
+    const description = nonEmptyString(resolved.description)
+    unordered.push({
+      name,
+      location,
+      required: resolved.required === true || location === "path",
+      style,
+      explode,
+      schema: {
+        ...base,
+        ...(base.description === undefined && description !== undefined ? { description } : {}),
+      },
+    })
+  }
+  return {
+    ok: true,
+    value: parameterLocations.flatMap((location) => unordered.filter((field) => field.location === location)),
+  }
+}
+
+const operationBody = (
+  document: Document,
+  operation: Record<string, unknown>,
+): Parsed<{ readonly fields: ReadonlyArray<PlannedField>; readonly body: Body | undefined }> => {
+  const resolved = resolve(document, operation.requestBody)
+  if (!isRecord(resolved)) return { ok: true, value: { fields: [], body: undefined } }
+  const content = isRecord(resolved.content) ? resolved.content : {}
+  const selected = jsonContent(content)
+  if (selected === undefined) {
+    return {
+      ok: false,
+      reason: `request body has no JSON content (declared: ${Object.keys(content).join(", ") || "none"})`,
+    }
+  }
+  const schema = resolve(document, selected.schema)
+  const required = resolved.required === true
+  if (!isFlattenableObjectBody(schema, required)) {
+    return {
+      ok: true,
+      value: {
+        fields: [
+          {
+            name: "body",
+            location: "body",
+            required,
+            schema: projectSchema(document, selected.schema),
+            style: undefined,
+            explode: undefined,
+          },
+        ],
+        body: { required, mode: "value", mediaType: selected.mediaType },
+      },
+    }
+  }
+  const requiredProperties = new Set(
+    Array.isArray(schema.required) ? schema.required.filter((item): item is string => typeof item === "string") : [],
+  )
+  return {
+    ok: true,
+    value: {
+      fields: Object.entries(schema.properties).map(([name, value]) => ({
+        name,
+        location: "body" as const,
+        required: required && requiredProperties.has(name),
+        schema: projectSchema(document, value),
+        style: undefined,
+        explode: undefined,
+      })),
+      body: { required, mode: "object", mediaType: selected.mediaType },
+    },
+  }
+}
+
+export const operationInput = (
+  document: Document,
+  pathItem: Record<string, unknown>,
+  operation: Record<string, unknown>,
+): Parsed<OperationInput> => {
+  const parameters = operationParameters(document, pathItem, operation)
+  if (!parameters.ok) return parameters
+  const requestBody = operationBody(document, operation)
+  if (!requestBody.ok) return requestBody
+  const fields = [...parameters.value, ...requestBody.value.fields]
+
+  const conflicts = new Set(
+    [...Map.groupBy(fields, (field) => field.name)]
+      .filter(([, matches]) => new Set(matches.map((field) => field.location)).size > 1)
+      .map(([name]) => name),
+  )
+  const used = new Set<string>()
+  return {
+    ok: true,
+    value: {
+      fields: fields.map((field) => {
+        const visibleName = isBlockedMember(field.name) ? `${field.name}_2` : field.name
+        const base = conflicts.has(field.name) ? `${field.location}_${visibleName}` : visibleName
+        const next = (index: number): string => {
+          const candidate = index === 1 ? base : `${base}_${index}`
+          return used.has(candidate) ? next(index + 1) : candidate
+        }
+        const inputName = next(1)
+        used.add(inputName)
+        return { ...field, inputName }
+      }),
+      body: requestBody.value.body,
+    },
+  }
+}
+
+export const inputSchema = (
+  fields: ReadonlyArray<InputField>,
+  definitions: Readonly<Record<string, JsonSchema>>,
+): JsonSchema => {
+  const required = fields.filter((field) => field.required).map((field) => field.inputName)
+  return withDefinitions(
+    {
+      type: "object",
+      properties: Object.fromEntries(fields.map((field) => [field.inputName, field.schema])),
+      ...(required.length === 0 ? {} : { required }),
+    },
+    definitions,
+  )
+}
+
+const successfulResponses = (
+  document: Document,
+  operation: Record<string, unknown>,
+): Parsed<ReadonlyArray<Record<string, unknown>>> => {
+  if (!isRecord(operation.responses)) return { ok: true, value: [] }
+  const entries = Object.entries(operation.responses)
+  const selected = [
+    ...entries.filter(([status]) => /^2\d\d$/.test(status)).sort(([a], [b]) => a.localeCompare(b)),
+    ...entries.filter(([status]) => status.toUpperCase() === "2XX"),
+  ]
+  const responses: Array<Record<string, unknown>> = []
+  for (const [, value] of selected) {
+    const resolved = resolve(document, value)
+    if (!isRecord(resolved) || nonEmptyString(resolved.$ref) !== undefined) {
+      return { ok: false, reason: "successful response declaration is invalid or unresolved" }
+    }
+    responses.push(resolved)
+  }
+  return { ok: true, value: responses }
+}
+
+export const operationOutput = (
+  document: Document,
+  operation: Record<string, unknown>,
+  definitions: Readonly<Record<string, JsonSchema>>,
+): Parsed<JsonSchema | undefined> => {
+  if (operation["x-websocket"] === true) return { ok: false, reason: "WebSocket operations are not supported" }
+  const responses = successfulResponses(document, operation)
+  if (!responses.ok) return responses
+  const streams = responses.value.some(
+    (response) =>
+      isRecord(response.content) &&
+      Object.keys(response.content).some(
+        (mediaType) => mediaType.split(";")[0]?.trim().toLowerCase() === "text/event-stream",
+      ),
+  )
+  if (streams) return { ok: false, reason: "SSE operations are not supported" }
+  const binary = responses.value.some(
+    (response) =>
+      isRecord(response.content) &&
+      Object.entries(response.content).some(([mediaType, value]) => isBinaryMediaType(document, mediaType, value)),
+  )
+  if (binary) return { ok: false, reason: "binary responses are not supported" }
+
+  const outcomes: Array<JsonSchema> = []
+  for (const response of responses.value) {
+    if (response.content !== undefined && !isRecord(response.content)) return { ok: true, value: undefined }
+    const content = isRecord(response.content) ? response.content : {}
+    if (Object.keys(content).length === 0) {
+      outcomes.push({ type: "null" })
+      continue
+    }
+    for (const [mediaType, value] of Object.entries(content)) {
+      if (!isJsonMediaType(mediaType)) {
+        outcomes.push({ type: "string" })
+        continue
+      }
+      if (!isRecord(value) || value.schema === undefined) return { ok: true, value: undefined }
+      outcomes.push(projectSchema(document, value.schema))
+    }
+  }
+  if (outcomes.length === 0) return { ok: true, value: undefined }
+  return {
+    ok: true,
+    value: withDefinitions(outcomes.length === 1 ? outcomes[0] ?? {} : { anyOf: outcomes }, definitions),
+  }
+}
+
+const sanitizeOperationSegment = (raw: string): string => {
+  const base =
+    raw
+      .replaceAll(/[^A-Za-z0-9_$]+/g, "_")
+      .replace(/^_+|_+$/g, "")
+      .replace(/^([0-9])/, "_$1") || "operation"
+  return isBlockedMember(base) ? `${base}_2` : base
+}
+
+const fallbackOperationId = (method: string, path: string): string =>
+  [
+    method,
+    ...path
+      .split("/")
+      .filter((part) => part !== "")
+      .flatMap((part) => (part.startsWith("{") && part.endsWith("}") ? ["by", part.slice(1, -1)] : [part]))
+      .flatMap((part) => part.split(/[^A-Za-z0-9]+/).filter((word) => word !== "")),
+  ]
+    .map((word, index) => {
+      const lower = word.toLowerCase()
+      return index === 0 ? lower : `${lower.charAt(0).toUpperCase()}${lower.slice(1)}`
+    })
+    .join("")
+
+export const operationPath = (
+  method: string,
+  path: string,
+  operation: Record<string, unknown>,
+  used: ReadonlySet<string>,
+  namespaces: ReadonlySet<string>,
+): ReadonlyArray<string> => {
+  const raw = nonEmptyString(operation.operationId)
+  const segments = (raw === undefined ? [fallbackOperationId(method, path)] : raw.split(".")).map(sanitizeOperationSegment)
+  if (isOperationPathAvailable(segments, used, namespaces)) return segments
+  const conflict = segments.slice(0, -1).findIndex((_, index) => used.has(segments.slice(0, index + 1).join(".")))
+  if (conflict >= 0 && conflict + 1 < segments.length) {
+    const collapsed = segments.flatMap((segment, index) => {
+      if (index === conflict) {
+        const next = segments[index + 1] ?? ""
+        return [`${segment}${next.charAt(0).toUpperCase()}${next.slice(1)}`]
+      }
+      return index === conflict + 1 ? [] : [segment]
+    })
+    if (isOperationPathAvailable(collapsed, used, namespaces)) return collapsed
+  }
+  const fallback = segments.join("_")
+  const next = (index: number): string => {
+    const candidate = `${fallback}_${index}`
+    return isOperationPathAvailable([candidate], used, namespaces) ? candidate : next(index + 1)
+  }
+  return [next(2)]
+}
+
+const isOperationPathAvailable = (
+  segments: ReadonlyArray<string>,
+  used: ReadonlySet<string>,
+  namespaces: ReadonlySet<string>,
+): boolean => {
+  const key = segments.join(".")
+  if (used.has(key) || namespaces.has(key)) return false
+  return segments.slice(0, -1).every((_, index) => !used.has(segments.slice(0, index + 1).join(".")))
+}
+
+export const specServerUrl = (source: Record<string, unknown>): Parsed<string> => {
+  const server = asArray(source.servers).find(isRecord)
+  const url = server === undefined ? undefined : nonEmptyString(server.url)
+  if (url === undefined) return { ok: false, reason: "spec declares no servers; pass baseUrl" }
+  if (/\{[^{}]+\}/.test(url)) {
+    return { ok: false, reason: `server URL '${url}' is not an absolute URL; pass baseUrl` }
+  }
+  return validateBaseUrl(url)
+}
+
+export const validateBaseUrl = (value: string): Parsed<string> => {
+  if (!/^https?:\/\//i.test(value)) return { ok: false, reason: `server URL '${value}' is not an absolute HTTP(S) URL` }
+  const url = URL.parse(value)
+  if (url === null || (url.protocol !== "http:" && url.protocol !== "https:")) {
+    return { ok: false, reason: `server URL '${value}' is not an absolute HTTP(S) URL` }
+  }
+  if (url.search !== "" || url.hash !== "") {
+    return { ok: false, reason: `server URL '${value}' contains an unsupported query string or fragment` }
+  }
+  return { ok: true, value }
+}
+
+export const securityRequirements = (value: unknown): Parsed<ReadonlyArray<SecurityRequirement>> => {
+  if (value === undefined) return { ok: true, value: [] }
+  if (!Array.isArray(value)) return { ok: false, reason: "security declaration is not an array" }
+  const requirements: Array<SecurityRequirement> = []
+  for (const item of value) {
+    if (!isRecord(item)) return { ok: false, reason: "security requirement is not an object" }
+    const requirement = Object.create(null) as Record<string, ReadonlyArray<string>>
+    for (const [name, scopes] of Object.entries(item)) {
+      if (!Array.isArray(scopes)) return { ok: false, reason: "security requirement scopes are not string arrays" }
+      const parsed = scopes.filter((scope): scope is string => typeof scope === "string")
+      if (parsed.length !== scopes.length) {
+        return { ok: false, reason: "security requirement scopes are not string arrays" }
+      }
+      requirement[name] = parsed
+    }
+    requirements.push(requirement)
+  }
+  return { ok: true, value: requirements }
+}
+
+export const operationSecurityRequirements = (
+  value: unknown,
+  defaults: Parsed<ReadonlyArray<SecurityRequirement>>,
+  schemes: Readonly<Record<string, SecurityScheme>>,
+): Parsed<ReadonlyArray<SecurityRequirement>> => {
+  const parsed = value === undefined ? defaults : securityRequirements(value)
+  if (!parsed.ok) return parsed
+  const supported = parsed.value.filter((requirement) =>
+    Object.keys(requirement).every((name) => {
+      const scheme = own(schemes, name)
+      return scheme !== undefined && !(scheme.type === "apiKey" && scheme.in === "cookie")
+    }),
+  )
+  if (parsed.value.length === 0 || supported.length > 0) return { ok: true, value: supported }
+
+  const names = [...new Set(parsed.value.flatMap((requirement) => Object.keys(requirement)))]
+  const cookieScheme = names.find((name) => {
+    const definition = own(schemes, name)
+    return definition?.type === "apiKey" && definition.in === "cookie"
+  })
+  return {
+    ok: false,
+    reason:
+      cookieScheme === undefined
+        ? `security requirement references missing or malformed scheme: ${names.join(", ")}`
+        : `cookie authentication '${cookieScheme}' is not supported`,
+  }
+}
+
+export const securitySchemes = (document: Document): Readonly<Record<string, SecurityScheme>> => {
+  const components = isRecord(document.components) ? document.components : {}
+  const declared = isRecord(components.securitySchemes) ? components.securitySchemes : {}
+  return Object.fromEntries(
+    Object.entries(declared).flatMap<readonly [string, SecurityScheme]>(([name, value]) => {
+      const resolved = resolve(document, value)
+      if (!isRecord(resolved)) return []
+      const type = nonEmptyString(resolved.type)
+      if (type === "apiKey") {
+        const carrier = nonEmptyString(resolved.in)
+        const parameter = nonEmptyString(resolved.name)
+        if (parameter === undefined || (carrier !== "header" && carrier !== "query" && carrier !== "cookie")) return []
+        return [[name, { type, name: parameter, in: carrier }] as const]
+      }
+      if (type === "http") {
+        const scheme = nonEmptyString(resolved.scheme)?.toLowerCase()
+        return scheme === undefined ? [] : [[name, { type, scheme }] as const]
+      }
+      if (type === "oauth2" || type === "openIdConnect") return [[name, { type }] as const]
+      return []
+    }),
+  )
+}

packages/codemode/src/openapi/types.ts

@@ -0,0 +1,112 @@
+import { Effect } from "effect"
+import { HttpClient } from "effect/unstable/http"
+import type { Definition, JsonSchema } from "../tool.js"
+
+/** A parsed OpenAPI 3.x document. YAML must be parsed by the host. */
+export type Document = Record<string, unknown>
+
+/** The operation identity handed to auth resolution and errors. */
+export type Operation = {
+  readonly operationId: string | undefined
+  readonly method: string
+  readonly path: string
+  readonly summary: string | undefined
+  readonly description: string | undefined
+}
+
+/** A resolved OpenAPI security scheme from `components.securitySchemes`. */
+export type SecurityScheme =
+  | { readonly type: "apiKey"; readonly name: string; readonly in: "header" | "query" | "cookie" }
+  | { readonly type: "http"; readonly scheme: string }
+  | { readonly type: "oauth2" }
+  | { readonly type: "openIdConnect" }
+
+/**
+ * Credential material returned by a host auth resolver. The carrier for `apiKey`
+ * comes from the scheme definition, not the credential. `header` is the escape
+ * hatch for nonstandard schemes.
+ */
+export type Credential =
+  | { readonly type: "bearer"; readonly token: string }
+  | { readonly type: "basic"; readonly username: string; readonly password: string }
+  | { readonly type: "apiKey"; readonly value: string }
+  | { readonly type: "header"; readonly name: string; readonly value: string }
+
+/**
+ * Resolves credential material for one named security scheme at call time.
+ * `undefined` means unavailable, try the next OR alternative; a failure aborts
+ * the call rather than falling through.
+ */
+export type AuthResolver = (context: {
+  readonly name: string
+  readonly definition: SecurityScheme
+  readonly scopes: ReadonlyArray<string>
+  readonly operation: Operation
+}) => Effect.Effect<Credential | undefined, unknown>
+
+export type Options = {
+  readonly spec: Document
+  /** Overrides all document, path, and operation `servers`. Required when no applicable absolute server URL exists. */
+  readonly baseUrl?: string | undefined
+  /** Host credential resolution, keyed by security scheme name. */
+  readonly auth?: { readonly resolve: AuthResolver } | undefined
+  /** Static headers on every request. Not model-visible; declared header params may override them, auth always wins. */
+  readonly headers?: Readonly<Record<string, string>> | undefined
+}
+
+/** An operation that could not be represented as a tool, and why. */
+export type Skipped = {
+  readonly method: string
+  readonly path: string
+  readonly reason: string
+}
+
+export type Tools = { [name: string]: Definition<HttpClient.HttpClient> | Tools }
+
+export type Result = {
+  /** Tool subtree; the host places it under a key in its `tools` tree. */
+  readonly tools: Tools
+  readonly skipped: ReadonlyArray<Skipped>
+}
+
+export type Parsed<T> = { readonly ok: true; readonly value: T } | { readonly ok: false; readonly reason: string }
+
+export type InputLocation = "path" | "query" | "header" | "body"
+
+export type InputField = {
+  /** Model-visible field name after cross-location collision handling. */
+  readonly inputName: string
+  /** Original parameter or body-property name used on the wire. */
+  readonly name: string
+  readonly location: InputLocation
+  readonly required: boolean
+  readonly schema: JsonSchema
+  readonly style: "simple" | "form" | "deepObject" | undefined
+  readonly explode: boolean | undefined
+}
+
+export type Body = { readonly required: boolean; readonly mode: "object" | "value"; readonly mediaType: string }
+
+export type OperationInput = {
+  readonly fields: ReadonlyArray<InputField>
+  readonly body: Body | undefined
+}
+
+/** One OR alternative: scheme name -> required scopes. Empty object = unauthenticated is acceptable. */
+export type SecurityRequirement = Readonly<Record<string, ReadonlyArray<string>>>
+
+export type Plan = {
+  readonly operation: Operation
+  readonly url: string
+  readonly fields: ReadonlyArray<InputField>
+  readonly body: Body | undefined
+  readonly security: ReadonlyArray<SecurityRequirement>
+  readonly schemes: Readonly<Record<string, SecurityScheme>>
+  readonly auth: { readonly resolve: AuthResolver } | undefined
+  readonly headers: Readonly<Record<string, string>>
+}
+
+export type AppliedAuth = {
+  readonly headers: Readonly<Record<string, string>>
+  readonly query: Readonly<Record<string, string>>
+}

packages/codemode/src/token.ts

@@ -1,10 +0,0 @@
-/**
- * Token estimation for budgeting model-facing text. Copied from
- * `@opencode-ai/core/util/token` (chars / 4) so this package stays
- * dependency-free; keep the two in sync if the heuristic ever changes.
- */
-export * as Token from "./token.js"
-
-const CHARS_PER_TOKEN = 4
-
-export const estimate = (input: string) => Math.max(0, Math.round(input.length / CHARS_PER_TOKEN))

packages/codemode/src/tool-runtime.ts

@@ -10,27 +10,32 @@ import {
   outputTypeScript,
   type Definition,
 } from "./tool.js"
-import { estimate } from "./token.js"
 import { SandboxDate, SandboxMap, SandboxPromise, SandboxRegExp, SandboxSet } from "./values.js"
 
+const estimateTokens = (input: string) => Math.max(0, Math.round(input.length / 4))
+
 export type HostTool<R = never> = (...args: Array<unknown>) => Effect.Effect<unknown, unknown, R>
 
 export type HostTools<R = never> = {
   [name: string]: HostTool<R> | Definition<R> | HostTools<R>
 }
 
-export type Services<Tools> = Tools extends (...args: Array<unknown>) => Effect.Effect<unknown, unknown, infer R>
-  ? R
-  : Tools extends {
-        readonly _tag: "CodeModeTool"
-        readonly run: (input: unknown) => Effect.Effect<unknown, unknown, infer R>
-      }
+export type Services<Tools> = ServicesOf<Tools, []>
+
+type ServicesOf<Tools, Depth extends ReadonlyArray<unknown>> = Depth["length"] extends 8
+  ? never
+  : Tools extends (...args: Array<unknown>) => Effect.Effect<unknown, unknown, infer R>
     ? R
-    : Tools extends object
-      ? string extends keyof Tools
-        ? never
-        : Services<Tools[keyof Tools]>
-      : never
+    : Tools extends {
+          readonly _tag: "CodeModeTool"
+          readonly run: (input: unknown) => Effect.Effect<unknown, unknown, infer R>
+        }
+      ? R
+      : Tools extends object
+        ? string extends keyof Tools
+          ? ServicesOf<Tools[string], [...Depth, unknown]>
+          : ServicesOf<Tools[keyof Tools], [...Depth, unknown]>
+        : never
 
 /** Minimal audit record retained for each admitted tool call. */
 export type ToolCall = {
@@ -290,17 +295,16 @@ const definitions = <R>(
   return entries
 }
 
-const describeDefinition = <R>(path: string, definition: Definition<R>): ToolDescription => ({
-  path,
-  description: definition.description,
-  signature: `${toolExpression(path)}(input: ${inputTypeScript(definition)}): Promise<${outputTypeScript(definition)}>`,
-})
-
 const visibleDefinitions = <R>(tools: HostTools<R>) =>
-  definitions(tools).flatMap(({ path, definition }) => {
-    const description = describeDefinition(path, definition)
-    return [{ path, definition, description }]
-  })
+  definitions(tools).map(({ path, definition }) => ({
+    path,
+    definition,
+    description: {
+      path,
+      description: definition.description,
+      signature: `${toolExpression(path)}(input: ${inputTypeScript(definition)}): Promise<${outputTypeScript(definition)}>`,
+    },
+  }))
 
 export const catalog = <R>(tools: HostTools<R>): ReadonlyArray<ToolDescription> =>
   visibleDefinitions(tools).map(({ description }) => description)
@@ -351,16 +355,10 @@ const termForms = (term: string): Array<string> => {
   return forms
 }
 
-const firstLine = (text: string) => text.split("\n", 1)[0]!.trim()
-
-/** One-line description used on inline catalog lines; the full text stays in search results. */
-const brief = (text: string, max = 120) => {
-  const line = firstLine(text)
-  return line.length > max ? line.slice(0, max - 1) + "..." : line
-}
-
 const catalogLine = (tool: ToolDescription) => {
-  const description = brief(tool.description)
+  // Inline catalog lines use only a compact first line; full text stays in search results.
+  const line = tool.description.split("\n", 1)[0]!.trim()
+  const description = line.length > 120 ? line.slice(0, 119) + "..." : line
   return description === "" ? `  - ${tool.signature}` : `  - ${tool.signature} // ${description}`
 }
 
@@ -430,7 +428,7 @@ export const discoveryPlan = <R>(
     picked: new Set<ToolDescription>(),
     queue: [...group].sort(
       (left, right) =>
-        estimate(catalogLine(left)) - estimate(catalogLine(right)) || left.path.localeCompare(right.path),
+        estimateTokens(catalogLine(left)) - estimateTokens(catalogLine(right)) || left.path.localeCompare(right.path),
     ),
   }))
   let used = 0
@@ -439,7 +437,7 @@ export const discoveryPlan = <R>(
     const stillActive: typeof active = []
     for (const selection of active) {
       const tool = selection.queue[0]!
-      const cost = estimate(catalogLine(tool))
+      const cost = estimateTokens(catalogLine(tool))
       if (used + cost > maxInlineCatalogTokens) continue
       selection.queue.shift()
       selection.picked.add(tool)
@@ -636,9 +634,6 @@ export type ToolRuntime<R = never> = {
   readonly keys: (path: ReadonlyArray<string>) => ReadonlyArray<string>
 }
 
-const failureMessage = (error: unknown): string =>
-  error instanceof ToolError || error instanceof ToolRuntimeError ? error.message : "Tool execution failed"
-
 export const make = <R>(
   tools: HostTools<R>,
   /** Undefined means unlimited tool calls. */
@@ -657,9 +652,16 @@ export const make = <R>(
     const startedAt = Date.now()
     return effect.pipe(
       Effect.tap(() => onEnd({ ...call, durationMs: Date.now() - startedAt, outcome: "success" })),
-      Effect.tapError((error) =>
-        onEnd({ ...call, durationMs: Date.now() - startedAt, outcome: "failure", message: failureMessage(error) }),
-      ),
+      Effect.tapError((error) => {
+        const message =
+          error instanceof ToolError || error instanceof ToolRuntimeError ? error.message : "Tool execution failed"
+        return onEnd({
+          ...call,
+          durationMs: Date.now() - startedAt,
+          outcome: "failure",
+          message,
+        })
+      }),
     )
   }
 

packages/codemode/src/tool.ts

@@ -1,4 +1,4 @@
-import { Effect, Schema } from "effect"
+import { Effect, JsonPointer, Schema } from "effect"
 
 /**
  * JSON Schema subset accepted for render-only tool schemas.
@@ -13,6 +13,7 @@ export type JsonSchema = {
   readonly const?: unknown
   readonly anyOf?: ReadonlyArray<JsonSchema>
   readonly oneOf?: ReadonlyArray<JsonSchema>
+  readonly allOf?: ReadonlyArray<JsonSchema>
   readonly properties?: Readonly<Record<string, JsonSchema>>
   readonly required?: ReadonlyArray<string>
   readonly items?: JsonSchema
@@ -76,6 +77,13 @@ const effectNumberSentinel = (schema: JsonSchema) =>
   schema.enum.length === 1 &&
   (schema.enum[0] === "NaN" || schema.enum[0] === "Infinity" || schema.enum[0] === "-Infinity")
 
+const intersection = (members: ReadonlyArray<string>): string => {
+  const concrete = members.filter((member) => member !== "unknown")
+  if (concrete.length === 0) return "unknown"
+  if (concrete.length === 1) return concrete[0] ?? "unknown"
+  return concrete.map((member) => (member.includes(" | ") ? `(${member})` : member)).join(" & ")
+}
+
 /**
  * Recursion ceiling for schema rendering. Object, array, and union recursion all increment
  * depth, so this bounds every recursion path - pathological or structurally cyclic schemas
@@ -89,6 +97,30 @@ type RenderContext = {
   readonly pretty: boolean
 }
 
+const hasUnresolvedRef = (
+  schema: JsonSchema,
+  definitions: Readonly<Record<string, JsonSchema>>,
+  seen: ReadonlySet<string> = new Set(),
+  visited: ReadonlySet<JsonSchema> = new Set(),
+): boolean => {
+  if (visited.has(schema)) return false
+  const nextVisited = new Set([...visited, schema])
+  if (schema.$ref !== undefined) {
+    const segment = schema.$ref.match(/^#\/(?:\$defs|definitions)\/([^/]+)$/)?.[1]
+    const name = segment === undefined ? undefined : JsonPointer.unescapeToken(segment)
+    if (name === undefined || definitions[name] === undefined || seen.has(name)) return true
+    if (hasUnresolvedRef(definitions[name], definitions, new Set([...seen, name]), nextVisited)) return true
+  }
+  return [
+    ...(schema.anyOf ?? []),
+    ...(schema.oneOf ?? []),
+    ...(schema.allOf ?? []),
+    ...Object.values(schema.properties ?? {}),
+    ...(schema.items === undefined ? [] : [schema.items]),
+    ...(typeof schema.additionalProperties === "object" ? [schema.additionalProperties] : []),
+  ].some((item) => hasUnresolvedRef(item, definitions, seen, nextVisited))
+}
+
 /**
  * Schema constraints a TypeScript type cannot express natively but a model benefits from,
  * surfaced as JSDoc tags (`@deprecated`, `@default`, `@format`, `@minItems`, `@maxItems`).
@@ -136,11 +168,18 @@ const renderSchema = (
   seen: ReadonlySet<string> = new Set(),
 ): string => {
   if (depth > MAX_RENDER_DEPTH) return "unknown"
+  const nested =
+    schema.definitions === undefined && schema.$defs === undefined
+      ? ctx
+      : { ...ctx, definitions: { ...ctx.definitions, ...(schema.definitions ?? {}), ...(schema.$defs ?? {}) } }
   if (schema.$ref) {
-    const name = schema.$ref.split("/").pop()
-    if (!name || !ctx.definitions[name]) return name ?? "unknown"
-    if (seen.has(name)) return name // recursive type: reference by name rather than loop
-    return renderSchema(ctx.definitions[name], ctx, depth, new Set([...seen, name]))
+    const segment = schema.$ref.match(/^#\/(?:\$defs|definitions)\/([^/]+)$/)?.[1]
+    const name = segment === undefined ? undefined : JsonPointer.unescapeToken(segment)
+    if (!name || !nested.definitions[name] || seen.has(name)) return "unknown"
+    return intersection([
+      renderSchema(nested.definitions[name], nested, depth, new Set([...seen, name])),
+      renderSchema({ ...schema, $ref: undefined }, nested, depth + 1, seen),
+    ])
   }
   if (schema.const !== undefined) return renderLiteral(schema.const)
   if (schema.enum) return schema.enum.map(renderLiteral).join(" | ")
@@ -166,24 +205,34 @@ const renderSchema = (
     ) {
       return "{}"
     }
-    return alternatives.map((item) => renderSchema(item, ctx, depth + 1, seen)).join(" | ")
+    const members = alternatives.map((item) => renderSchema(item, nested, depth + 1, seen))
+    if (members.some((member) => member === "unknown")) return "unknown"
+    return intersection([
+      members.join(" | "),
+      renderSchema({ ...schema, anyOf: undefined, oneOf: undefined }, nested, depth + 1, seen),
+    ])
+  }
+  if (schema.allOf) {
+    const members = schema.allOf.map((item) => renderSchema(item, nested, depth + 1, seen))
+    if (schema.allOf.some((item) => hasUnresolvedRef(item, nested.definitions))) return "unknown"
+    return intersection([renderSchema({ ...schema, allOf: undefined }, nested, depth + 1, seen), ...members])
   }
   if (Array.isArray(schema.type)) {
-    return schema.type.map((item) => renderSchema({ type: item }, ctx, depth + 1, seen)).join(" | ")
+    return schema.type.map((item) => renderSchema({ ...schema, type: item }, nested, depth + 1, seen)).join(" | ")
   }
   if (schema.type === "string") return "string"
   if (schema.type === "number" || schema.type === "integer") return "number"
   if (schema.type === "boolean") return "boolean"
   if (schema.type === "null") return "null"
-  if (schema.type === "array") return `Array<${renderSchema(schema.items ?? {}, ctx, depth + 1, seen)}>`
+  if (schema.type === "array") return `Array<${renderSchema(schema.items ?? {}, nested, depth + 1, seen)}>`
   if (schema.type === "object" || schema.properties) {
     const required = new Set(schema.required ?? [])
     const properties = Object.entries(schema.properties ?? {})
     const additional = schema.additionalProperties
     const indexType =
-      additional && typeof additional === "object" ? renderSchema(additional, ctx, depth + 1, seen) : undefined
+      additional && typeof additional === "object" ? renderSchema(additional, nested, depth + 1, seen) : undefined
     const field = ([name, value]: readonly [string, JsonSchema]) =>
-      `${renderKey(name)}${required.has(name) ? "" : "?"}: ${renderSchema(value, ctx, depth + 1, seen)}`
+      `${renderKey(name)}${required.has(name) ? "" : "?"}: ${renderSchema(value, nested, depth + 1, seen)}`
 
     if (!ctx.pretty) {
       const fields = properties.map(field)
@@ -253,7 +302,8 @@ export const inputProperties = <R>(definition: Definition<R>): Array<InputProper
     const definitions = document.definitions ?? {}
     let schema = document.schema
     if (schema.$ref !== undefined) {
-      const name = schema.$ref.split("/").pop()
+      const segment = schema.$ref.match(/^#\/(?:\$defs|definitions)\/([^/]+)$/)?.[1]
+      const name = segment === undefined ? undefined : JsonPointer.unescapeToken(segment)
       const resolved = name === undefined ? undefined : definitions[name]
       if (resolved === undefined) return []
       schema = resolved

packages/codemode/test/fixtures/openapi-happy-path.json

@@ -0,0 +1,245 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "CodeMode Happy Path",
+    "version": "1.0.0"
+  },
+  "servers": [
+    {
+      "url": "https://api.example.test/v1"
+    }
+  ],
+  "security": [
+    {
+      "BearerAuth": []
+    }
+  ],
+  "paths": {
+    "/users/{userId}": {
+      "parameters": [
+        {
+          "$ref": "#/components/parameters/UserId"
+        }
+      ],
+      "get": {
+        "operationId": "users.get",
+        "summary": "Get a user",
+        "parameters": [
+          {
+            "name": "include",
+            "in": "query",
+            "style": "form",
+            "explode": false,
+            "schema": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          },
+          {
+            "name": "verbose",
+            "in": "query",
+            "schema": {
+              "type": "boolean"
+            }
+          },
+          {
+            "name": "X-Trace-ID",
+            "in": "header",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/UserResponse"
+          }
+        }
+      },
+      "delete": {
+        "operationId": "users.remove",
+        "summary": "Remove a user",
+        "responses": {
+          "204": {
+            "description": "Removed"
+          }
+        }
+      }
+    },
+    "/users": {
+      "post": {
+        "operationId": "users.create",
+        "summary": "Create a user",
+        "security": [
+          {
+            "ApiKey": []
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "name": {
+                    "type": "string"
+                  },
+                  "email": {
+                    "type": "string",
+                    "format": "email"
+                  },
+                  "role": {
+                    "type": "string",
+                    "enum": [
+                      "admin",
+                      "member"
+                    ]
+                  }
+                },
+                "required": [
+                  "name",
+                  "email"
+                ],
+                "additionalProperties": false
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Created",
+            "content": {
+              "application/vnd.example+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/User"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/search": {
+      "get": {
+        "operationId": "search.run",
+        "summary": "Search users",
+        "security": [],
+        "parameters": [
+          {
+            "name": "filter",
+            "in": "query",
+            "style": "deepObject",
+            "explode": true,
+            "schema": {
+              "type": "object",
+              "properties": {
+                "query": {
+                  "type": "string"
+                },
+                "page": {
+                  "type": "integer"
+                }
+              },
+              "required": [
+                "query"
+              ],
+              "additionalProperties": false
+            }
+          },
+          {
+            "name": "tags",
+            "in": "query",
+            "style": "form",
+            "explode": true,
+            "schema": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Summary",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "parameters": {
+      "UserId": {
+        "name": "userId",
+        "in": "path",
+        "required": true,
+        "schema": {
+          "type": "string"
+        }
+      }
+    },
+    "responses": {
+      "UserResponse": {
+        "description": "A user",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/User"
+            }
+          }
+        }
+      }
+    },
+    "schemas": {
+      "User": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "email": {
+            "type": "string",
+            "format": "email"
+          },
+          "role": {
+            "type": "string",
+            "enum": [
+              "admin",
+              "member"
+            ]
+          }
+        },
+        "required": [
+          "id",
+          "name",
+          "email"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "securitySchemes": {
+      "BearerAuth": {
+        "type": "http",
+        "scheme": "bearer"
+      },
+      "ApiKey": {
+        "type": "apiKey",
+        "in": "query",
+        "name": "api_key"
+      }
+    }
+  }
+}

packages/codemode/test/openapi.test.ts

@@ -0,0 +1,958 @@
+import { describe, expect, test } from "bun:test"
+import { Effect, Layer, Option } from "effect"
+import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/unstable/http"
+import { CodeMode, OpenAPI } from "../src/index.js"
+import { inputTypeScript, outputTypeScript, Tool } from "../src/tool.js"
+
+const baseUrl = "http://localhost:4096"
+type Document = OpenAPI.Document
+
+type Recorded = {
+  readonly method: string
+  readonly url: string
+  readonly headers: Record<string, string>
+  readonly body: unknown
+}
+
+const opencodeSpec = async (): Promise<Document> => {
+  return Bun.file(new URL("./fixtures/opencode-v2-openapi.json", import.meta.url)).json() as Promise<Document>
+}
+
+const happyPathSpec = async (): Promise<Document> => {
+  return Bun.file(new URL("./fixtures/openapi-happy-path.json", import.meta.url)).json() as Promise<Document>
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value)
+
+const toolAt = (tools: unknown, name: string) =>
+  name.split(".").reduce<unknown>((current, segment) => (isRecord(current) ? current[segment] : undefined), tools)
+
+const recordingClient = (respond: (request: HttpClientRequest.HttpClientRequest) => Response) => {
+  const requests: Array<Recorded> = []
+  const layer = Layer.succeed(HttpClient.HttpClient)(
+    HttpClient.make((request) =>
+      Effect.gen(function* () {
+        const body =
+          request.body._tag === "Uint8Array" ? JSON.parse(new TextDecoder().decode(request.body.body)) : undefined
+        const url = Option.map(HttpClientRequest.toUrl(request), (resolved) => resolved.toString())
+        requests.push({
+          method: request.method,
+          url: Option.getOrElse(url, () => request.url),
+          headers: { ...request.headers },
+          body,
+        })
+        return HttpClientResponse.fromWeb(request, respond(request))
+      }),
+    ),
+  )
+  return { requests, layer }
+}
+
+const json = (value: unknown, status = 200) =>
+  new Response(JSON.stringify(value), { status, headers: { "content-type": "application/json" } })
+
+const singleOperation = (operation: Record<string, unknown>, method = "get"): Document => ({
+  openapi: "3.1.0",
+  paths: { "/test": { [method]: { operationId: "test", responses: { 200: { description: "Success" } }, ...operation } } },
+})
+
+describe("OpenAPI.fromSpec", () => {
+  test("covers a representative API from generation through execution", async () => {
+    const resolutions: Array<string> = []
+    const client = recordingClient((request) => {
+      const url = Option.getOrElse(HttpClientRequest.toUrl(request), () => new URL(request.url))
+      if (request.method === "POST") {
+        return new Response(
+          JSON.stringify({ id: "user-2", name: "Grace", email: "grace@example.test", role: "admin" }),
+          { status: 201, headers: { "content-type": "application/vnd.example+json" } },
+        )
+      }
+      if (request.method === "DELETE") return new Response(null, { status: 204 })
+      if (url.pathname === "/search") {
+        return new Response("2 matches", { headers: { "content-type": "text/plain" } })
+      }
+      return json({ id: "user-1", name: "Ada", email: "ada@example.test", role: "member" })
+    })
+    const api = OpenAPI.fromSpec({
+      spec: await happyPathSpec(),
+      baseUrl,
+      auth: {
+        resolve: ({ name }) => {
+          resolutions.push(name)
+          return Effect.succeed(
+            name === "BearerAuth"
+              ? { type: "bearer", token: "bearer-secret" }
+              : { type: "apiKey", value: "api-secret" },
+          )
+        },
+      },
+    })
+    const get = toolAt(api.tools, "users.get")
+    const create = toolAt(api.tools, "users.create")
+    const search = toolAt(api.tools, "search.run")
+    const remove = toolAt(api.tools, "users.remove")
+
+    expect(api.skipped).toEqual([])
+    if (!Tool.isDefinition(get) || !Tool.isDefinition(create) || !Tool.isDefinition(search) || !Tool.isDefinition(remove)) {
+      throw new Error("happy-path fixture did not generate every operation")
+    }
+    expect(inputTypeScript(get)).toBe(
+      '{ userId: string; include?: Array<string>; verbose?: boolean; "X-Trace-ID"?: string }',
+    )
+    expect(inputTypeScript(create)).toBe('{ name: string; email: string; role?: "admin" | "member" }')
+    expect(inputTypeScript(search)).toBe("{ filter?: { query: string; page?: number }; tags?: Array<string> }")
+    expect(inputTypeScript(remove)).toBe("{ userId: string }")
+    expect(outputTypeScript(get)).toContain("id: string")
+    expect(outputTypeScript(create)).toContain('role?: "admin" | "member"')
+    expect(outputTypeScript(search)).toBe("string")
+    expect(outputTypeScript(remove)).toBe("null")
+
+    const result = await Effect.runPromise(
+      CodeMode.make({ tools: { api: api.tools } })
+        .execute(`
+          const user = await tools.api.users.get({
+            userId: "user-1",
+            include: ["profile", "permissions"],
+            verbose: true,
+            "X-Trace-ID": "trace-1",
+          })
+          const created = await tools.api.users.create({
+            name: "Grace",
+            email: "grace@example.test",
+            role: "admin",
+          })
+          const summary = await tools.api.search.run({
+            filter: { query: "effect", page: 2 },
+            tags: ["typescript", "runtime"],
+          })
+          const removed = await tools.api.users.remove({ userId: "user-1" })
+          return { user, created, summary, removed }
+        `)
+        .pipe(Effect.provide(client.layer)),
+    )
+
+    expect(result).toMatchObject({
+      ok: true,
+      value: {
+        user: { id: "user-1", name: "Ada" },
+        created: { id: "user-2", name: "Grace" },
+        summary: "2 matches",
+        removed: null,
+      },
+    })
+    expect(resolutions).toEqual(["BearerAuth", "ApiKey", "BearerAuth"])
+    expect(client.requests).toHaveLength(4)
+
+    const getUrl = new URL(client.requests[0]!.url)
+    expect(getUrl.pathname).toBe("/users/user-1")
+    expect(getUrl.searchParams.get("include")).toBe("profile,permissions")
+    expect(getUrl.searchParams.get("verbose")).toBe("true")
+    expect(client.requests[0]!.headers["x-trace-id"]).toBe("trace-1")
+    expect(client.requests[0]!.headers.authorization).toBe("Bearer bearer-secret")
+
+    const createUrl = new URL(client.requests[1]!.url)
+    expect(createUrl.searchParams.get("api_key")).toBe("api-secret")
+    expect(client.requests[1]!.body).toEqual({ name: "Grace", email: "grace@example.test", role: "admin" })
+
+    const searchUrl = new URL(client.requests[2]!.url)
+    expect(searchUrl.searchParams.get("filter[query]")).toBe("effect")
+    expect(searchUrl.searchParams.get("filter[page]")).toBe("2")
+    expect(searchUrl.searchParams.getAll("tags")).toEqual(["typescript", "runtime"])
+    expect(client.requests[2]!.headers.authorization).toBeUndefined()
+    expect(new URL(client.requests[3]!.url).pathname).toBe("/users/user-1")
+    expect(client.requests[3]!.headers.authorization).toBe("Bearer bearer-secret")
+  })
+
+  test("converts representative opencode operations into the expected tool shape", async () => {
+    const spec = await opencodeSpec()
+    const result = OpenAPI.fromSpec({ spec, baseUrl })
+
+    expect(result.skipped).toHaveLength(5)
+    expect(result.skipped).toContainEqual({
+      method: "GET",
+      path: "/api/pty/{ptyID}/connect",
+      reason: "WebSocket operations are not supported",
+    })
+    expect(result.skipped.filter((item) => item.reason === "SSE operations are not supported")).toHaveLength(3)
+    expect(result.skipped).toContainEqual({
+      method: "GET",
+      path: "/api/fs/read/*",
+      reason: "binary responses are not supported",
+    })
+    expect(toolAt(result.tools, "v2.health.get")).not.toBeUndefined()
+    expect(toolAt(result.tools, "v2.session.get")).not.toBeUndefined()
+    expect(toolAt(result.tools, "v2.session.create")).not.toBeUndefined()
+
+    const sessionGet = toolAt(result.tools, "v2.session.get")
+    expect(Tool.isDefinition(sessionGet)).toBe(true)
+    if (!Tool.isDefinition(sessionGet)) throw new Error("v2.session.get was not generated")
+    expect(inputTypeScript(sessionGet)).toBe("{ sessionID: string }")
+    expect(outputTypeScript(sessionGet)).toContain("id: string")
+    expect(outputTypeScript(sessionGet)).toContain("additions: number")
+
+    const switchAgent = toolAt(result.tools, "v2.session.switchAgent")
+    expect(Tool.isDefinition(switchAgent)).toBe(true)
+    if (!Tool.isDefinition(switchAgent)) throw new Error("v2.session.switchAgent was not generated")
+    expect(inputTypeScript(switchAgent)).toBe("{ sessionID: string; agent: string }")
+
+    const contextEntryPut = toolAt(result.tools, "v2.session.contextEntry.put")
+    expect(Tool.isDefinition(contextEntryPut)).toBe(true)
+    if (!Tool.isDefinition(contextEntryPut)) throw new Error("v2.session.contextEntry.put was not generated")
+    expect(inputTypeScript(contextEntryPut)).toBe("{ sessionID: string; key: string; value: unknown }")
+    expect(toolAt(result.tools, "v2_session_context_entry_put_2")).toBeUndefined()
+    expect(toolAt(result.tools, "v2.pty.connect")).toBeUndefined()
+    expect(toolAt(result.tools, "v2.session.log")).toBeUndefined()
+    expect(toolAt(result.tools, "v2.event.subscribe")).toBeUndefined()
+    expect(toolAt(result.tools, "v2.event.changes")).toBeUndefined()
+    expect(toolAt(result.tools, "v2.fs.read")).toBeUndefined()
+    expect(toolAt(result.tools, "v2.pty.connectToken")).not.toBeUndefined()
+  })
+
+  test("preserves operation path sanitization and collision handling", () => {
+    const response = { responses: { 200: { description: "Success" } } }
+    const result = OpenAPI.fromSpec({
+      baseUrl,
+      spec: {
+        openapi: "3.1.0",
+        paths: {
+          "/first": { get: { ...response, operationId: "group.item" } },
+          "/second": { get: { ...response, operationId: "group.item" } },
+          "/third": { get: { ...response, operationId: "group..other" } },
+        },
+      },
+    })
+
+    expect(Tool.isDefinition(toolAt(result.tools, "group.item"))).toBe(true)
+    expect(Tool.isDefinition(toolAt(result.tools, "group_item_2"))).toBe(true)
+    expect(Tool.isDefinition(toolAt(result.tools, "group.operation.other"))).toBe(true)
+  })
+
+  test("synthesizes flat operation IDs from methods and paths", () => {
+    const response = { responses: { 200: { description: "Success" } } }
+    const tools = OpenAPI.fromSpec({
+      baseUrl,
+      spec: {
+        openapi: "3.1.0",
+        paths: {
+          "/users": { get: response, post: response },
+          "/users/{id}": { get: response, patch: response, delete: response },
+          "/organizations/{organizationId}/users/{id}": { get: response },
+        },
+      },
+    }).tools
+
+    for (const path of [
+      "getUsers",
+      "postUsers",
+      "getUsersById",
+      "patchUsersById",
+      "deleteUsersById",
+      "getOrganizationsByOrganizationidUsersById",
+    ]) {
+      expect(Tool.isDefinition(toolAt(tools, path))).toBe(true)
+    }
+  })
+
+  test("lets operation parameters override matching path parameters", () => {
+    const tool = toolAt(
+      OpenAPI.fromSpec({
+        baseUrl,
+        spec: {
+          openapi: "3.1.0",
+          paths: {
+            "/test": {
+              parameters: [{ name: "limit", in: "query", schema: { type: "string" } }],
+              get: {
+                operationId: "test",
+                parameters: [{ name: "limit", in: "query", required: true, schema: { type: "number" } }],
+                responses: { 200: { description: "Success" } },
+              },
+            },
+          },
+        },
+      }).tools,
+      "test",
+    )
+
+    if (!Tool.isDefinition(tool)) throw new Error("test was not generated")
+    expect(inputTypeScript(tool)).toBe("{ limit: number }")
+  })
+
+  test("normalizes OpenAPI 3.0 schemas with Effect", () => {
+    const result = OpenAPI.fromSpec({
+      baseUrl,
+      spec: {
+        openapi: "3.0.3",
+        paths: {
+          "/search": {
+            get: {
+              operationId: "search",
+              parameters: [
+                {
+                  in: "query",
+                  name: "value",
+                  schema: { type: "string", nullable: true, minLength: 2 },
+                },
+              ],
+              responses: { 200: { description: "Success" } },
+            },
+          },
+        },
+      },
+    })
+    const search = toolAt(result.tools, "search")
+
+    expect(Tool.isDefinition(search)).toBe(true)
+    if (!Tool.isDefinition(search)) throw new Error("search was not generated")
+    expect(inputTypeScript(search)).toBe("{ value?: string | null }")
+    const schema: unknown = search.input
+    const input = isRecord(schema) ? schema : {}
+    const properties = isRecord(input.properties) ? input.properties : {}
+    const value = isRecord(properties.value) ? properties.value : {}
+    expect(value.minLength).toBe(2)
+  })
+
+  test("preserves schema-local definitions alongside component definitions", () => {
+    const tool = toolAt(
+      OpenAPI.fromSpec({
+        baseUrl,
+        spec: {
+          openapi: "3.1.0",
+          paths: {
+            "/test": {
+              get: {
+                operationId: "test",
+                responses: {
+                  200: {
+                    description: "Success",
+                    content: {
+                      "application/json": {
+                        schema: { $ref: "#/$defs/Local", $defs: { Local: { type: "string" } } },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+          components: { schemas: { Global: { type: "number" } } },
+        },
+      }).tools,
+      "test",
+    )
+
+    if (!Tool.isDefinition(tool) || !isRecord(tool.output)) throw new Error("test output was not generated")
+    expect(tool.output.$defs).toMatchObject({ Local: { type: "string" }, Global: { type: "number" } })
+  })
+
+  test("documents that the opencode fixture is unauthenticated", async () => {
+    const spec = await opencodeSpec()
+    const components = isRecord(spec.components) ? spec.components : {}
+    const result = OpenAPI.fromSpec({ spec, baseUrl })
+
+    expect(spec.security).toStrictEqual([])
+    expect(isRecord(components.securitySchemes) ? Object.keys(components.securitySchemes) : []).toStrictEqual([])
+    const health = toolAt(result.tools, "v2.health.get")
+    const healthInput = isRecord(health) ? health.input : undefined
+    expect(healthInput).toMatchObject({ type: "object", properties: {} })
+    const input = isRecord(healthInput) ? healthInput : {}
+    expect(Object.keys(isRecord(input.properties) ? input.properties : {})).toStrictEqual([])
+  })
+
+  test("exposes real opencode operations through CodeMode discovery", async () => {
+    const { layer } = recordingClient(() => json({}))
+    const runtime = CodeMode.make({
+      tools: { opencode: OpenAPI.fromSpec({ spec: await opencodeSpec(), baseUrl }).tools },
+    })
+    const result = await Effect.runPromise(
+      runtime
+        .execute(
+          `
+        return await tools.$codemode.search({ query: "global health", namespace: "opencode", limit: 1 })
+      `,
+        )
+        .pipe(Effect.provide(layer)),
+    )
+
+    expect(result).toMatchObject({ ok: true })
+    if (!result.ok) return
+    expect(result.value).toMatchObject({
+      items: [
+        {
+          path: "tools.opencode.v2.health.get",
+          description: "Check whether the API server is ready to accept requests.",
+        },
+      ],
+    })
+    expect(JSON.stringify(result.value)).toContain("healthy: true")
+  })
+
+  test("invokes real opencode path parameters and JSON request bodies", async () => {
+    const { requests, layer } = recordingClient((request) => {
+      if (request.method === "GET") return json({ id: "ses_123" })
+      return json({ id: "ses_456" })
+    })
+    const runtime = CodeMode.make({
+      tools: { opencode: OpenAPI.fromSpec({ spec: await opencodeSpec(), baseUrl }).tools },
+    })
+
+    const result = await Effect.runPromise(
+      runtime
+        .execute(
+          `
+          const existing = await tools.opencode.v2.session.get({ sessionID: "ses_123" })
+          const created = await tools.opencode.v2.session.create({ id: "ses_456" })
+          return { existing, created }
+        `,
+        )
+        .pipe(Effect.provide(layer)),
+    )
+
+    expect(result).toMatchObject({ ok: true })
+    expect(requests).toHaveLength(2)
+    expect(requests[0]).toMatchObject({ method: "GET", body: undefined })
+    expect(new URL(requests[0]!.url).pathname).toBe("/api/session/ses_123")
+    expect(requests[1]).toMatchObject({
+      method: "POST",
+      url: "http://localhost:4096/api/session",
+      body: { id: "ses_456" },
+    })
+  })
+
+  test("serializes deep-object query parameters from the opencode fixture", async () => {
+    const client = recordingClient(() => json({ directory: "/tmp" }))
+    const location = toolAt(OpenAPI.fromSpec({ spec: await opencodeSpec(), baseUrl }).tools, "v2.location.get")
+    if (!Tool.isDefinition(location)) throw new Error("v2.location.get was not generated")
+
+    await Effect.runPromise(
+      location.run({ location: { directory: "/tmp", workspace: "workspace-1" } }).pipe(Effect.provide(client.layer)),
+    )
+
+    const url = new URL(client.requests[0]!.url)
+    expect(url.searchParams.get("location[directory]")).toBe("/tmp")
+    expect(url.searchParams.get("location[workspace]")).toBe("workspace-1")
+  })
+
+  test("serializes supported simple and form parameter shapes", async () => {
+    const client = recordingClient(() => json({ ok: true }))
+    const result = OpenAPI.fromSpec({
+      baseUrl,
+      spec: {
+        openapi: "3.1.0",
+        paths: {
+          "/items/{keys}": {
+            get: {
+              operationId: "items",
+              parameters: [
+                { name: "keys", in: "path", required: true, schema: { type: "array", items: { type: "string" } } },
+                { name: "tags", in: "query", style: "form", explode: false, schema: { type: "array" } },
+                { name: "filter", in: "query", style: "form", explode: true, schema: { type: "object" } },
+                { name: "nullable", in: "query", required: true, schema: { type: ["string", "null"] } },
+                { name: "constructor", in: "query", schema: { type: "string" } },
+                { name: "meta", in: "header", style: "simple", explode: true, schema: { type: "object" } },
+              ],
+              responses: { 200: { description: "Success" } },
+            },
+          },
+        },
+      },
+    })
+    const tool = toolAt(result.tools, "items")
+    if (!Tool.isDefinition(tool)) throw new Error("items was not generated")
+
+    await Effect.runPromise(
+      tool
+        .run({
+          keys: ["a!", "b*"],
+          tags: ["x", "y"],
+          filter: { state: "open", page: 2 },
+          nullable: null,
+          constructor_2: "safe",
+          meta: { a: "b", c: "d" },
+        })
+        .pipe(Effect.provide(client.layer)),
+    )
+
+    const url = new URL(client.requests[0]!.url)
+    expect(url.pathname).toBe("/items/a%21,b%2A")
+    expect(url.searchParams.get("tags")).toBe("x,y")
+    expect(url.searchParams.get("state")).toBe("open")
+    expect(url.searchParams.get("page")).toBe("2")
+    expect(url.searchParams.get("nullable")).toBe("null")
+    expect(url.searchParams.get("constructor")).toBe("safe")
+    expect(client.requests[0]!.headers.meta).toBe("a=b,c=d")
+    await expect(
+      Effect.runPromise(tool.run({ keys: [undefined] }).pipe(Effect.provide(client.layer))),
+    ).rejects.toThrow("unsupported nested value")
+  })
+
+  test("skips unsupported parameter encodings and malformed security", () => {
+    const result = OpenAPI.fromSpec({
+      baseUrl,
+      spec: {
+        openapi: "3.1.0",
+        security: [{ bearer: [] }],
+        paths: {
+          "/cookie": {
+            get: {
+              operationId: "cookie",
+              parameters: [{ name: "session", in: "cookie", schema: { type: "string" } }],
+              responses: { 200: { description: "Success" } },
+            },
+          },
+          "/reserved": {
+            get: {
+              operationId: "reserved",
+              parameters: [{ name: "query", in: "query", allowReserved: true, schema: { type: "string" } }],
+              responses: { 200: { description: "Success" } },
+            },
+          },
+          "/invalid-style": {
+            get: {
+              operationId: "invalidStyle",
+              parameters: [{ name: "query", in: "query", style: 42, schema: { type: "string" } }],
+              responses: { 200: { description: "Success" } },
+            },
+          },
+          "/security": {
+            get: { operationId: "security", security: null, responses: { 200: { description: "Success" } } },
+          },
+        },
+      },
+    })
+
+    expect(result.tools).toEqual({})
+    expect(result.skipped.map((item) => item.reason)).toEqual([
+      "cookie parameter 'session' is not supported",
+      "parameter 'query' uses unsupported allowReserved encoding",
+      "parameter 'query' has an invalid style",
+      "security declaration is not an array",
+    ])
+  })
+
+  test("fails closed on prototype-named missing security schemes", () => {
+    const result = OpenAPI.fromSpec({
+      baseUrl,
+      spec: singleOperation({ security: [JSON.parse('{"__proto__":[]}')] }),
+    })
+
+    expect(result.tools).toEqual({})
+    expect(result.skipped[0]?.reason).toBe("security requirement references missing or malformed scheme: __proto__")
+  })
+
+  test("resolves bearer authentication without exposing it as input", async () => {
+    const contexts: Array<Parameters<OpenAPI.AuthResolver>[0]> = []
+    const client = recordingClient(() => json({ ok: true }))
+    const spec = {
+      ...singleOperation({ operationId: undefined }),
+      security: [{ bearer: [] }],
+      components: { securitySchemes: { bearer: { type: "http", scheme: "bearer" } } },
+    } satisfies Document
+    const tool = toolAt(
+      OpenAPI.fromSpec({
+        baseUrl,
+        spec,
+        auth: {
+          resolve: (context) => {
+            contexts.push(context)
+            return Effect.succeed({ type: "bearer", token: "secret" })
+          },
+        },
+      }).tools,
+      "getTest",
+    )
+    if (!Tool.isDefinition(tool)) throw new Error("test was not generated")
+
+    await Effect.runPromise(tool.run({}).pipe(Effect.provide(client.layer)))
+
+    expect(inputTypeScript(tool)).toBe("{}")
+    expect(client.requests[0]!.headers.authorization).toBe("Bearer secret")
+    expect(contexts).toEqual([
+      {
+        name: "bearer",
+        definition: { type: "http", scheme: "bearer" },
+        scopes: [],
+        operation: {
+          operationId: undefined,
+          method: "GET",
+          path: "/test",
+          summary: undefined,
+          description: undefined,
+        },
+      },
+    ])
+  })
+
+  test("applies authentication carriers without prototype or collision loss", async () => {
+    const client = recordingClient(() => json({ ok: true }))
+    const authenticated = (security: ReadonlyArray<Record<string, ReadonlyArray<string>>>, schemes: Record<string, unknown>) =>
+      OpenAPI.fromSpec({
+        baseUrl,
+        spec: { ...singleOperation({}), security, components: { securitySchemes: schemes } },
+        auth: { resolve: () => Effect.succeed({ type: "apiKey", value: "secret" }) },
+      })
+    const prototype = toolAt(
+      authenticated([{ key: [] }], { key: { type: "apiKey", in: "query", name: "__proto__" } }).tools,
+      "test",
+    )
+    if (!Tool.isDefinition(prototype)) throw new Error("prototype auth tool was not generated")
+
+    await Effect.runPromise(prototype.run({}).pipe(Effect.provide(client.layer)))
+    expect(new URL(client.requests[0]!.url).searchParams.get("__proto__")).toBe("secret")
+
+    const duplicate = toolAt(
+      authenticated(
+        [{ first: [], second: [] }],
+        {
+          first: { type: "apiKey", in: "header", name: "x-key" },
+          second: { type: "apiKey", in: "header", name: "x-key" },
+        },
+      ).tools,
+      "test",
+    )
+    if (!Tool.isDefinition(duplicate)) throw new Error("duplicate auth tool was not generated")
+    await expect(Effect.runPromise(duplicate.run({}).pipe(Effect.provide(client.layer)))).rejects.toThrow(
+      "multiple credentials",
+    )
+
+    const cookie = authenticated([{ key: [] }], { key: { type: "apiKey", in: "cookie", name: "session" } })
+    expect(cookie.tools).toEqual({})
+    expect(cookie.skipped[0]?.reason).toBe("cookie authentication 'key' is not supported")
+
+    const alternative = OpenAPI.fromSpec({
+      baseUrl,
+      spec: {
+        ...singleOperation({}),
+        security: [{ cookie: [] }, { bearer: [] }],
+        components: {
+          securitySchemes: {
+            cookie: { type: "apiKey", in: "cookie", name: "session" },
+            bearer: { type: "http", scheme: "bearer" },
+          },
+        },
+      },
+      auth: {
+        resolve: ({ name }) =>
+          Effect.succeed(name === "bearer" ? { type: "bearer", token: "secret" } : undefined),
+      },
+    })
+    const alternativeTool = toolAt(alternative.tools, "test")
+    if (!Tool.isDefinition(alternativeTool)) throw new Error("supported auth alternative was not generated")
+    await Effect.runPromise(alternativeTool.run({}).pipe(Effect.provide(client.layer)))
+    expect(client.requests.at(-1)?.headers.authorization).toBe("Bearer secret")
+  })
+
+  test("honors server precedence and rejects ambiguous base URLs", async () => {
+    const client = recordingClient(() => json({ ok: true }))
+    const spec = {
+      ...singleOperation({ servers: [{ url: "https://operation.example/v1" }] }),
+      servers: [{ url: "https://document.example" }],
+    } satisfies Document
+    const tool = toolAt(OpenAPI.fromSpec({ spec }).tools, "test")
+    if (!Tool.isDefinition(tool)) throw new Error("test was not generated")
+
+    await Effect.runPromise(tool.run({}).pipe(Effect.provide(client.layer)))
+    expect(client.requests[0]?.url).toBe("https://operation.example/v1/test")
+
+    const invalid = OpenAPI.fromSpec({ spec, baseUrl: "https://example.com/api?tenant=one" })
+    expect(invalid.tools).toEqual({})
+    expect(invalid.skipped[0]?.reason).toContain("unsupported query string or fragment")
+
+    const malformed = OpenAPI.fromSpec({ spec, baseUrl: "https:/example.com" })
+    expect(malformed.tools).toEqual({})
+    expect(malformed.skipped[0]?.reason).toContain("not an absolute HTTP(S) URL")
+  })
+
+  test("resolves chained response refs before detecting unsupported transports", () => {
+    const result = OpenAPI.fromSpec({
+      baseUrl,
+      spec: {
+        ...singleOperation({ responses: { 200: { $ref: "#/components/responses/First" } } }),
+        components: {
+          responses: {
+            First: { $ref: "#/components/responses/Stream" },
+            Stream: { content: { "text/event-stream": { schema: { type: "string" } } } },
+          },
+        },
+      },
+    })
+
+    expect(result.tools).toEqual({})
+    expect(result.skipped[0]?.reason).toBe("SSE operations are not supported")
+  })
+
+  test("resolves response schemas before detecting binary output", () => {
+    const result = OpenAPI.fromSpec({
+      baseUrl,
+      spec: {
+        ...singleOperation({
+          responses: {
+            200: {
+              content: { "text/plain": { schema: { $ref: "#/components/schemas/File" } } },
+            },
+          },
+        }),
+        components: { schemas: { File: { type: "string", format: "binary" } } },
+      },
+    })
+
+    expect(result.tools).toEqual({})
+    expect(result.skipped[0]?.reason).toBe("binary responses are not supported")
+  })
+
+  test("validates composite parameters before resolving auth", async () => {
+    const resolutions: Array<string> = []
+    const client = recordingClient(() => json({ ok: true }))
+    const tool = toolAt(
+      OpenAPI.fromSpec({
+        baseUrl,
+        spec: {
+          ...singleOperation({
+            parameters: [{ name: "filter", in: "query", style: "form", explode: true, schema: { type: "object" } }],
+          }),
+          security: [{ bearer: [] }],
+          components: { securitySchemes: { bearer: { type: "http", scheme: "bearer" } } },
+        },
+        auth: {
+          resolve: ({ name }) => {
+            resolutions.push(name)
+            return Effect.succeed({ type: "bearer", token: "secret" })
+          },
+        },
+      }).tools,
+      "test",
+    )
+    if (!Tool.isDefinition(tool)) throw new Error("test was not generated")
+
+    await expect(
+      Effect.runPromise(tool.run({ filter: { value: undefined } }).pipe(Effect.provide(client.layer))),
+    ).rejects.toThrow("unsupported nested value")
+    expect(resolutions).toEqual([])
+    expect(client.requests).toEqual([])
+  })
+
+  test("preserves JSON media types and rejects unencodable bodies", async () => {
+    const client = recordingClient(() => json({ ok: true }))
+    const tool = toolAt(
+      OpenAPI.fromSpec({
+        baseUrl,
+        spec: singleOperation(
+          {
+            requestBody: {
+              required: true,
+              content: { "application/merge-patch+json": { schema: { type: "object" } } },
+            },
+          },
+          "post",
+        ),
+      }).tools,
+      "test",
+    )
+    if (!Tool.isDefinition(tool)) throw new Error("test was not generated")
+
+    await Effect.runPromise(tool.run({ body: { name: "updated" } }).pipe(Effect.provide(client.layer)))
+    expect(client.requests[0]!.headers["content-type"]).toBe("application/merge-patch+json")
+    const cyclic: Record<string, unknown> = {}
+    cyclic.self = cyclic
+    await expect(Effect.runPromise(tool.run({ body: cyclic }).pipe(Effect.provide(client.layer)))).rejects.toThrow(
+      "Invalid JSON body",
+    )
+  })
+
+  test("rejects oversized and malformed JSON responses", async () => {
+    const tool = toolAt(OpenAPI.fromSpec({ baseUrl, spec: singleOperation({}) }).tools, "test")
+    if (!Tool.isDefinition(tool)) throw new Error("test was not generated")
+    const oversized = recordingClient(
+      () => new Response(null, { headers: { "content-length": String(50 * 1024 * 1024 + 1) } }),
+    )
+    const malformed = recordingClient(
+      () => new Response("{", { headers: { "content-type": "application/json" } }),
+    )
+    const chunked = recordingClient(() => new Response(new Uint8Array(50 * 1024 * 1024 + 1)))
+
+    await expect(Effect.runPromise(tool.run({}).pipe(Effect.provide(oversized.layer)))).rejects.toThrow(
+      "response exceeds 50 MiB",
+    )
+    await expect(Effect.runPromise(tool.run({}).pipe(Effect.provide(malformed.layer)))).rejects.toThrow(
+      "returned malformed JSON",
+    )
+    await expect(Effect.runPromise(tool.run({}).pipe(Effect.provide(chunked.layer)))).rejects.toThrow(
+      "response exceeds 50 MiB",
+    )
+  })
+
+  test("keeps non-JSON responses raw and unions every success output", async () => {
+    const spec = singleOperation({
+      responses: {
+        200: { description: "Text", content: { "text/plain": { schema: { type: "string" } } } },
+        204: { description: "Empty" },
+      },
+    })
+    const tool = toolAt(OpenAPI.fromSpec({ baseUrl, spec }).tools, "test")
+    if (!Tool.isDefinition(tool)) throw new Error("test was not generated")
+    const client = recordingClient(() => new Response("123", { headers: { "content-type": "text/plain" } }))
+
+    expect(outputTypeScript(tool)).toBe("string | null")
+    await expect(Effect.runPromise(tool.run({}).pipe(Effect.provide(client.layer)))).resolves.toBe("123")
+  })
+
+  test("fails missing required parameters before auth and network", async () => {
+    const { requests, layer } = recordingClient(() => json({}))
+    const runtime = CodeMode.make({
+      tools: { opencode: OpenAPI.fromSpec({ spec: await opencodeSpec(), baseUrl }).tools },
+    })
+
+    const result = await Effect.runPromise(
+      runtime.execute("return await tools.opencode.v2.session.get({})").pipe(Effect.provide(layer)),
+    )
+
+    expect(result).toMatchObject({ ok: false })
+    expect(JSON.stringify(result)).toContain("Missing required path parameter 'sessionID'")
+    expect(requests).toHaveLength(0)
+  })
+
+  test("prefixes cross-location collisions and reconstructs the HTTP request", async () => {
+    const spec = {
+      openapi: "3.1.0",
+      info: { title: "collision", version: "1.0.0" },
+      paths: {
+        "/echo": {
+          post: {
+            operationId: "echo",
+            requestBody: {
+              required: true,
+              content: { "application/json": { schema: { type: "string" } } },
+            },
+            responses: { "204": { description: "Echoed" } },
+          },
+        },
+        "/things/{id}": {
+          post: {
+            operationId: "things.update",
+            parameters: [
+              { name: "id", in: "path", required: true, schema: { type: "string" } },
+              { name: "id", in: "query", required: true, schema: { type: "string" } },
+              { name: "path_id", in: "query", schema: { type: "string" } },
+              { name: "id", in: "header", required: true, schema: { type: "string" } },
+            ],
+            requestBody: {
+              required: true,
+              content: {
+                "application/json": {
+                  schema: {
+                    type: "object",
+                    properties: { id: { type: "string" } },
+                    required: ["id"],
+                    additionalProperties: false,
+                  },
+                },
+              },
+            },
+            responses: { "204": { description: "Updated" } },
+          },
+        },
+      },
+    } satisfies Document
+    const { requests, layer } = recordingClient(() => new Response(null, { status: 204 }))
+    const tools = OpenAPI.fromSpec({ spec, baseUrl }).tools
+    const update = toolAt(tools, "things.update")
+    const echo = toolAt(tools, "echo")
+
+    expect(Tool.isDefinition(update)).toBe(true)
+    if (!Tool.isDefinition(update)) throw new Error("things.update was not generated")
+    expect(inputTypeScript(update)).toBe(
+      "{ path_id: string; query_id: string; path_id_2?: string; header_id: string; body_id: string }",
+    )
+    expect(Tool.isDefinition(echo)).toBe(true)
+    if (!Tool.isDefinition(echo)) throw new Error("echo was not generated")
+    expect(inputTypeScript(echo)).toBe("{ body: string }")
+
+    const runtime = CodeMode.make({ tools })
+    const result = await Effect.runPromise(
+      runtime
+        .execute(
+          `
+            const updated = await tools.things.update({ path_id: "path", query_id: "query", path_id_2: "literal", header_id: "header", body_id: "body" })
+            const echoed = await tools.echo({ body: "hello" })
+            return { updated, echoed }
+          `,
+        )
+        .pipe(Effect.provide(layer)),
+    )
+
+    expect(result).toMatchObject({ ok: true })
+    expect(requests).toHaveLength(2)
+    expect(new URL(requests[0]!.url).pathname).toBe("/things/path")
+    expect(new URL(requests[0]!.url).searchParams.get("id")).toBe("query")
+    expect(new URL(requests[0]!.url).searchParams.get("path_id")).toBe("literal")
+    expect(requests[0]!.headers.id).toBe("header")
+    expect(requests[0]!.body).toStrictEqual({ id: "body" })
+    expect(requests[1]!.body).toBe("hello")
+  })
+
+  test("keeps bodies nested when flattening would lose schema semantics", () => {
+    const body = (schema: Record<string, unknown>, required = true) => ({
+      required,
+      content: { "application/json": { schema } },
+    })
+    const spec = {
+      openapi: "3.1.0",
+      info: { title: "bodies", version: "1.0.0" },
+      paths: Object.fromEntries(
+        [
+          [
+            "optional",
+            body(
+              {
+                type: "object",
+                properties: { name: { type: "string" } },
+                required: ["name"],
+                additionalProperties: false,
+              },
+              false,
+            ),
+          ],
+          ["dictionary", body({ type: "object", additionalProperties: { type: "string" } })],
+          [
+            "composed",
+            body({
+              type: "object",
+              allOf: [{ type: "object", properties: { name: { type: "string" } }, required: ["name"] }],
+              additionalProperties: false,
+            }),
+          ],
+          [
+            "nullable",
+            body({
+              type: ["object", "null"],
+              properties: { name: { type: "string" } },
+              additionalProperties: false,
+            }),
+          ],
+        ].map(([name, requestBody]) => [
+          `/body/${name}`,
+          {
+            post: {
+              operationId: `body.${name}`,
+              requestBody,
+              responses: { "204": { description: "Accepted" } },
+            },
+          },
+        ]),
+      ),
+    } satisfies Document
+    const tools = OpenAPI.fromSpec({ spec, baseUrl }).tools
+
+    for (const name of ["optional", "dictionary", "composed", "nullable"]) {
+      const tool = toolAt(tools, `body.${name}`)
+      expect(Tool.isDefinition(tool)).toBe(true)
+      if (!Tool.isDefinition(tool)) throw new Error(`body.${name} was not generated`)
+      const input = isRecord(tool.input) ? tool.input : {}
+      expect(Object.keys(isRecord(input.properties) ? input.properties : {})).toStrictEqual(["body"])
+    }
+    const optional = toolAt(tools, "body.optional")
+    if (!Tool.isDefinition(optional)) throw new Error("body.optional was not generated")
+    expect(inputTypeScript(optional)).toBe("{ body?: { name: string } }")
+  })
+})

packages/codemode/test/signature.test.ts

@@ -159,8 +159,8 @@ describe("pretty signature rendering", () => {
       $ref: "#/$defs/Node",
       $defs: { Node: { type: "object", properties: { child: { $ref: "#/$defs/Node" }, name: { type: "string" } } } },
     } as const
-    expect(jsonSchemaToTypeScript(cyclic)).toBe("{ child?: Node; name?: string }")
-    expect(jsonSchemaToTypeScript(cyclic, true)).toContain("child?: Node")
+    expect(jsonSchemaToTypeScript(cyclic)).toBe("{ child?: unknown; name?: string }")
+    expect(jsonSchemaToTypeScript(cyclic, true)).toContain("child?: unknown")
 
     let deep: Record<string, unknown> = { type: "string" }
     for (let level = 0; level < 12; level += 1) deep = { type: "object", properties: { next: deep } }
@@ -170,6 +170,43 @@ describe("pretty signature rendering", () => {
       expect(rendered).toContain("next?:")
     }
   })
+
+  test("intersects ref and union siblings instead of discarding them", () => {
+    expect(
+      jsonSchemaToTypeScript({
+        $ref: "#/$defs/User",
+        properties: { active: { type: "boolean" } },
+        required: ["active"],
+        $defs: {
+          User: { type: "object", properties: { id: { type: "string" } }, required: ["id"] },
+        },
+      }),
+    ).toBe("{ id: string } & { active: boolean }")
+    expect(
+      jsonSchemaToTypeScript({
+        type: "object",
+        properties: { common: { type: "boolean" } },
+        required: ["common"],
+        anyOf: [
+          { type: "object", properties: { name: { type: "string" } }, required: ["name"] },
+          { type: "object", properties: { count: { type: "number" } }, required: ["count"] },
+        ],
+      }),
+    ).toBe("({ name: string } | { count: number }) & { common: boolean }")
+    expect(jsonSchemaToTypeScript({ $ref: "https://example.com/schema.json" })).toBe("unknown")
+    expect(
+      jsonSchemaToTypeScript({
+        $ref: "#/$defs/User/properties/id",
+        $defs: { User: { type: "object" }, id: { type: "string" } },
+      }),
+    ).toBe("unknown")
+    expect(
+      jsonSchemaToTypeScript({
+        type: ["object", "null"],
+        properties: { name: { type: "string" } },
+      }),
+    ).toBe("{ name?: string } | null")
+  })
 })
 
 describe("non-identifier property names render as quoted keys", () => {
@@ -268,6 +305,32 @@ describe("union schemas render every alternative", () => {
     expect(inputTypeScript(tool)).toBe("{ value?: string | number }")
     expect(outputTypeScript(tool)).toBe("number | boolean")
   })
+
+  test("allOf renders intersections with parenthesized union members", () => {
+    const schema = {
+      allOf: [
+        { type: "object", properties: { id: { type: "string" } } },
+        { type: ["string", "null"] },
+      ],
+    } as const
+    expect(jsonSchemaToTypeScript(schema)).toBe("{ id?: string } & (string | null)")
+  })
+
+  test("allOf does not discard an unresolved constraint", () => {
+    expect(jsonSchemaToTypeScript({ allOf: [{ type: "string" }, { $ref: "https://example.com/external.json" }] })).toBe(
+      "unknown",
+    )
+    expect(
+      jsonSchemaToTypeScript({ allOf: [{ type: "string" }, { allOf: [{ $ref: "https://example.com/external.json" }] }] }),
+    ).toBe("unknown")
+    expect(
+      jsonSchemaToTypeScript({
+        type: "string",
+        allOf: [{ $ref: "#/$defs/Constraint" }],
+        $defs: { Constraint: { description: "TypeScript-neutral constraint" } },
+      }),
+    ).toBe("string")
+  })
 })
 
 describe("pretty signatures in search results", () => {

packages/protocol/src/groups/pty.ts

@@ -127,6 +127,7 @@ export const PtyGroup = HttpApiGroup.make("server.pty")
         description: "Establish a WebSocket connection streaming PTY output and accepting terminal input.",
         transform: (operation) => ({
           ...operation,
+          "x-websocket": true,
           parameters: [
             ...(operation.parameters ?? []),
             ...["location[directory]", "location[workspace]", "cursor", PTY_CONNECT_TICKET_QUERY].map((name) => ({