Files
waggle-os/packages/agent/src/memory-write-lint.ts
Oleg Maslov 0c3e2ead3b
Some checks failed
Installer Smoke / installer-smoke (push) Has been cancelled
moving
2026-09-02 10:10:29 +02:00

138 lines
6.2 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/**
* Memory-Write Lint — "fix the source, not the symptom".
*
* A deterministic (regex/heuristic, NO LLM) classifier that flags memory writes
* which merely record a capability failure symptom — e.g. "the Slack connector
* failed to authenticate" or "the web search tool keeps timing out". Memorizing
* such a symptom is the wrong response: the agent should fix or flag the
* capability (acquire_capability) instead of durably remembering that it is
* broken, which rots the moment the capability is repaired.
*
* Design constraints:
* - Conservative by default. Memory loss is worse than one extra nag, so any
* ambiguity resolves to `allow`.
* - User preferences / opinions about tools ("user prefers Slack over email")
* MUST pass — they reference a capability but carry no failure signal.
* - Detection is sentence-scoped: a capability noun and a failure verb must
* co-occur in the SAME sentence, so an unrelated "cannot" three sentences away
* from an unrelated "tool" does not trip the classifier.
*/
export type MemoryLintVerdict = 'allow' | 'capability_symptom';
export interface MemoryLintResult {
verdict: MemoryLintVerdict;
/** Best-effort name of the capability the symptom is about (feeds recordCapabilityGap). */
capability?: string;
/** Human-readable reason (the offending sentence), for the cancel message / log. */
reason?: string;
}
// A generic reference to an acquirable capability. Named services (Slack, Jira)
// are intentionally NOT listed — relying on generic nouns keeps the classifier
// conservative and avoids false positives like "the Slack meeting failed".
const CAPABILITY_NOUN =
/\b(tools?|skills?|connectors?|capabilit(?:y|ies)|integrations?|plugins?|mcp\s+servers?|apis?|connection)\b/i;
// Failure verbs / phrases. A bare "cannot" / "can't" is NOT a failure signal on
// its own — it also fronts preferences ("cannot stand Sketch") and dependence
// ("can't work without Jira"), neither of which is a broken capability. It fires
// only when directly followed by a capability verb (connect/authenticate/…), so
// "cannot launch" trips but "cannot stand" / "can't work without" do not.
const FAILURE_VERB = new RegExp(
[
/\bfail(?:ed|ing|s)?\b/.source,
/\b(?:does\s*n['’]?t|do\s*n['’]?t|did\s*n['’]?t|does\s+not|do\s+not|did\s+not)\s+work\b/.source,
/\b(?:is|are|was|were|are\s*n['’]?t|is\s*n['’]?t|not)\s+working\b/.source,
/\b(?:un)?available\b/.source,
/\bnot\s+available\b/.source,
/\bno\s+longer\s+available\b/.source,
/\berrors?\s+(?:out|when)\b/.source,
/\b(?:return|throw|give|gave|got|threw|returns|throws|gives|returning|throwing)\s+(?:an?\s+)?errors?\b/.source,
/\b(?:ca\s*n['’]?t|can\s*not|cannot|could\s*n['’]?t|could\s*not|unable\s+to)\s+(?:connect|authenticate|access|load|run|execute|reach|find|install|launch|open|start|respond|refresh|sync|fetch|retrieve|send|log\s*in|sign\s*in|complete|initiali[sz]e|render|save|read|write|be\s+reached|be\s+found)\b/.source,
/\bbroken\b/.source,
/\b(?:keeps?\s+)?(?:tim(?:e|ing)s?\s+out|timed\s+out|timing\s+out)\b/.source,
// Planned downtime ("down for maintenance") is a status fact, not a broken
// capability — the lookahead lets it pass while "is down" still fires.
/\bis\s+down\b(?!\s+for\s+maintenance)/.source,
/\bnot\s+responding\b/.source,
].join('|'),
'i',
);
// A connection failure implies an integration/capability on its own, even
// without a generic capability noun in the sentence.
const CONNECTION_FAILURE =
/\b(?:failed\s+to\s+connect|ca\s*n['’]?t\s+connect|cannot\s+connect|could\s*n['’]?t\s+connect|unable\s+to\s+connect|wo\s*n['’]?t\s+connect|not\s+connecting)\b/i;
const STOPWORDS = new Set([
'the', 'a', 'an', 'this', 'that', 'these', 'those', 'my', 'our', 'your',
'its', 'their', 'his', 'her', 'to', 'of', 'and', 'or', 'with', 'using',
]);
/**
* Extract a best-effort capability name from an offending sentence: up to two
* meaningful words preceding the capability noun (e.g. "web search tool"), or
* the target of a "connect to X" phrase, falling back to the generic noun.
*/
function extractCapability(sentence: string): string {
const nounMatch = sentence.match(
/((?:[\w.-]+\s+){0,2})(tools?|skills?|connectors?|capabilit(?:y|ies)|integrations?|plugins?|mcp\s+servers?|apis?|connection)\b/i,
);
if (nounMatch) {
const prefixWords = nounMatch[1]
.trim()
.split(/\s+/)
.filter((w) => w.length > 0 && !STOPWORDS.has(w.toLowerCase()));
const noun = nounMatch[2].trim();
const phrase = [...prefixWords, noun].join(' ').trim();
return phrase || noun;
}
const connectMatch = sentence.match(/connect(?:ing)?\s+to\s+(?:the\s+)?([\w-]+)/i);
if (connectMatch) return connectMatch[1];
return 'capability';
}
function classifySentence(sentence: string): MemoryLintResult | null {
const hasConnectionFailure = CONNECTION_FAILURE.test(sentence);
const hasCapabilityNoun = CAPABILITY_NOUN.test(sentence);
const hasFailureVerb = FAILURE_VERB.test(sentence);
if (hasConnectionFailure || (hasCapabilityNoun && hasFailureVerb)) {
return {
verdict: 'capability_symptom',
capability: extractCapability(sentence),
reason: sentence.trim(),
};
}
return null;
}
/**
* Lint a proposed memory write. Returns `capability_symptom` only when a single
* sentence pairs a capability reference with a failure signal; everything else
* (including tool preferences and unrelated capability mentions) is `allow`.
*
* @param content The memory content the agent wants to save.
* @param _type The memory type, if any. Unused today (the save_memory hook
* does not carry a semantic type) but accepted per the contract.
*/
export function lintMemoryWrite(content: string, _type?: string): MemoryLintResult {
if (!content || typeof content !== 'string' || content.trim().length === 0) {
return { verdict: 'allow' };
}
// Sentence-scope the check so a capability noun and a failure verb in
// unrelated sentences do not combine into a false positive.
const sentences = content.split(/(?<=[.!?\n])|[\n]/);
for (const sentence of sentences) {
if (!sentence.trim()) continue;
const result = classifySentence(sentence);
if (result) return result;
}
return { verdict: 'allow' };
}