api

package
v0.1.2 Latest Latest
Warning

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

Go to latest
Published: Nov 18, 2026 License: Apache-2.0 Imports: 15 Imported by: 0

Documentation

Overview

Package api holds the contracts shared by hosts, providers and storages.

The protocol types (Request, Message, the Content blocks and the Event stream a Provider emits) are what a provider adapter implements against. MessageStorage and UploadStorage are what a host implements to keep threads and uploaded files somewhere other than the defaults; WorkspaceStorage and FS describe the workspace neui gives each thread, and FS is what a tool works in. Instance and the Chat* types are the session-side view a chat UI renders from. ThreadConfig, FilesConfig and IslandConfig are the tunables for the root package's WithThreadConfig, WithFilesConfig (or the per-session OptionFilesConfig) and WithIslandConfig. The errors here are the sentinels callers compare with errors.Is.

Index

Constants

View Source
const (
	UserUploadsDir  = "user_uploads"
	AgentUploadsDir = "agent_uploads"
)

UserUploadsDir and AgentUploadsDir are the virtual directories under which FS serves the thread's stored files (OriginUser and OriginAgent); every other path is the workspace on disk.

View Source
const (
	// RoundInput marks a round that has only its input: its response is
	// still running, or it was interrupted before one was stored. It is
	// skipped on replay and can be retried.
	RoundInput = RoundState("")
	// RoundOk marks a round whose response completed (EventOk), with or
	// without tool calls.
	RoundOk = RoundState("ok")
	// RoundRefuse marks a round the model refused to answer. The model does
	// not see it again, and the tool results it answered reach the model only
	// as a note that they were omitted. It cannot be retried; Rewind it
	// instead.
	RoundRefuse = RoundState("refuse")
	// RoundAbort marks a round the user aborted during response
	// streaming; not replayed, has a retry option.
	RoundAbort = RoundState("abort")
	// RoundError marks a round that hit a network or other error; skipped
	// on replay, has retry.
	RoundError = RoundState("error")
)
View Source
const NoRoundID = RoundID(-1)

NoRoundID is the none/open sentinel for RoundID parameters.

View Source
const ReplayHeadroom = 1 << 20

ReplayHeadroom is the part of the model's request limit, 1 MiB, that a thread's byte budget leaves free for the tool schemas and the request envelope, which the budget does not count.

Variables

View Source
var DiscardedArguments = json.RawMessage("!discarded-arguments")

DiscardedArguments stands in ContentToolUse.Input for arguments that arrived and never formed valid JSON. It is deliberately not JSON at all: arguments a provider sent are always valid JSON, so nothing can collide with it and bytes.Equal is the whole test.

It is a marker held in memory and never reaches a wire of any kind. ContentToolUse.MarshalJSON writes nil in its place, so storage and every reload read a call that was sent no arguments, and what survives the round trip is the ToolErrJSON on the result answering it.

View Source
var ErrAskInIsland = errors.New("an ask tool cannot be an island app function")

ErrAskInIsland reports an Ask added to an island Library: an app function runs inside a script or a widget, where no one waits on a chat question.

View Source
var ErrCanceledByUser = errors.New("canceled by user")

ErrCanceledByUser is the cause a tool or task context carries when the user stopped the round, cancelled the task from the UI, or rewound past it; read it with context.Cause. An Ask the user dismisses returns it as its error. Any other cancellation is the runtime's own.

View Source
var ErrCompactionFailed = errors.New("the conversation no longer fits the model's context window, even after compaction")

ErrCompactionFailed reports that the conversation no longer fits the model's context window, even after compaction. It arrives as the Err of a ChatEventCriticalError after the failed round is stored, and the chat link closes as with any critical error.

View Source
var ErrDisabled = errors.New("neui for this session is disabled")

ErrDisabled is what Instance methods return while neui is not enabled for the session, before Enable or after Disable.

View Source
var ErrDrift = errors.New("thread advanced")

ErrDrift reports that a thread advanced between the read the caller worked from and the write it asked for, so nothing was written.

View Source
var ErrExists = errors.New("id already taken")

ErrExists reports a create on an id or name already taken; nothing is written.

View Source
var ErrInputTooLarge = errors.New("message is too large to send, split it into smaller messages or attach the content as a file")

ErrInputTooLarge reports an input over the round item budget (ThreadConfig.ReplayItemShare), counting its text and the file links its attachments turn into. It is refused where it is submitted, drafted or rewound to, and nothing of it is drafted, stored or sent. The error text tells the user to split it or attach the content as a file.

View Source
var ErrInvalidName = errors.New("invalid file name")

ErrInvalidName reports a name the uploads dirs cannot hold: empty, dotted, nested, or aimed outside an uploads dir.

View Source
var ErrMeasuredTooLarge = errors.New("provider refused a request measured as fitting")

ErrMeasuredTooLarge marks the CodeTooLarge an adapter reports when the server refused a request the adapter had already measured as fitting Model.RequestBytes: the declared limit over-promises for that endpoint, or the refusal is not about bytes at all. Neither is transient, so a caller reading it with errors.Is ends the turn instead of sending less and trying again, and the error names both the size measured and the limit it was measured against.

View Source
var ErrNoProvider = errors.New("no provider: set WithProvider on the app or pass OptionProvider to Enable")

ErrNoProvider is what Enable returns when the session would have no provider: the app has no WithProvider and Enable gets no OptionProvider, or the last OptionProvider is given nil. The session stays as it was.

View Source
var ErrNotFound = errors.New("not found")

ErrNotFound reports that the thread, record, file or path the caller named does not exist.

View Source
var ErrOutOfRange = errors.New("read offset past end of file")

ErrOutOfRange reports a read offset at or past the end of the file; reading a whole empty file from offset 0 is not an error.

View Source
var ErrQuota = errors.New("workspace quota exceeded; delete files no longer needed to free space")

ErrQuota reports a workspace write refused by the configured limits.

View Source
var ErrReadOnly = errors.New("uploads dirs accept no direct writes; copy an upload into the workspace to edit it, copy to agent_uploads/<name> to store")

ErrReadOnly reports a write aimed at the uploads dirs.

View Source
var ErrReserved = errors.New("that name is reserved for module scratch space and is not part of the workspace; use a different name")

ErrReserved reports a path aimed at the scratch directory TempDir hands to modules; it is not part of the workspace.

View Source
var ErrTooLarge = errors.New("file too large")

ErrTooLarge reports a file refused for exceeding the configured size cap.

View Source
var ErrTooMany = errors.New("too many files")

ErrTooMany reports a file refused because the attachment count cap is reached.

View Source
var ErrToolNotFound = errors.New("tool not found")

ErrToolNotFound reports a tool call naming no registered tool.

View Source
var ErrUnlinked = errors.New("instance was detached from the thread")

ErrUnlinked reports a call through an instance or chat that holds no thread, or no longer holds the one it acted on: the thread was reopened elsewhere or closed, including by Disable or a forced Enable. It is also the context.Cause of a running tool or task cancelled for that reason. Reopen the thread to act on it again.

View Source
var ErrVirtual = errors.New("uploads live in file storage and have no local path; copy into the workspace first")

ErrVirtual reports a local-path request for an entry that lives in file storage.

View Source
var ErrWrongState = errors.New("thread is in the wrong state to perform this action")

ErrWrongState reports an action the thread cannot take right now, such as sending while an input is already pending, sending an empty input, or stopping when nothing runs. Nothing changed; retry once the state allows it.

View Source
var NoCompaction = Compaction{
	Target: NoRoundID,
	Tail:   NoRoundID,
}

NoCompaction is the none sentinel Compaction, returned when no compaction exists.

Functions

func Final

func Final(e ChatEvent) bool

Final reports whether the event ends the current activity: true on a ChatEventRoundEnd, ChatEventToolResults or ChatEventCompacting with Final set, and on every ChatEventCriticalError. A chat uses it to switch its controls back to idle.

Types

type Chat

type Chat interface {
	// Update applies one event to the view. Events arrive one at a time, in
	// order, inside a Doors batch on ctx, so the view updates the page
	// directly from it.
	Update(ctx context.Context, e ChatEvent)
	gox.Comp
}

Chat is one rendered chat view, built by a ChatFactory for one thread link. The instance renders it as a component and then feeds it every change to the thread through Update. Implement it only to replace nekit.Chat with a chat UI of your own.

type ChatAsk

type ChatAsk struct {
	// Form is the question and its inputs, shown where the message box
	// normally is.
	Form gox.Elem
	// Button is the submit control, shown where the send button normally is;
	// its click handler calls Answer.Submit.
	Button gox.Elem
	// Cancel dismisses the ask and fails the tool call. The harness sets it,
	// overwriting whatever the handler returned, so leave it nil; a chat calls
	// it from its own dismiss control.
	Cancel func(context.Context)
	// Error is what the ask has to say about the answer as it stands, shown
	// next to the question; nil or an empty string shows nothing. It is a
	// readout, not a gate: whether the answer can be submitted stays the
	// ask's own business.
	Error doors.Beam[string]
}

ChatAsk is a question a tool puts to the user, returned by an Ask handler (neui.Module.Ask) and shown by the chat in place of its composer until the handler answers. nekit.AskOptions is a ready-made one.

type ChatEvent

type ChatEvent interface {
	// contains filtered or unexported methods
}

ChatEvent is one update to a chat's view. It is one of the ChatEvent* types in this package and nothing else.

type ChatEventAsk

type ChatEventAsk struct {
	// Ask is what to show: its Form, Button and Error.
	Ask ChatAsk
}

ChatEventAsk reports a tool asking the user for a decision. Show the ask until ChatEventAskDone; a new ask replaces one still showing.

type ChatEventAskDone

type ChatEventAskDone struct{}

ChatEventAskDone reports the pending ask resolved.

type ChatEventCompacting

type ChatEventCompacting struct {
	// Running is true while the compaction runs.
	Running bool
	// Usage is the estimated usage of the compacted context on the end of an
	// applied compaction, zero otherwise.
	Usage EventUsage
	// Final is true when the activity ends here: Stop canceled a compaction
	// the turn waited on after its round end or tool results were already
	// reported, so no other Final event follows; see Final.
	Final bool
	// CanCompact is ChatState.CanCompact after this event; always false while
	// Running.
	CanCompact bool
}

ChatEventCompacting reports a background compaction starting or ending. On the end of an applied one usage estimates the compacted context — the summary plus the rounds kept verbatim — and is zero otherwise.

type ChatEventCriticalError

type ChatEventCriticalError struct {
	// Err is the cause: a storage failure, ErrNotFound when the thread was
	// deleted through another instance's ThreadDelete, or ErrCompactionFailed
	// when compaction cannot make the conversation fit the model's context
	// window.
	Err error
}

ChatEventCriticalError reports the thread failing beyond recovery. The link is dropped with it, so this Chat receives no further events and every ChatThread call returns ErrUnlinked afterwards. The instance relinks to the thread, or to a fresh thread when that fails; a new Chat is built the next time the element renders, for example after ChatThread.Reload.

type ChatEventIndexed

type ChatEventIndexed struct {
	// Event is the provider event for one block of the streaming round's
	// response; apply it to Round.Response at Event.At().
	Event IndexedEvent
}

ChatEventIndexed carries one block-naming event of a streaming round.

type ChatEventInputPending

type ChatEventInputPending struct {
	// Pending is true once Send queued input behind the running activity
	// and false once it was consumed, unsent or dropped.
	Pending bool
}

ChatEventInputPending reports whether input is queued for the running activity.

type ChatEventName

type ChatEventName struct {
	// Name is the new name; empty leaves the thread unnamed.
	Name string
}

ChatEventName reports the thread's name changing.

type ChatEventRoundEnd

type ChatEventRoundEnd struct {
	// Round is the round that ended.
	Round RoundID
	// State is how it ended: RoundOk, RoundAbort, RoundRefuse or RoundError.
	State RoundState
	// Error is the ErrCode as a string when State is RoundError, empty
	// otherwise.
	Error string
	// Usage is what the round spent in total.
	Usage EventUsage
	// Final is true when the activity ends here; see Final.
	Final bool
	// CanCompact is ChatState.CanCompact after this event.
	CanCompact bool
}

ChatEventRoundEnd reports a round leaving the streaming state with the usage the round spent in total. Final is true when no agent-driven continuation follows; a round started by pending user input is a new activity, so it does not clear final.

type ChatEventRoundStart

type ChatEventRoundStart struct {
	// Round is the new round with its input and no response yet.
	Round Round
	// Truncate is NoRoundID for an ordinary round. After Rewind or Retry it
	// names the round the new one replaces: drop it and every round after it
	// from the view.
	Truncate RoundID
	// Usage is ChatState.Usage after this event: after a Rewind, the usage of
	// the history that remains; otherwise the value already reported.
	Usage EventUsage
	// CanCompact is ChatState.CanCompact after this event.
	CanCompact bool
}

ChatEventRoundStart reports a round entering the streaming state.

type ChatEventRoundUsage

type ChatEventRoundUsage struct {
	// Round is the streaming round.
	Round RoundID
	// Usage is the round's running total so far.
	Usage EventUsage
}

ChatEventRoundUsage reports the usage a streaming round has accumulated so far; every event carries the running total, not an increment.

type ChatEventTasks

type ChatEventTasks struct {
	// Tasks is the full current list, replacing the previous one.
	Tasks []Task
}

ChatEventTasks reports the thread's task list changing.

type ChatEventThreadCreated

type ChatEventThreadCreated struct{}

ChatEventThreadCreated reports that the thread's first round or first app event created it in storage. It fires once per thread, before the start event of the round that follows.

type ChatEventToolResults

type ChatEventToolResults struct {
	// Round is the round whose tool calls these answer.
	Round RoundID
	// Results holds one result per tool call, keyed by tool call id.
	Results map[string]ContentToolResult
	// Final is true when no continuation round follows, as after Stop.
	Final bool
}

ChatEventToolResults delivers the results of a tools round once every tool call in it has finished.

type ChatFactory

type ChatFactory interface {
	// Chat builds the view for the thread the instance has linked. It is
	// called each time the element from Instance.Render renders while a
	// thread is linked: on first render, whenever the instance switches
	// threads (ThreadOpen, ThreadNew, a ThreadDelete of its own thread,
	// Enable) and on ChatThread.Reload. A critical error alone builds no new
	// Chat. state is the full snapshot to render from; every later change
	// arrives through Chat.Update. thread is valid until the link drops, after
	// which its methods return ErrUnlinked.
	Chat(thread ChatThread, state ChatState) Chat
	// Placeholder stands in whenever there is no thread to render. A true
	// enabled means the session is enabled and a thread is on its way, so
	// the placeholder carries the loading state too; false means it is not
	// enabled.
	Placeholder(enabled doors.Beam[bool]) gox.Elem
}

ChatFactory builds the views Instance.Render shows. nekit.Chat is the ready-made implementation.

type ChatInput

type ChatInput struct {
	Input
	// Pending reports that the input has been submitted and waits for a round
	// to consume it; Unsend clears it again.
	Pending bool
}

ChatInput is the thread's staged input as a chat shows it.

type ChatState

type ChatState struct {
	// ID is the thread's id.
	ID ThreadID
	// Name is the chat title set by the agent; empty until named.
	Name string
	// Input is the staged draft and whether it is pending.
	Input ChatInput
	// Round is the round in progress, with its response or tool results so
	// far; nil when the thread is idle. Earlier rounds are read with
	// ChatThread.RoundBefore.
	Round *Round
	// Ask is the question showing to the user; nil when there is none.
	Ask *ChatAsk
	// Tasks is the background tasks still running.
	Tasks []Task
	// Usage is the token usage of the thread's context as it stands, what
	// compaction thresholds are measured against.
	Usage EventUsage
	// Compaction reports a compaction of the history running in the background.
	Compaction bool
	// CanCompact reports whether ChatThread.Compact would be accepted now: no
	// compaction is running, at least two rounds have completed since the last
	// compaction, and Usage has reached Config().CompactionAllowed times
	// Model().Context (not checked when Model().Context is 0). Later changes
	// arrive on ChatEventRoundStart, ChatEventRoundEnd and ChatEventCompacting.
	CanCompact bool
	// Meta is the meta that the Instance.ThreadOpen which switched to this
	// thread passed, nil for every other way a chat comes up. It is never
	// interpreted here: it reaches only the first chat initialised for that
	// open, so a later reload of the same thread sees nil and it does not
	// survive a page reload.
	Meta any
}

ChatState is the snapshot ChatFactory.Chat renders a thread from. Every later change arrives as a ChatEvent.

type ChatThread

type ChatThread interface {
	// Input stages input as the thread's draft without sending it, so a
	// reload or another tab on the thread picks it up as ChatState.Input.
	// ErrWrongState while an input is pending; ErrInputTooLarge when its text
	// is over the ThreadConfig.ReplayItemShare budget.
	Input(ctx context.Context, input Input) error
	// Send submits input. An idle thread starts a round with it at once
	// (ChatEventRoundStart); a busy one queues it as pending
	// (ChatEventInputPending) and runs it after the current activity.
	// ErrWrongState when an input is already pending or input is empty (an
	// idle thread with unanswered tool results accepts an empty Send and
	// resumes); ErrInputTooLarge when its text is over the
	// ThreadConfig.ReplayItemShare budget.
	Send(ctx context.Context, input Input) error
	// Stop aborts the running round, cancels the running tool calls with
	// ErrCanceledByUser, or cancels a compaction the turn waits on (results
	// already stashed stay for the next round), and drops any pending input;
	// the activity ends with a Final event. ErrWrongState when nothing is
	// running.
	Stop(ctx context.Context) error
	// Unsend withdraws the pending input back into the draft.
	// ErrWrongState when nothing is pending.
	Unsend(ctx context.Context) error
	// Retry runs the last round again when the thread is idle and that round
	// ended without an answer (error, abort, or input only); the new round's
	// ChatEventRoundStart names the replaced one in Truncate. ErrWrongState
	// otherwise, including after an ok or refused round.
	Retry(ctx context.Context) error
	// Compact starts a compaction of the history in the background. It
	// returns ErrWrongState when ChatState.CanCompact, as last reported, is
	// false; any other failure to start it is returned as is.
	Compact(ctx context.Context) error
	// Rewind deletes round and every round after it, then starts a new round
	// with input in its place; it works in any state and stops whatever is
	// running first. The ChatEventRoundStart it causes carries round in
	// Truncate. ErrInputTooLarge when the text is over the
	// ThreadConfig.ReplayItemShare budget. An empty input resumes from the
	// cut, and returns ErrWrongState with nothing changed when the cut would
	// leave nothing for the model to answer: no tool calls from the last
	// successful round before it and no records. A storage failure arrives as
	// ChatEventCriticalError instead of an error.
	Rewind(ctx context.Context, round RoundID, input Input) error
	// Reload re-renders the chat from scratch: the ChatFactory builds a new
	// Chat from a fresh ChatState and the current view is dropped.
	Reload(ctx context.Context)
	// RoundBefore returns at most limit stored rounds before start, oldest
	// first; NoRoundID returns the latest ones. Use it to page history in
	// as the user scrolls up. Results and record Data come back empty, as
	// MessageStorage.RoundBefore documents.
	RoundBefore(ctx context.Context, start RoundID, limit int) ([]Round, error)
	// RoundAfter returns at most limit stored rounds after start, oldest
	// first; NoRoundID returns the first ones. Results and record Data come
	// back empty.
	RoundAfter(ctx context.Context, start RoundID, limit int) ([]Round, error)
	// Model is the provider's model of the Enable configuration this handle
	// was linked with; it keeps returning it after the link drops.
	Model() Model
	// Config is the thread configuration of the Enable configuration this
	// handle was linked with; it keeps returning it after the link drops.
	Config() ThreadConfig
	// FS is the thread's file system, the workspace plus the uploads dirs, as
	// the agent's tools see it; use it to list or attach files from the chat.
	FS() FS
}

ChatThread is the live handle a Chat drives the thread through: the commands a user can issue and the reads a chat renders from. Once the thread has dropped this instance's link, every method that returns an error returns ErrUnlinked.

Call the commands with the ctx of the Doors event that triggered them, such as a click handler's: each blocks until the thread accepts or refuses it, and the ChatEvent it causes reaches Chat.Update before that event settles. A refused command changes nothing, except that a Send refused for empty input still replaces the staged draft with it.

type Compaction

type Compaction struct {
	Text   string  `json:"text"`   // the summary that replaces rounds before Target
	Target RoundID `json:"target"` // first kept round
	Tail   RoundID `json:"tail"`   // last completed round when it was made
	// Output is the output token count of the compaction response — the
	// summary's own size.
	Output int `json:"output"`
	// Base is the context total of the round replayed just before Target,
	// what the summarized part of the conversation cost.
	Base int `json:"base"`
}

Compaction is an additive summary row: Target is the round the summary attaches to on replay (the first kept round), and Tail is the last completed round when the compaction was made. ThreadCut at or before Tail removes the compaction, so a rewind there replays the originals.

Until a round runs on the compacted context, its reported usage is an estimate, a lower bound.

func (Compaction) IsValid

func (c Compaction) IsValid() bool

IsValid reports whether the compaction is set: both Target and Tail differ from NoRoundID.

type Container

type Container interface {
	// Content returns the block the output becomes.
	Content() UserContent
	// ContentType names the kind of block, such as "image" or "document".
	ContentType() string
}

Container is a tool output that becomes one block of a result, the block Content returns; ContentType names it for the tool's description.

type Content

type Content interface {
	json.Marshaler
	// contains filtered or unexported methods
}

Content is one block of a message: ContentText, ContentImage, ContentDocument, ContentToolUse, ContentToolResult, ContentReasoning, or ContentOpaque for what only one provider understands. Not every adapter can carry every block; see UserContent.

Meta on ContentText, ContentToolUse and ContentReasoning is the issuing adapter's own data, handed back to it unchanged on replay; folding a stream, a non-empty Meta replaces the one before it. On user-authored blocks (ContentText, ContentImage, ContentDocument) Meta is the caller's data, which no adapter reads or sends.

An adapter whose wire takes one string for several blocks joins them with a blank line, so lists, headings and code fences keep their framing.

type ContentDocument

type ContentDocument struct {
	Data []byte          `json:"data"`           // raw bytes; base64 in JSON
	Mime string          `json:"mimeType"`       // a DocumentMime value
	Name string          `json:"name"`           // file name or title, sent where the wire has one; may be empty
	Meta json.RawMessage `json:"meta,omitempty"` // caller data; adapters ignore it
}

ContentDocument is a file attachment, such as a PDF.

func (ContentDocument) MarshalJSON

func (c ContentDocument) MarshalJSON() ([]byte, error)

MarshalJSON encodes c with its "type" tag.

type ContentImage

type ContentImage struct {
	Data []byte          `json:"data"`           // raw bytes; base64 in JSON
	Mime string          `json:"mimeType"`       // an ImageMime value
	Meta json.RawMessage `json:"meta,omitempty"` // caller data; adapters ignore it
}

ContentImage is an image attachment.

func (ContentImage) MarshalJSON

func (c ContentImage) MarshalJSON() ([]byte, error)

MarshalJSON encodes c with its "type" tag.

type ContentOpaque

type ContentOpaque struct {
	Model  string          `json:"model"`  // configured model, as on ContentReasoning
	Kind   string          `json:"kind"`   // issuing adapter's name for the payload
	Data   json.RawMessage `json:"data"`   // bytes as the API sent them, which it may have signed
	Deltas []string        `json:"deltas"` // streamed fragments of a field inside Data, put back by the adapter
}

ContentOpaque carries a payload this protocol has no type for, such as the output of a tool the provider ran itself. It is meant for the adapter that issued it, and no field records the provider, so each adapter replays only opaque blocks its provider issued, judged by Kind and the shape of Data, and drops the rest; nothing upstream strips them. Folding a stream, a non-empty Kind or Data replaces the one before it and each Delta appends to Deltas in arrival order.

func (ContentOpaque) MarshalJSON

func (c ContentOpaque) MarshalJSON() ([]byte, error)

MarshalJSON encodes c with its "type" tag.

type ContentReasoning

type ContentReasoning struct {
	// Model is the model the provider was configured with, as EventStart.Model
	// reports. It is informational: adapters judge a stored block by its shape,
	// not by comparing this with the model of a later request.
	Model    string          `json:"model"`
	Summary  Indexed[string] `json:"summary"`        // paraphrase written by the service
	Thoughts Indexed[string] `json:"thoughts"`       // thinking as the model generated it
	Meta     json.RawMessage `json:"meta,omitempty"` // signature or sealed payload, replayed as is
}

ContentReasoning is the model's thinking, in whichever forms the provider hands over. Summary and Thoughts are keyed by the Part of EventSummary and EventThinking; read them in order with Ordered. A provider that does not index parts fills key 0. Any of Summary, Thoughts and Meta may be empty.

Where a provider signs or seals reasoning, Meta is what is replayed, byte for byte, and the text never is; such a block without Meta is not replayed. Whether a stored block is replayed at all is the adapter's decision. A sealed payload fails at any other provider and nothing here records the issuer, so each adapter replays only blocks its provider issued, judged by their shape, and drops the rest; nothing upstream strips them.

func (ContentReasoning) MarshalJSON

func (c ContentReasoning) MarshalJSON() ([]byte, error)

MarshalJSON encodes c with its "type" tag.

type ContentText

type ContentText struct {
	// Text is the block's text.
	Text string `json:"text"`
	// Meta is adapter data on model output, caller data on user input.
	Meta json.RawMessage `json:"meta,omitempty"`
}

ContentText is a plain text block.

func (ContentText) MarshalJSON

func (c ContentText) MarshalJSON() ([]byte, error)

MarshalJSON encodes c with its "type" tag.

type ContentToolResult

type ContentToolResult struct {
	ID      string       `json:"toolUseId"` // ContentToolUse.ID this answers
	Content UserContents `json:"content"`   // blocks the call produced, in order
	Error   ToolError    `json:"error"`     // ToolOk on success
}

ContentToolResult reports the outcome of the ContentToolUse with the same ID. NewContentToolResult builds one from a tool's output and error.

Its position among the blocks of a message is kept only as far as the wire allows. What the model reads is Content, plus whatever failure marker the adapter sends for an Error other than ToolOk.

func NewContentToolResult

func NewContentToolResult(id string, content UserContents, err error) ContentToolResult

NewContentToolResult builds the result answering call id. With a nil err it carries content as ToolOk. Otherwise content is dropped and the result is err.Error() as one text block, followed by the Container, else the MultiContainer, that err is or wraps, as NewToolContents encodes it; content that fails to encode is left out. It is classified ToolErrJSON when err wraps a DiscardedArgumentsError and ToolErrRuntime for any other error.

func (ContentToolResult) MarshalJSON

func (c ContentToolResult) MarshalJSON() ([]byte, error)

MarshalJSON encodes c with its "type" tag.

func (ContentToolResult) Refused

Refused returns c with its content replaced by a note that the output was omitted because the provider refused it, keeping ID and Error so the call stays answered.

type ContentToolUse

type ContentToolUse struct {
	ID    string          `json:"id"`              // provider's call id, matched by ContentToolResult.ID
	Name  string          `json:"name"`            // name of the Tool called
	Input json.RawMessage `json:"input,omitempty"` // omitempty keeps nil through a round trip
	Meta  json.RawMessage `json:"meta,omitempty"`  // issuing adapter's data
}

ContentToolUse is a tool call the model asked for. Every call replayed to a provider must be answered by a ContentToolResult with the same ID; LostResult stands in for one that is missing.

Input is the arguments as valid JSON; nil means the provider sent none, and an adapter writes {} where its wire requires an object. Arguments that never formed valid JSON are not stored: Input holds DiscardedArguments instead, and the result answering the call must carry ToolErrJSON. An adapter encodes such a call without reading Input, and refuses with CodeInvalid a discarded call whose result lacks ToolErrJSON.

func (ContentToolUse) LostResult

func (c ContentToolUse) LostResult() ContentToolResult

LostResult returns a ToolErrRuntime result answering c, telling the model the result was lost or the call never ran. Use it to keep a call answered when its real result is missing.

func (ContentToolUse) MarshalJSON

func (c ContentToolUse) MarshalJSON() ([]byte, error)

MarshalJSON encodes c with its "type" tag, writing DiscardedArguments as no input.

type Contents

type Contents []Content

Contents is a list of content blocks that decodes from JSON by each block's "type" tag, so a stored message reads back as the concrete Content types.

func (*Contents) UnmarshalJSON

func (cs *Contents) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes a JSON array of tagged blocks; a block with a missing or unknown type is an error.

type Cursor

type Cursor struct {
	Created time.Time `json:"created"` // Hit.Created
	Thread  ThreadID  `json:"thread"`  // Hit.Thread
	Round   RoundID   `json:"round"`   // Hit.Round
}

Cursor positions a RoundSearch page. It names one round by the whole sort key RoundSearch orders by, so a page resumes exactly where the last ended even when several rounds share a creation time. Build it from the last Hit of a page.

type DiscardedArgumentsError

type DiscardedArgumentsError struct {
	// Raw is the invalid argument text, if the caller still holds it; empty
	// asks the model to reissue the call with nothing quoted back.
	Raw string
}

DiscardedArgumentsError reports a tool call whose arguments never formed valid JSON, so the call was not made and the arguments were not stored. Answer the call with it through NewContentToolResult, which classifies it as ToolErrJSON, the classification ContentToolUse requires of the result answering a discarded call.

func (DiscardedArgumentsError) Error

func (e DiscardedArgumentsError) Error() string

Error tells the model to reissue the call, quoting at most the first 256 runes of Raw, since the result is resent with every later request.

type Document

type Document struct {
	// Data is the raw file bytes.
	Data []byte `json:"data"`
	// Mime is the document type; check it with IsValid before returning.
	Mime DocumentMime `json:"mime"`
}

Document is a document a tool returns: raw bytes and their DocumentMime. Content turns it into a ContentDocument with the mime as a plain string and no Name. Nothing checks Mime; check it with IsValid before returning.

func (Document) Content

func (d Document) Content() UserContent

Content returns d as a ContentDocument.

func (Document) ContentType

func (d Document) ContentType() string

ContentType returns "document".

type DocumentMime

type DocumentMime string

DocumentMime is a document type at least one provider accepts. The GPT adapter takes them all. The Claude adapter, in a user message or a tool result, sends DocumentPDF as a PDF, sends the text types (DocumentText, DocumentMarkdown, DocumentCSV, DocumentHTML, DocumentXML, DocumentJSON, DocumentYAML, DocumentRTF) as plain text, and leaves a note in place of the binary Office types and of text that is not UTF-8. The DeepSeek adapter takes no documents and leaves a note in place of each.

const (
	DocumentPDF      DocumentMime = "application/pdf"
	DocumentText     DocumentMime = "text/plain"
	DocumentJSON     DocumentMime = "application/json"
	DocumentMarkdown DocumentMime = "text/markdown"
	DocumentCSV      DocumentMime = "text/csv"
	DocumentHTML     DocumentMime = "text/html"
	DocumentXML      DocumentMime = "text/xml"
	DocumentYAML     DocumentMime = "application/yaml"
	DocumentRTF      DocumentMime = "application/rtf"
	DocumentDOC      DocumentMime = "application/msword"
	DocumentXLS      DocumentMime = "application/vnd.ms-excel"
	DocumentDOCX     DocumentMime = "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
	DocumentXLSX     DocumentMime = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
	DocumentPPTX     DocumentMime = "application/vnd.openxmlformats-officedocument.presentationml.presentation"
)

The accepted document types. Only DocumentPDF and the text types reach both the Claude and GPT adapters.

func (DocumentMime) IsValid

func (m DocumentMime) IsValid() bool

IsValid reports whether m is one of the accepted document types.

type ErrCode

type ErrCode string

ErrCode says why a turn is unusable and what the caller does about it. The constants are grouped by remedy: change the input, adjust the request and resend, retry unchanged, give up, decide yourself. CodeCapped, CodeContextLength and CodeTooLarge stay apart because their fixes differ: raise the cap, compact the conversation, or send fewer bytes.

const (
	CodeRefused       ErrCode = "refused"        // the model or the provider would not produce this reply; change the input
	CodeCapped        ErrCode = "capped"         // output was cut at the provider's configured response cap; raise it or continue
	CodeContextLength ErrCode = "context_length" // the conversation does not fit the model; compact it and retry
	CodeTooLarge      ErrCode = "too_large"      // the request is too large: over Model.RequestBytes, or refused by the service for its size; shed media and retry
	CodeNetwork       ErrCode = "network"        // connection, stream or deadline failed; retry as sent
	CodeBusy          ErrCode = "busy"           // rate limited or out of capacity; back off and retry
	CodeInvalid       ErrCode = "invalid"        // the request was refused as written; fix the request
	CodeAccess        ErrCode = "access"         // credentials, permission or balance; no request fixes it
	CodeUnknown       ErrCode = "unknown"        // nothing was recognized; Err carries it and the caller decides
)

type Event

type Event interface {
	// contains filtered or unexported methods
}

Event is one step of a streamed reply, as Provider.Stream sends it. Folding the whole sequence reconstructs the Message the turn produced.

stream    := EventErr | EventStart body (EventOk | EventErr)?
body      := any interleaving of block* and EventUsage*
block     := text | tool | reasoning | opaque
text      := (EventText | EventMeta)+ EventClose?
tool      := (EventTool | EventMeta)+ EventClose?
reasoning := (EventThinking | EventSummary | EventMeta)+ EventClose?
opaque    := EventOpaque+ EventClose?

A block is the subsequence of events sharing one Index, its position in the reconstructed Message.Content, counted by the adapter. Blocks interleave and several may be open at once, so a consumer keeps one block per Index. The first event at an Index names the block's kind and is never an EventMeta; an adapter with nothing readable yet sends the zero value of that kind's event. Repeated events at an Index merge field by field: content appends, identity and adapter data replace when not empty. Adapters emit as the wire delivers and hold nothing back; keepalives are never forwarded.

A block is complete at its EventClose, or at the terminal event. A stream that closes with neither, including one ended by cancelling ctx, is a cut-off reply and the consumer discards the turn.

type EventClose

type EventClose struct {
	Index int // block position in Message.Content
}

EventClose reports the block at Index complete before the turn ends; for a tool call it is when Args become parseable. Adapters emit it only where the wire frames the end of that specific block, so some wires never emit it. Its absence means nothing: a block is complete once it closed or the turn ended.

func (EventClose) At

func (e EventClose) At() int

At returns Index.

func (EventClose) Offset

func (e EventClose) Offset(n int) IndexedEvent

Offset returns a copy with Index shifted by n.

type EventErr

type EventErr struct {
	Code ErrCode // what to do about it
	Err  error   // the failure as it happened, for logs and errors.Is; always set
}

EventErr ends the turn without a reply worth keeping: store no Message and act on Code. Content that already streamed was real, but nothing more arrives. A provider value the adapter does not recognize ends here as CodeUnknown with the raw value in Err, never as a quiet EventOk. Cancelling ctx is not reported this way; the channel just closes. See Provider.Stream.

type EventMeta

type EventMeta struct {
	Index int             // block position in Message.Content
	Data  json.RawMessage // replaces, when not empty
}

EventMeta attaches adapter data to the block at Index, for any kind but opaque. It never opens a block. Data arrives whole and nothing but the adapter that emitted it reads it, handed back on a later turn; for signed or sealed reasoning it is the replay unit (see ContentReasoning). A reasoning block holding only a meta, opened by an empty EventThinking, is sealed thinking with nothing shown.

func (EventMeta) At

func (e EventMeta) At() int

At returns Index.

func (EventMeta) Offset

func (e EventMeta) Offset(n int) IndexedEvent

Offset returns a copy with Index shifted by n.

type EventOk

type EventOk struct {
	Code OkCode // how the reply ended
}

EventOk ends the turn with a reply worth keeping: fold the blocks into a Message and store it. Nothing follows it, and it completes every block still open.

type EventOpaque

type EventOpaque struct {
	Index int             // block position in Message.Content
	Kind  string          // replaces, when not empty
	Data  json.RawMessage // replaces, when not empty
	Delta string          // appends as one entry of Deltas
}

EventOpaque fills the opaque block at Index: a payload only the emitting adapter understands, handed back to it on a later turn. See ContentOpaque. Kind is the adapter's name for the payload. Delta is a streamed fragment of a field inside Data; each becomes one entry of ContentOpaque.Deltas and the adapter reassembles them on the way back.

func (EventOpaque) At

func (e EventOpaque) At() int

At returns Index.

func (EventOpaque) Offset

func (e EventOpaque) Offset(n int) IndexedEvent

Offset returns a copy with Index shifted by n.

type EventStart

type EventStart struct {
	// ID is the provider's id for the response; empty where it sends none.
	ID string
	// Model is the model the provider is configured with and sent, not the
	// name the service reports serving. It is informational and no adapter
	// replays by it. See ContentReasoning.Model.
	Model string
}

EventStart opens the turn and comes before any block, usage or EventOk event.

type EventSummary

type EventSummary struct {
	Index int    // block position in Message.Content
	Part  int    // run counter, as in EventThinking.Part
	Text  string // appends to the summary at Part
}

EventSummary fills the summary at Part of the reasoning block at Index, by the rule EventThinking states for Part. A summary is a paraphrase a service wrote of thinking it did not show, so a consumer must not render it as thinking.

func (EventSummary) At

func (e EventSummary) At() int

At returns Index.

func (EventSummary) Offset

func (e EventSummary) Offset(n int) IndexedEvent

Offset returns a copy with Index shifted by n.

type EventText

type EventText struct {
	Index int    // block position in Message.Content
	Text  string // appends
}

EventText fills the text block at Index.

func (EventText) At

func (e EventText) At() int

At returns Index.

func (EventText) Offset

func (e EventText) Offset(n int) IndexedEvent

Offset returns a copy with Index shifted by n.

type EventThinking

type EventThinking struct {
	Index int // block position in Message.Content
	// Part is the provider's own counter for the thought run this fragment
	// belongs to, 0 where it has none. Runs may interleave: fold by sorting
	// on Part, read nothing into gaps, and never join two parts with a
	// separator the model did not generate.
	Part int
	Text string // appends to the thought at Part
}

EventThinking fills the thought at Part of the reasoning block at Index.

func (EventThinking) At

func (e EventThinking) At() int

At returns Index.

func (EventThinking) Offset

func (e EventThinking) Offset(n int) IndexedEvent

Offset returns a copy with Index shifted by n.

type EventTool

type EventTool struct {
	Index int    // block position in Message.Content
	ID    string // replaces, when not empty
	Name  string // appends
	Args  string // appends
}

EventTool fills the tool call at Index. Name and Args may arrive fragmented and in either order. Args are parseable JSON only once the block closes or the turn ends, and may still be invalid if a token limit cut them.

ID pairs the call with its later ContentToolResult. Where the provider sends none (or, on some adapters, a duplicate), the adapter mints one from the provider's response id and the block position; without a response id the minted id is unique only within the turn. A later EventTool with a non-empty ID replaces it.

func (EventTool) At

func (e EventTool) At() int

At returns Index.

func (EventTool) Offset

func (e EventTool) Offset(n int) IndexedEvent

Offset returns a copy with Index shifted by n.

type EventUsage

type EventUsage struct {
	Input      int // prompt tokens processed fresh
	Output     int // generated tokens the model showed
	Reasoning  int // tokens spent thinking
	CacheRead  int // prompt tokens served from cache
	CacheWrite int // prompt tokens written into cache
}

EventUsage reports what the turn has cost so far. It may arrive several times or never, and each one carries the full running total rather than an increment: keep the last one seen, even when a total goes down as a provider corrects itself. The counters are disjoint, so the prompt was Input+CacheRead+CacheWrite tokens and the model generated Output+Reasoning. A zero is either zero or not reported.

func (EventUsage) Total

func (u EventUsage) Total() int

Total returns every counter summed: the context the turn occupied, prompt plus generated tokens.

type FS

type FS interface {
	// ReadRange streams [off, off+n) of the named file; n < 0 means to EOF.
	// Reading past EOF truncates silently; a negative off is refused and
	// off >= size returns ErrOutOfRange, except off 0 with negative n on
	// an empty file, which reads empty.
	ReadRange(ctx context.Context, name string, off, n int64) (io.ReadCloser, error)
	// ReadAll streams the whole file, wherever it lives.
	ReadAll(ctx context.Context, name string) (io.ReadCloser, error)
	// LocalPath returns the absolute local path of a workspace file, for
	// libraries that need io.ReaderAt or a real path. A virtual path is
	// ErrVirtual (copy it into the workspace first), and a missing one is
	// ErrNotFound.
	LocalPath(ctx context.Context, name string) (string, error)
	// TempDir returns the absolute local path of a scratch directory
	// reserved for libraries that do their own filesystem work and cannot
	// be routed through this interface, such as unpacking an archive,
	// creating it on first call. It is not workspace content: it stays out
	// of ReadDir and out of the FilesConfig workspace limits, every other
	// method refuses paths inside it with ErrReserved, and it is wiped once
	// a round's tool calls are done, so work outliving the round copies
	// what it needs into the workspace first.
	TempDir() (string, error)
	// Create opens a local file for writing, truncating if it exists,
	// creating parent directories as needed. Returns ErrReadOnly under
	// the uploads dirs, and ErrQuota when the FilesConfig workspace limits
	// are reached — at open or mid-write; Append and local Copy share both
	// refusals.
	Create(name string) (io.WriteCloser, error)
	// Append is Create without truncation, positioned at EOF.
	Append(name string) (io.WriteCloser, error)
	// Copy copies src to dst host-side (no caller byte shuttling).
	// src may be virtual; dst must be local-writable or
	// agent_uploads/<name>, which uploads to file storage instead of
	// writing locally — a name already taken is ErrExists. This is the
	// blessed "edit an upload" path.
	Copy(ctx context.Context, src, dst string) error
	// Rename moves a local file or directory. Either side under an
	// uploads dir returns ErrReadOnly.
	Rename(oldname, newname string) error
	// Remove deletes a local file or directory recursively, or an
	// agent_uploads/ file from file storage, freeing its name. user_uploads/
	// and the agent_uploads/ dir itself return ErrReadOnly, and a TempDir path
	// ErrReserved. A missing name is not an error.
	Remove(ctx context.Context, name string) error
	// Stat reports a name's entry from the merged view. Virtual entries carry
	// File.MIME, local files an extension-derived one; "" when unknown. A
	// missing name or a draft upload is ErrNotFound.
	Stat(ctx context.Context, name string) (FSEntry, error)
	// ReadDir lists a directory of the merged view, "." for root, which also
	// lists both uploads dirs. Uploads entries show final (deduplicated) names
	// and leave out drafts.
	ReadDir(ctx context.Context, name string) ([]FSEntry, error)
	// UserUpload streams r into file storage as a user_uploads/ draft, named by
	// the base name of the client-provided name ("unnamed" when that is empty,
	// "/", "." or ".."), with a "(N)" suffix before the extension when the name
	// is taken, and its MIME sniffed from the first 512 bytes. It returns the
	// draft's entry; the draft stays hidden from Stat, ReadDir and reads until it is
	// committed with UploadStorage.FileCommit.
	UserUpload(ctx context.Context, name string, r io.Reader) (FSEntry, error)
	// UploadStat returns an upload's entry whether or not it is still a
	// draft; Stat hides drafts, this is for whoever manages them. The name
	// is the user_uploads/ or agent_uploads/ path as listed.
	UploadStat(ctx context.Context, name string) (FSEntry, error)
	// DeleteUpload removes an upload from file storage; the name is the
	// user_uploads/ or agent_uploads/ path as listed. Missing is not an
	// error (ensure-absent).
	DeleteUpload(ctx context.Context, name string) error
}

FS is the filesystem a thread's tools see: the workspace merged with the thread's stored files, which appear under the virtual user_uploads/ and agent_uploads/ dirs and are streamed straight from file storage on read; nothing materializes locally. user_uploads/ is read-only; agent_uploads/ takes new files only through Copy and loses them only through Remove or DeleteUpload. Stat, ReadDir and every read leave out drafts; UploadStat reports them.

type FSEntry

type FSEntry struct {
	Name    string    // workspace-relative path
	Size    int64     // bytes; for directories whatever the OS reports (0 for the virtual dirs)
	Dir     bool      // a directory rather than a file
	ModTime time.Time // last write for local files, upload time for virtual ones
	MIME    string    // File.MIME for virtual entries, extension-derived for local files; "" when unknown or a directory
	Virtual bool      // served from file storage, not workspace disk: reads download, LocalPath refuses
}

FSEntry is one name in the merged filesystem view.

type File

type File struct {
	ThreadID  ThreadID  `json:"thread_id"`  // thread the file belongs to
	Name      string    `json:"name"`       // key within the thread and origin
	MIME      string    `json:"mime"`       // as the caller supplied it to FilePut
	Origin    Origin    `json:"origin"`     // which side stored it
	Size      int64     `json:"size"`       // bytes, measured by storage
	CreatedAt time.Time `json:"created_at"` // when FilePut committed it
	// Draft marks a blob stored ahead of the message that will carry it. A
	// draft is not part of the conversation: UploadStorage lists it like any
	// file, but FS leaves it out of Stat, ReadDir and every read. It stays a
	// draft until FileCommit clears it or it is deleted.
	Draft bool `json:"draft"`
}

File is the stored record: what the caller supplied plus what storage measured on the way in.

type FilesConfig

type FilesConfig struct {
	// TempDir is where each session creates its own temporary directory,
	// which holds the thread workspaces and, unless the session has its own
	// file storage, the uploads. It is read when Enable first runs for the
	// session. Default os.TempDir().
	TempDir string
	// MaxFiles is how many files the workspace may hold; the write that would
	// add one past it is refused with ErrQuota. Uploads live in file storage
	// and are not counted. Default 10000.
	MaxFiles int
	// MaxBytes is how many bytes the workspace may hold; a write crossing it is
	// refused with ErrQuota, at open or mid-write. Default 1 GiB.
	MaxBytes int64
	// ReadLimit is the byte budget of one file read: lines are returned until
	// their lengths add up to it, the line that crosses it included, and the
	// read then reports where to continue from. Negative returns every
	// requested line. Default 50 KiB.
	ReadLimit int
	// EditLimit is how many bytes of a file an edit may read into memory to
	// rewrite it; a bigger file is refused rather than loaded, since an edit
	// has to hold the whole file to replace text inside it. It bounds the
	// file, not the replacement, which the model's own output cap already
	// bounds. Default 10 MiB.
	EditLimit int
	// ImageFileLimit is how many bytes an image file may have to be handed to
	// the model; a bigger one is refused with ErrTooLarge rather than read as
	// an image. Default 20 MiB.
	ImageFileLimit int
	// DocumentLimit is how many bytes a document may have to be handed to the
	// model; a bigger one is refused with ErrTooLarge. Default 32 MiB.
	DocumentLimit int
	// UnzipLimit is the total unpacked size one archive may produce;
	// extraction stops and reports the limit once the entries written pass it,
	// so an archive cannot fill the workspace by what it decompresses to.
	// Default 512 MiB.
	UnzipLimit int64
	// UnzipFiles is how many entries one extraction writes; at the next entry
	// it stops with an error, and the entries already written stay in the
	// workspace. Default 10000.
	UnzipFiles int
}

FilesConfig bounds the workspace filesystem and the files module: what the workspace may hold on disk, how much of a file reaches the model, and how far an archive may unpack. A zero field takes its default and a negative field turns that limit off.

type Hit

type Hit struct {
	Thread  ThreadID  `json:"thread"`  // thread holding the round
	Round   RoundID   `json:"round"`   // the matched round
	Created time.Time `json:"created"` // the round's Created
	Snippet string    `json:"snippet"` // matched text with some context
}

Hit is one round matched by RoundSearch. Snippet is a bounded run of the matched text taken verbatim from the round, cut at rune boundaries and containing the match.

type Image

type Image struct {
	// Data is the raw image bytes.
	Data []byte `json:"data"`
	// Mime is the image type; check it with IsValid before returning.
	Mime ImageMime `json:"mime"`
}

Image is an image a tool returns: raw bytes and their ImageMime. Content turns it into a ContentImage with the mime as a plain string. Nothing checks Mime; check it with IsValid before returning.

func (Image) Content

func (i Image) Content() UserContent

Content returns i as a ContentImage.

func (Image) ContentType

func (i Image) ContentType() string

ContentType returns "image".

type ImageMime

type ImageMime string

ImageMime is an image type the Claude and GPT adapters both accept. The DeepSeek adapter accepts them on Flash models only and leaves a note in place of each image elsewhere.

const (
	ImagePNG  ImageMime = "image/png"
	ImageJPEG ImageMime = "image/jpeg"
	ImageWEBP ImageMime = "image/webp"
	ImageGIF  ImageMime = "image/gif" // non-animated only: OpenAI rejects animation, Anthropic keeps frame 1
)

The accepted image types.

func (ImageMime) IsValid

func (m ImageMime) IsValid() bool

IsValid reports whether m is one of the accepted image types.

type Indexed

type Indexed[T any] map[int]T

Indexed holds values the stream fills by index, so entries arrive in any order and the set can be sparse. Ordered reads them back in index order.

func (Indexed[T]) Iter

func (i Indexed[T]) Iter() iter.Seq[T]

Iter yields the values in index order.

func (Indexed[T]) Ordered

func (i Indexed[T]) Ordered() []T

Ordered returns the values in index order; nil when empty.

type IndexedEvent

type IndexedEvent interface {
	Event
	// At returns the block Index.
	At() int
	// Offset returns a copy with Index shifted by the given amount, for
	// appending a stream after content that already holds that many blocks.
	Offset(int) IndexedEvent
}

IndexedEvent is implemented by the events that belong to a block. Route a stream by block through it instead of switching over the seven types that carry an Index.

type Input

type Input struct {
	Attachments []string `json:"attachments"` // e.g. "user_uploads/report.pdf"
	Text        string   `json:"text"`        // "" for attachments only
}

Input is the user-typed text plus attachment filenames given as thread-relative paths.

func (Input) Content

func (in Input) Content() []Content

Content renders the input as protocol content: a file link per attachment followed by the text; nil when the input is empty.

func (Input) Len

func (in Input) Len() int

Len returns the number of content parts the input may produce: one for the text plus one per attachment.

type Instance

type Instance interface {
	// ID is the instance's immutable id, the one its own entry in Chats
	// carries.
	ID() string
	// State is this instance's own chat.
	State() doors.Beam[InstanceState]
	// Chats is every chat open in the session, keyed by thread. A tab with no
	// thread yet has no key, so it is absent. A thread is open in at most one
	// tab: when a tab opens a thread another tab has open, that other tab
	// moves to a fresh thread, so each entry is the one tab that has it.
	Chats() doors.Beam[map[ThreadID]InstanceChat]
	// Location is the session's time zone, a fixed UTC offset read from the
	// browser's clock and kept for the session once one reading succeeds.
	// Until then it is time.Local, the server's zone. When an instance's own
	// reading succeeds, it is stored before that instance's Status leaves
	// InstanceLoading.
	Location() *time.Location
	// ThreadOpen switches the instance to the thread, replacing whatever it
	// had open. A thread that is not in storage, a New one included, returns
	// the storage's ErrNotFound. meta reaches the chat that initialises for
	// this open as ChatState.Meta and is consumed there; pass nil when there
	// is nothing to hand over.
	ThreadOpen(ctx context.Context, id ThreadID, meta any) error
	// ThreadNew switches the instance to a fresh, empty thread, replacing
	// whatever it had open. The thread is not stored until its first round or
	// app event, so until then InstanceThread.New is true and ThreadList does
	// not list it.
	ThreadNew(ctx context.Context) error
	// ThreadRename sets the thread's name, replacing whatever it was named
	// before. The name is trimmed; one that is then empty leaves the thread
	// unnamed, and one that holds line breaks, control or format characters is
	// refused. A name over 80 runes is cut to its first 80 and trimmed again.
	// A thread that is not in storage, a New one included, returns
	// ErrNotFound. The instance stays on
	// the thread it has open, whichever thread was renamed, and a chat that
	// has the renamed thread open sees the new name at once.
	ThreadRename(ctx context.Context, id ThreadID, name string) error
	// ThreadClone copies the thread, with its name, all of its stored history
	// and its committed files of both origins, into a new one and returns the
	// new thread's id. A source that is not in storage returns the storage's
	// ErrNotFound; when copying the files fails, the clone is deleted and the
	// error returned. The copy is listed
	// and ready to ThreadOpen right away, and the instance stays on what it
	// had open.
	ThreadClone(ctx context.Context, id ThreadID) (ThreadID, error)
	// ThreadDelete removes the thread and everything in it; a thread that is
	// not there is not an error. An instance holding the deleted thread loses
	// it: this one moves to a fresh chat the way ThreadNew does, while any
	// other is dropped with a critical error and lands on a fresh chat of its
	// own.
	ThreadDelete(ctx context.Context, id ThreadID) error
	// ThreadGet reads the thread's stored metadata: name, dates and write
	// serial. A thread that is not in storage returns the storage's
	// ErrNotFound.
	ThreadGet(ctx context.Context, id ThreadID) (Thread, error)
	// ThreadList returns threads updated in [from, to), at most limit of them.
	// A zero from or to drops that bound; limit <= 0 means no cap. A non-empty
	// name keeps only threads whose name contains it, case-insensitively.
	// They come most recently updated first, ties broken by id descending, or
	// the reverse when asc is set, and limit keeps the first limit in that
	// order.
	ThreadList(ctx context.Context, from, to time.Time, asc bool, limit int, name string) ([]Thread, error)
	// RoundSearch returns rounds whose input text or response text contains
	// query, case-insensitively, at most limit of them; limit <= 0 means no
	// cap. Reasoning, tool calls, tool results, attachments and errors are not
	// searched, and an empty query matches nothing. A zero thread searches
	// every chat; a non-zero thread restricts the search to it, or, with
	// exclude set, to every chat but it. Hits are ordered by (created, thread,
	// round), ascending when asc and descending otherwise. A nil from starts
	// at the first hit in that order and inclusive is ignored; otherwise the
	// result starts at the round from names when inclusive, or just past it
	// when not.
	RoundSearch(ctx context.Context, thread ThreadID, exclude bool, query string, from *Cursor, inclusive bool, asc bool, limit int) ([]Hit, error)
	// Emit sends an app event to the thread this instance has open. The agent
	// reads it as an <app_event name="…"> element carrying attrs, with data as
	// its body: a string is escaped text, json.RawMessage is passed as is,
	// anything else is encoded as JSON. The event is stored in the thread,
	// creating a New thread in storage. An idle agent starts a turn at once; a
	// busy one reads it in its next turn, or a later one while the records
	// ahead of it fill a turn's ThreadConfig.ReplayItemShare budget. Returns
	// ErrUnlinked when the instance has no thread open or switched threads
	// before the event landed; a storage failure is returned and also ends the
	// link with ChatEventCriticalError.
	Emit(ctx context.Context, name string, attrs map[string]string, data any) error
	// Render returns the element that shows this instance's chat. It renders
	// factory.Placeholder while there is no thread to show and factory.Chat
	// once there is, and swaps the view in place whenever the instance
	// switches threads. Render it once per page; nekit.Chat does this for
	// you.
	Render(factory ChatFactory) gox.Elem
}

Instance is the neui side of one Doors page instance, the browser tab: which thread it has open, the session's other chats, thread storage, and the element that renders the chat. Get it with neui.Instance(ctx) from any ctx of that page. Every method that returns an error returns ErrDisabled while neui is not enabled for the session and context.Canceled once ctx is done. ThreadOpen, ThreadNew, ThreadDelete and Emit return ErrUnlinked until the instance has synced with its tab, shortly after the page loads.

type InstanceChat

type InstanceChat struct {
	// InstanceID is the owning instance's Instance.ID.
	InstanceID string
	// State is that instance's current InstanceState.
	State InstanceState
}

InstanceChat is one open chat in the session: InstanceID is the doors instance id, the tab the chat belongs to.

type InstanceState

type InstanceState struct {
	// Status is whether the session is enabled and the instance has a thread
	// yet.
	Status InstanceStatus
	// Thread is the thread the instance has open.
	Thread InstanceThread
}

InstanceState is the instance's view of itself. Thread is the zero value unless Status is InstanceEnabled.

type InstanceStatus

type InstanceStatus int

InstanceStatus is where the instance stands: InstanceDisabled while neui is not enabled for the session, InstanceLoading once it is but the tab's thread id has yet to sync, InstanceEnabled with a thread to render.

const (
	InstanceDisabled InstanceStatus = iota // session not enabled
	InstanceLoading                        // tab state not in yet
	InstanceEnabled                        // linked to a thread
)

type InstanceThread

type InstanceThread struct {
	// ID is the thread's id, valid for ThreadOpen, ThreadGet and the other
	// Thread* calls once the thread exists in storage.
	ID ThreadID
	// Name is the chat title set by the agent; empty until named.
	Name string
	// New is true until the thread's first round or first app event
	// (Instance.Emit) creates it in storage; until then Instance.ThreadList
	// does not list it.
	New bool
	// Updated is when this instance last saw a round start on the thread, by
	// its own clock; the zero time until one starts after the thread was
	// opened. It is not the stored Thread.Updated that Instance.ThreadList
	// orders by.
	Updated time.Time
}

InstanceThread is the thread the instance has open.

type IslandConfig

type IslandConfig struct {
	// MaxItems is how many slots, widgets and layouts one island may hold at
	// once; a create or set that would pass it is refused. Default 512.
	MaxItems int
	// MaxOps is how many sets, updates and notifies a script may queue before its
	// next ui.draw applies them; the call past it is refused. Default 512.
	MaxOps int
	// TurnTime is how long a script may run between ui.draw calls, fetch, app
	// function and tool calls included, before it is stopped. The app stays
	// up; the scripts still queued behind it are dropped. Default 30s.
	TurnTime time.Duration
	// Memory is the JS runtime's memory limit in bytes, at least 4 MiB.
	// Default 16 MiB.
	Memory int
	// MaxCallDepth is how many nested JS calls a script may make before a
	// stack overflow is thrown. Default 1000.
	MaxCallDepth int
	// MaxQueue is how many of the agent's scripts may wait to run on one
	// island; the one past it is refused, unless the agent sends it to replace
	// the running and queued ones. Default 16.
	MaxQueue int
	// FnTime is how long one IslandCall may run, app function calls included,
	// before it is stopped. Default 5s.
	FnTime time.Duration
	// FnMemory is the memory limit in bytes of the JS runtime an app run's
	// IslandCalls share, at least 4 MiB. Its call depth is MaxCallDepth.
	// Default 4 MiB.
	FnMemory int
}

IslandConfig bounds the scripts that draw into islands: how much UI one app may hold, how much a script may queue between draws, and the JS runtime it runs on. A zero or negative field takes its default.

type Message

type Message struct {
	Role    Role     `json:"role"`    // who wrote the turn
	Content Contents `json:"content"` // blocks in order; tool results go in user messages
}

Message is one turn of a conversation sent in a Request.

type MessageStorage

type MessageStorage interface {
	// ThreadList returns threads updated in [from, to), at most limit of
	// them. A zero from or to drops that bound; limit <= 0 means no cap. A
	// non-empty name keeps only threads whose name contains it,
	// case-insensitively, and limit counts what is left. They come most
	// recently updated first, ties broken by id descending, unless asc
	// reverses both, and limit keeps the first limit threads in that order.
	ThreadList(ctx context.Context, from, to time.Time, asc bool, limit int, name string) ([]Thread, error)
	// ThreadBump fetches the thread and bumps its Seq, taking the write
	// serial without writing any content. Updated stays as it was, so a
	// bump on its own does not reorder the thread in ThreadList.
	ThreadBump(ctx context.Context, thread ThreadID) (Thread, error)
	// ThreadGet returns the thread; an unknown id is ErrNotFound.
	ThreadGet(ctx context.Context, thread ThreadID) (Thread, error)
	// ThreadCreate creates an empty thread with the caller-supplied id; an id
	// already in use is ErrExists.
	ThreadCreate(ctx context.Context, id ThreadID) (Thread, error)
	// ThreadCut removes all rounds starting with round, and all compactions
	// whose Tail references a removed round (Tail >= round) — a rewind into a
	// compaction's verbatim region thereby replays originals. NoRoundID means
	// everything. Records with Origin >= round are removed; records with
	// Pin >= round are unpinned and surface again in the current request.
	ThreadCut(ctx context.Context, id ThreadID, seq Seq, round RoundID) (Seq, error)
	// ThreadRename sets the thread's name, replacing whatever it was named
	// before; an empty name leaves it unnamed again. Updated stays as it was,
	// so a rename does not reorder the thread in ThreadList.
	ThreadRename(ctx context.Context, id ThreadID, seq Seq, name string) (Seq, error)
	// ThreadClone creates the target thread as a copy of source with its name,
	// rounds, compactions and records; files and workspace are not copied. A
	// missing source is ErrNotFound and a target already in use ErrExists.
	ThreadClone(ctx context.Context, source ThreadID, target ThreadID) (Thread, error)
	// ThreadDelete removes the thread with its rounds, compactions and records;
	// its files and workspace are left to UploadStorage and WorkspaceStorage. It
	// takes no seq, and a thread that is not there is not an error.
	ThreadDelete(ctx context.Context, id ThreadID) error

	// CompactionCreate stores the compaction record: its Target is the round
	// the summary attaches to on replay (the first kept round), its Tail the
	// last round completed when the compaction was applied, and Output with
	// Base size the context it leaves behind.
	CompactionCreate(ctx context.Context, thread ThreadID, seq Seq, compaction Compaction) (Seq, error)
	// CompactionGet returns the latest compaction whose Tail < beforeTail;
	// a NoRoundID beforeTail means simply the latest. Returns NoCompaction
	// and a nil error when none exists.
	CompactionGet(ctx context.Context, thread ThreadID, beforeTail RoundID) (Compaction, error)

	// RoundRange returns rounds from start to end one by one; a NoRoundID
	// start means from the beginning, a NoRoundID end means to the head. A
	// non-nil second value ends the iteration.
	RoundRange(ctx context.Context, thread ThreadID, start RoundID, end RoundID) iter.Seq2[Round, error]
	// RoundBefore returns at most limit rounds before start (excluding it);
	// limit <= 0 returns none. They come in ascending id order; a NoRoundID
	// start means the last rounds, including the head. These rounds feed a chat, which never renders
	// tool results or record bodies, so Results comes back empty and
	// PinnedRecords come back without Data — read a round through
	// RoundRange when they are needed.
	RoundBefore(ctx context.Context, thread ThreadID, start RoundID, limit int) ([]Round, error)
	// RoundAfter returns at most limit rounds after start (excluding it);
	// limit <= 0 returns none. They come in ascending id order; a NoRoundID
	// start means the first rounds, including the oldest. Results and record Data come back empty, as in
	// RoundBefore.
	RoundAfter(ctx context.Context, thread ThreadID, start RoundID, limit int) ([]Round, error)
	// RoundSearch returns rounds whose input text or response text contains
	// query, case-insensitively — one Hit per round, at the first match,
	// input before response. Reasoning, tool calls, tool results,
	// attachments and errors are not searched. A zero thread searches every
	// thread; a named thread restricts the search to it, or with exclude
	// set, to every thread but it. An empty query matches nothing. Hits are
	// ordered by (created, thread, round), ascending when asc and descending
	// when not; a nil from starts at the end the direction runs from and
	// inclusive says nothing there, otherwise the walk starts at from, taking
	// the round it names when inclusive and starting past it when not. limit
	// caps the result; limit <= 0 means no cap. Only the chat calls this,
	// and an implementation that does not support search may return no
	// hits.
	RoundSearch(ctx context.Context, thread ThreadID, exclude bool, query string, from *Cursor, inclusive bool, asc bool, limit int) ([]Hit, error)
	// RoundInput creates a round in the input state with the user's input,
	// returns its id.
	RoundInput(ctx context.Context, thread ThreadID, seq Seq, input Input) (RoundID, Seq, error)
	// RoundOk marks the round completed with the model's usage and response
	// content.
	RoundOk(ctx context.Context, thread ThreadID, seq Seq, round RoundID, usage EventUsage, content Indexed[Content]) (Seq, error)
	// RoundRefuse marks the round refused, keeping whatever usage and
	// partial response content arrived before the refusal.
	RoundRefuse(ctx context.Context, thread ThreadID, seq Seq, round RoundID, usage EventUsage, content Indexed[Content]) (Seq, error)
	// RoundError marks the round errored and stores the error text, keeping
	// whatever usage and partial response content arrived before the error.
	RoundError(ctx context.Context, thread ThreadID, seq Seq, round RoundID, err string, usage EventUsage, content Indexed[Content]) (Seq, error)
	// RoundResult sets the round's tool results, keyed by tool call id,
	// replacing any stored before; pass every result in one call.
	RoundResult(ctx context.Context, thread ThreadID, seq Seq, round RoundID, result map[string]ContentToolResult) (Seq, error)
	// RoundAbort marks the round aborted, keeping whatever usage and partial
	// response content arrived before the abort.
	RoundAbort(ctx context.Context, thread ThreadID, seq Seq, round RoundID, usage EventUsage, content Indexed[Content]) (Seq, error)

	// RecordAdd stores a record, unpinned; origin is the round whose action
	// produced it. Returns the new record's id.
	RecordAdd(ctx context.Context, thread ThreadID, seq Seq, origin RoundID, kind string, attrs map[string]any, data any) (RecordID, Seq, error)
	// RecordPin pins the records to the round whose user message renders
	// them on replay. An unknown record id is ErrNotFound and pins nothing.
	RecordPin(ctx context.Context, thread ThreadID, seq Seq, pin RoundID, records []RecordID) (Seq, error)
	// RecordList returns the unpinned records in id order.
	RecordList(ctx context.Context, thread ThreadID) ([]Record, error)
}

MessageStorage stores one user's threads and rounds; round ids are thread-scoped and monotonically increasing. Writes are serialized per thread via Seq: each write takes seq as an optimistic concurrency guard, applies only if the thread is currently at that Seq, bumps it, and returns the new Seq; a stale seq fails the write with ErrDrift. A missing thread or round is ErrNotFound. NoRoundID (-1) is the open/none sentinel for RoundID parameters.

type Model

type Model struct {
	// Name is the id as it goes on the wire.
	Name string `json:"name"`
	// Context is the model's total window in tokens, input and output
	// together, as the provider publishes it. A provider that also caps input
	// lower than that refuses an over-long request with its context-length
	// error, which starts compaction like any other. Zero means unknown, not a
	// window of zero; a caller reading zero skips token-based compaction,
	// leaving the ThreadMemoryLimit byte budget and the API's own over-length
	// error to start it.
	Context int `json:"context"`
	// ImagePixels is the pixel area, width times height, worth sending in one
	// image: past it the API either downscales or refuses, so the extra pixels
	// buy nothing. Zero means unknown, and a caller reading zero sends what it
	// has.
	ImagePixels int `json:"imagePixels"`
	// ImageSide is the longest side, in pixels, worth sending in one image:
	// past it the API downscales or refuses, whatever the area. Zero means
	// unknown, and a caller reading zero holds an image it shapes to 2000.
	ImageSide int `json:"imageSide"`
	// ImageBytes is the largest one image the API takes, counted in raw file
	// bytes before base64 or any other encoding. A provider whose docs state
	// the limit on the encoded form declares the raw size that encodes to it:
	// three quarters of a base64 limit. Zero means unknown: no image is
	// refused for its size on replay, and an image shaped for the model is
	// held to 4 MiB.
	ImageBytes int `json:"imageBytes"`
	// ImagesPerRequest is how many images the API reads in one request. It
	// tracks the model's context rather than its byte limit, since every image
	// costs tokens. A PDF charges one per page, the API rendering every page to
	// an image. Zero means unknown.
	ImagesPerRequest int `json:"imagesPerRequest"`
	// RequestBytes is the largest request the API takes, counted as the
	// marshalled body that goes on the wire: every block of every message
	// included, media already base64-encoded. It is the one byte limit not
	// counted raw; the replay budget derived from it takes three quarters of
	// it to get back to raw media bytes (see ThreadConfig.ThreadMemoryLimit).
	// Zero means unknown: the body is sent without a size check, and the
	// replay budget is ThreadMemoryLimit alone.
	RequestBytes int `json:"requestBytes"`
}

Model names a model and carries what the API never reports about it. A provider package declares the models it knows as Model values; a caller may pass its own literal for a model the package does not list, or to override what it lists.

type MultiContainer

type MultiContainer interface {
	// Contents returns the blocks of the result, in order.
	Contents() []UserContent
}

MultiContainer is a tool output that becomes several blocks of one result, in the order Contents returns them.

type OkCode

type OkCode string

OkCode says how a turn that is worth keeping ended, for a caller that renders it. The decision to store was already made by the event this arrives on. A turn that wants tool results has no code of its own, and a caller dispatches from the calls it holds.

const (
	CodeTurn OkCode = "turn" // the model said everything it meant to say
)

type Origin

type Origin string

Origin says which side of the conversation a file came from. It is part of the key, so the two sides are separate namespaces.

const (
	OriginUser  Origin = "user"  // uploaded by the user
	OriginAgent Origin = "agent" // stored by the model or its tools
)

func (Origin) Valid

func (o Origin) Valid() bool

Valid reports whether o is an origin storage knows; FilePut refuses anything else.

type Provider

type Provider interface {
	// Name identifies the API. Signatures and sealed payloads are bound to the
	// API that issued them and cannot be replayed against another, so whoever
	// stores a conversation stores this name with it. No Content block carries it.
	Name() string

	// Stream returns at once and delivers the reply on the channel, in the order
	// it was produced.
	//
	// A turn that ends on its own ends in EventOk or EventErr, then the channel
	// closes. A connection that dies mid-reply ends in neither: an adapter must
	// not invent an ending, and a closed channel with no terminal event means an
	// incomplete reply.
	//
	// A caller that stops reading must cancel ctx, or the provider blocks. Cancel,
	// and a caller deadline on ctx, end the turn: the caller reads ctx.Err() rather
	// than a terminal event. Events already queued may still arrive before the
	// channel closes, and a caller that cancelled ignores whatever it is handed
	// from then on rather than counting it; what is promised is that the channel
	// closes and that no ending is invented. An adapter holds nothing open after
	// cancel. A deadline the provider keeps itself, such as an idle timeout, is
	// invisible in ctx and so ends the turn with EventErr and CodeNetwork.
	Stream(ctx context.Context, req Request) <-chan Event

	// Model is the model this provider was configured with: callable before the
	// first turn, and constant across turns.
	Model() Model
}

Provider is one model API. It converts a Request into whatever that API wants and the reply back into Events.

type Record

type Record struct {
	ID     RecordID       `json:"id"`     // identifies the record within its thread
	Origin RoundID        `json:"origin"` // round whose action created it
	Pin    RoundID        `json:"pin"`    // round that renders it; NoRoundID while unpinned
	Kind   string         `json:"kind"`   // element name, e.g. "task_notify"
	Attrs  map[string]any `json:"attrs"`  // element attributes; may be nil
	Data   any            `json:"data"`   // body: a string, json.RawMessage or any JSON-encodable value
}

Record is a thread-level entry produced by code: Origin is the round whose action created it, and Pin is the round whose user message renders it on replay (NoRoundID while unpinned).

The model reads a record as an element named Kind with Attrs as attributes and Data, escaped or JSON-encoded, as its body.

type RecordID

type RecordID int

RecordID identifies a record within its thread.

type Request

type Request struct {
	Tools      []Tool     `json:"tools"`      // tools the caller runs; empty offers none
	System     string     `json:"system"`     // system prompt; empty sends none
	Messages   []Message  `json:"messages"`   // the conversation, oldest first
	ToolChoice ToolChoice `json:"toolChoice"` // empty leaves the choice to the provider
}

Request is one call to a model. Field order follows the cache hierarchy: tools, then system, then messages. A change at one level invalidates that level and every level after it.

Model, the response cap, and sampling and reasoning settings are not fields here. They belong to the provider's own configuration; a caller wanting one model at two settings configures the provider twice.

type Role

type Role string

Role is the author of a message. Only user and assistant exist: the system prompt is request configuration, and a tool result is a content block that an adapter places in whichever message its provider expects.

const (
	RoleUser      Role = "user"
	RoleAssistant Role = "assistant"
)

The two roles.

type Round

type Round struct {
	ID     RoundID    `json:"id"`     // identifies the round within Thread
	Thread ThreadID   `json:"thread"` // thread the round belongs to
	State  RoundState `json:"state"`  // lifecycle; decides replay and retry
	// Created is when the round was opened. It is the zero time on rounds
	// written before storage recorded it.
	Created  time.Time                    `json:"created"`
	Input    Input                        `json:"input"`    // what the user sent
	Error    string                       `json:"error"`    // error text when State is RoundError
	Usage    EventUsage                   `json:"usage"`    // last usage the provider reported
	Response Indexed[Content]             `json:"response"` // the model's blocks, by stream Index
	Results  map[string]ContentToolResult `json:"results"`  // tool results by tool call id
	// PinnedRecords holds the records pinned to this round, filled on reads
	// by RoundRange, RoundBefore and RoundAfter; only RoundRange includes
	// their Data.
	PinnedRecords []Record `json:"records"`
}

Round is one full exchange — the user input plus the model's response, tool results, and usage — and the unit the UI renders as a turn.

type RoundID

type RoundID int

RoundID is a thread-scoped, monotonically increasing round identifier; NoRoundID (-1) is the none/open sentinel.

type RoundState

type RoundState string

RoundState is a round's lifecycle and replay tag; the zero value is RoundInput.

type Seq

type Seq int

Seq is a per-thread write serial that acts as an optimistic concurrency guard for MessageStorage writes.

type Task

type Task struct {
	// ID is stable for the task's lifetime and unique within the thread link.
	ID uint
	// Module is the name of the module whose tool started the task.
	Module string
	// Name is the name of that tool.
	Name string
	// Comment is the short description the tool gave when it started the
	// task; empty when it gave none.
	Comment string
	// Meta is the attrs the tool passed to ToolTask, never nil.
	Meta map[string]any
	// Cancel stops the task; the cause it is given is what the task reports.
	Cancel context.CancelCauseFunc
}

Task is a background task a tool started with neui.ToolTask, as a chat lists it.

type Thread

type Thread struct {
	ID      ThreadID  `json:"id"`      // stable key for every MessageStorage call on it
	Name    string    `json:"name"`    // display name; "" while unnamed
	Seq     Seq       `json:"seq"`     // current write serial, passed to the next write
	Created time.Time `json:"created"` // when ThreadCreate or ThreadClone made it
	Updated time.Time `json:"updated"` // last content write; ThreadList orders by it
}

Thread is one conversation as MessageStorage lists it.

type ThreadConfig

type ThreadConfig struct {
	// CompactionTrigger is the share of Model.Context that the thread's token
	// usage must reach, when a round ends, for the thread to start compacting.
	// It has no effect when Model.Context is zero, and above 1 it never fires;
	// the ThreadMemoryLimit byte budget and the API's over-length error still
	// start compaction either way. Default 0.8.
	CompactionTrigger float32
	// CompactionAllowed is the share of Model.Context the thread's token usage
	// must reach before a compaction the user requests is accepted; below it
	// the request fails with ErrWrongState. When Model.Context is zero the
	// share is not checked. Default 0.2.
	CompactionAllowed float32
	// CompactionPreserve is the share of the conversation kept verbatim after
	// the summary. Default 0.1.
	CompactionPreserve float32
	// ReplayItemShare sets the round item budget, Model.Context * 4 *
	// ReplayItemShare bytes (four bytes per token), assuming a 200,000-token
	// context when Model.Context is zero. Input: an Input whose text blocks,
	// its Text plus the file links its Attachments turn into, add up to more
	// than the budget is refused with ErrInputTooLarge where it is submitted,
	// drafted or rewound to. Tool results: a round's calls run in order while
	// their results' text is under the budget; the result that crosses it is
	// kept whole and the calls after it are answered without running; a result
	// whose text alone is over it is replaced by a note giving its size.
	// Records: a round takes the waiting records in arrival order while their
	// bodies add up to at most the budget, the rest wait for the next round,
	// and a first record over it alone is cut to it and taken by itself. On
	// replay each result's text, each record's body and the input's text are
	// cut to the budget, keeping head and tail; an input is over it only when
	// the budget shrank after it was sent, as after a switch to a smaller
	// model. Media blocks are not counted. Half of it bounds the values an
	// island script queues with ui.notify between draws. A non-positive value
	// takes the default, 0.1; a value above 0.25 counts as 0.25.
	ReplayItemShare float32
	// ThreadMemoryLimit is the byte budget over everything a thread holds for
	// replay: media counted raw, text counted as it stands. When
	// Model.RequestBytes is known the budget is at most
	// Model.RequestBytes*3/4 - ReplayHeadroom (the three quarters undo the
	// base64 inflation media takes on the wire). The first request the
	// provider refuses as too large lowers the budget and retries the round.
	// Going over the budget starts compaction. Negative means no byte budget.
	// Default 18 MiB.
	ThreadMemoryLimit int64
	// ToolCallLimit is how many tool calls of one round are executed; a call
	// past it is not run and is answered with an error naming the limit.
	// Negative runs every call a round asks for. Default 32.
	ToolCallLimit int
}

ThreadConfig holds the tunables of an app that are not a provider, a storage or a module. A zero field takes its default; a caller sets only what it wants to change.

type ThreadID

type ThreadID string

ThreadID names a thread. It is chosen by the caller of ThreadCreate and is also the key for the thread's files and workspace.

type Tool

type Tool struct {
	Name   string `json:"name"`        // name the model calls it by, echoed in ContentToolUse.Name
	Desc   string `json:"description"` // what the tool does and when to call it, written for the model
	Schema any    `json:"schema"`      // JSON Schema of the input, marshalling to an object; nil takes no input
}

Tool is a tool the caller runs itself and answers with a ContentToolResult.

Tools the provider runs are never declared here, even where the wire puts both in one array: the caller neither executes nor answers them, and their output arrives as ContentOpaque. Configure those on the adapter.

type ToolChoice

type ToolChoice string

ToolChoice constrains which tool the model may call. The constants below are modes; any other value names the one tool the model must call. Empty leaves the choice to the provider, which is not ToolChoiceAuto everywhere, so an adapter sends no field for it.

Modes and tool names share one string: a tool named auto, none or any cannot be forced and becomes a mode instead.

const (
	ToolChoiceAuto ToolChoice = "auto" // call a tool or answer, model decides
	ToolChoiceNone ToolChoice = "none" // answer without calling a tool
	ToolChoiceAny  ToolChoice = "any"  // call some tool, model picks which
)

func (ToolChoice) Tool

func (c ToolChoice) Tool() (string, bool)

Tool reports the forced tool name, or false for empty and for any mode.

type ToolError

type ToolError string

ToolError says how a call turned out. Any value but ToolOk is sent as the adapter's failure marker (an is_error flag or an "Error:" prefix); the failure itself is described in ContentToolResult.Content.

The three values are the whole set. A stored value that is none of them decodes as ToolErrRuntime, so a vocabulary that grew reads as a call that failed rather than as one that succeeded.

const (
	ToolOk         ToolError = ""            // the call ran and its output is in Content
	ToolErrRuntime ToolError = "err_runtime" // the call failed, or never ran for a reason of its own
	ToolErrJSON    ToolError = "err_json"    // the arguments never formed valid JSON, so the call was never made; see DiscardedArguments
)

func (*ToolError) UnmarshalJSON

func (e *ToolError) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes a stored value, reading any unknown one as ToolErrRuntime.

type UploadStorage

type UploadStorage interface {
	// FilePut streams r into a new blob and returns the record with Size
	// and CreatedAt filled. Name is the key within the thread and origin:
	// one path element, not empty, not "." or ".." and holding no
	// separator — anything else is ErrInvalidName, so every stored name is
	// addressable. A storage may also refuse, as ErrInvalidName, a name it
	// cannot hold, such as one too long for its keys. An empty threadID or
	// an origin that is not Valid is refused too. It commits whole or not at all, and a name already
	// taken is ErrExists with nothing written: blobs are immutable, so the
	// caller resolves a collision by choosing another name (on S3, a
	// conditional If-None-Match put). draft stores the blob as a draft, see
	// File.Draft.
	FilePut(ctx context.Context, threadID ThreadID, origin Origin, name string, mime string, r io.Reader, draft bool) (File, error)
	// FileCommit clears Draft on the record, making the blob part of the
	// conversation; a committed file stays committed. A missing key is
	// ErrNotFound. On a keyed store this is a metadata-only change (a tag,
	// a row update), never a copy.
	FileCommit(ctx context.Context, threadID ThreadID, origin Origin, name string) error
	// FileDiscardDrafts deletes the origin's drafts except those named in
	// keep, so a caller sweeps abandoned uploads in one call. A missing
	// thread or origin is nil.
	FileDiscardDrafts(ctx context.Context, threadID ThreadID, origin Origin, keep []string) error
	// FileStat returns the record; a missing key is ErrNotFound.
	FileStat(ctx context.Context, threadID ThreadID, origin Origin, name string) (File, error)
	// FileRead streams [off, off+n) of the blob; n < 0 means to EOF.
	// Reading past EOF truncates silently; a negative off is refused and
	// off at or past the end is ErrOutOfRange, except off 0 with negative
	// n on an empty blob, which reads empty (an S3 ranged GET answers 416
	// the same way). A missing key is ErrNotFound. The reader does not
	// watch ctx; closing it closes the blob.
	FileRead(ctx context.Context, threadID ThreadID, origin Origin, name string, off int64, n int64) (io.ReadCloser, error)
	// FileList yields the origin's files sorted lexically by name in byte
	// order, which is what a keyed store lists in. A missing thread or
	// origin yields nothing rather than an error. Records that cannot be
	// read are skipped; an error means the listing failed.
	FileList(ctx context.Context, threadID ThreadID, origin Origin) iter.Seq2[File, error]
	// FileDelete removes the blob and its record; a missing key is nil, so
	// deletes are idempotent.
	FileDelete(ctx context.Context, threadID ThreadID, origin Origin, name string) error
	// FileDeleteAll removes every blob in the thread, all origins; it is
	// called when the thread is deleted. A missing thread is nil, so it too
	// is idempotent.
	FileDeleteAll(ctx context.Context, threadID ThreadID) error
}

UploadStorage keeps immutable blobs under caller-chosen (thread, origin, name) keys. The contract mirrors S3 throughout, so a remote implementation can stand in for a local one unchanged. The blob never changes; the one mutable bit of the record is Draft, and FileCommit is the only way to flip it.

type UserContent

type UserContent interface {
	Content
	// contains filtered or unexported methods
}

UserContent is the subset of Content a user may author: text and attachments. A tool result carries the same subset, so it is also the content of ContentToolResult, and nesting a result in a result stays inexpressible.

Not every provider accepts the whole subset everywhere: some take only text in a tool result. An adapter leaves a note in place of a block it cannot carry, including one whose media type its API does not accept, and logs nothing, so a result always answers the call it is matched to and the request still goes out. The one refusal left is a discarded call whose result lacks ToolErrJSON; see ContentToolUse.

type UserContents

type UserContents []UserContent

UserContents decodes the narrower set a user may author, which is also what a tool result carries. A block that decodes but does not implement UserContent is an error, never a silent drop.

func NewToolContents

func NewToolContents(output any) (UserContents, error)

NewToolContents encodes a tool's output as the content of its result: UserContents and UserContent as they are, a Container as its Content, a MultiContainer as its Contents, a string or fmt.Stringer as one text block, and anything else as its JSON in one text block.

func (*UserContents) UnmarshalJSON

func (cs *UserContents) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes a JSON array of tagged blocks, failing on any block that is not UserContent.

type Widget

type Widget[P any] interface {
	// Update applies a patch already decoded and validated against P; a patch
	// that fails validation never reaches it. Use ctx for the door and beam
	// updates the patch causes.
	Update(ctx context.Context, patch P)
	gox.Comp
}

Widget is the component a Library.View or Library.Control factory returns: it renders once when an island script creates it, then receives the patches the script sends with update. P is the patch type; its JSON schema is what the model is told the patch looks like.

type Workspace

type Workspace struct {
	Dir  string   // absolute path; use Root for file access
	Root *os.Root // confined handle every file access goes through
}

Workspace is a thread's scratch directory. File access goes through Root, which cannot be escaped by .. or symlinks; Dir is the absolute path, for what needs a real path, such as a cwd or a library that opens files itself.

func (*Workspace) Close

func (w *Workspace) Close() error

Close releases the handle and nothing else: the directory stays, so the thread finds its files on the next open, and a second handle on the same workspace keeps working.

type WorkspaceStorage

type WorkspaceStorage interface {
	// WorkspaceOpen returns the thread's workspace, creating it on first use.
	WorkspaceOpen(threadID ThreadID) (Workspace, error)
	// WorkspaceDelete removes the workspace with everything in it; a missing
	// one is nil, so deletes are idempotent. A handle still open keeps its
	// descriptor but the files are gone.
	WorkspaceDelete(threadID ThreadID) error
}

WorkspaceStorage hands out per-thread scratch directories. A workspace is created on first open and survives Close, so a thread finds its files again until the workspace is deleted.

Jump to

Keyboard shortcuts

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