This commit is contained in:
467
packages/agent/src/prompt-assembler.ts
Normal file
467
packages/agent/src/prompt-assembler.ts
Normal file
@@ -0,0 +1,467 @@
|
||||
/**
|
||||
* 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, and Response format are never trimmed.
|
||||
*/
|
||||
|
||||
import type { MemoryFrame, Importance } from '@waggle/core';
|
||||
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: MemoryFrame[];
|
||||
personal: MemoryFrame[];
|
||||
/** 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;
|
||||
/** 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 v4 behavior
|
||||
* byte-identically when unset or explicitly 'compression'.
|
||||
*/
|
||||
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;
|
||||
}
|
||||
|
||||
// ── Constants ────────────────────────────────────────────────────────
|
||||
|
||||
const DEFAULT_MAX_CHARS = 32_000;
|
||||
const DEFAULT_CONFIDENCE_THRESHOLD = 0.3;
|
||||
|
||||
/** 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<Importance, number> = {
|
||||
critical: 4,
|
||||
important: 3,
|
||||
normal: 2,
|
||||
temporary: 1,
|
||||
deprecated: 0,
|
||||
};
|
||||
|
||||
/**
|
||||
* 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<MemoryFrame>, limit: number): MemoryFrame[] {
|
||||
const seen = new Set<number>();
|
||||
const deduped: MemoryFrame[] = [];
|
||||
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.id - a.id;
|
||||
});
|
||||
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);
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
function renderFrames(frames: MemoryFrame[]): 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 v4 behavior byte-identically.
|
||||
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 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 = 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 = 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 (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: MemoryFrame[] = [];
|
||||
if (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 (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 scaffold = selectScaffold(tier, taskShape, confThreshold, scaffoldStyle);
|
||||
if (scaffold) {
|
||||
sections.push({
|
||||
name: 'Response format',
|
||||
body: `# Response format\n${scaffold}`,
|
||||
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,
|
||||
scaffoldStyle,
|
||||
sectionsIncluded,
|
||||
framesUsed,
|
||||
totalChars: system.length,
|
||||
});
|
||||
|
||||
return {
|
||||
system,
|
||||
userPrefix: '',
|
||||
responseScaffold: scaffold,
|
||||
debug: {
|
||||
tier,
|
||||
taskShape: taskShape?.type ?? null,
|
||||
taskShapeConfidence: taskShape?.confidence ?? 0,
|
||||
scaffoldApplied: scaffold !== null,
|
||||
scaffoldStyle,
|
||||
sectionsIncluded,
|
||||
framesUsed,
|
||||
totalChars: system.length,
|
||||
},
|
||||
};
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user