@narumitw/pi-goal 0.54.17 → 0.55.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,22 @@
1
1
  # @narumitw/pi-goal
2
2
 
3
+ ## 0.55.1
4
+
5
+ ### Patch Changes
6
+
7
+ - Updated dependencies [cf7b63d]
8
+ - @narumitw/pi-tui-kit@0.70.0
9
+
10
+ ## 0.55.0
11
+
12
+ ### Minor Changes
13
+
14
+ - 2b3d1d2: Add default-off `retryUsageLimits` recovery for recognized provider quota errors. When enabled, Goal retains its identity and workflow ownership in active waiting, then schedules recovery through the settled-idle dispatcher using an applicable public reset hint or a 15-minute fallback. No usage service is required.
15
+
16
+ Only work-free, directly quota-rejected scheduled recovery requests are exempt from automatic-work and no-progress counters. Provider-reported token usage always counts; successful work, partial work, original requests, and native retries retain existing accounting.
17
+
18
+ Recovery can make paid requests and wait indefinitely for billing, credit, or entitlement action. Disabling it cancels pending quota recovery; enabling it does not restart an already stopped Goal. Native retry and ordinary external-wait policies remain unchanged.
19
+
3
20
  ## 0.54.17
4
21
 
5
22
  ### Patch Changes
package/README.md CHANGED
@@ -10,7 +10,7 @@ Explicit completion, blocker, and wait tools give each managed run a clear stopp
10
10
 
11
11
  - Starts and manages one session goal through `/goal` and its status, pause, resume, edit, and clear routes.
12
12
  - Continues exactly once from Pi's settled idle boundary after queued work, retries, and compaction have finished.
13
- - Waits quietly after exhausted retries or unclassified provider errors without adding a retry attempt.
13
+ - Waits quietly after exhausted retries or unclassified provider errors; optional usage-limit recovery can schedule later requests.
14
14
  - Uses explicit `goal_complete`, `goal_blocked`, and `goal_wait` tools with stale-goal guards and evidence requirements.
15
15
  - Renders an accepted `goal_complete` summary as Markdown in the TUI.
16
16
  - Tracks active, paused, blocked, usage-limited, budget-limited, waiting, and complete outcomes separately.
@@ -62,7 +62,8 @@ A missing file uses the defaults without creating it:
62
62
  "automaticTurns": 25,
63
63
  "noProgressTurns": 3
64
64
  },
65
- "rpc": { "enabled": false }
65
+ "rpc": { "enabled": false },
66
+ "retryUsageLimits": false
66
67
  }
67
68
  ```
68
69
 
@@ -71,6 +72,12 @@ The no-progress guard pauses repeated tool-free output.
71
72
  Choose **Unlimited** or **Off** explicitly to disable the corresponding guard; Unlimited requires confirmation and can continue consuming tokens and provider cost.
72
73
  Neither these guards nor an optional token budget is a dollar-cost cap.
73
74
 
75
+ **Retry usage limits** is **Off** by default: recognized quota errors stop the Goal until manual resume.
76
+ Opt in to keep the Goal waiting and attempt recovery after a usable reset hint or a fixed 15-minute fallback, without requiring another extension.
77
+ Recovery can make paid requests and wait indefinitely for billing, credit, or entitlement action; it does not redeem credits or change authentication or settings.
78
+ Only work-free, directly quota-rejected scheduled recovery requests are exempt from automatic-work and no-progress counters; all reported tokens still count.
79
+ See [usage-limit recovery](./docs/settings.md#usage-limit-recovery) before enabling it.
80
+
74
81
  Menu saves apply immediately, run in order, preserve unknown fields, and publish atomically.
75
82
  Manual edits apply at session start or `/reload`.
76
83
  Invalid settings remain untouched, use defaults, and make the TUI Settings screen read-only until repaired and reloaded.
@@ -89,8 +96,8 @@ Workflow mutual exclusion is cooperative and does not prevent unrelated processe
89
96
 
90
97
  Goal is independently installable and keeps its standalone behavior when no other protocol participant is present.
91
98
  On the characterized Pi `0.84.2` runtime, it participates in the anonymous `workflow:mutex:v1` `agent-workflow` group.
92
- An active Goal holds the group through ordinary work, external waiting, continuation delivery, compaction recovery, and provider retry.
93
- Paused, blocked, usage-limited, budget-limited, complete, cleared, and legacy-queue-only states do not hold it.
99
+ An active Goal holds the group through ordinary work, external waiting, optional usage-limit recovery, continuation delivery, compaction recovery, and provider retry.
100
+ Paused, blocked, stopped `usage_limited`, budget-limited, complete, cleared, and legacy-queue-only states do not hold it.
94
101
 
95
102
  Direct starts, menu starts, managed-run starts, stopped resumes, and stopped-goal edits use one final synchronous admission.
96
103
  Admission occurs after validation and confirmation but before any tool, Goal-state, persistence, prompt, queue, or status mutation.
@@ -179,7 +186,7 @@ This version no longer reads that global file, and `/goal clear` removes any leg
179
186
  - `paused · automatic limit 25/25` — the automatic-work limit paused the goal; `/goal` opens the recovery preview.
180
187
  - `paused · automatic 12/25` — another pause reason stopped work while preserving the finite epoch.
181
188
  - `blocked · automatic 12/25` — progress requires user or external action, or a terminal non-usage error stopped work.
182
- - `usage · automatic 12/25` — the provider or account usage limit stopped work.
189
+ - `usage · automatic 12/25` — the provider or account usage limit stopped work under the manual-recovery policy; enabled recovery instead shows waiting.
183
190
  - `budget 100k/100k · automatic 12/25` — the user-configured token budget was reached; auto-continuation stops.
184
191
  - `complete` — shown briefly after `goal_complete` succeeds.
185
192
 
@@ -277,10 +284,11 @@ An accepted call keeps the canonical Goal status active, checkpoints active elap
277
284
  It persists the reason and optional absolute deadline and terminates the normal single-tool run.
278
285
  Call `goal_wait` alone because Pi only guarantees early termination when every finalized result in a parallel tool batch terminates.
279
286
 
280
- After Pi finishes handling a provider error, pi-goal enters the same active waiting state without a deadline unless cancellation, an explicit usage limit, a failed compaction recovery, or a Goal safety limit requires a stopped state.
281
- This applies to exhausted, disabled, or zero-budget retries and to errors Pi does not classify for retry; Goal never adds a retry attempt.
287
+ After Pi finishes handling a non-usage provider error, pi-goal enters the same active waiting state without a deadline unless cancellation, a failed compaction recovery, or a Goal safety limit requires a stopped state.
288
+ This applies to exhausted, disabled, or zero-budget retries and to errors Pi does not classify for retry; this ordinary provider-error wait adds no retry attempt.
289
+ Recognized usage limits stop by default; [opt-in recovery](./docs/settings.md#usage-limit-recovery) instead uses a scheduled active wait.
282
290
  The warning reports bounded provider status and explains how a follow-up or `/goal resume` wakes the Goal.
283
- An already accepted `goal_wait` keeps its reason and deadline if a later assistant error occurs; the provider error does not replace that wait.
291
+ An already accepted `goal_wait` keeps its reason and deadline if a later non-usage assistant error occurs; recognized usage errors instead follow the configured quota policy.
284
292
  Context-overflow compaction exhaustion remains blocked because another model turn can repeat the same oversized request without corrective compaction.
285
293
 
286
294
  Interactive input, RPC input, another extension's `sendUserMessage()` input, and supported non-Goal custom follow-ups clear the wait before their turn runs.
@@ -320,13 +328,14 @@ The user can resolve the external condition and run `/goal resume` to rotate the
320
328
 
321
329
  ## 🛑 Interruption and queued-input behavior
322
330
 
323
- A user pause or aborted turn produces `paused`; a final recognized provider/account quota error produces `usage_limited`; failed native compaction recovery produces `blocked`.
331
+ A user pause or aborted turn produces `paused`; a final recognized provider/account quota error produces stopped `usage_limited` by default, or active waiting when `retryUsageLimits` is enabled; failed native compaction recovery produces `blocked`.
324
332
  Each stopped transition cancels pending continuation intent or delivery and aborts stale work when applicable.
325
333
  Stale tool calls remain blocked until the next non-goal user prompt, successful reactivation or replacement, or `/goal clear`.
326
334
  On `/goal clear`, the extension clears goal state, continuation markers, and any stale tool-call block without aborting an unrelated in-flight turn.
327
335
  Pi decides provider retry and context-overflow eligibility through its native classifiers.
328
336
  Its retry settings control provider retry attempts; native compact-and-retry recovery uses Pi's compaction settings and separate recovery limit.
329
- Goal adds no retry patterns or retry loop. Its usage-limit policy selects the final status without preventing recovery that Pi permits.
337
+ Goal adds no retry patterns and does not change Pi's native retry eligibility, backoff, cancellation, or accounting.
338
+ Its separate, default-off usage-limit policy can schedule recovery through the existing wait dispatcher after native recovery settles.
330
339
  An unclassified assistant error, including `Connection prematurely closed BEFORE response`, stays active until settlement and then enters deadline-free waiting even when Pi does not retry it.
331
340
  This intentionally also applies to invalid-request, authentication, permission, empty-message, and unrecognized account-limit errors that do not match the existing usage-limit policy.
332
341
  These errors can wait indefinitely and retain managed-run and Workflow Mutex ownership; use `/goal pause` or managed-run cancellation to stop them.
@@ -337,7 +346,7 @@ Native provider retries and overflow or truncated-response compaction retries st
337
346
  No extra continuation is queued, and automatic ownership remains charged through retry `agent_start` events.
338
347
  At `agent_settled`, reported cancellation takes precedence, including a full session abort during retry backoff without another assistant response.
339
348
  An aborted automatic compaction also pauses its matching Goal through Pi's compaction failure event.
340
- A final recognized usage limit selects `usage_limited`; otherwise remaining provider retry or unclassified-error recovery enters a deadline-free active wait before any continuation dispatches.
349
+ A final recognized usage limit selects stopped `usage_limited` with recovery disabled, or scheduled active waiting with recovery enabled; otherwise remaining provider retry or unclassified-error recovery enters a deadline-free active wait before any continuation dispatches.
341
350
  A later non-Goal input wakes the same Goal without rotating its stale-turn guard, so the model can continue, complete, or enter another wait with the current `goal_id`.
342
351
  If matching compaction recovery still exists at `agent_settled`, the Goal becomes `blocked` because recovery did not produce usable context.
343
352
  Stale recovery cannot wait or block a replacement goal.
@@ -391,6 +400,7 @@ A successful start produces canonical state on `pi-goal:event:${runId}`:
391
400
 
392
401
  Later state events use `active`, `complete`, `blocked`, `paused`, `usage_limited`, `budget_limited`, or `cleared`.
393
402
  Only `complete` is a successful terminal outcome.
403
+ Enabled usage-limit recovery keeps the same Goal ID and managed run `active`; it does not emit terminal `usage_limited` and later reopen that run.
394
404
  A matching completion may include `summary`; other terminal outcomes may include `reason`.
395
405
  Events come only from canonical Goal persistence and only for the matching managed run.
396
406
  Manual and restored Goals are not adopted or broadcast, unchanged persistence does not duplicate a status, and each run emits at most one terminal event.