zubo 0.1.0

package/src/tools/builtin-skills/web-search/handler.ts

@@ -0,0 +1,50 @@
+export default async function (input: Record<string, unknown>): Promise<string> {
+  const query = input.query as string;
+  const maxResults = (input.maxResults as number) || 5;
+
+  const url = `https://html.duckduckgo.com/html/?q=${encodeURIComponent(query)}`;
+
+  const res = await fetch(url, {
+    headers: {
+      "User-Agent": "Zubo/1.0",
+    },
+    signal: AbortSignal.timeout(15000),
+  });
+
+  if (!res.ok) {
+    throw new Error(`Search failed: ${res.status} ${res.statusText}`);
+  }
+
+  const html = await res.text();
+
+  // Parse results from DuckDuckGo HTML
+  const results: { title: string; url: string; snippet: string }[] = [];
+  const resultRegex =
+    /<a rel="nofollow" class="result__a" href="([^"]*)"[^>]*>([\s\S]*?)<\/a>[\s\S]*?<a class="result__snippet"[^>]*>([\s\S]*?)<\/a>/g;
+
+  let match;
+  while ((match = resultRegex.exec(html)) !== null && results.length < maxResults) {
+    const rawUrl = match[1];
+    const title = match[2].replace(/<[^>]+>/g, "").trim();
+    const snippet = match[3].replace(/<[^>]+>/g, "").trim();
+
+    // DuckDuckGo wraps URLs in a redirect — extract the actual URL
+    let finalUrl = rawUrl;
+    try {
+      const parsed = new URL(rawUrl, "https://duckduckgo.com");
+      finalUrl = parsed.searchParams.get("uddg") || rawUrl;
+    } catch (err: any) {
+      // URL parsing is non-critical; fall back to rawUrl
+    }
+
+    if (title) {
+      results.push({ title, url: finalUrl, snippet });
+    }
+  }
+
+  if (results.length === 0) {
+    return JSON.stringify({ query, results: [], message: "No results found." });
+  }
+
+  return JSON.stringify({ query, results });
+}

package/src/tools/executor.ts

@@ -0,0 +1,205 @@
+import { getTool } from "./registry";
+import { getToolPermission } from "./permissions";
+import { logger } from "../util/logger";
+import { recordError } from "../util/error-buffer";
+import { executeSandboxed } from "./sandbox";
+
+export interface ToolResult {
+  tool_use_id: string;
+  content: string;
+  is_error: boolean;
+}
+
+// Server-side confirmation tracking — prevents LLM from spoofing _confirmed
+const pendingConfirmations = new Map<string, { toolName: string; input: Record<string, unknown>; timestamp: number }>();
+
+// Clean up stale confirmations older than 10 minutes
+function cleanStaleConfirmations() {
+  const cutoff = Date.now() - 10 * 60 * 1000;
+  for (const [token, entry] of pendingConfirmations) {
+    if (entry.timestamp < cutoff) pendingConfirmations.delete(token);
+  }
+}
+
+// Determine if a tool should run in the sandbox (user-installed skills only)
+async function shouldSandbox(
+  toolName: string
+): Promise<{ handlerPath: string; timeoutMs: number; env: Record<string, string> } | null> {
+  try {
+    const { isUserInstalledSkill } = await import("./registry");
+
+    // Only sandbox tools that were loaded via the skill-loader from the user's skills directory
+    if (!isUserInstalledSkill(toolName)) return null;
+
+    const { existsSync, readFileSync } = await import("fs");
+    const { join } = await import("path");
+    const { paths } = await import("../config/paths");
+
+    // Check if sandbox is enabled in config
+    let timeoutMs = 30_000;
+    try {
+      const config = JSON.parse(readFileSync(paths.config, "utf-8"));
+      if (config.sandbox?.enabled === false) return null;
+      if (config.sandbox?.timeoutMs) timeoutMs = config.sandbox.timeoutMs;
+    } catch (err: any) {
+      logger.warn("Failed to read sandbox config", { error: (err as Error).message });
+    }
+
+    // Resolve the handler path and read SKILL.md for declared secrets
+    const skillDir = join(paths.skills, toolName);
+    const handlerPath = join(skillDir, "handler.ts");
+    if (!existsSync(handlerPath)) return null;
+
+    // If the handler uses getGoogleToken, it needs the main process globals — skip sandbox
+    const handlerCode = readFileSync(handlerPath, "utf-8");
+    if (handlerCode.includes("getGoogleToken")) {
+      return null;
+    }
+
+    // Only pass secrets that the skill actually references (grep handler for getSecret calls)
+    const env: Record<string, string> = {};
+    try {
+      const { getDb } = await import("../db/connection");
+      const db = getDb();
+      const rows = db.query("SELECT name, value FROM secrets").all() as { name: string; value: string }[];
+      for (const row of rows) {
+        // Only pass secrets referenced in the handler code
+        if (handlerCode.includes(`"${row.name}"`) || handlerCode.includes(`'${row.name}'`)) {
+          env[`ZUBO_SECRET_${row.name.toUpperCase()}`] = row.value;
+        }
+      }
+    } catch (err: any) {
+      logger.warn("Failed to resolve skill secrets for sandbox", { error: (err as Error).message });
+    }
+
+    return { handlerPath, timeoutMs, env };
+  } catch {
+    return null;
+  }
+}
+
+export async function executeTool(
+  name: string,
+  toolUseId: string,
+  input: Record<string, unknown>,
+  allowedTools?: string[]
+): Promise<ToolResult> {
+  // Defense-in-depth: if an allowedTools set is provided (sub-agents),
+  // reject any tool call not in the set, even if the LLM tries to call it.
+  if (allowedTools && !allowedTools.includes(name)) {
+    logger.warn(`Tool blocked by allowedTools: ${name}`);
+    return {
+      tool_use_id: toolUseId,
+      content: `Error: Tool '${name}' is not available in this agent context.`,
+      is_error: true,
+    };
+  }
+  const tool = getTool(name);
+  if (!tool) {
+    logger.error(`Tool not found: ${name}`);
+    return {
+      tool_use_id: toolUseId,
+      content: `Error: Unknown tool '${name}'`,
+      is_error: true,
+    };
+  }
+
+  const permission = getToolPermission(name);
+
+  if (permission === "deny") {
+    logger.warn(`Tool denied: ${name}`);
+    return {
+      tool_use_id: toolUseId,
+      content: `Error: Tool '${name}' is not permitted.`,
+      is_error: true,
+    };
+  }
+
+  if (permission === "confirm") {
+    cleanStaleConfirmations();
+
+    // Check for a valid server-issued confirmation token
+    const confirmToken = input._confirmToken as string | undefined;
+    if (confirmToken) {
+      const pending = pendingConfirmations.get(confirmToken);
+      if (!pending || pending.toolName !== name) {
+        return {
+          tool_use_id: toolUseId,
+          content: `Error: Invalid or expired confirmation token. The action was NOT executed. Please ask the user for approval again.`,
+          is_error: true,
+        };
+      }
+      // Valid token — clear it and proceed
+      pendingConfirmations.delete(confirmToken);
+    } else {
+      // No token — generate one and request confirmation
+      const { _confirmed, _confirmToken: _, ...displayInput } = input;
+      const desc = JSON.stringify(displayInput, null, 2);
+      const token = crypto.randomUUID();
+      pendingConfirmations.set(token, { toolName: name, input: displayInput, timestamp: Date.now() });
+      logger.info(`Tool requires confirmation: ${name}`);
+      return {
+        tool_use_id: toolUseId,
+        content: `CONFIRMATION REQUIRED — tool was NOT executed.\n\nTool: ${name}\nInput: ${desc}\nConfirmation Token: ${token}\n\nThis tool requires user approval before it can run. Describe this action to the user and ask for their permission. Once they approve, call this tool again with _confirmToken set to "${token}" in the input.`,
+        is_error: false,
+      };
+    }
+  }
+
+  const startTime = Date.now();
+  try {
+    const { _confirmed, _confirmToken, ...cleanInput } = input;
+    logger.info(`Executing tool: ${name}`);
+
+    // Check if this is a user-installed skill that should be sandboxed
+    let result: any;
+    const sandboxed = await shouldSandbox(name);
+    if (sandboxed) {
+      result = await executeSandboxed(sandboxed.handlerPath, cleanInput, {
+        timeoutMs: sandboxed.timeoutMs,
+        env: sandboxed.env,
+      });
+    } else {
+      result = await tool.execute(cleanInput);
+    }
+    const durationMs = Date.now() - startTime;
+
+    // Record tool metrics
+    try {
+      const { getDb } = await import("../db/connection");
+      const db = getDb();
+      db.prepare(
+        "INSERT INTO tool_metrics (tool_name, duration_ms, success) VALUES (?, ?, 1)"
+      ).run(name, durationMs);
+    } catch (err: any) {
+      logger.warn("Failed to record tool success metrics", { error: (err as Error).message });
+    }
+
+    return {
+      tool_use_id: toolUseId,
+      content: typeof result === "string" ? result : JSON.stringify(result),
+      is_error: false,
+    };
+  } catch (err: any) {
+    const durationMs = Date.now() - startTime;
+    logger.error(`Tool error: ${name}`, { error: err.message });
+    recordError(`tool:${name}`, err.message);
+
+    // Record failed tool metrics
+    try {
+      const { getDb } = await import("../db/connection");
+      const db = getDb();
+      db.prepare(
+        "INSERT INTO tool_metrics (tool_name, duration_ms, success) VALUES (?, ?, 0)"
+      ).run(name, durationMs);
+    } catch (metricsErr: any) {
+      logger.warn("Failed to record tool failure metrics", { error: (metricsErr as Error).message });
+    }
+
+    return {
+      tool_use_id: toolUseId,
+      content: `Error: ${err.message}`,
+      is_error: true,
+    };
+  }
+}

package/src/tools/integration-installer.ts

@@ -0,0 +1,106 @@
+import { readdirSync, existsSync, readFileSync, mkdirSync, writeFileSync } from "fs";
+import { join } from "path";
+
+const INTEGRATIONS_DIR = join(import.meta.dir, "builtin-integrations");
+
+export interface IntegrationInfo {
+  service: string;
+  skills: string[];
+  secret_name: string;
+}
+
+const SERVICE_SECRETS: Record<string, string> = {
+  github: "github_token",
+  google: "google_oauth",  // Google uses OAuth 2.0 — credentials are google_client_id + google_client_secret
+  notion: "notion_token",
+  slack: "slack_token",
+  linear: "linear_token",
+  jira: "jira_token",
+  twitter: "twitter_bearer_token",
+};
+
+/**
+ * Lists available integrations by scanning the builtin-integrations directory.
+ */
+export function listAvailableIntegrations(): IntegrationInfo[] {
+  const integrations: IntegrationInfo[] = [];
+
+  let services: string[];
+  try {
+    services = readdirSync(INTEGRATIONS_DIR);
+  } catch {
+    return [];
+  }
+
+  for (const service of services) {
+    const serviceDir = join(INTEGRATIONS_DIR, service);
+    let entries: string[];
+    try {
+      entries = readdirSync(serviceDir);
+    } catch {
+      continue;
+    }
+
+    const skills: string[] = [];
+    for (const entry of entries) {
+      const skillDir = join(serviceDir, entry);
+      if (
+        existsSync(join(skillDir, "SKILL.md")) &&
+        existsSync(join(skillDir, "handler.ts"))
+      ) {
+        skills.push(entry);
+      }
+    }
+
+    if (skills.length > 0) {
+      integrations.push({
+        service,
+        skills,
+        secret_name: SERVICE_SECRETS[service] || `${service}_token`,
+      });
+    }
+  }
+
+  return integrations;
+}
+
+/**
+ * Installs integration skill templates to the user's skills directory.
+ * Returns list of installed skill names.
+ */
+export function installIntegration(targetDir: string, service: string): string[] {
+  const serviceDir = join(INTEGRATIONS_DIR, service);
+  if (!existsSync(serviceDir)) return [];
+
+  let entries: string[];
+  try {
+    entries = readdirSync(serviceDir);
+  } catch {
+    return [];
+  }
+
+  const installed: string[] = [];
+
+  for (const entry of entries) {
+    const srcDir = join(serviceDir, entry);
+    const skillMd = join(srcDir, "SKILL.md");
+    const handlerTs = join(srcDir, "handler.ts");
+
+    if (!existsSync(skillMd) || !existsSync(handlerTs)) continue;
+
+    const destDir = join(targetDir, entry);
+
+    // Skip if already installed (preserve user edits)
+    if (existsSync(destDir)) {
+      installed.push(entry);
+      continue;
+    }
+
+    mkdirSync(destDir, { recursive: true });
+    writeFileSync(join(destDir, "SKILL.md"), readFileSync(skillMd));
+    writeFileSync(join(destDir, "handler.ts"), readFileSync(handlerTs));
+    installed.push(entry);
+  }
+
+  return installed;
+}

package/src/tools/permissions.ts

@@ -0,0 +1,45 @@
+export type ToolPermission = "auto" | "confirm" | "deny";
+
+const DEFAULT_PERMISSIONS: Record<string, ToolPermission> = {
+  // Built-in tools — always safe
+  datetime: "auto",
+  memory_write: "auto",
+  memory_search: "auto",
+  manage_skills: "auto",
+  cron_create: "auto",
+  cron_list: "auto",
+  cron_delete: "auto",
+
+  // Secrets — set/list are safe, delete requires confirmation
+  secret_set: "auto",
+  secret_list: "auto",
+  secret_delete: "confirm",
+
+  // Integrations
+  connect_service: "auto",
+
+  // Agent delegation
+  delegate: "auto",
+  manage_agents: "auto",
+
+  // Built-in skills — safe
+  web_search: "auto",
+  url_fetch: "auto",
+  file_read: "auto",
+  http_request: "auto",
+
+  // Built-in skills — potentially dangerous
+  shell: "confirm",
+  file_write: "confirm",
+
+  // Integration skills — posting requires confirmation
+  twitter_posts: "confirm",
+};
+
+/**
+ * Returns the permission level for a tool.
+ * Unknown tools (user-installed skills) default to "auto".
+ */
+export function getToolPermission(name: string): ToolPermission {
+  return DEFAULT_PERMISSIONS[name] ?? "auto";
+}

package/src/tools/registry.ts

@@ -0,0 +1,39 @@
+import type { LlmToolDef } from "../llm/provider";
+
+export interface ToolHandler {
+  definition: LlmToolDef;
+  execute: (input: Record<string, unknown>) => Promise<string>;
+}
+
+const tools = new Map<string, ToolHandler>();
+
+// Track which tools were loaded from the user skills directory (for sandboxing)
+const userInstalledSkills = new Set<string>();
+
+export function registerTool(handler: ToolHandler, isUserSkill: boolean = false) {
+  tools.set(handler.definition.name, handler);
+  if (isUserSkill) {
+    userInstalledSkills.add(handler.definition.name);
+  }
+}
+
+export function isUserInstalledSkill(name: string): boolean {
+  return userInstalledSkills.has(name);
+}
+
+export function getTool(name: string): ToolHandler | undefined {
+  return tools.get(name);
+}
+
+export function getAllToolDefs(): LlmToolDef[] {
+  return Array.from(tools.values()).map((t) => t.definition);
+}
+
+export function unregisterTool(name: string): boolean {
+  userInstalledSkills.delete(name);
+  return tools.delete(name);
+}
+
+export function getAllTools(): Map<string, ToolHandler> {
+  return tools;
+}

package/src/tools/sandbox-runner.ts

@@ -0,0 +1,56 @@
+#!/usr/bin/env bun
+/**
+ * Sandbox runner — entry point for isolated skill execution.
+ * Reads handler path + input from argv, runs the handler, writes JSON result to stdout.
+ * No access to parent process globals.
+ */
+export {};
+
+import { join } from "path";
+import { realpathSync } from "fs";
+
+const [handlerPath, inputJson] = process.argv.slice(2);
+
+if (!handlerPath || !inputJson) {
+  console.error("Usage: sandbox-runner.ts <handlerPath> <inputJson>");
+  process.exit(1);
+}
+
+// Validate handler path is within the user's skills directory (resolve symlinks)
+let resolvedHandler: string;
+let skillsDir: string;
+try {
+  resolvedHandler = realpathSync(handlerPath);
+  skillsDir = realpathSync(join(process.env.HOME ?? "", ".zubo", "workspace", "skills"));
+} catch {
+  console.error("Handler path does not exist or is not accessible");
+  process.exit(1);
+}
+if (!resolvedHandler.startsWith(skillsDir + "/")) {
+  console.error("Handler path must be within the skills directory");
+  process.exit(1);
+}
+
+// Set up minimal globalThis.Zubo with secrets from env
+(globalThis as any).Zubo = {
+  getSecret(name: string): string | undefined {
+    return process.env[`ZUBO_SECRET_${name.toUpperCase()}`];
+  },
+};
+
+try {
+  const input = JSON.parse(inputJson);
+  const mod = await import(handlerPath);
+  const handler = mod.default;
+
+  if (typeof handler !== "function") {
+    console.error("Handler must export a default function");
+    process.exit(1);
+  }
+
+  const result = await handler(input);
+  console.log(JSON.stringify(result));
+} catch (err: any) {
+  console.error(err.message ?? String(err));
+  process.exit(1);
+}

package/src/tools/sandbox.ts

@@ -0,0 +1,82 @@
+import { join, dirname } from "path";
+import { logger } from "../util/logger";
+
+const SANDBOX_RUNNER = join(import.meta.dir, "sandbox-runner.ts");
+
+/** Resolve the directory containing the `bun` binary once at import time. */
+const BUN_BIN_DIR = (() => {
+  try {
+    return dirname(Bun.which("bun") ?? process.execPath);
+  } catch {
+    return dirname(process.execPath);
+  }
+})();
+
+export interface SandboxOptions {
+  timeoutMs?: number;
+  env?: Record<string, string>;
+}
+
+/**
+ * Execute a skill handler in a sandboxed subprocess.
+ * The handler runs in a separate Bun process with no access to the parent's globals.
+ * Secrets are passed via environment variables.
+ */
+export async function executeSandboxed(
+  handlerPath: string,
+  input: Record<string, unknown>,
+  options: SandboxOptions = {}
+): Promise<string> {
+  const timeoutMs = options.timeoutMs ?? 30_000;
+
+  const proc = Bun.spawn(
+    ["bun", "run", SANDBOX_RUNNER, handlerPath, JSON.stringify(input)],
+    {
+      stdout: "pipe",
+      stderr: "pipe",
+      env: {
+        ...options.env,
+        // Minimal env — don't pass full parent env to prevent secret leakage
+        HOME: process.env.HOME ?? "",
+        PATH: `${BUN_BIN_DIR}:/usr/local/bin:/usr/bin:/bin`,
+        NODE_ENV: process.env.NODE_ENV ?? "production",
+      },
+    }
+  );
+
+  // Timeout enforcement
+  const timer = setTimeout(() => {
+    try {
+      proc.kill();
+    } catch (err: any) {
+      logger.warn("Failed to kill timed-out sandbox process", { error: (err as Error).message });
+    }
+  }, timeoutMs);
+
+  try {
+    const exitCode = await proc.exited;
+    clearTimeout(timer);
+
+    const stdout = await new Response(proc.stdout).text();
+    const stderr = await new Response(proc.stderr).text();
+
+    if (exitCode !== 0) {
+      const errMsg = stderr.trim() || `Process exited with code ${exitCode}`;
+      logger.error("Sandboxed skill error", { handlerPath, exitCode, stderr: errMsg.slice(0, 500) });
+      throw new Error(`Skill execution failed: ${errMsg.slice(0, 200)}`);
+    }
+
+    // Parse the JSON result from stdout
+    try {
+      const result = JSON.parse(stdout.trim());
+      return typeof result === "string" ? result : JSON.stringify(result);
+    } catch {
+      // If not valid JSON, return raw stdout
+      return stdout.trim();
+    }
+  } catch (err: any) {
+    clearTimeout(timer);
+    if (err.message?.includes("Skill execution failed")) throw err;
+    throw new Error(`Sandbox error: ${err.message}`);
+  }
+}

package/src/tools/skill-installer.ts

@@ -0,0 +1,52 @@
+import { readdirSync, existsSync, readFileSync, mkdirSync, writeFileSync } from "fs";
+import { join } from "path";
+
+const BUILTIN_SKILLS_DIR = join(import.meta.dir, "builtin-skills");
+
+export function getBuiltinSkillNames(): string[] {
+  try {
+    return readdirSync(BUILTIN_SKILLS_DIR).filter((entry) => {
+      const srcDir = join(BUILTIN_SKILLS_DIR, entry);
+      return existsSync(join(srcDir, "SKILL.md")) && existsSync(join(srcDir, "handler.ts"));
+    });
+  } catch {
+    return [];
+  }
+}
+
+export function reinstallBuiltinSkill(targetDir: string, skillName: string): boolean {
+  const srcDir = join(BUILTIN_SKILLS_DIR, skillName);
+  const destDir = join(targetDir, skillName);
+
+  const skillMd = join(srcDir, "SKILL.md");
+  const handlerTs = join(srcDir, "handler.ts");
+
+  if (!existsSync(skillMd) || !existsSync(handlerTs)) return false;
+
+  mkdirSync(destDir, { recursive: true });
+  writeFileSync(join(destDir, "SKILL.md"), readFileSync(skillMd));
+  writeFileSync(join(destDir, "handler.ts"), readFileSync(handlerTs));
+
+  return true;
+}
+
+export function installBuiltinSkills(targetDir: string): string[] {
+  if (!existsSync(targetDir)) {
+    mkdirSync(targetDir, { recursive: true });
+  }
+
+  const installed: string[] = [];
+
+  for (const entry of getBuiltinSkillNames()) {
+    const destDir = join(targetDir, entry);
+
+    // Skip if already exists (preserve user edits)
+    if (existsSync(destDir)) continue;
+
+    if (reinstallBuiltinSkill(targetDir, entry)) {
+      installed.push(entry);
+    }
+  }
+
+  return installed;
+}