create-evda 0.1.5 → 0.1.6

package/create-evda.mjs

@@ -3,6 +3,7 @@
 //
 //   create-evda <dir> [--agent-name NAME] [--owner NAME] [--purpose TEXT] [--voice TEXT]
 //                     [--platform claude|chatgpt|gemini|cursor|other] [--training-off] [--yes]
+//                     [--filing everything|asked] [--no-prompt-hook]
 //                     [--name NAME] [--layers record,ledger[,circles]] [--preset ID|none] [--force]
 //
 // On a terminal, any setup answer not given as a flag is asked, one question at a time, and setup
@@ -28,10 +29,14 @@ import { doctor } from "./lib/doctor.mjs";
 import { readPointer, setPointer, pointerPath } from "./lib/locate.mjs";
 import { FOLDER_MANIFEST } from "./lib/folders.mjs";
 import { EvdaError } from "./lib/errors.mjs";
-import { clients, installSkill } from "./lib/connect.mjs";
+import { clients, installSkill, installGuard } from "./lib/connect.mjs";
 import { desktopInstructions } from "./lib/routines.mjs";
+import { installHook } from "./lib/hooks.mjs";
 import { applyPreset, listPresets, planLines, presetIds, NONE } from "./lib/presets.mjs";
-import { PLATFORMS, PLATFORM_KEYS, LOADERS, DESKTOP_FILESYSTEM, DICTATION, DEFAULT_AGENT_NAME, platformKey, fillOwnerSection, aiLine, interview, trainingSection } from "./lib/setup.mjs";
+import { FILING_MODES } from "./lib/day-file.mjs";
+import { installPromptHook } from "./lib/hooks.mjs";
+import { PLATFORMS, PLATFORM_KEYS, LOADERS, DESKTOP_FILESYSTEM, DICTATION, DEFAULT_AGENT_NAME, platformKey, fillOwnerSection, aiLine, interview, trainingSection, termsSection, readerFor, INTRO } from "./lib/setup.mjs";
+import { describeReaders, parseReaders } from "./lib/readers.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const TEMPLATES = join(HERE, "templates");
@@ -47,6 +52,7 @@ const CANONICAL = {
   ledger: "ledger",
   circles: "circles",
   grants: "grants",
+  mounts: "mounts",
 };
 
 // What each record folder holds (Spec 07, section 2), written as folder.evda.json beside the
@@ -57,13 +63,13 @@ const FOLDER_TYPES = {
   "record/people": "person",
 };
 
-const USAGE = `usage: create-evda <dir> [--agent-name NAME] [--owner NAME] [--purpose TEXT] [--voice TEXT] [--platform ${PLATFORM_KEYS.join("|")}] [--training-off] [--yes] [--name NAME] [--kind person|agent|company] [--id ATLAS-ID] [--layers record,ledger] [--skill] [--routines morning,weekly] [--preset ${presetIds().join("|")}|none] [--use] [--no-pointer]`;
+const USAGE = `usage: create-evda <dir> [--agent-name NAME] [--owner NAME] [--purpose TEXT] [--voice TEXT] [--platform ${PLATFORM_KEYS.join("|")}] [--training-off] [--filing everything|asked] [--no-prompt-hook] [--yes] [--name NAME] [--kind person|agent|company] [--id ATLAS-ID] [--layers record,ledger] [--skill] [--routines morning,weekly] [--preset ${presetIds().join("|")}|none] [--use] [--no-pointer] [--no-guard]`;
 
 export function parseArgs(argv) {
   const opts = {
     layers: ["record", "ledger"], force: false, name: null, owner: "", kind: "person", id: null, pointer: true, use: false,
     yes: false, trainingOff: false, agentName: null, purpose: "", voice: "", platform: null, platformName: null,
-    skill: null, routines: null, preset: null,
+    skill: null, routines: null, preset: null, guard: true, filing: null, promptHook: true,
   };
   const args = argv.flatMap((a) => {
     const eq = /^(--[a-z-]+)=([\s\S]*)$/.exec(a);
@@ -82,6 +88,12 @@ export function parseArgs(argv) {
     else if (a === "--yes" || a === "-y") opts.yes = true;
     else if (a === "--training-off") opts.trainingOff = true;
     else if (a === "--skill") opts.skill = true;
+    else if (a === "--no-guard") opts.guard = false;
+    else if (a === "--no-prompt-hook") opts.promptHook = false;
+    else if (a === "--filing") {
+      opts.filing = value(++i, a).trim().toLowerCase();
+      if (!FILING_MODES.includes(opts.filing)) throw new EvdaError(`--filing takes ${FILING_MODES.join(" or ")}, got ${args[i]}`, { exit: 2 });
+    }
     else if (a === "--no-skill") opts.skill = false;
     else if (a === "--no-routines") opts.routines = [];
     else if (a === "--routines") {
@@ -147,9 +159,18 @@ export function scaffold(opts) {
   const id = opts.id ?? `${slug(opts.name)}.atlas`;
   const problems = holderProblems({ owner: { kind }, id });
   if (problems.length) throw new EvdaError(`REFUSED: ${problems.join(" ")}`, { exit: 2 });
-  const manifest = { evda: SCHEMA_VERSION, id, name: opts.name, owner: { name: opts.owner ?? "", kind }, created: today, layers: opts.layers, mapping };
+  // A new record's circles stop at any record made inside it (HQ-1371); a record adopted before
+  // that declares it when its owner opts in, so what it already syncs does not change under it.
+  const manifest = { evda: SCHEMA_VERSION, id, name: opts.name, owner: { name: opts.owner ?? "", kind }, created: today, layers: opts.layers, mapping, subrecords: "bounded" };
+  // Who reads the record: the AI the owner chose, for all of it (HQ-1374). Not local by default,
+  // because most people have no local model; a circle can say otherwise later, on the owner's yes.
+  const readBy = readerFor({ platform: opts.platform, platformName: opts.platformName, trainingOff: opts.trainingOff, date: today });
+  if (readBy) manifest.read_by = readBy;
+  // The owner's answer to the one filing question (HQ-1385). Unanswered, the key is left out and the
+  // agent asks at first connect.
+  if (opts.filing) manifest.filing = opts.filing;
   writeIfAbsent(join(dir, "evda.json"), JSON.stringify(manifest, null, 2) + "\n");
-  writeIfAbsent(join(dir, "README.md"), render("README.md", { training: trainingSection() }));
+  writeIfAbsent(join(dir, "README.md"), render("README.md", { training: trainingSection(), terms: termsSection(), intro: INTRO, localModel: localModelSection() }));
   // The owner section of AGENTS.md holds the setup answers in the owner's words. The AI line is
   // written only when training off was confirmed; empty, it is what makes the agent ask.
   const answers = {
@@ -167,6 +188,15 @@ export function scaffold(opts) {
   for (const [role, type] of Object.entries(FOLDER_TYPES)) {
     if (mapping[role]) writeIfAbsent(join(dir, mapping[role], FOLDER_MANIFEST), JSON.stringify({ type, connectors: [], views: [] }, null, 2) + "\n");
   }
+  // The Claude Code read guard, for an owner who chose Claude: sessions opened in this folder are
+  // stopped before reading a just-noted entry, or a part set to be read by a different AI.
+  const guard = opts.platform === "claude" && opts.guard !== false ? installGuard(dir) : null;
+  // Claude Code gets the keep-record Stop hook in the record's own .claude/ (HQ-1376): a session
+  // that read the record or heard the owner out and filed nothing is asked once before it stops.
+  const hook = opts.platform === "claude" && opts.hook !== false ? installHook(dir) : null;
+  // And the prompt hook (HQ-1385), only when the owner chose to have everything filed: each message
+  // they send in Claude Code is filed verbatim before the model sees it.
+  const promptHook = opts.platform === "claude" && opts.filing === "everything" && opts.promptHook !== false ? installPromptHook(dir) : null;
   writeVersion(dir, SCHEMA_VERSION);
   reindex({ dir, manifest, version: { declared: SCHEMA_VERSION, onDisk: SCHEMA_VERSION } });
 
@@ -180,7 +210,13 @@ export function scaffold(opts) {
   } else {
     pointer.action = "skipped (--no-pointer)";
   }
-  return { dir, manifest, pointer };
+  return { dir, manifest, pointer, guard, hook, promptHook };
+}
+
+// The local-model doc as a README section: its title dropped and its headings one level down.
+function localModelSection() {
+  const text = readFileSync(join(HERE, "docs", "local-model.md"), "utf8");
+  return text.split("\n").slice(1).join("\n").replace(/^## /gm, "### ").trim();
 }
 
 // Day one. The record's first daily file records the one true thing that has happened to it: it
@@ -223,7 +259,7 @@ async function terminalIO() {
 }
 
 export function needsAsking(opts) {
-  return opts.agentName == null || !opts.owner || !opts.purpose || !opts.voice || !opts.platform || !opts.trainingOff;
+  return opts.agentName == null || !opts.owner || !opts.purpose || !opts.voice || !opts.platform || !opts.trainingOff || !opts.filing;
 }
 
 // `io` is for tests: { interactive, ask(question), out(line) }. Without it, setup is interactive
@@ -245,9 +281,15 @@ export async function main(argv, io = null) {
     }
     log("");
   }
-  const { dir, pointer } = scaffold(opts);
+  const { dir, pointer, guard, hook, promptHook, manifest } = scaffold(opts);
   log(`created an EVDA at ${dir}`);
-  log(`locator ${pointer.path}: ${pointer.action}\n`);
+  log(`locator ${pointer.path}: ${pointer.action}`);
+  log(`read by: ${describeReaders(parseReaders(manifest.read_by).readers)}`);
+  if (guard) log(`read guard for Claude Code: ${guard.action} ${guard.path}`);
+  if (hook) log(`Claude Code Stop hook: ${hook.action} (${hook.settings} runs ${hook.hook}, in this record only)`);
+  if (promptHook) log(`Claude Code prompt hook: ${promptHook.action} (${promptHook.settings} runs ${promptHook.hook}, which files each message you send)`);
+  log(`filing: ${manifest.filing === "everything" ? "everything you say is filed automatically" : manifest.filing === "asked" ? "only when you ask" : "not answered yet; your agent asks the first time you connect"}`);
+  log("");
   // The chosen preset only adds folders to the fresh record, and doctor below reads what it wrote.
   if (opts.preset && opts.preset !== NONE) {
     const plan = applyPreset(dir, opts.preset);
@@ -286,6 +328,8 @@ export async function main(argv, io = null) {
     log(`Or schedule it with launchd on a Mac: evda routine ${key} ${dir} --install`);
   }
   log("");
+  for (const l of INTRO.split("\n")) log(l);
+  log("");
   log(`Then freewrite: what happened today, what is on your mind, what felt slightly off. Your words go into record/ as you talk. README.md says the rest.`);
   if (!asked) log(DICTATION);
   return 0;

package/docs/local-model.md

@@ -0,0 +1,34 @@
+# Running a model on your own computer
+
+A model on your own computer reads your record without it going to any company. It is slower and less capable than the models the AI companies run, and likelier to say something that is not in your record, so check what it cites against the file it names.
+
+## 1. Install a runner
+
+Either one works. Both are free and run on a Mac, Windows or Linux.
+
+- **Ollama** (<https://ollama.com>). Install it, then in a terminal: `ollama pull llama3.1:8b`. It serves the model on this computer at `http://localhost:11434`.
+- **LM Studio** (<https://lmstudio.ai>). Install it, open the Discover tab, and download a model. It can also start MCP servers itself, which is how it reaches your EVÐA (step 3).
+
+A Mac with Apple silicon and 16 GB of memory, or a PC with a graphics card that has 8 GB, runs a model of about 7 or 8 billion parameters. Less memory means a smaller model.
+
+## 2. Say which parts it reads
+
+In the circle's `eco.yaml`, or in `evda.json` for the whole record:
+
+    read_by: local
+
+or, naming the model and where it runs:
+
+    read_by:
+      - local: llama3.1:8b
+        on: this Mac
+
+A part set to `local` is refused to any hosted AI that checks: the evda MCP server refuses it, the Claude Code guard refuses it, and `AGENTS.md` tells every other agent to decline. You can keep the rest on the AI you already use. Run `evda doctor` after, and it prints who reads each part.
+
+## 3. Connect the model to your EVÐA
+
+Run `evda connect` to print the command that starts the evda MCP server. Give that command to an app that runs local models and speaks MCP (LM Studio does, in its Program tab under mcp.json), and add one setting so the server knows the caller is local:
+
+    "env": { "EVDA_READER": "local" }
+
+Then ask it what you wrote this week. If it answers from your files, it is reading them on this computer.

package/hooks/evda-read-guard.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// Claude Code PreToolUse hook: refuse Read, Grep and shell reads of a just-noted entry, or of a
+// file whose circle is read by an AI other than Claude. The logic is lib/guard.mjs; this file is
+// only the entry point a settings.json names. create-evda installs it for Claude owners.
+import { runHook } from "../lib/guard.mjs";
+
+runHook().then((code) => process.exit(code), () => process.exit(0));

package/lib/chat-export.mjs

@@ -0,0 +1,198 @@
+// The backstop (HQ-1385): what the owner said to Claude or ChatGPT that no agent filed, taken from the
+// app's own data export and added to the day it was said.
+//
+// An agent files while the conversation happens (evda_write, the nudge, the Claude Code hooks), and
+// the Claude app was measured not doing it (2026-09-22). The export holds every conversation, so
+// `evda gather <conversations.json> --into <record>` reads it, keeps only the owner's own messages,
+// and adds each one the record does not already hold, under its conversation's date and time. It
+// runs through gather's proposal and apply, so the owner sees the count first, says yes, and
+// `evda gather revert` takes it back byte for byte.
+//
+// Two formats, told apart by shape, never by file name:
+//   claude    Claude.ai Settings > Privacy > Export data: conversations.json, an array of
+//             { uuid, name, created_at, chat_messages: [{ sender: "human"|"assistant", text,
+//             content: [{ type: "text", text }], created_at }] }
+//   chatgpt   ChatGPT Settings > Data controls > Export: conversations.json, an array of
+//             { title, create_time, current_node, mapping: { id: { parent, message: { author:
+//             { role }, create_time, content: { parts } } } } }, read along the branch the owner
+//             last saw (current_node back to the root)
+//
+// Only the owner's messages are read: sender "human", role "user". The model's replies are not
+// their words and are never written.
+//
+// ALREADY FILED. A message is in the record when the normalized text of some section of a day file
+// (lowercase, letters and digits only, one space between words) contains the message's normalized
+// text, and that section's `## HH:MM` falls between WINDOW_BEFORE_MIN before the conversation began
+// and WINDOW_AFTER_MIN after the message was sent. Text in a day file above its first heading counts
+// for the whole day. So a message filed live, under the conversation's section, is found, and a
+// second backfill of the same export adds nothing.
+//
+// A message holding something shaped like a password, key or token is not written, and is counted.
+//
+// EVDA_CHAT_FALSIFY=<mode,...>, for the tests:
+//   no-dedupe       nothing counts as already filed
+//   assistant-too   the model's replies are read as the owner's
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { secretShape } from "./secret-shape.mjs";
+import { localDate, localTime, sectionBytes } from "./day-file.mjs";
+
+export const CHAT_FORMATS = { claude: "Claude.ai", chatgpt: "ChatGPT" };
+export const WINDOW_BEFORE_MIN = 60;
+export const WINDOW_AFTER_MIN = 12 * 60;
+const TITLE_MAX = 120;
+const DAY_FILE = /^(\d{4}-\d{2}-\d{2})\.md$/;
+
+const falsified = (mode) => (process.env.EVDA_CHAT_FALSIFY ?? "").split(",").map((s) => s.trim()).includes(mode);
+
+export const normalize = (t) => String(t).normalize("NFKC").toLowerCase().replace(/[‘’]/g, "'").replace(/[^\p{L}\p{N}]+/gu, " ").trim();
+
+const ms = (v) => {
+  if (typeof v === "number" && Number.isFinite(v)) return v < 1e12 ? Math.round(v * 1000) : v;
+  if (typeof v === "string" && v) { const t = Date.parse(v); return Number.isFinite(t) ? t : null; }
+  return null;
+};
+
+// "claude", "chatgpt", or null. `data` is the parsed JSON.
+export function chatFormat(data) {
+  if (!Array.isArray(data) || data.length === 0) return null;
+  const first = data.find((c) => c && typeof c === "object");
+  if (!first) return null;
+  if (Array.isArray(first.chat_messages)) return "claude";
+  if (first.mapping && typeof first.mapping === "object" && !Array.isArray(first.mapping)) return "chatgpt";
+  return null;
+}
+
+// Parse bytes as a chat export: { format, data } or null when they are not one.
+export function readChatExport(buf) {
+  const head = buf.subarray(0, 64).toString("utf8").trimStart();
+  if (!head.startsWith("[")) return null;
+  let data;
+  try { data = JSON.parse(buf.toString("utf8")); } catch { return null; }
+  const format = chatFormat(data);
+  return format ? { format, data } : null;
+}
+
+const claudeText = (m) => {
+  if (typeof m.text === "string" && m.text.trim()) return m.text;
+  return Array.isArray(m.content) ? m.content.filter((c) => c?.type === "text" && typeof c.text === "string").map((c) => c.text).join("\n\n") : "";
+};
+
+function chatgptBranch(conv) {
+  const map = conv.mapping ?? {};
+  const out = [];
+  if (conv.current_node && map[conv.current_node]) {
+    const seen = new Set();
+    for (let id = conv.current_node; id && map[id] && !seen.has(id); id = map[id].parent) { seen.add(id); out.push(map[id]); }
+    return out.reverse();
+  }
+  return Object.values(map).sort((a, b) => (ms(a?.message?.create_time) ?? 0) - (ms(b?.message?.create_time) ?? 0));
+}
+
+const chatgptText = (msg) => {
+  const parts = msg?.content?.parts;
+  if (!Array.isArray(parts)) return typeof msg?.content?.text === "string" ? msg.content.text : "";
+  return parts.filter((p) => typeof p === "string").join("\n\n");
+};
+
+// The export as conversations of the owner's messages:
+// [{ id, title, started, messages: [{ at, text }] }], each message's `at` in ms. A conversation with
+// no message from the owner is left out.
+export function conversations({ format, data }) {
+  const out = [];
+  const owner = (role) => role === (format === "claude" ? "human" : "user") || (falsified("assistant-too") && role === "assistant");
+  for (const conv of data) {
+    if (!conv || typeof conv !== "object") continue;
+    const started = ms(format === "claude" ? conv.created_at : conv.create_time);
+    const messages = [];
+    if (format === "claude") {
+      for (const m of conv.chat_messages ?? []) {
+        if (!owner(m?.sender)) continue;
+        const text = claudeText(m);
+        if (text.trim()) messages.push({ at: ms(m.created_at) ?? started, text });
+      }
+    } else {
+      for (const node of chatgptBranch(conv)) {
+        const m = node?.message;
+        if (!m || !owner(m.author?.role) || m.metadata?.is_visually_hidden_from_conversation) continue;
+        const text = chatgptText(m);
+        if (text.trim()) messages.push({ at: ms(m.create_time) ?? started, text });
+      }
+    }
+    if (!messages.length) continue;
+    const first = started ?? Math.min(...messages.map((m) => m.at ?? Infinity));
+    let title = typeof (conv.name ?? conv.title) === "string" ? String(conv.name ?? conv.title).replace(/\s+/g, " ").trim().slice(0, TITLE_MAX) : "";
+    if (title && secretShape(title)) title = "";
+    out.push({ id: String(conv.uuid ?? conv.conversation_id ?? conv.id ?? out.length), title, started: Number.isFinite(first) ? first : null, messages: messages.map((m) => ({ ...m, at: m.at ?? first })) });
+  }
+  return out;
+}
+
+// The day files' sections, for the already-filed test: [{ from, to, text }] with times in ms and the
+// normalized text. A `## HH:MM` heading starts a section at that minute; text above the first
+// heading spans its whole day.
+export function filedSections(dayDir) {
+  const out = [];
+  if (!dayDir || !existsSync(dayDir)) return out;
+  for (const name of readdirSync(dayDir)) {
+    const m = DAY_FILE.exec(name);
+    if (!m) continue;
+    const [y, mo, d] = m[1].split("-").map(Number);
+    const text = readFileSync(join(dayDir, name), "utf8");
+    const parts = text.split(/^## (\d{1,2}):(\d{2})\b.*$/m);
+    const dayStart = new Date(y, mo - 1, d).getTime();
+    out.push({ from: dayStart, to: new Date(y, mo - 1, d + 1).getTime() - 1, text: normalize(parts[0]) });
+    for (let i = 1; i < parts.length; i += 3) {
+      const at = new Date(y, mo - 1, d, Number(parts[i]), Number(parts[i + 1])).getTime();
+      out.push({ from: at, to: at, text: normalize(parts[i + 2] ?? "") });
+    }
+  }
+  return out;
+}
+
+export function isFiled(sections, conv, msg) {
+  if (falsified("no-dedupe")) return false;
+  const want = normalize(msg.text);
+  if (!want) return true;
+  const lo = (conv.started ?? msg.at) - WINDOW_BEFORE_MIN * 60_000;
+  const hi = msg.at + WINDOW_AFTER_MIN * 60_000;
+  return sections.some((s) => s.to >= lo && s.from <= hi && s.text.includes(want));
+}
+
+// What a backfill adds: one entry per conversation with messages the record lacks.
+// [{ date, time, title, words: [text], conversation }] and the counts.
+export function backfillPlan(convs, sections, { format }) {
+  const adds = [];
+  const c = { conversations: convs.length, messages: 0, filed: 0, secret: 0, add: 0 };
+  for (const conv of convs) {
+    const words = [];
+    for (const msg of conv.messages) {
+      c.messages += 1;
+      if (msg.text.split("\n").some(secretShape)) { c.secret += 1; continue; }
+      if (isFiled(sections, conv, msg)) { c.filed += 1; continue; }
+      words.push(msg.text);
+    }
+    if (!words.length) continue;
+    c.add += words.length;
+    const when = new Date(conv.started ?? conv.messages[0].at);
+    adds.push({ date: localDate(when), time: localTime(when), title: conv.title, conversation: conv.id, words, context: contextFor(format, conv.title) });
+  }
+  return { adds, counts: c };
+}
+
+export const contextFor = (format, title) => `from their ${CHAT_FORMATS[format]} export${title ? `, the conversation "${title.replace(/"/g, "'")}"` : ""}; added by evda gather, since it was not filed when it was said`;
+
+// The bytes to append to a day file whose text is `current` (null when absent) for these adds.
+export function dayAppend(current, adds) {
+  let text = current;
+  let out = "";
+  for (const a of adds) {
+    for (let i = 0; i < a.words.length; i++) {
+      const w = sectionBytes({ current: text, date: a.date, time: a.time, words: a.words[i], context: i === 0 ? a.context : null, continuing: i > 0, contextWritten: true });
+      out += w.text;
+      text = (text ?? "") + w.text;
+    }
+  }
+  return out;
+}