@kairyou/agent-tools 0.1.0 → 0.3.0

package/integrations/vision/lib/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)}`);
+}

package/integrations/vision/lib/inspect.mjs

@@ -0,0 +1,108 @@
+// Orchestrator shared by the MCP server and the diagnostic CLI. Owns question
+// validation, the process-local limiter, provider dispatch, and final secret
+// redaction — both entry points stay thin.
+
+import crypto from "node:crypto";
+import path from "node:path";
+import { agentToolsHome, loadVisionConfig } from "./config.mjs";
+import { ERROR_CODES, VisionError, toVisionError } from "./errors.mjs";
+import { loadImageSource } from "./image-source.mjs";
+import { createLimiter } from "./rate-limit.mjs";
+import { redactSecrets } from "./redact.mjs";
+import { inspectWithAnthropicCompatible } from "./providers/anthropic-compatible.mjs";
+import { inspectWithOpenAICompatible } from "./providers/openai-compatible.mjs";
+
+const PROVIDER_IMPL = {
+  "openai-compatible": inspectWithOpenAICompatible,
+  "anthropic-compatible": inspectWithAnthropicCompatible,
+};
+
+export const QUESTION_LIMITS = Object.freeze({
+  maxCount: 20,
+  maxIdLength: 64,
+  maxTextLength: 4000,
+});
+
+export function validateQuestions(questions) {
+  if (!Array.isArray(questions) || questions.length === 0) {
+    throw new VisionError(
+      ERROR_CODES.INPUT,
+      'questions must be a non-empty array of { "id": "<id>", "text": "<question>" }.'
+    );
+  }
+  if (questions.length > QUESTION_LIMITS.maxCount) {
+    throw new VisionError(
+      ERROR_CODES.INPUT,
+      `questions must contain at most ${QUESTION_LIMITS.maxCount} entries.`
+    );
+  }
+  const seen = new Set();
+  const out = [];
+  for (const q of questions) {
+    if (!q || typeof q !== "object" || typeof q.id !== "string" || q.id.trim() === "" ||
+        typeof q.text !== "string" || q.text.trim() === "") {
+      throw new VisionError(
+        ERROR_CODES.INPUT,
+        'Each question must be { "id": "<non-empty id>", "text": "<non-empty question>" }.'
+      );
+    }
+    if (q.id.length > QUESTION_LIMITS.maxIdLength) {
+      throw new VisionError(
+        ERROR_CODES.INPUT,
+        `Question id must be at most ${QUESTION_LIMITS.maxIdLength} characters.`
+      );
+    }
+    if (q.text.length > QUESTION_LIMITS.maxTextLength) {
+      throw new VisionError(
+        ERROR_CODES.INPUT,
+        `Question text must be at most ${QUESTION_LIMITS.maxTextLength} characters.`
+      );
+    }
+    if (seen.has(q.id)) {
+      throw new VisionError(ERROR_CODES.INPUT, `Duplicate question id: ${q.id}`);
+    }
+    seen.add(q.id);
+    out.push({ id: q.id, text: q.text });
+  }
+  return out;
+}
+
+// One service per process: the limiter state must span all tool calls handled
+// by this MCP server (or CLI invocation).
+export function createVisionService({ config, fetchImpl, now, limiterStateFile } = {}) {
+  const resolved = config || loadVisionConfig();
+  const sharedState =
+    limiterStateFile === undefined && !config
+      ? path.join(agentToolsHome(), "cache", "vision-rate-limit.json")
+      : limiterStateFile;
+  const limiter = createLimiter(resolved, now, { stateFile: sharedState || null });
+  const provider = PROVIDER_IMPL[resolved.provider];
+  const secrets = resolved.apiKey ? [resolved.apiKey] : [];
+
+  async function inspect({ image_source, questions }) {
+    const requestId = `vision_req_${crypto.randomUUID().slice(0, 8)}`;
+    const validQuestions = validateQuestions(questions);
+    try {
+      return await limiter.run(async () => {
+        const image = await loadImageSource(image_source, {
+          maxImageBytes: resolved.maxImageBytes,
+          timeoutMs: resolved.timeoutMs,
+          fetchImpl,
+        });
+        try {
+          const answers = await provider({ config: resolved, image, questions: validQuestions, fetchImpl });
+          return { request_id: requestId, answers };
+        } finally {
+          await image.dispose();
+        }
+      });
+    } catch (err) {
+      // Last-line defense: no output path may carry the resolved key.
+      const visionErr = toVisionError(err);
+      visionErr.message = redactSecrets(visionErr.message, secrets);
+      throw visionErr;
+    }
+  }
+
+  return { config: resolved, inspect };
+}

package/integrations/vision/lib/providers/anthropic-compatible.mjs

@@ -0,0 +1,59 @@
+// Anthropic-compatible adapter (Messages API with base64 image blocks).
+// Convention: vision.baseUrl is the gateway root, e.g.
+// https://gateway.example.com — the adapter appends /v1/messages (or just
+// /messages when the base already ends in /v1).
+
+import { ERROR_CODES, VisionError } from "../errors.mjs";
+import { buildPrompt, createBase64JsonBody, normalizeAnswers, postJson } from "./shared.mjs";
+
+function messagesUrl(baseUrl) {
+  return baseUrl.endsWith("/v1") ? `${baseUrl}/messages` : `${baseUrl}/v1/messages`;
+}
+
+function replyText(json) {
+  if (!Array.isArray(json?.content)) return null;
+  const parts = json.content.filter((p) => p?.type === "text" && typeof p.text === "string");
+  if (parts.length === 0) return null;
+  return parts.map((p) => p.text).join("");
+}
+
+export async function inspectWithAnthropicCompatible({ config, image, questions, fetchImpl }) {
+  const headers = { "anthropic-version": "2023-06-01" };
+  if (config.apiKey) headers["x-api-key"] = config.apiKey;
+  const body = createBase64JsonBody(image, (imageBase64) => ({
+    model: config.model,
+    max_tokens: config.maxOutputTokens,
+    messages: [
+      {
+        role: "user",
+        content: [
+          {
+            type: "image",
+            source: {
+              type: "base64",
+              media_type: image.mediaType,
+              data: imageBase64,
+            },
+          },
+          { type: "text", text: buildPrompt(questions) },
+        ],
+      },
+    ],
+  }));
+  const json = await postJson({
+    url: messagesUrl(config.baseUrl),
+    headers,
+    body,
+    timeoutMs: config.timeoutMs,
+    fetchImpl,
+    providerLabel: "Anthropic-compatible provider",
+  });
+  const text = replyText(json);
+  if (text === null) {
+    throw new VisionError(
+      ERROR_CODES.PROVIDER_RESPONSE,
+      "Anthropic-compatible provider response has no text content blocks."
+    );
+  }
+  return normalizeAnswers(text, questions);
+}

package/integrations/vision/lib/providers/openai-compatible.mjs

@@ -0,0 +1,56 @@
+// OpenAI-compatible adapter (Chat Completions with image_url content parts).
+// Convention: vision.baseUrl includes the version prefix, e.g.
+// https://gateway.example.com/v1 — the adapter appends /chat/completions.
+
+import { ERROR_CODES, VisionError } from "../errors.mjs";
+import { buildPrompt, createBase64JsonBody, normalizeAnswers, postJson } from "./shared.mjs";
+
+function replyText(json) {
+  const message = json?.choices?.[0]?.message;
+  if (typeof message?.content === "string") return message.content;
+  if (Array.isArray(message?.content)) {
+    return message.content
+      .filter((part) => part?.type === "text" && typeof part.text === "string")
+      .map((part) => part.text)
+      .join("");
+  }
+  return null;
+}
+
+export async function inspectWithOpenAICompatible({ config, image, questions, fetchImpl }) {
+  const headers = {};
+  if (config.apiKey) headers.authorization = `Bearer ${config.apiKey}`;
+  const body = createBase64JsonBody(image, (imageBase64) => ({
+    model: config.model,
+    // Gateway defaults vary and can silently truncate long transcriptions.
+    max_tokens: config.maxOutputTokens,
+    messages: [
+      {
+        role: "user",
+        content: [
+          { type: "text", text: buildPrompt(questions) },
+          {
+            type: "image_url",
+            image_url: { url: `data:${image.mediaType};base64,${imageBase64}` },
+          },
+        ],
+      },
+    ],
+  }));
+  const json = await postJson({
+    url: `${config.baseUrl}/chat/completions`,
+    headers,
+    body,
+    timeoutMs: config.timeoutMs,
+    fetchImpl,
+    providerLabel: "OpenAI-compatible provider",
+  });
+  const text = replyText(json);
+  if (text === null) {
+    throw new VisionError(
+      ERROR_CODES.PROVIDER_RESPONSE,
+      "OpenAI-compatible provider response has no choices[0].message.content."
+    );
+  }
+  return normalizeAnswers(text, questions);
+}