agentel 0.2.0

package/src/canonical-events.js

@@ -0,0 +1,575 @@
+"use strict";
+
+const crypto = require("crypto");
+const { parserVersionForSource } = require("./parser-versions");
+
+const CANONICAL_EVENT_SCHEMA_VERSION = "agentlog.events.v1";
+
+const EVENT_KINDS = {
+  SESSION_STARTED: "session.started",
+  PROMPT_SUBMITTED: "prompt.submitted",
+  TOOL_CALLED: "tool.called",
+  TOOL_COMPLETED: "tool.completed",
+  RESPONSE_GENERATED: "response.generated"
+};
+
+const PATH_ARGUMENT_KEYS = new Set([
+  "workdir",
+  "path",
+  "paths",
+  "cwd",
+  "file",
+  "files",
+  "filename",
+  "filenames",
+  "dir",
+  "dirs",
+  "directory",
+  "directories",
+  "root",
+  "roots",
+  "repo",
+  "repo_path",
+  "repo_root",
+  "workspace",
+  "workspace_path",
+  "absolute_path",
+  "relative_path",
+  "target_path",
+  "source_path",
+  "file_path"
+]);
+
+const TOOL_CATEGORY_DEFINITIONS = [
+  {
+    category: "shell",
+    label: "Shell",
+    icon: ">",
+    names: ["bash", "bashoutput", "killbash", "shell", "exec", "exec_command", "command", "execute", "terminal"]
+  },
+  {
+    category: "edit",
+    label: "Edit",
+    icon: "E",
+    names: ["edit", "multiedit", "write", "notebookedit", "apply_patch", "patch", "replace", "update_file"]
+  },
+  {
+    category: "read",
+    label: "Read",
+    icon: "R",
+    names: ["read", "notebookread", "ls", "list", "view", "view_image", "open", "cat", "sed"]
+  },
+  {
+    category: "search",
+    label: "Search",
+    icon: "?",
+    names: ["grep", "glob", "find", "rg", "search", "websearch"]
+  },
+  {
+    category: "web",
+    label: "Web",
+    icon: "W",
+    names: ["webfetch", "fetch", "browser", "open_url", "navigate"]
+  },
+  {
+    category: "task",
+    label: "Task",
+    icon: "A",
+    names: ["task", "todowrite", "todo_write", "spawn_agent", "wait_agent", "send_input"]
+  },
+  {
+    category: "skill",
+    label: "Skill",
+    icon: "$",
+    names: ["skill", "load_skill", "read_skill"]
+  },
+  {
+    category: "mcp",
+    label: "MCP",
+    icon: "M",
+    names: ["mcp", "mcp_tool_call"]
+  }
+];
+
+function normalizeSessionEvents(session, messages, options = {}) {
+  const parserVersion = options.parserVersion ?? session.parserVersion ?? parserVersionForSource(session.sourceType);
+  const events = [
+    baseEvent(session, {
+      messageIndex: -1,
+      ordinal: 0,
+      kind: EVENT_KINDS.SESSION_STARTED,
+      occurredAt: session.startedAt,
+      parserVersion,
+      role: "system",
+      indexed: {
+        title: session.title || `${session.provider || "Agent"} session`,
+        summary: "Session started",
+        status: "started"
+      },
+      body: {
+        text: session.title || "",
+        toolCall: null,
+        toolResult: null
+      }
+    })
+  ];
+  for (let index = 0; index < messages.length; index++) {
+    events.push(...messageToCanonicalEvents(messages[index], session, { ...options, parserVersion, messageIndex: index }));
+  }
+  return events;
+}
+
+function messageToCanonicalEvents(message, session, options = {}) {
+  const role = String(message?.role || "").toLowerCase();
+  if (!message || role === "system" || role === "developer") return [];
+  const messageIndex = Number.isFinite(Number(message.index)) ? Number(message.index) : options.messageIndex || 0;
+  const parserVersion = options.parserVersion ?? session.parserVersion ?? parserVersionForSource(session.sourceType);
+  const occurredAt = message.timestamp || session.startedAt || new Date().toISOString();
+  const content = String(message.content || "").trim();
+  const metadata = message.metadata || {};
+  const events = [];
+
+  if (role === "user") {
+    events.push(
+      baseEvent(session, {
+        messageIndex,
+        ordinal: 0,
+        kind: EVENT_KINDS.PROMPT_SUBMITTED,
+        occurredAt,
+        parserVersion,
+        role,
+        indexed: {
+          title: "User prompt",
+          summary: summarize(content),
+          status: "submitted"
+        },
+        body: { text: content, toolCall: null, toolResult: null }
+      })
+    );
+    return events;
+  }
+
+  let responseEventId = "";
+  if (role === "assistant" && content) {
+    const response = baseEvent(session, {
+      messageIndex,
+      ordinal: 0,
+      kind: EVENT_KINDS.RESPONSE_GENERATED,
+      occurredAt,
+      parserVersion,
+      role,
+      indexed: {
+        title: "Assistant response",
+        summary: summarize(content),
+        status: "generated"
+      },
+      body: { text: content, toolCall: null, toolResult: null }
+    });
+    responseEventId = response.eventId;
+    events.push(response);
+  }
+
+  const toolCalls = Array.isArray(metadata.toolCalls) ? metadata.toolCalls : [];
+  for (let index = 0; index < toolCalls.length; index++) {
+    const toolCall = normalizeToolCall(toolCalls[index], metadata.provider || session.provider);
+    if (!toolCall) continue;
+    const rendered = renderToolCallText(toolCall);
+    events.push(
+      baseEvent(session, {
+        messageIndex,
+        ordinal: index + 1,
+        kind: EVENT_KINDS.TOOL_CALLED,
+        occurredAt,
+        parserVersion,
+        role: "assistant",
+        parentEventId: responseEventId,
+        indexed: {
+          title: toolCall.title || toolCall.displayName || titleCaseToolName(toolCall.name || "tool"),
+          summary: summarize(rendered || toolCall.rawInputSummary || toolCall.argument || ""),
+          toolName: toolCall.name || toolCall.displayName || "",
+          toolCategory: toolCall.category || "",
+          toolIcon: toolCall.icon || "",
+          target: toolCall.target || "",
+          status: toolCall.status || "tool_call"
+        },
+        body: { text: rendered, toolCall, toolResult: null }
+      })
+    );
+  }
+
+  const toolResult = metadata.toolResult ? normalizeToolResult(metadata.toolResult, metadata.provider || session.provider) : role === "tool" ? normalizeToolResult(content, metadata.provider || session.provider) : null;
+  if (toolResult) {
+    events.push(
+      baseEvent(session, {
+        messageIndex,
+        ordinal: events.length + 1,
+        kind: EVENT_KINDS.TOOL_COMPLETED,
+        occurredAt,
+        parserVersion,
+        role: "tool",
+        indexed: {
+          title: toolResult.title || toolResult.kind || "Tool result",
+          summary: summarize(toolResult.summary || toolResult.output || content),
+          toolName: toolResult.kind || "",
+          toolCategory: toolResult.category || "",
+          toolIcon: toolResult.icon || "",
+          status: toolResult.status || "completed"
+        },
+        body: { text: toolResult.output || content, toolCall: null, toolResult }
+      })
+    );
+  }
+
+  return events;
+}
+
+function baseEvent(session, options) {
+  const body = options.body || {};
+  const indexed = {
+    title: String(options.indexed?.title || ""),
+    summary: String(options.indexed?.summary || "")
+  };
+  for (const key of ["toolName", "toolCategory", "toolIcon", "model", "status", "latencyMs", "target"]) {
+    if (options.indexed?.[key] !== undefined && options.indexed?.[key] !== "") indexed[key] = options.indexed[key];
+  }
+  return {
+    schemaVersion: CANONICAL_EVENT_SCHEMA_VERSION,
+    eventId: stableEventId(
+      session.sessionId,
+      options.messageIndex,
+      options.kind,
+      options.ordinal || 0,
+      `${indexed.title}\n${indexed.summary}\n${body.text || ""}`
+    ),
+    sessionId: session.sessionId,
+    messageIndex: options.messageIndex,
+    occurredAt: toIso(options.occurredAt) || new Date().toISOString(),
+    kind: options.kind,
+    provider: session.provider || "unknown",
+    sourceType: session.sourceType || "import",
+    parserVersion: options.parserVersion ?? null,
+    role: options.role || "",
+    repoCanonical: session.repoCanonical || "",
+    scopeCanonical: session.scopeCanonical || "",
+    indexed,
+    body: {
+      text: String(body.text || ""),
+      toolCall: body.toolCall || null,
+      toolResult: body.toolResult || null
+    },
+    parentEventId: options.parentEventId || ""
+  };
+}
+
+function stableEventId(sessionId, messageIndex, kind, ordinal, content) {
+  const hash = crypto
+    .createHash("sha256")
+    .update(String(sessionId || ""))
+    .update("\0")
+    .update(String(messageIndex))
+    .update("\0")
+    .update(String(kind || ""))
+    .update("\0")
+    .update(String(ordinal || 0))
+    .update("\0")
+    .update(String(content || ""))
+    .digest("hex");
+  return `evt_${hash.slice(0, 24)}`;
+}
+
+function renderEventText(event) {
+  const kind = event?.kind || "";
+  if (kind === EVENT_KINDS.SESSION_STARTED) return "";
+  if (kind === EVENT_KINDS.TOOL_CALLED) {
+    const toolCall = event.body?.toolCall || event.toolCall || {};
+    if (isLowSignalToolCall(toolCall)) return "";
+    return renderToolCallText(toolCall);
+  }
+  if (kind === EVENT_KINDS.TOOL_COMPLETED) {
+    const result = event.body?.toolResult || {};
+    const text = [event.indexed?.title, result.summary, result.output || event.body?.text].filter(Boolean).join("\n");
+    return approxTokenCount(text) > 700 ? [event.indexed?.title, result.summary].filter(Boolean).join(" ") : text;
+  }
+  return event.body?.text || event.indexed?.summary || "";
+}
+
+function renderToolCallText(toolCall) {
+  const normalized = normalizeToolCall(toolCall, toolCall?.provider) || {};
+  const name = titleCaseToolName(normalized.displayName || normalized.name || "tool");
+  const clauses = toolArgumentClauses(normalized);
+  if (!clauses.length) return name;
+  return `${name} with ${joinClauses(clauses)}`.slice(0, 4000);
+}
+
+function isLowSignalToolCall(toolCall) {
+  const normalized = normalizeToolCall(toolCall, toolCall?.provider);
+  if (!normalized) return true;
+  const clauses = toolArgumentClauses(normalized);
+  if (!clauses.length) return true;
+  const renderedArgs = toolMeaningfulArgumentValues(normalized).join(" ");
+  if (approxTokenCount(renderedArgs) > 1000) return true;
+  return !/[a-z]/i.test(renderedArgs);
+}
+
+function classifyTool(name, rawCategory = "") {
+  const keys = [normalizeToolKey(name), normalizeToolKey(rawCategory)].filter(Boolean);
+  if (keys.some((key) => key.startsWith("mcp_") || key.includes("_mcp_") || key.includes("mcp_tool"))) {
+    return toolCategoryDefinition("mcp");
+  }
+  for (const definition of TOOL_CATEGORY_DEFINITIONS) {
+    if (definition.names.some((candidate) => keys.includes(candidate))) return definition;
+  }
+  if (keys.some((key) => key.includes("search") || key.includes("grep") || key.includes("glob"))) return toolCategoryDefinition("search");
+  if (keys.some((key) => key.includes("web") || key.includes("browser") || key.includes("url"))) return toolCategoryDefinition("web");
+  if (keys.some((key) => key.includes("read") || key.includes("list"))) return toolCategoryDefinition("read");
+  if (keys.some((key) => key.includes("edit") || key.includes("write") || key.includes("patch"))) return toolCategoryDefinition("edit");
+  if (keys.some((key) => key.includes("bash") || key.includes("shell") || key.includes("command"))) return toolCategoryDefinition("shell");
+  if (keys.some((key) => key.includes("task") || key.includes("todo") || key.includes("agent"))) return toolCategoryDefinition("task");
+  return { category: "tool", label: "Tool", icon: "T" };
+}
+
+function toolCategoryDefinition(category) {
+  return TOOL_CATEGORY_DEFINITIONS.find((definition) => definition.category === category) || { category: "tool", label: "Tool", icon: "T" };
+}
+
+function normalizeToolKey(value) {
+  return String(value || "")
+    .trim()
+    .toLowerCase()
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "");
+}
+
+function normalizeToolCall(raw, provider = "") {
+  if (!raw) return null;
+  if (typeof raw === "string") {
+    const classification = classifyTool(raw);
+    return {
+      provider,
+      name: raw,
+      displayName: titleCaseToolName(raw),
+      category: classification.category,
+      categoryLabel: classification.label,
+      icon: classification.icon,
+      title: titleCaseToolName(raw),
+      argument: "",
+      rawInputSummary: "",
+      inputPreview: "",
+      target: ""
+    };
+  }
+  if (typeof raw !== "object") return null;
+  const parsedArguments = parseMaybeJson(raw.arguments ?? raw.args ?? raw.input ?? raw.rawInput ?? raw.argument);
+  const name = firstString(raw.name, raw.toolName, raw.displayName, raw.function?.name, raw.kind, raw.type, "tool");
+  const displayName = firstString(raw.displayName, titleCaseToolName(name));
+  const rawCategory = firstString(raw.rawCategory, raw.category, raw.kind, raw.type);
+  const classification = classifyTool(name, rawCategory);
+  const argument = firstString(raw.argument, raw.rawInputSummary, typeof parsedArguments === "string" ? parsedArguments : "");
+  const rawInputSummary = firstString(raw.rawInputSummary, argument);
+  const inputPreview = firstString(raw.inputPreview, rawInputSummary, summarizeToolInput(parsedArguments));
+  const target = firstString(raw.target, targetFromArguments(parsedArguments));
+  return {
+    provider: firstString(raw.provider, provider),
+    id: firstString(raw.id, raw.callId, raw.tool_call_id) || undefined,
+    name,
+    displayName,
+    rawCategory: rawCategory || undefined,
+    category: firstString(raw.normalizedCategory, raw.toolCategory, classification.category),
+    categoryLabel: firstString(raw.categoryLabel, classification.label),
+    icon: firstString(raw.icon, classification.icon),
+    title: firstString(raw.title, displayName),
+    status: firstString(raw.status) || undefined,
+    argument,
+    rawInputSummary,
+    inputPreview,
+    target,
+    arguments: parsedArguments && typeof parsedArguments === "object" && !Array.isArray(parsedArguments) ? parsedArguments : undefined
+  };
+}
+
+function summarizeToolInput(value) {
+  if (value == null || value === "") return "";
+  if (typeof value === "string") return value.slice(0, 240);
+  if (typeof value !== "object") return String(value);
+  const args = Array.isArray(value) ? value : Object.fromEntries(Object.entries(value).filter(([key]) => !isPathArgumentKey(key)));
+  const rendered = Array.isArray(args)
+    ? args.map(renderArgumentValue).filter(Boolean).join(", ")
+    : Object.entries(args)
+        .map(([key, item]) => {
+          const renderedValue = renderArgumentValue(item);
+          return renderedValue ? `${humanizeArgumentKey(key)} ${renderedValue}` : "";
+        })
+        .filter(Boolean)
+        .join(", ");
+  return rendered.slice(0, 240);
+}
+
+function targetFromArguments(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return "";
+  for (const [key, item] of Object.entries(value)) {
+    if (!isPathArgumentKey(key)) continue;
+    const rendered = renderArgumentValue(item);
+    if (rendered) return rendered.slice(0, 300);
+  }
+  return "";
+}
+
+function normalizeToolResult(raw, provider = "") {
+  if (!raw) return null;
+  if (typeof raw === "string") {
+    const output = raw.trim();
+    if (!output) return null;
+    const classification = classifyTool("tool_output");
+    return {
+      provider,
+      kind: "Tool output",
+      title: "Tool result",
+      category: classification.category,
+      categoryLabel: classification.label,
+      icon: classification.icon,
+      summary: firstLine(output),
+      output,
+      lineCount: output.split("\n").length,
+      collapsed: output.split("\n").length > 18,
+      status: "completed"
+    };
+  }
+  if (typeof raw !== "object") return null;
+  const output = firstString(raw.output, raw.text, raw.content, raw.result);
+  const summary = firstString(raw.summary, raw.detail, firstLine(output));
+  const kind = firstString(raw.kind, raw.type, raw.toolName, "Tool output");
+  const rawCategory = firstString(raw.rawCategory, raw.category, raw.kind, raw.type);
+  const classification = classifyTool(firstString(raw.toolName, raw.name, kind), rawCategory);
+  return {
+    provider: firstString(raw.provider, provider),
+    kind,
+    title: firstString(raw.title, raw.kind, "Tool result"),
+    rawCategory: rawCategory || undefined,
+    category: firstString(raw.normalizedCategory, raw.toolCategory, classification.category),
+    categoryLabel: firstString(raw.categoryLabel, classification.label),
+    icon: firstString(raw.icon, classification.icon),
+    summary,
+    output,
+    lineCount: Number(raw.lineCount || (output ? output.split("\n").length : 0)) || 0,
+    collapsed: Boolean(raw.collapsed),
+    status: firstString(raw.status, "completed")
+  };
+}
+
+function toolArgumentClauses(toolCall) {
+  const clauses = [];
+  const args = toolCall.arguments && typeof toolCall.arguments === "object" ? toolCall.arguments : {};
+  for (const [key, value] of Object.entries(args)) {
+    if (isPathArgumentKey(key)) continue;
+    const rendered = renderArgumentValue(value);
+    if (rendered) clauses.push(`${humanizeArgumentKey(key)} ${rendered}`);
+  }
+  const argument = String(toolCall.rawInputSummary || toolCall.argument || "").trim();
+  if (argument && !looksPathLike(argument) && !clauses.some((clause) => clause.includes(argument))) clauses.push(argument);
+  return clauses.map((clause) => clause.replace(/\s+/g, " ").trim()).filter(Boolean);
+}
+
+function toolMeaningfulArgumentValues(toolCall) {
+  const values = [];
+  const args = toolCall.arguments && typeof toolCall.arguments === "object" ? toolCall.arguments : {};
+  for (const [key, value] of Object.entries(args)) {
+    if (isPathArgumentKey(key)) continue;
+    const rendered = renderArgumentValue(value);
+    if (rendered) values.push(rendered);
+  }
+  const argument = String(toolCall.rawInputSummary || toolCall.argument || "").trim();
+  if (argument && !looksPathLike(argument)) values.push(argument);
+  return values;
+}
+
+function isPathArgumentKey(key) {
+  const normalized = String(key || "").trim().toLowerCase();
+  return PATH_ARGUMENT_KEYS.has(normalized) || /(^|_)(path|paths|file|files|dir|dirs|directory|directories|cwd|workspace|repo|root)$/.test(normalized);
+}
+
+function humanizeArgumentKey(key) {
+  const value = String(key || "argument").replace(/[_-]+/g, " ").trim();
+  return value.endsWith("s") ? value : value;
+}
+
+function renderArgumentValue(value) {
+  if (value == null) return "";
+  if (typeof value === "string") return value.slice(0, 300);
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  if (Array.isArray(value)) return value.map(renderArgumentValue).filter(Boolean).slice(0, 5).join(", ");
+  if (typeof value === "object") return JSON.stringify(value).slice(0, 300);
+  return "";
+}
+
+function joinClauses(clauses) {
+  if (clauses.length <= 1) return clauses[0] || "";
+  if (clauses.length === 2) return `${clauses[0]} and ${clauses[1]}`;
+  return `${clauses.slice(0, -1).join(", ")}, and ${clauses[clauses.length - 1]}`;
+}
+
+function titleCaseToolName(value) {
+  const text = String(value || "tool").trim();
+  if (!text) return "Tool";
+  return text
+    .split(/_+/g)
+    .map((part) => part.replace(/(^|[-\s])([a-z])/g, (_, prefix, char) => `${prefix}${char.toUpperCase()}`))
+    .join(" ");
+}
+
+function summarize(value, max = 300) {
+  const text = String(value || "").replace(/\s+/g, " ").trim();
+  if (text.length <= max) return text;
+  return `${text.slice(0, max - 1).trim()}…`;
+}
+
+function parseMaybeJson(value) {
+  if (typeof value !== "string") return value;
+  const text = value.trim();
+  if (!text) return "";
+  if (!/^[\[{"]/.test(text)) return text;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+function firstString(...values) {
+  for (const value of values) {
+    if (typeof value === "string" && value.trim()) return value.trim();
+  }
+  return "";
+}
+
+function firstLine(value) {
+  return String(value || "").split("\n").find((line) => line.trim())?.trim() || "";
+}
+
+function approxTokenCount(value) {
+  return String(value || "").split(/\s+/).filter(Boolean).length;
+}
+
+function looksPathLike(value) {
+  const text = String(value || "").trim();
+  return /^(?:~|\/|\.\/|\.\.\/|[A-Za-z]:\\)/.test(text) || text.split(/[\\/]/).length >= 3;
+}
+
+function toIso(value) {
+  if (!value) return "";
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? "" : date.toISOString();
+}
+
+module.exports = {
+  CANONICAL_EVENT_SCHEMA_VERSION,
+  EVENT_KINDS,
+  isLowSignalToolCall,
+  messageToCanonicalEvents,
+  normalizeSessionEvents,
+  normalizeToolCall,
+  normalizeToolResult,
+  renderEventText,
+  renderToolCallText,
+  stableEventId
+};