@callstack/apex 0.3.0 → 0.4.1

package/README.md

@@ -148,15 +148,43 @@ their own backup first, so an undo is itself reversible. Apex CLI records each b
 | OpenCode | `~/.config/opencode/opencode.json` or `.jsonc` | Adds `provider.callstack.ai`, OpenAI-compatible transport, model and environment-key reference; preserves the default model. A config already in OpenCode 2's `providers` format gets the v2 entry instead, and you add the key with `/connect`. |
 | Codex 0.134.0+ | `~/.codex/callstack_ai.config.toml` | Adds a self-contained Responses API provider/profile; leaves base config and default model untouched. |
 | Claude Code | `~/.claude/settings.json` | Merges attribution flag only; use `apex run claude` for gateway credentials and model selection. |
-| Pi | `~/.pi/agent/models.json` | Adds `providers.callstack` with Chat Completions, Apex and `$CALLSTACK_AUTH_TOKEN`; preserves other models. Requires a Pi version supporting `$VAR` key interpolation. |
+| Pi | `~/.pi/agent/models.json` and `settings.json` | Adds `providers.callstack` with Chat Completions, Apex and `$CALLSTACK_AUTH_TOKEN`; saves `medium` as Apex's per-model thinking default for direct launches. Preserves other models and their defaults. Requires a Pi version supporting `$VAR` key interpolation and `modelThinkingLevels`. |
 | Cursor | Guided setup | Prints endpoint, API-key and custom-model steps; does not modify private editor storage. |
 | VS Code / Copilot | Guided setup | Detects VS Code, not whether Copilot is installed; prints custom-endpoint steps and model JSON, retaining the editor-generated secret reference. |
-| Vercel AI SDK / Eve | Guided setup | Detected from the `package.json` in the directory you run Apex CLI from (`ai`, `@ai-sdk/openai` or `eve`); prints the connector snippet, which reads the key from `CALLSTACK_AUTH_TOKEN`, and the Eve context-window setting. Nothing is written into the project. |
-
-OpenCode, Pi, Codex and the Copilot model JSON also declare what Apex can do, in each tool's own
-fields: a 262,144-token context window, 16,384 output tokens, tool calling, image input, and the
-`none`/`low`/`medium`/`xhigh` reasoning efforts (default `medium`). Cursor and Claude Code have no
-such fields for a custom model.
+| Vercel AI SDK / Eve | Guided setup | Detected from the `package.json` in the directory you run Apex CLI from (`ai`, `@ai-sdk/openai` or `eve`); prints the connector snippet, which reads the key from `CALLSTACK_AUTH_TOKEN`. Nothing is written into the project. |
+
+Apex configs declare tool calling, image input, and the supported
+`none`/`low`/`medium`/`xhigh` reasoning efforts (default `medium`) where supported.
+OpenCode, Pi, Copilot, Claude's launcher, and the AI SDK guidance retain a 32,768-token output
+budget. OpenCode, Pi, Codex, Copilot, and Claude's launcher declare the model's native
+262,144-token context window using each app's documented fields. Input limits and compaction
+thresholds use the harness defaults; Apex CLI does not set a separate input budget or compaction
+reserve.
+Pi's per-model default applies to fresh direct launches and model selection; `apex run pi` also
+selects `medium` explicitly. Resumed Pi sessions retain their saved thinking level.
+
+The gateway model ID, authentication, `medium` default, and `off` → `none` translation remain
+Callstack-specific.
+
+| Harness | Context field | Output field | Official reference |
+| --- | --- | --- | --- |
+| OpenCode | `limit.context` | `limit.output` | [Custom providers](https://opencode.ai/docs/providers/) |
+| Pi | `contextWindow` | `maxTokens` | [Custom models](https://pi.dev/docs/latest/models) |
+| Codex | `model_context_window` | No output-limit config key | [OpenAI configuration reference](https://developers.openai.com/codex/config-reference/) |
+| Claude Code launcher | `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | [Environment variables](https://code.claude.com/docs/en/env-vars) |
+| VS Code / Copilot | `contextWindow` | `maxOutputTokens` | [Custom endpoint models](https://code.visualstudio.com/docs/agent-customization/language-models) |
+
+The Claude launcher sets context/output limits only in the child process and does not set compaction
+window or percentage controls. Pi retains its native compaction settings. The AI SDK
+snippet sets the output budget without inventing a context-window option.
+
+Run `apex init` again after updating the CLI to preview upgrades to an existing Apex setup; pass
+`--apply` to save them. Apex context/output metadata and reasoning mappings are updated in place. Older OpenCode input
+limits and Codex compaction overrides are removed so each harness uses its own compaction defaults.
+Codex's obsolete `model_max_output_tokens` key from older Apex versions is removed, and its dedicated
+profile becomes self-contained. Unrelated settings, models, credentials and comments are preserved;
+the ordinary backups and `apex undo` also cover upgrades. `none` remains supported: the gateway
+translates it to thinking off.
 
 Respects `XDG_CONFIG_HOME`, `CODEX_HOME`, `CLAUDE_CONFIG_DIR`, `PI_CODING_AGENT_DIR`,
 `XDG_STATE_HOME`/`APEX_STATE_DIR`, and Windows `APPDATA`. Project-specific settings and custom
@@ -201,9 +229,12 @@ Apex CLI will not break what you already have.
 How that works underneath:
 
 - Previews print paths and key/value changes, never secrets.
-- All selected configurations are parsed before any write. Malformed files, conflicting Codex
-  profile keys and symlinked files or directories are refused, and one bad assistant blocks the
-  whole batch instead of half-applying it.
+- All selected configurations are parsed before any write. Malformed files, symlinked files and
+  dangling links are refused, and one bad assistant blocks the whole batch instead of half-applying
+  it. Symlinked directories, such as Stow-managed dotfiles, are followed; the `.apex-backup-*` copies
+  then land in your dotfiles repo, so add `*.apex-backup-*` to its `.gitignore`.
+- The dedicated Codex Apex profile's owned keys are upgraded rather than rejected as conflicts;
+  the base `config.toml` and other profiles remain untouched.
 - JSON/JSONC edits preserve comments and unrelated keys. The Callstack endpoint is set to the
   documented one. A key the assistant already has (in OpenCode's own key store, or in Pi's
   `models.json`, where Apex CLI 0.2 put them) is kept, so upgrading never leaves an assistant