@ashx-j/lunr 0.2.21 → 0.2.23

package/dist/builtin-extensions/pi-subagents/src/intercom/native-supervisor-channel.js

@@ -4,9 +4,13 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { Type } from "typebox";
 import { SUBAGENT_CHILD_AGENT_ENV, SUBAGENT_CHILD_INDEX_ENV, SUBAGENT_ORCHESTRATOR_SESSION_ID_ENV, SUBAGENT_ORCHESTRATOR_TARGET_ENV, SUBAGENT_RUN_ID_ENV, SUBAGENT_SUPERVISOR_CHANNEL_DIR_ENV, SUBAGENT_SUPERVISOR_SESSION_ID_ENV, } from "../runs/shared/pi-args.js";
-import { INTERCOM_DETACH_REQUEST_EVENT, POLL_INTERVAL_MS, SUBAGENT_CONTROL_EVENT } from "../shared/types.js";
+import { ASYNC_DIR, INTERCOM_DETACH_REQUEST_EVENT, POLL_INTERVAL_MS, SUBAGENT_CONTROL_EVENT } from "../shared/types.js";
 import { writeAtomicJson } from "../shared/atomic-json.js";
 import { askRunningAsyncChild, reconcileAsyncQuestion } from "./supervisor-ask.js";
+import { CHILD_DESCRIPTION_ENV, SUPERVISOR_PROGRESS_TYPE, SUPERVISOR_PROTOCOL_VERSION, SUPERVISOR_REQUEST_TYPE, legacySupervisorBody, readCommunication, resolveCommunicationPeer, supervisorProtocolAvailable } from "./communication.js";
+import { renderCommunicationCall, renderCommunicationCard, renderCommunicationResult } from "../tui/communication.js";
+import { stopRequestPath } from "../runs/background/control-channel.js";
+import { readStatus } from "../shared/utils.js";
 import { answerSupervisorQuestion, cancelPendingSupervisorQuestionsForOwner, cancelSupervisorQuestion, claimQuestionNotification, formatSupervisorQuestionAnswer, hasOutstandingQuestionForChild, isQuestionWaitActive, listSupervisorChannelDirs, listSupervisorQuestions, markSupervisorQuestionDelivered, outstandingQuestionsForChild, pendingSupervisorQuestionsForDelivery, QUESTIONS_DIR, readSupervisorQuestion, resolveSupervisorChannelDir as resolveQuestionChannelDir, SUBAGENT_QUESTION_EVENT, SUBAGENT_SUPERVISOR_ANSWER_TYPE, SUPERVISOR_CHANNEL_ROOT, supervisorQuestionIsTerminal, supervisorQuestionPublicState, } from "./supervisor-questions.js";
 const REQUESTS_DIR = "requests";
 const REPLIES_DIR = "replies";
@@ -27,12 +31,14 @@ const PARENT_ASK_DESCRIPTION = [
     'Reply: { action: "reply", replyTo: "<requestId>", message: "..." }',
 ].join(" ");
 const CHILD_CONTACT_DESCRIPTION = [
-    "Contact the parent/supervisor session for a blocking decision, structured interview, progress update, or reply to a parent question.",
+    "Contact the supervisor for decisions outside your assigned authority, safety concerns, or blockers. Make reversible implementation choices within your scope yourself.",
+    "need_decision/interview_request wait for a reply: state the blocked decision, evidence, and recommended choice. Consolidate related questions; continue independent work before opening a blocking request.",
+    "Return one self-contained final report with outcomes, verification, blockers, and artifact paths; the runtime delivers it. Routine work already appears in activity indicators.",
     "For parent questions use action='reply' with replyTo set to the question id. Answer from current findings and uncertainty; do not start extra investigation just to reply. Continue the assigned task after replying.",
     "Do not open a blocking need_decision while a parent question is already outstanding for this child.",
 ].join(" ");
 const ContactSupervisorParamsSchema = Type.Object({
-    reason: Type.Optional(Type.String({ enum: ["need_decision", "interview_request", "progress_update"] })),
+    reason: Type.Optional(Type.String({ enum: ["need_decision", "interview_request", "progress_update", "handoff"] })),
     message: Type.Optional(Type.String()),
     interview: Type.Optional(Type.Unsafe({ type: "object", additionalProperties: true })),
     action: Type.Optional(Type.String({ enum: ["reply"] })),
@@ -87,6 +93,7 @@ function readChildMetadata() {
         orchestratorSessionId,
         supervisorSessionId: readTextEnv(SUBAGENT_SUPERVISOR_SESSION_ID_ENV),
         childTarget: readTextEnv("PI_SUBAGENT_INTERCOM_SESSION_NAME"),
+        description: readTextEnv(CHILD_DESCRIPTION_ENV),
     };
 }
 function readChildQuestionOwner(metadata = readChildMetadata()) {
@@ -124,10 +131,13 @@ function answerParentQuestion(params) {
             replyTo: answered.id,
             state: supervisorQuestionPublicState(answered),
             answered: true,
+            communication: { direction: "to", peer: "Supervisor", kind: "reply", message },
         },
     };
 }
 function reasonHeading(reason) {
+    if (reason === "handoff")
+        return "Subagent dependency handoff.";
     if (reason === "interview_request")
         return "Subagent requests a structured supervisor interview.";
     if (reason === "progress_update")
@@ -153,6 +163,39 @@ function formatChildMessage(input) {
     }
     return lines.join("\n").trimEnd();
 }
+function communicationKind(reason) {
+    return reason === "progress_update" ? "progress" : reason === "handoff" ? "handoff" : reason === "interview_request" ? "interview" : "request";
+}
+function communicationBody(message, interview, protocolVersion) {
+    const body = protocolVersion === SUPERVISOR_PROTOCOL_VERSION ? message : legacySupervisorBody(message);
+    return interview !== undefined && protocolVersion === SUPERVISOR_PROTOCOL_VERSION ? `${body}\n\n${JSON.stringify(interview, null, 2)}` : body;
+}
+function requestCommunication(request, state) {
+    return {
+        direction: "from",
+        peer: resolveCommunicationPeer(state, request.runId, request.childIndex, request.agent, request.description),
+        message: communicationBody(request.message, request.interview, request.protocolVersion),
+        kind: communicationKind(request.reason),
+    };
+}
+export function registerSupervisorRenderers(pi, state) {
+    for (const customType of [SUPERVISOR_REQUEST_TYPE, SUBAGENT_SUPERVISOR_ANSWER_TYPE]) {
+        pi.registerMessageRenderer(customType, (message, options, theme) => {
+            const details = message.details;
+            const communication = readCommunication(details?.communication) ?? {
+                direction: "from",
+                peer: details?.runId ? resolveCommunicationPeer(state, details.runId, details.childIndex ?? 0, details.childId ?? details.agent) : "Subagent",
+                message: legacySupervisorBody(typeof message.content === "string" ? message.content : message.content.filter((part) => part.type === "text").map((part) => part.text).join("\n")),
+                kind: customType === SUBAGENT_SUPERVISOR_ANSWER_TYPE ? "answer" : communicationKind(details?.reason),
+            };
+            return renderCommunicationCard(communication, options.expanded, theme);
+        });
+    }
+    pi.registerEntryRenderer(SUPERVISOR_PROGRESS_TYPE, (entry, options, theme) => {
+        const communication = readCommunication(entry.data?.communication);
+        return communication ? renderCommunicationCard(communication, options.expanded, theme) : undefined;
+    });
+}
 function parseStructuredReply(message) {
     const trimmed = message.trim();
     const fenced = trimmed.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/i)?.[1]?.trim();
@@ -214,21 +257,29 @@ async function sendSupervisorRequest(params, signal) {
         throw new Error("Native supervisor channel is not available for this subagent.");
     if (!params.reason)
         throw new Error("reason is required for supervisor contact.");
-    if (params.reason !== "progress_update" && hasOutstandingQuestionForChild(metadata.channelDir, metadata.childIndex, metadata.agent)) {
+    if (signal?.aborted)
+        throw new Error("Supervisor request cancelled.");
+    const protocolVersion = supervisorProtocolAvailable() ? SUPERVISOR_PROTOCOL_VERSION : undefined;
+    if (params.reason === "handoff" && !protocolVersion)
+        throw new Error("This supervisor uses the legacy protocol. Send actionable findings with progress_update instead.");
+    const expectsReply = params.reason === "need_decision" || params.reason === "interview_request";
+    if (expectsReply && hasOutstandingQuestionForChild(metadata.channelDir, metadata.childIndex, metadata.agent)) {
         throw new Error("A parent question is already outstanding for this child. Answer it with action='reply' before opening a blocking supervisor request.");
     }
-    if (params.reason !== "progress_update" && !params.message?.trim() && params.reason !== "interview_request") {
-        throw new Error("message is required for supervisor decisions.");
+    if (!params.message?.trim() && params.reason !== "interview_request") {
+        throw new Error("message is required for supervisor contact.");
     }
     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 = formatChildMessage({ ...metadata, reason: params.reason, message: params.message, interview: params.interview });
+    const message = protocolVersion ? params.message?.trim() || "Structured supervisor input requested." : formatChildMessage({ ...metadata, reason: params.reason, message: params.message, interview: params.interview });
+    const communication = { direction: "to", peer: "Supervisor", kind: communicationKind(params.reason), message: communicationBody(message, params.interview, protocolVersion) };
     const request = {
         type: "subagent.supervisor.request",
+        ...(protocolVersion ? { protocolVersion } : {}),
+        ...(metadata.description ? { description: metadata.description } : {}),
         id: requestId,
         createdAt,
         ...(expiresAt !== undefined ? { expiresAt } : {}),
@@ -255,13 +306,13 @@ async function sendSupervisorRequest(params, signal) {
     }
     if (!expectsReply) {
         return {
-            content: [{ type: "text", text: "Supervisor progress update queued." }],
-            details: { delivered: true, requestId, reason: params.reason },
+            content: [{ type: "text", text: params.reason === "handoff" ? "Dependency handoff queued. Continue independent work." : protocolVersion ? "Progress recorded for the UI only; the supervisor model will not receive it." : "Supervisor progress update queued." }],
+            details: { queued: true, requestId, reason: params.reason, communication },
         };
     }
     try {
         const reply = await waitForReply(metadata.channelDir, requestId, replyDeadline, signal);
-        const details = { requestId, reason: params.reason };
+        const details = { requestId, reason: params.reason, communication, response: reply.message };
         if (params.reason === "interview_request") {
             const structured = parseStructuredReply(reply.message);
             if (structured.error)
@@ -295,8 +346,16 @@ export function registerNativeSupervisorClient(pi, options = {}) {
         const tool = {
             name: "contact_supervisor",
             label: "Contact Supervisor",
-            description: CHILD_CONTACT_DESCRIPTION,
-            parameters: ContactSupervisorParamsSchema,
+            description: `${CHILD_CONTACT_DESCRIPTION} ${supervisorProtocolAvailable()
+                ? "handoff delivers actionable dependency findings or corrections without waiting: state what changes and consolidate evidence or reference one artifact. progress_update is UI-only and never reaches the supervisor model."
+                : "This legacy supervisor delivers progress_update to its model. Reserve it for actionable dependency findings or corrections."}`,
+            parameters: supervisorProtocolAvailable() ? ContactSupervisorParamsSchema : Type.Object({ ...ContactSupervisorParamsSchema.properties, reason: Type.Optional(Type.String({ enum: ["need_decision", "interview_request", "progress_update"] })) }, { additionalProperties: false }),
+            renderCall(args, theme, context) {
+                return renderCommunicationCall("contact_supervisor", args, theme, context, { direction: "to", peer: "Supervisor", kind: args.action === "reply" ? "reply" : communicationKind(args.reason), message: communicationBody(args.message ?? "", args.interview, SUPERVISOR_PROTOCOL_VERSION) });
+            },
+            renderResult(result, options, theme, context) {
+                return renderCommunicationResult(result.content, result.details, options.expanded, context.isError, theme);
+            },
             execute(_id, params, signal) {
                 return sendSupervisorRequest(params, signal);
             },
@@ -307,8 +366,14 @@ export function registerNativeSupervisorClient(pi, options = {}) {
         const tool = {
             name: "intercom",
             label: "Intercom",
-            description: "Native supervisor-channel intercom fallback for subagents. Prefer contact_supervisor when available.",
+            description: "Supervisor-only fallback; sibling discovery and sibling messaging are unavailable. Use contact_supervisor for decisions, replies, and dependency handoffs. list reports no sibling sessions; ask blocks for a supervisor decision; send is progress only.",
             parameters: IntercomParamsSchema,
+            renderCall(args, theme, context) {
+                return renderCommunicationCall("intercom", args, theme, context, args.message ? { direction: "to", peer: "Supervisor", kind: args.action === "ask" ? "request" : "progress", message: args.message } : undefined);
+            },
+            renderResult(result, options, theme, context) {
+                return renderCommunicationResult(result.content, result.details, options.expanded, context.isError, theme);
+            },
             async execute(_id, params, signal) {
                 const action = params.action;
                 if (action === "status")
@@ -334,7 +399,15 @@ function parseRequestFile(file, channelDir) {
             return undefined;
         if (typeof parsed.id !== "string" || !parsed.id)
             return undefined;
-        if (parsed.reason !== "need_decision" && parsed.reason !== "interview_request" && parsed.reason !== "progress_update")
+        if (parsed.reason !== "need_decision" && parsed.reason !== "interview_request" && parsed.reason !== "progress_update" && parsed.reason !== "handoff")
+            return undefined;
+        if (parsed.protocolVersion !== undefined && parsed.protocolVersion !== SUPERVISOR_PROTOCOL_VERSION)
+            return undefined;
+        if (parsed.protocolVersion === SUPERVISOR_PROTOCOL_VERSION && parsed.expectsReply !== (parsed.reason === "need_decision" || parsed.reason === "interview_request"))
+            return undefined;
+        if (parsed.reason === "handoff" && parsed.protocolVersion !== SUPERVISOR_PROTOCOL_VERSION)
+            return undefined;
+        if (parsed.description !== undefined && typeof parsed.description !== "string")
             return undefined;
         if (typeof parsed.message !== "string" || !parsed.message)
             return undefined;
@@ -516,21 +589,24 @@ function requestExpiresAt(request, now) {
         return expiresAt;
     return Number.isFinite(request.createdAt) ? request.createdAt + askTimeoutMs() : now;
 }
-function requestRunInactive(request, state) {
+function requestRunState(request, state) {
     if (state.foregroundControls.has(request.runId))
-        return false;
+        return "active";
     const foregroundRun = state.foregroundRuns?.get(request.runId);
     const foregroundChild = foregroundRun?.children.find((child) => child.index === request.childIndex && child.agent === request.agent)
         ?? foregroundRun?.children[request.childIndex];
     if (foregroundChild)
-        return foregroundChild.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";
+        return foregroundChild.status === "stopped" ? "stopped" : foregroundChild.status === "detached" ? "active" : "inactive";
+    const job = state.asyncJobs.get(request.runId) ?? state.fleetJobs?.get(request.runId);
+    const asyncDir = job?.asyncDir ?? path.join(ASYNC_DIR, safeSegment(request.runId));
+    const status = readStatus(asyncDir);
+    const runStatus = status?.state ?? job?.status;
+    const stepStatus = (status?.steps ?? job?.steps)?.[request.childIndex]?.status;
+    if (fs.existsSync(stopRequestPath(asyncDir)) || runStatus === "stopped" || job?.status === "stopped" || status?.stopped || stepStatus === "stopped")
+        return "stopped";
+    if (["complete", "failed", "paused"].includes(runStatus ?? "") || ["complete", "completed", "failed", "paused"].includes(stepStatus ?? ""))
+        return "inactive";
+    return "active";
 }
 function requestLifecycle(request, state, ctx, now) {
     if (ctx && !requestMatchesContext(request, state, ctx))
@@ -541,7 +617,8 @@ function requestLifecycle(request, state, ctx, now) {
         return "resolved";
     if (request.expectsReply && now > requestExpiresAt(request, now))
         return "expired";
-    if (request.expectsReply && requestRunInactive(request, state))
+    const runState = requestRunState(request, state);
+    if (runState === "stopped" || (request.expectsReply && runState === "inactive"))
         return "inactive";
     return "pending";
 }
@@ -563,8 +640,10 @@ function formatPendingLine(request) {
     const replyHint = request.expectsReply ? ` Reply: ${NATIVE_SUPERVISOR_TOOL_NAME}({ action: "reply", replyTo: "${request.id}", message: "..." })` : "";
     return `- ${request.id}: ${request.agent} [${request.runId}#${request.childIndex}] ${request.reason}.${replyHint}`;
 }
-function requestVisibleText(request) {
-    const lines = [request.message];
+function requestVisibleText(request, communication) {
+    const lines = [`From: ${communication.peer}`, "", communication.message];
+    if (request.reason === "interview_request")
+        lines.push("", "Reply with JSON matching the requested interview shape.");
     if (request.expectsReply) {
         lines.push("", `Reply with: ${NATIVE_SUPERVISOR_TOOL_NAME}({ action: "reply", replyTo: "${request.id}", message: "..." })`);
     }
@@ -622,6 +701,14 @@ function buildParentIntercomTool(pending, state, name = "intercom") {
         label: name === "intercom" ? "Intercom" : "Subagent Supervisor",
         description: PARENT_ASK_DESCRIPTION,
         parameters: ParentSupervisorParamsSchema,
+        renderCall(args, theme, context) {
+            const request = args.action === "reply" ? pending.get(args.replyTo) : undefined;
+            const peer = request ? requestCommunication(request, state).peer : args.id ? resolveCommunicationPeer(state, args.id, args.index ?? 0, args.childId) : "Subagent";
+            return renderCommunicationCall(name, args, theme, context, args.message ? { direction: "to", peer, message: args.message, kind: args.action === "ask" ? "question" : "reply" } : undefined);
+        },
+        renderResult(result, options, theme, context) {
+            return renderCommunicationResult(result.content, result.details, options.expanded, context.isError, theme);
+        },
         async execute(_id, params) {
             refreshPendingRequests(pending, state, state.lastUiContext ?? undefined);
             const input = params;
@@ -636,7 +723,7 @@ function buildParentIntercomTool(pending, state, name = "intercom") {
                 const request = resolvePendingRequest(pending, input);
                 writeReply(request, input.message ?? "");
                 pending.delete(request.id);
-                return { content: [{ type: "text", text: `Replied to supervisor request ${request.id}.` }], details: { replyTo: request.id, runId: request.runId, agent: request.agent } };
+                return { content: [{ type: "text", text: `Replied to ${requestCommunication(request, state).peer}.` }], details: { replyTo: request.id, runId: request.runId, agent: request.agent, communication: { ...requestCommunication(request, state), direction: "to", kind: "reply", message: input.message } } };
             }
             if (input.action === "ask") {
                 return askRunningAsyncChild({
@@ -666,7 +753,7 @@ function questionMatchesParentContext(question, state, ctx) {
         return false;
     return true;
 }
-function notifyQuestionTerminal(pi, question, channelDir) {
+function notifyQuestionTerminal(pi, question, channelDir, state) {
     if (!supervisorQuestionIsTerminal(question) || question.notifiedAt)
         return;
     pi.events?.emit(SUBAGENT_QUESTION_EVENT, {
@@ -678,22 +765,24 @@ function notifyQuestionTerminal(pi, question, channelDir) {
         return;
     if (!claimQuestionNotification(channelDir, question.id))
         return;
-    const state = supervisorQuestionPublicState(question);
+    const outcome = supervisorQuestionPublicState(question);
+    const communication = { direction: "from", peer: question.childDescription ?? resolveCommunicationPeer(state, question.runId, question.childIndex, question.childId), message: question.answer ?? question.cancelReason ?? outcome, kind: "answer" };
     pi.sendMessage({
         customType: SUBAGENT_SUPERVISOR_ANSWER_TYPE,
         content: formatSupervisorQuestionAnswer(question),
-        display: state === "answered",
+        display: outcome === "answered",
         details: {
             questionId: question.id,
-            state,
+            state: outcome,
+            communication,
             runId: question.runId,
             childIndex: question.childIndex,
             childId: question.childId,
             reason: question.reason,
-            answered: state === "answered",
+            answered: outcome === "answered",
             delivered: Boolean(question.deliveredAt),
         },
-    }, { triggerTurn: state === "answered" });
+    }, { triggerTurn: outcome === "answered" });
 }
 function pollSupervisorQuestions(pi, state, ctx) {
     for (const channelDir of listSupervisorChannelDirs()) {
@@ -701,13 +790,14 @@ function pollSupervisorQuestions(pi, state, ctx) {
             if (!questionMatchesParentContext(question, state, ctx))
                 continue;
             const current = reconcileAsyncQuestion(channelDir, question, state);
-            notifyQuestionTerminal(pi, current, channelDir);
+            notifyQuestionTerminal(pi, current, channelDir, state);
         }
     }
 }
 export function createNativeSupervisorChannel(pi, state) {
     const pending = new Map();
     const seenFiles = new Set();
+    const deliveredRequests = new Set();
     let poller;
     let lastStaleCleanupAt = 0;
     const registerParentTools = () => {
@@ -766,25 +856,37 @@ export function createNativeSupervisorChannel(pi, state) {
                 cleanupRequestLifecycle(request, lifecycle);
                 continue;
             }
-            seenFiles.add(file);
             if (request.expectsReply)
                 pending.set(request.id, request);
+            if (deliveredRequests.has(request.id)) {
+                seenFiles.add(file);
+                continue;
+            }
+            const communication = requestCommunication(request, state);
+            const details = {
+                id: request.id,
+                reason: request.reason,
+                expectsReply: request.expectsReply,
+                runId: request.runId,
+                agent: request.agent,
+                childIndex: request.childIndex,
+                communication,
+            };
+            if (request.reason === "progress_update" && request.protocolVersion === SUPERVISOR_PROTOCOL_VERSION) {
+                pi.appendEntry(SUPERVISOR_PROGRESS_TYPE, details);
+            }
             else {
-                removeRequestFile(request.requestFile);
+                pi.sendMessage({
+                    customType: SUPERVISOR_REQUEST_TYPE,
+                    content: requestVisibleText(request, communication),
+                    display: true,
+                    details,
+                }, { triggerTurn: request.expectsReply || request.reason === "handoff" });
             }
-            pi.sendMessage({
-                customType: "subagent_supervisor_request",
-                content: requestVisibleText(request),
-                display: true,
-                details: {
-                    id: request.id,
-                    reason: request.reason,
-                    expectsReply: request.expectsReply,
-                    runId: request.runId,
-                    agent: request.agent,
-                    childIndex: request.childIndex,
-                },
-            });
+            deliveredRequests.add(request.id);
+            seenFiles.add(file);
+            if (!request.expectsReply)
+                removeRequestFile(request.requestFile);
             if (request.expectsReply) {
                 const job = state.asyncJobs.get(request.runId);
                 if (job)
@@ -811,6 +913,12 @@ export function createNativeSupervisorChannel(pi, state) {
             if (poller)
                 return;
             registerParentTools();
+            for (const entry of state.lastUiContext?.sessionManager.getBranch?.() ?? []) {
+                const data = entry.type === "custom_message" && entry.customType === SUPERVISOR_REQUEST_TYPE ? entry.details
+                    : entry.type === "custom" && entry.customType === SUPERVISOR_PROGRESS_TYPE ? entry.data : undefined;
+                if (data && typeof data === "object" && "id" in data && typeof data.id === "string")
+                    deliveredRequests.add(data.id);
+            }
             poll();
             poller = setInterval(poll, CHANNEL_POLL_MS);
             poller.unref?.();
@@ -822,6 +930,7 @@ export function createNativeSupervisorChannel(pi, state) {
             poller = undefined;
             pending.clear();
             seenFiles.clear();
+            deliveredRequests.clear();
         },
         pending,
         cancelOwnedQuestions,