@ai-devkit/agent-manager 0.36.0 → 0.38.0

package/src/harnesses/claude/ClaudeSessionParser.ts

@@ -0,0 +1,524 @@
+import * as fs from "fs";
+import * as path from "path";
+import type { ConversationMessage, ConversationOptions } from "../../adapters/AgentAdapter.js";
+import { AgentStatus } from "../../adapters/AgentAdapter.js";
+import {
+  IncrementalJsonlSummary,
+  reduceJsonlContent,
+  type JsonlSummaryBounds,
+  type JsonlSummaryReducer,
+} from "../../utils/IncrementalJsonlSummary.js";
+import { JsonlTailReader, normalizeTail } from "../../utils/jsonlTail.js";
+
+/**
+ * Content block within a Claude Code JSONL message entry.
+ * Handles text, tool_use, and tool_result block types.
+ */
+export interface ContentBlock {
+  type?: string;
+  text?: string;
+  content?: string;
+  name?: string;
+  input?: Record<string, unknown>;
+  tool_use_id?: string;
+  is_error?: boolean;
+}
+
+/**
+ * A single line entry in a Claude Code session JSONL file.
+ *
+ * Each line is an independent JSON object with a type discriminator:
+ * - "user" / "assistant" / "system" — conversation turns
+ * - "progress" / "thinking" — intermediate agent state
+ * - "last-prompt" / "file-history-snapshot" — metadata (not conversation state)
+ */
+export interface SessionEntry {
+  type?: string;
+  timestamp?: string;
+  cwd?: string;
+  message?: {
+    content?: string | ContentBlock[];
+  };
+}
+
+/**
+ * Parsed session state extracted from a JSONL file.
+ * Aggregates data from all entries into a single summary.
+ */
+export interface ClaudeSession {
+  sessionId: string;
+  projectPath: string;
+  lastCwd?: string;
+  sessionStart: Date;
+  lastActive: Date;
+  lastEntryType?: string;
+  isInterrupted: boolean;
+  lastUserMessage?: string;
+  /** First meaningful user prompt in the session (post noise filter) */
+  firstUserMessage?: string;
+}
+
+/**
+ * O(1) running summary folded from session entries; `toSession` turns it into
+ * a `ClaudeSession`. Timestamps are epoch ms so cached state stays immutable.
+ */
+interface ClaudeSummaryState {
+  seenFirstLine: boolean;
+  /** A bounded cold start skipped the middle: later lines are not the session's first. */
+  pastHead?: boolean;
+  sessionStartMs?: number;
+  lastActiveMs?: number;
+  lastCwd?: string;
+  lastEntryType?: string;
+  isInterrupted: boolean;
+  lastUserMessage?: string;
+  firstUserMessage?: string;
+}
+
+/**
+ * Top-level JSONL entry types that represent conversation/agent state.
+ *
+ * Only these types update `lastEntryType` for status determination. All
+ * other types Claude Code emits (`attachment`, `permission-mode`,
+ * `ai-title`, `queued_command`, `tools_changed`, `model_changed`,
+ * `hook_progress`, …) are UI-state events that must not overwrite the
+ * last conversation turn — otherwise polling between writes lands on a
+ * UI-state entry and `determineStatus` falls through to UNKNOWN.
+ */
+const CONVERSATION_ENTRY_TYPES = new Set(["user", "assistant", "system", "progress", "thinking"]);
+
+export interface ClaudeSessionParserOptions {
+  /** Cold-start scan bounds for `readSessionIncremental` (see IncrementalJsonlSummary). */
+  summaryBounds?: JsonlSummaryBounds | false;
+}
+
+/**
+ * Parses Claude Code session JSONL files into structured data.
+ *
+ * Session files live at ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl
+ * and contain one JSON object per line, each representing a conversation
+ * event (user turn, assistant response, tool call, etc.).
+ */
+export class ClaudeSessionParser {
+  /** Incremental reader backing `getConversation({ tail })`. */
+  private readonly tailReader = new JsonlTailReader();
+
+  private readonly sessionCache: IncrementalJsonlSummary<ClaudeSummaryState>;
+
+  constructor(options: ClaudeSessionParserOptions = {}) {
+    this.sessionCache = new IncrementalJsonlSummary(this.summaryReducer, {
+      bounds: options.summaryBounds,
+    });
+  }
+
+  /**
+   * Parse a session JSONL file into a ClaudeSession summary.
+   *
+   * Iterates all lines to extract: session start time (from first entry),
+   * last activity timestamp, last entry type (for status), whether the
+   * session was interrupted, and the last meaningful user message.
+   *
+   * Returns null if the file is unreadable or empty.
+   */
+  readSession(filePath: string, projectPath: string): ClaudeSession | null {
+    let content: string;
+    try {
+      content = fs.readFileSync(filePath, "utf-8");
+    } catch {
+      return null;
+    }
+
+    return this.toSession(filePath, projectPath, reduceJsonlContent(this.summaryReducer, content));
+  }
+
+  /**
+   * Same result as `readSession`, but backed by a per-instance incremental
+   * cache so repeated refreshes only parse bytes appended since the last call.
+   * Call `pruneSessionCache()` once per refresh to evict files no longer read.
+   *
+   * The first read of a large transcript is a bounded head + tail scan (see
+   * `summaryReducer.skip`); fields whose entries lie only in the skipped
+   * middle fall back to their defaults instead of forcing a full parse.
+   */
+  readSessionIncremental(filePath: string, projectPath: string): ClaudeSession | null {
+    const result = this.sessionCache.read(filePath);
+    return result ? this.toSession(filePath, projectPath, result.state) : null;
+  }
+
+  /** Evict cached summaries for files not read since the previous prune. */
+  pruneSessionCache(): void {
+    this.sessionCache.prune();
+  }
+
+  /**
+   * Fold one JSONL entry into the O(1) session summary. Mirrors the fields
+   * `readSession` exposes: session start comes from the first line only;
+   * everything else tracks the latest matching entry.
+   *
+   * `skip` (bounded cold start) keeps the head's session start and first user
+   * message and clears every "latest" field, so those come from the tail only:
+   * a first user message beyond the head stays undefined, and a last user
+   * message before the tail window stays undefined.
+   */
+  private readonly summaryReducer: JsonlSummaryReducer<ClaudeSummaryState> = {
+    initial: () => ({ seenFirstLine: false, isInterrupted: false }),
+    reduce: (state, value) => {
+      const next: ClaudeSummaryState = { ...state, seenFirstLine: true };
+      if (!state.seenFirstLine) {
+        next.sessionStartMs = this.parseSessionStart(value);
+      }
+      if (!value || typeof value !== "object") {
+        return next;
+      }
+
+      const entry = value as SessionEntry;
+      if (entry.timestamp) {
+        const ts = new Date(entry.timestamp).getTime();
+        if (!Number.isNaN(ts)) {
+          next.lastActiveMs = ts;
+        }
+      }
+
+      if (typeof entry.cwd === "string" && entry.cwd.trim().length > 0) {
+        next.lastCwd = entry.cwd;
+      }
+
+      if (entry.type && CONVERSATION_ENTRY_TYPES.has(entry.type)) {
+        next.lastEntryType = entry.type;
+
+        if (entry.type === "user") {
+          const msgContent = entry.message?.content;
+          next.isInterrupted =
+            Array.isArray(msgContent) &&
+            msgContent.some(
+              (c) =>
+                (c.type === "text" && c.text?.includes("[Request interrupted")) ||
+                (c.type === "tool_result" && c.content?.includes("[Request interrupted")),
+            );
+
+          const text = this.extractUserMessageText(msgContent);
+          if (text) {
+            next.lastUserMessage = text;
+            if (!next.firstUserMessage && !state.pastHead) {
+              next.firstUserMessage = text;
+            }
+          }
+        } else {
+          next.isInterrupted = false;
+        }
+      }
+
+      return next;
+    },
+    skip: (state) => ({
+      seenFirstLine: true,
+      pastHead: true,
+      sessionStartMs: state.sessionStartMs,
+      firstUserMessage: state.firstUserMessage,
+      isInterrupted: false,
+    }),
+  };
+
+  private toSession(
+    filePath: string,
+    projectPath: string,
+    state: ClaudeSummaryState,
+  ): ClaudeSession {
+    const sessionStartMs = state.sessionStartMs ?? state.lastActiveMs;
+    return {
+      sessionId: path.basename(filePath, ".jsonl"),
+      projectPath: projectPath || state.lastCwd || "",
+      lastCwd: state.lastCwd,
+      sessionStart: sessionStartMs !== undefined ? new Date(sessionStartMs) : new Date(),
+      lastActive: state.lastActiveMs !== undefined ? new Date(state.lastActiveMs) : new Date(),
+      lastEntryType: state.lastEntryType,
+      isInterrupted: state.isInterrupted,
+      lastUserMessage: state.lastUserMessage,
+      firstUserMessage: state.firstUserMessage,
+    };
+  }
+
+  /**
+   * Determine agent status from parsed session state.
+   *
+   * Status mapping:
+   * - "user" + interrupted → WAITING (agent finished, awaiting new input)
+   * - "user" + not interrupted → RUNNING (agent is processing)
+   * - "progress" / "thinking" → RUNNING
+   * - "assistant" → WAITING (agent responded, awaiting user)
+   * - "system" → IDLE
+   */
+  determineStatus(session: ClaudeSession): AgentStatus {
+    if (!session.lastEntryType) {
+      return AgentStatus.UNKNOWN;
+    }
+
+    if (session.lastEntryType === "user") {
+      return session.isInterrupted ? AgentStatus.WAITING : AgentStatus.RUNNING;
+    }
+
+    if (session.lastEntryType === "progress" || session.lastEntryType === "thinking") {
+      return AgentStatus.RUNNING;
+    }
+
+    if (session.lastEntryType === "assistant") {
+      return AgentStatus.WAITING;
+    }
+
+    if (session.lastEntryType === "system") {
+      return AgentStatus.IDLE;
+    }
+
+    return AgentStatus.UNKNOWN;
+  }
+
+  /**
+   * Read the full conversation from a session JSONL file.
+   *
+   * Default mode returns only text content from user/assistant/system messages.
+   * Verbose mode also includes tool_use and tool_result blocks. With `tail`,
+   * only the last N messages are read (from the end of the file).
+   */
+  getConversation(sessionFilePath: string, options?: ConversationOptions): ConversationMessage[] {
+    const verbose = options?.verbose ?? false;
+    const tail = normalizeTail(options?.tail);
+    if (tail !== undefined) {
+      return this.tailReader.read(
+        sessionFilePath,
+        tail,
+        { parseLine: (line) => this.lineToMessage(line, verbose) },
+        String(verbose),
+      );
+    }
+
+    let content: string;
+    try {
+      content = fs.readFileSync(sessionFilePath, "utf-8");
+    } catch {
+      return [];
+    }
+
+    const lines = content.trim().split("\n");
+    const messages: ConversationMessage[] = [];
+
+    for (const line of lines) {
+      const message = this.lineToMessage(line, verbose);
+      if (message) messages.push(message);
+    }
+
+    return messages;
+  }
+
+  /** Convert one JSONL line into a conversation message, or null when it is not one. */
+  private lineToMessage(line: string, verbose: boolean): ConversationMessage | null {
+    let entry: SessionEntry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      return null;
+    }
+
+    let role: ConversationMessage["role"];
+    if (entry.type === "user") {
+      role = "user";
+    } else if (entry.type === "assistant") {
+      role = "assistant";
+    } else if (entry.type === "system") {
+      role = "system";
+    } else {
+      return null;
+    }
+
+    const text = this.extractConversationContent(entry.message?.content, role, verbose);
+    if (!text) return null;
+
+    return {
+      role,
+      content: text,
+      timestamp: entry.timestamp,
+    };
+  }
+
+  /**
+   * Parse session start time (epoch ms) from the first JSONL entry.
+   *
+   * Claude Code may emit a "file-history-snapshot" as the first entry,
+   * which stores its timestamp inside "snapshot.timestamp" rather than
+   * at the root level.
+   */
+  private parseSessionStart(firstEntry: unknown): number | undefined {
+    if (!firstEntry || typeof firstEntry !== "object") {
+      return undefined;
+    }
+    const entry = firstEntry as { timestamp?: string; snapshot?: { timestamp?: string } };
+    const rawTs = entry.timestamp || entry.snapshot?.timestamp;
+    if (rawTs) {
+      const ts = new Date(rawTs).getTime();
+      if (!Number.isNaN(ts)) {
+        return ts;
+      }
+    }
+    return undefined;
+  }
+
+  /**
+   * Extract meaningful text from a user message content field.
+   *
+   * Handles multiple formats:
+   * - Plain string content
+   * - Array of content blocks (extracts first text block)
+   * - Skill slash-commands (<command-message> tags)
+   * - Expanded skill content (extracts ARGUMENTS line)
+   * - Filters noise messages (interruptions, tool loaded, session continued)
+   */
+  private extractUserMessageText(
+    content: string | Array<{ type?: string; text?: string }> | undefined,
+  ): string | undefined {
+    if (!content) {
+      return undefined;
+    }
+
+    let raw: string | undefined;
+
+    if (typeof content === "string") {
+      raw = content.trim();
+    } else if (Array.isArray(content)) {
+      for (const block of content) {
+        if (block.type === "text" && block.text?.trim()) {
+          raw = block.text.trim();
+          break;
+        }
+      }
+    }
+
+    if (!raw) {
+      return undefined;
+    }
+
+    if (raw.startsWith("<command-message>")) {
+      return this.parseCommandMessage(raw);
+    }
+
+    if (raw.startsWith("Base directory for this skill:")) {
+      const argsMatch = raw.match(/\nARGUMENTS:\s*(.+)/);
+      return argsMatch?.[1]?.trim() || undefined;
+    }
+
+    if (isNoiseMessage(raw)) {
+      return undefined;
+    }
+
+    return raw;
+  }
+
+  /**
+   * Parse a <command-message> string into "/command args" format.
+   */
+  private parseCommandMessage(raw: string): string | undefined {
+    const nameMatch = raw.match(/<command-name>([^<]+)<\/command-name>/);
+    const argsMatch = raw.match(/<command-args>([^<]+)<\/command-args>/);
+    const name = nameMatch?.[1]?.trim();
+    if (!name) {
+      return undefined;
+    }
+    const args = argsMatch?.[1]?.trim();
+    return args ? `${name} ${args}` : name;
+  }
+
+  /**
+   * Extract displayable content from a message content field for conversation output.
+   */
+  private extractConversationContent(
+    content: string | ContentBlock[] | undefined,
+    role: ConversationMessage["role"],
+    verbose: boolean,
+  ): string | undefined {
+    if (!content) return undefined;
+
+    if (typeof content === "string") {
+      const cleaned = stripHarnessTags(content);
+      if (role === "user" && isNoiseMessage(cleaned)) return undefined;
+      return cleaned || undefined;
+    }
+
+    if (!Array.isArray(content)) return undefined;
+
+    const parts: string[] = [];
+
+    for (const block of content) {
+      if (block.type === "text" && block.text?.trim()) {
+        const cleaned = stripHarnessTags(block.text);
+        if (!cleaned) continue;
+        if (role === "user" && isNoiseMessage(cleaned)) continue;
+        parts.push(cleaned);
+      } else if (block.type === "tool_use" && verbose) {
+        const inputSummary =
+          block.input?.file_path || block.input?.pattern || block.input?.command || "";
+        parts.push(`[Tool: ${block.name}]${inputSummary ? " " + inputSummary : ""}`);
+      } else if (block.type === "tool_result" && verbose) {
+        const truncated = truncateToolResult(block.content || "");
+        const prefix = block.is_error ? "[Tool Error]" : "[Tool Result]";
+        parts.push(`${prefix} ${truncated}`);
+      }
+    }
+
+    return parts.length > 0 ? parts.join("\n") : undefined;
+  }
+}
+
+/**
+ * Tags whose entire block (including content) should be dropped — they are
+ * harness-injected prompt context (system reminders, hook output, command
+ * stdout), not meaningful conversation content.
+ */
+const HARNESS_DROP_TAGS = [
+  "system-reminder",
+  "local-command-stdout",
+  "local-command-stderr",
+  "user-prompt-submit-hook",
+  "command-stdout",
+  "command-stderr",
+  "bash-input",
+  "bash-stdout",
+  "bash-stderr",
+  "command-message",
+] as const;
+
+const HARNESS_DROP_RE = new RegExp(`<(${HARNESS_DROP_TAGS.join("|")})>[\\s\\S]*?</\\1>`, "g");
+
+const COMMAND_INVOCATION_RE =
+  /<command-name>([^<]+)<\/command-name>(?:\s*<command-args>([\s\S]*?)<\/command-args>)?/g;
+
+/**
+ * Remove harness-injected XML blocks from message text and collapse
+ * <command-name>/<command-args> pairs into a "/name args" shorthand.
+ *
+ * Returns the cleaned, trimmed text. Returns an empty string if nothing
+ * survives stripping.
+ */
+function stripHarnessTags(text: string): string {
+  let out = text.replace(HARNESS_DROP_RE, "");
+
+  out = out.replace(COMMAND_INVOCATION_RE, (_match, rawName: string, rawArgs?: string) => {
+    const name = rawName.trim();
+    const args = rawArgs?.trim();
+    return args ? `${name} ${args}` : name;
+  });
+
+  return out.replace(/\n{3,}/g, "\n\n").trim();
+}
+
+/** Check if a message is noise (not a meaningful user intent). */
+function isNoiseMessage(text: string): boolean {
+  return (
+    text.startsWith("[Request interrupted") ||
+    text === "Tool loaded." ||
+    text.startsWith("This session is being continued")
+  );
+}
+
+function truncateToolResult(content: string, maxLength = 200): string {
+  const firstLine = content.split("\n")[0] || "";
+  if (firstLine.length <= maxLength) return firstLine;
+  return firstLine.slice(0, maxLength - 3) + "...";
+}

package/src/harnesses/claude/credentials.ts

@@ -0,0 +1,122 @@
+import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const CLAUDE_KEYCHAIN_SERVICE = "Claude Code-credentials";
+
+export type ClaudeCredentialOptions = {
+  env?: NodeJS.ProcessEnv;
+  readFile?: (path: string, encoding: BufferEncoding) => Promise<string>;
+  now?: () => Date;
+  cwd?: string;
+  platform?: NodeJS.Platform;
+  keychainRead?: (service: string) => Promise<string | null>;
+};
+
+type Credential = { token: string | null; expired: boolean };
+
+function record(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function nonEmptyText(value: unknown): string | null {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+function credentialsPath(options: ClaudeCredentialOptions): string {
+  const env = options.env ?? process.env;
+  const configured = nonEmptyText(env.CLAUDE_CONFIG_DIR);
+  if (configured) {
+    const profileRoot = isAbsolute(configured)
+      ? configured
+      : resolve(options.cwd ?? process.cwd(), configured);
+    return join(profileRoot, ".credentials.json");
+  }
+  return join(env.HOME || homedir(), ".claude", ".credentials.json");
+}
+
+function credentialFromRoot(root: Record<string, unknown> | null, now: Date): Credential {
+  const oauth = record(root?.claudeAiOauth);
+  const token = nonEmptyText(oauth?.accessToken);
+  if (!token) return { token: null, expired: false };
+  const expired =
+    typeof oauth?.expiresAt === "number" &&
+    Number.isFinite(oauth.expiresAt) &&
+    oauth.expiresAt <= now.getTime();
+  return { token: expired ? null : token, expired };
+}
+
+function credentialFromPayload(payload: string | null, now: Date): Credential {
+  if (!payload) return { token: null, expired: false };
+  try {
+    return credentialFromRoot(record(JSON.parse(payload)), now);
+  } catch {
+    return { token: null, expired: false };
+  }
+}
+
+async function readProfileCredential(
+  options: ClaudeCredentialOptions,
+  now: Date,
+): Promise<Credential> {
+  try {
+    const payload = await (options.readFile ?? readFile)(credentialsPath(options), "utf8");
+    return credentialFromPayload(payload, now);
+  } catch {
+    return { token: null, expired: false };
+  }
+}
+
+async function readClaudeKeychain(service: string): Promise<string | null> {
+  try {
+    const { stdout } = await execFileAsync(
+      "/usr/bin/security",
+      ["find-generic-password", "-s", service, "-w"],
+      { encoding: "utf8", timeout: 1500, maxBuffer: 1024 * 1024 },
+    );
+    return nonEmptyText(stdout);
+  } catch {
+    return null;
+  }
+}
+
+async function readKeychainCredential(
+  options: ClaudeCredentialOptions,
+  now: Date,
+): Promise<Credential> {
+  const env = options.env ?? process.env;
+  const usesDefaultProfile = !nonEmptyText(env.CLAUDE_CONFIG_DIR);
+  if (!usesDefaultProfile || (options.platform ?? process.platform) !== "darwin") {
+    return { token: null, expired: false };
+  }
+  try {
+    const payload = await (options.keychainRead ?? readClaudeKeychain)(CLAUDE_KEYCHAIN_SERVICE);
+    return credentialFromPayload(payload, now);
+  } catch {
+    return { token: null, expired: false };
+  }
+}
+
+export async function resolveClaudeAnthropicToken(
+  options: ClaudeCredentialOptions = {},
+): Promise<string> {
+  const env = options.env ?? process.env;
+  const environmentToken = nonEmptyText(env.CLAUDE_CODE_OAUTH_TOKEN);
+  if (environmentToken) return environmentToken;
+
+  const now = options.now?.() ?? new Date();
+  const profileCredential = await readProfileCredential(options, now);
+  if (profileCredential.token) return profileCredential.token;
+
+  const keychainCredential = await readKeychainCredential(options, now);
+  if (keychainCredential.token) return keychainCredential.token;
+  if (profileCredential.expired || keychainCredential.expired) {
+    throw new Error("Claude OAuth credentials expired");
+  }
+  throw new Error("Claude OAuth credentials not found or malformed");
+}