lonny-agent 0.2.6 → 0.2.7

package/src/tools/execute/git.ts

@@ -0,0 +1,209 @@
+import { exec } from 'node:child_process'
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import type { Tool, ToolDefinition } from '../types.js'
+
+/** Normalize a git command string — strip common LLM mistakes. */
+function normalizeGitCommand(raw: string): string {
+  let cmd = String(raw).trim()
+  // LLM often writes `git("git status")` or `git("git status --short")`
+  cmd = cmd.replace(/^git\s+/, '')
+  // Strip leading `git(` or `git'` artifacts from LLM hallucination
+  cmd = cmd.replace(/^git['"(]\s*/, '').replace(/['")]\s*$/, '')
+  return cmd
+}
+
+/** Common corrections map for git subcommand typos. */
+const COMMON_TYPOS: Record<string, string> = {
+  stauts: 'status',
+  staus: 'status',
+  statsu: 'status',
+  comit: 'commit',
+  commmit: 'commit',
+  brach: 'branch',
+  branc: 'branch',
+  chekout: 'checkout',
+  checkut: 'checkout',
+  'diff --staged': 'diff --cached',
+  'diff --stage': 'diff --cached',
+}
+
+/** Suggest a fix for a failed git command based on stderr content. */
+function suggestFix(cmd: string, stderr: string): string | null {
+  const lower = stderr.toLowerCase()
+  if (lower.includes('not a git repository') || lower.includes('not a git repo')) {
+    return 'Not a git repository. Check that you are in the correct directory.'
+  }
+  if (lower.includes('did not match any file(s) known to git')) {
+    return 'The path does not match any tracked files. Use `git status` to see tracked files first.'
+  }
+  if (lower.includes('pathspec') && lower.includes('did not match')) {
+    return 'The pathspec did not match. Check the file path is correct and tracked by git.'
+  }
+  if (lower.includes('unknown option') || lower.includes('usage:')) {
+    return 'Unknown flag or syntax error. Check `git help` for the correct usage.'
+  }
+  if (lower.includes('ambiguous argument')) {
+    return 'Ambiguous argument. Try quoting the path or using `--` to separate options from paths.'
+  }
+  if (lower.includes('permission denied') || lower.includes('denied')) {
+    return 'Permission denied. You may not have access to this repository.'
+  }
+  return null
+}
+
+export const createGitTool = (cwd: string): Tool => {
+  const definition: ToolDefinition = {
+    name: 'git',
+    category: 'Execute',
+    group: 'Git',
+    description: `Run git commands for repository operations.
+
+COMMON USE CASES:
+  git({ command: "status" })             # Working tree status
+  git({ command: "diff" })               # Unstaged changes
+  git({ command: "diff --cached" })      # Staged changes
+  git({ command: "log --oneline -5" })   # Recent commits
+  git({ command: "show <hash>" })        # Show a specific commit
+  git({ command: "branch" })             # List branches
+  git({ command: "branch -a" })          # List all branches (including remote)
+
+NOTES:
+  - Omit the "git" prefix — just pass the subcommand.
+  - Use \`cwd\` to run in a subdirectory of the repo.`,
+    parameters: {
+      command: {
+        type: 'string',
+        description:
+          'Git subcommand and arguments (e.g. "status", "diff", "log --oneline -5"). Do NOT include the "git " prefix.',
+        required: true,
+      },
+      path: {
+        type: 'string',
+        description: 'Repository path (alias: cwd). Defaults to working directory.',
+        required: false,
+      },
+      cwd: {
+        type: 'string',
+        description: 'Working directory (alias: path). Defaults to working directory.',
+        required: false,
+      },
+    },
+  }
+
+  const execute = async (
+    input: Record<string, unknown>,
+  ): Promise<{ success: boolean; output: string; error?: string }> => {
+    let gitCmd = normalizeGitCommand(String(input.command || ''))
+
+    // Accept both `path` and `cwd` parameters (LLM convention)
+    const repoPath = String(input.path || input.cwd || cwd)
+
+    if (!gitCmd) {
+      return {
+        success: false,
+        output: '',
+        error:
+          'command is required. Use: git({ command: "status" }) — pass the subcommand without the "git " prefix.',
+      }
+    }
+
+    // Auto-correct common typos in the first subcommand word
+    const firstWord = gitCmd.split(/\s+/)[0]!
+    if (firstWord && COMMON_TYPOS[firstWord]) {
+      gitCmd = gitCmd.replace(firstWord, COMMON_TYPOS[firstWord]!)
+    }
+
+    // Safety: block destructive commands (checked AFTER normalization)
+    const destructivePatterns = [
+      /^push\b/i,
+      /^reset\s+(--hard|--soft|--mixed|--merge|--keep)/i,
+      /^(rebase|merge|cherry-pick|revert)\b/i,
+      /^branch\s+-[dD]/i,
+      /^branch\s+--delete\b/i,
+      /^tag\s+-[dD]/i,
+      /^(clean|gc|prune)\b/i,
+      /^update-ref\b/i,
+      /^rm\b/i,
+      /^commit\b/i,
+      /^checkout\b/i,
+      /^fetch\s+.*--force/i,
+      /^stash\s+(drop|clear)\b/i,
+      /^config\b/i,
+    ]
+
+    for (const pattern of destructivePatterns) {
+      if (pattern.test(gitCmd)) {
+        return {
+          success: false,
+          output: '',
+          error: `Destructive git command not allowed: "${gitCmd}". Only read-only operations are permitted. If you need to make changes, use the \`edit\` tool for file modifications and git add/commit for staging.`,
+        }
+      }
+    }
+
+    // Verify the repo path exists
+    if (!fs.existsSync(repoPath)) {
+      return {
+        success: false,
+        output: '',
+        error: `Repository path does not exist: "${repoPath}". Use a valid directory path.`,
+      }
+    }
+    if (!fs.statSync(repoPath).isDirectory()) {
+      return {
+        success: false,
+        output: '',
+        error: `Repository path is not a directory: "${repoPath}".`,
+      }
+    }
+
+    return new Promise(resolve => {
+      const child = exec(
+        `git ${gitCmd}`,
+        {
+          cwd: repoPath,
+          encoding: 'utf-8',
+          timeout: 30000,
+          maxBuffer: 10 * 1024 * 1024, // 10MB
+        },
+        (err, stdout, stderr) => {
+          if (err) {
+            const exitCode = typeof err.code === 'number' ? err.code : -1
+            const stderrMsg = stderr?.trim() || ''
+            const stdoutMsg = stdout?.trim() || ''
+
+            // git diff exits with 1 when there are differences — that's not an error
+            if ((gitCmd.startsWith('diff') || gitCmd.startsWith('status')) && stdoutMsg) {
+              return resolve({ success: true, output: stdoutMsg })
+            }
+
+            let errorMsg = stderrMsg || err.message || String(err)
+            const hint = suggestFix(gitCmd, errorMsg)
+            if (hint) errorMsg += `\n💡 ${hint}`
+
+            return resolve({
+              success: exitCode === 0 && stdoutMsg ? true : false,
+              output: stdoutMsg,
+              error: errorMsg,
+            })
+          }
+
+          const output = (stdout || '').trim() || '(empty output)'
+          return resolve({ success: true, output })
+        },
+      )
+
+      // Handle spawn error (e.g. git not installed)
+      child.on('error', spawnErr => {
+        return resolve({
+          success: false,
+          output: '',
+          error: `Failed to run git: ${spawnErr.message}. Ensure git is installed and in your PATH.`,
+        })
+      })
+    })
+  }
+
+  return { definition, execute }
+}

package/src/tools/execute/task_complete.ts

@@ -0,0 +1,40 @@
+import type { Tool, ToolResult } from '../types.js'
+
+/**
+ * A tool the model can call to explicitly signal that the task is complete.
+ * In loop mode, this stops the automatic continuation and ends the session.
+ */
+export const taskCompleteTool: Tool = {
+  definition: {
+    name: 'task_complete',
+    description: `Call this ONLY when you have confirmed at least THREE TIMES that the task is truly complete.
+
+  ⚠️  TRIPLE CONFIRMATION REQUIRED ⚠️
+  Before calling this tool, you MUST verify each of the following three checks:
+
+  Check 1 — All requested work is done: Have you addressed every item the user asked for?
+  Check 2 — All changes are verified: Did you run the relevant tests / build / commands and confirm they pass?
+  Check 3 — No remaining steps: Is there nothing left to do? No pending edits, unverified changes, or unanswered questions?
+
+  Only call this tool after all three checks pass. If any check fails, continue working instead.
+
+  Use this instead of just describing completion in text — calling this tool explicitly signals the system to stop processing.
+
+  Examples:
+    - After finishing all requested edits AND verifying they work (all 3 checks pass)
+    - After completing a research task AND presenting findings (all 3 checks pass)
+    - After a planned task is fully executed AND verified (all 3 checks pass)`,
+    parameters: {
+      summary: {
+        type: 'string',
+        description:
+          'A brief summary of what was accomplished in this session (include the 3 checks you verified)',
+        required: true,
+      },
+    },
+  },
+  async execute(input): Promise<ToolResult> {
+    const summary = (input.summary as string) || ''
+    return { success: true, output: `TASK_COMPLETE: ${summary}` }
+  },
+}

package/src/tools/install/clawhub.ts

@@ -0,0 +1,222 @@
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+// @ts-expect-error - adm-zip has no types
+import AdmZip from 'adm-zip'
+import { fmtErr } from '../errors.js'
+import type { ToolResult } from '../types.js'
+import { CLAWHUB_API_BASE, SKILLS_DIR } from './constants.js'
+import { generateClawHubSkillContent, sanitizeSkillName } from './skill-content.js'
+
+/** Fetch skill info from ClawHub API */
+export async function fetchClawHubSkillInfo(
+  slug: string,
+): Promise<{ displayName: string; summary: string; latestVersion: string } | null> {
+  try {
+    const response = await fetch(`${CLAWHUB_API_BASE}/skills/${encodeURIComponent(slug)}`, {
+      headers: { Accept: 'application/json' },
+    })
+    if (!response.ok) return null
+
+    const data = (await response.json()) as {
+      skill?: { displayName?: string; summary?: string }
+      latestVersion?: { version?: string }
+    }
+    return {
+      displayName: data.skill?.displayName || slug,
+      summary: data.skill?.summary || '',
+      latestVersion: data.latestVersion?.version || 'latest',
+    }
+  } catch {
+    return null
+  }
+}
+
+/** Download a ClawHub skill as a ZIP and extract its content */
+export async function downloadClawHubSkill(
+  slug: string,
+  version?: string,
+): Promise<{ files: Map<string, string> } | null> {
+  try {
+    const versionPath = version ? `/${version}` : ''
+    const url = `${CLAWHUB_API_BASE}/download?slug=${encodeURIComponent(slug)}${version ? `&version=${encodeURIComponent(version)}` : ''}`
+    const response = await fetch(url)
+    if (!response.ok) {
+      // Try alternative URL patterns
+      const altUrl = `${CLAWHUB_API_BASE}/download/${encodeURIComponent(slug)}${versionPath}`
+      const altResponse = await fetch(altUrl)
+      if (!altResponse.ok) return null
+
+      const buffer = await altResponse.arrayBuffer()
+      return extractZipContent(Buffer.from(buffer))
+    }
+
+    const buffer = await response.arrayBuffer()
+    return extractZipContent(Buffer.from(buffer))
+  } catch {
+    return null
+  }
+}
+
+/** Extract files from a ZIP buffer */
+export function extractZipContent(buffer: Buffer): { files: Map<string, string> } {
+  const zip = new AdmZip(buffer)
+  const entries = zip.getEntries()
+  const files = new Map<string, string>()
+
+  for (const entry of entries) {
+    if (!entry.isDirectory) {
+      files.set(entry.entryName, entry.getData().toString('utf-8'))
+    }
+  }
+
+  return { files }
+}
+
+/** Find the SKILL.md entry in the downloaded files (case-insensitive) */
+export function findSkillMdInZip(files: Map<string, string>): string | null {
+  for (const [filePath] of files) {
+    const normalized = filePath.replace(/\\/g, '/').toLowerCase()
+    if (normalized.endsWith('/skill.md')) {
+      return files.get(filePath) || null
+    }
+  }
+  // Fallback: check root-level SKILL.md
+  for (const [filePath] of files) {
+    const normalized = filePath.replace(/\\/g, '/')
+    if (normalized.toLowerCase() === 'skill.md' || normalized.endsWith('/skill.md')) {
+      return files.get(filePath) || null
+    }
+  }
+  return null
+}
+
+/** Normalize a ZIP file path, stripping common root directory */
+export function normalizeZipPath(filePath: string, _slug: string): string {
+  const normalized = filePath.replace(/\\/g, '/')
+  // Strip leading directory that matches the slug or is a common root
+  const parts = normalized.split('/')
+  if (parts.length > 1) {
+    // Remove the first segment if it's a common root
+    // ZIPs from ClawHub often have a root folder like "repo-release-notes/"
+    return parts.slice(1).join('/')
+  }
+  return normalized
+}
+
+/** Install a skill from ClawHub */
+export async function installFromClawHub(
+  cwd: string,
+  slug: string,
+  version: string | undefined,
+  info: { displayName: string; summary: string; latestVersion: string },
+  input: Record<string, unknown>,
+): Promise<ToolResult> {
+  const versionToUse = version || info.latestVersion
+
+  // Download the skill ZIP
+  const downloaded = await downloadClawHubSkill(slug, versionToUse)
+  if (!downloaded) {
+    return {
+      success: false,
+      output: '',
+      error: `Failed to download ClawHub skill "${slug}" (version ${versionToUse}).`,
+    }
+  }
+
+  const skillsDir = path.resolve(cwd, SKILLS_DIR)
+  const skillName = sanitizeSkillName(slug)
+  const skillFilePath = path.join(skillsDir, `${skillName}.md`)
+  const skillDirPath = path.join(skillsDir, skillName)
+
+  // Find the SKILL.md in the ZIP
+  const skillMdEntry = findSkillMdInZip(downloaded.files)
+
+  // Also extract supporting files into a subdirectory
+  if (skillMdEntry) {
+    // Extract all files into skill subdirectory for supporting files
+    try {
+      fs.mkdirSync(skillDirPath, { recursive: true })
+      for (const [filePath, content] of downloaded.files) {
+        // Normalize the path: strip common root directory
+        const normalizedPath = normalizeZipPath(filePath, slug)
+        if (!normalizedPath || normalizedPath === 'SKILL.md') continue // SKILL.md goes to root
+        const fullPath = path.join(skillDirPath, normalizedPath)
+        fs.mkdirSync(path.dirname(fullPath), { recursive: true })
+        fs.writeFileSync(fullPath, content, 'utf-8')
+      }
+    } catch (err) {
+      // Non-critical: supporting files are optional
+      console.warn(
+        `[install_skill] Warning: could not extract all supporting files: ${fmtErr(err)}`,
+      )
+    }
+
+    // Generate skill file (using the SKILL.md content from the ZIP)
+    const description = (input.description as string) || info.summary || slug
+    const skillContent = generateClawHubSkillContent(
+      slug,
+      info.displayName,
+      description,
+      skillMdEntry,
+    )
+
+    try {
+      fs.mkdirSync(skillsDir, { recursive: true })
+      fs.writeFileSync(skillFilePath, skillContent, 'utf-8')
+    } catch (err) {
+      return {
+        success: false,
+        output: '',
+        error: `Failed to write skill file: ${fmtErr(err)}`,
+      }
+    }
+  } else {
+    // No SKILL.md found in ZIP, generate a wrapper skill
+    const description = (input.description as string) || info.summary || slug
+    // Collect all extracted content as a markdown reference
+    const filesList = Array.from(downloaded.files.keys())
+      .map(f => `- ${f}`)
+      .join('\n')
+    const combinedContent =
+      `## Files in this skill\n\n${filesList}\n\n` +
+      Array.from(downloaded.files.entries())
+        .map(([name, content]) => `### ${name}\n\n\`\`\`\n${content.slice(0, 2000)}\n\`\`\``)
+        .join('\n\n')
+
+    const skillContent = generateClawHubSkillContent(
+      slug,
+      info.displayName,
+      description,
+      combinedContent,
+    )
+
+    try {
+      fs.mkdirSync(skillsDir, { recursive: true })
+      fs.writeFileSync(skillFilePath, skillContent, 'utf-8')
+    } catch (err) {
+      return {
+        success: false,
+        output: '',
+        error: `Failed to write skill file: ${fmtErr(err)}`,
+      }
+    }
+  }
+
+  const relPath = path.relative(cwd, skillFilePath).replace(/\\/g, '/')
+  const supportRelPath = skillMdEntry ? path.relative(cwd, skillDirPath).replace(/\\/g, '/') : ''
+
+  let output = `Installed ClawHub skill "${slug}" (v${versionToUse}) and created skill file "${relPath}".`
+  if (supportRelPath) {
+    output += `\nSupporting files extracted to "${supportRelPath}/".`
+  }
+  output += `
+
+The skill instructions will be loaded automatically on the next turn.
+
+To verify: use \`read\` on "${relPath}" to see the skill content.`
+
+  return {
+    success: true,
+    output,
+  }
+}

package/src/tools/install/constants.ts

@@ -0,0 +1,4 @@
+export const SKILLS_DIR = '.lonny/skills'
+export const NPM_REGISTRY_URL = 'https://registry.npmjs.org'
+export const CLAWHUB_API_BASE = 'https://clawhub.ai/api/v1'
+export const CLAWHUB_SITE = 'https://clawhub.ai'

package/src/tools/install/install_skill.ts

@@ -0,0 +1,150 @@
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import { fmtErr } from '../errors.js'
+import type { Tool, ToolResult } from '../types.js'
+import { fetchClawHubSkillInfo, installFromClawHub } from './clawhub.js'
+import { SKILLS_DIR } from './constants.js'
+import { fetchNpmPackageInfo, runNpmInstall } from './npm.js'
+import { extractUsageGuide, generateSkillContent, sanitizeSkillName } from './skill-content.js'
+
+export function createInstallSkillTool(cwd: string): Tool {
+  return {
+    definition: {
+      name: 'install_skill',
+      category: 'Install',
+      group: 'Skill',
+      description: `Install an npm package or ClawHub skill. This tool:
+1. For npm packages: fetches info from npm registry, runs \`npm install\`, creates a skill file
+2. For ClawHub skills: fetches skill metadata from clawhub.ai, downloads the skill bundle, writes SKILL.md
+
+After installation, the skill will be automatically loaded on the next conversation turn (the system prompt includes active skills).
+
+Use this when you need to use a third-party npm package or install a skill from ClawHub (clawhub.ai).
+
+ClawHub skills: pass the skill slug (e.g. \`repo-release-notes\`) as package_name. The tool auto-detects ClawHub skills.`,
+      parameters: {
+        package_name: {
+          type: 'string',
+          description:
+            'The npm package name or ClawHub skill slug to install (e.g. "dayjs", "cn-time-parser", "@scope/package", or ClawHub slug like "repo-release-notes")',
+          required: true,
+        },
+        description: {
+          type: 'string',
+          description:
+            'Optional description of what the package/skill does. If not provided, it will be fetched from the npm registry or ClawHub.',
+          required: false,
+        },
+        usage_guide: {
+          type: 'string',
+          description:
+            'Optional custom usage guide for the AI. If not provided, it will be auto-generated from the readme or ClawHub SKILL.md. Provide this if the auto-generated guide is insufficient.',
+          required: false,
+        },
+        clawhub: {
+          type: 'boolean',
+          description:
+            "Force ClawHub mode. If true, treats package_name as a ClawHub skill slug. Auto-detected if the package doesn't exist on npm.",
+          required: false,
+        },
+        version: {
+          type: 'string',
+          description: 'Optional version for ClawHub skill install (defaults to latest).',
+          required: false,
+        },
+      },
+    },
+    async execute(input): Promise<ToolResult> {
+      // ── Auto-correction: if input is a string, wrap it ────────────────
+      if (typeof input === 'string') {
+        input = { package_name: input }
+      }
+
+      const packageName = input.package_name as string
+      if (!packageName || typeof packageName !== 'string') {
+        return {
+          success: false,
+          output: '',
+          error: 'package_name is required (string)',
+        }
+      }
+
+      const forceClawHub = input.clawhub === true
+      const version = input.version as string | undefined
+
+      // ── Auto-detect: try npm first, fall back to ClawHub ──────────────
+      const npmInfo = forceClawHub ? null : await fetchNpmPackageInfo(packageName)
+
+      // If npm lookup failed and not forced, try ClawHub
+      if (!npmInfo && !forceClawHub) {
+        const clawhubInfo = await fetchClawHubSkillInfo(packageName)
+        if (clawhubInfo) {
+          // It's a ClawHub skill — install from ClawHub
+          return installFromClawHub(cwd, packageName, version, clawhubInfo, input)
+        }
+
+        return {
+          success: false,
+          output: '',
+          error: `"${packageName}" was not found on npm registry nor on ClawHub. Check the name and try again.`,
+        }
+      }
+
+      // If forced ClawHub mode
+      if (forceClawHub) {
+        const clawhubInfo = await fetchClawHubSkillInfo(packageName)
+        if (!clawhubInfo) {
+          return {
+            success: false,
+            output: '',
+            error: `"${packageName}" was not found on ClawHub.`,
+          }
+        }
+        return installFromClawHub(cwd, packageName, version, clawhubInfo, input)
+      }
+
+      // ── npm package install path ──────────────────────────────────────
+      const description = (input.description as string) || npmInfo?.description || packageName
+      const readme = npmInfo?.readme || ''
+
+      const installError = await runNpmInstall(cwd, packageName)
+      if (installError) {
+        return {
+          success: false,
+          output: '',
+          error: `npm install failed: ${installError}`,
+        }
+      }
+
+      const usageGuide = (input.usage_guide as string) || (readme ? extractUsageGuide(readme) : '')
+
+      const skillContent = generateSkillContent(packageName, description, usageGuide)
+
+      const skillsDir = path.resolve(cwd, SKILLS_DIR)
+      const skillName = sanitizeSkillName(packageName)
+      const skillFilePath = path.join(skillsDir, `${skillName}.md`)
+
+      try {
+        fs.mkdirSync(skillsDir, { recursive: true })
+        fs.writeFileSync(skillFilePath, skillContent, 'utf-8')
+      } catch (err) {
+        return {
+          success: false,
+          output: '',
+          error: `Failed to write skill file: ${fmtErr(err)}`,
+        }
+      }
+
+      const relPath = path.relative(cwd, skillFilePath).replace(/\\/g, '/')
+
+      return {
+        success: true,
+        output: `Installed npm package "${packageName}" and created skill "${relPath}".
+
+The package is now a project dependency. The skill file contains usage instructions for the AI and will be loaded automatically on the next turn.
+
+To verify: use \`read\` on "${relPath}" to see the skill content.`,
+      }
+    },
+  }
+}

package/src/tools/install/npm.ts

@@ -0,0 +1,60 @@
+import * as cp from 'node:child_process'
+import { NPM_REGISTRY_URL } from './constants.js'
+
+/** Fetch package info from npm registry */
+export async function fetchNpmPackageInfo(
+  packageName: string,
+): Promise<{ description: string; readme: string } | null> {
+  try {
+    const response = await fetch(`${NPM_REGISTRY_URL}/${encodeURIComponent(packageName)}`, {
+      headers: { Accept: 'application/json' },
+    })
+    if (!response.ok) return null
+
+    const data = (await response.json()) as {
+      description?: string
+      readme?: string
+    }
+    return {
+      description: data.description || '',
+      readme: data.readme || '',
+    }
+  } catch {
+    return null
+  }
+}
+
+/** Run npm install in the project directory */
+export async function runNpmInstall(cwd: string, packageName: string): Promise<string | null> {
+  return new Promise(resolve => {
+    const child = cp.spawn('npm', ['install', packageName], {
+      cwd,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      shell: process.platform === 'win32',
+    })
+
+    let stderr = ''
+    child.stderr?.on('data', (data: Buffer) => {
+      stderr += data.toString()
+    })
+
+    const timeout = setTimeout(() => {
+      child.kill()
+      resolve(`Timed out after 60s. ${stderr.slice(0, 500)}`)
+    }, 60_000)
+
+    child.on('close', code => {
+      clearTimeout(timeout)
+      if (code === 0) {
+        resolve(null) // success
+      } else {
+        resolve(stderr.slice(0, 500) || `npm install exited with code ${code}`)
+      }
+    })
+
+    child.on('error', err => {
+      clearTimeout(timeout)
+      resolve(`Failed to start npm install: ${err.message}`)
+    })
+  })
+}