@hheei/pi-todo 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hheei
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,42 @@
-# Temporary Holding Version
+# @hheei/pi-todo
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Todo task tracking for Pi. Owns the `todo` tool, the `/todo` command, task scheduling,
+hidden reminders, and the left-side footer status line.
+
+Install `@hheei/pi-settings` separately for the Settings UI. `@hheei/pi-ext-core` is a
+production dependency, not a separately loaded Pi extension.
+
+## Tool
+
+`todo({ operations })` applies an ordered, atomic batch of `create`, `update`, `list`, and
+`delete` operations. The whole batch is validated on a candidate state before anything is
+committed, so a rejected operation reports `No change made.` and leaves the live state
+untouched.
+
+- Exactly one task is `in_progress`; the active task is always set for you.
+- Starting a pending or blocked task demotes the previous active task to `pending`.
+- `completed` is terminal; create a new task to redo work.
+- `blocked` tasks stay visible but drive no guidance or reminder.
+
+The tool registers with `defaultActive: false`. Enable it through the Pi host's active tool
+set; the extension only starts its runtime, reminders, and footer when `todo` is active.
+
+## Command
+
+`/todo` shows active and recent tasks, `/todo list` shows every task, `/todo clear` resets
+the list and ids, and `/todo cancel #ID...` atomically suppresses tasks (advancing to the
+next pending task when the active one is cancelled). Cancelled tasks cannot be modified by
+the agent.
+
+## Footer status
+
+The footer status key is `pi-ext-tools:todo`. A recently completed task wins for 15s when later work is
+queued and 3 minutes otherwise, then the `in_progress` task, then the first pending task,
+then a recently blocked task for 15s. No visible task clears the status entirely.
+
+## Persistence
+
+Session state restores from the current branch: the newest `todo` tool result snapshot, or
+the `pi-ext-tools:todo:state` custom entry written by `/todo clear` and `/todo cancel`.
+Both forms are validated before use. Session tree navigation restores the branch state and
+refreshes the footer.

package/dist/extension.d.ts

@@ -0,0 +1,3 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+/** Registers the todo tool, /todo command, reminders, and footer status line. */
+export default function piTodoExtension(pi: ExtensionAPI): void;

package/dist/extension.js

@@ -0,0 +1,18 @@
+import { registerExtensionLifecycle } from "@hheei/pi-ext-core";
+import { createTodoFeature, TODO_TOOL_NAME } from "./todo.js";
+/** Registers the todo tool, /todo command, reminders, and footer status line. */
+export default function piTodoExtension(pi) {
+    const todo = createTodoFeature(pi);
+    registerExtensionLifecycle(pi, {
+        key: "@hheei/pi-todo",
+        start: async ({ extension, resources, signal }) => {
+            // The tool stays defaultActive: false, so its runtime, reminders, and footer only
+            // exist when the Pi host's active tool set already contains `todo`.
+            if (!pi.getActiveTools().includes(TODO_TOOL_NAME))
+                return;
+            await todo.start(extension, signal);
+            const sessionId = extension.sessionManager.getSessionId();
+            resources.add("todo", () => todo.dispose(sessionId));
+        },
+    });
+}

package/dist/footer-status.d.ts

@@ -0,0 +1,24 @@
+import type { ExtensionUIContext, Theme } from "@earendil-works/pi-coding-agent";
+import { type TaskState } from "./model.js";
+export declare const TODO_STATUS_KEY = "pi-ext-tools:todo";
+export declare const COMPLETED_DISPLAY_DURATION_MS: number;
+export declare const COMPLETED_WITH_SUBSEQUENT_DURATION_MS: number;
+export declare const BLOCKED_DISPLAY_DURATION_MS: number;
+export interface FooterStatusDecision {
+    readonly text: string | undefined;
+    readonly expiresAt?: number;
+}
+/**
+ * Footer text for the current task state, plus when that text expires.
+ *
+ * An in-progress task wins, then a recently completed one, then pending, then recently
+ * blocked; with no in-progress task a recent completion and a recent block compete on
+ * recency. A completion stays visible for `COMPLETED_WITH_SUBSEQUENT_DURATION_MS` when
+ * work is already queued behind it, otherwise for `COMPLETED_DISPLAY_DURATION_MS`.
+ */
+export declare function computeFooterStatus(state: TaskState, theme: Theme, now?: number): FooterStatusDecision;
+export interface TodoFooterStatusController {
+    update(state: TaskState): void;
+    dispose(): void;
+}
+export declare function createTodoFooterStatusController(ui: Pick<ExtensionUIContext, "setStatus" | "theme">, signal?: AbortSignal, now?: () => number): TodoFooterStatusController;

package/dist/footer-status.js

@@ -0,0 +1,111 @@
+import { TASK_GLYPH, TASK_TONE } from "./model.js";
+export const TODO_STATUS_KEY = "pi-ext-tools:todo";
+export const COMPLETED_DISPLAY_DURATION_MS = 3 * 60 * 1000; // 3 minutes
+export const COMPLETED_WITH_SUBSEQUENT_DURATION_MS = 15 * 1000; // 15 seconds
+export const BLOCKED_DISPLAY_DURATION_MS = 15 * 1000; // 15 seconds
+/** Most recently updated task in `status` whose update is still inside `window`. */
+function mostRecent(tasks, status, window, now) {
+    let newest;
+    for (const task of tasks) {
+        if (task.status !== status || task.updatedAt === undefined)
+            continue;
+        if (now - task.updatedAt >= window)
+            continue;
+        if (newest === undefined || task.updatedAt >= (newest.updatedAt ?? 0))
+            newest = task;
+    }
+    return newest;
+}
+function formatTaskStatus(task, theme) {
+    const tone = TASK_TONE[task.status];
+    const subject = task.subject.trim();
+    const styledSubject = tone === "dim" || tone === "success" ? theme.fg("dim", subject) : theme.fg("text", subject);
+    return `${theme.fg(tone, TASK_GLYPH[task.status])} ${theme.fg("accent", `#${task.id}`)} ${styledSubject}`;
+}
+/**
+ * Footer text for the current task state, plus when that text expires.
+ *
+ * An in-progress task wins, then a recently completed one, then pending, then recently
+ * blocked; with no in-progress task a recent completion and a recent block compete on
+ * recency. A completion stays visible for `COMPLETED_WITH_SUBSEQUENT_DURATION_MS` when
+ * work is already queued behind it, otherwise for `COMPLETED_DISPLAY_DURATION_MS`.
+ */
+export function computeFooterStatus(state, theme, now = Date.now()) {
+    const inProgress = state.tasks.find((task) => task.status === "in_progress");
+    const completedDuration = inProgress
+        ? COMPLETED_WITH_SUBSEQUENT_DURATION_MS
+        : COMPLETED_DISPLAY_DURATION_MS;
+    const recentCompleted = mostRecent(state.tasks, "completed", completedDuration, now);
+    const recentBlocked = mostRecent(state.tasks, "blocked", BLOCKED_DISPLAY_DURATION_MS, now);
+    if (!inProgress && recentCompleted && recentBlocked) {
+        const completedTime = recentCompleted.updatedAt ?? 0;
+        const blockedTime = recentBlocked.updatedAt ?? 0;
+        if (completedTime >= blockedTime) {
+            return {
+                text: formatTaskStatus(recentCompleted, theme),
+                expiresAt: completedTime + COMPLETED_DISPLAY_DURATION_MS,
+            };
+        }
+        return {
+            text: formatTaskStatus(recentBlocked, theme),
+            expiresAt: blockedTime + BLOCKED_DISPLAY_DURATION_MS,
+        };
+    }
+    if (recentCompleted) {
+        return {
+            text: formatTaskStatus(recentCompleted, theme),
+            expiresAt: (recentCompleted.updatedAt ?? 0) + completedDuration,
+        };
+    }
+    if (inProgress) {
+        return { text: formatTaskStatus(inProgress, theme) };
+    }
+    const pending = state.tasks.find((task) => task.status === "pending");
+    if (pending) {
+        return { text: formatTaskStatus(pending, theme) };
+    }
+    if (recentBlocked) {
+        return {
+            text: formatTaskStatus(recentBlocked, theme),
+            expiresAt: (recentBlocked.updatedAt ?? 0) + BLOCKED_DISPLAY_DURATION_MS,
+        };
+    }
+    return { text: undefined };
+}
+export function createTodoFooterStatusController(ui, signal, now = () => Date.now()) {
+    let currentTimer;
+    let isDisposed = false;
+    const clearTimer = () => {
+        if (currentTimer !== undefined)
+            clearTimeout(currentTimer);
+        currentTimer = undefined;
+    };
+    /** Renders the state, and re-renders when text that is only shown for a while expires. */
+    const scheduleNext = (state) => {
+        clearTimer();
+        const decision = computeFooterStatus(state, ui.theme, now());
+        ui.setStatus(TODO_STATUS_KEY, decision.text);
+        if (decision.expiresAt !== undefined) {
+            currentTimer = setTimeout(() => scheduleNext(state), decision.expiresAt - now());
+        }
+    };
+    const dispose = () => {
+        if (isDisposed)
+            return;
+        isDisposed = true;
+        clearTimer();
+        ui.setStatus(TODO_STATUS_KEY, undefined);
+    };
+    if (signal?.aborted === true)
+        dispose();
+    else
+        signal?.addEventListener("abort", dispose, { once: true });
+    return {
+        update(state) {
+            if (isDisposed)
+                return;
+            scheduleNext(state);
+        },
+        dispose,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { default } from "./extension.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { default } from "./extension.js";

package/dist/model.d.ts

@@ -0,0 +1,83 @@
+export type TaskStatus = "pending" | "in_progress" | "blocked" | "completed" | "suppressed";
+export type AgentTaskStatus = "pending" | "in_progress" | "blocked" | "completed";
+/** How each status is drawn wherever a task is rendered: glyph plus semantic tone. */
+export declare const TASK_GLYPH: Record<TaskStatus, string>;
+export declare const TASK_TONE: Record<TaskStatus, "success" | "warning" | "dim" | "muted">;
+export type TodoAction = "create" | "update" | "list" | "delete";
+export interface Task {
+    readonly id: number;
+    readonly subject: string;
+    readonly status: TaskStatus;
+    readonly updatedAt?: number;
+}
+export interface TaskState {
+    readonly tasks: readonly Task[];
+    readonly nextId: number;
+}
+export type TodoOperation = {
+    readonly action: "create";
+    readonly subject: string;
+    readonly status?: AgentTaskStatus;
+} | {
+    readonly action: "update";
+    readonly id: number;
+    readonly subject?: string;
+    readonly status?: AgentTaskStatus;
+} | {
+    readonly action: "list";
+    readonly status?: TaskStatus;
+} | {
+    readonly action: "delete";
+    readonly id: number;
+};
+export interface TodoParams {
+    readonly operations: readonly TodoOperation[];
+}
+export interface TodoOperationResult {
+    readonly index: number;
+    readonly action: TodoAction;
+    readonly changed: boolean;
+    readonly id?: number;
+}
+export type ApplyTodoResult = {
+    readonly ok: true;
+    readonly changed: boolean;
+    readonly state: TaskState;
+    readonly operations: readonly TodoOperationResult[];
+} | {
+    readonly ok: false;
+    readonly state: TaskState;
+    readonly error: string;
+    readonly operationIndex?: number;
+};
+export declare function freshTaskState(): TaskState;
+export declare function validateTaskState(value: unknown): TaskState | undefined;
+export declare function isValidTimestamp(now: unknown): now is number;
+export declare function activateFirstPending(state: TaskState, now?: number): TaskState;
+/**
+ * Applies a tool batch as one transaction. Every operation mutates only `draft`;
+ * any validation or transition failure returns the original state, so callers
+ * can safely render "No change made" without compensating partial writes.
+ */
+export declare function applyTodo(state: TaskState, params: TodoParams, now?: number): ApplyTodoResult;
+export type CancelTodosResult = {
+    readonly ok: true;
+    readonly changed: boolean;
+    readonly state: TaskState;
+    readonly cancelledIds: readonly number[];
+} | {
+    readonly ok: false;
+    readonly state: TaskState;
+    readonly error: string;
+};
+export declare function cancelTodosByUser(state: TaskState, ids: readonly number[], now?: number): CancelTodosResult;
+export type SuppressTodoResult = {
+    readonly ok: true;
+    readonly changed: boolean;
+    readonly state: TaskState;
+} | {
+    readonly ok: false;
+    readonly state: TaskState;
+    readonly error: string;
+};
+export declare function suppressTodoByUser(state: TaskState, id: number, now?: number): SuppressTodoResult;

package/dist/model.js

@@ -0,0 +1,342 @@
+import { isRecord } from "@hheei/pi-ext-core";
+/** How each status is drawn wherever a task is rendered: glyph plus semantic tone. */
+export const TASK_GLYPH = {
+    in_progress: "󰪠",
+    pending: "󰄰",
+    blocked: "󰀪",
+    completed: "󰄴",
+    suppressed: "󰅚",
+};
+export const TASK_TONE = {
+    in_progress: "warning",
+    pending: "muted",
+    blocked: "dim",
+    completed: "success",
+    suppressed: "muted",
+};
+export function freshTaskState() {
+    return { tasks: [], nextId: 1 };
+}
+const STATUSES = [
+    "pending",
+    "in_progress",
+    "blocked",
+    "completed",
+    "suppressed",
+];
+const ACTIONS = ["create", "update", "list", "delete"];
+function subjectError(subject) {
+    if (subject.trim() === "")
+        return "Subject must not be empty";
+    for (const character of subject) {
+        const codePoint = character.codePointAt(0) ?? 0;
+        if (codePoint <= 0x1f ||
+            (codePoint >= 0x7f && codePoint <= 0x9f) ||
+            codePoint === 0x2028 ||
+            codePoint === 0x2029)
+            return "Subject must be one printable line";
+    }
+    return undefined;
+}
+function isPositiveInteger(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+function isAgentTaskStatus(value) {
+    return (value === "pending" || value === "in_progress" || value === "blocked" || value === "completed");
+}
+function hasOnlyKeys(value, keys) {
+    return Object.keys(value).every((key) => keys.includes(key));
+}
+function cloneState(state) {
+    return {
+        tasks: [...state.tasks],
+        nextId: state.nextId,
+    };
+}
+export function validateTaskState(value) {
+    if (!isRecord(value) || !Array.isArray(value.tasks) || !isPositiveInteger(value.nextId))
+        return undefined;
+    const ids = new Set();
+    const tasks = [];
+    for (const valueTask of value.tasks) {
+        if (!isRecord(valueTask) || !isPositiveInteger(valueTask.id) || ids.has(valueTask.id))
+            return undefined;
+        if (typeof valueTask.subject !== "string" || subjectError(valueTask.subject))
+            return undefined;
+        if (!STATUSES.includes(valueTask.status))
+            return undefined;
+        if (valueTask.updatedAt !== undefined &&
+            (typeof valueTask.updatedAt !== "number" ||
+                !Number.isFinite(valueTask.updatedAt) ||
+                valueTask.updatedAt < 0)) {
+            return undefined;
+        }
+        ids.add(valueTask.id);
+        tasks.push({
+            id: valueTask.id,
+            subject: valueTask.subject,
+            status: valueTask.status,
+            ...(valueTask.updatedAt !== undefined ? { updatedAt: valueTask.updatedAt } : {}),
+        });
+    }
+    const maxId = tasks.reduce((max, task) => Math.max(max, task.id), 0);
+    if (value.nextId <= maxId || tasks.filter((task) => task.status === "in_progress").length > 1)
+        return undefined;
+    return { tasks, nextId: value.nextId };
+}
+function findTask(tasks, id) {
+    return tasks.find((task) => task.id === id);
+}
+function firstPending(tasks) {
+    return tasks
+        .filter((task) => task.status === "pending")
+        .sort((left, right) => left.id - right.id)[0];
+}
+export function isValidTimestamp(now) {
+    return typeof now === "number" && Number.isFinite(now) && now >= 0;
+}
+export function activateFirstPending(state, now) {
+    if (state.tasks.some((task) => task.status === "in_progress"))
+        return state;
+    const next = firstPending(state.tasks);
+    if (!next)
+        return state;
+    const timestamp = isValidTimestamp(now) ? Math.floor(now) : undefined;
+    return {
+        tasks: state.tasks.map((task) => task.id === next.id
+            ? {
+                ...task,
+                status: "in_progress",
+                ...(timestamp !== undefined ? { updatedAt: timestamp } : {}),
+            }
+            : task),
+        nextId: state.nextId,
+    };
+}
+/**
+ * Applies a tool batch as one transaction. Every operation mutates only `draft`;
+ * any validation or transition failure returns the original state, so callers
+ * can safely render "No change made" without compensating partial writes.
+ */
+export function applyTodo(state, params, now) {
+    if (now !== undefined && !isValidTimestamp(now)) {
+        return { ok: false, state, error: "Invalid timestamp" };
+    }
+    const timestamp = now !== undefined ? Math.floor(now) : undefined;
+    if (!isRecord(params) || !Array.isArray(params.operations) || params.operations.length === 0) {
+        return { ok: false, state, error: "operations must be a non-empty array" };
+    }
+    if (!validateTaskState(state))
+        return { ok: false, state, error: "Invalid task state" };
+    const draft = cloneState(state);
+    const operations = [];
+    let changed = false;
+    const fail = (error, operationIndex) => ({
+        ok: false,
+        state,
+        error,
+        operationIndex,
+    });
+    for (let index = 0; index < params.operations.length; index++) {
+        const operation = params.operations[index];
+        if (!isRecord(operation) ||
+            typeof operation.action !== "string" ||
+            !ACTIONS.includes(operation.action))
+            return fail("Invalid action", index);
+        const action = operation.action;
+        if (action === "list") {
+            if (params.operations.length !== 1 ||
+                !hasOnlyKeys(operation, ["action", "status"]) ||
+                (operation.status !== undefined && !STATUSES.includes(operation.status)))
+                return fail("Invalid list operation", index);
+            operations.push({ index, action, changed: false });
+            continue;
+        }
+        if (action === "create") {
+            if (!hasOnlyKeys(operation, ["action", "subject", "status"]) ||
+                typeof operation.subject !== "string")
+                return fail("Invalid create fields", index);
+            const subjectIssue = subjectError(operation.subject);
+            if (subjectIssue)
+                return fail(subjectIssue, index);
+            if (operation.status !== undefined && !isAgentTaskStatus(operation.status))
+                return fail("Invalid status", index);
+            const subject = operation.subject.trim();
+            const status = operation.status ?? "pending";
+            if (draft.nextId >= Number.MAX_SAFE_INTEGER)
+                return fail("Task id space exhausted", index);
+            const task = {
+                id: draft.nextId,
+                subject,
+                status,
+                ...(timestamp !== undefined ? { updatedAt: timestamp } : {}),
+            };
+            const existingTasks = status === "in_progress"
+                ? draft.tasks.map((existing) => existing.status === "in_progress"
+                    ? {
+                        ...existing,
+                        status: "pending",
+                        ...(timestamp !== undefined ? { updatedAt: timestamp } : {}),
+                    }
+                    : existing)
+                : draft.tasks;
+            draft.tasks = [...existingTasks, task];
+            draft.nextId++;
+            changed = true;
+            operations.push({ index, action, changed: true, id: task.id });
+            continue;
+        }
+        if (action === "delete") {
+            if (!hasOnlyKeys(operation, ["action", "id"]) || !isPositiveInteger(operation.id))
+                return fail("Invalid delete fields", index);
+            const id = operation.id;
+            const task = findTask(draft.tasks, id);
+            if (!task)
+                return fail(`Task #${id} does not exist`, index);
+            if (task.status === "suppressed")
+                return fail(`Task #${id} is suppressed`, index);
+            draft.tasks = draft.tasks.filter((candidate) => candidate.id !== id);
+            changed = true;
+            operations.push({ index, action, changed: true, id });
+            continue;
+        }
+        if (!hasOnlyKeys(operation, ["action", "id", "subject", "status"]) ||
+            !isPositiveInteger(operation.id))
+            return fail("Invalid update fields", index);
+        const id = operation.id;
+        const current = findTask(draft.tasks, id);
+        if (!current)
+            return fail(`Task #${id} does not exist`, index);
+        if (current.status === "suppressed")
+            return fail(`Task #${id} is suppressed`, index);
+        const hasSubject = operation.subject !== undefined;
+        const hasStatus = operation.status !== undefined;
+        if (!hasSubject && !hasStatus)
+            return fail("Update requires a mutable field", index);
+        if (hasSubject && typeof operation.subject !== "string")
+            return fail("Subject must not be empty", index);
+        if (hasSubject) {
+            const subjectIssue = subjectError(operation.subject);
+            if (subjectIssue)
+                return fail(subjectIssue, index);
+        }
+        if (hasStatus && !isAgentTaskStatus(operation.status))
+            return fail("Invalid status", index);
+        const subject = hasSubject ? operation.subject.trim() : current.subject;
+        const status = isAgentTaskStatus(operation.status) ? operation.status : current.status;
+        if (current.status === "completed" && status !== "completed") {
+            return fail(`Invalid status transition from completed to ${status}`, index);
+        }
+        const opTimestamp = timestamp !== undefined
+            ? timestamp + (params.operations.length > 1 && action === "update" ? index : 0)
+            : undefined;
+        const next = {
+            ...current,
+            subject,
+            status,
+            ...(opTimestamp !== undefined ? { updatedAt: opTimestamp } : {}),
+        };
+        // Pi permits exactly one active task. Starting a pending or blocked task is
+        // an explicit switch, not an error: demote the previous active task inside
+        // this same draft so the invariant never leaks between batch operations.
+        const candidateTasks = draft.tasks.map((task) => {
+            if (task.id === id)
+                return next;
+            if (status === "in_progress" && task.status === "in_progress") {
+                return {
+                    ...task,
+                    status: "pending",
+                    ...(timestamp !== undefined ? { updatedAt: timestamp } : {}),
+                };
+            }
+            return task;
+        });
+        const isChanged = candidateTasks.some((task, taskIndex) => {
+            const previous = draft.tasks[taskIndex];
+            return previous?.subject !== task.subject || previous.status !== task.status;
+        });
+        if (isChanged) {
+            draft.tasks = candidateTasks;
+            changed = true;
+        }
+        operations.push({ index, action, changed: isChanged, id });
+    }
+    if (changed && !draft.tasks.some((task) => task.status === "in_progress")) {
+        const next = firstPending(draft.tasks);
+        if (next) {
+            draft.tasks = draft.tasks.map((task) => task.id === next.id
+                ? {
+                    ...task,
+                    status: "in_progress",
+                    ...(timestamp !== undefined ? { updatedAt: timestamp } : {}),
+                }
+                : task);
+        }
+    }
+    if (!changed)
+        return { ok: true, changed: false, state, operations };
+    return { ok: true, changed: true, state: draft, operations };
+}
+export function cancelTodosByUser(state, ids, now) {
+    if (now !== undefined && !isValidTimestamp(now)) {
+        return { ok: false, state, error: "Invalid timestamp" };
+    }
+    const timestamp = now !== undefined ? Math.floor(now) : undefined;
+    if (!validateTaskState(state))
+        return { ok: false, state, error: "Invalid task state" };
+    if (!Array.isArray(ids) || ids.length === 0) {
+        return { ok: false, state, error: "At least one task id is required" };
+    }
+    for (const id of ids) {
+        if (!isPositiveInteger(id))
+            return { ok: false, state, error: `Invalid task id: ${id}` };
+        const current = findTask(state.tasks, id);
+        if (!current)
+            return { ok: false, state, error: `Task #${id} does not exist` };
+        if (current.status === "completed") {
+            return { ok: false, state, error: `Task #${id} is already completed` };
+        }
+    }
+    const targetIds = new Set(ids);
+    const cancelledIds = [];
+    let hasChanges = false;
+    let tasks = state.tasks.map((task) => {
+        if (targetIds.has(task.id) && task.status !== "suppressed") {
+            cancelledIds.push(task.id);
+            hasChanges = true;
+            return {
+                ...task,
+                status: "suppressed",
+                ...(timestamp !== undefined ? { updatedAt: timestamp } : {}),
+            };
+        }
+        return task;
+    });
+    if (!hasChanges) {
+        return { ok: true, changed: false, state, cancelledIds: [] };
+    }
+    if (!tasks.some((task) => task.status === "in_progress")) {
+        const next = firstPending(tasks);
+        if (next) {
+            tasks = tasks.map((task) => task.id === next.id
+                ? {
+                    ...task,
+                    status: "in_progress",
+                    ...(timestamp !== undefined ? { updatedAt: timestamp } : {}),
+                }
+                : task);
+        }
+    }
+    return {
+        ok: true,
+        changed: true,
+        state: { tasks, nextId: state.nextId },
+        cancelledIds,
+    };
+}
+export function suppressTodoByUser(state, id, now) {
+    const result = cancelTodosByUser(state, [id], now);
+    if (!result.ok)
+        return result;
+    return { ok: true, changed: result.changed, state: result.state };
+}

package/dist/state.d.ts

@@ -0,0 +1,8 @@
+import { type Task, type TaskState } from "./model.js";
+export interface TodoSnapshot {
+    readonly tasks: readonly Task[];
+    readonly nextId: number;
+}
+export declare function snapshotFromState(state: TaskState): TodoSnapshot;
+/** Validates one tool result's display snapshot; it never restores session state. */
+export declare function stateFromSnapshot(value: unknown, now?: number): TaskState | undefined;

package/dist/state.js

@@ -0,0 +1,12 @@
+import { activateFirstPending, validateTaskState } from "./model.js";
+export function snapshotFromState(state) {
+    return {
+        tasks: state.tasks.map((task) => ({ ...task })),
+        nextId: state.nextId,
+    };
+}
+/** Validates one tool result's display snapshot; it never restores session state. */
+export function stateFromSnapshot(value, now) {
+    const state = validateTaskState(value);
+    return state ? activateFirstPending(state, now) : undefined;
+}