ethagent 1.1.2 → 2.0.0

package/src/identity/continuity/privateEdit.ts

@@ -1,40 +1,14 @@
-import fs from 'node:fs/promises'
 import path from 'node:path'
 import { atomicWriteText } from '../../storage/atomicWrite.js'
-import type { EthagentConfig, EthagentIdentity } from '../../storage/config.js'
-import { applyRequestedEdit } from '../../tools/editUtils.js'
-import {
-  continuityVaultRef,
-  defaultContinuityFiles,
-  ensureContinuityVault,
-  type PrivateContinuityFile,
-} from './storage.js'
+import type { EthagentConfig } from '../../storage/config.js'
+import { ensureContinuityVault } from './storage.js'
+import { ensureTrailingNewline } from './storage/files.js'
+import { applyPrivateContinuityEdit } from './privateEdit/apply.js'
+import { renderPrivateContinuityDiff } from './privateEdit/diff.js'
+import { privateContinuityPath, readPrivateContinuityFile } from './privateEdit/files.js'
+import type { PreparedPrivateContinuityEdit, PrivateContinuityEditInput } from './privateEdit/types.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
-}
+export type { PreparedPrivateContinuityEdit, PrivateContinuityEditInput } from './privateEdit/types.js'
 
 export async function preparePrivateContinuityEdit(
   input: PrivateContinuityEditInput,
@@ -42,7 +16,7 @@ export async function preparePrivateContinuityEdit(
 ): Promise<PreparedPrivateContinuityEdit> {
   const identity = config?.identity
   if (!identity) {
-    throw new Error('no active identity; create or load an identity before proposing private continuity edits')
+    throw new Error('No active identity; create or load an identity before proposing private continuity edits')
   }
 
   const fullPath = privateContinuityPath(identity, input.file)
@@ -53,7 +27,7 @@ export async function preparePrivateContinuityEdit(
     identity,
     file: input.file,
     fullPath,
-    relativePath: `identity-vault/${input.file}`,
+    relativePath: 'identity-vault/' + input.file,
     directoryPath: path.dirname(fullPath),
     existedBefore: existing.existedBefore,
     previousContent: existing.existedBefore ? existing.content : '',
@@ -66,269 +40,7 @@ export async function preparePrivateContinuityEdit(
   }
 }
 
-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('appendToSection is required for append edits')
-    if (!input.appendText?.trim()) throw new Error('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('oldText is required; private continuity edits must patch existing scaffold text')
-  }
-  if (input.newText === undefined) {
-    throw new Error('newText is required for targeted private continuity edits')
-  }
-  return applyRequestedEdit(
-    input.file,
-    before,
-    input.oldText,
-    input.newText,
-    input.replaceAll ?? false,
-    false,
-  )
-}
-
 export async function writePreparedPrivateContinuityEdit(edit: PreparedPrivateContinuityEdit): Promise<void> {
   await ensureContinuityVault(edit.identity)
   await atomicWriteText(edit.fullPath, ensureTrailingNewline(edit.after), { mode: 0o600 })
 }
-
-function privateContinuityPath(identity: EthagentIdentity, file: PrivateContinuityFile): string {
-  const ref = continuityVaultRef(identity)
-  return file === 'SOUL.md' ? ref.soulPath : ref.memoryPath
-}
-
-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
-  }
-}
-
-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 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/publicSkills.ts

@@ -1,6 +1,6 @@
 import type { EthagentIdentity } from '../../storage/config.js'
 
-export type PublicSkill = {
+type PublicSkill = {
   id: string
   name: string
   description: string
@@ -8,7 +8,7 @@ export type PublicSkill = {
   outputModes: string[]
 }
 
-export type PublicSkillsProfile = {
+type PublicSkillsProfile = {
   name: string
   description: string
   version: string
@@ -16,14 +16,13 @@ export type PublicSkillsProfile = {
   skills: PublicSkill[]
 }
 
-export type AgentCard = {
+type AgentCard = {
   name: string
   description: string
   version: string
   protocolVersion: string
-  url: string
+  url?: string
   image?: string
-  iconUrl?: string
   defaultInputModes: string[]
   defaultOutputModes: string[]
   capabilities: {
@@ -93,7 +92,7 @@ export function renderPublicSkillsJson(profile: PublicSkillsProfile): string {
     ...(profile.imageUrl ? { imageUrl: profile.imageUrl } : {}),
     inputModes,
     outputModes,
-    boundary: 'Public discovery metadata only. This is not executable code, private memory, or a skill installation manifest.',
+    boundary: 'Public discovery only. This is not executable code, private memory, or a skill installation manifest.',
     capabilities: {
       softwareEngineering: true,
       workspaceTools: 'permissioned',
@@ -134,7 +133,7 @@ export function renderPublicSkillsJson(profile: PublicSkillsProfile): string {
   return `${JSON.stringify(summary, null, 2)}\n`
 }
 
-export function createAgentCard(profile: PublicSkillsProfile, url = 'ipfs://pending-agent-endpoint'): AgentCard {
+export function createAgentCard(profile: PublicSkillsProfile, url?: string): AgentCard {
   const inputModes = unique(profile.skills.flatMap(skill => skill.inputModes))
   const outputModes = unique(profile.skills.flatMap(skill => skill.outputModes))
   return {
@@ -142,8 +141,8 @@ export function createAgentCard(profile: PublicSkillsProfile, url = 'ipfs://pend
     description: profile.description,
     version: profile.version,
     protocolVersion: '0.2.6',
-    url,
-    ...(profile.imageUrl ? { image: profile.imageUrl, iconUrl: profile.imageUrl } : {}),
+    ...(url ? { url } : {}),
+    ...(profile.imageUrl ? { image: profile.imageUrl } : {}),
     defaultInputModes: inputModes.length ? inputModes : ['text/markdown'],
     defaultOutputModes: outputModes.length ? outputModes : ['text/markdown'],
     capabilities: {

package/src/identity/continuity/snapshots.ts

@@ -9,7 +9,7 @@ import {
   type ContinuitySnapshotContentHashes,
 } from './storage.js'
 
-export type PublishedContinuitySnapshot = {
+type PublishedContinuitySnapshot = {
   version: 1
   id: string
   createdAt: string
@@ -30,12 +30,12 @@ export type PublishedContinuitySnapshot = {
   }
 }
 
-export type RecordPublishedContinuitySnapshotInput = {
+type RecordPublishedContinuitySnapshotInput = {
   identity: EthagentIdentity
   label?: string
 }
 
-export function publishedContinuitySnapshotsPath(identity: EthagentIdentity): string {
+function publishedContinuitySnapshotsPath(identity: EthagentIdentity): string {
   return path.join(continuityVaultRef(identity).dir, '.published-snapshots.jsonl')
 }
 
@@ -88,10 +88,10 @@ export async function updatePublishedContinuitySnapshotContentHashes(
   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 })
+    if (!base) throw new Error('Published snapshot was not found')
+    snapshots.push(refreshPublishedSnapshotSidecars({ ...base, contentHashes }, identity))
   } else {
-    snapshots[index] = { ...snapshots[index]!, contentHashes }
+    snapshots[index] = refreshPublishedSnapshotSidecars({ ...snapshots[index]!, contentHashes }, identity)
   }
   await atomicWriteText(
     publishedContinuitySnapshotsPath(identity),
@@ -135,6 +135,17 @@ function enrichPublishedSnapshot(
   }
 }
 
+function refreshPublishedSnapshotSidecars(
+  snapshot: PublishedContinuitySnapshot,
+  identity: EthagentIdentity,
+): PublishedContinuitySnapshot {
+  return {
+    ...snapshot,
+    ...(identity.publicSkills?.cid ? { publicSkillsCid: identity.publicSkills.cid } : {}),
+    ...(identity.publicSkills?.agentCardCid ? { agentCardCid: identity.publicSkills.agentCardCid } : {}),
+  }
+}
+
 async function readPublishedContinuitySnapshotFile(identity: EthagentIdentity): Promise<PublishedContinuitySnapshot[]> {
   let raw: string
   try {

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

@@ -0,0 +1,111 @@
+import type { EthagentIdentity } from '../../../storage/config.js'
+import type { ContinuityAgentSnapshot, ContinuityFiles } from '../envelope.js'
+import { defaultPublicSkillsProfile, renderPublicSkillsJson } from '../publicSkills.js'
+import { renderPrivateIdentityBlock } from './markdown.js'
+
+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 share this file directly; save it via the Identity Hub encrypted snapshot.',
+      '- 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 the token URI and 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 the token URI and 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))
+}

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

@@ -0,0 +1,72 @@
+import fs from 'node:fs/promises'
+import { atomicWriteText } from '../../../storage/atomicWrite.js'
+import type { EthagentIdentity } from '../../../storage/config.js'
+import type { ContinuityFiles } from '../envelope.js'
+import { defaultContinuityFiles } from './defaults.js'
+import { continuityVaultRef } from './paths.js'
+import type { ContinuityVaultRef } from './types.js'
+
+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
+}
+
+async function writeMissingPrivateFile(file: string, content: string): Promise<void> {
+  if (await exists(file)) return
+  await atomicWriteText(file, ensureTrailingNewline(content), { mode: 0o600 })
+}
+
+export 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
+  }
+}
+
+export async function exists(file: string): Promise<boolean> {
+  try {
+    await fs.access(file)
+    return true
+  } catch {
+    return false
+  }
+}
+
+export async function statIfExists(file: string): Promise<import('node:fs').Stats | null> {
+  try {
+    return await fs.stat(file)
+  } catch {
+    return null
+  }
+}
+
+export function ensureTrailingNewline(value: string): string {
+  return value.endsWith('\n') ? value : `${value}\n`
+}