@staix/vault-mem 0.5.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/CHANGELOG.md +66 -0
  2. package/README.md +140 -23
  3. package/package.json +5 -4
  4. package/src/amem/seam.ts +15 -6
  5. package/src/analysis-commands.ts +1 -1
  6. package/src/analysis-input.ts +24 -3
  7. package/src/analysis-reports.ts +1 -1
  8. package/src/analysis-types.ts +13 -1
  9. package/src/canon-tables.ts +190 -0
  10. package/src/cli-output.ts +15 -1
  11. package/src/cli.ts +1 -1
  12. package/src/commands-table.ts +6 -2
  13. package/src/config.ts +31 -3
  14. package/src/frontmatter.ts +10 -3
  15. package/src/links.ts +13 -1
  16. package/src/mcp-spec.ts +19 -11
  17. package/src/mcp-vault.ts +14 -9
  18. package/src/mcp.ts +4 -2
  19. package/src/org-promote.ts +29 -12
  20. package/src/promote.ts +24 -12
  21. package/src/read-commands.ts +1 -2
  22. package/src/read-output.ts +7 -5
  23. package/src/registry.ts +1 -0
  24. package/src/skills-mine.ts +5 -4
  25. package/src/spec-command-table.ts +10 -1
  26. package/src/spec-commands.ts +7 -3
  27. package/src/spec-gitlinks.ts +106 -0
  28. package/src/spec-output.ts +30 -0
  29. package/src/spec-source.ts +9 -3
  30. package/src/spec-validate.ts +6 -3
  31. package/src/spec-write.ts +469 -0
  32. package/src/ui/inbox-source.ts +46 -0
  33. package/src/ui/inbox-worker.ts +8 -0
  34. package/src/ui/inbox.ts +152 -0
  35. package/src/ui/panel.js +26 -5
  36. package/src/ui/plugin.ts +42 -65
  37. package/src/ui/snapshot-cache.ts +123 -0
  38. package/src/vault-index.ts +109 -19
  39. package/src/vault-lint.ts +53 -5
  40. package/src/vault-log.ts +3 -2
  41. package/src/vault-stats.ts +110 -5
  42. package/src/write-commands.ts +4 -3
  43. package/src/write-files.ts +63 -0
  44. package/src/write-operations.ts +175 -25
  45. package/src/write-output.ts +20 -9
  46. package/src/write-types.ts +8 -1
  47. package/src/write-validation.ts +46 -17
  48. package/src/writer.ts +137 -41
  49. package/src/yaml-quoted.ts +12 -2
@@ -0,0 +1,152 @@
1
+ import { nextSnapshotCursor } from "./snapshot-cache.ts";
2
+ import { Worker } from "node:worker_threads";
3
+ import type { InboxItem } from "@staix/agent-console/contract";
4
+ import type { VaultSpec } from "../config.ts";
5
+ import type { InboxSource } from "./inbox-source.ts";
6
+
7
+ const CACHE_MS = 60_000;
8
+ // Revision-triggered refreshes keep this gap from the start of the last collection, so steady vault writes cannot
9
+ // rerun every source on each poll. An applied console write invalidates the inbox directly and bypasses the gap.
10
+ const REVISION_MS = 10_000;
11
+ const FIRST_WAIT_MS = 700;
12
+ const SOURCE_MS = 30_000;
13
+ // agent-mem has no total-count API; a saturated candidate source can only report a lower bound.
14
+ export type InboxRows = { items: InboxItem[]; more: number; moreIsLowerBound?: boolean };
15
+
16
+ function readInboxRows(value: unknown): InboxRows {
17
+ if (!value || typeof value !== "object" || !("items" in value) || !Array.isArray(value.items)
18
+ || !("more" in value) || typeof value.more !== "number" || !Number.isSafeInteger(value.more) || value.more < 0) {
19
+ throw new Error("inbox source returned no valid result; inspect System and restart the console provider");
20
+ }
21
+ return value as InboxRows;
22
+ }
23
+
24
+ /** An explicit error is a failure even when its message is empty. */
25
+ export function readInboxWorkerMessage(message: unknown): InboxRows {
26
+ if (message && typeof message === "object" && "error" in message) {
27
+ throw new Error(typeof message.error === "string" && message.error ? message.error
28
+ : "inbox source failed without an error message; inspect System and retry");
29
+ }
30
+ return readInboxRows(message && typeof message === "object" && "result" in message ? message.result : undefined);
31
+ }
32
+
33
+ /** Urgent rows precede candidates; newest candidates first. Never ship full lint reports or memory bodies. */
34
+ export function boundInbox(items: InboxItem[], more = 0, moreIsLowerBound = false): InboxRows {
35
+ const rank = (i: InboxItem) => {
36
+ if (i.chip?.tone === "err") return 0;
37
+ if (i.group === "alert") return 1;
38
+ return 2;
39
+ };
40
+ const clip = (value: string, limit: number) => {
41
+ let out = "", count = 0;
42
+ for (const point of value) { if (count++ === limit) break; out += point; }
43
+ return out;
44
+ };
45
+ const sorted = [...items].sort((a, b) => rank(a) - rank(b) || b.at.localeCompare(a.at) || a.id.localeCompare(b.id));
46
+ return { items: sorted.slice(0, 50).map(i => ({ ...i, title: clip(i.title, 160), ...(i.detail ? { detail: clip(i.detail, 240) } : {}) })),
47
+ more: more + Math.max(0, items.length - 50), ...(moreIsLowerBound ? { moreIsLowerBound: true } : {}) };
48
+ }
49
+
50
+ /** Workers isolate synchronous lint, SQLite and Git from requests. The deadline initiates termination;
51
+ * shutdown can still wait for a blocking native call, so the queue waits before starting another worker. */
52
+ export function runInboxSource(home: string, source: InboxSource): { result: Promise<InboxRows>; cancel: () => void } {
53
+ const panel = { candidates: "Promote", lint: "Lint", sync: "Overview" }[source.kind];
54
+ const worker = new Worker(new URL("./inbox-worker.ts", import.meta.url), { workerData: { home, source }, env: { ...process.env } });
55
+ let cancel = () => {};
56
+ const result = new Promise<InboxRows>((resolve, reject) => {
57
+ let settled = false;
58
+ const finish = (error?: Error, rows?: InboxRows) => {
59
+ if (settled) return;
60
+ settled = true; clearTimeout(timer);
61
+ void worker.terminate().then(() => {
62
+ if (error) reject(error); else resolve(rows!);
63
+ }, failure => reject(failure));
64
+ };
65
+ const timer = setTimeout(() => finish(new Error(`inbox ${source.kind} timed out after 30 s; inspect ${panel} and System, then retry`)), SOURCE_MS);
66
+ cancel = () => finish(new Error("inbox closed"));
67
+ worker.once("message", (message: unknown) => {
68
+ try { finish(undefined, readInboxWorkerMessage(message)); }
69
+ catch (error) { finish(error instanceof Error ? error : new Error(String(error))); }
70
+ });
71
+ worker.once("error", error => finish(error instanceof Error ? error : new Error(String(error))));
72
+ worker.once("exit", code => finish(new Error(`inbox worker exited (${code}); inspect System and restart the console provider`)));
73
+ });
74
+ return { result, cancel: () => cancel() };
75
+ }
76
+
77
+ type Runner = typeof runInboxSource;
78
+ /** `now` is looked up per call, so a test that spies on `Date.now` after opening the provider still moves this clock. */
79
+ export function createInboxSnapshot(home: string, vaults: VaultSpec[], log: (message: string) => void, run: Runner = runInboxSource, getRevision?: () => number, now: () => number = () => Date.now()) {
80
+ const sources: InboxSource[] = [...vaults.filter(v => v.kind === "org").map(vault => ({ kind: "sync" as const, vault })),
81
+ ...vaults.filter(v => v.kind === "personal").map(vault => ({ kind: "lint" as const, vault })), { kind: "candidates" }];
82
+ const rows = new Map<number, InboxRows>(), firstSeen = new Map<string, string>();
83
+ let cached: InboxRows | undefined, flight: Promise<void> | undefined, at = -Infinity, revision = 0, closed = false;
84
+ // `stale` is a revision change not yet collected; `due` is the earliest start of the next revision-triggered run.
85
+ let stale = false, due = -Infinity;
86
+ let cancel: (() => void) | undefined;
87
+ let sourceRevision = getRevision?.(), cursor = nextSnapshotCursor(), waited = false;
88
+ const statusAt = new Date().toISOString();
89
+ const status = (unavailable: boolean): InboxRows => ({ items: [{
90
+ id: unavailable ? "inbox:unavailable" : "inbox:refresh", group: "alert", kind: "status",
91
+ title: unavailable ? "Vault inbox is unavailable" : "Vault inbox is refreshing",
92
+ detail: unavailable ? "Inspect System, then retry." : "The first collection is running; check again shortly.",
93
+ at: statusAt, verbs: [], link: { panel: "overview" },
94
+ }], more: 0 });
95
+ function refresh() {
96
+ if (closed || flight || now() - at < CACHE_MS) return;
97
+ cursor = nextSnapshotCursor();
98
+ const started = revision;
99
+ // This run collects everything up to `started`; the next revision-triggered run waits for the gap.
100
+ stale = false; due = now() + REVISION_MS;
101
+ flight = (async () => {
102
+ // One worker at a time, including failed sources. A source's deadline covers its entire expensive step.
103
+ for (const [index, source] of sources.entries()) {
104
+ if (closed) return;
105
+ try {
106
+ const job = run(home, source); cancel = job.cancel;
107
+ rows.set(index, readInboxRows(await job.result));
108
+ } catch (error) {
109
+ if (!closed) log(`vmem: ${source.kind === "sync" ? "sync pending" : source.kind}${"vault" in source ? ` ${source.vault.id}` : ""} failed: ${error instanceof Error ? error.message : String(error)}`);
110
+ } finally { cancel = undefined; }
111
+ }
112
+ if (closed) return;
113
+ const all = [...rows.values()].flatMap(r => r.items);
114
+ for (const item of all) if (item.group === "alert") {
115
+ item.at = firstSeen.get(item.id) ?? item.at; firstSeen.set(item.id, item.at);
116
+ }
117
+ const ids = new Set(all.map(i => i.id));
118
+ for (const id of firstSeen.keys()) if (!ids.has(id)) firstSeen.delete(id);
119
+ cached = rows.size === 0 ? status(true) : boundInbox(all, [...rows.values()].reduce((n, r) => n + r.more, 0), [...rows.values()].some(r => r.moreIsLowerBound));
120
+ // An action during collection leaves these rows one revision behind: refresh again once the gap passes.
121
+ at = now(); if (started !== revision) stale = true;
122
+ })().catch(error => {
123
+ // Warm snapshots do not await this promise. Never let a refresh failure escape to the console.
124
+ if (!closed) {
125
+ cached ??= status(true);
126
+ at = now(); if (started !== revision) stale = true;
127
+ try { log(`vmem: inbox refresh failed: ${error instanceof Error ? error.message : String(error)}; inspect System and retry`); }
128
+ catch { /* A failed log sink must not create another unhandled rejection. */ }
129
+ }
130
+ }).finally(() => { flight = undefined; cursor = nextSnapshotCursor(); });
131
+ }
132
+ return {
133
+ async snapshot(): Promise<InboxRows & { cursor: number; refreshing?: boolean }> {
134
+ const current = getRevision?.();
135
+ if (current !== sourceRevision) { sourceRevision = current; revision++; stale = true; }
136
+ // A revision change refreshes at most once per gap; a console write clears the gate in `invalidate`.
137
+ if (stale && now() >= due) { stale = false; at = -Infinity; }
138
+ refresh();
139
+ if (!cached && flight && !waited) {
140
+ waited = true;
141
+ let timer: ReturnType<typeof setTimeout> | undefined;
142
+ await Promise.race([flight, new Promise<void>(resolve => { timer = setTimeout(resolve, FIRST_WAIT_MS); })]);
143
+ clearTimeout(timer);
144
+ }
145
+ return { ...(cached ?? status(false)), cursor, ...(flight ? { refreshing: true } : {}) };
146
+ },
147
+ // An applied console write is immediate: it bypasses the revision gap for the next poll, including any log
148
+ // append the same write made, then the gap starts again from that collection.
149
+ invalidate() { revision++; at = -Infinity; due = -Infinity; cursor = nextSnapshotCursor(); },
150
+ async close() { closed = true; cancel?.(); await flight; },
151
+ };
152
+ }
package/src/ui/panel.js CHANGED
@@ -84,9 +84,17 @@ export default (host) => {
84
84
  const meta = Object.fromEntries(Object.entries(values).map(([k, v]) => [k, v.trim()]).filter(([, v]) => v));
85
85
  host.action({ action: "promote-from-amem", id: picked.id, project: picked.project, ...meta, ...vaultParam() });
86
86
  })) : null;
87
+ // `reset` only says the page token was stale: the reply can land on the page holding the selected candidate.
88
+ // The returned page index decides whether an earlier page exists; an unavailable reply has none, so there a
89
+ // stale page param can still be cleared.
90
+ const pageIndex = Number(String(s.page ?? "").split(":")[1]);
91
+ const showFirst = Number.isSafeInteger(pageIndex) ? pageIndex > 0 : Boolean(params.page);
87
92
  return [s.unavailable ? ui.notice(s.unavailable, "err") : null, form,
88
- ui.rows(all, (c) => ui.row({ title: c.title || c.kind, sub: `${c.kind} · ${c.project} · ${new Date(c.at).toLocaleString()}`, onOpen: () => go("promote", { id: c.id, project: c.project }),
89
- ...(s.selected === c.id ? { chip: { text: "selected", tone: "neutral" } } : { verbs: [ui.button("Select", () => go("promote", { id: c.id, project: c.project }))] }) }))
93
+ s.nextPage || showFirst ? h("div", { class: "vmem-bar" },
94
+ ...(showFirst ? [ui.button("First page", () => go("promote"))] : []),
95
+ ...(s.nextPage ? [ui.button("Next page", () => go("promote", { page: s.nextPage }))] : [])) : null,
96
+ ui.rows(all, (c) => ui.row({ title: c.title || c.kind, sub: `${c.kind} · ${c.project} · ${new Date(c.at).toLocaleString()}`, onOpen: () => go("promote", { id: c.id, project: c.project, page: s.page }),
97
+ ...(s.selected === c.id ? { chip: { text: "selected", tone: "neutral" } } : { verbs: [ui.button("Select", () => go("promote", { id: c.id, project: c.project, page: s.page }))] }) }))
90
98
  ?? ui.empty("No promotion candidates", "Durable agent memories appear here when agent-mem marks them for the vault.")];
91
99
  },
92
100
  lint(s) {
@@ -106,8 +114,9 @@ export default (host) => {
106
114
  },
107
115
  };
108
116
 
109
- let last = "";
110
- host.onSnapshot((snap) => {
117
+ let last = "", savedView = "", savedSnapshot;
118
+ const viewKey = () => JSON.stringify([panel, params]);
119
+ const render = (snap) => {
111
120
  const sig = JSON.stringify([panel, snap]);
112
121
  if (sig === last) return; // unchanged poll: keep focus and scroll
113
122
  last = sig;
@@ -118,9 +127,21 @@ export default (host) => {
118
127
  root.replaceChildren(...(views[panel]?.(snap) ?? [ui.empty("Unknown panel")]).filter(Boolean));
119
128
  for (const el of root.querySelectorAll("input[name], select[name]")) if (values.has(el.name)) el[el.type === "checkbox" ? "checked" : "value"] = values.get(el.name);
120
129
  if (focused) root.querySelector(`[name="${focused}"]`)?.focus();
130
+ };
131
+ host.onSnapshot((snap) => {
132
+ if (snap.changed === false) {
133
+ if (last === "" && savedView === viewKey() && savedSnapshot) render(savedSnapshot);
134
+ return;
135
+ }
136
+ savedView = viewKey(); savedSnapshot = snap;
137
+ render(snap);
121
138
  });
122
139
  return {
123
- show(id, p = {}) { panel = id; params = p; last = ""; root.replaceChildren(); },
140
+ show(id, p = {}) {
141
+ panel = id; params = p; last = ""; root.replaceChildren();
142
+ // Some shells suppress unchanged replies before invoking onSnapshot. Restore on show too.
143
+ if (savedView === viewKey() && savedSnapshot) render(savedSnapshot);
144
+ },
124
145
  hide() {},
125
146
  destroy() { root.remove(); },
126
147
  };
package/src/ui/plugin.ts CHANGED
@@ -3,15 +3,15 @@
3
3
  * The provider reuses the `vmem mcp` handlers in process, so the console acts with exactly the MCP rights and checks.
4
4
  */
5
5
  import { readFileSync } from "node:fs";
6
- import type { ActionResult, Change, ConsolePlugin, ConsoleProvider, InboxItem } from "@staix/agent-console/contract";
6
+ import type { ActionResult, Change, ConsolePlugin, ConsoleProvider } from "@staix/agent-console/contract";
7
7
  import { analysisInput } from "../analysis-input.ts";
8
8
  import { resolveHome } from "../home.ts";
9
9
  import { createVaultMcp } from "../mcp-vault.ts";
10
10
  import { validArguments } from "../mcp.ts";
11
11
  import { listPromotionCandidates } from "../promote.ts";
12
12
  import { loadRegistry } from "../registry.ts";
13
- import { localSyncPending, STAGED_DESCRIPTION } from "../sync.ts";
14
- import { isDenied } from "../platform.ts";
13
+ import { createSnapshotRevision, createPromoteSnapshot, nextSnapshotCursor } from "./snapshot-cache.ts";
14
+ import { createInboxSnapshot } from "./inbox.ts";
15
15
  import { lintVault } from "../vault-lint.ts";
16
16
  import { readLogSince } from "../vault-log.ts";
17
17
  import type { LintCode } from "../analysis-types.ts";
@@ -123,7 +123,7 @@ export const plugin: ConsolePlugin = {
123
123
  return validArguments(out, schema ?? { type: "object" }) ? out : `invalid input for ${tool}`;
124
124
  };
125
125
 
126
- // ponytail: lint reads every note, so inbox polls reuse one result per vault for 60 s; invalidate on writes if it lags.
126
+ // The Lint panel reuses its report for 60 s; inbox collection has its own off-thread cache.
127
127
  const lintCache = new Map<string, { at: number; report: ReturnType<typeof lintVault> }>();
128
128
  const lint = (id: string) => {
129
129
  const hit = lintCache.get(id);
@@ -133,66 +133,19 @@ export const plugin: ConsolePlugin = {
133
133
  lintCache.set(id, { at: Date.now(), report });
134
134
  return report;
135
135
  };
136
- // Like lint, local Git state refreshes at most once per minute, including failures.
137
- const syncCache = new Map<string, { at: number; pending: ReturnType<typeof localSyncPending> | null }>();
138
- const syncPending = (id: string) => {
139
- const hit = syncCache.get(id);
140
- if (hit && Date.now() - hit.at < CACHE_MS) return hit.pending;
141
- let pending: ReturnType<typeof localSyncPending> | null = null;
142
- try {
143
- const config = loadRegistry(home), spec = config.vaults.find(v => v.id === id);
144
- const startup = mcp.vaults.find(v => v.id === id);
145
- if (!spec || JSON.stringify(spec) !== JSON.stringify(startup)) throw new Error("vault binding changed; restart the console provider");
146
- if (isDenied(spec.path, config.denyPaths)) throw new Error("vault path is denied; check its path policy in System");
147
- pending = localSyncPending(spec.path);
148
- } catch (error) { ctx.log(`vmem: sync pending ${id} failed: ${error instanceof Error ? error.message : String(error)}`); }
149
- syncCache.set(id, { at: Date.now(), pending });
150
- return pending;
151
- };
152
136
  const projectOf = new Map<string, string>();
137
+ const revision = createSnapshotRevision(home, mcp.vaults);
153
138
  const candidates = async () => {
154
- try {
155
- const { projects } = await listPromotionCandidates({ allProjects: true, limit: 50, piiPatterns: loadRegistry(home).piiPatterns });
156
- for (const p of projects) for (const c of p.candidates) projectOf.set(c.id, c.project);
157
- return { projects };
158
- }
159
- catch (error) { ctx.log(`vmem: promotion candidates unavailable: ${error instanceof Error ? error.message : String(error)}`); return { projects: [], unavailable: "agent-mem candidates are unavailable; see System" }; }
139
+ const { projects } = await listPromotionCandidates({ allProjects: true, limit: 50, piiPatterns: loadRegistry(home).piiPatterns });
140
+ projectOf.clear();
141
+ for (const p of projects) for (const c of p.candidates) projectOf.set(c.id, c.project);
142
+ return { projects };
160
143
  };
161
144
 
162
- // The shell keys snooze and oldest-first order on `at`, so an item keeps the time it was first seen.
163
- const firstSeen = new Map<string, string>();
164
- const since = (id: string) => { const at = firstSeen.get(id) ?? new Date().toISOString(); firstSeen.set(id, at); return at; };
165
- async function inbox(): Promise<InboxItem[]> {
166
- const items: InboxItem[] = [];
167
- for (const p of (await candidates()).projects) for (const c of p.candidates) items.push({
168
- id: `mem:${c.id}`, group: "candidate", kind: "promotion", title: c.title ?? c.kind, detail: `${c.kind} memory to promote into a vault note`,
169
- project: c.project, at: new Date(c.at).toISOString(),
170
- // Promotion needs a domain and topics, so the item opens the Promote panel instead of offering a one-key verb.
171
- verbs: [],
172
- link: { panel: "promote", params: { id: c.id, project: c.project } },
173
- });
174
- for (const v of mcp.vaults.filter(x => x.kind === "personal")) {
175
- let report;
176
- try { report = lint(v.id); } catch (error) { ctx.log(`vmem: lint ${v.id} failed: ${error instanceof Error ? error.message : String(error)}`); continue; }
177
- if (report.errors > 0) items.push({ id: `lint:${v.id}`, group: "alert", kind: "lint", title: `${report.errors} lint errors in ${v.id}`, detail: report.summary, at: since(`lint:${v.id}`),
178
- chip: { text: `${report.errors} errors`, tone: "err" }, verbs: [], link: { panel: "lint", params: { vault: v.id } } });
179
- const stale = report.findings.L11 ?? [];
180
- if (stale.length) items.push({ id: `stale:${v.id}`, group: "alert", kind: "lint", title: `Graph report is stale in ${v.id}`, detail: stale[0]!, at: since(`stale:${v.id}`),
181
- chip: { text: "stale", tone: "warn" }, verbs: [], link: { panel: "lint", params: { vault: v.id } } });
182
- }
183
- for (const v of mcp.vaults.filter(x => x.kind === "org")) {
184
- const pending = syncPending(v.id);
185
- if (!pending) continue;
186
- const count = pending.changed + pending.ahead;
187
- if (count > 0) items.push({ id: `sync:${v.id}`, group: "alert", kind: "sync", title: `${count} unsynced change${count === 1 ? "" : "s"} in ${v.id}`,
188
- detail: [`${pending.changed} uncommitted path${pending.changed === 1 ? "" : "s"} to sync`,
189
- ...(pending.ignored ? [`${pending.ignored} other path${pending.ignored === 1 ? "" : "s"} outside ${STAGED_DESCRIPTION} not counted`] : []),
190
- ...(pending.upstream ? [`${pending.ahead} local commit${pending.ahead === 1 ? "" : "s"} ahead of upstream`] : [])].join("; "), at: since(`sync:${v.id}`),
191
- chip: { text: "sync pending", tone: "warn" }, verbs: [], link: { panel: "overview", params: { vault: v.id } } });
192
- }
193
- for (const id of firstSeen.keys()) if (!items.some(i => i.id === id)) firstSeen.delete(id);
194
- return items;
195
- }
145
+ const promote = createPromoteSnapshot(revision.current, candidates);
146
+ const inbox = createInboxSnapshot(home, mcp.vaults, ctx.log, undefined, revision.current);
147
+ // One cursor for the whole Promote failure: a fresh one per failed scan would rebuild the panel every poll.
148
+ let promoteErrorCursor: number | undefined;
196
149
 
197
150
  /** One two-step operation: preview, and with the console's confirmation recompute and write only on the same fingerprint. */
198
151
  async function twoStep(tool: string, args: Args | string, confirmed: boolean, fingerprint: string | undefined, describe: (preview: Args) => { verb: string; preview: string[]; changes: Change[]; warnings: string[] }): Promise<ActionResult> {
@@ -204,16 +157,20 @@ export const plugin: ConsolePlugin = {
204
157
  return { ok: false, needsConfirm: true, fingerprint: preview.fingerprint, verb: d.verb, preview: d.preview, changes: d.changes, ...(d.warnings.length ? { warnings: d.warnings } : {}) };
205
158
  }
206
159
  const done = await call(tool, { ...args, confirm: true, fingerprint });
207
- if (done.applied === true) lintCache.clear();
160
+ if (done.applied === true) { lintCache.clear(); revision.invalidate(); inbox.invalidate(); }
208
161
  return confirmedOutcome(done, describe(preview).verb);
209
162
  }
210
163
 
211
164
  return {
165
+ async close() { await inbox.close(); },
212
166
  assets: { js: asset("./panel.js"), css: asset("./panel.css") },
213
167
  async snapshot(input) {
214
168
  const args = input as Args;
215
169
  switch (input.panel) {
216
- case "inbox": return { items: await inbox() };
170
+ case "inbox": {
171
+ const result = await inbox.snapshot();
172
+ return args.after === result.cursor ? { changed: false, cursor: result.cursor } : result;
173
+ }
217
174
  case "search": {
218
175
  const q = str(args.q);
219
176
  if (!q) return { hits: [], total: 0 };
@@ -246,7 +203,20 @@ export const plugin: ConsolePlugin = {
246
203
  const promotable = vaultOf(args)?.id === mcp.defaultVault && vaultOf(args)?.kind === "personal";
247
204
  return { note, links, orgVaults: promotable ? mcp.vaults.filter(v => v.kind === "org").map(v => v.id) : [] };
248
205
  }
249
- case "promote": return { ...(await candidates()), selected: str(args.id) ?? null };
206
+ case "promote": {
207
+ try {
208
+ const result = await promote.snapshot(args);
209
+ promoteErrorCursor = undefined;
210
+ return result;
211
+ } catch (error) {
212
+ ctx.log(`vmem: promotion snapshot unavailable: ${error instanceof Error ? error.message : String(error)}`);
213
+ promoteErrorCursor ??= nextSnapshotCursor();
214
+ // The shell keeps that one cursor: a matching `after` suppresses the unchanged error view.
215
+ return args.after === promoteErrorCursor
216
+ ? { changed: false, cursor: promoteErrorCursor }
217
+ : { projects: [], unavailable: "Promotion candidates are unavailable; see System", cursor: promoteErrorCursor };
218
+ }
219
+ }
250
220
  case "lint": {
251
221
  const vault = vaultOf(args);
252
222
  if (!vault) return { findings: [] };
@@ -300,8 +270,15 @@ export const plugin: ConsolePlugin = {
300
270
  case "promote-from-amem": {
301
271
  const id = (str(args.id) ?? "").replace(/^mem:/, "");
302
272
  if (!/^[0-9a-f-]{32,36}$/i.test(id)) return { ok: false, error: "a memory id is required" };
303
- if (!projectOf.has(id)) await candidates();
304
- const project = str(args.project) ?? projectOf.get(id);
273
+ let project = str(args.project) ?? projectOf.get(id);
274
+ if (!project) {
275
+ try { await candidates(); }
276
+ catch (error) {
277
+ ctx.log(`vmem: promotion candidates unavailable: ${error instanceof Error ? error.message : String(error)}`);
278
+ return { ok: false, error: "Promotion candidates are unavailable; see System" };
279
+ }
280
+ project = projectOf.get(id);
281
+ }
305
282
  return twoStep("vmem_promote_from_amem", forward("vmem_promote_from_amem", args, { id, ...(project ? { project } : {}) }), confirmed, fingerprint, p => {
306
283
  const dupes = Array.isArray(p.possibleDuplicates) ? p.possibleDuplicates as string[] : [];
307
284
  // Linking an existing note writes no vault file; it records the link in agent-mem only.
@@ -0,0 +1,123 @@
1
+ import { closeSync, constants, fstatSync, openSync, readSync } from "node:fs";
2
+ import { createHash } from "node:crypto";
3
+ import { join } from "node:path";
4
+ import type { VaultSpec } from "../config.ts";
5
+ import { CONFIG_FILE } from "../config.ts";
6
+ import type { listPromotionCandidates } from "../promote.ts";
7
+
8
+ type Candidates = Awaited<ReturnType<typeof listPromotionCandidates>>;
9
+ type Candidate = Candidates["projects"][number]["candidates"][number];
10
+ const PAGE_BYTES = 32 * 1024;
11
+ // Each of the 64 accepted selection characters can occupy six bytes after JSON escaping.
12
+ const SELECTED_BYTES = 64 * 6 + 2;
13
+ let sequence = Date.now();
14
+ export const nextSnapshotCursor = () => ++sequence;
15
+
16
+ /** Receipt metadata can share a timestamp across writes on coarse filesystems. Include a bounded
17
+ * log tail (or the entire size-limited registry) so same-size rewrites still invalidate. */
18
+ function revisionStamp(file: string, budget: number): string {
19
+ let fd: number | undefined;
20
+ try {
21
+ fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
22
+ const s = fstatSync(fd, { bigint: true });
23
+ const metadata = `${s.dev}:${s.ino}:${s.size}:${s.mtimeNs}:${s.ctimeNs}`;
24
+ if (!s.isFile()) return metadata;
25
+ const size = Number(s.size);
26
+ if (!Number.isSafeInteger(size)) throw new Error("revision source is too large");
27
+ if (budget > 256 && size > budget) throw new Error("registry exceeds its revision read budget");
28
+ const bytes = Buffer.alloc(Math.min(budget, size));
29
+ const count = readSync(fd, bytes, 0, bytes.length, Math.max(0, size - bytes.length));
30
+ return `${metadata}:${createHash("sha256").update(bytes.subarray(0, count)).digest("hex")}`;
31
+ } catch (error) {
32
+ if ((error as NodeJS.ErrnoException).code === "ENOENT") return "missing";
33
+ // A broken source must not prevent healthy vaults or unrelated panels from opening.
34
+ // Recovery changes this stamp back to file evidence and invalidates the cache.
35
+ return `error:${(error as NodeJS.ErrnoException).code ?? "UNREADABLE"}`;
36
+ } finally { if (fd !== undefined) closeSync(fd); }
37
+ }
38
+
39
+ /** A vmem write appends a receipt to its vault log. Check bounded receipt evidence, never scan notes or open Git/SQLite.
40
+ * Configuration changes also invalidate policy-screened candidates. An explicit invalidation covers an
41
+ * applied console write whose follow-up log failed, including link-only agent-mem promotions. */
42
+ export function createSnapshotRevision(home: string, vaults: VaultSpec[]) {
43
+ const files = [{ file: join(home, CONFIG_FILE), budget: 64 * 1024 }, ...vaults.map(vault => ({ file: join(vault.path, "log"), budget: 256 }))];
44
+ let previous = "", cursor = nextSnapshotCursor();
45
+ return {
46
+ current(): number {
47
+ const stamp = files.map(({ file, budget }) => revisionStamp(file, budget)).join("|");
48
+ if (stamp !== previous) { previous = stamp; cursor = nextSnapshotCursor(); }
49
+ return cursor;
50
+ },
51
+ invalidate() { cursor = nextSnapshotCursor(); },
52
+ };
53
+ }
54
+
55
+ /** Retain only the brief candidate metadata, and prepare byte-bounded pages once per revision.
56
+ * `cursor` identifies the page (including selection), `nextPage` is navigation, and `after` is conditional polling. */
57
+ export function createPromoteSnapshot(revision: () => number, load: () => Promise<Candidates>, now: () => number = Date.now) {
58
+ let cached: { revision: number; generation: number; digest: string; at: number; pages: Candidate[][] } | undefined;
59
+ let flight: Promise<void> | undefined;
60
+ const cursors = new Map<string, number>();
61
+ function response(rows: Candidate[], selected: string | null, cursor: number, page: string, nextPage?: string) {
62
+ const projects: Candidates["projects"] = [];
63
+ for (const row of rows) {
64
+ let project = projects.find(p => p.project === row.project);
65
+ if (!project) { project = { project: row.project, candidates: [] }; projects.push(project); }
66
+ project.candidates.push(row);
67
+ }
68
+ return { projects, selected, cursor, page, ...(nextPage ? { nextPage } : {}) };
69
+ }
70
+ return {
71
+ async snapshot(args: Record<string, unknown>): Promise<Record<string, unknown>> {
72
+ // A concurrent write may move the revision while the scan runs. Never label that scan as the new revision.
73
+ let attempts = 0;
74
+ while (!cached || cached.revision !== revision() || now() - cached.at >= 60_000) {
75
+ // Bound retries under sustained writes, retaining the last completed pages at their old revision.
76
+ if (++attempts > 2 && cached) break;
77
+ if (!flight) {
78
+ const started = revision();
79
+ flight = (async () => {
80
+ const result = await load();
81
+ const pages: Candidate[][] = [[]];
82
+ for (const project of result.projects) for (const item of project.candidates) {
83
+ const candidate = { ...item, title: item.title === null ? null : [...item.title].slice(0, 160).join("") };
84
+ const rows = pages.at(-1)!;
85
+ // Reserve enough envelope space for cursors, page tokens, and selection/reset metadata.
86
+ if (Buffer.byteLength(JSON.stringify(response([...rows, candidate], null, Number.MAX_SAFE_INTEGER, "x".repeat(80), "x".repeat(80)))) + SELECTED_BYTES > PAGE_BYTES - 256) {
87
+ if (rows.length === 0) throw new Error(`promotion candidate ${candidate.id.slice(0, 64)} in project ${candidate.project.slice(0, 160)} exceeds the 32 KiB page budget; inspect and shorten its agent-mem project or candidate metadata, then retry`);
88
+ pages.push([]);
89
+ if (Buffer.byteLength(JSON.stringify(response([candidate], null, Number.MAX_SAFE_INTEGER, "x".repeat(80), "x".repeat(80)))) + SELECTED_BYTES > PAGE_BYTES - 256) throw new Error(`promotion candidate ${candidate.id.slice(0, 64)} in project ${candidate.project.slice(0, 160)} exceeds the 32 KiB page budget; inspect and shorten its agent-mem project or candidate metadata, then retry`);
90
+ }
91
+ pages.at(-1)!.push(candidate);
92
+ }
93
+ const digest = createHash("sha256").update(JSON.stringify(pages)).digest("hex");
94
+ const identical = cached?.digest === digest;
95
+ cached = { revision: started, generation: identical ? cached!.generation : nextSnapshotCursor(), digest, at: now(), pages };
96
+ if (!identical) cursors.clear();
97
+ })().catch(error => {
98
+ // An error view replaces the last good view. Recovery must send full rows even when identical.
99
+ cursors.clear();
100
+ throw error;
101
+ }).finally(() => { flight = undefined; });
102
+ }
103
+ await flight;
104
+ }
105
+ const { pages, generation: rev } = cached;
106
+ const selected = typeof args.id === "string" && args.id.length <= 64 ? args.id : null;
107
+ const token = typeof args.page === "string" ? /^(\d+):(\d+)$/.exec(args.page) : null;
108
+ const validPage = token !== null && Number(token[1]) === rev && Number.isSafeInteger(Number(token[2])) && Number(token[2]) < pages.length;
109
+ const reset = args.page !== undefined && !validPage;
110
+ let index = validPage ? Number(token[2]) : 0;
111
+ if (!validPage && selected) index = Math.max(0, pages.findIndex(rows => rows.some(row => row.id === selected)));
112
+ const key = `${index}:${selected ?? ""}`;
113
+ let cursor = cursors.get(key);
114
+ if (cursor === undefined) {
115
+ // A bounded set of view cursors avoids growing with arbitrary selection inputs.
116
+ if (cursors.size >= 256) cursors.delete(cursors.keys().next().value!);
117
+ cursor = nextSnapshotCursor(); cursors.set(key, cursor);
118
+ }
119
+ if (args.after === cursor) return { changed: false, cursor };
120
+ return { ...response(pages[index]!, selected, cursor, `${rev}:${index}`, index + 1 < pages.length ? `${rev}:${index + 1}` : undefined), ...(reset ? { reset: true } : {}) };
121
+ },
122
+ };
123
+ }