@pi-unipi/unipi 3.0.0-alpha.2 → 3.0.0-alpha.21

package/packages/unipi/index.ts

@@ -9,8 +9,10 @@
  *   mise run unipi
  */
 
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { migrateState, sweepOrphanSessions } from "@pi-unipi/core";
+import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { installArbiter, installHarnessProvenance, migrateState, sweepOrphanSessions, withCommandEcho } from "@pi-unipi/core";
+import { withHarnessToolAnnotations } from "@pi-unipi/utility";
+import { readUtilSettings, simpleWrapTool, simpleWrapped, installSimpleGroupEvents } from "@pi-unipi/utility";
 
 import workflow from "@pi-unipi/workflow";
 import longHorizon from "@pi-unipi/long-horizon";
@@ -21,6 +23,7 @@ import backgroundTasks from "@pi-unipi/background-tasks";
 import btw from "@pi-unipi/btw/extensions/btw.js";
 import webApi from "@pi-unipi/web-api";
 import utility from "@pi-unipi/utility";
+import skillRegistry from "@pi-unipi/skill-registry";
 import askUser from "@pi-unipi/ask-user";
 import mcp from "@pi-unipi/mcp";
 import notify from "@pi-unipi/notify";
@@ -30,11 +33,44 @@ import compactor from "@pi-unipi/compactor";
 import footer from "@pi-unipi/footer";
 import updater from "@pi-unipi/updater";
 import inputShortcuts from "@pi-unipi/input-shortcuts";
-import image from "@pi-unipi/image";
 import fusion from "@pi-unipi/fusion";
 import watchdog from "@pi-unipi/watchdog";
 
 export default function (pi: ExtensionAPI) {
+  const api = withCommandEcho(pi);
+  // Harness provenance must observe every input/send — install before modules.
+  try {
+    installHarnessProvenance(api);
+  } catch {
+    // Provenance is cosmetic; never blocks startup.
+  }
+  // The turn arbiter must own the single agent_before_settle handler BEFORE
+  // any module mounts (idempotent; a no-op in child processes).
+  try {
+    installArbiter(pi);
+  } catch {
+    // Never block startup on the arbiter.
+  }
+  // "simple" render style = mcode transcript: every tool registered by any
+  // unipi module is captured here and, after all modules load, re-registered
+  // with the collapsed one-liner wrapper (execute/schema untouched; Ctrl+O
+  // falls back to the tool's own renderer). best-effort, never blocks load.
+  const captured = new Map<string, ToolDefinition<any, any, any>>();
+  const rawRegister = api.registerTool.bind(api);
+  const registering = new Proxy(api, {
+    get(target, prop, receiver) {
+      if (prop === "registerTool") {
+        return (tool: ToolDefinition<any, any, any>) => {
+          // Harness tool-annotation wrapper (idempotent, applied BEFORE the
+          // simple-mode wrapper so simpleResult hooks merge).
+          const wrapped = withHarnessToolAnnotations(tool);
+          captured.set(tool.name, wrapped);
+          return rawRegister(wrapped);
+        };
+      }
+      return Reflect.get(target, prop, receiver);
+    },
+  });
   // One-time v3 state relocation into ~/.unipi/{global,workspace}/, then reap
   // any dead-pid session dirs left by crashed sessions. Both are best-effort
   // and version/pid-gated, so they are cheap on every subsequent startup.
@@ -45,17 +81,13 @@ export default function (pi: ExtensionAPI) {
     // Never block startup on housekeeping.
   }
 
-  const load = (_name: string, extension: (api: ExtensionAPI) => void) => extension(pi);
+  const load = (_name: string, extension: (api: ExtensionAPI) => void) => extension(registering);
 
   load("workflow", workflow);
   load("long-horizon", longHorizon);
   load("memory", memory);
-  // Utility loads BEFORE info-screen: the name badge overlay must be pushed
-  // to the BOTTOM of the overlay stack. hideOverlay() pops the topmost entry,
-  // and a capturing overlay's done() callback is one-shot — if the badge were
-  // stacked above the boot info-screen, the info-screen's auto-close would pop
-  // the badge (spending its done()) and strand the dashboard uncloseable.
   load("utility", utility);
+  load("skill-registry", skillRegistry);
   load("info-screen", infoScreen);
   load("subagents", subagents);
   load("background-tasks", backgroundTasks);
@@ -70,7 +102,20 @@ export default function (pi: ExtensionAPI) {
   load("footer", footer);
   load("updater", updater);
   load("input-shortcuts", inputShortcuts);
-  load("image", image);
   load("fusion", fusion);
   load("watchdog", watchdog);
+
+  // After all modules registered: apply the mcode-style wrapper. Re-register
+  // with the RAW register (not the capturing proxy) to avoid double-capture.
+  if (readUtilSettings().render.style === "simple") {
+    installSimpleGroupEvents(api);
+    for (const def of captured.values()) {
+      if (simpleWrapped.has(def)) continue;
+      try {
+        rawRegister(simpleWrapTool(def));
+      } catch {
+        // keep the original tool on any failure
+      }
+    }
+  }
 }

package/packages/updater/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/updater",
-  "version": "3.0.0-alpha.2",
+  "version": "3.0.0-alpha.21",
   "description": "Auto-updater, changelog browser, and readme browser for Unipi — checks npm registry, renders CHANGELOG.md and README.md files in TUI overlays",
   "type": "module",
   "main": "index.ts",
@@ -34,7 +34,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "3.0.0-alpha.2"
+    "@pi-unipi/core": "3.0.0-alpha.21"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.87.1",

package/packages/utility/README.md

@@ -1,105 +1,112 @@
 # @pi-unipi/utility
 
-Environment info, diagnostics, cleanup, and the session name badge. The grab-bag package for maintaining your development environment and keeping an eye on provider cache behavior.
+The settings hub, automatic session naming, image tools, pasted-file attachments, `/unipi:answer`, and a few maintenance commands. Also keeps the shared model cache every other module's model picker reads.
 
 ## Commands
 
 | Command | Description |
 |---------|-------------|
-| `/unipi:env` | Show environment info (Node, Pi, OS, paths) |
-| `/unipi:doctor` | Run diagnostics across all modules |
-| `/unipi:status` | Show immediate guidance to the live `/unipi:info` dashboard and `/unipi:doctor` diagnostics |
-| `/unipi:cleanup` | Clean stale DBs, temp files, old sessions |
-| `/unipi:reload` | Explain how to reload extensions |
-| `/unipi:name-badge` | Toggle name badge overlay |
-| `/unipi:settings` | Badge field + "Set/Generate session name" actions (Utility group) |
-| `/unipi:settings` | Hub — badge behavior (Utility group) |
-| `/unipi:prefix-cache` | Show privacy-safe request-prefix transitions and provider cache token counters |
+| `/unipi:settings [search]` | Configure every UniPi module in one panel (global + project scopes); a search term opens it filtered (`/unipi:settings image`). Typing `/settings` lists it before pi's own `/settings` |
+| `/unipi:continue` (`/unipi:retry`) | Take another turn from where the agent stopped, without adding text |
+| `/unipi:cleanup` | Remove stale UniPi temp files and leftovers. Shows what it would remove and asks first; `--dry-run` only lists, `--yes` skips the question |
+| `/unipi:doctor` | Check folders, config, the model cache, the Decision Model key and skill exposure |
+| `/unipi:answer` (`reply`\|`questions`\|`web`) | Answer the agent's last reply without scrolling back and forth |
 
-### Examples
+Skill exposure and the skill manager live in `@pi-unipi/skill-registry` (`/unipi:skills`).
 
-```
-/unipi:env                 # Show environment
-/unipi:doctor              # Run diagnostics
-/unipi:cleanup             # Clean stale files
-/unipi:cleanup --dry-run   # Preview what would be cleaned
-/unipi:name-badge          # Toggle the session name badge
-/unipi:settings            # → Utility → "Generate session name"
-```
+The agent gets the three image tools (below) and nothing else from this package.
 
-## Special Triggers
+## Automatic session naming
 
-Utility registers with the info-screen dashboard, showing module status and diagnostic results. The footer subscribes to utility events for its extension status segment. When Herdr is present, the badge module syncs the session name to the pane title.
+After each round that finished normally, if you typed the prompt:
 
-## Provider prefix-cache diagnostics
+1. Greetings, thanks, "ok", "continue" and slash commands are skipped outright.
+2. jev (the Decision Model) answers two short questions: is this a real request with its own subject, and — if the session already has a name — does it move to a different task? Only a confident "yes" renames.
+3. The name is written by a separate throwaway session whose only tool is `rename_session`. It sees the current name and your last few requests, nothing else, and never touches the main session.
 
-`/unipi:prefix-cache` observes Pi's provider-native request payloads without modifying them. It reports session-local cache epochs, exact structural prefix extensions, retries, request-envelope/history boundaries, and provider-reported `cacheRead`/`cacheWrite` token totals.
+A name you set yourself with pi's `/name` is never overwritten. Without a Decision Model key, only an unnamed session gets named, on its first prompt of four words or more.
 
-The fingerprints are keyed HMAC-SHA-256 values using a random in-memory key that is discarded on reload. Raw prompts, messages, tool arguments, tool schemas, and provider payloads are never retained or logged by this diagnostic. Fingerprints therefore cannot be compared across process lifetimes. A reported prefix extension means the request is structurally eligible for reuse; provider TTL, routing, and cache policy still decide whether a hit occurs.
+Inside Herdr, the name is also shown as the pane title and, while the tab still has its default number, the tab label.
 
-`/unipi:cleanup` includes private `~/.unipi/tool-results/` artifacts in the normal temporary-file retention policy (7 days by default). Use dry-run mode to review candidates before deletion.
+Settings (`/unipi:settings` → Utility → Session name): auto-rename on/off, naming model (defaults to the session model), Herdr sync, and a **Rename now** action.
 
-## Agent Tools
+## Answering the last reply
 
-| Tool | Description |
-|------|-------------|
-| `ctx_env` | Environment inspection for debugging |
-| `set_session_name` | Set the session name for badge display (when badge agent-tool is enabled) |
+`/unipi:answer` opens one of three screens (Settings → Utility → Answer picks the default; `/unipi:answer reply|questions|web` overrides it once, with suggestions as you type):
 
-## Configurables
+- **reply** (default) — like `/unipi:btw`, it takes the place of the input area: the agent's last reply in a scrollable view on top, a fixed input box below. ↑↓ scroll the reply while nothing is typed; once you type they move the cursor in your answer, and Alt+↑↓ or PgUp/PgDn scroll instead. Shift+Enter (or Ctrl+J) adds a line, Enter sends it as your next message, Esc goes back to the normal editor with your draft. If the reply asks questions, Tab switches to **questions**.
+- **questions** — pi's editor holding only `Q1. … / A1:` pairs for every question in the reply: each sentence ending in `?`, in full, even when it wraps over several lines (code blocks and URLs are ignored). The cursor starts on the first answer, Tab / Shift+Tab jump between answers, Ctrl+G opens your `$EDITOR`, Enter sends one message that quotes each question above its answer; empty answers are listed as not answered.
+- **web** — a local page with the full reply on the left and one box per question on the right (plus a free-text note), on 127.0.0.1 behind a random URL. Over SSH (detected from `SSH_CONNECTION`/`SSH_TTY`) it doesn't open a browser: it shows the `ssh -L` command, built from this machine's hostname and the port (47321 unless you set one), and the URL to open on your own machine.
 
-### Name Badge
+When a reply asks questions, a line above the editor says so (`2 questions in the reply — /unipi:answer questions …`) until you send anything. Settings → Utility → Answer → Questions hint turns it off.
 
-```
-/unipi:settings              # Badge + skills discovery (Utility group)
-```
+## Pasted images and files
 
-Or edit `.unipi/config/util-settings.json` directly (migrated automatically from the legacy `.unipi/config/badge.json` on first read):
+Paste a screenshot (Ctrl+V), drag a file into the terminal, or paste a path, and the path in the editor becomes a token: `[Image #1]` for PNG/JPEG/GIF/WebP, `[File #2]` for documents (PDF, text, office files, archives, media). A chip row above the editor lists what's attached, with small previews in terminals that can draw images (Kitty, Ghostty, iTerm2, WezTerm).
 
-```json
-{
-  "badge": {
-    "badgeEnabled": true
-  }
-}
-```
+When you send:
+- Images go to the model as real images, in the order their tokens appear.
+- File tokens become `[File #2: /path/to/file]` so the agent can read them.
+- A line under your message in the transcript shows what was attached; the model doesn't see it.
 
-The badge is a persistent HUD overlay in the top-right corner showing the current session name. It auto-restores visibility on session restart.
+Delete a token to drop its attachment. Only paths that arrive by paste, drop or Ctrl+V are converted; a path you type stays text. Settings → Utility → Attachments turns this or the previews off.
 
-### Skill Exposure (jev-judged)
+## Image tools
 
-Controls which discovered skills are cataloged in the agent's system prompt. Configure via `/unipi:settings` (Skills group) or the engine file (`skills` subtree):
+| Tool | What it does |
+|------|--------------|
+| `image_generate` | Text → image |
+| `image_edit` | Image + text → image |
+| `image_recognize` | Image → text with a vision model; only offered while the session model can't see images itself |
 
-- **mode: `judged`** (default) — on the session's first prompt, if more than `maxSkills` skills are discovered, ONE jev (TypeSafe System One) request scores every skill's relevance to your prompt; only relevant ones stay cataloged, sorted by relevance and capped. The set is frozen per session and persisted, so the system prompt is byte-identical on every later turn (provider prefix cache stays intact).
-- **mode: `all`** — no judging; every skill stays.
-- **mode: `off`** — Unipi's bundled skills are stripped from the catalog (old `discovery: false` behavior).
+Settings → Image has one section per tool. Each model picker only lists models that fit: generation shows models whose output includes images, editing shows models that take an image and output one, recognition shows vision models. The list comes from the shared model cache: pi's registry, OpenRouter's image models (refreshed daily), and a few fal models when a fal key is set.
 
-Extra knobs: `threshold` (min jev relevance, default 0.3), `maxSkills` (cap, default 12), `recheck` (default on — later prompts on new topics get a "newly relevant skills" message revealing up to 5 hidden skills; revealed skills are never announced twice, and the system prompt itself never changes after the freeze).
+How a model is called depends on its provider:
 
-Skills stay invocable in every mode via `/skill:name` or by reading their SKILL.md directly. The judged set reuses the long-horizon **Decision model** (jev) — provider, model, key and base URL come from the Judge settings; missing key, timeout, or any failure exposes ALL skills (fail-open).
+| Model | Sent to | Key |
+|-------|---------|-----|
+| `openrouter/…` | OpenRouter (chat with image output) | Settings → Image → Keys, else pi's `/login`, else `OPENROUTER_API_KEY` |
+| `fal/…` | fal.run | Settings → Image → Keys, else `FAL_KEY` / `FAL_API_KEY` |
+| any other pi provider | that provider's endpoint (OpenAI images format) | pi's key for that provider |
+| anything, with a **custom endpoint** set | your base URL, model id sent as typed, format of your choice (OpenAI images, OpenRouter-style, fal) | the endpoint's own key |
 
-```json
-{
-  "skills": { "mode": "judged", "threshold": 0.3, "maxSkills": 12, "recheck": true }
-}
-```
+Defaults are FLUX.2 [klein] 4B on OpenRouter for both generation and editing, which is cheap and fast. Images are returned inline and saved to `~/.unipi/images/`. When a call fails, the tool reports it as a failure with the missing key or setting spelled out.
 
-## Programmatic API
+## Response formatting
 
-| Module | Path | Description |
-|--------|------|-------------|
-| ProcessLifecycle | `lifecycle/process` | Parent PID polling, orphan detection, signal handlers |
-| cleanupStale | `lifecycle/cleanup` | Stale DB/temp/session cleanup with dry-run |
-| AnalyticsCollector | `analytics/collector` | Privacy-respecting event collection with daily rollup |
-| runDiagnostics | `diagnostics/engine` | Cross-module health checks with plugin architecture |
+Settings → Utility → Response formatting → Style changes how pi's built-in `read`, `bash`, `edit` and `write` calls look in the transcript. The model sees exactly the same tools either way; only the drawing changes. It applies after `/reload` (or a restart) — the renderers are registered once when extensions load, so a change made mid-session takes effect on the next reload.
 
-## Privacy
+- **simple** — one line per tool, output collapsed:
+  ```
+  ▪ Read   ./demo/app.py · 5 lines
+  ▪ Edited ./demo/app.py · +1 -1
+  ▪ Ran    cd demo && ls -la && python3 app.py · 7 output lines
+  ```
+  The live (latest) row shows a ticking timer (`• Running npm test · 12s`) and
+  done rows pin the final duration (`· 7 output lines · 3s`). Tools that opt in
+  keep their result under the row (`ask_user`'s Q→A) or drive the meta live
+  (`run_subagent`'s model · calls · duration · tokens · cost). Sidekick steps
+  and other non-pi-tool activity draw with the same verbs/markers.
+- **regular** (default) — pi's own rendering, untouched.
+- **advanced** —
+  - Commands are syntax-highlighted. Code embedded in a command is highlighted in its own language: heredoc bodies (`python - <<'PY'`, `cat > x.ts <<EOF`) and `python -c` / `node -e` strings.
+  - Output shows its last 10 lines. Whole-output JSON is pretty-printed, test-run summaries (node:test, vitest, cargo, pytest) get a ✓/✗ line, and an exit line shows the code and time.
+  - Edits show as a diff with line numbers, syntax colouring by file type, and tinted added/removed lines.
+  - Writes and reads are highlighted by file type.
 
-The analytics collector is privacy-respecting:
-- No file contents recorded
-- No sensitive data (API keys, tokens, passwords) — redacted automatically
-- Strings truncated to 500 characters
-- All data stays local
+Ctrl+O expands anything collapsed in every style. In every style, blank runs
+between transcript blocks are normalized: each block keeps its interior
+spacing, but adjacent blocks are separated by exactly one blank row (pi
+otherwise stacks a block's own padding on top of its leading spacer,
+producing occasional 2–4 blank runs).
+
+## Model cache
+
+On every session start, utility writes pi's live model list (models with credentials) to `~/.unipi/config/models-cache.json`, with each model's input and output modalities. The settings hub pickers and kanboard read it; `readModelCache()` / `filterModels()` in `@pi-unipi/core` give the same list to any module.
+
+## Cleanup safety
+
+`/unipi:cleanup` can only remove what its allowlist names: saved tool outputs and `unipi-*` temp files older than 7 days, and the old compactor continuity database. Memory, v2 backups, kanboard boards, config and workspace state are never candidates.
 
 ## License
 

package/packages/utility/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/utility",
-  "version": "3.0.0-alpha.2",
+  "version": "3.0.0-alpha.21",
   "description": "Utility commands and tools for Pi coding agent — lifecycle, diagnostics, cache, analytics, display, batch execution",
   "type": "module",
   "main": "src/index.ts",
@@ -36,7 +36,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "3.0.0-alpha.2"
+    "@pi-unipi/core": "3.0.0-alpha.21"
   },
   "devDependencies": {},
   "peerDependencies": {

package/packages/utility/skills/image/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: image
+scope: agent
+description: |
+  Generate, edit and read images with the image_generate, image_edit and
+  image_recognize tools (@pi-unipi/utility). Use when the user asks for a
+  picture, icon, illustration, mockup or logo, wants an existing image
+  changed, or needs a screenshot/diagram read while the session model
+  cannot see images.
+---
+
+# Image tools
+
+| Tool | Use for |
+|------|---------|
+| `image_generate(prompt, model?)` | A new image from text |
+| `image_edit(prompt, image, model?)` | Change an existing image (`image` = file path, data: URL or base64) |
+| `image_recognize(image, prompt?, model?)` | Read an image with a vision model — only offered while your own model cannot see images |
+
+## Prompting
+
+- Be concrete: subject, style, composition, lighting, colours, text to render.
+- Say what you want, not what you don't — negation is unreliable.
+- For edits, say what to change AND what to keep; unmentioned details can drift.
+- Images cost money. Generate once, show the result, and only retry when asked.
+
+## Models
+
+Omit `model` to use the one set in `/unipi:settings` → Image. To override, pass
+`provider/model-id`, e.g. `openrouter/black-forest-labs/flux.2-klein-4b` or
+`fal/fal-ai/flux-2/klein/4b` (edits: `fal/fal-ai/flux-2/klein/4b/edit`).
+
+## Results
+
+Images come back inline and are saved under `~/.unipi/images/` (path in the
+result). If a call fails, the error says which key or setting is missing —
+tell the user that instead of retrying.

package/packages/utility/skills/utility/SKILL.md

@@ -2,69 +2,26 @@
 name: utility
 scope: agent
 description: |
-  Guidance for using the @pi-unipi/utility extension commands and tools.
-  Provides lifecycle management, diagnostics, cleanup, batch execution,
-  environment inspection, and terminal utilities.
+  What the @pi-unipi/utility extension does for the user: the /unipi:settings
+  hub, /unipi:continue (/unipi:retry), /unipi:cleanup, /unipi:doctor,
+  and automatic session naming. It gives the agent no tools.
 ---
 
-# @pi-unipi/utility — Agent Guidance
+# @pi-unipi/utility
 
-## Overview
+## Commands (user-facing)
 
-The `@pi-unipi/utility` extension provides general-purpose utilities for the Pi coding agent. It is **not** related to compaction — it provides helpers that any module or agent can use.
+| Command | Purpose |
+|---------|---------|
+| `/unipi:settings` | Configure every UniPi module |
+| `/unipi:continue` / `/unipi:retry` | Take another turn without new text |
+| `/unipi:cleanup` | Remove stale UniPi temp files (previews and asks first; `--dry-run`, `--yes`) |
+| `/unipi:doctor` | Check config, model cache, Decision Model key, skill exposure |
 
-## Commands
+## Notes for the agent
 
-| Command | Purpose | When to Use |
-|---------|---------|-------------|
-| `/unipi:continue` | Continue agent without polluting context | After interruption, to resume cleanly |
-| `/unipi:reload` | Explain how to reload extensions | When user asks about hot-reloading |
-| `/unipi:status` | Request status from all modules | To check which modules are loaded |
-| `/unipi:cleanup` | Clean stale files, DBs, sessions | When disk space is low or after crashes |
-| `/unipi:env` | Show environment info | For debugging version/path issues |
-| `/unipi:doctor` | Run diagnostics | When something seems broken |
-
-### Cleanup Options
-
-- `--dry-run` — Report what would be cleaned without removing anything
-- Default max ages: DBs 14 days, temp 7 days, sessions 30 days
-
-## Tools
-
-| Tool | Purpose |
-|------|---------|
-| `ctx_batch` | Atomic batch execution of commands with rollback |
-| `ctx_env` | Environment inspection |
-
-### Batch Execution Pattern
-
-```typescript
-import { BatchBuilder } from "@pi-unipi/utility/tools/batch";
-
-const report = await new BatchBuilder()
-  .addCommand("search", { query: "foo" })
-  .addTool("memory_search", { query: "bar" })
-  .withOptions({ failFast: true, commandTimeoutMs: 30000 })
-  .execute(myExecutor);
-```
-
-## Modules (for code use)
-
-| Module | Import Path | Purpose |
-|--------|-------------|---------|
-| ProcessLifecycle | `@pi-unipi/utility/lifecycle/process` | Parent PID polling, orphan detection, cleanup registry |
-| cleanupStale | `@pi-unipi/utility/lifecycle/cleanup` | Stale file/DB/session cleanup |
-| TTLCache | `@pi-unipi/utility/cache/ttl-cache` | In-memory or SQLite-backed TTL cache |
-| AnalyticsCollector | `@pi-unipi/utility/analytics/collector` | Privacy-respecting event collection |
-| runDiagnostics | `@pi-unipi/utility/diagnostics/engine` | Cross-module health checks |
-| detectCapabilities | `@pi-unipi/utility/display/capabilities` | Terminal feature detection |
-| clampWidth, wrapLines | `@pi-unipi/utility/display/width` | ANSI-aware text formatting |
-| SettingsInspector | `@pi-unipi/utility/tui/settings-inspector` | Reusable settings overlay model |
-
-## Integration Notes
-
-- Lifecycle manager is a singleton — use `getLifecycle()` to access
-- Analytics collector is a singleton — use `getAnalyticsCollector()`
-- Diagnostics engine supports custom plugins via `registerDiagnosticPlugin()`
-- TTLCache defaults to memory backend; set `persistent: true` for SQLite
-- All modules emit unipi events for cross-module integration
+- There is no tool to rename the session. Naming happens automatically after
+  real requests; the user can also use pi's `/name`.
+- Skills not listed in your catalog may still be installed. If the user names
+  a skill, read its SKILL.md or ask them to run `/skill:<name>`.
+- When something UniPi-related looks broken, suggest `/unipi:doctor`.

package/packages/utility/src/answer/extract.ts

@@ -0,0 +1,128 @@
+/**
+ * @pi-unipi/utility — /unipi:answer: questions in, answers out (pure)
+ *
+ * Pulls the questions out of the agent's last reply (any line with a "?"
+ * outside code blocks, list/heading markers stripped), builds a Q/A template,
+ * parses it back, and composes one user message that quotes each question.
+ */
+
+export const MAX_QUESTIONS = 20;
+
+/** Plain text of an assistant message's content. */
+export function messageText(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter((c): c is { type: "text"; text: string } => !!c && typeof c === "object" && (c as { type?: string }).type === "text")
+    .map((c) => c.text)
+    .join("\n");
+}
+
+function cleanLine(line: string): string {
+  return line
+    .replace(/^\s*(?:[-*+]|\d+[.)]|#{1,6}|>)\s+/, "")
+    .replace(/\*\*|__|`/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/**
+ * Questions in a reply. Lines are first joined into paragraphs (a question
+ * that wraps over several source lines stays whole), list items and headings
+ * each start their own paragraph, code blocks are skipped, and every sentence
+ * ending in "?" becomes one question — in full, never truncated.
+ */
+export function extractQuestions(text: string): string[] {
+  const paragraphs: string[] = [];
+  let current: string[] = [];
+  let fenced = false;
+  const flush = () => {
+    if (current.length) paragraphs.push(current.join(" "));
+    current = [];
+  };
+  for (const raw of text.split("\n")) {
+    if (/^\s*(```|~~~)/.test(raw)) {
+      flush();
+      fenced = !fenced;
+      continue;
+    }
+    if (fenced) continue;
+    if (!raw.trim()) {
+      flush();
+      continue;
+    }
+    // A new list item / heading / quote starts a new paragraph.
+    if (/^\s*(?:[-*+]|\d+[.)]|#{1,6}|>)\s+/.test(raw)) flush();
+    current.push(raw);
+  }
+  flush();
+
+  const out: string[] = [];
+  for (const para of paragraphs) {
+    const clean = cleanLine(para);
+    if (!clean.includes("?")) continue;
+    // A "?" inside a URL (query string) is not a question: park URLs as tokens.
+    const urls: string[] = [];
+    const masked = clean.replace(/https?:\/\/\S+/g, (u) => `\u0000${urls.push(u) - 1}\u0000`);
+    if (!masked.includes("?")) continue;
+    for (const sentence of masked.match(/[^.!?]*(?:[.!](?!\s|$)[^.!?]*)*\?+/g) ?? []) {
+      const q = sentence.replace(/\u0000(\d+)\u0000/g, (_m, i: string) => urls[Number(i)] ?? "").trim();
+      if (q.length < 4 || out.includes(q)) continue;
+      out.push(q);
+      if (out.length >= MAX_QUESTIONS) return out;
+    }
+  }
+  return out;
+}
+
+/** Q/A pairs, nothing else in the buffer; no questions → an empty buffer. */
+export function buildTemplate(questions: readonly string[]): string {
+  if (questions.length === 0) return "";
+  return questions.flatMap((q, i) => [`Q${i + 1}. ${q}`, `A${i + 1}: `, ""]).join("\n").trimEnd() + " ";
+}
+
+/** Answers by question index (0-based); missing/empty → "". */
+export function parseTemplate(text: string, count: number): string[] {
+  if (count === 0) return [text.trim()];
+  const answers: string[] = Array.from({ length: count }, () => "");
+  let current = -1;
+  const buf: string[][] = answers.map(() => []);
+  for (const line of text.split("\n")) {
+    if (/^Q\d+\.\s/.test(line)) {
+      current = -1;
+      continue;
+    }
+    const a = line.match(/^A(\d+):\s?(.*)$/);
+    if (a) {
+      const idx = Number(a[1]) - 1;
+      current = idx >= 0 && idx < buf.length ? idx : -1;
+      if (current >= 0) buf[current]!.push(a[2]!);
+      continue;
+    }
+    if (current >= 0) buf[current]!.push(line);
+  }
+  return buf.map((lines) => lines.join("\n").trim());
+}
+
+/** One user message; undefined when nothing was answered. */
+export function composeAnswers(questions: readonly string[], answers: readonly string[], note = ""): string | undefined {
+  const parts: string[] = [];
+  const skipped: number[] = [];
+  if (questions.length === 0) {
+    const text = [answers[0] ?? "", note].map((s) => s.trim()).filter(Boolean).join("\n\n");
+    return text || undefined;
+  }
+  questions.forEach((q, i) => {
+    const a = (answers[i] ?? "").trim();
+    if (!a) {
+      skipped.push(i + 1);
+      return;
+    }
+    parts.push(`${i + 1}. > ${q}\n\n${a}`);
+  });
+  if (parts.length === 0 && !note.trim()) return undefined;
+  const lines = [parts.join("\n\n")];
+  if (note.trim()) lines.push(note.trim());
+  if (skipped.length) lines.push(`(Not answered: ${skipped.map((n) => `#${n}`).join(", ")})`);
+  return lines.filter(Boolean).join("\n\n");
+}