privateer-agent 0.1.0

package/src/tools/task.ts

@@ -0,0 +1,52 @@
+import { tool } from "ai";
+import { z } from "zod";
+import type { ToolContext } from "./context.ts";
+import { loadAgents, findAgent } from "../agents/loader.ts";
+
+// Delegation tool: hand an open-ended investigation to a sub-agent that runs its own
+// loop and returns just a summary, keeping the parent conversation small. Without a
+// subagent_type it runs the default read-only agent (read/glob/grep); with one it uses
+// that custom agent's tools/model/instructions. Sub-agents cannot spawn further
+// sub-agents (no recursion).
+//
+// When the model emits several `task` calls in one turn the AI SDK runs their
+// execute()s concurrently, so sub-agents fan out in parallel — bounded by the
+// session's `maxSubagents` limiter.
+export function taskTool(ctx: ToolContext) {
+  const agents = loadAgents(ctx.cwd);
+  const agentList = agents.length
+    ? ` Available subagent_type values: ${agents.map((a) => `${a.name} (${a.description})`).join("; ")}.`
+    : "";
+  return tool({
+    description:
+      "Delegate a search or task to a sub-agent. Give it a complete, self-contained prompt; it " +
+      "explores and returns a text summary, keeping the main thread focused. Omit subagent_type " +
+      "for the default read-only agent (read/glob/grep, cannot modify files)." +
+      agentList,
+    inputSchema: z.object({
+      description: z.string().describe("Short 3–6 word description of the task."),
+      prompt: z.string().describe("The full, self-contained task for the sub-agent."),
+      subagent_type: z.string().optional().describe("Name of a custom sub-agent to use."),
+    }),
+    execute: async ({ description, prompt, subagent_type }, { toolCallId }) => {
+      if (!ctx.runSubAgent) return "Sub-agents are not available in this context.";
+      let agent;
+      if (subagent_type) {
+        agent = findAgent(subagent_type, ctx.cwd);
+        if (!agent) {
+          const names = loadAgents(ctx.cwd).map((a) => a.name).join(", ") || "(none defined)";
+          return `No sub-agent named "${subagent_type}". Available: ${names}.`;
+        }
+      }
+      try {
+        const { text, toolUses, tokens } = await ctx.runSubAgent({ description, prompt, agent });
+        // Report run metrics out-of-band (keyed by this call's id) for the grouped
+        // agents view; the model itself only ever sees the text summary.
+        ctx.onSubAgentMetrics?.(toolCallId, { toolUses, tokens });
+        return text;
+      } catch (err) {
+        return `Sub-agent failed: ${err instanceof Error ? err.message : String(err)}`;
+      }
+    },
+  });
+}

package/src/tools/todo.ts

@@ -0,0 +1,36 @@
+import { tool } from "ai";
+import { z } from "zod";
+import type { ToolContext } from "./context.ts";
+
+// The planning tool: the model maintains a single flat task list, rewriting the
+// whole list each call. State lives in the session's
+// TodoStore so the TUI can render it live. No filesystem mutation, so it isn't gated.
+export function todoTool(ctx: ToolContext) {
+  return tool({
+    description:
+      "Record and update your task list for multi-step work. Pass the COMPLETE list every " +
+      "time (it replaces the previous one). Keep exactly one item 'in_progress'; mark items " +
+      "'completed' as you finish them. Use this to plan non-trivial tasks and keep the user oriented.",
+    inputSchema: z.object({
+      todos: z
+        .array(
+          z.object({
+            content: z.string().describe("Imperative task description, e.g. 'Add auth middleware'."),
+            status: z.enum(["pending", "in_progress", "completed"]),
+            activeForm: z
+              .string()
+              .optional()
+              .describe("Present-continuous label shown while running, e.g. 'Adding auth middleware'."),
+          }),
+        )
+        .describe("The full task list, in order."),
+    }),
+    execute: async ({ todos }) => {
+      ctx.todos?.set(todos);
+      const done = todos.filter((t) => t.status === "completed").length;
+      const active = todos.find((t) => t.status === "in_progress");
+      const summary = `Updated todo list (${done}/${todos.length} done).`;
+      return active ? `${summary} In progress: ${active.content}` : summary;
+    },
+  });
+}

package/src/tools/todoStore.ts

@@ -0,0 +1,31 @@
+// Session-scoped todo list. The `todo` tool replaces it; the TUI subscribes to it to
+// render the live task panel. Kept deliberately tiny — it's just an observable array.
+
+export type TodoStatus = "pending" | "in_progress" | "completed";
+
+export interface TodoItem {
+  content: string;
+  status: TodoStatus;
+  activeForm?: string; // present-continuous label shown while in_progress
+}
+
+export class TodoStore {
+  private items: TodoItem[] = [];
+  private listeners = new Set<(items: TodoItem[]) => void>();
+
+  get(): TodoItem[] {
+    return this.items;
+  }
+
+  set(items: TodoItem[]): void {
+    this.items = items;
+    for (const l of this.listeners) l(items);
+  }
+
+  subscribe(fn: (items: TodoItem[]) => void): () => void {
+    this.listeners.add(fn);
+    return () => {
+      this.listeners.delete(fn);
+    };
+  }
+}

package/src/tools/walk.ts

@@ -0,0 +1,44 @@
+import { readdirSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+
+// Directories we never descend into, so searches stay fast and relevant without
+// needing a full .gitignore parser. (A richer ignore story can come later.)
+const SKIP_DIRS = new Set([
+  ".git",
+  "node_modules",
+  "dist",
+  "build",
+  ".next",
+  ".cache",
+  "coverage",
+  ".venv",
+  "__pycache__",
+  ".turbo",
+]);
+
+const MAX_FILES = 20_000;
+
+// Recursively list files under `root`, returning paths relative to `root` with
+// forward slashes (so glob patterns behave consistently across platforms).
+export function walkFiles(root: string): string[] {
+  const out: string[] = [];
+  const stack: string[] = [root];
+  while (stack.length && out.length < MAX_FILES) {
+    const dir = stack.pop()!;
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue; // unreadable dir — skip
+    }
+    for (const e of entries) {
+      if (e.isDirectory()) {
+        if (SKIP_DIRS.has(e.name)) continue;
+        stack.push(join(dir, e.name));
+      } else if (e.isFile()) {
+        out.push(relative(root, join(dir, e.name)).split(sep).join("/"));
+      }
+    }
+  }
+  return out;
+}

package/src/tools/web.ts

@@ -0,0 +1,145 @@
+import { tool } from "ai";
+import { z } from "zod";
+import type { ToolContext } from "./context.ts";
+import { PermissionDeniedError } from "../permissions/gate.ts";
+
+const MAX_BYTES = 2_000_000; // cap download size
+const MAX_TEXT = 20_000; // cap returned text
+const TIMEOUT_MS = 20_000;
+
+// Fetch a URL's body as text, with a timeout and size cap. Returns null fields on failure.
+async function fetchText(url: string): Promise<{ status: number; contentType: string; body: string }> {
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), TIMEOUT_MS);
+  try {
+    const res = await fetch(url, {
+      signal: ac.signal,
+      redirect: "follow",
+      headers: { "user-agent": "privateer-agent/0.1.0 (+https://github.com/privateer-agent/privateer-agent)" },
+    });
+    const body = (await res.text()).slice(0, MAX_BYTES);
+    return { status: res.status, contentType: res.headers.get("content-type") ?? "", body };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// Crude HTML→text: drop scripts/styles, turn block-closers into newlines, strip tags,
+// decode the common entities. Good enough to feed page content to the model.
+function htmlToText(html: string): string {
+  return html
+    .replace(/<script[\s\S]*?<\/script>/gi, " ")
+    .replace(/<style[\s\S]*?<\/style>/gi, " ")
+    .replace(/<\/(p|div|h[1-6]|li|tr|section|article|header|footer)>/gi, "\n")
+    .replace(/<br\s*\/?>/gi, "\n")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/&nbsp;/gi, " ")
+    .replace(/&amp;/gi, "&")
+    .replace(/&lt;/gi, "<")
+    .replace(/&gt;/gi, ">")
+    .replace(/&quot;/gi, '"')
+    .replace(/&#39;/gi, "'")
+    .replace(/[ \t]+/g, " ")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+function isHttpUrl(u: string): boolean {
+  try {
+    const parsed = new URL(u);
+    return parsed.protocol === "http:" || parsed.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+export function webFetchTool(ctx: ToolContext) {
+  return tool({
+    description:
+      "Fetch a URL and return its content as text (HTML is stripped to readable text). Use when " +
+      "the user gives a link or you need to read online docs. Network egress, so it may prompt.",
+    inputSchema: z.object({
+      url: z.string().describe("Absolute http(s) URL to fetch."),
+      prompt: z.string().optional().describe("What you're looking for (recorded for context; not a separate model call)."),
+    }),
+    execute: async ({ url, prompt }) => {
+      if (!isHttpUrl(url)) return `Error: not a valid http(s) URL: ${url}`;
+      const decision = await ctx.gate.request({
+        tool: "web_fetch",
+        kind: "fetch",
+        title: "Fetch URL",
+        detail: url,
+      });
+      if (decision === "deny") throw new PermissionDeniedError("web_fetch");
+
+      let result;
+      try {
+        result = await fetchText(url);
+      } catch (err) {
+        return `Error fetching ${url}: ${err instanceof Error ? err.message : String(err)}`;
+      }
+      const text = /html/i.test(result.contentType) ? htmlToText(result.body) : result.body.trim();
+      const capped = text.length > MAX_TEXT ? text.slice(0, MAX_TEXT) + "\n… (truncated)" : text;
+      const header = `[${result.status} · ${result.contentType || "?"}]${prompt ? ` looking for: ${prompt}` : ""}`;
+      return `${header}\n\n${capped || "(empty response)"}`;
+    },
+  });
+}
+
+// DuckDuckGo's keyless HTML endpoint, scraped for result titles + links. No API key
+// required, which keeps web_search working out of the box.
+// Caveat: it scrapes HTML, so it's best-effort and can break if DDG changes markup.
+function parseDdg(html: string, limit: number): string[] {
+  const out: string[] = [];
+  const re = /<a[^>]+class="result__a"[^>]*href="([^"]+)"[^>]*>([\s\S]*?)<\/a>/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(html)) && out.length < limit) {
+    const href = decodeDdgHref(m[1]);
+    const title = htmlToText(m[2]);
+    if (title) out.push(`${title}\n  ${href}`);
+  }
+  return out;
+}
+
+// DDG wraps results as //duckduckgo.com/l/?uddg=<encoded real url>.
+function decodeDdgHref(href: string): string {
+  try {
+    const u = new URL(href, "https://duckduckgo.com");
+    const uddg = u.searchParams.get("uddg");
+    return uddg ? decodeURIComponent(uddg) : u.toString();
+  } catch {
+    return href;
+  }
+}
+
+export function webSearchTool(ctx: ToolContext) {
+  return tool({
+    description:
+      "Search the web and return the top results (title + URL) via DuckDuckGo. Follow up with " +
+      "web_fetch to read a result. Network egress, so it may prompt.",
+    inputSchema: z.object({
+      query: z.string().describe("Search query."),
+    }),
+    execute: async ({ query }) => {
+      const decision = await ctx.gate.request({
+        tool: "web_search",
+        kind: "fetch",
+        title: "Web search",
+        detail: query,
+      });
+      if (decision === "deny") throw new PermissionDeniedError("web_search");
+
+      const url = `https://html.duckduckgo.com/html/?q=${encodeURIComponent(query)}`;
+      let result;
+      try {
+        result = await fetchText(url);
+      } catch (err) {
+        return `Error searching: ${err instanceof Error ? err.message : String(err)}`;
+      }
+      const results = parseDdg(result.body, 8);
+      return results.length
+        ? `Results for "${query}":\n\n${results.join("\n\n")}`
+        : `No results parsed for "${query}" (DuckDuckGo markup may have changed). Try web_fetch with a direct URL.`;
+    },
+  });
+}

package/src/tools/write.ts

@@ -0,0 +1,40 @@
+import { writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { dirname } from "node:path";
+import { tool } from "ai";
+import { z } from "zod";
+import type { ToolContext } from "./context.ts";
+import { resolveInCwd, displayPath, isOutsideScope } from "./context.ts";
+import { PermissionDeniedError } from "../permissions/gate.ts";
+import { isProtectedPath } from "../permissions/protected.ts";
+
+export function writeTool(ctx: ToolContext) {
+  return tool({
+    description:
+      "Write a file, creating parent directories as needed. Overwrites existing files. " +
+      "Prefer the edit tool for small changes to existing files.",
+    inputSchema: z.object({
+      path: z.string().describe("File path to write."),
+      content: z.string().describe("Full file contents."),
+    }),
+    execute: async ({ path, content }) => {
+      const abs = resolveInCwd(ctx, path);
+      const exists = existsSync(abs);
+      const outside = isOutsideScope(ctx, abs);
+      const decision = await ctx.gate.request({
+        tool: "write",
+        kind: "write",
+        title: outside ? "Write outside working directory" : exists ? "Overwrite file" : "Create file",
+        detail: `${outside ? abs : displayPath(ctx, abs)} (${content.split("\n").length} lines)`,
+        protected: isProtectedPath(abs),
+        outside,
+        path: abs,
+      });
+      if (decision === "deny") throw new PermissionDeniedError("write");
+
+      ctx.recordMutation?.(abs);
+      mkdirSync(dirname(abs), { recursive: true });
+      writeFileSync(abs, content, "utf8");
+      return `${exists ? "Wrote" : "Created"} ${displayPath(ctx, abs)} (${content.length} bytes).`;
+    },
+  });
+}

package/src/util/attachmentStore.ts

@@ -0,0 +1,72 @@
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, extname } from "node:path";
+import type { Attachment, Modality } from "./images.ts";
+
+// One stored attachment: its bytes persisted to a stable scratch file, keyed by the
+// "#n" reference the user sees in the prompt.
+export interface StoredAttachment {
+  n: number;
+  path: string; // absolute scratch-file path holding the decoded bytes
+  mediaType: string;
+  modality: Modality;
+  origin: string; // the token the user referenced (for display/debugging)
+}
+
+// Keeps the decoded bytes of every attachment seen this session in a private scratch
+// dir, keyed by its "[Kind #n]" reference, so the `save_attachment` tool can write one
+// back out to a real path on demand.
+//
+// This exists to close the macOS file-promise drop gap: the bytes we capture at
+// paste-time (in resolveAttachments) are the only durable copy — the terminal's
+// …/T/drop-XXXXXX/ file is a volatile stub that may already be gone or truncated by the
+// time the agent goes looking. We copy what we captured into a place we control, once,
+// instead of trusting that path twice.
+export class AttachmentStore {
+  private dir: string | null = null;
+  private readonly byN = new Map<number, StoredAttachment>();
+
+  private ensureDir(): string {
+    // mkdtemp gives a 0700 dir; created lazily so a session that never attaches
+    // anything leaves no temp files behind.
+    if (!this.dir) this.dir = mkdtempSync(join(tmpdir(), "privateer-att-"));
+    return this.dir;
+  }
+
+  // Persist an attachment's bytes to the scratch dir, keyed by n. Idempotent: the same
+  // n (a file referenced twice in a session) is written once and reused.
+  register(att: Attachment): StoredAttachment | undefined {
+    if (att.n == null) return undefined;
+    const existing = this.byN.get(att.n);
+    if (existing) return existing;
+    const file = join(this.ensureDir(), `att-${att.n}${extname(att.path)}`);
+    writeFileSync(file, Buffer.from(att.data, "base64"));
+    const stored: StoredAttachment = {
+      n: att.n,
+      path: file,
+      mediaType: att.mediaType,
+      modality: att.modality,
+      origin: att.path,
+    };
+    this.byN.set(att.n, stored);
+    return stored;
+  }
+
+  get(n: number): StoredAttachment | undefined {
+    return this.byN.get(n);
+  }
+
+  // The reference numbers currently held, ascending — for a helpful error when the
+  // model asks for one that isn't there.
+  refs(): number[] {
+    return [...this.byN.keys()].sort((a, b) => a - b);
+  }
+
+  // Remove the scratch dir (e.g. on session exit). Safe to call when nothing was stored.
+  cleanup(): void {
+    if (!this.dir) return;
+    rmSync(this.dir, { recursive: true, force: true });
+    this.dir = null;
+    this.byN.clear();
+  }
+}