@vedmalex/ai-connect 0.5.0 → 0.7.0

package/README.md

@@ -425,13 +425,74 @@ A `cli` route exposes the same management interfaces as other providers — `dis
 - **`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.
+**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). Provenance is exposed on the typed field `ModelInfo.contextWindowSource`: `"discovered"` (read from a live API/cli list-command record), `"configured"` (surfaced from the route's `contextWindow`), or `undefined` (unknown). A consumer mapping `catalog.contextLength` into `resolveModelContextWindow`'s `discovered` slot should do so ONLY when `contextWindowSource === "discovered"` — treat `"configured"` as the `configured` input and `undefined` as unknown (do not promote it to the `discovered` slot) — so the precedence `discovered > reference > configured > default` stays honest. (`metadata.contextWindowSource: "configured"` is retained as a back-compat alias on the configured-fill path.)
+
+**Discovery diagnostics.** A model-discovery route report (and its catalog) may carry a `warnings: string[]`. In particular, a cli `discovery.via: "command"` route whose list command fails/times out/returns nothing and falls back to its static `models[]` catalog records a warning there, so a degraded fallback is distinguishable from a healthy static catalog.
 
 Current local transport scope:
 
 - `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
 
+### CLI File and Image Input
+
+CLI routes can stage local attachment files into a temp directory and pass them to the subprocess as argv tokens or inline prompt references.
+
+**Client-level staging** is configured under `cli.staging`:
+
+```ts
+const client = createLocalClient(config, {
+  cli: {
+    staging: {
+      dir: "/tmp/my-staging",  // default: os.tmpdir()
+      prefix: "ai-connect-",   // temp dir name prefix
+      keep: true,               // retain per-invocation temp dir (debug only)
+    },
+  },
+});
+```
+
+Staged files are written under `<stagingDir>/attachments/` with sanitized basenames (path-traversal safe) and removed after the call completes (unless `keep: true`). Attachments that carry only a remote URI and no bytes degrade to the raw URI reference.
+
+**Per-route file input** is declared under `transport.cli.fileInput`:
+
+```ts
+transport: {
+  kind: "cli",
+  id: "my-route",
+  cli: {
+    fileInput: {
+      placement: "args",          // "args" (default) | "prompt"
+      perFileArgs: ["@{path}"],   // argv tokens per file; {path} and {name} placeholders
+      // mentionTemplate: "@{path}", // prompt placement: inserted per file (default "@{path}")
+      // separator: " ",
+      categories: ["image", "document", "text", "other"], // accepted categories (default: all)
+      stagingDir: "/custom/dir",  // per-route override of cli.staging.dir
+    },
+  },
+}
+```
+
+A `{files}` placeholder in `argsTemplate` expands to the full per-file argv block; it records a single telemetry key, not the staged absolute paths.
+
+**Capability gate.** A route advertises `supportsImageInput` only when its `fileInput` stages the `image` category, and `supportsFileUpload` only when it stages the `document` category. A route that does not accept a category rejects the attachment with `unsupported_capability` at routing time, before any subprocess is spawned.
+
+**Built-in preset behavior:**
+
+- **`pi` preset** — accepts attachments from all categories (`image`, `document`, `text`, `other`). Each file is passed as an `@{path}` argv token (`perFileArgs: ["@{path}"]`). Pass an image attachment and `pi` receives `@/tmp/.../attachments/photo.png` as an argument. PDFs are staged as-is with no document extraction; `pi` receives raw bytes — prefer images or text files for reliable results.
+
+  ```ts
+  const result = await client.generate({
+    messages: [{ role: "user", content: "Describe this image." }],
+    attachments: ["/path/to/photo.png"],
+    // route is pi:cli:local or routeHints selects pi-cli
+  });
+  ```
+
+- **`codex` preset** — accepts images only (`categories: ["image"]`). Each image is passed as `--image {path}` (`perFileArgs: ["--image", "{path}"]`). A non-image attachment (e.g. a PDF) on a codex route is rejected with `unsupported_capability` before any spawn.
+
+- **`claude` / `openclaude` presets** — do not accept CLI file input by default. File input is opt-in: add an explicit `transport.cli.fileInput` block to your route config.
+
 ## Mock Gateway
 
 For API-level debugging you can run a local mock backend that behaves like a small OpenAI/Anthropic/Gemini proxy and captures the real finalized wire payloads:

package/dist/browser/index.js

@@ -1,3 +1,125 @@
+// src/cli-presets.ts
+var AI_CONNECT_DEFAULT_CLI_PRESETS = {
+  pi: {
+    id: "pi",
+    label: "pi (coding agent)",
+    command: "pi",
+    transportId: "pi-cli",
+    options: {
+      preset: "pi",
+      // pi print mode emits the answer as plain text on stdout (no JSON wrapper),
+      // and has no ACP mode — so it uses the raw `text` parser and no discovery sidecar.
+      // pi takes file/image attachments as separate `@<path>` argv tokens (REQ-024);
+      // {files} expands one `@<staged-path>` token per attachment. pi stages all
+      // categories (PDFs as-is, no extraction guarantee).
+      argsTemplate: ["--print", "--model", "{model}", "{files}", "{prompt}"],
+      discovery: {
+        via: "none"
+      },
+      parser: {
+        kind: "text"
+      },
+      fileInput: {
+        placement: "args",
+        perFileArgs: ["@{path}"]
+      }
+    }
+  },
+  claude: {
+    id: "claude",
+    label: "Claude CLI",
+    command: "claude",
+    transportId: "claude-cli",
+    options: {
+      preset: "claude",
+      argsTemplate: ["--print", "--output-format", "json", "--model", "{model}", "{prompt}"],
+      discovery: {
+        via: "acp",
+        acp: {
+          transportId: "claude-code-acp"
+        }
+      },
+      parser: {
+        kind: "json",
+        textPath: "__preset__:claude.result",
+        usagePath: "usage",
+        errorPath: "__preset__:claude.error"
+      }
+    }
+  },
+  openclaude: {
+    id: "openclaude",
+    label: "OpenClaude CLI",
+    command: "openclaude",
+    transportId: "openclaude-cli",
+    options: {
+      preset: "openclaude",
+      argsTemplate: ["--print", "--output-format", "json", "--model", "{model}", "{prompt}"],
+      parser: {
+        kind: "json",
+        textPath: "__preset__:claude.result",
+        usagePath: "usage",
+        errorPath: "__preset__:claude.error"
+      }
+    }
+  },
+  codex: {
+    id: "codex",
+    label: "Codex CLI",
+    command: "codex",
+    transportId: "codex-cli",
+    options: {
+      preset: "codex",
+      // codex exec takes image attachments via `-i/--image <FILE>` flags
+      // (REQ-024); {files} expands a `--image <staged-path>` pair per image.
+      // Images only — a non-image attachment cleanly rejects pre-spawn.
+      argsTemplate: [
+        "exec",
+        "--json",
+        "--output-last-message",
+        "{output_file}",
+        "--model",
+        "{model}",
+        "{files}",
+        "{prompt}"
+      ],
+      discovery: {
+        via: "acp",
+        acp: {
+          transportId: "codex-acp"
+        }
+      },
+      fileInput: {
+        placement: "args",
+        perFileArgs: ["--image", "{path}"],
+        categories: ["image"]
+      },
+      parser: {
+        kind: "jsonl",
+        text: {
+          path: "__preset__:codex.text"
+        },
+        usage: {
+          path: "__preset__:codex.usage"
+        },
+        error: {
+          path: "__preset__:codex.error"
+        }
+      }
+    }
+  }
+};
+var AI_CONNECT_DEFAULT_CLI_COMMANDS = {
+  "anthropic:claude-cli": AI_CONNECT_DEFAULT_CLI_PRESETS.claude.command,
+  "anthropic:openclaude-cli": AI_CONNECT_DEFAULT_CLI_PRESETS.openclaude.command,
+  "openclaude:openclaude-cli": AI_CONNECT_DEFAULT_CLI_PRESETS.openclaude.command,
+  "openai:codex-cli": AI_CONNECT_DEFAULT_CLI_PRESETS.codex.command,
+  "pi:pi-cli": AI_CONNECT_DEFAULT_CLI_PRESETS.pi.command
+};
+function getCliTransportPreset(presetId) {
+  return AI_CONNECT_DEFAULT_CLI_PRESETS[presetId];
+}
+
 // src/errors.ts
 var AiConnectError = class extends Error {
   code;
@@ -345,9 +467,38 @@ function normalizeTransport(providerId, input) {
         ...fallback !== void 0 ? { fallback } : {}
       };
     })();
+    const fileInput = (() => {
+      const fi = descriptor.cli?.fileInput;
+      if (!fi) {
+        return void 0;
+      }
+      const validCategories = ["image", "document", "text", "other"];
+      if (fi.categories) {
+        for (const c of fi.categories) {
+          assert(
+            validCategories.includes(c),
+            `Unsupported CLI fileInput category "${String(c)}" for provider "${providerId}".`
+          );
+        }
+      }
+      const placement = fi.placement ?? "args";
+      assert(
+        placement === "args" || placement === "prompt",
+        `Unsupported CLI fileInput placement "${String(placement)}" for provider "${providerId}".`
+      );
+      return {
+        placement,
+        ...fi.perFileArgs ? { perFileArgs: fi.perFileArgs.map((part) => String(part)) } : {},
+        ...fi.mentionTemplate?.trim() ? { mentionTemplate: fi.mentionTemplate.trim() } : {},
+        ...fi.separator !== void 0 ? { separator: fi.separator } : {},
+        ...fi.categories ? { categories: [...fi.categories] } : {},
+        ...fi.stagingDir?.trim() ? { stagingDir: fi.stagingDir.trim() } : {}
+      };
+    })();
     return {
       ...normalized,
-      ...discovery ? { discovery } : {}
+      ...discovery ? { discovery } : {},
+      ...fileInput ? { fileInput } : {}
     };
   })();
   const normalizedAuth = descriptor.auth?.methodId?.trim() ? {
@@ -435,7 +586,40 @@ function normalizeRuntime(transport, runtime) {
   }
   return "universal";
 }
+function cliPresetIdForTransportId(transportId) {
+  switch (transportId) {
+    case "pi-cli":
+      return "pi";
+    case "claude-cli":
+      return "claude";
+    case "openclaude-cli":
+      return "openclaude";
+    case "codex-cli":
+      return "codex";
+    default:
+      return void 0;
+  }
+}
+function cliFileInputCategories(transport) {
+  if (transport.kind !== "cli") {
+    return /* @__PURE__ */ new Set();
+  }
+  const presetId = transport.cli?.preset ?? cliPresetIdForTransportId(transport.id);
+  const presetFileInput = presetId ? AI_CONNECT_DEFAULT_CLI_PRESETS[presetId]?.options.fileInput : void 0;
+  const routeFileInput = transport.cli?.fileInput;
+  if (!presetFileInput && !routeFileInput) {
+    return /* @__PURE__ */ new Set();
+  }
+  const merged = {
+    ...presetFileInput ?? {},
+    ...routeFileInput ?? {}
+  };
+  return new Set(
+    merged.categories ?? ["image", "document", "text", "other"]
+  );
+}
 function defaultCapabilities(transport, runtime) {
+  const cliFileCategories = cliFileInputCategories(transport);
   const localOnly = runtime === "local" || transport.kind === "acp" || transport.kind === "cli" || transport.kind === "server";
   const browserSafe = !localOnly;
   return {
@@ -450,10 +634,12 @@ function defaultCapabilities(transport, runtime) {
     supportsClientToolExecution: transport.kind === "api",
     // C6 / F-P-4: api routes now advertise document + image input parity with acp.
     // The per-account `capabilities` override remains the escape hatch for
-    // text-only api proxies that must opt out.
-    supportsFileUpload: transport.kind === "acp" || transport.kind === "api",
+    // text-only api proxies that must opt out. REQ-024: a cli route advertises
+    // document/image input ONLY for the categories its fileInput actually stages
+    // (category-aware so e.g. an image-only cli cleanly rejects a PDF pre-spawn).
+    supportsFileUpload: transport.kind === "acp" || transport.kind === "api" || cliFileCategories.has("document"),
     supportsFileOutput: transport.kind === "acp",
-    supportsImageInput: transport.kind === "acp" || transport.kind === "api",
+    supportsImageInput: transport.kind === "acp" || transport.kind === "api" || cliFileCategories.has("image"),
     supportsImageOutput: transport.kind === "acp",
     supportsProfileVerification: true,
     supportsCredentialRotation: false,
@@ -1794,6 +1980,8 @@ function fillConfiguredContextLength(route, models) {
     return {
       ...entry,
       contextLength: configured,
+      // FT-002: typed provenance (canonical) + metadata alias (back-compat).
+      contextWindowSource: "configured",
       metadata: { ...entry.metadata ?? {}, contextWindowSource: "configured" }
     };
   });
@@ -3123,7 +3311,8 @@ function createClient(configOrInput, options = {}) {
           ...catalog.canonicalModelId ? { canonicalModelId: catalog.canonicalModelId } : {},
           ...catalog.resolvedModelId ? { resolvedModelId: catalog.resolvedModelId } : {},
           ...catalog.currentModelId ? { currentModelId: catalog.currentModelId } : {},
-          availableModels: catalog.availableModels
+          availableModels: catalog.availableModels,
+          ...catalog.warnings?.length ? { warnings: catalog.warnings } : {}
         });
         wideAttempts.push({
           index: wideAttempts.length + 1,
@@ -4826,7 +5015,7 @@ function parseOpenAiModelCatalog(route, payload) {
         modelId: entry.id,
         name: typeof entry.display_name === "string" ? entry.display_name : typeof entry.name === "string" ? entry.name : entry.id,
         ...typeof entry.description === "string" ? { description: entry.description } : {},
-        ...contextLength !== void 0 ? { contextLength } : {},
+        ...contextLength !== void 0 ? { contextLength, contextWindowSource: "discovered" } : {},
         ...pricing ? { pricing } : {},
         ...free ? { free } : {},
         ...metadata ? {
@@ -6339,112 +6528,6 @@ var AI_CONNECT_DEFAULT_ACP_COMMANDS = {
   "opencode:opencode-acp": "opencode acp"
 };
 
-// src/cli-presets.ts
-var AI_CONNECT_DEFAULT_CLI_PRESETS = {
-  pi: {
-    id: "pi",
-    label: "pi (coding agent)",
-    command: "pi",
-    transportId: "pi-cli",
-    options: {
-      preset: "pi",
-      // pi print mode emits the answer as plain text on stdout (no JSON wrapper),
-      // and has no ACP mode — so it uses the raw `text` parser and no discovery sidecar.
-      argsTemplate: ["--print", "--model", "{model}", "{prompt}"],
-      discovery: {
-        via: "none"
-      },
-      parser: {
-        kind: "text"
-      }
-    }
-  },
-  claude: {
-    id: "claude",
-    label: "Claude CLI",
-    command: "claude",
-    transportId: "claude-cli",
-    options: {
-      preset: "claude",
-      argsTemplate: ["--print", "--output-format", "json", "--model", "{model}", "{prompt}"],
-      discovery: {
-        via: "acp",
-        acp: {
-          transportId: "claude-code-acp"
-        }
-      },
-      parser: {
-        kind: "json",
-        textPath: "__preset__:claude.result",
-        usagePath: "usage",
-        errorPath: "__preset__:claude.error"
-      }
-    }
-  },
-  openclaude: {
-    id: "openclaude",
-    label: "OpenClaude CLI",
-    command: "openclaude",
-    transportId: "openclaude-cli",
-    options: {
-      preset: "openclaude",
-      argsTemplate: ["--print", "--output-format", "json", "--model", "{model}", "{prompt}"],
-      parser: {
-        kind: "json",
-        textPath: "__preset__:claude.result",
-        usagePath: "usage",
-        errorPath: "__preset__:claude.error"
-      }
-    }
-  },
-  codex: {
-    id: "codex",
-    label: "Codex CLI",
-    command: "codex",
-    transportId: "codex-cli",
-    options: {
-      preset: "codex",
-      argsTemplate: [
-        "exec",
-        "--json",
-        "--output-last-message",
-        "{output_file}",
-        "--model",
-        "{model}",
-        "{prompt}"
-      ],
-      discovery: {
-        via: "acp",
-        acp: {
-          transportId: "codex-acp"
-        }
-      },
-      parser: {
-        kind: "jsonl",
-        text: {
-          path: "__preset__:codex.text"
-        },
-        usage: {
-          path: "__preset__:codex.usage"
-        },
-        error: {
-          path: "__preset__:codex.error"
-        }
-      }
-    }
-  }
-};
-var AI_CONNECT_DEFAULT_CLI_COMMANDS = {
-  "anthropic:claude-cli": AI_CONNECT_DEFAULT_CLI_PRESETS.claude.command,
-  "anthropic:openclaude-cli": AI_CONNECT_DEFAULT_CLI_PRESETS.openclaude.command,
-  "openclaude:openclaude-cli": AI_CONNECT_DEFAULT_CLI_PRESETS.openclaude.command,
-  "openai:codex-cli": AI_CONNECT_DEFAULT_CLI_PRESETS.codex.command,
-  "pi:pi-cli": AI_CONNECT_DEFAULT_CLI_PRESETS.pi.command
-};
-function getCliTransportPreset(presetId) {
-  return AI_CONNECT_DEFAULT_CLI_PRESETS[presetId];
-}
-
 // src/server-presets.ts
 var AI_CONNECT_DEFAULT_SERVER_PRESETS = {
   opencode: {