opencode-session-todo 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexandru Nedelcu
+
+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,32 @@
-# Temporary Holding Version
+# OpenCode 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.
+**A task list that stays with your session.**
+
+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.
+
+## Get started
+
+Add to `opencode.jsonc`:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": [
+    {
+      "package": "opencode-session-todo",
+      "options": {
+        "sidebarLimit": 5,
+      },
+    },
+  ],
+}
+```
+
+Reload OpenCode and reopen the TUI.
+
+- **Read and write** with `todoread` and `todowrite`, with conflict detection and change diffs.
+- **Keep tasks in view** in the sidebar; open `/todos` for the full list.
+- **Own the file** at `.agents/sessions/<session-id>/todo.txt`.
+
+[Usage & permissions](USAGE.md) · [Development & publishing](docs/development.md) · [MIT](LICENSE)

package/USAGE.md

@@ -0,0 +1,83 @@
+# Session TODOs
+
+## Setup
+
+Configure the plugin in `opencode.jsonc`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": [{ "package": "opencode-session-todo", "options": { "sidebarLimit": 5 } }]
+}
+```
+
+Then reload OpenCode:
+
+```sh
+opencode reload
+```
+
+Reopen the TUI after configuration changes. `sidebarLimit` is a positive integer, default **5**.
+
+## Tools
+
+Only root sessions expose these tools and receive the TODO lifecycle instructions. Subagents see neither tool.
+
+- `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.
+
+```json
+{
+  "previous": [],
+  "todos": [
+    { "content": "Run the tests", "status": "in_progress", "priority": "high" }
+  ]
+}
+```
+
+Statuses: `pending`, `in_progress`, `completed`, `cancelled`. Priorities: `high`, `medium`, `low`.
+At most one task may be `in_progress`. Content must be one nonempty trimmed line,
+cannot begin with a priority/date, and cannot contain `status:` or `pri:` tokens.
+
+## TUI
+
+- Click **TODO** or its `▼` / `▶` arrow to expand or collapse the sidebar list.
+- Above `sidebarLimit` total tasks, the sidebar shows only unfinished tasks, capped at the limit,
+  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
+
+```text
+<project/worktree>/.agents/sessions/<session-id>/todo.txt
+```
+
+```text
+(A) Run the tests status:in_progress
+(B) Review the changes
+x Read the docs pri:C
+x Superseded approach pri:B status:cancelled
+```
+
+`A` / `B` / `C` map to high / medium / low; other priority letters are unsupported.
+Add `.agents/sessions/` to your project's ignore rules to keep these files out of version control.
+
+## Permissions
+
+Both tools use `todowrite`. Writes require agent/session rules resolving to `allow`; `ask` and
+`deny` are rejected. Approval prompts, saved approvals, and experimental policies are unsupported.
+Read-only agents should deny `todowrite`.
+
+## Commands
+
+From the repository root:
+
+```sh
+bun run check
+bun test
+bun run format       # dprint fmt
+bun run format:check # dprint check
+```

package/dist/tui.js

@@ -0,0 +1,433 @@
+// @bun
+// tui.tsx
+import { createTextNode as _$createTextNode } from "@opentui/solid";
+import { insertNode as _$insertNode } from "@opentui/solid";
+import { createComponent as _$createComponent } from "@opentui/solid";
+import { effect as _$effect } from "@opentui/solid";
+import { insert as _$insert } from "@opentui/solid";
+import { memo as _$memo } from "@opentui/solid";
+import { setProp as _$setProp } from "@opentui/solid";
+import { createElement as _$createElement } from "@opentui/solid";
+import { Plugin } from "@opencode/plugin/tui";
+import { Session as Session2 } from "@opencode/schema/session";
+import { Effect as Effect2, Result, Schema as Schema4 } from "effect";
+import { createEffect, createMemo, createSignal, For, onCleanup, Show } from "solid-js";
+
+// rpc.ts
+import { Rpc } from "@opencode/schema/rpc";
+import { Session } from "@opencode/schema/session";
+import { Schema as Schema2 } from "effect";
+
+// src/model.ts
+import { Schema } from "effect";
+var Content = Schema.String.check(Schema.isMinLength(1), Schema.isTrimmed(), Schema.isPattern(/^[^\r\n\x00]+$/), Schema.makeFilter((value) => !/^(?:\([A-Z]\) |\d{4}-\d{2}-\d{2}(?: |$))/.test(value) && !/(?:^|\s)(?:status|pri):/.test(value), {
+  message: "Task text must not start with a priority/date or contain reserved status:/pri: tokens"
+})).pipe(Schema.brand("TodoContent"));
+var Status = Schema.Literals(["pending", "in_progress", "completed", "cancelled"]);
+var Priority = Schema.Literals(["high", "medium", "low"]);
+var Todo = Schema.Struct({ content: Content, status: Status, priority: Priority });
+var Todos = Schema.Array(Todo).check(Schema.makeFilter((todos) => {
+  let active = false;
+  for (const todo of todos) {
+    if (todo.status !== "in_progress")
+      continue;
+    if (active)
+      return false;
+    active = true;
+  }
+  return true;
+}, { message: "At most one todo may be in_progress" })).pipe(Schema.brand("TodoList"));
+var SessionName = Schema.String.check(Schema.isPattern(/^[A-Za-z0-9][A-Za-z0-9_-]*$/)).pipe(Schema.brand("TodoSessionName"));
+var Snapshot = Schema.Struct({ path: Schema.String, todos: Todos });
+
+class TodoError extends Schema.TaggedError()("TodoError", {
+  message: Schema.String
+}) {
+}
+
+// rpc.ts
+var TodoRpc = Rpc.define({
+  id: "session-todo",
+  methods: {
+    read: {
+      input: Schema2.toStandardSchemaV1(Schema2.Struct({ sessionID: Session.ID })),
+      output: Schema2.toStandardSchemaV1(Snapshot),
+      errors: { storage: Schema2.toStandardSchemaV1(Schema2.Struct({ message: Schema2.String })) }
+    }
+  },
+  events: {
+    updated: {
+      schema: Schema2.toStandardSchemaV1(Schema2.Struct({ sessionID: Session.ID, diff: Schema2.String }))
+    }
+  }
+});
+
+// src/sidebar.ts
+import { Effect, Schema as Schema3 } from "effect";
+var SidebarLimit = Schema3.Int.check(Schema3.isGreaterThan(0)).pipe(Schema3.brand("TodoSidebarLimit"));
+var SidebarOptions = Schema3.Struct({
+  sidebarLimit: SidebarLimit.pipe(Schema3.withDecodingDefaultKey(Effect.succeed(5)))
+});
+var incomplete = (todo) => todo.status === "pending" || todo.status === "in_progress";
+var projectTodos = (todos, mode) => {
+  if (mode === "full" || todos.length <= mode) {
+    return {
+      kind: "all",
+      items: todos,
+      remaining: todos.reduce((count, todo) => count + Number(incomplete(todo)), 0)
+    };
+  }
+  const items = [];
+  let remaining = 0;
+  for (const todo of todos) {
+    if (!incomplete(todo))
+      continue;
+    remaining += 1;
+    if (todo.status === "in_progress") {
+      if (items.length === mode)
+        items.pop();
+      items.unshift(todo);
+    } else if (items.length < mode)
+      items.push(todo);
+  }
+  return { kind: "limited", items, remaining, total: todos.length };
+};
+
+// tui.tsx
+var symbols = {
+  pending: "[ ]",
+  in_progress: "[\u2022]",
+  completed: "[\u2713]",
+  cancelled: "[\u2013]"
+};
+var colorFor = (status, theme) => {
+  switch (status) {
+    case "pending":
+      return theme.text.base;
+    case "in_progress":
+      return theme.text.feedback.warning.base;
+    case "completed":
+      return theme.text.muted;
+    case "cancelled":
+      return theme.text.feedback.error.base;
+  }
+};
+var Message = Schema4.Struct({
+  message: Schema4.String
+});
+var messageFor = (error) => Schema4.is(Message)(error) ? error.message : String(error);
+var tui_default = Plugin.define({
+  id: "session-todo",
+  setup(ctx) {
+    const options = Schema4.decodeUnknownResult(SidebarOptions)(ctx.options);
+    if (Result.isFailure(options)) {
+      ctx.ui.toast.show({
+        title: "Invalid TODO sidebar options",
+        message: options.failure.message,
+        variant: "error"
+      });
+      return () => {};
+    }
+    const api = ctx.client.rpc(TodoRpc);
+    const [sidebarView, updateSidebarView] = ctx.storage.store("sidebar", {
+      initial: {
+        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"
+      });
+      createEffect(() => {
+        const sessionID = props.sessionID;
+        setView({
+          status: "loading"
+        });
+        const controller = new AbortController;
+        let running = false;
+        const refresh = () => {
+          if (running || controller.signal.aborted)
+            return;
+          running = true;
+          const request = Schema4.decodeUnknownEffect(Session2.ID)(sessionID).pipe(Effect2.flatMap((id) => Effect2.tryPromise({
+            try: () => api.read({
+              sessionID: id
+            }, {
+              signal: controller.signal,
+              location: ctx.data.session.get(sessionID)?.location ?? ctx.location ?? ctx.data.location.default()
+            }),
+            catch: (error) => error
+          })));
+          Effect2.runPromise(request.pipe(Effect2.match({
+            onSuccess: (snapshot) => ({
+              status: "ready",
+              snapshot
+            }),
+            onFailure: (error) => ({
+              status: "error",
+              message: messageFor(error)
+            })
+          }))).then((next) => {
+            if (!controller.signal.aborted)
+              setView(next);
+          }).catch((error) => {
+            if (!controller.signal.aborted) {
+              setView({
+                status: "error",
+                message: messageFor(error)
+              });
+            }
+          }).finally(() => {
+            running = false;
+          });
+        };
+        refresh();
+        const timer = setInterval(refresh, 2000);
+        const unsubscribe = api.events.on("updated", (event) => {
+          if (event.data.sessionID === sessionID)
+            refresh();
+        });
+        onCleanup(() => {
+          controller.abort();
+          clearInterval(timer);
+          unsubscribe();
+        });
+      });
+      const snapshot = () => {
+        const current = view();
+        return current.status === "ready" ? current.snapshot : undefined;
+      };
+      const projection = createMemo(() => {
+        const current = snapshot();
+        return current === undefined ? undefined : projectTodos(current.todos, props.full ? "full" : options.success.sidebarLimit);
+      });
+      const todos = () => projection()?.items ?? [];
+      const active = () => projection()?.remaining ?? 0;
+      const more = () => {
+        const current = projection();
+        return current?.kind === "limited" ? current.total : undefined;
+      };
+      const error = () => {
+        const current = view();
+        return current.status === "error" ? current.message : undefined;
+      };
+      const visible = () => Boolean(props.full || snapshot()?.todos.length || error());
+      return _$createComponent(Show, {
+        get when() {
+          return visible();
+        },
+        get children() {
+          var _el$ = _$createElement("box"), _el$2 = _$createElement("box"), _el$4 = _$createElement("text"), _el$5 = _$createElement("b"), _el$7 = _$createElement("span"), _el$8 = _$createTextNode(` (`), _el$0 = _$createTextNode(` remaining)`);
+          _$insertNode(_el$, _el$2);
+          _$setProp(_el$, "flexDirection", "column");
+          _$setProp(_el$, "gap", 0);
+          _$setProp(_el$, "paddingTop", 1);
+          _$insertNode(_el$2, _el$4);
+          _$setProp(_el$2, "flexDirection", "row");
+          _$setProp(_el$2, "gap", 1);
+          _$setProp(_el$2, "onMouseDown", (event) => {
+            if (props.full)
+              return;
+            event.stopPropagation();
+            updateSidebarView((draft) => {
+              draft.open = !draft.open;
+            }).catch((error) => {
+              ctx.ui.toast.show({
+                title: "Todo sidebar",
+                message: `Cannot save expanded state: ${messageFor(error)}`,
+                variant: "error"
+              });
+            });
+          });
+          _$insert(_el$2, _$createComponent(Show, {
+            get when() {
+              return !props.full;
+            },
+            get children() {
+              var _el$3 = _$createElement("text");
+              _$insert(_el$3, () => sidebarView.open ? "\u25BC" : "\u25B6");
+              _$effect((_$p) => _$setProp(_el$3, "fg", ctx.theme.text.base, _$p));
+              return _el$3;
+            }
+          }), _el$4);
+          _$insertNode(_el$4, _el$5);
+          _$insertNode(_el$4, _el$7);
+          _$insertNode(_el$5, _$createTextNode(`TODO`));
+          _$insertNode(_el$7, _el$8);
+          _$insertNode(_el$7, _el$0);
+          _$insert(_el$7, active, _el$0);
+          _$insert(_el$, _$createComponent(Show, {
+            get when() {
+              return props.full || sidebarView.open;
+            },
+            get children() {
+              return [_$createComponent(Show, {
+                get when() {
+                  return props.full;
+                },
+                get children() {
+                  var _el$1 = _$createElement("text");
+                  _$insert(_el$1, () => snapshot()?.path ?? "Loading todo.txt\u2026");
+                  _$effect((_$p) => _$setProp(_el$1, "fg", ctx.theme.text.muted, _$p));
+                  return _el$1;
+                }
+              }), _$createComponent(Show, {
+                get when() {
+                  return error();
+                },
+                get children() {
+                  var _el$10 = _$createElement("text"), _el$11 = _$createTextNode(`Cannot read todos: `);
+                  _$insertNode(_el$10, _el$11);
+                  _$insert(_el$10, error, null);
+                  _$effect((_$p) => _$setProp(_el$10, "fg", ctx.theme.text.feedback.error.base, _$p));
+                  return _el$10;
+                }
+              }), _$createComponent(Show, {
+                get when() {
+                  return _$memo(() => !!(props.full && view().status === "ready"))() && todos().length === 0;
+                },
+                get children() {
+                  var _el$12 = _$createElement("text");
+                  _$insertNode(_el$12, _$createTextNode(`No todos for this session.`));
+                  _$effect((_$p) => _$setProp(_el$12, "fg", ctx.theme.text.muted, _$p));
+                  return _el$12;
+                }
+              }), _$createComponent(For, {
+                get each() {
+                  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);
+                  _$effect((_$p) => _$setProp(_el$17, "fg", colorFor(todo.status, ctx.theme), _$p));
+                  return _el$17;
+                })()
+              }), _$createComponent(Show, {
+                get when() {
+                  return more();
+                },
+                get children() {
+                  var _el$14 = _$createElement("text"), _el$15 = _$createTextNode(`Show all `), _el$16 = _$createTextNode(` todos \u2192`);
+                  _$insertNode(_el$14, _el$15);
+                  _$insertNode(_el$14, _el$16);
+                  _$setProp(_el$14, "onMouseDown", (event) => {
+                    event.stopPropagation();
+                    ctx.ui.panel.open("session-todo.list");
+                  });
+                  _$insert(_el$14, more, _el$16);
+                  _$effect((_$p) => _$setProp(_el$14, "fg", ctx.theme.text.feedback.info.base, _$p));
+                  return _el$14;
+                }
+              })];
+            }
+          }), null);
+          _$effect((_p$) => {
+            var _v$ = ctx.theme.text.base, _v$2 = {
+              fg: ctx.theme.text.muted
+            };
+            _v$ !== _p$.e && (_p$.e = _$setProp(_el$4, "fg", _v$, _p$.e));
+            _v$2 !== _p$.t && (_p$.t = _$setProp(_el$7, "style", _v$2, _p$.t));
+            return _p$;
+          }, {
+            e: undefined,
+            t: undefined
+          });
+          return _el$;
+        }
+      });
+    };
+    const sidebar = ctx.ui.slot({
+      append: "sidebar.content",
+      render: (props) => _$createComponent(List, {
+        get sessionID() {
+          return props.sessionID;
+        }
+      })
+    });
+    const Panel = (props) => {
+      ctx.keymap.layer(() => ({
+        mode: "global",
+        enabled: props.focused,
+        commands: [{
+          bind: "escape",
+          title: "Close session todos",
+          run: props.close
+        }]
+      }));
+      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) => {
+          event.stopPropagation();
+          props.close();
+        });
+        _$setProp(_el$23, "flexGrow", 1);
+        _$insert(_el$23, _$createComponent(List, {
+          get sessionID() {
+            return props.sessionID;
+          },
+          full: true
+        }));
+        _$effect((_$p) => _$setProp(_el$21, "fg", ctx.theme.text.base, _$p));
+        return _el$20;
+      })();
+    };
+    const panel = ctx.ui.slot({
+      append: "session.panel",
+      render: (props) => _$createComponent(Show, {
+        get when() {
+          return props.name === "session-todo.list";
+        },
+        get children() {
+          return _$createComponent(Panel, props);
+        }
+      })
+    });
+    ctx.keymap.layer(() => ({
+      mode: "global",
+      commands: [{
+        id: "session-todo.list",
+        title: "Toggle session todos",
+        group: "Session",
+        palette: true,
+        slash: {
+          name: "todos"
+        },
+        enabled: ctx.ui.router.current().type === "session",
+        run: () => {
+          if (ctx.ui.panel.current()?.name === "session-todo.list")
+            ctx.ui.panel.close();
+          else
+            ctx.ui.panel.open("session-todo.list");
+        }
+      }]
+    }));
+    return () => {
+      sidebar();
+      panel();
+      notify();
+    };
+  }
+});
+export {
+  tui_default as default
+};

package/docs/development.md

@@ -0,0 +1,28 @@
+# Development
+
+Requires Bun >= 1.4.2.
+
+```sh
+bun ci
+make test
+```
+
+`make test` runs typecheck, tests, and formatting checks.
+`make upgrade-dependencies` updates pinned dependencies and the lockfile.
+
+## Package entry points
+
+The package ships TypeScript sources for OpenCode's Bun runtime and precompiled Solid ESM for the TUI. Run `bun run build` before loading the local package; packing builds the TUI automatically.
+
+- `opencode-session-todo`: tools and RPC handlers.
+- `opencode-session-todo/tui`: sidebar and full panel.
+- `opencode-session-todo/rpc`: shared RPC definitions.
+
+## Publishing
+
+```sh
+npm login
+make publish
+```
+
+`make publish` runs the checks and a package dry-run before `npm publish --access public`.