@sng2c/pi-the-giver 0.1.0 → 0.1.1

package/node_modules/pi-subagents/src/extension/schemas.ts

@@ -0,0 +1,265 @@
+/**
+ * TypeBox schemas for subagent tool parameters
+ */
+
+import { Type } from "typebox";
+import { SUBAGENT_ACTIONS } from "../shared/types.ts";
+
+function keepTopLevelParameterDescriptions<T>(schema: T): T {
+	return pruneNestedDescriptions(schema, []) as T;
+}
+
+function pruneNestedDescriptions(value: unknown, path: string[]): unknown {
+	if (!value || typeof value !== "object") return value;
+
+	const result = Array.isArray(value) ? [] : Object.create(Object.getPrototypeOf(value));
+	for (const key of Reflect.ownKeys(value)) {
+		const descriptor = Object.getOwnPropertyDescriptor(value, key);
+		if (!descriptor) continue;
+		if (key === "description" && !isTopLevelParameterDescription(path)) continue;
+		if ("value" in descriptor) {
+			const nextPath = typeof key === "string" ? [...path, key] : path;
+			descriptor.value = pruneNestedDescriptions(descriptor.value, nextPath);
+		}
+		Object.defineProperty(result, key, descriptor);
+	}
+	return result;
+}
+
+function isTopLevelParameterDescription(path: string[]): boolean {
+	return path.length === 2 && path[0] === "properties";
+}
+
+const SkillOverride = Type.Unsafe({
+	anyOf: [
+		{ type: "array", items: { type: "string" } },
+		{ type: "boolean" },
+		{ type: "string" },
+	],
+	description: "Skill name(s) to make available (comma-separated), array of strings, or boolean (false disables, true uses default)",
+});
+
+const OutputOverride = Type.Unsafe({
+	anyOf: [
+		{ type: "string" },
+		{ type: "boolean" },
+	],
+	description: "Output filename/path (string), or false to disable file output",
+});
+
+const OutputModeOverride = Type.String({
+	enum: ["inline", "file-only"],
+	description: "Return saved output inline (default) or only a concise file reference. file-only requires output to be a path.",
+});
+
+const ReadsOverride = Type.Unsafe({
+	anyOf: [
+		{ type: "array", items: { type: "string" } },
+		{ type: "boolean" },
+	],
+	description: "Files to read before running (array of filenames), or false to disable",
+});
+
+const JsonSchemaObject = Type.Unsafe({
+	type: "object",
+	additionalProperties: true,
+	description: "JSON Schema object for strict structured output. Non-object roots are rejected.",
+});
+
+const AcceptanceOverride = Type.Unsafe({
+	anyOf: [
+		{ type: "string", enum: ["auto", "none", "attested", "checked", "verified", "reviewed"] },
+		{ type: "boolean", enum: [false] },
+		{ type: "object", additionalProperties: true },
+	],
+	description: "Optional acceptance policy. Omitted means auto-inferred; verified requires configured runtime commands.",
+});
+
+const TaskItem = Type.Object({
+	agent: Type.String(), 
+	task: Type.String(), 
+	cwd: Type.Optional(Type.String()),
+	count: Type.Optional(Type.Integer({ minimum: 1, description: "Repeat this parallel task N times with the same settings." })),
+	output: Type.Optional(OutputOverride),
+	outputMode: Type.Optional(OutputModeOverride),
+	reads: Type.Optional(ReadsOverride),
+	progress: Type.Optional(Type.Boolean({ description: "Enable progress.md tracking for this task" })),
+	model: Type.Optional(Type.String({ description: "Override model for this task (e.g. 'google/gemini-3-pro')" })),
+	skill: Type.Optional(SkillOverride),
+	acceptance: Type.Optional(AcceptanceOverride),
+});
+
+// Parallel task item (within a parallel step)
+const ParallelTaskSchema = Type.Object({
+	agent: Type.String(),
+	task: Type.Optional(Type.String({ description: "Task template with {task}, {previous}, {chain_dir} variables. Defaults to {previous}." })),
+	phase: Type.Optional(Type.String({ description: "Optional phase/group label for status and graph rendering." })),
+	label: Type.Optional(Type.String({ description: "Optional user-facing label for this parallel task." })),
+	as: Type.Optional(Type.String({ description: "Optional safe identifier used as {outputs.name} in later chain steps." })),
+	outputSchema: Type.Optional(JsonSchemaObject),
+	cwd: Type.Optional(Type.String()),
+	count: Type.Optional(Type.Integer({ minimum: 1, description: "Repeat this parallel task N times with the same settings." })),
+	output: Type.Optional(OutputOverride),
+	outputMode: Type.Optional(OutputModeOverride),
+	reads: Type.Optional(ReadsOverride),
+	progress: Type.Optional(Type.Boolean({ description: "Enable progress.md tracking in {chain_dir}" })),
+	skill: Type.Optional(SkillOverride),
+	model: Type.Optional(Type.String({ description: "Override model for this task" })),
+	acceptance: Type.Optional(AcceptanceOverride),
+});
+
+const DynamicExpandSchema = Type.Object({
+	from: Type.Object({
+		output: Type.String({ description: "Prior named structured output to expand from." }),
+		path: Type.String({ description: "JSON Pointer into the structured output, e.g. /items." }),
+	}, { additionalProperties: false }),
+	item: Type.Optional(Type.String({ description: "Template variable name for each item. Defaults to item." })),
+	key: Type.Optional(Type.String({ description: "JSON Pointer relative to each item for stable child ids." })),
+	maxItems: Type.Optional(Type.Integer({ minimum: 0, description: "Required fanout bound unless configured globally." })),
+	onEmpty: Type.Optional(Type.String({ enum: ["skip", "fail"], description: "Empty input behavior. Defaults to skip." })),
+}, { additionalProperties: false });
+
+const DynamicParallelTemplateSchema = Type.Object({
+	agent: Type.String(),
+	task: Type.Optional(Type.String({ description: "Task template with {item}, {item.path}, {task}, {previous}, {chain_dir}, and {outputs.name} variables." })),
+	phase: Type.Optional(Type.String({ description: "Optional phase/group label for status and graph rendering." })),
+	label: Type.Optional(Type.String({ description: "Optional user-facing label; item templates are supported." })),
+	outputSchema: Type.Optional(JsonSchemaObject),
+	cwd: Type.Optional(Type.String()),
+	output: Type.Optional(OutputOverride),
+	outputMode: Type.Optional(OutputModeOverride),
+	reads: Type.Optional(ReadsOverride),
+	progress: Type.Optional(Type.Boolean({ description: "Enable progress.md tracking in {chain_dir}" })),
+	skill: Type.Optional(SkillOverride),
+	model: Type.Optional(Type.String({ description: "Override model for this task" })),
+	acceptance: Type.Optional(AcceptanceOverride),
+}, { additionalProperties: false });
+
+const DynamicCollectSchema = Type.Object({
+	as: Type.String({ description: "Safe output name for the ordered collected result array." }),
+	outputSchema: Type.Optional(JsonSchemaObject),
+}, { additionalProperties: false });
+
+// Flattened so chain steps do not need an object-shape anyOf/oneOf union.
+const ChainItem = Type.Object({
+	agent: Type.Optional(Type.String({ description: "Sequential step agent name" })),
+	task: Type.Optional(Type.String({
+		description: "Task template with variables: {task}=original request, {previous}=prior step's text response, {chain_dir}=shared folder, {outputs.name}=prior named output. Required for first step, defaults to '{previous}' for subsequent steps."
+	})),
+	phase: Type.Optional(Type.String({ description: "Optional phase/group label for status and graph rendering." })),
+	label: Type.Optional(Type.String({ description: "Optional user-facing label for this chain step." })),
+	as: Type.Optional(Type.String({ description: "Optional safe identifier used as {outputs.name} in later chain steps." })),
+	outputSchema: Type.Optional(JsonSchemaObject),
+	cwd: Type.Optional(Type.String()),
+	output: Type.Optional(OutputOverride),
+	outputMode: Type.Optional(OutputModeOverride),
+	reads: Type.Optional(ReadsOverride),
+	progress: Type.Optional(Type.Boolean({ description: "Enable progress.md tracking in {chain_dir}" })),
+	skill: Type.Optional(SkillOverride),
+	model: Type.Optional(Type.String({ description: "Override model for this step" })),
+	acceptance: Type.Optional(AcceptanceOverride),
+	parallel: Type.Optional(Type.Unsafe({
+		anyOf: [
+			Type.Array(ParallelTaskSchema, { minItems: 1, description: "Tasks to run in parallel" }),
+			DynamicParallelTemplateSchema,
+		],
+		description: "Static parallel tasks array, or a single dynamic fanout child template when expand/collect are present.",
+	})),
+	expand: Type.Optional(DynamicExpandSchema),
+	collect: Type.Optional(DynamicCollectSchema),
+	concurrency: Type.Optional(Type.Number({ description: "Max concurrent tasks (default: 4)" })),
+	failFast: Type.Optional(Type.Boolean({ description: "Stop on first failure (default: false)" })),
+	worktree: Type.Optional(Type.Boolean({
+		description: "Create isolated git worktrees for each parallel task."
+	})),
+}, {
+	description: "Chain step: use {agent, task?, ...} for sequential, {parallel: [...]} for static concurrent execution, or {expand, parallel: {...}, collect} for dynamic fanout.",
+	additionalProperties: false,
+});
+
+const ControlOverrides = Type.Object({
+	enabled: Type.Optional(Type.Boolean({ description: "Enable/disable subagent control attention tracking for this run" })),
+	needsAttentionAfterMs: Type.Optional(Type.Integer({ minimum: 1, description: "No-observed-activity window before a run needs attention" })),
+	activeNoticeAfterMs: Type.Optional(Type.Integer({ minimum: 1, description: "Active-long-running notice threshold by elapsed ms (default: 240000)" })),
+	activeNoticeAfterTurns: Type.Optional(Type.Integer({ minimum: 1, description: "Optional active-long-running notice threshold by assistant turns (disabled by default)" })),
+	activeNoticeAfterTokens: Type.Optional(Type.Integer({ minimum: 1, description: "Optional active-long-running notice threshold by total tokens (disabled by default)" })),
+	failedToolAttemptsBeforeAttention: Type.Optional(Type.Integer({ minimum: 1, description: "Consecutive mutating-tool failures before escalating to needs_attention (default: 3)" })),
+	notifyOn: Type.Optional(Type.Array(Type.String({ enum: ["active_long_running", "needs_attention"] }), {
+		description: "Control event types that should notify the parent/orchestrator. Defaults to active_long_running and needs_attention.",
+	})),
+	notifyChannels: Type.Optional(Type.Array(Type.String({ enum: ["event", "async", "intercom"] }), {
+		description: "Notification channels to use when available. Defaults to event, async, and intercom.",
+	})),
+});
+
+const SubagentParamsSchema = Type.Object({
+	agent: Type.Optional(Type.String({ description: "Agent name (SINGLE mode) or target for management get/update/delete" })),
+	task: Type.Optional(Type.String({ description: "Task (SINGLE mode, optional for self-contained agents)" })),
+	// Management action (when present, tool operates in management mode)
+	action: Type.Optional(Type.String({
+		enum: [...SUBAGENT_ACTIONS],
+		description: "Management/control action. Omit for execution mode."
+	})),
+	id: Type.Optional(Type.String({
+		description: "Run id or prefix for action='status', action='interrupt', action='resume', or action='append-step'."
+	})),
+	runId: Type.Optional(Type.String({
+		description: "Target run ID for action='interrupt', action='resume', or action='append-step'. Defaults to the most recently active controllable run for interrupt. Prefer id for new calls."
+	})),
+	dir: Type.Optional(Type.String({
+		description: "Async run directory for action='status' or action='resume'."
+	})),
+	index: Type.Optional(Type.Integer({ minimum: 0, description: "Zero-based child index for actions that target a specific child." })),
+	message: Type.Optional(Type.String({ description: "Follow-up message for action='resume'. Use index to choose a child from multi-child runs." })),
+	// Chain identifier for management (can't reuse 'chain' — that's the execution array)
+	chainName: Type.Optional(Type.String({
+		description: "Chain name for get/update/delete management actions"
+	})),
+	// Agent/chain configuration for create/update (nested to avoid conflicts with execution fields)
+	config: Type.Optional(Type.Unsafe({
+		anyOf: [
+			{ type: "object", additionalProperties: true },
+			{ type: "string" },
+		],
+		description: "Agent/chain config for create/update. Object or JSON string; presence of steps creates a chain."
+	})),
+	tasks: Type.Optional(Type.Array(TaskItem, { description: "PARALLEL mode: [{agent, task, count?, output?, outputMode?, reads?, progress?}, ...]" })),
+	concurrency: Type.Optional(Type.Integer({ minimum: 1, description: "Top-level PARALLEL mode only: max concurrent tasks. Defaults to config.parallel.concurrency or 4." })),
+	worktree: Type.Optional(Type.Boolean({
+		description: "Create isolated git worktrees for parallel tasks; requires clean git state."
+	})),
+	chain: Type.Optional(Type.Array(ChainItem, { description: "CHAIN mode: sequential steps; each result becomes {previous}. append-step takes one tail step and may use {chain_dir}/{outputs.name}." })),
+	context: Type.Optional(Type.String({
+		enum: ["fresh", "fork"],
+		description: "'fresh' or 'fork' to branch from parent session. Explicit context overrides every child in the invocation. If omitted, each requested agent uses its own defaultContext; agents without defaultContext: 'fork' run fresh.",
+	})),
+	chainDir: Type.Optional(Type.String({ description: "Persistent chain artifact directory; defaults to user-scoped temp storage." })),
+	async: Type.Optional(Type.Boolean({ description: "Run in background (default: false, or per config)" })),
+	timeoutMs: Type.Optional(Type.Integer({ minimum: 1, description: "Optional run-level timeout in ms for foreground and async/background runs. Alias of maxRuntimeMs." })),
+	maxRuntimeMs: Type.Optional(Type.Integer({ minimum: 1, description: "Alias of timeoutMs for optional run-level timeout in foreground and async/background runs." })),
+	agentScope: Type.Optional(Type.String({ description: "Agent discovery scope: 'user', 'project', or 'both' (default: 'both'; project wins on name collisions)" })),
+	cwd: Type.Optional(Type.String()),
+	artifacts: Type.Optional(Type.Boolean({ description: "Write debug artifacts (default: true)" })),
+	includeProgress: Type.Optional(Type.Boolean({ description: "Include full progress in result (default: false)" })),
+	share: Type.Optional(Type.Boolean({ description: "Upload session to GitHub Gist for sharing (default: false)" })),
+	sessionDir: Type.Optional(
+		Type.String({ description: "Directory to store session logs (default: temp; enables sessions even if share=false)" }),
+	),
+	// Clarification TUI
+	clarify: Type.Optional(Type.Boolean({ description: "Show TUI to preview/edit before execution. Explicit clarify: true keeps the run foreground for the clarify UI; omitted clarify can still run in the background when async: true is set." })),
+	control: Type.Optional(ControlOverrides),
+	// Solo agent overrides
+	output: Type.Optional(Type.Unsafe({
+		anyOf: [
+			{ type: "string" },
+			{ type: "boolean" },
+		],
+		description: "Output file for single agent (string), or false to disable. Relative paths resolve against cwd.",
+	})),
+	outputMode: Type.Optional(OutputModeOverride),
+	skill: Type.Optional(SkillOverride),
+	model: Type.Optional(Type.String({ description: "Override model for single agent (e.g. 'anthropic/claude-sonnet-4')" })),
+	acceptance: Type.Optional(AcceptanceOverride),
+});
+
+export const SubagentParams = keepTopLevelParameterDescriptions(SubagentParamsSchema);

package/node_modules/pi-subagents/src/intercom/intercom-bridge.ts

@@ -0,0 +1,412 @@
+import { execSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { AgentConfig } from "../agents/agents.ts";
+import type { ExtensionConfig, IntercomBridgeConfig, IntercomBridgeMode } from "../shared/types.ts";
+import { getAgentDir, getProjectConfigDir } from "../shared/utils.ts";
+
+const PI_INTERCOM_PACKAGE_NAME = "pi-intercom";
+
+function defaultAgentDir(): string {
+	return getAgentDir();
+}
+
+function defaultIntercomExtensionDir(agentDir = defaultAgentDir()): string {
+	return path.join(agentDir, "extensions", PI_INTERCOM_PACKAGE_NAME);
+}
+
+export const INTERCOM_EXTENSION_DIR_ENV = "PI_INTERCOM_EXTENSION_DIR";
+
+// Launcher-provided override for the pi-intercom package directory. Lets a hermetic
+// wrapper point the subagent intercom bridge at a read-only install (e.g. a Nix-store
+// path) instead of seeding the package into the writable agent dir.
+function envIntercomExtensionDir(): string | undefined {
+	const dir = process.env[INTERCOM_EXTENSION_DIR_ENV]?.trim();
+	return dir ? dir : undefined;
+}
+
+function defaultIntercomConfigPath(agentDir = defaultAgentDir()): string {
+	return path.join(agentDir, "intercom", "config.json");
+}
+
+function defaultSubagentConfigDir(agentDir = defaultAgentDir()): string {
+	return path.join(agentDir, "extensions", "subagent");
+}
+
+const DEFAULT_INTERCOM_TARGET_PREFIX = "subagent-chat";
+export const INTERCOM_BRIDGE_MARKER = "Intercom orchestration channel:";
+const DEFAULT_INTERCOM_BRIDGE_TEMPLATE = `The inherited thread is reference-only. Do not continue that conversation or send questions, status updates, or completion handoffs to the supervisor in normal assistant text.
+
+Use contact_supervisor first. It resolves the supervisor session "{orchestratorTarget}" and run metadata automatically.
+- Need a decision, blocked, approval, or product/API/scope ambiguity: contact_supervisor({ reason: "need_decision", message: "<question>" })
+- After contact_supervisor with reason "need_decision", stay alive and continue only after the reply arrives. Do not finish your final response with a choose-one question.
+- Do not ask for clarification when the only conflict is review-only/no-edit versus progress-writing or artifact-writing instructions. Review-only/no-edit wins; leave files unchanged and mention the conflict in your final result only if it matters.
+- Meaningful progress or unexpected discoveries that change the plan: contact_supervisor({ reason: "progress_update", message: "UPDATE: <summary>" })
+- Generic intercom is lower-level plumbing/fallback only: intercom({ action: "ask", to: "{orchestratorTarget}", message: "<question>" })
+
+Do not use contact_supervisor or intercom for routine completion handoffs. If no coordination is needed, return a focused task result.`;
+
+export interface IntercomBridgeState {
+	active: boolean;
+	mode: IntercomBridgeMode;
+	orchestratorTarget?: string;
+	extensionDir: string;
+	instruction: string;
+}
+
+export interface IntercomBridgeDiagnostic {
+	active: boolean;
+	mode: IntercomBridgeMode;
+	wantsIntercom: boolean;
+	piIntercomAvailable: boolean;
+	extensionDir: string;
+	configPath?: string;
+	orchestratorTarget?: string;
+	reason?: string;
+	intercomConfigEnabled?: boolean;
+	intercomConfigError?: string;
+}
+
+interface ResolveIntercomBridgeInput {
+	config: ExtensionConfig["intercomBridge"];
+	context: "fresh" | "fork" | undefined;
+	orchestratorTarget?: string;
+	extensionDir?: string;
+	configPath?: string;
+	settingsDir?: string;
+	cwd?: string;
+	agentDir?: string;
+	globalNpmRoot?: string | null;
+}
+
+export function resolveIntercomSessionTarget(sessionName: string | undefined, sessionId: string): string {
+	const trimmedName = sessionName?.trim();
+	if (trimmedName) return trimmedName;
+	const normalizedSessionId = sessionId.startsWith("session-") ? sessionId.slice("session-".length) : sessionId;
+	return `${DEFAULT_INTERCOM_TARGET_PREFIX}-${normalizedSessionId.slice(0, 8)}`;
+}
+
+function sanitizeIntercomTargetPart(value: string): string {
+	return value.trim().toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "") || "agent";
+}
+
+export function resolveSubagentIntercomTarget(runId: string, agent: string, index?: number): string {
+	const stepSuffix = index !== undefined ? `-${index + 1}` : "";
+	return `subagent-${sanitizeIntercomTargetPart(agent)}-${sanitizeIntercomTargetPart(runId)}${stepSuffix}`;
+}
+
+export function resolveIntercomBridgeMode(value: unknown): IntercomBridgeMode {
+	if (value === "off" || value === "always" || value === "fork-only") return value;
+	return "always";
+}
+
+function resolveIntercomBridgeConfig(value: ExtensionConfig["intercomBridge"]): Required<IntercomBridgeConfig> {
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		return {
+			mode: "always",
+			instructionFile: "",
+		};
+	}
+	return {
+		mode: resolveIntercomBridgeMode(value.mode),
+		instructionFile: typeof value.instructionFile === "string" ? value.instructionFile : "",
+	};
+}
+
+function intercomConfigStatus(configPath: string): { enabled: boolean; error?: unknown } {
+	if (!fs.existsSync(configPath)) return { enabled: true };
+	try {
+		const parsed = JSON.parse(fs.readFileSync(configPath, "utf-8")) as { enabled?: unknown };
+		return { enabled: parsed.enabled !== false };
+	} catch (error) {
+		return { enabled: true, error };
+	}
+}
+
+function readJsonBestEffort(filePath: string): unknown {
+	try {
+		return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+	} catch (error) {
+		const code = error && typeof error === "object" && "code" in error ? (error as NodeJS.ErrnoException).code : undefined;
+		if (code !== "ENOENT") console.warn(`Failed to read JSON from '${filePath}'.`, error);
+		return null;
+	}
+}
+
+function packageHasPiExtension(packageRoot: string): boolean {
+	if (!fs.existsSync(packageRoot)) return false;
+	const pkg = readJsonBestEffort(path.join(packageRoot, "package.json"));
+	if (pkg && typeof pkg === "object" && !Array.isArray(pkg)) {
+		const pi = (pkg as { pi?: unknown }).pi;
+		if (pi && typeof pi === "object" && !Array.isArray(pi)) {
+			const extensions = (pi as { extensions?: unknown }).extensions;
+			return Array.isArray(extensions) && extensions.some((entry) => typeof entry === "string" && entry.trim() !== "");
+		}
+	}
+	return fs.existsSync(path.join(packageRoot, "extensions"));
+}
+
+function isSafePackagePath(value: string): boolean {
+	return value.length > 0
+		&& !path.isAbsolute(value)
+		&& value.split(/[\\/]/).every((part) => part.length > 0 && part !== "." && part !== "..");
+}
+
+function parseNpmPackageName(source: string): string | undefined {
+	const spec = source.slice(4).trim();
+	if (!spec) return undefined;
+	const match = spec.match(/^(@?[^@]+(?:\/[^@]+)?)(?:@(.+))?$/);
+	const packageName = match?.[1] ?? spec;
+	return isSafePackagePath(packageName) ? packageName : undefined;
+}
+
+function packageEntrySource(entry: unknown): string | undefined {
+	if (typeof entry === "string") return entry;
+	if (entry && typeof entry === "object" && !Array.isArray(entry) && typeof (entry as { source?: unknown }).source === "string") {
+		return (entry as { source: string }).source;
+	}
+	return undefined;
+}
+
+function packageEntryAllowsExtensions(entry: unknown): boolean {
+	if (!entry || typeof entry !== "object" || Array.isArray(entry)) return true;
+	const extensions = (entry as { extensions?: unknown }).extensions;
+	return !Array.isArray(extensions) || extensions.length > 0;
+}
+
+function findNearestProjectConfigDir(cwd: string): string | undefined {
+	let current = path.resolve(cwd);
+	while (true) {
+		const configDir = getProjectConfigDir(current);
+		if (fs.existsSync(path.join(configDir, "settings.json"))) return configDir;
+		const parent = path.dirname(current);
+		if (parent === current) return undefined;
+		current = parent;
+	}
+}
+
+let cachedGlobalNpmRoot: string | null | undefined;
+
+function getGlobalNpmRoot(): string | null {
+	if (cachedGlobalNpmRoot !== undefined) return cachedGlobalNpmRoot;
+	try {
+		cachedGlobalNpmRoot = execSync("npm root -g", { encoding: "utf-8", timeout: 5000 }).trim();
+		return cachedGlobalNpmRoot;
+	} catch {
+		cachedGlobalNpmRoot = null;
+		return null;
+	}
+}
+
+function tmpNpmIntercomPackageDir(agentDir: string): string | undefined {
+	const tmpNpmDir = path.join(agentDir, "tmp", "extensions", "npm");
+	try {
+		const entries = fs.readdirSync(tmpNpmDir, { withFileTypes: true });
+		for (const entry of entries) {
+			if (!entry.isDirectory()) continue;
+			const pkgDir = path.join(tmpNpmDir, entry.name, "node_modules", PI_INTERCOM_PACKAGE_NAME);
+			if (fs.existsSync(pkgDir) && packageHasPiExtension(pkgDir)) {
+				return path.resolve(pkgDir);
+			}
+		}
+	} catch {
+		// ignore ENOTDIR, ENOENT, permission errors
+	}
+	return undefined;
+}
+
+function configuredPiIntercomPackageDir(input: ResolveIntercomBridgeInput, agentDir: string): string | undefined {
+	const projectConfigDir = input.cwd ? findNearestProjectConfigDir(path.resolve(input.cwd)) : undefined;
+	const settingsFiles = [
+		...(projectConfigDir ? [{ file: path.join(projectConfigDir, "settings.json"), configDir: projectConfigDir, scope: "project" as const }] : []),
+		{ file: path.join(agentDir, "settings.json"), configDir: agentDir, scope: "user" as const },
+	];
+	const globalNpmRoot = input.globalNpmRoot === undefined ? getGlobalNpmRoot() : input.globalNpmRoot;
+
+	for (const { file, configDir, scope } of settingsFiles) {
+		const settings = readJsonBestEffort(file);
+		if (!settings || typeof settings !== "object" || Array.isArray(settings)) continue;
+		const packages = (settings as { packages?: unknown }).packages;
+		if (!Array.isArray(packages)) continue;
+
+		for (const entry of packages) {
+			if (!packageEntryAllowsExtensions(entry)) continue;
+			const source = packageEntrySource(entry)?.trim();
+			if (!source?.startsWith("npm:")) continue;
+			const packageName = parseNpmPackageName(source);
+			if (packageName !== PI_INTERCOM_PACKAGE_NAME) continue;
+			const candidates = scope === "project"
+				? [path.join(configDir, "npm", "node_modules", packageName)]
+				: [
+					...(globalNpmRoot ? [path.join(globalNpmRoot, packageName)] : []),
+					path.join(agentDir, "npm", "node_modules", packageName),
+				];
+			const packageRoot = candidates.find(packageHasPiExtension);
+			if (packageRoot) return path.resolve(packageRoot);
+		}
+	}
+	return undefined;
+}
+
+function resolveIntercomExtensionDir(input: ResolveIntercomBridgeInput, agentDir: string): string {
+	const legacyDir = path.resolve(input.extensionDir ?? envIntercomExtensionDir() ?? defaultIntercomExtensionDir(agentDir));
+	if (fs.existsSync(legacyDir)) return legacyDir;
+
+	const configured = configuredPiIntercomPackageDir(input, agentDir);
+	if (configured) return configured;
+
+	const tmpDir = tmpNpmIntercomPackageDir(agentDir);
+	if (tmpDir) return tmpDir;
+
+	return legacyDir;
+}
+
+function extensionSandboxAllowsIntercom(extensions: string[] | undefined, extensionDir: string): boolean {
+	if (extensions === undefined) return true;
+
+	const intercomDir = path.resolve(extensionDir).replaceAll("\\", "/").toLowerCase();
+	for (const entry of extensions) {
+		const normalized = entry.trim().replaceAll("\\", "/").toLowerCase();
+		if (normalized === "pi-intercom") return true;
+		if (normalized === intercomDir) return true;
+		if (normalized.startsWith(`${intercomDir}/`)) return true;
+		if (normalized.endsWith("/pi-intercom")) return true;
+		if (normalized.includes("/pi-intercom/")) return true;
+	}
+	return false;
+}
+
+function expandTilde(filePath: string): string {
+	return filePath.startsWith("~/") ? path.join(os.homedir(), filePath.slice(2)) : filePath;
+}
+
+function resolveInstructionTemplate(instructionFile: string, settingsDir: string): string {
+	if (!instructionFile) return DEFAULT_INTERCOM_BRIDGE_TEMPLATE;
+	const expandedPath = expandTilde(instructionFile);
+	const resolvedPath = path.isAbsolute(expandedPath)
+		? expandedPath
+		: path.resolve(settingsDir, expandedPath);
+	try {
+		return fs.readFileSync(resolvedPath, "utf-8");
+	} catch (error) {
+		console.warn(`Failed to read intercom bridge instructionFile at '${resolvedPath}'. Using default instructions.`, error);
+		return DEFAULT_INTERCOM_BRIDGE_TEMPLATE;
+	}
+}
+
+function buildIntercomBridgeInstruction(orchestratorTarget: string, template: string): string {
+	const instruction = template.replaceAll("{orchestratorTarget}", orchestratorTarget).trim();
+	if (instruction.startsWith(INTERCOM_BRIDGE_MARKER)) return instruction;
+	return `${INTERCOM_BRIDGE_MARKER}
+${instruction}`;
+}
+
+export function diagnoseIntercomBridge(input: ResolveIntercomBridgeInput): IntercomBridgeDiagnostic {
+	const config = resolveIntercomBridgeConfig(input.config);
+	const mode = config.mode;
+	const agentDir = path.resolve(input.agentDir ?? defaultAgentDir());
+	const extensionDir = resolveIntercomExtensionDir(input, agentDir);
+	const orchestratorTarget = input.orchestratorTarget?.trim();
+	const configPath = path.resolve(input.configPath ?? defaultIntercomConfigPath(agentDir));
+	const wantsIntercom = mode !== "off" && !(mode === "fork-only" && input.context !== "fork");
+	const piIntercomAvailable = fs.existsSync(extensionDir);
+	let configStatus: ReturnType<typeof intercomConfigStatus> | undefined;
+	let reason: string | undefined;
+	if (mode === "off") reason = "bridge mode is off";
+	else if (mode === "fork-only" && input.context !== "fork") reason = "bridge mode is fork-only and context is not fork";
+	else if (!orchestratorTarget) reason = "orchestrator target is not available";
+	else if (!piIntercomAvailable) reason = "pi-intercom extension was not found";
+	else {
+		configStatus = intercomConfigStatus(configPath);
+		if (!configStatus.enabled) reason = "intercom config is disabled";
+	}
+	let intercomConfigError: string | undefined;
+	if (configStatus?.error) {
+		const error = configStatus.error;
+		intercomConfigError = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+	}
+
+	return {
+		active: reason === undefined,
+		mode,
+		wantsIntercom,
+		piIntercomAvailable,
+		extensionDir,
+		configPath,
+		...(orchestratorTarget ? { orchestratorTarget } : {}),
+		...(reason ? { reason } : {}),
+		...(configStatus ? { intercomConfigEnabled: configStatus.enabled } : {}),
+		...(intercomConfigError ? { intercomConfigError } : {}),
+	};
+}
+
+export function resolveIntercomBridge(input: ResolveIntercomBridgeInput): IntercomBridgeState {
+	const config = resolveIntercomBridgeConfig(input.config);
+	const mode = config.mode;
+	const agentDir = path.resolve(input.agentDir ?? defaultAgentDir());
+	const extensionDir = resolveIntercomExtensionDir(input, agentDir);
+	const orchestratorTarget = input.orchestratorTarget?.trim();
+	const settingsDir = path.resolve(input.settingsDir ?? defaultSubagentConfigDir(agentDir));
+	const defaultInstruction = buildIntercomBridgeInstruction(
+		orchestratorTarget || "{orchestratorTarget}",
+		DEFAULT_INTERCOM_BRIDGE_TEMPLATE,
+	);
+
+	if (mode === "off") {
+		return { active: false, mode, extensionDir, instruction: defaultInstruction };
+	}
+	if (mode === "fork-only" && input.context !== "fork") {
+		return { active: false, mode, extensionDir, instruction: defaultInstruction };
+	}
+	if (!orchestratorTarget) {
+		return { active: false, mode, extensionDir, instruction: defaultInstruction };
+	}
+	if (!fs.existsSync(extensionDir)) {
+		return { active: false, mode, extensionDir, instruction: defaultInstruction };
+	}
+
+	const configPath = path.resolve(input.configPath ?? defaultIntercomConfigPath(agentDir));
+	const intercomStatus = intercomConfigStatus(configPath);
+	if (intercomStatus.error) console.warn(`Failed to parse intercom config at '${configPath}'. Assuming enabled.`, intercomStatus.error);
+	if (!intercomStatus.enabled) {
+		return { active: false, mode, extensionDir, instruction: defaultInstruction };
+	}
+
+	const instruction = buildIntercomBridgeInstruction(
+		orchestratorTarget,
+		resolveInstructionTemplate(config.instructionFile, settingsDir),
+	);
+
+	return {
+		active: true,
+		mode,
+		orchestratorTarget,
+		extensionDir,
+		instruction,
+	};
+}
+
+export function applyIntercomBridgeToAgent(agent: AgentConfig, bridge: IntercomBridgeState): AgentConfig {
+	if (!bridge.active || !bridge.orchestratorTarget) return agent;
+	if (!extensionSandboxAllowsIntercom(agent.extensions, bridge.extensionDir)) return agent;
+
+	const bridgeTools = ["intercom", "contact_supervisor"];
+	const tools = agent.tools
+		? [...agent.tools, ...bridgeTools.filter((tool) => !agent.tools?.includes(tool))]
+		: agent.tools;
+	const instruction = bridge.instruction;
+	const trimmedPrompt = agent.systemPrompt?.trim() || "";
+	const systemPrompt = trimmedPrompt.includes(INTERCOM_BRIDGE_MARKER)
+		? trimmedPrompt
+		: trimmedPrompt
+			? `${trimmedPrompt}\n\n${instruction}`
+			: instruction;
+
+	if (tools === agent.tools && systemPrompt === agent.systemPrompt) return agent;
+	return {
+		...agent,
+		tools,
+		systemPrompt,
+	};
+}