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
- Variables
- func Admit(tx *session.Tx, runs Runs, conversationID session.ID, draft Draft, now float64, ...) (session.ID, error)
- func AdmitStatus(tx *session.Tx, runs Runs, conversationID session.ID, draft Draft, now float64, ...) error
- func HasQueuedReset(items *delta.Arr) bool
- func InputDraft(content any, entry *delta.Obj, now float64) *jv.Object
- func IsDisplayOnly(entry *jv.Object) bool
- func PickInputEntry(entry *jv.Object) *jv.Object
- func RemoveItem(tx *session.Tx, conversationID, id session.ID) error
- func TakesContinuation(b *Boundary) bool
- func Unanswered(reason string) *jv.Object
- func UserDraft(content any, now float64) *jv.Object
- func WithdrawQueued(tx *session.Tx, conversationID session.ID) error
- func WithdrawQueuedFor(tx *session.Tx, conversationID session.ID, reason string) error
- type AbortResult
- type Admission
- type Boundary
- type BusyError
- type Draft
- type IdleError
- type QueueModes
- type Result
- type RunStart
- type Runs
Constants ¶
const ( ModeOne = "one-at-a-time" ModeAll = "all" )
Queue modes of the settings (src/harness/types.ts QueueMode).
const ( TypeInput = "input" TypeWrite = "write" TypeContinue = "continue" )
Submission types and settlement statuses (src/harness/types.ts SubmissionDraft).
Variables ¶
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.
var ErrConversationBusy = errors.New("ConversationBusy")
ErrConversationBusy matches a *BusyError with errors.Is. Read-only: assigned once at initialization.
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
RemoveItem is removeInboxItem: a withdrawn submission's item leaves the queue; the caller settles the submission.
func TakesContinuation ¶
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 ¶
Unanswered is the settlement {status: "unanswered", reason}.
func WithdrawQueued ¶
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.
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).
type Admission ¶
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.
type BusyError ¶
BusyError is Pi's ConversationBusy: a submission reached a busy conversation and was not admitted.
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 ¶
IdleError is Pi's ConversationIdle: an input with whenIdle "reject" reached an idle conversation and was not admitted.
type QueueModes ¶
type QueueModes struct{ Steering, FollowUp string }
QueueModes are the settings a boundary reads: steeringMode and followUpMode.
type Result ¶
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 ¶
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 RunStart ¶
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.