|
| 1 | +Here is the English translation of the specification document: |
| 2 | + |
| 3 | +--- |
| 4 | + |
| 5 | +# Goal Feature Breakdown |
| 6 | + |
| 7 | +This document breaks down the goal mode capabilities in `agent-core` into three distinct parts: |
| 8 | + |
| 9 | +1. **Core Workflow:** Essential runtime logic without which goal mode cannot run. |
| 10 | +2. **Metrics / Token Limits:** Makes goals measurable, limitable, and auditable. |
| 11 | +3. **User Interaction:** Allows users to safely initiate, understand, control, and resume goals. |
| 12 | + |
| 13 | +## 1. Core Workflow |
| 14 | + |
| 15 | +The core workflow forms the operational backbone of goal mode. It handles creating structured goals, maintaining the state machine, chaining regular turns into autonomous multi-turn execution, and enabling the model to transition or park goals via machine-readable signals. |
| 16 | + |
| 17 | +### Goal States |
| 18 | + |
| 19 | +The same main agent can hold at most **one** current goal at a time. A goal is not arbitrary chat text, but a structured state held by the runtime—containing at least the objective, optional completion criteria, current status, stop reason, and run metrics. |
| 20 | + |
| 21 | +States fall into four categories: |
| 22 | + |
| 23 | +- `active`: Currently being driven by the goal driver. Only this state automatically triggers the next turn. |
| 24 | +- `paused`: Temporarily halted while retaining the goal. Typically caused by user pause, user interruption, post-process recovery degradation, or provider/runtime errors. Resumable. |
| 25 | +- `blocked`: Confronted with a real blocker while retaining the goal. Typically caused by the model determining that external input is needed, the goal cannot be completed as currently stated, a budget limit has been reached, or a prompt hook has blocked execution. Resumable. |
| 26 | +- `complete`: A transient completion state. The runtime emits a completion event and immediately clears the goal; it is not persisted long-term. |
| 27 | + |
| 28 | +There is no `cancelled` state. Canceling simply clears the goal and instructs the model to ignore prior active reminders regarding that goal. |
| 29 | + |
| 30 | +### Creation and Replacement |
| 31 | + |
| 32 | +When creating a goal, the runtime must validate that the objective is neither empty nor excessively long. If an `active`, `paused`, or `blocked` goal already exists, new goal creation is rejected by default to prevent silent overwrites. A new goal replaces an existing one only when the user or caller explicitly requests replacement, in which case the old goal is cleared first. |
| 33 | + |
| 34 | +Upon creation, the new goal enters `active` status, is saved to persistent records, and triggers a goal update event. |
| 35 | + |
| 36 | +### Multi-Turn Driver |
| 37 | + |
| 38 | +The goal driver is responsible for progressing an `active` goal across continuous turns: |
| 39 | + |
| 40 | +- If a goal is already `active` at the start of a turn, execution enters the goal driver. |
| 41 | +- If the model creates a goal within a standard turn, or resumes a `paused`/`blocked` goal to `active`, the goal driver takes over execution after the current turn ends. |
| 42 | +- The driver executes only one standard turn at a time. |
| 43 | +- After each turn completes, the driver checks the goal status. |
| 44 | +- If the goal remains `active`, the runtime automatically appends a continuation prompt and starts the next turn. |
| 45 | +- If the goal transitions to `paused`, `blocked`, or is cleared, the driver stops. |
| 46 | + |
| 47 | +If the model does not call a status update tool and the goal remains `active`, the runtime continues to the next turn. The model cannot complete a goal merely by stating "done" in natural language; it must emit a structured status signal. |
| 48 | + |
| 49 | +### Goal Injection |
| 50 | + |
| 51 | +At the boundaries of each goal turn, the runtime injects the current goal state into the context. Injected content includes: |
| 52 | + |
| 53 | +- Notification that the session is currently in goal mode. |
| 54 | +- The objective and completion criteria. |
| 55 | +- Explicit notice that goal text is user-supplied data and must not override system/developer instructions, tool schemas, permission rules, or host controls. |
| 56 | +- Current status and progress. |
| 57 | +- Guidance for the model to perform a concise self-review and execute one coherent, manageable slice of work. |
| 58 | +- Instructions to directly mark simple, already-completed, impossible, unsafe, or contradictory goals as `complete` or `blocked` within the same turn. |
| 59 | +- Guidance to mark `complete` only when all requirements are met, verification passes, and no further useful steps remain. |
| 60 | +- Instructions to mark `blocked` when progress is halted by external dependencies or required user input. |
| 61 | +- Instructions not to mark `complete` if only planning, summarizing, initial drafting, or partial execution has occurred. |
| 62 | + |
| 63 | +Goal injection occurs strictly at turn/continuation boundaries rather than at every model step. This prevents context bloat and preserves prompt cache efficiency. |
| 64 | + |
| 65 | +Injections for `paused` and `blocked` goals are lighter: |
| 66 | + |
| 67 | +- `paused`: Reminds the model that the goal exists but should not proceed autonomously unless the user explicitly requests continuation. |
| 68 | +- `blocked`: Reminds the model that the goal is blocked and paused, unless the user addresses the blocker or requests a resume. |
| 69 | + |
| 70 | +### Continuation Prompt |
| 71 | + |
| 72 | +When a goal remains `active`, the runtime appends a system-triggered input equivalent to "continue working toward the current active goal." Beyond simply driving execution, it prompts the model to re-evaluate at each turn: |
| 73 | + |
| 74 | +- Whether the goal is already complete. |
| 75 | +- Whether a genuine blocker has been encountered. |
| 76 | +- Whether it should complete a reasonable slice of work before yielding to the next turn. |
| 77 | +- Whether it should avoid diverging or starting unrelated work. |
| 78 | +- Whether to refrain from asking the user for input unless genuinely blocked. |
| 79 | + |
| 80 | +### Completion, Blocking, and Pausing |
| 81 | + |
| 82 | +The model controls the goal lifecycle through structured status updates: |
| 83 | + |
| 84 | +- `complete`: Objective satisfied; runtime emits a completion event and clears the goal. |
| 85 | +- `blocked`: Real blocker encountered; runtime retains the goal and halts autonomous progression. |
| 86 | +- `paused`: Goal temporarily set aside; runtime retains the goal and halts autonomous progression. |
| 87 | +- `active`: Resumes a `paused` or `blocked` goal. |
| 88 | + |
| 89 | +Status update tool inputs should remain narrow, expressing only machine state. The model provides completion summaries or blocking reasons to the user in subsequent conversational output. |
| 90 | + |
| 91 | +When the model marks a goal `complete`, the runtime grants one final wrap-up turn for the model to generate a brief summary detailing what was accomplished and verified. |
| 92 | + |
| 93 | +When the model marks a goal `blocked`, the runtime similarly grants a wrap-up turn to explain the specific blocker and what inputs or changes are required to proceed. |
| 94 | + |
| 95 | +If the current turn has exhausted its step budget, the runtime should avoid forcing an extra wrap-up step, preventing "failed to generate summary" from becoming a turn-level failure. |
| 96 | + |
| 97 | +### Error Parking |
| 98 | + |
| 99 | +Goal mode treats technical execution failures as recoverable parking events: |
| 100 | + |
| 101 | +- User interrupts current turn: goal transitions to `paused`. |
| 102 | +- Provider rate limit: goal transitions to `paused`. |
| 103 | +- Provider connection, authentication, or API errors: goal transitions to `paused`. |
| 104 | +- Model configuration errors: goal transitions to `paused`. |
| 105 | +- Runtime exceptions: goal transitions to `paused`. |
| 106 | +- Provider safety filters: goal transitions to `paused`. |
| 107 | + |
| 108 | +Conversely, business logic, rules, or external blockers trigger `blocked`: |
| 109 | + |
| 110 | +- Prompt hooks blocking the goal. |
| 111 | +- Model determining it cannot proceed. |
| 112 | +- Budget exhausted. |
| 113 | +- Requirement for new conditions from the user or external systems. |
| 114 | + |
| 115 | +### Persistence and Recovery |
| 116 | + |
| 117 | +Goal creation, updates, completion, blocking, and clearing must be written to persistent records. Upon session restoration, the runtime uses these records to reconstruct the goal. |
| 118 | + |
| 119 | +If a restored goal was previously `active`, it must not automatically resume execution; instead, it is downgraded to `paused`. Active turns from prior processes cannot remain alive, and auto-resuming risks silently consuming resources after a restart. |
| 120 | + |
| 121 | +`paused` and `blocked` states are preserved as-is. `complete` states do not persist long-term, as completed goals are cleared. |
| 122 | + |
| 123 | +When a session is forked, the new session does not inherit the source session's goal, and the model is instructed not to pursue the old goal. |
| 124 | + |
| 125 | +--- |
| 126 | + |
| 127 | +## 2. Metrics / Token Limits |
| 128 | + |
| 129 | +This section makes goals measurable, limitable, and auditable. Without it, goals can still execute, but lack control boundaries. |
| 130 | + |
| 131 | +### Execution Metrics |
| 132 | + |
| 133 | +Goal metrics track: |
| 134 | + |
| 135 | +- Continuation turn count. |
| 136 | +- Token consumption. |
| 137 | +- Active wall-clock duration. |
| 138 | + |
| 139 | +Metrics accumulate only while the goal is `active`. Counting halts during `paused` and `blocked` periods. |
| 140 | + |
| 141 | +Turn metrics increment as each goal turn prepares to run. Consequently, if the model marks a goal `complete` during a turn, that turn is included in the final metrics. |
| 142 | + |
| 143 | +Token usage accumulates after each model step completes. Tokens consumed outside an `active` goal are not attributed to goal metrics. Token metrics should update silently in the background rather than refreshing the UI at every step. |
| 144 | + |
| 145 | +Time metrics measure active pursuit duration. Timer intervals start upon entering `active` and flush to cumulative totals upon leaving `active`; pause/resume cycles create distinct active intervals. |
| 146 | + |
| 147 | +### Budgets |
| 148 | + |
| 149 | +Goal budgets support: |
| 150 | + |
| 151 | +- Turn budget. |
| 152 | +- Token budget. |
| 153 | +- Wall-clock time budget. |
| 154 | + |
| 155 | +Budgets are omitted by default and set only when explicitly defined by the user (e.g., "max 20 turns," "under 500k tokens," "within 30 minutes"). Vague requests (e.g., "as fast as possible," "don't take too long") must not trigger budget settings, nor should the model invent budgets arbitrarily. |
| 156 | + |
| 157 | +Time budgets require valid ranges; excessively short or long durations are rejected. Turn and token budgets must be normalized to positive integers. |
| 158 | + |
| 159 | +### Hard Budget Stops |
| 160 | + |
| 161 | +Budget checks occur before and after each goal turn. Token budgets are also evaluated after individual model steps to prevent execution from continuing after an overrun. |
| 162 | + |
| 163 | +Once a budget limit is reached, the runtime immediately marks the goal `blocked` with a reason indicating budget exhaustion. This `blocked` state remains resumable, though resuming without altering the budget may trigger an immediate re-block. |
| 164 | + |
| 165 | +### Budget Nudging and Final Metrics |
| 166 | + |
| 167 | +When budget usage is low, system prompts encourage steady progress. When any budget metric exceeds 75% utilization, prompts shift focus toward convergence, advising against initiating optional or tangential work. |
| 168 | + |
| 169 | +Final response prompts for `complete` and `blocked` states should incorporate summary metrics (e.g., turns worked, elapsed time, tokens consumed). UI events should similarly include current metric snapshots and event types. |
| 170 | + |
| 171 | +Telemetry may record events such as goal creation, budget allocation, continuations, status changes, and clearing, but must exclude sensitive payload data like raw objective text or stop reasons. |
| 172 | + |
| 173 | +--- |
| 174 | + |
| 175 | +## 3. User Interaction |
| 176 | + |
| 177 | +This section enables users to safely initiate, observe, control, and recover goals. Without it, the runtime can function, but lacks appropriate UX and security boundaries. |
| 178 | + |
| 179 | +### Lifecycle Control |
| 180 | + |
| 181 | +Users retain direct operational control over goals: |
| 182 | + |
| 183 | +- Create |
| 184 | +- Inspect |
| 185 | +- Pause |
| 186 | +- Resume |
| 187 | +- Cancel |
| 188 | + |
| 189 | +These actions execute directly without requiring model turn processing. Pausing moves an `active` goal to `paused`; resuming transitions a `paused` or `blocked` goal back to `active`; canceling immediately clears the goal. |
| 190 | + |
| 191 | +Resuming clears previous stop reasons to signify a fresh attempt. Sending standard user messages does not automatically resume `paused` or `blocked` goals. |
| 192 | + |
| 193 | +### Confirmation for Model-Initiated Goals |
| 194 | + |
| 195 | +The model may create goals on behalf of the user, but only when explicitly requested (e.g., commands to start autonomous work) or mandated by host goal-intake prompts. Standard conversational requests must not be unilaterally upgraded into goals by the model. |
| 196 | + |
| 197 | +When the model invokes `CreateGoal` under non-auto permission modes, a user confirmation prompt must trigger. The confirmation UI allows the user to select the execution permission mode for the session. If the user declines, the goal is not created. |
| 198 | + |
| 199 | +Read/update control tools (`GetGoal`, `SetGoalBudget`, `UpdateGoal`) modify runtime goal state and can generally receive broader auto-approval. File writes, shell executions, and sensitive path access remain governed by standard host permission systems. |
| 200 | + |
| 201 | +### Context Prompts After Pause, Block, or Cancel |
| 202 | + |
| 203 | +- **Paused:** Context prompts state that a goal exists but must not proceed autonomously unless explicitly requested by the user. |
| 204 | +- **Blocked:** Context prompts state that the goal is blocked and halted, offering to assist with unblocking if requested, but otherwise defaulting to handling standard user prompts. |
| 205 | +- **Cancelled:** Appends instructions directing the model to ignore active reminders for the prior goal, preventing stale context from prompting continued work on cancelled targets. |
| 206 | + |
| 207 | +### User Responses on Complete and Blocked |
| 208 | + |
| 209 | +- **On Complete:** Goal is cleared; the model provides a concise completion summary detailing results and verifications performed. |
| 210 | +- **On Blocked:** Goal is retained; the model provides a concise explanation of the blocker, outlining required inputs, permissions, external conditions, or adjustments needed to continue. |
| 211 | + |
| 212 | +### Tool Exposure and Isolation |
| 213 | + |
| 214 | +Goal management tools are restricted to the **main agent**. Subagents must not directly create, resume, or terminate primary goals. |
| 215 | + |
| 216 | +When no goal is active, `UpdateGoal` and `SetGoalBudget` are hidden from the model schema and exposed only when a goal exists. |
| 217 | + |
| 218 | +Internal Goal IDs are not exposed to the model, as they serve strictly internal runtime/UI routing needs without user-facing semantic value. |
| 219 | + |
| 220 | +### Goal Authoring Assistance |
| 221 | + |
| 222 | +`write-goal` capabilities help refine raw user intent into actionable goal contracts. A well-defined goal explicitly identifies: |
| 223 | + |
| 224 | +- **End State:** What conditions must hold true upon completion. |
| 225 | +- **Proof:** What observable evidence verifies completion. |
| 226 | +- **Boundaries:** Permissible scope and explicitly prohibited actions. |
| 227 | +- **Loop:** Strategy for iterative execution. |
| 228 | +- **Stop Rule:** Specific conditions triggering a halt and report, avoiding brute-force iteration. |
| 229 | + |
| 230 | +Budgets are opt-in and should neither be included by default nor hardcoded as turn caps into the objective text itself. |
| 231 | + |
| 232 | +### UI and Session Semantics |
| 233 | + |
| 234 | +Goal creation, pausing, resuming, blocking, completion, and clearing trigger `goal updated` events. Distinction is maintained between lifecycle transitions and completion events: completion is a terminal event after which the goal snapshot clears to `null`. `blocked` and `paused` states preserve their snapshots, allowing UI interfaces to display resumable goals. |
| 235 | + |
| 236 | +During session restoration, active goals degrade to `paused` to prevent automatic background execution upon restart. Session forks do not inherit goals, and the model is instructed not to pursue goals originating from the source session. |
0 commit comments