Documentation
¶
Overview ¶
Package state maps relay conversation keys to ACP sessions and stable cwd dirs.
Index ¶
- Constants
- func ReadMetas(stateDir string) (map[string][]byte, error)
- func WriteMeta(stateDir, key string, data []byte) error
- type Agent
- type Config
- type CwdFor
- type Manager
- func (m *Manager) Agent() Agent
- func (m *Manager) Cancel(ctx context.Context, key string)
- func (m *Manager) Checkpoint(key string) (string, error)
- func (m *Manager) Close() error
- func (m *Manager) GCOnce()
- func (m *Manager) GetOrCreate(ctx context.Context, key string, sink client.SessionUpdateSink) (*Session, error)
- func (m *Manager) Known(key string) bool
- func (m *Manager) Len() int
- func (m *Manager) Live(key string) (sid acp.SessionId, lastUsed time.Time, ok bool)
- func (m *Manager) Reset(key string) error
- func (m *Manager) Run(ctx context.Context)
- func (m *Manager) SetCheckpoint(key, value string) error
- func (m *Manager) StateDir() string
- func (m *Manager) TakePendingSystemPrompt(s *Session) string
- func (m *Manager) Touch(s *Session)
- type Session
- type SystemPromptResumer
Constants ¶
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
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.
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 ¶
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 (*Manager) Checkpoint ¶ added in v0.2.6
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) 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
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) Live ¶ added in v0.21.0
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
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) SetCheckpoint ¶ added in v0.2.6
SetCheckpoint persists value as the opaque checkpoint for key under its cwd, atomically (write-temp + rename). Allocates the cwd if absent.
func (*Manager) TakePendingSystemPrompt ¶
TakePendingSystemPrompt returns inline fallback text for the next user prompt and clears the pending flag. Call with s.Mu held.
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 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.