Documentation
¶
Overview ¶
Package goal implements the persistent goal system. Mirrors Codex's ThreadGoal / ThreadGoalStatus from protocol.rs and the goal-management tools (create_goal, get_goal, update_goal).
Index ¶
- Constants
- Variables
- func BudgetLimitPrompt(g *Goal) string
- func ConfigureDefaultStoreBackend(backend Backend)
- func ContinuationPrompt(g *Goal) string
- func IsFinal(s Status) bool
- func ObjectiveUpdatedPrompt(g *Goal) string
- func ValidateObjective(objective string) error
- type Backend
- type Goal
- type SQLiteBackend
- type Status
- type Store
- func (s *Store) Clear(sessionID string)
- func (s *Store) Get(sessionID string) (*Goal, bool)
- func (s *Store) RecordTokenUsage(sessionID string, tokens int64)
- func (s *Store) Set(sessionID, objective string, tokenBudget *int64) *Goal
- func (s *Store) SetBackend(backend Backend)
- func (s *Store) Update(sessionID string, newStatus *Status, newObjective *string) (*Goal, bool)
Constants ¶
const MaxObjectiveChars = 4_000
MaxObjectiveChars mirrors Codex's MAX_THREAD_GOAL_OBJECTIVE_CHARS.
Variables ¶
var ErrGoalNotFound = sql.ErrNoRows
ErrGoalNotFound is returned by persistent backends when a session has no goal.
Functions ¶
func BudgetLimitPrompt ¶
BudgetLimitPrompt returns the prompt injected when a goal's token budget is exhausted. Mirrors Codex's budget_limit_prompt() + budget_limit.md template.
func ConfigureDefaultStoreBackend ¶ added in v1.2.0
func ConfigureDefaultStoreBackend(backend Backend)
ConfigureDefaultStoreBackend wires persistent storage into the process-level goal store used by the built-in goal tools.
func ContinuationPrompt ¶
ContinuationPrompt returns the hidden prompt injected after each turn of an active goal. Mirrors Codex's continuation_prompt() + continuation.md template.
func ObjectiveUpdatedPrompt ¶
ObjectiveUpdatedPrompt returns the prompt injected when a goal's objective is edited mid-session. Mirrors Codex's objective_updated_prompt() + objective_updated.md.
func ValidateObjective ¶
ValidateObjective returns an error when the objective violates the Codex constraints.
Types ¶
type Backend ¶ added in v1.2.0
type Backend interface {
SaveGoal(*Goal) error
LoadGoal(sessionID string) (*Goal, error)
DeleteGoal(sessionID string) error
}
Backend persists goals behind Store. Implementations must be safe for repeated writes of the same session ID.
type Goal ¶
type Goal struct {
SessionID string `json:"session_id"`
Objective string `json:"objective"`
Status Status `json:"status"`
TokenBudget *int64 `json:"token_budget,omitempty"`
TokensUsed int64 `json:"tokens_used"`
TimeUsedSeconds int64 `json:"time_used_seconds"`
CreatedAt int64 `json:"created_at"`
UpdatedAt int64 `json:"updated_at"`
// contains filtered or unexported fields
}
Goal mirrors Codex's ThreadGoal struct (protocol.rs:3651). Keyed by SessionID in the Store.
func (*Goal) IsOverBudget ¶
IsOverBudget returns true when the token budget is exhausted.
func (*Goal) RemainingTokens ¶
RemainingTokens returns how many tokens are left in the budget, or -1 if unbounded.
type SQLiteBackend ¶ added in v1.2.0
type SQLiteBackend struct {
// contains filtered or unexported fields
}
SQLiteBackend stores goals in the shared runtime SQLite database.
func NewSQLiteBackend ¶ added in v1.2.0
func NewSQLiteBackend(database *dbpkg.DB) (*SQLiteBackend, error)
NewSQLiteBackend creates a goal backend on top of the shared DB module.
func OpenSQLiteBackend ¶ added in v1.2.0
func OpenSQLiteBackend(path string) (*SQLiteBackend, error)
OpenSQLiteBackend opens a SQLite-backed goal store.
func (*SQLiteBackend) Close ¶ added in v1.2.0
func (b *SQLiteBackend) Close() error
Close releases the owned database handle.
func (*SQLiteBackend) DeleteGoal ¶ added in v1.2.0
func (b *SQLiteBackend) DeleteGoal(sessionID string) error
DeleteGoal removes a persisted goal for a session.
func (*SQLiteBackend) LoadGoal ¶ added in v1.2.0
func (b *SQLiteBackend) LoadGoal(sessionID string) (*Goal, error)
LoadGoal returns the persisted goal for a session.
func (*SQLiteBackend) SaveGoal ¶ added in v1.2.0
func (b *SQLiteBackend) SaveGoal(g *Goal) error
SaveGoal upserts the goal row for a session.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store is the in-memory goal registry keyed by SessionID. Thread-safe. Mirrors Codex's server-side goal state per thread.
func GetDefaultStore ¶
func GetDefaultStore() *Store
GetDefaultStore returns the process-level singleton GoalStore.
func (*Store) Get ¶
Get returns the current goal for sessionID, or false if none.
This is a pure read: it does not write to the backend. TimeUsedSeconds is always derived from CreatedAt/startedAt at read time (LoadGoal recomputes it the same way on a fresh load), so there is nothing to persist here - it never was a stored column. Get used to re-save the goal on every call purely to refresh this already-derived field; with a persistent backend wired in, that turned every read into a synchronous SQLite write, and this is called multiple times per agent turn whenever a goal is active (see internal/agent/runner.go's goal-continuation checks).
func (*Store) RecordTokenUsage ¶
RecordTokenUsage adds tokens to the running counter and auto-transitions to budgetLimited when the budget is exceeded. Called by the runner after each turn.
func (*Store) Set ¶
Set creates or replaces the goal for sessionID. Always sets status=active and resets usage counters. Mirrors Codex's ThreadGoalSetParams (new objective → create).
Returns a clone, not the Store's internal pointer - a caller mutating the returned Goal's exported fields directly (instead of going through Update/RecordTokenUsage) would otherwise corrupt Store state without holding s.mu, a data race independent of whether it actually happens today. Same reasoning applies to Get and Update below.
func (*Store) SetBackend ¶ added in v1.2.0
SetBackend installs optional persistent storage for this goal store.
Source Files