@danypops/papyrus 0.29.2 → 0.29.4

package/extension/src/discuss-ask-view.ts

@@ -1126,14 +1126,26 @@ export function isLiveAskPending(): boolean {
 	return livePendingCount > 0;
 }
 
-const DISCUSS_TYPING_COURTESY_POLL_MS = 400;
-const DISCUSS_TYPING_COURTESY_DEFAULT_MAX_WAIT_MS = 15_000;
-
-function resolveTypingCourtesyMaxWaitMs(): number {
-	const raw = process.env["PAPYRUS_DISCUSS_TYPING_COURTESY_MS"];
-	if (raw === undefined) return DISCUSS_TYPING_COURTESY_DEFAULT_MAX_WAIT_MS;
-	const parsed = Number(raw);
-	return Number.isFinite(parsed) && parsed >= 0 ? parsed : DISCUSS_TYPING_COURTESY_DEFAULT_MAX_WAIT_MS;
+const DISCUSS_TYPING_COURTESY_DEFAULT_POLL_MS = 100;
+const DISCUSS_TYPING_COURTESY_DEFAULT_INITIAL_QUIET_MS = 1_500;
+const DISCUSS_TYPING_COURTESY_DEFAULT_QUIET_FLOOR_MS = 300;
+const DISCUSS_TYPING_COURTESY_DEFAULT_DECAY_HORIZON_MS = 10_000;
+
+let typingCourtesyPollMs = DISCUSS_TYPING_COURTESY_DEFAULT_POLL_MS;
+let typingCourtesyInitialQuietMs = DISCUSS_TYPING_COURTESY_DEFAULT_INITIAL_QUIET_MS;
+let typingCourtesyQuietFloorMs = DISCUSS_TYPING_COURTESY_DEFAULT_QUIET_FLOOR_MS;
+let typingCourtesyDecayHorizonMs = DISCUSS_TYPING_COURTESY_DEFAULT_DECAY_HORIZON_MS;
+
+/** Test-only: the real decay curve runs over seconds, too slow to exercise at its real scale in a unit test. */
+export function setTypingCourtesyTimingForTests(overrides?: { pollMs?: number; initialQuietMs?: number; floorMs?: number; decayHorizonMs?: number }): void {
+	typingCourtesyPollMs = overrides?.pollMs ?? DISCUSS_TYPING_COURTESY_DEFAULT_POLL_MS;
+	typingCourtesyInitialQuietMs = overrides?.initialQuietMs ?? DISCUSS_TYPING_COURTESY_DEFAULT_INITIAL_QUIET_MS;
+	typingCourtesyQuietFloorMs = overrides?.floorMs ?? DISCUSS_TYPING_COURTESY_DEFAULT_QUIET_FLOOR_MS;
+	typingCourtesyDecayHorizonMs = overrides?.decayHorizonMs ?? DISCUSS_TYPING_COURTESY_DEFAULT_DECAY_HORIZON_MS;
+}
+
+function isTypingCourtesyEnabled(): boolean {
+	return parseBooleanPreference(process.env["PAPYRUS_DISCUSS_TYPING_COURTESY"]) ?? true;
 }
 
 function sleep(ms: number, signal?: AbortSignal): Promise<void> {
@@ -1145,31 +1157,65 @@ function sleep(ms: number, signal?: AbortSignal): Promise<void> {
 }
 
 /**
- * Whether there is a genuine editor draft to wait out right now -- a plain synchronous check so
- * the common case (no draft) never forces the caller through an extra microtask. Deliberately not
- * folded into waitForEditorCourtesy itself: an unconditional `await` there -- even one that
- * resolves immediately -- still yields once, which is enough to let a signal aborted synchronously
- * right after invoking askQuestion race past the abort listener registered deeper in
- * askQuestionBlocking and get missed entirely.
+ * Required quiet gap (no keystroke) before a live ask may open, as a function of how long we've
+ * already been waiting. Starts wide (a natural inter-word pause shouldn't count as "done typing")
+ * and decays toward a floor -- someone typing continuously gets pickier treatment over time
+ * rather than never being asked. No outer cap: someone typing with sub-floor gaps forever waits
+ * forever, same as the picker itself already waits indefinitely for a real human answer once open.
+ */
+function requiredQuietMsAt(elapsedMs: number): number {
+	const t = Math.min(1, Math.max(0, elapsedMs / typingCourtesyDecayHorizonMs));
+	return typingCourtesyInitialQuietMs - t * (typingCourtesyInitialQuietMs - typingCourtesyQuietFloorMs);
+}
+
+/**
+ * Ambient, session-lifetime keystroke clock -- deliberately NOT scoped per-ask. A per-ask listener
+ * would only see keystrokes from the moment the tool call happens to start, missing typing already
+ * in progress when it began (the exact case this feature exists to protect). Attached once per
+ * distinct ui instance (reference equality; a session's real ui object is stable for its lifetime)
+ * and left attached -- there is no unregister, matching onTerminalInput's own listener-return-value
+ * contract elsewhere in this file.
+ */
+let lastKeystrokeAt = 0;
+let trackedUi: ExtensionContext["ui"] | undefined;
+
+export function ensureTypingCourtesyTracking(ui: ExtensionContext["ui"]): void {
+	if (typeof ui.onTerminalInput !== "function" || trackedUi === ui) return;
+	trackedUi = ui;
+	ui.onTerminalInput(() => { lastKeystrokeAt = Date.now(); return undefined; });
+}
+
+/** Test-only: clears the ambient keystroke clock so one test's simulated typing can't bleed into another's. */
+export function resetTypingCourtesyTrackingForTests(): void {
+	lastKeystrokeAt = 0;
+	trackedUi = undefined;
+}
+
+/**
+ * Whether there is real, recent typing activity to wait out right now -- a plain synchronous read
+ * of the ambient keystroke clock so the common case (nobody typing) never forces the caller
+ * through an extra microtask. Deliberately not folded into waitForTypingCourtesy itself: an
+ * unconditional `await` there -- even one that resolves immediately -- still yields once, which is
+ * enough to let a signal aborted synchronously right after invoking askQuestion race past the
+ * abort listener registered deeper in askQuestionBlocking and get missed entirely.
  */
-export function hasEditorCourtesyDraft(ctx: ExtensionContext): boolean {
-	return typeof ctx.ui.getEditorText === "function" && ctx.ui.getEditorText().length > 0;
+export function isRecentlyTyping(): boolean {
+	return lastKeystrokeAt > 0 && Date.now() - lastKeystrokeAt < typingCourtesyInitialQuietMs;
 }
 
 /**
- * Waits for a non-empty editor draft to clear before popping the live ask over it. Bounded
- * (PAPYRUS_DISCUSS_TYPING_COURTESY_MS, default 15s, 0 disables): a draft left sitting unattended
- * must not withhold the question indefinitely, only a genuinely in-progress reply gets the
- * courtesy. Only call when hasEditorCourtesyDraft(ctx) is already true.
+ * Waits out real keystroke activity (not editor text content -- that can't distinguish "actively
+ * typing" from "a stale draft sitting there", and misses a mid-thought erase-and-resume) before
+ * popping the live ask over it. Only call when isRecentlyTyping() is already true.
  */
-export async function waitForEditorCourtesy(ctx: ExtensionContext, params: Pick<AskQuestionParams, "onUpdate" | "signal">): Promise<void> {
-	const maxWaitMs = resolveTypingCourtesyMaxWaitMs();
-	if (maxWaitMs <= 0) return;
-	const deadline = Date.now() + maxWaitMs;
-	params.onUpdate?.({ content: [{ type: "text", text: "Waiting for you to finish typing before asking..." }], details: undefined });
-	while (Date.now() < deadline && !params.signal?.aborted) {
-		await sleep(DISCUSS_TYPING_COURTESY_POLL_MS, params.signal);
-		if (typeof ctx.ui.getEditorText !== "function" || ctx.ui.getEditorText().length === 0) return;
+export async function waitForTypingCourtesy(params: Pick<AskQuestionParams, "onUpdate" | "signal">): Promise<void> {
+	const startedAt = Date.now();
+	let announced = false;
+	while (lastKeystrokeAt > 0 && !params.signal?.aborted) {
+		const elapsed = Date.now() - startedAt;
+		if (Date.now() - lastKeystrokeAt >= requiredQuietMsAt(elapsed)) return;
+		if (!announced) { announced = true; params.onUpdate?.({ content: [{ type: "text", text: "Waiting for you to finish typing before asking..." }], details: undefined }); }
+		await sleep(typingCourtesyPollMs, params.signal);
 	}
 }
 
@@ -1194,11 +1240,12 @@ async function askQuestionUnguarded(ctx: ExtensionContext, params: AskQuestionPa
 	const displayMode: AskDisplayMode = params.displayMode ?? envDisplayMode ?? "overlay";
 	const normalizedContext = params.context?.trim() || undefined;
 
+	if (isTypingCourtesyEnabled()) ensureTypingCourtesyTracking(ctx.ui);
 	livePendingCount += 1;
 	try {
-		// Only actually awaits (yielding a microtask) when there's a real draft to wait out --
-		// see hasEditorCourtesyDraft's own comment for why the common case must stay synchronous.
-		if (hasEditorCourtesyDraft(ctx)) await waitForEditorCourtesy(ctx, params);
+		// Only actually awaits (yielding a microtask) when there's real typing activity to wait out --
+		// see isRecentlyTyping's own comment for why the common case must stay synchronous.
+		if (isTypingCourtesyEnabled() && isRecentlyTyping()) await waitForTypingCourtesy(params);
 		params.onUpdate?.({ content: [{ type: "text", text: "Waiting for human input..." }], details: undefined });
 		return await askQuestionBlocking(ctx, params, options, allowMultiple, allowFreeform, allowComment, displayMode, normalizedContext);
 	} finally {

package/extension/src/domain-tools.ts

@@ -150,6 +150,23 @@ async function resolveArtifactIdByName(listOperation: OperationName, baseRequest
 	return matchArtifactByName(candidates, name);
 }
 
+/**
+ * Playbook `arguments` is intentionally untyped in this tool's schema (an array on create, a
+ * {name: value} map on invoke) -- unlike every other JSON-shaped field here, which has a concrete
+ * array/record schema the calling layer can serialize correctly. A genuinely schema-less field can
+ * arrive pre-serialized as JSON text instead of a parsed value; parse it back in place before it
+ * reaches the service, the same tolerance the CLI's own --arguments-json/--*-json flags already give.
+ */
+export function normalizeJsonEncodedField(params: Record<string, unknown>, key: string): void {
+	const value = params[key];
+	if (typeof value !== "string") return;
+	try {
+		params[key] = JSON.parse(value);
+	} catch {
+		throw new Error(`${key} must be valid JSON`);
+	}
+}
+
 /** Resolves every {nameKey -> idKey} pair present and not already satisfied by an explicit id, in place. */
 async function resolveNameFields(
 	params: Record<string, unknown>,
@@ -610,6 +627,7 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 				await resolveNameFields(params, [
 					{ nameKey: "name", idKey: "id", listOperation: "playbooks.list", baseRequest: { project_root: params.project_root } },
 				]);
+				if (action === "create" || action === "invoke") normalizeJsonEncodedField(params, "arguments");
 				if (action === "create") {
 					const artifact = await callService<Record<string, unknown>, Artifact>("playbooks.create", params);
 					return text(`Created playbook ${artifactLine(artifact)}`, createArtifactDetails("playbooks.create", artifact));

package/extension/src/index.ts

@@ -22,7 +22,7 @@ import type { GateResult } from "../../src/domain/gate.ts";
 import { formatMetadata } from "./artifact-format.ts";
 import { callService } from "./service-client.ts";
 import { registerDomainTools } from "./domain-tools.ts";
-import { isLiveAskPending } from "./discuss-ask-view.ts";
+import { ensureTypingCourtesyTracking, isLiveAskPending } from "./discuss-ask-view.ts";
 import { PLAYBOOK_BRIDGE_MAX_PLAYBOOKS, registerPlaybookBridge } from "./playbook-bridge.ts";
 import type { TaskGraph, TaskStatus } from "../../src/task-service.ts";
 import { ActiveTaskContinuation, automaticPauseReason, shouldResumeFocusOnHumanInput, type ActiveTaskMarker } from "./active-task-continuation.ts";
@@ -566,6 +566,10 @@ export default async function (pi: ExtensionAPI) {
 			// intentionally silent -- see comment above
 		}
 		if (!ctx.hasUI) return;
+		// Attached from session start, not lazily on first ask -- a per-ask listener would only see
+		// keystrokes from the moment that tool call happens to begin, missing typing already in
+		// progress when it started (the exact case Discuss's typing-courtesy wait protects against).
+		ensureTypingCourtesyTracking(ctx.ui);
 		overlay ??= new TaskOverlay();
 		overlay.setUI(ctx.ui);
 		overlay.setProjectRoot(ctx.cwd);

package/package.json

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

package/src/cli.ts

@@ -112,7 +112,7 @@ const USAGE = `Usage:
   papyrus skills instantiate <template-id> [--title <title>] [--body <body>] [--status <status>] [--labels-json <json>] [--extra-json <json>] [--json]
   papyrus skills assign-project <id> [project-root] [--json]
   papyrus skills update <id> [--title <title>] [--body <body>] [--labels-json <json>] [--json]
-  papyrus playbooks create --title <title> [--body <body>] [--trigger <text>] [--steps-json <json>] [--tools-json <json>] [--labels-json <json>] [--extra-json <json>] [--project-root <path>] [--json]
+  papyrus playbooks create --title <title> [--body <body>] [--trigger <text>] [--steps-json <json>] [--tools-json <json>] [--labels-json <json>] [--extra-json <json>] [--arguments-json <json>] [--project-root <path>] [--json]
   papyrus playbooks list [--status <status>] [--text <query>] [--limit <count>] [--project-root <path>] [--json]
   papyrus playbooks show <id> [--json]
   papyrus playbooks invoke <id> [--json]
@@ -201,6 +201,14 @@ function parseJsonStringArrayFlag(value: string | undefined, flag: string): stri
 	return parsed as string[];
 }
 
+/** Top-level shape only -- element shape (e.g. {name, description?, required?}) is validated server-side. */
+function parseJsonArrayFlag(value: string | undefined, flag: string): unknown[] {
+	if (value === undefined) throw new Error(`${flag} requires a value`);
+	const parsed = JSON.parse(value) as unknown;
+	if (!Array.isArray(parsed)) throw new Error(`${flag} must be a JSON array`);
+	return parsed;
+}
+
 function artifactLabel(artifact: CliArtifact): string {
 	return `${artifact.id} ${artifact.title}`;
 }
@@ -786,6 +794,7 @@ export async function runPlaybooksCli(args: string[], client: TaskCliClient): Pr
 	let tools: string[] | undefined;
 	let labels: string[] | undefined;
 	let extra: Record<string, unknown> | undefined;
+	let playbookArguments: unknown[] | undefined;
 	let status: string | undefined;
 	let text: string | undefined;
 	let limit: number | undefined;
@@ -800,6 +809,7 @@ export async function runPlaybooksCli(args: string[], client: TaskCliClient): Pr
 		if (argument === "--tools-json") { tools = parseJsonStringArrayFlag(args[++index], "--tools-json"); continue; }
 		if (argument === "--labels-json") { labels = parseJsonStringArrayFlag(args[++index], "--labels-json"); continue; }
 		if (argument === "--extra-json") { extra = parseJsonObjectFlag(args[++index], "--extra-json"); continue; }
+		if (argument === "--arguments-json") { playbookArguments = parseJsonArrayFlag(args[++index], "--arguments-json"); continue; }
 		if (argument === "--status") { status = args[++index]; if (!status) throw new Error("--status requires a value"); continue; }
 		if (argument === "--text") { text = args[++index]; if (text === undefined) throw new Error("--text requires a value"); continue; }
 		if (argument === "--project-root") { playbookProjectRoot = args[++index]; if (!playbookProjectRoot) throw new Error("--project-root requires a value"); continue; }
@@ -819,7 +829,7 @@ export async function runPlaybooksCli(args: string[], client: TaskCliClient): Pr
 		case "create": {
 			if (id) throw new Error("playbooks create accepts no positional arguments");
 			if (!title) throw new Error("playbooks create requires --title");
-			const artifact = await client.call<Record<string, unknown>, CliArtifact>("playbooks.create", { title, body, trigger, steps, tools, labels, extra, project_root: playbookProjectRoot });
+			const artifact = await client.call<Record<string, unknown>, CliArtifact>("playbooks.create", { title, body, trigger, steps, tools, labels, extra, arguments: playbookArguments, project_root: playbookProjectRoot });
 			result = artifact;
 			human = `Created playbook: ${artifactLabel(artifact)}`;
 			break;