@vale-dinap/lucidly 0.1.0 → 0.3.0

package/dist/core/engine.js

@@ -1,6 +1,6 @@
 const MAX_PATCH_LINES = 2000;
 const zeroUsage = () => ({ input: 0, output: 0, cacheRead: 0, cacheWrite: 0, responses: 0 });
-import { extractPlan, firstLine, hasDeviationCue, hasIntent, intentTitle, isSubstantivePrompt, isReply, endsWithQuestion, issueSummary, matchStep, sentences, similarity, stripMarkdown, tokens, truncate, } from "./text.js";
+import { extractPlan, firstLine, hasDeviationCue, hasIntent, intentTitle, isSubstantivePrompt, isHousekeeping, isReply, endsWithQuestion, lastQuestion, issueSummary, matchStep, sentences, similarity, stripMarkdown, tokens, truncate, } from "./text.js";
 const MAX_CHUNK = 256 * 1024;
 const MAX_CONTEXT_ITEMS = 12;
 /**
@@ -17,6 +17,8 @@ export class Engine {
     seq = 0;
     /** The main agent's last words asked the user something. */
     agentAsked = false;
+    /** ...and the question itself. */
+    agentQuestion;
     goalCtx = new Map();
     units = new Map();
     calls = new Map();
@@ -159,7 +161,9 @@ export class Engine {
                 row.diff = n.diff;
             if (n.files?.length && (n.kind === 'edit' || n.kind === 'write'))
                 row.files = n.files;
-            if (n.kind === 'command' && text) {
+            if (n.via)
+                row.via = n.via;
+            if ((n.kind === 'command' || n.via === 'command') && text) {
                 row.command = text.replace(/^(?:\$|PS>)\s?/, '');
                 if (n.detail)
                     row.short = n.detail.replace(/^\$\s?/, '');
@@ -429,7 +433,10 @@ export class Engine {
         }
         // A message sent while the agent is still in its turn is an interjection, not a new task.
         const midTurn = this.run.status === 'working';
-        this.run.status = 'working';
+        // /compact, /model...: no turn follows them, so the session (and its task) stays as it was.
+        const housekeeping = isHousekeeping(text);
+        if (!housekeeping)
+            this.run.status = 'working';
         const cur = this.currentGoal();
         // After the turn, a short message continues the task only if it answers the agent
         // ("yes", "go ahead", or anything after a question); "all done, pushed" is a new card.
@@ -440,18 +447,84 @@ export class Engine {
             this.addChunk(g.id, 'prompt', raw ?? text, ts, 'Prompt');
             return;
         }
-        this.setStatus(cur.id, 'active', ts);
+        if (!midTurn && !housekeeping)
+            return this.startRound(cur, text, ts, raw);
+        if (!housekeeping)
+            return this.interject(cur, text, ts, raw);
+        // A housekeeping command (/compact...) is a note where the task stands, not a message to the agent.
         const target = cur.unit ?? cur.current ?? cur.id;
         const n = this.newNode('activity', target, `You: ${truncate(text, 80)}`, { kind: 'user', status: 'done', startedAt: ts });
         this.addChunk(n.id, 'prompt', raw ?? text, ts, 'User reply');
         cur.lastTextChunk = null;
     }
+    /**
+     * A reply that continues a task after its turn ended starts a new round of it. The reply sits
+     * on the task itself, after the steps so far (and before a plan's steps still to come), keeping
+     * how the round before it ended; the work that follows goes into a step of its own.
+     */
+    startRound(g, text, ts, raw) {
+        const goal = this.touch(g.id);
+        const round = {
+            ...(goal.outcome ? { outcome: goal.outcome } : {}),
+            ...(g.interrupted ? { interrupted: true } : {}),
+            ...(this.agentAsked ? { asked: true } : {}),
+        };
+        this.closeSubtask(g, ts);
+        // The next action picks the next unfinished plan step, or starts a new step (see onToolStart).
+        g.current = null;
+        g.unit = null;
+        g.pending = null;
+        g.lastTextChunk = null;
+        g.interrupted = false;
+        this.userNode(g, text, ts, raw, { round });
+        delete goal.outcome;
+        delete goal.asked;
+        delete goal.question;
+        this.setStatus(g.id, 'active', ts);
+    }
+    /**
+     * A message sent while the agent works: like every message of yours, a node of its own on the
+     * task, after the steps so far. The work that follows goes into a new step, except that a plan
+     * step under way stays the current one until the plan moves on.
+     */
+    interject(g, text, ts, raw) {
+        this.closeSubtask(g, ts);
+        const step = g.current ? this.nodes.get(g.current) : undefined;
+        if (step && step.origin !== 'plan') {
+            if (step.status === 'active')
+                this.setStatus(step.id, 'done', ts);
+            g.current = null;
+            g.unit = null;
+        }
+        g.pending = null;
+        g.lastTextChunk = null;
+        this.userNode(g, text, ts, raw, {});
+        this.setStatus(g.id, 'active', ts);
+    }
+    /** A message of yours on the task itself: after the steps so far, before a plan's steps not started. */
+    userNode(g, text, ts, raw, extra) {
+        const goal = this.touch(g.id);
+        const n = this.newNode('activity', g.id, `You: ${truncate(text, 80)}`, { kind: 'user', status: 'done', startedAt: ts, ...extra });
+        const rest = goal.children.filter((c) => c !== n.id);
+        let at = rest.length;
+        while (at > 0) {
+            const c = this.nodes.get(rest[at - 1]);
+            if (!(c?.type === 'step' && (c.status === 'pending' || c.tentative)))
+                break;
+            at--;
+        }
+        rest.splice(at, 0, n.id);
+        goal.children = rest;
+        this.addChunk(n.id, 'prompt', raw ?? text, ts, 'User reply');
+    }
     // ───────────────────────────── narration
     onText(text, ts, scope) {
         if (!text.trim())
             return;
-        if (!scope)
+        if (!scope) {
             this.agentAsked = endsWithQuestion(text);
+            this.agentQuestion = this.agentAsked ? lastQuestion(text) : undefined;
+        }
         if (scope) {
             const n = this.scopes.get(scope);
             if (n) {
@@ -854,6 +927,7 @@ export class Engine {
                 tool: ev.tool,
                 detail: ev.detail,
                 files: ev.files,
+                ...(ev.via ? { via: ev.via } : {}),
                 status: 'active',
                 startedAt: ev.ts,
             });
@@ -862,7 +936,9 @@ export class Engine {
         if (ev.spawnsAgent)
             this.scopes.set(ev.callId, node.id);
         this.calls.set(ev.callId, { node: node.id, unit, tool: ev.tool, label: ev.label });
-        this.addChunk(node.id, 'tool', ev.raw ?? ev.detail ?? ev.label, ev.ts, ev.label);
+        const chunk = this.addChunk(node.id, 'tool', ev.raw ?? ev.detail ?? ev.label, ev.ts, ev.label);
+        if (ev.parts?.length && ev.parts.every((p) => p.text.length <= MAX_CHUNK))
+            this.chunks[chunk].parts = ev.parts;
         this.bump(unit, 'actions');
         this.addContext(unit, ev);
         const held = ev.spawnsAgent ? this.orphans.get(ev.callId) : undefined;
@@ -1023,6 +1099,17 @@ export class Engine {
             if (g.plan.length === 0 || isLastPlanned || !g.plan.includes(g.current))
                 this.setStatus(g.current, 'done', ts);
         }
+        if (this.agentAsked && !interrupted) {
+            goal.asked = true;
+            if (this.agentQuestion)
+                goal.question = this.agentQuestion;
+            else
+                delete goal.question;
+        }
+        else {
+            delete goal.asked;
+            delete goal.question;
+        }
         // The agent finished its turn: the task is done, unless it was cut short. A follow-up
         // reply reopens it (see onPrompt).
         this.setStatus(g.id, interrupted ? 'waiting' : 'done', ts);

package/dist/core/text.js

@@ -132,6 +132,10 @@ export function extractPlan(text, requireCue = false) {
     const cue = PLAN_CUE.test(lead);
     if ((!best.numbered || requireCue) && !cue)
         return null;
+    // Bullets that all open with a bold label ("**Rows:** the spotlight...") describe things, they
+    // aren't steps to take.
+    if (!best.numbered && best.items.every((s) => /^\*\*[^*]{1,60}?(?::\*\*|\*\*:)/.test(s.trim())))
+        return null;
     const items = best.items.map(cleanItem).filter((s) => s.length > 1);
     if (items.length < 2)
         return null;
@@ -200,6 +204,10 @@ const HOUSEKEEPING = /^\/(compact|clear|model|config|cost|context|status|help|me
  * A short message that answers the agent rather than giving it something new: an approval,
  * a choice, or anything at all when the agent's last words asked a question.
  */
+/** A slash command that manages the session (/compact, /model...) rather than asking for anything. */
+export function isHousekeeping(text) {
+    return HOUSEKEEPING.test(text.trim());
+}
 export function isReply(text, agentAsked) {
     const t = text.trim();
     // Housekeeping commands never start a task; any other slash command is a new request.
@@ -215,6 +223,11 @@ export function isReply(text, agentAsked) {
 export function endsWithQuestion(text) {
     return /\?\s*(\*+|_+|\)|")?\s*$/.test(text.trim());
 }
+/** The question the agent's words end with: their last sentence, without its formatting. */
+export function lastQuestion(text) {
+    const q = sentences(text).at(-1);
+    return q && /\?\W*$/.test(q) ? truncate(q.replace(/(?<=\?)\W*$/, ''), 200) : undefined;
+}
 export function isSubstantivePrompt(text) {
     const t = text.trim();
     const words = t.split(/\s+/).filter(Boolean).length;

package/dist/server/server.js

@@ -8,7 +8,7 @@ import { readFile, readdir, stat } from 'node:fs/promises';
 import { extname, normalize, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { RunSession } from "./session.js";
-import { ClaudeSessionSource, findSession, listSessions } from "../sources/claude-sessions.js";
+import { ClaudeSessionSource, LIVE_MS, findSession, listSessions } from "../sources/claude-sessions.js";
 const WEB_DIR = fileURLToPath(new URL('../../web/', import.meta.url));
 const SRC_DIR = fileURLToPath(new URL('../', import.meta.url));
 const STARTED = Date.now();
@@ -33,7 +33,6 @@ async function codeChangedSince(t) {
     return false;
 }
 const MAX_BODY = 512 * 1024 * 1024;
-const LIVE_MS = 3 * 60 * 1000;
 const TYPES = {
     '.html': 'text/html; charset=utf-8',
     '.js': 'text/javascript; charset=utf-8',

package/dist/sources/claude-sessions.js

@@ -15,6 +15,8 @@ export function projectsDir() {
 export function encodeCwd(cwd) {
     return cwd.replace(/[^a-zA-Z0-9]/g, '-');
 }
+/** A session written to within this long counts as live (the agent is, or was just, at work). */
+export const LIVE_MS = 3 * 60 * 1000;
 async function readSlice(path, start, length) {
     const fh = await open(path, 'r');
     try {
@@ -26,9 +28,20 @@ async function readSlice(path, start, length) {
         await fh.close();
     }
 }
+// Descriptions by path, reused while the file is unchanged: the session list refreshes every few
+// seconds while it is open, and only the sessions written to since are read again.
+const described = new Map();
 /** 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 known = described.get(path);
+    if (known && known.mtime === st.mtimeMs && known.size === st.size)
+        return known;
+    const info = await readDescription(path, st);
+    described.set(path, info);
+    return info;
+}
+async function readDescription(path, st) {
     const info = {
         id: basename(path, '.jsonl'),
         path,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vale-dinap/lucidly",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "See what your AI agent is doing, at a glance.",
   "keywords": [
     "claude",
@@ -46,6 +46,7 @@
     "bin/",
     "dist/",
     "web/",
-    "NOTICE"
+    "NOTICE",
+    "CHANGELOG.md"
   ]
 }