From 9e34bc2f756d63a464ae4e0b541547bbf308c98f Mon Sep 17 00:00:00 2001 From: Dmitrii Balabanov Date: Sun, 8 Mar 2026 16:33:59 +0200 Subject: [PATCH] docs: clarify tasktool runtime and sequential tools --- docs/tools_configuration.md | 19 +++++++++++++++++++ pkg/tools/README.md | 37 +++++++++++++++++++++++++++++++++++++ 2 files changed, 56 insertions(+) create mode 100644 pkg/tools/README.md diff --git a/docs/tools_configuration.md b/docs/tools_configuration.md index bde6b12fb..e9b3a8046 100644 --- a/docs/tools_configuration.md +++ b/docs/tools_configuration.md @@ -210,6 +210,25 @@ The skills tool configures skill discovery and installation via registries like The task tool lets the agent create and track a step-by-step execution plan visible to the user in real time. +### Runtime Behavior + +The tool supports four actions: + +| Action | Purpose | +| ------ | ------- | +| `create_plan` | Create a new checklist for the current session | +| `update_task` | Change a task status and optionally attach a short result | +| `list_plan` | Return the current checklist state | +| `resend_plan` | Send the current checklist again as a fresh message | + +Delivery is channel-aware: + +- On channels that can send and later edit a message, the initial plan is posted immediately and later `update_task` calls edit that same progress message. +- In direct/CLI mode, or on paths where out-of-band delivery is unavailable, the plan falls back to normal user-visible output so the checklist is still shown in chat. +- Telegram may split long plans across multiple messages; PicoClaw keeps track of all chunks so later updates can edit the full plan consistently. + +Most users only need to configure the tool. The LLM is responsible for choosing the appropriate action during planning and execution. + ### Config | Config | Type | Default | Description | diff --git a/pkg/tools/README.md b/pkg/tools/README.md new file mode 100644 index 000000000..01088ee6d --- /dev/null +++ b/pkg/tools/README.md @@ -0,0 +1,37 @@ +# PicoClaw Tool Development Notes + +This document is a short reference for implementing tools in `pkg/tools/`. + +## Core Interfaces + +- `Tool`: the base synchronous tool contract. Every tool must implement `Name`, `Description`, `Parameters`, and `Execute`. +- `AsyncExecutor`: for tools that start background work and report completion later through a callback. +- `SequentialTool`: for tools that must preserve model order within a single LLM turn. +- `AdvancedMessageManager`: for tools that need synchronous send/edit callbacks from the channel manager. + +## Execution Model + +Tool calls from one assistant response run in parallel by default. + +If a tool mutates shared state, or if one call can depend on a previous call from the same assistant message, implement `SequentialTool` and return `true` from `ExecuteSequentially()`. + +Example: `tasktool` uses `SequentialTool` because `create_plan` and `update_task` can appear in the same model turn and must execute in order. + +The sequential contract is honored by both the main agent loop and `RunToolLoop`, so subagent-style tool execution follows the same ordering rule. + +## Context Helpers + +`ExecuteWithContext` injects request-scoped metadata into the tool context: + +- `ToolChannel(ctx)` +- `ToolChatID(ctx)` +- `ToolSessionKey(ctx)` + +Use these helpers instead of storing per-request mutable state on tool instances. + +## Guidance + +- Prefer stateless tool instances. Shared mutable fields make parallel execution harder to reason about. +- Use `AsyncExecutor` only for genuinely background work. Most tools should stay synchronous. +- Use `AdvancedMessageManager` only when a tool must directly manage a user-visible message over time. +- If a tool needs ordered execution only for some calls, keep the implementation simple and still return `true`; correctness matters more than maximizing intra-turn parallelism.