@narumitw/pi-goal 0.53.1 → 0.54.0

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/src/runtime.ts CHANGED
@@ -7,6 +7,13 @@ import {
7
7
  updateGoalUsage,
8
8
  } from "./accounting.js";
9
9
  import { formatError, notifyTerminal, safeGoalMenuText, truncateNotification } from "./errors.js";
10
+ import {
11
+ createGoalContextContract,
12
+ createInactiveGoalContextContract,
13
+ hasGoalContextContract,
14
+ hasGoalContextContractHistory,
15
+ hasInactiveGoalContextContract,
16
+ } from "./goal-contract.js";
10
17
  import {
11
18
  appendGoalPromptMarker,
12
19
  extractContinuationMarker,
@@ -29,7 +36,7 @@ import {
29
36
  type GoalSettings,
30
37
  type GoalSettingsLoadIssue,
31
38
  } from "./settings.js";
32
- import { GoalToolPolicy, type GoalToolVisibilitySnapshot } from "./tool-policy.js";
39
+ import { assertGoalToolsAvailable, goalToolsAvailable } from "./tool-policy.js";
33
40
  import { type GoalWait, GoalWaitTimer } from "./wait.js";
34
41
  import { WorkflowMutex, type WorkflowMutexOwner } from "./workflow-mutex.js";
35
42
 
@@ -167,7 +174,6 @@ export interface GoalSettingsRuntimeSnapshot {
167
174
  staleGoalToolCallsBlocked: boolean;
168
175
  cancelledContinuationMarkers: Array<[string, string]>;
169
176
  terminalDetails?: GoalTerminalDetails;
170
- toolVisibility: GoalToolVisibilitySnapshot;
171
177
  }
172
178
 
173
179
  interface PendingGoalPrompt {
@@ -198,7 +204,7 @@ const CONTRADICTORY_COMPLETION_PATTERNS = [
198
204
  // and the cross-cutting invariants used by command and lifecycle orchestration.
199
205
  // Keep this state machine cohesive despite its size: prompt ownership, continuation,
200
206
  // budget, safety, external-wait, and queue transitions share ordering-sensitive invariants.
201
- // Tool visibility and generic wait-timer mechanics are delegated to focused collaborators.
207
+ // Tool availability and generic wait-timer mechanics are delegated to focused collaborators.
202
208
  // Cohesion justification: Goal transitions, continuation and wait ownership, queue state, and
203
209
  // budget/retry recovery share one generation-guarded runtime; separating them further would
204
210
  // duplicate stale-turn, timer, and persistence invariants across modules.
@@ -230,7 +236,6 @@ export class GoalRuntime {
230
236
  agentRunToolAttempted = false;
231
237
  guardAbortGoalId?: string;
232
238
  staleGoalToolCallsBlocked = false;
233
- readonly toolPolicy: GoalToolPolicy;
234
239
  private readonly workflowMutex: WorkflowMutex;
235
240
  private workflowOwner?: WorkflowMutexOwner;
236
241
  private workflowSession?: object;
@@ -248,7 +253,14 @@ export class GoalRuntime {
248
253
  constructor(pi: ExtensionAPI) {
249
254
  this.pi = pi;
250
255
  this.workflowMutex = new WorkflowMutex(pi);
251
- this.toolPolicy = new GoalToolPolicy(pi);
256
+ }
257
+
258
+ goalToolsAvailable() {
259
+ return goalToolsAvailable(this.pi);
260
+ }
261
+
262
+ assertGoalToolsAvailable() {
263
+ assertGoalToolsAvailable(this.pi);
252
264
  }
253
265
 
254
266
  bindWorkflowSession(session: object) {
@@ -285,31 +297,6 @@ export class GoalRuntime {
285
297
  if (!this.workflowMutex.isOwner(owner)) this.workflowOwner = undefined;
286
298
  }
287
299
 
288
- beginTemporaryWorkflowAccess(session?: unknown) {
289
- if (session && typeof session === "object" && this.workflowSession !== session) {
290
- this.bindWorkflowSession(session);
291
- }
292
- const alreadyOwned = this.workflowMutex.isOwner(this.workflowOwner);
293
- if (!alreadyOwned && !this.acquireWorkflow()) return undefined;
294
- let released = false;
295
- return () => {
296
- if (released) return;
297
- released = true;
298
- if (!alreadyOwned) this.releaseWorkflow();
299
- };
300
- }
301
-
302
- withTemporaryWorkflowAccess(action: () => void, session?: unknown) {
303
- const release = this.beginTemporaryWorkflowAccess(session);
304
- if (!release) return false;
305
- try {
306
- action();
307
- return true;
308
- } finally {
309
- release();
310
- }
311
- }
312
-
313
300
  hasLegacyQueueInterface() {
314
301
  return this.legacyExperimentalGoalsSetting || this.legacyQueueState !== undefined;
315
302
  }
@@ -427,7 +414,7 @@ export class GoalRuntime {
427
414
  return false;
428
415
  }
429
416
  if (!intent) return false;
430
- if (this.activeGoal?.status === "active" && !this.toolPolicy.toolsAvailable()) {
417
+ if (this.activeGoal?.status === "active" && !this.goalToolsAvailable()) {
431
418
  this.pauseGoalForUnavailableTools(ctx);
432
419
  return false;
433
420
  }
@@ -695,6 +682,7 @@ export class GoalRuntime {
695
682
  if (terminalReason !== undefined) this.setTerminalReason(this.activeGoal.id, terminalReason);
696
683
  const stoppedGoal = this.activeGoal;
697
684
  this.persistGoal(stoppedGoal);
685
+ this.ensureInactiveGoalContextContract(ctx);
698
686
  if (this.activeGoal?.id === stoppedGoal.id && this.activeGoal.status === stoppedGoal.status) {
699
687
  this.updateStatus(ctx, stoppedGoal);
700
688
  this.releaseWorkflow();
@@ -893,8 +881,22 @@ export class GoalRuntime {
893
881
  if (!recovery) return false;
894
882
  this.goalRecovery = undefined;
895
883
  const goal = this.activeGoal;
896
- if (goal?.id !== recovery.goalId || goal.status !== "active") return false;
884
+ if (goal?.id !== recovery.goalId || goal.status !== "active" || !this.ownsWorkflow(goal)) {
885
+ return false;
886
+ }
897
887
  const details = recovery.errorMessage ? `: ${truncateNotification(recovery.errorMessage)}` : "";
888
+ if (recovery.kind === "provider_retry") {
889
+ const waitingGoal = this.enterGoalWait(ctx, goal.id, {
890
+ reason: `Provider retries exhausted${details}`,
891
+ });
892
+ if (!waitingGoal) return false;
893
+ notifyTerminal(
894
+ ctx.ui,
895
+ `Goal waiting after provider retries were exhausted${details}. Send a follow-up or run /goal resume to retry.`,
896
+ "warning",
897
+ );
898
+ return true;
899
+ }
898
900
  const stoppedGoal = this.stopActiveGoal(ctx, {
899
901
  kind: "retry_exhausted",
900
902
  expectedGoalId: goal.id,
@@ -946,6 +948,37 @@ export class GoalRuntime {
946
948
  this.pendingNonGoalInputs = [];
947
949
  }
948
950
 
951
+ ensureGoalContextContract(ctx: StatusContext, goal: ActiveGoal) {
952
+ const contract = this.goalContextContractForPrompt(ctx, goal);
953
+ if (contract) this.pi.sendMessage(contract, { triggerTurn: false });
954
+ }
955
+
956
+ ensureInactiveGoalContextContract(ctx: StatusContext) {
957
+ const contract = this.goalContextContractForPrompt(ctx);
958
+ if (contract) this.pi.sendMessage(contract, { triggerTurn: false });
959
+ }
960
+
961
+ goalContextContractForPrompt(ctx: StatusContext, goal?: ActiveGoal) {
962
+ const { contextEntries, historyEntries } = goalContractEntries(ctx);
963
+ if (goal) {
964
+ return hasGoalContextContract(contextEntries, goal)
965
+ ? undefined
966
+ : createGoalContextContract(goal);
967
+ }
968
+ const hasHistory =
969
+ hasGoalContextContractHistory(contextEntries) ||
970
+ hasGoalContextContractHistory(historyEntries);
971
+ if (!hasHistory || hasInactiveGoalContextContract(contextEntries)) return undefined;
972
+ return createInactiveGoalContextContract();
973
+ }
974
+
975
+ hasGoalContextContractHistory(ctx: StatusContext) {
976
+ const { contextEntries, historyEntries } = goalContractEntries(ctx);
977
+ return (
978
+ hasGoalContextContractHistory(contextEntries) || hasGoalContextContractHistory(historyEntries)
979
+ );
980
+ }
981
+
949
982
  async sendOwnedGoalPrompt(
950
983
  ctx: StatusContext,
951
984
  goalId: string,
@@ -1210,10 +1243,9 @@ export class GoalRuntime {
1210
1243
  this.activeGoal = undefined;
1211
1244
  this.legacyQueueState = undefined;
1212
1245
  this.clearPersistedGoal(ctx.cwd, clearedGoal, reason);
1246
+ this.ensureInactiveGoalContextContract(ctx);
1213
1247
  ctx.ui.setStatus(STATUS_KEY, undefined);
1214
1248
  if (releaseWorkflow) this.releaseWorkflow();
1215
- // Do not relock toolPolicy: after first activation, keep tools visible for the
1216
- // rest of this extension runtime to avoid repeated tool-schema churn.
1217
1249
  }
1218
1250
 
1219
1251
  snapshotSettingsApplicationState(): GoalSettingsRuntimeSnapshot {
@@ -1234,7 +1266,6 @@ export class GoalRuntime {
1234
1266
  staleGoalToolCallsBlocked: this.staleGoalToolCallsBlocked,
1235
1267
  cancelledContinuationMarkers: [...this.cancelledContinuationMarkers],
1236
1268
  terminalDetails: this.terminalDetails ? structuredClone(this.terminalDetails) : undefined,
1237
- toolVisibility: this.toolPolicy.snapshot(),
1238
1269
  };
1239
1270
  }
1240
1271
 
@@ -1262,7 +1293,6 @@ export class GoalRuntime {
1262
1293
  this.terminalDetails = snapshot.terminalDetails
1263
1294
  ? structuredClone(snapshot.terminalDetails)
1264
1295
  : undefined;
1265
- this.toolPolicy.restore(snapshot.toolVisibility);
1266
1296
  }
1267
1297
 
1268
1298
  pauseGoalForUnavailableTools(ctx: StatusContext, abortTurn = true, recordUsage = true) {
@@ -1541,6 +1571,25 @@ function inputFingerprint(prompt: unknown) {
1541
1571
  .digest("hex");
1542
1572
  }
1543
1573
 
1574
+ function goalContractEntries(ctx: StatusContext) {
1575
+ const sessionManager = ctx.sessionManager as
1576
+ | {
1577
+ buildContextEntries?: () => unknown[];
1578
+ buildSessionContext?: () => { messages?: unknown[] };
1579
+ getBranch?: () => unknown[];
1580
+ getEntries?: () => unknown[];
1581
+ }
1582
+ | undefined;
1583
+ const historyEntries = sessionManager?.getBranch?.() ?? sessionManager?.getEntries?.() ?? [];
1584
+ return {
1585
+ contextEntries:
1586
+ sessionManager?.buildSessionContext?.().messages ??
1587
+ sessionManager?.buildContextEntries?.() ??
1588
+ historyEntries,
1589
+ historyEntries,
1590
+ };
1591
+ }
1592
+
1544
1593
  async function sendPrompt(
1545
1594
  pi: ExtensionAPI,
1546
1595
  ctx: StatusContext,
@@ -19,8 +19,6 @@ interface GoalSettingsApplyOptions {
19
19
  save?: (settings: GoalSettings) => void;
20
20
  }
21
21
 
22
- class WorkflowBusyError extends Error {}
23
-
24
22
  type LimitField = "automaticTurns" | "noProgressTurns";
25
23
  type LimitSelection = "unlimited" | "default" | "custom" | "off";
26
24
  export async function showGoalSettings(
@@ -50,7 +48,6 @@ export async function showGoalSettings(
50
48
  | "open-no-progress"
51
49
  | "choose-automatic"
52
50
  | "choose-no-progress"
53
- | "set-visibility"
54
51
  | "set-rpc";
55
52
  const menu = defineMenu<undefined, Screen, Action, ExtensionCommandContext>({
56
53
  start: invalid ? "invalid" : (options.initialScreen ?? "settings"),
@@ -78,14 +75,6 @@ export async function showGoalSettings(
78
75
  ),
79
76
  action: "open-no-progress",
80
77
  },
81
- {
82
- id: "toolVisibility",
83
- label: "Goal tools",
84
- description: "Keep terminal Goal tools visible, or reveal them after the first goal.",
85
- currentValue: visibilityLabel(runtime.settings.toolVisibility),
86
- values: ["Always", "After first goal"],
87
- action: "set-visibility",
88
- },
89
78
  {
90
79
  id: "rpcEnabled",
91
80
  label: "Managed run RPC",
@@ -106,7 +95,6 @@ export async function showGoalSettings(
106
95
  `Invalid settings file. Pi-goal is using built-in defaults. Fix ${safeTerminalText(settingsPath)} and run /reload. The file will not be overwritten.`,
107
96
  `Automatic-work limit: ${formatAutomaticWork(runtime.settings.continuationLimits.automaticTurns)}`,
108
97
  `No-progress guard: ${formatNoProgressProtection(runtime.settings.continuationLimits.noProgressTurns)}`,
109
- `Goal tools: ${visibilityLabel(runtime.settings.toolVisibility)}`,
110
98
  `Managed run RPC: ${runtime.settings.rpc.enabled ? "On" : "Off"}`,
111
99
  ],
112
100
  hint: "back",
@@ -143,24 +131,6 @@ export async function showGoalSettings(
143
131
  previewGoalIds.get("noProgressTurns") ?? null,
144
132
  isMenuCurrent,
145
133
  ),
146
- "set-visibility": async ({ value }) => {
147
- const nextVisibility = value === "Always" ? "always" : "after-first-goal";
148
- if (nextVisibility === runtime.settings.toolVisibility) return { kind: "stay" };
149
- try {
150
- const next = {
151
- ...structuredClone(runtime.settings),
152
- toolVisibility: nextVisibility,
153
- } satisfies GoalSettings;
154
- applyGoalSettings(runtime, next, ctx, {
155
- save: (settings) => (options.save ?? saveGoalSettings)(settings, settingsPath),
156
- });
157
- notifyTerminal(ctx.ui, `Goal tools: ${value}.`, "info");
158
- return { kind: "stay" };
159
- } catch (error) {
160
- notifySettingsFailure(ctx, settingsPath, error);
161
- return { kind: "rejected" };
162
- }
163
- },
164
134
  "set-rpc": async ({ value }) => {
165
135
  const enabled = value === "On";
166
136
  if (enabled === runtime.settings.rpc.enabled) return { kind: "stay" };
@@ -326,59 +296,44 @@ export function applyGoalSettings(
326
296
  options: GoalSettingsApplyOptions = {},
327
297
  ) {
328
298
  const snapshot = runtime.snapshotSettingsApplicationState();
329
- const visibilityChanges = snapshot.settings.toolVisibility !== next.toolVisibility;
330
- const releaseWorkflow = visibilityChanges
331
- ? runtime.beginTemporaryWorkflowAccess(ctx.sessionManager)
332
- : () => undefined;
333
- if (!releaseWorkflow) {
334
- throw new WorkflowBusyError(
335
- "Another workflow is active in this session. Goal tool visibility was not changed.",
336
- );
337
- }
338
-
339
299
  let fileSaved = false;
340
300
  try {
301
+ runtime.settings = structuredClone(next);
302
+ options.save?.(next);
303
+ fileSaved = options.save !== undefined;
304
+ const activeGoalId = runtime.activeGoal?.id;
305
+ const abortOwnedRun = activeGoalId !== undefined && runtime.agentRunGoalId === activeGoalId;
306
+ const pausedByAutomaticLimit = runtime.enforceAutomaticTurnLimit(ctx, abortOwnedRun);
307
+ if (!pausedByAutomaticLimit) runtime.enforceNoProgressLimit(ctx, abortOwnedRun);
308
+ if (runtime.activeGoal) {
309
+ runtime.updateStatus(ctx, runtime.activeGoal);
310
+ }
311
+ } catch (error) {
312
+ const rollbackErrors: unknown[] = [];
341
313
  try {
342
- applyToolVisibility(runtime, snapshot.settings, next, ctx);
343
- runtime.settings = structuredClone(next);
344
- options.save?.(next);
345
- fileSaved = options.save !== undefined;
346
- const activeGoalId = runtime.activeGoal?.id;
347
- const abortOwnedRun = activeGoalId !== undefined && runtime.agentRunGoalId === activeGoalId;
348
- const pausedByAutomaticLimit = runtime.enforceAutomaticTurnLimit(ctx, abortOwnedRun);
349
- if (!pausedByAutomaticLimit) runtime.enforceNoProgressLimit(ctx, abortOwnedRun);
350
- if (runtime.activeGoal) {
351
- runtime.updateStatus(ctx, runtime.activeGoal);
352
- }
353
- } catch (error) {
354
- const rollbackErrors: unknown[] = [];
314
+ runtime.restoreSettingsApplicationState(snapshot);
315
+ } catch (rollbackError) {
316
+ rollbackErrors.push(rollbackError);
317
+ }
318
+ if (fileSaved) {
355
319
  try {
356
- runtime.restoreSettingsApplicationState(snapshot);
320
+ options.save?.(snapshot.settings);
357
321
  } catch (rollbackError) {
358
322
  rollbackErrors.push(rollbackError);
359
323
  }
360
- if (fileSaved) {
361
- try {
362
- options.save?.(snapshot.settings);
363
- } catch (rollbackError) {
364
- rollbackErrors.push(rollbackError);
365
- }
366
- try {
367
- restorePersistedRuntime(runtime, ctx);
368
- } catch (rollbackError) {
369
- rollbackErrors.push(rollbackError);
370
- }
371
- }
372
- if (rollbackErrors.length > 0) {
373
- throw new AggregateError(
374
- [error, ...rollbackErrors],
375
- `pi-goal settings application failed and rollback was incomplete: ${formatError(error)}`,
376
- );
324
+ try {
325
+ restorePersistedRuntime(runtime, ctx);
326
+ } catch (rollbackError) {
327
+ rollbackErrors.push(rollbackError);
377
328
  }
378
- throw error;
379
329
  }
380
- } finally {
381
- releaseWorkflow();
330
+ if (rollbackErrors.length > 0) {
331
+ throw new AggregateError(
332
+ [error, ...rollbackErrors],
333
+ `pi-goal settings application failed and rollback was incomplete: ${formatError(error)}`,
334
+ );
335
+ }
336
+ throw error;
382
337
  }
383
338
  }
384
339
 
@@ -430,21 +385,6 @@ async function resolveLimitSelection(
430
385
  }
431
386
  }
432
387
 
433
- function applyToolVisibility(
434
- runtime: GoalRuntime,
435
- previous: GoalSettings,
436
- next: GoalSettings,
437
- ctx: ExtensionCommandContext,
438
- ) {
439
- if (previous.toolVisibility === next.toolVisibility) return;
440
- runtime.toolPolicy.applyVisibilityChange(
441
- previous.toolVisibility,
442
- next.toolVisibility,
443
- runtime.activeGoal !== undefined,
444
- ctx,
445
- );
446
- }
447
-
448
388
  function restorePersistedRuntime(runtime: GoalRuntime, ctx: ExtensionCommandContext) {
449
389
  if (runtime.activeGoal) {
450
390
  runtime.persistGoal(runtime.activeGoal);
@@ -507,10 +447,6 @@ function isLimitSelection(value: string): value is LimitSelection {
507
447
  return value === "unlimited" || value === "default" || value === "custom" || value === "off";
508
448
  }
509
449
 
510
- function visibilityLabel(value: GoalSettings["toolVisibility"]) {
511
- return value === "always" ? "Always" : "After first goal";
512
- }
513
-
514
450
  function notifySettingsFailure(ctx: ExtensionCommandContext, settingsPath: string, error: unknown) {
515
451
  const path = safeTerminalText(settingsPath);
516
452
  const detail = safeTerminalText(formatError(error));
package/src/settings.ts CHANGED
@@ -4,13 +4,10 @@ import { basename, dirname, join } from "node:path";
4
4
  import { getAgentDir } from "@earendil-works/pi-coding-agent";
5
5
 
6
6
  export const GOAL_SETTINGS_FILE = "pi-goal.json";
7
- export const GOAL_TOOL_VISIBILITIES = ["always", "after-first-goal"] as const;
8
7
 
9
- export type GoalToolVisibility = (typeof GOAL_TOOL_VISIBILITIES)[number];
10
8
  export type ContinuationLimit = number | null;
11
9
 
12
10
  export interface GoalSettings {
13
- toolVisibility: GoalToolVisibility;
14
11
  rpc: {
15
12
  enabled: boolean;
16
13
  };
@@ -21,7 +18,6 @@ export interface GoalSettings {
21
18
  }
22
19
 
23
20
  export const DEFAULT_GOAL_SETTINGS: GoalSettings = {
24
- toolVisibility: "after-first-goal",
25
21
  rpc: { enabled: false },
26
22
  continuationLimits: { automaticTurns: 25, noProgressTurns: 3 },
27
23
  };
@@ -42,10 +38,6 @@ interface GoalSettingsSaveFileSystem {
42
38
 
43
39
  export function normalizeGoalSettings(value: unknown): GoalSettings | undefined {
44
40
  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
45
- const toolVisibility = Object.hasOwn(value, "toolVisibility")
46
- ? Reflect.get(value, "toolVisibility")
47
- : DEFAULT_GOAL_SETTINGS.toolVisibility;
48
- if (!GOAL_TOOL_VISIBILITIES.includes(toolVisibility as GoalToolVisibility)) return undefined;
49
41
 
50
42
  const rpcValue = Object.hasOwn(value, "rpc") ? Reflect.get(value, "rpc") : undefined;
51
43
  if (
@@ -86,7 +78,6 @@ export function normalizeGoalSettings(value: unknown): GoalSettings | undefined
86
78
  if (automaticTurns === undefined || noProgressTurns === undefined) return undefined;
87
79
 
88
80
  return {
89
- toolVisibility: toolVisibility as GoalToolVisibility,
90
81
  rpc: { enabled: rpcEnabled },
91
82
  continuationLimits: { automaticTurns, noProgressTurns },
92
83
  };
@@ -128,7 +119,6 @@ export function saveGoalSettings(
128
119
  const document = `${JSON.stringify(
129
120
  {
130
121
  ...raw,
131
- toolVisibility: normalized.toolVisibility,
132
122
  rpc: { ...rpc, enabled: normalized.rpc.enabled },
133
123
  continuationLimits: {
134
124
  ...continuationLimits,
@@ -1,5 +1,4 @@
1
1
  import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
2
- import type { GoalToolVisibility } from "./settings.js";
3
2
 
4
3
  export const GOAL_COMPLETE_TOOL = "goal_complete";
5
4
  export const GOAL_BLOCKED_TOOL = "goal_blocked";
@@ -7,176 +6,14 @@ export const GOAL_WAIT_TOOL = "goal_wait";
7
6
  export const GOAL_TOOL_NAMES = [GOAL_COMPLETE_TOOL, GOAL_BLOCKED_TOOL, GOAL_WAIT_TOOL] as const;
8
7
  const REQUIRED_GOAL_TOOL_NAMES = [GOAL_COMPLETE_TOOL, GOAL_BLOCKED_TOOL] as const;
9
8
 
10
- export interface GoalToolVisibilitySnapshot {
11
- activeTools: string[];
12
- goalToolsUnlocked: boolean;
13
- goalToolsHiddenByPolicy: string[];
9
+ export function goalToolsAvailable(pi: Pick<ExtensionAPI, "getActiveTools">) {
10
+ const active = new Set(pi.getActiveTools());
11
+ return REQUIRED_GOAL_TOOL_NAMES.every((name) => active.has(name));
14
12
  }
15
13
 
16
- interface ToolPolicyContext {
17
- isIdle?: () => boolean;
18
- }
19
-
20
- export class GoalToolPolicy {
21
- private unlocked = false;
22
- private readonly hiddenByPolicy = new Set<string>();
23
- private readonly pi: ExtensionAPI;
24
-
25
- constructor(pi: ExtensionAPI) {
26
- this.pi = pi;
27
- }
28
-
29
- isUnlocked() {
30
- return this.unlocked;
31
- }
32
-
33
- hasHiddenTools() {
34
- return this.hiddenByPolicy.size > 0;
35
- }
36
-
37
- isGoalToolName(name: string) {
38
- return (GOAL_TOOL_NAMES as readonly string[]).includes(name);
39
- }
40
-
41
- toolsAvailable() {
42
- const active = new Set(this.pi.getActiveTools());
43
- return REQUIRED_GOAL_TOOL_NAMES.every((name) => active.has(name));
44
- }
45
-
46
- lock() {
47
- this.unlocked = false;
48
- }
49
-
50
- unlock() {
51
- this.unlocked = true;
52
- }
53
-
54
- unlockAndForgetHidden() {
55
- this.unlocked = true;
56
- this.hiddenByPolicy.clear();
57
- }
58
-
59
- hideIfLocked() {
60
- if (this.unlocked) return;
61
- const active = this.pi.getActiveTools();
62
- const hidden = active.filter((name) => this.isGoalToolName(name));
63
- if (hidden.length === 0) return;
64
- this.pi.setActiveTools(active.filter((name) => !this.isGoalToolName(name)));
65
- for (const name of hidden) this.hiddenByPolicy.add(name);
66
- }
67
-
68
- restoreHidden() {
69
- const activeBeforeRestore = this.pi.getActiveTools();
70
- const activeSet = new Set(activeBeforeRestore);
71
- const missingOwnedTools = [...this.hiddenByPolicy].filter((name) => !activeSet.has(name));
72
- if (missingOwnedTools.length === 0) {
73
- this.hiddenByPolicy.clear();
74
- return;
75
- }
76
- try {
77
- this.pi.setActiveTools([...activeBeforeRestore, ...missingOwnedTools]);
78
- const restored = new Set(this.pi.getActiveTools());
79
- if (missingOwnedTools.some((name) => !restored.has(name))) {
80
- throw new Error("the active tool policy rejected a previously hidden goal tool");
81
- }
82
- this.hiddenByPolicy.clear();
83
- } catch (error) {
84
- this.pi.setActiveTools(activeBeforeRestore);
85
- throw error;
86
- }
87
- }
88
-
89
- prepareActivation(visibility: GoalToolVisibility, ctx: ToolPolicyContext) {
90
- if (visibility === "after-first-goal") {
91
- if (!this.toolsAvailable() && ctx.isIdle?.() !== true) {
92
- throw new Error("wait until Pi is idle before revealing the goal tools");
93
- }
94
- this.reveal();
95
- return;
96
- }
97
- if (this.hasHiddenTools()) this.restoreHidden();
98
- this.unlock();
99
- this.assertAvailable();
100
- }
101
-
102
- prepareSessionStart(visibility: GoalToolVisibility, previous: GoalToolVisibility) {
103
- if (visibility === "after-first-goal" && previous === "always") this.lock();
104
- if (visibility !== "always") return;
105
- try {
106
- if (this.hasHiddenTools()) this.restoreHidden();
107
- } finally {
108
- // Always mode remains unlocked even when an external restrictive policy
109
- // prevents restoration; retained ownership lets a later session retry.
110
- this.unlock();
111
- }
112
- }
113
-
114
- reconcileRestoredState(visibility: GoalToolVisibility, hasUnfinishedGoal: boolean) {
115
- if (visibility !== "after-first-goal") return;
116
- if (hasUnfinishedGoal) this.unlockAndForgetHidden();
117
- else if (!this.unlocked) this.hideIfLocked();
118
- }
119
-
120
- applyVisibilityChange(
121
- previous: GoalToolVisibility,
122
- next: GoalToolVisibility,
123
- hasUnfinishedGoal: boolean,
124
- ctx: ToolPolicyContext,
125
- ) {
126
- if (previous === next) return;
127
- if (next === "always") {
128
- if (this.hasHiddenTools() && ctx.isIdle?.() !== true) {
129
- throw new Error("Wait for Pi to become idle before revealing Goal tools.");
130
- }
131
- this.restoreHidden();
132
- this.unlock();
133
- return;
134
- }
135
- if (hasUnfinishedGoal) {
136
- this.unlockAndForgetHidden();
137
- return;
138
- }
139
- if (ctx.isIdle?.() !== true) {
140
- throw new Error("Wait for Pi to become idle before hiding Goal tools.");
141
- }
142
- this.lock();
143
- this.hideIfLocked();
144
- }
145
-
146
- snapshot(): GoalToolVisibilitySnapshot {
147
- return {
148
- activeTools: this.pi.getActiveTools(),
149
- goalToolsUnlocked: this.unlocked,
150
- goalToolsHiddenByPolicy: [...this.hiddenByPolicy],
151
- };
152
- }
153
-
154
- restore(snapshot: GoalToolVisibilitySnapshot) {
155
- this.pi.setActiveTools(snapshot.activeTools);
156
- this.unlocked = snapshot.goalToolsUnlocked;
157
- this.hiddenByPolicy.clear();
158
- for (const name of snapshot.goalToolsHiddenByPolicy) this.hiddenByPolicy.add(name);
159
- }
160
-
161
- private reveal() {
162
- const snapshot = this.snapshot();
163
- try {
164
- const active = this.pi.getActiveTools();
165
- const activeSet = new Set(active);
166
- const missing = GOAL_TOOL_NAMES.filter((name) => !activeSet.has(name));
167
- if (missing.length > 0) this.pi.setActiveTools([...active, ...missing]);
168
- this.assertAvailable();
169
- this.unlockAndForgetHidden();
170
- } catch (error) {
171
- this.restore(snapshot);
172
- throw error;
173
- }
174
- }
175
-
176
- private assertAvailable() {
177
- if (this.toolsAvailable()) return;
178
- throw new Error(
179
- "goal_complete and goal_blocked are unavailable; include them in the active tool allowlist or leave the restrictive tool mode first.",
180
- );
181
- }
14
+ export function assertGoalToolsAvailable(pi: Pick<ExtensionAPI, "getActiveTools">) {
15
+ if (goalToolsAvailable(pi)) return;
16
+ throw new Error(
17
+ "goal_complete and goal_blocked are unavailable; include them in the active tool allowlist or leave the restrictive tool mode first.",
18
+ );
182
19
  }