pi-subagents 0.68.0 → 0.70.0

package/src/intercom/native-supervisor-channel.js

@@ -0,0 +1,894 @@
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { Type } from "typebox";
+import { INTERCOM_DETACH_REQUEST_EVENT, POLL_INTERVAL_MS, TEMP_ROOT_DIR } from "../shared/types.js";
+import { writeAtomicJson } from "../shared/atomic-json.js";
+import { shouldUseNativeFsWatch } from "../shared/watch-strategy.js";
+import { SUPERVISOR_REQUEST_MESSAGE_TYPE, SUPERVISOR_REPLY_ENTRY_TYPE, supervisorReplyHint, } from "./supervisor-ui.js";
+const SUPERVISOR_CHANNEL_ROOT = path.join(TEMP_ROOT_DIR, "supervisor-channels");
+const REQUESTS_DIR = "requests";
+const REPLIES_DIR = "replies";
+export const NATIVE_SUPERVISOR_TOOL_NAME = "subagent_supervisor";
+const MAX_MESSAGE_BYTES = 64 * 1024;
+const DEFAULT_ASK_TIMEOUT_MS = 10 * 60 * 1000;
+const CHANNEL_POLL_MS = Math.min(POLL_INTERVAL_MS, 500);
+const CHANNEL_SAFETY_POLL_MS = 5000;
+const STALE_EMPTY_CHANNEL_AGE_MS = 60 * 1000;
+const STALE_EMPTY_CHANNEL_CLEANUP_INTERVAL_MS = 60 * 1000;
+const MAX_SUPERVISOR_REQUEST_CORRELATIONS = 256;
+const SUPERVISOR_REQUEST_CORRELATION_RETENTION_MS = 10 * 60 * 1000;
+const ContactSupervisorParamsSchema = Type.Object({
+    reason: Type.String({ enum: ["need_decision", "interview_request", "progress_update"] }),
+    message: Type.Optional(Type.String()),
+    interview: Type.Optional(Type.Unsafe({ type: "object", additionalProperties: true })),
+}, { additionalProperties: false });
+const IntercomParamsSchema = Type.Object({
+    action: Type.String({ enum: ["list", "pending", "status", "reply"] }),
+    to: Type.Optional(Type.String()),
+    message: Type.Optional(Type.String()),
+    replyTo: Type.Optional(Type.String()),
+}, { additionalProperties: false });
+function safeSegment(value) {
+    return value.trim().replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "unknown";
+}
+export function resolveSupervisorChannelDir(runId, agent, childIndex) {
+    return path.join(SUPERVISOR_CHANNEL_ROOT, `${safeSegment(runId)}-${safeSegment(agent)}-${childIndex}`);
+}
+export function ensureSupervisorChannelDir(channelDir) {
+    fs.mkdirSync(path.join(channelDir, REQUESTS_DIR), { recursive: true, mode: 0o700 });
+    fs.mkdirSync(path.join(channelDir, REPLIES_DIR), { recursive: true, mode: 0o700 });
+}
+function requestPath(channelDir, requestId) {
+    return path.join(channelDir, REQUESTS_DIR, `${safeSegment(requestId)}.json`);
+}
+function replyPath(channelDir, requestId) {
+    return path.join(channelDir, REPLIES_DIR, `${safeSegment(requestId)}.json`);
+}
+function reasonHeading(reason) {
+    if (reason === "interview_request")
+        return "Subagent requests a structured supervisor interview.";
+    if (reason === "progress_update")
+        return "Subagent progress update.";
+    return "Subagent needs a supervisor decision.";
+}
+function parseStructuredReply(message) {
+    const trimmed = message.trim();
+    const fenced = trimmed.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/i)?.[1]?.trim();
+    try {
+        return { value: JSON.parse(fenced ?? trimmed) };
+    }
+    catch (error) {
+        return { error: error instanceof Error ? `${error.name}: ${error.message}` : String(error) };
+    }
+}
+function askTimeoutMs() {
+    const parsed = Number(process.env.PI_INTERCOM_ASK_TIMEOUT_MS);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_ASK_TIMEOUT_MS;
+}
+function delay(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new Error("Supervisor request cancelled."));
+            return;
+        }
+        let timer;
+        const cleanup = () => {
+            if (timer)
+                clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+        };
+        const onAbort = () => {
+            cleanup();
+            reject(new Error("Supervisor request cancelled."));
+        };
+        timer = setTimeout(() => {
+            cleanup();
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+async function waitForReply(channelDir, requestId, deadline, signal) {
+    const file = replyPath(channelDir, requestId);
+    while (Date.now() <= deadline) {
+        if (signal?.aborted)
+            throw new Error("Supervisor request cancelled.");
+        if (fs.existsSync(file)) {
+            const parsed = JSON.parse(fs.readFileSync(file, "utf-8"));
+            if (parsed.type === "subagent.supervisor.reply" && parsed.requestId === requestId && typeof parsed.message === "string") {
+                return parsed;
+            }
+        }
+        await delay(250, signal);
+    }
+    throw new Error("Timed out waiting for supervisor reply.");
+}
+async function sendSupervisorRequest(params, metadata, signal, toolCallId) {
+    if (!params.message?.trim() && params.reason !== "interview_request") {
+        throw new Error("message is required for supervisor decisions and progress updates.");
+    }
+    ensureSupervisorChannelDir(metadata.channelDir);
+    const requestId = randomUUID();
+    const expectsReply = params.reason !== "progress_update";
+    const createdAt = Date.now();
+    const replyDeadline = createdAt + askTimeoutMs();
+    const expiresAt = expectsReply ? replyDeadline : undefined;
+    const message = params.message?.trim() ?? "";
+    const requestToolCallId = typeof toolCallId === "string" && toolCallId.length > 0 ? toolCallId : undefined;
+    const request = {
+        type: "subagent.supervisor.request",
+        id: requestId,
+        createdAt,
+        ...(expiresAt !== undefined ? { expiresAt } : {}),
+        reason: params.reason,
+        message,
+        expectsReply,
+        ...(metadata.orchestratorTarget ? { orchestratorTarget: metadata.orchestratorTarget } : {}),
+        ...(metadata.orchestratorSessionId ? { orchestratorSessionId: metadata.orchestratorSessionId } : {}),
+        runId: metadata.runId,
+        agent: metadata.agent,
+        childIndex: metadata.childIndex,
+        ...(requestToolCallId ? { toolCallId: requestToolCallId } : {}),
+        ...(metadata.childTarget ? { childTarget: metadata.childTarget } : {}),
+        ...(params.interview !== undefined ? { interview: params.interview } : {}),
+    };
+    const serialized = JSON.stringify(request, null, "\t");
+    if (Buffer.byteLength(serialized, "utf-8") > MAX_MESSAGE_BYTES)
+        throw new Error("Supervisor request is too large.");
+    writeAtomicJson(requestPath(metadata.channelDir, requestId), request);
+    if (!expectsReply) {
+        return {
+            content: [{ type: "text", text: "Supervisor progress update queued." }],
+            details: { delivered: true, requestId, reason: params.reason },
+        };
+    }
+    try {
+        const reply = await waitForReply(metadata.channelDir, requestId, replyDeadline, signal);
+        const details = { requestId, reason: params.reason };
+        if (params.reason === "interview_request") {
+            const structured = parseStructuredReply(reply.message);
+            if (structured.error)
+                details.structuredReplyParseError = structured.error;
+            else
+                details.structuredReply = structured.value;
+        }
+        return {
+            content: [{ type: "text", text: `**Reply from supervisor:**\n${reply.message}` }],
+            details,
+        };
+    }
+    catch (error) {
+        removeRequestFile(requestPath(metadata.channelDir, requestId));
+        throw error;
+    }
+}
+function hasTool(pi, name) {
+    try {
+        return pi.getAllTools?.().some((tool) => tool.name === name) === true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Register the child-side `contact_supervisor` tool. The host passes the
+ * channel metadata in the child runtime config.
+ */
+export function registerNativeSupervisorClient(pi, metadata) {
+    if (!metadata || hasTool(pi, "contact_supervisor"))
+        return;
+    const tool = {
+        name: "contact_supervisor",
+        label: "Contact Supervisor",
+        description: "Contact the parent/supervisor session for a blocking decision, structured interview, or progress update.",
+        parameters: ContactSupervisorParamsSchema,
+        execute(id, params, signal) {
+            return sendSupervisorRequest(params, metadata, signal, id);
+        },
+    };
+    pi.registerTool(tool);
+}
+function parseRequestFile(file, channelDir) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf-8"));
+        if (parsed.type !== "subagent.supervisor.request")
+            return undefined;
+        if (typeof parsed.id !== "string" || !parsed.id)
+            return undefined;
+        if (parsed.reason !== "need_decision" && parsed.reason !== "interview_request" && parsed.reason !== "progress_update")
+            return undefined;
+        if (typeof parsed.message !== "string" || (!parsed.message.trim() && parsed.reason !== "interview_request"))
+            return undefined;
+        if (typeof parsed.runId !== "string" || typeof parsed.agent !== "string" || typeof parsed.childIndex !== "number")
+            return undefined;
+        return {
+            ...parsed,
+            ...(typeof parsed.toolCallId === "string" && parsed.toolCallId.length > 0 ? { toolCallId: parsed.toolCallId } : { toolCallId: undefined }),
+            channelDir,
+            requestFile: file,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function isMissingSupervisorDirectory(error, platform) {
+    const code = error.code;
+    return code === "ENOENT" || (platform === "win32" && code === "UNKNOWN");
+}
+function listRequestFiles(channelDirs, platform) {
+    if (!channelDirs) {
+        try {
+            channelDirs = fs.readdirSync(SUPERVISOR_CHANNEL_ROOT, { withFileTypes: true })
+                .filter(entry => entry.isDirectory()).map(entry => path.join(SUPERVISOR_CHANNEL_ROOT, entry.name));
+        }
+        catch (error) {
+            if (isMissingSupervisorDirectory(error, platform))
+                return [];
+            throw error;
+        }
+    }
+    const files = [];
+    for (const channelDir of channelDirs) {
+        const requestsDir = path.join(channelDir, REQUESTS_DIR);
+        let requestEntries;
+        try {
+            requestEntries = fs.readdirSync(requestsDir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const requestEntry of requestEntries) {
+            if (requestEntry.isFile() && requestEntry.name.endsWith(".json"))
+                files.push({ channelDir, file: path.join(requestsDir, requestEntry.name) });
+        }
+    }
+    return files;
+}
+function readDirectoryEntries(dir, platform) {
+    try {
+        return fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch (error) {
+        if (isMissingSupervisorDirectory(error, platform))
+            return [];
+        return undefined;
+    }
+}
+function directoryMtimeMs(dir) {
+    try {
+        return fs.statSync(dir).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+}
+function removeEmptyDirectory(dir) {
+    try {
+        fs.rmdirSync(dir);
+        return true;
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT")
+            return true;
+        if (code === "ENOTEMPTY" || code === "EEXIST" || code === "EPERM" || code === "EBUSY")
+            return false;
+        throw error;
+    }
+}
+function removeStaleEmptySupervisorChannel(channelDir, nowMs, platform) {
+    const requestsDir = path.join(channelDir, REQUESTS_DIR);
+    const repliesDir = path.join(channelDir, REPLIES_DIR);
+    const newestKnownMtimeMs = Math.max(directoryMtimeMs(channelDir), directoryMtimeMs(requestsDir), directoryMtimeMs(repliesDir));
+    if (nowMs - newestKnownMtimeMs < STALE_EMPTY_CHANNEL_AGE_MS)
+        return false;
+    const requestEntries = readDirectoryEntries(requestsDir, platform);
+    if (!requestEntries || requestEntries.length > 0)
+        return false;
+    const replyEntries = readDirectoryEntries(repliesDir, platform);
+    if (!replyEntries || replyEntries.length > 0)
+        return false;
+    if (!removeEmptyDirectory(requestsDir))
+        return false;
+    if (!removeEmptyDirectory(repliesDir))
+        return false;
+    if (!removeEmptyDirectory(channelDir))
+        return false;
+    return true;
+}
+function cleanupStaleEmptySupervisorChannels(nowMs = Date.now(), platform = process.platform) {
+    let channelEntries;
+    try {
+        channelEntries = fs.readdirSync(SUPERVISOR_CHANNEL_ROOT, { withFileTypes: true });
+    }
+    catch (error) {
+        if (isMissingSupervisorDirectory(error, platform))
+            return 0;
+        throw error;
+    }
+    let removed = 0;
+    for (const entry of channelEntries) {
+        if (!entry.isDirectory())
+            continue;
+        try {
+            if (removeStaleEmptySupervisorChannel(path.join(SUPERVISOR_CHANNEL_ROOT, entry.name), nowMs, platform))
+                removed++;
+        }
+        catch {
+            // Cleanup is opportunistic; active writers can race with us and will be picked up by a later pass.
+        }
+    }
+    return removed;
+}
+function requestMatchesOwner(request, state) {
+    const currentSessionId = state.supervisorOwnerSessionId;
+    return Boolean(currentSessionId && request.orchestratorSessionId === currentSessionId);
+}
+function rememberedForegroundChild(request, state) {
+    const run = state.foregroundRuns?.get(request.runId);
+    const child = run?.children.find((candidate) => candidate.index === request.childIndex && candidate.agent === request.agent)
+        ?? run?.children[request.childIndex];
+    return run && child ? { run, child } : undefined;
+}
+function markForegroundSupervisorAttention(request, state) {
+    const remembered = rememberedForegroundChild(request, state);
+    if (!remembered || remembered.child.status !== "detached")
+        return;
+    const updatedAt = Date.now();
+    remembered.run.updatedAt = updatedAt;
+    remembered.child.activityState = "needs_attention";
+    remembered.child.lastActivityAt = request.createdAt;
+    remembered.child.currentTool = "contact_supervisor";
+    remembered.child.currentToolStartedAt = request.createdAt;
+    remembered.child.updatedAt = updatedAt;
+}
+function clearForegroundSupervisorAttention(request, pending, state) {
+    if ([...pending.values()].some((candidate) => candidate.expectsReply
+        && candidate.runId === request.runId
+        && candidate.agent === request.agent
+        && candidate.childIndex === request.childIndex))
+        return;
+    const remembered = rememberedForegroundChild(request, state);
+    if (!remembered || remembered.child.status !== "detached")
+        return;
+    const updatedAt = Date.now();
+    remembered.run.updatedAt = updatedAt;
+    remembered.child.activityState = undefined;
+    remembered.child.lastActivityAt = updatedAt;
+    remembered.child.currentTool = undefined;
+    remembered.child.currentToolStartedAt = undefined;
+    remembered.child.updatedAt = updatedAt;
+}
+function removeRequestFile(file) {
+    try {
+        fs.rmSync(file, { force: true });
+    }
+    catch {
+        // Request cleanup is best-effort; reply files and timeout errors remain authoritative.
+    }
+}
+function requestExpiresAt(request, now) {
+    const expiresAt = request.expiresAt;
+    if (typeof expiresAt === "number" && Number.isFinite(expiresAt))
+        return expiresAt;
+    return Number.isFinite(request.createdAt) ? request.createdAt + askTimeoutMs() : now;
+}
+function requestRunInactive(request, state) {
+    if (state.foregroundControls.has(request.runId))
+        return false;
+    const foreground = rememberedForegroundChild(request, state);
+    if (foreground)
+        return foreground.child.status !== "detached";
+    const asyncJob = state.asyncJobs.get(request.runId);
+    if (!asyncJob)
+        return false;
+    if (asyncJob.status === "complete" || asyncJob.status === "failed" || asyncJob.status === "paused")
+        return true;
+    const stepStatus = asyncJob.steps?.[request.childIndex]?.status;
+    return stepStatus === "complete" || stepStatus === "completed" || stepStatus === "failed" || stepStatus === "paused";
+}
+function requestLifecycle(request, state, now, runState) {
+    if (!requestMatchesOwner(request, state))
+        return "wrong-session";
+    if (!fs.existsSync(request.requestFile))
+        return "missing";
+    if (request.expectsReply && fs.existsSync(replyPath(request.channelDir, request.id)))
+        return "resolved";
+    if (request.expectsReply && now > requestExpiresAt(request, now))
+        return "expired";
+    if (request.expectsReply && requestRunInactive(request, runState))
+        return "inactive";
+    return "pending";
+}
+function cleanupRequestLifecycle(request, lifecycle) {
+    if (lifecycle === "resolved" || lifecycle === "expired" || lifecycle === "inactive")
+        removeRequestFile(request.requestFile);
+}
+function refreshPendingRequests(pending, state, onLifecycle, runState) {
+    const now = Date.now();
+    for (const request of pending.values()) {
+        const lifecycle = requestLifecycle(request, state, now, runState(request));
+        if (lifecycle === "pending")
+            continue;
+        pending.delete(request.id);
+        onLifecycle(request, lifecycle);
+        cleanupRequestLifecycle(request, lifecycle);
+    }
+}
+function formatPendingLine(request) {
+    const replyHint = request.expectsReply ? ` Reply: ${supervisorReplyHint(request.id)}` : "";
+    return `- ${request.id}: ${request.agent} [${request.runId}#${request.childIndex}] ${request.reason}.${replyHint}`;
+}
+function requestVisibleText(request) {
+    const lines = [
+        reasonHeading(request.reason),
+        `Run: ${request.runId}`,
+        `Agent: ${request.agent}`,
+        `Child index: ${request.childIndex}`,
+    ];
+    lines.push("");
+    if (request.message)
+        lines.push(request.message);
+    if (request.reason === "interview_request") {
+        lines.push("", "Structured response requested. Reply with JSON, optionally fenced in ```json, matching the requested interview shape.");
+        if (request.interview !== undefined)
+            lines.push(JSON.stringify(request.interview, null, "\t"));
+    }
+    if (request.expectsReply)
+        lines.push("", `Reply with: ${supervisorReplyHint(request.id)}`);
+    lines.push("", `Live guidance: subagent({ action: "steer", id: ${JSON.stringify(request.runId)}, index: ${request.childIndex}, message: "..." })${request.expectsReply ? " (Reply to the pending request first.)" : ""}`);
+    return lines.join("\n").trimEnd();
+}
+function writeReply(request, message) {
+    if (!message.trim())
+        throw new Error("message is required for supervisor replies.");
+    const reply = {
+        type: "subagent.supervisor.reply",
+        requestId: request.id,
+        createdAt: Date.now(),
+        message: message.trim(),
+    };
+    writeAtomicJson(replyPath(request.channelDir, request.id), reply);
+    removeRequestFile(request.requestFile);
+    return reply;
+}
+function appendSupervisorReplyEntry(pi, request, reply) {
+    const appendEntry = pi.appendEntry;
+    if (typeof appendEntry !== "function")
+        return;
+    try {
+        appendEntry.call(pi, SUPERVISOR_REPLY_ENTRY_TYPE, {
+            requestId: request.id,
+            reason: request.reason,
+            runId: request.runId,
+            agent: request.agent,
+            childIndex: request.childIndex,
+            ...(request.childTarget ? { childTarget: request.childTarget } : {}),
+            message: reply.message,
+            createdAt: reply.createdAt,
+        });
+    }
+    catch (error) {
+        // The reply file is authoritative; a UI journal failure must not undo a delivered reply.
+        console.error("Failed to journal native supervisor reply:", error);
+    }
+}
+function resolvePendingRequest(pending, params) {
+    if (params.replyTo) {
+        const request = pending.get(params.replyTo);
+        if (!request)
+            throw new Error(`No pending supervisor request found for replyTo '${params.replyTo}'.`);
+        return request;
+    }
+    const requests = [...pending.values()].filter((request) => request.expectsReply);
+    if (params.to) {
+        const normalizedTo = params.to.toLowerCase();
+        const matches = requests.filter((request) => request.id.toLowerCase().startsWith(normalizedTo)
+            || request.agent.toLowerCase() === normalizedTo
+            || request.childTarget?.toLowerCase() === normalizedTo);
+        if (matches.length === 1)
+            return matches[0];
+        if (matches.length > 1)
+            throw new Error(`Multiple pending supervisor requests match '${params.to}'. Use replyTo.`);
+        throw new Error(`No pending supervisor request matches '${params.to}'. Use replyTo.`);
+    }
+    if (requests.length === 1)
+        return requests[0];
+    if (requests.length === 0)
+        throw new Error("No pending supervisor requests need a reply.");
+    throw new Error("Multiple pending supervisor requests need replies. Use replyTo.");
+}
+function publicPendingRequests(pending) {
+    return [...pending.values()].map((request) => ({
+        id: request.id,
+        runId: request.runId,
+        agent: request.agent,
+        childIndex: request.childIndex,
+        reason: request.reason,
+        expectsReply: request.expectsReply,
+    }));
+}
+function buildParentSupervisorTool(pi, pending, state, onLifecycle, discover, runState) {
+    return {
+        name: NATIVE_SUPERVISOR_TOOL_NAME,
+        label: "Subagent Supervisor",
+        description: "Native pi-subagents supervisor channel. Use reply/pending/status to answer child subagent requests without overriding pi-intercom.",
+        parameters: IntercomParamsSchema,
+        async execute(_id, params) {
+            // Discover new request files even when demand-gated polling is idle.
+            discover();
+            refreshPendingRequests(pending, state, onLifecycle, runState);
+            const input = params;
+            if (input.action === "status") {
+                return { content: [{ type: "text", text: `Native supervisor channel active. Pending replies: ${pending.size}.` }], details: { active: true, pending: pending.size, root: SUPERVISOR_CHANNEL_ROOT } };
+            }
+            if (input.action === "pending" || input.action === "list") {
+                const lines = [...pending.values()].filter((request) => request.expectsReply).map(formatPendingLine);
+                return { content: [{ type: "text", text: lines.length ? lines.join("\n") : "No pending supervisor requests." }], details: { pending: publicPendingRequests(pending) } };
+            }
+            if (input.action === "reply") {
+                const request = resolvePendingRequest(pending, input);
+                const reply = writeReply(request, input.message ?? "");
+                appendSupervisorReplyEntry(pi, request, reply);
+                onLifecycle(request, "resolved");
+                pending.delete(request.id);
+                clearForegroundSupervisorAttention(request, pending, state);
+                return { content: [{ type: "text", text: `Replied to supervisor request ${request.id}.` }], details: { replyTo: request.id, runId: request.runId, agent: request.agent } };
+            }
+            throw new Error(`Unsupported supervisor action: ${input.action}`);
+        },
+    };
+}
+export function createNativeSupervisorChannel(pi, state, deps = {}) {
+    const watch = deps.watch ?? fs.watch;
+    const timers = deps.timers ?? globalThis;
+    const runState = (request) => {
+        for (const ownerState of deps.getCurrentOwnerStates?.() ?? []) {
+            if (ownerState.asyncJobs.has(request.runId))
+                return ownerState;
+        }
+        return state;
+    };
+    const pending = new Map();
+    const requestCorrelations = new Map();
+    const correlationKey = (request) => {
+        if (!request.toolCallId)
+            return undefined;
+        return JSON.stringify([request.runId, request.agent, request.childIndex, request.toolCallId]);
+    };
+    const pruneRequestCorrelations = (now = Date.now()) => {
+        for (const [key, correlation] of requestCorrelations) {
+            if (correlation.state === "resolved" && now - correlation.updatedAt > SUPERVISOR_REQUEST_CORRELATION_RETENTION_MS)
+                requestCorrelations.delete(key);
+        }
+        while (requestCorrelations.size > MAX_SUPERVISOR_REQUEST_CORRELATIONS) {
+            const oldest = requestCorrelations.keys().next().value;
+            if (oldest === undefined)
+                break;
+            requestCorrelations.delete(oldest);
+        }
+    };
+    const rememberPendingRequest = (request) => {
+        const key = correlationKey(request);
+        if (!key || !request.expectsReply)
+            return;
+        requestCorrelations.set(key, { request, state: "pending", updatedAt: Date.now() });
+        pruneRequestCorrelations();
+    };
+    const rememberResolvedRequest = (request) => {
+        const key = correlationKey(request);
+        if (!key || !request.expectsReply)
+            return;
+        requestCorrelations.set(key, { request, state: "resolved", updatedAt: Date.now() });
+        pruneRequestCorrelations();
+    };
+    const observeRequestLifecycle = (request, lifecycle) => {
+        if (lifecycle !== "wrong-session")
+            rememberResolvedRequest(request);
+    };
+    const getSupervisorRequestState = (event) => {
+        if (event.currentTool === "intercom" || event.index === undefined)
+            return "unknown";
+        const toolCallId = typeof event.toolCallId === "string" && event.toolCallId.length > 0 ? event.toolCallId : undefined;
+        if (!toolCallId)
+            return "unknown";
+        pruneRequestCorrelations();
+        const key = correlationKey({ runId: event.runId, agent: event.agent, childIndex: event.index, toolCallId });
+        if (!key)
+            return "unknown";
+        const correlation = requestCorrelations.get(key);
+        if (!correlation)
+            return "unknown";
+        if (correlation.state === "resolved")
+            return "resolved";
+        const now = Date.now();
+        if (!fs.existsSync(correlation.request.requestFile)
+            || fs.existsSync(replyPath(correlation.request.channelDir, correlation.request.id))
+            || now > requestExpiresAt(correlation.request, now)
+            || requestRunInactive(correlation.request, runState(correlation.request))) {
+            rememberResolvedRequest(correlation.request);
+            return "resolved";
+        }
+        return "pending";
+    };
+    const seenFiles = new Set();
+    const requestWatchers = new Map();
+    let rootWatcher;
+    let poller;
+    let safetyPoller;
+    let deferredWatcherRefresh;
+    let started = false;
+    let lastStaleCleanupAt = 0;
+    const platform = deps.platform ?? process.platform;
+    const useNativeWatcher = () => !deps.getChannelDirs && shouldUseNativeFsWatch("supervisor-channel", platform) && platform !== "win32";
+    const hasTransportDemand = () => {
+        if (pending.size > 0)
+            return true;
+        if (state.foregroundControls.size > 0)
+            return true;
+        if (deps.getChannelDirs?.().dirs.length)
+            return true;
+        if ([...state.asyncJobs.values()].some((job) => job.status === "queued" || job.status === "running"))
+            return true;
+        for (const ownerState of deps.getCurrentOwnerStates?.() ?? []) {
+            for (const job of ownerState.asyncJobs.values()) {
+                if (job.status === "queued" || job.status === "running")
+                    return true;
+            }
+        }
+        return false;
+    };
+    const registerParentTools = () => {
+        if (!hasTool(pi, NATIVE_SUPERVISOR_TOOL_NAME))
+            pi.registerTool(buildParentSupervisorTool(pi, pending, state, observeRequestLifecycle, () => poll(), runState));
+    };
+    const cleanupStaleChannelsIfDue = () => {
+        if (deps.getChannelDirs)
+            return; // The root owns global retention cleanup.
+        const nowMs = Date.now();
+        if (nowMs - lastStaleCleanupAt < STALE_EMPTY_CHANNEL_CLEANUP_INTERVAL_MS)
+            return;
+        lastStaleCleanupAt = nowMs;
+        try {
+            cleanupStaleEmptySupervisorChannels(nowMs, platform);
+        }
+        catch {
+            // Supervisor delivery must not fail because best-effort temp cleanup failed.
+        }
+    };
+    const poll = () => {
+        cleanupStaleChannelsIfDue();
+        // Only display notifications require a live UI context, not request registration.
+        refreshPendingRequests(pending, state, observeRequestLifecycle, runState);
+        const now = Date.now();
+        const channels = deps.getChannelDirs?.();
+        for (const { channelDir, file } of listRequestFiles(channels?.dirs, platform)) {
+            if (seenFiles.has(file))
+                continue;
+            const request = parseRequestFile(file, channelDir);
+            if (!request || !requestMatchesOwner(request, state))
+                continue;
+            const lifecycle = requestLifecycle(request, state, now, runState(request));
+            if (lifecycle !== "pending") {
+                seenFiles.add(file);
+                observeRequestLifecycle(request, lifecycle);
+                cleanupRequestLifecycle(request, lifecycle);
+                continue;
+            }
+            seenFiles.add(file);
+            if (!request.expectsReply) {
+                // Progress is already visible through child activity; do not inject a
+                // parent message or trigger a parent model turn.
+                removeRequestFile(request.requestFile);
+                continue;
+            }
+            rememberPendingRequest(request);
+            pending.set(request.id, request);
+            markForegroundSupervisorAttention(request, state);
+            // The ask is already queued above. A sendMessage failure (no UI, stale context) must not
+            // lose it, and must not abort the loop before the remaining asks register.
+            try {
+                pi.sendMessage({
+                    customType: SUPERVISOR_REQUEST_MESSAGE_TYPE,
+                    content: requestVisibleText(request),
+                    display: true,
+                    details: {
+                        id: request.id,
+                        requestId: request.id,
+                        reason: request.reason,
+                        expectsReply: request.expectsReply,
+                        runId: request.runId,
+                        agent: request.agent,
+                        childIndex: request.childIndex,
+                        ...(request.childTarget ? { childTarget: request.childTarget } : {}),
+                        ...(request.interview !== undefined ? { interview: request.interview } : {}),
+                        requestBody: request.message,
+                        replyHint: supervisorReplyHint(request.id),
+                    },
+                }, { triggerTurn: true });
+            }
+            catch (error) {
+                console.error(`Failed to surface supervisor request ${request.id} as a user turn:`, error);
+            }
+            pi.events?.emit(INTERCOM_DETACH_REQUEST_EVENT, {
+                requestId: request.id,
+                runId: request.runId,
+                agent: request.agent,
+                childIndex: request.childIndex,
+            });
+            if (pending.has(request.id))
+                markForegroundSupervisorAttention(request, state);
+        }
+        channels?.retire?.();
+    };
+    const startPolling = () => {
+        if (poller)
+            return;
+        poller = timers.setInterval(() => {
+            poll();
+            if (!useNativeWatcher() && (platform === "darwin" || deps.getChannelDirs) && !hasTransportDemand()) {
+                if (poller)
+                    timers.clearInterval(poller);
+                poller = undefined;
+            }
+        }, CHANNEL_POLL_MS);
+        poller.unref?.();
+    };
+    const startSafetyPolling = () => {
+        if (safetyPoller)
+            return;
+        safetyPoller = timers.setInterval(() => {
+            watchExistingRequestDirs();
+            poll();
+        }, CHANNEL_SAFETY_POLL_MS);
+        safetyPoller.unref?.();
+    };
+    const watchRequestDir = (requestsDir) => {
+        if (requestWatchers.has(requestsDir))
+            return;
+        try {
+            const watcher = watch(requestsDir, () => poll());
+            watcher.on("error", () => {
+                try {
+                    watcher.close();
+                }
+                catch { }
+                requestWatchers.delete(requestsDir);
+                startPolling();
+            });
+            watcher.unref?.();
+            requestWatchers.set(requestsDir, watcher);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                startPolling();
+        }
+    };
+    const watchExistingRequestDirs = () => {
+        let channelEntries;
+        try {
+            channelEntries = fs.readdirSync(SUPERVISOR_CHANNEL_ROOT, { withFileTypes: true });
+        }
+        catch (error) {
+            if (isMissingSupervisorDirectory(error, platform))
+                return;
+            startPolling();
+            return;
+        }
+        for (const entry of channelEntries) {
+            if (entry.isDirectory())
+                watchRequestDir(path.join(SUPERVISOR_CHANNEL_ROOT, entry.name, REQUESTS_DIR));
+        }
+    };
+    const scheduleWatcherRefresh = () => {
+        if (deferredWatcherRefresh)
+            return;
+        deferredWatcherRefresh = timers.setImmediate(() => {
+            deferredWatcherRefresh = undefined;
+            if (!started)
+                return;
+            watchExistingRequestDirs();
+            poll();
+        });
+        deferredWatcherRefresh.unref?.();
+    };
+    return {
+        registerTools: registerParentTools,
+        activateTransport: () => {
+            if (!started)
+                return;
+            poll();
+            if (!useNativeWatcher() && hasTransportDemand())
+                startPolling();
+        },
+        findPendingAsks: (target) => {
+            // Receipt-only discovery: no registration, notification, cleanup or reply writes.
+            const channelDir = resolveSupervisorChannelDir(target.runId, target.agent, target.childIndex);
+            let files;
+            try {
+                files = fs.readdirSync(path.join(channelDir, REQUESTS_DIR));
+            }
+            catch (error) {
+                if (isMissingSupervisorDirectory(error, platform))
+                    return [];
+                throw error;
+            }
+            const now = Date.now();
+            return files.filter(file => file.endsWith(".json")).flatMap(file => {
+                const request = parseRequestFile(path.join(channelDir, REQUESTS_DIR, file), channelDir);
+                return request?.expectsReply && request.runId === target.runId
+                    && request.agent === target.agent && request.childIndex === target.childIndex
+                    && requestLifecycle(request, state, now, runState(request)) === "pending" ? [request.id] : [];
+            }).sort();
+        },
+        hasPendingRequests: () => {
+            if (!started)
+                return false;
+            poll();
+            return pending.size > 0;
+        },
+        start: () => {
+            if (started)
+                return;
+            started = true;
+            registerParentTools();
+            poll();
+            if (deps.getChannelDirs)
+                return; // Child polling starts only after a descendant launch.
+            try {
+                fs.mkdirSync(SUPERVISOR_CHANNEL_ROOT, { recursive: true });
+                if (!useNativeWatcher()) {
+                    if (platform === "win32")
+                        startPolling();
+                    return;
+                }
+                watchExistingRequestDirs();
+                rootWatcher = watch(SUPERVISOR_CHANNEL_ROOT, () => {
+                    watchExistingRequestDirs();
+                    poll();
+                    scheduleWatcherRefresh();
+                });
+                rootWatcher.on("error", startPolling);
+                startSafetyPolling();
+                scheduleWatcherRefresh();
+            }
+            catch {
+                startPolling();
+            }
+        },
+        dispose: () => {
+            started = false;
+            try {
+                rootWatcher?.close();
+            }
+            catch {
+                // Best effort during shutdown.
+            }
+            rootWatcher = undefined;
+            for (const watcher of requestWatchers.values()) {
+                try {
+                    watcher.close();
+                }
+                catch { }
+            }
+            requestWatchers.clear();
+            if (poller)
+                timers.clearInterval(poller);
+            poller = undefined;
+            if (safetyPoller)
+                timers.clearInterval(safetyPoller);
+            safetyPoller = undefined;
+            if (deferredWatcherRefresh)
+                timers.clearImmediate(deferredWatcherRefresh);
+            deferredWatcherRefresh = undefined;
+            pending.clear();
+            requestCorrelations.clear();
+            seenFiles.clear();
+        },
+        pending,
+        getSupervisorRequestState,
+    };
+}
+//# sourceMappingURL=native-supervisor-channel.js.map