openclaw/src/agents/subagent-announce-output.ts

import { isSilentReplyText, SILENT_REPLY_TOKEN } from "../auto-reply/tokens.js";
import { extractTextFromChatContent } from "../shared/chat-content.js";
import { wrapPromptDataBlock } from "./sanitize-for-prompt.js";
import {
  captureSubagentCompletionReplyUsing,
  readLatestSubagentOutputWithRetryUsing,
} from "./subagent-announce-capture.js";
import {
  callGateway,
  getRuntimeConfig,
  loadSessionStore,
  resolveAgentIdFromSessionKey,
  resolveStorePath,
} from "./subagent-announce.runtime.js";
import { assistantCallsSessionsYield, isSessionsYieldToolResult } from "./subagent-yield-output.js";
import { readLatestAssistantReply } from "./tools/agent-step.js";
import { extractAssistantText, sanitizeTextContent } from "./tools/session-message-text.js";
import { isAnnounceSkip } from "./tools/sessions-send-tokens.js";

const FAST_TEST_RETRY_INTERVAL_MS = 8;

type SubagentAnnounceOutputDeps = {
  callGateway: typeof callGateway;
  getRuntimeConfig: typeof getRuntimeConfig;
  readLatestAssistantReply: typeof readLatestAssistantReply;
};

const defaultSubagentAnnounceOutputDeps: SubagentAnnounceOutputDeps = {
  callGateway,
  getRuntimeConfig,
  readLatestAssistantReply,
};

let subagentAnnounceOutputDeps: SubagentAnnounceOutputDeps = defaultSubagentAnnounceOutputDeps;

function isFastTestMode() {
  return process.env.OPENCLAW_TEST_FAST === "1";
}

type ToolResultMessage = {
  role?: unknown;
  content?: unknown;
};

type SubagentOutputSnapshot = {
  latestAssistantText?: string;
  latestSilentText?: string;
  latestRawText?: string;
  assistantFragments: string[];
  toolCallCount: number;
  waitingForContinuation?: boolean;
};

type AgentWaitResult = {
  status?: string;
  startedAt?: number;
  endedAt?: number;
  error?: string;
  stopReason?: string;
  livenessState?: string;
  yielded?: boolean;
};

export type SubagentRunOutcome = {
  status: "ok" | "error" | "timeout" | "unknown";
  error?: string;
  startedAt?: number;
  endedAt?: number;
  elapsedMs?: number;
};

function readFiniteNumber(value: number | undefined): number | undefined {
  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
}

export function withSubagentOutcomeTiming(
  outcome: SubagentRunOutcome,
  timing: {
    startedAt?: number;
    endedAt?: number;
  },
): SubagentRunOutcome {
  const startedAt = readFiniteNumber(timing.startedAt) ?? readFiniteNumber(outcome.startedAt);
  const endedAt = readFiniteNumber(timing.endedAt) ?? readFiniteNumber(outcome.endedAt);
  const nextTiming: Pick<SubagentRunOutcome, "startedAt" | "endedAt" | "elapsedMs"> = {};
  if (typeof startedAt === "number") {
    nextTiming.startedAt = startedAt;
  }
  if (typeof endedAt === "number") {
    nextTiming.endedAt = endedAt;
  }
  if (typeof startedAt === "number" && typeof endedAt === "number") {
    nextTiming.elapsedMs = Math.max(0, endedAt - startedAt);
  }
  return { ...outcome, ...nextTiming };
}

function extractToolResultText(content: unknown): string {
  if (typeof content === "string") {
    return sanitizeTextContent(content);
  }
  if (content && typeof content === "object" && !Array.isArray(content)) {
    const obj = content as {
      text?: unknown;
      output?: unknown;
      content?: unknown;
      result?: unknown;
      error?: unknown;
      summary?: unknown;
    };
    if (typeof obj.text === "string") {
      return sanitizeTextContent(obj.text);
    }
    if (typeof obj.output === "string") {
      return sanitizeTextContent(obj.output);
    }
    if (typeof obj.content === "string") {
      return sanitizeTextContent(obj.content);
    }
    if (typeof obj.result === "string") {
      return sanitizeTextContent(obj.result);
    }
    if (typeof obj.error === "string") {
      return sanitizeTextContent(obj.error);
    }
    if (typeof obj.summary === "string") {
      return sanitizeTextContent(obj.summary);
    }
  }
  if (!Array.isArray(content)) {
    return "";
  }
  const joined = extractTextFromChatContent(content, {
    sanitizeText: sanitizeTextContent,
    normalizeText: (text) => text,
    joinWith: "\n",
  });
  return joined?.trim() ?? "";
}

function extractInlineTextContent(content: unknown): string {
  if (!Array.isArray(content)) {
    return "";
  }
  return (
    extractTextFromChatContent(content, {
      sanitizeText: sanitizeTextContent,
      normalizeText: (text) => text.trim(),
      joinWith: "",
    }) ?? ""
  );
}

function extractSubagentOutputText(message: unknown): string {
  if (!message || typeof message !== "object") {
    return "";
  }
  const role = (message as { role?: unknown }).role;
  const content = (message as { content?: unknown }).content;
  if (role === "assistant") {
    if (typeof content === "string") {
      return sanitizeTextContent(content);
    }
    return extractAssistantText(message) ?? "";
  }
  if (role === "toolResult" || role === "tool") {
    return extractToolResultText((message as ToolResultMessage).content);
  }
  if (role == null) {
    if (typeof content === "string") {
      return sanitizeTextContent(content);
    }
    if (Array.isArray(content)) {
      return extractInlineTextContent(content);
    }
  }
  return "";
}

function countAssistantToolCalls(content: unknown): number {
  if (!Array.isArray(content)) {
    return 0;
  }
  let count = 0;
  for (const block of content) {
    if (!block || typeof block !== "object") {
      continue;
    }
    const type = (block as { type?: unknown }).type;
    if (
      type === "toolCall" ||
      type === "tool_use" ||
      type === "toolUse" ||
      type === "functionCall" ||
      type === "function_call"
    ) {
      count += 1;
    }
  }
  return count;
}

function summarizeSubagentOutputHistory(messages: Array<unknown>): SubagentOutputSnapshot {
  const snapshot: SubagentOutputSnapshot = {
    assistantFragments: [],
    toolCallCount: 0,
  };
  let previousAssistantCalledYield = false;
  for (const message of messages) {
    if (!message || typeof message !== "object") {
      continue;
    }
    const role = (message as { role?: unknown }).role;
    if (role === "assistant") {
      snapshot.toolCallCount += countAssistantToolCalls((message as { content?: unknown }).content);
      if (assistantCallsSessionsYield(message)) {
        snapshot.latestAssistantText = undefined;
        snapshot.latestRawText = undefined;
        snapshot.latestSilentText = undefined;
        snapshot.assistantFragments = [];
        snapshot.waitingForContinuation = true;
        previousAssistantCalledYield = true;
        continue;
      }
      const text = extractSubagentOutputText(message).trim();
      if (!text) {
        previousAssistantCalledYield = false;
        continue;
      }
      if (isAnnounceSkip(text) || isSilentReplyText(text, SILENT_REPLY_TOKEN)) {
        snapshot.latestSilentText = text;
        snapshot.latestAssistantText = undefined;
        snapshot.assistantFragments = [];
        snapshot.waitingForContinuation = false;
        previousAssistantCalledYield = false;
        continue;
      }
      snapshot.latestSilentText = undefined;
      snapshot.latestAssistantText = text;
      snapshot.assistantFragments.push(text);
      snapshot.waitingForContinuation = false;
      previousAssistantCalledYield = false;
      continue;
    }
    if (isSessionsYieldToolResult(message, previousAssistantCalledYield)) {
      snapshot.latestAssistantText = undefined;
      snapshot.latestRawText = undefined;
      snapshot.latestSilentText = undefined;
      snapshot.assistantFragments = [];
      snapshot.waitingForContinuation = true;
      previousAssistantCalledYield = false;
      continue;
    }
    const text = extractSubagentOutputText(message).trim();
    if (text) {
      snapshot.latestRawText = text;
      snapshot.waitingForContinuation = false;
    }
    previousAssistantCalledYield = false;
  }
  return snapshot;
}

function formatSubagentPartialProgress(
  snapshot: SubagentOutputSnapshot,
  outcome?: SubagentRunOutcome,
): string | undefined {
  if (snapshot.latestSilentText) {
    return undefined;
  }
  const timedOut = outcome?.status === "timeout";
  if (snapshot.assistantFragments.length === 0 && (!timedOut || snapshot.toolCallCount === 0)) {
    return undefined;
  }
  const parts: string[] = [];
  if (timedOut && snapshot.toolCallCount > 0) {
    parts.push(
      `[Partial progress: ${snapshot.toolCallCount} tool call(s) executed before timeout]`,
    );
  }
  if (snapshot.assistantFragments.length > 0) {
    parts.push(snapshot.assistantFragments.slice(-3).join("\n\n---\n\n"));
  }
  return parts.join("\n\n") || undefined;
}

function selectSubagentOutputText(
  snapshot: SubagentOutputSnapshot,
  outcome?: SubagentRunOutcome,
): string | undefined {
  if (snapshot.waitingForContinuation) {
    return undefined;
  }
  if (snapshot.latestSilentText) {
    return snapshot.latestSilentText;
  }
  if (snapshot.latestAssistantText) {
    return snapshot.latestAssistantText;
  }
  const partialProgress = formatSubagentPartialProgress(snapshot, outcome);
  if (partialProgress) {
    return partialProgress;
  }
  return snapshot.latestRawText;
}

export async function readSubagentOutput(
  sessionKey: string,
  outcome?: SubagentRunOutcome,
): Promise<string | undefined> {
  const history = await subagentAnnounceOutputDeps.callGateway({
    method: "chat.history",
    params: { sessionKey, limit: 100 },
  });
  const messages = Array.isArray(history?.messages) ? history.messages : [];
  const snapshot = summarizeSubagentOutputHistory(messages);
  const selected = selectSubagentOutputText(snapshot, outcome);
  if (selected?.trim()) {
    return selected;
  }
  if (snapshot.waitingForContinuation) {
    return undefined;
  }
  const latestAssistant = await subagentAnnounceOutputDeps.readLatestAssistantReply({
    sessionKey,
    limit: 100,
  });
  return latestAssistant?.trim() ? latestAssistant : undefined;
}

export async function readLatestSubagentOutputWithRetry(params: {
  sessionKey: string;
  maxWaitMs: number;
  outcome?: SubagentRunOutcome;
}): Promise<string | undefined> {
  return await readLatestSubagentOutputWithRetryUsing({
    sessionKey: params.sessionKey,
    maxWaitMs: params.maxWaitMs,
    outcome: params.outcome,
    retryIntervalMs: isFastTestMode() ? FAST_TEST_RETRY_INTERVAL_MS : 100,
    readSubagentOutput,
  });
}

export async function waitForSubagentRunOutcome(
  runId: string,
  timeoutMs: number,
): Promise<AgentWaitResult> {
  const waitMs = Math.max(0, Math.floor(timeoutMs));
  return await subagentAnnounceOutputDeps.callGateway({
    method: "agent.wait",
    params: {
      runId,
      timeoutMs: waitMs,
    },
    timeoutMs: waitMs + 2000,
  });
}

export function applySubagentWaitOutcome(params: {
  wait: AgentWaitResult | undefined;
  outcome: SubagentRunOutcome | undefined;
  startedAt?: number;
  endedAt?: number;
}) {
  const next = {
    outcome: params.outcome,
    startedAt: params.startedAt,
    endedAt: params.endedAt,
  };
  if (typeof params.wait?.startedAt === "number" && typeof next.startedAt !== "number") {
    next.startedAt = params.wait.startedAt;
  }
  if (typeof params.wait?.endedAt === "number" && typeof next.endedAt !== "number") {
    next.endedAt = params.wait.endedAt;
  }
  const waitError = typeof params.wait?.error === "string" ? params.wait.error : undefined;
  let outcome = next.outcome;
  if (params.wait?.status === "timeout") {
    outcome = { status: "timeout" };
  } else if (params.wait?.status === "error") {
    outcome = { status: "error", error: waitError };
  } else if (params.wait?.status === "ok") {
    outcome = { status: "ok" };
  }
  next.outcome = outcome ? withSubagentOutcomeTiming(outcome, next) : undefined;
  return next;
}

export async function captureSubagentCompletionReply(
  sessionKey: string,
  options?: { waitForReply?: boolean; outcome?: SubagentRunOutcome },
): Promise<string | undefined> {
  return await captureSubagentCompletionReplyUsing({
    sessionKey,
    waitForReply: options?.waitForReply,
    maxWaitMs: isFastTestMode() ? 50 : 1_500,
    retryIntervalMs: isFastTestMode() ? FAST_TEST_RETRY_INTERVAL_MS : 100,
    readSubagentOutput: async (nextSessionKey) =>
      await readSubagentOutput(nextSessionKey, options?.outcome),
  });
}

function describeSubagentOutcome(outcome?: SubagentRunOutcome): string {
  if (!outcome) {
    return "unknown";
  }
  if (outcome.status === "ok") {
    return "ok";
  }
  if (outcome.status === "timeout") {
    return "timeout";
  }
  if (outcome.status === "error") {
    return outcome.error?.trim() ? `error: ${outcome.error.trim()}` : "error";
  }
  return "unknown";
}

function formatChildResultData(resultText?: string | null): string {
  return (
    wrapPromptDataBlock({
      label: "Child result",
      text: resultText?.trim() || "(no output)",
    }) || "Child result: (no output)"
  );
}

export function buildChildCompletionFindings(
  children: Array<{
    childSessionKey: string;
    task: string;
    label?: string;
    createdAt: number;
    endedAt?: number;
    frozenResultText?: string | null;
    outcome?: SubagentRunOutcome;
  }>,
): string | undefined {
  const sorted = [...children].toSorted((a, b) => {
    if (a.createdAt !== b.createdAt) {
      return a.createdAt - b.createdAt;
    }
    const aEnded = typeof a.endedAt === "number" ? a.endedAt : Number.MAX_SAFE_INTEGER;
    const bEnded = typeof b.endedAt === "number" ? b.endedAt : Number.MAX_SAFE_INTEGER;
    return aEnded - bEnded;
  });

  const sections: string[] = [];
  for (const [index, child] of sorted.entries()) {
    const resultText = child.frozenResultText?.trim();
    const outcome = describeSubagentOutcome(child.outcome);
    if (
      child.outcome?.status === "ok" &&
      resultText &&
      (isAnnounceSkip(resultText) || isSilentReplyText(resultText, SILENT_REPLY_TOKEN))
    ) {
      continue;
    }
    const title =
      child.label?.trim() ||
      child.task.trim() ||
      child.childSessionKey.trim() ||
      `child ${index + 1}`;
    const displayIndex = sections.length + 1;
    sections.push(
      [`${displayIndex}. ${title}`, `status: ${outcome}`, formatChildResultData(resultText)].join(
        "\n",
      ),
    );
  }

  if (sections.length === 0) {
    return undefined;
  }

  return ["Child completion results:", "", ...sections].join("\n\n");
}

export function dedupeLatestChildCompletionRows(
  children: Array<{
    childSessionKey: string;
    task: string;
    label?: string;
    createdAt: number;
    endedAt?: number;
    frozenResultText?: string | null;
    outcome?: SubagentRunOutcome;
  }>,
) {
  const latestByChildSessionKey = new Map<string, (typeof children)[number]>();
  for (const child of children) {
    const existing = latestByChildSessionKey.get(child.childSessionKey);
    if (!existing || child.createdAt > existing.createdAt) {
      latestByChildSessionKey.set(child.childSessionKey, child);
    }
  }
  return [...latestByChildSessionKey.values()];
}

export function filterCurrentDirectChildCompletionRows(
  children: Array<{
    runId: string;
    childSessionKey: string;
    requesterSessionKey: string;
    task: string;
    label?: string;
    createdAt: number;
    endedAt?: number;
    frozenResultText?: string | null;
    outcome?: SubagentRunOutcome;
  }>,
  params: {
    requesterSessionKey: string;
    getLatestSubagentRunByChildSessionKey?: (childSessionKey: string) =>
      | {
          runId: string;
          requesterSessionKey: string;
        }
      | null
      | undefined;
  },
) {
  if (typeof params.getLatestSubagentRunByChildSessionKey !== "function") {
    return children;
  }
  return children.filter((child) => {
    const latest = params.getLatestSubagentRunByChildSessionKey?.(child.childSessionKey);
    if (!latest) {
      return true;
    }
    return (
      latest.runId === child.runId && latest.requesterSessionKey === params.requesterSessionKey
    );
  });
}

function formatDurationShort(valueMs?: number) {
  if (!valueMs || !Number.isFinite(valueMs) || valueMs <= 0) {
    return "n/a";
  }
  const totalSeconds = Math.round(valueMs / 1000);
  const hours = Math.floor(totalSeconds / 3600);
  const minutes = Math.floor((totalSeconds % 3600) / 60);
  const seconds = totalSeconds % 60;
  if (hours > 0) {
    return `${hours}h${minutes}m`;
  }
  if (minutes > 0) {
    return `${minutes}m${seconds}s`;
  }
  return `${seconds}s`;
}

function formatTokenCount(value?: number) {
  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
    return "0";
  }
  if (value >= 1_000_000) {
    return `${(value / 1_000_000).toFixed(1)}m`;
  }
  if (value >= 1_000) {
    return `${(value / 1_000).toFixed(1)}k`;
  }
  return String(Math.round(value));
}

export async function buildCompactAnnounceStatsLine(params: {
  sessionKey: string;
  startedAt?: number;
  endedAt?: number;
}) {
  const cfg = subagentAnnounceOutputDeps.getRuntimeConfig();
  const agentId = resolveAgentIdFromSessionKey(params.sessionKey);
  const storePath = resolveStorePath(cfg.session?.store, { agentId });
  let entry = loadSessionStore(storePath)[params.sessionKey];
  const tokenWaitAttempts = isFastTestMode() ? 1 : 3;
  for (let attempt = 0; attempt < tokenWaitAttempts; attempt += 1) {
    const hasTokenData =
      typeof entry?.inputTokens === "number" ||
      typeof entry?.outputTokens === "number" ||
      typeof entry?.totalTokens === "number";
    if (hasTokenData) {
      break;
    }
    if (!isFastTestMode()) {
      await new Promise((resolve) => setTimeout(resolve, 150));
    }
    entry = loadSessionStore(storePath)[params.sessionKey];
  }

  const input = typeof entry?.inputTokens === "number" ? entry.inputTokens : 0;
  const output = typeof entry?.outputTokens === "number" ? entry.outputTokens : 0;
  const ioTotal = input + output;
  const promptCache = typeof entry?.totalTokens === "number" ? entry.totalTokens : undefined;
  const runtimeMs =
    typeof params.startedAt === "number" && typeof params.endedAt === "number"
      ? Math.max(0, params.endedAt - params.startedAt)
      : undefined;

  const parts = [
    `runtime ${formatDurationShort(runtimeMs)}`,
    `tokens ${formatTokenCount(ioTotal)} (in ${formatTokenCount(input)} / out ${formatTokenCount(output)})`,
  ];
  if (typeof promptCache === "number" && promptCache > ioTotal) {
    parts.push(`prompt/cache ${formatTokenCount(promptCache)}`);
  }
  return `Stats: ${parts.join(" • ")}`;
}

export const __testing = {
  setDepsForTest(overrides?: Partial<SubagentAnnounceOutputDeps>) {
    subagentAnnounceOutputDeps = overrides
      ? {
          ...defaultSubagentAnnounceOutputDeps,
          ...overrides,
        }
      : defaultSubagentAnnounceOutputDeps;
  },
};