pi-ui-extend 0.1.1

package/external/pi-tools-suite/src/compress/index.ts

@@ -0,0 +1,397 @@
+// ---------------------------------------------------------------------------
+// Dynamic Context Pruning (DCP) — module entry point for pi-tools-suite
+// ---------------------------------------------------------------------------
+
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent"
+import { loadConfig } from "./config.js"
+import {
+	createState,
+	resetState,
+	createInputFingerprint,
+	serializeState,
+	restoreState,
+	type DcpState,
+} from "./state.js"
+import {
+	SYSTEM_PROMPT,
+	MANUAL_MODE_SYSTEM_PROMPT,
+	CONTEXT_LIMIT_NUDGE_STRONG,
+	CONTEXT_LIMIT_NUDGE_SOFT,
+	TURN_NUDGE,
+	ITERATION_NUDGE,
+} from "./prompts.js"
+import {
+	applyPruning,
+	injectNudge,
+	getNudgeType,
+	detectCompressionCandidate,
+	detectMessageCompressionCandidates,
+	appendConcreteNudgeGuidance,
+	applyAnchoredNudges,
+	nudgeTypeLabel,
+	upsertNudgeAnchor,
+	getActiveSummaryTokenEstimate,
+	resolveContextThresholds,
+	estimateTokens,
+} from "./pruner.js"
+import type { DcpNudgeType } from "./pruner-types.js"
+import { registerCompressTool } from "./compress-tool.js"
+import { registerCommands } from "./commands.js"
+import { DcpUiController, normalizeDcpContextUsage } from "./ui.js"
+import { registerTuiFilter } from "./dcp-tui-filter.js"
+import { ignoreStaleExtensionContextError, safeGetContextUsage } from "../context-usage.js"
+
+const DCP_CONTEXT_USAGE_EVENT = "pi-tools-suite:dcp-context-usage"
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Persist the current DCP runtime state as a custom session entry so it
+ * survives session restarts and pi process restarts.
+ */
+function saveState(pi: ExtensionAPI, state: DcpState): void {
+	pi.appendEntry("dcp-state", serializeState(state))
+}
+
+function annotateMessagesWithBranchEntryIds(messages: any[], ctx: ExtensionContext): void {
+	let branch: any[] = []
+	try {
+		branch = ctx.sessionManager.getBranch()
+	} catch {
+		return
+	}
+
+	const entries = branch.filter((entry) => entry?.type === "message" && entry.message)
+	let searchFrom = 0
+	for (const msg of messages) {
+		for (let i = searchFrom; i < entries.length; i++) {
+			const entry = entries[i]
+			const entryMsg = entry.message
+			if (entryMsg?.role !== msg?.role) continue
+			if (
+				Number.isFinite(entryMsg?.timestamp) &&
+				Number.isFinite(msg?.timestamp) &&
+				entryMsg.timestamp !== msg.timestamp
+			) continue
+			msg._dcpEntryId = entry.id
+			searchFrom = i + 1
+			break
+		}
+	}
+}
+
+function baseNudgeText(type: DcpNudgeType): string {
+	if (type === "context-strong") return CONTEXT_LIMIT_NUDGE_STRONG
+	if (type === "context-soft") return CONTEXT_LIMIT_NUDGE_SOFT
+	if (type === "iteration") return ITERATION_NUDGE
+	return TURN_NUDGE
+}
+
+// ---------------------------------------------------------------------------
+// Module export
+// ---------------------------------------------------------------------------
+
+export default async function dcpModule(pi: ExtensionAPI): Promise<void> {
+	// ── 1. Load config ────────────────────────────────────────────────────────
+	const config = loadConfig(process.cwd())
+
+	if (!config.enabled) return
+
+	// ── 2. Create state ───────────────────────────────────────────────────────
+	const state = createState()
+	const ui = new DcpUiController(state)
+	const updateUi = (ctx: ExtensionContext): void => {
+		try {
+			if (!ctx?.hasUI) return
+			ui.setUICtx(ctx.ui)
+			ui.update(ctx)
+		} catch (error) {
+			ignoreStaleExtensionContextError(error)
+		}
+	}
+	const emitContextUsage = (ctx: ExtensionContext): void => {
+		const usage = safeGetContextUsage(ctx)
+		if (!usage) return
+		try {
+			;(pi as { events?: { emit?: (name: string, data: unknown) => void } }).events?.emit?.(DCP_CONTEXT_USAGE_EVENT, usage)
+		} catch (error) {
+			ignoreStaleExtensionContextError(error)
+		}
+	}
+	const appendNudgeTelemetry = (
+		type: DcpNudgeType,
+		anchor: { id: number; anchorTimestamp: number; anchorStableId?: string; anchorRole: string },
+		usage: ReturnType<typeof normalizeDcpContextUsage>,
+		toolCallsSinceLastUser: number,
+	): void => {
+		try {
+			pi.appendEntry("dcp-nudge", {
+				event: "emitted",
+				type,
+				label: nudgeTypeLabel(type),
+				anchorId: anchor.id,
+				anchorTimestamp: anchor.anchorTimestamp,
+				anchorStableId: anchor.anchorStableId,
+				anchorRole: anchor.anchorRole,
+				contextTokens: usage?.tokens,
+				contextWindow: usage?.contextWindow,
+				contextPercent: usage?.percent,
+				toolCallsSinceLastUser,
+				createdAt: Date.now(),
+			})
+		} catch {
+			// Telemetry is diagnostic only; never block context construction.
+		}
+	}
+
+	// Apply config baseline for manual mode before any session events fire.
+	if (config.manualMode.enabled) {
+		state.manualMode = true
+	}
+
+	// ── 3. Register TUI filter (strip DCP tags from displayed messages) ───────
+	registerTuiFilter(pi)
+
+	// ── 4. Register compress tool ─────────────────────────────────────────────
+	registerCompressTool(pi, state, config)
+
+	// ── 5. Register /dcp commands ─────────────────────────────────────────────
+	registerCommands(pi, state, config, {
+		onStateChanged(ctx) {
+			updateUi(ctx)
+		},
+	})
+
+	// ── 6. session_start: restore state from session entries ──────────────────
+	pi.on("session_start", async (_event, ctx) => {
+		// Reset to a clean slate first.
+		resetState(state)
+
+		// Re-apply config baseline so manual mode survives a session_start reset.
+		if (config.manualMode.enabled) {
+			state.manualMode = true
+		}
+
+		// Walk the branch looking for the most-recent persisted dcp-state entry.
+		let latestDcpState: unknown
+		for (const entry of ctx.sessionManager.getBranch()) {
+			if (entry.type === "custom" && entry.customType === "dcp-state") {
+				latestDcpState = entry.data
+			}
+		}
+
+		restoreState(state, latestDcpState)
+
+		// Show a rich status indicator + floating cleaned-context widget in the pi TUI.
+		updateUi(ctx)
+	})
+
+	// ── 7. session_shutdown: save state ───────────────────────────────────────
+	pi.on("session_shutdown", async (_event, _ctx) => {
+		saveState(pi, state)
+		ui.dispose()
+	})
+
+	// ── 8. before_agent_start: inject system prompt ───────────────────────────
+	pi.on("before_agent_start", async (event, _ctx) => {
+		const promptAddition = state.manualMode
+			? MANUAL_MODE_SYSTEM_PROMPT
+			: SYSTEM_PROMPT
+
+		return {
+			systemPrompt: event.systemPrompt + "\n\n" + promptAddition,
+		}
+	})
+
+	// ── 9. tool_call: record input args for dedup / purge fingerprinting ───────
+	pi.on("tool_call", async (event, _ctx) => {
+		if (!state.toolCalls.has(event.toolCallId)) {
+			state.toolCalls.set(event.toolCallId, {
+				toolCallId: event.toolCallId,
+				toolName: event.toolName,
+				inputArgs: event.input as Record<string, unknown>,
+				inputFingerprint: createInputFingerprint(
+					event.toolName,
+					event.input as Record<string, unknown>,
+				),
+				isError: false,
+				turnIndex: state.currentTurn,
+				timestamp: 0,
+				tokenEstimate: 0,
+			})
+		}
+	})
+
+	// ── 10. tool_result: finalise tool record with result info ─────────────────
+	pi.on("tool_result", async (event, ctx) => {
+		const record = state.toolCalls.get(event.toolCallId)
+
+		const outputText = event.content
+			.map((c: any) => (c.type === "text" ? c.text : ""))
+			.join("")
+		const tokenEstimate = estimateTokens(outputText)
+
+		if (record) {
+			record.isError = event.isError
+			record.timestamp = Date.now()
+			record.tokenEstimate = tokenEstimate
+			record.outputText = outputText
+			record.outputDetails = event.details
+		} else {
+			state.toolCalls.set(event.toolCallId, {
+				toolCallId: event.toolCallId,
+				toolName: event.toolName,
+				inputArgs: {},
+				inputFingerprint: createInputFingerprint(event.toolName, {}),
+				isError: event.isError,
+				turnIndex: state.currentTurn,
+				timestamp: Date.now(),
+				tokenEstimate,
+				outputText,
+				outputDetails: event.details,
+			})
+		}
+
+		if (event.toolName === "compress" && ctx.hasUI) {
+			updateUi(ctx)
+			emitContextUsage(ctx)
+		}
+	})
+
+	// ── 11. context: apply pruning and inject nudges ──────────────────────────
+	pi.on("context", async (event, ctx) => {
+		annotateMessagesWithBranchEntryIds(event.messages, ctx)
+		let prunedMessages = applyPruning(event.messages, state, config)
+		let candidate = null as ReturnType<typeof detectCompressionCandidate>
+		let messageCandidates = [] as ReturnType<typeof detectMessageCompressionCandidates>
+
+		// In manual mode we still apply pruning strategies (if
+		// automaticStrategies is on) but skip routine autonomous nudges. Emergency
+		// max-context nudges are still allowed, matching the manual-mode prompt.
+		const usage = normalizeDcpContextUsage(safeGetContextUsage(ctx))
+		if (usage) {
+			const contextPercent = typeof usage.percent === "number" && Number.isFinite(usage.percent)
+				? usage.percent / 100
+				: typeof usage.tokens === "number"
+					? usage.tokens / usage.contextWindow
+					: undefined
+
+			if (contextPercent === undefined) {
+				if (state.manualMode) {
+					state.nudgeAnchors = state.nudgeAnchors.filter((anchor) =>
+						anchor.type === "context-strong" || anchor.type === "context-soft",
+					)
+				}
+				applyAnchoredNudges(prunedMessages, state, (anchor) =>
+					appendConcreteNudgeGuidance(baseNudgeText(anchor.type), candidate, messageCandidates, state),
+				)
+				updateUi(ctx)
+				emitContextUsage(ctx)
+				return { messages: prunedMessages }
+			}
+
+			const ctxModel = (ctx as any).model
+			const provider = ctxModel?.provider ?? ctxModel?.providerId ?? ctxModel?.providerID
+			const model = ctxModel?.id ?? ctxModel?.model ?? ctxModel?.modelId ?? ctxModel?.modelID
+			const thresholds = resolveContextThresholds(config, [
+				provider && model ? `${provider}/${model}` : undefined,
+				model,
+			], usage.contextWindow)
+			if (config.compress.summaryBuffer) {
+				thresholds.maxContextPercent += getActiveSummaryTokenEstimate(state) / usage.contextWindow
+			}
+
+			let toolCallsSinceLastUser = 0
+			for (let i = prunedMessages.length - 1; i >= 0; i--) {
+				const msg = prunedMessages[i] as any
+				if (msg.role === "user") break
+				if (msg.role === "toolResult") toolCallsSinceLastUser++
+			}
+
+			const nudgeType = getNudgeType(
+				contextPercent,
+				state,
+				config,
+				toolCallsSinceLastUser,
+				thresholds,
+			)
+
+			const manualEmergencyOnly =
+				state.manualMode &&
+				(nudgeType !== "context-strong" && nudgeType !== "context-soft")
+
+			candidate = detectCompressionCandidate(
+				prunedMessages,
+				state,
+				config,
+				contextPercent,
+			)
+			messageCandidates = detectMessageCompressionCandidates(
+				prunedMessages,
+				config,
+				contextPercent,
+			)
+
+			if (nudgeType && !manualEmergencyOnly) {
+				const nudgeText = appendConcreteNudgeGuidance(
+					baseNudgeText(nudgeType),
+					candidate,
+					messageCandidates,
+					state,
+				)
+
+				const anchorResult = upsertNudgeAnchor(
+					prunedMessages,
+					state,
+					nudgeType,
+					{ contextPercent },
+				)
+				if (anchorResult.anchor) {
+					if (anchorResult.updated) {
+						appendNudgeTelemetry(nudgeType, anchorResult.anchor, usage, toolCallsSinceLastUser)
+						saveState(pi, state)
+					}
+				} else {
+					// No safe existing message could be anchored (rare); keep the older
+					// synthetic reminder fallback so DCP never silently drops a nudge.
+					injectNudge(prunedMessages, nudgeText)
+				}
+				state.nudgeCounter = 0
+				state.lastNudgeTurn = state.currentTurn
+			} else {
+				state.nudgeCounter++
+			}
+		}
+
+		if (state.manualMode) {
+			state.nudgeAnchors = state.nudgeAnchors.filter((anchor) =>
+				anchor.type === "context-strong" || anchor.type === "context-soft",
+			)
+		}
+		applyAnchoredNudges(prunedMessages, state, (anchor) =>
+			appendConcreteNudgeGuidance(baseNudgeText(anchor.type), candidate, messageCandidates, state),
+		)
+
+
+		// Update footer status and floating widget after each context event.
+		updateUi(ctx)
+		emitContextUsage(ctx)
+
+		return { messages: prunedMessages }
+	})
+
+	// ── 12. turn_end: refresh DCP status from Pi's final context percentage ───
+	pi.on("turn_end", async (_event, ctx) => {
+		updateUi(ctx)
+		emitContextUsage(ctx)
+	})
+
+	// ── 13. agent_end: persist state after each agent run ────────────────────
+	pi.on("agent_end", async (_event, ctx) => {
+		updateUi(ctx)
+		emitContextUsage(ctx)
+		saveState(pi, state)
+	})
+}

package/external/pi-tools-suite/src/compress/prompts.ts

@@ -0,0 +1,269 @@
+// ---------------------------------------------------------------------------
+// Dynamic Context Pruning (DCP) — PI extension prompts
+// ---------------------------------------------------------------------------
+// All prompt text is exported as plain strings so the extension index can
+// reference them by name without executing any logic here.
+// ---------------------------------------------------------------------------
+
+/**
+ * Appended to the existing system prompt when DCP is enabled (automatic mode).
+ */
+export const SYSTEM_PROMPT = `
+You operate in a context-constrained environment. Manage context continuously to avoid buildup and preserve retrieval quality. Efficient context management is paramount for your agentic performance.
+
+The ONLY tool you have for context management is \`compress\`. It replaces older conversation content with technical summaries you produce. It supports both range compression (\`ranges\`) and surgical one-message compression (\`messages\`).
+
+\`[dcp-id]: # (mNNN)\` markdown reference lines and \`<dcp-system-reminder>\` tags are environment-injected metadata. Do not output them.
+
+THE PHILOSOPHY OF COMPRESS
+\`compress\` transforms conversation content into dense, high-fidelity summaries. This is cleanup plus preservation: keep the state needed to continue, discard incidental transcript detail.
+
+Think of compression as phase transitions: raw exploration becomes refined understanding. The original context served its purpose; your summary now carries that understanding forward.
+
+OPERATING STANCE
+Prefer short, closed, summary-safe compressions.
+When multiple independent stale sections exist, prefer several focused compressions (in parallel when possible) over one broad compression.
+When one older message is huge but the surrounding context is still useful, use message-mode compression for that single message instead of compressing a broad range.
+Summaries should be proportional to future usefulness, not proportional to the amount of text being removed.
+
+Use \`compress\` as steady housekeeping while you work. After any completed implementation + verification slice, compress that closed slice before replying or starting a new task unless the next step needs exact raw logs/diffs. Do not carry large stale tool outputs across task boundaries.
+
+When a \`<dcp-system-reminder>\` appears, treat it as an active instruction for the next safe action, not as background advice. Before making another exploratory tool call or starting a new subtask, check whether any earlier slice is closed; if yes, call \`compress\` first. Do not merely acknowledge the reminder or postpone it across multiple tool calls.
+
+CADENCE, SIGNALS, AND LATENCY
+
+- No fixed threshold mandates compression
+- Prioritize closedness and independence over raw size
+- Prefer smaller, regular compressions over infrequent massive compressions for better latency and summary quality
+- When multiple independent stale sections are ready, batch compressions in parallel
+
+COMPRESS WHEN
+
+A section is genuinely closed and the raw conversation has served its purpose:
+
+- Research concluded and findings are clear
+- Implementation finished and verified
+- Exploration exhausted and patterns understood
+- Dead-end noise can be discarded without waiting for a whole chapter to close
+
+DO NOT COMPRESS IF
+
+- Raw context is still relevant and needed for edits or precise references
+- The target content is still actively in progress
+- You may need exact code, error messages, or file contents in the immediate next steps
+
+Before compressing, ask: _"Is this section closed enough to become summary-only right now?"_
+
+Evaluate conversation signal-to-noise REGULARLY. Use \`compress\` deliberately with quality-first summaries. Prioritize stale content intelligently to maintain a high-signal context window that supports your agency.
+
+It is your responsibility to keep a sharp, high-quality context window for optimal performance.
+`.trim()
+
+/**
+ * Used as the \`description\` field when registering the \`compress\` tool.
+ *
+ * Tool signature:
+ *   {
+ *     topic:  string           // 3-5 word label for this compression
+ *     ranges: Array<{
+ *       startId: string        // mNNN or bN
+ *       endId:   string        // mNNN or bN
+ *       summary: string        // continuation-focused technical summary
+ *     }>
+ *   }
+ */
+export const COMPRESS_RANGE_DESCRIPTION = `Collapse one or more ranges of the conversation into detailed summaries.
+
+AUTONOMOUS HOUSEKEEPING
+Do not wait for context emergencies. After a completed implementation + verification slice, compress that closed slice before replying or starting a new task unless the next step needs exact raw logs/diffs. Do not carry large stale tool outputs across task boundaries.
+
+DCP REMINDERS
+If a \`<dcp-system-reminder>\` is present in context, treat it as a direct instruction to evaluate compression immediately. If a safe closed range exists, call this tool before further exploration. Skipping compression is acceptable only when the newest raw context is still needed for the next concrete edit, test, or answer.
+
+THE SUMMARY
+Your summary must be COMPLETE FOR CONTINUATION, not a transcript rewrite. Preserve only information that will plausibly matter later: user intent, accepted constraints, decisions, files/symbols changed or inspected, exact errors that are still actionable, verification status, and next steps.
+
+Default to a compact structured summary (roughly 5-15 bullets for a normal completed work slice). Grow beyond that only when the compressed range contains multiple independent decisions, unresolved blockers, or precise state that is genuinely required to continue.
+
+Do not copy long raw code, JSON, diffs, logs, or tool output into summaries. Prefer semantic descriptions such as “updated foo.json so scene_assets_1.zai-svg has maxConcurrentRuns set to 5.” Include exact snippets only when the literal text is required for safe continuation, and keep them short and single-line.
+
+SUMMARY ARGUMENT SAFETY
+The summary is passed as a JSON string argument to the compress tool. Avoid raw double-quoted JSON fragments, multiline object literals, and diff hunks because they can make tool-call arguments malformed. If a literal field name matters, prefer plain prose or quote-light code spans such as \`maxConcurrentRuns: 5\` instead of raw \`"maxConcurrentRuns": 5\` blocks.
+
+USER INTENT FIDELITY
+When the compressed range includes user messages, preserve the user's intent with extra care. Do not change scope, constraints, priorities, acceptance criteria, or requested outcomes.
+Directly quote user messages when they are short enough to include safely. Direct quotes are preferred when they best preserve exact meaning.
+
+Be LEAN. Strip away the noise: failed attempts that led nowhere, verbose tool outputs, back-and-forth exploration, and incidental line-by-line edit history. What remains should be pure signal with enough detail to resume work confidently.
+
+TWO COMPRESSION MODES
+You may use either or both modes in one call:
+
+- \`ranges\`: collapse contiguous conversation spans using \`startId\`, \`endId\`, and \`summary\`.
+- \`messages\`: collapse individual raw messages using \`messageId\`, optional \`topic\`, and \`summary\`.
+
+Use \`messages\` for a single large stale message when surrounding messages should remain raw. \`messages\` accepts only raw \`mNNN\` IDs, not \`bN\` compressed block IDs.
+
+PROTECTED PROMPT CONTENT
+If selected user text contains \`<protect>...</protect>\` content, preserve that protected content verbatim in your summary. The tool may append protected text automatically, but you should still account for it semantically.
+
+COMPRESSED BLOCK PLACEHOLDERS
+When the selected range includes previously compressed blocks, use this exact placeholder format when referencing one:
+
+- \`(bN)\`
+
+Compressed block sections in context are clearly marked with a header:
+
+- \`[Compressed conversation section]\`
+
+Compressed block IDs always use the \`bN\` form (never \`mNNN\`) and are represented as hidden markdown reference metadata lines.
+
+Rules:
+
+- Include every required block placeholder exactly once when you intentionally roll up older compressed blocks. If you omit one or duplicate one, the tool will try to recover by preserving the missing block summaries automatically, but do not rely on that recovery path.
+- Do not invent placeholders for blocks outside the selected range.
+- Treat \`(bN)\` placeholders as RESERVED TOKENS. Do not emit \`(bN)\` text anywhere except intentional placeholders.
+- If you need to mention a block in prose, use plain text like \`compressed bN\` (not as a placeholder).
+- Preflight check before finalizing: the set of \`(bN)\` placeholders in your summary should match the required set, with no duplicates.
+
+These placeholders are semantic references. They will be replaced with the full stored compressed block content when the tool processes your output.
+
+FLOW PRESERVATION WITH PLACEHOLDERS
+When you use compressed block placeholders, write the surrounding summary text so it still reads correctly AFTER placeholder expansion.
+
+- Treat each placeholder as a stand-in for a full conversation segment, not as a short label.
+- Ensure transitions before and after each placeholder preserve chronology and causality.
+- Do not write text that depends on the placeholder staying literal (for example, "as noted in \`(b2)\`").
+- Your final meaning must be coherent once each placeholder is replaced with its full compressed block content.
+
+BOUNDARY IDS
+You specify boundaries by ID using the injected metadata IDs present in the conversation context:
+
+- \`mNNN\` IDs identify raw messages (3 digits, zero-padded, e.g. \`m001\`, \`m042\`)
+- \`bN\` IDs identify previously compressed blocks
+
+Each message has an ID in a hidden single-line markdown reference metadata line like \`[dcp-id]: # (m001)\`.
+Some message-compression candidate hints include a low/medium/high priority; prefer high-priority stale message IDs for message-mode compression when a full range would be too broad.
+The ID reference line appears at the end of the message it belongs to — it identifies the message above it, not the one below it.
+Treat these reference lines as boundary metadata only, not as tool result content.
+
+Rules:
+
+- Pick \`startId\` and \`endId\` directly from injected IDs in context.
+- IDs must exist in the current conversation context.
+- \`startId\` must appear before \`endId\`.
+- Do not invent IDs. Use only IDs that are present in context.
+
+BATCHING
+When multiple independent ranges or individual messages are ready, include all of them in one \`compress\` call. Range entries must not overlap. Message entries should each summarize exactly one raw message.`
+
+/**
+ * Injected into messages when context usage exceeds maxContextPercent.
+ * nudgeForce = "strong" — emergency recovery tone.
+ */
+export const CONTEXT_LIMIT_NUDGE_STRONG = `<dcp-system-reminder>
+CRITICAL WARNING: MAX CONTEXT LIMIT REACHED
+
+You are at or beyond the configured max context threshold. This is an emergency context-recovery moment.
+
+You MUST use the \`compress\` tool now. Do not continue normal exploration until compression is handled.
+
+If you are in the middle of a critical atomic operation, finish that atomic step first, then compress immediately.
+
+RANGE STRATEGY (MANDATORY)
+Prioritize one large, closed, high-yield compression range first.
+This overrides the normal preference for many small compressions.
+Only split into multiple compressions if one large range would reduce summary quality or make boundary selection unsafe.
+
+RANGE SELECTION
+Start from older, resolved history and capture as much stale context as safely possible in one pass.
+Avoid the newest active working slice unless it is clearly closed.
+Use injected boundary IDs for compression (\`mNNN\` for messages, \`bN\` for compressed blocks), and ensure \`startId\` appears before \`endId\`.
+For a single large stale message, use the \`messages\` array with its injected \`mNNN\` ID.
+
+SUMMARY REQUIREMENTS
+Your summary must cover all essential details from the selected range so work can continue without reopening raw messages, but it should not restate raw code, JSON, logs, or diffs unless a short literal is required.
+If the compressed range includes user messages, preserve user intent exactly. Prefer direct quotes for short user messages to avoid semantic drift.
+</dcp-system-reminder>`
+
+/**
+ * Injected into messages when context usage exceeds maxContextPercent.
+ * nudgeForce = "soft" — steady housekeeping tone.
+ */
+export const CONTEXT_LIMIT_NUDGE_SOFT = `<dcp-system-reminder>
+ACTION REQUIRED: Context usage is high.
+
+Before doing more exploration, look for a closed, self-contained range that no longer needs to stay raw and compress it now.
+
+Do not treat this as optional housekeeping. If any completed research, implementation, verification, CI-log inspection, or dead-end debugging slice is present, call the \`compress\` tool before continuing normal work.
+
+RANGE SELECTION
+Prefer older, resolved history. Avoid the newest active working slice unless it is clearly done.
+Use injected boundary IDs (\`mNNN\` for messages, \`bN\` for compressed blocks) and ensure \`startId\` appears before \`endId\`.
+For a single large stale message, use message-mode compression via the \`messages\` array.
+
+If multiple independent ranges are ready, batch them in a single \`compress\` call.
+If nothing is cleanly closed yet, continue only with the next atomic step and re-check immediately afterward.
+</dcp-system-reminder>`
+
+/**
+ * Injected as a lightweight reminder between minContextPercent and maxContextPercent
+ * at the configured nudgeFrequency cadence.
+ */
+export const TURN_NUDGE = `<dcp-system-reminder>
+ACTION REQUIRED: Evaluate the conversation for compressible ranges before continuing.
+
+If any range is cleanly closed and unlikely to be needed again, use the \`compress\` tool now.
+If direction has shifted, compress earlier ranges that are now less relevant.
+
+Do not defer this across another batch of searches, reads, CI log fetches, or tests. The next safe action should be compression whenever a closed slice exists.
+
+Prefer small, closed-range compressions over one broad compression.
+Use message-mode compression for isolated large stale messages.
+The goal is to filter noise and distill key information so context accumulation stays under control.
+Keep active context uncompressed.
+</dcp-system-reminder>`
+
+/**
+ * Injected after iterationNudgeThreshold tool calls since the last user message.
+ */
+export const ITERATION_NUDGE = `<dcp-system-reminder>
+ACTION REQUIRED: You've been iterating for a while after the last user message.
+
+Pause before the next non-atomic tool call. If there is a closed portion that is unlikely to be referenced immediately (for example, finished research before implementation, completed CI-log triage, a verified fix, or a dead-end investigation), use the \`compress\` tool on it now.
+
+Do not keep accumulating tool outputs while a completed slice remains raw. If a range is closed, compression is the next safe action.
+
+Prefer multiple short, closed ranges over one large range when several independent slices are ready.
+Use message-mode compression for isolated large stale messages.
+</dcp-system-reminder>`
+
+/**
+ * Replaces SYSTEM_PROMPT when manualMode.enabled = true.
+ * The agent should NOT proactively compress — only compress when explicitly
+ * requested by the user or when a context-limit nudge fires.
+ */
+export const MANUAL_MODE_SYSTEM_PROMPT = `
+You are operating in DCP manual mode for context management.
+
+\`[dcp-id]: # (mNNN)\` markdown reference lines and \`<dcp-system-reminder>\` tags are environment-injected metadata. Do not output them.
+
+In manual mode you do NOT proactively compress conversation content. Compression is a deliberate, user-directed action.
+
+WHEN TO COMPRESS
+- Only when the user explicitly asks you to compress
+- Only when a \`<dcp-system-reminder>\` nudge instructs you to (context-limit emergency)
+- Never as background housekeeping or on your own initiative
+
+WHEN YOU DO COMPRESS
+Apply the same quality standards as always:
+
+- Summaries must be complete for continuation, not transcript-sized; keep only file paths, decisions, findings, exact constraints, unresolved blockers, and verification state that may matter later
+- Avoid raw JSON/code/diff/log blocks in summary strings; describe changes in prose or use very short quote-light code spans when literals are necessary
+- Preserve user intent precisely; prefer direct quotes for short user messages
+- Use only boundary IDs present in context (\`mNNN\` for messages, \`bN\` for compressed blocks)
+- Batch independent ranges in a single \`compress\` call when possible
+- Use message-mode compression for isolated large stale messages when directed by a context-limit nudge
+
+Do not compress active, still-needed context. Only compress ranges that are genuinely closed and whose raw form is no longer required.
+`.trim()