@sigrun/todo 0.0.0-stage → 0.1.2

package/dist/log.js

@@ -0,0 +1,153 @@
+/**
+ * Transcript replay + per-conversation cache for `@sigrun/todo`.
+ *
+ * The transcript is the source of truth: every state-changing `todo` call
+ * returns the full post-change snapshot in its tool-result `details`, so the
+ * newest such snapshot in the fork-aware history IS the list. {@link replay}
+ * reads that snapshot; {@link TodoLog} caches it per conversation so a tool
+ * round does not re-scan the history between its own calls.
+ *
+ * The cache deliberately runs ahead of the transcript between a `todo` call
+ * and the round settling: an aborted call's change is uncommitted, and
+ * {@link TodoLog.settle} (called when the round ends) forgets the dirty
+ * entry so the next {@link TodoLog.get} re-reads the transcript without it.
+ */
+import { changesState } from "./state.js";
+import { EMPTY_STATE } from "./types.js";
+/** Page size for the host scan. */
+const PAGE_SIZE = 100;
+/**
+ * The {@link EntryReader} over a sigrun host's fork-aware transcript read,
+ * paging `host.conversations.entries` newest-first until exhausted.
+ */
+export function hostEntryReader(host) {
+    return async function* (conversationId) {
+        let cursor;
+        for (;;) {
+            const page = await host.conversations.entries(conversationId, { order: "descending" }, PAGE_SIZE, cursor);
+            for (const entry of page.items)
+                yield entry;
+            if (page.next === undefined)
+                return;
+            cursor = page.next;
+        }
+    };
+}
+/**
+ * The snapshot carried in one tool-result entry's `details`, or `undefined`
+ * when the entry is not a usable todo snapshot (wrong kind, wrong tool,
+ * error result, malformed details).
+ */
+function snapshotOf(entry) {
+    if (entry.kind !== "pi.tool-result")
+        return undefined;
+    const message = entry.model?.[0];
+    if (message?.role !== "toolResult" || message.toolName !== "todo" || message.isError !== false) {
+        return undefined;
+    }
+    const details = message.details;
+    if (details === undefined ||
+        typeof details !== "object" ||
+        !Array.isArray(details.tasks) ||
+        typeof details.nextId !== "number") {
+        return undefined;
+    }
+    return { tasks: details.tasks, nextId: details.nextId };
+}
+/**
+ * The todo list of one conversation: the newest committed `todo` snapshot in
+ * its fork-aware history. Walks newest→oldest; a `pi.reset` entry ends the
+ * walk (history before the reset is not this list's history); `pi.compaction`
+ * and everything else is walked past. No snapshot → {@link EMPTY_STATE}.
+ */
+export async function replay(read, conversationId) {
+    for await (const entry of read(conversationId)) {
+        if (entry.kind === "pi.reset")
+            return EMPTY_STATE;
+        const snapshot = snapshotOf(entry);
+        if (snapshot !== undefined)
+            return snapshot;
+    }
+    return EMPTY_STATE;
+}
+/**
+ * The per-conversation todo cache in front of the transcript.
+ *
+ * `get` seeds the cache from the transcript once per conversation;
+ * concurrent callers share ONE seeding promise (the transcript is scanned
+ * once no matter how many of a round's tool calls race). `mutate` awaits
+ * that seed, then reads-applies-writes synchronously — the NO-`await`
+ * window between the read and the write is what serializes parallel calls:
+ * no two mutations can observe the same state. A mutation whose op changes
+ * state ({@link changesState}) marks the entry dirty.
+ *
+ * `settle` ends a round: a dirty entry is dropped (the transcript either
+ * holds its snapshot by then or the call was aborted, in which case the
+ * uncommitted change must disappear) and reports `true`; a clean entry is
+ * kept and reports `false`. `forget` drops the entry unconditionally.
+ */
+export class TodoLog {
+    #read;
+    #cache = new Map();
+    #seeding = new Map();
+    constructor(read) {
+        this.#read = read;
+    }
+    /** The conversation's current state, seeding from the transcript once. */
+    async get(id) {
+        const cached = this.#cache.get(id);
+        if (cached !== undefined)
+            return cached.state;
+        return await this.#seed(id);
+    }
+    /**
+     * Apply `f` to the conversation's current state. Serialized with every
+     * other `mutate` of this conversation: after the seed resolves, the
+     * read-apply-write below contains no `await`, so it is atomic.
+     */
+    async mutate(id, f) {
+        await this.#seed(id);
+        // No await from here to the write — this IS the serializer.
+        const current = this.#cache.get(id) ?? { state: EMPTY_STATE, dirty: false };
+        const { state, op } = f(current.state);
+        this.#cache.set(id, { state, dirty: current.dirty || changesState(op) });
+        return { state, op };
+    }
+    /**
+     * End the conversation's round: a dirty entry is dropped (return `true`)
+     * so the next `get` re-reads the transcript — the committed snapshot, or
+     * the state without an aborted call's uncommitted change. Clean → `false`.
+     */
+    settle(id) {
+        const cached = this.#cache.get(id);
+        if (cached?.dirty !== true)
+            return false;
+        this.#cache.delete(id);
+        return true;
+    }
+    /** Drop the conversation's cache entry; the next `get` re-seeds. */
+    forget(id) {
+        this.#cache.delete(id);
+    }
+    /** Seed the cache from the transcript once per id, sharing one promise. */
+    #seed(id) {
+        const cached = this.#cache.get(id);
+        if (cached !== undefined)
+            return Promise.resolve(cached.state);
+        let seeding = this.#seeding.get(id);
+        if (seeding === undefined) {
+            seeding = replay(this.#read, id).then((state) => {
+                this.#cache.set(id, { state, dirty: false });
+                this.#seeding.delete(id);
+                return state;
+            }, (error) => {
+                // A rejected seed must NOT be cached: it stays retried by the
+                // next `get`, not pinned for the process lifetime.
+                this.#seeding.delete(id);
+                throw error;
+            });
+            this.#seeding.set(id, seeding);
+        }
+        return seeding;
+    }
+}

package/dist/panel.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The Todos panel (Task 9): a `perConversation` panel over the
+ * conversation's {@link TodoLog}.
+ *
+ * - `perConversation: true` and NO `instanceKey`: the channels attach the
+ *   panel with `params: { conversationId }` of the open conversation, and
+ *   the default canonical-JSON instance key is what the webui hashes —
+ *   declaring one would break live updates.
+ * - Every render/data checks the CALLER's access: the conversationId is
+ *   client-supplied, so an unknown conversation (a `meta` throw) or a
+ *   `none` verdict hides the panel outright.
+ * - Deleted tasks are tombstones (out of `items` AND out of `total`);
+ *   completed rows stay visible, `tone: "neutral"`, never `quiet`.
+ * - The tree is a `page` (no sidebar — panel placement) with a markdown
+ *   `done/total` line and a list `collection` bound to `/items`.
+ */
+import type { ConversationId, JsonObject } from "@earendil-works/pi-durable";
+import type { SigrunHost, SurfaceDef } from "@sigrun/sigrun/extension";
+import type { TodoLog } from "./log.js";
+export interface TodoPanelDeps {
+    readonly host: SigrunHost;
+    readonly log: TodoLog;
+}
+/**
+ * The conversation id of a `perConversation` params object, or `undefined`:
+ * a positive integer `conversationId`, nothing else. The value is
+ * client-supplied; a brand-cast number must still be an id, so only a
+ * positive integer is accepted. (The cast stamps pi-durable's branded
+ * `ConversationId` — the runtime check above is the whole guard.)
+ */
+export declare function conversationIdOf(params: JsonObject): ConversationId | undefined;
+/**
+ * The instance key a `changed` notification is routed by. This must equal
+ * `canonicalJson({ conversationId })` — the default key for the params the
+ * channels attach — which for this single numeric key is plain
+ * `JSON.stringify` (pinned against `canonicalJson` by the panel test).
+ */
+export declare function panelKey(id: ConversationId): string;
+export declare function createTodoPanel(deps: TodoPanelDeps): SurfaceDef<"panel">;

package/dist/panel.js

@@ -0,0 +1,152 @@
+/**
+ * The Todos panel (Task 9): a `perConversation` panel over the
+ * conversation's {@link TodoLog}.
+ *
+ * - `perConversation: true` and NO `instanceKey`: the channels attach the
+ *   panel with `params: { conversationId }` of the open conversation, and
+ *   the default canonical-JSON instance key is what the webui hashes —
+ *   declaring one would break live updates.
+ * - Every render/data checks the CALLER's access: the conversationId is
+ *   client-supplied, so an unknown conversation (a `meta` throw) or a
+ *   `none` verdict hides the panel outright.
+ * - Deleted tasks are tombstones (out of `items` AND out of `total`);
+ *   completed rows stay visible, `tone: "neutral"`, never `quiet`.
+ * - The tree is a `page` (no sidebar — panel placement) with a markdown
+ *   `done/total` line and a list `collection` bound to `/items`.
+ */
+/** The empty panel: no rows, whatever the access path that led here. */
+const EMPTY_DATA = { done: 0, total: 0, summary: "**0/0** done", items: [] };
+/**
+ * The conversation id of a `perConversation` params object, or `undefined`:
+ * a positive integer `conversationId`, nothing else. The value is
+ * client-supplied; a brand-cast number must still be an id, so only a
+ * positive integer is accepted. (The cast stamps pi-durable's branded
+ * `ConversationId` — the runtime check above is the whole guard.)
+ */
+export function conversationIdOf(params) {
+    const id = params.conversationId;
+    if (typeof id !== "number" || !Number.isInteger(id) || id <= 0)
+        return undefined;
+    // A positive integer IS a ConversationId; the brand carries no runtime payload.
+    return id;
+}
+/**
+ * The instance key a `changed` notification is routed by. This must equal
+ * `canonicalJson({ conversationId })` — the default key for the params the
+ * channels attach — which for this single numeric key is plain
+ * `JSON.stringify` (pinned against `canonicalJson` by the panel test).
+ */
+export function panelKey(id) {
+    return JSON.stringify({ conversationId: id });
+}
+function rowOf(task) {
+    const inProgress = task.status === "in_progress";
+    return {
+        id: String(task.id),
+        title: task.subject,
+        ...(task.note === undefined ? {} : { subtitle: task.note }),
+        status: {
+            label: inProgress ? (task.activeForm ?? "in progress") : task.status,
+            spinner: inProgress,
+        },
+        ...(task.status === "completed" ? { tone: "neutral" } : {}),
+        ...(task.blockedBy === undefined || task.blockedBy.length === 0
+            ? {}
+            : { deps: task.blockedBy.map(String) }),
+    };
+}
+function dataOf(tasks) {
+    // Tombstones are not list rows and do not count toward the total.
+    const visible = tasks.filter((task) => task.status !== "deleted");
+    return {
+        done: visible.filter((task) => task.status === "completed").length,
+        total: visible.length,
+        summary: `**${visible.filter((task) => task.status === "completed").length}/${visible.length}** done`,
+        items: visible.map(rowOf),
+    };
+}
+export function createTodoPanel(deps) {
+    const { host, log } = deps;
+    /** The rows + counts for one conversation, or `undefined` for `none`. */
+    async function resolve(ctx) {
+        const id = conversationIdOf(ctx.params);
+        if (id === undefined)
+            return { access: "read", data: EMPTY_DATA };
+        let meta;
+        try {
+            meta = await host.conversations.meta(id);
+        }
+        catch {
+            // Unknown conversation: the id was client-supplied, so a throw is
+            // the unknown-id signal — hide the panel, never leak the error.
+            return { access: "none", data: EMPTY_DATA };
+        }
+        const access = await host.access.accessOf(ctx.principal, meta);
+        if (access === "none")
+            return { access: "none", data: EMPTY_DATA };
+        const state = await log.get(id);
+        // Tasks render in state (id) order; the spec pins the panel to it.
+        return { access: "read", data: dataOf(state.tasks) };
+    }
+    /**
+     * The panel tree, built as a PLAIN object — the same shape
+     * `~/repos/sigrun-escalations` emits. Deliberately not the host's
+     * `tree()`/`page()`/`card()` builders: those are a RUNTIME import of
+     * `@sigrun/sigrun/blocks`, which an extension installed from the npm
+     * registry cannot resolve (the host package is not a dependency of an
+     * extension — it is the host). `v` is the block-set version the
+     * server validates against (`BLOCK_SET_VERSION`, currently 1).
+     */
+    function treeFor() {
+        const card = {
+            title: { $: "./title" },
+            subtitle: { $: "./subtitle" },
+            status: {
+                label: { $: "./status.label" },
+                spinner: { $: "./status.spinner" },
+            },
+            tone: { $: "./tone" },
+            deps: { $: "./deps" },
+        };
+        const main = [
+            { type: "markdown", text: { $: "/summary" } },
+            {
+                type: "collection",
+                id: "todos-list",
+                display: "list",
+                items: { $: "/items" },
+                item: card,
+            },
+        ];
+        return {
+            v: 1,
+            root: {
+                type: "page",
+                title: "Todos",
+                main,
+                empty: { icon: "list", title: "No tasks yet", hint: "The agent keeps this list." },
+            },
+        };
+    }
+    return {
+        id: "todos",
+        title: "Todos",
+        icon: "list",
+        placement: "panel",
+        perConversation: true,
+        // NO instanceKey: the default canonical-JSON key of the channel's
+        // params is what the webui hashes for live updates.
+        async render(ctx) {
+            const { access, data } = await resolve(ctx);
+            return {
+                tree: treeFor(),
+                data: data,
+                access,
+            };
+        },
+        async data(ctx) {
+            const { access, data } = await resolve(ctx);
+            return { data: data, access };
+        },
+    };
+}

package/dist/section.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The static prompt section: the discipline, not the list. The current list
+ * must never appear here — it changes per update, and prompt bytes that
+ * change per update break every cache the provider keeps. Freshness of the
+ * list is the hooks' job (check + reminder), not the prompt's.
+ */
+export declare const TODO_SECTION_TEXT = "Todo list: keep the `todo` list current as you work. Update an item as it completes or its status changes; delete an item a change of direction makes obsolete rather than leaving it open. The list belongs to the work, so maintain it as the work happens \u2014 not as a cleanup pass at the end.";
+export declare const todoSection: import("@earendil-works/pi-durable").PromptSection<import("@earendil-works/pi-durable").ToolRegistration>;

package/dist/section.js

@@ -0,0 +1,9 @@
+/**
+ * The static prompt section: the discipline, not the list. The current list
+ * must never appear here — it changes per update, and prompt bytes that
+ * change per update break every cache the provider keeps. Freshness of the
+ * list is the hooks' job (check + reminder), not the prompt's.
+ */
+import { section } from "@earendil-works/pi-durable";
+export const TODO_SECTION_TEXT = "Todo list: keep the `todo` list current as you work. Update an item as it completes or its status changes; delete an item a change of direction makes obsolete rather than leaving it open. The list belongs to the work, so maintain it as the work happens — not as a cleanup pass at the end.";
+export const todoSection = section("todo", (input) => input.agent.tools.some((tool) => tool.name === "todo") ? TODO_SECTION_TEXT : undefined);

package/dist/state.d.ts

@@ -0,0 +1,74 @@
+import { type Static, Type } from "@earendil-works/pi-ai";
+import type { Task, TaskStatus, TodoState } from "./types.js";
+/**
+ * Reducer outcome. Closed tagged union: a new action must extend this union AND
+ * `changesState` (compiler-enforced exhaustive), so every action decides whether
+ * it persists a snapshot.
+ *
+ * `error` carries its message in-band so callers can branch on
+ * `op.kind === "error"` without a side-channel boolean.
+ */
+export type Op = {
+    kind: "create";
+    taskIds: number[];
+} | {
+    kind: "update";
+    id: number;
+    fromStatus: TaskStatus;
+    toStatus: TaskStatus;
+    changed: boolean;
+} | {
+    kind: "delete";
+    id: number;
+    subject: string;
+} | {
+    kind: "list";
+    statusFilter?: TaskStatus;
+} | {
+    kind: "get";
+    task: Task;
+} | {
+    kind: "clear";
+    count: number;
+} | {
+    kind: "error";
+    message: string;
+};
+/**
+ * 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 declare function changesState(op: Op): boolean;
+/**
+ * The tool's parameter schema. Every `description` doubles as LLM-facing prompt
+ * copy, so the wording is part of the tool's behaviour.
+ */
+export declare const TodoParamsSchema: Type.TObject<{
+    action: Type.TUnsafe<"clear" | "create" | "delete" | "get" | "list" | "update">;
+    subject: Type.TOptional<Type.TString>;
+    description: Type.TOptional<Type.TString>;
+    activeForm: Type.TOptional<Type.TString>;
+    status: Type.TOptional<Type.TUnsafe<"completed" | "deleted" | "in_progress" | "pending">>;
+    blockedBy: Type.TOptional<Type.TArray<Type.TNumber>>;
+    addBlockedBy: Type.TOptional<Type.TArray<Type.TNumber>>;
+    removeBlockedBy: Type.TOptional<Type.TArray<Type.TNumber>>;
+    id: Type.TOptional<Type.TNumber>;
+    note: Type.TOptional<Type.TString>;
+    tasks: Type.TOptional<Type.TArray<Type.TObject<{
+        subject: Type.TString;
+        description: Type.TOptional<Type.TString>;
+        activeForm: Type.TOptional<Type.TString>;
+        blockedBy: Type.TOptional<Type.TArray<Type.TNumber>>;
+    }>>>;
+}>;
+export type TodoParams = Static<typeof TodoParamsSchema>;
+/**
+ * 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 declare function applyTodo(state: TodoState, params: TodoParams): {
+    state: TodoState;
+    op: Op;
+};