create-evda 0.1.8 → 0.1.9

package/lib/watch.mjs

@@ -0,0 +1,160 @@
+// Watching a record for saves (HQ-2068), so the computer sends a saved note in seconds instead of
+// at the next five-minute sync.
+//
+// macOS reports every change under a folder through FSEvents, which Node's recursive `fs.watch`
+// uses on darwin. This turns those reports into bursts: a run of saves close together is one burst,
+// said once it has been quiet for `quietMs`, or once it has run `maxWaitMs`, so an editor that
+// saves every keystroke still gets a sync every few seconds. What the scan would never send starts
+// nothing: the sync rules' exclusions (`.evda`, `.git`, `node_modules`, `.DS_Store`, an Office owner
+// file, the plan's own paths), an iCloud placeholder, and a dataless file iCloud has not brought
+// down (HQ-2017), or a folder (what changed inside it is reported on its own). A path that is gone
+// counts, since its removal is news.
+//
+// The watcher decides only WHEN a sync runs. The sync it starts is the ordinary bounded one, with
+// its own lock and guards (HQ-2041); the five-minute sync stays as the backstop for anything a
+// watcher misses (a change while the app was closed, an FSEvents drop).
+
+import { lstatSync, watch } from "node:fs";
+import { join, sep } from "node:path";
+import { datalessAmong, excluder, isPlaceholder } from "./sync-rules.mjs";
+
+export const WATCH_QUIET_MS = 1_000;
+export const WATCH_MAX_WAIT_MS = 5_000;
+
+/**
+ * Whether a change at `rel` (relative to `root`) is one a sync would act on: not excluded, not an
+ * iCloud placeholder, not a link or a folder, not a dataless file. A path that no longer exists counts.
+ */
+export function watchCounts(root, rel, { exclude = excluder(), env = process.env } = {}) {
+  const r = String(rel).split(sep).join("/").normalize("NFC");
+  if (r === "" || exclude(r)) return false;
+  if (isPlaceholder(r.slice(r.lastIndexOf("/") + 1))) return false;
+  let st;
+  try {
+    st = lstatSync(join(root, r));
+  } catch {
+    return true;
+  }
+  if (st.isSymbolicLink() || st.isDirectory()) return false;
+  if (st.isFile() && st.size > 0 && st.blocks === 0 && datalessAmong(root, [r], { env }).has(r)) return false;
+  return true;
+}
+
+/**
+ * Watch `root` and call `onBurst(paths)` once per burst of counted changes, with the paths in it.
+ * Returns `{ close() }`. `watchImpl` replaces `fs.watch` for a test that feeds it events.
+ */
+export function watchRecord(root, onBurst, { quietMs = WATCH_QUIET_MS, maxWaitMs = WATCH_MAX_WAIT_MS, exclude = excluder(), env = process.env, watchImpl = watch, now = () => Date.now() } = {}) {
+  let pending = new Set();
+  let first = 0;
+  let timer = null;
+  const fire = () => {
+    timer = null;
+    if (pending.size === 0) return;
+    const paths = [...pending];
+    pending = new Set();
+    first = 0;
+    onBurst(paths);
+  };
+  const watcher = watchImpl(root, { recursive: true, persistent: true }, (_event, name) => {
+    if (name == null) return;
+    const rel = String(name);
+    if (!watchCounts(root, rel, { exclude, env })) return;
+    pending.add(rel.split(sep).join("/").normalize("NFC"));
+    const t = now();
+    if (first === 0) first = t;
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(fire, Math.max(0, Math.min(quietMs, first + maxWaitMs - t)));
+  });
+  return {
+    close() {
+      if (timer) clearTimeout(timer);
+      timer = null;
+      watcher.close();
+    },
+  };
+}
+
+// ─── A device's note, taken in within seconds (HQ-2068) ─────────────────────
+//
+// The file watcher sees only saves on this computer, so a note a phone sent waited for the
+// five-minute sync. This looks at the relay instead: every `everyMs` it asks each mailbox this
+// computer reads for its first waiting envelope, takes nothing and acknowledges nothing, and says
+// so once per envelope it has not seen at the head of that mailbox. The sync it starts drains the
+// box; an envelope the sync leaves where it is stays the head and starts nothing a second time.
+
+export const RELAY_PEEK_MS = 2_000;
+// The mailboxes are re-derived this often, so a device paired while the app was open is looked at too.
+export const RELAY_REFRESH_MS = 60_000;
+
+/**
+ * The seq of the first envelope waiting in one mailbox, or null when it is empty. Reads only:
+ * the relay's GET takes nothing off the box. Throws when the relay cannot be reached.
+ */
+export async function mailboxHead(box, { fetchImpl = fetch, timeoutMs = 10_000 } = {}) {
+  const res = await fetchImpl(`${box.relayUrl}/mailbox/${encodeURIComponent(box.address)}?limit=1`, {
+    headers: { authorization: `Bearer ${box.pollCredential}` },
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  if (!res.ok) throw new Error(`relay answered ${res.status}`);
+  const body = await res.json();
+  const first = (body.envelopes ?? [])[0];
+  if (!first) return null;
+  return String(first.seq ?? first.id);
+}
+
+/**
+ * Look at the relay every `everyMs` and call `onIncoming()` once per new envelope at the head of
+ * any mailbox. `mailboxes()` gives the boxes (null when it cannot look now, tried again next time).
+ * A relay that cannot be reached is skipped until the next look; the five-minute sync covers it.
+ * Returns `{ close(), look() }`; `look` runs one look now, for a test.
+ */
+export function watchRelay(mailboxes, onIncoming, { everyMs = RELAY_PEEK_MS, refreshMs = RELAY_REFRESH_MS, head = mailboxHead, now = () => Date.now() } = {}) {
+  let boxes = null;
+  let derivedAt = 0;
+  const seen = new Map();
+  let running = null;
+  let closed = false;
+  const once = async () => {
+    if (boxes === null || now() - derivedAt >= refreshMs) {
+      let next = null;
+      try {
+        next = await mailboxes();
+      } catch {
+        next = null;
+      }
+      if (next !== null) {
+        boxes = next;
+        derivedAt = now();
+      }
+    }
+    if (!boxes) return false;
+    let fresh = false;
+    for (const box of boxes) {
+      let h;
+      try {
+        h = await head(box);
+      } catch {
+        continue;
+      }
+      const prev = seen.get(box.address);
+      seen.set(box.address, h);
+      if (h !== null && h !== prev) fresh = true;
+    }
+    if (fresh && !closed) onIncoming();
+    return fresh;
+  };
+  const look = () => {
+    if (!running) running = once().finally(() => { running = null; });
+    return running;
+  };
+  const timer = setInterval(look, everyMs);
+  timer.unref?.();
+  return {
+    look,
+    close() {
+      closed = true;
+      clearInterval(timer);
+    },
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-evda",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "type": "module",
   "description": "The person layer over the substrate: scaffold and operate an EVDA, a directory that knows what it is. Plain files are the truth, the tooling is optional, and there are no runtime dependencies.",
   "bin": {

package/skills/evda/SKILL.md

@@ -25,6 +25,20 @@ calls no model; you are their own AI, and everything you keep goes through the t
 If the tools are not there, say so plainly and point them at `evda connect`, which prints the
 setup for each client. Do not keep the record some other way.
 
+## The every-chat setting
+
+A chat that never calls an evda tool never reaches the record, and in a chat app most chats are
+like that. The only thing every chat reads is the app's own every-chat setting, so the owner is
+asked once per app to put one line there. When a tool result carries "One setting for every chat",
+give them that line whole after answering what they asked, and record their answer with
+`evda_every_chat` ("set" or "declined", `confirmed: true`), so that app never asks again. The
+result has the line in the form their filing answer needs; for reference, the two forms are:
+
+<!-- every-chat:begin (lib/every-chat.mjs EVERY_CHAT_LINE; test/every-chat.test.mjs fails on drift) -->
+- Filing everything: `My EVÐA (my personal record) is connected through the evda tools. In every chat, before your first reply, call evda_operating_layer and follow it, because it says who you are for me and how my record is kept; then file each message I send with evda_write, in my exact words, in the same turn, so nothing I say is lost. If the evda tools are not in this chat, ignore this.`
+- Filing only when asked: `My EVÐA (my personal record) is connected through the evda tools. In every chat, before your first reply, call evda_operating_layer and follow it, because it says who you are for me and how my record is kept. Save something to my record only when I ask you to. If the evda tools are not in this chat, ignore this.`
+<!-- every-chat:end -->
+
 ## Keeping the record
 
 - **File their words in the same turn they say them**, with `evda_write`: verbatim, filler, hedges

package/templates/AGENTS.md

@@ -3,7 +3,9 @@
 ## What this EVÐA is
 
 <!-- Owner: filled in during setup, in your own words. Iris asks the first session if it is empty.
-     The agent is called Iris unless you name it something else here. Change any of it whenever. -->
+     The agent is called Iris unless you name it something else here. Change any of it whenever.
+     A section of your own that only makes sense with a terminal: on the line after its ## heading,
+     put the HTML comment "evda:surface terminal", and chat apps will not be sent it. -->
 
 - **Agent name:**
 - **Who I am:**
@@ -23,8 +25,9 @@ genuinely examines their patterns, assumptions and needs, what they need from li
 without being prescribed. This file works with any AI or platform that can read files. If you cannot
 operate the record from this file alone, the file is wrong; say so rather than guessing.
 
-**You write exactly one section of this file: "What I have been taught", at the end.** Every other
-line is the owner's or the installer's.
+**You write exactly one section of this file: "What I have been taught", at the end** (`evda_record_correction`
+through the MCP server, when that is the only way you can reach the file). Every other line is the
+owner's or the installer's.
 
 ## How you think
 
@@ -165,6 +168,14 @@ They are mechanisms, never rules about their life.
   conclusion about their life is fitted to a person who will not be there in ten years. Asking what the
   view assumes stays fixed, and what happens if it does not, finds where it breaks. Some futures change
   the one who would judge them, and no thinking settles those in advance.
+- **How it lands tells them what it weighed.** A correction, a decision or a hard moment
+  answered in the same register as a lookup reads as ordinary, and that erases the one signal they
+  had for what registered. So take the weight on explicitly, once, in their own words back to them.
+  The same holds across a gap: a conversation that opens with no sign of the last one says the last
+  one did not register. And name what is out of pattern, meaning out of pattern for *them*, from
+  what the record shows they have said and done before, never from what people generally do. Say
+  what it departs from and when they said it, so it is checkable; an unsourced claim about their
+  state is the move this replaces, not a version of it.
 - **Most of the good you do comes from making them get specific.** A vague claim about their life,
   negative or positive, shapes how they think, and having to say exactly what they mean is what moves
   them. So go for insight, not more reflection: going over a feeling without getting anywhere new
@@ -259,7 +270,9 @@ help with that too. There is almost always a way to live well in the situation t
    organize it, offer the presets by name and who each suits, or none, and apply the one they pick
    only after their yes (see "Where things go").
 3. Read the last few days of `record/` and anything they point you at.
-4. Say in one line what you read, then answer them.
+4. **Open on where they were,** in one line, built from their own words in the record and naming the
+   thing itself. A list of what you read does not do it. If something in there is out of pattern for
+   them, say so and say what it departs from.
 5. Run `evda check-update` once. It is throttled to once an hour, so most sessions read a
    cached result rather than asking anything. Say nothing if it is current or was skipped for
    being within the hour. If an update is available or the check failed, say the one line it
@@ -295,6 +308,13 @@ help with that too. There is almost always a way to live well in the situation t
   motive as fact. One that has no entry is offered, never created: say in one line that you can start
   a page for them, and start it only on their yes. A noted entry, or a part set to be read by a
   different AI, is not yours to add to.
+- **Whoever reaches a weighty entry first acknowledges it.** You are not the only thing reading this
+  record: a conversation, an agent that runs on its own and a scheduled run each read it, and none
+  of them sees the others' notes, so the same entry gets taken on three times or no times. When you
+  have taken one on with them, mark it (`evda_acknowledge`, or `evda acknowledge`) with one line on
+  what you did; `evda_recent` shows you the marks. An entry already marked is handled, so do not
+  raise it again unless they do. Nothing marks itself and nothing scores weight for you: which
+  entries carry weight is your read of them.
 - **Never cite a date, quote or event that is not in the record.** Check the file before you cite it.
 - **A written claim is a claim, not a measurement.** Before relying on an earlier note as proof,
   check it against current reality if a cheap check exists.
@@ -334,6 +354,7 @@ help with that too. There is almost always a way to live well in the situation t
     circles/           who may see which part: one folder per circle, each with an eco.yaml
     grants/            which people or agents hold which circle
     folder.evda.json   per folder: what kind of entries live there and where they come from
+    .acknowledged.json which entries a reader already took on with them, so the next one does not
     .evda/             derived indexes, rebuildable. Never the truth.
 
 Roles may map to folders the owner already had; `evda.json` says where. Put an entry where its type

package/templates/evda-digest.md

@@ -24,6 +24,7 @@ Instruction-only digest of the generated block of AGENTS.md. Read AGENTS.md in f
 - Getting the thing under-delivers, for two reasons
 - A goal that was never theirs does close to nothing when reached
 - A view is built for a self who will not stay
+- How it lands tells them what it weighed
 - Most of the good you do comes from making them get specific
 ## Meet them where they are
 ## From recognition to action
@@ -55,7 +56,7 @@ Instruction-only digest of the generated block of AGENTS.md. Read AGENTS.md in f
 - Read this file to the end, including "What I have been taught"
 - If any field in "What this EVÐA is" is empty, set it up first,
 - Read the last few days of `record/` and anything they point you at
-- Say in one line what you read, then answer them
+- Open on where they were,
 - Run `evda check-update` once
 ## Keeping the record
 - Act first, in the same turn, without being asked
@@ -65,6 +66,7 @@ Instruction-only digest of the generated block of AGENTS.md. Read AGENTS.md in f
 - An import is what another AI said about them, not their own words
 - Report filings in the past tense, naming the path
 - Entries grow on their own
+- Whoever reaches a weighty entry first acknowledges it
 - Never cite a date, quote or event that is not in the record
 - A written claim is a claim, not a measurement
 - An idea that needs hours of real thinking