@vedmalex/ai-connect 0.5.0 → 0.7.0

package/dist/node/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,
@@ -1004,6 +1190,10 @@ function extension(value) {
   }
   return name.slice(index + 1).toLowerCase();
 }
+function extensionForMime(mimeType) {
+  const subtype = mimeType.split("/")[1]?.toLowerCase().replace(/[^a-z0-9.+-]/g, "");
+  return subtype && subtype.length > 0 ? subtype : "bin";
+}
 function isRemoteUrl(value) {
   try {
     const url = new URL(value);
@@ -1794,6 +1984,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" }
     };
   });
@@ -3126,7 +3318,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,
@@ -4829,7 +5022,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 ? {
@@ -6342,112 +6535,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: {
@@ -8561,25 +8648,26 @@ function splitCommandLine2(commandLine) {
 function quoteArg(value) {
   return /\s/.test(value) ? JSON.stringify(value) : value;
 }
-function buildCliPrompt(context) {
+function buildCliPrompt(context, fileInputEnabled) {
   if (context.request.operation !== "text") {
     throw new AiConnectError(
       "not_supported",
       `CLI transport "${context.route.transport.id}" only supports text requests.`
     );
   }
-  if (context.request.image || context.request.attachments.some(
-    (file) => portableFileCategory(file) === "image" || portableFileCategory(file) === "document"
-  )) {
+  if (context.request.image) {
     throw new AiConnectError(
       "unsupported_capability",
-      `CLI transport "${context.route.transport.id}" does not support image or document inputs.`
+      `CLI transport "${context.route.transport.id}" does not support image output.`
     );
   }
-  if (context.request.attachments.length > 0) {
+  if (!fileInputEnabled && context.request.attachments.length > 0) {
+    const hasBinary = context.request.attachments.some(
+      (file) => portableFileCategory(file) === "image" || portableFileCategory(file) === "document"
+    );
     throw new AiConnectError(
-      "not_supported",
-      `CLI transport "${context.route.transport.id}" does not support attachments.`
+      hasBinary ? "unsupported_capability" : "not_supported",
+      hasBinary ? `CLI transport "${context.route.transport.id}" does not support image or document inputs.` : `CLI transport "${context.route.transport.id}" does not support attachments.`
     );
   }
   return context.request.messages.map((message) => {
@@ -8724,11 +8812,16 @@ function createCliDiscoveryAcpRoute(route) {
 function resolveCliTransportOptions(route) {
   const presetId = route.transport.cli?.preset ?? defaultCliPresetIdForRoute(route);
   const preset = presetId ? getCliTransportPreset(presetId) : void 0;
+  const mergedFileInput = preset?.options.fileInput || route.transport.cli?.fileInput ? {
+    ...preset?.options.fileInput ?? {},
+    ...route.transport.cli?.fileInput ?? {}
+  } : void 0;
   const merged = {
     ...preset?.options ?? {},
     ...route.transport.cli ?? {},
     ...route.transport.cli?.argsTemplate ? { argsTemplate: route.transport.cli.argsTemplate } : {},
     ...route.transport.cli?.parser ? { parser: route.transport.cli.parser } : {},
+    ...mergedFileInput ? { fileInput: mergedFileInput } : {},
     ...presetId ? { preset: presetId } : {}
   };
   if (!merged.argsTemplate?.length) {
@@ -8739,15 +8832,73 @@ function resolveCliTransportOptions(route) {
   }
   return merged;
 }
-async function createOutputFile() {
+async function createCliTempDir(baseDir, prefix) {
   const tempDir = await fs2.mkdtemp(
-    path2.join(os2.tmpdir(), "ai-connect-cli-output-")
+    path2.join(baseDir ?? os2.tmpdir(), prefix ?? "ai-connect-cli-")
   );
   return {
     tempDir,
     outputFile: path2.join(tempDir, "last-message.txt")
   };
 }
+function safeStagedBasename(name, index, mimeType) {
+  const base = path2.basename(name.replace(/\\/g, "/"));
+  if (base === "" || base === "." || base === "..") {
+    return `attachment-${index}.${extensionForMime(mimeType)}`;
+  }
+  return base;
+}
+async function stageCliAttachments(attachments, attachDir, fileInput) {
+  const categories = new Set(
+    fileInput.categories ?? ["image", "document", "text", "other"]
+  );
+  await fs2.mkdir(attachDir, { recursive: true });
+  const refs = [];
+  const usedNames = /* @__PURE__ */ new Map();
+  for (let i = 0; i < attachments.length; i += 1) {
+    const file = preparePortableFile(attachments[i]);
+    const payload = await materializePortableFile(file);
+    if (!categories.has(payload.category)) {
+      continue;
+    }
+    let destName = safeStagedBasename(payload.name, i, payload.mimeType);
+    const seen = usedNames.get(destName);
+    if (seen !== void 0) {
+      destName = `${i}-${destName}`;
+    }
+    usedNames.set(destName, i);
+    const dest = path2.join(attachDir, destName);
+    if (payload.category === "text") {
+      if (payload.text !== void 0) {
+        await fs2.writeFile(dest, payload.text, "utf8");
+        refs.push(dest);
+        continue;
+      }
+    } else {
+      const bytes = payload.base64 ? Buffer.from(payload.base64, "base64") : await portableFileToBytes(file);
+      if (bytes !== void 0) {
+        await fs2.writeFile(dest, bytes);
+        refs.push(dest);
+        continue;
+      }
+    }
+    if (payload.uri) {
+      refs.push(payload.uri);
+    }
+  }
+  return refs;
+}
+function expandFileArgs(staged, fileInput) {
+  const perFileArgs = fileInput?.perFileArgs ?? ["@{path}"];
+  if (fileInput?.placement === "prompt") {
+    return [];
+  }
+  return staged.flatMap(
+    (ref) => perFileArgs.map(
+      (tpl) => tpl.replace("{path}", ref).replace("{name}", path2.basename(ref))
+    )
+  );
+}
 function materializeTemplateArg(templateArg, values, parameterKeys) {
   switch (templateArg) {
     case "{prompt}":
@@ -8774,31 +8925,62 @@ function materializeTemplateArg(templateArg, values, parameterKeys) {
 }
 async function buildCliInvocation(context, options) {
   const route = context.route;
-  const prompt = buildCliPrompt(context);
   const cliOptions = resolveCliTransportOptions(route);
+  const fileInput = cliOptions.fileInput;
+  const attachments = context.request.attachments;
+  const hasStageable = Boolean(fileInput) && attachments.length > 0;
+  let prompt = buildCliPrompt(context, Boolean(fileInput));
   const commandLine = resolveCliCommand(route, options);
   const resolved = splitCommandLine2(commandLine);
   const parameterKeys = [];
   let tempDir;
   let outputFile;
-  if (cliOptions.argsTemplate.includes("{output_file}")) {
-    const created = await createOutputFile();
+  const needsOutputFile = cliOptions.argsTemplate.includes("{output_file}");
+  if (needsOutputFile || hasStageable) {
+    const created = await createCliTempDir(
+      fileInput?.stagingDir ?? options?.staging?.dir,
+      options?.staging?.prefix
+    );
     tempDir = created.tempDir;
     outputFile = created.outputFile;
   }
+  let staged = [];
+  if (hasStageable && tempDir && fileInput) {
+    staged = await stageCliAttachments(
+      attachments,
+      path2.join(tempDir, "attachments"),
+      fileInput
+    );
+    if (fileInput.placement === "prompt" && staged.length > 0) {
+      const separator = fileInput.separator ?? " ";
+      const mentionTemplate = fileInput.mentionTemplate ?? "@{path}";
+      const mentions = staged.map(
+        (ref) => mentionTemplate.replace("{path}", ref).replace("{name}", path2.basename(ref))
+      ).join(separator);
+      prompt = `${prompt}${separator}${mentions}`;
+    }
+  }
   const args = [
     ...resolved.args,
-    ...cliOptions.argsTemplate.map(
-      (part) => materializeTemplateArg(
-        part,
-        {
-          prompt,
-          model: route.model,
-          ...outputFile ? { outputFile } : {}
-        },
-        parameterKeys
-      )
-    )
+    ...cliOptions.argsTemplate.flatMap((part) => {
+      if (part === "{files}") {
+        if (staged.length > 0) {
+          parameterKeys.push("{files}");
+        }
+        return expandFileArgs(staged, fileInput);
+      }
+      return [
+        materializeTemplateArg(
+          part,
+          {
+            prompt,
+            model: route.model,
+            ...outputFile ? { outputFile } : {}
+          },
+          parameterKeys
+        )
+      ];
+    })
   ];
   return {
     command: resolved.command,
@@ -8807,6 +8989,7 @@ async function buildCliInvocation(context, options) {
     env: buildCliEnvironment(options),
     ...tempDir ? { tempDir } : {},
     ...outputFile ? { outputFile } : {},
+    ...options?.staging?.keep ? { keepStaging: true } : {},
     parameterKeys
   };
 }
@@ -8835,16 +9018,20 @@ function buildCliDiscoveryInvocation(route, command, options) {
     parameterKeys
   };
 }
-function buildStaticCliCatalog(route) {
+function buildStaticCliCatalog(route, warning) {
   const models = route.advertisedModels.map((id) => ({
     modelId: id,
     name: id
   }));
-  return buildModelCatalog(
+  const catalog = buildModelCatalog(
     route,
     models,
     currentModelIdForRoute(route, route.advertisedModels)
   );
+  if (warning) {
+    catalog.warnings = [...catalog.warnings ?? [], warning];
+  }
+  return catalog;
 }
 function statsToUsage(stats) {
   if (!stats || typeof stats !== "object") {
@@ -8987,7 +9174,9 @@ function modelInfoFromRecord(record, selector) {
     modelId,
     name,
     ...description ? { description } : {},
-    ...contextLength !== void 0 ? { contextLength } : {}
+    // FT-002: a contextLength read from the list-command output is a discovered
+    // value (consistent with the API parsers), so tag its provenance.
+    ...contextLength !== void 0 ? { contextLength, contextWindowSource: "discovered" } : {}
   };
 }
 function parseCliModelList(stdout, parser, selector) {
@@ -9195,7 +9384,7 @@ async function executeCliInvocation(invocation, timeoutMs, phases, signal) {
   });
 }
 async function cleanupCliInvocation(invocation) {
-  if (invocation.tempDir) {
+  if (invocation.tempDir && !invocation.keepStaging) {
     await fs2.rm(invocation.tempDir, { recursive: true, force: true });
   }
 }
@@ -9258,13 +9447,20 @@ function createCliTransportManager(options) {
             throw error;
           }
           if (source.fallback === "static") {
-            return buildStaticCliCatalog(context.route);
+            const detail = error instanceof Error ? error.message : String(error);
+            return buildStaticCliCatalog(
+              context.route,
+              `CLI discovery command for "${context.route.transport.id}" failed (${detail}); fell back to the static models[] catalog.`
+            );
           }
           throw error;
         }
         if (models.length === 0) {
           if (source.fallback === "static") {
-            return buildStaticCliCatalog(context.route);
+            return buildStaticCliCatalog(
+              context.route,
+              `CLI discovery command for "${context.route.transport.id}" returned no models; fell back to the static models[] catalog.`
+            );
           }
           throw new AiConnectError(
             "temporary_unavailable",