background

package
v0.7.0 Latest Latest
Warning

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

Go to latest
Published: Apr 13, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BuildTools added in v0.7.0

func BuildTools(mgr *Manager, defaultDeliverTo []string) []*agent.Tool

BuildTools creates tools for managing background tasks.

Types

type AgentRunner

type AgentRunner interface {
	Run(ctx context.Context, sessionKey string, prompt string) (string, error)
}

AgentRunner executes agent prompts.

type ChannelNotifier

type ChannelNotifier interface {
	SendMessage(ctx context.Context, channel string, message string) error
}

ChannelNotifier sends notifications to communication channels.

type Manager

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

Manager handles lifecycle management of background tasks.

func NewManager

func NewManager(runner AgentRunner, notify *Notification, maxTasks int, taskTimeout time.Duration, logger *zap.SugaredLogger) *Manager

NewManager creates a new background task Manager. maxTasks limits the total number of non-terminal tasks. taskTimeout is the maximum duration for a single task (default: 30m). The semaphore size controls how many tasks can run concurrently (defaults to maxTasks if <= 0).

func (*Manager) Cancel

func (m *Manager) Cancel(id string) error

Cancel cancels a running or pending task by ID.

func (*Manager) List

func (m *Manager) List() []TaskSnapshot

List returns snapshots of all tasks.

func (*Manager) Result

func (m *Manager) Result(id string) (string, error)

Result returns the result of a completed task.

func (*Manager) Shutdown

func (m *Manager) Shutdown(ctx context.Context) error

Shutdown cancels all Pending/Running tasks and waits for goroutines to finish.

func (*Manager) Status

func (m *Manager) Status(id string) (*TaskSnapshot, error)

Status returns a snapshot of the task with the given ID.

func (*Manager) Submit

func (m *Manager) Submit(ctx context.Context, prompt string, origin Origin) (string, error)

Submit creates and enqueues a new background task. It returns the task ID on success.

func (*Manager) WithProjection added in v0.7.0

func (m *Manager) WithProjection(projection Projection) *Manager

WithProjection configures an optional projection hook for task lifecycle mirroring.

type Monitor

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

Monitor provides progress tracking for background tasks.

func NewMonitor

func NewMonitor(manager *Manager, logger *zap.SugaredLogger) *Monitor

NewMonitor creates a new Monitor that tracks tasks in the given Manager.

func (*Monitor) ActiveCount

func (m *Monitor) ActiveCount() int

ActiveCount returns the number of tasks currently pending or running.

func (*Monitor) Summary

func (m *Monitor) Summary() MonitorSummary

Summary returns an aggregate summary of all task states.

type MonitorSummary

type MonitorSummary struct {
	Total     int `json:"total"`
	Pending   int `json:"pending"`
	Running   int `json:"running"`
	Done      int `json:"done"`
	Failed    int `json:"failed"`
	Cancelled int `json:"cancelled"`
}

MonitorSummary provides an aggregate view of background task states.

type Notification

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

Notification handles sending completion or failure notifications for background tasks.

func NewNotification

func NewNotification(notifier ChannelNotifier, typing TypingIndicator, logger *zap.SugaredLogger) *Notification

NewNotification creates a new Notification with the given notifier and logger.

func (*Notification) Notify

func (n *Notification) Notify(ctx context.Context, task *Task) error

Notify sends a notification about a completed or failed task to its origin channel.

func (*Notification) NotifyStart

func (n *Notification) NotifyStart(ctx context.Context, task *Task) error

NotifyStart sends a notification that a background task has started execution.

func (*Notification) StartTyping

func (n *Notification) StartTyping(ctx context.Context, channel string) func()

StartTyping starts a typing indicator on the given channel. The returned stop function ends the typing indicator. It is always non-nil.

type Origin

type Origin struct {
	Channel string `json:"channel"`
	Session string `json:"session"`
}

Origin identifies where a background task was initiated from.

type Projection added in v0.7.0

type Projection interface {
	PrepareTask(ctx context.Context, prompt string, origin Origin) (string, error)
	SyncTask(ctx context.Context, snap TaskSnapshot) error
}

Projection mirrors background task lifecycle into another authority layer. RunLedger uses this to create canonical task IDs and persist transitions.

type Status

type Status int

Status represents the lifecycle state of a background task.

const (
	Pending Status = iota + 1
	Running
	Done
	Failed
	Cancelled
)

func (Status) String

func (s Status) String() string

String returns the human-readable name of the status.

func (Status) Valid

func (s Status) Valid() bool

Valid reports whether s is a known task status.

func (Status) Values

func (s Status) Values() []Status

Values returns all known task statuses.

type Task

type Task struct {
	ID            string
	Status        Status
	Prompt        string
	Result        string
	Error         string
	OriginChannel string // channel that initiated the request (e.g. "telegram", "slack")
	OriginSession string // original session key
	StartedAt     time.Time
	CompletedAt   time.Time
	TokensUsed    int
	// contains filtered or unexported fields
}

Task represents a background execution unit.

func (*Task) Cancel

func (t *Task) Cancel()

Cancel transitions the task to the Cancelled state and invokes the cancel function.

func (*Task) Complete

func (t *Task) Complete(result string)

Complete transitions the task to the Done state with the given result. If the task is already Cancelled, the transition is skipped to preserve the cancellation status.

func (*Task) Fail

func (t *Task) Fail(errMsg string)

Fail transitions the task to the Failed state with the given error message. If the task is already Cancelled, the transition is skipped to preserve the cancellation status.

func (*Task) SetRunning

func (t *Task) SetRunning()

SetRunning transitions the task to the Running state and records the start time.

func (*Task) Snapshot

func (t *Task) Snapshot() TaskSnapshot

Snapshot returns an immutable copy of the task's current state.

type TaskSnapshot

type TaskSnapshot struct {
	ID            string    `json:"id"`
	Status        Status    `json:"status"`
	StatusText    string    `json:"status_text"`
	Prompt        string    `json:"prompt"`
	Result        string    `json:"result"`
	Error         string    `json:"error,omitempty"`
	OriginChannel string    `json:"origin_channel"`
	OriginSession string    `json:"origin_session"`
	StartedAt     time.Time `json:"started_at"`
	CompletedAt   time.Time `json:"completed_at,omitempty"`
	TokensUsed    int       `json:"tokens_used"`
}

TaskSnapshot is an immutable copy of a Task, safe for concurrent reading.

type TypingIndicator

type TypingIndicator interface {
	StartTyping(ctx context.Context, channel string) (stop func(), err error)
}

TypingIndicator starts a typing indicator on a channel.

Jump to

Keyboard shortcuts

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