/**
 * inter-agent-pi
 * Pi extension for connecting to the inter-agent message bus
 *
 * Provides commands and tools to send, broadcast, list sessions, check status,
 * inspect local identity, and receive incoming messages as Pi notifications.
 *
 * Installation:
 * ```bash
 * pi install npm:@arcanemachine/inter-agent-pi
 * ```
 *
 * Or load directly from the source checkout:
 * ```bash
 * pi -e /path/to/inter-agent-pi
 * ```
 */

import type {
  ContextEvent,
  ExtensionAPI,
  ExtensionCommandContext,
  ExtensionContext,
  Theme,
} from "@earendil-works/pi-coding-agent";
import type { AutocompleteItem, Component } from "@earendil-works/pi-tui";
import { Box, Container, Spacer, Text } from "@earendil-works/pi-tui";
import { Type } from "typebox";
import { spawn, ChildProcess } from "node:child_process";

type PiCommandInfo = ReturnType<ExtensionAPI["getCommands"]>[number];
type PiSourceInfo = PiCommandInfo["sourceInfo"];

function samePiSource(left: PiSourceInfo, right: PiSourceInfo): boolean {
  return (
    left.source === right.source &&
    left.scope === right.scope &&
    left.origin === right.origin &&
    left.baseDir === right.baseDir
  );
}

// Test seam: production uses Node's `spawn`; behavior tests inject a fake
// factory to drive listener stdout without a real bus. Keep the default so the
// real runtime is unchanged.
let spawnChildProcess: typeof spawn = spawn;

/** @internal Replace the child process factory for behavior tests. */
export function _setSpawnForTest(impl: typeof spawn | null): void {
  spawnChildProcess = impl ?? spawn;
}

// Test seam: production resolves a process-global one-use carrier; behavior
// tests inject a fake carrier so reload lifecycle cases stay hermetic.
let reloadCarrierOverride: ReloadHandoffCarrier | null = null;
const defaultProcessCarrier = createProcessGlobalHandoffCarrier();

function resolveReloadCarrier(): ReloadHandoffCarrier {
  return reloadCarrierOverride ?? defaultProcessCarrier;
}

/** @internal Replace the reload handoff carrier for behavior tests. */
export function _setReloadCarrierForTest(
  carrier: ReloadHandoffCarrier | null,
): void {
  reloadCarrierOverride = carrier;
}
import {
  accessSync,
  constants,
  existsSync,
  lstatSync,
  readFileSync,
  realpathSync,
} from "node:fs";
import { homedir } from "node:os";
import {
  delimiter,
  dirname,
  isAbsolute,
  join,
  relative,
  resolve,
} from "node:path";

import {
  MAILBOX_MAX_UNREAD,
  MAILBOX_NOTICE_DEBOUNCE_MS_DEFAULT,
  MailboxDispatcher,
  buildNoticeCompact,
  buildNoticeExpanded,
  createProcessGlobalHandoffCarrier,
  deriveInboundMetadata,
  describeDestination,
  effectiveDeliveryMode,
  effectiveDebounceMs,
  isValidDebounceMs,
  isValidDeliveryMode,
} from "./mailbox.js";
import type {
  InboundImmediateMessage,
  MailboxSnapshot,
  ReloadHandoffCarrier,
} from "./mailbox.js";

import {
  ControlController,
  ControlEngine,
  CONTROL_CUSTOM_TYPE,
} from "./control.js";
import type {
  ControlControllerHost,
  ControlHost,
  ControlResponse,
  ControlToolResult,
  ControlWireRequest,
} from "./control.js";

// ── Configuration ───────────────────────────────────────────────────────────

interface InterAgentConfig {
  projectPaths?: string[];
  projectPathsExplicit?: boolean;
  projectPathsError?: string;
  host?: string;
  port?: number | string;
  dataDir?: string;
  secret?: string;
  tls?: boolean | string;
  tlsCert?: string;
  tlsKey?: string;
  deliveryMode?: string;
  mailboxNoticeDebounceMs?: number;
}

interface RawInterAgentConfig extends Omit<
  InterAgentConfig,
  "projectPaths" | "projectPathsExplicit" | "projectPathsError"
> {
  projectPaths?: unknown;
  projectPath?: unknown;
}

interface Settings {
  interAgent?: RawInterAgentConfig;
}

function managedRuntimeVenv(): string {
  return join(homedir(), ".pi", "agent", "inter-agent", "venv");
}

const RUNTIME_SETUP_DOCS = "README.md";
const SETUP_PYTHON_ENV = "INTER_AGENT_PI_SETUP_PYTHON";
const SETUP_SOURCE_ENV = "INTER_AGENT_PI_SETUP_SOURCE";
const SETUP_HELPER_REQUIREMENT = "inter-agent-pi~=0.3.1";
const SETUP_OUTPUT_MAX_BYTES = 8 * 1024;
const SETUP_PROCESS_TIMEOUT_MS = 120_000;
const PROJECT_PATHS_CONFIG_ERROR =
  "interAgent.projectPaths must be a non-empty list of non-empty strings";
const LEGACY_PROJECT_PATH_ERROR =
  "interAgent.projectPath is no longer supported; use interAgent.projectPaths with a list of checkout paths";

function expandHome(path: string): string {
  if (path === "~") return homedir();
  if (path.startsWith("~/")) return join(homedir(), path.slice(2));
  return path;
}

function resolvePathOption(path: string | undefined, baseDir: string) {
  if (!path) return path;
  const expanded = expandHome(path);
  return isAbsolute(expanded) ? expanded : resolve(baseDir, expanded);
}

function resolveProjectPaths(
  value: unknown,
  baseDir: string,
): { paths?: string[]; error?: string } {
  if (
    !Array.isArray(value) ||
    value.length === 0 ||
    !value.every(
      (candidate): candidate is string =>
        typeof candidate === "string" && candidate.trim().length > 0,
    )
  ) {
    return { error: PROJECT_PATHS_CONFIG_ERROR };
  }

  return {
    paths: value.map((candidate) => resolvePathOption(candidate, baseDir)!),
  };
}

function resolveConfigPaths(
  config: RawInterAgentConfig,
  settingsPath: string,
): InterAgentConfig {
  const baseDir = dirname(settingsPath);
  const {
    projectPath: _legacyProjectPath,
    projectPaths: rawProjectPaths,
    ...rest
  } = config;
  const resolved: InterAgentConfig = { ...rest };
  if (Object.prototype.hasOwnProperty.call(config, "dataDir")) {
    resolved.dataDir = resolvePathOption(config.dataDir, baseDir);
  }
  if (Object.prototype.hasOwnProperty.call(config, "tlsCert")) {
    resolved.tlsCert = resolvePathOption(config.tlsCert, baseDir);
  }
  if (Object.prototype.hasOwnProperty.call(config, "tlsKey")) {
    resolved.tlsKey = resolvePathOption(config.tlsKey, baseDir);
  }

  if (Object.prototype.hasOwnProperty.call(config, "projectPath")) {
    return {
      ...resolved,
      projectPaths: undefined,
      projectPathsError: LEGACY_PROJECT_PATH_ERROR,
    };
  }

  if (Object.prototype.hasOwnProperty.call(config, "projectPaths")) {
    const normalized = resolveProjectPaths(rawProjectPaths, baseDir);
    return {
      ...resolved,
      projectPaths: normalized.paths,
      projectPathsError: normalized.error,
    };
  }

  return resolved;
}

function mergeConfig(
  current: InterAgentConfig,
  next: RawInterAgentConfig,
  settingsPath: string,
): InterAgentConfig {
  const resolved = resolveConfigPaths(next, settingsPath);
  const hasProjectPaths = Object.prototype.hasOwnProperty.call(
    next,
    "projectPaths",
  );
  const hasLegacyProjectPath = Object.prototype.hasOwnProperty.call(
    next,
    "projectPath",
  );
  return {
    ...current,
    ...resolved,
    projectPathsExplicit:
      hasProjectPaths ||
      hasLegacyProjectPath ||
      current.projectPathsExplicit === true,
    projectPathsError:
      hasProjectPaths || hasLegacyProjectPath
        ? resolved.projectPathsError
        : current.projectPathsError,
  };
}

function loadConfig(): InterAgentConfig {
  const globalSettingsPath = join(homedir(), ".pi", "agent", "settings.json");
  const projectSettingsPath = join(process.cwd(), ".pi", "settings.json");

  let config: InterAgentConfig = {};

  // Load global settings first
  if (existsSync(globalSettingsPath)) {
    try {
      const parsed: Settings = JSON.parse(
        readFileSync(globalSettingsPath, "utf-8"),
      );
      if (parsed.interAgent) {
        config = mergeConfig(config, parsed.interAgent, globalSettingsPath);
      }
    } catch {
      // Invalid JSON, ignore
    }
  }

  // Project settings override global
  if (existsSync(projectSettingsPath)) {
    try {
      const parsed: Settings = JSON.parse(
        readFileSync(projectSettingsPath, "utf-8"),
      );
      if (parsed.interAgent) {
        config = mergeConfig(config, parsed.interAgent, projectSettingsPath);
      }
    } catch {
      // Invalid JSON, ignore
    }
  }

  return config;
}

type FailureRemedy = "setup" | "doctor";

interface InterAgentScripts {
  pi: string;
  connect: string;
  server: string;
  unavailableMessage?: string;
  unavailableRemedy?: FailureRemedy;
}

function isExecutable(path: string): boolean {
  try {
    accessSync(path, constants.X_OK);
    return true;
  } catch {
    return false;
  }
}

function scriptsFromBinDir(binDir: string): InterAgentScripts {
  return {
    pi: join(binDir, "inter-agent-pi"),
    connect: join(binDir, "inter-agent-connect"),
    server: join(binDir, "inter-agent-server"),
  };
}

function scriptsAvailable(scripts: InterAgentScripts): boolean {
  return [scripts.pi, scripts.connect, scripts.server].every(
    (script) => regularExecutable(script) && viableInterpreter(script),
  );
}

function regularExecutable(path: string): boolean {
  try {
    return lstatSync(path).isFile() && isExecutable(path);
  } catch {
    return false;
  }
}

function viableInterpreter(path: string): boolean {
  try {
    const firstLine = readFileSync(path, "utf8").split(/\r?\n/, 1)[0];
    if (!firstLine.startsWith("#!")) return false;
    const parts = firstLine.slice(2).trim().split(/\s+/).filter(Boolean);
    if (parts.length === 0) return false;
    if (parts[0] === "/usr/bin/env") {
      const interpreter = parts.slice(1).find((part) => !part.startsWith("-"));
      return interpreter ? findPathCommand(interpreter) !== null : false;
    }
    return isExecutable(parts[0]);
  } catch {
    return false;
  }
}

function managedHelpersUsable(): boolean {
  const scripts = scriptsFromBinDir(join(managedRuntimeVenv(), "bin"));
  return [scripts.pi, scripts.connect, scripts.server].every(
    (script) => regularExecutable(script) && viableInterpreter(script),
  );
}

type ManagedRuntimeState =
  | { kind: "missing" }
  | { kind: "healthy" }
  | { kind: "broken"; reason: string }
  | { kind: "unsafe"; reason: string };
type SafeManagedRuntimeState = Exclude<ManagedRuntimeState, { kind: "unsafe" }>;

function pathIsWithinHome(target: string): boolean {
  const home = resolve(homedir());
  if (target === resolve("/") || target === home) return false;
  const relativeTarget = relative(home, target);
  if (
    !relativeTarget ||
    relativeTarget.startsWith(`..${delimiter}`) ||
    relativeTarget === ".."
  ) {
    return false;
  }

  let existing = target;
  while (!existsSync(existing)) {
    const parent = dirname(existing);
    if (parent === existing) return false;
    existing = parent;
  }
  try {
    const realHome = realpathSync(home);
    const realExisting = realpathSync(existing);
    const realRelative = relative(realHome, realExisting);
    return (
      realRelative === "" ||
      (realRelative !== ".." &&
        !realRelative.startsWith(`..${delimiter}`) &&
        !isAbsolute(realRelative))
    );
  } catch {
    return false;
  }
}

function classifyManagedRuntime(): ManagedRuntimeState {
  const target = resolve(managedRuntimeVenv());
  if (!pathIsWithinHome(target)) {
    return { kind: "unsafe", reason: "managed environment path is unsafe" };
  }

  let targetStat;
  try {
    targetStat = lstatSync(target);
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
      return { kind: "missing" };
    }
    return {
      kind: "unsafe",
      reason: "managed environment cannot be inspected",
    };
  }
  if (targetStat.isSymbolicLink()) {
    return { kind: "unsafe", reason: "managed environment is a symlink" };
  }
  if (!targetStat.isDirectory()) {
    return { kind: "unsafe", reason: "managed environment is not a directory" };
  }

  const marker = join(target, "pyvenv.cfg");
  try {
    if (!lstatSync(marker).isFile()) {
      return {
        kind: "unsafe",
        reason: "managed environment is not a verified venv",
      };
    }
  } catch {
    return {
      kind: "unsafe",
      reason: "managed environment is not a verified venv",
    };
  }

  const python = join(target, "bin", "python");
  if (!isExecutable(python) || !managedHelpersUsable()) {
    return {
      kind: "broken",
      reason: "managed environment is incomplete or unusable",
    };
  }
  return { kind: "healthy" };
}

function setupPython(): string {
  return process.env[SETUP_PYTHON_ENV]?.trim() || "python3";
}

function setupSource(): string {
  return process.env[SETUP_SOURCE_ENV]?.trim() || SETUP_HELPER_REQUIREMENT;
}

function setupSourceDescription(): string {
  return process.env[SETUP_SOURCE_ENV]?.trim()
    ? `an explicit ${SETUP_SOURCE_ENV} override`
    : SETUP_HELPER_REQUIREMENT;
}

function setupOverrideWarning(config: InterAgentConfig): string | null {
  if (process.env.INTER_AGENT_PI_HELPER?.trim()) {
    return "INTER_AGENT_PI_HELPER remains higher precedence, so the managed environment is inactive while that override is configured; run /inter-agent doctor if this is unintended";
  }
  if (config.projectPathsExplicit) {
    return "configured interAgent.projectPaths remain higher precedence, so the managed environment is inactive while those paths are configured; run /inter-agent doctor if this is unintended";
  }
  return null;
}

function setupEnvironment(): NodeJS.ProcessEnv {
  const env: NodeJS.ProcessEnv = { ...process.env };
  for (const key of Object.keys(env)) {
    if (
      key === "PYTHONPATH" ||
      key === "PYTHONHOME" ||
      key === "VIRTUAL_ENV" ||
      key.startsWith("PIP_") ||
      key === "INTER_AGENT_SECRET" ||
      key === "INTER_AGENT_TLS_KEY" ||
      key === "INTER_AGENT_TLS_CERT"
    ) {
      delete env[key];
    }
  }
  env.PYTHONUNBUFFERED = "1";
  return env;
}

function findPathEntries(command: string): string[] {
  const entries: string[] = [];
  for (const dir of (process.env.PATH || "").split(delimiter)) {
    if (!dir) continue;
    const candidate = join(dir, command);
    if (existsSync(candidate)) entries.push(candidate);
  }
  return entries;
}

function findPathCommand(command: string): string | null {
  return (
    findPathEntries(command).find((candidate) => isExecutable(candidate)) ??
    null
  );
}

function pathScripts(): {
  scripts: InterAgentScripts | null;
  partial: boolean;
} {
  const entries = [
    findPathEntries("inter-agent-pi"),
    findPathEntries("inter-agent-connect"),
    findPathEntries("inter-agent-server"),
  ];
  const executable = entries.map(
    (candidates) =>
      candidates.find((candidate) => isExecutable(candidate)) ?? null,
  );
  const present = entries.filter((candidates) => candidates.length > 0).length;
  if (executable.every(Boolean)) {
    return {
      scripts: {
        pi: executable[0]!,
        connect: executable[1]!,
        server: executable[2]!,
      },
      partial: false,
    };
  }
  return { scripts: null, partial: present > 0 };
}

function missingConfiguredProjectPathsMessage(paths: string[]): string {
  const binDirs = paths.map((path) => join(path, ".venv", "bin"));
  return `inter-agent runtime was not found in configured projectPaths candidates: ${binDirs.join(", ")}. See ${RUNTIME_SETUP_DOCS}`;
}

function setupNeededMessage(): string {
  return `inter-agent managed runtime is not installed. See ${RUNTIME_SETUP_DOCS}`;
}

function getScripts(config: InterAgentConfig): InterAgentScripts {
  const helper = process.env.INTER_AGENT_PI_HELPER;
  if (helper) {
    const expanded = expandHome(helper);
    const scripts = scriptsFromBinDir(dirname(expanded));
    if (!scriptsAvailable(scripts) || expanded !== scripts.pi) {
      return {
        ...scripts,
        unavailableMessage: `inter-agent helper override is invalid at ${expanded}. See ${RUNTIME_SETUP_DOCS}`,
        unavailableRemedy: "doctor",
      };
    }
    return scripts;
  }

  if (config.projectPathsExplicit) {
    const managedScripts = scriptsFromBinDir(join(managedRuntimeVenv(), "bin"));
    if (config.projectPathsError) {
      return {
        ...managedScripts,
        unavailableMessage: `${config.projectPathsError}. See ${RUNTIME_SETUP_DOCS}`,
        unavailableRemedy: "doctor",
      };
    }

    const projectPaths = config.projectPaths ?? [];
    for (const projectPath of projectPaths) {
      const scripts = scriptsFromBinDir(join(projectPath, ".venv", "bin"));
      if (scriptsAvailable(scripts)) return scripts;
    }

    return {
      ...managedScripts,
      unavailableMessage: missingConfiguredProjectPathsMessage(projectPaths),
      unavailableRemedy: "doctor",
    };
  }

  const managedScripts = scriptsFromBinDir(join(managedRuntimeVenv(), "bin"));
  const managedState = classifyManagedRuntime();
  if (managedState.kind === "unsafe") {
    return {
      ...managedScripts,
      unavailableMessage: `${managedState.reason}. See ${RUNTIME_SETUP_DOCS}`,
      unavailableRemedy: "doctor",
    };
  }
  if (managedState.kind === "broken") {
    return {
      ...managedScripts,
      unavailableMessage: `${managedState.reason}. See ${RUNTIME_SETUP_DOCS}`,
      unavailableRemedy: "setup",
    };
  }
  if (managedState.kind === "healthy") return managedScripts;

  const fromPath = pathScripts();
  if (fromPath.scripts && scriptsAvailable(fromPath.scripts))
    return fromPath.scripts;
  if (fromPath.partial || fromPath.scripts) {
    return {
      ...managedScripts,
      unavailableMessage: "PATH inter-agent runtime is incomplete or unusable",
      unavailableRemedy: "doctor",
    };
  }

  return {
    ...managedScripts,
    unavailableMessage: setupNeededMessage(),
    unavailableRemedy: "setup",
  };
}

function interAgentEnv(
  config: InterAgentConfig = loadConfig(),
): NodeJS.ProcessEnv {
  const env: NodeJS.ProcessEnv = { ...process.env, PYTHONUNBUFFERED: "1" };
  if (config.host) env.INTER_AGENT_HOST = String(config.host);
  if (config.port !== undefined && config.port !== null) {
    env.INTER_AGENT_PORT = String(config.port);
  }
  if (config.dataDir) env.INTER_AGENT_DATA_DIR = config.dataDir;
  if (config.secret !== undefined)
    env.INTER_AGENT_SECRET = String(config.secret);
  if (config.tls !== undefined) env.INTER_AGENT_TLS = String(config.tls);
  if (config.tlsCert) env.INTER_AGENT_TLS_CERT = config.tlsCert;
  if (config.tlsKey) env.INTER_AGENT_TLS_KEY = config.tlsKey;
  return env;
}

// ── Constants ───────────────────────────────────────────────────────────────

const NOTIFY_MAX_LEN = 1000;
const DEFAULT_NAME = "pi";
const AUTO_STARTED_SERVER_IDLE_TIMEOUT_S = 300;
const SERVER_START_WAIT_ATTEMPTS = 30;
const SERVER_START_WAIT_MS = 500;
const LISTENER_STOP_SIGTERM_TIMEOUT_MS = 2000;
const LISTENER_STOP_SIGKILL_TIMEOUT_MS = 2000;
const CONTROL_HELPER_TIMEOUT_MS = 2500;
const CONTROL_HELPER_SIGKILL_GRACE_MS = 100;
const CONTROL_HELPER_MAX_STDOUT_BYTES = 64 * 1024;
const DOCTOR_SKILL_COMMAND = "skill:inter-agent-doctor";
// Test seam: behavior tests shorten the kill races so a hung-child failing stop
// exercise stays bounded; production keeps the real millisecond timeouts.
let stopTermTimeoutMs = LISTENER_STOP_SIGTERM_TIMEOUT_MS;
let stopKillTimeoutMs = LISTENER_STOP_SIGKILL_TIMEOUT_MS;
let controlHelperTimeoutMs = CONTROL_HELPER_TIMEOUT_MS;
let controlHelperSigkillGraceMs = CONTROL_HELPER_SIGKILL_GRACE_MS;

/** @internal Shorten the listener stop kill races for behavior tests. */
export function _setStopTimeoutsForTest(
  termMs: number | null,
  killMs: number | null,
): void {
  stopTermTimeoutMs = termMs ?? LISTENER_STOP_SIGTERM_TIMEOUT_MS;
  stopKillTimeoutMs = killMs ?? LISTENER_STOP_SIGKILL_TIMEOUT_MS;
}

/** @internal Shorten controller-helper timeout races for behavior tests. */
export function _setControlHelperTimeoutsForTest(
  timeoutMs: number | null,
  graceMs: number | null,
): void {
  controlHelperTimeoutMs = timeoutMs ?? CONTROL_HELPER_TIMEOUT_MS;
  controlHelperSigkillGraceMs = graceMs ?? CONTROL_HELPER_SIGKILL_GRACE_MS;
}
// ── State ───────────────────────────────────────────────────────────────────

interface ConnectionState {
  name: string;
  label: string | null;
  connected: boolean;
}

interface ScriptResult {
  stdout: string;
  stderr: string;
  code: number | null;
}

type FailureNotifier = (
  title: string,
  body: string,
  remedy?: FailureRemedy,
) => void;

interface ListenerOptions {
  notifyOnReady?: boolean;
  failureNotifier?: FailureNotifier;
}

let listenerProc: ChildProcess | null = null;
let currentCtx: ExtensionContext | null = null;
let messageBuffer = "";
let listenerReady = false;
let currentConnection: ConnectionState | null = null;
let activeStop: Promise<boolean> | null = null;
let mailboxController: MailboxDispatcher | null = null;
let controlEngine: ControlEngine | null = null;
let controlController: ControlController | null = null;

// ── Helpers ─────────────────────────────────────────────────────────────────

function truncate(text: string, max: number): string {
  if (text.length <= max) return text;
  return text.slice(0, max) + " …";
}

interface ListSession {
  name: string;
  label?: string | null;
}

function isListSession(value: unknown): value is ListSession {
  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
  const entry = value as Record<string, unknown>;
  if (typeof entry.name !== "string") return false;
  return (
    entry.label === undefined ||
    entry.label === null ||
    typeof entry.label === "string"
  );
}

function parseListSessions(value: unknown): ListSession[] {
  if (!value || typeof value !== "object" || Array.isArray(value)) {
    throw new Error("invalid response");
  }
  const payload = value as Record<string, unknown>;
  if (payload.op !== "list_ok") {
    throw new Error("invalid response");
  }
  const sessions = payload.sessions;
  if (!Array.isArray(sessions) || !sessions.every(isListSession)) {
    throw new Error("invalid response");
  }
  return sessions as ListSession[];
}

function formatListSessions(sessions: ListSession[]): string {
  return [...sessions]
    .sort((left, right) =>
      left.name === right.name ? 0 : left.name < right.name ? -1 : 1,
    )
    .map(
      (session) =>
        `• ${session.name}${session.label ? ` (${session.label})` : ""}`,
    )
    .join("\n");
}

// Compact one-line summary for the collapsed message renderer.
function messageSummary(details: {
  from?: string;
  text?: string;
  toInfo?: string;
  outgoing?: boolean;
}): string | null {
  const text = details.text ?? "";
  const chars = text.length;
  if (details.outgoing) {
    const toInfo = details.toInfo ?? "";
    if (toInfo.startsWith("to ")) {
      return `sent to ${toInfo.slice(3)} • ${chars} chars`;
    }
    if (toInfo === "broadcast") {
      return `broadcast • ${chars} chars`;
    }
    if (toInfo.startsWith("on ")) {
      return `published on ${toInfo.slice(3)} • ${chars} chars`;
    }
    return `sent ${toInfo} • ${chars} chars`;
  }
  if (details.from) {
    return `from ${details.from} • ${chars} chars`;
  }
  return null;
}

function renderOutgoingToolCall(toolName: string, theme: Theme): Component {
  return new Text(theme.fg("toolTitle", theme.bold(toolName)), 0, 0);
}

function renderOutgoingToolResult(
  toolName: string,
  result: { content: ReadonlyArray<{ type: string; text?: string }> },
  expanded: boolean,
  isPartial: boolean,
  isError: boolean,
  destination: string,
  message: string,
  theme: Theme,
): Component {
  if (isError) {
    const errorText = result.content
      .filter((block) => block.type === "text")
      .map((block) => block.text ?? "")
      .filter(Boolean)
      .join("\n");
    return new Text(theme.fg("error", errorText || `${toolName} failed`), 0, 0);
  }
  if (!expanded || isPartial) return new Container();
  return new Text(
    theme.fg("toolOutput", `\nTo: ${destination}\n\nMessage: ${message}`),
    0,
    0,
  );
}

function getConnectionState(ctx: ExtensionContext): ConnectionState | null {
  const branch = ctx.sessionManager.getBranch();
  for (let i = branch.length - 1; i >= 0; i--) {
    const entry = branch[i];
    if (entry.type === "custom" && entry.customType === "inter-agent-state") {
      return entry.data as ConnectionState;
    }
  }
  return null;
}

function persistState(pi: ExtensionAPI, state: ConnectionState) {
  pi.appendEntry("inter-agent-state", state);
}

function notify(
  title: string,
  body: string,
  type: "info" | "warning" | "error" = "info",
) {
  currentCtx?.ui.notify(truncate(`${title}: ${body}`, NOTIFY_MAX_LEN), type);
}

const PI_DOCTOR_FAILURE_HINT =
  "Run /inter-agent doctor for bounded diagnostics and check the Pi extension README.md for setup guidance.";
const PI_SETUP_FAILURE_HINT =
  "Run /inter-agent setup to create or repair the managed helper environment.";

function notifyCommandFailure(
  title: string,
  body: string,
  remedy: FailureRemedy = "doctor",
): void {
  const separator = /[.!?]$/.test(body) ? "" : ".";
  const hint =
    remedy === "setup" ? PI_SETUP_FAILURE_HINT : PI_DOCTOR_FAILURE_HINT;
  const suffix = `${separator} ${hint}`;
  const maxBodyLength = Math.max(
    0,
    NOTIFY_MAX_LEN - title.length - 2 - suffix.length,
  );
  const boundedBody =
    body.length <= maxBodyLength
      ? body
      : `${body.slice(0, Math.max(0, maxBodyLength - 2))} …`;
  notify(title, `${boundedBody}${suffix}`, "error");
}

const notifyDefaultFailure: FailureNotifier = (title, body, remedy) =>
  notifyCommandFailure(title, body, remedy);

function sendConnectionStatus(
  pi: ExtensionAPI,
  status: "connected" | "disconnected",
  message: string,
): void {
  pi.sendMessage(
    {
      customType: "inter-agent-status",
      content: message,
      display: true,
      details: { status },
    },
    { deliverAs: "followUp", triggerTurn: false },
  );
}

function connectedMessage(name: string, label: string | null): string {
  return `Connected to inter-agent message bus as "${name}"${label ? ` (${label})` : ""}.`;
}

const DISCONNECTED_MESSAGE = "Disconnected from inter-agent message bus.";

// Build an inbound peer body as a custom `inter-agent-message` payload. The
// content carries the body plus bounded reply-decision guidance; the display
// content is the clean body shown in the TUI. Immediate delivery reuses this
// builder so direct/broadcast/channel formatting and guidance stay identical.
function buildInboundMessage(
  from: string,
  text: string,
  toInfo: string,
): InboundImmediateMessage {
  const noReplyGuidance =
    "If no peer reply or user-facing action is needed, do not send a courtesy reply or discuss the message solely to acknowledge it.";
  const isChannel = toInfo.startsWith("on ");
  let replyInstruction: string;
  if (toInfo === "via broadcast") {
    replyInstruction = `Peer broadcast. Reply directly to ${from} only with inter_agent_send if it advances work or coordination, or to satisfy a request from the user; do not broadcast unless the user asks. ${noReplyGuidance}`;
  } else if (isChannel) {
    replyInstruction = `Peer channel message ${toInfo}. Reply to ${from} only with inter_agent_send, and only if it advances work or coordination; there is no publish tool, so reply directly rather than reposting to the channel. ${noReplyGuidance}`;
  } else {
    replyInstruction = `Peer message. Reply to ${from} only with inter_agent_send, and only if it advances work or coordination. ${noReplyGuidance}`;
  }
  const content = `[inter-agent message from agent ${from} ${toInfo}]

${text}

${replyInstruction}`;
  const displayContent = `[inter-agent message from agent ${from} ${toInfo}]

${text}`;
  return {
    customType: "inter-agent-message",
    content,
    display: true,
    details: { from, text, toInfo, displayContent },
  };
}

function showOutgoingInContext(
  pi: ExtensionAPI,
  from: string,
  text: string,
  toInfo: string,
) {
  pi.sendMessage(
    {
      customType: "inter-agent-message",
      content: `Outbound inter-agent history for a message sent as ${from} ${toInfo}. This records an action already completed; treat it as context, not a new request.

## BEGIN MESSAGE TRANSCRIPT

${text}

## END MESSAGE TRANSCRIPT`,
      display: true,
      details: {
        from,
        text,
        toInfo,
        outgoing: true,
        displayContent: `[outbound inter-agent history — sent by current agent (${from}) ${toInfo}]

${text}`,
      },
    },
    { triggerTurn: false, deliverAs: "followUp" },
  );
}

function execScript(script: string, args: string[]): Promise<ScriptResult> {
  return new Promise((resolve) => {
    const env = interAgentEnv();
    const proc = spawnChildProcess(script, args, {
      stdio: ["ignore", "pipe", "pipe"],
      shell: false,
      env,
    });
    let stdout = "";
    let stderr = "";
    proc.stdout?.on("data", (d: Buffer) => {
      stdout += d.toString();
    });
    proc.stderr?.on("data", (d: Buffer) => {
      stderr += d.toString();
    });
    proc.on("close", (code) => {
      resolve({ stdout, stderr, code });
    });
    proc.on("error", (err) => {
      const nodeErr = err as NodeJS.ErrnoException;
      if (nodeErr.code === "ENOENT") {
        stderr += `inter-agent command was not found at ${script}. Check that inter-agent is installed and configured, then try again.`;
      } else {
        stderr += String(err);
      }
      resolve({ stdout, stderr, code: null });
    });
  });
}

interface BoundedProcessResult extends ScriptResult {
  timedOut: boolean;
  outputExceeded: boolean;
}

function runBoundedProcess(
  command: string,
  args: string[],
): Promise<BoundedProcessResult> {
  return new Promise((resolve) => {
    const env = setupEnvironment();
    const proc = spawnChildProcess(command, args, {
      stdio: ["ignore", "pipe", "pipe"],
      shell: false,
      env,
    });
    let stdout = "";
    let stderr = "";
    let stdoutBytes = 0;
    let stderrBytes = 0;
    let timedOut = false;
    let outputExceeded = false;
    let settled = false;
    let timer: ReturnType<typeof setTimeout> | null = null;

    const finish = (code: number | null): void => {
      if (settled) return;
      settled = true;
      if (timer) clearTimeout(timer);
      resolve({ stdout, stderr, code, timedOut, outputExceeded });
    };
    const append = (chunk: Buffer, stream: "stdout" | "stderr"): void => {
      const currentBytes = stream === "stdout" ? stdoutBytes : stderrBytes;
      const remaining = SETUP_OUTPUT_MAX_BYTES - currentBytes;
      if (remaining <= 0) {
        outputExceeded = true;
        return;
      }
      const bounded =
        chunk.byteLength > remaining ? chunk.subarray(0, remaining) : chunk;
      if (stream === "stdout") {
        stdout += bounded.toString();
        stdoutBytes += chunk.byteLength;
      } else {
        stderr += bounded.toString();
        stderrBytes += chunk.byteLength;
      }
      if (chunk.byteLength > remaining) {
        outputExceeded = true;
      }
    };

    proc.stdout?.on("data", (chunk: Buffer) => append(chunk, "stdout"));
    proc.stderr?.on("data", (chunk: Buffer) => append(chunk, "stderr"));
    proc.once("close", (code) => finish(code));
    proc.once("error", (error) => {
      stderr = String(error);
      finish(null);
    });
    timer = setTimeout(() => {
      timedOut = true;
      try {
        proc.kill("SIGKILL");
      } catch {
        // The process may have exited before the timeout fired.
      }
      finish(null);
    }, SETUP_PROCESS_TIMEOUT_MS);
    timer.unref?.();
  });
}

function setupProcessFailure(
  stage: string,
  result: BoundedProcessResult,
): string {
  if (result.timedOut) return `${stage} timed out`;
  if (result.outputExceeded) return `${stage} produced too much output`;
  if (result.code === null) return `${stage} could not be started`;
  return `${stage} failed (exit ${result.code})`;
}

function execPiScript(
  scripts: InterAgentScripts,
  args: string[],
): Promise<ScriptResult> {
  if (scripts.unavailableMessage) {
    return Promise.resolve({
      stdout: "",
      stderr: scripts.unavailableMessage,
      code: 127,
    });
  }
  return execScript(scripts.pi, args);
}

function sleep(ms: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

function scriptFailureMessage(result: ScriptResult, operation: string): string {
  const output = (result.stderr || result.stdout).trim();
  if (!output && result.code === null) {
    return "inter-agent command was not found. Check that inter-agent is installed and configured, then try again.";
  }
  if (output.includes("not found")) {
    return output;
  }
  return truncate(output || `inter-agent ${operation} command failed`, 200);
}

function managedPythonPath(): string {
  return join(managedRuntimeVenv(), "bin", "python");
}

function setupVersionFailure(output: string): string | null {
  const match = output.match(/Python\s+(\d+)\.(\d+)/i);
  if (!match) return "selected Python did not report a usable version";
  const major = Number(match[1]);
  const minor = Number(match[2]);
  return major > 3 || (major === 3 && minor >= 10)
    ? null
    : "Python 3.10 or newer is required";
}

async function setupManagedRuntime(): Promise<
  { ok: true } | { ok: false; message: string }
> {
  const python = setupPython();
  const source = setupSource();
  const state = classifyManagedRuntime();
  if (state.kind === "unsafe") {
    return { ok: false, message: `${state.reason}; no files were changed` };
  }

  const version = await runBoundedProcess(python, ["-I", "--version"]);
  if (version.code !== 0) {
    return { ok: false, message: setupProcessFailure("Python check", version) };
  }
  const versionFailure = setupVersionFailure(
    `${version.stdout}\n${version.stderr}`,
  );
  if (versionFailure) return { ok: false, message: versionFailure };

  let targetState: SafeManagedRuntimeState = state;
  if (targetState.kind === "missing") {
    const created = await runBoundedProcess(python, [
      "-I",
      "-m",
      "venv",
      managedRuntimeVenv(),
    ]);
    if (created.code !== 0) {
      return {
        ok: false,
        message: setupProcessFailure("virtual environment creation", created),
      };
    }
  } else if (targetState.kind === "broken") {
    const repaired = await runBoundedProcess(python, [
      "-I",
      "-m",
      "venv",
      "--clear",
      managedRuntimeVenv(),
    ]);
    if (repaired.code !== 0) {
      return {
        ok: false,
        message: setupProcessFailure("managed environment repair", repaired),
      };
    }
  } else {
    const pipCheck = await runBoundedProcess(managedPythonPath(), [
      "-I",
      "-m",
      "pip",
      "--isolated",
      "--version",
    ]);
    if (pipCheck.code !== 0) {
      const reclassified = classifyManagedRuntime();
      if (reclassified.kind === "unsafe") {
        return {
          ok: false,
          message: `${reclassified.reason}; no files were changed`,
        };
      }
      targetState = reclassified;
      if (targetState.kind !== "broken" && targetState.kind !== "healthy") {
        return {
          ok: false,
          message:
            "managed environment pip is unusable and safe repair was not verified",
        };
      }
      const repaired = await runBoundedProcess(python, [
        "-I",
        "-m",
        "venv",
        "--clear",
        managedRuntimeVenv(),
      ]);
      if (repaired.code !== 0) {
        return {
          ok: false,
          message: setupProcessFailure("managed environment repair", repaired),
        };
      }
    }
  }

  const pip = await runBoundedProcess(managedPythonPath(), [
    "-I",
    "-m",
    "pip",
    "--isolated",
    "--version",
  ]);
  if (pip.code !== 0) {
    return {
      ok: false,
      message: setupProcessFailure("managed pip check", pip),
    };
  }
  const installed = await runBoundedProcess(managedPythonPath(), [
    "-I",
    "-m",
    "pip",
    "--isolated",
    "install",
    "--upgrade",
    "--no-cache-dir",
    "--",
    source,
  ]);
  if (installed.code !== 0) {
    return {
      ok: false,
      message: setupProcessFailure("helper installation", installed),
    };
  }
  if (!managedHelpersUsable()) {
    return {
      ok: false,
      message:
        "helper installation completed without all verified executable commands",
    };
  }
  return { ok: true };
}

async function readServerStatus(
  scripts: InterAgentScripts,
): Promise<
  | { ok: true; payload: Record<string, unknown> }
  | { ok: false; message: string; remedy?: FailureRemedy }
> {
  const result = await execPiScript(scripts, ["status", "--json"]);
  if (result.code !== 0) {
    return {
      ok: false,
      message:
        scripts.unavailableMessage || scriptFailureMessage(result, "status"),
      remedy: scripts.unavailableRemedy,
    };
  }

  try {
    const parsed: unknown = JSON.parse(result.stdout);
    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
      return { ok: true, payload: parsed as Record<string, unknown> };
    }
  } catch {
    // Fall through to the user-facing error below.
  }

  return {
    ok: false,
    message:
      "inter-agent status returned an invalid response. Try /inter-agent status; if this continues, check the inter-agent installation.",
  };
}

function statusState(payload: Record<string, unknown>): string {
  return typeof payload.state === "string" ? payload.state : "unknown";
}

function statusMessage(payload: Record<string, unknown>): string {
  return typeof payload.message === "string"
    ? payload.message
    : statusState(payload);
}

function shouldAutoStartServer(payload: Record<string, unknown>): boolean {
  return statusState(payload) === "unavailable";
}

function statusFailureGuidance(payload: Record<string, unknown>): string {
  const message = statusMessage(payload);
  switch (statusState(payload)) {
    case "auth_failed":
      return `${message}. Check that server and clients use the same inter-agent secret.`;
    case "protocol_mismatch":
      return `${message}. Another process may be using the inter-agent port; try /inter-agent status or restart the server.`;
    case "unavailable":
      return `${message}. Try /inter-agent status, or start inter-agent-server manually.`;
    default:
      return message;
  }
}

function startServerProcess(
  scripts: InterAgentScripts,
): Promise<{ ok: true; pid?: number } | { ok: false; message: string }> {
  if (scripts.unavailableMessage) {
    return Promise.resolve({ ok: false, message: scripts.unavailableMessage });
  }
  return new Promise((resolve) => {
    let settled = false;
    const finish = (
      result: { ok: true; pid?: number } | { ok: false; message: string },
    ) => {
      if (!settled) {
        settled = true;
        resolve(result);
      }
    };

    const proc = spawnChildProcess(
      scripts.server,
      ["--idle-timeout", String(AUTO_STARTED_SERVER_IDLE_TIMEOUT_S)],
      {
        stdio: "ignore",
        shell: false,
        detached: true,
        env: interAgentEnv(loadConfig()),
      },
    );

    proc.once("spawn", () => {
      proc.unref();
      finish({ ok: true, pid: proc.pid });
    });

    proc.once("error", (err) => {
      const nodeErr = err as NodeJS.ErrnoException;
      if (nodeErr.code === "ENOENT") {
        finish({
          ok: false,
          message: `inter-agent server command was not found at ${scripts.server}. Check that inter-agent is installed and configured, then try again.`,
        });
      } else {
        finish({
          ok: false,
          message: `could not start inter-agent server: ${String(err)}`,
        });
      }
    });

    proc.once("exit", (code, signal) => {
      finish({
        ok: false,
        message: `inter-agent server exited before it was ready (code ${code ?? "none"}, signal ${signal ?? "none"}). Try /inter-agent status or start inter-agent-server manually.`,
      });
    });
  });
}

async function waitForServerAvailable(
  scripts: InterAgentScripts,
): Promise<{ ok: true } | { ok: false; message: string }> {
  let lastMessage = "server unavailable";
  for (let i = 0; i < SERVER_START_WAIT_ATTEMPTS; i++) {
    const status = await readServerStatus(scripts);
    if (status.ok === false) {
      lastMessage = status.message;
    } else if (statusState(status.payload) === "available") {
      return { ok: true };
    } else {
      lastMessage = statusFailureGuidance(status.payload);
    }
    await sleep(SERVER_START_WAIT_MS);
  }

  return {
    ok: false,
    message: `Started the inter-agent server, but it did not become available. ${lastMessage}`,
  };
}

async function ensureServerAvailable(
  scripts: InterAgentScripts,
  failureNotifier: FailureNotifier = notifyDefaultFailure,
): Promise<boolean> {
  const initial = await readServerStatus(scripts);
  if (initial.ok === false) {
    failureNotifier(
      "[inter-agent] connect failed",
      initial.message,
      initial.remedy,
    );
    return false;
  }

  if (statusState(initial.payload) === "available") {
    return true;
  }

  if (!shouldAutoStartServer(initial.payload)) {
    failureNotifier(
      "[inter-agent] connect failed",
      statusFailureGuidance(initial.payload),
    );
    return false;
  }

  const started = await startServerProcess(scripts);
  if (started.ok === false) {
    failureNotifier(
      "[inter-agent] connect failed",
      started.message,
      scripts.unavailableRemedy,
    );
    return false;
  }

  const ready = await waitForServerAvailable(scripts);
  if (ready.ok === false) {
    failureNotifier("[inter-agent] connect failed", ready.message);
    return false;
  }

  return true;
}

function splitCommandArgs(input: string): string[] {
  const matches = input.match(/"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|\S+/g) || [];
  return matches.map((part) => {
    if (
      (part.startsWith('"') && part.endsWith('"')) ||
      (part.startsWith("'") && part.endsWith("'"))
    ) {
      return part.slice(1, -1).replace(/\\(["'\\])/g, "$1");
    }
    return part;
  });
}

function parseConnectArgs(
  args: string,
):
  | { ok: true; name: string; label: string | null }
  | { ok: false; message: string } {
  const parts = splitCommandArgs(args.trim());
  let name = DEFAULT_NAME;
  let label: string | null = null;
  let index = 0;

  if (parts[0] && parts[0] !== "--label") {
    name = parts[0];
    index = 1;
  }

  while (index < parts.length) {
    const part = parts[index];
    if (part === "--label") {
      const value = parts[index + 1];
      if (!value) {
        return {
          ok: false,
          message: "usage: /inter-agent connect <name> [--label <label>]",
        };
      }
      label = value;
      index += 2;
      continue;
    }
    if (label === null) {
      label = part;
      index += 1;
      continue;
    }
    return {
      ok: false,
      message: "usage: /inter-agent connect <name> [--label <label>]",
    };
  }

  return { ok: true, name, label };
}

function parseRenameArgs(
  args: string,
):
  | { ok: true; name: string; label: string | null }
  | { ok: false; message: string } {
  const trimmed = args.trim();
  if (!trimmed) {
    return {
      ok: false,
      message: "usage: /inter-agent rename <name> [--label <label>]",
    };
  }
  const parsed = parseConnectArgs(trimmed);
  if (parsed.ok === false) return parsed;
  if (parsed.name === DEFAULT_NAME && trimmed.startsWith("--label")) {
    return {
      ok: false,
      message: "usage: /inter-agent rename <name> [--label <label>]",
    };
  }
  return parsed;
}

function formatConnectError(code: string, text: string): string {
  switch (code) {
    case "NAME_TAKEN":
      return `${code}: ${text}. Choose a different name, or disconnect the existing session and try again.`;
    case "BAD_NAME":
      return `${code}: ${text}. Use lowercase letters, numbers, and hyphens; start with a letter or number; max 40 characters.`;
    case "AUTH_FAILED":
      return `${code}: ${text}. Check that server and clients use the same inter-agent secret.`;
    case "TOO_MANY_CONNECTIONS":
      return `${code}: ${text}. Disconnect another session, then try again.`;
    default:
      return `${code}: ${text}`;
  }
}

// ── Listener Management ─────────────────────────────────────────────────────

async function startListener(
  pi: ExtensionAPI,
  ctx: ExtensionContext,
  config: InterAgentConfig,
  name: string,
  label: string | null,
  options: ListenerOptions = {},
): Promise<boolean> {
  const wasConnected = listenerReady && currentConnection !== null;
  const reportFailure = options.failureNotifier ?? notifyDefaultFailure;
  const stopped = await stopListener(pi, ctx, { expected: true });
  if (!stopped) {
    reportFailure(
      "[inter-agent] listener error",
      "previous listener did not terminate; cannot start a new listener",
    );
    return false;
  }
  const scripts = getScripts(config);
  if (scripts.unavailableMessage) {
    reportFailure(
      "[inter-agent] listener error",
      scripts.unavailableMessage,
      scripts.unavailableRemedy,
    );
    return false;
  }
  const args = ["connect", name];
  if (label) args.push("--label", label);

  const proc = spawnChildProcess(scripts.pi, args, {
    stdio: ["ignore", "pipe", "pipe"],
    shell: false,
    env: interAgentEnv(config),
  });

  listenerProc = proc;
  messageBuffer = "";
  listenerReady = false;
  currentConnection = null;

  proc.stdout?.on("data", (data: Buffer) => {
    // Ignore output from a child that is no longer the current listener or is
    // being explicitly stopped, so stale frames cannot reanimate readiness,
    // overwrite a replacement listener's state, or deliver stale messages.
    if (listenerProc !== proc) return;
    const expected =
      (proc as ChildProcess & { __expectedStop?: boolean }).__expectedStop ===
      true;
    if (expected) return;

    messageBuffer += data.toString();
    const lines = messageBuffer.split("\n");
    messageBuffer = lines.pop() || "";

    for (const line of lines) {
      if (!line.trim()) continue;
      try {
        const msg = JSON.parse(line);
        if (msg.op === "welcome") {
          const state: ConnectionState = { name, label, connected: true };
          listenerReady = true;
          currentConnection = state;
          persistState(pi, state);
          updateStatus(ctx, state);
          // The listener re-emits `welcome` after every reconnect once the
          // private bridge is ready, so queued control responses flush here.
          controlEngine?.onListenerReady();
          if (options.notifyOnReady) {
            sendConnectionStatus(
              pi,
              "connected",
              connectedMessage(name, label),
            );
          }
          continue;
        }
        if (msg.op === "error") {
          const code = String(msg.code || "unknown");
          const text = String(msg.message || "connection rejected");
          reportFailure(
            `[inter-agent] connect failed`,
            formatConnectError(code, text),
          );
          listenerReady = false;
          currentConnection = null;
          void stopListener(pi, ctx, { expected: true });
          const state = getConnectionState(ctx);
          if (state) {
            persistState(pi, { ...state, connected: false });
            updateStatus(ctx, { ...state, connected: false });
          }
          continue;
        }
        if (msg.op === "msg") {
          // Control and unknown custom frames are classified before ordinary
          // mailbox processing. `pi.control.v1` frames go to the control
          // engine; unknown custom types are dropped with a bounded warning.
          // Neither ever becomes an ordinary mailbox entry or an empty body.
          if (typeof msg.custom_type === "string") {
            if (msg.custom_type === CONTROL_CUSTOM_TYPE) {
              controlEngine?.handleInboundCustomFrame({
                msgId: typeof msg.msg_id === "string" ? msg.msg_id : "",
                fromName:
                  typeof msg.from_name === "string" ? msg.from_name : "",
                customType: msg.custom_type,
                payload: msg.payload,
              });
            } else {
              notify(
                "[inter-agent] custom",
                `ignored unknown custom message type ${truncate(msg.custom_type, 64)}`,
                "warning",
              );
            }
            continue;
          }
          // Use the shared inbound parser so kind/toInfo derivation and the
          // `[from: name]` prefix handling stay consistent with the mailbox.
          // A malformed frame continues the per-line loop so a later valid
          // frame in the same stdout chunk is still handled.
          const meta = deriveInboundMetadata(msg);
          if (!meta) {
            notify(
              "[inter-agent] mailbox",
              "dropped an inbound message without a valid msg_id",
              "warning",
            );
            continue;
          }
          const mode = mailboxController?.getDeliveryMode() ?? "queued";
          // Queued notifications are metadata only; immediate mode restores the
          // existing bounded body notification (truncated inside `notify`).
          notify(
            `[inter-agent] ${meta.sender} ${meta.toInfo}`,
            mode === "immediate" ? meta.body : "queued in mailbox",
          );
          mailboxController?.deliverInbound({
            msgId: meta.msgId,
            sender: meta.sender,
            body: meta.body,
            kind: meta.kind,
            channel: meta.channel,
            target: meta.target,
            immediateMessage:
              mode === "immediate"
                ? buildInboundMessage(meta.sender, meta.body, meta.toInfo)
                : undefined,
          });
        }
      } catch {
        // Ignore non-JSON lines
      }
    }
  });

  proc.stderr?.on("data", (data: Buffer) => {
    if (listenerProc !== proc) return;
    const expected =
      (proc as ChildProcess & { __expectedStop?: boolean }).__expectedStop ===
      true;
    if (expected) return;

    const text = data.toString().trim();
    if (text) {
      notify("[inter-agent] listener stderr", text, "warning");
    }
  });

  proc.on("exit", (code) => {
    if (listenerProc !== proc) return;
    const expected =
      (proc as ChildProcess & { __expectedStop?: boolean }).__expectedStop ===
      true;
    const state = getConnectionState(ctx);
    const previousName = currentConnection?.name || state?.name || name;
    const wasConnected =
      listenerReady || currentConnection !== null || state?.connected === true;
    listenerProc = null;
    listenerReady = false;
    currentConnection = null;
    if (expected) return;
    // An unexpected exit clears durable routing state so the session_start
    // branch will not treat a dead listener as still connected. Expected
    // stops (disconnect or reload) own the durable-state transition themselves
    // via stopListener, so the exit handler must not overwrite it.
    if (state) {
      persistState(pi, { ...state, connected: false });
      updateStatus(ctx, { ...state, connected: false });
    }
    if (code !== 0 && code !== null) {
      const reconnectHint = wasConnected
        ? `. Use /inter-agent connect ${previousName} to reconnect.`
        : "";
      const body = `code ${code}${reconnectHint}`;
      if (wasConnected) {
        sendConnectionStatus(
          pi,
          "disconnected",
          `${DISCONNECTED_MESSAGE} Listener exited: ${body}`,
        );
      } else {
        notify("[inter-agent] listener exited", body, "warning");
      }
    } else if (wasConnected) {
      sendConnectionStatus(pi, "disconnected", DISCONNECTED_MESSAGE);
    }
  });

  proc.on("error", (err) => {
    if (listenerProc !== proc) return;
    const expected =
      (proc as ChildProcess & { __expectedStop?: boolean }).__expectedStop ===
      true;
    if (expected) return;

    const nodeErr = err as NodeJS.ErrnoException;
    if (nodeErr.code === "ENOENT") {
      reportFailure(
        "[inter-agent] listener error",
        "inter-agent connect command was not found. Check that inter-agent is installed and configured, then try again.",
      );
    } else {
      reportFailure("[inter-agent] listener error", String(err));
    }
  });

  return true;
}

async function stopListener(
  pi?: ExtensionAPI,
  ctx?: ExtensionContext,
  options: {
    expected?: boolean;
    /** Preserve the durable connected routing state in the transcript (used by
     a same-process `/reload` so the matching `session_start` reconnects the
     same identity once). Explicit disconnect and other shutdowns stay cleared. */
    preserveDurableConnected?: boolean;
  } = {},
): Promise<boolean> {
  const proc = listenerProc;
  const persistAfter = (): void => {
    if (!ctx || !pi) return;
    const state = getConnectionState(ctx);
    if (!state) return;
    const connected =
      options.preserveDurableConnected === true ? state.connected : false;
    persistState(pi, { ...state, connected });
    updateStatus(ctx, { ...state, connected });
  };
  if (!proc) {
    listenerReady = false;
    currentConnection = null;
    messageBuffer = "";
    persistAfter();
    return true;
  }

  if (activeStop) {
    return await activeStop;
  }

  const expected = options.expected === true;
  (proc as ChildProcess & { __expectedStop?: boolean }).__expectedStop =
    expected;

  activeStop = (async (): Promise<boolean> => {
    // Mark in-memory listener state unavailable immediately so no command
    // can use the terminating listener.
    listenerReady = false;
    currentConnection = null;
    messageBuffer = "";

    if (proc.exitCode !== null || proc.signalCode !== null) {
      listenerProc = null;
      return true;
    }

    proc.kill("SIGTERM");

    const termPromise = new Promise<void>((resolve) => {
      const onExit = () => {
        cleanup();
        resolve();
      };
      const onClose = () => {
        cleanup();
        resolve();
      };
      const cleanup = () => {
        proc.off("exit", onExit);
        proc.off("close", onClose);
      };
      proc.once("exit", onExit);
      proc.once("close", onClose);
      if (proc.exitCode !== null || proc.signalCode !== null) {
        cleanup();
        resolve();
      }
    });

    await Promise.race([termPromise, sleep(stopTermTimeoutMs)]);
    if (proc.exitCode !== null || proc.signalCode !== null) {
      listenerProc = null;
      return true;
    }

    proc.kill("SIGKILL");

    const killPromise = new Promise<void>((resolve) => {
      const onExit = () => {
        cleanup();
        resolve();
      };
      const onClose = () => {
        cleanup();
        resolve();
      };
      const cleanup = () => {
        proc.off("exit", onExit);
        proc.off("close", onClose);
      };
      proc.once("exit", onExit);
      proc.once("close", onClose);
      if (proc.exitCode !== null || proc.signalCode !== null) {
        cleanup();
        resolve();
      }
    });

    await Promise.race([killPromise, sleep(stopKillTimeoutMs)]);

    if (proc.exitCode !== null || proc.signalCode !== null) {
      listenerProc = null;
      return true;
    }
    return false;
  })();

  try {
    const exited = await activeStop;
    if (exited) {
      persistAfter();
    }
    return exited;
  } finally {
    activeStop = null;
  }
}

function updateStatus(ctx: ExtensionContext, state: ConnectionState | null) {
  if (state?.connected) {
    ctx.ui.setStatus("inter-agent", `IA: ${state.name} 🌐 `);
  } else {
    ctx.ui.setStatus("inter-agent", undefined);
  }
}

type ContextMessage = ContextEvent["messages"][number];

function isInterAgentContextMarker(message: ContextMessage): boolean {
  return (
    message.role === "custom" &&
    (message.customType === "inter-agent-message" ||
      message.customType === "inter-agent-mailbox")
  );
}

function filterInterAgentContext(
  event: ContextEvent,
): { messages: ContextEvent["messages"] } | undefined {
  if (!event.messages.some(isInterAgentContextMarker)) return undefined;

  const toolCallSuppression = new Map<string, boolean>();
  const messages: ContextEvent["messages"] = [];
  let changed = false;

  for (const message of event.messages) {
    if (message.role === "assistant") {
      const suppressed =
        message.stopReason === "error" || message.stopReason === "aborted";
      for (const block of message.content) {
        if (block.type === "toolCall") {
          toolCallSuppression.set(block.id, suppressed);
        }
      }
    }

    if (
      message.role === "toolResult" &&
      toolCallSuppression.get(message.toolCallId) === true
    ) {
      changed = true;
      continue;
    }

    messages.push(message);
  }

  return changed ? { messages } : undefined;
}

// ── Extension Export ────────────────────────────────────────────────────────

export default function (pi: ExtensionAPI) {
  const config = loadConfig();
  const currentScripts = () => getScripts(config);

  // ── Pi control V1 engine ────────────────────────────────────────────────
  // The target-side control engine observes Pi lifecycle events it registers
  // itself and is driven here for startup flag, session lifecycle, listener
  // readiness, and inbound custom-frame classification. Responses travel back
  // through the target's own persistent agent connection via the internal
  // `control-send` bridge helper; payloads and prompt text never appear in argv.
  function execControlBridge(
    target: string,
    payload: ControlWireRequest | ControlResponse,
  ): Promise<boolean> {
    return new Promise((resolve) => {
      const scripts = currentScripts();
      if (scripts.unavailableMessage || !currentConnection) {
        resolve(false);
        return;
      }
      const proc = spawnChildProcess(
        scripts.pi,
        ["control-send", "--name", currentConnection.name],
        {
          stdio: ["pipe", "pipe", "pipe"],
          shell: false,
          env: interAgentEnv(),
        },
      );
      let stdout = "";
      let stdoutBytes = 0;
      let settled = false;
      let deadlineTimer: ReturnType<typeof setTimeout> | null = null;
      let killTimer: ReturnType<typeof setTimeout> | null = null;

      const onStdout = (d: Buffer): void => {
        stdoutBytes += d.byteLength;
        if (stdoutBytes > CONTROL_HELPER_MAX_STDOUT_BYTES) {
          requestTermination();
          return;
        }
        stdout += d.toString();
      };
      const onStderr = (): void => {
        // Local helper diagnostics are not user-facing control responses.
      };
      const onClose = (code: number | null): void => {
        if (code !== 0) {
          finish(false);
          return;
        }
        try {
          const result = JSON.parse(stdout) as { op?: unknown };
          finish(result.op === "custom_ok");
        } catch {
          finish(false);
        }
      };
      const onError = (): void => finish(false);
      const cleanup = (): void => {
        if (deadlineTimer) clearTimeout(deadlineTimer);
        if (killTimer) clearTimeout(killTimer);
        proc.stdout?.off("data", onStdout);
        proc.stderr?.off("data", onStderr);
        proc.off("close", onClose);
        proc.off("error", onError);
      };
      const finish = (ok: boolean): void => {
        if (settled) return;
        settled = true;
        cleanup();
        resolve(ok);
      };
      const requestTermination = (): void => {
        if (settled) return;
        if (proc.exitCode !== null || proc.signalCode !== null) {
          finish(false);
          return;
        }
        try {
          proc.kill("SIGTERM");
        } catch {
          // The helper may have exited between the state check and kill.
        }
        if (settled) return;
        killTimer = setTimeout(() => {
          if (!settled && proc.exitCode === null && proc.signalCode === null) {
            try {
              proc.kill("SIGKILL");
            } catch {
              // The helper may have exited before escalation.
            }
          }
          finish(false);
        }, controlHelperSigkillGraceMs);
        killTimer.unref?.();
      };

      proc.stdout?.on("data", onStdout);
      proc.stderr?.on("data", onStderr);
      proc.on("close", onClose);
      proc.on("error", onError);
      deadlineTimer = setTimeout(requestTermination, controlHelperTimeoutMs);
      deadlineTimer.unref?.();
      proc.stdin?.end(
        JSON.stringify({
          custom_type: CONTROL_CUSTOM_TYPE,
          payload,
          to: target,
        }) + "\n",
      );
    });
  }

  function execControlSend(
    controller: string,
    payload: ControlResponse,
  ): Promise<boolean> {
    return execControlBridge(controller, payload);
  }

  const controlControllerHost: ControlControllerHost = {
    isListenerReady: () => listenerReady && currentConnection !== null,
    submitControlRequest: (target: string, payload: ControlWireRequest) =>
      execControlRequest(target, payload),
    isIdle: () => currentCtx?.isIdle() ?? true,
    hasPendingMessages: () => currentCtx?.hasPendingMessages() ?? false,
    sendResult: (message, triggerTurn) =>
      pi.sendMessage(message, { triggerTurn, deliverAs: "followUp" }),
    notify: (body, type = "info") =>
      notify("[inter-agent] control", body, type),
    schedule: (fn, ms) => {
      const handle = setTimeout(fn, ms);
      return () => clearTimeout(handle);
    },
  };
  function execControlRequest(
    target: string,
    payload: ControlWireRequest,
  ): Promise<boolean> {
    if (!listenerReady || !currentConnection) return Promise.resolve(false);
    return execControlBridge(target, payload);
  }

  const controlHost: ControlHost = {
    isIdle: () => currentCtx?.isIdle() ?? true,
    hasPendingMessages: () => currentCtx?.hasPendingMessages() ?? false,
    isStreaming: () => !(currentCtx?.isIdle() ?? true),
    isListenerReady: () => listenerReady,
    selfName: () => currentConnection?.name ?? null,
    sendUserMessage: (text, deliverAs) => {
      // Released Pi exposes fire-and-forget public submission only. Admission
      // and any asynchronous extension error remain unobservable here; the
      // control engine correlates only public lifecycle events.
      pi.sendUserMessage(text, deliverAs ? { deliverAs } : undefined);
    },
    abort: () => currentCtx?.abort(),
    shutdown: () => currentCtx?.shutdown(),
    submitControlResponse: (controller, payload) =>
      execControlSend(controller, payload),
    notifyWarning: (body) => notify("[inter-agent] control", body, "warning"),
  };
  controlEngine = new ControlEngine(pi, controlHost);
  controlController = new ControlController(controlControllerHost);
  controlEngine.setResponseHandler((response, fromName) =>
    controlController?.handleResponse(response, fromName),
  );

  // ── Mailbox state and delivery ───────────────────────────────
  const initialMode = effectiveDeliveryMode(config.deliveryMode);
  const initialDebounce = effectiveDebounceMs(config.mailboxNoticeDebounceMs);
  const modeConfiguredInvalid =
    config.deliveryMode !== undefined &&
    !isValidDeliveryMode(config.deliveryMode);
  const debounceConfiguredInvalid =
    config.mailboxNoticeDebounceMs !== undefined &&
    !isValidDebounceMs(config.mailboxNoticeDebounceMs);
  let warnedInvalidMode = false;
  let warnedInvalidDebounce = false;

  const mailbox = new MailboxDispatcher(
    {
      isIdle: () => currentCtx?.isIdle() ?? true,
      hasPendingMessages: () => currentCtx?.hasPendingMessages() ?? false,
      sendNotice: (message, triggerTurn) =>
        pi.sendMessage(message, { triggerTurn, deliverAs: "followUp" }),
      sendImmediate: (message, triggerTurn) =>
        pi.sendMessage(message, { triggerTurn, deliverAs: "followUp" }),
      notifyWarning: (body) => notify("[inter-agent] mailbox", body, "warning"),
      schedule: (fn, ms) => {
        const handle = setTimeout(fn, ms);
        return () => clearTimeout(handle);
      },
    },
    initialMode,
    initialDebounce,
  );
  mailboxController = mailbox;

  // ── Custom message renderer ──────────────────────────────────────────────
  // Connection status messages are visible in both the transcript and model
  // context, but never trigger a turn.
  pi.registerMessageRenderer<{
    status?: "connected" | "disconnected";
  }>("inter-agent-status", (message, _options, theme) => {
    const content = typeof message.content === "string" ? message.content : "";
    const box = new Box(1, 1, (t) => theme.bg("customMessageBg", t));
    box.addChild(new Text(theme.fg("customMessageText", content), 0, 0));
    return box as unknown as Component;
  });

  // Show a clean, user-facing summary in the TUI (from details.displayContent)
  // while the full `content` (with internal agent instructions) goes to the LLM.
  pi.registerMessageRenderer<{
    displayContent?: string;
    from?: string;
    text?: string;
    toInfo?: string;
    outgoing?: boolean;
  }>("inter-agent-message", (message, { expanded }, theme) => {
    const details =
      typeof message.details === "object" &&
      message.details !== null &&
      "displayContent" in message.details
        ? (message.details as {
            displayContent?: string;
            from?: string;
            text?: string;
            toInfo?: string;
            outgoing?: boolean;
          })
        : undefined;
    const display =
      details?.displayContent ??
      (typeof message.content === "string" ? message.content : "");
    const box = new Box(1, 1, (t) => theme.bg("customMessageBg", t));
    box.addChild(
      new Text(
        theme.fg("customMessageLabel", `\x1b[1m[inter-agent-message]\x1b[22m`),
        0,
        0,
      ),
    );
    box.addChild(new Spacer(1));
    if (expanded) {
      box.addChild(new Text(theme.fg("customMessageText", display), 0, 0));
    } else {
      const summary = details ? messageSummary(details) : null;
      if (summary) {
        box.addChild(new Text(theme.fg("muted", summary), 0, 0));
      }
    }
    return box as unknown as Component;
  });

  // Metadata-only mailbox notice renderer. Compact rendering shows unread
  // counts grouped by sender; expanded rendering lists every unread ID, sender,
  // kind, and channel. Details never contain bodies.
  pi.registerMessageRenderer<MailboxSnapshot>(
    "inter-agent-mailbox",
    (message, { expanded }, theme) => {
      const snap =
        typeof message.details === "object" && message.details !== null
          ? (message.details as MailboxSnapshot)
          : { unread: 0, messages: [], bySender: [] };
      const box = new Box(1, 1, (t) => theme.bg("customMessageBg", t));
      box.addChild(
        new Text(
          theme.fg(
            "customMessageLabel",
            `\x1b[1m[inter-agent-mailbox]\x1b[22m`,
          ),
          0,
          0,
        ),
      );
      box.addChild(new Spacer(1));
      if (expanded) {
        box.addChild(
          new Text(
            theme.fg("customMessageText", buildNoticeExpanded(snap).join("\n")),
            0,
            0,
          ),
        );
      } else {
        box.addChild(
          new Text(theme.fg("muted", buildNoticeCompact(snap)), 0, 0),
        );
      }
      return box as unknown as Component;
    },
  );

  // Remove provider-invalid tool results from histories containing inter-agent
  // custom messages. The filter is scoped to each context request.
  pi.on("context", (event) => filterInterAgentContext(event));

  // Register the startup routing-name flag during extension factory so Pi
  // exposes `pi --inter-agent <name>`. The value is only available later, at
  // `session_start`.
  pi.registerFlag("inter-agent", {
    type: "string",
    description:
      "Set this Pi worker's inter-agent routing name at process startup",
  });

  // The single comma-separated control allowlist flag. An absent flag disables
  // control completely while leaving ordinary inter-agent messaging unchanged;
  // an explicitly present but empty or invalid value fails closed with a
  // bounded user-facing error. Repeated flags follow documented last-value-wins
  // Pi behavior; the value is re-read on every session start (including reload,
  // which carries the original flag value through the existing runtime).
  pi.registerFlag("allow-control-by", {
    type: "string",
    description:
      "Comma-separated exact routing names allowed to control this Pi worker (pi.control.v1)",
  });

  // ── Session Lifecycle ─────────────────────────────────────────────────────

  pi.on("session_start", async (event, ctx) => {
    currentCtx = ctx;

    // Re-apply the single comma-separated control allowlist flag on every
    // session start. An absent flag disables control; an explicitly present
    // but invalid value fails closed with a bounded user-facing error while
    // leaving ordinary inter-agent messaging unchanged.
    const controlSetup = controlEngine?.onSessionStart(
      event?.reason,
      pi.getFlag("allow-control-by"),
    );
    if (controlSetup && !controlSetup.ok) {
      notify("[inter-agent] control", controlSetup.message ?? "", "error");
    }

    // Same-process `/reload` preserves the bounded unread mailbox through the
    // one-use carrier; every other start reason starts empty and clears any
    // stale handoff. Restoration is metadata/bodies only and never starts a
    // second listener or changes routing identity.
    if (event?.reason === "reload") {
      mailbox.restoreReloadHandoff(
        ctx.sessionManager.getSessionId(),
        resolveReloadCarrier(),
      );
      // Flush a restored pending body-free notice once, now that the new
      // runtime is idle; settle is a no-op unless a notice is actually pending.
      mailbox.settle();
    } else {
      resolveReloadCarrier().reset();
    }

    // Warn exactly once per invalid configured key once UI context exists.
    if (modeConfiguredInvalid && !warnedInvalidMode) {
      warnedInvalidMode = true;
      notify(
        "[inter-agent] config",
        `interAgent.deliveryMode ${JSON.stringify(config.deliveryMode)} is invalid; using "queued"`,
        "warning",
      );
    }
    if (debounceConfiguredInvalid && !warnedInvalidDebounce) {
      warnedInvalidDebounce = true;
      notify(
        "[inter-agent] config",
        `interAgent.mailboxNoticeDebounceMs is invalid; using ${MAILBOX_NOTICE_DEBOUNCE_MS_DEFAULT} ms`,
        "warning",
      );
    }
    // Prefer an explicit --inter-agent flag over any transcript-restored
    // connection state. The flag is reapplied on every session_start reason
    // (startup, reload, new, resume, fork) so the worker identity stays
    // effective after Pi replaces or reloads the extension session.
    const flagValue = pi.getFlag("inter-agent");
    const flagPresent = typeof flagValue === "string";

    if (flagPresent) {
      const explicitName = flagValue.trim();
      if (!explicitName) {
        notify(
          "[inter-agent] connect failed",
          "inter-agent routing name cannot be blank; use --inter-agent <name> or omit the flag",
          "error",
        );
        return;
      }

      const ready = await ensureServerAvailable(currentScripts());
      if (!ready) {
        const state = getConnectionState(ctx);
        if (state) {
          persistState(pi, { ...state, connected: false });
          updateStatus(ctx, { ...state, connected: false });
        }
        return;
      }
      await startListener(pi, ctx, config, explicitName, null, {
        notifyOnReady: true,
      });
      return;
    }

    const state = getConnectionState(ctx);
    if (state?.connected) {
      const ready = await ensureServerAvailable(currentScripts());
      if (!ready) {
        persistState(pi, { ...state, connected: false });
        updateStatus(ctx, { ...state, connected: false });
        return;
      }
      await startListener(pi, ctx, config, state.name, state.label, {
        notifyOnReady: true,
      });
    }
  });

  pi.on("session_shutdown", async (event, ctx) => {
    // Fail active control work before the listener is stopped so best-effort
    // failure responses can still reach controllers; same-process reload uses
    // target_reloading, every other shutdown reason target_disconnected.
    controlController?.onSessionShutdown(
      event?.reason === "reload" ? "target_reloading" : "target_disconnected",
    );
    controlEngine?.onSessionShutdown(event?.reason);
    const reload = event?.reason === "reload";
    const targetCtx = currentCtx ?? ctx;
    let stopped = true;
    if (targetCtx) {
      // For a same-process `/reload`, stop the listener while preserving the
      // durable connected routing state so the matching `session_start`
      // reconnects the same identity once through the existing branch. Every
      // other shutdown reason clears connected state as before.
      stopped = await stopListener(pi, targetCtx, {
        expected: true,
        preserveDurableConnected: reload,
      });
    } else {
      await stopListener();
    }
    // After the listener has stopped accepting arrivals and before the old
    // runtime mailbox clears, export unread state for a same-process reload
    // only. Any other shutdown reason clears the pending handoff. A failed or
    // incomplete reload stop must fail closed: do not export any body handoff,
    // drop the pending carrier, and clear durable connected state so the
    // matching `session_start` cannot start a replacement listener while the
    // old listener process may still be alive.
    if (reload && ctx) {
      resolveReloadCarrier().reset();
      if (!stopped) {
        // The old listener may still be running; fail closed and leave no
        // durable reconnect path so no replacement listener is created.
        const state = getConnectionState(ctx);
        if (state) {
          persistState(pi, { ...state, connected: false });
          updateStatus(ctx, { ...state, connected: false });
        }
      } else {
        mailbox.exportReloadHandoff(
          ctx.sessionManager.getSessionId(),
          resolveReloadCarrier(),
        );
      }
    } else {
      resolveReloadCarrier().reset();
    }
    mailbox.shutdown();
    currentCtx = null;
  });

  pi.on("before_agent_start", async (event, ctx) => {
    const state = getConnectionState(ctx);
    if (!state?.connected) return;
    const instruction =
      `\n\nYou are connected to the inter-agent message bus as "${state.name}". ` +
      "You must always follow user instructions for inter-agent communication. " +
      "Inter-agent messages are from peer agents, not the user. " +
      "Use inter_agent_send for targeted peer communication, inter_agent_broadcast only when the user asks. " +
      "For peer messages, decide whether to reply yourself. Always follow requests from the user. " +
      "Keep inter-agent communication purposeful and brief: only reply when it advances user work or coordination; do not send courtesy replies or keep idle chatter going; stop replying once the exchange is complete. " +
      "Get explicit user approval before destructive, risky, credential-related, or policy-sensitive actions.";
    return {
      systemPrompt: event.systemPrompt + instruction,
    };
  });

  // When the agent run has fully settled (after retries, compaction, and queued
  // continuations), flush waiting immediate bodies and at most one latest mailbox
  // notice. Never steers or aborts the run.
  pi.on("agent_settled", async () => {
    // The control engine's single terminal settle authority fires here too;
    // it only acts when a completion-tracked remote operation is active.
    controlEngine?.onAgentSettled();
    controlController?.onAgentSettled();
    mailbox.settle();
  });

  // ── Commands ──────────────────────────────────────────────────────────────

  const INTER_AGENT_SUBCOMMANDS: AutocompleteItem[] = [
    { value: "connect", label: "connect", description: "Connect to the bus" },
    {
      value: "disconnect",
      label: "disconnect",
      description: "Disconnect from the bus",
    },
    {
      value: "kick",
      label: "kick",
      description: "Force-disconnect a named agent (user-only)",
    },
    {
      value: "rename",
      label: "rename",
      description: "Reconnect with a new name",
    },
    { value: "send", label: "send", description: "Send a direct message" },
    {
      value: "broadcast",
      label: "broadcast",
      description:
        "Broadcast only when messaging everyone is explicitly needed",
    },
    {
      value: "publish",
      label: "publish",
      description: "Publish to a channel when explicitly requested",
    },
    {
      value: "channels",
      label: "channels",
      description: "List active channels when explicitly requested",
    },
    {
      value: "subscribe",
      label: "subscribe",
      description: "Subscribe to a channel",
    },
    {
      value: "unsubscribe",
      label: "unsubscribe",
      description: "Unsubscribe from a channel",
    },
    { value: "list", label: "list", description: "List connected sessions" },
    {
      value: "setup",
      label: "setup",
      description: "Create or repair the managed helper environment",
    },
    {
      value: "status",
      label: "status",
      description: "Check server status",
    },
    {
      value: "doctor",
      label: "doctor",
      description: "Run bounded, read-only Pi integration diagnostics",
    },
    {
      value: "delivery",
      label: "delivery",
      description:
        "Set [i]mmediate or [q]ueued (via mailbox) message delivery <immediate|queued>",
    },
    {
      value: "flush",
      label: "flush",
      description:
        "Move unread mailbox messages into context (all, or the oldest <count>)",
    },
    {
      value: "control",
      label: "control",
      description: "Control an allowlisted Pi target",
    },
  ];

  async function handleConnect(args: string, ctx: ExtensionContext) {
    const parsed = parseConnectArgs(args);
    if (parsed.ok === false) {
      notify("[inter-agent] connect failed", parsed.message, "error");
      return;
    }

    notify(
      "[inter-agent] connecting",
      `to inter-agent message bus as "${parsed.name}"${parsed.label ? ` (${parsed.label})` : ""}`,
    );

    const ready = await ensureServerAvailable(
      currentScripts(),
      notifyCommandFailure,
    );
    if (!ready) return;

    const started = await startListener(
      pi,
      ctx,
      config,
      parsed.name,
      parsed.label,
      {
        notifyOnReady: true,
        failureNotifier: notifyCommandFailure,
      },
    );
    if (!started) return;
  }

  async function handleDisconnect(_args: string, ctx: ExtensionContext) {
    // Fail active control work with target_disconnected before the listener
    // is removed so best-effort responses can still reach controllers.
    controlController?.onSessionShutdown("target_disconnected");
    controlEngine?.onExplicitDisconnect();
    const wasConnected = listenerReady && currentConnection !== null;
    const stopped = await stopListener(pi, ctx, { expected: true });
    if (stopped) {
      if (wasConnected) {
        sendConnectionStatus(pi, "disconnected", DISCONNECTED_MESSAGE);
      }
    } else {
      notifyCommandFailure(
        "[inter-agent] disconnect failed",
        "listener did not terminate",
      );
    }
  }

  async function handleKick(args: string, _ctx: ExtensionContext) {
    const name = args.trim();
    const parts = name.split(/\s+/).filter(Boolean);
    if (parts.length !== 1) {
      notify(
        "[inter-agent] kick failed",
        "usage: /inter-agent kick <name>",
        "error",
      );
      return;
    }
    // Kick is user-only and uses a short-lived authenticated control
    // connection; it does not require this Pi listener to be connected.
    const result = await execPiScript(currentScripts(), ["kick", name]);
    if (result.code !== 0) {
      notifyCommandFailure(
        "[inter-agent] kick failed",
        scriptFailureMessage(result, "kick"),
      );
      return;
    }
    try {
      const payload = JSON.parse(result.stdout);
      if (payload.op !== "kick_ok") {
        notifyCommandFailure("[inter-agent] kick failed", "invalid response");
        return;
      }
      notify(
        "[inter-agent] kicked",
        `removed ${payload.name} (session ${payload.session_id})`,
      );
    } catch {
      notifyCommandFailure("[inter-agent] kick failed", "invalid response");
    }
  }

  async function handleRename(args: string, ctx: ExtensionContext) {
    const parsed = parseRenameArgs(args);
    if (parsed.ok === false) {
      notify("[inter-agent] rename failed", parsed.message, "error");
      return;
    }
    if (!listenerReady || !currentConnection) {
      notifyCommandFailure(
        "[inter-agent] rename failed",
        "Not connected to the inter-agent bus. Use /inter-agent connect first.",
      );
      return;
    }

    const label = parsed.label ?? currentConnection.label;
    const ready = await ensureServerAvailable(
      currentScripts(),
      notifyCommandFailure,
    );
    if (!ready) return;

    // Rename replaces the listener identity; fail active control work with
    // target_disconnected and clear tracking before the replacement.
    controlController?.onSessionShutdown("target_disconnected");
    controlEngine?.onExplicitDisconnect();
    const started = await startListener(pi, ctx, config, parsed.name, label, {
      notifyOnReady: true,
      failureNotifier: notifyCommandFailure,
    });
    if (!started) {
      notifyCommandFailure(
        "[inter-agent] rename failed",
        "previous listener did not terminate",
      );
      return;
    }
  }

  async function handleSend(args: string, _ctx: ExtensionContext) {
    const match = args.trim().match(/^(\S+)\s+(.+)$/s);
    if (!match) {
      notify(
        "[inter-agent] send failed",
        "usage: /inter-agent send <to> <text>",
        "error",
      );
      return;
    }
    const [, to, text] = match;
    if (!listenerReady || !currentConnection) {
      notifyCommandFailure(
        "[inter-agent] send failed",
        "Not connected to the inter-agent bus. Use /inter-agent connect first.",
      );
      return;
    }
    const name = currentConnection.name;
    const result = await execPiScript(currentScripts(), [
      "send",
      to,
      text,
      "--from",
      name,
    ]);
    if (result.code !== 0) {
      notifyCommandFailure(
        "[inter-agent] send failed",
        scriptFailureMessage(result, "send"),
      );
      return;
    }
    notify("[inter-agent] sent", `to ${to}`);
    showOutgoingInContext(pi, name, text, `to ${to}`);
  }

  async function handleBroadcast(args: string, _ctx: ExtensionContext) {
    const text = args.trim();
    if (!text) {
      notify("[inter-agent] broadcast failed", "message required", "error");
      return;
    }
    if (!listenerReady || !currentConnection) {
      notifyCommandFailure(
        "[inter-agent] broadcast failed",
        "Not connected to the inter-agent bus. Use /inter-agent connect first.",
      );
      return;
    }
    const name = currentConnection.name;
    const result = await execPiScript(currentScripts(), [
      "broadcast",
      text,
      "--from",
      name,
    ]);
    if (result.code !== 0) {
      notifyCommandFailure(
        "[inter-agent] broadcast failed",
        scriptFailureMessage(result, "broadcast"),
      );
      return;
    }
    notify("[inter-agent] broadcast", "sent");
    showOutgoingInContext(pi, name, text, "broadcast");
  }

  async function handlePublish(args: string, _ctx: ExtensionContext) {
    const match = args.trim().match(/^(\S+)\s+(.+)$/s);
    if (!match) {
      notify(
        "[inter-agent] publish failed",
        "usage: /inter-agent publish <channel> <text>",
        "error",
      );
      return;
    }
    const [, channel, text] = match;
    if (!listenerReady || !currentConnection) {
      notifyCommandFailure(
        "[inter-agent] publish failed",
        "Not connected to the inter-agent bus. Use /inter-agent connect first.",
      );
      return;
    }
    const name = currentConnection.name;
    const result = await execPiScript(currentScripts(), [
      "publish",
      channel,
      text,
      "--from",
      name,
    ]);
    if (result.code !== 0) {
      notifyCommandFailure(
        "[inter-agent] publish failed",
        scriptFailureMessage(result, "publish"),
      );
      return;
    }
    notify("[inter-agent] published", `on ${channel}`);
    showOutgoingInContext(pi, name, text, `on ${channel}`);
  }

  async function handleChannels(args: string, _ctx: ExtensionContext) {
    if (args.trim()) {
      notify(
        "[inter-agent] channels failed",
        "usage: /inter-agent channels",
        "error",
      );
      return;
    }
    const result = await execPiScript(currentScripts(), ["channels", "--json"]);
    if (result.code !== 0) {
      notifyCommandFailure(
        "[inter-agent] channels failed",
        scriptFailureMessage(result, "channels"),
      );
      return;
    }
    try {
      const payload: unknown = JSON.parse(result.stdout);
      if (
        !payload ||
        typeof payload !== "object" ||
        Array.isArray(payload) ||
        (payload as { op?: unknown }).op !== "channels_ok" ||
        !Array.isArray((payload as { channels?: unknown }).channels)
      ) {
        throw new Error("invalid response");
      }
      const channels = (payload as { channels: unknown[] }).channels;
      const lines = channels.map((entry) => {
        if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
          throw new Error("invalid response");
        }
        const name = (entry as { name?: unknown }).name;
        const subscribers = (entry as { subscribers?: unknown }).subscribers;
        if (
          typeof name !== "string" ||
          !Array.isArray(subscribers) ||
          !subscribers.every((subscriber) => typeof subscriber === "string")
        ) {
          throw new Error("invalid response");
        }
        return `${name}: ${subscribers.join(", ")}`;
      });
      notify(
        "[inter-agent] channels",
        lines.join("; ") || "no channels currently have subscribers",
      );
    } catch {
      notifyCommandFailure("[inter-agent] channels failed", "invalid response");
    }
  }

  async function handleSubscribe(args: string, _ctx: ExtensionContext) {
    const channel = args.trim();
    const parts = channel.split(/\s+/).filter(Boolean);
    if (parts.length !== 1) {
      notify(
        "[inter-agent] subscribe failed",
        "usage: /inter-agent subscribe <channel>",
        "error",
      );
      return;
    }
    if (!listenerReady || !currentConnection) {
      notifyCommandFailure(
        "[inter-agent] subscribe failed",
        "Not connected to the inter-agent bus. Use /inter-agent connect first.",
      );
      return;
    }
    const name = currentConnection.name;
    const result = await execPiScript(currentScripts(), [
      "subscribe",
      channel,
      "--name",
      name,
    ]);
    if (result.code !== 0) {
      notifyCommandFailure(
        "[inter-agent] subscribe failed",
        scriptFailureMessage(result, "subscribe"),
      );
      return;
    }
    notify("[inter-agent] subscribed", channel);
  }

  async function handleUnsubscribe(args: string, _ctx: ExtensionContext) {
    const channel = args.trim();
    const parts = channel.split(/\s+/).filter(Boolean);
    if (parts.length !== 1) {
      notify(
        "[inter-agent] unsubscribe failed",
        "usage: /inter-agent unsubscribe <channel>",
        "error",
      );
      return;
    }
    if (!listenerReady || !currentConnection) {
      notifyCommandFailure(
        "[inter-agent] unsubscribe failed",
        "Not connected to the inter-agent bus. Use /inter-agent connect first.",
      );
      return;
    }
    const name = currentConnection.name;
    const result = await execPiScript(currentScripts(), [
      "unsubscribe",
      channel,
      "--name",
      name,
    ]);
    if (result.code !== 0) {
      notifyCommandFailure(
        "[inter-agent] unsubscribe failed",
        scriptFailureMessage(result, "unsubscribe"),
      );
      return;
    }
    notify("[inter-agent] unsubscribed", channel);
  }

  async function handleControl(args: string, _ctx: ExtensionContext) {
    const parts = splitCommandArgs(args.trim());
    if (parts.length < 2) {
      notify(
        "[inter-agent] control failed",
        "usage: /inter-agent control <target> <prompt|steer|follow_up|abort|state|shutdown> [text]",
        "error",
      );
      return;
    }
    const [target, command, ...textParts] = parts;
    const text = textParts.length > 0 ? textParts.join(" ") : undefined;
    const result = await controlController?.execute(target, command, text);
    if (!result) {
      notifyCommandFailure(
        "[inter-agent] control failed",
        "controller unavailable",
      );
      return;
    }
    if (result.details.error) {
      notifyCommandFailure(
        "[inter-agent] control failed",
        String(result.details.error),
      );
      return;
    }
    notify("[inter-agent] control", result.content[0].text);
  }

  async function handleDelivery(args: string, _ctx: ExtensionContext) {
    const raw = args.trim();
    const first = raw.charAt(0).toLowerCase();
    const mode = first === "i" ? "immediate" : first === "q" ? "queued" : raw;
    if (mode !== "queued" && mode !== "immediate") {
      notify(
        "[inter-agent] delivery failed",
        "usage: /inter-agent delivery <immediate|queued> (aliases: i, q)",
        "error",
      );
      return;
    }
    mailbox.setDeliveryMode(mode);
    const deliveryMessage =
      mode === "immediate"
        ? "Inter-agent message delivery is now immediate for future arrivals. Existing unread mailbox messages remain queued and unchanged."
        : "Inter-agent message delivery is now queued for future arrivals. Existing unread mailbox messages remain queued and unchanged.";
    notify(
      "[inter-agent] delivery",
      `future arrivals will be delivered ${
        mode === "immediate" ? "immediately" : "into the mailbox queue"
      }; ${mailbox.size} unread message(s) already queued are left unchanged`,
    );
    pi.sendMessage(
      {
        customType: "inter-agent-delivery-change",
        content: deliveryMessage,
        display: false,
      },
      { triggerTurn: false },
    );
  }

  const FLUSH_USAGE = "usage: /inter-agent flush [count]";

  /**
   * Parse the optional flush count. Returns null for invalid input; an object
   * with an undefined `count` means "every unread message".
   */
  function parseFlushCount(args: string): { count?: number } | null {
    if (!args) return {};
    const parts = args.split(/\s+/);
    if (parts.length !== 1) return null;
    if (!/^\d+$/.test(parts[0])) return null;
    const count = Number(parts[0]);
    if (
      !Number.isSafeInteger(count) ||
      count < 1 ||
      count > MAILBOX_MAX_UNREAD
    ) {
      return null;
    }
    return { count };
  }

  async function handleFlush(args: string, ctx: ExtensionCommandContext) {
    const parsed = parseFlushCount(args.trim());
    if (parsed === null) {
      notify("[inter-agent] flush failed", FLUSH_USAGE, "error");
      return;
    }
    // Wait before selecting so an argument-free flush moves the unread set that
    // exists once the command reaches its idle execution point.
    await ctx.waitForIdle();
    const selected = mailbox.selectUnread(parsed.count);
    if (selected.length === 0) {
      notify(
        "[inter-agent] flush",
        "This session's inter-agent mailbox is empty, so there are no messages to flush.",
      );
      return;
    }
    try {
      // Earlier entries enter context without triggering; only the final entry
      // starts the turn, so the complete batch is present before that turn.
      for (let index = 0; index < selected.length; index += 1) {
        const entry = selected[index];
        pi.sendMessage(
          buildInboundMessage(
            entry.sender,
            entry.body,
            describeDestination(entry.channel, entry.target),
          ),
          { triggerTurn: index === selected.length - 1 },
        );
      }
    } catch {
      notify(
        "[inter-agent] flush failed",
        "could not add the selected messages to context; they remain unread",
        "error",
      );
      return;
    }
    const removal = mailbox.read(selected.map((entry) => entry.msgId));
    if (removal.missing.length > 0 || removal.read.length !== selected.length) {
      notify(
        "[inter-agent] flush failed",
        "the injected messages could not be removed from the unread mailbox",
        "error",
      );
      return;
    }
    notify(
      "[inter-agent] flush",
      `${selected.length} message(s) flushed to context; ${removal.remaining} unread remaining`,
    );
  }

  async function handleSetup(args: string, ctx: ExtensionContext) {
    if (args.trim()) {
      notify(
        "[inter-agent] setup failed",
        "usage: /inter-agent setup",
        "error",
      );
      return;
    }

    const state = classifyManagedRuntime();
    if (state.kind === "unsafe") {
      notifyCommandFailure(
        "[inter-agent] setup failed",
        `${state.reason}; no files were changed`,
        "doctor",
      );
      return;
    }

    const overrideWarning = setupOverrideWarning(config);
    const action =
      state.kind === "missing"
        ? "create"
        : state.kind === "broken"
          ? "repair"
          : "update";
    let approved = false;
    try {
      approved = await ctx.ui.confirm(
        "Inter-agent setup",
        `This will ${action} the managed Python helper environment at ${managedRuntimeVenv()} and install ${setupSourceDescription()}. It may modify files and use the network. Endpoint, secret, Core, and mailbox state will not be changed.${overrideWarning ? ` ${overrideWarning}.` : ""} Continue?`,
      );
    } catch {
      notifyCommandFailure(
        "[inter-agent] setup failed",
        "could not show the approval prompt",
        "doctor",
      );
      return;
    }
    if (!approved) {
      notify("[inter-agent] setup", "setup cancelled");
      return;
    }

    const result = await setupManagedRuntime();
    if ("message" in result) {
      notifyCommandFailure(
        "[inter-agent] setup failed",
        result.message,
        "doctor",
      );
      return;
    }
    notify(
      "[inter-agent] setup",
      `managed helper environment ready at ${managedRuntimeVenv()}.${overrideWarning ? ` ${overrideWarning}.` : ""}`,
      overrideWarning ? "warning" : "info",
    );
  }

  async function handleList(_args: string, _ctx: ExtensionContext) {
    const result = await execPiScript(currentScripts(), ["list", "--json"]);
    if (result.code !== 0) {
      notifyCommandFailure(
        "[inter-agent] list failed",
        scriptFailureMessage(result, "list"),
      );
      return;
    }
    try {
      const sessions = parseListSessions(JSON.parse(result.stdout));
      const lines = formatListSessions(sessions);
      if (!lines) {
        notify("[inter-agent] list", "no agents connected");
      } else {
        notify("[inter-agent] list", lines);
      }
    } catch {
      notifyCommandFailure("[inter-agent] list failed", "invalid response");
    }
  }

  async function handleStatus(_args: string, _ctx: ExtensionContext) {
    const result = await execPiScript(currentScripts(), ["status", "--json"]);
    if (result.code !== 0) {
      notifyCommandFailure(
        "[inter-agent] status failed",
        scriptFailureMessage(result, "status"),
      );
      return;
    }
    try {
      const payload = JSON.parse(result.stdout);
      const state = String(payload.state || "unknown");
      const msg = String(payload.message || state);
      notify(
        "[inter-agent] status",
        msg,
        state === "available" ? "info" : "warning",
      );
    } catch {
      notifyCommandFailure("[inter-agent] status failed", "invalid response");
    }
  }

  async function handleDoctor(args: string, ctx: ExtensionContext) {
    let available = false;
    try {
      const commands = pi.getCommands();
      const extensionSources = commands
        .filter(
          (command) =>
            command.source === "extension" &&
            (command.name === "inter-agent" ||
              command.name.startsWith("inter-agent:")),
        )
        .map((command) => command.sourceInfo);
      available = commands.some(
        (command) =>
          command.source === "skill" &&
          command.name === DOCTOR_SKILL_COMMAND &&
          extensionSources.some((source) =>
            samePiSource(source, command.sourceInfo),
          ),
      );
    } catch {
      // A host that cannot enumerate commands cannot safely submit the skill.
    }
    if (!available) {
      notify(
        "[inter-agent] doctor failed",
        "packaged inter-agent-doctor skill is unavailable; reload or reinstall the extension, then check the Pi extension README.md for package-loading guidance",
        "error",
      );
      return;
    }

    const message = args
      ? `/${DOCTOR_SKILL_COMMAND} ${args}`
      : `/${DOCTOR_SKILL_COMMAND}`;
    try {
      // This is an explicit user-command submission. It intentionally does not
      // require a bus listener and never invokes an inter-agent helper.
      const options = ctx.isIdle()
        ? { expandPromptTemplates: true }
        : { expandPromptTemplates: true, deliverAs: "followUp" as const };
      pi.sendUserMessage(message, options);
    } catch {
      notify(
        "[inter-agent] doctor failed",
        "could not submit the doctor skill; check the Pi extension README.md for package-loading guidance",
        "error",
      );
    }
  }

  function showInterAgentUsage() {
    notify(
      "[inter-agent] usage",
      "usage: /inter-agent <connect|disconnect|kick|rename|send|broadcast|publish|channels|subscribe|unsubscribe|list|setup|status|doctor|delivery> [args]; flush: /inter-agent flush [count]; control: /inter-agent control <target> <command> [text]",
      "warning",
    );
  }

  pi.registerCommand("inter-agent", {
    description: "Inter-agent bus commands",
    getArgumentCompletions: (prefix: string): AutocompleteItem[] | null => {
      const filtered = INTER_AGENT_SUBCOMMANDS.filter((s) =>
        s.value.startsWith(prefix),
      );
      return filtered.length > 0 ? filtered : null;
    },
    handler: async (args, ctx) => {
      const trimmed = args.trim();
      if (!trimmed) {
        showInterAgentUsage();
        return;
      }
      const subcommand = trimmed.split(/\s+/, 1)[0];
      const rest = trimmed.slice(subcommand.length).trimStart();
      switch (subcommand) {
        case "connect":
          await handleConnect(rest, ctx);
          break;
        case "disconnect":
          await handleDisconnect(rest, ctx);
          break;
        case "kick":
          await handleKick(rest, ctx);
          break;
        case "rename":
          await handleRename(rest, ctx);
          break;
        case "send":
          await handleSend(rest, ctx);
          break;
        case "broadcast":
          await handleBroadcast(rest, ctx);
          break;
        case "publish":
          await handlePublish(rest, ctx);
          break;
        case "channels":
          await handleChannels(rest, ctx);
          break;
        case "subscribe":
          await handleSubscribe(rest, ctx);
          break;
        case "unsubscribe":
          await handleUnsubscribe(rest, ctx);
          break;
        case "list":
          await handleList(rest, ctx);
          break;
        case "setup":
          await handleSetup(rest, ctx);
          break;
        case "status":
          await handleStatus(rest, ctx);
          break;
        case "doctor":
          await handleDoctor(rest, ctx);
          break;
        case "delivery":
          await handleDelivery(rest, ctx);
          break;
        case "flush":
          await handleFlush(rest, ctx);
          break;
        case "control":
          await handleControl(rest, ctx);
          break;
        default:
          showInterAgentUsage();
      }
    },
  });

  // ── Tools ─────────────────────────────────────────────────────────────────

  const controlTarget = Type.String({
    minLength: 1,
    description: "Target routing name",
  });
  const controlRequestId = Type.Optional(
    Type.String({
      minLength: 1,
      maxLength: 128,
      description: "Deliberate replay request ID",
    }),
  );
  // Keep this schema flat for OpenAI-compatible providers that require every
  // function parameter schema to have a top-level object type. Command/text
  // relationships remain strictly validated by buildControlRequest().
  const controlToolParameters = Type.Object({
    target: controlTarget,
    command: Type.String({
      enum: ["prompt", "steer", "follow_up", "abort", "state", "shutdown"],
      description: "Control command",
    }),
    text: Type.Optional(
      Type.String({
        description: "Prompt, steering, or follow-up text",
      }),
    ),
    requestId: controlRequestId,
  });

  pi.registerTool({
    name: "inter_agent_control",
    label: "Control inter-agent Pi",
    description:
      "Send one asynchronous control request to an allowlisted Pi target. " +
      "A timeout has unknown outcome; do not retry automatically.",
    parameters: controlToolParameters,
    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
      const args = params as {
        target: string;
        command: string;
        text?: string;
        requestId?: string;
      };
      const result = await controlController?.execute(
        args.target,
        args.command,
        args.text,
        args.requestId,
      );
      if (!result) throw new Error("control controller unavailable");
      if (result.details.error) throw new Error(result.content[0].text);
      return result;
    },
  });

  pi.registerTool({
    name: "inter_agent_send",
    label: "Send inter-agent message",
    description:
      "Send a direct message to another agent on the inter-agent bus",
    parameters: Type.Object({
      to: Type.String({ description: "Target agent routing name" }),
      text: Type.String({ description: "Message text" }),
    }),
    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
      const { to, text } = params as { to: string; text: string };
      if (!listenerReady || !currentConnection) {
        throw new Error(
          "Not connected to the inter-agent bus. Use /inter-agent connect first.",
        );
      }
      const name = currentConnection.name;
      const result = await execPiScript(currentScripts(), [
        "send",
        to,
        text,
        "--from",
        name,
      ]);
      if (result.code !== 0) {
        throw new Error(scriptFailureMessage(result, "send"));
      }
      showOutgoingInContext(pi, name, text, `to ${to}`);
      return {
        content: [
          {
            type: "text" as const,
            text: `Message sent from the current agent to ${to}`,
          },
        ],
        details: { to, text },
      };
    },
    renderCall(_args, theme) {
      return renderOutgoingToolCall("inter_agent_send", theme);
    },
    renderResult(result, { expanded, isPartial }, theme, context) {
      return renderOutgoingToolResult(
        "inter_agent_send",
        result,
        expanded,
        isPartial,
        context.isError,
        context.args.to,
        context.args.text,
        theme,
      );
    },
  });

  pi.registerTool({
    name: "inter_agent_broadcast",
    label: "Broadcast inter-agent message",
    description:
      "Broadcast to all agents only when the user explicitly asks to message " +
      "everyone; prefer inter_agent_send for replies.",
    parameters: Type.Object({
      text: Type.String({ description: "Message text for all agents" }),
    }),
    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
      const { text } = params as { text: string };
      if (!listenerReady || !currentConnection) {
        throw new Error(
          "Not connected to the inter-agent bus. Use /inter-agent connect first.",
        );
      }
      const name = currentConnection.name;
      const result = await execPiScript(currentScripts(), [
        "broadcast",
        text,
        "--from",
        name,
      ]);
      if (result.code !== 0) {
        throw new Error(scriptFailureMessage(result, "broadcast"));
      }
      showOutgoingInContext(pi, name, text, "broadcast");
      return {
        content: [
          { type: "text" as const, text: "Broadcast sent to all other agents" },
        ],
        details: { text },
      };
    },
    renderCall(_args, theme) {
      return renderOutgoingToolCall("inter_agent_broadcast", theme);
    },
    renderResult(result, { expanded, isPartial }, theme, context) {
      return renderOutgoingToolResult(
        "inter_agent_broadcast",
        result,
        expanded,
        isPartial,
        context.isError,
        "everyone",
        context.args.text,
        theme,
      );
    },
  });

  pi.registerTool({
    name: "inter_agent_list",
    label: "List inter-agent sessions",
    description: "List all connected agent sessions on the inter-agent bus",
    parameters: Type.Object({}),
    async execute(_toolCallId, _params, _signal, _onUpdate, _ctx) {
      const result = await execPiScript(currentScripts(), ["list", "--json"]);
      if (result.code !== 0) {
        throw new Error(`List failed: ${scriptFailureMessage(result, "list")}`);
      }
      try {
        const sessions = parseListSessions(JSON.parse(result.stdout));
        return {
          content: [
            {
              type: "text" as const,
              text: formatListSessions(sessions) || "No agents connected",
            },
          ],
          details: { sessions },
        };
      } catch {
        throw new Error("Invalid list response");
      }
    },
  });

  pi.registerTool({
    name: "inter_agent_whoami",
    label: "Inter-agent local identity",
    description:
      "Report this Pi session's local inter-agent connection identity",
    parameters: Type.Object({}),
    async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
      const state = getConnectionState(ctx);
      const listenerRunning = listenerProc !== null;
      const connected =
        listenerReady && listenerRunning && currentConnection !== null;
      const name = connected ? currentConnection.name : null;
      const label = connected ? currentConnection.label : null;
      const lines = connected
        ? [
            "Connected: true",
            `Name: ${name}`,
            ...(label ? [`Label: ${label}`] : []),
          ]
        : [
            "Connected: false",
            ...(state?.name ? [`Last name: ${state.name}`] : []),
          ];
      return {
        content: [{ type: "text" as const, text: lines.join("\n") }],
        details: {
          connected,
          name,
          label,
          listener_running: listenerRunning,
          saved_name: state?.name ?? null,
          saved_connected: state?.connected ?? false,
        },
      };
    },
  });

  pi.registerTool({
    name: "inter_agent_status",
    label: "Inter-agent server status",
    description: "Check the status of the inter-agent server",
    parameters: Type.Object({}),
    async execute(_toolCallId, _params, _signal, _onUpdate, _ctx) {
      const result = await execPiScript(currentScripts(), ["status", "--json"]);
      if (result.code !== 0) {
        throw new Error(
          `Status check failed: ${scriptFailureMessage(result, "status")}`,
        );
      }
      try {
        const payload = JSON.parse(result.stdout);
        const text = `State: ${payload.state}\nMessage: ${payload.message}\nReachable: ${payload.server_reachable}`;
        return {
          content: [{ type: "text" as const, text }],
          details: payload,
        };
      } catch {
        throw new Error("Invalid status response");
      }
    },
  });

  pi.registerTool({
    name: "inter_agent_read_messages",
    label: "Read queued inter-agent messages",
    description:
      "Read and remove queued inter-agent messages from the Pi mailbox. Only " +
      "messages you have not read yet are returned. Reading never sends, replies, " +
      "subscribes, publishes, or triggers any peer action.",
    parameters: Type.Object({
      ids: Type.Optional(
        Type.Array(Type.String({ minLength: 1 }), {
          maxItems: MAILBOX_MAX_UNREAD,
          uniqueItems: true,
        }),
      ),
    }),
    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
      const { ids } = params as { ids?: string[] };
      const result = mailbox.read(ids);
      const readLines = result.read.map((m) => {
        const where = m.channel
          ? ` on ${m.channel}`
          : m.target
            ? ` to ${m.target}`
            : "";
        return `## ${m.msgId}\nfrom ${m.sender}${where} (${m.kind})\n\n${m.body}`;
      });
      let text: string;
      if (result.read.length === 0) {
        text =
          result.missing.length > 0
            ? `0 messages read. Not unread or missing: ${result.missing.join(", ")}`
            : "0 messages read; mailbox is empty";
      } else {
        text = `${result.read.length} message(s) read\n\n${readLines.join(
          "\n\n",
        )}`;
        if (result.missing.length > 0) {
          text += `\n\nNot unread or missing: ${result.missing.join(", ")}`;
        }
      }
      return {
        content: [{ type: "text" as const, text }],
        details: {
          read: result.read.map((m) => ({
            id: m.msgId,
            sender: m.sender,
            kind: m.kind,
            channel: m.channel,
            target: m.target,
            body: m.body,
          })),
          missing: result.missing,
          remaining: result.remaining,
        },
      };
    },
  });
}