- 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.
324 lines
13 KiB
TypeScript
324 lines
13 KiB
TypeScript
/**
|
||
* 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 } : {}) };
|
||
}
|