@yanickxia/agent-vision 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yanick Xia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,8 @@
+agent-vision is an independent implementation.
+
+It uses the Model Context Protocol SDK and an ffmpeg binary distributed by the
+@ffmpeg-installer/ffmpeg npm package. Those dependencies and platform binaries
+retain their own licenses.
+
+Design references and inspiration are listed in README.md. No GPL-licensed
+source code from farhanic017/vision-tool is included in this project.

package/README.md

@@ -0,0 +1,188 @@
+# agent-vision
+
+一个小而直接的视觉 MCP Server + Agent Skill：让纯文本 Agent 通过一个
+OpenAI-compatible 视觉模型理解图片和视频。
+
+- 纯 Node.js / TypeScript，`npx` 自动下载运行
+- MCP 工具：`analyze_image`、`analyze_video`
+- Agent Skills 标准目录：`skills/agent-vision/`
+- 图片：本地路径、HTTP(S) URL、Data URI
+- 视频：本地路径或 URL，自动下载 npm 内的 ffmpeg 并均匀抽帧
+- 单一 provider，无免费模型列表、fallback 竞速、watchdog 或透明代理
+
+## 为什么做这个项目
+
+参考项目各有优点，但组合起来偏重：
+
+- [luma-mcp](https://github.com/JochenYang/luma-mcp)：Node.js、npx 和图片预处理体验好，但主要面向单图。
+- [deepseek-vision-mcp](https://github.com/JunHua-ECJTU/deepseek-vision-mcp)：MCP 执行层与 Skill 决策层分离得很清楚，但依赖 Python，且本地视频受 provider 限制。
+- [vision-tool](https://github.com/farhanic017/vision-tool)：支持视频抽帧，但包含大量 provider 探测、并行 fallback 和安装逻辑，并采用 GPL-3.0。
+- [agent-vision-toolkit](https://github.com/Anionex/agent-vision-toolkit)：Skill 和任务工作流很强，但核心是多组 Python/Shell CLI，不是 MCP 视频服务。
+
+`agent-vision` 只保留一条链路：**MCP/CLI → 图片或视频帧 → 你配置的视觉 API → 文本**。
+本仓库是独立实现，没有复制 `vision-tool` 的 GPL 源码。
+
+## 要求
+
+- Node.js 20+
+- 一个支持 `/chat/completions` 和 `image_url` 的 OpenAI-compatible 视觉模型
+
+ffmpeg 由 `@ffmpeg-installer/ffmpeg` 按平台自动安装，无需另行安装。
+
+## 配置
+
+```bash
+export AGENT_VISION_BASE_URL="https://your-endpoint.example/v1"
+export AGENT_VISION_API_KEY="your-key"
+export AGENT_VISION_MODEL="your-vision-model"
+```
+
+本地无鉴权端点可以不设置 API key。变量优先级：
+
+| 设置 | 兼容回退 |
+|---|---|
+| `AGENT_VISION_API_KEY` | `VISION_API_KEY` → `OPENAI_API_KEY` |
+| `AGENT_VISION_BASE_URL` | `VISION_BASE_URL` → `OPENAI_BASE_URL` |
+| `AGENT_VISION_MODEL` | `VISION_MODEL` → `OPENAI_MODEL` |
+
+可选变量：
+
+| 变量 | 默认值 | 说明 |
+|---|---:|---|
+| `AGENT_VISION_MAX_TOKENS` | `4096` | 最大输出 tokens |
+| `AGENT_VISION_TIMEOUT_MS` | `120000` | 下载和 API 超时 |
+| `AGENT_VISION_MAX_IMAGE_MB` | `20` | 图片大小上限 |
+| `AGENT_VISION_MAX_VIDEO_MB` | `200` | 视频大小上限 |
+| `AGENT_VISION_HEADERS` | `{}` | 额外请求头 JSON |
+| `AGENT_VISION_ALLOW_PRIVATE_URLS` | `false` | 允许私网图片/视频来源 URL |
+| `AGENT_VISION_FFMPEG_PATH` | 自动发现 | 指定 ffmpeg 可执行文件；默认先用 PATH，再用 npm 内置版本 |
+
+## MCP 安装
+
+### npm（发布后推荐）
+
+```json
+{
+  "mcpServers": {
+    "agent-vision": {
+      "command": "npx",
+      "args": ["-y", "@yanickxia/agent-vision"],
+      "env": {
+        "AGENT_VISION_BASE_URL": "https://your-endpoint.example/v1",
+        "AGENT_VISION_API_KEY": "your-key",
+        "AGENT_VISION_MODEL": "your-vision-model"
+      }
+    }
+  }
+}
+```
+
+### 直接从 GitHub 运行
+
+```json
+{
+  "mcpServers": {
+    "agent-vision": {
+      "command": "npx",
+      "args": ["-y", "github:yanickxia/agent-vision"],
+      "env": {
+        "AGENT_VISION_BASE_URL": "https://your-endpoint.example/v1",
+        "AGENT_VISION_API_KEY": "your-key",
+        "AGENT_VISION_MODEL": "your-vision-model"
+      }
+    }
+  }
+}
+```
+
+Claude Desktop、Claude Code、Cursor、Cline 等使用上面的标准
+`mcpServers` 格式。
+
+### OpenCode
+
+```jsonc
+{
+  "mcp": {
+    "agent-vision": {
+      "type": "local",
+      "command": ["npx", "-y", "@yanickxia/agent-vision"],
+      "enabled": true,
+      "environment": {
+        "AGENT_VISION_BASE_URL": "https://your-endpoint.example/v1",
+        "AGENT_VISION_API_KEY": "your-key",
+        "AGENT_VISION_MODEL": "your-vision-model"
+      }
+    }
+  }
+}
+```
+
+## Agent Skill
+
+```bash
+npx skills add yanickxia/agent-vision --skill agent-vision -g -y
+```
+
+也可以复制 `skills/agent-vision/` 到 Agent 的 skills 目录。Skill 负责告诉
+Agent 何时调用图片/视频工具、如何传参和如何处理失败；MCP 负责实际读取文件、
+抽帧和请求模型。
+
+## CLI
+
+```bash
+npx -y @yanickxia/agent-vision image ./screenshot.png \
+  --prompt "读取报错并给出可能原因"
+
+npx -y @yanickxia/agent-vision video ./demo.mp4 \
+  --prompt "按时间顺序总结 UI 操作" --frames 8
+
+npx -y @yanickxia/agent-vision doctor
+```
+
+## MCP 工具
+
+### `analyze_image`
+
+```json
+{
+  "source": "/absolute/path/to/image.png",
+  "prompt": "这个页面有哪些可用性问题？"
+}
+```
+
+支持 JPEG、PNG、WebP、GIF、BMP。GIF 是否能体现动画取决于视觉模型；需要稳定的
+时间线分析时请转为视频并使用 `analyze_video`。
+
+### `analyze_video`
+
+```json
+{
+  "source": "/absolute/path/to/video.mp4",
+  "prompt": "概括操作流程和关键变化",
+  "max_frames": 8
+}
+```
+
+`max_frames` 范围 1–16，默认 8。实现会均匀抽取 JPEG 帧，并带时间点一起发给
+模型。它不是逐帧转写，快速变化可能被漏掉。
+
+## 隐私与安全
+
+- 图片会发送到你配置的视觉 API。
+- 视频不会整体发给模型；远程视频先下载到本地临时目录，然后只发送抽出的 JPEG 帧。
+- 临时目录在成功或失败后都会删除。
+- 用户提供的远程图片/视频 URL 默认拒绝 localhost、私网、链路本地和云元数据地址。
+- stdio 模式不向 stdout 写日志，避免破坏 MCP 协议。
+
+## 开发
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm pack --dry-run
+```
+
+## License
+
+MIT。第三方依赖保留各自许可证，见 `NOTICE`。

package/dist/analyze.d.ts

@@ -0,0 +1,14 @@
+import type { VisionConfig } from "./config.js";
+import { type VisionCompletion } from "./provider.js";
+export declare function analyzeImage(options: {
+    source: string;
+    prompt?: string;
+    config?: VisionConfig;
+}): Promise<VisionCompletion>;
+export declare function analyzeVideo(options: {
+    source: string;
+    prompt?: string;
+    maxFrames?: number;
+    config?: VisionConfig;
+}): Promise<VisionCompletion>;
+//# sourceMappingURL=analyze.d.ts.map

package/dist/analyze.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../src/analyze.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGhD,OAAO,EAA2B,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAS/E,wBAAsB,YAAY,CAAC,OAAO,EAAE;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAQ5B;AAED,wBAAsB,YAAY,CAAC,OAAO,EAAE;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAe5B"}

package/dist/analyze.js

@@ -0,0 +1,32 @@
+import { loadConfig } from "./config.js";
+import { loadImage } from "./image.js";
+import { requestVisionCompletion } from "./provider.js";
+import { extractVideoFrames } from "./video.js";
+const DEFAULT_IMAGE_PROMPT = "Describe this image accurately. Include visible text, layout, objects, colors, and details relevant to understanding it. Do not invent details that are not visible.";
+const DEFAULT_VIDEO_PROMPT = "Analyze these evenly sampled video frames as one timeline. Describe the sequence of events, scene or UI changes, actions, and visible text. Distinguish observations from uncertainty.";
+export async function analyzeImage(options) {
+    const config = options.config ?? loadConfig();
+    const image = await loadImage(options.source, config);
+    return requestVisionCompletion({
+        config,
+        prompt: options.prompt?.trim() || DEFAULT_IMAGE_PROMPT,
+        images: [{ dataUrl: image.dataUrl, label: image.label }],
+    });
+}
+export async function analyzeVideo(options) {
+    const config = options.config ?? loadConfig();
+    const frames = await extractVideoFrames({
+        source: options.source,
+        maxFrames: options.maxFrames ?? 8,
+        config,
+    });
+    const userPrompt = options.prompt?.trim();
+    return requestVisionCompletion({
+        config,
+        prompt: userPrompt
+            ? `${DEFAULT_VIDEO_PROMPT}\n\nUser question: ${userPrompt}`
+            : DEFAULT_VIDEO_PROMPT,
+        images: frames,
+    });
+}
+//# sourceMappingURL=analyze.js.map

package/dist/analyze.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze.js","sourceRoot":"","sources":["../src/analyze.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,uBAAuB,EAAyB,MAAM,eAAe,CAAC;AAC/E,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEhD,MAAM,oBAAoB,GACxB,sKAAsK,CAAC;AAEzK,MAAM,oBAAoB,GACxB,wLAAwL,CAAC;AAE3L,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,OAIlC;IACC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,UAAU,EAAE,CAAC;IAC9C,MAAM,KAAK,GAAG,MAAM,SAAS,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtD,OAAO,uBAAuB,CAAC;QAC7B,MAAM;QACN,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,oBAAoB;QACtD,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC;KACzD,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,OAKlC;IACC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,UAAU,EAAE,CAAC;IAC9C,MAAM,MAAM,GAAG,MAAM,kBAAkB,CAAC;QACtC,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,CAAC;QACjC,MAAM;KACP,CAAC,CAAC;IACH,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC;IAC1C,OAAO,uBAAuB,CAAC;QAC7B,MAAM;QACN,MAAM,EAAE,UAAU;YAChB,CAAC,CAAC,GAAG,oBAAoB,sBAAsB,UAAU,EAAE;YAC3D,CAAC,CAAC,oBAAoB;QACxB,MAAM,EAAE,MAAM;KACf,CAAC,CAAC;AACL,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+import { analyzeImage, analyzeVideo } from "./analyze.js";
+import { loadConfig } from "./config.js";
+import { errorMessage } from "./errors.js";
+import { SERVER_VERSION, startStdioServer } from "./server.js";
+import { ensureFfmpeg } from "./video.js";
+const HELP = `agent-vision ${SERVER_VERSION}
+
+Usage:
+  agent-vision                         Start the MCP stdio server
+  agent-vision image <source> [options]
+  agent-vision video <source> [options]
+  agent-vision doctor
+
+Options:
+  -p, --prompt <text>                  Question or focus for the analysis
+  --frames <1-16>                      Video frames to sample (default: 8)
+  -h, --help                           Show help
+  -v, --version                        Show version
+`;
+function option(args, long, short) {
+    const prefix = `${long}=`;
+    const inline = args.find((arg) => arg.startsWith(prefix));
+    if (inline)
+        return inline.slice(prefix.length);
+    const index = args.findIndex((arg) => arg === long || (short && arg === short));
+    return index >= 0 ? args[index + 1] : undefined;
+}
+async function runCli(args) {
+    const command = args[0];
+    if (!command) {
+        await startStdioServer();
+        return;
+    }
+    if (command === "--help" || command === "-h" || command === "help") {
+        process.stdout.write(HELP);
+        return;
+    }
+    if (command === "--version" || command === "-v") {
+        process.stdout.write(`${SERVER_VERSION}\n`);
+        return;
+    }
+    if (command === "doctor") {
+        const config = loadConfig();
+        let ffmpeg = "unavailable";
+        try {
+            ffmpeg = await ensureFfmpeg();
+        }
+        catch {
+            // Report below without failing before the full doctor output is printed.
+        }
+        const report = [
+            `model: ${config.model || "missing"}`,
+            `base URL: ${config.baseUrl}`,
+            `API key: ${config.apiKey ? "configured" : "not configured (allowed for local endpoints)"}`,
+            `ffmpeg: ${ffmpeg}`,
+        ];
+        process.stdout.write(`${report.join("\n")}\n`);
+        if (!config.model || ffmpeg === "unavailable")
+            process.exitCode = 1;
+        return;
+    }
+    if (command !== "image" && command !== "video") {
+        throw new Error(`Unknown command: ${command}\n\n${HELP}`);
+    }
+    const source = args[1];
+    if (!source || source.startsWith("-")) {
+        throw new Error(`${command} requires a source path or URL`);
+    }
+    const prompt = option(args.slice(2), "--prompt", "-p");
+    if (command === "image") {
+        const result = await analyzeImage({ source, ...(prompt ? { prompt } : {}) });
+        process.stdout.write(`${result.text}\n`);
+        return;
+    }
+    const framesRaw = option(args.slice(2), "--frames");
+    const maxFrames = framesRaw ? Number(framesRaw) : undefined;
+    const result = await analyzeVideo({
+        source,
+        ...(prompt ? { prompt } : {}),
+        ...(maxFrames !== undefined ? { maxFrames } : {}),
+    });
+    process.stdout.write(`${result.text}\n`);
+}
+runCli(process.argv.slice(2)).catch((error) => {
+    process.stderr.write(`agent-vision: ${errorMessage(error)}\n`);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C,MAAM,IAAI,GAAG,gBAAgB,cAAc;;;;;;;;;;;;;CAa1C,CAAC;AAEF,SAAS,MAAM,CAAC,IAAc,EAAE,IAAY,EAAE,KAAc;IAC1D,MAAM,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC;IAC1B,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;IAC1D,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC/C,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,IAAI,IAAI,CAAC,KAAK,IAAI,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC;IAChF,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAClD,CAAC;AAED,KAAK,UAAU,MAAM,CAAC,IAAc;IAClC,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACxB,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,gBAAgB,EAAE,CAAC;QACzB,OAAO;IACT,CAAC;IACD,IAAI,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QACnE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC3B,OAAO;IACT,CAAC;IACD,IAAI,OAAO,KAAK,WAAW,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QAChD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,cAAc,IAAI,CAAC,CAAC;QAC5C,OAAO;IACT,CAAC;IACD,IAAI,OAAO,KAAK,QAAQ,EAAE,CAAC;QACzB,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;QAC5B,IAAI,MAAM,GAAG,aAAa,CAAC;QAC3B,IAAI,CAAC;YACH,MAAM,GAAG,MAAM,YAAY,EAAE,CAAC;QAChC,CAAC;QAAC,MAAM,CAAC;YACP,yEAAyE;QAC3E,CAAC;QACD,MAAM,MAAM,GAAG;YACb,UAAU,MAAM,CAAC,KAAK,IAAI,SAAS,EAAE;YACrC,aAAa,MAAM,CAAC,OAAO,EAAE;YAC7B,YAAY,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,8CAA8C,EAAE;YAC3F,WAAW,MAAM,EAAE;SACpB,CAAC;QACF,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC/C,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,MAAM,KAAK,aAAa;YAAE,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACpE,OAAO;IACT,CAAC;IACD,IAAI,OAAO,KAAK,OAAO,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC;QAC/C,MAAM,IAAI,KAAK,CAAC,oBAAoB,OAAO,OAAO,IAAI,EAAE,CAAC,CAAC;IAC5D,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACvB,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,GAAG,OAAO,gCAAgC,CAAC,CAAC;IAC9D,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,CAAC;IACvD,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC;QACxB,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QAC7E,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC;QACzC,OAAO;IACT,CAAC;IACD,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;IACpD,MAAM,SAAS,GAAG,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC5D,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC;QAChC,MAAM;QACN,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7B,GAAG,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAClD,CAAC,CAAC;IACH,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC;AAC3C,CAAC;AAED,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IAC5C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,iBAAiB,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC/D,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CAAC,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,17 @@
+export interface VisionConfig {
+    apiKey?: string;
+    baseUrl: string;
+    model: string;
+    maxTokens: number;
+    timeoutMs: number;
+    headers: Record<string, string>;
+    maxImageBytes: number;
+    maxVideoBytes: number;
+    allowPrivateUrls: boolean;
+}
+type Environment = Record<string, string | undefined>;
+export declare function loadConfig(env?: Environment): VisionConfig;
+export declare function requireModel(config: VisionConfig): void;
+export declare function chatCompletionsUrl(baseUrl: string): string;
+export {};
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED,KAAK,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAgDtD,wBAAgB,UAAU,CAAC,GAAG,GAAE,WAAyB,GAAG,YAAY,CAiCvE;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAOvD;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAqB1D"}

package/dist/config.js

@@ -0,0 +1,92 @@
+import { VisionError } from "./errors.js";
+function firstNonEmpty(env, names) {
+    for (const name of names) {
+        const value = env[name]?.trim();
+        if (value)
+            return value;
+    }
+    return undefined;
+}
+function positiveInteger(env, name, fallback) {
+    const raw = env[name]?.trim();
+    if (!raw)
+        return fallback;
+    const value = Number(raw);
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new VisionError("CONFIG_ERROR", `${name} must be a positive integer`);
+    }
+    return value;
+}
+function parseHeaders(raw) {
+    if (!raw?.trim())
+        return {};
+    try {
+        const value = JSON.parse(raw);
+        if (!value || Array.isArray(value) || typeof value !== "object") {
+            throw new Error("expected a JSON object");
+        }
+        const headers = {};
+        for (const [key, headerValue] of Object.entries(value)) {
+            if (typeof headerValue !== "string") {
+                throw new Error(`header ${key} must be a string`);
+            }
+            headers[key] = headerValue;
+        }
+        return headers;
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new VisionError("CONFIG_ERROR", `AGENT_VISION_HEADERS must be a JSON object of string values: ${detail}`);
+    }
+}
+export function loadConfig(env = process.env) {
+    const apiKey = firstNonEmpty(env, [
+        "AGENT_VISION_API_KEY",
+        "VISION_API_KEY",
+        "OPENAI_API_KEY",
+    ]);
+    const baseUrl = firstNonEmpty(env, [
+        "AGENT_VISION_BASE_URL",
+        "VISION_BASE_URL",
+        "OPENAI_BASE_URL",
+    ]) ?? "https://api.openai.com/v1";
+    const model = firstNonEmpty(env, [
+        "AGENT_VISION_MODEL",
+        "VISION_MODEL",
+        "OPENAI_MODEL",
+    ]) ?? "";
+    return {
+        ...(apiKey ? { apiKey } : {}),
+        baseUrl,
+        model,
+        maxTokens: positiveInteger(env, "AGENT_VISION_MAX_TOKENS", 4096),
+        timeoutMs: positiveInteger(env, "AGENT_VISION_TIMEOUT_MS", 120_000),
+        headers: parseHeaders(env.AGENT_VISION_HEADERS),
+        maxImageBytes: positiveInteger(env, "AGENT_VISION_MAX_IMAGE_MB", 20) * 1024 * 1024,
+        maxVideoBytes: positiveInteger(env, "AGENT_VISION_MAX_VIDEO_MB", 200) * 1024 * 1024,
+        allowPrivateUrls: env.AGENT_VISION_ALLOW_PRIVATE_URLS?.trim().toLowerCase() === "true",
+    };
+}
+export function requireModel(config) {
+    if (!config.model) {
+        throw new VisionError("CONFIG_ERROR", "Set AGENT_VISION_MODEL (or VISION_MODEL / OPENAI_MODEL)");
+    }
+}
+export function chatCompletionsUrl(baseUrl) {
+    let url;
+    try {
+        url = new URL(baseUrl);
+    }
+    catch {
+        throw new VisionError("CONFIG_ERROR", `Invalid AGENT_VISION_BASE_URL: ${baseUrl}`);
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new VisionError("CONFIG_ERROR", "AGENT_VISION_BASE_URL must use http or https");
+    }
+    const path = url.pathname.replace(/\/+$/, "");
+    if (!path.endsWith("/chat/completions")) {
+        url.pathname = `${path}/chat/completions`;
+    }
+    return url.toString();
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,6 @@
+export declare class VisionError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string, options?: ErrorOptions);
+}
+export declare function errorMessage(error: unknown): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAKlE;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAQnD"}

package/dist/errors.js

@@ -0,0 +1,18 @@
+export class VisionError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = "VisionError";
+        this.code = code;
+    }
+}
+export function errorMessage(error) {
+    if (error instanceof VisionError) {
+        return `${error.code}: ${error.message}`;
+    }
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,WAAY,SAAQ,KAAK;IAC3B,IAAI,CAAS;IAEtB,YAAY,IAAY,EAAE,OAAe,EAAE,OAAsB;QAC/D,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,IAAI,KAAK,YAAY,WAAW,EAAE,CAAC;QACjC,OAAO,GAAG,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;IAC3C,CAAC;IACD,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,OAAO,KAAK,CAAC,OAAO,CAAC;IACvB,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC"}

package/dist/image.d.ts

@@ -0,0 +1,9 @@
+import type { VisionConfig } from "./config.js";
+export interface LoadedImage {
+    dataUrl: string;
+    mimeType: string;
+    bytes: number;
+    label: string;
+}
+export declare function loadImage(source: string, config: VisionConfig): Promise<LoadedImage>;
+//# sourceMappingURL=image.d.ts.map

package/dist/image.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image.d.ts","sourceRoot":"","sources":["../src/image.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAIhD,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AA8ED,wBAAsB,SAAS,CAC7B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,WAAW,CAAC,CAqCtB"}

package/dist/image.js

@@ -0,0 +1,108 @@
+import { readFile, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import { VisionError } from "./errors.js";
+import { fetchRemoteBuffer } from "./network.js";
+const SUPPORTED_MIME_TYPES = new Set([
+    "image/jpeg",
+    "image/png",
+    "image/webp",
+    "image/gif",
+    "image/bmp",
+]);
+function mimeFromMagic(buffer) {
+    if (buffer.length >= 3 && buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff) {
+        return "image/jpeg";
+    }
+    if (buffer.length >= 8 &&
+        buffer.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) {
+        return "image/png";
+    }
+    if (buffer.length >= 12 && buffer.toString("ascii", 0, 4) === "RIFF" && buffer.toString("ascii", 8, 12) === "WEBP") {
+        return "image/webp";
+    }
+    if (buffer.length >= 6 && /^GIF8[79]a$/.test(buffer.toString("ascii", 0, 6))) {
+        return "image/gif";
+    }
+    if (buffer.length >= 2 && buffer.toString("ascii", 0, 2) === "BM") {
+        return "image/bmp";
+    }
+    return undefined;
+}
+function expandLocalPath(source) {
+    const withoutAt = source.startsWith("@") ? source.slice(1) : source;
+    if (withoutAt === "~")
+        return homedir();
+    if (withoutAt.startsWith("~/")) {
+        return path.join(homedir(), withoutAt.slice(2));
+    }
+    return path.resolve(withoutAt);
+}
+function toLoadedImage(buffer, label, declaredMime) {
+    const detectedMime = mimeFromMagic(buffer);
+    const normalizedDeclared = declaredMime?.toLowerCase();
+    const mimeType = detectedMime ??
+        (normalizedDeclared && SUPPORTED_MIME_TYPES.has(normalizedDeclared)
+            ? normalizedDeclared
+            : undefined);
+    if (!mimeType) {
+        throw new VisionError("UNSUPPORTED_IMAGE", "Unsupported or invalid image. Supported formats: JPEG, PNG, WebP, GIF, BMP");
+    }
+    return {
+        dataUrl: `data:${mimeType};base64,${buffer.toString("base64")}`,
+        mimeType,
+        bytes: buffer.length,
+        label,
+    };
+}
+function parseDataUri(source, maxBytes) {
+    const match = source.match(/^data:(image\/[a-z0-9.+-]+);base64,([a-z0-9+/=\s]+)$/i);
+    if (!match?.[1] || !match[2]) {
+        throw new VisionError("INVALID_SOURCE", "Invalid base64 image data URI");
+    }
+    const compact = match[2].replace(/\s/g, "");
+    if (compact.length % 4 !== 0) {
+        throw new VisionError("INVALID_SOURCE", "Invalid base64 image data URI");
+    }
+    const buffer = Buffer.from(compact, "base64");
+    if (buffer.length > maxBytes) {
+        throw new VisionError("SOURCE_TOO_LARGE", "Image data URI exceeds the configured limit");
+    }
+    return toLoadedImage(buffer, "data-uri", match[1]);
+}
+export async function loadImage(source, config) {
+    const trimmed = source.trim();
+    if (!trimmed) {
+        throw new VisionError("INVALID_SOURCE", "Image source cannot be empty");
+    }
+    if (trimmed.startsWith("data:")) {
+        return parseDataUri(trimmed, config.maxImageBytes);
+    }
+    if (/^https?:\/\//i.test(trimmed)) {
+        const remote = await fetchRemoteBuffer({
+            url: trimmed,
+            maxBytes: config.maxImageBytes,
+            timeoutMs: config.timeoutMs,
+            allowPrivateUrls: config.allowPrivateUrls,
+        });
+        return toLoadedImage(remote.buffer, trimmed, remote.contentType);
+    }
+    const filePath = expandLocalPath(trimmed);
+    let fileStat;
+    try {
+        fileStat = await stat(filePath);
+    }
+    catch (error) {
+        throw new VisionError("FILE_NOT_FOUND", `Image file not found: ${filePath}`, {
+            cause: error,
+        });
+    }
+    if (!fileStat.isFile()) {
+        throw new VisionError("INVALID_SOURCE", `Not a file: ${filePath}`);
+    }
+    if (fileStat.size > config.maxImageBytes) {
+        throw new VisionError("SOURCE_TOO_LARGE", `Image is ${(fileStat.size / 1024 / 1024).toFixed(1)} MB; limit is ${(config.maxImageBytes / 1024 / 1024).toFixed(1)} MB`);
+    }
+    return toLoadedImage(await readFile(filePath), path.basename(filePath));
+}
+//# sourceMappingURL=image.js.map