@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.
- package/CHANGELOG.md +29 -1
- package/README.md +16 -12
- package/builtin/skills/plugin-authoring/SKILL.md +34 -0
- package/dist/cli.js +2334 -1715
- package/dist/sdk/agents/profiles.d.ts +13 -4
- package/dist/sdk/agents/profiles.js +59 -7
- package/dist/sdk/annotations/bridge.d.ts +2 -0
- package/dist/sdk/annotations/bridge.js +4 -0
- package/dist/sdk/annotations/capture.d.ts +44 -2
- package/dist/sdk/annotations/capture.js +104 -3
- package/dist/sdk/annotations/delivery.d.ts +24 -17
- package/dist/sdk/annotations/delivery.js +82 -49
- package/dist/sdk/annotations/inspect.js +7 -6
- package/dist/sdk/annotations/pageScript.js +4 -4
- package/dist/sdk/annotations/part.d.ts +0 -2
- package/dist/sdk/annotations/part.js +4 -33
- package/dist/sdk/annotations/queue.d.ts +2 -2
- package/dist/sdk/annotations/queue.js +12 -7
- package/dist/sdk/annotations/serverMethods.js +11 -7
- package/dist/sdk/annotations/store.d.ts +13 -21
- package/dist/sdk/annotations/store.js +47 -37
- package/dist/sdk/commands/list.js +2 -0
- package/dist/sdk/core/links.d.ts +51 -0
- package/dist/sdk/core/links.js +155 -0
- package/dist/sdk/harness.d.ts +5 -0
- package/dist/sdk/harness.js +11 -6
- package/dist/sdk/index.d.ts +1 -0
- package/dist/sdk/index.js +1 -0
- package/dist/sdk/plugins/builtin.js +11 -6
- package/dist/sdk/plugins/builtinRegistry.d.ts +3 -1
- package/dist/sdk/plugins/builtinRegistry.js +9 -3
- package/dist/sdk/plugins/discover.d.ts +7 -1
- package/dist/sdk/plugins/discover.js +41 -2
- package/dist/sdk/plugins/identity.js +1 -1
- package/dist/sdk/plugins/inventory.js +1 -1
- package/dist/sdk/plugins/manifest.d.ts +2 -0
- package/dist/sdk/plugins/manifest.js +21 -4
- package/dist/sdk/plugins/plugins.d.ts +2 -0
- package/dist/sdk/plugins/plugins.js +1 -0
- package/dist/sdk/plugins/proposals.d.ts +17 -0
- package/dist/sdk/plugins/proposals.js +147 -0
- package/dist/sdk/plugins/types.d.ts +1 -1
- package/dist/sdk/plugins/types.js +1 -1
- package/dist/sdk/prompt/compile.d.ts +11 -2
- package/dist/sdk/prompt/compile.js +32 -4
- package/dist/sdk/prompt/standard.d.ts +1 -1
- package/dist/sdk/prompt/standard.js +1 -1
- package/dist/sdk/server/methods.js +10 -0
- package/dist/sdk/sessions/sessionState.d.ts +13 -0
- package/dist/sdk/sessions/sessionState.js +31 -0
- package/dist/sdk/sessions/sessions.d.ts +7 -0
- package/dist/sdk/sessions/sessions.js +45 -5
- package/dist/sdk/sessions/subagentService.js +3 -3
- package/dist/sdk/terminal/opentui/theme.d.ts +2 -0
- package/dist/sdk/terminal/opentui/theme.js +1 -0
- package/dist/sdk/terminal/piExtension.js +71 -2
- package/dist/sdk/terminal/terminals.d.ts +9 -0
- package/dist/sdk/terminal/terminals.js +46 -14
- package/dist/sdk/terminal/tui/annotateCommand.d.ts +5 -1
- package/dist/sdk/terminal/tui/annotateCommand.js +21 -7
- package/dist/sdk/terminal/tui/annotateSend.d.ts +30 -0
- package/dist/sdk/terminal/tui/annotateSend.js +40 -0
- package/dist/sdk/terminal/tui/commandPages.d.ts +1 -1
- package/dist/sdk/terminal/tui/commandPages.js +2 -7
- package/dist/sdk/terminal/tui/commands.js +4 -2
- package/dist/sdk/terminal/tui/dialogs.js +1 -0
- package/dist/sdk/terminal/tui/keybindings.d.ts +1 -1
- package/dist/sdk/terminal/tui/keybindings.js +1 -1
- package/dist/sdk/terminal/tui/pageOverlay.d.ts +3 -0
- package/dist/sdk/terminal/tui/pageOverlay.js +12 -1
- package/dist/sdk/terminal/tui/pages/agentsPage.js +5 -2
- package/dist/sdk/terminal/tui/pages/annotatePage.d.ts +70 -16
- package/dist/sdk/terminal/tui/pages/annotatePage.js +349 -115
- package/dist/sdk/terminal/tui/pages/pluginsPage.d.ts +6 -0
- package/dist/sdk/terminal/tui/pages/pluginsPage.js +99 -1
- package/dist/sdk/terminal/tui/pages/usagePage.d.ts +4 -2
- package/dist/sdk/terminal/tui/pages/usagePage.js +39 -12
- package/dist/sdk/terminal/tui/pluginCommands.d.ts +1 -1
- package/dist/sdk/terminal/tui/pluginCommands.js +13 -3
- package/dist/sdk/tools/defaultSkills.d.ts +4 -0
- package/dist/sdk/tools/defaultSkills.js +20 -0
- package/dist/sdk/tools/definitions.d.ts +3 -1
- package/dist/sdk/tools/definitions.js +17 -1
- package/dist/sdk/tools/dispatch.js +12 -0
- package/dist/sdk/tools/harnessTools.js +1 -1
- package/dist/sdk/tools/sessionName.d.ts +7 -0
- package/dist/sdk/tools/sessionName.js +53 -8
- package/dist/sdk/world/world.d.ts +0 -2
- package/dist/terminal-opentui.js +2019 -1269
- package/dist/terminal-pi.js +106 -7
- package/docs/README.md +3 -0
- package/docs/architecture/02-sessions-and-runs.md +11 -5
- package/docs/architecture/03-variants.md +1 -3
- package/docs/architecture/04-prompt.md +16 -7
- package/docs/architecture/06-plugins-and-capabilities.md +36 -4
- package/docs/architecture/07-tools-and-gate.md +20 -5
- package/docs/architecture/10-server-protocol.md +52 -7
- package/docs/architecture/11-terminal.md +50 -19
- package/docs/architecture/12-storage.md +1 -0
- package/docs/architecture/13-world-tools.md +8 -6
- package/docs/architecture/README.md +3 -1
- package/docs/architecture/proposals/PROP-0018-annotation-queue-and-app-targets.md +6 -2
- package/docs/architecture/proposals/PROP-0048-simple-annotate.md +85 -0
- package/docs/architecture/proposals/README.md +1 -0
- package/docs/decisions/ADR-0044-annotations-pending-or-sent.md +24 -0
- package/docs/decisions/ADR-0045-default-plugin-authoring-skill.md +9 -0
- package/docs/decisions/ADR-0046-hash-bound-plugin-proposals.md +20 -0
- package/docs/decisions/ADR-0047-links-open-with-the-os-handler.md +47 -0
- package/docs/parity.md +7 -4
- package/docs/releases/1.3.1-unstable.1.md +8 -0
- package/docs/releases/1.3.1-unstable.2.md +11 -0
- package/docs/releases/README.md +7 -4
- package/docs/terminal-tui.md +62 -23
- package/package.json +1 -1
- package/dist/sdk/terminal/tui/pages/notesPage.d.ts +0 -75
- package/dist/sdk/terminal/tui/pages/notesPage.js +0 -201
package/dist/terminal-pi.js
CHANGED
|
@@ -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
|
-
|
|
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
|
|
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
|
|
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
|
|
329
|
-
needs tools or changes state, and revises it only when the overall objective changes,
|
|
330
|
-
manual name.
|
|
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;
|
|
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**
|
|
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
|
|
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/
|
|
154
|
-
|
|
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
|
|
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`.
|
|
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
|
|
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.
|
|
194
|
-
|
|
195
|
-
|
|
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.
|
|
235
|
-
| `annotations.
|
|
236
|
-
| `annotations.
|
|
237
|
-
| `annotations.
|
|
238
|
-
| `annotations.
|
|
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
|
|
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.
|