@cad0p/pi-heartbeat 0.0.1-20260814.0

package/.well-known/skills/index.json

@@ -0,0 +1,9 @@
+{
+  "skills": [
+    {
+      "name": "pi-heartbeat",
+      "path": "skills/pi-heartbeat/SKILL.md",
+      "description": "Non-blocking timers and heartbeats for pi agents. Use instead of `sleep` when waiting for builds, deployments, CI pipelines, or any async process. The agent returns to idle immediately and gets woken up when the timer fires. Triggers: timer, heartbeat, wait for build, poll, cron, wake me up, non-blocking wait, check back later, monitor deployment, periodic check."
+    }
+  ]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marc Fargas
+
+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

@@ -0,0 +1,169 @@
+# @cad0p/pi-heartbeat
+
+Non-blocking timers and heartbeats for [pi](https://github.com/badlogic/pi-mono) agents.
+
+`pi-heartbeat` replaces blocking `sleep` waits with timers that return immediately, so the agent can pause work without freezing the session.
+
+## What is pi?
+
+[Pi](https://github.com/badlogic/pi-mono) is an AI coding agent CLI (`@earendil-works/pi-coding-agent`).
+
+You run AI models in an interactive terminal, and the agent executes tools/commands while you chat with it. In that environment, `bash` calls like `sleep 60` block the active turn and prevent interaction until the command finishes.
+
+This extension gives the agent non-blocking waiting primitives (`timer`, `heartbeat`) so it can schedule follow-ups and return to idle immediately.
+
+## Why this extension?
+
+Without this extension, waits are usually implemented with shell `sleep`, polling loops, or long-running turns. That causes:
+
+- blocked chat while waiting
+- poor UX for long builds/deploys
+- brittle polling logic in bash
+
+With `pi-heartbeat`:
+
+- waits are non-blocking
+- timers can be canceled
+- follow-up messages include explicit context about what to check next
+
+## Install
+
+```bash
+pi install npm:@cad0p/pi-heartbeat
+```
+
+Or add to your `settings.json`:
+
+```json
+{
+  "packages": ["npm:@cad0p/pi-heartbeat"]
+}
+```
+
+## Prerequisites
+
+- [pi](https://github.com/badlogic/pi-mono) installed and working
+- A pi session where the agent can call tools
+- Extension installed via `pi install` or `settings.json`
+
+## Tools
+
+### `timer`
+
+One-shot wake-up after `N` seconds.
+
+```text
+timer(seconds: 60, message: "Check if build #42 finished — run gh run view 42")
+timer(seconds: 120, message: "Retry deploy check", id: "deploy-check-2")
+```
+
+- returns immediately (non-blocking)
+- wakes the agent once when the timer expires
+- supports multiple simultaneous timers
+- optional `id` for named cancellation
+
+### `heartbeat`
+
+Periodic wake-up every `N` seconds until stopped.
+
+```text
+heartbeat(action: "start", interval_seconds: 30, message: "Check deploy status")
+heartbeat(action: "status")
+heartbeat(action: "stop")
+```
+
+- wakes the agent repeatedly with the provided message
+- only one heartbeat can be active at a time
+- starting a new heartbeat replaces the previous one
+
+### `/cancel-timer`
+
+Manual timer/heartbeat control from chat.
+
+```text
+/cancel-timer            # list active timers
+/cancel-timer <id>       # cancel specific timer
+/cancel-timer heartbeat  # stop heartbeat
+/cancel-timer all        # cancel all timers + heartbeat
+```
+
+Use this when you need immediate control without waiting for the next trigger.
+
+## When to Use
+
+| Scenario | Before (blocks) | After (non-blocking) |
+|----------|------------------|----------------------|
+| Wait for build | `sleep 60 && gh run view 42` | `timer(60, 'Check build #42')` |
+| Monitor deploy | `while true; do sleep 30; check; done` | `heartbeat(start, 30, 'Check deploy')` |
+| Rate-limited API | `sleep 10` between calls | `timer(10, 'Resume API calls')` |
+
+## How It Works
+
+```text
+User: "Start the build and let me know when it's done"
+
+Agent: calls timer(seconds: 60, message: "Check build status")
+       -> tool returns immediately
+       -> agent tells user "I'll check in 60s"
+       -> session stays interactive
+
+[60 seconds later]
+
+Timer fires -> pi triggers a new agent turn
+-> agent wakes with the timer message in context
+-> agent runs the follow-up check
+-> if needed, schedules another timer/heartbeat
+```
+
+## vs. sleep
+
+|  | `sleep 60` | `timer(60)` |
+|---|---|---|
+| Chat blocked? | ✅ Yes | ❌ No |
+| User can interact? | ❌ No | ✅ Yes |
+| Cancellable? | Kill process | `/cancel-timer` |
+| Multiple waits? | Sequential | Concurrent |
+| Wake-up context? | Shell state only | Explicit message/context |
+
+## Limits
+
+- `timer`
+  - range: **1–3600 seconds**
+  - supports multiple simultaneous timers
+  - optional named `id` for cancellation
+- `heartbeat`
+  - interval: **10–3600 seconds**
+  - only one active heartbeat at a time
+
+## Sleep Interceptor
+
+This package also intercepts `sleep` in bash and blocks it only when `sleep` is the **only or last command** in a call.
+
+- `sleep 60` → **blocked** (only command)
+- `npm run build && sleep 60` → **blocked** (`sleep` is last)
+- `sleep 5 && npm start` → **allowed** (`sleep` is a startup delay before real work)
+
+Disable interception with:
+
+```bash
+PI_SLEEP_INTERCEPTOR=0
+```
+
+## Best Practices
+
+- Put actionable context in timer messages (what to check, what command to run)
+- Choose reasonable intervals (don’t poll every 10s for long operations)
+- Stop heartbeats when done (they continue until explicitly stopped)
+- Use chained timers for progressive backoff: `30s -> 60s -> 120s`
+
+## Development
+
+```bash
+npm test           # vitest run
+npm run typecheck  # tsc --noEmit
+npm run lint       # eslint
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@cad0p/pi-heartbeat",
+  "version": "0.0.1-20260814.0",
+  "description": "Non-blocking timers and heartbeats for pi agents — stop using sleep",
+  "author": "Marc Fargas",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cad0p/pi-heartbeat.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "pi",
+    "pi-package",
+    "agent",
+    "timer",
+    "heartbeat",
+    "cron",
+    "non-blocking",
+    "polling"
+  ],
+  "files": [
+    "src/**/*.ts",
+    "skills/**/*.md",
+    ".well-known/**",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.84.0"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/ __tests__/",
+    "test:integration": "vitest run --config vitest.integration.config.ts"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.27.0",
+    "@sinclair/typebox": "^0.34.0",
+    "eslint": "^9.27.0",
+    "globals": "^16.1.0",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.32.1",
+    "vitest": "^3.1.4",
+    "@changesets/cli": "^2.29.3",
+    "@marcfargas/pi-test-harness": "^0.4.1",
+    "@earendil-works/pi-coding-agent": "^0.84.0"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  }
+}

package/skills/pi-heartbeat/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: pi-heartbeat
+description: >-
+  Non-blocking timers and heartbeats for pi agents. Use instead of `sleep` when waiting
+  for builds, deployments, CI pipelines, or any async process. The agent returns to idle
+  immediately and gets woken up when the timer fires.
+  Triggers: timer, heartbeat, wait for build, poll, cron, wake me up, non-blocking wait,
+  check back later, monitor deployment, periodic check.
+---
+
+# Heartbeat & Timer Tools
+
+2 tools for non-blocking waiting. Stop using `sleep` — it blocks the chat.
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `timer` | One-shot "wake me up in N seconds" with a context message |
+| `heartbeat` | Periodic "ping me every N seconds" (start/stop/status) |
+
+## When to Use
+
+| Scenario | Before (blocks chat) | After (non-blocking) |
+|----------|---------------------|---------------------|
+| Wait for build | `sleep 60 && gh run view 42` | `timer(60, "Check build #42")` |
+| Monitor deploy | `while true; do sleep 30; check; done` | `heartbeat(start, 30, "Check deploy")` |
+| Rate-limited API | `sleep 10` between calls | `timer(10, "Resume API calls")` |
+
+## How It Works
+
+1. Agent calls `timer` or `heartbeat` — tool returns **immediately**
+2. Agent finishes response, goes idle — **user can chat freely**
+3. When timer fires, a message is injected via `sendMessage({ triggerTurn: true })`
+4. Agent wakes up with full context of what it was waiting for
+5. Agent acts (check status, retry, etc.) — can set another timer if needed
+
+## Timer
+
+```
+timer(seconds: 60, message: "Check if build #42 finished — run gh run view 42")
+```
+
+- Returns immediately with timer ID
+- Multiple timers can be active simultaneously
+- Optional `id` parameter for named timers (enables cancellation)
+- Max 3600 seconds (1 hour)
+
+## Heartbeat
+
+```
+heartbeat(action: "start", interval_seconds: 30, message: "Check deploy status")
+heartbeat(action: "status")
+heartbeat(action: "stop")
+```
+
+- Only one heartbeat active at a time (starting a new one stops the previous)
+- Min interval: 10 seconds
+- Tracks tick count for monitoring duration
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/cancel-timer` | List active timers and heartbeat |
+| `/cancel-timer <id>` | Cancel a specific timer |
+| `/cancel-timer heartbeat` | Stop the heartbeat |
+| `/cancel-timer all` | Cancel everything |
+
+## Best Practices
+
+- **Include actionable context** in the message: what to check, what command to run
+- **Set reasonable intervals** — don't heartbeat every 10s for a 30-minute deploy
+- **Stop heartbeats** when done — they keep firing until stopped
+- **Chain timers** for progressive backoff: check at 30s, then 60s, then 120s

package/src/commands/cancel.ts

@@ -0,0 +1,50 @@
+/**
+ * /cancel-timer command — list or cancel timers and heartbeats.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { TimerManager } from "../timer-manager.js";
+
+export function registerCancelCommand(pi: ExtensionAPI, manager: TimerManager): void {
+	pi.registerCommand("cancel-timer", {
+		description: "Cancel a timer by ID, 'heartbeat' to stop the heartbeat, or 'all' for everything",
+		handler: async (args, ctx) => {
+			const target = args.trim();
+
+			if (!target) {
+				const timers = manager.getActiveTimerIds();
+				const hb = manager.getHeartbeatState();
+				const hbText = hb
+					? `Heartbeat #${hb.id} active (every ${hb.intervalSeconds}s, ${hb.tick} ticks)`
+					: "No heartbeat";
+				ctx.ui.notify(
+					`Timers: ${timers.length ? timers.join(", ") : "none"}. ${hbText}`,
+					"info",
+				);
+				return;
+			}
+
+			if (target === "all") {
+				manager.clearAll();
+				ctx.ui.notify("All timers and heartbeats cancelled.", "info");
+				return;
+			}
+
+			if (target === "heartbeat") {
+				const stopped = manager.stopHeartbeat();
+				if (stopped) {
+					ctx.ui.notify(`Heartbeat #${stopped.id} stopped.`, "info");
+				} else {
+					ctx.ui.notify("No heartbeat was running.", "warning");
+				}
+				return;
+			}
+
+			if (manager.cancelTimer(target)) {
+				ctx.ui.notify(`Timer [${target}] cancelled.`, "info");
+			} else {
+				ctx.ui.notify(`No timer with ID [${target}] found.`, "warning");
+			}
+		},
+	});
+}

package/src/guards/prompt-injection.ts

@@ -0,0 +1,31 @@
+/**
+ * System prompt injection — tells the agent about timer/heartbeat on every turn.
+ *
+ * Injected via before_agent_start so the agent knows the tools exist
+ * even if the skill isn't loaded.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const TIMER_PROMPT = `
+## Non-blocking Timers (pi-heartbeat extension)
+
+You have two tools for non-blocking waiting. **Never use \`sleep\` for delays >5 seconds** — it blocks the chat.
+
+- **\`timer(seconds, message)\`** — One-shot. Returns immediately, wakes you up after N seconds with the message. Use instead of \`sleep\`.
+- **\`heartbeat(action, interval_seconds, message)\`** — Periodic. Pings you every N seconds. Use for monitoring (deploys, CI, long builds).
+
+When you need to wait for something:
+1. Call \`timer(seconds: N, message: "what to check and how")\`
+2. Tell the user you'll check back in Ns
+3. Finish your response — user can chat freely
+4. When woken up, check status and act (or set another timer)
+`.trim();
+
+export function registerPromptInjection(pi: ExtensionAPI): void {
+	pi.on("before_agent_start", async (event) => {
+		return {
+			systemPrompt: event.systemPrompt + "\n\n" + TIMER_PROMPT,
+		};
+	});
+}

package/src/guards/sleep-interceptor.ts

@@ -0,0 +1,80 @@
+/**
+ * Sleep interceptor — catches `sleep` in bash commands and redirects to timer tool.
+ *
+ * Short sleeps (≤5s) are allowed — they're typically "wait for server to boot".
+ * Longer sleeps get blocked with a message telling the agent to use `timer` instead.
+ *
+ * Only blocks when sleep is the LAST (or only) command segment — a leading
+ * `sleep 60 && curl something` is fine; a trailing `build && sleep 60` is not.
+ *
+ * Disable entirely by setting env var: PI_SLEEP_INTERCEPTOR=0
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { isToolCallEventType } from "@earendil-works/pi-coding-agent";
+
+/** Threshold in seconds — sleeps above this get blocked */
+const SLEEP_THRESHOLD = 5;
+
+/** Matches a segment that is SOLELY a sleep call (no operators). */
+const SOLE_SLEEP_PATTERN = /^\s*sleep\s+(\d+(?:\.\d+)?)\s*([smh]?)\s*$/;
+
+/**
+ * Parse sleep duration from a SINGLE command segment (no operators).
+ * Segment must be SOLELY a sleep command (whitespace OK).
+ * Pattern: /^\s*sleep\s+(\d+(?:\.\d+)?)\s*([smh]?)\s*$/
+ * Returns null if not a sole sleep.
+ */
+export function segmentSleepSeconds(segment: string): number | null {
+	const match = SOLE_SLEEP_PATTERN.exec(segment);
+	if (!match) return null;
+
+	const value = parseFloat(match[1]);
+	const unit = match[2] || "s";
+
+	if (unit === "m") return value * 60;
+	if (unit === "h") return value * 3600;
+	return value;
+}
+
+/**
+ * Returns sleep duration if the command's LAST segment is a sleep call.
+ * Splits on &&, ||, |, ; (simple split, best-effort, no quote handling).
+ * Trims and filters empty segments. Checks the last one.
+ * Returns null if sleep is not the trailing command (or no sleep).
+ */
+export function getTrailingSleepSeconds(command: string): number | null {
+	const segments = command
+		.split(/&&|\|\||[|;]/)
+		.map((s) => s.trim())
+		.filter((s) => s.length > 0);
+
+	if (segments.length === 0) return null;
+
+	const last = segments[segments.length - 1];
+	return segmentSleepSeconds(last);
+}
+
+export function registerSleepInterceptor(pi: ExtensionAPI): void {
+	if (process.env.PI_SLEEP_INTERCEPTOR === "0") return;
+
+	pi.on("tool_call", async (event) => {
+		if (!isToolCallEventType("bash", event)) return;
+
+		const command = event.input.command;
+		const sleepSeconds = getTrailingSleepSeconds(command);
+
+		if (sleepSeconds === null || sleepSeconds <= SLEEP_THRESHOLD) return;
+
+		return {
+			block: true,
+			reason:
+				`Blocked: \`sleep ${sleepSeconds}s\` blocks the chat — the user can't interact while waiting.\n\n` +
+				`Use the \`timer\` tool instead:\n` +
+				`  timer(seconds: ${Math.ceil(sleepSeconds)}, message: "describe what you're waiting for and what to check")\n\n` +
+				`The timer returns immediately (non-blocking), then wakes you up after ${Math.ceil(sleepSeconds)}s.\n` +
+				`For periodic checks, use \`heartbeat(action: "start", interval_seconds: ${Math.min(Math.ceil(sleepSeconds), 60)})\`.\n\n` +
+				`Short sleeps (≤${SLEEP_THRESHOLD}s) are still allowed for things like waiting for a server to boot.`,
+		};
+	});
+}

package/src/index.ts

@@ -0,0 +1,37 @@
+/**
+ * pi-heartbeat — Non-blocking timers and heartbeats for pi agents.
+ *
+ * Extension entry point. Registers:
+ *   - timer/heartbeat tools (the alternatives to sleep)
+ *   - sleep interceptor (blocks sleep >5s in bash, redirects to timer)
+ *   - system prompt injection (teaches the agent about the tools)
+ *   - /cancel-timer command
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerTimerTool } from "./tools/timer.js";
+import { registerHeartbeatTool } from "./tools/heartbeat.js";
+import { TimerManager } from "./timer-manager.js";
+import { registerCancelCommand } from "./commands/cancel.js";
+import { registerSleepInterceptor } from "./guards/sleep-interceptor.js";
+import { registerPromptInjection } from "./guards/prompt-injection.js";
+
+export default function activate(pi: ExtensionAPI): void {
+	const manager = new TimerManager(pi);
+
+	// Tools
+	registerTimerTool(pi, manager);
+	registerHeartbeatTool(pi, manager);
+
+	// Guards — block sleep, inject prompt
+	registerSleepInterceptor(pi);
+	registerPromptInjection(pi);
+
+	// Commands
+	registerCancelCommand(pi, manager);
+
+	// Cleanup
+	pi.on("session_shutdown", async () => {
+		manager.clearAll();
+	});
+}

package/src/timer-manager.ts

@@ -0,0 +1,165 @@
+/**
+ * TimerManager — Centralized timer/heartbeat state management.
+ *
+ * Handles one-shot timers and periodic heartbeats.
+ * Fires messages via pi.sendMessage({ triggerTurn: true }) to wake the agent.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export interface ActiveTimer {
+	id: string;
+	seconds: number;
+	message: string;
+	createdAt: string;
+}
+
+export interface HeartbeatState {
+	id: number;
+	intervalSeconds: number;
+	message: string;
+	tick: number;
+	createdAt: string;
+}
+
+export class TimerManager {
+	private timers = new Map<string, NodeJS.Timeout>();
+	private timerCounter = 0;
+	private heartbeatInterval: NodeJS.Timeout | undefined;
+	private heartbeatState: HeartbeatState | undefined;
+	private heartbeatIdCounter = 0;
+
+	constructor(private pi: ExtensionAPI) {}
+
+	// ── One-shot timers ─────────────────────────────────────────────
+
+	setTimer(seconds: number, message: string, id?: string): string {
+		const timerId = id ?? `timer-${++this.timerCounter}`;
+
+		// Cancel existing timer with same ID
+		this.cancelTimer(timerId);
+
+		const timeout = setTimeout(() => {
+			this.timers.delete(timerId);
+
+			try {
+				this.pi.sendMessage(
+					{
+						customType: "heartbeat-timer",
+						content: `⏰ Timer [${timerId}] fired (after ${seconds}s): ${message}`,
+						display: true,
+						details: {
+							type: "timer",
+							timerId,
+							seconds,
+							message,
+							firedAt: new Date().toISOString(),
+						},
+					},
+					{ triggerTurn: true },
+				);
+			} catch {
+				// The extension ctx is stale (session replaced/reloaded) or the
+				// session is shutting down. sendMessage will never succeed on
+				// this ctx, so there's nothing useful to do. The timer has
+				// already been removed from `this.timers` above. Swallow to
+				// prevent an uncaughtException that would kill the pi process.
+			}
+		}, seconds * 1000);
+
+		this.timers.set(timerId, timeout);
+		return timerId;
+	}
+
+	cancelTimer(id: string): boolean {
+		const timeout = this.timers.get(id);
+		if (timeout) {
+			clearTimeout(timeout);
+			this.timers.delete(id);
+			return true;
+		}
+		return false;
+	}
+
+	getActiveTimerIds(): string[] {
+		return [...this.timers.keys()];
+	}
+
+	// ── Heartbeat (periodic) ────────────────────────────────────────
+
+	startHeartbeat(intervalSeconds: number, message: string): HeartbeatState {
+		this.stopHeartbeat();
+
+		this.heartbeatIdCounter++;
+		const currentId = this.heartbeatIdCounter;
+
+		this.heartbeatState = {
+			id: currentId,
+			intervalSeconds,
+			message,
+			tick: 0,
+			createdAt: new Date().toISOString(),
+		};
+
+		const state = this.heartbeatState;
+
+		this.heartbeatInterval = setInterval(() => {
+			state.tick++;
+
+			try {
+				this.pi.sendMessage(
+					{
+						customType: "heartbeat-ping",
+						content: `💓 Heartbeat #${currentId} tick ${state.tick} (every ${intervalSeconds}s): ${message}`,
+						display: true,
+						details: {
+							type: "heartbeat",
+							heartbeatId: currentId,
+							tick: state.tick,
+							intervalSeconds,
+							message,
+							firedAt: new Date().toISOString(),
+						},
+					},
+					{ triggerTurn: true },
+				);
+			} catch {
+				// The extension ctx is stale (session replaced/reloaded) or the
+				// session is shutting down. Stop the interval so we don't keep
+				// throwing on every tick — a zombie interval that wastes CPU
+				// and risks crashing the process via uncaughtException.
+				this.stopHeartbeat();
+			}
+		}, intervalSeconds * 1000);
+
+		return { ...state };
+	}
+
+	stopHeartbeat(): HeartbeatState | undefined {
+		const state = this.heartbeatState;
+		if (this.heartbeatInterval) {
+			clearInterval(this.heartbeatInterval);
+			this.heartbeatInterval = undefined;
+			this.heartbeatState = undefined;
+		}
+		return state;
+	}
+
+	getHeartbeatState(): HeartbeatState | undefined {
+		return this.heartbeatState ? { ...this.heartbeatState } : undefined;
+	}
+
+	isHeartbeatActive(): boolean {
+		return this.heartbeatInterval !== undefined;
+	}
+
+	// ── Cleanup ─────────────────────────────────────────────────────
+
+	clearAll(): void {
+		for (const [, t] of this.timers) {
+			clearTimeout(t);
+		}
+		this.timers.clear();
+		this.stopHeartbeat();
+	}
+}

package/src/tools/heartbeat.ts

@@ -0,0 +1,100 @@
+/**
+ * Heartbeat tool — periodic non-blocking "ping me every N seconds".
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import type { TimerManager } from "../timer-manager.js";
+
+export function registerHeartbeatTool(pi: ExtensionAPI, manager: TimerManager): void {
+	pi.registerTool({
+		name: "heartbeat",
+		label: "Heartbeat",
+		description:
+			"Start or stop a periodic heartbeat. When running, you get woken up every N seconds " +
+			"with a status check message. Use for long-running monitoring " +
+			"(deployment progress, CI pipeline, server health, process supervision). " +
+			"Only one heartbeat can be active at a time. Starting a new one stops the previous.",
+		parameters: Type.Object({
+			action: Type.Union([Type.Literal("start"), Type.Literal("stop"), Type.Literal("status")]),
+			interval_seconds: Type.Optional(
+				Type.Number({
+					description: "Interval between heartbeats in seconds (default: 60, min: 10)",
+					minimum: 10,
+					maximum: 3600,
+				}),
+			),
+			message: Type.Optional(
+				Type.String({
+					description:
+						"Context for each heartbeat ping, e.g. 'Check deployment status on staging'",
+				}),
+			),
+		}),
+
+		async execute(_toolCallId, params): Promise<{ content: { type: "text"; text: string }[]; details: Record<string, any> }> {
+			if (params.action === "status") {
+				const state = manager.getHeartbeatState();
+				if (state) {
+					return {
+						content: [
+							{
+								type: "text" as const,
+								text: `Heartbeat #${state.id} active — every ${state.intervalSeconds}s, ${state.tick} ticks so far. Message: "${state.message}"`,
+							},
+						],
+						details: { active: true, ...state },
+					};
+				}
+				const timers = manager.getActiveTimerIds();
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `No heartbeat active. Active timers: ${timers.length ? timers.join(", ") : "none"}.`,
+						},
+					],
+					details: { active: false, timers },
+				};
+			}
+
+			if (params.action === "stop") {
+				const stopped = manager.stopHeartbeat();
+				if (stopped) {
+					return {
+						content: [
+							{
+								type: "text" as const,
+								text: `Heartbeat #${stopped.id} stopped after ${stopped.tick} ticks.`,
+							},
+						],
+						details: { stopped: true, ...stopped },
+					};
+				}
+				return {
+					content: [{ type: "text" as const, text: "No heartbeat was running." }],
+					details: { stopped: false },
+				};
+			}
+
+		// action === "start"
+			const intervalSec = params.interval_seconds ?? 60;
+			const msg = params.message ?? "Periodic status check";
+			const state = manager.startHeartbeat(intervalSec, msg);
+
+			return {
+				content: [
+					{
+						type: "text" as const,
+						text:
+							`Heartbeat #${state.id} started — pinging every ${intervalSec}s. ` +
+							`Message: "${msg}". ` +
+							`Use heartbeat(action: "stop") to cancel. ` +
+							`Finish your response — the user can chat freely.`,
+					},
+				],
+				details: { heartbeatId: state.id, intervalSeconds: intervalSec },
+			};
+		},
+	});
+}

package/src/tools/timer.ts

@@ -0,0 +1,54 @@
+/**
+ * Timer tool — one-shot non-blocking "wake me up in N seconds".
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import type { TimerManager } from "../timer-manager.js";
+
+export function registerTimerTool(pi: ExtensionAPI, manager: TimerManager): void {
+	pi.registerTool({
+		name: "timer",
+		label: "Timer",
+		description:
+			"Set a non-blocking timer. Returns immediately — you go idle and the user can chat. " +
+			"When the timer fires, you get woken up with the message. " +
+			"Use this instead of `sleep` when you need to wait for something " +
+			"(build completion, deployment, polling intervals, etc.). " +
+			"You can set multiple timers simultaneously.",
+		parameters: Type.Object({
+			seconds: Type.Number({
+				description: "Delay in seconds before waking up",
+				minimum: 1,
+				maximum: 3600,
+			}),
+			message: Type.String({
+				description:
+					"Context message delivered when timer fires. Include what you were waiting for " +
+					"and what to do next, e.g. 'Check if build #42 finished — run `gh run view 42`'",
+			}),
+			id: Type.Optional(
+				Type.String({
+					description: "Optional timer ID for cancellation. Auto-generated if omitted.",
+				}),
+			),
+		}),
+
+		async execute(_toolCallId, params) {
+			const timerId = manager.setTimer(params.seconds, params.message, params.id);
+
+			return {
+				content: [
+					{
+						type: "text" as const,
+						text:
+							`Timer [${timerId}] set for ${params.seconds}s. ` +
+							`You will be woken up with: "${params.message}". ` +
+							`Finish your response — the user can chat freely while waiting.`,
+					},
+				],
+				details: { timerId, seconds: params.seconds },
+			};
+		},
+	});
+}