@vedmalex/ai-connect 0.10.1 → 0.12.0

package/README.md

@@ -611,6 +611,60 @@ Three error codes are intentionally **hard-terminal**: they never rotate, retry,
 
 All other normalized error codes (`rate_limit`, `quota_exhausted`, `temporary_unavailable`, etc.) remain eligible for the rotation/retry/fallback chain you configure under `routing.fallback`.
 
+## Connection Registry (`connections.json`)
+
+Instead of hand-writing `defineConfig(...)`, you can declare your whole topology — endpoints,
+aliases (ordered failover chains), auth, and defaults — in a single **v2 registry document** and
+compile it into the exact config the client already consumes, plus ready-made `routeHints` per
+alias. It ships as two subpaths: `@vedmalex/ai-connect/registry` (pure, browser-safe:
+`parseRegistry` / `compileRegistry` / `convertV1Registry` / `mergeRegistries`) and
+`@vedmalex/ai-connect/registry/fs` (node/bun loader: `loadConnectionRegistry` / `loadV1Pair`).
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/vedmalex/ai-connect/main/schema/connections.v2.json",
+  "version": 2,
+  "defaults": { "alias": "fast" },
+  "endpoints": [
+    {
+      "id": "openai-main",
+      "provider": "openai",
+      "transport": "api",
+      "baseUrl": "https://api.openai.com/v1",
+      "auth": { "tokenEnv": "OPENAI_API_KEY" },
+      "models": ["gpt-4.1"],
+      "defaultModel": "gpt-4.1"
+    }
+  ],
+  "aliases": [{ "id": "fast", "chain": [{ "endpointId": "openai-main" }] }]
+}
+```
+
+```ts
+import { loadConnectionRegistry } from "@vedmalex/ai-connect/registry/fs";
+import { compileRegistry } from "@vedmalex/ai-connect/registry";
+import { createLocalClient } from "@vedmalex/ai-connect";
+
+const loaded = await loadConnectionRegistry(); // layered: user → project → AI_CONNECT_CONNECTIONS
+const compiled = compileRegistry(loaded.registry, { env: (name) => process.env[name] });
+const client = createLocalClient(compiled.config);
+
+const fast = compiled.aliases["fast"];
+if (!fast?.usable) throw new Error('alias "fast" is not usable'); // never dispatch on usable:false
+
+const result = await client.generate({
+  messages: [{ role: "user", content: "Summarize this design brief." }],
+  routeHints: fast.routeHints, // ordered failover pool
+});
+console.log(result.text);
+```
+
+The loader layers `~/.config/ai-connect/connections.json` (user) under
+`<cwd>/.config/ai-connect/connections.json` (project) under `$AI_CONNECT_CONNECTIONS`, each with
+a sibling `connections.secrets.json` overlay, and auto-converts legacy v1 (`rag-endpoints.json` +
+`rag-aliases.json`) pairs. Full format, layering, failure-taxonomy, and v1-migration guide:
+[docs/connection-registry.md](./docs/connection-registry.md).
+
 ## Cancellation, Pause, and Timeouts
 
 `generate(request, opts?)` and `stream(request, opts?)` accept an optional second argument:
@@ -1207,12 +1261,10 @@ ACP routes are treated as harness-owned connections:
 Tool semantics are intentionally split:
 
 - `api` routes support tool schema passthrough via `parameters.tools`
-- `api` routes also support client-managed tools through `clientTools`
-- `clientTools` are executed locally by `ai-connect` after the provider returns tool calls
 - `parameters.tools` remains the right path for upstream-managed tool schemas that are not executed by `ai-connect`
 - `acp` routes support harness-owned tool execution
 - `acp` routes do not currently forward request-defined tool schema from `parameters.tools`
-- `cli` and current built-in `server` routes do not support tool schema passthrough or tool execution
+- client-managed tools (`clientTools`) are executed locally by `ai-connect` and work on **all four transports** (since 0.11.0): natively on `api`, via an in-process loopback MCP bridge on `acp` (`session/new.mcpServers`; the agent must advertise HTTP MCP support), and via a shared text-based round protocol on `cli` / `server`
 
 That distinction is also reflected in route capabilities:
 
@@ -1257,11 +1309,13 @@ const result = await client.generate({
 });
 ```
 
-Current limits:
+`clientTools` semantics (as of 0.11.0 — see `docs/whats-new-0.11.md` for the full matrix):
 
-- `clientTools` are supported only for `generate()`
-- `clientTools` are currently supported only for text requests without attachments/image options
-- built-in local execution of `clientTools` is implemented for built-in API handlers: `openai`, `anthropic`, `gemini`
+- work in both `generate()` and `stream()` (streaming runs a full multi-round tool loop and emits additive `tool-call` / `tool-result` stream events)
+- combine with `attachments`/image input on `text`-operation requests: round 1 carries the attachments, follow-up rounds rely on message history; routing is capability-gated (`supportsClientToolExecution` AND `supportsImageInput`/`supportsFileUpload`), an incapable route pool fails fast with `unsupported_capability`
+- `operation: "image"` / `"file"` combined with `clientTools` is rejected up front with `unsupported_capability` (tool-loop semantics exist only for `text`)
+- built-in local execution on `api` routes covers the built-in handlers (`openai`, `anthropic`, `gemini`); `acp`/`cli`/`server` execute through their transport bridges (see the tool-semantics list above)
+- per-model capability hints (curated `MODEL_REFERENCE`) can narrow route capabilities per model — e.g. an embeddings model on a vision-capable provider no longer advertises image input in `listCandidateModels()`
 
 ### Context and MCP Semantics