state

package
v0.52.0 Latest Latest
Warning

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

Go to latest
Published: Nov 19, 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. When the Agent implements SessionCloser, each stale session is first closed on the agent (errors are logged and ignored) so the agent can free its per-session subprocesses.

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.

type SessionCloser added in v0.47.0

type SessionCloser interface {
	CloseSession(ctx context.Context, sid acp.SessionId) error
}

SessionCloser is optionally implemented by an Agent (as *client.AgentProc does) to free an agent-side session's resources. GCOnce calls it, best-effort, before dropping a stale session.

type SystemPromptResumer added in v0.42.0

type SystemPromptResumer interface {
	ResumeSessionWithSystemPrompt(ctx context.Context, cwd string, sid acp.SessionId, sink client.SessionUpdateSink, systemPromptBlocks []acp.ContentBlock) error
}

SystemPromptResumer is optionally implemented by an Agent to carry the session's system prompt on session/resume. The stable ACP system-prompt capability asks clients to re-send the prompt on every lifecycle request; when the Agent implements this (as *client.AgentProc does), Manager resumes through it. Agents that do not keep working through plain ResumeSession.

Jump to

Keyboard shortcuts

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