pi-afk 0.1.0

package/extensions/lock.ts

@@ -0,0 +1,320 @@
+import { createHash, randomUUID } from "node:crypto";
+import { chmod, lstat, mkdir, open, readFile, rename, rm, stat } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { getAfkHome } from "./config.ts";
+
+export interface LockOwner {
+	pid: number;
+	createdAt: number;
+	cwd: string;
+}
+
+export type LockAcquireResult = { ok: true } | { ok: false; owner?: LockOwner; reason: string };
+
+export interface AfkLockOptions {
+	pid?: number;
+	cwd?: string;
+	isProcessAlive?: (pid: number) => boolean;
+	invalidLockStaleMs?: number;
+}
+
+interface LegacyAfkLockOptions extends AfkLockOptions {
+	token: string;
+	home: string;
+}
+
+const DEFAULT_INVALID_LOCK_STALE_MS = 30_000;
+const OWNER_FILE = "owner.json";
+
+export function lockPathForToken(token: string, home = getAfkHome()): string {
+	const hash = createHash("sha256").update(token).digest("hex").slice(0, 32);
+	return join(home, "locks", `${hash}.lock`);
+}
+
+function defaultIsProcessAlive(pid: number): boolean {
+	if (!Number.isSafeInteger(pid) || pid <= 0) return false;
+
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		if (error && typeof error === "object" && "code" in error) {
+			if (error.code === "ESRCH") return false;
+			if (error.code === "EPERM") return true;
+		}
+		return false;
+	}
+}
+
+function hasErrorCode(error: unknown, code: string): boolean {
+	return Boolean(error && typeof error === "object" && "code" in error && error.code === code);
+}
+
+function parseLockOwner(raw: string): LockOwner | undefined {
+	try {
+		const parsed = JSON.parse(raw) as unknown;
+		if (!parsed || typeof parsed !== "object") return undefined;
+		const candidate = parsed as Record<string, unknown>;
+		if (!Number.isSafeInteger(candidate.pid) || Number(candidate.pid) <= 0) return undefined;
+		if (typeof candidate.createdAt !== "number" || !Number.isFinite(candidate.createdAt)) return undefined;
+		if (typeof candidate.cwd !== "string" || candidate.cwd.length === 0) return undefined;
+		return { pid: candidate.pid as number, createdAt: candidate.createdAt, cwd: candidate.cwd };
+	} catch (error) {
+		if (error instanceof SyntaxError) return undefined;
+		throw error;
+	}
+}
+
+function sameOwner(left: LockOwner, right: LockOwner): boolean {
+	return left.pid === right.pid && left.createdAt === right.createdAt && left.cwd === right.cwd;
+}
+
+async function fsyncDirectory(path: string): Promise<void> {
+	if (process.platform === "win32") return;
+
+	let handle;
+	try {
+		handle = await open(path, "r");
+		await handle.sync();
+	} catch (error) {
+		if (error && typeof error === "object" && "code" in error) {
+			const code = error.code;
+			if (code === "EINVAL" || code === "ENOTSUP" || code === "EISDIR" || code === "EPERM") return;
+		}
+		throw error;
+	} finally {
+		await handle?.close();
+	}
+}
+
+async function validateExistingDirectory(path: string, label: string): Promise<boolean> {
+	let info;
+	try {
+		info = await lstat(path);
+	} catch (error) {
+		if (hasErrorCode(error, "ENOENT")) return false;
+		throw error;
+	}
+
+	if (info.isSymbolicLink()) throw new Error(`${label} is a symlink: ${path}`);
+	if (!info.isDirectory()) throw new Error(`${label} must be a real directory: ${path}`);
+	return true;
+}
+
+async function writeSyncedFile(path: string, content: string): Promise<void> {
+	let handle;
+	try {
+		handle = await open(path, "wx", 0o600);
+		await handle.writeFile(content, "utf8");
+		await handle.sync();
+	} finally {
+		await handle?.close();
+	}
+}
+
+export class AfkLock {
+	private readonly token: string;
+	private readonly home: string;
+	private readonly path: string;
+	private readonly lockDir: string;
+	private readonly ownerPath: string;
+	private readonly pid: number;
+	private readonly cwd: string;
+	private readonly isProcessAlive: (pid: number) => boolean;
+	private readonly invalidLockStaleMs: number;
+	private acquiredOwner: LockOwner | undefined;
+
+	constructor(token: string, home?: string, options?: AfkLockOptions);
+	constructor(options: LegacyAfkLockOptions);
+	constructor(tokenOrOptions: string | LegacyAfkLockOptions, home = getAfkHome(), options: AfkLockOptions = {}) {
+		if (typeof tokenOrOptions === "string") {
+			this.token = tokenOrOptions;
+			this.home = home;
+		} else {
+			this.token = tokenOrOptions.token;
+			this.home = tokenOrOptions.home;
+			options = tokenOrOptions;
+		}
+		this.path = lockPathForToken(this.token, this.home);
+		this.lockDir = join(this.home, "locks");
+		this.ownerPath = join(this.path, OWNER_FILE);
+		this.pid = options.pid ?? process.pid;
+		this.cwd = options.cwd ?? process.cwd();
+		this.isProcessAlive = options.isProcessAlive ?? defaultIsProcessAlive;
+		this.invalidLockStaleMs = options.invalidLockStaleMs ?? DEFAULT_INVALID_LOCK_STALE_MS;
+	}
+
+	async acquire(): Promise<LockAcquireResult> {
+		await this.ensureLockDir();
+
+		for (;;) {
+			const owner: LockOwner = { pid: this.pid, createdAt: Date.now(), cwd: this.cwd };
+			const publishResult = await this.tryCreateLockDirectory(owner);
+			if (publishResult === "published") {
+				this.acquiredOwner = owner;
+				return { ok: true };
+			}
+
+			const existing = await this.readExistingLock(this.path);
+			if (!existing) continue;
+
+			if (!existing.owner) {
+				if (!(await this.isInvalidLockStale(this.path))) {
+					return { ok: false, reason: "lock owner metadata is invalid and fresh" };
+				}
+				if (await this.claimAndRemoveStaleLock(existing)) continue;
+				return { ok: false, reason: "lock changed during invalid cleanup" };
+			}
+
+			if (this.isProcessAlive(existing.owner.pid)) {
+				return { ok: false, owner: existing.owner, reason: "owner process is alive" };
+			}
+
+			if (await this.claimAndRemoveStaleLock(existing)) continue;
+			const changed = await this.readExistingLock(this.path);
+			if (changed?.owner) return { ok: false, owner: changed.owner, reason: "lock changed during stale cleanup" };
+			return { ok: false, reason: "lock changed during stale cleanup" };
+		}
+	}
+
+	async release(): Promise<void> {
+		if (!this.acquiredOwner) return;
+		const claimPath = await this.claimLockDirectory("release");
+		if (!claimPath) {
+			this.acquiredOwner = undefined;
+			return;
+		}
+
+		const claimed = await this.readExistingLock(claimPath);
+		if (claimed?.owner && sameOwner(claimed.owner, this.acquiredOwner)) {
+			await rm(claimPath, { recursive: true, force: true });
+			await fsyncDirectory(this.lockDir);
+		} else {
+			await this.restoreClaimedLock(claimPath);
+		}
+		this.acquiredOwner = undefined;
+	}
+
+	private async ensureLockDir(): Promise<void> {
+		const homeExists = await validateExistingDirectory(this.home, "AFK home");
+		if (!homeExists) await mkdir(this.home, { recursive: true, mode: 0o700 });
+		await chmod(this.home, 0o700);
+
+		try {
+			await mkdir(this.lockDir, { mode: 0o700 });
+			await fsyncDirectory(this.home);
+		} catch (error) {
+			if (!hasErrorCode(error, "EEXIST")) throw error;
+		}
+
+		await validateExistingDirectory(this.lockDir, "lock directory");
+		await chmod(this.lockDir, 0o700);
+		await fsyncDirectory(this.lockDir);
+	}
+
+	private async tryCreateLockDirectory(owner: LockOwner): Promise<"published" | "exists"> {
+		try {
+			await mkdir(this.path, { mode: 0o700 });
+		} catch (error) {
+			if (hasErrorCode(error, "EEXIST")) return "exists";
+			throw error;
+		}
+
+		try {
+			await writeSyncedFile(this.ownerPath, `${JSON.stringify(owner)}\n`);
+			await fsyncDirectory(this.path);
+			await fsyncDirectory(this.lockDir);
+			return "published";
+		} catch (error) {
+			await rm(this.path, { recursive: true, force: true });
+			await fsyncDirectory(this.lockDir);
+			throw error;
+		}
+	}
+
+	private async readExistingLock(path: string): Promise<{ raw: string | undefined; owner: LockOwner | undefined } | undefined> {
+		let info;
+		try {
+			info = await lstat(path);
+		} catch (error) {
+			if (hasErrorCode(error, "ENOENT")) return undefined;
+			throw error;
+		}
+
+		if (info.isSymbolicLink() || !info.isDirectory()) {
+			throw new Error(`lock path exists but is not a directory: ${path}`);
+		}
+
+		try {
+			const raw = await readFile(join(path, OWNER_FILE), "utf8");
+			return { raw, owner: parseLockOwner(raw) };
+		} catch (error) {
+			if (hasErrorCode(error, "ENOENT")) return { raw: undefined, owner: undefined };
+			throw error;
+		}
+	}
+
+	private async isInvalidLockStale(path: string): Promise<boolean> {
+		try {
+			const directoryInfo = await stat(path);
+			let newestMetadataMtime = directoryInfo.mtimeMs;
+			try {
+				const ownerInfo = await stat(join(path, OWNER_FILE));
+				newestMetadataMtime = Math.max(newestMetadataMtime, ownerInfo.mtimeMs);
+			} catch (error) {
+				if (!hasErrorCode(error, "ENOENT")) throw error;
+			}
+			return Date.now() - newestMetadataMtime > this.invalidLockStaleMs;
+		} catch (error) {
+			if (hasErrorCode(error, "ENOENT")) return false;
+			throw error;
+		}
+	}
+
+	private async claimAndRemoveStaleLock(expected: { raw: string | undefined; owner: LockOwner | undefined }): Promise<boolean> {
+		const claimPath = await this.claimLockDirectory("stale");
+		if (!claimPath) return false;
+
+		const claimed = await this.readExistingLock(claimPath);
+		if (!claimed || !this.sameLockMetadata(claimed, expected)) {
+			await this.restoreClaimedLock(claimPath);
+			return false;
+		}
+
+		await rm(claimPath, { recursive: true, force: true });
+		await fsyncDirectory(this.lockDir);
+		return true;
+	}
+
+	private async claimLockDirectory(reason: "release" | "stale"): Promise<string | undefined> {
+		const claimPath = join(this.lockDir, `.${basename(this.path)}.${process.pid}.${randomUUID()}.${reason}`);
+		try {
+			await rename(this.path, claimPath);
+			await fsyncDirectory(this.lockDir);
+			return claimPath;
+		} catch (error) {
+			if (hasErrorCode(error, "ENOENT") || hasErrorCode(error, "EEXIST")) return undefined;
+			throw error;
+		}
+	}
+
+	private async restoreClaimedLock(claimPath: string): Promise<void> {
+		try {
+			await rename(claimPath, this.path);
+			await fsyncDirectory(this.lockDir);
+		} catch (error) {
+			if (hasErrorCode(error, "ENOENT") || hasErrorCode(error, "EEXIST")) return;
+			throw error;
+		}
+	}
+
+	private sameLockMetadata(
+		left: { raw: string | undefined; owner: LockOwner | undefined },
+		right: { raw: string | undefined; owner: LockOwner | undefined },
+	): boolean {
+		if (left.raw !== right.raw) return false;
+		if (!left.owner && !right.owner) return true;
+		if (!left.owner || !right.owner) return false;
+		return sameOwner(left.owner, right.owner);
+	}
+}

package/extensions/telegram-format.ts

@@ -0,0 +1,58 @@
+import type { ActiveTelegramQuestion } from "./ask-queue.ts";
+
+export interface TelegramQuestionButton {
+	text: string;
+	callbackData: string;
+}
+
+export interface TelegramQuestionPayload {
+	text: string;
+	buttons: TelegramQuestionButton[][];
+}
+
+export interface ParsedCallbackData {
+	nonce: string;
+	optionIndex: number;
+}
+
+export function buildCallbackData(nonce: string, optionIndex: number): string {
+	return `afk:${nonce}:${optionIndex}`;
+}
+
+export function parseCallbackData(data: string): ParsedCallbackData | undefined {
+	const parts = data.split(":");
+	if (parts.length !== 3) return undefined;
+
+	const [prefix, nonce, rawOptionIndex] = parts;
+	if (prefix !== "afk" || !nonce || !rawOptionIndex) return undefined;
+
+	const optionIndex = Number(rawOptionIndex);
+	if (!Number.isSafeInteger(optionIndex) || optionIndex < 0) return undefined;
+
+	return { nonce, optionIndex };
+}
+
+export function buildQuestionPayload(active: ActiveTelegramQuestion): TelegramQuestionPayload {
+	const lines = [
+		`Question ${active.questionIndex + 1}/${active.totalQuestions}`,
+		"",
+		active.question.question,
+		"",
+		...active.question.options.map((option, index) => {
+			const description = option.description ? ` — ${option.description}` : "";
+			return `${index + 1}. ${option.label}${description}`;
+		}),
+		"",
+		"Choose an option below, or reply with custom text.",
+	];
+
+	return {
+		text: lines.join("\n"),
+		buttons: active.question.options.map((option, index) => [
+			{
+				text: `${option.recommended ? "⭐ " : ""}${option.label}`,
+				callbackData: buildCallbackData(active.nonce, index),
+			},
+		]),
+	};
+}

package/extensions/telegram.ts

@@ -0,0 +1,176 @@
+import { Bot, InlineKeyboard } from "grammy";
+import type { ActiveTelegramQuestion } from "./ask-queue.ts";
+import type { AfkConfig, LinkedTelegramCallback, LinkedTelegramMessage } from "./types.ts";
+import { buildQuestionPayload } from "./telegram-format.ts";
+
+export interface TelegramBridgeHandlers {
+	onText?: (message: LinkedTelegramMessage) => void | Promise<void>;
+	onMessage?: (message: LinkedTelegramMessage) => void | Promise<void>;
+	onCallback?: (callback: LinkedTelegramCallback) => void | Promise<void>;
+	onPollingError?: (error: unknown) => void;
+}
+
+interface TelegramBotLike {
+	on(event: "message:text" | "callback_query:data", handler: (ctx: TelegramContextLike) => void | Promise<void>): void;
+	catch?(handler: (error: unknown) => void): void;
+	init(): Promise<void>;
+	start(): void | Promise<void>;
+	stop(): void;
+	api: {
+		getMe(): Promise<{ username?: string; first_name: string }>;
+		sendMessage(chatId: number, text: string, options?: unknown): Promise<void>;
+		answerCallbackQuery(callbackQueryId: string, options?: { text: string }): Promise<void>;
+	};
+}
+
+interface TelegramContextLike {
+	chat: { id: number; type?: string };
+	from: { id: number };
+	message: { text: string };
+	callbackQuery: { id: string; data: string; message?: { chat: { id: number } } };
+}
+
+export interface TelegramBridgePort {
+	getMe(): Promise<{ username: string }>;
+	start(): Promise<void>;
+	stop(): void;
+	sendMessage(chatId: number, text: string): Promise<void>;
+	sendQuestion(config: Pick<AfkConfig, "chatId">, active: ActiveTelegramQuestion): Promise<void>;
+	answerCallback(callbackQueryId: string, text?: string): Promise<void>;
+}
+
+export class TelegramBridge implements TelegramBridgePort {
+	private readonly bot: TelegramBotLike;
+	private pollingPromise: Promise<void> | undefined;
+
+	constructor(token: string, private readonly handlers: TelegramBridgeHandlers, bot?: TelegramBotLike) {
+		this.bot = bot ?? (new Bot(token) as unknown as TelegramBotLike);
+		this.bot.on("message:text", (ctx) =>
+			this.isolateHandlerError(async () => {
+				const handler = this.handlers.onText ?? this.handlers.onMessage;
+				await handler?.({
+					chatId: ctx.chat.id,
+					userId: ctx.from.id,
+					text: ctx.message.text,
+					isPrivate: ctx.chat.type === "private",
+				});
+			}),
+		);
+		this.bot.on("callback_query:data", (ctx) => this.handleCallbackQuery(ctx));
+		this.bot.catch?.((error) => this.reportPollingError(error));
+	}
+
+	async getMe(): Promise<{ username: string }> {
+		const me = await this.bot.api.getMe();
+		return { username: me.username ?? me.first_name };
+	}
+
+	async start(): Promise<void> {
+		if (this.pollingPromise) return;
+
+		await this.bot.init();
+		if (this.pollingPromise) return;
+
+		let pollingResult: void | Promise<void>;
+		try {
+			pollingResult = this.bot.start();
+		} catch (error) {
+			this.pollingPromise = undefined;
+			throw error;
+		}
+
+		const polling = Promise.resolve(pollingResult);
+		this.pollingPromise = polling.catch((error: unknown) => {
+			this.pollingPromise = undefined;
+			this.reportPollingError(error);
+		});
+		await this.observeImmediatePollingFailure(polling);
+	}
+
+	stop(): void {
+		if (!this.pollingPromise) return;
+		try {
+			this.bot.stop();
+		} catch (error) {
+			this.reportPollingError(error);
+		} finally {
+			this.pollingPromise = undefined;
+		}
+	}
+
+	async sendMessage(chatId: number, text: string): Promise<void> {
+		await this.bot.api.sendMessage(chatId, text);
+	}
+
+	async sendQuestion(config: Pick<AfkConfig, "chatId">, active: ActiveTelegramQuestion): Promise<void> {
+		const payload = buildQuestionPayload(active);
+		const keyboard = new InlineKeyboard();
+		payload.buttons.forEach((row, rowIndex) => {
+			if (rowIndex > 0) keyboard.row();
+			for (const button of row) {
+				keyboard.text(button.text, button.callbackData);
+			}
+		});
+
+		await this.bot.api.sendMessage(config.chatId, payload.text, { reply_markup: keyboard });
+	}
+
+	async answerCallback(callbackQueryId: string, text?: string): Promise<void> {
+		if (text) {
+			await this.bot.api.answerCallbackQuery(callbackQueryId, { text });
+			return;
+		}
+		await this.bot.api.answerCallbackQuery(callbackQueryId);
+	}
+
+	private async handleCallbackQuery(ctx: TelegramContextLike): Promise<void> {
+		const { callbackQuery } = ctx;
+		const message = callbackQuery.message;
+		if (!message) {
+			await this.isolateHandlerError(() => this.answerCallback(callbackQuery.id));
+			return;
+		}
+
+		try {
+			await this.handlers.onCallback?.({
+				callbackQueryId: callbackQuery.id,
+				chatId: message.chat.id,
+				userId: ctx.from.id,
+				data: callbackQuery.data,
+			});
+		} catch (error) {
+			try {
+				await this.answerCallback(callbackQuery.id);
+			} catch (answerError) {
+				this.reportPollingError(answerError);
+			}
+			this.reportPollingError(error);
+		}
+	}
+
+	private async observeImmediatePollingFailure(polling: Promise<void>): Promise<void> {
+		const stillPolling = Symbol("stillPolling");
+		await Promise.race([
+			polling,
+			new Promise<typeof stillPolling>((resolve) => {
+				setImmediate(() => resolve(stillPolling));
+			}),
+		]);
+	}
+
+	private async isolateHandlerError(handler: () => void | Promise<void>): Promise<void> {
+		try {
+			await handler();
+		} catch (error) {
+			this.reportPollingError(error);
+		}
+	}
+
+	private reportPollingError(error: unknown): void {
+		try {
+			this.handlers.onPollingError?.(error);
+		} catch {
+			// Keep polling alive even if the error reporter fails.
+		}
+	}
+}

package/extensions/types.ts

@@ -0,0 +1,65 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type, type Static } from "typebox";
+
+export interface AfkConfig {
+	botToken: string;
+	botUsername: string;
+	chatId: number;
+	userId: number;
+}
+
+export interface LinkedTelegramMessage {
+	chatId: number;
+	userId: number;
+	text: string;
+	isPrivate: boolean;
+}
+
+export interface LinkedTelegramCallback {
+	callbackQueryId: string;
+	chatId: number;
+	userId: number;
+	data: string;
+}
+
+export const AfkOptionSchema = Type.Object({
+	label: Type.String({ minLength: 1, description: "Button label shown in Telegram" }),
+	value: Type.String({ minLength: 1, description: "Value returned to the agent if selected" }),
+	description: Type.Optional(Type.String({ description: "Optional context shown in the Telegram message body" })),
+	recommended: Type.Optional(Type.Boolean({ description: "Marks this option as recommended in Telegram" })),
+});
+
+export const AfkQuestionSchema = Type.Object({
+	id: Type.String({ minLength: 1, description: "Stable identifier used in the returned answer" }),
+	question: Type.String({ minLength: 1, description: "Question text sent to Telegram" }),
+	options: Type.Array(AfkOptionSchema, { minItems: 1, description: "Single-select answer options" }),
+});
+
+export const AfkToolParamsSchema = Type.Object({
+	mode: StringEnum(["notify", "ask"] as const, { description: "Send a notification or ask blocking questions" }),
+	message: Type.Optional(Type.String({ description: "Notification text for mode=notify" })),
+	questions: Type.Optional(Type.Array(AfkQuestionSchema, { description: "Questions for mode=ask" })),
+});
+
+export type AfkOption = Static<typeof AfkOptionSchema>;
+export type AfkQuestion = Static<typeof AfkQuestionSchema>;
+export type AfkToolParams = Static<typeof AfkToolParamsSchema>;
+
+export interface AfkAnswer {
+	id: string;
+	value: string;
+	label: string;
+	wasCustom: boolean;
+}
+
+export interface AfkAskResult {
+	mode: "ask";
+	answers: AfkAnswer[];
+}
+
+export interface AfkNotifyResult {
+	mode: "notify";
+	sent: boolean;
+}
+
+export type AfkToolDetails = AfkAskResult | AfkNotifyResult | { mode: "disabled" | "cancelled" | "error"; reason: string };

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "pi-afk",
+  "version": "0.1.0",
+  "description": "A Pi package extension that allows the agent to communicate with the user when they're afk.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Maz Li",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HamdiMaz/afk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/HamdiMaz/afk/issues"
+  },
+  "homepage": "https://github.com/HamdiMaz/afk#readme",
+  "engines": {
+    "node": ">=20.6.0"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "afk"
+  ],
+  "files": [
+    "extensions",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/index.ts"
+    ]
+  },
+  "scripts": {
+    "test": "tsx --test tests/**/*.test.ts",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run typecheck && npm run lint && npm test",
+    "prepublishOnly": "npm run check"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^0.74.1",
+    "@earendil-works/pi-coding-agent": "^0.74.0",
+    "@earendil-works/pi-tui": "^0.74.0",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^25.7.0",
+    "eslint": "^10.3.0",
+    "tsx": "^4.21.0",
+    "typebox": "^1.1.38",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.59.3"
+  },
+  "dependencies": {
+    "grammy": "^1.43.0"
+  }
+}