codemini-cli 0.3.9 → 0.4.1

package/src/core/default-system-prompt.js

@@ -9,14 +9,14 @@ function getToolFewShotBlock() {
 Use these as style examples for tool calls:
 
 Current working directory: ${cwd}
-When a tool takes file_path, build it from the current working directory and prefer absolute paths.
+When a tool takes path, build it from the current working directory and prefer absolute paths.
 If the user mentions a project-relative path like src/app.ts, resolve it from ${cwd} instead of guessing parent directories.
 
 1. File discovery then read
 User: compare the auth flow
 Assistant: first narrow the search with the project index
 Tool: query_project_index({"query":"auth flow","path":"src","max_results":3})
-Tool: read({"file_path":"${cwd}/src/auth/service.ts"})
+Tool: read({"path":"${cwd}/src/auth/service.ts"})
 
 If the visible tool list does not include a needed capability, load it with tool_search instead of assuming it does not exist.
 Example:
@@ -27,7 +27,7 @@ Tool: glob({"pattern":"src/**/*.ts"})
 User: rename loginUser to signInUser
 Assistant: first find the exact occurrences
 Tool: grep({"pattern":"loginUser","path":"src"})
-Tool: edit({"file_path":"${cwd}/src/auth/service.ts","old_string":"loginUser","new_string":"signInUser"})
+Tool: edit({"path":"${cwd}/src/auth/service.ts","old_text":"loginUser","new_text":"signInUser"})
 
 3. Read a specific range
 User: inspect the reducer around line 120
@@ -43,11 +43,18 @@ Assistant: keep the checklist updated as each phase finishes, and do not give a
 5. Create a new file
 User: add a notes file
 Assistant: create the file directly
-Tool: write({"file":"${cwd}/notes.txt","text":"todo\\n"})
+Tool: write({"path":"${cwd}/notes.txt","content":"todo\\n"})
 
-6. Capture a high-signal observation during work
-When you notice a reusable pattern, a user correction, a repeated failure, or a stable preference — capture it to the dream loop inbox for later consolidation.
-Tool: capture_memory({"summary":"User prefers tab size 2 for all JSON files","scope":"global","type":"preference"})
+6. Save a high-signal observation to memory
+When you notice a reusable pattern, a user correction, a repeated failure, or a stable preference — save it to persistent memory. Choose scope carefully:
+- scope "user" for personal preferences (language, reply style, interaction habits)
+- scope "global" for cross-project lessons (environment quirks, general tool workflows)
+- scope "project" for project-specific knowledge (architecture conventions, local config, test commands, file locations)
+
+Examples:
+Tool: save_memory({"content":"User prefers tab size 2 for all JSON files","scope":"user","kind":"preference"})
+Tool: save_memory({"content":"This project uses vitest, not jest — run tests with npx vitest run","scope":"project","kind":"pattern"})
+Tool: save_memory({"content":"WSL2 bash exec prefix does not support cd as a command","scope":"global","kind":"correction"})
 
 7. Run a dream loop consolidation pass
 When you want to review and consolidate inbox entries into long-term memory.
@@ -66,7 +73,7 @@ Tool: tool_search({"query":"web_search"})
 Tool: web_search({"query":"latest pnpm release","max_results":5})
 
 Prefer these direct tool shapes over multi-step metadata reads or shell fallbacks.
-Prefer explicit absolute file_path values when the current working directory is known.`;
+Prefer explicit absolute path values when the current working directory is known.`;
 }
 
 function getEnvBlock() {

package/src/core/dream-consolidate.js

@@ -1,5 +1,6 @@
 import { listMemories, listInbox, archiveEntry, promoteMemory } from './memory-store.js';
 import { writeDreamAuditReport } from './dream-audit.js';
+import { evaluateInboxBatch } from './dream-evaluator.js';
 
 const LONGTERM_TYPES = new Set(['preference', 'pattern', 'win', 'decision']);
 const OPERATIONAL_TYPES = new Set(['correction', 'failure', 'gap', 'observation']);
@@ -8,14 +9,6 @@ function normalizeText(value) {
   return String(value || '').trim().toLowerCase();
 }
 
-function mapInboxScopeToMemoryScope(scope) {
-  const value = normalizeText(scope);
-  if (value === 'repo' || value === 'project') return 'project';
-  if (value === 'thread') return 'global';
-  if (value === 'user') return 'user';
-  return 'global';
-}
-
 function chooseLifecycle(type) {
   const value = normalizeText(type);
   if (LONGTERM_TYPES.has(value)) return 'longterm';
@@ -55,7 +48,10 @@ export async function runDreamConsolidation({
   const filesRead = ['memory/inbox/*', 'memory/global.json', 'memory/user.json', 'memory/project/*.json'];
   const filesChanged = [];
 
+  /* ── Phase 1: 规则预过滤（快速剔除明显垃圾） ─────────────────── */
+  const candidates = [];
   const seen = new Map();
+
   for (const entry of inbox) {
     const summaryKey = normalizeText(entry.summary);
     if (!summaryKey) {
@@ -78,14 +74,58 @@ export async function runDreamConsolidation({
       continue;
     }
 
-    const lifecycle = chooseLifecycle(entry.type);
-    const promoteScope = mapInboxScopeToMemoryScope(entry.scope);
+    candidates.push(entry);
+  }
+
+  if (candidates.length === 0) {
+    const report = { timestamp: new Date().toISOString(), filesRead, filesChanged: [], candidatesGenerated: inbox.length, promotions, rejections, archives };
+    if (!dryRun && writeAudit) {
+      const reportPath = await writeDreamAuditReport(report);
+      report.auditReport = reportPath;
+    }
+    return { ok: true, dryRun, ...report };
+  }
+
+  /* ── Phase 2: LLM 批量评估（质量门控 + scope 分类 + 内容提炼） ── */
+  const llmResults = dryRun
+    ? candidates.map((e) => ({ id: e.id, action: 'keep', scope: 'global', kind: e.type || 'observation', content: e.details || e.summary, summary: e.summary, confidence: 0.9 }))
+    : await evaluateInboxBatch({ entries: candidates, config, workspaceRoot });
+
+  const resultMap = new Map(llmResults.map((r) => [r.id, r]));
+
+  /* ── Phase 3: 按评估结果 promote 或 archive ─────────────────── */
+  for (const entry of candidates) {
+    const evaluation = resultMap.get(entry.id);
+
+    if (!evaluation || evaluation.action === 'discard') {
+      const reason = evaluation?.reason || 'LLM discarded';
+      if (!dryRun) await archiveEntry(entry, 'discarded-by-evaluator', reason);
+      rejections.push({ summary: entry.summary, reason: `evaluator-discard: ${reason}` });
+      continue;
+    }
+
+    const promoteScope = evaluation.scope || 'global';
+    const lifecycle = chooseLifecycle(evaluation.kind);
+    const enrichedEntry = {
+      ...entry,
+      /* 用 LLM 提炼后的内容覆盖原始报错 */
+      summary: evaluation.summary || entry.summary,
+      details: evaluation.content || entry.details || entry.summary,
+      type: evaluation.kind || entry.type || 'observation'
+    };
 
     if (!dryRun) {
       try {
-        await promoteMemory({ entry, scope: promoteScope, lifecycle, workspaceRoot, config });
-        filesChanged.push({ file: `memory/${promoteScope}.json`, why: `Promoted "${entry.summary}" as ${lifecycle}` });
-        promotions.push({ summary: entry.summary, scope: promoteScope, lifecycle, rationale: entry.type });
+        await promoteMemory({
+          entry: enrichedEntry,
+          scope: promoteScope,
+          lifecycle,
+          workspaceRoot,
+          config,
+          confidence: evaluation.confidence || 0.8
+        });
+        filesChanged.push({ file: `memory/${promoteScope}.json`, why: `Promoted "${enrichedEntry.summary}" as ${lifecycle} (${promoteScope})` });
+        promotions.push({ summary: enrichedEntry.summary, scope: promoteScope, lifecycle, rationale: evaluation.kind, confidence: evaluation.confidence });
       } catch (error) {
         const reason = String(error?.message || error || 'promotion failed').slice(0, 180);
         await archiveEntry(entry, 'promotion-failed', reason);
@@ -95,7 +135,7 @@ export async function runDreamConsolidation({
       continue;
     }
 
-    promotions.push({ summary: entry.summary, scope: promoteScope, lifecycle, rationale: entry.type, dryRun: true });
+    promotions.push({ summary: enrichedEntry.summary, scope: promoteScope, lifecycle, rationale: evaluation.kind, confidence: evaluation.confidence, dryRun: true });
   }
 
   const report = {

package/src/core/dream-evaluator.js

@@ -0,0 +1,99 @@
+import { createChatCompletion } from './provider/index.js';
+
+const EVAL_TIMEOUT_MS = 30000;
+
+const SYSTEM_PROMPT = `You are a memory consolidation evaluator for a coding assistant. You receive a batch of inbox items (tool errors, observations, etc.) and decide for each one:
+
+1. **keep or discard** — Does this contain a reusable, durable insight? Discard transient errors, one-off issues, and noise.
+2. **scope** — "global" for cross-project knowledge (e.g., "WSL bash exec does not support cd"), "project" for project-specific context (e.g., "this project uses vitest for testing").
+3. **kind** — One of: pattern, observation, correction, decision, failure
+4. **content** — A refined, actionable sentence describing the insight. NOT the raw error text.
+5. **summary** — A short label (under 80 chars) for quick scanning.
+6. **confidence** — 0.5–1.0 based on how certain and durable the insight is.
+
+Respond with valid JSON only, no markdown fences:
+{"results":[{"id":"<inbox-id>","action":"keep","scope":"global|project","kind":"pattern|observation|correction|decision|failure","content":"...","summary":"...","confidence":0.8},{"id":"<inbox-id>","action":"discard","reason":"..."}]}
+
+Rules:
+- Raw tool error messages are NOT insights by themselves. Only keep if they reveal a reusable lesson.
+- "exit 127", "command not found", "permission denied", "blocked by policy" → always discard (transient/config issues)
+- A repeated pattern across multiple errors → keep as a "pattern" or "correction"
+- Project-specific paths, file names, or commands → scope "project"
+- General coding/environment knowledge → scope "global"
+- If in doubt, discard. Memory is expensive; only promote what future sessions will genuinely benefit from.`;
+
+function parseResults(text) {
+  try {
+    const json = JSON.parse(text);
+    if (!json?.results || !Array.isArray(json.results)) return [];
+    return json.results.map((r) => ({
+      id: String(r.id || ''),
+      action: r.action === 'keep' ? 'keep' : 'discard',
+      scope: r.scope === 'project' ? 'project' : 'global',
+      kind: ['pattern', 'observation', 'correction', 'decision', 'failure'].includes(r.kind) ? r.kind : 'observation',
+      content: String(r.content || '').slice(0, 300),
+      summary: String(r.summary || '').slice(0, 120),
+      confidence: Math.min(1, Math.max(0.5, Number(r.confidence) || 0.7)),
+      reason: String(r.reason || '')
+    }));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * 用 LLM 批量评估 inbox 条目，决定保留/丢弃、scope、内容提炼。
+ * @param {{ entries: Array, config: object, workspaceRoot?: string }} params
+ * @returns {Promise<Array<{ id, action, scope?, kind?, content?, summary?, confidence?, reason? }>>}
+ */
+export async function evaluateInboxBatch({ entries, config, workspaceRoot }) {
+  if (!entries || entries.length === 0) return [];
+
+  const batch = entries.map((e) => ({
+    id: e.id,
+    type: e.type || '',
+    source: e.source || '',
+    summary: (e.summary || '').slice(0, 150),
+    details: (e.details || '').slice(0, 400)
+  }));
+
+  try {
+    const result = await createChatCompletion({
+      sdkProvider: config?.sdk?.provider,
+      baseUrl: config?.gateway?.base_url,
+      apiKey: config?.gateway?.api_key,
+      model: config?.model?.name,
+      messages: [
+        { role: 'system', content: SYSTEM_PROMPT },
+        {
+          role: 'user',
+          content: `Evaluate these ${batch.length} inbox items. Workspace: ${workspaceRoot || process.cwd()}\n\n${JSON.stringify(batch, null, 2)}`
+        }
+      ],
+      temperature: 0,
+      timeoutMs: EVAL_TIMEOUT_MS
+    });
+
+    const text = result?.text || '';
+    const parsed = parseResults(text);
+    /* 确保每个 entry 都有结果，LLM 没返回的一律 discard */
+    const covered = new Set(parsed.map((r) => r.id));
+    for (const entry of entries) {
+      if (!covered.has(entry.id)) {
+        parsed.push({
+          id: entry.id,
+          action: 'discard',
+          reason: 'LLM did not return a result for this entry'
+        });
+      }
+    }
+    return parsed;
+  } catch {
+    /* LLM 调用失败 → 全部 discard（fail-safe） */
+    return entries.map((e) => ({
+      id: e.id,
+      action: 'discard',
+      reason: 'LLM evaluation failed'
+    }));
+  }
+}

package/src/core/fff-adapter.js

@@ -111,7 +111,7 @@ class FffMcpClient {
       capabilities: {},
       clientInfo: {
         name: 'codemini-cli',
-        version: '0.3.9'
+        version: '0.4.1'
       }
     });
     this.sendNotification('notifications/initialized', {});

package/src/core/memory-store.js

@@ -375,7 +375,8 @@ export async function promoteMemory({
   lifecycle = 'operational',
   workspaceRoot = process.cwd(),
   projectAlias = '',
-  config = {}
+  config = {},
+  confidence = 0.9
 } = {}) {
   if (!entry?.summary) throw new Error('Entry with summary is required for promotion');
   const lc = validateLifecycle(lifecycle);
@@ -386,7 +387,7 @@ export async function promoteMemory({
     kind: entry.type || 'note',
     summary: normalizeMemoryText(entry.summary),
     source: `dream-promote:${entry.id}`,
-    confidence: 0.9,
+    confidence: Math.min(1, Math.max(0.5, confidence)),
     replaceSimilar: true,
     workspaceRoot,
     projectAlias,

package/src/core/paths.js

@@ -3,7 +3,7 @@ import path from 'node:path';
 
 const GLOBAL_APP_DIR = 'codemini-global';
 const PROJECT_APP_DIR = '.codemini';
-const PROJECT_INDEX_DIR = '.codemini-project';
+const PROJECT_INDEX_DIR = '.codemini';
 
 export function getBaseConfigDir() {
   if (process.env.CODEMINI_GLOBAL_DIR) {

package/src/core/project-index.js

@@ -387,7 +387,7 @@ export async function initializeProjectIndex(cwd = process.cwd()) {
       projectRoot: targetRoot,
       projectMap,
       fileIndex,
-      summary: `initialized ${path.basename(targetRoot) || '.'}/.codemini-project (${Array.isArray(fileIndex?.files) ? fileIndex.files.length : 0} files)`
+      summary: `initialized ${path.basename(targetRoot) || '.'}/.codemini (${Array.isArray(fileIndex?.files) ? fileIndex.files.length : 0} files)`
     };
   })();
   initCache.set(cacheKey, promise);
@@ -447,7 +447,7 @@ export async function refreshIndexedFile(cwd = process.cwd(), relativePath = '')
     path: projectRelativePath,
     projectRoot,
     action,
-    summary: `${action} ${path.basename(projectRoot) || '.'}/.codemini-project for ${projectRelativePath}`
+    summary: `${action} ${path.basename(projectRoot) || '.'}/.codemini for ${projectRelativePath}`
   };
 }
 

package/src/core/provider/openai-compatible.js

@@ -54,6 +54,36 @@ async function parseJsonResponse(response) {
   return response.json();
 }
 
+function isRetryableStatus(status) {
+  return status === 408 || status === 409 || status === 425 || status === 429 || status >= 500;
+}
+
+function isRetryableError(error) {
+  const name = String(error?.name || '');
+  if (name === 'AbortError' || name === 'TimeoutError') return false;
+  const message = String(error?.message || error || '');
+  return /fetch failed|network|socket|ECONNRESET|ETIMEDOUT|EAI_AGAIN/i.test(message);
+}
+
+async function fetchWithRetry(url, init, { maxRetries = 0 } = {}) {
+  const attempts = Math.max(0, Number(maxRetries) || 0) + 1;
+  let lastError;
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    try {
+      const response = await fetch(url, init);
+      if (response.ok || !isRetryableStatus(response.status) || attempt === attempts - 1) {
+        return response;
+      }
+      await response.arrayBuffer().catch(() => null);
+    } catch (error) {
+      lastError = error;
+      if (!isRetryableError(error) || attempt === attempts - 1) throw error;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 50 * (attempt + 1)));
+  }
+  throw lastError || new Error('Gateway request failed');
+}
+
 async function* iterateSseEvents(stream) {
   const decoder = new TextDecoder();
   let buffer = '';
@@ -318,12 +348,12 @@ export async function createChatCompletion({
   maxRetries = 2
 }) {
   const payload = buildPayload({ model, temperature, messages, tools });
-  const response = await fetch(buildChatCompletionsUrl(baseUrl), {
+  const response = await fetchWithRetry(buildChatCompletionsUrl(baseUrl), {
     method: 'POST',
     headers: createHeaders(apiKey),
     body: JSON.stringify(payload),
     signal: AbortSignal.timeout(timeoutMs)
-  });
+  }, { maxRetries });
   const data = await parseJsonResponse(response);
   const message = data?.choices?.[0]?.message || {};
   const text = sanitizeMiniMaxText(model, extractTextContent(message.content));
@@ -386,12 +416,12 @@ export async function createChatCompletionStream({
     }
   }
   const payload = buildPayload({ model, temperature, messages, tools, stream: true });
-  const response = await fetch(buildChatCompletionsUrl(baseUrl), {
+  const response = await fetchWithRetry(buildChatCompletionsUrl(baseUrl), {
     method: 'POST',
     headers: createHeaders(apiKey),
     body: JSON.stringify(payload),
     signal: controller.signal
-  });
+  }, { maxRetries });
   if (!response.ok || !response.body) {
     const text = await response.text().catch(() => '');
     throw new Error(`Gateway error ${response.status}: ${text || response.statusText}`);
@@ -402,7 +432,8 @@ export async function createChatCompletionStream({
   let usage = null;
   let miniMaxStreamState = { rawContent: '', visibleText: '' };
 
-  for await (const chunk of iterateSseEvents(response.body)) {
+  try {
+    for await (const chunk of iterateSseEvents(response.body)) {
     usage = chunk?.usage || usage;
     const choice0 = chunk?.choices?.[0] || {};
     const delta = choice0?.delta || {};
@@ -452,6 +483,10 @@ export async function createChatCompletionStream({
     if (choice0?.finish_reason) {
       break;
     }
+    }
+  } finally {
+    timeoutSignal.removeEventListener('abort', onAbort);
+    if (externalSignal) externalSignal.removeEventListener('abort', onAbort);
   }
 
   const result = buildFinalStreamResult(text, toolCallsByIndex, usage, messages);

package/src/core/shell-profile.js

@@ -23,8 +23,10 @@ const SHELL_PROFILES = {
       'npm',
       'npx',
       'python',
+      'python3',
       'py',
       'pip',
+      'pip3',
       'get-childitem',
       'get-content',
       'select-string',
@@ -70,7 +72,9 @@ const SHELL_PROFILES = {
       'npm',
       'npx',
       'python',
+      'python3',
       'pip',
+      'pip3',
       'ls',
       'cat',
       'sed',
@@ -142,11 +146,11 @@ export function getShellSystemPrompt(value) {
 ALWAYS prefer dedicated tools over raw shell commands:
 - The visible default tool list is intentionally small. If a needed capability is not currently listed, do not assume it is unavailable — call tool_search to load additional tools first
 - Use query_project_index first for broad repository understanding. It combines project-map metadata with indexed file symbols so you can narrow candidates before reading source files
-- Use read to inspect files — NEVER use cat, head, or tail via run. read returns content directly by default; demo-style shapes like {file_path:"src/app.ts"}, {path:"src/app.ts:10-40"}, or {file_path:"src/app.ts", offset:10, limit:30} are accepted
+- Use read to inspect files — NEVER use cat, head, or tail via run. Use canonical shapes like {path:"src/app.ts"}, {path:"src/app.ts:10-40"}, or {path:"src/app.ts", start_line:10, end_line:40}
 - Use grep to search file contents — NEVER use grep or rg via run
 - Use list for directory-by-directory filesystem discovery. If you specifically need pattern-based file lookup like src/**/*.ts, load glob with tool_search instead of falling back to run
-- Use edit to modify existing files — this is the DEFAULT path for code changes. Demo-style aliases like {file_path:"src/app.ts", old_string:"foo", new_string:"bar"} are accepted
-- Use write only for creating new files or complete rewrites (set full_file_rewrite=true for existing code files). Aliases like {file:"notes.txt", text:"..."} are accepted
+- Use edit to modify existing files — this is the DEFAULT path for code changes. Prefer {path:"src/app.ts", old_text:"foo", new_text:"bar"}
+- Use write only for creating new files or complete rewrites (set full_file_rewrite=true for existing code files). Prefer {path:"notes.txt", content:"..."}
 - Use update_todos to manage the session todo checklist for complex work. Provide the full current list each time and usually keep exactly one item in_progress
 - Use read_plan and update_plan to recover or sync structured plan state when plan progress was interrupted (for example by transient gateway/model errors)
 - Use run for shell commands. For long-running processes (dev servers, watchers), set run_in_background=true when you know you do not need the final result immediately. Long-running commands may also be backgrounded automatically
@@ -164,7 +168,7 @@ Some tools are loaded on demand through tool_search. Common examples:
 - glob for pattern-based file lookup
 - ast_query and read_ast_node for advanced AST-scoped reads and edits
 - list_background_tasks, get_background_task, and stop_background_task for managing long-running background commands
-- remember_user, remember_global, remember_project, list_memory, search_memory, and forget_memory for persistent memory operations
+- save_memory, list_memory, search_memory, and forget_memory for persistent memory operations
 
 For structural code edits (functions, classes, methods), prefer AST-scoped reads before editing:
 - Common one-shot workflow: read(path, query=..., capture_name=...) → edit with symbol or ast_target
@@ -177,15 +181,15 @@ For background commands: use run to launch. If you need management tools that ar
 Common tool call patterns:
 - Query the project index first: {query:"login auth flow", path:"src", max_results:5}
 - Load a deferred tool when needed: {query:"glob"} or {query:"all"}
-- Read a file: {path:"src/app.ts"} or {file_path:"src/app.ts", offset:20, limit:40}
+- Read a file: {path:"src/app.ts"} or {path:"src/app.ts", start_line:20, end_line:60}
 - Read a specific range inline: {path:"src/app.ts:20-60"}
 - Search text: {pattern:"loginUser", path:"src"} or {query:"loginUser", directory:"src"}
 - List a directory first: {path:"src"}
 - After loading glob, find files by pattern: {pattern:"src/**/*.ts"} or {query:"src/**/*.ts"}
-- Edit exact text: {file_path:"src/app.ts", old_string:"foo", new_string:"bar"}
+- Edit exact text: {path:"src/app.ts", old_text:"foo", new_text:"bar"}
 - Edit with shorthand: {path:"src/app.ts", old_text:"foo", content:"bar"}
-- Write a new file: {file:"notes.txt", text:"..."} or {path:"src/page.tsx", content:"..."}
-- When the environment provides a Working directory, prefer absolute file_path values rooted there instead of guessing prefixes
+- Write a new file: {path:"notes.txt", content:"..."} or {path:"src/page.tsx", content:"..."}
+- When the environment provides a Working directory, prefer absolute path values rooted there instead of guessing prefixes
 - If the user gives a relative path like src/app.ts, resolve it from the current Working directory rather than inventing ../ or sibling folders
 
 # Doing tasks
@@ -214,7 +218,7 @@ Common tool call patterns:
 - Keep answers compact and easy to scan
 - Lead with the answer or next action, not scene-setting
 - Do not restate the user's request unless a brief restatement prevents ambiguity
-- When referencing code, use file_path:line_number format
+- When referencing code, use path:line_number format
 - Keep technical wording, commands, paths, and error details exact
 - Only use emojis if the user explicitly requests it`;
 }

package/src/core/tool-args.js

@@ -0,0 +1,181 @@
+import path from 'node:path';
+
+export function parseInlineRangePath(value) {
+  const text = String(value || '').trim();
+  if (!text) return null;
+  const match = text.match(/^(.*?):(\d+)(?:-(\d+))?$/);
+  if (!match) return null;
+  const [, maybePath, startRaw, endRaw] = match;
+  if (!maybePath || /^(?:[A-Za-z])$/.test(maybePath)) return null;
+  const startLine = Number(startRaw);
+  const endLine = Number(endRaw || startRaw);
+  if (!Number.isFinite(startLine) || startLine <= 0) return null;
+  if (!Number.isFinite(endLine) || endLine < startLine) return null;
+  return {
+    path: maybePath,
+    start_line: startLine,
+    end_line: endLine
+  };
+}
+
+export function normalizeReadArgs(rawArgs) {
+  const source =
+    rawArgs && typeof rawArgs === 'object' && !Array.isArray(rawArgs)
+      ? { ...rawArgs }
+      : { path: typeof rawArgs === 'string' ? rawArgs : '' };
+
+  const normalized = { ...source };
+  const aliasPath = String(source.path || source.file_path || source.file || source.target || '').trim();
+  if (aliasPath) normalized.path = aliasPath;
+
+  if (!Number.isFinite(Number(normalized.start_line)) && Number.isFinite(Number(source.offset))) {
+    normalized.start_line = Number(source.offset);
+  }
+
+  if (!Number.isFinite(Number(normalized.end_line)) && Number.isFinite(Number(source.limit))) {
+    const startLine = Number(normalized.start_line);
+    const limit = Number(source.limit);
+    if (startLine > 0 && limit > 0) {
+      normalized.end_line = startLine + limit - 1;
+    }
+  }
+
+  const inlineRange = parseInlineRangePath(normalized.path);
+  if (inlineRange) {
+    normalized.path = inlineRange.path;
+    if (!Number.isFinite(Number(normalized.start_line))) normalized.start_line = inlineRange.start_line;
+    if (!Number.isFinite(Number(normalized.end_line))) normalized.end_line = inlineRange.end_line;
+  }
+
+  return normalized;
+}
+
+export function normalizePathArgs(rawArgs, aliases = []) {
+  const source =
+    rawArgs && typeof rawArgs === 'object' && !Array.isArray(rawArgs)
+      ? { ...rawArgs }
+      : { path: typeof rawArgs === 'string' ? rawArgs : '' };
+  const normalized = { ...source };
+  const keys = ['path', ...aliases];
+  for (const key of keys) {
+    const value = String(source?.[key] || '').trim();
+    if (value) {
+      normalized.path = value;
+      break;
+    }
+  }
+  return normalized;
+}
+
+export function normalizePatternArgs(rawArgs, aliases = [], defaultPathAliases = []) {
+  const source =
+    rawArgs && typeof rawArgs === 'object' && !Array.isArray(rawArgs)
+      ? { ...rawArgs }
+      : { pattern: typeof rawArgs === 'string' ? rawArgs : '' };
+  const normalized = { ...source };
+  for (const key of ['pattern', ...aliases]) {
+    const value = String(source?.[key] || '').trim();
+    if (value) {
+      normalized.pattern = value;
+      break;
+    }
+  }
+  for (const key of ['path', ...defaultPathAliases]) {
+    const value = String(source?.[key] || '').trim();
+    if (value) {
+      normalized.path = value;
+      break;
+    }
+  }
+  return normalized;
+}
+
+export function normalizeWriteArgs(rawArgs) {
+  const source =
+    rawArgs && typeof rawArgs === 'object' && !Array.isArray(rawArgs)
+      ? { ...rawArgs }
+      : { path: typeof rawArgs === 'string' ? rawArgs : '' };
+  const normalized = { ...source };
+  const filePath = String(source.path || source.file_path || source.file || '').trim();
+  if (filePath) normalized.path = filePath;
+  if (normalized.content == null) {
+    if (source.text != null) normalized.content = source.text;
+    if (source.new_content != null) normalized.content = source.new_content;
+  }
+  return normalized;
+}
+
+export function normalizeWebFetchArgs(rawArgs) {
+  const normalized = normalizePathArgs(rawArgs, ['url', 'href', 'link', 'target']);
+  const url = String(normalized.url || normalized.path || '').trim();
+  return { ...normalized, url };
+}
+
+export function normalizeWebSearchArgs(rawArgs) {
+  const normalized = normalizePatternArgs(rawArgs, ['query', 'q', 'keyword']);
+  const query = String(normalized.query || normalized.pattern || '').trim();
+  return { ...normalized, query };
+}
+
+function buildDeleteApprovalDetails(source, rawPath) {
+  const existing =
+    source?.approval && typeof source.approval === 'object' && !Array.isArray(source.approval)
+      ? source.approval
+      : {};
+  const approvalPath = String(existing.path || rawPath || '').trim();
+  const approvalName = String(existing.name || (approvalPath ? path.basename(approvalPath) : '') || '').trim();
+  const approvalType = String(existing.type || '').trim();
+
+  const approval = {};
+  if (approvalPath) approval.path = approvalPath;
+  if (approvalName) approval.name = approvalName;
+  if (approvalType) approval.type = approvalType;
+  return Object.keys(approval).length > 0 ? approval : undefined;
+}
+
+export function normalizeToolArguments(toolName, args, rawArguments) {
+  const rawText = typeof rawArguments === 'string' ? rawArguments.trim() : '';
+  const primitive =
+    args == null || Array.isArray(args) || typeof args !== 'object'
+      ? args
+      : null;
+  const source =
+    args && typeof args === 'object' && !Array.isArray(args)
+      ? { ...args }
+      : {};
+
+  if (primitive != null && typeof primitive !== 'object') {
+    source._raw = rawText || String(primitive);
+  } else if (!source._raw && rawText && source._invalid_json) {
+    source._raw = rawText;
+  }
+
+  const stringValue =
+    typeof primitive === 'string'
+      ? primitive.trim()
+      : String(source._raw || '').trim();
+
+  if (toolName === 'read') return normalizeReadArgs({ ...source, ...(stringValue && !source.path ? { path: stringValue } : {}) });
+  if (toolName === 'list') return normalizePathArgs({ ...source, ...(stringValue && !source.path ? { path: stringValue } : {}) }, ['dir', 'directory']);
+  if (toolName === 'glob') return normalizePatternArgs({ ...source, ...(stringValue && !source.pattern ? { pattern: stringValue } : {}) }, ['glob', 'query'], ['directory']);
+  if (toolName === 'grep') return normalizePatternArgs({ ...source, ...(stringValue && !source.pattern ? { pattern: stringValue } : {}) }, ['query', 'symbol', 'q'], ['directory', 'dir', 'cwd']);
+  if (toolName === 'write') return normalizeWriteArgs({ ...source, ...(stringValue && !source.path ? { path: stringValue } : {}) });
+
+  if (toolName === 'edit') {
+    const value = String(source.path || source.file || source.file_path || '').trim();
+    if (value && !source.path) source.path = value;
+    return source;
+  }
+
+  if (toolName === 'delete') {
+    const normalized = normalizePathArgs(
+      { ...source, ...(stringValue && !source.path ? { path: stringValue } : {}) },
+      ['file_path', 'file', 'target', 'directory', 'dir']
+    );
+    const approval = buildDeleteApprovalDetails(normalized, normalized.path);
+    if (approval) normalized.approval = approval;
+    return normalized;
+  }
+
+  return source;
+}