@narumitw/pi-goal 0.27.1 → 0.28.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/README.md CHANGED
@@ -54,7 +54,8 @@ pi -e ./extensions/pi-goal
54
54
 
55
55
  ## ⚙️ Configuration
56
56
 
57
- Configuration is optional. Create `~/.pi/agent/pi-goal.json` only when overriding the defaults:
57
+ On the first session start, pi-goal automatically creates `~/.pi/agent/pi-goal.json`
58
+ with the complete current defaults:
58
59
 
59
60
  ```json
60
61
  {
@@ -69,6 +70,8 @@ Configuration is optional. Create `~/.pi/agent/pi-goal.json` only when overridin
69
70
  }
70
71
  ```
71
72
 
73
+ Edit this generated file only when overriding the defaults.
74
+
72
75
  `toolVisibility` accepts:
73
76
 
74
77
  - `"always"` (default) — pi-goal does not proactively hide `goal_complete` or `goal_blocked`, keeping the tool schema stable from session startup.
@@ -82,8 +85,16 @@ Configuration is optional. Create `~/.pi/agent/pi-goal.json` only when overridin
82
85
  - `noProgressTurns` is a positive safe integer and defaults to `3`. At the end of an automatic run, pi-goal compares visible assistant text after Unicode normalization, lowercasing, control-character removal, and whitespace collapse. Thinking and tool blocks are excluded; empty and punctuation-only output are equivalent. Consecutive empty or identical tool-free outputs increment the repeat count. Different non-empty output starts a new run at one, and any attempted tool call resets it. Set this field to `null` to disable only this heuristic.
83
86
 
84
87
  Settings are reread at Pi startup, session replacement, and `/reload`; the file is not watched live.
88
+ A missing file is created during any of those session starts, while an existing file is read without
89
+ being rewritten. Initialization publishes the generated file atomically and never overwrites a file
90
+ created concurrently by another process.
85
91
 
86
- Missing settings and omitted fields use the defaults above. Invalid settings produce a warning and fall back to all defaults; pi-goal never creates the file automatically. Reload Pi after changing the file. 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.
92
+ Omitted fields use the defaults above. Invalid or malformed existing settings are never overwritten;
93
+ they produce a warning and fall back to all defaults. If the default file cannot be created, pi-goal
94
+ warns, continues with the built-in defaults, and retries on the next session start. Reload Pi after
95
+ changing the file. If a live runtime reloads settings, switching `toolVisibility` to `"always"`
96
+ restores only the exact tools that pi-goal previously hid, while switching to
97
+ `"after-first-goal"` locks a runtime that has no unfinished goal.
87
98
 
88
99
  Tool visibility is a baseline, not ownership of Pi's global active-tool list. 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 both tools cannot be made available, and an already-active goal is paused without automatic continuation if they disappear. 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.
89
100
 
@@ -226,7 +237,8 @@ Whenever pi-goal persists canonical goal state, it emits `pi-goal:state` with `{
226
237
  ```txt
227
238
  extensions/pi-goal/
228
239
  ├── src/
229
- │ ├── goal.ts # Pi entrypoint, tool contracts, and lifecycle orchestration
240
+ │ ├── index.ts # Pi package entrypoint
241
+ │ ├── goal.ts # Tool contracts and lifecycle orchestration
230
242
  │ ├── commands.ts # Per-factory user-command and queue mutation controller
231
243
  │ ├── runtime.ts # Per-factory state, prompt ownership, budgets, and tool policy
232
244
  │ ├── safety.ts # Output normalization and no-progress fingerprint state
@@ -241,12 +253,12 @@ extensions/pi-goal/
241
253
  └── package.json
242
254
  ```
243
255
 
244
- Only `goal.ts` is a Pi entrypoint; the other source modules are internal. The package exposes its Pi extension through `package.json`:
256
+ `index.ts` is the Pi entrypoint and forwards to `goal.ts`; the other source modules are internal. The package exposes its Pi extension through `package.json`:
245
257
 
246
258
  ```json
247
259
  {
248
260
  "pi": {
249
- "extensions": ["./src/goal.ts"]
261
+ "extensions": ["./src/index.ts"]
250
262
  }
251
263
  }
252
264
  ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@narumitw/pi-goal",
3
- "version": "0.27.1",
3
+ "version": "0.28.0",
4
4
  "description": "Pi extension for autonomous /goal completion with opt-in experimental ordered queues.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -20,7 +20,7 @@
20
20
  ],
21
21
  "pi": {
22
22
  "extensions": [
23
- "./src/goal.ts"
23
+ "./src/index.ts"
24
24
  ]
25
25
  },
26
26
  "scripts": {
package/src/goal.ts CHANGED
@@ -30,7 +30,7 @@ import {
30
30
  truncateNotification,
31
31
  } from "./runtime.js";
32
32
  import { hasAssistantToolCall } from "./safety.js";
33
- import { DEFAULT_GOAL_SETTINGS, readGoalSettings } from "./settings.js";
33
+ import { DEFAULT_GOAL_SETTINGS, loadOrCreateGoalSettings } from "./settings.js";
34
34
 
35
35
  // goal.ts is the Pi-facing composition root: it keeps tool contracts and event
36
36
  // ordering together. Per-session mechanisms live in runtime.ts, while user command
@@ -52,6 +52,7 @@ interface GoalBlockedDetails {
52
52
 
53
53
  interface GoalOptions {
54
54
  settingsPath?: string;
55
+ settingsFileSystem?: Parameters<typeof loadOrCreateGoalSettings>[1];
55
56
  }
56
57
 
57
58
  const EXPERIMENTAL_GOALS_WARNING =
@@ -472,7 +473,10 @@ function registerGoalRuntime(pi: ExtensionAPI, options: GoalOptions = {}) {
472
473
  runtime.clearTerminalDetails();
473
474
  rpc.bindSession(ctx);
474
475
  const previousToolVisibility = runtime.settings.toolVisibility;
475
- const settingsResult = readGoalSettings(options.settingsPath);
476
+ const settingsResult = loadOrCreateGoalSettings(
477
+ options.settingsPath,
478
+ options.settingsFileSystem,
479
+ );
476
480
  runtime.settings =
477
481
  settingsResult.kind === "loaded" ? settingsResult.settings : DEFAULT_GOAL_SETTINGS;
478
482
  if (settingsResult.kind === "invalid") {
@@ -480,6 +484,11 @@ function registerGoalRuntime(pi: ExtensionAPI, options: GoalOptions = {}) {
480
484
  `pi-goal settings ignored: ${settingsResult.reason}. Using default settings.`,
481
485
  "warning",
482
486
  );
487
+ } else if (settingsResult.kind === "create-failed") {
488
+ ctx.ui.notify(
489
+ `Could not create pi-goal settings: ${settingsResult.reason}. Using default settings.`,
490
+ "warning",
491
+ );
483
492
  }
484
493
  if (runtime.settings.experimental.goals) {
485
494
  ctx.ui.notify(EXPERIMENTAL_GOALS_WARNING, "warning");
package/src/index.ts ADDED
@@ -0,0 +1 @@
1
+ export { default } from "./goal.js";
package/src/settings.ts CHANGED
@@ -1,5 +1,6 @@
1
- import { readFileSync } from "node:fs";
2
- import { join } from "node:path";
1
+ import { randomUUID } from "node:crypto";
2
+ import { linkSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
3
+ import { basename, dirname, join } from "node:path";
3
4
  import { getAgentDir } from "@earendil-works/pi-coding-agent";
4
5
 
5
6
  export const GOAL_SETTINGS_FILE = "pi-goal.json";
@@ -25,11 +26,24 @@ export const DEFAULT_GOAL_SETTINGS: GoalSettings = {
25
26
  continuationLimits: { automaticTurns: 25, noProgressTurns: 3 },
26
27
  };
27
28
 
29
+ export const DEFAULT_GOAL_SETTINGS_DOCUMENT = `${JSON.stringify(DEFAULT_GOAL_SETTINGS, null, 2)}\n`;
30
+
28
31
  export type GoalSettingsLoadResult =
29
32
  | { kind: "missing" }
30
33
  | { kind: "invalid"; reason: string }
31
34
  | { kind: "loaded"; settings: GoalSettings };
32
35
 
36
+ export type GoalSettingsInitializationResult =
37
+ | Exclude<GoalSettingsLoadResult, { kind: "missing" }>
38
+ | { kind: "create-failed"; reason: string };
39
+
40
+ interface GoalSettingsInitializationFileSystem {
41
+ mkdirSync: typeof mkdirSync;
42
+ writeFileSync: typeof writeFileSync;
43
+ linkSync: typeof linkSync;
44
+ rmSync: typeof rmSync;
45
+ }
46
+
33
47
  export function normalizeGoalSettings(value: unknown): GoalSettings | undefined {
34
48
  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
35
49
  const toolVisibility = Object.hasOwn(value, "toolVisibility")
@@ -95,6 +109,51 @@ function normalizeContinuationLimit(
95
109
  return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : undefined;
96
110
  }
97
111
 
112
+ export function loadOrCreateGoalSettings(
113
+ settingsPath = join(getAgentDir(), GOAL_SETTINGS_FILE),
114
+ overrides: Partial<GoalSettingsInitializationFileSystem> = {},
115
+ ): GoalSettingsInitializationResult {
116
+ const loaded = readGoalSettings(settingsPath);
117
+ if (loaded.kind !== "missing") return loaded;
118
+
119
+ const fs = { mkdirSync, writeFileSync, linkSync, rmSync, ...overrides };
120
+ const temporaryPath = join(
121
+ dirname(settingsPath),
122
+ `.${basename(settingsPath)}.${randomUUID()}.tmp`,
123
+ );
124
+ try {
125
+ fs.mkdirSync(dirname(settingsPath), { recursive: true });
126
+ fs.writeFileSync(temporaryPath, DEFAULT_GOAL_SETTINGS_DOCUMENT, {
127
+ encoding: "utf8",
128
+ flag: "wx",
129
+ });
130
+ try {
131
+ fs.linkSync(temporaryPath, settingsPath);
132
+ } catch (error) {
133
+ if (!isAlreadyExistsError(error)) throw error;
134
+ }
135
+
136
+ const published = readGoalSettings(settingsPath);
137
+ return published.kind === "missing"
138
+ ? {
139
+ kind: "create-failed",
140
+ reason: `${settingsPath}: settings file disappeared during initialization`,
141
+ }
142
+ : published;
143
+ } catch (error) {
144
+ return {
145
+ kind: "create-failed",
146
+ reason: `${settingsPath}: ${formatError(error)}`,
147
+ };
148
+ } finally {
149
+ try {
150
+ fs.rmSync(temporaryPath, { force: true });
151
+ } catch {
152
+ // Best-effort cleanup must not replace the initialization result.
153
+ }
154
+ }
155
+ }
156
+
98
157
  export function readGoalSettings(
99
158
  settingsPath = join(getAgentDir(), GOAL_SETTINGS_FILE),
100
159
  ): GoalSettingsLoadResult {
@@ -120,6 +179,10 @@ function isNodeError(error: unknown): error is NodeJS.ErrnoException {
120
179
  return error instanceof Error && "code" in error;
121
180
  }
122
181
 
182
+ function isAlreadyExistsError(error: unknown): boolean {
183
+ return isNodeError(error) && error.code === "EEXIST";
184
+ }
185
+
123
186
  function formatError(error: unknown) {
124
187
  return error instanceof Error ? error.message : String(error);
125
188
  }