@vale-dinap/lucidly 0.0.0-stage → 0.1.0

package/dist/server/session.js

@@ -0,0 +1,101 @@
+/**
+ * One open run: a source feeding an engine, the event log (for saving), and live subscribers.
+ * State lives in memory; saving writes the event log, loading replays it.
+ */
+import { Engine } from "../core/engine.js";
+export const SAVE_FORMAT = 'lucidly-run';
+export const SAVE_VERSION = 1;
+const FLUSH_MS = 120;
+export class RunSession {
+    id;
+    key;
+    label;
+    live;
+    engine = new Engine();
+    events = [];
+    source;
+    subs = new Set();
+    timer = null;
+    constructor(id, source, opts = {}) {
+        this.id = id;
+        this.source = source;
+        this.key = source?.key ?? opts.key ?? `run:${id}`;
+        this.label = opts.label ?? source?.label ?? id;
+        this.live = source?.live ?? false;
+    }
+    async start() {
+        if (this.source)
+            await this.source.start((evs) => this.ingest(evs));
+    }
+    ingest(evs) {
+        if (!evs.length)
+            return;
+        for (const e of evs)
+            this.events.push(e);
+        this.engine.applyAll(evs);
+        if (this.subs.size && !this.timer)
+            this.timer = setTimeout(() => this.flush(), FLUSH_MS);
+    }
+    flush() {
+        this.timer = null;
+        const patch = this.engine.takePatch();
+        if (!patch)
+            return;
+        for (const s of this.subs)
+            s('patch', patch);
+    }
+    subscribe(send) {
+        // Bring existing subscribers up to date first, so the new snapshot and their state agree.
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.flush();
+        }
+        else {
+            this.engine.takePatch();
+        }
+        this.subs.add(send);
+        send('snapshot', this.engine.snapshot());
+        return () => this.subs.delete(send);
+    }
+    info() {
+        const r = this.engine.run;
+        return {
+            id: this.id,
+            key: this.key,
+            label: this.label,
+            title: r.title,
+            live: this.live,
+            status: r.status,
+            eventCount: r.eventCount,
+            updatedAt: r.updatedAt,
+            subscribers: this.subs.size,
+        };
+    }
+    save() {
+        const r = this.engine.run;
+        return {
+            format: SAVE_FORMAT,
+            version: SAVE_VERSION,
+            savedAt: new Date().toISOString(),
+            label: this.label,
+            meta: { title: r.title, cwd: r.cwd, agent: r.agent, sessionId: r.sessionId },
+            events: this.events,
+        };
+    }
+    static fromSave(id, data) {
+        const f = data;
+        if (!f || f.format !== SAVE_FORMAT || !Array.isArray(f.events))
+            throw new Error('Not a Lucidly save file');
+        if ((f.version ?? 0) > SAVE_VERSION)
+            throw new Error(`Save file version ${f.version} is newer than this Lucidly`);
+        const s = new RunSession(id, null, { label: f.label ?? f.meta?.title ?? 'Saved run' });
+        s.ingest(f.events);
+        return s;
+    }
+    close() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.source?.stop();
+        this.subs.clear();
+    }
+}

package/dist/sources/claude-sessions.js

@@ -0,0 +1,329 @@
+/** Discover and follow Claude Code session transcripts under ~/.claude/projects. */
+import { homedir } from 'node:os';
+import { join, basename } from 'node:path';
+import { readdir, stat, open, readFile } from 'node:fs/promises';
+import { ClaudeCodeAdapter, cleanPrompt, harnessNotice } from "../adapters/claude-code.js";
+import { truncate } from "../core/text.js";
+import { LineTailer } from "./tail.js";
+export function claudeDir() {
+    return process.env.CLAUDE_CONFIG_DIR ?? join(homedir(), '.claude');
+}
+export function projectsDir() {
+    return join(claudeDir(), 'projects');
+}
+/** Claude Code names a project folder after its cwd with every non-alphanumeric char replaced by '-'. */
+export function encodeCwd(cwd) {
+    return cwd.replace(/[^a-zA-Z0-9]/g, '-');
+}
+async function readSlice(path, start, length) {
+    const fh = await open(path, 'r');
+    try {
+        const buf = Buffer.alloc(length);
+        const { bytesRead } = await fh.read(buf, 0, length, start);
+        return buf.subarray(0, bytesRead).toString('utf8');
+    }
+    finally {
+        await fh.close();
+    }
+}
+/** Cheap metadata: read the head for cwd/first prompt and the tail for the latest title. */
+export async function describeSession(path) {
+    const st = await stat(path);
+    const info = {
+        id: basename(path, '.jsonl'),
+        path,
+        project: basename(join(path, '..')),
+        mtime: st.mtimeMs,
+        size: st.size,
+    };
+    const head = await readSlice(path, 0, Math.min(st.size, 256 * 1024));
+    for (const line of head.split('\n')) {
+        if (!line.startsWith('{'))
+            continue;
+        let r;
+        try {
+            r = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!info.cwd && r.cwd)
+            info.cwd = r.cwd;
+        if (r.type === 'ai-title' && r.aiTitle)
+            info.title = r.aiTitle;
+        if (!info.firstPrompt && r.type === 'user' && !r.isMeta && !r.isSidechain) {
+            const c = r.message?.content;
+            const t = typeof c === 'string' ? c : Array.isArray(c) ? c.filter((b) => b.type === 'text').map((b) => b.text).join('\n') : '';
+            if (t && !harnessNotice(t)) {
+                const p = cleanPrompt(t);
+                if (p)
+                    info.firstPrompt = truncate(p, 140);
+            }
+        }
+        if (info.cwd && info.firstPrompt && info.title)
+            break;
+    }
+    if (st.size > 256 * 1024) {
+        const tailLen = Math.min(st.size, 512 * 1024);
+        const tail = await readSlice(path, st.size - tailLen, tailLen);
+        const titles = [...tail.matchAll(/"aiTitle":"((?:[^"\\]|\\.)*)"/g)];
+        if (titles.length) {
+            try {
+                info.title = JSON.parse(`"${titles[titles.length - 1][1]}"`);
+            }
+            catch {
+                /* keep head title */
+            }
+        }
+    }
+    return info;
+}
+/** Recent sessions, newest first. With `cwd`, only that project's sessions. */
+export async function listSessions(opts = {}) {
+    const root = projectsDir();
+    let projects;
+    try {
+        projects = await readdir(root);
+    }
+    catch {
+        return [];
+    }
+    if (opts.cwd) {
+        const want = encodeCwd(opts.cwd).toLowerCase();
+        projects = projects.filter((p) => p.toLowerCase() === want);
+    }
+    const files = [];
+    for (const p of projects) {
+        let entries;
+        try {
+            entries = await readdir(join(root, p));
+        }
+        catch {
+            continue;
+        }
+        for (const f of entries) {
+            if (!f.endsWith('.jsonl'))
+                continue;
+            const path = join(root, p, f);
+            try {
+                files.push({ path, mtime: (await stat(path)).mtimeMs });
+            }
+            catch {
+                /* vanished */
+            }
+        }
+    }
+    files.sort((a, b) => b.mtime - a.mtime);
+    const out = [];
+    for (const f of files.slice(0, opts.limit ?? 30)) {
+        try {
+            out.push(await describeSession(f.path));
+        }
+        catch {
+            /* unreadable */
+        }
+    }
+    return out;
+}
+/** Resolve a session id (or id prefix) to its transcript path. */
+export async function findSession(idOrPath) {
+    if (idOrPath.endsWith('.jsonl'))
+        return idOrPath;
+    const root = projectsDir();
+    let projects = [];
+    try {
+        projects = await readdir(root);
+    }
+    catch {
+        return null;
+    }
+    for (const p of projects) {
+        let entries = [];
+        try {
+            entries = await readdir(join(root, p));
+        }
+        catch {
+            continue;
+        }
+        const hit = entries.find((f) => f.endsWith('.jsonl') && f.startsWith(idOrPath));
+        if (hit)
+            return join(root, p, hit);
+    }
+    return null;
+}
+function parseLines(lines, adapter) {
+    const out = [];
+    for (const l of lines) {
+        if (!l.startsWith('{'))
+            continue;
+        try {
+            out.push(...adapter.push(JSON.parse(l)));
+        }
+        catch {
+            /* a corrupt line must not stop the stream */
+        }
+    }
+    out.push(...adapter.flush());
+    return out;
+}
+/** Text of a transcript record's user message (string or text blocks). */
+function messageText(rec) {
+    const c = rec?.message?.content;
+    if (typeof c === 'string')
+        return c;
+    if (Array.isArray(c))
+        return c.map((b) => (b?.type === 'text' ? b.text : '')).join('');
+    return '';
+}
+/** Reads the first complete line of a file (a subagent's first record is its task). */
+async function firstLine(path) {
+    const fh = await open(path, 'r');
+    try {
+        const buf = Buffer.alloc(256 * 1024);
+        const { bytesRead } = await fh.read(buf, 0, buf.length, 0);
+        const text = buf.subarray(0, bytesRead).toString('utf8');
+        const nl = text.indexOf('\n');
+        return nl >= 0 ? text.slice(0, nl) : null;
+    }
+    finally {
+        await fh.close();
+    }
+}
+const norm = (s) => s.replace(/\s+/g, ' ').trim();
+/**
+ * Follows one Claude Code session: the main transcript plus its subagent transcripts.
+ *
+ * A subagent's transcript is written live, but its `.meta.json` (which names the parent
+ * Agent call) only appears when the subagent finishes. To show subagent work as it happens,
+ * a new subagent file is linked to its parent call by matching its first prompt against
+ * the `prompt` input of the Agent/Task calls seen in the main transcript.
+ */
+export class ClaudeSessionSource {
+    live;
+    key;
+    label;
+    path;
+    tailers = [];
+    subagents = new Set();
+    /** Agent/Task calls from the main transcript: tool_use id -> normalized prompt. */
+    agentCalls = new Map();
+    claimed = new Set();
+    timer = null;
+    scanning = false;
+    emit = () => { };
+    constructor(path, live = true) {
+        this.path = path;
+        this.key = `claude:${path.toLowerCase()}`;
+        this.label = basename(path, '.jsonl');
+        this.live = live;
+    }
+    async start(emit) {
+        this.emit = emit;
+        const main = new ClaudeCodeAdapter();
+        const t = new LineTailer(this.path, (lines) => {
+            const spawned = this.noteAgentCalls(lines);
+            const evs = parseLines(lines, main);
+            if (evs.length)
+                this.emit(evs);
+            if (spawned && this.live)
+                setTimeout(() => void this.scanSubagents(), 250);
+        });
+        this.tailers.push(t);
+        await t.start(this.live);
+        await this.scanSubagents();
+        if (this.live) {
+            this.timer = setInterval(() => void this.scanSubagents(), 1000);
+            this.timer.unref?.();
+        }
+    }
+    stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        for (const t of this.tailers)
+            t.stop();
+    }
+    noteAgentCalls(lines) {
+        let found = false;
+        for (const line of lines) {
+            if (!line.includes('"tool_use"') || !/"name":"(?:Agent|Task)"/.test(line))
+                continue;
+            try {
+                const rec = JSON.parse(line);
+                for (const b of rec?.message?.content ?? []) {
+                    if (b?.type === 'tool_use' && (b.name === 'Agent' || b.name === 'Task') && typeof b.input?.prompt === 'string') {
+                        this.agentCalls.set(b.id, norm(b.input.prompt));
+                        found = true;
+                    }
+                }
+            }
+            catch {
+                /* not a full record */
+            }
+        }
+        return found;
+    }
+    async parentOf(dir, f) {
+        try {
+            const meta = JSON.parse(await readFile(join(dir, f.replace(/\.jsonl$/, '.meta.json')), 'utf8'));
+            if (meta.toolUseId)
+                return meta.toolUseId;
+        }
+        catch {
+            /* meta not written yet: the subagent is still running */
+        }
+        try {
+            const line = await firstLine(join(dir, f));
+            if (!line)
+                return undefined;
+            const prompt = norm(messageText(JSON.parse(line)));
+            if (!prompt)
+                return undefined;
+            const open = [...this.agentCalls].filter(([id]) => !this.claimed.has(id));
+            const hit = open.find(([, p]) => p === prompt) ?? open.find(([, p]) => p.startsWith(prompt.slice(0, 200)) || prompt.startsWith(p.slice(0, 200)));
+            return hit?.[0];
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async scanSubagents() {
+        if (this.scanning)
+            return;
+        this.scanning = true;
+        try {
+            const dir = join(this.path.replace(/\.jsonl$/, ''), 'subagents');
+            let entries;
+            try {
+                entries = await readdir(dir);
+            }
+            catch {
+                return;
+            }
+            for (const f of entries.sort()) {
+                if (!f.endsWith('.jsonl') || this.subagents.has(f))
+                    continue;
+                // Compaction runs replay the conversation to summarise it: not a subagent.
+                if (f.startsWith('agent-acompact')) {
+                    this.subagents.add(f);
+                    continue;
+                }
+                const toolUseId = await this.parentOf(dir, f);
+                if (!toolUseId)
+                    continue; // retry on the next scan
+                this.subagents.add(f);
+                this.claimed.add(toolUseId);
+                const adapter = new ClaudeCodeAdapter(toolUseId);
+                const t = new LineTailer(join(dir, f), (lines) => {
+                    const evs = parseLines(lines, adapter);
+                    if (evs.length)
+                        this.emit(evs);
+                });
+                this.tailers.push(t);
+                await t.start(this.live);
+            }
+        }
+        finally {
+            this.scanning = false;
+        }
+    }
+}

package/dist/sources/source.js

@@ -0,0 +1 @@
+export {};

package/dist/sources/stdin.js

@@ -0,0 +1,74 @@
+import { ClaudeCodeAdapter } from "../adapters/claude-code.js";
+import { TextAdapter } from "../adapters/text.js";
+class JsonLinesAdapter {
+    name = 'claude-code';
+    inner = new ClaudeCodeAdapter();
+    buffer = '';
+    push(input) {
+        this.buffer += String(input);
+        const lines = this.buffer.split('\n');
+        this.buffer = lines.pop() ?? '';
+        return lines.flatMap((l) => this.parse(l));
+    }
+    flush() {
+        const out = this.parse(this.buffer);
+        this.buffer = '';
+        return out;
+    }
+    parse(l) {
+        const t = l.trim();
+        if (!t.startsWith('{'))
+            return [];
+        try {
+            return this.inner.push(JSON.parse(t));
+        }
+        catch {
+            return [];
+        }
+    }
+}
+export class StreamSource {
+    live = true;
+    key;
+    label;
+    stream;
+    format;
+    adapter = null;
+    pending = '';
+    constructor(stream, label = 'stdin', format = 'auto') {
+        this.stream = stream;
+        this.label = label;
+        this.key = `stream:${label}:${Date.now()}`;
+        this.format = format;
+    }
+    async start(emit) {
+        this.stream.setEncoding('utf8');
+        this.stream.on('data', (chunk) => {
+            if (!this.adapter) {
+                this.pending += chunk;
+                const first = this.pending.split('\n').find((l) => l.trim());
+                if (first === undefined || (!this.pending.includes('\n') && this.format === 'auto'))
+                    return;
+                const json = this.format === 'json' || (this.format === 'auto' && first.trim().startsWith('{'));
+                this.adapter = json ? new JsonLinesAdapter() : new TextAdapter();
+                chunk = this.pending;
+                this.pending = '';
+            }
+            const evs = this.adapter.push(chunk);
+            if (evs.length)
+                emit(evs);
+        });
+        this.stream.on('end', () => {
+            if (!this.adapter && this.pending) {
+                this.adapter = this.pending.trim().startsWith('{') ? new JsonLinesAdapter() : new TextAdapter();
+                emit(this.adapter.push(this.pending));
+            }
+            const evs = this.adapter?.flush() ?? [];
+            if (evs.length)
+                emit(evs);
+        });
+    }
+    stop() {
+        this.stream.pause();
+    }
+}

package/dist/sources/tail.js

@@ -0,0 +1,105 @@
+/**
+ * Incremental line reader for files that grow (live transcripts).
+ * Reads from a byte offset in chunks, keeps a partial trailing line until it completes,
+ * and reacts to both fs.watch notifications and a slow poll (fs.watch is unreliable on some platforms).
+ */
+import { open, stat } from 'node:fs/promises';
+import { watch } from 'node:fs';
+const CHUNK = 1 << 20;
+export class LineTailer {
+    offset = 0;
+    partial = '';
+    timer = null;
+    watcher = null;
+    reading = false;
+    again = false;
+    stopped = false;
+    decoder = new TextDecoder('utf-8');
+    path;
+    onLines;
+    pollMs;
+    constructor(path, onLines, pollMs = 500) {
+        this.path = path;
+        this.onLines = onLines;
+        this.pollMs = pollMs;
+    }
+    /** Read everything currently in the file, then keep following it. */
+    async start(follow = true) {
+        await this.read();
+        if (!follow || this.stopped)
+            return;
+        try {
+            this.watcher = watch(this.path, () => void this.read());
+            this.watcher.on('error', () => {
+                this.watcher?.close();
+                this.watcher = null;
+            });
+        }
+        catch {
+            /* polling still works */
+        }
+        this.timer = setInterval(() => void this.read(), this.pollMs);
+        this.timer.unref?.();
+    }
+    stop() {
+        this.stopped = true;
+        if (this.timer)
+            clearInterval(this.timer);
+        this.watcher?.close();
+    }
+    /** Read new bytes. Safe to call concurrently: overlapping calls coalesce. */
+    async read() {
+        if (this.stopped)
+            return;
+        if (this.reading) {
+            this.again = true;
+            return;
+        }
+        this.reading = true;
+        try {
+            do {
+                this.again = false;
+                await this.readOnce();
+            } while (this.again && !this.stopped);
+        }
+        finally {
+            this.reading = false;
+        }
+    }
+    async readOnce() {
+        let size;
+        try {
+            size = (await stat(this.path)).size;
+        }
+        catch {
+            return;
+        }
+        if (size < this.offset) {
+            // truncated or replaced: start over
+            this.offset = 0;
+            this.partial = '';
+            this.decoder = new TextDecoder('utf-8');
+        }
+        if (size === this.offset)
+            return;
+        const fh = await open(this.path, 'r');
+        try {
+            const buf = Buffer.allocUnsafe(CHUNK);
+            while (this.offset < size && !this.stopped) {
+                const { bytesRead } = await fh.read(buf, 0, Math.min(CHUNK, size - this.offset), this.offset);
+                if (bytesRead === 0)
+                    break;
+                this.offset += bytesRead;
+                const text = this.partial + this.decoder.decode(buf.subarray(0, bytesRead), { stream: true });
+                const lines = text.split('\n');
+                this.partial = lines.pop() ?? '';
+                const complete = lines.map((l) => (l.endsWith('\r') ? l.slice(0, -1) : l)).filter((l) => l.length > 0);
+                if (complete.length)
+                    this.onLines(complete);
+            }
+        }
+        finally {
+            await fh.close();
+        }
+    }
+}

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@vale-dinap/lucidly",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "See what your AI agent is doing, at a glance.",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "ai",
+    "agent",
+    "coding-agent",
+    "transcript",
+    "viewer",
+    "visualization",
+    "observability",
+    "cli"
+  ],
+  "homepage": "https://github.com/vale-dinap/lucidly#readme",
+  "bugs": {
+    "url": "https://github.com/vale-dinap/lucidly/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vale-dinap/lucidly.git"
+  },
+  "author": "Valerio Di Napoli",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "lucidly": "bin/lucidly.js"
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "scripts": {
+    "start": "node src/cli.ts",
+    "test": "node --test \"test/**/*.test.ts\"",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0"
+  },
+  "files": [
+    "bin/",
+    "dist/",
+    "web/",
+    "NOTICE"
+  ]
+}