gentle-pi 2.4.0 → 2.6.0

package/lib/agents-config.ts

@@ -0,0 +1,315 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { THINKING_LEVELS as ROUTING_THINKING_LEVELS, type ThinkingLevel as RoutingThinkingLevel } from "./model-routing-authority.ts";
+
+// Gentle Agents configuration. Agent definitions are markdown files with YAML
+// frontmatter (the format gentle-ai installs) and runtime settings come from
+// subagents.json at the global and project level. Everything here is pure
+// apart from the discovery helpers, which take their roots as arguments.
+
+export const AGENT_MODE = {
+	TASK: "task",
+	BACKGROUND: "background",
+} as const;
+
+export type AgentMode = (typeof AGENT_MODE)[keyof typeof AGENT_MODE];
+
+export type ThinkingLevel = RoutingThinkingLevel;
+
+// Preserve the uppercase compatibility keys without maintaining a second level list.
+export const THINKING_LEVEL = Object.fromEntries(
+	ROUTING_THINKING_LEVELS.map((level) => [level.toUpperCase(), level]),
+) as { readonly [Level in ThinkingLevel as Uppercase<Level>]: Level };
+
+export const AGENT_SCOPE = {
+	GLOBAL: "global",
+	PROJECT: "project",
+} as const;
+
+export type AgentScope = (typeof AGENT_SCOPE)[keyof typeof AGENT_SCOPE];
+
+export const PROFILE_SOURCE = {
+	PROFILE: "profile",
+	DEFINITION: "definition",
+	DEFAULT: "default",
+	UNRESOLVED: "unresolved",
+} as const;
+
+export type ProfileSource = (typeof PROFILE_SOURCE)[keyof typeof PROFILE_SOURCE];
+
+export interface ModelRef {
+	provider: string | undefined;
+	id: string;
+}
+
+export interface AgentDefinition {
+	name: string;
+	description: string;
+	filePath: string;
+	scope: AgentScope;
+	instructions: string;
+	model: ModelRef | undefined;
+	thinking: ThinkingLevel | undefined;
+	mode: AgentMode | undefined;
+	tools: string[];
+}
+
+export interface AgentDefinitionError {
+	filePath: string;
+	error: string;
+}
+
+export interface ModelProfile {
+	model: ModelRef | undefined;
+	thinking: ThinkingLevel | undefined;
+}
+
+export interface AgentsConfig {
+	defaultModel: ModelRef | undefined;
+	defaultThinking: ThinkingLevel | undefined;
+	defaultMode: AgentMode;
+	modelProfiles: Record<string, ModelProfile>;
+	stallTimeoutMs: number;
+	maxConcurrency: number;
+	historyMaxTasks: number;
+}
+
+export interface ProfileSources {
+	model: ProfileSource;
+	thinking: ProfileSource;
+}
+
+export interface ResolvedProfile {
+	model: ModelRef | undefined;
+	thinking: ThinkingLevel | undefined;
+	source: ProfileSources;
+}
+
+export interface DiscoveryRoots {
+	cwd: string;
+	home: string;
+	agentHome?: string;
+}
+
+export interface DiscoveryResult {
+	agents: AgentDefinition[];
+	errors: string[];
+}
+
+export type FrontmatterValue = string | string[];
+
+export interface Frontmatter {
+	data: Record<string, FrontmatterValue>;
+	body: string;
+}
+
+const DEFAULT_STALL_TIMEOUT_MS = 4 * 60_000;
+const DEFAULT_MAX_CONCURRENCY = 5;
+const DEFAULT_HISTORY_MAX_TASKS = 200;
+const THINKING_LEVELS: readonly string[] = ROUTING_THINKING_LEVELS;
+const AGENT_MODES = Object.values(AGENT_MODE) as string[];
+
+function unquote(value: string): string {
+	const trimmed = value.trim();
+	const quoted = (trimmed.startsWith('"') && trimmed.endsWith('"')) || (trimmed.startsWith("'") && trimmed.endsWith("'"));
+	return quoted && trimmed.length >= 2 ? trimmed.slice(1, -1) : trimmed;
+}
+
+function parseInlineList(value: string): string[] {
+	return value.slice(1, -1).split(",").map(unquote).filter((item) => item.length > 0);
+}
+
+// Just enough YAML for agent frontmatter: `key: scalar`, `key: [a, b]`, and
+// `key:` followed by `- item` lines. Anything else stays a plain string.
+export function parseFrontmatter(text: string): Frontmatter {
+	const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(text);
+	if (!match) return { data: {}, body: text.trim() };
+	const data: Record<string, FrontmatterValue> = {};
+	let listKey: string | undefined;
+	for (const raw of match[1].split(/\r?\n/)) {
+		const item = /^\s*-\s+(.*)$/.exec(raw);
+		if (item && listKey) {
+			(data[listKey] as string[]).push(unquote(item[1]));
+			continue;
+		}
+		const pair = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(raw);
+		if (!pair) continue;
+		const [, key, value] = pair;
+		const trimmed = value.trim();
+		if (trimmed.length === 0) {
+			data[key] = [];
+			listKey = key;
+			continue;
+		}
+		listKey = undefined;
+		data[key] = trimmed.startsWith("[") && trimmed.endsWith("]") ? parseInlineList(trimmed) : unquote(trimmed);
+	}
+	return { data, body: match[2].trim() };
+}
+
+export function parseModelRef(value: unknown): ModelRef | undefined {
+	if (typeof value !== "string") return undefined;
+	const trimmed = value.trim();
+	if (trimmed.length === 0) return undefined;
+	const slash = trimmed.indexOf("/");
+	if (slash <= 0) return { provider: undefined, id: trimmed };
+	return { provider: trimmed.slice(0, slash), id: trimmed.slice(slash + 1) };
+}
+
+function parseThinking(value: unknown): ThinkingLevel | undefined | string {
+	if (value === undefined) return undefined;
+	const normalized = String(value).trim().toLowerCase();
+	return THINKING_LEVELS.includes(normalized) ? (normalized as ThinkingLevel) : `thinking "${value}" is not one of ${THINKING_LEVELS.join(", ")}`;
+}
+
+function parseMode(value: unknown): AgentMode | undefined | string {
+	if (value === undefined) return undefined;
+	const normalized = String(value).trim().toLowerCase();
+	return AGENT_MODES.includes(normalized) ? (normalized as AgentMode) : `mode "${value}" is not one of ${AGENT_MODES.join(", ")}`;
+}
+
+function parseTools(value: FrontmatterValue | undefined): string[] {
+	if (value === undefined) return [];
+	const items = Array.isArray(value) ? value : value.split(",");
+	return items.map((item) => item.trim()).filter((item) => item.length > 0);
+}
+
+function scalar(value: FrontmatterValue | undefined): string | undefined {
+	return typeof value === "string" ? value : undefined;
+}
+
+export function parseAgentDefinition(text: string, filePath: string, scope: AgentScope): AgentDefinition | AgentDefinitionError {
+	const { data, body } = parseFrontmatter(text);
+	const thinking = parseThinking(scalar(data.thinking) ?? scalar(data.effort) ?? scalar(data.thinking_level));
+	if (thinking !== undefined && !THINKING_LEVELS.includes(thinking)) return { filePath, error: thinking };
+	const mode = parseMode(scalar(data.subagent_mode) ?? scalar(data.mode));
+	if (mode !== undefined && !AGENT_MODES.includes(mode)) return { filePath, error: mode };
+	if (body.length === 0) return { filePath, error: "no instructions after the frontmatter" };
+	const name = scalar(data.name)?.trim() || basename(filePath).replace(/\.md$/i, "");
+	return {
+		name,
+		description: scalar(data.description)?.trim() ?? "",
+		filePath,
+		scope,
+		instructions: body,
+		model: parseModelRef(data.model),
+		thinking: thinking as ThinkingLevel | undefined,
+		mode: mode as AgentMode | undefined,
+		tools: parseTools(data.tools),
+	};
+}
+
+// Discovery order is precedence order: a later directory replaces an earlier
+// definition with the same name, so project beats global and `subagents/`
+// beats `agents/` within each scope.
+function profileRoot(roots: DiscoveryRoots): string {
+	return roots.agentHome ?? join(roots.home, ".pi", "agent");
+}
+
+export function agentDirectories(roots: DiscoveryRoots): Array<{ dir: string; scope: AgentScope }> {
+	const agentHome = profileRoot(roots);
+	return [
+		{ dir: join(agentHome, "agents"), scope: AGENT_SCOPE.GLOBAL },
+		{ dir: join(agentHome, "subagents"), scope: AGENT_SCOPE.GLOBAL },
+		{ dir: join(roots.cwd, ".pi", "agents"), scope: AGENT_SCOPE.PROJECT },
+		{ dir: join(roots.cwd, ".pi", "subagents"), scope: AGENT_SCOPE.PROJECT },
+	];
+}
+
+export function discoverAgents(roots: DiscoveryRoots): DiscoveryResult {
+	const agents = new Map<string, AgentDefinition>();
+	const errors: string[] = [];
+	for (const { dir, scope } of agentDirectories(roots)) {
+		if (!existsSync(dir)) continue;
+		for (const file of readdirSync(dir).filter((entry) => entry.toLowerCase().endsWith(".md")).sort()) {
+			const filePath = join(dir, file);
+			const parsed = parseAgentDefinition(readFileSync(filePath, "utf8"), filePath, scope);
+			if ("error" in parsed) errors.push(`${filePath}: ${parsed.error}`);
+			else agents.set(parsed.name, parsed);
+		}
+	}
+	return { agents: [...agents.values()].sort((a, b) => a.name.localeCompare(b.name)), errors };
+}
+
+type RawConfig = Record<string, unknown> | undefined;
+
+function positiveInteger(value: unknown, fallback: number): number {
+	return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : fallback;
+}
+
+function parseProfiles(value: unknown): Record<string, ModelProfile> {
+	const profiles: Record<string, ModelProfile> = {};
+	if (!value || typeof value !== "object") return profiles;
+	for (const [name, raw] of Object.entries(value as Record<string, unknown>)) {
+		if (!raw || typeof raw !== "object") continue;
+		const entry = raw as Record<string, unknown>;
+		const thinking = parseThinking(entry.effort ?? entry.thinking);
+		profiles[name] = { model: parseModelRef(entry.model), thinking: thinking !== undefined && THINKING_LEVELS.includes(thinking) ? (thinking as ThinkingLevel) : undefined };
+	}
+	return profiles;
+}
+
+function mergeProfiles(base: Record<string, ModelProfile>, override: Record<string, ModelProfile>): Record<string, ModelProfile> {
+	const merged = { ...base };
+	for (const [name, profile] of Object.entries(override)) {
+		merged[name] = { model: profile.model ?? base[name]?.model, thinking: profile.thinking ?? base[name]?.thinking };
+	}
+	return merged;
+}
+
+// Project settings override global ones field by field; model profiles merge
+// per agent so a project can change one effort without repeating the model.
+export function parseAgentsConfig(global: RawConfig, project: RawConfig): AgentsConfig {
+	const merged: Record<string, unknown> = { ...(global ?? {}), ...(project ?? {}) };
+	const thinking = parseThinking(merged.default_effort ?? merged.default_thinking_level ?? merged.default_thinking);
+	const mode = parseMode(merged.default_mode);
+	return {
+		defaultModel: parseModelRef(merged.default_model),
+		defaultThinking: thinking !== undefined && THINKING_LEVELS.includes(thinking) ? (thinking as ThinkingLevel) : undefined,
+		defaultMode: mode !== undefined && AGENT_MODES.includes(mode) ? (mode as AgentMode) : AGENT_MODE.TASK,
+		modelProfiles: mergeProfiles(parseProfiles(global?.model_profiles), parseProfiles(project?.model_profiles)),
+		// `timeout_ms` remains accepted as an inert legacy key so existing JSON
+		// files load normally; only silence is bounded by `stall_timeout_ms`.
+		stallTimeoutMs: positiveInteger(merged.stall_timeout_ms, DEFAULT_STALL_TIMEOUT_MS),
+		maxConcurrency: positiveInteger(merged.max_concurrency, DEFAULT_MAX_CONCURRENCY),
+		historyMaxTasks: positiveInteger(merged.history_max_tasks, DEFAULT_HISTORY_MAX_TASKS),
+	};
+}
+
+function readJson(path: string): RawConfig {
+	if (!existsSync(path)) return undefined;
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf8")) as unknown;
+		return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? (parsed as Record<string, unknown>) : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+export function loadAgentsConfig(roots: DiscoveryRoots): AgentsConfig {
+	return parseAgentsConfig(readJson(join(profileRoot(roots), "subagents.json")), readJson(join(roots.cwd, ".pi", "subagents.json")));
+}
+
+function pick<T>(candidates: Array<[T | undefined, ProfileSource]>): [T | undefined, ProfileSource] {
+	return candidates.find(([value]) => value !== undefined) ?? [undefined, PROFILE_SOURCE.UNRESOLVED];
+}
+
+export function resolveAgentProfile(agent: AgentDefinition, config: AgentsConfig): ResolvedProfile {
+	const profile = config.modelProfiles[agent.name];
+	const [model, modelSource] = pick<ModelRef>([
+		[profile?.model, PROFILE_SOURCE.PROFILE],
+		[agent.model, PROFILE_SOURCE.DEFINITION],
+		[config.defaultModel, PROFILE_SOURCE.DEFAULT],
+	]);
+	const [thinking, thinkingSource] = pick<ThinkingLevel>([
+		[profile?.thinking, PROFILE_SOURCE.PROFILE],
+		[agent.thinking, PROFILE_SOURCE.DEFINITION],
+		[config.defaultThinking, PROFILE_SOURCE.DEFAULT],
+	]);
+	return { model, thinking, source: { model: modelSource, thinking: thinkingSource } };
+}
+
+export function formatModelRef(model: ModelRef | undefined): string {
+	if (!model) return "default";
+	return model.provider ? `${model.provider}/${model.id}` : model.id;
+}

package/lib/agents-history.ts

@@ -0,0 +1,88 @@
+import { mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { emptyThread, type TaskRecord, type TaskThread } from "./agents-protocol.ts";
+
+// Gentle Agents history: one JSON file per finished task, written by the
+// host after the child is gone and read back lazily when the overlay opens
+// or a tool asks for a task from an earlier session. Everything is async so
+// the terminal never waits on disk.
+
+export interface StoredTask {
+	task: TaskRecord;
+	thread: TaskThread;
+}
+
+export function remediationUnresolved(task: TaskRecord): boolean {
+	const state = task.sddRemediation;
+	if (!state) return false;
+	if (state.acquireUncertain || state.settlementUncertain) return true;
+	if (state.settlement) return state.settlement.state === "blocked";
+	return !!state.token || !!state.actorClaimed || !["blocked", "complete"].includes(state.acquireResult?.state ?? "");
+}
+
+const FILE_SUFFIX = ".json";
+const SAFE_ID = /^[a-z0-9-]+$/i;
+
+export function historyDir(home: string, agentHome = join(home, ".pi", "agent")): string {
+	return join(agentHome, "gentle-agents", "tasks");
+}
+
+function fileFor(dir: string, id: string): string {
+	if (!SAFE_ID.test(id)) throw new Error(`invalid task id: ${id}`);
+	return join(dir, `${id}${FILE_SUFFIX}`);
+}
+
+function isRecord(value: unknown): value is TaskRecord {
+	const task = value as Partial<TaskRecord> | undefined;
+	return typeof task?.id === "string" && typeof task.agent === "string" && typeof task.status === "string" && typeof task.createdAt === "number";
+}
+
+function parseStored(text: string): StoredTask | undefined {
+	try {
+		const parsed = JSON.parse(text) as Partial<StoredTask>;
+		if (!isRecord(parsed.task)) return undefined;
+		const thread = parsed.thread && Array.isArray(parsed.thread.items) ? parsed.thread : emptyThread();
+		return { task: parsed.task, thread: { ...emptyThread(), ...thread } };
+	} catch {
+		return undefined;
+	}
+}
+
+export async function saveTask(dir: string, task: TaskRecord, thread: TaskThread): Promise<void> {
+	await mkdir(dir, { recursive: true });
+	const target = fileFor(dir, task.id);
+	const temp = `${target}.${process.pid}-${Math.random().toString(36).slice(2, 8)}.tmp`;
+	await writeFile(temp, JSON.stringify({ task, thread }), "utf8");
+	await rename(temp, target);
+}
+
+export async function loadStoredTask(dir: string, id: string): Promise<StoredTask | undefined> {
+	if (!SAFE_ID.test(id)) return undefined;
+	try {
+		return parseStored(await readFile(fileFor(dir, id), "utf8"));
+	} catch {
+		return undefined;
+	}
+}
+
+async function listFiles(dir: string): Promise<string[]> {
+	try {
+		return (await readdir(dir)).filter((name) => name.endsWith(FILE_SUFFIX));
+	} catch {
+		return [];
+	}
+}
+
+export async function loadHistory(dir: string): Promise<StoredTask[]> {
+	const files = await listFiles(dir);
+	const stored = await Promise.all(files.map(async (name) => parseStored(await readFile(join(dir, name), "utf8").catch(() => ""))));
+	return stored.filter((entry): entry is StoredTask => entry !== undefined).sort((a, b) => b.task.createdAt - a.task.createdAt);
+}
+
+// Keep the newest `maxTasks` files; the rest go. Returns how many were removed.
+export async function pruneHistory(dir: string, maxTasks: number): Promise<number> {
+	const stored = await loadHistory(dir);
+	const extra = stored.filter(({ task }) => !remediationUnresolved(task)).slice(Math.max(0, maxTasks));
+	await Promise.all(extra.map((entry) => rm(fileFor(dir, entry.task.id), { force: true })));
+	return extra.length;
+}

package/lib/agents-messaging.ts

@@ -0,0 +1,187 @@
+export const CHILD_MESSAGE_MAX_BYTES = 8 * 1024;
+export const CHILD_ACK_ERROR_MAX_BYTES = 256;
+export const CHILD_QUERY_ERROR_MAX_BYTES = 256;
+export const CHILD_MESSAGE_MAX_INFLIGHT = 8;
+export const CHILD_MESSAGE_TIMEOUT_MS = 2_000;
+export const CHILD_QUERY_MAX_INFLIGHT = 4;
+export const CHILD_QUERY_TIMEOUT_MS = 30_000;
+
+export interface NotificationFrame {
+	id: string;
+	kind: "notification";
+	message: string;
+}
+
+export interface QueryFrame {
+	id: string;
+	kind: "query";
+	message: string;
+}
+
+export type ChildFrame = NotificationFrame | QueryFrame;
+
+interface AckFrame {
+	id: string;
+	accepted: boolean;
+	error?: string;
+}
+
+type ReplyFrame = { id: string; message: string } | { id: string; error: string };
+
+export interface IpcEndpoint {
+	connected?: boolean;
+	send(message: unknown, callback?: (error: Error | null) => void): boolean;
+	on(event: "message" | "disconnect", listener: (...args: unknown[]) => void): unknown;
+}
+
+type Cancel = () => void;
+type Schedule = (fn: () => void, ms: number) => Cancel;
+type Pending<T> = { resolve: (value: T) => void; reject: (error: Error) => void; cancel: Cancel };
+
+function record(value: unknown): value is Record<string, unknown> {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function exact(value: Record<string, unknown>, keys: readonly string[]): boolean {
+	return Object.keys(value).every((key) => keys.includes(key));
+}
+
+function wellFormedUnicode(value: string): boolean {
+	for (let index = 0; index < value.length; index += 1) {
+		const code = value.charCodeAt(index);
+		if (code >= 0xD800 && code <= 0xDBFF) {
+			const next = value.charCodeAt(index + 1);
+			if (index + 1 >= value.length || next < 0xDC00 || next > 0xDFFF) return false;
+			index += 1;
+		} else if (code >= 0xDC00 && code <= 0xDFFF) return false;
+	}
+	return true;
+}
+
+function boundedText(value: unknown, maxBytes: number): value is string {
+	return typeof value === "string" && wellFormedUnicode(value) && Buffer.byteLength(value, "utf8") <= maxBytes;
+}
+
+function validCorrelation(value: unknown, prefix: "n" | "q"): value is string {
+	if (typeof value !== "string" || !new RegExp(`^${prefix}[1-9]\\d{0,15}$`).test(value)) return false;
+	const counter = Number(value.slice(1));
+	return Number.isSafeInteger(counter) && counter > 0;
+}
+
+export function validChildId(value: unknown): value is string {
+	return validCorrelation(value, "n");
+}
+
+export function validChildQueryId(value: unknown): value is string {
+	return validCorrelation(value, "q");
+}
+
+export function validChildMessage(value: unknown): value is string {
+	return boundedText(value, CHILD_MESSAGE_MAX_BYTES);
+}
+
+export function parseChildFrame(value: unknown): { frame?: ChildFrame; id?: string; error?: string } {
+	if (!record(value)) return { error: "invalid child IPC frame" };
+	const id = validChildQueryId(value.id) || validChildId(value.id) ? value.id : undefined;
+	if (!exact(value, ["id", "kind", "message"])) return { ...(id === undefined ? {} : { id }), error: "invalid child IPC frame" };
+	if (id === undefined) return { error: "invalid child IPC correlation" };
+	if (value.kind !== "notification" && value.kind !== "query") return { id, error: "unsupported child IPC kind" };
+	if (value.kind === "notification" && !validChildId(id) || value.kind === "query" && !validChildQueryId(id)) return { id, error: "invalid child IPC correlation" };
+	if (!validChildMessage(value.message)) return { id, error: "invalid child IPC message" };
+	return { frame: { id, kind: value.kind, message: value.message } } as { frame: ChildFrame };
+}
+
+function parseAck(value: unknown): AckFrame | undefined {
+	if (!record(value) || !exact(value, ["id", "kind", "accepted", "error"]) || !validChildId(value.id) || value.kind !== "ack" || typeof value.accepted !== "boolean") return undefined;
+	if (value.accepted && value.error !== undefined) return undefined;
+	if (value.error !== undefined && !boundedText(value.error, CHILD_ACK_ERROR_MAX_BYTES)) return undefined;
+	return { id: value.id, accepted: value.accepted, ...(value.error === undefined ? {} : { error: value.error }) };
+}
+
+function parseReply(value: unknown): ReplyFrame | undefined {
+	if (!record(value) || !validChildQueryId(value.id) || value.kind !== "reply") return undefined;
+	if (exact(value, ["id", "kind", "message"]) && validChildMessage(value.message)) return { id: value.id, message: value.message };
+	if (exact(value, ["id", "kind", "error"]) && boundedText(value.error, CHILD_QUERY_ERROR_MAX_BYTES)) return { id: value.id, error: value.error };
+	return undefined;
+}
+
+// Child-side admissions make acceptance explicit, but do not imply the parent
+// model read the message or that any later delivery is guaranteed.
+export class ChildMessenger {
+	private readonly pending = new Map<string, Pending<void>>();
+	private readonly queries = new Map<string, Pending<string>>();
+	private readonly endpoint: IpcEndpoint;
+	private readonly schedule: Schedule;
+	private nextId = 0;
+	private nextQueryId = 0;
+	private closed = false;
+
+	constructor(endpoint: IpcEndpoint, schedule: Schedule = (fn, ms) => {
+		const timer = setTimeout(fn, ms);
+		timer.unref?.();
+		return () => clearTimeout(timer);
+	}) {
+		this.endpoint = endpoint;
+		this.schedule = schedule;
+		endpoint.on("message", (value) => this.receive(value));
+		endpoint.on("disconnect", () => this.close("parent notification channel closed"));
+	}
+
+	notify(message: string): Promise<void> {
+		if (!this.available()) return Promise.reject(new Error("parent notification channel closed"));
+		if (!validChildMessage(message)) return Promise.reject(new Error("message is not well-formed UTF-16 or exceeds 8KiB"));
+		if (this.pending.size >= CHILD_MESSAGE_MAX_INFLIGHT) return Promise.reject(new Error("too many pending parent-message admissions"));
+		if (this.nextId >= Number.MAX_SAFE_INTEGER) return Promise.reject(new Error("parent-message correlation exhausted"));
+		return this.send(this.pending, `n${++this.nextId}`, "notification", message, CHILD_MESSAGE_TIMEOUT_MS, "parent-message admission timed out");
+	}
+
+	query(message: string): Promise<string> {
+		if (!this.available()) return Promise.reject(new Error("parent notification channel closed"));
+		if (!validChildMessage(message)) return Promise.reject(new Error("query is not well-formed UTF-16 or exceeds 8KiB"));
+		if (this.queries.size >= CHILD_QUERY_MAX_INFLIGHT) return Promise.reject(new Error("too many pending parent queries"));
+		if (this.nextQueryId >= Number.MAX_SAFE_INTEGER) return Promise.reject(new Error("parent query correlation exhausted"));
+		return this.send(this.queries, `q${++this.nextQueryId}`, "query", message, CHILD_QUERY_TIMEOUT_MS, "parent query timed out");
+	}
+
+	close(reason = "parent notification channel closed"): void {
+		if (this.closed) return;
+		this.closed = true;
+		for (const id of [...this.pending.keys()]) this.settle(this.pending, id, new Error(reason));
+		for (const id of [...this.queries.keys()]) this.settle(this.queries, id, new Error(reason));
+	}
+
+	private available(): boolean {
+		if (!this.closed && this.endpoint.connected !== false) return true;
+		this.close("parent notification channel closed");
+		return false;
+	}
+
+	private send<T>(pending: Map<string, Pending<T>>, id: string, kind: "notification" | "query", message: string, timeout: number, timeoutMessage: string): Promise<T> {
+		return new Promise((resolve, reject) => {
+			const settle = (error?: Error, reply?: T) => this.settle(pending, id, error, reply);
+			const cancel = this.schedule(() => settle(new Error(timeoutMessage)), timeout);
+			pending.set(id, { resolve, reject, cancel });
+			try { this.endpoint.send({ id, kind, message }, (error) => { if (error) settle(error); }); }
+			catch (error) { settle(error instanceof Error ? error : new Error(String(error))); }
+		});
+	}
+
+	private receive(value: unknown): void {
+		const ack = parseAck(value);
+		if (ack) {
+			this.settle(this.pending, ack.id, ack.accepted ? undefined : new Error(ack.error || "parent rejected notification"));
+			return;
+		}
+		const reply = parseReply(value);
+		if (reply) this.settle(this.queries, reply.id, "error" in reply ? new Error(reply.error || "parent rejected query") : undefined, "message" in reply ? reply.message : undefined);
+	}
+
+	private settle<T>(pending: Map<string, Pending<T>>, id: string, error?: Error, value?: T): void {
+		const entry = pending.get(id);
+		if (!entry) return;
+		pending.delete(id);
+		entry.cancel();
+		if (error) entry.reject(error);
+		else entry.resolve(value as T);
+	}
+}