privateer-agent 0.1.0

package/src/engine/router.ts

@@ -0,0 +1,165 @@
+import type { LanguageModel, ModelMessage } from "ai";
+import type { Modality } from "../util/images.ts";
+
+export type { Modality };
+
+// The named routes the engine can switch between per turn. `default` is always
+// present (it's the session's configured model); the rest are optional specialized
+// targets resolved from the `router` config block.
+export type RouteName = "default" | "vision" | "document" | "audio" | "video" | "long" | "fast";
+
+// Routes that exist to satisfy a specific input modality, in the order we prefer them
+// when several could cover a turn's requirements.
+const MODALITY_ROUTES: { name: RouteName; modality: Modality }[] = [
+  { name: "vision", modality: "image" },
+  { name: "document", modality: "document" },
+  { name: "audio", modality: "audio" },
+  { name: "video", modality: "video" },
+];
+
+// A resolved, ready-to-stream model plus the per-model knobs that travel with it
+// (Anthropic caching/thinking depend on the model family, so they're per-route) and
+// the set of input modalities it accepts (so the router can satisfy a turn's needs).
+export interface Route {
+  spec: string; // "provider:model"
+  model: LanguageModel;
+  cacheControl: boolean;
+  thinkingBudget?: number;
+  label: string; // short display name for UI notices (the model id tail)
+  supports: Set<Modality>;
+}
+
+export interface RouteSet {
+  default: Route;
+  vision?: Route;
+  document?: Route;
+  audio?: Route;
+  video?: Route;
+  long?: Route;
+  fast?: Route;
+  longThreshold: number; // estimated tokens above which `long` applies
+  fastMaxChars: number; // prompt length at/below which `fast` applies
+}
+
+// What the current turn looks like, used to pick a route.
+export interface RouteSignals {
+  modalities: Set<Modality>; // input modalities anywhere in the conversation (sticky)
+  estTokens: number; // estimated tokens of the whole conversation
+  promptChars: number; // length of the new user prompt
+}
+
+export interface RouteSelection {
+  name: RouteName;
+  route: Route;
+  reason?: string; // short human reason, for the UI notice
+  missing?: Modality[]; // modalities the chosen route can't satisfy (warn)
+}
+
+function covers(route: Route | undefined, required: Set<Modality>): route is Route {
+  if (!route) return false;
+  for (const m of required) if (!route.supports.has(m)) return false;
+  return true;
+}
+
+function missingFrom(route: Route, required: Set<Modality>): Modality[] {
+  return [...required].filter((m) => !route.supports.has(m));
+}
+
+// Candidate routes to consider for an attachment-bearing turn, in preference order:
+// the dedicated modality routes first, then long/fast/default as fallbacks (they may
+// happen to be multimodal). Deduped by identity.
+function candidateRoutes(routes: RouteSet): Route[] {
+  const ordered = [
+    ...MODALITY_ROUTES.map((r) => routes[r.name]),
+    routes.long,
+    routes.fast,
+    routes.default,
+  ].filter((r): r is Route => Boolean(r));
+  return [...new Set(ordered)];
+}
+
+// Pick the model for this turn.
+//   • If the turn requires input modalities, choose the highest-preference route whose
+//     `supports` covers the whole union (capability is a hard requirement). If none
+//     fully covers, fall back to the route covering the most, flagging what's missing.
+//   • Otherwise apply the soft preferences: long (large context) > fast (short prompt)
+//     > default.
+export function selectRoute(routes: RouteSet, s: RouteSignals): RouteSelection {
+  if (s.modalities.size > 0) {
+    const candidates = candidateRoutes(routes);
+    const full = candidates.find((r) => covers(r, s.modalities));
+    if (full) {
+      const name = routeNameOf(routes, full);
+      return { name, route: full, reason: reasonFor(s.modalities) };
+    }
+    // No single route covers everything — pick the one that covers the most and warn.
+    let best = routes.default;
+    let bestMissing = missingFrom(best, s.modalities);
+    for (const r of candidates) {
+      const miss = missingFrom(r, s.modalities);
+      if (miss.length < bestMissing.length) {
+        best = r;
+        bestMissing = miss;
+      }
+    }
+    return {
+      name: routeNameOf(routes, best),
+      route: best,
+      reason: reasonFor(s.modalities),
+      missing: bestMissing,
+    };
+  }
+  if (routes.long && s.estTokens > routes.longThreshold) {
+    return { name: "long", route: routes.long, reason: "long context" };
+  }
+  if (routes.fast && s.promptChars <= routes.fastMaxChars) {
+    return { name: "fast", route: routes.fast, reason: "short prompt" };
+  }
+  return { name: "default", route: routes.default };
+}
+
+function reasonFor(modalities: Set<Modality>): string {
+  return `${[...modalities].join("+")} input`;
+}
+
+// Recover the route name for a resolved Route (for the UI/event). Falls back to
+// "default" if it isn't one of the named slots.
+function routeNameOf(routes: RouteSet, route: Route): RouteName {
+  const names: RouteName[] = ["vision", "document", "audio", "video", "long", "fast"];
+  for (const n of names) if (routes[n] === route) return n;
+  return "default";
+}
+
+const MEDIA_MODALITY: { test: RegExp; modality: Modality }[] = [
+  { test: /^image\//, modality: "image" },
+  { test: /^audio\//, modality: "audio" },
+  { test: /^video\//, modality: "video" },
+  { test: /^application\/pdf$/, modality: "document" },
+];
+
+function modalityOfMediaType(mediaType: string): Modality | null {
+  return MEDIA_MODALITY.find((m) => m.test.test(mediaType))?.modality ?? null;
+}
+
+// The input modalities present anywhere in the conversation. Keyed off the whole
+// history (not just the new message) so that once an attachment is in context,
+// follow-up turns stay on a model that can accept it rather than replaying it to one
+// that can't.
+export function requiredModalities(messages: ModelMessage[]): Set<Modality> {
+  const out = new Set<Modality>();
+  for (const m of messages) {
+    const content = m.content;
+    if (!Array.isArray(content)) continue;
+    for (const part of content) {
+      if (!part || typeof part !== "object" || !("type" in part)) continue;
+      const t = (part as { type: string }).type;
+      if (t === "image") out.add("image");
+      else if (t === "file") {
+        const mt = (part as { mediaType?: string }).mediaType;
+        const mod = mt ? modalityOfMediaType(mt) : null;
+        if (mod) out.add(mod);
+      }
+    }
+  }
+  return out;
+}

package/src/hooks/engine.ts

@@ -0,0 +1,155 @@
+import type { ToolSet } from "ai";
+import { exec } from "../tools/exec.ts";
+
+// A single hook: a shell command, optionally gated by a regex matched against the
+// tool name (tool events only). Loaded from settings under the `hooks` key.
+export interface HookDef {
+  matcher?: string;
+  command: string;
+}
+
+export type HookEvent = "PreToolUse" | "PostToolUse" | "UserPromptSubmit" | "Stop";
+export type HooksConfig = Partial<Record<HookEvent, HookDef[]>>;
+
+// Aggregated result of firing an event's hooks.
+export interface HookOutcome {
+  block?: boolean; // PreToolUse / UserPromptSubmit may veto
+  reason?: string;
+  additionalContext?: string; // UserPromptSubmit may inject extra context
+}
+
+const HOOK_TIMEOUT_MS = 30_000;
+const KNOWN_EVENTS: HookEvent[] = ["PreToolUse", "PostToolUse", "UserPromptSubmit", "Stop"];
+
+// Parse the loosely-typed `hooks` section of settings into a validated HooksConfig.
+export function loadHooks(raw: unknown): HooksConfig {
+  if (typeof raw !== "object" || raw === null) return {};
+  const out: HooksConfig = {};
+  for (const event of KNOWN_EVENTS) {
+    const entries = (raw as Record<string, unknown>)[event];
+    if (!Array.isArray(entries)) continue;
+    const defs: HookDef[] = [];
+    for (const e of entries) {
+      if (e && typeof e === "object" && typeof (e as any).command === "string") {
+        defs.push({ matcher: (e as any).matcher, command: (e as any).command });
+      }
+    }
+    if (defs.length) out[event] = defs;
+  }
+  return out;
+}
+
+function matches(def: HookDef, toolName?: string): boolean {
+  if (!def.matcher) return true;
+  if (toolName === undefined) return true;
+  try {
+    return new RegExp(def.matcher).test(toolName);
+  } catch {
+    return false; // invalid regex → don't match
+  }
+}
+
+// Fire one hook with a JSON payload on stdin; interpret its result. A hook blocks by
+// exiting with code 2 (reason from stderr) or printing JSON with decision "block"/"deny".
+// It may inject context via { "additionalContext": "..." }.
+async function fireHook(def: HookDef, payload: unknown, cwd: string): Promise<HookOutcome> {
+  const res = await exec(def.command, [], {
+    cwd,
+    timeoutMs: HOOK_TIMEOUT_MS,
+    shell: true,
+    input: JSON.stringify(payload),
+  });
+  if (res.code === 2) return { block: true, reason: res.stderr.trim() || "blocked by hook" };
+  const stdout = res.stdout.trim();
+  if (stdout.startsWith("{")) {
+    try {
+      const out = JSON.parse(stdout) as Record<string, unknown>;
+      const decision = (out.decision ?? out.permissionDecision) as string | undefined;
+      return {
+        block: decision === "block" || decision === "deny",
+        reason: (out.reason ?? out.permissionDecisionReason) as string | undefined,
+        additionalContext: out.additionalContext as string | undefined,
+      };
+    } catch {
+      /* not JSON → no control signal */
+    }
+  }
+  return {};
+}
+
+// Runs the configured hooks for each lifecycle event.
+export class HookRunner {
+  constructor(
+    private readonly hooks: HooksConfig,
+    private readonly cwd: string,
+  ) {}
+
+  has(event: HookEvent): boolean {
+    return (this.hooks[event]?.length ?? 0) > 0;
+  }
+
+  config(): HooksConfig {
+    return this.hooks;
+  }
+
+  // Fire tool-event hooks (Pre/PostToolUse). The first hook to block wins.
+  async tool(
+    event: "PreToolUse" | "PostToolUse",
+    toolName: string,
+    payload: { input: unknown; output?: unknown },
+  ): Promise<HookOutcome> {
+    const defs = (this.hooks[event] ?? []).filter((d) => matches(d, toolName));
+    let merged: HookOutcome = {};
+    for (const def of defs) {
+      const outcome = await fireHook(def, { event, tool: toolName, ...payload, cwd: this.cwd }, this.cwd);
+      if (outcome.block) return outcome;
+      merged = { ...merged, ...outcome };
+    }
+    return merged;
+  }
+
+  // Fire UserPromptSubmit hooks; a block vetoes the turn, additionalContext is merged.
+  async prompt(text: string): Promise<HookOutcome> {
+    const defs = this.hooks.UserPromptSubmit ?? [];
+    let context = "";
+    for (const def of defs) {
+      const outcome = await fireHook(def, { event: "UserPromptSubmit", prompt: text, cwd: this.cwd }, this.cwd);
+      if (outcome.block) return outcome;
+      if (outcome.additionalContext) context += (context ? "\n" : "") + outcome.additionalContext;
+    }
+    return context ? { additionalContext: context } : {};
+  }
+
+  // Fire Stop hooks (turn finished); fire-and-report, no control flow.
+  async stop(): Promise<void> {
+    for (const def of this.hooks.Stop ?? []) {
+      await fireHook(def, { event: "Stop", cwd: this.cwd }, this.cwd);
+    }
+  }
+}
+
+// Wrap each tool's execute with Pre/PostToolUse hooks. A blocking PreToolUse hook
+// short-circuits the call, returning the reason so the model can adapt. No-op when no
+// tool hooks are configured.
+export function wrapToolsWithHooks(tools: ToolSet, runner: HookRunner): ToolSet {
+  if (!runner.has("PreToolUse") && !runner.has("PostToolUse")) return tools;
+  const wrapped: ToolSet = {};
+  for (const [name, t] of Object.entries(tools)) {
+    const orig = (t as any).execute;
+    if (typeof orig !== "function") {
+      wrapped[name] = t;
+      continue;
+    }
+    wrapped[name] = {
+      ...(t as any),
+      execute: async (input: unknown, options: unknown) => {
+        const pre = await runner.tool("PreToolUse", name, { input });
+        if (pre.block) return `Blocked by PreToolUse hook: ${pre.reason ?? "no reason given"}`;
+        const output = await orig(input, options);
+        await runner.tool("PostToolUse", name, { input, output });
+        return output;
+      },
+    } as ToolSet[string];
+  }
+  return wrapped;
+}

package/src/main.tsx

@@ -0,0 +1,167 @@
+import React from "react";
+import { render } from "ink";
+import { Command } from "commander";
+import { Root } from "./components/Root.tsx";
+import { NAME, VERSION, DESCRIPTION } from "./version.ts";
+import { loadConfig } from "./config/load.ts";
+import { createSession } from "./session.ts";
+import { loadLatest, loadSession } from "./memory/store.ts";
+import { configuredProviders } from "./providers/resolve.ts";
+import { describeError } from "./engine/errors.ts";
+
+// Set while Ink owns the screen. A stray unhandled rejection while the TUI is up
+// must NOT reach stdout/stderr — Node's default printer dumps the whole error
+// object (the request body included) unredacted and scrambles the render. The
+// underlying error has already surfaced cleanly via the engine's `error` event,
+// so here we just swallow the duplicate.
+let tuiActive = false;
+
+process.on("unhandledRejection", (reason) => {
+  if (tuiActive) return;
+  const d = describeError(reason);
+  process.stderr.write(`\nError: ${d.message}${d.hint ? `\n${d.hint}` : ""}\n`);
+  process.exitCode = 1;
+});
+
+interface CliOptions {
+  print?: boolean;
+  model?: string;
+  cwd?: string;
+  dangerouslySkipPermissions?: boolean;
+  // Commander treats `--no-quarter` as a negatable boolean: `quarter` is true by
+  // default and becomes false when the flag is passed.
+  quarter?: boolean;
+  continue?: boolean;
+  resume?: string;
+  onboard?: boolean;
+  // Commander negatable boolean: `confine` is true by default, false with --no-confine.
+  confine?: boolean;
+}
+
+const DEFAULT_MODEL = "anthropic:claude-opus-4-8";
+
+async function main() {
+  const program = new Command();
+
+  program
+    .name(NAME)
+    .description(DESCRIPTION)
+    .version(VERSION, "-v, --version")
+    .argument("[prompt...]", "prompt to send (with -p, runs headless)")
+    .option("-p, --print", "print mode: run headless and write the answer to stdout")
+    .option("-m, --model <provider:model>", "model to use, e.g. openrouter:anthropic/claude-opus-4.8")
+    .option("-C, --cwd <dir>", "working directory")
+    .option("--no-confine", "let the agent read/edit outside the working directory without prompting")
+    .option("--dangerously-skip-permissions", "auto-approve all tool actions (bypass mode)")
+    .option("--no-quarter", "auto-approve all tool actions, taking no prisoners (bypass mode)")
+    .option("-c, --continue", "resume the most recent session in this directory")
+    .option("-r, --resume <id>", "resume a specific session by id (printed on exit)")
+    .option("--onboard", "run the provider/key setup flow")
+    .action(async (promptParts: string[], options: CliOptions) => {
+      try {
+        if (options.cwd) process.chdir(options.cwd);
+        const config = loadConfig();
+        if (options.dangerouslySkipPermissions || options.quarter === false)
+          config.permissionMode = "bypass";
+        // --no-confine turns off the working-directory boundary for this run.
+        if (options.confine === false) config.confineToCwd = false;
+        // --resume <id> loads a specific session (the id printed on a prior exit);
+        // --continue loads the most recent one.
+        const resume = options.resume
+          ? loadSession(process.cwd(), options.resume)
+          : options.continue
+            ? loadLatest(process.cwd())
+            : null;
+        if (options.resume && !resume) {
+          process.stderr.write(`No session "${options.resume}" found in this directory.\n`);
+        }
+        const modelSpec = options.model ?? resume?.modelSpec ?? config.defaultModel ?? DEFAULT_MODEL;
+
+        if (options.print) {
+          await runPrint(modelSpec, promptParts.join(" ").trim(), config.confineToCwd);
+          return;
+        }
+
+        // First-run onboarding: no provider has credentials yet (and we're not
+        // resuming). Also forceable with --onboard.
+        const noProviderReady = !configuredProviders(config).some((p) => p.ready);
+        const startInOnboarding = Boolean(options.onboard) || (!resume && noProviderReady);
+
+        // Interactive TUI.
+        tuiActive = true;
+        const { waitUntilExit } = render(
+          <Root
+            config={config}
+            modelSpec={modelSpec}
+            cwd={process.cwd()}
+            resume={resume}
+            startInOnboarding={startInOnboarding}
+          />,
+        );
+        await waitUntilExit();
+        tuiActive = false;
+
+        // On exit, print a hash that resumes this conversation later (à la Claude
+        // Code). The latest persisted session carries the id used this run; it only
+        // exists once at least one turn has been saved.
+        const last = loadLatest(process.cwd());
+        if (last && last.messages.length > 0) {
+          process.stdout.write(`\nResume this session:  ${NAME} --resume ${last.id}\n`);
+        }
+      } catch (err) {
+        // Configuration/resolution errors are expected and user-facing — print them
+        // cleanly without a stack trace.
+        process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exitCode = 1;
+      }
+    });
+
+  await program.parseAsync(process.argv);
+}
+
+// Headless one-shot: stream the answer to stdout, surfacing tool activity on stderr.
+async function runPrint(modelSpec: string, prompt: string, confineToCwd: boolean) {
+  if (!prompt) {
+    process.stderr.write("No prompt provided.\n");
+    process.exitCode = 1;
+    return;
+  }
+  const session = createSession({ config: loadConfig(), modelSpec, cwd: process.cwd(), confineToCwd });
+  for await (const ev of session.engine.send(prompt)) {
+    switch (ev.type) {
+      case "text":
+        process.stdout.write(ev.text);
+        break;
+      case "tool-call":
+        process.stderr.write(`\n· ${ev.name} ${JSON.stringify(ev.input)}\n`);
+        break;
+      case "tool-error":
+        process.stderr.write(`\n! ${ev.name}: ${ev.error}\n`);
+        break;
+      case "routed":
+        process.stderr.write(
+          ev.missing && ev.missing.length > 0
+            ? `\n⚠ no model configured for ${ev.missing.join("/")} input\n`
+            : `\n↪ ${ev.label}${ev.reason ? ` · ${ev.reason}` : ""}\n`,
+        );
+        break;
+      case "error":
+        process.stderr.write(`\nError: ${ev.error}${ev.hint ? `\n${ev.hint}` : ""}\n`);
+        process.exitCode = 1;
+        break;
+      case "finish":
+        process.stdout.write(
+          `\n\n[${modelSpec} · ${ev.usage.totalTokens} tokens · ${ev.finishReason}]\n`,
+        );
+        break;
+    }
+  }
+}
+
+main().catch((err) => {
+  // Redact + summarize rather than dumping the raw error object, which may carry
+  // request bodies or key material in provider-error fields.
+  const d = describeError(err);
+  process.stderr.write(`Error: ${d.message}${d.hint ? `\n${d.hint}` : ""}\n`);
+  process.exit(1);
+});