Files
waggle-os/packages/agent/src/prompt-assembler.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

534 lines
22 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.
/**
* PromptAssembler — sixth layer between memory retrieval and the LLM call.
*
* Produces a tier-adaptive, typed, scaffolded prompt. Wraps the existing
* buildSystemPrompt path rather than replacing it. DEFAULT ON since the W4
* live chat smoke (kill switch: WAGGLE_PROMPT_ASSEMBLER=0).
*
* Tier drives:
* - frame count (top 3 / 6 / 10 for small / mid / frontier)
* - response scaffold (tier != frontier AND task shape confidence ≥ 0.3)
*
* Truncation policy: if the assembled system prompt exceeds `maxSystemChars`,
* trim Recent changes → Active work → State, in that order. Identity, Persona,
* Personal preferences, Response format, and Closed-world rewrite are never trimmed.
*/
import type { MemoryImportance } from '@waggle/memory-contract';
import type { RecallFrame } from './recall-frame.js';
import type { AgentPersona } from './personas.js';
import type { ModelTier } from './model-tier.js';
import { detectTaskShape, type TaskShape, type TaskShapeType } from './task-shape.js';
import type { ContextFrames } from './orchestrator.js';
import { logTurnEvent } from './turn-context.js';
// ── Types ────────────────────────────────────────────────────────────
export interface RecalledMemory {
workspace: RecallFrame[];
personal: RecallFrame[];
/** False if the injection scanner blocked the recall — assembler must ignore. */
scanSafe: boolean;
/**
* W4.5: pre-rendered multi-lane recall block (the recallMemory output —
* profiles/facts/events/window/snippet sections + temporal guidance +
* provenance preamble). When present, the assembler renders it VERBATIM
* as the recall section instead of re-rendering raw frames — fixing both
* the double-compute (no second search) and the lane-fidelity loss (the
* frame renderer knows nothing about the W4.3b lanes).
*/
renderedText?: string;
}
export interface AssembleInput {
corePrompt: string;
persona: AgentPersona | null;
context: ContextFrames;
recalled: RecalledMemory;
query: string;
tier: ModelTier;
taskShape?: TaskShape;
workspaceTone?: string;
}
export interface AssembledPromptDebug {
tier: ModelTier;
taskShape: TaskShapeType | null;
taskShapeConfidence: number;
scaffoldApplied: boolean;
/** Always returned; optional in the type for backward-compatible external mocks. */
exclusiveResponseContract?: boolean;
/** Always returned; optional in the type for backward-compatible external mocks. */
scaffoldSuppressed?: boolean;
/** Always returned; optional in the type for backward-compatible external mocks. */
closedWorldRewrite?: boolean;
/** v5: which scaffold style was used (compression = v4 default, expansion = v5 opt-in). */
scaffoldStyle: ScaffoldStyle;
sectionsIncluded: string[];
framesUsed: number;
totalChars: number;
}
export interface AssembledPrompt {
system: string;
userPrefix: string;
responseScaffold: string | null;
debug: AssembledPromptDebug;
}
/**
* Scaffold style — v5 addition.
*
* v4's scaffolds are compression-style: "say less, in shorter form." v5 adds
* expansion-style scaffolds that give the model explicit multi-part templates
* to fill. The hypothesis: dense instruction-tuned families (Gemma) benefit
* from expansion, while reasoning-capable families (Claude, Qwen thinking
* variants) benefit from compression. See v5 brief §0 and §7.3.
*/
export type ScaffoldStyle = 'compression' | 'expansion';
export interface AssembleOptions {
taskShape?: TaskShape;
tierOverride?: ModelTier;
/** Max system-prompt chars before truncation kicks in. Default 32_000. */
maxSystemChars?: number;
/** Minimum task-shape confidence for scaffold emission. Default 0.3. */
confidenceThreshold?: number;
/**
* v5: scaffold variant. Default 'compression' preserves the v4 scaffold
* body; the assembler adds a response-format precedence qualifier.
*/
scaffoldStyle?: ScaffoldStyle;
/**
* W4.5: pre-rendered recall block from recallMemory. When set (even to ''),
* buildAssembledPrompt skips its own searches — fixes the double-compute
* bug (recall ran twice per turn). '' means recall was empty/blocked.
*/
recalledText?: string;
/** H-AUDIT-1: per-turn trace ID (UUID v4). Logs prompt-assembly stage. */
turnId?: string;
/**
* Force exclusive-output handling for code-owned prompts with a typed output
* contract. Free-form user language is deliberately not inferred here.
*/
exclusiveResponseContract?: boolean;
}
// ── Constants ────────────────────────────────────────────────────────
const DEFAULT_MAX_CHARS = 32_000;
const DEFAULT_CONFIDENCE_THRESHOLD = 0.3;
const DEFAULT_SCAFFOLD_QUALIFIER = 'If the user specifies a response format, follow it exactly. Otherwise:';
const TRANSFORM_DIRECTIVE_START = String.raw`(?:^|[.!?]\s+)`;
const TRANSFORM_DIRECTIVE_COURTESY = String.raw`(?:(?:please|kindly)\s+|(?:can|could|would|will)\s+you\s+|I\s+(?:want|need)\s+you\s+to\s+|I'd\s+like\s+you\s+to\s+)?`;
const CLOSED_WORLD_TRANSFORM_REQUEST = new RegExp([
`${TRANSFORM_DIRECTIVE_START}${TRANSFORM_DIRECTIVE_COURTESY}${String.raw`(?:rewrite|rephrase|paraphrase|revise|edit|polish|tighten|condense|shorten|summari[sz]e|translate)\b`}`,
`${TRANSFORM_DIRECTIVE_START}${TRANSFORM_DIRECTIVE_COURTESY}${String.raw`turn\b[\s\S]{0,80}\binto\b`}`,
].join('|'), 'i');
const CLOSED_WORLD_BOUNDARY_FIRST_REQUEST = new RegExp([
`${TRANSFORM_DIRECTIVE_START}${String.raw`using\s+only\s+(?:the\s+)?(?:supplied|provided|source)\s+(?:text|facts?|material|content|information)[,:]\s+(?:please\s+)?(?:rewrite|rephrase|paraphrase|revise|edit|polish|tighten|condense|shorten|summari[sz]e|translate)\b`}`,
`${TRANSFORM_DIRECTIVE_START}${String.raw`without\s+(?:add(?:ing)?|introduc(?:ing)?|invent(?:ing)?)\s+(?:any\s+)?(?:new|additional)\s+(?:claims?|facts?|details?|information)[,:]\s+(?:please\s+)?(?:rewrite|rephrase|paraphrase|revise|edit|polish|tighten|condense|shorten|summari[sz]e|translate)\b`}`,
].join('|'), 'i');
const CLOSED_WORLD_EVIDENCE_BOUNDARY = new RegExp([
String.raw`\bclosed[- ]world\b`,
String.raw`\b(?:add|introduce|invent)\s+no\s+(?:new|additional)\s+(?:claims?|facts?|details?|information)\b`,
String.raw`\b(?:do\s+not|don't|without)\s+(?:add(?:ing)?|introduc(?:e|ing)|invent(?:ing)?)\s+(?:any\s+)?(?:new|additional)\s+(?:claims?|facts?|details?|information)\b`,
String.raw`\bus(?:e|ing)\s+only\s+(?:the\s+)?(?:supplied|provided|source)\s+(?:text|facts?|material|content|information)\b`,
String.raw`\b(?:supplied|provided)\s+(?:text|facts?|material|content|information)\s+(?:is|are)\s+(?:the\s+)?(?:complete|entire|only)\s+(?:evidence|source|basis|input)\b`,
].join('|'), 'i');
export const CLOSED_WORLD_REWRITE_CONTRACT = [
'# Closed-world rewrite',
"The user's supplied source text is the complete evidence boundary for this transformation.",
'- Preserve every supplied fact, including its polarity, status, quantity, timing, recommendation, and original certainty.',
'- Do not add implications, explanations, rationale, risks, causes, predictions, assumptions, recommendations, or conclusions unless the source states them.',
'- Output only the requested rewrite; omit commentary and follow-up offers unless the user explicitly requests them.',
].join('\n');
export function isClosedWorldRewriteRequest(query: string): boolean {
return (CLOSED_WORLD_TRANSFORM_REQUEST.test(query)
|| CLOSED_WORLD_BOUNDARY_FIRST_REQUEST.test(query))
&& CLOSED_WORLD_EVIDENCE_BOUNDARY.test(query);
}
/** Frames retained per tier — assembler caps top-N after upstream retrieval. */
const FRAME_LIMITS: Record<ModelTier, number> = {
small: 3,
mid: 6,
frontier: 10,
};
/** Numeric weight for frame ranking — higher = more important. */
const IMPORTANCE_WEIGHT: Record<MemoryImportance, number> = {
critical: 4,
important: 3,
normal: 2,
temporary: 1,
};
/**
* COMPRESSION scaffold matrix — v4 default.
*
* Rule: apply only when tier !== 'frontier' AND taskShape.confidence ≥ threshold.
* `draft` and `mixed` never get a scaffold at any tier.
*
* Text preserved byte-for-byte from v4 for parity. See PromptAssembler v4
* brief §9 and v5 brief §9 for rationale.
*/
const COMPRESSION_SCAFFOLDS: Record<TaskShapeType, Record<ModelTier, string | null>> = {
research: {
small: 'Cite the frame. Quote the relevant fragment. Answer directly.',
mid: 'Cite source. Answer.',
frontier: null,
},
compare: {
small: 'State the assumption. List the trade-offs. Give the recommendation.',
mid: 'Briefly state assumption, then recommendation.',
frontier: null,
},
decide: {
small: 'State the assumption. List the trade-offs. Give the recommendation.',
mid: 'Briefly state assumption, then recommendation.',
frontier: null,
},
review: {
small: 'State the assumption. List the trade-offs. Give the recommendation.',
mid: 'Briefly state assumption, then recommendation.',
frontier: null,
},
'plan-execute': {
small: 'Confirm inputs. State plan in one sentence. Execute. Report result.',
mid: 'State plan. Execute. Report.',
frontier: null,
},
draft: { small: null, mid: null, frontier: null },
mixed: { small: null, mid: null, frontier: null },
};
/**
* EXPANSION scaffold matrix — v5 addition.
*
* Design principle: replace "say less" with "say more, in named sections."
* Dense instruction-tuned models (Gemma family) appear to be hurt by
* compression-style scaffolds because compression fights their natural
* elaboration. Expansion gives them more structure to fill.
*
* Frontier tier deliberately yields `null` for every shape — v4 showed
* F > E with compression scaffolds (which also produce `null` at frontier,
* since the assembler's frontier treatment is "no response scaffold, but
* still the typed layered prompt"). Don't risk that replication by
* applying expansion to frontier models.
*
* See PromptAssembler v5 brief §7.3.
*/
const EXPANSION_SCAFFOLDS: Record<TaskShapeType, Record<ModelTier, string | null>> = {
research: {
small:
'Answer in three parts:\n' +
'1. Direct answer — one sentence stating the answer without qualification.\n' +
'2. Source — identify the memory frame and quote the relevant fragment verbatim.\n' +
'3. Context — briefly describe surrounding facts or decisions that situate this answer.',
mid: 'Direct answer first, then source quote, then one-sentence context.',
frontier: null,
},
compare: {
small:
'Structure your response in four parts:\n' +
"1. Assumption — state the key assumption you're reasoning under.\n" +
'2. Factors — walk through each relevant factor in turn. For each: name it, ' +
'explain how it specifically applies to this case, and weigh its importance.\n' +
'3. Trade-offs — identify the main tension between the options.\n' +
'4. Recommendation — give a clear recommendation with a brief justification, ' +
'and state your confidence (low/medium/high).',
mid:
'Organize your response as: assumption, factors analyzed in turn, main trade-off, ' +
'recommendation with confidence level.',
frontier: null,
},
decide: {
small:
'Structure your response in four parts:\n' +
"1. Assumption — state the key assumption you're reasoning under.\n" +
'2. Factors — walk through each relevant factor in turn. For each: name it, ' +
'explain how it specifically applies to this case, and weigh its importance.\n' +
'3. Trade-offs — identify the main tension between the options.\n' +
'4. Recommendation — give a clear recommendation with a brief justification, ' +
'and state your confidence (low/medium/high).',
mid:
'Organize your response as: assumption, factors analyzed in turn, main trade-off, ' +
'recommendation with confidence level.',
frontier: null,
},
review: {
small:
'Structure your response in four parts:\n' +
"1. Assumption — state the key assumption you're reasoning under.\n" +
'2. Factors — walk through each relevant factor in turn. For each: name it, ' +
'explain how it specifically applies to this case, and weigh its importance.\n' +
'3. Trade-offs — identify the main tension between the options.\n' +
'4. Recommendation — give a clear recommendation with a brief justification, ' +
'and state your confidence (low/medium/high).',
mid:
'Organize your response as: assumption, factors analyzed in turn, main trade-off, ' +
'recommendation with confidence level.',
frontier: null,
},
'plan-execute': {
small:
'Organize your response as named phases. For each phase:\n' +
'- Goal — what this phase achieves.\n' +
'- Steps — 2–4 concrete steps.\n' +
'- Dependencies — what must be true before this phase starts.\n' +
'- Blockers — anything currently unresolved.\n\n' +
'Conclude with: (a) a timeline estimate, and (b) a summary of the critical-path risk.',
mid:
'Plan as named phases. Each phase: goal, steps, dependencies, blockers. ' +
'Close with timeline and critical-path risk.',
frontier: null,
},
draft: { small: null, mid: null, frontier: null },
mixed: { small: null, mid: null, frontier: null },
};
/** Section names, in truncation-priority order (first to trim → last to trim). */
const TRUNCATION_ORDER = ['Recent changes', 'Active work', 'State'] as const;
// ── Helpers ──────────────────────────────────────────────────────────
function selectFrames(frames: ReadonlyArray<RecallFrame>, limit: number): RecallFrame[] {
const seen = new Set<string>();
const deduped: RecallFrame[] = [];
for (const f of frames) {
if (!seen.has(f.id)) {
seen.add(f.id);
deduped.push(f);
}
}
deduped.sort((a, b) => {
const weightDelta = IMPORTANCE_WEIGHT[b.importance] - IMPORTANCE_WEIGHT[a.importance];
if (weightDelta !== 0) return weightDelta;
return b.created_at.localeCompare(a.created_at);
});
return deduped.slice(0, limit);
}
function selectScaffold(
tier: ModelTier,
taskShape: TaskShape | undefined,
confidenceThreshold: number,
style: ScaffoldStyle,
): string | null {
if (!taskShape) return null;
if (taskShape.confidence < confidenceThreshold) return null;
// Frontier short-circuit — belt-and-suspenders with the maps themselves
// (both COMPRESSION and EXPANSION map frontier to null for every shape).
// See v5 brief §7.3.
if (tier === 'frontier') return null;
const map = style === 'expansion' ? EXPANSION_SCAFFOLDS : COMPRESSION_SCAFFOLDS;
return map[taskShape.type][tier];
}
function renderPersona(persona: AgentPersona): string {
const lines = [`## Persona: ${persona.name}`];
if (persona.tagline) lines.push(persona.tagline);
lines.push(persona.description);
const operatingInstructions = persona.systemPrompt.trim();
if (operatingInstructions) {
lines.push(`### Persona operating instructions\n${operatingInstructions}`);
}
return lines.join('\n');
}
function renderFrames(frames: RecallFrame[]): string {
// W4.1 (#1): date-prefixed — matches recallMemory's `[YYYY-MM-DD, importance]`
// line format so the temporal anchor survives the assembled path too.
return frames.map(f => `- [${f.created_at?.slice(0, 10) ?? 'unknown'}, ${f.importance}] ${f.content}`).join('\n');
}
function renderActiveWork(items: ContextFrames['activeWork']): string {
const sorted = [...items].sort((a, b) => b.priority - a.priority);
return sorted.map(w => `- [${w.category}] ${w.content}`).join('\n');
}
function renderPreferences(prefs: string[]): string {
return prefs.map(p => `- ${p}`).join('\n');
}
// ── PromptAssembler ──────────────────────────────────────────────────
interface Section {
name: string;
body: string;
/** Frames contributed (for debug.framesUsed accounting on trim). */
frameCount: number;
}
export class PromptAssembler {
assemble(input: AssembleInput, opts: AssembleOptions = {}): AssembledPrompt {
const maxChars = opts.maxSystemChars ?? DEFAULT_MAX_CHARS;
const confThreshold = opts.confidenceThreshold ?? DEFAULT_CONFIDENCE_THRESHOLD;
const tier = opts.tierOverride ?? input.tier;
// v5 brief §7.2: default 'compression' preserves the v4 scaffold body.
const scaffoldStyle: ScaffoldStyle = opts.scaffoldStyle ?? 'compression';
// Brief §10: derive task shape from query when caller hasn't supplied one.
const taskShape = opts.taskShape ?? input.taskShape ?? detectTaskShape(input.query);
const frameLimit = FRAME_LIMITS[tier];
const closedWorldRewrite = isClosedWorldRewriteRequest(input.query);
const sections: Section[] = [];
// ── Identity (from corePrompt; always first; never trimmed) ──
const identityBody = input.corePrompt.trim();
if (identityBody) {
const prefixed = identityBody.startsWith('# Identity')
? identityBody
: `# Identity\n${identityBody}`;
sections.push({ name: 'Identity', body: prefixed, frameCount: 0 });
}
// ── Persona (never trimmed) ──
if (input.persona) {
sections.push({ name: 'Persona', body: renderPersona(input.persona), frameCount: 0 });
}
// ── State (I-frames) — trimmable ──
const stateFrames = closedWorldRewrite ? [] : selectFrames(input.context.stateFrames, frameLimit);
if (stateFrames.length > 0) {
sections.push({
name: 'State',
body: `# State\n${renderFrames(stateFrames)}`,
frameCount: stateFrames.length,
});
}
// ── Recent changes (P/B-frames) — trimmable first ──
const changeFrames = closedWorldRewrite ? [] : selectFrames(input.context.recentChanges, frameLimit);
if (changeFrames.length > 0) {
sections.push({
name: 'Recent changes',
body: `# Recent changes\n${renderFrames(changeFrames)}`,
frameCount: changeFrames.length,
});
}
// ── Active work (awareness items) — trimmable ──
if (!closedWorldRewrite && input.context.activeWork.length > 0) {
sections.push({
name: 'Active work',
body: `# Active work\n${renderActiveWork(input.context.activeWork)}`,
frameCount: 0,
});
}
// ── Personal preferences (never trimmed) ──
if (input.context.personalPreferences.length > 0) {
sections.push({
name: 'Personal preferences',
body: `# Personal preferences\n${renderPreferences(input.context.personalPreferences)}`,
frameCount: 0,
});
}
// ── Recalled memory — only when the upstream injection scan passed ──
// Brief §8: recallMemory already scans; assembler must not re-scan, and
// must ignore recall entirely when scanSafe is false.
const recalledFrames: RecallFrame[] = [];
if (!closedWorldRewrite && input.recalled.scanSafe && input.recalled.renderedText) {
// W4.5: pre-rendered multi-lane block — carries its own header
// ('# Recalled Memories' + provenance + temporal guidance). Subject
// to the same overall char budget as every other section.
sections.push({
name: 'Recalled memory',
body: input.recalled.renderedText,
frameCount: 0,
});
} else if (!closedWorldRewrite && input.recalled.scanSafe) {
recalledFrames.push(
...selectFrames(input.recalled.workspace, frameLimit),
...selectFrames(input.recalled.personal, frameLimit),
);
}
if (recalledFrames.length > 0) {
sections.push({
name: 'Recalled memory',
body: `# Recalled memory\n${renderFrames(recalledFrames)}`,
frameCount: recalledFrames.length,
});
}
// ── Response format (scaffold) — gated ──
const candidateScaffold = selectScaffold(tier, taskShape, confThreshold, scaffoldStyle);
const exclusiveResponseContract = opts.exclusiveResponseContract === true;
const scaffold = exclusiveResponseContract || closedWorldRewrite || candidateScaffold === null
? null
: `${DEFAULT_SCAFFOLD_QUALIFIER} ${candidateScaffold}`;
const scaffoldSuppressed = (exclusiveResponseContract || closedWorldRewrite)
&& candidateScaffold !== null;
if (scaffold) {
sections.push({
name: 'Response format',
body: `# Response format\n${scaffold}`,
frameCount: 0,
});
}
if (closedWorldRewrite) {
sections.push({
name: 'Closed-world rewrite',
body: CLOSED_WORLD_REWRITE_CONTRACT,
frameCount: 0,
});
}
// ── Compose + truncate ──
const join = (s: Section[]): string => s.map(x => x.body).join('\n\n');
let system = join(sections);
if (system.length > maxChars) {
for (const trimName of TRUNCATION_ORDER) {
if (system.length <= maxChars) break;
const idx = sections.findIndex(s => s.name === trimName);
if (idx < 0) continue;
sections.splice(idx, 1);
system = join(sections);
}
}
const sectionsIncluded = sections.map(s => s.name);
const framesUsed = sections.reduce((sum, s) => sum + s.frameCount, 0);
// H-AUDIT-1: log assembled-prompt shape. Cheap, high-signal — ties the
// turnId to the exact prompt shape that went to the LLM.
logTurnEvent(opts.turnId, {
stage: 'prompt-assembler.assemble',
tier,
taskShape: taskShape?.type ?? null,
scaffoldApplied: scaffold !== null,
exclusiveResponseContract,
scaffoldSuppressed,
closedWorldRewrite,
scaffoldStyle,
sectionsIncluded,
framesUsed,
totalChars: system.length,
});
return {
system,
userPrefix: '',
responseScaffold: scaffold,
debug: {
tier,
taskShape: taskShape?.type ?? null,
taskShapeConfidence: taskShape?.confidence ?? 0,
scaffoldApplied: scaffold !== null,
exclusiveResponseContract,
scaffoldSuppressed,
closedWorldRewrite,
scaffoldStyle,
sectionsIncluded,
framesUsed,
totalChars: system.length,
},
};
}
}