wishforge-ide/docs/reference/provider-proxy.md
eust-w 86649af4d6 docs: rewrite architecture and restructure documentation
- docs/architecture.md replaces system-design.md: component map,
  run state machine with an explicit waiting-reason catalogue, key
  sequences (dispatch, execute/verify/repair, integrate, release,
  IDE launch, lessons), data model, API surface, identity and trust
  model, isolation modes (host for local development, kata for
  production), deployment topology, ADRs, known limitations and a
  requirement-to-test verification matrix.
- docs/development.md: local setup, one-command start, first wish,
  IDE, MCP and the test matrix (integration toggles are explicit).
- docs/operations.md: production prerequisites, explicit deployment
  mode, component configuration, Kubernetes provisioner, tenants and
  quotas, IDE gateway routing and lifecycle, delivery, monitoring,
  backup/restore, incident handling and known risks. Merges the former
  observability, recovery, billing-entitlements and runbook documents.
- Contract documents move to docs/reference/; evidence narratives that
  pointed at machine-local /private/tmp files are removed and the UI
  reference is rewritten for the target console.
- Delete docs for removed scope: workspace snapshot handoff and private
  application access.
- README rewritten as a concise entry point.

The documents describe the target state that the following
implementation commits realise.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-19 13:29:46 +08:00

5.9 KiB

Run-scoped Codex model proxy

The production execution job receives a proxy token, not the tenant's long-lived OpenAI API key. Only the control-plane/Vault process can decrypt that key. The proxy constructs the upstream URL itself: https://api.openai.com/v1/responses for POST and https://api.openai.com/v1/models for GET. Client-selected upstream URLs, redirects, arbitrary headers and additional API routes are refused.

Integration contract

const proxy = new ProviderProxy(store, env);
const credential = await proxy.credential(actor, run);
// { apiKey: proxyToken, baseUrl, expiresAt, metering: 'proxy' }
const upstreamResponse = await proxy.forward({
  authorization, method, path, headers, body: rawUint8Array, signal
});
// Standard Response, including a ReadableStream for SSE.

The public base URL includes /provider-proxy/v1. The HTTP adapter strips that prefix and passes exactly /responses or /models to forward. It must forward Response bodies with backpressure/cancellation, use no request-body logging, and never route this bearer through the ordinary OIDC or internal-service guard. The proxy independently authenticates its own audience. The credential carries metering: proxy; worker-reported model tokens must not be charged again.

Required configuration:

  • WF_PROVIDER_PROXY_PUBLIC_URL: production HTTPS base URL ending in /provider-proxy/v1; development permits explicit localhost HTTP.
  • WF_PROVIDER_PROXY_SIGNING_KEY: independent secret of at least 32 characters.
  • WF_PROVIDER_PROXY_ALLOWED_MODELS: comma-separated operator-approved model IDs.
  • Development additionally requires WF_PROVIDER_PROXY_ENABLED=true.
  • Production credential decryption uses the existing external Vault integration.

Proxy JWTs have a separate issuer/audience and a lifetime bounded by both the remaining task budget and one hour. They bind tenant, run, execution generation, lease token, authenticated worker principal and the exact provider-connection version. Every request rechecks these bindings. While a stream is active the proxy repeats the checks at most one second apart and aborts its upstream reader when cancellation, lease expiry, generation replacement or credential revocation is observed. Polling revocation is bounded, not an instantaneous network cutoff; already-dispatched provider work may still incur usage after an abort.

Budget and request state

Only one upstream request may be active per run. Before external I/O the API persists its request claim under the tenant transaction lock. A request is keyed by run/generation/lease/connection and its idempotency key, or the body digest when the client provides no key. Changing the body under the same key fails. Completed bounded responses can be replayed without another provider request.

The proxy supports self-contained text, local function/custom tools and bounded namespaces containing only those local tool types. It rejects conversation/previous-response references, stored prompt templates, remote MCP and hosted tools, background execution, multimodal/file inputs and unverified top-level parameters. It forces store: false, default service tier, and tenant/run-specific cache and safety identifiers. Model/context choices that need an unsupported wire feature must fail explicitly, without reverting to a raw API key.

Input reservation uses serialized text bytes plus conservative protocol overhead. max_output_tokens is bounded by the run's remaining reservation. This is a conservative admission estimate, not an exact tokenizer or monetary quotation. Actual billing tokens are accepted only from the trusted upstream JSON usage or terminal Responses SSE usage (input_tokens + output_tokens == total_tokens). The ledger charges each proxy request once, independently of executor output. If actual usage exceeds the remaining budget, the actual value is recorded and new execution stops. No preflight estimate guarantees a remote provider cannot report an in-flight overrun.

SSE frames are parsed across byte and CRLF boundaries, bounded in size and redacted before forwarding/caching. Upstream authorization/error headers are not forwarded. Non-success provider bodies are replaced with generic errors so they cannot echo the private key. Requests are bounded to 2 MiB, SSE frames to 1 MiB, responses to 16 MiB, replay caches to 2 MiB and one upstream call to 120 seconds. These limits are explicit compatibility constraints for live Codex validation.

If a dispatched POST times out, the stream ends without trusted terminal usage, or the client disconnects, the record becomes unknown. Its active reservation is retained and the run waits with provider_usage_unknown. Subsequent requests, including after a new execution lease, cannot blindly repeat the operation. There is no automated resolution that invents usage; an operator must reconcile the provider's actual outcome before execution can safely resume. Raw prompts and original credentials are not recorded in these operation rows. Replay data is tenant-owned model output and remains subject to platform retention controls.

Official API references: Responses create, streaming Responses.

Tests

tests/provider-proxy.test.ts uses an injected local fake upstream and covers audience separation, tenant/lease/generation/connection binding, SSE chunking, secret redaction, one-time metering, route/tool/model denial, cancellation, connection rotation, budget admission and unresolved-outcome handling. WF_CODEX_SDK_INTEGRATION=1 npx vitest run tests/integration/codex-sdk.test.ts runs the pinned Codex SDK/CLI through the real proxy against a local fake upstream; it does not contact a real model.

CodeBuddy stays disabled in production until an equivalent proxy protocol exists. Unsupported Codex features and expired scoped tokens never fall back to an ambient account or a long-lived key.