zubo 0.1.0

package/src/tools/skill-loader.ts

@@ -0,0 +1,259 @@
+import { readdirSync, readFileSync, existsSync, watch } from "fs";
+import { join } from "path";
+import { paths } from "../config/paths";
+import { logger } from "../util/logger";
+import { registerTool, getTool, unregisterTool } from "./registry";
+
+/** Tracks all skill names loaded via loadSkills so hot-reload can unregister them. */
+const loadedSkillNames = new Set<string>();
+
+export interface SkillDef {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  dirPath: string;
+}
+
+export interface SkillParamDef {
+  type: string;
+  description?: string;
+  required?: boolean;
+}
+
+export function paramsToJsonSchema(params: Record<string, SkillParamDef>): Record<string, unknown> {
+  const properties: Record<string, { type: string; description?: string }> = {};
+  const required: string[] = [];
+
+  for (const [key, def] of Object.entries(params)) {
+    properties[key] = { type: def.type || "string" };
+    if (def.description) properties[key].description = def.description;
+    if (def.required) required.push(key);
+  }
+
+  return { type: "object", properties, required };
+}
+
+export function parseSkillExport(
+  skillConfig: { name: string; description: string; params?: Record<string, SkillParamDef> },
+  dirPath: string
+): SkillDef | null {
+  const { name, description, params } = skillConfig;
+
+  if (!name || !/^[a-z0-9_]+$/.test(name)) return null;
+  if (!description) return null;
+
+  const inputSchema = params ? paramsToJsonSchema(params) : { type: "object", properties: {}, required: [] };
+
+  return { name, description, inputSchema, dirPath };
+}
+
+export function parseSkillMd(content: string, dirPath: string): SkillDef | null {
+  const lines = content.split("\n");
+
+  // H1 = tool name
+  const h1Line = lines.find((l) => /^# /.test(l));
+  if (!h1Line) return null;
+  const name = h1Line.replace(/^# /, "").trim();
+  if (!/^[a-z0-9_]+$/.test(name)) return null;
+
+  // Description = text between H1 and first H2
+  const h1Index = lines.indexOf(h1Line);
+  let descLines: string[] = [];
+  for (let i = h1Index + 1; i < lines.length; i++) {
+    if (/^## /.test(lines[i])) break;
+    descLines.push(lines[i]);
+  }
+  const description = descLines.join("\n").trim();
+  if (!description) return null;
+
+  // Input Schema = fenced JSON inside ## Input Schema
+  let inputSchema: Record<string, unknown> = {
+    type: "object",
+    properties: {},
+    required: [],
+  };
+  const schemaHeading = lines.findIndex((l) => /^## Input Schema/.test(l));
+  if (schemaHeading !== -1) {
+    let inFence = false;
+    let jsonLines: string[] = [];
+    for (let i = schemaHeading + 1; i < lines.length; i++) {
+      if (/^## /.test(lines[i]) && !inFence) break;
+      if (/^```/.test(lines[i])) {
+        if (inFence) break;
+        inFence = true;
+        continue;
+      }
+      if (inFence) jsonLines.push(lines[i]);
+    }
+    if (jsonLines.length) {
+      try {
+        inputSchema = JSON.parse(jsonLines.join("\n"));
+      } catch {
+        // Fall back to empty schema
+      }
+    }
+  }
+
+  // Usage Hints (optional) = appended to description
+  let fullDescription = description;
+  const hintsHeading = lines.findIndex((l) => /^## Usage Hints/.test(l));
+  if (hintsHeading !== -1) {
+    let hintLines: string[] = [];
+    for (let i = hintsHeading + 1; i < lines.length; i++) {
+      if (/^## /.test(lines[i])) break;
+      hintLines.push(lines[i]);
+    }
+    const hints = hintLines.join("\n").trim();
+    if (hints) {
+      fullDescription += "\n\n" + hints;
+    }
+  }
+
+  return { name, description: fullDescription, inputSchema, dirPath };
+}
+
+export async function loadSkills(skillsDir: string): Promise<string[]> {
+  if (!existsSync(skillsDir)) return [];
+
+  const loaded: string[] = [];
+  let entries: string[];
+
+  try {
+    entries = readdirSync(skillsDir);
+  } catch {
+    return [];
+  }
+
+  for (const entry of entries) {
+    const dirPath = join(skillsDir, entry);
+    const skillMdPath = join(dirPath, "SKILL.md");
+    const handlerPath = join(dirPath, "handler.ts");
+
+    if (!existsSync(handlerPath)) continue;
+
+    try {
+      let skill: SkillDef | null = null;
+      let handler: ((input: Record<string, unknown>) => Promise<string>) | undefined;
+
+      // Try SKILL.md first (backward compat)
+      if (existsSync(skillMdPath)) {
+        const mdContent = readFileSync(skillMdPath, "utf-8");
+        skill = parseSkillMd(mdContent, dirPath);
+        if (!skill) {
+          logger.warn(
+            `Skipping skill in ${entry}: invalid SKILL.md (name must match [a-z0-9_], description required)`
+          );
+          continue;
+        }
+      } else {
+        // Single-file: read metadata from handler.ts exports
+        const mod = await import(handlerPath + "?t=" + Date.now());
+        if (mod.skill && typeof mod.skill === "object") {
+          skill = parseSkillExport(mod.skill, dirPath);
+          handler = mod.default;
+          if (!skill) {
+            logger.warn(
+              `Skipping skill in ${entry}: invalid skill export (name must match [a-z0-9_], description required)`
+            );
+            continue;
+          }
+        } else {
+          logger.warn(`Skipping skill in ${entry}: no SKILL.md and no exported skill config`);
+          continue;
+        }
+      }
+
+      // Warn on name collision
+      if (getTool(skill.name)) {
+        logger.warn(`Skill "${skill.name}" conflicts with existing tool, skipping`);
+        continue;
+      }
+
+      // Dynamically import handler (if not already loaded from single-file path)
+      if (!handler) {
+        const mod = await import(handlerPath + "?t=" + Date.now());
+        handler = mod.default;
+      }
+      if (typeof handler !== "function") {
+        logger.warn(`Skipping skill "${skill.name}": handler.ts must export a default function`);
+        continue;
+      }
+
+      // Wrap handler with validation: ensure it returns a string
+      const rawHandler = handler;
+      const safeHandler = async (input: Record<string, unknown>): Promise<string> => {
+        const result = await rawHandler(input);
+        if (typeof result !== "string") {
+          logger.warn(`Skill "${skill.name}" returned ${typeof result}, expected string. Coercing to JSON.`);
+          return JSON.stringify(result);
+        }
+        return result;
+      };
+
+      registerTool({
+        definition: {
+          name: skill.name,
+          description: skill.description,
+          input_schema: skill.inputSchema,
+        },
+        execute: safeHandler,
+      }, true);
+
+      loadedSkillNames.add(skill.name);
+      loaded.push(skill.name);
+    } catch (err: any) {
+      logger.error(`Failed to load skill from ${entry}: ${err.message}`);
+    }
+  }
+
+  return loaded;
+}
+
+/**
+ * Unregisters all previously loaded skills, then reloads them from disk.
+ * Used by the hot-reload watcher to pick up file changes.
+ */
+export async function reloadAllSkills(): Promise<string[]> {
+  for (const name of loadedSkillNames) {
+    unregisterTool(name);
+  }
+  loadedSkillNames.clear();
+
+  return loadSkills(paths.skills);
+}
+
+/**
+ * Watches the skills directory for file changes and reloads all skills
+ * after a short debounce. Returns a cleanup function to stop watching.
+ */
+export function watchSkills(): () => void {
+  const skillsDir = paths.skills;
+
+  if (!existsSync(skillsDir)) {
+    logger.warn("Skills directory does not exist, skipping hot-reload watcher");
+    return () => {};
+  }
+
+  let debounceTimer: ReturnType<typeof setTimeout> | null = null;
+
+  const watcher = watch(skillsDir, { recursive: true }, (_eventType, filename) => {
+    if (debounceTimer) clearTimeout(debounceTimer);
+
+    debounceTimer = setTimeout(async () => {
+      logger.info("Skill file changed, reloading skills", { filename });
+      try {
+        const skillNames = await reloadAllSkills();
+        logger.info("Skills reloaded successfully", { skills: skillNames });
+      } catch (err: any) {
+        logger.error("Failed to reload skills", { error: err.message });
+      }
+    }, 500);
+  });
+
+  logger.info("Skill hot-reload watcher started", { dir: skillsDir });
+
+  return () => {
+    if (debounceTimer) clearTimeout(debounceTimer);
+    watcher.close();
+  };
+}

package/src/types/optional-deps.d.ts

@@ -0,0 +1,23 @@
+// Type declarations for optional dependencies that may not be installed.
+// These modules are dynamically imported inside try/catch blocks.
+
+declare module "pdf-parse" {
+  interface PdfData {
+    numpages: number;
+    numrender: number;
+    info: Record<string, unknown>;
+    metadata: unknown;
+    text: string;
+    version: string;
+  }
+  function pdfParse(buffer: Buffer): Promise<PdfData>;
+  export default pdfParse;
+}
+
+declare module "mammoth" {
+  interface ExtractResult {
+    value: string;
+    messages: unknown[];
+  }
+  export function extractRawText(options: { buffer: Buffer }): Promise<ExtractResult>;
+}

package/src/util/auth.ts

@@ -0,0 +1,121 @@
+import { Database } from "bun:sqlite";
+
+/**
+ * API key authentication for the Zubo HTTP API.
+ * Keys are stored as SHA-256 hashes — the raw key is only shown at creation time.
+ */
+
+export function generateApiKey(): string {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+export function hashApiKey(key: string): string {
+  const hasher = new Bun.CryptoHasher("sha256");
+  hasher.update(key);
+  return hasher.digest("hex");
+}
+
+export function initAuth(db: Database): void {
+  db.run(`
+    CREATE TABLE IF NOT EXISTS api_keys (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      label TEXT NOT NULL DEFAULT '',
+      key_hash TEXT NOT NULL UNIQUE,
+      created_at TEXT NOT NULL DEFAULT (datetime('now')),
+      last_used_at TEXT
+    )
+  `);
+}
+
+export function createApiKey(
+  db: Database,
+  label: string
+): { key: string; id: number } {
+  initAuth(db);
+  const key = generateApiKey();
+  const keyHash = hashApiKey(key);
+  const result = db
+    .prepare("INSERT INTO api_keys (label, key_hash) VALUES (?, ?)")
+    .run(label, keyHash);
+  return { key, id: Number(result.lastInsertRowid) };
+}
+
+export function listApiKeys(
+  db: Database
+): { id: number; label: string; created_at: string; last_used_at: string | null }[] {
+  initAuth(db);
+  return db
+    .query("SELECT id, label, created_at, last_used_at FROM api_keys ORDER BY id")
+    .all() as any[];
+}
+
+export function deleteApiKey(db: Database, id: number): boolean {
+  initAuth(db);
+  const result = db.prepare("DELETE FROM api_keys WHERE id = ?").run(id);
+  return result.changes > 0;
+}
+
+export function validateRequest(db: Database, req: Request): boolean {
+  const authHeader = req.headers.get("Authorization");
+  if (!authHeader) return false;
+
+  const match = authHeader.match(/^Bearer\s+(.+)$/i);
+  if (!match) return false;
+
+  const key = match[1];
+  const keyHash = hashApiKey(key);
+
+  initAuth(db);
+  const row = db
+    .query("SELECT id FROM api_keys WHERE key_hash = ?")
+    .get(keyHash) as { id: number } | null;
+
+  if (!row) return false;
+
+  // Update last_used_at
+  db.prepare("UPDATE api_keys SET last_used_at = datetime('now') WHERE id = ?").run(
+    row.id
+  );
+  return true;
+}
+
+// Session tokens for dashboard embedding (single-use, short-lived)
+const sessionTokens = new Map<string, number>(); // token -> expiry timestamp
+
+const MAX_SESSION_TOKENS = 1000;
+
+export function generateSessionToken(): string {
+  const token = crypto.randomUUID();
+  // 1-hour expiry
+  sessionTokens.set(token, Date.now() + 3600_000);
+
+  // Evict oldest tokens if over capacity
+  if (sessionTokens.size > MAX_SESSION_TOKENS) {
+    const iter = sessionTokens.keys();
+    const oldest = iter.next().value;
+    if (oldest) sessionTokens.delete(oldest);
+  }
+
+  return token;
+}
+
+export function validateSessionToken(token: string): boolean {
+  const expiry = sessionTokens.get(token);
+  if (!expiry) return false;
+  // Delete immediately to prevent race condition
+  sessionTokens.delete(token);
+  if (Date.now() > expiry) return false;
+  return true;
+}
+
+// Clean expired session tokens periodically
+setInterval(() => {
+  const now = Date.now();
+  for (const [token, expiry] of sessionTokens) {
+    if (now > expiry) sessionTokens.delete(token);
+  }
+}, 300_000).unref?.();

package/src/util/costs.ts

@@ -0,0 +1,59 @@
+/**
+ * Model pricing table (per 1M tokens, in USD).
+ * Updated as of late 2025.
+ */
+const MODEL_PRICING: Record<string, { input: number; output: number }> = {
+  // Anthropic
+  "claude-sonnet-4-5-20250929": { input: 3.0, output: 15.0 },
+  "claude-haiku-4-5-20251001": { input: 0.8, output: 4.0 },
+  "claude-opus-4-6": { input: 15.0, output: 75.0 },
+
+  // OpenAI
+  "gpt-4.1": { input: 2.0, output: 8.0 },
+  "gpt-4.1-mini": { input: 0.4, output: 1.6 },
+  "gpt-4.1-nano": { input: 0.1, output: 0.4 },
+  "gpt-4o": { input: 2.5, output: 10.0 },
+  "gpt-4o-mini": { input: 0.15, output: 0.6 },
+  "o1-mini": { input: 1.1, output: 4.4 },
+  "o3-mini": { input: 1.1, output: 4.4 },
+
+  // xAI
+  "grok-4.1-fast": { input: 0.2, output: 0.5 },
+
+  // DeepSeek
+  "deepseek-chat": { input: 0.56, output: 1.68 },
+  "deepseek-reasoner": { input: 0.55, output: 2.19 },
+
+  // Groq
+  "llama-3.3-70b-versatile": { input: 0.59, output: 0.79 },
+  "llama-3.1-8b-instant": { input: 0.05, output: 0.08 },
+
+  // Together
+  "meta-llama/Llama-3.3-70B-Instruct-Turbo": { input: 0.88, output: 0.88 },
+
+  // OpenRouter — pricing depends on underlying model, use provider's pricing
+  "anthropic/claude-sonnet-4-5": { input: 3.0, output: 15.0 },
+
+  // Default fallback (free / local)
+  _default: { input: 0, output: 0 },
+};
+
+/**
+ * Estimate cost in USD for a given model and token counts.
+ */
+export function estimateCost(
+  model: string,
+  inputTokens: number,
+  outputTokens: number
+): number {
+  // Try exact match first, then prefix match
+  let pricing = MODEL_PRICING[model];
+  if (!pricing) {
+    const key = Object.keys(MODEL_PRICING).find((k) => model.startsWith(k));
+    pricing = key ? MODEL_PRICING[key] : MODEL_PRICING._default;
+  }
+
+  const inputCost = (inputTokens / 1_000_000) * pricing.input;
+  const outputCost = (outputTokens / 1_000_000) * pricing.output;
+  return Math.round((inputCost + outputCost) * 1_000_000) / 1_000_000; // 6 decimal places
+}

package/src/util/error-buffer.ts

@@ -0,0 +1,32 @@
+/**
+ * A ring buffer of recent errors for agent visibility.
+ * The agent can check this to explain what went wrong.
+ */
+
+interface ErrorEntry {
+  source: string;
+  message: string;
+  timestamp: string;
+}
+
+const MAX_ENTRIES = 20;
+const buffer: ErrorEntry[] = [];
+
+export function recordError(source: string, message: string): void {
+  buffer.push({
+    source,
+    message,
+    timestamp: new Date().toISOString(),
+  });
+  if (buffer.length > MAX_ENTRIES) {
+    buffer.shift();
+  }
+}
+
+export function getRecentErrors(limit: number = 10): ErrorEntry[] {
+  return buffer.slice(-limit);
+}
+
+export function clearErrors(): void {
+  buffer.length = 0;
+}

package/src/util/google-tokens.ts

@@ -0,0 +1,180 @@
+/**
+ * Shared Google OAuth 2.0 token management.
+ *
+ * All Google integration handlers should call `getGoogleAccessToken()`
+ * instead of reading secrets directly. This module handles token refresh
+ * and the initial authorization code exchange.
+ */
+
+import { getSecret, setSecret } from "../secrets/store";
+
+const GOOGLE_TOKEN_URL = "https://oauth2.googleapis.com/token";
+const GOOGLE_AUTH_URL = "https://accounts.google.com/o/oauth2/v2/auth";
+
+/** Scopes requested for all Google integrations */
+const SCOPES = [
+  "https://www.googleapis.com/auth/gmail.modify",
+  "https://www.googleapis.com/auth/calendar",
+  "https://www.googleapis.com/auth/spreadsheets",
+  "https://www.googleapis.com/auth/documents",
+  "https://www.googleapis.com/auth/drive",
+];
+
+/**
+ * Returns a valid Google access token, refreshing if necessary.
+ *
+ * This is the single entry point every Google handler should use.
+ * Throws if no refresh token is stored (user has not connected Google yet).
+ */
+export async function getGoogleAccessToken(): Promise<string> {
+  const accessToken = getSecret("google_access_token");
+  const expiresAtRaw = getSecret("google_token_expires_at");
+
+  if (accessToken && expiresAtRaw) {
+    const expiresAt = parseInt(expiresAtRaw, 10);
+    // Refresh 5 minutes before actual expiry to avoid race conditions
+    const bufferMs = 5 * 60 * 1000;
+    if (Date.now() < expiresAt - bufferMs) {
+      return accessToken;
+    }
+  }
+
+  // Token missing or expired -- attempt refresh
+  return refreshGoogleToken();
+}
+
+/**
+ * Refreshes the Google access token using the stored refresh token.
+ * Stores the new access token and its expiry time.
+ */
+export async function refreshGoogleToken(): Promise<string> {
+  const refreshToken = getSecret("google_refresh_token");
+  if (!refreshToken) {
+    throw new Error(
+      "Google not connected. Use the google_oauth tool to set up Google."
+    );
+  }
+
+  const clientId = getSecret("google_client_id");
+  const clientSecret = getSecret("google_client_secret");
+
+  if (!clientId || !clientSecret) {
+    throw new Error(
+      "Google client credentials missing. Use the google_oauth tool to set up Google."
+    );
+  }
+
+  const res = await fetch(GOOGLE_TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "refresh_token",
+      refresh_token: refreshToken,
+      client_id: clientId,
+      client_secret: clientSecret,
+    }),
+  });
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    console.error(`[Google] Token refresh failed ${res.status}: ${body.slice(0, 500)}`);
+    throw new Error(
+      `Google token refresh failed (${res.status}). You may need to reconnect Google using the google_oauth tool.`
+    );
+  }
+
+  const data = (await res.json()) as {
+    access_token: string;
+    expires_in: number;
+    token_type: string;
+    refresh_token?: string;
+  };
+
+  // Store new access token and computed expiry timestamp
+  setSecret("google_access_token", data.access_token, "google");
+  const expiresAt = Date.now() + data.expires_in * 1000;
+  setSecret("google_token_expires_at", String(expiresAt), "google");
+
+  // Google occasionally rotates refresh tokens -- store the new one if provided
+  if (data.refresh_token) {
+    setSecret("google_refresh_token", data.refresh_token, "google");
+  }
+
+  return data.access_token;
+}
+
+/**
+ * Exchanges an authorization code for access + refresh tokens.
+ * Called once after the user completes the OAuth consent screen.
+ */
+export async function exchangeGoogleCode(
+  code: string,
+  redirectUri: string
+): Promise<void> {
+  const clientId = getSecret("google_client_id");
+  const clientSecret = getSecret("google_client_secret");
+
+  if (!clientId || !clientSecret) {
+    throw new Error(
+      "Google client credentials not found. Store google_client_id and google_client_secret first."
+    );
+  }
+
+  const res = await fetch(GOOGLE_TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "authorization_code",
+      code,
+      redirect_uri: redirectUri,
+      client_id: clientId,
+      client_secret: clientSecret,
+    }),
+  });
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    console.error(`[Google] Code exchange failed ${res.status}: ${body.slice(0, 500)}`);
+    throw new Error(
+      `Google authorization failed (${res.status}). Please try the OAuth flow again.`
+    );
+  }
+
+  const data = (await res.json()) as {
+    access_token: string;
+    expires_in: number;
+    refresh_token?: string;
+    token_type: string;
+  };
+
+  setSecret("google_access_token", data.access_token, "google");
+  const expiresAt = Date.now() + data.expires_in * 1000;
+  setSecret("google_token_expires_at", String(expiresAt), "google");
+
+  if (data.refresh_token) {
+    setSecret("google_refresh_token", data.refresh_token, "google");
+  }
+}
+
+/**
+ * Builds the Google OAuth 2.0 authorization URL.
+ * Uses `access_type=offline` and `prompt=consent` to ensure a refresh token
+ * is always returned, even if the user has previously authorized the app.
+ */
+export function getGoogleAuthUrl(redirectUri: string): string {
+  const clientId = getSecret("google_client_id");
+  if (!clientId) {
+    throw new Error("google_client_id not found in secrets.");
+  }
+
+  const params = new URLSearchParams({
+    client_id: clientId,
+    redirect_uri: redirectUri,
+    response_type: "code",
+    scope: SCOPES.join(" "),
+    access_type: "offline",
+    prompt: "consent",
+  });
+
+  return `${GOOGLE_AUTH_URL}?${params.toString()}`;
+}