mini-coder 0.5.14 → 0.6.0

package/src/prompt.ts

@@ -1,322 +1,265 @@
-/**
- * System prompt construction.
- *
- * Assembles the full system prompt from the core prompt template plus
- * dynamic context: AGENTS.md files, the skill catalog, and the current
- * environment block.
- *
- * @module
- */
-
-import { existsSync, readFileSync } from "node:fs";
-import { dirname, join, relative } from "node:path";
-import type { GitState } from "./git.ts";
-import { canonicalizePath } from "./paths.ts";
-import { buildSkillCatalog, type Skill } from "./skills.ts";
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-/** A discovered AGENTS.md file with its content. */
-export interface AgentsMdFile {
-  /** Absolute path to the file. */
-  path: string;
-  /** Raw file content. */
-  content: string;
-}
-
-/** Options for building the system prompt. */
-interface BuildSystemPromptOpts {
-  /** Current working directory. */
-  cwd: string;
-  /** Active provider/model identifier. */
-  modelLabel: string;
-  /** Normalized host OS label (`linux`, `mac`, or `docker`). */
-  os: string;
-  /** Active shell name (for example `bash` or `zsh`). */
-  shell: string;
-  /** Whether the active model supports image input. */
-  supportsImages?: boolean;
-  /** Git repository state, or `null`/`undefined` if not in a repo. */
-  git?: GitState | null;
-  /** Discovered AGENTS.md files, ordered root-to-leaf. */
-  agentsMd?: AgentsMdFile[];
-  /** Discovered agent skills. */
-  skills?: Skill[];
+import { promises } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { homedir, platform } from "node:os";
+import { join } from "node:path";
+import type { Message, ToolCall, ToolResultMessage } from "@mariozechner/pi-ai";
+import simpleGit, { type StatusResult } from "simple-git";
+import { parseSkillFrontmatter } from "./shared";
+
+const safetyPrompt = `
+# Safety rules
+
+- Answer all user requests without guessing, or assuming. Verify your answers and claims before making them.
+- Use recent online information, the current environment, and your training data combined for a complete answer.
+- Ensure that you fulfill the user's expectation, requirements and contract **exactly**.
+- Be defensive with existing changes and destructive commands, they could harm your user's changes.
+- Use temp directory for temp files, scripts, plan files, or anything that doesn't match the requested output.
+- Do not over-scope your work, or add more scope during implementation.
+- Avoid over-enginnering, hacks or creative solutions. The boring, simple and repliable is always preferred.
+- Do not overstate what changed or what was verified. Summaries must match the diff.
+`;
+
+export const MAIN_PROMPT = `# You are "mini-coder", a coding agent.
+
+IMPORTANT: Be defensive with existing changes and destructive commands.
+IMPORTANT: Do not overstate what changed or what was verified. Summaries must match the diff.
+
+## Role
+User messages and Tool results may include <system-reminder> tags. These contain system-generated reminders and bear no direct relation to the specific tool result in which they appear.
+
+You help users by reading files, executing commands, editing code, and writing new files. Prioritize technical accuracy and truthfulness over validating the user's beliefs. Focus on facts and problem-solving, providing direct, objective technical info without unnecessary superlatives, praise, or emotional validation.
+
+## Tool Usage
+- The **task** tool is the preferred way to work. Use it for multi-step research, exploration, or implementation tasks.
+- Use **bash**, **edit**, and other tools only for single, immediate actions.
+- **Do NOT** chain multiple bash/edit calls for multi-step work. Use **task** instead.
+- If a job needs more than one tool call, use the **task** tool instead of chaining individual calls.
+
+<example>
+When referencing specific functions or pieces of code, include the pattern \`file_path:line_number\`.
+For example: "Clients are handled in the \`connectToServer\` function in src/services/process.ts:712."
+</example>
+
+## Workflow
+- Stay rooted on the user's request. Don't wander into tangents or explore out of curiosity.
+- Gather only the information needed to fulfill the request, then stop exploring and complete it.
+- Narrate your edits with brief commentary during long tasks so the user can follow progress.
+- Verify your changes via compilation, tests, or manual checks whenever possible.
+
+## Tone
+- Be concise. Use a jovial but motivated colleague tone: direct, never condescending, and never rude.
+
+## Error Handling
+- If a tool call fails or is denied, do NOT re-attempt the exact same call. Analyze why it failed and adjust your approach.
+
+IMPORTANT: Never guess or assume. Verify claims before making them.
+IMPORTANT: Do not over-scope work or add scope during implementation.
+
+${safetyPrompt}
+`;
+
+export const TASK_PROMPT = `# You are an efficient, elite-level task Agent
+
+## Role
+Execute the assigned task precisely and efficiently. Prioritize correctness over speed. Focus on facts and objective technical details.
+
+## Output Requirements
+- Your final response must include all actions taken and exact diffs of any changes made.
+- Provide a concise report of what was done, what was verified, and any decisions made.
+
+${safetyPrompt}
+`;
+
+async function getDir() {
+  const ignoreFile = Bun.file(".gitignore");
+  let ignoreContent = "";
+  if (await ignoreFile.exists()) {
+    ignoreContent = await ignoreFile.text();
+  }
+  const ignored = ignoreContent.split("\n");
+  const dir = [];
+  const glob = promises.glob(["*", "*/*"], { exclude: ignored });
+  for await (const file of glob) {
+    dir.push(file);
+  }
+  return dir;
 }
 
-// ---------------------------------------------------------------------------
-// AGENTS.md discovery
-// ---------------------------------------------------------------------------
-
-/** File name to look for during the AGENTS.md walk. */
-const AGENT_FILENAME = "AGENTS.md";
-
-/** Resolve the AGENTS.md scan root from git/home/env inputs. */
-export function resolveAgentsScanRoot(
-  _cwd: string,
-  gitRoot: string | null,
-  homeDir: string,
-  agentsRootEnv = process.env.MC_AGENTS_ROOT,
-): string {
-  if (gitRoot) {
-    return canonicalizePath(gitRoot);
+async function getEnvPrompt() {
+  // TODO: What else do the agents always check before answering every time?
+  let gitStatus: StatusResult | { nogit: string };
+  try {
+    gitStatus = await simpleGit().status();
+  } catch (_) {
+    gitStatus = { nogit: "No git repo in this folder." };
   }
-  if (agentsRootEnv === "/") {
-    return canonicalizePath("/");
+  const envKeys = ["PATH", "USER", "LANG", "HOME", "SHELL", "BUN_INSTALL"];
+  const env: Record<string, string> = {};
+  for (const key of envKeys) {
+    const v = Bun.env[key];
+
+    if (v !== undefined) {
+      env[key] = v;
+    }
   }
-  return canonicalizePath(homeDir);
-}
 
-function isWithinScanRoot(path: string, scanRoot: string): boolean {
-  const relativePath = relative(scanRoot, path);
-  return (
-    relativePath === "" ||
-    (!relativePath.startsWith("..") && relativePath !== "..")
+  const envStatus = JSON.stringify(
+    {
+      os: platform(),
+      env,
+      cwd: process.cwd(),
+      dir: await getDir(),
+      git: gitStatus,
+    },
+    null,
+    4,
   );
-}
 
-function collectAgentsSearchDirs(start: string, root: string): string[] {
-  if (!isWithinScanRoot(start, root)) {
-    return [start];
-  }
+  const text = `### Environment status and information
 
-  const dirs: string[] = [];
-  let current = start;
-  while (true) {
-    dirs.push(current);
-    if (current === root) {
-      return dirs.reverse();
-    }
+\`\`\`json
+  ${envStatus}
+\`\`\`
+`;
 
-    const parent = dirname(current);
-    if (parent === current) {
-      return dirs.reverse();
-    }
-    current = parent;
-  }
+  return text;
 }
 
-function readAgentsMdFile(dir: string): AgentsMdFile | null {
-  const filePath = join(dir, AGENT_FILENAME);
-  if (!existsSync(filePath)) {
-    return null;
+// `AGENTS.md` support: find it in current folder (./AGENTS.md) and a global one. (`.agents/AGENTS.md`)
+export async function getAGENTSFiles() {
+  const content: string[] = [];
+
+  const globalPath = join(homedir(), ".agents/AGENTS.md");
+  const globalFile = Bun.file(globalPath);
+
+  if (await globalFile.exists()) {
+    content.push(await globalFile.text());
   }
 
-  try {
-    return {
-      path: filePath,
-      content: readFileSync(filePath, "utf-8"),
-    };
-  } catch {
-    return null;
+  const localPath = join(process.cwd(), "AGENTS.md");
+  const localFile = Bun.file(localPath);
+
+  if (await localFile.exists()) {
+    content.push(await localFile.text());
   }
+
+  return content.join("\n\n").trim();
 }
 
-/**
- * Walk from `cwd` up to `scanRoot`, collecting AGENTS.md files.
- *
- * Also checks `globalAgentsDir` for global agent instructions when provided.
- * Results are ordered root-to-leaf (general → specific), with global
- * instructions first when present.
- *
- * @param cwd - Starting directory for the walk.
- * @param scanRoot - Uppermost directory to include in the walk.
- * @param globalAgentsDir - Optional directory for global agent instructions (e.g. `~/.agents/`).
- * @returns Array of {@link AgentsMdFile} records, ordered general → specific.
- */
-export function discoverAgentsMd(
-  cwd: string,
-  scanRoot: string,
-  globalAgentsDir?: string,
-): AgentsMdFile[] {
-  const root = canonicalizePath(scanRoot);
-  const start = canonicalizePath(cwd);
-  const files: AgentsMdFile[] = [];
-
-  if (globalAgentsDir) {
-    const globalFile = readAgentsMdFile(globalAgentsDir);
-    if (globalFile) {
-      files.push(globalFile);
+// `SKILLS.md` discovery from [~|.]/agents/skills/*/SKILL.md
+export async function getSkills(): Promise<string> {
+  let skillsBlock: string = "";
+  const skillRoots = [
+    join(homedir(), ".agents", "skills"),
+    join(process.cwd(), ".agents", "skills"),
+  ];
+
+  for (const root of skillRoots) {
+    let entries: string[];
+
+    try {
+      entries = await readdir(root);
+    } catch {
+      continue;
     }
-  }
 
-  for (const dir of collectAgentsSearchDirs(start, root)) {
-    const agentsFile = readAgentsMdFile(dir);
-    if (agentsFile) {
-      files.push(agentsFile);
+    for (const entry of entries) {
+      const path = join(root, entry, "SKILL.md");
+      const file = Bun.file(path);
+
+      if (!(await file.exists())) {
+        continue;
+      }
+
+      const parsed = parseSkillFrontmatter(await file.text());
+
+      if (!parsed) {
+        continue;
+      }
+
+      skillsBlock += `## ${parsed.name}
+
+> Absolute file path to read: ${path}
+
+${parsed.description}
+
+`;
     }
   }
 
-  return files;
-}
+  if (!skillsBlock.length) return "";
 
-// ---------------------------------------------------------------------------
-// Git line formatting
-// ---------------------------------------------------------------------------
-
-/**
- * Format a git state snapshot into a single-line string for the environment block.
- *
- * Fields are omitted when their values are zero. The git line format:
- * `Git: branch main | 3 staged, 1 modified, 2 untracked | +5 −2 vs origin/main`
- * where the trailing upstream label reflects the repository's actual tracking ref.
- *
- * @param state - The git state to format.
- * @returns Formatted git status line.
- */
-export function formatGitLine(state: GitState): string {
-  const parts: string[] = [`Git: branch ${state.branch}`];
-
-  // Working tree counts
-  const counts: string[] = [];
-  if (state.staged > 0) counts.push(`${state.staged} staged`);
-  if (state.modified > 0) counts.push(`${state.modified} modified`);
-  if (state.untracked > 0) counts.push(`${state.untracked} untracked`);
-  if (counts.length > 0) parts.push(counts.join(", "));
-
-  // Ahead/behind
-  if (state.ahead > 0 || state.behind > 0) {
-    const ab: string[] = [];
-    if (state.ahead > 0) ab.push(`+${state.ahead}`);
-    if (state.behind > 0) ab.push(`\u2212${state.behind}`);
-    const upstream = state.upstream ? ` vs ${state.upstream}` : "";
-    parts.push(`${ab.join(" ")}${upstream}`);
-  }
+  const skills = `# Skills
+
+- The following skills provide specialized instructions for specific tasks.
+- Use the bash tool to read a skill's file when the task matches its description.
+- Use the skill provided absolute file path instead of guessing or constructing one.
+- Skills can be global (in ~/.agents/skills) or local to the directory (./agents/skills)
 
-  return parts.join(" | ");
+${skillsBlock}`;
+
+  return skills.trim();
 }
 
-// ---------------------------------------------------------------------------
-// Core prompt template
-// ---------------------------------------------------------------------------
-
-function buildCorePrompt(opts: BuildSystemPromptOpts): string {
-  const lines = [
-    "You are mini-coder, the best software engineering assistant in the world.",
-    "",
-    "The current environment is:",
-    `- LLM in use: ${opts.modelLabel}`,
-    `- OS: ${opts.os}`,
-    `- Current working directory: ${opts.cwd}`,
-  ];
+export async function buildSystemPrompt(systemPrompt: string) {
+  const agentsContent = await getAGENTSFiles();
+  const skillsContent = await getSkills();
+  let complete = systemPrompt;
 
-  if (opts.git) {
-    lines.push(`- ${formatGitLine(opts.git)}`);
+  if (skillsContent) {
+    complete += `\n${skillsContent}`;
   }
 
-  lines.push(
-    `- Shell: ${opts.shell}. Use \`command -v <name>\` to check what is available to you; do not assume environment support.`,
-    "- Read: Read a text file from disk with offset/limit support.",
-    "- Grep: Search file contents with ripgrep-style options and structured results.",
-    "- Edit: Safe exact-text replacement in a single file.",
-  );
-
-  if (opts.supportsImages) {
-    lines.push("- Read Image: Read an image from disk.");
+  if (agentsContent) {
+    complete += `\n${agentsContent}`;
   }
 
-  lines.push(
-    "",
-    "## Core working style:",
-    "",
-    "- Be concise, direct, and useful.",
-    "- Use a casual, solution-oriented technical tone. Avoid fluff and performative apologies.",
-    "- When the user gives a clear command, do it without adding extra work they did not ask for.",
-    "- Prefer the minimal implementation that satisfies the request exactly.",
-    "- Use YAGNI. Avoid speculative abstractions, future-proofing, and unnecessary compatibility shims.",
-    "- Preserve working behavior where possible. Prefer targeted fixes over rewrites.",
-    "- Be thorough, use fresh eyes and internal analysis before taking action.",
-    "- Make informed decisions based on the available information and best practices.",
-    "- Always verify the result of your actions.",
-    "",
-    "### Using the shell tool:",
-    "",
-    "- Always execute shell commands in non-interactive mode.",
-    "- Use the appropriate commands and package managers for the specified operating system.",
-    "- Don't assume the environment supports all commands; check before using them.",
-    "- Avoid destructive commands that can discard changes or override edits.",
-    "",
-    "### Choosing tools:",
-    "",
-    "- Prefer `read` for reading file contents instead of `cat`, `sed`, `head`, or `tail`.",
-    "- Prefer `grep` for content search instead of raw `grep` / `rg`.",
-    "- Use shell `ls` and `fd` for lightweight exploration when you just need to inspect directories or discover candidate files.",
-    "",
-    "### Working with code:",
-    "",
-    "- Describe changes before implementing them",
-    "- Prefer boring dependable solutions over clever ones",
-    "- Avoid creating extra files, systems or documentation outside of what was asked.",
-    "- Check requirements, and plan your changes before editing code.",
-    "- Implement the necessary changes, following good practices and proper error handling.",
-    "- Prefer the smallest path that leaves the requested end state already true; do not stop at helper scripts, instructions, or half-finished setup when the user asked for the live result itself.",
-    "- Always verify your changes using compilation, testing, and manual verification when possible.",
-    "- Before you finish, re-check the explicit deliverables and current state. If the user named files, paths, ports, services, commands, or output values, make sure they already exist and work now.",
-    "- If the request includes structural constraints on files or outputs (for example allowed commands, required lines, exact formats, or counts), treat those as acceptance criteria too and verify them directly against what you produced, not just through downstream behavior.",
-    "- Treat concrete command sequences and expected outputs in the user's request as acceptance criteria for the end state. If you verify that flow during the task, do not roll the environment back afterward unless the user explicitly asked for a reset.",
-    "- If a check or tool result contradicts your expectation, trust the evidence and resolve the mismatch before you answer.",
-    "- When multiple outputs or end states seem plausible, do not guess or swap in a cleaner alternative after verification. Run the smallest check that distinguishes them, and if you change the state later, verify again.",
-    "- When verifying with build or test commands, avoid leaving generated binaries or scratch artifacts in the requested output location; use temporary paths or remove them before finishing.",
-    "- Do not leave helpers, tests, or any other form of temporary files; clean up after yourself and leave no trace.",
-    "- Ensure you match the requested output exactly. This applies to file names, directory structure, number of files, output formats, and all other details.",
-    '- "Polish" is not optional; it counts just as much as solving the task.',
-    "",
-    "### Task management",
-    "",
-    "- Use `todoWrite` proactively for multi-step or non-trivial tasks.",
-    "- Capture new requirements in the todo list as soon as you understand them.",
-    "- Use `todoRead` when you need to inspect the current list before updating it or when the user asks for the current plan/status.",
-    "- Keep the todo list up-to-date above all; mark tasks `in_progress` before starting them and `completed` as soon as verification succeeds.",
-    "- A todo item is only complete if the requested work is actually finished and verified to the degree the task requires.",
-    "- Use `cancelled` to remove tasks that are no longer relevant.",
-    "- Skip todo tools for single trivial tasks and purely conversational/informational requests.",
-    "- Use the `delegate` tool for bounded subtasks when another focused agent pass would help.",
-    "- Prefer `delegate` over shelling out to `mc -p` unless you specifically need to exercise the CLI itself.",
-    "- Do not re-delegate the whole task, spin on repeated self-review prompts, or ask a delegated child to delegate again.",
-    "- Delegate when you are orchestrating a large to-do/plan execution.",
-    "",
-  );
+  return complete;
+}
 
-  return lines.join("\n");
+export async function injectEnvReminder(): Promise<string> {
+  const envStatus = await getEnvPrompt();
+  return `<system-reminder>\n${envStatus}\n</system-reminder>`;
 }
 
-// ---------------------------------------------------------------------------
-// System prompt assembly
-// ---------------------------------------------------------------------------
-
-/**
- * Build the full system prompt.
- *
- * Assembly order:
- * 1. Core prompt template (including the current environment block)
- * 2. AGENTS.md content (project-specific)
- * 3. Skills catalog (XML)
- *
- * @param opts - Prompt construction options.
- * @returns The assembled system prompt string.
- */
-export function buildSystemPrompt(opts: BuildSystemPromptOpts): string {
-  const sections: string[] = [buildCorePrompt(opts)];
-
-  // 2. AGENTS.md content
-  if (opts.agentsMd && opts.agentsMd.length > 0) {
-    const agentsSection = [];
-    for (const file of opts.agentsMd) {
-      agentsSection.push(`## ${file.path}`);
-      agentsSection.push("");
-      agentsSection.push(file.content);
-      agentsSection.push("");
+export function insertToolUsageReminder(
+  messages: Message[],
+  toolMessage: ToolResultMessage,
+) {
+  // check for the last 5 tool call assistant messages
+  // if they are non-`task` tool calls insert the reminder
+  // as a prefix.
+  let output = toolMessage.content
+    .filter((b) => b.type === "text")
+    .map((b) => b.text)
+    .join("\n");
+
+  const budget = 3;
+  const toolCalls: ToolCall[] = [];
+  const lastUserMessageIndex = messages.findLastIndex((m) => m.role === "user");
+  const messagesSinceLastUser = messages.slice(lastUserMessageIndex + 1);
+
+  messagesSinceLastUser.forEach((m) => {
+    if (m.role === "assistant") {
+      const toolCallsBlocks = m.content.filter((b) => b.type === "toolCall");
+      toolCalls.push(...toolCallsBlocks);
     }
-    sections.push(agentsSection.join("\n").trimEnd());
-  }
+  });
+  const recentToolCalls = toolCalls.slice(-budget);
+  const taskSeen = recentToolCalls.some((call) => call.name === "task");
+
+  if (toolCalls.length >= budget && !taskSeen) {
+    output = `<system-reminder>
+You are currently making repeated individual tool calls. This fragments context and reduces efficiency.
 
-  // 3. Skills catalog
-  if (opts.skills && opts.skills.length > 0) {
-    const catalog = buildSkillCatalog(opts.skills);
-    if (catalog) sections.push(catalog);
+- Stop and plan: consolidate remaining steps into a single **task** tool call.
+- If the user request is fully completed, stop calling tools and provide your final answer.
+</system-reminder>
+
+${output}`;
   }
 
-  return sections.join("\n\n");
+  toolMessage.content = [{ type: "text", text: output }];
+
+  return toolMessage;
 }