Anthropic/XAI Optimizations (#866)

* anthropic cache management, extend default poll window, xai parallel

* anth cache fix

* harden

* version bump

* status view improvements

* xai auth support, codex refactor, session tui fixes

* improve wording/symbols

* fix auth and session test isolation

* otel warns

---------

Co-authored-by: evalstate <evalstate@users.noreply.github.com>

Author: evalstate

docs/docs/_generated/tui_runtime_reference.md

@@ -33,4 +33,6 @@
 | `shell_execution.interactive_use_pty` | `SHELL_EXECUTION__INTERACTIVE_USE_PTY` | `bool` | `True` | Use a PTY for interactive prompt shell commands. |
 | `shell_execution.timeout_seconds` | `SHELL_EXECUTION__TIMEOUT_SECONDS` | `int` | `90` | Maximum seconds without command output before termination. |
 | `shell_execution.warning_interval_seconds` | `SHELL_EXECUTION__WARNING_INTERVAL_SECONDS` | `int` | `30` | Show timeout warnings every N seconds. |
+| `shell_execution.process_poll_max_wait_seconds` | `SHELL_EXECUTION__PROCESS_POLL_MAX_WAIT_SECONDS` | `int` | `250` | Maximum wait accepted by poll_process. |
+| `shell_execution.managed_process_poll_history_folding` | `SHELL_EXECUTION__MANAGED_PROCESS_POLL_HISTORY_FOLDING` | `Literal['auto', 'on', 'off']` | `auto` | Fold repetitive quiet poll_process exchanges. |
 | `tui.completion_menu_reserved_lines` | `TUI__COMPLETION_MENU_RESERVED_LINES` | `int` | `6` | Prompt-toolkit lines reserved below the input for completion menus. |

docs/docs/agents/instructions.md

@@ -28,6 +28,7 @@ The following variables are available in System Prompt templates:
 | <nobr>`{{agentType}}`</nobr> | Current agent type |  |
 | <nobr>`{{agentCardPath}}`</nobr> | Source AgentCard path | `(internal)` when not loaded from a card |
 | <nobr>`{{agentCardDir}}`</nobr> | Directory containing the source AgentCard | `(internal)` when not loaded from a card |
+| <nobr>`{{modelReferences}}`</nobr> | Model references | Includes the effective `$system.default` Useful for instructing CLI based subagents |
 | <nobr>`{{model_specific}}`</nobr> | Model-specific prompt guidance from the resolved model catalog entry or model overlay | Empty when the selected model has no model-specific guidance |
 | <nobr>`{{hostPlatform}}`</nobr> | Host platform information |  |
 | <nobr>`{{pythonVer}}`</nobr> | Python version |  |
@@ -38,7 +39,7 @@ The following variables are available in System Prompt templates:
 ```
 Environment:
 - Workspace root: /home/user/project
-- Client: Zed 0.232
+- Client: fast-agent (pid 12345)
 - Host platform: Linux-6.6.87.2-microsoft-standard-WSL2
 ```
 

docs/docs/guides/codex.md

@@ -46,7 +46,7 @@ connect to MCP Servers.
 If you want to use the Codex OAuth models directly, authenticate once first:
 
 ```bash
-fast-agent auth codexplan
+fast-agent auth login codex
 ```
 
 This stores the token in your OS keyring. After that you can use Codex OAuth

docs/docs/mcp/mcp-oauth.md

@@ -65,22 +65,22 @@ Notes:
 
 - Show auth status (keyring backend, stored identities, configured servers → identities)
   - `fast-agent auth`
-  - `fast-agent auth status`
+  - `fast-agent auth mcp status`
   - Single target:
-    - `fast-agent auth status https://example-server.modelcontextprotocol.io`
-    - `fast-agent auth status myserver`
+    - `fast-agent auth mcp status https://example-server.modelcontextprotocol.io`
+    - `fast-agent auth mcp status myserver`
 
 - Proactive login (perform OAuth and store tokens)
   - By server name in config:
-    - `fast-agent auth login myserver`
+    - `fast-agent auth mcp login myserver`
   - By identity (ad hoc, no config):
-    - HTTP (default): `fast-agent auth login https://example-server.modelcontextprotocol.io`
-    - SSE: `fast-agent auth login https://example-server.modelcontextprotocol.io --transport sse`
+    - HTTP (default): `fast-agent auth mcp login https://example-server.modelcontextprotocol.io`
+    - SSE: `fast-agent auth mcp login https://example-server.modelcontextprotocol.io --transport sse`
 
 - Clear tokens
-  - By identity (base URL): `fast-agent auth clear --identity https://example-server.modelcontextprotocol.io`
-  - By server name (from config): `fast-agent auth clear myserver`
-  - All identities: `fast-agent auth clear --all`
+  - By identity (base URL): `fast-agent auth mcp logout --identity https://example-server.modelcontextprotocol.io`
+  - By server name (from config): `fast-agent auth mcp logout myserver`
+  - All identities: `fast-agent auth mcp logout --all`
 
 - Check full app config (includes server OAuth flags and token presence):
   - `fast-agent check`
@@ -98,12 +98,12 @@ to an empty value to disable the built-in default.
   - A local callback server (`http://localhost:3030/callback`) captures the code; if the port is blocked, you’ll be prompted to paste the callback URL.
 
 - Proactive login (no agent session needed)
-  - `fast-agent auth login https://example-server.modelcontextprotocol.io`
+  - `fast-agent auth mcp login https://example-server.modelcontextprotocol.io`
   - Complete the link flow once; tokens will be reused next time.
 
 - Inspect and clear a specific identity
-  - `fast-agent auth status https://example-server.modelcontextprotocol.io`
-  - `fast-agent auth clear --identity https://example-server.modelcontextprotocol.io`
+  - `fast-agent auth mcp status https://example-server.modelcontextprotocol.io`
+  - `fast-agent auth mcp logout --identity https://example-server.modelcontextprotocol.io`
 
 ## Troubleshooting
 

docs/docs/models/index.md

@@ -9,7 +9,7 @@ social:
 
 **`fast-agent`** has native support for **OpenAI Responses** and **Chat Completions**, **Anthropic Messages**, **Google GenAI** and **Amazon Bedrock** APIs. 
 
-OpenAI Codex users can use their subscription with **`fast-agent`**, using their existing installation or logging in with `fast-agent auth codexplan`. 
+OpenAI Codex users can use their subscription with **`fast-agent`**, using their existing installation or logging in with `fast-agent auth login codex`.
 
 Chat Completions models are also available via **Microsoft Azure**, and supported Anthropic models are available on **Google Vertex**.
 

docs/docs/models/llm_providers.md

@@ -34,7 +34,7 @@ The `default_headers` option is available for OpenAI-compatible providers (inclu
 | --- | --- | --- | --- |
 | OpenAI Responses | `responses` | `OPENAI_API_KEY` | Native Responses API, reasoning, web search, connectors, remote MCP |
 | OpenAI Chat Completions | `openai` | `OPENAI_API_KEY` | OpenAI-compatible Chat Completions models |
-| Codex Responses | `codexresponses` | `fast-agent auth codexplan` or `CODEX_API_KEY` | Codex subscription-backed Responses models; no provider-managed MCP/connectors |
+| Codex Responses | `codexresponses` | `fast-agent auth login codex` or `CODEX_API_KEY` | Codex subscription-backed Responses models; no provider-managed MCP/connectors |
 | Anthropic | `anthropic` | `ANTHROPIC_API_KEY` or Anthropic SDK credentials | Claude Messages API, prompt caching, web tools |
 | Google | `google` | `GOOGLE_API_KEY` | Native Gemini API |
 | Azure OpenAI | `azure` | `AZURE_OPENAI_API_KEY` | Azure deployments and optional DefaultAzureCredential |

docs/docs/models/model_overlays.md

@@ -127,6 +127,7 @@ metadata:
     - image/jpeg
     - image/png
   default_temperature: 0.8
+  managed_process_poll_folding: true
   process_poll_default_wait_seconds: 30
   fast: true
 
@@ -183,6 +184,10 @@ Common fields:
 - `context_window`
 - `max_output_tokens`
 - `tokenizes`
+- `managed_process_poll_folding`: whether automatic folding of repetitive
+  quiet `poll_process` exchanges has been validated for this model. This is
+  consulted when `shell_execution.managed_process_poll_history_folding` is
+  `auto`.
 - `process_poll_default_wait_seconds`: default `poll_process` wait when the model
   omits `wait_sec` (`0` keeps polling non-blocking). The value is capped by
   `shell_execution.process_poll_max_wait_seconds`.

docs/docs/models/providers/openai.md

@@ -28,7 +28,7 @@ Encrypted reasoning blocks are used to maintain model intelligence between tool
 
 | Feature | `responses` | `codexresponses` | `openai` Chat Completions |
 | --- | --- | --- | --- |
-| Auth | `OPENAI_API_KEY` | `fast-agent auth codexplan` or `CODEX_API_KEY` | `OPENAI_API_KEY` |
+| Auth | `OPENAI_API_KEY` | `fast-agent auth login codex` or `CODEX_API_KEY` | `OPENAI_API_KEY` |
 | API surface | OpenAI Responses API | Codex Responses backend | Chat Completions API |
 | Curated aliases | `gpt55`, `gpt54`, `gpt52`, `codex`, `chatgpt` | `codexplan`, `codexplan54`, `codexspark` | `openai.gpt-4.1`, `openai.gpt-4o` |
 | Structured outputs | Yes, JSON schema where model supports it | Yes, JSON schema where model supports it | Yes, model-dependent Chat Completions structured outputs |
@@ -77,7 +77,7 @@ Examples:
 ### Codex Responses models
 
 Use `codexresponses` for Codex subscription-backed models. Authenticate with
-`fast-agent auth codexplan` or provide `CODEX_API_KEY`.
+`fast-agent auth login codex` or provide `CODEX_API_KEY`.
 
 The `codexresponses` provider is similar to `responses`, with these main differences:
 
@@ -208,7 +208,7 @@ for card-scoped runtime targets.
 
 ## Codex (OAuth Responses)
 
-**`fast-agent`** supports using your OpenAI Codex subscription. Run `fast-agent auth codexplan`
+**`fast-agent`** supports using your OpenAI Codex subscription. Run `fast-agent auth login codex`
 once, then use a Codex OAuth model alias such as `codexplan` (GPT-5.5 planning),
 `codexplan54` (GPT-5.4 planning), `codexplan53` (GPT-5.3 Codex planning), or
 `codexspark` (GPT-5.3 Codex Spark).
@@ -217,7 +217,7 @@ once, then use a Codex OAuth model alias such as `codexplan` (GPT-5.5 planning),
 
 ```bash
 # Start OAuth login (stores tokens in your OS keyring)
-fast-agent auth codexplan
+fast-agent auth login codex
 
 # Use the Codex planning model
 fast-agent --model codexplan
@@ -245,7 +245,7 @@ codexresponses:
 
 **Notes:**
 
-- Tokens are stored in your OS keyring via `fast-agent auth codexplan`.
+- Tokens are stored in your OS keyring, with a secure file fallback, via `fast-agent auth login codex`.
 - `codexplan` maps to `codexresponses.gpt-5.5?reasoning=medium`.
 - `codexplan54` maps to `codexresponses.gpt-5.4?reasoning=high`.
 - `codexplan53` maps to `codexresponses.gpt-5.3-codex?reasoning=medium`.
@@ -254,5 +254,6 @@ codexresponses:
 - Provider-managed MCP is **not** supported with `codexresponses`, including
   Codex OAuth aliases such as `codexplan`, `codexplan54`, and `codexspark`.
   Use `responses` instead when you need `management: provider`.
-- To remove tokens, use: `fast-agent auth codex-clear`.
+- To remove fast-agent-owned tokens, use: `fast-agent auth logout codex`. Codex
+  CLI auth files are treated as read-only and are never modified or deleted.
 - `fast-agent check` and `fast-agent auth` show Codex OAuth status.

docs/docs/models/providers/xai.md

@@ -11,6 +11,33 @@ social:
 
 Use the `xai` provider for xAI Grok models. xAI supports both `web_search` and `x_search`; fast-agent sends `x_search` as xAI's provider-managed X Search tool.
 
+## Sign in with a Grok/X subscription
+
+```bash
+fast-agent auth login xai
+```
+
+The device login opens an xAI verification URL and displays a code. Provider
+credentials use the OS keyring when it is writable and otherwise fall back to
+`~/.fast-agent/auth.json`. Access tokens refresh automatically before expiry.
+
+The model selector also offers this login when an xAI model is selected without
+a configured credential.
+
+Useful credential commands:
+
+```bash
+fast-agent auth status xai
+fast-agent auth token xai
+fast-agent auth export xai ./xai.auth.json
+fast-agent auth logout xai
+```
+
+An exported file contains only the selected provider and includes its refresh
+token. Set `FAST_AGENT_AUTH_FILE` to use that portable file. This is the
+recommended form for long-running Harbor jobs because refreshed credentials are
+written back to the staged file.
+
 ## Configure
 
 ```yaml
@@ -23,6 +50,9 @@ Environment variables:
 
 - `XAI_API_KEY`: Your xAI API key
 - `XAI_BASE_URL`: Override the API endpoint
+- `FAST_AGENT_AUTH_FILE`: Explicit portable provider credential file
+
+An explicit `xai.api_key` or `XAI_API_KEY` takes precedence over stored OAuth.
 
 ## Use a model
 

docs/docs/ref/cmd_switches.md

@@ -134,6 +134,18 @@ fast-agent export latest --hf-url hf://buckets/your-name/fast-agent-traces/
 
 See the full reference [here](export_command/).
 
+## fast-agent session Command
+
+Remove empty session placeholders left by interrupted startups:
+
+```bash
+fast-agent session prune --empty
+```
+
+This preserves sessions with history, titles, previews, or pins. Run it when no
+other fast-agent process is starting or waiting for its first turn, because
+those live sessions are also empty until they persist content.
+
 ## fast-agent check Command
 
 Use `fast-agent check` to diagnose your configuration: