ethagent 0.2.1 → 1.0.0

package/src/identity/continuity/snapshots.ts

@@ -0,0 +1,183 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import type { EthagentIdentity } from '../../storage/config.js'
+import { atomicWriteText } from '../../storage/atomicWrite.js'
+import {
+  continuityVaultRef,
+  ensureContinuityVault,
+  localContinuitySnapshotContentHashes,
+  type ContinuitySnapshotContentHashes,
+} from './storage.js'
+
+export type PublishedContinuitySnapshot = {
+  version: 1
+  id: string
+  createdAt: string
+  cid: string
+  metadataCid?: string
+  agentUri?: string
+  txHash?: string
+  publicSkillsCid?: string
+  agentCardCid?: string
+  contentHashes?: ContinuitySnapshotContentHashes
+  label: string
+  identity: {
+    address: string
+    ownerAddress?: string
+    chainId?: number
+    identityRegistryAddress?: string
+    agentId?: string
+  }
+}
+
+export type RecordPublishedContinuitySnapshotInput = {
+  identity: EthagentIdentity
+  label?: string
+}
+
+export function publishedContinuitySnapshotsPath(identity: EthagentIdentity): string {
+  return path.join(continuityVaultRef(identity).dir, '.published-snapshots.jsonl')
+}
+
+export async function recordPublishedContinuitySnapshot(
+  input: RecordPublishedContinuitySnapshotInput,
+): Promise<PublishedContinuitySnapshot | null> {
+  const backup = input.identity.backup
+  if (!backup?.cid) return null
+  await ensureContinuityVault(input.identity)
+  const createdAt = backup.createdAt ?? new Date().toISOString()
+  const contentHashes = await localContinuitySnapshotContentHashes(input.identity).catch(() => undefined)
+  const snapshot: PublishedContinuitySnapshot = {
+    version: 1,
+    id: `${createdAt}:${backup.cid}`.replaceAll('\\', '/'),
+    createdAt,
+    cid: backup.cid,
+    ...(backup.metadataCid ? { metadataCid: backup.metadataCid } : {}),
+    ...(backup.agentUri ? { agentUri: backup.agentUri } : {}),
+    ...(backup.txHash ? { txHash: backup.txHash } : {}),
+    ...(input.identity.publicSkills?.cid ? { publicSkillsCid: input.identity.publicSkills.cid } : {}),
+    ...(input.identity.publicSkills?.agentCardCid ? { agentCardCid: input.identity.publicSkills.agentCardCid } : {}),
+    ...(contentHashes ? { contentHashes } : {}),
+    label: input.label ?? 'published encrypted snapshot',
+    identity: {
+      address: input.identity.address,
+      ...(input.identity.ownerAddress ? { ownerAddress: input.identity.ownerAddress } : {}),
+      ...(input.identity.chainId ? { chainId: input.identity.chainId } : {}),
+      ...(input.identity.identityRegistryAddress ? { identityRegistryAddress: input.identity.identityRegistryAddress } : {}),
+      ...(input.identity.agentId ? { agentId: input.identity.agentId } : {}),
+    },
+  }
+
+  const existing = await readPublishedContinuitySnapshotFile(input.identity)
+  if (existing.some(item => item.cid === snapshot.cid)) return snapshot
+  await fs.appendFile(publishedContinuitySnapshotsPath(input.identity), `${JSON.stringify(snapshot)}\n`, {
+    encoding: 'utf8',
+    mode: 0o600,
+  })
+  return snapshot
+}
+
+export async function updatePublishedContinuitySnapshotContentHashes(
+  identity: EthagentIdentity,
+  cid: string,
+  contentHashes: ContinuitySnapshotContentHashes,
+): Promise<void> {
+  await ensureContinuityVault(identity)
+  const current = currentPublishedSnapshot(identity)
+  const snapshots = await readPublishedContinuitySnapshotFile(identity)
+  const index = snapshots.findIndex(item => item.cid === cid)
+  if (index === -1) {
+    const base = current.find(item => item.cid === cid)
+    if (!base) throw new Error('published snapshot was not found')
+    snapshots.push({ ...base, contentHashes })
+  } else {
+    snapshots[index] = { ...snapshots[index]!, contentHashes }
+  }
+  await atomicWriteText(
+    publishedContinuitySnapshotsPath(identity),
+    snapshots.map(snapshot => JSON.stringify(snapshot)).join('\n') + '\n',
+    { mode: 0o600 },
+  )
+}
+
+export async function listPublishedContinuitySnapshots(
+  identity: EthagentIdentity,
+  limit = 30,
+): Promise<PublishedContinuitySnapshot[]> {
+  const snapshots = await readPublishedContinuitySnapshotFile(identity)
+
+  for (const current of currentPublishedSnapshot(identity)) {
+    const index = snapshots.findIndex(item => item.cid === current.cid)
+    if (index === -1) {
+      snapshots.push(current)
+    } else {
+      snapshots[index] = enrichPublishedSnapshot(snapshots[index]!, current)
+    }
+  }
+
+  return snapshots
+    .sort((a, b) => b.createdAt.localeCompare(a.createdAt))
+    .slice(0, limit)
+}
+
+function enrichPublishedSnapshot(
+  snapshot: PublishedContinuitySnapshot,
+  current: PublishedContinuitySnapshot,
+): PublishedContinuitySnapshot {
+  return {
+    ...snapshot,
+    ...(snapshot.metadataCid ? {} : current.metadataCid ? { metadataCid: current.metadataCid } : {}),
+    ...(snapshot.agentUri ? {} : current.agentUri ? { agentUri: current.agentUri } : {}),
+    ...(snapshot.txHash ? {} : current.txHash ? { txHash: current.txHash } : {}),
+    ...(snapshot.publicSkillsCid ? {} : current.publicSkillsCid ? { publicSkillsCid: current.publicSkillsCid } : {}),
+    ...(snapshot.agentCardCid ? {} : current.agentCardCid ? { agentCardCid: current.agentCardCid } : {}),
+    ...(snapshot.contentHashes ? {} : current.contentHashes ? { contentHashes: current.contentHashes } : {}),
+  }
+}
+
+async function readPublishedContinuitySnapshotFile(identity: EthagentIdentity): Promise<PublishedContinuitySnapshot[]> {
+  let raw: string
+  try {
+    raw = await fs.readFile(publishedContinuitySnapshotsPath(identity), 'utf8')
+  } catch (error: unknown) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return []
+    throw error
+  }
+
+  const snapshots: PublishedContinuitySnapshot[] = []
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim()
+    if (!trimmed) continue
+    try {
+      snapshots.push(JSON.parse(trimmed) as PublishedContinuitySnapshot)
+    } catch {
+      continue
+    }
+  }
+  return snapshots
+}
+
+function currentPublishedSnapshot(identity: EthagentIdentity): PublishedContinuitySnapshot[] {
+  const backup = identity.backup
+  if (!backup?.cid) return []
+  const createdAt = backup.createdAt ?? identity.createdAt ?? new Date(0).toISOString()
+  return [{
+    version: 1,
+    id: `${createdAt}:${backup.cid}`.replaceAll('\\', '/'),
+    createdAt,
+    cid: backup.cid,
+    ...(backup.metadataCid ? { metadataCid: backup.metadataCid } : {}),
+    ...(backup.agentUri ? { agentUri: backup.agentUri } : {}),
+    ...(backup.txHash ? { txHash: backup.txHash } : {}),
+    ...(identity.publicSkills?.cid ? { publicSkillsCid: identity.publicSkills.cid } : {}),
+    ...(identity.publicSkills?.agentCardCid ? { agentCardCid: identity.publicSkills.agentCardCid } : {}),
+    label: 'current published snapshot',
+    identity: {
+      address: identity.address,
+      ...(identity.ownerAddress ? { ownerAddress: identity.ownerAddress } : {}),
+      ...(identity.chainId ? { chainId: identity.chainId } : {}),
+      ...(identity.identityRegistryAddress ? { identityRegistryAddress: identity.identityRegistryAddress } : {}),
+      ...(identity.agentId ? { agentId: identity.agentId } : {}),
+    },
+  }]
+}

package/src/identity/continuity/storage.ts

@@ -0,0 +1,507 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { createHash } from 'node:crypto'
+import { getConfigDir, type EthagentIdentity } from '../../storage/config.js'
+import { atomicWriteText } from '../../storage/atomicWrite.js'
+import type { ContinuityAgentSnapshot, ContinuityFiles } from './envelope.js'
+import { defaultPublicSkillsProfile, renderPublicSkillsJson } from './publicSkills.js'
+
+export const PRIVATE_CONTINUITY_FILES = ['SOUL.md', 'MEMORY.md'] as const
+export type PrivateContinuityFile = (typeof PRIVATE_CONTINUITY_FILES)[number]
+
+export type ContinuityVaultRef = {
+  dir: string
+  soulPath: string
+  memoryPath: string
+  publicSkillsPath: string
+}
+
+export type IdentityMarkdownScaffold = ContinuityFiles & {
+  'skills.json': string
+}
+
+export type ContinuitySnapshotFile = PrivateContinuityFile | 'skills.json'
+export type ContinuitySnapshotContentHashes = Record<ContinuitySnapshotFile, string>
+export type ContinuityPublishState = 'not-restored' | 'not-published' | 'verify-needed' | 'local-changes' | 'published'
+export type ContinuityWorkingTreeStatus = {
+  ready: boolean
+  newestLocalChangeAt?: string
+  localChangedAfterBackup: boolean
+  publishState: ContinuityPublishState
+  localContentHashes?: ContinuitySnapshotContentHashes
+  publishedContentHashes?: ContinuitySnapshotContentHashes
+}
+
+export function continuityVaultRef(identity: Pick<EthagentIdentity, 'chainId' | 'identityRegistryAddress' | 'agentId' | 'address'>): ContinuityVaultRef {
+  const dir = path.join(getConfigDir(), 'continuity', continuityVaultId(identity))
+  return {
+    dir,
+    soulPath: path.join(dir, 'SOUL.md'),
+    memoryPath: path.join(dir, 'MEMORY.md'),
+    publicSkillsPath: path.join(dir, 'skills.json'),
+  }
+}
+
+export async function ensureContinuityVault(identity: EthagentIdentity): Promise<ContinuityVaultRef> {
+  const ref = continuityVaultRef(identity)
+  await fs.mkdir(ref.dir, { recursive: true, mode: 0o700 })
+  return ref
+}
+
+export async function ensureContinuityFiles(identity: EthagentIdentity): Promise<ContinuityFiles> {
+  const ref = await ensureContinuityVault(identity)
+  const defaults = defaultContinuityFiles(identity)
+  await writeMissingPrivateFile(ref.soulPath, defaults['SOUL.md'])
+  await writeMissingPrivateFile(ref.memoryPath, defaults['MEMORY.md'])
+  return readContinuityFiles(identity)
+}
+
+export async function readContinuityFiles(identity: EthagentIdentity): Promise<ContinuityFiles> {
+  const ref = await ensureContinuityVault(identity)
+  const defaults = defaultContinuityFiles(identity)
+  return {
+    'SOUL.md': await readOrDefault(ref.soulPath, defaults['SOUL.md']),
+    'MEMORY.md': await readOrDefault(ref.memoryPath, defaults['MEMORY.md']),
+  }
+}
+
+export async function writeContinuityFiles(identity: EthagentIdentity, files: ContinuityFiles): Promise<ContinuityVaultRef> {
+  const ref = await ensureContinuityVault(identity)
+  await atomicWriteText(ref.soulPath, ensureTrailingNewline(files['SOUL.md']), { mode: 0o600 })
+  await atomicWriteText(ref.memoryPath, ensureTrailingNewline(files['MEMORY.md']), { mode: 0o600 })
+  return ref
+}
+
+export async function ensureIdentityMarkdownScaffold(
+  identity: EthagentIdentity,
+  options: { publicSkillsFallback?: string | (() => Promise<string>) } = {},
+): Promise<IdentityMarkdownScaffold> {
+  const privateFiles = await ensureContinuityFiles(identity)
+  const publicSkills = await ensurePublicSkillsFile(identity, { fallback: options.publicSkillsFallback })
+  return {
+    ...privateFiles,
+    'skills.json': publicSkills,
+  }
+}
+
+export async function writeIdentityMarkdownScaffold(
+  identity: EthagentIdentity,
+  files: IdentityMarkdownScaffold,
+): Promise<ContinuityVaultRef> {
+  const ref = await writeContinuityFiles(identity, {
+    'SOUL.md': files['SOUL.md'],
+    'MEMORY.md': files['MEMORY.md'],
+  })
+  await writePublicSkillsFile(identity, files['skills.json'])
+  return ref
+}
+
+export async function syncIdentityMarkdownScaffold(identity: EthagentIdentity): Promise<IdentityMarkdownScaffold> {
+  const next = await prepareSyncedIdentityMarkdownScaffold(identity)
+  await writeIdentityMarkdownScaffold(identity, next)
+  return next
+}
+
+export async function prepareSyncedIdentityMarkdownScaffold(identity: EthagentIdentity): Promise<IdentityMarkdownScaffold> {
+  await ensureIdentityMarkdownScaffold(identity)
+  const privateFiles = await readContinuityFiles(identity)
+  const publicSkills = await readPublicSkillsFile(identity)
+  const privateDefaults = defaultContinuityFiles(identity)
+  const publicDefault = defaultPublicSkillsJson(identity)
+  return {
+    'SOUL.md': syncGeneratedMarkdown(privateFiles['SOUL.md'], privateDefaults['SOUL.md'], [
+      { marker: 'identity', legacyHeading: 'Identity' },
+    ]),
+    'MEMORY.md': syncGeneratedMarkdown(privateFiles['MEMORY.md'], privateDefaults['MEMORY.md'], [
+      { marker: 'identity' },
+    ]),
+    'skills.json': syncSkillsJson(publicSkills, publicDefault),
+  }
+}
+
+export async function prepareSyncedPublicSkillsJson(identity: EthagentIdentity): Promise<string> {
+  await ensurePublicSkillsFile(identity)
+  const publicSkills = await readPublicSkillsFile(identity)
+  return syncSkillsJson(publicSkills, defaultPublicSkillsJson(identity))
+}
+
+function syncSkillsJson(existing: string, fresh: string): string {
+  try {
+    const existingParsed = JSON.parse(existing)
+    const freshParsed = JSON.parse(fresh)
+    const merged = {
+      ...existingParsed,
+      ...freshParsed,
+      skills: existingParsed.skills || freshParsed.skills,
+      inputModes: existingParsed.inputModes || freshParsed.inputModes,
+      outputModes: existingParsed.outputModes || freshParsed.outputModes,
+    }
+    return `${JSON.stringify(merged, null, 2)}\n`
+  } catch {
+    return fresh
+  }
+}
+
+export async function ensurePublicSkillsFile(
+  identity: EthagentIdentity,
+  options: { fallback?: string | (() => Promise<string>) } = {},
+): Promise<string> {
+  const ref = await ensureContinuityVault(identity)
+  if (await exists(ref.publicSkillsPath)) return readPublicSkillsFile(identity)
+
+
+  const fallback = await resolvePublicSkillsFallback(identity, options.fallback)
+  await atomicWriteText(ref.publicSkillsPath, ensureTrailingNewline(fallback), { mode: 0o644 })
+  return readPublicSkillsFile(identity)
+}
+
+export async function readPublicSkillsFile(identity: EthagentIdentity): Promise<string> {
+  const ref = await ensureContinuityVault(identity)
+  return readOrDefault(ref.publicSkillsPath, defaultPublicSkillsJson(identity))
+}
+
+export async function writePublicSkillsFile(identity: EthagentIdentity, content: string): Promise<ContinuityVaultRef> {
+  const ref = await ensureContinuityVault(identity)
+  await atomicWriteText(ref.publicSkillsPath, ensureTrailingNewline(content), { mode: 0o644 })
+  return ref
+}
+
+export async function continuityVaultStatus(identity: EthagentIdentity): Promise<{ ready: boolean; files: ContinuityVaultRef }> {
+  const ref = continuityVaultRef(identity)
+  const [soul, memory] = await Promise.all([exists(ref.soulPath), exists(ref.memoryPath)])
+  return { ready: soul && memory, files: ref }
+}
+
+export async function continuityWorkingTreeStatus(
+  identity: EthagentIdentity,
+  publishedSnapshot?: { contentHashes?: ContinuitySnapshotContentHashes },
+): Promise<ContinuityWorkingTreeStatus> {
+  const ref = continuityVaultRef(identity)
+  const stats = await Promise.all([
+    statIfExists(ref.soulPath),
+    statIfExists(ref.memoryPath),
+    statIfExists(ref.publicSkillsPath),
+  ])
+  const newestMs = Math.max(0, ...stats.flatMap(stat => stat ? [stat.mtimeMs] : []))
+  const ready = Boolean(stats[0] && stats[1])
+  const localContentHashes = ready
+    ? await localContinuitySnapshotContentHashes(identity).catch(() => undefined)
+    : undefined
+  const publishedContentHashes = publishedSnapshot?.contentHashes
+  const publishState: ContinuityPublishState = !ready
+    ? 'not-restored'
+    : !identity.backup?.cid
+      ? 'not-published'
+      : !localContentHashes || !publishedContentHashes
+        ? 'verify-needed'
+        : equalContinuitySnapshotHashes(localContentHashes, publishedContentHashes)
+          ? 'published'
+          : 'local-changes'
+
+  return {
+    ready,
+    ...(newestMs > 0 ? { newestLocalChangeAt: new Date(newestMs).toISOString() } : {}),
+    localChangedAfterBackup: publishState === 'local-changes',
+    publishState,
+    ...(localContentHashes ? { localContentHashes } : {}),
+    ...(publishedContentHashes ? { publishedContentHashes } : {}),
+  }
+}
+
+export async function localContinuitySnapshotContentHashes(
+  identity: EthagentIdentity,
+): Promise<ContinuitySnapshotContentHashes> {
+  const privateFiles = await readContinuityFiles(identity)
+  const publicSkills = await readPublicSkillsFile(identity)
+  return continuitySnapshotContentHashes(privateFiles, publicSkills)
+}
+
+export function continuitySnapshotContentHashes(
+  privateFiles: ContinuityFiles,
+  publicSkills: string,
+): ContinuitySnapshotContentHashes {
+  return {
+    'SOUL.md': hashContinuitySnapshotContent(privateFiles['SOUL.md']),
+    'MEMORY.md': hashContinuitySnapshotContent(privateFiles['MEMORY.md']),
+    'skills.json': hashContinuitySnapshotContent(publicSkills),
+  }
+}
+
+export function equalContinuitySnapshotHashes(
+  a: ContinuitySnapshotContentHashes,
+  b: ContinuitySnapshotContentHashes,
+): boolean {
+  return a['SOUL.md'] === b['SOUL.md']
+    && a['MEMORY.md'] === b['MEMORY.md']
+    && a['skills.json'] === b['skills.json']
+}
+
+function hashContinuitySnapshotContent(value: string): string {
+  return createHash('sha256').update(normalizeSnapshotContent(value), 'utf8').digest('hex')
+}
+
+function normalizeSnapshotContent(value: string): string {
+  const normalized = value.replace(/\r\n?/g, '\n')
+  return normalized.endsWith('\n') ? normalized : `${normalized}\n`
+}
+
+export function continuityAgentSnapshot(identity: EthagentIdentity): ContinuityAgentSnapshot {
+  const state = identity.state ?? {}
+  return {
+    ...(identity.chainId ? { chainId: identity.chainId } : {}),
+    ...(identity.identityRegistryAddress ? { identityRegistryAddress: identity.identityRegistryAddress } : {}),
+    ...(identity.agentId ? { agentId: identity.agentId } : {}),
+    ...(identity.agentUri ? { agentUri: identity.agentUri } : {}),
+    ...(identity.metadataCid ? { metadataCid: identity.metadataCid } : {}),
+    ...(typeof state.name === 'string' ? { name: state.name } : {}),
+    ...(typeof state.description === 'string' ? { description: state.description } : {}),
+  }
+}
+
+export function defaultContinuityFiles(identity: EthagentIdentity, now = new Date()): ContinuityFiles {
+  const owner = identity.ownerAddress ?? identity.address
+  const created = now.toISOString().slice(0, 10)
+  const identityBlock = renderPrivateIdentityBlock({
+    owner,
+    token: identity.agentId ? `#${identity.agentId}` : 'pending registration',
+    chainId: identity.chainId ? identity.chainId.toString() : 'unknown',
+    registry: identity.identityRegistryAddress ?? 'unknown',
+  })
+  return {
+    'SOUL.md': [
+      '# SOUL.md',
+      '',
+      identityBlock,
+      '',
+      '## Persona',
+      '',
+      '- Describe the private agent persona, voice, and collaboration style.',
+      '- Keep standing behavior that should survive model switches and device restores.',
+      '- Prefer stable guidance over session-specific preferences.',
+      '',
+      '## Operating Principles',
+      '',
+      '- Record durable values, decision preferences, and owner-approved working principles.',
+      '- Keep implementation-specific facts in MEMORY.md unless they define behavior.',
+      '',
+      '## Private Instructions',
+      '',
+      '- Keep owner-specific standing instructions in this file.',
+      '- Do not publish this file directly; use encrypted snapshot backup from Identity Hub.',
+      '- Public capabilities belong in skills.json.',
+      '',
+      '## Boundaries',
+      '',
+      '- Record private behavioral limits and owner-approved constraints here.',
+      '- Do not store seed phrases, private keys, raw wallet signatures, or API keys.',
+      '- Do not place public delegation claims here; keep them in skills.json.',
+      '',
+      '## Maintenance Rules',
+      '',
+      '- Keep the generated Agent Identity block intact; edit owner-authored sections below it.',
+      '- Do not duplicate the mutable public agent name here; it lives in token metadata and the Agent Card.',
+      '- Move factual project memory to MEMORY.md when it is not persona or instruction material.',
+      '- Revise or remove stale guidance instead of accumulating contradictions.',
+      '',
+      '## Change Notes',
+      '',
+      '- Add dated notes when the persona or long-lived private guidance changes.',
+      '',
+      `Created: ${created}`,
+    ].join('\n') + '\n',
+    'MEMORY.md': [
+      '# MEMORY.md',
+      '',
+      identityBlock,
+      '',
+      '## Durable User Preferences',
+      '',
+      '- Add long-lived owner preferences that should survive across sessions and model switches.',
+      '',
+      '## Project Context',
+      '',
+      '- Add stable project facts, repo conventions, and active workstreams.',
+      '',
+      '## Decisions and Rationale',
+      '',
+      '- Record important decisions and why they were made.',
+      '',
+      '## Facts to Revalidate',
+      '',
+      '- Add time-sensitive facts that should be checked before reuse, with dates or source context when available.',
+      '',
+      '## Maintenance Rules',
+      '',
+      '- Prefer stable facts, preferences, and decisions over chat transcripts.',
+      '- Do not duplicate the mutable public agent name here; it lives in token metadata and the Agent Card.',
+      '- Add dates or source context when a note may become stale or environment-specific.',
+      '- Remove or rewrite stale memory instead of accumulating contradictions.',
+      '',
+      '## Boundaries',
+      '',
+      '- Do not store seed phrases, private keys, raw wallet signatures, or API keys.',
+      '- Do not store secrets unless the user explicitly asks and the risk is clear.',
+      '- Keep public capabilities in skills.json.',
+      '',
+      `Created: ${created}`,
+    ].join('\n') + '\n',
+  }
+}
+
+export function defaultPublicSkillsJson(identity: EthagentIdentity): string {
+  return renderPublicSkillsJson(defaultPublicSkillsProfile(identity))
+}
+
+function continuityVaultId(identity: Pick<EthagentIdentity, 'chainId' | 'identityRegistryAddress' | 'agentId' | 'address'>): string {
+  const chain = identity.chainId?.toString() ?? 'unknown-chain'
+  const registry = sanitizePathPart(identity.identityRegistryAddress ?? 'unknown-registry')
+  const token = sanitizePathPart(identity.agentId ?? identity.address)
+  return `${chain}-${registry}-${token}`
+}
+
+function sanitizePathPart(value: string): string {
+  return value.trim().toLowerCase().replace(/^0x/, '').replace(/[^a-z0-9._-]+/g, '-').slice(0, 120) || 'unknown'
+}
+
+async function writeMissingPrivateFile(file: string, content: string): Promise<void> {
+  if (await exists(file)) return
+  await atomicWriteText(file, ensureTrailingNewline(content), { mode: 0o600 })
+}
+
+async function resolvePublicSkillsFallback(
+  identity: EthagentIdentity,
+  fallback: string | (() => Promise<string>) | undefined,
+): Promise<string> {
+  if (typeof fallback === 'string') return fallback
+  if (fallback) {
+    try {
+      return await fallback()
+    } catch {
+      return defaultPublicSkillsJson(identity)
+    }
+  }
+  return defaultPublicSkillsJson(identity)
+}
+
+async function readOrDefault(file: string, fallback: string): Promise<string> {
+  try {
+    return await fs.readFile(file, 'utf8')
+  } catch (err: unknown) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return fallback
+    throw err
+  }
+}
+
+async function exists(file: string): Promise<boolean> {
+  try {
+    await fs.access(file)
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function statIfExists(file: string): Promise<import('node:fs').Stats | null> {
+  try {
+    return await fs.stat(file)
+  } catch {
+    return null
+  }
+}
+
+function ensureTrailingNewline(value: string): string {
+  return value.endsWith('\n') ? value : `${value}\n`
+}
+
+type SyncBlock = {
+  marker: string
+  legacyHeading?: string
+}
+
+function renderPrivateIdentityBlock(args: {
+  owner: string
+  token: string
+  chainId: string
+  registry: string
+}): string {
+  return [
+    '<!-- ethagent:identity:start -->',
+    '## Agent Identity',
+    `- Owner wallet: ${args.owner}`,
+    `- ERC-8004 token: ${args.token}`,
+    `- Chain ID: ${args.chainId}`,
+    `- Registry: ${args.registry}`,
+    '- Visibility: private local working file; encrypted before IPFS backup.',
+    '<!-- ethagent:identity:end -->',
+  ].join('\n')
+}
+
+function syncGeneratedMarkdown(existing: string, fresh: string, blocks: SyncBlock[]): string {
+  let next = replaceFirstHeading(existing, firstHeading(fresh))
+  for (const block of blocks) {
+    next = replaceOrInsertMarkedBlock(next, fresh, block)
+  }
+  return ensureTrailingNewline(next)
+}
+
+function firstHeading(markdown: string): string {
+  return markdown.split(/\r?\n/).find(line => line.startsWith('# ')) ?? ''
+}
+
+function replaceFirstHeading(markdown: string, heading: string): string {
+  if (!heading) return markdown
+  const lines = markdown.split(/\r?\n/)
+  const index = lines.findIndex(line => line.startsWith('# '))
+  if (index === -1) return `${heading}\n\n${markdown.trimStart()}`
+  lines[index] = heading
+  return lines.join('\n')
+}
+
+function replaceOrInsertMarkedBlock(markdown: string, fresh: string, block: SyncBlock): string {
+  const freshBlock = extractMarkedBlock(fresh, block.marker)
+  if (!freshBlock) return markdown
+  const replaced = replaceMarkedBlock(markdown, block.marker, freshBlock)
+  if (replaced) return replaced
+  if (block.legacyHeading) {
+    const replacedLegacy = replaceMarkdownSection(markdown, block.legacyHeading, freshBlock)
+    if (replacedLegacy) return replacedLegacy
+  }
+  return insertAfterFirstHeading(markdown, freshBlock)
+}
+
+function extractMarkedBlock(markdown: string, marker: string): string | null {
+  const start = `<!-- ethagent:${marker}:start -->`
+  const end = `<!-- ethagent:${marker}:end -->`
+  const startIndex = markdown.indexOf(start)
+  const endIndex = markdown.indexOf(end, startIndex + start.length)
+  if (startIndex === -1 || endIndex === -1) return null
+  return markdown.slice(startIndex, endIndex + end.length).trim()
+}
+
+function replaceMarkedBlock(markdown: string, marker: string, replacement: string): string | null {
+  const start = `<!-- ethagent:${marker}:start -->`
+  const end = `<!-- ethagent:${marker}:end -->`
+  const startIndex = markdown.indexOf(start)
+  const endIndex = markdown.indexOf(end, startIndex + start.length)
+  if (startIndex === -1 || endIndex === -1) return null
+  return `${markdown.slice(0, startIndex)}${replacement}${markdown.slice(endIndex + end.length)}`
+}
+
+function replaceMarkdownSection(markdown: string, heading: string, replacement: string): string | null {
+  const lines = markdown.split(/\r?\n/)
+  const start = lines.findIndex(line => line.trim() === `## ${heading}`)
+  if (start === -1) return null
+  const end = lines.findIndex((line, index) => index > start && /^##\s+/.test(line))
+  const before = lines.slice(0, start)
+  const after = end === -1 ? [] : lines.slice(end)
+  return [...before, replacement, '', ...after].join('\n')
+}
+
+function insertAfterFirstHeading(markdown: string, block: string): string {
+  const lines = markdown.split(/\r?\n/)
+  const headingIndex = lines.findIndex(line => line.startsWith('# '))
+  if (headingIndex === -1) return `${block}\n\n${markdown.trimStart()}`
+  const before = lines.slice(0, headingIndex + 1)
+  const after = lines.slice(headingIndex + 1)
+  return [...before, '', block, '', ...after].join('\n')
+}