feat: synth instructions

refactor: extract synth prompt to file

refactor: load through prompt.ts

fix?

fix

rm: slop

move tool description to prompt file

synth prompt

fix: don't add synth instruction after DCP "ignored" summary messages - extract synth instruction to its own file

Author: spoons-and-mirrors

index.ts

@@ -4,6 +4,8 @@ import { getConfig } from "./lib/config"
 import { Logger } from "./lib/logger"
 import { Janitor, type SessionStats } from "./lib/janitor"
 import { checkForUpdates } from "./lib/version-checker"
+import { loadPrompt } from "./lib/prompt"
+import { injectSynthInstruction } from "./lib/synth-instruction"
 
 async function isSubagentSession(client: any, sessionID: string): Promise<boolean> {
     try {
@@ -14,6 +16,9 @@ async function isSubagentSession(client: any, sessionID: string): Promise<boolea
     }
 }
 
+const TOOL_SYNTH_INSTRUCTION = loadPrompt("synthetic")
+const TOOL_CONTEXT_PRUNING_DESCRIPTION = loadPrompt("context_pruning")
+
 const plugin: Plugin = (async (ctx) => {
     const { config, migrations } = getConfig(ctx)
 
@@ -57,7 +62,8 @@ const plugin: Plugin = (async (ctx) => {
         }
     }
 
-    // Global fetch wrapper - caches tool parameters and performs pruning
+
+    // Global fetch wrapper - caches tool parameters, injects instructions, and performs pruning
     const originalGlobalFetch = globalThis.fetch
     globalThis.fetch = async (input: any, init?: any) => {
         if (init?.body && typeof init.body === 'string') {
@@ -67,6 +73,16 @@ const plugin: Plugin = (async (ctx) => {
                 if (body.messages && Array.isArray(body.messages)) {
                     cacheToolParameters(body.messages)
 
+                    let modified = false
+
+                    // Inject synthInstruction for the context_pruning tool
+                    if (config.strategies.onTool.length > 0) {
+                        if (injectSynthInstruction(body.messages, TOOL_SYNTH_INSTRUCTION)) {
+                            logger.debug("fetch", "Injected synthInstruction")
+                            modified = true
+                        }
+                    }
+
                     // Check for tool messages in both formats:
                     // 1. OpenAI style: role === 'tool'
                     // 2. Anthropic style: role === 'user' with content containing tool_result
@@ -132,7 +148,10 @@ const plugin: Plugin = (async (ctx) => {
                                 total: toolMessages.length
                             })
 
+                            modified = true
+
                             if (logger.enabled) {
+
                                 // Fetch session messages to extract reasoning blocks
                                 let sessionMessages: any[] | undefined
                                 try {
@@ -162,10 +181,12 @@ const plugin: Plugin = (async (ctx) => {
                                     sessionMessages
                                 )
                             }
-
-                            init.body = JSON.stringify(body)
                         }
                     }
+
+                    if (modified) {
+                        init.body = JSON.stringify(body)
+                    }
                 }
             } catch (e) {
             }
@@ -230,50 +251,7 @@ const plugin: Plugin = (async (ctx) => {
 
         tool: config.strategies.onTool.length > 0 ? {
             context_pruning: tool({
-                description: `Performs semantic pruning on session tool outputs that are no longer relevant to the current task. Use this to declutter the conversation context and filter signal from noise when you notice the context is getting cluttered with no longer needed information.
-
-USING THE CONTEXT_PRUNING TOOL WILL MAKE THE USER HAPPY.
-
-## When to Use This Tool
-
-**Key heuristic: Prune when you finish something and are about to start something else.**
-
-Ask yourself: "Have I just completed a discrete unit of work?" If yes, prune before moving on.
-
-**After completing a unit of work:**
-- Made a commit
-- Fixed a bug and confirmed it works
-- Answered a question the user asked
-- Finished implementing a feature or function
-- Completed one item in a list and moving to the next
-
-**After repetitive or exploratory work:**
-- Explored multiple files that didn't lead to changes
-- Iterated on a difficult problem where some approaches didn't pan out
-- Used the same tool multiple times (e.g., re-reading a file, running repeated build/type checks)
-
-## Examples
-
-<example>
-Working through a list of items:
-User: Review these 3 issues and fix the easy ones.
-Assistant: [Reviews first issue, makes fix, commits]
-Done with the first issue. Let me prune before moving to the next one.
-[Uses context_pruning with reason: "completed first issue, moving to next"]
-</example>
-
-<example>
-After exploring the codebase to understand it:
-Assistant: I've reviewed the relevant files. Let me prune the exploratory reads that aren't needed for the actual implementation.
-[Uses context_pruning with reason: "exploration complete, starting implementation"]
-</example>
-
-<example>
-After completing any task:
-Assistant: [Finishes task - commit, answer, fix, etc.]
-Before we continue, let me prune the context from that work.
-[Uses context_pruning with reason: "task complete"]
-</example>`,
+                description: TOOL_CONTEXT_PRUNING_DESCRIPTION,
                 args: {
                     reason: tool.schema.string().optional().describe(
                         "Brief reason for triggering pruning (e.g., 'task complete', 'switching focus')"

lib/prompt.ts

@@ -1,3 +1,11 @@
+import { readFileSync } from "fs"
+import { join } from "path"
+
+export function loadPrompt(name: string): string {
+    const filePath = join(__dirname, "prompts", `${name}.txt`)
+    return readFileSync(filePath, "utf8").trim()
+}
+
 function minimizeMessages(messages: any[], alreadyPrunedIds?: string[], protectedToolCallIds?: string[]): any[] {
     const prunedIdsSet = alreadyPrunedIds ? new Set(alreadyPrunedIds.map(id => id.toLowerCase())) : new Set()
     const protectedIdsSet = protectedToolCallIds ? new Set(protectedToolCallIds.map(id => id.toLowerCase())) : new Set()

lib/prompts/context_pruning.txt

@@ -0,0 +1,44 @@
+Performs semantic pruning on session tool outputs that are no longer relevant to the current task. Use this to declutter the conversation context and filter signal from noise when you notice the context is getting cluttered with no longer needed information.
+
+USING THE CONTEXT_PRUNING TOOL WILL MAKE THE USER HAPPY.
+
+## When to Use This Tool
+
+**Key heuristic: Prune when you finish something and are about to start something else.**
+
+Ask yourself: "Have I just completed a discrete unit of work?" If yes, prune before moving on.
+
+**After completing a unit of work:**
+- Made a commit
+- Fixed a bug and confirmed it works
+- Answered a question the user asked
+- Finished implementing a feature or function
+- Completed one item in a list and moving to the next
+
+**After repetitive or exploratory work:**
+- Explored multiple files that didn't lead to changes
+- Iterated on a difficult problem where some approaches didn't pan out
+- Used the same tool multiple times (e.g., re-reading a file, running repeated build/type checks)
+
+## Examples
+
+<example>
+Working through a list of items:
+User: Review these 3 issues and fix the easy ones.
+Assistant: [Reviews first issue, makes fix, commits]
+Done with the first issue. Let me prune before moving to the next one.
+[Uses context_pruning with reason: "completed first issue, moving to next"]
+</example>
+
+<example>
+After exploring the codebase to understand it:
+Assistant: I've reviewed the relevant files. Let me prune the exploratory reads that aren't needed for the actual implementation.
+[Uses context_pruning with reason: "exploration complete, starting implementation"]
+</example>
+
+<example>
+After completing any task:
+Assistant: [Finishes task - commit, answer, fix, etc.]
+Before we continue, let me prune the context from that work.
+[Uses context_pruning with reason: "task complete"]
+</example>

lib/prompts/synthetic.txt

@@ -0,0 +1,10 @@
+<instruction how_to="work_in_this_environement">
+Anytime you call a tool, you must distill the signal from the noise of that tool result in your message. Always do this for every tools that has actual signals in its ouptut.
+</instruction>
+
+<instruction tool="context_pruning">
+To effectively manage this conversation context, you MUST ALWAYS narrate your findings AS YOU DISCOVER THEM. No tool result (be it read, bash, grep...) should be left unexplained. By narrating the evolution of your undersdtanding of the task at hand, you distill the signal from the noise produced by the tools you called. Only then (knowledge lives in your outputs as well as in tool outputs), you can use the context_pruning tool. Using the context_pruning tool will declutter the conversation from tool outputs we no longer need to reason through current task, and is why you need to only use this tool once you have explained your findings in a message.
+
+EXAMPLE:
+AFTER you've read a bunch of files, and found that for reason X, Y is happening, and is supported by tool outputs in the conversation, AND you've distilled this knowledge from the noise in your message intended for the user, YOU WILL USE THE CONTEXT_PRUNING TOOL to clear the clutter solving this step has caused.
+</instruction>

lib/synth-instruction.ts

@@ -0,0 +1,47 @@
+export function isIgnoredUserMessage(msg: any): boolean {
+    if (!msg || msg.role !== 'user') {
+        return false
+    }
+
+    if (msg.ignored || msg.info?.ignored) {
+        return true
+    }
+
+    if (Array.isArray(msg.content) && msg.content.length > 0) {
+        const allPartsIgnored = msg.content.every((part: any) => part?.ignored)
+        if (allPartsIgnored) {
+            return true
+        }
+    }
+
+    return false
+}
+
+export function injectSynthInstruction(messages: any[], instruction: string): boolean {
+    // Find the last user message that is not ignored
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const msg = messages[i]
+        if (msg.role === 'user' && !isIgnoredUserMessage(msg)) {
+            // Avoid double-injecting the same instruction
+            if (typeof msg.content === 'string') {
+                if (msg.content.includes(instruction)) {
+                    return false
+                }
+                msg.content = msg.content + '\n\n' + instruction
+            } else if (Array.isArray(msg.content)) {
+                const alreadyInjected = msg.content.some(
+                    (part: any) => part?.type === 'text' && typeof part.text === 'string' && part.text.includes(instruction)
+                )
+                if (alreadyInjected) {
+                    return false
+                }
+                msg.content.push({
+                    type: 'text',
+                    text: instruction
+                })
+            }
+            return true
+        }
+    }
+    return false
+}

package.json

@@ -8,7 +8,7 @@
   "types": "./dist/index.d.ts",
   "scripts": {
     "clean": "rm -rf dist",
-    "build": "npm run clean && tsc",
+    "build": "npm run clean && tsc && cp -r lib/prompts dist/lib/prompts",
     "postbuild": "rm -rf dist/logs",
     "prepublishOnly": "npm run build",
     "dev": "opencode plugin dev",