privateer-agent 0.2.1 → 0.3.0

package/src/providers/resolve.ts

@@ -1,78 +0,0 @@
-import type { LanguageModel } from "ai";
-import type { Config } from "../config/schema.ts";
-import { KNOWN_PROVIDERS, type ProviderName } from "../config/schema.ts";
-import { buildModel, providerRequiresKey } from "./registry.ts";
-import { hasCredentials } from "../auth/privateer.ts";
-
-// Privateer's readiness is session-based, not key-based: ready iff logged in.
-function providerReady(name: ProviderName, cfg: { apiKey?: string }): boolean {
-  if (name === "privateer") return hasCredentials();
-  return providerRequiresKey(name) ? Boolean(cfg.apiKey) : true;
-}
-
-export interface ResolvedModel {
-  spec: string; // original "provider:model" string
-  provider: ProviderName;
-  modelId: string;
-  model: LanguageModel;
-}
-
-function isKnownProvider(name: string): name is ProviderName {
-  return (KNOWN_PROVIDERS as readonly string[]).includes(name);
-}
-
-// Parse a "provider:model" spec. The model id itself may contain ":" or "/"
-// (e.g. "openrouter:anthropic/claude-opus-4.8"), so only the first ":" splits.
-export function parseModelSpec(spec: string): { provider: string; modelId: string } {
-  const idx = spec.indexOf(":");
-  if (idx === -1) {
-    throw new Error(
-      `Invalid model "${spec}". Use "provider:model", e.g. openrouter:anthropic/claude-opus-4.8`,
-    );
-  }
-  return { provider: spec.slice(0, idx).trim(), modelId: spec.slice(idx + 1).trim() };
-}
-
-// A Privateer account model is served over one of two privacy channels: NEAR's
-// confidential-compute TEE (model ids prefixed "near/", cryptographically
-// attestable) or the account's zero-data-retention OpenRouter proxy (every other
-// id, pinned to ZDR endpoints server-side). The picker and the status-bar shield
-// both surface this so the active privacy channel is always visible.
-export type PrivateerChannel = "tee" | "zdr";
-
-export function privateerChannel(modelId: string): PrivateerChannel {
-  return modelId.startsWith("near/") ? "tee" : "zdr";
-}
-
-// Turn a model spec + config into a ready-to-use AI SDK model, validating that the
-// provider is known and configured. Construction does not hit the network.
-export function resolveModel(spec: string, config: Config): ResolvedModel {
-  const { provider, modelId } = parseModelSpec(spec);
-
-  if (!isKnownProvider(provider)) {
-    throw new Error(
-      `Unknown provider "${provider}". Known: ${KNOWN_PROVIDERS.join(", ")}.`,
-    );
-  }
-  if (!modelId) throw new Error(`Missing model id in "${spec}".`);
-
-  const cfg = config.providers[provider] ?? {};
-  if (provider === "privateer" && !hasCredentials()) {
-    throw new Error(`Not signed in to your Privateer account. Run /login first.`);
-  }
-  if (provider !== "privateer" && providerRequiresKey(provider) && !cfg.apiKey) {
-    throw new Error(
-      `No API key for "${provider}". Set ${provider.toUpperCase()}_API_KEY or add it to ~/.privateer/config.json.`,
-    );
-  }
-
-  return { spec, provider, modelId, model: buildModel(provider, cfg, modelId) };
-}
-
-// Which providers currently have working credentials — used by /doctor and provider listing.
-export function configuredProviders(config: Config): { name: ProviderName; ready: boolean }[] {
-  return KNOWN_PROVIDERS.map((name) => {
-    const cfg = config.providers[name] ?? {};
-    return { name, ready: providerReady(name, cfg) };
-  });
-}

package/src/skills/installer.ts

@@ -1,222 +0,0 @@
-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

@@ -1,88 +0,0 @@
-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);
-}

package/src/tools/askUser.ts

@@ -1,92 +0,0 @@
-import { tool } from "ai";
-import { z } from "zod";
-import type { ToolContext } from "./context.ts";
-
-// A single selectable approach presented to the user.
-export interface UserChoiceOption {
-  label: string;
-  description?: string;
-}
-
-// A decision the model surfaces to the user via the `ask_user` tool.
-export interface UserQuestion {
-  question: string;
-  options: UserChoiceOption[];
-  multiSelect: boolean;
-}
-
-// The user's answer: chosen option index(es), free-form custom text, or a dismissal.
-export type UserAnswer =
-  | { kind: "selected"; indices: number[] }
-  | { kind: "custom"; text: string }
-  | { kind: "dismissed" };
-
-// Bridge supplied by the interactive session: surface a question to the TUI and
-// resolve with the user's choice. Absent in non-interactive contexts (sub-agents,
-// remote-driven turns, headless runs), where the tool reports it couldn't ask.
-export type UserAsker = (q: UserQuestion) => Promise<UserAnswer>;
-
-// The `ask_user` tool: when the right implementation direction is genuinely
-// ambiguous, the model puts a small menu of approaches to the user and blocks until
-// they pick one (or write their own answer). No filesystem mutation, so it isn't
-// gated — but it does pause the turn on the human, exactly like the approval prompt.
-export function askUserTool(ctx: ToolContext) {
-  return tool({
-    description:
-      "Ask the user to choose between competing implementation directions when the right " +
-      "approach is genuinely ambiguous and the choice materially changes the work (architecture, " +
-      "a library, a data model, the scope of a change). Present 2–4 concrete options, " +
-      "most-recommended first, each with its trade-offs; the user picks one (or writes their own " +
-      "answer). Prefer this over silently guessing on a consequential fork. Do NOT use it for " +
-      "trivial choices you can reasonably make yourself, or to request permission for an action — " +
-      "the approval gate handles permissions.",
-    inputSchema: z.object({
-      question: z.string().describe("The decision to put to the user, phrased as a question."),
-      options: z
-        .array(
-          z.object({
-            label: z
-              .string()
-              .describe("Short name for this approach, e.g. 'Server-side rendering'."),
-            description: z
-              .string()
-              .optional()
-              .describe("One or two sentences on what it entails and its trade-offs."),
-          }),
-        )
-        .min(2)
-        .max(4)
-        .describe("The competing approaches, most-recommended first."),
-      multiSelect: z
-        .boolean()
-        .optional()
-        .describe("Allow the user to choose more than one option (default false)."),
-    }),
-    execute: async ({ question, options, multiSelect }) => {
-      if (!ctx.askUser) {
-        return (
-          "Cannot ask the user interactively in this context. Pick the best option using your " +
-          "own judgment, then state which you chose and why before proceeding."
-        );
-      }
-      const answer = await ctx.askUser({ question, options, multiSelect: multiSelect ?? false });
-      if (answer.kind === "custom") {
-        return `The user answered: ${answer.text}`;
-      }
-      if (answer.kind === "dismissed") {
-        return (
-          "The user dismissed the question without choosing. Either restate the choice briefly in " +
-          "plain prose, or proceed with the best option and say which you picked."
-        );
-      }
-      const chosen = answer.indices.map((i) => options[i]).filter(Boolean);
-      if (chosen.length === 0) {
-        return "The user made no selection. Proceed with the best option and state which you chose.";
-      }
-      const rendered = chosen
-        .map((o) => (o.description ? `"${o.label}" (${o.description})` : `"${o.label}"`))
-        .join(", ");
-      return `The user chose: ${rendered}. Proceed with this direction.`;
-    },
-  });
-}

package/src/tools/bash.ts

@@ -1,98 +0,0 @@
-import { tool } from "ai";
-import { z } from "zod";
-import type { ToolContext } from "./context.ts";
-import { exec } from "./exec.ts";
-import { PermissionDeniedError } from "../permissions/gate.ts";
-
-const DEFAULT_TIMEOUT = 120_000;
-const MAX_TIMEOUT = 600_000;
-// Cap how much command output enters the conversation. Unbounded output (a big
-// `git diff`, a verbose build log) is otherwise re-sent on every subsequent step of
-// the agentic loop, ballooning token usage. Keep the head and tail — both ends carry
-// the most signal (the command's start and its final status/errors).
-const MAX_OUTPUT_CHARS = 30_000;
-const HEAD_CHARS = 20_000;
-
-function clampOutput(text: string): string {
-  if (text.length <= MAX_OUTPUT_CHARS) return text;
-  const head = text.slice(0, HEAD_CHARS);
-  const tail = text.slice(text.length - (MAX_OUTPUT_CHARS - HEAD_CHARS));
-  const omitted = text.length - MAX_OUTPUT_CHARS;
-  return `${head}\n… (${omitted} chars of output truncated) …\n${tail}`;
-}
-
-export function bashTool(ctx: ToolContext) {
-  return tool({
-    description:
-      "Run a shell command in the working directory and return its output. " +
-      "Use for builds, tests, git, and other CLI tasks. Avoid long-running/interactive commands.",
-    inputSchema: z.object({
-      command: z.string().describe("The shell command to run."),
-      timeout: z.number().int().positive().optional().describe("Timeout in ms (max 600000)."),
-      run_in_background: z
-        .boolean()
-        .optional()
-        .describe("Run detached and return immediately; poll with bash_output, stop with kill_shell."),
-    }),
-    execute: async ({ command, timeout, run_in_background }) => {
-      const decision = await ctx.gate.request({
-        tool: "bash",
-        kind: "bash",
-        title: run_in_background ? "Run command (background)" : "Run command",
-        detail: command,
-      });
-      if (decision === "deny") throw new PermissionDeniedError("bash");
-
-      if (run_in_background) {
-        if (!ctx.processes) return "Background execution is not available in this context.";
-        const id = ctx.processes.spawn(command, ctx.cwd);
-        return `Started in background as ${id}. Read output with bash_output(bash_id="${id}"); stop with kill_shell(bash_id="${id}").`;
-      }
-
-      const timeoutMs = Math.min(timeout ?? DEFAULT_TIMEOUT, MAX_TIMEOUT);
-      const { stdout, stderr, code, timedOut } = await exec(command, [], {
-        cwd: ctx.cwd,
-        timeoutMs,
-        shell: true,
-      });
-
-      const parts: string[] = [];
-      if (stdout.trim()) parts.push(clampOutput(stdout.trimEnd()));
-      if (stderr.trim()) parts.push(`[stderr]\n${clampOutput(stderr.trimEnd())}`);
-      if (timedOut) parts.push(`[timed out after ${timeoutMs}ms]`);
-      parts.push(`[exit code ${code ?? "null"}]`);
-      return parts.join("\n");
-    },
-  });
-}
-
-export function bashOutputTool(ctx: ToolContext) {
-  return tool({
-    description:
-      "Read new output from a background shell started with bash run_in_background. Returns only " +
-      "output produced since the previous read, plus the shell's status.",
-    inputSchema: z.object({
-      bash_id: z.string().describe("The background shell id (e.g. bash_1)."),
-    }),
-    execute: async ({ bash_id }) => {
-      if (!ctx.processes) return "Background processes are not available in this context.";
-      const r = ctx.processes.read(bash_id);
-      if (!r) return `No background shell "${bash_id}".`;
-      const head = `[${r.status}${r.status === "exited" ? `, exit ${r.code ?? "null"}` : ""}]`;
-      return r.output ? `${head}\n${r.output.trimEnd()}` : `${head} (no new output)`;
-    },
-  });
-}
-
-export function killShellTool(ctx: ToolContext) {
-  return tool({
-    description: "Stop a background shell started with bash run_in_background.",
-    inputSchema: z.object({
-      bash_id: z.string().describe("The background shell id to stop."),
-    }),
-    execute: async ({ bash_id }) => {
-      if (!ctx.processes) return "Background processes are not available in this context.";
-      return ctx.processes.kill(bash_id) ? `Stopped ${bash_id}.` : `No background shell "${bash_id}".`;
-    },
-  });
-}