ethagent 1.1.2 → 2.0.0

package/src/identity/continuity/history.ts

@@ -11,7 +11,7 @@ import {
   type PrivateContinuityFile,
 } from './storage.js'
 
-export type PrivateContinuityHistorySnapshot = {
+type PrivateContinuityHistorySnapshot = {
   version: 1
   id: string
   createdAt: string
@@ -35,7 +35,7 @@ export type PrivateContinuityHistorySnapshot = {
   checkpointLabel?: string
 }
 
-export type RecordPrivateContinuityHistoryInput = {
+type RecordPrivateContinuityHistoryInput = {
   identity: EthagentIdentity
   file: PrivateContinuityFile
   filePath: string
@@ -51,7 +51,7 @@ export type RecordPrivateContinuityHistoryInput = {
   checkpointLabel?: string
 }
 
-export function privateContinuityHistoryPath(identity: EthagentIdentity): string {
+function privateContinuityHistoryPath(identity: EthagentIdentity): string {
   return path.join(continuityVaultRef(identity).dir, '.history.jsonl')
 }
 
@@ -121,7 +121,7 @@ export async function restorePrivateContinuityHistorySnapshot(
 ): Promise<PrivateContinuityHistorySnapshot> {
   const snapshot = (await listPrivateContinuityHistory(identity, 500))
     .find(item => item.id === snapshotId)
-  if (!snapshot) throw new Error('private continuity checkpoint was not found')
+  if (!snapshot) throw new Error('Private continuity checkpoint was not found')
 
   if (snapshot.previousFiles) {
     await writeContinuityFiles(identity, snapshot.previousFiles)

package/src/identity/continuity/localBackup.ts

@@ -0,0 +1,249 @@
+import { spawn } from 'node:child_process'
+import fs from 'node:fs'
+import fsp from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import type { EthagentIdentity } from '../../storage/config.js'
+import { continuityVaultRef } from './storage.js'
+import { buildZip, type ZipEntry } from './zipWriter.js'
+
+type LocalBackupResult =
+  | { ok: true; path: string; method: string }
+  | { ok: false; cancelled: boolean; error: string }
+
+type SaveDialogCommand = {
+  cmd: string
+  args: string[]
+  method: string
+}
+
+export async function exportLocalBackup(
+  identity: EthagentIdentity,
+  options: {
+    platform?: NodeJS.Platform
+    env?: NodeJS.ProcessEnv
+    timeoutMs?: number
+    spawnImpl?: typeof spawn
+    homeDir?: string
+  } = {},
+): Promise<LocalBackupResult> {
+  const platform = options.platform ?? process.platform
+  const env = options.env ?? process.env
+  const homeDir = options.homeDir ?? os.homedir()
+  const ref = continuityVaultRef(identity)
+
+  const entries: ZipEntry[] = []
+  for (const [name, file] of [
+    ['SOUL.md', ref.soulPath],
+    ['MEMORY.md', ref.memoryPath],
+    ['skills.json', ref.publicSkillsPath],
+  ] as const) {
+    try {
+      const data = await fsp.readFile(file)
+      entries.push({ name, data })
+    } catch (err: unknown) {
+      const code = (err as NodeJS.ErrnoException).code
+      if (code !== 'ENOENT') {
+        return { ok: false, cancelled: false, error: `read ${name} failed: ${(err as Error).message}` }
+      }
+    }
+  }
+  if (entries.length === 0) {
+    return { ok: false, cancelled: false, error: 'no local continuity files to back up' }
+  }
+
+  const archive = buildZip(entries)
+  const defaultName = defaultBackupFilename(identity)
+  const dialog = resolveSaveDialogCommand(platform, env, defaultName)
+
+  if (dialog) {
+    const chosen = await runSaveDialog(dialog, options.spawnImpl ?? spawn, options.timeoutMs ?? 120_000)
+    if (chosen.ok) {
+      const target = ensureZipExtension(chosen.file)
+      try {
+        await fsp.writeFile(target, archive)
+        return { ok: true, path: target, method: dialog.method }
+      } catch (err: unknown) {
+        return { ok: false, cancelled: false, error: `write failed: ${(err as Error).message}` }
+      }
+    }
+    if (!chosen.cancelled) {
+      const fallback = path.join(homeDir, defaultName)
+      try {
+        await fsp.writeFile(fallback, archive)
+        return { ok: true, path: fallback, method: 'home dir fallback' }
+      } catch (err: unknown) {
+        return { ok: false, cancelled: false, error: `write failed: ${(err as Error).message}` }
+      }
+    }
+    return chosen
+  }
+
+  const fallback = path.join(homeDir, defaultName)
+  try {
+    await fsp.writeFile(fallback, archive)
+    return { ok: true, path: fallback, method: 'home dir' }
+  } catch (err: unknown) {
+    return { ok: false, cancelled: false, error: `write failed: ${(err as Error).message}` }
+  }
+}
+
+function defaultBackupFilename(identity: EthagentIdentity): string {
+  const idPart = identity.agentId ? `agent-${identity.agentId}` : 'agent'
+  const stamp = timestampSlug(new Date())
+  return `ethagent-backup-${idPart}-${stamp}.zip`
+}
+
+function timestampSlug(date: Date): string {
+  const pad = (n: number): string => String(n).padStart(2, '0')
+  return `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}-${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`
+}
+
+function ensureZipExtension(file: string): string {
+  return /\.zip$/i.test(file) ? file : `${file}.zip`
+}
+
+function resolveSaveDialogCommand(platform: NodeJS.Platform, env: NodeJS.ProcessEnv, defaultName: string): SaveDialogCommand | null {
+  if (platform === 'win32') {
+    const powershell = findExecutable('powershell.exe', env, platform) ?? findExecutable('pwsh.exe', env, platform)
+    if (!powershell) return null
+    return {
+      cmd: powershell,
+      args: [
+        '-NoProfile',
+        '-STA',
+        '-ExecutionPolicy',
+        'Bypass',
+        '-Command',
+        [
+          '[Console]::OutputEncoding = [System.Text.Encoding]::UTF8',
+          'Add-Type -AssemblyName System.Windows.Forms',
+          '$dialog = New-Object System.Windows.Forms.SaveFileDialog',
+          '$dialog.Title = "Save Local Backup"',
+          '$dialog.Filter = "Zip archive (*.zip)|*.zip|All files (*.*)|*.*"',
+          '$dialog.DefaultExt = "zip"',
+          `$dialog.FileName = "${defaultName.replace(/"/g, '`"')}"`,
+          '$dialog.OverwritePrompt = $true',
+          'if ($dialog.ShowDialog() -eq [System.Windows.Forms.DialogResult]::OK) { Write-Output $dialog.FileName }',
+        ].join('; '),
+      ],
+      method: 'windows save dialog',
+    }
+  }
+  if (platform === 'darwin') {
+    return {
+      cmd: 'osascript',
+      args: [
+        '-e',
+        `set chosen to choose file name with prompt "Save Local Backup" default name "${defaultName.replace(/"/g, '\\"')}"`,
+        '-e',
+        'POSIX path of chosen',
+      ],
+      method: 'macOS save dialog',
+    }
+  }
+  const zenity = findExecutable('zenity', env, platform)
+  if (zenity) {
+    return {
+      cmd: zenity,
+      args: [
+        '--file-selection',
+        '--save',
+        '--confirm-overwrite',
+        '--title=Save Local Backup',
+        `--filename=${path.join(env.HOME ?? '.', defaultName)}`,
+        '--file-filter=Zip archive | *.zip',
+      ],
+      method: 'zenity',
+    }
+  }
+  const kdialog = findExecutable('kdialog', env, platform)
+  if (kdialog) {
+    return {
+      cmd: kdialog,
+      args: ['--getsavefilename', path.join(env.HOME ?? '.', defaultName), 'Zip archive (*.zip)'],
+      method: 'kdialog',
+    }
+  }
+  return null
+}
+
+function runSaveDialog(
+  command: SaveDialogCommand,
+  spawnImpl: typeof spawn,
+  timeoutMs: number,
+): Promise<{ ok: true; file: string } | { ok: false; cancelled: boolean; error: string }> {
+  return new Promise(resolve => {
+    let stdout = ''
+    let stderr = ''
+    let settled = false
+    let child: ReturnType<typeof spawn>
+    try {
+      child = spawnImpl(command.cmd, command.args, {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        windowsHide: true,
+      })
+    } catch (err: unknown) {
+      resolve({ ok: false, cancelled: false, error: (err as Error).message })
+      return
+    }
+    const timer = setTimeout(() => {
+      if (settled) return
+      settled = true
+      child.kill()
+      resolve({ ok: false, cancelled: false, error: 'save dialog timed out' })
+    }, timeoutMs)
+    child.stdout?.setEncoding('utf8')
+    child.stderr?.setEncoding('utf8')
+    child.stdout?.on('data', chunk => { stdout += String(chunk) })
+    child.stderr?.on('data', chunk => { stderr += String(chunk) })
+    child.on('error', err => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      resolve({ ok: false, cancelled: false, error: err.message })
+    })
+    child.on('close', code => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      const file = stdout.trim()
+      if (code === 0 && file) {
+        resolve({ ok: true, file })
+        return
+      }
+      const detail = stderr.trim()
+      const cancelled = code === 0 || /cancel/i.test(detail)
+      resolve({ ok: false, cancelled, error: cancelled ? 'save cancelled' : detail || `${command.method} exited ${code}` })
+    })
+  })
+}
+
+function findExecutable(command: string, env: NodeJS.ProcessEnv, platform: NodeJS.Platform): string | null {
+  const hasPathSeparator = command.includes('/') || command.includes('\\')
+  if (hasPathSeparator || path.isAbsolute(command)) return canAccessExecutable(command) ? command : null
+  const pathParts = (env.PATH ?? '').split(path.delimiter).filter(Boolean)
+  const extensions = platform === 'win32'
+    ? (env.PATHEXT ?? '.EXE;.CMD;.BAT;.COM').split(';').filter(Boolean)
+    : ['']
+  for (const dir of pathParts) {
+    for (const ext of extensions) {
+      const candidate = path.join(dir, platform === 'win32' && path.extname(command) === '' ? `${command}${ext}` : command)
+      if (canAccessExecutable(candidate)) return candidate
+      if (platform === 'win32') {
+        const lower = path.join(dir, path.extname(command) === '' ? `${command}${ext.toLowerCase()}` : command)
+        if (canAccessExecutable(lower)) return lower
+      }
+    }
+  }
+  return null
+}
+
+function canAccessExecutable(file: string): boolean {
+  try {
+    fs.accessSync(file, fs.constants.X_OK)
+    return true
+  } catch {
+    return false
+  }
+}

package/src/identity/continuity/privateEdit/apply.ts

@@ -0,0 +1,170 @@
+import type { EthagentIdentity } from '../../../storage/config.js'
+import { applyRequestedEdit } from '../../../tools/editUtils.js'
+import { defaultContinuityFiles, type PrivateContinuityFile } from '../storage.js'
+import type { PrivateContinuityEditInput } from './types.js'
+
+export function applyPrivateContinuityEdit(input: PrivateContinuityEditInput, before: string, identity: EthagentIdentity) {
+  if (input.replaceWholeFile) {
+    throw new Error('Private continuity files must be edited in place; whole-file replacement is disabled')
+  }
+  if (input.appendToSection || input.appendText) {
+    if (!input.appendToSection?.trim()) throw new Error('Field appendToSection is required for append edits')
+    if (!input.appendText?.trim()) throw new Error('Field appendText is required for append edits')
+    if (input.oldText || input.newText !== undefined) {
+      throw new Error('Use either appendToSection+appendText or oldText+newText, not both')
+    }
+    return appendToMarkdownSection(identity, input.file, before, input.appendToSection, input.appendText)
+  }
+  if (!input.oldText?.trim()) {
+    throw new Error('Field oldText is required; private continuity edits must patch existing scaffold text')
+  }
+  if (input.newText === undefined) {
+    throw new Error('Field newText is required for targeted private continuity edits')
+  }
+  return applyRequestedEdit(
+    input.file,
+    before,
+    input.oldText,
+    input.newText,
+    input.replaceAll ?? false,
+    false,
+  )
+}
+
+function appendToMarkdownSection(
+  identity: EthagentIdentity,
+  file: PrivateContinuityFile,
+  before: string,
+  section: string,
+  appendText: string,
+) {
+  const heading = normalizeSectionHeading(section)
+  let working = before
+  let repairedMissingSection = false
+  let lines = working.split(/\r?\n/)
+  let bounds = findMarkdownSectionBounds(lines, heading)
+  if (!bounds) {
+    const repaired = insertDefaultScaffoldSection(identity, file, before, heading)
+    if (!repaired) {
+      throw new Error(`section "${section}" was not found in ${file}; target an existing scaffold section`)
+    }
+    working = repaired
+    repairedMissingSection = true
+    lines = working.split(/\r?\n/)
+    bounds = findMarkdownSectionBounds(lines, heading)
+  }
+  if (!bounds) {
+    throw new Error(`section "${section}" was not found in ${file}; target an existing scaffold section`)
+  }
+  const { start, end: insertAt } = bounds
+  const prefix = lines.slice(0, insertAt).join('\n').replace(/\s+$/g, '')
+  const suffix = insertAt >= lines.length ? '' : lines.slice(insertAt).join('\n').replace(/^\s+/g, '')
+  const normalizedAppend = ensureTrailingNewline(appendText.trim())
+  const after = ensureTrailingNewline(suffix
+    ? `${prefix}\n${normalizedAppend}\n${suffix}`
+    : `${prefix}\n${normalizedAppend}`)
+  const afterLines = after.split(/\r?\n/)
+  const afterBounds = findMarkdownSectionBounds(afterLines, heading)
+  return {
+    before,
+    after,
+    summary: repairedMissingSection
+      ? `repair ${heading} section and append to ${heading} in ${file}`
+      : `append to ${heading} in ${file}`,
+    previewBefore: repairedMissingSection
+      ? `section "${heading}" was missing in ${file}; approval will add the scaffold section before appending.`
+      : previewText(sectionPreview(lines, start, insertAt)),
+    previewAfter: previewText(afterBounds
+      ? sectionPreview(afterLines, afterBounds.start, afterBounds.end)
+      : normalizedAppend),
+  }
+}
+
+function insertDefaultScaffoldSection(
+  identity: EthagentIdentity,
+  file: PrivateContinuityFile,
+  before: string,
+  heading: string,
+): string | null {
+  const defaults = defaultContinuityFiles(identity)[file]
+  const defaultSection = extractMarkdownSection(defaults, heading)
+  if (!defaultSection) return null
+
+  const defaultHeadings = markdownSectionHeadings(defaults)
+  const targetIndex = defaultHeadings.indexOf(heading)
+  if (targetIndex === -1) return null
+
+  const lines = before.split(/\r?\n/)
+  const followingHeadings = new Set(defaultHeadings.slice(targetIndex + 1))
+  const followingIndex = lines.findIndex(line => followingHeadings.has(normalizeSectionHeading(line)))
+  if (followingIndex !== -1) {
+    return insertSectionAtLine(before, followingIndex, defaultSection)
+  }
+
+  const previousHeadings = new Set(defaultHeadings.slice(0, targetIndex))
+  let insertAfterPrevious: number | null = null
+  for (let index = 0; index < lines.length; index += 1) {
+    if (!previousHeadings.has(normalizeSectionHeading(lines[index] ?? ''))) continue
+    const bounds = findMarkdownSectionBounds(lines, normalizeSectionHeading(lines[index] ?? ''))
+    if (bounds && bounds.end > (insertAfterPrevious ?? -1)) insertAfterPrevious = bounds.end
+  }
+  if (insertAfterPrevious !== null) {
+    return insertSectionAtLine(before, insertAfterPrevious, defaultSection)
+  }
+
+  const firstHeading = lines.findIndex(line => /^#\s+/.test(line.trim()))
+  return insertSectionAtLine(before, firstHeading === -1 ? 0 : firstHeading + 1, defaultSection)
+}
+
+function insertSectionAtLine(markdown: string, lineIndex: number, section: string): string {
+  const lines = markdown.split(/\r?\n/)
+  const before = lines.slice(0, lineIndex).join('\n').replace(/\s+$/g, '')
+  const after = lines.slice(lineIndex).join('\n').replace(/^\s+/g, '')
+  const block = section.trim()
+  if (!before) return ensureTrailingNewline(after ? `${block}\n\n${after}` : block)
+  return ensureTrailingNewline(after ? `${before}\n\n${block}\n\n${after}` : `${before}\n\n${block}`)
+}
+
+function extractMarkdownSection(markdown: string, heading: string): string | null {
+  const lines = markdown.split(/\r?\n/)
+  const bounds = findMarkdownSectionBounds(lines, heading)
+  if (!bounds) return null
+  return lines.slice(bounds.start, bounds.end).join('\n').trim()
+}
+
+function markdownSectionHeadings(markdown: string): string[] {
+  return markdown
+    .split(/\r?\n/)
+    .filter(line => /^##\s+/.test(line.trim()))
+    .map(normalizeSectionHeading)
+}
+
+function findMarkdownSectionBounds(lines: string[], heading: string): { start: number; end: number } | null {
+  const start = lines.findIndex(line => normalizeSectionHeading(line) === heading && /^#{1,6}\s+/.test(line.trim()))
+  if (start === -1) return null
+  const nextSection = lines.findIndex((line, index) => index > start && /^##\s+/.test(line.trim()))
+  return { start, end: nextSection === -1 ? lines.length : nextSection }
+}
+
+function normalizeSectionHeading(value: string): string {
+  return value.trim().replace(/^#+\s*/, '').trim()
+}
+
+function sectionPreview(lines: string[], start: number, end: number): string {
+  return lines.slice(start, Math.min(end, start + 8)).join('\n')
+}
+
+function markdownLines(value: string): string[] {
+  const lines = value.split(/\r?\n/)
+  if (lines[lines.length - 1] === '') lines.pop()
+  return lines
+}
+
+function ensureTrailingNewline(value: string): string {
+  return value.endsWith('\n') ? value : `${value}\n`
+}
+
+function previewText(text: string, max = 700): string {
+  if (text.length <= max) return text
+  return `${text.slice(0, max - 3)}...`
+}

package/src/identity/continuity/privateEdit/diff.ts

@@ -0,0 +1,82 @@
+import type { PrivateContinuityFile } from '../storage.js'
+
+export function renderPrivateContinuityDiff(file: PrivateContinuityFile, before: string, after: string): string {
+  if (before === after) return '(no changes)'
+  const changedLines = changedMarkdownLines(before, after)
+  const lines = [
+    `--- ${file}`,
+    `+++ ${file}`,
+    ...(changedLines.length > 0 ? changedLines : ['(only whitespace or line ending changes)']),
+  ]
+  const diff = lines.join('\n')
+  return diff.length <= 2400 ? diff : `${diff.slice(0, 2397)}...`
+}
+
+function changedMarkdownLines(before: string, after: string): string[] {
+  const beforeLines = markdownLines(before)
+  const afterLines = markdownLines(after)
+  const lengths = lcsLengths(beforeLines, afterLines)
+  const changed: string[] = []
+  let beforeIndex = 0
+  let afterIndex = 0
+
+  while (beforeIndex < beforeLines.length && afterIndex < afterLines.length) {
+    if (beforeLines[beforeIndex] === afterLines[afterIndex]) {
+      beforeIndex += 1
+      afterIndex += 1
+      continue
+    }
+
+    const deleteScore = lengths[beforeIndex + 1]![afterIndex]!
+    const insertScore = lengths[beforeIndex]![afterIndex + 1]!
+    const deleteRevealsMatch = beforeLines[beforeIndex + 1] === afterLines[afterIndex]
+    const insertRevealsMatch = beforeLines[beforeIndex] === afterLines[afterIndex + 1]
+
+    if (insertRevealsMatch && insertScore >= deleteScore) {
+      changed.push(`+${afterLines[afterIndex]}`)
+      afterIndex += 1
+    } else if (deleteRevealsMatch && deleteScore >= insertScore) {
+      changed.push(`-${beforeLines[beforeIndex]}`)
+      beforeIndex += 1
+    } else if (deleteScore >= insertScore) {
+      changed.push(`-${beforeLines[beforeIndex]}`)
+      beforeIndex += 1
+    } else {
+      changed.push(`+${afterLines[afterIndex]}`)
+      afterIndex += 1
+    }
+  }
+
+  while (beforeIndex < beforeLines.length) {
+    changed.push(`-${beforeLines[beforeIndex]}`)
+    beforeIndex += 1
+  }
+  while (afterIndex < afterLines.length) {
+    changed.push(`+${afterLines[afterIndex]}`)
+    afterIndex += 1
+  }
+
+  return changed
+}
+
+function lcsLengths(beforeLines: string[], afterLines: string[]): number[][] {
+  const lengths = Array.from(
+    { length: beforeLines.length + 1 },
+    () => Array<number>(afterLines.length + 1).fill(0),
+  )
+
+  for (let beforeIndex = beforeLines.length - 1; beforeIndex >= 0; beforeIndex -= 1) {
+    for (let afterIndex = afterLines.length - 1; afterIndex >= 0; afterIndex -= 1) {
+      lengths[beforeIndex]![afterIndex] = beforeLines[beforeIndex] === afterLines[afterIndex]
+        ? lengths[beforeIndex + 1]![afterIndex + 1]! + 1
+        : Math.max(lengths[beforeIndex + 1]![afterIndex]!, lengths[beforeIndex]![afterIndex + 1]!)
+    }
+  }
+
+  return lengths
+}
+
+function markdownLines(value: string): string[] {
+  const normalized = value.replace(/\r\n?/g, '\n')
+  return normalized.split('\n')
+}

package/src/identity/continuity/privateEdit/files.ts

@@ -0,0 +1,23 @@
+import fs from 'node:fs/promises'
+import { type EthagentIdentity } from '../../../storage/config.js'
+import { continuityVaultRef, defaultContinuityFiles, type PrivateContinuityFile } from '../storage.js'
+
+export function privateContinuityPath(identity: EthagentIdentity, file: PrivateContinuityFile): string {
+  const ref = continuityVaultRef(identity)
+  return file === 'SOUL.md' ? ref.soulPath : ref.memoryPath
+}
+
+export async function readPrivateContinuityFile(
+  identity: EthagentIdentity,
+  file: PrivateContinuityFile,
+  fullPath: string,
+): Promise<{ content: string; existedBefore: boolean }> {
+  try {
+    return { content: await fs.readFile(fullPath, 'utf8'), existedBefore: true }
+  } catch (err: unknown) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+      return { content: defaultContinuityFiles(identity)[file], existedBefore: false }
+    }
+    throw err
+  }
+}

package/src/identity/continuity/privateEdit/types.ts

@@ -0,0 +1,28 @@
+import type { EthagentIdentity } from '../../../storage/config.js'
+import type { PrivateContinuityFile } from '../storage.js'
+
+export type PrivateContinuityEditInput = {
+  file: PrivateContinuityFile
+  oldText?: string
+  newText?: string
+  appendToSection?: string
+  appendText?: string
+  replaceAll?: boolean
+  replaceWholeFile?: boolean
+}
+
+export type PreparedPrivateContinuityEdit = {
+  identity: EthagentIdentity
+  file: PrivateContinuityFile
+  fullPath: string
+  relativePath: string
+  directoryPath: string
+  existedBefore: boolean
+  previousContent: string
+  before: string
+  after: string
+  previewBefore: string
+  previewAfter: string
+  changeSummary: string
+  diff: string
+}