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

package/src/code-agent-traces/index.ts

@@ -0,0 +1,520 @@
+import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, normalize, relative } from "node:path";
+import { resolveEvoDevPaths } from "../config/paths.ts";
+import { resolveProjectWorkspaceFromCwd } from "../projects/index.ts";
+import { resolveTraceSessionKey, resolveTraceTeamContext } from "../runtime-logs/index.ts";
+import { normalizeTimestamp, sha256Short } from "../utils/index.ts";
+
+export type CodeAgentTraceTarget = "claude" | "codex";
+export type CodeAgentTraceRefSource =
+  | "hook-payload"
+  | "environment"
+  | "adapter-discovery"
+  | "manual";
+
+export interface CodeAgentTraceRefV1 {
+  version: 1;
+  id: string;
+  target: CodeAgentTraceTarget;
+  sessionKey: string;
+  nativeSessionIdHash: string | null;
+  projectKey: string | null;
+  runId: string | null;
+  roleId: string | null;
+  cwdHash: string | null;
+  discoveredAt: string;
+  source: CodeAgentTraceRefSource;
+  tracePath: string | null;
+  tracePathExistsAtDiscovery: boolean | null;
+  tracePathTrusted: boolean;
+  contentStoredByEvoDev: false;
+  contentReadableByDefault: false;
+  notes: string[];
+}
+
+export interface CodeAgentTraceRefPaths {
+  rootDir: string;
+  claudeDir: string;
+  codexDir: string;
+}
+
+export interface CreateCodeAgentTraceRefInput {
+  target: CodeAgentTraceTarget;
+  sessionKey: string;
+  nativeSessionId?: string | null;
+  nativeSessionIdHash?: string | null;
+  projectKey?: string | null;
+  runId?: string | null;
+  roleId?: string | null;
+  cwd?: string | null;
+  cwdHash?: string | null;
+  discoveredAt?: Date | string;
+  source: CodeAgentTraceRefSource;
+  tracePath?: string | null;
+  tracePathExistsAtDiscovery?: boolean | null;
+  tracePathTrusted?: boolean;
+  notes?: string[];
+}
+
+export interface CodeAgentTraceRefRecord {
+  ref: CodeAgentTraceRefV1;
+  path: string;
+}
+
+export interface CodeAgentTraceRefListInput {
+  homeDir: string;
+  target?: CodeAgentTraceTarget;
+  projectKey?: string;
+  runId?: string;
+  roleId?: string;
+}
+
+export interface RecordCodeAgentTraceRefFromHookInput {
+  homeDir: string;
+  target: CodeAgentTraceTarget;
+  payload: Record<string, unknown>;
+  environment?: Record<string, string | undefined>;
+  now?: Date | string;
+}
+
+const CODE_AGENT_TRACE_TARGETS = ["claude", "codex"] as const;
+const CODE_AGENT_TRACE_REF_SOURCES = [
+  "hook-payload",
+  "environment",
+  "adapter-discovery",
+  "manual",
+] as const;
+const SENSITIVE_IDENTIFIER_PATTERN =
+  /https?:\/\/\S+|(^|[^a-z0-9])(secret|token|password|passwd|private|internal|api[_-]?key|apikey|credential|credentials|stdout|stderr|transcript|formattedresponse|additionalcontext)([^a-z0-9]|$)|raw[\s_-]?(payload|prompt|output|source)|source[\s_-]?dump/i;
+const SENSITIVE_PATH_PATTERN =
+  /(^|[/\\._-])(secret|token|password|passwd|api[_-]?key|apikey|credential|credentials)([/\\._-]|$)/i;
+
+export function resolveCodeAgentTraceRefPaths(homeDir: string): CodeAgentTraceRefPaths {
+  const rootDir = join(resolveEvoDevPaths(homeDir).stateDir, "code-agent-traces");
+  return {
+    rootDir,
+    claudeDir: join(rootDir, "claude"),
+    codexDir: join(rootDir, "codex"),
+  };
+}
+
+export function createCodeAgentTraceRef(input: CreateCodeAgentTraceRefInput): CodeAgentTraceRefV1 {
+  const sessionKey = sanitizePersistentIdentifier(input.sessionKey, "session");
+  const nativeSessionId = input.nativeSessionId ?? null;
+  const nativeSessionIdHash =
+    input.nativeSessionIdHash === undefined
+      ? hashOptionalIdentifier(nativeSessionId)
+      : sanitizeHashMetadata(input.nativeSessionIdHash);
+  const cwdHash =
+    input.cwdHash === undefined
+      ? hashOptionalIdentifier(input.cwd ?? null)
+      : sanitizeHashMetadata(input.cwdHash);
+  const notes = [...(input.notes ?? [])];
+  const normalizedTracePath = normalizeTracePathForStorage(input.tracePath ?? null, notes, {
+    nativeSessionId,
+    nativeSessionIdHash,
+  });
+
+  return {
+    version: 1,
+    id: `trace-ref-${input.target}-${sessionKey}`,
+    target: input.target,
+    sessionKey,
+    nativeSessionIdHash,
+    projectKey:
+      input.projectKey === undefined || input.projectKey === null
+        ? null
+        : sanitizePersistentIdentifier(input.projectKey, "project"),
+    runId:
+      input.runId === undefined || input.runId === null
+        ? null
+        : sanitizePersistentIdentifier(input.runId, "run"),
+    roleId:
+      input.roleId === undefined || input.roleId === null
+        ? null
+        : sanitizePersistentIdentifier(input.roleId, "role"),
+    cwdHash,
+    discoveredAt: normalizeTimestamp(input.discoveredAt),
+    source: input.source,
+    tracePath: normalizedTracePath,
+    tracePathExistsAtDiscovery:
+      normalizedTracePath === null ? null : (input.tracePathExistsAtDiscovery ?? null),
+    tracePathTrusted: normalizedTracePath === null ? false : (input.tracePathTrusted ?? false),
+    contentStoredByEvoDev: false,
+    contentReadableByDefault: false,
+    notes: sanitizeNotes(notes),
+  };
+}
+
+export function parseCodeAgentTraceRef(value: unknown): CodeAgentTraceRefV1 {
+  if (!isRecord(value)) throw new Error("Code Agent trace ref must be an object.");
+  if (value.version !== 1) throw new Error("Code Agent trace ref version must be 1.");
+  assertString("id", value.id);
+  assertEnum("target", value.target, CODE_AGENT_TRACE_TARGETS);
+  assertString("sessionKey", value.sessionKey);
+  assertNullableString("nativeSessionIdHash", value.nativeSessionIdHash);
+  assertNullableString("projectKey", value.projectKey);
+  assertNullableString("runId", value.runId);
+  assertNullableString("roleId", value.roleId);
+  assertNullableString("cwdHash", value.cwdHash);
+  assertString("discoveredAt", value.discoveredAt);
+  assertEnum("source", value.source, CODE_AGENT_TRACE_REF_SOURCES);
+  assertNullableString("tracePath", value.tracePath);
+  if (
+    value.tracePathExistsAtDiscovery !== null &&
+    typeof value.tracePathExistsAtDiscovery !== "boolean"
+  ) {
+    throw new Error("tracePathExistsAtDiscovery must be boolean or null.");
+  }
+  if (typeof value.tracePathTrusted !== "boolean") {
+    throw new Error("tracePathTrusted must be boolean.");
+  }
+  if (value.contentStoredByEvoDev !== false) {
+    throw new Error("contentStoredByEvoDev must be false.");
+  }
+  if (value.contentReadableByDefault !== false) {
+    throw new Error("contentReadableByDefault must be false.");
+  }
+  if (!Array.isArray(value.notes) || !value.notes.every((note) => typeof note === "string")) {
+    throw new Error("notes must be a string array.");
+  }
+
+  return value as unknown as CodeAgentTraceRefV1;
+}
+
+export async function writeCodeAgentTraceRef(input: {
+  homeDir: string;
+  ref: CodeAgentTraceRefV1;
+}): Promise<CodeAgentTraceRefRecord> {
+  const ref = sanitizeCodeAgentTraceRefForWrite(parseCodeAgentTraceRef(input.ref));
+  const path = resolveCodeAgentTraceRefPath({
+    homeDir: input.homeDir,
+    target: ref.target,
+    sessionKey: ref.sessionKey,
+  });
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(ref, null, 2)}\n`, "utf8");
+  return { ref, path };
+}
+
+export async function readCodeAgentTraceRef(input: {
+  homeDir: string;
+  id: string;
+}): Promise<CodeAgentTraceRefRecord> {
+  const targetAndSession = parseTraceRefId(input.id);
+  const path = resolveCodeAgentTraceRefPath({
+    homeDir: input.homeDir,
+    target: targetAndSession.target,
+    sessionKey: targetAndSession.sessionKey,
+  });
+  const ref = sanitizeCodeAgentTraceRefForWrite(
+    parseCodeAgentTraceRef(JSON.parse(await readFile(path, "utf8"))),
+  );
+  if (ref.id !== input.id) throw new Error(`Code Agent trace ref id mismatch: ${input.id}`);
+  return { ref, path };
+}
+
+export async function listCodeAgentTraceRefs(
+  input: CodeAgentTraceRefListInput,
+): Promise<CodeAgentTraceRefRecord[]> {
+  const targets = input.target === undefined ? [...CODE_AGENT_TRACE_TARGETS] : [input.target];
+  const records: CodeAgentTraceRefRecord[] = [];
+  for (const target of targets) {
+    const dir = resolveCodeAgentTraceRefTargetDir(input.homeDir, target);
+    const entries = await readDirectoryEntries(dir);
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+      const path = join(dir, entry.name);
+      const ref = sanitizeCodeAgentTraceRefForWrite(
+        parseCodeAgentTraceRef(JSON.parse(await readFile(path, "utf8"))),
+      );
+      if (input.projectKey !== undefined && ref.projectKey !== input.projectKey) continue;
+      if (input.runId !== undefined && ref.runId !== input.runId) continue;
+      if (input.roleId !== undefined && ref.roleId !== input.roleId) continue;
+      records.push({ ref, path });
+    }
+  }
+  return records.sort((left, right) => left.ref.id.localeCompare(right.ref.id));
+}
+
+export async function recordCodeAgentTraceRefFromHook(
+  input: RecordCodeAgentTraceRefFromHookInput,
+): Promise<CodeAgentTraceRefRecord | null> {
+  const environment = input.environment ?? {};
+  const sessionIdFromPayload = optionalString(input.payload.session_id ?? input.payload.sessionId);
+  const sessionIdFromEnvironment = optionalString(environment.EVODEV_CODE_AGENT_SESSION_ID);
+  const tracePathFromPayload = readPayloadTracePath(input.payload);
+  const tracePathFromEnvironment = optionalString(environment.EVODEV_CODE_AGENT_TRACE_PATH);
+  const nativeSessionId = sessionIdFromPayload ?? sessionIdFromEnvironment;
+  const tracePathInput = tracePathFromPayload ?? tracePathFromEnvironment;
+  if (nativeSessionId === null && tracePathInput === null) return null;
+
+  const notes: string[] = [];
+  const normalizedPath = normalizeTracePathForInspection(tracePathInput, notes);
+  const pathStatus =
+    normalizedPath === null
+      ? { exists: null, trusted: false, notes: [] }
+      : await inspectTracePath({
+          homeDir: input.homeDir,
+          target: input.target,
+          tracePath: normalizedPath,
+        });
+  notes.push(...pathStatus.notes);
+  const team = resolveTraceTeamContext({
+    homeDir: input.homeDir,
+    payload: input.payload,
+    environment,
+  });
+  const cwd = optionalString(input.payload.cwd);
+  const workspace =
+    team === null && cwd !== null
+      ? await resolveProjectWorkspaceFromCwd({ homeDir: input.homeDir, cwd })
+      : null;
+  const source =
+    sessionIdFromPayload !== null || tracePathFromPayload !== null ? "hook-payload" : "environment";
+
+  const ref = createCodeAgentTraceRef({
+    target: input.target,
+    sessionKey: resolveTraceSessionKey(input.payload),
+    nativeSessionId,
+    projectKey: team?.projectKey ?? workspace?.projectKey ?? null,
+    runId: team?.runId ?? null,
+    roleId: team?.roleId ?? null,
+    cwd,
+    discoveredAt: input.now,
+    source,
+    tracePath: normalizedPath,
+    tracePathExistsAtDiscovery: pathStatus.exists,
+    tracePathTrusted: pathStatus.trusted,
+    notes,
+  });
+  return await writeCodeAgentTraceRef({ homeDir: input.homeDir, ref });
+}
+
+function sanitizeCodeAgentTraceRefForWrite(ref: CodeAgentTraceRefV1): CodeAgentTraceRefV1 {
+  return createCodeAgentTraceRef({
+    target: ref.target,
+    sessionKey: ref.sessionKey,
+    nativeSessionIdHash: sanitizeHashMetadata(ref.nativeSessionIdHash),
+    projectKey: ref.projectKey,
+    runId: ref.runId,
+    roleId: ref.roleId,
+    cwdHash: sanitizeHashMetadata(ref.cwdHash),
+    discoveredAt: ref.discoveredAt,
+    source: ref.source,
+    tracePath: ref.tracePath,
+    tracePathExistsAtDiscovery: ref.tracePathExistsAtDiscovery,
+    tracePathTrusted: ref.tracePathTrusted,
+    notes: ref.notes,
+  });
+}
+
+function resolveCodeAgentTraceRefPath(input: {
+  homeDir: string;
+  target: CodeAgentTraceTarget;
+  sessionKey: string;
+}): string {
+  return join(
+    resolveCodeAgentTraceRefTargetDir(input.homeDir, input.target),
+    `${sanitizePersistentIdentifier(input.sessionKey, "session")}.json`,
+  );
+}
+
+function resolveCodeAgentTraceRefTargetDir(homeDir: string, target: CodeAgentTraceTarget): string {
+  const paths = resolveCodeAgentTraceRefPaths(homeDir);
+  return target === "claude" ? paths.claudeDir : paths.codexDir;
+}
+
+function parseTraceRefId(id: string): { target: CodeAgentTraceTarget; sessionKey: string } {
+  const match = id.match(/^trace-ref-(claude|codex)-(.+)$/);
+  if (match === null) throw new Error(`Invalid Code Agent trace ref id: ${id}`);
+  return {
+    target: match[1] as CodeAgentTraceTarget,
+    sessionKey: sanitizePersistentIdentifier(match[2] ?? "", "session"),
+  };
+}
+
+async function readDirectoryEntries(dir: string) {
+  try {
+    return await readdir(dir, { withFileTypes: true });
+  } catch (error) {
+    if (isNotFoundError(error)) return [];
+    throw error;
+  }
+}
+
+function readPayloadTracePath(payload: Record<string, unknown>): string | null {
+  return (
+    optionalString(payload.transcript_path) ??
+    optionalString(payload.transcriptPath) ??
+    optionalString(payload.trace_path) ??
+    optionalString(payload.tracePath) ??
+    optionalString(payload.session_path) ??
+    optionalString(payload.sessionPath)
+  );
+}
+
+function normalizeTracePathForStorage(
+  value: string | null,
+  notes: string[],
+  redaction: { nativeSessionId: string | null; nativeSessionIdHash: string | null },
+): string | null {
+  const normalized = normalizeTracePathForInspection(value, notes);
+  return normalized === null ? null : redactTracePathForStorage(normalized, notes, redaction);
+}
+
+function normalizeTracePathForInspection(value: string | null, notes: string[]): string | null {
+  if (value === null || value.trim() === "") return null;
+  const trimmed = value.trim();
+  if (/[\0\r\n]/.test(trimmed)) {
+    notes.push("trace path omitted: unsafe control characters");
+    return null;
+  }
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed)) {
+    notes.push("trace path omitted: URLs are not stored");
+    return null;
+  }
+  if (!isAbsolute(trimmed)) {
+    notes.push("trace path omitted: relative paths are not trusted");
+    return null;
+  }
+  if (hasRawTraversalSegment(trimmed)) {
+    notes.push("trace path omitted: traversal segments are not trusted");
+    return null;
+  }
+  if (SENSITIVE_PATH_PATTERN.test(trimmed)) {
+    notes.push("trace path omitted: sensitive-looking path segment");
+    return null;
+  }
+  return normalize(trimmed);
+}
+
+function redactTracePathForStorage(
+  path: string,
+  notes: string[],
+  redaction: { nativeSessionId: string | null; nativeSessionIdHash: string | null },
+): string {
+  if (redaction.nativeSessionId === null || redaction.nativeSessionId.trim() === "") return path;
+  if (!path.includes(redaction.nativeSessionId)) return path;
+  notes.push("trace-path-redacted-native-session-id");
+  return path
+    .split(redaction.nativeSessionId)
+    .join(redaction.nativeSessionIdHash ?? "native-session-id-redacted");
+}
+
+async function inspectTracePath(input: {
+  homeDir: string;
+  target: CodeAgentTraceTarget;
+  tracePath: string;
+}): Promise<{ exists: boolean | null; trusted: boolean; notes: string[] }> {
+  const notes: string[] = [];
+  let exists: boolean | null = null;
+  try {
+    await stat(input.tracePath);
+    exists = true;
+  } catch (error) {
+    if (isNotFoundError(error)) {
+      exists = false;
+      notes.push("trace path was not present at discovery");
+    } else {
+      exists = null;
+      notes.push("trace path existence could not be checked");
+    }
+  }
+
+  const trusted = exists === true && isDescendant(resolveTargetUserDir(input), input.tracePath);
+  if (exists === true && !trusted) {
+    notes.push("trace path exists outside the target user-level directory");
+  }
+  return { exists, trusted, notes };
+}
+
+function resolveTargetUserDir(input: { homeDir: string; target: CodeAgentTraceTarget }): string {
+  return normalize(
+    join(stripTrailingSlash(input.homeDir), input.target === "claude" ? ".claude" : ".codex"),
+  );
+}
+
+function isDescendant(parent: string, child: string): boolean {
+  const relation = relative(normalize(parent), normalize(child));
+  return relation === "" || (!relation.startsWith("..") && !isAbsolute(relation));
+}
+
+function hasRawTraversalSegment(path: string): boolean {
+  return path.split(/[/\\]+/).some((part) => part === "..");
+}
+
+function hashOptionalIdentifier(value: string | null): string | null {
+  if (value === null || value.trim() === "") return null;
+  return `sha256-${sha256Short(value)}`;
+}
+
+function sanitizeHashMetadata(value: string | null): string | null {
+  if (value === null || value.trim() === "") return null;
+  if (/^sha256-[a-f0-9]{16}$/i.test(value)) return value;
+  return hashOptionalIdentifier(value);
+}
+
+function sanitizePersistentIdentifier(value: string, prefix: string): string {
+  const pathSafe = value.replace(/[^a-zA-Z0-9._-]/g, "-").slice(0, 120) || `${prefix}-local`;
+  if (!SENSITIVE_IDENTIFIER_PATTERN.test(value) && !SENSITIVE_IDENTIFIER_PATTERN.test(pathSafe)) {
+    return pathSafe;
+  }
+  return `${prefix}-${sha256Short(value)}`;
+}
+
+function sanitizeNotes(notes: string[]): string[] {
+  return notes
+    .filter((note) => note.trim() !== "")
+    .slice(0, 20)
+    .map((note) => sanitizeNote(note));
+}
+
+function sanitizeNote(note: string): string {
+  const truncated = note.trim().slice(0, 240);
+  if (SENSITIVE_IDENTIFIER_PATTERN.test(truncated)) return "trace ref note redacted";
+  return truncated;
+}
+
+function optionalString(value: unknown): string | null {
+  return typeof value === "string" && value.trim() !== "" ? value : null;
+}
+
+function assertString(label: string, value: unknown): asserts value is string {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`${label} must be a non-empty string.`);
+  }
+}
+
+function assertNullableString(label: string, value: unknown): asserts value is string | null {
+  if (value !== null && typeof value !== "string") {
+    throw new Error(`${label} must be a string or null.`);
+  }
+}
+
+function assertEnum<T extends readonly string[]>(
+  label: string,
+  value: unknown,
+  allowed: T,
+): asserts value is T[number] {
+  if (typeof value !== "string" || !allowed.includes(value)) {
+    throw new Error(`${label} is invalid.`);
+  }
+}
+
+function stripTrailingSlash(path: string): string {
+  if (path === "/") return path;
+  return path.replace(/[/\\]+$/, "");
+}
+
+function isNotFoundError(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    (("code" in error && (error as NodeJS.ErrnoException).code === "ENOENT") ||
+      error.message.includes("ENOENT"))
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/config/index.ts

@@ -8,13 +8,18 @@ export {
 } from "./registry.ts";
 export {
   type EvoDevSettings,
+  type EvolutionSettings,
+  type MemorySettings,
   type PluginSettings,
   type SettingsInput,
   type TeamRuntimeSettings,
+  createDefaultMemorySettings,
+  createDefaultEvolutionSettings,
   createDefaultTeamRuntimeSettings,
   createDefaultSettings,
   mergeSettings,
   parseSettings,
+  readRuntimeInjectionSettings,
 } from "./settings.ts";
 export {
   type InstallState,

package/src/config/paths.ts

@@ -29,7 +29,7 @@ export function resolveEvoDevPaths(homeDir: string = getHomeDir()): EvoDevPaths
   const evosDir = `${rootDir}/evos`;
   const roleAgentsDir = `${rootDir}/agents/roles`;
   const teamsDir = `${rootDir}/teams`;
-  const runsDir = `${rootDir}/runs`;
+  const runsDir = `${teamsDir}/runs`;
 
   return {
     homeDir: normalizedHome,