task

Documentation

Overview

Package task is a unified registry for background tasks. Tools (shell commands, sub-agent dispatch, etc.) register their long-running work via a shared Runtime so callers can list and cancel them through one surface.

Index

• Constants
• type Entry
  • func (e *Entry) SetCancel(fn func())
• type Notification
  • func NotificationFromEntry(e *Entry) Notification
  • func (n Notification) ToAgentMessage() agentcore.AgentMessage
• type Runtime
  • func NewRuntime() *Runtime
  • func (r *Runtime) Get(id string) *Entry
  • func (r *Runtime) List() []Entry
  • func (r *Runtime) NextID(prefix string) string
  • func (r *Runtime) Register(entry *Entry)
  • func (r *Runtime) Stop(id string) bool
  • func (r *Runtime) StopAll() int
  • func (r *Runtime) Update(id string, fn func(e *Entry)) bool
• type Status
• type Type

Constants

const CompletedTag = "background-task-completed"

CompletedTag is the XML-style wrapper tag used in the AgentMessage emitted by ToAgentMessage().

Types

type Entry

type Entry struct {
	ID          string
	Type        Type
	Description string
	Status      Status
	StartedAt   time.Time
	EndedAt     time.Time
	OutputFile  string // path to output file on disk
	Error       string
	ExitCode    int // shell: process exit code
	ToolCount   int // number of tool calls executed

	// Shell-specific
	PID     int
	Command string

	// SubAgent-specific
	Agent     string
	Prompt    string // original task prompt
	TokensIn  int
	TokensOut int
	// contains filtered or unexported fields
}

Entry is the unified representation of any background task. Both shell tools and sub-agent tools register entries through a shared Runtime.

func (*Entry) SetCancel

func (e *Entry) SetCancel(fn func())

SetCancel sets the cancellation function for this task entry. Called during registration; only Stop()/StopAll() invoke it.

type Notification

type Notification struct {
	TaskID      string `json:"task_id"`
	Type        Type   `json:"type"`
	Status      Status `json:"status"`
	Description string `json:"description,omitempty"`
	OutputFile  string `json:"output_file,omitempty"`
	Error       string `json:"error,omitempty"`
	ExitCode    *int   `json:"exit_code,omitempty"`
	Command     string `json:"command,omitempty"`
	Agent       string `json:"agent,omitempty"`
}

Notification is the JSON payload delivered to the calling agent when a background task finishes.

func NotificationFromEntry

func NotificationFromEntry(e *Entry) Notification

NotificationFromEntry converts a task entry into a notification payload.

func (Notification) ToAgentMessage

func (n Notification) ToAgentMessage() agentcore.AgentMessage

ToAgentMessage wraps the notification as a user-role AgentMessage that the parent agent can consume as a follow-up.

type Runtime

type Runtime struct {
	// contains filtered or unexported fields
}

Runtime is a unified registry for background tasks.

func NewRuntime

func NewRuntime() *Runtime

NewRuntime creates an empty runtime.

func (*Runtime) Get

func (r *Runtime) Get(id string) *Entry

Get returns a snapshot of a single task, or nil if not found.

func (*Runtime) List

func (r *Runtime) List() []Entry

List returns snapshots of all tasks, sorted by creation time.

func (*Runtime) NextID

func (r *Runtime) NextID(prefix string) string

NextID generates a sequential task ID with the given prefix (e.g. "shell", "bg").

func (*Runtime) Register

func (r *Runtime) Register(entry *Entry)

Register adds a task entry. The caller is responsible for populating all fields.

func (*Runtime) Stop

func (r *Runtime) Stop(id string) bool

Stop cancels a running task by ID. Returns true if a running task was found and its cancel function was invoked. The background goroutine is responsible for writing the terminal status and EndedAt after observing the cancellation.

func (*Runtime) StopAll

func (r *Runtime) StopAll() int

StopAll cancels all running tasks. Returns the number cancelled.

func (*Runtime) Update

func (r *Runtime) Update(id string, fn func(e *Entry)) bool

Update applies a mutation function to a task entry under the lock. Returns false if the task is not found.

type Status

type Status string

Status represents the lifecycle state of a background task.

const (
	Running   Status = "running"
	Completed Status = "completed"
	Failed    Status = "failed"
)

type Type

type Type string

Type distinguishes the origin of a background task.

const (
	TypeShell    Type = "shell"
	TypeSubAgent Type = "subagent"
)