ethagent 1.1.2 → 2.0.0

package/src/identity/continuity/storage/markdown.ts

@@ -0,0 +1,81 @@
+type SyncBlock = {
+  marker: string
+}
+
+export 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')
+}
+
+export 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
+  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 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')
+}
+
+function ensureTrailingNewline(value: string): string {
+  return value.endsWith('\n') ? value : `${value}\n`
+}

package/src/identity/continuity/storage/paths.ts

@@ -0,0 +1,24 @@
+import path from 'node:path'
+import { getConfigDir, type EthagentIdentity } from '../../../storage/config.js'
+import type { ContinuityVaultRef } from './types.js'
+
+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'),
+  }
+}
+
+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'
+}

package/src/identity/continuity/storage/scaffold.ts

@@ -0,0 +1,124 @@
+import { atomicWriteText } from '../../../storage/atomicWrite.js'
+import type { EthagentIdentity } from '../../../storage/config.js'
+import type { ContinuityFiles } from '../envelope.js'
+import { defaultContinuityFiles, defaultPublicSkillsJson } from './defaults.js'
+import {
+  ensureContinuityFiles,
+  ensureContinuityVault,
+  ensureTrailingNewline,
+  exists,
+  readContinuityFiles,
+  readOrDefault,
+  writeContinuityFiles,
+} from './files.js'
+import { syncGeneratedMarkdown } from './markdown.js'
+import type { ContinuityVaultRef, IdentityMarkdownScaffold } from './types.js'
+
+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' },
+    ]),
+    '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,
+    }
+    if (!Object.hasOwn(freshParsed, 'imageUrl')) delete merged.imageUrl
+    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
+}
+
+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)
+}

package/src/identity/continuity/storage/status.ts

@@ -0,0 +1,86 @@
+import { createHash } from 'node:crypto'
+import type { EthagentIdentity } from '../../../storage/config.js'
+import type { ContinuityFiles } from '../envelope.js'
+import { continuityVaultRef } from './paths.js'
+import { exists, readContinuityFiles, statIfExists } from './files.js'
+import { readPublicSkillsFile } from './scaffold.js'
+import type { ContinuityPublishState, ContinuitySnapshotContentHashes, ContinuityVaultRef, ContinuityWorkingTreeStatus } from './types.js'
+
+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)
+}
+
+function continuitySnapshotContentHashes(
+  privateFiles: ContinuityFiles,
+  publicSkills: string,
+): ContinuitySnapshotContentHashes {
+  return {
+    'SOUL.md': hashContinuitySnapshotContent(privateFiles['SOUL.md']),
+    'MEMORY.md': hashContinuitySnapshotContent(privateFiles['MEMORY.md']),
+    'skills.json': hashContinuitySnapshotContent(publicSkills),
+  }
+}
+
+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`
+}

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

@@ -0,0 +1,27 @@
+import type { ContinuityFiles } from '../envelope.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
+}