Documentation
¶
Overview ¶
Package plan provides a toolset that lets two or more agents collaborate on plans addressed by name. Plans persist through a pluggable Storage backend; the default FilesystemStorage keeps them as JSON files in a global shared folder under the docker-agent data directory, so any agent that loads this toolset can write, read, list, and delete the same shared plans, and they persist across sessions. Embedders can inject an alternative backend (e.g. a database or remote store) with WithStorage.
Concurrency: agents that share one ToolSet instance also share its Storage, which serializes their operations. The default FilesystemStorage guards its read-modify-write revision bump with a mutex and writes atomically (write-to-temp + rename), so a reader — including a separate docker-agent process — never observes a partially written plan. Two distinct processes writing the *same* plan at the very same instant can still race on the revision bump (last writer wins); this is acceptable for the intended in-process multi-agent collaboration. Other backends can make the bump atomic.
Index ¶
- Constants
- func CreateToolSet() (tools.ToolSet, error)
- func DefaultDir() string
- type DeletePlanArgs
- type FilesystemStorage
- func (s *FilesystemStorage) Delete(_ context.Context, name string) (bool, error)
- func (s *FilesystemStorage) Get(_ context.Context, name string) (Plan, bool, error)
- func (s *FilesystemStorage) List(_ context.Context) ([]Summary, []string, error)
- func (s *FilesystemStorage) String() string
- func (s *FilesystemStorage) Upsert(_ context.Context, name, content, title, author string) (Plan, error)
- type ListResult
- type Option
- type Plan
- type ReadPlanArgs
- type Storage
- type Summary
- type ToolSet
- type WritePlanArgs
Constants ¶
const ( ToolNameWritePlan = "write_plan" ToolNameReadPlan = "read_plan" ToolNameListPlans = "list_plans" ToolNameDeletePlan = "delete_plan" )
Variables ¶
This section is empty.
Functions ¶
func CreateToolSet ¶
CreateToolSet is used by the tools registry. It returns a process-wide singleton so that all agents collaborating in the same process share one storage over the global plans folder.
func DefaultDir ¶
func DefaultDir() string
DefaultDir is the global shared folder where plans are stored, under the docker-agent data directory.
Types ¶
type DeletePlanArgs ¶
type DeletePlanArgs struct {
Name string `json:"name" jsonschema:"The name of the plan to delete."`
}
type FilesystemStorage ¶ added in v1.88.0
type FilesystemStorage struct {
// contains filtered or unexported fields
}
FilesystemStorage is the default Storage. It persists each plan as a JSON file named <name>.json in a directory, with atomic temp+rename writes, plan name validation, and unreadable-file warnings on List. A mutex serializes its operations so the read-modify-write revision bump in Upsert is consistent within a process.
func NewFilesystemStorage ¶ added in v1.88.0
func NewFilesystemStorage(dir string) *FilesystemStorage
NewFilesystemStorage returns a filesystem-backed Storage rooted at dir. The directory is created lazily on the first write, not here, so a parent that is momentarily unavailable at startup is recovered from automatically.
func (*FilesystemStorage) String ¶ added in v1.88.0
func (s *FilesystemStorage) String() string
String renders the backend for ToolSet.Describe, e.g. "dir=/path/to/plans".
type ListResult ¶
type ListResult struct {
Plans []Summary `json:"plans"`
Warnings []string `json:"warnings,omitempty"`
}
ListResult is the output of list_plans. Warnings lists plan files that could not be read or decoded, so a caller can tell "no plans exist" apart from "some plans failed to load" — important because an agent that mistakes a temporarily unreadable plan for a missing one could recreate and clobber it.
type Option ¶ added in v1.88.0
type Option func(*ToolSet)
Option configures a ToolSet.
func WithStorage ¶ added in v1.88.0
WithStorage injects a custom Storage backend in place of the default FilesystemStorage, letting embedders supply their own store and get per-instance isolation. The provided storage must not be nil.
type Plan ¶
type Plan struct {
Name string `json:"name"`
Title string `json:"title,omitempty"`
Content string `json:"content"`
// Author is a free-form label identifying who last wrote the plan
// (typically the agent name). It helps collaborators see who made the
// most recent change.
Author string `json:"author,omitempty"`
Revision int `json:"revision"`
UpdatedAt string `json:"updatedAt"`
}
Plan is a shared document collaborated on by the agents.
type ReadPlanArgs ¶
type ReadPlanArgs struct {
Name string `json:"name" jsonschema:"The name of the plan to read."`
}
type Storage ¶ added in v1.88.0
type Storage interface {
// Get returns the named plan. The bool is false with a nil error when no
// such plan exists, so callers can tell a missing plan apart from a real
// read failure (returned as a non-nil error).
Get(ctx context.Context, name string) (Plan, bool, error)
// Upsert creates or replaces the named plan's content and, when non-empty,
// its title and author; omitted title/author are preserved from the
// previous revision. It bumps the revision and stamps UpdatedAt, returning
// the stored plan.
Upsert(ctx context.Context, name, content, title, author string) (Plan, error)
// List returns a summary of every stored plan. Warnings carries entries
// that could not be read, so a caller can tell "no plans" apart from "some
// plans failed to load".
List(ctx context.Context) (plans []Summary, warnings []string, err error)
// Delete removes the named plan. The bool is false with a nil error when
// there was no such plan to delete.
Delete(ctx context.Context, name string) (deleted bool, err error)
}
Storage persists the plans a ToolSet operates on. Implementations decide how a plan is stored (files, memory, a database, a remote service) and own the revision bump in Upsert, so a backend can make it atomic. The default FilesystemStorage is used when WithStorage injects nothing else.
type Summary ¶
type Summary struct {
Name string `json:"name"`
Title string `json:"title,omitempty"`
Author string `json:"author,omitempty"`
Revision int `json:"revision"`
UpdatedAt string `json:"updatedAt"`
}
Summary is a lightweight view of a plan returned by list_plans.
type ToolSet ¶
type ToolSet struct {
// contains filtered or unexported fields
}
func New ¶
New builds a per-instance plan toolset. With no options it uses the default FilesystemStorage rooted at DefaultDir(); pass WithStorage to inject another backend. Each call returns an independent instance — use CreateToolSet for the process-wide singleton shared by collaborating agents.
func (*ToolSet) Instructions ¶
type WritePlanArgs ¶
type WritePlanArgs struct {
Name string `json:"name" jsonschema:"The plan name. Lowercase letters, digits, '-' and '_' only (e.g. 'release', 'db-migration')."`
Content string `json:"content" jsonschema:"The full plan content (markdown). Replaces the existing plan."`
Title string `json:"title,omitempty" jsonschema:"Optional human-readable title. Preserved from the previous revision when omitted."`
Author string `` /* 166-byte string literal not displayed */
}
Source Files