inputqueue

package
v0.6.2 Latest Latest
Warning

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

Go to latest
Published: Nov 13, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var ErrInputTextRequired = errors.New("inputqueue: text is required")

ErrInputTextRequired reports a queued input without text or attachments.

Functions

func DecodeMentions

func DecodeMentions(raw string) ([]mention.Mention, error)

DecodeMentions reads a persisted mentions array; blank and empty arrays decode as none.

func EncodeMentions

func EncodeMentions(mentions []mention.Mention) (string, error)

EncodeMentions renders verified mentions as the JSON array persisted beside queued input and prompt admissions. No mentions persist as the empty array.

func HasMentions

func HasMentions(raw string) bool

HasMentions reports whether a persisted mentions array carries at least one mention.

Types

type Config

type Config struct {
	QueueCap     int
	MaxTextBytes int
}

Config controls queue admission.

type IDGenerator

type IDGenerator func() (string, error)

IDGenerator returns a stable queue entry ID or the entropy failure that prevented allocation.

type InputRequest

type InputRequest struct {
	MessageID        string
	Priority         int
	SessionID        string
	Text             string
	TargetTurnID     string
	Generation       int64
	Runtime          store.SessionInputRuntime
	SkillInvocations []commandpkg.Invocation
	Mentions         []mention.Mention
	// HumanIngress records human operator authorship; it selects the session-references form at dispatch.
	HumanIngress bool
	Attachments  []store.SessionInputAttachment
	// Coalesce merges a synthetic wake into the session's open row of its key.
	Coalesce *store.SessionInputCoalesce
}

InputRequest carries the common fields for a non-admitted busy input.

type MentionAdmission

type MentionAdmission struct {
	Mentions     []mention.Mention
	HumanIngress bool
}

MentionAdmission is what admission verified for a replacement's authored text: its mentions and whether the human operator authored it.

type Option

type Option func(*Service)

Option customizes a Service.

func WithClock

func WithClock(now func() time.Time) Option

WithClock injects a deterministic clock.

func WithIDGenerator

func WithIDGenerator(generator IDGenerator) Option

WithIDGenerator injects deterministic queue ids.

type Service

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

Service owns validation and admission policy for session busy input.

func New

func New(store Store, cfg Config, opts ...Option) (*Service, error)

New constructs a busy-input queue service.

func (*Service) Cancel

func (s *Service) Cancel(ctx context.Context, sessionID string, entryID string) (store.SessionInputQueueEntry, error)

Cancel cancels one pending queue entry.

func (*Service) CancelPendingSteer

func (s *Service) CancelPendingSteer(ctx context.Context, sessionID, entryID string) error

func (*Service) ClaimBatch

func (s *Service) ClaimBatch(
	ctx context.Context,
	sessionID string,
	limit int,
	accept func(*store.SessionInputQueueEntry) bool,
) ([]store.SessionInputQueueEntry, error)

ClaimBatch leases up to limit consecutive entries behind an already claimed head while accept approves them. A store without batch support dispatches entries one at a time.

func (*Service) ClaimNext

func (s *Service) ClaimNext(
	ctx context.Context,
	sessionID string,
) (store.SessionInputQueueEntry, bool, error)

ClaimNext leases the next input eligible for dispatch.

func (*Service) CurrentGeneration

func (s *Service) CurrentGeneration(ctx context.Context, sessionID string) (int64, error)

CurrentGeneration reads the current persisted generation for queue fencing.

func (*Service) Enqueue

Enqueue appends operator input behind the active prompt turn.

func (*Service) EnqueueAdmitted

func (s *Service) EnqueueAdmitted(
	ctx context.Context,
	admission store.SessionPromptAdmissionRequest,
	generation int64,
	targetTurnID string,
	supersede bool,
) (store.SessionPromptAdmission, store.SessionInputQueueEntry, int, bool, error)

EnqueueAdmitted atomically persists one external command receipt and its queue entry. With supersede, an agent-authored entry cancels its sender's older undispatched entries in the same transaction; the store ignores it for operator input.

func (*Service) EnqueueAdmittedInterrupt

func (s *Service) EnqueueAdmittedInterrupt(
	ctx context.Context,
	admission store.SessionPromptAdmissionRequest,
	targetTurnID string,
) (store.SessionPromptAdmission, store.SessionInputQueueEntry, bool, error)

EnqueueAdmittedInterrupt atomically persists a replacement command receipt and queue entry.

func (*Service) EnqueueInterrupt

func (s *Service) EnqueueInterrupt(
	ctx context.Context,
	req InputRequest,
) (store.SessionInputQueueEntry, int, error)

EnqueueInterrupt persists replacement input before the active turn is canceled.

func (*Service) EnqueueSynthetic

func (s *Service) EnqueueSynthetic(
	ctx context.Context,
	req InputRequest,
	turnID string,
	prompt *store.SessionInputSyntheticPrompt,
	taskRunID string,
) (store.SessionInputQueueEntry, error)

EnqueueSynthetic captures daemon work under the same capacity and claim policy as human input.

func (*Service) FailStaleDispatches

func (s *Service) FailStaleDispatches(ctx context.Context) (int, error)

FailStaleDispatches settles leases left by a previous daemon process.

func (*Service) Get

func (s *Service) Get(
	ctx context.Context,
	sessionID string,
	entryID string,
) (store.SessionInputQueueEntry, error)

Get returns one exact durable queue entry.

func (*Service) List

func (s *Service) List(
	ctx context.Context,
	sessionID string,
) ([]store.SessionInputQueueEntry, error)

List returns current pending operator inputs in dispatch order.

func (*Service) ListSupersededSteers

func (s *Service) ListSupersededSteers(
	ctx context.Context,
	sessionID, afterID string,
) ([]store.SessionInputQueueEntry, error)

ListSupersededSteers returns a bounded page for idempotent transcript repair.

func (*Service) MarkClearTraceProjected

func (s *Service) MarkClearTraceProjected(ctx context.Context, sessionID, entryID string) error

func (*Service) MarkFailed

func (s *Service) MarkFailed(ctx context.Context, sessionID string, entryID string, summary string) error

MarkFailed records failed dispatch.

func (*Service) MarkSent

func (s *Service) MarkSent(ctx context.Context, sessionID string, entryID string) error

MarkSent records successful dispatch.

func (*Service) MarkSentInTurn

func (s *Service) MarkSentInTurn(ctx context.Context, sessionID, entryID, turnID string) error

MarkSentInTurn records successful dispatch together with the turn that consumed the entry.

func (*Service) PeekNext

func (s *Service) PeekNext(
	ctx context.Context,
	sessionID string,
) (store.SessionInputQueueEntry, bool, error)

PeekNext returns the next eligible input without mutating its queue state.

func (*Service) PendingClearTraces

func (s *Service) PendingClearTraces(ctx context.Context, sessionID string) ([]store.SessionInputClearTrace, error)

func (*Service) PrepareQueue

func (s *Service) PrepareQueue(req InputRequest) (store.SessionInputQueueInsert, error)

PrepareQueue validates queued input and allocates its durable insert without persisting it.

func (*Service) PromoteQueuedAgentToSteer

func (s *Service) PromoteQueuedAgentToSteer(
	ctx context.Context,
	sessionID, entryID, targetTurnID string,
) (store.SessionInputQueueEntry, bool, error)

PromoteQueuedAgentToSteer stages one queued agent message as steering for targetTurnID while keeping its identity. It reports false when the entry is no longer eligible.

func (*Service) PromoteToSteer

func (s *Service) PromoteToSteer(
	ctx context.Context,
	sessionID string,
	entryID string,
	text string,
	targetTurnID string,
	messageID string,
	idempotencyKey string,
	skillInvocations []commandpkg.Invocation,
	admission MentionAdmission,
) (store.SessionInputQueueEntry, bool, error)

PromoteToSteer atomically replaces one queued input with priority steering input.

func (*Service) Release

func (s *Service) Release(ctx context.Context, sessionID string, entryID string) error

Release returns a leased entry to queued state after a dispatch race.

func (*Service) Replace

func (s *Service) Replace(
	ctx context.Context,
	sessionID string,
	entryID string,
	text string,
	messageID string,
	idempotencyKey string,
	skillInvocations []commandpkg.Invocation,
	admission MentionAdmission,
) (store.SessionInputQueueEntry, bool, error)

Replace atomically replaces one queued input with a new queue identity.

func (*Service) ReplayPromotion

func (s *Service) ReplayPromotion(
	ctx context.Context,
	sessionID string,
	entryID string,
	text string,
	targetTurnID string,
	messageID string,
	idempotencyKey string,
	skillInvocations []commandpkg.Invocation,
) (store.SessionInputQueueEntry, bool, error)

ReplayPromotion returns an exact prior queue-to-steer mutation without changing queue state.

func (*Service) ReserveSteer

func (s *Service) ReserveSteer(
	ctx context.Context,
	sessionID, entryID string,
) (store.SessionInputQueueEntry, bool, error)

func (*Service) ResolveSteer

func (s *Service) ResolveSteer(
	ctx context.Context, sessionID, entryID string, delivery store.SteerDeliveryMode,
) (store.SessionInputQueueEntry, error)

func (*Service) RevertPromotedAgent

func (s *Service) RevertPromotedAgent(ctx context.Context, sessionID, entryID string) (bool, error)

RevertPromotedAgent returns a promoted agent message whose delivery never started to the queue.

func (*Service) SettlePendingSteer

func (s *Service) SettlePendingSteer(
	ctx context.Context, sessionID, entryID string, delivery store.SteerDeliveryMode,
) (store.SessionInputQueueEntry, bool, error)

func (*Service) StageAdmittedSteer

func (s *Service) StageAdmittedSteer(
	ctx context.Context,
	admission store.SessionPromptAdmissionRequest,
	targetTurnID string,
	generation int64,
	supersede bool,
) (store.SessionPromptAdmission, store.SessionInputQueueEntry, bool, error)

StageAdmittedSteer atomically persists one external receipt and its steering entry. With supersede, an agent-authored steer also cancels its sender's older undispatched queued messages in the same transaction, exactly as a superseding queued send does.

func (*Service) StageSteer

func (s *Service) StageSteer(
	ctx context.Context,
	req InputRequest,
) (store.SessionInputQueueEntry, error)

StageSteer persists replacement steering guidance while a turn is active.

func (*Service) SupersedeBoundarySteers

func (s *Service) SupersedeBoundarySteers(
	ctx context.Context,
	sessionID, turnID, replacementID string,
) ([]string, error)

SupersedeBoundarySteers retires guidance superseded by an empty operator interrupt.

func (*Service) SyntheticAdmitted

func (s *Service) SyntheticAdmitted(ctx context.Context, sessionID, messageID string) (bool, error)

SyntheticAdmitted reports whether a synthetic input with messageID was already queued, dispatched, or sent for the session. Stores without the lookup report false.

type Store

type Store interface {
	store.SessionInputQueueStore
}

Store is the persistence boundary for busy input.

Jump to

Keyboard shortcuts

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