Goal State Machine

Goal State Machine

In One Sentence

The core of an Agent’s “planning capability” is a state machine: a Goal has a lifecycle and transitions from one phase to the next; the Agent drives it with round continuation until it is reached or blocked.

The Four States (Aligned with the Official)

StateMeaningAuto round continuation
activeIn progress✅ Yes (RoundDriver continues)
pausedPaused❌ No (waiting to resume)
blockedBlocked (blocker unresolved)❌ No
completeCompleted❌ No

Stable Error Codes

Nine stable GOAL_* error codes aligned with the official error.ts (e.g. GOAL_INVALID_MAX_ROUNDS, GOAL_STALE_REVISION, GOAL_NOT_FOUND). Errors are routed by stable string, never by parsing message text.

In Dsh-Go 

1ts := goal.NewGoalToolset(sl) // bound to the session log
2// 6 tools: goal_list / goal_set_phase / goal_set_description
3//         / goal_set_max_rounds / goal_add_blocker / goal_report_blocker

The example shows how a stable error code is expressed cleanly:

1if _, err := call(ts, "goal_set_max_rounds", map[string]any{"maxRounds": float64(-1)}); err != nil {
2    if ge, ok := err.(*goal.GoalError); ok {
3        fmt.Println(ge.Code) // GOAL_INVALID_MAX_ROUNDS
4    }
5}

Source Reference

  • pkg/goal/goal.go — the Goal state machine and its 6 tools
  • pkg/goal/errors.go — 9 stable error codes + GoalError
  • Runnable example: examples/tutorial step 3

Next Steps