This repository is the reference TypeScript implementation of the OpenAI API Rewrite Framework. It is a server-side rewrite layer that sits between OpenAI-compatible clients and upstream model providers, transparently transforming tools, tool_choice, tool calls, and tool results while keeping the client API unchanged.

The framework provides three complementary mechanisms:

1. Compressing rewrites — proxy-handled tools, I/O variants, server-side VFS, and subagent compression.
2. Exposing rewrites — deterministic synthetic tool calls injected by the server (e.g. code_search, integration adapters) before the model sees the request.
3. Virtual tool calling — tunnel disallowed tools through user messages for providers with restricted allowlists.

Rewrite state is carried across turns in encrypted reasoning/thinking envelopes when available, or through an optional per-session fallback store.

1. Install dependencies:

   npm install

2. Place provider credentials in .env:

   PROVIDER_API_KEY="sk-..."
   PROVIDER_BASE_URL="https://api.openai.com/v1"
   PROVIDER_MODEL="gpt-4o"

3. Start the dev server:

   npm run dev
   # or
   npx tsx src/cli.ts --config examples/config.yaml

4. Hit the health endpoint to confirm it is up:

   curl http://localhost:3000/health

5. Make an OpenAI-compatible chat request through the proxy:

   curl http://localhost:3000/v1/chat/completions \
     -H "Content-Type: application/json" \
     -H "X-Session-Id: quickstart" \
     -d '{ "model": "gpt-4o", "messages": [{"role": "user", "content": "What is in /workspace/readme.md?"}], "tools": [{"type": "function", "function": {"name": "code_search", "description": "Search the codebase", "parameters": {"type": "object", "properties": {"query": {"type": "string"}}, "required": ["query"]}}}] }'

A runnable client example is in examples/client-snippet.ts.

The proxy is configured through a server-side rewrite registry. See examples/config.yaml.

Key concepts:

• Compressing tools (kind: compressing) are emitted by the model and intercepted by the proxy. They can be proxy-handled, variant-compressed, routed to a subagent, or forwarded to the provider.
• Exposing tools (kind: exposing) are deterministic synthetic calls triggered before the model turn. model_visible: false hides them from the provider request while still showing them to the client as normal model-originated calls.
• Provider capabilities describe which tools the upstream provider supports and which tool patterns should be virtualized.
• disallowed_strategy selects how unsupported tools behave: message (encode as user content), internal (execute by proxy), or block (reject).

• The rewrite registry is never sent to clients or providers; tool schemas are plain OpenAI function definitions.
• Rewrite state is encrypted with a per-tenant or per-session key using AES-256-GCM. Tampered envelopes are rejected.
• Envelopes are nested into provider reasoning/thinking fields when available, or stored server-side when not.
• VFS paths and integration adapters should be validated and tenant-isolated in production deployments.

Run checks:

npm run typecheck
npm run lint
npm test

Run the full suite including gate-keyed real-provider integration tests:

npm test

Gate-skipped tests fail gracefully when a provider is rate-limited or does not support the required capabilities.

src/
  agent/          # Agent and WrapperProvider harness
  cli.ts          # CLI dev server entry point
  crypto/         # Envelope encryption and key derivation
  errors/         # Error normalization
  idmap/          # Tool-call ID remapping
  observability/  # Rewrite decision logging
  passes/         # Exposing, compressing, and virtual-tool passes
  pipeline/       # Request/response pipeline orchestration
  provider/       # Provider adapter interface and OpenAI REST adapter
  tools/          # VFS, code search, integration adapters
  types/          # OpenAI, rewrite, envelope, and registry types
examples/
  config.yaml          # Example rewrite registry
  client-snippet.ts    # Stock OpenAI SDK client targetting the proxy
  dev-server.ts        # Programmatic example of driving the wrapper
tests/
  unit/           # Fast, provider-free tests
  integration/    # Real-provider integration tests gated by capability
  agent/          # Agent-driven end-to-end feature tests with pass@n

MIT