Files
waggle-os/packages/server/src/local/loop-executor.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

324 lines
13 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.
/**
* Loop executor — the report-only (L1) tick for `job_type:'loop'` automations.
*
* A "Loop" is a stateful, memory-powered scheduled automation for knowledge
* work. Each tick composes pieces Waggle already ships:
*
* recall (memory search) → what does this workspace's memory say about the goal?
* prior state (Awareness)→ what did the PREVIOUS tick report? (cross-tick spine)
* maker (toolless chat) → produce a report grounded in the above
* checker (LLMJudge) → verify the report against a rubric (the gate)
* write-back (memory + Awareness) → persist into local memory
*
* L1 / report-only guarantee: the maker is a plain text completion with NO
* tools wired, so a tick cannot send an email, write a file, or touch any
* external system — the only side effect is writing to the workspace's own
* memory (local, sovereign). This is what makes Loop v0 safe by construction;
* the headless ConfirmationGate deny-default (confirmation.ts) is the second
* line of defence for the day tools are added.
*
* Everything here is reused infrastructure — no new abstractions. The executor
* is extracted from index.ts only so it can be unit-tested with an in-memory
* memory store + a stubbed chat function.
*/
import type { AwarenessLayer } from '@waggle/core';
import type { MemoryScope, MemoryStore } from '@waggle/memory-contract';
import { LLMJudge, scanForInjection } from '@waggle/agent';
/** Minimal slice of a CronSchedule the loop executor needs (decoupled for tests). */
export interface LoopSchedule {
id: number;
name: string;
job_config: string;
last_run_at: string | null;
}
/** A single LLM completion. maxTokens lets the checker run cheaper than the maker. */
export type LoopChat = (prompt: string, maxTokens?: number) => Promise<string>;
export interface LoopLogger {
info: (msg: string) => void;
warn: (msg: string) => void;
}
export interface LoopTickDeps {
schedule: LoopSchedule;
memory: MemoryStore;
/** The workspace (or personal) memory this loop reads and writes. */
scope: MemoryScope;
/** Awareness items of the same scope, in waggle.db; the loop keeps its state there. */
awareness: AwarenessLayer;
/** Toolless completion against the local proxy/LiteLLM. */
chat: LoopChat;
log: LoopLogger;
}
/** A single follow-up action an assist-mode Loop proposes (held for approval). */
export interface ProposedAction {
tool: string;
args: Record<string, unknown>;
summary: string;
}
export interface LoopTickResult {
/** true when the tick did no work (no prompt, throttled, empty output). */
skipped?: boolean;
reason?: string;
/** ≤200-char notification body. */
summary: string;
/** Judge overall score 0..1 (undefined when the checker failed). */
score?: number;
/** Whether a memory frame was written this tick. */
wrote?: boolean;
/** Assist mode: the single action the maker proposed (the caller enqueues it
* — runLoopTick stays pure and never touches the held-action store). */
proposedAction?: ProposedAction;
}
/**
* Cost floor: a loop is 1–2 LLM round-trips, so an unguarded `* * * * *` cron
* would burn tokens every 60s. Skip a tick that fires within this window of the
* previous run. Mirrors connector_fetch's frequency-floor philosophy (a tighter
* cron is treated as "as often as the floor allows", never an error). Override
* per-loop via job_config.minIntervalMs.
*/
export const LOOP_MIN_INTERVAL_MS = 10 * 60 * 1000; // 10 minutes
interface LoopSpec {
prompt: string;
query: string;
rubric?: string;
writeToMemory: boolean;
minIntervalMs: number;
/** 'report' = L1 (default). 'assist' = L2: the maker may propose ONE action
* that is held for human approval. The maker stays toolless either way. */
mode: 'report' | 'assist';
}
/** Matches a fenced ```json … ``` block (used to extract / strip a proposal). */
const PROPOSAL_FENCE_RE = /```json\s*([\s\S]*?)```/gi;
/**
* Extract the LAST ```json fence from an assist-mode maker reply as a proposed
* action. Returns null for no fence, malformed JSON, an explicit {"none":true},
* or a missing tool. Pure + dependency-free. The args are NOT validated here —
* the enqueue boundary (enqueueHeldAction) allowlists + injection-scans them.
*/
export function parseProposal(makerOutput: string): ProposedAction | null {
const matches = [...makerOutput.matchAll(PROPOSAL_FENCE_RE)];
if (matches.length === 0) return null;
let parsed: unknown;
try {
parsed = JSON.parse(matches[matches.length - 1][1].trim());
} catch {
return null;
}
if (!parsed || typeof parsed !== 'object') return null;
const o = parsed as Record<string, unknown>;
if (o.none === true) return null;
if (typeof o.tool !== 'string' || !o.tool.trim()) return null;
return {
tool: o.tool,
args: o.args && typeof o.args === 'object' ? o.args as Record<string, unknown> : {},
summary: typeof o.summary === 'string' ? o.summary : '',
};
}
/** Parse + validate the loop's job_config blob into a LoopSpec. */
export function parseLoopSpec(jobConfig: string): LoopSpec | null {
let cfg: Record<string, unknown>;
try {
cfg = JSON.parse(jobConfig || '{}') as Record<string, unknown>;
} catch {
return null;
}
const prompt = typeof cfg.prompt === 'string' ? cfg.prompt.trim() : '';
if (!prompt) return null;
const queryRaw = typeof cfg.query === 'string' ? cfg.query.trim() : '';
const minRaw = typeof cfg.minIntervalMs === 'number' && Number.isFinite(cfg.minIntervalMs)
? cfg.minIntervalMs
: LOOP_MIN_INTERVAL_MS;
return {
prompt,
query: queryRaw || prompt,
rubric: typeof cfg.rubric === 'string' && cfg.rubric.trim() ? cfg.rubric : undefined,
writeToMemory: cfg.writeToMemory !== false,
minIntervalMs: Math.max(0, minRaw),
mode: cfg.mode === 'assist' ? 'assist' : 'report',
};
}
/** Build the maker prompt: grounds the report in prior-tick state + recalled memory. */
export function buildMakerPrompt(opts: {
name: string;
prompt: string;
priorResult: string;
recalled: string;
/** assist mode (L2) — ask the maker to optionally propose ONE action. */
assist?: boolean;
}): string {
const parts = [
`You are running a scheduled knowledge-work automation called "${opts.name}".`,
];
if (opts.priorResult) {
parts.push(`What you reported on the previous run:\n${opts.priorResult}`);
}
if (opts.recalled) {
parts.push(`Relevant context recalled from this workspace's memory:\n${opts.recalled}`);
}
parts.push(`Your task:\n${opts.prompt}`);
if (opts.assist) {
parts.push(
'Produce a concise, factual report grounded in the recalled context. Then, IF AND ONLY IF a ' +
'concrete follow-up action would clearly help, propose exactly ONE action by ending your reply ' +
'with a single fenced JSON block:\n' +
'```json\n{"tool":"send_email","args":{"to":"…","subject":"…","body":"…"},"summary":"one line: what it does and why"}\n```\n' +
'Allowed tools: send_email, write_file, edit_file, or a connector write action. If no action is ' +
'warranted, end with ```json\n{"none":true}\n```. You are NOT executing anything — a human reviews ' +
'and approves every proposal before it runs. Do not invent facts.',
);
} else {
parts.push(
'Produce a concise, factual report. Emphasise what is NEW or changed since the previous ' +
'run. Do not invent facts — ground every claim in the recalled context, or say plainly ' +
'what you could not determine. This is a report only; do not take any action.',
);
}
return parts.join('\n\n');
}
/**
* Run one Loop tick. Pure-ish: all I/O goes through `deps` (memory, awareness,
* chat). Throws are intentionally NOT swallowed for the maker/judge LLM path so
* the scheduler records the failure in cron_execution_history and auto-disables
* after repeated failures (feeds the engine-liveness/health story); recall and
* memory-write failures ARE caught (best-effort, must not fail the whole tick).
*/
export async function runLoopTick(deps: LoopTickDeps): Promise<LoopTickResult> {
const { schedule, memory, scope, awareness, chat, log } = deps;
const spec = parseLoopSpec(schedule.job_config);
if (!spec) {
log.warn(`[loop] "${schedule.name}" has no usable prompt in job_config — skipping`);
return { skipped: true, reason: 'no prompt', summary: '' };
}
const stateKey = `loop:${schedule.id}`; // namespaced so loops don't collide on awareness.status
const prior = awareness.getByStatus(stateKey)[0];
const priorMeta = prior ? awareness.parseMetadata(prior) : undefined;
let priorResult = priorMeta ? String(priorMeta.result ?? '') : '';
// Cost floor — throttle a loop that ran within its min interval. Measured
// against the awareness `lastTickAt` (ISO-8601 + timezone, written ONLY after
// a genuine run), NOT schedule.last_run_at: the scheduler rewrites that via
// markRun even on a SKIP (which would reset the window every tick), and it is
// SQLite's `datetime('now')` space format that V8 parses as LOCAL time
// (timezone-dependent breakage). lastTickAt is the correct, TZ-safe signal.
const lastTick = priorMeta?.lastTickAt ? Date.parse(String(priorMeta.lastTickAt)) : NaN;
if (Number.isFinite(lastTick)) {
const elapsed = Date.now() - lastTick;
if (elapsed >= 0 && elapsed < spec.minIntervalMs) {
return { skipped: true, reason: 'within min interval', summary: '' };
}
}
// Recall prior context by meaning (best-effort — a recall failure must not kill the tick).
let recalled = '';
try {
const hits = await memory.search(spec.query, { scopes: [scope], limit: 8 });
recalled = hits.map(h => h.text).join('\n---\n');
} catch (err) {
log.warn(`[loop] "${schedule.name}" recall failed: ${err instanceof Error ? err.message : String(err)}`);
}
// Defense-in-depth: recalled memory and the prior tick's output are untrusted
// input to the maker prompt — drop any context that trips the injection
// scanner (the same guard connector-harvest applies before a memory write).
// Matters more once loops gain tools, but cheap and consistent to enforce at L1.
if (recalled && !scanForInjection(recalled, 'tool_output').safe) {
log.warn(`[loop] "${schedule.name}" recalled memory tripped injection scan — dropping context`);
recalled = '';
}
if (priorResult && !scanForInjection(priorResult, 'tool_output').safe) {
log.warn(`[loop] "${schedule.name}" prior-tick state tripped injection scan — dropping context`);
priorResult = '';
}
// Maker — toolless report generation. In assist mode it may append a single
// ```json proposal fence (parsed + stripped below; never executed here).
const rawReport = (await chat(buildMakerPrompt({
name: schedule.name,
prompt: spec.prompt,
priorResult,
recalled,
assist: spec.mode === 'assist',
}), 2048)).trim();
if (!rawReport) {
return { skipped: true, reason: 'empty report', summary: '' };
}
// Assist mode: lift the proposed action out and strip its fence from the
// human-facing report. runLoopTick stays pure — the caller enqueues it.
let proposedAction: ProposedAction | undefined;
let report = rawReport;
if (spec.mode === 'assist') {
proposedAction = parseProposal(rawReport) ?? undefined;
report = rawReport.replace(PROPOSAL_FENCE_RE, '').trim() || rawReport;
}
// Checker — LLMJudge verifies the report (the verification gate). Best-effort:
// the judge never throws (returns an errorScore on failure), but the LLM call
// it makes could, so guard it — a low/absent score still reports at L1.
let score: number | undefined;
try {
const judge = new LLMJudge((p) => chat(p, 512), spec.rubric ? { rubricOverride: spec.rubric } : {});
const judged = await judge.score({
input: spec.query,
expected: 'A correct, complete, well-grounded report.',
actual: report,
context: priorResult ? `Prior tick result:\n${priorResult}` : undefined,
});
if (judged.parsed) score = judged.overall;
} catch (err) {
log.warn(`[loop] "${schedule.name}" checker failed: ${err instanceof Error ? err.message : String(err)}`);
}
// Write the report into local memory (the durable spine). Best-effort.
let wrote = false;
if (spec.writeToMemory) {
try {
const header = `[Loop: ${schedule.name}] ${new Date().toISOString()}${score !== undefined ? ` · score ${score.toFixed(2)}` : ''}`;
// ISO timestamp in the body keeps each tick's memory distinct (the store
// does not write identical text twice in one scope).
await memory.remember({
scope,
text: `${header}\n\n${report}`,
kind: 'note',
source: 'agent_inferred',
origin: 'loop',
});
wrote = true;
} catch (err) {
log.warn(`[loop] "${schedule.name}" memory write failed: ${err instanceof Error ? err.message : String(err)}`);
}
}
// Update cross-tick state so the NEXT tick sees what this one reported.
const meta = {
status: stateKey,
result: report,
lastTickAt: new Date().toISOString(),
...(score !== undefined ? { score: String(score) } : {}),
};
try {
if (prior) awareness.updateMetadata(prior.id, meta);
else awareness.add('pending', `Loop: ${schedule.name}`, 0, undefined, meta);
} catch (err) {
log.warn(`[loop] "${schedule.name}" state update failed: ${err instanceof Error ? err.message : String(err)}`);
}
const summary = report.length > 200 ? `${report.slice(0, 197)}...` : report;
return { summary, score, wrote, ...(proposedAction ? { proposedAction } : {}) };
}