@xprnvd/pi-context-view 0.0.0-stage → 0.8.0

package/src/probe/trigger.ts

@@ -0,0 +1,178 @@
+/**
+ * ProbeTrigger: the automatic probe policy. It waits for idle, applies
+ * the probe preconditions, starts the one SilentProbe attempt of this runtime,
+ * and waits for its snapshot in SnapshotStore. It imports no capture module and
+ * applies no run-mode guard; consumers decide when to ask for a probe.
+ */
+import { type ExtensionAPI, type ExtensionCommandContext, shouldCompact } from "@earendil-works/pi-coding-agent";
+
+import type { CompactionState } from "../compaction.ts";
+import { readGlobalCacheWarmingMode, readLiveSettings } from "../settings.ts";
+import type { SnapshotReader } from "../snapshot.ts";
+import { probeFailure, type ProbeFailure } from "./failure.ts";
+import type { ProbeOutcome, SilentProbe } from "./silent-probe.ts";
+import { runWithProbeToken } from "./token.ts";
+
+/**
+ * How long to wait for the probe snapshot after the probe settles. Capture
+ * settles the probe's guard in its own `agent_settled` handler, which runs
+ * after SilentProbe's, so the snapshot normally arrives at once.
+ */
+const DEFAULT_SNAPSHOT_GRACE_MS = 1_000;
+
+/**
+ * Result of asking for a probe: the store received the probe's snapshot with a
+ * settled guard, or why it did not. The result holds no snapshot, so the
+ * cached attempt keeps none in memory; consumers read it from the store.
+ */
+export type ProbeResult =
+	| { readonly status: "captured" }
+	| ProbeFailure;
+
+/** Dependencies and timing of a ProbeTrigger. */
+export interface ProbeTriggerOptions {
+	readonly pi: ExtensionAPI;
+	readonly probe: SilentProbe;
+	readonly snapshots: SnapshotReader;
+	readonly compaction: CompactionState;
+	/** Wait after the probe settles before reporting a missing snapshot; defaults to 1 s. */
+	readonly snapshotGraceMs?: number;
+}
+
+/**
+ * Starts at most one probe per extension runtime; concurrent and later callers
+ * share its result. A skipped precondition does not consume the attempt.
+ */
+export class ProbeTrigger {
+	private readonly pi: ExtensionAPI;
+	private readonly probe: SilentProbe;
+	private readonly snapshots: SnapshotReader;
+	private readonly compaction: CompactionState;
+	private readonly snapshotGraceMs: number;
+	private attempt: Promise<ProbeResult> | undefined;
+
+	public constructor(options: ProbeTriggerOptions) {
+		this.pi = options.pi;
+		this.probe = options.probe;
+		this.snapshots = options.snapshots;
+		this.compaction = options.compaction;
+		this.snapshotGraceMs = options.snapshotGraceMs ?? DEFAULT_SNAPSHOT_GRACE_MS;
+	}
+
+	/**
+	 * Wait for idle, then resolve once the first `synthetic-probe` snapshot
+	 * published after the probe started has a settled guard, or with the reason
+	 * the probe was skipped or failed.
+	 */
+	public async request(context: ExtensionCommandContext): Promise<ProbeResult> {
+		await context.waitForIdle();
+		const failure = getProbeUnavailableFailure(this.pi, context, this.compaction.isActive);
+		if (failure !== undefined) return failure;
+		this.attempt ??= this.run(context);
+		return this.attempt;
+	}
+
+	/** Start the probe run with the working row hidden and wait for its result. */
+	private async run(context: ExtensionCommandContext): Promise<ProbeResult> {
+		const attempt = this.probe.start();
+		// Subscribe before sending, so no publication of this probe is missed
+		const result = waitForProbeResult(this.snapshots, attempt.completion, this.snapshotGraceMs);
+		// Only the attempt's starter sends: a repeated empty send would be a real turn
+		if (!attempt.started) return result;
+
+		context.ui.setWorkingVisible(false);
+		try {
+			// Pi emits `input` and `before_agent_start` from inside this call, so the
+			// token reaches both handlers and identifies the run even when another
+			// extension's input transform rewrites the prompt text.
+			runWithProbeToken(attempt.token, () => this.pi.sendUserMessage(""));
+		} catch (error) {
+			this.probe.fail("startup", error instanceof Error ? error.message : String(error));
+		}
+		try {
+			return await result;
+		} finally {
+			context.ui.setWorkingVisible(true);
+		}
+	}
+}
+
+/**
+ * Resolve once the probe's snapshot has a settled guard, with the attempt's
+ * failure, or with a missing-snapshot failure once `graceMs` passed after the
+ * probe settled.
+ * Probes run one at a time, so any `synthetic-probe` publication belongs to
+ * this attempt.
+ */
+function waitForProbeResult(
+	snapshots: SnapshotReader,
+	completion: Promise<ProbeOutcome>,
+	graceMs: number,
+): Promise<ProbeResult> {
+	return new Promise((resolve) => {
+		let finished = false;
+		let graceTimer: NodeJS.Timeout | undefined;
+		const unsubscribe = snapshots.subscribe((snapshot) => {
+			if (snapshot.origin === "synthetic-probe" && snapshot.guard.status !== "pending") {
+				finish({ status: "captured" });
+			}
+		});
+
+		/** Resolve once, then stop listening and cancel the grace timer. */
+		function finish(result: ProbeResult): void {
+			if (finished) return;
+			finished = true;
+			unsubscribe();
+			if (graceTimer !== undefined) clearTimeout(graceTimer);
+			resolve(result);
+		}
+
+		void completion.then((outcome) => {
+			if (finished) return;
+			if (outcome.status === "failed") {
+				finish(outcome);
+				return;
+			}
+			graceTimer = setTimeout(() => finish(probeFailure("missing-snapshot")), graceMs);
+		});
+	});
+}
+
+/** Explain why a silent probe cannot run now, or undefined when it can. */
+function getProbeUnavailableFailure(
+	pi: ExtensionAPI,
+	context: ExtensionCommandContext,
+	compactionInProgress: boolean,
+): ProbeFailure | undefined {
+	if (compactionInProgress) return probeFailure("compaction");
+	if (context.hasPendingMessages()) return probeFailure("pending-messages");
+	if (context.model === undefined) return probeFailure("missing-model");
+	// Pi's virtual-model discriminator is not exported from its package root
+	if (context.model.api === "pi-virtual") return probeFailure("virtual-model");
+	if (!context.modelRegistry.hasConfiguredAuth(context.model)) {
+		return probeFailure("missing-auth", context.model.provider);
+	}
+	return getProbeSettingsUnavailableFailure(pi, context);
+}
+
+/** Check live compaction settings and both sources of the global-only warming preference. */
+function getProbeSettingsUnavailableFailure(
+	pi: ExtensionAPI,
+	context: ExtensionCommandContext,
+): ProbeFailure | undefined {
+	try {
+		const settings = readLiveSettings(pi);
+		// The merged snapshot can mask global idle warming with an ignored project override
+		if (settings.getCacheWarmingMode() === "idle" || readGlobalCacheWarmingMode(context.cwd) === "idle") {
+			return probeFailure("idle-warming");
+		}
+		const compaction = settings.getCompactionSettings(context.model);
+		const usage = context.getContextUsage();
+		if (usage?.tokens != null && shouldCompact(usage.tokens, usage.contextWindow, compaction)) {
+			return probeFailure("context-limit");
+		}
+	} catch {
+		return probeFailure("settings");
+	}
+	return undefined;
+}

package/src/probe/view.ts

@@ -0,0 +1,26 @@
+/**
+ * ProbeView: all that capture reads from the probe layer. Capture never sees
+ * how or when a probe starts.
+ */
+import type { ContextEvent } from "@earendil-works/pi-coding-agent";
+
+import type { ProbeFilter } from "./filter.ts";
+import type { SilentProbe } from "./silent-probe.ts";
+
+/** Run origin and probe-message filter, read by capture. */
+export interface ProbeView {
+	/** True while SilentProbe owns the current run. */
+	readonly isCurrentRun: boolean;
+	/** Remove recorded probe messages; returns the same array when none match. */
+	filterMessages(messages: ContextEvent["messages"]): ContextEvent["messages"];
+}
+
+/** Combine ProbeFilter and SilentProbe into the one view capture depends on. */
+export function createProbeView(filter: ProbeFilter, probe: SilentProbe): ProbeView {
+	return {
+		get isCurrentRun() {
+			return probe.isCurrentRun;
+		},
+		filterMessages: (messages) => filter.filterMessages(messages),
+	};
+}

package/src/projection.ts

@@ -0,0 +1,122 @@
+/**
+ * Session projections for the views: the filtered projection at a leaf with
+ * each message's source entry, and the latest request snapshot, forced prompt
+ * included, applied to the current projection for Usage
+ * (doc/architecture/views.md). Reads snapshots and Pi data only; imports no
+ * capture or probe module.
+ */
+import { declarationsEqual, getCurrentSystemMessage, type SystemMessage } from "@earendil-works/pi-ai";
+import { buildSessionProjection, type SessionEntry } from "@earendil-works/pi-coding-agent";
+
+import type { ConversationChange, RequestMessage, RequestSnapshot, SystemChange } from "./snapshot.ts";
+
+/** A projected message with the session entry that owns it. */
+export interface ProjectedMessage {
+	readonly entryId: string;
+	readonly message: RequestMessage;
+}
+
+/** Removes recorded probe messages, as capture did for its baseline. */
+export type MessageFilter = (messages: RequestMessage[]) => RequestMessage[];
+
+/** Inputs for applying a request snapshot to the current projection. */
+export interface SnapshotApplicationInput {
+	/** Latest request snapshot, or undefined when none was captured. */
+	readonly snapshot: RequestSnapshot | undefined;
+	/** Current session entries; they are append-only, so the snapshot's leaf still rebuilds its baseline. */
+	readonly entries: SessionEntry[];
+	/** Current session leaf. */
+	readonly leafId: string | null;
+	readonly filterMessages: MessageFilter;
+}
+
+/** Current messages with the request's changes applied, and the system changes that still apply. */
+export interface AppliedRequest {
+	/** Current branch messages, system messages included, with the request's conversation changes. */
+	readonly messages: RequestMessage[];
+	/** Current branch messages without the request's changes, as Pi's session holds them. */
+	readonly branchMessages: RequestMessage[];
+	/** Request-only system changes; empty unless the recorded system state is unchanged since capture. */
+	readonly systemChanges: readonly SystemChange[];
+	/** The request's forced prompt, under the same freshness rule as `systemChanges`. */
+	readonly forcedPrompt?: string;
+}
+
+/** The filtered session projection at `leafId`, keeping each message's source entry. */
+export function readProjection(
+	entries: SessionEntry[],
+	leafId: string | null,
+	filterMessages: MessageFilter,
+): ProjectedMessage[] {
+	return buildSessionProjection(entries, leafId).entries.flatMap(({ sourceEntry, messages }) =>
+		filterMessages(messages).map((message) => ({ entryId: sourceEntry.id, message })));
+}
+
+/**
+ * Apply a request snapshot to the current projection. Conversation changes
+ * apply by baseline entry: additions are appended, a modification replaces its
+ * entry's message, and a deletion removes it. A change whose entry has left the
+ * projection is stale and dropped. System changes are deltas against the
+ * snapshot's replayed system state, and a forced prompt is a rendering of it,
+ * so both apply only while the current replayed state still equals it.
+ */
+export function applyRequestSnapshot(input: SnapshotApplicationInput): AppliedRequest {
+	const current = readProjection(input.entries, input.leafId, input.filterMessages);
+	const branchMessages = current.map(({ message }) => message);
+	if (input.snapshot === undefined) return { messages: branchMessages, branchMessages, systemChanges: [] };
+	const messages = applyConversationChanges(current, input.snapshot.changes.conversation);
+	return { messages, branchMessages, ...freshSystemState(input.snapshot, input.entries, messages) };
+}
+
+/** Current messages with modifications and deletions applied in place, then additions appended. */
+function applyConversationChanges(
+	current: readonly ProjectedMessage[],
+	changes: readonly ConversationChange[],
+): RequestMessage[] {
+	// A deletion maps its target to undefined
+	const replaced = new Map<ProjectedMessage, RequestMessage | undefined>();
+	const additions: RequestMessage[] = [];
+	for (const change of changes) {
+		if (change.type === "added") {
+			additions.push(change.message);
+			continue;
+		}
+		// An entry rarely holds more than one conversation message; take the first one not yet changed
+		const target = current.find((candidate) => candidate.entryId === change.entryId
+			&& candidate.message.role !== "system" && !replaced.has(candidate));
+		// Compaction or branch navigation removed the entry since capture
+		if (target === undefined) continue;
+		replaced.set(target, change.type === "modified" ? change.message : undefined);
+	}
+	const applied = current.flatMap((projected) => {
+		if (!replaced.has(projected)) return [projected.message];
+		const replacement = replaced.get(projected);
+		return replacement === undefined ? [] : [replacement];
+	});
+	return [...applied, ...additions];
+}
+
+/** The snapshot's system changes and forced prompt, or neither once the replayed state changed since capture. */
+function freshSystemState(
+	snapshot: RequestSnapshot,
+	entries: SessionEntry[],
+	messages: readonly RequestMessage[],
+): Omit<AppliedRequest, "messages" | "branchMessages"> {
+	const { changes: { system }, forcedPrompt } = snapshot;
+	if (system.length === 0 && forcedPrompt === undefined) return { systemChanges: [] };
+	const baseline = getCurrentSystemMessage(buildSessionProjection(entries, snapshot.leafId).messages);
+	if (!sameSystemState(baseline, getCurrentSystemMessage(messages))) return { systemChanges: [] };
+	return { systemChanges: system, forcedPrompt };
+}
+
+/** Whether two replayed system states have the same content, sections in order, and declarations. */
+function sameSystemState(a: SystemMessage | undefined, b: SystemMessage | undefined): boolean {
+	if (a === undefined || b === undefined) return a === b;
+	if (JSON.stringify(a.content) !== JSON.stringify(b.content)) return false;
+	if (JSON.stringify(Object.entries(a.sections ?? {})) !== JSON.stringify(Object.entries(b.sections ?? {}))) {
+		return false;
+	}
+	const aTools = a.toolsAdded ?? [];
+	const bTools = b.toolsAdded ?? [];
+	return aTools.length === bTools.length && aTools.every((tool, index) => declarationsEqual(tool, bTools[index]));
+}

package/src/prompt-additions.ts

@@ -0,0 +1,226 @@
+/** Pure, deliberately heuristic attribution of the unwrapped text around pi's prompt sections. */
+import type { SlashCommandInfo, SourceInfo, ToolInfo } from "@earendil-works/pi-coding-agent";
+
+import { AGGREGATE_SOURCE, extensionSource, type InjectionSource, type TextSpan } from "./model.ts";
+
+/** Public tool/command provenance only; no extension files are read to guess an owner. */
+export interface PromptSourceSlice {
+	readonly source: string;
+	readonly path: string;
+	/** Package root only, never a shared directory of loose extension files. */
+	readonly baseDir?: string;
+	/** Tools and slash commands this source registered; commands carry their `/`. */
+	readonly names?: readonly string[];
+}
+
+/** Optional observations that improve guesses without claiming handler-level provenance. */
+export interface PromptAdditionOptions {
+	readonly sources?: readonly PromptSourceSlice[];
+	/** Ordered, non-overlapping ranges counted as System Prompt sections, not additions. */
+	readonly excluded?: readonly TextSpan[];
+}
+
+/** One contiguous captured run outside prompt sections and whitespace-only gaps. */
+export interface PromptAdditionRun {
+	readonly text: string;
+	readonly source: InjectionSource;
+	/** Tool or command of `source` the run named, when exactly one of them occurs in it. */
+	readonly tool?: string;
+	readonly attribution?: "guess";
+}
+
+/** Characters that may follow a matched path: its own separator, or ordinary prose punctuation. */
+const PATH_BOUNDARY = "[/\\s\"'`<>\\[\\](),;:]";
+
+/** Shortest registered name worth guessing; shorter tokens match ordinary prose too readily. */
+const MIN_NAME_LENGTH = 3;
+
+/**
+ * Split the text after `start` into blank-line blocks, then guess a source only
+ * on a unique package-name or full-path match. Unmatched/ambiguous text stays
+ * unattributed.
+ */
+export function splitPromptAdditions(
+	prompt: string,
+	start: number,
+	options: PromptAdditionOptions,
+): PromptAdditionRun[] {
+	const regions = additionRegions(prompt, start, prompt.length, options.excluded ?? []);
+	const runs: Array<{ text: string; source: InjectionSource; tool?: string }> = [];
+	for (const region of regions) {
+		let previous: { text: string; source: InjectionSource; tool?: string } | undefined;
+		for (const text of splitBlocks(region)) {
+			const owner = guessOwner(text, options.sources ?? []);
+			// Merge only inside one region: text on either side of a section has different authors.
+			if (previous?.source.id === owner.source.id && previous.tool === owner.tool) {
+				previous.text += text;
+				continue;
+			}
+			previous = { text, ...owner };
+			runs.push(previous);
+		}
+	}
+	return runs.map((run) => ({
+		...run,
+		attribution: run.source.id === AGGREGATE_SOURCE.id ? undefined : "guess",
+	}));
+}
+
+/**
+ * Collect the provenance of every loaded extension that registered a tool or a
+ * command, together with the names it registered. It is the only extension
+ * roster pi exposes, and it feeds attribution guesses alone: extensions
+ * registering neither are invisible here.
+ */
+export function collectPromptSources(
+	allTools: readonly ToolInfo[],
+	commands: readonly SlashCommandInfo[],
+): PromptSourceSlice[] {
+	const sources = new Map<string, CollectedPromptSource>();
+	for (const tool of allTools) addPromptSource(sources, tool.sourceInfo, tool.name);
+	// Prompt text refers to a command the way a user types it, so keep its slash.
+	for (const command of commands) {
+		addPromptSource(sources, command.sourceInfo, command.name.startsWith("/") ? command.name : `/${command.name}`);
+	}
+	return [...sources.values()];
+}
+
+/** Keep gaps separate: removing a section must not join evidence from different additions. */
+function additionRegions(prompt: string, start: number, end: number, excluded: readonly TextSpan[]): string[] {
+	const regions: string[] = [];
+	let cursor = start;
+	for (const span of excluded) {
+		if (span.end <= cursor || span.start >= end) continue;
+		if (span.start > cursor) regions.push(prompt.slice(cursor, span.start));
+		cursor = Math.min(end, span.end);
+	}
+	if (cursor < end) regions.push(prompt.slice(cursor, end));
+	return regions;
+}
+
+/** Keep separators with the following block; trailing whitespace stays with the final block. */
+function splitBlocks(text: string): string[] {
+	const blocks: string[] = [];
+	let start = 0;
+	for (const separator of text.matchAll(/\r?\n[\t ]*\r?\n(?:[\t ]*\r?\n)*/g)) {
+		if (text.slice(start, separator.index).trim().length === 0) continue;
+		if (text.slice(separator.index).trim().length === 0) break;
+		blocks.push(text.slice(start, separator.index));
+		start = separator.index;
+	}
+	// Removing a section can leave a separator behind; blank text has no author.
+	if (text.slice(start).trim().length > 0) blocks.push(text.slice(start));
+	return blocks;
+}
+
+/** Extension a block was guessed to belong to, and the tool or command it named. */
+interface PromptAdditionOwner {
+	readonly source: InjectionSource;
+	readonly tool?: string;
+}
+
+/**
+ * Several tools/commands from one package are one candidate, not an ambiguous
+ * match; two path extensions are two candidates.
+ */
+function guessOwner(text: string, sources: readonly PromptSourceSlice[]): PromptAdditionOwner {
+	const normalized = text.replaceAll("\\", "/");
+	const matches = new Map<string, InjectionSource>();
+	for (const source of sources) {
+		if (source.source === "builtin" || source.source === "sdk") continue;
+		const packageName = source.source.match(/^npm:((?:@[^/]+\/)?[^@]+)(?:@.*)?$/)?.[1];
+		if (
+			containsPath(normalized, source.path) || containsPath(normalized, source.baseDir) ||
+			(packageName !== undefined && containsPackage(normalized, packageName)) ||
+			(/^(npm:|git:|https?:\/\/|ssh:\/\/)/.test(source.source) && containsPackage(normalized, source.source))
+		) {
+			const owner = extensionSource(source, sources);
+			matches.set(owner.id, owner);
+		}
+	}
+	const [match] = matches.values();
+	if (matches.size !== 1 || match === undefined) return { source: AGGREGATE_SOURCE };
+	return { source: match, tool: guessTool(normalized, sources, match.id) };
+}
+
+/**
+ * Registered tool or command of the owning extension the block names, when
+ * exactly one of them occurs in it. Two mentions name no tool, as two packages
+ * name no extension; the result only qualifies a guessed label, so it never
+ * changes which item counts the text.
+ */
+function guessTool(
+	text: string,
+	sources: readonly PromptSourceSlice[],
+	ownerId: string,
+): string | undefined {
+	const matches = new Set<string>();
+	for (const source of sources) {
+		if (extensionSource(source).id !== ownerId) continue;
+		for (const name of source.names ?? []) {
+			if (name.length >= MIN_NAME_LENGTH && containsName(text, name)) matches.add(name);
+		}
+	}
+	const [name] = matches;
+	return matches.size === 1 ? name : undefined;
+}
+
+/**
+ * Require a complete name token, so a longer identifier and a path segment are
+ * no mention: `web_search` matches in prose but not in `tools/web_search.md`,
+ * and the command `/ask` matches only where it is written with its slash.
+ */
+function containsName(text: string, name: string): boolean {
+	return new RegExp(`(?<![\\w/-])${escapePattern(name)}(?![\\w-])`).test(text);
+}
+
+/**
+ * Require a complete package token: a longer package name must not match, while
+ * ordinary sentence punctuation after the name must, so `pi-web-providers` and
+ * `pi-web.js` are rejected where `npm:pi-web.` is accepted.
+ */
+function containsPackage(text: string, name: string): boolean {
+	const escaped = escapePattern(name);
+	return new RegExp(`(?:^|[^\\w@/.-]|/node_modules/)${escaped}(?![\\w-])(?!\\.[\\w-])`).test(text);
+}
+
+/** Match absolute paths at boundaries; a package root may be followed by a child path. */
+function containsPath(text: string, path: string | undefined): boolean {
+	if (path === undefined) return false;
+	const normalized = path.replaceAll("\\", "/").replace(/\/+$/, "");
+	// A relative or synthetic provenance such as `<builtin:read>` is no evidence of authorship.
+	if (!/^(\/|[A-Za-z]:\/).+/.test(normalized)) return false;
+	return new RegExp(`(?:^|[^\\w/.-])${escapePattern(normalized)}(?=$|${PATH_BOUNDARY})`).test(text);
+}
+
+/** Escape literal provenance before using it in a boundary-sensitive pattern. */
+function escapePattern(text: string): string {
+	return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** Slice under construction: its names arrive one tool or command at a time. */
+interface CollectedPromptSource extends Omit<PromptSourceSlice, "names"> {
+	readonly names: string[];
+}
+
+/** Record one registered name under its extension's provenance, skipping pi's own sources. */
+function addPromptSource(
+	sources: Map<string, CollectedPromptSource>,
+	sourceInfo: SourceInfo,
+	name: string,
+): void {
+	if (sourceInfo.source === "builtin" || sourceInfo.source === "sdk") return;
+	const key = `${sourceInfo.source}\n${sourceInfo.path}`;
+	let collected = sources.get(key);
+	if (collected === undefined) {
+		collected = {
+			source: sourceInfo.source,
+			path: sourceInfo.path,
+			// A top-level extension's baseDir is a shared directory, not its own root.
+			baseDir: sourceInfo.origin === "package" ? sourceInfo.baseDir : undefined,
+			names: [],
+		};
+		sources.set(key, collected);
+	}
+	if (!collected.names.includes(name)) collected.names.push(name);
+}

package/src/prompt-blocks.ts

@@ -0,0 +1,80 @@
+/** Locate pi's XML prompt sections without assuming extensions preserve their order. */
+import type { TextSpan } from "./model.ts";
+
+/** Block pi renders one bullet per visible tool into, in its `tools` section. */
+export const AVAILABLE_TOOLS_BLOCK = { id: "base-prompt:available-tools", label: "Tools" };
+/** Block pi renders tool guideline bullets into, in its `rules` section. */
+export const GUIDELINES_BLOCK = { id: "base-prompt:guidelines", label: "Rules" };
+/** Block pi renders its own documentation into, in its `docs` section. */
+export const DOCUMENTATION_BLOCK = { id: "base-prompt:documentation", label: "Docs" };
+
+/** Pi's normal emission order, also the blocks a custom prompt replaces. */
+export const BASE_PROMPT_BLOCKS = [AVAILABLE_TOOLS_BLOCK, GUIDELINES_BLOCK, DOCUMENTATION_BLOCK];
+
+/** One complete top-level XML section, with transport framing separated from its body. */
+export interface PromptSection extends TextSpan {
+	readonly name: string;
+	/** Includes the newline before the body, but not the newline before the closing tag. */
+	readonly body: TextSpan;
+}
+
+/**
+ * Locate pi's sections in rendered order. Skip whole sections and fenced examples
+ * so tags in instruction files, skills, addenda, and custom sections are not blocks.
+ */
+export function findPromptSections(prompt: string): PromptSection[] {
+	const sections: PromptSection[] = [];
+	let fence: string | undefined;
+	const pattern = /^<([a-z][a-z0-9_-]*)>\n|^ {0,3}(`{3,}|~{3,})([^\n]*)/gm;
+	for (let match = pattern.exec(prompt); match !== null; match = pattern.exec(prompt)) {
+		const marker = match[2];
+		if (marker !== undefined) {
+			if (fence === undefined) fence = marker;
+			else if (marker[0] === fence[0] && marker.length >= fence.length && match[3].trim() === "") fence = undefined;
+			continue;
+		}
+		if (fence !== undefined) continue;
+		const name = match[1];
+		const closing = `\n</${name}>`;
+		const end = prompt.indexOf(closing, pattern.lastIndex);
+		if (end === -1) continue;
+		const after = end + closing.length;
+		if (after < prompt.length && prompt[after] !== "\n") continue;
+		sections.push({ name, start: match.index, end: after, body: { start: pattern.lastIndex - 1, end } });
+		pattern.lastIndex = after;
+	}
+	return sections;
+}
+
+/** Locate native XML tool surfaces with bounded, consecutive bullet regions and positional markers. */
+export function findSectionToolBlocks(prompt: string, sections: readonly PromptSection[]): LocatedPromptBlock[] {
+	const order = ["tools", "rules", "docs", "addendum", "project_context", "skills", "cwd"];
+	return sections.flatMap((section): LocatedPromptBlock[] => {
+		if (section.name !== "tools" && section.name !== "rules") return [];
+		const block = section.name === "tools" ? AVAILABLE_TOOLS_BLOCK : GUIDELINES_BLOCK;
+		const moved = sections.some((other) => other.start < section.start &&
+			order.indexOf(other.name) > order.indexOf(section.name));
+		const bullets = findBulletSpan(prompt, section.body.start);
+		return [{ ...block, ...section.body, bullets, moved: moved || undefined }];
+	});
+}
+
+/** One native tool-surface section body and its bullet region, in original prompt coordinates. */
+export interface LocatedPromptBlock extends TextSpan {
+	readonly id: string;
+	readonly label: string;
+	/** Exact bullet region, including the newline before the first bullet. */
+	readonly bullets?: TextSpan;
+	/** Position differs from pi's normal block order; no claim about which handler moved it. */
+	readonly moved?: boolean;
+}
+
+/** Consecutive complete bullet lines; stop before any unrelated prose. */
+function findBulletSpan(prompt: string, start: number): TextSpan | undefined {
+	let end = start;
+	while (prompt.startsWith("\n- ", end)) {
+		const newline = prompt.indexOf("\n", end + 1);
+		end = newline === -1 ? prompt.length : newline;
+	}
+	return end === start ? undefined : { start, end };
+}