OpenAI Agents API Runtime Adapter

[BryanHarrisScripts]

Developer brief

Goal

Evaluate OpenAI's new Agents API as an optional cloud Agent runtime behind PlotPickle's existing Agent compute/provider boundaries.

This is not a migration of PlotPickle Agents to OpenAI, not a replacement for the current embedded runtime, not a new Agent registry, and not a move of deterministic PlotPickle authority into a model harness.

Architectural rule:

PlotPickle owns the Agent, job, story/project context, authority, deterministic evaluation, provider policy and UX. The Agent runtime is replaceable infrastructure.

Official reference: https://openai.com/index/introducing-the-agents-api/

OpenAI announced the Agents API on September 10, 2026 as a public beta. The current API exposes the Codex harness as a managed service with long-session context management, tool search/programmatic tool calling, MCP/custom/built-in tools, subagents, and selectable execution environments. OpenAI currently states that developers may use an OpenAI-hosted sandbox, their own infrastructure, or supported environment providers, and that there is no separate Agents API fee beyond consumed model/tool usage.

Because this is public beta, beta-specific request/response shapes must remain isolated inside an adapter and must not leak into core PlotPickle Agent, story, LEARN, STORY or BUZZ contracts.

Current PlotPickle authority to preserve

The repository already has the right conceptual boundary:

• build/agent-compute-gateway.ts — Human-facing PlotPickle Agent compute assignment/readiness;
• build/agent-compute-store.ts — protected local assignment persistence;
• build/writing-assistant-gateway.ts — current execution route;
• build/mastra-agent-runtime.ts — current embedded PlotPickle Agent roles;
• lib/agents/agent-profiles — canonical Agent profiles/ownership;
• modules/creative-room/curriculum-guide.ts and Sage modules — existing bounded embedded Agent contract;
• Local Story Mode / Cloud Story Mode — provider/model setup;
• Settings / Agents — global default plus per-Agent compute overrides;
• BUZZ-managed Agent runtime/provider ownership — separate and outside PlotPickle Agent compute.

The existing #1847/#1848/#1849 architecture already establishes that provider/model setup belongs to Story Mode and Settings / Agents assigns configured compute to embedded PlotPickle Agents. It also forbids silent fallback when a pinned provider is unavailable.

This issue extends that architecture rather than creating another one.

Critical distinction: provider is not runtime

Do not overload the existing openai provider value to mean "use Agents API."

• Provider/model answers what model compute is being used.
• Agent runtime/harness answers what execution harness coordinates context, tools, sessions and subagents.

Conceptually:

PlotPickle Agent Profile
 -> PlotPickle Agent Contract / Job
 -> Agent Compute Resolver
      -> provider/model: local / ollama / openai / minimax / gemini
      -> runtime: native/direct / openai-agents / future adapters

The first implementation may restrict openai-agents to a ready OpenAI route, but that is a capability rule, not part of Agent identity/business logic.

Existing assignments continue to mean the current native/direct path unless the Human explicitly selects another proven runtime.

Why evaluate the Agents API

Test whether the managed harness removes infrastructure PlotPickle would otherwise need to build/maintain while preserving PlotPickle authority.

Highest-value capabilities:

1. Long-running sessions and context compaction — potentially useful for lengthy story work without making remote runtime state story canon.
2. Tool search/programmatic tool calling — potentially avoids loading PlotPickle's full capability catalog into every turn.
3. MCP support — potentially exposes narrowly approved PlotPickle-owned tools through a standard boundary.
4. Subagents — potentially useful for independent review lenses such as structure, continuity and reader response.
5. Managed execution environments — potentially useful for selected cloud tasks while remaining opt-in and isolated.

Locked authority model

PlotPickle remains authoritative for:

• Agent identity/profile and role/job definition;
• Human-selected provider/runtime policy;
• PPF/project/canon truth;
• Context Engine selection and knowledge boundaries;
• capability grants;
• deterministic rules, validation and scoring;
• LEARN curriculum authority;
• STORY mechanical authority;
• generated-vs-accepted provenance;
• Human creative authority;
• UX, cloud disclosure, cost and availability policy;
• success/failure evidence.

The Agents API may execute, reason, compact context, discover explicitly permitted tools and coordinate bounded subagents. It may not redefine those PlotPickle authorities.

Session and canon boundary

An Agents API session is runtime state, not PPF canon.

If persistent session identifiers are used:

• store only the minimum mapping needed to resume the Agent;
• keep it in protected local runtime/application state, not story canon;
• scope it so one project/Agent session cannot inherit another project's context;
• provide deterministic reset/recreate semantics;
• do not serialize runtime internals into PPF;
• remote session memory is never proof that a story fact was accepted;
• only existing PlotPickle transitions may admit generated material into durable story/project state.

Before a live cloud call, preserve PlotPickle's existing disclosure/consent boundary for project material leaving the computer. Send only the bounded context needed for the job.

Retention/deletion semantics must be verified against current beta documentation during implementation rather than assumed.

Capability and safety boundary

Runtime capability does not equal PlotPickle permission.

• Runtime tools must come from an explicit PlotPickle-approved capability set.
• A tool is not exposed merely because the runtime supports MCP/tool search.
• Initial live phases are read-oriented and non-mutating.
• Remote execution receives only explicitly selected context/resources.
• Subagents inherit a subset of the parent PlotPickle capability scope, never more.
• Runtime/provider failure must be visible and must not silently change compute routes.

Observability contract

Make runtime use observable without storing hidden model reasoning.

Capture structured operational evidence such as:

• PlotPickle Agent/profile ID;
• resolved provider/model;
• resolved runtime (native/direct vs openai-agents);
• session create/resume/reset state;
• permitted tools used;
• subagent count/role labels;
• elapsed time;
• usage/cost fields when returned;
• environment type;
• final success/failure/cancelled state;
• deterministic PlotPickle evaluation result where applicable.

Reference vertical slice

Use one existing embedded PlotPickle Agent contract for the first live proof. Prefer the current Sage/Curriculum Guide path because it is bounded, read-oriented and already tested.

This use of Sage is a transport/runtime proof only. It must not implement or alter #1918 Phase 8 journey awareness, Phase 9 Agent lenses, curriculum authority, progression logic or LEARN UI.

First live proof:

Existing Sage request
 -> existing bounded curriculum/project context
 -> PlotPickle Agent compute resolver
 -> OpenAI Agents runtime adapter
 -> Agents API session
 -> final Agent answer
 -> existing PlotPickle response contract

The caller should not need to know the Agents API was used except through explicit runtime/status diagnostics.

A later bounded subagent proof may use a DraftLens/Reader Simulation style review because that is where parallel specialist contexts may be valuable. Do not make that a dependency of the first single-Agent proof.

Progressive implementation plan

Phase 0 — Contract and beta isolation

No live Agents API call.

• create the canonical developer brief;
• lock provider != runtime as an invariant;
• define a runtime-neutral execution request/result contract;
• define runtime capabilities for sessions/tools/MCP/subagents/environment support;
• define native/direct as current default runtime;
• define openai-agents as optional/not-ready until proven;
• keep OpenAI beta schemas inside the adapter;
• define session scope/reset/local persistence;
• define outbound story-data/privacy boundary;
• define no-silent-fallback behavior;
• add focused contract tests.

Exit: runtime seam exists with zero behavior change.

Phase 1 — Adapter skeleton + mocked contract

• implement the adapter behind the Phase 0 seam;
• keep it unreachable from normal Settings/UI;
• use mocked fixtures only;
• map PlotPickle Agent request to Agents API request without leaking beta types;
• map final result/error back to the existing PlotPickle Agent result contract;
• prove existing direct/local/Ollama/OpenAI/MiniMax/Gemini behavior is unchanged;
• prove unsupported provider/runtime combinations fail clearly;
• prove no fallback to another route.

Exit: adapter shape is testable with zero paid calls and zero user-facing behavior change.

Phase 2 — Opt-in live single-Agent transport probe

• add a developer-only/explicit opt-in live path;
• use one existing Sage/Curriculum Guide request;
• use the smallest useful bounded context;
• use a ready OpenAI route only;
• start with the simplest safe supported environment and no unrelated local resources;
• return through the existing Sage/Agent response contract;
• record operational evidence and usage;
• no new UI, no PPF mutation, no tool calling, no subagents.

Exit: one existing PlotPickle Agent can run through Agents API without product authority changing.

Phase 3 — Session durability/context proof

• create/resume the same bounded Agent session across multiple turns;
• prove project/Agent scoping prevents cross-project context leakage;
• exercise long-session/compaction behavior where practical;
• prove PlotPickle can reset the runtime session deterministically;
• prove story/canon truth still comes only from PlotPickle state;
• compare observed context/token behavior with native/direct.

Exit: durable runtime context is useful without becoming a second memory/canon system.

Phase 4 — Tool search/MCP with one read-only capability

• expose exactly one safe read-only PlotPickle-owned capability;
• prefer a deterministic query capability;
• test tool discovery/tool search instead of sending an unrestricted tool catalog;
• prove an ungranted tool cannot be used;
• prove tool output is bounded before re-entry into Agent context;
• prove failure does not widen permissions.

Exit: tool discovery reduces context/tool overhead without weakening PlotPickle permissions.

Phase 5 — Bounded subagent proof

Only after Phases 2–4 are clean.

• select one review workload that genuinely benefits from independent specialist analysis;
• recommended shape: parent review Agent delegates bounded structure/continuity/reader-response perspectives;
• tightly cap concurrent subagents;
• give each subagent a minimal context and strict role/output contract;
• subagents cannot gain broader capabilities than the parent;
• parent may synthesize evidence, but deterministic PlotPickle evaluation remains outside the runtime;
• compare latency, usage/cost and output value with existing native/sequential behavior.

Exit: measured evidence shows whether subagent orchestration is worth product adoption.

Phase 6 — Reliability, cancellation, cost and environment policy

• define timeout/cancellation semantics;
• handle network/runtime failure;
• handle beta/API incompatibility fail-closed;
• ensure retry/idempotency cannot duplicate side effects;
• surface provider/runtime unavailable states truthfully;
• capture usage/cost evidence where available;
• define per-session limits for subagents/tool calls/runtime duration;
• compare hosted vs PlotPickle-owned environment only if a concrete need appears.

Exit: adapter has acceptable production failure boundaries or the experiment is rejected.

Phase 7 — Human-facing runtime selection, only if spike passes

Do not expose Settings/UI merely because an API call works.

If Phases 0–6 prove value:

• extend PlotPickle Agent compute presentation to distinguish Provider from Runtime;
• preserve native/direct as compatibility default;
• expose OpenAI Agents only when OpenAI and the adapter are ready;
• permit default/per-Agent runtime override only where supported;
• make cloud/hosted-runtime status visible before use;
• preserve Skin V1 keyboard behavior;
• keep BUZZ-managed Agents outside this configuration;
• selecting a runtime must not silently change provider/model or paid-route authority.

Exit: Human can deliberately opt an eligible PlotPickle Agent into the runtime without confusing provider, model and harness.

Evaluation criteria

A working API call alone is not success. Evaluate:

• custom orchestration/context code avoided;
• long-session continuity;
• context/token efficiency from compaction/tool search;
• latency and cost;
• reliability/recovery;
• usefulness of subagent fan-out;
• preservation of local-first/provider-independent architecture;
• observability and capability isolation;
• maintenance complexity introduced by public-beta churn.

Acceptance criteria

• Canonical developer brief exists before implementation code.
• Provider/model remains distinct from Agent runtime.
• Existing behavior remains native/direct by default.
• Agents API is isolated behind one runtime adapter.
• OpenAI beta schemas do not leak into canonical Agent/PPF/LEARN/STORY/BUZZ contracts.
• Existing local/Ollama/OpenAI direct/MiniMax/Gemini routes remain compatible.
• BUZZ-managed Agents remain outside PlotPickle runtime configuration.
• Live calls are explicit opt-in and use bounded disclosed context.
• Remote session state never becomes PPF/canon authority.
• Sessions are scoped/resettable with no cross-project/Agent leakage.
• Tools are allow-listed by PlotPickle capability.
• Subagents cannot exceed parent capabilities.
• Runtime/provider failures never silently change compute route.
• Structured observability reports selected runtime/provider/model/session/tool/subagent/usage/final state without storing hidden reasoning.
• Deterministic PlotPickle evaluation and canon admission remain outside the Agent runtime.
• Human-facing runtime controls appear only after the spike proves value/readiness.
• Focused contract/security tests pass.
• Existing Cloud Story Mode: capability-driven providers and task routing #1847/PlotPickle Agents: default compute plus per-agent overrides #1848/Skin V1 Settings: dashboard-matched typography and full keyboard directory #1849 regressions remain green.
• Exact-head required GitHub gates are green before implementation phases merge.

Non-goals

• migrating every PlotPickle Agent to Agents API;
• replacing Mastra immediately;
• removing local/Ollama execution;
• removing MiniMax or Gemini support;
• making OpenAI the only Agent provider;
• changing BUZZ-managed Agent ownership;
• implementing LEARN: 24-course guided journey, open exploration, integrity harness and Agent lenses #1918 Phase 8/9 inside this spike;
• changing Sage curriculum/learning authority;
• changing PPF/canon authority;
• changing STORY deterministic game authority;
• broad UI work before runtime proof;
• automatic compute fallback;
• storing remote Agent memory as canonical story truth;
• treating public-beta availability as a commitment to production adoption.

Sequencing / roadmap rule

Creating this issue does not interrupt the current PlotPickle roadmap.

Treat it as a bounded architecture spike in the backlog until the Human explicitly schedules it.

When scheduled, build and merge one phase at a time:

Phase 0 -> Phase 1 -> Phase 2 -> Phase 3 -> Phase 4 -> Phase 5 -> Phase 6 -> optional Phase 7

Stop after any phase if the adapter adds more complexity than it removes or weakens PlotPickle's local-first/Human-authority boundaries.

Do not bundle this into #1918, STORY #1675, BUZZ, or unrelated Settings work.

Canonical developer brief

Commit and maintain:

docs/developer-briefs/<issue>-openai-agents-api-runtime-adapter.md

The brief must preserve the provider-vs-runtime distinction, adapter isolation, bounded Sage transport proof, session/canon boundary, capability restrictions, subagent inheritance, observability contract, phased plan and no-roadmap-interruption rule.

[BryanHarrisScripts]

Canonical developer brief prepared at docs/developer-briefs/1996-openai-agents-api-runtime-adapter.md on branch issue-1996-openai-agents-runtime-brief (commit 536e6281986db1a5a7d303d2e2aae440ea072f52). Main correctly rejected the direct docs write because required status checks are enforced, so no branch protection was bypassed. No implementation has started; #1996 remains a backlog architecture spike until the Human explicitly schedules Phase 0.