@evo-dev/core 0.0.1-alpha.2 → 0.0.1-alpha.20

package/src/evolution/control/index.ts

@@ -0,0 +1,20 @@
+export {
+  formatEvolutionProcessResult,
+  formatEvolutionReviewSnapshot,
+} from "../formatters.ts";
+export { processEvolutionTriggers } from "../processor/index.ts";
+export { readEvolutionReviewSnapshot } from "../candidates/index.ts";
+export {
+  listEvolutionTriggers,
+  listSegmentEvolutionTriggers,
+} from "../triggers/index.ts";
+export type {
+  EvolutionProcessInput,
+  EvolutionProcessProgress,
+  EvolutionProcessResult,
+  EvolutionReviewSnapshot,
+  EvolutionTriggerListInput,
+  EvolutionTriggerRecord,
+  SegmentEvolutionTriggerListInput,
+  SegmentEvolutionTriggerRecord,
+} from "../schema.ts";

package/src/evolution/evidence/analysis.ts

@@ -0,0 +1,533 @@
+import { readFile, readdir } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { readCodeAgentTraceRef } from "../../code-agent-traces/index.ts";
+import { resolveEvoDevPaths } from "../../config/paths.ts";
+import { type EvoDevExecutionEventV1, resolveProjectLogKey } from "../../runtime-logs/index.ts";
+import { createStableId, normalizeTimestamp, pathExists } from "../../utils/index.ts";
+import { resolveEvolutionPaths } from "../paths.ts";
+import type {
+  EvolutionAnalyzeInput,
+  EvolutionAnalyzeResult,
+  EvolutionEpisode,
+  EvolutionEpisodeStatus,
+  EvolutionEvidenceEvent,
+  EvolutionEvidenceEventKind,
+  EvolutionEvidenceSourceRef,
+  EvolutionEvidenceWindow,
+  EvolutionTriggerPolicy,
+  EvolutionTriggerReason,
+  EvolutionTriggerStrength,
+} from "../schema.ts";
+import {
+  MAX_EVIDENCE_EVENTS,
+  createPrivacyFields,
+  displayPath,
+  isRecord,
+  optionalString,
+  sanitizeId,
+  sanitizeOptionalId,
+  sanitizeText,
+  uniqueSanitizedIds,
+  validateEvolutionEvidenceWindow,
+} from "../shared.ts";
+import {
+  createTriggerPolicy,
+  decideEvolutionTrigger,
+  normalizeEvolutionEventType,
+  strongestTrigger,
+} from "../triggers/classification.ts";
+
+export async function analyzeEvolutionRun(
+  input: EvolutionAnalyzeInput,
+): Promise<EvolutionAnalyzeResult> {
+  const projectKey = resolveEvolutionProjectKey(input);
+  const runId = sanitizeId(input.runId);
+  const paths = resolveEvolutionPaths({ homeDir: input.homeDir, projectKey, runId });
+  const warnings: string[] = [];
+  const sourceRefs: EvolutionEvidenceSourceRef[] = [];
+  const linkedTraceRefIds = new Set<string>();
+  const events: EvolutionEvidenceEvent[] = [];
+  const logsDir = resolveEvoDevPaths(input.homeDir).logsDir;
+  const projectRunAgentsDir = join(logsDir, "teams", projectKey, runId, "agents");
+  const legacyProjectRunAgentsDir = join(logsDir, projectKey, runId, "agents");
+  const agentDirs = (await pathExists(projectRunAgentsDir))
+    ? await readdir(projectRunAgentsDir, { withFileTypes: true })
+    : [];
+  const legacyAgentDirs = (await pathExists(legacyProjectRunAgentsDir))
+    ? await readdir(legacyProjectRunAgentsDir, { withFileTypes: true })
+    : [];
+
+  if (agentDirs.length === 0 && legacyAgentDirs.length === 0) {
+    warnings.push(
+      `No agent execution event directory found: ${displayPath(input.homeDir, projectRunAgentsDir)}`,
+    );
+  } else {
+    const rolesWithExecutionEvents = new Set<string>();
+    for (const roleDir of agentDirs.filter((entry) => entry.isDirectory())) {
+      const roleId = sanitizeId(roleDir.name);
+      const eventsPath = join(projectRunAgentsDir, roleDir.name, "events.jsonl");
+      if (!(await pathExists(eventsPath))) continue;
+      rolesWithExecutionEvents.add(roleId);
+
+      const sourceRef: EvolutionEvidenceSourceRef = {
+        id: `source-${sourceRefs.length + 1}`,
+        kind: "evodev-execution-event",
+        path: displayPath(input.homeDir, eventsPath),
+        roleId,
+        rawContentStored: false,
+        externalContentCopied: false,
+      };
+      sourceRefs.push(sourceRef);
+      const parsed = await readExecutionEvidenceEvents({
+        path: eventsPath,
+        roleId,
+        sourceRefId: sourceRef.id,
+        existingCount: events.length,
+      });
+      events.push(...parsed.events);
+      for (const traceRefId of parsed.traceRefIds) linkedTraceRefIds.add(traceRefId);
+      warnings.push(...parsed.warnings);
+    }
+
+    for (const roleDir of legacyAgentDirs.filter((entry) => entry.isDirectory())) {
+      const roleId = sanitizeId(roleDir.name);
+      if (rolesWithExecutionEvents.has(roleId)) continue;
+      const tracePath = join(legacyProjectRunAgentsDir, roleDir.name, "trace.log");
+      if (!(await pathExists(tracePath))) continue;
+
+      const sourceRef: EvolutionEvidenceSourceRef = {
+        id: `source-${sourceRefs.length + 1}`,
+        kind: "team-agent-trace",
+        path: displayPath(input.homeDir, tracePath),
+        roleId,
+        rawContentStored: false,
+        externalContentCopied: false,
+      };
+      sourceRefs.push(sourceRef);
+      const parsed = await readTraceEvidenceEvents({
+        path: tracePath,
+        roleId,
+        sourceRefId: sourceRef.id,
+        existingCount: events.length,
+      });
+      events.push(...parsed.events);
+      warnings.push(...parsed.warnings);
+    }
+  }
+
+  for (const traceRefId of [...linkedTraceRefIds].sort()) {
+    try {
+      const record = await readCodeAgentTraceRef({ homeDir: input.homeDir, id: traceRefId });
+      sourceRefs.push({
+        id: `source-${sourceRefs.length + 1}`,
+        kind: "code-agent-trace-ref",
+        path: displayPath(input.homeDir, record.path),
+        roleId: record.ref.roleId,
+        rawContentStored: false,
+        externalContentCopied: false,
+      });
+    } catch {
+      warnings.push(
+        `Code Agent trace ref metadata not found for linked ref: ${sanitizeText(traceRefId)}.`,
+      );
+    }
+  }
+
+  if (events.length > MAX_EVIDENCE_EVENTS) {
+    warnings.push(
+      `Evidence events truncated from ${events.length} to ${MAX_EVIDENCE_EVENTS} metadata events.`,
+    );
+  }
+  const limitedEvents = events.slice(0, MAX_EVIDENCE_EVENTS);
+  const episodeAnalysis = buildEvolutionEpisodeAnalysis(limitedEvents);
+
+  const evidenceWindow: EvolutionEvidenceWindow = {
+    schemaVersion: 1,
+    id: createStableId("evidence", [projectKey, runId]),
+    kind: "evidence-window",
+    projectKey,
+    runId,
+    taskId: null,
+    createdAt: normalizeTimestamp(input.now),
+    sourceRefs,
+    events: episodeAnalysis.events,
+    episodes: episodeAnalysis.episodes,
+    triggerPolicy: episodeAnalysis.triggerPolicy,
+    privacy: createPrivacyFields({
+      sourceRefs,
+      events: episodeAnalysis.events,
+      episodes: episodeAnalysis.episodes,
+    }),
+  };
+  validateEvolutionEvidenceWindow(evidenceWindow);
+
+  return {
+    evidenceWindow,
+    warnings,
+  };
+}
+
+async function readExecutionEvidenceEvents(input: {
+  path: string;
+  roleId: string;
+  sourceRefId: string;
+  existingCount: number;
+}): Promise<{ events: EvolutionEvidenceEvent[]; warnings: string[]; traceRefIds: string[] }> {
+  const raw = await readFile(input.path, "utf8");
+  const lines = raw.split("\n");
+  const events: EvolutionEvidenceEvent[] = [];
+  const warnings: string[] = [];
+  const traceRefIds = new Set<string>();
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index]?.trim();
+    if (line === undefined || line === "") continue;
+
+    try {
+      const value = JSON.parse(line) as unknown;
+      if (!isRecord(value) || value.kind !== "evodev-execution-event") continue;
+      const codeAgentTraceRefId = optionalString(value.codeAgentTraceRefId);
+      if (codeAgentTraceRefId !== null) traceRefIds.add(codeAgentTraceRefId);
+      const event = createEvidenceEventFromExecutionEvent({
+        executionEvent: value as unknown as EvoDevExecutionEventV1,
+        roleId: input.roleId,
+        sourceRefId: input.sourceRefId,
+        lineNumber: index + 1,
+        sequence: input.existingCount + events.length + 1,
+      });
+      if (event !== null) events.push(event);
+    } catch {
+      warnings.push(
+        `Skipped malformed execution event JSON at ${basename(input.path)}:${index + 1}.`,
+      );
+    }
+  }
+
+  return { events, warnings, traceRefIds: [...traceRefIds] };
+}
+
+function createEvidenceEventFromExecutionEvent(input: {
+  executionEvent: EvoDevExecutionEventV1;
+  roleId: string;
+  sourceRefId: string;
+  lineNumber: number;
+  sequence: number;
+}): EvolutionEvidenceEvent | null {
+  const metadata = isRecord(input.executionEvent.metadata) ? input.executionEvent.metadata : {};
+  const phase = optionalString(metadata.phase);
+  const target = optionalString(input.executionEvent.target);
+  const eventType = optionalString(input.executionEvent.eventType);
+  const summarySource =
+    optionalString(input.executionEvent.summary) ?? [target, phase].filter(Boolean).join(" ");
+  if (summarySource.trim() === "") return null;
+  const normalizedType = normalizeEvolutionEventType(eventType);
+  const kind = classifyEvidenceEvent({
+    error: null,
+    summary: summarySource,
+    target,
+    eventType,
+    phase,
+  });
+  const trigger = decideEvolutionTrigger({
+    eventType: normalizedType,
+    summary: summarySource,
+    kind,
+  });
+
+  return {
+    id: `event-${String(input.sequence).padStart(4, "0")}`,
+    kind,
+    eventType: normalizedType,
+    hookEventId: sanitizeOptionalId(input.executionEvent.eventId),
+    occurredAt: optionalString(input.executionEvent.timestamp),
+    summary: sanitizeText(summarySource),
+    roleId: sanitizeOptionalId(input.executionEvent.roleId) ?? sanitizeId(input.roleId),
+    taskId: sanitizeOptionalId(input.executionEvent.taskId),
+    evidenceRef: `${input.sourceRefId}#L${input.lineNumber}`,
+    episodeIds: [],
+    triggerStrength: trigger.strength,
+    triggerReason: trigger.reason,
+    rawContentStored: false,
+  };
+}
+
+async function readTraceEvidenceEvents(input: {
+  path: string;
+  roleId: string;
+  sourceRefId: string;
+  existingCount: number;
+}): Promise<{ events: EvolutionEvidenceEvent[]; warnings: string[] }> {
+  const raw = await readFile(input.path, "utf8");
+  const lines = raw.split("\n");
+  const events: EvolutionEvidenceEvent[] = [];
+  const warnings: string[] = [];
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index]?.trim();
+    if (line === undefined || line === "") continue;
+
+    try {
+      const value = JSON.parse(line) as unknown;
+      if (!isRecord(value)) continue;
+      const event = createEvidenceEventFromTrace({
+        trace: value,
+        roleId: input.roleId,
+        sourceRefId: input.sourceRefId,
+        lineNumber: index + 1,
+        sequence: input.existingCount + events.length + 1,
+      });
+      if (event !== null) events.push(event);
+    } catch {
+      warnings.push(`Skipped malformed trace JSON at ${basename(input.path)}:${index + 1}.`);
+    }
+  }
+
+  return { events, warnings };
+}
+
+function createEvidenceEventFromTrace(input: {
+  trace: Record<string, unknown>;
+  roleId: string;
+  sourceRefId: string;
+  lineNumber: number;
+  sequence: number;
+}): EvolutionEvidenceEvent | null {
+  const phase = optionalString(input.trace.phase);
+  const target = optionalString(input.trace.target);
+  const traceEvent = isRecord(input.trace.event) ? input.trace.event : null;
+  const result = isRecord(input.trace.result) ? input.trace.result : null;
+  const error = optionalString(input.trace.error);
+  const eventSummary = traceEvent === null ? null : optionalString(traceEvent.summary);
+  const eventType = traceEvent === null ? null : optionalString(traceEvent.type);
+  const eventId = traceEvent === null ? null : optionalString(traceEvent.eventId);
+  const resultSummary = result === null ? null : optionalString(result.summary);
+  const summarySource =
+    error ?? resultSummary ?? eventSummary ?? [target, phase].filter(Boolean).join(" ");
+  if (summarySource.trim() === "") return null;
+  const normalizedType = normalizeEvolutionEventType(eventType);
+  const trigger = decideEvolutionTrigger({
+    eventType: normalizedType,
+    summary: summarySource,
+    kind: classifyEvidenceEvent({
+      error,
+      summary: summarySource,
+      target,
+      eventType,
+      phase,
+    }),
+  });
+
+  return {
+    id: `event-${String(input.sequence).padStart(4, "0")}`,
+    kind: classifyEvidenceEvent({
+      error,
+      summary: summarySource,
+      target,
+      eventType,
+      phase,
+    }),
+    eventType: normalizedType,
+    hookEventId: eventId === null ? null : sanitizeId(eventId),
+    occurredAt: optionalString(input.trace.timestamp),
+    summary: sanitizeText(summarySource),
+    roleId: sanitizeId(input.roleId),
+    taskId: extractTraceTaskId(input.trace),
+    evidenceRef: `${input.sourceRefId}#L${input.lineNumber}`,
+    episodeIds: [],
+    triggerStrength: trigger.strength,
+    triggerReason: trigger.reason,
+    rawContentStored: false,
+  };
+}
+
+function classifyEvidenceEvent(input: {
+  error: string | null;
+  summary: string;
+  target: string | null;
+  eventType: string | null;
+  phase: string | null;
+}): EvolutionEvidenceEventKind {
+  const haystack = [input.summary, input.target, input.eventType, input.phase]
+    .filter(Boolean)
+    .join(" ");
+  const normalizedType = normalizeEvolutionEventType(input.eventType);
+  if (
+    normalizedType === "StopFailure" ||
+    normalizedType === "PostToolUseFailure" ||
+    normalizedType === "PermissionDenied"
+  ) {
+    return "error";
+  }
+  if (
+    normalizedType === "PreToolUse" ||
+    normalizedType === "PostToolUse" ||
+    normalizedType === "PermissionRequest" ||
+    normalizedType === "PostToolBatch"
+  ) {
+    return "tool-call";
+  }
+  if (normalizedType === "SubagentStart" || normalizedType === "SubagentStop") return "subagent";
+  if (
+    normalizedType === "SessionStart" ||
+    normalizedType === "SessionEnd" ||
+    normalizedType === "UserPromptSubmit" ||
+    normalizedType === "Stop" ||
+    normalizedType === "TaskCreated" ||
+    normalizedType === "TaskCompleted"
+  ) {
+    return "run-state";
+  }
+  if (input.error !== null || /error|failed|failure|issue/i.test(haystack)) return "error";
+  if (/skill/i.test(haystack)) return "skill-call";
+  if (/subagent|agent|team|role/i.test(haystack)) return "subagent";
+  if (/tool/i.test(haystack)) return "tool-call";
+  if (/verify|verification|test|lint|typecheck|build/i.test(haystack)) return "verification";
+  if (/review/i.test(haystack)) return "review";
+  if (/completed|started|stopped|running/i.test(haystack)) return "run-state";
+  return "trace";
+}
+
+function buildEvolutionEpisodeAnalysis(events: EvolutionEvidenceEvent[]): {
+  events: EvolutionEvidenceEvent[];
+  episodes: EvolutionEpisode[];
+  triggerPolicy: EvolutionTriggerPolicy;
+} {
+  const episodeLinks = new Map<string, string[]>();
+  const episodes: EvolutionEpisode[] = [];
+  const addEpisode = (input: Omit<EvolutionEpisode, "rawContentStored">) => {
+    if (input.eventIds.length === 0) return;
+    const episode: EvolutionEpisode = { ...input, rawContentStored: false };
+    episodes.push(episode);
+    for (const eventId of episode.eventIds) {
+      episodeLinks.set(eventId, [...(episodeLinks.get(eventId) ?? []), episode.id]);
+    }
+  };
+
+  if (events.length > 0) {
+    const strongest = strongestTrigger(events);
+    addEpisode({
+      id: "episode-session-0001",
+      kind: "session",
+      status: events.some((event) => event.eventType === "StopFailure") ? "failed" : "closed",
+      roleId: null,
+      taskId: null,
+      startedAt: events[0]?.occurredAt ?? null,
+      endedAt: events.at(-1)?.occurredAt ?? null,
+      eventIds: events.map((event) => event.id),
+      triggerStrength: strongest.strength,
+      triggerReason: strongest.reason,
+      summary: `Session episode with ${events.length} metadata event(s).`,
+    });
+  }
+
+  let turnEvents: EvolutionEvidenceEvent[] = [];
+  let turnIndex = 1;
+  const closeTurn = (status: EvolutionEpisodeStatus) => {
+    if (turnEvents.length === 0) return;
+    const strongest = strongestTrigger(turnEvents);
+    addEpisode({
+      id: `episode-turn-${String(turnIndex).padStart(4, "0")}`,
+      kind: "turn",
+      status,
+      roleId: firstRoleId(turnEvents),
+      taskId: firstTaskId(turnEvents),
+      startedAt: turnEvents[0]?.occurredAt ?? null,
+      endedAt: turnEvents.at(-1)?.occurredAt ?? null,
+      eventIds: turnEvents.map((event) => event.id),
+      triggerStrength: strongest.strength,
+      triggerReason: strongest.reason,
+      summary: `Turn episode closed with ${turnEvents.length} metadata event(s).`,
+    });
+    turnEvents = [];
+    turnIndex += 1;
+  };
+  for (const event of events) {
+    if (event.eventType === "UserPromptSubmit") {
+      closeTurn("open");
+      turnEvents = [event];
+      continue;
+    }
+    if (turnEvents.length > 0) turnEvents.push(event);
+    if (event.eventType === "Stop" || event.eventType === "StopFailure") {
+      closeTurn(event.eventType === "StopFailure" ? "failed" : "closed");
+    }
+  }
+  closeTurn("open");
+
+  const taskIds = uniqueSanitizedIds(
+    events.flatMap((event) => (event.taskId === null ? [] : [event.taskId])),
+  );
+  taskIds.forEach((taskId, index) => {
+    const taskEvents = events.filter((event) => event.taskId === taskId);
+    const strongest = strongestTrigger(taskEvents);
+    addEpisode({
+      id: `episode-task-${String(index + 1).padStart(4, "0")}`,
+      kind: "task",
+      status: taskEvents.some((event) => event.eventType === "StopFailure") ? "failed" : "closed",
+      roleId: firstRoleId(taskEvents),
+      taskId,
+      startedAt: taskEvents[0]?.occurredAt ?? null,
+      endedAt: taskEvents.at(-1)?.occurredAt ?? null,
+      eventIds: taskEvents.map((event) => event.id),
+      triggerStrength: strongest.strength,
+      triggerReason: strongest.reason,
+      summary: `Task episode ${taskId} contains ${taskEvents.length} metadata event(s).`,
+    });
+  });
+
+  const roleIds = uniqueSanitizedIds(
+    events.flatMap((event) => (event.roleId === null ? [] : [event.roleId])),
+  );
+  roleIds.forEach((roleId, index) => {
+    const roleEvents = events.filter((event) => event.roleId === roleId);
+    const strongest = strongestTrigger(roleEvents);
+    addEpisode({
+      id: `episode-role-${String(index + 1).padStart(4, "0")}`,
+      kind: "role",
+      status: roleEvents.some((event) => event.eventType === "StopFailure") ? "failed" : "closed",
+      roleId,
+      taskId: firstTaskId(roleEvents),
+      startedAt: roleEvents[0]?.occurredAt ?? null,
+      endedAt: roleEvents.at(-1)?.occurredAt ?? null,
+      eventIds: roleEvents.map((event) => event.id),
+      triggerStrength: strongest.strength,
+      triggerReason: strongest.reason,
+      summary: `Role episode ${roleId} contains ${roleEvents.length} metadata event(s).`,
+    });
+  });
+
+  return {
+    events: events.map((event) => ({ ...event, episodeIds: episodeLinks.get(event.id) ?? [] })),
+    episodes,
+    triggerPolicy: createTriggerPolicy(events),
+  };
+}
+
+function firstRoleId(events: EvolutionEvidenceEvent[]): string | null {
+  return events.find((event) => event.roleId !== null)?.roleId ?? null;
+}
+
+function firstTaskId(events: EvolutionEvidenceEvent[]): string | null {
+  return events.find((event) => event.taskId !== null)?.taskId ?? null;
+}
+
+function extractTraceTaskId(trace: Record<string, unknown>): string | null {
+  const event = isRecord(trace.event) ? trace.event : {};
+  const metadata = isRecord(event.metadata) ? event.metadata : {};
+  const input = isRecord(trace.input) ? trace.input : {};
+  const payload = isRecord(input.payload) ? input.payload : {};
+  return sanitizeOptionalId(
+    metadata.taskId ??
+      metadata.task_id ??
+      payload.taskId ??
+      payload.task_id ??
+      payload.taskID ??
+      null,
+  );
+}
+
+function resolveEvolutionProjectKey(input: EvolutionAnalyzeInput): string {
+  if (input.projectKey !== undefined) return sanitizeId(input.projectKey);
+  if (input.projectDir !== undefined) return resolveProjectLogKey(input.homeDir, input.projectDir);
+  throw new Error("Missing project scope: pass --project <projectKey> or --project-dir <path>.");
+}

package/src/evolution/evidence/index.ts

@@ -0,0 +1,3 @@
+export * as runtimeLogs from "../../runtime-logs/index.ts";
+export * as sessionMemory from "./session-memory/index.ts";
+export * as traceRefs from "../../code-agent-traces/index.ts";