state

package
v0.41.0 Latest Latest
Warning

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

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

Documentation

Overview

Package state maps relay conversation keys to ACP sessions and stable cwd dirs.

Index

Constants

View Source
const MetaFile = ".conv.json"

MetaFile is the per-conversation metadata file stored in <StateDir>/convs/<key>/. Its content is opaque to the kit: the relay owns its format.

It exists so a relay can rebuild its own key → conversation index from the conversation dirs alone, when its index file is lost. It is keyed by the conversation key, so it lives under the default layout even when a custom CwdFor sends the agent's cwd elsewhere: it is relay state, not agent state.

Variables

This section is empty.

Functions

func ReadMetas added in v0.39.0

func ReadMetas(stateDir string) (map[string][]byte, error)

ReadMetas returns the metadata of every conversation dir under <StateDir>/convs that has one, by key. A missing convs dir is an empty result. A dir without a metadata file is left out of the result. An unreadable metadata file is an error, because a silent gap is the failure a restore must not hide.

func WriteMeta added in v0.39.0

func WriteMeta(stateDir, key string, data []byte) error

WriteMeta stores data as the metadata of key, atomically (write-temp + rename). It creates the conversation dir if absent. It does not need a Manager, so a relay can call it before the Manager exists.

Types

type Agent

type Agent interface {
	Caps() client.Caps
	NewSession(ctx context.Context, cwd string, sink client.SessionUpdateSink, systemPromptBlocks []acp.ContentBlock) (acp.SessionId, error)
	ListSessions(ctx context.Context, cwd string) ([]client.SessionInfo, error)
	ResumeSession(ctx context.Context, cwd string, sid acp.SessionId, sink client.SessionUpdateSink) error
	Cancel(ctx context.Context, sid acp.SessionId) error
	DropSession(sid acp.SessionId)
	RebindSink(sid acp.SessionId, sink client.SessionUpdateSink)
}

Agent is the subset of *client.AgentProc needed by Manager.

type Config

type Config struct {
	Agent       Agent
	StateDir    string
	IdleTimeout time.Duration // 0 => 30 minutes

	// CwdFor optionally overrides cwd layout. If nil, keys must be single safe
	// path components and are stored under <StateDir>/convs/<key>.
	CwdFor CwdFor

	// SystemPrompt is durable per-session instruction text. If Provider is set,
	// it is called for each new/resumed session and overrides SystemPrompt.
	SystemPrompt         string
	SystemPromptProvider func() string

	// SystemPromptForKey, if set, resolves the durable system prompt per
	// conversation key. It takes precedence over SystemPromptProvider and
	// SystemPrompt and is evaluated at session creation/resume. Use it for
	// per-conversation persona (e.g. a different prompt per Slack channel).
	SystemPromptForKey func(key string) string
}

Config configures a Manager.

type CwdFor

type CwdFor func(stateDir, key string) (string, error)

CwdFor returns and creates the stable cwd for key. A custom CwdFor is responsible for its own path validation and mkdirs. The default stores each key as one safe path component under <StateDir>/convs/<key>.

type Manager

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

Manager owns the key -> session map, stable cwd allocation, best-effort resume, and idle GC. GC drops in-memory sessions but never deletes cwd dirs.

func New

func New(cfg Config) (*Manager, error)

New constructs a Manager. Call Run(ctx) to start idle GC.

func (*Manager) Agent

func (m *Manager) Agent() Agent

Agent returns the underlying ACP agent.

func (*Manager) Cancel

func (m *Manager) Cancel(ctx context.Context, key string)

Cancel sends session/cancel if key has a live session.

func (*Manager) Checkpoint added in v0.2.6

func (m *Manager) Checkpoint(key string) (string, error)

Checkpoint returns the opaque checkpoint string persisted for key, or "" if none has been set. The Manager stores and returns it verbatim; the relay owns its meaning (e.g. a last-processed external event id). Allocates the cwd if absent.

func (*Manager) Close

func (m *Manager) Close() error

Close releases the os.Root handle used by the default cwd allocator.

func (*Manager) GCOnce

func (m *Manager) GCOnce()

GCOnce drops stale in-memory sessions and leaves their cwd dirs intact.

func (*Manager) GetOrCreate

func (m *Manager) GetOrCreate(ctx context.Context, key string, sink client.SessionUpdateSink) (*Session, error)

GetOrCreate returns an existing session for key or creates/resumes one.

func (*Manager) Known added in v0.2.6

func (m *Manager) Known(key string) bool

Known reports whether a session for key already exists — either live in memory or as a persisted cwd on disk. Disk is the source of truth across restarts: the in-memory map is empty after a restart, but cwd dirs survive, so a relay that only follows conversations it has been engaged in can use Known as a restart-stable membership check.

The disk check uses the default cwd layout (<StateDir>/convs/<key>). When a custom CwdFor is configured, Known consults only the in-memory map, since the custom layout's existence semantics are the caller's to define.

func (*Manager) Len

func (m *Manager) Len() int

Len returns the number of live sessions.

func (*Manager) Live added in v0.21.0

func (m *Manager) Live(key string) (sid acp.SessionId, lastUsed time.Time, ok bool)

Live reports key's live ACP session id and when it was last used, without creating a session. ok is false when key has no live session (never started, or reaped by idle GC). It exists for read-only status reports, which must not spawn a session as a side effect.

func (*Manager) Reset added in v0.24.0

func (m *Manager) Reset(key string) error

Reset drops key's live session so the next GetOrCreate starts a NEW one: the resume tier is skipped once, or it would simply reload the session being discarded. The cwd is kept. It never errors; the error return satisfies convo.Resetter.

func (*Manager) Run

func (m *Manager) Run(ctx context.Context)

Run drives idle GC until ctx is cancelled.

func (*Manager) SetCheckpoint added in v0.2.6

func (m *Manager) SetCheckpoint(key, value string) error

SetCheckpoint persists value as the opaque checkpoint for key under its cwd, atomically (write-temp + rename). Allocates the cwd if absent.

func (*Manager) StateDir

func (m *Manager) StateDir() string

StateDir returns the configured state root.

func (*Manager) TakePendingSystemPrompt

func (m *Manager) TakePendingSystemPrompt(s *Session) string

TakePendingSystemPrompt returns inline fallback text for the next user prompt and clears the pending flag. Call with s.Mu held.

func (*Manager) Touch

func (m *Manager) Touch(s *Session)

Touch marks a session as recently used.

type Session

type Session struct {
	Key       string
	SessionID acp.SessionId
	Cwd       string

	// Mu serializes prompt submission for this session. ACP allows one
	// outstanding prompt per session at a time.
	Mu sync.Mutex
	// contains filtered or unexported fields
}

Session holds manager-side state for one ACP session.

Jump to

Keyboard shortcuts

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