@kairyou/agent-tools 0.1.0 → 0.2.0

package/lib/usage.mjs

@@ -14,7 +14,7 @@ const CODEX_HOME = process.env.CODEX_HOME || join(homedir(), ".codex");
 const AGENT_TOOLS_HOME = process.env.AGENT_TOOLS_HOME || join(homedir(), ".agent-tools");
 const AUTH_PATH = join(CODEX_HOME, "auth.json");
 const CODEX_CONFIG_PATH = join(CODEX_HOME, "config.toml");
-const AGENT_CONFIG_PATH = process.env.AGENT_TOOLS_CONFIG || join(AGENT_TOOLS_HOME, "config.jsonc");
+const AGENT_CONFIG_PATH = join(AGENT_TOOLS_HOME, "config.jsonc");
 const DEBUG_PATH = join(AGENT_TOOLS_HOME, "logs", "usage-debug.log");
 const ROUTE_CACHE_PATH = join(AGENT_TOOLS_HOME, "cache", "usage-routes.json");
 const SNAPSHOT_PATH = join(AGENT_TOOLS_HOME, "cache", "usage-snapshot.json");

package/lib/vision/cli.mjs

@@ -0,0 +1,137 @@
+// `agent-tools inspect-image` and the installed agent fallback entry for the
+// vision runtime. MCP remains preferred; this direct entry covers hosts or
+// model gateways that cannot invoke MCP namespace tools.
+//
+// Usage:
+//   agent-tools inspect-image <path|url> --question "<text>" [--question "..."]
+//   agent-tools inspect-image --request-file <request.json> [--json]
+//
+// Options:
+//   -q, --question <text>   Question about the image (repeatable with a target).
+//   --request-file <path>   Read MCP-shaped { image_source, questions } JSON.
+//   --json                  Print the raw JSON result only.
+//   -h, --help              Show this help.
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createVisionService } from "./inspect.mjs";
+import { isVisionError } from "./errors.mjs";
+
+function printHelp() {
+  const lines = [];
+  for (const line of fs.readFileSync(fileURLToPath(import.meta.url), "utf8").split("\n")) {
+    if (line.startsWith("//")) lines.push(line.replace(/^\/\/ ?/, ""));
+    else if (lines.length) break;
+  }
+  console.log(lines.join("\n"));
+}
+
+function parseArgs(argv) {
+  const opts = { target: null, questions: [], requestFile: null, json: false, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    switch (a) {
+      case "-q":
+      case "--question": {
+        const value = argv[++i];
+        if (!value) {
+          console.error(`Missing value for ${a}`);
+          process.exit(2);
+        }
+        opts.questions.push(value);
+        break;
+      }
+      case "--json": opts.json = true; break;
+      case "--request-file": {
+        const value = argv[++i];
+        if (!value) {
+          console.error("Missing value for --request-file");
+          process.exit(2);
+        }
+        opts.requestFile = value;
+        break;
+      }
+      case "-h":
+      case "--help": opts.help = true; break;
+      default:
+        if (a.startsWith("-")) {
+          console.error(`Unknown option: ${a}`);
+          process.exit(2);
+        }
+        if (opts.target) {
+          console.error(`Unexpected extra argument: ${a} (one image per call)`);
+          process.exit(2);
+        }
+        opts.target = a;
+    }
+  }
+  return opts;
+}
+
+export async function runInspectImageCli(argv) {
+  const opts = parseArgs(argv);
+  if (opts.help || (!opts.target && !opts.requestFile && opts.questions.length === 0)) {
+    printHelp();
+    return opts.help ? 0 : 2;
+  }
+  if (opts.requestFile && (opts.target || opts.questions.length > 0)) {
+    console.error("--request-file cannot be combined with <path|url> or --question.");
+    return 2;
+  }
+
+  try {
+    let imageSource;
+    let questions;
+    if (opts.requestFile) {
+      const requestPath = path.resolve(opts.requestFile);
+      let request;
+      try {
+        request = JSON.parse(fs.readFileSync(requestPath, "utf8"));
+      } catch (err) {
+        console.error(`Cannot read --request-file ${requestPath}: ${err.message}`);
+        return 2;
+      }
+      imageSource = request?.image_source;
+      questions = request?.questions;
+    } else {
+      if (!opts.target) {
+        console.error("Missing <path|url> argument.");
+        return 2;
+      }
+      if (opts.questions.length === 0) {
+        console.error('Missing --question. Example: --question "What error code is shown?"');
+        return 2;
+      }
+      const type = /^https?:\/\//i.test(opts.target) ? "url" : "file";
+      imageSource = { type, value: opts.target };
+      questions = opts.questions.map((text, i) => ({ id: `q${i + 1}`, text }));
+    }
+
+    const service = createVisionService();
+    const result = await service.inspect({
+      image_source: imageSource,
+      questions,
+    });
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return 0;
+    }
+    console.log(`request_id: ${result.request_id}`);
+    for (const answer of result.answers) {
+      const q = questions.find((x) => x.id === answer.question_id);
+      console.log(`\n${answer.question_id}: ${q ? q.text : ""}`);
+      console.log(`  answer: ${answer.answer === null ? "(none)" : answer.answer}`);
+      if (answer.uncertainty) console.log(`  uncertainty: ${answer.uncertainty}`);
+    }
+    return 0;
+  } catch (err) {
+    const code = isVisionError(err) ? err.code : "internal_error";
+    console.error(`[${code}] ${err.message}`);
+    return 1;
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  process.exitCode = await runInspectImageCli(process.argv.slice(2));
+}

package/lib/vision/config.mjs

@@ -0,0 +1,159 @@
+// Vision configuration loader. The single source of truth is
+// ~/.agent-tools/config.jsonc (override root with AGENT_TOOLS_HOME). No
+// implicit environment fallback: `apiKey` is either a literal string or an
+// explicit `{ "env": "VARIABLE_NAME" }` secret reference declared in the file.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { parse as parseJsonc } from "jsonc-parser";
+import { ERROR_CODES, VisionError } from "./errors.mjs";
+
+export const PROVIDERS = Object.freeze(["openai-compatible", "anthropic-compatible"]);
+
+export const CONFIG_DEFAULTS = Object.freeze({
+  timeoutMs: 30000,
+  maxImageBytes: 20 * 1024 * 1024,
+  maxConcurrentRequests: 2,
+  maxRequestsPerMinute: 30,
+  // Sent to both providers (Anthropic requires max_tokens; OpenAI gateway
+  // defaults are unpredictable). Lower it if your model caps output smaller.
+  maxOutputTokens: 8192,
+});
+
+const CONFIG_TEMPLATE = `{
+  "vision": {
+    "provider": "openai-compatible",        // or "anthropic-compatible"
+    "baseUrl": "https://gateway.example.com/v1",
+    "model": "internal-vlm",
+    "apiKey": { "env": "OPENAI_API_KEY" }   // or a literal string
+  }
+}`;
+
+export function agentToolsHome(env = process.env) {
+  return env.AGENT_TOOLS_HOME || path.join(os.homedir(), ".agent-tools");
+}
+
+export function configPath(env = process.env) {
+  return path.join(agentToolsHome(env), "config.jsonc");
+}
+
+function configError(message) {
+  return new VisionError(
+    ERROR_CODES.CONFIG,
+    `${message}\nAdd a "vision" block to ${configPath()} , for example:\n${CONFIG_TEMPLATE}`
+  );
+}
+
+// Resolve `apiKey` per the secret reference rules. Returns the secret string,
+// or null when the gateway does not require a key (field omitted).
+export function resolveSecret(apiKey, env = process.env) {
+  if (apiKey === undefined || apiKey === null) return null;
+  if (typeof apiKey === "string") {
+    if (apiKey.trim() === "") {
+      throw new VisionError(ERROR_CODES.CONFIG, "vision.apiKey is an empty string; remove it or set a value.");
+    }
+    return apiKey;
+  }
+  if (typeof apiKey === "object" && typeof apiKey.env === "string" && apiKey.env.trim() !== "") {
+    const name = apiKey.env;
+    const value = env[name];
+    if (value === undefined || value === "") {
+      // Name the variable, never its (missing) value; no silent fallback.
+      throw new VisionError(
+        ERROR_CODES.CONFIG,
+        `vision.apiKey references environment variable "${name}", which is not set or empty.`
+      );
+    }
+    return value;
+  }
+  throw new VisionError(
+    ERROR_CODES.CONFIG,
+    'vision.apiKey must be a string or { "env": "VARIABLE_NAME" }.'
+  );
+}
+
+function positiveInt(raw, name, fallback, { allowZero = false } = {}) {
+  if (raw === undefined || raw === null) return fallback;
+  if (!Number.isInteger(raw) || raw < 0 || (!allowZero && raw === 0)) {
+    throw new VisionError(
+      ERROR_CODES.CONFIG,
+      `vision.${name} must be a positive integer${allowZero ? " (0 disables it)" : ""}.`
+    );
+  }
+  return raw;
+}
+
+function normalizeBaseUrl(raw) {
+  if (typeof raw !== "string") throw configError("vision.baseUrl must be an http(s) URL.");
+  let parsed;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    throw configError("vision.baseUrl must be an http(s) URL.");
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw configError("vision.baseUrl must be an http(s) URL.");
+  }
+  if (parsed.username || parsed.password) {
+    throw configError("vision.baseUrl must not contain credentials.");
+  }
+  if (parsed.search || parsed.hash) {
+    throw configError("vision.baseUrl must not contain a query string or fragment.");
+  }
+  return parsed.toString().replace(/\/+$/, "");
+}
+
+// Load and validate the vision config. `file`/`env` are injectable for tests.
+export function loadVisionConfig({ file, env = process.env } = {}) {
+  const target = file || configPath(env);
+  if (!fs.existsSync(target)) {
+    throw configError(`Config file not found: ${target}`);
+  }
+  let raw;
+  try {
+    raw = fs.readFileSync(target, "utf8").replace(/^/, "");
+  } catch (err) {
+    throw configError(`Cannot read ${target}: ${err.message}`);
+  }
+  const errors = [];
+  const parsed = parseJsonc(raw, errors, { allowTrailingComma: true });
+  if (errors.length > 0 || !parsed || typeof parsed !== "object") {
+    throw configError(`Cannot parse ${target} as JSONC.`);
+  }
+  const vision = parsed.vision;
+  if (!vision || typeof vision !== "object") {
+    throw configError(`Missing "vision" section in ${target}.`);
+  }
+  if (!PROVIDERS.includes(vision.provider)) {
+    throw configError(
+      `vision.provider must be one of: ${PROVIDERS.join(", ")} (got ${JSON.stringify(vision.provider ?? null)}).`
+    );
+  }
+  const baseUrl = normalizeBaseUrl(vision.baseUrl);
+  if (typeof vision.model !== "string" || vision.model.trim() === "") {
+    throw configError("vision.model must be a non-empty string.");
+  }
+
+  return {
+    provider: vision.provider,
+    baseUrl,
+    model: vision.model,
+    apiKey: resolveSecret(vision.apiKey, env),
+    timeoutMs: positiveInt(vision.timeoutMs, "timeoutMs", CONFIG_DEFAULTS.timeoutMs),
+    maxImageBytes: positiveInt(vision.maxImageBytes, "maxImageBytes", CONFIG_DEFAULTS.maxImageBytes),
+    maxConcurrentRequests: positiveInt(
+      vision.maxConcurrentRequests,
+      "maxConcurrentRequests",
+      CONFIG_DEFAULTS.maxConcurrentRequests
+    ),
+    // 0 disables the rolling-window limit; concurrency has no disable switch.
+    maxRequestsPerMinute: positiveInt(
+      vision.maxRequestsPerMinute,
+      "maxRequestsPerMinute",
+      CONFIG_DEFAULTS.maxRequestsPerMinute,
+      { allowZero: true }
+    ),
+    maxOutputTokens: positiveInt(vision.maxOutputTokens, "maxOutputTokens", CONFIG_DEFAULTS.maxOutputTokens),
+  };
+}

package/lib/vision/errors.mjs

@@ -0,0 +1,35 @@
+// Normalized error type for the vision runtime. Every failure surfaced to the
+// MCP tool, the diagnostic CLI, or tests carries a stable `code` so callers can
+// branch on category without parsing prose.
+
+export const ERROR_CODES = Object.freeze({
+  CONFIG: "config_error",
+  INPUT: "input_error",
+  FETCH: "fetch_error",
+  RATE_LIMIT: "rate_limit_error",
+  PROVIDER_AUTH: "provider_auth_error",
+  PROVIDER_HTTP: "provider_http_error",
+  PROVIDER_TIMEOUT: "provider_timeout_error",
+  PROVIDER_RESPONSE: "provider_response_error",
+});
+
+export class VisionError extends Error {
+  constructor(code, message, { cause, detail } = {}) {
+    super(message, cause ? { cause } : undefined);
+    this.name = "VisionError";
+    this.code = code;
+    if (detail !== undefined) this.detail = detail;
+  }
+}
+
+export function isVisionError(err) {
+  return err instanceof VisionError;
+}
+
+// Wrap unknown failures so callers always see a VisionError. Existing
+// VisionErrors pass through untouched.
+export function toVisionError(err, fallbackCode = ERROR_CODES.PROVIDER_HTTP) {
+  if (isVisionError(err)) return err;
+  const message = err && typeof err.message === "string" ? err.message : String(err);
+  return new VisionError(fallbackCode, message, { cause: err });
+}

package/lib/vision/image-source.mjs

@@ -0,0 +1,273 @@
+// Image acquisition: explicit local file paths and http(s) URLs only. No
+// directory enumeration, globbing, or implicit search — the caller must name
+// one concrete image. URLs are unrestricted by host/IP (personal local tool);
+// protection is resource-based: timeout, redirect cap, size cap, and image
+// signature validation.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { ERROR_CODES, VisionError } from "./errors.mjs";
+
+export const SUPPORTED_MEDIA_TYPES = Object.freeze([
+  "image/png",
+  "image/jpeg",
+  "image/webp",
+  "image/gif",
+]);
+
+const MAX_REDIRECTS = 5;
+
+// Identify the image type from magic bytes; extensions and Content-Type
+// headers are hints only and are never trusted.
+export function sniffMediaType(bytes) {
+  if (!bytes || bytes.length < 12) return null;
+  if (bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47) {
+    return "image/png";
+  }
+  if (bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) {
+    return "image/jpeg";
+  }
+  if (
+    bytes[0] === 0x52 && bytes[1] === 0x49 && bytes[2] === 0x46 && bytes[3] === 0x46 &&
+    bytes[8] === 0x57 && bytes[9] === 0x45 && bytes[10] === 0x42 && bytes[11] === 0x50
+  ) {
+    return "image/webp";
+  }
+  if (bytes[0] === 0x47 && bytes[1] === 0x49 && bytes[2] === 0x46 && bytes[3] === 0x38) {
+    return "image/gif";
+  }
+  return null;
+}
+
+function validateImageHeader(header, byteLength, origin, maxImageBytes) {
+  if (byteLength === 0) {
+    throw new VisionError(ERROR_CODES.INPUT, `${origin} is empty.`);
+  }
+  if (byteLength > maxImageBytes) {
+    throw new VisionError(
+      ERROR_CODES.INPUT,
+      `${origin} is ${byteLength} bytes, over the ${maxImageBytes}-byte limit (vision.maxImageBytes).`
+    );
+  }
+  const mediaType = sniffMediaType(header);
+  if (!mediaType) {
+    throw new VisionError(
+      ERROR_CODES.INPUT,
+      `${origin} is not a supported image (expected PNG, JPEG, WebP, or GIF).`
+    );
+  }
+  return mediaType;
+}
+
+function loadFile(value, maxImageBytes) {
+  const resolved = path.resolve(value);
+  let stat;
+  try {
+    stat = fs.statSync(resolved);
+  } catch {
+    throw new VisionError(ERROR_CODES.INPUT, `Image file not found: ${resolved}`);
+  }
+  if (!stat.isFile()) {
+    throw new VisionError(ERROR_CODES.INPUT, `Not a file: ${resolved} (directories are not accepted).`);
+  }
+  if (stat.size > maxImageBytes) {
+    throw new VisionError(
+      ERROR_CODES.INPUT,
+      `${resolved} is ${stat.size} bytes, over the ${maxImageBytes}-byte limit (vision.maxImageBytes).`
+    );
+  }
+  let handle;
+  try {
+    handle = fs.openSync(resolved, "r");
+    const header = Buffer.alloc(12);
+    const headerLength = fs.readSync(handle, header, 0, header.length, 0);
+    const mediaType = validateImageHeader(
+      header.subarray(0, headerLength),
+      stat.size,
+      resolved,
+      maxImageBytes
+    );
+    let disposed = false;
+    return {
+      mediaType,
+      byteLength: stat.size,
+      createReadStream: () => fs.createReadStream(resolved, { fd: handle, autoClose: false, start: 0 }),
+      dispose() {
+        if (disposed) return;
+        disposed = true;
+        fs.closeSync(handle);
+      },
+    };
+  } catch (err) {
+    if (handle !== undefined) fs.closeSync(handle);
+    if (err instanceof VisionError) throw err;
+    throw new VisionError(ERROR_CODES.INPUT, `Cannot read ${resolved}: ${err.message}`);
+  }
+}
+
+async function downloadCapped(response, url, maxImageBytes) {
+  const declared = Number(response.headers.get("content-length"));
+  if (Number.isFinite(declared) && declared > maxImageBytes) {
+    throw new VisionError(
+      ERROR_CODES.INPUT,
+      `${url} declares ${declared} bytes, over the ${maxImageBytes}-byte limit (vision.maxImageBytes).`
+    );
+  }
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "agent-tools-vision-"));
+  const tempFile = path.join(tempDir, "image");
+  const handle = await fs.promises.open(tempFile, "wx", 0o600);
+  const header = Buffer.alloc(12);
+  let headerLength = 0;
+  let total = 0;
+  try {
+    for await (const value of response.body) {
+      const chunk = Buffer.from(value);
+      total += chunk.length;
+      if (total > maxImageBytes) {
+        throw new VisionError(
+          ERROR_CODES.INPUT,
+          `${url} exceeded the ${maxImageBytes}-byte limit (vision.maxImageBytes) while downloading.`
+        );
+      }
+      if (headerLength < header.length) {
+        const copied = chunk.copy(header, headerLength, 0, header.length - headerLength);
+        headerLength += copied;
+      }
+      let offset = 0;
+      while (offset < chunk.length) {
+        const { bytesWritten } = await handle.write(chunk, offset, chunk.length - offset, null);
+        if (bytesWritten === 0) throw new Error(`Could not write downloaded image data for ${url}.`);
+        offset += bytesWritten;
+      }
+    }
+  } catch (error) {
+    await handle.close().catch(() => {});
+    fs.rmSync(tempDir, { recursive: true, force: true });
+    throw error;
+  }
+  await handle.close();
+  let mediaType;
+  try {
+    mediaType = validateImageHeader(header.subarray(0, headerLength), total, url, maxImageBytes);
+  } catch (error) {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+    throw error;
+  }
+  let disposed = false;
+  return {
+    mediaType,
+    byteLength: total,
+    tempFile,
+    createReadStream: () => fs.createReadStream(tempFile),
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    },
+  };
+}
+
+function requireHttpUrl(value, code, message) {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new VisionError(code, message);
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new VisionError(code, message);
+  }
+  return parsed;
+}
+
+async function discardRedirectBody(response) {
+  if (response.body && typeof response.body.cancel === "function") {
+    try {
+      await response.body.cancel();
+    } catch {
+      // Redirect metadata remains usable even if connection cleanup fails.
+    }
+  }
+}
+
+async function loadUrl(value, { maxImageBytes, timeoutMs, fetchImpl }) {
+  const invalidInitial = `Only valid http(s) URLs are supported: ${value}`;
+  let current = requireHttpUrl(value, ERROR_CODES.INPUT, invalidInitial);
+
+  const doFetch = fetchImpl || fetch;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+      let response;
+      try {
+        response = await doFetch(current.href, { redirect: "manual", signal: controller.signal });
+      } catch (err) {
+        if (controller.signal.aborted) {
+          throw new VisionError(ERROR_CODES.FETCH, `Timed out fetching ${current.href} after ${timeoutMs}ms.`);
+        }
+        throw new VisionError(ERROR_CODES.FETCH, `Cannot fetch ${current.href}: ${err.message}`, { cause: err });
+      }
+      if (response.status >= 300 && response.status < 400) {
+        const location = response.headers.get("location");
+        if (!location) {
+          await discardRedirectBody(response);
+          throw new VisionError(ERROR_CODES.FETCH, `${current.href} redirected without a Location header.`);
+        }
+        if (hop === MAX_REDIRECTS) {
+          await discardRedirectBody(response);
+          throw new VisionError(ERROR_CODES.FETCH, `${value} exceeded ${MAX_REDIRECTS} redirects.`);
+        }
+        let redirected;
+        try {
+          redirected = new URL(location, current);
+        } catch {
+          await discardRedirectBody(response);
+          throw new VisionError(ERROR_CODES.FETCH, `${current.href} redirected to an invalid URL: ${location}`);
+        }
+        if (redirected.protocol !== "http:" && redirected.protocol !== "https:") {
+          await discardRedirectBody(response);
+          throw new VisionError(
+            ERROR_CODES.FETCH,
+            `${current.href} redirected to unsupported protocol ${redirected.protocol}`
+          );
+        }
+        await discardRedirectBody(response);
+        current = redirected;
+        continue;
+      }
+      if (!response.ok) {
+        throw new VisionError(ERROR_CODES.FETCH, `${current.href} returned HTTP ${response.status}.`);
+      }
+      try {
+        return await downloadCapped(response, current.href, maxImageBytes);
+      } catch (err) {
+        if (err instanceof VisionError) throw err;
+        if (controller.signal.aborted) {
+          throw new VisionError(ERROR_CODES.FETCH, `Timed out fetching ${current.href} after ${timeoutMs}ms.`);
+        }
+        throw new VisionError(ERROR_CODES.FETCH, `Cannot read ${current.href}: ${err.message}`, { cause: err });
+      }
+    }
+    throw new VisionError(ERROR_CODES.FETCH, `${value} exceeded ${MAX_REDIRECTS} redirects.`);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// source: { type: "file" | "url", value: string }
+// Returns a disposable, repeatable stream source. URL downloads are spooled to
+// a private temporary file so provider serialization never needs the complete
+// image or its base64 representation in memory.
+export async function loadImageSource(source, { maxImageBytes, timeoutMs, fetchImpl } = {}) {
+  if (!source || typeof source !== "object" || typeof source.value !== "string" || source.value.trim() === "") {
+    throw new VisionError(
+      ERROR_CODES.INPUT,
+      'image_source must be { "type": "file" | "url", "value": "<path or url>" }.'
+    );
+  }
+  if (source.type === "file") return loadFile(source.value, maxImageBytes);
+  if (source.type === "url") return loadUrl(source.value, { maxImageBytes, timeoutMs, fetchImpl });
+  throw new VisionError(ERROR_CODES.INPUT, `Unsupported image_source.type: ${JSON.stringify(source.type)}`);
+}