@bumpyclock/pi-tasque 0.1.0

package/src/session-todos/state/invariants.ts

@@ -0,0 +1,17 @@
+import type { TaskStatus } from "../tool/types.js";
+
+/**
+ * Todo status transition table. Same-status updates are idempotent; `deleted`
+ * is terminal and `completed` may only move to `deleted`.
+ */
+export const VALID_TRANSITIONS: Record<TaskStatus, ReadonlySet<TaskStatus>> = {
+	pending: new Set(["in_progress", "completed", "deleted"]),
+	in_progress: new Set(["pending", "completed", "deleted"]),
+	completed: new Set(["deleted"]),
+	deleted: new Set(),
+};
+
+export function isTransitionValid(from: TaskStatus, to: TaskStatus): boolean {
+	if (from === to) return true;
+	return VALID_TRANSITIONS[from].has(to);
+}

package/src/session-todos/state/replay.ts

@@ -0,0 +1,272 @@
+import {
+	TOOL_NAME,
+	type Task,
+	type TaskDetails,
+	type TaskStatus,
+} from "../tool/types.js";
+import {
+	cloneTask,
+	cloneTaskState,
+	EMPTY_STATE,
+	type TaskState,
+} from "./state.js";
+
+interface BranchContext {
+	sessionManager: {
+		getBranch(): Iterable<unknown>;
+	};
+}
+
+interface BranchMessageEntry {
+	type?: string;
+	message?: {
+		role?: string;
+		toolName?: string;
+		details?: unknown;
+	};
+}
+
+const VALID_STATUSES = new Set<TaskStatus>([
+	"pending",
+	"in_progress",
+	"completed",
+	"deleted",
+]);
+
+const TASK_BRIDGE_REPLAY_TOOL_NAME = "task_bridge";
+const TSQ_CLAIM_REPLAY_TOOL_NAME = "tsq_claim";
+const TASK_BRIDGE_MUTATION_ACTIONS = new Set(["promote_todo", "import_tsq"]);
+
+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 isSafePositiveInteger(value: unknown): value is number {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 1;
+}
+
+function isOptionalString(value: unknown): boolean {
+	return value === undefined || typeof value === "string";
+}
+
+function isTask(value: unknown): value is Task {
+	if (!isPlainObject(value)) return false;
+	return (
+		isSafePositiveInteger(value.id) &&
+		typeof value.subject === "string" &&
+		value.subject.trim().length > 0 &&
+		typeof value.status === "string" &&
+		VALID_STATUSES.has(value.status as TaskStatus) &&
+		isOptionalString(value.description) &&
+		isOptionalString(value.activeForm) &&
+		isOptionalString(value.owner) &&
+		(value.blockedBy === undefined ||
+			(Array.isArray(value.blockedBy) &&
+				value.blockedBy.every(isSafePositiveInteger))) &&
+		(value.metadata === undefined || isPlainObject(value.metadata))
+	);
+}
+
+function hasBlockedByCycle(tasks: readonly Task[]): boolean {
+	const edges = new Map<number, readonly number[]>();
+	for (const task of tasks) edges.set(task.id, task.blockedBy ?? []);
+
+	const visiting = new Set<number>();
+	const visited = new Set<number>();
+
+	const visit = (taskId: number): boolean => {
+		if (visiting.has(taskId)) return true;
+		if (visited.has(taskId)) return false;
+
+		visiting.add(taskId);
+		for (const blockerId of edges.get(taskId) ?? []) {
+			if (visit(blockerId)) return true;
+		}
+		visiting.delete(taskId);
+		visited.add(taskId);
+		return false;
+	};
+
+	for (const taskId of edges.keys()) {
+		if (visit(taskId)) return true;
+	}
+	return false;
+}
+
+function hasValidTaskSnapshot(tasks: readonly Task[], nextId: number): boolean {
+	const tasksById = new Map<number, Task>();
+	let maxTaskId = 0;
+
+	for (const task of tasks) {
+		if (tasksById.has(task.id)) return false;
+		tasksById.set(task.id, task);
+		maxTaskId = Math.max(maxTaskId, task.id);
+	}
+
+	if (tasks.length > 0 && nextId <= maxTaskId) return false;
+
+	for (const task of tasks) {
+		for (const blockerId of task.blockedBy ?? []) {
+			if (blockerId === task.id) return false;
+			const blocker = tasksById.get(blockerId);
+			if (!blocker || blocker.status === "deleted") return false;
+		}
+	}
+
+	return !hasBlockedByCycle(tasks);
+}
+
+/**
+ * Defensive snapshot guard. Replay only needs the persisted task list and next
+ * id; older compatible todo results may include extra fields.
+ */
+export function isTaskDetails(value: unknown): value is TaskDetails {
+	if (!isPlainObject(value)) return false;
+	const tasks = value.tasks;
+	return (
+		Array.isArray(tasks) &&
+		tasks.every(isTask) &&
+		isSafePositiveInteger(value.nextId) &&
+		hasValidTaskSnapshot(tasks, value.nextId)
+	);
+}
+
+function emptyState(): TaskState {
+	return cloneTaskState(EMPTY_STATE);
+}
+
+interface BridgeLinkReplayDetails {
+	readonly todoId: number;
+	readonly tsqId: string;
+}
+
+function getReplayableBridgeLink(
+	details: unknown,
+): BridgeLinkReplayDetails | undefined {
+	if (!isPlainObject(details) || details.ok !== true) return undefined;
+	const data = details.data;
+	if (!isPlainObject(data) || data.action !== "link") return undefined;
+	const link = data.link;
+	if (!isPlainObject(link)) return undefined;
+	if (!isSafePositiveInteger(link.todoId)) return undefined;
+	if (typeof link.tsqId !== "string") return undefined;
+
+	const tsqId = link.tsqId.trim();
+	if (tsqId.length === 0) return undefined;
+	return { todoId: link.todoId, tsqId };
+}
+
+function applyReplayableBridgeLink(
+	state: TaskState,
+	link: BridgeLinkReplayDetails,
+): TaskState {
+	const taskIndex = state.tasks.findIndex((task) => task.id === link.todoId);
+	const task = state.tasks[taskIndex];
+	if (task === undefined || task.status === "deleted") return state;
+
+	const metadata = { ...(task.metadata ?? {}), tsqId: link.tsqId };
+	const tasks = [...state.tasks];
+	tasks[taskIndex] = { ...task, metadata };
+	return { tasks, nextId: state.nextId };
+}
+
+function getReplayableBridgeTodoSnapshot(
+	details: unknown,
+): TaskState | undefined {
+	if (!isPlainObject(details) || details.ok !== true) return undefined;
+	const data = details.data;
+	if (!isPlainObject(data)) return undefined;
+	if (
+		typeof data.action !== "string" ||
+		!TASK_BRIDGE_MUTATION_ACTIONS.has(data.action)
+	) {
+		return undefined;
+	}
+
+	const snapshot = data.todoSnapshot;
+	if (!isTaskDetails(snapshot)) return undefined;
+	return cloneTaskState(snapshot);
+}
+
+function getReplayableClaimTodo(details: unknown): Task | undefined {
+	if (!isPlainObject(details) || details.ok !== true) return undefined;
+	const data = details.data;
+	if (!isPlainObject(data) || data.createTodo !== true) return undefined;
+	const todo = data.todo;
+	if (!isTask(todo)) return undefined;
+
+	const tsqId = getClaimTodoTsqId(data, todo);
+	if (tsqId === undefined) return undefined;
+	return cloneTask({ ...todo, metadata: { ...(todo.metadata ?? {}), tsqId } });
+}
+
+function getClaimTodoTsqId(
+	data: Record<string, unknown>,
+	todo: Task,
+): string | undefined {
+	const id = data.id;
+	if (typeof id === "string" && id.trim().length > 0) return id.trim();
+	const metadataId = todo.metadata?.tsqId;
+	if (typeof metadataId === "string" && metadataId.trim().length > 0) {
+		return metadataId.trim();
+	}
+	return undefined;
+}
+
+function applyReplayableClaimTodo(state: TaskState, todo: Task): TaskState {
+	if (state.tasks.some((task) => task.id === todo.id)) return state;
+
+	const tasks = [...state.tasks, todo];
+	const nextId = Math.max(state.nextId, todo.id + 1);
+	if (!hasValidTaskSnapshot(tasks, nextId)) return state;
+	return { tasks, nextId };
+}
+
+/**
+ * Rebuild todo state from the current session branch. The latest compatible
+ * `todo` tool result wins; malformed snapshots are skipped. Successful
+ * state-mutating `task_bridge` results replay their todo snapshot, while
+ * successful `task_bridge link` results and successful `tsq_claim` createTodo
+ * results are replayed onto the current todo snapshot so bridge metadata,
+ * imports/promotions, and claim-created todos survive reload/branch replay.
+ */
+export function replayFromBranch(ctx: BranchContext): TaskState {
+	let result = emptyState();
+
+	for (const entry of ctx.sessionManager.getBranch()) {
+		const branchEntry = entry as BranchMessageEntry;
+		if (branchEntry.type !== "message") continue;
+
+		const message = branchEntry.message;
+		if (!message || message.role !== "toolResult") continue;
+
+		if (message.toolName === TOOL_NAME) {
+			if (!isTaskDetails(message.details)) continue;
+			result = cloneTaskState(message.details);
+			continue;
+		}
+
+		if (message.toolName === TASK_BRIDGE_REPLAY_TOOL_NAME) {
+			const snapshot = getReplayableBridgeTodoSnapshot(message.details);
+			if (snapshot !== undefined) {
+				result = snapshot;
+				continue;
+			}
+
+			const link = getReplayableBridgeLink(message.details);
+			if (link === undefined) continue;
+			result = applyReplayableBridgeLink(result, link);
+			continue;
+		}
+
+		if (message.toolName === TSQ_CLAIM_REPLAY_TOOL_NAME) {
+			const todo = getReplayableClaimTodo(message.details);
+			if (todo === undefined) continue;
+			result = applyReplayableClaimTodo(result, todo);
+		}
+	}
+
+	return result;
+}

package/src/session-todos/state/selectors.ts

@@ -0,0 +1,140 @@
+import type { Task, TaskStatus } from "../tool/types.js";
+import type { TaskState } from "./state.js";
+
+/** Tasks excluding deleted tombstones — canonical visible todo list. */
+export function selectVisibleTasks(state: TaskState): readonly Task[] {
+	return state.tasks.filter((task) => task.status !== "deleted");
+}
+
+export interface TasksByStatus {
+	pending: readonly Task[];
+	inProgress: readonly Task[];
+	completed: readonly Task[];
+}
+
+/** Visible tasks grouped by user-facing status buckets. */
+export function selectTasksByStatus(state: TaskState): TasksByStatus {
+	const visible = selectVisibleTasks(state);
+	return {
+		pending: visible.filter((task) => task.status === "pending"),
+		inProgress: visible.filter((task) => task.status === "in_progress"),
+		completed: visible.filter((task) => task.status === "completed"),
+	};
+}
+
+export interface TodoCounts {
+	total: number;
+	pending: number;
+	inProgress: number;
+	completed: number;
+}
+
+/** Counts used by the overlay heading and /todos command summary. */
+export function selectTodoCounts(state: TaskState): TodoCounts {
+	const groups = selectTasksByStatus(state);
+	return {
+		total:
+			groups.pending.length +
+			groups.inProgress.length +
+			groups.completed.length,
+		pending: groups.pending.length,
+		inProgress: groups.inProgress.length,
+		completed: groups.completed.length,
+	};
+}
+
+/** Show row ids only when dependency suffixes need an id anchor. */
+export function selectShowTaskIds(state: TaskState): boolean {
+	return selectVisibleTasks(state).some(
+		(task) => (task.blockedBy?.length ?? 0) > 0,
+	);
+}
+
+/** Resolve a task subject by id for tool-call rendering. */
+export function selectTaskSubjectById(
+	state: TaskState,
+	id: number,
+): string | undefined {
+	return state.tasks.find((task) => task.id === id)?.subject;
+}
+
+export interface OverlayLayout {
+	visible: readonly Task[];
+	hiddenCompleted: number;
+	truncatedTail: number;
+}
+
+/**
+ * Decide which rows fit in the overlay body.
+ *
+ * When overflowing, one body slot is reserved for a summary row. Completed rows
+ * are hidden first; if active rows still overflow, the active tail is truncated.
+ */
+export function selectOverlayLayout(
+	state: TaskState,
+	budget: number,
+): OverlayLayout {
+	const all = selectVisibleTasks(state);
+	const normalizedBudget = Number.isFinite(budget)
+		? Math.max(0, Math.floor(budget))
+		: 0;
+	const nonCompleted = all.filter((task) => task.status !== "completed");
+	const totalCompleted = all.length - nonCompleted.length;
+
+	if (all.length <= normalizedBudget) {
+		return { visible: all, hiddenCompleted: 0, truncatedTail: 0 };
+	}
+
+	if (normalizedBudget <= 0) {
+		return {
+			visible: [],
+			hiddenCompleted: totalCompleted,
+			truncatedTail: nonCompleted.length,
+		};
+	}
+
+	const rowBudget = normalizedBudget - 1;
+	if (rowBudget <= 0) {
+		return {
+			visible: [],
+			hiddenCompleted: totalCompleted,
+			truncatedTail: nonCompleted.length,
+		};
+	}
+
+	if (nonCompleted.length <= rowBudget) {
+		const kept = new Set<Task>(nonCompleted);
+		for (const task of all) {
+			if (kept.size >= rowBudget) break;
+			if (task.status === "completed") kept.add(task);
+		}
+
+		const visible = all.filter((task) => kept.has(task));
+		const shownCompleted = visible.filter(
+			(task) => task.status === "completed",
+		).length;
+		return {
+			visible,
+			hiddenCompleted: totalCompleted - shownCompleted,
+			truncatedTail: 0,
+		};
+	}
+
+	return {
+		visible: nonCompleted.slice(0, rowBudget),
+		hiddenCompleted: totalCompleted,
+		truncatedTail: nonCompleted.length - rowBudget,
+	};
+}
+
+/** Whether any visible task is still actionable. */
+export function selectHasActive(state: TaskState): boolean {
+	return selectVisibleTasks(state).some((task) =>
+		ACTIVE_STATUSES.has(task.status),
+	);
+}
+
+export const ACTIVE_STATUSES: ReadonlySet<TaskStatus> = new Set([
+	"pending",
+	"in_progress",
+]);