praxis-agent 0.53.1 → 0.55.0

package/README.md

@@ -13,7 +13,8 @@ Praxis is a local-first, single-user general agent for the command line.
 
 It provides an interactive or headless agent loop, local tools, permissions,
 sessions, skills, hooks, MCP, plugins, background agents, and provider-neutral
-Anthropic/OpenAI-compatible model access. Praxis deliberately excludes
+Anthropic, OpenAI-compatible Chat Completions, and OpenAI Responses model
+access. Praxis deliberately excludes
 accounts, organizations, billing, managed enterprise policy, remote control,
 IDE surfaces, and telemetry control planes.
 
@@ -27,9 +28,9 @@ sessions, configuration, or compatibility directories.
 - macOS or Linux
 - Node.js 24 or newer
 - [`ripgrep`](https://github.com/BurntSushi/ripgrep) (`rg`) for the Grep tool
-- an API key and model ID for an Anthropic or OpenAI-compatible provider (the
-  stable setup), or the explicitly enabled experimental ChatGPT-backed Codex
-  subscription integration
+- an API key and model ID for an Anthropic, OpenAI-compatible, or OpenAI
+  Responses provider (the stable setup), or the explicitly enabled experimental
+  ChatGPT-backed Codex subscription integration
 
 Praxis does not use Claude subscription authentication. Claude-shaped message,
 tool, and CLI protocol forms remain supported where they are part of the
@@ -63,6 +64,20 @@ cd /path/to/project
 praxis
 ```
 
+To use OpenAI's Responses API with an explicit API-key provider:
+
+```sh
+export PRAXIS_PROVIDER="openai-responses"
+export OPENAI_API_KEY="your-api-key"
+export PRAXIS_MODEL="your-responses-model-id"
+
+cd /path/to/project
+praxis
+```
+
+The `openai` provider remains OpenAI-compatible Chat Completions. Provider
+protocols are selected explicitly; model IDs never switch protocols implicitly.
+
 Praxis also has an experimental `openai-codex` provider for ChatGPT-backed
 Codex subscriptions. It is separate from OpenAI API-key access, requires
 `experimental.codexSubscription: true`, and stores OAuth credentials in the
@@ -238,7 +253,16 @@ troubleshooting. Run `praxis --help` for the authoritative command surface.
   recovery for malformed streamed tool arguments without tool execution or
   lost resumability, one default-on bounded Anthropic non-streaming replay for
   eligible stream/idle failures without exposing failed-attempt output, and
-  token-only/no-API-dollar accounting for subscription runs.
+  token-only/no-API-dollar accounting for subscription runs. Each main user
+  Turn and independent auxiliary Agent, Workflow, Team, recovery, or memory
+  Turn receives its own provider client. Session-memory requests reuse a
+  completion-scoped client but restart routing from primary for each request;
+  auto-mode critic and eval-judge requests remain independently constructed
+  one-shot clients. Failed attempts stay buffered, and the first successful
+  route, whether primary or fallback, stays sticky only through that logical
+  Turn's tool continuations; incompatible routes fail closed, and the next
+  independent Turn starts from primary. Recovery may persist only an optional
+  selected model, never provider route or wire state.
 - **Transactional self-update** — `praxis update` verifies the package before
   installing it, rejects concurrent updates, and can roll back after an
   interruption or crash.

package/dist/application/native-sidechain-transcript.d.ts

@@ -7,6 +7,8 @@ export interface NativeSidechainMetadata {
     readonly spawnDepth: number;
     readonly cwd: string;
     readonly promptId: string;
+    /** Provider-neutral selected model identifier for recovery. */
+    readonly model?: string;
     readonly name?: string;
     readonly permissionMode?: NativeSidechainPermissionMode;
     readonly isolation?: 'worktree';

package/dist/application/native-sidechain-transcript.js

@@ -19,6 +19,7 @@ const requiredKeys = [
     'promptId',
 ];
 const optionalKeys = [
+    'model',
     'name',
     'permissionMode',
     'isolation',
@@ -74,6 +75,8 @@ function validateMetadata(value) {
         throw new Error('native sidechain metadata cwd is invalid');
     if (!nonBlank(record.promptId))
         throw new Error('native sidechain metadata promptId is invalid');
+    if (record.model !== undefined && !nonBlank(record.model))
+        throw new Error('native sidechain metadata model is invalid');
     if (record.name !== undefined && !nonBlank(record.name))
         throw new Error('native sidechain metadata name is invalid');
     if (record.permissionMode !== undefined &&

package/dist/application/session-service.d.ts

@@ -70,6 +70,8 @@ export interface ClaudeSessionServiceOptions {
     enableWorkflows?: boolean;
     providerForModel?: (model: string) => ModelProvider;
     providerForMainModel?: (model: string) => ModelProvider;
+    /** Creates one fresh main-turn provider per outer user turn; never used for auxiliary model calls. */
+    providerForTurn?: (model?: string) => ModelProvider;
     /** Creates a provider adapter dedicated to Session memory requests so
      *  adapter-local cache and retry state are not shared with the foreground. */
     sessionMemoryProviderFactory?: () => ModelProvider;

package/dist/application/session-service.js

@@ -745,7 +745,16 @@ export class ClaudeSessionService {
             ? (options.extensions?.agent(options.agent) ?? null)
             : null;
         if (configuredAgent && options.provider) {
-            this.activeProvider = this.providerForAgent(configuredAgent);
+            const selectedModel = !options.explicitModel &&
+                configuredAgent.model &&
+                configuredAgent.model !== 'inherit'
+                ? configuredAgent.model
+                : undefined;
+            const selectProvider = options.providerForMainModel ?? options.providerForModel;
+            this.activeProvider =
+                selectedModel !== undefined && selectProvider
+                    ? selectProvider(selectedModel)
+                    : this.options.provider;
         }
     }
     nextScheduledPrompt(signal) {
@@ -1108,6 +1117,9 @@ export class ClaudeSessionService {
                 ...(this.options.providerForModel
                     ? { providerForModel: this.options.providerForModel }
                     : {}),
+                ...(this.options.providerForTurn
+                    ? { providerForTurn: this.options.providerForTurn }
+                    : {}),
                 baseTools: wrappedBase,
                 ...(this.options.deferMcpTools === undefined
                     ? {}
@@ -2849,6 +2861,9 @@ export class ClaudeSessionService {
                         ...(this.options.providerForModel
                             ? { providerForModel: this.options.providerForModel }
                             : {}),
+                        ...(this.options.providerForTurn
+                            ? { providerForTurn: this.options.providerForTurn }
+                            : {}),
                         baseTools,
                         ...(this.options.deferMcpTools === undefined
                             ? {}
@@ -5043,6 +5058,12 @@ export class ClaudeSessionService {
     providerForAgent(agent) {
         const inherited = this.provider();
         const selectProvider = this.options.providerForMainModel ?? this.options.providerForModel;
+        const effectiveModel = !this.options.explicitModel && agent?.model && agent.model !== 'inherit'
+            ? agent.model
+            : inherited.model;
+        if (this.options.providerForTurn) {
+            return this.options.providerForTurn(effectiveModel);
+        }
         if (this.options.explicitModel ||
             !agent?.model ||
             agent.model === 'inherit' ||

package/dist/application/subagent-service.d.ts

@@ -76,6 +76,7 @@ export interface ClaudeSubagentExecutorOptions {
     maxCalls?: number;
     maxOutputBytes?: number;
     providerForModel?: (model: string) => ModelProvider;
+    providerForTurn?: (model?: string) => ModelProvider;
     toolNames?: readonly string[];
     backgroundTaskNotifications?: (waitForRunning: boolean) => Promise<string[]>;
     notificationDelivered?: (notification: {
@@ -117,6 +118,7 @@ export declare class ClaudeSubagentExecutor {
     sendBackgroundMessage(agentId: string, message: string, summary: string | undefined, toolUseId: string): string;
     stopAllBackgroundTasks(): readonly string[];
     private cwd;
+    private providerForTurn;
     private agentDefinition;
     private resolveAgentInput;
     registry(sessionId: string, depth: number, promptIdForCall: (callId: string) => string | null, parentAgentId?: string): ToolRegistry;

package/dist/application/subagent-service.js

@@ -586,6 +586,15 @@ export class ClaudeSubagentExecutor {
     cwd() {
         return this.options.cwdProvider?.() ?? this.options.cwd;
     }
+    providerForTurn(model) {
+        if (this.options.providerForTurn) {
+            return this.options.providerForTurn(model);
+        }
+        if (model !== undefined) {
+            return this.options.providerForModel?.(model) ?? this.options.provider;
+        }
+        return this.options.provider;
+    }
     agentDefinition(input) {
         return this.options.extensions?.agent(input.subagentType) ?? null;
     }
@@ -753,7 +762,9 @@ export class ClaudeSubagentExecutor {
             !this.options.extensions?.agent(input.subagentType)) {
             throw new Error(`Unknown Claude agent ${input.subagentType}`);
         }
-        if (input.model && !this.options.providerForModel) {
+        if (input.model &&
+            !this.options.providerForModel &&
+            !this.options.providerForTurn) {
             throw new Error('Agent model overrides are unavailable for this provider');
         }
         if (input.permissionMode &&
@@ -850,6 +861,7 @@ export class ClaudeSubagentExecutor {
                 ...(input.permissionMode
                     ? { permissionMode: input.permissionMode }
                     : {}),
+                ...(input.model ? { model: input.model } : {}),
                 ...(input.isolation ? { isolation: input.isolation } : {}),
                 ...(parentAgentId ? { parentAgentId } : {}),
                 ...(initialIsolation ? { worktreePath: initialIsolation.cwd } : {}),
@@ -863,9 +875,7 @@ export class ClaudeSubagentExecutor {
         catch (error) {
             return settleInitialSetupFailure(error, initialIsolation);
         }
-        const provider = input.model
-            ? (this.options.providerForModel?.(input.model) ?? this.options.provider)
-            : this.options.provider;
+        const provider = this.providerForTurn(input.model);
         const backgroundRun = this.createBackgroundAgentRun({
             input,
             parentCwd,
@@ -874,11 +884,14 @@ export class ClaudeSubagentExecutor {
             ...(initialIsolation ? { initialIsolation } : {}),
             createIsolation: () => this.createAgentWorktree(paths.praxisRoot, sessionId, agentId, parentCwd),
             execute: async (cwd, message, signal, continuation) => {
+                const turnProvider = continuation
+                    ? this.providerForTurn(input.model)
+                    : provider;
                 const run = (lease) => this.runSidechain({
                     ...lease,
                     sessionId,
                     input,
-                    provider,
+                    provider: turnProvider,
                     agentId,
                     spawnDepth,
                     promptId,
@@ -1346,13 +1359,12 @@ export class ClaudeSubagentExecutor {
             !this.options.extensions?.agent(options.agentType)) {
             throw new Error(`Unknown Claude agent ${options.agentType}`);
         }
-        if (options.model && !this.options.providerForModel) {
+        if (options.model &&
+            !this.options.providerForModel &&
+            !this.options.providerForTurn) {
             throw new Error('Workflow agent model overrides are unavailable for this provider');
         }
-        const provider = options.model
-            ? (this.options.providerForModel?.(options.model) ??
-                this.options.provider)
-            : this.options.provider;
+        const provider = this.providerForTurn(options.model);
         const input = {
             description: options.label ?? 'Workflow agent',
             prompt: options.prompt,
@@ -1395,6 +1407,7 @@ export class ClaudeSubagentExecutor {
                 spawnDepth: 1,
                 cwd: agentCwd,
                 promptId: options.promptId,
+                ...(input.model ? { model: input.model } : {}),
                 ...(options.isolation ? { isolation: options.isolation } : {}),
                 ...(isolation ? { worktreePath: isolation.cwd } : {}),
             });
@@ -1716,11 +1729,11 @@ export class ClaudeSubagentExecutor {
             prompt,
             subagentType: agentType,
             ...(name ? { name } : {}),
+            ...(metadata?.model ? { model: metadata.model } : {}),
             ...(permissionMode ? { permissionMode } : {}),
             ...(isolation ? { isolation } : {}),
             runInBackground: true,
         };
-        const provider = this.options.provider;
         const recoveredPromptId = metadata?.promptId ?? randomUUID();
         const backgroundRun = this.createBackgroundAgentRun({
             input,
@@ -1731,6 +1744,9 @@ export class ClaudeSubagentExecutor {
             ...(restoredIsolation ? { initialIsolation: restoredIsolation } : {}),
             createIsolation: () => this.createAgentWorktree(paths.praxisRoot, sessionId, agentId, parentCwd),
             execute: async (cwd, message, signal, continuation) => {
+                // Recovery never restores provider-native route state. Each recovered
+                // execution, including every later follow-up, gets a fresh turn.
+                const provider = this.providerForTurn(input.model);
                 const run = (lease) => this.runSidechain({
                     ...lease,
                     sessionId,
@@ -1757,7 +1773,7 @@ export class ClaudeSubagentExecutor {
             prompt,
             toolUseId,
             outputFile: sidechainPaths.transcriptFile,
-            resolvedModel: provider.model ?? 'praxis/provider',
+            resolvedModel: metadata?.model ?? this.options.provider.model ?? 'praxis/provider',
             lifecycle: backgroundRun.lifecycle,
             run: backgroundRun.run,
             markBackground: backgroundRun.markBackground,

package/dist/application/team-agent-runtime.d.ts

@@ -14,6 +14,7 @@ export interface ClaudeTeamAgentRuntimeOptions {
     readonly hooks?: ClaudeHookRunner;
     readonly contextAssembler?: ContextAssembler;
     readonly providerForModel?: (model: string) => ModelProvider;
+    readonly providerForTurn?: (model?: string) => ModelProvider;
     readonly permissionResolverForMode?: (mode: AgentPermissionMode) => PermissionResolver;
     readonly eventSink?: RuntimeEventSink;
     readonly approveTool?: (call: ModelToolCall, originalCall?: ModelToolCall, decision?: PermissionDecision) => PermissionApproval | Promise<PermissionApproval>;

package/dist/application/team-agent-runtime.js

@@ -79,6 +79,9 @@ export class ClaudeTeamAgentRuntime {
             ...(this.options.providerForModel
                 ? { providerForModel: this.options.providerForModel }
                 : {}),
+            ...(this.options.providerForTurn
+                ? { providerForTurn: this.options.providerForTurn }
+                : {}),
             ...(this.options.permissionResolverForMode
                 ? {
                     permissionResolverForMode: this.options.permissionResolverForMode,

package/dist/cli-runtime.js

@@ -1044,6 +1044,7 @@ const createDefaultService = async ({ eventSink, requireProvider, hooksOnly = fa
     let provider;
     let providerForModel;
     let providerForMainModel;
+    let providerForTurn;
     let providerBillingMode;
     const context = parseContextEnvironment(runtimeEnvironment);
     const apiKey = runtimeEnvironment.PRAXIS_API_KEY;
@@ -1164,17 +1165,25 @@ const createDefaultService = async ({ eventSink, requireProvider, hooksOnly = fa
             providerBillingMode = registry.target.billingMode;
             providerForModel = (selectedModel) => registry.create(selectedModel);
             const createProvider = providerForModel;
-            providerForMainModel = (primaryModel) => {
+            const createProviderStack = (primaryModel, routeScope) => {
                 const models = [primaryModel, ...(cli.fallbackModels ?? [])].filter((candidate, index, all) => all.indexOf(candidate) === index);
                 const providers = models.map((candidate) => createProvider(candidate));
                 const selected = providers[0];
                 if (!selected)
                     throw new Error('A primary model is required');
                 return providers.length > 1
-                    ? new FallbackModelProvider({ providers })
+                    ? new FallbackModelProvider({ providers, routeScope })
                     : selected;
             };
-            provider = providerForMainModel(model);
+            providerForMainModel = (primaryModel) => createProviderStack(primaryModel, 'completion');
+            const defaultProvider = providerForMainModel(model);
+            provider = defaultProvider;
+            providerForTurn = (turnModel) => {
+                const selectedModel = turnModel ?? model;
+                return selectedModel === undefined
+                    ? defaultProvider
+                    : createProviderStack(selectedModel, 'turn');
+            };
         }
         catch (error) {
             const optionalProviderError = error instanceof ProviderAuthenticationError ||
@@ -1468,9 +1477,11 @@ const createDefaultService = async ({ eventSink, requireProvider, hooksOnly = fa
         });
     if (memoryDirectory)
         await mkdir(memoryDirectory, { recursive: true });
-    const projectMemoryProviderFactory = providerForMainModel && model
-        ? () => providerForMainModel(model)
-        : undefined;
+    const projectMemoryProviderFactory = providerForTurn
+        ? () => providerForTurn()
+        : providerForMainModel && model
+            ? () => providerForMainModel(model)
+            : undefined;
     const projectMemoryRecall = projectMemoryPolicy.recall &&
         memoryDirectory &&
         projectMemoryProviderFactory
@@ -1902,6 +1913,7 @@ const createDefaultService = async ({ eventSink, requireProvider, hooksOnly = fa
                     ...(hooks ? { hooks } : {}),
                     ...(contextAssembler ? { contextAssembler } : {}),
                     ...(providerForModel ? { providerForModel } : {}),
+                    ...(providerForTurn ? { providerForTurn } : {}),
                     permissionResolverForMode,
                     eventSink: runtimeEventSink,
                 }),
@@ -1918,6 +1930,7 @@ const createDefaultService = async ({ eventSink, requireProvider, hooksOnly = fa
             provider: hostedToolProvider,
             ...(providerForModel ? { providerForModel } : {}),
             ...(providerForMainModel ? { providerForMainModel } : {}),
+            ...(providerForTurn ? { providerForTurn } : {}),
             tools: filteredTools,
             toolCapabilityEnvironment: runtimeEnvironment,
             ...(!experimentalNativeTranscriptWrites ? { mcp: mcpTools } : {}),

package/dist/providers/codex-subscription.d.ts

@@ -14,19 +14,13 @@ export interface CodexSubscriptionProviderOptions {
     maxErrorBodyBytes?: number;
     thinking?: ModelThinkingConfig;
 }
-export declare function serializeCodexRequest(request: ModelRequest, model: string, configuredThinking?: ModelThinkingConfig): Record<string, unknown>;
-export declare function parseCodexSseFrame(data: string): ModelStreamEvent[];
 export declare class CodexSubscriptionProvider implements ModelProvider {
     private readonly options;
     readonly model: string;
     readonly capabilities: ModelProvider['capabilities'];
     private readonly fetchImplementation;
-    private readonly maxStreamBufferBytes;
-    private readonly maxToolArgumentsBytes;
-    private readonly maxToolCallsPerResponse;
-    private readonly maxToolMetadataBytes;
-    private readonly maxReasoningBytes;
     private readonly maxErrorBodyBytes;
+    private readonly responsesCodec;
     constructor(options: CodexSubscriptionProviderOptions);
     complete(request: ModelRequest): AsyncIterable<ModelStreamEvent>;
 }