pim-agent 0.0.1 → 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AaronCQL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,10 +1,296 @@
-# pim-agent
+<!-- omit in toc -->
+# PIM - Pi IMproved
 
-Placeholder. This version exists only to register the package name so that npm
-trusted publishing (OIDC) can be configured for it; npm cannot publish a
-package's first version over OIDC.
+[![npm version](https://img.shields.io/npm/v/pim-agent?style=flat-square)](https://www.npmjs.com/package/pim-agent)
+[![npm downloads](https://img.shields.io/npm/dm/pim-agent?style=flat-square)](https://www.npmjs.com/package/pim-agent)
+[![license](https://img.shields.io/npm/l/pim-agent?style=flat-square)](./LICENSE)
+[![Bun](https://img.shields.io/badge/runtime-Bun-black?logo=bun&style=flat-square)](https://bun.com)
 
-The real package — a batteries-included distro of Pi, in your terminal, browser
-and Telegram — lands as `0.9.0`, published from CI with provenance.
+A batteries-included distro of Pi, accessible in your terminal, browser and Telegram.
 
-<https://github.com/AaronCQL/pim-agent>
+- **For the agent**: model-aware editing, web search/fetch, subagents, and more, behind a system prompt under 3K tokens.
+- **For you**: shared terminal/browser sessions, a mobile-friendly web UI, and a Telegram bot.
+- **Still Pi**: your Pi extensions, CLI, sessions and config keep working, while vanilla `pi` stays untouched.
+
+![Pim running in a terminal, a browser and Telegram, with a live session shared between them](https://raw.githubusercontent.com/AaronCQL/pim-agent/refs/heads/main/assets/hero.webp)
+
+- [Quick Start](#quick-start)
+  - [Web \& Telegram](#web--telegram)
+- [Agent Tools](#agent-tools)
+- [Terminal UI](#terminal-ui)
+- [Web UI](#web-ui)
+  - [Setup](#setup)
+  - [Remote Access](#remote-access)
+- [Telegram Bot](#telegram-bot)
+  - [Setup](#setup-1)
+  - [Commands](#commands)
+  - [Features](#features)
+- [Configuration](#configuration)
+  - [Toggling Features](#toggling-features)
+  - [API Keys (Optional)](#api-keys-optional)
+  - [Recommended TUI Settings (Optional)](#recommended-tui-settings-optional)
+- [Why Pim?](#why-pim)
+  - [Pi Core](#pi-core)
+  - [Lean System Prompt](#lean-system-prompt)
+  - [Model-Aware Tools](#model-aware-tools)
+- [Benchmarks](#benchmarks)
+  - [Terminal-Bench 2.0](#terminal-bench-20)
+- [Changelog](#changelog)
+- [Developing](#developing)
+
+## Quick Start
+
+Ensure that you have [Bun](https://bun.com/docs/installation) already installed:
+
+```sh
+# Install pim:
+bun install -g pim-agent
+
+# Launch pim TUI:
+pim
+
+# Update pim:
+pim update
+```
+
+### Web & Telegram
+
+To use Pim via your browser or Telegram, the recommended approach is to install the servers as a persistent daemon:
+
+```sh
+# Supports Linux (systemd) and macOS (launchd)
+pim --mode daemon --install
+
+# Tear down
+pim --mode daemon --uninstall
+```
+
+Supported arguments:
+
+| Flag | Default |
+| --- | --- |
+| `--surfaces` | `web,telegram` |
+| `--port` (web only) | `4319` |
+| `--hostname` (web only) | `127.0.0.1` |
+| `--cwd` | Current working directory |
+
+These are frozen into the daemon's unit file at install time, so re-run `--install` to change them. Flags you omit keep their installed values, and an older per-surface install is stopped and replaced for you. The daemon auto-restarts on failure, and updates in place from **Settings → Update & Restart** on the web UI, or `/update` in Telegram.
+
+After installing with the default settings, the web UI is at <http://localhost:4319>. Telegram needs a bot token first (see [Telegram Bot](#telegram-bot)). Surfaces start in isolation, so an unconfigured bot still leaves the browser served.
+
+## Agent Tools
+
+Pim revamps Pi's default tools (`bash`, `read`, `write`, `edit`) so they produce consistent behaviour and output, cross-reference each other where useful, and render uniformly in your UIs. It also adds:
+
+- **`apply_patch`** - V4A patch editing, dynamically exposed instead of `edit` for OpenAI and select Claude models
+- **`glob`** - file enumeration by glob pattern, sorted newest-first, respects `.gitignore`
+- **`grep`** - regex search across files with context lines, multiline matching, respects `.gitignore`
+- **`web_search`** - search the web via [Exa](https://exa.ai)/[Firecrawl](https://www.firecrawl.dev/)/[DuckDuckGo](https://duckduckgo.com/) with ranked results and snippets
+- **`web_fetch`** - fetch websites as Markdown via [Jina](https://jina.ai/reader/), with browser-rendered fallback via [`Bun.WebView`](https://bun.com/docs/runtime/webview)
+- **`subagent`** - delegate complex work to isolated sub-sessions with full tool access
+
+## Terminal UI
+
+Pim also ships with quality of life improvements for the TUI:
+
+- **ANSI-compatible themes** - `pim-light` and `pim-dark` themes which adapt to your terminal's colour scheme
+- **fzf-style autocomplete** - `@path` file picker and `/command` picker with fuzzy search
+- **Git-aware powerline footer** - cwd, git branch and states, context usage, model and session cost (run `/pim` to disable)
+- **TPS reporting** - per-cycle decode/prefill rate, TTFT, and cache read tokens (disabled by default; run `/pim` to enable)
+- **Concise tool UI** - minimal one-liner title across all tool calls, `Ctrl+O` to toggle full details
+
+## Web UI
+
+Run Pim in the browser, on any device. Hosted on a machine you can reach remotely, this lets you start work at your desk and carry on from your phone.
+
+### Setup
+
+See [Web & Telegram](#web--telegram).
+
+### Remote Access
+
+> [!WARNING]
+> Web mode has no built-in authentication, and the agent runs shell commands as you: anything that can reach the port has full access to the host. Bind it to a private network, never to `0.0.0.0`.
+
+[Tailscale](https://tailscale.com/) is the recommended way to do this. Binding to your tailnet IP keeps the server off your LAN and off the public internet, while every device on your tailnet can still reach it:
+
+```sh
+# Look up this machine's tailnet IP:
+tailscale ip -4
+
+# Install with --hostname set to it:
+pim --mode daemon --install --hostname=100.115.46.15 # Replace with your actual tailscale IP
+```
+
+The web UI is then at `http://<tailnet-ip>:4319` and `localhost` no longer serves it.
+
+## Telegram Bot
+
+Run Pim as a Telegram bot with full agent capabilities in your DMs or group chats (supports threads).
+
+### Setup
+
+Create `~/.pim/telegram/config.json` with your bot token (from [@BotFather](https://t.me/BotFather)) and an allowlist of chat IDs the bot will respond to:
+
+```json
+{
+  "token": "YOUR_TELEGRAM_BOT_TOKEN",
+  "allow": [123456789, 987654321]
+}
+```
+
+Then [install the daemon](#run-as-a-daemon), which brings the bot up with it.
+
+### Commands
+
+> [!TIP]
+> Use `/commands` on your bot for all commands to show up on your Telegram UI.
+
+| Command      | Description                                        |
+| ------------ | -------------------------------------------------- |
+| `/cancel`    | Cancel the current turn                            |
+| `/cd`        | Show or change the working directory               |
+| `/chatid`    | Show this chat's numeric ID                        |
+| `/clear`     | Reset chat history and context window              |
+| `/commands`  | Register all commands with Telegram                |
+| `/compact`   | Compact the current session context                |
+| `/effort`    | Show or change thinking effort level               |
+| `/logs`      | Show or change log verbosity                       |
+| `/model`     | Show or change the AI model                        |
+| `/temporary` | Toggle temporary chat (fresh session each message) |
+| `/update`    | Update the bot to the latest version               |
+| `/usage`     | Show context window and session cost               |
+
+### Features
+
+- ⏰ **Scheduled tasks** - your bot can create one-time, interval, or cron-based tasks that fire automatically; ask your bot to schedule something.
+- 👀 **Live progress logs** - use `/logs` to choose what you see while the agent works: final replies, tool use, intermediate text, or thinking.
+- 📝 **Rich Markdown** - supports Telegram's [rich text formatting](https://telegram.org/blog/watch-apps-and-more#obscenely-rich-text-formatting-for-bots) with full markdown and LaTeX math support.
+- 📎 **Rich media** - send photos, documents, videos, audio, and voice messages directly in chat; your bot can also send files back to you.
+- 🧵 **Thread-specific prompts** - each chat (or thread) gets its own session and optional instructions; ask your bot to modify its instructions.
+
+## Configuration
+
+### Toggling Features
+
+Pim ships a collection of features, nearly all enabled by default. To enable or disable specific features, run `/pim` in the TUI and toggle from the list. The changes apply to the running session immediately.
+
+### API Keys (Optional)
+
+The `web_search` tool tries [Exa](https://exa.ai) → [Firecrawl](https://www.firecrawl.dev/) → DuckDuckGo (via [Jina](https://jina.ai/reader/) reader), and the `web_fetch` tool uses Jina with a `Bun.WebView` fallback. These tools still work without API keys, but are subject to the following keyless rate limits (as of Sept 2026):
+
+- Exa - 1,000 requests per month
+- Firecrawl - 1,000 requests per month
+- Jina - 20 requests per minute
+
+For heavier usage, add API keys to `~/.pim/settings.json`:
+
+```json
+{
+  "exa": {
+    "apiKey": "api_key_here"
+  },
+  "firecrawl": {
+    "apiKey": "api_key_here"
+  },
+  "jina": {
+    "apiKey": "api_key_here"
+  }
+}
+```
+
+Environment variables take precedence over `settings.json` when set:
+
+```sh
+EXA_API_KEY='api_key_here' FIRECRAWL_API_KEY='api_key_here' JINA_API_KEY='api_key_here' pim
+```
+
+### Recommended TUI Settings (Optional)
+
+Add the following settings to your `~/.pi/agent/settings.json` for the best experience with Pim:
+
+```json
+{
+  "quietStartup": true,
+  "editorPaddingX": 1,
+  "markdown": {
+    "codeBlockIndent": ""
+  }
+}
+```
+
+## Why Pim?
+
+Pim's philosophy is **opinionated but minimal**. Its goal is to improve the out-of-the-box experience for both users and agents, without sacrificing composability with other Pi extensions.
+
+### Pi Core
+
+Think of Pim as an opinionated, batteries-included distro of Pi (like what Ubuntu is to Linux). Pim uses Pi in its core, and everything Pi does, it continues to do:
+
+- **Every Pi extension still works.** Pim registers its own extensions in-process, so third-party extensions from your Pi settings load right alongside them, exactly as before.
+- **Pi's CLI, sessions and config are unchanged.** Pim reads and writes pi's own session files, so a conversation started in pi resumes in pim and back again. Only Pim's own settings live separately in `~/.pim/settings.json`.
+- **Your vanilla `pi` keeps working.** Pim never registers itself with Pi and never touches your Pi settings, so `pi` and `pim` can both be used on the same machine.
+
+### Lean System Prompt
+
+Pim's system prompt is **under 3K tokens** despite exposing 10+ tools, far leaner than alternatives like OpenCode (~10K), Hermes (~16K), or Claude Code (~30K).
+
+This is achieved by having tool descriptions focus on _how_ to use each tool instead of prescribing _when_, since models already appear to internally encode when tools are needed, and prompting them to call tools can [suppress both necessary and unnecessary calls](https://arxiv.org/abs/2605.09252).
+
+### Model-Aware Tools
+
+LLMs are [increasingly post-trained](https://openai.com/index/introducing-codex) for specific agent harnesses, making tool schemas part of the model's learned interface. For text-file editing, Anthropic models are trained to use [string replacement operations](https://platform.claude.com/docs/en/agents-and-tools/tool-use/text-editor-tool), while OpenAI models use [V4A patch operations](https://developers.openai.com/api/docs/guides/tools-apply-patch).
+
+Pim keeps the active toolset model-aware instead of assuming one tool fits every LLM. It dynamically exposes the tools best suited to the selected model, giving each model the interface that best matches its learned behaviour while keeping the prompt lean.
+
+## Benchmarks
+
+### Terminal-Bench 2.0
+
+| ID | Pim Version | LLM / Model | Results |
+| --- | --- | --- | --- |
+| [r1](./benchmarks/terminal_bench_2/results/r1/) | [`21d084d1`](https://github.com/AaronCQL/pim-agent/tree/21d084d1) | `Qwen3.6-35B-A3B-UD-Q6_K_XL.gguf` | **41.6%** (37/89) |
+| [r2](./benchmarks/terminal_bench_2/results/r2/) | [`bfd792cf`](https://github.com/AaronCQL/pim-agent/tree/bfd792cf) | `Qwen3.6-35B-A3B-UD-Q6_K_XL.gguf` | **36.0%** (32/89) |
+| [r3](./benchmarks/terminal_bench_2/results/r3/) | [`cd52f3a4`](https://github.com/AaronCQL/pim-agent/tree/cd52f3a4) | `Qwen3.6-35B-A3B-UD-Q6_K_XL.gguf` | **36.0%** (32/89) |
+
+Preliminary aggregate score of **37.8%** from 3 independent runs. Each ran on an incremental build of Pim, though changes between runs were minor and none were tuned to the benchmark. Pim's `subagent` tool was disabled for all runs to keep each trial single-agent.
+
+On average, Pim solves **~54% more tasks** than [little-coder](https://github.com/itayinbarr/little-coder) with the same Qwen3.6-35B model (37.8% vs 24.6%). This also places Pim in a similar tier to Claude Code + Sonnet 4.5 (40.1%), and above Codex + GPT-5-Mini (31.9%).
+
+The Qwen3.6-35B model is hosted via llama.cpp on an M4 Pro 48GB MacBook, with the following config:
+
+```sh
+llama-server \
+  -c 131072 \
+  -ngl 99 \
+  --slot-save-path /tmp/llama-slots \
+  --flash-attn on \
+  --cache-type-k q8_0 \
+  --cache-type-v q8_0 \
+  --jinja \
+  --temp 0.6 \
+  --top-p 0.95 \
+  --top-k 20 \
+  --min-p 0.0 \
+  --presence-penalty 0.0 \
+  --repeat-penalty 1.0 \
+  --reasoning-budget 16384 \
+  --reasoning-budget-message "Alright, I've thought enough. Let me take the next concrete step now — either a tool call or a final answer — and refine based on what I learn." \
+  -np 1
+```
+
+_Note 1_: results are preliminary as only 3 independent full runs were conducted; Terminal-Bench 2.0 requires 5 independent full runs under a fixed configuration for an official score.
+
+_Note 2_: the gap with little-coder may be partly explained by different inference configs (128K context vs 32K, Q6_K_XL vs Q4_K_M, higher thinking budget, etc.).
+
+_Note 3_: in r1 and r3, the `code-from-image` trial was counted as non-passing because Qwen autonomously searched for the answer online after legitimately trying for a while.
+
+_Note 4_: see the [`benchmarks/terminal_bench_2`](./benchmarks/terminal_bench_2/) dir for breakdown of results and reproduction steps.
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for release notes.
+
+## Developing
+
+See [AGENTS.md](./AGENTS.md) for the developer guide.

package/bin/pim.ts

@@ -0,0 +1,151 @@
+#!/usr/bin/env bun
+import { Readable } from "node:stream";
+
+import { main } from "@earendil-works/pi-coding-agent";
+
+import {
+  CoreExtensions,
+  type PimInlineExtension,
+} from "#core/extensions/CoreExtensions";
+import { ExtensionToggles } from "#core/shared/ExtensionToggles";
+import { PimVersion } from "#core/shared/PimVersion";
+import { Supervisor } from "#core/shared/Supervisor";
+import { Updater } from "#core/shared/Updater";
+import init from "#tui/extensions/_init/index";
+import commandPicker from "#tui/extensions/command-picker/index";
+import filePicker from "#tui/extensions/file-picker/index";
+import footer from "#tui/extensions/footer/index";
+import pim from "#tui/extensions/pim/index";
+import sessionLease from "#tui/extensions/session-lease/index";
+import tps from "#tui/extensions/tps/index";
+import workingIndicator from "#tui/extensions/working-indicator/index";
+import { themeCliArgs } from "#tui/themes/themeCliArgs";
+
+// `_init` must stay first: it installs the runtime guard.
+const extensionFactories: readonly PimInlineExtension[] = [
+  { name: "_init", factory: init },
+  ...CoreExtensions.list,
+  { name: "command-picker", factory: commandPicker },
+  { name: "file-picker", factory: filePicker },
+  { name: "footer", factory: footer },
+  { name: "pim", factory: pim },
+  { name: "session-lease", factory: sessionLease },
+  { name: "tps", factory: tps },
+  { name: "working-indicator", factory: workingIndicator },
+];
+
+async function runUpdate(force: boolean): Promise<number> {
+  const at = await Supervisor.detectInstall();
+  if (!force && at.kind === "prod") {
+    const [installed, available] = await Promise.all([
+      PimVersion.current(),
+      PimVersion.latest({ timeoutMs: 10_000 }),
+    ]);
+    if (available === undefined) {
+      console.error("Could not determine the latest pim version.");
+      return 1;
+    }
+    if (!PimVersion.isNewer(available, installed)) {
+      console.log(`pim is already up to date (v${installed})`);
+      return 0;
+    }
+  }
+  const outcome = await Updater.run({
+    onStep: (label) => console.log(`[update] ${label}`),
+  });
+  for (const skip of outcome.skipped) {
+    console.log(`[update] skipped ${skip.label}: ${skip.reason}`);
+  }
+  if (!outcome.ok) {
+    console.error(outcome.error);
+    return 1;
+  }
+  console.log(
+    outcome.to === outcome.from
+      ? `pim is on v${outcome.to}`
+      : `Updated pim from v${outcome.from} to v${outcome.to}`
+  );
+  return 0;
+}
+
+const cliArgs = process.argv.slice(2);
+
+// Pi's argparse rejects prompts starting with `-` and ignores `--`; route them through stdin.
+const dashDashIdx = cliArgs.indexOf("--");
+let promptViaStdin: string | undefined;
+if (dashDashIdx >= 0) {
+  promptViaStdin = cliArgs.slice(dashDashIdx + 1).join(" ");
+  cliArgs.length = dashDashIdx;
+}
+
+if (cliArgs.includes("--version") || cliArgs.includes("-v")) {
+  console.log(
+    `pim ${await PimVersion.current()} (pi ${await PimVersion.pi()})`
+  );
+  process.exit(0);
+}
+
+// Pi's `update` cannot move the pi inside pim's install tree; only reinstalling pim can.
+if (cliArgs[0] === "update") {
+  const rest = cliArgs.slice(1);
+  const isSelf = rest.every(
+    (arg) => arg === "self" || arg === "pim" || arg === "--force"
+  );
+  if (isSelf) {
+    process.exit(await runUpdate(rest.includes("--force")));
+  }
+}
+
+// Pi's banner points at `pi update`, which cannot reach the bundled copy.
+process.env["PI_SKIP_VERSION_CHECK"] = "1";
+
+const modeIdx = cliArgs.findIndex(
+  (a) => a === "--mode" || a.startsWith("--mode=")
+);
+const mode =
+  modeIdx >= 0
+    ? cliArgs[modeIdx]!.includes("=")
+      ? cliArgs[modeIdx]!.split("=")[1]
+      : cliArgs[modeIdx + 1]
+    : undefined;
+// Writing a unit file must not load the frontend it describes; keep these imports lazy.
+const daemonAction = cliArgs.includes("--install")
+  ? "install"
+  : cliArgs.includes("--uninstall")
+    ? "uninstall"
+    : undefined;
+// `--mode web` and `--mode telegram` are the single-surface spellings of the daemon.
+if (mode === "daemon" || mode === "web" || mode === "telegram") {
+  if (daemonAction !== undefined) {
+    const { DaemonInstall } = await import("#daemon/DaemonInstall");
+    await (daemonAction === "install"
+      ? DaemonInstall.install(cliArgs)
+      : DaemonInstall.uninstall());
+    process.exit(0);
+  }
+  const { start } = await import("#daemon/index");
+  await start(cliArgs);
+  process.exit(0);
+}
+
+if (promptViaStdin !== undefined) {
+  // Pi's `readPipedStdin()` only checks `isTTY` and drains, so an in-memory Readable passes as a pipe.
+  Object.defineProperty(process, "stdin", {
+    value: Readable.from([promptViaStdin]),
+    configurable: true,
+  });
+}
+
+// Pi's `cli.js` preamble, minus `configureHttpDispatcher()`, which `main` calls itself.
+process.title = "pi";
+process.env["PI_CODING_AGENT"] = "true";
+process.env["AI_AGENT"] = "pi";
+process.emitWarning = () => {};
+
+// Pi never applies its `enabled` filter to inline factories, so the toggle must gate inside the factory.
+await main([...themeCliArgs(cliArgs), ...cliArgs], {
+  extensionFactories: extensionFactories.map(({ name, factory }) => ({
+    name,
+    factory: ExtensionToggles.gate(name, factory),
+  })),
+});

package/package.json

@@ -1,9 +1,87 @@
 {
   "name": "pim-agent",
-  "version": "0.0.1",
-  "description": "Placeholder — the real release lands as 0.9.0.",
+  "version": "0.9.0",
+  "description": "A batteries-included distro of Pi, accessible in your terminal, browser and Telegram.",
   "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "agent"
+  ],
   "homepage": "https://github.com/AaronCQL/pim-agent#readme",
-  "repository": { "type": "git", "url": "git+https://github.com/AaronCQL/pim-agent.git" },
-  "files": ["README.md"]
+  "bugs": {
+    "url": "https://github.com/AaronCQL/pim-agent/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AaronCQL/pim-agent.git"
+  },
+  "bin": {
+    "pim": "bin/pim.ts"
+  },
+  "imports": {
+    "#core/*": "./packages/core/src/*.ts",
+    "#daemon/*": "./packages/daemon/src/*.ts",
+    "#tui/*": "./packages/tui/src/*.ts",
+    "#telegram/*": "./packages/telegram/src/*.ts",
+    "#protocol/*": "./packages/protocol/src/*.ts",
+    "#server/*": "./packages/server/src/*.ts",
+    "#web/*": "./packages/web/src/*.ts"
+  },
+  "files": [
+    "bin/",
+    "packages/core/src/",
+    "packages/daemon/src/",
+    "packages/tui/src/",
+    "packages/telegram/src/",
+    "packages/protocol/src/",
+    "packages/server/src/",
+    "packages/web/dist/client/",
+    "!packages/core/src/**/fixtures/",
+    "!packages/**/*.test.ts"
+  ],
+  "engines": {
+    "bun": ">=1.2.7"
+  },
+  "pi": {
+    "image": "https://raw.githubusercontent.com/AaronCQL/pim-agent/refs/heads/main/assets/hero.webp"
+  },
+  "scripts": {
+    "dev": "bun link && pim",
+    "prepack": "bun run web:build",
+    "probe": "bun packages/server/src/probe.ts",
+    "check": "bun scripts/check.ts",
+    "gen:brand": "bun scripts/brand/generate.ts",
+    "gen:hero": "bun scripts/hero/generate.ts",
+    "web:build": "cd packages/web && vite build",
+    "web:dev": "cd packages/web && vite"
+  },
+  "devDependencies": {
+    "@fontsource/commit-mono": "^5.3.0",
+    "@happy-dom/global-registrator": "^20.14.0",
+    "@iconify-json/griddy-icons": "^1.2.0",
+    "@iconify-json/solar": "^1.2.10",
+    "@jsquash/webp": "^1.5.0",
+    "@resvg/resvg-js": "^2.6.2",
+    "@solidjs/vite-plugin": "3.0.0-next.40",
+    "@solidjs/web": "^2.0.0-rc.7",
+    "@types/bun": "latest",
+    "happy-dom": "^20.14.0",
+    "highlight.js": "^11.12.0",
+    "oxfmt": "0.67.0",
+    "oxlint": "^1.82.0",
+    "solid-js": "^2.0.0-rc.7",
+    "streaming-markdown": "^0.2.15",
+    "typescript": "^7.0.2",
+    "unocss": "^66.10.0",
+    "vite": "^8.2.2"
+  },
+  "dependencies": {
+    "@earendil-works/pi-coding-agent": "0.85.1",
+    "@earendil-works/pi-server": "0.85.1",
+    "diff": "^9.0.0",
+    "fzf": "^0.5.2",
+    "grammy": "^1.46.0",
+    "ignore": "^7.0.9",
+    "ky": "^2.1.0"
+  }
 }

package/packages/core/src/attachments/AttachmentStore.ts

@@ -0,0 +1,99 @@
+import { mkdir } from "node:fs/promises";
+import { basename, extname } from "node:path";
+
+import { SafePath } from "../shared/SafePath";
+
+/** A file the store has taken a copy of, under a name it chose. */
+export type StoredFile = {
+  /** Names the file within its scope; what a client sends back on a prompt. */
+  readonly id: string;
+  /** Absolute path on the server. The only path the agent is ever told. */
+  readonly path: string;
+  readonly mimeType: string;
+};
+
+/** A file that now lives on the machine the agent runs on. */
+export type StoredAttachment = StoredFile & {
+  /** Present only for images small enough to inline into the prompt. */
+  readonly imageBase64: string | undefined;
+};
+
+export type AttachmentInput = {
+  readonly bytes: ArrayBuffer;
+  readonly mimeType: string;
+  /** Client-supplied filename. Only its basename is ever used. */
+  readonly name?: string;
+  /** Stem of the stored filename; a random one when omitted. */
+  readonly stem?: string;
+  /** Extension to fall back on when `name` carries none. */
+  readonly ext?: string;
+};
+
+/** Above this, an image is referenced by path instead of inlined. */
+const IMAGE_BYTES_LIMIT = 4 * 1024 * 1024;
+
+/** Materialises client bytes onto the server's filesystem; the agent is only ever told a server path. */
+export class AttachmentStore {
+  public constructor(private readonly root: string) {}
+
+  public async store(
+    scope: string,
+    input: AttachmentInput
+  ): Promise<StoredAttachment> {
+    const { id, path } = await this.place(
+      scope,
+      input.stem,
+      extensionOf(input)
+    );
+    await Bun.write(path, input.bytes);
+
+    const isImage = input.mimeType.startsWith("image/");
+    return {
+      id,
+      path,
+      mimeType: input.mimeType,
+      imageBase64:
+        isImage && input.bytes.byteLength <= IMAGE_BYTES_LIMIT
+          ? Buffer.from(input.bytes).toString("base64")
+          : undefined,
+    };
+  }
+
+  /** Copies a file already on the agent's disk into the store so it can be served. */
+  public async storeFile(scope: string, source: string): Promise<StoredFile> {
+    const file = Bun.file(source);
+    const name = basename(source);
+    const ext = extname(name);
+    // Keep `basename(name, ext)`: a regex strip leaves a dotfile like `.bashrc` with no name.
+    const { id, path } = await this.place(scope, basename(name, ext), ext);
+    await Bun.write(path, file);
+    return { id, path, mimeType: file.type || "application/octet-stream" };
+  }
+
+  private async place(
+    scope: string,
+    stem: string | undefined,
+    ext: string
+  ): Promise<{ readonly id: string; readonly path: string }> {
+    const dir = this.scopeDir(scope);
+    await mkdir(dir, { recursive: true });
+    const id = SafePath.safeName(
+      `${stem || Bun.randomUUIDv7()}-${Date.now()}${ext}`
+    );
+    return { id, path: SafePath.contain(dir, id) };
+  }
+
+  private scopeDir(scope: string): string {
+    return SafePath.contain(this.root, SafePath.safeName(scope));
+  }
+
+  /** Where `store` put this id; the id is re-sanitised, so it can never name a file outside its scope. */
+  public locate(scope: string, id: string): string {
+    return SafePath.contain(this.scopeDir(scope), SafePath.safeName(id));
+  }
+}
+
+function extensionOf(input: AttachmentInput): string {
+  const fromName = extname(basename(input.name ?? ""));
+  return fromName || input.ext || "";
+}