pi-cue 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 purboo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,80 @@
-# Temporary Holding Version
+# pi-cue
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**A tap on your wrist 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.
+
+## Setup
+
+1. Install **Bark** from the App Store and allow notifications.
+2. `pi install npm:pi-cue`
+3. In pi: `/cue key <the URL Bark shows>`, then `/cue test`.
+
+The key is stored in `~/.pi/agent/cue.json` (mode 600). `PI_CUE_KEY` and `PI_CUE_SERVER` work too.
+
+## Use
+
+Cues are **off** in every session until you turn them on, so parallel sessions don't all tap you.
+
+| | |
+|---|---|
+| `/cue` | Toggle for this session. Remembered when you resume it. |
+| `/cue on` · `/cue off` | Explicit. |
+| `/cue test` | Send a sample. |
+| `/cue status` | On/off, key, server. |
+
+While on, `cue` shows in the status line.
+
+## What you get
+
+| | When | Level |
+|---|---|---|
+| `● 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 | 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 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
+
+- **Away only.** A cue waits out a grace period and is dropped if you pressed a key around that time. Escape-aborted runs never cue.
+- **One per session.** Each session replaces its own notification instead of stacking.
+- **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`:
+
+```json
+{
+  "key": "…",
+  "server": "https://api.day.app",
+  "default": "on",
+  "detail": false,
+  "graceMs": 15000,
+  "askGraceMs": 8000,
+  "minRunMs": 30000,
+  "remindMs": 600000
+}
+```
+
+`"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
+
+```bash
+bun install
+bun run link-pi
+bun run check        # tsc + bun test
+pi -e ./index.ts     # try it
+```

package/index.ts

@@ -0,0 +1,174 @@
+/**
+ * pi-cue: a tap on the wrist 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.
+ */
+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, question, render, repoName } from "./src/text.ts";
+
+const ENTRY = "pi-cue";
+const STATUS = "cue";
+
+interface MessageLike {
+	role?: string;
+	stopReason?: string;
+	errorMessage?: string;
+	content?: unknown;
+}
+
+function textOf(content: unknown): string {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	return content
+		.map((p) => (p && (p as { type?: string }).type === "text" ? String((p as { text?: unknown }).text ?? "") : ""))
+		.join("\n");
+}
+
+export default function piCue(pi: ExtensionAPI): void {
+	let cfg: Config = loadConfig();
+	let cwd = process.cwd();
+	let sessionId = "";
+	let unlisten: (() => void) | undefined;
+	let last: { failed: boolean; text: string } = { failed: false, text: "" };
+	const zh = isChinese();
+
+	const id = () => `cue-${sessionId}`;
+
+	const cue: Cue = createCue(
+		{
+			now: Date.now,
+			after(ms, fn) {
+				const t = setTimeout(fn, ms);
+				t.unref?.(); // never keep pi alive for a tap
+				return () => clearTimeout(t);
+			},
+			send(note: Note) {
+				const m = render(note, cwd, { zh, detail: cfg.detail });
+				void push(cfg, { id: id(), group: repoName(cwd), ...m });
+			},
+			withdraw() {
+				void remove(cfg, id());
+			},
+		},
+		cfg.timing,
+	);
+
+	const showStatus = (ctx: ExtensionContext) => {
+		if (ctx.hasUI) ctx.ui.setStatus(STATUS, cue.isEnabled() ? "cue" : undefined);
+	};
+
+	const restored = (ctx: ExtensionContext): boolean | undefined => {
+		const branch = ctx.sessionManager.getBranch();
+		for (let i = branch.length - 1; i >= 0; i--) {
+			const e = branch[i] as { type?: string; customType?: string; data?: { on?: boolean } };
+			if (e.type === "custom" && e.customType === ENTRY && typeof e.data?.on === "boolean") return e.data.on;
+		}
+		return undefined;
+	};
+
+	pi.on("session_start", (_e, ctx) => {
+		cue.reset();
+		unlisten?.();
+		unlisten = undefined;
+		cfg = loadConfig();
+		cwd = ctx.cwd;
+		sessionId = ctx.sessionManager.getSessionId().slice(0, 8);
+		last = { failed: false, text: "" };
+		if (!ctx.hasUI) return; // nested and headless sessions never tap
+		unlisten = ctx.ui.onTerminalInput((data) => {
+			if (isHumanKey(data)) cue.input();
+			return undefined;
+		});
+		cue.setEnabled((restored(ctx) ?? cfg.on) && !!cfg.key);
+		showStatus(ctx);
+	});
+
+	pi.on("agent_start", (_e, ctx) => {
+		cwd = ctx.cwd;
+		last = { failed: false, text: "" };
+		cue.runStart();
+	});
+
+	// agent_end fires per attempt and pi may still retry; agent_settled is final.
+	pi.on("agent_end", (e) => {
+		const msg = [...e.messages].reverse().find((m) => (m as MessageLike).role === "assistant") as
+			| MessageLike
+			| undefined;
+		const failed = msg?.stopReason === "error";
+		last = { failed, text: failed ? (msg?.errorMessage ?? "") : textOf(msg?.content) };
+	});
+
+	pi.on("agent_settled", (e, ctx) => {
+		cwd = ctx.cwd;
+		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));
+	pi.on("ui_prompt_end", () => cue.promptEnd());
+
+	pi.on("session_shutdown", async () => {
+		unlisten?.();
+		unlisten = undefined;
+		// Quitting means you are here: clear what is still on the phone, and wait for it
+		// so the request is not cut off by the process exiting.
+		const onPhone = cue.isLive();
+		cue.reset();
+		if (onPhone) await remove(cfg, id());
+	});
+
+	const say = (ctx: ExtensionContext, msg: string, type: "info" | "warning" | "error" = "info") =>
+		ctx.ui.notify(msg, type);
+
+	const setOn = (ctx: ExtensionContext, on: boolean) => {
+		if (on && !cfg.key) {
+			say(ctx, zh ? "还没有 Bark key。先运行 /cue key <key 或 Bark 显示的 URL>" : "No Bark key yet. Run /cue key <key or the URL Bark shows>", "warning");
+			return;
+		}
+		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");
+	};
+
+	pi.registerCommand("cue", {
+		description: "Tap on the wrist 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) => {
+			const [sub = "", ...rest] = args.trim().split(/\s+/);
+			switch (sub.toLowerCase()) {
+				case "":
+					return setOn(ctx, !cue.isEnabled());
+				case "on":
+					return setOn(ctx, true);
+				case "off":
+					return setOn(ctx, false);
+				case "key": {
+					const found = parseKey(rest.join(" "));
+					if (!found) return say(ctx, zh ? "没认出这个 key。粘贴 Bark App 首页的 URL 或 key。" : "That does not look like a Bark key or URL.", "error");
+					saveKey(found);
+					cfg = loadConfig();
+					return say(ctx, zh ? "key 已保存。运行 /cue test 试一条。" : "Key saved. Run /cue test to try one.");
+				}
+				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 });
+					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");
+				}
+				case "status":
+					return say(ctx, `cue ${cue.isEnabled() ? "on" : "off"} · key ${cfg.key ? "set" : "missing"} · ${cfg.server}`);
+				default:
+					return say(ctx, "/cue [on | off | test | key <key> | status]", "warning");
+			}
+		},
+	});
+}

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "pi-cue",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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",
+  "author": "purboo",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/purboo/pi-cue.git"
+  },
+  "homepage": "https://github.com/purboo/pi-cue#readme",
+  "bugs": {
+    "url": "https://github.com/purboo/pi-cue/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "notification",
+    "bark",
+    "apple-watch"
+  ],
+  "files": [
+    "index.ts",
+    "src"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "check": "tsc --noEmit && bun test",
+    "link-pi": "D=\"$(dirname \"$(readlink -f \"$(command -v pi)\")\")/../../..\" && mkdir -p node_modules/@earendil-works && for p in pi-ai pi-coding-agent pi-tui; do ln -sfn \"$(cd \"$D/$p\" && pwd)\" node_modules/@earendil-works/$p; done"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.4",
+    "typescript": "5"
+  }
+}

package/src/bark.ts

@@ -0,0 +1,109 @@
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { DEFAULT_TIMING, type Timing } from "./core.ts";
+
+export const DEFAULT_SERVER = "https://api.day.app";
+
+export interface Config {
+	key: string;
+	server: string;
+	/** Whether new sessions start with cues on. */
+	on: boolean;
+	/** Include the result / question text. Off sends only the project and state. */
+	detail: boolean;
+	timing: Timing;
+}
+
+export function configPath(env: NodeJS.ProcessEnv = process.env): string {
+	return join(env.PI_CODING_AGENT_DIR || join(homedir(), ".pi", "agent"), "cue.json");
+}
+
+const positive = (v: unknown, fallback: number, allowZero = false): number =>
+	typeof v === "number" && Number.isFinite(v) && (allowZero ? v >= 0 : v > 0) ? v : fallback;
+
+export function loadConfig(env: NodeJS.ProcessEnv = process.env, path = configPath(env)): Config {
+	let file: Record<string, unknown> = {};
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf8"));
+		if (parsed && typeof parsed === "object") file = parsed;
+	} catch {
+		// no file yet
+	}
+	const str = (v: unknown) => (typeof v === "string" && v.trim() ? v.trim() : "");
+	const t = DEFAULT_TIMING;
+	return {
+		key: str(env.PI_CUE_KEY) || str(file.key),
+		server: (str(env.PI_CUE_SERVER) || str(file.server) || DEFAULT_SERVER).replace(/\/+$/, ""),
+		on: env.PI_CUE === "1" || file.default === "on",
+		detail: file.detail !== false,
+		timing: {
+			graceMs: positive(file.graceMs, t.graceMs),
+			askGraceMs: positive(file.askGraceMs, t.askGraceMs),
+			minRunMs: positive(file.minRunMs, t.minRunMs, true),
+			remindMs: positive(file.remindMs, t.remindMs, true),
+		},
+	};
+}
+
+/** Accepts a bare key or the URL the Bark app shows (`https://host/KEY` or `https://host/KEY/...`). */
+export function parseKey(input: string): { key: string; server?: string } | undefined {
+	const text = input.trim();
+	if (!text) return undefined;
+	if (/^https?:\/\//i.test(text)) {
+		try {
+			const url = new URL(text);
+			const key = url.pathname.split("/").filter(Boolean)[0];
+			return key ? { key, server: url.origin } : undefined;
+		} catch {
+			return undefined;
+		}
+	}
+	return /^[\w-]{6,}$/.test(text) ? { key: text } : undefined;
+}
+
+/** Saves the key without disturbing other settings; the file holds a secret, so owner-only. */
+export function saveKey(found: { key: string; server?: string }, path = configPath()): void {
+	let file: Record<string, unknown> = {};
+	try {
+		file = JSON.parse(readFileSync(path, "utf8"));
+	} catch {
+		// first save
+	}
+	file.key = found.key;
+	if (found.server && found.server !== DEFAULT_SERVER) file.server = found.server;
+	else delete file.server;
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, `${JSON.stringify(file, null, 2)}\n`, { mode: 0o600 });
+	chmodSync(path, 0o600);
+}
+
+export interface Push {
+	id: string;
+	group: string;
+	title: string;
+	subtitle: string;
+	body: string;
+	level: string;
+}
+
+async function post(cfg: Config, payload: Record<string, unknown>, fetcher: typeof fetch): Promise<boolean> {
+	if (!cfg.key) return false;
+	try {
+		const res = await fetcher(`${cfg.server}/push`, {
+			method: "POST",
+			headers: { "content-type": "application/json; charset=utf-8" },
+			body: JSON.stringify({ device_key: cfg.key, ...payload }),
+			signal: AbortSignal.timeout(4_000),
+		});
+		return res.ok;
+	} catch {
+		return false; // best effort: a missed tap must never disturb pi
+	}
+}
+
+export const push = (cfg: Config, p: Push, fetcher: typeof fetch = fetch) => post(cfg, { ...p }, fetcher);
+
+/** Deleting is a silent push, so Bark needs Background App Refresh to act on it. */
+export const remove = (cfg: Config, id: string, fetcher: typeof fetch = fetch) =>
+	post(cfg, { id, delete: "1" }, fetcher);

package/src/core.ts

@@ -0,0 +1,193 @@
+/**
+ * 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
+ * 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.
+ */
+
+export type Kind = "done" | "fail" | "ask";
+
+export interface Note {
+	kind: Kind;
+	/** 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;
+	/** Second and last nudge for a decision that nobody answered. */
+	remind?: boolean;
+}
+
+export interface Timing {
+	/** Wait before announcing a finished run. */
+	graceMs: number;
+	/** Wait before announcing a decision; shorter, because the agent is blocked. */
+	askGraceMs: number;
+	/**
+	 * 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;
+}
+
+export const DEFAULT_TIMING: Timing = {
+	graceMs: 15_000,
+	askGraceMs: 8_000,
+	minRunMs: 30_000,
+	remindMs: 10 * 60_000,
+};
+
+export interface Deps {
+	now(): number;
+	/** Run `fn` after `ms`; returns a canceller. */
+	after(ms: number, fn: () => void): () => void;
+	send(note: Note): void;
+	/** Remove whatever this session last put on the phone. */
+	withdraw(): void;
+}
+
+/** Keystrokes this recent before an event still count as "you are here". */
+const PRESENT_MS = 5_000;
+
+export interface Cue {
+	setEnabled(on: boolean): void;
+	isEnabled(): boolean;
+	/** A cue from this session is currently on the phone. */
+	isLive(): boolean;
+	/** A human key press. */
+	input(): void;
+	/** `agent_start`. */
+	runStart(): 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. */
+	reset(): void;
+}
+
+export function createCue(deps: Deps, timing: Timing = DEFAULT_TIMING): Cue {
+	let enabled = false;
+	let lastInput = Number.NEGATIVE_INFINITY;
+	let startedAt: number | null = null;
+	let depth = 0;
+	let live = false;
+	/** `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 = () => {
+		pending?.cancel();
+		pending = null;
+	};
+
+	const withdraw = () => {
+		cancelRemind?.();
+		cancelRemind = null;
+		if (!live) return;
+		live = false;
+		deps.withdraw();
+	};
+
+	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, () => {
+			pending = null;
+			if (lastInput >= at - PRESENT_MS) return; // you are at the keyboard
+			live = true;
+			deps.send(note);
+			if (note.kind === "ask" && timing.remindMs > 0) {
+				cancelRemind = deps.after(timing.remindMs, () => {
+					cancelRemind = null;
+					deps.send({ ...note, remind: true, elapsedMs: timing.remindMs });
+				});
+			}
+		});
+		pending = { prompt, cancel };
+	};
+
+	return {
+		setEnabled(on) {
+			enabled = on;
+			if (!on) {
+				drop();
+				withdraw();
+			}
+		},
+		isEnabled: () => enabled,
+		isLive: () => live,
+
+		input() {
+			lastInput = deps.now();
+			// Typing means you have seen it; take it off the phone.
+			if (live) withdraw();
+		},
+
+		runStart() {
+			// Runs can restart on retry; keep the first start so the duration is the whole run.
+			if (startedAt === null) startedAt = deps.now();
+			dropRun();
+			withdraw();
+		},
+
+		settled({ aborted, failed, text, question }) {
+			const started = startedAt;
+			startedAt = null;
+			dropRun();
+			if (!enabled || aborted) return;
+			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 }, true);
+		},
+
+		promptEnd() {
+			depth = Math.max(0, depth - 1);
+			if (depth > 0) return;
+			if (pending?.prompt) drop();
+			withdraw();
+		},
+
+		reset() {
+			drop();
+			cancelRemind?.();
+			cancelRemind = null;
+			live = false;
+			startedAt = null;
+			depth = 0;
+		},
+	};
+}
+
+/**
+ * Raw terminal input also carries things you did not type: focus reports,
+ * mouse events, and replies to terminal queries. Only real keys show presence.
+ */
+export function isHumanKey(data: string): boolean {
+	if (!data) return false;
+	if (/^\x1b\[[IO]$/.test(data)) return false; // focus in / out
+	if (/^\x1b\[[<?>]/.test(data)) return false; // SGR mouse, DEC and DA replies
+	if (/^\x1b\[\d+;\d+R$/.test(data)) return false; // cursor position report
+	if (/^\x1b[\]P_^]/.test(data)) return false; // OSC, DCS, APC, PM replies
+	return true;
+}

package/src/text.ts

@@ -0,0 +1,88 @@
+import { basename } from "node:path";
+import type { Note } from "./core.ts";
+
+export type Level = "active" | "timeSensitive";
+
+export interface Message {
+	title: string;
+	subtitle: string;
+	body: string;
+	level: Level;
+}
+
+const COPY = {
+	zh: { done: "完成", fail: "失败", ask: "需要你", remind: "仍在等你", waiting: "等你回复" },
+	en: { done: "Done", fail: "Failed", ask: "Needs you", remind: "Still waiting", waiting: "Waiting for your reply" },
+};
+
+const MARK = { done: "✓", fail: "✗", ask: "●" } as const;
+
+export function isChinese(env: NodeJS.ProcessEnv = process.env): boolean {
+	const hint = env.LC_ALL || env.LC_MESSAGES || env.LANG || Intl.DateTimeFormat().resolvedOptions().locale;
+	return /^zh/i.test(hint);
+}
+
+/** `45s`, `2m14s`, `1h3m`. */
+export function duration(ms: number): string {
+	const total = Math.max(0, Math.round(ms / 1000));
+	if (total < 60) return `${total}s`;
+	const m = Math.floor(total / 60);
+	const s = total % 60;
+	if (m < 60) return s ? `${m}m${s}s` : `${m}m`;
+	const h = Math.floor(m / 60);
+	return m % 60 ? `${h}h${m % 60}m` : `${h}h`;
+}
+
+/** 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 = 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;
+}
+
+export function render(note: Note, cwd: string, opts: { zh: boolean; detail: boolean }): Message {
+	const c = opts.zh ? COPY.zh : COPY.en;
+	const label = note.remind ? c.remind : c[note.kind];
+	const subtitle = note.elapsedMs && note.elapsedMs >= 1000 ? `${label} · ${duration(note.elapsedMs)}` : label;
+	const detail = opts.detail ? oneLine(note.text) : "";
+	const body = detail || (note.kind === "ask" && opts.detail ? c.waiting : "");
+	return {
+		title: `${MARK[note.kind]} ${repoName(cwd)}`,
+		subtitle,
+		body,
+		level: note.kind === "done" ? "active" : "timeSensitive",
+	};
+}