ocuclaw 0.1.0

package/dist/domain/activity-status-adapter.js

@@ -0,0 +1,1041 @@
+import path from "node:path";
+
+const GLOBAL_RUN_KEY = "__global__";
+const DEFAULT_MAX_LABEL_CHARS = 120;
+const TOOL_PREVIEW_CHARS = 30;
+
+const REDACT_QUERY_KEYS = "(token|access_token|api_key|key|password|secret)";
+const THINKING_SUMMARY_KEYS = ["summary", "thinkingSummary", "reasoningSummary", "intentLabel"];
+const THINKING_DETAIL_KEYS = ["thinking", "reasoning", "thinkingText", "text", "analysis"];
+const GENERIC_THINKING_LABEL = "Thinking...";
+const ACTIVITY_INTENTS = new Set([
+  "thinking",
+  "thinking_summary",
+  "queued",
+  "fs.read",
+  "fs.write",
+  "fs.edit",
+  "search.files",
+  "search.web",
+  "browser.browse",
+  "browser.navigate",
+  "browser.fill",
+  "network.fetch",
+  "terminal.exec",
+  "terminal.git",
+  "agent.subtask",
+  "agent.coordinate",
+  "message.send",
+  "session.manage",
+  "canvas.edit",
+  "generic",
+]);
+
+function isObject(value) {
+  return value && typeof value === "object" && !Array.isArray(value);
+}
+
+function asString(value) {
+  return typeof value === "string" ? value : null;
+}
+
+function isNullishToken(value) {
+  if (typeof value !== "string") return false;
+  const normalized = value.trim().toLowerCase();
+  return (
+    normalized === "null" ||
+    normalized === "undefined" ||
+    normalized === "(null)" ||
+    normalized === "(undefined)" ||
+    normalized === "none"
+  );
+}
+
+function normalizeLowerToken(value) {
+  const text = asString(value);
+  return text ? text.trim().toLowerCase() : "";
+}
+
+function pickString(obj, keys) {
+  const entry = pickStringEntry(obj, keys);
+  return entry ? entry.value : null;
+}
+
+function pickStringEntry(obj, keys) {
+  if (!isObject(obj)) return null;
+  for (const key of keys) {
+    const value = asString(obj[key]);
+    if (value && value.trim()) return { key, value };
+  }
+  return null;
+}
+
+function normalizeThinkingText(raw) {
+  const text = asString(raw);
+  if (!text) return null;
+  const cleaned = text.replace(/\*\*/g, "").trim();
+  return cleaned || null;
+}
+
+function extractFirstBoldThinkingSegment(raw) {
+  const text = asString(raw);
+  if (!text) return null;
+  const match = text.match(/\*\*([\s\S]+?)\*\*/);
+  if (!match) return null;
+  return normalizeThinkingText(match[1]);
+}
+
+function normalizeThinkingSummarySource(value) {
+  const normalized = normalizeLowerToken(value);
+  return (
+    normalized === "summary" ||
+    normalized === "bold" ||
+    normalized === "detail" ||
+    normalized === "generic"
+  )
+    ? normalized
+    : null;
+}
+
+function normalizeIntent(value) {
+  const normalized = normalizeLowerToken(value);
+  return ACTIVITY_INTENTS.has(normalized) ? normalized : null;
+}
+
+function parseArgs(raw) {
+  if (isObject(raw)) return raw;
+  if (typeof raw !== "string") return null;
+  try {
+    const parsed = JSON.parse(raw);
+    return isObject(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function normalizeArgs(activity) {
+  const candidates = [
+    activity && activity.args,
+    activity && activity.arguments,
+    activity && activity.toolArgs,
+    activity && activity.input,
+  ];
+  for (const candidate of candidates) {
+    const parsed = parseArgs(candidate);
+    if (parsed) return parsed;
+  }
+  return null;
+}
+
+function pickThinkingSummary(activity) {
+  return normalizeThinkingText(pickString(activity, THINKING_SUMMARY_KEYS));
+}
+
+function pickThinkingDetail(activity) {
+  return normalizeThinkingText(pickString(activity, THINKING_DETAIL_KEYS));
+}
+
+function resolveThinkingContent(activity, existingLabel, existingDetail, includeThinking) {
+  const summaryEntry = pickStringEntry(activity, THINKING_SUMMARY_KEYS);
+  const detailEntry = pickStringEntry(activity, THINKING_DETAIL_KEYS);
+  const summaryText = normalizeThinkingText(summaryEntry && summaryEntry.value);
+  const detailText = normalizeThinkingText(detailEntry && detailEntry.value);
+  const boldLabelCandidate = extractFirstBoldThinkingSegment(detailEntry && detailEntry.value);
+  const explicitSource = normalizeThinkingSummarySource(
+    activity && activity.thinkingSummarySource
+  );
+  const existingLabelText = normalizeThinkingText(existingLabel);
+  const existingDetailText = normalizeThinkingText(existingDetail);
+
+  const candidates = [
+    { source: "summary", label: summaryText },
+    { source: "bold", label: boldLabelCandidate },
+    { source: "detail", label: detailText },
+  ];
+
+  let selected = null;
+  if (explicitSource && explicitSource !== "generic") {
+    const explicitLabel = (
+      candidates.find((candidate) => (
+        candidate.source === explicitSource &&
+        candidate.label
+      ))?.label ||
+      existingLabelText ||
+      summaryText ||
+      boldLabelCandidate ||
+      detailText
+    );
+    if (explicitLabel) {
+      selected = { source: explicitSource, label: explicitLabel };
+    }
+  }
+  if (!selected) {
+    selected = candidates.find((candidate) => candidate.label) || null;
+  }
+  if (!selected && existingLabelText) {
+    const normalizedExistingLabel = normalizeLowerToken(existingLabelText);
+    const inferredSource =
+      normalizedExistingLabel === "thinking" || normalizedExistingLabel === "thinking..."
+        ? "generic"
+        : "detail";
+    selected = { source: inferredSource, label: existingLabelText };
+  }
+  if (!selected && includeThinking) {
+    selected = { source: "generic", label: GENERIC_THINKING_LABEL };
+  }
+
+  return {
+    label: selected ? selected.label : null,
+    detail: detailText || existingDetailText || (
+      selected && selected.source !== "generic" ? selected.label : null
+    ),
+    thinkingSummarySource: selected ? selected.source : null,
+  };
+}
+
+function isThinkingActivity(activity, category) {
+  const state = normalizeLowerToken(activity && activity.state);
+  if (state !== "thinking" && state !== "queued") return false;
+  if (activity && activity.tool) return false;
+
+  if (normalizeLowerToken(category) === "thinking") return true;
+  if (normalizeLowerToken(activity && activity.category) === "thinking") return true;
+  if (normalizeLowerToken(activity && activity.origin) === "thinking") return true;
+  if (pickThinkingSummary(activity)) return true;
+  if (pickThinkingDetail(activity)) return true;
+  return !(activity && activity.tool);
+}
+
+function shortText(text, maxChars) {
+  if (!text) return "";
+  if (text.length <= maxChars) return text;
+  if (maxChars <= 3) return ".".repeat(Math.max(maxChars, 0));
+  return `${text.slice(0, maxChars - 3)}...`;
+}
+
+function lowercaseLeadingWord(rawText) {
+  if (typeof rawText !== "string" || rawText.length === 0) return rawText;
+  const match = rawText.match(/[A-Za-z][A-Za-z0-9_-]*/);
+  if (!match || match.index == null) return rawText;
+  const start = match.index;
+  const token = match[0];
+  const end = start + token.length;
+  return `${rawText.slice(0, start)}${token.toLowerCase()}${rawText.slice(end)}`;
+}
+
+function collapseWhitespace(text) {
+  return text.replace(/\s+/g, " ").trim();
+}
+
+function redactSecrets(rawText) {
+  if (!rawText) return "";
+  let text = String(rawText);
+
+  text = text.replace(
+    new RegExp(`([?&]${REDACT_QUERY_KEYS}=)[^&#\\s]+`, "gi"),
+    "$1[redacted]",
+  );
+  text = text.replace(
+    /((?:api[_-]?key|token|password|secret)\s*[=:]\s*)([^,\s"'`]+)/gi,
+    "$1[redacted]",
+  );
+  text = text.replace(/(authorization\s*:\s*bearer\s+)[^\s"'`]+/gi, "$1[redacted]");
+  text = text.replace(/\bBearer\s+[A-Za-z0-9._-]{8,}\b/g, "Bearer [redacted]");
+  text = text.replace(/\b(sk-[A-Za-z0-9]{16,}|ghp_[A-Za-z0-9]{20,}|xox[baprs]-[A-Za-z0-9-]{10,})\b/g, "[redacted]");
+
+  return text;
+}
+
+function sanitizeText(rawText, maxChars) {
+  const redacted = redactSecrets(rawText);
+  const collapsed = collapseWhitespace(redacted);
+  return shortText(collapsed, maxChars);
+}
+
+function hostFromUrl(urlString) {
+  if (!urlString) return null;
+  try {
+    const parsed = new URL(urlString);
+    return parsed.host || null;
+  } catch {
+    return null;
+  }
+}
+
+function extractFirstUrl(text) {
+  if (!text) return null;
+  const match = text.match(/https?:\/\/[^\s"'`]+/i);
+  return match ? match[0] : null;
+}
+
+function extractBrowserQueryFromCommand(command) {
+  const match = command.match(/[?&]q=([^&"'`\s]+)/i);
+  if (!match) return null;
+  try {
+    return decodeURIComponent(match[1].replace(/\+/g, " "));
+  } catch {
+    return match[1].replace(/\+/g, " ");
+  }
+}
+
+function stripQuotes(value) {
+  if (!value) return value;
+  return String(value).replace(/^['"]+|['"]+$/g, "");
+}
+
+function escapeRegex(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function filenameFromPath(pathValue) {
+  if (!pathValue || typeof pathValue !== "string") return null;
+  const cleaned = stripQuotes(pathValue.trim());
+  if (!cleaned) return null;
+  const normalized = cleaned.replace(/[;,)]+$/g, "");
+  if (!normalized) return null;
+  if (isNullishToken(normalized)) return null;
+  // Ignore shell variable/subshell paths like "$f", "${file}", or "$(mktemp)".
+  if (/\$[({]?[A-Za-z_][A-Za-z0-9_]*[)}]?/.test(normalized) || /\$\(.+\)/.test(normalized)) {
+    return null;
+  }
+  if (/^(?:\/dev\/(?:null|stdout|stderr)|nul)$/i.test(normalized)) return null;
+  return path.basename(normalized);
+}
+
+function pickMktempTemplatePath(rawArgs) {
+  if (!rawArgs || typeof rawArgs !== "string") return null;
+  const tokens = rawArgs
+    .match(/"[^"]*"|'[^']*'|[^\s]+/g)
+    ?.map((token) => stripQuotes(token).trim())
+    ?.filter(Boolean);
+  if (!tokens || tokens.length === 0) return null;
+
+  for (let index = tokens.length - 1; index >= 0; index -= 1) {
+    const token = tokens[index];
+    if (!token || token === "mktemp" || token.startsWith("-")) continue;
+    if (isNullishToken(token)) continue;
+    return token;
+  }
+  return null;
+}
+
+function extractMktempBindings(command) {
+  if (!command || typeof command !== "string") return [];
+  const out = [];
+  const regex = /([A-Za-z_][A-Za-z0-9_]*)\s*=\s*\$\(\s*mktemp\b([^)]*)\)/g;
+  let match;
+  while ((match = regex.exec(command)) !== null) {
+    const varName = match[1];
+    const templatePath = pickMktempTemplatePath(match[2]);
+    const fileName = filenameFromPath(templatePath);
+    if (!fileName) continue;
+    out.push({ varName, fileName });
+  }
+  return out;
+}
+
+function commandRefsVarWithRedirect(command, varName, operator) {
+  if (!command || !varName) return false;
+  const varRef = `\\$\\{?${escapeRegex(varName)}\\}?`;
+  const op = escapeRegex(operator);
+  const regex = new RegExp(`(?:^|\\s)${op}\\s*(?:["']?${varRef}["']?)`);
+  return regex.test(command);
+}
+
+function commandReadsVarWithCat(command, varName) {
+  if (!command || !varName) return false;
+  const varRef = `\\$\\{?${escapeRegex(varName)}\\}?`;
+  const regex = new RegExp(`(?:^|\\s)cat\\s+(?:["']?${varRef}["']?)`);
+  return regex.test(command);
+}
+
+function categoryFromToolName(lowName) {
+  if (lowName.startsWith("browser") || lowName === "web" || lowName === "web.search") return "browser";
+  if (lowName === "read" || lowName === "write" || lowName === "edit" || lowName.startsWith("fs.")) return "filesystem";
+  if (lowName === "search" || lowName.startsWith("vector") || lowName === "grep" || lowName === "find") return "search";
+  if (lowName === "exec" || lowName === "bash" || lowName.startsWith("shell")) return "terminal";
+  return "generic";
+}
+
+function intentFromToolName(lowName, args) {
+  const query = pickString(args, ["query", "q", "term", "search"]);
+
+  switch (lowName) {
+    case "read":
+    case "fs.read":
+      return "fs.read";
+    case "write":
+    case "apply_patch":
+    case "fs.write":
+      return "fs.write";
+    case "edit":
+    case "fs.edit":
+      return "fs.edit";
+    case "search":
+    case "grep":
+    case "find":
+      return "search.files";
+    case "browser.search":
+    case "web.search":
+      return "search.web";
+    case "browser.click":
+    case "browser.navigate":
+      return "browser.navigate";
+    case "browser.fill":
+      return "browser.fill";
+    case "browser":
+    case "web":
+      return query ? "search.web" : "browser.browse";
+    case "exec":
+    case "bash":
+      return "terminal.exec";
+    case "git":
+      return "terminal.git";
+    case "llm_task":
+      return "agent.subtask";
+    case "agent_send":
+      return "agent.coordinate";
+    case "message":
+      return "message.send";
+    case "sessions_list":
+    case "sessions_read":
+    case "session_status":
+      return "session.manage";
+    case "canvas":
+      return "canvas.edit";
+    case "fetch":
+      return "network.fetch";
+    default:
+      break;
+  }
+
+  if (lowName.startsWith("browser")) {
+    if (lowName.includes("fill")) return "browser.fill";
+    if (lowName.includes("click") || lowName.includes("navigate")) return "browser.navigate";
+    if (lowName.includes("search")) return "search.web";
+    return "browser.browse";
+  }
+  if (lowName.startsWith("web")) {
+    return lowName.includes("search") ? "search.web" : "browser.browse";
+  }
+  if (lowName.includes("search")) {
+    return lowName.includes("web") || lowName.includes("browser")
+      ? "search.web"
+      : "search.files";
+  }
+  if (lowName.startsWith("fs.")) {
+    if (lowName.includes("read")) return "fs.read";
+    if (lowName.includes("edit")) return "fs.edit";
+    return "fs.write";
+  }
+  if (lowName.startsWith("session")) return "session.manage";
+  if (lowName.startsWith("http")) return "network.fetch";
+  if (lowName.startsWith("git")) return "terminal.git";
+  if (lowName.startsWith("shell")) return "terminal.exec";
+  return "generic";
+}
+
+function isExplanatoryThinkingLabel(label) {
+  const normalizedLabel = normalizeThinkingText(label);
+  if (!normalizedLabel) return false;
+  const normalizedToken = collapseWhitespace(normalizedLabel)
+    .toLowerCase()
+    .replace(/\u2026/g, "...");
+  return normalizedToken !== "thinking" && normalizedToken !== "thinking...";
+}
+
+function labelFromExecCommand(command) {
+  const raw = command ? String(command).trim() : "";
+  if (!raw) {
+    return {
+      label: "Running a command...",
+      category: "terminal",
+      intent: "terminal.exec",
+    };
+  }
+
+  if (raw.includes("agent-browser")) {
+    const query = extractBrowserQueryFromCommand(raw);
+    if (query) {
+      return {
+        label: `Searching "${shortText(sanitizeText(query, TOOL_PREVIEW_CHARS), TOOL_PREVIEW_CHARS)}"...`,
+        category: "browser",
+        intent: "search.web",
+      };
+    }
+    const browserUrl = extractFirstUrl(raw);
+    if (browserUrl) {
+      const host = hostFromUrl(browserUrl);
+      return {
+        label: host ? `Browsing ${host}...` : "Using browser...",
+        category: "browser",
+        intent: "browser.browse",
+      };
+    }
+    return {
+      label: "Using browser...",
+      category: "browser",
+      intent: "browser.browse",
+    };
+  }
+
+  if (/(^|\s)(curl|wget)\b/i.test(raw) || /https?:\/\//i.test(raw)) {
+    const url = extractFirstUrl(raw);
+    const host = hostFromUrl(url);
+    if (host) {
+      return {
+        label: `Fetching from ${host}...`,
+        category: "network",
+        intent: "network.fetch",
+      };
+    }
+    return {
+      label: "Fetching data...",
+      category: "network",
+      intent: "network.fetch",
+    };
+  }
+
+  const appendMatch = raw.match(/(?:^|\s)>>\s*([^\s]+)/);
+  if (appendMatch) {
+    const fileName = filenameFromPath(appendMatch[1]);
+    if (fileName) {
+      return {
+        label: `Appending to ${fileName}...`,
+        category: "filesystem",
+        intent: "fs.write",
+      };
+    }
+  }
+
+  const writeMatch = raw.match(/(?:^|\s)>\s*([^\s]+)/);
+  if (writeMatch) {
+    const fileName = filenameFromPath(writeMatch[1]);
+    if (fileName) {
+      return {
+        label: `Writing ${fileName}...`,
+        category: "filesystem",
+        intent: "fs.write",
+      };
+    }
+  }
+
+  const mktempBindings = extractMktempBindings(raw);
+  for (const binding of mktempBindings) {
+    if (commandRefsVarWithRedirect(raw, binding.varName, ">>")) {
+      return {
+        label: `Appending to ${binding.fileName}...`,
+        category: "filesystem",
+        intent: "fs.write",
+      };
+    }
+  }
+  for (const binding of mktempBindings) {
+    if (commandRefsVarWithRedirect(raw, binding.varName, ">")) {
+      return {
+        label: `Writing ${binding.fileName}...`,
+        category: "filesystem",
+        intent: "fs.write",
+      };
+    }
+  }
+  for (const binding of mktempBindings) {
+    if (commandReadsVarWithCat(raw, binding.varName)) {
+      return {
+        label: `Reading ${binding.fileName}...`,
+        category: "filesystem",
+        intent: "fs.read",
+      };
+    }
+  }
+
+  const catMatch = raw.match(/^cat\s+([^\s>]+)/);
+  if (catMatch) {
+    const fileName = filenameFromPath(catMatch[1]);
+    if (fileName) {
+      return {
+        label: `Reading ${fileName}...`,
+        category: "filesystem",
+        intent: "fs.read",
+      };
+    }
+  }
+
+  if (/^(grep|rg|find)\b/.test(raw)) {
+    return {
+      label: "Searching files...",
+      category: "search",
+      intent: "search.files",
+    };
+  }
+  if (/\bgit\s+/.test(raw)) {
+    return {
+      label: "Running git...",
+      category: "terminal",
+      intent: "terminal.git",
+    };
+  }
+
+  return {
+    label: `Running: ${shortText(sanitizeText(raw, TOOL_PREVIEW_CHARS), TOOL_PREVIEW_CHARS)}`,
+    category: "terminal",
+    intent: "terminal.exec",
+  };
+}
+
+function mapToolLabel(toolName, activityPath, args, options) {
+  const maxLabelChars = options.maxLabelChars;
+  const lowName = String(toolName || "").toLowerCase();
+  const rawPathValue = asString(activityPath) || pickString(args, [
+    "path",
+    "filePath",
+    "file_path",
+    "filepath",
+    "file",
+    "target",
+    "outputPath",
+    "output_path",
+    "output",
+    "destination",
+    "dest",
+  ]);
+  const pathValue = rawPathValue && !isNullishToken(rawPathValue) ? rawPathValue : null;
+  const fileName = filenameFromPath(pathValue);
+  const query = pickString(args, ["query", "q", "term", "search"]);
+  const url = pickString(args, ["url", "href", "uri"]);
+  const command = pickString(args, ["command", "cmd", "shell"]);
+
+  switch (lowName) {
+    case "write":
+    case "apply_patch":
+    case "fs.write":
+      return {
+        label: `Writing ${fileName || "file"}...`,
+        detail: pathValue || command || null,
+        category: "filesystem",
+        intent: "fs.write",
+      };
+    case "read":
+    case "fs.read":
+      return {
+        label: `Reading ${fileName || "file"}...`,
+        detail: pathValue || command || null,
+        category: "filesystem",
+        intent: "fs.read",
+      };
+    case "edit":
+    case "fs.edit":
+      return {
+        label: `Editing ${fileName || "file"}...`,
+        detail: pathValue || command || null,
+        category: "filesystem",
+        intent: "fs.edit",
+      };
+    case "search":
+      if (query) {
+        const shortQuery = shortText(sanitizeText(query, TOOL_PREVIEW_CHARS), TOOL_PREVIEW_CHARS);
+        return {
+          label: `Searching for "${shortQuery}"...`,
+          detail: query,
+          category: "search",
+          intent: "search.files",
+        };
+      }
+      return {
+        label: "Searching files...",
+        detail: pathValue || null,
+        category: "search",
+        intent: "search.files",
+      };
+    case "bash":
+    case "exec": {
+      const fromCommand = labelFromExecCommand(command);
+      return {
+        label: fromCommand.label,
+        detail: command || pathValue || null,
+        category: fromCommand.category,
+        intent: fromCommand.intent,
+      };
+    }
+    case "browser.search":
+    case "web.search":
+      if (query) {
+        const shortQuery = shortText(sanitizeText(query, TOOL_PREVIEW_CHARS), TOOL_PREVIEW_CHARS);
+        return {
+          label: `Searching the web for "${shortQuery}"...`,
+          detail: query,
+          category: "browser",
+          intent: "search.web",
+        };
+      }
+      if (url) {
+        return {
+          label: "Searching the web...",
+          detail: url,
+          category: "browser",
+          intent: "search.web",
+        };
+      }
+      return {
+        label: "Searching the web...",
+        detail: null,
+        category: "browser",
+        intent: "search.web",
+      };
+    case "browser":
+    case "web":
+      if (query) {
+        const shortQuery = shortText(sanitizeText(query, TOOL_PREVIEW_CHARS), TOOL_PREVIEW_CHARS);
+        return {
+          label: `Searching the web for "${shortQuery}"...`,
+          detail: query,
+          category: "browser",
+          intent: "search.web",
+        };
+      }
+      if (url) {
+        return {
+          label: "Browsing the web...",
+          detail: url,
+          category: "browser",
+          intent: "browser.browse",
+        };
+      }
+      return {
+        label: "Browsing the web...",
+        detail: null,
+        category: "browser",
+        intent: "browser.browse",
+      };
+    case "browser.click":
+      return {
+        label: "Navigating a webpage...",
+        detail: url || null,
+        category: "browser",
+        intent: "browser.navigate",
+      };
+    case "browser.fill":
+      return {
+        label: "Filling out a form...",
+        detail: url || null,
+        category: "browser",
+        intent: "browser.fill",
+      };
+    case "browser.navigate":
+      return {
+        label: "Opening a webpage...",
+        detail: url || null,
+        category: "browser",
+        intent: "browser.navigate",
+      };
+    case "llm_task":
+      return {
+        label: "Running a sub-task...",
+        detail: null,
+        category: "generic",
+        intent: "agent.subtask",
+      };
+    case "agent_send":
+      return {
+        label: "Coordinating with another agent...",
+        detail: null,
+        category: "generic",
+        intent: "agent.coordinate",
+      };
+    case "message":
+      return {
+        label: "Sending a message...",
+        detail: null,
+        category: "generic",
+        intent: "message.send",
+      };
+    case "sessions_list":
+    case "sessions_read":
+    case "session_status":
+      return {
+        label: "Checking sessions...",
+        detail: null,
+        category: "generic",
+        intent: "session.manage",
+      };
+    case "canvas":
+      return {
+        label: "Working on canvas...",
+        detail: null,
+        category: "generic",
+        intent: "canvas.edit",
+      };
+    default:
+      if (fileName) {
+        return {
+          label: `${toolName} ${fileName}...`,
+          detail: pathValue || null,
+          category: categoryFromToolName(lowName),
+          intent: intentFromToolName(lowName, args),
+        };
+      }
+      return {
+        label: `Using ${toolName}...`,
+        detail: query || url || command || null,
+        category: categoryFromToolName(lowName),
+        intent: intentFromToolName(lowName, args),
+      };
+  }
+}
+
+function normalizePhase(phase, state) {
+  const p = typeof phase === "string" ? phase.toLowerCase() : "";
+  if (p === "start" || p === "update" || p === "end") return p;
+  if (
+    p === "error" ||
+    p === "complete" ||
+    p === "completed" ||
+    p === "done" ||
+    p === "result" ||
+    p === "failed" ||
+    p === "finish" ||
+    p === "finished"
+  ) {
+    return "end";
+  }
+
+  const s = typeof state === "string" ? state.toLowerCase() : "";
+  if (s === "idle" || s === "error" || s === "done" || s === "cancelled" || s === "canceled") return "end";
+  if (s === "thinking" || s === "queued") return "update";
+  return "update";
+}
+
+function normalizeRunKey(runId) {
+  if (typeof runId === "string" && runId.trim()) return runId.trim();
+  return GLOBAL_RUN_KEY;
+}
+
+function sanitizeIdPart(value) {
+  return String(value || "")
+    .trim()
+    .replace(/[^a-zA-Z0-9._:-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+function createActivityStatusAdapter(opts) {
+  const options = opts || {};
+  const enabled = options.enabled !== false;
+  const includeThinking = options.includeThinking !== false;
+  const maxLabelChars =
+    Number.isFinite(options.maxLabelChars) && options.maxLabelChars > 0
+      ? Math.floor(options.maxLabelChars)
+      : DEFAULT_MAX_LABEL_CHARS;
+
+  /** @type {Map<string, {seq: number, toolStartCount: number, currentActivityId: string|null, toolContextByActivityId: Map<string, {label: string, detail: string|null, category: string|null, intent: string|null}>}>} */
+  const runStates = new Map();
+
+  function getRunState(runKey) {
+    let state = runStates.get(runKey);
+    if (!state) {
+      state = {
+        seq: 0,
+        toolStartCount: 0,
+        currentActivityId: null,
+        toolContextByActivityId: new Map(),
+      };
+      runStates.set(runKey, state);
+    }
+    return state;
+  }
+
+  function reset() {
+    runStates.clear();
+  }
+
+  function augmentActivity(rawActivity) {
+    if (!isObject(rawActivity)) return rawActivity;
+
+    const activity = { ...rawActivity };
+    const runKey = normalizeRunKey(activity.runId);
+    const runState = getRunState(runKey);
+    const phase = normalizePhase(activity.phase, activity.state);
+
+    runState.seq += 1;
+    const seq = Number.isFinite(activity.seq) ? Math.floor(activity.seq) : runState.seq;
+
+    let activityId = asString(activity.activityId) && activity.activityId.trim()
+      ? activity.activityId.trim()
+      : null;
+
+    if (!activityId) {
+      if (phase === "start") {
+        if (activity.origin === "tool" || activity.tool) {
+          runState.toolStartCount += 1;
+          const toolName = sanitizeIdPart(activity.tool || "tool");
+          activityId = `${runKey}:tool:${toolName || "tool"}:${runState.toolStartCount}`;
+        } else if (activity.origin === "lifecycle") {
+          activityId = `${runKey}:lifecycle`;
+        } else {
+          activityId = `${runKey}:activity:${runState.seq}`;
+        }
+      } else {
+        activityId = runState.currentActivityId || `${runKey}:activity`;
+      }
+    }
+
+    if (phase === "start" || phase === "update") {
+      runState.currentActivityId = activityId;
+    }
+    if (phase === "end") {
+      runState.currentActivityId = null;
+    }
+
+    let label = asString(activity.label);
+    let detail = asString(activity.detail);
+    let category = asString(activity.category);
+    let thinkingSummarySource = null;
+    let suppressThinkingContent = false;
+    const args = normalizeArgs(activity) || {};
+    const previousToolContext = activity.tool && activityId
+      ? runState.toolContextByActivityId.get(activityId)
+      : null;
+    const hasCurrentToolContext =
+      !!asString(activity.path) ||
+      !!pickString(args, [
+        "path",
+        "filePath",
+        "file_path",
+        "filepath",
+        "file",
+        "target",
+        "outputPath",
+        "output_path",
+        "output",
+        "destination",
+        "dest",
+        "query",
+        "q",
+        "term",
+        "search",
+        "url",
+        "href",
+        "uri",
+        "command",
+        "cmd",
+        "shell",
+      ]);
+    const mappedTool = activity.tool
+      ? mapToolLabel(activity.tool, activity.path, args, {
+        maxLabelChars,
+      })
+      : null;
+    const isThinking = isThinkingActivity(activity, category);
+
+    if (isThinking) {
+      if (!category) category = "thinking";
+      const resolvedThinking = resolveThinkingContent(
+        activity,
+        label,
+        detail,
+        includeThinking,
+      );
+      thinkingSummarySource = resolvedThinking.thinkingSummarySource;
+      if (!label) {
+        label = resolvedThinking.label;
+      }
+      if (!detail) {
+        detail = resolvedThinking.detail;
+      }
+
+      if (!includeThinking) {
+        suppressThinkingContent = true;
+        label = null;
+        detail = null;
+        thinkingSummarySource = null;
+      }
+    } else if (!label && activity.tool) {
+      if (previousToolContext && !hasCurrentToolContext) {
+        label = previousToolContext.label;
+        if (!detail) detail = previousToolContext.detail;
+        if (!category) category = previousToolContext.category;
+      }
+      if (!label) {
+        const mapped = mappedTool;
+        label = mapped.label;
+        if (!detail) detail = mapped.detail;
+        if (!category) category = mapped.category;
+      }
+    }
+
+    let intent = normalizeIntent(activity.intent);
+    if (normalizeLowerToken(activity && activity.state) === "queued") {
+      intent = "queued";
+    } else if (activity.tool) {
+      intent = (
+        (!hasCurrentToolContext && previousToolContext && previousToolContext.intent) ||
+        (mappedTool && mappedTool.intent) ||
+        intentFromToolName(normalizeLowerToken(activity.tool), args)
+      );
+    } else if (isThinking) {
+      intent = isExplanatoryThinkingLabel(label) ? "thinking_summary" : "thinking";
+    }
+
+    if (activity.tool && activityId && label) {
+      runState.toolContextByActivityId.set(activityId, {
+        label,
+        detail: detail || null,
+        category: category || null,
+        intent: intent || null,
+      });
+    }
+
+    const result = {
+      ...activity,
+      activityId,
+      seq,
+      phase,
+    };
+
+    if (suppressThinkingContent) {
+      delete result.label;
+      delete result.detail;
+    }
+
+    if (runKey !== GLOBAL_RUN_KEY && !result.runId) {
+      result.runId = runKey;
+    }
+
+    if (typeof activity.isError === "boolean") {
+      result.isError = activity.isError;
+    }
+    if (Number.isFinite(activity.exitCode)) {
+      result.exitCode = Math.trunc(activity.exitCode);
+    }
+    if (Number.isFinite(activity.durationMs) && activity.durationMs >= 0) {
+      result.durationMs = Math.trunc(activity.durationMs);
+    }
+
+    if (enabled) {
+      if (label) result.label = sanitizeText(lowercaseLeadingWord(label), maxLabelChars);
+      if (detail) result.detail = sanitizeText(detail, Math.max(maxLabelChars, 200));
+      if (category) result.category = sanitizeIdPart(category.toLowerCase()) || "generic";
+      if (thinkingSummarySource) result.thinkingSummarySource = thinkingSummarySource;
+      const resultSummary = asString(activity.resultSummary);
+      if (resultSummary) {
+        result.resultSummary = sanitizeText(resultSummary, Math.max(maxLabelChars, 200));
+      }
+    }
+    if (intent) {
+      result.intent = intent;
+    } else {
+      delete result.intent;
+    }
+
+    return result;
+  }
+
+  return {
+    augmentActivity,
+    reset,
+  };
+}
+
+export {
+  createActivityStatusAdapter,
+};