claude-memory-admin 1.8.0 → 1.10.0

package/public/views/header.mjs

@@ -22,6 +22,7 @@ const NAVIGATION = [
     segments: [
       { id: 'instructions', label: 'Instructions' },
       { id: 'settings', label: 'Settings' },
+      { id: 'cost', label: 'Cost' },
       { id: 'sessions', label: 'Sessions' },
       { id: 'tools', label: 'Tools' },
     ],
@@ -39,13 +40,27 @@ function segmentVisible(tab, segment, store) {
     return segment === 'index' ? Boolean(store.hasIndex) : true;
   }
   if (segment === 'instructions') return global || hasProjectDir(store);
+  if (segment === 'cost') return global;
   if (segment === 'tools') return state.tools.some((tool) => tool.found);
   if (global) return false;
   if (segment === 'sessions') return Boolean(store.sessions?.count);
   return true;
 }
 
+export const costProblems = () => {
+  const data = state.aux.cost;
+  if (!data) return [];
+  return [
+    ...(data.settings?.problems || []),
+    ...(data.agents || []).flatMap((agent) => agent.problems || []),
+  ];
+};
+
 function segmentBadge(id) {
+  if (id === 'cost') {
+    const problems = costProblems();
+    return problems.length ? { badge: String(problems.length), tone: worstSeverity(problems) } : {};
+  }
   if (id === 'instructions') {
     const problems = state.aux.instructions?.problems || [];
     return problems.length ? { badge: String(problems.length), tone: worstSeverity(problems) } : {};
@@ -56,7 +71,10 @@ function segmentBadge(id) {
   }
   if (id === 'sessions') {
     const sessions = state.store.sessions;
-    return sessions ? { badge: String(sessions.count), tone: sessions.expiringCount ? 'warn' : 'neutral' } : {};
+    if (!sessions) return {};
+    const live = state.activeSessions.some((s) => s.storeId === state.store.id);
+    const badge = live ? `● ${sessions.count}` : String(sessions.count);
+    return { badge, tone: live ? 'ok' : sessions.expiringCount ? 'warn' : 'neutral' };
   }
   return {};
 }
@@ -88,6 +106,7 @@ function tabBadge(tab, store) {
   const problems = [
     ...(state.aux.instructions?.problems || []),
     ...(state.aux.settings?.problems || []),
+    ...costProblems(),
   ];
   return problems.length ? { badge: String(problems.length), tone: worstSeverity(problems) } : {};
 }

package/public/views/sessions.mjs

@@ -20,11 +20,26 @@ export function focusSession(id) {
   goTo('environment', 'sessions');
 }
 
-function sessionRow(session, memoriesFrom, focused) {
+function agoLabel(ms) {
+  const seconds = Math.max(0, Math.round((Date.now() - ms) / 1000));
+  if (seconds < 60) return `${seconds}s ago`;
+  const minutes = Math.round(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+  return `${Math.round(minutes / 60)}h ago`;
+}
+
+function sessionRow(session, memoriesFrom, focused, live) {
   const soon = session.expiresInDays !== null && session.expiresInDays <= 7;
   const caret = node('span', { class: ui.contextCaret, text: focused ? '\u25be' : '\u25b8' });
 
   const tags = [];
+  if (live) {
+    tags.push(node('span', {
+      class: ui.badge('ok'),
+      text: live.status === 'waiting' ? 'waiting' : live.status || 'active',
+      title: live.waitingFor || `updated ${agoLabel(live.updatedAt)}`,
+    }));
+  }
   if (session.gitBranch) tags.push(node('span', { class: ui.badge('neutral'), text: session.gitBranch }));
   if (session.model) tags.push(node('span', { class: ui.badge('neutral'), text: session.model }));
   if (session.expiresInDays !== null) {
@@ -196,8 +211,33 @@ export async function renderSessions(container) {
     paint('tab');
   };
 
+  const active = state.activeSessions.filter((s) => s.storeId === state.storeId);
+  const byId = new Map(active.map((s) => [s.sessionId, s]));
+
   container.append(node('p', { class: ui.noteTight, text: 'The transcripts sitting beside this store\u2019s memory. Claude Code deletes them once they pass the retention period and never touches memory/, so this is the evidence that expires while the memories stay. This tab only reads, and only the head of each file - nothing here deletes a transcript.' }));
 
+  if (active.length) {
+    const list = node('div', { class: ui.card });
+    for (const session of active) {
+      list.append(node('button', {
+        class: ui.contextRowButton,
+        onclick: () => focusSession(session.sessionId),
+      }, [
+        node('div', { class: ui.contextMain }, [
+          node('div', { class: ui.contextTags }, [
+            node('span', {
+              class: ui.badge('ok'),
+              text: session.status === 'waiting' ? 'waiting' : session.status || 'active',
+            }),
+          ]),
+          node('div', { class: ui.contextFile, text: session.name || session.sessionId }),
+        ]),
+        node('div', { class: ui.contextSize, text: session.waitingFor || agoLabel(session.updatedAt) }),
+      ]));
+    }
+    container.append(meterPanel('Active now', null, list));
+  }
+
   container.append(node('div', { class: ui.meter }, [
     node('div', { class: ui.meterTop }, [
       node('span', { class: ui.meterValue, text: String(data.count) }),
@@ -241,7 +281,7 @@ export async function renderSessions(container) {
   const card = node('div', { class: ui.card });
   let focused = null;
   for (const session of visible) {
-    const row = sessionRow(session, byOrigin.get(session.id) || [], session.id === focus);
+    const row = sessionRow(session, byOrigin.get(session.id) || [], session.id === focus, byId.get(session.id));
     if (session.id === focus) focused = row;
     card.append(row);
   }

package/public/views/stores.mjs

@@ -22,10 +22,17 @@ function issueTitle(store) {
   return parts.length ? `${store.dir}\n${parts.join(', ')}` : store.dir;
 }
 
+function activeTitle(active) {
+  const waiting = active.filter((s) => s.status === 'waiting').length;
+  const label = active.length === 1 ? '1 session' : `${active.length} sessions`;
+  return waiting ? `${label} - ${waiting} waiting for input` : `${label} ${active.length === 1 ? 'is' : 'are'} busy`;
+}
+
 function storeButton(store) {
   const global = store.kind === 'global';
   const health = !global && !store.hasMemoryDir ? 'none' : store.severity || 'ok';
   const off = store.autoMemory && store.autoMemory.known && !store.autoMemory.enabled;
+  const active = state.activeSessions.filter((s) => s.storeId === store.id);
   return node('button', {
     class: ui.storeItem({ active: store.id === state.storeId, empty: !global && !store.hasMemoryDir }),
     onclick: () => openStore(store.id),
@@ -34,6 +41,7 @@ function storeButton(store) {
     node('span', { class: ui.storeRow }, [
       node('span', { class: ui.dot(health) }),
       node('span', { class: ui.storeName, text: store.label }),
+      active.length ? node('span', { class: ui.dot('ok'), title: activeTitle(active) }) : null,
       off ? node('span', { class: ui.offMarker, text: 'off', title: 'Auto memory is disabled for this project' }) : null,
       global ? null : node('span', { class: ui.storeCount, text: store.hasMemoryDir ? String(store.memoryCount) : '-' }),
     ]),

package/server.mjs

@@ -12,12 +12,15 @@ import { projectsRoot, resolveRoot } from './src/projects.mjs';
 import { buildStore } from './src/model.mjs';
 import { resolveGlobalInstructions, resolveInstructions, summarise } from './src/instructions.mjs';
 import { settingsReport, summariseSettings } from './src/settings.mjs';
+import { costReport, writeUserSetting } from './src/cost.mjs';
+import { AGENTS_DIR, AGENT_FIELDS, agentsDirExists, listAgents, setAgentField } from './src/agents.mjs';
 import { listStores } from './src/stores.mjs';
 import { forgetPath, rememberPath } from './src/pathcache.mjs';
 import { searchAll } from './src/search.mjs';
 import { verifyPaths } from './src/pathcheck.mjs';
 import { detectTools, toolReport } from './src/tools.mjs';
 import { sessionsWithSummaries, transcriptDir } from './src/sessions.mjs';
+import { readLiveSessions } from './src/liveSessions.mjs';
 import {
   addIndexEntry,
   addIndexEntryPreview,
@@ -146,15 +149,23 @@ function storeProjectDir(store) {
 
 /**
  * The global store holds instructions, not memory, and its directory is ~/.claude
- * itself. Every write endpoint below resolves a target inside `store.dir`, so
- * without this guard a delete aimed at it would land on the user's CLAUDE.md and
- * settings rather than on a memory file. It is read-only, and refused here once
- * rather than in each of the fifteen handlers.
+ * itself. Every memory write endpoint below resolves a target inside `store.dir`,
+ * so without this guard a delete aimed at it would land on the user's CLAUDE.md
+ * and settings rather than on a memory file. It is refused here once rather than
+ * in each of the fifteen handlers.
+ *
+ * The Cost handlers are the two exceptions, and the only writes this app makes
+ * outside a memory store. They do not take a path from the request at all: one
+ * writes an allowlisted key to ~/.claude/settings.json, the other one of two
+ * frontmatter fields in a named file inside ~/.claude/agents. Neither can reach
+ * an instruction file, which is what the rest of this guard exists to protect.
  */
-export function refuseWritesToGlobal(store, method) {
-  if (store.kind === 'global' && method !== 'GET') {
-    throw new Error('The global store is read-only: it holds instruction files, not memory.');
-  }
+const GLOBAL_WRITE_ACTIONS = new Set(['cost/setting', 'cost/agent']);
+
+export function refuseWritesToGlobal(store, method, action = null) {
+  if (store.kind !== 'global' || method === 'GET') return;
+  if (action && GLOBAL_WRITE_ACTIONS.has(action)) return;
+  throw new Error('The global store is read-only: it holds instruction files, not memory.');
 }
 
 /** A store with nothing to build a memory model from, in the shape the frontend expects. */
@@ -242,14 +253,26 @@ async function handleApi(req, res, url) {
     return sendJson(res, 200, { stores: issueSweep() });
   }
 
+  // Same "ahead of requireStore" reasoning as the issues sweep above: real
+  // store ids always carry a "kind:" prefix, so "active" can never collide.
+  if (segments.length === 3 && segments[1] === 'stores' && segments[2] === 'active' && req.method === 'GET') {
+    const live = readLiveSessions();
+    const projectStores = listStores(ROOT).filter((s) => s.kind === 'auto' && s.pathExists);
+    const sessions = live.map((session) => ({
+      ...session,
+      storeId: projectStores.find((s) => s.path === session.cwd)?.id ?? null,
+    }));
+    return sendJson(res, 200, { sessions });
+  }
+
   if (segments[1] !== 'stores' || segments.length < 3) {
     return sendJson(res, 404, { error: 'Unknown endpoint' });
   }
 
   const store = requireStore(decodeURIComponent(segments[2]));
-  refuseWritesToGlobal(store, req.method);
-  const dir = store.dir;
   const action = segments.slice(3).join('/');
+  refuseWritesToGlobal(store, req.method, action);
+  const dir = store.dir;
 
   if (!action && req.method === 'GET') {
     // buildStore reads every .md in the directory as a memory file, which for
@@ -299,6 +322,34 @@ async function handleApi(req, res, url) {
     return sendJson(res, 200, settingsReport({ projectDir: storeProjectDir(store) }));
   }
 
+  // The Cost segment. User scope only: the knobs it writes are about every
+  // session on the machine, and the file it writes them to is ~/.claude/settings.json.
+  if ((action === 'cost' || action.startsWith('cost/')) && store.kind !== 'global') {
+    return sendJson(res, 400, { error: 'The cost settings are user-scope, and are edited from the Global entry.' });
+  }
+
+  if (action === 'cost' && req.method === 'GET') {
+    return sendJson(res, 200, {
+      settings: costReport(),
+      agents: listAgents(),
+      agentsDir: AGENTS_DIR,
+      agentsDirExists: agentsDirExists(),
+      agentFields: AGENT_FIELDS,
+    });
+  }
+
+  if (action === 'cost/setting' && req.method === 'POST') {
+    const body = await readBody(req);
+    writeUserSetting(body.key, body.value ?? null);
+    return sendJson(res, 200, { settings: costReport() });
+  }
+
+  if (action === 'cost/agent' && req.method === 'POST') {
+    const body = await readBody(req);
+    const agents = setAgentField(body.file, body.field, body.value ?? null);
+    return sendJson(res, 200, { agents, agentsDir: AGENTS_DIR, agentsDirExists: agentsDirExists() });
+  }
+
   if (action === 'delete-preview' && req.method === 'POST') {
     const body = await readBody(req);
     return sendJson(res, 200, deletePreview(dir, body.file));

package/src/agents.mjs

@@ -0,0 +1,268 @@
+// User-scope subagent definitions: ~/.claude/agents/*.md.
+//
+// Not to be confused with ~/.claude/agent-memory (src/stores.mjs), which is what
+// those agents *remember*. This module is about what they *are*: a markdown file
+// whose frontmatter names the agent and, optionally, pins the model and effort
+// it runs at. Pinning a summariser to Haiku while a reviewer stays on Opus is the
+// finer-grained version of the CLAUDE_CODE_SUBAGENT_MODEL switch in src/cost.mjs,
+// which - worth remembering when both are set - outranks everything here.
+//
+// Only `model` and `effort` are writable. The prompt body, the tool lists and
+// every other field are read and shown but never rewritten: a body is prose
+// somebody wrote on purpose, and this tool has no view on it.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { parseFrontmatter } from './parse.mjs';
+import { writeFileAtomic } from './mutate.mjs';
+
+export const AGENTS_DIR = path.join(os.homedir(), '.claude', 'agents');
+
+const MODEL_ID = /^claude-[A-Za-z0-9._[\]-]+$/;
+
+export const AGENT_FIELDS = {
+  model: {
+    unset: 'inherit',
+    allowModelId: true,
+    options: [
+      { value: null, label: 'inherit', note: 'the session model' },
+      { value: 'haiku', label: 'haiku' },
+      { value: 'sonnet', label: 'sonnet' },
+      { value: 'opus', label: 'opus' },
+      { value: 'fable', label: 'fable' },
+    ],
+  },
+  effort: {
+    unset: 'default',
+    allowModelId: false,
+    options: [
+      { value: null, label: 'default', note: 'the session effort' },
+      { value: 'low', label: 'low' },
+      { value: 'medium', label: 'medium' },
+      { value: 'high', label: 'high' },
+      { value: 'xhigh', label: 'xhigh' },
+      { value: 'max', label: 'max' },
+    ],
+  },
+};
+
+export const AGENT_PROBLEM_SEVERITY = {
+  'no-frontmatter': 'bad',
+  'missing-name': 'warn',
+  'missing-description': 'warn',
+  'name-mismatch': 'warn',
+  'unknown-model': 'warn',
+  'unknown-effort': 'warn',
+};
+
+function known(field, value) {
+  const spec = AGENT_FIELDS[field];
+  if (spec.options.some((option) => option.value === value)) return true;
+  return spec.allowModelId && MODEL_ID.test(value);
+}
+
+/**
+ * A filename this module is willing to touch, resolved inside the agents
+ * directory. The same shape as safeMemoryPath in src/mutate.mjs: a bare .md
+ * basename, no dotfiles, and a realpath check so a symlink cannot point the
+ * write somewhere else.
+ */
+export function safeAgentPath(dir, file) {
+  if (typeof file !== 'string' || !file || file.includes('\0')) {
+    throw new Error('Invalid filename');
+  }
+  if (file !== path.basename(file) || file.startsWith('.') || !file.endsWith('.md')) {
+    throw new Error(`Refusing to touch "${file}": must be a plain .md filename`);
+  }
+
+  const full = path.join(dir, file);
+  const rel = path.relative(dir, full);
+  if (rel.startsWith('..') || path.isAbsolute(rel)) {
+    throw new Error('Path escapes the agents directory');
+  }
+  if (fs.existsSync(full)) {
+    const realDir = fs.realpathSync(dir);
+    const realFull = fs.realpathSync(full);
+    if (path.relative(realDir, realFull).startsWith('..')) {
+      throw new Error('Path escapes the agents directory');
+    }
+  }
+  return full;
+}
+
+function describeAgent(dir, file) {
+  const full = path.join(dir, file);
+  const stem = file.replace(/\.md$/, '');
+
+  let text;
+  try {
+    text = fs.readFileSync(full, 'utf8');
+  } catch (err) {
+    return {
+      file,
+      name: stem,
+      description: '',
+      tools: '',
+      model: null,
+      effort: null,
+      bytes: 0,
+      problems: [{ kind: 'no-frontmatter', severity: 'bad', detail: err.message }],
+    };
+  }
+
+  const { data, hasFrontmatter } = parseFrontmatter(text);
+  const scalar = (key) => (typeof data[key] === 'string' ? data[key].trim() : '');
+  const name = scalar('name') || stem;
+  const model = scalar('model') || null;
+  const effort = scalar('effort') || null;
+
+  const problems = [];
+  const flag = (kind, detail) => problems.push({ kind, severity: AGENT_PROBLEM_SEVERITY[kind], detail });
+
+  if (!hasFrontmatter) {
+    flag('no-frontmatter', 'The file has no --- frontmatter block, so Claude Code does not read it as an agent definition.');
+  } else {
+    if (!scalar('name')) flag('missing-name', `No name: field, so the agent is addressed as "${stem}" after its file.`);
+    if (!scalar('description')) flag('missing-description', 'No description: field. Claude decides when to delegate from that description, so an agent without one is never chosen on its own.');
+    if (scalar('name') && scalar('name') !== stem) flag('name-mismatch', `Named "${scalar('name')}" in a file called "${file}".`);
+    if (model && !known('model', model)) flag('unknown-model', `model: ${model} is neither an alias nor a claude- model name.`);
+    if (effort && !known('effort', effort)) flag('unknown-effort', `effort: ${effort} is not one of low, medium, high, xhigh or max.`);
+  }
+
+  return {
+    file,
+    name,
+    description: scalar('description'),
+    tools: scalar('tools'),
+    model,
+    effort,
+    bytes: Buffer.byteLength(text, 'utf8'),
+    problems,
+  };
+}
+
+/**
+ * Every user-scope agent definition. A directory that is not there is the
+ * ordinary state of a machine whose owner has never written one, not a failure,
+ * so it answers with an empty list.
+ */
+export function listAgents({ dir = AGENTS_DIR } = {}) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  return entries
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.md') && !entry.name.startsWith('.'))
+    .map((entry) => describeAgent(dir, entry.name))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** Whether the directory itself exists, which is what tells an empty list from a missing one. */
+export function agentsDirExists({ dir = AGENTS_DIR } = {}) {
+  try {
+    return fs.statSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+const fieldLine = (field) => new RegExp(`^${field}[ \\t]*:`);
+
+/**
+ * Where a field that is not there yet should go: straight after the name or
+ * description when that line carries its value inline, and otherwise at the end
+ * of the block. Appending is always valid - a top-level key ends whatever nested
+ * block preceded it - so the nicer placement is only taken when it is provably
+ * safe, which rules out a folded or block scalar the insertion would land inside.
+ */
+function inlineScalarAt(block, key) {
+  const index = block.findIndex((line) => fieldLine(key).test(line));
+  if (index === -1) return -1;
+  const rest = block[index].slice(block[index].indexOf(':') + 1).trim();
+  if (!rest || rest.startsWith('|') || rest.startsWith('>')) return -1;
+  return index;
+}
+
+function insertionIndex(block) {
+  const description = block.findIndex((line) => fieldLine('description').test(line));
+  const inline = inlineScalarAt(block, 'description');
+  if (inline !== -1) return inline + 1;
+  if (description !== -1) return block.length;
+
+  const name = inlineScalarAt(block, 'name');
+  return name === -1 ? block.length : name + 1;
+}
+
+/**
+ * Rewrite one frontmatter field, leaving every other byte of the file alone:
+ * the body, the other fields, their order, their spacing and any comments among
+ * them. The same principle src/parse.mjs applies to MEMORY.md - edit the line
+ * that changed, never re-emit the document from a parse of it.
+ */
+export function rewriteAgentField(text, field, value) {
+  const lines = text.split('\n');
+  if (lines[0]?.trim() !== '---') {
+    throw new Error('This file has no frontmatter block, so there is nothing to set.');
+  }
+
+  let end = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === '---') { end = i; break; }
+  }
+  if (end === -1) {
+    throw new Error('This file has an unterminated frontmatter block.');
+  }
+
+  const block = lines.slice(1, end);
+  const at = block.findIndex((line) => fieldLine(field).test(line));
+
+  if (value === null) {
+    if (at === -1) return text;
+    block.splice(at, 1);
+  } else if (at === -1) {
+    block.splice(insertionIndex(block), 0, `${field}: ${value}`);
+  } else {
+    block[at] = `${field}: ${value}`;
+  }
+
+  return [lines[0], ...block, ...lines.slice(end)].join('\n');
+}
+
+function normaliseAgentValue(field, value) {
+  const spec = AGENT_FIELDS[field];
+  if (value === null || value === undefined) return null;
+  if (typeof value !== 'string') throw new Error(`${field} takes a string, not ${typeof value}.`);
+
+  const trimmed = value.trim();
+  if (!trimmed || trimmed === spec.unset) return null;
+  if (known(field, trimmed)) return trimmed;
+
+  throw new Error(`"${trimmed}" is not a value ${field} accepts.`);
+}
+
+/**
+ * Set or clear `model` or `effort` on one agent file, atomically, and answer with
+ * the refreshed list so the caller renders what is on disk rather than what it
+ * hoped it wrote.
+ */
+export function setAgentField(file, field, value, { dir = AGENTS_DIR } = {}) {
+  if (!Object.prototype.hasOwnProperty.call(AGENT_FIELDS, field)) {
+    throw new Error(`"${field}" is not a field this tool writes. Only model and effort are editable here.`);
+  }
+
+  const full = safeAgentPath(dir, file);
+  if (!fs.existsSync(full)) throw new Error(`${file} is no longer there - reload and try again.`);
+
+  const next = normaliseAgentValue(field, value);
+  const original = fs.readFileSync(full, 'utf8');
+  const rewritten = rewriteAgentField(original, field, next);
+
+  if (rewritten !== original) writeFileAtomic(dir, file, rewritten);
+
+  return listAgents({ dir });
+}