@principal-ai/principal-view-core 0.28.8 → 0.28.10

package/src/opencode/agent-sessions.ts

@@ -0,0 +1,282 @@
+import {
+  ClineSessionReader,
+  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, and Grok, normalizing raw events into repo-aware universal events.
+ *
+ * This is the single source of truth for CLI and trail-viewer 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" | "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();
+
+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;
+}
+
+/** 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 trail-viewer 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 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;
+  }
+  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" {
+  if (isClineSession(sessionId)) return "cline";
+  if (isPiSession(sessionId)) return "pi";
+  if (isGrokSession(sessionId)) return "grok";
+  return "opencode";
+}
+
+/**
+ * Fetch a session's raw universal events from the appropriate source.
+ */
+export function fetchRawEvents(
+  sessionId: string,
+  options: {
+    agent?: "cline" | "opencode" | "pi" | "grok";
+    dbPath?: string;
+  } = {},
+): {
+  agent: "cline" | "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,
+      },
+    };
+  }
+  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,199 @@
+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 trail-viewer'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) return bestMatch;
+
+    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;
+  }
+}

package/src/opencode/pipeline.ts

@@ -0,0 +1,141 @@
+import {
+  PathNormalizationService,
+  V1EventBridgeProcessor,
+  createAccumulatedState,
+  eventOp,
+  type RepoNormalizedUniversalAgentSessionEvent,
+  type RepositoryInfo,
+  type UniversalAgentSessionEvent,
+} from "@principal-ai/agent-monitoring";
+import { NodePathNormalizationAdapter } from "./node-path-adapter";
+
+export { NodePathNormalizationAdapter };
+
+/**
+ * Pure, agent-agnostic session pipeline shared by CLI and trail-viewer.
+ *
+ * This module intentionally imports NO better-sqlite3 / OpenCodeEventStore so
+ * it can be loaded in any runtime (the trail-viewer runs under Bun, where
+ * better-sqlite3's native NAPI binding crashes). Runtime-specific DB access
+ * feeds this pipeline; everything after the raw rows are in is shared.
+ */
+
+/** A raw opencode event DB row, before JSON decoding of its `data` payload. */
+export interface OpenCodeEventRow {
+  id: string;
+  aggregateId: string;
+  seq: number;
+  type: string;
+  data: string | Record<string, unknown>;
+}
+
+/**
+ * Convert raw opencode event rows into universal events. Handles both string
+ * (SQLite TEXT, unparsed) and already-parsed object `data` payloads.
+ */
+export function opencodeRowsToUniversalEvents(
+  rows: OpenCodeEventRow[],
+): UniversalAgentSessionEvent[] {
+  const processor = new V1EventBridgeProcessor();
+  return rows.map((row) =>
+    processor.normalize({
+      type: row.type as
+        | "session.created.1"
+        | "session.updated.1"
+        | "message.updated.1"
+        | "message.part.updated.1"
+        | "message.removed.1",
+      data:
+        typeof row.data === "string"
+          ? (JSON.parse(row.data) as Record<string, unknown>)
+          : row.data,
+      id: row.id,
+      aggregateId: row.aggregateId,
+      seq: row.seq,
+    }),
+  );
+}
+
+/** Normalize raw universal events into repo-normalized universal events. */
+export async function normalizeEvents(
+  events: UniversalAgentSessionEvent[],
+  workingDirectory = "",
+  knownRoots?: Map<string, RepositoryInfo>,
+): Promise<RepoNormalizedUniversalAgentSessionEvent[]> {
+  const { normalized } = await normalizeEventsWithAdapter(events, workingDirectory, knownRoots);
+  return normalized;
+}
+
+/**
+ * Like `normalizeEvents`, but also returns the adapter so callers can inspect
+ * `adapter.newlyDiscovered` for auto-registration of newly found git roots.
+ */
+export async function normalizeEventsWithAdapter(
+  events: UniversalAgentSessionEvent[],
+  workingDirectory = "",
+  knownRoots?: Map<string, RepositoryInfo>,
+): Promise<{ normalized: RepoNormalizedUniversalAgentSessionEvent[]; adapter: NodePathNormalizationAdapter }> {
+  const adapter = new NodePathNormalizationAdapter(knownRoots);
+  const service = new PathNormalizationService(adapter);
+  const normalized = await service.normalizePathsBatch(events, workingDirectory);
+  return { normalized, adapter };
+}
+
+/** Compute the accumulated agent-session event rows for a normalized session. */
+export function accumulateEvents(
+  normalizedEvents: RepoNormalizedUniversalAgentSessionEvent[],
+  sessionTitle = "",
+): Array<{ normalized: RepoNormalizedUniversalAgentSessionEvent; accumulated: unknown }> {
+  const accState = createAccumulatedState(sessionTitle);
+  return normalizedEvents.map((normalizedEvent) => ({
+    normalized: normalizedEvent,
+    accumulated: eventOp(accState, normalizedEvent),
+  }));
+}
+
+/** Collect the distinct repositories referenced across a normalized session. */
+export function collectRepositories(
+  normalizedEvents: RepoNormalizedUniversalAgentSessionEvent[],
+): RepositoryInfo[] {
+  const byRoot = new Map<string, RepositoryInfo>();
+
+  // Event-level repository context uses the RepositoryInfo shape (key: `root`).
+  const putEventRepo = (root: string, repo: RepositoryInfo) => {
+    byRoot.set(root, {
+      root,
+      remoteUrl: repo.remoteUrl,
+      owner: repo.owner,
+      repo: repo.repo,
+      branch: repo.branch,
+      headCommit: repo.headCommit,
+    });
+  };
+
+  // Per-file repository uses the NormalizedPathInfo shape (key: `gitRoot`, no
+  // branch/headCommit). Normalize into the RepositoryInfo shape.
+  const putFileRepo = (
+    root: string,
+    repo: { remoteUrl?: string; owner?: string; repo?: string },
+  ) => {
+    const existing = byRoot.get(root);
+    byRoot.set(root, {
+      root,
+      remoteUrl: repo.remoteUrl ?? existing?.remoteUrl,
+      owner: repo.owner ?? existing?.owner,
+      repo: repo.repo ?? existing?.repo,
+      branch: existing?.branch,
+      headCommit: existing?.headCommit,
+    });
+  };
+
+  for (const event of normalizedEvents) {
+    if (event.repository?.root) putEventRepo(event.repository.root, event.repository);
+    for (const file of event.files ?? []) {
+      const fileRepo = file.repository;
+      if (fileRepo?.gitRoot) {
+        putFileRepo(fileRepo.gitRoot, fileRepo);
+      }
+    }
+  }
+  return Array.from(byRoot.values());
+}

package/src/opencode/types.ts

@@ -0,0 +1,43 @@
+export interface OpenCodeRawEvent {
+  id: string
+  aggregateId: string
+  seq: number
+  type: string
+  data: Record<string, unknown>
+}
+
+export interface OpenCodeSessionEvents {
+  sessionId: string
+  events: OpenCodeRawEvent[]
+  hasMore: boolean
+}
+
+export interface OpenCodeEventRetriever {
+  readAggregate(
+    sessionId: string,
+    options?: { after?: number; limit?: number }
+  ): OpenCodeSessionEvents
+}
+
+export interface OpenCodeStoreOptions {
+  dbPath?: string
+}
+
+export interface SessionSummary {
+  id: string
+  title: string
+  slug: string
+  createdAt: string
+  durationMs: number
+  eventCount: number
+  isFinished: boolean
+  children: SessionSummary[]
+}
+
+export interface SessionListResult {
+  groups: Array<{
+    parent: SessionSummary
+    children: SessionSummary[]
+  }>
+  standalone: SessionSummary[]
+}