@danypops/papyrus 0.29.1 → 0.29.3

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

@@ -1126,6 +1126,99 @@ export function isLiveAskPending(): boolean {
 	return livePendingCount > 0;
 }
 
+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> {
+	return new Promise((resolve) => {
+		if (signal?.aborted) { resolve(); return; }
+		const timer = setTimeout(resolve, ms);
+		signal?.addEventListener("abort", () => { clearTimeout(timer); resolve(); }, { once: true });
+	});
+}
+
+/**
+ * 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 isRecentlyTyping(): boolean {
+	return lastKeystrokeAt > 0 && Date.now() - lastKeystrokeAt < typingCourtesyInitialQuietMs;
+}
+
+/**
+ * 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 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);
+	}
+}
+
 /**
  * Discuss's live:true synchronous ask -- interactive AskComponent when a real TUI is available,
  * dialog fallback (ctx.ui.select/input) in RPC/headless mode, no-op undefined without any
@@ -1147,9 +1240,13 @@ async function askQuestionUnguarded(ctx: ExtensionContext, params: AskQuestionPa
 	const displayMode: AskDisplayMode = params.displayMode ?? envDisplayMode ?? "overlay";
 	const normalizedContext = params.context?.trim() || undefined;
 
-	params.onUpdate?.({ content: [{ type: "text", text: "Waiting for human input..." }], details: undefined });
+	if (isTypingCourtesyEnabled()) ensureTypingCourtesyTracking(ctx.ui);
 	livePendingCount += 1;
 	try {
+		// 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 {
 		livePendingCount -= 1;

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.1",
+  "version": "0.29.3",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "keywords": ["pi-package"],