@eldrforge/ai-service 0.1.15 → 0.1.17

package/LICENSE

@@ -175,7 +175,7 @@
 
    END OF TERMS AND CONDITIONS
 
-   Copyright 2025 Calen Varek
+   Copyright 2025 Tim O'Brien
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/README.md

@@ -4,7 +4,7 @@ AI-powered content generation library with agentic capabilities for commit messa
 
 ## Overview
 
-`@eldrforge/ai-service` is a TypeScript library that provides intelligent content generation powered by OpenAI's GPT models. It was extracted from the [kodrdriv](https://github.com/calenvarek/kodrdriv) automation tool to enable standalone use in any Node.js application.
+`@eldrforge/ai-service` is a TypeScript library that provides intelligent content generation powered by OpenAI's GPT models. It was extracted from the [kodrdriv](https://github.com/grunnverk/kodrdriv) automation tool to enable standalone use in any Node.js application.
 
 ### Key Features
 
@@ -1198,12 +1198,12 @@ Monitor usage with the `toolMetrics` data.
 
 ## Contributing
 
-Contributions are welcome! This library was extracted from [kodrdriv](https://github.com/calenvarek/kodrdriv).
+Contributions are welcome! This library was extracted from [kodrdriv](https://github.com/grunnverk/kodrdriv).
 
 ### Development Setup
 
 ```bash
-git clone https://github.com/calenvarek/ai-service.git
+git clone https://github.com/grunnverk/ai-service.git
 cd ai-service
 npm install
 npm run build
@@ -1224,15 +1224,15 @@ Apache-2.0
 
 ## Related Projects
 
-- **[kodrdriv](https://github.com/calenvarek/kodrdriv)** - Full automation toolkit that uses this library
+- **[kodrdriv](https://github.com/grunnverk/kodrdriv)** - Full automation toolkit that uses this library
 - **[@eldrforge/git-tools](https://www.npmjs.com/package/@eldrforge/git-tools)** - Git utility functions
 - **[@riotprompt/riotprompt](https://www.npmjs.com/package/@riotprompt/riotprompt)** - Structured prompt builder
 
 ## Support
 
-- 📖 [Full Documentation](https://github.com/calenvarek/ai-service)
-- 🐛 [Issue Tracker](https://github.com/calenvarek/ai-service/issues)
-- 💬 [Discussions](https://github.com/calenvarek/ai-service/discussions)
+- 📖 [Full Documentation](https://github.com/grunnverk/ai-service)
+- 🐛 [Issue Tracker](https://github.com/grunnverk/ai-service/issues)
+- 💬 [Discussions](https://github.com/grunnverk/ai-service/discussions)
 
 ## Changelog
 

package/dist/index.js

@@ -1,6 +1,7 @@
 import { OpenAI } from "openai";
 import { safeJsonParse, run, localBranchExists, isBranchInSyncWithRemote, safeSyncBranchWithRemote } from "@eldrforge/git-tools";
-import fs$1 from "fs";
+import * as fs$1 from "fs";
+import fs__default from "fs";
 import { spawnSync } from "child_process";
 import * as path from "path";
 import path__default from "path";
@@ -296,7 +297,7 @@ async function transcribeAudio(filePath, options = { model: "whisper-1" }) {
       await options.storage.writeTemp(debugFile, JSON.stringify(requestData, null, 2));
       logger2.debug("Wrote request debug file to %s", debugFile);
     }
-    audioStream = fs$1.createReadStream(filePath);
+    audioStream = fs__default.createReadStream(filePath);
     if (audioStream && typeof audioStream.on === "function") {
       audioStream.on("error", (streamError) => {
         logger2.error("Audio stream error: %s", streamError.message);
@@ -1143,7 +1144,8 @@ function createCommitTools() {
     createGetFileDependenciesTool$1(),
     createAnalyzeDiffSectionTool$1(),
     createGetRecentCommitsTool$1(),
-    createGroupFilesByConcernTool$1()
+    createGroupFilesByConcernTool$1(),
+    createGetFileModificationTimesTool()
   ];
 }
 function createGetFileHistoryTool$1() {
@@ -1562,6 +1564,115 @@ Suggestion: These ${groupCount} groups might be better as separate commits if th
     }
   };
 }
+function createGetFileModificationTimesTool() {
+  return {
+    name: "get_file_modification_times",
+    description: "Get modification timestamps for changed files. Temporal proximity is one signal (among others) that can help identify related changes. Files modified close together MAY be part of the same logical change, but this is not guaranteed - always cross-reference with logical groupings.",
+    category: "Organization",
+    cost: "cheap",
+    examples: [
+      {
+        scenario: "Identify files modified together vs at different times",
+        params: { filePaths: ["src/auth.ts", "src/user.ts", "README.md", "tests/auth.test.ts"] },
+        expectedResult: "Files with timestamps grouped by temporal proximity"
+      }
+    ],
+    parameters: {
+      type: "object",
+      properties: {
+        filePaths: {
+          type: "array",
+          description: "All changed files to analyze",
+          items: { type: "string", description: "File path" }
+        }
+      },
+      required: ["filePaths"]
+    },
+    execute: async (params, context) => {
+      const { filePaths } = params;
+      const workingDir = context?.workingDirectory || process.cwd();
+      const fileInfos = [];
+      const errors = [];
+      for (const filePath of filePaths) {
+        try {
+          const fullPath = path.isAbsolute(filePath) ? filePath : path.join(workingDir, filePath);
+          const stat = fs$1.statSync(fullPath);
+          fileInfos.push({
+            file: filePath,
+            mtime: stat.mtime,
+            mtimeMs: stat.mtimeMs
+          });
+        } catch {
+          errors.push(filePath);
+        }
+      }
+      fileInfos.sort((a, b) => a.mtimeMs - b.mtimeMs);
+      const CLUSTER_THRESHOLD_MS = 10 * 60 * 1e3;
+      const clusters = [];
+      let currentCluster = [];
+      for (const info of fileInfos) {
+        if (currentCluster.length === 0) {
+          currentCluster.push(info);
+        } else {
+          const lastFile = currentCluster[currentCluster.length - 1];
+          if (info.mtimeMs - lastFile.mtimeMs <= CLUSTER_THRESHOLD_MS) {
+            currentCluster.push(info);
+          } else {
+            clusters.push(currentCluster);
+            currentCluster = [info];
+          }
+        }
+      }
+      if (currentCluster.length > 0) {
+        clusters.push(currentCluster);
+      }
+      let output = `## File Modification Times (sorted oldest to newest)
+
+`;
+      for (const info of fileInfos) {
+        const timeStr = info.mtime.toISOString().replace("T", " ").replace(/\.\d{3}Z$/, "");
+        output += `${timeStr}  ${info.file}
+`;
+      }
+      if (errors.length > 0) {
+        output += `
+## Files not found (possibly deleted):
+`;
+        output += errors.map((f) => `  - ${f}`).join("\n");
+      }
+      output += `
+
+## Temporal Clusters (files modified within 10 minutes of each other)
+
+`;
+      if (clusters.length === 1) {
+        output += `All ${fileInfos.length} files were modified in a single work session.
+`;
+      } else {
+        output += `Found ${clusters.length} distinct work sessions:
+
+`;
+        clusters.forEach((cluster, idx) => {
+          const startTime = cluster[0].mtime.toISOString().replace("T", " ").replace(/\.\d{3}Z$/, "");
+          const endTime = cluster[cluster.length - 1].mtime.toISOString().replace("T", " ").replace(/\.\d{3}Z$/, "");
+          const durationMs = cluster[cluster.length - 1].mtimeMs - cluster[0].mtimeMs;
+          const durationMins = Math.round(durationMs / 6e4);
+          output += `### Session ${idx + 1} (${cluster.length} files, ${durationMins} min span)
+`;
+          output += `Time: ${startTime} to ${endTime}
+`;
+          output += `Files:
+`;
+          output += cluster.map((f) => `  - ${f.file}`).join("\n");
+          output += "\n\n";
+        });
+        output += `
+**Note**: These ${clusters.length} temporal clusters may indicate separate work sessions. Cross-reference with logical groupings to determine if they represent distinct changes worth splitting.`;
+      }
+      return output;
+    }
+  };
+}
 async function runAgenticCommit(config) {
   const {
     changedFiles,
@@ -1627,52 +1738,120 @@ async function runAgenticCommit(config) {
   };
 }
 function buildSystemPrompt$2(toolGuidance) {
-  return `You are an expert software engineer tasked with generating meaningful commit messages.
+  return `You are a professional software engineer writing commit messages for your team.
 
 ${toolGuidance}
 
+## Your Task
+
+Analyze the staged changes and determine the best way to commit them. Your primary goal is to create **meaningful, atomic commits** that each represent a single logical change.
+
+**CRITICAL**: When there are many changed files, especially after a long work session (multiple hours), you should almost always split them into multiple commits. A single commit with 10+ files usually indicates multiple distinct changes that should be separated.
+
+Think about:
+- What distinct features, fixes, or improvements are represented?
+- Are there natural groupings by functionality, module, or purpose?
+- When were files modified relative to each other?
+- What should reviewers focus on in each commit?
+
 ## Investigation Strategy
 
-For simple changes (1-3 files, obvious purpose):
-- Use 1-2 tools: get_recent_commits to avoid duplicates, get_related_tests if logic changed
+For any non-trivial set of changes, gather multiple signals to understand how to group commits:
+
+1. **Check file modification times** using \`get_file_modification_times\`
+   - This reveals *when* files were changed relative to each other
+   - Files modified close together *may* be part of the same logical change
+   - Large temporal gaps *can* indicate separate work sessions
+   - Note: temporal proximity is one signal, not a guarantee of relatedness
+
+2. **Understand logical relationships** using \`group_files_by_concern\`
+   - Groups by module, type (tests, docs, source), and directory structure
+   - Reveals which files are functionally related regardless of when they were modified
+
+3. **Cross-reference both signals** to make informed decisions:
+   - Files modified together AND logically related → strong candidate for same commit
+   - Files modified apart BUT logically related → might still belong together
+   - Files modified together BUT logically unrelated → consider splitting
+   - Use your judgment - neither signal is definitive on its own
+
+4. **Investigate further** as needed:
+   - 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
+
+## When to Split Commits
+
+**Prefer multiple commits when:**
+- Changes span multiple hours of work (check modification times!)
+- Different logical features or fixes are included
+- Test changes could be separated from production code changes
+- Documentation updates are unrelated to code changes
+- Refactoring is mixed with feature work
+- Configuration changes are mixed with implementation changes
+- Files in different modules/packages are changed for different reasons
+
+**Keep as one commit when:**
+- All changes are part of a single, cohesive feature
+- Files were modified together in a focused work session
+- Test changes directly test the production code changes
+- The changes tell a single coherent story
+
+**Default bias**: When in doubt about whether to split, **prefer splitting**. It's better to have too many focused commits than too few bloated ones. A good commit should be understandable and reviewable in isolation.
+
+## Important Context Guidelines
+
+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
 
-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 - only for the FIRST group of changes if splitting]
 
-If you recommend splitting into multiple commits, also include:
+If changes should be split into multiple commits (which is often the case with large changesets):
 
 SUGGESTED_SPLITS:
 Split 1:
 Files: [list of files]
-Rationale: [why these belong together]
+Rationale: [why these belong together - mention temporal clustering and/or logical relationship]
 Message: [commit message for this split]
 
 Split 2:
+Files: [list of files]
+Rationale: [why these belong together]
+Message: [commit message for this split]
+
+Split 3:
 ...
 
-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) {
+  const fileCount = changedFiles.length;
+  const manyFiles = fileCount >= 5;
   let message = `I have staged changes that need a commit message.
 
-Changed files (${changedFiles.length}):
+Changed files (${fileCount}):
 ${changedFiles.map((f) => `  - ${f}`).join("\n")}
 
 Diff:
@@ -1690,9 +1869,24 @@ ${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.`;
+## Your Analysis Task
+
+${manyFiles ? `With ${fileCount} files changed, consider whether these represent multiple distinct changes that should be split into separate commits.
+
+` : ""}Gather signals to understand the changes:
+1. Use \`get_file_modification_times\` to see when files were modified relative to each other
+2. Use \`group_files_by_concern\` to understand how files relate by type/purpose
+3. Cross-reference both signals - temporal proximity and logical relatedness - to determine the best commit structure
+
+Consider:
+- What distinct features, fixes, or improvements are included?
+- Are files that were modified together also logically related?
+- Would separate commits make the history more understandable?
+
+${manyFiles ? "With many files, consider whether multiple focused commits would be clearer than one large commit." : "If changes represent multiple logical concerns, suggest splits."}
+
+If context information is provided, use it only if relevant to these specific changes.
+Don't force connections that don't exist - focus on what actually changed.`;
   return message;
 }
 function parseAgenticResult$1(finalMessage) {
@@ -2455,56 +2649,79 @@ async function runAgenticRelease(config) {
   };
 }
 function buildSystemPrompt$1(toolGuidance) {
-  return `You are an expert software engineer and technical writer tasked with generating comprehensive, thoughtful release notes.
+  return `You are a professional software engineer writing release notes for your team and users.
 
 ${toolGuidance}
-- get_tag_history: Use early to understand release cadence. Good for: establishing context about project versioning patterns
 
-**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
+## 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.
 
-**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
+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?
 
-**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
+Use the available tools to investigate the changes. The more you understand, the better your notes will be.
 
-## Your Investigation Strategy
+**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
 
-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
+## Investigation Approach
 
-Use at least 6-8 tools per release to ensure comprehensive analysis. Each tool provides a different lens on the changes.
+Use tools based on what you need to know:
 
-Output format:
-When you're ready to provide the final release notes, format them as JSON:
+**Context:**
+- get_tag_history - understand release patterns
+- get_release_stats - quantify scope
+- compare_previous_release - see how this compares
+
+**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
+
+**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)
+
+## Writing Style
+
+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
+
+Structure your notes logically:
+- Start with the most important changes
+- Group related changes together
+- Explain breaking changes clearly
+- Include practical examples when helpful
+
+## Output Format
+
+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;
@@ -2537,15 +2754,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?
+
+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.
 
-Use the available tools to gather additional context as needed. Take your time to understand the changes deeply before writing the release notes.`;
+Investigate as needed to write accurate, helpful release notes.`;
   return message;
 }
 function parseAgenticResult(finalMessage) {