privateer-agent 0.1.0

package/src/auth/privateer.ts

@@ -0,0 +1,393 @@
+/**
+ * Privateer account login for the agent CLI.
+ *
+ * Instead of a provider API key, the terminal logs into the user's Privateer
+ * account and runs inference billed to that account. Auth uses the device
+ * authorization grant (RFC 8628): the CLI shows a short user_code, the user
+ * approves it inside the already-logged-in Privateer mobile/web app, and the
+ * server mints a CLI-scoped session here. This works identically for email and
+ * wallet accounts — the wallet/password signing all happens in the app, never
+ * in the terminal.
+ *
+ * Framework-agnostic on purpose: the Ink UI drives `runDeviceLogin` and the
+ * provider factory uses `authedFetch`; nothing here imports React.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync, rmSync } from "node:fs";
+import { hostname, userInfo } from "node:os";
+import { globalDir, credentialsPath } from "../config/paths.ts";
+import { isAccountCapCode } from "../engine/errors.ts";
+
+// Default Privateer API host. NOTE: this is still the legacy "helix" Render
+// hostname the mobile/web client also points at (client/config/environment.ts);
+// centralize/rename later. Override with PRIVATEER_SERVER_URL for dev/self-host.
+export const DEFAULT_SERVER_URL = "https://helix-server-m1ac.onrender.com";
+
+export interface PrivateerUser {
+  id: string;
+  email: string | null;
+  solanaPublicKey: string | null;
+  kekSource: string | null;
+}
+
+export interface Credentials {
+  accessToken: string;
+  refreshToken: string;
+  user: PrivateerUser;
+  serverBaseUrl: string;
+}
+
+// A server URL is safe only if it's https, OR http to a loopback host (dev).
+// Anything else (plain http to a remote host) would send the account bearer
+// token in cleartext and is rejected — a poisoned PRIVATEER_SERVER_URL must not
+// be able to redirect/downgrade the connection and exfiltrate the token.
+export function isSafeServerUrl(raw: string): boolean {
+  let u: URL;
+  try {
+    u = new URL(raw);
+  } catch {
+    return false;
+  }
+  if (u.protocol === "https:") return true;
+  if (u.protocol === "http:" && (u.hostname === "localhost" || u.hostname === "127.0.0.1" || u.hostname === "::1")) {
+    return true;
+  }
+  return false;
+}
+
+// Resolved base URL: env override > stored (from a prior login) > default.
+// Both the override and the stored value are validated — never fall through to
+// an insecure host that could capture the session token.
+export function serverBaseUrl(): string {
+  const env = process.env.PRIVATEER_SERVER_URL?.replace(/\/$/, "");
+  if (env) {
+    if (!isSafeServerUrl(env)) {
+      throw new Error(
+        `Refusing PRIVATEER_SERVER_URL=${env}: must be https:// (http allowed only for localhost). ` +
+          `This protects your account token from being sent over an insecure or attacker-controlled connection.`,
+      );
+    }
+    return env;
+  }
+  const base = (loadCredentials()?.serverBaseUrl || DEFAULT_SERVER_URL).replace(/\/$/, "");
+  if (!isSafeServerUrl(base)) {
+    throw new Error(`Stored Privateer server URL is not https (${base}). Run /logout then /login again.`);
+  }
+  return base;
+}
+
+// A friendly default label so a linked session is recognizable in the app's
+// "Linked terminals" list, e.g. "patrick@MacBook-Pro".
+export function defaultDeviceLabel(): string {
+  try {
+    return `${userInfo().username}@${hostname()}`;
+  } catch {
+    return "terminal";
+  }
+}
+
+// ── Credential storage (0600, like saveGlobalConfig) ─────────────────────────
+
+let _cache: Credentials | null | undefined;
+
+// Per-terminal child session (see spawnChildSession). Held in memory ONLY — it
+// is never written to the shared credentials file, so each running terminal
+// rotates its own refresh token in isolation.
+interface ChildSession { accessToken: string; refreshToken: string; }
+let _child: ChildSession | null = null;
+let _spawnInFlight: Promise<ChildSession> | null = null;
+let _refreshInFlight: Promise<ChildSession> | null = null;
+
+export function loadCredentials(): Credentials | null {
+  if (_cache !== undefined) return _cache;
+  const path = credentialsPath();
+  if (!existsSync(path)) return (_cache = null);
+  try {
+    _cache = JSON.parse(readFileSync(path, "utf8")) as Credentials;
+  } catch {
+    _cache = null;
+  }
+  return _cache;
+}
+
+export function saveCredentials(creds: Credentials): void {
+  const dir = globalDir();
+  mkdirSync(dir, { recursive: true });
+  tryChmod(dir, 0o700);
+  const path = credentialsPath();
+  writeFileSync(path, JSON.stringify(creds, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
+  tryChmod(path, 0o600);
+  _cache = creds;
+}
+
+export function clearCredentials(): void {
+  try {
+    rmSync(credentialsPath(), { force: true });
+  } catch {
+    /* nothing to remove */
+  }
+  _cache = null;
+  _child = null;
+}
+
+export function hasCredentials(): boolean {
+  return loadCredentials() !== null;
+}
+
+export function currentUser(): PrivateerUser | null {
+  return loadCredentials()?.user ?? null;
+}
+
+function tryChmod(path: string, mode: number): void {
+  try {
+    chmodSync(path, mode);
+  } catch {
+    /* non-POSIX filesystem — best effort */
+  }
+}
+
+// ── Device authorization flow ────────────────────────────────────────────────
+
+export interface DeviceCode {
+  device_code: string;
+  user_code: string;
+  verification_uri?: string;
+  verification_uri_complete?: string;
+  expires_in: number;
+  interval: number;
+}
+
+async function postJson(base: string, path: string, body: unknown, init: RequestInit = {}): Promise<Response> {
+  // Spread init FIRST so method/headers/body below stay authoritative — otherwise
+  // a trailing `...init` clobbers the merged headers (dropping Content-Type when a
+  // caller passes its own headers, e.g. Authorization on /auth/session/spawn).
+  return fetch(`${base}${path}`, {
+    ...init,
+    method: "POST",
+    headers: { "Content-Type": "application/json", ...((init.headers as Record<string, string>) || {}) },
+    body: JSON.stringify(body),
+  });
+}
+
+// Step 1: ask the server for a device + user code the human will approve in-app.
+export async function requestDeviceCode(deviceLabel = defaultDeviceLabel()): Promise<DeviceCode> {
+  const base = serverBaseUrl();
+  const res = await postJson(base, "/auth/device/code", { deviceLabel });
+  if (!res.ok) {
+    throw new Error(`Couldn't start login (${res.status}). Check your connection or PRIVATEER_SERVER_URL.`);
+  }
+  return (await res.json()) as DeviceCode;
+}
+
+export type PollState = "pending" | "slow_down";
+
+/**
+ * Step 2: poll until the user approves in the app. Resolves with the saved
+ * credentials, or rejects on denial/expiry. `onPoll` lets the UI show progress;
+ * `signal` cancels the wait.
+ */
+export async function pollForToken(
+  code: DeviceCode,
+  opts: { onPoll?: (state: PollState) => void; signal?: AbortSignal } = {},
+): Promise<Credentials> {
+  const base = serverBaseUrl();
+  let interval = Math.max(1, code.interval || 5) * 1000;
+  const deadline = Date.now() + (code.expires_in || 600) * 1000;
+
+  while (Date.now() < deadline) {
+    if (opts.signal?.aborted) throw new Error("Login cancelled.");
+    await sleep(interval, opts.signal);
+
+    const res = await postJson(base, "/auth/device/token", { device_code: code.device_code });
+
+    if (res.ok) {
+      const data = (await res.json()) as Omit<Credentials, "serverBaseUrl">;
+      const creds: Credentials = { ...data, serverBaseUrl: base };
+      saveCredentials(creds);
+      return creds;
+    }
+
+    let err = "";
+    try {
+      err = ((await res.json()) as { error?: string }).error || "";
+    } catch {
+      /* non-JSON */
+    }
+
+    if (err === "authorization_pending") {
+      opts.onPoll?.("pending");
+    } else if (err === "slow_down") {
+      interval += 2000; // back off per RFC 8628
+      opts.onPoll?.("slow_down");
+    } else if (err === "access_denied") {
+      throw new Error("Login was denied in the app.");
+    } else if (err === "expired_token") {
+      throw new Error("This login code expired. Run /login again.");
+    } else {
+      throw new Error(`Login failed (${res.status}${err ? `: ${err}` : ""}).`);
+    }
+  }
+  throw new Error("This login code expired. Run /login again.");
+}
+
+/**
+ * High-level orchestration: request a code, surface it via `onCode`, then wait
+ * for approval. Returns the logged-in user.
+ */
+export async function runDeviceLogin(opts: {
+  deviceLabel?: string;
+  onCode: (code: DeviceCode) => void;
+  onPoll?: (state: PollState) => void;
+  signal?: AbortSignal;
+}): Promise<PrivateerUser> {
+  const code = await requestDeviceCode(opts.deviceLabel);
+  opts.onCode(code);
+  const creds = await pollForToken(code, { onPoll: opts.onPoll, signal: opts.signal });
+  return creds.user;
+}
+
+// ── Session token use + refresh ──────────────────────────────────────────────
+
+/**
+ * Spawn THIS terminal's own session from the machine login (parent) refresh
+ * token. The parent token is only VALIDATED here — never rotated — so any number
+ * of terminals can spawn concurrently without colliding. The resulting child
+ * pair lives in memory only; the terminal then rotates its own refresh token in
+ * isolation, so two terminals never fight over one rotating token (which would
+ * trip the server's reuse-detection and revoke every session).
+ */
+async function spawnChildSession(): Promise<ChildSession> {
+  const parent = loadCredentials();
+  if (!parent) throw new Error("Not logged in to Privateer. Run /login.");
+  // Present the parent access token as a possession proof alongside the refresh
+  // token. The server allows this access token to be expired (the valid refresh
+  // token is the liveness proof) — so the parent file stays read-only and never
+  // needs rotating — but a refresh token WITHOUT a real signed access JWT can't
+  // spawn. Both are validated server-side against the same account.
+  const res = await postJson(serverBaseUrl(), "/auth/session/spawn", {
+    refreshToken: parent.refreshToken,
+    deviceLabel: defaultDeviceLabel(),
+  }, {
+    headers: { Authorization: `Bearer ${parent.accessToken}` },
+  });
+  if (!res.ok) {
+    // Parent refresh token invalid/expired → the machine login is gone.
+    if (res.status === 401) clearCredentials();
+    throw new Error("Your Privateer session expired. Run /login to sign in again.");
+  }
+  const { accessToken, refreshToken } = (await res.json()) as ChildSession;
+  _child = { accessToken, refreshToken };
+  return _child;
+}
+
+// Ensure a child session exists, de-duping concurrent spawns within this process.
+function ensureChildSession(): Promise<ChildSession> {
+  if (_child) return Promise.resolve(_child);
+  if (!_spawnInFlight) {
+    _spawnInFlight = spawnChildSession().finally(() => { _spawnInFlight = null; });
+  }
+  return _spawnInFlight;
+}
+
+// Rotate this terminal's own refresh token; if it's gone, spawn a fresh child.
+// Single-flighted so concurrent 401s don't double-rotate (which would reuse-trip
+// the child's own token).
+function refreshChildSession(): Promise<ChildSession> {
+  if (_refreshInFlight) return _refreshInFlight;
+  _refreshInFlight = (async (): Promise<ChildSession> => {
+    if (_child) {
+      const res = await postJson(serverBaseUrl(), "/auth/refresh", { refreshToken: _child.refreshToken });
+      if (res.ok) {
+        const { accessToken, refreshToken } = (await res.json()) as ChildSession;
+        _child = { accessToken, refreshToken };
+        return _child;
+      }
+    }
+    _child = null; // child rotation failed (expired/reused) — get a new one
+    return spawnChildSession();
+  })().finally(() => { _refreshInFlight = null; });
+  return _refreshInFlight;
+}
+
+/**
+ * fetch wrapper matching the global `fetch` signature, for use as the AI SDK
+ * provider's `fetch`. Authenticates with THIS terminal's child session and, on a
+ * 401, refreshes once and retries. The body is buffered so the retry can resend.
+ */
+export async function authedFetch(input: Parameters<typeof fetch>[0], init: RequestInit = {}): Promise<Response> {
+  const bodyBuf = init.body; // AI SDK passes a string body; safe to resend.
+  // Use a Headers object and `.set` (case-insensitive) so OUR bearer replaces any
+  // Authorization the caller already set. The AI SDK lowercases its headers and
+  // sends `authorization: Bearer <placeholder apiKey>`; a plain spread that adds an
+  // `Authorization` key would leave BOTH, which undici combines into
+  // "Bearer placeholder, Bearer <real>" → the server rejects it as Invalid token.
+  const withAuth = (token: string): RequestInit => {
+    const headers = new Headers(init.headers);
+    headers.set("Authorization", `Bearer ${token}`);
+    return { ...init, headers };
+  };
+
+  let child = await ensureChildSession();
+  let res = await fetch(input, withAuth(child.accessToken));
+  if (res.status === 401) {
+    child = await refreshChildSession();
+    res = await fetch(input, { ...withAuth(child.accessToken), body: bodyBuf });
+  }
+  return await defuseRetryableCap(res);
+}
+
+// A hard account cap (daily/monthly limit reached, balance exhausted) comes back
+// as a 429, which the AI SDK treats as retryable — so it burns its whole retry
+// budget waiting on a limit that won't clear, then surfaces a generic "Too Many
+// Requests". Detect the cap by the backend's machine `code` and rewrite the status
+// to 402 (Payment Required), which the SDK does NOT retry, while preserving the
+// body and headers so describeError still shows the backend's own message. Only a
+// 429 is inspected, and only its (small, non-streaming) error body is buffered;
+// transient 429s without a cap code pass through untouched and stay retryable.
+async function defuseRetryableCap(res: Response): Promise<Response> {
+  if (res.status !== 429) return res;
+  const body = await res.text();
+  let code: unknown;
+  try {
+    const parsed = JSON.parse(body) as { code?: unknown; error?: { code?: unknown } };
+    code = parsed.code ?? parsed.error?.code;
+  } catch {
+    /* non-JSON body — can't be a structured cap, leave it retryable */
+  }
+  const status = isAccountCapCode(typeof code === "string" ? code : undefined) ? 402 : 429;
+  return new Response(body, { status, statusText: res.statusText, headers: res.headers });
+}
+
+/** Authenticated JSON request against the Privateer API (relative path). */
+export async function apiRequest(path: string, init: RequestInit = {}): Promise<Response> {
+  const base = serverBaseUrl();
+  return authedFetch(`${base}${path}`, init);
+}
+
+// ── Logout ───────────────────────────────────────────────────────────────────
+
+/**
+ * Log out this terminal: revoke its session server-side (best effort) and wipe
+ * local credentials. Other devices/sessions are untouched.
+ */
+export async function logout(): Promise<void> {
+  try {
+    await apiRequest("/auth/logout", { method: "POST" });
+  } catch {
+    /* best effort — clear locally regardless */
+  }
+  clearCredentials();
+}
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const t = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(t);
+        reject(new Error("Login cancelled."));
+      },
+      { once: true },
+    );
+  });
+}

package/src/commands/custom.ts

@@ -0,0 +1,75 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { globalPaths, projectPaths } from "../config/paths.ts";
+import { walkFiles } from "../tools/walk.ts";
+
+// A user-authored slash command loaded from a markdown file under
+// .privateer/commands/. The body is a prompt template; frontmatter is optional.
+export interface CustomCommand {
+  name: string; // file path minus .md, separators → ":" (e.g. "git/pr.md" → "git:pr")
+  description: string;
+  argumentHint?: string;
+  allowedTools?: string[];
+  model?: string;
+  body: string;
+  scope: "project" | "user";
+}
+
+// Minimal YAML-ish frontmatter: a leading `---` block of `key: value` lines.
+export function parseFrontmatter(raw: string): { meta: Record<string, string>; body: string } {
+  const lines = raw.split("\n");
+  if (lines[0]?.trim() !== "---") return { meta: {}, body: raw };
+  const meta: Record<string, string> = {};
+  let i = 1;
+  for (; i < lines.length; i++) {
+    if (lines[i].trim() === "---") {
+      i++;
+      break;
+    }
+    const m = lines[i].match(/^([A-Za-z0-9_-]+)\s*:\s*(.*)$/);
+    if (m) meta[m[1].toLowerCase()] = m[2].trim();
+  }
+  return { meta, body: lines.slice(i).join("\n").replace(/^\n+/, "") };
+}
+
+function loadFromDir(dir: string, scope: "project" | "user"): CustomCommand[] {
+  if (!existsSync(dir)) return [];
+  const out: CustomCommand[] = [];
+  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 ?? `custom ${scope} command`,
+      argumentHint: meta["argument-hint"],
+      allowedTools: meta["allowed-tools"]
+        ?.split(",")
+        .map((s) => s.trim())
+        .filter(Boolean),
+      model: meta.model,
+      body: body.trim(),
+      scope,
+    });
+  }
+  return out;
+}
+
+// Load custom commands from user (~/.privateer) then project (./.privateer);
+// a project command overrides a user command of the same name.
+export function loadCustomCommands(cwd: string = process.cwd()): CustomCommand[] {
+  const byName = new Map<string, CustomCommand>();
+  for (const c of loadFromDir(globalPaths().commands, "user")) byName.set(c.name, c);
+  for (const c of loadFromDir(projectPaths(cwd).commands, "project")) byName.set(c.name, c);
+  return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+// Expand a command body against its arguments: $1..$9 are positional words,
+// $ARGUMENTS and $@ are the full argument string.
+export function expandCommand(cmd: CustomCommand, argString: string): string {
+  const args = argString.trim();
+  const parts = args.length ? args.split(/\s+/) : [];
+  return cmd.body
+    .replace(/\$([1-9])/g, (_, d: string) => parts[Number(d) - 1] ?? "")
+    .replace(/\$ARGUMENTS\b/g, args)
+    .replace(/\$@/g, args);
+}