tasklist

package
v0.1.9 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 19, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

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

View Source
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

func IsToolName(name string) bool

IsToolName reports whether name is the current todo_write tool or the legacy update_plan name kept for transcript replay.

func Validate

func Validate(update Update) error

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

func ValidateSnapshot(snapshot Snapshot) error

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

func Apply(current Snapshot, update Update) (Snapshot, error)

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

func Project(messages []ai.Message) Snapshot

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.

func (Snapshot) Clone

func (snapshot Snapshot) Clone() Snapshot

Clone returns a detached snapshot.

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.

func Decode

func Decode(data []byte) (Update, error)

Decode strictly decodes and validates one update call.

func FromMessage

func FromMessage(message ai.Message) (Update, bool)

FromMessage returns the last valid todo_write or legacy update_plan call in one assistant message. The legacy marker changes only the merge default; an explicit merge value means the same thing in both contracts.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL