@phi-code-admin/phi-code 0.83.0 → 0.84.0

package/extensions/phi/todo/todo.ts

@@ -0,0 +1,146 @@
+/**
+ * todo tool + /todos command — thin registration shell.
+ *
+ * Tool/command identity, schema, types, reducer, store, replay, response
+ * envelope, selectors, and view formatters live in the layered modules under
+ * `tool/`, `state/`, and `view/`. This file is the package-root registration
+ * surface — it mirrors `packages/rpiv-ask-user-question/ask-user-question.ts`
+ * which keeps the tool registration at the package root.
+ *
+ * Public re-exports below preserve the pre-refactor import surface so that
+ * `index.ts`, `todo-overlay.ts`, and the global `test/setup.ts` `beforeEach`
+ * continue to import from `./todo.js`.
+ */
+
+import type { ExtensionAPI } from "phi-code";
+import { loadConfig, validateGuidanceFields } from "./config.js";
+import { formatStatusLabel, t } from "./state/i18n-bridge.js";
+import { replayFromBranch } from "./state/replay.js";
+import { selectTasksByStatus, selectTodoCounts, selectVisibleTasks } from "./state/selectors.js";
+import { applyTaskMutation } from "./state/state-reducer.js";
+import { commitState, getState, replaceState } from "./state/store.js";
+import { buildToolResult } from "./tool/response-envelope.js";
+import {
+	COMMAND_NAME,
+	ERR_REQUIRES_INTERACTIVE,
+	MSG_NO_TODOS,
+	type TaskMutationParams,
+	TOOL_LABEL,
+	TOOL_NAME,
+	TodoParamsSchema,
+} from "./tool/types.js";
+import { formatCommandTaskLine, renderTodoCall, renderTodoResult } from "./view/format.js";
+
+// English fallbacks for localized /todos section headers — the box-drawing
+// decoration is part of the localized string so translators can adjust spacing.
+const SECTION_PENDING = "── Pending ──";
+const SECTION_IN_PROGRESS = "── In Progress ──";
+const SECTION_COMPLETED = "── Completed ──";
+
+// ---------------------------------------------------------------------------
+// Public re-exports — pre-refactor consumers (overlay, tests, index.ts) keep
+// importing from `./todo.js`. New code may opt into deeper imports.
+// ---------------------------------------------------------------------------
+
+export { isTransitionValid } from "./state/invariants.js";
+export { applyTaskMutation } from "./state/state-reducer.js";
+export { __resetState, getNextId, getTodos } from "./state/store.js";
+export { deriveBlocks, detectCycle } from "./state/task-graph.js";
+export type { Task, TaskAction, TaskDetails, TaskStatus } from "./tool/types.js";
+export { TOOL_NAME } from "./tool/types.js";
+
+/**
+ * Backward-compat replay shim. Pre-refactor `reconstructTodoState(ctx)`
+ * mutated module state directly; the new replay seam (`state/replay.ts`)
+ * returns a `TaskState` and the caller commits via `replaceState`.
+ */
+export function reconstructTodoState(ctx: Parameters<typeof replayFromBranch>[0]): void {
+	replaceState(replayFromBranch(ctx));
+}
+
+// ---------------------------------------------------------------------------
+// Tool registration
+// ---------------------------------------------------------------------------
+
+export const DEFAULT_PROMPT_SNIPPET = "Manage a task list to track multi-step progress";
+export const DEFAULT_PROMPT_GUIDELINES: string[] = [
+	"Use `todo` for complex work with 3+ steps, when the user gives you a list of tasks, or immediately after receiving new instructions to capture requirements. Skip it for single trivial tasks and purely conversational requests.",
+	"When starting any task, mark it in_progress BEFORE beginning work. Mark it completed IMMEDIATELY when done — never batch completions. Exactly one task should be in_progress at a time.",
+	"Never mark a task completed if tests are failing, the implementation is partial, or you hit unresolved errors — keep it in_progress and create a new task for the blocker instead.",
+	"Task status is a 4-state machine: pending → in_progress → completed, plus deleted as a tombstone. Pass activeForm (present-continuous label, e.g. 'researching existing tool') when marking in_progress.",
+	"Use blockedBy to express dependencies (A is blocked by B). On create, pass blockedBy as the initial set. On update, use addBlockedBy / removeBlockedBy (additive merge — do not resend the full array). Cycles are rejected.",
+	"list hides tombstoned (deleted) tasks by default; pass includeDeleted:true to see them. Pass status to filter by a single status.",
+	"Subject must be short and imperative (e.g. 'Research existing tool'); description is for long-form detail. activeForm is a present-continuous label shown while in_progress.",
+];
+
+export function registerTodoTool(pi: ExtensionAPI): void {
+	const guidance = validateGuidanceFields(loadConfig().guidance);
+	pi.registerTool({
+		name: TOOL_NAME,
+		label: TOOL_LABEL,
+		description:
+			"Manage a task list for tracking multi-step progress. Actions: create (new task), update (change status/fields/dependencies), list (all tasks, optionally filtered by status), get (single task details), delete (tombstone), clear (reset all). Status: pending → in_progress → completed, plus deleted tombstone. Use this to plan and track multi-step work like research, design, and implementation.",
+		promptSnippet: guidance.promptSnippet ?? DEFAULT_PROMPT_SNIPPET,
+		promptGuidelines: guidance.promptGuidelines ?? DEFAULT_PROMPT_GUIDELINES,
+		parameters: TodoParamsSchema,
+
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			const result = applyTaskMutation(getState(), params.action, params as TaskMutationParams);
+			commitState(result.state);
+			return buildToolResult(params.action, params as TaskMutationParams, result.state, result.op);
+		},
+
+		renderCall(args, theme, _context) {
+			return renderTodoCall(args as never, theme, getState());
+		},
+
+		renderResult(result, _opts, theme, _context) {
+			return renderTodoResult(result, theme);
+		},
+	});
+}
+
+// ---------------------------------------------------------------------------
+// /todos slash command
+// ---------------------------------------------------------------------------
+
+export function registerTodosCommand(pi: ExtensionAPI): void {
+	pi.registerCommand(COMMAND_NAME, {
+		description: "Show all todos on the current branch, grouped by status",
+		handler: async (_args, ctx) => {
+			if (!ctx.hasUI) {
+				ctx.ui.notify(t("command.requires_interactive", ERR_REQUIRES_INTERACTIVE), "error");
+				return;
+			}
+			const state = getState();
+			const visible = selectVisibleTasks(state);
+			if (visible.length === 0) {
+				ctx.ui.notify(t("command.no_todos", 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: string[] = [header.join(" · ")];
+			if (groups.pending.length > 0) {
+				lines.push(t("command.section.pending", SECTION_PENDING));
+				for (const task of groups.pending) lines.push(formatCommandTaskLine(task, "○"));
+			}
+			if (groups.inProgress.length > 0) {
+				lines.push(t("command.section.in_progress", SECTION_IN_PROGRESS));
+				for (const task of groups.inProgress) lines.push(formatCommandTaskLine(task, "◐"));
+			}
+			if (groups.completed.length > 0) {
+				lines.push(t("command.section.completed", SECTION_COMPLETED));
+				for (const task of groups.completed) lines.push(formatCommandTaskLine(task, "✓"));
+			}
+
+			ctx.ui.notify(lines.join("\n"), "info");
+		},
+	});
+}

package/extensions/phi/todo/tool/response-envelope.ts

@@ -0,0 +1,94 @@
+import 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";
+
+/**
+ * Format a single task as a `[status] #id subject [(activeForm)] [⛓ #dep,…]`
+ * line. Used by the `list` content branch only — the overlay and `/todos`
+ * formatting paths use `view/format.ts` for richer presentations.
+ */
+function formatListLine(t: Task): string {
+	const block = t.blockedBy?.length ? ` ⛓ ${t.blockedBy.map((id) => `#${id}`).join(",")}` : "";
+	const form = t.status === "in_progress" && t.activeForm ? ` (${t.activeForm})` : "";
+	return `[${t.status}] #${t.id} ${t.subject}${form}${block}`;
+}
+
+/**
+ * Multi-line presentation for the `get` action. Order of rows is pinned by
+ * pre-refactor `todo.ts:354-376` — description, activeForm, blockedBy, blocks,
+ * owner — so envelope-level snapshot tests stay byte-equivalent.
+ */
+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");
+}
+
+/**
+ * Pure formatter: `(op, state) → string`. Closed switch on `op.kind` —
+ * adding a new `Op` variant fails to compile here until a branch is added.
+ * The strings on each branch are byte-equivalent to pre-refactor `todo.ts`
+ * reducer output.
+ */
+export function formatContent(op: Op, state: TaskState): string {
+	switch (op.kind) {
+		case "create": {
+			const t = state.tasks.find((x) => x.id === op.taskId);
+			// Defensive — `op.taskId` always resolves on success path.
+			if (!t) return `Created #${op.taskId}`;
+			return `Created #${t.id}: ${t.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 view = state.tasks;
+			if (!op.includeDeleted) view = view.filter((t) => t.status !== "deleted");
+			if (op.statusFilter) view = view.filter((t) => t.status === op.statusFilter);
+			return view.length === 0 ? "No tasks" : view.map(formatListLine).join("\n");
+		}
+		case "get":
+			return formatGetLines(op.task, state);
+		case "error":
+			return `Error: ${op.message}`;
+	}
+}
+
+/**
+ * Build the LLM-facing tool envelope after the store has committed the
+ * reducer's new state. `details` is the persistence + replay snapshot —
+ * `state/replay.ts` consumes this exact shape on session lifecycle events.
+ *
+ * Mirrors `packages/rpiv-ask-user-question/tool/response-envelope.ts:13-47`.
+ */
+export function buildToolResult(
+	action: TaskAction,
+	params: TaskMutationParams,
+	state: TaskState,
+	op: Op,
+): { content: Array<{ type: "text"; text: string }>; details: TaskDetails } {
+	const text = formatContent(op, state);
+	const details: TaskDetails = {
+		action,
+		params: params as Record<string, unknown>,
+		tasks: state.tasks,
+		nextId: state.nextId,
+		...(op.kind === "error" ? { error: op.message } : {}),
+	};
+	return { content: [{ type: "text", text }], details };
+}

package/extensions/phi/todo/tool/types.ts

@@ -0,0 +1,128 @@
+import { StringEnum } from "phi-code-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"`) AND the permissions entry at
+// `templates/pi-permissions.jsonc:26`. 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`; `state/replay.ts` 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 are pinned by registration tests and the
+// pre-refactor schema at `packages/rpiv-todo/todo.ts:512-573`.
+// ---------------------------------------------------------------------------
+
+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>;

package/extensions/phi/todo/view/format.ts

@@ -0,0 +1,162 @@
+import type { Theme } from "phi-code";
+import { Text } from "phi-code-tui";
+import { formatStatusLabel } from "../state/i18n-bridge.js";
+import { selectTaskSubjectById } from "../state/selectors.js";
+import type { TaskState } from "../state/state.js";
+import type { Task, TaskAction, TaskDetails, TaskMutationParams, TaskStatus } from "../tool/types.js";
+
+// Re-export so legacy import paths (todo.ts, tests) continue to resolve;
+// the canonical definition lives in the i18n bridge.
+export { formatStatusLabel };
+
+// ---------------------------------------------------------------------------
+// Status presentation tables — the single source of truth for glyph/color.
+// ---------------------------------------------------------------------------
+
+export const STATUS_GLYPH: Record<TaskStatus, string> = {
+	pending: "○",
+	in_progress: "◐",
+	completed: "●",
+	deleted: "⊘",
+};
+
+/**
+ * Color palette for the renderResult status echo. `deleted` uses `muted` so a
+ * successful delete is visually distinct from the error branch (which uses
+ * `error` + `✗`). Mirrors pre-refactor `todo.ts:444-450`.
+ */
+export const STATUS_COLOR: Record<TaskStatus, "dim" | "warning" | "success" | "muted"> = {
+	pending: "dim",
+	in_progress: "warning",
+	completed: "success",
+	deleted: "muted",
+};
+
+/**
+ * Per-action prefix glyph for renderCall. `+` create, `→` update, `×` delete,
+ * `›` get, `☰` list, `∅` clear. Pre-refactor `todo.ts:457-464`.
+ */
+export const ACTION_GLYPH: Record<TaskAction, string> = {
+	create: "+",
+	update: "→",
+	delete: "×",
+	get: "›",
+	list: "☰",
+	clear: "∅",
+};
+
+/**
+ * Glyph for the persistent overlay's per-task row. Differs from `STATUS_GLYPH`
+ * for `completed` (`✓` vs `●`) and `deleted` (`✗` vs `⊘`) because the
+ * overlay caller never renders a `deleted` row but uses `✗` in its
+ * error-toned palette. Mirrors pre-refactor `todo-overlay.ts:23-33`.
+ */
+export function overlayStatusGlyph(status: TaskStatus, theme: Theme): string {
+	switch (status) {
+		case "pending":
+			return theme.fg("dim", "○");
+		case "in_progress":
+			return theme.fg("warning", "◐");
+		case "completed":
+			return theme.fg("success", "✓");
+		case "deleted":
+			return theme.fg("error", "✗");
+	}
+}
+
+/**
+ * Format a single task for the overlay (with theme + glyph + dep suffix).
+ * Used by `TodoOverlay.formatTaskLine` post-refactor; behavior is unchanged.
+ */
+export function formatOverlayTaskLine(t: Task, theme: Theme, showId: boolean): string {
+	const glyph = overlayStatusGlyph(t.status, theme);
+	const subjectColor = t.status === "completed" || t.status === "deleted" ? "dim" : "text";
+	let subject = theme.fg(subjectColor, t.subject);
+	if (t.status === "completed" || t.status === "deleted") {
+		subject = theme.strikethrough(subject);
+	}
+	let line = `${glyph}`;
+	if (showId) line += ` ${theme.fg("accent", `#${t.id}`)}`;
+	line += ` ${subject}`;
+	if (t.status === "in_progress" && t.activeForm) {
+		line += ` ${theme.fg("dim", `(${t.activeForm})`)}`;
+	}
+	if (t.blockedBy && t.blockedBy.length > 0) {
+		line += ` ${theme.fg("dim", `⛓ ${t.blockedBy.map((id) => `#${id}`).join(",")}`)}`;
+	}
+	return line;
+}
+
+/**
+ * Format a single task line for the `/todos` slash command (no glyph color,
+ * indented bullet prefix). Pre-refactor `todo.ts:670-674`.
+ */
+export function formatCommandTaskLine(t: Task, glyph: string): string {
+	const form = t.status === "in_progress" && t.activeForm ? ` (${t.activeForm})` : "";
+	const block = t.blockedBy?.length ? `    ⛓ ${t.blockedBy.map((id) => `#${id}`).join(",")}` : "";
+	return `  ${glyph} #${t.id} ${t.subject}${form}${block}`;
+}
+
+// ---------------------------------------------------------------------------
+// Tool render hooks — wrapped so `todo.ts` becomes a thin call-site.
+// ---------------------------------------------------------------------------
+
+/**
+ * `renderCall` body. Receives the parsed args, the theme, and the live
+ * `TaskState` (resolved by the caller via `getState()`). Returns a `Text`
+ * node identical to pre-refactor `todo.ts:507-525`.
+ */
+export function renderTodoCall(
+	args: TaskMutationParams & { action: TaskAction },
+	theme: Theme,
+	state: TaskState,
+): Text {
+	const glyph = ACTION_GLYPH[args.action] ?? args.action;
+	let text = theme.fg("toolTitle", theme.bold("todo ")) + theme.fg("muted", glyph);
+
+	if (args.action === "create" && args.subject) {
+		text += ` ${theme.fg("dim", args.subject)}`;
+	} else if (
+		(args.action === "update" || args.action === "get" || args.action === "delete") &&
+		args.id !== undefined
+	) {
+		const subject = selectTaskSubjectById(state, args.id);
+		text += ` ${theme.fg("accent", subject ?? `#${args.id}`)}`;
+	} else if (args.action === "list" && args.status) {
+		text += ` ${theme.fg("muted", formatStatusLabel(args.status))}`;
+	}
+	return new Text(text, 0, 0);
+}
+
+/**
+ * `renderResult` body. Inspects `details` to pick the per-action status echo
+ * (only `create`/`update`/`delete` advertise a status; `list`/`get`/`clear`
+ * fall back to plain `✓`). Identical visual output to pre-refactor
+ * `todo.ts:533-565`.
+ */
+export function renderTodoResult(result: { details?: unknown }, theme: Theme): Text {
+	const details = result.details as TaskDetails | undefined;
+	let status: TaskStatus | undefined;
+	if (details) {
+		const params = details.params as TaskMutationParams;
+		switch (details.action) {
+			case "create":
+				status = details.tasks[details.tasks.length - 1]?.status;
+				break;
+			case "update":
+				status = params.status ?? details.tasks.find((t) => t.id === params.id)?.status;
+				break;
+			case "delete":
+				status = details.tasks.find((t) => t.id === params.id)?.status;
+				break;
+			case "list":
+			case "get":
+			case "clear":
+				break;
+		}
+	}
+	if (status) {
+		return new Text(theme.fg(STATUS_COLOR[status], `${STATUS_GLYPH[status]} ${formatStatusLabel(status)}`), 0, 0);
+	}
+	return new Text(theme.fg("success", "✓"), 0, 0);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@phi-code-admin/phi-code",
-	"version": "0.83.0",
+	"version": "0.84.0",
 	"description": "Coding agent CLI with persistent memory, sub-agents, intelligent routing, and orchestration",
 	"type": "module",
 	"piConfig": {