@evo-dev/core 0.0.1-alpha.3 → 0.0.1-alpha.4

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(),
+  };
+  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`,
+  );
+}

package/src/hooks/index.ts

@@ -1,13 +1,19 @@
-import { createHash } from "node:crypto";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import { enqueueEvolutionTrigger, resolveEvolutionTriggerDecision } from "../evolution/index.ts";
+import {
+  type SessionMemoryPolicySnapshot,
+  updateSessionMemoryFromHook,
+} from "../evolution/evidence/session-memory/index.ts";
 import {
   createScopedKnowledgeContextPack,
   formatScopedKnowledgePromptBlock,
   hasContextInjectionReceipt,
   writeContextInjectionReceipt,
-} from "../knowledge/index.ts";
+} from "../evolution/knowledge/index.ts";
+import {
+  enqueueEvolutionTrigger,
+  resolveEvolutionTriggerDecision,
+} from "../evolution/triggers/index.ts";
 import { resolveTraceTeamContext } from "../runtime-logs/index.ts";
 import {
   type TaskContract,
@@ -24,6 +30,7 @@ import {
   resolveTeamRunPaths,
   updateTeamAgentHookState,
 } from "../team/index.ts";
+import { sha256Short } from "../utils/index.ts";
 
 export const CANONICAL_HOOK_EVENT_TYPES = [
   "SessionStart",
@@ -180,6 +187,7 @@ export interface HandleHookRuntimeInput {
   receivedAt?: string;
   environment?: Record<string, string | undefined>;
   runtimeInjectionEnabled?: boolean;
+  sessionMemoryPolicy?: Partial<SessionMemoryPolicySnapshot>;
 }
 
 const DEFAULT_EVENT_SETTINGS: Record<CanonicalHookEventType, boolean> = {
@@ -468,7 +476,12 @@ export async function handleHookRuntime(input: HandleHookRuntimeInput): Promise<
   } else if (result === undefined) {
     result = await handleAdditionalContext(input, input.event.type);
   }
-  const evolutionDiagnostics = await recordEvolutionTriggerFromHook(input);
+  const sessionMemoryDiagnostics = await recordSessionMemoryFromHook(input);
+  const evolutionDiagnostics =
+    sessionMemoryDiagnostics.queuedSegmentTriggerId !== null ||
+    shouldSuppressLegacyEvolutionTrigger(input.event.type)
+      ? { stateWrites: [], warnings: [] }
+      : await recordEvolutionTriggerFromHook(input);
   const messageDiagnostics = await deliverPendingTeamMessagesFromHook(input, result);
   const scopedContextDiagnostics = await injectScopedKnowledgeContextFromHook(input, result);
   const teamStateDiagnostics = await recordTeamAgentHookStateFromHook(input);
@@ -476,7 +489,10 @@ export async function handleHookRuntime(input: HandleHookRuntimeInput): Promise<
     appendRuntimeDiagnostics(
       appendRuntimeDiagnostics(
         appendRuntimeDiagnostics(
-          appendRuntimeDiagnostics(result, diagnostics),
+          appendRuntimeDiagnostics(
+            appendRuntimeDiagnostics(result, diagnostics),
+            sessionMemoryDiagnostics,
+          ),
           evolutionDiagnostics,
         ),
         messageDiagnostics,
@@ -611,6 +627,37 @@ async function recordEvolutionTriggerFromHook(
   }
 }
 
+async function recordSessionMemoryFromHook(
+  input: HandleHookRuntimeInput,
+): Promise<HookRuntimeDiagnostics & { queuedSegmentTriggerId: string | null }> {
+  try {
+    const result = await updateSessionMemoryFromHook({
+      homeDir: input.homeDir,
+      target: input.target,
+      event: input.event,
+      rawPayload: input.rawPayload,
+      environment: input.environment,
+      receivedAt: input.receivedAt,
+      policy: input.sessionMemoryPolicy,
+    });
+    return {
+      stateWrites: result.stateWrites,
+      warnings: result.warnings,
+      queuedSegmentTriggerId: result.queuedSegmentTriggerId,
+    };
+  } catch {
+    return {
+      stateWrites: [],
+      warnings: ["Session Memory state could not be updated at this hook safe point."],
+      queuedSegmentTriggerId: null,
+    };
+  }
+}
+
+function shouldSuppressLegacyEvolutionTrigger(eventType: CanonicalHookEventType): boolean {
+  return eventType === "Stop" || eventType === "SubagentStop" || eventType === "SessionEnd";
+}
+
 async function deliverPendingTeamMessagesFromHook(
   input: HandleHookRuntimeInput,
   result: HookRuntimeResult | undefined,
@@ -1139,7 +1186,7 @@ function resolveHookSessionKey(payload: Record<string, unknown>): string {
   const sessionId = optionalPayloadString(payload.session_id ?? payload.sessionId);
   const cwd = optionalPayloadString(payload.cwd);
   const source = sessionId ?? cwd ?? "local";
-  return `session-${createHash("sha256").update(source).digest("hex").slice(0, 16)}`;
+  return `session-${sha256Short(source)}`;
 }
 
 async function writeJsonFile(path: string, value: unknown): Promise<void> {
@@ -1297,7 +1344,7 @@ function stableEventId(
 
 function hashOptionalIdentifier(value: unknown): string | null {
   if (typeof value !== "string" || value.length === 0) return null;
-  return `sha256-${createHash("sha256").update(value).digest("hex").slice(0, 16)}`;
+  return `sha256-${sha256Short(value)}`;
 }
 
 function optionalBoolean(value: unknown, fallback: boolean, path: string): boolean {

package/src/index.ts

@@ -4,9 +4,17 @@ export * from "./code-agent-traces/index.ts";
 export * from "./config/index.ts";
 export * from "./daemon/index.ts";
 export * from "./evolution/index.ts";
+export * as evolutionCandidates from "./evolution/candidates/index.ts";
+export * as evolutionControl from "./evolution/control/index.ts";
+export * as evolutionEvidence from "./evolution/evidence/index.ts";
+export * from "./evolution/evidence/session-memory/index.ts";
+export * from "./evolution/knowledge/index.ts";
+export * as evolutionKnowledge from "./evolution/knowledge/index.ts";
+export * as evolutionProcessor from "./evolution/processor/index.ts";
+export * from "./evolution/review/index.ts";
+export * as evolutionReview from "./evolution/review/index.ts";
+export * as evolutionTriggers from "./evolution/triggers/index.ts";
 export * from "./hooks/index.ts";
-export * from "./knowledge/index.ts";
-export * from "./learning/index.ts";
 export * from "./observability/index.ts";
 export * from "./pack/index.ts";
 export * from "./plugins/index.ts";

package/src/runtime-logs/index.ts

@@ -1,7 +1,7 @@
-import { createHash } from "node:crypto";
 import { appendFile, mkdir } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative } from "node:path";
 import { resolveEvoDevPaths } from "../config/paths.ts";
+import { normalizeTimestamp, sha256Short } from "../utils/index.ts";
 
 export type EvoDevLogPhase = "started" | "completed" | "failed";
 export type EvoDevDebugLogLevel = "verbose" | "debug" | "info" | "warn" | "error";
@@ -559,7 +559,7 @@ export function resolveTraceSessionKey(payload: unknown): string {
   const sessionId = optionalString(record.session_id ?? record.sessionId);
   const cwd = optionalString(record.cwd);
   const source = sessionId ?? cwd ?? "local";
-  return `session-${createHash("sha256").update(source).digest("hex").slice(0, 16)}`;
+  return `session-${sha256Short(source)}`;
 }
 
 function sanitizeTraceLogEntryForAppend(entry: TraceLogEntryV1): TraceLogEntryV1 {
@@ -644,12 +644,6 @@ async function appendJsonLine(path: string, value: unknown): Promise<void> {
   await appendFile(path, `${JSON.stringify(value)}\n`, "utf8");
 }
 
-function normalizeTimestamp(value?: Date | string): string {
-  if (value instanceof Date) return value.toISOString();
-  if (typeof value === "string" && value.trim() !== "") return new Date(value).toISOString();
-  return new Date().toISOString();
-}
-
 function formatLocalDateKey(timestamp: string): string {
   const date = new Date(timestamp);
   const year = date.getFullYear();
@@ -727,8 +721,7 @@ function createExecutionEventId(input: {
   summary: string;
   metadata: Record<string, EvoDevExecutionEventMetadataValue>;
 }): string {
-  const hash = createHash("sha256").update(JSON.stringify(input)).digest("hex").slice(0, 16);
-  return `exec-${hash}`;
+  return `exec-${sha256Short(JSON.stringify(input))}`;
 }
 
 function sanitizeDebugValue(value: unknown, depth = 0): unknown {
@@ -775,8 +768,7 @@ function sanitizePersistentIdentifier(value: string, prefix: string): string {
   if (!SENSITIVE_EVENT_TEXT_PATTERN.test(value) && !SENSITIVE_EVENT_TEXT_PATTERN.test(pathSafe)) {
     return pathSafe;
   }
-  const hash = createHash("sha256").update(value).digest("hex").slice(0, 16);
-  return `${prefix}-${hash}`;
+  return `${prefix}-${sha256Short(value)}`;
 }
 
 function stripTrailingSlash(path: string): string {

package/src/team/index.ts

@@ -12,7 +12,7 @@ import {
   formatScopedKnowledgePromptBlock,
   hasContextInjectionReceipt,
   writeContextInjectionReceipt,
-} from "../knowledge/index.ts";
+} from "../evolution/knowledge/index.ts";
 import { resolveProjectLogKey } from "../runtime-logs/index.ts";
 import { renderTeamRoleStartupPrompt } from "./prompts.ts";
 

package/src/utils/errors.ts

@@ -0,0 +1,13 @@
+export function isNotFoundError(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    (("code" in error && (error as NodeJS.ErrnoException).code === "ENOENT") ||
+      error.message.includes("ENOENT"))
+  );
+}
+
+export function isFileExistsError(error: unknown): boolean {
+  return (
+    error instanceof Error && "code" in error && (error as NodeJS.ErrnoException).code === "EEXIST"
+  );
+}

package/src/utils/fs.ts

@@ -0,0 +1,40 @@
+import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { isNotFoundError } from "./errors.ts";
+
+export async function pathExists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch (error) {
+    if (isNotFoundError(error)) return false;
+    throw error;
+  }
+}
+
+export async function readJsonFile<T>(path: string, parse: (value: unknown) => T): Promise<T> {
+  return parse(JSON.parse(await readFile(path, "utf8")) as unknown);
+}
+
+export async function readJsonFiles<T>(dir: string, parse: (value: unknown) => T): Promise<T[]> {
+  if (!(await pathExists(dir))) return [];
+  const entries = await readdir(dir, { withFileTypes: true });
+  const values: T[] = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+    values.push(await readJsonFile(join(dir, entry.name), parse));
+  }
+  return values;
+}
+
+export async function writeJsonFile(
+  path: string,
+  value: unknown,
+  options: { overwrite?: boolean } = {},
+): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, {
+    encoding: "utf8",
+    flag: options.overwrite === false ? "wx" : "w",
+  });
+}

package/src/utils/hash.ts

@@ -0,0 +1,9 @@
+import { createHash } from "node:crypto";
+
+export function sha256Hex(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+export function sha256Short(value: string, length = 16): string {
+  return sha256Hex(value).slice(0, length);
+}

package/src/utils/ids.ts

@@ -0,0 +1,12 @@
+import { sha256Short } from "./hash.ts";
+
+export function createStableId(prefix: string, parts: string[]): string {
+  return `${prefix}-${sha256Short(parts.join("\0"))}`;
+}
+
+export function sanitizeStorageId(value: string, fallbackPrefix: string): string {
+  const sanitized = value.replace(/[^a-zA-Z0-9._-]/g, "-").slice(0, 120);
+  return sanitized === "" || sanitized === "." || sanitized === ".."
+    ? `${fallbackPrefix}-local`
+    : sanitized;
+}

package/src/utils/index.ts

@@ -0,0 +1,7 @@
+export * from "./errors.ts";
+export * from "./fs.ts";
+export * from "./hash.ts";
+export * from "./ids.ts";
+export * from "./parsing.ts";
+export * from "./text.ts";
+export * from "./time.ts";