@danypops/pi-papyrus 0.35.0

package/README.md

@@ -0,0 +1,146 @@
+# @danypops/pi-papyrus
+
+The Pi extension for Papyrus: native tools, TUI panels, and context injection over `@danypops/papyrus`'s authenticated loopback daemon.
+
+## Tools
+
+The `papyrus_*` tools are the low-level graph-store API:
+
+- **`papyrus_query`** — filter by kind/status or search title and body
+- **`papyrus_graph`** — link artifacts, perform bounded traversal, or read the mutation event log
+- **`papyrus_show`** — read nested metadata and bounded edges, optionally running gates
+
+Agent-facing domain tools own lifecycle invariants and sit above this store API:
+
+- **`tasks`** — create/update/list/show/plan, manage the singleton active focus, replace evidence-bearing checklists, hierarchy/dependencies, lifecycle transitions, non-blocking gates, and review completion that focuses one deterministic ready successor without claiming effort
+- **`notes`** — capture/list/show deferred human intent, mark it consumed, promote it to an existing Task/Doc/Rule/Skill, or archive it with an explicit disposition
+- **`docs`** — create/update/list/show, activate/archive/reopen, and document-safe graph links; Note mutations remain behind the Notes facade
+- **`rules`** — create/update/list/show/preview, enable/disable, and attach governance gates to tasks
+- **`skills`** — create/update/list/show/invoke/run, enable/disable, create compatibility templates, and atomically instantiate parameterized workflow runs
+- **`playbooks`** — a completely different beast from Skills, not a subtype: a trigger and an ordered list of steps an agent reads and follows, never mechanically instantiated and never composed the way Skills call other Skills. create/update/list/show/invoke, enable/disable. A Playbook can declare named arguments (`{name, description?, required?}`, required defaults true); invoking with some unsupplied lists exactly which required ones are still missing and directs the agent to ask via `discuss` with `live:true` rather than guess
+
+Every tool operation is registered in the daemon's `/api/v1/ops` registry; parity is verified in tests. The task consumer uses the `tasks.graph` operation, which returns task nodes with explicit parent, child, and dependency IDs rather than leaking SQLite rows or asking the UI to reconstruct relationships.
+
+## Interactive frontends
+
+- `/tasks` — project/focused-graph scope, task lifecycle, append-only history, gates, dependencies, and nested metadata
+- `/note <request>` — directly capture one project-scoped deferred request without creating a Task
+- `/notes` — searchable project Notes inbox with consume, promote, and disposition-aware archive actions
+- `/docs` — searchable non-Note documents, lifecycle, details, edit, and graph links
+- `/rules` — severity/condition rows, exact injection preview, edit, enable/disable, and task gating
+- `/skills` — trigger/tools rows, edit, invocation into the editor, and artifact templates
+- `/playbooks` — trigger/tools rows, edit, invocation into the editor, and graph links
+- `/playbook <name>` — tab-completes active playbook titles and places that one's invocation directly in the editor, one step instead of browse-then-select; no argument falls back to the full `/playbooks` browser
+
+All frontends use daemon-backed domain operations; none opens SQLite from the Pi process. **Show details** opens a bounded navigable view across Tasks, Notes, Docs, Rules, legacy Skills, templates, and workflow Skills. User-authored bodies render as width-aware Markdown with headings, emphasis, links, quotes, lists, tables, inline/fenced code, syntax highlighting, and every color/decorative style derived dynamically from the active Pi theme. Generated lifecycle, metadata, checklist, gate, history, and relationship sections keep explicit semantic theme colors; relationships render as a small Unicode graph via `beautiful-mermaid` when the neighbor set is real and within the routed-rendering bound, falling back to a plain, still name-resolved arrow list otherwise. `↑/↓` scrolls, `←/→` pans wide relationships, and Esc returns to the browser; non-interactive clients receive stable source text.
+
+## Notes
+
+Notes are project-scoped `doc/note` artifacts for human requests that should be considered later. Capturing a Note does not create work, inject the entire inbox into prompts, or imply acceptance. The agent can use the `notes` domain tool to list and consume open Notes, decide whether to create a Task, Doc, Rule, or Skill through its owning domain tool, then promote the Note by linking that artifact. Archive requires one of `completed`, `duplicate`, `declined`, or `superseded`; promote archives with a `promoted` disposition and target ID. Capture, consumption, and disposition provenance remain in bounded Note history.
+
+The default inbox contains draft and consumed/active Notes, is bounded to 50 rows, and has a hard limit of 200. Bodies are capped at 10,000 characters. Generic document and graph lifecycle operations reject Note mutations so they cannot bypass disposition provenance.
+
+```bash
+papyrus notes capture "Investigate the retry policy" --json
+papyrus notes list --limit 25 --json
+papyrus notes show <note-id> --json
+papyrus notes consume <note-id> --json
+# Create the resulting artifact with tasks/docs/rules/skills first, then:
+papyrus notes promote <note-id> <target-id> --reason "Converted to tracked work" --json
+papyrus notes archive <note-id> declined --reason "No longer relevant" --json
+```
+
+A persistent widget (matching the Task widget) shows a simple `Notes N` count, scoped by default to the current project (CWD), so a growing inbox is visible without opening `/notes`.
+
+## Discuss
+
+Discuss is a native, persistent deliberation, distinct from a one-shot ask: it survives across turns and sessions, takes multiple rounds, and can genuinely block a Task's completion until settled or deferred. A Discussion is a `doc` artifact with `subtype: "discussion"` -- real graph citizenship (edges, show/list) without a fifth enforced artifact kind. Its fine-grained lifecycle (`active`/`deferred`/`settled`) lives in `extra.discussion`, since Papyrus enforces status vocabulary per kind, not per subtype.
+
+Rounds are a dedicated append-only child table (mirroring Task history's own shape): `open` records round 1, `reply` appends further rounds, refused once the Discussion is `deferred` or `settled` -- resume first. `defer` is explicitly non-blocking (paused, reason optional, resumable); `settle` is terminal, records an outcome, and archives the Doc. `block`/`unblock` manage the blocking relationship to a Task independently of `open`.
+
+Blocking is real: `tasks.complete` is refused while any `active` Discussion has a `blocks` edge to that Task. A `deferred` Discussion does not block -- "we will get back to this" is distinct from "resolved."
+
+`open`/`reply` can also pose a structured choice instead of (or alongside) free text: `options` (2-10 entries) plus `options_mode` -- `single` is mutually exclusive (exactly one pick), `multi` allows several. The Discussion remembers the pending choice (`extra.discussion.pendingOptions`/`pendingOptionsMode`) until a `reply` answers it with `selected`, validated against exactly what was offered and the mode's cardinality; a reply can also pose the *next* round's choice in the same call.
+
+Run `/discuss` for the interactive panel: browse every Discussion (the real `active`/`deferred`/`settled` state shown per row, alongside any choice awaiting an answer), open a scrollable transcript showing what was posed and picked in each round, and reply/defer/resume/settle or block/unblock a task without leaving the TUI. Replying to a pending choice shows a real picker -- the native single-select list for `single`, or a checkbox multi-select for `multi`, since no built-in multi-select exists in the Pi extension UI. Both modes append a numbered "type your own answer" row -- a genuinely open answer is exactly as valid as any posed option. The multi-select picker supports a number key as a direct quick-select (jump straight to that row instead of scrolling), and steadily highlights checked rows while dimming the rest so the eye reads "what's chosen" independent of cursor position; its cursor row blinks to mark focus. It also auto-cancels after 30s of zero input -- the very first keystroke of any kind stops that countdown permanently for that prompt. Opening a *new* Discussion is left to the agent (same as Docs/Rules/Skills) -- `/discuss` browses and drives existing ones.
+
+```bash
+papyrus discuss open --title "Naming" --actor alice --content "Should we rename this?" --blocks-json '["task-id"]' --json
+papyrus discuss open --title "Which approach" --actor alice --content "Pick one" --options-json '["A","B"]' --options-mode single --json
+papyrus discuss reply <discussion-id> --actor bob --content "I think so, here's why..." --json
+papyrus discuss reply <discussion-id> --actor bob --content "Going with B" --selected-json '["B"]' --json
+papyrus discuss defer <discussion-id> --reason "Waiting on design review" --json
+papyrus discuss resume <discussion-id> --json
+papyrus discuss settle <discussion-id> --settlement "Agreed: renaming to X" --json
+papyrus discuss show <discussion-id> --json
+```
+
+## Tasks
+
+Run `/tasks` for the interactive task panel:
+
+- `/` filters; arrow keys navigate; Enter opens task actions; `s` switches among the persisted current-project, focused-root graph, and explicit all-projects views
+- `g` opens the programmatic Unicode graph; Tab switches dependency/composition views and arrow keys pan
+- routed graph layouts are bounded to 48 nodes/96 edges; larger graphs use a deterministic, box-drawn line fallback, and renderer failures are contained inside the viewport rather than escaping Pi
+- advance the `todo → in-progress → review → done` lifecycle; failed review becomes `rejected`, retry returns to `in-progress`, and `canceled` is terminal
+- use **focus** as the independent singleton Task selection that automatic continuation follows; focusing, pausing, or resuming never changes lifecycle
+- starting nested effort moves todo ancestors to in-progress; submitting enters review; completing review checks both typed checklist proofs and executable gates
+- passing review marks only that task done and focuses one deterministic ready successor while leaving the successor todo until effort starts
+- successors are never auto-completed; fan-in, fan-out, diamonds, and disconnected DAGs remain explicit
+- inspect deterministic execution layers, readiness, a box-drawn nested hierarchy, composition, dependencies, evidence-bearing checklists, and verification gates
+- lifecycle colors are semantic and redundant with text/glyphs: To-Do grey, in-progress yellow, review blue, rejected orange, done green, and canceled red; `▶` marks active focus
+- Show details keeps Checklist and Validation gates separate from incidental Metadata, renders bounded post-migration lifecycle history with actor/source/reason and gate evidence, then renders relationships as a Unicode box-drawing graph footer; `↑/↓` scrolls and `←/→` pans wide graphs
+- the compact persistent widget shows the current scope label plus bounded open work in containment order and always retains active focus when it belongs to that scope, refreshed both on tool activity and a bounded background poll so a mutation from another session or a plain CLI call is reflected without needing a Papyrus-tool call to trigger it
+
+Authenticated CLI parity covers the changed lifecycle and focus operations:
+
+```bash
+papyrus tasks graph --json
+papyrus tasks scope --json
+papyrus tasks scope project --json
+papyrus tasks scope graph <root-id> --json
+papyrus tasks scope all --json
+papyrus tasks assign-project <task-id> [project-root] --json
+papyrus tasks active --json
+papyrus tasks history <id> --json
+papyrus tasks focus <id> --json
+papyrus tasks focused --json
+papyrus tasks pause --json
+papyrus tasks unpause --json
+papyrus tasks clear-focus --json
+papyrus tasks update <id> --title "Revised title" --body "Revised body" --json
+papyrus tasks update <id> --status todo --reason "created with legacy default" --json
+papyrus tasks start <id> --json
+papyrus tasks submit <id> --json
+papyrus tasks complete <id> --json
+papyrus tasks reject <id> --json
+papyrus tasks retry <id> --json
+papyrus tasks cancel <id> --json
+```
+
+Task edits mutate the existing Papyrus-owned Task identity and append an `updated` event; title, body, and labels can be revised without canceling the Task or creating a replacement. Lifecycle, relationships, gates, checklist metadata, scope, and focus remain intact. The same `update` action provides a narrowly guarded recovery for Tasks accidentally created terminal by a legacy default: `status=todo` requires an audit reason, cannot be combined with content edits, only applies when `created` is the sole lifecycle event, and appends `creation_recovered` rather than rewriting history.
+
+### Focus-driven automatic continuation
+
+Automatic continuation is a property of the singleton Task focus, not a per-Task automation flag. An active focus continues at Pi's public `agent_settled` boundary when Pi is idle and has no queued messages. `tasks pause` preserves the focused Task while stopping continuation; `tasks unpause` resumes it; `tasks clear-focus` removes it. Replacing focus selects an existing Task rather than creating or canceling one.
+
+Continuation is single-flight and bounded to 20 automatic turns or 6 unchanged Task snapshots. Reaching either bound persists a paused focus and records the reason in append-only Task history. Human input resumes only these automatically paused focuses; an explicit user pause remains paused.
+
+Checklist criteria are an item-to-proof map. Every new item requires one or more typed references to inspectable evidence; proof presence does not imply that the evidence passed an executable gate:
+
+```ts
+checklist: {
+  "Write failing skill-row tests": {
+    proof: [
+      { type: "file", target: "test/frontends.test.ts" },
+      { type: "symbol", target: "test/frontends.test.ts#skill row test" }
+    ]
+  }
+}
+```
+
+Proof types are `file`, `symbol`, `code`, `test`, `command`, `artifact`, and `url`. Existing array checklists remain readable as legacy items with `proof: missing`; Papyrus does not invent evidence.
+
+Papyrus also injects an Alef-style reconciliation block at `before_agent_start` while work remains: `Current`, `Desired`, `Verify`, and `Next`. The agent is explicitly instructed to ask **"Did we accomplish this task?"** and run review before marking it done. The injection disappears when every task is done or canceled.
+
+After assembling each system-prompt addition, Papyrus emits a versioned `papyrus.context-injection.v1` observation on Pi's shared extension event bus. It contains only exact byte/character sizes, Rule count, a labeled token estimate, prompt share, sequence, and a SHA-256 payload fingerprint; Rule/Task text, prompts, project paths, and credentials are never included. Jittor can persist and assess these observations without Papyrus maintaining a second telemetry store.

package/THIRD_PARTY_LICENSES.md

@@ -0,0 +1,31 @@
+# Third-party licenses
+
+## pi-ask-user (MIT)
+
+`extension/src/discuss-ask-view.ts` and `extension/src/discuss-ask-layout.ts` are substantially
+adapted from [pi-ask-user](https://github.com/edlsh/pi-ask-user), used here as the interactive
+UI for Discuss's own `live:true` synchronous ask.
+
+```
+MIT License
+
+Copyright (c) 2026 Enzo Lucchesi
+
+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/extension/src/active-task-continuation.ts

@@ -0,0 +1,131 @@
+export interface ActiveTaskMarker {
+	id: string;
+	title: string;
+	updated_at: string;
+}
+
+export interface ActiveTaskContinuationOptions {
+	maxTurns: number;
+	maxUnchangedTurns: number;
+}
+
+export interface ActiveTaskContinuationState {
+	queued: boolean;
+	consecutiveTurns: number;
+	unchangedTurns: number;
+	pausedReason?: string;
+}
+
+export interface ActiveTaskContinuationDecision {
+	action: "continue" | "wait" | "pause";
+	reason: string;
+	prompt?: string;
+}
+
+const TITLE_LIMIT = 120;
+const AUTOMATIC_PAUSE_PREFIX = "automatic continuation paused:";
+
+export function automaticPauseReason(reason: string): string {
+	return `${AUTOMATIC_PAUSE_PREFIX} ${reason}`;
+}
+
+export function shouldResumeFocusOnHumanInput(status: string, pauseReason?: string): boolean {
+	return status === "paused" && pauseReason?.startsWith(AUTOMATIC_PAUSE_PREFIX) === true;
+}
+
+function fingerprint(task: ActiveTaskMarker): string {
+	return `${task.id}:${task.updated_at}`;
+}
+
+function continuationPrompt(task: ActiveTaskMarker): string {
+	return [
+		"Continue the active Papyrus Task now; do not hand off merely because the previous Pi run settled.",
+		"Reconcile its lifecycle, take the next concrete action, use tools, submit it for review when implementation effort is ready, and run gates plus checklist review before completion.",
+		"Do not shrink the task's scope to whatever fits in this turn, and do not treat a status update or summary as a substitute for doing the work or as proof of completion.",
+		"If something blocks progress, do not reject or pause on the first obstacle -- only after it genuinely recurs, and only when the task truly cannot proceed without external input.",
+		`Active task: ${task.title.slice(0, TITLE_LIMIT)}`,
+	].join("\n");
+}
+
+export class ActiveTaskContinuation {
+	private queued = false;
+	private consecutiveTurns = 0;
+	private unchangedTurns = 0;
+	private lastFingerprint: string | undefined;
+	private pausedReason: string | undefined;
+
+	constructor(private readonly options: ActiveTaskContinuationOptions) {
+		if (!Number.isInteger(options.maxTurns) || options.maxTurns < 1) throw new Error("maxTurns must be a positive integer");
+		if (!Number.isInteger(options.maxUnchangedTurns) || options.maxUnchangedTurns < 1) {
+			throw new Error("maxUnchangedTurns must be a positive integer");
+		}
+	}
+
+	evaluate(task: ActiveTaskMarker | null, context: { idle: boolean; pendingMessages: boolean }): ActiveTaskContinuationDecision {
+		if (!context.idle) return { action: "wait", reason: "Pi is not settled" };
+		if (context.pendingMessages) return { action: "wait", reason: "Pi already has pending messages" };
+		if (this.queued) return { action: "wait", reason: "continuation already queued" };
+		if (!task) {
+			this.resetProgress();
+			return { action: "wait", reason: "no active task" };
+		}
+
+		const currentFingerprint = fingerprint(task);
+		if (currentFingerprint !== this.lastFingerprint) {
+			this.lastFingerprint = currentFingerprint;
+			this.unchangedTurns = 0;
+			this.pausedReason = undefined;
+		} else {
+			this.unchangedTurns += 1;
+		}
+
+		if (this.consecutiveTurns >= this.options.maxTurns) {
+			return this.pause(`automatic turn limit reached (${this.options.maxTurns})`);
+		}
+		if (this.unchangedTurns >= this.options.maxUnchangedTurns) {
+			return this.pause(`no task progress after ${this.options.maxUnchangedTurns} automatic turns`);
+		}
+
+		this.queued = true;
+		this.consecutiveTurns += 1;
+		return {
+			action: "continue",
+			reason: "an active task remains",
+			prompt: continuationPrompt(task),
+		};
+	}
+
+	onAgentStart(): void {
+		this.queued = false;
+	}
+
+	onCompaction(): void {
+		this.queued = false;
+	}
+
+	onHumanInput(): void {
+		this.resetProgress();
+	}
+
+	status(): ActiveTaskContinuationState {
+		return {
+			queued: this.queued,
+			consecutiveTurns: this.consecutiveTurns,
+			unchangedTurns: this.unchangedTurns,
+			...(this.pausedReason ? { pausedReason: this.pausedReason } : {}),
+		};
+	}
+
+	private pause(reason: string): ActiveTaskContinuationDecision {
+		this.pausedReason = reason;
+		return { action: "pause", reason };
+	}
+
+	private resetProgress(): void {
+		this.queued = false;
+		this.consecutiveTurns = 0;
+		this.unchangedTurns = 0;
+		this.lastFingerprint = undefined;
+		this.pausedReason = undefined;
+	}
+}

package/extension/src/artifact-browser.ts

@@ -0,0 +1,227 @@
+import type { ExtensionCommandContext, Theme } from "@earendil-works/pi-coding-agent";
+import { DynamicBorder, rawKeyHint } from "@earendil-works/pi-coding-agent";
+import { Container, Input, Spacer, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { SEED_RELATIONS, type Artifact, type OperationName } from "@danypops/papyrus";
+import type { StatusPresentation } from "./artifact-status-presentation.ts";
+import { artifactDetailsText } from "./artifact-detail-format.ts";
+import { showArtifactDetailView } from "./artifact-detail-view.ts";
+import { callService } from "./service-client.ts";
+
+export { artifactDetailsText } from "./artifact-detail-format.ts";
+
+const BROWSER_QUERY_LIMIT = 500;
+const BROWSER_VISIBLE_ROWS = 20;
+const DETAIL_GRAPH_DEPTH = 4;
+const DETAIL_GRAPH_NODES = 100;
+
+export interface ArtifactBrowserConfig {
+	kind: string;
+	title: string;
+	statusOrder: string[];
+	presentation: Record<string, StatusPresentation>;
+	listOperation?: OperationName;
+	listInput?: Record<string, unknown>;
+	rowMeta(row: Artifact, theme: Theme): string;
+	actions(row: Artifact): string[];
+	handleAction(choice: string, row: Artifact, ctx: ExtensionCommandContext): Promise<void>;
+}
+
+export function filterArtifactRows(rows: Artifact[], query: string): Artifact[] {
+	const needle = query.trim().toLowerCase();
+	if (!needle) return [...rows];
+	return rows.filter((row) => [
+		row.id,
+		row.title,
+		row.body,
+		row.subtype,
+		row.labels.join(" "),
+		JSON.stringify(row.extra),
+	].some((value) => value.toLowerCase().includes(needle)));
+}
+
+export function statusSummary(rows: Artifact[], order: string[]): Array<{ status: string; count: number }> {
+	const counts = new Map<string, number>();
+	for (const row of rows) counts.set(row.status, (counts.get(row.status) ?? 0) + 1);
+	return order.filter((status) => counts.has(status)).map((status) => ({ status, count: counts.get(status)! }));
+}
+
+async function loadArtifacts(config: ArtifactBrowserConfig): Promise<Artifact[]> {
+	return callService<Record<string, unknown>, Artifact[]>(config.listOperation ?? "artifact.query", {
+		kind: config.kind,
+		limit: BROWSER_QUERY_LIMIT,
+		...(config.listInput ?? {}),
+	});
+}
+
+export type ArtifactDetailLoader = (
+	operation: OperationName,
+	input: Record<string, unknown>,
+) => Promise<Artifact | null>;
+
+const loadArtifactDetails: ArtifactDetailLoader = (operation, input) =>
+	callService<Record<string, unknown>, Artifact | null>(operation, input);
+
+export async function showArtifactDetails(
+	ctx: ExtensionCommandContext,
+	id: string,
+	operation: OperationName = "artifact.show",
+	input: Record<string, unknown> = {},
+	load: ArtifactDetailLoader = loadArtifactDetails,
+): Promise<void> {
+	try {
+		const artifact = await load(operation, {
+			id,
+			...input,
+			tree: true,
+			depth: DETAIL_GRAPH_DEPTH,
+			max_nodes: DETAIL_GRAPH_NODES,
+		});
+		if (!artifact) { ctx.ui.notify("Artifact not found", "error"); return; }
+		await showArtifactDetailView(ctx, artifact);
+	} catch (error) {
+		ctx.ui.notify(`Show details failed: ${error instanceof Error ? error.message : error}`, "error");
+	}
+}
+
+export async function linkFromArtifact(ctx: ExtensionCommandContext, fromId: string, fixedRelation?: string): Promise<void> {
+	const target = await ctx.ui.input("Target artifact id:", "");
+	if (!target) return;
+	const relation = fixedRelation ?? await ctx.ui.select("Relation", [...SEED_RELATIONS]);
+	if (!relation) return;
+	try {
+		await callService("graph.link", { from: fromId, relation, to: target });
+		ctx.ui.notify(`Artifacts linked via ${relation}`, "info");
+	} catch (error) {
+		ctx.ui.notify(`Link failed: ${error instanceof Error ? error.message : error}`, "error");
+	}
+}
+
+export async function setArtifactStatus(ctx: ExtensionCommandContext, id: string, status: string): Promise<void> {
+	try {
+		const artifact = await callService<Record<string, unknown>, Artifact | null>("graph.status", { id, status });
+		if (!artifact) { ctx.ui.notify("Artifact not found", "error"); return; }
+		ctx.ui.notify(`${artifact.title} → [${artifact.status}]`, "info");
+	} catch (error) {
+		ctx.ui.notify(`Status change failed: ${error instanceof Error ? error.message : error}`, "error");
+	}
+}
+
+export async function showArtifactBrowser(ctx: ExtensionCommandContext, config: ArtifactBrowserConfig): Promise<void> {
+	if (!ctx.hasUI) {
+		ctx.ui.notify(`/${config.kind}s requires interactive mode`, "warning");
+		return;
+	}
+	let rows = await loadArtifacts(config);
+	if (rows.length === 0) {
+		ctx.ui.notify(`No ${config.kind} artifacts yet. Ask the agent to create one.`, "info");
+		return;
+	}
+
+	for (;;) {
+		const selected = await renderPanel(ctx, rows, config);
+		if (selected === undefined) return;
+		if (selected === "refresh") { rows = await loadArtifacts(config); continue; }
+		const choices = config.actions(selected);
+		const choice = await ctx.ui.select(selected.title, choices);
+		if (!choice) continue;
+		await config.handleAction(choice, selected, ctx);
+		rows = await loadArtifacts(config);
+	}
+}
+
+function renderPanel(
+	ctx: ExtensionCommandContext,
+	rows: Artifact[],
+	config: ArtifactBrowserConfig,
+): Promise<Artifact | "refresh" | undefined> {
+	return ctx.ui.custom<Artifact | "refresh" | undefined>((tui, theme, _keybindings, done) => {
+		const input = new Input();
+		let searchActive = false;
+		let filtered = [...rows];
+		let selectedIndex = 0;
+
+		function applyFilter(): void {
+			filtered = filterArtifactRows(rows, input.getValue());
+			selectedIndex = 0;
+		}
+
+		const header = {
+			invalidate() {},
+			render(width: number): string[] {
+				const title = theme.bold(config.title);
+				const hint = searchActive
+					? rawKeyHint("esc", "clear")
+					: [rawKeyHint("enter", "actions"), rawKeyHint("/", "filter"), rawKeyHint("r", "refresh"), rawKeyHint("esc", "close")]
+						.join(theme.fg("muted", " · "));
+				const spacing = Math.max(1, width - visibleWidth(title) - visibleWidth(hint));
+				const summary = statusSummary(rows, config.statusOrder)
+					.map(({ status, count }) => {
+						const presentation = config.presentation[status];
+						const glyph = presentation ? theme.fg(presentation.color, presentation.glyph) : status;
+						return `${glyph} ${count} ${status}`;
+					})
+					.join(", ");
+				return [
+					truncateToWidth(`${title}${" ".repeat(spacing)}${hint}`, width, ""),
+					truncateToWidth(theme.fg("muted", summary), width, ""),
+				];
+			},
+		};
+
+		const list = {
+			invalidate() {},
+			render(width: number): string[] {
+				const lines = searchActive ? [...input.render(width), ""] : [""];
+				if (filtered.length === 0) return [...lines, theme.fg("muted", `  No matching ${config.kind}s`)];
+				const start = Math.max(0, Math.min(selectedIndex - Math.floor(BROWSER_VISIBLE_ROWS / 2), filtered.length - BROWSER_VISIBLE_ROWS));
+				const end = Math.min(start + BROWSER_VISIBLE_ROWS, filtered.length);
+				for (let index = start; index < end; index++) {
+					const row = filtered[index]!;
+					const selected = index === selectedIndex;
+					const cursor = selected ? theme.fg("accent", "❯") : " ";
+					const presentation = config.presentation[row.status];
+					const glyph = presentation ? theme.fg(presentation.color, presentation.glyph) : "?";
+					const title = selected ? theme.bold(row.title) : row.title;
+					const meta = config.rowMeta(row, theme);
+					lines.push(truncateToWidth(`${cursor} ${glyph} ${title}${meta ? `${theme.fg("dim", " · ")}${meta}` : ""}`, width, ""));
+				}
+				lines.push(theme.fg("muted", `  ${selectedIndex + 1}/${filtered.length} ${config.kind}`));
+				return lines;
+			},
+		};
+
+		const container = new Container();
+		container.addChild(new Spacer(1));
+		container.addChild(new DynamicBorder());
+		container.addChild(new Spacer(1));
+		container.addChild(header);
+		container.addChild(new Spacer(1));
+		container.addChild(list);
+		container.addChild(new Spacer(1));
+		container.addChild(new DynamicBorder());
+
+		return {
+			render: (width: number) => container.render(width),
+			invalidate: () => container.invalidate(),
+			handleInput(data: string) {
+				if (searchActive) {
+					if (data === "\x1b") { searchActive = false; applyFilter(); }
+					else if (data === "\r") searchActive = false;
+					else { input.handleInput(data); applyFilter(); }
+					tui.requestRender();
+					return;
+				}
+				switch (data) {
+					case "\x1b[A": selectedIndex = (selectedIndex - 1 + filtered.length) % Math.max(filtered.length, 1); break;
+					case "\x1b[B": selectedIndex = (selectedIndex + 1) % Math.max(filtered.length, 1); break;
+					case "/": searchActive = true; break;
+					case "r": done("refresh"); return;
+					case "\r": { const row = filtered[selectedIndex]; if (row) done(row); return; }
+					case "\x1b": done(undefined); return;
+					default: return;
+				}
+				tui.requestRender();
+			},
+		};
+	});
+}

package/extension/src/artifact-detail-format.ts

@@ -0,0 +1,38 @@
+import type { Artifact } from "@danypops/papyrus";
+import { formatMetadata } from "./artifact-format.ts";
+
+export interface ArtifactDetailContent {
+	title: string;
+	identity: string;
+	body: string;
+	labels: string[];
+	metadata: string[];
+	relationships: string[];
+}
+
+export function artifactDetailContent(artifact: Artifact, relationshipLines: string[] = []): ArtifactDetailContent {
+	return {
+		title: artifact.title,
+		identity: `${artifact.id} [${artifact.kind}|${artifact.status}]${artifact.subtype ? ` · ${artifact.subtype}` : ""}`,
+		body: artifact.body || "(no body)",
+		labels: [...artifact.labels],
+		metadata: Object.keys(artifact.extra).length > 0 ? formatMetadata(artifact.extra) : [],
+		relationships: relationshipLines,
+	};
+}
+
+/**
+ * Deliberately plain, unlike ArtifactDetailViewport's TUI body (renderMarkdownBody): this path
+ * feeds ctx.ui.notify(), used outside interactive mode (RPC, piped/non-terminal callers) where
+ * ANSI escape codes are noise or corruption, not formatting. Raw Markdown source stays readable
+ * as plain text either way. relationshipLines is still upgraded (a real graph or a resolved
+ * arrow list, never raw ids) since that needs no color to read.
+ */
+export function artifactDetailsText(artifact: Artifact, relationshipLines: string[] = []): string {
+	const content = artifactDetailContent(artifact, relationshipLines);
+	let output = `${content.title}\n${content.identity}\n\n${content.body}`;
+	if (content.labels.length > 0) output += `\n\nLabels: ${content.labels.join(", ")}`;
+	if (content.metadata.length > 0) output += `\n\nMetadata:\n${content.metadata.map((line) => `  ${line}`).join("\n")}`;
+	if (content.relationships.length > 0) output += `\n\nRelationships:\n${content.relationships.map((line) => `  ${line}`).join("\n")}`;
+	return output;
+}