Documentation
¶
Overview ¶
Package live is the runtime that ties the Kiln components together during a session: it owns the current Session (world + chat + plans), the Journal that persists every edit, the framework.App that serves the live preview, and the SSE broadcaster that notifies the panel.
Apply is the single funnel through which the world ever changes. Anything that wants to mutate state — the agent's tool surface, the chat panel's undo button, an external MCP client — converges on this one path so journal, app, and SSE stay consistent.
Index ¶
- type AppFactory
- type Broadcaster
- type Event
- type Live
- func (l *Live) App() *framework.App
- func (l *Live) Apply(e journal.Entry) error
- func (l *Live) Aux() *router.Router
- func (l *Live) Deferred() kilnrender.Deferred
- func (l *Live) Journal() journal.Journal
- func (l *Live) Notify(kind, summary string)
- func (l *Live) Reload() error
- func (l *Live) ServeHTTP(w http.ResponseWriter, r *http.Request)
- func (l *Live) ServeSSE(w http.ResponseWriter, r *http.Request)
- func (l *Live) Session() *journal.Session
- func (l *Live) SetFallbackFunc(fn func(*http.Request) string)
- func (l *Live) SetFallbackHTML(html string)
- func (l *Live) Subscribe() (<-chan Event, func())
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AppFactory ¶
AppFactory builds a fresh framework.App. Kiln calls it on every rebuild so callers can wire any options they want (DB, custom plugins, …).
type Broadcaster ¶
type Broadcaster struct {
// contains filtered or unexported fields
}
Broadcaster fan-outs Events to subscribed channels. Slow consumers drop events rather than blocking the broadcaster.
func NewBroadcaster ¶
func NewBroadcaster() *Broadcaster
NewBroadcaster returns an empty Broadcaster.
func (*Broadcaster) Send ¶
func (b *Broadcaster) Send(e Event)
Send delivers e to every subscribed channel. Non-blocking: a subscriber whose buffer is full will miss this event.
func (*Broadcaster) Subscribe ¶
func (b *Broadcaster) Subscribe() (<-chan Event, func())
Subscribe registers a channel and returns it along with an unsubscribe function. The channel is closed by unsubscribe; callers must call it.
type Event ¶
type Event struct {
EntryID string `json:"entry_id"`
Kind string `json:"kind"`
Op string `json:"op,omitempty"`
// Summary is a glanceable, human-readable digest of the entry's
// payload (e.g. "name=posts fields=3" for add_entity). Empty for
// kinds that don't have a useful one-liner. Computed in Apply.
Summary string `json:"summary,omitempty"`
}
Event is one notification published when a journal entry is applied. Subscribers learn that something changed; they can pull current state (e.g. the Deferred report or specific entity data) via separate calls.
type Live ¶
type Live struct {
// contains filtered or unexported fields
}
Live is the runtime coordinator: Session ↔ Journal ↔ App ↔ SSE.
func New ¶
func New(j journal.Journal, factory AppFactory) (*Live, error)
New constructs a Live runtime from an existing journal (which may already contain entries from a previous session). It replays the journal, builds the initial app, and is ready to Apply further entries.
func (*Live) App ¶
App returns the current rebuilt framework.App. Callers can use this to reach app.MCP (per-entity MCP tools auto-registered when an entity has mcp:true) or app.Router() for advanced wiring. Note: the pointer changes on every Apply rebuild — don't cache it.
func (*Live) Apply ¶
Apply is the single funnel. It applies the entry to the in-memory session, validates it by rebuilding the app, and ONLY THEN persists it to the journal — so a poison entry that fails the rebuild never reaches the durable log (which would re-fail on every restart). On any failure the pre-entry state is restored by replaying the (still-unchanged) journal.
func (*Live) Aux ¶
Aux returns the auxiliary router, mounted on the same listener as the rebuilt app but stable across rebuilds. Use it to register surfaces that must survive world mutations (e.g. the chat panel).
func (*Live) Deferred ¶
func (l *Live) Deferred() kilnrender.Deferred
Deferred returns the most recent Deferred report from rebuild.
func (*Live) Notify ¶
Notify broadcasts a synthetic SSE Event without journaling. Use for runtime lifecycle signals the panel needs to react to but that are not part of world state — agent_turn_started, agent_turn_ended, session_reset, etc. Safe to call concurrently.
func (*Live) Reload ¶
Reload discards the in-memory session and rebuilds it from the journal. Useful after out-of-band journal writes or recovery from inconsistency.
func (*Live) ServeHTTP ¶
func (l *Live) ServeHTTP(w http.ResponseWriter, r *http.Request)
ServeHTTP first tries the auxiliary router (kiln-internal paths), falling through to the current app's router on 404.
func (*Live) ServeSSE ¶
func (l *Live) ServeSSE(w http.ResponseWriter, r *http.Request)
ServeSSE is a stand-alone HTTP handler that streams events as Server-Sent Events. Mount at e.g. "/.kiln/events".
func (*Live) SetFallbackFunc ¶
SetFallbackFunc installs a per-request fallback renderer. Use when the fallback HTML depends on request headers (e.g. host/port for rendering correct curl examples). Mutually exclusive with SetFallbackHTML — the most recent setter wins.
func (*Live) SetFallbackHTML ¶
SetFallbackHTML installs a catch-all HTML response for any request the world doesn't claim. Empty disables the fallback (default). cmd/kiln wires this to chat.HostHTML() so every URL surfaces the floating widget when no page is registered.
Source Files