@eldrforge/ai-service 0.1.16 → 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,
@@ -1633,32 +1744,70 @@ ${toolGuidance}
 
 ## Your Task
 
-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.
-
-Think about:
-- What problem does this solve?
-- How do the changes work together?
-- What should reviewers focus on?
-- Are there any important implications?
+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.
 
-Use the available tools to investigate the changes. The more you understand, the better your message will be.
+**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.
 
-**Important**: If additional context is provided (from context files or other sources), use your judgment:
+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 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 in this commit
-
-## Investigation Approach
-
-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
+- Focus on accurately describing what actually changed
 
 ## Writing Style
 
@@ -1677,25 +1826,32 @@ Follow conventional commit format when appropriate (feat:, fix:, refactor:, docs
 When ready, format your response as:
 
 COMMIT_MESSAGE:
-[Your commit message here]
+[Your commit message here - only for the FIRST group of changes if splitting]
 
-If changes should be split into multiple commits:
+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:
 ...
 
 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:
@@ -1713,16 +1869,24 @@ ${logContext}`;
   }
   message += `
 
-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?
+## Your Analysis Task
 
-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.
+${manyFiles ? `With ${fileCount} files changed, consider whether these represent multiple distinct changes that should be split into separate commits.
 
-Investigate as needed to write an accurate, helpful message.`;
+` : ""}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) {