pi-cue 0.1.0 → 0.1.2

package/README.md

@@ -1,8 +1,8 @@
 # pi-cue
 
-**A tap on your wrist when pi is done, or needs you.**
+**A notification on your iPhone when pi is done, or needs you.**
 
-Pushes to your iPhone and Apple Watch through [Bark](https://github.com/Finb/Bark), but only when you are away. If you are at the keyboard, nothing happens.
+Sent through [Bark](https://github.com/Finb/Bark), and only when you are away: if you are at the keyboard, nothing happens. While the iPhone is locked, it reaches your Apple Watch too.
 
 ## Setup
 
@@ -14,7 +14,7 @@ The key is stored in `~/.pi/agent/cue.json` (mode 600). `PI_CUE_KEY` and `PI_CUE
 
 ## Use
 
-Cues are **off** in every session until you turn them on, so parallel sessions don't all tap you.
+Cues are **off** in every session until you turn them on, so parallel sessions don't all notify you.
 
 | | |
 |---|---|
@@ -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 alerts again.
 
 ## Quiet by design
 
@@ -43,8 +49,6 @@ The body is the question, the error, or the first line of the answer.
 - **Cleans up.** Answering, typing, starting a new run, or quitting removes the notification from the phone and watch. Removal needs Bark's *Background App Refresh*.
 - **Never in the way.** Network errors are swallowed. Nested and headless sessions never cue.
 
-The Watch only gets iPhone notifications while the iPhone is locked.
-
 ## Config
 
 `~/.pi/agent/cue.json`, all optional except `key`:
@@ -62,7 +66,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

@@ -1,5 +1,5 @@
 /**
- * pi-cue: a tap on the wrist when pi is done, or needs you.
+ * pi-cue: a phone notification when pi is done, or needs you.
  *
  * Off by default per session; `/cue` turns it on for the current one.
  * All logic lives in src/core.ts; this file only wires pi events to it.
@@ -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";
@@ -42,7 +42,7 @@ export default function piCue(pi: ExtensionAPI): void {
 			now: Date.now,
 			after(ms, fn) {
 				const t = setTimeout(fn, ms);
-				t.unref?.(); // never keep pi alive for a tap
+				t.unref?.(); // never keep pi alive for a notification
 				return () => clearTimeout(t);
 			},
 			send(note: Note) {
@@ -77,7 +77,7 @@ export default function piCue(pi: ExtensionAPI): void {
 		cwd = ctx.cwd;
 		sessionId = ctx.sessionManager.getSessionId().slice(0, 8);
 		last = { failed: false, text: "" };
-		if (!ctx.hasUI) return; // nested and headless sessions never tap
+		if (!ctx.hasUI) return; // nested and headless sessions never notify
 		unlisten = ctx.ui.onTerminalInput((data) => {
 			if (isHumanKey(data)) cue.input();
 			return undefined;
@@ -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));
@@ -130,11 +135,11 @@ export default function piCue(pi: ExtensionAPI): void {
 		cue.setEnabled(on);
 		pi.appendEntry(ENTRY, { on });
 		showStatus(ctx);
-		say(ctx, on ? (zh ? "cue 已开启:完成或需要你时会推送" : "cue on: you will be tapped when pi is done or needs you") : zh ? "cue 已关闭" : "cue off");
+		say(ctx, on ? (zh ? "cue 已开启:完成或需要你时会推送" : "cue on: you will be notified when pi is done or needs you") : zh ? "cue 已关闭" : "cue off");
 	};
 
 	pi.registerCommand("cue", {
-		description: "Tap on the wrist when pi is done or needs you (on | off | test | key <key>)",
+		description: "Notify your phone when pi is done or needs you (on | off | test | key <key>)",
 		getArgumentCompletions: (prefix) =>
 			["on", "off", "test", "key", "status"].filter((s) => s.startsWith(prefix)).map((s) => ({ value: s, label: s })),
 		handler: async (args, ctx) => {
@@ -155,7 +160,8 @@ export default function piCue(pi: ExtensionAPI): void {
 				}
 				case "test": {
 					if (!cfg.key) return say(ctx, zh ? "还没有 key,先运行 /cue key" : "No key yet. Run /cue key first.", "warning");
-					const m = render({ kind: "done", elapsedMs: 83_000, text: zh ? "这是一条测试" : "This is a test" }, cwd, { zh, detail: true });
+					// Always English: a test is often sent to show someone else what a cue looks like.
+					const m = render({ kind: "done", elapsedMs: 83_000, text: "Test notification from pi-cue. You are all set." }, cwd, { zh: false, detail: true });
 					const ok = await push(cfg, { id: `${id()}-test`, group: repoName(cwd), ...m });
 					return say(ctx, ok ? (zh ? "已发送" : "Sent") : zh ? "发送失败,检查 key 和网络" : "Send failed; check the key and network", ok ? "info" : "error");
 				}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-cue",
-  "version": "0.1.0",
-  "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.",
+  "version": "0.1.2",
+  "description": "Get a notification on your iPhone (and Apple Watch) when pi is done or needs you, only when you are away. Uses Bark.",
   "type": "module",
   "license": "MIT",
   "author": "purboo",

package/src/bark.ts

@@ -98,7 +98,7 @@ async function post(cfg: Config, payload: Record<string, unknown>, fetcher: type
 		});
 		return res.ok;
 	} catch {
-		return false; // best effort: a missed tap must never disturb pi
+		return false; // best effort: a missed notification must never disturb pi
 	}
 }
 

package/src/core.ts

@@ -2,7 +2,7 @@
  * The decision logic, free of pi and the network. Everything time-related and
  * every side effect is injected, so it can be tested with a fake clock.
  *
- * The rule of thumb: a cue is a tap on the wrist, so it must only fire when
+ * The rule of thumb: a cue interrupts you, so it must only fire when
  * you are away. Every cue therefore waits a grace period, and is dropped if
  * you touched the keyboard around that time or the situation resolved itself.
  */
@@ -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;
 }