@devspecai/pi-plugin 0.0.0-stage → 0.10.3

package/extensions/core/background-journal.ts

@@ -0,0 +1,85 @@
+import { projectBackgroundTask, type ObservedBackgroundTask } from "./background-observer.ts";
+
+/** Non-context session entries: observation only, never executable authority. */
+export const BACKGROUND_WORK_ENTRY = "devspec-background-observation";
+export interface BackgroundWorkScope {
+	nativeSessionId: string;
+	connectionId: string;
+	sessionId: string;
+	attachmentId: string;
+}
+export interface BackgroundWorkEntry {
+	version: 1;
+	scope: BackgroundWorkScope;
+	task: ObservedBackgroundTask;
+}
+const scopeFields = ["nativeSessionId", "connectionId", "sessionId", "attachmentId"] as const;
+function record(value: unknown): Record<string, unknown> | null {
+	return value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : null;
+}
+export function backgroundScopeKey(scope: BackgroundWorkScope): string {
+	return JSON.stringify(scopeFields.map(field => scope[field]));
+}
+
+/** Copy an allowlist only; never persist the provider's full snapshot. */
+export function backgroundWorkEntry(scope: BackgroundWorkScope, task: ObservedBackgroundTask): BackgroundWorkEntry {
+	return {
+		version: 1,
+		scope: { nativeSessionId: scope.nativeSessionId, connectionId: scope.connectionId, sessionId: scope.sessionId, attachmentId: scope.attachmentId },
+		task: { id: task.id, startTime: task.startTime, state: task.state },
+	};
+}
+
+function parseEntry(value: unknown): BackgroundWorkEntry | null {
+	const row = record(value);
+	const scope = record(row?.scope);
+	const task = record(row?.task);
+	if (row?.version !== 1 || !scope || !task ||
+		Object.keys(row).some(key => !["version", "scope", "task"].includes(key)) ||
+		Object.keys(scope).some(key => !(scopeFields as readonly string[]).includes(key)) ||
+		Object.keys(task).some(key => !["id", "startTime", "state"].includes(key)) ||
+		scopeFields.some(field => typeof scope[field] !== "string" || !scope[field] || (scope[field] as string).length > 256)) return null;
+	const projected = projectBackgroundTask({ id: task.id, startTime: task.startTime, status: task.state === "unknown" ? "running" : task.state });
+	if (!projected) return null;
+	if (task.state === "unknown") projected.state = "unknown";
+	return backgroundWorkEntry(scope as unknown as BackgroundWorkScope, projected);
+}
+
+/**
+ * Pass getBranch(), never every entry in the file: abandoned branches and other
+ * attachments cannot donate work. Restoration proves only ownership. A formerly
+ * running task is unknown until the current provider confirms it; terminal rows
+ * cannot be resurrected by delayed running snapshots or duplicate launch rows.
+ */
+export function restoreBackgroundWork(entries: readonly unknown[], scope: BackgroundWorkScope): ObservedBackgroundTask[] {
+	const key = backgroundScopeKey(scope);
+	const tasks = new Map<string, ObservedBackgroundTask>();
+	for (const value of entries) {
+		const row = record(value);
+		if (row?.type !== "custom" || row.customType !== BACKGROUND_WORK_ENTRY) continue;
+		const entry = parseEntry(row.data);
+		if (!entry || backgroundScopeKey(entry.scope) !== key) continue;
+		const previous = tasks.get(entry.task.id);
+		if (previous && (previous.startTime !== entry.task.startTime || !["running", "unknown"].includes(previous.state))) continue;
+		tasks.set(entry.task.id, entry.task);
+	}
+	return [...tasks.values()].filter(task => task.state === "running" || task.state === "unknown")
+		.map(task => ({ id: task.id, startTime: task.startTime, state: "unknown" }));
+}
+
+/**
+ * Tasks this conversation and connection journaled as finished (any attachment):
+ * a launch restored after /reload whose task already ended will not wake this
+ * instance (item 7a4d04fd). Only explicit terminal rows count.
+ */
+export function journaledFinishedTasks(entries: readonly unknown[], nativeSessionId: string, connectionId: string): Set<string> {
+	const finished = new Set<string>();
+	for (const value of entries) {
+		const row = record(value);
+		if (row?.type !== "custom" || row.customType !== BACKGROUND_WORK_ENTRY) continue;
+		const entry = parseEntry(row.data);
+		if (!entry || entry.scope.nativeSessionId !== nativeSessionId || entry.scope.connectionId !== connectionId) continue;
+		if (entry.task.state === "completed" || entry.task.state === "failed" || entry.task.state === "killed") finished.add(entry.task.id);
+	}
+	return finished;
+}

package/extensions/core/background-observer.ts

@@ -0,0 +1,279 @@
+import { randomUUID } from "node:crypto";
+
+// db495c8f: observe the provider, never the model's consumption of a notice.
+// Public API: pi-background-tasks/docs/api/eventbus-v1.md. No provider imports,
+// task files, commands, output paths, prompt content or credentials are retained.
+const REQUEST = "pi-background-tasks:request:v1";
+const RESPONSE = "pi-background-tasks:response:v1";
+const TERMINAL = "pi-background-tasks:terminal:v1";
+const REQUEST_SCHEMA = "pi-background-tasks.extension-request.v1";
+const RESPONSE_SCHEMA = "pi-background-tasks.extension-response.v1";
+const TERMINAL_SCHEMA = "pi-background-tasks.extension-terminal.v1";
+const LAUNCH_TOOLS = new Set([
+	"bg_run", "bg_run_pi_attested", "bg_delegate", "fusion_reason",
+	"fusion_investigate", "fusion_research", "fusion_validate",
+]);
+
+export interface BackgroundEventBus {
+	on(event: string, handler: (value: unknown) => void): (() => void) | void;
+	emit(event: string, value: unknown): void;
+}
+
+/** Opaque caller-owned native-session + attachment generation, not a room name. */
+export type BackgroundScope = string;
+export type ObservedTaskState = "running" | "unknown" | "completed" | "failed" | "killed";
+export interface ObservedBackgroundTask {
+	id: string;
+	/** Provider launch identity protects against a stale response for a reused id. */
+	startTime: number;
+	state: ObservedTaskState;
+}
+export interface BackgroundObservation {
+	scope: BackgroundScope | null;
+	tasks: ObservedBackgroundTask[];
+}
+
+function record(value: unknown): Record<string, unknown> | null {
+	return value !== null && typeof value === "object" && !Array.isArray(value)
+		? value as Record<string, unknown> : null;
+}
+function terminal(state: ObservedTaskState): boolean {
+	return state === "completed" || state === "failed" || state === "killed";
+}
+
+/** Allowlist projection. Never spread a provider snapshot into shared state. */
+export function projectBackgroundTask(value: unknown): ObservedBackgroundTask | null {
+	const row = record(value);
+	if (!row || typeof row.id !== "string" || !row.id || row.id.length > 200 || row.id.trim() !== row.id ||
+		typeof row.startTime !== "number" || !Number.isSafeInteger(row.startTime) || row.startTime < 0 ||
+		typeof row.status !== "string" || !["running", "completed", "failed", "killed"].includes(row.status)) return null;
+	return { id: row.id, startTime: row.startTime, state: row.status as ObservedTaskState };
+}
+
+/** A tool that starts provider background work (the launch, not its inspection). */
+export function isBackgroundLaunchTool(toolName: string): boolean {
+	return LAUNCH_TOOLS.has(toolName);
+}
+
+/** A successful launch proves ownership; inspection of someone else's task does not. */
+export function backgroundTaskFromLaunch(toolName: string, result: unknown, isError = false): ObservedBackgroundTask | null {
+	if (isError || !LAUNCH_TOOLS.has(toolName)) return null;
+	const outer = record(result);
+	const details = record(outer?.details) ?? outer;
+	return projectBackgroundTask(details?.task);
+}
+
+/** Validated management results observe known work; they never establish ownership. */
+export function backgroundTasksFromManagement(toolName: string, result: unknown, isError = false): ObservedBackgroundTask[] {
+	if (isError || (toolName !== "bg_kill" && toolName !== "bg_status")) return [];
+	const outer = record(result);
+	const details = record(outer?.details) ?? outer;
+	const values = toolName === "bg_kill" ? [details?.task] : details?.tasks;
+	if (!Array.isArray(values)) return [];
+	return values.map(projectBackgroundTask).filter((task): task is ObservedBackgroundTask => task !== null);
+}
+
+interface PendingRequest {
+	operation: "capabilities" | "status";
+	finish: (value: Record<string, unknown> | null) => void;
+}
+
+/**
+ * Small observation adapter, not a task manager. Only explicitly registered
+ * launches/restored identities belong here. A status listing is never authority
+ * to adopt work. Missing, unavailable and malformed observations stay unknown.
+ *
+ * Caller drives refresh from its existing lifecycle/safety cadence. Terminal
+ * events are immediate; no extra model turn, polling loop or server request.
+ */
+export class BackgroundWorkObserver {
+	private scope: BackgroundScope | null = null;
+	private epoch = 0;
+	private supported = false;
+	private disposed = false;
+	private readonly tasks = new Map<string, ObservedBackgroundTask>();
+	private readonly earlyTerminals = new Map<string, ObservedBackgroundTask>();
+	private readonly pending = new Map<string, PendingRequest>();
+	private readonly subscriptions: (() => void)[] = [];
+	private inFlight: Promise<void> | null = null;
+	private offset = 0;
+	private readonly events: BackgroundEventBus;
+	private readonly onChange: (observation: BackgroundObservation) => void;
+	private readonly options: { timeoutMs?: number; batchSize?: number; concurrency?: number; earlyLimit?: number };
+
+	constructor(
+		events: BackgroundEventBus,
+		onChange: (observation: BackgroundObservation) => void,
+		options: { timeoutMs?: number; batchSize?: number; concurrency?: number; earlyLimit?: number } = {},
+	) {
+		this.events = events;
+		this.onChange = onChange;
+		this.options = options;
+		for (const [name, handler] of [
+			[RESPONSE, (value: unknown) => this.response(value)],
+			[TERMINAL, (value: unknown) => this.terminalEvent(value)],
+		] as const) {
+			const stop = events.on(name, handler);
+			if (typeof stop === "function") this.subscriptions.push(stop);
+		}
+	}
+
+	/** A real attachment/session change revokes old observations and pending callbacks. */
+	bind(scope: BackgroundScope | null): void {
+		if (this.disposed || this.scope === scope) return;
+		this.epoch += 1;
+		this.scope = scope;
+		this.supported = false;
+		this.tasks.clear();
+		this.earlyTerminals.clear();
+		this.offset = 0;
+		for (const request of [...this.pending.values()]) request.finish(null);
+		this.inFlight = null;
+		this.changed();
+	}
+
+	/** Caller captures scope when work launches, not when its tool result arrives. */
+	track(task: ObservedBackgroundTask, scope: BackgroundScope): boolean {
+		if (this.disposed || !this.scope || scope !== this.scope || !this.validIdentity(task)) return false;
+		const old = this.tasks.get(task.id);
+		if (old) {
+			// Conflicting launch identities are not evidence the old work finished.
+			if (old.startTime !== task.startTime) return false;
+			this.apply(old, task.state);
+			return true;
+		}
+		const early = this.earlyTerminals.get(task.id);
+		const current: ObservedBackgroundTask = { id: task.id, startTime: task.startTime, state: task.state };
+		if (early?.startTime === task.startTime) current.state = early.state;
+		this.earlyTerminals.delete(task.id);
+		this.tasks.set(task.id, current);
+		this.changed();
+		return true;
+	}
+
+	/** An inspection/terminal result can update only an already-owned execution. */
+	observe(task: ObservedBackgroundTask, scope: BackgroundScope): boolean {
+		const owned = this.tasks.get(task.id);
+		if (this.disposed || scope !== this.scope || !owned || !this.validIdentity(task) || owned.startTime !== task.startTime) return false;
+		this.apply(owned, task.state);
+		return true;
+	}
+
+	snapshot(): BackgroundObservation {
+		return { scope: this.scope, tasks: [...this.tasks.values()].map(task => ({ ...task })) };
+	}
+
+	/** Only explicit provider-terminal evidence removes an owned task from pending. */
+	pendingIds(): string[] {
+		return [...this.tasks.values()].filter(task => !terminal(task.state)).map(task => task.id);
+	}
+
+	refresh(): Promise<void> {
+		if (this.disposed || !this.scope || this.pendingIds().length === 0) return Promise.resolve();
+		if (this.inFlight) return this.inFlight;
+		const epoch = this.epoch;
+		const work = this.reconcile(epoch).finally(() => { if (this.epoch === epoch) this.inFlight = null; });
+		this.inFlight = work;
+		return work;
+	}
+
+	dispose(): void {
+		if (this.disposed) return;
+		this.bind(null);
+		this.disposed = true;
+		for (const stop of this.subscriptions) stop();
+		this.subscriptions.length = 0;
+	}
+
+	private validIdentity(task: ObservedBackgroundTask): boolean {
+		return typeof task.id === "string" && task.id.length > 0 && task.id.length <= 200 && task.id.trim() === task.id &&
+			Number.isSafeInteger(task.startTime) && task.startTime >= 0 &&
+			["running", "unknown", "completed", "failed", "killed"].includes(task.state);
+	}
+
+	private changed(): void {
+		// A consumer fault must never poison the provider's terminal publication.
+		try { this.onChange(this.snapshot()); } catch { /* next refresh still observes truth */ }
+	}
+
+	private apply(task: ObservedBackgroundTask, state: ObservedTaskState): void {
+		// A delayed running/status result cannot resurrect terminal work.
+		if (terminal(task.state) || task.state === state) return;
+		task.state = state;
+		this.changed();
+	}
+
+	private terminalEvent(value: unknown): void {
+		if (this.disposed || !this.scope) return;
+		const frame = record(value);
+		if (frame?.schema_version !== TERMINAL_SCHEMA) return;
+		const task = projectBackgroundTask(frame.task);
+		if (!task || !terminal(task.state)) return;
+		const owned = this.tasks.get(task.id);
+		if (owned) {
+			if (owned.startTime === task.startTime) this.apply(owned, task.state);
+			return;
+		}
+		// A fast job may finish before tool_execution_end supplies its launch
+		// receipt. Keep only bounded non-content metadata, never adopt it alone.
+		this.earlyTerminals.set(task.id, task);
+		const limit = Math.max(0, Math.min(256, this.options.earlyLimit ?? 64));
+		while (this.earlyTerminals.size > limit) this.earlyTerminals.delete(this.earlyTerminals.keys().next().value!);
+	}
+
+	private response(value: unknown): void {
+		const frame = record(value);
+		if (frame?.schema_version !== RESPONSE_SCHEMA || typeof frame.request_id !== "string") return;
+		const request = this.pending.get(frame.request_id);
+		if (!request || frame.operation !== request.operation) return;
+		request.finish(frame.ok === true ? record(frame.result) : null);
+	}
+
+	private request(operation: "capabilities" | "status", payload: Record<string, unknown>): Promise<Record<string, unknown> | null> {
+		if (this.disposed || !this.scope) return Promise.resolve(null);
+		return new Promise(resolve => {
+			const id = randomUUID();
+			const timer = setTimeout(() => finish(null), Math.max(1, Math.min(5_000, this.options.timeoutMs ?? 1_000)));
+			const finish = (value: Record<string, unknown> | null) => {
+				if (!this.pending.delete(id)) return;
+				clearTimeout(timer);
+				resolve(value);
+			};
+			this.pending.set(id, { operation, finish });
+			try {
+				this.events.emit(REQUEST, { schema_version: REQUEST_SCHEMA, request_id: id, operation, payload });
+			} catch { finish(null); }
+		});
+	}
+
+	private async reconcile(epoch: number): Promise<void> {
+		const current = () => !this.disposed && epoch === this.epoch && this.scope !== null;
+		if (!this.supported) {
+			const capabilities = await this.request("capabilities", {});
+			if (!current()) return;
+			this.supported = capabilities?.api_version === 1 && capabilities.status === true;
+			if (!this.supported) {
+				for (const task of this.tasks.values()) this.apply(task, "unknown");
+				return;
+			}
+		}
+		const all = [...this.tasks.values()].filter(task => !terminal(task.state));
+		if (!all.length) return;
+		const size = Math.max(1, Math.min(64, this.options.batchSize ?? 32));
+		const selected = Array.from({ length: Math.min(size, all.length) }, (_, i) => all[(this.offset + i) % all.length]!);
+		this.offset = (this.offset + selected.length) % all.length;
+		let next = 0;
+		const worker = async () => {
+			while (current() && next < selected.length) {
+				const task = selected[next++]!;
+				if (terminal(task.state)) continue;
+				const result = await this.request("status", { taskId: task.id });
+				if (!current() || this.tasks.get(task.id) !== task) return;
+				const values = result?.tasks;
+				const observed = Array.isArray(values) && values.length === 1 ? projectBackgroundTask(values[0]) : null;
+				this.apply(task, observed?.id === task.id && observed.startTime === task.startTime ? observed.state : "unknown");
+			}
+		};
+		await Promise.all(Array.from({ length: Math.max(1, Math.min(4, this.options.concurrency ?? 4, selected.length)) }, worker));
+	}
+}

package/extensions/core/bond-recovery.ts

@@ -0,0 +1,65 @@
+import type { RemoteConnectionIdentity } from "./remote-payload.ts";
+
+export interface PumpAuthorityIdentity {
+	generation: number;
+	connectionId: string;
+}
+
+/** Immutable authority captured before an awaited connection-scoped operation. */
+export function capturePumpAuthority(input: PumpAuthorityIdentity): PumpAuthorityIdentity {
+	return { generation: input.generation, connectionId: input.connectionId };
+}
+
+/** A delayed write may commit only while both pump generation and connection match. */
+export function isPumpAuthorityCurrent(
+	captured: PumpAuthorityIdentity,
+	current: PumpAuthorityIdentity,
+): boolean {
+	return captured.generation === current.generation && captured.connectionId === current.connectionId;
+}
+
+export interface RecoveredConnectionScopeInput {
+	currentConnectionId: string;
+	nextConnectionId: string;
+	generation: number;
+	nextGeneration: number;
+	cursor?: string;
+	dispatchCursor?: string;
+	systemNoticeCursor?: string;
+	synced: boolean;
+	agentName: string;
+	codename?: string;
+}
+
+export interface RecoveredConnectionScope {
+	changedConnection: boolean;
+	generation: number;
+	cursor?: string;
+	dispatchCursor?: string;
+	systemNoticeCursor?: string;
+	synced: boolean;
+	connectionIdentity: RemoteConnectionIdentity;
+}
+
+/**
+ * Plan the connection-scoped state transition for a recovered bond.
+ * Same-row revival preserves exactly-once clocks. A replacement row starts with
+ * fresh clocks and exact addressee identity; caller rekeys notice memory.
+ */
+export function planRecoveredConnectionScope(input: RecoveredConnectionScopeInput): RecoveredConnectionScope {
+	const changedConnection = input.currentConnectionId !== input.nextConnectionId;
+	return {
+		changedConnection,
+		generation: changedConnection ? input.nextGeneration : input.generation,
+		...(changedConnection || !input.cursor ? {} : { cursor: input.cursor }),
+		...(changedConnection || !input.dispatchCursor ? {} : { dispatchCursor: input.dispatchCursor }),
+		...(changedConnection || !input.systemNoticeCursor ? {} : { systemNoticeCursor: input.systemNoticeCursor }),
+		synced: changedConnection ? false : input.synced,
+		connectionIdentity: {
+			connection_id: input.nextConnectionId,
+			agent_name: input.agentName,
+			codename: input.codename ?? null,
+			label: input.codename ? `${input.agentName} · ${input.codename}` : input.agentName,
+		},
+	};
+}

package/extensions/core/bond-state.ts

@@ -0,0 +1,80 @@
+/**
+ * DevSpec Pi — bond state (shared across extension files).
+ *
+ * IMPORTANT: pi loads every extension file with a FRESH module graph
+ * (jiti `moduleCache: false`), so module-level state is NOT shared between
+ * extension files. Anything cross-extension must live on globalThis.
+ */
+
+export interface BondState {
+	connectionId: string;
+	/** Immutable DevSpec project bound when this connection generation registered. */
+	projectId?: string;
+	/** Display-only project name confirmed at registration. */
+	projectName?: string;
+	/** Immutable factual snapshot captured at registration, injected as a tail message. */
+	repositoryContext?: string;
+	/** Hidden server-minted capability; transport header only, never model context. */
+	connectionCapability?: string;
+	codename?: string;
+	/** Attached DevSpec session, when attached (sessionless otherwise). */
+	sessionId?: string;
+	/** Verbatim server attachment fence, not a locally reconstructed Date. */
+	attachedAt?: string;
+	/** Server-owned speech-only epoch; explicit attachment writes rotate it. */
+	speechAttachmentId?: string;
+	/** The attached session's title, learned by the attach-time context fetch. */
+	sessionTitle?: string;
+	/** One-shot room orientation digest, captured at cold-start sync. */
+	roomDigest?: string;
+	/** One-shot attach-time context block (identity + recent tail), set when the
+	 *  adopted session changes — injected once per attach, never replayed. */
+	attachContext?: string;
+	/** Instruction tiers returned by register/attach — applied while bonded. */
+	instructions?: {
+		owner_custom_instructions?: string;
+		owner_agent_rules?: string;
+		project_custom_instructions?: string;
+		project_agent_rules?: string;
+	};
+}
+
+const GLOBAL_KEY = "__devspecPiBond";
+
+interface BondStore {
+	current: BondState | null;
+}
+
+function store(): BondStore {
+	const g = globalThis as unknown as Record<string, BondStore | undefined>;
+	if (!g[GLOBAL_KEY]) g[GLOBAL_KEY] = { current: null };
+	return g[GLOBAL_KEY] as BondStore;
+}
+
+export function getBond(): BondState | null {
+	return store().current;
+}
+
+export function setBond(bond: BondState | null): void {
+	store().current = bond;
+}
+
+/** Extract the negotiated capability from MCP result metadata without touching visible content. */
+export function connectionCapabilityFromResult(raw: unknown): string | undefined {
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+	const meta = (raw as { _meta?: unknown })._meta;
+	if (!meta || typeof meta !== "object" || Array.isArray(meta)) return undefined;
+	const devspec = (meta as { devspec?: unknown }).devspec;
+	if (!devspec || typeof devspec !== "object" || Array.isArray(devspec)) return undefined;
+	const capability = (devspec as { connection_capability?: unknown }).connection_capability;
+	if (!capability || typeof capability !== "object" || Array.isArray(capability)) return undefined;
+	const row = capability as { version?: unknown; value?: unknown };
+	return row.version === 1 && typeof row.value === "string" && /^dvsc_[A-Za-z0-9_-]{20,}$/.test(row.value)
+		? row.value
+		: undefined;
+}
+
+// There is deliberately no turn-post marker here. Delivery has exactly one
+// writer — the extension's mechanical settle (item cc9e8c43) — so there is
+// nothing to suppress. The marker that lived here (857d984c) guarded a
+// dual-writer model that no longer exists.

package/extensions/core/clear-conversation.ts

@@ -0,0 +1,53 @@
+/**
+ * Clear this agent's conversation for the owner's CONTROL `clear` (item 6beb89c6).
+ *
+ * Pi's own tree navigation, back to just before the first thing the agent was told
+ * (a message, or a context message DevSpec added): the model's context is empty
+ * again, and the session is the same one, so the DevSpec connection, which is keyed
+ * by the session id, stays bonded and in its room. The old conversation stays in the session tree, reachable with /tree. A new
+ * session (/new) would replace the session id, and with it the connection.
+ *
+ * The context DevSpec adds (instructions, repository facts, room orientation) is
+ * added again on the next turn, because each is added whenever the branch lacks it.
+ *
+ * Navigating to a message puts its text back into an empty editor. That is
+ * right for /tree, where the person means to edit and resend it, and wrong here:
+ * nobody asked to resend anything, so the editor is left as it was.
+ */
+
+/** The part of a session entry this reads. */
+export interface BranchEntryLike {
+	id: string;
+	type: string;
+	message?: { role?: string };
+}
+
+/**
+ * The first thing the agent was told on this branch, or null when it has been told
+ * nothing. Entries before it (the model and thinking level the session started
+ * with) are settings, not conversation, and stay.
+ */
+export function firstConversationEntryId(branch: readonly BranchEntryLike[]): string | null {
+	return branch.find((entry) =>
+		entry.type === "custom_message" || (entry.type === "message" && entry.message?.role === "user"))?.id ?? null;
+}
+
+export interface ClearConversationHost {
+	/** The current branch, root first (`sessionManager.getBranch()`). */
+	branch(): readonly BranchEntryLike[];
+	navigateTree(targetId: string): Promise<{ cancelled: boolean }>;
+	getEditorText(): string;
+	setEditorText(text: string): void;
+}
+
+export type ClearOutcome = "cleared" | "already_clear";
+
+export async function clearConversation(host: ClearConversationHost): Promise<ClearOutcome> {
+	const target = firstConversationEntryId(host.branch());
+	if (!target) return "already_clear";
+	const editorBefore = host.getEditorText();
+	const result = await host.navigateTree(target);
+	if (result.cancelled) throw new Error("Pi cancelled clearing the conversation.");
+	if (host.getEditorText() !== editorBefore) host.setEditorText(editorBefore);
+	return "cleared";
+}

package/extensions/core/client-versions.ts

@@ -0,0 +1,56 @@
+import { readFileSync } from "node:fs";
+import { VERSION as PI_VERSION } from "@earendil-works/pi-coding-agent";
+
+const LABEL = /^[A-Za-z0-9][A-Za-z0-9._+\/-]{0,63}$/;
+export type ClientVersionReport = Readonly<{ plugin_version?: string; host_version?: string }>;
+
+/** Only our own executing package is a plugin-version source. */
+export function versionReportFromManifest(manifest: unknown, hostVersion: unknown): ClientVersionReport {
+	if (!manifest || typeof manifest !== "object") return {};
+	const value = manifest as { name?: unknown; version?: unknown };
+	if ((value.name !== "@devspecai/pi-plugin" && value.name !== "@devspec/pi-plugin") || typeof value.version !== "string" || !LABEL.test(value.version)) return {};
+	return Object.freeze({
+		plugin_version: value.version,
+		...(typeof hostVersion === "string" && LABEL.test(hostVersion) ? { host_version: hostVersion } : {}),
+	});
+}
+
+function readLoadedReport(): ClientVersionReport {
+	try {
+		return versionReportFromManifest(JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")), PI_VERSION);
+	} catch {
+		// An unreadable artifact is unknown, never the host's or cwd's package.
+		return {};
+	}
+}
+
+// Capture at module load. Reading the file on every call would make old loaded
+// code advertise a newer checkout's version after an in-place update (debdc8a7).
+export const LOADED_CLIENT_VERSIONS = readLoadedReport();
+
+/**
+ * The header every DevSpec request carries to say which plugin made it (ADR
+ * "Protecting intent" §14; decision bab58fed; server side 2295e089):
+ * `x-devspec-plugin: pi/<version>`. It identifies the plugin for the
+ * no-plugin notice, agent health and "update your plugin" messages; it is not
+ * authority, which the server always checks itself.
+ */
+export const PLUGIN_HEADER = "x-devspec-plugin";
+/** This plugin's id in that header, shared by every DevSpec plugin's `<id>/<version>` contract. */
+export const PLUGIN_ID = "pi";
+
+/**
+ * The identifying header for this loaded artifact. The version is the one the
+ * running code was loaded with, read from this package's own manifest. When it
+ * cannot be read, no version is invented: the header is left off and DevSpec
+ * treats the call as it treats any unidentified client.
+ */
+export function pluginHeaders(report: ClientVersionReport = LOADED_CLIENT_VERSIONS): Readonly<Record<string, string>> {
+	return report.plugin_version ? { [PLUGIN_HEADER]: `${PLUGIN_ID}/${report.plugin_version}` } : {};
+}
+
+export function withClientVersions(name: string, args: Record<string, unknown>, report = LOADED_CLIENT_VERSIONS): Record<string, unknown> {
+	if (name !== "register_connection" && name !== "attach_connection") return args;
+	const { plugin_version: _plugin, host_version: _host, ...rest } = args;
+	return { ...rest, ...report };
+}