@herdctl/core 5.5.0 → 5.7.0

package/dist/state/jsonl-parser.js

@@ -0,0 +1,437 @@
+/**
+ * JSONL session file parser
+ *
+ * Parses Claude Code `.jsonl` session files into structured ChatMessage arrays
+ * for the web frontend. Supports streaming parsing for memory efficiency,
+ * message deduplication, tool call/result pairing, and metadata extraction.
+ */
+import { createReadStream } from "node:fs";
+import { createInterface } from "node:readline";
+import { extractToolResults, extractToolUseBlocks, getToolInputSummary, } from "./tool-parsing.js";
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Extract text content from a message's content field.
+ *
+ * Content can be a plain string or an array of content blocks.
+ * For arrays, text blocks are filtered and joined with newlines.
+ */
+function extractTextContent(content) {
+    if (typeof content === "string") {
+        return content;
+    }
+    if (Array.isArray(content)) {
+        const textParts = [];
+        for (const block of content) {
+            if (block &&
+                typeof block === "object" &&
+                "type" in block &&
+                block.type === "text" &&
+                "text" in block &&
+                typeof block.text === "string") {
+                textParts.push(block.text);
+            }
+        }
+        return textParts.join("\n");
+    }
+    return "";
+}
+/**
+ * Check whether a message's content contains tool_result blocks
+ */
+function hasToolResultBlocks(content) {
+    if (!Array.isArray(content))
+        return false;
+    return content.some((block) => block && typeof block === "object" && "type" in block && block.type === "tool_result");
+}
+/**
+ * Create a readline interface that streams a JSONL file line by line.
+ *
+ * Returns null if the file cannot be opened (e.g., ENOENT).
+ */
+function createLineReader(filePath) {
+    return new Promise((resolve) => {
+        const stream = createReadStream(filePath, { encoding: "utf-8" });
+        stream.on("error", () => {
+            resolve(null);
+        });
+        stream.on("open", () => {
+            const rl = createInterface({ input: stream, crlfDelay: Infinity });
+            resolve(rl);
+        });
+    });
+}
+// =============================================================================
+// parseSessionMessages
+// =============================================================================
+/**
+ * Parse a JSONL session file into an array of ChatMessages.
+ *
+ * Streams the file line by line for memory efficiency. Handles:
+ * - Plain user text messages
+ * - Assistant text messages (deduplicated by message.id)
+ * - Tool use blocks from assistant messages (stored as pending)
+ * - Tool result blocks from user messages (paired with pending tool uses)
+ *
+ * @param sessionFilePath - Absolute path to the .jsonl file
+ * @param options - Optional settings (limit caps total messages returned)
+ * @returns Array of ChatMessages in chronological order
+ */
+export async function parseSessionMessages(sessionFilePath, options) {
+    const rl = await createLineReader(sessionFilePath);
+    if (!rl)
+        return [];
+    const messages = [];
+    const seenAssistantIds = new Set();
+    const pendingToolUses = new Map();
+    const limit = options?.limit;
+    for await (const line of rl) {
+        // Respect message limit
+        if (limit !== undefined && messages.length >= limit)
+            break;
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            continue; // Skip malformed lines
+        }
+        const type = parsed.type;
+        if (type !== "user" && type !== "assistant")
+            continue;
+        const message = parsed.message;
+        if (!message)
+            continue;
+        const timestamp = typeof parsed.timestamp === "string" ? parsed.timestamp : new Date().toISOString();
+        // ── User messages ──────────────────────────────────────────────────
+        if (type === "user") {
+            const content = message.content;
+            // Tool result message
+            if (hasToolResultBlocks(content)) {
+                const toolResults = extractToolResults(parsed);
+                for (const result of toolResults) {
+                    if (limit !== undefined && messages.length >= limit)
+                        break;
+                    const pending = result.toolUseId ? pendingToolUses.get(result.toolUseId) : undefined;
+                    const toolName = pending?.name ?? "unknown";
+                    const inputSummary = pending
+                        ? getToolInputSummary(pending.name, pending.input)
+                        : undefined;
+                    // Calculate duration if we have timestamps
+                    let durationMs;
+                    if (pending) {
+                        const startMs = new Date(pending.timestamp).getTime();
+                        const endMs = new Date(timestamp).getTime();
+                        if (!Number.isNaN(startMs) && !Number.isNaN(endMs) && endMs >= startMs) {
+                            durationMs = endMs - startMs;
+                        }
+                    }
+                    messages.push({
+                        role: "tool",
+                        content: result.output,
+                        timestamp,
+                        toolCall: {
+                            toolName,
+                            inputSummary,
+                            output: result.output,
+                            isError: result.isError,
+                            durationMs,
+                        },
+                    });
+                    // Clean up matched pending tool use
+                    if (result.toolUseId) {
+                        pendingToolUses.delete(result.toolUseId);
+                    }
+                }
+                continue;
+            }
+            // Plain text user message
+            const text = extractTextContent(content);
+            if (text.length > 0) {
+                messages.push({ role: "user", content: text, timestamp });
+            }
+            continue;
+        }
+        // ── Assistant messages ──────────────────────────────────────────────
+        if (type === "assistant") {
+            const messageId = typeof message.id === "string" ? message.id : undefined;
+            // Deduplicate by message ID
+            if (messageId) {
+                if (seenAssistantIds.has(messageId))
+                    continue;
+                seenAssistantIds.add(messageId);
+            }
+            const content = message.content;
+            // Simple string content
+            if (typeof content === "string") {
+                if (content.length > 0) {
+                    messages.push({ role: "assistant", content, timestamp });
+                }
+                continue;
+            }
+            // Array of content blocks
+            if (Array.isArray(content)) {
+                // Extract text from text blocks
+                const text = extractTextContent(content);
+                // Extract tool_use blocks and store as pending
+                const toolUseBlocks = extractToolUseBlocks(parsed);
+                for (const block of toolUseBlocks) {
+                    if (block.id) {
+                        pendingToolUses.set(block.id, {
+                            name: block.name,
+                            input: block.input,
+                            timestamp,
+                        });
+                    }
+                }
+                // Create assistant message for text content
+                if (text.length > 0 && (limit === undefined || messages.length < limit)) {
+                    messages.push({ role: "assistant", content: text, timestamp });
+                }
+            }
+        }
+    }
+    return messages;
+}
+// =============================================================================
+// extractSessionMetadata
+// =============================================================================
+/**
+ * Extract summary metadata from a JSONL session file.
+ *
+ * Streams the entire file to count messages and find timestamp bounds,
+ * but captures metadata fields from only the first relevant messages.
+ *
+ * @param sessionFilePath - Absolute path to the .jsonl file
+ * @returns Session metadata with counts and previews
+ */
+export async function extractSessionMetadata(sessionFilePath) {
+    const rl = await createLineReader(sessionFilePath);
+    const metadata = {
+        sessionId: "",
+        firstMessagePreview: undefined,
+        gitBranch: undefined,
+        claudeCodeVersion: undefined,
+        messageCount: 0,
+        firstMessageAt: undefined,
+        lastMessageAt: undefined,
+        summary: undefined,
+        isSidechain: false,
+    };
+    if (!rl)
+        return metadata;
+    const seenAssistantIds = new Set();
+    let foundFirstUser = false;
+    for await (const line of rl) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        const type = parsed.type;
+        // Track summary entries (type: "summary" with top-level summary field)
+        if (type === "summary" && typeof parsed.summary === "string") {
+            metadata.summary = parsed.summary;
+            continue;
+        }
+        if (type !== "user" && type !== "assistant")
+            continue;
+        const timestamp = typeof parsed.timestamp === "string" ? parsed.timestamp : undefined;
+        // Track sessionId from first line that has it
+        if (metadata.sessionId === "" && typeof parsed.sessionId === "string") {
+            metadata.sessionId = parsed.sessionId;
+        }
+        // Track timestamp bounds
+        if (timestamp) {
+            if (metadata.firstMessageAt === undefined) {
+                metadata.firstMessageAt = timestamp;
+            }
+            metadata.lastMessageAt = timestamp;
+        }
+        if (type === "user") {
+            // Extract first-user-message-specific fields
+            if (!foundFirstUser) {
+                foundFirstUser = true;
+                if (parsed.isSidechain === true) {
+                    metadata.isSidechain = true;
+                }
+                if (typeof parsed.gitBranch === "string") {
+                    metadata.gitBranch = parsed.gitBranch;
+                }
+                if (typeof parsed.version === "string") {
+                    metadata.claudeCodeVersion = parsed.version;
+                }
+                const message = parsed.message;
+                if (message) {
+                    const content = message.content;
+                    // Only extract preview from plain text messages, not tool results
+                    if (!hasToolResultBlocks(content)) {
+                        const text = extractTextContent(content);
+                        if (text.length > 0) {
+                            metadata.firstMessagePreview =
+                                text.length > 100 ? `${text.substring(0, 100)}...` : text;
+                        }
+                    }
+                }
+            }
+            metadata.messageCount++;
+            continue;
+        }
+        if (type === "assistant") {
+            const message = parsed.message;
+            const messageId = message && typeof message.id === "string" ? message.id : undefined;
+            // Deduplicate assistant messages by ID
+            if (messageId) {
+                if (seenAssistantIds.has(messageId))
+                    continue;
+                seenAssistantIds.add(messageId);
+            }
+            metadata.messageCount++;
+        }
+    }
+    return metadata;
+}
+// =============================================================================
+// extractSessionUsage
+// =============================================================================
+/**
+ * Extract token usage data from a JSONL session file.
+ *
+ * Streams the file and tracks the last seen inputTokens value from
+ * assistant messages. The most recent value represents the current
+ * context window fill level (not cumulative across turns).
+ *
+ * @param sessionFilePath - Absolute path to the .jsonl file
+ * @returns Usage summary with input tokens, turn count, and data availability flag
+ */
+export async function extractSessionUsage(sessionFilePath) {
+    const rl = await createLineReader(sessionFilePath);
+    if (!rl) {
+        return { inputTokens: 0, turnCount: 0, hasData: false };
+    }
+    const seenIds = new Set();
+    let lastInputTokens = 0;
+    let hasData = false;
+    for await (const line of rl) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if (parsed.type !== "assistant")
+            continue;
+        const message = parsed.message;
+        if (!message)
+            continue;
+        // Deduplicate by message ID
+        const messageId = typeof message.id === "string" ? message.id : undefined;
+        if (messageId) {
+            if (seenIds.has(messageId))
+                continue;
+            seenIds.add(messageId);
+        }
+        // Extract usage
+        const usage = message.usage;
+        if (!usage)
+            continue;
+        hasData = true;
+        const inputTokens = typeof usage.input_tokens === "number" ? usage.input_tokens : 0;
+        const cacheCreation = typeof usage.cache_creation_input_tokens === "number" ? usage.cache_creation_input_tokens : 0;
+        const cacheRead = typeof usage.cache_read_input_tokens === "number" ? usage.cache_read_input_tokens : 0;
+        lastInputTokens = inputTokens + cacheCreation + cacheRead;
+    }
+    return {
+        inputTokens: lastInputTokens,
+        turnCount: seenIds.size,
+        hasData,
+    };
+}
+// =============================================================================
+// isSidechainSession
+// =============================================================================
+/**
+ * Check if a session file represents a sidechain (sub-agent) session.
+ *
+ * Claude Code sets `isSidechain: true` on the first JSONL entry when:
+ * - The session is a Task tool sub-agent (most common — prompt-cache warmups)
+ * - The `--resume` flag was used to start the session
+ *
+ * These sessions are typically noise (a single "Warmup" message + response)
+ * and are filtered out of UI-facing session discovery to avoid clutter.
+ *
+ * Reads only the first line of the JSONL file for efficiency — O(1) per file.
+ *
+ * @param sessionFilePath - Absolute path to the .jsonl file
+ * @returns true if the session is a sidechain session
+ */
+export async function isSidechainSession(sessionFilePath) {
+    const rl = await createLineReader(sessionFilePath);
+    if (!rl)
+        return false;
+    for await (const line of rl) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            rl.close();
+            return parsed.isSidechain === true;
+        }
+        catch {
+            rl.close();
+            return false;
+        }
+    }
+    return false;
+}
+// =============================================================================
+// extractLastSummary
+// =============================================================================
+/**
+ * Extract only the last summary from a JSONL session file.
+ *
+ * This is a lightweight alternative to extractSessionMetadata when only the
+ * auto-generated session name is needed. It streams the file and returns the
+ * last `summary` value from entries with `type: "summary"`.
+ *
+ * @param sessionFilePath - Absolute path to the .jsonl file
+ * @returns The last summary string, or undefined if none found
+ */
+export async function extractLastSummary(sessionFilePath) {
+    const rl = await createLineReader(sessionFilePath);
+    if (!rl)
+        return undefined;
+    let lastSummary;
+    for await (const line of rl) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        // Only process summary entries
+        if (parsed.type === "summary" && typeof parsed.summary === "string") {
+            lastSummary = parsed.summary;
+        }
+    }
+    return lastSummary;
+}
+//# sourceMappingURL=jsonl-parser.js.map

package/dist/state/jsonl-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonl-parser.js","sourceRoot":"","sources":["../../src/state/jsonl-parser.ts"],"names":[],"mappings":"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"}

package/dist/state/session-attribution.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Session attribution module
+ *
+ * Determines the origin of a Claude Code session (web, discord, slack, schedule, or native CLI)
+ * by cross-referencing HerdCTL's job metadata and platform session YAML files.
+ */
+export type SessionOrigin = "web" | "discord" | "slack" | "schedule" | "native";
+export interface SessionAttribution {
+    origin: SessionOrigin;
+    agentName: string | undefined;
+    triggerType: string | undefined;
+}
+export interface AttributionIndex {
+    /** Attribute a single session ID */
+    getAttribute(sessionId: string): SessionAttribution;
+    /** Batch attribute multiple session IDs */
+    getAttributes(sessionIds: string[]): Map<string, SessionAttribution>;
+    /** Number of entries in the index (for diagnostics) */
+    readonly size: number;
+}
+/**
+ * Build an attribution index from job metadata and platform YAML files
+ *
+ * @param stateDir - Path to the .herdctl state directory
+ * @returns An AttributionIndex for looking up session origins
+ *
+ * @example
+ * ```typescript
+ * const index = await buildAttributionIndex('/path/to/.herdctl');
+ * const attribution = index.getAttribute('session-123');
+ * console.log(attribution.origin); // 'discord'
+ * ```
+ */
+export declare function buildAttributionIndex(stateDir: string): Promise<AttributionIndex>;
+//# sourceMappingURL=session-attribution.d.ts.map

package/dist/state/session-attribution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-attribution.d.ts","sourceRoot":"","sources":["../../src/state/session-attribution.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAcH,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,SAAS,GAAG,OAAO,GAAG,UAAU,GAAG,QAAQ,CAAC;AAEhF,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,aAAa,CAAC;IACtB,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAED,MAAM,WAAW,gBAAgB;IAC/B,oCAAoC;IACpC,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,kBAAkB,CAAC;IACpD,2CAA2C;IAC3C,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IACrE,uDAAuD;IACvD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AA8ID;;;;;;;;;;;;GAYG;AACH,wBAAsB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAuDvF"}

package/dist/state/session-attribution.js

@@ -0,0 +1,179 @@
+/**
+ * Session attribution module
+ *
+ * Determines the origin of a Claude Code session (web, discord, slack, schedule, or native CLI)
+ * by cross-referencing HerdCTL's job metadata and platform session YAML files.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import yaml from "yaml";
+import { z } from "zod";
+import { createLogger } from "../utils/logger.js";
+import { listJobs } from "./job-metadata.js";
+// =============================================================================
+// Schemas
+// =============================================================================
+const PlatformSessionSchema = z.object({
+    version: z.union([z.literal(1), z.literal(2), z.literal(3)]),
+    agentName: z.string(),
+    channels: z.record(z.string(), z.object({
+        sessionId: z.string(),
+        lastMessageAt: z.string(),
+    })),
+});
+// =============================================================================
+// Logger
+// =============================================================================
+const logger = createLogger("SessionAttribution");
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Convert a trigger type to a session origin
+ */
+function triggerTypeToOrigin(triggerType) {
+    switch (triggerType) {
+        case "web":
+            return "web";
+        case "discord":
+            return "discord";
+        case "slack":
+            return "slack";
+        case "schedule":
+            return "schedule";
+        // manual, webhook, chat, fork — all treated as native CLI usage
+        default:
+            return "native";
+    }
+}
+/**
+ * Build the job index from job metadata files
+ */
+async function buildJobIndex(jobsDir) {
+    const index = new Map();
+    const result = await listJobs(jobsDir, {}, { logger });
+    for (const job of result.jobs) {
+        if (job.session_id) {
+            index.set(job.session_id, {
+                agent: job.agent,
+                triggerType: job.trigger_type,
+            });
+        }
+    }
+    return index;
+}
+/**
+ * Build the platform index from platform session YAML files
+ */
+async function buildPlatformIndex(stateDir) {
+    const index = new Map();
+    const platforms = ["discord", "slack", "web"];
+    for (const platform of platforms) {
+        const sessionDir = path.join(stateDir, `${platform}-sessions`);
+        let fileNames;
+        try {
+            fileNames = await fs.readdir(sessionDir);
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                logger.debug(`Session directory does not exist: ${sessionDir}`);
+                continue;
+            }
+            throw error;
+        }
+        const yamlFiles = fileNames.filter((name) => name.endsWith(".yaml"));
+        for (const fileName of yamlFiles) {
+            const filePath = path.join(sessionDir, fileName);
+            try {
+                const content = await fs.readFile(filePath, "utf-8");
+                const parsed = yaml.parse(content);
+                const validated = PlatformSessionSchema.safeParse(parsed);
+                if (!validated.success) {
+                    logger.warn(`Malformed platform session file: ${filePath}: ${validated.error.message}`);
+                    continue;
+                }
+                const session = validated.data;
+                for (const channel of Object.values(session.channels)) {
+                    index.set(channel.sessionId, {
+                        platform,
+                        agentName: session.agentName,
+                    });
+                }
+            }
+            catch (error) {
+                if (error instanceof yaml.YAMLParseError) {
+                    logger.warn(`Failed to parse YAML file: ${filePath}: ${error.message}`);
+                    continue;
+                }
+                throw error;
+            }
+        }
+    }
+    return index;
+}
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Build an attribution index from job metadata and platform YAML files
+ *
+ * @param stateDir - Path to the .herdctl state directory
+ * @returns An AttributionIndex for looking up session origins
+ *
+ * @example
+ * ```typescript
+ * const index = await buildAttributionIndex('/path/to/.herdctl');
+ * const attribution = index.getAttribute('session-123');
+ * console.log(attribution.origin); // 'discord'
+ * ```
+ */
+export async function buildAttributionIndex(stateDir) {
+    const jobsDir = path.join(stateDir, "jobs");
+    const [jobIndex, platformIndex] = await Promise.all([
+        buildJobIndex(jobsDir),
+        buildPlatformIndex(stateDir),
+    ]);
+    const getAttribute = (sessionId) => {
+        // Check job index first
+        const jobEntry = jobIndex.get(sessionId);
+        if (jobEntry) {
+            return {
+                origin: triggerTypeToOrigin(jobEntry.triggerType),
+                agentName: jobEntry.agent,
+                triggerType: jobEntry.triggerType,
+            };
+        }
+        // Check platform index
+        const platformEntry = platformIndex.get(sessionId);
+        if (platformEntry) {
+            return {
+                origin: platformEntry.platform,
+                agentName: platformEntry.agentName,
+                triggerType: undefined,
+            };
+        }
+        // Default to native
+        return {
+            origin: "native",
+            agentName: undefined,
+            triggerType: undefined,
+        };
+    };
+    const getAttributes = (sessionIds) => {
+        const result = new Map();
+        for (const sessionId of sessionIds) {
+            result.set(sessionId, getAttribute(sessionId));
+        }
+        return result;
+    };
+    // Calculate unique session IDs across both indexes
+    const allSessionIds = new Set([...jobIndex.keys(), ...platformIndex.keys()]);
+    return {
+        getAttribute,
+        getAttributes,
+        get size() {
+            return allSessionIds.size;
+        },
+    };
+}
+//# sourceMappingURL=session-attribution.js.map