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

package/src/evolution/evidence/session-memory/analysis.ts

@@ -0,0 +1,287 @@
+import { createStableId, normalizeTimestamp } from "../../../utils/index.ts";
+import type {
+  EvolutionEpisode,
+  EvolutionEvidenceEvent,
+  EvolutionEvidenceEventKind,
+  EvolutionEvidenceWindow,
+  EvolutionTriggerReason,
+  EvolutionTriggerStrength,
+} from "../../schema.ts";
+import {
+  MAX_EVIDENCE_EVENTS,
+  createPrivacyFields,
+  displayPath,
+  sanitizeId,
+  sanitizeOptionalId,
+  sanitizeText,
+  validateEvolutionEvidenceWindow,
+} from "../../shared.ts";
+import {
+  createTriggerPolicy,
+  decideEvolutionTrigger,
+  normalizeEvolutionEventType,
+  strongestTrigger,
+} from "../../triggers/classification.ts";
+import { resolveSessionMemoryPaths } from "./paths.ts";
+import { redactSessionMemoryCredentialText } from "./sensitivity.ts";
+import type {
+  SessionEvidenceSegmentV1,
+  SessionMemorySegmentReason,
+  SessionMemorySignal,
+  SessionMemorySignalStrength,
+} from "./types.ts";
+
+export type SessionSegmentDistillationSkipReason =
+  | "sensitive-segment"
+  | "segment-deleted"
+  | "segment-raw-expired"
+  | "segment-ignored"
+  | "segment-rejected"
+  | "no-distillation-signal";
+
+export interface SessionSegmentEvidenceAnalysis {
+  evidenceWindow: EvolutionEvidenceWindow | null;
+  skipReason: SessionSegmentDistillationSkipReason | null;
+  warnings: string[];
+}
+
+/**
+ * Converts a stored Session Memory segment into the metadata-only evidence contract consumed by
+ * the existing distillation and OKF activation pipeline. Raw excerpts are deliberately excluded.
+ */
+export function analyzeSessionEvidenceSegment(input: {
+  homeDir: string;
+  segment: SessionEvidenceSegmentV1;
+  now?: string | Date;
+}): SessionSegmentEvidenceAnalysis {
+  const { segment } = input;
+  if (segment.lifecycle.status === "deleted") return skipped("segment-deleted");
+  if (segment.lifecycle.status === "raw-expired") return skipped("segment-raw-expired");
+  if (segment.lifecycle.status === "ignored") return skipped("segment-ignored");
+  if (segment.lifecycle.reviewState === "rejected") return skipped("segment-rejected");
+
+  const roleId = resolveSegmentRoleId(segment);
+  const sourceRefId = "source-session-segment";
+  const episodeId = "episode-session-0001";
+  const signals = segment.signals.slice(0, MAX_EVIDENCE_EVENTS);
+  const events = signals.map((signal, index) =>
+    createSegmentEvidenceEvent({
+      signal,
+      segmentReason: segment.reason,
+      segmentStrength: segment.strength,
+      roleId,
+      sourceRefId,
+      episodeId,
+      sequence: index + 1,
+    }),
+  );
+  if (!isSegmentEligibleForDistillation(segment, events)) {
+    return skipped("no-distillation-signal");
+  }
+
+  const strongest = strongestTrigger(events);
+  const episode: EvolutionEpisode = {
+    id: episodeId,
+    kind: "session",
+    status: events.some((event) => event.kind === "error") ? "failed" : "closed",
+    roleId,
+    taskId: null,
+    startedAt: events[0]?.occurredAt ?? segment.createdAt,
+    endedAt: events.at(-1)?.occurredAt ?? segment.createdAt,
+    eventIds: events.map((event) => event.id),
+    triggerStrength: strongest.strength,
+    triggerReason: strongest.reason,
+    summary: `Session Memory segment ${segment.reason} contains ${events.length} normalized metadata signal(s).`,
+    rawContentStored: false,
+  };
+  const paths = resolveSessionMemoryPaths({
+    homeDir: input.homeDir,
+    projectKey: segment.projectKey,
+    sessionKey: segment.sessionKey,
+  });
+  const evidenceWindow: EvolutionEvidenceWindow = {
+    schemaVersion: 1,
+    id: createStableId("segment-evidence", [segment.id]),
+    kind: "evidence-window",
+    projectKey: sanitizeId(segment.projectKey),
+    // A segment needs its own run namespace so multiple segments from one native/team session do
+    // not overwrite one another's evidence window, plan, or distillation batch.
+    runId: createStableId("segment-run", [segment.projectKey, segment.sessionKey, segment.id]),
+    taskId: null,
+    createdAt: normalizeTimestamp(input.now),
+    sourceRefs: [
+      {
+        id: sourceRefId,
+        kind: "session-memory-segment",
+        path: displayPath(input.homeDir, paths.segmentPath(segment.id)),
+        roleId,
+        rawContentStored: false,
+        externalContentCopied: false,
+      },
+    ],
+    events,
+    episodes: [episode],
+    triggerPolicy: createTriggerPolicy(events),
+    privacy: createPrivacyFields({ events, episodes: [episode] }),
+  };
+  validateEvolutionEvidenceWindow(evidenceWindow);
+  return {
+    evidenceWindow,
+    skipReason: null,
+    warnings:
+      segment.signals.length > MAX_EVIDENCE_EVENTS
+        ? [
+            `Session segment metadata signals were truncated from ${segment.signals.length} to ${MAX_EVIDENCE_EVENTS}.`,
+          ]
+        : [],
+  };
+}
+
+function skipped(skipReason: SessionSegmentDistillationSkipReason): SessionSegmentEvidenceAnalysis {
+  return { evidenceWindow: null, skipReason, warnings: [] };
+}
+
+function resolveSegmentRoleId(segment: SessionEvidenceSegmentV1): string | null {
+  const explicitRoleId = sanitizeOptionalId(segment.roleId);
+  if (explicitRoleId !== null) return explicitRoleId;
+  // Ordinary non-team sessions still need a bounded role scope for OKF policy. The configured Code
+  // Agent target is a real session attribute; unknown targets remain unscoped and cannot auto-accept.
+  return segment.target === "unknown" ? null : sanitizeId(segment.target);
+}
+
+function createSegmentEvidenceEvent(input: {
+  signal: SessionMemorySignal;
+  segmentReason: SessionMemorySegmentReason;
+  segmentStrength: SessionMemorySignalStrength;
+  roleId: string | null;
+  sourceRefId: string;
+  episodeId: string;
+  sequence: number;
+}): EvolutionEvidenceEvent {
+  const eventType = normalizeEvolutionEventType(input.signal.eventType);
+  const summary =
+    sanitizeText(redactSessionMemoryCredentialText(input.signal.summary).value) ||
+    "Session metadata signal observed.";
+  const kind = classifySegmentSignal(input.signal, summary);
+  const baseTrigger = decideEvolutionTrigger({ eventType, summary, kind });
+  const segmentTrigger =
+    input.signal.reason === "observed"
+      ? null
+      : classifySegmentTrigger(input.segmentReason, input.segmentStrength);
+  const trigger = segmentTrigger ?? baseTrigger;
+  return {
+    id: `event-${String(input.sequence).padStart(4, "0")}`,
+    kind,
+    eventType,
+    hookEventId: sanitizeOptionalId(input.signal.eventId),
+    occurredAt: input.signal.occurredAt,
+    summary,
+    roleId: input.roleId,
+    taskId: null,
+    evidenceRef: `${input.sourceRefId}#signal-${input.sequence}`,
+    episodeIds: [input.episodeId],
+    triggerStrength: trigger.strength,
+    triggerReason: trigger.reason,
+    rawContentStored: false,
+  };
+}
+
+function classifySegmentSignal(
+  signal: SessionMemorySignal,
+  summary: string,
+): EvolutionEvidenceEventKind {
+  const eventType = normalizeEvolutionEventType(signal.eventType);
+  if (
+    eventType === "StopFailure" ||
+    eventType === "PostToolUseFailure" ||
+    eventType === "PermissionDenied" ||
+    signal.reason === "failure-signal" ||
+    signal.reason === "permission-denied"
+  ) {
+    return "error";
+  }
+  if (
+    signal.reason === "verification-after-fix" ||
+    /verify|test|lint|typecheck|build/i.test(summary)
+  ) {
+    return "verification";
+  }
+  if (
+    signal.reason === "user-interruption" ||
+    signal.reason === "intent-refinement" ||
+    signal.reason === "explicit-memory-intent"
+  ) {
+    return "user-feedback";
+  }
+  if (
+    eventType === "PreToolUse" ||
+    eventType === "PostToolUse" ||
+    eventType === "PermissionRequest" ||
+    eventType === "PostToolBatch"
+  ) {
+    return "tool-call";
+  }
+  if (eventType === "SubagentStart" || eventType === "SubagentStop") return "subagent";
+  if (/skill/i.test(summary)) return "skill-call";
+  if (/review/i.test(summary)) return "review";
+  if (
+    eventType === "SessionStart" ||
+    eventType === "SessionEnd" ||
+    eventType === "UserPromptSubmit" ||
+    eventType === "Stop" ||
+    eventType === "TaskCreated" ||
+    eventType === "TaskCompleted"
+  ) {
+    return "run-state";
+  }
+  return "trace";
+}
+
+function classifySegmentTrigger(
+  reason: SessionMemorySegmentReason,
+  strength: SessionMemorySignalStrength,
+): { strength: EvolutionTriggerStrength; reason: EvolutionTriggerReason } {
+  if (reason === "failure-signal") return { strength: "strong", reason: "failure-signal" };
+  if (reason === "permission-denied") return { strength: "strong", reason: "permission-denied" };
+  if (reason === "historical-import") {
+    return { strength: "strong", reason: "explicit-command" };
+  }
+  if (reason === "session-memory-init") return { strength: "none", reason: "none" };
+  return {
+    strength: strength === "strong" ? "strong" : "conditional",
+    reason: "explicit-command",
+  };
+}
+
+function isSegmentEligibleForDistillation(
+  segment: SessionEvidenceSegmentV1,
+  events: EvolutionEvidenceEvent[],
+): boolean {
+  if (events.length === 0) return false;
+  if (
+    segment.reason === "user-interruption" ||
+    segment.reason === "failure-signal" ||
+    segment.reason === "permission-denied" ||
+    segment.reason === "verification-after-fix" ||
+    segment.reason === "explicit-memory-intent" ||
+    segment.reason === "historical-import"
+  ) {
+    return true;
+  }
+
+  const hasOutcomeSignal =
+    segment.normalized.decisions.length > 0 ||
+    segment.normalized.failures.length > 0 ||
+    segment.normalized.verifications.length > 0 ||
+    events.some((event) => event.kind === "error" || event.kind === "verification");
+  if (segment.reason === "session-memory-threshold") return hasOutcomeSignal;
+  if (segment.reason !== "intent-refinement") return false;
+  return (
+    hasOutcomeSignal ||
+    segment.signals.some(
+      (signal) =>
+        signal.reason === "explicit-memory-intent" ||
+        ["TaskCompleted", "Stop", "SessionEnd", "SubagentStop"].includes(signal.eventType),
+    )
+  );
+}

package/src/evolution/evidence/session-memory/constants.ts

@@ -0,0 +1,9 @@
+export const DEFAULT_MAX_RAW_EVENT_BYTES = 64 * 1024;
+
+export const EXPLICIT_MEMORY_PATTERN =
+  /\b(remember|memorize|do not repeat|don't repeat|this is important|save this|learn this)\b/i;
+
+export const FAILURE_PATTERN = /\b(fail|failed|failure|error|issue|exception|crash)\b/i;
+
+export const VERIFICATION_PATTERN =
+  /\b(test|lint|typecheck|build|verify|verification|passed|success)\b/i;

package/src/evolution/evidence/session-memory/index.ts

@@ -0,0 +1,9 @@
+export * from "./analysis.ts";
+export * from "./paths.ts";
+export * from "./policy.ts";
+export * from "./sensitivity.ts";
+export * from "./semantic-packet.ts";
+export * from "./retention.ts";
+export * from "./storage.ts";
+export * from "./types.ts";
+export * from "./updater.ts";

package/src/evolution/evidence/session-memory/paths.ts

@@ -0,0 +1,29 @@
+import { join } from "node:path";
+import { resolveEvoDevPaths } from "../../../config/paths.ts";
+import { sanitizeStorageId } from "../../../utils/index.ts";
+import type { SessionMemoryPaths } from "./types.ts";
+
+export function resolveSessionMemoryPaths(input: {
+  homeDir: string;
+  projectKey: string;
+  sessionKey: string;
+}): SessionMemoryPaths {
+  const rootDir = join(resolveEvoDevPaths(input.homeDir).stateDir, "session-memory");
+  const projectKey = sanitizeStorageId(input.projectKey, "project");
+  const sessionKey = sanitizeStorageId(input.sessionKey, "session");
+  const projectDir = join(rootDir, projectKey);
+  const sessionDir = join(projectDir, sessionKey);
+  const segmentsDir = join(sessionDir, "segments");
+  return {
+    rootDir,
+    projectDir,
+    sessionDir,
+    statePath: join(sessionDir, "state.json"),
+    cursorPath: join(sessionDir, "cursor.json"),
+    eventsPath: join(sessionDir, "events.jsonl"),
+    segmentsDir,
+    segmentPath: (segmentId: string) =>
+      join(segmentsDir, `${sanitizeStorageId(segmentId, "segment")}.json`),
+    indexPath: join(sessionDir, "index.json"),
+  };
+}

package/src/evolution/evidence/session-memory/policy.ts

@@ -0,0 +1,39 @@
+import { optionalBoolean, positiveInteger } from "../../../utils/index.ts";
+import type { SessionMemoryPolicySnapshot } from "./types.ts";
+
+export function createDefaultSessionMemoryPolicy(): SessionMemoryPolicySnapshot {
+  return {
+    enabled: true,
+    storeRawSegments: true,
+    maxRawSegmentBytes: 200_000,
+    retentionDays: 30,
+    minimumMessageTokensToInit: 10_000,
+    minimumTokensBetweenUpdate: 5_000,
+    toolCallsBetweenUpdates: 9,
+  };
+}
+
+export function parseSessionMemoryPolicy(
+  value: Partial<SessionMemoryPolicySnapshot> | undefined,
+): SessionMemoryPolicySnapshot {
+  const defaults = createDefaultSessionMemoryPolicy();
+  if (value === undefined) return defaults;
+  return {
+    enabled: optionalBoolean(value.enabled, defaults.enabled),
+    storeRawSegments: optionalBoolean(value.storeRawSegments, defaults.storeRawSegments),
+    maxRawSegmentBytes: positiveInteger(value.maxRawSegmentBytes, defaults.maxRawSegmentBytes),
+    retentionDays: positiveInteger(value.retentionDays, defaults.retentionDays),
+    minimumMessageTokensToInit: positiveInteger(
+      value.minimumMessageTokensToInit,
+      defaults.minimumMessageTokensToInit,
+    ),
+    minimumTokensBetweenUpdate: positiveInteger(
+      value.minimumTokensBetweenUpdate,
+      defaults.minimumTokensBetweenUpdate,
+    ),
+    toolCallsBetweenUpdates: positiveInteger(
+      value.toolCallsBetweenUpdates,
+      defaults.toolCallsBetweenUpdates,
+    ),
+  };
+}