Merge upstream main (v0.25.0) into sync branch and preserve fork customizations

.env.example

@@ -33,6 +33,12 @@
 #     ANTHROPIC_API_KEY=sk-ant-your-key-here
 #     ANTHROPIC_MODEL=claude-sonnet-4-5              (optional)
 #     ANTHROPIC_BASE_URL=https://api.anthropic.com   (optional)
+#     ANTHROPIC_AUTH_TOKEN=your-provider-token       (custom Bearer endpoints)
+#
+#   Option 1b — Custom Anthropic-compatible API (Bearer auth):
+#     ANTHROPIC_BASE_URL=https://your-provider.example
+#     ANTHROPIC_AUTH_TOKEN=your-provider-token
+#     ANTHROPIC_MODEL=your-model-name
 #
 #   Option 2 — OpenAI:
 #     CLAUDE_CODE_USE_OPENAI=1
@@ -175,6 +181,8 @@ ANTHROPIC_API_KEY=sk-ant-your-key-here
 # -----------------------------------------------------------------------------
 # CLAUDE_CODE_USE_OPENAI=1
 # OPENAI_API_KEY=sk-your-key-here
+# Optional: rotate across multiple OpenAI-compatible API keys on auth/quota/rate-limit failures.
+# OPENAI_API_KEYS=sk-key-a,sk-key-b
 # OPENAI_MODEL=gpt-4o
 # For DeepSeek, set:
 # OPENAI_BASE_URL=https://api.deepseek.com/v1
@@ -192,13 +200,33 @@ ANTHROPIC_API_KEY=sk-ant-your-key-here
 # For Hicap, use the OpenAI-compatible route flag above and set:
 # HICAP_API_KEY=your-hicap-key-here
 # OPENAI_BASE_URL=https://api.hicap.ai/v1
-# OPENAI_MODEL=claude-opus-4.7
+# OPENAI_MODEL=claude-opus-4.8
+# For AI/ML API, the key alone enables the OpenAI-compatible route:
+# AIMLAPI_API_KEY=your-aimlapi-key-here
+# OPENAI_BASE_URL=https://api.aimlapi.com/v1
+# OPENAI_MODEL=gpt-4o
 
 # Use a custom OpenAI-compatible endpoint (optional — defaults to api.openai.com)
 # OPENAI_BASE_URL=https://api.openai.com/v1
-# Choose the OpenAI-compatible API surface (optional — defaults to chat_completions)
-# Supported: chat_completions, responses
+# Choose the OpenAI-compatible API surface (optional).
+# Supported: chat_completions, responses, responses_compat
+# Left unset, GPT-5.4/5.5/5.6 models (mini/nano variants excluded) on
+# api.openai.com or Azure OpenAI are auto-routed to responses (they reject
+# function tools + reasoning_effort on chat_completions); everything else
+# defaults to chat_completions. Set this to override: an explicit
+# chat_completions wins over the model auto-detection, but a provider
+# catalog's requiredApiFormat still takes precedence over it. GPT-5.6 omits
+# reasoning effort on this fallback because chat_completions rejects it with tools.
 # OPENAI_API_FORMAT=chat_completions
+# Force Azure-style URL and api-key-header handling for
+# custom or private Azure endpoints whose hostname would not otherwise match
+# (APIM-fronted, private link). Note: this also widens the GPT-5.4/5.5/5.6
+# responses auto-route above to ANY base URL — do not set it against gateways
+# that lack /v1/responses.
+# On Azure, OPENAI_MODEL is your deployment name; if it is not the model id
+# (e.g. production-coding), the model-name auto-route cannot recognize it —
+# set OPENAI_API_FORMAT=responses explicitly for gpt-5.4/5.5/5.6 deployments.
+# OPENAI_AZURE_STYLE=1
 # Choose a custom auth header for OpenAI-compatible providers (optional).
 # Authorization defaults to Bearer; custom headers default to the raw API key.
 # Set OPENAI_AUTH_HEADER_VALUE when the header value differs from OPENAI_API_KEY.
@@ -249,6 +277,7 @@ ANTHROPIC_API_KEY=sk-ant-your-key-here
 # OPENAI_BASE_URL=http://localhost:11434/v1
 # OPENAI_API_KEY=ollama
 # OPENAI_MODEL=llama3.2
+# OPENCLAUDE_OLLAMA_NUM_CTX=32768              — request-level Ollama context window
 
 # -----------------------------------------------------------------------------
 # Option 6: LM Studio (local models)
@@ -350,6 +379,34 @@ ANTHROPIC_API_KEY=sk-ant-your-key-here
 #   OPENAI_MODEL=accounts/fireworks/models/llama-v3p1-70b-instruct
 
 
+# -----------------------------------------------------------------------------
+# Option 13: LongCat
+# -----------------------------------------------------------------------------
+# LongCat is Meituan's OpenAI-compatible API for LongCat-2.0.
+# Get your API key from https://longcat.chat/platform/api_keys
+# Docs: https://longcat.chat/platform/docs/
+#
+#   CLAUDE_CODE_USE_OPENAI=1
+#   LONGCAT_API_KEY=your-longcat-key-here
+#   OPENAI_BASE_URL=https://api.longcat.chat/openai/v1
+#   OPENAI_MODEL=LongCat-2.0
+#
+# Or run: openclaude --provider longcat
+# Or configure interactively with /provider
+
+
+# -----------------------------------------------------------------------------
+# Option 14: ClinePass
+# -----------------------------------------------------------------------------
+# ClinePass is an AI model gateway with usage limits (5hr, weekly, monthly).
+# Get your API key from https://app.cline.bot/dashboard/subscription?personal=true
+# Models include DeepSeek, Qwen, GLM, Kimi, MiMo, and MiniMax.
+#
+#   CLINE_API_KEY=your-cline-api-key-here
+#   CLINE_API_MODEL=cline-pass/deepseek-v4-flash   (optional, default)
+#
+# Usage limits are displayed via /usage command.
+
 # =============================================================================
 # OPTIONAL TUNING
 # =============================================================================
@@ -398,8 +455,15 @@ ANTHROPIC_API_KEY=sk-ant-your-key-here
 # Turn on whichever audience you're debugging; both can run together.
 # OPENCLAUDE_LOG_TOKEN_USAGE=verbose
 
-# Custom timeout for API requests in milliseconds (default: varies)
-# API_TIMEOUT_MS=60000
+# Time-to-response-headers deadline for OpenAI-compatible API requests
+# in milliseconds (default: 600000, or 10 minutes). Use a safe positive
+# integer; invalid values use the default and values above 2147483647 are capped.
+# This runtime setting must be exported from your shell or launcher; the
+# provider env-file loader intentionally ignores runtime/debug knobs.
+# This covers generic OpenAI-compatible requests, direct GitHub Copilot
+# Responses, and Copilot chat-to-Responses fallback requests. First-party
+# Codex OAuth Responses and the Anthropic SDK retain their existing handling.
+# API_TIMEOUT_MS=600000
 
 # Enable debug logging
 # CLAUDE_DEBUG=1
@@ -478,6 +542,7 @@ ANTHROPIC_API_KEY=sk-ant-your-key-here
 # you must explicitly set WEB_SEARCH_PROVIDER=custom.
 #
 # WEB_SEARCH_PROVIDER=auto
+# WEB_SEARCH_TIMEOUT_SEC=15                  — built-in search provider timeout in seconds (default 15)
 
 # ── Built-in custom API presets ─────────────────────────────────────
 #
@@ -512,7 +577,7 @@ ANTHROPIC_API_KEY=sk-ant-your-key-here
 # The custom provider enforces security guardrails by default.
 # Override these only if you understand the risks.
 #
-# WEB_CUSTOM_TIMEOUT_SEC=15                  — request timeout in seconds (default 15)
+# WEB_CUSTOM_TIMEOUT_SEC=120                 — request timeout in seconds (default 120)
 # WEB_CUSTOM_MAX_BODY_KB=300                 — max POST body size in KB (default 300)
 # WEB_CUSTOM_ALLOW_ARBITRARY_HEADERS=false   — set "true" to use non-standard headers
 # WEB_CUSTOM_ALLOW_HTTP=false                — set "true" to allow http:// URLs

.gitattributes

@@ -59,6 +59,7 @@ CODE_OF_CONDUCT* text
 *.xml text
 *.csv text
 *.sql text
+*.scm text eol=lf
 
 # Graphics (binary)
 *.png binary

.github/workflows/install-hygiene.yml

@@ -0,0 +1,51 @@
+# Daily zero-warning-install watch on the PUBLISHED package.
+#
+# The published tarball ships no lockfile, so even with exact-pinned direct
+# dependencies the registry can drift under us after a release: a transitive
+# dependency gets deprecated (npm prints the deprecation on every user
+# install), a platform-specific optional package (@vscode/ripgrep-*) changes,
+# or a new npm version alters behavior. None of that touches a file in this
+# repo, so no PR or release gate can catch it — only re-verifying the real
+# `npm install -g @gitlawb/openclaude@latest` against the live registry does.
+#
+# The OS matrix matters: each platform resolves a different ripgrep optional
+# package, so a Linux-only check is blind to what macOS/Windows users install.
+name: Install hygiene
+
+on:
+  schedule:
+    - cron: '17 6 * * *' # daily, off the top-of-hour rush
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  verify-published-install:
+    name: ${{ matrix.os }} / Node ${{ matrix.node-version }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        node-version: [22, 24]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Set up Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - name: Set up Bun
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+        with:
+          bun-version-file: .bun-version
+
+      # The verify script only uses node builtins + scripts/externalsValidation
+      # (relative import) — no bun install needed, keeping the matrix cheap.
+      - name: Verify published package installs clean
+        run: bun run scripts/verify-clean-install.ts --published

.github/workflows/pr-checks.yml

@@ -12,6 +12,9 @@ permissions:
 jobs:
   smoke-and-tests:
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [22, "24.11.x"]
 
     steps:
       - name: Check out repository
@@ -22,32 +25,19 @@ jobs:
       - name: Set up Node.js
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
-          node-version: 22
+          node-version: ${{ matrix.node-version }}
 
       - name: Set up Bun
         uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
         with:
           bun-version-file: .bun-version
 
-      - name: Set up Python
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
-        with:
-          python-version: "3.12"
-          cache: "pip"
-          cache-dependency-path: python/requirements.txt
-
       - name: Install dependencies
         run: bun install --frozen-lockfile
 
       - name: Smoke and full unit test suite
         run: bun run check
 
-      - name: Install Python test dependencies
-        run: python -m pip install -r python/requirements.txt
-
-      - name: Python unit tests
-        run: python -m pytest -q python/tests
-
       - name: Suspicious PR intent scan
         env:
           PR_SCAN_BASE: ${{ github.event_name == 'pull_request' && github.event.pull_request.base.sha || 'origin/main' }}

.github/workflows/release.yml

@@ -29,9 +29,50 @@ jobs:
           token: ${{ secrets.GITHUB_TOKEN }}
           release-type: node
 
+  # Zero-warning install gate: pack the release tag and install it globally in
+  # a sandbox (cold + upgrade scenarios) on the supported Node floor (22 →
+  # npm 10) and current (24 → npm 11), whose warning output differs. Publish
+  # is blocked unless the real `npm install -g` experience is clean.
+  install-verify:
+    name: Verify clean npm install (Node ${{ matrix.node-version }})
+    needs: release-please
+    if: ${{ needs.release-please.outputs.release_created == 'true' }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version: [22, 24]
+    steps:
+      - name: Checkout release tag
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          ref: ${{ needs.release-please.outputs.tag_name }}
+          persist-credentials: false
+
+      - name: Set up Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - name: Set up Bun
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+        with:
+          bun-version-file: .bun-version
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build
+        run: bun run build
+
+      - name: Verify zero-warning global install
+        run: bun run install:verify
+
   publish-npm:
     name: Publish to npm
-    needs: release-please
+    needs: [release-please, install-verify]
     if: ${{ needs.release-please.outputs.release_created == 'true' }}
     runs-on: ubuntu-latest
     environment: release
@@ -68,8 +109,12 @@ jobs:
       - name: Smoke test
         run: bun run smoke
 
-      - name: Dry-run package
-        run: npm pack --dry-run
+      # Final install-hygiene gate on the publishing machine itself (the
+      # install-verify job covered Node 22/24 already); packs with
+      # --ignore-scripts to reuse the dist/ built above. Supersedes the old
+      # `npm pack --dry-run` (contents are asserted inside the verify).
+      - name: Verify zero-warning global install
+        run: bun run install:verify
 
       - name: Clear token auth for trusted publishing
         run: |

.gitignore

@@ -25,6 +25,7 @@ __pycache__/
 agent.log
 plan/
 .tmp
+.tmp-*
 temp_reference/
 
 # Added by ggshield

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.19.0"
+  ".": "0.25.0"
 }

AGENTS.md

@@ -23,7 +23,6 @@ The installed CLI runs on Node.js `>=22.0.0`. Bun is used for source builds, scr
 - React + Ink for terminal UI.
 - Bun lockfile and Bun scripts for development workflows.
 - Node runtime for the built CLI.
-- Python exists for legacy/local-provider helper code. Do not add new Python code or expand Python-based features unless a maintainer explicitly approves that direction.
 
 Common libraries and patterns:
 
@@ -44,7 +43,6 @@ Common libraries and patterns:
 - `src/tasks/` - local, remote, workflow, and monitor task handling.
 - `docs/integrations/` - provider integration guidance.
 - `web/` - documentation website.
-- `python/` - legacy/local-provider helper code and tests; maintain existing code here, but prefer TypeScript for new implementation.
 
 ## Validation
 
@@ -69,12 +67,6 @@ bun run test:provider
 bun run test:provider-recommendation
 ```
 
-Python checks, only when touching existing Python helper code:
-
-```bash
-python -m pytest -q python/tests
-```
-
 Web checks, when touching `web/`:
 
 ```bash