@vedmalex/ai-connect 0.2.0 → 0.4.0

package/README.md

@@ -5,7 +5,7 @@
 It models routes as `provider + transport + account + credential + model`, so one client can combine:
 
 - direct APIs for `OpenAI`, `Anthropic`, and `Gemini`
-- local-only ACP harness routes for `Claude Code`, `Codex`, and `Gemini`
+- local-only ACP harness routes for `Claude Code` and `Codex`
 - key rotation, account rotation, cooldowns, retries, and fallback chains
 - portable file, PDF document, and image inputs across direct API and ACP paths
 - cooperative cancellation, pause-with-partial, and per-operation timeouts
@@ -17,8 +17,8 @@ It models routes as `provider + transport + account + credential + model`, so on
 Implemented today:
 
 - `OpenAI API`, `Anthropic API`, `Gemini API`
-- `Claude Code ACP`, `Codex ACP`, `Gemini ACP`
-- `Gemini CLI`, `Qwen CLI`, `Claude/OpenClaude CLI`, `Codex CLI`
+- `Claude Code ACP`, `Codex ACP`
+- `agy CLI`, `pi CLI`, `Claude/OpenClaude CLI`, `Codex CLI`
 - `OpenCode Server`
 - browser and local client factories
 - env-backed key pools with delimiter-based rotation
@@ -219,51 +219,11 @@ Dedicated provider-specific ACP examples:
 
 - [examples/acp-claude.ts](/Users/vedmalex/work/ai-connect/examples/acp-claude.ts)
 - [examples/acp-codex.ts](/Users/vedmalex/work/ai-connect/examples/acp-codex.ts)
-- [examples/acp-gemini.ts](/Users/vedmalex/work/ai-connect/examples/acp-gemini.ts)
-
 Dedicated `clientTools` examples:
 
 - [examples/browser-client-tools.ts](/Users/vedmalex/work/ai-connect/examples/browser-client-tools.ts)
 - [examples/local-client-tools.ts](/Users/vedmalex/work/ai-connect/examples/local-client-tools.ts)
 
-For Gemini ACP you can choose the harness auth mode per connection by creating separate accounts:
-
-```ts
-const client = createLocalClient(
-  defineConfig({
-    providers: {
-      gemini: {
-        accounts: [
-          {
-            id: "gemini-default",
-            transport: { kind: "acp", id: "gemini-acp" },
-            models: ["auto-gemini-3"],
-          },
-          {
-            id: "gemini-oauth",
-            transport: {
-              kind: "acp",
-              id: "gemini-acp",
-              auth: {
-                methodId: "oauth-personal",
-              },
-            },
-            models: ["auto-gemini-3"],
-          },
-        ],
-      },
-    },
-    routing: {
-      operations: {
-        text: ["gemini:gemini-acp:gemini-oauth:auto-gemini-3"],
-      },
-    },
-  }),
-);
-```
-
-This keeps ACP harness auth explicit at connection selection time without injecting provider keys or `baseUrl` from `ai-connect`.
-
 ## Local CLI And Server Presets
 
 Built-in local transport presets are available both as catalog entries and as exported preset metadata:
@@ -279,7 +239,6 @@ import {
 const localCatalog = listTextProviderCatalog({ runtime: "local" });
 const codexCli = getTextTransportPresetById("openai", "codex-cli");
 const opencodeServer = AI_CONNECT_DEFAULT_SERVER_PRESETS.opencode;
-const geminiCli = AI_CONNECT_DEFAULT_CLI_PRESETS.gemini;
 ```
 
 For built-in CLI routes the shortest form is still the route `id`:
@@ -287,7 +246,7 @@ For built-in CLI routes the shortest form is still the route `id`:
 ```ts
 transport: {
   kind: "cli",
-  id: "gemini-cli",
+  id: "codex-cli",
 }
 ```
 
@@ -296,9 +255,9 @@ If you want a custom route id but still want the built-in argv/parser/command de
 ```ts
 transport: {
   kind: "cli",
-  id: "my-gemini-wrapper",
+  id: "my-codex-wrapper",
   cli: {
-    preset: "gemini",
+    preset: "codex",
   },
 }
 ```
@@ -316,10 +275,6 @@ Known local presets now include:
 - `anthropic:claude-cli`
 - `openclaude:openclaude-cli`
 - `anthropic:claude-code-acp`
-- `gemini:gemini-cli`
-- `gemini:gemini-acp`
-- `qwen:qwen-cli`
-- `qwen:qwen-acp`
 - `opencode:opencode-server`
 - `opencode:opencode-acp`
 
@@ -368,6 +323,76 @@ const client = createLocalClient(
 );
 ```
 
+The parser supports three kinds:
+
+- `kind: "json"` — parse stdout as a single JSON object; read the answer from `textPath` (plus optional `usagePath` / `errorPath`).
+- `kind: "jsonl"` — parse stdout as newline-delimited JSON; select the answer/usage/error lines with `{ path, wherePath, whereEquals }` selectors.
+- `kind: "text"` — treat stdout as **raw plain text** and return it as `result.text`. For **print-mode coding-agent CLIs that emit plain text, not JSON** (no `--output-format json` flag, no ACP mode). Options:
+  - `trim` (default `true`) — trim leading/trailing whitespace.
+  - `stripAnsi` (default `false`) — strip ANSI escape sequences (spinner/color noise) before returning.
+
+  Print-mode plain text carries no token information, so `result.usage` is absent (none is fabricated). An empty stdout on a non-zero exit still rejects with `temporary_unavailable`.
+
+```ts
+import { createLocalClient, defineConfig } from "@vedmalex/ai-connect";
+
+// A custom print-mode coding-agent CLI ("agy") that writes the answer as raw text.
+const client = createLocalClient(
+  defineConfig({
+    providers: {
+      agy: {
+        accounts: [
+          {
+            id: "local",
+            transport: {
+              kind: "cli",
+              id: "agy-cli",
+              command: "agy",
+              cli: {
+                argsTemplate: ["-p", "{prompt}", "--model", "{model}"],
+                parser: { kind: "text" }, // raw stdout -> result.text
+              },
+            },
+            models: ["default"],
+          },
+        ],
+      },
+    },
+  }),
+);
+```
+
+Another print-mode coding-agent CLI example — `pi` (invoked with `pi --print`; no ACP sidecar):
+
+```ts
+import { createLocalClient, defineConfig } from "@vedmalex/ai-connect";
+
+const client = createLocalClient(
+  defineConfig({
+    providers: {
+      pi: {
+        accounts: [
+          {
+            id: "local",
+            transport: {
+              kind: "cli",
+              id: "pi-cli",
+              command: "pi",
+              cli: {
+                argsTemplate: ["--print", "--model", "{model}", "{prompt}"],
+                parser: { kind: "text" }, // raw stdout -> result.text
+                discovery: { via: "none" }, // no ACP sidecar for pi
+              },
+            },
+            models: ["gemini-3.1-pro-low", "gemini-3-flash"],
+          },
+        ],
+      },
+    },
+  }),
+);
+```
+
 Supported placeholders in `argsTemplate`:
 
 - `{prompt}`
@@ -376,9 +401,40 @@ Supported placeholders in `argsTemplate`:
 
 `{output_file}` is useful for CLIs like `codex exec` that stream JSONL to stdout but write the final assistant message to a file.
 
+### CLI Model Discovery
+
+A `cli` route exposes the same management interfaces as other providers — `discoverModels` / `checkHealth` / `probeModels` / `listCandidateModels`. The discovery **source** is resolved from `transport.cli.discovery.via`; when `via` is omitted it is chosen by the chain **`command` → `acp` → `static` → `none`**:
+
+- **`command`** — run a configured CLI sub-command that lists models and parse its stdout. Reuses the same `json | jsonl | text` formats; model fields are mapped with a `models` selector. Falls back to the static source on empty/failed output (`fallback: "static"` by default when `models[]` is present; set `fallback: "none"` to fail loud):
+
+  ```ts
+  transport: {
+    kind: "cli",
+    command: "agy",
+    cli: {
+      argsTemplate: ["-p", "{prompt}", "--model", "{model}"],
+      parser: { kind: "text" },
+      discovery: {
+        command: {
+          argsTemplate: ["models", "list", "--json"],
+          parser: { kind: "json" },
+          models: { path: "data", idPath: "id", namePath: "display_name", contextLengthPath: "context_window" },
+        },
+      },
+    },
+  },
+  models: ["agy-pro", { id: "agy-fast", contextWindow: 200_000 }],
+  ```
+
+- **`acp`** — delegate discovery to an ACP sidecar (the default for the built-in coding-agent presets).
+- **`static`** — build the catalog from the account's configured `models[]` (+ `contextWindow`). This is the default for a preset-less custom CLI that declares `models[]` (it previously reported `not_supported`); opt out with `discovery: { via: "none" }`.
+- **`none`** — no discovery.
+
+**Configured context window (GAP-A).** A model entry's `contextLength` is surfaced from the route's configured `contextWindow` only when discovery did not already report one (monotonic — a live discovered value always wins). Such entries are tagged `metadata.contextWindowSource: "configured"`. A consumer mapping `catalog.contextLength` into `resolveModelContextWindow`'s `discovered` slot should gate on `metadata.contextWindowSource !== "configured"` (otherwise feed it as the `configured` input) so the documented precedence `discovered > reference > configured > default` stays honest.
+
 Current local transport scope:
 
-- `cli`: text generation, plus optional model discovery via an ACP sidecar
+- `cli`: text generation, plus model discovery via a list `command`, a `static` config catalog, or an ACP sidecar
 - `server`: text generation plus provider-native model discovery
 
 ## Mock Gateway
@@ -933,7 +989,7 @@ When consuming `ai-connect` from `bs-search`:
 | Context-window resolution | yes | yes | yes |
 | Local file paths | no | yes | yes |
 | Local command/session verification | no | yes | yes |
-| Claude/Codex/Gemini ACP | no | yes | yes |
+| Claude/Codex ACP | no | yes | yes |
 
 ## Runtime Entry Points
 
@@ -1017,8 +1073,6 @@ Current discovery support matrix:
 
 Built-in CLI discovery defaults:
 
-- `gemini-cli` -> `gemini-acp`
-- `qwen-cli` -> `qwen-acp`
 - `claude-cli` -> `claude-code-acp`
 - `codex-cli` -> `codex-acp`
 - `openclaude-cli` -> no default discovery bridge
@@ -1029,22 +1083,38 @@ CLI discovery through ACP adds ACP-side prerequisites:
 - the ACP harness must be authenticated if that provider requires auth
 - `verify()` checks route plausibility and handler presence, but it does not perform a live discovery/auth handshake up front
 
-For custom CLI wrappers you can make the public API stay uniform by delegating discovery to ACP:
+For custom CLI wrappers you can make the public API stay uniform by delegating discovery to an ACP sidecar. For example, a Codex wrapper that delegates to `codex-acp`:
 
 ```ts
 transport: {
   kind: "cli",
-  id: "my-gemini-wrapper",
-  command: "/opt/bin/gemini-wrapper",
+  id: "my-codex-wrapper",
+  command: "/opt/bin/codex-wrapper",
   cli: {
     discovery: {
       via: "acp",
       acp: {
-        providerId: "gemini",
-        transportId: "gemini-acp",
-        auth: {
-          methodId: "oauth-personal",
-        },
+        providerId: "openai",
+        transportId: "codex-acp",
+      },
+    },
+  },
+}
+```
+
+Or a Claude wrapper delegating to `claude-code-acp`:
+
+```ts
+transport: {
+  kind: "cli",
+  id: "my-claude-wrapper",
+  command: "/opt/bin/claude-wrapper",
+  cli: {
+    discovery: {
+      via: "acp",
+      acp: {
+        providerId: "anthropic",
+        transportId: "claude-code-acp",
       },
     },
   },
@@ -1156,9 +1226,7 @@ Server routes:
 
 ACP usage statistics are exposed on `result.usage` when the harness provides them. `ai-connect` currently normalizes:
 
-- Gemini ACP `_meta.quota.token_count` and `_meta.quota.model_usage`
 - OpenCode ACP `usage_update` (`used`, `size`, `cost`)
-- Qwen ACP `_meta.usage` (`inputTokens`, `outputTokens`, `totalTokens`, `thoughtTokens`, `cachedReadTokens`)
 
 ## Examples
 
@@ -1166,7 +1234,6 @@ See:
 
 - [examples/acp-claude.ts](/Users/vedmalex/work/ai-connect/examples/acp-claude.ts)
 - [examples/acp-codex.ts](/Users/vedmalex/work/ai-connect/examples/acp-codex.ts)
-- [examples/acp-gemini.ts](/Users/vedmalex/work/ai-connect/examples/acp-gemini.ts)
 - [examples/browser-basic.ts](/Users/vedmalex/work/ai-connect/examples/browser-basic.ts)
 - [examples/local-acp.ts](/Users/vedmalex/work/ai-connect/examples/local-acp.ts)
 - [examples/local-test-server.ts](/Users/vedmalex/work/ai-connect/examples/local-test-server.ts)
@@ -1189,7 +1256,8 @@ If you are targeting the local gateway at `127.0.0.1:8045`, configure direct API
 ```ts
 import { createLocalClient, defineConfig } from "@vedmalex/ai-connect";
 
-const LOCAL_TEST_API_KEY = "sk-8181e6a4a59b4ec5a9931f3ae0f359c4";
+// Read the local gateway key from the environment — never hardcode a key.
+const LOCAL_TEST_API_KEY = process.env.LOCAL_TEST_API_KEY ?? "";
 
 const client = createLocalClient(
   defineConfig({
@@ -1248,6 +1316,8 @@ console.log(
 
 ## Publishing
 
+> Full release runbook (OIDC trusted publishing, cutting a release, caveats): [`docs/publishing.md`](./docs/publishing.md).
+
 `@vedmalex/ai-connect` ships as a public scoped npm package. The package metadata enforces the publish boundary:
 
 - `publishConfig.access` is `public`, which is required for a scoped name to publish without an explicit `--access public` flag.

package/dist/browser/index.js

@@ -219,11 +219,7 @@ function normalizeTransport(providerId, input) {
         ...selector.whereEquals !== void 0 ? { whereEquals: selector.whereEquals } : {}
       };
     };
-    const parser = (() => {
-      if (!descriptor.cli?.parser) {
-        return void 0;
-      }
-      const cliParser = descriptor.cli.parser;
+    const normalizeCliParser = (cliParser) => {
       if (cliParser.kind === "json") {
         assert(
           cliParser.textPath.trim().length > 0,
@@ -236,13 +232,22 @@ function normalizeTransport(providerId, input) {
           ...cliParser.usagePath?.trim() ? { usagePath: cliParser.usagePath.trim() } : {}
         };
       }
+      if (cliParser.kind === "text") {
+        return {
+          kind: "text",
+          // Default trim=true, stripAnsi=false; only persist explicit overrides.
+          ...cliParser.trim === false ? { trim: false } : {},
+          ...cliParser.stripAnsi === true ? { stripAnsi: true } : {}
+        };
+      }
       return {
         kind: "jsonl",
         text: normalizeSelector(cliParser.text, "text"),
         ...cliParser.error ? { error: normalizeSelector(cliParser.error, "error") } : {},
         ...cliParser.usage ? { usage: normalizeSelector(cliParser.usage, "usage") } : {}
       };
-    })();
+    };
+    const parser = descriptor.cli?.parser ? normalizeCliParser(descriptor.cli.parser) : void 0;
     const normalized = {
       ...descriptor.cli.preset ? { preset: descriptor.cli.preset } : {},
       ...descriptor.cli.argsTemplate ? {
@@ -254,11 +259,13 @@ function normalizeTransport(providerId, input) {
       if (!descriptor.cli?.discovery) {
         return void 0;
       }
-      const via = descriptor.cli.discovery.via ?? "none";
-      assert(
-        via === "none" || via === "acp",
-        `Unsupported CLI discovery mode "${String(via)}" for provider "${providerId}".`
-      );
+      const explicitVia = descriptor.cli.discovery.via;
+      if (explicitVia !== void 0) {
+        assert(
+          explicitVia === "none" || explicitVia === "acp" || explicitVia === "command" || explicitVia === "static",
+          `Unsupported CLI discovery mode "${String(explicitVia)}" for provider "${providerId}".`
+        );
+      }
       const launch = descriptor.cli.discovery.acp?.launch ? (() => {
         const contextMode = descriptor.cli.discovery?.acp?.launch?.contextMode ?? "workspace";
         const skillsMode = descriptor.cli.discovery?.acp?.launch?.skillsMode ?? "default";
@@ -279,7 +286,7 @@ function normalizeTransport(providerId, input) {
         methodId: descriptor.cli.discovery.acp.auth.methodId.trim(),
         params: descriptor.cli.discovery.acp.auth.params ?? {}
       } : void 0;
-      const acp = via === "acp" ? {
+      const acp = descriptor.cli.discovery.acp ? {
         ...descriptor.cli.discovery.acp?.providerId?.trim() ? { providerId: descriptor.cli.discovery.acp.providerId.trim() } : {},
         ...descriptor.cli.discovery.acp?.transportId?.trim() ? {
           transportId: descriptor.cli.discovery.acp.transportId.trim()
@@ -287,9 +294,55 @@ function normalizeTransport(providerId, input) {
         ...auth ? { auth } : {},
         ...launch ? { launch } : {}
       } : void 0;
+      const commandInput = descriptor.cli.discovery.command;
+      const command = commandInput ? (() => {
+        assert(
+          Array.isArray(commandInput.argsTemplate) && commandInput.argsTemplate.length > 0,
+          `CLI discovery command.argsTemplate must be a non-empty array for provider "${providerId}".`
+        );
+        const cmdParserInput = commandInput.parser ?? { kind: "text" };
+        const cmdParser = cmdParserInput.kind === "text" ? {
+          kind: "text",
+          ...cmdParserInput.trim === false ? { trim: false } : {},
+          ...cmdParserInput.stripAnsi === true ? { stripAnsi: true } : {}
+        } : { kind: cmdParserInput.kind };
+        if (cmdParser.kind !== "text") {
+          assert(
+            Boolean(commandInput.models?.idPath?.trim()),
+            `CLI discovery command.models.idPath is required for a ${cmdParser.kind} parser for provider "${providerId}".`
+          );
+        }
+        const m = commandInput.models;
+        const models = m?.idPath?.trim() ? {
+          ...m.path?.trim() ? { path: m.path.trim() } : {},
+          idPath: m.idPath.trim(),
+          ...m.namePath?.trim() ? { namePath: m.namePath.trim() } : {},
+          ...m.descriptionPath?.trim() ? { descriptionPath: m.descriptionPath.trim() } : {},
+          ...m.contextLengthPath?.trim() ? { contextLengthPath: m.contextLengthPath.trim() } : {}
+        } : void 0;
+        return {
+          ...commandInput.command?.trim() ? { command: commandInput.command.trim() } : {},
+          argsTemplate: commandInput.argsTemplate.map((part) => String(part)),
+          parser: cmdParser,
+          ...models ? { models } : {}
+        };
+      })() : void 0;
+      assert(
+        explicitVia !== "command" || command !== void 0,
+        `CLI discovery via:"command" requires a discovery.command block for provider "${providerId}".`
+      );
+      const fallback = descriptor.cli.discovery.fallback;
+      if (fallback !== void 0) {
+        assert(
+          fallback === "static" || fallback === "none",
+          `Unsupported CLI discovery fallback "${String(fallback)}" for provider "${providerId}".`
+        );
+      }
       return {
-        via,
-        ...acp ? { acp } : {}
+        ...explicitVia !== void 0 ? { via: explicitVia } : {},
+        ...acp ? { acp } : {},
+        ...command ? { command } : {},
+        ...fallback !== void 0 ? { fallback } : {}
       };
     })();
     return {
@@ -1730,6 +1783,25 @@ function resolveModelContextWindow(input) {
   const fallback = isUsableContextLength(input.defaultContextWindow) ? input.defaultContextWindow : DEFAULT_CONTEXT_WINDOW;
   return { contextWindow: fallback, source: "default" };
 }
+function fillConfiguredContextLength(route, models) {
+  if (!isUsableContextLength(route.contextWindow)) {
+    return models;
+  }
+  const configured = route.contextWindow;
+  return models.map((entry) => {
+    if (isUsableContextLength(entry.contextLength)) {
+      return entry;
+    }
+    if (route.model !== void 0 && entry.modelId !== route.model) {
+      return entry;
+    }
+    return {
+      ...entry,
+      contextLength: configured,
+      metadata: { ...entry.metadata ?? {}, contextWindowSource: "configured" }
+    };
+  });
+}
 function modelContextCacheKey(input) {
   if (typeof input === "string") {
     return { key: `::${input}`, model: input };
@@ -2172,6 +2244,7 @@ function normalizeResult(route, output, attempts) {
     attempts,
     ...output.toolCalls ? { toolCalls: output.toolCalls } : {},
     ...output.text !== void 0 ? { text: output.text } : {},
+    ...output.reasoning !== void 0 ? { reasoning: output.reasoning } : {},
     ...output.data !== void 0 ? { data: output.data } : {},
     ...output.usage !== void 0 ? { usage: output.usage } : {}
   };
@@ -4722,18 +4795,19 @@ function canonicalGeminiImageModelId(modelId) {
 }
 function buildModelCatalog(route, availableModels, currentModelId) {
   const requestedModelId = route.model;
-  const requestedModelAdvertised = availableModels.some(
+  const filledModels = fillConfiguredContextLength(route, availableModels);
+  const requestedModelAdvertised = filledModels.some(
     (model) => model.modelId === requestedModelId
   );
   const canonicalModelId = route.provider === "gemini" ? canonicalGeminiImageModelId(requestedModelId) : void 0;
-  const resolvedModelId = requestedModelAdvertised ? requestedModelId : canonicalModelId && availableModels.some((model) => model.modelId === canonicalModelId) ? canonicalModelId : void 0;
+  const resolvedModelId = requestedModelAdvertised ? requestedModelId : canonicalModelId && filledModels.some((model) => model.modelId === canonicalModelId) ? canonicalModelId : void 0;
   return {
     requestedModelId,
     requestedModelAdvertised,
     ...canonicalModelId ? { canonicalModelId } : {},
     ...resolvedModelId ? { resolvedModelId } : {},
     ...currentModelId ? { currentModelId } : {},
-    availableModels
+    availableModels: filledModels
   };
 }
 function parseOpenAiModelCatalog(route, payload) {
@@ -5548,6 +5622,9 @@ function extractText(value) {
         return [part];
       }
       if (part && typeof part === "object") {
+        if (part.thought === true) {
+          return [];
+        }
         const candidate = part.text;
         if (typeof candidate === "string") {
           return [candidate];
@@ -5558,6 +5635,22 @@ function extractText(value) {
   }
   return "";
 }
+function extractThoughts(value) {
+  if (!Array.isArray(value)) {
+    return void 0;
+  }
+  const thoughts = value.flatMap((part) => {
+    if (part && typeof part === "object" && part.thought === true) {
+      const candidate = part.text;
+      if (typeof candidate === "string") {
+        return [candidate];
+      }
+    }
+    return [];
+  });
+  const joined = thoughts.join("\n").trim();
+  return joined.length > 0 ? joined : void 0;
+}
 function imageAttachmentsFromPayload(payload, ...sources) {
   return extractImagePayloads(payload, ...sources).map(
     (item) => preparePortableFile(item)
@@ -6100,8 +6193,11 @@ async function runGemini(fetchImpl, context) {
     throw classifyApiError(provider, response, payload);
   }
   const data = payload;
+  const geminiThoughts = extractThoughts(data.candidates?.[0]?.content?.parts);
   return {
     text: extractText(data.candidates?.[0]?.content?.parts),
+    // The model's `{ thought: true }` parts, separated from the answer (consumers route this to a thinking UI).
+    ...geminiThoughts ? { reasoning: geminiThoughts } : {},
     data,
     ...geminiToolCallsFromPayload(data).length > 0 ? { toolCalls: geminiToolCallsFromPayload(data) } : {},
     ...(() => {