sailfork / t3code-github / packages/ provider-core/ src/ server/ notification.ts

import type {
  OrchestrationV2ConversationMessage,
  OrchestrationV2Notification,
  OrchestrationV2NotificationSource,
  OrchestrationV2Subagent,
  OrchestrationV2TurnItem,
  ThreadId,
} from "@t3tools/contracts";

type NotificationOutcome = OrchestrationV2Notification["outcome"];

export type BackgroundWork = {
  readonly label?: string | undefined;
} & (
  | { readonly kind: "subagent"; readonly childThreadId?: ThreadId | undefined }
  | { readonly kind: "command"; readonly exitCode?: number | undefined }
  | { readonly kind: "monitor" }
  | { readonly kind: "background_task" }
);

export type BackgroundWorkReport = BackgroundWork & { readonly outcome: NotificationOutcome };

const LABEL_MAX_LENGTH = 80;

export function reportLabel(label: string | undefined): string | undefined {
  const firstLine = label?.trim().split("\n")[0]?.trim();
  if (firstLine === undefined || firstLine.length === 0) return undefined;
  if (firstLine.length <= LABEL_MAX_LENGTH) return firstLine;
  let end = LABEL_MAX_LENGTH - 1;
  const previous = firstLine.charCodeAt(end - 1);
  const next = firstLine.charCodeAt(end);
  if (previous >= 0xd800 && previous <= 0xdbff && next >= 0xdc00 && next <= 0xdfff) {
    end -= 1;
  }
  return `${firstLine.slice(0, end)}…`;
}

const KIND_NOUN: Record<BackgroundWork["kind"], readonly [string, string]> = {
  subagent: ["Subagent", "subagents"],
  command: ["Command", "commands"],
  monitor: ["Monitor", "monitors"],
  background_task: ["Background task", "background tasks"],
};

function outcomeVerb(kind: BackgroundWork["kind"], outcome: NotificationOutcome) {
  switch (outcome) {
    case "failed":
      return "failed";
    case "cancelled":
      return "was stopped";
    case "updated":
      return kind === "monitor" ? "reported new output" : "updated";
    case "completed":
    case "unknown":
      return "finished";
  }
}

function combinedOutcome(outcomes: ReadonlyArray<NotificationOutcome>): NotificationOutcome {
  if (outcomes.includes("failed")) return "failed";
  if (outcomes.includes("cancelled")) return "cancelled";
  if (outcomes.length > 0 && outcomes.every((outcome) => outcome === "completed")) {
    return "completed";
  }
  return outcomes.includes("updated") ? "updated" : "unknown";
}

function exitSuffix(report: BackgroundWorkReport): string {
  return report.kind === "command" && report.exitCode !== undefined
    ? ` (exit ${report.exitCode})`
    : "";
}

function namedReport(report: BackgroundWorkReport, capitalize: boolean): string {
  const noun = KIND_NOUN[report.kind][0];
  const label = reportLabel(report.label);
  const named = `${capitalize ? noun : noun.toLowerCase()}${label === undefined ? "" : ` "${label}"`}`;
  return `${named}${exitSuffix(report)}`;
}

function joinNames(names: ReadonlyArray<string>): string {
  if (names.length <= 1) return names.join("");
  return `${names.slice(0, -1).join(", ")} and ${names.at(-1)}`;
}

function reportsSummary(
  reports: readonly [BackgroundWorkReport, ...ReadonlyArray<BackgroundWorkReport>],
  outcome: NotificationOutcome,
): string {
  const [first] = reports;
  if (reports.length === 1) {
    const label = reportLabel(first.label);
    const noun = KIND_NOUN[first.kind][0];
    return `${noun}${label === undefined ? "" : ` "${label}"`} ${outcomeVerb(first.kind, first.outcome)}${exitSuffix(first)}`;
  }
  const verb =
    outcome === "failed"
      ? "failed"
      : outcome === "cancelled"
        ? "were stopped"
        : outcome === "updated"
          ? "updated"
          : "finished";
  if (reports.length > 3 || reports.every((report) => reportLabel(report.label) === undefined)) {
    const kinds = new Set(reports.map((report) => report.kind));
    const noun = kinds.size === 1 ? KIND_NOUN[first.kind][1] : "background tasks";
    return `${reports.length} ${noun} ${verb}`;
  }
  return `${joinNames(reports.map((report, index) => namedReport(report, index === 0)))} ${verb}`;
}

function reportsSource(
  reports: readonly [BackgroundWorkReport, ...ReadonlyArray<BackgroundWorkReport>],
): OrchestrationV2NotificationSource {
  const [first, ...rest] = reports;
  if (rest.some((report) => report.kind !== first.kind)) return { kind: "background_task" };
  switch (first.kind) {
    case "subagent":
      return rest.length === 0 && first.childThreadId !== undefined
        ? { kind: "subagent", childThreadId: first.childThreadId }
        : { kind: "subagent" };
    case "command":
    case "monitor":
    case "background_task":
      return { kind: first.kind };
  }
}

export function backgroundWorkNotification(
  reports: readonly [BackgroundWorkReport, ...ReadonlyArray<BackgroundWorkReport>],
): OrchestrationV2Notification;
export function backgroundWorkNotification(
  reports: ReadonlyArray<BackgroundWorkReport>,
): OrchestrationV2Notification | null;
export function backgroundWorkNotification(
  reports: ReadonlyArray<BackgroundWorkReport>,
): OrchestrationV2Notification | null {
  const [first, ...rest] = reports;
  if (first === undefined) return null;
  const outcome = combinedOutcome(reports.map((report) => report.outcome));
  return {
    source: reportsSource([first, ...rest]),
    outcome,
    summary: reportsSummary([first, ...rest], outcome),
  };
}

function delegatedTaskReport(
  task: OrchestrationV2Subagent | undefined,
): Extract<BackgroundWorkReport, { readonly kind: "subagent" }> {
  const outcome: NotificationOutcome =
    task?.status === "failed"
      ? "failed"
      : task?.status === "cancelled" || task?.status === "interrupted"
        ? "cancelled"
        : task?.status === "completed"
          ? "completed"
          : "unknown";
  return {
    kind: "subagent",
    label: task?.title?.trim() || task?.prompt,
    outcome,
    ...(task?.childThreadId == null ? {} : { childThreadId: task.childThreadId }),
  };
}

function delegatedCompletionNotification(
  completion: NonNullable<OrchestrationV2ConversationMessage["delegatedCompletion"]>,
  tasks: ReadonlyArray<OrchestrationV2Subagent>,
): OrchestrationV2Notification {
  const taskIds = completion.taskIds;
  const reports = taskIds.map((taskId) =>
    delegatedTaskReport(tasks.find((task) => task.id === taskId)),
  );
  const delegatedByRun = tasks.filter(
    (task) => task.origin === "app_owned" && task.runId === completion.parentRunId,
  ).length;
  const outcome = combinedOutcome(reports.map((report) => report.outcome));
  const verb = outcome === "failed" ? "failed" : outcome === "cancelled" ? "stopped" : "finished";
  const [only] = reports;
  if (reports.length === 1 && only !== undefined) {
    const label = reportLabel(only.label);
    return {
      source: {
        kind: "delegated_task",
        taskIds,
        ...(only.childThreadId === undefined ? {} : { childThreadId: only.childThreadId }),
      },
      outcome,
      summary: `Delegated task${label === undefined ? "" : ` "${label}"`} ${verb}`,
    };
  }
  const labels = reports.flatMap((report) => reportLabel(report.label) ?? []);
  const count =
    delegatedByRun > taskIds.length
      ? `${taskIds.length} of ${delegatedByRun}`
      : `${taskIds.length}`;
  return {
    source: { kind: "delegated_task", taskIds },
    outcome,
    summary: `${count} delegated tasks ${verb}${labels.length === 0 ? "" : `: ${labels.join(", ")}`}`,
  };
}

export function notificationTurnItem(
  item: OrchestrationV2TurnItem,
  message: Pick<OrchestrationV2ConversationMessage, "notification" | "delegatedCompletion">,
  tasks: ReadonlyArray<OrchestrationV2Subagent>,
): OrchestrationV2TurnItem {
  if (item.type !== "user_message") return item;
  const notification =
    message.delegatedCompletion === undefined
      ? message.notification
      : delegatedCompletionNotification(message.delegatedCompletion, tasks);
  if (notification === undefined) return item;
  const {
    type: _type,
    messageId: _messageId,
    inputIntent: _inputIntent,
    text: _text,
    attachments: _attachments,
    createdBy: _createdBy,
    creationSource: _creationSource,
    scheduledTaskId: _scheduledTaskId,
    modelSwitch: _modelSwitch,
    ...base
  } = item;
  return { ...base, type: "notification", ...notification };
}