Documentation
¶
Overview ¶
Package scene defines the Scene primitive — a named, structured, mutable session-scoped entity an agent uses to build durable visual output. Scenes are content-agnostic from the runtime's perspective: the engine stores blobs, journals patches, and emits scene.* events; downstream renderers (UIs, exporters) interpret the schema-specific content.
The Store interface is what the nexus.scene plugin implements; it backs the SceneHandle methods the scene tools surface to agents and exposes the patch history that the replay primitive consumes for time-travel.
Index ¶
- Variables
- type IDedCreator
- type MemoryStore
- func (s *MemoryStore) Create(sessionID, schema string, initial any, agentID string) (SceneHandle, error)
- func (s *MemoryStore) CreateWithID(sessionID, id, schema string, initial any, agentID string) (SceneHandle, error)
- func (s *MemoryStore) Delete(sessionID, id string) error
- func (s *MemoryStore) Get(sessionID, id string) (Scene, error)
- func (s *MemoryStore) List(sessionID string) []SceneHandle
- func (s *MemoryStore) Patch(sessionID, id string, patch any, agentID string) (SceneHandle, error)
- func (s *MemoryStore) WithPatcher(p Patcher) *MemoryStore
- type Patcher
- type Scene
- type SceneEvent
- type SceneHandle
- type ShallowMerge
- type Store
Constants ¶
This section is empty.
Variables ¶
var ErrNotFound = errors.New("scene: not found")
ErrNotFound is returned by Get/Patch/Delete when the scene does not exist.
Functions ¶
This section is empty.
Types ¶
type IDedCreator ¶
type IDedCreator interface {
CreateWithID(sessionID, id, schema string, initial any, agentID string) (SceneHandle, error)
}
IDedCreator is an optional extension a Store may implement to create a scene under a caller-chosen id (used to seed AG-UI inbound shared state, E3-S2). Consumers type-assert for it and fall back to Create + a generated id when the store does not support it. Kept off the core Store interface so existing implementations need no change.
type MemoryStore ¶
type MemoryStore struct {
// contains filtered or unexported fields
}
MemoryStore is a goroutine-safe in-memory implementation suitable for the engine's default. Persistence is the plugin's job — MemoryStore is the authoritative source between persistence flushes.
func NewMemoryStore ¶
func NewMemoryStore() *MemoryStore
NewMemoryStore returns an empty store using ShallowMerge as the patcher.
func (*MemoryStore) Create ¶
func (s *MemoryStore) Create(sessionID, schema string, initial any, agentID string) (SceneHandle, error)
func (*MemoryStore) CreateWithID ¶
func (s *MemoryStore) CreateWithID(sessionID, id, schema string, initial any, agentID string) (SceneHandle, error)
CreateWithID is Create with a caller-chosen scene id. When id is empty a fresh id is generated (the normal Create path). When id is non-empty it is used verbatim, letting a client seed a scene under a known id (AG-UI inbound shared state, E3-S2). It is additive to the Store interface — callers that only hold a Store type-assert for the IDedCreator interface below.
func (*MemoryStore) Delete ¶
func (s *MemoryStore) Delete(sessionID, id string) error
func (*MemoryStore) List ¶
func (s *MemoryStore) List(sessionID string) []SceneHandle
func (*MemoryStore) Patch ¶
func (s *MemoryStore) Patch(sessionID, id string, patch any, agentID string) (SceneHandle, error)
func (*MemoryStore) WithPatcher ¶
func (s *MemoryStore) WithPatcher(p Patcher) *MemoryStore
WithPatcher swaps the default ShallowMerge for a schema-specific merger.
type Patcher ¶
Patcher merges a patch into existing content. The runtime is schema- agnostic, so the default Patcher does shallow JSON merge for maps and otherwise replaces. Schema-specific renderers can provide their own Patcher implementation if they need a richer semantics, but the runtime only ships shallow merge.
type Scene ¶
type Scene struct {
Handle SceneHandle `json:"handle"`
Content any `json:"content"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
History []SceneEvent `json:"history,omitempty"`
}
Scene is the full materialized record: handle, current content, and an optional patch history. Returned from Store.Get; the caller owns the content map.
type SceneEvent ¶
type SceneEvent struct {
Sequence int `json:"sequence"`
Timestamp time.Time `json:"timestamp"`
AgentID string `json:"agent_id,omitempty"`
Patch any `json:"patch"`
Initial bool `json:"initial,omitempty"`
}
SceneEvent records a single mutation on the scene's history. The patch is the value passed to PatchScene at the time; the first event records the initial content.
type SceneHandle ¶
type SceneHandle struct {
ID string `json:"id"`
SessionID string `json:"session_id"`
Schema string `json:"schema"`
Version int `json:"version"`
}
SceneHandle is the stable, session-scoped identity of a Scene plus a few pieces of metadata the agent's prompt may want to reference (the schema it conforms to, the current version). The Content lives in the Store.
type ShallowMerge ¶
type ShallowMerge struct{}
ShallowMerge is the default Patcher: maps merge key-by-key (the patch wins on collision), everything else replaces.
func (ShallowMerge) Apply ¶
func (ShallowMerge) Apply(existing, patch any) any
Apply merges patch into existing per the package doc.
type Store ¶
type Store interface {
Create(sessionID, schema string, initial any, agentID string) (SceneHandle, error)
Get(sessionID, id string) (Scene, error)
Patch(sessionID, id string, patch any, agentID string) (SceneHandle, error)
Delete(sessionID, id string) error
List(sessionID string) []SceneHandle
}
Store is the contract the nexus.scene plugin implements and tools / the replay primitive consume. Implementations must serialize concurrent patches against the same Scene (parent + sub-agent contention) and emit scene.created / scene.patched / scene.deleted on the bus.