pi-cue 0.1.0 → 0.1.1

package/README.md

@@ -29,12 +29,18 @@ While on, `cue` shows in the status line.
 
 | | When | Level |
 |---|---|---|
-| `● repo` · Needs you | pi waits on a confirm / select / input for 8s | time-sensitive |
+| `● repo` · Needs you | pi waits on a confirm / select / input for 8s, or the reply ends on a question | time-sensitive |
 | `● repo` · Still waiting | the same decision is still open after 10 min (once) | time-sensitive |
 | `✗ repo` · Failed | a run failed | time-sensitive |
-| `✓ repo` · Done · 3m12s | a run of 30s or more finished, 15s ago | normal |
+| `✓ repo` · Done · 3m12s | pi stopped 15s ago, and you had been away 30s or more | normal |
 
-The body is the question, the error, or the first line of the answer.
+The body is the question, the error, or the first line of the answer. The time is how long since you last touched pi.
+
+## Background subagents
+
+When a background subagent wakes the agent for a quick wrap-up, that still cues: away time counts from your last key press, not from the start of the run. A subagent's question, relayed by the agent as a reply ending in `?`, cues as *Needs you*.
+
+pi does not tell extensions about background work, so the turn that dispatches subagents cues once as *Done* (the body usually says what was dispatched), and each subagent that wakes the agent replaces that notification and taps again.
 
 ## Quiet by design
 
@@ -62,7 +68,7 @@ The Watch only gets iPhone notifications while the iPhone is locked.
 }
 ```
 
-`"default": "on"` (or `PI_CUE=1`) starts new sessions with cues on. `"detail": false` sends only the project and state, never text from the session; worth it on the public Bark server. `remindMs: 0` disables the reminder.
+`"default": "on"` (or `PI_CUE=1`) starts new sessions with cues on. `"detail": false` sends only the project and state, never text from the session; worth it on the public Bark server. `remindMs: 0` disables the reminder. `minRunMs` is the away time needed before *Done* or a question cues.
 
 ## Development
 

package/index.ts

@@ -7,7 +7,7 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { type Config, loadConfig, parseKey, push, remove, saveKey } from "./src/bark.ts";
 import { type Cue, createCue, isHumanKey, type Note } from "./src/core.ts";
-import { isChinese, render, repoName } from "./src/text.ts";
+import { isChinese, question, render, repoName } from "./src/text.ts";
 
 const ENTRY = "pi-cue";
 const STATUS = "cue";
@@ -103,7 +103,12 @@ export default function piCue(pi: ExtensionAPI): void {
 
 	pi.on("agent_settled", (e, ctx) => {
 		cwd = ctx.cwd;
-		cue.settled({ aborted: e.aborted, failed: last.failed, text: last.text });
+		cue.settled({
+			aborted: e.aborted,
+			failed: last.failed,
+			text: last.text,
+			question: last.failed ? undefined : question(last.text),
+		});
 	});
 
 	pi.on("ui_prompt_start", (e) => cue.promptStart(e.title));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cue",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "A tap on your wrist when pi is done, or needs you. Bark push to iPhone and Apple Watch, only when you are away.",
   "type": "module",
   "license": "MIT",

package/src/core.ts

@@ -11,7 +11,7 @@ export type Kind = "done" | "fail" | "ask";
 
 export interface Note {
 	kind: Kind;
-	/** Run duration (done/fail) or time spent waiting (reminder). */
+	/** Time since you last touched pi (done/fail/ask), or time spent waiting (reminder). */
 	elapsedMs?: number;
 	/** One-line detail: result summary, error, or the question being asked. */
 	text?: string;
@@ -24,7 +24,10 @@ export interface Timing {
 	graceMs: number;
 	/** Wait before announcing a decision; shorter, because the agent is blocked. */
 	askGraceMs: number;
-	/** Runs shorter than this are not worth a cue (failures always are). */
+	/**
+	 * Only cue once you have been away this long, counted from your last key press,
+	 * so a quick wrap-up run woken by a background subagent still counts. Failures always cue.
+	 */
 	minRunMs: number;
 	/** Nudge once more if a decision is still open after this long. 0 = never. */
 	remindMs: number;
@@ -58,8 +61,11 @@ export interface Cue {
 	input(): void;
 	/** `agent_start`. */
 	runStart(): void;
-	/** `agent_settled`. */
-	settled(run: { aborted: boolean; failed: boolean; text?: string }): void;
+	/**
+	 * `agent_settled`. `question` is set when the reply ends by asking you something:
+	 * the ball is in your court, so it cues like a dialog does.
+	 */
+	settled(run: { aborted: boolean; failed: boolean; text?: string; question?: string }): void;
 	promptStart(title?: string): void;
 	promptEnd(): void;
 	/** New session in the same process: forget everything, touch nothing remote. */
@@ -72,7 +78,8 @@ export function createCue(deps: Deps, timing: Timing = DEFAULT_TIMING): Cue {
 	let startedAt: number | null = null;
 	let depth = 0;
 	let live = false;
-	let pending: { kind: Kind; cancel: () => void } | null = null;
+	/** `prompt`: waits on a dialog, so only the dialog closing resolves it, not a run boundary. */
+	let pending: { prompt: boolean; cancel: () => void } | null = null;
 	let cancelRemind: (() => void) | null = null;
 
 	const drop = () => {
@@ -88,7 +95,11 @@ export function createCue(deps: Deps, timing: Timing = DEFAULT_TIMING): Cue {
 		deps.withdraw();
 	};
 
-	const schedule = (graceMs: number, note: Note) => {
+	const dropRun = () => {
+		if (pending && !pending.prompt) drop();
+	};
+
+	const schedule = (graceMs: number, note: Note, prompt = false) => {
 		drop();
 		const at = deps.now();
 		const cancel = deps.after(graceMs, () => {
@@ -103,7 +114,7 @@ export function createCue(deps: Deps, timing: Timing = DEFAULT_TIMING): Cue {
 				});
 			}
 		});
-		pending = { kind: note.kind, cancel };
+		pending = { prompt, cancel };
 	};
 
 	return {
@@ -126,30 +137,34 @@ export function createCue(deps: Deps, timing: Timing = DEFAULT_TIMING): Cue {
 		runStart() {
 			// Runs can restart on retry; keep the first start so the duration is the whole run.
 			if (startedAt === null) startedAt = deps.now();
-			if (pending && pending.kind !== "ask") drop();
+			dropRun();
 			withdraw();
 		},
 
-		settled({ aborted, failed, text }) {
+		settled({ aborted, failed, text, question }) {
 			const started = startedAt;
 			startedAt = null;
-			if (pending && pending.kind !== "ask") drop();
+			dropRun();
 			if (!enabled || aborted) return;
-			const elapsedMs = started === null ? 0 : deps.now() - started;
-			if (!failed && elapsedMs < timing.minRunMs) return;
-			schedule(timing.graceMs, { kind: failed ? "fail" : "done", elapsedMs, text });
+			const now = deps.now();
+			const since = Number.isFinite(lastInput) ? lastInput : (started ?? now);
+			const elapsedMs = now - since;
+			if (failed) return schedule(timing.graceMs, { kind: "fail", elapsedMs, text });
+			if (elapsedMs < timing.minRunMs) return;
+			if (question) return schedule(timing.askGraceMs, { kind: "ask", elapsedMs, text: question });
+			schedule(timing.graceMs, { kind: "done", elapsedMs, text });
 		},
 
 		promptStart(title) {
 			depth += 1;
 			if (!enabled || depth > 1) return;
-			schedule(timing.askGraceMs, { kind: "ask", text: title });
+			schedule(timing.askGraceMs, { kind: "ask", text: title }, true);
 		},
 
 		promptEnd() {
 			depth = Math.max(0, depth - 1);
 			if (depth > 0) return;
-			if (pending?.kind === "ask") drop();
+			if (pending?.prompt) drop();
 			withdraw();
 		},
 

package/src/text.ts

@@ -34,21 +34,41 @@ export function duration(ms: number): string {
 }
 
 /** First meaningful line, stripped of markdown noise, cut to `max` characters. */
+const clean = (raw: string) =>
+	raw
+		.replace(/^\s*(?:#{1,6}|>|[-*+]|\d+[.)])\s+/, "")
+		.replace(/[`*_~]/g, "")
+		.replace(/\s+/g, " ")
+		.trim();
+
+const clip = (line: string, max: number) => {
+	const chars = Array.from(line);
+	return chars.length <= max ? line : `${chars.slice(0, max - 1).join("").trimEnd()}…`;
+};
+
 export function oneLine(text: string | undefined, max = 90): string {
 	if (!text) return "";
 	for (const raw of text.split(/\r?\n/)) {
-		const line = raw
-			.replace(/^\s*(?:#{1,6}|>|[-*+]|\d+[.)])\s+/, "")
-			.replace(/[`*_~]/g, "")
-			.replace(/\s+/g, " ")
-			.trim();
-		if (!line) continue;
-		const chars = Array.from(line);
-		return chars.length <= max ? line : `${chars.slice(0, max - 1).join("").trimEnd()}…`;
+		const line = clean(raw);
+		if (line) return clip(line, max);
 	}
 	return "";
 }
 
+/**
+ * The question a reply ends on, if it ends on one: "Merge it now?" at the end means
+ * the agent is waiting for you even though no dialog opened. Heuristic by design.
+ */
+export function question(text: string | undefined, max = 90): string | undefined {
+	if (!text) return undefined;
+	const lines = text.split(/\r?\n/).map(clean).filter(Boolean);
+	const last = lines.at(-1)?.replace(/[\s)）"'”’]+$/, "");
+	if (!last || !/[?？]$/.test(last)) return undefined;
+	// Keep only the final sentence of a long line.
+	const sentence = last.split(/(?<=[.!。！？?])\s*/).filter(Boolean).at(-1) ?? last;
+	return clip(sentence, max);
+}
+
 export function repoName(cwd: string): string {
 	return basename(cwd) || cwd;
 }