osborn 0.1.6 → 0.5.3

package/dist/session-access.d.ts

@@ -0,0 +1,399 @@
+/**
+ * session-access.ts — Programmatic access to Claude Agent SDK session artifacts
+ *
+ * Given a session ID and project directory, resolves all related files:
+ * conversations, sub-agents, tool results, plans, todos, tasks, file history.
+ *
+ * The JSONL files contain FULL, untruncated content — no caps on tool results,
+ * file reads, or assistant reasoning.
+ *
+ *
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * CLAUDE SESSION STORAGE — DIRECTORY MAP & RELATIONSHIP RULES
+ * ═══════════════════════════════════════════════════════════════════════════════
+ *
+ * All session data lives under a single root directory:
+ *   claudeDir = CLAUDE_CONFIG_DIR env var || ~/.claude
+ *
+ * The "project slug" is the project's absolute path with "/" replaced by "-":
+ *   /Users/foo/my-project  →  -Users-foo-my-project
+ *
+ *
+ * ── DIRECTORY STRUCTURE ─────────────────────────────────────────────────────
+ *
+ *   {claudeDir}/
+ *   ├── settings.json                  Global settings (MCP servers, etc.)
+ *   ├── history.jsonl                  Top-level conversation index
+ *   │
+ *   ├── projects/{projectSlug}/        ALL SESSION DATA lives here
+ *   │   ├── {sessionId}.jsonl          Main conversation (1 file per session)
+ *   │   ├── {sessionId}/
+ *   │   │   ├── subagents/
+ *   │   │   │   └── agent-{hash}.jsonl Sub-agent conversations (one per Task tool call)
+ *   │   │   └── tool-results/
+ *   │   │       └── {hash}.txt         Large tool outputs (exceeding inline threshold)
+ *   │   ├── .session-meta.json         Maps sessionId → {agentMode, lastUpdated, projectPath}
+ *   │   └── memory/MEMORY.md           Persistent project memory
+ *   │
+ *   ├── plans/                         GLOBAL — not per-session
+ *   │   └── {slug}.md                  Plan files (linked to sessions via slug field)
+ *   │
+ *   ├── todos/
+ *   │   └── {sessionId}-agent-{sessionId}.json   Todo items per session
+ *   │
+ *   ├── tasks/{sessionId}/             Only exists if TaskCreate was used
+ *   │   ├── .lock
+ *   │   └── .highwatermark             Task ID counter
+ *   │
+ *   ├── file-history/{sessionId}/      Versioned backups of edited files
+ *   │   └── {hash}@v{N}               e.g., 65c16cbbfa80f250@v3
+ *   │
+ *   ├── debug/                         Debug logs
+ *   ├── shell-snapshots/               Terminal snapshots
+ *   ├── paste-cache/                   Paste history
+ *   └── statsig/                       Analytics
+ *
+ *
+ * ── GIVEN A SESSION ID, HOW TO FIND EVERYTHING ─────────────────────────────
+ *
+ * You need TWO inputs: sessionId + projectDir (the working directory).
+ * From those, everything is deterministic:
+ *
+ *   projectSlug = projectDir.replace(/\//g, '-')
+ *   base        = {claudeDir}/projects/{projectSlug}
+ *
+ *   RELIABLE (deterministic paths):
+ *   ┌──────────────────┬────────────────────────────────────────────────────────┐
+ *   │ Artifact         │ Path                                                   │
+ *   ├──────────────────┼────────────────────────────────────────────────────────┤
+ *   │ Conversation     │ {base}/{sessionId}.jsonl                  (always)     │
+ *   │ Sub-agents       │ {base}/{sessionId}/subagents/agent-*.jsonl (glob)      │
+ *   │ Tool result cache│ {base}/{sessionId}/tool-results/*.txt      (glob)      │
+ *   │ Todos            │ {claudeDir}/todos/{sessionId}-agent-{sessionId}.json   │
+ *   │ Tasks            │ {claudeDir}/tasks/{sessionId}/         (may not exist) │
+ *   │ File history     │ {claudeDir}/file-history/{sessionId}/  (may not exist) │
+ *   └──────────────────┴────────────────────────────────────────────────────────┘
+ *
+ *   UNRELIABLE (requires JSONL parsing):
+ *   ┌──────────────────┬────────────────────────────────────────────────────────┐
+ *   │ Plan file        │ Read JSONL → extract `slug` field →                    │
+ *   │                  │ {claudeDir}/plans/{slug}.md                            │
+ *   │                  │ ⚠ Slug is NOT unique per session (10+ sessions can     │
+ *   │                  │   share the same slug). Slug is sometimes null.        │
+ *   │                  │ Fallback: search JSONL for Write tool calls targeting  │
+ *   │                  │ ~/.claude/plans/*.md to find the actual plan file.     │
+ *   ├──────────────────┼────────────────────────────────────────────────────────┤
+ *   │ Session metadata │ {base}/.session-meta.json                              │
+ *   │                  │ ⚠ May be in a DIFFERENT project slug if the agent's   │
+ *   │                  │   cwd differs from the project root (e.g., running    │
+ *   │                  │   from /project/agent/ puts metadata in               │
+ *   │                  │   -project-agent/ not -project/).                     │
+ *   └──────────────────┴────────────────────────────────────────────────────────┘
+ *
+ *
+ * ── JSONL LINE SHAPES (each line is one JSON object) ───────────────────────
+ *
+ * type: "file-history-snapshot"  (usually line 1)
+ *   { type, messageId, snapshot: { trackedFileBackups: { [path]: { backupFileName, version } }, timestamp } }
+ *
+ * type: "user" (user message)
+ *   { type: "user", sessionId, slug, cwd, version, gitBranch, uuid, parentUuid, timestamp,
+ *     message: { role: "user", content: [{ type: "text", text: "..." }] } }
+ *
+ * type: "user" (tool_result — SDK wraps results in a user message)
+ *   { type: "user", uuid, parentUuid, timestamp,
+ *     message: { role: "user", content: [{ type: "tool_result", tool_use_id, content: "FULL output" }] },
+ *     toolUseResult: { type: "text", file?: { filePath, content: "FULL FILE CONTENT" } } }
+ *
+ * type: "assistant" (with thinking + tool_use)
+ *   { type: "assistant", sessionId, uuid, parentUuid, timestamp, requestId,
+ *     message: { model, id, role: "assistant",
+ *       content: [
+ *         { type: "thinking", thinking: "full reasoning..." },
+ *         { type: "text", text: "visible response" },
+ *         { type: "tool_use", id, name, input: {...} }
+ *       ],
+ *       usage: { input_tokens, cache_creation_input_tokens, cache_read_input_tokens, output_tokens }
+ *     } }
+ *
+ * type: "progress" (hook events)
+ *   { type: "progress", parentUuid, parentToolUseID, toolUseID, timestamp,
+ *     data: { type: "hook_progress", hookEvent, hookName, command } }
+ *
+ *
+ * ── HOW ARTIFACTS RELATE TO EACH OTHER ─────────────────────────────────────
+ *
+ * Messages link via parentUuid chain (forms a linked list of the conversation).
+ *
+ * Sub-agents: Parent session sees Task tool_use + tool_result.
+ *   The sub-agent's FULL work is in its own JSONL file under subagents/.
+ *   The "queue-operation" events in the main JSONL map task_id to sub-agent filenames.
+ *
+ * Tool result cache: When a tool result exceeds the inline threshold, the SDK
+ *   stores the full output in {sessionId}/tool-results/{hash}.txt and references
+ *   it from the JSONL. The JSONL tool_result content may be truncated while the
+ *   .txt file has the full content.
+ *
+ * Plans: Stored GLOBALLY in {claudeDir}/plans/{slug}.md — NOT per-session.
+ *   The "slug" field in JSONL events is the link. Multiple sessions can share
+ *   the same slug. A session's plan is found by: read JSONL → find slug → open
+ *   plans/{slug}.md. If slug is null, search for Write calls to plans/*.md.
+ *
+ * Todos: One file per session-agent pair. May be empty [].
+ *   Path is deterministic from sessionId alone.
+ *
+ * File history: Versioned backups of files the agent edited during the session.
+ *   Only exists if Write/Edit tools were used.
+ *
+ * Session metadata (.session-meta.json): A SINGLE file per project slug that
+ *   maps ALL session IDs → { agentMode, editMode, lastUpdated, projectPath }.
+ *   Careful: the cwd when the agent ran determines which project slug folder
+ *   the metadata ends up in.
+ *
+ *
+ * ── KEY FACTS FOR BUILDING NEW FUNCTIONS ───────────────────────────────────
+ *
+ * 1. JSONL content is FULL and UNTRUNCATED — complete file reads, bash outputs,
+ *    web search results, thinking blocks, assistant reasoning. No caps.
+ *
+ * 2. The SDK and CLI share the SAME storage. Sessions created by the SDK can
+ *    be resumed via CLI and vice versa.
+ *
+ * 3. Storage location is controlled ONLY by CLAUDE_CONFIG_DIR env var + the
+ *    project path slug derived from cwd. There is no sessionDir or outputPath
+ *    option in the SDK.
+ *
+ * 4. JSONL files are written INCREMENTALLY by the SDK — new lines are appended.
+ *    This enables the watchSessionFile() pattern for real-time tailing.
+ *
+ * 5. All functions accept SessionAccessOptions with optional claudeDir to
+ *    override the default path resolution.
+ *
+ * 6. The projectSlug encoding is simple: replace all "/" with "-".
+ *    /Users/newupgrade/Desktop/Developer/osborn → -Users-newupgrade-Desktop-Developer-osborn
+ *
+ * ═══════════════════════════════════════════════════════════════════════════════
+ */
+import { watch } from 'fs';
+export interface SessionPaths {
+    /** Main conversation JSONL file */
+    conversation: string;
+    /** Directory containing subagents/ and tool-results/ */
+    sessionDir: string;
+    /** Sub-agent JSONL files (may be empty) */
+    subagents: string[];
+    /** Large tool result cache files (may be empty) */
+    toolResults: string[];
+    /** Todos JSON file */
+    todos: string;
+    /** Tasks directory (may not exist) */
+    tasks: string;
+    /** File history directory (may not exist) */
+    fileHistory: string;
+    /** Debug log file (may not exist) */
+    debugLog: string;
+    /** Whether the main conversation file exists */
+    exists: boolean;
+}
+export interface SessionMessage {
+    type: 'user' | 'assistant' | 'tool_use' | 'tool_result' | 'progress' | 'file-history-snapshot' | 'other';
+    timestamp?: string;
+    uuid?: string;
+    parentUuid?: string | null;
+    sessionId?: string;
+    slug?: string;
+    role?: string;
+    text?: string;
+    toolName?: string;
+    toolId?: string;
+    toolInput?: Record<string, any>;
+    toolUseId?: string;
+    toolResultContent?: string;
+    toolUseResult?: any;
+    raw: any;
+}
+export interface SubagentInfo {
+    taskId: string;
+    filePath: string;
+    fileSize: number;
+    messages: SessionMessage[];
+}
+export interface SessionPlanInfo {
+    slug: string;
+    planPath: string;
+    content: string;
+    exists: boolean;
+}
+export interface ToolResultEntry {
+    toolName: string;
+    toolId: string;
+    toolInput: Record<string, any>;
+    resultContent: string;
+    toolUseResult?: any;
+    timestamp?: string;
+}
+/** Options passed to most functions — allows custom claude dir */
+export interface SessionAccessOptions {
+    /** Override the claude directory (default: CLAUDE_CONFIG_DIR env or ~/.claude) */
+    claudeDir?: string;
+}
+/** Main agent transcript + all sub-agent transcripts in one object */
+export interface SessionTranscripts {
+    /** The main session conversation (the agent itself) */
+    agent: {
+        sessionId: string;
+        filePath: string;
+        fileSize: number;
+        messages: SessionMessage[];
+        rawLines: any[];
+    };
+    /** All sub-agent conversations spawned via Task tool */
+    subagents: SubagentInfo[];
+}
+/**
+ * Resolve all artifact paths for a session.
+ * Does NOT read any files — just computes paths and checks existence.
+ *
+ * @param sessionId - The session UUID
+ * @param projectDir - The project working directory (e.g., /Users/.../osborn)
+ * @param opts.claudeDir - Override the claude directory path
+ */
+export declare function getSessionPaths(sessionId: string, projectDir: string, opts?: SessionAccessOptions): SessionPaths;
+/**
+ * Read raw JSON objects from a JSONL file — no parsing into SessionMessage.
+ * Returns the actual JSON as-is so you can inspect the full object shapes.
+ */
+export declare function readRawJsonl(filePath: string): any[];
+/**
+ * Read the full conversation history from a session.
+ * Returns structured messages in chronological order.
+ *
+ * @param sessionId - The session UUID
+ * @param projectDir - The project working directory (e.g., /Users/.../osborn)
+ * @param opts.lastN - Only return the last N messages (default: all)
+ * @param opts.types - Filter by message type (default: all types)
+ * @param opts.claudeDir - Override the claude directory path
+ */
+export declare function readSessionHistory(sessionId: string, projectDir: string, opts?: {
+    lastN?: number;
+    types?: SessionMessage['type'][];
+    claudeDir?: string;
+}): SessionMessage[];
+/**
+ * Get sub-agent transcripts for a session.
+ * Each sub-agent has its own JSONL file with a full conversation.
+ */
+export declare function getSubagentTranscripts(sessionId: string, projectDir: string, opts?: SessionAccessOptions): SubagentInfo[];
+/**
+ * Get the raw JSON objects from the main session JSONL file.
+ * Returns the actual JSON as written by the SDK — no transformation.
+ * Use this when you need the full object shapes for inspection.
+ *
+ * @param lastN - Only return the last N lines (default: all)
+ */
+export declare function getRawSessionJsonl(sessionId: string, projectDir: string, opts?: SessionAccessOptions & {
+    lastN?: number;
+}): any[];
+/**
+ * Get the main agent transcript AND all sub-agent transcripts together.
+ * This is the primary function for accessing what Claude is doing —
+ * the agent's own conversation plus every sub-agent it spawned.
+ *
+ * The agent transcript contains: user messages, assistant reasoning,
+ * tool_use calls, tool_result responses, thinking blocks, progress events.
+ *
+ * Sub-agent transcripts contain the same structure but for each Task
+ * tool invocation (Explore agents, Plan agents, etc.).
+ */
+export declare function getSessionTranscripts(sessionId: string, projectDir: string, opts?: SessionAccessOptions): SessionTranscripts;
+/**
+ * Find the plan file associated with a session.
+ * Plans are linked via the `slug` field in JSONL events.
+ *
+ * Falls back to searching for Write tool calls targeting ~/.claude/plans/
+ * if slug is not found.
+ */
+export declare function getSessionPlan(sessionId: string, projectDir: string, opts?: SessionAccessOptions): SessionPlanInfo | null;
+/**
+ * Get recent tool use/result pairs from a session.
+ * Returns matched pairs of (tool_use → tool_result) in chronological order.
+ *
+ * @param lastN - Number of recent pairs to return (default: 10, 0 = all)
+ * @param opts.toolNameFilter - Optional: only return results from these tool names (e.g., ['Read', 'WebSearch'])
+ */
+export declare function getRecentToolResults(sessionId: string, projectDir: string, lastN?: number, opts?: SessionAccessOptions & {
+    toolNameFilter?: string[];
+}): ToolResultEntry[];
+/**
+ * Watch a session JSONL file for new entries.
+ * Calls back with each new parsed entry as it's appended.
+ *
+ * Returns the fs.FSWatcher (call .close() to stop watching).
+ */
+export declare function watchSessionFile(sessionId: string, projectDir: string, callback: (entry: SessionMessage) => void, opts?: SessionAccessOptions): ReturnType<typeof watch> | null;
+/**
+ * Get the session slug (human-readable name) from a session.
+ */
+export declare function getSessionSlug(sessionId: string, projectDir: string, opts?: SessionAccessOptions): string | null;
+/**
+ * Get todos for a session.
+ */
+export declare function getSessionTodos(sessionId: string, opts?: SessionAccessOptions): any[];
+/**
+ * Get the text-only conversation (user messages + assistant text responses).
+ * Useful for building context for the fast brain.
+ *
+ * @param lastN - Number of exchanges to return
+ * @param maxCharsPerMessage - Max chars per message (0 = no limit)
+ */
+export declare function getConversationText(sessionId: string, projectDir: string, lastN?: number, maxCharsPerMessage?: number, opts?: SessionAccessOptions): {
+    role: string;
+    text: string;
+}[];
+/**
+ * Search the session JSONL for entries matching a keyword (case-insensitive).
+ * Searches across text, toolResultContent, toolName, and toolInput.
+ * Returns matching entries with 500-char excerpts around the match.
+ *
+ * @param keyword - The search keyword (case-insensitive)
+ * @param opts.maxResults - Maximum number of results to return (default: 20)
+ */
+export declare function searchSessionJsonl(sessionId: string, projectDir: string, keyword: string, opts?: SessionAccessOptions & {
+    maxResults?: number;
+}): {
+    type: string;
+    text: string;
+    timestamp?: string;
+}[];
+/**
+ * Get session stats: message counts, tool usage breakdown, data sizes.
+ * Helps the fast brain decide how much data to read and which tools to query.
+ */
+export declare function getSessionStats(sessionId: string, projectDir: string, opts?: SessionAccessOptions): {
+    totalMessages: number;
+    userMessages: number;
+    assistantMessages: number;
+    toolUseCount: number;
+    toolResultCount: number;
+    toolBreakdown: Record<string, number>;
+    subagentCount: number;
+    fileSizeBytes: number;
+    firstTimestamp?: string;
+    lastTimestamp?: string;
+} | null;
+/**
+ * Get a quick summary of a session: slug, message count, timestamps, tools used.
+ */
+export declare function getSessionSummary(sessionId: string, projectDir: string, opts?: SessionAccessOptions): {
+    sessionId: string;
+    slug: string;
+    messageCount: number;
+    userMessages: number;
+    assistantMessages: number;
+    toolUseCount: number;
+    uniqueTools: string[];
+    subagentCount: number;
+    firstTimestamp: string;
+    lastTimestamp: string;
+    fileSize: number;
+};