ethagent 0.2.0 → 1.0.0

package/src/tools/bashTool.ts

@@ -0,0 +1,140 @@
+import path from 'node:path'
+import { spawn } from 'node:child_process'
+import { z } from 'zod'
+import type { Tool } from './contracts.js'
+import { assessBashCommand, validateBashCommandInput } from './bashSafety.js'
+import { resolveWorkspacePath } from './readTool.js'
+
+const schema = z.object({
+  command: z.string().min(1),
+  cwd: z.string().optional(),
+})
+
+export const bashTool: Tool<typeof schema> = {
+  name: 'run_bash',
+  kind: 'bash',
+  description: 'Run a shell command in the current workspace and return stdout, stderr, and the exit code.',
+  inputSchema: schema,
+  inputSchemaJson: {
+    type: 'object',
+    properties: {
+      command: { type: 'string', description: 'Shell command to run.' },
+      cwd: { type: 'string', description: 'Optional working directory inside the workspace.' },
+    },
+    required: ['command'],
+  },
+  parse(input) {
+    const parsed = schema.parse(input)
+    const validationError = validateBashCommandInput(parsed.command)
+    if (validationError) {
+      throw new Error(validationError)
+    }
+    return parsed
+  },
+  async buildPermissionRequest(input, context) {
+    const cwd = input.cwd ? resolveWorkspacePath(context.workspaceRoot, input.cwd) : context.workspaceRoot
+    const safety = assessBashCommand(input.command)
+    return {
+      kind: 'bash',
+      command: input.command,
+      commandPrefix: safety.commandPrefix,
+      cwd,
+      title: 'allow shell command?',
+      subtitle: `${input.command}\n${cwd}`,
+      warning: safety.warning,
+      canPersistExact: safety.canPersistExact,
+      canPersistPrefix: safety.canPersistPrefix,
+    }
+  },
+  async execute(input, context) {
+    const cwd = input.cwd ? resolveWorkspacePath(context.workspaceRoot, input.cwd) : context.workspaceRoot
+    const output = await runCommand(input.command, cwd, context.abortSignal)
+    const relativeCwd = path.relative(context.workspaceRoot, cwd) || '.'
+    const stdout = output.stdout.trim()
+    const stderr = output.stderr.trim()
+    const parts = [
+      `cwd: ${relativeCwd}`,
+      `exit: ${output.exitCode}`,
+      stdout ? `stdout:\n${truncate(stdout)}` : '',
+      stderr ? `stderr:\n${truncate(stderr)}` : '',
+    ].filter(Boolean)
+    return {
+      ok: output.exitCode === 0,
+      summary: `ran ${input.command}`,
+      content: parts.join('\n\n'),
+    }
+  },
+}
+
+function runCommand(
+  command: string,
+  cwd: string,
+  abortSignal?: AbortSignal,
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+  return new Promise((resolve, reject) => {
+    if (abortSignal?.aborted) {
+      reject(new Error('command cancelled'))
+      return
+    }
+
+    const child = spawn(command, {
+      cwd,
+      shell: true,
+      windowsHide: true,
+    })
+    let settled = false
+    const timeout = setTimeout(() => {
+      killChildProcessTree(child.pid)
+    }, 60_000)
+    let stdout = ''
+    let stderr = ''
+    const onAbort = () => {
+      cleanup()
+      killChildProcessTree(child.pid)
+      if (!settled) {
+        settled = true
+        reject(new Error('command cancelled'))
+      }
+    }
+    const cleanup = () => {
+      clearTimeout(timeout)
+      abortSignal?.removeEventListener('abort', onAbort)
+    }
+
+    abortSignal?.addEventListener('abort', onAbort, { once: true })
+
+    child.stdout.on('data', chunk => { stdout += String(chunk) })
+    child.stderr.on('data', chunk => { stderr += String(chunk) })
+    child.on('error', error => {
+      cleanup()
+      if (settled) return
+      settled = true
+      reject(error)
+    })
+    child.on('close', code => {
+      cleanup()
+      if (settled) return
+      settled = true
+      resolve({ stdout, stderr, exitCode: code ?? 1 })
+    })
+  })
+}
+
+function killChildProcessTree(pid: number | undefined): void {
+  if (!pid) return
+  if (process.platform === 'win32') {
+    const killer = spawn('taskkill', ['/pid', String(pid), '/t', '/f'], { windowsHide: true })
+    killer.on('error', () => {})
+    killer.unref()
+    return
+  }
+  try {
+    process.kill(pid, 'SIGTERM')
+  } catch {
+  }
+}
+
+function truncate(text: string, max = 4000): string {
+  if (text.length <= max) return text
+  return `${text.slice(0, max - 3)}...`
+}

package/src/tools/changeDirectoryTool.ts

@@ -0,0 +1,213 @@
+import fs from 'node:fs/promises'
+import fsSync from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { z } from 'zod'
+import type { Tool } from './contracts.js'
+import { resolveUserPath } from '../runtime/cwd.js'
+
+const schema = z.object({
+  path: z.string().min(1),
+})
+
+export const changeDirectoryTool: Tool<typeof schema> = {
+  name: 'change_directory',
+  kind: 'cd',
+  description: 'Change the current working directory for subsequent tool use.',
+  inputSchema: schema,
+  inputSchemaJson: {
+    type: 'object',
+    properties: {
+      path: { type: 'string', description: 'Target directory path. May be relative to the current workspace or begin with ~.' },
+    },
+    required: ['path'],
+  },
+  parse(input) {
+    return schema.parse(input)
+  },
+  async buildPermissionRequest(input, context) {
+    const fullPath = resolveTargetDirectory(context.workspaceRoot, input.path)
+    return {
+      kind: 'cd',
+      path: fullPath,
+      relativePath: path.relative(context.workspaceRoot, fullPath) || path.basename(fullPath),
+      directoryPath: path.dirname(fullPath),
+      title: 'allow directory change?',
+      subtitle: fullPath,
+    }
+  },
+  async execute(input, context) {
+    const fullPath = resolveTargetDirectory(context.workspaceRoot, input.path)
+    const stat = await fs.stat(fullPath)
+    if (!stat.isDirectory()) throw new Error(`not a directory: ${input.path}`)
+    context.changeDirectory?.(fullPath)
+    return {
+      ok: true,
+      summary: `changed directory to ${fullPath}`,
+      content: fullPath,
+    }
+  },
+}
+
+function resolveTargetDirectory(workspaceRoot: string, requestedPath: string): string {
+  return resolveDirectoryIntent(requestedPath, workspaceRoot)
+}
+
+function resolveDirectoryIntent(input: string, workspaceRoot: string): string {
+  const normalized = normalizeIntentInput(input)
+  if (!normalized) {
+    throw new Error('missing directory path')
+  }
+
+  if (looksLikeConcretePath(normalized)) {
+    return resolveUserPath(normalized, workspaceRoot)
+  }
+
+  const scoped = resolveScopedPhrase(normalized, workspaceRoot)
+  if (scoped) return scoped
+
+  const direct = resolveDirectoryHint(normalized, workspaceRoot)
+  if (direct) return direct
+
+  return resolveUserPath(normalized, workspaceRoot)
+}
+
+function resolveScopedPhrase(input: string, workspaceRoot: string): string | undefined {
+  const normalized = simplifyNaturalPhrase(input)
+  const parts = normalized
+    .split(/\b(?:in|into|inside|under|within)\b/g)
+    .map(part => part.trim())
+    .filter(Boolean)
+  if (parts.length < 2) return undefined
+
+  const baseHint = parts.at(-1)
+  if (!baseHint) return undefined
+  const targetHint = parts.slice(0, -1).join(' ').trim()
+  const baseDir = resolveDirectoryHint(baseHint, workspaceRoot)
+  if (!baseDir) return undefined
+  if (!targetHint) return baseDir
+
+  if (looksLikeConcretePath(targetHint)) {
+    return path.resolve(baseDir, targetHint)
+  }
+
+  const match = findNamedChild(baseDir, targetHint)
+  if (match) return match
+
+  const segments = targetHint
+    .split(/[\\/]/)
+    .map(part => part.trim())
+    .filter(Boolean)
+  if (segments.length === 0) return baseDir
+
+  let current = baseDir
+  for (const segment of segments) {
+    const next = findNamedChild(current, segment)
+    if (!next) {
+      return path.join(baseDir, ...segments)
+    }
+    current = next
+  }
+  return current
+}
+
+function resolveDirectoryHint(input: string, workspaceRoot: string): string | undefined {
+  const hint = simplifyNaturalPhrase(input)
+  if (!hint) return undefined
+  if (looksLikeConcretePath(hint)) return resolveUserPath(hint, workspaceRoot)
+
+  const normalizedHint = hint.toLowerCase()
+  const anchors = buildSearchAnchors(workspaceRoot)
+
+  for (const candidate of anchors) {
+    if (path.basename(candidate).toLowerCase() === normalizedHint) return candidate
+  }
+
+  for (const anchor of anchors) {
+    const child = findNamedChild(anchor, normalizedHint)
+    if (child) return child
+  }
+
+  return undefined
+}
+
+function buildSearchAnchors(workspaceRoot: string): string[] {
+  const home = os.homedir()
+  const seen = new Set<string>()
+  const out: string[] = []
+  const add = (candidate: string) => {
+    const resolved = path.resolve(candidate)
+    if (seen.has(resolved)) return
+    seen.add(resolved)
+    out.push(resolved)
+  }
+
+  for (const dir of ancestorDirectories(workspaceRoot)) add(dir)
+  add(home)
+  for (const child of safeReadDirectories(home)) add(child)
+  return out
+}
+
+function ancestorDirectories(start: string): string[] {
+  const out: string[] = []
+  let current = path.resolve(start)
+  while (true) {
+    out.push(current)
+    const parent = path.dirname(current)
+    if (parent === current) break
+    current = parent
+  }
+  return out
+}
+
+function findNamedChild(parent: string, nameOrPhrase: string): string | undefined {
+  const wanted = simplifyNaturalPhrase(nameOrPhrase).toLowerCase()
+  if (!wanted) return undefined
+
+  const children = safeReadDirectories(parent)
+  for (const child of children) {
+    if (path.basename(child).toLowerCase() === wanted) return child
+  }
+
+  return undefined
+}
+
+function safeReadDirectories(dir: string): string[] {
+  try {
+    return fsSync.readdirSync(dir, { withFileTypes: true })
+      .filter(entry => entry.isDirectory())
+      .map(entry => path.join(dir, entry.name))
+  } catch {
+    return []
+  }
+}
+
+function normalizeIntentInput(input: string): string {
+  return input
+    .trim()
+    .replace(/\?+$/, '')
+    .replace(/^["'`]+|["'`]+$/g, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
+function simplifyNaturalPhrase(input: string): string {
+  return input
+    .toLowerCase()
+    .replace(/\b(?:the|my)\b/g, ' ')
+    .replace(/\b(?:folder|directory)\b/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
+function looksLikeConcretePath(input: string): boolean {
+  return (
+    input.startsWith('~') ||
+    /^[A-Za-z]:[\\/]/.test(input) ||
+    input.startsWith('/') ||
+    input.startsWith('./') ||
+    input.startsWith('../') ||
+    input.includes('\\') ||
+    input.includes('/')
+  )
+}

package/src/tools/contracts.ts

@@ -0,0 +1,179 @@
+import { z } from 'zod'
+import type { EthagentConfig } from '../storage/config.js'
+
+import type { McpRuntime } from '../mcp/manager.js'
+
+export type ToolKind = 'read' | 'write' | 'edit' | 'delete' | 'bash' | 'cd' | 'private-continuity-read' | 'private-continuity-edit' | 'mcp'
+
+export type PermissionRequest =
+  | {
+      kind: 'read'
+      path: string
+      relativePath: string
+      directoryPath: string
+      title: string
+      subtitle: string
+    }
+  | {
+      kind: 'write'
+      path: string
+      relativePath: string
+      directoryPath: string
+      title: string
+      subtitle: string
+      before: string
+      after: string
+      changeSummary: string
+    }
+  | {
+      kind: 'edit'
+      path: string
+      relativePath: string
+      directoryPath: string
+      title: string
+      subtitle: string
+      before: string
+      after: string
+      changeSummary: string
+    }
+  | {
+      kind: 'private-continuity-read'
+      path: string
+      relativePath: string
+      directoryPath: string
+      title: string
+      subtitle: string
+      file: 'SOUL.md' | 'MEMORY.md'
+      range: string
+    }
+  | {
+      kind: 'private-continuity-edit'
+      path: string
+      relativePath: string
+      directoryPath: string
+      title: string
+      subtitle: string
+      file: 'SOUL.md' | 'MEMORY.md'
+      before: string
+      after: string
+      diff: string
+      changeSummary: string
+    }
+  | {
+      kind: 'delete'
+      path: string
+      relativePath: string
+      directoryPath: string
+      title: string
+      subtitle: string
+      before: string
+      after: string
+      changeSummary: string
+    }
+  | {
+      kind: 'bash'
+      command: string
+      commandPrefix: string
+      cwd: string
+      title: string
+      subtitle: string
+      warning?: string
+      canPersistExact: boolean
+      canPersistPrefix: boolean
+    }
+  | {
+      kind: 'mcp'
+      title: string
+      subtitle: string
+      serverName: string
+      normalizedServerName: string
+      toolName: string
+      toolKey: string
+      readOnly: boolean
+      destructive: boolean
+      openWorld: boolean
+      canPersistServer: boolean
+    }
+  | {
+      kind: 'cd'
+      path: string
+      relativePath: string
+      directoryPath: string
+      title: string
+      subtitle: string
+    }
+
+export type PermissionMode = 'default' | 'plan' | 'accept-edits'
+
+export const SessionPermissionRuleSchema = z.union([
+  z.object({ kind: z.literal('read'), scope: z.literal('kind') }),
+  z.object({ kind: z.literal('read'), scope: z.literal('path'), path: z.string().min(1) }),
+  z.object({ kind: z.literal('read'), scope: z.literal('directory'), path: z.string().min(1) }),
+  z.object({ kind: z.literal('edit'), scope: z.literal('kind') }),
+  z.object({ kind: z.literal('edit'), scope: z.literal('path'), path: z.string().min(1) }),
+  z.object({ kind: z.literal('edit'), scope: z.literal('directory'), path: z.string().min(1) }),
+  z.object({ kind: z.literal('write'), scope: z.literal('kind') }),
+  z.object({ kind: z.literal('write'), scope: z.literal('path'), path: z.string().min(1) }),
+  z.object({ kind: z.literal('write'), scope: z.literal('directory'), path: z.string().min(1) }),
+  z.object({ kind: z.literal('delete'), scope: z.literal('kind') }),
+  z.object({ kind: z.literal('delete'), scope: z.literal('path'), path: z.string().min(1) }),
+  z.object({ kind: z.literal('delete'), scope: z.literal('directory'), path: z.string().min(1) }),
+  z.object({ kind: z.literal('cd'), scope: z.literal('kind') }),
+  z.object({ kind: z.literal('cd'), scope: z.literal('path'), path: z.string().min(1) }),
+  z.object({ kind: z.literal('cd'), scope: z.literal('directory'), path: z.string().min(1) }),
+  z.object({ kind: z.literal('bash'), scope: z.literal('command'), command: z.string().min(1), cwd: z.string().min(1) }),
+  z.object({ kind: z.literal('bash'), scope: z.literal('prefix'), commandPrefix: z.string().min(1), cwd: z.string().min(1) }),
+  z.object({ kind: z.literal('mcp'), scope: z.literal('tool'), toolKey: z.string().min(1) }),
+  z.object({ kind: z.literal('mcp'), scope: z.literal('server'), normalizedServerName: z.string().min(1) }),
+])
+
+export type SessionPermissionRule = z.infer<typeof SessionPermissionRuleSchema>
+
+export type PermissionDecision =
+  | 'allow-once'
+  | 'allow-kind-project'
+  | 'allow-path-project'
+  | 'allow-directory-project'
+  | 'allow-command-project'
+  | 'allow-command-prefix-project'
+  | 'allow-mcp-tool-project'
+  | 'allow-mcp-server-project'
+  | 'deny'
+
+export type ToolResult =
+  | { ok: true; summary: string; content: string }
+  | { ok: false; summary: string; content: string }
+
+export type ToolExecutionContext = {
+  workspaceRoot: string
+  config?: EthagentConfig
+  abortSignal?: AbortSignal
+  mcp?: McpRuntime
+  changeDirectory?: (next: string) => void
+  checkpoint?: {
+    sessionId: string
+    turnId: string
+    messageRole: 'user'
+    promptSnippet: string
+    checkpointLabel: string
+  }
+}
+
+export type Tool<Input extends z.ZodTypeAny = z.ZodTypeAny> = {
+  name: string
+  kind: ToolKind
+  description: string
+  inputSchema: Input
+  inputSchemaJson: {
+    type: 'object'
+    properties?: Record<string, unknown>
+    required?: string[]
+    oneOf?: Array<Record<string, unknown>>
+    anyOf?: Array<Record<string, unknown>>
+    additionalProperties?: boolean
+  }
+  readOnly?: boolean
+  parse(input: Record<string, unknown>): z.infer<Input>
+  buildPermissionRequest(input: z.infer<Input>, context: ToolExecutionContext): Promise<PermissionRequest>
+  execute(input: z.infer<Input>, context: ToolExecutionContext): Promise<ToolResult>
+}

package/src/tools/deleteFileTool.ts

@@ -0,0 +1,111 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { z } from 'zod'
+import { recordRewindSnapshot } from '../storage/rewind.js'
+import type { Tool } from './contracts.js'
+import { resolveWorkspacePath } from './readTool.js'
+
+const schema = z.object({
+  path: z.string().min(1),
+})
+
+export const deleteFileTool: Tool<typeof schema> = {
+  name: 'delete_file',
+  kind: 'delete',
+  description: 'Delete one file in the current workspace. Use this for user requests to remove a file; do not use run_bash for normal file deletion.',
+  inputSchema: schema,
+  inputSchemaJson: {
+    type: 'object',
+    properties: {
+      path: { type: 'string', description: 'Path to the file to delete.' },
+    },
+    required: ['path'],
+  },
+  parse(input) {
+    return schema.parse(input)
+  },
+  async buildPermissionRequest(input, context) {
+    const prepared = await prepareDelete(input, context)
+    return {
+      kind: 'delete',
+      path: prepared.fullPath,
+      relativePath: prepared.relativePath,
+      directoryPath: path.dirname(prepared.fullPath),
+      title: 'allow file delete?',
+      subtitle: prepared.fullPath,
+      before: preview(prepared.before),
+      after: '(deleted)',
+      changeSummary: `delete ${prepared.relativePath}`,
+    }
+  },
+  async execute(input, context) {
+    const prepared = await prepareDelete(input, context)
+    const rewindWarning = await tryRecordRewindSnapshot({
+      workspaceRoot: context.workspaceRoot,
+      filePath: prepared.fullPath,
+      relativePath: prepared.relativePath,
+      existedBefore: true,
+      previousContent: prepared.before,
+      changeSummary: `restore deleted ${prepared.relativePath}`,
+      createdAt: new Date().toISOString(),
+      sessionId: context.checkpoint?.sessionId,
+      turnId: context.checkpoint?.turnId,
+      messageRole: context.checkpoint?.messageRole,
+      promptSnippet: context.checkpoint?.promptSnippet,
+      checkpointLabel: context.checkpoint?.checkpointLabel,
+    })
+    await fs.unlink(prepared.fullPath)
+    return {
+      ok: true,
+      summary: `deleted ${prepared.relativePath}`,
+      content: rewindWarning
+        ? `deleted ${prepared.fullPath}\nwarning: ${rewindWarning}`
+        : `deleted ${prepared.fullPath}`,
+    }
+  },
+}
+
+async function prepareDelete(input: z.infer<typeof schema>, context: { workspaceRoot: string }) {
+  assertSafeDeletePath(input.path)
+  const fullPath = resolveWorkspacePath(context.workspaceRoot, input.path)
+  const stats = await fs.stat(fullPath)
+  if (stats.isDirectory()) {
+    throw new Error('delete_file path points to a directory; provide a file path')
+  }
+  const before = await fs.readFile(fullPath, 'utf8')
+  return {
+    fullPath,
+    relativePath: path.relative(context.workspaceRoot, fullPath) || path.basename(fullPath),
+    before,
+  }
+}
+
+function assertSafeDeletePath(requestedPath: string): void {
+  const trimmed = requestedPath.trim()
+  if (trimmed !== requestedPath || trimmed.length === 0) {
+    throw new Error('delete_file path must be a clean workspace-relative file path')
+  }
+  if (/[|;&<>`]/.test(trimmed)) {
+    throw new Error('delete_file path must not contain shell operators')
+  }
+  if (/^(?:rm|del|erase|rmdir|remove-item|mkdir|type|cat|echo|copy|move|mv|cp)\b/i.test(trimmed)) {
+    throw new Error('delete_file path looks like a shell command; pass only the file path')
+  }
+}
+
+async function tryRecordRewindSnapshot(
+  snapshot: Parameters<typeof recordRewindSnapshot>[0],
+): Promise<string | undefined> {
+  try {
+    await recordRewindSnapshot(snapshot)
+    return undefined
+  } catch (error: unknown) {
+    const message = (error as Error).message || 'rewind checkpoint could not be recorded'
+    return `rewind checkpoint was not recorded (${message})`
+  }
+}
+
+function preview(text: string, max = 1200): string {
+  if (text.length <= max) return text
+  return `${text.slice(0, max - 3)}...`
+}