@danypops/pi-papyrus 0.44.0 → 0.45.0

package/README.md

@@ -10,13 +10,14 @@ The `papyrus_*` tools are the low-level graph-store API:
 - **`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. `discuss` is still a single tool with an `action` parameter -- `live:true` needs an interactive UI round-trip a stateless Vehicle operation can't express. `notes`, `docs`, `rules`, `playbooks`, and `tasks` are projected from Papyrus's own Vehicle as one real tool per operation (`notes_capture`, `rules_create`, `playbooks_invoke`, `tasks_complete`, and so on) -- no `action` dispatch, each with its own schema:
+Agent-facing domain tools own lifecycle invariants and sit above this store API. `notes`, `docs`, `rules`, `playbooks`, `tasks`, and `discuss` are all projected from Papyrus's own Vehicle as one real tool per operation (`notes_capture`, `rules_create`, `playbooks_invoke`, `tasks_complete`, `discuss_open`, and so on) -- no `action` dispatch, each with its own schema. `discuss_open`/`discuss_reply` additionally accept `live: true` for a synchronous human round-trip, via vehicle-client-pi's `interactiveFollowUps` hook rather than a bespoke tool:
 
 - **tasks** (`tasks_create`, `tasks_update`, `tasks_list`, `tasks_show`, `tasks_plan`, `tasks_graph`, `tasks_focus`, `tasks_pause`, `tasks_unpause`, `tasks_clear_focus`, `tasks_start`, `tasks_submit`, `tasks_complete`, `tasks_reject`, `tasks_retry`, `tasks_cancel`, `tasks_cancel_subtree`, `tasks_run_gates`, `tasks_set_checklist`, `tasks_set_gates`, `tasks_depend`, `tasks_undepend`, `tasks_contain`, `tasks_uncontain`, `tasks_claim`, `tasks_heartbeat_lease`, `tasks_release_lease`, `tasks_lease`, `tasks_context`, `tasks_event_feed`, `tasks_scope`, `tasks_set_scope`, `tasks_assign_project`, `tasks_active`, `tasks_focused`, `tasks_history`) — manages the singleton active focus, evidence-bearing checklists, hierarchy/dependencies, lifecycle transitions, non-blocking gates, and review completion that focuses one deterministic ready successor without claiming effort. `project_root` is required wherever a plain `tasks` call would otherwise need one (list/graph/plan/active/focused/scope/context/create) -- there is no ambient Pi cwd server-side. `tasks_focus`/`tasks_pause`/`tasks_unpause`/`tasks_clear_focus` still authorize their write via this session's own cached secret, and still broadcast `papyrus.task-focus.v1` on Pi's own event bus for a sibling extension to observe, exactly as before
 - **notes** (`notes_capture`, `notes_list`, `notes_show`, `notes_consume`, `notes_promote`, `notes_archive`) — capture/list/show deferred human intent, mark it consumed, promote it to an existing Task/Doc/Rule/Playbook, or archive it with an explicit disposition
 - **docs** (`docs_create`, `docs_list`, `docs_show`, `docs_activate`, `docs_archive`, `docs_reopen`, `docs_link`, `docs_assign_project`, `docs_update`) — activate/archive/reopen and document-safe graph links; Note mutations remain behind the Notes facade
 - **rules** (`rules_create`, `rules_list`, `rules_show`, `rules_preview`, `rules_enable`, `rules_disable`, `rules_gate`, `rules_assign_project`, `rules_update`) — enable/disable and attach governance gates to tasks
-- **playbooks** (`playbooks_create`, `playbooks_list`, `playbooks_show`, `playbooks_invoke`, `playbooks_preview`, `playbooks_enable`, `playbooks_disable`, `playbooks_assign_project`, `playbooks_update`, `playbooks_contain`, `playbooks_uncontain`, `playbooks_depend`, `playbooks_undepend`) — a trigger and an ordered list of steps. Each step is a plain prose string (a task), or a structured object: `{kind:'doc',title,body?,subtype?,labels?}` creates a Doc, `{kind:'rule',title,body?,condition?,action?,severity?,labels?}` creates a Rule, `{kind:'call',title,playbookId,arguments?}` nests another Playbook's own run as a pipeline step gated in the same sequence, `{kind:'task',title?,body}` is an explicit task step. `playbooks_invoke` recycles the shared blueprint materialization engine: it compiles the steps and any `contain`/`depend` composition into real artifacts (a Task per plain/task step, a Doc/Rule per doc/rule step, a nested run per call step), wires task-like steps with `dependsOn` so completing one auto-focuses the next, and focuses the first real task. No text dump — one step surfaces at a time, as it becomes the focused task, same as any other Task. `playbooks_contain`/`playbooks_uncontain` nest a child Playbook inside a parent (its steps run after the parent's own, as part of it); `playbooks_depend`/`playbooks_undepend` chain a prerequisite Playbook before another (it must fully complete first) -- both are whole-Playbook composition, distinct from a `call` step's finer-grained, single-step nesting. `playbooks_preview` renders the whole tree as text with no side effects, for reading before invoking. A Playbook can declare named arguments (`{name, description?, required?, type?('string'|'number'|'boolean', default 'string'), enum?, default?}`, required defaults true; referenced in step text/call arguments as `{{name}}`); invoking with a required one unsupplied creates nothing and reports exactly which are still missing, directing the agent to ask via `discuss` with `live:true` rather than guess
+- **playbooks** (`playbooks_create`, `playbooks_list`, `playbooks_show`, `playbooks_invoke`, `playbooks_preview`, `playbooks_enable`, `playbooks_disable`, `playbooks_assign_project`, `playbooks_update`, `playbooks_contain`, `playbooks_uncontain`, `playbooks_depend`, `playbooks_undepend`) — a trigger and an ordered list of steps. Each step is a plain prose string (a task), or a structured object: `{kind:'doc',title,body?,subtype?,labels?}` creates a Doc, `{kind:'rule',title,body?,condition?,action?,severity?,labels?}` creates a Rule, `{kind:'call',title,playbookId,arguments?}` nests another Playbook's own run as a pipeline step gated in the same sequence, `{kind:'task',title?,body}` is an explicit task step. `playbooks_invoke` recycles the shared blueprint materialization engine: it compiles the steps and any `contain`/`depend` composition into real artifacts (a Task per plain/task step, a Doc/Rule per doc/rule step, a nested run per call step), wires task-like steps with `dependsOn` so completing one auto-focuses the next, and focuses the first real task. No text dump — one step surfaces at a time, as it becomes the focused task, same as any other Task. `playbooks_contain`/`playbooks_uncontain` nest a child Playbook inside a parent (its steps run after the parent's own, as part of it); `playbooks_depend`/`playbooks_undepend` chain a prerequisite Playbook before another (it must fully complete first) -- both are whole-Playbook composition, distinct from a `call` step's finer-grained, single-step nesting. `playbooks_preview` renders the whole tree as text with no side effects, for reading before invoking. A Playbook can declare named arguments (`{name, description?, required?, type?('string'|'number'|'boolean', default 'string'), enum?, default?}`, required defaults true; referenced in step text/call arguments as `{{name}}`); invoking with a required one unsupplied creates nothing and reports exactly which are still missing, directing the agent to ask via `discuss_open`/`discuss_reply` with `live:true` rather than guess
+- **discuss** (`discuss_open`, `discuss_reply`, `discuss_defer`, `discuss_resume`, `discuss_settle`, `discuss_block`, `discuss_unblock`, `discuss_show`, `discuss_rounds`, `discuss_list`) — a Discussion persists across multiple rounds and can genuinely block a Task's completion until settled or deferred (`discuss_block`/`discuss_unblock`). `discuss_reply` is refused once deferred or settled -- `discuss_resume` first. `discuss_open`/`discuss_reply` can pose a structured choice via `options` (2-10 entries, each a bare string or `{title, description}`) + `options_mode` (`single`/`multi`); a later `discuss_reply` answers it via `selected`, validated against it. `live: true` on either gets the human's answer synchronously in the same tool call -- the operation itself always durably records the round first (exactly like every other Vehicle operation), then an optional local prompt (the pending choice's picker if one was posed, otherwise a freeform question) runs via a per-operation `interactiveFollowUps` resolver (see `@danypops/vehicle-client-pi`), degrading silently to the plain async round when there's no interactive UI
 
 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.
 
@@ -52,7 +53,7 @@ A persistent widget (matching the Task widget) shows a simple `Notes N` count, s
 
 ## 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.
+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 `task` artifact with `subtype: "discussion"` -- real graph citizenship (edges, show/list, `blocks`) without a dedicated enforced artifact kind of its own. 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`.
 

package/extension/src/discuss-live-follow-up.ts

@@ -0,0 +1,66 @@
+/**
+ * discuss.open/discuss.reply's live:true synchronous human round-trip -- the
+ * one piece of discuss's own retired pi.registerTool() the plain
+ * request/response Vehicle projection can't express on its own, wired in via
+ * vehicle-client-pi's interactiveFollowUps hook (vehicle-notes-client.ts).
+ *
+ * The primary invoke() always durably records the round first, exactly like
+ * every other Vehicle operation -- this only ever adds an OPTIONAL synchronous
+ * prompt on top when ctx.hasUI and the caller actually asked for one. No
+ * answer (canceled, no UI, live not requested) falls back to the operation's
+ * own default content/details, matching the retired tool's exact fallback
+ * behavior.
+ */
+import type { DiscussionAndRounds } from "@danypops/papyrus";
+import { readDiscussionExtra } from "@danypops/papyrus";
+import type { PiVehicleInteractiveFollowUp } from "@danypops/vehicle-client-pi";
+import { askQuestion } from "./discuss-ask-view.ts";
+
+export const discussLiveFollowUp: PiVehicleInteractiveFollowUp = async (request, output, client) => {
+	const live = (request.input as { live?: unknown } | undefined)?.live === true;
+	if (!live || !request.context.hasUI) return undefined;
+
+	const result = output as DiscussionAndRounds;
+	const pending = (() => {
+		try {
+			return readDiscussionExtra(result.discussion.extra);
+		} catch {
+			return undefined;
+		}
+	})();
+	// The just-recorded round's own content IS the real question -- a generic "Reply to
+	// <title>:" wrapper as the primary question, with the real content demoted to
+	// "Context:", left a human staring at a labeled-backwards prompt (live-observed on the
+	// retired tool). The wrapper is now only a fallback for the degenerate case of empty
+	// content; the title becomes a plain orientation subtitle instead.
+	const question = result.rounds[0]?.content?.trim() || `Reply to "${result.discussion.title}":`;
+	const subtitle = result.discussion.title;
+	const answer = await askQuestion(request.context, {
+		question,
+		subtitle,
+		onUpdate: request.onUpdate,
+		signal: request.signal,
+		...(pending?.pendingOptions && pending.pendingOptions.length > 0 && pending.pendingOptionsMode
+			? {
+					options: pending.pendingOptions.map((title, index) => ({
+						title,
+						description: pending.pendingOptionDescriptions?.[index] || undefined,
+					})),
+					allowMultiple: pending.pendingOptionsMode === "multi",
+				}
+			: {}),
+	});
+	if (!answer) return undefined; // canceled, or no UI capable of answering -- default content/details stand
+
+	const answered = (await client.invoke("discuss.reply", 1, {
+		id: result.discussion.id,
+		actor: "human",
+		content: answer.content,
+		...(answer.selected ? { selected: answer.selected } : {}),
+		source: "discuss-live",
+	})) as DiscussionAndRounds;
+	return {
+		content: [{ type: "text", text: `"${answered.discussion.title}": ${answer.content}` }],
+		output: answered,
+	};
+};

package/extension/src/discuss.ts

@@ -1,16 +1,18 @@
 /**
  * discuss.ts — /discuss interactive panel.
  * Reuses the generic artifact browser (artifact-browser.ts), same as docs.ts/rules.ts/notes.ts:
- * a Discussion is a `doc` artifact, so the browser's list/filter/refresh/select-action loop
- * applies unchanged. The one real wrinkle is that Discuss's meaningful lifecycle state
- * (active/deferred/settled) lives in extra.discussion, not the shared doc status column the
- * browser colors its row glyph by (see artifact-status-presentation.ts's DISCUSSION_STATE_PRESENTATION
- * comment) -- so the real state is surfaced in rowMeta text instead, the same way rules.ts
- * surfaces severity and notes.ts surfaces history count, both also not the row glyph.
+ * a Discussion is a `task` artifact (subtype "discussion"), so the browser's
+ * list/filter/refresh/select-action loop applies unchanged. The one real wrinkle is that
+ * Discuss's meaningful lifecycle state (active/deferred/settled) lives in extra.discussion, not
+ * the shared status column the browser colors its row glyph by (see
+ * artifact-status-presentation.ts's DISCUSSION_STATE_PRESENTATION comment) -- so the real state
+ * is surfaced in rowMeta text instead, the same way rules.ts surfaces severity and notes.ts
+ * surfaces history count, both also not the row glyph.
  *
- * Creating a new Discussion is left to the agent (the discuss tool), matching docs.ts/rules.ts/
- * playbooks.ts precedent -- Notes is the one kind with a human-facing creation command (/note),
- * because Notes exists specifically as a human-authored inbox.
+ * Creating a new Discussion is left to the agent (discuss_open, Vehicle-projected -- see
+ * vehicle-notes-client.ts), matching docs.ts/rules.ts/playbooks.ts precedent -- Notes is the one
+ * kind with a human-facing creation command (/note), because Notes exists specifically as a
+ * human-authored inbox.
  */
 
 import { type Artifact, type DiscussionAndRounds, readDiscussionExtra } from "@danypops/papyrus";
@@ -82,7 +84,7 @@ function discussionActions(discussion: Artifact): string[] {
 
 export async function showDiscussions(ctx: ExtensionCommandContext): Promise<void> {
 	await showArtifactBrowser(ctx, {
-		kind: "doc",
+		kind: "discussion",
 		title: "Discussions",
 		listOperation: "discuss.list",
 		statusOrder: ["draft", "active", "archived"],

package/extension/src/domain-tools.ts

@@ -1,98 +1,6 @@
-import { type Artifact, type DiscussionAndRounds, type DiscussionRound, type OperationName, readDiscussionExtra } from "@danypops/papyrus";
-import type { AgentToolUpdateCallback, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
-import { askQuestion } from "./discuss-ask-view.ts";
+import type { Artifact, OperationName } from "@danypops/papyrus";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { callService } from "./service-client.ts";
-import { renderPapyrusToolCall, renderPapyrusToolResult } from "./tool-rendering/index.ts";
-import {
-	createArtifactDetails,
-	createArtifactListDetails,
-	createModelContent,
-	createPreviewDetails,
-} from "./tool-rendering/render-model.ts";
-
-function text(message: string, details: unknown = {}) {
-	const modelContent = createModelContent(message);
-	return { content: [{ type: "text" as const, text: modelContent.text }], details };
-}
-
-/**
- * live:true's synchronous half: reuses the same Discuss-owned ask UI (discuss-ask-view.ts) the
- * /discuss TUI's own "Reply" action uses when the just-created round posed a structured choice,
- * or a plain freeform prompt otherwise -- so "ask" covers both a completely open question and a
- * choice tied to this specific Discussion. Returns undefined on cancel or when no interactive UI
- * is available, never throws -- an unanswered live prompt still leaves the round it already
- * recorded intact.
- */
-/**
- * The discuss tool accepts each option as either a bare string (self-evident choices) or
- * {title, description} (a real tradeoff worth spelling out) -- normalizes to the two parallel
- * arrays discuss.open/discuss.reply actually expect (options: string[], option_descriptions:
- * string[], index-aligned, empty string meaning "none for this one"). Mutates params in place.
- */
-function normalizeDiscussOptions(params: Record<string, unknown>): void {
-	const raw = params.options;
-	if (!Array.isArray(raw)) return;
-	let anyDescription = false;
-	const titles: string[] = [];
-	const descriptions: string[] = [];
-	for (const entry of raw) {
-		if (typeof entry === "string") {
-			titles.push(entry);
-			descriptions.push("");
-			continue;
-		}
-		if (entry && typeof entry === "object" && typeof (entry as Record<string, unknown>).title === "string") {
-			const record = entry as Record<string, unknown>;
-			titles.push(record.title as string);
-			const description = typeof record.description === "string" ? record.description : "";
-			if (description) anyDescription = true;
-			descriptions.push(description);
-			continue;
-		}
-		titles.push(String(entry));
-		descriptions.push("");
-	}
-	params.options = titles;
-	if (anyDescription) params.option_descriptions = descriptions;
-}
-
-async function liveAnswer(
-	ctx: ExtensionContext,
-	discussion: Artifact,
-	latestContent: string | undefined,
-	onUpdate: AgentToolUpdateCallback | undefined,
-	signal: AbortSignal | undefined,
-): Promise<{ content: string; selected?: string[] } | undefined> {
-	if (!ctx.hasUI) return undefined;
-	const pending = (() => {
-		try {
-			return readDiscussionExtra(discussion.extra);
-		} catch {
-			return undefined;
-		}
-	})();
-	// The just-recorded round's own content IS the real question -- a generic "Reply to <title>:"
-	// wrapper as the primary question, with the real content demoted to "Context:", left a human
-	// staring at a labeled-backwards prompt (live-observed). The wrapper is now only a fallback for
-	// the degenerate case of empty content; the title becomes a plain orientation subtitle instead.
-	const question = latestContent?.trim() || `Reply to "${discussion.title}":`;
-	const subtitle = discussion.title;
-	if (pending?.pendingOptions && pending.pendingOptions.length > 0 && pending.pendingOptionsMode) {
-		return askQuestion(ctx, {
-			question,
-			subtitle,
-			options: pending.pendingOptions.map((title, index) => ({
-				title,
-				description: pending.pendingOptionDescriptions?.[index] || undefined,
-			})),
-			allowMultiple: pending.pendingOptionsMode === "multi",
-			onUpdate,
-			signal,
-		});
-	}
-	return askQuestion(ctx, { question, subtitle, onUpdate, signal });
-}
 
 /**
  * Every domain tool's primary interfacing point is an artifact's NAME, not its id -- id is a
@@ -202,195 +110,8 @@ export async function resolveNameFields(
 	}
 }
 
-/** Resolves a `namesKey` string array to an `idsKey` id array, only when idsKey isn't already explicitly given. */
-async function resolveNameArrayField(
-	params: Record<string, unknown>,
-	namesKey: string,
-	idsKey: string,
-	listOperation: OperationName,
-	baseRequest: Record<string, unknown>,
-	notes?: string[],
-): Promise<void> {
-	const names = params[namesKey];
-	if (Array.isArray(names) && names.length > 0 && !params[idsKey]) {
-		params[idsKey] = await Promise.all(names.map((entry) => resolveArtifactIdByName(listOperation, baseRequest, String(entry), notes)));
-	}
-}
-
-/**
- * Shared "remove"/"restore" dispatch for every domain tool (tasks/docs/rules/playbooks) --
- * artifact.remove/restore are kind-agnostic composition-root operations (see service.ts),
- * not owned by any one domain module, so every domain tool exposes the same two actions
- * over the same two operations rather than reinventing trash semantics four times.
- * Returns null when action is neither, so callers fall through to their own dispatch.
- */
-async function _handleArtifactRemoveRestore(action: unknown, params: Record<string, unknown>): Promise<ReturnType<typeof text> | null> {
-	// Trashed/restored artifacts stay directly showable, so known identities render by title on
-	// either side of the action. An unresolved explicit id stays in structured/error channels;
-	// normal model text does not turn that backend key into the artifact's public name.
-	const titleOf = async (): Promise<string> => {
-		try {
-			const artifact = await callService<Record<string, unknown>, Artifact | null>("artifact.show", { id: params.id });
-			return artifact ? `"${artifact.title}"` : "unknown artifact";
-		} catch {
-			return "unknown artifact";
-		}
-	};
-	if (action === "remove") {
-		const label = await titleOf();
-		const record = await callService<
-			Record<string, unknown>,
-			{ artifactId: string; trashedAt: string; purgeAfter: string; reason?: string }
-		>("artifact.remove", params);
-		const message = `Trashed ${label}, eligible for purge at ${record.purgeAfter}.`;
-		return text(message, createPreviewDetails("artifact.remove", "Trashed", record.artifactId));
-	}
-	if (action === "restore") {
-		const label = await titleOf();
-		const outcome = await callService<Record<string, unknown>, { restored: boolean }>("artifact.restore", params);
-		const output = outcome.restored ? `Restored ${label}.` : `${label} was not trashed.`;
-		return text(output, createPreviewDetails("artifact.restore", "Restored", output));
-	}
-	if (action === "remove_subtree") {
-		const label = await titleOf();
-		const outcome = await callService<Record<string, unknown>, { removed: string[]; skipped: string[] }>("artifact.remove_subtree", params);
-		const message = `Trashed ${label} and ${outcome.removed.length - 1} contained artifact(s)${outcome.skipped.length > 0 ? `, skipped ${outcome.skipped.length} already-trashed` : ""}.`;
-		return text(message, createPreviewDetails("artifact.remove_subtree", "Trashed subtree", JSON.stringify(outcome, null, 2)));
-	}
-	return null;
-}
-
-// notes.*, rules.*, docs.*, playbooks.*, tasks.*, and the shared artifact.* are
-// registered as Vehicles (see ../vehicle-notes-client.ts and @danypops/papyrus's
-// src/vehicle/papyrus-vehicle.ts), not pi.registerTool()s in this file.
-
-export function registerDiscussTool(pi: ExtensionAPI): void {
-	pi.registerTool({
-		name: "discuss",
-		label: "Discuss",
-		description:
-			"Native Papyrus deliberation with a real lifecycle -- distinct from a one-shot ask: a Discussion persists, takes multiple rounds, and can genuinely block a Task's completion until settled or deferred. ACTIONS: open, reply, defer, resume, settle, block, unblock, show, rounds, list. open starts round 1 and optionally blocks_task_ids immediately. reply is refused once deferred or settled -- resume first. defer is explicitly non-blocking (paused, resumable); settle is terminal and archives the discussion. block/unblock manage the blocking relationship to a task independently of open. A task's completion is refused while any active Discussion blocks it. open/reply can pose a structured choice via options (2-10 entries) + options_mode ('single' mutually exclusive, 'multi' allows several); reply answers a currently pending choice via selected, validated against it. Each option is either a bare string or {title, description}; description is optional for exactly 2 options (a self-evident yes/no) but REQUIRED and non-empty for every option once there are 3 or more -- rejected otherwise. One line: the real pro/con/risk/consequence, never padding that just restates the title. Pass live:true on open or reply to get the human's answer synchronously in this same call, via an interactive prompt (the pending choice's picker if one was posed, otherwise a freeform question) -- covers a completely open question with no artifact (open with no prior discussion) and a question tied to a specific existing artifact (reply, addressed by name) alike. Only takes effect with an interactive UI available; otherwise degrades silently to the normal async round. The live picker docks in the input area itself (falls back to a plain text prompt if unsupported in the current UI mode). PREFER `name` (the discussion's exact title) over `id`, `task_name`/`blocks_task_names` over `task_id`/`blocks_task_ids` -- all are backend implementation details, resolved from name automatically.",
-		parameters: Type.Object({
-			action: Type.String(),
-			id: Type.Optional(Type.String()),
-			name: Type.Optional(Type.String()),
-			title: Type.Optional(Type.String()),
-			actor: Type.Optional(Type.String()),
-			content: Type.Optional(Type.String()),
-			body: Type.Optional(Type.String()),
-			labels: Type.Optional(Type.Array(Type.String())),
-			blocks_task_ids: Type.Optional(Type.Array(Type.String())),
-			blocks_task_names: Type.Optional(Type.Array(Type.String())),
-			task_id: Type.Optional(Type.String()),
-			task_name: Type.Optional(Type.String()),
-			reason: Type.Optional(Type.String()),
-			settlement: Type.Optional(Type.String()),
-			state: Type.Optional(Type.String()),
-			after_round: Type.Optional(Type.Number()),
-			limit: Type.Optional(Type.Number()),
-			options: Type.Optional(
-				Type.Array(Type.Union([Type.String(), Type.Object({ title: Type.String(), description: Type.Optional(Type.String()) })])),
-			),
-			options_mode: Type.Optional(Type.String()),
-			selected: Type.Optional(Type.Array(Type.String())),
-			live: Type.Optional(Type.Boolean()),
-		}),
-		// Blocks other tool calls in the same assistant turn until live:true's human answer comes
-		// back, same reasoning as pi-ask-user's own tool: the model must not batch a live ask with
-		// bash/edit/write and let those run before the human sees the prompt.
-		executionMode: "sequential",
-		renderCall(args, theme) {
-			return renderPapyrusToolCall("Discuss", args, theme);
-		},
-		renderResult(result, options, theme, context) {
-			return renderPapyrusToolResult(result, options, theme, context);
-		},
-		async execute(_id, rawParams, signal, onUpdate, ctx) {
-			try {
-				const params: Record<string, unknown> = { ...rawParams };
-				const action = params.action;
-				const taskScope = { project_root: ctx.cwd };
-				await resolveNameFields(params, [
-					{ nameKey: "name", idKey: "id", listOperation: "discuss.list", baseRequest: {} },
-					{ nameKey: "task_name", idKey: "task_id", listOperation: "tasks.list", baseRequest: taskScope },
-				]);
-				await resolveNameArrayField(params, "blocks_task_names", "blocks_task_ids", "tasks.list", taskScope);
-				if (action === "open" || action === "reply") {
-					normalizeDiscussOptions(params);
-					// Matches the tasks/notes tools' own convention: an agent-driven mutation with no
-					// explicit human actor still needs a real, non-generic label for the audit trail,
-					// not a bare daemon rejection.
-					if (typeof params.actor !== "string" || params.actor.length === 0) params.actor = "agent";
-					const operation = action === "open" ? "discuss.open" : "discuss.reply";
-					const result = await callService<Record<string, unknown>, DiscussionAndRounds>(operation, params);
-					const fallback =
-						action === "open"
-							? text(`Opened discussion ${artifactLine(result.discussion)}`, createArtifactDetails("discuss.open", result.discussion))
-							: text(
-									`Round ${result.rounds[0]?.roundNumber} added to "${result.discussion.title}"`,
-									createArtifactDetails("discuss.reply", result.discussion),
-								);
-					if (params.live !== true) return fallback;
-					const answer = await liveAnswer(ctx, result.discussion, result.rounds[0]?.content, onUpdate, signal);
-					if (!answer) return fallback;
-					const answered = await callService<Record<string, unknown>, DiscussionAndRounds>("discuss.reply", {
-						id: result.discussion.id,
-						actor: "human",
-						content: answer.content,
-						...(answer.selected ? { selected: answer.selected } : {}),
-						source: "discuss-live",
-					});
-					return text(`"${answered.discussion.title}": ${answer.content}`, createArtifactDetails("discuss.reply", answered.discussion));
-				}
-				if (action === "block" || action === "unblock") {
-					const operation = action === "block" ? "discuss.block" : "discuss.unblock";
-					const [outcome, discussionAndRounds, task] = await Promise.all([
-						callService<Record<string, unknown>, { blocked?: boolean; unblocked?: boolean }>(operation, params),
-						callService<Record<string, unknown>, DiscussionAndRounds>("discuss.show", { id: params.id }),
-						callService<Record<string, unknown>, Artifact>("tasks.show", { id: params.task_id }),
-					]);
-					const discussion = discussionAndRounds.discussion;
-					const message =
-						action === "unblock" && !outcome.unblocked
-							? "No such blocking relationship."
-							: `"${discussion.title}" ${action === "block" ? "now blocks" : "no longer blocks"} "${task.title}"`;
-					return text(message, createPreviewDetails(operation, action === "block" ? "Blocked" : "Unblocked", message));
-				}
-				if (action === "show") {
-					const result = await callService<Record<string, unknown>, DiscussionAndRounds>("discuss.show", params);
-					const rounds = result.rounds.map((round) => `  [round ${round.roundNumber}] ${round.actor}: ${round.content}`).join("\n");
-					return text(`${artifactLine(result.discussion)}\n\n${rounds}`, createArtifactDetails("discuss.show", result.discussion));
-				}
-				if (action === "rounds") {
-					const rounds = await callService<Record<string, unknown>, DiscussionRound[]>("discuss.rounds", params);
-					const output = rounds.map((round) => `[round ${round.roundNumber}] ${round.actor}: ${round.content}`).join("\n") || "No rounds.";
-					return text(output, createPreviewDetails("discuss.rounds", "Discussion rounds", output));
-				}
-				if (action === "list") {
-					const rows = await callService<Record<string, unknown>, Artifact[]>("discuss.list", params);
-					return text(
-						rows.length ? artifactLines(rows).join("\n") : "No discussions found.",
-						createArtifactListDetails("discuss.list", rows),
-					);
-				}
-				const operations = { defer: "discuss.defer", resume: "discuss.resume", settle: "discuss.settle" } as const;
-				const operation = operations[action as keyof typeof operations];
-				if (!operation) throw new Error(`unknown discuss action: ${action}`);
-				const artifact = await callService<Record<string, unknown>, Artifact>(operation, params);
-				return text(artifactLine(artifact), createArtifactDetails(operation, artifact));
-			} catch (error) {
-				throw new Error(`discuss failed: ${error instanceof Error ? error.message : error}`);
-			}
-		},
-	});
-}
-
-/** Thin orchestrator: each domain's tool is independently navigable/testable via its own registerXTool function. */
-// notes, rules, docs, playbooks, and tasks are no longer registered here -- all migrated
-// onto Vehicle (registerNotesVehicle in vehicle-notes-client.ts, wired at session_start in
-// index.ts), replacing their own pi.registerTool() mega-tools. See @danypops/papyrus's
-// src/vehicle/papyrus-vehicle.ts for the server side. discuss remains here -- live:true needs an
-// interactive UI round-trip a stateless Vehicle operation can't express.
-export function registerDomainTools(pi: ExtensionAPI): void {
-	registerDiscussTool(pi);
-}
+// notes.*, rules.*, docs.*, playbooks.*, tasks.*, discuss.*, and the shared artifact.*
+// are all registered as Vehicles (see ../vehicle-notes-client.ts and @danypops/papyrus's
+// src/vehicle/papyrus-vehicle.ts) -- no domain has a hand-rolled pi.registerTool() left
+// in this file. What remains here (above) is name-resolution machinery still used
+// directly by index.ts's own low-level tools (papyrus_graph).

package/extension/src/index.ts

@@ -37,7 +37,7 @@ import { buildTaskItemTree, computeContextBudget } from "./context-budget.ts";
 import { PAPYRUS_CONTEXT_HUB_PRODUCER_NAME, papyrusContextSegment } from "./context-hub-contribution.ts";
 import { buildContextInjection } from "./context-injection-telemetry.ts";
 import { ensureTypingCourtesyTracking, isLiveAskPending } from "./discuss-ask-view.ts";
-import { registerDomainTools, resolveNameFields } from "./domain-tools.ts";
+import { resolveNameFields } from "./domain-tools.ts";
 import { renderNoteWidgetLines } from "./note-widget.ts";
 import { PLAYBOOK_BRIDGE_MAX_PLAYBOOKS, registerPlaybookBridge } from "./playbook-bridge.ts";
 import { callService, subscribeTaskPushChannel } from "./service-client.ts";
@@ -351,7 +351,6 @@ export class NoteOverlay {
 
 export default async function (pi: ExtensionAPI) {
 	setTaskFocusEventBus(pi);
-	registerDomainTools(pi);
 	registerPlaybookBridge(pi);
 	let contextInjectionSequence = 0;
 	const contextInjectionProducerId = randomUUID();

package/extension/src/vehicle-notes-client.ts

@@ -1,7 +1,8 @@
 /**
  * Registers every Vehicle-projected domain (notes.*, rules.*, docs.*, playbooks.*,
- * tasks.*, artifact.*) as real Pi tools -- see @danypops/papyrus's
- * src/vehicle/papyrus-vehicle.ts.
+ * tasks.*, discuss.*, artifact.*) as real Pi tools -- see @danypops/papyrus's
+ * src/vehicle/papyrus-vehicle.ts. discuss.* is the last of the six domains to
+ * migrate off pi-papyrus's own retired hand-rolled pi.registerTool() mega-tool.
  *
  * Fails silently on a stale/unreachable daemon handle instead of aborting extension
  * setup: Papyrus's daemon doesn't auto-spawn, and a tool that failed to register
@@ -23,6 +24,7 @@ import { createReconnectingVehicleClient } from "@danypops/vehicle-client/daemon
 import { RemoteVehicleClient } from "@danypops/vehicle-client/http";
 import { registerVehicleTools } from "@danypops/vehicle-client-pi";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { discussLiveFollowUp } from "./discuss-live-follow-up.ts";
 import { currentVehicleClientTarget } from "./service-client.ts";
 import { sessionSecretField } from "./session-identity.ts";
 import { emitTaskFocusEvent } from "./task-focus-events.ts";
@@ -39,6 +41,8 @@ const REGISTERED_PERMISSIONS = [
 	"playbooks:write",
 	"tasks:read",
 	"tasks:write",
+	"discuss:read",
+	"discuss:write",
 	"artifact:read",
 	"artifact:write",
 ];
@@ -92,6 +96,15 @@ export async function registerNotesVehicle(pi: ExtensionAPI): Promise<void> {
 			// token-cost router correlating its own telemetry with the currently focused task)
 			// -- has no Vehicle-transport equivalent, so it's emitted here, client-side, rather
 			// than from the operation's own output.
+			// discuss.open/discuss.reply's own live:true synchronous human round-trip --
+			// see discuss-live-follow-up.ts. Every other operation's resolver call
+			// returns undefined, meaning zero behavior change for the other 5 domains.
+			interactiveFollowUps: (descriptor) =>
+				descriptor.name === "discuss.open" || descriptor.name === "discuss.reply" ? discussLiveFollowUp : undefined,
+			// The retired discuss tool declared executionMode: "sequential" so the model
+			// couldn't batch a live ask alongside other tool calls in the same turn and
+			// let those run before the human sees the prompt -- same reasoning here.
+			executionMode: (descriptor) => (descriptor.name === "discuss.open" || descriptor.name === "discuss.reply" ? "sequential" : undefined),
 			onInvoked: ({ descriptor }, output) => {
 				if (descriptor.name === "tasks.focus") {
 					const artifact = output as { id: string } | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/pi-papyrus",
-  "version": "0.44.0",
+  "version": "0.45.0",
   "description": "Pi host extension for Papyrus: native tools, TUI panels, and context injection over the daemon-backed graph store",
   "type": "module",
   "keywords": ["pi-package"],
@@ -18,9 +18,9 @@
   },
   "dependencies": {
     "@danypops/jittor": "^0.14.0",
-    "@danypops/papyrus": "^0.43.0",
+    "@danypops/papyrus": "^0.44.0",
     "@danypops/vehicle-client": "^0.5.0",
-    "@danypops/vehicle-client-pi": "^0.8.1",
+    "@danypops/vehicle-client-pi": "^0.13.0",
     "@danypops/vehicle-core": "^0.10.0",
     "@danypops/vehicle-server": "^0.11.0",
     "beautiful-mermaid": "1.1.3",