pi-afk 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## v0.1.0
+
+- Initial Pi extension package scaffold.
+- Added `/afk` and `/afk-settings` commands for session-scoped Telegram AFK mode.
+- Added the `afk` agent tool for Telegram notifications and blocking questions.
+- Added persistent Telegram config storage, bot-token locking, serialized ask queue, Telegram formatting, and grammY long-polling bridge.
+- Added tests and documentation for the AFK MVP workflow.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hamdi Alareij
+
+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,60 @@
+# afk
+
+A Pi package extension that allows the agent to communicate with the user when they're afk.
+
+## Status
+
+AFK provides a Pi extension MVP with `/afk`, `/afk-settings`, and an `afk` agent tool backed by a linked Telegram bot.
+
+## AFK MVP usage
+
+1. Create a Telegram bot with BotFather and copy the bot token.
+2. Start Pi with this package loaded: `pi -e .`.
+3. Run `/afk-settings`.
+4. Paste the bot token when prompted.
+5. Send the displayed one-time code directly to the Telegram bot.
+6. Run `/afk` to enable AFK mode for the current Pi session.
+7. While AFK mode is on, the agent can use the `afk` tool to notify you or ask questions through Telegram.
+8. Run `/afk` again to turn AFK mode off.
+
+AFK mode is session-scoped. It turns off on `/new`, `/resume`, `/fork`, `/clone`, `/reload`, and Pi shutdown. Telegram bot settings remain saved in user config.
+
+## Install for local development
+
+```bash
+npm install
+npm run check
+```
+
+## Use with Pi during development
+
+```bash
+pi -e .
+```
+
+Pi loads the package through `package.json`:
+
+```json
+{ "pi": { "extensions": ["./extensions/index.ts"] } }
+```
+
+## Project layout
+
+```text
+extensions/index.ts             Pi extension entry point
+extensions/controller.ts        AFK runtime orchestration
+extensions/config.ts            Telegram config persistence
+extensions/lock.ts              Bot-token process lock
+extensions/ask-queue.ts         Serialized blocking question queue
+extensions/telegram.ts          grammY bridge
+extensions/telegram-format.ts   Telegram question/button formatting
+extensions/types.ts             Shared schemas and types
+extensions/README.md            Extension-specific notes
+tests/                          Node test runner tests
+```
+
+## Release checks
+
+```bash
+npm run check
+```

package/extensions/README.md

@@ -0,0 +1,12 @@
+# AFK Extension
+
+Runtime pieces:
+
+- `index.ts` wires Pi commands, tool registration, and lifecycle hooks.
+- `controller.ts` owns AFK runtime state and composes config, locking, Telegram, and the ask queue.
+- `config.ts` persists Telegram bot settings in user config.
+- `lock.ts` prevents two Pi processes from polling with the same bot token.
+- `ask-queue.ts` serializes blocking AFK questions.
+- `telegram.ts` adapts grammY long polling to the controller.
+- `telegram-format.ts` formats Telegram question messages and buttons.
+- `types.ts` contains shared schemas and TypeScript types.

package/extensions/ask-queue.ts

@@ -0,0 +1,231 @@
+import { randomUUID } from "node:crypto";
+import type { AfkAnswer, AfkQuestion } from "./types.ts";
+
+export interface ActiveTelegramQuestion {
+	requestId: string;
+	nonce: string;
+	questionIndex: number;
+	totalQuestions: number;
+	question: AfkQuestion;
+}
+
+export interface AskQueueTransport {
+	sendQuestion(active: ActiveTelegramQuestion): Promise<void>;
+	sendCancellation(reason: string): Promise<void>;
+}
+
+export interface AskQueueOptions {
+	makeNonce?: () => string;
+}
+
+interface QueuedAsk {
+	requestId: string;
+	questions: AfkQuestion[];
+	answers: AfkAnswer[];
+	resolve: (answers: AfkAnswer[]) => void;
+	reject: (error: Error) => void;
+	removeAbortListener: () => void;
+}
+
+interface ActiveAsk extends QueuedAsk {
+	questionIndex: number;
+	nonce: string;
+}
+
+export class AfkAskCancelledError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "AfkAskCancelledError";
+	}
+}
+
+const abortReason = (signal: AbortSignal): string => {
+	const { reason } = signal;
+	if (typeof reason === "string" && reason.trim()) return reason;
+	return "AFK ask was aborted";
+};
+
+export class AskQueue {
+	private readonly queue: QueuedAsk[] = [];
+	private active: ActiveAsk | undefined;
+	private readonly makeNonce: () => string;
+
+	constructor(
+		private readonly transport: AskQueueTransport,
+		options: AskQueueOptions = {},
+	) {
+		this.makeNonce = options.makeNonce ?? (() => randomUUID().slice(0, 8));
+	}
+
+	enqueue(questions: AfkQuestion[], signal?: AbortSignal): Promise<AfkAnswer[]> {
+		if (questions.length === 0) {
+			return Promise.reject(new Error("AFK ask requires at least one question"));
+		}
+
+		return new Promise<AfkAnswer[]>((resolve, reject) => {
+			const request: QueuedAsk = {
+				requestId: randomUUID(),
+				questions: questions.map((item) => ({
+					...item,
+					options: item.options.map((option) => ({ ...option })),
+				})),
+				answers: [],
+				resolve,
+				reject,
+				removeAbortListener: () => {},
+			};
+			const abort = () => {
+				const reason = signal ? abortReason(signal) : "AFK ask was aborted";
+				if (this.active?.requestId === request.requestId) {
+					this.cancelActive(reason);
+					return;
+				}
+
+				if (this.removeQueued(request.requestId)) {
+					request.removeAbortListener();
+					reject(new AfkAskCancelledError(reason));
+				}
+			};
+
+			if (signal?.aborted) {
+				reject(new AfkAskCancelledError(abortReason(signal)));
+				return;
+			}
+
+			if (signal) {
+				signal.addEventListener("abort", abort, { once: true });
+				request.removeAbortListener = () => signal.removeEventListener("abort", abort);
+			}
+
+			this.queue.push(request);
+			void this.pump();
+		});
+	}
+
+	async answerWithOption(nonce: string, optionIndex: number): Promise<boolean> {
+		const active = this.active;
+		if (!active || active.nonce !== nonce) return false;
+
+		const question = active.questions[active.questionIndex];
+		const option = question?.options[optionIndex];
+		if (!question || !option) return false;
+
+		active.answers.push({ id: question.id, value: option.value, label: option.label, wasCustom: false });
+		await this.advance();
+		return true;
+	}
+
+	async answerWithText(text: string): Promise<boolean> {
+		const active = this.active;
+		if (!active) return false;
+
+		const trimmed = text.trim();
+		if (!trimmed) return false;
+
+		const question = active.questions[active.questionIndex];
+		if (!question) return false;
+
+		active.answers.push({ id: question.id, value: trimmed, label: trimmed, wasCustom: true });
+		await this.advance();
+		return true;
+	}
+
+	cancelAll(reason: string): void {
+		const error = new AfkAskCancelledError(reason);
+		const hadActive = Boolean(this.active);
+
+		if (this.active) {
+			this.active.removeAbortListener();
+			this.active.reject(error);
+			this.active = undefined;
+		}
+
+		for (const item of this.queue.splice(0)) {
+			item.removeAbortListener();
+			item.reject(error);
+		}
+
+		if (hadActive) void this.transport.sendCancellation(reason).catch(() => {});
+	}
+
+	get hasPendingQuestion(): boolean {
+		return Boolean(this.active);
+	}
+
+	private async pump(): Promise<void> {
+		if (this.active || this.queue.length === 0) return;
+
+		const next = this.queue.shift();
+		if (!next) return;
+
+		const active = { ...next, questionIndex: 0, nonce: this.makeNonce() };
+		this.active = active;
+		try {
+			await this.sendActiveQuestion(active);
+		} catch (error) {
+			await this.rejectActiveAndPump(error, active);
+		}
+	}
+
+	private async sendActiveQuestion(active: ActiveAsk): Promise<void> {
+		const question = active.questions[active.questionIndex];
+		if (!question) return;
+
+		await this.transport.sendQuestion({
+			requestId: active.requestId,
+			nonce: active.nonce,
+			questionIndex: active.questionIndex,
+			totalQuestions: active.questions.length,
+			question,
+		});
+	}
+
+	private async advance(): Promise<void> {
+		const active = this.active;
+		if (!active) return;
+
+		if (active.questionIndex + 1 >= active.questions.length) {
+			active.removeAbortListener();
+			active.resolve(active.answers);
+			this.active = undefined;
+			await this.pump();
+			return;
+		}
+
+		active.questionIndex += 1;
+		active.nonce = this.makeNonce();
+		try {
+			await this.sendActiveQuestion(active);
+		} catch (error) {
+			await this.rejectActiveAndPump(error, active);
+		}
+	}
+
+	private removeQueued(requestId: string): boolean {
+		const index = this.queue.findIndex((item) => item.requestId === requestId);
+		if (index < 0) return false;
+		this.queue.splice(index, 1);
+		return true;
+	}
+
+	private cancelActive(reason: string): void {
+		if (!this.active) return;
+
+		const active = this.active;
+		active.removeAbortListener();
+		active.reject(new AfkAskCancelledError(reason));
+		this.active = undefined;
+		void this.transport.sendCancellation(reason).catch(() => {});
+		void this.pump();
+	}
+
+	private async rejectActiveAndPump(error: unknown, failedActive: ActiveAsk): Promise<void> {
+		const active = this.active;
+		if (!active || active.requestId !== failedActive.requestId) return;
+
+		active.removeAbortListener();
+		active.reject(error instanceof Error ? error : new Error(String(error)));
+		this.active = undefined;
+		await this.pump();
+	}
+}

package/extensions/config.ts

@@ -0,0 +1,172 @@
+import { randomUUID } from "node:crypto";
+import { chmod, lstat, mkdir, open, readdir, readFile, rename, rm } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { AfkConfig } from "./types.ts";
+
+export function getAfkHome(env: NodeJS.ProcessEnv = process.env): string {
+	const afkHome = env.PI_AFK_HOME?.trim();
+	if (afkHome) return afkHome;
+	const home = env.HOME?.trim() || homedir();
+	return join(home, ".pi", "agent", "afk");
+}
+
+export function configPath(home = getAfkHome()): string {
+	return join(home, "config.json");
+}
+
+export function isAfkConfig(value: unknown): value is AfkConfig {
+	if (!value || typeof value !== "object") return false;
+	const candidate = value as Record<string, unknown>;
+	return (
+		typeof candidate.botToken === "string" &&
+		candidate.botToken.trim().length > 0 &&
+		typeof candidate.botUsername === "string" &&
+		candidate.botUsername.trim().length > 0 &&
+		typeof candidate.chatId === "number" &&
+		Number.isSafeInteger(candidate.chatId) &&
+		candidate.chatId > 0 &&
+		typeof candidate.userId === "number" &&
+		Number.isSafeInteger(candidate.userId) &&
+		candidate.userId > 0
+	);
+}
+
+function cleanConfig(config: AfkConfig): AfkConfig {
+	return {
+		botToken: config.botToken.trim(),
+		botUsername: config.botUsername.trim(),
+		chatId: config.chatId,
+		userId: config.userId,
+	};
+}
+
+function hasErrorCode(error: unknown, code: string): boolean {
+	return Boolean(error && typeof error === "object" && "code" in error && error.code === code);
+}
+
+function isAfkOwnedEntry(entry: string): boolean {
+	return entry === "config.json" || entry === "locks" || /^\.config\.json\..+\.tmp$/.test(entry);
+}
+
+async function validateExistingAfkHome(home: string): Promise<boolean> {
+	let stats;
+	try {
+		stats = await lstat(home);
+	} catch (error) {
+		if (hasErrorCode(error, "ENOENT")) return false;
+		throw error;
+	}
+
+	if (stats.isSymbolicLink()) throw new Error(`Unsafe AFK home: ${home} is a symlink`);
+	if (!stats.isDirectory()) throw new Error(`Unsafe AFK home: ${home} is not a directory`);
+
+	const entries = await readdir(home);
+	const unrelatedEntry = entries.find((entry) => !isAfkOwnedEntry(entry));
+	if (unrelatedEntry) throw new Error(`Unsafe AFK home: contains unrelated entry ${unrelatedEntry}`);
+	return true;
+}
+
+async function prepareAfkHomeForWrite(home: string): Promise<void> {
+	const exists = await validateExistingAfkHome(home);
+	if (!exists) await mkdir(home, { recursive: true, mode: 0o700 });
+	await chmod(home, 0o700);
+}
+
+async function validateConfigFile(path: string): Promise<boolean> {
+	let stats;
+	try {
+		stats = await lstat(path);
+	} catch (error) {
+		if (hasErrorCode(error, "ENOENT")) return false;
+		throw error;
+	}
+
+	if (stats.isSymbolicLink()) throw new Error(`Unsafe AFK config file: ${path} is a symlink`);
+	if (!stats.isFile()) throw new Error(`Unsafe AFK config file: ${path} is not a regular file`);
+	return true;
+}
+
+export async function readConfig(home = getAfkHome()): Promise<AfkConfig | undefined> {
+	const exists = await validateExistingAfkHome(home);
+	if (!exists) return undefined;
+
+	await chmod(home, 0o700);
+
+	const targetPath = configPath(home);
+	const configExists = await validateConfigFile(targetPath);
+	if (!configExists) return undefined;
+
+	let raw;
+	try {
+		raw = await readFile(targetPath, "utf8");
+	} catch (error) {
+		if (hasErrorCode(error, "ENOENT")) return undefined;
+		throw error;
+	}
+
+	await validateConfigFile(targetPath);
+	await chmod(targetPath, 0o600);
+
+	try {
+		const parsed = JSON.parse(raw) as unknown;
+		if (!isAfkConfig(parsed)) return undefined;
+		return cleanConfig(parsed);
+	} catch (error) {
+		if (error instanceof SyntaxError) return undefined;
+		throw error;
+	}
+}
+
+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();
+	}
+}
+
+export async function writeConfig(config: AfkConfig, home = getAfkHome()): Promise<void> {
+	if (!isAfkConfig(config)) throw new Error("Invalid AFK config: refusing to write config.json");
+
+	await prepareAfkHomeForWrite(home);
+
+	const targetPath = configPath(home);
+	await validateConfigFile(targetPath);
+	const tempPath = join(home, `.config.json.${process.pid}.${randomUUID()}.tmp`);
+	let handle;
+
+	try {
+		handle = await open(tempPath, "wx", 0o600);
+		await handle.writeFile(`${JSON.stringify(cleanConfig(config), null, 2)}\n`, "utf8");
+		await handle.sync();
+		await handle.close();
+		handle = undefined;
+		await chmod(tempPath, 0o600);
+		await rename(tempPath, targetPath);
+		await validateConfigFile(targetPath);
+		await chmod(targetPath, 0o600);
+		await fsyncDirectory(home);
+	} catch (error) {
+		try {
+			await handle?.close();
+		} finally {
+			await rm(tempPath, { force: true });
+		}
+		throw error;
+	}
+}
+
+export function redactConfig(config: AfkConfig): Omit<AfkConfig, "botToken"> & { botToken: "<redacted>" } {
+	return { ...cleanConfig(config), botToken: "<redacted>" };
+}