ethagent 3.3.4 → 4.0.0

package/src/cli/status.ts

@@ -0,0 +1,46 @@
+import { loadConfig, type EthagentIdentity } from '../storage/config.js'
+import { getIdentityStatus } from '../storage/identity.js'
+import { continuityWorkingTreeStatus } from '../identity/continuity/storage/status.js'
+import { listPublishedContinuitySnapshots } from '../identity/continuity/snapshots.js'
+import { changedContinuitySnapshotFiles } from '../identity/manager/continuity/state.js'
+
+function shortAddr(addr: string | undefined): string {
+  if (!addr) return ''
+  return addr.slice(0, 6) + '…' + addr.slice(-4)
+}
+
+function networkName(chainId: number | undefined): string | null {
+  if (chainId === 1) return 'mainnet'
+  if (chainId === 8453) return 'base'
+  return null
+}
+
+export async function runStatus(version: string): Promise<number> {
+  const config = await loadConfig().catch(() => null)
+  const status = await getIdentityStatus(config ?? undefined).catch(() => null)
+  if (!status?.address) {
+    process.stdout.write(`ethagent v${version} · no identity yet\n`)
+    return 0
+  }
+  const bits: string[] = [`ethagent v${version}`]
+  if (status.agentId) bits.push(`#${status.agentId}`)
+  const network = networkName(status.chainId)
+  if (network) bits.push(network)
+  bits.push(shortAddr(status.address))
+  const localChanges = config?.identity ? await localChangesSegment(config.identity) : null
+  if (localChanges) bits.push(localChanges)
+  process.stdout.write(bits.join(' · ') + '\n')
+  return 0
+}
+
+async function localChangesSegment(identity: EthagentIdentity): Promise<string | null> {
+  try {
+    const [latest] = await listPublishedContinuitySnapshots(identity, 1)
+    const status = await continuityWorkingTreeStatus(identity, latest)
+    if (status.publishState !== 'local-changes') return null
+    const files = changedContinuitySnapshotFiles(status)
+    return files.length > 0 ? `local-changes: ${files.join(', ')}` : 'local-changes'
+  } catch {
+    return null
+  }
+}

package/src/cli/sync.ts

@@ -0,0 +1,167 @@
+import { loadConfig, type EthagentIdentity } from '../storage/config.js'
+import { readContinuityFiles, statIfExists, writeContinuityFiles } from '../identity/continuity/storage/files.js'
+import { continuityVaultRef } from '../identity/continuity/storage/paths.js'
+import { continuityWorkingTreeStatus } from '../identity/continuity/storage/status.js'
+import { listPublishedContinuitySnapshots } from '../identity/continuity/snapshots.js'
+import { changedContinuitySnapshotFiles } from '../identity/manager/continuity/state.js'
+import { listSkills } from '../identity/continuity/skills/loadSkills.js'
+import { hashManagedBody, normalizeBody, reconstructVaultFile, sectionKey } from './syncAdapters/managedBlock.js'
+import { hookFilePath, readHookPayload, samePath } from './hookIo.js'
+import {
+  BUILT_IN_ADAPTERS,
+  type SyncAdapter,
+  type SyncContext,
+} from './syncAdapters/index.js'
+import type { PublicSkill } from './syncAdapters/shared.js'
+
+export type SyncOptions = { quiet?: boolean }
+
+export async function runSync(opts: SyncOptions = {}): Promise<number> {
+  const config = await loadConfig()
+  if (!config?.identity) return 0
+
+  let all: Awaited<ReturnType<typeof listSkills>>
+  try {
+    all = await listSkills(config.identity)
+  } catch (err) {
+    process.stderr.write(`ethagent: could not load skills, skipping sync to avoid removing managed files (${(err as Error).message})\n`)
+    return 1
+  }
+  const publicSkills: PublicSkill[] = all.filter(s => s.visibility === 'public')
+
+  const targets: SyncAdapter[] = []
+  for (const adapter of BUILT_IN_ADAPTERS) {
+    if (await adapter.detect().catch(() => false)) targets.push(adapter)
+  }
+  if (targets.length === 0) {
+    if (!opts.quiet) process.stdout.write('ethagent: no harness detected\n')
+    return 0
+  }
+
+  let context: SyncContext
+  let pulled: string[] = []
+  try {
+    const reconciled = await reconcileSoulMemory(config.identity, targets)
+    context = { soul: reconciled.soul, memory: reconciled.memory }
+    pulled = reconciled.pulled
+  } catch (err) {
+    process.stderr.write(`ethagent: could not reconcile soul/memory, skipping sync to avoid overwriting harness files (${(err as Error).message})\n`)
+    return 1
+  }
+
+  const summaries: string[] = []
+  for (const adapter of targets) {
+    try {
+      const { count, skipped } = await adapter.mirror(publicSkills, context)
+      let summary = `${adapter.name}: ${count} skill${count === 1 ? '' : 's'}`
+      if (skipped > 0) summary += `, skipped ${skipped} unmanaged`
+      summaries.push(summary)
+    } catch (err) {
+      summaries.push(`${adapter.name}: failed (${(err as Error).message})`)
+    }
+  }
+  if (!opts.quiet) {
+    process.stdout.write(`ethagent: synced -> ${summaries.join(' | ')}\n`)
+    if (pulled.length > 0) {
+      process.stdout.write(`ethagent: pulled ${pulled.join(', ')} drift from your harness into the vault\n`)
+    }
+  }
+  if (!opts.quiet) await reportLocalChanges(config.identity)
+  return 0
+}
+
+async function reportLocalChanges(identity: EthagentIdentity): Promise<void> {
+  try {
+    const [latest] = await listPublishedContinuitySnapshots(identity, 1)
+    const status = await continuityWorkingTreeStatus(identity, latest)
+    if (status.publishState !== 'local-changes') return
+    const files = changedContinuitySnapshotFiles(status)
+    const detail = files.length > 0 ? ` (${files.join(', ')})` : ''
+    process.stdout.write(`ethagent: local changes detected${detail}, run 'ethagent' and Save Snapshot to back up\n`)
+  } catch {}
+}
+
+export async function reconcileSoulMemory(
+  identity: EthagentIdentity,
+  adapters: SyncAdapter[],
+): Promise<SyncContext & { pulled: string[] }> {
+  const files = await readContinuityFiles(identity)
+  const ref = continuityVaultRef(identity)
+  const [soulStat, memoryStat] = await Promise.all([
+    statIfExists(ref.soulPath),
+    statIfExists(ref.memoryPath),
+  ])
+
+  const reads = await Promise.all(
+    adapters.map(adapter => (adapter.readManaged ? adapter.readManaged().catch(() => null) : Promise.resolve(null))),
+  )
+
+  const soulPick = soulStat
+    ? pickNewest(files['SOUL.md'], soulStat.mtimeMs, reads.map(r => ({ body: r?.soul ?? null, mtimeMs: r?.mtimeMs ?? 0, lastPushedHash: r?.lastSoulHash })), '# SOUL.md')
+    : { content: files['SOUL.md'], pulled: false }
+  const memoryPick = memoryStat
+    ? pickNewest(files['MEMORY.md'], memoryStat.mtimeMs, reads.map(r => ({ body: r?.memory ?? null, mtimeMs: r?.mtimeMs ?? 0, lastPushedHash: r?.lastMemoryHash })), '# MEMORY.md')
+    : { content: files['MEMORY.md'], pulled: false }
+
+  const pulled: string[] = []
+  if (soulPick.pulled) pulled.push('SOUL.md')
+  if (memoryPick.pulled) pulled.push('MEMORY.md')
+  if (pulled.length > 0) {
+    await writeContinuityFiles(identity, { 'SOUL.md': soulPick.content, 'MEMORY.md': memoryPick.content })
+  }
+  return { soul: soulPick.content, memory: memoryPick.content, pulled }
+}
+
+function pickNewest(
+  vaultContent: string,
+  vaultMtimeMs: number,
+  candidates: Array<{ body: string | null; mtimeMs: number; lastPushedHash?: string }>,
+  fallbackHeader: string,
+): { content: string; pulled: boolean } {
+  const vaultKey = sectionKey(vaultContent)
+  let winningBody: string | null = null
+  let winningMtime = vaultMtimeMs
+  for (const candidate of candidates) {
+    if (candidate.body === null) continue
+    if (normalizeBody(candidate.body) === vaultKey) continue
+    if (candidate.lastPushedHash && hashManagedBody(candidate.body) === candidate.lastPushedHash) continue
+    if (candidate.mtimeMs > winningMtime) {
+      winningMtime = candidate.mtimeMs
+      winningBody = candidate.body
+    }
+  }
+  if (winningBody === null) return { content: vaultContent, pulled: false }
+  return { content: reconstructVaultFile(vaultContent, winningBody, fallbackHeader), pulled: true }
+}
+
+export async function runSyncList(): Promise<number> {
+  for (const adapter of BUILT_IN_ADAPTERS) {
+    const detected = await adapter.detect().catch(() => false)
+    const mark = detected ? 'detected' : 'not detected'
+    process.stdout.write(`  ${adapter.name.padEnd(14)} ${mark.padEnd(13)} ${adapter.description}\n`)
+  }
+  return 0
+}
+
+export async function runSyncOnEdit(): Promise<number> {
+  const editedPath = await readEditedFilePathFromStdin()
+  if (!editedPath) return 0
+  const config = await loadConfig()
+  if (!config?.identity) return 0
+  if (!isManagedCorePath(config.identity, editedPath)) return 0
+  return runSync({ quiet: true })
+}
+
+export function isManagedCorePath(identity: EthagentIdentity, editedPath: string): boolean {
+  const managed: string[] = []
+  for (const adapter of BUILT_IN_ADAPTERS) {
+    if (adapter.managedFilePaths) managed.push(...adapter.managedFilePaths())
+  }
+  const ref = continuityVaultRef(identity)
+  managed.push(ref.soulPath, ref.memoryPath)
+  return managed.some(candidate => samePath(candidate, editedPath))
+}
+
+async function readEditedFilePathFromStdin(): Promise<string | null> {
+  return hookFilePath(await readHookPayload())
+}

package/src/cli/syncAdapters/claude-code.ts

@@ -0,0 +1,86 @@
+import fs from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { MANIFEST_FILE, mirrorAsSkillFolders, pathExists, readManifest, type PublicSkill } from './shared.js'
+import { injectManagedBlock, readManagedContext, renderManagedBlock, writeManagedSyncState } from './managedBlock.js'
+import type { ManagedRead, SyncContext } from './index.js'
+
+function claudeDir(): string {
+  return path.join(os.homedir(), '.claude')
+}
+
+function claudeSkillsDir(): string {
+  return path.join(claudeDir(), 'skills')
+}
+
+function claudeMdPath(): string {
+  return path.join(claudeDir(), 'CLAUDE.md')
+}
+
+function claudeProjectMemoryMdPath(): string {
+  const slug = process.cwd().replace(/[:\\\/]/g, '-')
+  return path.join(claudeDir(), 'projects', slug, 'memory', 'MEMORY.md')
+}
+
+// The Claude Code native per-project memory directory for the current project.
+// ethagent's portable memory supersedes this; the --memory-guard hook redirects
+// the model away from writing here so nothing siloes on one machine.
+export function claudeCodeNativeMemoryDir(): string {
+  return path.dirname(claudeProjectMemoryMdPath())
+}
+
+// Every project's mirrored MEMORY.md under a given ~/.claude root, across all
+// directories the agent has ever been synced in, not just the current cwd.
+// Reset uses this so no project is left whispering a stale ethagent block.
+export async function projectMemoryMirrorsUnder(claudeRoot: string): Promise<string[]> {
+  const projectsDir = path.join(claudeRoot, 'projects')
+  let slugs: string[]
+  try {
+    slugs = await fs.readdir(projectsDir)
+  } catch {
+    return []
+  }
+  const mirrors: string[] = []
+  for (const slug of slugs) {
+    const file = path.join(projectsDir, slug, 'memory', 'MEMORY.md')
+    if (await pathExists(file)) mirrors.push(file)
+  }
+  return mirrors
+}
+
+export const claudeCodeAdapter = {
+  name: 'claude-code' as const,
+  description: 'Mirror public skills into ~/.claude/skills and inject soul/memory into ~/.claude/CLAUDE.md and the project MEMORY.md.',
+  async detect(): Promise<boolean> {
+    return pathExists(claudeDir())
+  },
+  async readManaged(): Promise<ManagedRead | null> {
+    return readManagedContext(claudeMdPath())
+  },
+  managedFilePaths(): string[] {
+    return [claudeMdPath()]
+  },
+  async resetManagedFilePaths(): Promise<string[]> {
+    return [claudeMdPath(), ...(await projectMemoryMirrorsUnder(claudeDir()))]
+  },
+  async cleanup(): Promise<void> {
+    const skillsDir = claudeSkillsDir()
+    const manifest = await readManifest(skillsDir)
+    await Promise.all(
+      manifest.skills.map(name =>
+        fs.rm(path.join(skillsDir, name), { recursive: true, force: true }).catch(() => {})
+      )
+    )
+    await fs.rm(path.join(skillsDir, MANIFEST_FILE), { force: true }).catch(() => {})
+  },
+  async mirror(skills: PublicSkill[], context?: SyncContext): Promise<{ count: number; skipped: number }> {
+    const result = await mirrorAsSkillFolders(claudeSkillsDir(), skills)
+    if (context) {
+      for (const target of [claudeMdPath(), claudeProjectMemoryMdPath()]) {
+        await injectManagedBlock(target, renderManagedBlock(context))
+      }
+      await writeManagedSyncState(claudeMdPath(), context)
+    }
+    return result
+  },
+}

package/src/cli/syncAdapters/codex.ts

@@ -0,0 +1,66 @@
+import fs from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { parseSkillFile } from '../../identity/continuity/skills/frontmatter.js'
+import { pathExists, type PublicSkill } from './shared.js'
+import { injectManagedBlock, readManagedContext, renderManagedBlock, writeManagedSyncState } from './managedBlock.js'
+import type { ManagedRead, SyncContext } from './index.js'
+
+function codexDir(): string {
+  return path.join(os.homedir(), '.codex')
+}
+
+function agentsFilePath(): string {
+  return path.join(codexDir(), 'AGENTS.md')
+}
+
+type EnrichedSkill = PublicSkill & { body: string }
+
+async function enrichSkills(skills: PublicSkill[]): Promise<EnrichedSkill[]> {
+  const out: EnrichedSkill[] = []
+  for (const skill of skills) {
+    try {
+      const raw = await fs.readFile(skill.absolutePath, 'utf8')
+      const { body } = parseSkillFile(raw)
+      out.push({ ...skill, body })
+    } catch {}
+  }
+  return out
+}
+
+function neutralizeManagedMarkers(text: string): string {
+  return text.replace(/<!--\s*ethagent:/gi, '<!-- ethagent ')
+}
+
+function renderSkillsText(skills: EnrichedSkill[]): string {
+  if (skills.length === 0) return '_no public skills published yet._'
+  const lines: string[] = []
+  for (const skill of skills) {
+    lines.push(`## ${neutralizeManagedMarkers(skill.displayName ?? skill.name)}`, '')
+    if (skill.description) lines.push(neutralizeManagedMarkers(skill.description), '')
+    if (skill.body) lines.push(neutralizeManagedMarkers(skill.body), '')
+  }
+  return lines.join('\n').trim()
+}
+
+export const codexAdapter = {
+  name: 'codex' as const,
+  description: 'Merge soul, memory, and public skill content into ~/.codex/AGENTS.md between ethagent markers.',
+  async detect(): Promise<boolean> {
+    return pathExists(path.join(codexDir(), 'config.toml'))
+  },
+  async readManaged(): Promise<ManagedRead | null> {
+    return readManagedContext(agentsFilePath())
+  },
+  managedFilePaths(): string[] {
+    return [agentsFilePath()]
+  },
+  async mirror(skills: PublicSkill[], context?: SyncContext): Promise<{ count: number; skipped: number }> {
+    await fs.mkdir(codexDir(), { recursive: true })
+    const enriched = await enrichSkills(skills)
+    const block = renderManagedBlock(context, renderSkillsText(enriched))
+    await injectManagedBlock(agentsFilePath(), block)
+    if (context) await writeManagedSyncState(agentsFilePath(), context)
+    return { count: enriched.length, skipped: 0 }
+  },
+}

package/src/cli/syncAdapters/index.ts

@@ -0,0 +1,45 @@
+import fs from 'node:fs/promises'
+import type { PublicSkill } from './shared.js'
+import { claudeCodeAdapter } from './claude-code.js'
+import { codexAdapter } from './codex.js'
+import { removeManagedBlock } from './managedBlock.js'
+
+export type SyncContext = {
+  soul: string
+  memory: string
+}
+
+export type ManagedRead = {
+  soul: string | null
+  memory: string | null
+  mtimeMs: number
+  lastSoulHash?: string
+  lastMemoryHash?: string
+}
+
+export type SyncAdapter = {
+  name: string
+  description: string
+  detect: () => Promise<boolean>
+  readManaged?: () => Promise<ManagedRead | null>
+  managedFilePaths?: () => string[]
+  resetManagedFilePaths?: () => Promise<string[]>
+  cleanup?: () => Promise<void>
+  mirror: (skills: PublicSkill[], context?: SyncContext) => Promise<{ count: number; skipped: number }>
+}
+
+export const BUILT_IN_ADAPTERS: SyncAdapter[] = [claudeCodeAdapter, codexAdapter]
+
+export async function clearHarnessManagedBlocks(): Promise<string[]> {
+  const cleared: string[] = []
+  for (const adapter of BUILT_IN_ADAPTERS) {
+    const paths = adapter.resetManagedFilePaths
+      ? await adapter.resetManagedFilePaths().catch(() => [])
+      : (adapter.managedFilePaths?.() ?? [])
+    for (const filePath of paths) {
+      if (await removeManagedBlock(filePath).catch(() => false)) cleared.push(filePath)
+    }
+    await adapter.cleanup?.().catch(() => {})
+  }
+  return cleared
+}

package/src/cli/syncAdapters/managedBlock.ts

@@ -0,0 +1,175 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { createHash } from 'node:crypto'
+import { ensureTrailingNewline } from '../../identity/continuity/storage/files.js'
+import { normalizeSnapshotContent } from '../../identity/continuity/storage/status.js'
+import type { ManagedRead, SyncContext } from './index.js'
+
+const SYNC_STATE_FILE = '.ethagent-sync.json'
+
+export const START = '<!-- ethagent:start -->'
+export const END = '<!-- ethagent:end -->'
+const MANAGED_NOTE = '<!-- managed by ethagent; edits between these markers are pulled into your vault on `ethagent --sync`. -->'
+const SOUL_START = '<!-- ethagent:soul:start -->'
+const SOUL_END = '<!-- ethagent:soul:end -->'
+const MEMORY_START = '<!-- ethagent:memory:start -->'
+const MEMORY_END = '<!-- ethagent:memory:end -->'
+
+function stripFirstHeader(value: string): string {
+  return value.replace(/^#[^\n]*\n/, '')
+}
+
+export function sectionKey(fileContent: string): string {
+  return normalizeSnapshotContent(stripFirstHeader(fileContent).trim())
+}
+
+export function normalizeBody(body: string): string {
+  return normalizeSnapshotContent(body.trim())
+}
+
+export function renderManagedBlock(context: SyncContext | undefined, extra?: string): string {
+  const lines: string[] = [START, MANAGED_NOTE, '']
+  if (context) {
+    const soul = stripFirstHeader(context.soul).trim()
+    lines.push(SOUL_START)
+    if (soul) lines.push(soul)
+    lines.push(SOUL_END, '')
+    const memory = stripFirstHeader(context.memory).trim()
+    lines.push(MEMORY_START)
+    if (memory) lines.push(memory)
+    lines.push(MEMORY_END, '')
+  }
+  const tail = extra?.trim()
+  if (tail) lines.push(tail, '')
+  lines.push(END)
+  return lines.join('\n')
+}
+
+export async function injectManagedBlock(filePath: string, block: string): Promise<void> {
+  await fs.mkdir(path.dirname(filePath), { recursive: true })
+  let existing = ''
+  try { existing = await fs.readFile(filePath, 'utf8') } catch {}
+
+  let next: string
+  const startIdx = existing.indexOf(START)
+  const endIdx = existing.indexOf(END)
+  if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+    const before = existing.slice(0, startIdx).replace(/\n+$/, '')
+    const after = existing.slice(endIdx + END.length).replace(/^\n+/, '')
+    const parts: string[] = []
+    if (before) parts.push(before, '')
+    parts.push(block)
+    if (after) parts.push('', after)
+    next = parts.join('\n').replace(/\n{3,}/g, '\n\n') + (existing.endsWith('\n') ? '\n' : '')
+  } else {
+    next = existing
+      ? `${existing.replace(/\n+$/, '')}\n\n${block}\n`
+      : `${block}\n`
+  }
+
+  await fs.writeFile(filePath, next, 'utf8')
+}
+
+export async function removeManagedBlock(filePath: string): Promise<boolean> {
+  let existing: string
+  try { existing = await fs.readFile(filePath, 'utf8') } catch { return false }
+
+  const startIdx = existing.indexOf(START)
+  const endIdx = existing.indexOf(END)
+  if (startIdx === -1 || endIdx === -1 || endIdx <= startIdx) return false
+
+  const before = existing.slice(0, startIdx).replace(/\n+$/, '')
+  const after = existing.slice(endIdx + END.length).replace(/^\n+/, '')
+  const remainder = [before, after].filter(Boolean).join('\n\n')
+
+  if (remainder.trim() === '') {
+    await fs.rm(filePath, { force: true })
+  } else {
+    await fs.writeFile(filePath, `${remainder}\n`, 'utf8')
+  }
+  await fs.rm(syncStatePath(filePath), { force: true })
+  return true
+}
+
+export function extractOutsideManaged(fileContent: string): string {
+  const startIdx = fileContent.indexOf(START)
+  const endIdx = fileContent.indexOf(END)
+  if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+    const before = fileContent.slice(0, startIdx).replace(/\n+$/, '')
+    const after = fileContent.slice(endIdx + END.length).replace(/^\n+/, '')
+    return [before, after].filter(Boolean).join('\n\n').trim()
+  }
+  return fileContent.trim()
+}
+
+function extractBetween(text: string, start: string, end: string): string | null {
+  const startIdx = text.indexOf(start)
+  if (startIdx === -1) return null
+  const endIdx = text.indexOf(end, startIdx + start.length)
+  if (endIdx === -1) return null
+  return text.slice(startIdx + start.length, endIdx).trim()
+}
+
+export function parseManagedContext(fileContent: string): { soul: string | null; memory: string | null } {
+  return {
+    soul: extractBetween(fileContent, SOUL_START, SOUL_END),
+    memory: extractBetween(fileContent, MEMORY_START, MEMORY_END),
+  }
+}
+
+export async function readManagedContext(filePath: string): Promise<ManagedRead | null> {
+  let content: string
+  let mtimeMs: number
+  try {
+    content = await fs.readFile(filePath, 'utf8')
+    mtimeMs = (await fs.stat(filePath)).mtimeMs
+  } catch {
+    return null
+  }
+  const { soul, memory } = parseManagedContext(content)
+  const { soulHash, memoryHash } = await readManagedSyncState(filePath)
+  return {
+    soul,
+    memory,
+    mtimeMs,
+    ...(soulHash ? { lastSoulHash: soulHash } : {}),
+    ...(memoryHash ? { lastMemoryHash: memoryHash } : {}),
+  }
+}
+
+export function hashManagedBody(body: string): string {
+  return createHash('sha256').update(normalizeBody(body).replace(/\n{3,}/g, '\n\n'), 'utf8').digest('hex')
+}
+
+function syncStatePath(managedFilePath: string): string {
+  return path.join(path.dirname(managedFilePath), SYNC_STATE_FILE)
+}
+
+export async function writeManagedSyncState(managedFilePath: string, context: SyncContext): Promise<void> {
+  const state = {
+    soulHash: hashManagedBody(stripFirstHeader(context.soul)),
+    memoryHash: hashManagedBody(stripFirstHeader(context.memory)),
+  }
+  try {
+    await fs.writeFile(syncStatePath(managedFilePath), `${JSON.stringify(state)}\n`, 'utf8')
+  } catch {
+  }
+}
+
+async function readManagedSyncState(managedFilePath: string): Promise<{ soulHash?: string; memoryHash?: string }> {
+  try {
+    const parsed = JSON.parse(await fs.readFile(syncStatePath(managedFilePath), 'utf8')) as Record<string, unknown>
+    return {
+      soulHash: typeof parsed.soulHash === 'string' ? parsed.soulHash : undefined,
+      memoryHash: typeof parsed.memoryHash === 'string' ? parsed.memoryHash : undefined,
+    }
+  } catch {
+    return {}
+  }
+}
+
+export function reconstructVaultFile(currentVaultContent: string, newBody: string, fallbackHeader: string): string {
+  const headerMatch = currentVaultContent.match(/^#[^\n]*\n/)
+  const header = headerMatch ? headerMatch[0] : `${fallbackHeader}\n`
+  return ensureTrailingNewline(`${header}\n${newBody.trim()}\n`)
+}

package/src/cli/syncAdapters/shared.ts

@@ -0,0 +1,63 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import type { SkillIndexEntry } from '../../identity/continuity/skills/types.js'
+
+export type PublicSkill = SkillIndexEntry
+
+export const MANIFEST_FILE = '.ethagent-managed.json'
+
+export type Manifest = {
+  version: 1
+  managedAt: string
+  skills: string[]
+}
+
+export async function readManifest(root: string): Promise<Manifest> {
+  try {
+    const raw = await fs.readFile(path.join(root, MANIFEST_FILE), 'utf8')
+    const parsed = JSON.parse(raw) as Manifest
+    if (parsed.version === 1 && Array.isArray(parsed.skills)) return parsed
+  } catch {}
+  return { version: 1, managedAt: new Date(0).toISOString(), skills: [] }
+}
+
+export async function writeManifest(root: string, owned: string[]): Promise<void> {
+  const next: Manifest = { version: 1, managedAt: new Date().toISOString(), skills: owned }
+  await fs.writeFile(path.join(root, MANIFEST_FILE), JSON.stringify(next, null, 2) + '\n', 'utf8')
+}
+
+export async function pathExists(file: string): Promise<boolean> {
+  try { await fs.access(file); return true } catch { return false }
+}
+
+export async function mirrorAsSkillFolders(
+  root: string,
+  skills: PublicSkill[],
+): Promise<{ count: number; skipped: number }> {
+  await fs.mkdir(root, { recursive: true })
+  const manifest = await readManifest(root)
+  const incoming = new Set(skills.map(s => s.name))
+  const owned: string[] = []
+  let skipped = 0
+  for (const skill of skills) {
+    const targetDir = path.join(root, skill.name)
+    const targetFile = path.join(targetDir, 'SKILL.md')
+    const exists = await pathExists(targetDir)
+    const isOurs = manifest.skills.includes(skill.name)
+    if (exists && !isOurs) { skipped++; continue }
+    try {
+      const body = await fs.readFile(skill.absolutePath, 'utf8')
+      await fs.mkdir(targetDir, { recursive: true })
+      await fs.writeFile(targetFile, body, 'utf8')
+      owned.push(skill.name)
+    } catch {}
+  }
+  const keep = new Set<string>(owned)
+  for (const name of manifest.skills) if (incoming.has(name)) keep.add(name)
+  for (const stale of manifest.skills) {
+    if (keep.has(stale)) continue
+    await fs.rm(path.join(root, stale), { recursive: true, force: true }).catch(() => null)
+  }
+  await writeManifest(root, [...keep])
+  return { count: owned.length, skipped }
+}