llm-cli-gateway 1.16.2 → 1.17.1

package/CHANGELOG.md

@@ -4,6 +4,48 @@ All notable changes to the llm-cli-gateway project.
 
 ## Unreleased
 
+## [1.17.1] - 2026-05-30 — Socket shell-access suppression
+
+Patch release updating the package's Socket policy for the reviewed gateway
+process-launching capability.
+
+### Changed
+
+- Suppressed Socket's `shellAccess` alert in `socket.yml` now that the
+  child-process surface is documented and release-audited.
+- Updated README Socket-alert wording so reviewers still get the bounded
+  shell-access rationale without seeing the same package alert on every release.
+
+## [1.17.0] - 2026-05-30 — upstream provider tracking
+
+Feature release adding repeatable upstream-provider contract tracking for the
+gateway's supported CLIs.
+
+### Added
+
+- Added provider-specific maintenance skills for Claude Code, Codex, Gemini,
+  Grok, and Mistral Vibe.
+- Added upstream source metadata to the CLI contract table and mirrored it into
+  `docs/upstream/provider-sources.dag.toml`.
+- Added `scripts/upstream-scan.mjs` plus `npm run upstream:contracts` and
+  `npm run upstream:scan` for offline contract checks and advisory live source
+  scans.
+- Added upstream source tests covering contract/TOML synchronization.
+
+### Changed
+
+- Pointed Claude Code tracking at the markdown changelog, Codex tracking at the
+  GitHub releases feed plus product changelog, Gemini tracking at the Gemini CLI
+  changelog plus GitHub releases, and Grok tracking at the markdown xAI release
+  notes.
+- Ignored local-only agent/worktree artifacts that should not enter source
+  control.
+
+### Fixed
+
+- Fixed the `maxTokens` request schema so token budgets no longer reuse the
+  `maxTurns` limit.
+
 ## [1.16.2] - 2026-05-29 — release formatting follow-up
 
 Patch release that keeps the Mistral Vibe CLI contract fixes from `1.16.1`

package/README.md

@@ -1176,7 +1176,7 @@ The gateway supports concurrent requests across different CLIs. Each request spa
 
 ### Socket alerts — context for reviewers
 
-If you're vetting `llm-cli-gateway` through [Socket](https://socket.dev/npm/package/llm-cli-gateway) or a similar supply-chain scanner, you'll see three behavioural alerts and some dependency-ownership alerts. They are accurate descriptions of what the package does and what it depends on; we've left them visible (not silenced in `socket.yml`) so you don't have to take our word for it. Here's the context for each:
+If you're vetting `llm-cli-gateway` through [Socket](https://socket.dev/npm/package/llm-cli-gateway) or a similar supply-chain scanner, you'll see behavioural alerts and some dependency-ownership alerts. They are accurate descriptions of what the package does and what it depends on. The reviewed `shellAccess` capability is suppressed in `socket.yml` to avoid a repeat finding on every release; the rationale remains documented here and in the package.
 
 | Alert                            | Where                                                                                                                                                                                            | Why it's bounded                                                                                                                                                                                                                                                                                                                                                                                     |
 | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

package/dist/index.d.ts

@@ -66,6 +66,7 @@ type GatewayLogger = typeof logger;
  * upper bound — no plausible single agent loop exceeds 10k turns or 10k USD.
  */
 export declare const MAX_TURNS_SCHEMA: z.ZodNumber;
+export declare const MAX_TOKENS_SCHEMA: z.ZodNumber;
 export declare const MAX_PRICE_SCHEMA: z.ZodNumber;
 /**
  * Slice λ: shared worktree directive for all 10 `*_request` / `*_request_async`

package/dist/index.js

@@ -242,6 +242,10 @@ const MCP_SERVER_ENUM = z.enum(CLAUDE_MCP_SERVER_NAMES);
  * upper bound — no plausible single agent loop exceeds 10k turns or 10k USD.
  */
 export const MAX_TURNS_SCHEMA = z.number().int().positive().safe().max(10_000);
+// Token budgets can legitimately exceed the agent-turn cap by orders of
+// magnitude. Keep a finite operational guardrail while avoiding the 10k turn
+// ceiling that would make large-context Vibe sessions unusable.
+export const MAX_TOKENS_SCHEMA = z.number().int().positive().safe().max(100_000_000);
 // `.min(1e-6)` keeps the value in JS's decimal-stringify range:
 // String(1e-6) === "0.000001" but String(1e-7) === "1e-7", which both
 // upstream CLIs would reject. 1µUSD per request is fine-grained enough
@@ -3826,7 +3830,7 @@ export function createGatewayServer(deps = {}) {
             .describe("Emit `--trust` so Vibe trusts the cwd for this invocation only (not persisted to trusted_folders.toml) and skips the interactive trust prompt (Phase 4 slice γ)."),
         maxTurns: MAX_TURNS_SCHEMA.optional().describe("Vibe `--max-turns N`: cap the agent-loop iteration count (programmatic mode only, Phase 4 slice δ). Bounded to safe integers ≤ 10000."),
         maxPrice: MAX_PRICE_SCHEMA.optional().describe("Vibe `--max-price DOLLARS`: interrupt the session when cumulative cost crosses this cap (programmatic mode only, Phase 4 slice δ). Bounded to finite values ≤ 10000 USD."),
-        maxTokens: MAX_TURNS_SCHEMA.optional().describe("Vibe `--max-tokens N`: cap cumulative prompt + completion tokens for the session (programmatic mode only). Bounded to safe integers ≤ 10000."),
+        maxTokens: MAX_TOKENS_SCHEMA.optional().describe("Vibe `--max-tokens N`: cap cumulative prompt + completion tokens for the session (programmatic mode only). Bounded to safe integers ≤ 100000000."),
         // Phase 4 slice ζ — Vibe working-directory + additional-dirs parity.
         workingDir: z
             .string()
@@ -4548,7 +4552,7 @@ export function createGatewayServer(deps = {}) {
                 .describe("Emit `--trust` so Vibe trusts the cwd for this invocation only (not persisted to trusted_folders.toml) and skips the interactive trust prompt (Phase 4 slice γ)."),
             maxTurns: MAX_TURNS_SCHEMA.optional().describe("Vibe `--max-turns N`: cap the agent-loop iteration count (programmatic mode only, Phase 4 slice δ). Bounded to safe integers ≤ 10000."),
             maxPrice: MAX_PRICE_SCHEMA.optional().describe("Vibe `--max-price DOLLARS`: interrupt the session when cumulative cost crosses this cap (programmatic mode only, Phase 4 slice δ). Bounded to finite values ≤ 10000 USD."),
-            maxTokens: MAX_TURNS_SCHEMA.optional().describe("Vibe `--max-tokens N`: cap cumulative prompt + completion tokens for the session (programmatic mode only). Bounded to safe integers ≤ 10000."),
+            maxTokens: MAX_TOKENS_SCHEMA.optional().describe("Vibe `--max-tokens N`: cap cumulative prompt + completion tokens for the session (programmatic mode only). Bounded to safe integers ≤ 100000000."),
             // Phase 4 slice ζ — Vibe working-directory + additional-dirs parity.
             workingDir: z
                 .string()

package/dist/upstream-contracts.d.ts

@@ -13,6 +13,43 @@ export interface CliFlagContract {
     pattern?: RegExp;
     description: string;
 }
+/**
+ * Pure upstream-tracking metadata for a provider CLI.
+ *
+ * IMPORTANT — non-duplication invariant: nothing here encodes mechanical
+ * behaviour. Flags, output modes, session/resume rules, permission modes,
+ * forbidden flags, env contracts, and positional limits live ONLY in the
+ * surrounding {@link CliContract} and are validated ONLY by
+ * {@link validateUpstreamCliArgs} / {@link validateUpstreamCliEnv}. The fields
+ * below are descriptive pointers used by the upstream changelog scanner
+ * (`scripts/upstream-scan.mjs`) and surfaced in the contract report — they
+ * never drive argv/env enforcement.
+ *
+ * `docs/upstream/provider-sources.dag.toml` mirrors `sourceUrls` and
+ * `watchCategories` for the scanner's offline scan plan; a unit test
+ * (`upstream-sources.test.ts`) asserts the TOML stays in sync with these
+ * fields so the two cannot drift. The TypeScript values here are authoritative;
+ * the TOML is scanner input only and is never consulted for contract
+ * enforcement.
+ */
+export interface CliUpstreamMetadata {
+    /** Canonical changelog / release-notes URLs the scanner fetches with --live. */
+    sourceUrls: readonly string[];
+    /** Distribution package identifier (npm package name, PyPI project, …). */
+    packageName?: string;
+    /** Source repository URL, when distinct from the changelog source. */
+    repo?: string;
+    /** Human-facing install / getting-started docs. */
+    installDocsUrl?: string;
+    /** Distribution channel the gateway expects the CLI to ship through. */
+    releaseChannel?: "npm" | "pypi" | "github-release" | "vendor";
+    /**
+     * Contract surfaces worth watching in upstream release notes (e.g. "flags",
+     * "output-formats", "session-resume"). Descriptive labels for the scanner and
+     * report ONLY — never a validation input.
+     */
+    watchCategories: readonly string[];
+}
 export interface CliContract {
     cli: CliType;
     executable: string;
@@ -31,6 +68,8 @@ export interface CliContract {
     resumeMaxPositionals?: number;
     resumeOnlyFlags?: readonly string[];
     resumeForbiddenFlags?: readonly string[];
+    /** Non-mechanical upstream-tracking metadata. See {@link CliUpstreamMetadata}. */
+    upstreamMetadata?: CliUpstreamMetadata;
 }
 export interface CliContractFixture {
     id: string;

package/dist/upstream-contracts.js

@@ -14,6 +14,13 @@ export const UPSTREAM_CLI_CONTRACTS = {
         cli: "claude",
         executable: "claude",
         upstream: "Claude Code CLI",
+        upstreamMetadata: {
+            sourceUrls: ["https://code.claude.com/docs/en/changelog.md"],
+            packageName: "@anthropic-ai/claude-code",
+            installDocsUrl: "https://code.claude.com/docs/en/overview",
+            releaseChannel: "npm",
+            watchCategories: ["flags", "output-formats", "permission-modes", "session-resume", "models"],
+        },
         helpArgs: [["--help"]],
         maxPositionals: 0,
         mcpTools: ["claude_request", "claude_request_async"],
@@ -197,6 +204,23 @@ export const UPSTREAM_CLI_CONTRACTS = {
         cli: "codex",
         executable: "codex",
         upstream: "OpenAI Codex CLI",
+        upstreamMetadata: {
+            sourceUrls: [
+                "https://github.com/openai/codex/releases",
+                "https://developers.openai.com/codex/changelog",
+            ],
+            packageName: "@openai/codex",
+            repo: "https://github.com/openai/codex",
+            installDocsUrl: "https://developers.openai.com/codex/cli",
+            releaseChannel: "npm",
+            watchCategories: [
+                "flags",
+                "sandbox-modes",
+                "approval-modes",
+                "session-resume",
+                "output-schema",
+            ],
+        },
         helpArgs: [
             ["exec", "--help"],
             ["exec", "resume", "--help"],
@@ -343,6 +367,17 @@ export const UPSTREAM_CLI_CONTRACTS = {
         cli: "gemini",
         executable: "gemini",
         upstream: "Google Gemini CLI",
+        upstreamMetadata: {
+            sourceUrls: [
+                "https://geminicli.com/docs/changelogs/",
+                "https://github.com/google-gemini/gemini-cli/releases",
+            ],
+            packageName: "@google/gemini-cli",
+            repo: "https://github.com/google-gemini/gemini-cli",
+            installDocsUrl: "https://geminicli.com/docs/",
+            releaseChannel: "npm",
+            watchCategories: ["flags", "approval-modes", "output-formats", "session-resume"],
+        },
         helpArgs: [["--help"]],
         maxPositionals: 0,
         mcpTools: ["gemini_request", "gemini_request_async"],
@@ -428,6 +463,12 @@ export const UPSTREAM_CLI_CONTRACTS = {
         cli: "grok",
         executable: "grok",
         upstream: "xAI Grok CLI",
+        upstreamMetadata: {
+            sourceUrls: ["https://docs.x.ai/developers/release-notes.md"],
+            installDocsUrl: "https://docs.x.ai/build/overview",
+            releaseChannel: "vendor",
+            watchCategories: ["flags", "permission-modes", "session-resume", "sandbox", "output-formats"],
+        },
         helpArgs: [["--help"]],
         maxPositionals: 0,
         mcpTools: ["grok_request", "grok_request_async"],
@@ -582,6 +623,14 @@ export const UPSTREAM_CLI_CONTRACTS = {
         cli: "mistral",
         executable: "vibe",
         upstream: "Mistral Vibe CLI",
+        upstreamMetadata: {
+            sourceUrls: ["https://github.com/mistralai/mistral-vibe/releases"],
+            packageName: "mistral-vibe",
+            repo: "https://github.com/mistralai/mistral-vibe",
+            installDocsUrl: "https://github.com/mistralai/mistral-vibe#installation",
+            releaseChannel: "pypi",
+            watchCategories: ["flags", "agent-modes", "session-logging", "output-formats", "env-model"],
+        },
         helpArgs: [["--help"]],
         maxPositionals: 0,
         mcpTools: ["mistral_request", "mistral_request_async"],
@@ -960,6 +1009,19 @@ export function buildUpstreamContractReport(options = {}) {
             {
                 executable: contract.executable,
                 upstream: contract.upstream,
+                // Pure metadata pointers (changelog URLs, package name, watch
+                // categories). Enriched from the CliContract — the single source of
+                // truth — so report consumers and the scanner read the same values.
+                upstreamMetadata: contract.upstreamMetadata
+                    ? {
+                        sourceUrls: contract.upstreamMetadata.sourceUrls,
+                        packageName: contract.upstreamMetadata.packageName ?? null,
+                        repo: contract.upstreamMetadata.repo ?? null,
+                        installDocsUrl: contract.upstreamMetadata.installDocsUrl ?? null,
+                        releaseChannel: contract.upstreamMetadata.releaseChannel ?? null,
+                        watchCategories: contract.upstreamMetadata.watchCategories,
+                    }
+                    : null,
                 command: contract.command ?? null,
                 helpArgs: contract.helpArgs,
                 mcpTools: contract.mcpTools,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-cli-gateway",
-  "version": "1.16.2",
+  "version": "1.17.1",
   "mcpName": "io.github.verivus-oss/llm-cli-gateway",
   "description": "MCP server providing unified access to Claude Code, Codex, Gemini, Grok, and Mistral Vibe CLIs with session management, retry logic, async job orchestration, durable job results, and cross-LLM validation.",
   "license": "MIT",
@@ -71,6 +71,8 @@
     "test:pg": "bash ./scripts/test-pg.sh",
     "test:all": "npm run test && npm run test:pg",
     "smoke:cache-control": "node docs/plans/slice-kappa-smoke-test.mjs",
+    "upstream:contracts": "node scripts/upstream-scan.mjs --contracts-check",
+    "upstream:scan": "node scripts/upstream-scan.mjs",
     "lint": "eslint src/**/*.ts",
     "lint:fix": "eslint src/**/*.ts --fix",
     "format": "prettier --write 'src/**/*.ts'",

package/socket.yml

@@ -2,11 +2,9 @@ version: 2
 
 # Socket alerts on llm-cli-gateway
 # ---------------------------------
-# This package intentionally triggers three of Socket's behavioural alerts.
-# We do NOT disable them — they are accurate descriptions of what the package
-# does, and silencing them would hide useful signal from anyone evaluating
-# this dependency. The rationale for each is documented inline below and in
-# detail under "Security Considerations" in README.md.
+# This package intentionally triggers behavioural alerts. They are accurate
+# descriptions of what the package does; the rationale for each is documented
+# inline below and in detail under "Security Considerations" in README.md.
 #
 #   networkAccess
 #     src/http-transport.ts opens an HTTP MCP transport (createServer/listen).
@@ -22,11 +20,37 @@ version: 2
 #     (SQLite, sessions.json) or explicit local CLI process I/O.
 #
 #   shellAccess
-#     src/executor.ts uses child_process.spawn(cmd, args, { ... }) with a
-#     fixed allow-list of CLI binaries (claude / codex / gemini / grok /
-#     vibe). shell:true is never set; arguments are passed as an array, so
-#     there is no shell interpolation path for user input. Spawning these
-#     CLIs is the entire purpose of the package.
+#     This alert fires on every module that imports node:child_process, and
+#     because spawning provider CLIs and git is the entire purpose of the package
+#     it is a reviewed capability description, not a finding. As of v1.17.1 this
+#     specific reviewed alert is suppressed via `issueRules.shellAccess: false`
+#     to avoid noisy repeat findings on every release.
+#
+#     INVARIANT enforced across ALL sites below: arguments are always passed
+#     as an array and `shell: true` is NEVER set, so there is no shell
+#     interpolation path for user input. `scripts/release-security-audit.sh`
+#     guards the dynamic-execution surface. When you add a new module that
+#     imports child_process, add it to this list so the alert location set
+#     stays documented instead of reading like a regression.
+#
+#     Current production child_process sites (dist/*.js mirrors of src/*.ts):
+#       - src/executor.ts          spawn(cmd, args) — provider CLI allow-list
+#                                   (claude / codex / gemini / grok / vibe).
+#       - src/worktree-manager.ts  spawn("git", args) — gateway-owned git
+#                                   worktree lifecycle (add / list / prune /
+#                                   remove / branch -D).
+#       - src/cli-updater.ts       spawnSync(cmd, args) — provider CLI version
+#                                   + upgrade checks.
+#       - src/provider-status.ts   spawnSync(cmd, args) — provider login-status
+#                                   probe.
+#       - src/upstream-contracts.ts spawnSync(cmd, ["--help"]) — optional
+#                                   installed-CLI contract probe.
+#       - src/endpoint-exposure.ts spawnSync(process.execPath, ["-e", …]) —
+#                                   out-of-process HEAD reachability probe
+#                                   (opt-in via the start:http path only).
+#       - src/async-job-manager.ts imports the ChildProcess *type* only for
+#                                   job lifecycle tracking; it spawns via
+#                                   executor.ts (spawnCliProcess), not directly.
 #
 #   usesEval
 #     Not in our source. Transitive via @modelcontextprotocol/sdk → ajv@8,
@@ -40,16 +64,6 @@ version: 2
 #     gateway does not call db.pragma() from production code; SQLite setup
 #     uses fixed literal db.exec("PRAGMA ...") statements, and the release
 #     security audit fails future production `.pragma()` calls.
-#
-#   ioredis obfuscated code / base64 strings
-#     Socket may flag ioredis@5.10.1 built/constants/TLSProfiles.js because it
-#     contains base64-looking strings. This is a reviewed false positive: the
-#     strings are PEM-encoded Redis Cloud TLS CA certificates. The file exports
-#     static TLS profile data only; it contains no decoder loop, dynamic eval,
-#     network call, or hidden execution path. The same file is byte-for-byte
-#     identical in ioredis@5.9.2. ioredis is not installed by the default
-#     production dependency tree; it is an optional peer for PostgreSQL/Redis
-#     session storage and a pinned dev dependency for tests.
 
 issueRules:
   # Defaults from Socket. Listed explicitly so future contributors see what
@@ -60,6 +74,7 @@ issueRules:
   installScripts: true
   telemetry: true
   hasNativeCode: true            # better-sqlite3 — known and expected
+  shellAccess: false             # reviewed gateway capability; see rationale above
   shellScriptOverride: true
   gitDependency: true
   httpDependency: true