trajectories 0.0.0 → 0.1.1

package/legacy/src/parentage.ts

@@ -0,0 +1,562 @@
+import { closeSync, existsSync, fstatSync, openSync, readFileSync, readSync } from "node:fs";
+import { basename, dirname, isAbsolute, join } from "node:path";
+import { withReadOnlyDb } from "./native/sqlite-ro.js";
+import { readKimiSubagentMeta } from "./native/kimi.js";
+
+export interface SessionParentage {
+  parent_session_id: string | null;
+  parent_tool_use_id: string | null;
+  agent_nickname: string | null;
+  thread_role: string | null;
+}
+
+export const EMPTY_SESSION_PARENTAGE: SessionParentage = {
+  parent_session_id: null,
+  parent_tool_use_id: null,
+  agent_nickname: null,
+  thread_role: null,
+};
+
+export interface ParentageOptions {
+  sessionId?: string;
+  transcript?: string;
+  /**
+   * A parent edge a source's own registry recorded elsewhere, read at scan time
+   * (Grok registers a child under the parent's directory, so a per-session read
+   * cannot find it without walking the store).
+   */
+  registryParentSessionId?: string;
+  /**
+   * The tool call that spawned a child session, read from the parent's own
+   * transcript at scan time (Kimi's parent wire binds `parent_tool_call_id` to
+   * the spawned agent, and nothing on the child names it).
+   */
+  registryParentToolUseId?: string;
+  onDiagnostic?: (diagnostic: ParentageDiagnostic) => void;
+}
+
+export interface ParentageDiagnostic {
+  code: "invalid_metadata" | "read_error" | "unresolved_reference" | "conflicting_evidence" | "incomplete_evidence";
+  sourcePath: string;
+  message: string;
+}
+
+class ParentageError extends Error {
+  constructor(readonly code: ParentageDiagnostic["code"], message: string, readonly sourcePath = "") {
+    super(message);
+  }
+}
+
+function reportError(options: ParentageOptions, sourcePath: string, error: unknown): void {
+  options.onDiagnostic?.({
+    code: error instanceof ParentageError ? error.code : "read_error",
+    sourcePath: error instanceof ParentageError && error.sourcePath ? error.sourcePath : sourcePath,
+    message: error instanceof ParentageError ? error.message : "Could not read source parentage evidence.",
+  });
+}
+
+const FILE_PREFIX_BYTES = 64 * 1024;
+const META_SCAN_LINES = 40;
+
+/**
+ * Source-proved session parentage stored beside Trajectory records.
+ *
+ * `@letta-ai/trajectory` CanonicalRecord has no parent/subagent fields
+ * (`source_group_id` is this transcript's own id). Ledger keeps using
+ * Trajectory as the record SoT and folds the edge here.
+ *
+ * Proven shapes (independently implemented; do not copy AGPL Obelisk):
+ * - Codex `session_meta` (`parent_thread_id` / spawn / nickname)
+ * - Claude Code `<parent>/subagents/` path, sidechain `sessionId`, `.meta.json`
+ * - Pi / OpenClaw `branchedFrom` / `parentSession` session header
+ * - OMP nested `<parent>.jsonl` + `<parent>/<child>.jsonl` sibling header
+ * - Hermes `sessions.parent_session_id`
+ * - OpenCode session JSON `parentID` / SQLite `session.parent_id`
+ * - Cursor `.../<parent>/subagents/` path when that layout exists
+ * - Grok `<parent>/subagents/<child>/meta.json` registry, read at scan time
+ * - Kimi `<parent-session>/subagents/<agent>/` path, with the spawning tool
+ *   call and `subagent_type` from the parent's wire and the child's `meta.json`
+ */
+export function extractSessionParentage(
+  source: string,
+  sourcePath: string,
+  options: ParentageOptions = {},
+): SessionParentage {
+  try {
+    switch (source) {
+      case "codex":
+        return readCodexParentage(
+          options.transcript ?? readFilePrefix(sourcePath),
+        );
+      case "claude-code":
+        return extractClaudeCodeParentage(
+          sourcePath,
+          options.transcript ?? readFilePrefixIfPresent(sourcePath, !parentIdFromSubagentsPath(sourcePath)),
+          options,
+        );
+      case "cursor":
+        return extractPathSubagentParentage(sourcePath);
+      case "grok":
+        return extractGrokParentage(sourcePath, options);
+      case "kimi":
+        return extractKimiParentage(sourcePath, options);
+      case "pi":
+      case "openclaw":
+        return extractPiHeaderParentage(
+          sourcePath,
+          options.transcript ?? readFilePrefixIfPresent(sourcePath),
+        );
+      case "omp":
+        return extractOmpParentage(
+          sourcePath,
+          options.transcript ?? readFilePrefixIfPresent(sourcePath),
+        );
+      case "hermes":
+        return extractHermesParentage(sourcePath, options.sessionId);
+      case "opencode":
+        return extractOpenCodeParentage(sourcePath, options.sessionId, options.transcript);
+      default:
+        return { ...EMPTY_SESSION_PARENTAGE };
+    }
+  } catch (error) {
+    reportError(options, sourcePath, error);
+    return { ...EMPTY_SESSION_PARENTAGE };
+  }
+}
+
+export function extractCodexParentageFromTranscript(
+  transcript: string,
+  options: ParentageOptions = {},
+): SessionParentage {
+  return extractSessionParentage("codex", "", { ...options, transcript });
+}
+
+function readCodexParentage(transcript: string): SessionParentage {
+  const found: SessionParentage = { ...EMPTY_SESSION_PARENTAGE };
+  for (const obj of scanJsonlObjects(transcript, META_SCAN_LINES, "session_meta")) {
+    if (obj.type !== "session_meta") continue;
+    const payload = asRecord(obj.payload);
+    if (!payload) continue;
+    mergeParentage(found, parentageFromCodexMeta(payload));
+    if (found.parent_session_id && found.agent_nickname && found.thread_role) {
+      break;
+    }
+  }
+  return found;
+}
+
+export function mergeParentage(
+  current: SessionParentage,
+  incoming: SessionParentage,
+): SessionParentage {
+  current.parent_session_id = current.parent_session_id ?? incoming.parent_session_id;
+  current.parent_tool_use_id = current.parent_tool_use_id ?? incoming.parent_tool_use_id;
+  current.agent_nickname = current.agent_nickname ?? incoming.agent_nickname;
+  current.thread_role = current.thread_role ?? incoming.thread_role;
+  return current;
+}
+
+export function parentageEquals(a: SessionParentage, b: SessionParentage): boolean {
+  return (
+    a.parent_session_id === b.parent_session_id &&
+    a.parent_tool_use_id === b.parent_tool_use_id &&
+    a.agent_nickname === b.agent_nickname &&
+    a.thread_role === b.thread_role
+  );
+}
+
+function extractPathSubagentParentage(sourcePath: string): SessionParentage {
+  const parent = parentIdFromSubagentsPath(sourcePath);
+  if (!parent) return { ...EMPTY_SESSION_PARENTAGE };
+  return {
+    parent_session_id: parent,
+    parent_tool_use_id: null,
+    agent_nickname: null,
+    thread_role: sourcePath.replace(/\\/g, "/").includes("/subagents/workflows/")
+      ? "workflow_agent"
+      : "subagent",
+  };
+}
+
+/**
+ * Grok's edge is recorded by the parent, not the child: the child's own
+ * directory holds no mention of its parent. The scanner reads the registry
+ * while it walks the store and passes the child's edge here; the path shape is
+ * the second piece of evidence, for a listing rooted inside a parent's
+ * registry directory (`<parent>/subagents/<child>/updates.jsonl`). A session is
+ * never its own parent.
+ */
+function extractGrokParentage(sourcePath: string, options: ParentageOptions): SessionParentage {
+  const parent = asNonEmptyString(options.registryParentSessionId) ?? parentIdFromSubagentsPath(sourcePath);
+  if (!parent) return { ...EMPTY_SESSION_PARENTAGE };
+  const child = asNonEmptyString(options.sessionId) ?? asNonEmptyString(basename(dirname(sourcePath)));
+  if (child === parent) return { ...EMPTY_SESSION_PARENTAGE };
+  return {
+    parent_session_id: parent,
+    parent_tool_use_id: null,
+    agent_nickname: null,
+    thread_role: "subagent",
+  };
+}
+
+/**
+ * Kimi's edge is the filesystem shape plus the parent's own wire: a child
+ * transcript is `<parent-session>/subagents/<agent-id>/wire.jsonl`, so the
+ * enclosing session directory names the parent, and the child's `meta.json`
+ * carries the `subagent_type` the parent launched it as. The tool call that
+ * spawned the child is not written on the child at all — the parent's wire
+ * binds `parent_tool_call_id` → `agent_id` — so it arrives from the scan
+ * (`options.registryParentToolUseId`) when the binding was readable. A session
+ * is never its own parent.
+ */
+function extractKimiParentage(sourcePath: string, options: ParentageOptions): SessionParentage {
+  const parent = parentIdFromSubagentsPath(sourcePath);
+  if (!parent) return { ...EMPTY_SESSION_PARENTAGE };
+  const agentId = asNonEmptyString(basename(dirname(sourcePath)));
+  if (!agentId || agentId === parent) return { ...EMPTY_SESSION_PARENTAGE };
+  const child = asNonEmptyString(options.sessionId);
+  if (child === parent) return { ...EMPTY_SESSION_PARENTAGE };
+  return {
+    parent_session_id: parent,
+    parent_tool_use_id: asNonEmptyString(options.registryParentToolUseId),
+    agent_nickname: readKimiSubagentMeta(dirname(sourcePath)).agentType ?? null,
+    thread_role: "subagent",
+  };
+}
+
+function extractClaudeCodeParentage(
+  sourcePath: string,
+  transcript: string | null,
+  options: ParentageOptions,
+): SessionParentage {
+  const found = transcript ? parentageFromClaudeTranscript(transcript) : { ...EMPTY_SESSION_PARENTAGE };
+  if (!found) return { ...EMPTY_SESSION_PARENTAGE };
+  const fromPath = extractPathSubagentParentage(sourcePath);
+  if (found.parent_session_id && fromPath.parent_session_id && found.parent_session_id !== fromPath.parent_session_id) {
+    reportError(options, sourcePath, new ParentageError("conflicting_evidence", "Explicit Claude metadata overrides the parent directory."));
+  } else if (fromPath.thread_role === "workflow_agent") {
+    found.thread_role = fromPath.thread_role;
+  }
+  mergeParentage(found, fromPath);
+
+  mergeParentage(found, parentageFromClaudeMetaFile(sourcePath, options));
+
+  if (found.parent_session_id && !found.thread_role) {
+    found.thread_role = "subagent";
+  }
+  return found;
+}
+
+function parentIdFromSubagentsPath(sourcePath: string): string | null {
+  const parts = sourcePath.split(/[/\\]/).filter((part) => part.length > 0);
+  const idx = parts.lastIndexOf("subagents");
+  if (idx <= 0) return null;
+  const parent = asNonEmptyString(parts[idx - 1]);
+  if (!parent || parent === "." || parent === "..") return null;
+  return parent;
+}
+
+function parentageFromClaudeTranscript(transcript: string): SessionParentage | null {
+  const found: SessionParentage = { ...EMPTY_SESSION_PARENTAGE };
+  let childId: string | null = null;
+  // Match Trajectory's standalone-sidechain boundary, not an embedded child row.
+  for (const obj of scanJsonlObjects(transcript, Infinity)) {
+    if ((obj.type !== "user" && obj.type !== "assistant") || !asRecord(obj.message)) continue;
+    if (obj.isSidechain !== true) return null;
+    const agentId = asNonEmptyString(obj.agentId);
+    const sessionId = asNonEmptyString(obj.sessionId);
+    if (!agentId || !sessionId || agentId === sessionId) return { ...EMPTY_SESSION_PARENTAGE };
+    if ((childId && childId !== agentId) ||
+        (found.parent_session_id && found.parent_session_id !== sessionId)) {
+      throw new ParentageError("conflicting_evidence", "Claude sidechain rows disagree about the child or parent identity.");
+    }
+    childId = agentId;
+    found.parent_session_id = sessionId;
+    found.thread_role = "subagent";
+  }
+  return found;
+}
+
+function parentageFromClaudeMetaFile(sourcePath: string, options: ParentageOptions): SessionParentage {
+  if (!sourcePath.toLowerCase().endsWith(".jsonl")) {
+    return { ...EMPTY_SESSION_PARENTAGE };
+  }
+  const metaPath = `${sourcePath.slice(0, -".jsonl".length)}.meta.json`;
+  if (!existsSync(metaPath)) return { ...EMPTY_SESSION_PARENTAGE };
+  try {
+    const meta = asRecord(JSON.parse(readFileSync(metaPath, "utf8")));
+    if (!meta) throw new ParentageError("invalid_metadata", "Claude sidecar must be a JSON object.");
+    return {
+      parent_session_id: null,
+      parent_tool_use_id: asNonEmptyString(meta.toolUseId),
+      agent_nickname: asNonEmptyString(meta.agentType),
+      thread_role: null,
+    };
+  } catch (error) {
+    reportError(options, metaPath, error instanceof SyntaxError
+      ? new ParentageError("invalid_metadata", "Claude sidecar is not valid JSON.") : error);
+    return { ...EMPTY_SESSION_PARENTAGE };
+  }
+}
+
+function extractPiHeaderParentage(
+  sourcePath: string,
+  transcript: string | null,
+): SessionParentage {
+  const header = readPiSessionHeader(transcript ?? readFilePrefixIfPresent(sourcePath));
+  if (!header) return { ...EMPTY_SESSION_PARENTAGE };
+  const parent =
+    resolvePiParentRef(asNonEmptyString(header.branchedFrom), sourcePath);
+  const otherParent = resolvePiParentRef(asNonEmptyString(header.parentSession), sourcePath);
+  if (parent && otherParent && parent !== otherParent) {
+    throw new ParentageError("conflicting_evidence", "Pi header parent references disagree.");
+  }
+  const resolved = parent ?? otherParent;
+  if (resolved === header.id) throw new ParentageError("conflicting_evidence", "A session cannot be its own parent.");
+  if (!resolved) return { ...EMPTY_SESSION_PARENTAGE };
+  return {
+    parent_session_id: resolved,
+    parent_tool_use_id: null,
+    agent_nickname: null,
+    thread_role: "subagent",
+  };
+}
+
+function extractOmpParentage(
+  sourcePath: string,
+  transcript: string | null,
+): SessionParentage {
+  if (!readPiSessionHeader(transcript)) {
+    throw new ParentageError("invalid_metadata", "OMP child has no valid session header.");
+  }
+  const fromHeader = extractPiHeaderParentage(sourcePath, transcript);
+  if (fromHeader.parent_session_id) return fromHeader;
+  const siblingId = readPiSessionIdFromFile(`${dirname(sourcePath)}.jsonl`);
+  if (!siblingId) return { ...EMPTY_SESSION_PARENTAGE };
+  return {
+    parent_session_id: siblingId,
+    parent_tool_use_id: null,
+    agent_nickname: null,
+    thread_role: "subagent",
+  };
+}
+
+function resolvePiParentRef(ref: string | null, childPath: string): string | null {
+  if (!ref) return null;
+  if (!ref.includes("/") && !ref.includes("\\") && !/\.jsonl$/i.test(ref)) return ref;
+  const target = isAbsolute(ref) ? ref : join(dirname(childPath), ref);
+  const id = readPiSessionIdFromFile(target);
+  if (!id) throw new ParentageError("unresolved_reference", "Parent reference has no readable session header.", target);
+  return id;
+}
+
+export function readPiSessionIdFromFile(path: string, options: ParentageOptions = {}): string | null {
+  try {
+    const id = readPiSessionHeader(readFilePrefix(path))?.id;
+    if (!id) throw new ParentageError("invalid_metadata", "No valid session header in the bounded file prefix.");
+    return id;
+  } catch (error) {
+    reportError(options, path, error);
+    return null;
+  }
+}
+
+function readPiSessionHeader(
+  transcript: string | null,
+): { id: string; parentSession?: unknown; branchedFrom?: unknown } | null {
+  if (!transcript) return null;
+  for (const obj of scanJsonlObjects(transcript, META_SCAN_LINES, '"session"')) {
+    if (obj.type !== "session") continue;
+    const id = asNonEmptyString(obj.id);
+    if (!id) throw new ParentageError("invalid_metadata", "Session header has no nonblank id.");
+    return { id, parentSession: obj.parentSession, branchedFrom: obj.branchedFrom };
+  }
+  return null;
+}
+
+function extractOpenCodeParentage(
+  sourcePath: string,
+  sessionId: string | undefined,
+  transcript?: string,
+): SessionParentage {
+  const fromJson = parentageFromOpenCodeJson(sourcePath, transcript);
+  if (fromJson.parent_session_id || fromJson.parent_known) {
+    const { session_id: _id, parent_known: _known, ...parentage } = fromJson;
+    return parentage;
+  }
+  const id = fromJson.session_id ?? asNonEmptyString(sessionId);
+  if (!id) return { ...EMPTY_SESSION_PARENTAGE };
+  const dbPath = findOpenCodeDatabase(sourcePath);
+  if (!dbPath) return { ...EMPTY_SESSION_PARENTAGE };
+  return extractOpenCodeSqliteParentage(dbPath, id);
+}
+
+function parentageFromOpenCodeJson(sourcePath: string, transcript?: string): SessionParentage & {
+  session_id: string | null;
+  parent_known: boolean;
+} {
+  const empty = { ...EMPTY_SESSION_PARENTAGE, session_id: null, parent_known: false };
+  if (transcript === undefined && (!/\.jsonl?$/i.test(sourcePath) || !existsSync(sourcePath))) {
+    return empty;
+  }
+  const text = transcript ?? readFileSync(sourcePath, "utf8");
+  let parsed: Record<string, unknown> | null;
+  try {
+    parsed = asRecord(JSON.parse(text));
+  } catch {
+    throw new ParentageError("invalid_metadata", "OpenCode session is not valid JSON.");
+  }
+  if (!parsed) throw new ParentageError("invalid_metadata", "OpenCode session must be a JSON object.");
+  const nestedInfo = asRecord(parsed.info);
+  if (("info" in parsed || "messages" in parsed) && !nestedInfo) {
+    throw new ParentageError("invalid_metadata", "OpenCode export has no valid info object.");
+  }
+  const info = nestedInfo ?? parsed;
+  const parent =
+    asNonEmptyString(info.parentID) ?? asNonEmptyString(info.parent_id);
+  const sessionId = asNonEmptyString(info.id);
+  const parentKnown = Object.hasOwn(info, "parentID") || Object.hasOwn(info, "parent_id");
+  if (!parent) return { ...empty, session_id: sessionId, parent_known: parentKnown };
+  return {
+    parent_session_id: parent,
+    parent_tool_use_id: null,
+    agent_nickname: null,
+    thread_role: "subagent",
+    session_id: sessionId,
+    parent_known: true,
+  };
+}
+
+function findOpenCodeDatabase(startPath: string): string | null {
+  if (startPath.toLowerCase().endsWith(".db") && existsSync(startPath)) {
+    return startPath;
+  }
+  let dir = dirname(startPath);
+  for (let i = 0; i < 8; i++) {
+    const candidate = join(dir, "opencode.db");
+    if (existsSync(candidate)) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+function extractOpenCodeSqliteParentage(
+  dbPath: string,
+  sessionId: string,
+): SessionParentage {
+  // Same gradient as the OpenCode adapter: a store held by its own writer is
+  // read from a private copy instead of costing the parent link.
+  const row = withReadOnlyDb(dbPath, (db) =>
+    db
+      .query<{ parent_id: string | null }, [string]>(
+        "SELECT parent_id FROM session WHERE id = ? LIMIT 1",
+      )
+      .get(sessionId));
+  const parent = asNonEmptyString(row?.parent_id);
+  if (!parent) return { ...EMPTY_SESSION_PARENTAGE };
+  return {
+    parent_session_id: parent,
+    parent_tool_use_id: null,
+    agent_nickname: null,
+    thread_role: "subagent",
+  };
+}
+
+function extractHermesParentage(
+  sourcePath: string,
+  sessionId: string | undefined,
+): SessionParentage {
+  if (!sessionId || !existsSync(sourcePath)) {
+    return { ...EMPTY_SESSION_PARENTAGE };
+  }
+  const row = withReadOnlyDb(sourcePath, (db) =>
+    db
+      .query<{ parent_session_id: string | null }, [string]>(
+        "SELECT parent_session_id FROM sessions WHERE id = ? LIMIT 1",
+      )
+      .get(sessionId));
+  const parent = asNonEmptyString(row?.parent_session_id);
+  if (!parent) return { ...EMPTY_SESSION_PARENTAGE };
+  return {
+    parent_session_id: parent,
+    parent_tool_use_id: null,
+    agent_nickname: null,
+    thread_role: "subagent",
+  };
+}
+
+function parentageFromCodexMeta(payload: Record<string, unknown>): SessionParentage {
+  const source = asRecord(payload.source);
+  const subagent = asRecord(source?.subagent);
+  const spawn = asRecord(subagent?.thread_spawn);
+  const parent =
+    asNonEmptyString(payload.parent_thread_id) ??
+    asNonEmptyString(spawn?.parent_thread_id) ??
+    asNonEmptyString(subagent?.parent_thread_id) ??
+    asNonEmptyString(payload.forked_from_id);
+  return {
+    parent_session_id: parent,
+    parent_tool_use_id:
+      asNonEmptyString(payload.parent_tool_use_id) ??
+      asNonEmptyString(spawn?.parent_tool_use_id) ??
+      null,
+    agent_nickname:
+      asNonEmptyString(payload.agent_nickname) ??
+      asNonEmptyString(spawn?.agent_nickname) ??
+      null,
+    thread_role: asNonEmptyString(payload.thread_source),
+  };
+}
+
+function* scanJsonlObjects(
+  transcript: string,
+  maxLines: number,
+  needle?: string,
+): Generator<Record<string, unknown>> {
+  let offset = 0;
+  for (let i = 0; i < maxLines && offset < transcript.length; i++) {
+    const nl = transcript.indexOf("\n", offset);
+    const line = nl === -1 ? transcript.slice(offset) : transcript.slice(offset, nl);
+    offset = nl === -1 ? transcript.length : nl + 1;
+    if (!line.trim()) continue;
+    if (needle && !line.includes(needle)) continue;
+    try {
+      const obj = JSON.parse(line) as unknown;
+      const record = asRecord(obj);
+      if (record) yield record;
+    } catch {
+      throw new ParentageError("invalid_metadata", "Source metadata contains malformed JSONL.");
+    }
+  }
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function asNonEmptyString(value: unknown): string | null {
+  return typeof value === "string" ? value.trim() || null : null;
+}
+
+function readFilePrefixIfPresent(path: string, requireComplete = false): string | null {
+  if (!existsSync(path)) return null;
+  return readFilePrefix(path, requireComplete);
+}
+
+function readFilePrefix(path: string, requireComplete = false): string {
+  const fd = openSync(path, "r");
+  try {
+    const buf = Buffer.alloc(FILE_PREFIX_BYTES);
+    const n = readSync(fd, buf, 0, buf.length, 0);
+    if (requireComplete && fstatSync(fd).size > n) {
+      throw new ParentageError("incomplete_evidence", "A bounded prefix cannot prove a standalone Claude sidechain.", path);
+    }
+    return buf.subarray(0, n).toString("utf8");
+  } finally {
+    closeSync(fd);
+  }
+}