privateer-agent 0.1.0

package/src/remote/relayClient.ts

@@ -0,0 +1,283 @@
+/**
+ * Remote-access relay client (Phase 2).
+ *
+ * When the user enables /remote-access, the running TUI opens an outbound
+ * WebSocket to the Privateer server's relay. The app ("controller") can then
+ * drive THIS terminal ("agent"): it sends prompts down, and we stream the
+ * engine's events + tool-approval requests back up. Tool execution still runs
+ * locally and stays gated — a remote-driven turn relays every would-be action
+ * to the app for Allow/Deny (see uiGate.ts getRemote).
+ *
+ * The socket is authenticated with a single-use, short-TTL ticket minted over
+ * the authenticated REST channel (RN can't set WS headers and a JWT in the URL
+ * would leak). We never carry the JWT into the WS URL.
+ *
+ * Framework-agnostic: nothing here imports React. The App owns an instance via
+ * a ref and wires the callbacks to its turn loop.
+ */
+import WebSocket from "ws";
+import { randomUUID } from "node:crypto";
+import { apiRequest, serverBaseUrl } from "../auth/privateer.ts";
+import type { EngineEvent } from "../engine/events.ts";
+import type { PermissionRequest } from "../permissions/gate.ts";
+
+// Display label for THIS running terminal. Deliberately NON-PII: we do NOT send
+// username@hostname or the working-directory name to the server/controller (the
+// server is supposed to learn as little as possible). A short random tag lets the
+// user tell multiple terminals apart; they can rename it in the app.
+function terminalLabel(): string {
+  return `terminal-${randomUUID().slice(0, 4)}`;
+}
+
+// Best-effort redaction of secret-looking content before it crosses the relay to
+// the controller/server. This is a SAFETY NET, not a guarantee — truncation
+// bounds size, this bounds obvious secret leakage (bearer tokens, API keys, env
+// secrets, PEM private keys). The "output may contain secrets" warning still
+// stands; a determined leak (unusual formats) can slip through.
+function redactSecrets(s: string): string {
+  if (!s) return s;
+  return s
+    .replace(/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, "[redacted private key]")
+    .replace(/\b(bearer)\s+[A-Za-z0-9._\-]{12,}/gi, "$1 [redacted]")
+    .replace(/\b(sk|rk|pk|ghp|gho|ghs|github_pat|AKIA|ASIA)[-_][A-Za-z0-9]{8,}/g, "[redacted key]")
+    .replace(/\b([A-Z0-9_]*(?:KEY|SECRET|TOKEN|PASSWORD|PASSWD|PRIVATE)[A-Z0-9_]*)\s*[:=]\s*['"]?[^\s'"]{6,}/gi, "$1=[redacted]");
+}
+
+// Redact then clip: redaction runs on full text so a secret near the cut isn't
+// missed, then we bound the wire size.
+function safe(s: string, max: number): string {
+  return clip(redactSecrets(s), max);
+}
+
+export interface RelayCallbacks {
+  // A prompt arrived from the app — feed it into the turn loop (tagged remote).
+  onPrompt: (text: string) => void;
+  // The app asked to interrupt the in-flight turn.
+  onInterrupt: () => void;
+  // The app answered a relayed approval request.
+  onApprovalResponse: (id: string, decision: "allow" | "deny") => void;
+  // A controller attached — push a transcript snapshot so it can catch up.
+  onControllerAttached: () => void;
+  // Surface a one-line status/notice in the TUI.
+  onStatus?: (text: string) => void;
+}
+
+const RECONNECT_MS = 3000;
+// Coalesce streaming deltas so we don't emit one WS frame per token.
+const TEXT_FLUSH_MS = 60;
+
+function clip(s: string, max: number): string {
+  if (s.length <= max) return s;
+  return s.slice(0, max) + `\n… (${s.length - max} more chars)`;
+}
+
+function asText(output: unknown): string {
+  return typeof output === "string" ? output : JSON.stringify(output);
+}
+
+// A relay-specific projection of an EngineEvent: serializable + size-bounded.
+// The raw event's tool input/output are `unknown` and bash output can be ~30k
+// chars, so we normalize to text and truncate before sending over the wire.
+function projectEvent(ev: EngineEvent): Record<string, unknown> {
+  switch (ev.type) {
+    case "tool-call":
+      return { type: "tool-call", id: ev.id, name: ev.name, input: safe(asText(ev.input), 2000) };
+    case "tool-result":
+      return { type: "tool-result", id: ev.id, name: ev.name, output: safe(asText(ev.output), 4000) };
+    case "tool-error":
+      return { type: "tool-error", id: ev.id, name: ev.name, error: safe(ev.error, 2000) };
+    case "usage":
+      return { type: "usage", usage: ev.usage, turn: ev.turn };
+    case "finish":
+      return { type: "finish", finishReason: ev.finishReason };
+    case "routed":
+      return { type: "routed", label: ev.label, reason: ev.reason };
+    case "retrying":
+      return { type: "retrying", attempt: ev.attempt, max: ev.max, reason: clip(ev.reason, 500) };
+    case "error":
+      return { type: "error", error: clip(ev.error, 2000), hint: ev.hint };
+    case "compacted":
+      return { type: "compacted", before: ev.before, after: ev.after };
+    case "aborted":
+      return { type: "aborted" };
+    case "step-finish":
+      return { type: "step-finish" };
+    default:
+      // text/reasoning are coalesced in sendEvent and never reach here.
+      return { type: ev.type };
+  }
+}
+
+export class RelayClient {
+  private ws: WebSocket | null = null;
+  private closed = false;
+  private connecting = false;
+  private reconnectTimer: ReturnType<typeof setTimeout> | undefined;
+  // Ordered delta buffer (text/reasoning) coalesced into one frame per flush.
+  private bufKind: "text" | "reasoning" | null = null;
+  private buf = "";
+  private flushTimer: ReturnType<typeof setTimeout> | undefined;
+  // Stable for this process so reconnects keep the same terminal identity.
+  private readonly termId = randomUUID();
+  private readonly label = terminalLabel();
+
+  constructor(private readonly cb: RelayCallbacks) {}
+
+  async start(): Promise<void> {
+    this.closed = false;
+    await this.connect();
+  }
+
+  stop(): void {
+    this.closed = true;
+    if (this.reconnectTimer) { clearTimeout(this.reconnectTimer); this.reconnectTimer = undefined; }
+    if (this.flushTimer) { clearTimeout(this.flushTimer); this.flushTimer = undefined; }
+    this.bufKind = null;
+    this.buf = "";
+    try { this.ws?.close(); } catch (_) { /* ignore */ }
+    this.ws = null;
+  }
+
+  private async connect(): Promise<void> {
+    if (this.closed || this.connecting || this.ws) return;
+    this.connecting = true;
+    try {
+      // apiRequest → authedFetch refreshes the JWT on 401, so a single in-flight
+      // ticket mint never races a second refresher (we guard with `connecting`).
+      const res = await apiRequest("/relay/ticket", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ role: "agent", termId: this.termId, label: this.label }),
+      });
+      if (!res.ok) throw new Error(`relay ticket HTTP ${res.status}`);
+      const { ticket } = (await res.json()) as { ticket: string };
+
+      const wsUrl =
+        serverBaseUrl().replace(/^http/, "ws") + `/relay?ticket=${encodeURIComponent(ticket)}`;
+      this.debug(`connecting → ${wsUrl}`);
+      const ws = new WebSocket(wsUrl);
+      this.ws = ws;
+      let opened = false;
+      let lastErr = "";
+
+      ws.on("open", () => {
+        opened = true;
+        this.cb.onStatus?.("Remote access connected — drive this terminal from the Privateer app.");
+      });
+      ws.on("message", (data) => this.handle(data));
+      ws.on("close", () => {
+        if (this.ws === ws) this.ws = null;
+        if (!this.closed) {
+          this.cb.onStatus?.(
+            opened
+              ? "Remote access disconnected — reconnecting…"
+              : `Remote access couldn't connect${lastErr ? ` (${lastErr})` : ""} — retrying…`,
+          );
+        }
+        this.scheduleReconnect();
+      });
+      ws.on("error", (err: Error) => {
+        // 'close' fires right after and surfaces the reason; just capture it.
+        lastErr = err?.message || String(err);
+        this.debug(`ws error: ${lastErr}`);
+      });
+    } catch (err) {
+      // Ticket mint failed (auth/network/route) — surface it; a silent failure
+      // looks identical to "connected but ignoring me".
+      const msg = err instanceof Error ? err.message : String(err);
+      this.cb.onStatus?.(`Remote access couldn't reach the relay (${msg}) — retrying…`);
+      this.scheduleReconnect();
+    } finally {
+      this.connecting = false;
+    }
+  }
+
+  private debug(msg: string): void {
+    if (process.env.PRIVATEER_RELAY_DEBUG) this.cb.onStatus?.(`relay: ${msg}`);
+  }
+
+  private scheduleReconnect(): void {
+    if (this.closed || this.reconnectTimer) return;
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = undefined;
+      void this.connect();
+    }, RECONNECT_MS);
+  }
+
+  private handle(data: WebSocket.RawData): void {
+    let frame: { type?: string; text?: string; id?: string; decision?: string };
+    try {
+      frame = JSON.parse(data.toString());
+    } catch (_) {
+      return;
+    }
+    this.debug(`recv ${frame.type}`);
+    switch (frame.type) {
+      case "prompt":
+        if (typeof frame.text === "string" && frame.text.trim()) this.cb.onPrompt(frame.text);
+        break;
+      case "interrupt":
+        this.cb.onInterrupt();
+        break;
+      case "approval_response":
+        if (frame.id) this.cb.onApprovalResponse(frame.id, frame.decision === "deny" ? "deny" : "allow");
+        break;
+      case "controller_attached":
+        this.cb.onControllerAttached();
+        break;
+    }
+  }
+
+  private rawSend(frame: unknown): void {
+    const ws = this.ws;
+    if (ws && ws.readyState === WebSocket.OPEN) {
+      try { ws.send(JSON.stringify(frame)); } catch (_) { /* socket dying */ }
+    }
+  }
+
+  // ── agent → controller ──────────────────────────────────────────────────────
+
+  sendEvent(ev: EngineEvent): void {
+    if (ev.type === "text") return this.bufferDelta("text", ev.text);
+    if (ev.type === "reasoning") return this.bufferDelta("reasoning", ev.text);
+    this.flushDeltas(); // preserve ordering relative to buffered text
+    this.rawSend({ type: "event", event: projectEvent(ev) });
+  }
+
+  // Catch-up history sent to a controller on attach. Structured (not markdown) so
+  // the app renders it with the same styling as the live feed. Bounded: last 80
+  // entries, each clipped.
+  sendSnapshot(entries: { kind: string; text: string }[]): void {
+    const trimmed = entries.slice(-80).map((e) => ({ kind: e.kind, text: safe(String(e.text ?? ""), 4000) }));
+    this.rawSend({ type: "snapshot", entries: trimmed });
+  }
+
+  requestApproval(id: string, req: PermissionRequest): void {
+    this.rawSend({
+      type: "approval_request",
+      id,
+      req: { tool: req.tool, kind: req.kind, title: req.title, detail: safe(req.detail, 4000), outside: !!req.outside },
+    });
+  }
+
+  private bufferDelta(kind: "text" | "reasoning", text: string): void {
+    if (this.bufKind && this.bufKind !== kind) this.flushDeltas();
+    this.bufKind = kind;
+    this.buf += text;
+    if (!this.flushTimer) {
+      this.flushTimer = setTimeout(() => {
+        this.flushTimer = undefined;
+        this.flushDeltas();
+      }, TEXT_FLUSH_MS);
+    }
+  }
+
+  private flushDeltas(): void {
+    if (this.flushTimer) { clearTimeout(this.flushTimer); this.flushTimer = undefined; }
+    if (this.bufKind && this.buf) {
+      this.rawSend({ type: "event", event: { type: this.bufKind, text: this.buf } });
+    }
+    this.bufKind = null;
+    this.buf = "";
+  }
+}

package/src/session.ts

@@ -0,0 +1,264 @@
+import type { LanguageModel, ToolSet } from "ai";
+import type { Config } from "./config/schema.ts";
+import { resolveModel, parseModelSpec } from "./providers/resolve.ts";
+import { modelSupports, modalitiesFor, suggestModelFor } from "./providers/capabilities.ts";
+import type { Route, RouteSet, Modality } from "./engine/router.ts";
+import { createTools, createReadOnlyTools, createToolSubset } from "./tools/index.ts";
+import { buildSystemPrompt, buildSubAgentPrompt, buildAgentPrompt } from "./context/systemPrompt.ts";
+import { findOutputStyle } from "./context/outputStyles.ts";
+import { QueryEngine } from "./engine/QueryEngine.ts";
+import { autoApproveGate, type PermissionGate } from "./permissions/gate.ts";
+import type { SubAgentRunner } from "./tools/context.ts";
+import { TodoStore } from "./tools/todoStore.ts";
+import type { CheckpointStore } from "./memory/checkpoints.ts";
+import type { ProcessRegistry } from "./tools/processRegistry.ts";
+import { AttachmentStore } from "./util/attachmentStore.ts";
+import { HookRunner, loadHooks, wrapToolsWithHooks } from "./hooks/engine.ts";
+import { createLimiter } from "./util/limit.ts";
+
+export interface SessionOptions {
+  config: Config;
+  modelSpec: string;
+  cwd: string;
+  gate?: PermissionGate;
+  // Confine file tools to cwd (default true). False lets the agent read/edit anywhere.
+  confineToCwd?: boolean;
+  // Out-of-cwd directories approved this session; shared with the gate so an approved
+  // location stops re-prompting. Pass the same array instance the gate holds.
+  allowedOutsideRoots?: string[];
+  // Active output style name (persona); resolved against .privateer/output-styles.
+  outputStyle?: string;
+  // When true, the system prompt instructs the model to plan, not implement.
+  planMode?: boolean;
+  // Session checkpoint store; write/edit record mutations into it for /rewind.
+  checkpoints?: CheckpointStore;
+  // Extra tools merged into the toolset (e.g. tools exposed by MCP servers).
+  extraTools?: ToolSet;
+  // Background-shell registry for bash run_in_background / bash_output / kill_shell.
+  processes?: ProcessRegistry;
+  // Session attachment store, so dragged/pasted file bytes can be saved via the
+  // save_attachment tool. Created here when the caller doesn't supply one.
+  attachments?: AttachmentStore;
+  // Reports each finished `task` sub-agent's run metrics (tool uses + tokens) by
+  // tool-call id, so the TUI can render the grouped agents view. Best-effort.
+  onSubAgentMetrics?: (toolCallId: string, m: { toolUses: number; tokens: number }) => void;
+}
+
+export interface Session {
+  engine: QueryEngine;
+  modelSpec: string;
+  provider: string;
+  modelId: string;
+  cwd: string;
+  todos: TodoStore;
+  attachments: AttachmentStore;
+}
+
+// Assemble a ready-to-run agent session: resolve the model, bind tools to the
+// cwd + permission gate, build the system prompt, and create the engine.
+export function createSession(opts: SessionOptions): Session {
+  const resolved = resolveModel(opts.modelSpec, opts.config);
+  const gate = opts.gate ?? autoApproveGate;
+  const confineToCwd = opts.confineToCwd ?? true;
+  const allowedOutsideRoots = opts.allowedOutsideRoots ?? [];
+  const todos = new TodoStore();
+  const attachments = opts.attachments ?? new AttachmentStore();
+  const cache = isAnthropicFamily(resolved.provider, resolved.modelId);
+
+  // Bound how many sub-agents run at once when the model fans `task` calls out.
+  const subAgentLimit = createLimiter(opts.config.maxSubagents);
+
+  // A `task` sub-agent: a fresh engine run to completion, returning the text it
+  // produced. Without an agent definition it uses the read-only toolset under an
+  // auto-approve gate; with one it uses that agent's tools (routed through the parent
+  // gate, so any mutations are still user-approved), model override, and instructions.
+  const runSubAgent: SubAgentRunner = ({ description, prompt, agent }) =>
+    subAgentLimit(async () => {
+    let model = resolved.model;
+    let childCache = cache;
+    if (agent?.model) {
+      try {
+        const r = resolveModel(agent.model, opts.config);
+        model = r.model;
+        childCache = isAnthropicFamily(r.provider, r.modelId);
+      } catch {
+        /* fall back to the parent model */
+      }
+    }
+    const system = agent
+      ? buildAgentPrompt({ cwd: opts.cwd, model: opts.modelSpec, description, instructions: agent.prompt })
+      : buildSubAgentPrompt({ cwd: opts.cwd, model: opts.modelSpec, description });
+    const tools = agent
+      ? createToolSubset({ cwd: opts.cwd, gate, confineToCwd, allowedOutsideRoots }, agent.tools)
+      : createReadOnlyTools({ cwd: opts.cwd, gate: autoApproveGate, confineToCwd, allowedOutsideRoots });
+
+    const child = new QueryEngine({
+      routes: singleRouteSet(agent?.model ?? opts.modelSpec, model, childCache),
+      system,
+      tools,
+      maxSteps: Math.min(opts.config.maxSteps, 20),
+    });
+    let out = "";
+    let toolUses = 0;
+    for await (const ev of child.send(prompt)) {
+      if (ev.type === "text") out += ev.text;
+      else if (ev.type === "tool-call") toolUses++;
+      else if (ev.type === "error")
+        return { text: `Sub-agent error: ${ev.error}`, toolUses, tokens: child.usage.totalTokens };
+    }
+    return {
+      text: out.trim() || "(sub-agent returned no output)",
+      toolUses,
+      tokens: child.usage.totalTokens,
+    };
+    });
+
+  const hooks = new HookRunner(loadHooks((opts.config as Record<string, unknown>).hooks), opts.cwd);
+  const tools = wrapToolsWithHooks(
+    {
+      ...createTools({
+        cwd: opts.cwd,
+        gate,
+        confineToCwd,
+        allowedOutsideRoots,
+        todos,
+        runSubAgent,
+        onSubAgentMetrics: opts.onSubAgentMetrics,
+        recordMutation: opts.checkpoints ? (abs) => opts.checkpoints!.recordMutation(abs) : undefined,
+        processes: opts.processes,
+        attachments,
+      }),
+      ...(opts.extraTools ?? {}),
+    },
+    hooks,
+  );
+  const outputStyleBody = opts.outputStyle
+    ? findOutputStyle(opts.outputStyle, opts.cwd)?.body
+    : undefined;
+  const system = buildSystemPrompt({
+    cwd: opts.cwd,
+    model: opts.modelSpec,
+    outputStyleBody,
+    planMode: opts.planMode,
+  });
+
+  const engine = new QueryEngine({
+    routes: buildRouteSet(opts.config, opts.modelSpec, resolved.model, cache),
+    system,
+    tools,
+    maxSteps: opts.config.maxSteps,
+    contextBudget: opts.config.contextBudget,
+    compactRatio: opts.config.compactRatio,
+  });
+
+  return {
+    engine,
+    modelSpec: opts.modelSpec,
+    provider: resolved.provider,
+    modelId: resolved.modelId,
+    cwd: opts.cwd,
+    todos,
+    attachments,
+  };
+}
+
+// Anthropic prompt caching only benefits Anthropic-family models: direct Anthropic,
+// or an OpenRouter route to an Anthropic model. For everything else the cache hints
+// are a harmless no-op, but we skip them to avoid sending unused providerOptions.
+function isAnthropicFamily(provider: string, modelId: string): boolean {
+  if (provider === "anthropic") return true;
+  if (provider === "openrouter") return modelId.startsWith("anthropic/");
+  return false;
+}
+
+// Short display name for UI notices: drop any "vendor/" prefix from the model id.
+function shortLabel(spec: string): string {
+  const modelId = spec.includes(":") ? spec.slice(spec.indexOf(":") + 1) : spec;
+  return modelId.slice(modelId.lastIndexOf("/") + 1);
+}
+
+// Resolve a "provider:model" spec into a Route, deriving its per-model cache /
+// thinking flags and supported input modalities from the model family.
+function buildRoute(spec: string, config: Config): Route {
+  const r = resolveModel(spec, config);
+  const cache = isAnthropicFamily(r.provider, r.modelId);
+  return {
+    spec,
+    model: r.model,
+    cacheControl: cache,
+    thinkingBudget: cache ? config.thinkingBudget : undefined,
+    label: shortLabel(spec),
+    supports: modalitiesFor(r.provider, r.modelId),
+  };
+}
+
+// A trivial RouteSet with only the default route (sub-agents, which run one fixed
+// model). The high `longThreshold` / zero `fastMaxChars` keep the router on default.
+function singleRouteSet(spec: string, model: LanguageModel, cacheControl: boolean): RouteSet {
+  const { provider, modelId } = parseModelSpec(spec);
+  return {
+    default: { spec, model, cacheControl, label: shortLabel(spec), supports: modalitiesFor(provider, modelId) },
+    longThreshold: Number.POSITIVE_INFINITY,
+    fastMaxChars: 0,
+  };
+}
+
+// Pairs of (config key, RouteSet key, modality) for the modality routes.
+const MODALITY_ROUTE_KEYS: { cfg: "vision" | "document" | "audio" | "video"; modality: Modality }[] = [
+  { cfg: "vision", modality: "image" },
+  { cfg: "document", modality: "document" },
+  { cfg: "audio", modality: "audio" },
+  { cfg: "video", modality: "video" },
+];
+
+// Assemble the session's RouteSet: the default route (the already-resolved session
+// model) plus any configured modality/long/fast routes, each tagged with the input
+// modalities its model accepts. Optional routes that fail to resolve are skipped
+// rather than failing the session. For each modality whose route is unset, hybrid
+// auto-detect picks a capable model when the default can't handle that modality.
+function buildRouteSet(
+  config: Config,
+  defaultSpec: string,
+  defaultModel: LanguageModel,
+  defaultCache: boolean,
+): RouteSet {
+  const router = config.router;
+  const tryRoute = (spec?: string): Route | undefined => {
+    if (!spec) return undefined;
+    try {
+      return buildRoute(spec, config);
+    } catch {
+      return undefined; // unconfigured/invalid optional route → ignored
+    }
+  };
+
+  const { provider: defProvider, modelId: defModelId } = parseModelSpec(defaultSpec);
+  const routes: RouteSet = {
+    default: {
+      spec: defaultSpec,
+      model: defaultModel,
+      cacheControl: defaultCache,
+      thinkingBudget: defaultCache ? config.thinkingBudget : undefined,
+      label: shortLabel(defaultSpec),
+      supports: modalitiesFor(defProvider, defModelId),
+    },
+    vision: tryRoute(router?.vision),
+    document: tryRoute(router?.document),
+    audio: tryRoute(router?.audio),
+    video: tryRoute(router?.video),
+    long: tryRoute(router?.long),
+    fast: tryRoute(router?.fast),
+    longThreshold: router?.longThreshold ?? Math.floor((config.contextBudget ?? 120_000) / 2),
+    fastMaxChars: router?.fastMaxChars ?? 280,
+  };
+
+  if (router?.auto ?? true) {
+    for (const { cfg, modality } of MODALITY_ROUTE_KEYS) {
+      if (routes[cfg]) continue; // explicitly configured → leave it
+      if (modelSupports(modality, defProvider, defModelId)) continue; // default handles it
+      const suggestion = suggestModelFor(modality, config);
+      if (suggestion) routes[cfg] = tryRoute(suggestion);
+    }
+  }
+  return routes;
+}

package/src/tools/bash.ts

@@ -0,0 +1,98 @@
+import { tool } from "ai";
+import { z } from "zod";
+import type { ToolContext } from "./context.ts";
+import { exec } from "./exec.ts";
+import { PermissionDeniedError } from "../permissions/gate.ts";
+
+const DEFAULT_TIMEOUT = 120_000;
+const MAX_TIMEOUT = 600_000;
+// Cap how much command output enters the conversation. Unbounded output (a big
+// `git diff`, a verbose build log) is otherwise re-sent on every subsequent step of
+// the agentic loop, ballooning token usage. Keep the head and tail — both ends carry
+// the most signal (the command's start and its final status/errors).
+const MAX_OUTPUT_CHARS = 30_000;
+const HEAD_CHARS = 20_000;
+
+function clampOutput(text: string): string {
+  if (text.length <= MAX_OUTPUT_CHARS) return text;
+  const head = text.slice(0, HEAD_CHARS);
+  const tail = text.slice(text.length - (MAX_OUTPUT_CHARS - HEAD_CHARS));
+  const omitted = text.length - MAX_OUTPUT_CHARS;
+  return `${head}\n… (${omitted} chars of output truncated) …\n${tail}`;
+}
+
+export function bashTool(ctx: ToolContext) {
+  return tool({
+    description:
+      "Run a shell command in the working directory and return its output. " +
+      "Use for builds, tests, git, and other CLI tasks. Avoid long-running/interactive commands.",
+    inputSchema: z.object({
+      command: z.string().describe("The shell command to run."),
+      timeout: z.number().int().positive().optional().describe("Timeout in ms (max 600000)."),
+      run_in_background: z
+        .boolean()
+        .optional()
+        .describe("Run detached and return immediately; poll with bash_output, stop with kill_shell."),
+    }),
+    execute: async ({ command, timeout, run_in_background }) => {
+      const decision = await ctx.gate.request({
+        tool: "bash",
+        kind: "bash",
+        title: run_in_background ? "Run command (background)" : "Run command",
+        detail: command,
+      });
+      if (decision === "deny") throw new PermissionDeniedError("bash");
+
+      if (run_in_background) {
+        if (!ctx.processes) return "Background execution is not available in this context.";
+        const id = ctx.processes.spawn(command, ctx.cwd);
+        return `Started in background as ${id}. Read output with bash_output(bash_id="${id}"); stop with kill_shell(bash_id="${id}").`;
+      }
+
+      const timeoutMs = Math.min(timeout ?? DEFAULT_TIMEOUT, MAX_TIMEOUT);
+      const { stdout, stderr, code, timedOut } = await exec(command, [], {
+        cwd: ctx.cwd,
+        timeoutMs,
+        shell: true,
+      });
+
+      const parts: string[] = [];
+      if (stdout.trim()) parts.push(clampOutput(stdout.trimEnd()));
+      if (stderr.trim()) parts.push(`[stderr]\n${clampOutput(stderr.trimEnd())}`);
+      if (timedOut) parts.push(`[timed out after ${timeoutMs}ms]`);
+      parts.push(`[exit code ${code ?? "null"}]`);
+      return parts.join("\n");
+    },
+  });
+}
+
+export function bashOutputTool(ctx: ToolContext) {
+  return tool({
+    description:
+      "Read new output from a background shell started with bash run_in_background. Returns only " +
+      "output produced since the previous read, plus the shell's status.",
+    inputSchema: z.object({
+      bash_id: z.string().describe("The background shell id (e.g. bash_1)."),
+    }),
+    execute: async ({ bash_id }) => {
+      if (!ctx.processes) return "Background processes are not available in this context.";
+      const r = ctx.processes.read(bash_id);
+      if (!r) return `No background shell "${bash_id}".`;
+      const head = `[${r.status}${r.status === "exited" ? `, exit ${r.code ?? "null"}` : ""}]`;
+      return r.output ? `${head}\n${r.output.trimEnd()}` : `${head} (no new output)`;
+    },
+  });
+}
+
+export function killShellTool(ctx: ToolContext) {
+  return tool({
+    description: "Stop a background shell started with bash run_in_background.",
+    inputSchema: z.object({
+      bash_id: z.string().describe("The background shell id to stop."),
+    }),
+    execute: async ({ bash_id }) => {
+      if (!ctx.processes) return "Background processes are not available in this context.";
+      return ctx.processes.kill(bash_id) ? `Stopped ${bash_id}.` : `No background shell "${bash_id}".`;
+    },
+  });
+}