# oapi_codemode v0.4.1 - Table of Contents

> OpenAPI search-and-execute tools for LLM agents, Cloudflare code-mode style — the sandbox never sees your credentials

## Pages

- [OapiCodemode](readme.md)

## Modules

- [OapiCodemode](OapiCodemode.md): OpenAPI search-and-execute for LLM agents, Cloudflare-codemode style.
- [OapiCodemode.ApiConfig](OapiCodemode.ApiConfig.md): Per-API registration config. Everything the spec cannot know.
- [OapiCodemode.Artifact](OapiCodemode.Artifact.md): The ingestion output: sandbox spec payload plus the proxy's operation index.
- [OapiCodemode.Credentials](OapiCodemode.Credentials.md): Host-implemented credential resolution, library-implemented attachment.
- [OapiCodemode.Executor](OapiCodemode.Executor.md): The sandbox contract — the entire interface a TS execution environment
must satisfy. Deliberately minimal: run code with globals and callbacks,
return the value and console output.
- [OapiCodemode.Executor.Deno](OapiCodemode.Executor.Deno.md): Subprocess Deno executor — the alternative to the recommended
`OapiCodemode.Executor.SafeJS`, and the only one that dispatches a
guest's `Promise.all` requests *concurrently*. The costs against SafeJS:
a `deno` 2.x binary must be on `PATH` in every image that runs it, and
V8 has no hard memory cap (an `ArrayBuffer` bomb walks past
`--max-old-space-size`). Its `:timeout`, unlike SafeJS's, is a
wall-clock deadline that already includes host-callback time.
- [OapiCodemode.Executor.Mock](OapiCodemode.Executor.Mock.md): Test executor: the "sandbox" is an Elixir function you set per test.
Exercises the plumbing (globals in, callbacks out, results back) without
a JS runtime.
- [OapiCodemode.Executor.SafeJS](OapiCodemode.Executor.SafeJS.md): The recommended executor: in-process on
[ex_safejs](https://github.com/jtippett/ex_safejs), the QuickJS-NG engine
embedded as a Rustler NIF (our hard fork of lpgauth/quicksand). A hex
dependency with precompiled binaries is the whole deployment story — no
runtime binary in the image, no subprocess, no container config — and
QuickJS's own allocator is the sole memory authority, so a guest's live
memory is genuinely capped: typed-array/`ArrayBuffer` bombs, the vector
that escapes V8's heap limit, come back as a structured out-of-memory
error. The engine is complete and mature (regex included — global match,
named groups, lookaheads) with O(1) container access, so searching a
multi-MB spec as data is not pathological.
- [OapiCodemode.Executor.ZapCode](OapiCodemode.Executor.ZapCode.md): In-process executor on [ex_zapcode](https://github.com/jtippett/ex_zapcode),
a pure-Rust TypeScript-subset interpreter shipped as a NIF. Like
`OapiCodemode.Executor.SafeJS` it deploys as nothing but a hex dependency
— no subprocess, no runtime binary in the image, no container config —
and bounds live guest memory (`limits: %{max_memory: bytes}`).
- [OapiCodemode.Ingest](OapiCodemode.Ingest.md): Pure pipeline: raw spec source -> `OapiCodemode.Artifact`.
- [OapiCodemode.Ingest.Deref](OapiCodemode.Ingest.Deref.md): Resolves all same-document $refs inline so sandbox code never chases references.
- [OapiCodemode.Ingest.Normalize](OapiCodemode.Ingest.Normalize.md): Extracts a flat operation list from a dereferenced spec, deriving stable
readable ids where operationId is missing (the oaskit `cards_freeze_ALTIJVI`
lesson: never trust upstream ids to exist or be usable).

- [OapiCodemode.Ingest.Parser](OapiCodemode.Ingest.Parser.md): Parses raw YAML/JSON into a map and checks it is an OpenAPI 3.x document.
- [OapiCodemode.Operation](OapiCodemode.Operation.md): One HTTP operation extracted from a spec, ready for matching and validation.
- [OapiCodemode.Proxy](OapiCodemode.Proxy.md): The validating, credential-injecting request pipeline:
match -> policy -> validate -> credentials -> execute -> normalize.
- [OapiCodemode.Proxy.Matcher](OapiCodemode.Proxy.Matcher.md): Matches an intercepted (method, path) against the operation index.
On failure, suggests the nearest operations so the model can self-correct
without another search round-trip.

- [OapiCodemode.Proxy.Query](OapiCodemode.Proxy.Query.md): Serializes query parameters honoring the spec's style/explode declarations
(the ele lesson: default serializers silently mismatch backend expectations).
Supported: form (explode true/false), deepObject, spaceDelimited,
pipeDelimited. Anything else falls back to form+explode.
- [OapiCodemode.Proxy.Validator](OapiCodemode.Proxy.Validator.md): Validates an intercepted request against the operation's dereferenced schema.
- [OapiCodemode.Registry](OapiCodemode.Registry.md): Holds ingested artifacts and per-API config in ETS. No persistence:
hosts re-register at boot from wherever they keep specs.
- [OapiCodemode.Registry.Entry](OapiCodemode.Registry.Entry.md)
- [OapiCodemode.Tools](OapiCodemode.Tools.md): Emits the two codemode tools as data plus handlers. Transport-agnostic:
hosts wrap these into their own tool layers (gentility's CloudLoop.Tool,
ele's UserMCP.Tool, or a gen_mcp server).
- [OapiCodemode.Tools.Descriptions](OapiCodemode.Tools.Descriptions.md): Assembles search/execute tool descriptions from registry state. The
description IS the documentation — every global the sandbox actually
receives must be declared here, with real names, or the model has to
guess at them.

- [OapiCodemode.Tools.Result](OapiCodemode.Tools.Result.md): JSON-encodes tool results with a budget cap and an instructive trailer.

