spiracha 2.0.0 → 2.2.0

package/src/lib/grok-exporter-types.ts

@@ -0,0 +1,110 @@
+import os from 'node:os';
+import path from 'node:path';
+import type { ExportFormat, JsonValue } from './shared';
+
+export const getDefaultGrokHome = (_env: NodeJS.ProcessEnv = process.env, homeDir = os.homedir()): string => {
+    return path.join(homeDir, '.grok');
+};
+
+export const DEFAULT_GROK_HOME = getDefaultGrokHome();
+
+export const resolveGrokHome = (): string => {
+    const configured = process.env.SPIRACHA_GROK_HOME?.trim() || process.env.SPIRACHA_GROK_DIR?.trim();
+    return configured ? configured : DEFAULT_GROK_HOME;
+};
+
+export const resolveGrokSessionsDir = (): string => {
+    const configured = process.env.SPIRACHA_GROK_SESSIONS_DIR?.trim();
+    return configured ? configured : path.join(resolveGrokHome(), 'sessions');
+};
+
+export type GrokWorkspaceGroup = {
+    assistantMessageCount: number;
+    chatMessageCount: number;
+    directoryName: string;
+    key: string;
+    label: string;
+    lastActiveAtIso: string | null;
+    lastActiveAtMs: number | null;
+    messageCount: number;
+    reasoningCount: number;
+    sessionCount: number;
+    toolCallCount: number;
+    toolResultCount: number;
+    uri: string;
+    userMessageCount: number;
+    worktree: string;
+};
+
+export type GrokSessionSummary = {
+    agentName: string | null;
+    assistantMessageCount: number;
+    chatHistoryPath: string;
+    chatMessageCount: number;
+    createdAtIso: string | null;
+    createdAtMs: number | null;
+    currentModelId: string | null;
+    cwd: string | null;
+    gitBranch: string | null;
+    gitRemotes: string[];
+    gitRootDir: string | null;
+    headCommit: string | null;
+    lastActiveAtIso: string | null;
+    lastActiveAtMs: number | null;
+    messageCount: number;
+    modelLabel: string | null;
+    reasoningCount: number;
+    renderablePartCount: number;
+    sandboxProfile: string | null;
+    sessionDir: string;
+    sessionId: string;
+    summaryPath: string;
+    title: string;
+    toolCallCount: number;
+    toolResultCount: number;
+    updatesPath: string | null;
+    userMessageCount: number;
+    workspaceKey: string;
+    workspaceLabel: string;
+    worktree: string;
+};
+
+export type GrokPartType = 'reasoning' | 'text' | 'tool_call' | 'tool_result' | 'unknown';
+
+export type GrokTranscriptPart = {
+    argumentsText?: string | null;
+    outputText?: string | null;
+    partId: string;
+    raw: Record<string, JsonValue>;
+    text?: string;
+    toolCallId?: string | null;
+    toolName?: string | null;
+    type: GrokPartType;
+};
+
+export type GrokTranscriptEntry = {
+    createdAtMs: number | null;
+    entryId: string;
+    modelFingerprint?: string | null;
+    modelId?: string | null;
+    parts: GrokTranscriptPart[];
+    raw: Record<string, JsonValue>;
+    role: string;
+    timestamp: string | null;
+    type: string;
+};
+
+export type GrokSessionTranscript = {
+    entries: GrokTranscriptEntry[];
+    rawEvents: Record<string, JsonValue>[];
+    rawPayloadsOmitted?: boolean;
+    renderablePartCount: number;
+    session: GrokSessionSummary;
+};
+
+export type GrokExportOptions = {
+    includeCommentary: boolean;
+    includeMetadata: boolean;
+    includeTools: boolean;
+    outputFormat: ExportFormat;
+};

package/src/lib/grok-transcript-phase.ts

@@ -0,0 +1,61 @@
+import type { GrokTranscriptEntry, GrokTranscriptPart } from './grok-exporter-types';
+
+export type GrokAssistantMessagePhase = 'commentary' | 'final_answer' | null;
+
+const isGrokCommentaryEnvelope = (entry: GrokTranscriptEntry, part: GrokTranscriptPart): boolean => {
+    const text = part.text?.trim() ?? '';
+    return entry.role === 'system' || text.startsWith('<user_info>') || text.startsWith('<system-reminder>');
+};
+
+export const getFinalGrokAssistantTextPartIds = (entries: GrokTranscriptEntry[]): Set<string> => {
+    const finalPartIds = new Set<string>();
+    let latestAssistantTextPartId: string | null = null;
+
+    const flushAssistantRun = () => {
+        if (latestAssistantTextPartId) {
+            finalPartIds.add(latestAssistantTextPartId);
+            latestAssistantTextPartId = null;
+        }
+    };
+
+    for (const entry of entries) {
+        if (entry.role === 'user') {
+            flushAssistantRun();
+            continue;
+        }
+
+        if (entry.role !== 'assistant') {
+            continue;
+        }
+
+        for (const part of entry.parts) {
+            if (part.type === 'tool_call') {
+                latestAssistantTextPartId = null;
+                continue;
+            }
+
+            if (part.type === 'text' && part.text?.trim()) {
+                latestAssistantTextPartId = part.partId;
+            }
+        }
+    }
+
+    flushAssistantRun();
+    return finalPartIds;
+};
+
+export const getGrokTextPartPhase = (
+    entry: GrokTranscriptEntry,
+    part: GrokTranscriptPart,
+    finalTextPartIds: Set<string>,
+): GrokAssistantMessagePhase => {
+    if (isGrokCommentaryEnvelope(entry, part)) {
+        return 'commentary';
+    }
+
+    if (entry.role !== 'assistant') {
+        return null;
+    }
+
+    return finalTextPartIds.has(part.partId) ? 'final_answer' : 'commentary';
+};

package/src/lib/grok-transcript.ts

@@ -0,0 +1,167 @@
+import type {
+    GrokExportOptions,
+    GrokSessionSummary,
+    GrokSessionTranscript,
+    GrokTranscriptEntry,
+    GrokTranscriptPart,
+} from './grok-exporter-types';
+import { getFinalGrokAssistantTextPartIds, getGrokTextPartPhase } from './grok-transcript-phase';
+import {
+    cleanExtractedText,
+    cleanInlineTitle,
+    formatInlineLiteral,
+    type MetadataEntry,
+    renderCodeBlock,
+    renderDocumentTitle,
+    renderMetadataBlock,
+    renderSection,
+} from './shared';
+
+const TOOL_OUTPUT_PREVIEW_LIMIT = 4000;
+
+const getSessionTitle = (session: GrokSessionSummary): string => {
+    return cleanInlineTitle(session.title || session.sessionId);
+};
+
+const buildMetadataEntries = (session: GrokSessionSummary): MetadataEntry[] => [
+    { key: 'exported_from', value: 'grok_local_session' },
+    { key: 'session_id', value: session.sessionId },
+    { key: 'title', value: session.title },
+    { key: 'source_transcript_path', value: session.chatHistoryPath },
+    { key: 'workspace_key', value: session.workspaceKey },
+    { key: 'worktree', value: session.worktree },
+    { key: 'cwd', value: session.cwd },
+    { key: 'model', value: session.currentModelId },
+    { key: 'model_label', value: session.modelLabel },
+    { key: 'agent_name', value: session.agentName },
+    { key: 'git_branch', value: session.gitBranch },
+    { key: 'created_at_iso', value: session.createdAtIso },
+    { key: 'last_active_at_iso', value: session.lastActiveAtIso },
+    { key: 'message_count', value: session.messageCount },
+    { key: 'tool_call_count', value: session.toolCallCount },
+    { key: 'tool_result_count', value: session.toolResultCount },
+];
+
+const roleTitle = (role: string): string => {
+    if (role === 'assistant') {
+        return 'Assistant';
+    }
+
+    if (role === 'user') {
+        return 'User';
+    }
+
+    if (role === 'system') {
+        return 'System';
+    }
+
+    if (role === 'tool') {
+        return 'Tool';
+    }
+
+    return role ? cleanInlineTitle(role) : 'Message';
+};
+
+const truncateOutput = (text: string): string => {
+    if (text.length <= TOOL_OUTPUT_PREVIEW_LIMIT) {
+        return text;
+    }
+
+    return `${text.slice(0, TOOL_OUTPUT_PREVIEW_LIMIT)}\n... (truncated)`;
+};
+
+const renderTextPart = (entry: GrokTranscriptEntry, part: GrokTranscriptPart, options: GrokExportOptions): string => {
+    const text = cleanExtractedText(part.text ?? '').trim();
+    return text ? renderSection(roleTitle(entry.role), text, options.outputFormat) : '';
+};
+
+const renderReasoningPart = (part: GrokTranscriptPart, options: GrokExportOptions): string => {
+    if (!options.includeCommentary) {
+        return '';
+    }
+
+    const text = cleanExtractedText(part.text ?? '').trim();
+    return text ? renderSection('Reasoning', text, options.outputFormat) : '';
+};
+
+const renderToolCallPart = (part: GrokTranscriptPart, options: GrokExportOptions): string => {
+    if (!options.includeTools) {
+        return '';
+    }
+
+    const toolName = part.toolName ?? 'unknown';
+    const lines = [`Tool: ${formatInlineLiteral(toolName, options.outputFormat)}`];
+    if (part.toolCallId) {
+        lines.push(`Call ID: ${part.toolCallId}`);
+    }
+    if (part.argumentsText?.trim()) {
+        lines.push('', 'Input:', '', renderCodeBlock(part.argumentsText.trim(), options.outputFormat));
+    }
+
+    return renderSection('Tool Call', lines.join('\n'), options.outputFormat);
+};
+
+const renderToolResultPart = (part: GrokTranscriptPart, options: GrokExportOptions): string => {
+    if (!options.includeTools) {
+        return '';
+    }
+
+    const outputText = part.outputText?.trim();
+    if (!outputText) {
+        return '';
+    }
+
+    const lines: string[] = [];
+    if (part.toolCallId) {
+        lines.push(`Call ID: ${part.toolCallId}`, '');
+    }
+    lines.push(renderCodeBlock(truncateOutput(outputText), options.outputFormat));
+    return renderSection('Tool Output', lines.join('\n'), options.outputFormat);
+};
+
+const renderPart = (
+    entry: GrokTranscriptEntry,
+    part: GrokTranscriptPart,
+    options: GrokExportOptions,
+    finalAssistantTextPartIds: Set<string>,
+): string => {
+    switch (part.type) {
+        case 'text':
+            if (
+                getGrokTextPartPhase(entry, part, finalAssistantTextPartIds) === 'commentary' &&
+                !options.includeCommentary
+            ) {
+                return '';
+            }
+            return renderTextPart(entry, part, options);
+        case 'reasoning':
+            return renderReasoningPart(part, options);
+        case 'tool_call':
+            return renderToolCallPart(part, options);
+        case 'tool_result':
+            return renderToolResultPart(part, options);
+        case 'unknown':
+            return '';
+    }
+};
+
+export const renderGrokTranscript = (transcript: GrokSessionTranscript, options: GrokExportOptions): string | null => {
+    const finalAssistantTextPartIds = getFinalGrokAssistantTextPartIds(transcript.entries);
+    const sections = transcript.entries.flatMap((entry) =>
+        entry.parts.map((part) => renderPart(entry, part, options, finalAssistantTextPartIds)).filter(Boolean),
+    );
+    if (sections.length === 0) {
+        return null;
+    }
+
+    const parts = [
+        renderDocumentTitle(getSessionTitle(transcript.session), options.outputFormat),
+        '',
+        options.includeMetadata
+            ? renderMetadataBlock(buildMetadataEntries(transcript.session), options.outputFormat)
+            : '',
+        ...sections,
+    ].filter(Boolean);
+
+    return `${parts.join('\n').trimEnd()}\n`;
+};

package/src/lib/kiro-db.ts

@@ -1,7 +1,7 @@
-import { createHash } from 'node:crypto';
-import { readdir, stat } from 'node:fs/promises';
+import { createHash, randomUUID } from 'node:crypto';
+import { readdir, rename, rm, stat } from 'node:fs/promises';
 import path from 'node:path';
-import { mapWithConcurrency } from './concurrency';
+import { createConcurrencyLimiter, mapWithConcurrency } from './concurrency';
 import {
     getDefaultKiroDataDir,
     type KiroSessionSummary,
@@ -11,21 +11,26 @@ import {
     type KiroWorkspaceGroup,
     resolveKiroWorkspaceSessionsDir,
 } from './kiro-exporter-types';
+import { getPortablePathBasename } from './portable-path';
 import {
     asObject,
     asString,
     cleanExtractedText,
     cleanInlineTitle,
-    getPortablePathBasename,
     isWorkspacePathQuery,
     type JsonValue,
+    readDirectoryEntriesIfExists,
     workspacePathMatchesQuery,
 } from './shared';
 
 export { getDefaultKiroDataDir, resolveKiroWorkspaceSessionsDir };
 
 const READ_CONCURRENCY = 8;
+const DELETE_CONCURRENCY = 1;
+const EXECUTION_CACHE_TTL_MS = 1_000;
 const WORKSPACE_KEY_PREFIX = 'workspace:';
+const kiroDeleteLimiter = createConcurrencyLimiter(DELETE_CONCURRENCY);
+const executionFilesCache = new Map<string, { expiresAtMs: number; files: KiroExecutionFile[] }>();
 
 type KiroSessionIndexEntry = {
     createdAtMs: number | null;
@@ -45,6 +50,11 @@ type KiroExecutionFile = {
     raw: Record<string, JsonValue>;
 };
 
+export type DeleteKiroSessionResult = {
+    deletedFiles: string[];
+    deletedSessionIds: string[];
+};
+
 type ReadSessionFileOptions = {
     includeExecutions?: boolean;
     sessionsDir: string;
@@ -82,19 +92,23 @@ const toIso = (value: number | null): string | null => {
     return value === null ? null : new Date(value).toISOString();
 };
 
+const parseTimestampStringMs = (value: string): number | null => {
+    const numeric = Number(value);
+    if (Number.isFinite(numeric)) {
+        return numeric > 0 && numeric < 10_000_000_000 ? numeric * 1000 : numeric;
+    }
+
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : null;
+};
+
 const parseTimestampMs = (value: JsonValue | undefined): number | null => {
     if (typeof value === 'number' && Number.isFinite(value)) {
         return value > 0 && value < 10_000_000_000 ? value * 1000 : value;
     }
 
     if (typeof value === 'string') {
-        const numeric = Number(value);
-        if (Number.isFinite(numeric)) {
-            return numeric > 0 && numeric < 10_000_000_000 ? numeric * 1000 : numeric;
-        }
-
-        const parsed = Date.parse(value);
-        return Number.isFinite(parsed) ? parsed : null;
+        return value.trim() ? parseTimestampStringMs(value) : null;
     }
 
     return null;
@@ -283,7 +297,9 @@ const parseHistoryEntry = (raw: Record<string, JsonValue>, index: number): KiroT
         promptLogCount: getPromptLogCount(raw),
         raw,
         role: asString(message.role ?? null) ?? 'message',
-        timestamp: null,
+        timestamp: toIso(
+            parseTimestampMs(raw.timestamp ?? raw.createdAt ?? raw.created_at ?? message.timestamp ?? null),
+        ),
     };
 };
 
@@ -439,7 +455,7 @@ const getKiroWorkspaceHash = (workspacePath: string): string => {
 };
 
 const listFilesRecursively = async (root: string, maxDepth = 3): Promise<string[]> => {
-    const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
+    const entries = await readDirectoryEntriesIfExists(root);
     const files: string[] = [];
 
     for (const entry of entries) {
@@ -467,18 +483,31 @@ const listExecutionFilesForSession = async (
         return [];
     }
 
-    const files = await listFilesRecursively(workspaceExecutionRoot);
-    const executions = await mapWithConcurrency(files, READ_CONCURRENCY, async (filePath) => {
-        const raw = await readJsonObject(filePath);
-        return asString(raw?.chatSessionId ?? null) === sessionId && raw ? { filePath, raw } : null;
-    });
+    const cached = executionFilesCache.get(workspaceExecutionRoot);
+    let executions = cached && cached.expiresAtMs > Date.now() ? cached.files : null;
+    if (!executions) {
+        const files = await listFilesRecursively(workspaceExecutionRoot);
+        executions = (
+            await mapWithConcurrency(files, READ_CONCURRENCY, async (filePath) => {
+                const raw = await readJsonObject(filePath);
+                return raw ? { filePath, raw } : null;
+            })
+        ).flatMap((execution) => (execution ? [execution] : []));
+        executionFilesCache.set(workspaceExecutionRoot, {
+            expiresAtMs: Date.now() + EXECUTION_CACHE_TTL_MS,
+            files: executions,
+        });
+    }
 
-    return executions.flatMap((execution) => (execution ? [execution] : []));
+    return executions.filter((execution) => asString(execution.raw.chatSessionId ?? null) === sessionId);
 };
 
 const getActionTimestamp = (action: Record<string, JsonValue>, execution: Record<string, JsonValue>): string | null => {
     return toIso(
-        parseTimestampMs(action.emittedAt) ?? parseTimestampMs(action.endTime) ?? parseTimestampMs(execution.endTime),
+        parseTimestampMs(action.emittedAt) ??
+            parseTimestampMs(action.endTime) ??
+            parseTimestampMs(execution.endTime) ??
+            parseTimestampMs(execution.startTime),
     );
 };
 
@@ -589,6 +618,7 @@ const parseExecutionActionMessageEntry = (
         raw: {
             ...action,
             executionFilePath: execution.filePath,
+            executionStartTime: execution.raw.startTime ?? null,
         },
         role: 'assistant',
         timestamp: getActionTimestamp(action, execution.raw),
@@ -628,6 +658,7 @@ const parseExecutionActionToolEntry = (
         raw: {
             ...action,
             executionFilePath: execution.filePath,
+            executionStartTime: execution.raw.startTime ?? null,
         },
         role: 'tool',
         timestamp: getActionTimestamp(action, execution.raw),
@@ -673,43 +704,87 @@ const readExecutionEntries = async (
     return executions.sort(compareExecutionFiles).flatMap(parseExecutionEntries);
 };
 
-const getVisibleEntries = (
-    historyEntries: KiroTranscriptEntry[],
-    executionEntries: KiroTranscriptEntry[],
-): KiroTranscriptEntry[] => {
-    if (executionEntries.length === 0) {
-        return historyEntries;
-    }
-
-    const executionEntriesById = new Map<string, KiroTranscriptEntry[]>();
+const groupExecutionEntriesById = (executionEntries: KiroTranscriptEntry[]) => {
+    const entriesById = new Map<string, KiroTranscriptEntry[]>();
     for (const entry of executionEntries) {
         if (!entry.executionId) {
             continue;
         }
 
-        const entries = executionEntriesById.get(entry.executionId) ?? [];
+        const entries = entriesById.get(entry.executionId) ?? [];
         entries.push(entry);
-        executionEntriesById.set(entry.executionId, entries);
+        entriesById.set(entry.executionId, entries);
     }
+    return entriesById;
+};
 
+const replaceExecutionPlaceholders = (
+    historyEntries: KiroTranscriptEntry[],
+    executionEntriesById: Map<string, KiroTranscriptEntry[]>,
+) => {
     const usedExecutionIds = new Set<string>();
     const visibleEntries: KiroTranscriptEntry[] = [];
     for (const entry of historyEntries) {
         const matchingExecutionEntries = entry.executionId ? executionEntriesById.get(entry.executionId) : undefined;
-        if (isAssistantPlaceholderEntry(entry)) {
-            if (matchingExecutionEntries) {
-                visibleEntries.push(...matchingExecutionEntries);
-                usedExecutionIds.add(entry.executionId!);
-            }
+        if (!isAssistantPlaceholderEntry(entry) || !matchingExecutionEntries) {
+            visibleEntries.push(entry);
             continue;
         }
 
-        visibleEntries.push(entry);
+        visibleEntries.push(...matchingExecutionEntries);
+        usedExecutionIds.add(entry.executionId!);
     }
+    return { usedExecutionIds, visibleEntries };
+};
 
-    visibleEntries.push(
-        ...executionEntries.filter((entry) => !entry.executionId || !usedExecutionIds.has(entry.executionId)),
-    );
+const groupUnmatchedExecutionEntries = (executionEntries: KiroTranscriptEntry[], usedExecutionIds: Set<string>) => {
+    const groups = new Map<string, KiroTranscriptEntry[]>();
+    for (const entry of executionEntries) {
+        if (entry.executionId && usedExecutionIds.has(entry.executionId)) {
+            continue;
+        }
+
+        const groupKey = entry.executionId ?? asString(entry.raw.executionFilePath ?? null) ?? entry.entryId;
+        const group = groups.get(groupKey) ?? [];
+        group.push(entry);
+        groups.set(groupKey, group);
+    }
+    return groups.values();
+};
+
+const insertExecutionGroupByStartTime = (
+    visibleEntries: KiroTranscriptEntry[],
+    executionGroup: KiroTranscriptEntry[],
+) => {
+    const firstEntry = executionGroup[0]!;
+    const executionTime = parseTimestampMs(firstEntry.raw.executionStartTime) ?? parseTimestampMs(firstEntry.timestamp);
+    const insertionIndex =
+        executionTime === null
+            ? -1
+            : visibleEntries.findIndex((entry) => {
+                  const entryTime = parseTimestampMs(entry.timestamp);
+                  return entryTime !== null && entryTime > executionTime;
+              });
+    if (insertionIndex < 0) {
+        visibleEntries.push(...executionGroup);
+    } else {
+        visibleEntries.splice(insertionIndex, 0, ...executionGroup);
+    }
+};
+
+const getVisibleEntries = (
+    historyEntries: KiroTranscriptEntry[],
+    executionEntries: KiroTranscriptEntry[],
+): KiroTranscriptEntry[] => {
+    if (executionEntries.length === 0) {
+        return historyEntries;
+    }
+
+    const executionEntriesById = groupExecutionEntriesById(executionEntries);
+    const { usedExecutionIds, visibleEntries } = replaceExecutionPlaceholders(historyEntries, executionEntriesById);
+    for (const executionGroup of groupUnmatchedExecutionEntries(executionEntries, usedExecutionIds)) {
+        insertExecutionGroupByStartTime(visibleEntries, executionGroup);
+    }
     return visibleEntries;
 };
 
@@ -782,7 +857,7 @@ const readSessionFile = async (
 const listSessionFilesForWorkspace = async (sessionsDir: string, directoryName: string): Promise<KiroSessionFile[]> => {
     const workspaceDir = path.join(sessionsDir, directoryName);
     const index = await readSessionIndex(workspaceDir);
-    const entries = await readdir(workspaceDir, { withFileTypes: true }).catch(() => []);
+    const entries = await readDirectoryEntriesIfExists(workspaceDir);
 
     return entries
         .filter((entry) => entry.isFile() && entry.name.endsWith('.json') && entry.name !== 'sessions.json')
@@ -815,7 +890,7 @@ const readSessionFiles = async (files: KiroSessionFile[]): Promise<KiroSessionTr
     const transcripts = await mapWithConcurrency(files, READ_CONCURRENCY, (file) =>
         readSessionFile(file, { includeExecutions: false, sessionsDir: path.dirname(path.dirname(file.filePath)) }),
     );
-    return transcripts.flatMap((transcript) => (transcript ? [transcript] : []));
+    return transcripts.flatMap((transcript) => (transcript && transcript.renderablePartCount > 0 ? [transcript] : []));
 };
 
 const compareNullableMsDesc = (left: number | null, right: number | null): number => {
@@ -929,7 +1004,39 @@ export const listKiroSessionsForGroup = async (
 
 const locateSessionFile = async (sessionsDir: string, sessionId: string): Promise<KiroSessionFile | null> => {
     const files = await listSessionFiles(sessionsDir);
-    return files.find((file) => path.basename(file.filePath, '.json') === sessionId) ?? null;
+    const filenameMatch = files.find((file) => path.basename(file.filePath, '.json') === sessionId);
+    if (filenameMatch) {
+        return filenameMatch;
+    }
+
+    const bodyMatches = await mapWithConcurrency(files, READ_CONCURRENCY, async (file) => {
+        const raw = await readJsonObject(file.filePath);
+        return asString(raw?.sessionId ?? null) === sessionId ? file : null;
+    });
+    return bodyMatches.find((file): file is KiroSessionFile => file !== null) ?? null;
+};
+
+const removeKiroSessionIndexEntry = async (workspaceDir: string, sessionId: string): Promise<void> => {
+    const indexPath = path.join(workspaceDir, 'sessions.json');
+    const value = (await Bun.file(indexPath)
+        .json()
+        .catch(() => null)) as JsonValue | null;
+    if (!Array.isArray(value)) {
+        return;
+    }
+
+    const next = value.filter((item) => asString(asObject(item)?.sessionId ?? null) !== sessionId);
+    if (next.length === value.length) {
+        return;
+    }
+
+    const tempPath = `${indexPath}.${randomUUID()}.tmp`;
+    try {
+        await Bun.write(tempPath, JSON.stringify(next, null, 2));
+        await rename(tempPath, indexPath);
+    } finally {
+        await rm(tempPath, { force: true });
+    }
 };
 
 export const readKiroSessionTranscript = async (
@@ -947,3 +1054,40 @@ export const readKiroSessionTranscript = async (
 
     return readSessionFile(file, { includeExecutions: true, sessionsDir });
 };
+
+export const deleteKiroSession = (sessionsDir: string, sessionId: string): Promise<DeleteKiroSessionResult> => {
+    return kiroDeleteLimiter(async () => {
+        if (!(await pathExists(sessionsDir))) {
+            return { deletedFiles: [], deletedSessionIds: [] };
+        }
+
+        const file = await locateSessionFile(sessionsDir, sessionId);
+        if (!file) {
+            return { deletedFiles: [], deletedSessionIds: [] };
+        }
+
+        const transcript = await readSessionFile(file, { includeExecutions: false, sessionsDir });
+        const executionFiles = transcript
+            ? await listExecutionFilesForSession(
+                  getKiroDataDirFromSessionsDir(sessionsDir),
+                  sessionId,
+                  transcript.session.worktree,
+              )
+            : [];
+        const deletedFiles = [file.filePath, ...executionFiles.map((execution) => execution.filePath)];
+
+        await Promise.all(deletedFiles.map((filePath) => rm(filePath, { force: true })));
+        executionFilesCache.delete(
+            path.join(
+                getKiroDataDirFromSessionsDir(sessionsDir),
+                getKiroWorkspaceHash(transcript?.session.worktree ?? ''),
+            ),
+        );
+        await removeKiroSessionIndexEntry(path.dirname(file.filePath), sessionId);
+
+        return {
+            deletedFiles,
+            deletedSessionIds: [sessionId],
+        };
+    });
+};