session

Documentation

Index

• func IsReservedRuntimeStateKey(key string) bool
• func StripPlanKeys(state map[string]any)
• type AppliedCheckpoint
• type Checkpointer
  • func NewCheckpointer() Checkpointer
  • func (Checkpointer) Apply(cp stores.SessionCheckpoint, sm *SessionManager) (AppliedCheckpoint, error)
  • func (Checkpointer) Capture(window []*streaming.Message, sm *SessionManager, ...) (*stores.SessionCheckpoint, error)
• type PlanStore
  • func NewPlanStore() *PlanStore
  • func (p *PlanStore) ConsumeDocumentUpdated() bool
  • func (p *PlanStore) Document() string
  • func (p *PlanStore) ExportInto(state map[string]any)
  • func (p *PlanStore) Get() []Todo
  • func (p *PlanStore) HasActive() bool
  • func (p *PlanStore) LoadFromState(state map[string]any)
  • func (p *PlanStore) Set(todos []Todo)
  • func (p *PlanStore) SetDocument(plan string)
• type Runtime
  • func NewRuntime(ch chan streaming.StreamEvent, store stores.BaseStore, sm *SessionManager) Runtime
  • func (rt Runtime) AdoptInterrupt(intr interrupt.Interrupt) (interrupt.Interrupt, error)
  • func (rt Runtime) EmitPlanUpdate(plan []Todo)
  • func (rt Runtime) EmitUpdate(message string)
  • func (rt Runtime) HasPendingInterrupt() bool
  • func (rt Runtime) PendingInterrupt(id string) (interrupt.Interrupt, bool)
  • func (rt Runtime) RaiseInterrupt(kind string, payload []byte) (interrupt.Interrupt, error)
  • func (rt Runtime) ReturnInterrupt(id string, result []byte) (interrupt.Interrupt, error)
  • func (rt Runtime) StateDelete(key string)
  • func (rt Runtime) StateGet(key string) (any, bool)
  • func (rt Runtime) StateSet(key string, value any)
  • func (rt Runtime) TakeResolvedInterrupt(id string) (interrupt.Interrupt, bool)
• type SessionManager
  • func NewSessionManager() *SessionManager
  • func (s *SessionManager) ClearInterrupts()
  • func (s *SessionManager) HasActivePlan() bool
  • func (s *SessionManager) HasPendingInterrupt() bool
  • func (s *SessionManager) LoadInterruptsJSON(pendingJSON, resolvedJSON []byte) error
  • func (s *SessionManager) LoadUserAndPlanState(state map[string]any)
  • func (s *SessionManager) PendingInterrupt(id string) (interrupt.Interrupt, bool)
  • func (s *SessionManager) Plan() *PlanStore
  • func (s *SessionManager) ReturnInterrupt(id string, result []byte) (interrupt.Interrupt, error)
  • func (s *SessionManager) SnapshotDurable() (runtimeState map[string]any, pending, resolved interruptMap)
  • func (s *SessionManager) StateDelete(key string)
  • func (s *SessionManager) StateGet(key string) (any, bool)
  • func (s *SessionManager) StateSet(key string, value any)
• type Todo

Functions

func IsReservedRuntimeStateKey

func IsReservedRuntimeStateKey(key string) bool

IsReservedRuntimeStateKey reports keys owned by SessionManager export.

func StripPlanKeys

func StripPlanKeys(state map[string]any)

StripPlanKeys removes reserved plan keys from a runtime state map so they are not exposed via user-facing StateGet after load.

Types

type AppliedCheckpoint

type AppliedCheckpoint struct {
	Window               []*streaming.Message
	PendingToolCalls     map[string]stores.PendingToolCall
	InterruptToRequester map[string]string
}

AppliedCheckpoint is harness-side state restored from a store blob (everything not owned by SessionManager).

type Checkpointer

type Checkpointer struct{}

Checkpointer builds and applies SessionCheckpoint blobs. It does not own live session data — SessionManager does. It does not own persistence I/O — stores.BaseStore does.

Capture/Apply are pure over their inputs so tests can assert wire format without a real store.

func NewCheckpointer

func NewCheckpointer() Checkpointer

NewCheckpointer returns a Checkpointer.

func (Checkpointer) Apply

func (Checkpointer) Apply(cp stores.SessionCheckpoint, sm *SessionManager) (AppliedCheckpoint, error)

Apply loads SessionManager state from the checkpoint and returns maps the harness must reattach (window, pending tools, interrupt routing).

func (Checkpointer) Capture

func (Checkpointer) Capture(
	window []*streaming.Message,
	sm *SessionManager,
	pendingToolCalls map[string]stores.PendingToolCall,
	interruptToRequester map[string]string,
) (*stores.SessionCheckpoint, error)

Capture assembles a durable checkpoint from the message window, session manager (user state + plan + interrupts), and harness park maps.

type PlanStore

type PlanStore struct {
	// contains filtered or unexported fields
}

PlanStore holds the plan document and todo list for Adaptive Case Management. It is a SessionManager module — not exposed on HarnessRuntime.

func NewPlanStore

func NewPlanStore() *PlanStore

NewPlanStore returns an empty plan store.

func (*PlanStore) ConsumeDocumentUpdated

func (p *PlanStore) ConsumeDocumentUpdated() bool

ConsumeDocumentUpdated returns whether the plan document was updated since the last consume, and clears the flag.

func (*PlanStore) Document

func (p *PlanStore) Document() string

Document returns the plaintext project plan draft.

func (*PlanStore) ExportInto

func (p *PlanStore) ExportInto(state map[string]any)

ExportInto writes plan fields into a runtime-state map for session checkpoints. Overwrites reserved keys with the current PlanStore contents.

func (*PlanStore) Get

func (p *PlanStore) Get() []Todo

Get returns a shallow copy of the current todos, or nil if no plan was ever set. An empty non-nil slice means an explicit empty plan (e.g. after deleting all todos).

func (*PlanStore) HasActive

func (p *PlanStore) HasActive() bool

HasActive reports whether a todo list is present (write-lock unlock condition).

func (*PlanStore) LoadFromState

func (p *PlanStore) LoadFromState(state map[string]any)

LoadFromState hydrates the store from checkpoint RuntimeState (including JSON-rehydrated []any / map shapes). Safe to call with nil state.

func (*PlanStore) Set

func (p *PlanStore) Set(todos []Todo)

Set replaces the todo list (caller should emit StreamEventPlanUpdate separately). Pass nil to clear the plan entirely; pass a non-nil empty slice for an empty plan.

func (*PlanStore) SetDocument

func (p *PlanStore) SetDocument(plan string)

SetDocument stores the plaintext project plan draft. Marks the document updated only when replacing an existing draft with different text (edits), not on the initial install from create_plan.

type Runtime

type Runtime struct {
	Store             stores.BaseStore
	CurrentToolCallID string
	// contains filtered or unexported fields
}

Runtime is the tool-facing surface for a single harness turn: EmitUpdate, StateGet/Set/Delete, RaiseInterrupt, Store, CurrentToolCallID.

Lifetime: create with NewRuntime at Run start (with the turn event channel); discard when the turn ends. Session state lives on SessionManager and outlives the turn. Value copies share the same channel and session pointers.

Invariants: out and session are always non-nil after NewRuntime.

func NewRuntime

func NewRuntime(ch chan streaming.StreamEvent, store stores.BaseStore, sm *SessionManager) Runtime

NewRuntime builds a turn-scoped Runtime. ch and sm must be non-nil.

func (Runtime) AdoptInterrupt

func (rt Runtime) AdoptInterrupt(intr interrupt.Interrupt) (interrupt.Interrupt, error)

AdoptInterrupt attaches a child interrupt to the current tool call.

func (Runtime) EmitPlanUpdate

func (rt Runtime) EmitPlanUpdate(plan []Todo)

EmitPlanUpdate sends a non-blocking plan_update stream event.

func (Runtime) EmitUpdate

func (rt Runtime) EmitUpdate(message string)

EmitUpdate sends a non-blocking tool progress update for the current call.

func (Runtime) HasPendingInterrupt

func (rt Runtime) HasPendingInterrupt() bool

HasPendingInterrupt is true when any interrupt is still open. Prefer SessionManager.HasPendingInterrupt when no turn Runtime is in hand.

func (Runtime) PendingInterrupt

func (rt Runtime) PendingInterrupt(id string) (interrupt.Interrupt, bool)

PendingInterrupt returns an open interrupt for tool-call id if any.

func (Runtime) RaiseInterrupt

func (rt Runtime) RaiseInterrupt(kind string, payload []byte) (interrupt.Interrupt, error)

RaiseInterrupt parks the current tool until the host resumes with a payload.

func (Runtime) ReturnInterrupt

func (rt Runtime) ReturnInterrupt(id string, result []byte) (interrupt.Interrupt, error)

ReturnInterrupt resolves a parked interrupt with the host payload. Prefer SessionManager.ReturnInterrupt when no turn Runtime is in hand.

func (Runtime) StateDelete

func (rt Runtime) StateDelete(key string)

StateDelete removes a session value.

func (Runtime) StateGet

func (rt Runtime) StateGet(key string) (any, bool)

StateGet returns a session value stored with StateSet.

func (Runtime) StateSet

func (rt Runtime) StateSet(key string, value any)

StateSet stores a session value for tools and interceptors.

func (Runtime) TakeResolvedInterrupt

func (rt Runtime) TakeResolvedInterrupt(id string) (interrupt.Interrupt, bool)

TakeResolvedInterrupt removes and returns a resolved interrupt if present.

type SessionManager

type SessionManager struct {
	// contains filtered or unexported fields
}

SessionManager owns durable and live data for one agent harness thread (checkpoint id), not an ACP client session id: plan, user tool state, and interrupts. Knowledge namespace + ResultSet live on brain.SearchContext. Builtins close over it; user tools use Runtime.

func NewSessionManager

func NewSessionManager() *SessionManager

NewSessionManager returns an empty manager ready for use.

func (*SessionManager) ClearInterrupts

func (s *SessionManager) ClearInterrupts()

ClearInterrupts drops pending and resolved interrupt maps (steer / cancel finalize).

func (*SessionManager) HasActivePlan

func (s *SessionManager) HasActivePlan() bool

HasActivePlan reports whether a non-empty todo list is present.

func (*SessionManager) HasPendingInterrupt

func (s *SessionManager) HasPendingInterrupt() bool

HasPendingInterrupt reports whether any interrupt is still awaiting a client payload.

func (*SessionManager) LoadInterruptsJSON

func (s *SessionManager) LoadInterruptsJSON(pendingJSON, resolvedJSON []byte) error

LoadInterruptsJSON restores interrupt maps from checkpoint JSON blobs.

func (*SessionManager) LoadUserAndPlanState

func (s *SessionManager) LoadUserAndPlanState(state map[string]any)

LoadUserAndPlanState hydrates user State and plan from checkpoint RuntimeState. Reserved keys (including legacy _search_namespace) are not left as user keys.

func (*SessionManager) PendingInterrupt

func (s *SessionManager) PendingInterrupt(id string) (interrupt.Interrupt, bool)

PendingInterrupt returns an open interrupt for id if any.

func (*SessionManager) Plan

func (s *SessionManager) Plan() *PlanStore

Plan returns the plan module. Never nil after NewSessionManager.

func (*SessionManager) ReturnInterrupt

func (s *SessionManager) ReturnInterrupt(id string, result []byte) (interrupt.Interrupt, error)

ReturnInterrupt resolves a parked interrupt (session-scoped; no turn bus needed).

func (*SessionManager) SnapshotDurable

func (s *SessionManager) SnapshotDurable() (runtimeState map[string]any, pending, resolved interruptMap)

SnapshotDurable copies user state, plan modules, and interrupt maps for checkpointing. Interrupts are deep-cloned so marshal does not race live maps. Reserved plan keys in userState are never exported as user keys; plan is written via PlanStore.ExportInto.

func (*SessionManager) StateDelete

func (s *SessionManager) StateDelete(key string)

StateDelete removes a host/tool state value without a turn Runtime.

func (*SessionManager) StateGet

func (s *SessionManager) StateGet(key string) (any, bool)

StateGet returns a host/tool state value without a turn Runtime.

func (*SessionManager) StateSet

func (s *SessionManager) StateSet(key string, value any)

StateSet stores a host/tool state value without a turn Runtime.

type Todo

type Todo = streaming.Todo

Todo is an alias for the public streaming plan item type.