pikuri-tasks 0.0.6 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ceab6f3f6999fb22176982adb511db13d445cba7044a435492071f2308f4eae
-  data.tar.gz: da032f405772ada2943df18113c1b4670799003069c5f329676d4bdc765d4397
+  metadata.gz: bef39f17faad60151665971aac68c2090ca08d02e343ce209ca00cdc81e4e7c5
+  data.tar.gz: bc0e54db37e868a58015c8ff18f0a9aba2a7e1232310faa608fcd4e525e2aea8
 SHA512:
-  metadata.gz: 7e74049b277b94b546f6e7a6a237e0e595aee40c7bd78fb7029bdb75c9eca36d52144ea97cd71f7215dfcf7a1dbea8c8270c6ef6f8125bd256b27c413d8a2566
-  data.tar.gz: 8a46f113b26b1014b34b434fe8b2a79eccef7c2a587dc4ffff8ead471b96ebbf5f8c4cb642934938ef244b39cc5cde6ea4f6ac9a0d272322edbccff05c5a5e24
+  metadata.gz: 6583cca82b6b2b8ac13169ce045420cb960a06157a2cc2f4da7f6ebbbbb232066ae58d9b484c4736bc509b4c78625265a5b84838cd44e9cbe2dbd94c5575fbb0
+  data.tar.gz: b778189760eb74d9ee7d882da3b308ed4bd8a020d21c2f480e6f2cc76b1868b64ea907e24f5ce132b688b14c09fcd38e8237e8825bf0a02398c31d99e077ad0e

data/README.md

@@ -5,19 +5,19 @@ In-memory task list + four LLM-facing tools for the
 
 Provides:
 - `Pikuri::Tasks::List` — per-Agent in-memory list of
-  `(content, status)` items. Status is one of `pending`,
+  `(id, content, status)` items. Status is one of `pending`,
   `in_progress`, `completed`. Nothing is written to disk.
 - Four tool classes, all sharing one `List` instance:
   - `Pikuri::Tasks::Create` (`task_create`) — mass-create pending
-    items from a newline-separated `items` string. Atomic: if any
-    line is a duplicate (within the batch or already on the list),
-    nothing is added.
+    items from a JSON array of strings. Atomic: if any element is
+    blank or a duplicate (within the batch or already on the
+    list), nothing is added.
   - `Pikuri::Tasks::InProgress` (`task_in_progress`) — mark an item
-    as `in_progress` by content.
+    as `in_progress` by numeric id.
   - `Pikuri::Tasks::Completed` (`task_completed`) — mark an item as
-    `completed` by content.
+    `completed` by numeric id.
   - `Pikuri::Tasks::Delete` (`task_delete`) — remove an item by
-    content.
+    numeric id.
 - `Pikuri::Tasks::Extension` — wires the four tools + a brief
   `<tasks_usage>` workflow snippet into a `Pikuri::Agent` via the
   `c.add_extension(...)` block API.
@@ -25,10 +25,12 @@ Provides:
 Two shape choices worth flagging:
 - **Status is baked into the tool name** (no `status:` parameter
   with an enum). Removes the `"in-progress"` vs `"in_progress"`
-  vs `"inprogress"` typo failure mode on smaller models.
-- **Content doubles as identifier** across the three update tools
-  (no item IDs to bookkeep). Duplicates are rejected on
-  `task_create` so the identifier stays unique.
+  vs `"inprogress"` typo failure mode.
+- **Items are addressed by numeric id** — assigned on create,
+  shown in every rendered list, never reused after a delete. A
+  near-miss when re-typing the task's content cannot lock the
+  model out of its own list; duplicates are still rejected on
+  `task_create` because they are almost always a mistake.
 
 ## Install
 
@@ -59,9 +61,9 @@ so the LLM always sees fresh state without a separate read tool:
 
 ```
 <tasks>
-- [pending] Add dark mode toggle
-- [in_progress] Write unit tests
-- [completed] Update README
+- #1 [pending] Add dark mode toggle
+- #2 [in_progress] Write unit tests
+- #3 [completed] Update README
 </tasks>
 ```
 

data/lib/pikuri/tasks/completed.rb

@@ -2,25 +2,23 @@
 
 module Pikuri
   module Tasks
-    # The +task_completed+ tool: mark the item whose +content+ exactly
-    # matches as +completed+. Same shape and rationale as
-    # {InProgress} — the status is baked into the tool name to remove
-    # the enum-typo failure mode small models hit on
-    # +"completed"+ / +"complete"+ / +"done"+.
+    # The +task_completed+ tool: mark the item with the given +id+ as
+    # +completed+. Same shape as {InProgress} (status in the tool name,
+    # item addressed by numeric +#id+). Returns {List#render}; a bad id
+    # returns +"Error: no such task id"+ plus the current list.
     #
-    # Returns the rendered current list via {List#render} on success,
-    # or +"Error: no such task: '<content>'"+ when the content does
-    # not match.
+    # Sharing: +P_one_agent+ — closes over one agent's {List}; see its
+    # +== Sharing+.
     class Completed < Pikuri::Tool
       # @return [String]
       DESCRIPTION = <<~DESC
         Mark a task as `completed` once the work — including any required verification — is actually done.
 
         Usage:
-        - Pass the exact `content` string the task was created with.
+        - Pass the task's numeric `id` as shown in the rendered list (`- #3 [in_progress] ...` → id 3).
         - Do NOT mark `completed` based on intent; mark it only after the underlying work is verified.
         - If the work is partially done or blocked, leave the task `in_progress` and add a follow-up via `task_create`.
-        - On `Error: no such task: ...` the call did nothing — read the returned list in any subsequent tool's output to pick the right name.
+        - On `Error: no such task id: ...` the call did nothing — the error includes the current list; pick the right id from it.
         - On success the full current list is returned for you to read back.
       DESC
 
@@ -31,24 +29,26 @@ module Pikuri
           name: 'task_completed',
           description: DESCRIPTION,
           parameters: Pikuri::Tool::Parameters.build { |p|
-            p.required_string :content,
-                              'Exact content of the existing task to mark as ' \
-                              'completed, e.g. "Add dark mode toggle".'
+            p.required_integer :id,
+                               'Numeric id of the existing task to mark as ' \
+                               'completed, as shown in the rendered list, e.g. 3.'
           },
-          execute: lambda { |content:|
-            Completed.execute(list: list, content: content)
-          }
+          execute: lambda { |id:|
+            Completed.execute(list: list, id: id)
+          },
+          # No legs; see {Create}.
+          trifecta_legs: Pikuri::Tool::TrifectaLegs::NONE
         )
       end
 
       # @param list [List]
-      # @param content [String]
+      # @param id [Integer]
       # @return [String]
-      def self.execute(list:, content:)
-        list.set_status(content: content, status: 'completed')
+      def self.execute(list:, id:)
+        list.set_status(id: id, status: 'completed')
         list.render
       rescue ItemNotFound
-        "Error: no such task: '#{content}'"
+        "Error: no such task id: #{id}. Current list:\n#{list.render}"
       end
     end
   end

data/lib/pikuri/tasks/create.rb

@@ -2,23 +2,22 @@
 
 module Pikuri
   module Tasks
-    # The +task_create+ tool: mass-create pending items in a single
-    # call from a newline-separated +items+ string. Why
-    # newline-separated rather than a JSON array: it stays within
-    # pikuri's scalar-only +Tool::Parameters+ DSL (no array support
-    # to extend), and a smaller model never has to balance brackets
-    # or escape quotes — fewer formatting failure modes on the burst
-    # of items that opens most multi-step work.
+    # The +task_create+ tool: mass-create pending items from a JSON array
+    # of strings — a native +items+ array parameter, the shape the model's
+    # training prior produces unprompted. (Regression guard: don't revert
+    # to a newline-separated string. An earlier such design meant to spare
+    # small models the bracket-balancing, but models sent JSON arrays
+    # anyway and the splitter turned `[`, `"foo",`, `]` into garbage tasks
+    # — match the prior, don't fight it.)
     #
-    # Each line is right- and left-stripped; blank lines are skipped.
-    # If any input is a duplicate (within the batch, or already in
-    # the list), the whole call aborts with an +"Error: ..."+ string
-    # and nothing is added — the LLM resends a corrected batch on the
-    # next turn. Atomic semantics keep the list in a coherent state
-    # the LLM doesn't have to reconcile.
+    # Atomic: each element is stripped, and a blank or duplicate element
+    # (within the batch or already in the list) aborts the *whole* call
+    # with an +"Error: ..."+ string and adds nothing — the LLM resends a
+    # corrected batch, and never has to reconcile a half-applied list. On
+    # success returns {List#render}.
     #
-    # On success returns the rendered current list via {List#render},
-    # so the LLM always sees fresh state without a separate read tool.
+    # Sharing: +P_one_agent+ — closes over one agent's {List}; see its
+    # +== Sharing+.
     class Create < Pikuri::Tool
       # @return [String] static description shown to the LLM,
       #   opencode-shape (summary + +Usage:+ bullets).
@@ -27,42 +26,43 @@ module Pikuri
 
         Usage:
         - Use at the start of a multi-step task to capture the plan.
-        - `items` is a single newline-separated string — one task per line. Blank lines are ignored.
-        - Duplicate content (within the batch or already on the list) aborts the whole call with `Error: ...` and adds nothing — resend a corrected batch.
-        - Empty input is rejected the same way.
-        - On success the full current list is returned for you to read back.
+        - A blank element, a duplicate (within the batch or already on the list), or an empty array aborts the whole call with `Error: ...` and adds nothing — resend a corrected batch.
+        - On success the full current list is returned, with each task's `#id` — use that id with `task_in_progress` / `task_completed` / `task_delete`.
       DESC
 
-      # @param list [List] the shared per-Agent list, captured by
-      #   closure so every tool in the {Extension}'s set mutates the
-      #   same instance.
+      # @param list [List] the shared per-Agent list, captured by closure
+      #   so every task tool mutates the same instance.
       # @return [Create]
       def initialize(list:)
         super(
           name: 'task_create',
           description: DESCRIPTION,
           parameters: Pikuri::Tool::Parameters.build { |p|
-            p.required_string :items,
-                              'Newline-separated list of task contents, e.g. ' \
-                              '"Add dark mode toggle\nWrite unit tests\nUpdate README". ' \
-                              'Blank lines are ignored.'
+            p.required_string_array :items,
+                                    'Task contents, one task per array element, e.g. ' \
+                                    '["Add dark mode toggle", "Write unit tests", "Update README"].'
           },
           execute: lambda { |items:|
             Create.execute(list: list, items: items)
-          }
+          },
+          # No legs: an in-memory, per-agent list. Nothing read from disk, nothing sent.
+          trifecta_legs: Pikuri::Tool::TrifectaLegs::NONE
         )
       end
 
-      # Validate and apply the batch. Public so specs can drive it
-      # without constructing a tool instance.
+      # Validate and apply the batch.
       #
       # @param list [List]
-      # @param items [String] raw +items+ argument from the LLM.
+      # @param items [Array<String>] raw +items+ argument from the LLM
+      #   (already type-validated by {Pikuri::Tool::Parameters}).
       # @return [String] either {List#render} on success or an
       #   +"Error: ..."+ string the LLM can react to.
       def self.execute(list:, items:)
-        cleaned = items.lines.map(&:strip).reject(&:empty?)
-        return 'Error: task_create requires at least one non-blank item' if cleaned.empty?
+        return 'Error: task_create requires at least one item' if items.empty?
+
+        cleaned = items.map(&:strip)
+        blank = cleaned.index('')
+        return "Error: blank item at index #{blank} — every element must be non-blank task text" if blank
 
         seen_in_batch = {}
         cleaned.each do |c|

data/lib/pikuri/tasks/delete.rb

@@ -2,29 +2,24 @@
 
 module Pikuri
   module Tasks
-    # The +task_delete+ tool: remove the item whose +content+ exactly
-    # matches from the list. Used to drop items that turned out to be
-    # unnecessary, were created in error, or have been superseded —
-    # rather than leaving them sitting in +pending+ as visual noise.
+    # The +task_delete+ tool: remove the item with the given +id+.
+    # Distinct from {Completed} in intent — +completed+ means the work was
+    # done, +delete+ means the task shouldn't have been there — a
+    # distinction the tool names carry, not the list. A deleted id is never
+    # reused ({List#add}). Returns {List#render}; a bad id returns
+    # +"Error: no such task id"+ plus the current list.
     #
-    # Distinct from {Completed}: +completed+ means the work was
-    # actually done; +delete+ means the task should never have been
-    # there. The list itself draws no such distinction once an item
-    # is gone, but the LLM picks the right verb because the tool
-    # names make the intent clear.
-    #
-    # Returns the rendered current list via {List#render} on success,
-    # or +"Error: no such task: '<content>'"+ when the content does
-    # not match.
+    # Sharing: +P_one_agent+ — closes over one agent's {List}; see its
+    # +== Sharing+.
     class Delete < Pikuri::Tool
       # @return [String]
       DESCRIPTION = <<~DESC
         Remove a task from the list. Use this for items that turn out not to be needed, were created in error, or have been superseded.
 
         Usage:
-        - Pass the exact `content` string the task was created with.
+        - Pass the task's numeric `id` as shown in the rendered list (`- #3 [pending] ...` → id 3).
         - Use `task_completed` (not this) when the work was actually done.
-        - On `Error: no such task: ...` the call did nothing — read the returned list in any subsequent tool's output to pick the right name.
+        - On `Error: no such task id: ...` the call did nothing — the error includes the current list; pick the right id from it.
         - On success the full current list is returned for you to read back.
       DESC
 
@@ -35,24 +30,26 @@ module Pikuri
           name: 'task_delete',
           description: DESCRIPTION,
           parameters: Pikuri::Tool::Parameters.build { |p|
-            p.required_string :content,
-                              'Exact content of the existing task to remove, ' \
-                              'e.g. "Add dark mode toggle".'
+            p.required_integer :id,
+                               'Numeric id of the existing task to remove, ' \
+                               'as shown in the rendered list, e.g. 3.'
+          },
+          execute: lambda { |id:|
+            Delete.execute(list: list, id: id)
           },
-          execute: lambda { |content:|
-            Delete.execute(list: list, content: content)
-          }
+          # No legs; see {Create}.
+          trifecta_legs: Pikuri::Tool::TrifectaLegs::NONE
         )
       end
 
       # @param list [List]
-      # @param content [String]
+      # @param id [Integer]
       # @return [String]
-      def self.execute(list:, content:)
-        list.delete(content)
+      def self.execute(list:, id:)
+        list.delete(id)
         list.render
       rescue ItemNotFound
-        "Error: no such task: '#{content}'"
+        "Error: no such task id: #{id}. Current list:\n#{list.render}"
       end
     end
   end

data/lib/pikuri/tasks/extension.rb

@@ -3,47 +3,28 @@
 module Pikuri
   # Namespace for the in-memory task-list feature. Holds the
   # {List} value type, the four task tool classes ({Create},
-  # {InProgress}, {Completed}, {Delete}), and the {Extension} that
-  # wires them into an {Pikuri::Agent}.
+  # {InProgress}, {Completed}, {Delete}), the {ListChanged} domain
+  # event, and the {Extension} that wires them into an
+  # {Pikuri::Agent}.
   module Tasks
-    # An {Pikuri::Agent::Extension} that auto-wires an in-memory
-    # task list onto an agent: constructs a fresh {List}, registers
-    # the four task tool classes against it, and appends a brief
-    # workflow snippet to the system prompt.
-    #
-    # == Usage
+    # An {Pikuri::Agent::Extension} that auto-wires an in-memory task list
+    # onto an agent: constructs a fresh {List}, registers the four task
+    # tools against it, contributes a workflow snippet, and (in {#bind})
+    # arms {ListChanged} emission.
     #
     #   Pikuri::Agent.new(transport: ..., system_prompt: ...) do |c|
     #     c.add_extension Pikuri::Tasks::Extension.new
     #   end
     #
-    # The list is per-Agent and in-memory. It is dropped when the
-    # agent is garbage-collected — nothing is written to disk.
-    #
-    # == Sub-agents
-    #
-    # Sub-agents do not inherit extensions (see CLAUDE.md's "Seams").
-    # Concretely: a sub-agent spawned by the +agent+ tool gets a
-    # fresh persona, fresh toolset, no task list. That keeps the
-    # parent's plan private to the parent and avoids the
-    # who-owns-which-task confusion a shared list would produce.
-    # If a host wants the sub-agent to also have a task list, it
-    # adds the extension to the sub-agent's own configurator —
-    # cleanly opt-in, no implicit sharing.
-    #
-    # == Empty default
-    #
-    # No +catalog+-style empty state: registering the extension
-    # always installs the four tools and the snippet. A host that
-    # doesn't want tasks simply omits the extension.
+    # Sub-agents don't inherit extensions, so a spawned sub-agent gets no
+    # task list — keeping the parent's plan private and avoiding
+    # who-owns-which-task confusion. A host wanting one adds the extension
+    # to the sub-agent's own configurator.
     class Extension
       include Pikuri::Agent::Extension
 
-      # System-prompt snippet appended once per agent. Short by
-      # design: rules-of-thumb only, no inventory (the tool
-      # descriptions cover their own usage). Mirrors the shape of
-      # opencode's +todowrite.txt+ but condensed to fit pikuri's
-      # "short prose over abstract framing" docs convention.
+      # System-prompt snippet appended once per agent. Rules-of-thumb
+      # only, no inventory (the tool descriptions cover their own usage).
       #
       # @return [String]
       PROMPT_SNIPPET = <<~PROMPT
@@ -51,19 +32,18 @@ module Pikuri
         You have an in-memory task list. Use it to plan and track multi-step work.
 
         Workflow:
-        - When a task has 3+ steps, call `task_create` once with the full plan (newline-separated items, all start as `pending`).
-        - Before starting an item, call `task_in_progress` with its exact content. Keep exactly one item `in_progress` at a time.
-        - When an item is fully done (including any required verification), call `task_completed` with its exact content.
+        - When a task has 3+ steps, call `task_create` once with the full plan (a JSON array of strings, all start as `pending`).
+        - Before starting an item, call `task_in_progress` with its numeric id. Keep exactly one item `in_progress` at a time.
+        - When an item is fully done (including any required verification), call `task_completed` with its numeric id.
         - Use `task_delete` to remove items that turn out not to be needed.
 
         Skip task tracking entirely for single-step or purely informational requests — it adds noise, not value.
 
-        Every mutation returns the full current list, so you do not need a separate read tool. Content doubles as identifier across the four tools: spelling and capitalization must match exactly.
+        Every mutation returns the full current list, with each task's id (`- #3 [pending] ...` → id 3), so you do not need a separate read tool. Ids never change and are never reused.
         </tasks_usage>
       PROMPT
 
-      # Tool classes the extension auto-registers. Used both for
-      # construction and for the duplicate-registration guard below.
+      # Tool classes the extension auto-registers.
       TOOL_CLASSES = [Create, InProgress, Completed, Delete].freeze
 
       # @return [Extension]
@@ -71,17 +51,16 @@ module Pikuri
         @list = List.new
       end
 
-      # @return [List] the per-agent list, exposed for tests and for
-      #   hosts that want to render it in a UI (a future TUI could
-      #   surface +list.items+ in a sidebar).
+      # @return [List] the per-agent list, exposed for tests. Do NOT read
+      #   it from another thread — it's agent-thread-confined; consume the
+      #   {ListChanged} events wired by {#bind} instead.
       attr_reader :list
 
-      # Construct the four tools (each sharing +@list+) and register
-      # them, then append {PROMPT_SNIPPET}. Raises if any of the four
-      # tool classes have been pre-registered via +c.add_tool+ — the
-      # whole point of the extension is to be the single owner of the
-      # shared list, and a manually pre-registered tool would bind to
-      # a different list.
+      # Construct the four tools (each sharing +@list+), register them,
+      # and append {PROMPT_SNIPPET}. Raises if any of the four were
+      # pre-registered via +c.add_tool+ — the extension is the single
+      # owner of the shared list, and a pre-registered tool would bind to
+      # a different one.
       #
       # @param c [Pikuri::Agent::Configurator]
       # @return [void]
@@ -95,7 +74,33 @@ module Pikuri
         end
 
         TOOL_CLASSES.each { |cls| c.add_tool(cls.new(list: @list)) }
-        c.append_system_prompt(PROMPT_SNIPPET)
+        nil
+      end
+
+      # @return [Array<String>] the static task-workflow snippet.
+      def system_prompt_snippets = [PROMPT_SNIPPET]
+
+      # Arm {List#on_change} to emit a {ListChanged} (carrying a fresh
+      # {List#items} snapshot) after every mutation — how a UI listener
+      # observes the list without touching the agent-thread-confined {List}.
+      #
+      # @param ctx [Pikuri::Agent::ExtensionContext]
+      # @return [void]
+      def bind(ctx)
+        @list.on_change = -> { ctx.emit_event(ListChanged.new(items: @list.items)) }
+        nil
+      end
+
+      # Clear the task list on conversation reset — a plan is meaningless
+      # without the conversation that produced it. {List#clear} fires the
+      # armed +on_change+, so an empty {ListChanged} reaches the listener
+      # stream like any other mutation.
+      #
+      # @param ctx [Pikuri::Agent::ExtensionContext] unused; part of the
+      #   protocol signature.
+      # @return [void]
+      def on_conversation_reset(_ctx)
+        @list.clear
         nil
       end
     end

data/lib/pikuri/tasks/in_progress.rb

@@ -2,26 +2,28 @@
 
 module Pikuri
   module Tasks
-    # The +task_in_progress+ tool: mark the item whose +content+
-    # exactly matches as +in_progress+. The status name is baked into
-    # the tool name rather than passed as a parameter — that takes
-    # one degree of freedom away from the LLM (no +"in-progress"+ vs
-    # +"in_progress"+ vs +"inprogress"+ typos) at the cost of one
-    # extra tool class.
+    # The +task_in_progress+ tool: mark the item with the given +id+ as
+    # +in_progress+. The status is baked into the tool name, not a
+    # parameter — one fewer degree of freedom for the LLM (no
+    # +"in-progress"+/+"inprogress"+ typos) at the cost of one tool class.
     #
-    # Returns the rendered current list via {List#render} on success,
-    # or +"Error: no such task: '<content>'"+ when the content does
-    # not match — the LLM can read the returned list to find the
-    # closest match and re-call.
+    # Items are addressed by numeric +#id+, not content string (regression
+    # guard: an earlier content-as-id design locked the LLM out of its own
+    # list on one near-miss byte — a stray quote or trailing comma; an id
+    # is two digits it just read back). Returns {List#render}; a bad id
+    # returns +"Error: no such task id"+ plus the current list.
+    #
+    # Sharing: +P_one_agent+ — closes over one agent's {List}; see its
+    # +== Sharing+.
     class InProgress < Pikuri::Tool
       # @return [String]
       DESCRIPTION = <<~DESC
         Mark a task as `in_progress` immediately before you start working on it.
 
         Usage:
-        - Pass the exact `content` string the task was created with — content doubles as identifier; spelling and capitalization must match.
+        - Pass the task's numeric `id` as shown in the rendered list (`- #3 [pending] ...` → id 3).
         - Keep exactly one task `in_progress` at a time. Finish (or revert) the current one before starting another.
-        - On `Error: no such task: ...` the call did nothing — read the returned list in any subsequent tool's output to pick the right name.
+        - On `Error: no such task id: ...` the call did nothing — the error includes the current list; pick the right id from it.
         - On success the full current list is returned for you to read back.
       DESC
 
@@ -32,24 +34,26 @@ module Pikuri
           name: 'task_in_progress',
           description: DESCRIPTION,
           parameters: Pikuri::Tool::Parameters.build { |p|
-            p.required_string :content,
-                              'Exact content of the existing task to mark as ' \
-                              'in_progress, e.g. "Add dark mode toggle".'
+            p.required_integer :id,
+                               'Numeric id of the existing task to mark as ' \
+                               'in_progress, as shown in the rendered list, e.g. 3.'
+          },
+          execute: lambda { |id:|
+            InProgress.execute(list: list, id: id)
           },
-          execute: lambda { |content:|
-            InProgress.execute(list: list, content: content)
-          }
+          # No legs; see {Create}.
+          trifecta_legs: Pikuri::Tool::TrifectaLegs::NONE
         )
       end
 
       # @param list [List]
-      # @param content [String]
+      # @param id [Integer]
       # @return [String]
-      def self.execute(list:, content:)
-        list.set_status(content: content, status: 'in_progress')
+      def self.execute(list:, id:)
+        list.set_status(id: id, status: 'in_progress')
         list.render
       rescue ItemNotFound
-        "Error: no such task: '#{content}'"
+        "Error: no such task id: #{id}. Current list:\n#{list.render}"
       end
     end
   end

data/lib/pikuri/tasks/list.rb

@@ -2,54 +2,60 @@
 
 module Pikuri
   module Tasks
-    # Raised by {List#add} when a new item's +content+ already appears
-    # in the list. Content doubles as identifier in the task tools, so
-    # duplicates would make +task_in_progress+ / +task_completed+ /
-    # +task_delete+ ambiguous. The exception carries the offending
-    # content string so the tool layer can surface it verbatim in the
-    # +"Error: ..."+ observation.
+    # Raised by {List#add} when a new item's +content+ already appears in
+    # the list — rejected because a duplicate is almost always an LLM
+    # mistake (re-sending an already-captured plan). Carries the offending
+    # content for the +"Error: ..."+ observation.
     class DuplicateItem < StandardError; end
 
-    # Raised by {List#set_status} and {List#delete} when no item with
-    # the given +content+ exists. The four task tools rescue this and
-    # report +"Error: no such task: <content>"+ so the LLM can correct
-    # the name on the next turn.
+    # Raised by {List#set_status} and {List#delete} when no item with the
+    # given +id+ exists; the mutation tools rescue it into an +"Error: no
+    # such task id"+ observation.
     class ItemNotFound < StandardError; end
 
-    # Allowed values for {Item#status}. Kept deliberately small — three
-    # states match the workflow the prompt advertises (pending → in_progress
-    # → completed) without inviting a +cancelled+ vs +deleted+ debate.
-    # +task_delete+ removes items outright rather than introducing a
-    # fourth status.
+    # Allowed values for {Item#status}. Deliberately three — the workflow
+    # the prompt advertises (pending → in_progress → completed) — with
+    # +task_delete+ removing items outright rather than adding a fourth
+    # +cancelled+/+deleted+ status.
     STATUSES = %w[pending in_progress completed].freeze
 
-    # One row in a {List}. +content+ is the LLM-visible string that
-    # also acts as identifier across the four task tools; +status+ is
-    # one of {STATUSES}.
-    Item = Data.define(:content, :status)
+    # One row in a {List}. +id+ is the numeric identifier the mutation
+    # tools address the item by (assigned by {List#add}, never reused);
+    # +content+ is the LLM-visible task text; +status+ is one of {STATUSES}.
+    Item = Data.define(:id, :content, :status)
 
     # An in-memory ordered list of {Item}s, scoped to a single
-    # {Pikuri::Agent}. Held inside {Extension} and captured by closure
-    # into the +execute+ block of each of the four task tool classes,
-    # so every mutation hits the same instance.
+    # {Pikuri::Agent}, shared by closure into all four task tools so every
+    # mutation hits the same instance.
     #
-    # == Concurrency
+    # Not persisted: dropped when the +Agent+ is collected, matching the
+    # gem's "in-memory only" scope.
     #
-    # The agent loop is single-threaded with respect to tool calls
-    # (ruby_llm dispatches them sequentially), so no locking. A future
-    # parallel-tool-execution feature would need a +Mutex+ here.
+    # == Sharing
     #
-    # == Persistence
-    #
-    # None. The list is dropped when the +Agent+ is garbage-collected.
-    # That matches the gem's stated scope: "in-memory only, no
-    # session-state-on-disk."
+    # +P_one_agent+ — this is one conversation's plan, so two agents on one
+    # list would read and complete each other's tasks. Unguarded, and it needs
+    # no lock because its only caller is the agent whose tool calls are already
+    # serialized. Another thread (a UI rendering the list) must not touch a
+    # +List+ directly: it consumes the {ListChanged} events {Extension#bind}
+    # wires onto the listener stream, whose +items+ payload is an immutable
+    # snapshot safe to hand across threads.
     class List
       # @return [List]
       def initialize
         @items = []
+        @next_id = 1
+        @on_change = nil
       end
 
+      # Optional zero-argument hook invoked synchronously after every
+      # *successful* mutation (a raise means nothing changed, so no
+      # notify). Set by {Extension#bind} to emit a {ListChanged}; +nil+
+      # (default) disables notification.
+      #
+      # @return [Proc, nil]
+      attr_accessor :on_change
+
       # @return [Array<Item>] a frozen snapshot of the current items,
       #   in insertion order. Callers cannot mutate the internal
       #   storage through this accessor.
@@ -67,82 +73,95 @@ module Pikuri
         @items.empty?
       end
 
-      # Append a new item with status +pending+. Content matching is
-      # exact (no case- or whitespace-folding) since the tools quote
-      # the content back to the LLM as the identifier.
+      # Append a new item with status +pending+ and the next id from a
+      # monotonic per-list counter. Ids are never reused: after a
+      # delete, the freed id stays dead, so a stale id held by the LLM
+      # errors loudly instead of silently resolving to a newer task.
       #
       # @param content [String] non-empty content; whitespace is the
       #   caller's responsibility.
       # @return [Item] the newly added item
-      # @raise [DuplicateItem] if an item with the same +content+
-      #   already exists.
+      # @raise [DuplicateItem] if an item with the same +content+ exists.
       def add(content)
-        raise DuplicateItem, content if find(content)
+        raise DuplicateItem, content if @items.any? { |i| i.content == content }
 
-        item = Item.new(content: content, status: 'pending')
+        item = Item.new(id: @next_id, content: content, status: 'pending')
+        @next_id += 1
         @items << item
+        @on_change&.call
         item
       end
 
-      # Update the status of the item whose +content+ matches.
+      # Update the status of the item whose +id+ matches.
       #
-      # @param content [String]
+      # @param id [Integer]
       # @param status [String] one of {STATUSES}.
       # @return [Item] the updated item (a fresh frozen +Data+
       #   instance — the old one is replaced in place).
       # @raise [ItemNotFound] if no matching item exists.
       # @raise [ArgumentError] if +status+ is not in {STATUSES}.
-      def set_status(content:, status:)
+      def set_status(id:, status:)
         unless STATUSES.include?(status)
           raise ArgumentError, "invalid status: #{status.inspect} (allowed: #{STATUSES.join(', ')})"
         end
 
-        idx = @items.index { |i| i.content == content }
-        raise ItemNotFound, content if idx.nil?
+        idx = @items.index { |i| i.id == id }
+        raise ItemNotFound, id.to_s if idx.nil?
 
-        @items[idx] = Item.new(content: content, status: status)
+        @items[idx] = @items[idx].with(status: status)
+        @on_change&.call
         @items[idx]
       end
 
-      # Remove the item whose +content+ matches.
+      # Remove the item whose +id+ matches. The id is not reused for
+      # later items (see {#add}).
       #
-      # @param content [String]
+      # @param id [Integer]
       # @return [Item] the removed item.
       # @raise [ItemNotFound] if no matching item exists.
-      def delete(content)
-        idx = @items.index { |i| i.content == content }
-        raise ItemNotFound, content if idx.nil?
+      def delete(id)
+        idx = @items.index { |i| i.id == id }
+        raise ItemNotFound, id.to_s if idx.nil?
+
+        removed = @items.delete_at(idx)
+        @on_change&.call
+        removed
+      end
 
-        @items.delete_at(idx)
+      # Drop every item and rewind the id counter to 1, then fire
+      # {#on_change} (always, even when already empty, so a UI listener
+      # sees the cleared state). Rewinding +@next_id+ is safe here — unlike
+      # after {#delete}, a clear wipes the model's context too, so no stale
+      # id survives to collide with a reused one.
+      #
+      # @return [void]
+      def clear
+        @items = []
+        @next_id = 1
+        @on_change&.call
+        nil
       end
 
-      # The canonical rendering returned as the observation by every
-      # task tool, so the LLM sees the latest full state on each call
-      # without needing a separate read tool. Format:
+      # The canonical rendering every task tool returns as its
+      # observation, so the LLM sees the full state (ids included) each
+      # call without a separate read tool:
       #
       #   <tasks>
-      #   - [pending] Add dark mode toggle
-      #   - [in_progress] Write unit tests
-      #   - [completed] Update README
+      #   - #1 [pending] Add dark mode toggle
+      #   - #2 [in_progress] Write unit tests
+      #   - #3 [completed] Update README
       #   </tasks>
       #
-      # Empty list renders as +<tasks>(empty)</tasks>+ so the LLM gets
-      # an unambiguous "yes, the call worked and the list is now empty"
-      # signal rather than an ambiguous blank block.
+      # Empty renders as +<tasks>(empty)</tasks>+ — an unambiguous "the
+      # call worked, list is now empty" rather than a blank block.
       #
       # @return [String]
       def render
         return '<tasks>(empty)</tasks>' if @items.empty?
 
-        lines = @items.map { |i| "- [#{i.status}] #{i.content}" }
+        lines = @items.map { |i| "- ##{i.id} [#{i.status}] #{i.content}" }
         "<tasks>\n#{lines.join("\n")}\n</tasks>"
       end
-
-      private
-
-      def find(content)
-        @items.find { |i| i.content == content }
-      end
     end
   end
 end

data/lib/pikuri/tasks/list_changed.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Pikuri
+  module Tasks
+    # Domain event emitted after every {List} mutation (add / status
+    # change / delete), wired by {Extension#bind} via
+    # {Pikuri::Agent::ExtensionContext#emit_event}. Carries a frozen
+    # whole-list snapshot ({List#items}), so a consumer needs no +List+
+    # reference — render or serialize the payload as-is.
+    #
+    # A batch +task_create+ emits one event per added item, so a renderer
+    # should treat the latest snapshot as authoritative (last-wins), not
+    # diff event-by-event. Fired on the agent's thread — a listener
+    # feeding another thread serializes inside +on_event+ and hands off
+    # only the immutable result (see {List}'s thread-confinement note).
+    ListChanged = Data.define(:items)
+  end
+end

data/lib/pikuri-tasks.rb

@@ -2,16 +2,8 @@
 
 require 'pikuri-core'
 
-# Entry file for the pikuri-tasks gem. Sets up a dedicated Zeitwerk
-# loader rooted at this gem's +lib/+, contributing to the shared
-# +Pikuri::+ namespace alongside pikuri-core. After +require
-# 'pikuri-tasks'+, +Pikuri::Tasks::List+, the four task tool classes
-# (+Create+, +InProgress+, +Completed+, +Delete+), and
-# +Pikuri::Tasks::Extension+ are all defined.
-#
-# The loader is per-gem (not shared with pikuri-core's loader) so each
-# gem owns its own +lib/+ tree and the cooperation between gems is via
-# the Pikuri namespace alone.
+# Entry file for the pikuri-tasks gem: sets up the per-gem Zeitwerk
+# loader. See {Pikuri::Tasks} for the namespace overview.
 module Pikuri
   module Tasks
     LOADER = Zeitwerk::Loader.new

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: pikuri-tasks
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.1.0
 platform: ruby
 authors:
 - Martin Vysny
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-04 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pikuri-core
@@ -16,14 +15,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.0.6
+        version: 0.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.0.6
+        version: 0.1.0
 description: |
   pikuri-tasks gives a pikuri-core agent an in-memory task list it
   can use to plan and track multi-step work. A +Pikuri::Tasks::List+
@@ -51,6 +50,7 @@ files:
 - lib/pikuri/tasks/extension.rb
 - lib/pikuri/tasks/in_progress.rb
 - lib/pikuri/tasks/list.rb
+- lib/pikuri/tasks/list_changed.rb
 homepage: https://codeberg.org/mvysny/pikuri
 licenses:
 - MIT
@@ -59,7 +59,6 @@ metadata:
   changelog_uri: https://codeberg.org/mvysny/pikuri/src/branch/master/CHANGELOG.md
   bug_tracker_uri: https://codeberg.org/mvysny/pikuri/issues
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -74,8 +73,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.7
 specification_version: 4
 summary: Per-session in-memory task list + tools for pikuri.
 test_files: []