privateer-agent 0.1.0 → 0.2.1

package/src/tools/askUser.ts

@@ -0,0 +1,92 @@
+import { tool } from "ai";
+import { z } from "zod";
+import type { ToolContext } from "./context.ts";
+
+// A single selectable approach presented to the user.
+export interface UserChoiceOption {
+  label: string;
+  description?: string;
+}
+
+// A decision the model surfaces to the user via the `ask_user` tool.
+export interface UserQuestion {
+  question: string;
+  options: UserChoiceOption[];
+  multiSelect: boolean;
+}
+
+// The user's answer: chosen option index(es), free-form custom text, or a dismissal.
+export type UserAnswer =
+  | { kind: "selected"; indices: number[] }
+  | { kind: "custom"; text: string }
+  | { kind: "dismissed" };
+
+// Bridge supplied by the interactive session: surface a question to the TUI and
+// resolve with the user's choice. Absent in non-interactive contexts (sub-agents,
+// remote-driven turns, headless runs), where the tool reports it couldn't ask.
+export type UserAsker = (q: UserQuestion) => Promise<UserAnswer>;
+
+// The `ask_user` tool: when the right implementation direction is genuinely
+// ambiguous, the model puts a small menu of approaches to the user and blocks until
+// they pick one (or write their own answer). No filesystem mutation, so it isn't
+// gated — but it does pause the turn on the human, exactly like the approval prompt.
+export function askUserTool(ctx: ToolContext) {
+  return tool({
+    description:
+      "Ask the user to choose between competing implementation directions when the right " +
+      "approach is genuinely ambiguous and the choice materially changes the work (architecture, " +
+      "a library, a data model, the scope of a change). Present 2–4 concrete options, " +
+      "most-recommended first, each with its trade-offs; the user picks one (or writes their own " +
+      "answer). Prefer this over silently guessing on a consequential fork. Do NOT use it for " +
+      "trivial choices you can reasonably make yourself, or to request permission for an action — " +
+      "the approval gate handles permissions.",
+    inputSchema: z.object({
+      question: z.string().describe("The decision to put to the user, phrased as a question."),
+      options: z
+        .array(
+          z.object({
+            label: z
+              .string()
+              .describe("Short name for this approach, e.g. 'Server-side rendering'."),
+            description: z
+              .string()
+              .optional()
+              .describe("One or two sentences on what it entails and its trade-offs."),
+          }),
+        )
+        .min(2)
+        .max(4)
+        .describe("The competing approaches, most-recommended first."),
+      multiSelect: z
+        .boolean()
+        .optional()
+        .describe("Allow the user to choose more than one option (default false)."),
+    }),
+    execute: async ({ question, options, multiSelect }) => {
+      if (!ctx.askUser) {
+        return (
+          "Cannot ask the user interactively in this context. Pick the best option using your " +
+          "own judgment, then state which you chose and why before proceeding."
+        );
+      }
+      const answer = await ctx.askUser({ question, options, multiSelect: multiSelect ?? false });
+      if (answer.kind === "custom") {
+        return `The user answered: ${answer.text}`;
+      }
+      if (answer.kind === "dismissed") {
+        return (
+          "The user dismissed the question without choosing. Either restate the choice briefly in " +
+          "plain prose, or proceed with the best option and say which you picked."
+        );
+      }
+      const chosen = answer.indices.map((i) => options[i]).filter(Boolean);
+      if (chosen.length === 0) {
+        return "The user made no selection. Proceed with the best option and state which you chose.";
+      }
+      const rendered = chosen
+        .map((o) => (o.description ? `"${o.label}" (${o.description})` : `"${o.label}"`))
+        .join(", ");
+      return `The user chose: ${rendered}. Proceed with this direction.`;
+    },
+  });
+}

package/src/tools/context.ts

@@ -4,6 +4,7 @@ import type { TodoStore } from "./todoStore.ts";
 import type { AgentDefinition } from "../agents/loader.ts";
 import type { ProcessRegistry } from "./processRegistry.ts";
 import type { AttachmentStore } from "../util/attachmentStore.ts";
+import type { UserAsker } from "./askUser.ts";
 
 // A finished sub-agent's result: its final text answer plus run metrics (how many
 // tools it called and how many tokens it spent), so the UI can show a per-agent
@@ -52,6 +53,19 @@ export interface ToolContext {
   // Session attachment store (decoded bytes of pasted/dropped files, by "#n"), for the
   // save_attachment tool to write one back to disk.
   attachments?: AttachmentStore;
+  // Surfaces an `ask_user` question to the interactive UI and resolves with the
+  // user's choice. Absent outside the live TUI (sub-agents, remote-driven turns,
+  // headless runs) — the tool then reports it couldn't ask and the model proceeds.
+  askUser?: UserAsker;
+  // Streams a file to the connected remote controller (the Privateer app) over the
+  // relay, for the send_file_to_client tool. Absent when remote access is off or in
+  // bare/sub-agent/daemon contexts — the tool then reports it can't send.
+  sendFileToController?: (file: {
+    name: string;
+    mediaType: string;
+    base64: string;
+    size: number;
+  }) => Promise<{ ok: boolean; reason?: string }>;
 }
 
 // Resolve a possibly-relative path against the session cwd. The cwd is a *soft*

package/src/tools/index.ts

@@ -10,13 +10,23 @@ import { todoTool } from "./todo.ts";
 import { taskTool } from "./task.ts";
 import { webFetchTool, webSearchTool } from "./web.ts";
 import { saveAttachmentTool } from "./saveAttachment.ts";
+import { sendFileToClientTool } from "./sendFileToClient.ts";
 import { memoryTool } from "./memory.ts";
+import { askUserTool } from "./askUser.ts";
+import { worktreeTool } from "./worktree.ts";
+import { routineTool } from "./routine.ts";
+import { skillTool } from "./skill.ts";
+import { loadSkills } from "../skills/loader.ts";
 
 export type { ToolContext } from "./context.ts";
 
 // Build the full toolset bound to a session context (cwd + permission gate + todo store).
 export function createTools(ctx: ToolContext): ToolSet {
+  // Registered only when skills exist — an empty catalog would be dead weight in
+  // every request.
+  const { skills } = loadSkills(ctx.cwd);
   return {
+    ...(skills.length > 0 ? { skill: skillTool(ctx, skills) } : {}),
     read: readTool(ctx),
     write: writeTool(ctx),
     edit: editTool(ctx),
@@ -30,7 +40,11 @@ export function createTools(ctx: ToolContext): ToolSet {
     web_fetch: webFetchTool(ctx),
     web_search: webSearchTool(ctx),
     save_attachment: saveAttachmentTool(ctx),
+    send_file_to_client: sendFileToClientTool(ctx),
     memory: memoryTool(ctx),
+    ask_user: askUserTool(ctx),
+    worktree: worktreeTool(ctx),
+    routine: routineTool(ctx),
   };
 }
 

package/src/tools/routine.ts

@@ -0,0 +1,110 @@
+import { tool } from "ai";
+import { z } from "zod";
+import type { ToolContext } from "./context.ts";
+import { PermissionDeniedError } from "../permissions/gate.ts";
+import { DELIVERY_CHANNELS, newRoutineId, type Routine } from "../routines/schema.ts";
+import { triggerError, computeNextRun, describeTrigger } from "../routines/trigger.ts";
+import { splitRoutineTools } from "../routines/toolSelect.ts";
+import { upsertRoutine } from "../routines/store.ts";
+import { sendToDaemon, DaemonNotRunningError } from "../daemon/ipc.ts";
+
+// Lets the agent turn a request like "summarize world news every morning" or
+// "remind me at 3pm tomorrow" into a saved routine. Creating one is a persistent
+// mutation, so it routes through the permission gate — the agent proposes, the user
+// approves, then it lands in routines.json and the running daemon picks it up.
+export function routineTool(ctx: ToolContext) {
+  return tool({
+    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; this prompts for approval before saving. Runs use a safe read/web toolset (no " +
+      "writing or shell) unless `tools` grants more.",
+    inputSchema: z.object({
+      name: z.string().describe("Short unique label, e.g. 'morning-news'."),
+      cron: z
+        .string()
+        .optional()
+        .describe("Recurring: standard 5-field cron, e.g. '0 8 * * *' for 08:00 daily. Omit for one-off."),
+      at: z
+        .string()
+        .optional()
+        .describe("One-off: ISO-8601 datetime, e.g. '2026-07-02T15:00:00'. Omit for recurring."),
+      prompt: z.string().describe("Self-contained instruction the agent runs when it fires."),
+      delivery: z
+        .array(z.enum(DELIVERY_CHANNELS))
+        .optional()
+        .describe("How to deliver the result. Defaults to ['file']. 'email' leaves the machine (opt-in)."),
+      cwd: z.string().optional().describe("Working directory for the run. Defaults to the current one."),
+      model: z.string().optional().describe("Optional 'provider:model' override."),
+      tools: z
+        .array(z.string())
+        .optional()
+        .describe(
+          "Tool allow-list: builtin names ('read') and/or MCP selectors '<server>__<tool>' or " +
+            "'<server>__*'. MCP tools run unattended with no approval prompts — grant only what " +
+            "the task needs. Omit for the default safe read/web set.",
+        ),
+    }),
+    execute: async ({ name, cron, at, prompt, delivery, cwd, model, tools }) => {
+      const err = triggerError({ cron, at });
+      if (err) return `Error: ${err}`;
+
+      const chans = delivery && delivery.length > 0 ? delivery : ["file" as const];
+      const next = computeNextRun({ cron, at });
+      const detail =
+        `${name}: ${describeTrigger({ cron, at })}` +
+        (next ? ` (next ${next.toLocaleString()})` : "") +
+        ` → ${chans.join(",")}`;
+
+      // Confirm with the user. Egress grants are flagged so the human sees them:
+      // email delivery, and any MCP tools — those run unattended under the daemon's
+      // auto-approve gate, so this approval is the only human decision they get.
+      const split = splitRoutineTools(tools);
+      const flags: string[] = [];
+      if (chans.includes("email")) flags.push("email leaves your machine");
+      if (split.mcp.length > 0) flags.push(`grants external MCP tools, unattended: ${split.mcp.join(", ")}`);
+      const decision = await ctx.gate.request({
+        tool: "routine",
+        kind: "write",
+        title: "Create routine",
+        detail: flags.length > 0 ? `${detail}  [${flags.join("] [")}]` : detail,
+        // An MCP grant must always reach the human, above bypass mode/allowlists.
+        alwaysAsk: split.mcp.length > 0,
+      });
+      if (decision === "deny") throw new PermissionDeniedError("routine");
+
+      const routine: Routine = {
+        id: newRoutineId(),
+        name,
+        cron,
+        at,
+        prompt,
+        cwd: cwd ?? ctx.cwd,
+        model,
+        delivery: chans,
+        tools,
+        enabled: true,
+        nextRun: next?.toISOString(),
+      };
+
+      // Prefer handing it to the running daemon (it validates + schedules); fall back
+      // to writing the file directly so the routine persists until the daemon starts.
+      try {
+        const res = await sendToDaemon({ cmd: "add", routine });
+        if (!res.ok) return `Error saving routine: ${res.message ?? "unknown"}`;
+        return `Created routine "${name}" (${describeTrigger({ cron, at })}). Next run ${next ? next.toLocaleString() : "unknown"}, delivery: ${chans.join(", ")}.`;
+      } catch (e) {
+        if (e instanceof DaemonNotRunningError) {
+          upsertRoutine(routine);
+          return (
+            `Saved routine "${name}" (${describeTrigger({ cron, at })}), but the scheduler daemon isn't ` +
+            `running yet, so it won't fire until you start it: run \`privateer daemon\` (or \`privateer daemon --detach\`).`
+          );
+        }
+        return `Error contacting the scheduler: ${e instanceof Error ? e.message : String(e)}`;
+      }
+    },
+  });
+}

package/src/tools/sendFileToClient.ts

@@ -0,0 +1,55 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { basename } from "node:path";
+import { tool } from "ai";
+import { z } from "zod";
+import type { ToolContext } from "./context.ts";
+import { resolveInCwd, displayPath, guardScope } from "./context.ts";
+import { mediaTypeForPath } from "../util/images.ts";
+
+// Per-file ceiling for the relay's chunked file channel; mirrors the relay
+// client's MAX_ATTACH_BYTES so the tool fails fast with a friendly message
+// instead of letting the transfer be rejected mid-flight.
+const MAX_SEND_BYTES = 10 * 1024 * 1024;
+
+export function sendFileToClientTool(ctx: ToolContext) {
+  return tool({
+    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.",
+    inputSchema: z.object({
+      path: z.string().describe("Path of the file to send, relative to cwd or absolute."),
+    }),
+    execute: async ({ path }) => {
+      if (!ctx.sendFileToController) {
+        return "Cannot send: remote access is not enabled in this session (/remote-access to enable).";
+      }
+      const abs = resolveInCwd(ctx, path);
+      if (!existsSync(abs)) return `File not found: ${displayPath(ctx, abs)}`;
+      const stat = statSync(abs);
+      if (stat.isDirectory()) return `${displayPath(ctx, abs)} is a directory — send a single file.`;
+      if (stat.size === 0) return `${displayPath(ctx, abs)} is empty — nothing to send.`;
+      if (stat.size > MAX_SEND_BYTES) {
+        return (
+          `${displayPath(ctx, abs)} is ${(stat.size / (1024 * 1024)).toFixed(1)} MB; ` +
+          `the remote channel caps at ${MAX_SEND_BYTES / (1024 * 1024)} MB per file.`
+        );
+      }
+      const blocked = await guardScope(ctx, abs, { kind: "read", title: "Send file to connected app" });
+      if (blocked) return blocked;
+
+      const bytes = readFileSync(abs);
+      const mediaType = mediaTypeForPath(abs);
+      const res = await ctx.sendFileToController({
+        name: basename(abs),
+        mediaType,
+        base64: bytes.toString("base64"),
+        size: bytes.length,
+      });
+      return res.ok
+        ? `Sent ${basename(abs)} (${bytes.length} bytes, ${mediaType}) to the connected app.`
+        : `Couldn't send ${basename(abs)}: ${res.reason ?? "unknown error"}. Is the app currently connected?`;
+    },
+  });
+}

package/src/tools/skill.ts

@@ -0,0 +1,44 @@
+import { tool } from "ai";
+import { z } from "zod";
+import type { ToolContext } from "./context.ts";
+import { loadSkills, type SkillDefinition } from "../skills/loader.ts";
+
+// Progressive disclosure for skills: the model sees only the catalog (names +
+// descriptions, embedded in this tool's description — same pattern as `task`
+// advertising sub-agents) and pulls a skill's full instructions into the
+// conversation by calling the tool. Loading a skill also unlocks reads of its
+// bundled files, which live outside cwd for user-scoped skills.
+export function skillTool(ctx: ToolContext, skills?: SkillDefinition[]) {
+  const list = skills ?? loadSkills(ctx.cwd).skills;
+  return tool({
+    description:
+      "Load a skill — a package of expert instructions for a specific kind of task. " +
+      "When a listed skill matches the user's request, load it BEFORE attempting the " +
+      "task and follow its instructions. Available skills:\n" +
+      list.map((s) => `- ${s.name}: ${s.description}`).join("\n"),
+    inputSchema: z.object({
+      skill: z.string().describe("Name of the skill to load."),
+    }),
+    execute: async ({ skill }) => {
+      const def = list.find((s) => s.name === skill);
+      if (!def) {
+        const names = list.map((s) => s.name).join(", ") || "(none)";
+        return `No skill named "${skill}". Available: ${names}.`;
+      }
+      // Bundled files (scripts/, references/, ...) sit next to SKILL.md — for a
+      // user-scoped skill that's outside cwd, so mark the directory in-scope for
+      // this session rather than prompting on every read.
+      const roots = (ctx.allowedOutsideRoots ??= []);
+      if (!roots.includes(def.dir)) roots.push(def.dir);
+      const advisory = def.allowedTools?.length
+        ? `\nDeclared allowed-tools: ${def.allowedTools.join(", ")} (advisory in this version).`
+        : "";
+      return (
+        `Skill "${def.name}" loaded (base directory: ${def.dir}). ` +
+        `Bundled files can be read with the read tool using paths under that directory.` +
+        advisory +
+        `\n\n${def.body}`
+      );
+    },
+  });
+}

package/src/tools/worktree.ts

@@ -0,0 +1,145 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { basename, resolve } from "node:path";
+import type { ToolContext } from "./context.ts";
+import { exec } from "./exec.ts";
+import { PermissionDeniedError } from "../permissions/gate.ts";
+
+const GIT_TIMEOUT = 60_000;
+
+// Strip a worktree/branch name down to a filesystem- and git-safe slug.
+function sanitizeName(name: string): string {
+  return name
+    .trim()
+    .replace(/[^A-Za-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 60);
+}
+
+// The sibling path a named worktree lives at: ../<repo>-wt-<name>.
+function worktreePath(cwd: string, slug: string): string {
+  return resolve(cwd, "..", `${basename(cwd)}-wt-${slug}`);
+}
+
+async function git(cwd: string, args: string[]) {
+  return exec("git", args, { cwd, timeoutMs: GIT_TIMEOUT });
+}
+
+interface WorktreeEntry {
+  path: string;
+  branch?: string;
+  head?: string;
+}
+
+// Parse `git worktree list --porcelain` into structured entries.
+function parseWorktrees(porcelain: string): WorktreeEntry[] {
+  const entries: WorktreeEntry[] = [];
+  let cur: WorktreeEntry | null = null;
+  for (const line of porcelain.split("\n")) {
+    if (line.startsWith("worktree ")) {
+      if (cur) entries.push(cur);
+      cur = { path: line.slice("worktree ".length) };
+    } else if (line.startsWith("branch ") && cur) {
+      cur.branch = line.slice("branch ".length).replace(/^refs\/heads\//, "");
+    } else if (line.startsWith("HEAD ") && cur) {
+      cur.head = line.slice("HEAD ".length, "HEAD ".length + 8);
+    }
+  }
+  if (cur) entries.push(cur);
+  return entries;
+}
+
+// The `worktree` tool: lets the agent develop a candidate approach in an isolated
+// git worktree (its own branch + working copy) so a risky or exploratory direction
+// never touches the main tree. Combined with `ask_user`, this is the building block
+// for "try an approach, compare the diff, keep or discard it". Mutating actions
+// (create/remove) run git and are routed through the permission gate.
+export function worktreeTool(ctx: ToolContext) {
+  return tool({
+    description:
+      "Manage git worktrees to develop a candidate approach in isolation (its own branch + " +
+      "working copy), so an exploratory or risky direction doesn't touch the main tree. " +
+      "Actions: 'create' a new worktree on a fresh branch, 'list' existing worktrees, 'remove' " +
+      "one when done. Use this to try an approach the user can later compare via its diff and " +
+      "keep or discard. The repository must be a git repo.",
+    inputSchema: z.object({
+      action: z.enum(["create", "list", "remove"]).describe("What to do."),
+      name: z
+        .string()
+        .optional()
+        .describe("Worktree/branch name for create and remove (e.g. 'redis-cache')."),
+      base: z
+        .string()
+        .optional()
+        .describe("For create: the ref to branch from (default: current HEAD)."),
+      deleteBranch: z
+        .boolean()
+        .optional()
+        .describe("For remove: also delete the worktree's branch (default false)."),
+    }),
+    execute: async ({ action, name, base, deleteBranch }) => {
+      if (action === "list") {
+        const { stdout, code } = await git(ctx.cwd, ["worktree", "list", "--porcelain"]);
+        if (code !== 0) return "Not a git repository, or `git worktree` failed.";
+        const entries = parseWorktrees(stdout.trim());
+        if (entries.length <= 1) return "No additional worktrees. Only the main working tree exists.";
+        return entries
+          .map((e) => `${e.path}${e.branch ? `  [${e.branch}]` : ""}${e.head ? `  @${e.head}` : ""}`)
+          .join("\n");
+      }
+
+      const slug = sanitizeName(name ?? "");
+      if (!slug) return "A non-empty `name` is required for this action.";
+      const path = worktreePath(ctx.cwd, slug);
+
+      if (action === "create") {
+        const args = ["worktree", "add", "-b", slug, path];
+        if (base) args.push(base);
+        const cmd = `git ${args.join(" ")}`;
+        const decision = await ctx.gate.request({
+          tool: "worktree",
+          kind: "bash",
+          title: "Create git worktree",
+          detail: cmd,
+        });
+        if (decision === "deny") throw new PermissionDeniedError("worktree");
+        const { stderr, code } = await git(ctx.cwd, args);
+        if (code !== 0) return `git worktree add failed:\n${stderr.trim()}`;
+        // Let the agent edit inside the new worktree without the confinement gate
+        // re-prompting on every file — the user just approved creating it here.
+        if (ctx.allowedOutsideRoots && !ctx.allowedOutsideRoots.includes(path)) {
+          ctx.allowedOutsideRoots.push(path);
+        }
+        return (
+          `Created worktree at ${path} on new branch '${slug}'.\n` +
+          `Work there with absolute paths under that directory; it's isolated from the main tree. ` +
+          `Compare later with: git -C "${path}" diff ${base ?? "HEAD"}`
+        );
+      }
+
+      // remove
+      const cmd = `git worktree remove ${path}${deleteBranch ? ` && git branch -D ${slug}` : ""}`;
+      const decision = await ctx.gate.request({
+        tool: "worktree",
+        kind: "bash",
+        title: "Remove git worktree",
+        detail: cmd,
+      });
+      if (decision === "deny") throw new PermissionDeniedError("worktree");
+      const rm = await git(ctx.cwd, ["worktree", "remove", path]);
+      if (rm.code !== 0) {
+        return `git worktree remove failed (commit or discard changes first, or it doesn't exist):\n${rm.stderr.trim()}`;
+      }
+      if (ctx.allowedOutsideRoots) {
+        const i = ctx.allowedOutsideRoots.indexOf(path);
+        if (i >= 0) ctx.allowedOutsideRoots.splice(i, 1);
+      }
+      let msg = `Removed worktree ${path}.`;
+      if (deleteBranch) {
+        const br = await git(ctx.cwd, ["branch", "-D", slug]);
+        msg += br.code === 0 ? ` Deleted branch '${slug}'.` : ` (branch '${slug}' not deleted: ${br.stderr.trim()})`;
+      }
+      return msg;
+    },
+  });
+}

package/src/util/images.ts

@@ -26,6 +26,41 @@ const MEDIA_TYPES: Record<string, { mediaType: string; modality: Modality }> = {
   ".mkv": { mediaType: "video/x-matroska", modality: "video" },
 };
 
+// Classify a media type into one of our binary modalities, or null when it's a
+// text-like file that should be inlined as plain text rather than attached. Used by
+// the relay path (App.tsx) to decide what to do with a file received from the app:
+// a null result means "decode and inline the text"; otherwise it's a binary
+// attachment the model reads directly.
+export function mediaModality(mediaType: string): Modality | null {
+  if (mediaType.startsWith("image/")) return "image";
+  if (mediaType === "application/pdf") return "document";
+  if (mediaType.startsWith("audio/")) return "audio";
+  if (mediaType.startsWith("video/")) return "video";
+  return null;
+}
+
+// Text-like extensions whose concrete media type matters to the app (rendering /
+// save-as). Everything else in TEXT_EXTS is close enough to text/plain.
+const TEXT_MEDIA_TYPES: Record<string, string> = {
+  ".json": "application/json",
+  ".html": "text/html",
+  ".csv": "text/csv",
+  ".xml": "application/xml",
+  ".svg": "image/svg+xml",
+};
+
+// Media type for a file at `p`, for files sent over the relay to the app: binary
+// kinds from MEDIA_TYPES, recognized text kinds as text, else octet-stream (the
+// app renders those as a generic file card).
+export function mediaTypeForPath(p: string): string {
+  const ext = extname(p).toLowerCase();
+  const meta = MEDIA_TYPES[ext];
+  if (meta) return meta.mediaType;
+  const text = TEXT_MEDIA_TYPES[ext];
+  if (text) return text;
+  return TEXT_EXTS.has(ext) ? "text/plain" : "application/octet-stream";
+}
+
 // Magic-byte checks per media type, used to reject placeholder/corrupt files at capture
 // time. The motivating case: macOS delivers a drag from a screenshot thumbnail as a
 // *file promise*, so the terminal's …/T/drop-XXXXXX/ file can be a 4-byte stub holding