@raybase/openai-subscription 0.0.0 → 0.1.0

package/templates/tanstack-start/.agents/skills/raybase-openai-subscription/references/compatibility-and-testing.md

@@ -0,0 +1,129 @@
+# Compatibility and testing
+
+Use this ladder to diagnose the narrowest failing contract without leaking
+credentials or poisoning a healthy subscription lane.
+
+## Diagnostic ladder
+
+1. Start with a freshly linked eligible account and a minimal request with no
+   tools or response format. Confirm account/workspace/model routing and SSE.
+2. Add one known-valid strict function tool whose parameters are a closed root
+   object. This isolates tool transport from the app's tool catalog.
+3. Test final structured output separately with Responses `text.format`.
+   Function `parameters` and final response schemas share the strict subset but
+   occupy different request fields.
+4. Replay the exact failing app schema. Record only HTTP status, the module's
+   sanitized and bounded fingerprint, request ID presence, counts, and sizes.
+   A bounded request ID may remain on the thrown error as an opaque support
+   correlation handle, but do not persist it automatically. Never record
+   request authorization, relay secrets, cookies, account IDs, raw messages or
+   parameter paths, bodies containing private input, or unrelated response
+   headers.
+5. Classify ownership before changing health:
+   - auth/revocation/eligibility/account selection;
+   - rate limit or transient upstream failure;
+   - fixed transport envelope/header/stream drift;
+   - caller tool or response schema;
+   - app action validation after a valid model response.
+6. For a parseable caller schema `400`, assert the public fingerprint is
+   sanitized and capped, the upstream message/parameter are absent, and
+   subscription health stays at its previous connected state. The app may
+   separately record its selected model attempt as failed.
+7. After focused fixtures pass, complete a real subscription-backed app turn
+   through the local relay with the app's full tool catalog. Check the rendered
+   response and both health surfaces.
+
+## Minimum fixtures
+
+Cover all of these with exact schema assertions and restoration tests:
+
+- closed root object with every property required;
+- optional scalar represented with `null` and removed for the original app
+  validator;
+- optional `const` using `anyOf` with `null`;
+- root discriminated and plain unions normalized to one object;
+- nested `oneOf` policy and nested `anyOf` output;
+- selected-branch recursive restoration;
+- arrays containing normalized objects;
+- open records encoded as JSON strings and parsed back to objects;
+- unconstrained values encoded as JSON strings and parsed back to every JSON
+  value kind;
+- malformed/non-object roots rejected before transport;
+- invalid JSON encodings rejected by the original validator;
+- sanitized JSON refusal fixtures for both response-format
+  `invalid_json_schema` and tool `invalid_function_parameters` envelopes;
+- `invalid_function_parameters` mapped without upstream detail or a health
+  incident;
+- code-first/type-fallback normalization, hostile punctuation, a 32-character
+  token cap, and omission of overlong request IDs;
+- empty, malformed, oversized, non-object, and detail-free `400` bodies mapped
+  to `protocol:unexpected_http_status_400` with
+  `protocol_update_required`;
+- provider-level proof that a connected subscription remains connected with no
+  incident for a parseable request rejection, while an unclassifiable `400`
+  still transitions health.
+
+## Request content verified 2026-08-11
+
+A redacted local probe against the private subscription endpoint verified the
+request-side image boundary independently of the public OpenAI API:
+
+- Ordered image content uses `{ "type": "input_image", "image_url": ... }`.
+  Both an absolute HTTPS URL and a `data:image/...;base64,...` value completed.
+- Inline PNG, JPEG, WEBP, and non-animated GIF samples completed.
+- Omitting `detail` completed, as did explicit upstream probes for `auto`,
+  `low`, `high`, and `original`. Raybase's provider-neutral image contract does
+  not expose that knob, so the adapter always omits it; no semantic equivalence
+  between the values was inferred.
+- `quality` is not an image-input field here. The endpoint rejected it with
+  `400 unknown_parameter` at the image part, and Raybase rejects it locally
+  rather than sending it.
+- A valid 1x1 PNG carrying valid ancillary padding completed through
+  **19,573,864 encoded JSON request bytes** and **14,680,144 decoded image
+  bytes**. No rejection occurred below the probe's hard 20 MiB request-body
+  safety cap, so the exact private limit remains unverified. This proves a
+  request-body lower bound, not an image-decoding or useful-pixel bound.
+
+Agent attachments remain deliberately more conservative: the default is 8 MiB
+per file, before base64 expansion, plus the configured per-message attachment
+count. Endpoint permissiveness does not widen those runtime admission limits.
+
+Documented or adjacent content kinds that remain unsupported are Responses
+`input_file` (file URL, file ID, or base64 file data), image-by-file-ID, Codex
+`input_audio`/audio URLs, multimodal function-call outputs, assistant image
+content, and image-generation/output-item families. Core exposes no image
+result or stream event and this module does not author an image-generation
+tool. The response-side test therefore asserts the gap precisely:
+`image_generation_call` still fails closed as
+`protocol:unknown_output_item`; it is not silently skipped.
+
+## Live smoke requirements
+
+Use a disposable app copy and the candidate Core CLI/package, not an old
+workspace binary. Keep existing secret files out of output and source control.
+For a runtime integration:
+
+1. `raybase modules doctor` passes the runtime contract.
+2. `raybase doctor`/`raybase check` contain no installed-only subscription
+   findings.
+3. `raybase modules status --json` reports `integration: "runtime"`, enabled,
+   not scaffold-installed.
+4. `raybase dev` starts the loopback relay and injects both local names.
+5. A linked subscription turn reaches the expected model with the full app tool
+   set and renders a response.
+6. Subscription health and app model health are healthy afterward.
+7. Clean shutdown removes temporary relay values.
+8. Removing the declaration restores the non-blocking undeclared-dependency
+   advisory and skips relay startup.
+
+Do not replace the real linked turn with a mock when live acceptance is part of
+the plan. If linking or upstream access is unavailable, record the exact blocker
+and keep the implementation partial.
+
+## Reconfirming Codex mapping
+
+When Codex CLI behavior matters, inspect a pinned open-source tag. Trace
+`--output-schema` from CLI configuration to the Responses request and compare it
+with current official OpenAI docs. Do not infer an API parameter from an
+internal Rust type name, and do not vendor a mutable Codex checkout into the
+module skill.

package/templates/tanstack-start/.agents/skills/raybase-openai-subscription/references/module-contract.md

@@ -0,0 +1,133 @@
+# Module contract
+
+This reference describes the working developer contract for Raybase's
+experimental `@raybase/openai-subscription` module. Private upstream details
+are observations, not a public OpenAI API guarantee.
+
+## Integration shapes
+
+### Installed
+
+`raybase modules add openai-subscription` owns the scaffold, module lock,
+selected `openai-codex-subscription` provider, credential and background
+strategy, generated provider manifest, and production egress binding. An
+omitted `integration` field means `"installed"`. Exact install-lock provenance
+wins; it cannot be relabeled runtime to bypass drift checks.
+
+### Runtime-registered
+
+An app with its own dispatcher may register the package's public runtime API
+and declare:
+
+```json
+{
+  "raybase": {
+    "modules": {
+      "openai-subscription": {
+        "enabled": true,
+        "package": "@raybase/openai-subscription",
+        "integration": "runtime"
+      }
+    }
+  }
+}
+```
+
+The exact package must be a production dependency. Applicable Wrangler
+`secrets.required` scopes declare `RAYBASE_OPENAI_SUBSCRIPTION_KEY`, and
+`env.local-dev.secrets.required` declares `RAYBASE_LOCAL_CODEX_RELAY_URL` and
+`RAYBASE_LOCAL_CODEX_RELAY_SECRET`. Runtime doctor does not require the
+installed provider source, selected-provider manifest, or `CODEX_EGRESS`.
+
+An enabled declaration of either flavor starts the dev relay. An undeclared
+direct dependency does not; doctor gives a non-blocking advisory rather than
+guessing from imports.
+
+## Credentials and scope
+
+- `operator`: one explicitly responsible operator-linked credential scope.
+- `user`: separately linked user scopes; never cross users or tenants.
+- `organization`: use only with the corresponding reviewed organization
+  arrangement and application policy.
+
+Store encrypted credentials in the module's durable store. Keep the encryption
+key in Worker secrets only. Device codes may be shown during an active link,
+but access, refresh, identity, device, relay, and encryption secrets never enter
+logs, source, browser persistence, fixtures, backups, screenshots, or handoffs.
+Account/workspace selection is explicit; relinking replaces the intended scope,
+not an arbitrary healthy credential.
+
+Raybase informs but does not certify subscription-plan compliance. Never pool a
+personal plan across unrelated employees, customers, users, or tenants. Prefer
+individually linked eligible accounts or the appropriate Business, Enterprise,
+or API arrangement.
+
+These illustrations remain explicitly non-certifying:
+
+- Plausible personal-use example: a private, noncommercial household app
+  operated by the subscription holder and used within that household—
+  Birch-shaped, with one household, one operator, two partners, and one
+  subscription in the operator's name.
+- Likely inappropriate: one personal subscription pooled for employees,
+  customers, unrelated users, or multiple tenants.
+- Safer small-team pattern: each user links an eligible subscription, or the
+  team uses an appropriate Business, Enterprise, or API arrangement.
+- Multi-tenant pattern: tenant/user-scoped credentials; never silently reuse
+  one tenant or operator credential in another tenant.
+
+## Local relay and deployed egress
+
+Local development uses a per-boot, loopback-only relay. `raybase dev` injects a
+URL and authorization secret into the local worker for that session and removes
+them during cleanup. Do not print or persist the secret. A relay startup or
+injection failure is fatal to dev startup and must name the consequence: the
+OpenAI subscription lane is unavailable for the session.
+
+Production uses the reviewed egress binding and fixed transport implementation.
+Keep the route allowlist narrow, strip caller-supplied authorization and routing
+headers, set only reviewed headers, stream without buffering the whole response,
+propagate cancellation, and bound error-body reads. Do not make endpoints,
+headers, or account-routing details application-configurable.
+
+## Health and error ownership
+
+Persisted subscription health describes the credential/transport lane, not all
+caller mistakes.
+
+- Authentication, account eligibility, workspace selection, revocation, rate
+  limits, and reviewed transport compatibility map to their specific safe
+  health states and retry/action guidance.
+- `protocol_update_required` is reserved for transport-owned drift: a fixed
+  endpoint, required header, request/response envelope, or streaming protocol
+  no longer matches the reviewed implementation.
+- A parseable Codex `400` with a usable machine `error.code`, or `error.type`
+  as fallback, is a safe request error. Normalize it to lowercase, replace
+  non-`[a-z0-9_]` runs, trim separators, cap the token at 32 characters, and
+  emit `protocol:codex_400_<token>` without a health field.
+- Preserve the exact `invalid_function_parameters` plus
+  `tools[n].parameters` ownership case. Free-form upstream `message` text
+  never participates in classification or public output; `param` participates
+  only in that exact tool-schema check. Leave previously connected
+  subscription health intact.
+- Empty, malformed, oversized, non-object, and machine-detail-free `400`
+  bodies remain `protocol:unexpected_http_status_400` with
+  `protocol_update_required` because caller ownership is not established.
+- A trimmed, non-empty `x-oai-request-id` of at most 128 characters may travel
+  as opaque `oaiRequestId` metadata on the thrown error. Keep it separate from
+  the fingerprint and do not automatically persist it in health, incidents,
+  notifications, or audits.
+- App model routing may separately mark its chosen model lane unhealthy after a
+  bad request; that must not be confused with subscription credential health.
+- Transient upstream failures use bounded retry policy and must not be relabeled
+  permanent protocol drift.
+
+When genuine protocol drift occurs, update and re-review the module. Operators
+must not edit fixed endpoints, allowlists, or private headers to work around it.
+
+## Provenance
+
+Observed and reconfirmed 2026-08-10 against the open-source Codex CLI tag
+`rust-v0.146.0-alpha.9.2` (commit
+`86cc9f2177cad015befd595286d8767a650f7d13`) and live Responses behavior. Recheck
+these observations during compatibility updates; do not treat the date or tag
+as an upstream stability promise.

package/templates/tanstack-start/.agents/skills/raybase-openai-subscription/references/structured-outputs.md

@@ -0,0 +1,159 @@
+# Structured outputs and strict tool schemas
+
+This is the self-contained schema contract developers need when sending
+structured output through the module. It is the standard OpenAI Structured
+Outputs subset, not a subscription-specific alternative.
+
+## Two request shapes, one strict subset
+
+Final structured output in the Responses API uses `text.format`:
+
+```json
+{
+  "model": "MODEL_ID",
+  "input": "Extract project metadata",
+  "text": {
+    "format": {
+      "type": "json_schema",
+      "name": "project_metadata",
+      "strict": true,
+      "schema": {
+        "type": "object",
+        "properties": { "name": { "type": "string" } },
+        "required": ["name"],
+        "additionalProperties": false
+      }
+    }
+  }
+}
+```
+
+Codex CLI's `--output-schema` maps to this Responses shape. The internal name
+`codex_output_schema` is not a top-level API request parameter.
+
+Strict function tools put the schema in `parameters`:
+
+```json
+{
+  "type": "function",
+  "name": "project_lookup",
+  "description": "Look up one project.",
+  "strict": true,
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "projectId": { "type": "string" },
+      "includeArchived": { "type": ["boolean", "null"] }
+    },
+    "required": ["projectId", "includeArchived"],
+    "additionalProperties": false
+  }
+}
+```
+
+The transport forwards both shapes; it does not turn an invalid application
+schema into a valid one.
+
+## Required subset rules
+
+1. The root is always `{ "type": "object" }`. Root `anyOf` and root `oneOf`
+   unions are rejected.
+2. Every object has `additionalProperties: false`.
+3. Every property is named in `required`. Represent model-level optionality by
+   allowing `null`, then remove a `null` placeholder before app validation when
+   the original field was optional.
+4. Nested `anyOf` is supported. Strict function parameters reject `oneOf`;
+   avoid it or deliberately normalize it to nested `anyOf` while keeping the
+   original validator authoritative.
+5. Do not send unsupported composition or conditionals such as `allOf`, `not`,
+   `if`, `then`, or `else` unless current official compatibility explicitly
+   supports them.
+6. Each schema branch must constrain a real JSON type or supported union. An
+   empty schema from `z.unknown()` is not a strict schema.
+7. Open-ended records using `propertyNames` or schema-valued
+   `additionalProperties` are outside the safe strict subset. Prefer explicit
+   known keys.
+
+## Unions and optional fields
+
+A Zod discriminated union commonly emits a root `oneOf`; a plain union commonly
+emits root `anyOf`. Neither can be sent unchanged as function parameters.
+Redesign it as one root object whose branch-specific fields are nullable:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "kind": { "type": "string", "enum": ["text", "count"] },
+    "text": { "type": ["string", "null"] },
+    "count": { "type": ["number", "null"] }
+  },
+  "required": ["kind", "text", "count"],
+  "additionalProperties": false
+}
+```
+
+After generation, select the original branch from its discriminator, remove
+only the nullable padding for fields optional in that branch, and validate with
+the original Zod schema. Restoration must recurse through the selected branch;
+walking the union wrapper alone loses its property rules.
+
+For an optional `const`, use a real union:
+
+```json
+{ "anyOf": [{ "type": "string", "const": "fixed" }, { "type": "null" }] }
+```
+
+Adding `null` to a separate enum does not make a non-null `const` reachable.
+
+## Open records and arbitrary JSON
+
+When the application truly needs an open record or `unknown` value, use an
+explicit reversible wire representation rather than pretending it is strict:
+
+```json
+{
+  "type": "string",
+  "description": "A JSON object encoded as a string."
+}
+```
+
+Parse the generated string as JSON, require the intended value kind, then run
+the original application validator before execution. For arbitrary JSON, say
+"A JSON value encoded as a string" and accept any successfully parsed JSON
+kind. A parse failure remains invalid input; never execute the unparsed string
+as though it satisfied the original schema.
+
+Wire normalization may broaden what the model can generate, but it never
+broadens what the action may execute. Application validation is the security
+and correctness boundary.
+
+## Failure handling
+
+An upstream 400 with code `invalid_function_parameters` and a parameter path
+under `tools[n].parameters` identifies a caller-owned tool schema. Return the
+safe app error `invalid_function_parameters`, do not retain the private schema
+detail, and do not transition subscription health to
+`protocol_update_required`.
+
+An upstream response-format rejection with code `invalid_json_schema` is also
+caller-owned. It produces the bounded fingerprint
+`protocol:codex_400_invalid_json_schema` with no subscription-health change.
+Other parseable machine codes or types use the same sanitized, 32-character
+`protocol:codex_400_<token>` form. Upstream messages and parameter paths are
+not exposed. If the `400` body is malformed or contains no usable machine
+code/type, the transport cannot assign ownership and retains the conservative
+`protocol:unexpected_http_status_400` protocol-health fallback.
+
+## Official provenance
+
+Rules reconfirmed 2026-08-10:
+
+- https://developers.openai.com/api/docs/guides/structured-outputs
+- https://developers.openai.com/api/docs/guides/function-calling
+- https://developers.openai.com/cookbook/examples/codex/build_code_review_with_codex_sdk#codex-structured-outputs
+- https://github.com/openai/codex (reviewed tag and commit are recorded in
+  `module-contract.md`)
+
+External links are provenance and update checks; the working rules are included
+above so the installed skill remains usable on its own.

package/templates/tanstack-start/src/openai-subscription.ts

@@ -0,0 +1,11 @@
+import { openaiSubscriptionModule, type OpenAISubscriptionFetcher } from "@raybase/openai-subscription";
+import type { RaybaseEnv } from "@raybase/core/worker";
+
+export const openaiSubscription = openaiSubscriptionModule<RaybaseEnv & { CODEX_EGRESS: OpenAISubscriptionFetcher }>({
+  credentialMode: "user",
+  background: { strategy: "disabled" },
+  applicationScope: "raybase-app",
+  codexEgress: import.meta.env.DEV
+    ? { strategy: "local-relay" }
+    : { strategy: "cloudflare-vpc", binding: "CODEX_EGRESS" }
+});