privateer-agent 0.1.1 → 0.3.0

package/src/session.ts

@@ -1,264 +1,97 @@
-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;
+// Thin headless session wrapper (Phase 1).
+//
+// Wraps Pi's createAgentSession and exposes the ONE thing the preserved
+// connection layer needs: a subscription that yields privateer EngineEvents
+// (via the adapter) instead of raw Pi events. `createSession()` →
+// `{ session, subscribeAsEngineEvents() }`, per docs/pi-migration-plan.md §2
+// Phase 1. Mirrors the setup proven in ../../ pi-spike/spike-b.mjs.
+//
+// This module is Pi-touching: it is only ever loaded via a DYNAMIC import from
+// an entrypoint that has already run ./boot.ts (env + dispatcher). Never import
+// it statically from boot.ts or anything boot pulls in.
+
+import {
+  createAgentSession,
+  DefaultResourceLoader,
+  SessionManager,
+  SettingsManager,
+  ModelRegistry,
+  AuthStorage,
+} from "@earendil-works/pi-coding-agent";
+
+import { agentDir as defaultAgentDir } from "./config/paths.ts";
+import { createEngineEventAdapter } from "./bridge/engineAdapter.ts";
+import type { EngineEvent } from "./engine/events.ts";
+
+export interface CreateSessionOptions {
   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;
+  // Pi extension factories, e.g. [makePermissionGate({ decide })].
+  extensionFactories?: Array<(pi: any) => void>;
+  // Custom tools (defineTool) plus the enabled tool-name allowlist.
+  customTools?: unknown[];
+  tools?: string[];
+  // Override the Pi agent dir; defaults to $PRIVATEER_HOME/agent (pinned by boot).
+  agentDir?: string;
 }
 
-// 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 });
+export interface PrivateerSession {
+  session: any;
+  // Subscribe to the turn stream as privateer EngineEvents. Returns an unsubscribe.
+  subscribeAsEngineEvents(onEvent: (ev: EngineEvent) => void): () => void;
+  adapter: ReturnType<typeof createEngineEventAdapter>;
+}
 
-    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,
-    };
-    });
+export async function createSession(opts: CreateSessionOptions): Promise<PrivateerSession> {
+  const AGENT_DIR = opts.agentDir ?? process.env.PI_CODING_AGENT_DIR ?? defaultAgentDir();
+
+  const authStorage = AuthStorage.inMemory();
+  const modelRegistry = ModelRegistry.create(authStorage, `${AGENT_DIR}/models.json`);
+  if (typeof (modelRegistry as any).refresh === "function") await (modelRegistry as any).refresh();
+  else if (typeof (modelRegistry as any).loadModels === "function")
+    await (modelRegistry as any).loadModels();
+
+  const model = modelRegistry.find(opts.provider, opts.modelId);
+  if (!model) {
+    const ids = ((modelRegistry as any).getAll?.() ?? []).map(
+      (m: any) => `${m.provider}/${m.id}`,
+    );
+    throw new Error(
+      `model ${opts.provider}/${opts.modelId} not found. Registry has: ${ids.join(", ") || "(none)"}`,
+    );
+  }
 
-  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({
+  const settingsManager = SettingsManager.create(opts.cwd, AGENT_DIR);
+  const loader = new DefaultResourceLoader({
     cwd: opts.cwd,
-    model: opts.modelSpec,
-    outputStyleBody,
-    planMode: opts.planMode,
+    agentDir: AGENT_DIR,
+    settingsManager,
+    extensionFactories: opts.extensionFactories ?? [],
   });
+  await loader.reload();
 
-  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,
+  const { session } = await createAgentSession({
     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);
-    }
+    agentDir: AGENT_DIR,
+    model,
+    authStorage,
+    modelRegistry,
+    settingsManager,
+    sessionManager: SessionManager.inMemory(opts.cwd),
+    resourceLoader: loader,
+    ...(opts.customTools ? { customTools: opts.customTools } : {}),
+    ...(opts.tools ? { tools: opts.tools } : {}),
+  } as any);
+
+  const adapter = createEngineEventAdapter();
+
+  function subscribeAsEngineEvents(onEvent: (ev: EngineEvent) => void): () => void {
+    const unsub = session.subscribe((ev: any) => {
+      for (const ee of adapter.toEngineEvents(ev)) onEvent(ee);
+    });
+    return () => unsub?.();
   }
-  return routes;
+
+  return { session, subscribeAsEngineEvents, adapter };
 }

package/src/tools/routine.ts

@@ -0,0 +1,129 @@
+// The `create_routine` tool — lets the agent turn "summarize the news every morning"
+// or "remind me at 3pm tomorrow" into a saved routine the scheduler daemon runs
+// unattended (see src/daemon). Ported from tree-cli/src/tools/routine.ts, adapted to
+// Pi's registerTool (TypeBox schema) with the in-tool ctx.gate.request removed: in
+// the Pi model our permission-gate extension gates the tool_call itself (classify.ts
+// gives it a "Create routine" prompt + flags email/webhook egress).
+
+import { Type } from "typebox";
+import { readFileSync } from "node:fs";
+import { configPath } from "../config/paths.ts";
+import { newRoutineId, webhookName, type Routine } from "../routines/schema.ts";
+import { triggerError, computeNextRun, describeTrigger } from "../routines/trigger.ts";
+import { upsertRoutine } from "../routines/store.ts";
+import { sendToDaemon, DaemonNotRunningError } from "../daemon/ipc.ts";
+
+const KNOWN_CHANNELS = new Set(["file", "relay", "notice", "cloud", "email"]);
+
+function loadWebhooks(): Record<string, { url?: string }> {
+  try {
+    return JSON.parse(readFileSync(configPath(), "utf8")).webhooks ?? {};
+  } catch {
+    return {};
+  }
+}
+
+function text(t: string) {
+  return { content: [{ type: "text", text: t }], details: {} };
+}
+
+export const routineToolDefinition = {
+  name: "create_routine",
+  label: "Create Routine",
+  description:
+    "Create a routine: a saved task the scheduler runs unattended, either recurring (a cron " +
+    "expression) or one-off (a specific datetime), and delivers the result. Use when the user asks " +
+    "to be notified/updated on a cadence ('every morning', 'nightly') or at a future time ('at 3pm " +
+    "tomorrow'). Set exactly one of `cron` or `at`. Confirm timing + delivery with the user first; " +
+    "creating a routine prompts for approval. Runs use a safe read-only toolset unless `tools` grants more.",
+  parameters: Type.Object({
+    name: Type.String({ description: "Short unique label, e.g. 'morning-news'." }),
+    cron: Type.Optional(Type.String({ description: "Recurring: 5-field cron, e.g. '0 8 * * *' (08:00 daily). Omit for one-off." })),
+    at: Type.Optional(Type.String({ description: "One-off: ISO-8601 datetime, e.g. '2026-07-02T15:00:00'. Omit for recurring." })),
+    prompt: Type.String({ description: "Self-contained instruction the agent runs when it fires." }),
+    delivery: Type.Optional(
+      Type.Array(Type.String(), {
+        description:
+          "Where to deliver: 'file' (default), 'notice', 'relay', 'cloud' (E2E-encrypted to your Privateer " +
+          "account), 'email' (plaintext, opt-in), or 'webhook:<name>' (name must exist in config webhooks).",
+      }),
+    ),
+    cwd: Type.Optional(Type.String({ description: "Working directory for the run. Defaults to the current one." })),
+    model: Type.Optional(Type.String({ description: "Optional 'provider:model' or 'provider/model' override." })),
+    tools: Type.Optional(Type.Array(Type.String(), { description: "Tool allow-list; omit for the default safe set." })),
+  }),
+  async execute(
+    _toolCallId: string,
+    params: {
+      name: string;
+      cron?: string;
+      at?: string;
+      prompt: string;
+      delivery?: string[];
+      cwd?: string;
+      model?: string;
+      tools?: string[];
+    },
+    _signal?: AbortSignal,
+    _onUpdate?: unknown,
+    ctx?: { cwd?: string },
+  ) {
+    const { name, cron, at, prompt, delivery, cwd, model, tools } = params;
+
+    const err = triggerError({ cron, at });
+    if (err) return text(`Error: ${err}`);
+
+    const chans = delivery && delivery.length > 0 ? delivery : ["file"];
+    // Validate channels: known names or webhook:<name>.
+    const bad = chans.filter((c) => !KNOWN_CHANNELS.has(c) && webhookName(c) === null);
+    if (bad.length > 0) return text(`Error: unknown delivery channel(s): ${bad.join(", ")}.`);
+
+    // Webhook targets must be pre-declared in config (the routine never carries a URL).
+    const hooks = chans.map(webhookName).filter((n): n is string => n !== null);
+    if (hooks.length > 0) {
+      const configured = loadWebhooks();
+      const unknown = hooks.filter((n) => !configured[n]);
+      if (unknown.length > 0) {
+        return text(
+          `Error: webhook${unknown.length > 1 ? "s" : ""} not configured: ${unknown.join(", ")}. ` +
+            `Declare them under "webhooks" in ~/.privateer/config.json first.`,
+        );
+      }
+    }
+
+    const next = computeNextRun({ cron, at });
+    const routine: Routine = {
+      id: newRoutineId(),
+      name,
+      cron,
+      at,
+      prompt,
+      cwd: cwd ?? ctx?.cwd ?? process.cwd(),
+      model,
+      delivery: chans as Routine["delivery"],
+      tools,
+      enabled: true,
+      nextRun: next?.toISOString(),
+    };
+
+    // Hand to the running daemon (it validates + schedules); fall back to writing the
+    // file so the routine persists until the daemon starts.
+    try {
+      const res = await sendToDaemon({ cmd: "add", routine });
+      if (!res.ok) return text(`Error saving routine: ${res.message ?? "unknown"}`);
+      return text(
+        `Created routine "${name}" (${describeTrigger({ cron, at })}). ` +
+          `Next run ${next ? next.toLocaleString() : "unknown"}, delivery: ${chans.join(", ")}.`,
+      );
+    } catch (e) {
+      if (e instanceof DaemonNotRunningError) {
+        upsertRoutine(routine);
+        return text(
+          `Saved routine "${name}" (${describeTrigger({ cron, at })}), but the scheduler daemon isn't ` +
+            `running yet, so it won't fire until you start it.`,
+        );
+      }
+      return text(`Error contacting the scheduler: ${e instanceof Error ? e.message : String(e)}`);
+    }
+  },
+};

package/src/tools/saveAttachment.ts

@@ -1,53 +1,50 @@
+// The `save_attachment` tool — persist a file the user attached from the app (shown
+// in the prompt as "[Attachment #n] name") to a real path on disk. Ported from
+// tree-cli to Pi registerTool; the in-tool ctx.gate.request is dropped (our gate
+// extension gates the tool_call, classified as a write against the destination path).
+
+import { Type } from "typebox";
 import { writeFileSync, mkdirSync, readFileSync } from "node:fs";
-import { dirname } from "node:path";
-import { tool } from "ai";
-import { z } from "zod";
-import type { ToolContext } from "./context.ts";
-import { resolveInCwd, displayPath, isOutsideScope } from "./context.ts";
-import { PermissionDeniedError } from "../permissions/gate.ts";
-import { isProtectedPath } from "../permissions/protected.ts";
+import { dirname, isAbsolute, resolve } from "node:path";
+import type { AttachmentStore } from "../util/attachmentStore.ts";
+
+function text(t: string) {
+  return { content: [{ type: "text", text: t }], details: {} };
+}
 
-export function saveAttachmentTool(ctx: ToolContext) {
-  return tool({
+export function makeSaveAttachmentTool(store: AttachmentStore) {
+  return {
+    name: "save_attachment",
+    label: "Save Attachment",
     description:
-      "Save a user-attached file (image, PDF, audio, or video — shown in the prompt as a " +
-      '"[Image #n]" / "[PDF #n]" / etc. chip) to a path on disk. Use this to persist a pasted ' +
-      "or dragged-in attachment instead of trying to copy it from a temp or drop path, which is " +
-      "unreliable and may be an empty placeholder. `ref` is the number n from the chip.",
-    inputSchema: z.object({
-      ref: z
-        .number()
-        .int()
-        .describe("The attachment reference number n, taken from its [Kind #n] chip."),
-      path: z.string().describe("Destination file path to write the attachment to."),
+      "Save a file the user attached from the Privateer app (shown in the prompt as a \"[Attachment #n] " +
+      "name\" chip) to a path on disk. Use this to persist a received attachment. `ref` is the number n.",
+    parameters: Type.Object({
+      ref: Type.Integer({ description: "The attachment reference number n from its [Attachment #n] chip." }),
+      path: Type.String({ description: "Destination file path to write the attachment to." }),
     }),
-    execute: async ({ ref, path }) => {
-      const store = ctx.attachments;
-      const entry = store?.get(ref);
+    async execute(
+      _toolCallId: string,
+      params: { ref: number; path: string },
+      _signal?: AbortSignal,
+      _onUpdate?: unknown,
+      ctx?: { cwd?: string },
+    ) {
+      const entry = store.get(params.ref);
       if (!entry) {
-        const avail = store?.refs() ?? [];
-        return avail.length
-          ? `No attachment #${ref}. Available this session: ${avail.map((n) => `#${n}`).join(", ")}.`
-          : `No attachment #${ref}: nothing has been attached this session.`;
+        const avail = store.refs();
+        return text(
+          avail.length
+            ? `No attachment #${params.ref}. Available this session: ${avail.map((n) => `#${n}`).join(", ")}.`
+            : `No attachment #${params.ref}: nothing has been attached this session.`,
+        );
       }
-      const abs = resolveInCwd(ctx, path);
-      const outside = isOutsideScope(ctx, abs);
-      const decision = await ctx.gate.request({
-        tool: "save_attachment",
-        kind: "write",
-        title: outside ? "Save attachment outside working directory" : "Save attachment",
-        detail: `[#${ref}] → ${outside ? abs : displayPath(ctx, abs)} (${entry.mediaType})`,
-        protected: isProtectedPath(abs),
-        outside,
-        path: abs,
-      });
-      if (decision === "deny") throw new PermissionDeniedError("save_attachment");
-
-      ctx.recordMutation?.(abs);
+      const cwd = ctx?.cwd ?? process.cwd();
+      const abs = isAbsolute(params.path) ? params.path : resolve(cwd, params.path);
       mkdirSync(dirname(abs), { recursive: true });
       const bytes = readFileSync(entry.path);
       writeFileSync(abs, bytes);
-      return `Saved attachment #${ref} to ${displayPath(ctx, abs)} (${bytes.length} bytes).`;
+      return text(`Saved attachment #${params.ref} (${entry.name}, ${entry.mediaType}) to ${params.path} (${bytes.length} bytes).`);
     },
-  });
+  };
 }

package/src/tools/sendFile.ts

@@ -0,0 +1,75 @@
+// The `send_file_to_client` tool — stream a file from disk up to the connected
+// Privateer app (the phone/web client driving this terminal via /remote-access) so
+// the user can preview/save it on their device. Ported from tree-cli, adapted to Pi
+// registerTool + the RemoteBridge (which owns the relay's chunked sendFile). Gated by
+// our permission-gate extension like any tool.
+
+import { Type } from "typebox";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { basename, isAbsolute, resolve } from "node:path";
+
+const MAX_SEND_BYTES = 10 * 1024 * 1024; // mirrors the relay's per-file cap
+
+const MEDIA: Record<string, string> = {
+  png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", gif: "image/gif", webp: "image/webp",
+  svg: "image/svg+xml", pdf: "application/pdf", txt: "text/plain", md: "text/markdown",
+  json: "application/json", csv: "text/csv", html: "text/html", mp4: "video/mp4",
+  mov: "video/quicktime", mp3: "audio/mpeg", wav: "audio/wav", zip: "application/zip",
+};
+function mediaTypeForPath(p: string): string {
+  const ext = p.split(".").pop()?.toLowerCase() ?? "";
+  return MEDIA[ext] ?? "application/octet-stream";
+}
+
+function text(t: string) {
+  return { content: [{ type: "text", text: t }], details: {} };
+}
+
+export interface SendFileBridge {
+  isConnected(): boolean;
+  sendFile(file: { name: string; mediaType: string; base64: string; size: number }): Promise<{ ok: boolean; reason?: string }>;
+}
+
+export function makeSendFileTool(bridge: SendFileBridge) {
+  return {
+    name: "send_file_to_client",
+    label: "Send File to App",
+    description:
+      "Send a file from disk to the connected Privateer app (the phone/web client driving this terminal " +
+      "remotely), where the user can preview it and save/share it on their device. Use when the user asks " +
+      "to see, download, or receive a file on their phone or browser. Only works while remote access is on " +
+      "and the app is connected; max 10 MB per file.",
+    parameters: Type.Object({
+      path: Type.String({ description: "Path of the file to send, relative to cwd or absolute." }),
+    }),
+    async execute(
+      _toolCallId: string,
+      params: { path: string },
+      _signal?: AbortSignal,
+      _onUpdate?: unknown,
+      ctx?: { cwd?: string },
+    ) {
+      if (!bridge.isConnected()) {
+        return text(
+          "Cannot send: remote access is off or the app isn't connected right now. " +
+            "Turn it on with /remote-access and open the Privateer app, then try again.",
+        );
+      }
+      const cwd = ctx?.cwd ?? process.cwd();
+      const abs = isAbsolute(params.path) ? params.path : resolve(cwd, params.path);
+      if (!existsSync(abs)) return text(`File not found: ${params.path}`);
+      const stat = statSync(abs);
+      if (stat.isDirectory()) return text(`${params.path} is a directory — send a single file.`);
+      if (stat.size === 0) return text(`${params.path} is empty — nothing to send.`);
+      if (stat.size > MAX_SEND_BYTES) {
+        return text(`${params.path} is ${(stat.size / 1048576).toFixed(1)} MB; the relay caps at ${MAX_SEND_BYTES / 1048576} MB per file.`);
+      }
+      const bytes = readFileSync(abs);
+      const mediaType = mediaTypeForPath(abs);
+      const res = await bridge.sendFile({ name: basename(abs), mediaType, base64: bytes.toString("base64"), size: bytes.length });
+      return res.ok
+        ? text(`Sent ${basename(abs)} (${bytes.length} bytes, ${mediaType}) to the connected app.`)
+        : text(`Couldn't send ${basename(abs)}: ${res.reason ?? "unknown error"}. Is the app currently connected?`);
+    },
+  };
+}