pi-kanban 0.3.1 → 2.0.0

package/extensions/package.json

@@ -0,0 +1 @@
+{ "type": "module" }

package/extensions/tools/ask.ts

@@ -0,0 +1,85 @@
+import { Type } from "typebox";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { BoardDownError, boardFetch, boardTerminalId, okJson, pollSettled, POLL_MS, postJson, resolveTarget, sessionIdOf, terminalToken, toolText as text } from "./board-api.js";
+
+type Answer = { status: "answered"; data: unknown } | { status: "dismissed" | "cancelled" | "gone" | "pending"; reason?: string };
+export type AskOpen = { title: string; args: unknown };
+
+function answerText(title: string, a: Answer): string {
+	if (a.status === "answered") return `The user answered "${title}":\n${JSON.stringify(a.data, null, 2)}`;
+	if (a.status === "dismissed" && a.reason === "replaced") return `"${title}" was replaced by a newer question.`;
+	if (a.status === "dismissed") return `The user skipped "${title}" without answering. Go on with your best default, and ask in chat only when no default works.`;
+	return `"${title}" is no longer open on the board; the user did not answer it.`;
+}
+
+const ASK_PARAMS = Type.Object({
+	title: Type.String({ description: "The question, short: it titles the modal and the chip that reopens it" }),
+	file: Type.String({ description: "Path of the HTML card: absolute, or relative to the session cwd" }),
+	size: Type.Optional(
+		Type.Union([Type.Literal("md"), Type.Literal("lg"), Type.Literal("full")], {
+			description: "Modal size: md for a short form, lg (default) for most cards, full for a playground or a quiz sheet",
+		}),
+	),
+});
+
+const INTERRUPTED = "Interrupted; the question was closed.";
+
+export const ASK_TOOL = "ask";
+
+// A board ask fires no UI prompt event, so the live state learns of it from these.
+export const ASK_OPEN = "kanban:ask-open";
+export const ASK_CLOSE = "kanban:ask-close";
+
+// The call waits until the user answers or skips. An abort closes the modal, because the run went on without it.
+async function askOnBoard(pi: ExtensionAPI, base: string, headers: Record<string, string>, body: object, open: AskOpen, signal?: AbortSignal): Promise<string> {
+	const { id } = await okJson(postJson(base, body, { headers, signal }));
+	const at = `${base}/${encodeURIComponent(id)}`;
+	pi.events.emit(ASK_OPEN, open);
+	try {
+		return answerText(open.title, await pollSettled<Answer>(`${at}/wait?ms=${POLL_MS}`, { headers, signal }));
+	} catch (e) {
+		if (!signal?.aborted) throw e;
+		await boardFetch(at, { method: "DELETE", headers }).catch(() => {});
+		throw new Error(INTERRUPTED);
+	} finally {
+		pi.events.emit(ASK_CLOSE, open);
+	}
+}
+
+// Without a board the TUI asks in a line of text: the card cannot render there.
+async function askInTui(ctx: ExtensionContext, title: string, file: string, signal?: AbortSignal): Promise<string> {
+	ctx.ui.notify(`The pi-kanban board is not running, so the card ${file} cannot open. Answer in text.`, "warning");
+	const answer = await ctx.ui.input(title, "Type the answer, or press Esc to skip", { signal });
+	if (signal?.aborted) throw new Error(INTERRUPTED);
+	return answer === undefined ? answerText(title, { status: "dismissed" }) : answerText(title, { status: "answered", data: answer });
+}
+
+export function registerAsk(pi: ExtensionAPI) {
+	const terminal = boardTerminalId();
+
+	pi.registerTool({
+		name: ASK_TOOL,
+		label: "Ask",
+		description:
+			"Ask the user through an HTML card in a modal on the pi-kanban board, and wait. The result is the data the card sent, as JSON, or a line that says the user skipped. Write the card to an HTML file in your scratchpad and pass it as file. The card sends the answer with pk.send(data), a <form data-pk-submit> or a <button data-pk-action>.",
+		promptSnippet:
+			"Ask the user on an HTML card on the pi-kanban board and wait for the answer, when it needs something to see or control: swatches, a diagram, sliders, a long form, a quiz sheet, a playground",
+		promptGuidelines: ["Before you write an ask card, read the ask skill: it has the card's HTML contract and theme variables."],
+		parameters: ASK_PARAMS,
+		annotations: { destructiveHint: false, openWorldHint: false },
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			const sessionId = sessionIdOf(ctx);
+			const file = resolveTarget(ctx.cwd, params.file);
+			const body = { sessionId, title: params.title, file, size: params.size };
+			try {
+				const [base, headers] = terminal
+					? [`/api/terminals/${encodeURIComponent(terminal)}/ask`, { "x-terminal-token": terminalToken() }]
+					: [`/api/sessions/${encodeURIComponent(sessionId)}/ask`, {}];
+				return text(await askOnBoard(pi, base, headers, body, { title: params.title, args: params }, signal));
+			} catch (e) {
+				if (e instanceof BoardDownError && ctx.hasUI) return text(await askInTui(ctx, params.title, file, signal));
+				throw e;
+			}
+		},
+	});
+}

package/extensions/tools/board-api.ts

@@ -0,0 +1,142 @@
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import { isAbsolute, join as joinPath, resolve as resolvePath } from "node:path";
+import { getAgentDir, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+const DEFAULT_PORT = 3460;
+
+const requireHere = createRequire(import.meta.url);
+// The board's CommonJS modules, shared with the extension.
+export const lib = (name: string) => requireHere(`../../lib/${name}`);
+
+const { linkUrl } = requireHere("../../public/link-url.js") as { linkUrl: (v: unknown) => string | null };
+export const isUrl = (target: string) => linkUrl(target) !== null;
+
+// The board resolves a path against its own cwd, so a relative path is made absolute here.
+// A file:// URL is left to the board, which converts it.
+export function resolveTarget(cwd: string, input: string): string {
+	const target = input.trim();
+	if (!target) throw new Error("A path or URL is required.");
+	if (isUrl(target) || /^file:/i.test(target)) return target;
+	const expanded = target === "~" || /^~[\\/]/.test(target) ? joinPath(homedir(), target.slice(1)) : target;
+	// Git Bash hands out `/c/x` for `C:\x`, as cliPath in cli.js also handles.
+	const native = process.platform === "win32" ? expanded.replace(/^\/([a-zA-Z])(?=\/|$)/, "$1:/") : expanded;
+	return isAbsolute(native) ? resolvePath(native) : resolvePath(cwd, native);
+}
+
+const BOARD_DOWN ='The pi-kanban board is not running. Ask the user to start it with "pi-kanban".';
+
+export function kanbanDir(): string {
+	return joinPath(getAgentDir(), "kanban");
+}
+
+// EPERM means the process exists but belongs to someone else.
+function isPidAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (e: any) {
+		return e?.code === "EPERM";
+	}
+}
+
+export function readText(file: string): string | null {
+	try {
+		return readFileSync(file, "utf8");
+	} catch {
+		return null;
+	}
+}
+
+function readJson(file: string): any {
+	try {
+		return JSON.parse(readText(file) ?? "null");
+	} catch {
+		return null;
+	}
+}
+
+// The same rule as cli.js: PK_URL, then this agent dir's server.json beacon, then the default port.
+// Read on every call, so a board that restarted on another port is found. Null means the beacon
+// names a server that is gone, so the default port could be another agent dir's board.
+export function boardUrl(): string | null {
+	if (process.env.PK_URL) return process.env.PK_URL.replace(/\/+$/, "");
+	const beacon = readJson(joinPath(kanbanDir(), "server.json"));
+	if (!beacon) return `http://127.0.0.1:${DEFAULT_PORT}`;
+	return beacon.port && beacon.pid && isPidAlive(beacon.pid) ? `http://127.0.0.1:${beacon.port}` : null;
+}
+
+export class BoardDownError extends Error {
+	constructor(cause?: unknown) {
+		super(BOARD_DOWN, { cause });
+		this.name = "BoardDownError";
+	}
+}
+
+// Rejects with BoardDownError when no board answers, so a caller can tell "board down" from an HTTP error.
+export async function boardFetch(path: string, init?: RequestInit): Promise<Response> {
+	const url = boardUrl();
+	if (!url) throw new BoardDownError();
+	try {
+		return await fetch(`${url}${path}`, init);
+	} catch (e: any) {
+		if (e?.name === "AbortError") throw e;
+		throw new BoardDownError(e);
+	}
+}
+
+// Read on every call: a restarted board writes a new token.
+export function terminalToken(): string {
+	const url = boardUrl();
+	if (!url) throw new BoardDownError();
+	const port = new URL(url).port;
+	const token = readJson(joinPath(kanbanDir(), "terminal-tokens", `${port}.json`))?.token;
+	if (typeof token === "string" && token) return token;
+	throw new Error(`No terminal token for the pi-kanban board on port ${port}. It must run with the terminal enabled.`);
+}
+
+export const { boardTerminalId } = lib("board-dir.js") as { boardTerminalId: () => string | null };
+
+// Under the board's 25 s cap on a long-poll, so each poll answers before the board gives up on it.
+export const POLL_MS = 20_000;
+
+export async function pollSettled<T extends { status: string }>(path: string, init: RequestInit = {}): Promise<T> {
+	for (;;) {
+		const got: T = await okJson(boardFetch(path, { cache: "no-store", ...init }));
+		if (got.status !== "pending") return got;
+	}
+}
+
+export function postJson(path: string, body: unknown, init: RequestInit = {}): Promise<Response> {
+	return boardFetch(path, {
+		...init,
+		method: init.method ?? "POST",
+		headers: { "Content-Type": "application/json", ...(init.headers as Record<string, string> | undefined) },
+		body: JSON.stringify(body),
+	});
+}
+
+// The board answers errors as { error }.
+export async function errorText(res: Response): Promise<string> {
+	const text = await res.text().catch(() => "");
+	try {
+		const { error } = JSON.parse(text);
+		if (typeof error === "string" && error) return error;
+	} catch {}
+	return `pi-kanban answered HTTP ${res.status}`;
+}
+
+export async function okJson(pending: Promise<Response>): Promise<any> {
+	const res = await pending;
+	if (!res.ok) throw new Error(await errorText(res));
+	return res.status === 204 ? null : res.json();
+}
+
+export function sessionIdOf(ctx: ExtensionContext): string {
+	const id = ctx.sessionManager.getSessionId();
+	if (!id) throw new Error("This pi session has no id yet.");
+	return id;
+}
+
+export const toolText = (t: string) => ({ content: [{ type: "text" as const, text: t }], details: undefined });

package/extensions/tools/cli-path.ts

@@ -0,0 +1,34 @@
+import { chmodSync, mkdirSync, writeFileSync } from "node:fs";
+import { delimiter, join as joinPath } from "node:path";
+import { fileURLToPath } from "node:url";
+import { kanbanDir, readText } from "./board-api.js";
+
+const SERVER_ENV = "PI_KANBAN_SERVER";
+
+// The shims read the server from the env, so every pi process runs the server.js of the package
+// that loaded it, whatever copy last wrote the shared shims.
+const SHIMS: Record<string, string> = {
+	"pi-kanban": `#!/bin/sh\nexec node "$${SERVER_ENV}" "$@"\n`,
+	"pi-kanban.cmd": `@node "%${SERVER_ENV}%" %*\r\n`,
+};
+
+// The skills run `pi-kanban`. The shims go first on PATH, so the CLI is the version of the skills
+// pi loaded, also when another version or none is installed globally. They are written here, not
+// shipped, because an npm pack made on Windows drops the executable bit.
+export function addCliToPath(dir = joinPath(kanbanDir(), "bin")): void {
+	process.env[SERVER_ENV] = fileURLToPath(new URL("../../server.js", import.meta.url));
+	try {
+		mkdirSync(dir, { recursive: true });
+		for (const [name, text] of Object.entries(SHIMS)) {
+			const file = joinPath(dir, name);
+			if (readText(file) === text) continue;
+			writeFileSync(file, text);
+			chmodSync(file, 0o755);
+		}
+	} catch (e: any) {
+		console.warn(`pi-kanban: CLI shims failed: ${e?.message ?? e}`);
+		return;
+	}
+	const parts = (process.env.PATH ?? "").split(delimiter).filter((p) => p && p !== dir);
+	process.env.PATH = [dir, ...parts].join(delimiter);
+}

package/extensions/tools/dispatch.ts

@@ -0,0 +1,56 @@
+import { Type } from "typebox";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { boardFetch, boardTerminalId, okJson, postJson, sessionIdOf, toolText as text } from "./board-api.js";
+
+export const REPORT_TOOL = "dispatch_report";
+
+const PROBE_TIMEOUT_MS = 5_000;
+
+const WORKER_PROMPT = [
+	"pi-kanban started this session for another pi session, which waits for your result.",
+	`When the task is done, or you cannot finish it, call ${REPORT_TOOL} once with a short report: what you did, the outcome, and the paths of files with details.`,
+	"Keep the report under 2000 characters; it is all the other session gets.",
+].join("\n");
+
+async function isDispatched(sessionId: string): Promise<boolean> {
+	try {
+		const res = await boardFetch(`/api/dispatch/${encodeURIComponent(sessionId)}/report`, { signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) });
+		return res.ok;
+	} catch (e: any) {
+		console.warn(`pi-kanban: could not ask the board whether this session is a dispatch: ${e?.message ?? e}`);
+		return false;
+	}
+}
+
+export function registerDispatch(pi: ExtensionAPI) {
+	let worker = false;
+
+	// Only a session in the board's terminal can be a dispatch, and the board knows which ones are.
+	// It asks on every start, so a dispatch the board resumed after a restart still reports.
+	pi.on("session_start", async (_event, ctx) => {
+		const sessionId = ctx.sessionManager.getSessionId();
+		if (!sessionId) return;
+		worker = !!boardTerminalId() && (await isDispatched(sessionId));
+		const active = pi.getActiveTools();
+		if (active.includes(REPORT_TOOL) === worker) return;
+		pi.setActiveTools(worker ? [...active, REPORT_TOOL] : active.filter((t) => t !== REPORT_TOOL));
+	});
+
+	pi.on("before_agent_start", async (event) => {
+		if (worker) event.systemPromptOptions.sections.dispatch = WORKER_PROMPT;
+		else delete event.systemPromptOptions.sections.dispatch;
+	});
+
+	pi.registerTool({
+		name: REPORT_TOOL,
+		label: "Dispatch report",
+		description: "Send your report to the pi session that dispatched you. Call it once, when the task is done or you cannot finish it.",
+		parameters: Type.Object({ text: Type.String({ description: "The report: what you did, the outcome, paths of files with details" }) }),
+		annotations: { destructiveHint: false, openWorldHint: false },
+		defaultActive: false,
+		async execute(_toolCallId, p, signal, _onUpdate, ctx) {
+			await okJson(postJson(`/api/dispatch/${encodeURIComponent(sessionIdOf(ctx))}/report`, { text: p.text }, { signal }));
+			return text("Report sent. Tell the user it was sent, then stop.");
+		},
+	});
+}

package/extensions/tools/inbox.ts

@@ -0,0 +1,86 @@
+import { readFile } from "node:fs/promises";
+import { join as joinPath } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { boardFetch, errorText, kanbanDir, lib } from "./board-api.js";
+
+const { isContained } = lib("contain.js") as { isContained: (child: string, root: string) => boolean };
+
+type Events = { events: string[]; seqs: number[]; board: string };
+
+// The board caps a wait at 120 s.
+const WAIT_SEC = 110;
+const RETRY_MS = [2_000, 5_000, 15_000, 30_000];
+
+// pi names a session file <ISO timestamp>_<id>.jsonl.
+function sessionIdOf(file: string | undefined): string | undefined {
+	return file ? /_([^_\\/]+)\.jsonl$/.exec(file)?.[1] : undefined;
+}
+
+// A review or answer line ends with the path of the file that holds the batch (lib/session-events.js).
+const FILE_RE = /: (.+\.md)$/;
+
+async function withBatch(line: string): Promise<string> {
+	const file = FILE_RE.exec(line)?.[1];
+	if (!file) return line;
+	if (!isContained(file, joinPath(kanbanDir(), "reviews"))) return line;
+	const batch = await readFile(file, "utf8").catch(() => "");
+	return batch ? `${line}\n\n${batch}` : line;
+}
+
+// Drains the board's queue for this session (reviews, preview answers, task moves) into the
+// conversation. A line stays on the board until its ack, which rides on the next poll.
+// `prev` on the first poll makes the board deliver to this session what it still sends to the
+// old id (lib/session-events.js).
+async function drain(pi: ExtensionAPI, ctx: ExtensionContext, sessionId: string, prev: string | undefined, signal: AbortSignal) {
+	let board = "";
+	let seq = 0;
+	let first = true;
+	let fails = 0;
+	while (!signal.aborted) {
+		try {
+			const q = new URLSearchParams({ wait: String(WAIT_SEC), got: String(seq), ack: String(seq), board });
+			if (first) {
+				q.set("first", "1");
+				if (prev) q.set("prev", prev);
+			}
+			const res = await boardFetch(`/api/sessions/${encodeURIComponent(sessionId)}/events?${q}`, { cache: "no-store", signal });
+			if (!res.ok) throw new Error(await errorText(res));
+			const got = (await res.json()) as Events;
+			first = false;
+			fails = 0;
+			if (got.board !== board) seq = 0;
+			board = got.board;
+			const texts = await Promise.all(got.events.map(withBatch));
+			if (signal.aborted) return;
+			for (const text of texts) pi.sendUserMessage(text, ctx.isIdle() ? undefined : { deliverAs: "followUp" });
+			if (got.seqs.length) seq = Math.max(seq, ...got.seqs);
+		} catch (e: any) {
+			if (signal.aborted) return;
+			if (fails === 0 && e?.name !== "BoardDownError") console.warn(`pi-kanban: board inbox: ${e?.message ?? e}`);
+			await sleep(RETRY_MS[Math.min(fails++, RETRY_MS.length - 1)], undefined, { signal }).catch(() => {});
+		}
+	}
+}
+
+export function registerInbox(pi: ExtensionAPI) {
+	if (process.env.PI_SUBAGENT_CHILD) return;
+	let stop: AbortController | null = null;
+
+	pi.on("session_start", async (event, ctx) => {
+		stop?.abort();
+		stop = null;
+		const sessionId = ctx.sessionManager.getSessionId();
+		if (!sessionId || !ctx.hasUI) return;
+		// pi loads the extension again for each session, so only the event knows the one before.
+		// A resumed session is not its successor.
+		const prev = event.reason === "new" || event.reason === "fork" ? sessionIdOf(event.previousSessionFile) : undefined;
+		stop = new AbortController();
+		void drain(pi, ctx, sessionId, prev, stop.signal);
+	});
+
+	pi.on("session_shutdown", async () => {
+		stop?.abort();
+		stop = null;
+	});
+}

package/extensions/tools/kanban-command.ts

@@ -0,0 +1,27 @@
+import { isUrl, okJson, postJson, terminalToken } from "./board-api.js";
+
+const postBoardJson = (path: string, body: unknown, headers?: Record<string, string>) => okJson(postJson(path, body, { headers }));
+
+export async function linkDoc(sessionId: string, target: string, opts: { unlink?: boolean; open?: boolean } = {}): Promise<string> {
+	const out = await postBoardJson("/api/document/link", { path: target, sessionId, unlink: !!opts.unlink, open: !!opts.open });
+	const what = isUrl(target) ? "URL" : "Document";
+	const line = `${what} ${opts.unlink ? "unlinked from" : "linked to"} the session: ${out.path}`;
+	return !opts.unlink && out.tabs === 0 ? `${line}\nNo board tab is open; the board shows it when one opens.` : line;
+}
+
+// A URL cannot open in the preview modal, so it is linked and the board tab on screen offers an Open button.
+// A sessionId also moves the board to that session.
+export async function previewDoc(target: string, sessionId: string | null): Promise<string> {
+	if (isUrl(target)) {
+		if (!sessionId) throw new Error("A URL is linked to a session, and this pi session has no id yet.");
+		return linkDoc(sessionId, target, { open: true });
+	}
+	await postBoardJson("/api/preview", { path: target, sessionId });
+	return `Preview opened on the board: ${target}`;
+}
+
+// The board starts the tool, which runs package code, so a companion pane takes the terminal token.
+// With a board terminal id, the board tab that shows that terminal switches to the pane.
+export async function openCompanion(sessionId: string, companion: string, terminal?: string) {
+	return postBoardJson(`/api/panes/${encodeURIComponent(sessionId)}`, { companion, terminal }, { "x-terminal-token": terminalToken() });
+}

package/extensions/tools/scratchpad.ts

@@ -0,0 +1,70 @@
+import { mkdirSync } from "node:fs";
+import { join as joinPath } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { kanbanDir, lib } from "./board-api.js";
+
+const pads = lib("scratchpad-dir.js") as {
+	defaultScratchpadRoot: () => string;
+	scratchpadPath: (root: string, cwd: string, sessionId: string) => string;
+	recordedPadDir: (entries: unknown[]) => string | null;
+	prunePads: (o: { root: string; isLive: (sessionId: string) => boolean }) => Promise<string[]>;
+	SCRATCHPAD_ENTRY: string;
+	PAD_MAX_AGE_MS: number;
+};
+const liveSessions = lib("live-sessions.js") as {
+	readLiveSessions: (dir: string) => { sessionId: string; pid: number | null }[];
+	isSessionLive: (sessions: unknown[], sessionId: string) => boolean;
+};
+
+export const SCRATCHPAD_ENV = "PI_SCRATCHPAD_DIR";
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+function promptSection(dir: string): string {
+	return [
+		`Use this session's scratchpad dir for temporary files, such as notes, scripts, logs and command output, in place of /tmp or the project: ${dir}`,
+		`It is also in $${SCRATCHPAD_ENV}, and the pi-kanban board lists its files.`,
+		`It is deleted ${Math.round(pads.PAD_MAX_AGE_MS / DAY_MS)} days after the session ends, so put files the user keeps in the project or where the user says.`,
+	].join("\n");
+}
+
+async function prune(root: string, sessionId: string): Promise<void> {
+	const live = liveSessions.readLiveSessions(joinPath(kanbanDir(), "live"));
+	await pads.prunePads({ root, isLive: (id) => id === sessionId || liveSessions.isSessionLive(live, id) });
+}
+
+// A subagent child reuses the pad its parent put in the environment, so both write to one dir.
+export function registerScratchpad(pi: ExtensionAPI) {
+	const inherited = process.env.PI_SUBAGENT_CHILD ? process.env[SCRATCHPAD_ENV] : undefined;
+	const root = pads.defaultScratchpadRoot();
+	let dir: string | null = inherited ?? null;
+	let pruned = false;
+
+	pi.on("session_start", async (_event, ctx) => {
+		const sessionId = ctx.sessionManager.getSessionId();
+		if (!sessionId) return;
+		if (!inherited) {
+			const next = pads.scratchpadPath(root, ctx.sessionManager.getCwd(), sessionId);
+			try {
+				mkdirSync(next, { recursive: true });
+			} catch (e: any) {
+				console.warn(`pi-kanban: cannot create scratchpad ${next}: ${e?.message ?? e}`);
+				dir = null;
+				delete process.env[SCRATCHPAD_ENV];
+				return;
+			}
+			dir = next;
+			process.env[SCRATCHPAD_ENV] = dir;
+		}
+		if (pads.recordedPadDir(ctx.sessionManager.getEntries()) !== dir) pi.appendEntry(pads.SCRATCHPAD_ENTRY, { dir });
+
+		if (inherited || pruned) return;
+		pruned = true;
+		setImmediate(() => prune(root, sessionId).catch((e: any) => console.warn(`pi-kanban: scratchpad prune failed: ${e?.message ?? e}`)));
+	});
+
+	pi.on("before_agent_start", async (event) => {
+		if (dir) event.systemPromptOptions.sections.scratchpad = promptSection(dir);
+		else delete event.systemPromptOptions.sections.scratchpad;
+	});
+}

package/extensions/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2024",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "noEmit": true,
+    "resolveJsonModule": true,
+    "lib": ["es2024"],
+    "types": ["node"]
+  },
+  "include": ["./**/*.ts"]
+}

package/lib/agent-dir.js

@@ -0,0 +1,20 @@
+const os = require('node:os');
+const path = require('node:path');
+const { realpathDeepest } = require('./contain');
+
+// libuv aborts the process when a watched Windows path holds an 8.3 short name (NIKIFO~1),
+// because the events come back with the long name, so every dir the board watches gets its long form.
+const longPath = (dir) => realpathDeepest(path.resolve(dir));
+
+// Mirrors getAgentDir() in @earendil-works/pi-coding-agent. PI_DIR is pi-kanban's own
+// override (demo, tests) and points at the parent of the agent dir.
+function rawAgentDir() {
+  if (process.env.PI_DIR) return path.join(process.env.PI_DIR, 'agent');
+  const envDir = process.env.PI_CODING_AGENT_DIR;
+  if (envDir) return envDir.replace(/^~(?=$|[\\/])/, os.homedir());
+  return path.join(os.homedir(), '.pi', 'agent');
+}
+
+const getAgentDir = () => longPath(rawAgentDir());
+
+module.exports = { getAgentDir, longPath };

package/lib/agent-log.js

@@ -0,0 +1,64 @@
+'use strict';
+
+const fs = require('node:fs').promises;
+const path = require('node:path');
+const { writeJsonAtomic } = require('./atomic-write');
+
+// A message to a stopped subagent spawns it again under the same id, and the plugin appends
+// another start line. Each start line begins a new run, so nothing of the run before it shows.
+function foldAgentLines(raw) {
+  let merged = {};
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    let obj;
+    try { obj = JSON.parse(line); } catch (_) { continue; }
+    if (obj.event === 'start') merged = {};
+    Object.assign(merged, obj);
+  }
+  return merged;
+}
+
+// An agent id is a file name in the activity dir; the server strips request ids to the same alphabet.
+function sanitizeAgentId(raw) {
+  return path.basename(String(raw)).replace(/[^a-zA-Z0-9_-]/g, '');
+}
+
+// The pi extension writes a session's activity dir: <agentId>.jsonl lines, _waiting.json and
+// _stop.json. The server folds a line last-key-wins, so a line leaves out a field it does not know.
+async function appendAgentLines(dir, records) {
+  if (!records.length) return;
+  const byAgent = new Map();
+  for (const r of records) byAgent.set(r.agentId, (byAgent.get(r.agentId) || '') + `${JSON.stringify(r)}\n`);
+  await fs.mkdir(dir, { recursive: true });
+  await Promise.all([...byAgent].map(([agentId, text]) => fs.appendFile(path.join(dir, `${agentId}.jsonl`), text, 'utf8')));
+}
+
+// pi does not say which tool asked, so the marker names the newest tool still running.
+function promptMarker(prompt, tool, now) {
+  return {
+    kind: prompt.kind === 'confirm' ? 'permission' : 'question',
+    toolName: tool?.toolName ?? prompt.title ?? prompt.kind,
+    toolInput: JSON.stringify(tool?.args ?? { title: prompt.title ?? null }),
+    timestamp: now,
+  };
+}
+
+async function writeWaiting(dir, marker) {
+  await writeJsonAtomic(path.join(dir, '_waiting.json'), { status: 'waiting', ...marker });
+}
+
+async function clearWaiting(dir) {
+  await fs.rm(path.join(dir, '_waiting.json'), { force: true });
+}
+
+// Only the marker's mtime is read: the session is unread until opened or written again.
+async function markStopped(dir) {
+  await fs.mkdir(dir, { recursive: true });
+  await fs.writeFile(path.join(dir, '_stop.json'), '');
+}
+
+async function clearStopped(dir) {
+  await fs.rm(path.join(dir, '_stop.json'), { force: true });
+}
+
+module.exports = { foldAgentLines, sanitizeAgentId, appendAgentLines, promptMarker, writeWaiting, clearWaiting, markStopped, clearStopped };