background

package
v0.9.0 Latest Latest
Warning

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

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

Documentation

Overview

Package background holds the shared background-work parts: in-memory implementations, the lifecycle-listener registry and the lifecycle helpers. It must not branch on activity kind.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Clock 

type Clock interface {
	Now() time.Time
}

Clock abstracts time so tests can move it.

type Delivery 

type Delivery struct {
	// Text is the model-facing body, one line per entry, without a wrapper.
	Text string
	// AckIDs are the completion notices Text delivers. They are acknowledged
	// once the assistant message carrying them is persisted.
	AckIDs []string
}

Delivery is background-work context for the model at one round boundary.

type Lifecycle 

type Lifecycle struct {
	Registry  interfaces.ActivityRegistry
	Inbox     interfaces.NoticeInbox
	KeepAlive interfaces.SessionKeepAliver // optional
	Events    interfaces.WorkEventEmitter  // optional
	Logf      func(ctx context.Context, format string, args ...any)
}

Lifecycle combines the shared parts in the only orders that are safe. Features call these four methods and never the underlying interfaces.

func (*Lifecycle) Alive 

func (l *Lifecycle) Alive(
	ctx context.Context, s interfaces.SessionRef, id string, lease time.Duration,
) (bool, error)

Alive renews the registration and, when it still exists, keeps the sandbox alive. found=false means the item was removed or expired; the caller decides whether to re-register.

func (*Lifecycle) Begin 

func (l *Lifecycle) Begin(
	ctx context.Context, s interfaces.SessionRef, a interfaces.BackgroundActivity,
	lease time.Duration, kindCap int, start func(context.Context) error,
) error

Begin registers a, then runs start. Registering first means lifecycle protection is in force the moment the work exists. If start fails the registration is removed. On success the sandbox is kept alive once at once, because nothing renewed it before the work began.

func (*Lifecycle) Discard 

func (l *Lifecycle) Discard(ctx context.Context, s interfaces.SessionRef, id string) error

Discard removes the registration without a notice or event. Use it only when the result was already handed to the model directly.

func (*Lifecycle) Finish 

func (l *Lifecycle) Finish(
	ctx context.Context, s interfaces.SessionRef, n interfaces.BackgroundNotice,
	r interfaces.WorkResult, parentMessageID string,
) error

Finish records the completion notice, emits work_finished only if this call wrote the notice first, then removes the registration. Push comes first: in the other order there is a window where neither the registry nor the inbox knows the item. If Push fails the registration is kept so the item stays queryable and a later Finish can retry.

type Listeners 

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

Listeners is the ordered set of session lifecycle listeners. Feature listeners run in registration order; on delete the shared activity registry and inbox are cleared after all of them have run.

func NewListeners 

func NewListeners(
	registry interfaces.ActivityRegistry,
	inbox interfaces.NoticeInbox,
	logf func(ctx context.Context, format string, args ...any),
) *Listeners

NewListeners returns an empty listener set. A nil logf discards warnings.

func (*Listeners) NotifyDelete 

func (l *Listeners) NotifyDelete(ctx context.Context, s interfaces.SessionRef) error

NotifyDelete calls OnDelete on every listener, then clears the session's activity items and notices. A failed stop preserves shared state and keeps the session available for a retry, especially on a retained shared machine.

func (*Listeners) NotifyDeleteAborted 

func (l *Listeners) NotifyDeleteAborted(ctx context.Context, s interfaces.SessionRef)

NotifyDeleteAborted reopens submission gates when a listener or the session repository rejected deletion. Already stopped jobs remain stopped.

func (*Listeners) NotifyStop 

func (l *Listeners) NotifyStop(ctx context.Context, s interfaces.SessionRef)

NotifyStop calls OnStop on every listener. Errors are logged, never returned.

func (*Listeners) Register 

func (l *Listeners) Register(listener interfaces.SessionLifecycleListener)

Register appends a listener.

type MemoryActivityRegistry 

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

MemoryActivityRegistry is the single-process ActivityRegistry used by Lite.

func NewMemoryActivityRegistry 

func NewMemoryActivityRegistry(clock Clock) *MemoryActivityRegistry

NewMemoryActivityRegistry returns an empty registry. A nil clock means SystemClock.

func (*MemoryActivityRegistry) Add 

func (r *MemoryActivityRegistry) Add(
	_ context.Context, s interfaces.SessionRef, a interfaces.BackgroundActivity, lease time.Duration, kindCap int,
) error

Add implements interfaces.ActivityRegistry.

func (*MemoryActivityRegistry) List 

func (r *MemoryActivityRegistry) List(
	_ context.Context, s interfaces.SessionRef,
) ([]interfaces.BackgroundActivity, error)

List implements interfaces.ActivityRegistry.

func (*MemoryActivityRegistry) Remove 

func (r *MemoryActivityRegistry) Remove(_ context.Context, s interfaces.SessionRef, id string) error

Remove implements interfaces.ActivityRegistry.

func (*MemoryActivityRegistry) Renew 

func (r *MemoryActivityRegistry) Renew(
	_ context.Context, s interfaces.SessionRef, id string, lease time.Duration,
) (bool, error)

Renew implements interfaces.ActivityRegistry.

type MemoryNoticeInbox 

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

MemoryNoticeInbox is the single-process NoticeInbox used by Lite.

func NewMemoryNoticeInbox 

func NewMemoryNoticeInbox(clock Clock) *MemoryNoticeInbox

NewMemoryNoticeInbox returns an empty inbox. A nil clock means SystemClock.

func (*MemoryNoticeInbox) Ack 

func (b *MemoryNoticeInbox) Ack(_ context.Context, s interfaces.SessionRef, ids []string) error

Ack implements interfaces.NoticeInbox.

func (*MemoryNoticeInbox) Clear 

func (b *MemoryNoticeInbox) Clear(_ context.Context, s interfaces.SessionRef) error

Clear implements interfaces.NoticeInbox.

func (*MemoryNoticeInbox) Pending 

func (b *MemoryNoticeInbox) Pending(
	_ context.Context, s interfaces.SessionRef,
) ([]interfaces.BackgroundNotice, error)

Pending implements interfaces.NoticeInbox.

func (*MemoryNoticeInbox) Push 

func (b *MemoryNoticeInbox) Push(
	_ context.Context, s interfaces.SessionRef, n interfaces.BackgroundNotice,
) (bool, error)

Push implements interfaces.NoticeInbox.

type RunNotices 

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

RunNotices decides, for one agent run, what the model is told about background work and when. A run executes in one process, so its sets live in memory; the shared registry and inbox are only read here.

func NewRunNotices 

func NewRunNotices(
	s interfaces.SessionRef, registry interfaces.ActivityRegistry, inbox interfaces.NoticeInbox,
) *RunNotices

NewRunNotices returns a tracker for one run of session s.

func (*RunNotices) BeforeFinal 

func (r *RunNotices) BeforeFinal(ctx context.Context) (Delivery, error)

BeforeFinal returns what to tell the model before it may finish: unseen completion notices, and one reminder for each item this run started that is still running and has not been reminded about.

func (*RunNotices) MarkSeen 

func (r *RunNotices) MarkSeen(ids ...string)

MarkSeen records finished IDs a tool already showed the model, so their notices are not injected again and are acknowledged with the turn.

func (*RunNotices) MarkStarted 

func (r *RunNotices) MarkStarted(id string)

MarkStarted records work this run submitted and got back as still running. Only such work is reminded about before the final answer.

func (*RunNotices) RoundStart 

func (r *RunNotices) RoundStart(ctx context.Context) (Delivery, error)

RoundStart returns what to tell the model before a round's LLM call: on the run's first boundary, the work still running; on every boundary, completion notices this run has not seen.

func (*RunNotices) TakeSeen 

func (r *RunNotices) TakeSeen() []string

TakeSeen returns the IDs MarkSeen recorded since the previous call.

type SystemClock 

type SystemClock struct{}

SystemClock is the real wall clock.

func (SystemClock) Now 

func (SystemClock) Now() time.Time

Now returns time.Now().

Source Files

View all Source files

Directories

Path Synopsis
Package backgroundtest holds contract tests shared by every implementation of the background-work interfaces.
 Package backgroundtest holds contract tests shared by every implementation of the background-work interfaces.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.