- 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>
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.