scene

package
v0.32.1 Latest Latest
Warning

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

Go to latest
Published: Nov 1, 2026 License: MIT Imports: 5 Imported by: 0

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

Constants

This section is empty.

Variables

View Source
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) Get

func (s *MemoryStore) Get(sessionID, id string) (Scene, 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

type Patcher interface {
	Apply(existing, patch any) any
}

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.

Jump to

Keyboard shortcuts

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