spiracha 1.4.0 → 2.0.0

package/src/client.ts

@@ -0,0 +1,290 @@
+import {
+    getConversation as getLocalConversation,
+    listConversationSources as listLocalConversationSources,
+    listConversationsForPath as listLocalConversationsForPath,
+    renderConversationMarkdown as renderLocalConversationMarkdown,
+    resolveConversationRef as resolveLocalConversationRef,
+} from './lib/conversation-data';
+import type {
+    ConversationDataLocations,
+    ConversationDetail,
+    ConversationMessageSelector,
+    ConversationPage,
+    ConversationSourceInfo,
+    GetConversationOptions,
+    ListConversationsForPathOptions,
+    ResolvedConversationRef,
+} from './lib/conversation-data/types';
+
+export type {
+    ConversationDataLocations,
+    ConversationDeepLinks,
+    ConversationDetail,
+    ConversationMessage,
+    ConversationMessagePhase,
+    ConversationMessageRole,
+    ConversationMessageSelector,
+    ConversationPage,
+    ConversationPathMatch,
+    ConversationSource,
+    ConversationSourceInfo,
+    GetConversationOptions,
+    ListConversationsForPathOptions,
+    ResolvedConversationRef,
+} from './lib/conversation-data/types';
+
+type HttpEnvelope<T> = {
+    data?: T;
+    error?: {
+        message?: string | null;
+    } | null;
+    meta?: {
+        hasNext?: boolean | null;
+        nextCursor?: string | null;
+        next_cursor?: string | null;
+    } | null;
+};
+
+export class SpirachaClientError extends Error {
+    readonly status: number | null;
+
+    constructor(message: string, status: number | null = null) {
+        super(message);
+        this.name = 'SpirachaClientError';
+        this.status = status;
+    }
+}
+
+export type LocalConversationClientOptions = {
+    locations?: ConversationDataLocations;
+    mode?: 'local';
+};
+
+export type HttpConversationClientOptions = {
+    baseUrl: string;
+    mode: 'http';
+};
+
+export type CreateConversationClientOptions = HttpConversationClientOptions | LocalConversationClientOptions;
+
+export type ExportConversationMarkdownOptions = GetConversationOptions;
+
+export type ConversationClient = {
+    exportConversationMarkdown: (options: ExportConversationMarkdownOptions) => Promise<string | null>;
+    getConversation: (options: GetConversationOptions) => Promise<ConversationDetail | null>;
+    listConversations: (options: ListConversationsForPathOptions) => Promise<ConversationPage>;
+    listSources: () => Promise<ConversationSourceInfo[]>;
+    resolveConversationRef: (ref: string) => Promise<ResolvedConversationRef | null>;
+};
+
+const withDefaultLocations = <T extends { locations?: ConversationDataLocations }>(
+    options: T,
+    locations: ConversationDataLocations | undefined,
+): T => {
+    return locations && !options.locations ? { ...options, locations } : options;
+};
+
+const normalizeBaseUrl = (value: string): URL => {
+    try {
+        const url = new URL(value);
+        if (url.protocol === 'http:' || url.protocol === 'https:') {
+            return url;
+        }
+    } catch {
+        // Fall through to a consistent client-facing error.
+    }
+
+    throw new SpirachaClientError(`Invalid Spiracha base URL "${value}". Use an http:// or https:// URL.`);
+};
+
+const appendOptionalNumber = (url: URL, key: string, value: number | undefined): void => {
+    if (value !== undefined) {
+        url.searchParams.set(key, String(value));
+    }
+};
+
+const appendListOptions = (url: URL, options: ListConversationsForPathOptions): void => {
+    url.searchParams.set('cwd', options.cwd);
+    if (options.cursor) {
+        url.searchParams.set('cursor', options.cursor);
+    }
+    if (options.includeMessages !== undefined) {
+        url.searchParams.set('include_messages', String(options.includeMessages));
+    }
+    if (options.limit !== undefined) {
+        url.searchParams.set('limit', String(options.limit));
+    }
+    if (options.messageSelector) {
+        url.searchParams.set('message_selector', options.messageSelector);
+    }
+    if (options.sources && options.sources !== 'all') {
+        url.searchParams.set('source', options.sources.join(','));
+    }
+    appendOptionalNumber(url, 'updated_after_ms', options.updatedAfterMs);
+    appendOptionalNumber(url, 'updated_before_ms', options.updatedBeforeMs);
+};
+
+const appendMessageSelector = (url: URL, messageSelector: ConversationMessageSelector | undefined): void => {
+    if (messageSelector) {
+        url.searchParams.set('message_selector', messageSelector);
+    }
+};
+
+const httpErrorMessage = async (response: Response): Promise<string> => {
+    const text = await response.text();
+    if (!text.trim()) {
+        return response.statusText || `HTTP ${response.status}`;
+    }
+
+    try {
+        const parsed = JSON.parse(text) as HttpEnvelope<unknown>;
+        return parsed.error?.message || text.trim();
+    } catch {
+        return text.trim();
+    }
+};
+
+const fetchResponse = async (url: URL, init?: RequestInit): Promise<Response> => {
+    try {
+        return await fetch(url, init);
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new SpirachaClientError(`Unable to reach Spiracha at ${url.origin}: ${message}`);
+    }
+};
+
+const assertOkResponse = async (response: Response): Promise<void> => {
+    if (response.ok) {
+        return;
+    }
+
+    throw new SpirachaClientError(
+        `Spiracha API request failed (${response.status}): ${await httpErrorMessage(response)}`,
+        response.status,
+    );
+};
+
+const readJsonEnvelope = async <T>(response: Response): Promise<HttpEnvelope<T>> => {
+    try {
+        return (await response.json()) as HttpEnvelope<T>;
+    } catch {
+        throw new SpirachaClientError('Spiracha API returned invalid JSON.', response.status);
+    }
+};
+
+const fetchJson = async <T>(url: URL, init?: RequestInit): Promise<HttpEnvelope<T>> => {
+    const response = await fetchResponse(url, init);
+    await assertOkResponse(response);
+    return readJsonEnvelope(response);
+};
+
+const fetchJsonOrNull = async <T>(url: URL, init?: RequestInit): Promise<HttpEnvelope<T> | null> => {
+    const response = await fetchResponse(url, init);
+    if (response.status === 404) {
+        return null;
+    }
+
+    await assertOkResponse(response);
+    return readJsonEnvelope(response);
+};
+
+const fetchTextOrNull = async (url: URL, init?: RequestInit): Promise<string | null> => {
+    const response = await fetchResponse(url, init);
+    if (response.status === 404) {
+        return null;
+    }
+
+    await assertOkResponse(response);
+    return response.text();
+};
+
+const requireData = <T>(envelope: HttpEnvelope<T>, label: string): T => {
+    if (envelope.data === undefined) {
+        throw new SpirachaClientError(`Spiracha API response did not include ${label}.`);
+    }
+
+    return envelope.data;
+};
+
+const normalizePage = (envelope: HttpEnvelope<ConversationDetail[]>): ConversationPage => {
+    const data = requireData(envelope, 'a data field');
+    if (!Array.isArray(data)) {
+        throw new SpirachaClientError('Spiracha API response did not include a data array.');
+    }
+
+    return {
+        data,
+        meta: {
+            hasNext: envelope.meta?.hasNext === true,
+            nextCursor: envelope.meta?.nextCursor ?? envelope.meta?.next_cursor ?? null,
+        },
+    };
+};
+
+const makeHttpUrl = (baseUrl: URL, pathname: string): URL => new URL(pathname, baseUrl);
+
+const rejectHttpLocations = (locations: ConversationDataLocations | undefined): void => {
+    if (locations) {
+        throw new SpirachaClientError('`locations` is only supported by local Spiracha clients.');
+    }
+};
+
+const makeLocalClient = (options: LocalConversationClientOptions): ConversationClient => ({
+    exportConversationMarkdown: async (getOptions) => {
+        const conversation = await getLocalConversation(withDefaultLocations(getOptions, options.locations));
+        return conversation ? renderLocalConversationMarkdown(conversation) : null;
+    },
+    getConversation: (getOptions) => getLocalConversation(withDefaultLocations(getOptions, options.locations)),
+    listConversations: (listOptions) =>
+        listLocalConversationsForPath(withDefaultLocations(listOptions, options.locations)),
+    listSources: () => listLocalConversationSources(),
+    resolveConversationRef: (ref) => resolveLocalConversationRef(ref),
+});
+
+const makeHttpClient = (options: HttpConversationClientOptions): ConversationClient => {
+    const baseUrl = normalizeBaseUrl(options.baseUrl);
+
+    return {
+        exportConversationMarkdown: async (getOptions) => {
+            rejectHttpLocations(getOptions.locations);
+            const { id, messageSelector, source } = getOptions;
+            const url = makeHttpUrl(baseUrl, `/api/v1/conversations/${source}/${encodeURIComponent(id)}/export`);
+            appendMessageSelector(url, messageSelector);
+            return fetchTextOrNull(url);
+        },
+        getConversation: async (getOptions) => {
+            rejectHttpLocations(getOptions.locations);
+            const { id, messageSelector, source } = getOptions;
+            const url = makeHttpUrl(baseUrl, `/api/v1/conversations/${source}/${encodeURIComponent(id)}`);
+            appendMessageSelector(url, messageSelector);
+            const envelope = await fetchJsonOrNull<ConversationDetail>(url);
+            if (!envelope) {
+                return null;
+            }
+            return requireData(envelope, 'a conversation');
+        },
+        listConversations: async (listOptions) => {
+            rejectHttpLocations(listOptions.locations);
+            const url = makeHttpUrl(baseUrl, '/api/v1/conversations');
+            appendListOptions(url, listOptions);
+            return normalizePage(await fetchJson<ConversationDetail[]>(url));
+        },
+        listSources: async () => {
+            const envelope = await fetchJson<ConversationSourceInfo[]>(makeHttpUrl(baseUrl, '/api/v1/sources'));
+            return requireData(envelope, 'a source list');
+        },
+        resolveConversationRef: async (ref) => {
+            const url = makeHttpUrl(baseUrl, '/api/v1/resolve');
+            url.searchParams.set('ref', ref);
+            const envelope = await fetchJsonOrNull<ResolvedConversationRef>(url);
+            if (!envelope) {
+                return null;
+            }
+            return requireData(envelope, 'a resolved ref');
+        },
+    };
+};
+
+export const createConversationClient = (options: CreateConversationClientOptions = {}): ConversationClient => {
+    return options.mode === 'http' ? makeHttpClient(options) : makeLocalClient(options);
+};

package/src/lib/antigravity-db.ts

@@ -48,12 +48,23 @@ const isSafeConversationId = (value: string) => SAFE_CONVERSATION_ID_PATTERN.tes
 type TranscriptFile = {
     bytes: number;
     entryCount: number;
+    fullPath: string | null;
     mtimeMs: number;
+    model: string | null;
     path: string;
     root: string;
     source: Exclude<AntigravityTranscriptSource, 'safe-storage'>;
 };
 
+export type AntigravityConversationMessage = {
+    createdAtMs: number | null;
+    metadata: Record<string, unknown>;
+    order: number;
+    phase: 'final_answer' | 'reasoning' | 'tool_call' | 'tool_output' | 'unknown';
+    role: 'assistant' | 'system' | 'tool' | 'unknown' | 'user';
+    text: string;
+};
+
 type WorkspaceInfo = Pick<SummaryEntry, 'workspaceFolder' | 'workspaceKey' | 'workspaceLabel' | 'workspaceUri'>;
 
 const UNKNOWN_WORKSPACE: WorkspaceInfo = {
@@ -489,6 +500,44 @@ const countJsonlEntries = async (filePath: string): Promise<number> => {
     }
 };
 
+const stripModelQualifier = (value: string): string => value.replace(/\s*\([^)]*\)\s*$/u, '').trim();
+
+const extractModelSelection = (content: string): string | null => {
+    const marker = '`Model Selection`';
+    const markerIndex = content.indexOf(marker);
+    if (markerIndex < 0) {
+        return null;
+    }
+
+    const toIndex = content.indexOf(' to ', markerIndex + marker.length);
+    if (toIndex < 0) {
+        return null;
+    }
+
+    const candidate = content.slice(toIndex + ' to '.length);
+    const endMarkers = ['. No need', '. If reporting', '</USER_SETTINGS_CHANGE>', '\n'];
+    const endIndex = endMarkers.reduce<number | null>((earliest, endMarker) => {
+        const index = candidate.indexOf(endMarker);
+        return index < 0 || (earliest !== null && index >= earliest) ? earliest : index;
+    }, null);
+    const rawModel = (endIndex === null ? candidate : candidate.slice(0, endIndex)).trim();
+    return rawModel ? stripModelQualifier(rawModel) : null;
+};
+
+const extractTranscriptModel = async (filePath: string): Promise<string | null> => {
+    const text = await Bun.file(filePath)
+        .text()
+        .catch(() => '');
+    for (const entry of parseLogEntries(text)) {
+        const model = extractModelSelection(getString(entry.content) ?? '');
+        if (model) {
+            return model;
+        }
+    }
+
+    return null;
+};
+
 const preferTranscriptFile = (current: TranscriptFile | undefined, candidate: TranscriptFile): TranscriptFile => {
     if (!current) {
         return candidate;
@@ -505,6 +554,36 @@ const preferTranscriptFile = (current: TranscriptFile | undefined, candidate: Tr
     return candidate.entryCount > current.entryCount ? candidate : current;
 };
 
+const readTranscriptFileCandidate = async (
+    root: string,
+    logsDir: string,
+    candidate: { name: string; source: TranscriptFile['source'] },
+): Promise<TranscriptFile | null> => {
+    const transcriptPath = path.join(logsDir, candidate.name);
+    try {
+        const info = await stat(transcriptPath);
+        if (!info.isFile()) {
+            return null;
+        }
+
+        const fullPath = path.join(logsDir, 'transcript_full.jsonl');
+        const hasFullTranscript = await pathExists(fullPath);
+        const modelSourcePath = hasFullTranscript ? fullPath : transcriptPath;
+        return {
+            bytes: info.size,
+            entryCount: await countJsonlEntries(modelSourcePath),
+            fullPath: hasFullTranscript ? fullPath : null,
+            model: await extractTranscriptModel(modelSourcePath),
+            mtimeMs: info.mtimeMs,
+            path: transcriptPath,
+            root,
+            source: candidate.source,
+        };
+    } catch {
+        return null;
+    }
+};
+
 const readTranscriptFilesForRoot = async (root: string): Promise<Map<string, TranscriptFile>> => {
     const brainDir = getAntigravityBrainDir(root);
     let entries: Array<{ isDirectory: () => boolean; name: string }> = [];
@@ -525,25 +604,10 @@ const readTranscriptFilesForRoot = async (root: string): Promise<Map<string, Tra
             { name: 'overview.txt', source: 'overview' as const },
             { name: 'transcript.jsonl', source: 'transcript' as const },
         ]) {
-            const transcriptPath = path.join(logsDir, candidate.name);
-            try {
-                const info = await stat(transcriptPath);
-                if (!info.isFile()) {
-                    continue;
-                }
-
-                transcripts.set(
-                    entry.name,
-                    preferTranscriptFile(transcripts.get(entry.name), {
-                        bytes: info.size,
-                        entryCount: await countJsonlEntries(transcriptPath),
-                        mtimeMs: info.mtimeMs,
-                        path: transcriptPath,
-                        root,
-                        source: candidate.source,
-                    }),
-                );
-            } catch {}
+            const transcript = await readTranscriptFileCandidate(root, logsDir, candidate);
+            if (transcript) {
+                transcripts.set(entry.name, preferTranscriptFile(transcripts.get(entry.name), transcript));
+            }
         }
     }
 
@@ -640,6 +704,7 @@ const toConversation = (
         createdAtMs: summary?.createdAtMs ?? null,
         indexedItemCount: summary?.indexedItemCount ?? null,
         lastUpdatedAtMs,
+        model: transcript?.model ?? null,
         sourceRoot,
         summaryPath: summary?.summaryPath ?? null,
         title: summary?.title ?? cleanTitle(fallbackTitle, conversationId),
@@ -872,6 +937,135 @@ const renderLogEntry = (entry: AntigravityLogEntry): string[] => {
     return parts;
 };
 
+const logEntryCreatedAtMs = (entry: AntigravityLogEntry): number | null => {
+    const timestamp = getString(entry.created_at);
+    if (!timestamp) {
+        return null;
+    }
+
+    const parsed = Date.parse(timestamp);
+    return Number.isFinite(parsed) ? parsed : null;
+};
+
+const logEntryOrder = (entry: AntigravityLogEntry, fallback: number): number => {
+    return typeof entry.step_index === 'number' && Number.isFinite(entry.step_index) ? entry.step_index : fallback;
+};
+
+const isAssistantLogEntry = (entry: AntigravityLogEntry): boolean => {
+    return getString(entry.source) === 'MODEL' && getString(entry.type) === 'PLANNER_RESPONSE';
+};
+
+const logEntryRole = (entry: AntigravityLogEntry): AntigravityConversationMessage['role'] => {
+    const source = getString(entry.source);
+    if (source?.startsWith('USER')) {
+        return 'user';
+    }
+    if (isAssistantLogEntry(entry)) {
+        return 'assistant';
+    }
+    if (source === 'SYSTEM') {
+        return 'system';
+    }
+    if (source === 'MODEL') {
+        return 'tool';
+    }
+    return 'unknown';
+};
+
+const logEntryPhase = (entry: AntigravityLogEntry): AntigravityConversationMessage['phase'] => {
+    const role = logEntryRole(entry);
+    if (role === 'assistant') {
+        return 'final_answer';
+    }
+    if (role === 'tool') {
+        return 'tool_output';
+    }
+    return 'unknown';
+};
+
+const logEntryMetadata = (entry: AntigravityLogEntry): Record<string, unknown> => ({
+    source: getString(entry.source),
+    status: getString(entry.status),
+    type: getString(entry.type),
+});
+
+const toolCallsText = (toolCalls: unknown): string => {
+    if (!Array.isArray(toolCalls)) {
+        return '';
+    }
+
+    return toolCalls
+        .flatMap((call) => {
+            if (!call || typeof call !== 'object') {
+                return [];
+            }
+            const { args, name } = call as { args?: unknown; name?: unknown };
+            return [JSON.stringify({ args, name: typeof name === 'string' ? name : 'unknown' })];
+        })
+        .join('\n');
+};
+
+const logEntryToMessages = (entry: AntigravityLogEntry, index: number): AntigravityConversationMessage[] => {
+    const order = logEntryOrder(entry, index);
+    const createdAtMs = logEntryCreatedAtMs(entry);
+    const role = logEntryRole(entry);
+    const phase = logEntryPhase(entry);
+    const metadata = logEntryMetadata(entry);
+    const messages: AntigravityConversationMessage[] = [];
+    const thinking = getString(entry.thinking)?.trim();
+    if (thinking && role === 'assistant') {
+        messages.push({
+            createdAtMs,
+            metadata,
+            order,
+            phase: 'reasoning',
+            role: 'assistant',
+            text: thinking,
+        });
+    }
+
+    const content = cleanLogContent(entry);
+    if (content) {
+        messages.push({
+            createdAtMs,
+            metadata,
+            order,
+            phase,
+            role,
+            text: content,
+        });
+    }
+
+    const calls = toolCallsText(entry.tool_calls);
+    if (calls) {
+        messages.push({
+            createdAtMs,
+            metadata,
+            order,
+            phase: 'tool_call',
+            role: 'tool',
+            text: calls,
+        });
+    }
+
+    return messages;
+};
+
+export const readAntigravityConversationMessages = async (
+    conversation: AntigravityConversation,
+): Promise<AntigravityConversationMessage[]> => {
+    if (!conversation.transcriptPath || !conversation.transcriptSource) {
+        return [];
+    }
+
+    try {
+        const entries = parseLogEntries(await Bun.file(conversation.transcriptPath).text());
+        return entries.flatMap(logEntryToMessages);
+    } catch {
+        return [];
+    }
+};
+
 const renderAntigravityTranscriptMarkdown = async (conversation: AntigravityConversation): Promise<string | null> => {
     if (!conversation.transcriptPath || !conversation.transcriptSource) {
         return null;

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

@@ -45,6 +45,7 @@ export type AntigravityConversation = {
     createdAtMs: number | null;
     indexedItemCount: number | null;
     lastUpdatedAtMs: number | null;
+    model: string | null;
     sourceRoot: string | null;
     summaryPath: string | null;
     title: string;