pi-blackhole 0.2.0

package/src/om/agents/dropper/agent.ts

@@ -0,0 +1,204 @@
+/**
+ * Dropper agent — uses agentLoop to propose prunable observations.
+ *
+ * Upstream: https://github.com/elpapi42/pi-observational-memory (src/agents/dropper/agent.ts)
+ * Modified by pi-vcc-om: detects agent_end stopReason="error" in the stream
+ * and throws if the API errored without collecting any drop candidates.
+ */
+import { agentLoop, type AgentContext, type AgentLoopConfig, type AgentTool } from "@earendil-works/pi-agent-core";
+import type { Message, Model, ModelThinkingLevel } from "@earendil-works/pi-ai";
+import { Type } from "@earendil-works/pi-ai";
+import type { Static } from "typebox";
+import { AGENT_LOOP_MAX_TOKENS, boundedMaxTokens } from "../../model-budget.js";
+import { observationToSummaryLine, reflectionToSummaryLine, type Observation, type Reflection } from "../../ledger/index.js";
+import { DROPPER_SYSTEM } from "./prompts.js";
+
+interface RunDropperArgs {
+	model: Model<any>;
+	apiKey: string;
+	headers?: Record<string, string>;
+	reflections: Reflection[];
+	observations: Observation[];
+	/** Compact summary of existing active observations for context. */
+	existingObservationsSummary?: string;
+	budgetTokens: number;
+	signal?: AbortSignal;
+	agentLoop?: typeof agentLoop;
+	maxTurns?: number;
+	thinkingLevel?: ModelThinkingLevel;
+}
+
+const DROP_SKIP_FULLNESS = 0.10;
+const DROP_LOW_URGENCY_FULLNESS = 0.30;
+const DROP_MEDIUM_URGENCY_FULLNESS = 0.60;
+const DROP_MAX_FULLNESS = 1.00;
+const DROP_MIN_RATIO = 0.10;
+const DROP_MAX_RATIO = 0.50;
+
+export type DropUrgency = "low" | "medium" | "high";
+
+const RELEVANCE_DROP_RANK: Record<Observation["relevance"], number> = {
+	low: 0,
+	medium: 1,
+	high: 2,
+	critical: 3,
+};
+
+const DropObservationsSchema = Type.Object({
+	ids: Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }),
+	reason: Type.Optional(Type.String()),
+});
+
+type DropObservationsArgs = Static<typeof DropObservationsSchema>;
+
+function joinOrEmpty(items: string[]): string {
+	return items.length ? items.join("\n") : "(none yet)";
+}
+
+export function observationPoolFullness(observationTokens: number, budgetTokens: number): number {
+	if (!Number.isFinite(observationTokens) || observationTokens <= 0) return 0;
+	if (!Number.isFinite(budgetTokens) || budgetTokens <= 0) return 0;
+	return observationTokens / budgetTokens;
+}
+
+export function dropUrgencyForFullness(fullness: number): DropUrgency {
+	if (fullness < DROP_LOW_URGENCY_FULLNESS) return "low";
+	if (fullness < DROP_MEDIUM_URGENCY_FULLNESS) return "medium";
+	return "high";
+}
+
+export function maxDropCountForPool(observations: readonly Observation[], observationTokens: number, budgetTokens: number): number {
+	const droppableCount = observations.filter((observation) => observation.relevance !== "critical").length;
+	if (droppableCount === 0) return 0;
+
+	const fullness = observationPoolFullness(observationTokens, budgetTokens);
+	if (fullness < DROP_SKIP_FULLNESS) return 0;
+
+	const cappedFullness = Math.min(DROP_MAX_FULLNESS, Math.max(DROP_SKIP_FULLNESS, fullness));
+	const dropRatio = DROP_MIN_RATIO
+		+ ((cappedFullness - DROP_SKIP_FULLNESS) / (DROP_MAX_FULLNESS - DROP_SKIP_FULLNESS))
+		* (DROP_MAX_RATIO - DROP_MIN_RATIO);
+	return Math.max(1, Math.floor(droppableCount * dropRatio));
+}
+
+export function normalizeDropObservationIds(
+	ids: readonly string[] | undefined,
+	observations: readonly Observation[],
+): string[] | undefined {
+	if (!ids || ids.length === 0) return undefined;
+	const allowed = new Map(observations.map((observation) => [observation.id, observation]));
+	const result: string[] = [];
+	const seen = new Set<string>();
+	for (const id of ids) {
+		const observation = allowed.get(id);
+		if (!observation) continue;
+		if (observation.relevance === "critical") continue;
+		if (seen.has(id)) continue;
+		seen.add(id);
+		result.push(id);
+	}
+	return result.length > 0 ? result : undefined;
+}
+
+export function selectDropCandidates(
+	ids: readonly string[],
+	observations: readonly Observation[],
+	maxDrops: number,
+): string[] {
+	if (maxDrops <= 0 || ids.length === 0) return [];
+
+	const byId = new Map(observations.map((observation) => [observation.id, observation]));
+	const firstProposalIndex = new Map<string, number>();
+	for (let i = 0; i < ids.length; i++) {
+		const id = ids[i];
+		if (!firstProposalIndex.has(id)) firstProposalIndex.set(id, i);
+	}
+
+	return Array.from(firstProposalIndex.entries())
+		.map(([id, index]) => ({ id, index, observation: byId.get(id) }))
+		.filter((candidate): candidate is { id: string; index: number; observation: Observation } =>
+			candidate.observation !== undefined && candidate.observation.relevance !== "critical"
+		)
+		.sort((a, b) => {
+			const relevanceDelta = RELEVANCE_DROP_RANK[a.observation.relevance] - RELEVANCE_DROP_RANK[b.observation.relevance];
+			return relevanceDelta || a.index - b.index;
+		})
+		.slice(0, maxDrops)
+		.map((candidate) => candidate.id);
+}
+
+export async function runDropper(args: RunDropperArgs): Promise<string[] | undefined> {
+	const { model, apiKey, headers, reflections, observations, budgetTokens, signal } = args;
+	if (observations.length === 0) return undefined;
+
+	const observationTokens = observations.reduce((sum, observation) => sum + observation.tokenCount, 0);
+	const fullness = observationPoolFullness(observationTokens, budgetTokens);
+	const urgency = dropUrgencyForFullness(fullness);
+	const maxDropsAllowed = maxDropCountForPool(observations, observationTokens, budgetTokens);
+	if (maxDropsAllowed <= 0) return undefined;
+
+	const proposedDropIds: string[] = [];
+	const proposed = new Set<string>();
+
+	const dropObservations: AgentTool<typeof DropObservationsSchema> = {
+		name: "drop_observations",
+		label: "Drop observations",
+		description: "Propose active observation ids that are safe to remove from compacted memory.",
+		parameters: DropObservationsSchema,
+		execute: async (_id, params: DropObservationsArgs) => {
+			const normalized = normalizeDropObservationIds(params.ids, observations) ?? [];
+			let added = 0;
+			for (const id of normalized) {
+				if (proposed.has(id)) continue;
+				proposed.add(id);
+				proposedDropIds.push(id);
+				added++;
+			}
+			return {
+				content: [{ type: "text", text: `Queued ${added} drop candidate${added === 1 ? "" : "s"}. Candidates this run: ${proposedDropIds.length}. Maximum drops allowed: ${maxDropsAllowed}.` }],
+				details: { added, totalCandidates: proposedDropIds.length, maxDropsAllowed },
+			};
+		},
+	};
+
+	const fullnessPercent = Math.round(fullness * 100);
+	const existingObservationsContext = args.existingObservationsSummary
+		? `EXISTING ACTIVE OBSERVATIONS (for context only — these are NOT candidates for dropping):\n${args.existingObservationsSummary}\n\n`
+		: '';
+
+	const userText = `CURRENT REFLECTIONS:\n${joinOrEmpty(reflections.map(reflectionToSummaryLine))}\n\n${existingObservationsContext}NEW OBSERVATIONS TO EVALUATE FOR DROPPING:\n${joinOrEmpty(observations.map(observationToSummaryLine))}\n\nObservation pool pressure: ~${observationTokens.toLocaleString()} tokens; target budget: ~${budgetTokens.toLocaleString()} tokens; fullness: ~${fullnessPercent.toLocaleString()}%.\nDrop urgency: ${urgency}.\nMaximum drops allowed this run: ${maxDropsAllowed.toLocaleString()} observation${maxDropsAllowed === 1 ? "" : "s"}.\nThis maximum is a hard upper bound, not a target. Drop fewer or none if fewer observations are clearly safe.`;
+	const prompts: Message[] = [{ role: "user", content: [{ type: "text", text: userText }], timestamp: Date.now() }];
+	const context: AgentContext = { systemPrompt: DROPPER_SYSTEM, messages: [], tools: [dropObservations as AgentTool<any>] };
+	const reasoning = (model as { reasoning?: unknown }).reasoning;
+	const thinkingLevel = args.thinkingLevel ?? "low";
+	const effectiveMaxTurns = args.maxTurns && args.maxTurns > 0 ? args.maxTurns : undefined;
+	let turnCount = 0;
+	const config: AgentLoopConfig = {
+		model,
+		apiKey,
+		headers,
+		maxTokens: boundedMaxTokens(model, AGENT_LOOP_MAX_TOKENS),
+		convertToLlm: (msgs) => msgs as Message[],
+		toolExecution: "sequential",
+		...(reasoning && thinkingLevel !== "off" ? { reasoning: thinkingLevel } : {}),
+		...(effectiveMaxTurns !== undefined ? { shouldStopAfterTurn: () => ++turnCount >= effectiveMaxTurns } : {}),
+	};
+
+	const loop = args.agentLoop ?? agentLoop;
+	const stream = loop(prompts, context, config, signal);
+	let agentError: string | undefined;
+	for await (const event of stream) {
+		// Tool execution collects candidate ids.
+		if (event.type === "agent_end") {
+			const msgs = ((event as any).messages || []) as Array<{ stopReason?: string; errorMessage?: string }>;
+			const lastMsg = msgs[msgs.length - 1];
+			if (lastMsg?.stopReason === "error") {
+				agentError = lastMsg.errorMessage ?? "Unknown API error";
+			}
+		}
+	}
+	await stream.result();
+	if (agentError && proposedDropIds.length === 0) throw new Error(`Dropper API error: ${agentError}`);
+	const droppedIds = selectDropCandidates(proposedDropIds, observations, maxDropsAllowed);
+	return droppedIds.length > 0 ? droppedIds : undefined;
+}

package/src/om/agents/dropper/prompts.ts

@@ -0,0 +1,48 @@
+export const DROPPER_SYSTEM = `You are the dropper agent for a coding assistant.
+
+These records are the ONLY information the assistant will have about past interactions once the raw conversation is compacted out of context. Dropping the wrong observation can make future work repeat, contradict, or misremember the user. Take this seriously.
+
+Your job is to identify only the safest active observations to remove from compacted memory by calling drop_observations with their ids. Default action is KEEP. When uncertain, keep the observation.
+
+Active-memory framing. Dropping an observation removes it from active compacted memory; it does not erase the ledger history or source evidence. Still, future compressed context will no longer show the observation, so only drop it when its durable meaning is safely captured elsewhere or it is genuinely low-signal and carries no unique future value.
+
+The user message includes drop urgency and "Maximum drops allowed this run". The maximum is a hard upper bound, not a target. Never try to hit it. Drop fewer or none when fewer observations are safely removable.
+
+Urgency guidance:
+- low urgency: only propose trivially safe drops, usually low-signal observations with no unique detail.
+- medium urgency: perform conservative cleanup; prefer low observations and clearly redundant medium observations.
+- high urgency: cleanup is more useful, but preservation rules do not weaken and load-bearing memory must still be kept.
+
+What to drop, in priority order:
+- Redundant observations whose durable meaning is already captured by current reflections with equivalent fidelity.
+- Superseded observations where a later observation clearly replaces the older state.
+- Repeated routine tool acknowledgements or low-signal progress updates that do not carry decisions, constraints, exact errors, or user-specific facts.
+- Older medium observations that no longer carry working context and are covered by a reflection or a newer observation.
+
+Age-gradient rule. Recent observations carry working context the assistant may still need; older observations have usually been summarized elsewhere or are no longer load-bearing. Prefer older safe drops before newer working context.
+
+Relevance guidance:
+- low: consider first, but drop only when it carries no unique detail, decision, state, error, identifier, or user-specific fact.
+- medium: drop when redundant with reflections or other observations, or when the work state is clearly obsolete.
+- high: drop only when clearly superseded or already captured by a reflection with equivalent fidelity.
+- critical: NEVER drop. Code also rejects critical ids, but you must avoid proposing them.
+
+User assertions and concrete completions are never droppable, even at non-critical relevance, unless a current reflection preserves the exact assertion/completion and its important details with equivalent fidelity.
+
+Preservation floor. Regardless of relevance label, urgency, budget pressure, or age, do not drop observations that uniquely carry any of the following:
+- User preferences, constraints, corrections, or identity/role facts.
+- Concrete completions that future runs must not redo.
+- Named identifiers, file paths, function names, package names, tickets, commit SHAs, handles, or exact commands.
+- Exact error messages, diagnostic output, or test failure names.
+- Architectural or technical decisions and their rationale.
+- Dates of specific events, deadlines, meetings, migrations, or incidents.
+- Current unresolved blockers, TODOs, partial work, or decisions waiting on the user.
+- Non-standard user terminology or unusual phrasing needed for future recognition.
+
+What you cannot do:
+- You cannot merge observations.
+- You cannot rewrite or edit observations.
+- You cannot add new observations or reflections.
+- You can only call drop_observations with ids from the current observations list.
+
+Do not force drops you do not believe in. If no observations are safe to drop, do not call the tool and reply briefly. Hitting the budget or maximum count is less important than preserving load-bearing memory.`;

package/src/om/agents/observer/agent.ts

@@ -0,0 +1,256 @@
+/**
+ * Observer agent — uses agentLoop to distill conversation chunks into observations.
+ *
+ * Upstream: https://github.com/elpapi42/pi-observational-memory (src/agents/observer/agent.ts)
+ * Modified by pi-vcc-om: detects agent_end stopReason="error" in the stream
+ * and throws if the API errored without collecting any tool results.
+ * This allows the consolidation pipeline to fall back to alternative models.
+ */
+import { agentLoop, type AgentContext, type AgentLoopConfig, type AgentTool } from "@earendil-works/pi-agent-core";
+import type { Message, Model, ModelThinkingLevel } from "@earendil-works/pi-ai";
+import { Type } from "@earendil-works/pi-ai";
+import type { Static } from "typebox";
+import { hashId } from "../../ids.js";
+import { AGENT_LOOP_MAX_TOKENS, boundedMaxTokens } from "../../model-budget.js";
+import { OBSERVER_SYSTEM } from "./prompts.js";
+import { nowTimestamp, truncateRecordContent } from "../../serialize.js";
+import type { Observation, Relevance } from "../../ledger/index.js";
+import { estimateStringTokens } from "../../tokens.js";
+
+interface RunObserverArgs {
+	model: Model<any>;
+	apiKey: string;
+	headers?: Record<string, string>;
+	priorReflections: string[];
+	priorObservations: string[];
+	chunk: string;
+	allowedSourceEntryIds: string[];
+	signal?: AbortSignal;
+	agentLoop?: typeof agentLoop;
+	maxTurns?: number;
+	thinkingLevel?: ModelThinkingLevel;
+}
+
+const RelevanceSchema = Type.Union([
+	Type.Literal("low"),
+	Type.Literal("medium"),
+	Type.Literal("high"),
+	Type.Literal("critical"),
+]);
+
+export const OBSERVATION_TIMESTAMP_PATTERN = "^[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}$";
+
+const RecordObservationsSchema = Type.Object({
+	observations: Type.Array(
+		Type.Object({
+			timestamp: Type.String({
+				pattern: OBSERVATION_TIMESTAMP_PATTERN,
+				description: "Observation time in local 'YYYY-MM-DD HH:MM' format.",
+			}),
+			content: Type.String({
+				minLength: 1,
+				description: "Single-line plain prose. No markdown, no tags, no embedded timestamp.",
+			}),
+			relevance: RelevanceSchema,
+			sourceEntryIds: Type.Array(
+				Type.String({ minLength: 1 }),
+				{
+					minItems: 1,
+					description:
+						"Exact source entry ids from the chunk that directly support this observation. " +
+						"Use only ids shown in '[Source entry id: ...]' labels; never invent ids.",
+				},
+			),
+		}),
+		{ description: "Batch of new observations. May be empty only if the tool is not called at all." },
+	),
+});
+
+type RecordObservationsArgs = Static<typeof RecordObservationsSchema>;
+
+function joinOrEmpty(items: string[]): string {
+	return items.length ? items.join("\n") : "(none yet)";
+}
+
+export function normalizeSourceEntryIds(
+	sourceEntryIds: readonly string[] | undefined,
+	allowedSourceEntryIds: readonly string[],
+): string[] | undefined {
+	if (!sourceEntryIds || sourceEntryIds.length === 0) return undefined;
+	const allowedOrder = new Map<string, number>();
+	for (let i = 0; i < allowedSourceEntryIds.length; i++) allowedOrder.set(allowedSourceEntryIds[i], i);
+
+	const seen = new Set<string>();
+	for (const id of sourceEntryIds) {
+		if (!allowedOrder.has(id)) return undefined;
+		seen.add(id);
+	}
+	if (seen.size === 0) return undefined;
+	return Array.from(seen).sort((a, b) => (allowedOrder.get(a) ?? 0) - (allowedOrder.get(b) ?? 0));
+}
+
+/** Result returned by runObserver when no observations are recorded. */
+export type ObserverEmptyReason =
+	| { kind: "no_new_content" }           // model ran but nothing worth recording
+	| { kind: "tool_not_called" }          // model didn't call record_observations at all
+	| { kind: "all_rejected"; count: number } // tool called but all sourceEntryIds invalid
+	| { kind: "all_duplicates"; count: number } // tool called but all already seen
+	| { kind: "empty_array"; count: number }; // tool called but returned empty observations array
+
+export interface ObserverResult {
+	observations: Observation[] | undefined;
+	emptyReason?: ObserverEmptyReason;
+}
+
+export async function runObserver(args: RunObserverArgs): Promise<ObserverResult> {
+	const { model, apiKey, headers, priorReflections, priorObservations, chunk, allowedSourceEntryIds, signal } = args;
+	const conversation = chunk.trim();
+	if (!conversation) return { observations: undefined };
+
+	const accumulated = new Map<string, Observation>();
+	let toolCalled = false;
+	let totalAdded = 0;
+	let totalDuplicates = 0;
+	let totalRejected = 0;
+	let totalProposed = 0;
+
+	const recordObservations: AgentTool<typeof RecordObservationsSchema> = {
+		name: "record_observations",
+		label: "Record observations",
+		description:
+			"Record a batch of new observations distilled from the conversation chunk. " +
+			"Call this multiple times as you work through the chunk. Stop calling when coverage is complete, " +
+			"then emit a short plain-text confirmation to end the run.",
+		parameters: RecordObservationsSchema,
+		execute: async (_id, params: RecordObservationsArgs) => {
+			toolCalled = true;
+			let added = 0;
+			let duplicates = 0;
+			let rejected = 0;
+			for (const obs of params.observations) {
+				totalProposed++;
+				const sourceEntryIds = normalizeSourceEntryIds(obs.sourceEntryIds, allowedSourceEntryIds);
+				if (!sourceEntryIds) {
+					rejected++;
+					continue;
+				}
+				const content = truncateRecordContent(obs.content);
+				const id = hashId(content);
+				if (accumulated.has(id)) {
+					duplicates++;
+					continue;
+				}
+				accumulated.set(id, {
+					id,
+					content,
+					timestamp: obs.timestamp,
+					relevance: obs.relevance as Relevance,
+					sourceEntryIds,
+					tokenCount: estimateStringTokens(content),
+				});
+				added++;
+			}
+			totalAdded += added;
+			totalDuplicates += duplicates;
+			totalRejected += rejected;
+			const rejectedPart = rejected > 0
+				? ` ${rejected} observation${rejected === 1 ? "" : "s"} rejected for missing or invalid sourceEntryIds.`
+				: "";
+			const ack =
+				`Recorded ${added} new observation${added === 1 ? "" : "s"} ` +
+				(duplicates > 0 ? `(${duplicates} duplicate${duplicates === 1 ? "" : "s"} skipped).` : ".") +
+				rejectedPart +
+				` Total so far this run: ${accumulated.size}. ` +
+				`Continue if the chunk still has uncovered content; otherwise stop calling the tool and emit a short plain-text confirmation.`;
+			return { content: [{ type: "text", text: ack }], details: { added, duplicates, rejected, total: accumulated.size } };
+		},
+	};
+
+	const now = nowTimestamp();
+	const userText = `Current local time: ${now}
+
+CURRENT REFLECTIONS:
+${joinOrEmpty(priorReflections)}
+
+CURRENT OBSERVATIONS:
+${joinOrEmpty(priorObservations)}
+
+Compress the following new conversation chunk into observations by calling record_observations one or more times. Do not restate facts already present in current reflections or current observations. Prefer inline conversation timestamps when assigning times; fall back to the current local time above only if no message timestamp applies. Stop calling the tool and reply with a short plain-text confirmation once the chunk is fully covered.
+
+NEW CONVERSATION CHUNK:
+${conversation}`;
+
+	const prompts: Message[] = [
+		{
+			role: "user",
+			content: [{ type: "text", text: userText }],
+			timestamp: Date.now(),
+		},
+	];
+
+	const context: AgentContext = {
+		systemPrompt: OBSERVER_SYSTEM,
+		messages: [],
+		tools: [recordObservations as AgentTool<any>],
+	};
+
+	const reasoning = (model as { reasoning?: unknown }).reasoning;
+	const thinkingLevel = args.thinkingLevel ?? "low";
+	const effectiveMaxTurns = args.maxTurns && args.maxTurns > 0 ? args.maxTurns : undefined;
+	let turnCount = 0;
+	const config: AgentLoopConfig = {
+		model,
+		apiKey,
+		headers,
+		maxTokens: boundedMaxTokens(model, AGENT_LOOP_MAX_TOKENS),
+		convertToLlm: (msgs) => msgs as Message[],
+		toolExecution: "sequential",
+		...(reasoning && thinkingLevel !== "off" ? { reasoning: thinkingLevel } : {}),
+		...(effectiveMaxTurns !== undefined
+			? {
+				shouldStopAfterTurn: () => {
+					turnCount++;
+					return turnCount >= effectiveMaxTurns;
+				},
+			}
+			: {}),
+	};
+
+	const loop = args.agentLoop ?? agentLoop;
+	const stream = loop(prompts, context, config, signal);
+	let agentError: string | undefined;
+	for await (const event of stream) {
+		// Drain events; the tool's execute already collects records.
+		if (event.type === "agent_end") {
+			const msgs = ((event as any).messages || []) as Array<{ stopReason?: string; errorMessage?: string }>;
+			const lastMsg = msgs[msgs.length - 1];
+			if (lastMsg?.stopReason === "error") {
+				agentError = lastMsg.errorMessage ?? "Unknown API error";
+			}
+		}
+	}
+	await stream.result();
+
+	if (agentError && accumulated.size === 0) {
+		throw new Error(`Observer API error: ${agentError}`);
+	}
+
+	if (accumulated.size === 0) {
+		// Determine why no observations were recorded
+		let emptyReason: ObserverEmptyReason;
+		if (!toolCalled) {
+			emptyReason = { kind: "tool_not_called" };
+		} else if (totalRejected > 0 && totalAdded === 0) {
+			emptyReason = { kind: "all_rejected", count: totalRejected };
+		} else if (totalDuplicates > 0 && totalAdded === 0) {
+			emptyReason = { kind: "all_duplicates", count: totalDuplicates };
+		} else if (totalProposed === 0) {
+			emptyReason = { kind: "empty_array", count: 0 };
+		} else {
+			emptyReason = { kind: "no_new_content" };
+		}
+		return { observations: undefined, emptyReason };
+	}
+
+	return { observations: Array.from(accumulated.values()) };
+}

package/src/om/agents/observer/prompts.ts

@@ -0,0 +1,119 @@
+export const OBSERVER_SYSTEM = `You are the observation agent for a coding assistant.
+
+These records are the ONLY information the assistant will have about past interactions once the raw conversation is compacted out of context. Anything you do not capture here will be forgotten. Anything you distort here will be remembered wrong. Take this seriously.
+
+Your job is to compress a chunk of recent conversation into timestamped, rated observations by calling the record_observations tool. The observations you emit — together with the reflections crystallized from them — are the assistant's ONLY memory of this session after the raw conversation falls out of context.
+
+You receive:
+- Current reflections (long-lived facts already crystallized).
+- Current observations (already-recorded observations, each shown as "[id] YYYY-MM-DD HH:MM [relevance] content").
+- A new chunk of conversation with source entry labels and inline message timestamps. Each source block starts with "[Source entry id: <id>]" followed by content formatted as "[User @ YYYY-MM-DD HH:MM]:", "[Assistant @ ...]:", "[Tool result for <name> @ ...]:", custom messages, or branch summaries.
+- A current local time fallback for observations that have no obvious message timestamp.
+
+How you work:
+1. Read reflections and current observations so you know what is already captured.
+2. Read the conversation chunk and identify what new information it contains.
+3. Call record_observations with a batch covering part (or all) of the chunk.
+4. Read the progress receipt. If content remains uncovered, call again. You may call the tool many times.
+5. When the chunk is fully covered, STOP calling the tool and reply with a brief plain-text confirmation (one short sentence). That ends the run.
+
+What to emit:
+- Produce NEW observations for the new chunk only. Do not restate facts already present in reflections or current observations unless something has materially changed.
+- Use the timestamp from the relevant conversation message. Fall back to current local time ONLY when no message timestamp applies.
+- For every observation, include sourceEntryIds: the smallest exact set of "[Source entry id: ...]" ids that directly support the observation.
+- Never invent source entry ids. Use only ids printed in the chunk. If an observation spans multiple turns or tool results, include every supporting source entry id.
+- Observations with missing, empty, or invalid sourceEntryIds will be rejected and not recorded, so do not call record_observations until you can cite valid source ids.
+- Group repeated similar tool calls into a single observation rather than one per call.
+- Skip routine, low-information events. It is fine to emit zero observations if the chunk carries no new information — in that case, simply do not call the tool and end with a plain-text confirmation.
+
+Observation content rules:
+
+Format.
+- Single line of plain prose. No markdown, no bullets, no code fences, no XML/HTML tags, no emojis.
+- Do NOT include the timestamp or relevance inside the content string — those are separate fields.
+- No structured fields embedded in the text (no "key: value" lines, no JSON).
+
+Preserve user assertions exactly.
+When the user TELLS you something about themselves, their project, or their environment, capture it as an assertion. When the user ASKS something, capture it as a question. Assertions are authoritative — a later question on the same topic does not invalidate them.
+  BAD:  User wondered if they have two kids.
+  GOOD: User stated they have two kids.
+  BAD:  User discussed auth middleware.
+  GOOD: User asked how to configure JWT auth middleware.
+Why this matters: if the user says "I use Postgres" and later asks "what db am I on?", downstream agents must treat the assertion as the answer, not the question.
+
+Preserve unusual phrasing.
+When the user uses non-standard terminology, quote their exact words so future runs can recognize the term.
+  BAD:  User exercised yesterday.
+  GOOD: User stated they did a "movement session" (their term) yesterday.
+
+Use precise action verbs. Replace vague verbs with ones that clarify the nature of the action.
+  BAD:  User got a new subscription.
+  GOOD: User subscribed to the Pro plan.
+  BAD:  User stopped getting the newsletter.
+  GOOD: User unsubscribed from the newsletter.
+  BAD:  User got the library.
+  GOOD: User installed the zod package via pnpm.
+
+Frame state changes as supersession so the old state is explicit.
+  BAD:  User prefers React Query now.
+  GOOD: User will use React Query (switching from SWR).
+Why this matters: without supersession framing, the reflector may crystallize both the old and the new as equally valid preferences.
+
+Mark concrete completions explicitly.
+Use "completed:", "resolved:", "confirmed working", or similar phrasing so future runs know not to redo the work.
+  BAD:  Wrote the login handler.
+  GOOD: completed: implemented login handler at src/auth/login.ts; user confirmed tests pass.
+Why this matters: without a completion marker, a later assistant may re-implement work that is already done, wasting the user's time and risking regressions.
+
+Split compound statements into separate observations.
+If a single message contains multiple independent facts, intents, or events, emit one observation per fact. One observation per line is what enables downstream retrieval and dropping to operate at fact granularity.
+  BAD:  User will visit their parents this weekend and needs to clean the garage.
+  GOOD: User will visit their parents this weekend. + User stated they need to clean the garage this weekend.
+  BAD:  User started a new job and is moving to a new apartment next week.
+  GOOD: User started a new job. + User will move to a new apartment next week.
+  BAD:  Assistant recommended Lucia, NextAuth, and Clerk for auth, and user chose Lucia.
+  GOOD: Assistant recommended auth libraries: Lucia (session-based, minimal), NextAuth (OAuth-heavy, Next-native), Clerk (hosted, paid). + User chose Lucia.
+Why this matters: a future query like "which auth library did the user pick?" can match a single-fact observation cleanly; a compound observation hides the decision inside a recommendation list.
+
+Group repeated similar tool calls into a single observation rather than one per call.
+  BAD:  Agent viewed src/auth.ts. Agent viewed src/users.ts. Agent viewed src/routes.ts.
+  GOOD: Agent surveyed auth-related files (src/auth.ts, src/users.ts, src/routes.ts) and located token validation in src/auth.ts:45.
+
+Detail preservation. When an observation references specific things, preserve the distinguishing details so future queries can still find them:
+
+- File/location: full path + line number when relevant (src/auth.ts:45, not "the auth file").
+- Identifiers and names: package names, function names, variable names, handles, ticket ids, commit SHAs, error codes. Keep them verbatim.
+- Error messages: quote verbatim.
+    BAD:  Build failed with a type error.
+    GOOD: Build failed: TS2322: Type 'string | undefined' is not assignable to type 'string' at src/auth.ts:47.
+- Numerical results: exact values, units, and direction.
+    BAD:  Optimization made it faster.
+    GOOD: Optimization reduced p95 latency from 420ms to 180ms (57% faster).
+- Quantities and counts: "3 failing tests (auth.test.ts, users.test.ts, routes.test.ts)" not "some failing tests".
+- Recommendation or decision lists: preserve the distinguishing attribute per item.
+    BAD:  Assistant recommended 3 auth libraries.
+    GOOD: Assistant recommended auth libraries: Lucia (session-based, minimal), NextAuth (OAuth-heavy, Next-native), Clerk (hosted, paid).
+- Role / participation: capture the user's role at an event, not just attendance.
+    BAD:  User worked on the migration.
+    GOOD: User led the migration from MySQL to Postgres.
+
+If a detail is non-obvious from the code or git history, it belongs in the observation. If it is trivially re-derivable, it does not.
+
+Relevance levels (pick one per observation; this field drives future dropping):
+
+- critical: user assertions about identity, role, or persistent preferences; explicit corrections ("no, don't do X"); concrete completions that future runs MUST NOT redo. These are load-bearing and will NEVER be dropped. Why this matters: if a "critical" item is lost, the assistant may redo finished work, contradict a correction, or misrepresent who the user is.
+- high: non-trivial technical decisions, architectural direction, unresolved blockers, key constraints. Worth keeping across many compactions.
+- medium: task-level context that helps within the current work but isn't durable. The default when you are unsure between medium and high.
+- low: routine tool-call acks, repetitive status updates, content trivially re-derivable from recent messages. The dropper will drop these first.
+
+Do NOT default to "critical" or "high". Most observations are medium or low. Reserve "critical" for things that would cause real damage if forgotten.
+
+  BAD:  relevance=critical for "Agent ran tests and they passed."
+  GOOD: relevance=low for "Agent ran tests and they passed." (routine; captured by a completion observation if it matters)
+
+  BAD:  relevance=medium for "User said they are colorblind; red/green indicators do not work for them."
+  GOOD: relevance=critical for "User said they are colorblind; red/green indicators do not work for them." (persistent constraint; forgetting it causes real harm)
+
+Timestamp format: "YYYY-MM-DD HH:MM" (local time, 24-hour, to the minute). This goes in the timestamp field, not the content.
+
+Remember: these observations are the assistant's ONLY memory of this chunk once the raw messages fall out of context. Make them count.`;