Universal.Operative.Sdk.Codex 1.0.1

Universal.Operative.Sdk.Codex

Version 1.0.1 adds Options.AlwaysOnTools for consumer core tools such as messaging, file delivery and review. These tools are exposed on the first call, included in code-mode execution, and inherited by child agents. Keep optional specialties in DeferredTools; duplicate names across either list and built-ins are rejected. Codex refreshes its tool annotations before each model invocation, so persisted annotations cannot hide current tools after restoring or resetting context.

An independently registered Codex-compatible toolset for disposable local infrastructure. Register a fresh CodexToolSet per operative and dispose it when the session ends:

await using var tools = CodexToolSet.Create(new()
{
    WorkingDirectory = workspace,
    StorageDirectory = stateDirectory,
});
var operative = new EngineBuilder()
    .WithModel(model)
    .UseCodexToolSet(tools)
    .BuildOperative(conversation);

UseCodexToolSet replaces the builder's existing tools, tool packs, and catalog activation policy. The caller owns the toolset. The tools use the SDK's common ITool contract; the subagent execution path depends on Sdk.Discrete. Children inherit their direct parent's model, transformer stack (including compaction), dispatch hooks, and execution limits by default. Configure those policies before calling UseCodexToolSet, which snapshots the configuration. Each child gets fresh builder collections and its own Codex runtime wrappers, conversation, and process registry; the coordinator and discussion board are shared. Configured models, transformers, and hooks are shared policy instances, so custom stateful policies must support concurrent use or be freshly constructed through Options.AgentFactory.

Options.AgentFactory remains an explicit replacement for inheritance. Return a fresh builder to customize a child's model, compaction threshold, summarization model, or other engine policies. For example, AgentFactory = request => EngineBuilder.FromDefaults(SelectModel(request), summaryModel) uses the standard SDK compaction stack. To inherit that stack without a custom factory, construct the parent with EngineBuilder.FromDefaults(model) before attaching the toolset. A plain parent builder still has no automatic compaction to inherit. Closed agents retain their compacted conversation and their own saved configuration when resumed.

The standard compactor preserves newly arrived user input as actionable text even when MessagesToKeep is zero, so resuming after compaction does not turn a new task into background history. Forced-threshold tests cover both agent protocols, summary continuity after close/resume, and factory customization; an opt-in OpenAI test exercises inherited compaction at a 1,000-token threshold.

The compatibility reference is openai/codex revision 14a477ea89712071944244022e8a10142845456e. Upstream tools are feature gated; this package combines the locally implementable families into one configurable surface.

Version 1.0.0 requires Universal.Operative.Sdk 6.1.3 or later and Universal.Operative.Sdk.Discrete 3.1.1 or later. OpenAI consumers must use Universal.Operative.Sdk.Discrete.OpenAI 3.2.0 or later for the native namespace/custom-input transport and optional-argument fixes; the provider adapter remains a separate installation.

Release builds create NuGet packages in each project's normal bin/Release directory. Publish the kernel first, then Discrete, then the OpenAI adapter and Codex, then Codex.V8. Both new Codex packages are version 1.0.0 with release notes Initial release..

The universal tool definition retains its dispatch name and portable JSON schema. Native OpenAI namespace and custom-format hints are stored in Extensions["openai"], exposed by the OpenAI adapter's GetOpenAI() tool-definition view. The Codex package emits this metadata without depending on that adapter.

Discrete OpenAI-compatible function transports (OpenAI Chat Completions, ChatGPT, DeepSeek, MoonshotAI, xAI/Grok, LMStudio Chat/Responses, DashScope Chat/Responses, MiMo Chat, and Foundry) share stable provider-safe aliases and restore dispatch names on streamed calls. Native string history replays as { "input": "raw text" }; tools accept that schema as their portable fallback. Native grammar enforcement remains a provider capability. Backend restrictions, such as MiMo's unsupported forced tool choice, still apply. This compatibility coverage does not claim native-format support in Anthropic, Gemini, Bedrock, or realtime adapters.

Use the corresponding adapter release for this fallback: ChatGPT 3.1.1, DeepSeek 3.0.3, MoonshotAI 3.0.1, xAI 3.0.2, Grok 3.0.2, LMStudio 3.0.1, DashScope 3.0.1, MiMo 1.0.1, or Foundry 1.1.1.

Names in each family inherit the namespace shown on its first entry. Options can disable families and customize the V2 namespace. NamespaceOverrides renames other built-in namespaces and applies to children and code-mode metadata. GPT-6.1 Sol reserves some upstream names for configured hosted tools and rejects local replacements under those names. For local tools, use AgentV2Namespace = "operative_agents" and map history, notes, memories, skills, multi_agent_v1, and clock to application-owned names such as operative_history. Storage uses local files; it does not require a server.

Optional tools are registered when their backends are supplied:

Universal.Operative.Sdk.Codex.V8 supplies an optional embedded ClearScript/V8 code-mode backend. Core tools carry no V8 native dependency. No Node.js installation is required. The V8 project references native packages for Windows, Linux, and macOS on x64 and ARM64; platform-specific runtime validation is still required.

Commands execute directly on the host. There are no sandbox or approval tools. The default executor uses redirected pipes; real PTY execution requires ICodexTerminal. The consumer owns that terminal backend; toolset disposal interrupts the sessions it registered without disposing the shared provider.

Goals and token budgets belong to individual agent runtimes. A root goal does not cap the sum of child usage; consumers requiring a total spend limit must enforce it across model invocations. Agents that reach their model iteration limit report an errored status rather than a completed result.

The OpenAI Responses adapter advertises raw-input custom tools and tool namespaces. Raw tools also accept the {"input":"raw source"} function fallback. Adapters without native namespaces need their own name mapping where the provider disallows dotted function names; this package does not imply transport compatibility with every provider. Context remaining is an estimate. Local history, memory, skills, discussion, and goals replace hosted services with session-local behavior.

Local skills use complete skill://executor/local/... package/resource identifiers. Paginated reads retain their original snapshot if a file changes; omit the cursor to refresh. Discussion pages use opaque offset cursors; keep the filters and sort unchanged when continuing a page. Closing an agent terminates its processes and JavaScript cells. Resuming retains its conversation and queued input and constructs a fresh execution runtime. Agent tools reject interrupting or closing the caller itself or its ancestors.

Hosted permission/environment setup, plugin installation, Apps messaging infrastructure, and internal test synchronization tools are excluded. Web search, image generation, MCP connections, and user interface presentation remain consumer-provided services.

The deterministic suite covers the complete enabled tool inventory, replacement registration, process sessions, patches, both agent protocols, storage, code mode, BYO services, context/goals, native Responses transport, and teardown races. Opt-in LiveOperativeTests use GPT-6.1 Sol through the OpenAI Responses adapter for a solo coding goal, an implementer plus independent critic with a shared board, and V1 close/resume with structured follow-up input. Set OPERATIVE_CODEX_LIVE=1 and OPENAI_API_KEY (or the existing OpenAI test user secrets); optionally set OPERATIVE_CODEX_MODEL. Per-request usage, tool calls, unfinished dispatches, goal state, and artifacts are retained under the temporary operative-codex-live directory. These workload measurements are individual observations rather than a statistical benchmark. Runtime validation was performed on Windows; the boundaries above apply.