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 SessionCloser
- 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. 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
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 SessionCloser ¶ added in v0.47.0
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.