Documentation
¶
Overview ¶
Package tasklist owns the bounded todo_write contract and its durable projection from assistant tool calls. Historical update_plan calls are recognized on replay with their original replace-by-default semantics.
Index ¶
Constants ¶
const ( // ToolName is the application-owned task progress tool. ToolName = "todo_write" // LegacyToolName is the pre-rename tool name. It remains readable so a // resumed session replays its historical calls with their original // replace-by-default semantics; the catalog never offers it again. LegacyToolName = "update_plan" MaxItems = 64 MaxStepBytes = 512 MaxExplanationBytes = 4 << 10 MaxUpdateBytes = 64 << 10 // MaxMetaBytes bounds one item's free-form meta object. The reference keeps // meta unbounded; pips keeps the plan's payload bounded. MaxMetaBytes = 1 << 10 )
Variables ¶
This section is empty.
Functions ¶
func IsToolName ¶ added in v0.1.9
IsToolName reports whether name is the current todo_write tool or the legacy update_plan name kept for transcript replay.
func Validate ¶
Validate enforces the bounded call contract: either an explicit clear with no items, an explicit replace with no items, or the 1-64 item count, the explanation, each item's id, step, meta and status, and the duplicate-id rule among the items the call carries. Multiple items may be in progress: parallel work is a model-level plan choice, so the tool does not count them. A folded state that is still invalid is refused by Apply, not here.
func ValidateSnapshot ¶
ValidateSnapshot validates either a full in-process Snapshot or a redacted count-only event projection whose Items slice is nil. The full shape is the folded-state contract, so an older projection whose items carry no id still validates: the fold, not this check, is what assigns ids.
Types ¶
type Item ¶
type Item struct {
ID string `json:"id,omitempty" description:"Stable item identifier; defaults to the step text"`
Step string `json:"step,omitempty" description:"Concise task step"`
Status Status `json:"status,omitempty" description:"Task status: pending, in_progress, completed, or cancelled"`
Meta map[string]any `json:"meta,omitempty" description:"Optional bounded JSON object with free-form metadata"`
}
Item is one plan entry supplied by the model. ID is the item's stable identifier and defaults to the step text when omitted, so a plan written without ids stays addressable by its steps. Step is optional in a merge, where an omitted step keeps the stored text, and Status is optional in both modes.
type Snapshot ¶
type Snapshot struct {
Items []Item `json:"items,omitempty"`
Completed int `json:"completed"`
InProgress int `json:"in_progress"`
Cancelled int `json:"cancelled"`
Total int `json:"total"`
}
Snapshot is the clone-safe task progress projection consumed by frontends.
func Apply ¶ added in v0.1.9
Apply folds one decoded call onto the current plan. It is the only place the plan is derived: the bootstrap replay, the live reducer, and the transcript scan behind the per-turn reminder all call it, so the pane, the reminder, the gate and a resumed session cannot drift. A clear or an explicit empty replace empties the projection; a replace rebuilds the list from the call; a merge updates by id and appends an unknown id. todo_write merges by default; a legacy update_plan call replaces by default. The folded state is validated before it is returned, so the tool refuses a call that would push the plan past its item bound.
func Project ¶
Project returns the latest applicable todo_write projection in a transcript. Historical update_plan calls are folded with their original replace-by-default semantics. A call that cannot be applied leaves the previous state alone, so a malformed or refused call cannot corrupt the plan.
type Status ¶
type Status string
Status is one task's lifecycle state.
const ( StatusPending Status = "pending" StatusInProgress Status = "in_progress" StatusCompleted Status = "completed" // StatusCancelled is a terminal status for a genuinely blocked step. The // reference's gate reminder tells the model to mark such a todo cancelled, // and a cancelled item never counts as in progress. StatusCancelled Status = "cancelled" )
type Update ¶
type Update struct {
Explanation string `json:"explanation,omitempty" description:"Optional concise reason for this update"`
Merge *bool `` /* 157-byte string literal not displayed */
Clear bool `json:"clear,omitempty" description:"Remove the whole plan; plan must carry no items"`
Plan []Item `json:"plan,omitempty" description:"Task items to write; 1-64 items unless clear is true"`
// contains filtered or unexported fields
}
Update folds one call onto the current plan. Merge is nullable so an absent field is distinguishable from false. Absent and false both replace, which is pips' own historical meaning of every update_plan call ever written; the auto-upgrade net of Apply is what makes a status-only flip cheap anyway. Update is one task progress call. Merge is a presence-aware override: the todo_write tool merges by default, while a legacy update_plan call replaces by default. FromMessage records which contract produced the value, so replay keeps the meaning the transcript was written with.