pi-onlooker 0.1.1 → 0.1.3

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.
Files changed (29) hide show
  1. package/CHANGELOG.md +13 -0
  2. package/README.md +1 -1
  3. package/extensions/index.ts +74 -60
  4. package/node_modules/pi-hl-utils/LICENSE +21 -0
  5. package/node_modules/pi-hl-utils/package.json +47 -0
  6. package/node_modules/pi-hl-utils/src/errors.ts +9 -0
  7. package/{src/utils → node_modules/pi-hl-utils/src}/layered-settings.ts +194 -55
  8. package/{src/utils → node_modules/pi-hl-utils/src}/null-optional-arguments.ts +20 -19
  9. package/{src/utils → node_modules/pi-hl-utils/src}/pi-agent-session-discovery.ts +3 -1
  10. package/node_modules/pi-hl-utils/src/record.ts +3 -0
  11. package/node_modules/pi-hl-utils/src/settings-command.ts +213 -0
  12. package/node_modules/pi-hl-utils/src/settings-menu.ts +477 -0
  13. package/package.json +7 -1
  14. package/skills/pi-onlooker/SKILL.md +2 -2
  15. package/src/onlooker-calibration.ts +1 -2
  16. package/src/onlooker-command.ts +9 -33
  17. package/src/onlooker-contract.ts +0 -1
  18. package/src/onlooker-evidence.ts +3 -4
  19. package/src/onlooker-menu.ts +89 -227
  20. package/src/onlooker-observer.ts +31 -18
  21. package/src/onlooker-rendering.ts +56 -29
  22. package/src/onlooker-settings.ts +5 -53
  23. package/src/protected-tools.ts +2 -1
  24. package/src/utils/settings-command.ts +0 -92
  25. package/src/utils/settings-menu.ts +0 -258
  26. /package/{src/utils → node_modules/pi-hl-utils/src}/evidence.ts +0 -0
  27. /package/{src/utils → node_modules/pi-hl-utils/src}/expand-on-click.ts +0 -0
  28. /package/{src/utils → node_modules/pi-hl-utils/src}/token-calibration.ts +0 -0
  29. /package/{src/utils → node_modules/pi-hl-utils/src}/ui.ts +0 -0
package/CHANGELOG.md CHANGED
@@ -2,6 +2,19 @@
2
2
 
3
3
  Pi shows the entries newer than your installed version after `pi update`.
4
4
 
5
+ ## 0.1.3
6
+
7
+ ### Patch Changes
8
+
9
+ - A Review that passes its 120 s deadline no longer pauses the Onlooker. The next turn's Review covers its turns instead, and the Onlooker pauses only after 3 late Reviews in a row.
10
+ - Text from the reviewer model, provider errors and settings now shows without terminal control sequences, so it can no longer change the window title, clear the screen or add hidden links. Line breaks and tabs stay.
11
+
12
+ ## 0.1.2
13
+
14
+ ### Patch Changes
15
+
16
+ - An unknown key in the `onlooker` settings entry is now reported as `unknown option <key>`. In the `/onlooker` menu, two quick presses on a cycled row now advance it twice instead of writing the same value twice.
17
+
5
18
  ## 0.1.1
6
19
 
7
20
  ### Patch Changes
package/README.md CHANGED
@@ -146,7 +146,7 @@ Run `/onlooker status` first. It shows the error and the counts of withheld and
146
146
 
147
147
  **`Onlooker model is unavailable: ...`**: set a model from `/model`, or run `/onlooker inherit model`.
148
148
 
149
- **`Onlooker review deadline exceeded`**: pick a faster `model` or a lower `thinkingLevel`, then run `/onlooker on`.
149
+ **`Onlooker review deadline exceeded`**: 3 Reviews in a row passed their 120 s deadline. A single late Review is left to the next turn. Pick a faster `model` or a lower `thinkingLevel`, then run `/onlooker on`.
150
150
 
151
151
  **`Onlooker project settings require a trusted project`**: trust the project, or use `--global`.
152
152
 
@@ -5,12 +5,21 @@ import type {
5
5
  ExtensionContext,
6
6
  ExtensionUIContext,
7
7
  } from "@earendil-works/pi-coding-agent";
8
+ import { errorText } from "pi-hl-utils/errors";
9
+ import { expandEntryOnClick, expandMessageOnClick } from "pi-hl-utils/expand-on-click";
10
+ import { layeredMenuScopes } from "pi-hl-utils/layered-settings";
11
+ import { acceptNullForOptionalArguments } from "pi-hl-utils/null-optional-arguments";
12
+ import { discoverPiAgentSession } from "pi-hl-utils/pi-agent-session-discovery";
13
+ import { registerSettingsCommand } from "pi-hl-utils/settings-command";
14
+ import { SettingsMenu } from "pi-hl-utils/settings-menu";
15
+ import { noticeText } from "pi-hl-utils/ui";
8
16
  import { Type } from "typebox";
9
17
 
10
- import { completeOnlookerCommandArguments, parseOnlookerCommand } from "../src/onlooker-command.js";
18
+ import { onlookerCommandSpec } from "../src/onlooker-command.js";
11
19
  import {
12
- OnlookerSettingsMenu,
20
+ onlookerMenuSpec,
13
21
  type OnlookerMenuHost,
22
+ type OnlookerMenuView,
14
23
  type OnlookerScopedOptions,
15
24
  } from "../src/onlooker-menu.js";
16
25
  import { OnlookerObserver } from "../src/onlooker-observer.js";
@@ -28,20 +37,13 @@ import {
28
37
  } from "../src/onlooker-rendering.js";
29
38
  import { isOnlookerSession } from "../src/onlooker-session.js";
30
39
  import {
31
- readOnlookerLayers,
32
- readOnlookerOverrides,
33
- readOnlookerSettings,
34
- writeOnlookerSettings,
40
+ onlookerSettings,
35
41
  type OnlookerLayers,
36
42
  type OnlookerChange,
37
43
  type OnlookerAppliedChange,
38
44
  type OnlookerSettingScope,
39
45
  } from "../src/onlooker-settings.js";
40
46
  import { TROUBLESHOOTING_HINT } from "../src/troubleshooting-skill.js";
41
- import { expandEntryOnClick, expandMessageOnClick } from "../src/utils/expand-on-click.js";
42
- import { acceptNullForOptionalArguments } from "../src/utils/null-optional-arguments.js";
43
- import { discoverPiAgentSession } from "../src/utils/pi-agent-session-discovery.js";
44
- import { noticeText } from "../src/utils/ui.js";
45
47
 
46
48
  const askToolParameters = Type.Object(
47
49
  { message: Type.String({ minLength: 1 }) },
@@ -122,7 +124,11 @@ export default function onlooker(pi: ExtensionAPI): void {
122
124
  renderResult: (result, options, theme, context) =>
123
125
  renderOnlookerAskResult(
124
126
  result.content.map((item) => (item.type === "text" ? item.text : "")).join(""),
125
- { expanded: options.expanded, isPartial: options.isPartial, isError: context.isError },
127
+ {
128
+ expanded: options.expanded,
129
+ isPartial: options.isPartial,
130
+ isError: context.isError,
131
+ },
126
132
  theme,
127
133
  context,
128
134
  ),
@@ -138,7 +144,7 @@ export default function onlooker(pi: ExtensionAPI): void {
138
144
  } catch (cause) {
139
145
  // Caller cancellation is not a malfunction the Skill diagnoses.
140
146
  if (signal?.aborted) throw cause;
141
- const text = cause instanceof Error ? cause.message : String(cause);
147
+ const text = errorText(cause);
142
148
  throw new Error(`${text}\n\n${TROUBLESHOOTING_HINT}`, { cause });
143
149
  }
144
150
  },
@@ -182,7 +188,7 @@ export default function onlooker(pi: ExtensionAPI): void {
182
188
  const found = discoverPiAgentSession(pi, piSdk.AgentSession);
183
189
  if (found.ok) {
184
190
  observed = found.session;
185
- layers = readOnlookerLayers(observed.settingsManager);
191
+ layers = onlookerSettings.readLayers(observed.settingsManager);
186
192
  await refresh(ctx);
187
193
  } else {
188
194
  error = found.warning;
@@ -215,7 +221,7 @@ export default function onlooker(pi: ExtensionAPI): void {
215
221
  async function refresh(ctx: ExtensionContext): Promise<void> {
216
222
  if (!observed || privateSession) return;
217
223
  try {
218
- const { settings } = readOnlookerSettings(observed, layers);
224
+ const { settings } = onlookerSettings.readSettings(observed, layers);
219
225
  displayName = settings.name;
220
226
  if (observer) observer.configure(settings);
221
227
  else
@@ -237,7 +243,7 @@ export default function onlooker(pi: ExtensionAPI): void {
237
243
  );
238
244
  setAskToolAvailable(settings.enabled);
239
245
  } catch (cause) {
240
- error = cause instanceof Error ? cause.message : String(cause);
246
+ error = errorText(cause);
241
247
  setAskToolAvailable(true);
242
248
  await observer?.dispose();
243
249
  observer = undefined;
@@ -247,7 +253,7 @@ export default function onlooker(pi: ExtensionAPI): void {
247
253
 
248
254
  /** Current effective settings and live Onlooker state, as recorded in status entries. */
249
255
  function statusData(subject: AgentSession): OnlookerStatusEntry {
250
- const resolved = readOnlookerSettings(subject, layers);
256
+ const resolved = onlookerSettings.readSettings(subject, layers);
251
257
  const live = observer?.status ?? idleStatus(resolved.settings.enabled);
252
258
  return { ...resolved, ...live, error: error ?? live.lastError };
253
259
  }
@@ -259,8 +265,13 @@ export default function onlooker(pi: ExtensionAPI): void {
259
265
  if (changes.length) entry.changes = [...changes];
260
266
  pi.appendEntry("pi-onlooker-status", entry);
261
267
  } catch (cause) {
262
- error = cause instanceof Error ? cause.message : String(cause);
263
- pi.appendEntry("pi-onlooker-status", { state: "paused", error, usage: null, cost: null });
268
+ error = errorText(cause);
269
+ pi.appendEntry("pi-onlooker-status", {
270
+ state: "paused",
271
+ error,
272
+ usage: null,
273
+ cost: null,
274
+ });
264
275
  }
265
276
  if (error) ctx.ui.notify(noticeText(displayName, error), "error");
266
277
  }
@@ -273,24 +284,16 @@ export default function onlooker(pi: ExtensionAPI): void {
273
284
  change: OnlookerChange,
274
285
  isCurrent: () => boolean,
275
286
  ): Promise<OnlookerAppliedChange | undefined> {
276
- if (scope === "session") {
277
- const overrides = readOnlookerOverrides(subject.sessionManager);
278
- if (change.action === "inherit") delete overrides[change.key];
279
- else Object.assign(overrides, change.patch);
280
- pi.appendEntry("pi-onlooker-settings", { version: 1, overrides });
281
- } else {
282
- const updated = await writeOnlookerSettings(
283
- subject.settingsManager,
284
- scope,
285
- change,
286
- isCurrent,
287
- );
288
- if (!isCurrent() || !updated) return undefined;
289
- layers[scope] = updated;
290
- }
287
+ const updated = await onlookerSettings.writeChange(pi, subject, scope, change, isCurrent);
288
+ if (!isCurrent() || !updated) return undefined;
289
+ if (scope !== "session") layers[scope] = updated;
291
290
  error = undefined;
292
291
  await refresh(ctx);
293
- return { scope, key: change.key, options: change.action === "inherit" ? {} : change.patch };
292
+ return {
293
+ scope,
294
+ key: change.key,
295
+ options: change.action === "inherit" ? {} : change.patch,
296
+ };
294
297
  }
295
298
 
296
299
  /** The settings menu's view of this extension's settings authority. */
@@ -304,16 +307,14 @@ export default function onlooker(pi: ExtensionAPI): void {
304
307
  view() {
305
308
  const data = statusData(subject);
306
309
  const authored: Partial<OnlookerScopedOptions> = {
307
- session: readOnlookerOverrides(subject.sessionManager),
310
+ session: onlookerSettings.readOverrides(subject.sessionManager),
308
311
  };
309
312
  if (!(layers.project instanceof Error)) authored.project = layers.project;
310
313
  if (!(layers.global instanceof Error)) authored.global = layers.global;
311
314
  return {
312
315
  headline: onlookerStatusHeadline(data, theme),
313
316
  paused: data.state === "paused",
314
- scopes: subject.settingsManager.isProjectTrusted()
315
- ? ["session", "project", "global"]
316
- : ["session", "global"],
317
+ scopes: layeredMenuScopes(subject.settingsManager),
317
318
  settings: data.settings ?? {},
318
319
  sources: data.sources ?? {},
319
320
  authored,
@@ -342,10 +343,10 @@ export default function onlooker(pi: ExtensionAPI): void {
342
343
  async function openMenu(ctx: ExtensionContext, subject: AgentSession): Promise<void> {
343
344
  const applied: OnlookerAppliedChange[] = [];
344
345
  let discarded = false;
345
- let menu: OnlookerSettingsMenu | undefined;
346
+ let menu: SettingsMenu<OnlookerMenuView, OnlookerChange> | undefined;
346
347
  await ctx.ui.custom<void>((tui, theme, _keybindings, done) => {
347
- const opened = new OnlookerSettingsMenu(
348
- menuHost(ctx, subject, theme, applied),
348
+ const opened = new SettingsMenu(
349
+ onlookerMenuSpec(menuHost(ctx, subject, theme, applied)),
349
350
  {
350
351
  tui,
351
352
  theme,
@@ -372,39 +373,52 @@ export default function onlooker(pi: ExtensionAPI): void {
372
373
  if (!discarded && observed === subject && applied.length) status(ctx, applied);
373
374
  }
374
375
 
375
- pi.registerCommand("onlooker", {
376
+ registerSettingsCommand(pi, {
377
+ name: "onlooker",
376
378
  description: "Onlooker settings menu, or on, off, inherit, set, and status",
377
- getArgumentCompletions: completeOnlookerCommandArguments,
378
- async handler(args, ctx) {
379
+ optionKeys: onlookerSettings.optionKeys,
380
+ parse: onlookerCommandSpec,
381
+ start(ctx) {
379
382
  if (privateSession) {
380
383
  pi.appendEntry("pi-onlooker-status", {
381
384
  state: "private",
382
385
  error: "Private Onlooker Sessions cannot create another Onlooker",
383
386
  });
384
- return;
387
+ return undefined;
385
388
  }
386
389
  const subject = observed;
387
390
  let stamp = generation;
388
391
  const isCurrent = () => generation === stamp && observed === subject;
389
392
  let applied: OnlookerAppliedChange | undefined;
390
- try {
393
+ const showStatus = () => {
394
+ if (isCurrent()) status(ctx, applied ? [applied] : []);
395
+ };
396
+ // Checked before the parse, so an unavailable session is reported before a usage error.
397
+ const requireSubject = (): AgentSession => {
391
398
  if (!subject) throw new Error(error ?? "Onlooker session is unavailable");
392
- const command = parseOnlookerCommand(args);
393
- if (command.action === "menu" && ctx.mode === "tui") {
399
+ return subject;
400
+ };
401
+ return {
402
+ check: requireSubject,
403
+ status: showStatus,
404
+ async menu() {
405
+ const session = requireSubject();
394
406
  // Opening fails closed to the status entry when settings cannot be read.
395
- statusData(subject);
396
- await openMenu(ctx, subject);
397
- return;
398
- }
399
- if (command.action !== "status" && command.action !== "menu") {
407
+ statusData(session);
408
+ await openMenu(ctx, session);
409
+ },
410
+ async change(command) {
411
+ const session = requireSubject();
400
412
  stamp = ++generation;
401
- applied = await applyChange(ctx, subject, command.scope, command, isCurrent);
402
- }
403
- } catch (cause) {
404
- if (!isCurrent()) return;
405
- error = cause instanceof Error ? cause.message : String(cause);
406
- }
407
- if (isCurrent()) status(ctx, applied ? [applied] : []);
413
+ applied = await applyChange(ctx, session, command.scope, command, isCurrent);
414
+ showStatus();
415
+ },
416
+ fail(cause) {
417
+ if (!isCurrent()) return;
418
+ error = errorText(cause);
419
+ showStatus();
420
+ },
421
+ };
408
422
  },
409
423
  });
410
424
  }
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Hugo Lopes
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,47 @@
1
+ {
2
+ "name": "pi-hl-utils",
3
+ "version": "0.0.0",
4
+ "private": true,
5
+ "description": "Shared code for the Pi extensions of this repository.",
6
+ "license": "MIT",
7
+ "files": [
8
+ "src"
9
+ ],
10
+ "type": "module",
11
+ "exports": {
12
+ "./errors": "./src/errors.ts",
13
+ "./evidence": "./src/evidence.ts",
14
+ "./expand-on-click": "./src/expand-on-click.ts",
15
+ "./layered-settings": "./src/layered-settings.ts",
16
+ "./null-optional-arguments": "./src/null-optional-arguments.ts",
17
+ "./pi-agent-session-discovery": "./src/pi-agent-session-discovery.ts",
18
+ "./record": "./src/record.ts",
19
+ "./settings-command": "./src/settings-command.ts",
20
+ "./settings-menu": "./src/settings-menu.ts",
21
+ "./token-calibration": "./src/token-calibration.ts",
22
+ "./ui": "./src/ui.ts",
23
+ "./testing/*": "./testing/*.ts"
24
+ },
25
+ "scripts": {
26
+ "check": "tsc --noEmit && vitest --run"
27
+ },
28
+ "devDependencies": {
29
+ "@earendil-works/pi-ai": "^1.5.2",
30
+ "@earendil-works/pi-coding-agent": "^1.5.2",
31
+ "@earendil-works/pi-tui": "^1.5.2",
32
+ "@types/node": "^26.6.6",
33
+ "typebox": "^1.4.3",
34
+ "typescript": "^7.0.2",
35
+ "vitest": "^5.0.3"
36
+ },
37
+ "peerDependencies": {
38
+ "@earendil-works/pi-ai": "*",
39
+ "@earendil-works/pi-coding-agent": "*",
40
+ "@earendil-works/pi-tui": "*",
41
+ "typebox": "*"
42
+ },
43
+ "engines": {
44
+ "node": ">=22.19.0",
45
+ "pi": ">=1.0.3"
46
+ }
47
+ }
@@ -0,0 +1,9 @@
1
+ /** A thrown value's message, or its string form. */
2
+ export function errorText(cause: unknown): string {
3
+ return cause instanceof Error ? cause.message : String(cause);
4
+ }
5
+
6
+ /** Whether a thrown value is a file system error for a missing path. */
7
+ export function isMissingFileError(cause: unknown): boolean {
8
+ return cause instanceof Error && "code" in cause && cause.code === "ENOENT";
9
+ }