Files
waggle-os/packages/agent/src/tools.ts
shumeiko.it 784ca770b1 refactor(memory): run agent recall, memory tools and the server on the memory contract (P1.5)
- Orchestrator, memory tools, context loader and pattern write-back use a
  MemoryStore and a workspace scope instead of MindDB layers; the knowledge
  graph tools, cognify, memory linker and feedback handler are gone (graph
  hidden in v1, ADR-0002).
- The server opens one mem0 store in <dataDir>/memory/, embedded by the
  in-process model on first use, and extracts facts about the user in the
  background with the model the user chose (memoryExtraction setting).
- Legacy .mind memories are copied into the store once, in the background;
  the legacy files are only read.
- Weaver consolidation, harvest, wiki, memory import, memory lanes, vector
  backfill and index reconciliation are removed; agent runs, loops, sub-agent
  results, connector fetch and the failed-turn capture write through the
  contract. Workspace sessions no longer hold a mind handle.
- FileIndexer and the install audit move to waggle.db; recall date helpers and
  the reranker are copied into core.
- The CLI REPL opens the same memory store.
2026-10-24 11:56:26 +02:00

469 lines
21 KiB
TypeScript
Raw Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
import {
PERSONAL_SCOPE,
workspaceScope,
MEMORY_IMPORTANCE,
MEMORY_SOURCES,
type MemoryHit,
type MemoryImportance,
type MemoryKind,
type MemoryScope,
type MemorySource,
type MemoryStore,
} from '@waggle/memory-contract';
import type { IdentityLayer, AwarenessLayer } from '@waggle/core';
import type { RiskLevel } from '@waggle/shared';
import { createCoreLogger } from '@waggle/core';
import { detectContradiction } from './contradiction-detector.js';
import { scanForInjection } from './injection-scanner.js';
import { normalizeForDedup, detectDramaticClaims, deriveConfidence, type ConfidenceLevel } from './text-analysis.js';
export type { ConfidenceLevel } from './text-analysis.js';
export { formatCombinedResult } from './result-formatter.js';
const log = createCoreLogger('mind-tools');
export interface ToolDefinition {
name: string;
description: string;
parameters: Record<string, unknown>;
execute: (args: Record<string, unknown>) => Promise<string>;
/**
* Provider-authored runtime risk. This is trusted metadata, never model input;
* confirmation policy may use it only to elevate name-based risk.
*/
riskLevel?: RiskLevel;
/** PM-6: Whether this tool can operate without LLM connectivity (default: false) */
offlineCapable?: boolean;
/**
* Dynamic availability check — called before each agent turn to decide
* whether this tool should be included in the tool list.
* Return false to hide the tool (e.g., browser not connected, no git repo).
* If not provided, the tool is always available.
*/
checkAvailability?: () => boolean;
}
/** Tracks tool utilization across the current session */
export interface ToolUtilizationTracker {
/** Record that a tool was used */
recordUsage(toolName: string): void;
/** Get the set of unique tools used this session */
getUsedTools(): Set<string>;
/** Get the total number of available tools */
totalAvailable: number;
/** Get utilization ratio (uniqueUsed / totalAvailable) */
getUtilization(): number;
}
/** Create a ToolUtilizationTracker instance */
export function createToolUtilizationTracker(totalAvailable: number): ToolUtilizationTracker {
const usedTools = new Set<string>();
return {
recordUsage(toolName: string) {
usedTools.add(toolName);
},
getUsedTools() {
return new Set(usedTools);
},
totalAvailable,
getUtilization() {
if (totalAvailable === 0) return 0;
return usedTools.size / totalAvailable;
},
};
}
export interface MindToolDeps {
memory: MemoryStore;
identity: IdentityLayer;
awareness: AwarenessLayer;
/** Active workspace, checked at call time; null when only personal memory is active. */
getWorkspaceId?: () => string | null;
/** W5.7: workspaces searched by search_all_workspaces. */
listWorkspaces?: () => Array<{ id: string; name: string }>;
/** Optional tool utilization tracker for session-level stats */
toolUtilizationTracker?: ToolUtilizationTracker;
/**
* Review C2: externally-owned save counter so the rate limit survives
* tool-array reconstruction (persona switch, workspace change, MCP reconnect).
* If omitted, a local counter is used (legacy behavior).
*/
saveCounter?: { count: number };
}
/** Kinds the agent may choose when it saves a memory. */
const SAVE_KINDS: readonly MemoryKind[] = ['fact', 'preference', 'decision', 'event', 'note'];
/** Recent memories compared against a new one for contradictions. */
const CONTRADICTION_WINDOW = 50;
/** Search hits compared against a new memory for normalized duplicates. */
const DEDUP_CANDIDATES = 20;
function formatHit(hit: MemoryHit, index: number): string {
return `[${index + 1}] (score: ${hit.score.toFixed(3)}, date: ${hit.createdAt.slice(0, 10)}, kind: ${hit.kind}, importance: ${hit.importance}, source: ${hit.source})\n${hit.text}`;
}
export function createMindTools(deps: MindToolDeps): ToolDefinition[] {
// W2.10: Per-session memory save rate limiter (prevents memory flooding attacks)
// Review C2: use externally-owned counter when provided so limit survives
// tool-array reconstruction (persona switch, workspace change, MCP reconnect).
const MAX_SAVES_PER_SESSION = 50;
const saveCounter = deps.saveCounter ?? { count: 0 };
const activeWorkspace = (): MemoryScope | null => {
const id = deps.getWorkspaceId?.() ?? null;
return id ? workspaceScope(id) : null;
};
return [
{
name: 'get_identity',
description: 'Get the agent identity (who am I, what is my role)',
offlineCapable: true,
parameters: {},
execute: async () => {
if (!deps.identity.exists()) return 'No identity configured yet.';
return deps.identity.toContext();
},
},
{
name: 'get_awareness',
description: 'Get current awareness state (active tasks, recent actions, pending items, flags, tool utilization)',
offlineCapable: true,
parameters: {},
execute: async () => {
let context = deps.awareness.toContext();
// Append utilization stats if tracker is available
if (deps.toolUtilizationTracker) {
const tracker = deps.toolUtilizationTracker;
const used = tracker.getUsedTools();
const utilization = tracker.getUtilization();
context += `\n\n## Tool Utilization\n`;
context += `- Unique tools used this session: ${used.size}\n`;
context += `- Total available tools: ${tracker.totalAvailable}\n`;
context += `- Utilization: ${(utilization * 100).toFixed(1)}%\n`;
if (utilization < 0.1) {
context += `- Note: Low utilization — consider using more of your available tools (skills, workflows, sub-agents) for richer results.\n`;
}
}
return context;
},
},
{
name: 'search_memory',
description: 'Search through memory for relevant past experiences and knowledge. Searches both personal and workspace memory when a workspace is active.',
offlineCapable: true,
parameters: {
type: 'object',
properties: {
query: { type: 'string', description: 'What to search for' },
scope: {
type: 'string',
enum: ['all', 'personal', 'workspace'],
description: 'Which memory to search (default: all)',
},
limit: { type: 'number', description: 'Max results to return' },
importance: {
type: 'string',
enum: ['critical', 'important', 'normal', 'temporary', 'all'],
description: 'Filter by importance level (default: all)',
},
since: {
type: 'string',
description: 'ISO date — only return memories created after this date (e.g., "2026-03-14")',
},
until: {
type: 'string',
description: 'ISO date — only return memories created before this date (e.g., "2026-03-21")',
},
},
required: ['query'],
},
execute: async (args) => {
const limit = typeof args.limit === 'number' && args.limit > 0 ? args.limit : 10;
const scope = (args.scope as string) ?? 'all';
const query = String(args.query ?? '');
const importanceFilter = (args.importance as string) ?? 'all';
// F20: Temporal filtering params
const since = typeof args.since === 'string' ? args.since : undefined;
const until = typeof args.until === 'string' ? args.until : undefined;
const ws = activeWorkspace();
// F14: exact importance filter, applied after ranking
const byImportance = (hits: MemoryHit[]): MemoryHit[] =>
importanceFilter === 'all' ? hits : hits.filter(h => h.importance === importanceFilter);
const search = (target: MemoryScope, max: number): Promise<MemoryHit[]> =>
deps.memory.search(query, {
scopes: [target],
limit: importanceFilter === 'all' ? max : max * 5,
...(since && { since }),
...(until && { until: until.length === 10 ? `${until}T23:59:59.999Z` : until }),
});
const sections: string[] = [];
// W2.6: Search workspace memory FIRST (results shown before personal)
if (ws && (scope === 'all' || scope === 'workspace')) {
const wsResults = byImportance(await search(ws, limit)).slice(0, limit);
if (wsResults.length > 0) {
sections.push('## Workspace Memory');
sections.push(...wsResults.map(formatHit));
}
}
// Search personal memory (with reduced limit when a workspace is active)
if (scope === 'all' || scope === 'personal') {
// W2.6: When inside a workspace, cap personal results to reduce noise
const personalLimit = (ws && scope === 'all') ? Math.min(limit, 3) : limit;
const personalResults = byImportance(await search(PERSONAL_SCOPE, personalLimit)).slice(0, personalLimit);
if (personalResults.length > 0) {
if (ws) {
sections.push('## Personal Memory\n_(Cross-workspace — not specific to this workspace)_');
}
sections.push(...personalResults.map(formatHit));
}
}
// W2.5: Detect potential contradictions in results
if (sections.length > 1) {
const allContent = sections.filter(s => !s.startsWith('##')).join('\n');
const contradictionSignals = ['but ', 'however', 'instead', 'no longer', 'changed to', 'reversed', 'cancelled', 'not '];
const hasConflictSignal = contradictionSignals.some(s => allContent.toLowerCase().includes(s));
if (hasConflictSignal) {
sections.push('\n⚠️ Note: Multiple memories found. Check for potential contradictions — verify which is the most current/authoritative version.');
}
}
if (sections.length === 0) return 'No relevant memories found.';
return sections.join('\n\n');
},
},
// W5.7: Cross-workspace search — searches ALL workspaces + personal
{
name: 'search_all_workspaces',
description: 'Search across ALL workspaces and personal memory simultaneously. Use for cross-project queries like "what should I work on?" or "find everything about topic X across all projects".',
offlineCapable: true,
parameters: {
type: 'object',
properties: {
query: { type: 'string', description: 'What to search for across all workspaces' },
limit: { type: 'number', description: 'Max results per workspace (default: 5)' },
},
required: ['query'],
},
execute: async (args) => {
const query = String(args.query ?? '');
const limitPerWs = typeof args.limit === 'number' && args.limit > 0 ? args.limit : 5;
const sections: string[] = [];
const short = (hit: MemoryHit, i: number): string =>
`[${i + 1}] (score: ${hit.score.toFixed(3)}, importance: ${hit.importance})\n${hit.text}`;
const personalResults = await deps.memory.search(query, { scopes: [PERSONAL_SCOPE], limit: limitPerWs });
if (personalResults.length > 0) {
sections.push('## Personal Memory');
sections.push(...personalResults.map(short));
}
for (const { id, name } of deps.listWorkspaces?.() ?? []) {
try {
const wsResults = await deps.memory.search(query, { scopes: [workspaceScope(id)], limit: limitPerWs });
if (wsResults.length > 0) {
sections.push(`## Workspace: ${name} (${id})`);
sections.push(...wsResults.map(short));
}
} catch (err) { log.warn(`search_all_workspaces: skipped workspace ${id}`, err); }
}
if (sections.length === 0) return 'No relevant memories found across any workspace.';
return sections.join('\n\n');
},
},
{
name: 'save_memory',
description: 'Save a new memory. Defaults to workspace memory when a workspace is active.\n\n'
+ 'CRITICAL ROUTING RULES:\n'
+ '- target="workspace" (DEFAULT): ALL project data, client data, decisions, tasks, meeting notes, research findings, confidential information, names, budgets, timelines. '
+ 'Workspace memories are ISOLATED — they cannot be seen from other workspaces. Use this for ANYTHING workspace-specific.\n'
+ '- target="personal": ONLY for user preferences (favorite color, communication style), personal facts (name, role, timezone), '
+ 'and cross-workspace knowledge (general skills, tool preferences). Personal memories are shared across ALL workspaces.\n\n'
+ 'When in doubt, use workspace. Never save client names, budgets, confidential data, or project-specific information to personal memory.',
offlineCapable: true,
parameters: {
type: 'object',
properties: {
content: { type: 'string', description: 'The memory content to save' },
kind: {
type: 'string',
enum: [...SAVE_KINDS],
description: 'What the memory is: fact (default), preference, decision, event (something that happened, with its date in the text), note.',
},
importance: {
type: 'string',
enum: ['critical', 'important', 'normal', 'temporary'],
description: 'How important is this memory',
},
target: {
type: 'string',
enum: ['workspace', 'personal'],
description: 'Which memory to save to. Workspace (default): ALL project/client/confidential data — isolated per workspace. Personal: ONLY user preferences and cross-workspace knowledge — shared across all workspaces.',
},
source: {
type: 'string',
enum: ['user_stated', 'tool_verified', 'agent_inferred'],
description: 'Provenance: user_stated = the user said this, tool_verified = confirmed via tool output, agent_inferred = your own analysis/synthesis.',
},
confidence: {
type: 'string',
enum: ['high', 'medium', 'low', 'unverified'],
description: 'Confidence level. Auto-derived from source if omitted: tool_verified→high, user_stated→medium, agent_inferred→low.',
},
},
required: ['content'],
},
execute: async (args) => {
const content = typeof args.content === 'string' ? args.content.trim() : '';
if (!content) return 'Memory save skipped: content is empty.';
// Review C1: scan LLM-controlled content for prompt-injection payloads
// BEFORE any write.
const scan = scanForInjection(content, 'user_input');
if (!scan.safe) {
return `Memory save blocked: content contains suspected prompt-injection payload (${scan.flags.join(', ')}). The content was NOT saved.`;
}
// W2.10: Rate limit memory saves to prevent flooding (50 per session)
// Review C2: counter is externally-owned so it survives tool-array rebuilds.
saveCounter.count++;
if (saveCounter.count > MAX_SAVES_PER_SESSION) {
return `Memory save rate limit reached (${MAX_SAVES_PER_SESSION} saves this session). This prevents memory flooding. Start a new session to save more memories.`;
}
// Untrusted args: validate against the canonical unions, default on mismatch.
let importance: MemoryImportance =
typeof args.importance === 'string' && (MEMORY_IMPORTANCE as readonly string[]).includes(args.importance)
? (args.importance as MemoryImportance)
: 'normal';
const kind: MemoryKind =
typeof args.kind === 'string' && (SAVE_KINDS as readonly string[]).includes(args.kind)
? (args.kind as MemoryKind)
: 'fact';
const target = typeof args.target === 'string' ? args.target : 'workspace';
const source: MemorySource =
typeof args.source === 'string' && (MEMORY_SOURCES as readonly string[]).includes(args.source)
? (args.source as MemorySource)
: 'user_stated';
const ws = activeWorkspace();
// F6: Derive confidence from source if not explicitly provided
const confidence: ConfidenceLevel = (args.confidence as ConfidenceLevel) ?? deriveConfidence(source);
// F7: Strict workspace routing — respect target parameter, with safety guardrail
let effectiveTarget = target;
// B1-guardrail: Detect workspace-specific content being routed to personal memory
// If a workspace is active and content contains confidential/project signals, redirect to workspace
if (effectiveTarget === 'personal' && ws != null) {
const workspaceSpecificPatterns = [
/\bconfidential\b/i, /\bclient\b/i, /\bbudget\b/i, /\bengagement\b/i,
/\bdeliverable\b/i, /\bmilestone\b/i, /\btimeline\b/i, /\bdeadline\b/i,
/\bceo\b/i, /\bcto\b/i, /\bcfo\b/i, /\bcoo\b/i,
/\$\d{2,}[,.]?\d*[kmb]?\b/i, // dollar amounts ($500K, $1.2M, etc.)
/\bproject\b.*\b(?:plan|status|update)\b/i,
/\bcontract\b/i, /\bproposal\b/i, /\bnda\b/i, /\bsow\b/i,
];
if (workspaceSpecificPatterns.some(p => p.test(content))) {
effectiveTarget = 'workspace';
}
}
const useWorkspace = effectiveTarget === 'workspace' && ws != null;
const targetScope = useWorkspace ? ws! : PERSONAL_SCOPE;
const otherScope = useWorkspace ? PERSONAL_SCOPE : ws;
const mindLabel = useWorkspace ? 'workspace' : 'personal';
// F22: Detect dramatic claims and flag them
const dramaticClaims = detectDramaticClaims(content);
let dramaticFlag = '';
if (dramaticClaims.length) {
// Downgrade importance to 'temporary' for dramatic claims unless explicitly set to critical
if (importance !== 'critical') {
importance = 'temporary';
}
dramaticFlag = ` [flag: dramatic_claim (${dramaticClaims.join(', ')})]`;
}
// ── Dedup (F7 cross-memory + F16 normalized) ──────────────
// Identical text in the target scope is caught by the store itself;
// this also catches normalized matches and copies in the other scope.
const normalized = normalizeForDedup(content);
const findDuplicate = async (scope: MemoryScope): Promise<string | null> => {
if (!normalized) return null;
try {
const candidates = await deps.memory.search(content, { scopes: [scope], limit: DEDUP_CANDIDATES });
const match = candidates.find(c => normalizeForDedup(c.text) === normalized);
return match ? match.id : null;
} catch {
return null; // non-blocking — proceed with save if dedup check fails
}
};
const sameScopeDuplicate = await findDuplicate(targetScope);
if (sameScopeDuplicate) {
return `Memory already exists in ${mindLabel} memory (${sameScopeDuplicate}) — skipped duplicate save.`;
}
if (otherScope) {
const crossDuplicate = await findDuplicate(otherScope);
if (crossDuplicate) {
const otherLabel = useWorkspace ? 'personal' : 'workspace';
return `Memory already exists in ${otherLabel} memory (${crossDuplicate}) — skipped cross-memory duplicate save.`;
}
}
// Skills 2.0 gap K: write-path conflict detection. Conflicts are data,
// not errors: the memory is still saved, and the response is flagged
// so the agent surfaces the conflict to the user.
let conflictFlag = '';
try {
const recent = await deps.memory.list({ scopes: [targetScope], limit: CONTRADICTION_WINDOW });
const contradiction = detectContradiction(content, recent.map(r => ({ content: r.text })));
if (contradiction.isContradiction && contradiction.conflictsWith) {
conflictFlag = ` [flag: contradicts_existing (${contradiction.conflictsWith.slice(0, 80).replace(/\s+/g, ' ').trim()}…)]`;
}
} catch { /* non-blocking — contradiction check failure proceeds with save */ }
const [change] = await deps.memory.remember({
scope: targetScope,
text: content,
kind,
importance,
source,
origin: 'agent',
metadata: { confidence },
});
if (change?.event === 'unchanged') {
return `Memory already exists in ${mindLabel} memory (${change.record.id}) — skipped duplicate save.`;
}
return `Memory saved to ${mindLabel} memory (kind: ${kind}, importance: ${importance}, source: ${source}, confidence: ${confidence}${dramaticFlag}${conflictFlag}).`;
},
},
{
name: 'add_task',
description: 'Add a task to the awareness layer for tracking',
offlineCapable: true,
parameters: {
type: 'object',
properties: {
content: { type: 'string', description: 'Task description' },
priority: { type: 'number', description: 'Priority (0-10, higher = more important)' },
},
required: ['content'],
},
execute: async (args) => {
const taskContent = typeof args.content === 'string' ? args.content.slice(0, 2000) : '';
const item = deps.awareness.add('task', taskContent, (args.priority as number) ?? 5);
return `Task added: "${item.content}" (priority: ${item.priority})`;
},
},
];
}