@sigrun/todo 0.0.0-stage → 0.1.1

package/dist/state.js

@@ -0,0 +1,282 @@
+import { StringEnum, Type } from "@earendil-works/pi-ai";
+import { detectCycle } from "./graph.js";
+/**
+ * True when `op` changed the task state — the calls whose post-change snapshot
+ * must be persisted for replay. Reads, failures and a no-effect `update` leave
+ * state untouched.
+ */
+export function changesState(op) {
+    switch (op.kind) {
+        case "create":
+        case "delete":
+        case "clear":
+            return true;
+        case "update":
+            return op.changed;
+        case "list":
+        case "get":
+        case "error":
+            return false;
+    }
+}
+/**
+ * Allowed forward transitions per source status. `completed` is one-way to
+ * `deleted` (never back to `in_progress`); `deleted` is terminal. Idempotent
+ * same→same is allowed separately, so this table only enumerates transitions.
+ */
+const VALID_TRANSITIONS = {
+    pending: new Set(["in_progress", "completed", "deleted"]),
+    in_progress: new Set(["pending", "completed", "deleted"]),
+    completed: new Set(["deleted"]),
+    deleted: new Set(),
+};
+function isTransitionValid(from, to) {
+    return from === to || VALID_TRANSITIONS[from].has(to);
+}
+const CreateTaskItemSchema = Type.Object({
+    subject: Type.String({ description: "Task subject line" }),
+    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')",
+    })),
+    blockedBy: Type.Optional(Type.Array(Type.Number(), {
+        description: "Existing task ids this item waits on. Cannot name another item in this same batch; create the prerequisite first, then the dependent with blockedBy.",
+    })),
+});
+/**
+ * The tool's parameter schema. Every `description` doubles as LLM-facing prompt
+ * copy, so the wording is part of the tool's behaviour.
+ */
+export const TodoParamsSchema = Type.Object({
+    action: StringEnum(["create", "update", "list", "get", "delete", "clear"]),
+    subject: Type.Optional(Type.String({ description: "Task subject line (required for create unless tasks[] is set)" })),
+    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"], {
+        description: "Set this task's status (update): one of pending, in_progress, completed, deleted. When action is list, filters returned tasks by this status.",
+    })),
+    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)" })),
+    id: Type.Optional(Type.Number({ description: "Task id (required for update, get, delete)" })),
+    note: Type.Optional(Type.String({
+        description: "Short note stored on the task (update, delete): why it was dropped, or why it stays open",
+    })),
+    tasks: Type.Optional(Type.Array(CreateTaskItemSchema, {
+        description: "Batch create: independent tasks in one call, one-of with subject. The whole list is validated then committed together. Items cannot blockedBy each other; create the prerequisite first, then the dependent with blockedBy.",
+    })),
+});
+/** Per-item create fields: on a batch they belong to each `tasks[]` item. */
+const BATCH_ITEM_FIELDS = ["description", "activeForm", "blockedBy"];
+function errorResult(state, message) {
+    return { state, op: { kind: "error", message } };
+}
+function buildCreatedTask(id, spec, subject) {
+    const task = { id, subject, status: "pending" };
+    if (spec.description)
+        task.description = spec.description;
+    if (spec.activeForm)
+        task.activeForm = spec.activeForm;
+    if (spec.blockedBy?.length)
+        task.blockedBy = [...spec.blockedBy];
+    return task;
+}
+function validateCreateBlockedBy(state, blockedBy, siblingIds) {
+    if (!blockedBy?.length)
+        return undefined;
+    for (const dep of blockedBy) {
+        if (siblingIds.has(dep)) {
+            return `blockedBy: #${dep} is another item in this batch; create the prerequisite first, then the dependent with blockedBy`;
+        }
+        const depTask = state.tasks.find((task) => task.id === dep);
+        if (!depTask)
+            return `blockedBy: #${dep} not found`;
+        if (depTask.status === "deleted")
+            return `blockedBy: #${dep} is deleted`;
+    }
+    return undefined;
+}
+function sameNumberList(a, b) {
+    const x = a ?? [];
+    const y = b ?? [];
+    return x.length === y.length && x.every((value, index) => value === y[index]);
+}
+/**
+ * Did this `update` change anything? A no-effect update — `status` set to its
+ * current value, or a field re-sent unchanged — reports false so the caller can
+ * say "no change" instead of "updated", which otherwise drives a model to
+ * re-issue the same call in a loop.
+ *
+ * blockedBy is order-sensitive (the reducer preserves insertion order).
+ */
+function taskChanged(before, after) {
+    return (before.subject !== after.subject ||
+        before.status !== after.status ||
+        before.description !== after.description ||
+        before.activeForm !== after.activeForm ||
+        before.note !== after.note ||
+        !sameNumberList(before.blockedBy, after.blockedBy));
+}
+/**
+ * Pure reducer: (state, params) → (state, op). Formatting belongs to the tool's
+ * response envelope and persistence to the log; validation stays in-reducer so
+ * every invariant is enforced before any state is written.
+ */
+export function applyTodo(state, params) {
+    switch (params.action) {
+        case "create": {
+            const batch = params.tasks;
+            if (Array.isArray(batch) && params.subject !== undefined) {
+                return errorResult(state, "create requires subject or tasks[], not both");
+            }
+            if (Array.isArray(batch)) {
+                const topLevel = BATCH_ITEM_FIELDS.filter((field) => params[field] !== undefined);
+                if (topLevel.length) {
+                    return errorResult(state, `create with tasks[] takes ${topLevel.join(", ")} on each item, not at the top level`);
+                }
+                if (batch.length === 0)
+                    return errorResult(state, "tasks[] must be non-empty");
+                for (const [index, item] of batch.entries()) {
+                    if (!item.subject.trim())
+                        return errorResult(state, `tasks[${index}]: subject required for create`);
+                }
+                const siblingIds = new Set(batch.map((_, index) => state.nextId + index));
+                for (const item of batch) {
+                    const blockedError = validateCreateBlockedBy(state, item.blockedBy, siblingIds);
+                    if (blockedError)
+                        return errorResult(state, blockedError);
+                }
+                const created = batch.map((item, index) => buildCreatedTask(state.nextId + index, item, item.subject));
+                return {
+                    state: { tasks: [...state.tasks, ...created], nextId: state.nextId + created.length },
+                    op: { kind: "create", taskIds: created.map((task) => task.id) },
+                };
+            }
+            if (!params.subject?.trim())
+                return errorResult(state, "subject required for create");
+            const blockedError = validateCreateBlockedBy(state, params.blockedBy, new Set());
+            if (blockedError)
+                return errorResult(state, blockedError);
+            const newTask = buildCreatedTask(state.nextId, params, params.subject);
+            return {
+                state: { tasks: [...state.tasks, newTask], nextId: state.nextId + 1 },
+                op: { kind: "create", taskIds: [newTask.id] },
+            };
+        }
+        case "update": {
+            if (params.id === undefined)
+                return errorResult(state, "id required for update");
+            const index = state.tasks.findIndex((task) => task.id === params.id);
+            if (index === -1)
+                return errorResult(state, `#${params.id} not found`);
+            const current = state.tasks[index];
+            const hasMutation = params.subject !== undefined ||
+                params.description !== undefined ||
+                params.activeForm !== undefined ||
+                params.status !== undefined ||
+                params.note !== undefined ||
+                (params.addBlockedBy && params.addBlockedBy.length > 0) ||
+                (params.removeBlockedBy && params.removeBlockedBy.length > 0);
+            if (!hasMutation) {
+                return errorResult(state, "update requires at least one mutable field: subject, description, activeForm, status, note, addBlockedBy, or removeBlockedBy");
+            }
+            let newStatus = current.status;
+            if (params.status !== undefined) {
+                if (!isTransitionValid(current.status, params.status)) {
+                    return errorResult(state, `illegal transition ${current.status} → ${params.status}`);
+                }
+                newStatus = params.status;
+            }
+            let newBlockedBy = current.blockedBy ? [...current.blockedBy] : [];
+            if (params.removeBlockedBy?.length) {
+                const toRemove = new Set(params.removeBlockedBy);
+                newBlockedBy = newBlockedBy.filter((dep) => !toRemove.has(dep));
+            }
+            if (params.addBlockedBy?.length) {
+                for (const dep of params.addBlockedBy) {
+                    if (dep === current.id)
+                        return errorResult(state, `cannot block #${current.id} on itself`);
+                    const depTask = state.tasks.find((task) => task.id === dep);
+                    if (!depTask)
+                        return errorResult(state, `addBlockedBy: #${dep} not found`);
+                    if (depTask.status === "deleted")
+                        return errorResult(state, `addBlockedBy: #${dep} is deleted`);
+                    if (!newBlockedBy.includes(dep))
+                        newBlockedBy.push(dep);
+                }
+                if (detectCycle(state.tasks, current.id, newBlockedBy)) {
+                    return errorResult(state, "addBlockedBy would create a cycle in the blockedBy graph");
+                }
+            }
+            const updated = { ...current, status: newStatus };
+            if (params.subject !== undefined)
+                updated.subject = params.subject;
+            if (params.description !== undefined)
+                updated.description = params.description;
+            if (params.activeForm !== undefined)
+                updated.activeForm = params.activeForm;
+            if (params.note !== undefined)
+                updated.note = params.note;
+            if (newBlockedBy.length)
+                updated.blockedBy = newBlockedBy;
+            else
+                delete updated.blockedBy;
+            const tasks = [...state.tasks];
+            tasks[index] = updated;
+            return {
+                state: { tasks, nextId: state.nextId },
+                op: {
+                    kind: "update",
+                    id: updated.id,
+                    fromStatus: current.status,
+                    toStatus: newStatus,
+                    changed: taskChanged(current, updated),
+                },
+            };
+        }
+        case "list": {
+            return {
+                state,
+                op: { kind: "list", ...(params.status !== undefined ? { statusFilter: params.status } : {}) },
+            };
+        }
+        case "get": {
+            if (params.id === undefined)
+                return errorResult(state, "id required for get");
+            const task = state.tasks.find((candidate) => candidate.id === params.id);
+            if (!task)
+                return errorResult(state, `#${params.id} not found`);
+            return { state, op: { kind: "get", task } };
+        }
+        case "delete": {
+            if (params.id === undefined)
+                return errorResult(state, "id required for delete");
+            const index = state.tasks.findIndex((task) => task.id === params.id);
+            if (index === -1)
+                return errorResult(state, `#${params.id} not found`);
+            const current = state.tasks[index];
+            if (current.status === "deleted")
+                return errorResult(state, `#${current.id} is already deleted`);
+            const updated = { ...current, status: "deleted" };
+            if (params.note !== undefined)
+                updated.note = params.note;
+            const tasks = [...state.tasks];
+            tasks[index] = updated;
+            return {
+                state: { tasks, nextId: state.nextId },
+                op: { kind: "delete", id: updated.id, subject: updated.subject },
+            };
+        }
+        case "clear": {
+            // `nextId` is deliberately kept (rpiv-todo resets it to 1): ids must
+            // never be reused, because every snapshot kept in the transcript would
+            // then point two tasks at the same id.
+            return {
+                state: { tasks: [], nextId: state.nextId },
+                op: { kind: "clear", count: state.tasks.length },
+            };
+        }
+    }
+}

package/dist/tool.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The `todo` tool: the only writer of a conversation's task list, and the
+ * source of the snapshots `replay` reads.
+ *
+ * One call applies one reducer step ({@link applyTodo}) to the conversation's
+ * {@link TodoLog}, and the reducer's op decides what the result carries:
+ *
+ * - `output` — the model's terse status line, always ending with the open-item
+ *   count (open = `pending` + `in_progress`);
+ * - `details` — the full post-change snapshot, so the transcript can be
+ *   replayed. STATE-CHANGING calls only: `replay` ignores a snapshot's
+ *   `action`, so a read-only result carrying `{tasks, nextId}` (a filtered
+ *   `list`, say) would silently become the conversation's list;
+ * - `onChanged` — the panel's cue, fired once per call that changed the list,
+ *   and never for a read, a failure or a no-effect update.
+ *
+ * An error op carries `isError` and the reducer's message, with no details.
+ *
+ * `callers: ["model"]` keeps the tool out of code mode: a nested call's result
+ * is not recorded in the transcript, so a script-made change could never be
+ * replayed. `replay` stays at its `"unsafe"` default — an interrupted call is
+ * abandoned and the model re-issues it, where `"safe"` could apply a
+ * non-idempotent create twice.
+ */
+import { type ConversationId, type ToolRegistration } from "@earendil-works/pi-durable";
+import type { TodoLog } from "./log.js";
+import { TodoParamsSchema } from "./state.js";
+export interface TodoToolDeps {
+    /** The conversation's cache in front of the transcript. */
+    log: TodoLog;
+    /** Called once per call whose result changed the list. */
+    onChanged: (conversationId: ConversationId) => void;
+}
+/** The `todo` tool over one conversation-scoped {@link TodoLog}. */
+export declare function createTodoTool(deps: TodoToolDeps): ToolRegistration<typeof TodoParamsSchema>;

package/dist/tool.js

@@ -0,0 +1,168 @@
+/**
+ * The `todo` tool: the only writer of a conversation's task list, and the
+ * source of the snapshots `replay` reads.
+ *
+ * One call applies one reducer step ({@link applyTodo}) to the conversation's
+ * {@link TodoLog}, and the reducer's op decides what the result carries:
+ *
+ * - `output` — the model's terse status line, always ending with the open-item
+ *   count (open = `pending` + `in_progress`);
+ * - `details` — the full post-change snapshot, so the transcript can be
+ *   replayed. STATE-CHANGING calls only: `replay` ignores a snapshot's
+ *   `action`, so a read-only result carrying `{tasks, nextId}` (a filtered
+ *   `list`, say) would silently become the conversation's list;
+ * - `onChanged` — the panel's cue, fired once per call that changed the list,
+ *   and never for a read, a failure or a no-effect update.
+ *
+ * An error op carries `isError` and the reducer's message, with no details.
+ *
+ * `callers: ["model"]` keeps the tool out of code mode: a nested call's result
+ * is not recorded in the transcript, so a script-made change could never be
+ * replayed. `replay` stays at its `"unsafe"` default — an interrupted call is
+ * abandoned and the model re-issues it, where `"safe"` could apply a
+ * non-idempotent create twice.
+ */
+import { defineTool } from "@earendil-works/pi-durable";
+import { applyTodo, changesState, TodoParamsSchema } from "./state.js";
+/** Statuses as they read inside a sentence: `in_progress` is two words. */
+const STATUS_TEXT = {
+    pending: "pending",
+    in_progress: "in progress",
+    completed: "completed",
+    deleted: "deleted",
+};
+/** `1 task` / `2 tasks`, with an optional filter name: `1 pending task`. */
+function countOf(count, noun, scope) {
+    const text = scope === undefined ? noun : `${STATUS_TEXT[scope]} ${noun}`;
+    return `${count} ${text}${count === 1 ? "" : "s"}`;
+}
+/**
+ * The count sentence that ends every successful result — the model's answer to
+ * "how much is left". A read's filter never narrows it: it always counts the
+ * whole list.
+ */
+function openSummary(state) {
+    const open = state.tasks.filter((task) => task.status === "pending" || task.status === "in_progress");
+    const inProgress = open.filter((task) => task.status === "in_progress").length;
+    const suffix = inProgress === 0 ? "" : ` (${inProgress} in progress)`;
+    return `${open.length} open${suffix}`;
+}
+/** `#3 Wire the panel` — a task named by id and subject. */
+function labelOf(id, subject) {
+    return `#${id} ${subject}`;
+}
+/** The subject of the task an `update` or `delete` addressed. */
+function subjectOf(state, id) {
+    return state.tasks.find((task) => task.id === id)?.subject ?? "";
+}
+/**
+ * `#3 [in_progress] Wire the panel` — one entry of a list. The bracket repeats
+ * the parameter's own spelling, so the model reads back the token it passes.
+ */
+function listEntry(task) {
+    return `#${task.id} [${task.status}] ${task.subject}`;
+}
+/**
+ * The `list` view: the matching tasks and the whole-list count. Deleted tasks
+ * are tombstones — kept in the snapshot so replay and ids stay stable, but left
+ * out of an unfiltered list.
+ */
+function listText(state, statusFilter, summary) {
+    const shown = statusFilter === undefined
+        ? state.tasks.filter((task) => task.status !== "deleted")
+        : state.tasks.filter((task) => task.status === statusFilter);
+    if (shown.length === 0) {
+        const scope = statusFilter === undefined ? "" : ` ${STATUS_TEXT[statusFilter]}`;
+        return `No${scope} tasks. ${summary}.`;
+    }
+    const header = countOf(shown.length, "task", statusFilter);
+    return `${header}: ${shown.map(listEntry).join("; ")}. ${summary}.`;
+}
+/**
+ * The `get` view: the task with the fields the list view omits — the
+ * description, what it waits on, and its note.
+ */
+function getText(task, summary) {
+    const extras = [];
+    if (task.blockedBy?.length) {
+        extras.push(`blocked by ${task.blockedBy.map((id) => `#${id}`).join(", ")}`);
+    }
+    if (task.note !== undefined)
+        extras.push(`note: ${task.note}`);
+    const description = task.description === undefined ? "" : ` — ${task.description}`;
+    const suffix = extras.length === 0 ? "" : ` (${extras.join("; ")})`;
+    return `${listEntry(task)}${description}${suffix}. ${summary}.`;
+}
+/**
+ * The model's view of one round — the text {@link createTodoTool} returns as
+ * `output`. A mutation is one sentence; a read is a list; an error is its own
+ * message with no count, because nothing changed and a count would only pad the
+ * reason it failed.
+ */
+function formatOutput(state, op) {
+    const summary = openSummary(state);
+    switch (op.kind) {
+        case "create": {
+            const created = op.taskIds.map((id) => labelOf(id, subjectOf(state, id))).join(", ");
+            return `Created ${created}. ${summary}.`;
+        }
+        case "update": {
+            const label = labelOf(op.id, subjectOf(state, op.id));
+            // A no-effect update says so: a bare "updated" drives a model to
+            // re-issue the same call in a loop.
+            if (!op.changed)
+                return `No change to ${label}. ${summary}.`;
+            if (op.fromStatus === op.toStatus)
+                return `Updated ${label}. ${summary}.`;
+            const to = STATUS_TEXT[op.toStatus];
+            return `Updated ${label}: ${STATUS_TEXT[op.fromStatus]} → ${to}. ${summary}.`;
+        }
+        case "delete":
+            return `Deleted ${labelOf(op.id, op.subject)}. ${summary}.`;
+        case "clear":
+            return `Cleared ${countOf(op.count, "task")}. ${summary}.`;
+        case "get":
+            return getText(op.task, summary);
+        case "list":
+            return listText(state, op.statusFilter, summary);
+        case "error":
+            return op.message;
+    }
+}
+/**
+ * The `details` of a state-changing result: the whole post-change list,
+ * deleted tasks included. `TodoSnapshot` is an interface without an index
+ * signature, so it is not structurally a `JsonValue`; `satisfies` checks the
+ * fields and the cast only satisfies the tool-result typing.
+ */
+function snapshotOf(action, state) {
+    const snapshot = {
+        action,
+        tasks: state.tasks,
+        nextId: state.nextId,
+    };
+    return snapshot;
+}
+/** The `todo` tool over one conversation-scoped {@link TodoLog}. */
+export function createTodoTool(deps) {
+    const { log, onChanged } = deps;
+    return defineTool({
+        name: "todo",
+        description: "Maintain this conversation's task list. Use it to plan multi-step work and to keep the user's panel current: one entry per unit of work, `in_progress` when you start it, `completed` when it is done.",
+        callers: ["model"],
+        parameters: TodoParamsSchema,
+        execute: async (args, api) => {
+            const { state, op } = await log.mutate(api.conversationId, (current) => applyTodo(current, args));
+            const output = [{ type: "text", text: formatOutput(state, op) }];
+            if (op.kind === "error")
+                return { output, isError: true };
+            // Reads, and an update that re-sent the values already stored: nothing
+            // changed, so there is nothing to persist and nothing to refresh. A
+            // snapshot here would re-stamp the transcript with the state it holds.
+            if (!changesState(op))
+                return { output };
+            onChanged(api.conversationId);
+            return { output, details: snapshotOf(args.action, state) };
+        },
+    });
+}

package/dist/types.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Canonical todo state for `@sigrun/todo`. The shape is pinned: every
+ * state-changing `todo` result carries it as `details`, and replay reads the
+ * latest snapshot off the transcript, so field names and field order are a
+ * cross-version compatibility surface.
+ */
+export type TaskStatus = "pending" | "in_progress" | "completed" | "deleted";
+export interface Task {
+    id: number;
+    subject: string;
+    description?: string;
+    activeForm?: string;
+    status: TaskStatus;
+    blockedBy?: number[];
+    note?: string;
+}
+export interface TodoState {
+    tasks: Task[];
+    nextId: number;
+}
+export declare const EMPTY_STATE: TodoState;
+export type TodoAction = "create" | "update" | "list" | "get" | "delete" | "clear";
+/** The `details` of every state-changing result: the full post-change state. */
+export interface TodoSnapshot extends TodoState {
+    action: TodoAction;
+}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * Canonical todo state for `@sigrun/todo`. The shape is pinned: every
+ * state-changing `todo` result carries it as `details`, and replay reads the
+ * latest snapshot off the transcript, so field names and field order are a
+ * cross-version compatibility surface.
+ */
+export const EMPTY_STATE = { tasks: [], nextId: 1 };

package/package.json

@@ -1,6 +1,58 @@
 {
-  "name": "@sigrun/todo",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@sigrun/todo",
+	"version": "0.1.1",
+	"description": "Agent-kept task list for sigrun: a todo list the agent owns, rendered in a conversation panel",
+	"type": "module",
+	"engines": {
+		"node": ">=22.19.0"
+	},
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist",
+		"CHANGELOG.md",
+		"THIRD_PARTY_NOTICES.md"
+	],
+	"scripts": {
+		"test": "node scripts/check-manifest.mjs --expect-name @sigrun/todo && vitest run",
+		"typecheck": "tsc --noEmit",
+		"build": "tsc -p tsconfig.build.json",
+		"prepublishOnly": "npm run build"
+	},
+	"peerDependencies": {
+		"@earendil-works/chord": "1.3.0 || 1.4.0",
+		"@earendil-works/pi-ai": "1.3.0 || 1.4.0",
+		"@earendil-works/pi-durable": "1.3.0 || 1.4.0"
+	},
+	"dependencies": {},
+	"devDependencies": {
+		"@earendil-works/chord": "1.4.0",
+		"@earendil-works/pi-ai": "1.4.0",
+		"@earendil-works/pi-durable": "1.4.0",
+		"@sigrun/sigrun": "file:../sigrun",
+		"@sigrun/shared": "file:../sigrun/shared",
+		"@types/node": "^26.6.4",
+		"tsx": "^4.23.15",
+		"typescript": "^7.0.2",
+		"vitest": "^5.0.3"
+	},
+	"license": "MIT",
+	"repository": {
+		"type": "github",
+		"url": "git+https://github.com/sigrun-ai/sigrun-todo.git"
+	},
+	"bugs": {
+		"url": "https://github.com/sigrun-ai/sigrun-todo/issues"
+	},
+	"homepage": "https://github.com/sigrun-ai/sigrun-todo#readme",
+	"publishConfig": {
+		"access": "public",
+		"provenance": true
+	}
+}