@sema-agent/core 5.48.0 → 5.50.0

package/dist/stores/file/strategy-store.js

@@ -0,0 +1,340 @@
+import { accessSync, constants as FS, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+import { atomicWriteFile } from "./fs-atomic.js";
+import { createSafeNotifier, observeThenableRejection } from "../../core/safe-notify.js";
+import { MAX_STRATEGY_INJECTION_TOTAL_BYTES, MAX_STRATEGY_TEXT_BYTES, compileStrategyQuery, resolveCapacityCap, resolveFindLimit, scoreStoredStrategy, storedStrategyShapeIssue, strategyDedupKey, validateStrategyForWrite, } from "../../core/strategy-store.js";
+function configRefusal(message, code) {
+    const e = new Error(message);
+    e.code = code;
+    return e;
+}
+const SCOPE_SLUG_MAX = 40;
+const READ_FILE_CAP_FACTOR = 4;
+const STALE_TEMP_MS = 60 * 60 * 1000;
+const MAX_ENTRY_FILE_BYTES = 65536;
+const FILE_RE = /^([A-Za-z0-9_-]{1,64})\.json$/;
+export class FileStrategyStore {
+    root;
+    maxPerScope;
+    onIncident;
+    warnedOps = new Set();
+    sinkNotifier = createSafeNotifier();
+    sweptTemps = new Set();
+    constructor(opts) {
+        this.maxPerScope = resolveCapacityCap("maxPerScope", opts.maxPerScope ?? 100);
+        this.onIncident = opts.onIncident;
+        const root = opts.root;
+        if (typeof root !== "string" || root.length === 0) {
+            throw configRefusal("FileStrategyStore: root must be a non-empty path", "config.strategy_root_invalid");
+        }
+        try {
+            mkdirSync(root, { recursive: true, mode: 0o700 });
+        }
+        catch (err) {
+            throw configRefusal(`FileStrategyStore: cannot create root ${root}: ${String(err.message ?? err)}`, "config.strategy_root_invalid");
+        }
+        let st;
+        try {
+            st = statSync(root);
+        }
+        catch (err) {
+            throw configRefusal(`FileStrategyStore: cannot stat root ${root}: ${String(err.message ?? err)}`, "config.strategy_root_invalid");
+        }
+        if (!st.isDirectory()) {
+            throw configRefusal(`FileStrategyStore: root ${root} exists and is not a directory`, "config.strategy_root_invalid");
+        }
+        try {
+            accessSync(root, FS.W_OK);
+        }
+        catch {
+            throw configRefusal(`FileStrategyStore: root ${root} is not writable`, "config.strategy_root_invalid");
+        }
+        this.root = root;
+    }
+    scopeDirName(scope) {
+        const slug = scope
+            .toLowerCase()
+            .replace(/[^a-z0-9-]+/g, "-")
+            .replace(/^-+|-+$/g, "")
+            .slice(0, SCOPE_SLUG_MAX);
+        const h = createHash("sha256").update(scope, "utf8").digest("hex").slice(0, 24);
+        return `${slug || "s"}-${h}`;
+    }
+    scopeDirPath(scope) {
+        return join(this.root, this.scopeDirName(scope));
+    }
+    assertScopeDirSafe(dir) {
+        let st;
+        try {
+            st = lstatSync(dir);
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return;
+            throw err;
+        }
+        if (st.isSymbolicLink() || !st.isDirectory()) {
+            const e = new Error(`FileStrategyStore: scope directory ${dir} is not a plain directory (symlink or non-dir refused)`);
+            e.code = "strategy.scope_dir_invalid";
+            throw e;
+        }
+    }
+    incident(i) {
+        const sink = this.onIncident;
+        if (sink !== undefined) {
+            const site = `FileStrategyStore.onIncident.${i.op}`;
+            this.sinkNotifier.notify(() => observeThenableRejection(sink(i), this.sinkNotifier, site), site);
+            return;
+        }
+        if (!this.warnedOps.has(i.op)) {
+            this.warnedOps.add(i.op);
+            console.warn(`FileStrategyStore ${i.op} incident: ${i.error}${i.path !== undefined ? ` (${i.path})` : ""}`);
+        }
+    }
+    sweepStaleTemps(dir) {
+        if (this.sweptTemps.has(dir))
+            return;
+        this.sweptTemps.add(dir);
+        let names;
+        try {
+            names = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        const cutoff = Date.now() - STALE_TEMP_MS;
+        for (const name of names) {
+            if (!name.endsWith(".tmp"))
+                continue;
+            const p = join(dir, name);
+            try {
+                if (statSync(p).mtimeMs < cutoff)
+                    unlinkSync(p);
+            }
+            catch {
+            }
+        }
+    }
+    loadScope(scope, dir, readCap) {
+        let names;
+        try {
+            names = readdirSync(dir);
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return [];
+            throw err;
+        }
+        let candidates = names.filter((n) => FILE_RE.test(n)).sort();
+        if (Number.isFinite(readCap) && candidates.length > readCap) {
+            this.incident({
+                op: "find",
+                error: `scope directory holds ${candidates.length} entry files, over the ${readCap} read cap — parsing the first ${readCap} only (an external writer likely inflated this directory)`,
+                path: dir,
+            });
+            candidates = candidates.slice(0, readCap);
+        }
+        const out = [];
+        for (const name of candidates) {
+            const p = join(dir, name);
+            let fst;
+            try {
+                fst = lstatSync(p);
+            }
+            catch (err) {
+                if (err.code === "ENOENT")
+                    continue;
+                this.incident({ op: "find", error: `unstat-able entry skipped: ${String(err.message ?? err)}`, path: p });
+                continue;
+            }
+            if (!fst.isFile()) {
+                this.incident({ op: "find", error: "non-regular entry skipped (symlink or special file refused)", path: p });
+                continue;
+            }
+            if (fst.size > MAX_ENTRY_FILE_BYTES) {
+                this.quarantine(p, `entry file is ${fst.size} bytes, over the ${MAX_ENTRY_FILE_BYTES} read bound`);
+                continue;
+            }
+            let raw;
+            try {
+                raw = readFileSync(p, "utf8");
+            }
+            catch (err) {
+                if (err.code === "ENOENT")
+                    continue;
+                this.incident({ op: "find", error: `unreadable entry skipped: ${String(err.message ?? err)}`, path: p });
+                continue;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                this.quarantine(p, "unparseable JSON");
+                continue;
+            }
+            if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+                this.quarantine(p, "top-level JSON value is not an object");
+                continue;
+            }
+            const rec = parsed;
+            if (rec.v !== 1) {
+                this.incident({ op: "parse", error: `unknown schema version ${String(rec.v)} — entry skipped, file left in place`, path: p });
+                continue;
+            }
+            const { v: _v, ...candidate } = rec;
+            const issue = storedStrategyShapeIssue(candidate);
+            if (issue !== null) {
+                this.quarantine(p, issue);
+                continue;
+            }
+            const entry = candidate;
+            const fileId = FILE_RE.exec(name)[1];
+            if (entry.scope !== scope || entry.id !== fileId) {
+                this.incident({
+                    op: "find",
+                    error: `entry skipped: scope/id mismatch (file claims scope ${JSON.stringify(entry.scope)}, id ${JSON.stringify(entry.id)})`,
+                    id: fileId,
+                    path: p,
+                });
+                continue;
+            }
+            out.push({ entry, path: p });
+        }
+        const byKey = new Map();
+        for (const le of out) {
+            const key = strategyDedupKey(le.entry);
+            const prev = byKey.get(key);
+            if (prev === undefined || scoreStoredStrategy(le.entry) > scoreStoredStrategy(prev.entry))
+                byKey.set(key, le);
+        }
+        return [...byKey.values()];
+    }
+    quarantine(p, reason) {
+        try {
+            renameSync(p, `${p}.bad`);
+            this.incident({ op: "parse", error: `corrupt entry quarantined (${reason})`, path: p });
+        }
+        catch (err) {
+            this.incident({ op: "parse", error: `corrupt entry skipped (${reason}); quarantine rename failed: ${String(err.message ?? err)}`, path: p });
+        }
+    }
+    writeEntry(dir, path, entry) {
+        const record = {
+            v: 1,
+            id: entry.id,
+            problem: entry.problem,
+            strategy: entry.strategy,
+            confidence: entry.confidence,
+            scope: entry.scope,
+            ts: entry.ts,
+            ...(entry.teacherModel !== undefined ? { teacherModel: entry.teacherModel } : {}),
+            ...(entry.signature !== undefined ? { signature: entry.signature } : {}),
+            ...(entry.origin !== undefined ? { origin: entry.origin } : {}),
+        };
+        const bytes = JSON.stringify(record);
+        if (Buffer.byteLength(bytes, "utf8") > MAX_ENTRY_FILE_BYTES) {
+            const e = new Error(`FileStrategyStore: entry serializes over the ${MAX_ENTRY_FILE_BYTES}-byte read bound (JSON escaping expanded it past the field caps) — refusing a write the read side would quarantine`);
+            e.code = "strategy.entry_invalid";
+            throw e;
+        }
+        atomicWriteFile(dir, path, bytes);
+    }
+    save(s) {
+        validateStrategyForWrite(s);
+        const dir = this.scopeDirPath(s.scope);
+        this.assertScopeDirSafe(dir);
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        this.sweepStaleTemps(dir);
+        const existing = this.loadScope(s.scope, dir, this.retrievalReadCap());
+        const key = strategyDedupKey(s);
+        const dup = existing.find((le) => strategyDedupKey(le.entry) === key);
+        let all;
+        if (dup !== undefined) {
+            const refreshed = {
+                ...dup.entry,
+                ...(s.confidence >= dup.entry.confidence ? { confidence: s.confidence, ts: s.ts } : {}),
+                ...(s.teacherModel !== undefined ? { teacherModel: s.teacherModel } : {}),
+            };
+            this.writeEntry(dir, dup.path, refreshed);
+            dup.entry = refreshed;
+            all = existing;
+        }
+        else {
+            const p = join(dir, `${s.id}.json`);
+            const byId = existing.find((le) => le.entry.id === s.id);
+            this.writeEntry(dir, p, s);
+            if (byId !== undefined) {
+                byId.entry = s;
+                all = existing;
+            }
+            else {
+                all = [...existing, { entry: s, path: p }];
+            }
+        }
+        if (all.length > this.maxPerScope) {
+            this.evict(all, this.maxPerScope);
+        }
+    }
+    evict(all, keep) {
+        const sorted = [...all].sort((a, b) => scoreStoredStrategy(b.entry) - scoreStoredStrategy(a.entry));
+        for (const le of sorted.slice(keep)) {
+            try {
+                unlinkSync(le.path);
+            }
+            catch (err) {
+                if (err.code === "ENOENT")
+                    continue;
+                this.incident({ op: "evict", error: String(err.message ?? err), id: le.entry.id, path: le.path });
+            }
+        }
+    }
+    find(scope, query, limit) {
+        const cap = resolveFindLimit(limit);
+        const dir = this.scopeDirPath(scope);
+        this.assertScopeDirSafe(dir);
+        const matches = compileStrategyQuery(query);
+        if (matches === null)
+            return [];
+        const ranked = this.loadScope(scope, dir, this.retrievalReadCap())
+            .map((le) => le.entry)
+            .filter((e) => matches(e.problem))
+            .sort((a, b) => scoreStoredStrategy(b) - scoreStoredStrategy(a))
+            .slice(0, cap);
+        let bytes = 0;
+        for (let i = 0; i < ranked.length; i++) {
+            bytes += Buffer.byteLength(ranked[i].strategy, "utf8");
+            if (bytes > MAX_STRATEGY_INJECTION_TOTAL_BYTES) {
+                this.incident({
+                    op: "find",
+                    error: `result truncated at ${i} of ${ranked.length} entries — combined strategy text exceeded ${MAX_STRATEGY_INJECTION_TOTAL_BYTES} bytes (per-entry cap ${MAX_STRATEGY_TEXT_BYTES})`,
+                });
+                return ranked.slice(0, i);
+            }
+        }
+        return ranked;
+    }
+    retrievalReadCap() {
+        return this.maxPerScope * READ_FILE_CAP_FACTOR;
+    }
+    prune(scope, maxSize) {
+        const n = resolveCapacityCap("maxSize", maxSize);
+        const dir = this.scopeDirPath(scope);
+        this.assertScopeDirSafe(dir);
+        const all = this.loadScope(scope, dir, Number.POSITIVE_INFINITY);
+        if (all.length > n)
+            this.evict(all, n);
+    }
+    scopeUsage(scope) {
+        const dir = this.scopeDirPath(scope);
+        this.assertScopeDirSafe(dir);
+        return { used: this.loadScope(scope, dir, Number.POSITIVE_INFINITY).length, capacity: this.maxPerScope };
+    }
+    hasStrategy(scope, entry) {
+        const dir = this.scopeDirPath(scope);
+        this.assertScopeDirSafe(dir);
+        const key = strategyDedupKey(entry);
+        return this.loadScope(scope, dir, this.retrievalReadCap()).some((le) => strategyDedupKey(le.entry) === key);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "5.48.0",
+  "version": "5.50.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",

package/test/export-surface.snapshot.json

@@ -1,6 +1,6 @@
 {
   "_comment": "design/87 L3 — frozen public export surface of src/index.ts (name -> kind). DO NOT edit by hand to silence a red test. A removed/changed entry = a SemVer-BREAKING change; bump MAJOR and update this fixture in the SAME commit (design/87 §4.2 / §5.2). Regenerate via REGEN in test/export-surface.test.ts.",
-  "count": 1639,
+  "count": 1646,
   "exports": {
     "A2ATaskState": "type",
     "A2ATaskStateReversal": "type",
@@ -317,6 +317,8 @@
     "FileStorageBackend": "class",
     "FileStorageBackendOptions": "interface",
     "FileStorageCorruptReadInfo": "interface",
+    "FileStrategyStore": "class",
+    "FileStrategyStoreOptions": "interface",
     "FileToolResultStore": "class",
     "FileUsageWindowStore": "class",
     "FileWorkflowJournalStore": "class",
@@ -866,6 +868,8 @@
     "SecretEnvFindingKind": "type",
     "SecretRef": "interface",
     "SectionRenderInputs": "interface",
+    "SeedStrategiesReport": "interface",
+    "SeedStrategyEntry": "type",
     "SelectiveRecallOptions": "interface",
     "SelectiveRecallResult": "type",
     "SemaTaskHandle": "interface",
@@ -929,7 +933,9 @@
     "StoredSession": "class",
     "StoredSessionRules": "interface",
     "StoredStrategy": "interface",
+    "StrategyOrigin": "type",
     "StrategyStore": "interface",
+    "StrategyStoreIncident": "interface",
     "StreamFn": "type",
     "StreamingImportValidator": "class",
     "StrictControlPlaneLedger": "type",
@@ -1571,6 +1577,7 @@
     "screenInboundEntries": "function",
     "screenRuleSyncState": "function",
     "scrubSecretEnv": "function",
+    "seedStrategies": "function",
     "selectModel": "function",
     "selectModelOrThrow": "function",
     "selfOrchestrationFailClosedReason": "function",