@devspecai/pi-plugin 0.0.0-stage → 0.10.3

package/extensions/core/active-session-plans.ts

@@ -0,0 +1,374 @@
+import { createHash } from "node:crypto";
+
+/**
+ * Strict negotiated active-session-plan projection for canonical ingress 1.3.
+ *
+ * The server owns this schema. Pi validates the complete projection before it
+ * can affect tool activation or model context, then serializes it only at the
+ * newest delivery tail. Presence is read-awareness, never mutation authority.
+ */
+
+export const ACTIVE_PLAN_PROJECTION_VERSION = 1 as const;
+export const ACTIVE_PLAN_MAX_PLANS = 64;
+export const ACTIVE_PLAN_MAX_STEPS = 64;
+export const ACTIVE_PLAN_MAX_TITLE_CHARS = 300;
+export const ACTIVE_PLAN_MAX_FAILURE_REASON_CHARS = 4_096;
+export const ACTIVE_PLAN_MAX_IDENTITY_CHARS = 300;
+export const ACTIVE_PLAN_MAX_TOTAL_TEXT_CHARS = 131_072;
+export const ACTIVE_PLAN_AUTHORITY_NOTE =
+	"Advisory read-awareness only. Presence does not authorize execution or mutation; manage_plan still requires a capability-authenticated caller identity, explicit plan_id for cross-plan work, and expected_revision." as const;
+export const ACTIVE_PLAN_CLEAR_TOMBSTONE = [
+	"== ACTIVE SESSION PLANS ==",
+	"Authoritative current inventory: none.",
+	"Any earlier active-session-plan projection in this conversation is stale. Do not continue, complete, abandon, or adopt a plan from that stale projection.",
+].join("\n");
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const DATETIME_WITH_OFFSET_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+
+export type ActivePlanStepStatus = "pending" | "in_progress" | "completed" | "failed" | "skipped";
+
+export interface ActivePlanAgentIdentity {
+	kind: "dev" | "connection";
+	connection_id: string | null;
+	agent_name: string;
+	codename: string | null;
+}
+
+export interface ActiveSessionPlanStep {
+	id: string;
+	position: number;
+	title: string;
+	status: ActivePlanStepStatus;
+	failure_reason?: string;
+	retryable?: boolean;
+}
+
+export interface ActiveSessionPlan {
+	id: string;
+	title: string;
+	revision: number;
+	status: "active";
+	created_at: string;
+	origin: ActivePlanAgentIdentity;
+	steward: ActivePlanAgentIdentity;
+	owner: { user_id: string; display_name: string };
+	orphaned: boolean;
+	progress: { terminal: number; total: number; completed: number; skipped: number };
+	steps: ActiveSessionPlanStep[];
+}
+
+export interface ActiveSessionPlansProjection {
+	version: typeof ACTIVE_PLAN_PROJECTION_VERSION;
+	advisory: true;
+	authority_note: typeof ACTIVE_PLAN_AUTHORITY_NOTE;
+	inventory: { returned: number; total_known: number; truncated: false };
+	plans: ActiveSessionPlan[];
+}
+
+interface ActivePlanAwarenessStore {
+	/** Pi local session id → SHA-256 of the last actually injected active projection. */
+	injectedByLocalSession: Map<string, string>;
+}
+
+const AWARENESS_STORE_KEY = Symbol.for("devspec.pi.active-plan-awareness.v1");
+const MAX_AWARENESS_SESSIONS = 100;
+
+function awarenessStore(): ActivePlanAwarenessStore {
+	const root = globalThis as typeof globalThis & { [AWARENESS_STORE_KEY]?: ActivePlanAwarenessStore };
+	const current = root[AWARENESS_STORE_KEY];
+	if (!current || !(current.injectedByLocalSession instanceof Map)) {
+		root[AWARENESS_STORE_KEY] = { injectedByLocalSession: new Map() };
+	}
+	return root[AWARENESS_STORE_KEY]!;
+}
+
+function exactAwarenessKey(value: string): string | null {
+	return value && value === value.trim() ? value : null;
+}
+
+/** Persist only a digest proving active-plan awareness reached this transcript. */
+export function markActivePlanAwareness(localSessionId: string, activeTail: string): string | null {
+	const key = exactAwarenessKey(localSessionId);
+	if (!key || !activeTail || activeTail === ACTIVE_PLAN_CLEAR_TOMBSTONE) return null;
+	const digest = createHash("sha256").update(activeTail, "utf8").digest("hex");
+	const store = awarenessStore().injectedByLocalSession;
+	store.delete(key);
+	store.set(key, digest);
+	while (store.size > MAX_AWARENESS_SESSIONS) {
+		const oldest = store.keys().next().value;
+		if (typeof oldest !== "string") break;
+		store.delete(oldest);
+	}
+	return digest;
+}
+
+export function activePlanAwarenessHash(localSessionId: string): string | null {
+	const key = exactAwarenessKey(localSessionId);
+	return key ? awarenessStore().injectedByLocalSession.get(key) ?? null : null;
+}
+
+/** Clear only after the authoritative no-plan tombstone was actually injected. */
+export function clearActivePlanAwareness(localSessionId: string): boolean {
+	const key = exactAwarenessKey(localSessionId);
+	return key ? awarenessStore().injectedByLocalSession.delete(key) : false;
+}
+
+export function resetActivePlanAwarenessForTests(): void {
+	awarenessStore().injectedByLocalSession.clear();
+}
+
+type Row = Record<string, unknown>;
+
+function fail(path: string, message: string): never {
+	throw new Error(`${path}: ${message}`);
+}
+
+function record(value: unknown, path: string): Row {
+	if (!value || typeof value !== "object" || Array.isArray(value)) fail(path, "expected object");
+	return value as Row;
+}
+
+function exactKeys(value: Row, keys: readonly string[], path: string): void {
+	const actual = Object.keys(value).sort();
+	const expected = [...keys].sort();
+	if (actual.length !== expected.length || actual.some((key, index) => key !== expected[index])) {
+		fail(path, `expected exactly ${expected.join(", ")}`);
+	}
+}
+
+function boundedString(value: unknown, path: string, max: number): string {
+	if (typeof value !== "string" || value.length === 0 || value.length > max) {
+		fail(path, `expected non-empty string <= ${max} characters`);
+	}
+	return value;
+}
+
+function uuid(value: unknown, path: string): string {
+	const parsed = boundedString(value, path, 64);
+	if (!UUID_RE.test(parsed)) fail(path, "expected UUID");
+	return parsed;
+}
+
+function datetime(value: unknown, path: string): string {
+	const parsed = boundedString(value, path, 64);
+	if (!DATETIME_WITH_OFFSET_RE.test(parsed) || Number.isNaN(Date.parse(parsed))) fail(path, "expected offset datetime");
+	return parsed;
+}
+
+function integer(value: unknown, path: string, minimum = 0, maximum = Number.MAX_SAFE_INTEGER): number {
+	if (typeof value !== "number" || !Number.isSafeInteger(value) || value < minimum || value > maximum) {
+		fail(path, `expected integer ${minimum}..${maximum}`);
+	}
+	return value;
+}
+
+function boolean(value: unknown, path: string): boolean {
+	if (typeof value !== "boolean") fail(path, "expected boolean");
+	return value;
+}
+
+function identity(value: unknown, path: string): ActivePlanAgentIdentity {
+	const row = record(value, path);
+	exactKeys(row, ["kind", "connection_id", "agent_name", "codename"], path);
+	if (row.kind !== "dev" && row.kind !== "connection") fail(`${path}.kind`, "expected dev | connection");
+	const connectionId = row.connection_id === null ? null : uuid(row.connection_id, `${path}.connection_id`);
+	if ((row.kind === "dev") !== (connectionId === null)) fail(`${path}.connection_id`, "identity kind contradicts connection id");
+	return {
+		kind: row.kind,
+		connection_id: connectionId,
+		agent_name: boundedString(row.agent_name, `${path}.agent_name`, ACTIVE_PLAN_MAX_IDENTITY_CHARS),
+		codename: row.codename === null ? null : boundedString(row.codename, `${path}.codename`, ACTIVE_PLAN_MAX_IDENTITY_CHARS),
+	};
+}
+
+function step(value: unknown, path: string): ActiveSessionPlanStep {
+	const row = record(value, path);
+	const status = row.status;
+	if (!["pending", "in_progress", "completed", "failed", "skipped"].includes(String(status))) {
+		fail(`${path}.status`, "unknown step status");
+	}
+	const failed = status === "failed";
+	exactKeys(
+		row,
+		failed
+			? row.failure_reason === undefined
+				? ["id", "position", "title", "status", "retryable"]
+				: ["id", "position", "title", "status", "failure_reason", "retryable"]
+			: ["id", "position", "title", "status"],
+		path,
+	);
+	return {
+		id: uuid(row.id, `${path}.id`),
+		position: integer(row.position, `${path}.position`, Number.MIN_SAFE_INTEGER),
+		title: boundedString(row.title, `${path}.title`, ACTIVE_PLAN_MAX_TITLE_CHARS),
+		status: status as ActivePlanStepStatus,
+		...(failed ? {
+			...(row.failure_reason === undefined ? {} : {
+				failure_reason: boundedString(row.failure_reason, `${path}.failure_reason`, ACTIVE_PLAN_MAX_FAILURE_REASON_CHARS),
+			}),
+			retryable: boolean(row.retryable, `${path}.retryable`),
+		} : {}),
+	};
+}
+
+function plan(value: unknown, path: string): ActiveSessionPlan {
+	const row = record(value, path);
+	exactKeys(row, ["id", "title", "revision", "status", "created_at", "origin", "steward", "owner", "orphaned", "progress", "steps"], path);
+	if (row.status !== "active") fail(`${path}.status`, "expected active");
+	const owner = record(row.owner, `${path}.owner`);
+	exactKeys(owner, ["user_id", "display_name"], `${path}.owner`);
+	const progress = record(row.progress, `${path}.progress`);
+	exactKeys(progress, ["terminal", "total", "completed", "skipped"], `${path}.progress`);
+	if (!Array.isArray(row.steps) || row.steps.length > ACTIVE_PLAN_MAX_STEPS) fail(`${path}.steps`, `expected at most ${ACTIVE_PLAN_MAX_STEPS} steps`);
+	const steps = row.steps.map((value, index) => step(value, `${path}.steps[${index}]`));
+	const parsedProgress = {
+		terminal: integer(progress.terminal, `${path}.progress.terminal`),
+		total: integer(progress.total, `${path}.progress.total`),
+		completed: integer(progress.completed, `${path}.progress.completed`),
+		skipped: integer(progress.skipped, `${path}.progress.skipped`),
+	};
+	const completed = steps.filter((item) => item.status === "completed").length;
+	const skipped = steps.filter((item) => item.status === "skipped").length;
+	if (parsedProgress.total !== steps.length || parsedProgress.completed !== completed ||
+		parsedProgress.skipped !== skipped || parsedProgress.terminal !== completed + skipped) {
+		fail(`${path}.progress`, "progress does not match canonical steps");
+	}
+	return {
+		id: uuid(row.id, `${path}.id`),
+		title: boundedString(row.title, `${path}.title`, ACTIVE_PLAN_MAX_TITLE_CHARS),
+		revision: integer(row.revision, `${path}.revision`, 1),
+		status: "active",
+		created_at: datetime(row.created_at, `${path}.created_at`),
+		origin: identity(row.origin, `${path}.origin`),
+		steward: identity(row.steward, `${path}.steward`),
+		owner: {
+			user_id: uuid(owner.user_id, `${path}.owner.user_id`),
+			display_name: boundedString(owner.display_name, `${path}.owner.display_name`, ACTIVE_PLAN_MAX_IDENTITY_CHARS),
+		},
+		orphaned: boolean(row.orphaned, `${path}.orphaned`),
+		progress: parsedProgress,
+		steps,
+	};
+}
+
+/** Parse the complete strict v1 inventory or throw without producing a partial projection. */
+export function parseActiveSessionPlansProjection(value: unknown, path = "ingress.active_session_plans"): ActiveSessionPlansProjection {
+	const row = record(value, path);
+	exactKeys(row, ["version", "advisory", "authority_note", "inventory", "plans"], path);
+	if (row.version !== ACTIVE_PLAN_PROJECTION_VERSION) fail(`${path}.version`, "unknown projection version");
+	if (row.advisory !== true) fail(`${path}.advisory`, "projection must be advisory");
+	if (row.authority_note !== ACTIVE_PLAN_AUTHORITY_NOTE) fail(`${path}.authority_note`, "unknown authority note");
+	const inventory = record(row.inventory, `${path}.inventory`);
+	exactKeys(inventory, ["returned", "total_known", "truncated"], `${path}.inventory`);
+	if (inventory.truncated !== false) fail(`${path}.inventory.truncated`, "complete projection cannot be truncated");
+	if (!Array.isArray(row.plans) || row.plans.length < 1 || row.plans.length > ACTIVE_PLAN_MAX_PLANS) {
+		fail(`${path}.plans`, `expected 1..${ACTIVE_PLAN_MAX_PLANS} plans`);
+	}
+	const plans = row.plans.map((value, index) => plan(value, `${path}.plans[${index}]`));
+	const returned = integer(inventory.returned, `${path}.inventory.returned`, 1, ACTIVE_PLAN_MAX_PLANS);
+	const totalKnown = integer(inventory.total_known, `${path}.inventory.total_known`, 1, ACTIVE_PLAN_MAX_PLANS);
+	if (returned !== plans.length || totalKnown !== plans.length) fail(`${path}.inventory`, "inventory metadata must describe the complete plans array");
+	const totalTextChars = plans.reduce((total, item) => total + item.title.length +
+		item.origin.agent_name.length + (item.origin.codename?.length ?? 0) +
+		item.steward.agent_name.length + (item.steward.codename?.length ?? 0) +
+		item.owner.display_name.length + item.steps.reduce((sum, entry) => sum + entry.title.length + (entry.failure_reason?.length ?? 0), 0), 0);
+	if (totalTextChars > ACTIVE_PLAN_MAX_TOTAL_TEXT_CHARS) fail(`${path}.plans`, "active plan projection text exceeds safe bound");
+	return {
+		version: ACTIVE_PLAN_PROJECTION_VERSION,
+		advisory: true,
+		authority_note: ACTIVE_PLAN_AUTHORITY_NOTE,
+		inventory: { returned, total_known: totalKnown, truncated: false },
+		plans,
+	};
+}
+
+const STEP_MARK: Record<ActivePlanStepStatus, string> = {
+	pending: "[ ]",
+	in_progress: "[>]",
+	completed: "[x]",
+	failed: "[!]",
+	skipped: "[-]",
+};
+
+function agentLabel(value: ActivePlanAgentIdentity): string {
+	return value.kind === "dev"
+		? "Dev"
+		: `${value.agent_name}${value.codename ? ` · ${value.codename}` : ""} (${value.connection_id})`;
+}
+
+/** Compact deterministic delivery-tail serialization. Other agents' plans remain read-only. */
+export function serializeActiveSessionPlansProjection(
+	projection: ActiveSessionPlansProjection | null,
+	connectionId: string,
+): string {
+	if (!projection) return "";
+	const lines = ["== ACTIVE SESSION PLANS ==", projection.authority_note];
+	for (const [index, item] of projection.plans.entries()) {
+		const own = item.steward.connection_id === connectionId;
+		lines.push(
+			"",
+			`${index + 1}. ${own ? "[OWN] " : "[ROOM · READ-ONLY] "}\"${item.title}\" | plan_id=${item.id} | revision=${item.revision} | active | steward=${agentLabel(item.steward)} | origin=${agentLabel(item.origin)} | owner=${item.owner.display_name} (${item.owner.user_id}) | orphaned=${item.orphaned} | progress=${item.progress.terminal}/${item.progress.total}`,
+		);
+		for (const entry of item.steps) {
+			lines.push(`   ${STEP_MARK[entry.status]} ${entry.position}. ${entry.title} | step_id=${entry.id} | status=${entry.status}${entry.status === "failed" ? ` | retryable=${entry.retryable} | failure=${JSON.stringify(entry.failure_reason)}` : ""}`);
+		}
+		if (!own) continue;
+		const allTerminal = item.progress.total > 0 && item.progress.terminal === item.progress.total;
+		const inProgress = item.steps.find((entry) => entry.status === "in_progress");
+		lines.push(
+			`   Own-plan guidance: first decide whether to complete, continue, hand off for adoption where supported, or abandon this plan; never silently drop, restart, or infer mutation authority from this projection. Every manage_plan mutation must use plan_id=${item.id} and expected_revision=${item.revision}.`,
+			allTerminal
+				? "   All steps are terminal: complete only if the outcome was achieved; otherwise abandon with a specific reason."
+				: inProgress
+					? `   To continue, resume the in_progress step step_id=${inProgress.id} before starting any pending step. If the user pivoted, abandon with a specific reason; if unsure, ask before another tool action.`
+					: "   To continue, start the next pending step before acting. If the user pivoted, abandon with a specific reason; if another supported connection should continue, leave the plan for explicit adoption; if unsure, ask before another tool action.",
+		);
+		const failed = item.steps.filter((entry) => entry.status === "failed");
+		if (failed.some((entry) => entry.retryable)) lines.push("   Failed-step guidance: a retryable failed step may be restarted once; if it fails again, stop and ask rather than looping.");
+		if (failed.some((entry) => !entry.retryable)) lines.push("   Failed-step guidance: do not retry a non-retryable failed step; explain it and ask whether to skip, amend, or abandon.");
+	}
+	return lines.join("\n");
+}
+
+/**
+ * Calculate the one-shot tail for an authoritative inventory transition.
+ * Never-had-plan → none stays silent; active → none emits one clearing tombstone.
+ */
+export function activePlanTransitionTail(previousCurrentTail: string, nextCurrentTail: string): string {
+	if (previousCurrentTail === nextCurrentTail) return "";
+	if (previousCurrentTail && !nextCurrentTail) return ACTIVE_PLAN_CLEAR_TOMBSTONE;
+	return nextCurrentTail;
+}
+
+/**
+ * Authoritative transition across pump replacement/reload/rebond. A fresh pump
+ * has no plan content, so only the global injected hash can prove that a no-plan
+ * tombstone is needed. The hash is not cleared until delivery.
+ */
+export function authoritativeActivePlanTransitionTail(
+	localSessionId: string,
+	previousCurrentTail: string,
+	nextCurrentTail: string,
+): string {
+	const localTransition = activePlanTransitionTail(previousCurrentTail, nextCurrentTail);
+	if (localTransition) return localTransition;
+	return !nextCurrentTail && activePlanAwarenessHash(localSessionId)
+		? ACTIVE_PLAN_CLEAR_TOMBSTONE
+		: "";
+}
+
+/** A canonical queued turn uses the newest state; a local turn consumes pending change only. */
+export function activePlanTailForDelivery(
+	hasCanonicalOwnerTurn: boolean,
+	currentTail: string,
+	pendingTail: string,
+): string {
+	return hasCanonicalOwnerTurn ? currentTail || pendingTail : pendingTail;
+}
+
+/** Append only at the current delivery tail; never splice stable/history bytes. */
+export function appendActivePlanTail(prefix: string, tail: string): string {
+	if (!tail) return prefix;
+	return prefix ? `${prefix}\n\n${tail}` : tail;
+}

package/extensions/core/adapter-overlap.ts

@@ -0,0 +1,247 @@
+/**
+ * DevSpec Pi — detect and persist-disable an adapter-mounted DevSpec MCP
+ * server (item d2f4f25c).
+ *
+ * Native tools already speak /api/mcp. If pi-mcp-adapter also loads a
+ * `devspec` entry from project `.mcp.json`, the model pays the catalog
+ * twice and sees pump/delivery verbs we hid. Foreign servers (Supabase,
+ * browsers) are left alone. The shared `.mcp.json` is never rewritten —
+ * other hosts in the same checkout still need it.
+ *
+ * Pure helpers, unit-tested. Persistence writes only `{ disabled: true }`
+ * into the Pi-local adapter overlay (`.pi/mcp-adapter.json`).
+ */
+
+import {
+	DEFAULT_MCP_URL,
+	STAGING_MCP_URL,
+	mcpUrl,
+} from "./config.ts";
+import {
+	MODEL_VERB_NAMES,
+	NEVER_MODEL_VERBS,
+	PUMP_VERBS,
+} from "../generated/mcp-catalog.ts";
+
+export const ALL_DEVSPEC_VERBS: readonly string[] = [
+	...MODEL_VERB_NAMES,
+	...PUMP_VERBS,
+	...NEVER_MODEL_VERBS,
+];
+
+const VERB_SET = new Set<string>(ALL_DEVSPEC_VERBS);
+
+/** Prefix modes pi-mcp-adapter uses when registering direct tools. */
+export const ADAPTER_PREFIX_MODES = ["server", "none", "short", "mcp"] as const;
+export type AdapterPrefixMode = (typeof ADAPTER_PREFIX_MODES)[number];
+
+export interface McpServerEntry {
+	url?: unknown;
+	disabled?: unknown;
+	[key: string]: unknown;
+}
+
+export interface McpConfigFile {
+	mcpServers?: Record<string, McpServerEntry>;
+	"mcp-servers"?: Record<string, McpServerEntry>;
+}
+
+export interface DevspecServerHit {
+	name: string;
+	/** Absolute path of the config file that declared it (not the overlay). */
+	source: string;
+	url: string;
+	alreadyDisabled: boolean;
+}
+
+export interface AdapterGuardState {
+	/** Servers we decided to hide this process. */
+	suppressed: DevspecServerHit[];
+	/** Whether the Pi-owned duplicate settings were prepared successfully. */
+	persisted: boolean;
+	/** Overlay path we wrote / would write. */
+	overlayPath: string | null;
+}
+
+const GUARD_KEY = "__devspecPiAdapterGuard";
+
+function guardStore(): AdapterGuardState {
+	const g = globalThis as unknown as Record<string, AdapterGuardState | undefined>;
+	if (!g[GUARD_KEY]) {
+		g[GUARD_KEY] = { suppressed: [], persisted: false, overlayPath: null };
+	}
+	return g[GUARD_KEY] as AdapterGuardState;
+}
+
+export function getAdapterGuardState(): AdapterGuardState {
+	return guardStore();
+}
+
+/** Test hook — do not call from production code. */
+export function resetAdapterGuardState(): void {
+	const g = globalThis as unknown as Record<string, AdapterGuardState | undefined>;
+	g[GUARD_KEY] = { suppressed: [], persisted: false, overlayPath: null };
+}
+
+export function recordAdapterGuard(next: Partial<AdapterGuardState>): AdapterGuardState {
+	const cur = guardStore();
+	if (next.suppressed) cur.suppressed = next.suppressed;
+	if (next.persisted !== undefined) cur.persisted = next.persisted;
+	if (next.overlayPath !== undefined) cur.overlayPath = next.overlayPath;
+	return cur;
+}
+
+/**
+ * Apex domains DevSpec deploys under: production (`api.devspec.ai`) and
+ * staging (`api.devspecstaging.com`). Matching the apex and any subdomain also
+ * keeps recognising the retiring `staging.devspec.ai`, which a checkout's
+ * `.mcp.json` may still name — that entry is exactly what this guard disables.
+ */
+const DEVSPEC_APEX_DOMAINS: readonly string[] = ["devspec.ai", "devspecstaging.com"];
+
+/** Hostname is DevSpec's own MCP (prod, staging, or any deploy under either apex). */
+export function isDevspecMcpHost(hostname: string): boolean {
+	const host = hostname.trim().toLowerCase();
+	return DEVSPEC_APEX_DOMAINS.some((apex) => host === apex || host.endsWith(`.${apex}`));
+}
+
+/**
+ * A configured MCP url is DevSpec's own verb surface — not a foreign server.
+ * Matches prod/staging hostnames, or whatever endpoint THIS package is
+ * currently speaking (DEVSPEC_MCP_URL / DEVSPEC_ENV).
+ */
+export function isDevspecMcpUrl(url: unknown, effectiveEndpoint: string = mcpUrl()): boolean {
+	if (typeof url !== "string" || !url.trim()) return false;
+	let parsed: URL;
+	try {
+		parsed = new URL(url.trim());
+	} catch {
+		return false;
+	}
+	if (isDevspecMcpHost(parsed.hostname)) return true;
+	return normalizeEndpoint(url) === normalizeEndpoint(effectiveEndpoint);
+}
+
+export function normalizeEndpoint(url: string): string {
+	try {
+		const u = new URL(url.trim());
+		u.hash = "";
+		u.search = "";
+		let path = u.pathname.replace(/\/+$/, "");
+		if (!path) path = "";
+		return `${u.protocol}//${u.host.toLowerCase()}${path}`;
+	} catch {
+		return url.trim().replace(/\/+$/, "").toLowerCase();
+	}
+}
+
+export function serversFromConfig(raw: unknown): Record<string, McpServerEntry> {
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
+	const obj = raw as McpConfigFile;
+	const block = obj.mcpServers ?? obj["mcp-servers"];
+	if (!block || typeof block !== "object" || Array.isArray(block)) return {};
+	return block;
+}
+
+export function parseConfigJson(text: string): unknown {
+	return JSON.parse(text) as unknown;
+}
+
+/** Known DevSpec endpoints this package might be talking to. */
+export function knownDevspecEndpoints(): string[] {
+	return [mcpUrl(), DEFAULT_MCP_URL, STAGING_MCP_URL];
+}
+
+export function findDevspecServers(
+	servers: Record<string, McpServerEntry>,
+	source: string,
+	effectiveEndpoint: string = mcpUrl(),
+): DevspecServerHit[] {
+	const hits: DevspecServerHit[] = [];
+	for (const [name, entry] of Object.entries(servers)) {
+		if (!entry || typeof entry !== "object") continue;
+		if (typeof entry.url !== "string") continue;
+		if (!isDevspecMcpUrl(entry.url, effectiveEndpoint)) continue;
+		hits.push({
+			name,
+			source,
+			url: entry.url,
+			alreadyDisabled: entry.disabled === true,
+		});
+	}
+	return hits;
+}
+
+export function adapterPrefix(serverName: string, mode: AdapterPrefixMode): string {
+	if (mode === "none") return "";
+	if (mode === "short") {
+		const short = serverName.replace(/-?mcp$/i, "").replace(/-/g, "_");
+		return short || "mcp";
+	}
+	if (mode === "mcp") return `mcp__${serverName.replace(/-/g, "_")}`;
+	return serverName.replace(/-/g, "_");
+}
+
+export function adapterToolName(verb: string, serverName: string, mode: AdapterPrefixMode): string {
+	const p = adapterPrefix(serverName, mode);
+	const sanitized = verb.replace(/\./g, "_");
+	return p ? `${p}_${sanitized}` : sanitized;
+}
+
+/** Every name the adapter might have registered for this server. */
+export function adapterToolNamesFor(serverName: string): string[] {
+	const names = new Set<string>();
+	for (const mode of ADAPTER_PREFIX_MODES) {
+		for (const verb of ALL_DEVSPEC_VERBS) {
+			names.add(adapterToolName(verb, serverName, mode));
+		}
+	}
+	return [...names];
+}
+
+export function isDevspecVerb(name: string): boolean {
+	return VERB_SET.has(name);
+}
+
+/**
+ * Tools we may deactivate THIS session. Prefixed adapter names are always
+ * safe. Bare catalog names are only safe when `sourceInfo` says they came
+ * from the adapter — otherwise they are our native registrations.
+ */
+export function toolsToDeactivate(
+	registered: Array<{ name: string; sourceInfo?: { source?: string; path?: string } }>,
+	serverNames: string[],
+): string[] {
+	const prefixed = new Set<string>();
+	for (const server of serverNames) {
+		for (const n of adapterToolNamesFor(server)) prefixed.add(n);
+	}
+	const out: string[] = [];
+	for (const tool of registered) {
+		const namespaceMatch = serverNames.some((server) => {
+			const namespace = `mcp__${server.replace(/[^a-zA-Z0-9_]/g, "_")}`;
+			return tool.name === namespace || tool.name.startsWith(`${namespace}__`);
+		});
+		if ((namespaceMatch || prefixed.has(tool.name)) && !isDevspecVerb(tool.name)) {
+			out.push(tool.name);
+			continue;
+		}
+		if (isDevspecVerb(tool.name) && isAdapterSource(tool.sourceInfo)) {
+			out.push(tool.name);
+		}
+	}
+	return out;
+}
+
+export function isAdapterSource(sourceInfo: { source?: string; path?: string } | undefined): boolean {
+	if (!sourceInfo) return false;
+	const blob = `${sourceInfo.source ?? ""} ${sourceInfo.path ?? ""}`.toLowerCase();
+	return blob.includes("pi-mcp-adapter") || blob.includes("mcp-adapter");
+}
+
+export const SUPPRESSION_NOTICE =
+	"DevSpec MCP is disabled in Pi to avoid duplicate tools. This plugin provides DevSpec instead. Other agents’ settings and your other MCP servers are unchanged.";
+
+/** Authored guidance, never interpolated config names, paths or credentials. */
+export const SUPPRESSION_AGENT_GUIDANCE =
+	"The DevSpec Pi plugin replaces a separately configured DevSpec MCP server. Its duplicate protection can mark that server disabled in Pi; this is expected, not a sign-in or connection failure. Explain this only if asked, and do not re-enable the duplicate or delete shared MCP configuration to fix it. Do not announce this proactively. The plugin's override is Pi-only: it does not change shared configuration, Claude Code settings or foreign MCP servers. Use the native DevSpec tools. Suppression does not prove that those tools are signed in or healthy: if they fail, diagnose the plugin connection with /devspec.status and /devspec.login separately.";

package/extensions/core/assistant-speech.ts

@@ -0,0 +1,44 @@
+import { randomUUID } from "node:crypto";
+import { extractAssistantParts } from "./trail.ts";
+
+/** Emptiness predicate only; the delivered string is never normalized. */
+export function hasAssistantSpeech(text: string): boolean {
+	return text.replace(/[\s\p{Cf}\p{Default_Ignorable_Code_Point}]/gu, "").length > 0;
+}
+
+export interface AssistantSpeechRecord {
+	readonly assistantSourceId: string;
+	readonly text: string;
+}
+
+/** Created before provider work; one finalization, one stable retry identity. */
+export class AssistantSpeechSource {
+	readonly assistantSourceId = randomUUID();
+	private text: string | undefined;
+	private record: AssistantSpeechRecord | null = null;
+	finalize(message: unknown): AssistantSpeechRecord | null {
+		if (!message || typeof message !== "object" || !("role" in message) || message.role !== "assistant") return null;
+		const { text } = extractAssistantParts(message);
+		if (this.text !== undefined) {
+			if (this.text !== text) throw new Error("Assistant speech source text conflict.");
+			return this.record;
+		}
+		this.text = text;
+		if (hasAssistantSpeech(text)) this.record = Object.freeze({ assistantSourceId: this.assistantSourceId, text });
+		return this.record;
+	}
+}
+
+export function assistantSpeechWithinBudget(text: string): boolean {
+	return [...text].length <= 100_000 && Buffer.byteLength(JSON.stringify(text), "utf8") <= 512_000;
+}
+
+/** Serial source delivery only; errors do not poison later independent speech. */
+export class AssistantSpeechQueue {
+	private tail: Promise<void> = Promise.resolve();
+	enqueue(post: () => Promise<void>): Promise<void> {
+		const next = this.tail.then(post);
+		this.tail = next.catch(() => undefined);
+		return next;
+	}
+}

package/extensions/core/attach-context.ts

@@ -0,0 +1,25 @@
+/**
+ * DevSpec Pi — the bonded session's display identity (item 9dcbd157).
+ *
+ * After an attach, Pi reads the room's transcript only to learn its title for
+ * the status line. Conversational and model context arrive exclusively through
+ * negotiated canonical ingress; the transcript never becomes model context here.
+ * (The attach-time tail and agenda block this module used to build had no caller
+ * left and clipped what it showed, so it was removed: DevSpec item 5a9eaa57.)
+ */
+
+import { isRealSessionTitle } from "./status-line.ts";
+
+export interface SessionIdentity {
+	sessionId: string;
+	title: string | null;
+}
+
+/** The session's real title, or null for a brand-new room whose title is not generated yet. */
+export function shapeTranscript(sessionId: string, raw: unknown): SessionIdentity {
+	const t = (raw ?? {}) as { title?: unknown };
+	return {
+		sessionId,
+		title: isRealSessionTitle(t.title) ? t.title.trim() : null,
+	};
+}