Add a lightweight structured LLM request side channel

[shiny-code-bot]

Objective

Add a thread-free stateless structured inference primitive to Codex Lab core and expose it primarily through the app server so application clients can make strict JSON-schema requests without entering the coding-agent thread/turn lifecycle.

An optional CLI may later wrap the same primitive, but the app-server contract is the primary product surface.

Finish Line

An official Codex Lab release exposes structuredRequest/start and structuredRequest/cancel over app server, backed by one stateless core request path with explicit model, developer instructions, user input, output schema, timeout/cancellation, served-model metadata, and token usage.

The request uses existing Codex Lab auth, account pooling, provider routing, model catalogs, and aliases while loading no tools, skills, MCP context, repository instructions, conversation history, or resumable rollout state.

Current Status

State: implementation is included in the published Lab.6 source; installed RPC behavior and downstream Mediaforce acceptance still need qualification.

• PR Add stateless structured app-server requests #719 merged into main on August 17, 2026 at merge commit 9e3eeb23e39d63e2e8c4328d515ce33d5c5213be from head bd8acdae36225e3688c919ce5d9fa6434e8fc0ee.
• The merged implementation adds the dedicated stateless core model-request path and experimental app-server v2 methods structuredRequest/start and structuredRequest/cancel.
• The request path preserves execution-account leases, account-aware model catalogs, auth/provider/model routing, strict schema output, usage, served-model metadata, timeout, and cancellation while excluding tools, skills, MCP, repository/session context, and rollout creation.
• Validation passed before merge: cargo check -p codex-app-server, focused core/app-server tests, all 313 app-server-protocol tests, and 17 GitHub checks. Full-history review/comment coverage was clear immediately before merge.
• JetBrains inspection remained inconclusive because IntelliJ could not produce a current stable result; no actionable code finding was reported.
• Mediaforce issue cbusillo/mediaforce#176 remains blocked on a released artifact containing this merge, not merely source availability on main.

Next action: verify the existing installed Lab.6 structured-request RPC in an isolated test home, then let Mediaforce run its model-tier, failure-matrix and efficiency acceptance before switching production traffic. The published source 9148747 contains structuredRequest/start and /cancel. Do not rebuild or republish Lab.6 merely to resume this acceptance.

Last verified: September 11, 2026 for published/candidate source presence. Historical pre-merge checks above are not a new installed-artifact acceptance.

September 11 source verification: structuredRequest/start and /cancel, StructuredRequestProcessor and the stateless core request path are present in the preserved #902 candidate e967324. #778's hybrid plan will reuse this existing primitive for suitable non-code work; it does not require a new stateless request implementation or select it as the first convergence-payback extraction. The 275-line core implementation still uses engine client/account infrastructure. Published Lab.6 source 9148747 also contains both RPC registrations. These source reads are not installed-artifact/Mediaforce acceptance and do not by themselves close this issue.

Scope

• Maintain one stateless core request API with a fresh model client/session per call.
• Accept an explicit model, developer instructions, user input, strict JSON Schema, optional output-token limit, and optional timeout.
• Return validated JSON plus served model, response id, usage, and duration metadata.
• Expose the primitive through dedicated app-server v2 start/cancel methods without requiring a thread id.
• Preserve account-aware auth, provider/model routing, aliases, rate-limit behavior, and cancellation semantics.
• Prove that tools, skills, MCP, repository instructions, history, and rollout persistence are absent.
• Keep a CLI wrapper optional and downstream of the shared core/app-server contract.
• Keep prompts and failures privacy-safe; do not echo private request content in routine diagnostics.

Acceptance Criteria

• Sol, Terra, and Luna each complete strict schema-constrained requests through the released app-server RPC.
• Request-shape tests prove the agent prompt, tool catalog, skills, MCP, repository rules, and conversation history are absent.
• Requests use the active execution-account lease and account-aware model manager.
• Invalid model/provider, timeout, cancellation, transport failure, malformed schema, tool-call output, missing output, and invalid JSON produce deterministic bounded failures.
• Concurrent request ids are isolated by connection and exact caller ids can be cancelled.
• Responses report the served model, provider response id, usage when supplied, and elapsed milliseconds.
• Requests create no resumable thread, rollout, or history artifact.
• Stable and experimental protocol fixtures remain generated and all protocol tests pass.
• A repeatable Mediaforce comparison demonstrates materially lower prompt-token and/or latency overhead than the current warm exec --ephemeral --output-schema route before Mediaforce switches production traffic.

Relationships

• Native roadmap parent: Launch Codex Lab and establish post-cutover roadmap #498.
• Blocks the waiting Mediaforce adoption issue cbusillo/mediaforce#176.
• Consumer evidence and completed advisor foundation: cbusillo/mediaforce#163 and cbusillo/mediaforce#176.
• Related evaluation and request-observability work: Run paired Codex Lab versus Every Code product evaluation #520.
• Related provider selection and usage-accounting context: Provider-agnostic worker decision spike #2.
• lab.5 release plan Publish and prove Codex Lab lab.5 #624 is not blocked by this issue unless maintainers explicitly add it to that release scope.
• Historical MVP parent Codex Lab MVP dogfood plan #28 is complete and no longer owns this issue.

Decisions

• App server is the primary application integration surface; a CLI is optional and must be a thin wrapper over the same core primitive.
• Use dedicated structuredRequest/* methods rather than a lightweight flag on turn/start, so non-agent behavior cannot silently inherit thread history, tools, skills, or MCP later.
• Reuse Codex Lab's execution-account, auth, provider, model-catalog, alias, usage, and cancellation machinery rather than building a second provider client.
• Start returns the final result synchronously while a concurrent cancel request targets a client-generated id scoped to its connection.
• The stateless request uses ephemeral account-lease persistence and never creates a resumable thread or rollout.
• No long-lived feature flag and no CLI-first implementation.

Open Questions

• Should optional metadata be JSONL events, a single response envelope, or a separate file descriptor/output file?
• Should image input be included initially or remain on exec --image --output-schema until a concrete non-agent consumer requires it?

[shiny-code-app]

Backlog reconciliation — 2026-09-26

Owner decision, 2026-09-26: retire the structuredRequest/* side channel. It merged on the old Lab main (#719), but it is absent from the fresh-start main and is not one of the needs in DIRECTION.md. Its consumer cbusillo/mediaforce#176 has been told to use stock codex exec --ephemeral --output-schema, or a sidecar if the overhead matters.