@stevecastaneda/paseo-progress 0.1.0

package/server/launcher.ts

@@ -0,0 +1,97 @@
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { delimiter, dirname, join } from "node:path";
+
+export const PLUGIN_ID = "progress";
+
+// The launcher never names a plugin folder. Each run asks Paseo which copy of
+// the plugin it is running, so updates and `npm run dev` switches keep working.
+export function launcherScript(): string {
+  return `#!/usr/bin/env node
+// Written by the ${PLUGIN_ID} Paseo plugin. Runs the progress command from the
+// copy of the plugin Paseo is running now.
+const [major, minor] = process.versions.node.split(".").map(Number);
+if (major < 22 || (major === 22 && minor < 18)) {
+  console.error("paseo-progress needs Node.js 22.18 or later; this is " + process.version + ".");
+  process.exit(1);
+}
+// Not require: a package.json with "type": "module" above this folder makes Node load it as ESM.
+const { spawnSync } = process.getBuiltinModule("node:child_process");
+const { existsSync } = process.getBuiltinModule("node:fs");
+const { join } = process.getBuiltinModule("node:path");
+
+function pluginDirectory() {
+  if (process.env.PASEO_PROGRESS_PLUGIN_DIR) return process.env.PASEO_PROGRESS_PLUGIN_DIR;
+  const clis = [process.env.PASEO_BIN, "paseo", "/Applications/Paseo.app/Contents/Resources/bin/paseo"].filter(Boolean);
+  for (const cli of clis) {
+    const result = spawnSync(cli, ["plugin", "ls", "${PLUGIN_ID}", "--json"], { encoding: "utf8" });
+    if (result.error || result.status !== 0) continue;
+    try {
+      const plugin = JSON.parse(result.stdout).find((entry) => entry.id === "${PLUGIN_ID}");
+      return plugin && plugin.path;
+    } catch {
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
+// An npm install puts the plugin under node_modules, where Node won't run
+// TypeScript, so the npm package carries the command compiled to dist/.
+const directory = pluginDirectory();
+const entry = directory && [join(directory, "dist", "server", "cli.js"), join(directory, "server", "cli.ts")].find((path) => existsSync(path));
+if (!entry) {
+  console.error("The ${PLUGIN_ID} plugin is not installed in Paseo, or Paseo is not reachable. Check with: paseo plugin ls");
+  process.exit(1);
+}
+const run = spawnSync(process.execPath, [entry, ...process.argv.slice(2)], { stdio: "inherit" });
+process.exit(run.status === null ? 1 : run.status);
+`;
+}
+
+const MARKER = `Written by the ${PLUGIN_ID} Paseo plugin`;
+
+export function defaultLauncherPath(home = homedir()): string {
+  return join(home, ".local", "bin", "paseo-progress");
+}
+
+export type LauncherState = "missing" | "current" | "outdated" | "foreign";
+
+export async function launcherState(path: string): Promise<LauncherState> {
+  const current = await readFile(path, "utf8").catch(() => null);
+  if (current === null) return "missing";
+  if (current === launcherScript()) return "current";
+  return current.includes(MARKER) ? "outdated" : "foreign";
+}
+
+// Writes the launcher when it is missing or out of date. Never replaces a file
+// something else put there. Returns whether it wrote.
+export async function installLauncher(path: string): Promise<boolean> {
+  const state = await launcherState(path);
+  if (state === "current") return false;
+  if (state === "foreign") throw new Error(`${path} already exists and was not written by this plugin. Move it, or pass another path.`);
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, launcherScript());
+  await chmod(path, 0o755);
+  return true;
+}
+
+// For the panel: whether agents on the daemon host can run `paseo-progress`.
+export async function launcherStatus(path = defaultLauncherPath(), pathEnv = process.env.PATH ?? "") {
+  return {
+    path,
+    state: await launcherState(path),
+    onPath: pathEnv.split(delimiter).some((entry) => entry.replace(/\/+$/, "") === dirname(path)),
+  };
+}
+
+export async function handleLauncherStatus() {
+  return launcherStatus();
+}
+
+// Runs only when the user presses Install in the panel.
+export async function handleInstallLauncher() {
+  const path = defaultLauncherPath();
+  await installLauncher(path);
+  return launcherStatus(path);
+}

package/server/lock.ts

@@ -0,0 +1,32 @@
+import { mkdir, rm, stat } from "node:fs/promises";
+
+const RETRY_MS = 25;
+const WAIT_MS = 10_000;
+// A lock older than this was left by a command that crashed.
+const STALE_MS = 30_000;
+
+// Serializes read-then-append so two commands never hand out the same id or
+// interleave a line. mkdir is atomic, so only one process creates the folder.
+export async function withLock<T>(lockPath: string, work: () => Promise<T>): Promise<T> {
+  const started = Date.now();
+  while (true) {
+    try {
+      await mkdir(lockPath);
+      break;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      const since = await stat(lockPath).then((info) => Date.now() - info.mtimeMs, () => 0);
+      if (since > STALE_MS) {
+        await rm(lockPath, { recursive: true, force: true });
+        continue;
+      }
+      if (Date.now() - started > WAIT_MS) throw new Error(`Timed out waiting for ${lockPath}. If no other progress command is running, delete it.`);
+      await new Promise((resolve) => setTimeout(resolve, RETRY_MS + Math.random() * RETRY_MS));
+    }
+  }
+  try {
+    return await work();
+  } finally {
+    await rm(lockPath, { recursive: true, force: true });
+  }
+}

package/server/open.ts

@@ -0,0 +1,107 @@
+import type { PluginHandlerContext } from "@getpaseo/plugin/server";
+import { execFile } from "node:child_process";
+import { open, readFile, realpath, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, relative, resolve } from "node:path";
+import { promisify } from "node:util";
+import { findAttachment, imageMimeType, previewKind } from "../shared/attachments.ts";
+import { readProgress } from "./progress-file.ts";
+import { outside } from "./paths.ts";
+
+export type Opener = (path: string) => Promise<void>;
+
+// The command that opens `path` on this host: like a double-click, except
+// plain-text files go to the default browser (`browser` is its bundle id): the
+// Mac's default app for them is often an editor, or one that closes straight
+// away. The browser shows them as text.
+export function openCommand(path: string, platform: NodeJS.Platform, browser: string | null): [string, string[]] {
+  if (platform === "win32") return ["explorer", [path]];
+  if (platform !== "darwin") return ["xdg-open", [path]];
+  const toBrowser = previewKind(path) === "text";
+  return toBrowser ? ["open", ["-b", browser ?? "com.apple.Safari", path]] : ["open", [path]];
+}
+
+// The default browser from Launch Services, e.g. "com.google.chrome".
+async function defaultBrowser(): Promise<string | null> {
+  try {
+    const plist = join(homedir(), "Library/Preferences/com.apple.LaunchServices/com.apple.launchservices.secure.plist");
+    const { stdout } = await promisify(execFile)("plutil", ["-convert", "json", "-o", "-", plist]);
+    const handlers = (JSON.parse(stdout).LSHandlers ?? []) as Array<{ LSHandlerURLScheme?: string; LSHandlerRoleAll?: string }>;
+    return handlers.find((handler) => handler.LSHandlerURLScheme === "https")?.LSHandlerRoleAll ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export const systemOpener: Opener = async (path) => {
+  const browser = process.platform === "darwin" ? await defaultBrowser() : null;
+  const [command, args] = openCommand(path, process.platform, browser);
+  await promisify(execFile)(command, args);
+};
+
+// A deliverable or question attachment the agent recorded, found by reference,
+// so the panel can never reach an arbitrary path. Only files inside the
+// worktree resolve.
+async function resolveAttachment(directory: string, ref: string, verb: string): Promise<{ path: string; target: string }> {
+  const { dashboard } = await readProgress(directory);
+  const path = findAttachment(dashboard, ref)?.path;
+  if (!path) throw new Error(`No local ${ref.startsWith("Q") ? "attachment" : "deliverable"} ${ref} in this worktree.`);
+  const root = await realpath(directory);
+  const target = await realpath(resolve(root, path)).catch(() => null);
+  if (!target) throw new Error(`${path} no longer exists.`);
+  const inside = relative(root, target);
+  if (outside(inside)) throw new Error(`${path} is outside this worktree, so it was not ${verb}.`);
+  return { path, target };
+}
+
+export async function openDeliverable(directory: string, id: string, opener: Opener): Promise<{ opened: string }> {
+  const { target } = await resolveAttachment(directory, id, "opened");
+  await opener(target);
+  return { opened: target };
+}
+
+// Large enough for full-page screenshots; the image travels over the socket.
+export const MAX_PREVIEW_BYTES = 10 * 1024 * 1024;
+
+// Text past this is cut off in the preview; the full file is a click away.
+export const MAX_PREVIEW_TEXT_BYTES = 256 * 1024;
+
+export type Preview =
+  | { kind: "image"; dataUri: string; bytes: number }
+  | { kind: "text"; text: string; bytes: number; truncated: boolean };
+
+// An image (as a data URI) or a text file's contents, so any client (desktop
+// or phone) can show it without reaching the daemon host's disk.
+export async function previewDeliverable(directory: string, id: string): Promise<Preview> {
+  const { path, target } = await resolveAttachment(directory, id, "previewed");
+  const kind = previewKind(target);
+  if (!kind) throw new Error(`${path} isn't an image or text file, so it can't be previewed.`);
+  const { size } = await stat(target);
+  if (kind === "text") {
+    // Read only what's shown, so a huge log doesn't load whole.
+    const file = await open(target);
+    try {
+      const { buffer, bytesRead } = await file.read({ buffer: Buffer.alloc(Math.min(size, MAX_PREVIEW_TEXT_BYTES)), position: 0 });
+      return { kind, text: buffer.subarray(0, bytesRead).toString("utf8"), bytes: size, truncated: size > MAX_PREVIEW_TEXT_BYTES };
+    } finally {
+      await file.close();
+    }
+  }
+  if (size > MAX_PREVIEW_BYTES) throw new Error(`${path} is ${Math.round(size / 1024 / 1024)} MB, too large to preview.`);
+  const data = await readFile(target);
+  return { kind, dataUri: `data:${imageMimeType(target)};base64,${data.toString("base64")}`, bytes: size };
+}
+
+export async function handlePreviewDeliverable(
+  input: { workspaceId: string; workspaceDirectory: string; ref: string },
+  _context: PluginHandlerContext,
+) {
+  return previewDeliverable(input.workspaceDirectory, input.ref);
+}
+
+export async function handleOpenDeliverable(
+  input: { workspaceId: string; workspaceDirectory: string; ref: string },
+  _context: PluginHandlerContext,
+) {
+  return openDeliverable(input.workspaceDirectory, input.ref, systemOpener);
+}

package/server/paths.ts

@@ -0,0 +1,7 @@
+import { isAbsolute, sep } from "node:path";
+
+// Whether a path from relative(root, target) leaves the root. "..notes" is a
+// name inside it, not a step out.
+export function outside(inside: string): boolean {
+  return inside === ".." || inside.startsWith(`..${sep}`) || isAbsolute(inside);
+}

package/server/progress-file.ts

@@ -0,0 +1,141 @@
+// Everything that reads or writes a worktree's progress files: the event log
+// the command appends to, the panel-opened marker, and the .gitignore that keeps
+// both out of git. The command and the panel's RPC handlers go through here, so
+// they always agree on where the files are and how they're read.
+import { access, appendFile, mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { EMPTY_DASHBOARD, parseProgress, reduceProgress, type Dashboard, type NextIds } from "../shared/dashboard.ts";
+import { EVENT_VERSION, eventSchema, PANEL_OPENED_FILE, PROGRESS_FILE, type ProgressEvent } from "../shared/events.ts";
+import { withLock } from "./lock.ts";
+
+const SCRATCH_DIR = dirname(PROGRESS_FILE);
+const LOCK_FILE = `${PROGRESS_FILE}.lock`;
+
+// Names only this plugin's files, so they stay out of git without the user
+// editing their own .gitignore. Other files in .scratch/ are left to the repo.
+export const SCRATCH_GITIGNORE = `# Added by the progress plugin for Paseo so its files stay out of git.
+${basename(PROGRESS_FILE)}
+${basename(LOCK_FILE)}/
+${basename(PANEL_OPENED_FILE)}
+.gitignore
+`;
+
+// An event as a command builds it; `append` stamps the version and time.
+export type EventDraft = { [K in ProgressEvent["type"]]: Omit<Extract<ProgressEvent, { type: K }>, "v" | "ts"> }[ProgressEvent["type"]];
+
+// A draft the event schema rejects. The message names each bad field.
+export class InvalidEvent extends Error {}
+
+export interface ProgressRead {
+  // Whether the worktree has a progress file at all.
+  configured: boolean;
+  dashboard: Dashboard;
+  panelOpened: boolean;
+}
+
+// The parsed file per worktree, kept until its size or change time moves. The
+// file only grows, and the panel and pills read it every few seconds.
+const parsedFiles = new Map<string, { size: number; mtimeMs: number; ctimeMs: number; parsed: ReturnType<typeof parseProgress> }>();
+// Replaced file snapshots and their derived data can be collected together.
+const dashboards = new WeakMap<ReturnType<typeof parseProgress>, { dashboard: Dashboard; from: number; until: number }>();
+
+// The dashboard at `now`, for the panel, the pills and `show`. Repeated reads
+// reuse the last one until the file changes or a stale or overdue time passes.
+// Stale and overdue checks use the daemon host's clock, the same clock the
+// command stamps events with.
+export async function readProgress(root: string, now = new Date()): Promise<ProgressRead> {
+  const parsed = await readParsed(root);
+  const panelOpened = await exists(join(root, PANEL_OPENED_FILE));
+  if (parsed === null) return { configured: false, dashboard: EMPTY_DASHBOARD, panelOpened };
+  let cached = dashboards.get(parsed);
+  // A backwards clock jump must also re-evaluate stale/overdue state.
+  if (!cached || now.getTime() < cached.from || now.getTime() >= cached.until) {
+    const { dashboard, validUntil } = reduceProgress(parsed, now);
+    cached = { dashboard, from: now.getTime(), until: validUntil };
+    dashboards.set(parsed, cached);
+  }
+  return { configured: true, dashboard: cached.dashboard, panelOpened };
+}
+
+// Appends the one event `write` builds from the file as it is now. Commands
+// that run at once take turns, so each sees the others' events and no two hand
+// out the same id. `write` may throw to append nothing.
+export async function appendProgress<T>(
+  root: string,
+  now: () => Date,
+  write: (state: { dashboard: Dashboard; nextIds: NextIds }) => { event: EventDraft; result: T },
+): Promise<T> {
+  await prepareScratch(root);
+  return withLock(join(root, LOCK_FILE), async () => {
+    const text = (await readText(root)) ?? "";
+    const { dashboard, nextIds } = reduceProgress(parseProgress(text), now());
+    const { event, result } = write({ dashboard, nextIds });
+    const checked = eventSchema.safeParse({ v: EVENT_VERSION, ts: now().toISOString(), ...withoutUndefined(event) });
+    if (!checked.success) {
+      throw new InvalidEvent(checked.error.issues.map((issue) => `${issue.path.join(".") || "value"}: ${issue.message}`).join("; "));
+    }
+    // A line cut short (a killed command, a hand edit) would swallow this event, so start a new line.
+    const lead = text && !text.endsWith("\n") ? "\n" : "";
+    await appendFile(join(root, PROGRESS_FILE), `${lead}${JSON.stringify(checked.data)}\n`);
+    return result;
+  });
+}
+
+export async function markPanelOpened(root: string): Promise<void> {
+  await prepareScratch(root);
+  await writeFile(join(root, PANEL_OPENED_FILE), "");
+}
+
+// Creates .scratch/ in the worktree and, the first time, its .gitignore. An
+// existing .gitignore is the user's, so it is never touched.
+async function prepareScratch(root: string): Promise<void> {
+  const directory = join(root, SCRATCH_DIR);
+  await mkdir(directory, { recursive: true });
+  await writeFile(join(directory, ".gitignore"), SCRATCH_GITIGNORE, { flag: "wx" }).catch((error: NodeJS.ErrnoException) => {
+    if (error.code !== "EEXIST") throw error;
+  });
+}
+
+async function readText(root: string): Promise<string | null> {
+  try {
+    return await readFile(join(root, PROGRESS_FILE), "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+async function readParsed(root: string): Promise<ReturnType<typeof parseProgress> | null> {
+  const info = await stat(join(root, PROGRESS_FILE)).catch((error: NodeJS.ErrnoException) => {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  });
+  if (!info) {
+    parsedFiles.delete(root);
+    return null;
+  }
+  const cached = parsedFiles.get(root);
+  if (cached && cached.size === info.size && cached.mtimeMs === info.mtimeMs && cached.ctimeMs === info.ctimeMs) return cached.parsed;
+  // Stat before reading: if the file grows in between, the next stat won't match and it's read again.
+  const text = await readText(root);
+  if (text === null) {
+    parsedFiles.delete(root);
+    return null;
+  }
+  const parsed = parseProgress(text);
+  parsedFiles.set(root, { size: info.size, mtimeMs: info.mtimeMs, ctimeMs: info.ctimeMs, parsed });
+  return parsed;
+}
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function withoutUndefined<T extends object>(value: T): T {
+  return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined)) as T;
+}

package/server/skill.ts

@@ -0,0 +1,85 @@
+import { execFile } from "node:child_process";
+import { lstat, mkdir, readlink, symlink, unlink } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { PLUGIN_ID } from "./launcher.ts";
+
+export const SKILL_NAME = "paseo-progress";
+
+// The same three folders Paseo installs its own skills into: the shared
+// ~/.agents folder plus Claude Code's and Codex's own.
+export function defaultSkillPaths(home = homedir()): string[] {
+  return [".agents", ".claude", ".codex"].map((folder) => join(home, folder, "skills", SKILL_NAME));
+}
+
+export function skillSource(pluginDirectory: string): string {
+  return join(pluginDirectory, "skills", SKILL_NAME);
+}
+
+// The skill is a link into the copy of the plugin Paseo runs, so plugin
+// updates reach agents without reinstalling. "outdated" is a link this plugin
+// made to a copy Paseo no longer runs; "foreign" is anything else.
+export type SkillState = "missing" | "current" | "outdated" | "foreign";
+
+export async function skillState(path: string, pluginDirectory: string): Promise<SkillState> {
+  const stats = await lstat(path).catch(() => null);
+  if (!stats) return "missing";
+  if (!stats.isSymbolicLink()) return "foreign";
+  const target = resolve(dirname(path), await readlink(path));
+  if (target === skillSource(pluginDirectory)) return "current";
+  return basename(target) === SKILL_NAME && basename(dirname(target)) === "skills" ? "outdated" : "foreign";
+}
+
+// Links the skill wherever it is missing or points at an old copy of the
+// plugin. Leaves alone anything else at those paths. Returns whether it wrote.
+export async function installSkill(paths: string[], pluginDirectory: string): Promise<boolean> {
+  const states = await Promise.all(paths.map((path) => skillState(path, pluginDirectory)));
+  if (states.every((state) => state === "foreign")) throw new Error(`${paths.join(", ")} already exist and were not linked by this plugin.`);
+  let wrote = false;
+  for (const [index, path] of paths.entries()) {
+    if (states[index] !== "missing" && states[index] !== "outdated") continue;
+    if (states[index] === "outdated") await unlink(path);
+    await mkdir(dirname(path), { recursive: true });
+    await symlink(skillSource(pluginDirectory), path, "dir");
+    wrote = true;
+  }
+  return wrote;
+}
+
+// "current" once every folder that can take the link has it.
+export async function skillStatus(paths: string[], pluginDirectory: string) {
+  const targets = await Promise.all(paths.map(async (path) => ({ path, state: await skillState(path, pluginDirectory) })));
+  const states = targets.map((target) => target.state);
+  const state: SkillState = states.includes("outdated") ? "outdated"
+    : states.includes("missing") ? "missing"
+    : states.includes("current") ? "current" : "foreign";
+  return { state, targets };
+}
+
+// The server bundle doesn't know its own folder, so ask Paseo, the same way
+// the launcher does.
+export async function findPluginDirectory(): Promise<string> {
+  const clis = [process.env.PASEO_BIN, "paseo", "/Applications/Paseo.app/Contents/Resources/bin/paseo"].filter((cli): cli is string => Boolean(cli));
+  for (const cli of clis) {
+    try {
+      const { stdout } = await promisify(execFile)(cli, ["plugin", "ls", PLUGIN_ID, "--json"]);
+      const plugin = (JSON.parse(stdout) as Array<{ id: string; path?: string }>).find((entry) => entry.id === PLUGIN_ID);
+      if (plugin?.path) return plugin.path;
+    } catch {
+      // Try the next place the paseo CLI might be.
+    }
+  }
+  throw new Error("Could not ask Paseo where this plugin is installed.");
+}
+
+export async function handleSkillStatus() {
+  return skillStatus(defaultSkillPaths(), await findPluginDirectory());
+}
+
+// Runs only when the user presses Install skill in the panel.
+export async function handleInstallSkill() {
+  const pluginDirectory = await findPluginDirectory();
+  await installSkill(defaultSkillPaths(), pluginDirectory);
+  return skillStatus(defaultSkillPaths(), pluginDirectory);
+}

package/shared/attachments.ts

@@ -0,0 +1,100 @@
+// Anything the user can open from the dashboard: a deliverable ("D3") or a
+// file on a question ("Q7.2", counting from 1). The panel lists them and the
+// server finds them by the same reference, so both read it from here.
+import type { Dashboard, Deliverable, Question } from "./dashboard.ts";
+
+export interface Attachment {
+  ref: string;
+  title: string;
+  path?: string;
+  url?: string;
+  // What the agent said a deliverable is. Question files don't have one.
+  kind?: Deliverable["kind"];
+}
+
+export function deliverableAttachment(deliverable: Deliverable): Attachment {
+  return { ref: deliverable.id, title: deliverable.title, path: deliverable.path, url: deliverable.url, kind: deliverable.kind };
+}
+
+export function questionAttachments(question: Question): Attachment[] {
+  return question.files.map((file, index) => ({
+    ref: `${question.id}.${index + 1}`,
+    title: file.label ?? (file.path ?? file.url ?? "").replace(/[\\/]+$/, "").split(/[\\/]/).pop() ?? "",
+    path: file.path,
+    url: file.url,
+  }));
+}
+
+// The attachment a reference names, or null when it names nothing.
+export function findAttachment(dashboard: Dashboard, ref: string): Attachment | null {
+  const question = ref.match(/^(Q\d+)\./);
+  if (question) {
+    const found = [...dashboard.questions.open, ...dashboard.questions.answered].find((candidate) => candidate.id === question[1]);
+    return (found && questionAttachments(found).find((attachment) => attachment.ref === ref)) ?? null;
+  }
+  const deliverable = dashboard.deliverables.find((candidate) => candidate.id === ref);
+  return deliverable ? deliverableAttachment(deliverable) : null;
+}
+
+const IMAGE_TYPES: Record<string, string> = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".svg": "image/svg+xml",
+};
+
+// Plain text shown as-is in the preview dialog, and opened in the browser on
+// the host. HTML is left to the browser either way.
+const TEXT_EXTENSIONS = new Set([".md", ".markdown", ".mdx", ".txt", ".log", ".json", ".jsonl", ".yaml", ".yml", ".csv"]);
+
+function extension(path: string): string | null {
+  return path.toLowerCase().match(/\.[a-z0-9]+$/)?.[0] ?? null;
+}
+
+// The image type of a path by its extension, or null when it isn't an image.
+export function imageMimeType(path: string): string | null {
+  return IMAGE_TYPES[extension(path) ?? ""] ?? null;
+}
+
+export function previewKind(path: string): "image" | "text" | null {
+  if (imageMimeType(path)) return "image";
+  return TEXT_EXTENSIONS.has(extension(path) ?? "") ? "text" : null;
+}
+
+// Whether the preview dialog can show it. Only a browser draws SVG: Paseo's
+// desktop app can, the phone apps' image view can't, so there an SVG opens on
+// the host like any other file.
+export function canPreview(attachment: Attachment, where: { browser: boolean }): boolean {
+  if (!attachment.path) return false;
+  const kind = previewKind(attachment.path);
+  if (kind === "image" && extension(attachment.path) === ".svg") return where.browser;
+  return kind !== null;
+}
+
+const KIND_ICON: Record<NonNullable<Deliverable["kind"]>, string> = {
+  file: "File",
+  folder: "Folder",
+  report: "FileChartColumn",
+  screenshot: "Image",
+  link: "Globe",
+};
+
+// One icon per attachment, the same on every screen. What the agent called a
+// deliverable wins; otherwise the file itself decides.
+export function attachmentIcon(attachment: Attachment): string {
+  if (attachment.kind && attachment.kind !== "file") return KIND_ICON[attachment.kind];
+  if (attachment.url) return "Globe";
+  if (!attachment.path) return "File";
+  const kind = previewKind(attachment.path);
+  return kind === "image" ? "Image" : kind === "text" ? "FileText" : /[\/]$/.test(attachment.path) ? "Folder" : "File";
+}
+
+// The short name people recognize: a file or folder's own name, or a link's site.
+export function shortName(attachment: Attachment): string {
+  if (attachment.url) {
+    try { return new URL(attachment.url).host.replace(/^www\./, ""); } catch { return attachment.url; }
+  }
+  return (attachment.path ?? "").replace(/[\\/]+$/, "").split(/[\\/]/).pop() ?? "";
+}