@nick3/copilot-api 1.3.1 → 1.3.5

package/README.md

@@ -52,9 +52,9 @@ Compared with routing everything through plain Chat Completions compatibility, t
 - **Flexible Authentication**: Authenticate interactively or provide a GitHub token directly, suitable for CI/CD environments.
 - **Support for Different Account Types**: Works with individual, business, and enterprise GitHub Copilot plans.
 - **Multi-Account Support**: Use multiple GitHub Copilot accounts with automatic routing: premium models use accounts in order and fall back on quota exhaustion; free models are distributed round-robin across accounts by default (configurable in config.json).
-- **Opencode OAuth Support**: Use opencode GitHub Copilot authentication by setting `COPILOT_API_OAUTH_APP=opencode` environment variable.
-- **GitHub Enterprise Support**: Connect to GHE.com by setting `COPILOT_API_ENTERPRISE_URL` environment variable (e.g., `company.ghe.com`).
-- **Custom Data Directory**: Change the default data directory (where tokens and config are stored) by setting `COPILOT_API_HOME` environment variable.
+- **Opencode OAuth Support**: Use opencode GitHub Copilot authentication by setting `COPILOT_API_OAUTH_APP=opencode` environment variable or using `--oauth-app=opencode` command line option.
+- **GitHub Enterprise Support**: Connect to GHE.com by setting `COPILOT_API_ENTERPRISE_URL` environment variable (e.g., `company.ghe.com`) or using `--enterprise-url=company.ghe.com` command line option.
+- **Custom Data Directory**: Change the default data directory (where tokens and config are stored) by setting `COPILOT_API_HOME` environment variable or using `--api-home=/path/to/dir` command line option.
 - **Multi-Provider Anthropic Proxy Routes**: Add global provider configs and call external Anthropic-compatible APIs via `/:provider/v1/messages` and `/:provider/v1/models`.
 
 ## Better Agent Semantics
@@ -237,6 +237,16 @@ Copilot API now uses a subcommand structure with these main commands:
 
 ## Command Line Options
 
+### Global Options
+
+The following options can be used with any subcommand. When passing them before the subcommand, use the `--key=value` form:
+
+| Option            | Description                                            | Default | Alias |
+| ----------------- | ------------------------------------------------------ | ------- | ----- |
+| --api-home        | Path to the API home directory (sets COPILOT_API_HOME) | none    | none  |
+| --oauth-app       | OAuth app identifier (sets COPILOT_API_OAUTH_APP)      | none    | none  |
+| --enterprise-url  | Enterprise URL for GitHub (sets COPILOT_API_ENTERPRISE_URL) | none | none |
+
 ### Start Command Options
 
 The following command line options are available for the `start` command:
@@ -315,14 +325,15 @@ The `<target>` can be either the account ID (GitHub username) or a 1-based index
       "gpt-5-mini": "<built-in exploration prompt>",
       "gpt-5.3-codex": "<built-in commentary prompt>",
       "gpt-5.4": "<built-in commentary prompt>"
-	    },
-	    "smallModel": "gpt-5-mini",
-	    "freeModelLoadBalancing": true,
-	    "responsesApiContextManagementModels": [],
-	    "modelReasoningEfforts": {
-	      "gpt-5-mini": "low",
-	      "gpt-5.3-codex": "xhigh",
-	      "gpt-5.4": "xhigh"
+    "useMessagesApi": true
+    },
+    "smallModel": "gpt-5-mini",
+    "freeModelLoadBalancing": true,
+    "responsesApiContextManagementModels": [],
+    "modelReasoningEfforts": {
+      "gpt-5-mini": "low",
+      "gpt-5.3-codex": "xhigh",
+      "gpt-5.4": "xhigh"
     },
     "modelAliases": {
       "fast": { "target": "gpt-5-mini", "allowOriginal": false },
@@ -331,29 +342,31 @@ The `<target>` can be either the account ID (GitHub username) or a 1-based index
     "allowOriginalModelNamesForAliases": false,
     "useFunctionApplyPatch": true,
     "forceAgent": false,
-    "compactUseSmallModel": true
+    "compactUseSmallModel": true,
+    "useMessagesApi": true
   }
   ```
 - **auth.apiKeys:** API keys used for request authentication. Supports multiple keys for rotation. Requests can authenticate with either `x-api-key: <key>` or `Authorization: Bearer <key>`. If empty or omitted, authentication is disabled.
-	- **extraPrompts:** Map of `model -> prompt` appended to the first system prompt when translating Anthropic-style requests to Copilot. Use this to inject guardrails or guidance per model. Missing default entries are auto-added without overwriting your custom prompts. The built-in prompts for `gpt-5.3-codex` and `gpt-5.4` enable phase-aware commentary, which lets the model emit a short user-facing progress update before tools or deeper reasoning.
-	- **providers:** Global upstream provider map. Each provider key (for example `custom`) becomes a route prefix (`/custom/v1/messages`). Currently only `type: "anthropic"` is supported.
-	  - `enabled` defaults to `true` if omitted.
-	  - `baseUrl` should be provider API base URL without trailing `/v1/messages`.
-	  - `apiKey` is used as upstream `x-api-key`.
-	  - `models` (optional): Per-model configuration map. Each key is a model ID (matching the model name in requests), and the value is:
-	    - `temperature` (optional): Default temperature value used when the request does not specify one.
-	    - `topP` (optional): Default top_p value used when the request does not specify one.
-	    - `topK` (optional): Default top_k value used when the request does not specify one.
-	- **responsesApiContextManagementModels:** List of model IDs that should receive Responses API `context_management` compaction instructions. Use this when a model supports server-side context management and you want the proxy to keep only the latest compaction carrier on follow-up turns.
-	- **smallModel:** Fallback model used for tool-less warmup messages, compact/background requests, and other short housekeeping turns (for example from Claude Code or OpenCode) to avoid spending premium requests; defaults to `gpt-5-mini`. If original names are blocked and this points to an aliased target, it resolves to the preferred alias.
-	- **freeModelLoadBalancing:** Enable round-robin routing for free-model requests across multiple accounts. Defaults to `true`. Set to `false` to route free-model requests sequentially (same ordering strategy as premium models).
-	- **apiKey (deprecated):** Legacy single-key field kept for migration compatibility. Prefer `auth.apiKeys`. When `auth.apiKeys` is empty, the server falls back to `COPILOT_API_KEY` and then `apiKey`.
-	- **modelReasoningEfforts:** Per-model `reasoning.effort` sent to the Copilot Responses API. Allowed values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. If a model isn’t listed, `high` is used by default.
-	- **modelAliases:** Map of `alias -> { target, allowOriginal? }` (legacy string values are still accepted). Alias keys are normalized (trim + lowercase) and must be non-empty; aliases cannot map to themselves (case-insensitive), and conflicting normalized aliases are rejected. `allowOriginal` overrides the global default per alias. If multiple aliases map to the same target, original names are allowed when any alias sets `allowOriginal: true` (allow-wins). Admin UI/API rejects blocked keys (`__proto__`, `constructor`, `prototype`). Aliases can be used in downstream requests.
-	- **allowOriginalModelNamesForAliases:** Global default for aliases that omit `allowOriginal`. When `false` (default), targets are blocked unless an alias explicitly allows them; when `true`, targets are allowed unless all aliases explicitly block them.
+- **extraPrompts:** Map of `model -> prompt` appended to the first system prompt when translating Anthropic-style requests to Copilot. Use this to inject guardrails or guidance per model. Missing default entries are auto-added without overwriting your custom prompts. The built-in prompts for `gpt-5.3-codex` and `gpt-5.4` enable phase-aware commentary, which lets the model emit a short user-facing progress update before tools or deeper reasoning.
+- **providers:** Global upstream provider map. Each provider key (for example `custom`) becomes a route prefix (`/custom/v1/messages`). Currently only `type: "anthropic"` is supported.
+  - `enabled` defaults to `true` if omitted.
+  - `baseUrl` should be provider API base URL without trailing `/v1/messages`.
+  - `apiKey` is used as upstream `x-api-key`.
+  - `models` (optional): Per-model configuration map. Each key is a model ID (matching the model name in requests), and the value is:
+    - `temperature` (optional): Default temperature value used when the request does not specify one.
+    - `topP` (optional): Default top_p value used when the request does not specify one.
+    - `topK` (optional): Default top_k value used when the request does not specify one.
+- **responsesApiContextManagementModels:** List of model IDs that should receive Responses API `context_management` compaction instructions. Use this when a model supports server-side context management and you want the proxy to keep only the latest compaction carrier on follow-up turns.
+- **smallModel:** Fallback model used for tool-less warmup messages, compact/background requests, and other short housekeeping turns (for example from Claude Code or OpenCode) to avoid spending premium requests; defaults to `gpt-5-mini`. If original names are blocked and this points to an aliased target, it resolves to the preferred alias.
+- **freeModelLoadBalancing:** Enable round-robin routing for free-model requests across multiple accounts. Defaults to `true`. Set to `false` to route free-model requests sequentially (same ordering strategy as premium models).
+- **apiKey (deprecated):** Legacy single-key field kept for migration compatibility. Prefer `auth.apiKeys`. When `auth.apiKeys` is empty, the server falls back to `COPILOT_API_KEY` and then `apiKey`.
+- **modelReasoningEfforts:** Per-model `reasoning.effort` sent to the Copilot Responses API. Allowed values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. If a model isn’t listed, `high` is used by default.
+- **modelAliases:** Map of `alias -> { target, allowOriginal? }` (legacy string values are still accepted). Alias keys are normalized (trim + lowercase) and must be non-empty; aliases cannot map to themselves (case-insensitive), and conflicting normalized aliases are rejected. `allowOriginal` overrides the global default per alias. If multiple aliases map to the same target, original names are allowed when any alias sets `allowOriginal: true` (allow-wins). Admin UI/API rejects blocked keys (`__proto__`, `constructor`, `prototype`). Aliases can be used in downstream requests.
+- **allowOriginalModelNamesForAliases:** Global default for aliases that omit `allowOriginal`. When `false` (default), targets are blocked unless an alias explicitly allows them; when `true`, targets are allowed unless all aliases explicitly block them.
 - **useFunctionApplyPatch:** When `true` (default), `POST /v1/responses` converts a `tools` entry with `{ "type": "custom", "name": "apply_patch" }` into an OpenAI-style `function` tool (with a parameter schema) for upstream compatibility. Set to `false` to leave custom tools untouched.
 - **forceAgent:** When `true`, `POST /v1/responses` treats a request as agent-initiated if **any** input item has `role: "assistant"`. When `false` (default), only the **last** input item is checked.
 - **compactUseSmallModel:** When `true`, detected "compact" requests (e.g., from Claude Code or opencode compact mode) will automatically use the configured `smallModel` to avoid consuming premium usage for short/background tasks. Defaults to `true`.
+- **useMessagesApi:** When `true` (default), Claude-family models that support Copilot's native `/v1/messages` endpoint may use the Messages API path. Set to `false` to skip the Messages API candidate and fall back to `/responses` (if supported) or `/chat/completions`.
 
 Edit this file to customize prompts or swap in your own fast model. If you edit it manually, restart the server (or call `GET /api/admin/config`) so the cached config is refreshed. Changes made through the Admin UI/API are validated, written to disk, and applied immediately; unknown keys are rejected.
 
@@ -530,6 +543,18 @@ npx @nick3/copilot-api@latest start --proxy-env
 
 # Use opencode GitHub Copilot authentication
 COPILOT_API_OAUTH_APP=opencode npx @nick3/copilot-api@latest start
+
+# Set custom API home directory via command line
+npx @nick3/copilot-api@latest --api-home=/path/to/custom/dir start
+
+# Use GitHub Enterprise via command line
+npx @nick3/copilot-api@latest --enterprise-url=company.ghe.com start
+
+# Use opencode OAuth via command line
+npx @nick3/copilot-api@latest --oauth-app=opencode start
+
+# Combine multiple global options
+npx @nick3/copilot-api@latest --api-home=/custom/path --oauth-app=opencode --enterprise-url=company.ghe.com start
 ```
 
 ### Opencode OAuth Authentication
@@ -757,12 +782,14 @@ Here is an example `.claude/settings.json` file:
 }
 ```
 
-### CLAUDE.md / AGENTS.md (Optional)
+### CLAUDE.md or AGENTS.md Recommended Content
 
-If you're using Claude Code (or another agent runner) and want stricter “ask before acting” behavior, you may choose to add rules like:
+Please include the following in `CLAUDE.md` or `AGENTS.md`:
 
-- Prefer using the runner's dedicated question tool for user-facing questions.
-- Ask the user to confirm completion before ending the task.
+```
+- Prohibited from directly asking questions to users, MUST use question tool.
+- Once you can confirm that the task is complete, MUST use question tool to make user confirm. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again, after try again, MUST use question tool to make user confirm again.
+```
 
 You can find more options here: [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)
 

package/dist/account-DhQb2A6q.js

@@ -0,0 +1,17 @@
+//#region src/lib/types/account.ts
+const ACCOUNT_TYPE_VALUES = [
+	"individual",
+	"business",
+	"enterprise"
+];
+function isAccountType(value) {
+	return typeof value === "string" && ACCOUNT_TYPE_VALUES.includes(value);
+}
+function parseAccountType(value) {
+	if (!isAccountType(value)) throw new Error(`Invalid account type: ${String(value)}. Valid values: ${ACCOUNT_TYPE_VALUES.join(", ")}`);
+	return value;
+}
+
+//#endregion
+export { parseAccountType };
+//# sourceMappingURL=account-DhQb2A6q.js.map

package/dist/account-DhQb2A6q.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"account-DhQb2A6q.js","names":["ACCOUNT_TYPE_VALUES: ReadonlyArray<AccountType>"],"sources":["../src/lib/types/account.ts"],"sourcesContent":["import type { ModelsResponse } from \"~/services/copilot/get-models\"\n\n/**\n * Account type for GitHub Copilot subscription.\n */\nexport type AccountType = \"individual\" | \"business\" | \"enterprise\"\n\nexport const ACCOUNT_TYPE_VALUES: ReadonlyArray<AccountType> = [\n  \"individual\",\n  \"business\",\n  \"enterprise\",\n]\n\nexport function isAccountType(value: unknown): value is AccountType {\n  return (\n    typeof value === \"string\"\n    && (ACCOUNT_TYPE_VALUES as ReadonlyArray<string>).includes(value)\n  )\n}\n\nexport function parseAccountType(value: unknown): AccountType {\n  if (!isAccountType(value)) {\n    throw new Error(\n      `Invalid account type: ${String(value)}. Valid values: ${ACCOUNT_TYPE_VALUES.join(\n        \", \",\n      )}`,\n    )\n  }\n  return value\n}\n\n/**\n * Metadata for a registered account, stored in the registry file.\n */\nexport interface AccountMeta {\n  /** GitHub login (username) */\n  id: string\n  /** Account subscription type */\n  accountType: AccountType\n  /** Timestamp when the account was added */\n  addedAt: number\n}\n\n/**\n * Registry file structure for storing account metadata.\n */\nexport interface AccountRegistry {\n  /** Schema version for future migrations */\n  version: 1\n  /** Ordered list of accounts (order = priority) */\n  accounts: Array<AccountMeta>\n}\n\n/**\n * Runtime state for an account, including tokens and quota information.\n */\nexport interface AccountRuntime extends AccountMeta {\n  /** GitHub personal access token */\n  githubToken: string\n  /** Copilot API token (obtained from GitHub) */\n  copilotToken?: string\n  /** VS Code version for API headers */\n  vsCodeVersion?: string\n  /** Cached available models for this account */\n  models?: ModelsResponse\n  /** Timestamp of last models fetch */\n  lastModelsFetch?: number\n  /** Whether models refresh is in progress */\n  isRefreshingModels?: boolean\n  /** Promise for an in-flight models refresh */\n  modelsRefreshPromise?: Promise<void>\n  /** Total premium interactions quota entitlement */\n  premiumEntitlement?: number\n  /** Remaining premium interactions quota */\n  premiumRemaining?: number\n  /** Reserved premium interaction units for in-flight requests */\n  premiumReserved?: number\n  /** Internal reservation map for idempotent release */\n  premiumReservations?: Map<symbol, number>\n  /** Whether this account has unlimited quota */\n  unlimited?: boolean\n  /** Whether this account allows overage billing (enterprise feature) */\n  overagePermitted?: boolean\n  /** Timestamp of last quota fetch */\n  lastQuotaFetch?: number\n  /** Token refresh timer reference */\n  refreshTimer?: ReturnType<typeof setInterval>\n  /** Whether this account has failed (e.g., 401 error) */\n  failed?: boolean\n  /** Failure reason if failed */\n  failureReason?: string\n  /** Whether quota refresh is in progress (prevents concurrent refreshes) */\n  isRefreshingQuota?: boolean\n  /** Promise for an in-flight quota refresh (allows concurrent callers to await the same refresh) */\n  quotaRefreshPromise?: Promise<void>\n}\n\n/**\n * Context required for making API calls on behalf of an account.\n * This is a subset of AccountRuntime used by service functions.\n */\nexport interface AccountContext {\n  /** GitHub personal access token */\n  githubToken: string\n  /** Copilot API token */\n  copilotToken?: string\n  /** Account subscription type */\n  accountType: AccountType\n  /** VS Code version for API headers */\n  vsCodeVersion?: string\n}\n"],"mappings":";AAOA,MAAaA,sBAAkD;CAC7D;CACA;CACA;CACD;AAED,SAAgB,cAAc,OAAsC;AAClE,QACE,OAAO,UAAU,YACb,oBAA8C,SAAS,MAAM;;AAIrE,SAAgB,iBAAiB,OAA6B;AAC5D,KAAI,CAAC,cAAc,MAAM,CACvB,OAAM,IAAI,MACR,yBAAyB,OAAO,MAAM,CAAC,kBAAkB,oBAAoB,KAC3E,KACD,GACF;AAEH,QAAO"}