ethagent 0.2.1 → 1.0.0

package/src/tools/editTool.ts

@@ -0,0 +1,160 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { z } from 'zod'
+import { recordRewindSnapshot } from '../storage/rewind.js'
+import type { EthagentConfig } from '../storage/config.js'
+import type { Tool } from './contracts.js'
+import { applyRequestedEdit } from './editUtils.js'
+import { resolveWorkspacePath } from './readTool.js'
+
+const schema = z.object({
+  path: z.string().min(1),
+  oldText: z.string().optional(),
+  newText: z.string(),
+  replaceAll: z.boolean().optional(),
+  replaceWholeFile: z.boolean().optional(),
+})
+
+export const editTool: Tool<typeof schema> = {
+  name: 'edit_file',
+  kind: 'edit',
+  description: 'Edit a workspace text file. Provide oldText and newText for targeted replacement, or just newText only for ordinary whole-file workspace edits. Do not use for private SOUL.md or MEMORY.md when an identity is linked; use propose_private_continuity_edit instead.',
+  inputSchema: schema,
+  inputSchemaJson: {
+    type: 'object',
+    properties: {
+      path: { type: 'string', description: 'Path to the file to edit.' },
+      oldText: { type: 'string', description: 'Exact text to find and replace. Prefer this for existing files. Omit only for ordinary whole-file workspace edits.' },
+      newText: { type: 'string', description: 'Replacement text, or entire file contents if oldText is omitted.' },
+      replaceAll: { type: 'boolean', description: 'Replace every exact oldText match. Prefer false unless you are certain.' },
+    },
+    required: ['path', 'newText'],
+  },
+  parse(input) {
+    return schema.parse(input)
+  },
+  async buildPermissionRequest(input, context) {
+    const { fullPath, relativePath, applied } = await prepareEdit(input, context)
+    return {
+      kind: 'edit',
+      path: fullPath,
+      relativePath,
+      directoryPath: path.dirname(fullPath),
+      title: 'allow file edit?',
+      subtitle: fullPath,
+      before: applied.previewBefore,
+      after: applied.previewAfter,
+      changeSummary: applied.summary,
+    }
+  },
+  async execute(input, context) {
+    const { fullPath, applied, existedBefore, before } = await prepareEdit(input, context)
+    const rewindWarning = await tryRecordRewindSnapshot({
+      workspaceRoot: context.workspaceRoot,
+      filePath: fullPath,
+      relativePath: path.relative(context.workspaceRoot, fullPath) || path.basename(fullPath),
+      existedBefore,
+      previousContent: before,
+      changeSummary: applied.summary,
+      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.mkdir(path.dirname(fullPath), { recursive: true })
+    await fs.writeFile(fullPath, applied.after, 'utf8')
+    return {
+      ok: true,
+      summary: applied.summary,
+      content: rewindWarning
+        ? `updated ${fullPath}\nwarning: ${rewindWarning}`
+        : `updated ${fullPath}`,
+    }
+  },
+}
+
+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})`
+  }
+}
+
+async function prepareEdit(input: z.infer<typeof schema>, context: { workspaceRoot: string; config?: EthagentConfig }) {
+  assertSafeEditPath(input.path)
+  assertNotPrivateContinuityWorkspacePath(input.path, context.config, 'edit_file')
+  const fullPath = resolveWorkspacePath(context.workspaceRoot, input.path)
+  await assertEditableFileTarget(fullPath)
+  const { content: before, existed } = await readOptionalTextFile(fullPath)
+  const applied = applyRequestedEdit(
+    input.path,
+    before,
+    input.oldText,
+    input.newText,
+    input.replaceAll ?? false,
+    input.replaceWholeFile ?? false,
+  )
+  return {
+    fullPath,
+    relativePath: path.relative(context.workspaceRoot, fullPath) || path.basename(fullPath),
+    existedBefore: existed,
+    before,
+    applied,
+  }
+}
+
+async function assertEditableFileTarget(fullPath: string): Promise<void> {
+  try {
+    const stats = await fs.stat(fullPath)
+    if (stats.isDirectory()) {
+      throw new Error('edit_file path points to a directory; provide a file path')
+    }
+  } catch (error: unknown) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return
+    throw error
+  }
+}
+
+function assertSafeEditPath(requestedPath: string): void {
+  const trimmed = requestedPath.trim()
+  if (trimmed !== requestedPath || trimmed.length === 0) {
+    throw new Error('edit_file path must be a clean workspace-relative file path')
+  }
+
+  if (/[|;&<>`]/.test(trimmed)) {
+    throw new Error('edit_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('edit_file path looks like a shell command; pass only the file path')
+  }
+}
+
+function assertNotPrivateContinuityWorkspacePath(
+  requestedPath: string,
+  config: EthagentConfig | undefined,
+  toolName: string,
+): void {
+  if (!config?.identity) return
+  const basename = path.basename(requestedPath.replaceAll('\\', '/')).toUpperCase()
+  if (basename !== 'SOUL.MD' && basename !== 'MEMORY.MD') return
+  throw new Error(
+    `${toolName} must not create or overwrite ${basename}; use propose_private_continuity_edit to patch the existing identity-vault scaffold`,
+  )
+}
+
+async function readOptionalTextFile(fullPath: string): Promise<{ content: string; existed: boolean }> {
+  try {
+    return { content: await fs.readFile(fullPath, 'utf8'), existed: true }
+  } catch (error: unknown) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return { content: '', existed: false }
+    throw error
+  }
+}

package/src/tools/editUtils.ts

@@ -0,0 +1,170 @@
+const LEFT_SINGLE_CURLY_QUOTE = '\u2018'
+const RIGHT_SINGLE_CURLY_QUOTE = '\u2019'
+const LEFT_DOUBLE_CURLY_QUOTE = '\u201c'
+const RIGHT_DOUBLE_CURLY_QUOTE = '\u201d'
+
+export type AppliedEdit = {
+  before: string
+  after: string
+  summary: string
+  previewBefore: string
+  previewAfter: string
+}
+
+export function applyRequestedEdit(
+  filePath: string,
+  before: string,
+  oldText: string | undefined,
+  newText: string,
+  replaceAll = false,
+  _replaceWholeFile = false,
+): AppliedEdit {
+  if (!oldText) {
+    if (newText.length === 0) {
+      throw new Error('edit_file newText is empty; empty whole-file writes are not valid unless replacing a specific oldText range')
+    }
+    return {
+      before,
+      after: newText,
+      summary: before.length === 0 ? `create ${filePath}` : `replace entire ${filePath}`,
+      previewBefore: previewText(before),
+      previewAfter: previewText(newText),
+    }
+  }
+
+  if (replaceAll) {
+    const matchCount = countOccurrences(before, oldText)
+    if (matchCount === 0) throw new Error('oldText was not found in the file')
+    return {
+      before,
+      after: before.replaceAll(oldText, () => newText),
+      summary: `replace ${matchCount} match${matchCount === 1 ? '' : 'es'} in ${filePath}`,
+      previewBefore: previewText(oldText),
+      previewAfter: previewText(newText),
+    }
+  }
+
+  const actualOldText = findUniqueEditableMatch(before, oldText)
+  if (!actualOldText) throw new Error('oldText was not found in the file')
+  if (countOccurrences(before, actualOldText) > 1) {
+    throw new Error('oldText matched multiple locations; provide more context or use replaceAll')
+  }
+
+  const adjustedNewText = preserveQuoteStyle(oldText, actualOldText, newText)
+  return {
+    before,
+    after: replaceSingleOccurrence(before, actualOldText, adjustedNewText),
+    summary: `edit ${filePath}`,
+    previewBefore: previewText(actualOldText),
+    previewAfter: previewText(adjustedNewText),
+  }
+}
+
+function replaceSingleOccurrence(content: string, search: string, replace: string): string {
+  const index = content.indexOf(search)
+  if (index === -1) throw new Error('oldText was not found in the file')
+  return `${content.slice(0, index)}${replace}${content.slice(index + search.length)}`
+}
+
+function findUniqueEditableMatch(fileContent: string, searchText: string): string | null {
+  const exactCount = countOccurrences(fileContent, searchText)
+  if (exactCount === 1) return searchText
+  if (exactCount > 1) return searchText
+
+  const normalizedSearch = normalizeQuotes(searchText)
+  const normalizedFile = normalizeQuotes(fileContent)
+  const firstIndex = normalizedFile.indexOf(normalizedSearch)
+  if (firstIndex === -1) return null
+
+  const secondIndex = normalizedFile.indexOf(normalizedSearch, firstIndex + normalizedSearch.length)
+  if (secondIndex !== -1) return null
+
+  return fileContent.slice(firstIndex, firstIndex + searchText.length)
+}
+
+function countOccurrences(content: string, search: string): number {
+  if (!search) return 0
+  let count = 0
+  let offset = 0
+  while (true) {
+    const index = content.indexOf(search, offset)
+    if (index === -1) return count
+    count += 1
+    offset = index + search.length
+  }
+}
+
+function normalizeQuotes(text: string): string {
+  return text
+    .replaceAll(LEFT_SINGLE_CURLY_QUOTE, "'")
+    .replaceAll(RIGHT_SINGLE_CURLY_QUOTE, "'")
+    .replaceAll(LEFT_DOUBLE_CURLY_QUOTE, '"')
+    .replaceAll(RIGHT_DOUBLE_CURLY_QUOTE, '"')
+}
+
+function preserveQuoteStyle(oldText: string, actualOldText: string, newText: string): string {
+  if (oldText === actualOldText) return newText
+
+  let result = newText
+  if (containsCurlyDoubleQuotes(actualOldText)) result = applyCurlyDoubleQuotes(result)
+  if (containsCurlySingleQuotes(actualOldText)) result = applyCurlySingleQuotes(result)
+  return result
+}
+
+function containsCurlyDoubleQuotes(text: string): boolean {
+  return text.includes(LEFT_DOUBLE_CURLY_QUOTE) || text.includes(RIGHT_DOUBLE_CURLY_QUOTE)
+}
+
+function containsCurlySingleQuotes(text: string): boolean {
+  return text.includes(LEFT_SINGLE_CURLY_QUOTE) || text.includes(RIGHT_SINGLE_CURLY_QUOTE)
+}
+
+function applyCurlyDoubleQuotes(text: string): string {
+  const chars = [...text]
+  const out: string[] = []
+
+  for (let index = 0; index < chars.length; index += 1) {
+    const char = chars[index]
+    if (char !== '"') {
+      out.push(char!)
+      continue
+    }
+    out.push(isOpeningContext(chars, index) ? LEFT_DOUBLE_CURLY_QUOTE : RIGHT_DOUBLE_CURLY_QUOTE)
+  }
+
+  return out.join('')
+}
+
+function applyCurlySingleQuotes(text: string): string {
+  const chars = [...text]
+  const out: string[] = []
+
+  for (let index = 0; index < chars.length; index += 1) {
+    const char = chars[index]
+    if (char !== "'") {
+      out.push(char!)
+      continue
+    }
+
+    const prev = index > 0 ? chars[index - 1] : undefined
+    const next = index < chars.length - 1 ? chars[index + 1] : undefined
+    if (prev && next && /\p{L}/u.test(prev) && /\p{L}/u.test(next)) {
+      out.push(RIGHT_SINGLE_CURLY_QUOTE)
+      continue
+    }
+
+    out.push(isOpeningContext(chars, index) ? LEFT_SINGLE_CURLY_QUOTE : RIGHT_SINGLE_CURLY_QUOTE)
+  }
+
+  return out.join('')
+}
+
+function isOpeningContext(chars: string[], index: number): boolean {
+  if (index === 0) return true
+  return [' ', '\t', '\n', '\r', '(', '[', '{'].includes(chars[index - 1] ?? '')
+}
+
+function previewText(text: string, max = 700): string {
+  if (text.length <= max) return text
+  return `${text.slice(0, max - 3)}...`
+}

package/src/tools/listDirectoryTool.ts

@@ -0,0 +1,55 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { z } from 'zod'
+import type { Tool } from './contracts.js'
+import { resolveWorkspacePath } from './readTool.js'
+
+const schema = z.object({
+  path: z.string().optional(),
+})
+
+export const listDirectoryTool: Tool<typeof schema> = {
+  name: 'list_directory',
+  kind: 'read',
+  description: 'List files and folders in the current workspace. Use this first when you need to discover existing files before reading or editing them.',
+  inputSchema: schema,
+  inputSchemaJson: {
+    type: 'object',
+    properties: {
+      path: { type: 'string', description: 'Optional directory path relative to the current workspace.' },
+    },
+    required: [],
+  },
+  parse(input) {
+    return schema.parse(input)
+  },
+  async buildPermissionRequest(input, context) {
+    const fullPath = resolveWorkspacePath(context.workspaceRoot, input.path ?? '.')
+    const relativePath = path.relative(context.workspaceRoot, fullPath) || '.'
+    return {
+      kind: 'read',
+      path: fullPath,
+      relativePath,
+      directoryPath: fullPath,
+      title: 'allow directory listing?',
+      subtitle: fullPath,
+    }
+  },
+  async execute(input, context) {
+    const fullPath = resolveWorkspacePath(context.workspaceRoot, input.path ?? '.')
+    const entries = await fs.readdir(fullPath, { withFileTypes: true })
+    const lines = entries
+      .sort((left, right) => {
+        if (left.isDirectory() && !right.isDirectory()) return -1
+        if (!left.isDirectory() && right.isDirectory()) return 1
+        return left.name.localeCompare(right.name)
+      })
+      .map(entry => `${entry.isDirectory() ? '[dir]' : '     '} ${entry.name}`)
+    const relativePath = path.relative(context.workspaceRoot, fullPath) || '.'
+    return {
+      ok: true,
+      summary: `listed ${relativePath}`,
+      content: lines.length > 0 ? lines.join('\n') : '(empty directory)',
+    }
+  },
+}

package/src/tools/mcpResourceTools.ts

@@ -0,0 +1,95 @@
+import { z } from 'zod'
+import type { Tool } from './contracts.js'
+import { normalizeNameForMcp } from '../mcp/names.js'
+
+const ListMcpResourcesInput = z.object({
+  server: z.string().min(1).optional(),
+})
+
+const ReadMcpResourceInput = z.object({
+  server: z.string().min(1),
+  uri: z.string().min(1),
+})
+
+export const listMcpResourcesTool: Tool<typeof ListMcpResourcesInput> = {
+  name: 'list_mcp_resources',
+  kind: 'mcp',
+  readOnly: true,
+  description: 'List resources exposed by connected MCP servers.',
+  inputSchema: ListMcpResourcesInput,
+  inputSchemaJson: {
+    type: 'object',
+    properties: {
+      server: { type: 'string', description: 'Optional MCP server name. Omit to list resources from every connected server.' },
+    },
+  },
+  parse(input) {
+    return ListMcpResourcesInput.parse(input)
+  },
+  async buildPermissionRequest(input) {
+    const serverName = input.server ?? '*'
+    return {
+      kind: 'mcp',
+      title: 'allow MCP resource listing?',
+      subtitle: input.server ? `list resources from ${input.server}` : 'list resources from all connected MCP servers',
+      serverName,
+      normalizedServerName: normalizeNameForMcp(serverName),
+      toolName: 'list_mcp_resources',
+      toolKey: 'list_mcp_resources',
+      readOnly: true,
+      destructive: false,
+      openWorld: false,
+      canPersistServer: Boolean(input.server),
+    }
+  },
+  async execute(input, context) {
+    if (!context.mcp) return { ok: false, summary: 'MCP unavailable', content: 'MCP runtime is not available.' }
+    return {
+      ok: true,
+      summary: input.server ? `listed MCP resources from ${input.server}` : 'listed MCP resources',
+      content: await context.mcp.listResources(input.server),
+    }
+  },
+}
+
+export const readMcpResourceTool: Tool<typeof ReadMcpResourceInput> = {
+  name: 'read_mcp_resource',
+  kind: 'mcp',
+  readOnly: true,
+  description: 'Read a specific resource from a connected MCP server.',
+  inputSchema: ReadMcpResourceInput,
+  inputSchemaJson: {
+    type: 'object',
+    properties: {
+      server: { type: 'string', description: 'The connected MCP server name.' },
+      uri: { type: 'string', description: 'The resource URI to read.' },
+    },
+    required: ['server', 'uri'],
+  },
+  parse(input) {
+    return ReadMcpResourceInput.parse(input)
+  },
+  async buildPermissionRequest(input) {
+    return {
+      kind: 'mcp',
+      title: 'allow MCP resource read?',
+      subtitle: `${input.server} / ${input.uri}`,
+      serverName: input.server,
+      normalizedServerName: normalizeNameForMcp(input.server),
+      toolName: 'read_mcp_resource',
+      toolKey: `read_mcp_resource:${normalizeNameForMcp(input.server)}`,
+      readOnly: true,
+      destructive: false,
+      openWorld: false,
+      canPersistServer: true,
+    }
+  },
+  async execute(input, context) {
+    if (!context.mcp) return { ok: false, summary: 'MCP unavailable', content: 'MCP runtime is not available.' }
+    return {
+      ok: true,
+      summary: `read MCP resource ${input.uri}`,
+      content: await context.mcp.readResource(input.server, input.uri, context.abortSignal),
+    }
+  },
+}

package/src/tools/permissionRules.ts

@@ -0,0 +1,85 @@
+import path from 'node:path'
+import type { PermissionDecision, PermissionRequest, SessionPermissionRule } from './contracts.js'
+
+export function buildPermissionRule(
+  decision: PermissionDecision,
+  request: PermissionRequest,
+): SessionPermissionRule | undefined {
+  switch (decision) {
+    case 'allow-kind-project':
+      if (request.kind === 'read' || request.kind === 'edit' || request.kind === 'write' || request.kind === 'cd') return { kind: request.kind, scope: 'kind' }
+      return undefined
+    case 'allow-path-project':
+      if (request.kind === 'read' || request.kind === 'edit' || request.kind === 'write' || request.kind === 'cd') {
+        return { kind: request.kind, scope: 'path', path: request.path }
+      }
+      return undefined
+    case 'allow-directory-project':
+      if (request.kind === 'read' || request.kind === 'edit' || request.kind === 'write' || request.kind === 'cd') {
+        return { kind: request.kind, scope: 'directory', path: request.directoryPath }
+      }
+      return undefined
+    case 'allow-command-project':
+      if (request.kind === 'bash' && request.canPersistExact) {
+        return { kind: 'bash', scope: 'command', command: request.command, cwd: request.cwd }
+      }
+      return undefined
+    case 'allow-command-prefix-project':
+      if (request.kind === 'bash' && request.canPersistPrefix && request.commandPrefix) {
+        return { kind: 'bash', scope: 'prefix', commandPrefix: request.commandPrefix, cwd: request.cwd }
+      }
+      return undefined
+    case 'allow-mcp-tool-project':
+      if (request.kind === 'mcp') return { kind: 'mcp', scope: 'tool', toolKey: request.toolKey }
+      return undefined
+    case 'allow-mcp-server-project':
+      if (request.kind === 'mcp' && request.canPersistServer) {
+        return { kind: 'mcp', scope: 'server', normalizedServerName: request.normalizedServerName }
+      }
+      return undefined
+    default:
+      return undefined
+  }
+}
+
+export function matchPermissionRule(
+  rules: SessionPermissionRule[],
+  request: PermissionRequest,
+): SessionPermissionRule | undefined {
+  return rules.find(rule => matchesPermissionRule(rule, request))
+}
+
+export function shouldPersistPermissionDecision(decision: PermissionDecision): boolean {
+  return decision !== 'allow-once' && decision !== 'deny'
+}
+
+function matchesPermissionRule(rule: SessionPermissionRule, request: PermissionRequest): boolean {
+  if (rule.kind !== request.kind) return false
+
+  if (request.kind === 'read' || request.kind === 'edit' || request.kind === 'write' || request.kind === 'delete' || request.kind === 'cd') {
+    if (request.kind === 'delete') return false
+    if (rule.scope === 'kind') return true
+    if (rule.scope === 'path') return rule.path === request.path
+    if (rule.scope === 'directory') {
+      return request.path === rule.path || request.path.startsWith(`${rule.path}${path.sep}`)
+    }
+    return false
+  }
+
+  if (request.kind === 'bash') {
+    if (rule.scope === 'command') return rule.command === request.command && rule.cwd === request.cwd
+    if (rule.scope === 'prefix') {
+      const normalizedCommand = request.command.trim()
+      return (
+        rule.cwd === request.cwd &&
+        (normalizedCommand === rule.commandPrefix || normalizedCommand.startsWith(`${rule.commandPrefix} `))
+      )
+    }
+  }
+
+  if (request.kind === 'mcp') {
+    if (rule.scope === 'tool') return rule.toolKey === request.toolKey
+    if (rule.scope === 'server') return rule.normalizedServerName === request.normalizedServerName
+  }
+  return false
+}