inbox

package
v0.7.0 Latest Latest
Warning

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

Go to latest
Published: Nov 5, 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"
	TypeContinue = "continue"
)

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.

View Source
var ErrConversationIdle = errors.New("ConversationIdle")

ErrConversationIdle matches an *IdleError 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 AdmitStatus

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

AdmitStatus is Admit that also reports how the submission was admitted, in a.

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 TakesContinuation

func TakesContinuation(b *Boundary) bool

TakesContinuation is generation.ts takesContinuation without the continuation itself: whether an answer's `onYield` continuation is taken (spec section 8.3), decided from the inbox before the final boundary places anything: only when it holds no user item, of which the boundary would select one, and no reset, which would otherwise run first.

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 Admission

type Admission struct {
	ID     session.ID
	Status string
	Link   any
}

Admission is what admitSubmission returns (submissions.ts Admission): the submission's ID and its `status` once admitted: queued, placed, or done (a stale write reports done), and, for a steer admission to a busy run, the run's carrier, which the submission's span links to.

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
	// WhenIdle is "reject" or empty (start a run).
	WhenIdle string
	// Span is the host's handle of the submission's span, which the commit's events go to (TxScope.Span); Trace is the carrier of the submission's span (propagation.inject(span)), stored on its record; nil: none.
	Trace any
	Span  uint32
	// Propagation is set when that span's adapter propagates (span.propagation !== undefined).
	Propagation bool
}

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

type IdleError

type IdleError struct{ ConversationID session.ID }

IdleError is Pi's ConversationIdle: an input with whenIdle "reject" reached an idle conversation and was not admitted.

func (*IdleError) Error

func (e *IdleError) Error() string

func (*IdleError) Is

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

Is matches ErrConversationIdle.

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
	First    session.ID
	HasFirst bool
	Reset    bool
}

Result is the selected user items in ID order, the first entry the boundary placed, a write's or a user item's (a run it starts begins there, LiveRun.first; HasFirst: whether it placed one), 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.

func (Result) Start

func (r Result) Start() RunStart

Start is what startRun takes for the run the boundary's users start.

type RunStart

type RunStart struct {
	Inputs   []session.ID
	First    session.ID
	HasFirst bool
}

RunStart is what startRun takes (generation.ts): the run's placed inputs, and its first entry (LiveRun.first; HasFirst: whether it has one).

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, run RunStart) 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