@fitchmultz/pi-subagents 0.44.7 → 0.45.0

package/dist/pi-intercom/broker/spawn.js

@@ -7,18 +7,21 @@ import net from "net";
 import { getPiAgentDir } from "../agent-dir.js";
 import { getBrokerSocketPath, getLegacyBrokerSocketPath, isOwnedBrokerSocket } from "./paths.js";
 import { isBrokerPidReused } from "./pid.js";
+import { errorMessage, hasErrorCode } from "../../shared/unknown.js";
 const INTERCOM_DIR = join(getPiAgentDir(), "intercom");
 const EXTENSION_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
 const BROKER_PID = join(INTERCOM_DIR, "broker.pid");
 const BROKER_SPAWN_LOCK = join(INTERCOM_DIR, "broker.spawn.lock");
 function sleep(ms) {
-    return new Promise(resolve => setTimeout(resolve, ms));
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
 }
 function usesLegacyTsxDefault(brokerCommand, brokerArgs) {
-    return brokerCommand === "npx"
-        && brokerArgs.length === 2
-        && brokerArgs[0] === "--no-install"
-        && brokerArgs[1] === "tsx";
+    return (brokerCommand === "npx" &&
+        brokerArgs.length === 2 &&
+        brokerArgs[0] === "--no-install" &&
+        brokerArgs[1] === "tsx");
 }
 export function getBrokerLaunchSpec(brokerPath, brokerCommand, brokerArgs) {
     if (usesLegacyTsxDefault(brokerCommand, brokerArgs)) {
@@ -41,7 +44,7 @@ export function getBrokerSpawnOptions() {
     };
 }
 function toError(error) {
-    return error instanceof Error ? error : new Error(String(error));
+    return error instanceof Error ? error : new Error(errorMessage(error));
 }
 export async function spawnBrokerIfNeeded(brokerCommand, brokerArgs) {
     await mkdir(INTERCOM_DIR, { recursive: true });
@@ -73,7 +76,7 @@ export async function spawnBrokerIfNeeded(brokerCommand, brokerArgs) {
             };
             const onExit = (code, signal) => {
                 cleanup();
-                if (signal) {
+                if (signal !== null) {
                     reject(new Error(`Intercom broker exited before startup with signal ${signal}`));
                     return;
                 }
@@ -81,10 +84,12 @@ export async function spawnBrokerIfNeeded(brokerCommand, brokerArgs) {
             };
             child.once("error", onError);
             child.once("exit", onExit);
-            waitForBroker().then(() => {
+            waitForBroker()
+                .then(() => {
                 cleanup();
                 resolve();
-            }, (error) => {
+            })
+                .catch((error) => {
                 cleanup();
                 reject(toError(error));
             });
@@ -98,8 +103,9 @@ export async function isBrokerRunning() {
     return checkSocketConnectable();
 }
 function readLivePid() {
-    if (!existsSync(BROKER_PID))
+    if (!existsSync(BROKER_PID)) {
         return null;
+    }
     let raw;
     try {
         raw = readFileSync(BROKER_PID, "utf-8");
@@ -108,30 +114,34 @@ function readLivePid() {
         return null;
     }
     const pid = parseInt(raw.trim(), 10);
-    if (!Number.isFinite(pid) || pid <= 0)
+    if (!Number.isFinite(pid) || pid <= 0) {
         return null;
+    }
     try {
         process.kill(pid, 0);
     }
     catch (error) {
-        return error.code === "EPERM" ? pid : null;
+        return hasErrorCode(error, "EPERM") ? pid : null;
     }
     return isBrokerPidReused(pid, raw) ? null : pid;
 }
 export async function stopUnhealthyBrokerBeforeSpawn() {
-    if (await checkSocketConnectable())
+    if (await checkSocketConnectable()) {
         return;
+    }
     const pid = readLivePid();
-    if (pid === null)
+    if (pid === null) {
         return;
+    }
     throw new Error(`Intercom broker PID ${pid} may still own accepted work but its socket is unhealthy; refusing to spawn a second broker. Let the broker exit normally, then retry.`);
 }
 async function checkSocketConnectable() {
     const preferred = getBrokerSocketPath();
-    if (isOwnedBrokerSocket(preferred) && await checkOneSocket(preferred))
+    if (isOwnedBrokerSocket(preferred) && (await checkOneSocket(preferred))) {
         return true;
+    }
     const legacy = getLegacyBrokerSocketPath();
-    return legacy !== preferred && isOwnedBrokerSocket(legacy) && await checkOneSocket(legacy);
+    return legacy !== preferred && isOwnedBrokerSocket(legacy) && (await checkOneSocket(legacy));
 }
 function checkOneSocket(brokerSocket) {
     return new Promise((resolve) => {
@@ -148,7 +158,7 @@ function checkOneSocket(brokerSocket) {
         socket.on("connect", onConnect);
         socket.on("error", onError);
         const timeout = setTimeout(() => finish(false), 1000);
-        timeout.unref?.();
+        timeout.unref();
     });
 }
 function acquireSpawnLock() {
@@ -159,16 +169,11 @@ function acquireSpawnLock() {
             return true;
         }
         catch (error) {
-            if (!(error instanceof Error) || error.code !== "EEXIST") {
+            if (!hasErrorCode(error, "EEXIST")) {
                 throw error;
             }
             if (isSpawnLockStale()) {
-                try {
-                    unlinkSync(BROKER_SPAWN_LOCK);
-                }
-                catch {
-                    // If we can't delete the stale lock, retry a few times before giving up
-                }
+                releaseSpawnLock();
                 continue;
             }
             return false;
@@ -181,7 +186,9 @@ function isSpawnLockStale() {
         return false;
     }
     try {
-        const [pidLine = "", createdAtLine = "0"] = readFileSync(BROKER_SPAWN_LOCK, "utf-8").trim().split("\n");
+        const [pidLine = "", createdAtLine = "0"] = readFileSync(BROKER_SPAWN_LOCK, "utf-8")
+            .trim()
+            .split("\n");
         const pid = Number.parseInt(pidLine, 10);
         const createdAt = Number.parseInt(createdAtLine, 10);
         const ageMs = Date.now() - createdAt;
@@ -212,9 +219,13 @@ function releaseSpawnLock() {
 async function waitForBroker(timeoutMs = 5000) {
     const start = Date.now();
     while (Date.now() - start < timeoutMs) {
+        // Each probe must finish before the next to avoid parallel socket attempts.
+        // oxlint-disable-next-line no-await-in-loop
         if (await checkSocketConnectable()) {
             return;
         }
+        // Polling waits between probes rather than starting an unbounded batch.
+        // oxlint-disable-next-line no-await-in-loop
         await sleep(100);
     }
     throw new Error("Broker failed to start within timeout");

package/dist/pi-intercom/config.js

@@ -1,10 +1,8 @@
-import { existsSync, readFileSync } from "fs";
-import { join } from "path";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import { Key } from "@earendil-works/pi-tui";
 import { getPiAgentDir } from "./agent-dir.js";
-function getConfigPath() {
-    return join(getPiAgentDir(), "intercom", "config.json");
-}
+import { isRecord, isUnknownArray } from "./validation.js";
 const defaults = {
     shortcut: Key.altShift("m"),
     brokerCommand: process.execPath,
@@ -20,80 +18,96 @@ function isShortcut(value) {
     const prefix = value.match(/^(?:(?:ctrl|shift|alt|super)\+)+/)?.[0] ?? "";
     const modifiers = prefix.split("+").filter(Boolean);
     const key = value.slice(prefix.length);
-    return new Set(modifiers).size === modifiers.length && (namedKeys.has(key) || /^[a-z0-9]$/.test(key));
+    return (new Set(modifiers).size === modifiers.length && (namedKeys.has(key) || /^[a-z0-9]$/.test(key)));
+}
+function configuredString(parsed, key) {
+    if (!Object.hasOwn(parsed, key)) {
+        return defaults[key];
+    }
+    const value = parsed[key];
+    if (typeof value !== "string") {
+        throw new Error(`"${key}" must be a string`);
+    }
+    if (key === "status") {
+        return value;
+    }
+    if (value.trim() === "") {
+        throw new Error('"brokerCommand" must not be empty');
+    }
+    return value.trim();
+}
+function brokerCommand(parsed) {
+    return configuredString(parsed, "brokerCommand") ?? defaults.brokerCommand;
+}
+function configuredShortcut(parsed) {
+    if (!Object.hasOwn(parsed, "shortcut")) {
+        return defaults.shortcut;
+    }
+    if (typeof parsed.shortcut !== "string") {
+        throw new Error('"shortcut" must be a native key identifier');
+    }
+    const shortcut = parsed.shortcut.trim();
+    if (!isShortcut(shortcut)) {
+        throw new Error('"shortcut" must be a native key identifier, for example alt+shift+m');
+    }
+    return shortcut;
+}
+function configuredArgs(parsed) {
+    if (!Object.hasOwn(parsed, "brokerArgs")) {
+        return defaults.brokerArgs;
+    }
+    if (!isUnknownArray(parsed.brokerArgs)) {
+        throw new Error('"brokerArgs" must be an array');
+    }
+    return parsed.brokerArgs.map((arg) => {
+        if (typeof arg !== "string") {
+            throw new Error('"brokerArgs" items must be strings');
+        }
+        return arg;
+    });
+}
+function configuredBoolean(parsed, key) {
+    if (!Object.hasOwn(parsed, key)) {
+        return defaults[key];
+    }
+    const value = parsed[key];
+    if (typeof value !== "boolean") {
+        throw new Error(`"${key}" must be a boolean`);
+    }
+    return value;
+}
+function configuredTimeout(parsed, key) {
+    if (!Object.hasOwn(parsed, key)) {
+        return defaults[key];
+    }
+    const value = parsed[key];
+    const min = key === "askTimeoutMs" ? 1000 : 500;
+    if (typeof value !== "number" || !Number.isFinite(value) || value < min) {
+        throw new Error(`"${key}" must be a finite number >= ${min}`);
+    }
+    return value;
 }
 export function loadConfig() {
-    const configPath = getConfigPath();
+    const configPath = join(getPiAgentDir(), "intercom", "config.json");
     if (!existsSync(configPath)) {
         return { ...defaults };
     }
     try {
-        const raw = readFileSync(configPath, "utf-8");
-        const parsed = JSON.parse(raw);
-        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        const parsed = JSON.parse(readFileSync(configPath, "utf-8"));
+        if (!isRecord(parsed)) {
             throw new Error("Config must be a JSON object");
         }
-        const parsedConfig = parsed;
-        const config = { ...defaults };
-        if (Object.hasOwn(parsedConfig, "shortcut")) {
-            if (typeof parsedConfig.shortcut !== "string")
-                throw new Error('"shortcut" must be a native key identifier');
-            const shortcut = parsedConfig.shortcut.trim();
-            if (!isShortcut(shortcut))
-                throw new Error('"shortcut" must be a native key identifier, for example alt+shift+m');
-            config.shortcut = shortcut;
-        }
-        if (Object.hasOwn(parsedConfig, "brokerCommand")) {
-            if (typeof parsedConfig.brokerCommand !== "string") {
-                throw new Error(`"brokerCommand" must be a string`);
-            }
-            const brokerCommand = parsedConfig.brokerCommand.trim();
-            if (!brokerCommand) {
-                throw new Error(`"brokerCommand" must not be empty`);
-            }
-            config.brokerCommand = brokerCommand;
-        }
-        if (Object.hasOwn(parsedConfig, "brokerArgs")) {
-            if (!Array.isArray(parsedConfig.brokerArgs)) {
-                throw new Error(`"brokerArgs" must be an array`);
-            }
-            const brokerArgs = [];
-            for (const arg of parsedConfig.brokerArgs) {
-                if (typeof arg !== "string") {
-                    throw new Error(`"brokerArgs" items must be strings`);
-                }
-                brokerArgs.push(arg);
-            }
-            config.brokerArgs = brokerArgs;
-        }
-        if (Object.hasOwn(parsedConfig, "confirmSend")) {
-            if (typeof parsedConfig.confirmSend !== "boolean") {
-                throw new Error(`"confirmSend" must be a boolean`);
-            }
-            config.confirmSend = parsedConfig.confirmSend;
-        }
-        if (Object.hasOwn(parsedConfig, "replyHint")) {
-            if (typeof parsedConfig.replyHint !== "boolean") {
-                throw new Error(`"replyHint" must be a boolean`);
-            }
-            config.replyHint = parsedConfig.replyHint;
-        }
-        if (Object.hasOwn(parsedConfig, "status")) {
-            if (typeof parsedConfig.status !== "string") {
-                throw new Error(`"status" must be a string`);
-            }
-            config.status = parsedConfig.status;
-        }
-        for (const [key, min] of [["askTimeoutMs", 1000], ["sendTimeoutMs", 500], ["listTimeoutMs", 500]]) {
-            if (Object.hasOwn(parsedConfig, key)) {
-                const value = parsedConfig[key];
-                if (typeof value !== "number" || !Number.isFinite(value) || value < min) {
-                    throw new Error(`"${key}" must be a finite number >= ${min}`);
-                }
-                config[key] = value;
-            }
-        }
-        return config;
+        return {
+            shortcut: configuredShortcut(parsed),
+            brokerCommand: brokerCommand(parsed),
+            brokerArgs: configuredArgs(parsed),
+            confirmSend: configuredBoolean(parsed, "confirmSend"),
+            replyHint: configuredBoolean(parsed, "replyHint"),
+            status: configuredString(parsed, "status"),
+            askTimeoutMs: configuredTimeout(parsed, "askTimeoutMs"),
+            sendTimeoutMs: configuredTimeout(parsed, "sendTimeoutMs"),
+            listTimeoutMs: configuredTimeout(parsed, "listTimeoutMs"),
+        };
     }
     catch (error) {
         console.error(`Failed to load intercom config at ${configPath}:`, error);

package/dist/pi-intercom/connection.js

@@ -0,0 +1,297 @@
+import { createHash } from "node:crypto";
+import { IntercomClient } from "./broker/client.js";
+import { spawnBrokerIfNeeded } from "./broker/spawn.js";
+import { asError, errorMessage } from "./validation.js";
+import { formatTargetOptions, resolveSessionTarget } from "./session-targets.js";
+/** Owns socket registration, coalesced connects and the reconnect/startup timers. */
+export class IntercomConnection {
+    client = null;
+    reconnectTimer = null;
+    startupTimer = null;
+    connecting = null;
+    connectingGeneration = null;
+    attempt = 0;
+    syncError;
+    lifecycle;
+    config;
+    topics;
+    hooks;
+    constructor(lifecycle, config, topics, hooks) {
+        this.lifecycle = lifecycle;
+        this.config = config;
+        this.topics = topics;
+        this.hooks = hooks;
+    }
+    get active() {
+        return this.client;
+    }
+    get topicSyncError() {
+        return this.syncError;
+    }
+    get isConnecting() {
+        return this.startupTimer !== null || this.connecting !== null;
+    }
+    clearTopicSyncError() {
+        this.syncError = undefined;
+    }
+    start(ctx, generation) {
+        this.attempt = 0;
+        this.syncError = undefined;
+        this.clearTimers();
+        this.scheduleStartup(ctx, generation);
+    }
+    clearStartup() {
+        if (this.startupTimer) {
+            clearTimeout(this.startupTimer);
+            this.startupTimer = null;
+        }
+    }
+    clearReconnect() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+    }
+    clearTimers() {
+        this.clearStartup();
+        this.clearReconnect();
+    }
+    scheduleStartup(ctx, generation) {
+        this.clearStartup();
+        this.startupTimer = setTimeout(() => {
+            this.startupTimer = null;
+            if (!this.lifecycle.live(ctx, generation)) {
+                return;
+            }
+            this.ensure("startup").catch(() => {
+                if (!this.lifecycle.live(ctx, generation)) {
+                    return;
+                }
+                this.client = null;
+                this.scheduleReconnect();
+            });
+        }, 0);
+        this.startupTimer.unref();
+    }
+    scheduleReconnect() {
+        if (this.reconnectTimer || this.connecting || !this.lifecycle.live()) {
+            return;
+        }
+        const generation = this.lifecycle.generation;
+        const delays = [1000, 2000, 5000, 10000, 30000];
+        const delay = delays[Math.min(this.attempt, delays.length - 1)] ?? 30000;
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            if (this.lifecycle.generation !== generation || !this.lifecycle.live()) {
+                return;
+            }
+            this.attempt += 1;
+            this.ensure("background").catch(() => {
+                /* ensure owns the next retry after settlement. */
+            });
+        }, delay);
+        this.reconnectTimer.unref();
+    }
+    syncIdentity(sessionId) {
+        if (this.client && this.lifecycle.live()) {
+            this.client.updatePresence({
+                ...this.lifecycle.identity(sessionId),
+                status: this.lifecycle.status(),
+                ...this.lifecycle.health(this.hooks.pendingAsks()),
+            });
+        }
+    }
+    syncStatus() {
+        if (this.client && this.lifecycle.currentSessionId !== null && this.lifecycle.live()) {
+            this.client.updatePresence({
+                status: this.lifecycle.status(),
+                ...this.lifecycle.health(this.hooks.pendingAsks()),
+            });
+        }
+    }
+    createClient() {
+        const next = new IntercomClient({
+            sendTimeoutMs: this.config.sendTimeoutMs,
+            listTimeoutMs: this.config.listTimeoutMs,
+        });
+        this.client = next;
+        next.on("message", (from, message) => {
+            const ctx = this.lifecycle.live();
+            if (this.client !== next || !ctx) {
+                return;
+            }
+            this.hooks.incoming(ctx, from, message).catch((error) => {
+                console.error("Intercom inbound delivery failed:", error);
+            });
+        });
+        next.on("session_left", (id) => {
+            if (this.client !== next) {
+                return;
+            }
+            this.topics.disconnected(id);
+            this.hooks.peerLeft(id);
+        });
+        next.on("disconnected", (error) => {
+            if (this.client !== next) {
+                return;
+            }
+            this.hooks.disconnected(error);
+            this.client = null;
+            this.topics.disconnected();
+            this.clearReconnect();
+            this.scheduleReconnect();
+        });
+        next.on("error", () => {
+            /* Disconnect owns recovery; suppress socket noise in the TUI. */
+        });
+        return next;
+    }
+    async restoreTopics(active) {
+        const changes = [
+            ...[...this.topics.presence().topics].map((topic) => ({
+                action: "restore",
+                topic,
+            })),
+            ...[...this.topics.presence().subscriptions].map((subscription) => ({
+                action: "restore",
+                subscription,
+            })),
+        ];
+        let failure;
+        for (const change of changes) {
+            try {
+                // Restore order preserves publication/subscription admission and bounded transport pressure.
+                // oxlint-disable-next-line no-await-in-loop
+                await active.updateTopics(change);
+            }
+            catch (error) {
+                if (!active.isConnected()) {
+                    throw error;
+                }
+                failure ??= errorMessage(error);
+            }
+        }
+        return failure;
+    }
+    async synchronizeTopics(next, ctx, generation) {
+        if (!next.supportsTopics) {
+            this.topics.disconnected();
+            return;
+        }
+        const failure = await this.restoreTopics(next);
+        const sessions = await next.listSessions();
+        if (!this.lifecycle.live(ctx, generation)) {
+            return;
+        }
+        this.syncError = failure;
+        this.topics.refresh(sessions);
+        if (failure !== undefined && failure !== "" && next.sessionId !== null) {
+            this.topics.disconnected(next.sessionId);
+        }
+    }
+    async connect(reason, ctx, generation, sessionId) {
+        const next = this.createClient();
+        try {
+            if (reason !== "peer-awareness") {
+                await spawnBrokerIfNeeded(this.config.brokerCommand, this.config.brokerArgs);
+            }
+            await next.connect(await this.lifecycle.registration(this.hooks.pendingAsks()), `pi-${createHash("sha256").update(sessionId).digest("hex").slice(0, 32)}`);
+            if (!this.lifecycle.live(ctx, generation)) {
+                await next.disconnect();
+                throw new Error("Intercom runtime no longer active");
+            }
+            this.client = next;
+            this.syncIdentity(ctx.sessionManager.getSessionId());
+            this.attempt = 0;
+            await this.synchronizeTopics(next, ctx, generation);
+            return next;
+        }
+        catch (error) {
+            if (this.client === next) {
+                this.client = null;
+            }
+            // A failed topic snapshot can leave a registered socket alive; the attempt still owns it.
+            await next.disconnect().catch((cleanupError) => {
+                console.error("Intercom failed connection cleanup:", cleanupError);
+            });
+            throw asError(error);
+        }
+    }
+    async ensure(reason) {
+        const generation = this.lifecycle.generation;
+        const restoring = this.hooks.restoring();
+        if (restoring) {
+            await restoring;
+        }
+        const ctx = this.lifecycle.live();
+        if (!ctx || generation !== this.lifecycle.generation) {
+            throw new Error("Intercom shutting down");
+        }
+        if (this.connecting && this.connectingGeneration === generation) {
+            return this.connecting;
+        }
+        if (this.client?.isConnected() === true) {
+            return this.client;
+        }
+        const sessionId = this.lifecycle.currentSessionId;
+        if (sessionId === null) {
+            throw new Error("Intercom runtime not initialized");
+        }
+        this.clearReconnect();
+        // Publish ownership before registration, which can synchronously invoke subscribers.
+        const attempt = Promise.resolve().then(() => this.connect(reason, ctx, generation, sessionId));
+        this.connecting = attempt;
+        this.connectingGeneration = generation;
+        return await this.finishAttempt(attempt, ctx, generation);
+    }
+    async finishAttempt(attempt, ctx, generation) {
+        let retry = false;
+        try {
+            return await attempt;
+        }
+        catch (error) {
+            retry = this.lifecycle.live(ctx, generation) !== null;
+            throw error;
+        }
+        finally {
+            if (this.connecting === attempt) {
+                this.connecting = null;
+                this.connectingGeneration = null;
+            }
+            if (retry) {
+                this.scheduleReconnect();
+            }
+        }
+    }
+    async shutdown() {
+        this.clearTimers();
+        // The bounded launcher attempt is joined before socket shutdown.
+        await Promise.allSettled([this.connecting]);
+        if (this.client) {
+            await this.client.disconnect();
+            this.client = null;
+        }
+    }
+}
+export async function resolveConnectedTarget(active, name) {
+    const sessions = await active.listSessions();
+    const resolution = resolveSessionTarget(sessions, name);
+    if (resolution.status === "found" && resolution.target) {
+        return resolution.target.id;
+    }
+    if (resolution.status === "ambiguous") {
+        throw new Error(`Target "${name}" matches multiple sessions. Use one of these targets: ${formatTargetOptions(resolution.matches, sessions)}.`);
+    }
+    if (resolution.status === "prefix_too_short") {
+        throw new Error(`Target "${name}" is too short. Use the displayed target from intercom list, such as ${formatTargetOptions(resolution.matches, sessions)}.`);
+    }
+    return null;
+}
+export async function resolvePeerHealth(active, id) {
+    try {
+        return (await active.listSessions()).find((session) => session.id === id) ?? null;
+    }
+    catch {
+        return null; /* Unknown health must not skip an ordinary blocking reply. */
+    }
+}

package/dist/pi-intercom/identity.js

@@ -0,0 +1,58 @@
+function environmentText(name) {
+    return process.env[name]?.trim() ?? "";
+}
+export function readChildOrchestratorMetadata() {
+    const orchestratorTarget = environmentText("PI_SUBAGENT_ORCHESTRATOR_TARGET");
+    const runId = environmentText("PI_SUBAGENT_RUN_ID");
+    const agent = environmentText("PI_SUBAGENT_CHILD_AGENT");
+    const index = environmentText("PI_SUBAGENT_CHILD_INDEX");
+    if ([orchestratorTarget, runId, agent, index].includes("")) {
+        return null;
+    }
+    const sessionName = environmentText("PI_SUBAGENT_INTERCOM_SESSION_NAME");
+    return {
+        orchestratorTarget,
+        runId,
+        agent,
+        index,
+        ...(sessionName !== "" ? { sessionName } : {}),
+    };
+}
+export function formatChildOrchestratorMessage(kind, metadata, message) {
+    const headings = {
+        ask: "Subagent needs a supervisor decision.",
+        interview: "Subagent requests a structured supervisor interview.",
+        update: "Subagent progress update.",
+    };
+    return [
+        headings[kind],
+        `Run: ${metadata.runId}`,
+        `Agent: ${metadata.agent}`,
+        `Child index: ${metadata.index}`,
+        metadata.sessionName !== undefined && metadata.sessionName !== ""
+            ? `Child intercom target: ${metadata.sessionName}`
+            : undefined,
+        "",
+        message,
+    ]
+        .filter((line) => line !== undefined)
+        .join("\n");
+}
+export function resolveIntercomPresenceName(sessionName, sessionId) {
+    const name = sessionName?.trim();
+    if (name !== undefined && name !== "") {
+        return name;
+    }
+    const normalized = sessionId.startsWith("session-")
+        ? sessionId.slice("session-".length)
+        : sessionId;
+    return `subagent-chat-${normalized.slice(0, 8)}`;
+}
+export function buildPresenceIdentity(pi, sessionId) {
+    const name = process.env.PI_SUBAGENT_INTERCOM_SESSION_NAME?.trim();
+    return {
+        name: name !== undefined && name !== ""
+            ? name
+            : resolveIntercomPresenceName(pi.getSessionName(), sessionId),
+    };
+}