@danypops/papyrus 0.23.0 → 0.25.0

package/README.md

@@ -122,7 +122,7 @@ Agent-facing domain tools own lifecycle invariants and sit above this store API:
 - **`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
+- **`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.
 
@@ -145,6 +145,7 @@ Tasks, Docs, Rules, and Skills all support first-class `update` (title/body/labe
 - `/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. `↑/↓` scrolls, `←/→` pans wide relationships, and Esc returns to the browser; non-interactive clients receive stable source text.
 
@@ -174,7 +175,7 @@ Blocking is real: `tasks.complete` is refused while any `active` Discussion has
 
 `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 (space to toggle, enter to confirm) for `multi`, since no built-in multi-select exists in the Pi extension UI. Opening a *new* Discussion is left to the agent (same as Docs/Rules/Skills) -- `/discuss` browses and drives existing ones.
+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

package/extension/src/discuss.ts

@@ -83,8 +83,14 @@ export async function showDiscussions(ctx: ExtensionCommandContext): Promise<voi
 			if (choice === "Reply") {
 				const pending = (() => { try { return readDiscussionExtra(discussion.extra); } catch { return undefined; } })();
 				if (pending?.pendingOptions && pending.pendingOptions.length > 0 && pending.pendingOptionsMode) {
-					const selected = await pickDiscussionOptions(commandCtx, pending.pendingOptionsMode, pending.pendingOptions);
-					if (!selected) return; // canceled
+					const result = await pickDiscussionOptions(commandCtx, pending.pendingOptionsMode, pending.pendingOptions);
+					if (!result) return; // canceled
+					if (result.kind === "freeform") {
+						await callService("discuss.reply", { id: discussion.id, actor: ACTOR, content: result.text, source: SOURCE });
+						commandCtx.ui.notify("Reply added.", "info");
+						return;
+					}
+					const { selected } = result;
 					const elaboration = await commandCtx.ui.input("Elaborate (optional):", selected.join(", "));
 					if (elaboration === undefined) return; // canceled
 					await callService("discuss.reply", { id: discussion.id, actor: ACTOR, content: elaboration || selected.join(", "), selected, source: SOURCE });

package/extension/src/discussion-picker.ts

@@ -1,47 +1,118 @@
 /**
- * discussion-picker.ts — the structured-choice picker for /discuss's "Reply" action.
+ * discussion-picker.ts — the structured-choice picker for /discuss's "Reply" action and the
+ * discuss tool's own live:true synchronous ask.
  *
- * "single" mode (mutually exclusive) needs nothing bespoke: the Pi extension UI already
- * provides exactly that (ctx.ui.select). "multi" (allow several) has no native equivalent
- * anywhere in @earendil-works/pi-coding-agent or pi-tui (checked both) -- so this is a small,
- * genuinely domain-specific checkbox-list component, not a generic library replacement.
+ * "single" mode (mutually exclusive) needs nothing bespoke for the pick list itself: the Pi
+ * extension UI already provides exactly that (ctx.ui.select). "multi" (allow several) has no
+ * native equivalent anywhere in @earendil-works/pi-coding-agent or pi-tui (checked both) -- so
+ * that one is a small, genuinely domain-specific checkbox-list component, not a generic library
+ * replacement. Both modes get a numbered quick-select (press the row's digit instead of
+ * scrolling with arrows) and an appended "type your own answer" row, itself numbered the same
+ * way -- a genuinely open question is exactly as valid an answer as any of the posed options.
  */
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
+import { DISCUSSION_PICKER_IDLE_TIMEOUT_MS, DISCUSSION_PICKER_TICK_MS } from "../../src/constants.ts";
 import type { DiscussionOptionsMode } from "../../src/domain/discussion.ts";
 
-/** Toggle with space, confirm with enter (refuses an empty confirm -- at least one pick is required), cancel with escape. */
-async function pickMultiple(ctx: ExtensionContext, title: string, options: string[]): Promise<string[] | undefined> {
-	return ctx.ui.custom<string[] | undefined>((tui, theme, _keybindings, done) => {
+const FREEFORM_LABEL = "Something else (type your own answer)";
+
+export type DiscussionPickResult = { kind: "selected"; selected: string[] } | { kind: "freeform"; text: string };
+
+/** digit "1".."9" -> index 0-8, "0" -> index 9 (DISCUSSION_OPTIONS_MAX_COUNT is 10) -- standard terminal-menu numbering, not 0-indexed. */
+function digitToIndex(data: string, rowCount: number): number | undefined {
+	if (data === "0") return rowCount >= 10 ? 9 : undefined;
+	if (data.length === 1 && data >= "1" && data <= "9") {
+		const index = Number(data) - 1;
+		return index < rowCount ? index : undefined;
+	}
+	return undefined;
+}
+
+function rowNumberLabel(index: number): string {
+	if (index < 9) return `${index + 1}`;
+	if (index === 9) return "0";
+	return " "; // beyond the 1-9,0 quick-select range (should not happen given DISCUSSION_OPTIONS_MAX_COUNT=10, but never crash rendering)
+}
+
+async function promptFreeformAnswer(ctx: ExtensionContext): Promise<DiscussionPickResult | undefined> {
+	const text = await ctx.ui.input("Your answer:", "");
+	return text ? { kind: "freeform", text } : undefined;
+}
+
+/**
+ * Toggle with space or a row's number, confirm with enter (refuses an empty confirm -- at least
+ * one pick is required), cancel with escape. Picking the freeform row exits the checkbox flow
+ * entirely rather than adding it to the selection.
+ *
+ * Idle countdown: auto-cancels after DISCUSSION_PICKER_IDLE_TIMEOUT_MS of no input at all --
+ * the first keystroke of any kind stops it permanently (not a pause; it never resumes for this
+ * picker instance), since a countdown ticking while someone is actively engaging is pressure,
+ * not a nudge. The same tick also drives a slow, deliberately noticeable blink on the cursor
+ * row -- checked rows stay steadily highlighted, everything else stays dimmed, so the eye reads
+ * "what's chosen" at a glance independent of where the cursor happens to be.
+ */
+async function pickMultiple(ctx: ExtensionContext, title: string, options: string[], allowFreeform: boolean, idleTimeoutMs: number, tickMs: number): Promise<DiscussionPickResult | undefined> {
+	return ctx.ui.custom<DiscussionPickResult | undefined>((tui, theme, _keybindings, done) => {
+		const rows = allowFreeform ? [...options, FREEFORM_LABEL] : options;
+		const freeformIndex = allowFreeform ? rows.length - 1 : -1;
 		const checked = new Set<number>();
 		let selectedIndex = 0;
+		let hasInteracted = false;
+		let remainingMs = idleTimeoutMs;
+		let blinkOn = true;
+		const tick = setInterval(() => {
+			blinkOn = !blinkOn;
+			if (!hasInteracted) {
+				remainingMs -= tickMs;
+				if (remainingMs <= 0) { finish(undefined); return; }
+			}
+			tui.requestRender();
+		}, tickMs);
+		const finish = (value: DiscussionPickResult | undefined) => { clearInterval(tick); done(value); };
+		const chooseFreeform = () => { promptFreeformAnswer(ctx).then(finish); };
+		const toggle = (index: number) => {
+			if (index === freeformIndex) { chooseFreeform(); return; }
+			if (checked.has(index)) checked.delete(index); else checked.add(index);
+			tui.requestRender();
+		};
 		return {
 			invalidate() {},
 			render(width: number): string[] {
 				const lines: string[] = [
 					theme.bold(title),
-					theme.fg("muted", "space toggle \u00b7 enter confirm \u00b7 esc cancel"),
+					theme.fg("muted", "number/space toggle \u00b7 enter confirm \u00b7 esc cancel"),
 					"",
 				];
-				options.forEach((option, index) => {
-					const cursor = index === selectedIndex ? theme.fg("accent", "\u276f") : " ";
-					const box = checked.has(index) ? theme.fg("success", "[x]") : "[ ]";
-					const label = index === selectedIndex ? theme.bold(option) : option;
-					lines.push(truncateToWidth(`${cursor} ${box} ${label}`, width, ""));
+				rows.forEach((option, index) => {
+					const isCursor = index === selectedIndex;
+					const isChecked = checked.has(index);
+					const cursorGlyph = isCursor && blinkOn ? theme.fg("accent", "\u276f") : " ";
+					const box = index === freeformIndex ? "  " : isChecked ? theme.fg("success", "[x]") : "[ ]";
+					let label = option;
+					if (isChecked) label = theme.bold(theme.fg("success", label));
+					else if (isCursor) label = theme.bold(theme.fg("accent", label));
+					else label = theme.fg("dim", label);
+					lines.push(truncateToWidth(`${cursorGlyph} ${rowNumberLabel(index)}. ${box} ${label}`, width, ""));
 				});
 				lines.push("");
 				lines.push(theme.fg("dim", `${checked.size} selected`));
+				if (!hasInteracted) lines.push(theme.fg("dim", `auto-cancels in ${Math.max(0, Math.ceil(remainingMs / 1000))}s (press any key to stop)`));
 				return lines;
 			},
 			handleInput(data: string) {
-				if (matchesKey(data, "up")) selectedIndex = (selectedIndex - 1 + options.length) % options.length;
-				else if (matchesKey(data, "down")) selectedIndex = (selectedIndex + 1) % options.length;
-				else if (data === " ") { if (checked.has(selectedIndex)) checked.delete(selectedIndex); else checked.add(selectedIndex); }
+				hasInteracted = true;
+				const digit = digitToIndex(data, rows.length);
+				if (digit !== undefined) { selectedIndex = digit; toggle(digit); return; }
+				if (matchesKey(data, "up")) selectedIndex = (selectedIndex - 1 + rows.length) % rows.length;
+				else if (matchesKey(data, "down")) selectedIndex = (selectedIndex + 1) % rows.length;
+				else if (data === " ") { toggle(selectedIndex); return; }
 				else if (matchesKey(data, "enter")) {
+					if (selectedIndex === freeformIndex && checked.size === 0) { chooseFreeform(); return; }
 					if (checked.size === 0) return; // refuse an empty confirm -- selecting nothing isn't a valid answer
-					done([...checked].sort((a, b) => a - b).map((index) => options[index]!));
+					finish({ kind: "selected", selected: [...checked].sort((a, b) => a - b).map((index) => rows[index]!) });
 					return;
-				} else if (matchesKey(data, "escape")) { done(undefined); return; }
+				} else if (matchesKey(data, "escape")) { finish(undefined); return; }
 				else return;
 				tui.requestRender();
 			},
@@ -50,15 +121,28 @@ async function pickMultiple(ctx: ExtensionContext, title: string, options: strin
 }
 
 /**
- * Picks one (single) or several (multi) of the given options, or undefined if the user cancels.
- * Takes the base ExtensionContext (just .ui) rather than the wider ExtensionCommandContext, since
- * a tool's execute() only ever receives the former -- the discuss tool's own live mode reuses
- * this same picker, not just the /discuss TUI panel.
+ * Picks one (single) or several (multi) of the given options, or a freeform typed answer
+ * instead, or undefined if the user cancels. Takes the base ExtensionContext (just .ui) rather
+ * than the wider ExtensionCommandContext, since a tool's execute() only ever receives the
+ * former -- the discuss tool's own live mode reuses this same picker, not just the /discuss
+ * TUI panel. Single mode's numbered quick-select is not guaranteed: it delegates to Pi's own
+ * native ctx.ui.select, which this package does not control the key handling of.
  */
-export async function pickDiscussionOptions(ctx: ExtensionContext, mode: DiscussionOptionsMode, options: string[]): Promise<string[] | undefined> {
+export async function pickDiscussionOptions(
+	ctx: ExtensionContext,
+	mode: DiscussionOptionsMode,
+	options: string[],
+	allowFreeform = true,
+	/** Test seam: real timers, not faked global time -- pass tiny values to exercise the idle-cancel/blink logic quickly and deterministically. */
+	idleTimeoutMs = DISCUSSION_PICKER_IDLE_TIMEOUT_MS,
+	tickMs = DISCUSSION_PICKER_TICK_MS,
+): Promise<DiscussionPickResult | undefined> {
 	if (mode === "single") {
-		const pick = await ctx.ui.select("Pick one:", options);
-		return pick ? [pick] : undefined;
+		const rows = allowFreeform ? [...options, FREEFORM_LABEL] : options;
+		const pick = await ctx.ui.select("Pick one:", rows);
+		if (!pick) return undefined;
+		if (allowFreeform && pick === FREEFORM_LABEL) return promptFreeformAnswer(ctx);
+		return { kind: "selected", selected: [pick] };
 	}
-	return pickMultiple(ctx, "Pick one or more:", options);
+	return pickMultiple(ctx, "Pick one or more:", options, allowFreeform, idleTimeoutMs, tickMs);
 }

package/extension/src/domain-tools.ts

@@ -42,8 +42,10 @@ async function liveAnswer(ctx: ExtensionContext, discussion: Artifact): Promise<
 	if (!ctx.hasUI) return undefined;
 	const pending = (() => { try { return readDiscussionExtra(discussion.extra); } catch { return undefined; } })();
 	if (pending?.pendingOptions && pending.pendingOptions.length > 0 && pending.pendingOptionsMode) {
-		const selected = await pickDiscussionOptions(ctx, pending.pendingOptionsMode, pending.pendingOptions);
-		return selected ? { content: selected.join(", "), selected } : undefined;
+		const result = await pickDiscussionOptions(ctx, pending.pendingOptionsMode, pending.pendingOptions);
+		if (!result) return undefined;
+		if (result.kind === "freeform") return { content: result.text };
+		return { content: result.selected.join(", "), selected: result.selected };
 	}
 	const content = await ctx.ui.input(`Reply to "${discussion.title}":`, "");
 	return content ? { content } : undefined;
@@ -524,11 +526,12 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "playbooks",
 		label: "Playbooks",
-		description: "Playbook domain tool -- a completely different beast from the skills tool, not a subtype of it. A Playbook is a trigger and an ordered list of steps an agent reads and follows; it is never mechanically instantiated the way a Skill's artifact-template or workflow blueprint is, and it never composes other Playbooks. ACTIONS: create, list, show, invoke, enable, disable, assign_project, update, remove, restore. project_root is optional at creation (omitted = unscoped); assign_project reassigns it later, or unscopes when project_root is omitted. invoke renders the trigger/steps/tools into guidance plus any real linked artifacts. update changes title/body/labels (at least one required) and is refused for a read-only external projection. remove moves a Playbook to a time-gated trash, excluded from list/query but still directly showable, restorable via restore until the purge deadline. PREFER `name` (the playbook's exact title) over `id` -- id is a backend implementation detail, resolved from name automatically.",
+		description: "Playbook domain tool -- a completely different beast from the skills tool, not a subtype of it. A Playbook is a trigger and an ordered list of steps an agent reads and follows; it is never mechanically instantiated the way a Skill's artifact-template or workflow blueprint is, and it never composes other Playbooks. ACTIONS: create, list, show, invoke, enable, disable, assign_project, update, remove, restore. project_root is optional at creation (omitted = unscoped); assign_project reassigns it later, or unscopes when project_root is omitted. On create, `arguments` declares named inputs the Playbook needs: [{name, description?, required?}] (required defaults true). On invoke, `arguments` supplies known values as {name: value}; invoke renders which declared REQUIRED arguments are still missing and directs you to ask the human for them via the discuss tool with live:true -- never guess or invent a value for a missing required argument. update changes title/body/labels (at least one required) and is refused for a read-only external projection. remove moves a Playbook to a time-gated trash, excluded from list/query but still directly showable, restorable via restore until the purge deadline. PREFER `name` (the playbook's exact title) over `id` -- id is a backend implementation detail, 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()),
 			body: Type.Optional(Type.String()), trigger: Type.Optional(Type.String()), steps: Type.Optional(Type.Array(Type.String())),
 			tools: Type.Optional(Type.Array(Type.String())), labels: Type.Optional(Type.Array(Type.String())),
+			arguments: Type.Optional(Type.Unknown()),
 			extra: Type.Optional(Type.Record(Type.String(), Type.Unknown())), status: Type.Optional(Type.String()),
 			text: Type.Optional(Type.String()), limit: Type.Optional(Type.Number()),
 			project_root: Type.Optional(Type.String()), reason: Type.Optional(Type.String()),

package/extension/src/index.ts

@@ -462,6 +462,11 @@ export default async function (pi: ExtensionAPI) {
 		description: "Browse, edit, and invoke Papyrus playbooks -- trigger/steps guidance an agent reads and follows (interactive)",
 		handler: async (_args, ctx) => { await playbooksModule.showPlaybooks(ctx); },
 	});
+	pi.registerCommand("playbook", {
+		description: "Open one Papyrus playbook directly by name (tab-completes active playbook titles) and place its invocation in the editor; no argument opens the full /playbooks browser instead",
+		getArgumentCompletions: (argumentPrefix) => playbooksModule.playbookArgumentCompletions(argumentPrefix),
+		handler: async (args, ctx) => { await playbooksModule.openPlaybookByName(args, ctx); },
+	});
 	pi.registerCommand("discuss", {
 		description: "Browse Papyrus Discussions and reply, defer, resume, settle, or block/unblock a task (interactive)",
 		handler: async (_args, ctx) => { await discussModule.showDiscussions(ctx); },

package/extension/src/playbooks.ts

@@ -1,9 +1,44 @@
+import type { AutocompleteItem } from "@earendil-works/pi-tui";
 import type { ExtensionCommandContext, Theme } from "@earendil-works/pi-coding-agent";
 import type { Artifact } from "../../src/domain/artifact.ts";
 import { showArtifactBrowser, showArtifactDetails } from "./artifact-browser.ts";
 import { PLAYBOOK_STATUS_PRESENTATION } from "./artifact-status-presentation.ts";
+import { matchArtifactByName } from "./domain-tools.ts";
 import { callService } from "./service-client.ts";
 
+const PLAYBOOK_COMPLETION_MAX_CANDIDATES = 100;
+
+async function activePlaybooks(): Promise<Artifact[]> {
+	return callService<Record<string, unknown>, Artifact[]>("playbooks.list", { status: "active", limit: PLAYBOOK_COMPLETION_MAX_CANDIDATES });
+}
+
+/** `/playbook <tab>` completions -- title-prefix match, since that's what a human actually types, not a full-text search of body content. */
+export async function playbookArgumentCompletions(argumentPrefix: string): Promise<AutocompleteItem[] | null> {
+	try {
+		const needle = argumentPrefix.trim().toLowerCase();
+		const rows = await activePlaybooks();
+		return rows
+			.filter((row) => row.title.toLowerCase().startsWith(needle))
+			.sort((a, b) => a.title.localeCompare(b.title))
+			.map((row) => ({ value: row.title, label: row.title, description: typeof row.extra["trigger"] === "string" ? row.extra["trigger"] : undefined }));
+	} catch {
+		return null; // a Papyrus daemon hiccup degrades to "no suggestions", never breaks the command line
+	}
+}
+
+/** `/playbook <name>` (no args opens the full browser instead): resolves by exact title, then places its invocation directly in the editor -- one step, not browse-then-select-then-invoke. */
+export async function openPlaybookByName(name: string, ctx: ExtensionCommandContext): Promise<void> {
+	if (!name.trim()) { await showPlaybooks(ctx); return; }
+	try {
+		const id = matchArtifactByName(await activePlaybooks(), name);
+		const invocation = await callService<Record<string, unknown>, string>("playbooks.invoke", { id });
+		ctx.ui.setEditorText(invocation);
+		ctx.ui.notify(`"${name.trim()}" invocation placed in the editor`, "info");
+	} catch (error) {
+		ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+	}
+}
+
 const PLAYBOOK_RELATIONS = ["references", "documents", "relates_to", "contains", "part_of"];
 
 function strings(value: unknown): string[] {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "keywords": ["pi-package"],

package/src/constants.ts

@@ -100,6 +100,9 @@ export const SKILL_MAX_RENDERED_BYTES = 1_048_576;
 export const SKILL_INVOCATION_MAX_LINKED_ARTIFACTS = 20;
 export const SKILL_INVOCATION_MAX_CALL_DEPTH = 4;
 export const PLAYBOOK_INVOCATION_MAX_LINKED_ARTIFACTS = 20;
+export const PLAYBOOK_ARGUMENT_MAX_COUNT = 20;
+export const PLAYBOOK_ARGUMENT_NAME_MAX_LENGTH = 64;
+export const PLAYBOOK_ARGUMENT_DESCRIPTION_MAX_LENGTH = 500;
 
 /**
  * At the core, a workflow Skill creates Tasks and begins a pipeline -- an Ansible playbook or
@@ -172,6 +175,9 @@ export const DISCUSSION_ACTOR_MAX_LENGTH = 128;
 export const DISCUSSION_OPTIONS_MIN_COUNT = 2;
 export const DISCUSSION_OPTIONS_MAX_COUNT = 10;
 export const DISCUSSION_OPTION_MAX_LENGTH = 200;
+/** The multi-select picker's idle auto-cancel countdown and its render tick (also drives the cursor-row blink). Single-select has no equivalent -- it delegates to Pi's own native ctx.ui.select, whose input loop this package does not control. */
+export const DISCUSSION_PICKER_IDLE_TIMEOUT_MS = 30_000;
+export const DISCUSSION_PICKER_TICK_MS = 500;
 /** Bounds for the generic graph projection protocol (external bounded contexts). */
 export const GRAPH_PROJECTION_MAX_ARTIFACTS_PER_BATCH = 500;
 export const GRAPH_PROJECTION_MAX_EDGES_PER_BATCH = 1_000;

package/src/domain-services.ts

@@ -4,6 +4,9 @@ import {
 	ARTIFACT_LABEL_MAX_LENGTH,
 	ARTIFACT_SCOPE_MAX_ARTIFACTS,
 	ARTIFACT_TITLE_MAX_LENGTH,
+	PLAYBOOK_ARGUMENT_DESCRIPTION_MAX_LENGTH,
+	PLAYBOOK_ARGUMENT_MAX_COUNT,
+	PLAYBOOK_ARGUMENT_NAME_MAX_LENGTH,
 	PLAYBOOK_INVOCATION_MAX_LINKED_ARTIFACTS,
 	RULE_TEXT_HARD_LIMIT_CHARACTERS,
 	SKILL_INVOCATION_MAX_CALL_DEPTH,
@@ -522,12 +525,46 @@ export function transitionSkill(artifacts: ArtifactStore, id: string, action: Sk
  * mechanically instantiated into other artifacts; a Playbook is never instantiated, it's read
  * and followed, and it never composes other Playbooks the way a Skill can call another Skill.
  */
+export interface PlaybookArgument {
+	name: string;
+	description?: string;
+	/** Defaults true: naming an argument at all is a signal it matters, so an author must opt out explicitly to make one optional. */
+	required: boolean;
+}
+
+/** Rejects malformed input rather than silently dropping a bad entry -- the same posture creation validation already takes everywhere else. */
+function validatePlaybookArguments(value: unknown): PlaybookArgument[] | undefined {
+	if (value === undefined) return undefined;
+	if (!Array.isArray(value)) throw new Error("playbook arguments must be an array");
+	if (value.length > PLAYBOOK_ARGUMENT_MAX_COUNT) throw new Error(`playbook arguments cannot exceed ${PLAYBOOK_ARGUMENT_MAX_COUNT} entries`);
+	const seen = new Set<string>();
+	return value.map((entry, index) => {
+		if (typeof entry !== "object" || entry === null || Array.isArray(entry)) throw new Error(`argument at index ${index} must be an object`);
+		const record = entry as Record<string, unknown>;
+		const name = record["name"];
+		if (typeof name !== "string" || name.trim().length === 0 || name.length > PLAYBOOK_ARGUMENT_NAME_MAX_LENGTH) {
+			throw new Error(`argument name must be between 1 and ${PLAYBOOK_ARGUMENT_NAME_MAX_LENGTH} characters`);
+		}
+		if (seen.has(name)) throw new Error(`argument name "${name}" is declared more than once`);
+		seen.add(name);
+		const description = record["description"];
+		if (description !== undefined && (typeof description !== "string" || description.length > PLAYBOOK_ARGUMENT_DESCRIPTION_MAX_LENGTH)) {
+			throw new Error(`argument "${name}" description cannot exceed ${PLAYBOOK_ARGUMENT_DESCRIPTION_MAX_LENGTH} characters`);
+		}
+		const required = record["required"];
+		if (required !== undefined && typeof required !== "boolean") throw new Error(`argument "${name}" required must be a boolean`);
+		return { name, ...(description !== undefined ? { description: description as string } : {}), required: required !== false };
+	});
+}
+
 export interface CreatePlaybookInput {
 	title: string;
 	body?: string;
 	trigger?: string;
 	steps?: string[];
 	tools?: string[];
+	/** Declares named arguments this Playbook needs -- see playbookInvocation for how a missing required one surfaces. */
+	arguments?: unknown;
 	labels?: string[];
 	extra?: Record<string, unknown>;
 	projectRoot?: string;
@@ -538,6 +575,7 @@ export type UpdatePlaybookInput = UpdateContentInput;
 
 export function createPlaybook(artifacts: ArtifactStore, scopes: ArtifactScopeStore, input: CreatePlaybookInput, context?: ArtifactEventContext): Artifact {
 	const projectRoot = input.projectRoot === undefined ? undefined : normalizeProjectRoot(input.projectRoot);
+	const declaredArguments = validatePlaybookArguments(input.arguments);
 	const playbook = artifacts.create({
 		kind: "playbook",
 		status: "active", // explicit; see createDocument for why defaultStatusFor is not trusted here
@@ -549,6 +587,7 @@ export function createPlaybook(artifacts: ArtifactStore, scopes: ArtifactScopeSt
 			...(input.trigger ? { trigger: input.trigger } : {}),
 			...(input.steps ? { steps: input.steps } : {}),
 			...(input.tools ? { tools: input.tools } : {}),
+			...(declaredArguments ? { arguments: declaredArguments } : {}),
 		},
 	}, context);
 	scopes.assign(playbook.id, projectRoot, projectRoot === undefined ? "unscoped" : "explicit");
@@ -587,16 +626,34 @@ export function transitionPlaybook(artifacts: ArtifactStore, id: string, action:
 	return artifacts.setStatus(id, target, context)!;
 }
 
-/** Renders trigger/steps/tools into readable guidance, plus any real linked artifacts. No nested playbook-calls-playbook composition -- a Playbook is a flat procedure, not a composable bundle. */
-export function playbookInvocation(artifacts: ArtifactStore, id: string): string {
+/**
+ * Renders trigger/steps/tools/arguments into readable guidance, plus any real linked artifacts.
+ * No nested playbook-calls-playbook composition -- a Playbook is a flat procedure, not a
+ * composable bundle. `provided` is the caller's already-known argument values (e.g. from the
+ * conversation so far); any declared *required* argument missing from it is called out
+ * explicitly, directing the agent to discuss (live:true) rather than guess or silently proceed.
+ */
+export function playbookInvocation(artifacts: ArtifactStore, id: string, provided: Record<string, string> = {}): string {
 	const playbook = requireKind(artifacts, id, "playbook");
 	const trigger = typeof playbook.extra["trigger"] === "string" ? playbook.extra["trigger"] : "manual invocation";
 	const steps = Array.isArray(playbook.extra["steps"]) ? playbook.extra["steps"].filter((step): step is string => typeof step === "string") : [];
 	const tools = Array.isArray(playbook.extra["tools"]) ? playbook.extra["tools"].filter((tool): tool is string => typeof tool === "string") : [];
+	const declaredArguments = Array.isArray(playbook.extra["arguments"]) ? (playbook.extra["arguments"] as PlaybookArgument[]) : [];
+	const argumentLines = declaredArguments.map((argument) => {
+		const value = provided[argument.name];
+		if (value !== undefined) return `- ${argument.name}: ${value}`;
+		const qualifier = argument.required ? "required" : "optional";
+		return `- ${argument.name} (${qualifier}${argument.description ? `: ${argument.description}` : ""}) -- not yet provided`;
+	});
+	const missingRequired = declaredArguments.filter((argument) => argument.required && provided[argument.name] === undefined);
 	const sections = [[
 		`Apply Papyrus playbook "${playbook.title}" (${playbook.id}).`,
 		`Trigger: ${trigger}`,
 		...(playbook.body ? [`Context: ${playbook.body}`] : []),
+		...(argumentLines.length > 0 ? ["Arguments:", ...argumentLines] : []),
+		...(missingRequired.length > 0
+			? [`Missing required argument(s): ${missingRequired.map((argument) => argument.name).join(", ")}. Ask the human for these directly -- the discuss tool with live:true asks synchronously and gets a real answer in this same turn -- before proceeding with the steps below. Do not guess or invent a value.`]
+			: []),
 		...(steps.length ? ["Steps:", ...steps.map((step, index) => `${index + 1}. ${step}`)] : []),
 		...(tools.length ? [`Tools: ${tools.join(", ")}`] : []),
 	].join("\n")];

package/src/modules/playbooks.ts

@@ -61,12 +61,13 @@ export function playbooksOperations(artifacts: ArtifactStore, scopes: ArtifactSc
 		define("playbooks.create", (input: OperationInput) => createPlaybook(artifacts, scopes, {
 			title: string(input, "title"), body: optionalString(input, "body"), trigger: optionalString(input, "trigger"),
 			steps: input["steps"] as string[] | undefined, tools: input["tools"] as string[] | undefined,
+			arguments: input["arguments"],
 			labels: input["labels"] as string[] | undefined, extra: input["extra"] as Record<string, unknown> | undefined,
 			projectRoot: optionalString(input, "project_root"),
 		}, eventContext(input))),
 		define("playbooks.list", (input: OperationInput) => listPlaybooks(artifacts, scopes, artifactFilter(input))),
 		define("playbooks.show", (input: OperationInput) => showPlaybook(artifacts, string(input, "id"))),
-		define("playbooks.invoke", (input: OperationInput) => playbookInvocation(artifacts, string(input, "id"))),
+		define("playbooks.invoke", (input: OperationInput) => playbookInvocation(artifacts, string(input, "id"), input["arguments"] as Record<string, string> | undefined)),
 		define("playbooks.enable", (input: OperationInput) => transitionPlaybook(artifacts, string(input, "id"), "enable", eventContext(input))),
 		define("playbooks.disable", (input: OperationInput) => transitionPlaybook(artifacts, string(input, "id"), "disable", eventContext(input))),
 		define("playbooks.assign_project", (input: OperationInput) => assignPlaybookProject(artifacts, scopes, string(input, "id"), optionalString(input, "project_root"))),