privateer-agent 0.1.0

package/src/config/schema.ts

@@ -0,0 +1,94 @@
+import { z } from "zod";
+import { DEFAULT_DENYLIST } from "../permissions/danger.ts";
+
+// A provider's credentials/endpoint. All fields optional so config can be sparse
+// and filled in from environment variables at load time.
+export const ProviderConfig = z.object({
+  apiKey: z.string().optional(),
+  baseURL: z.string().optional(),
+  // OpenRouter only: when true, every request is pinned to a Zero-Data-Retention
+  // endpoint (provider.zdr) so prompts can't be retained. Models without a ZDR
+  // endpoint then become unusable (and render red in the picker). Ignored by
+  // other providers.
+  enforceZdr: z.boolean().optional(),
+});
+export type ProviderConfig = z.infer<typeof ProviderConfig>;
+
+export const PERMISSION_MODES = ["default", "acceptEdits", "bypass", "plan"] as const;
+export type PermissionMode = (typeof PERMISSION_MODES)[number];
+
+export const Config = z.object({
+  // "provider:model", e.g. "openrouter:anthropic/claude-opus-4.8".
+  defaultModel: z.string().default("anthropic:claude-opus-4-8"),
+  permissionMode: z.enum(PERMISSION_MODES).default("acceptEdits"),
+  providers: z
+    .object({
+      openrouter: ProviderConfig.optional(),
+      anthropic: ProviderConfig.optional(),
+      openai: ProviderConfig.optional(),
+      ollama: ProviderConfig.optional(),
+      nearai: ProviderConfig.optional(),
+      // Privateer account: inference billed to the user's account, no API key.
+      // Auth lives in ~/.privateer/credentials.json (see src/auth/privateer.ts),
+      // not here; this entry only carries an optional server baseURL override.
+      privateer: ProviderConfig.optional(),
+    })
+    .default({}),
+  // Confine file access to the working directory. When true (the default), the agent
+  // reads/searches/edits only within cwd; reaching outside (an absolute path or `../`
+  // escape) requires explicit per-location approval. Set false to let it roam freely.
+  confineToCwd: z.boolean().default(true),
+  // Bash command prefixes that are auto-approved (e.g. "git status", "ls").
+  allowlist: z.array(z.string()).default([]),
+  // Regex sources for commands that ALWAYS require confirmation, even under
+  // bypass or an allowlist entry (destructive/exfil shapes). Extend per-project.
+  denylist: z.array(z.string()).default(DEFAULT_DENYLIST),
+  // Hard cap on agent tool-loop steps per turn.
+  maxSteps: z.number().int().positive().default(50),
+  // Approx token budget for the conversation context (used to trigger auto-compaction).
+  contextBudget: z.number().int().positive().default(120_000),
+  // Fraction of contextBudget at which to auto-compact older history (0–1).
+  compactRatio: z.number().positive().max(1).default(0.8),
+  // Modal (vim) editing in the prompt input.
+  vim: z.boolean().default(false),
+  // Active output style (persona) by name; loaded from .privateer/output-styles.
+  outputStyle: z.string().optional(),
+  // Max `task` sub-agents allowed to run concurrently when the model fans them out.
+  maxSubagents: z.number().int().positive().default(4),
+  // Anthropic extended-thinking budget in tokens (opt-in; Anthropic models only).
+  thinkingBudget: z.number().int().positive().optional(),
+  // Per-turn model routing. The `default` route is `defaultModel` above; these are
+  // the specialized routes the router switches to based on the turn's data/shape.
+  // See src/engine/router.ts for the selection rules (vision > long > fast > default).
+  router: z
+    .object({
+      // Per-modality routes — turns whose input includes that kind go to this model.
+      vision: z.string().optional(), // image input
+      document: z.string().optional(), // PDF / document input
+      audio: z.string().optional(), // audio input
+      video: z.string().optional(), // video input
+      long: z.string().optional(), // large conversations
+      fast: z.string().optional(), // short, cheap turns
+      // Estimated-token threshold that triggers the `long` route. Defaults to half
+      // the contextBudget when unset (resolved in the session, not here).
+      longThreshold: z.number().int().positive().optional(),
+      // Prompts at or below this many characters are eligible for the `fast` route.
+      fastMaxChars: z.number().int().positive().default(280),
+      // Referenced text/code files at or below this many bytes are inlined into the
+      // prompt (read-as-text); larger ones are left as a path for the read tool.
+      inlineTextMaxBytes: z.number().int().positive().default(65_536),
+      // Hybrid auto-detect: when a modality route is unset and the default model can't
+      // handle that modality, pick a capable model automatically.
+      auto: z.boolean().default(true),
+    })
+    .optional(),
+  // Shell command whose stdout becomes the status line; receives session JSON on stdin.
+  statusLine: z.string().optional(),
+})
+  // Preserve unknown keys so layered settings files can carry forward-compatible
+  // sections (hooks, mcpServers, statusLine, …) before they have explicit schemas.
+  .catchall(z.unknown());
+export type Config = z.infer<typeof Config>;
+
+export const KNOWN_PROVIDERS = ["openrouter", "anthropic", "openai", "ollama", "nearai", "privateer"] as const;
+export type ProviderName = (typeof KNOWN_PROVIDERS)[number];

package/src/context/outputStyles.ts

@@ -0,0 +1,42 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { globalPaths, projectPaths } from "../config/paths.ts";
+import { walkFiles } from "../tools/walk.ts";
+import { parseFrontmatter } from "../commands/custom.ts";
+
+// A persona/behavior preset loaded from .privateer/output-styles/<name>.md. Its body
+// replaces the default tone section of the system prompt while the tool policy,
+// security stance, and environment grounding stay intact.
+export interface OutputStyle {
+  name: string;
+  description?: string;
+  body: string;
+  scope: "project" | "user";
+}
+
+function loadFromDir(dir: string, scope: "project" | "user"): OutputStyle[] {
+  if (!existsSync(dir)) return [];
+  const out: OutputStyle[] = [];
+  for (const rel of walkFiles(dir)) {
+    if (!rel.endsWith(".md")) continue;
+    const { meta, body } = parseFrontmatter(readFileSync(join(dir, rel), "utf8"));
+    out.push({
+      name: rel.replace(/\.md$/, "").split("/").join(":"),
+      description: meta.description,
+      body: body.trim(),
+      scope,
+    });
+  }
+  return out;
+}
+
+export function loadOutputStyles(cwd: string = process.cwd()): OutputStyle[] {
+  const byName = new Map<string, OutputStyle>();
+  for (const s of loadFromDir(globalPaths().outputStyles, "user")) byName.set(s.name, s);
+  for (const s of loadFromDir(projectPaths(cwd).outputStyles, "project")) byName.set(s.name, s);
+  return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function findOutputStyle(name: string, cwd: string = process.cwd()): OutputStyle | undefined {
+  return loadOutputStyles(cwd).find((s) => s.name === name);
+}

package/src/context/projectInfo.ts

@@ -0,0 +1,59 @@
+import { execFileSync } from "node:child_process";
+import { walkFiles } from "../tools/walk.ts";
+
+// Lightweight, synchronous environment probes used to enrich the system prompt at
+// session start. Everything here fails soft: outside a git repo, or if `git` is
+// missing, the git block is simply omitted rather than throwing.
+
+function git(cwd: string, args: string[]): string | null {
+  try {
+    return execFileSync("git", args, {
+      cwd,
+      encoding: "utf8",
+      timeout: 3_000,
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+export interface GitInfo {
+  branch: string;
+  status: string; // short porcelain, possibly truncated
+  recent: string; // last few commit subjects
+}
+
+// A compact git snapshot, or null when cwd isn't a working tree.
+export function gitStatus(cwd: string): GitInfo | null {
+  const inside = git(cwd, ["rev-parse", "--is-inside-work-tree"]);
+  if (inside !== "true") return null;
+
+  const branch = git(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]) || "(detached)";
+  const raw = git(cwd, ["status", "--porcelain"]) ?? "";
+  const lines = raw ? raw.split("\n") : [];
+  const status =
+    lines.length === 0
+      ? "(clean)"
+      : lines.slice(0, 20).join("\n") +
+        (lines.length > 20 ? `\n… (+${lines.length - 20} more)` : "");
+  const recent = git(cwd, ["log", "--oneline", "-5"]) ?? "";
+
+  return { branch, status, recent };
+}
+
+// A shallow snapshot of the project's files (respecting walk's skip list), capped
+// so the prompt stays small. Gives the model a sense of layout before it explores.
+export function dirSnapshot(cwd: string, limit = 40): string {
+  let files: string[];
+  try {
+    files = walkFiles(cwd);
+  } catch {
+    return "";
+  }
+  if (files.length === 0) return "";
+  files.sort();
+  const shown = files.slice(0, limit);
+  const more = files.length > limit ? `\n… (+${files.length - limit} more files)` : "";
+  return shown.join("\n") + more;
+}

package/src/context/systemPrompt.ts

@@ -0,0 +1,167 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { gitStatus, dirSnapshot } from "./projectInfo.ts";
+import { loadMemoryContext } from "../memory/auto.ts";
+
+// The system prompt is assembled from modular sections: static segments first,
+// then a dynamic environment block. Static sections (identity, tone, tool
+// policy) come first so they stay byte-stable across turns and cache well; the
+// dynamic environment block (cwd, git status, snapshot) comes last. `buildSystemPrompt`
+// stays a pure synchronous string builder — the only I/O is reading project files and
+// the soft git/dir probes in projectInfo.ts.
+
+const IDENTITY = `You are Privateer, a provider-agnostic terminal coding agent. You help with software \
+engineering tasks directly from the user's terminal, with the same working style as a senior \
+engineer pairing over a shared shell.`;
+
+const TONE = `Tone and style:
+- Be concise and direct. Minimize preamble and postamble — no "Sure!", no "Here is what I'll do" \
+unless asked. Let your actions and their results speak.
+- Prefer doing over explaining. When a task is clear, use your tools to accomplish it rather than \
+describing how the user could.
+- Keep prose short. Answer the question that was asked; don't volunteer tangents.
+- When you finish a task, stop. Don't summarize work the user just watched you do.`;
+
+const SECURITY = `Security:
+- Assist with defensive security, debugging, and legitimate engineering. Refuse to help create or \
+improve malware, exploits aimed at systems the user doesn't own, or other clearly malicious uses.
+- Never expose or exfiltrate secrets. Don't print API keys or credentials you encounter.`;
+
+const TOOL_POLICY = `Using your tools:
+- Explore before you change: use 'glob' to find files by name and 'grep' to search contents. \
+Read a file with 'read' before editing it.
+- Prefer 'edit' (exact-string replace) over 'write' for changes to existing files; reserve 'write' \
+for new files or full rewrites.
+- Batch independent reads/searches rather than going one at a time.
+- For multi-step work, call 'todo' to lay out and track the plan; keep exactly one item \
+in_progress and mark items completed as you finish them. This keeps the user oriented.
+- For broad, open-ended search or investigation, delegate to a 'task' sub-agent so the details \
+stay out of the main conversation; it returns just a summary.
+- Use 'bash' for builds, tests, git, and other CLI work. Avoid long-running or interactive commands.
+- Each tool call is a separate model round-trip, so chain related shell steps into one \
+'bash' call with '&&' rather than firing them one at a time (e.g. \
+'git add -A && git commit -m "…" && git push', not three calls). Keep commands you need \
+to inspect the output of (a failing test, a diff you'll act on) separate.
+- Scope a commit to how the user asked. An unqualified "commit" / "commit and push" means the \
+whole working tree (stage all changes) — not just files you touched this turn. A scoped request \
+("commit the README", "commit the screenshot") means stage only what that names. When an \
+unqualified commit would sweep in a lot of unrelated changes, say what you're including in one line \
+before doing it.
+- When you create a git commit, end the message with a blank line followed by this trailer so the \
+work is attributed to Privateer as a co-author:
+  Co-Authored-By: Privateer <291203302+privateer-first-mate@users.noreply.github.com>
+- Use 'web_fetch' to read a known URL when the user provides one or you need current docs.
+- Mutating actions (write/edit/bash) may require user approval; that's expected — proceed and let \
+the gate handle it.`;
+
+const MEMORY = `Memory:
+- You have a persistent memory across sessions. When an index of saved memories is \
+present below, treat each line as something you already know; read the named .md file \
+with 'read' when an entry looks relevant to the current task.
+- Use the 'memory' tool to record durable facts worth remembering long-term: stable user \
+preferences, project conventions, and feedback on how to work — not transient details \
+about the current task. Prefer updating an existing memory (reuse its name) over \
+creating a near-duplicate. Default to project scope; use global only for facts that hold \
+across every project.`;
+
+const RECAP = `Recaps:
+- End every response with a single final line that begins with "recap: " — one plain-language \
+sentence summarizing what the user has accomplished so far this session (their goals and the \
+changes they've driven), not a restatement of what you just did. Keep it to one line; if nothing \
+has happened yet, recap the user's stated goal.`;
+
+const PLAN_MODE = `Plan mode is active. Your write, edit, and bash tools are disabled — do not attempt to \
+modify files or run commands. Investigate with read, glob, and grep, then present a clear, \
+step-by-step implementation plan as your final message. Do not start implementing; wait for the \
+user to approve the plan first.`;
+
+export interface SystemPromptOptions {
+  cwd: string;
+  model: string;
+  // Optional output-style body: replaces the default tone/persona section.
+  outputStyleBody?: string;
+  // When true, append the plan-mode mandate (read-only, produce a plan).
+  planMode?: boolean;
+}
+
+// System prompt for a `task` sub-agent: same environment grounding, but a read-only,
+// report-back mandate. It shares the parent's identity/security stance but swaps the
+// tool policy for the restricted subset.
+export function buildSubAgentPrompt(opts: SystemPromptOptions & { description: string }): string {
+  return [
+    IDENTITY,
+    SECURITY,
+    `You are running as a read-only sub-agent for the task: "${opts.description}".`,
+    `You have read, glob, and grep only — you cannot modify files or run commands. Investigate ` +
+      `thoroughly and efficiently, then return a concise, self-contained summary of your findings ` +
+      `(reference concrete file paths and line numbers). Do not ask the user questions; you run ` +
+      `autonomously and your final message is your whole report.`,
+    `Environment:\n- cwd: ${opts.cwd}\n- platform: ${process.platform}`,
+  ].join("\n\n");
+}
+
+// System prompt for a user-defined sub-agent: the agent's own instructions plus the
+// shared identity/security stance and an autonomous report-back mandate.
+export function buildAgentPrompt(
+  opts: SystemPromptOptions & { description: string; instructions: string },
+): string {
+  return [
+    IDENTITY,
+    opts.instructions,
+    SECURITY,
+    `You are running as a sub-agent for the task: "${opts.description}". Work autonomously and ` +
+      `return a concise, self-contained final report (reference concrete file paths). Do not ask ` +
+      `the user questions — your final message is your whole report.`,
+    `Environment:\n- cwd: ${opts.cwd}\n- platform: ${process.platform}`,
+  ].join("\n\n");
+}
+
+export function buildSystemPrompt(opts: SystemPromptOptions): string {
+  // An active output style replaces the default tone/persona section.
+  const persona = opts.outputStyleBody?.trim() || TONE;
+  const parts: string[] = [IDENTITY, persona, SECURITY, TOOL_POLICY, MEMORY, RECAP];
+  if (opts.planMode) parts.push(PLAN_MODE);
+
+  // --- Dynamic environment section ---
+  const env: string[] = [
+    `Environment:`,
+    `- cwd: ${opts.cwd}`,
+    `- model: ${opts.model}`,
+    `- launched in: ${process.cwd()}`,
+    `- platform: ${process.platform}`,
+    `- date: ${new Date().toISOString().slice(0, 10)}`,
+    `\nTreat cwd as the project scope: interpret relative paths from it and keep your ` +
+      `exploration, searches, and edits inside it. The file tools are confined to cwd — a path ` +
+      `that resolves outside it (an absolute path elsewhere, a sibling directory, or a '../' ` +
+      `escape) is blocked unless the user has explicitly asked you to work there, in which case ` +
+      `they'll be prompted to approve it. Don't reach outside cwd on your own; if a task seems to ` +
+      `need a file outside it, ask the user rather than guessing.`,
+  ];
+
+  const git = gitStatus(opts.cwd);
+  if (git) {
+    env.push(`- git branch: ${git.branch}`);
+    env.push(`\nGit status (porcelain):\n${git.status}`);
+    if (git.recent) env.push(`\nRecent commits:\n${git.recent}`);
+  }
+
+  const snapshot = dirSnapshot(opts.cwd);
+  if (snapshot) env.push(`\nProject files (partial):\n${snapshot}`);
+
+  parts.push(env.join("\n"));
+
+  // Project context file, our CLAUDE.md analog. Loaded last so user-authored
+  // standing instructions carry the most weight.
+  const ctxFile = join(opts.cwd, "PRIVATEER.md");
+  if (existsSync(ctxFile)) {
+    parts.push(`Project context from PRIVATEER.md:\n${readFileSync(ctxFile, "utf8").trim()}`);
+  }
+
+  // Recalled memory index, our auto-memory analog. Read a listed .md for full detail.
+  const memory = loadMemoryContext(opts.cwd);
+  if (memory) {
+    parts.push(`Persistent memory (index — read a file for detail):\n${memory}`);
+  }
+
+  return parts.join("\n\n");
+}