inbox

package
v0.5.2 Latest Latest
Warning

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

Go to latest
Published: Oct 22, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package inbox is the Session-side submission queue of src/harness/inbox.ts and submissions.ts: the built-in pi.inbox document, the boundaries that place queued items, and admission, abort and withdrawal of submissions. It runs inside a session.Tx and holds no state.

Index

Constants

View Source
const (
	ModeOne = "one-at-a-time"
	ModeAll = "all"
)

Queue modes of the settings (src/harness/types.ts QueueMode).

View Source
const (
	TypeInput = "input"
	TypeWrite = "write"
)

Submission types and settlement statuses (src/harness/types.ts SubmissionDraft).

Variables

View Source
var Def = &session.DocDef{
	Kind:    "pi.inbox",
	Version: 1,
	Scope:   session.ScopeConversation,
	History: session.HistoryLatest,
	Fork:    session.ForkInitial,
	Initial: func(any) *jv.Object {
		value := jv.NewObject()
		value.Set("items", []any{})
		return value
	},
	CheckpointWhen: func(value *jv.Object, _ []delta.Op, _ int) bool {
		items, _ := value.Get("items")
		list, _ := items.([]any)
		return len(list) == 0
	},
}

Def is InboxDoc: one conversation's submissions waiting for a boundary, in ID order. Its value is {items}; an item is {id, mode: "steer"|"followUp", content, entry?} (entry: the {kind, data?} an input is placed as when not pi.user) or {id, mode: "write", entry}. Read-only: assigned once at initialization.

View Source
var ErrConversationBusy = errors.New("ConversationBusy")

ErrConversationBusy matches a *BusyError with errors.Is. Read-only: assigned once at initialization.

Functions

func Admit

func Admit(tx *session.Tx, runs Runs, conversationID session.ID, draft Draft, now float64, modes QueueModes) (session.ID, error)

Admit is admitSubmission: it admits a submission inside a commit (spec section 6); Conversation.submit() and conversation-owned compactions share it. A known request ID returns its existing submission without writing. A busy display-only write (only kind and data) is appended and settled done at once, busy or not, as it changes nothing the model sees; only behind a queued reset it queues, so it lands after the reset instead of before it in the context the reset ends. A busy conversation queues anything else in pi.inbox, or rejects whenBusy "reject" input with ConversationBusy. An idle conversation with queued items queues it behind them and runs a final boundary. Otherwise idle input places its entry (pi.user, or the input's own) and starts a run, and an idle write appends its entry and settles done, or stale when its head reaches before the active range.

func HasQueuedReset

func HasQueuedReset(items *delta.Arr) bool

HasQueuedReset is hasQueuedReset: whether a reset (a head "self" write) is queued; entries appended before it leave the active range when it lands.

func InputDraft

func InputDraft(content any, entry *delta.Obj, now float64) *jv.Object

InputDraft is the entry draft an input is placed as (appendInput): the pi.user draft, or the input's entry {kind, data?} with the user message of content as its model.

func IsDisplayOnly

func IsDisplayOnly(entry *jv.Object) bool

IsDisplayOnly is isDisplayOnly: whether a write has no model, head or edits (a present member counts, even if empty), so it changes nothing the model sees and needs no boundary.

func PickInputEntry

func PickInputEntry(entry *jv.Object) *jv.Object

PickInputEntry is pickInputEntry: the kind and data of an input's entry as strict JSON, without other members an untyped caller might pass.

func RemoveItem

func RemoveItem(tx *session.Tx, conversationID, id session.ID) error

RemoveItem is removeInboxItem: a withdrawn submission's item leaves the queue; the caller settles the submission.

func Unanswered

func Unanswered(reason string) *jv.Object

Unanswered is the settlement {status: "unanswered", reason}.

func UserDraft

func UserDraft(content any, now float64) *jv.Object

UserDraft is the pi.user entry draft of one user input: model is [UserMessage].

func WithdrawQueued

func WithdrawQueued(tx *session.Tx, conversationID session.ID) error

WithdrawQueued is withdrawQueuedInputs, used by Conversation.abort() and abort cascades: each queued input settles unanswered with reason aborted and leaves the inbox; queued writes stay for later placement.

func WithdrawQueuedFor

func WithdrawQueuedFor(tx *session.Tx, conversationID session.ID, reason string) error

WithdrawQueuedFor is withdrawQueuedInputs with a reason: each queued input settles unanswered with reason and leaves the inbox; queued writes stay for later placement.

Types

type AbortResult

type AbortResult string

AbortResult is the outcome of Abort.

const (
	Aborted       AbortResult = "aborted"
	AlreadyPlaced AbortResult = "already_placed"
	Settled       AbortResult = "settled"
	NotFound      AbortResult = "not_found"
)

Abort outcomes (submissions.ts AbortResult, plus not_found).

func Abort

func Abort(tx *session.Tx, id, conversationID session.ID) (AbortResult, error)

Abort is Submissions.abort: it withdraws a queued submission and removes its inbox item; placed inputs and settled submissions are reported. conversationID zero matches any conversation.

type Boundary

type Boundary struct {
	ConversationID session.ID
	Inbox          *delta.Obj
	Modes          QueueModes
	// Head is the start of the active range, the newest head marker's head; heads written in this commit advance it.
	Head    session.ID
	HasHead bool
}

Boundary is what a boundary reads before the commit's first table write, and the newest head it has seen so far.

func Prepare

func Prepare(tx *session.Tx, conversationID session.ID, modes QueueModes) (*Boundary, error)

Prepare is prepareBoundary: table reads must precede the commit's first table write, so callers prepare the boundary at the start of their commit.

func (*Boundary) IsStale

func (b *Boundary) IsStale(entry *jv.Object) bool

IsStale is isStale: whether a head write targets an entry before the active range, so placing it would bring back cut history.

type BusyError

type BusyError struct{ ConversationID session.ID }

BusyError is Pi's ConversationBusy: a submission reached a busy conversation and was not admitted.

func (*BusyError) Error

func (e *BusyError) Error() string

func (*BusyError) Is

func (e *BusyError) Is(target error) bool

Is matches ErrConversationBusy.

type Draft

type Draft struct {
	RequestID *string
	Type      string
	Content   any
	Entry     *jv.Object
	// WhenBusy is "steer", "followUp" or "reject"; empty queues as followUp.
	WhenBusy string
}

Draft is a SubmissionDraft: input carries Content, WhenBusy and optionally the InputEntry it is placed as (Entry), a write carries Entry, the entry it appends.

type QueueModes

type QueueModes struct{ Steering, FollowUp string }

QueueModes are the settings a boundary reads: steeringMode and followUpMode.

type Result

type Result struct {
	Users []session.ID
	Reset bool
}

Result is the selected user items in ID order, and whether a head "self" write (a reset) was placed.

func Apply

func Apply(tx *session.Tx, b *Boundary, final bool, now float64) (Result, error)

Apply is applyBoundary: it places the queued items a boundary selects (spec section 6): every write, the first or all steers, and at final the first or all follow-ups. A selected reset turns a postTools boundary into final. Writes are placed first and user items after them, each in ID order, so user items queued before a reset run in the new context. A write whose head targets an entry before the active range, including a range started earlier in this commit, is stale. Selected and stale items are removed positionally, after the entries are appended.

type Runs

type Runs interface {
	Live(tx *session.Tx, conversationID session.ID) (*delta.Obj, error)
	Start(tx *session.Tx, conversationID session.ID, live *delta.Obj, inputs []session.ID) error
}

Runs is what admission needs of the generation task: the conversation's pi.live document and the start of a run for placed inputs (startRun in src/harness/generation.ts). The turn package, which depends on this one, implements it.

Jump to

Keyboard shortcuts

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