@evo-dev/core 0.0.1-alpha → 0.0.1-alpha.10

package/src/evolution/triggers/classification.ts

@@ -0,0 +1,102 @@
+import type {
+  EvolutionEvidenceEvent,
+  EvolutionEvidenceEventKind,
+  EvolutionEvidenceWindow,
+  EvolutionEvosCase,
+  EvolutionNormalizedEventType,
+  EvolutionTriggerPolicy,
+  EvolutionTriggerReason,
+  EvolutionTriggerStrength,
+} from "../schema.ts";
+import { NORMALIZED_EVENT_TYPES, sanitizeText } from "../shared.ts";
+
+export function normalizeEvolutionEventType(
+  value: string | null | undefined,
+): EvolutionNormalizedEventType {
+  if (value === "AgentStop") return "SubagentStop";
+  if (typeof value === "string" && (NORMALIZED_EVENT_TYPES as readonly string[]).includes(value)) {
+    return value as EvolutionNormalizedEventType;
+  }
+  return "unknown";
+}
+
+export function decideEvolutionTrigger(input: {
+  eventType: EvolutionNormalizedEventType;
+  summary: string;
+  kind: EvolutionEvidenceEventKind;
+}): { strength: EvolutionTriggerStrength; reason: EvolutionTriggerReason } {
+  if (input.eventType === "TaskCompleted") return { strength: "strong", reason: "task-completed" };
+  if (input.eventType === "StopFailure") return { strength: "strong", reason: "stop-failure" };
+  if (input.eventType === "PostToolUseFailure")
+    return { strength: "strong", reason: "tool-failure" };
+  if (input.eventType === "PermissionDenied")
+    return { strength: "strong", reason: "permission-denied" };
+  if (input.eventType === "Stop") return { strength: "conditional", reason: "turn-completed" };
+  if (input.eventType === "SessionEnd") return { strength: "conditional", reason: "session-ended" };
+  if (input.eventType === "SubagentStop")
+    return { strength: "conditional", reason: "role-completed" };
+  if (input.kind === "error" || /fail|failed|failure|error|issue/i.test(input.summary)) {
+    return { strength: "strong", reason: "failure-signal" };
+  }
+  return { strength: "none", reason: "none" };
+}
+
+export function createTriggerPolicy(events: EvolutionEvidenceEvent[]): EvolutionTriggerPolicy {
+  const failures = events.filter((event) => event.kind === "error").length;
+  const verifications = events.filter((event) => event.kind === "verification").length;
+  const roleLifecycle = events.filter((event) => event.kind === "subagent").length;
+  const skillCalls = events.filter((event) => event.kind === "skill-call").length;
+  const strongest = strongestTrigger(events);
+  const reasons = uniqueTriggerReasons(
+    events.flatMap((event) => (event.triggerReason === "none" ? [] : [event.triggerReason])),
+  );
+  const hasSignal = failures > 0 || verifications > 0 || roleLifecycle > 0 || skillCalls > 0;
+  return {
+    strongest: strongest.strength,
+    reasons,
+    distillRecommended:
+      strongest.strength === "strong" || (strongest.strength === "conditional" && hasSignal),
+    evidenceSignals: { failures, verifications, roleLifecycle, skillCalls },
+  };
+}
+
+export function strongestTrigger(events: EvolutionEvidenceEvent[]): {
+  strength: EvolutionTriggerStrength;
+  reason: EvolutionTriggerReason;
+} {
+  const strong = events.find((event) => event.triggerStrength === "strong");
+  if (strong !== undefined) return { strength: "strong", reason: strong.triggerReason };
+  const conditional = events.find((event) => event.triggerStrength === "conditional");
+  if (conditional !== undefined) {
+    return { strength: "conditional", reason: conditional.triggerReason };
+  }
+  return { strength: "none", reason: "none" };
+}
+
+export function uniqueTriggerReasons(values: EvolutionTriggerReason[]): EvolutionTriggerReason[] {
+  return [...new Set(values)].filter((reason) => reason !== "none");
+}
+
+export function chooseEvosTriggerKind(
+  evidenceWindow: EvolutionEvidenceWindow,
+): EvolutionEvosCase["trigger"]["kind"] {
+  if (evidenceWindow.triggerPolicy.reasons.includes("task-completed")) return "task-completion";
+  if (evidenceWindow.triggerPolicy.reasons.includes("turn-completed")) return "session-completion";
+  if (evidenceWindow.triggerPolicy.reasons.includes("session-ended")) return "session-completion";
+  return "manual";
+}
+
+export function createTriggerSummary(evidenceWindow: EvolutionEvidenceWindow): string {
+  const reasons = evidenceWindow.triggerPolicy.reasons.join(", ") || "manual";
+  return sanitizeText(
+    `Evolution distillation used ${evidenceWindow.triggerPolicy.strongest} trigger evidence: ${reasons}.`,
+  );
+}
+
+export function createTriggerDecisionSummary(
+  eventType: EvolutionNormalizedEventType,
+  strength: EvolutionTriggerStrength,
+  reason: EvolutionTriggerReason,
+): string {
+  return `Hook event ${eventType} classified as ${strength} evolution trigger (${reason}).`;
+}

package/src/evolution/triggers/index.ts

@@ -0,0 +1,295 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { resolveEvoDevPaths } from "../../config/paths.ts";
+import {
+  createStableId,
+  isFileExistsError,
+  normalizeTimestamp,
+  readJsonFiles,
+  writeJsonFile as writeJson,
+} from "../../utils/index.ts";
+import { resolveEvolutionPaths } from "../paths.ts";
+import type {
+  EvolutionTriggerDecision,
+  EvolutionTriggerInput,
+  EvolutionTriggerListInput,
+  EvolutionTriggerRecord,
+  EvolutionTriggerStatus,
+  SegmentEvolutionTriggerInput,
+  SegmentEvolutionTriggerListInput,
+  SegmentEvolutionTriggerRecord,
+} from "../schema.ts";
+import {
+  createPrivacyFields,
+  listDirectoryNames,
+  parseSegmentTrigger,
+  parseTrigger,
+  sanitizeId,
+  sanitizeStorageId,
+  sanitizeText,
+  validateEvolutionTriggerRecord,
+  validateSegmentEvolutionTriggerRecord,
+} from "../shared.ts";
+import {
+  createTriggerDecisionSummary,
+  decideEvolutionTrigger,
+  normalizeEvolutionEventType,
+} from "./classification.ts";
+
+export function resolveEvolutionTriggerDecision(input: {
+  eventType: string;
+  summary?: string | null;
+}): EvolutionTriggerDecision {
+  const eventType = normalizeEvolutionEventType(input.eventType);
+  const trigger = decideEvolutionTrigger({
+    eventType,
+    summary: input.summary ?? "",
+    kind: "trace",
+  });
+  return {
+    eventType,
+    strength: trigger.strength,
+    reason: trigger.reason,
+    shouldQueue: trigger.strength !== "none",
+    summary: createTriggerDecisionSummary(eventType, trigger.strength, trigger.reason),
+  };
+}
+
+export async function enqueueEvolutionTrigger(
+  input: EvolutionTriggerInput,
+): Promise<EvolutionTriggerRecord | null> {
+  const decision = resolveEvolutionTriggerDecision({
+    eventType: input.eventType,
+    summary: input.summary,
+  });
+  if (!decision.shouldQueue) return null;
+
+  const now = normalizeTimestamp(input.now);
+  const projectKey = sanitizeId(input.projectKey);
+  const runId = sanitizeId(input.runId);
+  const id = createStableId("trigger", [
+    projectKey,
+    runId,
+    input.roleId ?? "",
+    input.eventId ?? "",
+    decision.eventType,
+    now,
+  ]);
+  const trigger: EvolutionTriggerRecord = {
+    schemaVersion: 1,
+    id,
+    kind: "evolution-trigger",
+    projectKey,
+    runId,
+    roleId: input.roleId === undefined || input.roleId === null ? null : sanitizeId(input.roleId),
+    taskId: input.taskId === undefined || input.taskId === null ? null : sanitizeId(input.taskId),
+    eventType: decision.eventType,
+    eventId:
+      input.eventId === undefined || input.eventId === null ? null : sanitizeId(input.eventId),
+    evidenceRef:
+      input.evidenceRef === undefined || input.evidenceRef === null
+        ? null
+        : sanitizeText(input.evidenceRef),
+    summary: sanitizeText(input.summary ?? decision.summary),
+    triggerStrength: decision.strength,
+    triggerReason: decision.reason,
+    status: "pending",
+    attempts: 0,
+    createdAt: now,
+    updatedAt: now,
+    processedBatchId: null,
+    lastError: null,
+    rawContentStored: false,
+    privacy: createPrivacyFields(input.summary ?? decision.summary),
+  };
+  validateEvolutionTriggerRecord(trigger);
+  const paths = resolveEvolutionPaths({ homeDir: input.homeDir, projectKey, runId });
+  await writeJson(join(paths.triggersDir, `${trigger.id}.json`), trigger, { overwrite: false });
+  return trigger;
+}
+
+export async function listEvolutionTriggers(
+  input: EvolutionTriggerListInput,
+): Promise<EvolutionTriggerRecord[]> {
+  const paths = resolveEvoDevPaths(input.homeDir);
+  const evolutionStateDir = join(paths.stateDir, "evolution");
+  const projectKeys =
+    input.projectKey === undefined
+      ? await listDirectoryNames(evolutionStateDir)
+      : [sanitizeStorageId("projectKey", input.projectKey)];
+  const triggers: EvolutionTriggerRecord[] = [];
+  for (const projectKey of projectKeys) {
+    const projectStateDir = join(evolutionStateDir, projectKey);
+    const runIds =
+      input.runId === undefined
+        ? await listDirectoryNames(projectStateDir)
+        : [sanitizeStorageId("runId", input.runId)];
+    for (const runId of runIds) {
+      const runTriggers = await readJsonFiles(
+        join(projectStateDir, runId, "triggers"),
+        parseTrigger,
+      );
+      triggers.push(
+        ...runTriggers.filter(
+          (trigger) => input.status === undefined || trigger.status === input.status,
+        ),
+      );
+    }
+  }
+  return triggers.sort((left, right) => left.createdAt.localeCompare(right.createdAt));
+}
+
+export async function enqueueSegmentEvolutionTrigger(
+  input: SegmentEvolutionTriggerInput,
+): Promise<SegmentEvolutionTriggerRecord> {
+  const now = normalizeTimestamp(input.now);
+  const projectKey = sanitizeId(input.projectKey);
+  const sessionKey = sanitizeId(input.sessionKey);
+  const segmentId = sanitizeId(input.segmentId);
+  const id = createStableId("segment-trigger", [projectKey, sessionKey, segmentId]);
+  const trigger: SegmentEvolutionTriggerRecord = {
+    schemaVersion: 1,
+    id,
+    kind: "segment-evolution-trigger",
+    projectKey,
+    sessionKey,
+    runId: input.runId === undefined || input.runId === null ? null : sanitizeId(input.runId),
+    roleId: input.roleId === undefined || input.roleId === null ? null : sanitizeId(input.roleId),
+    segmentId,
+    segmentPath: sanitizeText(input.segmentPath),
+    strength: input.strength,
+    reason: input.reason,
+    summary: sanitizeText(input.summary),
+    status: "pending",
+    attempts: 0,
+    createdAt: now,
+    updatedAt: now,
+    processedBatchId: null,
+    lastError: null,
+    rawContentStored: false,
+  };
+  validateSegmentEvolutionTriggerRecord(trigger);
+  const path = resolveSegmentEvolutionTriggerPath(input.homeDir, trigger);
+  try {
+    await writeJson(path, trigger, { overwrite: false });
+    return trigger;
+  } catch (error) {
+    if (!isFileExistsError(error)) throw error;
+    return parseSegmentTrigger(JSON.parse(await readFile(path, "utf8")) as unknown);
+  }
+}
+
+export async function listSegmentEvolutionTriggers(
+  input: SegmentEvolutionTriggerListInput,
+): Promise<SegmentEvolutionTriggerRecord[]> {
+  const paths = resolveEvoDevPaths(input.homeDir);
+  const evolutionStateDir = join(paths.stateDir, "evolution");
+  const projectKeys =
+    input.projectKey === undefined
+      ? await listDirectoryNames(evolutionStateDir)
+      : [sanitizeStorageId("projectKey", input.projectKey)];
+  const triggers: SegmentEvolutionTriggerRecord[] = [];
+  for (const projectKey of projectKeys) {
+    const projectSegmentsDir = join(evolutionStateDir, projectKey, "segments");
+    const projectTriggers = await readJsonFiles(projectSegmentsDir, parseSegmentTrigger);
+    triggers.push(
+      ...projectTriggers.filter((trigger) => {
+        if (input.status !== undefined && trigger.status !== input.status) return false;
+        if (
+          input.runId !== undefined &&
+          trigger.runId !== sanitizeStorageId("runId", input.runId)
+        ) {
+          return false;
+        }
+        return true;
+      }),
+    );
+  }
+  return triggers.sort((left, right) => left.createdAt.localeCompare(right.createdAt));
+}
+
+export function groupTriggersByRun(triggers: EvolutionTriggerRecord[]): EvolutionTriggerRecord[][] {
+  const groups = new Map<string, EvolutionTriggerRecord[]>();
+  for (const trigger of triggers) {
+    const key = `${trigger.projectKey}\0${trigger.runId}`;
+    groups.set(key, [...(groups.get(key) ?? []), trigger]);
+  }
+  return [...groups.values()];
+}
+
+export async function updateTriggers(
+  homeDir: string,
+  triggers: EvolutionTriggerRecord[],
+  patch: {
+    status: EvolutionTriggerStatus;
+    updatedAt: string;
+    attempts?: ((trigger: EvolutionTriggerRecord) => number) | number;
+    processedBatchId?: string | null;
+    lastError?: string | null;
+  },
+): Promise<void> {
+  for (const trigger of triggers) {
+    const next: EvolutionTriggerRecord = {
+      ...trigger,
+      status: patch.status,
+      updatedAt: patch.updatedAt,
+      attempts:
+        typeof patch.attempts === "function"
+          ? patch.attempts(trigger)
+          : (patch.attempts ?? trigger.attempts),
+      processedBatchId:
+        patch.processedBatchId === undefined ? trigger.processedBatchId : patch.processedBatchId,
+      lastError: patch.lastError === undefined ? trigger.lastError : patch.lastError,
+    };
+    validateEvolutionTriggerRecord(next);
+    const paths = resolveEvolutionPaths({
+      homeDir,
+      projectKey: next.projectKey,
+      runId: next.runId,
+    });
+    await writeJson(join(paths.triggersDir, `${next.id}.json`), next, { overwrite: true });
+  }
+}
+
+export async function updateSegmentTriggers(
+  homeDir: string,
+  triggers: SegmentEvolutionTriggerRecord[],
+  patch: {
+    status: EvolutionTriggerStatus;
+    updatedAt: string;
+    attempts?: ((trigger: SegmentEvolutionTriggerRecord) => number) | number;
+    processedBatchId?: string | null;
+    lastError?: string | null;
+  },
+): Promise<void> {
+  for (const trigger of triggers) {
+    const next: SegmentEvolutionTriggerRecord = {
+      ...trigger,
+      status: patch.status,
+      updatedAt: patch.updatedAt,
+      attempts:
+        typeof patch.attempts === "function"
+          ? patch.attempts(trigger)
+          : (patch.attempts ?? trigger.attempts),
+      processedBatchId:
+        patch.processedBatchId === undefined ? trigger.processedBatchId : patch.processedBatchId,
+      lastError: patch.lastError === undefined ? trigger.lastError : patch.lastError,
+    };
+    validateSegmentEvolutionTriggerRecord(next);
+    await writeJson(resolveSegmentEvolutionTriggerPath(homeDir, next), next, { overwrite: true });
+  }
+}
+
+export function resolveSegmentEvolutionTriggerPath(
+  homeDir: string,
+  trigger: Pick<SegmentEvolutionTriggerRecord, "projectKey" | "id">,
+): string {
+  const paths = resolveEvoDevPaths(homeDir);
+  return join(
+    paths.stateDir,
+    "evolution",
+    sanitizeStorageId("projectKey", trigger.projectKey),
+    "segments",
+    `${sanitizeStorageId("segmentTrigger", trigger.id)}.json`,
+  );
+}