@evo-dev/core 0.0.1-alpha.1 → 0.0.1-alpha.11

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

@@ -0,0 +1,281 @@
+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-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 === "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 === "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"
+  ) {
+    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,7 @@
+export * from "./analysis.ts";
+export * from "./paths.ts";
+export * from "./policy.ts";
+export * from "./sensitivity.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,
+    ),
+  };
+}

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

@@ -0,0 +1,202 @@
+import {
+  createStableId,
+  sanitizeStorageId,
+  sanitizeSummary,
+  sha256Hex,
+  truncateUtf8Tail,
+} from "../../../utils/index.ts";
+import { DEFAULT_MAX_RAW_EVENT_BYTES, VERIFICATION_PATTERN } from "./constants.ts";
+import {
+  detectSessionMemorySensitivity,
+  redactSessionMemoryCredentialText,
+  redactSessionMemoryCredentials,
+} from "./sensitivity.ts";
+import { readLineRange } from "./storage.ts";
+import type {
+  SessionEvidenceSegmentV1,
+  SessionMemoryCursorV1,
+  SessionMemoryPaths,
+  SessionMemoryRawEventV1,
+  SessionMemorySegmentReason,
+  SessionMemorySignal,
+  SessionMemorySignalStrength,
+  SessionMemoryStateV1,
+  UpdateSessionMemoryInput,
+} from "./types.ts";
+
+export function createRawEvent(
+  input: UpdateSessionMemoryInput,
+  now: string,
+): SessionMemoryRawEventV1 {
+  const originalRawJson = stringifyPayload(input.rawPayload);
+  const redactedPayload = redactSessionMemoryCredentials(input.rawPayload);
+  const redactedSummary = redactSessionMemoryCredentialText(input.event.payload.summary);
+  const rawJson = stringifyPayload(redactedPayload.value);
+  const truncated = truncateUtf8Tail(rawJson, DEFAULT_MAX_RAW_EVENT_BYTES);
+  const sensitivity = detectSessionMemorySensitivity(redactedPayload.value);
+  return {
+    schemaVersion: 1,
+    kind: "session-memory-raw-event",
+    eventId: input.event.eventId,
+    eventType: input.event.type,
+    occurredAt: input.event.time.occurredAt,
+    receivedAt: now,
+    summary: sanitizeSummary(redactedSummary.value),
+    rawPayloadJson: truncated.content,
+    rawPayloadByteLength: Buffer.byteLength(originalRawJson, "utf8"),
+    rawPayloadTruncated: truncated.truncated,
+    secretsDetected: sensitivity.classification === "credential",
+    sensitivity: sensitivity.classification,
+    sensitivityReasons: sensitivity.reasons,
+    credentialRedactionApplied: redactedPayload.redacted || redactedSummary.redacted,
+  };
+}
+
+export function createSignal(
+  input: UpdateSessionMemoryInput,
+  rawEvent: SessionMemoryRawEventV1,
+  rawEventLine: number,
+): SessionMemorySignal {
+  return {
+    eventId: input.event.eventId,
+    eventType: input.event.type,
+    reason: "observed",
+    strength: "normal",
+    occurredAt: input.event.time.occurredAt,
+    summary: rawEvent.summary,
+    rawEventLine,
+  };
+}
+
+export async function createSegment(input: {
+  paths: SessionMemoryPaths;
+  state: SessionMemoryStateV1;
+  cursor: SessionMemoryCursorV1;
+  reason: SessionMemorySegmentReason;
+  strength: SessionMemorySignalStrength;
+  signals: SessionMemorySignal[];
+  currentLine: number;
+  now: string;
+}): Promise<SessionEvidenceSegmentV1> {
+  const fromLine = (input.cursor.lastCapturedLine ?? 0) + 1;
+  const toLine = input.currentLine;
+  const raw = await readLineRange(input.paths.eventsPath, fromLine, toLine);
+  const truncated = truncateUtf8Tail(raw.content, input.state.policy.maxRawSegmentBytes);
+  const signalSummaries = input.signals.map((signal) => signal.summary).filter(Boolean);
+  const failures = input.signals
+    .filter((signal) => signal.reason === "failure-signal")
+    .map((signal) => signal.summary);
+  const verifications = input.signals
+    .filter(
+      (signal) =>
+        signal.reason === "verification-after-fix" || VERIFICATION_PATTERN.test(signal.summary),
+    )
+    .map((signal) => signal.summary);
+  const segmentId = createStableId("segment", [
+    input.state.projectKey,
+    input.state.sessionKey,
+    input.reason,
+    String(fromLine),
+    String(toLine),
+    input.signals.at(-1)?.eventId ?? input.now,
+  ]);
+  return {
+    schemaVersion: 1,
+    kind: "session-evidence-segment",
+    id: segmentId,
+    projectKey: input.state.projectKey,
+    runId: input.state.runId,
+    roleId: input.state.roleId,
+    sessionKey: input.state.sessionKey,
+    target: input.state.target,
+    createdAt: input.now,
+    reason: input.reason,
+    strength: input.strength,
+    source: {
+      traceRefId: input.cursor.traceRefId,
+      sourcePath: input.paths.eventsPath,
+      fromOffset: null,
+      toOffset: null,
+      fromLine,
+      toLine,
+      fromEventId: input.signals[0]?.eventId ?? null,
+      toEventId: input.signals.at(-1)?.eventId ?? null,
+    },
+    signals: input.signals,
+    rawExcerpt: {
+      stored: true,
+      encoding: "utf8",
+      content: truncated.content,
+      truncated: raw.truncated || truncated.truncated,
+      byteLength: Buffer.byteLength(truncated.content, "utf8"),
+      sha256: sha256Hex(truncated.content),
+    },
+    normalized: {
+      summary: createSegmentSummary(input.reason, input.strength, signalSummaries),
+      userIntent: firstUserPromptSummary(input.signals),
+      intentDelta: intentDeltaSummary(input.signals),
+      decisions: [],
+      failures,
+      verifications,
+      touchedTools: collectTouchedTools(raw.content),
+    },
+    privacy: {
+      localOnly: true,
+      rawPromptStored: input.signals.some((signal) => signal.eventType === "UserPromptSubmit"),
+      rawOutputStored: input.signals.some((signal) =>
+        ["PostToolUse", "PostToolUseFailure", "PostToolBatch"].includes(signal.eventType),
+      ),
+      sourceContentStored: true,
+      secretsDetected: raw.secretsDetected,
+      sensitivity: raw.sensitivity,
+      sensitivityReasons: raw.sensitivityReasons,
+      redactionApplied: raw.redactionApplied,
+      externalUploadAllowed: false,
+    },
+    lifecycle: {
+      status: "captured",
+      reviewState: "not-required",
+      consumedByBatchIds: [],
+    },
+  };
+}
+
+export function estimateTokenCount(rawPayloadJson: string, summary: string): number {
+  return Math.max(1, Math.ceil((rawPayloadJson.length + summary.length) / 4));
+}
+
+function createSegmentSummary(
+  reason: SessionMemorySegmentReason,
+  strength: SessionMemorySignalStrength,
+  summaries: string[],
+): string {
+  const suffix = summaries.length === 0 ? "No event summary." : summaries.slice(-3).join(" / ");
+  return sanitizeSummary(`Session segment ${reason} (${strength}): ${suffix}`);
+}
+
+function firstUserPromptSummary(signals: SessionMemorySignal[]): string | null {
+  return signals.find((signal) => signal.eventType === "UserPromptSubmit")?.summary ?? null;
+}
+
+function intentDeltaSummary(signals: SessionMemorySignal[]): string | null {
+  const prompts = signals.filter((signal) => signal.eventType === "UserPromptSubmit");
+  if (prompts.length < 2) return null;
+  return prompts.at(-1)?.summary ?? null;
+}
+
+function collectTouchedTools(rawContent: string): string[] {
+  const tools = new Set<string>();
+  for (const match of rawContent.matchAll(/"tool(?:Name|_name)"\s*:\s*"([^"]+)"/g)) {
+    const tool = match[1]?.trim();
+    if (tool !== undefined && tool !== "") tools.add(sanitizeStorageId(tool, "tool"));
+  }
+  return [...tools].slice(0, 20);
+}
+
+function stringifyPayload(payload: Record<string, unknown>): string {
+  try {
+    return JSON.stringify(payload);
+  } catch {
+    return JSON.stringify({ unserializable: true });
+  }
+}