opencode-session-todo 0.1.2 → 0.2.1

package/README.md

@@ -5,6 +5,8 @@
 Session-local [todo.txt](https://github.com/todotxt/todo.txt) for OpenCode V2.
 Tools for the agent. A sidebar for you. Plain text you can edit.
 
+[![npm version](https://img.shields.io/npm/v/opencode-session-todo)](https://www.npmjs.com/package/opencode-session-todo)
+
 ## Get started
 
 Add to `opencode.jsonc`:

package/USAGE.md

@@ -23,6 +23,9 @@ Reopen the TUI after configuration changes. `sidebarLimit` is a positive integer
 
 Only root sessions expose these tools and receive the TODO lifecycle instructions. Subagents see neither tool.
 
+Agents start a TODO list when they have more than one work item to track, not for a straightforward
+question or a single work item. Existing unfinished work remains tracked through completion.
+
 - `todoread({})` reads the current session's tasks and file path. Missing files return an empty list.
 - `todowrite({ previous, todos })` replaces the ordered list only when the stored list still equals `previous`; take `previous` from the latest `todoread` or `todowrite` result. A mismatch fails with an instruction to `todoread` and retry. The result reports a before/after diff. An empty `todos` array clears the list.
 
@@ -46,7 +49,6 @@ cannot begin with a priority/date, and cannot contain `status:` or `pri:` tokens
   with the active task first.
 - **Show all …**, `/todos`, or **Ctrl+P → Toggle session todos** opens the full scrollable panel.
 - Close with **Close ×**, **Esc** while focused, or the same command-palette action.
-- Each `todowrite` pops a toast with the before/after diff of the change.
 - Manual file edits appear within two seconds. Collapsing does not change the tasks.
 
 ## Storage

package/dist/tui.js

@@ -57,7 +57,7 @@ var TodoRpc = Rpc.define({
   },
   events: {
     updated: {
-      schema: Schema2.toStandardSchemaV1(Schema2.Struct({ sessionID: Session.ID, diff: Schema2.String }))
+      schema: Schema2.toStandardSchemaV1(Schema2.Struct({ sessionID: Session.ID, diff: Schema2.String, summary: Schema2.String }))
     }
   }
 });
@@ -93,13 +93,16 @@ var projectTodos = (todos, mode) => {
   return { kind: "limited", items, remaining, total: todos.length };
 };
 
-// tui.tsx
-var symbols = {
+// src/summary.ts
+var todoSymbols = {
   pending: "[ ]",
   in_progress: "[\u2022]",
   completed: "[\u2713]",
   cancelled: "[\u2013]"
 };
+var formatTodo = (todo) => `${todoSymbols[todo.status]} ${todo.content} \xB7 ${todo.priority}`;
+
+// tui.tsx
 var colorFor = (status, theme) => {
   switch (status) {
     case "pending":
@@ -134,16 +137,6 @@ var tui_default = Plugin.define({
         open: true
       }
     });
-    const notify = api.events.on("updated", (event) => {
-      if (event.data.diff === "")
-        return;
-      ctx.ui.toast.show({
-        title: "TODO updated",
-        message: event.data.diff,
-        variant: "info",
-        sessionID: event.data.sessionID
-      });
-    });
     const List = (props) => {
       const [view, setView] = createSignal({
         status: "loading"
@@ -307,12 +300,8 @@ var tui_default = Plugin.define({
                   return todos();
                 },
                 children: (todo) => (() => {
-                  var _el$17 = _$createElement("text"), _el$18 = _$createTextNode(` `), _el$19 = _$createTextNode(` \xB7 `);
-                  _$insertNode(_el$17, _el$18);
-                  _$insertNode(_el$17, _el$19);
-                  _$insert(_el$17, () => symbols[todo.status], _el$18);
-                  _$insert(_el$17, () => todo.content, _el$19);
-                  _$insert(_el$17, () => todo.priority, null);
+                  var _el$17 = _$createElement("text");
+                  _$insert(_el$17, () => formatTodo(todo));
                   _$effect((_$p) => _$setProp(_el$17, "fg", colorFor(todo.status, ctx.theme), _$p));
                   return _el$17;
                 })()
@@ -369,26 +358,26 @@ var tui_default = Plugin.define({
         }]
       }));
       return (() => {
-        var _el$20 = _$createElement("box"), _el$21 = _$createElement("text"), _el$23 = _$createElement("scrollbox");
-        _$insertNode(_el$20, _el$21);
-        _$insertNode(_el$20, _el$23);
-        _$setProp(_el$20, "flexDirection", "column");
-        _$setProp(_el$20, "flexGrow", 1);
-        _$setProp(_el$20, "padding", 1);
-        _$insertNode(_el$21, _$createTextNode(`Close \xD7 \xB7 Esc when focused \xB7 Ctrl+P to toggle`));
-        _$setProp(_el$21, "onMouseDown", (event) => {
+        var _el$18 = _$createElement("box"), _el$19 = _$createElement("text"), _el$21 = _$createElement("scrollbox");
+        _$insertNode(_el$18, _el$19);
+        _$insertNode(_el$18, _el$21);
+        _$setProp(_el$18, "flexDirection", "column");
+        _$setProp(_el$18, "flexGrow", 1);
+        _$setProp(_el$18, "padding", 1);
+        _$insertNode(_el$19, _$createTextNode(`Close \xD7 \xB7 Esc when focused \xB7 Ctrl+P to toggle`));
+        _$setProp(_el$19, "onMouseDown", (event) => {
           event.stopPropagation();
           props.close();
         });
-        _$setProp(_el$23, "flexGrow", 1);
-        _$insert(_el$23, _$createComponent(List, {
+        _$setProp(_el$21, "flexGrow", 1);
+        _$insert(_el$21, _$createComponent(List, {
           get sessionID() {
             return props.sessionID;
           },
           full: true
         }));
-        _$effect((_$p) => _$setProp(_el$21, "fg", ctx.theme.text.base, _$p));
-        return _el$20;
+        _$effect((_$p) => _$setProp(_el$19, "fg", ctx.theme.text.base, _$p));
+        return _el$18;
       })();
     };
     const panel = ctx.ui.slot({
@@ -424,7 +413,6 @@ var tui_default = Plugin.define({
     return () => {
       sidebar();
       panel();
-      notify();
     };
   }
 });

package/index.ts

@@ -10,9 +10,15 @@ import { Effect, Schema, type Scope } from "effect"
 import { resolve } from "node:path"
 import { TodoRpc } from "./rpc.ts"
 import { diffTodos } from "./src/diff.ts"
-import { TodoInstructions } from "./src/instructions.ts"
+import {
+  TodoInstructions,
+  TodoLifecycleInstructions,
+  TodoReadInstructions,
+  TodoWriteInstructions,
+} from "./src/instructions.ts"
 import { Snapshot, TodoError, Todos } from "./src/model.ts"
 import { makeTodoStore, SessionDirectory, type TodoStore, type WriteResult } from "./src/store.ts"
+import { summarizeTodos } from "./src/summary.ts"
 
 const WriteInput = Schema.Struct({ previous: Todos, todos: Todos })
 const ReadInput = Schema.Struct({})
@@ -157,7 +163,11 @@ export const register = (ctx: TodoPluginContext): Effect.Effect<void, never, Sco
       )
       const diff: string = diffTodos(saved.previous, saved.todos)
       yield* rpc.events
-        .emit("updated", { sessionID: context.sessionID, diff })
+        .emit("updated", {
+          sessionID: context.sessionID,
+          diff,
+          summary: summarizeTodos(saved.previous, saved.todos),
+        })
         .pipe(
           Effect.catch(
             (error): Effect.Effect<void> =>
@@ -191,8 +201,7 @@ export const register = (ctx: TodoPluginContext): Effect.Effect<void, never, Sco
     yield* ctx.tool.transform((editor): void => {
       editor.add({
         name: "todowrite",
-        description:
-          `Replace this session's ordered todo list when it still equals the \`previous\` list you send; take \`previous\` from the latest todoread or todowrite result in this conversation. A mismatch fails the write: use todoread, then retry. Status: pending, in_progress, completed, cancelled; at most one in_progress. Priority: high, medium, low. Text is one trimmed line; status:/pri: are reserved. An empty todos array clears the list. Persists as project-local todo.txt and updates the TUI.\n\n${TodoInstructions}`,
+        description: `${TodoWriteInstructions}\n\n${TodoLifecycleInstructions}`,
         input: WriteInput,
         output: Snapshot,
         options: { codemode: false, permission: "todowrite" },
@@ -200,8 +209,7 @@ export const register = (ctx: TodoPluginContext): Effect.Effect<void, never, Sco
       })
       editor.add({
         name: "todoread",
-        description:
-          `Read this session's todo.txt list and storage path. Use it to obtain the \`previous\` list todowrite expects, or to retry after a failed write; missing files mean an empty list.\n\n${TodoInstructions}`,
+        description: `${TodoReadInstructions}\n\n${TodoLifecycleInstructions}`,
         input: ReadInput,
         output: Snapshot,
         options: { codemode: false, permission: "todowrite" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-session-todo",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "Session-local todo.txt tools and TUI for OpenCode V2",
   "homepage": "https://github.com/alexandru/opencode-todo#readme",
   "bugs": {

package/rpc.ts

@@ -15,7 +15,7 @@ export const TodoRpc = Rpc.define({
   events: {
     updated: {
       schema: Schema.toStandardSchemaV1(
-        Schema.Struct({ sessionID: Session.ID, diff: Schema.String }),
+        Schema.Struct({ sessionID: Session.ID, diff: Schema.String, summary: Schema.String }),
       ),
     },
   },

package/src/instructions.ts

@@ -1,10 +1,33 @@
-export const TodoInstructions: string = `TODO lifecycle
+export const TodoWriteInstructions: string = `### \`todowrite\`
+
+Replace this session’s TODO list.
+
+- You MUST pass the last known saved list as \`previous\`; use \`[]\` when known empty.
+- You SHOULD reuse the returned saved list for subsequent writes.
+- On conflict, you MUST call \`todoread\` and retry.`
+
+export const TodoReadInstructions: string = `### \`todoread\`
+
+Read this session’s saved TODO list and storage path.
+
+- You SHOULD use \`todoread\` only when the saved list is unknown or \`todowrite\` reports a conflict.`
+
+export const TodoLifecycleInstructions: string = `### TODO lifecycle
+
+- You MUST create a TODO list when you have more than one work item to track.
+- You MUST NOT create a TODO list for a straightforward question or a single work item.
+- You MUST NOT split a single work item into artificial steps just to justify a TODO list.
+
+The following rules apply only when a TODO list is needed or already tracks unfinished work.
 
 - You MUST keep this session's TODO list synchronized with the requested work and its actual progress.
-- You MUST pass the list you expect to be stored as \`previous\` to every todowrite; when the write reports the stored list changed, you MUST use todoread and retry with the refreshed list. You MUST preserve existing tasks, order, statuses, and priorities unless actual progress or the user's instructions require a change.
+- You MUST preserve existing tasks, order, statuses, and priorities unless actual progress or the user's instructions require a change.
 - You MUST mark a task in_progress before starting it. You MUST keep at most one task in_progress.
 - You MUST mark a task completed immediately after finishing its work and required verification.
 - You MUST NOT mark blocked, failed, skipped, unfinished, or unverified work completed. Unstarted or deferred work MUST remain pending; cancelled work MUST be represented as cancelled.
 - You MUST update the list after each meaningful status transition. You MUST NOT batch status updates until the end of the conversation or leave finished work in_progress.
 - Before your final response, you MUST reconcile the list with what was actually done and accurately retain unfinished work.
 - You SHOULD keep task descriptions concise and actionable.`
+
+export const TodoInstructions: string =
+  `${TodoWriteInstructions}\n\n${TodoReadInstructions}\n\n${TodoLifecycleInstructions}`

package/src/summary.ts

@@ -0,0 +1,32 @@
+import type { Todo, Todos } from "./model.ts"
+
+export const todoSymbols: Readonly<Record<Todo["status"], string>> = {
+  pending: "[ ]",
+  in_progress: "[•]",
+  completed: "[✓]",
+  cancelled: "[–]",
+}
+
+export const formatTodo = (todo: Todo): string =>
+  `${todoSymbols[todo.status]} ${todo.content} · ${todo.priority}`
+
+const keyFor = (todo: Todo): string => `${todo.status}|${todo.priority}|${todo.content}`
+
+export const summarizeTodos = (previous: Todos, next: Todos): string => {
+  const unchanged: Map<string, number> = new Map()
+  for (const todo of previous) {
+    const key: string = keyFor(todo)
+    unchanged.set(key, (unchanged.get(key) ?? 0) + 1)
+  }
+  const lines: string[] = []
+  for (const todo of next) {
+    const key: string = keyFor(todo)
+    const remaining: number = unchanged.get(key) ?? 0
+    if (remaining > 0) {
+      unchanged.set(key, remaining - 1)
+    } else {
+      lines.push(formatTodo(todo))
+    }
+  }
+  return lines.join("\n")
+}

package/tui.tsx

@@ -17,6 +17,7 @@ import {
 import { TodoRpc } from "./rpc.ts"
 import { type Snapshot, type Todo } from "./src/model.ts"
 import { projectTodos, SidebarOptions, type TodoProjection } from "./src/sidebar.ts"
+import { formatTodo } from "./src/summary.ts"
 
 type View =
   | { readonly status: "loading" }
@@ -28,13 +29,6 @@ interface Props {
   readonly full?: boolean
 }
 
-const symbols: Readonly<Record<Todo["status"], string>> = {
-  pending: "[ ]",
-  in_progress: "[•]",
-  completed: "[✓]",
-  cancelled: "[–]",
-}
-
 const colorFor = (
   status: Todo["status"],
   theme: ResolvedTheme,
@@ -71,15 +65,6 @@ export default Plugin.define({
     const [sidebarView, updateSidebarView] = ctx.storage.store("sidebar", {
       initial: { open: true },
     })
-    const notify: () => void = api.events.on("updated", (event): void => {
-      if (event.data.diff === "") return
-      ctx.ui.toast.show({
-        title: "TODO updated",
-        message: event.data.diff,
-        variant: "info",
-        sessionID: event.data.sessionID,
-      })
-    })
     const List = (props: Props): JSX.Element => {
       const [view, setView] = createSignal<View>({ status: "loading" })
       createEffect((): void => {
@@ -207,7 +192,7 @@ export default Plugin.define({
               <For each={todos()}>
                 {(todo): JSX.Element => (
                   <text fg={colorFor(todo.status, ctx.theme)}>
-                    {symbols[todo.status]} {todo.content} · {todo.priority}
+                    {formatTodo(todo)}
                   </text>
                 )}
               </For>
@@ -293,7 +278,6 @@ export default Plugin.define({
     return (): void => {
       sidebar()
       panel()
-      notify()
     }
   },
 })