@bacnh85/pi-attachments 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+## 0.2.0
+
+- **Readable path references by default (read on demand).** `[[attach:name]]`
+  tokens now resolve to `📎 /abs/path` chips — text files are no longer dumped
+  into the message as `<file>` content blocks. The model reads the referenced
+  file on demand via its `read` tool (works for absolute paths + images
+  natively), keeping the transcript tidy and eliminating per-turn token
+  re-reads of large content.
+- Images keep attaching a real `ImageContent` part alongside the 📎 chip.
+- `inlineTextFiles` now defaults to `false`; set `true` to restore the old
+  `<file>`-block inlining (Claude Code `@file` style).
+
+## 0.1.0
+
+Initial release.
+
+- **Attachment chips for drag-drop / clipboard paste**: dropping file(s) into the
+  terminal (or `alt+shift+v` for Finder/Explorer-copied files) no longer dumps
+  raw paths into your prompt. Path-only pastes are intercepted before the
+  editor and shown as a tidy 📎 chip list above the input; on submit the chips
+  become real attachments.
+- **Image path → real attachment**: the `input` hook finds existing image file paths
+  (png/jpg/jpeg/webp/gif) in submitted text — including the `/tmp/pi-clipboard-*.png`
+  paths Pi's Ctrl+V paste writes and the paths terminals paste on file drag-drop —
+  and converts them into real `ImageContent` parts, so the model sees the image
+  instead of just a path string.
+- **Text-file inlining**: existing absolute text-file paths under
+  `attachments.maxInlineBytes` (default 100KB) are replaced with
+  `<file name="...">…</file>` blocks (same convention as pi's `@file` CLI args).
+- **Paste files from clipboard**: `alt+shift+v` (configurable via
+  `attachments.pasteFileShortcut`) reads file references from the OS clipboard
+  (macOS Finder, Windows Explorer, Linux X11/Wayland file managers) and pastes
+  their paths into the editor.
+- Settings under the `attachments` key in `~/.pi/agent/settings.json`:
+  `inlineTextFiles` (bool, default true), `maxInlineBytes` (default 100000),
+  `pasteFileShortcut` (default `"alt+shift+v"`).

package/README.md

@@ -0,0 +1,96 @@
+# @bacnh85/pi-attachments
+
+Image and file attachments for [Pi](https://github.com/earendil-works/pi) — make
+pasted and drag-dropped files reach the model as real content, not dead path text.
+
+## The problem
+
+Pi's Ctrl+V image paste writes the clipboard image to a temp file and inserts
+the **path as text** into the editor. Terminals' file drag-drop (iTerm2,
+Terminal.app, WezTerm, kitty, …) pastes the dropped file's path as text too.
+Nothing converts that path into an attachment — the model receives only the
+path string and must spend a turn calling `read` (and often doesn't). Pasting
+files copied in Finder/Explorer does nothing at all.
+
+## Install
+
+```bash
+pi install @bacnh85/pi-attachments
+```
+
+## What it does
+
+1. **Attachment chips (drag-drop / clipboard paste).** Dropping file(s) into
+   the terminal — or pressing `alt+shift+v` with files copied in Finder /
+   Explorer / a Linux file manager — inserts filename tokens into your prompt
+   and shows a chip list above the editor instead of dumping raw paths:
+   ```
+   📎 demo.jpeg · C601079.pdf
+   [[attach:demo.jpeg]] what's wrong in this screenshot?
+   ```
+   On submit the tokens resolve to real, readable references. Remove one by
+   deleting its `[[attach:...]]` token from the prompt — the chip disappears
+   immediately and the file is not sent.
+2. **Readable path references (default).** A dropped/pasted file resolves to
+   a `📎 /abs/path` chip — never a content dump. The transcript stays tidy
+   and the model reads the file on demand with its `read` tool (pi's read
+   handles absolute paths and images natively). Zero per-turn token cost.
+   - text files → `📎 /path/to/file.ts`
+   - images → `📎 /path/to/img.png` **plus** a real `ImageContent` attachment
+     (requires a vision-capable model; pi shows "(image omitted: model does
+     not support images)" otherwise)
+3. **Text-file inlining (opt-in).** With `inlineTextFiles: true`, absolute
+   text-file paths are inlined as `<file name="...">…</file>` content blocks
+   (pi's `@file` CLI convention) instead of 📎 path chips. Claude Code `@file`
+   style — convenient, but the content is re-read on every turn, so it is
+   off by default.
+4. **Paste files from the clipboard.** `alt+shift+v` reads file references
+   copied in Finder / Explorer / a Linux file manager and queues them as
+   chips; the input hook does the rest.
+
+## Configuration
+
+`~/.pi/agent/settings.json`:
+
+```json
+{
+  "attachments": {
+    "inlineTextFiles": false,
+    "maxInlineBytes": 100000,
+    "pasteFileShortcut": "alt+shift+v"
+  }
+}
+```
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `inlineTextFiles` | `false` | Inline text files as `<file>` blocks instead of 📎 path chips |
+| `maxInlineBytes` | `100000` | Max file size for text inlining (`inlineTextFiles` mode) |
+| `pasteFileShortcut` | `"alt+shift+v"` | Keybinding for paste-file-from-clipboard |
+
+## Notes
+
+- **Removing an attachment**: delete its `[[attach:filename]]` token from the
+  prompt — the chip disappears immediately and the file is not sent. Clickable
+  (x) chips aren't possible: the editor owns keyboard focus and extension
+  widgets don't receive mouse events, so token-editing is the removal path.
+  Same-basename files get unique names (`demo.jpeg`, `demo-2.jpeg`).
+- **Tokens survive restarts**: each drop is remembered in
+  `~/.pi/agent/pi-attachments.json` (name → absolute path, newest 200 kept),
+  so referencing `[[attach:foo.ts]]` in a later session still resolves to the
+  dropped file — no dead tokens.
+- Conservative matching: prose like "see main.rs" or "the .jpg extension" never
+  triggers anything — images require an existing file with an image extension,
+  text inlining requires an absolute existing path.
+- pi core auto-resizes attached images (see the `images.autoResize` setting).
+- kitty's OSC 72 drag-drop protocol is not supported (requires raw stdin access
+  that extensions don't have); kitty <0.47 drops paths, which work.
+
+## Development
+
+```bash
+cd pi-attachments
+npm install
+npm test          # mocha + tsx
+npm run typecheck
+```

package/extensions/index.ts

@@ -0,0 +1,198 @@
+/**
+ * pi-attachments — real attachments from pasted/dropped file paths.
+ *
+ * Drag-drop / clipboard-paste flow:
+ * 1. onTerminalInput intercepts the bracketed paste BEFORE the editor and,
+ *    when the payload is file paths only, swaps it for [[attach:name]] tokens
+ *    and shows a 📎 chip list above the editor (widget).
+ * 2. On submit, the input hook resolves tokens:
+ *    - images → 📎 path text + real ImageContent parts
+ *    - text files → 📎 path text (default; model reads on demand via read)
+ *      or <file> content blocks (inlineTextFiles opt-in)
+ * The user's chat line shows only the tidy 📎 chips.
+ */
+
+import type { ExtensionAPI, InputEvent, TerminalInputHandler } from "@earendil-works/pi-coding-agent";
+import { detectSupportedImageMimeTypeFromFile } from "@earendil-works/pi-coding-agent";
+import { readFile, stat } from "node:fs/promises";
+import { readClipboardFilePaths } from "./lib/clipboard-files";
+import { absolutePathSpans, extractImagePaths } from "./lib/paths";
+import { lookup, remember } from "./lib/registry";
+import { loadSettings } from "./lib/settings";
+import { AttachmentTray } from "./lib/tray";
+
+const BRACKETED_PASTE = /^\x1b\[200~([\s\S]*?)\x1b\[201~$/;
+
+/** Split on whitespace NOT preceded by a backslash, so "/a/with\\ space.png" stays one token. */
+function splitPathTokens(payload: string): string[] {
+  return payload.trim().split(/(?<!\\)\s+/).filter(Boolean);
+}
+
+/** Paste payload is all path-like tokens (optionally escaped spaces)? */
+function looksLikePathPayload(payload: string): boolean {
+  const tokens = splitPathTokens(payload);
+  return tokens.length > 0 && tokens.every((t) => t.replace(/\\ /g, " ").startsWith("/"));
+}
+
+export default function piAttachments(pi: ExtensionAPI): void {
+  const settings = loadSettings();
+  const tray = new AttachmentTray();
+  let trayUi: { setWidget: (key: string, lines: string[]) => void } | undefined;
+
+  const updateWidget = () => {
+    trayUi?.setWidget("pi-attachments", tray.render());
+  };
+
+  // 1. Intercept path-only bracketed pastes → tokens + chip widget.
+  //    onTerminalInput fires for EVERY keystroke, so we also keep the chip
+  //    list in sync for free: if the user deletes a [[attach:N]] token from
+  //    the prompt, its chip disappears immediately (and the file is not sent).
+  const onPaste: TerminalInputHandler = (data) => {
+    if (tray.size > 0) {
+      const before = tray.size;
+      tray.prune(editorText?.() ?? "");
+      if (tray.size !== before) updateWidget();
+    }
+    const m = data.match(BRACKETED_PASTE);
+    if (!m || !looksLikePathPayload(m[1])) return undefined;
+    const tokens: string[] = [];
+    for (const raw of splitPathTokens(m[1])) {
+      const item = tray.add(raw.replace(/\\ /g, " "));
+      remember(item.name, item.path); // survive session restarts
+      tokens.push(item.token);
+    }
+    updateWidget();
+    return { data: tokens.join(" ") };
+  };
+  // Captured at session_start — lets onPaste read the editor for prune-sync.
+  let editorText: (() => string) | undefined;
+  pi.on("session_start", async (_event, ctx) => {
+    trayUi = ctx.ui;
+    editorText = (ctx.ui as any).getEditorText?.bind(ctx.ui);
+    ctx.ui.onTerminalInput?.(onPaste);
+    updateWidget();
+  });
+
+  // 2. On submit: resolve [[attach:name]] tokens → real content.
+  pi.on("input", async (event: InputEvent, ctx) => {
+    if (event.source === "extension") return; // don't reprocess our own sends
+
+    // Prune tray items whose tokens the user deleted from the editor.
+    tray.prune(ctx?.ui?.getEditorText?.() ?? event.text ?? "");
+
+    const raw = event.text ?? "";
+    if (!raw.trim()) {
+      updateWidget();
+      return;
+    }
+
+    const images: Array<{ type: "image"; data: string; mimeType: string }> = [...(event.images ?? [])];
+    const attachedImages = new Set<string>(); // paths already attached via tokens
+    let text = raw;
+
+    // a. Resolve [[attach:name]] tokens (tray first, then persistent registry).
+    for (const m of raw.matchAll(/\[\[attach:([^\]]+)\]\]/g)) {
+      const token = m[0];
+      const name = m[1];
+      if (!text.includes(token)) continue; // duplicate token already replaced
+      const trayItem = tray.resolve(raw).find((i) => i.token === token);
+      const path = trayItem?.path ?? lookup(name);
+      if (!path) continue; // unknown token — leave as-is for the model
+
+      const mimeType = await detectSupportedImageMimeTypeFromFile(path).catch(() => null);
+      if (mimeType) {
+        if (!attachedImages.has(path)) {
+          // Distinct tokens may resolve to the same path (same file dropped twice) — attach once.
+          try {
+            const content = await readFile(path);
+            images.push({ type: "image", data: content.toString("base64"), mimeType });
+            attachedImages.add(path);
+          } catch {
+            /* unreadable → skip */
+          }
+        }
+        text = text.split(token).join(`📎 ${path}`);
+        continue;
+      }
+
+      // Non-image: inline as <file> only when inlineTextFiles is on and size allows;
+      // otherwise resolve to a 📎 path the model reads on demand.
+      if (settings.inlineTextFiles) {
+        try {
+          const s = await stat(path);
+          if (s.size <= settings.maxInlineBytes) {
+            const content = (await readFile(path, "utf-8")).replace(/^\uFEFF/, "").replace(/\n$/, "");
+            text = text.split(token).join(`<file name="${path}">\n${content}\n</file>`);
+            continue;
+          }
+        } catch {
+          /* fall through to 📎 path */
+        }
+      }
+      text = text.split(token).join(`📎 ${path}`);
+    }
+
+    // b. Existing image paths typed elsewhere in the message → attach too.
+    for (const p of extractImagePaths(text)) {
+      if (attachedImages.has(p)) continue;
+      try {
+        const mimeType = await detectSupportedImageMimeTypeFromFile(p);
+        if (!mimeType) continue;
+        const content = await readFile(p);
+        images.push({ type: "image", data: content.toString("base64"), mimeType });
+      } catch {
+        /* unreadable file → skip */
+      }
+    }
+
+    // c. Text-path inlining (opt-in old behavior): absolute text-file paths in
+    //    the message → <file> blocks. Spans come from one greedy regex pass
+    //    (disjoint matches), applied right-to-left so earlier spans stay valid.
+    if (settings.inlineTextFiles) {
+      const replacements: Array<{ start: number; end: number; block: string }> = [];
+      for (const span of absolutePathSpans(text)) {
+        try {
+          const s = await stat(span.path);
+          if (s.size > settings.maxInlineBytes) continue;
+          const content = (await readFile(span.path, "utf-8")).replace(/^\uFEFF/, "").replace(/\n$/, ""); // stripBom + trailing newline
+          replacements.push({ start: span.start, end: span.end, block: `<file name="${span.path}">\n${content}\n</file>` });
+        } catch {
+          /* unreadable file → skip */
+        }
+      }
+      if (replacements.length) {
+        replacements.sort((a, b) => b.start - a.start);
+        for (const r of replacements) {
+          text = text.slice(0, r.start) + r.block + text.slice(r.end);
+        }
+      }
+    }
+
+    // Message sent — the chip list is consumed; hide the widget.
+    if (tray.size > 0 && tray.expand(raw) !== raw) tray.clear();
+    updateWidget();
+
+    if (text === raw && images.length === (event.images?.length ?? 0)) return;
+    return { action: "transform", text, images };
+  });
+
+  // 3. Clipboard file paste shortcut → queue into the tray as tokens.
+  // ponytail: settings string → KeyId cast; a bad key just never matches (pi's keybinding parser ignores unknown ids)
+  pi.registerShortcut(settings.pasteFileShortcut as Parameters<ExtensionAPI["registerShortcut"]>[0], {
+    description: "Paste file(s) from clipboard as attachments",
+    handler: async (ctx) => {
+      const paths = await readClipboardFilePaths();
+      if (paths.length === 0) {
+        ctx.ui.notify("No files in clipboard", "info");
+        return;
+      }
+      const tokens = paths.map((p) => {
+        const item = tray.add(p);
+        remember(item.name, item.path); // survive session restarts
+        return item.token;
+      });
+      ctx.ui.pasteToEditor(tokens.join(" "));
+      updateWidget();
+    },
+  });
+}

package/extensions/lib/clipboard-files.ts

@@ -0,0 +1,79 @@
+/**
+ * Read file paths (not bytes) from the OS clipboard.
+ *
+ * Each platform exposes copied files as file URLs / file lists:
+ * - macOS:  «class furl» via osascript (Finder "Copy")
+ * - Windows: FileDropList via PowerShell (Explorer "Copy")
+ * - Linux:  text/uri-list (xclip / wl-paste), gnome-copied-files fallback
+ *
+ * Missing tools or an empty (file-less) clipboard yield [] — never throws.
+ */
+
+import { execFile } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+
+const run = promisify(execFile);
+
+export async function readClipboardFilePaths(): Promise<string[]> {
+  try {
+    if (process.platform === "darwin") return await readMac();
+    if (process.platform === "win32") return await readWindows();
+    return await readLinux();
+  } catch {
+    return [];
+  }
+}
+
+async function readMac(): Promise<string[]> {
+  // ponytail: single file only; AppleScript repeat-loop if multi-file copies matter
+  const { stdout } = await run("osascript", ["-e", 'POSIX path of (the clipboard as «class furl»)'], { timeout: 3000 });
+  return [stdout.trim()].filter(Boolean);
+}
+
+async function readWindows(): Promise<string[]> {
+  const { stdout } = await run(
+    "powershell",
+    ["-NoProfile", "-STA", "-Command", "(Get-Clipboard -Format FileDropList) -join ';'"],
+    { timeout: 5000 },
+  );
+  return stdout.split(";").map((p) => p.trim()).filter(Boolean);
+}
+
+async function readLinux(): Promise<string[]> {
+  const isWayland = Boolean(process.env.WAYLAND_DISPLAY) || process.env.XDG_SESSION_TYPE === "wayland";
+  const targets: Array<{ cmd: string; args: string[] }> = isWayland
+    ? [
+        { cmd: "wl-paste", args: ["--type", "text/uri-list"] },
+        { cmd: "wl-paste", args: ["--type", "x-special/gnome-copied-files"] },
+      ]
+    : [
+        { cmd: "xclip", args: ["-selection", "clipboard", "-t", "text/uri-list", "-o"] },
+        { cmd: "xclip", args: ["-selection", "clipboard", "-t", "x-special/gnome-copied-files", "-o"] },
+      ];
+  for (const t of targets) {
+    try {
+      const { stdout } = await run(t.cmd, t.args, { timeout: 2000 });
+      const paths = parseUriList(stdout);
+      if (paths.length) return paths;
+    } catch {
+      /* try next target */
+    }
+  }
+  return [];
+}
+
+/** Parse `file:///a%20b` lines (uri-list) or `copy\nfile:///...` (gnome-copied-files). */
+export function parseUriList(raw: string): string[] {
+  const out: string[] = [];
+  for (const line of raw.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("file:///") && !trimmed.startsWith("file://localhost/")) continue;
+    try {
+      out.push(fileURLToPath(trimmed));
+    } catch {
+      /* skip malformed uri */
+    }
+  }
+  return out;
+}

package/extensions/lib/paths.ts

@@ -0,0 +1,72 @@
+/**
+ * File-path extraction from submitted input text.
+ *
+ * Conservative by design: images match any existing path with an image
+ * extension; text files must be absolute paths (drag-drop and clipboard
+ * always produce absolute paths — prose mentions like "see main.rs" never
+ * match).
+ */
+
+import { statSync } from "node:fs";
+// Token may contain backslash-escaped spaces ("with\ space.png" — the form
+// terminals paste on file drops); the escaped form is unescaped before fs access.
+const IMAGE_RE = /[^\s"']+(?:\\ [^\s"']+)*\.(?:png|jpe?g|webp|gif)\b/gi;
+/** Absolute-path token regex: slash segments whose chars may include backslash-escaped spaces (terminal drop form). */
+export const ABSOLUTE_PATH_RE = /(?:\/(?:[\w.@+-]|\\ )+)+/g;
+
+/** A matched absolute-path token: unescaped path plus its literal span in the text. */
+export interface AbsolutePathSpan {
+  path: string;
+  /** Start of the literal match (incl. any `\ ` escapes) in the source text. */
+  start: number;
+  /** End of the literal match. */
+  end: number;
+}
+
+/** All distinct existing-file image paths referenced in text (order-preserving). */
+export function extractImagePaths(text: string): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const match of text.matchAll(IMAGE_RE)) {
+    const p = unescape(match[0]);
+    if (seen.has(p)) continue;
+    if (!isFile(p)) continue;
+    seen.add(p);
+    out.push(p);
+  }
+  return out;
+}
+
+/** Distinct existing absolute non-image file paths referenced in text. */
+export function extractTextFilePaths(text: string): string[] {
+  return [...new Set(absolutePathSpans(text).map((s) => s.path))];
+}
+
+/**
+ * Existing absolute non-image path tokens with their literal text spans.
+ * One greedy regex pass yields disjoint matches, so a span can never be the
+ * prefix of another (e.g. /a/b inside /a/b.c); replacement can therefore use
+ * the spans directly, right-to-left.
+ */
+export function absolutePathSpans(text: string): AbsolutePathSpan[] {
+  const out: AbsolutePathSpan[] = [];
+  for (const match of text.matchAll(ABSOLUTE_PATH_RE)) {
+    const p = unescape(match[0]);
+    if (/\.(?:png|jpe?g|webp|gif)$/i.test(p)) continue; // images are handled separately
+    if (!isFile(p)) continue;
+    out.push({ path: p, start: match.index, end: match.index + match[0].length });
+  }
+  return out;
+}
+
+function unescape(p: string): string {
+  return p.replace(/\\ /g, " ");
+}
+
+function isFile(p: string): boolean {
+  try {
+    return statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}

package/extensions/lib/registry.ts

@@ -0,0 +1,57 @@
+/**
+ * Persistent token→path registry: survives session restarts so an
+ * [[attach:file.ts]] token pasted/referenced in a LATER session still
+ * resolves to the dropped file's absolute path.
+ *
+ * Stored at <agentDir>/pi-attachments.json (non-secret: names + paths only),
+ * capped at REGISTRY_MAX entries (oldest evicted).
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+const REGISTRY_MAX = 200;
+
+export function registryPath(): string {
+  const dir = process.env.PI_CODING_AGENT_DIR || join(homedir(), ".pi", "agent");
+  return join(dir, "pi-attachments.json");
+}
+
+type Registry = Record<string, string>; // name → absolute path
+
+function load(): Registry {
+  const p = registryPath();
+  if (!existsSync(p)) return {};
+  try {
+    const j = JSON.parse(readFileSync(p, "utf-8"));
+    return j && typeof j === "object" ? j : {};
+  } catch {
+    return {};
+  }
+}
+
+function save(reg: Registry): void {
+  // Evict oldest (first-inserted) entries beyond the cap.
+  const keys = Object.keys(reg);
+  if (keys.length > REGISTRY_MAX) {
+    for (const k of keys.slice(0, keys.length - REGISTRY_MAX)) delete reg[k];
+  }
+  // Atomic write (tmp + rename): a crash mid-write never leaves a truncated
+  // registry, and a fresh PI_CODING_AGENT_DIR gets created on first save.
+  const p = registryPath();
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(`${p}.tmp`, JSON.stringify(reg, null, 2));
+  renameSync(`${p}.tmp`, p);
+}
+
+export function remember(name: string, path: string): void {
+  const reg = load();
+  delete reg[name]; // re-insert at the end (most recent)
+  reg[name] = path;
+  save(reg);
+}
+
+export function lookup(name: string): string | undefined {
+  return load()[name];
+}

package/extensions/lib/settings.ts

@@ -0,0 +1,43 @@
+/**
+ * Settings from the `attachments` key of Pi's settings.json
+ * (~/.pi/agent/settings.json, or PI_CODING_AGENT_DIR). Non-secret only.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export interface AttachmentsSettings {
+  /**
+   * When true, text-file attachments are inlined as <file> blocks (Claude Code
+   * @file style — content dumped into context, re-read every turn).
+   * When false (default), they resolve to a 📎 path the model reads on demand.
+   */
+  inlineTextFiles: boolean;
+  /** Max bytes for text-file inlining (inlineTextFiles mode only). Default 100_000. */
+  maxInlineBytes: number;
+  /** Keybinding for paste-file-from-clipboard. Default "alt+shift+v". */
+  pasteFileShortcut: string;
+}
+
+export const DEFAULTS: AttachmentsSettings = {
+  inlineTextFiles: false,
+  maxInlineBytes: 100_000,
+  pasteFileShortcut: "alt+shift+v",
+};
+
+export function loadSettings(): AttachmentsSettings {
+  const dir = process.env.PI_CODING_AGENT_DIR || join(homedir(), ".pi", "agent");
+  const p = join(dir, "settings.json");
+  if (!existsSync(p)) return { ...DEFAULTS };
+  try {
+    const raw = JSON.parse(readFileSync(p, "utf-8"))?.attachments ?? {};
+    return {
+      inlineTextFiles: typeof raw.inlineTextFiles === "boolean" ? raw.inlineTextFiles : DEFAULTS.inlineTextFiles,
+      maxInlineBytes: typeof raw.maxInlineBytes === "number" && raw.maxInlineBytes > 0 ? raw.maxInlineBytes : DEFAULTS.maxInlineBytes,
+      pasteFileShortcut: typeof raw.pasteFileShortcut === "string" && raw.pasteFileShortcut ? raw.pasteFileShortcut : DEFAULTS.pasteFileShortcut,
+    };
+  } catch {
+    return { ...DEFAULTS };
+  }
+}

package/extensions/lib/tray.ts

@@ -0,0 +1,71 @@
+/**
+ * Pending-attachment tray: holds files queued by drag-drop paste / clipboard
+ * paste until submit. The tray renders as a single chip line above the editor;
+ * on submit the input hook swaps the [[attach:name]] tokens for real content.
+ */
+
+import { basename } from "node:path";
+
+export interface PendingAttachment {
+  /** [[attach:name]] token inserted into the editor text (filename-based). */
+  token: string;
+  path: string;
+  /** Display name used inside the token (unique across the tray). */
+  name: string;
+}
+
+export class AttachmentTray {
+  private items: PendingAttachment[] = [];
+
+  add(path: string): PendingAttachment {
+    const name = this.uniqueName(basename(path));
+    const item = { token: `[[attach:${name}]]`, path, name };
+    this.items.push(item);
+    return item;
+  }
+
+  /** Resolve tokens still present in submitted text; returns kept items in order. */
+  resolve(text: string): PendingAttachment[] {
+    return this.items.filter((i) => text.includes(i.token));
+  }
+
+  /** Replace every live [[attach:name]] token in text with the real path (for the input hook). */
+  expand(text: string): string {
+    let out = text;
+    for (const i of this.items) {
+      if (out.includes(i.token)) out = out.split(i.token).join(i.path);
+    }
+    return out;
+  }
+
+  /** Drop items whose tokens are gone from the editor (user deleted them). */
+  prune(editorText: string): void {
+    this.items = this.items.filter((i) => editorText.includes(i.token));
+  }
+
+  clear(): void {
+    this.items = [];
+  }
+
+  get size(): number {
+    return this.items.length;
+  }
+
+  /** Single chip line: 📎 demo.jpeg · C601079.pdf */
+  render(): string[] {
+    if (this.items.length === 0) return [];
+    return [`📎 ${this.items.map((i) => i.name).join(" · ")}`];
+  }
+
+  /** First basename is used as-is; duplicates get -2, -3… before the extension. */
+  private uniqueName(base: string): string {
+    if (!this.items.some((i) => i.name === base)) return base;
+    const dot = base.lastIndexOf(".");
+    const stem = dot > 0 ? base.slice(0, dot) : base;
+    const ext = dot > 0 ? base.slice(dot) : "";
+    for (let n = 2; ; n++) {
+      const candidate = `${stem}-${n}${ext}`;
+      if (!this.items.some((i) => i.name === candidate)) return candidate;
+    }
+  }
+}

package/extensions/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@bacnh85/pi-attachments",
+  "version": "0.2.0",
+  "description": "Image and file attachments for Pi \u2014 converts pasted/dropped file paths into real image attachments, inlines text files, and pastes clipboard file references.",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/bacnh85/pi-extensions/tree/main/pi-attachments",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bacnh85/pi-extensions.git",
+    "directory": "pi-attachments"
+  },
+  "bugs": {
+    "url": "https://github.com/bacnh85/pi-extensions/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "attachments",
+    "images",
+    "clipboard"
+  ],
+  "files": [
+    "README.md",
+    "CHANGELOG.md",
+    "extensions/index.ts",
+    "extensions/package.json",
+    "extensions/lib/"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/index.ts"
+    ]
+  },
+  "scripts": {
+    "test": "cd extensions && npx mocha",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.84.3 <0.85.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.3",
+    "@earendil-works/pi-ai": "^0.84.0",
+    "@earendil-works/pi-tui": "^0.84.3",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^20.19.43",
+    "chai": "^4.5.0",
+    "mocha": "^11.8.0",
+    "tsx": "^4.22.4",
+    "typescript": "^5.9.3"
+  },
+  "overrides": {
+    "serialize-javascript@>=5.0.0 <7.0.5": "^7.0.5",
+    "js-yaml@>=4.0.0 <4.3.1": "^4.3.1",
+    "brace-expansion@>=2.0.0 <2.1.4": "^2.1.4",
+    "diff": "^8.0.3"
+  }
+}