@devspecai/pi-plugin 0.0.0-stage → 0.10.3

package/extensions/core/json-schema.ts

@@ -0,0 +1,16 @@
+/**
+ * Wrap a server JSON Schema as a TypeBox TSchema.
+ *
+ * The catalog is generated from DevSpec's own MCP tool-definitions. Re-encoding
+ * every property into Type.Object / StringEnum by hand is how this rots
+ * (item 523f1512). Type.Unsafe keeps the server schema byte-faithful.
+ */
+
+import { Type, type TSchema } from "typebox";
+
+export function jsonSchemaToTypebox(schema: Record<string, unknown> | undefined): TSchema {
+	if (!schema || typeof schema !== "object") {
+		return Type.Object({});
+	}
+	return Type.Unsafe(schema);
+}

package/extensions/core/local-activity.ts

@@ -0,0 +1,34 @@
+/** Exact local admission uses existing attempt IDs, never speech or latest-at-completion. */
+export interface LocalActivityScope {
+	connection_id: string;
+	expected_session_id: string;
+	expected_attachment_id: string;
+	expected_attached_at: string;
+}
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export async function startLocalActivity(input: {
+	scope: LocalActivityScope;
+	attemptId: string;
+	previousAttemptId: string | null;
+	current: () => boolean;
+	request: (args: Record<string, unknown>) => Promise<unknown>;
+}): Promise<string | null> {
+	const { scope, attemptId, current, request } = input;
+	let previous = input.previousAttemptId;
+	try {
+		for (let retry = 0; retry < 2; retry++) {
+			if (!current()) return null;
+			const raw = await request({ ...scope, local_activity_version: 1, local_turn: true,
+				attempt_id: attemptId, previous_attempt_id: previous });
+			if (!current() || !raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+			const result = raw as Record<string, unknown>;
+			if (result.connection_id !== scope.connection_id || result.attempt_id !== attemptId ||
+				result.expected_session_id !== scope.expected_session_id || result.expected_attachment_id !== scope.expected_attachment_id ||
+				typeof result.expected_attached_at !== "string" || Date.parse(result.expected_attached_at) !== Date.parse(scope.expected_attached_at)) return null;
+			if (result.status === "working" && typeof result.already_started === "boolean") return attemptId;
+			if (result.status !== "predecessor_changed" || typeof result.previous_attempt_id !== "string" || !uuid.test(result.previous_attempt_id)) return null;
+			previous = result.previous_attempt_id;
+		}
+	} catch { /* Unknown admission never becomes a completion identity. */ }
+	return null;
+}

package/extensions/core/mcp-config-guard.ts

@@ -0,0 +1,117 @@
+/** Pi 1.x configuration ownership (9021dd85). No shared/other-host files are written. */
+import { readFileSync, writeFileSync, mkdirSync, renameSync, unlinkSync, lstatSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
+import { findDevspecServers, type DevspecServerHit } from "./adapter-overlap.ts";
+
+type ObjectMap = Record<string, unknown>;
+export interface ConfigSnapshot { path: string; text: string | null; value: ObjectMap }
+function object(value: unknown): value is ObjectMap {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+export function readConfig(path: string): ConfigSnapshot {
+	let text: string;
+	try { text = readFileSync(path, "utf8"); }
+	catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return { path, text: null, value: {} }; throw error; }
+	const value: unknown = JSON.parse(text);
+	if (!object(value) || (value.mcpServers !== undefined && !object(value.mcpServers))) throw new Error("Invalid MCP config shape");
+	return { path, text, value };
+}
+function unchanged(snapshot: ConfigSnapshot): void {
+	if (readConfig(snapshot.path).text !== snapshot.text) throw new Error("MCP configuration changed concurrently");
+	// Do not follow a symlink into a shared configuration or another host's settings.
+	try { if (lstatSync(snapshot.path).isSymbolicLink()) throw new Error("MCP configuration is a symlink; review it manually"); }
+	catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+}
+export function saveConfig(snapshot: ConfigSnapshot, value: ObjectMap): boolean {
+	if (isDeepStrictEqual(snapshot.value, value)) return false;
+	unchanged(snapshot);
+	mkdirSync(dirname(snapshot.path), { recursive: true });
+	const temp = `${snapshot.path}.${randomUUID()}.tmp`;
+	try {
+		writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+		unchanged(snapshot);
+		renameSync(temp, snapshot.path);
+	} finally { try { unlinkSync(temp); } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; } }
+	return true;
+}
+
+/** Move only recognized legacy overlay entries. Full native entries are never migrated. */
+export function migrateLegacyOverlay(nativePath: string, adapterPath: string): boolean {
+	const source = readConfig(nativePath);
+	const servers = (source.value.mcpServers ?? {}) as ObjectMap;
+	const legacy = Object.entries(servers).filter(([, entry]) => object(entry)
+		&& Object.keys(entry).length > 0
+		&& Object.keys(entry).every((key) => key === "disabled" || key === "protocolVersion")
+		&& (entry.disabled === undefined || typeof entry.disabled === "boolean")
+		&& (entry.protocolVersion === undefined || typeof entry.protocolVersion === "string"));
+	if (legacy.length === 0) return false;
+	const destination = readConfig(adapterPath);
+	const nextServers: ObjectMap = Object.assign(Object.create(null), destination.value.mcpServers ?? {});
+	for (const [name, entry] of legacy) {
+		const existing = nextServers[name];
+		if (existing !== undefined && !object(existing)) throw new Error("Invalid adapter override");
+		for (const [key, value] of Object.entries(entry as ObjectMap)) {
+			if (object(existing) && key in existing && !isDeepStrictEqual(existing[key], value)) throw new Error("Conflicting MCP overrides; review manually");
+		}
+		nextServers[name] = { ...(existing as ObjectMap ?? {}), ...(entry as ObjectMap) };
+	}
+	// Both files are validated before either changes. Save destination first: interruption
+	// may leave a retryable duplicate, never delete the only copy of a user's setting.
+	unchanged(source);
+	unchanged(destination);
+	writeFileSync(`${nativePath}.devspec-backup-${randomUUID()}`, source.text!, { flag: "wx", mode: 0o600 });
+	saveConfig(destination, { ...destination.value, mcpServers: nextServers });
+	const remaining = { ...servers };
+	for (const [name] of legacy) delete remaining[name];
+	saveConfig(source, { ...source.value, mcpServers: remaining });
+	return true;
+}
+
+export function disableNativeDuplicates(path: string, endpoint: string, effectiveNames?: Set<string>): { hits: DevspecServerHit[]; changed: boolean } {
+	const source = readConfig(path);
+	const servers = (source.value.mcpServers ?? {}) as Record<string, { url?: unknown; enabled?: unknown }>;
+	const hits = findDevspecServers(servers, path, endpoint).filter((hit) => !effectiveNames || effectiveNames.has(hit.name)).map((hit) => ({ ...hit, alreadyDisabled: servers[hit.name].enabled === false }));
+	const next = { ...servers };
+	for (const hit of hits) next[hit.name] = { ...next[hit.name], enabled: false };
+	return { hits, changed: hits.length > 0 && saveConfig(source, { ...source.value, mcpServers: next }) };
+}
+
+export function disableEffectiveNativeDuplicates(paths: string[], endpoint: string) {
+	const owners = new Map<string, string>();
+	for (const path of paths) for (const name of Object.keys(readConfig(path).value.mcpServers as ObjectMap ?? {})) owners.set(name, path);
+	let changed = false;
+	const hits: DevspecServerHit[] = [];
+	for (const path of paths) {
+		const result = disableNativeDuplicates(path, endpoint, new Set([...owners].filter(([, owner]) => owner === path).map(([name]) => name)));
+		hits.push(...result.hits); changed = result.changed || changed;
+	}
+	return { hits, changed };
+}
+
+export interface AdapterConfigApi {
+	loadMcpConfig: (overridePath?: string, cwd?: string) => { mcpServers: Record<string, { url?: unknown; disabled?: unknown }> };
+	writeProjectServerDisabledOverride: (overridePath: string | undefined, cwd: string, name: string, disabled: boolean) => { path: string; changed: boolean };
+}
+export function disableAdapterDuplicates(api: AdapterConfigApi, cwd: string, endpoint: string, overridePath?: string) {
+	// Let the adapter own imports, precedence, custom config paths, JSONC and credential
+	// handling. Do not maintain a second, incomplete implementation of its discovery.
+	const config = api.loadMcpConfig(overridePath, cwd);
+	const hits = findDevspecServers(config.mcpServers, "pi-mcp-adapter", endpoint);
+	let changed = false;
+	for (const hit of hits) {
+		if (!hit.alreadyDisabled) {
+			const path = join(cwd, ".pi", "mcp-adapter.json");
+			try { if (lstatSync(path).isSymbolicLink()) throw new Error("Adapter override is a symlink"); }
+			catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+			changed = api.writeProjectServerDisabledOverride(overridePath, cwd, hit.name, true).changed || changed;
+		}
+	}
+	const verified = api.loadMcpConfig(overridePath, cwd);
+	if (hits.some((hit) => verified.mcpServers[hit.name]?.disabled !== true)) throw new Error("Adapter did not apply duplicate override; review exclusive/in-memory config");
+	return { hits, changed };
+}
+export function configPaths(agentDir: string, cwd: string, trusted: boolean) {
+	return [agentDir, ...(trusted ? [join(cwd, ".pi")] : [])].map((dir) => ({ native: join(dir, "mcp.json"), adapter: join(dir, "mcp-adapter.json") }));
+}

package/extensions/core/model-catalog.ts

@@ -0,0 +1,76 @@
+/**
+ * Live host model snapshot for CONTROL list_models (item abbec798).
+ *
+ * The list is THIS process’s list right now — scopedModels if the session is
+ * scoped, else auth-filtered getAvailable(). Never a DevSpec-owned menu.
+ */
+
+export interface ModelCatalogEntry {
+	provider: string;
+	id: string;
+	name?: string;
+}
+
+export interface ModelCatalogSnapshot {
+	v: 1;
+	current: string | null;
+	models: ModelCatalogEntry[];
+	at: string;
+	truncated?: boolean;
+}
+
+type ModelLike = {
+	provider?: string;
+	id?: string;
+	name?: string;
+};
+
+export function collectModelCatalog(ctx: {
+	scopedModels?: readonly { model?: ModelLike }[] | null;
+	modelRegistry?: {
+		getAvailable?: () => readonly ModelLike[];
+		// Pi's Model is a subtype; we only read provider/id/name.
+		hasConfiguredAuth?: (model: never) => boolean;
+	} | null;
+	model?: ModelLike | null;
+	now?: string;
+}): ModelCatalogSnapshot {
+	const scoped = (ctx.scopedModels ?? [])
+		.map((s) => s?.model)
+		.filter((m): m is ModelLike => Boolean(m?.provider && m?.id));
+	let raw: readonly ModelLike[];
+	if (scoped.length > 0) raw = scoped;
+	else {
+		const available = ctx.modelRegistry?.getAvailable?.();
+		if (!Array.isArray(available)) throw new Error("Host model registry unavailable");
+		// Unknown auth state is a failed read, not proof that a provider has no models.
+		raw = available.filter((m: ModelLike) => !ctx.modelRegistry?.hasConfiguredAuth || ctx.modelRegistry.hasConfiguredAuth(m as never));
+	}
+
+	const seen = new Set<string>();
+	const models: ModelCatalogEntry[] = [];
+	for (const m of raw) {
+		const provider = typeof m.provider === "string" ? m.provider.trim() : "";
+		const id = typeof m.id === "string" ? m.id.trim() : "";
+		if (!provider || !id || (m.name !== undefined && typeof m.name !== "string")) throw new Error("Invalid host model catalogue entry");
+		const key = `${provider}/${id}`;
+		if (seen.has(key)) continue;
+		seen.add(key);
+		const name = typeof m.name === "string" ? m.name.trim() : "";
+		models.push({
+			provider,
+			id,
+			...(name && name !== id ? { name } : {}),
+		});
+	}
+
+	const currentProvider = typeof ctx.model?.provider === "string" ? ctx.model.provider.trim() : "";
+	const currentId = typeof ctx.model?.id === "string" ? ctx.model.id.trim() : "";
+
+	return {
+		v: 1,
+		current: currentProvider && currentId ? `${currentProvider}/${currentId}` : null,
+		models,
+		at: ctx.now ?? new Date().toISOString(),
+	};
+}

package/extensions/core/model-surface.ts

@@ -0,0 +1,125 @@
+/** Native model surface: every safe eligible operation is available immediately.
+ * The wire catalogue, authored model guidance and optional search index are
+ * generated from the shared contract. Search recommends; it never grants access.
+ */
+import MiniSearch from 'minisearch';
+import { MCP_CATALOG, MODEL_VERB_NAMES, TOOL_SEARCH_DOCUMENTS, type CatalogEntry } from '../generated/mcp-catalog.ts';
+import { ROOM_READ_DESCRIPTION, ROOM_READ_SCHEMA, ROOM_READ_TOOL, ROOM_READ_PROMPT_METADATA } from './room-reader.ts';
+
+export const TOOL_LOADER_NAME = 'search_devspec_tools';
+export const PLAN_TOOL_NAME = 'manage_plan';
+export const POLL_TOOL_NAME = 'manage_poll';
+export const DIRECTED_QUESTION_TOOL_NAME = 'manage_directed_question';
+export const ACTIVATION_ONLY_VERBS = new Set<string>([PLAN_TOOL_NAME, POLL_TOOL_NAME, DIRECTED_QUESTION_TOOL_NAME]);
+/** Retained export name for host consumers; no longer a selected fifteen-tool tier. */
+export const HOT_SET_VERBS = MODEL_VERB_NAMES.filter(name => !ACTIVATION_ONLY_VERBS.has(name) && name !== TOOL_LOADER_NAME);
+export type HotSetVerb = (typeof HOT_SET_VERBS)[number];
+export const HOT_SET = new Set<string>(HOT_SET_VERBS);
+export const SCOPE_KEYS = ['git_remote', 'project_id', 'pinned_project_id', 'session_id', 'connection_id', 'local_session_id', 'commit_provenance_source', 'provenance_source'] as const;
+export const SCOPE_KEY_SET = new Set<string>(SCOPE_KEYS);
+export const MODEL_OWNED_SESSION_ID_VERBS = new Set<string>(['get_session_transcript']);
+export function scopeKeysForTool(name?: string): Set<string> {
+  const keys = new Set<string>(SCOPE_KEYS);
+  if (name && MODEL_OWNED_SESSION_ID_VERBS.has(name)) keys.delete('session_id');
+  return keys;
+}
+export function isConnectionBoundTool(name: string): boolean { return ACTIVATION_ONLY_VERBS.has(name); }
+export const TOOL_LOADER_DESCRIPTION = MCP_CATALOG.find(entry => entry.name === TOOL_LOADER_NAME)!.description;
+export interface ToolPromptMetadata { promptSnippet?: string; promptGuidelines?: string[]; }
+export const TOOL_LOADER_PROMPT_METADATA: ToolPromptMetadata = {};
+
+/** Drop host identity without discarding operational sentences or schema constraints. */
+export function slimSchema(schema: Record<string, unknown> | undefined, omitKeys: Set<string> = SCOPE_KEY_SET): Record<string, unknown> {
+  if (!schema || typeof schema !== 'object') return { type: 'object', properties: {} };
+  const visit = (value: unknown): unknown => {
+    if (Array.isArray(value)) return value.map(visit);
+    if (!value || typeof value !== 'object') return value;
+    return slimSchema(value as Record<string, unknown>, omitKeys);
+  };
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(schema)) {
+    if (key === 'properties' && value && typeof value === 'object' && !Array.isArray(value)) {
+      out.properties = Object.fromEntries(Object.entries(value).filter(([name, child]) => !omitKeys.has(name) && !(child && typeof child === 'object' && (child as Record<string, unknown>)['x-devspec-host-only'] === true)).map(([name, child]) => [name, visit(child)]));
+    } else if (key === 'required' && Array.isArray(value)) {
+      const required = value.filter(name => typeof name === 'string' && !omitKeys.has(name));
+      if (required.length) out.required = required;
+    } else out[key] = visit(value);
+  }
+  return out;
+}
+export function slimCatalogEntry(entry: CatalogEntry): CatalogEntry {
+  const inputSchema = slimSchema(entry.modelInputSchema, scopeKeysForTool(entry.name));
+  if (MODEL_OWNED_SESSION_ID_VERBS.has(entry.name) && Array.isArray(inputSchema.required)) {
+    const required = inputSchema.required.filter(name => name !== 'session_id');
+    if (required.length) inputSchema.required = required; else delete inputSchema.required;
+  }
+  return { ...entry, inputSchema };
+}
+export function catalogEntry(name: string): CatalogEntry | undefined { return MCP_CATALOG.find(entry => entry.name === name); }
+export function allModelFacingTools(): CatalogEntry[] { return MCP_CATALOG.filter(entry => entry.kind === 'model').map(slimCatalogEntry); }
+export function modelFacingSurface(): CatalogEntry[] { return allModelFacingTools().filter(entry => HOT_SET.has(entry.name)); }
+/** No deferred model tier remains. Kept for session-recovery consumers. */
+export function rareModelSurface(): CatalogEntry[] { return []; }
+export function rareModelVerbs(): string[] { return []; }
+export function isCallableModelVerb(name: string): boolean { return catalogEntry(name)?.kind === 'model'; }
+export function isHotSetVerb(name: string): boolean { return HOT_SET.has(name); }
+/** Tool schemas already carry the guidance; do not repeat the catalogue in prose. */
+export function hotToolPromptMetadata(_entry: CatalogEntry): ToolPromptMetadata { return {}; }
+
+export function exactModelToolNames(query: string): string[] | null {
+  const names = query.trim().replace(/`/g, '').split(/[\s,]+/).map(name => name.replace(/^\+/, ''));
+  return names.length && names.every(name => /^[a-z][a-z0-9]*_[a-z0-9_]+$/.test(name)) ? [...new Set(names)] : null;
+}
+const index = new MiniSearch({ fields: ['name', 'intent'], storeFields: ['description'], searchOptions: { boost: { intent: 3, name: 1 }, prefix: false, fuzzy: false } });
+index.addAll(TOOL_SEARCH_DOCUMENTS);
+const genericTerms = new Set('a an the to of for in on by with this that it my our me we you all is are can could please what how do does show get find list read write create update save send add tool tools'.split(' '));
+/** A page of recommendations, the same shape and bounds as the server's. */
+export interface ToolSearchPage { total_matching: number; offset: number; limit: number; returned: number; has_more: boolean; next_offset: number | null }
+export function toolSearchPage(total: number, offset: number, limit: number, returned: number): ToolSearchPage {
+  const end = offset + returned;
+  return { total_matching: total, offset, limit, returned, has_more: end < total, next_offset: end < total ? end : null };
+}
+/** The server's page size: three by default, ten at most. */
+export function toolSearchLimit(limit: unknown): number { return Math.max(1, Math.min(10, Math.trunc(typeof limit === 'number' && Number.isFinite(limit) ? limit : 3) || 3)); }
+/** Offline BM25 fallback. The server's hybrid recommendation is optional. */
+export function rankRareModelTools(query: string, availableNames: readonly string[] = HOT_SET_VERBS): CatalogEntry[] {
+  const available = new Set(availableNames);
+  const names = exactModelToolNames(query);
+  const specific = (query.toLowerCase().match(/[a-z0-9]+/g) ?? []).filter(term => !genericTerms.has(term));
+  const hits = names ?? (specific.length ? index.search(query).filter(hit => specific.some(term => (hit.match[term]?.length ?? 0) > 0)).map(hit => String(hit.id)) : []);
+  return hits.filter(name => available.has(name) && name !== TOOL_LOADER_NAME).flatMap(name => {
+    const entry = catalogEntry(name);
+    return entry?.kind === 'model' ? [slimCatalogEntry(entry)] : [];
+  });
+}
+export function searchRareModelTools(query: string, limit = 3, availableNames: readonly string[] = HOT_SET_VERBS, offset = 0): CatalogEntry[] {
+  const start = Math.max(0, Math.trunc(offset) || 0);
+  return rankRareModelTools(query, availableNames).slice(start, start + toolSearchLimit(limit));
+}
+/** The loader's parameters are the tool's own definition, less what the host fills in. */
+export function toolLoaderInputSchema(): Record<string, unknown> {
+  return slimCatalogEntry(catalogEntry(TOOL_LOADER_NAME)!).inputSchema;
+}
+export function estimatePrefixChars(instructions: string): number {
+  const tools = modelFacingSurface().map(entry => ({ name: entry.name, description: entry.description, inputSchema: entry.inputSchema }));
+  return JSON.stringify(tools).length + JSON.stringify({ name: TOOL_LOADER_NAME, description: TOOL_LOADER_DESCRIPTION, inputSchema: toolLoaderInputSchema() }).length
+    + JSON.stringify({ name: ROOM_READ_TOOL, description: ROOM_READ_DESCRIPTION, inputSchema: ROOM_READ_SCHEMA }).length
+    + instructions.length + (ROOM_READ_PROMPT_METADATA.promptSnippet ? `- ${ROOM_READ_TOOL}: ${ROOM_READ_PROMPT_METADATA.promptSnippet}`.length : 0);
+}
+export function estimatePlanToolChars(): number {
+  const entry = catalogEntry(PLAN_TOOL_NAME);
+  if (!entry) return 0;
+  const tool = slimCatalogEntry(entry);
+  return JSON.stringify({ name: tool.name, description: tool.description, inputSchema: tool.inputSchema }).length;
+}
+export function withPlanToolActive(active: readonly string[], enabled: boolean): string[] {
+  const rest = active.filter(name => name !== PLAN_TOOL_NAME); return enabled ? [...rest, PLAN_TOOL_NAME] : rest;
+}
+export function withDirectedQuestionToolActive(active: readonly string[], enabled: boolean): string[] {
+  const rest = active.filter(name => name !== DIRECTED_QUESTION_TOOL_NAME); return enabled ? [...rest, DIRECTED_QUESTION_TOOL_NAME] : rest;
+}
+export function withPollToolActive(active: readonly string[], enabled: boolean): string[] {
+  const rest = active.filter(name => name !== POLL_TOOL_NAME); return enabled ? [...rest, POLL_TOOL_NAME] : rest;
+}
+export function estimatePrefixTokens(instructions: string): number { return Math.ceil(estimatePrefixChars(instructions) / 4); }
+// Footprint is diagnostic, never a quota that hides operations or clips prose.

package/extensions/core/notice-reply.ts

@@ -0,0 +1,215 @@
+/**
+ * A notice-woken run's reply, posted into the room as a reply to the DevSpec
+ * notices that woke it (DevSpec item 6aad2b46; the server side is 8885423d).
+ *
+ * What such a post means — outside every command, turn and attempt, labelled as
+ * a reply to a DevSpec notice and to no person — is served at
+ * devspec://product/remote-ingress-contract (semantics.notice_reply). This module
+ * is Pi's side only: which notices a run answers, what counts as its final reply,
+ * the post's arguments, reading the receipt or the refusal, and reading the
+ * negotiated room snapshot of such a row exactly as the server's schema does.
+ */
+import { hasAssistantSpeech } from "./assistant-speech.ts";
+import { advertisesRoomContext } from "./room-context.ts";
+import { unwrapMcpResult } from "./result.ts";
+
+/** The server's NoticeReplySnapshot version and bounds (parity-tested against the served schema). */
+export const NOTICE_REPLY_SNAPSHOT_VERSION = 1;
+export const NOTICE_REPLY_MAX_NOTICES = 25;
+export const NOTICE_REPLY_NOTICE_KINDS = ["server_notice", "unlinked_commit_item_review"] as const;
+export const NOTICE_REPLY_NOTICE_KEYS = ["notice_id", "kind", "topic", "notice_type", "summary", "records"] as const;
+export const NOTICE_REPLY_RECORD_KEYS = ["label", "record_type", "record_id", "title", "url"] as const;
+/** zod's z.string().uuid(), the pattern the served JSON schema carries for notice_id. */
+export const NOTICE_REPLY_UUID_PATTERN = "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$";
+const UUID = new RegExp(NOTICE_REPLY_UUID_PATTERN);
+
+export interface NoticeReplyRecord { label: string; record_type: string; record_id: string; title: string; url: string | null }
+export interface NoticeReplyNotice {
+	notice_id: string;
+	kind: (typeof NOTICE_REPLY_NOTICE_KINDS)[number];
+	topic: string;
+	notice_type: string;
+	summary: string;
+	records: NoticeReplyRecord[];
+}
+/** room_context.messages[].notice_reply: the server's snapshot of the notices a row replies to. */
+export interface NoticeReplySnapshot { version: 1; notices: NoticeReplyNotice[] }
+
+type Row = Record<string, unknown>;
+function row(value: unknown): Row | null {
+	return value !== null && typeof value === "object" && !Array.isArray(value) ? value as Row : null;
+}
+function exactly(value: Row, keys: readonly string[]): boolean {
+	return keys.every((key) => Object.hasOwn(value, key)) && Object.keys(value).every((key) => keys.includes(key));
+}
+const strings = (value: Row, keys: readonly string[]) => keys.every((key) => typeof value[key] === "string");
+
+/**
+ * The snapshot exactly as the server's NoticeReplySnapshotSchema reads it, or null
+ * when the server's schema would refuse it. Strings may be empty, as zod's
+ * z.string() allows; nothing is trimmed or rewritten.
+ */
+export function parseNoticeReplySnapshot(value: unknown): NoticeReplySnapshot | null {
+	const snapshot = row(value);
+	if (!snapshot || !exactly(snapshot, ["version", "notices"]) || snapshot.version !== NOTICE_REPLY_SNAPSHOT_VERSION) return null;
+	const notices = snapshot.notices;
+	if (!Array.isArray(notices) || notices.length < 1 || notices.length > NOTICE_REPLY_MAX_NOTICES) return null;
+	const parsed: NoticeReplyNotice[] = [];
+	for (const item of notices) {
+		const notice = row(item);
+		if (!notice || !exactly(notice, NOTICE_REPLY_NOTICE_KEYS) || !strings(notice, ["notice_id", "topic", "notice_type", "summary"])) return null;
+		if (!UUID.test(notice.notice_id as string) || !NOTICE_REPLY_NOTICE_KINDS.includes(notice.kind as NoticeReplyNotice["kind"])) return null;
+		if (!Array.isArray(notice.records)) return null;
+		const records: NoticeReplyRecord[] = [];
+		for (const entry of notice.records) {
+			const record = row(entry);
+			if (!record || !exactly(record, NOTICE_REPLY_RECORD_KEYS) || !strings(record, ["label", "record_type", "record_id", "title"])) return null;
+			if (record.url !== null && typeof record.url !== "string") return null;
+			records.push({ label: record.label as string, record_type: record.record_type as string, record_id: record.record_id as string, title: record.title as string, url: record.url as string | null });
+		}
+		parsed.push({ notice_id: notice.notice_id as string, kind: notice.kind as NoticeReplyNotice["kind"], topic: notice.topic as string, notice_type: notice.notice_type as string, summary: notice.summary as string, records });
+	}
+	return { version: 1, notices: parsed };
+}
+
+/** Opt in to the snapshot only when the served contract advertises it: an older server refuses the argument. */
+export function advertisesNoticeReply(resource: unknown): boolean {
+	try {
+		for (const item of (row(resource)?.contents ?? []) as unknown[]) {
+			if (!advertisesRoomContext({ contents: [item] })) continue;
+			const contract = row(JSON.parse(String(row(item)?.text)));
+			const activation = row(contract?.activation);
+			const requires = row(activation?.notice_reply_requires);
+			if (activation?.notice_reply_negotiation_argument === "notice_reply_version" && requires?.room_context_version === 1 && requires?.notice_reply_version === 1) return true;
+		}
+	} catch { /* An older or unreadable advertisement keeps the room lane without the snapshot. */ }
+	return false;
+}
+
+/** The notice ids of one delivered batch, from the details Pi put on the notice message itself. */
+export function noticeIdsFromDelivery(details: unknown): string[] {
+	const notices = row(details)?.notices;
+	if (!Array.isArray(notices)) return [];
+	const ids: string[] = [];
+	for (const notice of notices) {
+		const id = row(notice)?.notice_id;
+		if (typeof id === "string" && UUID.test(id) && !ids.includes(id)) ids.push(id);
+	}
+	return ids;
+}
+
+/**
+ * The run's final reply: the text of its last assistant message, when the model
+ * finished that message itself. A run that ends on a tool call, an abort or a
+ * provider error, or whose last message has no text, has no final reply.
+ */
+export function noticeReplyFinalText(message: { text: string; stopReason?: string | null }): string | null {
+	if (message.stopReason !== "stop" && message.stopReason !== "length") return null;
+	return hasAssistantSpeech(message.text) ? message.text : null;
+}
+
+/** What one notice-woken segment answers and what it ended up saying. */
+export interface NoticeReplyCapture {
+	/** The connection the notices were delivered to; only it may name them. */
+	connectionId: string;
+	noticeIds: string[];
+	/** The notice framing told the model its final message reaches the room. */
+	roomPromised: boolean;
+	finalText: string | null;
+}
+
+export type NoticeReplyCallResult = { raw: unknown } | { refusal: string };
+
+export type NoticeReplyOutcome =
+	| { kind: "posted"; messageId: string; sessionId: string; idempotent: boolean }
+	| { kind: "no_final_text" }
+	| { kind: "not_attached" }
+	| { kind: "connection_changed" }
+	| { kind: "refused"; reason: string; detail: string }
+	| { kind: "unconfirmed"; detail: string };
+
+const canonical = (ids: readonly string[]) => [...new Set(ids.map((id) => id.trim().toLowerCase()))].sort();
+
+/** A stored receipt for exactly this reply, or null. Anything else is not proof the room shows it. */
+export function readNoticeReplyReceipt(raw: unknown, expected: { connectionId: string; noticeIds: readonly string[] }):
+	{ messageId: string; sessionId: string; idempotent: boolean } | null {
+	const { details, isError } = unwrapMcpResult(raw);
+	const data = row(details);
+	const delivery = row(data?.delivery);
+	if (isError || !data || !delivery) return null;
+	if (delivery.status !== "stored" && delivery.status !== "idempotently_stored") return null;
+	const messageId = data.message_id;
+	const sessionId = data.session_id;
+	if (typeof messageId !== "string" || !messageId || delivery.message_id !== messageId || typeof sessionId !== "string" || !sessionId) return null;
+	if (data.connection_id !== expected.connectionId || data.phase !== "answer" || data.turn_effect !== "none") return null;
+	const answered = row(data.notice_reply)?.notice_ids;
+	if (!Array.isArray(answered) || !answered.every((id) => typeof id === "string")) return null;
+	if (JSON.stringify(canonical(answered as string[])) !== JSON.stringify(canonical(expected.noticeIds))) return null;
+	return { messageId, sessionId, idempotent: delivery.status === "idempotently_stored" };
+}
+
+/** The server's refusal: its delivery reason and its own words, verbatim. */
+export function readNoticeReplyRefusal(text: string): { reason: string; detail: string } {
+	try {
+		const data = row(JSON.parse(text));
+		const delivery = row(data?.delivery);
+		if (delivery?.status === "rejected" && typeof delivery.reason === "string" && delivery.reason) {
+			return { reason: delivery.reason, detail: typeof data?.error === "string" && data.error.trim() ? data.error.trim() : text.trim() };
+		}
+	} catch { /* A refusal before anything was read is plain text. */ }
+	return { reason: "refused", detail: text.trim() };
+}
+
+/**
+ * Post the segment's final reply as a reply to its notices. Only connection_id,
+ * the text and the notice ids identify it: no command, turn, attempt, trail or
+ * completion, so nothing here can change Working, Pending or idle. The server
+ * stores the same notices and text once, so a room change between its read and
+ * its write is sent once more.
+ */
+export async function postNoticeReply(input: {
+	capture: NoticeReplyCapture;
+	/** This Pi's DevSpec connection and room right now, or null without one. */
+	current: () => { connectionId: string; sessionId: string | null } | null;
+	call: (args: Record<string, unknown>) => Promise<NoticeReplyCallResult>;
+	/** agent_name, agent_stats and model, as every answer carries them. */
+	extraArgs?: Record<string, unknown>;
+}): Promise<NoticeReplyOutcome> {
+	const { capture } = input;
+	if (capture.finalText === null || capture.noticeIds.length === 0) return { kind: "no_final_text" };
+	const args = { ...input.extraArgs, connection_id: capture.connectionId, message: capture.finalText, system_notice_ids: [...capture.noticeIds] };
+	for (let attempt = 0; ; attempt += 1) {
+		const now = input.current();
+		if (!now || now.connectionId !== capture.connectionId) return { kind: "connection_changed" };
+		if (!now.sessionId) return { kind: "not_attached" };
+		let result: NoticeReplyCallResult;
+		try { result = await input.call(args); }
+		catch (error) { return { kind: "unconfirmed", detail: error instanceof Error ? error.message : String(error) }; }
+		if ("refusal" in result) {
+			const refusal = readNoticeReplyRefusal(result.refusal);
+			if (refusal.reason === "room_changed" && attempt === 0) continue;
+			return { kind: "refused", ...refusal };
+		}
+		const receipt = readNoticeReplyReceipt(result.raw, { connectionId: capture.connectionId, noticeIds: capture.noticeIds });
+		return receipt ? { kind: "posted", ...receipt } : { kind: "unconfirmed", detail: "DevSpec's receipt did not confirm this reply" };
+	}
+}
+
+/** What the person at Pi is told, or null when there is nothing to tell. Never silent about a reply that did not land. */
+export function noticeReplyTerminalMessage(outcome: NoticeReplyOutcome, capture: NoticeReplyCapture): string | null {
+	const what = capture.noticeIds.length === 1 ? "The reply to the DevSpec notice" : `The reply to ${capture.noticeIds.length} DevSpec notices`;
+	switch (outcome.kind) {
+		case "posted":
+		case "no_final_text":
+			return null;
+		case "not_attached":
+			// Not attached when the notice arrived: the model was told its reply stays here.
+			return capture.roomPromised ? `DevSpec: ${what} was not posted, because Pi is no longer attached to a room. It stays here in the terminal.` : null;
+		case "connection_changed":
+			return `DevSpec: ${what} was not posted, because this Pi's DevSpec connection changed during the run. It stays here in the terminal.`;
+		case "refused":
+			return `DevSpec: ${what} was not posted to the room (${outcome.reason}). ${outcome.detail}`;
+		case "unconfirmed":
+			return `DevSpec: ${what} may not have reached the room (${outcome.detail}). Check the room before sending it again.`;
+	}
+}