privateer-agent 0.1.0

package/src/components/promptModel.ts

@@ -0,0 +1,73 @@
+// Pure logic behind the prompt input: mode detection and autocomplete matching.
+// Kept free of Ink so it can be unit-tested directly.
+
+export type InputMode = "bash" | "memory" | "command" | "prompt";
+
+// A leading "/" only starts a slash command when the first word looks like a
+// command name — no path separators or dots. This lets absolute file paths like
+// "/Users/me/shot.png" be typed as a normal prompt (and attached as an image)
+// instead of being mistaken for a command. A bare "/" still opens the menu.
+export function isSlashCommand(value: string): boolean {
+  if (value[0] !== "/") return false;
+  const firstWord = value.slice(1).split(/\s/, 1)[0];
+  // Command names are strictly alphanumeric (with - and _); anything else in the
+  // first word — a "/", ".", "\", etc. — means it's a path, not a command.
+  return firstWord.length === 0 || /^[A-Za-z0-9_-]+$/.test(firstWord);
+}
+
+// What the leading character of the buffer means. `!` shells out, `#` appends to
+// project memory, `/` runs a slash command, anything else is a model prompt.
+export function detectMode(value: string): InputMode {
+  if (value[0] === "!") return "bash";
+  if (value[0] === "#") return "memory";
+  if (isSlashCommand(value)) return "command";
+  return "prompt";
+}
+
+// The command-name fragment being typed, when the cursor sits within the first
+// word of a leading "/command". Null once the user moves on to typing arguments.
+export function slashQuery(value: string, cursor: number): string | null {
+  if (!isSlashCommand(value)) return null;
+  const firstSpace = value.indexOf(" ");
+  const nameEnd = firstSpace === -1 ? value.length : firstSpace;
+  if (cursor > nameEnd) return null;
+  return value.slice(1, nameEnd);
+}
+
+// The @-mention token under the cursor: the '@' index plus the text typed after
+// it. Requires the '@' to start a word (so emails like a@b don't trigger it).
+export function mentionAt(value: string, cursor: number): { start: number; query: string } | null {
+  let i = cursor;
+  while (i > 0 && !/\s/.test(value[i - 1])) i--;
+  if (value[i] !== "@") return null;
+  return { start: i, query: value.slice(i + 1, cursor) };
+}
+
+export interface CommandItem {
+  name: string;
+  summary: string;
+}
+
+export function filterCommands(all: CommandItem[], query: string): CommandItem[] {
+  const q = query.toLowerCase();
+  return all.filter((c) => c.name.toLowerCase().startsWith(q));
+}
+
+// Substring file match, ranked: basename hits beat path hits, earlier and shorter
+// paths win. Keeps the menu small and relevant on large trees.
+export function filterFiles(all: string[], query: string, limit: number): string[] {
+  const q = query.toLowerCase();
+  if (!q) return all.slice(0, limit);
+  const scored: { f: string; score: number }[] = [];
+  for (const f of all) {
+    const lower = f.toLowerCase();
+    const idx = lower.indexOf(q);
+    if (idx === -1) continue;
+    const base = lower.slice(lower.lastIndexOf("/") + 1);
+    const baseIdx = base.indexOf(q);
+    const score = (baseIdx === -1 ? 1000 : baseIdx) + idx * 0.01 + f.length * 0.001;
+    scored.push({ f, score });
+  }
+  scored.sort((a, b) => a.score - b.score);
+  return scored.slice(0, limit).map((s) => s.f);
+}

package/src/components/spinnerVerbs.ts

@@ -0,0 +1,46 @@
+// A set of gerund "thinking" verbs shown beside the spinner while a turn runs.
+// One is chosen at random per turn.
+const VERBS = [
+  "Cogitating",
+  "Pondering",
+  "Brewing",
+  "Conjuring",
+  "Forging",
+  "Wrangling",
+  "Synthesizing",
+  "Percolating",
+  "Ruminating",
+  "Noodling",
+  "Computing",
+  "Crafting",
+  "Composing",
+  "Deliberating",
+  "Tinkering",
+  "Hatching",
+  "Incubating",
+  "Marinating",
+  "Musing",
+  "Orchestrating",
+  "Puzzling",
+  "Scheming",
+  "Simmering",
+  "Spelunking",
+  "Stewing",
+  "Summoning",
+  "Unfurling",
+  "Whirring",
+  "Working",
+  "Wibbling",
+  "Manifesting",
+  "Channeling",
+  "Concocting",
+  "Crunching",
+  "Divining",
+  "Finagling",
+  "Mulling",
+  "Plotting",
+  "Reticulating",
+  "Transmuting",
+];
+
+export const randomVerb = (): string => VERBS[Math.floor(Math.random() * VERBS.length)];

package/src/components/theme.ts

@@ -0,0 +1,55 @@
+import type { PermissionMode } from "../config/schema.ts";
+import type { ZdrPosture } from "../providers/models.ts";
+
+// Single source of truth for TUI color. Privateer's navy/white identity drives the
+// accent: it marks bullets, the prompt prefix, headings, and the active permission
+// mode. Text is the terminal default (white on dark); metadata is dimmed gray.
+//
+// Note on navy: a true navy (#1e3a5f) is too dark to read on dark terminals, so the
+// accent is a brighter navy/indigo. It's one knob — tune it here and the whole UI
+// follows.
+export const theme = {
+  accent: "#5c7cfa", // Privateer navy/indigo — the single accent hue
+  accentDim: "#3b5b8c",
+  text: undefined as string | undefined, // terminal default
+  dim: "gray",
+  success: "green",
+  error: "red",
+  warning: "yellow",
+  diffAdded: "green",
+  diffRemoved: "red",
+} as const;
+
+// Permission-mode accent colors (moved here from StatusBar so color lives in one place).
+export const MODE_COLOR: Record<PermissionMode, string> = {
+  default: theme.warning,
+  acceptEdits: theme.success,
+  bypass: theme.error,
+  plan: theme.accent,
+};
+
+// OpenRouter ZDR posture colors — green enforced, yellow available, red retained.
+// Shared by the status-bar shield and the per-model badges in the picker.
+export const POSTURE_COLOR: Record<ZdrPosture, string> = {
+  green: theme.success,
+  yellow: theme.warning,
+  red: theme.error,
+};
+
+// Capitalized tool display names: read → Read, web_fetch → WebFetch.
+const TOOL_DISPLAY: Record<string, string> = {
+  read: "Read",
+  write: "Write",
+  edit: "Edit",
+  glob: "Glob",
+  grep: "Grep",
+  bash: "Bash",
+  bash_output: "BashOutput",
+  kill_shell: "KillShell",
+  todo: "TodoWrite",
+  task: "Task",
+  web_fetch: "WebFetch",
+  web_search: "WebSearch",
+};
+
+export const toolDisplayName = (name: string): string => TOOL_DISPLAY[name] ?? name;

package/src/components/types.ts

@@ -0,0 +1,34 @@
+// One rendered line/block in the conversation transcript.
+export type ToolStatus = "running" | "done" | "error";
+
+export interface ToolEntry {
+  kind: "tool";
+  id: string;
+  name: string;
+  input: unknown;
+  status: ToolStatus;
+  output?: string;
+  error?: string;
+  // Set only on `task` calls: the sub-agent's short description, its type (undefined =
+  // the default read-only explorer), and run metrics filled in when it finishes. Drives
+  // the grouped "N agents finished" rendering.
+  agent?: { description: string; subagentType?: string; toolUses?: number; tokens?: number };
+}
+
+export type Entry =
+  | { kind: "user"; text: string }
+  | { kind: "assistant"; text: string }
+  | { kind: "thinking"; text: string }
+  | ToolEntry
+  // `hint` is an optional actionable line rendered dim beneath the notice
+  // (used by error notices to suggest a next step).
+  | { kind: "notice"; text: string; tone?: "info" | "error"; hint?: string };
+
+// A render-time row: either a single transcript entry, or a run of two-or-more
+// concurrent `task` sub-agents collapsed into one grouped block. Grouping happens at
+// render time (see groupRows) so the underlying transcript stays a flat entry list.
+export interface AgentGroupRow {
+  kind: "agent-group";
+  agents: ToolEntry[];
+}
+export type Row = Entry | AgentGroupRow;

package/src/components/useTeeShield.ts

@@ -0,0 +1,104 @@
+import { useEffect, useState } from "react";
+import type { Config } from "../config/schema.ts";
+import { parseModelSpec, privateerChannel } from "../providers/resolve.ts";
+import {
+  fetchAttestation,
+  fetchAttestationViaServer,
+  teePosture,
+  type Attestation,
+  type TeePosture,
+} from "../providers/attestation.ts";
+
+// What the status-bar shield should render for a TEE attestation. Distinct from
+// posture so a dim "needs a key / unknown" affordance never implies a verdict.
+export type TeeState =
+  | { kind: "hidden" } // not a TEE-backed model — no badge
+  | { kind: "no-key" } // NEAR AI (BYO key) selected but no API key to attest with
+  | { kind: "loading" } // fetching the attestation report
+  | { kind: "error" } // network / timeout / HTTP failure
+  | { kind: "ready"; posture: TeePosture; attestation: Attestation };
+
+// Attestations are per-model (each model has its own enclave + signing key), so we
+// cache the in-flight/resolved promise per (apiKey, baseURL, modelId) and reuse it
+// for the session. Concurrent consumers dedupe to one fetch; a rejection is evicted
+// so a later selection can retry rather than being stuck in error forever.
+const cache = new Map<string, Promise<Attestation>>();
+
+function loadAttestation(apiKey: string, baseURL: string | undefined, modelId: string): Promise<Attestation> {
+  const key = `${apiKey}::${baseURL ?? ""}::${modelId}`;
+  let pending = cache.get(key);
+  if (!pending) {
+    pending = fetchAttestation({ apiKey, baseURL }, modelId).catch((err) => {
+      cache.delete(key);
+      throw err;
+    });
+    cache.set(key, pending);
+  }
+  return pending;
+}
+
+// Account-billed `privateer:near/*` models attest through the Privateer server
+// proxy (the NEAR key stays server-side), so they cache by model id alone.
+const serverCache = new Map<string, Promise<Attestation>>();
+
+function loadServerAttestation(modelId: string): Promise<Attestation> {
+  let pending = serverCache.get(modelId);
+  if (!pending) {
+    pending = fetchAttestationViaServer(modelId).catch((err) => {
+      serverCache.delete(modelId);
+      throw err;
+    });
+    serverCache.set(modelId, pending);
+  }
+  return pending;
+}
+
+// Resolve the TEE shield state for the currently selected model. Two paths trigger
+// a fetch: BYO `nearai:*` models (direct gateway, needs a key) and account-billed
+// `privateer:near/*` models (server proxy, uses the logged-in session). Everything
+// else returns "hidden" before touching the network.
+export function useTeeShield(modelSpec: string, config: Config): TeeState {
+  let provider = "";
+  let modelId = "";
+  try {
+    ({ provider, modelId } = parseModelSpec(modelSpec));
+  } catch {
+    provider = "";
+    modelId = "";
+  }
+  const cfg = config.providers.nearai ?? {};
+  const isNearai = provider === "nearai";
+  const isPrivateerTee = provider === "privateer" && privateerChannel(modelId) === "tee";
+  const apiKey = isNearai ? cfg.apiKey : undefined;
+  const baseURL = cfg.baseURL;
+
+  const [state, setState] = useState<TeeState>({ kind: "hidden" });
+
+  useEffect(() => {
+    if (!isNearai && !isPrivateerTee) {
+      setState({ kind: "hidden" });
+      return;
+    }
+    if (isNearai && !apiKey) {
+      setState({ kind: "no-key" });
+      return;
+    }
+    let ignore = false;
+    setState({ kind: "loading" });
+    const pending = isPrivateerTee
+      ? loadServerAttestation(modelId)
+      : loadAttestation(apiKey!, baseURL, modelId);
+    pending
+      .then((attestation) => {
+        if (!ignore) setState({ kind: "ready", posture: teePosture(attestation), attestation });
+      })
+      .catch(() => {
+        if (!ignore) setState({ kind: "error" });
+      });
+    return () => {
+      ignore = true;
+    };
+  }, [isNearai, isPrivateerTee, apiKey, baseURL, modelId]);
+
+  return state;
+}

package/src/components/useTerminalWidth.ts

@@ -0,0 +1,24 @@
+import { useEffect, useState } from "react";
+import { useStdout } from "ink";
+
+// Current terminal column count, re-read on every resize.
+//
+// The dynamic region below <Static> is erased and redrawn on each render. Ink
+// counts the previous frame by its newlines, so any line that soft-wraps — or
+// that the terminal reflows when dragged narrower — desyncs the erase and leaves
+// stale copies in the scrollback (the classic stack of duplicated status bars).
+// Subscribing to resize lets those lines re-truncate to the new width and stay a
+// single row, which keeps Ink's erase count correct.
+export function useTerminalWidth(): number {
+  const { stdout } = useStdout();
+  const [cols, setCols] = useState(stdout?.columns ?? 80);
+  useEffect(() => {
+    if (!stdout) return;
+    const onResize = () => setCols(stdout.columns ?? 80);
+    stdout.on("resize", onResize);
+    return () => {
+      stdout.off("resize", onResize);
+    };
+  }, [stdout]);
+  return cols;
+}

package/src/components/useZdrShield.ts

@@ -0,0 +1,126 @@
+import { useEffect, useState } from "react";
+import type { Config, ProviderName } from "../config/schema.ts";
+import { parseModelSpec, privateerChannel } from "../providers/resolve.ts";
+import { fetchZdrAccount, zdrPosture, type ZdrAccountData, type ZdrPosture } from "../providers/models.ts";
+
+// What the status-bar shield should render. Distinct from posture so we can show a
+// dim "needs a key / unknown" affordance without ever implying a colored verdict.
+export type ZdrState =
+  | { kind: "hidden" } // not a ZDR-backed model — no badge
+  | { kind: "no-key" } // OpenRouter selected but no API key to query with
+  | { kind: "loading" } // fetching the account snapshot
+  | { kind: "error" } // network / timeout / HTTP failure
+  | { kind: "ready"; posture: ZdrPosture };
+
+// The ZDR snapshot (Z, U, enforcement) is global per account, not per model, so we
+// fetch it once per (apiKey, baseURL) and reuse it for the whole session — switching
+// models re-evaluates synchronously. The cache holds the in-flight/resolved promise so
+// concurrent consumers dedupe to a single fetch pair; a rejection is evicted so a later
+// selection can retry rather than being stuck in error forever.
+const cache = new Map<string, Promise<ZdrAccountData>>();
+
+function loadAccount(apiKey: string, baseURL: string | undefined): Promise<ZdrAccountData> {
+  const key = `${apiKey}::${baseURL ?? ""}`;
+  let pending = cache.get(key);
+  if (!pending) {
+    pending = fetchZdrAccount({ apiKey, baseURL }).catch((err) => {
+      cache.delete(key);
+      throw err;
+    });
+    cache.set(key, pending);
+  }
+  return pending;
+}
+
+// Resolve the ZDR shield state for the currently selected model. Only OpenRouter
+// models trigger a fetch; everything else returns "hidden" before touching the network.
+export function useZdrShield(modelSpec: string, config: Config): ZdrState {
+  let provider = "";
+  let modelId = "";
+  try {
+    ({ provider, modelId } = parseModelSpec(modelSpec));
+  } catch {
+    provider = "";
+    modelId = "";
+  }
+  const cfg = config.providers.openrouter ?? {};
+  const isOpenRouter = provider === "openrouter";
+  // Account-billed Privateer models that aren't NEAR/TEE route through the server's
+  // ZDR-pinned OpenRouter proxy — zero retention is guaranteed server-side.
+  const isPrivateerZdr = provider === "privateer" && privateerChannel(modelId) === "zdr";
+  const apiKey = isOpenRouter ? cfg.apiKey : undefined;
+  const baseURL = cfg.baseURL;
+  const enforced = Boolean(cfg.enforceZdr);
+
+  const [state, setState] = useState<ZdrState>({ kind: "hidden" });
+
+  useEffect(() => {
+    if (isPrivateerZdr) {
+      // The proxy always pins ZDR endpoints, so the posture is green without a
+      // client-side account query (there's no OpenRouter key on this side).
+      setState({ kind: "ready", posture: "green" });
+      return;
+    }
+    if (!isOpenRouter) {
+      setState({ kind: "hidden" });
+      return;
+    }
+    if (!apiKey) {
+      setState({ kind: "no-key" });
+      return;
+    }
+    let ignore = false;
+    setState({ kind: "loading" });
+    loadAccount(apiKey, baseURL)
+      .then((acct) => {
+        if (!ignore) setState({ kind: "ready", posture: zdrPosture(modelId, acct, enforced) });
+      })
+      .catch(() => {
+        if (!ignore) setState({ kind: "error" });
+      });
+    return () => {
+      ignore = true;
+    };
+  }, [isOpenRouter, isPrivateerZdr, apiKey, baseURL, modelId, enforced]);
+
+  return state;
+}
+
+// The account snapshot itself, for callers that score many models at once (the
+// OpenRouter model picker renders a per-row badge). Same fetch + cache as the
+// shield, but it hands back the raw ZdrAccountData so the consumer can call
+// zdrPosture(id, account) for each model synchronously, without a fetch per row.
+export type ZdrAccountState =
+  | { kind: "idle" } // not OpenRouter, or no key — no badges
+  | { kind: "loading" }
+  | { kind: "error" }
+  | { kind: "ready"; account: ZdrAccountData };
+
+export function useZdrAccount(provider: ProviderName | string, config: Config): ZdrAccountState {
+  const cfg = config.providers.openrouter ?? {};
+  const apiKey = provider === "openrouter" ? cfg.apiKey : undefined;
+  const baseURL = cfg.baseURL;
+
+  const [state, setState] = useState<ZdrAccountState>({ kind: "idle" });
+
+  useEffect(() => {
+    if (provider !== "openrouter" || !apiKey) {
+      setState({ kind: "idle" });
+      return;
+    }
+    let ignore = false;
+    setState({ kind: "loading" });
+    loadAccount(apiKey, baseURL)
+      .then((account) => {
+        if (!ignore) setState({ kind: "ready", account });
+      })
+      .catch(() => {
+        if (!ignore) setState({ kind: "error" });
+      });
+    return () => {
+      ignore = true;
+    };
+  }, [provider, apiKey, baseURL]);
+
+  return state;
+}

package/src/config/load.ts

@@ -0,0 +1,115 @@
+import { readFileSync, existsSync, mkdirSync, writeFileSync, chmodSync } from "node:fs";
+import { Config, type Config as ConfigT, type ProviderName } from "./schema.ts";
+import { globalPaths, projectPaths, managedSettingsPath } from "./paths.ts";
+
+// Back-compat re-exports: existing callers import these from here.
+export { globalDir } from "./paths.ts";
+export function globalConfigPath(): string {
+  return globalPaths().config;
+}
+export function projectConfigPath(): string {
+  return projectPaths().config;
+}
+
+function readJsonIfExists(path: string): unknown {
+  if (!existsSync(path)) return undefined;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (err) {
+    throw new Error(`Failed to parse config at ${path}: ${(err as Error).message}`);
+  }
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+// Recursively merge raw config layers: objects merge per-key, everything else
+// (scalars, arrays) is replaced by the higher-precedence layer.
+function deepMerge(base: unknown, over: unknown): unknown {
+  if (over === undefined) return base;
+  if (!isPlainObject(base) || !isPlainObject(over)) return over;
+  const out: Record<string, unknown> = { ...base };
+  for (const [k, v] of Object.entries(over)) {
+    if (v === undefined) continue;
+    out[k] = k in out ? deepMerge(out[k], v) : v;
+  }
+  return out;
+}
+
+export interface ConfigLayer {
+  label: string;
+  path: string;
+  present: boolean;
+}
+
+// The precedence chain, ordered low → high. Each scope contributes its
+// config.json (credentials + prefs) then its settings file(s) on top; managed
+// enterprise settings, if present, win over everything.
+function layerSpecs(): { label: string; path: string }[] {
+  const g = globalPaths();
+  const p = projectPaths();
+  const specs = [
+    { label: "user config", path: g.config },
+    { label: "user settings", path: g.settings },
+    { label: "project config", path: p.config },
+    { label: "project settings", path: p.settings },
+    { label: "project settings (local)", path: p.settingsLocal },
+  ];
+  const managed = managedSettingsPath();
+  if (managed) specs.push({ label: "managed", path: managed });
+  return specs;
+}
+
+// Resolved layer presence, for `/doctor` and `/config`.
+export function configLayers(): ConfigLayer[] {
+  return layerSpecs().map(({ label, path }) => ({ label, path, present: existsSync(path) }));
+}
+
+// Environment fallbacks for provider credentials. Applied only when config omits them.
+function applyEnv(cfg: ConfigT): ConfigT {
+  const p = cfg.providers;
+  const set = (name: ProviderName, key: "apiKey" | "baseURL", val?: string) => {
+    if (!val) return;
+    p[name] = { ...(p[name] ?? {}), [key]: (p[name] as any)?.[key] ?? val };
+  };
+  set("openrouter", "apiKey", process.env.OPENROUTER_API_KEY);
+  set("anthropic", "apiKey", process.env.ANTHROPIC_API_KEY);
+  set("openai", "apiKey", process.env.OPENAI_API_KEY);
+  set("ollama", "baseURL", process.env.OLLAMA_BASE_URL);
+  set("nearai", "apiKey", process.env.NEAR_AI_API_KEY ?? process.env.NEARAI_API_KEY);
+  return cfg;
+}
+
+export function loadConfig(): ConfigT {
+  // Merge raw layers first (so per-layer files stay partial), then parse once so
+  // schema defaults are applied to the resolved object rather than each layer.
+  let raw: unknown = {};
+  for (const { path } of layerSpecs()) {
+    raw = deepMerge(raw, readJsonIfExists(path));
+  }
+  const cfg = Config.parse(raw ?? {});
+  return applyEnv(cfg);
+}
+
+// Persist the global config (used by /model, /provider, /permissions to remember
+// choices). The file holds provider API keys, so it is written owner-only (0600)
+// inside an owner-only directory (0700). `chmod` is best-effort: it's a no-op on
+// filesystems/platforms (e.g. Windows) that don't honour POSIX modes.
+export function saveGlobalConfig(cfg: ConfigT): void {
+  const g = globalPaths();
+  mkdirSync(g.dir, { recursive: true });
+  tryChmod(g.dir, 0o700);
+  // `mode` on writeFileSync only applies when creating the file, so chmod after
+  // to also tighten a pre-existing, looser config.
+  writeFileSync(g.config, JSON.stringify(cfg, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
+  tryChmod(g.config, 0o600);
+}
+
+function tryChmod(path: string, mode: number): void {
+  try {
+    chmodSync(path, mode);
+  } catch {
+    /* non-POSIX filesystem or insufficient perms — nothing we can do */
+  }
+}

package/src/config/paths.ts

@@ -0,0 +1,61 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+// Global config/data dir. Overridable via PRIVATEER_HOME (portability + tests).
+// Computed lazily so the env var can be set before first use.
+export function globalDir(): string {
+  return process.env.PRIVATEER_HOME ?? join(homedir(), ".privateer");
+}
+
+// Project-scoped config dir (./.privateer).
+export function projectDir(cwd: string = process.cwd()): string {
+  return join(cwd, ".privateer");
+}
+
+// Privateer-account session credentials (JWT access/refresh + user). Kept in a
+// SEPARATE file from config.json: these are session tokens, not BYO provider
+// keys, and have a different lifecycle (rotated on refresh, cleared on logout).
+export function credentialsPath(): string {
+  return join(globalDir(), "credentials.json");
+}
+
+// Optional enterprise-managed settings file (highest precedence). Opt-in via env
+// so it stays out of the way for individuals and tests.
+export function managedSettingsPath(): string | undefined {
+  return process.env.PRIVATEER_MANAGED_SETTINGS || undefined;
+}
+
+// The standard file/dir layout under a scope's .privateer directory. Later
+// milestones (commands, agents, mcp, output styles) resolve their roots here so
+// the convention lives in one place.
+export interface ScopePaths {
+  dir: string;
+  config: string; // config.json — credentials + prefs (existing single file)
+  settings: string; // settings.json — layered settings
+  settingsLocal: string; // settings.local.json — gitignored local overrides
+  commands: string; // commands/ — custom slash commands (M2)
+  agents: string; // agents/ — custom subagents (M4)
+  outputStyles: string; // output-styles/ — persona prompts (M2)
+  mcp: string; // mcp.json — MCP server declarations (M4)
+}
+
+function scopePaths(dir: string): ScopePaths {
+  return {
+    dir,
+    config: join(dir, "config.json"),
+    settings: join(dir, "settings.json"),
+    settingsLocal: join(dir, "settings.local.json"),
+    commands: join(dir, "commands"),
+    agents: join(dir, "agents"),
+    outputStyles: join(dir, "output-styles"),
+    mcp: join(dir, "mcp.json"),
+  };
+}
+
+export function globalPaths(): ScopePaths {
+  return scopePaths(globalDir());
+}
+
+export function projectPaths(cwd: string = process.cwd()): ScopePaths {
+  return scopePaths(projectDir(cwd));
+}