@abot-ai/runtime 1.0.0 → 1.2.0

package/dist/src/web-ui/app/lib/conversation-role-model.js

@@ -0,0 +1,193 @@
+import {
+  eventTone,
+  formatEventDetail,
+  formatEventLabel,
+  titleCaseEventValue,
+} from "./event-presentation.js";
+import { textOf } from "./text-format.js";
+import { countToolInvocations } from "./tool-invocation-count.js";
+
+const ROLE_TITLES = Object.freeze({
+  supervisor: "Supervisor",
+  planner: "Planner",
+  worker: "Worker",
+  reviewer: "Reviewer",
+});
+
+const ROLE_RESPONSIBILITIES = Object.freeze({
+  supervisor: "Coordinates the request",
+  planner: "Plans the work",
+  worker: "Performs assigned tasks",
+  reviewer: "Reviews the result",
+});
+
+function latestRoleAction(group) {
+  const toolEvent = group.toolEvents.at(-1);
+  return roleActivitySummary(toolEvent || group.latestEvent);
+}
+
+function belongsToRoleRequest(event, requestId) {
+  if (!event || typeof event !== "object") return false;
+  return textOf(event.requestId) === requestId;
+}
+
+function activityPosition(event) {
+  if (Number.isSafeInteger(event.eventSequence) && event.eventSequence > 0) {
+    return { domain: "runtime", value: event.eventSequence };
+  }
+  const replaySequence = event.lastSeqNo ?? event.seqNo;
+  if (Number.isSafeInteger(replaySequence) && replaySequence > 0) {
+    return { domain: "replay", value: replaySequence };
+  }
+  return null;
+}
+
+function orderedRequestActivity(events, requestId) {
+  const unique = [];
+  const seen = new Set();
+  const domains = new Map();
+  for (const event of events) {
+    if (!belongsToRoleRequest(event, requestId)) continue;
+    const position = activityPosition(event);
+    if (!position) {
+      unique.push({ event, position });
+      continue;
+    }
+    const identity = `${position.domain}:${position.value}`;
+    if (seen.has(identity)) continue;
+    seen.add(identity);
+    unique.push({ event, position });
+    const domain = domains.get(position.domain) || { events: [], next: 0 };
+    domain.events.push({ event, position });
+    domains.set(position.domain, domain);
+  }
+  for (const domain of domains.values()) {
+    domain.events.sort(
+      (left, right) => left.position.value - right.position.value,
+    );
+  }
+  // Runtime and replay cursors are separate counters. Sort only within each
+  // counter's existing slots, retaining arrival order for unsequenced history.
+  return unique.map(({ event, position }) => {
+    if (!position) return event;
+    const domain = domains.get(position.domain);
+    return domain.events[domain.next++].event;
+  });
+}
+
+function activityEventName(event) {
+  return textOf(event.eventName || event.name || event.rawType || event.type);
+}
+
+function isRequestTerminalEvent(event) {
+  if (event.type === "completed" || event.type === "failed") return true;
+  const name = activityEventName(event);
+  return name === "request.completed" || name === "request.failed";
+}
+
+function isToolActivityEvent(event) {
+  return activityEventName(event).startsWith("tool.");
+}
+
+function hasSupportedRoleStage(stage) {
+  return Object.hasOwn(ROLE_TITLES, stage);
+}
+
+function isFailedRoleActivity(event) {
+  return (textOf(event.tone) || eventTone(event)) === "failed";
+}
+
+function roleActivitySummary(event) {
+  return (
+    textOf(event.summary).trim() ||
+    formatEventDetail(event) ||
+    formatEventLabel(event)
+  );
+}
+
+function createRoleGroup(role, event) {
+  return { role, phase: "", latestEvent: event, toolEvents: [] };
+}
+
+function isActiveRoleActivity(group, activeRole, streaming) {
+  if (!streaming) return false;
+  if (group.role !== activeRole) return false;
+  return !isFailedRoleActivity(group.latestEvent);
+}
+
+function canShowActiveRoles(streaming, terminalSeen) {
+  if (terminalSeen) return false;
+  return streaming;
+}
+
+function buildRoleCard(group, activeRole, streaming) {
+  const failed = isFailedRoleActivity(group.latestEvent);
+  const active = isActiveRoleActivity(group, activeRole, streaming);
+  const toolCount = countToolInvocations(group.toolEvents);
+  let tone = "recorded";
+  if (active) tone = "active";
+  if (failed) tone = "failed";
+  return {
+    id: group.role,
+    role: group.role,
+    title: ROLE_TITLES[group.role],
+    responsibility: ROLE_RESPONSIBILITIES[group.role],
+    phaseLabel: titleCaseEventValue(group.phase),
+    summary: latestRoleAction(group),
+    facts:
+      toolCount > 0
+        ? [`${toolCount} tool call${toolCount === 1 ? "" : "s"}`]
+        : [],
+    active,
+    tone,
+  };
+}
+
+export function buildConversationRoleCards({
+  requestId,
+  events = [],
+  streaming = false,
+} = {}) {
+  const normalizedRequestId = textOf(requestId).trim();
+  if (!normalizedRequestId) return [];
+
+  const groups = new Map();
+  let activeRole = "";
+  let terminalSeen = false;
+  const activityEvents = Array.isArray(events) ? events : [];
+  for (const event of orderedRequestActivity(
+    activityEvents,
+    normalizedRequestId,
+  )) {
+    if (isRequestTerminalEvent(event)) {
+      terminalSeen = true;
+      activeRole = "";
+      continue;
+    }
+
+    const stage = textOf(event.stage).trim();
+    if (stage) {
+      activeRole = "";
+      if (!hasSupportedRoleStage(stage)) continue;
+      activeRole = stage;
+      const group = groups.get(stage) || createRoleGroup(stage, event);
+      group.phase = textOf(event.phase);
+      group.latestEvent = event;
+      groups.set(stage, group);
+    }
+
+    if (!activeRole) continue;
+    if (!isToolActivityEvent(event)) continue;
+    const group = groups.get(activeRole);
+    group.latestEvent = event;
+    group.toolEvents.push({ ...event, eventName: activityEventName(event) });
+  }
+
+  return [...groups.values()].map((group) =>
+    buildRoleCard(
+      group,
+      activeRole,
+      canShowActiveRoles(streaming, terminalSeen),
+    ),
+  );
+}

package/dist/src/web-ui/app/lib/event-presentation.js

@@ -1,5 +1,15 @@
 import { textOf } from "./text-format.js";
 
+function canMergeEventTimelineEntries(previous, event, name, summary) {
+  if (!previous) return false;
+  if (previous.name !== name) return false;
+  if (previous.summary !== summary) return false;
+  if (previous.tone !== event.tone) return false;
+  if (textOf(previous.requestId) !== textOf(event.requestId)) return false;
+  if (textOf(previous.stage) !== textOf(event.stage)) return false;
+  return textOf(previous.phase) === textOf(event.phase);
+}
+
 export function buildEventTimelineEntries(events) {
   const entries = [];
   for (const event of events) {
@@ -7,13 +17,15 @@ export function buildEventTimelineEntries(events) {
     if (!name) continue;
     const summary = textOf(event.summary);
     const previous = entries[entries.length - 1];
-    if (
-      previous &&
-      previous.name === name &&
-      previous.summary === summary &&
-      previous.tone === event.tone
-    ) {
+    if (canMergeEventTimelineEntries(previous, event, name, summary)) {
       previous.count = (previous.count || 1) + (event.count || 1);
+      if (typeof event.eventSequence === "number")
+        previous.eventSequence = Math.max(
+          previous.eventSequence ?? 0,
+          event.eventSequence,
+        );
+      if (typeof event.lastSeqNo === "number")
+        previous.lastSeqNo = event.lastSeqNo;
       continue;
     }
     entries.push({
@@ -241,8 +253,17 @@ export function eventKeyFor(message, label, tone) {
   const tool = textOf(message.tool);
   const approvalId = textOf(message.approvalId);
   const status = textOf(message.status);
+  const stage = textOf(message.stage);
   const phase = textOf(message.phase);
-  return [requestId, name, label, tone, tool, approvalId, status, phase]
-    .filter(Boolean)
-    .join("|");
+  return JSON.stringify([
+    requestId,
+    name,
+    label,
+    tone,
+    tool,
+    approvalId,
+    status,
+    stage,
+    phase,
+  ]);
 }

package/dist/src/web-ui/app/lib/source-url-policy.d.ts

@@ -0,0 +1,2 @@
+export declare function parseWebSourceUrl(value: unknown): URL | null;
+export declare function webSourceFaviconUrl(value: unknown): string;

package/dist/src/web-ui/app/lib/source-url-policy.js

@@ -0,0 +1,31 @@
+const MAX_SOURCE_URL_LENGTH = 4_096;
+
+export function parseWebSourceUrl(value) {
+  if (typeof value !== "string") return null;
+  const candidate = value.trim();
+  if (!candidate || candidate.length > MAX_SOURCE_URL_LENGTH) return null;
+  if (/[\u0000-\u0020\u007f]/u.test(candidate)) return null;
+  try {
+    const url = new URL(candidate);
+    if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+    if (url.username || url.password) return null;
+    return url;
+  } catch {
+    return null;
+  }
+}
+
+function canLoadOriginIcon(hostname) {
+  const host = hostname.toLowerCase().replace(/\.$/u, "");
+  if (!host.includes(".")) return false;
+  if (host.startsWith("[")) return false;
+  if (/^\d+(?:\.\d+){3}$/u.test(host)) return false;
+  const localSuffixes = [".localhost", ".local", ".internal", ".home", ".lan"];
+  return !localSuffixes.some((suffix) => host.endsWith(suffix));
+}
+
+export function webSourceFaviconUrl(value) {
+  const url = parseWebSourceUrl(value);
+  if (!url || !canLoadOriginIcon(url.hostname)) return "";
+  return `${url.origin}/favicon.ico`;
+}

package/dist/src/web-ui/app/lib/task-progress.d.ts

@@ -0,0 +1,53 @@
+import type { EventRecord } from "./event-presentation.js";
+
+export interface TaskProgressItem {
+  id: string;
+  title: string;
+  status: "pending" | "in_progress" | "done" | "blocked";
+  order: number;
+}
+
+interface PlanEventPosition {
+  source: "eventSequence" | "seqNo";
+  value: number;
+}
+
+interface PlanItemUpdate {
+  item: TaskProgressItem;
+  position?: PlanEventPosition;
+  planSummary?: string;
+  planTotal?: number;
+  planCompleted?: number;
+}
+
+interface PlanReplayState {
+  snapshot?: {
+    summary: string;
+    total: number;
+    completed: number;
+    items: TaskProgressItem[];
+    hasSnapshot: boolean;
+  };
+  snapshotPosition?: PlanEventPosition;
+  itemUpdates: PlanItemUpdate[];
+}
+
+export interface TaskProgress {
+  requestId: string;
+  summary: string;
+  total: number;
+  completed: number;
+  items: TaskProgressItem[];
+  activeItem: string;
+  hasSignal: boolean;
+  hasSnapshot: boolean;
+  lastEventSequence?: number;
+  lastSeqNo?: number;
+  replayState?: PlanReplayState;
+}
+
+export declare function taskStatusClass(status: unknown): string;
+export declare function reduceTaskProgress(
+  current: TaskProgress | undefined,
+  message: EventRecord,
+): TaskProgress | undefined;

package/dist/src/web-ui/app/lib/task-progress.js

@@ -0,0 +1,233 @@
+import {
+  getPlanItemPayload,
+  getPlanPayload,
+  getRecord,
+} from "./event-presentation.js";
+import { textOf } from "./text-format.js";
+
+const PLAN_ITEM_STATUSES = new Set([
+  "pending",
+  "in_progress",
+  "done",
+  "blocked",
+]);
+
+export function taskStatusClass(status) {
+  const normalized = textOf(status).trim().toLowerCase();
+  if (normalized === "done" || normalized === "completed") return "done";
+  if (normalized === "in_progress" || normalized === "active") return "active";
+  if (normalized === "blocked" || normalized === "failed") return "failed";
+  if (normalized === "superseded") return "muted";
+  return "pending";
+}
+
+function isTaskProgressCount(value) {
+  return Number.isInteger(value) && value >= 0;
+}
+
+function hasValidPlanItem(item) {
+  if (!getRecord(item)) return false;
+  if (typeof item.title !== "string" || !item.title.trim()) return false;
+  return PLAN_ITEM_STATUSES.has(item.status);
+}
+
+function hasValidPlanSnapshot(plan) {
+  if (!Array.isArray(plan.items)) return false;
+  if (!plan.items.every(hasValidPlanItem)) return false;
+  if (plan.total !== undefined && !isTaskProgressCount(plan.total))
+    return false;
+  if (plan.completed !== undefined && !isTaskProgressCount(plan.completed)) {
+    return false;
+  }
+  const total = plan.total ?? plan.items.length;
+  if (total < plan.items.length) return false;
+  return (plan.completed ?? 0) <= total;
+}
+
+function isPlanEventForRequest(current, message) {
+  if (message.type !== "event") return false;
+  if (typeof message.requestId !== "string" || !message.requestId.trim()) {
+    return false;
+  }
+  if (current && current.requestId !== message.requestId) return false;
+  if (message.stage === "development_plan") return true;
+  return textOf(message.name).startsWith("planner.plan.");
+}
+
+function planEventPosition(message) {
+  if (isTaskProgressCount(message.eventSequence)) {
+    return { source: "eventSequence", value: message.eventSequence };
+  }
+  if (isTaskProgressCount(message.seqNo)) {
+    return { source: "seqNo", value: message.seqNo };
+  }
+  return undefined;
+}
+
+function comparePlanEventPositions(left, right) {
+  if (!left || !right) return undefined;
+  if (left.source !== right.source) return undefined;
+  return left.value - right.value;
+}
+
+function isCoveredPlanEvent(position, baseline) {
+  const comparison = comparePlanEventPositions(position, baseline);
+  return comparison !== undefined && comparison <= 0;
+}
+
+function isLaterPlanEvent(position, baseline) {
+  const comparison = comparePlanEventPositions(position, baseline);
+  return comparison !== undefined && comparison > 0;
+}
+
+function planEventSequence(current, message) {
+  if (isTaskProgressCount(message.eventSequence)) {
+    return {
+      lastEventSequence: Math.max(
+        current?.lastEventSequence ?? 0,
+        message.eventSequence,
+      ),
+      lastSeqNo: current?.lastSeqNo,
+    };
+  }
+  return {
+    lastEventSequence: current?.lastEventSequence,
+    lastSeqNo: isTaskProgressCount(message.seqNo)
+      ? Math.max(current?.lastSeqNo ?? 0, message.seqNo)
+      : current?.lastSeqNo,
+  };
+}
+
+function orderPlanItems(items) {
+  return [...items].sort((left, right) => {
+    const leftOrder = left.order > 0 ? left.order : Infinity;
+    const rightOrder = right.order > 0 ? right.order : Infinity;
+    return leftOrder - rightOrder;
+  });
+}
+
+function findPlanItemIndex(items, nextItem) {
+  const nextId = nextItem.id.trim();
+  if (nextId) {
+    const idIndex = items.findIndex((item) => item.id.trim() === nextId);
+    if (idIndex >= 0) return idIndex;
+  }
+  const nextTitle = nextItem.title.trim().toLowerCase();
+  return items.findIndex((item) => {
+    if (nextId && item.id.trim()) return false;
+    return item.title.trim().toLowerCase() === nextTitle;
+  });
+}
+
+function projectPlanItemUpdate(current, message) {
+  if (!hasValidPlanItem(message.item)) return null;
+  const item = getPlanItemPayload(message);
+  const items = [...(current?.items || [])];
+  const index = findPlanItemIndex(items, item);
+  const previousItem = items[index];
+  const nextItem = {
+    ...item,
+    id: item.id || previousItem?.id || "",
+    order: item.order || previousItem?.order || 0,
+  };
+  if (index < 0) items.push(nextItem);
+  else items[index] = nextItem;
+
+  const total = isTaskProgressCount(message.planTotal)
+    ? message.planTotal
+    : Math.max(current?.total || 0, items.length);
+  const statusChange =
+    Number(nextItem.status === "done") -
+    Number(previousItem?.status === "done");
+  const completed = isTaskProgressCount(message.planCompleted)
+    ? message.planCompleted
+    : Math.max(0, (current?.completed || 0) + statusChange);
+  return {
+    summary: textOf(message.planSummary, current?.summary || ""),
+    total,
+    completed,
+    items,
+    hasSnapshot: current?.hasSnapshot || false,
+  };
+}
+
+function normalizedPlanItemUpdate(message, position) {
+  return {
+    item: getPlanItemPayload(message),
+    position,
+    ...(typeof message.planSummary === "string"
+      ? { planSummary: message.planSummary }
+      : {}),
+    ...(isTaskProgressCount(message.planTotal)
+      ? { planTotal: message.planTotal }
+      : {}),
+    ...(isTaskProgressCount(message.planCompleted)
+      ? { planCompleted: message.planCompleted }
+      : {}),
+  };
+}
+
+function orderPlanItemUpdates(updates) {
+  return [...updates].sort(
+    (left, right) =>
+      comparePlanEventPositions(left.position, right.position) ?? 0,
+  );
+}
+
+function hasRetainedPlanEvent(updates, position) {
+  return updates.some(
+    (update) => comparePlanEventPositions(update.position, position) === 0,
+  );
+}
+
+function reducePlanReplayState(current, message, rawPlan) {
+  const replay = current?.replayState || { itemUpdates: [] };
+  const position = planEventPosition(message);
+  if (isCoveredPlanEvent(position, replay.snapshotPosition)) return null;
+  if (rawPlan) {
+    return {
+      snapshot: { ...getPlanPayload(message), hasSnapshot: true },
+      snapshotPosition: position,
+      itemUpdates: replay.itemUpdates.filter((update) =>
+        isLaterPlanEvent(update.position, position),
+      ),
+    };
+  }
+  if (!hasValidPlanItem(message.item)) return null;
+  if (hasRetainedPlanEvent(replay.itemUpdates, position)) return null;
+  const update = normalizedPlanItemUpdate(message, position);
+  // Intermediate item states matter when legacy deltas omit plan counters.
+  // Keep normalized deltas only until an authoritative snapshot covers them.
+  return {
+    ...replay,
+    itemUpdates: orderPlanItemUpdates([...replay.itemUpdates, update]),
+  };
+}
+
+function projectPlanReplayState(replay) {
+  let projection = replay.snapshot;
+  for (const update of replay.itemUpdates) {
+    projection = projectPlanItemUpdate(projection, update);
+  }
+  return projection;
+}
+
+export function reduceTaskProgress(current, message) {
+  if (!isPlanEventForRequest(current, message)) return current;
+  const rawPlan = getRecord(message.plan);
+  if (rawPlan && !hasValidPlanSnapshot(rawPlan)) return current;
+  const replayState = reducePlanReplayState(current, message, rawPlan);
+  if (!replayState) return current;
+  const projection = projectPlanReplayState(replayState);
+  const items = orderPlanItems(projection.items);
+  return {
+    ...projection,
+    requestId: message.requestId,
+    items,
+    activeItem:
+      items.find((item) => item.status === "in_progress")?.title || "",
+    hasSignal: true,
+    ...planEventSequence(current, message),
+    replayState,
+  };
+}

package/dist/src/web-ui/app/lib/tool-invocation-count.d.ts

@@ -0,0 +1,5 @@
+import type { EventRecord } from "./event-presentation.js";
+
+export declare function countToolInvocations(
+  events: readonly EventRecord[],
+): number;

package/dist/src/web-ui/app/lib/tool-invocation-count.js

@@ -0,0 +1,21 @@
+function isToolInvocationStart(event) {
+  return event.eventName === "tool.started";
+}
+
+function hasFiniteInvocationMultiplicity(value) {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+function toolInvocationMultiplicity(event) {
+  if (!hasFiniteInvocationMultiplicity(event.count)) return 1;
+  return Math.max(1, event.count);
+}
+
+export function countToolInvocations(events) {
+  let count = 0;
+  for (const event of events) {
+    if (!isToolInvocationStart(event)) continue;
+    count += toolInvocationMultiplicity(event);
+  }
+  return count;
+}

package/dist/src/web-ui/app/lib/web-source-event.d.ts

@@ -0,0 +1,8 @@
+import type { normalizeWebSources } from "./web-sources.js";
+import type { normalizeLegacyWebSources } from "./web-sources.js";
+
+export declare function projectWebSourceEvent(
+  message: Record<string, unknown>,
+):
+  | ReturnType<typeof normalizeWebSources>
+  | ReturnType<typeof normalizeLegacyWebSources>;

package/dist/src/web-ui/app/lib/web-source-event.js

@@ -0,0 +1,21 @@
+import {
+  normalizeLegacyWebSources,
+  normalizeWebSources,
+} from "./web-sources.js";
+
+function isCompletedWebTool(message) {
+  const name = message.name || message.rawType || message.type;
+  if (name !== "tool.completed") return false;
+  if (message.ok !== true) return false;
+  return message.tool === "web_search" || message.tool === "web_fetch";
+}
+
+export function projectWebSourceEvent(message) {
+  if (!isCompletedWebTool(message)) return null;
+  const meta = message.meta;
+  if (!meta || typeof meta !== "object" || Array.isArray(meta)) return null;
+  if (Object.hasOwn(meta, "webSources")) {
+    return normalizeWebSources(meta.webSources, message.tool);
+  }
+  return normalizeLegacyWebSources(meta, message.tool);
+}

package/dist/src/web-ui/app/lib/web-sources.d.ts

@@ -0,0 +1,36 @@
+export type WebSourceRetrieval = "not_attempted" | "retrieved" | "failed";
+export type WebSourcePresentation =
+  | "omitted"
+  | "reference"
+  | "snippet"
+  | "content";
+export type WebSource = {
+  url: string;
+  requestedUrl?: string;
+  title: string;
+  retrieval: WebSourceRetrieval;
+  presentation: WebSourcePresentation | "unknown";
+  contentTruncated: boolean;
+};
+export type WebSourcesReceipt = {
+  version: 0 | 1;
+  operation: "search" | "fetch";
+  provider?: "brave" | "light";
+  sources: WebSource[];
+  omittedSourceCount?: number;
+};
+export type ConversationSourcesGroup = WebSourcesReceipt & {
+  id: string;
+  callId: string;
+};
+export declare function normalizeWebSources(
+  value: unknown,
+  toolName: unknown,
+): WebSourcesReceipt | null;
+export declare function normalizeLegacyWebSources(
+  value: unknown,
+  toolName: unknown,
+): WebSourcesReceipt | null;
+export declare function buildConversationSources(
+  events?: unknown[],
+): ConversationSourcesGroup[];