@eldrforge/ai-service 0.1.14 → 0.1.16

package/dist/index.js

@@ -1,12 +1,12 @@
 import { OpenAI } from "openai";
-import { safeJsonParse, run } from "@eldrforge/git-tools";
+import { safeJsonParse, run, localBranchExists, isBranchInSyncWithRemote, safeSyncBranchWithRemote } from "@eldrforge/git-tools";
 import fs$1 from "fs";
 import { spawnSync } from "child_process";
 import * as path from "path";
 import path__default from "path";
 import * as os from "os";
 import * as fs from "fs/promises";
-import { recipe } from "@riotprompt/riotprompt";
+import { registerTemplates, cook, ConversationBuilder, generateToolGuidance, ConversationLogger, MetricsCollector } from "@riotprompt/riotprompt";
 import { fileURLToPath } from "url";
 let logger;
 function setLogger(customLogger) {
@@ -114,7 +114,10 @@ async function createCompletion(messages, options = { model: "gpt-4o-mini" }) {
     if (!apiKey) {
       throw new OpenAIError("OPENAI_API_KEY environment variable is not set");
     }
-    const timeoutMs = parseInt(process.env.OPENAI_TIMEOUT_MS || "300000");
+    const timeoutMs = parseInt(process.env.OPENAI_TIMEOUT_MS || "300000", 10);
+    if (isNaN(timeoutMs) || timeoutMs <= 0) {
+      throw new OpenAIError("Invalid OPENAI_TIMEOUT_MS value - must be a positive number");
+    }
     openai = new OpenAI({
       apiKey,
       timeout: timeoutMs
@@ -157,8 +160,9 @@ async function createCompletion(messages, options = { model: "gpt-4o-mini" }) {
     const completionPromise = openai.chat.completions.create(apiOptions);
     let timeoutId = null;
     const timeoutPromise = new Promise((_, reject) => {
-      const timeoutMs2 = parseInt(process.env.OPENAI_TIMEOUT_MS || "300000");
-      timeoutId = setTimeout(() => reject(new OpenAIError(`OpenAI API call timed out after ${timeoutMs2 / 1e3} seconds`)), timeoutMs2);
+      const timeoutMs2 = parseInt(process.env.OPENAI_TIMEOUT_MS || "300000", 10);
+      const validTimeout = isNaN(timeoutMs2) || timeoutMs2 <= 0 ? 3e5 : timeoutMs2;
+      timeoutId = setTimeout(() => reject(new OpenAIError(`OpenAI API call timed out after ${validTimeout / 1e3} seconds`)), validTimeout);
     });
     let progressIntervalId = null;
     progressIntervalId = setInterval(() => {
@@ -710,6 +714,31 @@ function requireTTY(errorMessage = "Interactive mode requires a terminal. Use --
     throw new Error(errorMessage);
   }
 }
+const initializeTemplates = () => {
+  const templates = {
+    // Commit message generation template
+    "commit": {
+      persona: { path: "personas/you.md" },
+      instructions: [{ path: "instructions/commit.md" }]
+    },
+    // Release notes generation template
+    "release": {
+      persona: { path: "personas/releaser.md" },
+      instructions: [{ path: "instructions/release.md" }]
+    },
+    // Code review template
+    "review": {
+      persona: { path: "personas/you.md" },
+      instructions: [{ path: "instructions/review.md" }]
+    }
+  };
+  registerTemplates(templates);
+};
+const TemplateNames = {
+  COMMIT: "commit",
+  RELEASE: "release",
+  REVIEW: "review"
+};
 const __filename$3 = fileURLToPath(import.meta.url);
 const __dirname$3 = path__default.dirname(__filename$3);
 const createCommitPrompt = async ({ overridePaths: _overridePaths, overrides: _overrides }, { diffContent, userDirection, isFileContent, githubIssuesContext }, { logContext, context, directories } = {}) => {
@@ -735,7 +764,14 @@ const createCommitPrompt = async ({ overridePaths: _overridePaths, overrides: _o
   if (directories && directories.length > 0) {
     contextItems.push({ directories, title: "Directories" });
   }
-  return recipe(basePath).persona({ path: "personas/you.md" }).instructions({ path: "instructions/commit.md" }).overridePaths(_overridePaths ?? []).overrides(_overrides ?? true).content(...contentItems).context(...contextItems).cook();
+  return cook({
+    basePath,
+    template: TemplateNames.COMMIT,
+    overridePaths: _overridePaths ?? [],
+    overrides: _overrides ?? true,
+    content: contentItems,
+    context: contextItems
+  });
 };
 const __filename$2 = fileURLToPath(import.meta.url);
 const __dirname$2 = path__default.dirname(__filename$2);
@@ -780,7 +816,14 @@ const createReleasePrompt = async ({ overrides: _overrides, overridePaths: _over
   if (directories && directories.length > 0) {
     contextItems.push({ directories, title: "Directories" });
   }
-  const prompt = await recipe(basePath).persona({ path: "personas/releaser.md" }).instructions({ path: "instructions/release.md" }).overridePaths(_overridePaths ?? []).overrides(_overrides ?? true).content(...contentItems).context(...contextItems).cook();
+  const prompt = await cook({
+    basePath,
+    template: TemplateNames.RELEASE,
+    overridePaths: _overridePaths ?? [],
+    overrides: _overrides ?? true,
+    content: contentItems,
+    context: contextItems
+  });
   return {
     prompt,
     maxTokens,
@@ -814,7 +857,14 @@ const createReviewPrompt = async ({ overridePaths: _overridePaths, overrides: _o
   if (directories && directories.length > 0) {
     contextItems.push({ directories, title: "Directories" });
   }
-  return recipe(basePath).persona({ path: "personas/you.md" }).instructions({ path: "instructions/review.md" }).overridePaths(_overridePaths ?? []).overrides(_overrides ?? true).content(...contentItems).context(...contextItems).cook();
+  return cook({
+    basePath,
+    template: TemplateNames.REVIEW,
+    overridePaths: _overridePaths ?? [],
+    overrides: _overrides ?? true,
+    content: contentItems,
+    context: contextItems
+  });
 };
 class AgenticExecutor {
   logger;
@@ -823,7 +873,7 @@ class AgenticExecutor {
     this.logger = logger2;
   }
   /**
-   * Run the agentic loop
+   * Run the agentic loop with ConversationBuilder
    */
   async run(config) {
     const {
@@ -836,15 +886,33 @@ class AgenticExecutor {
       debugResponseFile,
       storage,
       logger: logger2,
-      openaiReasoning = false
+      openaiReasoning = false,
+      tokenBudget
     } = config;
-    const messages = [...initialMessages];
+    const conversation = ConversationBuilder.create({ model }, logger2);
+    for (const msg of initialMessages) {
+      if (msg.role === "system") {
+        conversation.addSystemMessage(msg.content);
+      } else if (msg.role === "user") {
+        conversation.addUserMessage(msg.content);
+      }
+    }
+    if (tokenBudget) {
+      this.log("Configuring token budget", tokenBudget);
+      conversation.withTokenBudget({
+        max: tokenBudget.max,
+        reserveForResponse: tokenBudget.reserveForResponse || 4e3,
+        strategy: tokenBudget.strategy || "fifo",
+        onBudgetExceeded: tokenBudget.onBudgetExceeded || "compress"
+      });
+    }
     let iterations = 0;
     let toolCallsExecuted = 0;
-    this.log("Starting agentic loop", { maxIterations, toolCount: tools.count() });
+    this.log("Starting agentic loop with ConversationBuilder", { maxIterations, toolCount: tools.count() });
     while (iterations < maxIterations) {
       iterations++;
       this.log(`Iteration ${iterations}/${maxIterations}`);
+      const messages = conversation.toMessages();
       const response = await createCompletionWithRetry(
         messages,
         {
@@ -863,23 +931,16 @@ class AgenticExecutor {
       if (toolCalls.length === 0) {
         const finalContent = message.content || "";
         this.log("Agent completed without tool calls", { iterations, toolCallsExecuted });
-        messages.push({
-          role: "assistant",
-          content: finalContent
-        });
+        conversation.addAssistantMessage(finalContent);
         return {
           finalMessage: finalContent,
           iterations,
           toolCallsExecuted,
-          conversationHistory: messages,
+          conversationHistory: conversation.toMessages(),
           toolMetrics: this.toolMetrics
         };
       }
-      messages.push({
-        role: "assistant",
-        content: message.content || null,
-        tool_calls: toolCalls
-      });
+      conversation.addAssistantWithToolCalls(message.content || null, toolCalls);
       this.log(`Executing ${toolCalls.length} tool call(s)`);
       for (const toolCall of toolCalls) {
         const startTime = Date.now();
@@ -889,14 +950,16 @@ class AgenticExecutor {
           if (this.logger?.info) {
             this.logger.info(`🔧 Running tool: ${toolName}`);
           }
-          const args = JSON.parse(toolCall.function.arguments);
+          let args;
+          try {
+            args = JSON.parse(toolCall.function.arguments);
+          } catch (parseError) {
+            throw new Error(`Failed to parse tool arguments: ${parseError.message}`);
+          }
           const result = await tools.execute(toolName, args);
           const duration = Date.now() - startTime;
-          messages.push({
-            role: "tool",
-            tool_call_id: toolCall.id,
-            content: this.formatToolResult({ id: toolCall.id, name: toolName, result })
-          });
+          const formattedResult = this.formatToolResult({ id: toolCall.id, name: toolName, result });
+          conversation.addToolResult(toolCall.id, formattedResult, toolName);
           toolCallsExecuted++;
           this.toolMetrics.push({
             name: toolName,
@@ -924,22 +987,16 @@ class AgenticExecutor {
           if (this.logger?.warn) {
             this.logger.warn(`❌ Tool ${toolName} failed: ${errorMessage}`);
           }
-          messages.push({
-            role: "tool",
-            tool_call_id: toolCall.id,
-            content: `Tool execution failed: ${errorMessage}`
-          });
+          conversation.addToolResult(toolCall.id, `Tool execution failed: ${errorMessage}`, toolName);
         }
       }
       this.log(`Completed tool execution`, { toolCallsExecuted });
     }
     this.log("Max iterations reached, forcing completion", { iterations, toolCallsExecuted });
-    messages.push({
-      role: "user",
-      content: "Please provide your final analysis and commit message based on your investigation. Do not request any more tools."
-    });
+    conversation.addUserMessage("Please provide your final analysis based on your investigation. Do not request any more tools.");
+    const finalMessages = conversation.toMessages();
     const finalResponse = await createCompletionWithRetry(
-      messages,
+      finalMessages,
       {
         model,
         openaiReasoning: openaiReasoning || void 0,
@@ -948,15 +1005,12 @@ class AgenticExecutor {
         logger: logger2
       }
     );
-    messages.push({
-      role: "assistant",
-      content: finalResponse
-    });
+    conversation.addAssistantMessage(finalResponse);
     return {
       finalMessage: finalResponse,
       iterations,
       toolCallsExecuted,
-      conversationHistory: messages,
+      conversationHistory: conversation.toMessages(),
       toolMetrics: this.toolMetrics
     };
   }
@@ -1096,6 +1150,20 @@ function createGetFileHistoryTool$1() {
   return {
     name: "get_file_history",
     description: "Get git commit history for one or more files to understand their evolution and past changes",
+    category: "Understanding",
+    cost: "cheap",
+    examples: [
+      {
+        scenario: "Check if file has recent refactoring",
+        params: { filePaths: ["src/auth.ts"], limit: 5 },
+        expectedResult: "List of recent commits affecting auth.ts"
+      },
+      {
+        scenario: "Understand evolution of multiple related files",
+        params: { filePaths: ["src/user.ts", "src/auth.ts"], limit: 10, format: "detailed" },
+        expectedResult: "Detailed commit history for both files"
+      }
+    ],
     parameters: {
       type: "object",
       properties: {
@@ -1137,6 +1205,20 @@ function createGetFileContentTool$1() {
   return {
     name: "get_file_content",
     description: "Get the complete current content of a file to understand context around changes. Returns a message if the file does not exist (e.g., if it was deleted).",
+    category: "Understanding",
+    cost: "moderate",
+    examples: [
+      {
+        scenario: "See full class definition for modified method",
+        params: { filePath: "src/services/auth.ts", includeLineNumbers: true },
+        expectedResult: "Complete file content with line numbers"
+      },
+      {
+        scenario: "Check imports and structure",
+        params: { filePath: "src/utils/helpers.ts" },
+        expectedResult: "Full file content showing imports and exports"
+      }
+    ],
     parameters: {
       type: "object",
       properties: {
@@ -1180,6 +1262,20 @@ function createSearchCodebaseTool$1() {
   return {
     name: "search_codebase",
     description: "Search for code patterns, function names, or text across the codebase using git grep",
+    category: "Analysis",
+    cost: "moderate",
+    examples: [
+      {
+        scenario: "Find all uses of a renamed function",
+        params: { query: "oldFunctionName", fileTypes: ["ts", "tsx"] },
+        expectedResult: "List of files and lines containing the function"
+      },
+      {
+        scenario: "Check if pattern exists elsewhere",
+        params: { query: "pattern.*string", contextLines: 3 },
+        expectedResult: "Matching lines with surrounding context"
+      }
+    ],
     parameters: {
       type: "object",
       properties: {
@@ -1224,6 +1320,9 @@ function createGetRelatedTestsTool$1() {
   return {
     name: "get_related_tests",
     description: "Find test files related to production files to understand what the code is supposed to do",
+    category: "Understanding",
+    cost: "cheap",
+    examples: [{ scenario: "Find tests for modified service", params: { filePaths: ["src/services/auth.ts"] }, expectedResult: "List of related test files" }],
     parameters: {
       type: "object",
       properties: {
@@ -1270,6 +1369,9 @@ function createGetFileDependenciesTool$1() {
   return {
     name: "get_file_dependencies",
     description: "Find which files import or depend on the changed files to assess change impact",
+    category: "Analysis",
+    cost: "moderate",
+    examples: [{ scenario: "Check impact of util function change", params: { filePaths: ["src/utils/format.ts"] }, expectedResult: "Files that import format.ts" }],
     parameters: {
       type: "object",
       properties: {
@@ -1313,6 +1415,9 @@ function createAnalyzeDiffSectionTool$1() {
   return {
     name: "analyze_diff_section",
     description: "Get expanded context around specific lines in a file to better understand changes",
+    category: "Understanding",
+    cost: "cheap",
+    examples: [{ scenario: "See context around confusing change", params: { filePath: "src/auth.ts", startLine: 45, endLine: 52, contextLines: 15 }, expectedResult: "Expanded code section with context" }],
     parameters: {
       type: "object",
       properties: {
@@ -1361,6 +1466,9 @@ function createGetRecentCommitsTool$1() {
   return {
     name: "get_recent_commits",
     description: "Get recent commits that modified the same files to understand recent work in this area",
+    category: "Understanding",
+    cost: "cheap",
+    examples: [{ scenario: "Check for duplicate commit messages", params: { filePaths: ["src/auth.ts"], since: "1 week ago", limit: 5 }, expectedResult: "Recent commits to auth.ts" }],
     parameters: {
       type: "object",
       properties: {
@@ -1400,6 +1508,15 @@ function createGroupFilesByConcernTool$1() {
   return {
     name: "group_files_by_concern",
     description: "Analyze changed files and suggest logical groupings that might represent separate commits",
+    category: "Organization",
+    cost: "cheap",
+    examples: [
+      {
+        scenario: "Check if multiple unrelated changes should be split",
+        params: { filePaths: ["src/auth.ts", "README.md", "tests/auth.test.ts", "package.json"] },
+        expectedResult: "Files grouped by concern with split suggestions"
+      }
+    ],
     parameters: {
       type: "object",
       properties: {
@@ -1458,7 +1575,8 @@ async function runAgenticCommit(config) {
     debugResponseFile,
     storage,
     logger: logger2,
-    openaiReasoning
+    openaiReasoning,
+    tokenBudget
   } = config;
   const toolRegistry = createToolRegistry({
     workingDirectory: process.cwd(),
@@ -1467,7 +1585,13 @@ async function runAgenticCommit(config) {
   });
   const tools = createCommitTools();
   toolRegistry.registerAll(tools);
-  const systemPrompt = buildSystemPrompt$1();
+  const toolGuidance = generateToolGuidance(tools, {
+    strategy: "adaptive",
+    includeExamples: true,
+    explainWhenToUse: true,
+    includeCategories: true
+  });
+  const systemPrompt = buildSystemPrompt$2(toolGuidance);
   const userMessage = buildUserMessage$1(changedFiles, diffContent, userDirection, logContext);
   const messages = [
     { role: "system", content: systemPrompt },
@@ -1483,7 +1607,13 @@ async function runAgenticCommit(config) {
     debugResponseFile,
     storage,
     logger: logger2,
-    openaiReasoning
+    openaiReasoning,
+    tokenBudget: tokenBudget || {
+      max: 15e4,
+      reserveForResponse: 4e3,
+      strategy: "fifo",
+      onBudgetExceeded: "compress"
+    }
   };
   const result = await runAgentic(agenticConfig);
   const parsed = parseAgenticResult$1(result.finalMessage);
@@ -1496,53 +1626,60 @@ async function runAgenticCommit(config) {
     toolMetrics: result.toolMetrics
   };
 }
-function buildSystemPrompt$1() {
-  return `You are an expert software engineer tasked with generating meaningful commit messages.
+function buildSystemPrompt$2(toolGuidance) {
+  return `You are a professional software engineer writing commit messages for your team.
+
+${toolGuidance}
 
-You have access to tools to understand changes deeply. Use them strategically based on what you see:
+## Your Task
 
-## When to Use Each Tool
+Write a commit message that clearly explains what changed and why. Your message should help teammates understand the changes without needing to read the diff.
 
-**Understanding What Changed:**
-- get_file_content: Use when you need full context. Good for: seeing entire class/function being modified, checking imports, understanding overall structure
-- analyze_diff_section: Use when diff is confusing. Good for: expanding context around small changes, seeing how code integrates
-- get_file_dependencies: Use for import/refactor changes. Good for: understanding what's being moved/reorganized, checking dependency impact
+Think about:
+- What problem does this solve?
+- How do the changes work together?
+- What should reviewers focus on?
+- Are there any important implications?
 
-**Understanding Why:**
-- get_file_history: Use to see evolution. Good for: understanding if this continues previous work, checking for patterns
-- get_recent_commits: Use to check recent context. Good for: avoiding duplicate messages, understanding if this is part of a series
-- search_codebase: Use to understand usage. Good for: seeing if changes affect multiple places, finding patterns
+Use the available tools to investigate the changes. The more you understand, the better your message will be.
 
-**Organizing Changes:**
-- group_files_by_concern: Use when multiple files changed. Good for: identifying logical groupings, determining if split is needed
-- get_related_tests: Use for logic changes. Good for: understanding intent from test changes, verifying behavior changes
+**Important**: If additional context is provided (from context files or other sources), use your judgment:
+- If the context is relevant to these specific changes, incorporate it
+- If the context describes unrelated changes or other packages, ignore it
+- Don't force connections between unrelated information
+- Focus on accurately describing what actually changed in this commit
 
-## Investigation Strategy
+## Investigation Approach
 
-For simple changes (1-3 files, obvious purpose):
-- Use 1-2 tools: get_recent_commits to avoid duplicates, get_related_tests if logic changed
+Use tools based on what you need to know:
+- group_files_by_concern - understand how files relate
+- get_file_content - see full context when diffs are unclear
+- get_file_history - understand how code evolved
+- get_file_dependencies - assess impact of changes
+- get_recent_commits - avoid duplicate messages
+- get_related_tests - understand behavior changes
+- search_codebase - find usage patterns
 
-For moderate changes (4-10 files, clear theme):
-- Use 2-4 tools: group_files_by_concern, get_file_content for key files, get_recent_commits, get_related_tests
+## Writing Style
 
-For complex changes (10+ files, or unclear purpose):
-- Use 4-6 tools: group_files_by_concern, get_file_history, get_file_content for key files, get_file_dependencies, get_related_tests, search_codebase
+Write naturally and directly:
+- Use plain language, not corporate speak
+- Be specific and concrete
+- Avoid buzzwords and jargon
+- No emojis or excessive punctuation
+- No phrases like "this commit" or "this PR"
+- No meta-commentary about the commit itself
 
-Always use tools to understand context - don't rely only on the diff.
+Follow conventional commit format when appropriate (feat:, fix:, refactor:, docs:, test:, chore:), but prioritize clarity over formality.
 
-## Guidelines
-- Follow conventional commit format when appropriate (feat:, fix:, refactor:, docs:, test:, chore:)
-- Consider suggesting split commits for unrelated changes
-- Output only the commit message and/or splits - no conversational remarks
-- NEVER include phrases like "If you want" or "Let me know" or offer follow-up actions
+## Output Format
 
-Output format:
-When you're ready to provide the final commit message, format it as:
+When ready, format your response as:
 
 COMMIT_MESSAGE:
-[Your generated commit message here]
+[Your commit message here]
 
-If you recommend splitting into multiple commits, also include:
+If changes should be split into multiple commits:
 
 SUGGESTED_SPLITS:
 Split 1:
@@ -1553,7 +1690,7 @@ Message: [commit message for this split]
 Split 2:
 ...
 
-If changes should remain as one commit, do not include SUGGESTED_SPLITS section.`;
+Output only the commit message and splits. No conversational remarks or follow-up offers.`;
 }
 function buildUserMessage$1(changedFiles, diffContent, userDirection, logContext) {
   let message = `I have staged changes that need a commit message.
@@ -1576,9 +1713,16 @@ ${logContext}`;
   }
   message += `
 
-Please investigate these changes and generate an appropriate commit message.
-Use the available tools to gather additional context as needed.
-If these changes should be split into multiple commits, suggest the groupings.`;
+Analyze these changes and write a clear commit message. Consider:
+- What problem does this solve?
+- How do the changes work together?
+- Should this be one commit or multiple?
+
+If context information is provided, use it only if relevant to these specific changes.
+Don't force connections that don't exist - if context doesn't apply to this package,
+simply ignore it and focus on the actual changes.
+
+Investigate as needed to write an accurate, helpful message.`;
   return message;
 }
 function parseAgenticResult$1(finalMessage) {
@@ -1976,6 +2120,9 @@ function createGetTagHistoryTool() {
   return {
     name: "get_tag_history",
     description: "Get the history of previous release tags to understand release patterns and versioning",
+    category: "Release Analysis",
+    cost: "cheap",
+    examples: [{ scenario: "Check recent version tags", params: { limit: 5, pattern: "v*" }, expectedResult: "List of recent version tags with dates" }],
     parameters: {
       type: "object",
       properties: {
@@ -2025,6 +2172,9 @@ function createComparePreviousReleaseTool() {
   return {
     name: "compare_previous_release",
     description: "Compare this release with a previous release to understand what changed between versions",
+    category: "Release Analysis",
+    cost: "moderate",
+    examples: [{ scenario: "Compare with last release", params: { previousTag: "v1.0.0", currentRef: "HEAD" }, expectedResult: "Commit count and file change statistics" }],
     parameters: {
       type: "object",
       properties: {
@@ -2080,6 +2230,9 @@ function createGetReleaseStatsTool() {
   return {
     name: "get_release_stats",
     description: "Get comprehensive statistics about the release including contributors, file changes, and commit patterns",
+    category: "Release Analysis",
+    cost: "moderate",
+    examples: [{ scenario: "Get release overview", params: { fromRef: "v1.0.0", toRef: "HEAD" }, expectedResult: "Contributors, file changes, and top modified files" }],
     parameters: {
       type: "object",
       properties: {
@@ -2133,6 +2286,9 @@ function createGetBreakingChangesTool() {
   return {
     name: "get_breaking_changes",
     description: "Search for potential breaking changes by looking for specific patterns in commits and diffs",
+    category: "Release Analysis",
+    cost: "expensive",
+    examples: [{ scenario: "Check for breaking changes", params: { fromRef: "v1.0.0", toRef: "HEAD" }, expectedResult: "List of potential breaking changes found" }],
     parameters: {
       type: "object",
       properties: {
@@ -2196,6 +2352,9 @@ function createAnalyzeCommitPatternsTool() {
   return {
     name: "analyze_commit_patterns",
     description: "Analyze commit messages to identify patterns and themes in the release",
+    category: "Release Analysis",
+    cost: "cheap",
+    examples: [{ scenario: "Find commit themes", params: { fromRef: "v1.0.0", toRef: "HEAD" }, expectedResult: "Commit types and top keywords" }],
     parameters: {
       type: "object",
       properties: {
@@ -2267,7 +2426,8 @@ async function runAgenticRelease(config) {
     debugResponseFile,
     storage,
     logger: logger2,
-    openaiReasoning
+    openaiReasoning,
+    tokenBudget
   } = config;
   const toolRegistry = createToolRegistry({
     workingDirectory: process.cwd(),
@@ -2276,7 +2436,13 @@ async function runAgenticRelease(config) {
   });
   const tools = createReleaseTools();
   toolRegistry.registerAll(tools);
-  const systemPrompt = buildSystemPrompt();
+  const toolGuidance = generateToolGuidance(tools, {
+    strategy: "adaptive",
+    includeExamples: true,
+    explainWhenToUse: true,
+    includeCategories: true
+  });
+  const systemPrompt = buildSystemPrompt$1(toolGuidance);
   const userMessage = buildUserMessage({
     fromRef,
     toRef,
@@ -2300,7 +2466,13 @@ async function runAgenticRelease(config) {
     debugResponseFile,
     storage,
     logger: logger2,
-    openaiReasoning
+    openaiReasoning,
+    tokenBudget: tokenBudget || {
+      max: 2e5,
+      reserveForResponse: 8e3,
+      strategy: "fifo",
+      onBudgetExceeded: "compress"
+    }
   };
   const result = await runAgentic(agenticConfig);
   const parsed = parseAgenticResult(result.finalMessage);
@@ -2312,64 +2484,80 @@ async function runAgenticRelease(config) {
     toolMetrics: result.toolMetrics
   };
 }
-function buildSystemPrompt() {
-  return `You are an expert software engineer and technical writer tasked with generating comprehensive, thoughtful release notes.
+function buildSystemPrompt$1(toolGuidance) {
+  return `You are a professional software engineer writing release notes for your team and users.
+
+${toolGuidance}
+
+## Your Task
+
+Write release notes that clearly explain what's in this release and why it matters. Your notes should help users and developers understand what changed without needing to read every commit.
+
+Focus on:
+- What problems does this release solve?
+- What new capabilities does it add?
+- What's the impact on users and developers?
+- Are there breaking changes or important considerations?
+
+Use the available tools to investigate the changes. The more you understand, the better your notes will be.
+
+**Important**: If additional context is provided (from context files or other sources), use your judgment:
+- If the context is relevant to this specific package/release, incorporate it appropriately
+- If the context describes changes in other packages or unrelated work, ignore it
+- Don't fabricate connections between this package and unrelated context
+- Be honest about what changed - only mention what actually happened in this release
+- Context is supplemental information, not a requirement to include
 
-You have access to tools to investigate the release in depth. Use them strategically:
+## Investigation Approach
 
-## Investigation Tools
+Use tools based on what you need to know:
 
-**Understanding Context & History:**
-- get_file_history: Use when you need to understand how a file evolved. Good for: seeing if a refactor is part of a larger pattern, understanding why certain decisions were made
-- get_recent_commits: Use to see what happened to files recently. Good for: detecting related work, understanding if this is part of an ongoing effort
-- compare_previous_release: Use to contextualize scope. Good for: comparing size/impact of this release vs previous ones, identifying if this is major/minor
-- get_tag_history: Use early to understand release cadence. Good for: establishing context about project versioning patterns
+**Context:**
+- get_tag_history - understand release patterns
+- get_release_stats - quantify scope
+- compare_previous_release - see how this compares
 
-**Analyzing Current Changes:**
-- get_file_content: Use when diff alone isn't enough. Good for: understanding APIs, seeing full class/function context, checking imports
-- analyze_diff_section: Use to expand context around cryptic changes. Good for: seeing surrounding code, understanding integration points
-- get_file_dependencies: Use for refactors/moves. Good for: assessing impact scope, identifying what depends on changed code
-- search_codebase: Use to find usage patterns. Good for: checking if APIs are widely used, finding similar patterns elsewhere
+**Understanding:**
+- group_files_by_concern - identify themes
+- analyze_commit_patterns - detect patterns
+- get_file_content - see full context
+- analyze_diff_section - expand unclear changes
+- get_file_history - understand evolution
 
-**Pattern Recognition:**
-- group_files_by_concern: Use when many files changed. Good for: organizing changes into logical themes, identifying what actually happened
-- analyze_commit_patterns: Use for many commits. Good for: detecting themes across commits, identifying if work is focused or scattered
-- get_release_stats: Use to quantify scope. Good for: getting concrete metrics on scale of changes
+**Impact:**
+- get_file_dependencies - assess reach
+- search_codebase - find usage patterns
+- get_related_tests - understand behavior changes
+- get_breaking_changes - identify breaking changes (always use)
 
-**Risk Assessment:**
-- get_breaking_changes: Always use. Good for: identifying API changes, finding removals/signature changes that could break users
-- get_related_tests: Use for significant logic changes. Good for: understanding what behavior changed, verifying test coverage exists
+## Writing Style
 
-## Your Investigation Strategy
+Write naturally and directly:
+- Use plain language that users can understand
+- Be specific about what changed and why
+- Avoid marketing speak and buzzwords
+- No emojis or excessive punctuation
+- No phrases like "we're excited to announce"
+- No meta-commentary about the release itself
+- Focus on facts and implications, not enthusiasm
 
-1. **Start broad** (2-3 tools): get_tag_history, get_release_stats, analyze_commit_patterns
-2. **Identify themes** (1-2 tools): group_files_by_concern if many files, compare_previous_release for context
-3. **Deep dive** (3-5 tools): get_file_content for key changes, get_file_dependencies for refactors, analyze_diff_section for unclear changes
-4. **Verify understanding** (2-3 tools): get_related_tests for logic changes, search_codebase for impact
-5. **Check risks** (1 tool): get_breaking_changes always
+Structure your notes logically:
+- Start with the most important changes
+- Group related changes together
+- Explain breaking changes clearly
+- Include practical examples when helpful
 
-Use at least 6-8 tools per release to ensure comprehensive analysis. Each tool provides a different lens on the changes.
+## Output Format
 
-Output format:
-When you're ready to provide the final release notes, format them as JSON:
+When ready, format your response as JSON:
 
 RELEASE_NOTES:
 {
-  "title": "A concise, single-line title capturing the most significant changes",
-  "body": "The detailed release notes in Markdown format, following best practices for structure, depth, and analysis"
-}
-
-The release notes should:
-- Demonstrate genuine understanding of the changes
-- Provide context and explain implications
-- Connect related changes to reveal patterns
-- Be substantial and analytical, not formulaic
-- Sound like they were written by a human who studied the changes
-- Be grounded in actual commits and issues (no hallucinations)
-- Be standalone documentation that can be published as-is
-- NEVER include conversational elements like "If you want, I can also..." or "Let me know if..."
-- NEVER offer follow-up actions, questions, or suggestions for additional work
-- End with substantive content, not conversational closing remarks`;
+  "title": "Clear, factual title describing the main changes",
+  "body": "Detailed release notes in Markdown format"
+}
+
+Output only the JSON. No conversational remarks or follow-up offers.`;
 }
 function buildUserMessage(params) {
   const { fromRef, toRef, logContent, diffContent, milestoneIssues, releaseFocus, userContext } = params;
@@ -2402,15 +2590,17 @@ ${userContext}`;
   }
   message += `
 
-Please investigate these changes thoroughly and generate comprehensive release notes that:
-1. Demonstrate deep understanding of what changed and why
-2. Provide context about how changes relate to each other
-3. Explain implications for users and developers
-4. Connect this release to previous releases and project evolution
-5. Identify any breaking changes or significant architectural shifts
-6. Follow best practices for technical writing and release notes
+Analyze these changes and write clear release notes. Consider:
+- What's the main story of this release?
+- What problems does it solve?
+- What's the impact on users and developers?
+- Are there breaking changes?
 
-Use the available tools to gather additional context as needed. Take your time to understand the changes deeply before writing the release notes.`;
+If context information is provided, use it only if relevant to this specific package.
+Don't force connections that don't exist - if context describes changes in other packages
+or unrelated features, simply ignore it and focus on what actually changed in this release.
+
+Investigate as needed to write accurate, helpful release notes.`;
   return message;
 }
 function parseAgenticResult(finalMessage) {
@@ -2418,8 +2608,13 @@ function parseAgenticResult(finalMessage) {
   if (jsonMatch) {
     try {
       const jsonStr = jsonMatch[1].trim();
-      const parsed = JSON.parse(jsonStr);
-      if (parsed.title && parsed.body) {
+      let parsed;
+      try {
+        parsed = JSON.parse(jsonStr);
+      } catch {
+        parsed = null;
+      }
+      if (parsed && parsed.title && parsed.body) {
         return {
           releaseNotes: {
             title: parsed.title,
@@ -2455,36 +2650,1084 @@ function parseAgenticResult(finalMessage) {
     }
   };
 }
+function createPublishTools() {
+  return [
+    createCheckGitStatusTool(),
+    createCheckBranchSyncTool(),
+    createAnalyzeDivergenceTool(),
+    createGetCommitLogTool(),
+    createGetBranchInfoTool(),
+    createSyncBranchTool(),
+    createGetDiffStatsTool(),
+    createCheckConflictsTool(),
+    createResetBranchTool()
+  ];
+}
+function createCheckGitStatusTool() {
+  return {
+    name: "check_git_status",
+    description: "Check the current git repository status, including uncommitted changes, current branch, and repository state",
+    parameters: {
+      type: "object",
+      properties: {
+        showUntracked: {
+          type: "boolean",
+          description: "Include untracked files in output (default: false)",
+          default: false
+        }
+      },
+      required: []
+    },
+    execute: async (params, context) => {
+      const { showUntracked = false } = params;
+      const workingDir = context?.workingDirectory || process.cwd();
+      try {
+        const branchResult = await run("git branch --show-current", { cwd: workingDir });
+        const currentBranch = branchResult.stdout.trim();
+        const statusCmd = showUntracked ? "git status --porcelain" : "git status --porcelain --untracked-files=no";
+        const statusResult = await run(statusCmd, { cwd: workingDir });
+        const hasChanges = statusResult.stdout.trim().length > 0;
+        const headResult = await run("git rev-parse --short HEAD", { cwd: workingDir });
+        const headSha = headResult.stdout.trim();
+        return {
+          currentBranch,
+          headSha,
+          hasUncommittedChanges: hasChanges,
+          statusOutput: statusResult.stdout
+        };
+      } catch (error) {
+        throw new Error(`Failed to check git status: ${error.message}`);
+      }
+    }
+  };
+}
+function createCheckBranchSyncTool() {
+  return {
+    name: "check_branch_sync",
+    description: "Check if a local branch is synchronized with its remote counterpart. Returns sync status, local/remote SHAs, and whether the branch exists locally.",
+    parameters: {
+      type: "object",
+      properties: {
+        branchName: {
+          type: "string",
+          description: "Name of the branch to check"
+        }
+      },
+      required: ["branchName"]
+    },
+    execute: async (params, _context) => {
+      const { branchName } = params;
+      try {
+        const exists = await localBranchExists(branchName);
+        if (!exists) {
+          return {
+            exists: false,
+            message: `Branch '${branchName}' does not exist locally`
+          };
+        }
+        const syncStatus = await isBranchInSyncWithRemote(branchName);
+        return {
+          exists: true,
+          branchName,
+          inSync: syncStatus.inSync,
+          localSha: syncStatus.localSha,
+          remoteSha: syncStatus.remoteSha,
+          error: syncStatus.error,
+          isDiverged: syncStatus.localSha !== syncStatus.remoteSha
+        };
+      } catch (error) {
+        throw new Error(`Failed to check branch sync: ${error.message}`);
+      }
+    }
+  };
+}
+function createAnalyzeDivergenceTool() {
+  return {
+    name: "analyze_divergence",
+    description: "Analyze how two branches have diverged by showing commits unique to each branch",
+    parameters: {
+      type: "object",
+      properties: {
+        sourceBranch: {
+          type: "string",
+          description: "The source/local branch name"
+        },
+        targetBranch: {
+          type: "string",
+          description: 'The target/remote branch to compare against (e.g., "origin/main")'
+        },
+        maxCommits: {
+          type: "number",
+          description: "Maximum number of commits to show for each branch (default: 10)",
+          default: 10
+        }
+      },
+      required: ["sourceBranch", "targetBranch"]
+    },
+    execute: async (params, context) => {
+      const { sourceBranch, targetBranch, maxCommits = 10 } = params;
+      const workingDir = context?.workingDirectory || process.cwd();
+      try {
+        const sourceOnlyResult = await run(
+          `git log ${targetBranch}..${sourceBranch} --oneline -n ${maxCommits}`,
+          { cwd: workingDir }
+        );
+        const targetOnlyResult = await run(
+          `git log ${sourceBranch}..${targetBranch} --oneline -n ${maxCommits}`,
+          { cwd: workingDir }
+        );
+        const mergeBaseResult = await run(
+          `git merge-base ${sourceBranch} ${targetBranch}`,
+          { cwd: workingDir }
+        );
+        return {
+          sourceBranch,
+          targetBranch,
+          mergeBase: mergeBaseResult.stdout.trim(),
+          commitsInSourceOnly: sourceOnlyResult.stdout.trim() || "None",
+          commitsInTargetOnly: targetOnlyResult.stdout.trim() || "None",
+          isDiverged: sourceOnlyResult.stdout.trim().length > 0 && targetOnlyResult.stdout.trim().length > 0,
+          canFastForward: sourceOnlyResult.stdout.trim().length === 0
+          // Target is ahead, can fast-forward
+        };
+      } catch (error) {
+        throw new Error(`Failed to analyze divergence: ${error.message}`);
+      }
+    }
+  };
+}
+function createGetCommitLogTool() {
+  return {
+    name: "get_commit_log",
+    description: "Get git commit log for a branch or commit range with detailed information",
+    parameters: {
+      type: "object",
+      properties: {
+        ref: {
+          type: "string",
+          description: 'Git ref (branch name, commit range like "main..working", or single commit)'
+        },
+        maxCommits: {
+          type: "number",
+          description: "Maximum number of commits to return (default: 20)",
+          default: 20
+        },
+        format: {
+          type: "string",
+          description: 'Format: "oneline" for brief, "full" for detailed with message body',
+          enum: ["oneline", "full"],
+          default: "oneline"
+        }
+      },
+      required: ["ref"]
+    },
+    execute: async (params, context) => {
+      const { ref, maxCommits = 20, format = "oneline" } = params;
+      const workingDir = context?.workingDirectory || process.cwd();
+      try {
+        const formatStr = format === "full" ? "%H%n%an <%ae>%n%ad%n%s%n%n%b%n---" : "%h - %s (%an, %ar)";
+        const result = await run(
+          `git log "${ref}" --format="${formatStr}" -n ${maxCommits}`,
+          { cwd: workingDir }
+        );
+        return result.stdout || "No commits found";
+      } catch (error) {
+        throw new Error(`Failed to get commit log: ${error.message}`);
+      }
+    }
+  };
+}
+function createGetBranchInfoTool() {
+  return {
+    name: "get_branch_info",
+    description: "Get detailed information about a branch including its tracking info, last commit, and whether it exists remotely",
+    parameters: {
+      type: "object",
+      properties: {
+        branchName: {
+          type: "string",
+          description: "Name of the branch to inspect"
+        }
+      },
+      required: ["branchName"]
+    },
+    execute: async (params, context) => {
+      const { branchName } = params;
+      const workingDir = context?.workingDirectory || process.cwd();
+      try {
+        const localExists = await localBranchExists(branchName);
+        if (!localExists) {
+          try {
+            const remoteCheckResult = await run(`git ls-remote --heads origin ${branchName}`, { cwd: workingDir });
+            const remoteExists = remoteCheckResult.stdout.trim().length > 0;
+            return {
+              branchName,
+              existsLocally: false,
+              existsRemotely: remoteExists,
+              message: remoteExists ? `Branch exists remotely but not locally` : `Branch does not exist locally or remotely`
+            };
+          } catch {
+            return {
+              branchName,
+              existsLocally: false,
+              existsRemotely: false
+            };
+          }
+        }
+        let trackingBranch = null;
+        try {
+          const trackingResult = await run(`git rev-parse --abbrev-ref ${branchName}@{upstream}`, { cwd: workingDir });
+          trackingBranch = trackingResult.stdout.trim();
+        } catch {
+        }
+        const lastCommitResult = await run(
+          `git log ${branchName} -1 --format="%H|%h|%s|%an|%ar"`,
+          { cwd: workingDir }
+        );
+        const [fullSha, shortSha, subject, author, relativeDate] = lastCommitResult.stdout.trim().split("|");
+        const countResult = await run(`git rev-list --count ${branchName}`, { cwd: workingDir });
+        const commitCount = parseInt(countResult.stdout.trim(), 10);
+        if (isNaN(commitCount)) {
+          throw new Error(`Invalid commit count returned from git: ${countResult.stdout}`);
+        }
+        return {
+          branchName,
+          existsLocally: true,
+          trackingBranch,
+          lastCommit: {
+            fullSha,
+            shortSha,
+            subject,
+            author,
+            relativeDate
+          },
+          commitCount
+        };
+      } catch (error) {
+        throw new Error(`Failed to get branch info: ${error.message}`);
+      }
+    }
+  };
+}
+function createSyncBranchTool() {
+  return {
+    name: "sync_branch",
+    description: "Attempt to synchronize a local branch with its remote counterpart. Returns success status and details about what happened.",
+    parameters: {
+      type: "object",
+      properties: {
+        branchName: {
+          type: "string",
+          description: "Name of the branch to sync"
+        }
+      },
+      required: ["branchName"]
+    },
+    execute: async (params, _context) => {
+      const { branchName } = params;
+      try {
+        const syncResult = await safeSyncBranchWithRemote(branchName);
+        return {
+          branchName,
+          success: syncResult.success,
+          conflictResolutionRequired: syncResult.conflictResolutionRequired,
+          error: syncResult.error,
+          message: syncResult.success ? `Successfully synchronized ${branchName} with remote` : syncResult.conflictResolutionRequired ? `Sync failed due to merge conflicts in ${branchName}` : `Sync failed: ${syncResult.error}`
+        };
+      } catch (error) {
+        throw new Error(`Failed to sync branch: ${error.message}`);
+      }
+    }
+  };
+}
+function createGetDiffStatsTool() {
+  return {
+    name: "get_diff_stats",
+    description: "Get statistics about differences between two git refs (branches, commits, etc.)",
+    parameters: {
+      type: "object",
+      properties: {
+        fromRef: {
+          type: "string",
+          description: 'Starting ref (e.g., "main", "origin/main")'
+        },
+        toRef: {
+          type: "string",
+          description: 'Ending ref (e.g., "working", "HEAD")'
+        },
+        includeFileList: {
+          type: "boolean",
+          description: "Include list of changed files (default: true)",
+          default: true
+        }
+      },
+      required: ["fromRef", "toRef"]
+    },
+    execute: async (params, context) => {
+      const { fromRef, toRef, includeFileList = true } = params;
+      const workingDir = context?.workingDirectory || process.cwd();
+      try {
+        const statsResult = await run(`git diff --shortstat ${fromRef}..${toRef}`, { cwd: workingDir });
+        let fileList = null;
+        if (includeFileList) {
+          const fileListResult = await run(`git diff --name-status ${fromRef}..${toRef}`, { cwd: workingDir });
+          fileList = fileListResult.stdout;
+        }
+        return {
+          fromRef,
+          toRef,
+          stats: statsResult.stdout.trim() || "No differences",
+          fileList
+        };
+      } catch (error) {
+        throw new Error(`Failed to get diff stats: ${error.message}`);
+      }
+    }
+  };
+}
+function createCheckConflictsTool() {
+  return {
+    name: "check_conflicts",
+    description: "Check if merging one branch into another would result in conflicts (without actually performing the merge)",
+    parameters: {
+      type: "object",
+      properties: {
+        sourceBranch: {
+          type: "string",
+          description: "Branch to merge from"
+        },
+        targetBranch: {
+          type: "string",
+          description: "Branch to merge into"
+        }
+      },
+      required: ["sourceBranch", "targetBranch"]
+    },
+    execute: async (params, context) => {
+      const { sourceBranch, targetBranch } = params;
+      const workingDir = context?.workingDirectory || process.cwd();
+      try {
+        const mergeBaseResult = await run(
+          `git merge-base ${targetBranch} ${sourceBranch}`,
+          { cwd: workingDir }
+        );
+        const mergeBase = mergeBaseResult.stdout.trim();
+        const mergeTreeResult = await run(
+          `git merge-tree ${mergeBase} ${targetBranch} ${sourceBranch}`,
+          { cwd: workingDir }
+        );
+        const hasConflicts = mergeTreeResult.stdout.includes("<<<<<<<") || mergeTreeResult.stdout.includes(">>>>>>>") || mergeTreeResult.stdout.includes("=======");
+        const conflicts = hasConflicts ? mergeTreeResult.stdout.match(/\+\+\+ b\/([^\n]+)/g)?.map((m) => m.replace(/\+\+\+ b\//, "")) : [];
+        return {
+          sourceBranch,
+          targetBranch,
+          mergeBase,
+          hasConflicts,
+          conflictingFiles: conflicts || [],
+          message: hasConflicts ? `Merging ${sourceBranch} into ${targetBranch} would create conflicts` : `Merging ${sourceBranch} into ${targetBranch} should succeed without conflicts`
+        };
+      } catch (error) {
+        throw new Error(`Failed to check conflicts: ${error.message}`);
+      }
+    }
+  };
+}
+function createResetBranchTool() {
+  return {
+    name: "reset_branch",
+    description: "Reset a branch to match another ref (e.g., reset local main to origin/main). USE WITH CAUTION - this is a destructive operation.",
+    parameters: {
+      type: "object",
+      properties: {
+        branchName: {
+          type: "string",
+          description: "Name of the branch to reset"
+        },
+        targetRef: {
+          type: "string",
+          description: 'Ref to reset to (e.g., "origin/main")'
+        },
+        resetType: {
+          type: "string",
+          description: 'Type of reset: "hard" (discard changes), "soft" (keep changes staged), "mixed" (keep changes unstaged)',
+          enum: ["hard", "soft", "mixed"],
+          default: "hard"
+        }
+      },
+      required: ["branchName", "targetRef"]
+    },
+    execute: async (params, context) => {
+      const { branchName, targetRef, resetType = "hard" } = params;
+      const workingDir = context?.workingDirectory || process.cwd();
+      try {
+        await run(`git checkout ${branchName}`, { cwd: workingDir });
+        await run(`git reset --${resetType} ${targetRef}`, { cwd: workingDir });
+        const headResult = await run("git rev-parse --short HEAD", { cwd: workingDir });
+        const newHead = headResult.stdout.trim();
+        return {
+          branchName,
+          targetRef,
+          resetType,
+          newHead,
+          message: `Successfully reset ${branchName} to ${targetRef} (${resetType})`
+        };
+      } catch (error) {
+        throw new Error(`Failed to reset branch: ${error.message}`);
+      }
+    }
+  };
+}
+async function runAgenticPublish(config) {
+  const {
+    targetBranch,
+    sourceBranch,
+    issue,
+    issueDetails,
+    workingDirectory = process.cwd(),
+    model = "gpt-4o",
+    maxIterations = 10,
+    debug = false,
+    storage,
+    logger: logger2,
+    dryRun = false
+  } = config;
+  const toolContext = {
+    workingDirectory,
+    storage,
+    logger: logger2
+  };
+  const tools = createToolRegistry(toolContext);
+  tools.registerAll(createPublishTools());
+  const systemPrompt = buildSystemPrompt(issue, dryRun);
+  const userPrompt = buildUserPrompt({
+    issue,
+    targetBranch,
+    sourceBranch,
+    issueDetails
+  });
+  const messages = [
+    {
+      role: "system",
+      content: systemPrompt
+    },
+    {
+      role: "user",
+      content: userPrompt
+    }
+  ];
+  const executor = new AgenticExecutor(logger2);
+  const result = await executor.run({
+    messages,
+    tools,
+    model,
+    maxIterations,
+    debug,
+    storage,
+    logger: logger2
+  });
+  const analysis = parseAgentResponse(result.finalMessage);
+  return {
+    success: analysis.success,
+    message: result.finalMessage,
+    actionsTaken: analysis.actionsTaken,
+    iterations: result.iterations,
+    toolCallsExecuted: result.toolCallsExecuted,
+    requiresManualIntervention: analysis.requiresManualIntervention,
+    manualSteps: analysis.manualSteps
+  };
+}
+function buildSystemPrompt(issue, dryRun) {
+  const modeNote = dryRun ? "\n\nIMPORTANT: This is a DRY RUN. Do not use tools that make destructive changes (like reset_branch or sync_branch). Only use diagnostic tools to analyze the issue and provide recommendations." : "";
+  return `You are an expert Git operations assistant helping to diagnose and fix issues that prevent publishing a software package.
+
+Your role is to:
+1. Use the available tools to investigate the problem
+2. Analyze the root cause of the issue
+3. ${dryRun ? "Recommend" : "Attempt to fix"} the issue using best practices
+4. Provide clear explanations of what you found and ${dryRun ? "would do" : "did"}
+
+Available tools allow you to:
+- Check git status and branch information
+- Analyze divergence between branches
+- View commit logs and diff statistics
+- Check for potential merge conflicts
+${dryRun ? "" : "- Sync branches with remote\n- Reset branches to match remote refs"}
+
+Guidelines:
+- Always diagnose before taking action
+- Prefer safe, non-destructive operations when possible
+- If a situation requires manual intervention, clearly state why and provide steps
+- Be thorough in your analysis
+- Consider the impact of each action on the repository state
+
+Current issue type: ${issue}${modeNote}`;
+}
+function buildUserPrompt(params) {
+  const { issue, targetBranch, sourceBranch, issueDetails } = params;
+  const issueDescriptions = {
+    branch_sync: `The target branch '${targetBranch}' is not synchronized with its remote counterpart. This prevents the publish workflow from proceeding safely.`,
+    uncommitted_changes: `There are uncommitted changes in the working directory on branch '${sourceBranch}'. The publish workflow requires a clean working directory.`,
+    merge_conflicts: `There are merge conflicts between '${sourceBranch}' and '${targetBranch}' that need to be resolved before publishing.`,
+    unknown: `An unknown issue is preventing the publish workflow from proceeding.`
+  };
+  const basePrompt = `I'm trying to run a publish workflow that will:
+1. Create a release from source branch '${sourceBranch}'
+2. Merge it into target branch '${targetBranch}'
+3. Publish the package
+
+However, I'm encountering an issue:
+
+${issueDescriptions[issue] || issueDescriptions.unknown}`;
+  const detailsSection = issueDetails ? `
+
+Additional details:
+${issueDetails}` : "";
+  return `${basePrompt}${detailsSection}
+
+Please investigate this issue and ${process.env.DRY_RUN ? "recommend how to fix it" : "attempt to fix it if possible"}. Use the available tools to:
+
+1. Diagnose the exact problem
+2. Understand what caused it (e.g., what commits are causing divergence)
+3. ${process.env.DRY_RUN ? "Recommend a solution" : "Attempt to resolve it safely"}
+4. Explain what ${process.env.DRY_RUN ? "should be" : "was"} done and why
+
+If the issue requires manual intervention, please explain why and provide clear steps.`;
+}
+function parseAgentResponse(message) {
+  const successIndicators = [
+    "successfully",
+    "resolved",
+    "fixed",
+    "synced",
+    "safe to proceed",
+    "ready to publish"
+  ];
+  const manualInterventionIndicators = [
+    "requires manual",
+    "manual intervention",
+    "cannot automatically",
+    "you will need to",
+    "please manually"
+  ];
+  const messageLower = message.toLowerCase();
+  const hasSuccessIndicator = successIndicators.some((indicator) => messageLower.includes(indicator));
+  const hasManualIndicator = manualInterventionIndicators.some((indicator) => messageLower.includes(indicator));
+  const actionsTaken = [];
+  const actionPatterns = [
+    /(?:I |We )?(checked|analyzed|found|discovered|synced|reset|merged|fetched|pulled|compared|investigated)\s+([^.\n]+)/gi,
+    /(?:Successfully|Successfully)\s+([^.\n]+)/gi
+  ];
+  for (const pattern of actionPatterns) {
+    const matches = message.matchAll(pattern);
+    for (const match of matches) {
+      actionsTaken.push(match[0].trim());
+    }
+  }
+  const manualSteps = [];
+  const stepPatterns = [
+    /(?:Step \d+:|^\d+\.)\s*(.+)$/gim,
+    /^[-*]\s+(.+)$/gim
+  ];
+  if (hasManualIndicator) {
+    for (const pattern of stepPatterns) {
+      const matches = message.matchAll(pattern);
+      for (const match of matches) {
+        const step = match[1]?.trim();
+        if (step && step.length > 10) {
+          manualSteps.push(step);
+        }
+      }
+    }
+  }
+  return {
+    success: hasSuccessIndicator && !hasManualIndicator,
+    actionsTaken: [...new Set(actionsTaken)],
+    // Remove duplicates
+    requiresManualIntervention: hasManualIndicator,
+    manualSteps: [...new Set(manualSteps)]
+    // Remove duplicates
+  };
+}
+function formatAgenticPublishResult(result) {
+  const lines = [];
+  lines.push("");
+  lines.push("═══════════════════════════════════════════════════════════");
+  lines.push("         AGENTIC PUBLISH RECOVERY REPORT");
+  lines.push("═══════════════════════════════════════════════════════════");
+  lines.push("");
+  if (result.success) {
+    lines.push("✅ Status: RESOLVED");
+  } else if (result.requiresManualIntervention) {
+    lines.push("⚠️  Status: MANUAL INTERVENTION REQUIRED");
+  } else {
+    lines.push("❌ Status: UNRESOLVED");
+  }
+  lines.push("");
+  lines.push(`Iterations: ${result.iterations}`);
+  lines.push(`Tools executed: ${result.toolCallsExecuted}`);
+  lines.push("");
+  if (result.actionsTaken.length > 0) {
+    lines.push("Actions taken:");
+    for (const action of result.actionsTaken) {
+      lines.push(`  • ${action}`);
+    }
+    lines.push("");
+  }
+  if (result.requiresManualIntervention && result.manualSteps && result.manualSteps.length > 0) {
+    lines.push("Manual steps required:");
+    for (let i = 0; i < result.manualSteps.length; i++) {
+      lines.push(`  ${i + 1}. ${result.manualSteps[i]}`);
+    }
+    lines.push("");
+  }
+  lines.push("Detailed analysis:");
+  lines.push("───────────────────────────────────────────────────────────");
+  lines.push(result.message);
+  lines.push("───────────────────────────────────────────────────────────");
+  lines.push("");
+  if (result.success) {
+    lines.push("You can now retry the publish command.");
+  } else if (result.requiresManualIntervention) {
+    lines.push("Please complete the manual steps above, then retry the publish command.");
+  } else {
+    lines.push("The issue could not be resolved automatically. Please review the analysis above.");
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+function createConversationLogger(config) {
+  const {
+    outputDir,
+    format = "json",
+    storage,
+    logger: logger2
+  } = config;
+  return {
+    /**
+     * Save a conversation to disk
+     */
+    async save(conversationId, messages, metadata) {
+      try {
+        if (!storage) {
+          throw new Error("Storage adapter required");
+        }
+        const conversation = {
+          id: conversationId,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          messages,
+          metadata: metadata || {}
+        };
+        const filename = `${conversationId}.${format}`;
+        const filepath = path__default.join(outputDir, filename);
+        const content = format === "json" ? JSON.stringify(conversation, null, 2) : formatConversationAsMarkdown(conversation);
+        await storage.writeOutput(filename, content);
+        if (logger2) {
+          logger2.debug(`Logged conversation ${conversationId} to ${filepath}`);
+        }
+        return filepath;
+      } catch (error) {
+        if (logger2) {
+          logger2.warn(`Failed to log conversation ${conversationId}: ${error.message}`);
+        }
+        throw error;
+      }
+    },
+    /**
+     * Load a conversation from disk
+     */
+    async load(conversationId) {
+      try {
+        if (!storage) {
+          throw new Error("Storage adapter required");
+        }
+        const filename = `${conversationId}.${format}`;
+        const content = await storage.readFile(path__default.join(outputDir, filename), "utf-8");
+        let conversation;
+        if (format === "json") {
+          try {
+            conversation = JSON.parse(content);
+          } catch (parseError) {
+            throw new Error(`Failed to parse conversation JSON: ${parseError.message}`);
+          }
+        } else {
+          conversation = content;
+        }
+        if (logger2) {
+          logger2.info(`Loaded conversation ${conversationId}`);
+        }
+        return conversation;
+      } catch (error) {
+        if (logger2) {
+          logger2.warn(`Failed to load conversation ${conversationId}: ${error.message}`);
+        }
+        throw error;
+      }
+    },
+    /**
+     * Get conversation summary
+     */
+    async getSummary(conversationId) {
+      try {
+        const conversation = await this.load(conversationId);
+        return {
+          id: conversation.id,
+          timestamp: conversation.timestamp,
+          messageCount: conversation.messages?.length || 0,
+          metadata: conversation.metadata
+        };
+      } catch (error) {
+        if (logger2) {
+          logger2.warn(`Failed to get summary for ${conversationId}: ${error.message}`);
+        }
+        throw error;
+      }
+    },
+    /**
+     * Create riotprompt ConversationLogger instance for advanced usage
+     */
+    createRiotLogger() {
+      const logConfig = {
+        enabled: true,
+        outputPath: outputDir,
+        format,
+        includeMetadata: true
+      };
+      return new ConversationLogger(logConfig, logger2);
+    }
+  };
+}
+function formatConversationAsMarkdown(conversation) {
+  const lines = [];
+  lines.push(`# Conversation: ${conversation.id}`);
+  lines.push("");
+  lines.push(`**Timestamp:** ${conversation.timestamp}`);
+  if (conversation.metadata) {
+    lines.push("");
+    lines.push("## Metadata");
+    lines.push("```json");
+    lines.push(JSON.stringify(conversation.metadata, null, 2));
+    lines.push("```");
+  }
+  lines.push("");
+  lines.push("## Messages");
+  lines.push("");
+  for (let i = 0; i < conversation.messages.length; i++) {
+    const msg = conversation.messages[i];
+    lines.push(`### Message ${i + 1}: ${msg.role}`);
+    lines.push("");
+    lines.push(msg.content || "(no content)");
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+function generateConversationId(command) {
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").split(".")[0];
+  return `${command}-${timestamp}`;
+}
+async function generateReflectionReport(options) {
+  const {
+    iterations,
+    toolCallsExecuted,
+    maxIterations,
+    toolMetrics,
+    conversationHistory,
+    commitMessage,
+    suggestedSplits,
+    releaseNotes,
+    logger: logger2
+  } = options;
+  const sections = [];
+  sections.push("# Agentic Workflow - Self-Reflection Report");
+  sections.push("");
+  sections.push(`Generated: ${(/* @__PURE__ */ new Date()).toISOString()}`);
+  sections.push("");
+  sections.push("## Execution Summary");
+  sections.push("");
+  sections.push(`- **Iterations**: ${iterations}${iterations >= maxIterations ? " (max reached)" : ""}`);
+  sections.push(`- **Tool Calls**: ${toolCallsExecuted}`);
+  sections.push(`- **Unique Tools**: ${new Set(toolMetrics.map((m) => m.name)).size}`);
+  sections.push("");
+  const toolStats = calculateToolStats(toolMetrics);
+  sections.push("## Tool Effectiveness Analysis");
+  sections.push("");
+  if (toolStats.size === 0) {
+    sections.push("*No tools were executed during this run.*");
+  } else {
+    sections.push("| Tool | Calls | Success | Failures | Success Rate | Avg Duration |");
+    sections.push("|------|-------|---------|----------|--------------|--------------|");
+    for (const [toolName, stats] of Array.from(toolStats.entries()).sort((a, b) => b[1].total - a[1].total)) {
+      const successRate = stats.total > 0 ? (stats.success / stats.total * 100).toFixed(1) : "0.0";
+      const avgDuration = stats.total > 0 ? (stats.totalDuration / stats.total).toFixed(0) : "0";
+      sections.push(`| ${toolName} | ${stats.total} | ${stats.success} | ${stats.failures} | ${successRate}% | ${avgDuration}ms |`);
+    }
+  }
+  sections.push("");
+  if (toolStats.size > 0) {
+    sections.push("### Tool Performance Insights");
+    sections.push("");
+    const failedTools = Array.from(toolStats.entries()).filter(([_, stats]) => stats.failures > 0);
+    if (failedTools.length > 0) {
+      sections.push("**Tools with Failures:**");
+      for (const [toolName, stats] of failedTools) {
+        const failureRate = stats.total > 0 ? (stats.failures / stats.total * 100).toFixed(1) : "0.0";
+        sections.push(`- ${toolName}: ${stats.failures}/${stats.total} failures (${failureRate}%)`);
+      }
+      sections.push("");
+    }
+    const slowTools = Array.from(toolStats.entries()).filter(([_, stats]) => stats.total > 0 && stats.totalDuration / stats.total > 1e3).sort((a, b) => {
+      const avgA = a[1].total > 0 ? a[1].totalDuration / a[1].total : 0;
+      const avgB = b[1].total > 0 ? b[1].totalDuration / b[1].total : 0;
+      return avgB - avgA;
+    });
+    if (slowTools.length > 0) {
+      sections.push("**Slow Tools (>1s average):**");
+      for (const [toolName, stats] of slowTools) {
+        const avgDuration = stats.total > 0 ? (stats.totalDuration / stats.total / 1e3).toFixed(2) : "0.00";
+        sections.push(`- ${toolName}: ${avgDuration}s average`);
+      }
+      sections.push("");
+    }
+    sections.push("**Most Frequently Used:**");
+    const topTools = Array.from(toolStats.entries()).slice(0, 3);
+    for (const [toolName, stats] of topTools) {
+      sections.push(`- ${toolName}: ${stats.total} calls`);
+    }
+    sections.push("");
+  }
+  sections.push("## Recommendations for Improvement");
+  sections.push("");
+  const recommendations = generateRecommendations(options, toolStats);
+  if (recommendations.length === 0) {
+    sections.push("*No specific recommendations at this time. Execution appears optimal.*");
+  } else {
+    for (const rec of recommendations) {
+      sections.push(rec);
+    }
+  }
+  sections.push("");
+  sections.push("## Detailed Execution Timeline");
+  sections.push("");
+  if (toolMetrics.length === 0) {
+    sections.push("*No tool execution timeline available.*");
+  } else {
+    sections.push("| Time | Iteration | Tool | Result | Duration |");
+    sections.push("|------|-----------|------|--------|----------|");
+    for (const metric of toolMetrics) {
+      const time = new Date(metric.timestamp).toLocaleTimeString();
+      const result = metric.success ? "✅ Success" : `❌ ${metric.error || "Failed"}`;
+      sections.push(`| ${time} | ${metric.iteration} | ${metric.name} | ${result} | ${metric.duration}ms |`);
+    }
+    sections.push("");
+  }
+  if (conversationHistory && conversationHistory.length > 0) {
+    sections.push("## Conversation History");
+    sections.push("");
+    sections.push("<details>");
+    sections.push("<summary>Click to expand full agentic interaction</summary>");
+    sections.push("");
+    sections.push("```json");
+    sections.push(JSON.stringify(conversationHistory, null, 2));
+    sections.push("```");
+    sections.push("");
+    sections.push("</details>");
+    sections.push("");
+  }
+  if (commitMessage) {
+    sections.push("## Generated Commit Message");
+    sections.push("");
+    sections.push("```");
+    sections.push(commitMessage);
+    sections.push("```");
+    sections.push("");
+    if (suggestedSplits && suggestedSplits.length > 1) {
+      sections.push("## Suggested Commit Splits");
+      sections.push("");
+      for (let i = 0; i < suggestedSplits.length; i++) {
+        const split = suggestedSplits[i];
+        sections.push(`### Split ${i + 1}`);
+        sections.push("");
+        sections.push(`**Files**: ${split.files.join(", ")}`);
+        sections.push("");
+        sections.push(`**Rationale**: ${split.rationale}`);
+        sections.push("");
+        sections.push(`**Message**:`);
+        sections.push("```");
+        sections.push(split.message);
+        sections.push("```");
+        sections.push("");
+      }
+    }
+  }
+  if (releaseNotes) {
+    sections.push("## Generated Release Notes");
+    sections.push("");
+    sections.push("### Title");
+    sections.push("```");
+    sections.push(releaseNotes.title);
+    sections.push("```");
+    sections.push("");
+    sections.push("### Body");
+    sections.push("```markdown");
+    sections.push(releaseNotes.body);
+    sections.push("```");
+    sections.push("");
+  }
+  if (logger2) {
+    logger2.debug(`Generated reflection report with ${toolStats.size} unique tools`);
+  }
+  return sections.join("\n");
+}
+function calculateToolStats(toolMetrics) {
+  const stats = /* @__PURE__ */ new Map();
+  for (const metric of toolMetrics) {
+    if (!stats.has(metric.name)) {
+      stats.set(metric.name, { total: 0, success: 0, failures: 0, totalDuration: 0 });
+    }
+    const toolStat = stats.get(metric.name);
+    toolStat.total++;
+    toolStat.totalDuration += metric.duration;
+    if (metric.success) {
+      toolStat.success++;
+    } else {
+      toolStat.failures++;
+    }
+  }
+  return stats;
+}
+function generateRecommendations(options, toolStats) {
+  const recommendations = [];
+  const toolsWithFailures = Array.from(toolStats.entries()).filter(([_, stats]) => stats.failures > 0);
+  if (toolsWithFailures.length > 0) {
+    recommendations.push("- **Tool Failures**: Investigate and fix tools that are failing. This may indicate issues with error handling or tool implementation.");
+  }
+  const slowTools = Array.from(toolStats.entries()).filter(([_, stats]) => stats.total > 0 && stats.totalDuration / stats.total > 1e3);
+  if (slowTools.length > 0) {
+    recommendations.push("- **Performance**: Consider optimizing slow tools or caching results to improve execution speed.");
+  }
+  if (options.iterations >= options.maxIterations) {
+    recommendations.push("- **Max Iterations Reached**: The agent reached maximum iterations. Consider increasing the limit or improving tool efficiency to allow the agent to complete naturally.");
+  }
+  const underutilizedTools = Array.from(toolStats.entries()).filter(([_, stats]) => stats.total === 1);
+  if (underutilizedTools.length > 3) {
+    recommendations.push("- **Underutilized Tools**: Many tools were called only once. Consider whether all tools are necessary or if the agent needs better guidance on when to use them.");
+  }
+  const uniqueTools = toolStats.size;
+  if (uniqueTools === 1 && options.toolCallsExecuted > 3) {
+    recommendations.push("- **Low Tool Diversity**: Only one tool was used despite multiple calls. Consider if the agent needs better guidance to use a variety of tools.");
+  }
+  return recommendations;
+}
+async function saveReflectionReport(report, outputPath, storage) {
+  if (!storage) {
+    throw new Error("Storage adapter required to save report");
+  }
+  const filename = outputPath.split("/").pop() || "reflection.md";
+  await storage.writeOutput(filename, report);
+}
+function createMetricsCollector(config = {}) {
+  const { logger: logger2 } = config;
+  const collector = new MetricsCollector(logger2);
+  const toolMetrics = [];
+  return {
+    /**
+     * Record a tool execution
+     */
+    recordToolExecution(metric) {
+      toolMetrics.push(metric);
+      collector.recordToolCall(
+        metric.name,
+        metric.iteration,
+        metric.duration,
+        metric.success,
+        metric.error
+      );
+      if (logger2) {
+        const status = metric.success ? "success" : "failed";
+        logger2.debug(`Tool ${metric.name} ${status} in ${metric.duration}ms`);
+      }
+    },
+    /**
+     * Record an iteration
+     */
+    recordIteration() {
+      collector.incrementIteration();
+      if (logger2) {
+        logger2.debug(`Iteration incremented`);
+      }
+    },
+    /**
+     * Get tool metrics in legacy format (for backward compatibility)
+     */
+    getToolMetrics() {
+      return [...toolMetrics];
+    },
+    /**
+     * Generate execution metrics report
+     */
+    generateReport() {
+      return collector.getMetrics([]);
+    },
+    /**
+     * Get summary statistics
+     */
+    getSummary() {
+      const report = collector.getMetrics([]);
+      return {
+        totalIterations: report.iterations,
+        totalToolCalls: report.toolCallsExecuted,
+        totalDuration: report.totalDuration,
+        toolMetrics: report.toolMetrics,
+        toolStats: report.toolStats
+      };
+    },
+    /**
+     * Reset all metrics
+     */
+    reset() {
+      toolMetrics.length = 0;
+    }
+  };
+}
 export {
   AgenticExecutor,
   OpenAIError,
   STANDARD_CHOICES,
   SecureTempFile,
+  TemplateNames,
   ToolRegistry,
   cleanupTempFile,
   createCommitPrompt,
   createCommitTools,
   createCompletion,
   createCompletionWithRetry,
+  createConversationLogger,
+  createMetricsCollector,
   createNoOpLogger,
+  createPublishTools,
   createReleasePrompt,
   createReleaseTools,
   createReviewPrompt,
   createSecureTempFile,
   createToolRegistry,
   editContentInEditor,
+  formatAgenticPublishResult,
+  generateConversationId,
+  generateReflectionReport,
   getLLMFeedbackInEditor,
   getLogger,
   getModelForCommand,
   getOpenAIReasoningForCommand,
   getUserChoice,
   getUserTextInput,
+  initializeTemplates,
   isRateLimitError,
   isTokenLimitError,
   requireTTY,
   runAgentic,
   runAgenticCommit,
+  runAgenticPublish,
   runAgenticRelease,
+  saveReflectionReport,
   setLogger,
   transcribeAudio,
   tryLoadWinston