From 87dbbedd4bd933968d5aeb15577fd2a3a7eff8bb Mon Sep 17 00:00:00 2001 From: Finessse Date: Fri, 26 Dec 2025 05:08:15 +0700 Subject: [PATCH] feat(middleware): enhance agentic harness prompts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Improve INITIALIZER and CODING prompts based on Anthropic guidance: - Structured feature_list.json format - GET BEARINGS workflow for coding mode - Puppeteer MCP detection for browser testing - Session-aware state detection 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- internal/api/middleware/agentic_harness.go | 352 ++++++++++++++++++--- 1 file changed, 303 insertions(+), 49 deletions(-) diff --git a/internal/api/middleware/agentic_harness.go b/internal/api/middleware/agentic_harness.go index 35009649..5717b210 100644 --- a/internal/api/middleware/agentic_harness.go +++ b/internal/api/middleware/agentic_harness.go @@ -8,12 +8,33 @@ import ( "path/filepath" "strconv" "strings" + "sync" "github.com/gin-gonic/gin" "github.com/tidwall/gjson" "github.com/tidwall/sjson" ) +var ( + harnessEnabledOnce sync.Once + harnessEnabled bool +) + +// isHarnessEnabled checks if the agentic harness is enabled via environment variable. +// Defaults to true if CLIPROXY_HARNESS_ENABLED is not set or is "true"/"1". +func isHarnessEnabled() bool { + harnessEnabledOnce.Do(func() { + val := os.Getenv("CLIPROXY_HARNESS_ENABLED") + if val == "" { + harnessEnabled = true + return + } + val = strings.ToLower(strings.TrimSpace(val)) + harnessEnabled = val == "true" || val == "1" || val == "yes" + }) + return harnessEnabled +} + const ( // Initializer prompt: forces the agent to set up the environment. harnessInitializerPrompt = ` @@ -21,28 +42,85 @@ const ( You are the **Initializer Agent** in a Long-Running Agent Harness. Your ONLY goal is to set up the project environment for future Coding Agents. -**CRITICAL INSTRUCTIONS**: -1. **Analyze the User's Request**: Understand what feature or app needs to be built. -2. **Create 'feature_list.json'**: - - Write a JSON file listing ALL features/requirements as separate items. - - Mark them all as "passes": false. - - Format: - Request: "Build a todo app" - File Content: - [ - { "category": "core", "description": "User can add a todo", "steps": ["Open app", "Enter text", "Press enter", "See new item"], "passes": false }, - { "category": "core", "description": "User can delete a todo", "steps": ["Open app", "Click delete", "Item removed"], "passes": false } - ] -3. **Create 'claude-progress.txt'**: - - Create this file with a header "## Progress Log". - - Add an initial entry: "- [Initializer] Environment setup started." -4. **Create 'init.sh' (Optional)**: - - If a dev server is needed, create a script to start it (e.g., 'npm run dev'). -5. **Initial Commit**: - - Initialize git if not present. - - Commit these foundational files. +## CRITICAL: YOU DO NOT IMPLEMENT FEATURES +Your job is ONLY to scaffold the harness files. Do NOT write any application code. +Do NOT create components, pages, or business logic. Only create the harness metadata files. -**DO NOT** start implementing features yourself. Your job is ONLY to scaffold the harness. +## INSTRUCTIONS + +### 1. Analyze the User's Request +Understand what feature or app needs to be built. Break it down into discrete, testable features. + +### 2. Create 'feature_list.json' +Write a JSON file listing ALL features/requirements as separate items. + +**Required Format:** +{ + "features": [ + { + "id": "feat-001", + "category": "core", + "description": "User can add a todo item", + "steps": [ + "Open the application", + "Enter text in the input field", + "Press Enter or click Add button", + "Verify new item appears in the list" + ], + "passes": false, + "priority": 1 + }, + { + "id": "feat-002", + "category": "core", + "description": "User can delete a todo item", + "steps": [ + "Open the application with existing items", + "Click the delete button on an item", + "Verify item is removed from the list" + ], + "passes": false, + "priority": 2 + } + ] +} + +**Field Descriptions:** +- id: Unique identifier (feat-XXX format) +- category: "core", "enhancement", "ui", "integration", etc. +- description: Clear, testable user-facing behavior +- steps: Exact steps to verify this feature works +- passes: Always false initially +- priority: Lower number = higher priority (implement first) + +### 3. Create 'claude-progress.txt' +Create this file with structured session logging: + +## Progress Log + +### Session: YYYY-MM-DD HH:MM +- [Initializer] Environment setup started. +- [Initializer] Created feature_list.json with N features. +- [Initializer] Created init.sh for development server. + +### 4. Create 'init.sh' (REQUIRED for web apps) +For ANY web application, you MUST create init.sh: +#!/bin/bash +# Start the development server +npm install +npm run dev & +sleep 5 +echo "Dev server started at http://localhost:3000" + +Make it executable and ensure it handles common setup tasks. + +### 5. Initial Commit +- Initialize git if not present. +- Commit these foundational files with message: "chore: initialize agent harness" + +## REMINDER +You are ONLY scaffolding. The Coding Agent will implement features in future turns. +Do NOT write application code. Do NOT create UI components. ONLY create the harness files. ` // Coding prompt: forces the agent to work incrementally. @@ -51,30 +129,80 @@ Your ONLY goal is to set up the project environment for future Coding Agents. You are a **Coding Agent** in a Long-Running Agent Harness. Your goal is to make **incremental progress** on the project. -**WORKFLOW**: -1. **Read Context**: - - Read 'claude-progress.txt' to see what was done last. - - Read 'feature_list.json' to see what is missing. - - Read recent git log to understand recent changes. - - If 'init.sh' exists, run it to start the dev server. - - Run a basic end-to-end sanity check before new work. -2. **Pick ONE Task**: - - Choose the highest-priority failing feature from 'feature_list.json'. - - Announce your plan. -3. **Implement & Verify**: - - Write code for that ONE feature. - - Verify it works end-to-end (tests or browser check). -4. **Update State**: - - Update 'feature_list.json': set "passes": true for the completed feature. - - Append to 'claude-progress.txt': "- [Coding] Implemented ." -5. **Commit**: - - Git commit your changes. +## STEP 1: GET BEARINGS (MANDATORY - DO THIS FIRST) +Before ANY coding, you MUST execute these commands in order: -**RESTRICTIONS**: -- Do NOT try to finish the whole project in one turn. -- Do NOT leave the code in a broken state. -- Always update the harness files ('feature_list.json', 'claude-progress.txt') before stopping. -- Do NOT edit 'feature_list.json' except toggling a feature's "passes" field after verified testing. +1. pwd # Know where you are +2. git log --oneline -5 # See recent changes +3. cat claude-progress.txt # Read what was done before +4. cat feature_list.json # See all features and their status +5. ./init.sh # Start dev server if it exists + +Do NOT skip this step. Do NOT assume you know the project state. + +## STEP 2: SANITY CHECK (MANDATORY) +Before implementing anything new: +- Verify existing features still work +- Check for any regressions from previous changes +- If using Puppeteer MCP, run a quick browser test on the current state +- If something is broken, FIX IT FIRST before new work + +## STEP 3: PICK ONE TASK +- Find the highest-priority feature where "passes": false +- Announce: "I will implement: [feature description]" +- Do NOT pick multiple features + +## STEP 4: IMPLEMENT & VERIFY +- Write code for that ONE feature only +- You MUST verify it works before marking complete +- Verification methods (in order of preference): + 1. **Puppeteer MCP**: Use browser automation to test UI features (STRONGLY PREFERRED) + 2. **Unit/Integration tests**: Run existing test suites + 3. **Manual verification**: Only if automated testing unavailable + +**VERIFICATION IS NOT OPTIONAL.** You must ACTUALLY TEST the feature. +Do NOT mark a feature as passing based on "the code looks correct." + +## STEP 5: UPDATE STATE +After VERIFIED implementation: + +1. Update feature_list.json: + - Set "passes": true ONLY for features you have ACTUALLY VERIFIED + +2. Append to claude-progress.txt: + - [Coding] Implemented : . Verified via . + + Example: + - [Coding] Implemented feat-003: User can mark todo complete. Verified via Puppeteer browser test. + +## STEP 6: COMMIT +- Git commit with descriptive message +- Include feature ID in commit message + +## RESTRICTIONS +- Do NOT try to finish the whole project in one turn +- Do NOT leave the code in a broken state +- Do NOT mark features as "passes": true without ACTUAL verification +- Do NOT edit feature_list.json except to toggle "passes" after verified testing +- ALWAYS update harness files before stopping +` + + // harnessTestingReminder is injected when Puppeteer MCP is detected + harnessTestingReminder = ` +## PUPPETEER MCP DETECTED +You have access to Puppeteer MCP for browser automation testing. + +**YOU MUST USE IT** to verify features. This is not optional. + +Testing workflow: +1. Navigate to the application URL (usually http://localhost:3000 or similar) +2. Take a screenshot to verify the page loaded +3. Interact with UI elements to test the feature +4. Take a screenshot after interaction to verify the result +5. Only mark "passes": true if the browser test confirms it works + +Do NOT rely on "the code looks correct." Run the actual browser test. +If Puppeteer tests fail, the feature does NOT pass. Fix it before moving on. ` ) @@ -87,6 +215,12 @@ func AgenticHarnessMiddleware() gin.HandlerFunc { // If rootDir is empty, the current working directory is used. func AgenticHarnessMiddlewareWithRootDir(rootDir string) gin.HandlerFunc { return func(c *gin.Context) { + // Check if harness is enabled via environment variable + if !isHarnessEnabled() { + c.Next() + return + } + req := c.Request if req == nil || req.Method != http.MethodPost { c.Next() @@ -116,8 +250,8 @@ func AgenticHarnessMiddlewareWithRootDir(rootDir string) gin.HandlerFunc { // 3. Detect State // We look for evidence that the harness is already active (features/progress files). - // We also check conversation length. - state := detectHarnessState(body, rootDir) + // We also check conversation length and session-based storage. + state := detectHarnessState(body, c, rootDir) // 4. Inject Prompt var promptToInject string @@ -126,6 +260,10 @@ func AgenticHarnessMiddlewareWithRootDir(rootDir string) gin.HandlerFunc { promptToInject = harnessInitializerPrompt case "CODING": promptToInject = harnessCodingPrompt + // Append Puppeteer testing reminder if MCP is detected + if detectPuppeteerMCP(body) { + promptToInject += harnessTestingReminder + } default: // "PASSIVE" - do nothing, let the user drive. c.Next() @@ -146,7 +284,108 @@ func AgenticHarnessMiddlewareWithRootDir(rootDir string) gin.HandlerFunc { } } -func detectHarnessState(body []byte, rootDir string) string { +// detectPuppeteerMCP checks if Puppeteer MCP is available in the conversation or tools array. +func detectPuppeteerMCP(body []byte) bool { + raw := strings.ToLower(string(body)) + + // Check for common Puppeteer MCP indicators + puppeteerIndicators := []string{ + "puppeteer", + "mcp_puppeteer", + "mcp-puppeteer", + "puppeteer_navigate", + "puppeteer_screenshot", + "puppeteer_click", + "browser_action", + } + + for _, indicator := range puppeteerIndicators { + if strings.Contains(raw, indicator) { + return true + } + } + + // Check tools array specifically for more precise detection + tools := gjson.GetBytes(body, "tools") + if tools.Exists() && tools.IsArray() { + for _, tool := range tools.Array() { + toolName := strings.ToLower(tool.Get("name").String()) + toolDesc := strings.ToLower(tool.Get("description").String()) + if strings.Contains(toolName, "puppeteer") || strings.Contains(toolDesc, "puppeteer") { + return true + } + } + } + + return false +} + +// extractSessionKeyFromContext extracts session key from request headers. +func extractSessionKeyFromContext(c *gin.Context) string { + if v := c.GetHeader("X-CLIProxyAPI-Session"); v != "" { + return v + } + if v := c.GetHeader("X-Session-Id"); v != "" { + return v + } + return "" +} + +// extractSessionKeyFromBody extracts session key from request body JSON fields. +func extractSessionKeyFromBody(body []byte) string { + if v := gjson.GetBytes(body, "prompt_cache_key"); v.Exists() && v.Type == gjson.String { + return v.String() + } + if v := gjson.GetBytes(body, "metadata.session_id"); v.Exists() && v.Type == gjson.String { + return v.String() + } + if v := gjson.GetBytes(body, "session_id"); v.Exists() && v.Type == gjson.String { + return v.String() + } + return "" +} + +// memoryBaseDirForHarness returns the base directory for memory/session storage. +func memoryBaseDirForHarness() string { + if v := os.Getenv("CLIPROXY_MEMORY_DIR"); v != "" { + return v + } + // Try default locations + if home, err := os.UserHomeDir(); err == nil { + return filepath.Join(home, ".proxypilot", "memory") + } + return filepath.Join(".", ".proxypilot", "memory") +} + +// harnessFileVariations lists possible file name variations for harness files. +var harnessProgressFileVariations = []string{ + "claude-progress.txt", + "claude-progress", + "progress.txt", +} + +var harnessFeatureFileVariations = []string{ + "feature_list.json", + "feature_list", + "features.json", +} + +// checkHarnessFilesExist checks if any harness files exist in the given directory. +func checkHarnessFilesExist(dir string) bool { + for _, f := range harnessProgressFileVariations { + if fileExists(dir, f) { + return true + } + } + for _, f := range harnessFeatureFileVariations { + if fileExists(dir, f) { + return true + } + } + return false +} + +func detectHarnessState(body []byte, c *gin.Context, rootDir string) string { // Simple heuristic: // If the conversation contains references to "claude-progress.txt" or "feature_list.json", // it's likely already in the harness flow -> CODING. @@ -157,8 +396,23 @@ func detectHarnessState(body []byte, rootDir string) string { return "CODING" } - // Prefer filesystem truth when available. - if fileExists(rootDir, "claude-progress.txt") || fileExists(rootDir, "feature_list.json") { + // Try to get session key from context headers first, then from body + sessionKey := extractSessionKeyFromContext(c) + if sessionKey == "" { + sessionKey = extractSessionKeyFromBody(body) + } + + // Check session-based storage for harness files + if sessionKey != "" { + memoryDir := memoryBaseDirForHarness() + sessionHarnessDir := filepath.Join(memoryDir, "sessions", sessionKey, "harness") + if checkHarnessFilesExist(sessionHarnessDir) { + return "CODING" + } + } + + // Prefer filesystem truth when available (check rootDir with file variations). + if checkHarnessFilesExist(rootDir) { return "CODING" }