@kairyou/agent-tools 0.1.0 → 0.3.0

package/{statusline/claude/statusline.mjs → integrations/statusline/claude-statusline.mjs}

@@ -20,7 +20,9 @@ const AGENT_TOOLS_HOME = process.env.AGENT_TOOLS_HOME || join(SCRIPT_DIR, "..",
 const DEFAULT_CONFIG_FILE = join(AGENT_TOOLS_HOME, "config.jsonc");
 const SNAPSHOT_FILE = join(AGENT_TOOLS_HOME, "cache", "usage-snapshot.json");
 const REFRESH_STATE_FILE = join(AGENT_TOOLS_HOME, "cache", "usage-refresh-state.json");
-const USAGE_RUNTIME = join(AGENT_TOOLS_HOME, "lib", "usage.mjs");
+// Cross-integration dependency: statusline renders provider usage via the
+// usage integration's query engine.
+const USAGE_RUNTIME = join(AGENT_TOOLS_HOME, "integrations", "usage", "core.mjs");
 const DEFAULT_SNAPSHOT_TTL_MS = 60_000;
 const DEFAULT_REFRESH_COOLDOWN_MS = 30_000;
 const DEFAULT_FAILURE_BACKOFF_MS = 120_000;
@@ -132,7 +134,7 @@ function normalizeField(field) {
 }
 
 function mergeConfig(cli) {
-  const rootConfig = readJsonFile(process.env.AGENT_TOOLS_CONFIG || DEFAULT_CONFIG_FILE);
+  const rootConfig = readJsonFile(DEFAULT_CONFIG_FILE);
   const fileConfig = rootConfig.statusline || {};
   const envFields = process.env.AGENT_TOOLS_STATUSLINE_FIELDS;
   const envSeparator = process.env.AGENT_TOOLS_STATUSLINE_SEPARATOR;

package/integrations/usage/cli.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// Local CLI used by the managed at-usage skills.
+
+import { queryAgentProviderUsage } from "./core.mjs";
+
+function parseAgent(argv) {
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--agent" && argv[index + 1]) return argv[index + 1];
+    if (arg.startsWith("--agent=")) return arg.slice("--agent=".length);
+  }
+  return null;
+}
+
+const agent = parseAgent(process.argv.slice(2));
+if (agent !== "claude" && agent !== "codex") {
+  process.stderr.write(agent ? `Unsupported agent: ${agent}\n` : "Missing --agent <claude|codex>\n");
+  process.exitCode = 2;
+} else {
+  try {
+    const result = await queryAgentProviderUsage(agent);
+    if (result?.text) process.stdout.write(`${result.text}\n`);
+  } catch {
+    // Usage is informational. Leave stdout empty so the skill can report the
+    // provider as unavailable without exposing endpoint or credential details.
+  }
+}

package/{hooks/codex/usage-hook.mjs → integrations/usage/codex-hook.mjs}

@@ -11,7 +11,7 @@ import { fileURLToPath } from "node:url";
 
 const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
 const AGENT_TOOLS_HOME = process.env.AGENT_TOOLS_HOME || path.resolve(SCRIPT_DIR, "..", "..");
-const USAGE_SCRIPT = path.join(AGENT_TOOLS_HOME, "lib", "usage.mjs");
+const USAGE_SCRIPT = path.join(SCRIPT_DIR, "core.mjs");
 const LOG_PATH = path.join(AGENT_TOOLS_HOME, "logs", "usage-hook.log");
 const TIMEOUT_MS = Number(process.env.AGENT_TOOLS_USAGE_HOOK_TIMEOUT_MS || 4500);
 const MAX_LOG_BYTES = Number(process.env.AGENT_TOOLS_USAGE_HOOK_LOG_BYTES || 256 * 1024);

package/{lib/usage.mjs → integrations/usage/core.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");
@@ -1171,6 +1171,10 @@ export async function queryProviderUsage(input, options = {}) {
 }
 
 async function refresh(agent = "codex") {
+  return await queryAgentProviderUsage(agent);
+}
+
+export async function queryAgentProviderUsage(agent = "codex") {
   return await queryUsageContext(await usageContext(agent), {
     agent,
     rememberSnapshot: agent === "claude",

package/{plugins/opencode/usage-plugin.mjs → integrations/usage/opencode-plugin.mjs}

@@ -1,4 +1,4 @@
-import { queryProviderUsage } from "../../lib/usage.mjs";
+import { queryProviderUsage } from "./core.mjs";
 
 const DEFAULT_REFRESH_MS = 60_000;
 

package/integrations/usage/skills/at-usage/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: at-usage
+description: Query and display the current API provider balance and recent usage.
+---
+
+Run this installed local command once using the shell or command-execution tool:
+
+```text
+node "{{USAGE_CLI_PATH}}" --agent {{USAGE_AGENT}}
+```
+
+Return stdout verbatim as the complete response. Do not explain, reformat, or
+wrap it in Markdown. If stdout is empty, say exactly `Provider usage is unavailable.`
+
+Never run `npx`, `npm`, `pnpm`, `bun`, install a package, or substitute another
+usage script. Use only the installed command above.

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