privateer-agent 0.1.0 → 0.2.1

package/src/routines/store.ts

@@ -0,0 +1,205 @@
+import { mkdirSync, writeFileSync, readFileSync, existsSync, chmodSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { globalDir } from "../config/load.ts";
+import { Routine, RoutineFile } from "./schema.ts";
+
+// routines.json lives alongside config.json in the global dir. It can carry the
+// prompt text and (for email delivery) recipient hints, so it is written owner-only
+// (0600) inside the owner-only global dir, mirroring saveGlobalConfig.
+export function routinesFilePath(): string {
+  return join(globalDir(), "routines.json");
+}
+
+// Per-routine output directory (dated result files + latest.md).
+export function routineOutputDir(name: string): string {
+  return join(globalDir(), "routines", slug(name));
+}
+
+function slug(name: string): string {
+  return name.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "routine";
+}
+
+// A stable relay terminal id for the daemon, persisted so it reappears as the same
+// "Privateer Routines" terminal in the app across restarts (rather than a fresh
+// random terminal each boot). Random on first use so it stays unique per install —
+// the relay routes on this id with no user namespacing, so a shared constant could
+// collide across accounts. Matches the server's isValidTermId (`[A-Za-z0-9_-]{8,64}`).
+export function routineRelayId(): string {
+  const path = join(globalDir(), "routines", "relay-id");
+  if (existsSync(path)) {
+    const existing = readFileSync(path, "utf8").trim();
+    if (/^[A-Za-z0-9_-]{8,64}$/.test(existing)) return existing;
+  }
+  const id = `routines-${randomUUID().replace(/-/g, "")}`;
+  const dir = join(globalDir(), "routines");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(path, id + "\n", { encoding: "utf8", mode: 0o600 });
+  tryChmod(path, 0o600);
+  return id;
+}
+
+function tryChmod(path: string, mode: number): void {
+  try {
+    chmodSync(path, mode);
+  } catch {
+    /* non-POSIX filesystem or insufficient perms — nothing we can do */
+  }
+}
+
+export function loadRoutines(): Routine[] {
+  const path = routinesFilePath();
+  if (!existsSync(path)) return [];
+  try {
+    return RoutineFile.parse(JSON.parse(readFileSync(path, "utf8"))).routines;
+  } catch {
+    // A corrupt or hand-edited file shouldn't crash the daemon; treat as empty.
+    return [];
+  }
+}
+
+export function saveRoutines(routines: Routine[]): void {
+  const dir = globalDir();
+  mkdirSync(dir, { recursive: true });
+  tryChmod(dir, 0o700);
+  const payload: RoutineFile = { routines };
+  writeFileSync(routinesFilePath(), JSON.stringify(payload, null, 2) + "\n", {
+    encoding: "utf8",
+    mode: 0o600,
+  });
+  tryChmod(routinesFilePath(), 0o600);
+}
+
+// Look up by id first, then by (case-insensitive) name for CLI convenience.
+export function findRoutine(routines: Routine[], idOrName: string): Routine | undefined {
+  const needle = idOrName.trim().toLowerCase();
+  return (
+    routines.find((r) => r.id === idOrName) ??
+    routines.find((r) => r.name.toLowerCase() === needle)
+  );
+}
+
+// Insert or replace a routine (matched by id), persisting the whole file.
+export function upsertRoutine(routine: Routine): Routine[] {
+  const routines = loadRoutines();
+  const i = routines.findIndex((r) => r.id === routine.id);
+  if (i >= 0) routines[i] = routine;
+  else routines.push(routine);
+  saveRoutines(routines);
+  return routines;
+}
+
+// Remove a routine by id or name. Returns the removed routine, or null if absent.
+export function removeRoutine(idOrName: string): Routine | null {
+  const routines = loadRoutines();
+  const target = findRoutine(routines, idOrName);
+  if (!target) return null;
+  saveRoutines(routines.filter((r) => r.id !== target.id));
+  return target;
+}
+
+// Write a run's result to the routine's output dir: a dated file plus latest.md.
+// Returns the absolute path of latest.md.
+export function writeRoutineOutput(name: string, content: string): string {
+  const dir = routineOutputDir(name);
+  mkdirSync(dir, { recursive: true });
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  writeFileSync(join(dir, `${stamp}.md`), content, "utf8");
+  const latest = join(dir, "latest.md");
+  writeFileSync(latest, content, "utf8");
+  return latest;
+}
+
+// A pending routine result queued for the next interactive session ("notice"
+// delivery). The TUI drains these on startup so results surface even when no
+// terminal was attached at fire time.
+export interface RoutineNotice {
+  routine: string;
+  at: string; // ISO timestamp
+  status: "ok" | "error";
+  preview: string; // short single-line summary
+  path?: string; // latest.md, when file delivery also ran
+}
+
+function noticesPath(): string {
+  return join(globalDir(), "routines", "notices.json");
+}
+
+export function loadNotices(): RoutineNotice[] {
+  const path = noticesPath();
+  if (!existsSync(path)) return [];
+  try {
+    const data = JSON.parse(readFileSync(path, "utf8"));
+    return Array.isArray(data) ? (data as RoutineNotice[]) : [];
+  } catch {
+    return [];
+  }
+}
+
+export function addNotice(notice: RoutineNotice): void {
+  const dir = join(globalDir(), "routines");
+  mkdirSync(dir, { recursive: true });
+  const notices = loadNotices();
+  notices.push(notice);
+  // Keep the queue bounded so an offline stretch can't grow it without limit.
+  const trimmed = notices.slice(-50);
+  writeFileSync(noticesPath(), JSON.stringify(trimmed, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
+  tryChmod(noticesPath(), 0o600);
+}
+
+// Read and clear the notice queue (called by the TUI on startup).
+export function drainNotices(): RoutineNotice[] {
+  const notices = loadNotices();
+  if (notices.length === 0) return [];
+  try {
+    writeFileSync(noticesPath(), "[]\n", { encoding: "utf8", mode: 0o600 });
+  } catch {
+    /* best-effort clear */
+  }
+  return notices;
+}
+
+// A relay result produced while no controller was attached, held until the app
+// next connects. Persisted (not just in-memory) so it survives a daemon restart.
+export interface PendingRelay {
+  routine: string;
+  at: string; // ISO timestamp
+  content: string;
+}
+
+function pendingRelayPath(): string {
+  return join(globalDir(), "routines", "pending-relay.json");
+}
+
+export function loadPendingRelay(): PendingRelay[] {
+  const path = pendingRelayPath();
+  if (!existsSync(path)) return [];
+  try {
+    const data = JSON.parse(readFileSync(path, "utf8"));
+    return Array.isArray(data) ? (data as PendingRelay[]) : [];
+  } catch {
+    return [];
+  }
+}
+
+export function addPendingRelay(entry: PendingRelay): void {
+  const dir = join(globalDir(), "routines");
+  mkdirSync(dir, { recursive: true });
+  const queue = loadPendingRelay();
+  queue.push(entry);
+  const trimmed = queue.slice(-50); // bound the backlog
+  writeFileSync(pendingRelayPath(), JSON.stringify(trimmed, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
+  tryChmod(pendingRelayPath(), 0o600);
+}
+
+// Read and clear the pending-relay queue (called when a controller attaches).
+export function drainPendingRelay(): PendingRelay[] {
+  const queue = loadPendingRelay();
+  if (queue.length === 0) return [];
+  try {
+    writeFileSync(pendingRelayPath(), "[]\n", { encoding: "utf8", mode: 0o600 });
+  } catch {
+    /* best-effort clear */
+  }
+  return queue;
+}

package/src/routines/toolSelect.ts

@@ -0,0 +1,48 @@
+import type { ToolSet } from "ai";
+
+// A routine's `tools` field mixes builtin tool names with MCP selectors. MCP tools
+// are namespaced "<server>__<tool>" (see adaptMcpTools), and no builtin name contains
+// "__", so the separator is unambiguous: entries with "__" are MCP selectors — an
+// exact tool name or a per-server wildcard "<server>__*" — everything else is a
+// builtin allowlist entry.
+
+export interface RoutineToolSplit {
+  // Builtin tool names (read, glob, ...). Empty → caller falls back to the safe set.
+  builtin: string[];
+  // MCP selectors: "<server>__<tool>" exact, or "<server>__*" for a whole server.
+  mcp: string[];
+  // Unique server prefixes from `mcp`, i.e. which servers need connecting at all.
+  servers: string[];
+}
+
+export function splitRoutineTools(tools?: string[]): RoutineToolSplit {
+  const builtin: string[] = [];
+  const mcp: string[] = [];
+  const servers = new Set<string>();
+  for (const t of tools ?? []) {
+    const sep = t.indexOf("__");
+    if (sep > 0) {
+      mcp.push(t);
+      servers.add(t.slice(0, sep));
+    } else {
+      builtin.push(t);
+    }
+  }
+  return { builtin, mcp, servers: [...servers] };
+}
+
+// Does a namespaced MCP tool name match a selector? Exact match, or "<server>__*"
+// matching any tool on that server.
+export function matchesSelector(name: string, selector: string): boolean {
+  if (selector.endsWith("__*")) return name.startsWith(selector.slice(0, -1));
+  return name === selector;
+}
+
+// Narrow a connected MCP toolset to the selected tools. Least privilege matters here:
+// routine runs use the auto-approve gate, so anything left in this set fires without
+// a human in the loop.
+export function filterMcpTools(tools: ToolSet, selectors: string[]): ToolSet {
+  return Object.fromEntries(
+    Object.entries(tools).filter(([name]) => selectors.some((s) => matchesSelector(name, s))),
+  );
+}

package/src/routines/trigger.ts

@@ -0,0 +1,41 @@
+import { nextRun as cronNext, cronError } from "./cron.ts";
+import { isRecurring, type Routine } from "./schema.ts";
+
+// A routine's trigger: a recurring `cron` expression or a one-off `at` datetime.
+type Trigger = Pick<Routine, "cron" | "at">;
+
+// Validate the trigger, returning an error message or null. Enforces "exactly one"
+// and that the chosen form parses.
+export function triggerError(t: Trigger): string | null {
+  const hasCron = Boolean(t.cron);
+  const hasAt = Boolean(t.at);
+  if (hasCron === hasAt) return "set exactly one of `cron` (recurring) or `at` (one-off)";
+  if (hasCron) return cronError(t.cron!);
+  return Number.isNaN(Date.parse(t.at!)) ? `invalid datetime "${t.at}"` : null;
+}
+
+// The fire time to store as `nextRun`. For cron: the next match strictly after
+// `from`. For a one-off: the fixed `at` time as-is (even if already past, so a
+// missed one-off still fires once when the daemon comes back). Null if unparseable.
+export function computeNextRun(t: Trigger, from: Date = new Date()): Date | null {
+  if (t.cron) return cronNext(t.cron, from);
+  if (t.at) {
+    const d = new Date(t.at);
+    return Number.isNaN(d.getTime()) ? null : d;
+  }
+  return null;
+}
+
+// After a run, what to persist. Recurring routines reschedule; one-offs disable
+// themselves (they've now fired).
+export function advanceAfterRun(routine: Routine, from: Date = new Date()): Partial<Routine> {
+  if (isRecurring(routine)) return { nextRun: computeNextRun(routine, from)?.toISOString() };
+  return { enabled: false, nextRun: undefined };
+}
+
+// Short human description of when a routine fires, for /routine listings.
+export function describeTrigger(t: Trigger): string {
+  if (t.cron) return t.cron;
+  if (t.at) return `once @ ${new Date(t.at).toLocaleString()}`;
+  return "(no trigger)";
+}

package/src/session.ts

@@ -9,6 +9,7 @@ import { findOutputStyle } from "./context/outputStyles.ts";
 import { QueryEngine } from "./engine/QueryEngine.ts";
 import { autoApproveGate, type PermissionGate } from "./permissions/gate.ts";
 import type { SubAgentRunner } from "./tools/context.ts";
+import type { UserAsker } from "./tools/askUser.ts";
 import { TodoStore } from "./tools/todoStore.ts";
 import type { CheckpointStore } from "./memory/checkpoints.ts";
 import type { ProcessRegistry } from "./tools/processRegistry.ts";
@@ -34,6 +35,10 @@ export interface SessionOptions {
   checkpoints?: CheckpointStore;
   // Extra tools merged into the toolset (e.g. tools exposed by MCP servers).
   extraTools?: ToolSet;
+  // When set, restrict the built-in toolset to these tool names (MCP `extraTools`
+  // are always kept). Used for unattended runs (scheduled routines) that must not
+  // have write/bash/edit auto-approved with no human to gate them.
+  allowedTools?: string[];
   // Background-shell registry for bash run_in_background / bash_output / kill_shell.
   processes?: ProcessRegistry;
   // Session attachment store, so dragged/pasted file bytes can be saved via the
@@ -42,6 +47,17 @@ export interface SessionOptions {
   // Reports each finished `task` sub-agent's run metrics (tool uses + tokens) by
   // tool-call id, so the TUI can render the grouped agents view. Best-effort.
   onSubAgentMetrics?: (toolCallId: string, m: { toolUses: number; tokens: number }) => void;
+  // Surfaces an `ask_user` question to the live TUI and resolves with the choice.
+  // Omitted outside the interactive app, where ask_user reports it couldn't ask.
+  askUser?: UserAsker;
+  // Streams a file to the connected remote controller (Privateer app), for the
+  // send_file_to_client tool. Omitted when remote access isn't available.
+  sendFileToController?: (file: {
+    name: string;
+    mediaType: string;
+    base64: string;
+    size: number;
+  }) => Promise<{ ok: boolean; reason?: string }>;
 }
 
 export interface Session {
@@ -114,20 +130,29 @@ export function createSession(opts: SessionOptions): Session {
     });
 
   const hooks = new HookRunner(loadHooks((opts.config as Record<string, unknown>).hooks), opts.cwd);
+  let builtinTools = createTools({
+    cwd: opts.cwd,
+    gate,
+    confineToCwd,
+    allowedOutsideRoots,
+    todos,
+    runSubAgent,
+    onSubAgentMetrics: opts.onSubAgentMetrics,
+    recordMutation: opts.checkpoints ? (abs) => opts.checkpoints!.recordMutation(abs) : undefined,
+    processes: opts.processes,
+    attachments,
+    askUser: opts.askUser,
+    sendFileToController: opts.sendFileToController,
+  });
+  if (opts.allowedTools) {
+    const allow = new Set(opts.allowedTools);
+    builtinTools = Object.fromEntries(
+      Object.entries(builtinTools).filter(([name]) => allow.has(name)),
+    );
+  }
   const tools = wrapToolsWithHooks(
     {
-      ...createTools({
-        cwd: opts.cwd,
-        gate,
-        confineToCwd,
-        allowedOutsideRoots,
-        todos,
-        runSubAgent,
-        onSubAgentMetrics: opts.onSubAgentMetrics,
-        recordMutation: opts.checkpoints ? (abs) => opts.checkpoints!.recordMutation(abs) : undefined,
-        processes: opts.processes,
-        attachments,
-      }),
+      ...builtinTools,
       ...(opts.extraTools ?? {}),
     },
     hooks,

package/src/skills/installer.ts

@@ -0,0 +1,222 @@
+import { execFile } from "node:child_process";
+import {
+  copyFileSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve, sep } from "node:path";
+import { promisify } from "node:util";
+import { globalPaths, projectPaths } from "../config/paths.ts";
+import { parseFrontmatter } from "../commands/custom.ts";
+import { walkFiles } from "../tools/walk.ts";
+import { isInsideDir } from "../tools/context.ts";
+import { SKILL_NAME_RE, loadSkills } from "./loader.ts";
+
+// Installs skills from GitHub into .privateer/skills/. Security posture: nothing
+// from a fetched repo is ever executed at install time (no hooks, no scripts) —
+// files are only copied. Symlinks are dropped (they could alias paths outside the
+// skill), per-skill size/count caps bound the copy, and skill names are validated
+// before choosing a target directory. A skill's scripts only ever run later via
+// the bash tool, under the normal permission gate — the same trust model as any
+// file the model reads.
+
+const execFileAsync = promisify(execFile);
+
+const MAX_FILES = 100;
+const MAX_BYTES = 20 * 1024 * 1024;
+
+export interface SkillSource {
+  repoUrl: string;
+  ref?: string;
+  subpath?: string;
+}
+
+// Accepts "owner/repo", "owner/repo/path/to/skill", "https://github.com/owner/repo[.git]",
+// and "https://github.com/owner/repo/tree/<ref>/<path>".
+export function parseSkillSource(src: string): SkillSource {
+  const s = src.trim().replace(/\/+$/, "");
+  const reject = () =>
+    new Error(
+      `Unrecognized skill source "${src}". Use owner/repo, owner/repo/path, or a github.com URL.`,
+    );
+  let m = /^https:\/\/github\.com\/([^/]+)\/([^/]+?)(?:\.git)?(?:\/tree\/([^/]+)(?:\/(.+))?)?$/.exec(s);
+  let owner: string, repo: string, ref: string | undefined, subpath: string | undefined;
+  if (m) {
+    [, owner, repo, ref, subpath] = m;
+  } else if (/^[\w.-]+\/[\w.-]+(\/.*)?$/.test(s) && !s.includes(":")) {
+    const parts = s.split("/");
+    [owner, repo] = parts;
+    subpath = parts.length > 2 ? parts.slice(2).join("/") : undefined;
+  } else {
+    throw reject();
+  }
+  if (subpath?.split("/").some((p) => p === ".." || p === "")) throw reject();
+  return { repoUrl: `https://github.com/${owner}/${repo}.git`, ref, subpath };
+}
+
+// Find installable skills (directories containing a valid SKILL.md) under a local
+// directory. With a subpath that itself holds a SKILL.md, that single skill is
+// returned; otherwise the tree is scanned. Pure fs — no network.
+export function discoverSkills(
+  rootDir: string,
+  subpath?: string,
+): { found: { name: string; dir: string }[]; invalid: string[] } {
+  const base = subpath ? join(rootDir, subpath) : rootDir;
+  if (!existsSync(base)) throw new Error(`Path "${subpath ?? "."}" not found in the repository.`);
+  const candidates: string[] = [];
+  if (existsSync(join(base, "SKILL.md"))) {
+    candidates.push(base);
+  } else {
+    for (const rel of walkFiles(base)) {
+      if (!rel.endsWith("/SKILL.md")) continue;
+      candidates.push(join(base, rel.slice(0, -"/SKILL.md".length)));
+    }
+  }
+  const found: { name: string; dir: string }[] = [];
+  const invalid: string[] = [];
+  for (const dir of candidates) {
+    const { meta } = parseFrontmatter(readFileSync(join(dir, "SKILL.md"), "utf8"));
+    const name = (meta.name || dir.split(sep).pop() || "").toLowerCase();
+    if (!SKILL_NAME_RE.test(name) || !meta.description) {
+      invalid.push(dir === base ? name || "(unnamed)" : name);
+      continue;
+    }
+    found.push({ name, dir });
+  }
+  return { found, invalid };
+}
+
+// Copy one skill directory into the target, skipping symlinks and enforcing the
+// per-skill caps. Cleans up the target on any failure.
+export function copySkillDir(srcDir: string, destDir: string): void {
+  let files = 0;
+  let bytes = 0;
+  const copy = (from: string, to: string) => {
+    mkdirSync(to, { recursive: true });
+    for (const entry of readdirSync(from, { withFileTypes: true })) {
+      const src = join(from, entry.name);
+      const st = lstatSync(src);
+      if (st.isSymbolicLink()) continue;
+      if (st.isDirectory()) {
+        copy(src, join(to, entry.name));
+      } else if (st.isFile()) {
+        files += 1;
+        bytes += st.size;
+        if (files > MAX_FILES || bytes > MAX_BYTES) {
+          throw new Error(`Skill exceeds limits (${MAX_FILES} files / ${MAX_BYTES / 1024 / 1024} MB).`);
+        }
+        copyFileSync(src, join(to, entry.name));
+      }
+    }
+  };
+  try {
+    copy(srcDir, destDir);
+  } catch (err) {
+    rmSync(destDir, { recursive: true, force: true });
+    throw err;
+  }
+}
+
+export interface InstallOptions {
+  scope: "project" | "user";
+  all?: boolean;
+  force?: boolean;
+  cwd?: string;
+}
+
+// Install skills discovered under a local directory (the post-clone half, factored
+// out so tests need neither git nor network).
+export function installFromDir(
+  localDir: string,
+  subpath: string | undefined,
+  opts: InstallOptions,
+): { name: string; dir: string }[] {
+  const { found, invalid } = discoverSkills(localDir, subpath);
+  if (found.length === 0) {
+    throw new Error(
+      `No installable skills found${invalid.length ? ` (invalid: ${invalid.join(", ")})` : ""}.`,
+    );
+  }
+  if (found.length > 1 && !opts.all) {
+    throw new Error(
+      `Found ${found.length} skills: ${found.map((f) => f.name).join(", ")}. ` +
+        `Install one by path (install <src>/<skill-path>) or pass --all.`,
+    );
+  }
+  const root =
+    opts.scope === "project" ? projectPaths(opts.cwd ?? process.cwd()).skills : globalPaths().skills;
+  const installed: { name: string; dir: string }[] = [];
+  for (const skill of found) {
+    const target = join(root, skill.name);
+    if (existsSync(target)) {
+      if (!opts.force) throw new Error(`Skill "${skill.name}" already exists at ${target}. Use --force to replace it.`);
+      rmSync(target, { recursive: true, force: true });
+    }
+    copySkillDir(skill.dir, target);
+    installed.push({ name: skill.name, dir: target });
+  }
+  return installed;
+}
+
+// Fetch a source from GitHub (shallow clone — no archive extraction, no execution)
+// and install the skills it contains.
+export async function installSkills(
+  src: string,
+  opts: InstallOptions,
+): Promise<{ name: string; dir: string }[]> {
+  const { repoUrl, ref, subpath } = parseSkillSource(src);
+  const tmp = mkdtempSync(join(tmpdir(), "privateer-skill-"));
+  try {
+    const args = ["clone", "--depth", "1", ...(ref ? ["--branch", ref] : []), repoUrl, tmp];
+    await execFileAsync("git", args, { timeout: 120_000 }).catch((err) => {
+      throw new Error(`git clone failed for ${repoUrl}: ${err instanceof Error ? err.message : String(err)}`);
+    });
+    return installFromDir(tmp, subpath, opts);
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+// Remove an installed skill by name. Without an explicit scope, project is tried
+// first (mirroring lookup precedence). Resolves by directory name first — the
+// merged loader hides a user-scope skill shadowed by a project one — and falls
+// back to the loader for skills whose frontmatter name differs from their dir.
+export function removeSkill(
+  name: string,
+  opts: { scope?: "project" | "user"; cwd?: string },
+): { dir: string } {
+  const cwd = opts.cwd ?? process.cwd();
+  const roots =
+    opts.scope === "project"
+      ? [projectPaths(cwd).skills]
+      : opts.scope === "user"
+        ? [globalPaths().skills]
+        : [projectPaths(cwd).skills, globalPaths().skills];
+  // The name rule (no separators, no dots) also rules out path traversal here.
+  if (SKILL_NAME_RE.test(name)) {
+    for (const root of roots) {
+      const dir = join(root, name);
+      if (existsSync(dir)) {
+        rmSync(dir, { recursive: true, force: true });
+        return { dir };
+      }
+    }
+  }
+  const skill = loadSkills(cwd).skills.find(
+    (s) => s.name === name && (!opts.scope || s.scope === opts.scope),
+  );
+  if (skill) {
+    const root = skill.scope === "project" ? projectPaths(cwd).skills : globalPaths().skills;
+    if (isInsideDir(root, resolve(skill.dir))) {
+      rmSync(skill.dir, { recursive: true, force: true });
+      return { dir: skill.dir };
+    }
+  }
+  throw new Error(`No installed skill "${name}"${opts.scope ? ` in ${opts.scope} scope` : ""}.`);
+}

package/src/skills/loader.ts

@@ -0,0 +1,88 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { globalPaths, projectPaths } from "../config/paths.ts";
+import { parseFrontmatter } from "../commands/custom.ts";
+
+// An agent skill: a directory under .privateer/skills/ containing SKILL.md
+// (frontmatter + instruction body) plus optional bundled files (scripts/,
+// references/, ...). Format-compatible with Claude Code skills, so published
+// skills work when dropped in unchanged. The model sees only name+description
+// (the catalog in the `skill` tool); the body is loaded on demand.
+export interface SkillDefinition {
+  name: string; // frontmatter `name`, else the directory name
+  description: string; // required — a skill without one is skipped
+  allowedTools?: string[]; // frontmatter `allowed-tools` — parsed, advisory in v1
+  model?: string; // parsed, unused in v1 (skills run inline in the main loop)
+  body: string; // SKILL.md body — the instructions
+  dir: string; // absolute skill directory, base path for bundled files
+  scope: "project" | "user";
+}
+
+// Lowercase alphanumeric + hyphens, ≤64 chars (the Claude Code skill-name rule).
+export const SKILL_NAME_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+function loadFromDir(
+  root: string,
+  scope: "project" | "user",
+): { skills: SkillDefinition[]; warnings: string[] } {
+  const skills: SkillDefinition[] = [];
+  const warnings: string[] = [];
+  if (!existsSync(root)) return { skills, warnings };
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const dir = join(root, entry.name);
+    const file = join(dir, "SKILL.md");
+    if (!existsSync(file)) continue;
+    const { meta, body } = parseFrontmatter(readFileSync(file, "utf8"));
+    const name = (meta.name || entry.name).toLowerCase();
+    if (!SKILL_NAME_RE.test(name)) {
+      warnings.push(`${scope} skill "${entry.name}": invalid name "${name}" — skipped`);
+      continue;
+    }
+    if (!meta.description) {
+      warnings.push(`${scope} skill "${name}": missing description — skipped`);
+      continue;
+    }
+    if (meta.name && meta.name.toLowerCase() !== entry.name.toLowerCase()) {
+      warnings.push(`${scope} skill "${name}": directory is named "${entry.name}"`);
+    }
+    skills.push({
+      name,
+      description: meta.description,
+      allowedTools: meta["allowed-tools"]
+        ?.split(",")
+        .map((s) => s.trim())
+        .filter(Boolean),
+      model: meta.model,
+      body: body.trim(),
+      dir,
+      scope,
+    });
+  }
+  return { skills, warnings };
+}
+
+// User (~/.privateer/skills) then project (./.privateer/skills); a project skill
+// overrides a user skill of the same name.
+export function loadSkills(cwd: string = process.cwd()): {
+  skills: SkillDefinition[];
+  warnings: string[];
+} {
+  const byName = new Map<string, SkillDefinition>();
+  const warnings: string[] = [];
+  for (const scoped of [
+    loadFromDir(globalPaths().skills, "user"),
+    loadFromDir(projectPaths(cwd).skills, "project"),
+  ]) {
+    for (const s of scoped.skills) byName.set(s.name, s);
+    warnings.push(...scoped.warnings);
+  }
+  return {
+    skills: [...byName.values()].sort((a, b) => a.name.localeCompare(b.name)),
+    warnings,
+  };
+}
+
+export function findSkill(name: string, cwd: string = process.cwd()): SkillDefinition | undefined {
+  return loadSkills(cwd).skills.find((s) => s.name === name);
+}