@bumpyclock/pi-tasque 0.1.0

package/src/session-todos/todo.ts

@@ -0,0 +1,239 @@
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import {
+	selectTasksByStatus,
+	selectTodoCounts,
+	selectVisibleTasks,
+} from "./state/selectors.js";
+import { applyTaskMutation } from "./state/state-reducer.js";
+import { commitState, getState, replaceState } from "./state/store.js";
+import { replayFromBranch } from "./state/replay.js";
+import { buildToolResult } from "./tool/response-envelope.js";
+import {
+	COMMAND_NAME,
+	ERR_REQUIRES_INTERACTIVE,
+	MSG_NO_TODOS,
+	TOOL_LABEL,
+	TOOL_NAME,
+	TodoParamsSchema,
+	type TaskAction,
+	type TaskMutationParams,
+} from "./tool/types.js";
+import { TodoOverlay } from "./todo-overlay.js";
+import {
+	formatCommandTaskLine,
+	formatStatusLabel,
+	renderTodoCall,
+	renderTodoResult,
+} from "./view/format.js";
+
+const SECTION_PENDING = "── Pending ──";
+const SECTION_IN_PROGRESS = "── In Progress ──";
+const SECTION_COMPLETED = "── Completed ──";
+const TODO_AFFECTING_TOOLS = new Set(["todo", "task_bridge", "tsq_claim"]);
+
+export const TODO_PROMPT_SNIPPET =
+	"Manage current-session tactical todos for multi-step execution.";
+
+export const TODO_PROMPT_GUIDELINES: string[] = [
+	"Use `todo` for current-session tactical work: inspect, edit, verify, and handoff steps for the task in front of you.",
+	"Use `todo` for session work, not durable backlog; use Tasque/tsq tools for durable ownership, specs, and cross-session work.",
+	"Mark one task in_progress before starting it, complete it when verified, and keep blocked or partial work out of completed.",
+	"Use blockedBy for session-local dependencies; list hides deleted tombstones unless includeDeleted is true.",
+];
+
+export { isTransitionValid } from "./state/invariants.js";
+export { applyTaskMutation } from "./state/state-reducer.js";
+export {
+	__resetState,
+	commitState,
+	getNextId,
+	getState,
+	getTodos,
+} from "./state/store.js";
+export { deriveBlocks, detectCycle } from "./state/task-graph.js";
+export type {
+	Task,
+	TaskAction,
+	TaskDetails,
+	TaskMutationParams,
+	TaskStatus,
+} from "./tool/types.js";
+export { COMMAND_NAME, TOOL_NAME } from "./tool/types.js";
+
+/** Rebuild live todo state from the current branch replay snapshot. */
+export function reconstructTodoState(
+	ctx: Parameters<typeof replayFromBranch>[0],
+): void {
+	replaceState(replayFromBranch(ctx));
+}
+
+export function registerTodoTool(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: TOOL_NAME,
+		label: TOOL_LABEL,
+		description:
+			"Manage current-session todos for tactical execution. Actions: create, update, list, get, delete, clear. Use for this session's working checklist, not durable backlog.",
+		promptSnippet: TODO_PROMPT_SNIPPET,
+		promptGuidelines: TODO_PROMPT_GUIDELINES,
+		parameters: TodoParamsSchema,
+
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			const { action, ...mutationParams } = params as TaskMutationParams & {
+				action: TaskAction;
+			};
+			const result = applyTaskMutation(getState(), action, mutationParams);
+			commitState(result.state);
+			return buildToolResult(action, mutationParams, result.state, result.op);
+		},
+
+		renderCall(args, theme, _context) {
+			return renderTodoCall(
+				args as TaskMutationParams & { action: TaskAction },
+				theme,
+				getState(),
+			);
+		},
+
+		renderResult(result, _opts, theme, _context) {
+			return renderTodoResult(result, theme);
+		},
+	});
+}
+
+export function registerTodosCommand(pi: ExtensionAPI): void {
+	pi.registerCommand(COMMAND_NAME, {
+		description: "Show current-session todos grouped by status",
+		handler: async (_args, ctx) => {
+			if (!ctx.hasUI) {
+				ctx.ui.notify(ERR_REQUIRES_INTERACTIVE, "error");
+				return;
+			}
+
+			const state = getState();
+			const visible = selectVisibleTasks(state);
+			if (visible.length === 0) {
+				ctx.ui.notify(MSG_NO_TODOS, "info");
+				return;
+			}
+
+			const groups = selectTasksByStatus(state);
+			const counts = selectTodoCounts(state);
+			const header: string[] = [];
+			if (counts.completed > 0) {
+				header.push(
+					`${counts.completed}/${counts.total} ${formatStatusLabel("completed")}`,
+				);
+			}
+			if (counts.inProgress > 0) {
+				header.push(`${counts.inProgress} ${formatStatusLabel("in_progress")}`);
+			}
+			if (counts.pending > 0) {
+				header.push(`${counts.pending} ${formatStatusLabel("pending")}`);
+			}
+
+			const lines = [header.join(" · ")];
+			if (groups.pending.length > 0) {
+				lines.push(SECTION_PENDING);
+				for (const task of groups.pending) {
+					lines.push(formatCommandTaskLine(task, "○"));
+				}
+			}
+			if (groups.inProgress.length > 0) {
+				lines.push(SECTION_IN_PROGRESS);
+				for (const task of groups.inProgress) {
+					lines.push(formatCommandTaskLine(task, "◐"));
+				}
+			}
+			if (groups.completed.length > 0) {
+				lines.push(SECTION_COMPLETED);
+				for (const task of groups.completed) {
+					lines.push(formatCommandTaskLine(task, "✓"));
+				}
+			}
+
+			ctx.ui.notify(lines.join("\n"), "info");
+		},
+	});
+}
+
+export function registerSessionTodoModule(pi: ExtensionAPI): void {
+	registerTodoTool(pi);
+	registerTodosCommand(pi);
+	registerTodoLifecycle(pi);
+}
+
+function registerTodoLifecycle(pi: ExtensionAPI): void {
+	const overlay = new TodoOverlay();
+
+	function bindUiAndUpdate(ctx: ExtensionContext): void {
+		if (!hasOverlayUi(ctx)) {
+			overlay.dispose();
+			return;
+		}
+		overlay.setUICtx(ctx.ui);
+		overlay.update();
+	}
+
+	function replayAndUpdate(
+		ctx: ExtensionContext,
+		options: { readonly resetCompletedDisplayState: boolean },
+	): void {
+		reconstructTodoState(ctx);
+		if (options.resetCompletedDisplayState) {
+			overlay.resetCompletedDisplayState();
+		}
+		bindUiAndUpdate(ctx);
+	}
+
+	pi.on("session_start", (_event, ctx) => {
+		replayAndUpdate(ctx, { resetCompletedDisplayState: true });
+	});
+
+	pi.on("session_compact", (_event, ctx) => {
+		replayAndUpdate(ctx, { resetCompletedDisplayState: false });
+	});
+
+	pi.on("session_tree", (_event, ctx) => {
+		replayAndUpdate(ctx, { resetCompletedDisplayState: true });
+	});
+
+	pi.on("tool_execution_end", (event, ctx) => {
+		if (!TODO_AFFECTING_TOOLS.has(event.toolName)) return;
+		if (!isSuccessfulToolExecutionResult(event)) return;
+		bindUiAndUpdate(ctx);
+	});
+
+	pi.on("turn_start", (_event, ctx) => {
+		if (!hasOverlayUi(ctx)) return;
+		overlay.setUICtx(ctx.ui);
+		overlay.hideCompletedTasksFromPreviousTurn();
+	});
+
+	pi.on("session_shutdown", () => {
+		overlay.dispose();
+	});
+}
+
+function hasOverlayUi(ctx: ExtensionContext): boolean {
+	return ctx.hasUI === true && ctx.ui !== undefined;
+}
+
+function isSuccessfulToolExecutionResult(event: {
+	readonly isError: boolean;
+	readonly result: unknown;
+}): boolean {
+	if (event.isError) return false;
+	const result = event.result;
+	if (!isRecord(result)) return true;
+	const details = result.details;
+	if (!isRecord(details)) return true;
+	if (details.ok === false) return false;
+	return details.error === undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/session-todos/tool/response-envelope.ts

@@ -0,0 +1,143 @@
+import { cloneTaskState, type TaskState } from "../state/state.js";
+import type { Op } from "../state/state-reducer.js";
+import { deriveBlocks } from "../state/task-graph.js";
+import type {
+	Task,
+	TaskAction,
+	TaskDetails,
+	TaskMutationParams,
+} from "./types.js";
+
+export interface TodoToolResult {
+	content: Array<{ type: "text"; text: string }>;
+	details: TaskDetails;
+}
+
+function formatListLine(task: Task): string {
+	const activeForm =
+		task.status === "in_progress" && task.activeForm
+			? ` (${task.activeForm})`
+			: "";
+	const blockedBy = task.blockedBy?.length
+		? ` ⛓ ${task.blockedBy.map((id) => `#${id}`).join(",")}`
+		: "";
+	return `[${task.status}] #${task.id} ${task.subject}${activeForm}${blockedBy}`;
+}
+
+function formatGetLines(task: Task, state: TaskState): string {
+	const blocks = deriveBlocks(state.tasks).get(task.id) ?? [];
+	const lines = [`#${task.id} [${task.status}] ${task.subject}`];
+	if (task.description) lines.push(`  description: ${task.description}`);
+	if (task.activeForm) lines.push(`  activeForm: ${task.activeForm}`);
+	if (task.blockedBy?.length) {
+		lines.push(
+			`  blockedBy: ${task.blockedBy.map((id) => `#${id}`).join(", ")}`,
+		);
+	}
+	if (blocks.length) {
+		lines.push(`  blocks: ${blocks.map((id) => `#${id}`).join(", ")}`);
+	}
+	if (task.owner) lines.push(`  owner: ${task.owner}`);
+	return lines.join("\n");
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+}
+
+function cloneDetailValue(value: unknown): unknown {
+	if (value === null || typeof value !== "object") return value;
+
+	if (typeof globalThis.structuredClone === "function") {
+		try {
+			return globalThis.structuredClone(value);
+		} catch {
+			// Fall back for values structuredClone cannot copy, like functions.
+		}
+	}
+
+	if (Array.isArray(value)) return value.map(cloneDetailValue);
+
+	if (isPlainObject(value)) {
+		const cloned: Record<string, unknown> = {};
+		for (const [key, nestedValue] of Object.entries(value)) {
+			cloned[key] = cloneDetailValue(nestedValue);
+		}
+		return cloned;
+	}
+
+	return value;
+}
+
+function cloneParams(params: TaskMutationParams): Record<string, unknown> {
+	const cloned: Record<string, unknown> = {};
+	for (const [key, value] of Object.entries(params)) {
+		cloned[key] = cloneDetailValue(value);
+	}
+	return cloned;
+}
+
+/** LLM-facing text for todo reducer operations. */
+export function formatContent(op: Op, state: TaskState): string {
+	switch (op.kind) {
+		case "create": {
+			const task = state.tasks.find((candidate) => candidate.id === op.taskId);
+			if (!task) return `Created #${op.taskId}`;
+			return `Created #${task.id}: ${task.subject} (pending)`;
+		}
+		case "update": {
+			const transition =
+				op.fromStatus === op.toStatus
+					? ""
+					: ` (${op.fromStatus} → ${op.toStatus})`;
+			return `Updated #${op.id}${transition}`;
+		}
+		case "delete":
+			return `Deleted #${op.id}: ${op.subject}`;
+		case "clear":
+			return `Cleared ${op.count} tasks`;
+		case "list": {
+			let tasks = state.tasks;
+			if (!op.includeDeleted) {
+				tasks = tasks.filter((task) => task.status !== "deleted");
+			}
+			if (op.statusFilter) {
+				tasks = tasks.filter((task) => task.status === op.statusFilter);
+			}
+			return tasks.length === 0
+				? "No tasks"
+				: tasks.map(formatListLine).join("\n");
+		}
+		case "get":
+			return formatGetLines(op.task, state);
+		case "error":
+			return `Error: ${op.message}`;
+	}
+}
+
+/**
+ * Compatible `todo` result envelope. `details` is the replay snapshot consumed
+ * by session branch replay, so keep field names stable.
+ */
+export function buildToolResult(
+	action: TaskAction,
+	params: TaskMutationParams,
+	state: TaskState,
+	op: Op,
+): TodoToolResult {
+	const snapshot = cloneTaskState(state);
+	const details: TaskDetails = {
+		action,
+		params: cloneParams(params),
+		tasks: snapshot.tasks,
+		nextId: snapshot.nextId,
+		...(op.kind === "error" ? { error: op.message } : {}),
+	};
+
+	return {
+		content: [{ type: "text", text: formatContent(op, state) }],
+		details,
+	};
+}

package/src/session-todos/tool/types.ts

@@ -0,0 +1,149 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { type Static, Type } from "typebox";
+
+// ---------------------------------------------------------------------------
+// Tool / command identity — verbatim string boundaries.
+// Tool name "todo" is the persistence key for branch replay (filtering
+// `toolResult.toolName === "todo"`). DO NOT rename.
+// ---------------------------------------------------------------------------
+
+export const TOOL_NAME = "todo";
+export const TOOL_LABEL = "Todo";
+export const COMMAND_NAME = "todos";
+
+// ---------------------------------------------------------------------------
+// User-facing strings (kept stable for /todos UX parity).
+// ---------------------------------------------------------------------------
+
+export const ERR_REQUIRES_INTERACTIVE = "/todos requires interactive mode";
+export const MSG_NO_TODOS = "No todos yet. Ask the agent to add some!";
+
+// ---------------------------------------------------------------------------
+// Public domain types
+// ---------------------------------------------------------------------------
+
+export type TaskStatus = "pending" | "in_progress" | "completed" | "deleted";
+
+export type TaskAction =
+	| "create"
+	| "update"
+	| "list"
+	| "get"
+	| "delete"
+	| "clear";
+
+export interface Task {
+	id: number;
+	subject: string;
+	description?: string;
+	activeForm?: string;
+	status: TaskStatus;
+	blockedBy?: number[];
+	owner?: string;
+	metadata?: Record<string, unknown>;
+}
+
+/**
+ * Persistence + replay snapshot. Every successful `todo` tool call returns this
+ * shape under `details`; replay reads the latest one from the branch to
+ * reconstruct module state. Field order and field names are pinned by
+ * cross-version replay compatibility.
+ */
+export interface TaskDetails {
+	action: TaskAction;
+	params: Record<string, unknown>;
+	tasks: Task[];
+	nextId: number;
+	error?: string;
+}
+
+/**
+ * Open-shape input bag the reducer accepts. Stays an interface so the index
+ * signature (`[key: string]: unknown`) lets the runtime pass through TypeBox
+ * `Static<typeof TodoParamsSchema>` without `as` casts.
+ */
+export interface TaskMutationParams {
+	[key: string]: unknown;
+	subject?: string;
+	description?: string;
+	activeForm?: string;
+	status?: TaskStatus;
+	blockedBy?: number[];
+	addBlockedBy?: number[];
+	removeBlockedBy?: number[];
+	owner?: string;
+	metadata?: Record<string, unknown>;
+	id?: number;
+	includeDeleted?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// TypeBox parameter schema — every `description` doubles as LLM-facing prompt
+// copy. Field order and wording stay compatible with rpiv-todo v1.
+// ---------------------------------------------------------------------------
+
+export const TodoParamsSchema = Type.Object({
+	action: StringEnum([
+		"create",
+		"update",
+		"list",
+		"get",
+		"delete",
+		"clear",
+	] as const),
+	subject: Type.Optional(
+		Type.String({ description: "Task subject line (required for create)" }),
+	),
+	description: Type.Optional(
+		Type.String({ description: "Long-form task description" }),
+	),
+	activeForm: Type.Optional(
+		Type.String({
+			description:
+				"Present-continuous spinner label shown while status is in_progress (e.g. 'writing tests')",
+		}),
+	),
+	status: Type.Optional(
+		StringEnum(["pending", "in_progress", "completed", "deleted"] as const, {
+			description: "Target status (update) or list filter (list)",
+		}),
+	),
+	blockedBy: Type.Optional(
+		Type.Array(Type.Number(), {
+			description: "Initial blockedBy ids (create only)",
+		}),
+	),
+	addBlockedBy: Type.Optional(
+		Type.Array(Type.Number(), {
+			description: "Task ids to add to blockedBy (update only, additive merge)",
+		}),
+	),
+	removeBlockedBy: Type.Optional(
+		Type.Array(Type.Number(), {
+			description:
+				"Task ids to remove from blockedBy (update only, additive merge)",
+		}),
+	),
+	owner: Type.Optional(
+		Type.String({ description: "Agent/owner assigned to this task" }),
+	),
+	metadata: Type.Optional(
+		Type.Record(Type.String(), Type.Unknown(), {
+			description:
+				"Arbitrary metadata; pass null value for a key to delete that key on update",
+		}),
+	),
+	id: Type.Optional(
+		Type.Number({
+			description: "Task id (required for update, get, delete)",
+		}),
+	),
+	includeDeleted: Type.Optional(
+		Type.Boolean({
+			description:
+				"If true, list action returns deleted (tombstoned) tasks as well. Default: false.",
+		}),
+	),
+});
+
+export type TodoParams = Static<typeof TodoParamsSchema>;