@vedmalex/ai-connect 0.4.0 → 0.6.0

package/README.md

@@ -274,6 +274,7 @@ Known local presets now include:
 - `openai:codex-cli`
 - `anthropic:claude-cli`
 - `openclaude:openclaude-cli`
+- `pi:pi-cli`
 - `anthropic:claude-code-acp`
 - `opencode:opencode-server`
 - `opencode:opencode-acp`
@@ -362,7 +363,7 @@ const client = createLocalClient(
 );
 ```
 
-Another print-mode coding-agent CLI example — `pi` (invoked with `pi --print`; no ACP sidecar):
+`pi` has a built-in CLI preset (`pi-cli`). The preset supplies the default command (`pi`), argsTemplate (`["--print","--model","{model}","{prompt}"]`), parser (`kind: "text"`), and discovery (`via: "none"`). The minimal config is therefore:
 
 ```ts
 import { createLocalClient, defineConfig } from "@vedmalex/ai-connect";
@@ -376,15 +377,9 @@ const client = createLocalClient(
             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
-              },
+              id: "pi-cli", // selects the built-in pi-cli preset
             },
-            models: ["gemini-3.1-pro-low", "gemini-3-flash"],
+            models: ["gemini-3.1-pro-low"],
           },
         ],
       },
@@ -437,6 +432,65 @@ 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() ? {
@@ -383,7 +534,7 @@ function normalizeTransport(providerId, input) {
     };
   }
   if (descriptor.kind === "cli") {
-    const inferredId2 = providerId === "anthropic" ? "claude-cli" : providerId === "openclaude" ? "openclaude-cli" : providerId === "openai" ? "codex-cli" : providerId === "gemini" ? "gemini-cli" : providerId === "qwen" ? "qwen-cli" : "cli";
+    const inferredId2 = providerId === "anthropic" ? "claude-cli" : providerId === "openclaude" ? "openclaude-cli" : providerId === "openai" ? "codex-cli" : providerId === "pi" ? "pi-cli" : "cli";
     return {
       kind: "cli",
       id: descriptor.id?.trim() || inferredId2,
@@ -400,7 +551,7 @@ function normalizeTransport(providerId, input) {
       ...descriptor.baseUrl?.trim() ? { baseUrl: descriptor.baseUrl.trim() } : {}
     };
   }
-  const inferredId = providerId === "anthropic" ? "claude-code-acp" : providerId === "openai" ? "codex-acp" : providerId === "gemini" ? "gemini-acp" : "acp";
+  const inferredId = providerId === "anthropic" ? "claude-code-acp" : providerId === "openai" ? "codex-acp" : "acp";
   const normalizedLaunch = descriptor.launch ? (() => {
     const contextMode = descriptor.launch?.contextMode ?? "workspace";
     const skillsMode = descriptor.launch?.skillsMode ?? "default";
@@ -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,
@@ -1638,18 +1824,14 @@ var MODEL_REFERENCE = {
     key: "gemini-3.1-flash-lite",
     contextLength: 1048576
   },
+  "gemini-3.1-pro": { key: "gemini-3.1-pro", contextLength: 1048576 },
   "gemini-3-pro": { key: "gemini-3-pro", contextLength: 2097152 },
   "auto-gemini-3": { key: "auto-gemini-3", contextLength: 1048576 },
   "gemini-2.5-flash": { key: "gemini-2.5-flash", contextLength: 1048576 },
   "gemini-2.5-pro": { key: "gemini-2.5-pro", contextLength: 2097152 },
   "gemini-2.0-flash": { key: "gemini-2.0-flash", contextLength: 1048576 },
   "gemini-1.5-flash": { key: "gemini-1.5-flash", contextLength: 1048576 },
-  "gemini-1.5-pro": { key: "gemini-1.5-pro", contextLength: 2097152 },
-  // --- Qwen (catalog: qwen3-coder-plus) ---
-  "qwen3-coder-plus": { key: "qwen3-coder-plus", contextLength: 1048576 },
-  "qwen3-coder": { key: "qwen3-coder", contextLength: 262144 },
-  "qwen-max": { key: "qwen-max", contextLength: 32768 },
-  "qwen-plus": { key: "qwen-plus", contextLength: 131072 }
+  "gemini-1.5-pro": { key: "gemini-1.5-pro", contextLength: 2097152 }
 };
 function normalizeModelKey(model) {
   let key = model.trim().toLowerCase();
@@ -6340,144 +6522,9 @@ function createDefaultRouteHandlers(options = {}) {
 var AI_CONNECT_DEFAULT_ACP_COMMANDS = {
   "anthropic:claude-code-acp": "npx -y @agentclientprotocol/claude-agent-acp@^0.25.0",
   "openai:codex-acp": "npx @zed-industries/codex-acp@^0.11.1",
-  "gemini:gemini-acp": "gemini --acp",
-  "qwen:qwen-acp": "qwen --acp",
   "opencode:opencode-acp": "opencode acp"
 };
 
-// src/cli-presets.ts
-var AI_CONNECT_DEFAULT_CLI_PRESETS = {
-  gemini: {
-    id: "gemini",
-    label: "Gemini CLI",
-    command: "gemini",
-    transportId: "gemini-cli",
-    options: {
-      preset: "gemini",
-      argsTemplate: ["-p", "{prompt}", "--output-format", "json", "--model", "{model}"],
-      discovery: {
-        via: "acp",
-        acp: {
-          transportId: "gemini-acp"
-        }
-      },
-      parser: {
-        kind: "json",
-        textPath: "response",
-        usagePath: "stats",
-        errorPath: "error"
-      }
-    }
-  },
-  qwen: {
-    id: "qwen",
-    label: "Qwen CLI",
-    command: "qwen",
-    transportId: "qwen-cli",
-    options: {
-      preset: "qwen",
-      argsTemplate: ["-p", "{prompt}", "--output-format", "json", "--model", "{model}"],
-      discovery: {
-        via: "acp",
-        acp: {
-          transportId: "qwen-acp"
-        }
-      },
-      parser: {
-        kind: "json",
-        textPath: "__preset__:qwen.result",
-        usagePath: "__preset__:qwen.stats",
-        errorPath: "__preset__:qwen.error"
-      }
-    }
-  },
-  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,
-  "gemini:gemini-cli": AI_CONNECT_DEFAULT_CLI_PRESETS.gemini.command,
-  "qwen:qwen-cli": AI_CONNECT_DEFAULT_CLI_PRESETS.qwen.command
-};
-function getCliTransportPreset(presetId) {
-  return AI_CONNECT_DEFAULT_CLI_PRESETS[presetId];
-}
-
 // src/server-presets.ts
 var AI_CONNECT_DEFAULT_SERVER_PRESETS = {
   opencode: {
@@ -6594,52 +6641,22 @@ var TEXT_PROVIDER_CATALOG = [
         runtime: "universal",
         defaultModel: "gemini-3.1-flash-lite",
         defaultBaseUrl: ""
-      },
-      {
-        providerId: "gemini",
-        providerLabel: "Gemini",
-        transportKind: "cli",
-        transportId: "gemini-cli",
-        transportLabel: "Gemini CLI",
-        runtime: "local",
-        defaultModel: "gemini-2.5-flash",
-        defaultCommand: AI_CONNECT_DEFAULT_CLI_COMMANDS["gemini:gemini-cli"]
-      },
-      {
-        providerId: "gemini",
-        providerLabel: "Gemini",
-        transportKind: "acp",
-        transportId: "gemini-acp",
-        transportLabel: "Gemini ACP",
-        runtime: "local",
-        defaultModel: "auto-gemini-3",
-        defaultCommand: AI_CONNECT_DEFAULT_ACP_COMMANDS["gemini:gemini-acp"]
       }
     ]
   },
   {
-    providerId: "qwen",
-    label: "Qwen",
+    providerId: "pi",
+    label: "pi",
     transports: [
       {
-        providerId: "qwen",
-        providerLabel: "Qwen",
+        providerId: "pi",
+        providerLabel: "pi",
         transportKind: "cli",
-        transportId: "qwen-cli",
-        transportLabel: "Qwen CLI",
+        transportId: "pi-cli",
+        transportLabel: "pi CLI",
         runtime: "local",
-        defaultModel: "qwen3-coder-plus",
-        defaultCommand: AI_CONNECT_DEFAULT_CLI_COMMANDS["qwen:qwen-cli"]
-      },
-      {
-        providerId: "qwen",
-        providerLabel: "Qwen",
-        transportKind: "acp",
-        transportId: "qwen-acp",
-        transportLabel: "Qwen ACP",
-        runtime: "local",
-        defaultModel: "default",
-        defaultCommand: AI_CONNECT_DEFAULT_ACP_COMMANDS["qwen:qwen-acp"]
+        defaultModel: "gemini-3.1-pro-low",
+        defaultCommand: AI_CONNECT_DEFAULT_CLI_COMMANDS["pi:pi-cli"]
       }
     ]
   },