@nanhara/hara 0.116.0 → 0.117.0

package/CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to `@nanhara/hara`.
 > Versioning (pre-1.0, SemVer-style): the **minor** (middle) number bumps for a **new feature**; the
 > **patch** (last) number bumps for **optimizations/fixes of existing features**.
 
+## 0.117.0 — serve batch 3: context watermark · compact · rewind · fuzzy file search
+
+Codex-desktop parity for the conversation-hygiene set — everything a client needs to keep a long
+session healthy without dropping to the CLI:
+
+- **Context watermark everywhere.** Every `session.send` result and `event.turn_end` now carries
+  `ctx: { lastInput, window, pct }` — how full the model's window was on the last turn. Clients
+  render a live meter with zero extra round-trips. `session.context` returns the same watermark
+  plus the spend breakdown (your messages / assistant / per-tool) on demand.
+- **`session.compact`** — the CLI's `/compact`, serve-side: summarize-and-replace with the same
+  8-section brief, working-memory notes kept on the session, and the recently-touched-file restore
+  (limited to files under the session's own cwd — serve is multi-session; nothing leaks across
+  projects). Busy-guarded like a turn.
+- **`session.rewind`** — fork the thread back to before the n-th-most-recent user turn (codex
+  `thread/rollback`). History-only; file edits are not reverted.
+- **`files.search`** — fuzzy project-file lookup (git-aware listing + the CLI's fuzzy ranker),
+  powering @-mention autocomplete in the desktop composer. Resolves the search root from an
+  explicit `cwd` or a `sessionId`.
+
 ## 0.116.0 — the desktop-grade serve protocol (models · automation · rename/archive · capabilities)
 
 - **Session source stamping.** Sessions now record WHO created them (`interactive` / `gateway` / `cron`,

package/dist/agent/compact.js

@@ -25,6 +25,17 @@ export const COMPACT_SYSTEM = "Summarize the conversation so far into a structur
     "7. All user messages — EVERY user message so far (excluding tool results), verbatim and in order; abbreviate only huge pasted blobs with […]. These are the ground truth of intent.\n" +
     "8. Next step — the immediate next action, INCLUDING a direct verbatim quote of the user's most recent request so there is no drift.\n" +
     "Be specific and concrete. Drop the <analysis>; output only the headed summary.";
+/** Working-memory notes distilled from a compaction summary — short lines that survive the history wipe
+ *  (stored on SessionMeta.workingSet, injected into subsequent turns). Shared by the CLI /compact path
+ *  and serve's session.compact. */
+export function workingSetFromSummary(s) {
+    return s
+        .split("\n")
+        .map((l) => l.replace(/^[-*\d.\s]+/, "").trim())
+        .filter((l) => l.length > 3)
+        .slice(0, 12)
+        .map((l) => l.slice(0, 140));
+}
 /** Post-compaction file restore (Claude Code's TW5): re-attach the CURRENT content of the files the
  *  conversation was just working with, so the summary isn't the model's only anchor — it doesn't have
  *  to re-read its own working set next turn (and can't act on a stale memory of an edited file).

package/dist/index.js

@@ -24,7 +24,7 @@ import { clearEnrollment, enrollDevice, heartbeat, syncOrgRoles } from "./org-fl
 import { loadActiveProfile, listProfiles, useProfile, addProfile, upsertProfile, removeProfile, setModel as setProfileModel, resetModel as resetProfileModel, getProfile, effectiveModel, routingLabel, routeHost, activeId, resolveActive, setFlagOverride, writePin, removePin, pinFilePath, DEFAULT_ORG_ID, PERSONAL_ID, } from "./profile/profile.js";
 import { loadPermissionRules, scaffoldPermissions, globalPermissionsPath, projectPermissionsPath } from "./security/permissions.js";
 import { routingProvider } from "./agent/route.js";
-import { shouldAutoCompact, shouldAutoCompactTokens, AUTO_COMPACT_TOKEN_CAP, COMPACT_SYSTEM, buildFileRestore } from "./agent/compact.js";
+import { shouldAutoCompact, shouldAutoCompactTokens, AUTO_COMPACT_TOKEN_CAP, COMPACT_SYSTEM, buildFileRestore, workingSetFromSummary } from "./agent/compact.js";
 import { recentTouched } from "./agent/touched.js";
 import { INTERJECT_PREFIX } from "./agent/reminders.js";
 import { checkForUpdate } from "./update-check.js";
@@ -758,13 +758,8 @@ const MEMORY_DISTILL_SYSTEM = "You consolidate an agent's short-term daily memor
     "conventions / user preferences from the logs that are NOT already captured, and persist each with " +
     "memory_write (target=memory, or target=user for preferences; pick the right scope=project|global). " +
     "Skip the ephemeral, the one-off, and anything already known. Be terse and de-duplicated. Then reply DONE.";
-// COMPACT_SYSTEM (the 8-section brief) lives in agent/compact.ts so tests can pin its structure.
-const workingSetFromSummary = (s) => s
-    .split("\n")
-    .map((l) => l.replace(/^[-*\d.\s]+/, "").trim())
-    .filter((l) => l.length > 3)
-    .slice(0, 12)
-    .map((l) => l.slice(0, 140));
+// COMPACT_SYSTEM (the 8-section brief) + workingSetFromSummary live in agent/compact.ts so tests can
+// pin their structure and serve's session.compact shares the exact same distillation.
 /** Summarize the conversation and replace history with the summary (keeping working-memory notes). Shared by
  *  /compact (manual) and auto-compaction. Returns the summary, or null on failure / nothing to do. */
 async function compactConversation(provider, history, meta, stats) {

package/dist/serve/protocol.js

@@ -8,7 +8,8 @@
 //   session.list      {cwd?}                     → {sessions:[{id,title,cwd,model,updatedAt}]}
 //   session.create    {cwd?,approval?}           → {sessionId,model}
 //   session.resume    {sessionId}                → {sessionId,model,history:[{role,text}]}
-//   session.send      {sessionId,text}           → (streams events, then) {reply,usage}
+//   session.send      {sessionId,text,images?}   → (streams events, then) {reply,usage}
+//                      images: [{path,mediaType?}] — pasted screenshots etc., inlined for vision models
 //   session.interrupt {sessionId}                → {}
 //   approval.reply    {approvalId,allow,always?}  → {}
 //   plugins.list      {}                          → {plugins:[{name,version,description,enabled,skills,agents,mcpServers}]}
@@ -17,6 +18,9 @@
 //   automation.list   {}                          → {jobs:[{id,name,mode,enabled,lastRunAt,lastStatus,…}],
 //                                                    sessions:[{id,title,source,sourceName,updatedAt,…}]}
 //   models.list       {}                          → {models:[…], current, effortLevels:[…]}
+//   automation.add    {name,schedule,task,mode?,cwd?,tz?} → {id,name,schedule}
+//   automation.toggle {id,enabled}                → {id,enabled}
+//   automation.delete {id}                        → {id,deleted}
 //   session.rename    {sessionId,title}           → {sessionId,title}
 //   session.archive   {sessionId,archived}        → {sessionId,archived}   (list hides archived unless {archived:true})
 //   session.set-model {sessionId,model?,effort?}  → {sessionId,model,effort} (next turn; refused mid-turn)

package/dist/serve/server.js

@@ -5,17 +5,25 @@
 // (no import cycle back into the CLI entry).
 import { WebSocketServer } from "ws";
 import { randomBytes, randomUUID, timingSafeEqual, createHash } from "node:crypto";
-import { writeFileSync, unlinkSync, mkdirSync } from "node:fs";
+import { writeFileSync, unlinkSync, mkdirSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import "../tools/all.js"; // register the full built-in toolset — serve must work as a standalone entry
 import { runAgent } from "../agent/loop.js";
+import { COMPACT_SYSTEM, buildFileRestore, workingSetFromSummary } from "../agent/compact.js";
+import { rewindTo } from "../agent/rewind.js";
+import { analyzeContext } from "../agent/context-report.js";
+import { recentTouched } from "../agent/touched.js";
+import { contextWindow, ctxPctFor } from "../statusbar.js";
+import { listProjectFiles } from "../fs-walk.js";
+import { fuzzyRank } from "../fuzzy.js";
 import { loadAgentsMd } from "../context/agents-md.js";
 import { expandMentions } from "../context/mentions.js";
 import { memoryDigest } from "../memory/store.js";
 import { listInstalled, enabledPlugins, setPluginEnabled } from "../plugins/plugins.js";
 import { loadSkillIndex } from "../skills/skills.js";
-import { loadJobs } from "../cron/store.js";
+import { loadJobs, saveJobs, addJob } from "../cron/store.js";
+import { parseSchedule, describeSchedule } from "../cron/schedule.js";
 import { SessionHub, realStore } from "./sessions.js";
 import { parseFrame, rpcResult, rpcError, rpcNotify, ERR, PROTOCOL_VERSION } from "./protocol.js";
 const APPROVAL_TIMEOUT_MS = 300_000; // an unanswered approval denies after 5 min (never hangs a turn)
@@ -70,7 +78,7 @@ export async function startServe(opts, deps) {
         writeFileSync(discoveryPath, JSON.stringify({ host: opts.host, port, token, pid: process.pid, version: deps.version }, null, 2), { mode: 0o600 });
     }
     /** Run one turn on a session, streaming events to all authed clients. */
-    const runTurn = async (s, text) => {
+    const runTurn = async (s, text, images) => {
         const sessionId = s.meta.id;
         s.busy = true;
         s.abort = new AbortController();
@@ -96,8 +104,9 @@ export async function startServe(opts, deps) {
             broadcast("approval.request", { sessionId, approvalId, question: q });
         });
         try {
-            // @file mentions expand to file contents, same as the CLI (`@src/foo.ts` in the composer works)
-            s.history.push({ role: "user", content: expandMentions(text, s.meta.cwd) });
+            // @file mentions expand to file contents, same as the CLI (`@src/foo.ts` in the composer works).
+            // Pasted images ride along as NeutralMsg.images — a vision-capable model sees them inline.
+            s.history.push({ role: "user", content: expandMentions(text, s.meta.cwd), ...(images && images.length ? { images } : {}) });
             await runAgent(s.history, {
                 provider: s.provider,
                 ctx: {
@@ -118,14 +127,57 @@ export async function startServe(opts, deps) {
             hub.save(s);
             const usage = { input: s.stats.input - before.input, output: s.stats.output - before.output };
             const reply = lastAssistantText(s.history);
-            broadcast("event.turn_end", { sessionId, reply, usage });
-            return { reply, usage };
+            // context watermark rides along with every turn end (codex thread/tokenUsage/updated pattern) —
+            // clients render a meter without an extra round-trip.
+            const ctx = ctxOf(s);
+            broadcast("event.turn_end", { sessionId, reply, usage, ctx });
+            return { reply, usage, ctx };
         }
         finally {
             s.busy = false;
             s.abort = null;
         }
     };
+    /** Context watermark for a session: how full the model's window was on the last turn. */
+    const ctxOf = (s) => {
+        const lastInput = s.stats.lastInput ?? 0;
+        return { lastInput, window: contextWindow(s.meta.model), pct: ctxPctFor(s.meta.model, lastInput) };
+    };
+    /** Summarize + replace a session's history — the CLI's /compact, serve-side (codex thread/compact).
+     *  Mirrors index.ts compactConversation; the file restore is limited to files under the session's own
+     *  cwd because serve is multi-session (recentTouched is process-wide and must not leak across projects). */
+    const compactSession = async (s) => {
+        const r = await s.provider.turn({
+            system: COMPACT_SYSTEM,
+            history: [...s.history, { role: "user", content: "Summarize our conversation so far per the instructions." }],
+            tools: [],
+            onText: () => { },
+        });
+        if (r.stop === "error")
+            return null;
+        const summary = r.text.trim();
+        if (!summary)
+            return null;
+        s.meta.workingSet = workingSetFromSummary(summary);
+        s.history.length = 0;
+        s.history.push({ role: "user", content: `Summary of our conversation so far (continue from here):\n\n${summary}` });
+        const touched = recentTouched(20).filter((f) => f.startsWith(s.meta.cwd)).slice(0, 5);
+        const restore = buildFileRestore(touched, (f) => {
+            try {
+                return readFileSync(f, "utf8");
+            }
+            catch {
+                return null;
+            }
+        });
+        if (restore)
+            s.history.push({ role: "user", content: restore });
+        s.stats.input += r.usage?.input ?? 0;
+        s.stats.output += r.usage?.output ?? 0;
+        s.stats.lastInput = r.usage?.input ?? 0; // ctx% now reflects the (small) summary
+        hub.save(s);
+        return summary;
+    };
     wss.on("connection", (ws) => {
         ws.on("message", async (raw) => {
             const parsed = parseFrame(String(raw));
@@ -145,7 +197,9 @@ export async function startServe(opts, deps) {
                     // (client-declared) is accepted and currently unused — reserved for opt-outs/experimental gating.
                     const methods = [
                         "session.list", "session.create", "session.resume", "session.send", "session.interrupt", "session.set-model",
-                        "approval.reply", "plugins.list", "plugins.set", "skills.list", "automation.list", "models.list",
+                        "session.rename", "session.archive", "session.compact", "session.rewind", "session.context",
+                        "approval.reply", "plugins.list", "plugins.set", "skills.list", "models.list", "files.search",
+                        "automation.list", "automation.add", "automation.toggle", "automation.delete",
                     ];
                     return reply(rpcResult(id, { name: "hara", version: deps.version, protocol: PROTOCOL_VERSION, cwd: opts.cwd, provider: deps.providerId, model: deps.model, capabilities: { methods } }));
                 }
@@ -185,7 +239,10 @@ export async function startServe(opts, deps) {
                             return reply(rpcError(id, ERR.NO_SESSION, `no live session ${p.sessionId} — session.create/resume first`));
                         if (s.busy)
                             return reply(rpcError(id, ERR.BUSY, "a turn is already running on this session"));
-                        const r = await runTurn(s, p.text);
+                        const images = Array.isArray(p.images)
+                            ? p.images.filter((im) => im && typeof im.path === "string").map((im) => ({ path: im.path, mediaType: typeof im.mediaType === "string" ? im.mediaType : "image/png" }))
+                            : undefined;
+                        const r = await runTurn(s, p.text, images);
                         return reply(rpcResult(id, r));
                     }
                     case "session.interrupt": {
@@ -259,14 +316,116 @@ export async function startServe(opts, deps) {
                         // The automation timeline's data: cron jobs with their last outcome, plus this machine's
                         // automated sessions (source=cron/gateway) so the desktop can render results and "continue
                         // as conversation". Read-only.
-                        const jobs = loadJobs().map((j) => ({ id: j.id, name: j.name, mode: j.mode, cwd: j.cwd, enabled: j.enabled, deliver: j.deliver, lastRunAt: j.lastRunAt, lastStatus: j.lastStatus, lastError: j.lastError }));
+                        const jobs = loadJobs().map((j) => ({ id: j.id, name: j.name, mode: j.mode, cwd: j.cwd, enabled: j.enabled, deliver: j.deliver, lastRunAt: j.lastRunAt, lastStatus: j.lastStatus, lastError: j.lastError, schedule: describeSchedule(j.schedule) }));
                         const automated = hub.list().filter((m) => m.source === "cron" || m.source === "gateway").map((m) => ({ id: m.id, title: m.title, cwd: m.cwd, source: m.source, sourceName: m.sourceName, updatedAt: m.updatedAt }));
                         return reply(rpcResult(id, { jobs, sessions: automated }));
                     }
+                    case "automation.add": {
+                        if (typeof p.name !== "string" || !p.name || typeof p.schedule !== "string" || typeof p.task !== "string" || !p.task) {
+                            return reply(rpcError(id, ERR.PARAMS, "name + schedule + task required"));
+                        }
+                        const sched = parseSchedule(p.schedule, Date.now());
+                        if ("error" in sched)
+                            return reply(rpcError(id, ERR.PARAMS, `bad schedule: ${sched.error}`));
+                        const job = addJob({
+                            name: p.name.slice(0, 60),
+                            schedule: sched,
+                            task: p.task,
+                            mode: ["print", "org", "command"].includes(p.mode) ? p.mode : "print",
+                            cwd: typeof p.cwd === "string" && p.cwd ? p.cwd : opts.cwd,
+                            ...(typeof p.tz === "string" && p.tz ? { tz: p.tz } : {}),
+                            createdAt: Date.now(),
+                        });
+                        return reply(rpcResult(id, { id: job.id, name: job.name, schedule: describeSchedule(job.schedule) }));
+                    }
+                    case "automation.toggle": {
+                        if (typeof p.id !== "string" || typeof p.enabled !== "boolean")
+                            return reply(rpcError(id, ERR.PARAMS, "id + enabled required"));
+                        const jobs = loadJobs();
+                        const job = jobs.find((j) => j.id === p.id);
+                        if (!job)
+                            return reply(rpcError(id, ERR.PARAMS, `no job ${p.id}`));
+                        job.enabled = p.enabled;
+                        saveJobs(jobs);
+                        return reply(rpcResult(id, { id: job.id, enabled: job.enabled }));
+                    }
+                    case "automation.delete": {
+                        if (typeof p.id !== "string")
+                            return reply(rpcError(id, ERR.PARAMS, "id required"));
+                        const jobs = loadJobs();
+                        if (!jobs.some((j) => j.id === p.id))
+                            return reply(rpcError(id, ERR.PARAMS, `no job ${p.id}`));
+                        saveJobs(jobs.filter((j) => j.id !== p.id));
+                        return reply(rpcResult(id, { id: p.id, deleted: true }));
+                    }
                     case "skills.list": {
                         const cwd = typeof p.cwd === "string" && p.cwd ? p.cwd : opts.cwd;
                         return reply(rpcResult(id, { skills: loadSkillIndex(cwd).map((s) => ({ id: s.id, description: s.description, source: s.source })) }));
                     }
+                    case "files.search": {
+                        // fuzzy file lookup for the composer's @-mention autocomplete (codex fuzzyFileSearch).
+                        // Relative POSIX paths; empty query returns the first files as a browse list.
+                        const sess = typeof p.sessionId === "string" ? hub.get(p.sessionId) : undefined;
+                        const cwd = typeof p.cwd === "string" && p.cwd ? p.cwd : (sess?.meta.cwd ?? opts.cwd);
+                        const limit = Math.min(Math.max(Math.trunc(Number(p.limit) || 20), 1), 50);
+                        const all = listProjectFiles(cwd);
+                        const query = typeof p.query === "string" ? p.query : "";
+                        const files = query ? fuzzyRank(query, all, (f) => f).slice(0, limit).map((r) => r.item) : all.slice(0, limit);
+                        return reply(rpcResult(id, { files, cwd }));
+                    }
+                    case "session.context": {
+                        // context-spend breakdown + watermark on demand (codex thread/tokenUsage + /context).
+                        if (typeof p.sessionId !== "string")
+                            return reply(rpcError(id, ERR.PARAMS, "sessionId required"));
+                        const s = hub.get(p.sessionId);
+                        if (!s)
+                            return reply(rpcError(id, ERR.NO_SESSION, `no live session ${p.sessionId}`));
+                        const report = analyzeContext(s.history);
+                        return reply(rpcResult(id, { sessionId: s.meta.id, ...ctxOf(s), total: report.total, rows: report.rows.slice(0, 8) }));
+                    }
+                    case "session.compact": {
+                        // manual compaction (codex thread/compact/start): summarize + replace history, keep working
+                        // notes, restore this-cwd touched files. Busy-guarded like a turn — it IS a provider call.
+                        if (typeof p.sessionId !== "string")
+                            return reply(rpcError(id, ERR.PARAMS, "sessionId required"));
+                        const s = hub.get(p.sessionId);
+                        if (!s)
+                            return reply(rpcError(id, ERR.NO_SESSION, `no live session ${p.sessionId}`));
+                        if (s.busy)
+                            return reply(rpcError(id, ERR.BUSY, "a turn is running — compact after it finishes"));
+                        if (s.history.length < 2)
+                            return reply(rpcError(id, ERR.PARAMS, "nothing to compact yet"));
+                        s.busy = true;
+                        try {
+                            broadcast("event.notice", { sessionId: s.meta.id, text: "✻ Compacting conversation…" });
+                            const summary = await compactSession(s);
+                            if (!summary)
+                                return reply(rpcError(id, ERR.INTERNAL, "compaction failed — try again or /clear"));
+                            broadcast("event.notice", { sessionId: s.meta.id, text: `(compacted — history replaced with a summary; ${s.meta.workingSet?.length ?? 0} notes kept)` });
+                            return reply(rpcResult(id, { sessionId: s.meta.id, ctx: ctxOf(s), notes: s.meta.workingSet?.length ?? 0, history: historyForClient(s.history) }));
+                        }
+                        finally {
+                            s.busy = false;
+                        }
+                    }
+                    case "session.rewind": {
+                        // fork the thread back to before the n-th-most-recent user turn (codex thread/rollback;
+                        // n=1 drops the last exchange). History-only — file edits are not reverted.
+                        if (typeof p.sessionId !== "string" || !Number.isInteger(p.n))
+                            return reply(rpcError(id, ERR.PARAMS, "sessionId + n required"));
+                        const s = hub.get(p.sessionId);
+                        if (!s)
+                            return reply(rpcError(id, ERR.NO_SESSION, `no live session ${p.sessionId}`));
+                        if (s.busy)
+                            return reply(rpcError(id, ERR.BUSY, "a turn is running — rewind after it finishes"));
+                        const next = rewindTo(s.history, p.n);
+                        if (!next)
+                            return reply(rpcError(id, ERR.PARAMS, `n out of range (1..${s.history.filter((m) => m.role === "user").length})`));
+                        s.history.length = 0;
+                        s.history.push(...next);
+                        hub.save(s);
+                        return reply(rpcResult(id, { sessionId: s.meta.id, history: historyForClient(s.history) }));
+                    }
                     default:
                         return reply(rpcError(id, ERR.METHOD, `unknown method ${req.method}`));
                 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanhara/hara",
-  "version": "0.116.0",
+  "version": "0.117.0",
   "description": "hara — a coding agent CLI that runs like an engineering org.",
   "bin": {
     "hara": "dist/index.js"