@pencil-agent/nano-pencil 1.14.2 → 1.14.3

package/dist/packages/mem-core/extension.js

@@ -10,11 +10,11 @@ import { Type } from "@sinclair/typebox";
 import { SessionManager } from "@pencil-agent/nano-pencil";
 import { NanoMemEngine } from "./engine.js";
 import { reportDiagnostic } from "./diagnostics.js";
-import { readDreamLockMtimeMs, rollbackDreamLock, stampDreamLock, tryAcquireDreamLock } from "./dream-lock.js";
+import { readDreamLockMtimeMs, rollbackDreamLock, tryAcquireDreamLock } from "./dream-lock.js";
 import { renderFullInsightsHtml } from "./full-insights-html.js";
 import { hasParseableLlmJson } from "./llm-json.js";
 import { extractTags } from "./scoring.js";
-import { loadEntries, loadMeta } from "./store.js";
+import { loadMeta } from "./store.js";
 const extractedItemSchema = Type.Object({
     type: Type.Union([
         Type.Literal("preference"),
@@ -66,6 +66,9 @@ const memoryJsonContracts = {
         schema: Type.Object({ recommendations: Type.Array(Type.String()) }),
     },
 };
+const dreamCommands = ["run", "status", "stop"];
+const memoryEditFields = ["summary", "detail", "content", "salience", "ttl", "retention"];
+const memoryResolveActions = ["merge", "demote", "forget", "mark-situational"];
 function withTimeout(promise, timeoutMs) {
     return new Promise((resolve) => {
         const timer = setTimeout(() => resolve(undefined), timeoutMs);
@@ -314,25 +317,51 @@ async function readMetaLastConsolidationMs(memoryDir) {
         return 0;
     }
 }
-async function countBaseMemoryEntries(memoryDir) {
-    const [knowledge, lessons, events] = await Promise.all([
-        loadEntries(join(memoryDir, "knowledge.json")),
-        loadEntries(join(memoryDir, "lessons.json")),
-        loadEntries(join(memoryDir, "events.json")),
-    ]);
-    return knowledge.length + lessons.length + events.length;
+function formatElapsed(ms) {
+    const seconds = Math.max(0, Math.round(ms / 1000));
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    const remainder = seconds % 60;
+    return remainder > 0 ? `${minutes}m ${remainder}s` : `${minutes}m`;
+}
+function describeDreamSource(source) {
+    return source === "auto" ? "automatic" : source === "manual" ? "manual" : "not started";
 }
-function formatDreamSummary(params) {
-    const { added, candidates, memoryDir } = params;
-    if (candidates <= 0) {
-        return `Dream: no consolidation needed.\nMemory dir: ${memoryDir}`;
+function formatDreamStatus(task, memoryDir) {
+    const lines = [`Memory refresh: ${task.status}`];
+    lines.push(`Mode: ${describeDreamSource(task.source)}`);
+    if (task.startedAtMs) {
+        const endedAt = task.endedAtMs ?? Date.now();
+        lines.push(`${task.status === "running" ? "Running for" : "Duration"}: ${formatElapsed(endedAt - task.startedAtMs)}`);
     }
-    return [
-        `Dream: consolidation completed.`,
-        `Candidates processed: ${candidates}`,
-        `New memories added: ${added}`,
-        `Memory dir: ${memoryDir}`,
-    ].join("\n");
+    if (task.sessionsReviewing)
+        lines.push(`Reviewing: ${task.sessionsReviewing} past sessions`);
+    if (task.result) {
+        lines.push(`Reviewed: ${task.result.episodesConsidered} past sessions`);
+        lines.push(`Memories: ${task.result.added} added, ${task.result.updated} updated, ${task.result.skipped} skipped`);
+    }
+    if (task.status === "running")
+        lines.push("Stop: /dream stop");
+    if (task.lastError)
+        lines.push(`Needs attention: ${task.lastError}`);
+    lines.push(`Saved in: ${memoryDir}`);
+    return lines.join("\n");
+}
+function formatDreamResult(result, memoryDir) {
+    const sample = result.entries
+        .slice(0, 5)
+        .map((entry) => `- [${entry.type}] ${entry.name || entry.summary || entry.id}`)
+        .join("\n");
+    const lines = [
+        "Memory refreshed.",
+        `Reviewed: ${result.stats.episodesConsidered} past sessions`,
+        `Memories: ${result.stats.added} added, ${result.stats.updated} updated, ${result.stats.skipped} skipped`,
+        `Saved in: ${memoryDir}`,
+    ];
+    if (sample)
+        lines.push("", "Examples:", sample);
+    return lines.join("\n");
 }
 export default function nanomemExtension(api) {
     const project = getProject();
@@ -440,67 +469,100 @@ export default function nanomemExtension(api) {
             console.error("[nanomem] startup maintenance failed:", error);
         }
     });
-    const maybeRunAutoDream = async (ctx) => {
-        const cfg = getDreamConfig(ctx);
-        if (!cfg.enabled)
-            return;
-        if (dreamTask.status === "running")
-            return;
-        const lastAtMs = Math.max(await readMetaLastConsolidationMs(memoryDir), await readDreamLockMtimeMs(lockPath));
-        const hoursSince = (Date.now() - lastAtMs) / 3_600_000;
-        if (lastAtMs > 0 && hoursSince < cfg.minHours)
-            return;
-        const scanIntervalMs = cfg.scanIntervalMinutes * 60_000;
-        if (Date.now() - lastSessionScanAtMs < scanIntervalMs)
-            return;
-        lastSessionScanAtMs = Date.now();
-        const touchedCount = await SessionManager.countTouchedSince(ctx.cwd, lastAtMs, {
-            excludeBasename: sessionId,
-        });
-        if (touchedCount < cfg.minSessions)
+    const runDreamTask = async (ctx, source, options = {}) => {
+        if (dreamTask.status === "running") {
+            if (options.notifyWhenDone) {
+                ctx.ui.notify("Memory refresh is already running. Use /dream status to check progress.", "info");
+            }
             return;
+        }
+        const cfg = getDreamConfig(ctx);
         const prior = await tryAcquireDreamLock(lockPath, cfg.holderStaleMinutes * 60_000);
-        if (prior === null)
+        if (prior === null) {
+            if (options.notifyWhenDone) {
+                ctx.ui.notify("Memory refresh is already running in another session. Try /dream status later.", "info");
+            }
             return;
+        }
         const abort = new AbortController();
         dreamTask = {
             status: "running",
+            source,
             startedAtMs: Date.now(),
-            sessionsReviewing: touchedCount,
+            sessionsReviewing: options.sessionsReviewing,
             priorLockMtimeMs: prior,
             abort,
         };
-        ctx.ui.setStatus("nanomem", `Dream: running (${touchedCount} sessions)`);
+        ctx.ui.setStatus("nanomem", options.sessionsReviewing ? `Memory refresh: running (${options.sessionsReviewing} sessions)` : "Memory refresh: running");
+        bindLlm(ctx);
         try {
             const result = await engine.consolidateDetailed({ signal: abort.signal });
             dreamTask = {
                 status: "completed",
+                source,
                 startedAtMs: dreamTask.startedAtMs,
                 endedAtMs: Date.now(),
-                sessionsReviewing: touchedCount,
+                sessionsReviewing: options.sessionsReviewing,
+                result: result.stats,
             };
-            ctx.ui.setStatus("nanomem", `Dream: completed (+${result.stats.added})`);
-            if (result.stats.added + result.stats.updated > 0 && ctx.hasUI) {
-                ctx.ui.notify(`Dream completed: +${result.stats.added} added, ${result.stats.updated} updated`, "info");
+            ctx.ui.setStatus("nanomem", `Memory refresh: done (+${result.stats.added})`);
+            if (options.notifyWhenDone || (ctx.hasUI && result.stats.added + result.stats.updated > 0)) {
+                ctx.ui.notify(formatDreamResult(result, memoryDir), "info");
             }
         }
-        catch (e) {
-            if (abort.signal.aborted || (e instanceof Error && e.message === "AbortError")) {
-                // kill path handles rollback
+        catch (error) {
+            if (abort.signal.aborted || (error instanceof Error && error.message === "AbortError")) {
+                if (dreamTask.status !== "killed") {
+                    dreamTask = {
+                        status: "killed",
+                        source,
+                        startedAtMs: dreamTask.startedAtMs,
+                        endedAtMs: Date.now(),
+                        sessionsReviewing: options.sessionsReviewing,
+                    };
+                    await rollbackDreamLock(lockPath, prior);
+                    ctx.ui.setStatus("nanomem", "Memory refresh: stopped");
+                }
                 return;
             }
+            const message = error instanceof Error ? error.message : String(error);
             dreamTask = {
                 status: "failed",
+                source,
                 startedAtMs: dreamTask.startedAtMs,
                 endedAtMs: Date.now(),
-                sessionsReviewing: touchedCount,
-                lastError: e instanceof Error ? e.message : String(e),
+                sessionsReviewing: options.sessionsReviewing,
+                lastError: message,
                 priorLockMtimeMs: prior,
             };
-            ctx.ui.setStatus("nanomem", "Dream: failed");
+            ctx.ui.setStatus("nanomem", "Memory refresh: failed");
             await rollbackDreamLock(lockPath, prior);
+            if (options.notifyWhenDone || ctx.hasUI) {
+                ctx.ui.notify(`Memory refresh failed.\nNeeds attention: ${message}`, "error");
+            }
         }
     };
+    const maybeRunAutoDream = async (ctx) => {
+        const cfg = getDreamConfig(ctx);
+        if (!cfg.enabled)
+            return;
+        if (dreamTask.status === "running")
+            return;
+        const lastAtMs = Math.max(await readMetaLastConsolidationMs(memoryDir), await readDreamLockMtimeMs(lockPath));
+        const hoursSince = (Date.now() - lastAtMs) / 3_600_000;
+        if (lastAtMs > 0 && hoursSince < cfg.minHours)
+            return;
+        const scanIntervalMs = cfg.scanIntervalMinutes * 60_000;
+        if (Date.now() - lastSessionScanAtMs < scanIntervalMs)
+            return;
+        lastSessionScanAtMs = Date.now();
+        const touchedCount = await SessionManager.countTouchedSince(ctx.cwd, lastAtMs, {
+            excludeBasename: sessionId,
+        });
+        if (touchedCount < cfg.minSessions)
+            return;
+        await runDreamTask(ctx, "auto", { sessionsReviewing: touchedCount });
+    };
     api.on("turn_end", async (_event, ctx) => {
         // Never block turn lifecycle
         void maybeRunAutoDream(ctx).catch(() => { });
@@ -591,50 +653,41 @@ export default function nanomemExtension(api) {
         }
     });
     api.registerCommand("dream", {
-        description: "Consolidate NanoMem episodes into durable memories. Usage: /dream [run|stop|status]",
+        description: "Refresh long-term NanoMem memories. Usage: /dream [run|status|stop]",
+        getArgumentCompletions: (argumentPrefix) => {
+            const prefix = argumentPrefix.trim().toLowerCase();
+            const matches = dreamCommands.filter((command) => command.startsWith(prefix));
+            if (matches.length === 0)
+                return null;
+            return matches.map((command) => ({ value: command, label: command }));
+        },
         handler: async (args, ctx) => {
             const cmd = (args || "").trim().toLowerCase();
             if (cmd === "stop" || cmd === "kill" || cmd === "cancel") {
                 if (dreamTask.status !== "running" || !dreamTask.abort) {
-                    ctx.ui.notify("Dream: no background task is running.", "info");
+                    ctx.ui.notify("No memory refresh is running.", "info");
                     return;
                 }
+                const prior = dreamTask.priorLockMtimeMs;
                 dreamTask.abort.abort();
                 dreamTask.status = "killed";
                 dreamTask.endedAtMs = Date.now();
-                ctx.ui.setStatus("nanomem", "Dream: killed");
-                if (typeof dreamTask.priorLockMtimeMs === "number") {
-                    await rollbackDreamLock(lockPath, dreamTask.priorLockMtimeMs);
+                ctx.ui.setStatus("nanomem", "Memory refresh: stopped");
+                if (typeof prior === "number") {
+                    await rollbackDreamLock(lockPath, prior);
                 }
-                ctx.ui.notify("Dream: background task killed and lock rolled back.", "info");
+                ctx.ui.notify("Memory refresh stopped. You can run /dream again when ready.", "info");
                 return;
             }
             if (cmd === "status") {
-                const status = dreamTask.status;
-                const sessions = dreamTask.sessionsReviewing ?? 0;
-                const err = dreamTask.lastError ? `\nError: ${dreamTask.lastError}` : "";
-                ctx.ui.notify(`Dream status: ${status}${sessions ? ` (${sessions} sessions)` : ""}${err}`, "info");
+                ctx.ui.notify(formatDreamStatus(dreamTask, memoryDir), "info");
                 return;
             }
-            // Manual run: not gate-checked and not blocked by lock. Always stamps lock to suppress immediate auto-dream.
-            await stampDreamLock(lockPath);
-            bindLlm(ctx);
-            const result = await engine.consolidateDetailed();
-            const sample = result.entries
-                .slice(0, 5)
-                .map((e) => `- [${e.type}] ${e.name || e.summary || e.id}`)
-                .join("\n");
-            const summary = [
-                `Dream: consolidation completed.`,
-                `Episodes considered: ${result.stats.episodesConsidered}`,
-                `Added: ${result.stats.added} | Updated: ${result.stats.updated} | Skipped: ${result.stats.skipped}`,
-                `Memory dir: ${memoryDir}`,
-                sample ? "" : "",
-                sample ? `\nExamples:\n${sample}` : "",
-            ]
-                .filter((x) => x !== "")
-                .join("\n");
-            ctx.ui.notify(summary, "info");
+            if (cmd && cmd !== "run") {
+                ctx.ui.notify("Usage: /dream [run|status|stop]", "warning");
+                return;
+            }
+            await runDreamTask(ctx, "manual", { notifyWhenDone: true });
         },
     });
     api.registerCommand("mem-search", {
@@ -694,11 +747,11 @@ export default function nanomemExtension(api) {
         }
     };
     api.registerCommand("mem-insights", {
-        description: "Generate NanoMem full insights HTML report (uses LLM when available)",
+        description: "Create a readable NanoMem insights HTML report",
         handler: runMemInsights,
     });
     api.registerCommand("mem-align", {
-        description: "Show which stable memories and current states are shaping the agent",
+        description: "Show which memories are shaping the current agent behavior",
         handler: async (_args, ctx) => {
             const snapshot = await engine.getAlignmentSnapshot();
             const topIdentity = snapshot.identityCore
@@ -718,7 +771,7 @@ export default function nanomemExtension(api) {
         },
     });
     api.registerCommand("mem-review", {
-        description: "Review the highest-risk memory conflicts and suggested actions",
+        description: "Review memory conflicts and suggested actions",
         handler: async (_args, ctx) => {
             const snapshot = await engine.getAlignmentSnapshot();
             const topConflicts = snapshot.conflicts.slice(0, 3);
@@ -733,7 +786,14 @@ export default function nanomemExtension(api) {
         },
     });
     api.registerCommand("mem-edit", {
-        description: "Edit a memory entry by ID. Usage: /mem-edit <id> <field> <value>",
+        description: "Edit one memory by ID. Usage: /mem-edit <id> <field> <value>",
+        getArgumentCompletions: (argumentPrefix) => {
+            const prefix = argumentPrefix.trim().toLowerCase();
+            const values = memoryEditFields
+                .filter((value) => value.startsWith(prefix))
+                .map((value) => ({ value, label: value }));
+            return values.length > 0 ? values : null;
+        },
         handler: async (args, ctx) => {
             const parts = (args || "").trim().split(/\s+/);
             const [id, field, ...rest] = parts;
@@ -751,6 +811,13 @@ export default function nanomemExtension(api) {
     });
     api.registerCommand("mem-resolve", {
         description: "Resolve a memory conflict. Usage: /mem-resolve <aId> <bId> [merge|demote|forget|mark-situational]",
+        getArgumentCompletions: (argumentPrefix) => {
+            const prefix = argumentPrefix.trim().toLowerCase();
+            const values = memoryResolveActions
+                .filter((value) => value.startsWith(prefix))
+                .map((value) => ({ value, label: value }));
+            return values.length > 0 ? values : null;
+        },
         handler: async (args, ctx) => {
             const [aId, bId, action] = (args || "").trim().split(/\s+/);
             if (!aId || !bId) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pencil-agent/nano-pencil",
-  "version": "1.14.2",
+  "version": "1.14.3",
   "description": "CLI writing agent with read, bash, edit, write tools and session management. Supports DashScope and Ali Token Plan. Soul enabled by default for AI personality evolution.",
   "type": "module",
   "bin": {
@@ -49,7 +49,7 @@
     "test:team": "node --test --import tsx test/team-parser.test.ts test/team-runtime.test.ts",
     "test:plan": "node --test --import tsx test/plan-mode.test.ts",
     "test:utils": "node --test --import tsx test/logger.test.ts",
-    "test:commands": "node --test --import tsx test/slash-command-catalog.test.ts",
+    "test:commands": "node --test --import tsx test/slash-command-catalog.test.ts test/extension-command-completions.test.ts",
     "test:security": "node --test --import tsx test/security-audit.test.ts",
     "test:tools": "node --test --import tsx test/workspace-write-guard.test.ts test/read-tool.test.ts test/tool-window-validation.test.ts test/bash-sandbox.test.ts",
     "test:presence": "node --test --import tsx test/presence-opening.test.ts",