@oh-my-pi/pi-coding-agent 12.7.6 → 12.8.0

package/docs/environment-variables.md

@@ -1,257 +0,0 @@
-# Environment Variables Reference
-
-This document lists all environment variables used by the coding agent.
-
-## API Keys
-
-### Multi-Provider Support
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `OPENAI_API_KEY` | OpenAI API key for GPT models | - |
-| `ANTHROPIC_API_KEY` | Anthropic API key for Claude models | - |
-| `ANTHROPIC_OAUTH_TOKEN` | Anthropic OAuth token (takes precedence over `ANTHROPIC_API_KEY`) | - |
-| `GOOGLE_API_KEY` | Google Gemini API key | - |
-| `COPILOT_GITHUB_TOKEN` | GitHub Copilot personal access token | `$GH_TOKEN` or `$GITHUB_TOKEN` |
-| `GH_TOKEN` | GitHub CLI token (fallback for Copilot) | - |
-| `GITHUB_TOKEN` | GitHub token (fallback for Copilot and API access) | - |
-| `EXA_API_KEY` | Exa search API key | - |
-| `GROQ_API_KEY` | Groq API key for Llama and other models | - |
-| `CEREBRAS_API_KEY` | Cerebras API key | - |
-| `XAI_API_KEY` | xAI API key for Grok models | - |
-| `OPENROUTER_API_KEY` | OpenRouter aggregated models API key | - |
-| `MISTRAL_API_KEY` | Mistral AI API key | - |
-| `ZAI_API_KEY` | z.ai API key (ZhipuAI/GLM models) | - |
-| `MINIMAX_API_KEY` | MiniMax API key | - |
-| `OPENCODE_API_KEY` | OpenCode API key | - |
-| `CURSOR_ACCESS_TOKEN` | Cursor AI access token | - |
-| `AI_GATEWAY_API_KEY` | Vercel AI Gateway API key | - |
-| `PERPLEXITY_API_KEY` | Perplexity search API key | - |
-
-### Provider-Specific Configuration
-
-#### AWS Bedrock
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `AWS_REGION` | AWS region for Bedrock | `$AWS_DEFAULT_REGION` or `us-east-1` |
-| `AWS_DEFAULT_REGION` | AWS default region | - |
-| `AWS_PROFILE` | AWS CLI profile name | - |
-| `AWS_ACCESS_KEY_ID` | AWS access key ID | - |
-| `AWS_SECRET_ACCESS_KEY` | AWS secret access key | - |
-| `AWS_BEARER_TOKEN_BEDROCK` | AWS bearer token for Bedrock | - |
-| `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` | ECS container credentials URI | - |
-| `AWS_CONTAINER_CREDENTIALS_FULL_URI` | ECS container credentials full URI | - |
-| `AWS_WEB_IDENTITY_TOKEN_FILE` | Web identity token file path | - |
-| `AWS_ROLE_ARN` | IAM role ARN for web identity | - |
-
-#### Azure OpenAI
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `AZURE_OPENAI_API_KEY` | Azure OpenAI API key (required) | - |
-| `AZURE_OPENAI_API_VERSION` | Azure OpenAI API version | `2024-10-01-preview` |
-| `AZURE_OPENAI_BASE_URL` | Azure OpenAI base URL | Constructed from resource name |
-| `AZURE_OPENAI_RESOURCE_NAME` | Azure OpenAI resource name | - |
-| `AZURE_OPENAI_DEPLOYMENT_NAME_MAP` | JSON map of model IDs to deployment names | `{}` |
-
-#### Google Cloud (Vertex AI)
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `GOOGLE_CLOUD_PROJECT` | Google Cloud project ID (required for Vertex AI) | `$GCLOUD_PROJECT` |
-| `GCLOUD_PROJECT` | Google Cloud project ID (alternative) | - |
-| `GOOGLE_CLOUD_PROJECT_ID` | Google Cloud project ID (used during OAuth discovery) | `$GOOGLE_CLOUD_PROJECT` |
-| `GOOGLE_CLOUD_LOCATION` | Google Cloud location (required for Vertex AI) | - |
-| `GOOGLE_APPLICATION_CREDENTIALS` | Path to Google service account JSON | - |
-
-#### Anthropic Search & Custom Base URLs
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `ANTHROPIC_BASE_URL` | Custom Anthropic API base URL | - |
-| `ANTHROPIC_SEARCH_API_KEY` | API key for Anthropic search (separate from main API) | - |
-| `ANTHROPIC_SEARCH_BASE_URL` | Custom base URL for Anthropic search | - |
-| `ANTHROPIC_SEARCH_MODEL` | Model to use for web search | `claude-sonnet-4` |
-
-#### Kimi
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `KIMI_CODE_BASE_URL` | Kimi Code API base URL | `https://kimi.moonshot.cn` |
-| `KIMI_CODE_OAUTH_HOST` | Kimi Code OAuth host | `$KIMI_OAUTH_HOST` or `https://kimi.moonshot.cn` |
-| `KIMI_OAUTH_HOST` | Kimi OAuth host (fallback) | - |
-
-## Model Configuration
-
-### Model Role Overrides
-
-Override model roles via environment variables (ephemeral, not persisted):
-
-| Variable | Description | CLI Flag |
-|----------|-------------|----------|
-| `PI_SMOL_MODEL` | Fast model for lightweight tasks | `--smol` |
-| `PI_SLOW_MODEL` | Reasoning model for thorough analysis | `--slow` |
-| `PI_PLAN_MODEL` | Model for architectural planning | `--plan` |
-
-## Agent Configuration
-
-### Core Settings
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `PI_CODING_AGENT_DIR` | Directory for agent data (sessions, auth, cache) | `~/.omp/agent` |
-| `PI_SUBPROCESS_CMD` | Custom command for spawning subagents | Auto-detected |
-| `PI_NO_TITLE` | Disable automatic session title generation | `false` |
-| `NULL_PROMPT` | Use empty system prompt (testing) | `false` |
-| `PI_BLOCKED_AGENT` | Override agent type in task tool | - |
-
-### Caching
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `PI_CACHE_RETENTION` | Prompt cache retention (`long` = 24h for OpenAI) | - |
-
-## Python Configuration
-
-### Python Kernel
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `VIRTUAL_ENV` | Python virtual environment path | Auto-detected (`.venv` or `venv`) |
-| `PI_PY` | Python tool mode (`per-session`, `per-call`, `off`) | `per-session` |
-| `PI_PYTHON_SKIP_CHECK` | Skip Python availability check (testing) | `false` |
-
-### External Python Gateway
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `PI_PYTHON_GATEWAY_URL` | External Python gateway URL | - |
-| `PI_PYTHON_GATEWAY_TOKEN` | Authentication token for gateway | - |
-
-### Debugging
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `PI_PYTHON_IPC_TRACE` | Trace Python IPC messages (`1` = enabled) | `false` |
-
-## Task & Subagent Configuration
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `PI_TASK_MAX_OUTPUT_BYTES` | Maximum output bytes per subagent | `500000` |
-| `PI_TASK_MAX_OUTPUT_LINES` | Maximum output lines per subagent | `5000` |
-
-## TUI & Terminal Configuration
-
-### Terminal Capabilities
-
-| Variable | Description | Auto-Detected |
-|----------|-------------|---------------|
-| `COLORTERM` | Terminal color support (`truecolor`, `24bit`) | Yes |
-| `COLORFGBG` | Terminal foreground/background colors | Yes |
-| `TERM` | Terminal type | Yes |
-| `TERM_PROGRAM` | Terminal program name | Yes |
-| `TERM_PROGRAM_VERSION` | Terminal program version | Yes |
-| `TERMINAL_EMULATOR` | Terminal emulator name | Yes |
-| `WT_SESSION` | Windows Terminal session ID | Yes |
-
-### TUI Behavior
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `PI_NOTIFICATIONS` | Desktop notifications (`off`, `0`, `false` = disabled) | Enabled |
-| `PI_TUI_WRITE_LOG` | Log all TUI write operations to file | - |
-| `PI_HARDWARE_CURSOR` | Show hardware cursor (`1` = enabled) | `false` |
-
-## Bash & Shell Configuration
-
-### Shell Detection
-
-| Variable | Description | Auto-Detected |
-|----------|-------------|---------------|
-| `SHELL` | User's default shell | Yes (Unix) |
-| `ComSpec` | Command processor | Yes (Windows) |
-
-### Editor
-
-| Variable | Description | Fallback |
-|----------|-------------|----------|
-| `VISUAL` | Visual editor for external editing (Ctrl+G) | `$EDITOR` |
-| `EDITOR` | Default text editor | - |
-
-### Bash Tool Behavior
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `PI_BASH_NO_CI` | Don't set `CI=true` in bash environment | `$CLAUDE_BASH_NO_CI` |
-| `CLAUDE_BASH_NO_CI` | Legacy name for `PI_BASH_NO_CI` | - |
-| `PI_BASH_NO_LOGIN` | Don't use login shell for bash | `$CLAUDE_BASH_NO_LOGIN` |
-| `CLAUDE_BASH_NO_LOGIN` | Legacy name for `PI_BASH_NO_LOGIN` | - |
-| `PI_SHELL_PREFIX` | Prefix for bash commands | `$CLAUDE_CODE_SHELL_PREFIX` |
-| `CLAUDE_CODE_SHELL_PREFIX` | Legacy name for `PI_SHELL_PREFIX` | - |
-
-## Desktop Environment Detection
-
-These are auto-detected for system prompt context:
-
-| Variable | Purpose |
-|----------|---------|
-| `KDE_FULL_SESSION` | Detect KDE desktop |
-| `XDG_CURRENT_DESKTOP` | Current desktop environment |
-| `DESKTOP_SESSION` | Desktop session name |
-| `XDG_SESSION_DESKTOP` | XDG desktop session |
-| `GDMSESSION` | GDM session type |
-| `WINDOWMANAGER` | Window manager name |
-| `XDG_CONFIG_HOME` | User config directory |
-| `APPDATA` | Windows app data directory |
-| `HOME` | User home directory |
-
-## LSP Configuration
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `PI_DISABLE_LSPMUX` | Disable lspmux integration (`1` = disabled) | `false` |
-
-## Debugging & Development
-
-### General Debugging
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `DEBUG` | Enable debug logging | `false` |
-| `PI_DEV` | Development mode (verbose native addon loading) | `false` |
-| `PI_TIMING` | Log tool factory and operation timings (`1` = enabled) | `false` |
-
-### Startup Debugging
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `PI_DEBUG_STARTUP` | Print startup stage timings to stderr | `false` |
-
-### Provider-Specific Debugging
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `DEBUG_CURSOR` | Cursor provider debug logging (`1` = basic, `2` or `verbose` = detailed) | `false` |
-| `DEBUG_CURSOR_LOG` | Path to write Cursor debug log file | - |
-| `PI_CODEX_DEBUG` | OpenAI Codex debug logging (`1` or `true` = enabled) | `false` |
-
-## Commit Message Generation
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `PI_COMMIT_TEST_FALLBACK` | Force fallback commit generation (testing) | `false` |
-| `PI_COMMIT_NO_FALLBACK` | Disable fallback commit generation | `false` |
-| `PI_COMMIT_MAP_REDUCE` | Enable/disable map-reduce for large diffs (`false` = disabled) | Enabled |
-
-## Testing & CI
-
-These are auto-detected but documented for completeness:
-
-| Variable | Description |
-|----------|-------------|
-| `BUN_ENV` | Bun environment (`test` skips certain checks) |
-| `NODE_ENV` | Node environment (`test` skips certain checks) |
-| `E2E` | Enable end-to-end tests (`1` or `true`) |
-| `PI_NO_LOCAL_LLM` | Skip local LLM tests (Ollama, LM Studio) |

package/docs/extension-loading.md

@@ -1,106 +0,0 @@
-# Extension Loading
-
-This document describes how omp discovers and loads extensions at runtime. It covers two related systems:
-
-- **Extension modules**: TypeScript/JavaScript modules that register tools, hooks, commands, etc.
-- **Gemini-style extensions**: `gemini-extension.json` manifests that declare MCP servers, tools, and context.
-
-## Extension Modules (TypeScript/JavaScript)
-
-### Discovery Locations
-
-Extension modules are auto-discovered from native config roots:
-
-- `.omp` (primary)
-- `.pi` (legacy alias)
-
-For each root:
-
-- **User-level**: `~/.omp/agent/extensions/`
-- **Project-level**: `<cwd>/.omp/extensions/`
-
-### Configured Paths
-
-Additional extension paths can be provided via settings and CLI:
-
-- **Global settings**: `~/.omp/agent/config.yml` (or `$PI_CODING_AGENT_DIR/config.yml`)
-- **Project settings**: `<cwd>/.omp/settings.json`
-- **CLI**: `--extension` or `-e`
-
-The settings schema uses the `extensions` array (paths are files or directories):
-
-```yaml
-# ~/.omp/agent/config.yml
-extensions:
-  - ./local-extension.ts
-  - ~/extensions/pack
-```
-
-```json
-// .omp/settings.json
-{
-	"extensions": ["./project-extension.ts"]
-}
-```
-
-Path resolution rules:
-
-- `~` expands to the home directory
-- Relative paths resolve against the current working directory
-
-To disable all extension loading:
-
-```bash
-omp --no-extensions
-```
-
-### Entry Point Resolution
-
-Within an `extensions/` directory (auto-discovered or provided as a configured path):
-
-1. **Direct files**: `extensions/*.ts` or `extensions/*.js`
-2. **Subdirectory with index**: `extensions/<name>/index.ts` or `index.js`
-3. **Subdirectory with package.json**: `extensions/<name>/package.json` containing `omp.extensions` or `pi.extensions`
-
-Example `package.json` manifest:
-
-```json
-{
-	"name": "my-extension-pack",
-	"omp": {
-		"extensions": ["./src/safety-gates.ts", "./src/custom-tools.ts"]
-	}
-}
-```
-
-Notes:
-
-- No recursion beyond one directory level. Use `package.json` manifests for nested layouts.
-- Extension discovery ignores dotfiles and `node_modules`.
-- `.gitignore`, `.ignore`, and `.fdignore` are honored for auto-discovered directories.
-
-### Extension Naming and Disabling
-
-Extension names are derived from the entry point path:
-
-- `extensions/foo.ts` → `foo`
-- `extensions/foo/index.ts` → `foo`
-
-To disable an extension module, add its ID to `disabledExtensions`:
-
-```yaml
-disabledExtensions:
-  - "extension-module:foo"
-```
-
-## Gemini-Style Extensions (gemini-extension.json)
-
-`gemini-extension.json` manifests are discovered in config roots under:
-
-```
-<root>/extensions/<name>/gemini-extension.json
-```
-
-Where `<root>` is one of `.omp`, `.pi`, `.gemini` (at both user and project level).
-
-These manifests describe MCP servers, tools, and context. They are parsed as data (not executed as TypeScript modules). If `name` is missing from the manifest, the directory name is used instead.