@matthewfl/pi-jtodo 0.0.1

package/src/model.ts

@@ -0,0 +1,155 @@
+/**
+ * Data model — types ported from jcode-task-types/src/lib.rs, plus
+ * sanitizers used when replaying tool-result `details` from the session
+ * branch (which round-trips through JSON, so all fields are optional).
+ */
+
+export interface TodoItem {
+	id: string;
+	content: string;
+	status: string;
+	priority: string;
+	group?: string;
+	confidence?: number;
+	completion_confidence?: number;
+	/** Tool-maintained; model-supplied values are discarded on write. */
+	confidence_history: number[];
+}
+
+export interface TodoPlan {
+	user_intention?: string;
+	understands_user_intent?: number;
+	/** Tool-maintained; model-supplied values are discarded on write. */
+	understands_user_intent_history: number[];
+}
+
+export interface TodoGoal {
+	/** Group label this goal describes; undefined = the ungrouped flat list. */
+	group?: string;
+	closed_feedback_loop?: number;
+	closed_feedback_loop_history: number[];
+	feedback_loop?: string;
+	end_to_end_ownership?: number;
+	end_to_end_ownership_history: number[];
+}
+
+export type GateObservationKind = "intent_understanding" | "closed_feedback_loop";
+
+/** A point during the turn that a quality check would have interrupted on. */
+export interface GateObservation {
+	kind: GateObservationKind;
+	group?: string;
+	score?: number;
+}
+
+export interface TodoState {
+	todos: TodoItem[];
+	plan: TodoPlan;
+	goals: TodoGoal[];
+}
+
+export type TodoPlanField = "user_intention" | "understands_user_intent";
+export interface TodoPlanChange {
+	before?: TodoPlan;
+	after?: TodoPlan;
+	fields: TodoPlanField[];
+}
+
+export type TodoGoalField = "closed_feedback_loop" | "feedback_loop" | "end_to_end_ownership";
+export interface TodoGoalChange {
+	before?: TodoGoal;
+	after?: TodoGoal;
+	fields: TodoGoalField[];
+}
+
+export interface TodoDetails extends TodoState {
+	operation: "read" | "write" | "rejected";
+	/** One-line applied-change digest, set on accepted writes that changed
+	 *  something: "2 updated; 1 new; removed #x; group cleared on #y". */
+	item_changes?: string;
+	plan_update?: TodoPlanChange;
+	goal_updates?: TodoGoalChange[];
+}
+
+export function defaultState(): TodoState {
+	return {
+		todos: [],
+		plan: { understands_user_intent_history: [] },
+		goals: [],
+	};
+}
+
+/** Normalized group label: trimmed, empty/whitespace -> undefined (implicit goal). */
+export function goalGroupKey(group: string | undefined | null): string | undefined {
+	if (group === undefined || group === null) return undefined;
+	const trimmed = group.trim();
+	return trimmed.length > 0 ? trimmed : undefined;
+}
+
+export function planIsDefault(plan: TodoPlan): boolean {
+	return (
+		plan.user_intention === undefined &&
+		plan.understands_user_intent === undefined &&
+		plan.understands_user_intent_history.length === 0
+	);
+}
+
+// ----------------------------------------------------------------------------
+// Sanitizers (defensive: details replayed from session JSON may be partial)
+// ----------------------------------------------------------------------------
+
+function numArray(value: unknown): number[] {
+	return Array.isArray(value) ? value.filter((v): v is number => typeof v === "number") : [];
+}
+
+export function sanitizeItem(raw: unknown): TodoItem | undefined {
+	if (typeof raw !== "object" || raw === null) return undefined;
+	const r = raw as Record<string, unknown>;
+	if (typeof r.id !== "string" && typeof r.id !== "number") return undefined;
+	const item: TodoItem = {
+		id: String(r.id),
+		content: typeof r.content === "string" ? r.content : "",
+		status: typeof r.status === "string" ? r.status : "pending",
+		priority: typeof r.priority === "string" ? r.priority : "medium",
+		confidence_history: numArray(r.confidence_history),
+
+	};
+	if (typeof r.group === "string") item.group = r.group;
+	if (typeof r.confidence === "number") item.confidence = r.confidence;
+	if (typeof r.completion_confidence === "number") item.completion_confidence = r.completion_confidence;
+	return item;
+}
+
+export function sanitizeState(raw: unknown): TodoState | undefined {
+	if (typeof raw !== "object" || raw === null) return undefined;
+	const r = raw as Record<string, unknown>;
+	if (!Array.isArray(r.todos)) return undefined;
+	const todos = r.todos.map(sanitizeItem).filter((t): t is TodoItem => t !== undefined);
+
+	const plan: TodoPlan = { understands_user_intent_history: [] };
+	if (typeof r.plan === "object" && r.plan !== null) {
+		const p = r.plan as Record<string, unknown>;
+		if (typeof p.user_intention === "string") plan.user_intention = p.user_intention;
+		if (typeof p.understands_user_intent === "number")
+			plan.understands_user_intent = p.understands_user_intent;
+		plan.understands_user_intent_history = numArray(p.understands_user_intent_history);
+	}
+
+	const goals: TodoGoal[] = [];
+	if (Array.isArray(r.goals)) {
+		for (const g of r.goals) {
+			if (typeof g !== "object" || g === null) continue;
+			const gr = g as Record<string, unknown>;
+			const goal: TodoGoal = {
+				closed_feedback_loop_history: numArray(gr.closed_feedback_loop_history),
+				end_to_end_ownership_history: numArray(gr.end_to_end_ownership_history),
+			};
+			if (typeof gr.group === "string") goal.group = gr.group;
+			if (typeof gr.closed_feedback_loop === "number") goal.closed_feedback_loop = gr.closed_feedback_loop;
+			if (typeof gr.feedback_loop === "string") goal.feedback_loop = gr.feedback_loop;
+			if (typeof gr.end_to_end_ownership === "number") goal.end_to_end_ownership = gr.end_to_end_ownership;
+			goals.push(goal);
+		}
+	}
+	return { todos, plan, goals };
+}

package/src/normalize.ts

@@ -0,0 +1,122 @@
+/**
+ * Lenient input normalization — port of jcode-app-core's
+ * normalize_todo_input (issue #357). Runs in the tool's prepareArguments
+ * hook, before schema validation.
+ *
+ * Some providers intermittently emit tool arguments as JSON *strings*
+ * instead of native types: the whole `todos` array as one stringified JSON
+ * blob, individual items as stringified objects, or numeric fields like
+ * `confidence` as "90". Strict validation would reject these, failing the
+ * entire call. Legacy aliases (hill_climbability, alignment_score,
+ * user_intention_alignment) are accepted at runtime but never advertised.
+ */
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Coerce a numeric string ("90") or whole float (90.0) to an integer, and
+ *  an empty string to null. Anything else passes through unchanged. */
+function coerceValueToInteger(value: unknown): unknown {
+	if (typeof value === "string") {
+		const trimmed = value.trim();
+		if (trimmed === "") return null;
+		if (/^\d+$/.test(trimmed)) return Number.parseInt(trimmed, 10);
+		return value;
+	}
+	if (typeof value === "number" && !Number.isInteger(value)) {
+		if (Number.isFinite(value) && value >= 0 && Number.isSafeInteger(Math.trunc(value))) {
+			return Math.trunc(value);
+		}
+	}
+	return value;
+}
+
+function parseJsonIf(value: unknown, shape: "object" | "array"): unknown {
+	if (typeof value !== "string") return value;
+	const trimmed = value.trim();
+	if (trimmed === "") return null;
+	try {
+		const parsed = JSON.parse(trimmed);
+		if (parsed === null) return null;
+		if (shape === "object" && isPlainObject(parsed)) return parsed;
+		if (shape === "array" && Array.isArray(parsed)) return parsed;
+		return value;
+	} catch {
+		return value;
+	}
+}
+
+const PLAN_SCORE_ALIASES = ["alignment_score", "user_intention_alignment"];
+const GOAL_LOOP_ALIASES = ["hill_climbability"];
+
+const NUMERIC_ITEM_KEYS = [
+	"confidence",
+	"completion_confidence",
+	"closed_feedback_loop",
+	"hill_climbability",
+	"alignment_score",
+	"user_intention_alignment",
+	"end_to_end_ownership",
+];
+
+function adoptAlias(
+	fields: Record<string, unknown>,
+	target: string,
+	aliases: string[],
+): void {
+	if (typeof fields[target] === "number" && Number.isInteger(fields[target])) return;
+	for (const alias of aliases) {
+		const v = fields[alias];
+		if (typeof v === "number" && Number.isInteger(v)) {
+			fields[target] = v;
+			return;
+		}
+	}
+}
+
+/** Normalize raw todo-tool arguments; returns a fresh object (never mutates). */
+export function normalizeTodoInput(raw: unknown): unknown {
+	if (!isPlainObject(raw)) return raw;
+	const input = JSON.parse(JSON.stringify(raw)) as Record<string, unknown>;
+
+	// plan: stringified object or "" -> absent
+	if ("plan" in input) {
+		input.plan = parseJsonIf(input.plan, "object");
+		if (input.plan === null) {
+			delete input.plan;
+		} else if (isPlainObject(input.plan)) {
+			const plan = input.plan;
+			for (const key of [...PLAN_SCORE_ALIASES, "understands_user_intent"]) {
+				if (key in plan) plan[key] = coerceValueToInteger(plan[key]);
+			}
+			adoptAlias(plan, "understands_user_intent", PLAN_SCORE_ALIASES);
+			for (const alias of PLAN_SCORE_ALIASES) delete plan[alias];
+		}
+	}
+
+	for (const key of ["todos", "goals"]) {
+		if (!(key in input)) continue;
+		const entries = parseJsonIf(input[key], "array");
+		if (entries === null) {
+			delete input[key];
+			continue;
+		}
+		if (!Array.isArray(entries)) continue;
+		input[key] = entries.map((item) => {
+			const parsed = parseJsonIf(item, "object");
+			if (!isPlainObject(parsed)) return parsed;
+			for (const numKey of NUMERIC_ITEM_KEYS) {
+				if (numKey in parsed) parsed[numKey] = coerceValueToInteger(parsed[numKey]);
+			}
+			if (key === "goals") {
+				// serde(alias) equivalent: pre-rename keys still load, but the
+				// advertised schema only knows the new names.
+				adoptAlias(parsed, "closed_feedback_loop", GOAL_LOOP_ALIASES);
+				for (const alias of GOAL_LOOP_ALIASES) delete parsed[alias];
+			}
+			return parsed;
+		});
+	}
+	return input;
+}

package/src/schema.ts

@@ -0,0 +1,101 @@
+/**
+ * Tool parameter schema — field names, required arrays, and description
+ * texts verbatim from jcode-app-core/src/tool/todo.rs::parameters_schema().
+ * The descriptions are handwritten model-visible calibration text: they
+ * never mention thresholds, gate wording, scores, or domain hints.
+ */
+
+import { type Static, Type } from "typebox";
+
+export const TodoItemSchema = Type.Object({
+	content: Type.String({ description: "Task." }),
+	status: Type.String({ description: "Status." }),
+	priority: Type.String({ description: "Priority." }),
+	id: Type.String({ description: "ID." }),
+	group: Type.Optional(
+		Type.String({
+			description:
+				"Optional group label, encouraged. Prefer a group whenever the task has more than one step: todos sharing a group render together under one header, so use one group per coherent goal (e.g. 'optimize rendering'), and start a new group instead of renaming the existing one when the user steers into new work. Omit only for a one-off flat list (ungrouped items share one implicit goal and its checks). On update-style writes, omitting this field keeps the item's existing group — send an empty string to clear it.",
+		}),
+	),
+	confidence: Type.Integer({
+		minimum: 0,
+		maximum: 100,
+		description:
+			"Self-assessed confidence, 0-100, that this todo can be completed correctly. Reassess it as evidence accumulates while working.",
+	}),
+	completion_confidence: Type.Optional(
+		Type.Integer({
+			minimum: 0,
+			maximum: 100,
+			description:
+				"Self-assessed confidence, 0-100, that this todo was completed correctly. Use only for completed items. On later writes, omitting this field keeps the stored value for this id.",
+		}),
+	),
+});
+
+export const TodoPlanInputSchema = Type.Object(
+	{
+		user_intention: Type.String({
+			description:
+				"Concise statement of what the user actually wants: their underlying reason and desired end state for this work. Omit on later updates to retain the stored intention.",
+		}),
+		understands_user_intent: Type.Integer({
+			minimum: 0,
+			maximum: 100,
+			description:
+				"Self-assessment, 0-100, of how well you understand what the user actually wants and how faithfully this plan represents it: their underlying goal, what they left implicit, and what outcome would make them consider this done. Before scoring, form a requirement inventory covering outcomes, deliverables, constraints, prohibited actions, integration paths, edge cases, and necessary follow-through, and check that the plan and its feedback loops name an explicit observation or check for each item. A generic instruction to run tests, verify, or review does not establish coverage: tests count only for behaviors they actually enforce, while non-testable requirements such as edit scope, dependency limits, required reporting, branches or commits, and prohibited modifications need separate explicit checks. Score low when interpretations of the request still materially diverge, you are guessing at intent, or any material item is unrepresented. Prefer resolving low understanding by re-reading the request and investigating the conversation and codebase over asking the user, since asking blocks them.",
+		}),
+	},
+	{
+		description:
+			"Plan-level understanding of the user's request, covering the whole todo list. Send it on the first write and whenever your understanding changes.",
+	},
+);
+
+export const TodoGoalSchema = Type.Object({
+	group: Type.Optional(
+		Type.String({
+			description: "Group label this goal describes. Omit or null for the ungrouped list.",
+		}),
+	),
+	closed_feedback_loop: Type.Integer({
+		minimum: 0,
+		maximum: 100,
+		description:
+			"Self-assessment, 0-100: how much of this goal's correctness the `feedback_loop` below can tell you on its own, without your judgment or the user's.",
+	}),
+	feedback_loop: Type.String({
+		description:
+			"Concrete requirement-to-check process used to compare progress across iterations and detect whether the user's intention is satisfied or violated. Name an explicit observation or check for every material behavior, deliverable, constraint, prohibited action, integration path, edge case, and necessary follow-through. Generic phrases such as run tests, verify, or review count only for requirements those named checks demonstrably enforce; add separate checks for non-testable prompt requirements.",
+	}),
+	end_to_end_ownership: Type.Optional(
+		Type.Integer({
+			minimum: 0,
+			maximum: 100,
+			description:
+				"Completion-time self-assessment, 0-100, of whether the full intended user outcome and its necessary follow-through were delivered, rather than only the immediate implementation. Use only when completing the goal.",
+		}),
+	),
+});
+
+export const TodoParams = Type.Object({
+	todos: Type.Optional(
+		Type.Array(TodoItemSchema, {
+			description:
+				"Todo list to save. Replaces the stored list when present: re-list every item (omitting one deletes it), but only re-type fields you are changing — optional fields you omit on an existing id are inherited. To read or keep the current list, omit the field entirely — never send an empty array unless you intend to clear every todo.",
+		}),
+	),
+	plan: Type.Optional(TodoPlanInputSchema),
+	goals: Type.Optional(
+		Type.Array(TodoGoalSchema, {
+			description:
+				"Optional goal-level assessments, one per todo group. Use group: null for an ungrouped list. Stored assessments for groups omitted from an update are retained.",
+		}),
+	),
+});
+
+export type TodoParamsInput = Static<typeof TodoParams>;
+export type TodoItemInput = Static<typeof TodoItemSchema>;
+export type TodoPlanInput = Static<typeof TodoPlanInputSchema>;
+export type TodoGoalInput = Static<typeof TodoGoalSchema>;

package/src/viewer.ts

@@ -0,0 +1,136 @@
+/**
+ * /todos TUI viewer — a read-only overlay component showing the current
+ * branch's todo state. Rendering chrome is pi-local (jcode's own TUI todo
+ * view is a different design); the content mirrors the stored state.
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
+import type { TodoState } from "./model.js";
+
+export class TodoListComponent {
+	private state: TodoState;
+	private armed: boolean;
+	private theme: Theme;
+	private onClose: () => void;
+	private cachedWidth?: number;
+	private cachedLines?: string[];
+
+	constructor(state: TodoState, armed: boolean, theme: Theme, onClose: () => void) {
+		this.state = state;
+		this.armed = armed;
+		this.theme = theme;
+		this.onClose = onClose;
+	}
+
+	handleInput(data: string): void {
+		if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) {
+			this.onClose();
+		}
+	}
+
+	render(width: number): string[] {
+		if (this.cachedLines && this.cachedWidth === width) return this.cachedLines;
+		const th = this.theme;
+		const lines: string[] = [""];
+		lines.push(
+			truncateToWidth(
+				th.fg("borderMuted", "─".repeat(3)) +
+					th.fg("accent", " Todos ") +
+					th.fg("borderMuted", "─".repeat(Math.max(0, width - 10))),
+				width,
+			),
+		);
+		lines.push("");
+
+		const total = this.state.todos.length;
+		const completed = this.state.todos.filter((t) => t.status === "completed").length;
+		const cancelled = this.state.todos.filter((t) => t.status === "cancelled").length;
+		const inProgress = this.state.todos.filter((t) => t.status === "in_progress").length;
+		const pending = total - completed - cancelled - inProgress;
+		const percent = total === 0 ? 0 : Math.round(((completed + cancelled) / total) * 100);
+		lines.push(truncateToWidth(`  ${completed + cancelled}/${total} settled (${percent}%)`, width));
+		if (inProgress) lines.push(truncateToWidth(`  ${inProgress} in progress`, width));
+		if (pending) lines.push(truncateToWidth(`  ${pending} pending`, width));
+		if (cancelled) lines.push(truncateToWidth(`  ${cancelled} cancelled`, width));
+		lines.push(truncateToWidth(`  ${th.fg("dim", `auto-poke: ${this.armed ? "on" : "off"}`)}`, width));
+
+		if (this.state.plan.user_intention) {
+			lines.push("");
+			lines.push(
+				truncateToWidth(`  ${th.fg("muted", "Intention:")} ${this.state.plan.user_intention}`, width),
+			);
+		}
+
+		if (total === 0) {
+			lines.push("");
+			lines.push(truncateToWidth(`  ${th.fg("dim", "No todos yet.")}`, width));
+		} else {
+			lines.push("");
+			for (const todo of this.state.todos) {
+				let icon: string;
+				let color: "success" | "error" | "accent" | "dim";
+				switch (todo.status) {
+					case "completed":
+						icon = "✓";
+						color = "success";
+						break;
+					case "cancelled":
+						icon = "✗";
+						color = "error";
+						break;
+					case "in_progress":
+						icon = "▶";
+						color = "accent";
+						break;
+					default:
+						icon = "○";
+						color = "dim";
+				}
+				let text = todo.content;
+				if (todo.status === "completed" || todo.status === "cancelled") {
+					text = th.fg("dim", text);
+				}
+				const group = todo.group ? th.fg("muted", `[${todo.group}] `) : "";
+				lines.push(
+					truncateToWidth(
+						`  ${th.fg(color, icon)} ${th.fg("accent", `#${todo.id}`)} ${group}${text}`,
+						width,
+					),
+				);
+			}
+		}
+
+		if (this.state.goals.length) {
+			lines.push("");
+			lines.push(truncateToWidth(`  ${th.fg("muted", "Goals:")}`, width));
+			for (const goal of this.state.goals) {
+				const g = goal.group ?? "(ungrouped)";
+				const loop = goal.feedback_loop ? ` – ${goal.feedback_loop}` : "";
+				const ownership =
+					goal.end_to_end_ownership !== undefined
+						? ` [ownership ${goal.end_to_end_ownership}]`
+						: "";
+				lines.push(
+					truncateToWidth(
+						`    ${th.fg("accent", g)}${th.fg("dim", loop)}${th.fg("dim", ownership)}`,
+						width,
+					),
+				);
+			}
+		}
+
+		lines.push("");
+		lines.push(truncateToWidth(`  ${th.fg("dim", "Press Escape to close")}`, width));
+		lines.push("");
+
+		this.cachedWidth = width;
+		this.cachedLines = lines;
+		return lines;
+	}
+
+	invalidate(): void {
+		this.cachedWidth = undefined;
+		this.cachedLines = undefined;
+	}
+}

package/src/watchdog.ts

@@ -0,0 +1,71 @@
+/**
+ * Idle starvation watchdog — the liveness half of pi-simple-goal's watchdog,
+ * applied to the todo auto-poke cycle (jcode's queued-followup starvation
+ * watchdog, QUEUED_FOLLOWUP_STARVATION_TIMEOUT, is the same idea).
+ *
+ * Model: while auto-poke is armed and todos remain open, the agent should
+ * NEVER sit idle for long — the turn-end machine pokes at every settle, so
+ * a long quiet period means the follow-up was lost (dispatch consumed, run
+ * never started, provider died silently). A periodic tick detects that
+ * state and re-fires the poke, with a small cap so a truly wedged session
+ * disarms instead of looping. Any real activity (agent start, turn end,
+ * user input, our own successful send) postpones the fire window, and a
+ * user abort (Esc) disarms the whole cycle via the normal path.
+ */
+
+export interface WatchdogDeps {
+	now: () => number;
+	isArmed: () => boolean;
+	isIdle: () => boolean;
+	incompleteCount: () => number;
+	wasAborted: () => boolean;
+	idleMs: number;
+	maxRePokes: number;
+	/** Re-send the auto-poke follow-up (fire-and-forget is fine). */
+	onFire: (consecutiveRePokes: number) => void;
+	/** Cap reached or abort races in: stop the cycle (`disarm` + notice). */
+	onStarve: (reason: "cap" | "aborted") => void;
+}
+
+export interface Watchdog {
+	tick: () => void;
+	notifyActivity: () => void;
+	/** Consecutive re-pokes with no real activity; exposed for tests. */
+	getRePokes: () => number;
+}
+
+export function createWatchdog(deps: WatchdogDeps): Watchdog {
+	let lastActivity = deps.now();
+	let rePokes = 0;
+	return {
+		notifyActivity() {
+			lastActivity = deps.now();
+			rePokes = 0;
+		},
+		getRePokes: () => rePokes,
+		tick() {
+			const now = deps.now();
+			if (!deps.isArmed() || !deps.isIdle()) {
+				lastActivity = now;
+				return;
+			}
+			if (deps.incompleteCount() === 0) {
+				lastActivity = now;
+				rePokes = 0;
+				return;
+			}
+			if (now - lastActivity < deps.idleMs) return;
+			lastActivity = now; // one shot per window regardless of outcome
+			if (deps.wasAborted()) {
+				deps.onStarve("aborted");
+				return;
+			}
+			if (rePokes >= deps.maxRePokes) {
+				deps.onStarve("cap");
+				return;
+			}
+			rePokes += 1;
+			deps.onFire(rePokes);
+		},
+	};
+}