@oisin-ee/pi-todo 0.7.1 → 0.8.0

package/README.md

@@ -82,14 +82,14 @@ Outside the terminal UI, `/todos` prints the list instead.
 
 ## Shared work display
 
-When a compatible pi-wrangle extension is active, its work widget replaces the standalone todo widget.
-Tasks remain on the current Pi session branch. Wrangle receives a read-only presentation capability through `pi.events`.
-Pi-todo owns the renderer in both standalone and shared views. Wrangle hosts it above the editor without opening a popup.
+When a compatible pi-dogsled extension is active, its work widget replaces the standalone todo widget.
+Tasks remain on the current Pi session branch. Dogsled receives a read-only presentation capability through `pi.events`.
+Pi-todo owns the renderer in both standalone and shared views. Dogsled hosts it above the editor without opening a popup.
 Alt+J/K scrolls the hosted rows. Alt+I toggles their expansion. Ordinary editor keys remain unchanged.
 `/todos` and Alt+T request the shared Todos view. `/todos list` still prints the full list.
 When shared presentation ends, the standalone widget returns without changing task state.
 
-The [version 2 display contract](https://github.com/oisin-ee/wrangle/blob/main/docs/pi-work.md)
+The [version 2 display contract](https://github.com/oisin-ee/dogsled/blob/main/docs/pi-work.md)
 defines the snapshot request, acknowledgement, release, and read-only view events.
 Incompatible versions leave the standalone widget available. Rendering failures restore it without changing saved tasks.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oisin-ee/pi-todo",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "A todo tool for pi with a Rust core: one active task, state on the session branch.",
   "keywords": [
     "pi-extension",

package/src/contract-fixture.ts

@@ -0,0 +1,103 @@
+import type { TodoParams, TodoSession } from "./tool.ts";
+import { STATE_ENTRY } from "./state.ts";
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+import type { TodoList } from "./wasm.ts";
+import { runTodo } from "./tool.ts";
+
+interface Fixture {
+  readonly entries: SessionEntry[];
+  readonly session: TodoSession;
+  readonly call: (params: TodoParams) => TodoList;
+}
+
+/**
+ * Creates a branch-backed caller using the real tool and WASM core.
+ * @param {readonly unknown[]} snapshots Existing stored snapshots.
+ * @returns {Fixture} The tool caller and Pi append seam.
+ */
+const first = 0,
+  second = 1,
+  third = 2,
+  last = -1,
+  fixture = (snapshots: readonly unknown[] = []): Fixture => {
+    const entries = snapshots.map((data): SessionEntry => ({
+        customType: STATE_ENTRY,
+        data,
+        id: crypto.randomUUID(),
+        parentId: null,
+        timestamp: "2026-10-20T00:00:00Z",
+        type: "custom",
+      })),
+      session: TodoSession = {
+        append: (customType, data): void => {
+          entries.push({
+            customType,
+            data,
+            id: crypto.randomUUID(),
+            parentId: entries.at(last)?.id ?? null,
+            timestamp: "2026-10-20T00:00:00Z",
+            type: "custom",
+          });
+        },
+        branch: () => entries,
+        sessionId: "test-session",
+      };
+    return { call: (params) => runTodo(params, session).details, entries, session };
+  },
+  /**
+   * A complete self-assigned contract for deterministic behavior tests.
+   * @returns {NonNullable<TodoParams["contract"]>} Authored contract fields.
+   */
+  contract = (): NonNullable<TodoParams["contract"]> => ({
+    acceptance: {
+      argv: ["moon", "run", "todo-core:test"],
+      cwd: ".",
+      expected: "passes",
+      kind: "command",
+    },
+    assignment: { kind: "self" },
+    deliverable: "Executable task contracts",
+    dependsOn: [],
+    scope: { generates: [], owns: ["src/"], reads: ["README.md"], repositoryId: "oisinpi" },
+  }),
+  /**
+   * Returns the runtime ID from the first root in a tool result.
+   * @param {TodoList} list Real tool result.
+   * @returns {string} Runtime ID.
+   */
+  firstId = (list: TodoList): string => {
+    const id = list.tasks.at(first)?.unit?.reference.unitId;
+    if (id === undefined) {
+      throw new Error("Expected a runtime unit ID");
+    }
+    return id;
+  },
+  /**
+   * Requires a root identity at a known fixture position.
+   * @param {TodoList} list Tool result.
+   * @param {number} index Root position.
+   * @returns {string} Runtime ID.
+   */
+  rootId = (list: TodoList, index: number): string => {
+    const id = list.tasks.at(index)?.unit?.reference.unitId;
+    if (id === undefined) {
+      throw new Error("Expected root identity");
+    }
+    return id;
+  },
+  /**
+   * Requires a child identity from the first outcome.
+   * @param {TodoList} list Tool result.
+   * @param {number} index Child position.
+   * @returns {string} Runtime ID.
+   */
+  childId = (list: TodoList, index: number): string => {
+    const id = list.tasks.at(first)?.subtasks?.at(index)?.unit?.reference.unitId;
+    if (id === undefined) {
+      throw new Error("Expected child identity");
+    }
+    return id;
+  };
+
+export { childId, contract, first, firstId, fixture, last, rootId, second, third };
+export type { Fixture };

package/src/display.ts

@@ -41,8 +41,14 @@ const emptyCount = 0,
       active = list.tasks.flatMap((task) => [
         ...(task.status === "in_progress" ? [task.content] : []),
         ...(task.subtasks ?? [])
-          .filter((child: Readonly<Subtask>) => child.status === "in_progress")
-          .map((child: Readonly<Subtask>) => `${task.content} → ${child.content}`),
+          .filter(
+            (child: Readonly<Pick<Subtask, "content" | "status">>) =>
+              child.status === "in_progress",
+          )
+          .map(
+            (child: Readonly<Pick<Subtask, "content" | "status">>) =>
+              `${task.content} → ${child.content}`,
+          ),
       ]),
       current =
         active.length > emptyCount

package/src/gate.ts

@@ -0,0 +1,79 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { TaskProvider } from "./provider.ts";
+import { ownsTodo } from "./lifecycle.ts";
+
+/** Exact structured reads and workflow controls, never command-text inference. */
+const controls = new Set([
+    "ask",
+    "codemode",
+    "interview",
+    "todo",
+    "tool_search",
+    "read",
+    "ls",
+    "find",
+    "grep",
+    "hypa_read",
+    "hypa_ls",
+    "hypa_find",
+    "hypa_grep",
+    "web_search",
+    "web_fetch",
+    "lsp_diagnostics",
+    "ctx_search",
+    "ctx_stats",
+    "mcp__codebase_memory__search_graph",
+    "mcp__codebase_memory__get_code_snippet",
+    "mcp__codebase_memory__trace_path",
+    "mcp__codebase_memory__detect_changes",
+    "hindsight_search_knowledge_pages",
+    "hindsight_list_knowledge_pages",
+    "hindsight_read_knowledge_page",
+    "hindsight_reflect",
+    "hindsight_sync_status",
+    "hindsight_diagnose",
+    "hindsight_capture_initiative",
+    "mcp__dogsled__spawn",
+    "mcp__dogsled__send",
+    "mcp__dogsled__cancel",
+    "mcp__dogsled__close",
+    "mcp__dogsled__stop",
+    "mcp__dogsled__read",
+    "mcp__dogsled__status",
+    "mcp__dogsled__inbox",
+  ]),
+  /**
+   * Checks actual calls and leases execution-bearing calls.
+   * @param {Readonly<ExtensionAPI>} pi Runtime hooks and metadata.
+   * @param {Readonly<TaskProvider>} provider Task state and leases.
+   */
+  registerGate = (
+    pi: Readonly<Pick<ExtensionAPI, "on" | "getAllTools">>,
+    provider: Readonly<TaskProvider>,
+  ): void => {
+    pi.on("tool_call", (event: Readonly<{ toolName: string; toolCallId: string }>, ctx) => {
+      if (!ownsTodo(pi)) {
+        return { block: false };
+      }
+      provider.context(ctx);
+      if (controls.has(event.toolName)) {
+        return { block: false };
+      }
+      const active = provider.capability().active();
+      if (!active.ok || active.value === null) {
+        return {
+          block: true,
+          reason: active.ok
+            ? "Start a complete self-assigned leaf with todo before shell, code, mutation, or unknown tools."
+            : active.error.message,
+        };
+      }
+      provider.lease(event.toolCallId, active.value.ref);
+      return { block: false };
+    });
+    pi.on("tool_execution_end", (event: Readonly<{ toolCallId: string }>) => {
+      provider.release(event.toolCallId);
+    });
+  };
+
+export { registerGate };

package/src/generated/todo_core.d.ts

@@ -1,11 +1,21 @@
 /* tslint:disable */
 /* eslint-disable */
+/**
+ * A draft leaf; local keys are resolved only within its creation request.
+ */
+export interface DraftItem {
+    content: string;
+    key?: string | undefined;
+    contract?: ContractDraft;
+}
+
 /**
  * A leaf work unit. Grandchildren are not accepted.
  */
 export interface Subtask {
     content: string;
     status: Status;
+    unit?: Unit;
 }
 
 /**
@@ -23,6 +33,27 @@ export interface Task {
     content: string;
     status: Status;
     subtasks?: Subtask[];
+    unit?: Unit;
+}
+
+/**
+ * Atomic claim snapshot and its exported result.
+ */
+export interface ClaimChange {
+    list: TodoList;
+    persist: boolean;
+    value: ClaimResult;
+}
+
+/**
+ * Author-editable fields. A draft can omit fields but cannot supply invalid values.
+ */
+export interface ContractDraft {
+    deliverable?: string;
+    scope?: Scope;
+    acceptance?: Acceptance;
+    dependsOn?: string[];
+    assignment?: Assignment;
 }
 
 /**
@@ -33,13 +64,149 @@ export interface ReminderHistory {
 }
 
 /**
- * Exact task content, scoped by an optional root parent.
+ * Branch provenance of one immutable contract revision.
+ */
+export interface UnitRef {
+    sessionId: string;
+    unitId: string;
+    revision: number;
+    /**
+     * Empty only until the containing Pi entry has been appended and read.
+     */
+    contractEntryId: string;
+}
+
+/**
+ * Child creation never accepts another outcome.
+ */
+export type LeafItem = string | DraftItem;
+
+/**
+ * Complete contract projection used at the component boundary.
+ */
+export interface UnitContract {
+    ref: UnitRef;
+    title: string;
+    deliverable: string;
+    scope: Scope;
+    acceptance: Acceptance;
+    dependsOn: string[];
+    assignment: Assignment;
+}
+
+/**
+ * Completed prerequisite revision frozen at claim time.
+ */
+export interface Prerequisite {
+    unitId: string;
+    completedRevision: number;
+}
+
+/**
+ * Concrete WASM settlement response.
+ */
+export interface SettlementChange {
+    list: TodoList;
+    persist: boolean;
+    value: SettlementResult;
+}
+
+/**
+ * Desired executor, not a process or a model override.
+ */
+export type Assignment = { kind: "self" } | { kind: "worker"; profile: string };
+
+/**
+ * Durable accepted event identity survives a new binding or revision.
+ */
+export interface AcceptedEvent {
+    origin: UnitRef;
+    execution: ExecutionRef;
+    eventId: string;
+}
+
+/**
+ * Evidence for an execution which obtained an export digest.
+ */
+export type BoundResult = { kind: "returned"; evidence: EvidenceRef } | { kind: "stopped"; evidence?: EvidenceRef; reason: string };
+
+/**
+ * Evidence requirement. Creating a command does not execute it.
+ */
+export type Acceptance = { kind: "command"; cwd: string; argv: string[]; expected: string } | { kind: "review"; artifact: string; criterion: string };
+
+/**
+ * Exact revision/execution correlation, not runtime worker state.
+ */
+export interface TaskBinding {
+    contract: UnitRef;
+    execution: ExecutionRef;
+    exportDigest: string;
+}
+
+/**
+ * Exactly the binding and export persisted in the claim snapshot.
+ */
+export interface ClaimResult {
+    binding: TaskBinding;
+    exported: TaskExport;
+}
+
+/**
+ * Executor-owned release facts; unknown outcomes never release a hold.
+ */
+export type Settlement = { version: number; eventId: string; binding: TaskBinding; result: BoundResult } | { version: number; eventId: string; origin: UnitRef; execution: ExecutionRef; result: UnstartedResult };
+
+/**
+ * Executor-owned transport; task semantics are validated here.
+ */
+export interface Seed {
+    version: number;
+    execution: ExecutionRef;
+    binding: TaskBinding;
+    exported: TaskExport;
+}
+
+/**
+ * Export envelope; the digest excludes only its own field.
+ */
+export interface TaskExport {
+    version: number;
+    provider: string;
+    contract: UnitContract;
+    prerequisites: Prerequisite[];
+    brief: string;
+    digest: string;
+}
+
+/**
+ * Frozen import and its local session, not an executor lifecycle record.
+ */
+export interface ImportedUnit {
+    seed: Seed;
+    localSessionId: string;
+    seal: Seal | undefined;
+}
+
+/**
+ * IDs address migrated tasks; exact labels address only legacy records.
  */
 export interface Request {
     op: Operation;
     items?: readonly Item[] | undefined;
     task?: string | undefined;
     parent?: string | undefined;
+    contract?: ContractDraft | undefined;
+    start?: string | undefined;
+    evidence?: string | undefined;
+}
+
+/**
+ * Immutable local completion evidence. Pi derives the containing entry ID on replay.
+ */
+export interface Seal {
+    entryId: string;
+    disposition: Status;
 }
 
 /**
@@ -50,25 +217,99 @@ export interface WidgetRow {
     text: string;
 }
 
+/**
+ * Opaque executor identity; no process interpretation belongs here.
+ */
+export interface ExecutionRef {
+    executor: string;
+    ownerId: string;
+    requestId: string;
+}
+
+/**
+ * Optimistic claim identity, supplied by a cooperating extension.
+ */
+export interface ClaimInput {
+    expected: UnitRef;
+    execution: ExecutionRef;
+}
+
+/**
+ * Ordered digest projection. Struct declaration order is the wire order.
+ */
+export interface ExportData {
+    version: number;
+    provider: string;
+    contract: UnitContract;
+    prerequisites: Prerequisite[];
+    brief: string;
+}
+
+/**
+ * Precommit abandonment has no export digest.
+ */
+export type UnstartedResult = { kind: "not_started"; reason: string };
+
+/**
+ * Provider acknowledgement, including closure after activation ends.
+ */
+export interface ImportReceipt {
+    version: number;
+    execution: ExecutionRef;
+    unitRef: UnitRef;
+    digest: string;
+    localSessionId: string;
+    seal: Seal | undefined;
+}
+
 /**
  * Relevant facts in branch order, including proposed boundary entries.
  */
 export type ReminderFact = { kind: "user" } | { kind: "snapshot"; list: TodoList } | { kind: "reminder" };
 
+/**
+ * Repository-relative declared scope, not a filesystem permission grant.
+ */
+export interface Scope {
+    repositoryId: string;
+    owns: string[];
+    reads: string[];
+    generates: string[];
+}
+
 /**
  * Root creation accepts standalone outcomes or outcomes with leaf work units.
  */
-export type Item = string | { content: string; subtasks: readonly string[] };
+export type Item = string | { content: string; subtasks: LeafItem[] } | DraftItem;
 
 /**
  * Semantic styling for a terminal row.
  */
 export type WidgetKind = "heading" | "active" | "upcoming" | "done" | "dropped" | "summary";
 
+/**
+ * Stored task metadata, independent of process execution state.
+ */
+export interface Unit {
+    reference: UnitRef;
+    draft: ContractDraft;
+    localSessionId?: string;
+    acceptanceEvidence?: string;
+    binding?: TaskBinding;
+    frozenExportJson?: string;
+    evidence?: EvidenceRef[];
+    acceptedEvents?: AcceptedEvent[];
+    /**
+     * The last claimed revision cannot launch again after settlement.
+     */
+    attemptedRevision?: number;
+    imported?: ImportedUnit;
+}
+
 /**
  * Supported model-facing operations.
  */
-export type Operation = "init" | "start" | "done" | "drop" | "append" | "view";
+export type Operation = "init" | "start" | "done" | "drop" | "append" | "view" | "update";
 
 /**
  * The state of one outcome or work unit.
@@ -82,6 +323,47 @@ export interface TodoList {
     tasks: Task[];
 }
 
+/**
+ * Trusted runtime identity, separate from agent-authored tool parameters.
+ */
+export interface MutationContext {
+    sessionId: string;
+    mutationId: string;
+}
+
+/**
+ * Untrusted worker result reference, never acceptance.
+ */
+export interface EvidenceRef {
+    execution: ExecutionRef;
+    resultId: string;
+    summary: string;
+}
+
+/**
+ * Validated local activation, not a worker-state projection.
+ */
+export interface ActiveUnit {
+    ref: UnitRef;
+    localSessionId: string;
+    seeded: boolean;
+}
+
+/**
+ * Whether settlement changed this branch.
+ */
+export interface SettlementResult {
+    applied: boolean;
+}
+
+
+/**
+ * Reads validated current-session activation.
+ *
+ * # Errors
+ * Rejects invalid persisted state.
+ */
+export function active(list: TodoList, session_id: string): ActiveUnit | undefined;
 
 /**
  * Applies one validated operation.
@@ -90,7 +372,15 @@ export interface TodoList {
  *
  * Throws for malformed input or a rejected operation.
  */
-export function apply(list: TodoList, request: Request): Change;
+export function apply(list: TodoList, request: unknown, context: MutationContext): Change;
+
+/**
+ * Validates and atomically freezes a worker contract.
+ *
+ * # Errors
+ * Rejects malformed requests, stale origins and competing claims.
+ */
+export function claim(list: TodoList, input: string, session_id: string): ClaimChange;
 
 /**
  * Computes completion policy from branch facts.
@@ -101,6 +391,22 @@ export function apply(list: TodoList, request: Request): Change;
  */
 export function completion_reminder(facts: ReminderHistory): string | undefined;
 
+/**
+ * Imports one validated seed into a fresh worker session.
+ *
+ * # Errors
+ * Rejects invalid seed, repository identity or existing work.
+ */
+export function import_unit(list: TodoList, input: string, session_id: string, repository_id: string): Change;
+
+/**
+ * Reads immutable import acknowledgement and closure evidence.
+ *
+ * # Errors
+ * Rejects invalid persisted state.
+ */
+export function imported(list: TodoList, session_id: string): ImportReceipt | undefined;
+
 /**
  * Replaces the whole list with `items`.
  *
@@ -110,6 +416,14 @@ export function completion_reminder(facts: ReminderHistory): string | undefined;
  */
 export function init(items: string[]): TodoList;
 
+/**
+ * Reads a complete task contract.
+ *
+ * # Errors
+ * Rejects unknown IDs or incomplete contracts.
+ */
+export function inspect(list: TodoList, id: string): UnitContract;
+
 /**
  * Validates a stored snapshot. It comes from the session file, so it is typed
  * `unknown` and checked here, by the type that owns its shape.
@@ -120,6 +434,22 @@ export function init(items: string[]): TodoList;
  */
 export function parse(snapshot: unknown): TodoList;
 
+/**
+ * Prevents mutations of revisions with an in-flight tool call.
+ *
+ * # Errors
+ * Rejects closure, replacement or alteration of any leased revision.
+ */
+export function protect(before: TodoList, after: TodoList, leases: UnitRef[]): void;
+
+/**
+ * Records an executor's exact release evidence, never acceptance.
+ *
+ * # Errors
+ * Rejects malformed or mismatched settlements.
+ */
+export function settle(list: TodoList, input: string, session_id: string): SettlementChange;
+
 /**
  * The model-facing summary of `list`.
  *
@@ -142,10 +472,17 @@ export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembl
 
 export interface InitOutput {
     readonly memory: WebAssembly.Memory;
-    readonly apply: (a: number, b: number, c: number) => void;
+    readonly active: (a: number, b: number, c: number, d: number) => void;
+    readonly apply: (a: number, b: number, c: number, d: number) => void;
+    readonly claim: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
     readonly completion_reminder: (a: number, b: number) => void;
+    readonly import_unit: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => void;
+    readonly imported: (a: number, b: number, c: number, d: number) => void;
     readonly init: (a: number, b: number, c: number) => void;
+    readonly inspect: (a: number, b: number, c: number, d: number) => void;
     readonly parse: (a: number, b: number) => void;
+    readonly protect: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly settle: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
     readonly view: (a: number, b: number) => void;
     readonly widget: (a: number, b: number, c: number) => void;
     readonly __wbindgen_export: (a: number, b: number) => number;