@principal-ai/subsystems-core 0.29.0

package/src/opencode/agent-sessions.ts

@@ -0,0 +1,376 @@
+import {
+  ClineSessionReader,
+  CodexSessionReader,
+  CursorSessionReader,
+  GrokSessionReader,
+  PiSessionReader,
+  type UniversalAgentSessionEvent,
+} from "@principal-ai/agent-monitoring";
+import { OpenCodeEventStore } from "./OpenCodeEventStore";
+import {
+  NodePathNormalizationAdapter,
+  accumulateEvents,
+  collectRepositories,
+  normalizeEvents,
+  normalizeEventsWithAdapter,
+  opencodeRowsToUniversalEvents,
+} from "./pipeline";
+
+export {
+  NodePathNormalizationAdapter,
+  normalizeEvents,
+  normalizeEventsWithAdapter,
+  accumulateEvents,
+  collectRepositories,
+};
+
+/**
+ * Shared, agent-agnostic session access: list + fetch across Cline, opencode,
+ * pi, Grok, and Codex, normalizing raw events into repo-aware universal events.
+ *
+ * This is the single source of truth for CLI and principal-studio session pulling.
+ * opencode listing delegates to `OpenCodeEventStore.listSessionsWithSummaries()`,
+ * which already builds parent/child groups and excludes subagent (child) sessions
+ * from the standalone list.
+ */
+
+export type SupportedSessionAgent =
+  | "cline"
+  | "codex"
+  | "cursor"
+  | "opencode"
+  | "pi"
+  | "grok"
+  | "unknown";
+
+export interface AgentSessionSummary {
+  agent: SupportedSessionAgent;
+  sessionId: string;
+  title: string;
+  createdAt: string;
+  eventCount: number;
+  isFinished: boolean;
+  parentID?: string;
+}
+
+export interface AgentSessionMeta {
+  sessionName: string;
+  sessionTask: string;
+  workingDirectory: string;
+  createdAt?: string;
+}
+
+const clineReader = new ClineSessionReader();
+const piReader = new PiSessionReader();
+const grokReader = new GrokSessionReader();
+const codexReader = new CodexSessionReader();
+const cursorReader = new CursorSessionReader();
+
+function isClineSession(sessionId: string): boolean {
+  return clineReader.readSession(sessionId) !== null;
+}
+
+function isPiSession(sessionId: string): boolean {
+  return piReader.readSession(sessionId) !== null;
+}
+
+function isGrokSession(sessionId: string): boolean {
+  return grokReader.readSession(sessionId) !== null;
+}
+
+function isCodexSession(sessionId: string): boolean {
+  return codexReader.readSession(sessionId) !== null;
+}
+
+function isCursorSession(sessionId: string): boolean {
+  return cursorReader.readSession(sessionId) !== null;
+}
+
+/** List Cline CLI sessions from the durable on-disk transcript. */
+function listClineSessions(): AgentSessionSummary[] {
+  return clineReader.listSessions().map((record) => {
+    const meta = record.metadata;
+    const promptText = (meta.prompt ?? "").trim();
+    const title =
+      promptText.length > 0
+        ? promptText.length > 80
+          ? `${promptText.slice(0, 80)}…`
+          : promptText
+        : "Cline session";
+    return {
+      agent: "cline" as const,
+      sessionId: record.sessionId,
+      title,
+      createdAt: meta.started_at ?? "",
+      eventCount: clineReader.readMessages(record.sessionId)?.messages.length ?? 0,
+      isFinished: meta.status === "completed" || meta.status === "failed",
+    };
+  });
+}
+
+/** List pi CLI sessions from the durable on-disk JSONL transcripts. */
+function listPiSessions(): AgentSessionSummary[] {
+  return piReader.listSessions().map((record) => {
+    const promptText = (record.firstPrompt ?? "").trim();
+    const title =
+      promptText.length > 0
+        ? promptText.length > 80
+          ? `${promptText.slice(0, 80)}…`
+          : promptText
+        : "pi session";
+    return {
+      agent: "pi" as const,
+      sessionId: record.sessionId,
+      title,
+      createdAt: record.header.timestamp ?? "",
+      eventCount: record.messageCount,
+      // pi transcripts carry no finished marker; the principal-studio appends a
+      // synthesized session-end event at read time.
+      isFinished: false,
+    };
+  });
+}
+
+/** List Grok Build sessions from ~/.grok/sessions durable JSONL. */
+function listGrokSessions(): AgentSessionSummary[] {
+  return grokReader.listSessions().map((record) => {
+    return {
+      agent: "grok" as const,
+      sessionId: record.sessionId,
+      title: record.title || "Grok session",
+      createdAt: record.createdAt,
+      eventCount: record.messageCount,
+      isFinished: false,
+      parentID: record.parentSessionId,
+    };
+  });
+}
+
+/** List Codex sessions from durable rollout JSONL. */
+function listCodexSessions(): AgentSessionSummary[] {
+  return codexReader.listSessions().map((record) => ({
+    agent: "codex" as const,
+    sessionId: record.sessionId,
+    title: record.firstPrompt || "Codex session",
+    createdAt:
+      typeof record.meta.timestamp === "string"
+        ? record.meta.timestamp
+        : new Date(record.lastActivity).toISOString(),
+    eventCount: record.messageCount,
+    isFinished: false,
+  }));
+}
+
+/** List Cursor IDE agent chats from ~/.cursor/chats. */
+function listCursorSessions(): AgentSessionSummary[] {
+  return cursorReader.listSessions().map((record) => ({
+    agent: "cursor" as const,
+    sessionId: record.sessionId,
+    title: record.title || "Cursor session",
+    createdAt: record.createdAt || new Date(record.lastActivity).toISOString(),
+    eventCount: record.messageCount,
+    isFinished: false,
+  }));
+}
+
+/**
+ * List opencode sessions, top-level only by default. Delegates to the store's
+ * grouped `listSessionsWithSummaries()` which excludes subagent (child) sessions.
+ */
+function listOpencodeSessions(dbPath?: string): AgentSessionSummary[] {
+  const store = new OpenCodeEventStore({ dbPath });
+  try {
+    const result = store.listSessionsWithSummaries(50);
+    const toSummary = (s: {
+      id: string;
+      title: string;
+      createdAt: string;
+      eventCount: number;
+      isFinished: boolean;
+    }): AgentSessionSummary => ({
+      agent: "opencode",
+      sessionId: s.id,
+      title: s.title,
+      createdAt: s.createdAt,
+      eventCount: s.eventCount,
+      isFinished: s.isFinished,
+    });
+    const standalone: AgentSessionSummary[] = [
+      ...result.standalone.map(toSummary),
+      ...result.groups.map((g) => toSummary(g.parent)),
+    ];
+    // Sort newest-first by createdAt
+    return standalone.sort((a, b) =>
+      b.createdAt < a.createdAt ? -1 : b.createdAt > a.createdAt ? 1 : 0,
+    );
+  } finally {
+    store.close();
+  }
+}
+
+/** List sessions from all supported agents. Top-level only by default. */
+export function listAgentSessions(
+  options: { dbPath?: string } = {},
+): AgentSessionSummary[] {
+  const all: AgentSessionSummary[] = [];
+  let firstError: Error | null = null;
+  try {
+    all.push(...listOpencodeSessions(options.dbPath));
+  } catch (err) {
+    firstError = err as Error;
+  }
+  try {
+    all.push(...listClineSessions());
+  } catch (err) {
+    if (!firstError) firstError = err as Error;
+  }
+  try {
+    all.push(...listPiSessions());
+  } catch (err) {
+    if (!firstError) firstError = err as Error;
+  }
+  try {
+    all.push(...listGrokSessions());
+  } catch (err) {
+    if (!firstError) firstError = err as Error;
+  }
+  try {
+    all.push(...listCodexSessions());
+  } catch (err) {
+    if (!firstError) firstError = err as Error;
+  }
+  try {
+    all.push(...listCursorSessions());
+  } catch (err) {
+    if (!firstError) firstError = err as Error;
+  }
+  if (all.length === 0 && firstError) {
+    throw firstError;
+  }
+  return all;
+}
+
+/** Detect which agent a session id belongs to. */
+export function detectAgent(
+  sessionId: string,
+): "cline" | "opencode" | "pi" | "grok" | "codex" | "cursor" {
+  if (isClineSession(sessionId)) return "cline";
+  if (isPiSession(sessionId)) return "pi";
+  if (isGrokSession(sessionId)) return "grok";
+  if (isCodexSession(sessionId)) return "codex";
+  if (isCursorSession(sessionId)) return "cursor";
+  return "opencode";
+}
+
+/**
+ * Fetch a session's raw universal events from the appropriate source.
+ */
+export function fetchRawEvents(
+  sessionId: string,
+  options: {
+    agent?: "cline" | "codex" | "cursor" | "opencode" | "pi" | "grok";
+    dbPath?: string;
+  } = {},
+): {
+  agent: "cline" | "codex" | "cursor" | "opencode" | "pi" | "grok";
+  events: UniversalAgentSessionEvent[];
+  sessionMeta: AgentSessionMeta;
+} {
+  const agent = options.agent ?? detectAgent(sessionId);
+  if (agent === "cline") {
+    const record = clineReader.readSession(sessionId);
+    const promptText = (record?.metadata.prompt ?? "").trim();
+    return {
+      agent,
+      events: clineReader.toUniversalEvents(sessionId),
+      sessionMeta: {
+        sessionName: "cline",
+        sessionTask:
+          (promptText.length > 80 ? `${promptText.slice(0, 80)}…` : promptText) ||
+          "Cline session",
+        workingDirectory: record?.metadata.workspace_root ?? record?.metadata.cwd ?? "",
+      },
+    };
+  }
+  if (agent === "pi") {
+    const record = piReader.readSession(sessionId);
+    const promptText = (record?.firstPrompt ?? "").trim();
+    return {
+      agent,
+      events: piReader.toUniversalEvents(sessionId),
+      sessionMeta: {
+        sessionName: "pi",
+        sessionTask:
+          (promptText.length > 80 ? `${promptText.slice(0, 80)}…` : promptText) || "pi session",
+        workingDirectory: "",
+      },
+    };
+  }
+  if (agent === "grok") {
+    const record = grokReader.readSession(sessionId);
+    return {
+      agent,
+      events: grokReader.toUniversalEvents(sessionId),
+      sessionMeta: {
+        sessionName: "grok",
+        sessionTask: record?.title || "Grok session",
+        workingDirectory: record?.cwd ?? "",
+        createdAt: record?.createdAt,
+      },
+    };
+  }
+  if (agent === "codex") {
+    const record = codexReader.readSession(sessionId);
+    const promptText = (record?.firstPrompt ?? "").trim();
+    return {
+      agent,
+      events: codexReader.toUniversalEvents(sessionId),
+      sessionMeta: {
+        sessionName: "codex",
+        sessionTask:
+          (promptText.length > 80 ? `${promptText.slice(0, 80)}…` : promptText) ||
+          "Codex session",
+        workingDirectory: record?.cwd ?? "",
+        createdAt:
+          typeof record?.meta.timestamp === "string"
+            ? record.meta.timestamp
+            : undefined,
+      },
+    };
+  }
+  if (agent === "cursor") {
+    const record = cursorReader.readSession(sessionId);
+    const promptText = (record?.firstPrompt ?? "").trim();
+    return {
+      agent,
+      events: cursorReader.toUniversalEvents(sessionId),
+      sessionMeta: {
+        sessionName: "cursor",
+        sessionTask:
+          record?.title ||
+          (promptText.length > 80 ? `${promptText.slice(0, 80)}…` : promptText) ||
+          "Cursor session",
+        workingDirectory: record?.cwd ?? "",
+        createdAt: record?.createdAt,
+      },
+    };
+  }
+  const store = new OpenCodeEventStore({ dbPath: options.dbPath });
+  try {
+    const { events } = store.readAggregate(sessionId, { limit: 10000 });
+    const meta = store.getSessionMeta(sessionId);
+    const title =
+      meta.title && !meta.title.startsWith("New session") ? meta.title : meta.slug;
+    return {
+      agent,
+      events: opencodeRowsToUniversalEvents(events),
+      sessionMeta: {
+        sessionName: meta.slug || "opencode",
+        sessionTask: title || meta.slug || "opencode",
+        workingDirectory: meta.directory,
+      },
+    };
+  } finally {
+    store.close();
+  }
+}

package/src/opencode/index.ts

@@ -0,0 +1,23 @@
+export type {
+  OpenCodeRawEvent,
+  OpenCodeSessionEvents,
+  OpenCodeEventRetriever,
+  OpenCodeStoreOptions,
+} from "./types";
+
+export { listAgentSessions, detectAgent, fetchRawEvents } from "./agent-sessions";
+export type {
+  AgentSessionSummary,
+  AgentSessionMeta,
+  SupportedSessionAgent,
+} from "./agent-sessions";
+
+export {
+  NodePathNormalizationAdapter,
+  normalizeEvents,
+  normalizeEventsWithAdapter,
+  accumulateEvents,
+  collectRepositories,
+  opencodeRowsToUniversalEvents,
+} from "./pipeline";
+export type { OpenCodeEventRow } from "./pipeline";

package/src/opencode/node-path-adapter.ts

@@ -0,0 +1,205 @@
+import { spawnSync } from "node:child_process";
+import { promises as fs } from "node:fs";
+import { dirname, isAbsolute as pathIsAbsolute, relative, resolve } from "node:path";
+import os from "node:os";
+import type {
+  PathNormalizationAdapter,
+  RepositoryInfo,
+  SystemInfo,
+} from "@principal-ai/agent-monitoring";
+
+/**
+ * NodePathNormalizationAdapter — a Node.js implementation of the
+ * `PathNormalizationAdapter` interface from `@principal-ai/agent-monitoring`.
+ *
+ * This is the shared, agent-agnostic adapter used by the CLI's `agent-session`
+ * command. It discovers git roots by walking up directories and enriches them
+ * with git metadata via the `git` CLI (spawnSync). It keeps the same interface
+ * so `PathNormalizationService` can be shared verbatim. It is the Node.js
+ * analogue of the principal-studio's `BunNormalizationAdapter` and the desktop
+ * app's `ServerPathNormalizationAdapter`.
+ */
+function gitCommand(cwd: string, subcommand: string): string | undefined {
+  const result = spawnSync("git", ["-C", cwd, ...subcommand.split(" ")], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+    timeout: 5000,
+  });
+  if (result.status !== 0 || !result.stdout) return undefined;
+  return result.stdout.trim() || undefined;
+}
+
+/** Basic GitHub owner/repo extraction from a remote URL. */
+function githubIdentityFromRemoteUrl(remoteUrl: string): {
+  owner: string;
+  name: string;
+} | null {
+  const cleaned = remoteUrl
+    .replace(/^git@github\.com:/, "")
+    .replace(/^https?:\/\/github\.com\//, "")
+    .replace(/\.git$/, "");
+  const parts = cleaned.split("/").filter(Boolean);
+  if (parts.length >= 2) {
+    return { owner: parts[0], name: parts[1] };
+  }
+  return null;
+}
+
+export class NodePathNormalizationAdapter implements PathNormalizationAdapter {
+  private homeDir: string;
+  private gitRootCache = new Map<string, string | null>();
+  private canonicalCaseCache = new Map<string, string>();
+  private knownRoots: Map<string, RepositoryInfo>;
+  /** Roots discovered via .git walk-up that weren't in the initial knownRoots */
+  readonly newlyDiscovered: RepositoryInfo[] = [];
+
+  constructor(knownRoots?: Map<string, RepositoryInfo>) {
+    this.homeDir = os.homedir();
+    this.knownRoots = knownRoots ?? new Map();
+  }
+
+  /**
+   * Resolve the on-disk spelling of a directory path segment by segment. On
+   * case-insensitive filesystems (macOS APFS) the same directory is reachable
+   * under any casing, so git-root discovery can surface `/repo` and `/Repo` as
+   * two distinct roots unless we pin them to the actual on-disk spelling.
+   */
+  private async canonicalizeCase(input: string): Promise<string> {
+    const cached = this.canonicalCaseCache.get(input);
+    if (cached !== undefined) return cached;
+    const segments = input.split("/").filter(Boolean);
+    let current = "/";
+    for (const seg of segments) {
+      let real = seg;
+      try {
+        const entries = await fs.readdir(current);
+        const match = entries.find(
+          (name) => name.toLowerCase() === seg.toLowerCase(),
+        );
+        if (match) real = match;
+      } catch {
+        // segment vanished; keep the given spelling
+      }
+      current = current === "/" ? `/${real}` : `${current}/${real}`;
+    }
+    this.canonicalCaseCache.set(input, current);
+    return current;
+  }
+
+  async getRawRepositoryInfo(
+    absolutePath: string,
+  ): Promise<RepositoryInfo | null> {
+    // Canonicalize the input: strip trailing slashes and collapse redundant
+    // separators (e.g. a tool that reads a directory as "/repo/" vs "/repo").
+    // findGitRoot returns its input verbatim when it IS the git root, so an
+    // uncanonical input would surface the same repo under two distinct root
+    // strings and duplicate it in the session's repo list. NOTE: use resolve,
+    // not normalize — path.normalize preserves trailing slashes.
+    const target = resolve(absolutePath);
+
+    // Fast path: prefix-match against known roots (zero I/O).
+    // Match on a path boundary so sibling dirs (/repo vs /repo2) don't collide.
+    let bestMatch: RepositoryInfo | null = null;
+    let bestLen = 0;
+    for (const [root, info] of this.knownRoots) {
+      const rootCanon = resolve(root);
+      if ((target === rootCanon || target.startsWith(`${rootCanon}/`)) && rootCanon.length > bestLen) {
+        bestMatch = info;
+        bestLen = rootCanon.length;
+      }
+    }
+    if (bestMatch) {
+      // A registry entry can carry a case-variant spelling of the same dir
+      // (e.g. `developer/...` on a case-insensitive fs). Pin it to the on-disk
+      // casing too, so a polluted registry can't surface the same repo twice.
+      const canonicalRoot = await this.canonicalizeCase(bestMatch.root);
+      return { ...bestMatch, root: canonicalRoot };
+    }
+
+    const gitRoot = await this.findGitRoot(target);
+    if (!gitRoot) return null;
+
+    // Pin the root to its on-disk casing so a case-variant spelling of the same
+    // directory never surfaces as a second repo (see canonicalizeCase).
+    const canonicalRoot = await this.canonicalizeCase(gitRoot);
+
+    const remoteUrl = gitCommand(canonicalRoot, "remote get-url origin");
+    const branch = gitCommand(canonicalRoot, "rev-parse --abbrev-ref HEAD");
+    const headCommit = gitCommand(canonicalRoot, "rev-parse HEAD");
+
+    let owner: string | undefined;
+    let repo: string | undefined;
+    if (remoteUrl) {
+      const identity = githubIdentityFromRemoteUrl(remoteUrl);
+      if (identity) {
+        owner = identity.owner;
+        repo = identity.name;
+      }
+    }
+    if (!repo) {
+      const parts = canonicalRoot.replace(/\/+$/, "").split("/");
+      repo = parts[parts.length - 1] ?? undefined;
+    }
+
+    const info: RepositoryInfo = {
+      root: canonicalRoot,
+      remoteUrl,
+      owner,
+      repo,
+      branch,
+      headCommit,
+    };
+    if (!this.knownRoots.has(canonicalRoot)) {
+      this.knownRoots.set(canonicalRoot, info);
+      this.newlyDiscovered.push(info);
+    }
+    return info;
+  }
+
+  private async findGitRoot(dir: string): Promise<string | null> {
+    const cached = this.gitRootCache.get(dir);
+    if (cached !== undefined) return cached;
+    try {
+      const s = await fs.stat(resolve(dir, ".git"));
+      if (s.isDirectory() || s.isFile()) {
+        this.gitRootCache.set(dir, dir);
+        return dir;
+      }
+    } catch {
+      // not a git root; walk up
+    }
+    const parent = dirname(dir);
+    if (parent === dir || parent.length >= dir.length) {
+      this.gitRootCache.set(dir, null);
+      return null;
+    }
+    const result = await this.findGitRoot(parent);
+    this.gitRootCache.set(dir, result);
+    return result;
+  }
+
+  getSystemInfo(): SystemInfo {
+    return {
+      homeDir: this.homeDir,
+      pathSeparator: "/",
+      platform: process.platform,
+      machineId: "",
+    };
+  }
+
+  resolvePath(relativePath: string, workingDirectory: string): string {
+    return resolve(workingDirectory, relativePath);
+  }
+
+  isAbsolutePath(path: string): boolean {
+    return pathIsAbsolute(path);
+  }
+
+  getRelativePath(fromPath: string, toPath: string): string {
+    return relative(fromPath, toPath);
+  }
+
+  isAvailable(): boolean {
+    return true;
+  }
+}