backgroundtask

type Config struct {
	// ForegroundTimeoutMs sets the foreground budget: the time a foreground run is
	// allowed to occupy the foreground before its deadline fires.
	// When > 0, a foreground run that hasn't completed within this many
	// milliseconds reaches its deadline (see ShouldAutoBackground for what happens then).
	// When 0, there is no deadline (foreground runs block until completion).
	//
	// Default: 120000ms (120 seconds).
	ForegroundTimeoutMs *int

	// ShouldAutoBackground decides, at a foreground run's deadline, whether it may be
	// moved to the background (kept running) instead of being canceled. Applications
	// can use it to permit long-lived workloads such as servers and watchers while
	// timing out commands whose results are no longer useful. The hook receives the
	// task, so a host can branch on Task.Type and recover domain parameters from
	// Task.Metadata (e.g. the shell command via filesystem.CommandFromTask).
	//
	// Deciding whether a workload is genuinely long-lived is inherently host- and
	// command-specific, so this package ships no built-in policy: the framework
	// cannot reliably infer "never exits" from a command string, and a wrong guess
	// either kills a useful run or keeps a doomed one. Hosts encode their own rules.
	//
	// It is consulted ONLY for the auto path — a foreground run that hits its
	// deadline. An explicit RunInBackground run always backgrounds immediately,
	// regardless of this hook.
	//
	// When nil (the default), it is treated as always returning false: a run that
	// hits its deadline is canceled and reported as timed out, never auto-backgrounded.
	ShouldAutoBackground func(ctx context.Context, task *Task) bool

	// IDGen, when set, decides the full ID of every task created by this Manager.
	// If nil, Manager uses its default task-type-prefixed base62 ID.
	//
	// IDGen may be called concurrently by concurrent Run / RunStream calls. It
	// must return a non-empty ID. The returned ID must be unique among this
	// Manager's registered tasks; a duplicate fails task creation.
	IDGen IDGenerator

	// BackgroundNotice customizes the chunk emitted on a RunStream caller's stream
	// when a task starts in the background or is auto-moved there. The Manager owns
	// only lifecycle facts (id, type, output file); how a host tells the model to
	// retrieve the result is host-specific — one host exposes a task_output tool,
	// another points at the output file — so that wording does not belong in this
	// type-erased layer.
	//
	// When nil, defaultBackgroundNotice is used: it announces the background launch
	// and, when an output file is reserved, directs the reader to Read that path for
	// interim output.
	//
	// The ctx passed to the hook is the run's context (detached from the caller's
	// cancellation, carrying its values); use it only for value lookup, not to gate
	// the notice on cancellation.
	BackgroundNotice func(ctx context.Context, info NoticeInfo) string
}

type IDGenerator func(ctx context.Context, input *RunInput) (string, error)

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

type NoticeInfo struct {
	// Task is a snapshot of the task at the moment the notice is emitted, carrying
	// ID, Type, and OutputFile. Nil only if the task vanished mid-emit (not expected).
	Task *Task
	// AutoBackgrounded is false when the run was launched directly in the background
	// (RunInBackground), and true when a foreground run was auto-moved to the
	// background at its deadline because the ShouldAutoBackground hook permitted it
	// (a deadline the hook declines becomes a timeout failure, which never reaches
	// this notice). The true case is the same transition reported to subscribers as
	// TaskEventBackgrounded.
	AutoBackgrounded bool
}

type RunInput struct {
	// Description is a short human-readable title for the task, stored in Task.Description.
	Description string
	// Type is an optional tag for the task (e.g. "bash", "subagent"), stored in
	// Task.Type. See Task.Type.
	Type string
	// ToolUseID is the optional id of the tool call launching this task, stored in
	// Task.ToolUseID. See Task.ToolUseID.
	ToolUseID string
	// RunInBackground controls execution mode: true returns immediately with StatusRunning.
	RunInBackground bool
	// Metadata is optional caller-supplied data attached to the task's Task.Metadata.
	// It is for observers (Get/List, the task_output tool, the host) to correlate or
	// label background tasks — e.g. an originating tool-call ID, session, or trace.
	// The Manager does not interpret it. It is shallow-copied into the task on creation.
	Metadata map[string]any
	// OutputFile is the optional path the launcher will write this task's output
	// to. When non-empty it is recorded on Task.OutputFile and surfaced in the
	// background notice; the Manager itself never writes the file. The launcher
	// (a domain adapter) owns writing, so the file may carry interim output while
	// the task runs. Empty means the task has no output file.
	OutputFile string
	// ForegroundTimeoutMs optionally overrides the Manager's foreground budget for
	// this run only. When nil, the Manager's configured default applies. When non-nil,
	// it bounds how long the run may occupy the foreground before its deadline fires
	// (see Config.ShouldAutoBackground for what happens at the deadline). A value <= 0
	// removes the deadline for this run (blocks until completion). Ignored when
	// RunInBackground is true.
	ForegroundTimeoutMs *int
}

type Status string

type StreamWorkFunc func(ctx context.Context, task TaskInfo) (*schema.StreamReader[string], error)

type Task struct {
	// ID is the unique identifier for this task, generated by Manager.
	ID string
	// Type is a caller-supplied tag (e.g. "bash", "subagent") identifying what kind
	// of work this task runs. The Manager does not interpret it; it lets the
	// ShouldAutoBackground hook and observers distinguish domains without parsing
	// Description. Empty if the launcher did not set it.
	Type string
	// ToolUseID is the id of the tool call that launched this task, when known.
	// It lets a host correlate a task event back to the originating tool call.
	// Empty if the launcher did not set it.
	ToolUseID string
	// Description is a human-readable summary of what the task does.
	Description string
	// Status is the current lifecycle status.
	Status Status
	// Result contains the task output, set when Status is StatusCompleted.
	Result string
	// OutputFile is the path the task's output is written to, when the launcher
	// supplied one via RunInput.OutputFile. Empty otherwise. The Manager only
	// records and surfaces this path (in notices and Get/List); it never writes
	// the file — the launcher's work owns writing, so it may contain interim
	// output while the task is still running. The file outlives the in-memory
	// record, so it remains readable after the Manager is rebuilt.
	OutputFile string
	// OutputFileErr is set by the launcher (via MarkOutputFileUnreliable) when a
	// write to OutputFile fails, so the file is known to be incomplete. It is
	// empty while the file is trustworthy. When non-empty, neither OutputFile nor
	// Result can be treated as the authoritative complete output: the file has a
	// gap, and Result is only whatever the worker returned (which may be empty
	// while the task is still running, and — depending on the worker — may be a
	// partial projection of the file rather than its full content). Consumers
	// should report the file's failed state honestly rather than present either
	// side as complete. The Manager does not interpret the value beyond emptiness;
	// it carries the first failure's message for diagnostics.
	OutputFileErr string
	// Error contains the error message, set when Status is StatusFailed.
	Error string
	// RunInBackground indicates whether this task is running (or ran) in the
	// background — either launched with RunInBackground, or moved to the background
	// after exhausting its foreground budget. It distinguishes background tasks
	// from foreground ones when inspecting task state.
	RunInBackground bool
	// CreatedAt is the time the task was registered.
	CreatedAt time.Time
	// DoneAt is the time the task reached a terminal state. Nil if still running.
	DoneAt *time.Time
	// Metadata holds arbitrary extensible fields for future use.
	Metadata map[string]any
}

type TaskEvent struct {
	// Type is the transition that caused this event.
	Type TaskEventType
	// Task is the task snapshot immediately after the transition.
	Task *Task
}

type TaskEventType string

type TaskInfo struct {
	// ID is the Manager-generated task id. It is the one fact the work cannot
	// otherwise obtain: the id is assigned inside createTask, after the work
	// closure is already built. The launcher passes it to MarkOutputFileUnreliable
	// to report an output-file write failure against this task.
	ID string
	// Backgrounded is closed when this task moves to background execution: before
	// the work starts for an explicit RunInBackground launch, or at the
	// auto-background transition (foreground deadline reached and permitted). It
	// stays open for a run that completes in the foreground. Work uses it to stop
	// side effects that are only valid while the run is foreground — most notably
	// forwarding events to the launching turn's live stream, which the turn closes
	// once it ends. It is never nil.
	Backgrounded <-chan struct{}
}

type WorkFunc func(ctx context.Context, task TaskInfo) (result string, err error)