@narumitw/pi-goal 0.53.3 → 0.54.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/README.md CHANGED
@@ -55,7 +55,6 @@ When `~/.pi/agent/pi-goal.json` is absent, pi-goal uses these built-in defaults
55
55
 
56
56
  ```json
57
57
  {
58
- "toolVisibility": "after-first-goal",
59
58
  "rpc": {
60
59
  "enabled": false
61
60
  },
@@ -67,14 +66,13 @@ When `~/.pi/agent/pi-goal.json` is absent, pi-goal uses these built-in defaults
67
66
  ```
68
67
 
69
68
  Use `/goal` → **Settings…** in the TUI to create or update the file interactively, or create and edit it directly.
70
- The standard Settings screen keeps all four controls on one level in task order; the two safety limits open standard choice screens:
69
+ The standard Settings screen keeps all three controls on one level in task order; the two safety limits open standard choice screens:
71
70
 
72
71
  - **Automatic-work limit** shows the exact response limit or **Unlimited**.
73
72
  Choose **Set response limit…** to edit the current finite value (or the built-in default of 25 when switching from Unlimited), or choose **Unlimited…**.
74
73
  Unlimited requires confirmation that tool loops may continue consuming tokens and provider cost without a response-count cap.
75
74
  - **No-progress guard** shows **_N_ runs** or **Off**.
76
75
  Choose the default threshold, **Off**, or **Set threshold…** and enter a safe whole number greater than zero.
77
- - **Goal tools** controls whether all Goal tools are always visible or appear after the first goal.
78
76
  - **Managed run RPC** controls whether trusted installed extensions may start and cancel managed Goal runs.
79
77
  It defaults to **Off** and is a cooperation setting, not an extension security sandbox.
80
78
 
@@ -82,16 +80,12 @@ Custom number inputs reject zero, negative numbers, decimals, text, and unsafe i
82
80
  Interactive changes are serialized, written atomically, preserve unknown fields, and apply to the current runtime.
83
81
  A successful change updates the visible state immediately.
84
82
  A failed save restores the prior value and reports the settings path so it can be retried.
85
- Tool-visibility changes that would alter the active tool schema are rejected while Pi is busy or another cooperative workflow owns the session; retry after both conditions clear.
86
83
  Escape returns to the previous screen without reverting changes that were already saved.
87
84
 
88
- `toolVisibility` accepts:
89
-
90
- - `"always"` — pi-goal does not proactively hide `goal_complete`, `goal_blocked`, or `goal_wait`, keeping the Goal tool schema stable from session startup.
91
- - `"after-first-goal"` (default) — hides all three Goal tools at fresh runtime startup, reveals them for the first accepted Goal activation, and treats an unfinished-goal restore as unlocked for the remainder of that extension runtime.
92
- On restore, pi-goal uses the active tools already established by earlier lifecycle handlers; it does not re-add missing terminal tools over a restrictive policy.
93
- Failed kickoff, replacement, resume, or reactivating-edit delivery restores the exact pre-activation tool set, including Goal tools exposed by another extension.
94
- If revealing the tools would widen an already-running turn, wait for Pi to become idle and retry `/goal`.
85
+ Pi-goal registers `goal_complete`, `goal_blocked`, and `goal_wait` once and keeps their schemas stable from startup.
86
+ Visible Goal tools do not mean Goal mode is active, and only the latest effective active Goal contract authorizes their use.
87
+ Pi-goal never widens a restrictive active-tool policy; activation rejects when required terminal tools are missing, and an active Goal pauses if they later disappear.
88
+ The retired `toolVisibility` key is ignored and preserved as unknown data when another setting is saved.
95
89
 
96
90
  `experimental.goals` is a removed legacy setting.
97
91
  If it remains `true`, pi-goal accepts the settings file, ignores the old queue feature, and shows an affected-user warning that recommends `/goal edit` when an active objective exists or `/goal <objectives>` when no active goal exists.
@@ -126,11 +120,9 @@ Omitted fields use the defaults above.
126
120
  Invalid or malformed existing settings are never overwritten; they produce a warning and fall back to all defaults.
127
121
  In the TUI, Goal Settings becomes a read-only summary that identifies the invalid file and directs the user to fix it and run `/reload`.
128
122
  Reload Pi after changing the file.
129
- If a live runtime reloads settings, switching `toolVisibility` to `"always"` restores only the exact tools that pi-goal previously hid, while switching to `"after-first-goal"` locks a runtime that has no unfinished goal.
130
123
 
131
- Inactive tool widening first takes temporary Workflow Mutex ownership and leaves settings, hidden-tool ownership, and active tools unchanged when another workflow is active.
132
- Tool visibility is a baseline, not ownership of Pi's global active-tool list.
133
- Plan mode or another restrictive policy may temporarily hide the tools. pi-goal does not fight that policy on restore or on every turn: activation is rejected if the required terminal tools cannot be made available, and an already-active goal is paused without automatic continuation if they disappear.
124
+ Plan mode or another restrictive policy may hide Goal tools.
125
+ Pi-goal does not fight that policy on restore or on later turns: activation rejects when required terminal tools are unavailable, and an already-active goal pauses without automatic continuation if they disappear.
134
126
  A restrictive allowlist created before `goal_wait` existed can still run ordinary Goals with `goal_complete` and `goal_blocked`, but the model cannot enter external waiting until that allowlist also includes `goal_wait`.
135
127
  The pause aborts a Goal-owned kickoff, resume, active-edit, or automatic-continuation prompt, but it does not cancel or stale-block an unrelated user or extension turn, including startup follow-ups after a restrictive restore.
136
128
 
@@ -149,8 +141,6 @@ Restored active Goal state acquires before tool restoration, persistence publica
149
141
  If restoration is busy, the Goal moves only to its existing paused safe state, does not change active tools or schedule work, and can be resumed explicitly after the other workflow ends.
150
142
  Restored stopped Goals and inert legacy queues do not acquire or schedule automatic work.
151
143
 
152
- Inactive session-start restoration and live settings changes that could alter Goal tool visibility use temporary synchronous ownership.
153
- A busy result preserves the settings file, in-memory settings, active tools, and hidden-tool retry ownership.
154
144
  An active Goal still pauses if a non-participating restrictive policy later removes its required terminal tools.
155
145
 
156
146
  The coexistence guarantee is cooperative and applies only when every contender implements v1 on the characterized Pi runtime and shares its event bus and session-manager identity.
@@ -229,8 +219,7 @@ Goal state is stored as Pi session state, similar to Codex's thread-owned goals.
229
219
  `/reload` and reopening the same Pi session can restore that session's unfinished goal.
230
220
  An active restored goal already at or above its finite automatic-work limit pauses before another provider request and reports that progress is saved; use `/goal` to review and continue.
231
221
  A restored waiting Goal remains quiet, excludes offline and waiting wall time from active elapsed time, and restores only its absolute optional deadline timer.
232
- With `"after-first-goal"`, an admitted unfinished restore marks the tools unlocked in the new extension runtime, but it does not widen an active-tool set already restricted by an earlier lifecycle handler; an active goal instead restores as paused when admission is busy or either terminal tool is missing.
233
- If no unfinished goal remains, a fresh runtime starts locked again.
222
+ An active restored goal pauses when workflow admission is busy or either required terminal tool is missing, without changing the active tool set.
234
223
  Active elapsed time is checkpointed before shutdown and restarted after reload only when the Goal is not waiting, so offline and stopped wall-clock time is excluded.
235
224
  Automatic-response counts, repeat fingerprints, and safety-pause causes persist across reload and compaction.
236
225
  A direct non-`/goal` user/RPC input resets the safety epoch only while the goal is active and reclassifies the in-flight run as manual; extension input and messages sent while stopped do not reset it.
@@ -295,9 +284,8 @@ While a goal is active, Goal-owned messages carry persistence rules and a `<goal
295
284
  Kickoff, resume, edited-objective, wait-resume, and automatic-continuation prompts all place a trust boundary before the escaped objective, identifying it as user-provided task data; they preserve its full scope across turns and require the agent to derive concrete requirements from the objective and referenced artifacts.
296
285
  They treat the current worktree, command output, tests, runtime behavior, PR state, rendered artifacts, and external state as authoritative; previous conversation and plans are context rather than proof.
297
286
 
298
- With the default `toolVisibility: "after-first-goal"`, the first accepted Goal activation intentionally reveals the three Goal tools and changes the tool-definition prefix once.
299
- Choosing `toolVisibility: "always"` avoids that activation-time tool change, while both visibility modes use the same Goal contract flow.
300
- After activation, pi-goal does not change the base system instructions or ordered active tools merely for continuation, token accounting, or wait resume.
287
+ Goal helper names, definitions, and active prompt metadata remain stable across Goal activation, continuation, token accounting, wait resume, completion, and clearing.
288
+ Mode-only positive instructions live in the append-only active Goal contract instead of globally active tool prompt metadata.
301
289
  Current token-budget usage is carried by the newly appended Goal prompt instead of rewriting leading system instructions.
302
290
  The first accepted handoff for each Goal identity persists one deterministic hidden Goal contract at the same agent-start boundary, after previously retained conversation history.
303
291
  The contract explicitly supersedes earlier Goal contracts, excludes mutable token, iteration, and elapsed-time counters, and stays at its appended history position.
@@ -503,7 +491,7 @@ packages/pi-goal/
503
491
  │ ├── lifecycle.ts # Pi session, agent, tool, and compaction event adapter
504
492
  │ ├── goal-contract.ts # Deterministic post-compaction model contract
505
493
  │ ├── runtime.ts # Per-factory Goal state, transitions, prompts, and budgets
506
- │ ├── tool-policy.ts # Goal tool visibility ownership and rollback
494
+ │ ├── tool-policy.ts # Goal tool names and read-only availability checks
507
495
  │ ├── safety.ts # Output normalization and no-progress fingerprint state
508
496
  │ ├── wait.ts # External-wait validation and session timer ownership
509
497
  │ ├── errors.ts # Pi-aligned provider error and retry classification
@@ -13,7 +13,7 @@ import {
13
13
  safeGoalMenuText,
14
14
  truncateNotification,
15
15
  updateGoalUsage
16
- } from "./chunk-2ARA24RR.js";
16
+ } from "./chunk-UQRRW4CY.js";
17
17
 
18
18
  // src/command.ts
19
19
  var MAX_OBJECTIVE_LENGTH = 4e3;
@@ -639,146 +639,17 @@ function isRecord3(value) {
639
639
  var GOAL_COMPLETE_TOOL = "goal_complete";
640
640
  var GOAL_BLOCKED_TOOL = "goal_blocked";
641
641
  var GOAL_WAIT_TOOL = "goal_wait";
642
- var GOAL_TOOL_NAMES = [GOAL_COMPLETE_TOOL, GOAL_BLOCKED_TOOL, GOAL_WAIT_TOOL];
643
642
  var REQUIRED_GOAL_TOOL_NAMES = [GOAL_COMPLETE_TOOL, GOAL_BLOCKED_TOOL];
644
- var GoalToolPolicy = class {
645
- unlocked = false;
646
- hiddenByPolicy = /* @__PURE__ */ new Set();
647
- pi;
648
- constructor(pi) {
649
- this.pi = pi;
650
- }
651
- isUnlocked() {
652
- return this.unlocked;
653
- }
654
- hasHiddenTools() {
655
- return this.hiddenByPolicy.size > 0;
656
- }
657
- isGoalToolName(name) {
658
- return GOAL_TOOL_NAMES.includes(name);
659
- }
660
- toolsAvailable() {
661
- const active = new Set(this.pi.getActiveTools());
662
- return REQUIRED_GOAL_TOOL_NAMES.every((name) => active.has(name));
663
- }
664
- lock() {
665
- this.unlocked = false;
666
- }
667
- unlock() {
668
- this.unlocked = true;
669
- }
670
- unlockAndForgetHidden() {
671
- this.unlocked = true;
672
- this.hiddenByPolicy.clear();
673
- }
674
- hideIfLocked() {
675
- if (this.unlocked) return;
676
- const active = this.pi.getActiveTools();
677
- const hidden = active.filter((name) => this.isGoalToolName(name));
678
- if (hidden.length === 0) return;
679
- this.pi.setActiveTools(active.filter((name) => !this.isGoalToolName(name)));
680
- for (const name of hidden) this.hiddenByPolicy.add(name);
681
- }
682
- restoreHidden() {
683
- const activeBeforeRestore = this.pi.getActiveTools();
684
- const activeSet = new Set(activeBeforeRestore);
685
- const missingOwnedTools = [...this.hiddenByPolicy].filter((name) => !activeSet.has(name));
686
- if (missingOwnedTools.length === 0) {
687
- this.hiddenByPolicy.clear();
688
- return;
689
- }
690
- try {
691
- this.pi.setActiveTools([...activeBeforeRestore, ...missingOwnedTools]);
692
- const restored = new Set(this.pi.getActiveTools());
693
- if (missingOwnedTools.some((name) => !restored.has(name))) {
694
- throw new Error("the active tool policy rejected a previously hidden goal tool");
695
- }
696
- this.hiddenByPolicy.clear();
697
- } catch (error) {
698
- this.pi.setActiveTools(activeBeforeRestore);
699
- throw error;
700
- }
701
- }
702
- prepareActivation(visibility, ctx) {
703
- if (visibility === "after-first-goal") {
704
- if (!this.toolsAvailable() && ctx.isIdle?.() !== true) {
705
- throw new Error("wait until Pi is idle before revealing the goal tools");
706
- }
707
- this.reveal();
708
- return;
709
- }
710
- if (this.hasHiddenTools()) this.restoreHidden();
711
- this.unlock();
712
- this.assertAvailable();
713
- }
714
- prepareSessionStart(visibility, previous) {
715
- if (visibility === "after-first-goal" && previous === "always") this.lock();
716
- if (visibility !== "always") return;
717
- try {
718
- if (this.hasHiddenTools()) this.restoreHidden();
719
- } finally {
720
- this.unlock();
721
- }
722
- }
723
- reconcileRestoredState(visibility, hasUnfinishedGoal) {
724
- if (visibility !== "after-first-goal") return;
725
- if (hasUnfinishedGoal) this.unlockAndForgetHidden();
726
- else if (!this.unlocked) this.hideIfLocked();
727
- }
728
- applyVisibilityChange(previous, next, hasUnfinishedGoal, ctx) {
729
- if (previous === next) return;
730
- if (next === "always") {
731
- if (this.hasHiddenTools() && ctx.isIdle?.() !== true) {
732
- throw new Error("Wait for Pi to become idle before revealing Goal tools.");
733
- }
734
- this.restoreHidden();
735
- this.unlock();
736
- return;
737
- }
738
- if (hasUnfinishedGoal) {
739
- this.unlockAndForgetHidden();
740
- return;
741
- }
742
- if (ctx.isIdle?.() !== true) {
743
- throw new Error("Wait for Pi to become idle before hiding Goal tools.");
744
- }
745
- this.lock();
746
- this.hideIfLocked();
747
- }
748
- snapshot() {
749
- return {
750
- activeTools: this.pi.getActiveTools(),
751
- goalToolsUnlocked: this.unlocked,
752
- goalToolsHiddenByPolicy: [...this.hiddenByPolicy]
753
- };
754
- }
755
- restore(snapshot) {
756
- this.pi.setActiveTools(snapshot.activeTools);
757
- this.unlocked = snapshot.goalToolsUnlocked;
758
- this.hiddenByPolicy.clear();
759
- for (const name of snapshot.goalToolsHiddenByPolicy) this.hiddenByPolicy.add(name);
760
- }
761
- reveal() {
762
- const snapshot = this.snapshot();
763
- try {
764
- const active = this.pi.getActiveTools();
765
- const activeSet = new Set(active);
766
- const missing = GOAL_TOOL_NAMES.filter((name) => !activeSet.has(name));
767
- if (missing.length > 0) this.pi.setActiveTools([...active, ...missing]);
768
- this.assertAvailable();
769
- this.unlockAndForgetHidden();
770
- } catch (error) {
771
- this.restore(snapshot);
772
- throw error;
773
- }
774
- }
775
- assertAvailable() {
776
- if (this.toolsAvailable()) return;
777
- throw new Error(
778
- "goal_complete and goal_blocked are unavailable; include them in the active tool allowlist or leave the restrictive tool mode first."
779
- );
780
- }
781
- };
643
+ function goalToolsAvailable(pi) {
644
+ const active = new Set(pi.getActiveTools());
645
+ return REQUIRED_GOAL_TOOL_NAMES.every((name) => active.has(name));
646
+ }
647
+ function assertGoalToolsAvailable(pi) {
648
+ if (goalToolsAvailable(pi)) return;
649
+ throw new Error(
650
+ "goal_complete and goal_blocked are unavailable; include them in the active tool allowlist or leave the restrictive tool mode first."
651
+ );
652
+ }
782
653
 
783
654
  // src/workflow-mutex.ts
784
655
  var WORKFLOW_MUTEX_CHANNEL = "workflow:mutex:v1";
@@ -891,7 +762,6 @@ var GoalRuntime = class {
891
762
  agentRunToolAttempted = false;
892
763
  guardAbortGoalId;
893
764
  staleGoalToolCallsBlocked = false;
894
- toolPolicy;
895
765
  workflowMutex;
896
766
  workflowOwner;
897
767
  workflowSession;
@@ -907,7 +777,12 @@ var GoalRuntime = class {
907
777
  constructor(pi) {
908
778
  this.pi = pi;
909
779
  this.workflowMutex = new WorkflowMutex(pi);
910
- this.toolPolicy = new GoalToolPolicy(pi);
780
+ }
781
+ goalToolsAvailable() {
782
+ return goalToolsAvailable(this.pi);
783
+ }
784
+ assertGoalToolsAvailable() {
785
+ assertGoalToolsAvailable(this.pi);
911
786
  }
912
787
  bindWorkflowSession(session) {
913
788
  this.workflowSession = session;
@@ -938,29 +813,6 @@ var GoalRuntime = class {
938
813
  this.workflowMutex.release(owner);
939
814
  if (!this.workflowMutex.isOwner(owner)) this.workflowOwner = void 0;
940
815
  }
941
- beginTemporaryWorkflowAccess(session) {
942
- if (session && typeof session === "object" && this.workflowSession !== session) {
943
- this.bindWorkflowSession(session);
944
- }
945
- const alreadyOwned = this.workflowMutex.isOwner(this.workflowOwner);
946
- if (!alreadyOwned && !this.acquireWorkflow()) return void 0;
947
- let released = false;
948
- return () => {
949
- if (released) return;
950
- released = true;
951
- if (!alreadyOwned) this.releaseWorkflow();
952
- };
953
- }
954
- withTemporaryWorkflowAccess(action, session) {
955
- const release = this.beginTemporaryWorkflowAccess(session);
956
- if (!release) return false;
957
- try {
958
- action();
959
- return true;
960
- } finally {
961
- release();
962
- }
963
- }
964
816
  hasLegacyQueueInterface() {
965
817
  return this.legacyExperimentalGoalsSetting || this.legacyQueueState !== void 0;
966
818
  }
@@ -1049,7 +901,7 @@ var GoalRuntime = class {
1049
901
  return false;
1050
902
  }
1051
903
  if (!intent) return false;
1052
- if (this.activeGoal?.status === "active" && !this.toolPolicy.toolsAvailable()) {
904
+ if (this.activeGoal?.status === "active" && !this.goalToolsAvailable()) {
1053
905
  this.pauseGoalForUnavailableTools(ctx);
1054
906
  return false;
1055
907
  }
@@ -1705,6 +1557,13 @@ var GoalRuntime = class {
1705
1557
  clearLegacyPersistedGoal(cwd);
1706
1558
  }
1707
1559
  clearActiveGoal(ctx, reason = "goal cleared", releaseWorkflow = true) {
1560
+ this.clearActiveGoalState(ctx, reason, releaseWorkflow);
1561
+ this.ensureInactiveGoalContextContract(ctx);
1562
+ }
1563
+ clearCompletedGoal(ctx) {
1564
+ this.clearActiveGoalState(ctx, "goal cleared", true);
1565
+ }
1566
+ clearActiveGoalState(ctx, reason, releaseWorkflow) {
1708
1567
  const clearedGoal = this.activeGoal;
1709
1568
  this.clearGoalWaitTimer();
1710
1569
  this.cancelContinuationWork();
@@ -1714,7 +1573,6 @@ var GoalRuntime = class {
1714
1573
  this.activeGoal = void 0;
1715
1574
  this.legacyQueueState = void 0;
1716
1575
  this.clearPersistedGoal(ctx.cwd, clearedGoal, reason);
1717
- this.ensureInactiveGoalContextContract(ctx);
1718
1576
  ctx.ui.setStatus(STATUS_KEY, void 0);
1719
1577
  if (releaseWorkflow) this.releaseWorkflow();
1720
1578
  }
@@ -1731,8 +1589,7 @@ var GoalRuntime = class {
1731
1589
  guardAbortGoalId: this.guardAbortGoalId,
1732
1590
  staleGoalToolCallsBlocked: this.staleGoalToolCallsBlocked,
1733
1591
  cancelledContinuationMarkers: [...this.cancelledContinuationMarkers],
1734
- terminalDetails: this.terminalDetails ? structuredClone(this.terminalDetails) : void 0,
1735
- toolVisibility: this.toolPolicy.snapshot()
1592
+ terminalDetails: this.terminalDetails ? structuredClone(this.terminalDetails) : void 0
1736
1593
  };
1737
1594
  }
1738
1595
  restoreSettingsApplicationState(snapshot) {
@@ -1751,7 +1608,6 @@ var GoalRuntime = class {
1751
1608
  this.staleGoalToolCallsBlocked = snapshot.staleGoalToolCallsBlocked;
1752
1609
  this.cancelledContinuationMarkers = new Map(snapshot.cancelledContinuationMarkers);
1753
1610
  this.terminalDetails = snapshot.terminalDetails ? structuredClone(snapshot.terminalDetails) : void 0;
1754
- this.toolPolicy.restore(snapshot.toolVisibility);
1755
1611
  }
1756
1612
  pauseGoalForUnavailableTools(ctx, abortTurn = true, recordUsage = true) {
1757
1613
  const goal = this.activeGoal;
@@ -2044,4 +1900,4 @@ export {
2044
1900
  isContradictoryCompletionSummary,
2045
1901
  goalIdRejectionReason
2046
1902
  };
2047
- //# sourceMappingURL=chunk-ZT3VZXYO.js.map
1903
+ //# sourceMappingURL=chunk-UC6U2RFG.js.map