goal

package
v0.1.2 Latest Latest
Warning

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

Go to latest
Published: Nov 13, 2026 License: MIT Imports: 4 Imported by: 0

Documentation

Overview

Goal failure classes and block reasons match upstream goal (review fix R06). Upstream types.ts defines active/paused/blocked/complete and GoalBlockReason; domain.ts defines nine stable routing codes. Callers route on ErrorCode, not message text. GoalError supports Go error chaining through Cause, and blocked goals must carry a nonempty GoalBlockReason.

Package goal implements goal state, automatic rounds, and six goal_* tools, matching core/goal. State persists as goal/change events with monotonic CAS revisions. RoundDriver continues active goals on turn-stopping until completion or maxRounds. Tools list goals, set phase/description/max rounds, add blockers, and report blockers; reporting a blocker concludes the turn.

Goal transitions follow upstream source-phase allowlists. Valid destination values alone are insufficient: complete is terminal and only active can become paused or blocked. Invalid transitions return GOAL_INVALID_TRANSITION.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CanTransition

func CanTransition(from, to Phase) bool

CanTransition validates transitions:

  • active to active, paused, blocked, or complete;
  • paused or blocked to active or complete;
  • complete is terminal.

Types

type ErrorCode

type ErrorCode string

ErrorCode is a stable goal-domain routing code matching GoalErrorCode upstream.

const (
	ErrorAgentNotLive       ErrorCode = "GOAL_AGENT_NOT_LIVE"
	ErrorNotFound           ErrorCode = "GOAL_NOT_FOUND"
	ErrorAlreadyExists      ErrorCode = "GOAL_ALREADY_EXISTS"
	ErrorStaleRevision      ErrorCode = "GOAL_STALE_REVISION"
	ErrorInvalidObjective   ErrorCode = "GOAL_INVALID_OBJECTIVE"
	ErrorInvalidMaxRounds   ErrorCode = "GOAL_INVALID_MAX_ROUNDS"
	ErrorInvalidBlockReason ErrorCode = "GOAL_INVALID_BLOCK_REASON"
	ErrorInvalidEdit        ErrorCode = "GOAL_INVALID_EDIT"
	ErrorInvalidTransition  ErrorCode = "GOAL_INVALID_TRANSITION"
)

The nine upstream stable error codes.

type Goal

type Goal struct {
	ID          string   `json:"id"`
	Phase       Phase    `json:"phase"`
	Description string   `json:"description"`
	MaxRounds   int      `json:"maxRounds"`
	Revision    uint64   `json:"revision"`
	Blockers    []string `json:"blockers,omitempty"`
	// BlockReason exists only for blocked goals, matching GoalSnapshot.blockedReason.
	BlockReason *GoalBlockReason `json:"blockedReason,omitempty"`
}

Goal holds runtime goal state.

func FromLog

func FromLog(sl *session.SessionLog) (Goal, bool)

FromLog derives the latest goal using monotonically increasing CAS revisions.

func NewGoal

func NewGoal(id, desc string, maxRounds int) Goal

NewGoal creates a goal starting at revision one.

type GoalBlockReason

type GoalBlockReason struct {
	// Code is a stable lower-kebab-case category.
	Code string `json:"code"`
	// Message is a nonempty explanation for users and models.
	Message string `json:"message"`
}

GoalBlockReason is the stable reason a goal is blocked.

func NewBlockReason

func NewBlockReason(code, message string) (GoalBlockReason, bool)

NewBlockReason constructs a reason and validates nonempty code and message.

type GoalError

type GoalError struct {
	Code    ErrorCode `json:"code"`
	Message string    `json:"message"`
	Cause   error     `json:"-"`
}

GoalError carries a stable goal-domain code.

func FromError

func FromError(err error) *GoalError

FromError preserves GoalError values and classifies other errors as unknown.

func NewGoalError

func NewGoalError(code ErrorCode, message string, cause error) *GoalError

NewGoalError constructs an error with a stable code.

func (*GoalError) Error

func (e *GoalError) Error() string

Error implements error.

func (*GoalError) Unwrap

func (e *GoalError) Unwrap() error

Unwrap exposes Cause to errors.Is and errors.As.

type GoalToolset

type GoalToolset struct {
	// contains filtered or unexported fields
}

GoalToolset contains goal tools.

func NewGoalToolset

func NewGoalToolset(sl *session.SessionLog) *GoalToolset

NewGoalToolset creates a goal toolset.

func (*GoalToolset) Tools

func (g *GoalToolset) Tools() []*tools.Tool

Tools returns all six tools for registration in the M23 pipeline.

type Phase

type Phase string

Phase identifies a goal phase.

const (
	PhaseActive   Phase = "active"
	PhasePaused   Phase = "paused"
	PhaseBlocked  Phase = "blocked"
	PhaseComplete Phase = "complete"
)

The four upstream goal phases.

func (Phase) Valid

func (p Phase) Valid() bool

Valid reports whether the phase is one of the four valid GoalPhase values.

type RoundDriver

type RoundDriver struct {
	// contains filtered or unexported fields
}

RoundDriver decides whether active goals continue at turn-stopping.

func NewRoundDriver

func NewRoundDriver() *RoundDriver

NewRoundDriver creates a continuation driver.

func (*RoundDriver) OnTurnStopping

func (d *RoundDriver) OnTurnStopping(sl *session.SessionLog, round int) bool

OnTurnStopping reports whether another round should start when a turn stops.

func (*RoundDriver) WaitRound

func (d *RoundDriver) WaitRound(ctx context.Context) (int, error)

WaitRound waits for continuation or context cancellation/timeout.

Jump to

Keyboard shortcuts

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