@xingular/harness 1.3.1-unstable.0 → 1.3.1-unstable.2

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 (116) hide show
  1. package/CHANGELOG.md +29 -1
  2. package/README.md +16 -12
  3. package/builtin/skills/plugin-authoring/SKILL.md +34 -0
  4. package/dist/cli.js +2334 -1715
  5. package/dist/sdk/agents/profiles.d.ts +13 -4
  6. package/dist/sdk/agents/profiles.js +59 -7
  7. package/dist/sdk/annotations/bridge.d.ts +2 -0
  8. package/dist/sdk/annotations/bridge.js +4 -0
  9. package/dist/sdk/annotations/capture.d.ts +44 -2
  10. package/dist/sdk/annotations/capture.js +104 -3
  11. package/dist/sdk/annotations/delivery.d.ts +24 -17
  12. package/dist/sdk/annotations/delivery.js +82 -49
  13. package/dist/sdk/annotations/inspect.js +7 -6
  14. package/dist/sdk/annotations/pageScript.js +4 -4
  15. package/dist/sdk/annotations/part.d.ts +0 -2
  16. package/dist/sdk/annotations/part.js +4 -33
  17. package/dist/sdk/annotations/queue.d.ts +2 -2
  18. package/dist/sdk/annotations/queue.js +12 -7
  19. package/dist/sdk/annotations/serverMethods.js +11 -7
  20. package/dist/sdk/annotations/store.d.ts +13 -21
  21. package/dist/sdk/annotations/store.js +47 -37
  22. package/dist/sdk/commands/list.js +2 -0
  23. package/dist/sdk/core/links.d.ts +51 -0
  24. package/dist/sdk/core/links.js +155 -0
  25. package/dist/sdk/harness.d.ts +5 -0
  26. package/dist/sdk/harness.js +11 -6
  27. package/dist/sdk/index.d.ts +1 -0
  28. package/dist/sdk/index.js +1 -0
  29. package/dist/sdk/plugins/builtin.js +11 -6
  30. package/dist/sdk/plugins/builtinRegistry.d.ts +3 -1
  31. package/dist/sdk/plugins/builtinRegistry.js +9 -3
  32. package/dist/sdk/plugins/discover.d.ts +7 -1
  33. package/dist/sdk/plugins/discover.js +41 -2
  34. package/dist/sdk/plugins/identity.js +1 -1
  35. package/dist/sdk/plugins/inventory.js +1 -1
  36. package/dist/sdk/plugins/manifest.d.ts +2 -0
  37. package/dist/sdk/plugins/manifest.js +21 -4
  38. package/dist/sdk/plugins/plugins.d.ts +2 -0
  39. package/dist/sdk/plugins/plugins.js +1 -0
  40. package/dist/sdk/plugins/proposals.d.ts +17 -0
  41. package/dist/sdk/plugins/proposals.js +147 -0
  42. package/dist/sdk/plugins/types.d.ts +1 -1
  43. package/dist/sdk/plugins/types.js +1 -1
  44. package/dist/sdk/prompt/compile.d.ts +11 -2
  45. package/dist/sdk/prompt/compile.js +32 -4
  46. package/dist/sdk/prompt/standard.d.ts +1 -1
  47. package/dist/sdk/prompt/standard.js +1 -1
  48. package/dist/sdk/server/methods.js +10 -0
  49. package/dist/sdk/sessions/sessionState.d.ts +13 -0
  50. package/dist/sdk/sessions/sessionState.js +31 -0
  51. package/dist/sdk/sessions/sessions.d.ts +7 -0
  52. package/dist/sdk/sessions/sessions.js +45 -5
  53. package/dist/sdk/sessions/subagentService.js +3 -3
  54. package/dist/sdk/terminal/opentui/theme.d.ts +2 -0
  55. package/dist/sdk/terminal/opentui/theme.js +1 -0
  56. package/dist/sdk/terminal/piExtension.js +71 -2
  57. package/dist/sdk/terminal/terminals.d.ts +9 -0
  58. package/dist/sdk/terminal/terminals.js +46 -14
  59. package/dist/sdk/terminal/tui/annotateCommand.d.ts +5 -1
  60. package/dist/sdk/terminal/tui/annotateCommand.js +21 -7
  61. package/dist/sdk/terminal/tui/annotateSend.d.ts +30 -0
  62. package/dist/sdk/terminal/tui/annotateSend.js +40 -0
  63. package/dist/sdk/terminal/tui/commandPages.d.ts +1 -1
  64. package/dist/sdk/terminal/tui/commandPages.js +2 -7
  65. package/dist/sdk/terminal/tui/commands.js +4 -2
  66. package/dist/sdk/terminal/tui/dialogs.js +1 -0
  67. package/dist/sdk/terminal/tui/keybindings.d.ts +1 -1
  68. package/dist/sdk/terminal/tui/keybindings.js +1 -1
  69. package/dist/sdk/terminal/tui/pageOverlay.d.ts +3 -0
  70. package/dist/sdk/terminal/tui/pageOverlay.js +12 -1
  71. package/dist/sdk/terminal/tui/pages/agentsPage.js +5 -2
  72. package/dist/sdk/terminal/tui/pages/annotatePage.d.ts +70 -16
  73. package/dist/sdk/terminal/tui/pages/annotatePage.js +349 -115
  74. package/dist/sdk/terminal/tui/pages/pluginsPage.d.ts +6 -0
  75. package/dist/sdk/terminal/tui/pages/pluginsPage.js +99 -1
  76. package/dist/sdk/terminal/tui/pages/usagePage.d.ts +4 -2
  77. package/dist/sdk/terminal/tui/pages/usagePage.js +39 -12
  78. package/dist/sdk/terminal/tui/pluginCommands.d.ts +1 -1
  79. package/dist/sdk/terminal/tui/pluginCommands.js +13 -3
  80. package/dist/sdk/tools/defaultSkills.d.ts +4 -0
  81. package/dist/sdk/tools/defaultSkills.js +20 -0
  82. package/dist/sdk/tools/definitions.d.ts +3 -1
  83. package/dist/sdk/tools/definitions.js +17 -1
  84. package/dist/sdk/tools/dispatch.js +12 -0
  85. package/dist/sdk/tools/harnessTools.js +1 -1
  86. package/dist/sdk/tools/sessionName.d.ts +7 -0
  87. package/dist/sdk/tools/sessionName.js +53 -8
  88. package/dist/sdk/world/world.d.ts +0 -2
  89. package/dist/terminal-opentui.js +2019 -1269
  90. package/dist/terminal-pi.js +106 -7
  91. package/docs/README.md +3 -0
  92. package/docs/architecture/02-sessions-and-runs.md +11 -5
  93. package/docs/architecture/03-variants.md +1 -3
  94. package/docs/architecture/04-prompt.md +16 -7
  95. package/docs/architecture/06-plugins-and-capabilities.md +36 -4
  96. package/docs/architecture/07-tools-and-gate.md +20 -5
  97. package/docs/architecture/10-server-protocol.md +52 -7
  98. package/docs/architecture/11-terminal.md +50 -19
  99. package/docs/architecture/12-storage.md +1 -0
  100. package/docs/architecture/13-world-tools.md +8 -6
  101. package/docs/architecture/README.md +3 -1
  102. package/docs/architecture/proposals/PROP-0018-annotation-queue-and-app-targets.md +6 -2
  103. package/docs/architecture/proposals/PROP-0048-simple-annotate.md +85 -0
  104. package/docs/architecture/proposals/README.md +1 -0
  105. package/docs/decisions/ADR-0044-annotations-pending-or-sent.md +24 -0
  106. package/docs/decisions/ADR-0045-default-plugin-authoring-skill.md +9 -0
  107. package/docs/decisions/ADR-0046-hash-bound-plugin-proposals.md +20 -0
  108. package/docs/decisions/ADR-0047-links-open-with-the-os-handler.md +47 -0
  109. package/docs/parity.md +7 -4
  110. package/docs/releases/1.3.1-unstable.1.md +8 -0
  111. package/docs/releases/1.3.1-unstable.2.md +11 -0
  112. package/docs/releases/README.md +7 -4
  113. package/docs/terminal-tui.md +62 -23
  114. package/package.json +1 -1
  115. package/dist/sdk/terminal/tui/pages/notesPage.d.ts +0 -75
  116. package/dist/sdk/terminal/tui/pages/notesPage.js +0 -201
@@ -1079,6 +1079,37 @@ async function withCommandBudget(run2, abort, seconds) {
1079
1079
  // src/tools/sessionName.ts
1080
1080
  var SESSION_NAME = "session_name";
1081
1081
  var SESSION_GUIDANCE = "If the request needs tools or changes state \u2014 not a greeting, thanks, or a short conversational reply \u2014 call session_name once before your first other tool call, naming the work from the request. Use one short imperative sentence of at most six words. Revise the name only when the overall objective changes; keep the current name when it does not.";
1082
+ function normalizeSessionName(value) {
1083
+ if (typeof value !== "string") throw invalid("Send name as a short sentence of at most six words.");
1084
+ if (/[\x00-\x08\x0e-\x1f\x7f-\x9f]/u.test(value)) {
1085
+ throw invalid("Session names cannot contain terminal escapes or control characters.");
1086
+ }
1087
+ const name = value.replace(/\s+/gu, " ").trim();
1088
+ if (!name || name.split(" ").length > 6) throw invalid("Use a non-empty session name of at most six words.");
1089
+ return name;
1090
+ }
1091
+ var CONVERSATIONAL = /^(?:hi|hello|hey|yo|thanks|thank you|ok|okay|sure|great|nice|cool|sounds good|got it|good morning|good afternoon|good evening|how are you|what'?s up)[.!?]*$/iu;
1092
+ var LEADING = /^(?:please|can you|could you|would you|i want you to|i'd like you to|help me|let'?s|go ahead and)[,\s]+/iu;
1093
+ function deriveSessionName(text4) {
1094
+ if (typeof text4 !== "string") return null;
1095
+ const input = text4.trim();
1096
+ if (!input || input.startsWith("!") || input.startsWith("```") || /^https?:\/\//iu.test(input)) return null;
1097
+ if (CONVERSATIONAL.test(input)) return null;
1098
+ if (/^continue\b/iu.test(input)) return "Continue previous work";
1099
+ const sentence = input.split(/[.!?](?:\s|$)/u)[0] ?? input;
1100
+ const cleaned = sentence.replace(/```[\s\S]*?```/gu, " ").replace(/[`*_~#>]/gu, " ").replace(/[:;,]+/gu, " ").replace(LEADING, "").replace(/\s+/gu, " ").trim();
1101
+ if (!/[a-z]/iu.test(cleaned)) return null;
1102
+ const words = cleaned.split(" ").filter(Boolean).slice(0, 6);
1103
+ if (!words.length) return null;
1104
+ const name = words.join(" ").replace(/^[\p{P}\p{S}]+/u, "").replace(/[\p{P}\p{S}]+$/u, "").trim();
1105
+ if (!name) return null;
1106
+ const capitalized = name[0].toUpperCase() + name.slice(1);
1107
+ try {
1108
+ return normalizeSessionName(capitalized);
1109
+ } catch {
1110
+ return null;
1111
+ }
1112
+ }
1082
1113
  function sessionNameTool(current) {
1083
1114
  return {
1084
1115
  name: SESSION_NAME,
@@ -1087,12 +1118,7 @@ function sessionNameTool(current) {
1087
1118
  parameters: (Type3) => Type3.Object({ name: Type3.String({ description: "One short sentence describing the objective, at most six words" }) }),
1088
1119
  planModeSafe: () => true,
1089
1120
  execute: async (input) => {
1090
- if (typeof input.name !== "string") throw invalid("Send name as a short sentence of at most six words.");
1091
- if (/[\x00-\x08\x0e-\x1f\x7f-\x9f]/u.test(input.name)) {
1092
- throw invalid("Session names cannot contain terminal escapes or control characters.");
1093
- }
1094
- const name = input.name.replace(/\s+/gu, " ").trim();
1095
- if (!name || name.split(" ").length > 6) throw invalid("Use a non-empty session name of at most six words.");
1121
+ const name = normalizeSessionName(input.name);
1096
1122
  const session = current();
1097
1123
  if (!session) throw invalid("The native session is unavailable; try naming it again once it is ready.");
1098
1124
  if (session.sessionName !== name) session.setSessionName(name);
@@ -1139,7 +1165,8 @@ var WORLD_GUIDANCE = [
1139
1165
  ].join("\n");
1140
1166
 
1141
1167
  // src/prompt/compile.ts
1142
- var SECTION_ORDER = { harnessIdentity: 5, system: 25, guardrails: 40, memory: 45, references: 50, subagents: 64, scripts: 66, wiki: 80, tools: 90, reporting: 95 };
1168
+ var SESSION_STATE_BUDGET = 1e3;
1169
+ var SECTION_ORDER = { harnessIdentity: 5, system: 25, sessionState: 30, guardrails: 40, memory: 45, references: 50, subagents: 64, scripts: 66, wiki: 80, tools: 90, reporting: 95 };
1143
1170
  function clip2(text4, limit) {
1144
1171
  return charCount(text4) <= limit ? text4 : `${takeChars(text4, limit)}\u2026`;
1145
1172
  }
@@ -1174,7 +1201,19 @@ ${todo}`);
1174
1201
 
1175
1202
  ${body}`;
1176
1203
  }
1204
+ function sessionStateText(state, options) {
1205
+ const parts = [];
1206
+ if (options.name) parts.push(`Name: ${state.name ? JSON.stringify(state.name) : "unnamed"}.`);
1207
+ if (options.todo) {
1208
+ parts.push(`Todo for this run: ${describeTodo(state.todo)}`);
1209
+ if (state.previousTodo?.length) parts.push(`Previous run's todo (context, not this run's list): ${describeTodo(state.previousTodo)}`);
1210
+ }
1211
+ if (!parts.length) return null;
1212
+ parts.push(state.firstTurn ? "This is the first turn in this native session." : "This run continues the conversation; the todo list resets for each run.");
1213
+ return clip2(parts.join("\n"), SESSION_STATE_BUDGET);
1214
+ }
1177
1215
  var BUILT_IN_DYNAMIC = [
1216
+ { id: "session-state", order: SECTION_ORDER.sessionState },
1178
1217
  { id: "references", order: SECTION_ORDER.references },
1179
1218
  { id: "wiki", order: SECTION_ORDER.wiki }
1180
1219
  ];
@@ -2244,6 +2283,10 @@ async function piExtension_default(pi, planRun, getSession) {
2244
2283
  const fileTools = /* @__PURE__ */ new Map();
2245
2284
  const writeAuthorizations = /* @__PURE__ */ new Map();
2246
2285
  let workspaceRoot = null;
2286
+ let sessionState = null;
2287
+ let stateDelivered = false;
2288
+ let autoNameTried = false;
2289
+ let lastTodo = [];
2247
2290
  let stage = "Tool discovery";
2248
2291
  try {
2249
2292
  await terminalCall("startup", { phase: stage });
@@ -2316,6 +2359,19 @@ async function piExtension_default(pi, planRun, getSession) {
2316
2359
  pi.registerTool(createWorkspaceShellTool({ createBashTool, createPowerShellTool }, process.cwd(), workspaceBash));
2317
2360
  pi.registerTool(withWorkspaceWriteAuthorization(createWriteTool(process.cwd(), { operations: workspaceWriteOperations }), writeAuthorizations));
2318
2361
  pi.registerTool(withWorkspaceWriteAuthorization(createEditTool(process.cwd(), { operations: workspaceEditOperations }), writeAuthorizations));
2362
+ pi.on("context", (event) => {
2363
+ if (!sessionState || stateDelivered) return;
2364
+ stateDelivered = true;
2365
+ return {
2366
+ messages: [...event.messages, {
2367
+ role: "custom",
2368
+ customType: "xingular-session-state",
2369
+ content: sessionState,
2370
+ display: false,
2371
+ timestamp: Date.now()
2372
+ }]
2373
+ };
2374
+ });
2319
2375
  compactionCheckpoint({ planInstructions: () => planRun?.active ? PLAN_INSTRUCTIONS : null })(pi);
2320
2376
  const slicePolicy = parseWorkSlice(void 0);
2321
2377
  const sliceState = createSliceState(slicePolicy);
@@ -2326,6 +2382,10 @@ async function piExtension_default(pi, planRun, getSession) {
2326
2382
  });
2327
2383
  pi.on("session_start", async (_event, ctx) => {
2328
2384
  context = ctx;
2385
+ sessionState = null;
2386
+ stateDelivered = false;
2387
+ autoNameTried = false;
2388
+ lastTodo = [];
2329
2389
  if (timer) clearInterval(timer);
2330
2390
  await terminalCall("ready", { nativeSessionId: ctx.sessionManager.getSessionFile(), owners: subagentHistory(ctx.sessionManager.getBranch?.() ?? []).owners });
2331
2391
  timer = setInterval(() => {
@@ -2421,6 +2481,39 @@ async function piExtension_default(pi, planRun, getSession) {
2421
2481
  stoppedChildren = null;
2422
2482
  if (notice) return { message: { customType: SUBAGENT_RESULTS, content: notice.text, display: false, details: { [SUBAGENT_RECEIPT]: notice.receipt } } };
2423
2483
  });
2484
+ pi.on("before_agent_start", async (event, ctx) => {
2485
+ if (event.messageType !== "user") return;
2486
+ const branch = ctx.sessionManager.getBranch?.() ?? [];
2487
+ const hasUser = branch.some((entry) => entry.type === "message" && entry.message?.role === "user");
2488
+ let name = typeof pi.getSessionName === "function" ? pi.getSessionName() ?? null : null;
2489
+ if (!name && !autoNameTried && pi.setSessionName) {
2490
+ const candidate = deriveSessionName(event.prompt);
2491
+ if (candidate) {
2492
+ autoNameTried = true;
2493
+ try {
2494
+ const policy = await controlCall("terminal.policy", { tool: SESSION_NAME, args: { name: candidate } });
2495
+ if (policy.allowed && !policy.requiresApproval) {
2496
+ pi.setSessionName(candidate);
2497
+ name = candidate;
2498
+ }
2499
+ } catch {
2500
+ }
2501
+ }
2502
+ }
2503
+ const state = {
2504
+ name,
2505
+ todo: [],
2506
+ ...lastTodo.length ? { previousTodo: lastTodo } : {},
2507
+ firstTurn: !hasUser
2508
+ };
2509
+ lastTodo = [];
2510
+ const active = typeof pi.getActiveTools === "function" ? pi.getActiveTools() : null;
2511
+ sessionState = sessionStateText(state, {
2512
+ name: active ? active.includes(SESSION_NAME) : true,
2513
+ todo: active ? active.includes(TODO_WRITE) : true
2514
+ });
2515
+ stateDelivered = false;
2516
+ });
2424
2517
  const deliverChildren = async (event, ctx, settle) => {
2425
2518
  if (!nativeSubagents || settle && event.outcome !== "completed" || ctx.signal?.aborted) return;
2426
2519
  const result = await withParentCancellation(ctx.signal, () => controlCall("terminal.subagents.delivery", { history: subagentHistory([...ctx.sessionManager.getBranch(), ...event.entries]), settle }, 2147483647));
@@ -2560,6 +2653,10 @@ async function piExtension_default(pi, planRun, getSession) {
2560
2653
  if (timer) clearInterval(timer);
2561
2654
  timer = null;
2562
2655
  context = null;
2656
+ sessionState = null;
2657
+ stateDelivered = false;
2658
+ autoNameTried = false;
2659
+ lastTodo = [];
2563
2660
  await terminalCall("shutdown").catch(() => {
2564
2661
  });
2565
2662
  });
@@ -2592,6 +2689,8 @@ async function piExtension_default(pi, planRun, getSession) {
2592
2689
  recorded = Promise.resolve();
2593
2690
  const result = await todo.execute(input);
2594
2691
  await recorded;
2692
+ const items = input.items;
2693
+ if (Array.isArray(items)) lastTodo = items;
2595
2694
  return { content: [{ type: "text", text: typeof result === "string" ? result : result.text }], details: void 0 };
2596
2695
  }
2597
2696
  });
package/docs/README.md CHANGED
@@ -17,6 +17,9 @@ change the binding architecture or describe implemented capabilities.
17
17
 
18
18
  | ID | Record | Type | Status | Related |
19
19
  |---|---|---|---|---|
20
+ | ADR-0047 | [A link a person clicks opens with the system's handler](decisions/ADR-0047-links-open-with-the-os-handler.md) | Decision | Implemented in the Harness, the terminal and the App; acceptance not certified | [10 Server protocol](architecture/10-server-protocol.md), [parity register](parity.md) |
21
+ | ADR-0046 | [Hash-bound plugin proposal review](decisions/ADR-0046-hash-bound-plugin-proposals.md) | Decision | Harness API and model proposal tool implemented; review surfaces pending | [06 Plugins](architecture/06-plugins-and-capabilities.md), [parity register](parity.md) |
22
+ | ADR-0045 | [Release-owned plugin-authoring skill](decisions/ADR-0045-default-plugin-authoring-skill.md) | Decision | Implemented as an on-demand resource | [06 Plugins](architecture/06-plugins-and-capabilities.md) |
20
23
  | PROP-0026 | [Connect structural sketch lines in the terminal display](architecture/proposals/PROP-0026-connected-sketch-display.md) | Proposal | Implemented; working tree and isolated fixtures verified | [ADR-0027](decisions/ADR-0027-connected-sketch-display.md), [11 Terminal](architecture/11-terminal.md), [parity register](parity.md) |
21
24
  | ADR-0027 | [Project structural ASCII sketch lines into connected terminal borders](decisions/ADR-0027-connected-sketch-display.md) | Decision | Accepted; working tree and isolated fixtures verified | [PROP-0026](architecture/proposals/PROP-0026-connected-sketch-display.md), [14 Surfaces and parity](architecture/14-surfaces-and-parity.md) |
22
25
  | FW-0001 | [Agent Modes, starting with Router Agent Mode](future-work.md#fw-0001-agent-modes-starting-with-router-agent-mode) | Future work | Candidate; requires architecture proposal before implementation | [Architecture glossary](architecture/README.md#glossary), [Feature guide](features/README.md#planned-agent-modes) |
@@ -109,7 +109,9 @@ A session that cannot open ends its run as `failed` and returns `nativeSessionId
109
109
  the session opened with.
110
110
  - **Agent profiles** (PROP-0029). `agent` names a profile: built-in (`worker`, `explorer`),
111
111
  `<data root>/agents/<name>.md`, `<project>/.xingular/agents/<name>.md`, or a c5 definition of
112
- the parent's variant, later sources winning (`agents/profiles.ts`). A profile narrows the
112
+ the parent's variant, later sources winning (`agents/profiles.ts`). A switched-on package's
113
+ profiles (page 06) then fill names nobody else took; the run resolves them once at start into
114
+ `packageProfiles`, and its children resolve their profiles from that list. A profile narrows the
113
115
  child's tools and plugins (`agents/narrow.ts`), may choose its variant, model and effort, and
114
116
  frames it with a "Your role" section. The child's record carries `profile`; the spawn result
115
117
  carries `agent` and any `unavailableTools`. `main` is reserved for the main agent's row: no
@@ -325,12 +327,16 @@ Decisions: [ADR-0002](../decisions/ADR-0002-native-subagent-lifecycle.md) (super
325
327
  ## Native session names (PROP-0010)
326
328
 
327
329
  `session_name({ name: string })` adds or revises the current Pi session's name in embedded
328
- and terminal execution. The agent calls it once before its first other tool call when a request
329
- needs tools or changes state, and revises it only when the overall objective changes, including a
330
- manual name. Agent-submitted names are imperative sentences
330
+ and terminal execution. The agent normally calls it once before its first other tool call when a
331
+ request needs tools or changes state, and revises it only when the overall objective changes,
332
+ including a manual name. When a top-level attended session starts unnamed, the harness also
333
+ derives a provisional name from a substantive first request before the first model request;
334
+ greetings, thanks and short conversational replies stay unnamed. The model may revise the
335
+ provisional name. Agent-submitted names are imperative sentences
331
336
  of at most six whitespace-separated words; whitespace is normalized, and empty names,
332
337
  terminal escapes, non-whitespace controls and longer names fail without writing. Identical
333
338
  names are a no-op. Pi's native session-info history is the only storage; continuation and
334
339
  reopen preserve it. Each child names only itself. There is no additional model request or
335
- run-event schema. The normal capability selection and host gate apply; `harnessTools: false`
340
+ run-event schema. The normal capability selection and host gate apply; a refused or failed
341
+ provisional name leaves the session unnamed and never fails the run. `harnessTools: false`
336
342
  omits the tool. Plan mode permits it as session metadata maintenance.
@@ -60,9 +60,7 @@ The surface is `PI_SURFACE` (`variant/surface.ts`), the one surface this harness
60
60
  - **INV-FND-2** A variant changes only by committing a new validated version (`commit` →
61
61
  `validate`, `INV-VAR-2`), and a refinement moves a head only when a person adopts
62
62
  (`INV-REF-6`). There is no other door.
63
- - **INV-VAR-1** A variant is the only thing in the harness that shapes an agent's
64
- instructions. The application adds its own sections through `Launch` (page 01); no other
65
- harness code adds instruction text.
63
+ - **INV-VAR-1** Variant instructions are versioned per scope. The application adds its own sections through `Launch` (page 01). The release-owned `plugin-authoring` skill is also available on demand in structured and terminal sessions, including existing variants; its body is not always-on. A variant skill with the same name takes precedence. It is shipped as a package resource and does not mutate pinned versions.
66
64
  - **INV-VAR-2** Every saved version is validated (`commit` → `validate`). An invalid variant is
67
65
  refused with every problem listed.
68
66
  - **INV-VAR-3** A version is never edited. A change is a new version; `restore` moves the head
@@ -28,8 +28,7 @@ A `ContextPack` holds `sections: Section[]` (each with `id`, `title`,
28
28
 
29
29
  ## Section order
30
30
 
31
- `SECTION_ORDER`: `harnessIdentity` 5, `system` 25, `guardrails` 40, `memory` 45, `references`
32
- 50, `subagents` 64, `scripts` 66, `wiki` 80, `tools` 90, `reporting` 95. Application sections
31
+ `SECTION_ORDER`: `harnessIdentity` 5, `system` 25, `sessionState` 30, `guardrails` 40, `memory` 45, `references` 50, `subagents` 64, `scripts` 66, `wiki` 80, `tools` 90, `reporting` 95. Application sections
33
32
  sit among them by their `order`; plan mode uses `plan` at 25. Ties keep insertion order.
34
33
  When a run may spawn, the dynamic `subagents` section lists every profile it can start (built-in,
35
34
  global, project and variant c5 names) and replaces the variant's own list (PROP-0029). Normal-mode
@@ -42,6 +41,14 @@ the first other tool call when work has several steps, asks for the list to stay
42
41
  requests a final update before the reply. Only fully completed work is
43
42
  marked completed; unfinished or blocked steps remain accurate (PROP-0006).
44
43
 
44
+ `session-state` is a built-in dynamic section at order 30 when a top-level run supplies it. It
45
+ names the current session or says “unnamed”, shows this run's todo (empty at the start) and a
46
+ previous run's list as context, and says whether this is the first turn. It describes only tools
47
+ in the frozen set: the name line appears only with `session_name`, and the todo line only with
48
+ `todo_write`. It never enters the stable prefix. Structured sessions deliver it through
49
+ `sessionLaunch` and the changed-section rule; the terminal appends the same text as a request-time
50
+ custom message.
51
+
45
52
  The fixed `harness-identity` section says `You are an AI agent running in <productName>.` and uses
46
53
  `env.productName` (default `Xingular Agent`). `Launch.standard: { cwd, project?: { name } | null }` requests shared role and working-folder
47
54
  sections from `prompt/standard.ts`; the compiler supplies common connections, file and annotation
@@ -114,8 +121,8 @@ file SecretStore with a host Keychain. See [parity](../parity.md).
114
121
  instructions. SDK sessions use `sessionLaunch`; terminal sessions use `compile` + `render`.
115
122
  - **INV-PRM-2** The system prompt holds only stable text: identity, role, the variant's sections, the
116
123
  harness's reporting guidance, tool guidance and the tool manifest. Changing state never enters it.
117
- - **INV-PRM-3** `references`, `wiki`, and every section the application marks `dynamic` are
118
- delivered as context updates in native history, never in the system prompt.
124
+ - **INV-PRM-3** `session-state`, `references`, `wiki`, and every section the application marks
125
+ `dynamic` are delivered as context updates in native history, never in the system prompt.
119
126
  - **INV-PRM-4** An update carries only changed dynamic sections, so an unchanged turn appends
120
127
  nothing. A compaction on the active branch forces the full snapshot again.
121
128
  - **INV-PRM-5** The pack only describes tools the caller can call (the frozen capability set).
@@ -150,8 +157,9 @@ what this page states is binding. Adopting parts of that draft is an architectur
150
157
  ## Source map
151
158
 
152
159
  `src/prompt/compile.ts`, `src/sessions/sessions.ts` (calls `sessionLaunch`),
153
- `src/terminal/terminals.ts` (calls `compile` + `render`), `src/variant/materialise.ts` (variant
154
- sections), `src/sessions/planMode.ts` (`plan` section).
160
+ `src/terminal/terminals.ts` (calls `compile` + `render`), `src/sessions/sessionState.ts`
161
+ (the native name reader and state shape), `src/variant/materialise.ts` (variant sections),
162
+ `src/sessions/planMode.ts` (`plan` section).
155
163
 
156
164
  ## Session naming guidance (PROP-0010)
157
165
 
@@ -159,4 +167,5 @@ The Session tool group describes `session_name` when available: call it once bef
159
167
  other tool call when a request needs tools or changes state, with an imperative sentence of at
160
168
  most six words, and revise only when the objective changes.
161
169
  This is fixed foundation guidance. The current name stays in native session metadata and
162
- the terminal snapshot; it is never interpolated into the stable system prompt.
170
+ the terminal snapshot; it may appear in the request-scoped `session-state` update, but it is never
171
+ interpolated into the stable system prompt.
@@ -3,7 +3,7 @@
3
3
  ## Purpose
4
4
 
5
5
  A *plugin* is a bundle with a title, a description and contributions: instructions, skills,
6
- commands, tools, connections, code (a Pi extension) and themes. A Pi package is a plugin as it is;
6
+ commands, subagent profiles (`agent`), tools, connections, code (a Pi extension) and themes. A Pi package is a plugin as it is;
7
7
  so are the harness's own parts, the application's parts, a person's registry, the folder every
8
8
  account shares, and what a working folder brings. This part decides what a session loads, who has
9
9
  what switched on, which code may run, and what reaches one caller. A *capability set* is the
@@ -22,6 +22,7 @@ callable result for one run.
22
22
  | `FIRST_PARTY_PLUGINS` | `plugins/firstParty.ts` | `output-trim`, `budget-guard`: inline extensions shipped switched off. `lessons`: switched off; its contribution turns on reflection after a run (page 08, PROP-0008) and loads no Pi code. |
23
23
  | `Hooks` | `plugins/hooks.ts` | Runs a package's hooks file after a write. |
24
24
  | install / trust | `plugins/install.ts`, `plugins/trust.ts` | Install through Pi's package manager with scripts off; trust code by hash. |
25
+ | proposals | `plugins/proposals.ts` | Validate and store inert proposals; preview, reject or accept a hash-bound review. |
25
26
  | inventory / api | `plugins/inventory.ts`, `plugins/api.ts` | `plugins.list`, `plugins.inventory`, attach, trust. |
26
27
  | capability api | `capabilities/api.ts`, `capabilities/types.ts` | `list`, `resolve`, `toolIntersection`, `inventory`, `attach`. |
27
28
  | run snapshot | `capabilities/runSnapshot.ts` | `freezeRun`, `loadRun`, `capabilitySet`. |
@@ -29,8 +30,9 @@ callable result for one run.
29
30
  ## Contracts
30
31
 
31
32
  - **Loading.** `Plugins.loading({ cwd, agentDir, caller, contributions, install? })` returns
32
- `extensionPaths`, `skillPaths`, `promptPaths`, `themePaths`, `builtins` (legacy shape; no Pi CLI built-ins selected), `hooks`,
33
- `found`, `detached`, `projectCode`, `packageCode`. A session opens Pi with its own discovery off
33
+ `extensionPaths`, `skillPaths`, `promptPaths`, `themePaths`, `profilePaths`, `builtins` (legacy shape; no Pi CLI built-ins selected), `hooks`,
34
+ `found`, `detached`, `projectCode`, `packageCode`. `profilePaths` are read by the harness for
35
+ subagent profiles (page 02); Pi is never given them. A session opens Pi with its own discovery off
34
36
  and only these paths; a terminal receives them as `--extension`, `--skill`,
35
37
  `--prompt-template` and `--theme` after `--no-extensions --no-skills --no-prompt-templates
36
38
  --no-themes`. Pi still reads `AGENTS.md` and `SYSTEM.md` itself.
@@ -45,10 +47,39 @@ callable result for one run.
45
47
  - **Attachments.** `config/plugin-attachments.json` holds `global`, `agents`, `projects` (each
46
48
  `{ on, off }`) and `settings` per plugin. The narrowest scope that says something wins: agent,
47
49
  then project, then everywhere. With no entry an item keeps its default.
48
- - **Package metadata.** A Pi package may declare `"harness": { "extends": [...], "hooks": "./hooks.mjs", "commandPrefix": "my-tools" }`.
50
+ - **Package metadata.** A Pi package may declare `"harness": { "extends": [...], "hooks": "./hooks.mjs", "commandPrefix": "my-tools", "agents": "./agents" }`.
51
+ A package without a `package.json` name is named, described and versioned by the first of
52
+ `plugin.json`, `.claude-plugin/plugin.json`, `.codex-plugin/plugin.json`, so an agent plugin
53
+ written for other harnesses installs as it is.
54
+ - **Package subagent profiles.** An installed package's agents folder (`agents/` unless
55
+ `harness.agents` names another) brings each Markdown file whose frontmatter has a `name` and a
56
+ `description` as an `agent` contribution (at most 50). It is text: it needs no trust and follows
57
+ its switch like a skill. The profile is named by its frontmatter, not its file. Fields only other
58
+ harnesses understand are dropped (`agents/profiles.ts`, `parsePackageProfile`): their tool names
59
+ are translated (`Read`→`read`, `Glob`→`find`, …), a model without a provider is left to the
60
+ parent, `plugins` and `variant` are never taken, and a tool list of which nothing translates
61
+ keeps the child read-only. A package profile never replaces a built-in, person's, project's or
62
+ variant's profile of the same name; the listing reports it as a problem instead.
49
63
  `commandPrefix` is optional; in the terminal, commands otherwise use a normalized package name as
50
64
  their owner prefix. Prefixes use lowercase letters, digits and hyphens, starting with a letter;
51
65
  `plugin` and `skill` are reserved. See page 11 for the command route and collision rules.
66
+ - **Plugin authoring.** `plugin_propose` creates a pending proposal, not an installation. The
67
+ release-owned `plugin-authoring` skill is available on demand in structured and terminal sessions;
68
+ a pinned variant's skill of the same name wins. It adds no trust or permission
69
+ ([ADR-0045](../decisions/ADR-0045-default-plugin-authoring-skill.md)).
70
+ - **Proposal review.** `plugins/proposals.ts` validates a lowercase package name, nonempty description,
71
+ and 1–100 UTF-8 text files (256 KiB each, 1 MiB total). It accepts `README.md`, extensions
72
+ (`.ts`, `.js`, `.mjs`), Markdown skills, prompts and agents, and JSON themes in their respective
73
+ directories; paths must be safe and cannot contain `.git` or `node_modules`. A
74
+ `skills/<name>/SKILL.md` needs matching name and nonempty description frontmatter. The Harness
75
+ generates `package.json`; it is not supplied by the proposal. Preview revalidates the stored data
76
+ and computes SHA-256 over name, description, generated manifest and sorted file entries. Accept
77
+ and reject require the current preview hash and pending status; stale reviews fail.
78
+ Acceptance rechecks after adoption and listing, refuses an existing package name or already-trusted
79
+ identical package code, stages and publishes under `<data root>/plugins/<name>`, clears old
80
+ attachment decisions for that package and explicitly switches it off globally. It grants no code
81
+ trust or permission; reject retains the proposal as rejected. These are trusted caller review
82
+ operations, not model tools. See [ADR-0046](../decisions/ADR-0046-hash-bound-plugin-proposals.md).
52
83
  - **Hooks.** A package declares `"harness": { "extends": [...], "hooks": "./hooks.mjs" }`. Events:
53
84
  `wiki.page.saved`, `history.run.ended`. A hook has 30 seconds; its errors are kept in
54
85
  `plugin-hooks.json`. `ctx.call(connection, tool, args)` reaches only a connected app that is on
@@ -114,6 +145,7 @@ callable result for one run.
114
145
  ```text
115
146
  <data root>/config/plugin-attachments.json (registry-enabled.json read until the first change)
116
147
  <data root>/plugins/<name>/ packages kept with the data; removal moves to trash/plugins/
148
+ <data root>/plugin-proposals/<id>.json proposed text, hash and review status
117
149
  <state dir>/plugin-trust.json trusted code, by hash
118
150
  <state dir>/plugin-registered.json what each extension registered last time
119
151
  <state dir>/plugin-hooks.json hooks and their last run
@@ -18,7 +18,7 @@ person without letting remembered per-tool grants widen that boundary.
18
18
  | `askUserTool` (`ask_user`) | `tools/askUser.ts` | Stops an attended plan run and asks up to five related questions with choices and concise 1–2 word labels; absent from newly resolved normal runs. |
19
19
  | `todoTool` (`todo_write`) | `tools/todo.ts` | Writes the run's whole todo list as a `todo.updated` event (PROP-0006, renamed by PROP-0045). Read-only for the gate, so plan mode allows it. Terminal sessions register the same tool; it reaches the run through the `todo` telemetry call. The prompt's Progress group asks the model to call it before the first other tool call when work has several steps, keep it current, and write one final update before replying; unfinished work is not automatically marked complete. The pre-rename `checklist.updated` event is still read, never written. |
20
20
  | `subagentTools` | `tools/spawnSubagent.ts` | `spawn_subagent` (requires a short `title`, PROP-0030) and `wait_subagents`; normal-mode descriptions guide selective, bounded delegation, while plan-mode spawns require a named eligible read-only research profile. |
21
- | `annotationsPart` (`page_notes_list`, `page_notes_read`, `page_notes_mark_fixed`) | `annotations/part.ts` | World tools over the page notes a person shared with the session or agent (PROP-0017). `page_notes_mark_fixed` records the agent's claim that it fixed a note it was sent; it never resolves a note or changes grants (PROP-0018). |
21
+ | `annotationsPart` (`page_notes_list`, `page_notes_read`) | `annotations/part.ts` | Read-only world tools over the page notes a person shared with the session or agent (PROP-0017, PROP-0048). |
22
22
  | `webTools` | `web/tools.ts` | `web_search` (Brave, key from the secret store), `web_fetch` (checked public reads). An application provides them as a provider. |
23
23
  | gate | `sessions/sessions.ts::gate`, `sessions/runner.ts` | `ToolGate { ask, check }`, loaded as the last extension (`xagent-approvals`). |
24
24
  | `Approvals`, `decide`, `grant`, `approvalKey` | `sessions/approvals.ts` | Standing approvals. |
@@ -26,7 +26,7 @@ person without letting remembered per-tool grants widen that boundary.
26
26
  Harness tools: `get_capabilities` (read-only current-run discovery), `history_search`, `history_read`,
27
27
  `trajectory_search`, `trajectory_read`, `wiki_search`, `wiki_read`, `wiki_list`, `wiki_write`
28
28
  (not in the default set), `skill_load`, `ask_user` (attended plan runs and pinned continuations only),
29
- `todo_write`. Broker:
29
+ `todo_write`, `plugin_propose`. Broker:
30
30
  `mcp_list_tools`, `mcp_call_tool`. Native Pi tools: `read`, `grep`, `find`,
31
31
  `ls`, `edit`, `write`, `bash`.
32
32
 
@@ -45,6 +45,17 @@ when plan mode is active it reports the plan's allowed tool set. `sessions/planM
45
45
  the shared read-only allowlist. Host sessions use this Harness tool rather than defining a duplicate.
46
46
  It reports availability, never permission, and every call remains subject to the gate.
47
47
 
48
+ ## Plugin proposal security
49
+
50
+ `plugin_propose { name, description, files }` is a write-classified Harness tool, subject to the
51
+ normal capability and per-call gate, and creates only a pending proposal in the Harness data root.
52
+ It does not accept, install, enable or trust a plugin. Proposal text is untrusted, including skill
53
+ instructions; preview and human review are needed before acceptance. Acceptance is a separate
54
+ trusted-caller API, bound to the reviewed content hash; it does not execute package code, grant
55
+ trust or bypass the loader, attachment controls, capability restrictions or gate. Text contributions
56
+ can load once enabled without code trust, so review their instructions as well as executable files.
57
+ See page 06 and [ADR-0046](../decisions/ADR-0046-hash-bound-plugin-proposals.md).
58
+
48
59
  ## Native file paths
49
60
 
50
61
  The read-only `read`, `grep`, `find` and `ls` tools accept paths relative to the working folder,
@@ -190,9 +201,13 @@ the switch and global tools.
190
201
  `session_name` (`tools/sessionName.ts`) binds to the current native session. It maintains
191
202
  only Pi session metadata and is explicitly plan-safe, while still subject to capability
192
203
  selection and the host policy. The prompt asks for it once before the first other tool call when
193
- a request needs tools or changes state. The terminal registers the same definition through its Pi
194
- bridge; standalone policy permits naming without approval. See page 02 for validation and
195
- persistence. It is a foundation tool, not mutable variant data.
204
+ a request needs tools or changes state. When a top-level attended session starts unnamed, the
205
+ harness also derives a provisional name from its first substantive request and sets it through
206
+ Pi before the first model request; a host gate refusal or a failed write leaves the session
207
+ unnamed and never fails the run. The model may revise the provisional name. The terminal
208
+ registers the same definition through its Pi bridge; standalone policy permits naming without
209
+ approval. See page 02 for validation and persistence. It is a foundation tool, not mutable
210
+ variant data.
196
211
 
197
212
  ## Diagnostic probes
198
213
 
@@ -70,6 +70,24 @@ harness → host { v: 1, id, call, params } host → harness { v: 1
70
70
  relayed in order (INV-RUN-3).
71
71
  - Errors carry a stable `code`, a message and an optional hint (`core/errors.ts`).
72
72
 
73
+ ## Plugin proposals
74
+
75
+ | Method | Input | Reply |
76
+ |---|---|---|
77
+ | `plugins.proposals.create` | `{ name, description, files }` (path-to-text object) | pending `Proposal` |
78
+ | `plugins.proposals.list` | `{}` | `Proposal[]`, including decided records |
79
+ | `plugins.proposals.preview` | `{ id }` | revalidated `Proposal` with current content hash |
80
+ | `plugins.proposals.accept` | `{ id, hash }` | accepted `Proposal` |
81
+ | `plugins.proposals.reject` | `{ id, hash }` | rejected `Proposal` |
82
+
83
+ A `Proposal` has `id`, `name`, `description`, `files`, generated `manifest`, `hash`, `createdAt`,
84
+ `status` and optional `decidedAt`. Both decisions require the pending proposal's current preview
85
+ hash; acceptance installs it switched off without trusting code. These methods expose trusted host
86
+ operations, not an assertion that a host has built a review UI. Protected terminal control routes
87
+ `plugins.proposals.list|preview|accept|reject` delegate to the same service when configured; they
88
+ require the terminal control key. The model tool can create only. Validation and trust details are
89
+ on page 06.
90
+
73
91
  ## Usage (PROP-0042)
74
92
 
75
93
  | Method | Input | Reply |
@@ -188,6 +206,7 @@ from preparation, never from the request.
188
206
  | `terminal.browser.connections.save` | `{ input: ConnectionInput }` | Existing safe `Connection` record |
189
207
  | `terminal.browser.connections.test\|signIn\|signOut\|remove` | `{ id }` | Existing connection service result |
190
208
  | `terminal.usage.summary\|limits` | `{ scope, period, timezoneOffsetMinutes }` / `{ refresh? }` | Existing usage service result, scoped to this terminal's account and project |
209
+ | `terminal.usage.allLimits` | `{ refresh? }` | All-account provider limits; refresh reads providers due under the configured cache interval, without changing the pinned account |
191
210
  | `terminal.usage.headers` | `{ provider, status, headers }` | `{}`; only limit-bearing headers, throttled, stored as an account limit reading |
192
211
 
193
212
  Protected `plugins.install { source }`, `plugins.update { pluginId? }` and
@@ -231,14 +250,18 @@ same service through `terminal.worktrees.*` routes, which need the control key (
231
250
  | `annotations.revokeBinding` | `{ binding }` | `{ revoked }` |
232
251
  | `annotations.import` | `{ notes }` | `{ imported, skipped }` (ids kept) |
233
252
  | `annotations.pageScript` | `{}` | `{ script }`: the page helper, with `__ARGS__` for one operation |
234
- | `annotations.queue` | `{ id, sessionId, expectedVersion?, autoSend? }` | `Note`, shared with the session and queued (PROP-0018) |
235
- | `annotations.dequeue` / `annotations.confirm` | `{ id, expectedVersion? }` | `Note` |
236
- | `annotations.queued` | `{ sessionId }` | `{ notes }`, oldest first |
237
- | `annotations.createAndAct` | `{ note, action: save \| queue \| send, sessionId?, trusted? }` | `{ note, send }`; an untrusted send waits for `confirm` |
238
- | `annotations.compose` | `{ sessionId, ids? }` | `{ text, ids }`: one instruction for a host's own `sessions.run` |
253
+ | `annotations.markPending` | `{ id, sessionId, expectedVersion? }` | `Note`, shared with the session and unsent (PROP-0018, PROP-0048) |
254
+ | `annotations.confirm` | `{ id, expectedVersion? }` | `Note` |
255
+ | `annotations.confirmAll` | `{ sessionId }` | `{ notes }`: every page-origin note of the session, confirmed |
256
+ | `annotations.pending` | `{ sessionId }` | `{ notes }`, unsent, oldest first |
257
+ | `annotations.clear` | `{ sessionId }` | `{ notes }`: the session's unsent notes, resolved and no longer shared with it |
258
+ | `annotations.createAndAct` | `{ note, action: save \| send, sessionId?, trusted? }` | `{ note, send }`; with a session the note is always shared; `send` sends all unsent notes; an untrusted note waits for `confirm` |
259
+ | `annotations.compose` | `{ sessionId, ids?, prompt? }` | `{ text, ids }`: one message for a host's own `sessions.run`, with the person's request last |
239
260
  | `annotations.delivered` | `{ ids, sessionId, runId }` | `{ notes }`, marked sent |
240
- | `annotations.send` | `{ sessionId, ids? }` | `{ state: sent \| busy \| host \| empty, … }` |
261
+ | `annotations.send` | `{ sessionId, ids?, prompt? }` | `{ state: sent \| busy \| host \| empty, …; empty has unconfirmed }` |
241
262
  | `annotations.capture.attach` | `{ key, kind: web \| cdp \| bridge, endpoint?, name? }` | `{ kind, app, windows, bridge? }` |
263
+ | `annotations.capture.discover` | `{}` | `{ apps: [{ endpoint, port, name, browser, electron, windows }] }`: apps on a loopback DevTools port |
264
+ | `annotations.capture.launch` | `{ key, path, args? }` | `{ kind: cdp, app, windows, endpoint }`: starts the app with a DevTools port and attaches |
242
265
  | `annotations.capture.target` | `{ key }` | `{ kind, app, inspecting, windows }` |
243
266
  | `annotations.capture.selectWindow` | `{ key, window }` | `{}` |
244
267
  | `annotations.capture.open` | `{ key, url? }` | `{ url, title }` |
@@ -247,9 +270,31 @@ same service through `terminal.worktrees.*` routes, which need the control key (
247
270
  | `annotations.capture.release` | `{ key }` | `{}` |
248
271
  | `annotations.bridge.start` | `{}` | `{ port, token, scriptUrl, snippet }` |
249
272
 
250
- Notices: `annotations.changed { sessionId, ids }` after any queue, send or fix;
273
+ Notices: `annotations.changed { sessionId, ids }` after any share, send or clear;
251
274
  `annotations.ready { sessionId, ids }` when a host session's waiting notes should be sent now.
252
275
 
253
276
  Errors: `version_conflict`, `not_found`, `annotation_limit`, `invalid_request`, `invalid_data`. The
254
277
  terminal reaches the same store through `terminal.annotations.*`, which shares only with its own
255
278
  session and needs the control key (`INV-TUI-4`).
279
+
280
+ ## Links (ADR-0047)
281
+
282
+ A link a person clicks is a person's action, not a model tool call: nothing here is in
283
+ `HARNESS_TOOLS`, so the gate, standing approvals and redaction never see it. `core/links.ts` holds
284
+ the one allowlist both front ends use, and `openLink` is the only door into the operating system.
285
+
286
+ | Method | Input | Reply |
287
+ |---|---|---|
288
+ | `links.open` | `{ target, base? }` | `OpenedTarget`: `{ kind: "web", url }`, `{ kind: "mail", address }`, `{ kind: "file", path }` or `{ kind: "directory", path }` |
289
+
290
+ `target` is what the link says; `base` is the absolute folder a relative target is resolved
291
+ against, and without it a relative target is refused. `linkTarget` classifies without touching the
292
+ filesystem (`http`/`https`, `mailto`, `file`, an absolute path, or a relative path under `base`),
293
+ and `openableTarget` then checks what it names: a regular file or a directory, never an application
294
+ bundle, an installer, or a launchable script, and never a file with an executable bit set, because
295
+ `xdg-open` runs one. The address is passed to `open`/`xdg-open`/`rundll32` as one argument, never
296
+ through a shell.
297
+
298
+ Errors: `link_not_openable`, with a message a person can read, and `invalid_request` when `target`
299
+ is missing. The opener is `HarnessOptions.linkOpener`, so a host with its own native opener keeps
300
+ the policy and replaces only the spawn.