agent-recall-core 3.4.51 → 3.5.3
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.
- package/README.md +670 -330
- package/dist/digest/match.d.ts +2 -0
- package/dist/digest/match.d.ts.map +1 -1
- package/dist/digest/match.js +5 -0
- package/dist/digest/match.js.map +1 -1
- package/dist/digest/store.d.ts.map +1 -1
- package/dist/digest/store.js +2 -3
- package/dist/digest/store.js.map +1 -1
- package/dist/embeddings/config.d.ts.map +1 -1
- package/dist/embeddings/config.js +17 -4
- package/dist/embeddings/config.js.map +1 -1
- package/dist/helpers/alignment-patterns.d.ts +46 -0
- package/dist/helpers/alignment-patterns.d.ts.map +1 -1
- package/dist/helpers/alignment-patterns.js +103 -2
- package/dist/helpers/alignment-patterns.js.map +1 -1
- package/dist/helpers/journal-files.d.ts +12 -6
- package/dist/helpers/journal-files.d.ts.map +1 -1
- package/dist/helpers/journal-files.js +13 -7
- package/dist/helpers/journal-files.js.map +1 -1
- package/dist/index.d.ts +23 -6
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +23 -5
- package/dist/index.js.map +1 -1
- package/dist/palace/rooms.d.ts +7 -0
- package/dist/palace/rooms.d.ts.map +1 -1
- package/dist/palace/rooms.js +13 -0
- package/dist/palace/rooms.js.map +1 -1
- package/dist/prompts/consolidation-prompt.js +14 -14
- package/dist/retrieval/candidates.d.ts +17 -0
- package/dist/retrieval/candidates.d.ts.map +1 -1
- package/dist/retrieval/candidates.js +4 -2
- package/dist/retrieval/candidates.js.map +1 -1
- package/dist/retrieval/contradiction.d.ts +42 -0
- package/dist/retrieval/contradiction.d.ts.map +1 -1
- package/dist/retrieval/contradiction.js +126 -7
- package/dist/retrieval/contradiction.js.map +1 -1
- package/dist/retrieval/lexical-index.d.ts +150 -0
- package/dist/retrieval/lexical-index.d.ts.map +1 -0
- package/dist/retrieval/lexical-index.js +516 -0
- package/dist/retrieval/lexical-index.js.map +1 -0
- package/dist/retrieval/query-memory.d.ts +17 -7
- package/dist/retrieval/query-memory.d.ts.map +1 -1
- package/dist/retrieval/query-memory.js +279 -71
- package/dist/retrieval/query-memory.js.map +1 -1
- package/dist/storage/classification.d.ts.map +1 -1
- package/dist/storage/classification.js +6 -1
- package/dist/storage/classification.js.map +1 -1
- package/dist/storage/content-guard.d.ts +32 -0
- package/dist/storage/content-guard.d.ts.map +1 -1
- package/dist/storage/content-guard.js +467 -48
- package/dist/storage/content-guard.js.map +1 -1
- package/dist/storage/corrections.d.ts +3 -1
- package/dist/storage/corrections.d.ts.map +1 -1
- package/dist/storage/corrections.js +52 -67
- package/dist/storage/corrections.js.map +1 -1
- package/dist/storage/cwd-allowlist.d.ts +30 -2
- package/dist/storage/cwd-allowlist.d.ts.map +1 -1
- package/dist/storage/cwd-allowlist.js +105 -22
- package/dist/storage/cwd-allowlist.js.map +1 -1
- package/dist/storage/deferred-bookkeeping.d.ts +34 -0
- package/dist/storage/deferred-bookkeeping.d.ts.map +1 -0
- package/dist/storage/deferred-bookkeeping.js +201 -0
- package/dist/storage/deferred-bookkeeping.js.map +1 -0
- package/dist/storage/filelock.d.ts +26 -8
- package/dist/storage/filelock.d.ts.map +1 -1
- package/dist/storage/filelock.js +202 -26
- package/dist/storage/filelock.js.map +1 -1
- package/dist/storage/frontmatter.d.ts +14 -0
- package/dist/storage/frontmatter.d.ts.map +1 -0
- package/dist/storage/frontmatter.js +22 -0
- package/dist/storage/frontmatter.js.map +1 -0
- package/dist/storage/fs-utils.d.ts +53 -0
- package/dist/storage/fs-utils.d.ts.map +1 -1
- package/dist/storage/fs-utils.js +140 -2
- package/dist/storage/fs-utils.js.map +1 -1
- package/dist/storage/hook-session.d.ts +9 -0
- package/dist/storage/hook-session.d.ts.map +1 -0
- package/dist/storage/hook-session.js +49 -0
- package/dist/storage/hook-session.js.map +1 -0
- package/dist/storage/identity-card.d.ts +27 -0
- package/dist/storage/identity-card.d.ts.map +1 -0
- package/dist/storage/identity-card.js +86 -0
- package/dist/storage/identity-card.js.map +1 -0
- package/dist/storage/lifecycle-telemetry.d.ts +1 -1
- package/dist/storage/lifecycle-telemetry.d.ts.map +1 -1
- package/dist/storage/lifecycle-telemetry.js +2 -2
- package/dist/storage/lifecycle-telemetry.js.map +1 -1
- package/dist/storage/memory-protocol.js +55 -55
- package/dist/storage/paths.d.ts.map +1 -1
- package/dist/storage/paths.js +7 -2
- package/dist/storage/paths.js.map +1 -1
- package/dist/storage/pending.d.ts +39 -3
- package/dist/storage/pending.d.ts.map +1 -1
- package/dist/storage/pending.js +126 -20
- package/dist/storage/pending.js.map +1 -1
- package/dist/storage/project.d.ts.map +1 -1
- package/dist/storage/project.js +34 -9
- package/dist/storage/project.js.map +1 -1
- package/dist/storage/session.d.ts.map +1 -1
- package/dist/storage/session.js +43 -16
- package/dist/storage/session.js.map +1 -1
- package/dist/storage/state-card.d.ts +59 -0
- package/dist/storage/state-card.d.ts.map +1 -0
- package/dist/storage/state-card.js +162 -0
- package/dist/storage/state-card.js.map +1 -0
- package/dist/storage/store-manifest.js +57 -57
- package/dist/storage/unclaimed.js +2 -2
- package/dist/storage/unclaimed.js.map +1 -1
- package/dist/supabase/config.d.ts.map +1 -1
- package/dist/supabase/config.js +7 -1
- package/dist/supabase/config.js.map +1 -1
- package/dist/supabase/embedding.d.ts.map +1 -1
- package/dist/supabase/embedding.js +7 -0
- package/dist/supabase/embedding.js.map +1 -1
- package/dist/supabase/sync.d.ts.map +1 -1
- package/dist/supabase/sync.js +42 -18
- package/dist/supabase/sync.js.map +1 -1
- package/dist/tools-logic/bootstrap.d.ts.map +1 -1
- package/dist/tools-logic/bootstrap.js +4 -2
- package/dist/tools-logic/bootstrap.js.map +1 -1
- package/dist/tools-logic/check.d.ts +69 -2
- package/dist/tools-logic/check.d.ts.map +1 -1
- package/dist/tools-logic/check.js +280 -57
- package/dist/tools-logic/check.js.map +1 -1
- package/dist/tools-logic/dream-admission.js +29 -29
- package/dist/tools-logic/recall-backend.d.ts.map +1 -1
- package/dist/tools-logic/recall-backend.js +11 -1
- package/dist/tools-logic/recall-backend.js.map +1 -1
- package/dist/tools-logic/session-end.d.ts +18 -1
- package/dist/tools-logic/session-end.d.ts.map +1 -1
- package/dist/tools-logic/session-end.js +36 -5
- package/dist/tools-logic/session-end.js.map +1 -1
- package/dist/tools-logic/session-start-render.d.ts +35 -0
- package/dist/tools-logic/session-start-render.d.ts.map +1 -0
- package/dist/tools-logic/session-start-render.js +240 -0
- package/dist/tools-logic/session-start-render.js.map +1 -0
- package/dist/tools-logic/session-start.d.ts +21 -0
- package/dist/tools-logic/session-start.d.ts.map +1 -1
- package/dist/tools-logic/session-start.js +279 -225
- package/dist/tools-logic/session-start.js.map +1 -1
- package/dist/tools-logic/smart-recall.d.ts +60 -0
- package/dist/tools-logic/smart-recall.d.ts.map +1 -1
- package/dist/tools-logic/smart-recall.js +221 -31
- package/dist/tools-logic/smart-recall.js.map +1 -1
- package/dist/tools-logic/smart-remember-vector.d.ts +3 -1
- package/dist/tools-logic/smart-remember-vector.d.ts.map +1 -1
- package/dist/tools-logic/smart-remember-vector.js +3 -1
- package/dist/tools-logic/smart-remember-vector.js.map +1 -1
- package/dist/tools-logic/smart-remember.d.ts.map +1 -1
- package/dist/tools-logic/smart-remember.js +8 -5
- package/dist/tools-logic/smart-remember.js.map +1 -1
- package/dist/types.d.ts +98 -2
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +164 -3
- package/dist/types.js.map +1 -1
- package/dist/vector/embedding.d.ts +20 -1
- package/dist/vector/embedding.d.ts.map +1 -1
- package/dist/vector/embedding.js +30 -1
- package/dist/vector/embedding.js.map +1 -1
- package/dist/vector/local-vector-backend.d.ts +4 -1
- package/dist/vector/local-vector-backend.d.ts.map +1 -1
- package/dist/vector/local-vector-backend.js +7 -3
- package/dist/vector/local-vector-backend.js.map +1 -1
- package/package.json +59 -59
|
@@ -18,19 +18,52 @@ import { palaceDir, projectsRootDir } from "./paths.js";
|
|
|
18
18
|
import { ensureDir } from "./fs-utils.js";
|
|
19
19
|
/**
|
|
20
20
|
* Normalize a filesystem path for stable matching:
|
|
21
|
-
* - Resolve symlinks (handles macOS /tmp → /private/tmp)
|
|
21
|
+
* - Resolve symlinks/junctions (handles macOS /tmp → /private/tmp)
|
|
22
|
+
* - Resolve win32 8.3 short-name aliases to the canonical long form and
|
|
23
|
+
* canonicalize on-disk component case: fs.realpathSync.native uses the
|
|
24
|
+
* OS final-path lookup, while the JS fs.realpathSync only follows
|
|
25
|
+
* symlinks and passes `RUNNER~1`-style aliases through VERBATIM. That
|
|
26
|
+
* gap broke the CRITICAL-2 directory-identity gate on GitHub's
|
|
27
|
+
* windows-latest runner (CI run 38230438655, 2026-10-12), whose TEMP is
|
|
28
|
+
* C:\Users\RUNNER~1\…: the allowlist stored one spelling of the project
|
|
29
|
+
* root, `git rev-parse --show-toplevel` produced the other, and the
|
|
30
|
+
* strict compare fell through to raw git identity.
|
|
31
|
+
* - Canonicalize separators to forward slashes (Windows realpath returns
|
|
32
|
+
* backslashes; stored allowlist entries and the "+ '/'" prefix checks
|
|
33
|
+
* below assume one canonical separator)
|
|
22
34
|
* - Strip trailing slash
|
|
23
|
-
* Falls back to the
|
|
35
|
+
* Falls back to the JS realpath, then to the input, if resolution fails
|
|
36
|
+
* (path doesn't exist on disk yet).
|
|
37
|
+
*
|
|
38
|
+
* NOTE: output keeps the canonical ON-DISK case — never lowercase it here
|
|
39
|
+
* (stored entries stay human-readable). COMPARISONS must additionally fold
|
|
40
|
+
* case on win32: use `pathCompareKey`.
|
|
24
41
|
*/
|
|
25
42
|
export function normalizePath(p) {
|
|
26
43
|
let normalized = p;
|
|
27
44
|
try {
|
|
28
|
-
normalized = fs.realpathSync(p);
|
|
45
|
+
normalized = fs.realpathSync.native(p);
|
|
29
46
|
}
|
|
30
47
|
catch {
|
|
31
|
-
|
|
48
|
+
try {
|
|
49
|
+
normalized = fs.realpathSync(p);
|
|
50
|
+
}
|
|
51
|
+
catch {
|
|
52
|
+
// path may not exist on disk yet; use the literal string
|
|
53
|
+
}
|
|
32
54
|
}
|
|
33
|
-
return normalized.replace(/\/+$/, "");
|
|
55
|
+
return normalized.replace(/\\/g, "/").replace(/\/+$/, "");
|
|
56
|
+
}
|
|
57
|
+
/**
|
|
58
|
+
* Comparison key for an already-normalizePath'd path: folded to lower case on
|
|
59
|
+
* win32 (NTFS resolves names case-insensitively, so two spellings of the same
|
|
60
|
+
* directory must compare equal — part of the 2026-10-12 CI fix above) and
|
|
61
|
+
* kept exact elsewhere (POSIX filesystems are case-sensitive). Every equality
|
|
62
|
+
* or prefix check against allowlist entries must go through this key, never
|
|
63
|
+
* raw string comparison.
|
|
64
|
+
*/
|
|
65
|
+
export function pathCompareKey(p) {
|
|
66
|
+
return process.platform === "win32" ? p.toLowerCase() : p;
|
|
34
67
|
}
|
|
35
68
|
function allowlistPath(slug) {
|
|
36
69
|
return path.join(palaceDir(slug), "cwd-allowlist.json");
|
|
@@ -47,23 +80,60 @@ export function readCwdAllowlist(slug) {
|
|
|
47
80
|
const parsed = JSON.parse(raw);
|
|
48
81
|
if (!parsed || !Array.isArray(parsed.paths))
|
|
49
82
|
return { paths: [] };
|
|
50
|
-
return {
|
|
83
|
+
return {
|
|
84
|
+
// Re-normalize at read time: entries written before the realpath.native
|
|
85
|
+
// fix (or on a machine where the dir did not exist yet at write time)
|
|
86
|
+
// may carry an 8.3 short-name or stale-case spelling — healing them
|
|
87
|
+
// here keeps every comparison downstream canonical without a migration.
|
|
88
|
+
paths: parsed.paths
|
|
89
|
+
.filter((s) => typeof s === "string" && path.isAbsolute(s))
|
|
90
|
+
.map((s) => normalizePath(s)),
|
|
91
|
+
};
|
|
51
92
|
}
|
|
52
93
|
catch {
|
|
53
94
|
return { paths: [] };
|
|
54
95
|
}
|
|
55
96
|
}
|
|
97
|
+
/**
|
|
98
|
+
* Registrations a read has queued (deferred-bookkeeping.ts) but not yet written. matchCwd consults them, so a
|
|
99
|
+
* later "auto" call in the same process resolves exactly as if the registration had been written at once:
|
|
100
|
+
* deferring the write must not change what the next read sees. In memory only; cleared when the write lands.
|
|
101
|
+
*/
|
|
102
|
+
const pendingCwds = new Map(); // projects root -> key -> entry
|
|
103
|
+
const MAX_PENDING_CWDS = 256;
|
|
104
|
+
function pendingKey(slug, normalized) {
|
|
105
|
+
return `${slug}|${pathCompareKey(normalized)}`;
|
|
106
|
+
}
|
|
107
|
+
/** Make a queued (not yet written) registration visible to cwd matching in this process. */
|
|
108
|
+
export function notePendingCwd(slug, cwdPath) {
|
|
109
|
+
if (!cwdPath || !path.isAbsolute(cwdPath))
|
|
110
|
+
return;
|
|
111
|
+
const normalized = normalizePath(cwdPath);
|
|
112
|
+
const root = projectsRootDir();
|
|
113
|
+
let m = pendingCwds.get(root);
|
|
114
|
+
if (!m)
|
|
115
|
+
pendingCwds.set(root, (m = new Map()));
|
|
116
|
+
if (m.size >= MAX_PENDING_CWDS)
|
|
117
|
+
m.delete(m.keys().next().value);
|
|
118
|
+
m.set(pendingKey(slug, normalized), { slug, path: normalized });
|
|
119
|
+
}
|
|
120
|
+
function forgetPendingCwd(slug, normalized) {
|
|
121
|
+
pendingCwds.get(projectsRootDir())?.delete(pendingKey(slug, normalized));
|
|
122
|
+
}
|
|
56
123
|
/**
|
|
57
124
|
* Atomically add an absolute path to the project's cwd-allowlist (idempotent).
|
|
58
125
|
* Normalizes the path (trailing slash removed).
|
|
59
126
|
*/
|
|
60
127
|
export function addCwdToAllowlist(slug, cwdPath) {
|
|
61
|
-
if (!cwdPath || !
|
|
128
|
+
if (!cwdPath || !path.isAbsolute(cwdPath))
|
|
62
129
|
return;
|
|
63
130
|
const normalized = normalizePath(cwdPath);
|
|
64
131
|
const current = readCwdAllowlist(slug);
|
|
65
|
-
|
|
132
|
+
// Case-folded dedupe (win32): two spellings of one directory are one entry.
|
|
133
|
+
if (current.paths.some((p) => pathCompareKey(p) === pathCompareKey(normalized))) {
|
|
134
|
+
forgetPendingCwd(slug, normalized); // already persisted: nothing left pending
|
|
66
135
|
return;
|
|
136
|
+
}
|
|
67
137
|
const next = { paths: [...current.paths, normalized].sort() };
|
|
68
138
|
const dir = palaceDir(slug);
|
|
69
139
|
ensureDir(dir);
|
|
@@ -72,6 +142,8 @@ export function addCwdToAllowlist(slug, cwdPath) {
|
|
|
72
142
|
const tmp = `${target}.tmp.${process.pid}.${Date.now()}`;
|
|
73
143
|
fs.writeFileSync(tmp, JSON.stringify(next, null, 2), { encoding: "utf-8", mode: 0o600 });
|
|
74
144
|
fs.renameSync(tmp, target);
|
|
145
|
+
// Only after the entry is on disk: a throw above leaves it pending for the next flush.
|
|
146
|
+
forgetPendingCwd(slug, normalized);
|
|
75
147
|
}
|
|
76
148
|
/**
|
|
77
149
|
* Scan every project's allowlist; return the slug whose allowlist contains a
|
|
@@ -84,29 +156,40 @@ export function addCwdToAllowlist(slug, cwdPath) {
|
|
|
84
156
|
* storage/project.ts, for how the `exact` flag is used).
|
|
85
157
|
*/
|
|
86
158
|
function matchCwd(cwd) {
|
|
87
|
-
if (!cwd || !
|
|
159
|
+
if (!cwd || !path.isAbsolute(cwd))
|
|
88
160
|
return null;
|
|
89
161
|
const normalized = normalizePath(cwd);
|
|
162
|
+
const cwdKey = pathCompareKey(normalized);
|
|
90
163
|
const projectsDir = projectsRootDir();
|
|
91
|
-
|
|
164
|
+
const pending = [...(pendingCwds.get(projectsDir)?.values() ?? [])];
|
|
165
|
+
if (!fs.existsSync(projectsDir) && pending.length === 0)
|
|
92
166
|
return null;
|
|
93
|
-
|
|
94
|
-
|
|
167
|
+
const best = { hit: null };
|
|
168
|
+
const consider = (slug, p) => {
|
|
169
|
+
// Exact match OR cwd lives strictly under p — case-folded on win32.
|
|
170
|
+
const pKey = pathCompareKey(p);
|
|
171
|
+
if (cwdKey === pKey || cwdKey.startsWith(pKey + "/")) {
|
|
172
|
+
if (!best.hit || p.length > best.hit.matchedPath.length)
|
|
173
|
+
best.hit = { slug, matchedPath: p };
|
|
174
|
+
}
|
|
175
|
+
};
|
|
176
|
+
const entries = fs.existsSync(projectsDir) ? fs.readdirSync(projectsDir) : [];
|
|
177
|
+
for (const entry of entries) {
|
|
95
178
|
if (entry.startsWith("_archived_") || entry.startsWith("."))
|
|
96
179
|
continue;
|
|
97
|
-
const
|
|
98
|
-
|
|
99
|
-
// Exact match OR cwd lives strictly under p
|
|
100
|
-
if (normalized === p || normalized.startsWith(p + "/")) {
|
|
101
|
-
if (!bestMatch || p.length > bestMatch.matchedPath.length) {
|
|
102
|
-
bestMatch = { slug: entry, matchedPath: p };
|
|
103
|
-
}
|
|
104
|
-
}
|
|
105
|
-
}
|
|
180
|
+
for (const p of readCwdAllowlist(entry).paths)
|
|
181
|
+
consider(entry, p); // entries arrive re-normalized (realpath'd)
|
|
106
182
|
}
|
|
183
|
+
for (const e of pending)
|
|
184
|
+
consider(e.slug, e.path);
|
|
185
|
+
const bestMatch = best.hit;
|
|
107
186
|
if (!bestMatch)
|
|
108
187
|
return null;
|
|
109
|
-
return {
|
|
188
|
+
return {
|
|
189
|
+
slug: bestMatch.slug,
|
|
190
|
+
exact: pathCompareKey(bestMatch.matchedPath) === cwdKey,
|
|
191
|
+
matchedPath: bestMatch.matchedPath,
|
|
192
|
+
};
|
|
110
193
|
}
|
|
111
194
|
/**
|
|
112
195
|
* Scan every project's allowlist; return the slug whose allowlist contains a
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"cwd-allowlist.js","sourceRoot":"","sources":["../../src/storage/cwd-allowlist.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAM1C
|
|
1
|
+
{"version":3,"file":"cwd-allowlist.js","sourceRoot":"","sources":["../../src/storage/cwd-allowlist.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
export interface BookkeepingOp {
|
|
2
|
+
/** Same key in the same store: the later op replaces the earlier (or, with `repeat`, is applied once more). Omit for a distinct event. */
|
|
3
|
+
key?: string;
|
|
4
|
+
/** Count repeats of this key instead of collapsing them (e.g. N accesses to one room are N increments). */
|
|
5
|
+
repeat?: boolean;
|
|
6
|
+
apply(): void | Promise<void>;
|
|
7
|
+
}
|
|
8
|
+
export interface FlushResult {
|
|
9
|
+
applied: number;
|
|
10
|
+
failed: number;
|
|
11
|
+
}
|
|
12
|
+
/** Run `fn` as a read: bookkeep() calls made inside it (through any await) are queued, not applied. */
|
|
13
|
+
export declare function withDeferredBookkeeping<T>(fn: () => T): T;
|
|
14
|
+
/** True inside withDeferredBookkeeping(): the caller is a read and its bookkeeping is queued. */
|
|
15
|
+
export declare function inReadScope(): boolean;
|
|
16
|
+
/**
|
|
17
|
+
* Record or queue one bookkeeping write. Queued inside withDeferredBookkeeping() (returns undefined);
|
|
18
|
+
* otherwise applied now, returning apply()'s result so a caller can await it exactly as before.
|
|
19
|
+
*/
|
|
20
|
+
export declare function bookkeep(op: BookkeepingOp): void | Promise<void>;
|
|
21
|
+
/** Apply what the current store has queued. Never throws. Called before a write tool runs. */
|
|
22
|
+
export declare function flushBookkeeping(): Promise<FlushResult>;
|
|
23
|
+
/**
|
|
24
|
+
* Apply every store's queue (the periodic timer and shutdown). Never throws. Stores flush concurrently, each
|
|
25
|
+
* bounded per op, so one slow tenant cannot delay the others.
|
|
26
|
+
*/
|
|
27
|
+
export declare function flushAllBookkeeping(): Promise<FlushResult>;
|
|
28
|
+
/** Queue depth and drops, for tests and operators. `pending` is the current store's; `dropped` is process-wide. */
|
|
29
|
+
export declare function bookkeepingStats(): {
|
|
30
|
+
pending: number;
|
|
31
|
+
dropped: number;
|
|
32
|
+
stores: number;
|
|
33
|
+
};
|
|
34
|
+
//# sourceMappingURL=deferred-bookkeeping.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"deferred-bookkeeping.d.ts","sourceRoot":"","sources":["../../src/storage/deferred-bookkeeping.ts"],"names":[],"mappings":"AAyCA,MAAM,WAAW,aAAa;IAC5B,0IAA0I;IAC1I,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,2GAA2G;IAC3G,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,WAAW;IAAG,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AAmChE,uGAAuG;AACvG,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAEzD;AAED,iGAAiG;AACjG,wBAAgB,WAAW,IAAI,OAAO,CAErC;AAYD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,EAAE,EAAE,aAAa,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAiChE;AA2CD,8FAA8F;AAC9F,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,WAAW,CAAC,CAO7D;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,WAAW,CAAC,CAWhE;AAED,mHAAmH;AACnH,wBAAgB,gBAAgB,IAAI;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAIvF"}
|
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Deferred bookkeeping: how a read-only tool call stays read-only.
|
|
3
|
+
*
|
|
4
|
+
* A retrieval tool (session_start, recall) used to record what it surfaced while it answered: correction
|
|
5
|
+
* "retrieved" outcomes, rule hit counts, palace room access counts and salience, the explicit recall feedback,
|
|
6
|
+
* lifecycle telemetry, working-memory notes, derived caches. None of that is the answer; all of it changed the
|
|
7
|
+
* user's store (and some of it later ranking) during a call the client was told only reads.
|
|
8
|
+
*
|
|
9
|
+
* Inside withDeferredBookkeeping() every such write goes through bookkeep(), which does not run it. It queues
|
|
10
|
+
* it, per store root (so per tenant on the hosted server, never mixed), and the queue is applied later:
|
|
11
|
+
* 1. before the next WRITE tool call on that store (flushBookkeeping), so the write sees current counters;
|
|
12
|
+
* 2. by a periodic background flush (flushAllBookkeeping on an unref-ed timer, every 30 s);
|
|
13
|
+
* 3. at graceful shutdown: the stdio server flushes (bounded, about 1.5 s) when stdin ends or closes and on
|
|
14
|
+
* SIGTERM/SIGINT, on every host including hook-owned ones; the HTTP server flushes within its 8 s drain
|
|
15
|
+
* window, and whatever is still queued when that window closes is lost.
|
|
16
|
+
* Best effort by design: a read never waits on the queue, never fails because of it, and a crash (kill -9,
|
|
17
|
+
* power loss) before the next flush loses the queued counters, telemetry and recall ratings (each one
|
|
18
|
+
* re-derivable or advisory), never memory. A write tool waits at most about 1.5 s for the queue
|
|
19
|
+
* (mcp-server lib/bookkeeping.ts); a slower flush keeps running in the background.
|
|
20
|
+
*
|
|
21
|
+
* Outside withDeferredBookkeeping() (the CLI, the SDK, every write tool) bookkeep() just runs the operation
|
|
22
|
+
* now and returns its result, so those paths behave exactly as before.
|
|
23
|
+
*
|
|
24
|
+
* Bounds: MAX_OPS_PER_ROOT queued operations per store, past which the oldest op is dropped; MAX_ROOTS
|
|
25
|
+
* stores, past which the oldest IDLE store's queue is dropped (a store with a flush in flight is never
|
|
26
|
+
* evicted; if none is idle the new op is dropped). Every drop is counted (bookkeepingStats().dropped).
|
|
27
|
+
* Each op is also bounded in time (DEFAULT_OP_TIMEOUT_MS): one that does not settle in time is counted failed,
|
|
28
|
+
* logged once, and the chain moves on, so a hung op can never wedge the store's flush chain. A timed-out op
|
|
29
|
+
* cannot be cancelled and may still land later, so "failed" means "not confirmed"; every queued op must be
|
|
30
|
+
* idempotent or advisory.
|
|
31
|
+
*
|
|
32
|
+
* Counters are ADVISORY. A write tool waits at most 1.5 s for the queue; if a flush is still applying ops after
|
|
33
|
+
* that, the write runs concurrently with it, and a read-modify-write counter op on a file the write also edits
|
|
34
|
+
* can lose one update (the counter undercounts). Nothing ranks on an exact count, so no lock is taken.
|
|
35
|
+
*
|
|
36
|
+
* A repeated operation under one key collapses (the latest replaces the earlier one), or with `repeat` counts
|
|
37
|
+
* up to REPEAT_CAP applications.
|
|
38
|
+
*/
|
|
39
|
+
import { AsyncLocalStorage } from "node:async_hooks";
|
|
40
|
+
import { getRoot, getTenantContext, withRoot, withTenant } from "../types.js";
|
|
41
|
+
const MAX_OPS_PER_ROOT = 256;
|
|
42
|
+
const MAX_ROOTS = 256;
|
|
43
|
+
const REPEAT_CAP = 16;
|
|
44
|
+
const FLUSH_INTERVAL_MS = 30_000;
|
|
45
|
+
/** Longest one queued op may run before the flush gives up on it and moves on (AGENT_RECALL_BOOKKEEP_OP_TIMEOUT_MS overrides, read per op). */
|
|
46
|
+
const DEFAULT_OP_TIMEOUT_MS = 3000;
|
|
47
|
+
function opTimeoutMs() {
|
|
48
|
+
const n = Number(process.env.AGENT_RECALL_BOOKKEEP_OP_TIMEOUT_MS);
|
|
49
|
+
return Number.isFinite(n) && n > 0 ? n : DEFAULT_OP_TIMEOUT_MS;
|
|
50
|
+
}
|
|
51
|
+
const deferring = new AsyncLocalStorage();
|
|
52
|
+
const queues = new Map();
|
|
53
|
+
let seq = 0;
|
|
54
|
+
let dropped = 0;
|
|
55
|
+
let timer;
|
|
56
|
+
/** Run `fn` as a read: bookkeep() calls made inside it (through any await) are queued, not applied. */
|
|
57
|
+
export function withDeferredBookkeeping(fn) {
|
|
58
|
+
return deferring.run(true, fn);
|
|
59
|
+
}
|
|
60
|
+
/** True inside withDeferredBookkeeping(): the caller is a read and its bookkeeping is queued. */
|
|
61
|
+
export function inReadScope() {
|
|
62
|
+
return deferring.getStore() === true;
|
|
63
|
+
}
|
|
64
|
+
function currentScope() {
|
|
65
|
+
const tenant = getTenantContext();
|
|
66
|
+
return tenant ? { tenant, root: tenant.root } : { root: getRoot() };
|
|
67
|
+
}
|
|
68
|
+
function runInScope(scope, fn) {
|
|
69
|
+
// exit(): an apply running under a flush that started inside a read must itself write, not re-queue.
|
|
70
|
+
return deferring.exit(() => (scope.tenant ? withTenant(scope.tenant, fn) : withRoot(scope.root, fn)));
|
|
71
|
+
}
|
|
72
|
+
/**
|
|
73
|
+
* Record or queue one bookkeeping write. Queued inside withDeferredBookkeeping() (returns undefined);
|
|
74
|
+
* otherwise applied now, returning apply()'s result so a caller can await it exactly as before.
|
|
75
|
+
*/
|
|
76
|
+
export function bookkeep(op) {
|
|
77
|
+
if (!deferring.getStore())
|
|
78
|
+
return op.apply();
|
|
79
|
+
const scope = currentScope();
|
|
80
|
+
let q = queues.get(scope.root);
|
|
81
|
+
if (!q) {
|
|
82
|
+
if (queues.size >= MAX_ROOTS) {
|
|
83
|
+
// Evict the oldest IDLE queue: deleting one with a flush in flight would let a fresh queue for that root
|
|
84
|
+
// interleave with the running flush.
|
|
85
|
+
let victim;
|
|
86
|
+
for (const [root, cand] of queues)
|
|
87
|
+
if (!cand.busy) {
|
|
88
|
+
victim = root;
|
|
89
|
+
break;
|
|
90
|
+
}
|
|
91
|
+
if (victim === undefined) {
|
|
92
|
+
dropped++;
|
|
93
|
+
return;
|
|
94
|
+
}
|
|
95
|
+
dropped += queues.get(victim).entries.size;
|
|
96
|
+
queues.delete(victim);
|
|
97
|
+
}
|
|
98
|
+
q = { scope, entries: new Map(), flushing: Promise.resolve(), busy: 0 };
|
|
99
|
+
queues.set(scope.root, q);
|
|
100
|
+
}
|
|
101
|
+
const key = op.key ?? `#${seq++}`;
|
|
102
|
+
const prev = q.entries.get(key);
|
|
103
|
+
if (prev) {
|
|
104
|
+
prev.op = op;
|
|
105
|
+
prev.times = op.repeat ? Math.min(prev.times + 1, REPEAT_CAP) : 1;
|
|
106
|
+
}
|
|
107
|
+
else {
|
|
108
|
+
if (q.entries.size >= MAX_OPS_PER_ROOT) {
|
|
109
|
+
q.entries.delete(q.entries.keys().next().value);
|
|
110
|
+
dropped++;
|
|
111
|
+
}
|
|
112
|
+
q.entries.set(key, { op, times: 1 });
|
|
113
|
+
}
|
|
114
|
+
if (!timer) {
|
|
115
|
+
timer = setInterval(() => { void flushAllBookkeeping(); }, FLUSH_INTERVAL_MS);
|
|
116
|
+
timer.unref();
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
/** Apply one op, rejecting after the op timeout. The op cannot be cancelled; its late result is ignored. */
|
|
120
|
+
function applyBounded(scope, op) {
|
|
121
|
+
const ms = opTimeoutMs();
|
|
122
|
+
return new Promise((resolve, reject) => {
|
|
123
|
+
const timer = setTimeout(() => reject(new Error(`bookkeeping op timed out after ${ms} ms`)), ms);
|
|
124
|
+
timer.unref();
|
|
125
|
+
// Promise.resolve().then also turns a synchronous throw into a rejection. Settling after the timeout is a no-op.
|
|
126
|
+
Promise.resolve()
|
|
127
|
+
.then(() => runInScope(scope, () => op.apply()))
|
|
128
|
+
.then(() => { clearTimeout(timer); resolve(); }, (err) => { clearTimeout(timer); reject(err); });
|
|
129
|
+
});
|
|
130
|
+
}
|
|
131
|
+
async function flushQueue(q) {
|
|
132
|
+
const result = { applied: 0, failed: 0 };
|
|
133
|
+
const run = async () => {
|
|
134
|
+
const batch = [...q.entries.values()];
|
|
135
|
+
q.entries.clear();
|
|
136
|
+
for (const { op, times } of batch) {
|
|
137
|
+
for (let i = 0; i < times; i++) {
|
|
138
|
+
try {
|
|
139
|
+
await applyBounded(q.scope, op);
|
|
140
|
+
result.applied++;
|
|
141
|
+
}
|
|
142
|
+
catch (err) {
|
|
143
|
+
result.failed++;
|
|
144
|
+
console.error(`[agent-recall] bookkeeping write skipped: ${err instanceof Error ? err.message : String(err)}`);
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
}
|
|
148
|
+
};
|
|
149
|
+
q.busy++;
|
|
150
|
+
const next = q.flushing.then(run, run);
|
|
151
|
+
q.flushing = next;
|
|
152
|
+
try {
|
|
153
|
+
await next;
|
|
154
|
+
}
|
|
155
|
+
finally {
|
|
156
|
+
q.busy--;
|
|
157
|
+
}
|
|
158
|
+
return result;
|
|
159
|
+
}
|
|
160
|
+
/** Apply what the current store has queued. Never throws. Called before a write tool runs. */
|
|
161
|
+
export async function flushBookkeeping() {
|
|
162
|
+
try {
|
|
163
|
+
const q = queues.get(currentScope().root);
|
|
164
|
+
return q ? await flushQueue(q) : { applied: 0, failed: 0 };
|
|
165
|
+
}
|
|
166
|
+
catch {
|
|
167
|
+
return { applied: 0, failed: 0 };
|
|
168
|
+
}
|
|
169
|
+
}
|
|
170
|
+
/**
|
|
171
|
+
* Apply every store's queue (the periodic timer and shutdown). Never throws. Stores flush concurrently, each
|
|
172
|
+
* bounded per op, so one slow tenant cannot delay the others.
|
|
173
|
+
*/
|
|
174
|
+
export async function flushAllBookkeeping() {
|
|
175
|
+
const total = { applied: 0, failed: 0 };
|
|
176
|
+
const settled = await Promise.allSettled([...queues.values()].map((q) => flushQueue(q)));
|
|
177
|
+
for (const s of settled) {
|
|
178
|
+
if (s.status === "fulfilled") {
|
|
179
|
+
total.applied += s.value.applied;
|
|
180
|
+
total.failed += s.value.failed;
|
|
181
|
+
}
|
|
182
|
+
else
|
|
183
|
+
total.failed++;
|
|
184
|
+
}
|
|
185
|
+
// Only idle queues: one with a flush in flight (or ops added meanwhile) must stay, or a new queue for the
|
|
186
|
+
// same root could interleave with the running flush.
|
|
187
|
+
for (const [root, q] of queues)
|
|
188
|
+
if (q.entries.size === 0 && !q.busy)
|
|
189
|
+
queues.delete(root);
|
|
190
|
+
return total;
|
|
191
|
+
}
|
|
192
|
+
/** Queue depth and drops, for tests and operators. `pending` is the current store's; `dropped` is process-wide. */
|
|
193
|
+
export function bookkeepingStats() {
|
|
194
|
+
let pending = 0;
|
|
195
|
+
try {
|
|
196
|
+
pending = queues.get(currentScope().root)?.entries.size ?? 0;
|
|
197
|
+
}
|
|
198
|
+
catch { /* outside a tenant scope in strict mode */ }
|
|
199
|
+
return { pending, dropped, stores: queues.size };
|
|
200
|
+
}
|
|
201
|
+
//# sourceMappingURL=deferred-bookkeeping.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"deferred-bookkeeping.js","sourceRoot":"","sources":["../../src/storage/deferred-bookkeeping.ts"],"names":[],"mappings":"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"}
|
|
@@ -88,18 +88,36 @@ export declare class LockContentionError extends Error {
|
|
|
88
88
|
readonly heldForMs: number | null;
|
|
89
89
|
constructor(lockName: string, holderPid: number | null, heldForMs: number | null);
|
|
90
90
|
}
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
91
|
+
export interface AcquireLockOptions {
|
|
92
|
+
/**
|
|
93
|
+
* Wait as long as the holder PID probes ALIVE (and from this boot) instead
|
|
94
|
+
* of applying the 5s no-progress ("wedged holder") deadline. Dead holders
|
|
95
|
+
* are still reclaimed promptly; the maxTotalWaitMs hard cap still applies.
|
|
96
|
+
*
|
|
97
|
+
* CI windows-latest regression (2026-10-12): on a starved 2-vCPU runner a
|
|
98
|
+
* perfectly healthy holder can sit DESCHEDULED past the no-progress
|
|
99
|
+
* deadline, so recordOutcome's materialized-counter pass skipped 190/480
|
|
100
|
+
* updates. For callers whose critical section only rewrites state that is
|
|
101
|
+
* re-derivable from an authoritative source (the _outcomes.jsonl ledger),
|
|
102
|
+
* losing the pass to a starvation misdiagnosis is strictly worse than
|
|
103
|
+
* waiting out a live holder — opt in here. Hot paths that must stay
|
|
104
|
+
* responsive to a genuinely wedged (alive-but-stuck) holder keep the
|
|
105
|
+
* default.
|
|
106
|
+
*/
|
|
107
|
+
waitForLiveHolder?: boolean;
|
|
108
|
+
/**
|
|
109
|
+
* Hard cap on the total wait (default MAX_TOTAL_WAIT_MS = 60s). Exists for
|
|
110
|
+
* tests and callers that need a tighter liveness bound; the default is the
|
|
111
|
+
* documented absolute worst case.
|
|
112
|
+
*/
|
|
113
|
+
maxTotalWaitMs?: number;
|
|
114
|
+
}
|
|
115
|
+
export declare function acquireLock(name: string, opts?: AcquireLockOptions): Promise<() => void>;
|
|
98
116
|
/**
|
|
99
117
|
* Execute a function while holding a lock.
|
|
100
118
|
* Lock is always released, even on error. Prefer a synchronous fn (bounded
|
|
101
119
|
* hold); an async fn is allowed only for the documented awareness nesting —
|
|
102
120
|
* see the header's lock-ordering section.
|
|
103
121
|
*/
|
|
104
|
-
export declare function withLock<T>(name: string, fn: () => T | Promise<T
|
|
122
|
+
export declare function withLock<T>(name: string, fn: () => T | Promise<T>, opts?: AcquireLockOptions): Promise<T>;
|
|
105
123
|
//# sourceMappingURL=filelock.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"filelock.d.ts","sourceRoot":"","sources":["../../src/storage/filelock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AASH;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,QAAQ,CAAC;
|
|
1
|
+
{"version":3,"file":"filelock.d.ts","sourceRoot":"","sources":["../../src/storage/filelock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AASH;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,QAAQ,CAAC;AAiCnC;;;;kCAIkC;AAClC,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;gBAEtB,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;CAoBjF;AA4TD,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;;;;;;;OAcG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,kBAAuB,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CAsFlG;AAED;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,GAAE,kBAAuB,GAAG,OAAO,CAAC,CAAC,CAAC,CAOnH"}
|