llm-cli-gateway 1.0.0

package/dist/session-manager-pg.js

@@ -0,0 +1,383 @@
+import { randomUUID } from "crypto";
+const DEFAULT_SESSION_DESCRIPTIONS = {
+    claude: "Claude Session",
+    codex: "Codex Session",
+    gemini: "Gemini Session"
+};
+/**
+ * PostgreSQL-backed session manager with Redis caching
+ */
+export class PostgreSQLSessionManager {
+    pool;
+    redis;
+    cacheTtl;
+    logger;
+    constructor(pool, redis, cacheTtl, logger) {
+        this.pool = pool;
+        this.redis = redis;
+        this.cacheTtl = cacheTtl;
+        this.logger = logger;
+    }
+    /**
+     * Acquire distributed lock using Redis SET NX EX
+     * Returns [success, lockValue] tuple
+     */
+    async acquireLock(key, ttlSeconds) {
+        const lockKey = `lock:${key}`;
+        const lockValue = randomUUID();
+        // SET NX EX atomic operation
+        const result = await this.redis.set(lockKey, lockValue, "EX", ttlSeconds, "NX");
+        return [result === "OK", lockValue];
+    }
+    async sleep(ms) {
+        await new Promise(resolve => setTimeout(resolve, ms));
+    }
+    /**
+     * Acquire a distributed lock with bounded retries to smooth contention spikes.
+     */
+    async acquireLockWithRetry(key, ttlSeconds, errorLabel, maxWaitMs = 6000) {
+        const deadline = Date.now() + maxWaitMs;
+        while (true) {
+            const [lockAcquired, lockValue] = await this.acquireLock(key, ttlSeconds);
+            if (lockAcquired) {
+                return lockValue;
+            }
+            if (Date.now() >= deadline) {
+                throw new Error(`Failed to acquire lock for ${errorLabel}`);
+            }
+            // Small jitter avoids lock-step retries from concurrent callers.
+            await this.sleep(25 + Math.floor(Math.random() * 25));
+        }
+    }
+    /**
+     * Release distributed lock using Lua script for atomic compare-and-delete
+     * Only releases if lockValue matches (prevents releasing another process's lock)
+     */
+    async releaseLock(key, lockValue) {
+        const lockKey = `lock:${key}`;
+        // Lua script for atomic compare-and-delete
+        const script = `
+      if redis.call("get", KEYS[1]) == ARGV[1] then
+        return redis.call("del", KEYS[1])
+      else
+        return 0
+      end
+    `;
+        await this.redis.eval(script, 1, lockKey, lockValue);
+    }
+    /**
+     * Invalidate session cache
+     */
+    async invalidateCache(sessionId) {
+        try {
+            await this.redis.del(`session:${sessionId}`);
+        }
+        catch (error) {
+            // Graceful degradation - log but don't fail
+            this.logger.error(`Cache invalidation failed for session ${sessionId}`, { error, sessionId });
+        }
+    }
+    /**
+     * Invalidate session list cache using SCAN (non-blocking)
+     */
+    async invalidateListCache(cli) {
+        try {
+            if (cli) {
+                await this.redis.del(`session_list:${cli}`);
+            }
+            else {
+                // Use SCAN instead of KEYS to avoid blocking Redis
+                const keys = [];
+                let cursor = "0";
+                do {
+                    const [nextCursor, matchedKeys] = await this.redis.scan(cursor, "MATCH", "session_list:*", "COUNT", 100);
+                    cursor = nextCursor;
+                    keys.push(...matchedKeys);
+                } while (cursor !== "0");
+                // Delete in batches to avoid overwhelming Redis
+                if (keys.length > 0) {
+                    await this.redis.del(...keys);
+                }
+            }
+        }
+        catch (error) {
+            this.logger.error("List cache invalidation failed", { error });
+        }
+    }
+    /**
+     * Create a new session
+     */
+    async createSession(cli, description, sessionId) {
+        const id = sessionId || randomUUID();
+        const sessionDescription = description ?? DEFAULT_SESSION_DESCRIPTIONS[cli];
+        const now = new Date().toISOString();
+        const client = await this.pool.connect();
+        try {
+            await client.query("BEGIN");
+            // Insert session
+            await client.query(`INSERT INTO sessions (id, cli, description, created_at, last_used_at)
+         VALUES ($1, $2, $3, $4, $5)`, [id, cli, sessionDescription, now, now]);
+            // Set as active if none exists
+            await client.query(`INSERT INTO active_sessions (cli, session_id, updated_at)
+         VALUES ($1, $2, $3)
+         ON CONFLICT (cli) DO NOTHING`, [cli, id, now]);
+            await client.query("COMMIT");
+            const session = {
+                id,
+                cli,
+                createdAt: now,
+                lastUsedAt: now,
+                description: sessionDescription
+            };
+            // Write-through to cache
+            try {
+                await this.redis.setex(`session:${id}`, this.cacheTtl.session, JSON.stringify(session));
+            }
+            catch (error) {
+                // Graceful degradation
+                this.logger.error("Cache write failed", { error });
+            }
+            // Invalidate list cache
+            await this.invalidateListCache(cli);
+            return session;
+        }
+        catch (error) {
+            await client.query("ROLLBACK");
+            throw error;
+        }
+        finally {
+            client.release();
+        }
+    }
+    /**
+     * Get session by ID (cache-aside pattern)
+     */
+    async getSession(sessionId) {
+        // Try cache first
+        try {
+            const cached = await this.redis.get(`session:${sessionId}`);
+            if (cached) {
+                return JSON.parse(cached);
+            }
+        }
+        catch (error) {
+            // Graceful degradation - fallback to DB
+            this.logger.error("Cache read failed", { error });
+        }
+        // Cache miss - query database
+        const result = await this.pool.query(`SELECT id, cli, description, metadata, created_at AS "createdAt", last_used_at AS "lastUsedAt"
+       FROM sessions
+       WHERE id = $1`, [sessionId]);
+        if (result.rows.length === 0) {
+            return null;
+        }
+        const session = result.rows[0];
+        // Populate cache
+        try {
+            await this.redis.setex(`session:${sessionId}`, this.cacheTtl.session, JSON.stringify(session));
+        }
+        catch (error) {
+            this.logger.error("Cache write failed", { error });
+        }
+        return session;
+    }
+    /**
+     * List all sessions, optionally filtered by CLI
+     */
+    async listSessions(cli) {
+        // Try cache for CLI-specific lists
+        const cacheKey = cli ? `session_list:${cli}` : null;
+        if (cacheKey) {
+            try {
+                const cached = await this.redis.get(cacheKey);
+                if (cached) {
+                    return JSON.parse(cached);
+                }
+            }
+            catch (error) {
+                this.logger.error("Cache read failed", { error });
+            }
+        }
+        // Query database
+        const query = cli
+            ? `SELECT id, cli, description, metadata, created_at AS "createdAt", last_used_at AS "lastUsedAt"
+         FROM sessions
+         WHERE cli = $1
+         ORDER BY last_used_at DESC`
+            : `SELECT id, cli, description, metadata, created_at AS "createdAt", last_used_at AS "lastUsedAt"
+         FROM sessions
+         ORDER BY last_used_at DESC`;
+        const result = cli ? await this.pool.query(query, [cli]) : await this.pool.query(query);
+        const sessions = result.rows;
+        // Cache CLI-specific lists
+        if (cacheKey) {
+            try {
+                await this.redis.setex(cacheKey, this.cacheTtl.sessionList, JSON.stringify(sessions));
+            }
+            catch (error) {
+                this.logger.error("Cache write failed", { error });
+            }
+        }
+        return sessions;
+    }
+    /**
+     * Delete a session
+     */
+    async deleteSession(sessionId) {
+        // Get session to find CLI type
+        const session = await this.getSession(sessionId);
+        if (!session) {
+            return false;
+        }
+        // Delete from database (CASCADE will handle active_sessions)
+        const result = await this.pool.query("DELETE FROM sessions WHERE id = $1", [sessionId]);
+        if (result.rowCount === 0) {
+            return false;
+        }
+        // Invalidate caches (session, active session for this CLI, and list)
+        await this.invalidateCache(sessionId);
+        try {
+            await this.redis.del(`active_session:${session.cli}`);
+        }
+        catch (error) {
+            this.logger.error(`Failed to invalidate active session cache for ${session.cli}`, { error });
+        }
+        await this.invalidateListCache(session.cli);
+        return true;
+    }
+    /**
+     * Set active session for a CLI (with distributed locking)
+     */
+    async setActiveSession(cli, sessionId) {
+        // Validate session exists if not null
+        if (sessionId !== null) {
+            const session = await this.getSession(sessionId);
+            if (!session || session.cli !== cli) {
+                return false;
+            }
+        }
+        // Acquire lock with bounded retries to avoid failing benign concurrent updates.
+        const lockValue = await this.acquireLockWithRetry(`active_session:${cli}`, 5, `active session ${cli}`);
+        try {
+            // UPSERT active session
+            const now = new Date().toISOString();
+            await this.pool.query(`INSERT INTO active_sessions (cli, session_id, updated_at)
+         VALUES ($1, $2, $3)
+         ON CONFLICT (cli) DO UPDATE SET session_id = $2, updated_at = $3`, [cli, sessionId, now]);
+            // Update cache
+            try {
+                if (sessionId) {
+                    await this.redis.setex(`active_session:${cli}`, this.cacheTtl.activeSession, sessionId);
+                }
+                else {
+                    await this.redis.del(`active_session:${cli}`);
+                }
+            }
+            catch (error) {
+                this.logger.error("Cache update failed", { error });
+            }
+            return true;
+        }
+        finally {
+            // Release lock with ownership verification
+            try {
+                await this.releaseLock(`active_session:${cli}`, lockValue);
+            }
+            catch (error) {
+                this.logger.error(`Failed to release lock for active session ${cli}`, { error, cli });
+            }
+        }
+    }
+    /**
+     * Get active session for a CLI
+     */
+    async getActiveSession(cli) {
+        // Try cache first
+        try {
+            const cachedId = await this.redis.get(`active_session:${cli}`);
+            if (cachedId) {
+                return await this.getSession(cachedId);
+            }
+        }
+        catch (error) {
+            this.logger.error("Cache read failed", { error });
+        }
+        // Query database
+        const result = await this.pool.query("SELECT session_id FROM active_sessions WHERE cli = $1", [cli]);
+        if (result.rows.length === 0 || !result.rows[0].session_id) {
+            return null;
+        }
+        const sessionId = result.rows[0].session_id;
+        // Populate cache
+        try {
+            await this.redis.setex(`active_session:${cli}`, this.cacheTtl.activeSession, sessionId);
+        }
+        catch (error) {
+            this.logger.error("Cache write failed", { error });
+        }
+        return await this.getSession(sessionId);
+    }
+    /**
+     * Update session usage timestamp
+     */
+    async updateSessionUsage(sessionId) {
+        const now = new Date().toISOString();
+        await this.pool.query("UPDATE sessions SET last_used_at = $1 WHERE id = $2", [now, sessionId]);
+        // Invalidate cache to force refresh
+        await this.invalidateCache(sessionId);
+    }
+    /**
+     * Update session metadata (atomic JSONB merge)
+     */
+    async updateSessionMetadata(sessionId, metadata) {
+        // Use PostgreSQL JSONB || operator for atomic merge (prevents race conditions)
+        const result = await this.pool.query(`UPDATE sessions
+       SET metadata = COALESCE(metadata, '{}'::jsonb) || $1::jsonb
+       WHERE id = $2
+       RETURNING id`, [JSON.stringify(metadata), sessionId]);
+        if (result.rowCount === 0) {
+            return false;
+        }
+        // Invalidate cache
+        await this.invalidateCache(sessionId);
+        return true;
+    }
+    /**
+     * Clear all sessions, optionally filtered by CLI
+     * Invalidates all related caches (session, active, list)
+     */
+    async clearAllSessions(cli) {
+        // First get all sessions to invalidate their caches
+        const sessions = await this.listSessions(cli);
+        // Delete from database
+        const query = cli ? "DELETE FROM sessions WHERE cli = $1" : "DELETE FROM sessions";
+        const result = cli ? await this.pool.query(query, [cli]) : await this.pool.query(query);
+        // Invalidate individual session caches (concurrent — each has its own try/catch)
+        await Promise.all(sessions.map(session => this.invalidateCache(session.id)));
+        // Invalidate active session caches
+        if (cli) {
+            try {
+                await this.redis.del(`active_session:${cli}`);
+            }
+            catch (error) {
+                this.logger.error(`Failed to invalidate active session cache for ${cli}`, { error, cli });
+            }
+        }
+        else {
+            // Invalidate all active session caches
+            try {
+                await Promise.all([
+                    this.redis.del("active_session:claude"),
+                    this.redis.del("active_session:codex"),
+                    this.redis.del("active_session:gemini")
+                ]);
+            }
+            catch (error) {
+                this.logger.error("Failed to invalidate active session caches", { error });
+            }
+        }
+        // Invalidate list caches
+        await this.invalidateListCache(cli);
+        return result.rowCount || 0;
+    }
+}

package/dist/session-manager.d.ts

@@ -0,0 +1,62 @@
+import type { Config } from "./config.js";
+import type { DatabaseConnection } from "./db.js";
+import type { Logger } from "./logger.js";
+export declare const CLI_TYPES: readonly ["claude", "codex", "gemini"];
+export type CliType = (typeof CLI_TYPES)[number];
+export interface Session {
+    id: string;
+    cli: CliType;
+    createdAt: string;
+    lastUsedAt: string;
+    description?: string;
+    metadata?: Record<string, any>;
+}
+export interface SessionStorage {
+    sessions: Record<string, Session>;
+    activeSession: Record<CliType, string | null>;
+}
+export declare class FileSessionManager {
+    private storagePath;
+    private storage;
+    private readonly sessionTtlMs;
+    constructor(customPath?: string, sessionTtlMs?: number);
+    private isExpired;
+    private evictExpiredSessions;
+    private ensureStorageDirectory;
+    private loadStorage;
+    private saveStorage;
+    createSession(cli: CliType, description?: string, sessionId?: string): Session;
+    getSession(sessionId: string): Session | null;
+    listSessions(cli?: CliType): Session[];
+    deleteSession(sessionId: string): boolean;
+    setActiveSession(cli: CliType, sessionId: string | null): boolean;
+    getActiveSession(cli: CliType): Session | null;
+    updateSessionUsage(sessionId: string): void;
+    updateSessionMetadata(sessionId: string, metadata: Record<string, any>): boolean;
+    clearAllSessions(cli?: CliType): number;
+}
+export declare const SessionManager: typeof FileSessionManager;
+/**
+ * Session manager interface supporting both sync (file) and async (PostgreSQL) backends.
+ * Methods return T | Promise<T> so both backends satisfy the contract.
+ * Callers must always use `await` for uniform handling.
+ */
+export interface ISessionManager {
+    createSession(cli: CliType, description?: string, sessionId?: string): Session | Promise<Session>;
+    getSession(sessionId: string): Session | null | Promise<Session | null>;
+    listSessions(cli?: CliType): Session[] | Promise<Session[]>;
+    deleteSession(sessionId: string): boolean | Promise<boolean>;
+    setActiveSession(cli: CliType, sessionId: string | null): boolean | Promise<boolean>;
+    getActiveSession(cli: CliType): Session | null | Promise<Session | null>;
+    updateSessionUsage(sessionId: string): void | Promise<void>;
+    updateSessionMetadata(sessionId: string, metadata: Record<string, any>): boolean | Promise<boolean>;
+    clearAllSessions(cli?: CliType): number | Promise<number>;
+}
+/**
+ * Factory function to create session manager
+ * Returns PostgreSQLSessionManager if config present, otherwise FileSessionManager
+ * @param config - Configuration object
+ * @param db - Optional pre-existing DatabaseConnection (avoids creating duplicate connections)
+ * @param logger - Logger instance for structured logging
+ */
+export declare function createSessionManager(config?: Config, db?: DatabaseConnection, logger?: Logger): Promise<ISessionManager>;

package/dist/session-manager.js

@@ -0,0 +1,223 @@
+import { randomUUID } from "crypto";
+import { homedir } from "os";
+import { join, dirname } from "path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, openSync, fsyncSync, closeSync, chmodSync } from "fs";
+import { DEFAULT_SESSION_TTL_SECONDS } from "./config.js";
+import { noopLogger } from "./logger.js";
+export const CLI_TYPES = ["claude", "codex", "gemini"];
+const createEmptyActiveSessions = () => Object.fromEntries(CLI_TYPES.map(cli => [cli, null]));
+const DEFAULT_SESSION_DESCRIPTIONS = {
+    claude: "Claude Session",
+    codex: "Codex Session",
+    gemini: "Gemini Session"
+};
+export class FileSessionManager {
+    storagePath;
+    storage = { sessions: {}, activeSession: createEmptyActiveSessions() };
+    sessionTtlMs;
+    constructor(customPath, sessionTtlMs) {
+        this.sessionTtlMs = sessionTtlMs ?? DEFAULT_SESSION_TTL_SECONDS * 1000;
+        this.storagePath = customPath || join(homedir(), ".llm-cli-gateway", "sessions.json");
+        this.ensureStorageDirectory();
+        this.loadStorage();
+    }
+    isExpired(session) {
+        const ts = new Date(session.lastUsedAt).getTime();
+        if (!Number.isFinite(ts))
+            return true; // malformed → expired
+        return Date.now() - ts > this.sessionTtlMs;
+    }
+    evictExpiredSessions() {
+        let count = 0;
+        for (const [id, session] of Object.entries(this.storage.sessions)) {
+            if (this.isExpired(session)) {
+                delete this.storage.sessions[id];
+                if (this.storage.activeSession[session.cli] === id) {
+                    this.storage.activeSession[session.cli] = null;
+                }
+                count++;
+            }
+        }
+        if (count > 0)
+            this.saveStorage();
+        return count;
+    }
+    ensureStorageDirectory() {
+        const storageDir = dirname(this.storagePath);
+        if (!existsSync(storageDir)) {
+            mkdirSync(storageDir, { recursive: true });
+        }
+    }
+    loadStorage() {
+        if (existsSync(this.storagePath)) {
+            try {
+                const data = readFileSync(this.storagePath, "utf-8");
+                this.storage = JSON.parse(data);
+            }
+            catch (error) {
+                // If file is corrupted, start fresh
+                this.storage = { sessions: {}, activeSession: createEmptyActiveSessions() };
+            }
+        }
+        else {
+            this.storage = { sessions: {}, activeSession: createEmptyActiveSessions() };
+        }
+    }
+    saveStorage() {
+        const tempPath = `${this.storagePath}.tmp.${process.pid}`;
+        writeFileSync(tempPath, JSON.stringify(this.storage, null, 2), { encoding: "utf-8", mode: 0o600 });
+        const fd = openSync(tempPath, "r+");
+        try {
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        renameSync(tempPath, this.storagePath);
+        chmodSync(this.storagePath, 0o600);
+    }
+    createSession(cli, description, sessionId) {
+        this.evictExpiredSessions();
+        const id = sessionId || randomUUID();
+        const sessionDescription = description ?? DEFAULT_SESSION_DESCRIPTIONS[cli];
+        const session = {
+            id,
+            cli,
+            createdAt: new Date().toISOString(),
+            lastUsedAt: new Date().toISOString(),
+            description: sessionDescription
+        };
+        this.storage.sessions[id] = session;
+        // Set as active session if none exists for this CLI
+        if (!this.storage.activeSession[cli]) {
+            this.storage.activeSession[cli] = id;
+        }
+        this.saveStorage();
+        return session;
+    }
+    getSession(sessionId) {
+        const session = this.storage.sessions[sessionId];
+        if (!session)
+            return null;
+        if (this.isExpired(session)) {
+            this.deleteSession(sessionId);
+            return null;
+        }
+        return session;
+    }
+    listSessions(cli) {
+        this.evictExpiredSessions();
+        const sessions = Object.values(this.storage.sessions);
+        if (cli) {
+            return sessions.filter(s => s.cli === cli);
+        }
+        return sessions;
+    }
+    deleteSession(sessionId) {
+        if (!this.storage.sessions[sessionId]) {
+            return false;
+        }
+        const session = this.storage.sessions[sessionId];
+        delete this.storage.sessions[sessionId];
+        // If this was the active session, clear it
+        if (this.storage.activeSession[session.cli] === sessionId) {
+            this.storage.activeSession[session.cli] = null;
+        }
+        this.saveStorage();
+        return true;
+    }
+    setActiveSession(cli, sessionId) {
+        if (sessionId !== null) {
+            const session = this.storage.sessions[sessionId];
+            if (!session)
+                return false;
+            if (this.isExpired(session)) {
+                this.deleteSession(sessionId);
+                return false;
+            }
+            if (session.cli !== cli)
+                return false;
+        }
+        this.storage.activeSession[cli] = sessionId;
+        this.saveStorage();
+        return true;
+    }
+    getActiveSession(cli) {
+        const sessionId = this.storage.activeSession[cli];
+        if (!sessionId)
+            return null;
+        const session = this.storage.sessions[sessionId];
+        if (!session || this.isExpired(session)) {
+            this.storage.activeSession[cli] = null;
+            if (session)
+                delete this.storage.sessions[sessionId];
+            this.saveStorage();
+            return null;
+        }
+        return session;
+    }
+    updateSessionUsage(sessionId) {
+        const session = this.storage.sessions[sessionId];
+        if (!session)
+            return;
+        if (this.isExpired(session)) {
+            this.deleteSession(sessionId);
+            return;
+        }
+        session.lastUsedAt = new Date().toISOString();
+        this.saveStorage();
+    }
+    updateSessionMetadata(sessionId, metadata) {
+        const session = this.storage.sessions[sessionId];
+        if (!session)
+            return false;
+        if (this.isExpired(session)) {
+            this.deleteSession(sessionId);
+            return false;
+        }
+        session.metadata = { ...session.metadata, ...metadata };
+        this.saveStorage();
+        return true;
+    }
+    clearAllSessions(cli) {
+        const sessionsToDelete = cli
+            ? Object.values(this.storage.sessions).filter(s => s.cli === cli)
+            : Object.values(this.storage.sessions);
+        sessionsToDelete.forEach(session => {
+            delete this.storage.sessions[session.id];
+            if (this.storage.activeSession[session.cli] === session.id) {
+                this.storage.activeSession[session.cli] = null;
+            }
+        });
+        this.saveStorage();
+        return sessionsToDelete.length;
+    }
+}
+// Maintain backward compatibility
+export const SessionManager = FileSessionManager;
+/**
+ * Factory function to create session manager
+ * Returns PostgreSQLSessionManager if config present, otherwise FileSessionManager
+ * @param config - Configuration object
+ * @param db - Optional pre-existing DatabaseConnection (avoids creating duplicate connections)
+ * @param logger - Logger instance for structured logging
+ */
+export async function createSessionManager(config, db, logger) {
+    if (config?.database && config?.redis) {
+        // Import dynamically to avoid loading pg/ioredis if not needed
+        const { PostgreSQLSessionManager } = await import("./session-manager-pg.js");
+        // Use provided db connection or create new one
+        if (!db) {
+            const { createDatabaseConnection } = await import("./db.js");
+            db = await createDatabaseConnection(config, logger);
+        }
+        return new PostgreSQLSessionManager(db.getPool(), db.getRedis(), config.cacheTtl, logger ?? noopLogger);
+    }
+    else {
+        // Use file-based storage with TTL from config
+        const sessionTtlMs = config?.sessionTtl
+            ? config.sessionTtl * 1000
+            : DEFAULT_SESSION_TTL_SECONDS * 1000;
+        return new FileSessionManager(undefined, sessionTtlMs);
+    }
+}

package/dist/stream-json-parser.d.ts

@@ -0,0 +1,35 @@
+/**
+ * NDJSON parser for Claude `--output-format stream-json --include-partial-messages`.
+ *
+ * Each line of stdout is a complete JSON object. This parser extracts the
+ * final result text, cost, usage, and metadata from the stream.
+ */
+export interface StreamJsonUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadInputTokens: number;
+    cacheCreationInputTokens: number;
+}
+export interface StreamJsonResult {
+    text: string;
+    costUsd: number | null;
+    usage: StreamJsonUsage | null;
+    sessionId: string | null;
+    model: string | null;
+    durationApiMs: number | null;
+    isError: boolean;
+    numTurns: number | null;
+}
+/**
+ * Parse completed NDJSON stdout from `claude --output-format stream-json --include-partial-messages`.
+ *
+ * Parsing strategy:
+ * 1. Split by newlines, filter empty lines
+ * 2. JSON.parse each line, skip malformed lines
+ * 3. Find the `type=result` event — contains final text, cost, usage
+ * 4. Fall back to the last `type=assistant` event if no result event
+ * 5. Extract `model` from `type=system` (init) event
+ *
+ * No rawEvents stored — the stdout buffer is already in memory.
+ */
+export declare function parseStreamJson(stdout: string): StreamJsonResult;