@xingular/harness 1.3.1-unstable.4 → 1.3.1-unstable.8

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 (150) hide show
  1. package/CHANGELOG.md +74 -0
  2. package/README.md +14 -9
  3. package/dist/cli.js +1734 -796
  4. package/dist/sdk/accounts/choices.d.ts +18 -0
  5. package/dist/sdk/accounts/choices.js +27 -0
  6. package/dist/sdk/cli.js +4 -0
  7. package/dist/sdk/commands/extensionOwners.d.ts +4 -0
  8. package/dist/sdk/commands/extensionOwners.js +17 -0
  9. package/dist/sdk/commands/list.js +15 -2
  10. package/dist/sdk/commands/promptLoader.d.ts +5 -0
  11. package/dist/sdk/commands/promptLoader.js +76 -0
  12. package/dist/sdk/commands/promptRoutes.d.ts +13 -0
  13. package/dist/sdk/commands/promptRoutes.js +46 -0
  14. package/dist/sdk/commands/registry.d.ts +14 -0
  15. package/dist/sdk/commands/registry.js +2 -0
  16. package/dist/sdk/commands/runtimeRouter.d.ts +4 -0
  17. package/dist/sdk/commands/runtimeRouter.js +48 -0
  18. package/dist/sdk/computer/boundary.d.ts +40 -0
  19. package/dist/sdk/computer/boundary.js +79 -0
  20. package/dist/sdk/computer/contracts.d.ts +127 -0
  21. package/dist/sdk/computer/contracts.js +13 -0
  22. package/dist/sdk/computer/control.d.ts +34 -0
  23. package/dist/sdk/computer/control.js +112 -0
  24. package/dist/sdk/computer/terminalCapture.d.ts +26 -0
  25. package/dist/sdk/computer/terminalCapture.js +64 -0
  26. package/dist/sdk/computer/volatileImages.d.ts +9 -0
  27. package/dist/sdk/computer/volatileImages.js +50 -0
  28. package/dist/sdk/context/runDetails.d.ts +16 -0
  29. package/dist/sdk/context/runDetails.js +22 -0
  30. package/dist/sdk/doctor/checks.js +3 -0
  31. package/dist/sdk/doctor/probe.js +8 -6
  32. package/dist/sdk/harness.d.ts +8 -0
  33. package/dist/sdk/harness.js +7 -4
  34. package/dist/sdk/history/trajectory.js +2 -0
  35. package/dist/sdk/hub/hub.js +1 -1
  36. package/dist/sdk/hub/schema.d.ts +2 -2
  37. package/dist/sdk/plugins/manifest.d.ts +2 -0
  38. package/dist/sdk/plugins/manifest.js +1 -0
  39. package/dist/sdk/prompt/compile.d.ts +3 -1
  40. package/dist/sdk/prompt/compile.js +10 -7
  41. package/dist/sdk/refine/host.d.ts +9 -1
  42. package/dist/sdk/refine/host.js +29 -0
  43. package/dist/sdk/refine/prompts.d.ts +15 -0
  44. package/dist/sdk/refine/prompts.js +44 -0
  45. package/dist/sdk/refine/recursion.js +4 -4
  46. package/dist/sdk/refine/runner.d.ts +2 -0
  47. package/dist/sdk/refine/runner.js +2 -1
  48. package/dist/sdk/refine/serverMethods.js +4 -1
  49. package/dist/sdk/refine/service.d.ts +31 -0
  50. package/dist/sdk/refine/service.js +119 -4
  51. package/dist/sdk/refine/trajectory.js +7 -2
  52. package/dist/sdk/refine/types.d.ts +16 -0
  53. package/dist/sdk/remote/webClient.js +7 -3
  54. package/dist/sdk/server/methods.js +31 -1
  55. package/dist/sdk/sessions/compactionCheckpoint.d.ts +6 -1
  56. package/dist/sdk/sessions/compactionCheckpoint.js +34 -35
  57. package/dist/sdk/sessions/contracts.d.ts +141 -2
  58. package/dist/sdk/sessions/contracts.js +115 -3
  59. package/dist/sdk/sessions/planMode.d.ts +1 -1
  60. package/dist/sdk/sessions/planMode.js +7 -4
  61. package/dist/sdk/sessions/registry.d.ts +6 -2
  62. package/dist/sdk/sessions/registry.js +16 -13
  63. package/dist/sdk/sessions/runStore.d.ts +3 -1
  64. package/dist/sdk/sessions/runStore.js +26 -8
  65. package/dist/sdk/sessions/runner.d.ts +5 -5
  66. package/dist/sdk/sessions/runner.js +78 -15
  67. package/dist/sdk/sessions/sessions.js +35 -21
  68. package/dist/sdk/sessions/workSlice.d.ts +2 -0
  69. package/dist/sdk/sessions/workSlice.js +4 -3
  70. package/dist/sdk/terminal/client.d.ts +3 -0
  71. package/dist/sdk/terminal/client.js +13 -0
  72. package/dist/sdk/terminal/controller.d.ts +2 -0
  73. package/dist/sdk/terminal/controller.js +12 -6
  74. package/dist/sdk/terminal/opentui/theme.d.ts +2 -0
  75. package/dist/sdk/terminal/opentui/theme.js +4 -0
  76. package/dist/sdk/terminal/piExtension.js +73 -13
  77. package/dist/sdk/terminal/standalone.d.ts +6 -1
  78. package/dist/sdk/terminal/standalone.js +30 -3
  79. package/dist/sdk/terminal/terminals.d.ts +11 -1
  80. package/dist/sdk/terminal/terminals.js +58 -5
  81. package/dist/sdk/terminal/trajectory.js +2 -2
  82. package/dist/sdk/terminal/tui/commandPages.d.ts +1 -1
  83. package/dist/sdk/terminal/tui/commandPages.js +4 -2
  84. package/dist/sdk/terminal/tui/commands.js +29 -65
  85. package/dist/sdk/terminal/tui/modeChoices.d.ts +18 -0
  86. package/dist/sdk/terminal/tui/modeChoices.js +26 -1
  87. package/dist/sdk/terminal/tui/pages/contextPage.d.ts +30 -1
  88. package/dist/sdk/terminal/tui/pages/contextPage.js +109 -8
  89. package/dist/sdk/terminal/tui/pages/textPage.d.ts +17 -0
  90. package/dist/sdk/terminal/tui/pages/textPage.js +52 -0
  91. package/dist/sdk/terminal/tui/pages/trajectoryPage.d.ts +1 -0
  92. package/dist/sdk/terminal/tui/pages/trajectoryPage.js +12 -3
  93. package/dist/sdk/terminal/tui/runtime.js +60 -3
  94. package/dist/sdk/terminal/tui/sideQuestion.d.ts +3 -0
  95. package/dist/sdk/terminal/tui/sideQuestion.js +7 -1
  96. package/dist/sdk/terminal/tui/status.d.ts +0 -6
  97. package/dist/sdk/terminal/tui/status.js +1 -15
  98. package/dist/sdk/terminal/tui/variantCommands.d.ts +32 -0
  99. package/dist/sdk/terminal/tui/variantCommands.js +359 -0
  100. package/dist/sdk/terminal/variantControl.d.ts +24 -0
  101. package/dist/sdk/terminal/variantControl.js +145 -0
  102. package/dist/sdk/tools/definitions.js +1 -1
  103. package/dist/sdk/tools/dispatch.d.ts +1 -1
  104. package/dist/sdk/tools/dispatch.js +17 -3
  105. package/dist/sdk/variant/store.d.ts +33 -1
  106. package/dist/sdk/variant/store.js +108 -3
  107. package/dist/sdk/worktrees/git.d.ts +2 -0
  108. package/dist/sdk/worktrees/git.js +8 -0
  109. package/dist/sdk/worktrees/snapshot.d.ts +16 -0
  110. package/dist/sdk/worktrees/snapshot.js +83 -0
  111. package/dist/sdk/world/actions.js +1 -1
  112. package/dist/terminal-opentui.js +1643 -451
  113. package/dist/terminal-pi.js +179 -56
  114. package/docs/architecture/02-sessions-and-runs.md +33 -13
  115. package/docs/architecture/03-variants.md +24 -3
  116. package/docs/architecture/04-prompt.md +22 -11
  117. package/docs/architecture/05-refinement.md +32 -5
  118. package/docs/architecture/06-plugins-and-capabilities.md +13 -2
  119. package/docs/architecture/07-tools-and-gate.md +14 -0
  120. package/docs/architecture/08-memory-and-history.md +7 -3
  121. package/docs/architecture/09-accounts-and-connectors.md +13 -3
  122. package/docs/architecture/10-server-protocol.md +26 -3
  123. package/docs/architecture/11-terminal.md +50 -19
  124. package/docs/architecture/12-storage.md +12 -4
  125. package/docs/architecture/13-world-tools.md +19 -0
  126. package/docs/architecture/14-surfaces-and-parity.md +3 -3
  127. package/docs/architecture/README.md +2 -0
  128. package/docs/architecture/proposals/PROP-0049-context-attribution.md +7 -1
  129. package/docs/architecture/proposals/PROP-0050-run-stop-codes-and-refusals.md +30 -0
  130. package/docs/architecture/proposals/PROP-0051-unfinished-run-handoff.md +110 -0
  131. package/docs/architecture/proposals/PROP-0052-terminal-refine-and-variant-switch.md +111 -0
  132. package/docs/architecture/proposals/README.md +2 -0
  133. package/docs/decisions/ADR-0032-compaction-run-checkpoints.md +3 -1
  134. package/docs/decisions/ADR-0059-run-diagnostic-evidence.md +35 -0
  135. package/docs/decisions/ADR-0060-approvals-are-controls.md +40 -0
  136. package/docs/decisions/ADR-0061-strict-plugin-command-namespaces.md +41 -0
  137. package/docs/decisions/ADR-0062-shared-account-state.md +67 -0
  138. package/docs/decisions/ADR-0063-unfinished-work-handoffs.md +32 -0
  139. package/docs/decisions/ADR-0064-account-model-fallback-on-resume.md +79 -0
  140. package/docs/decisions/ADR-0065-variant-switch-at-turn-boundaries.md +31 -0
  141. package/docs/decisions/ADR-0066-guided-refinement-from-turn-snapshots.md +37 -0
  142. package/docs/decisions/ADR-0067-cache-stable-compaction-checkpoint.md +54 -0
  143. package/docs/doctor.md +2 -0
  144. package/docs/parity.md +18 -7
  145. package/docs/releases/1.3.1-unstable.5.md +53 -0
  146. package/docs/releases/1.3.1-unstable.6.md +31 -0
  147. package/docs/releases/1.3.1-unstable.7.md +17 -0
  148. package/docs/releases/1.3.1-unstable.8.md +19 -0
  149. package/docs/terminal-tui.md +48 -16
  150. package/package.json +1 -1
@@ -0,0 +1,34 @@
1
+ import type { ToolSession } from "../tools/types.js";
2
+ import { type ComputerButton, type ComputerControlScreenshot, type ComputerKey, type ComputerTarget } from "./contracts.js";
3
+ import type { ComputerScreenshot } from "./screenshot.js";
4
+ /**
5
+ * The host resolves only the window currently approved for this session. The opaque handle must
6
+ * identify that exact window, not a display or a mutable selection. Each operation must atomically
7
+ * revalidate session approval, window identity and run liveness at the point of effect. Capture
8
+ * obeys ComputerScreenshotBackend's isolation contract. Click coordinates are capture pixels;
9
+ * the host must refuse if geometry, scaling, visibility or focus makes that mapping unsafe.
10
+ * Type and key must not reach another window or sensitive fields. Unsupported operations refuse;
11
+ * there is no fallback. A host unable to guarantee these conditions must not supply a backend.
12
+ */
13
+ export interface ComputerControlBackend {
14
+ target(session: ToolSession): Promise<string>;
15
+ screenshot(session: ToolSession, handle: string): Promise<ComputerScreenshot>;
16
+ click(session: ToolSession, handle: string, screenshot: ComputerScreenshot, input: {
17
+ x: number;
18
+ y: number;
19
+ button: ComputerButton;
20
+ }): Promise<void>;
21
+ type(session: ToolSession, handle: string, text: string): Promise<void>;
22
+ key(session: ToolSession, handle: string, key: ComputerKey): Promise<void>;
23
+ activate(session: ToolSession, handle: string): Promise<void>;
24
+ }
25
+ /** One instance is bound to one trusted ToolSession. Calls must still pass the normal tool gate;
26
+ * this adapter does not implement human per-action approval. Do not share instances across runs. */
27
+ export declare function createComputerControl(session: ToolSession, backend?: ComputerControlBackend): {
28
+ target(input: unknown): Promise<ComputerTarget>;
29
+ screenshot(input: unknown): Promise<ComputerControlScreenshot>;
30
+ click(input: unknown): Promise<void>;
31
+ type(input: unknown): Promise<void>;
32
+ key(input: unknown): Promise<void>;
33
+ activate(input: unknown): Promise<void>;
34
+ };
@@ -0,0 +1,112 @@
1
+ import { randomUUID } from 'node:crypto';
2
+ import { HarnessError } from "../core/errors.js";
3
+ import { COMPUTER_KEYS, COMPUTER_LIMITS } from "./contracts.js";
4
+ function invalid() { throw new HarnessError('invalid_input', 'Invalid computer control input.'); }
5
+ function object(input, keys) {
6
+ if (!input || typeof input !== 'object' || Array.isArray(input))
7
+ return invalid();
8
+ const value = input;
9
+ if (Object.keys(value).length !== keys.length || keys.some(key => !Object.hasOwn(value, key)))
10
+ return invalid();
11
+ return value;
12
+ }
13
+ function identifier(value) {
14
+ return typeof value === 'string' && value.length > 0 && value.length <= COMPUTER_LIMITS.id && !/[\x00-\x1f\x7f]/.test(value);
15
+ }
16
+ function stopped(session) {
17
+ if (session.run.finished)
18
+ throw new HarnessError('run_stopped', 'The run was stopped; computer control is cancelled.');
19
+ }
20
+ /** One instance is bound to one trusted ToolSession. Calls must still pass the normal tool gate;
21
+ * this adapter does not implement human per-action approval. Do not share instances across runs. */
22
+ export function createComputerControl(session, backend) {
23
+ let selected;
24
+ let captured;
25
+ let busy = false;
26
+ async function operation(fn) {
27
+ stopped(session);
28
+ if (!backend)
29
+ throw new HarnessError('computer_unavailable', 'Computer control is unavailable: no approved-window backend.');
30
+ if (busy)
31
+ throw new HarnessError('computer_busy', 'A computer operation is already in progress.');
32
+ busy = true;
33
+ try {
34
+ const result = await fn(backend);
35
+ stopped(session);
36
+ return result;
37
+ }
38
+ finally {
39
+ busy = false;
40
+ }
41
+ }
42
+ function handle(input) {
43
+ if (!identifier(input.target))
44
+ return invalid();
45
+ if (!selected || input.target !== selected.id)
46
+ throw new HarnessError('computer_target_unavailable', 'The approved target is unavailable or stale.');
47
+ return selected.handle;
48
+ }
49
+ return {
50
+ async target(input) {
51
+ object(input, []);
52
+ return operation(async (host) => {
53
+ selected = undefined;
54
+ captured = undefined;
55
+ const resolved = await host.target(session);
56
+ if (!identifier(resolved))
57
+ throw new HarnessError('computer_error', 'The host returned an invalid target.');
58
+ stopped(session);
59
+ selected = { id: randomUUID(), handle: resolved };
60
+ return { target: selected.id };
61
+ });
62
+ },
63
+ async screenshot(input) {
64
+ const args = object(input, ['target']);
65
+ const target = handle(args);
66
+ return operation(async (host) => {
67
+ captured = undefined;
68
+ const shot = await host.screenshot(session, target);
69
+ if (!shot || typeof shot.data !== 'string' || !shot.data || shot.data.length > COMPUTER_LIMITS.imageData || !['image/png', 'image/jpeg'].includes(shot.mimeType) || !Number.isSafeInteger(shot.width) || shot.width <= 0 || shot.width > COMPUTER_LIMITS.dimension || !Number.isSafeInteger(shot.height) || shot.height <= 0 || shot.height > COMPUTER_LIMITS.dimension)
70
+ throw new HarnessError('computer_error', 'The host returned an invalid window capture.');
71
+ stopped(session);
72
+ captured = { id: randomUUID(), shot: { ...shot } };
73
+ return { screenshot: captured.id, data: shot.data, mimeType: shot.mimeType, width: shot.width, height: shot.height };
74
+ });
75
+ },
76
+ async click(input) {
77
+ const args = object(input, ['target', 'screenshot', 'x', 'y', 'button']);
78
+ const target = handle(args);
79
+ if (!identifier(args.screenshot) || !Number.isSafeInteger(args.x) || !Number.isSafeInteger(args.y) || !['left', 'right', 'middle'].includes(args.button))
80
+ return invalid();
81
+ if (!captured || args.screenshot !== captured.id)
82
+ throw new HarnessError('computer_screenshot_stale', 'The screenshot is unavailable or stale.');
83
+ const shot = captured.shot;
84
+ const x = args.x, y = args.y;
85
+ if (x < 0 || y < 0 || x >= shot.width || y >= shot.height)
86
+ return invalid();
87
+ const button = args.button;
88
+ return operation(async (host) => { captured = undefined; await host.click(session, target, shot, { x, y, button }); });
89
+ },
90
+ async type(input) {
91
+ const args = object(input, ['target', 'text']);
92
+ const target = handle(args);
93
+ if (typeof args.text !== 'string' || !args.text.length || args.text.length > COMPUTER_LIMITS.text || /[\x00-\x1f\x7f]/.test(args.text))
94
+ return invalid();
95
+ const text = args.text;
96
+ return operation(async (host) => { captured = undefined; await host.type(session, target, text); });
97
+ },
98
+ async key(input) {
99
+ const args = object(input, ['target', 'key']);
100
+ const target = handle(args);
101
+ if (typeof args.key !== 'string' || !COMPUTER_KEYS.includes(args.key))
102
+ return invalid();
103
+ const key = args.key;
104
+ return operation(async (host) => { captured = undefined; await host.key(session, target, key); });
105
+ },
106
+ async activate(input) {
107
+ const args = object(input, ['target']);
108
+ const target = handle(args);
109
+ return operation(async (host) => { captured = undefined; await host.activate(session, target); });
110
+ }
111
+ };
112
+ }
@@ -0,0 +1,26 @@
1
+ import type { ToolSession } from "../tools/types.js";
2
+ import type { ComputerScreenshot, ComputerScreenshotBackend } from "./screenshot.js";
3
+ /** Trusted host code only. Selection must be a person-controlled choice of one exact window,
4
+ * not a model-supplied identifier or a remembered tool grant. Null means no approval. */
5
+ export interface TerminalCaptureHost<Window> {
6
+ selectWindow(session: ToolSession): Promise<Window | null>;
7
+ /** A fresh human decision for this exact window and capture, never a standing approval. */
8
+ approveCapture(session: ToolSession, window: Window): Promise<boolean>;
9
+ /** At the point of capture, enforce the screenshot.ts isolation contract, exact window identity,
10
+ * current person approval, run/session liveness and revocation atomically with capture. Call
11
+ * check() at that point; it is necessary but not sufficient to enforce OS/host isolation.
12
+ * Never fall back to a display or another window. Refuse if any guarantee is unavailable. */
13
+ captureWindow(session: ToolSession, window: Window, check: () => void): Promise<ComputerScreenshot>;
14
+ }
15
+ export interface TerminalCaptureBridge {
16
+ /** Only expose this backend to the normal gated screenshot tool. */
17
+ backend: ComputerScreenshotBackend;
18
+ /** Trusted person-facing wiring only; never expose selection/revocation as model tools. */
19
+ selectWindow(): Promise<boolean>;
20
+ revoke(): void;
21
+ /** Permanently closes the session bridge. */
22
+ close(): void;
23
+ }
24
+ /** One parent-owned instance per ToolSession and run. Neither this adapter nor an opaque window
25
+ * handle proves that an injected host can enforce isolation; the host is the security boundary. */
26
+ export declare function createTerminalCaptureBridge<Window>(session: ToolSession, host: TerminalCaptureHost<Window>): TerminalCaptureBridge;
@@ -0,0 +1,64 @@
1
+ import { HarnessError } from "../core/errors.js";
2
+ /** One parent-owned instance per ToolSession and run. Neither this adapter nor an opaque window
3
+ * handle proves that an injected host can enforce isolation; the host is the security boundary. */
4
+ export function createTerminalCaptureBridge(session, host) {
5
+ const run = session.run;
6
+ let closed = false;
7
+ let generation = 0;
8
+ let selected;
9
+ let busy = false;
10
+ function live() {
11
+ if (closed)
12
+ throw new HarnessError('computer_unavailable', 'The capture session is closed.');
13
+ if (session.run !== run || run.finished)
14
+ throw new HarnessError('run_stopped', 'The run was stopped; capture is cancelled.');
15
+ }
16
+ function revoke() { generation++; selected = undefined; }
17
+ function current(selection) {
18
+ live();
19
+ if (selected !== selection || generation !== selection.generation)
20
+ throw new HarnessError('computer_target_unavailable', 'The approved window is unavailable or revoked.');
21
+ }
22
+ return {
23
+ backend: {
24
+ async capture(request) {
25
+ live();
26
+ if (request !== session || request.run !== run)
27
+ throw new HarnessError('computer_unavailable', 'Capture belongs to another session or run.');
28
+ if (busy)
29
+ throw new HarnessError('computer_busy', 'A capture is already in progress.');
30
+ const selection = selected;
31
+ if (!selection)
32
+ throw new HarnessError('computer_target_unavailable', 'No window is approved for this session.');
33
+ busy = true;
34
+ try {
35
+ const approved = await host.approveCapture(session, selection.window);
36
+ current(selection);
37
+ if (approved !== true)
38
+ throw new HarnessError('computer_denied', 'Window capture was not approved.');
39
+ const shot = await host.captureWindow(session, selection.window, () => current(selection));
40
+ current(selection);
41
+ return shot;
42
+ }
43
+ finally {
44
+ busy = false;
45
+ }
46
+ }
47
+ },
48
+ async selectWindow() {
49
+ live();
50
+ revoke();
51
+ const revision = generation;
52
+ const window = await host.selectWindow(session);
53
+ live();
54
+ if (revision !== generation)
55
+ throw new HarnessError('computer_target_unavailable', 'Window selection was revoked or replaced.');
56
+ if (window === null || window === undefined)
57
+ return false;
58
+ selected = { window, generation: revision };
59
+ return true;
60
+ },
61
+ revoke,
62
+ close() { closed = true; revoke(); }
63
+ };
64
+ }
@@ -0,0 +1,9 @@
1
+ import type { SessionManager } from '@earendil-works/pi-coding-agent';
2
+ /** Keeps approved-window image bytes out of Pi's session manager. The owner must apply `restore`
3
+ * only to a model-request context and call `clear` on run termination. This does not protect host
4
+ * logs, provider retention, event listeners or other capture tools. */
5
+ export declare function volatileComputerImages(manager: SessionManager): {
6
+ restore<T>(messages: readonly T[]): T[];
7
+ clear(): void;
8
+ dispose(): void;
9
+ };
@@ -0,0 +1,50 @@
1
+ /** Keeps approved-window image bytes out of Pi's session manager. The owner must apply `restore`
2
+ * only to a model-request context and call `clear` on run termination. This does not protect host
3
+ * logs, provider retention, event listeners or other capture tools. */
4
+ export function volatileComputerImages(manager) {
5
+ const images = new Map();
6
+ const append = manager.appendMessage.bind(manager);
7
+ const original = manager.appendMessage;
8
+ const replacement = (value) => {
9
+ const message = value;
10
+ if (message.role !== 'toolResult' || message.toolName !== 'computer_screenshot' || typeof message.toolCallId !== 'string' || !Array.isArray(message.content))
11
+ return append(value);
12
+ const content = message.content;
13
+ const captured = content.filter(block => block?.type === 'image');
14
+ images.delete(message.toolCallId);
15
+ if (captured.length) {
16
+ images.set(message.toolCallId, captured.map(block => ({ ...block })));
17
+ while (images.size > 6)
18
+ images.delete(images.keys().next().value);
19
+ }
20
+ const clean = {
21
+ role: 'toolResult',
22
+ toolName: 'computer_screenshot',
23
+ toolCallId: message.toolCallId,
24
+ content: [{ type: 'text', text: '[Window capture omitted from saved history.]' }],
25
+ isError: message.isError === true,
26
+ timestamp: typeof message.timestamp === 'number' ? message.timestamp : Date.now()
27
+ };
28
+ return append(clean);
29
+ };
30
+ manager.appendMessage = replacement;
31
+ return {
32
+ restore(messages) {
33
+ return messages.map(value => {
34
+ const message = value;
35
+ if (message.role !== 'toolResult' || message.toolName !== 'computer_screenshot' || typeof message.toolCallId !== 'string')
36
+ return value;
37
+ const captured = images.get(message.toolCallId);
38
+ if (!captured || !Array.isArray(message.content))
39
+ return value;
40
+ return { ...message, content: [...message.content, ...captured.map(block => ({ ...block }))] };
41
+ });
42
+ },
43
+ clear() { images.clear(); },
44
+ dispose() {
45
+ images.clear();
46
+ if (manager.appendMessage === replacement)
47
+ manager.appendMessage = original;
48
+ }
49
+ };
50
+ }
@@ -0,0 +1,16 @@
1
+ /** Facts recorded for one run. Null means that the fact was not recorded. */
2
+ export interface RunDetails {
3
+ runId: string;
4
+ status: string | null;
5
+ mode: string | null;
6
+ model: string | null;
7
+ effort: string | null;
8
+ variantScope: string | null;
9
+ variantVersion: string | null;
10
+ workspaceRoot: string | null;
11
+ tools: string[] | null;
12
+ connectors: string[] | null;
13
+ skills: string[] | null;
14
+ plugins: string[] | null;
15
+ }
16
+ export declare function runDetails(root: string, runId: string): RunDetails;
@@ -0,0 +1,22 @@
1
+ import { loadRun as loadCapabilities } from "../capabilities/runSnapshot.js";
2
+ import { loadRun, readEvents } from "../sessions/runStore.js";
3
+ export function runDetails(root, runId) {
4
+ const run = loadRun(root, runId);
5
+ const capabilities = loadCapabilities(root, runId);
6
+ const snapshot = readEvents(root, runId).filter((event) => event.type === 'context.snapshot').at(-1);
7
+ const payload = snapshot?.payload;
8
+ return {
9
+ runId: run.id,
10
+ status: run.status ?? null,
11
+ mode: run.effectiveMode ?? null,
12
+ model: run.model ?? null,
13
+ effort: run.effort ?? null,
14
+ variantScope: run.variantScope ?? null,
15
+ variantVersion: run.variantVersion ?? null,
16
+ workspaceRoot: run.workspaceRoot ?? null,
17
+ tools: payload && !payload.toolsTruncated && Array.isArray(payload.tools) ? payload.tools.map((tool) => tool.name) : null,
18
+ connectors: capabilities?.connectors ?? null,
19
+ skills: run.loadedSkills ?? null,
20
+ plugins: run.activatedPlugins ?? null
21
+ };
22
+ }
@@ -82,6 +82,9 @@ export async function builtinChecks(harness, context, secrets, assets = defaultA
82
82
  }
83
83
  }
84
84
  },
85
+ check('computer.capture', 'tools', 'Application window capture', async () => context.tools.includes('computer_screenshot')
86
+ ? { status: 'unverified', evidence: 'A computer screenshot tool is listed for this session; its backend and window isolation were not tested.', remedy: 'Check the provider and approve an application window before capture.' }
87
+ : { status: 'blocked', evidence: 'No computer screenshot tool is listed for this session. An application window cannot be read through this capability.', remedy: 'Use a host with an approved-window capture backend.' }),
85
88
  check('runtime.pi', 'runtime', 'Pi runtime', async () => { await loadPi(); return pass(`Pi ${PINNED_PI_VERSION} loaded with its required dispatcher.`); }),
86
89
  check('runtime.launcher', 'runtime', 'Terminal launcher', async () => {
87
90
  if (!executable(assets.node))
@@ -33,7 +33,7 @@ export async function diagnosticProbe(harness, context, inputSignal, action) {
33
33
  freezeRun(root, id, caller, capabilities);
34
34
  const run = harness.runs.start(id, id);
35
35
  run.onInterrupt(() => interrupt.abort());
36
- const abort = () => { run.finish('interrupted'); void harness.world.release(id); };
36
+ const abort = () => { run.finish('interrupted', undefined, undefined, 'user_abort'); void harness.world.release(id); };
37
37
  signal.addEventListener('abort', abort, { once: true });
38
38
  const gate = harness.sessions.diagnosticGate(run, caller);
39
39
  try {
@@ -44,11 +44,13 @@ export async function diagnosticProbe(harness, context, inputSignal, action) {
44
44
  signal.throwIfAborted();
45
45
  if (run.finished || !capabilities.tools.includes(name))
46
46
  throw new HarnessError('doctor_blocked', 'This tool is outside the diagnostic capability set.');
47
- const refusal = await gate.check(name, input);
48
- if (refusal)
47
+ const callId = randomUUID();
48
+ const refusal = await gate.checkDetailed?.(name, input);
49
+ if (refusal) {
50
+ run.emit('tool.refused', { toolCallId: callId, name, code: refusal.code, reason: 'The tool policy refused this diagnostic call.' });
49
51
  throw new HarnessError('doctor_blocked', 'The tool policy refused this diagnostic call.');
52
+ }
50
53
  signal.throwIfAborted();
51
- const callId = randomUUID();
52
54
  run.emit('tool.started', { toolCallId: callId, name, summary: 'Synthetic diagnostic input' });
53
55
  try {
54
56
  let result;
@@ -80,12 +82,12 @@ export async function diagnosticProbe(harness, context, inputSignal, action) {
80
82
  return result;
81
83
  }
82
84
  catch (error) {
83
- run.finish(signal.aborted ? 'interrupted' : 'failed', { code: 'doctor_failed', message: 'The diagnostic probe failed.' });
85
+ run.finish(signal.aborted ? 'interrupted' : 'failed', { code: 'doctor_failed', message: 'The diagnostic probe failed.' }, undefined, signal.aborted ? 'user_abort' : undefined);
84
86
  throw error;
85
87
  }
86
88
  finally {
87
89
  signal.removeEventListener('abort', abort);
88
- run.finish(signal.aborted ? 'interrupted' : 'completed');
90
+ run.finish(signal.aborted ? 'interrupted' : 'completed', undefined, undefined, signal.aborted ? 'user_abort' : undefined);
89
91
  harness.apps.revokeRun(id, id);
90
92
  await harness.world.release(id);
91
93
  }
@@ -38,6 +38,12 @@ export interface HarnessOptions {
38
38
  dataRoot?: string | null;
39
39
  /** Device-local state that never belongs in the data root: accounts, approvals, connections, sockets. */
40
40
  stateDir: string;
41
+ /**
42
+ * Where account identity lives: the registry, each account's Pi folder, and the shared settings.
43
+ * Defaults to `<state dir>/accounts`. A launch that points it at another state's folder signs in
44
+ * as that state's accounts, so it must pair it with that state's secret store.
45
+ */
46
+ accountsDir?: string;
41
47
  /** Where credentials are kept. Defaults to an owner-only file in the state directory. */
42
48
  secrets?: SecretStore;
43
49
  /** How the harness names itself to a model. */
@@ -101,6 +107,8 @@ export declare class Harness {
101
107
  readonly bus: Bus;
102
108
  readonly env: Env;
103
109
  readonly stateDir: string;
110
+ /** The account registry, account Pi folders and their shared settings; usually `<state dir>/accounts`. */
111
+ readonly accountsDir: string;
104
112
  readonly policy: ToolPolicy;
105
113
  /** How a link a person clicked reaches the operating system (page 10, `links.open`). */
106
114
  readonly linkOpener: LinkOpener;
@@ -73,6 +73,8 @@ export class Harness {
73
73
  bus = new Bus();
74
74
  env;
75
75
  stateDir;
76
+ /** The account registry, account Pi folders and their shared settings; usually `<state dir>/accounts`. */
77
+ accountsDir;
76
78
  policy;
77
79
  /** How a link a person clicked reaches the operating system (page 10, `links.open`). */
78
80
  linkOpener;
@@ -116,9 +118,10 @@ export class Harness {
116
118
  constructor(options) {
117
119
  this.browserEnabled = options.browser !== false;
118
120
  this.stateDir = options.stateDir;
121
+ this.accountsDir = options.accountsDir ?? join(this.stateDir, 'accounts');
119
122
  mkdirSync(this.stateDir, { recursive: true });
120
123
  // Before anything can start a session: no inherited credential, no `~/.pi`.
121
- isolateProcess(join(this.stateDir, 'accounts'));
124
+ isolateProcess(this.accountsDir);
122
125
  this.env = new Env(options.dataRoot || null, options.directory ?? EMPTY_DIRECTORY, options.productName ?? DEFAULT_PRODUCT_NAME, this.bus);
123
126
  this.hub = new Hub(this, options.hub);
124
127
  this.policy = options.policy ?? {};
@@ -127,7 +130,7 @@ export class Harness {
127
130
  this.trust = new VariantTrust(this.stateDir);
128
131
  this.refineHost = options.refineHost ?? null;
129
132
  const secrets = options.secrets ?? fileSecretStore(join(this.stateDir, 'secrets.json'));
130
- this.accounts = new Accounts({ dir: join(this.stateDir, 'accounts'), secrets, bus: this.bus });
133
+ this.accounts = new Accounts({ dir: this.accountsDir, secrets, bus: this.bus });
131
134
  this.approvals = new Approvals(this.stateDir, this.bus);
132
135
  this.usageLimits = new UsageLimits({ accounts: this.accounts, root: () => this.env.dataRoot });
133
136
  // Response headers are the free, always-fresh limit signal; the account runtime reports them here.
@@ -153,7 +156,7 @@ export class Harness {
153
156
  wanted: async () => {
154
157
  if (!this.env.dataRoot)
155
158
  return [];
156
- const shared = ensureSharedDir(join(this.stateDir, 'accounts'));
159
+ const shared = ensureSharedDir(this.accountsDir);
157
160
  // A hook comes only with a package: one kept beside the data, or one the shared settings
158
161
  // name. With neither there is nothing to look for, and Pi is not loaded to find that out.
159
162
  const named = readJsonOr(join(shared, 'settings.json'), {}).packages;
@@ -205,7 +208,7 @@ export class Harness {
205
208
  this.refine = new Refinements({ root: () => this.env.root, bus: this.bus, trust: this.trust, host: () => this.refineHost, runtime: refineRuntime });
206
209
  this.lessons = new Lessons({ root: () => this.env.root, runtime: refineRuntime });
207
210
  this.pageNotes = new NoteDeliveries({ root: () => this.env.root, bus: this.bus, terminals: () => this.terminals ?? null });
208
- this.terminals = new Terminals({ trust: this.trust, subagents: this.subagents, sideQuestions: this.sideQuestions, resolveCapabilities: (caller, tools, cwd) => capabilities.resolve(this, { agentId: caller.agentId ?? null, projectId: caller.projectId ?? null, cwd, tools }), env: this.env, stateDir: this.stateDir, accounts: this.accounts, runs: this.runs, approvals: this.approvals, apps: this.apps, policy: this.policy, bus: this.bus, plugins: this.plugins, usage: this.usage, usageLimits: this.usageLimits, pluginControl: { list: (scope) => pluginApi.list(this, scope), attach: (params, on) => pluginApi.attach(this, params, on), trust: (scope) => pluginApi.trust(this, scope), untrust: (scope) => pluginApi.untrust(this, scope), configure: (params) => pluginApi.configure(this, params), install: params => pluginInstall.install(this, params), remove: params => pluginInstall.remove(this, params), proposals: { list: () => pluginProposals.list(this.env.root), preview: id => pluginProposals.preview(this.env.root, id), accept: (id, hash) => pluginProposals.accept(this, id, hash), reject: (id, hash) => pluginProposals.reject(this.env.root, id, hash) } }, assets: options.assets, hub: this.hub, world: this.world, doctor: this.doctor, worktrees: this.worktrees, noteCapture: this.noteCapture, pageNotes: this.pageNotes });
211
+ this.terminals = new Terminals({ trust: this.trust, subagents: this.subagents, sideQuestions: this.sideQuestions, resolveCapabilities: (caller, tools, cwd) => capabilities.resolve(this, { agentId: caller.agentId ?? null, projectId: caller.projectId ?? null, cwd, tools }), env: this.env, stateDir: this.stateDir, accounts: this.accounts, runs: this.runs, approvals: this.approvals, apps: this.apps, policy: this.policy, bus: this.bus, plugins: this.plugins, usage: this.usage, usageLimits: this.usageLimits, pluginControl: { list: (scope) => pluginApi.list(this, scope), attach: (params, on) => pluginApi.attach(this, params, on), trust: (scope) => pluginApi.trust(this, scope), untrust: (scope) => pluginApi.untrust(this, scope), configure: (params) => pluginApi.configure(this, params), install: params => pluginInstall.install(this, params), remove: params => pluginInstall.remove(this, params), proposals: { list: () => pluginProposals.list(this.env.root), preview: id => pluginProposals.preview(this.env.root, id), accept: (id, hash) => pluginProposals.accept(this, id, hash), reject: (id, hash) => pluginProposals.reject(this.env.root, id, hash) } }, assets: options.assets, hub: this.hub, world: this.world, doctor: this.doctor, worktrees: this.worktrees, noteCapture: this.noteCapture, pageNotes: this.pageNotes, refine: this.refine });
209
212
  this.ready = this.apps.start().catch((error) => log('connected apps', error instanceof Error ? error.message : String(error)));
210
213
  this.runs.listen((event, run) => {
211
214
  this.accounts.onRunEvent(event, run);
@@ -71,6 +71,8 @@ function summary(env, run, projects) {
71
71
  project: project ? { id: project.id, name: project.name, slug: project.slug } : null,
72
72
  mode: run.mode,
73
73
  status: run.status,
74
+ terminalReason: run.terminalReason ?? null,
75
+ terminalCode: run.terminalCode ?? null,
74
76
  goal: goal.length > 500 ? `${goal.slice(0, 497)}…` : goal || null,
75
77
  startedAt: run.startedAt,
76
78
  endedAt: run.endedAt,
@@ -134,7 +134,7 @@ export class Hub {
134
134
  });
135
135
  if (receipt.entry.delivery.kind === 'pi-package') {
136
136
  const source = receipt.entry.delivery.source;
137
- const settings = readJsonOr(join(this.harness.stateDir, 'accounts', '_shared', 'pi', 'settings.json'), {});
137
+ const settings = readJsonOr(join(this.harness.accountsDir, '_shared', 'pi', 'settings.json'), {});
138
138
  return settings.packages?.some((item) => (typeof item === 'string' ? item : item.source) === source) ?? false;
139
139
  }
140
140
  }
@@ -134,9 +134,9 @@ export declare const hubReceiptSchema: z.ZodObject<{
134
134
  resourceIds: z.ZodArray<z.ZodString>;
135
135
  document: z.ZodNullable<z.ZodString>;
136
136
  state: z.ZodOptional<z.ZodEnum<{
137
- incomplete: "incomplete";
138
137
  installed: "installed";
139
138
  changed: "changed";
139
+ incomplete: "incomplete";
140
140
  }>>;
141
141
  }, z.core.$strict>;
142
142
  export declare const hubPreviewPageSchema: z.ZodObject<{
@@ -257,9 +257,9 @@ export declare const hubOverviewSchema: z.ZodObject<{
257
257
  resourceIds: z.ZodArray<z.ZodString>;
258
258
  document: z.ZodNullable<z.ZodString>;
259
259
  state: z.ZodOptional<z.ZodEnum<{
260
- incomplete: "incomplete";
261
260
  installed: "installed";
262
261
  changed: "changed";
262
+ incomplete: "incomplete";
263
263
  }>>;
264
264
  }, z.core.$strict>>;
265
265
  origin: z.ZodEnum<{
@@ -7,6 +7,8 @@ export interface PackageManifest {
7
7
  extends: string[];
8
8
  /** Stable terminal command namespace, or `null` to use the normalized package name. */
9
9
  commandPrefix: string | null;
10
+ /** A prompt template name exposed only at the package namespace root. */
11
+ defaultPrompt: string | null;
10
12
  /** The hooks file, inside the package, or `null` when it has none. */
11
13
  hooks: string | null;
12
14
  /** The folder of subagent profiles, inside the package. `agents` unless the manifest names another. */
@@ -64,6 +64,7 @@ export function packageManifest(packageRoot) {
64
64
  version: text(manifest.version) ?? text(plugin.version),
65
65
  extends: (Array.isArray(own.extends) ? own.extends : typeof own.extends === 'string' ? [own.extends] : []).filter((id) => typeof id === 'string' && !!id),
66
66
  commandPrefix: typeof own.commandPrefix === 'string' && /^[a-z][a-z0-9-]*$/i.test(own.commandPrefix) && !['plugin', 'skill'].includes(own.commandPrefix.toLowerCase()) ? own.commandPrefix.toLowerCase() : null,
67
+ defaultPrompt: typeof own.defaultPrompt === 'string' && /^[a-z][a-z0-9-]*$/.test(own.defaultPrompt) ? own.defaultPrompt : null,
67
68
  hooks: inside(own.hooks),
68
69
  agents: inside(own.agents) ?? 'agents',
69
70
  connectorTemplates: (Array.isArray(own.connectors) ? own.connectors : []).flatMap((value) => {
@@ -7,6 +7,8 @@ import type { SessionState } from "../sessions/sessionState.js";
7
7
  import { type StandardSession } from "./standard.js";
8
8
  export declare const REQUIRED_SKILLS_BUDGET = 12000;
9
9
  export declare const REFERENCES_BUDGET = 12000;
10
+ /** An approval is a control the person clicks; the model never asks for permission in a message. */
11
+ export declare const APPROVAL_GUIDANCE = "Approvals: when a call needs a person, the Harness pauses that exact call and shows them Allow and Deny. Never ask for permission in a message, never end your turn to wait for an answer, and never call a task blocked on approval before trying: a denial arrives as the tool result, and you continue from it.";
10
12
  /** Where the harness's own sections sit; an application's sections are placed among them by `order`. */
11
13
  export declare const SECTION_ORDER: {
12
14
  readonly harnessIdentity: 5;
@@ -151,7 +153,7 @@ export interface Launch {
151
153
  profile?: string;
152
154
  }
153
155
  /** How a run's final reply is shaped. Fixed text: it sits in the stable prefix of every pack. */
154
- export declare const REPORTING_GUIDANCE = "When you finish work, write the final reply for a person who did not watch you work.\n\n- Start with the answer or outcome in one or two sentences. If they asked a question, answer it first.\n- Keep it concise and use only headings or structure that help explain the outcome; do not force a fixed set of report headings.\n- When work involves files, identify the relevant paths and briefly state what changed or mattered. Use `path:line` references where useful, and a table (File | Change | Why) when there are three or more changed files.\n- Include blockers, risks, or next steps only when they are concrete and relevant.\n- Use **Need human inspection** only when a concrete verification requires a person because you could not perform or observe it. State what remains unverified, why you could not verify it, and the specific check the person should make. Do not use this for checks you ran or generic risks.\n- Name only checks actually run and their results; never claim a check you did not run.\n- Use a Markdown table when comparing options, listing several items with the same fields, or reporting the results of several checks. Use prose or bullets otherwise.\n- A one-line question gets a one-line answer.\n- If the person, the application, or the current mode asks for a different format, follow that.\n";
156
+ export declare const REPORTING_GUIDANCE = "When you finish work, write the final reply for a person who did not watch you work.\n\n- Lead with the outcome, not the steps taken to reach it. If the person asked a question, answer it first.\n- Cover the most important information and use as much structure as the answer needs. Use descriptive headings, lists, or tables when they help explain the outcome; do not force a fixed set of report headings. Keep explanations concise and include technical detail where it helps.\n- When work involves files, identify the relevant paths and briefly state what changed or mattered. Use `path:line` references where useful, and a table (File | Change | Why) when there are three or more changed files.\n- Include blockers, risks, or next steps only when they are concrete and relevant.\n- When work remains unfinished, state the concrete decision the person must make or the next action and its owner for each material blocker; do not merely restate the blocker or invent a human decision.\n- Use **Need human inspection** only when a concrete verification requires a person because you could not perform or observe it. State what remains unverified, why you could not verify it, and the specific check the person should make. Do not use this for checks you ran or generic risks.\n- Name only checks actually run and their results; never claim a check you did not run.\n- Use a Markdown table when comparing options, listing several items with the same fields, or reporting the results of several checks. Use prose or bullets otherwise.\n- A one-line question gets a one-line answer.\n- If the person, the application, or the current mode asks for a different format, follow that.\n";
155
157
  export declare const HISTORY_GROUP: string[];
156
158
  export declare const WIKI_GROUP: string[];
157
159
  export declare const NATIVE_GROUP: string[];
@@ -29,15 +29,18 @@ export const REFERENCES_BUDGET = 12000;
29
29
  /** Always-on variant text is capped when the variant is saved, so its sections are never cut here. */
30
30
  const VARIANT_BUDGET = 30_000;
31
31
  const NOTES_LISTED = 25;
32
+ /** An approval is a control the person clicks; the model never asks for permission in a message. */
33
+ export const APPROVAL_GUIDANCE = 'Approvals: when a call needs a person, the Harness pauses that exact call and shows them Allow and Deny. Never ask for permission in a message, never end your turn to wait for an answer, and never call a task blocked on approval before trying: a denial arrives as the tool result, and you continue from it.';
32
34
  /** Where the harness's own sections sit; an application's sections are placed among them by `order`. */
33
35
  export const SECTION_ORDER = { harnessIdentity: 5, system: 25, sessionState: 30, guardrails: 40, memory: 45, references: 50, requiredSkills: 52, subagents: 64, scripts: 66, wiki: 80, tools: 90, reporting: 95 };
34
36
  /** How a run's final reply is shaped. Fixed text: it sits in the stable prefix of every pack. */
35
37
  export const REPORTING_GUIDANCE = `When you finish work, write the final reply for a person who did not watch you work.
36
38
 
37
- - Start with the answer or outcome in one or two sentences. If they asked a question, answer it first.
38
- - Keep it concise and use only headings or structure that help explain the outcome; do not force a fixed set of report headings.
39
+ - Lead with the outcome, not the steps taken to reach it. If the person asked a question, answer it first.
40
+ - Cover the most important information and use as much structure as the answer needs. Use descriptive headings, lists, or tables when they help explain the outcome; do not force a fixed set of report headings. Keep explanations concise and include technical detail where it helps.
39
41
  - When work involves files, identify the relevant paths and briefly state what changed or mattered. Use \`path:line\` references where useful, and a table (File | Change | Why) when there are three or more changed files.
40
42
  - Include blockers, risks, or next steps only when they are concrete and relevant.
43
+ - When work remains unfinished, state the concrete decision the person must make or the next action and its owner for each material blocker; do not merely restate the blocker or invent a human decision.
41
44
  - Use **Need human inspection** only when a concrete verification requires a person because you could not perform or observe it. State what remains unverified, why you could not verify it, and the specific check the person should make. Do not use this for checks you ran or generic risks.
42
45
  - Name only checks actually run and their results; never claim a check you did not run.
43
46
  - Use a Markdown table when comparing options, listing several items with the same fields, or reporting the results of several checks. Use prose or bullets otherwise.
@@ -79,9 +82,9 @@ export function renderCompactionCheckpoint(input) {
79
82
  if (!input.todo.length && !input.planInstructions)
80
83
  return null;
81
84
  const parts = [
82
- 'This is current state from the active run after context compaction, not a new user request. Continue the same request. Do not infer that omitted details or decisions were settled.',
85
+ 'This is the state of the active run when its context was compacted, not a new user request. Continue the same request; todo updates later in the conversation supersede the list below. Do not infer that omitted details or decisions were settled.',
83
86
  input.goal.trim() ? `## Current request\n\n${clip(input.goal.trim(), 1_000)}` : '',
84
- input.planInstructions ? `## Active plan instructions\n\n${clip(input.planInstructions, 4_000)}` : ''
87
+ input.planInstructions ? `## Active plan instructions\n\n${clip(input.planInstructions, 8_000)}` : ''
85
88
  ].filter(Boolean);
86
89
  if (input.todo.length) {
87
90
  const active = input.todo.filter((item) => item.status !== 'completed');
@@ -92,7 +95,7 @@ export function renderCompactionCheckpoint(input) {
92
95
  ].filter(Boolean).join('\n\n');
93
96
  parts.push(`## Current todo list\n\n${todo}`);
94
97
  }
95
- const body = clip(parts.join('\n\n'), 8_000);
98
+ const body = clip(parts.join('\n\n'), 13_000);
96
99
  return `[Harness context update — not a user message]\n\n## Compaction checkpoint\n\n${body}`;
97
100
  }
98
101
  /** The Wiki pointer: the current project's notes, and how to read the rest. */
@@ -136,7 +139,7 @@ export function toolGroups(context, launch, dataRoot) {
136
139
  const native = NATIVE_GROUP.filter((name) => enabled.includes(name));
137
140
  const wikiTools = WIKI_GROUP.filter((name) => name !== 'wiki_write' || enabled.includes(name));
138
141
  const readGuidance = `Read-only file tools accept absolute paths and paths beginning with ~ anywhere this process has operating-system read access. The working folder is a default location, not a read boundary.${dataRoot ? ` The Harness data root is ${dataRoot}.` : ''}`;
139
- const writeGuidance = 'Keep native file writes and Bash filesystem effects inside the active project workspace. Outside file targets require one-call approval; remembered tool grants do not satisfy it. Bash, including an initial ! command, may read as before but writes are sandboxed to the workspace unless the explicit Full Permission switch is on. Keep task outputs in the project, following an existing artifacts/ or outputs/ convention when present.';
142
+ const writeGuidance = 'Keep native file writes and Bash filesystem effects inside the active project workspace, where they run without asking. An outside file target is allowed too: call the tool and the Harness pauses that one call until the person clicks Allow or Deny, so nothing outside changes first. Remembered tool grants do not answer an outside target; only the explicit Full Permission switch answers it for the run. Bash, including an initial ! command, may read as before but writes are sandboxed to the workspace unless that switch is on. Keep task outputs in the project, following an existing artifacts/ or outputs/ convention when present.';
140
143
  // One wording for every front end: the terminal and a host give the same tools the same words (INV-PAR-1).
141
144
  const nativeGuidance = `Files and shell: ${readGuidance} ${writeGuidance} Edits and commands still pass through the Harness gate.`;
142
145
  const groups = [
@@ -192,7 +195,7 @@ export function toolGroups(context, launch, dataRoot) {
192
195
  }
193
196
  /** One paragraph per tool group the caller has, then the harness's own tool guidance. */
194
197
  function tools(groups, guidance, pointer) {
195
- let text = '';
198
+ let text = `${APPROVAL_GUIDANCE}\n\n`;
196
199
  for (const group of groups)
197
200
  if (group.guidance)
198
201
  text += `${group.guidance}\n\n`;