Documentation
¶
Index ¶
- Constants
- func ClassifyBadID(id string) string
- func GenerateAgentID(existingIDs []string) (string, error)
- func IsValidAgentID(id string) bool
- func ParseAgentID(id string) (string, error)
- type Instance
- type Store
- func (s *Store) Add(inst *Instance) error
- func (s *Store) Count() int
- func (s *Store) Get(agentID string) (*Instance, error)
- func (s *Store) IncrementPrimeCallCount(agentID string) (*Instance, bool, error)
- func (s *Store) List() ([]*Instance, error)
- func (s *Store) Prune() (int, error)
- func (s *Store) Update(inst *Instance) error
Constants ¶
const ( // ExcessivePrimeThreshold is the number of prime calls per instance before warning. // Agents should typically call prime once at session start. Multiple calls suggest // context compaction issues or agent misconfiguration. ExcessivePrimeThreshold = 5 )
Variables ¶
This section is empty.
Functions ¶
func ClassifyBadID ¶ added in v0.2.0
ClassifyBadID returns a diagnostic message explaining why id is not a valid agent ID. Returns empty string if id is valid or doesn't match a known wrong-format pattern (caller should use generic error).
func GenerateAgentID ¶
GenerateAgentID generates a new unique agent ID checking for collisions against existing IDs in the store.
The ID format is Ox<4-char> where chars are [0-9A-Za-z]. This provides 62^4 = 14,776,336 possible combinations.
Examples:
- GenerateAgentID([]string{}) -> "OxA1b2"
- GenerateAgentID([]string{"OxA1b2"}) -> "OxC3d4" (different ID)
- GenerateAgentID([]string{"OxA1b2", ...}) -> error if can't find unique ID after 10 retries
func IsValidAgentID ¶
IsValidAgentID checks if a string is a valid agent ID format.
Valid format requirements:
- Must start with "Ox"
- Must be exactly 6 characters total
- Suffix (4 chars) must be alphanumeric [0-9A-Za-z]
Examples:
- IsValidAgentID("OxA1b2") -> true
- IsValidAgentID("Ox1234") -> true
- IsValidAgentID("OxZzZz") -> true
- IsValidAgentID("ox1234") -> false (wrong prefix)
- IsValidAgentID("OX1234") -> false (wrong prefix)
- IsValidAgentID("Ox123") -> false (too short)
- IsValidAgentID("Ox12345") -> false (too long)
- IsValidAgentID("Ox12#4") -> false (invalid character)
- IsValidAgentID("") -> false
- IsValidAgentID("random") -> false
func ParseAgentID ¶
ParseAgentID extracts the 4-char suffix from an agent ID. Returns error if format is invalid.
Examples:
- ParseAgentID("OxA1b2") -> "A1b2", nil
- ParseAgentID("Ox1234") -> "1234", nil
- ParseAgentID("ox1234") -> "", error (invalid prefix)
- ParseAgentID("Ox123") -> "", error (wrong length)
- ParseAgentID("") -> "", error (invalid format)
Types ¶
type Instance ¶
type Instance struct {
AgentID string `json:"agent_id"` // "Ox" + 4-char identifier (e.g., "Oxa7b3")
ServerSessionID string `json:"oxsid"` // Full server-generated session ID (JSON: oxsid for compat)
CreatedAt time.Time `json:"created_at"`
ExpiresAt time.Time `json:"expires_at"`
// Coding agent metadata
AgentType string `json:"agent_type,omitempty"` // claude-code, droid, cursor, windsurf
AgentVer string `json:"agent_ver,omitempty"` // Agent version (e.g., "1.0.42")
Model string `json:"model,omitempty"` // Model used (e.g., "claude-opus-4-5")
// Usage tracking
PrimeCallCount int `json:"prime_call_count,omitempty"` // number of times prime was called
}
Instance represents an agent instance with server-assigned identifiers.
func (*Instance) IsPrimeExcessive ¶
IsPrimeExcessive returns true if prime has been called more than the threshold. This indicates potential context compaction issues or agent misconfiguration.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store manages instance persistence using JSONL format
Design decision: Per-user instance directories Rationale: Multiple git users (or pair programmers) can work on the same repo without instance conflicts. Path: .sageox/agent_instances/<user-slug>/agent_instances.jsonl
func NewStore ¶
NewStore initializes an instance store for the given project root. Uses "anonymous" as the user slug for backward compatibility. Prefer NewStoreForUser when git identity is available.
func NewStoreForUser ¶
NewStoreForUser initializes an instance store for a specific user. The userSlug should be generated from GitIdentity.Slug() for per-user isolation. Path: .sageox/agent_instances/<user-slug>/agent_instances.jsonl
func (*Store) Get ¶
Get retrieves an instance by agent ID, pruning expired instances during read.
Design decision: Prune on read Rationale: Amortizes cleanup cost; ensures Get() never returns expired instances without extra syscall. Triggers async compaction if thresholds exceeded.
func (*Store) IncrementPrimeCallCount ¶
IncrementPrimeCallCount increments the prime call count for an instance. Returns the updated instance and whether the prime count is now excessive.
Source Files