ethagent 2.3.0 → 3.0.0

package/src/identity/continuity/envelope.ts

@@ -10,6 +10,16 @@ export type ContinuityFiles = {
   'MEMORY.md': string
 }
 
+export type ContinuitySkillsTree = Record<string, string>
+
+const PRIVATE_SKILL_FILE_RE = /^[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)+$/
+const PRIVATE_SKILL_LAST_SEG_FILE_RE = /^[A-Za-z0-9._-]+\.[A-Za-z0-9]+$/
+const LEGACY_NESTED_SKILL_RE = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+\/.+$/
+const LEGACY_FLAT_NAME_MD_RE = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+\.md$/i
+const MAX_PRIVATE_SKILL_ENTRIES = 500
+const MAX_PRIVATE_SKILL_BODY_BYTES = 256 * 1024
+const MAX_PRIVATE_SKILL_PATH_LEN = 256
+
 type ContinuityTranscriptSummary = {
   sessionId?: string
   createdAt?: string
@@ -33,6 +43,7 @@ type ContinuitySnapshotPayload = {
   sequence?: number
   agent: ContinuityAgentSnapshot
   files: ContinuityFiles
+  skills?: ContinuitySkillsTree
   transcript: ContinuityTranscriptSummary[]
   state: Record<string, unknown>
 }
@@ -997,6 +1008,7 @@ function continuityPayloadFromArgs(args: {
   createdAt: string
   payload: Omit<ContinuitySnapshotPayload, 'version' | 'ownerAddress' | 'createdAt'> & { createdAt?: string }
 }): ContinuitySnapshotPayload {
+  const skills = normalizeContinuitySkills(args.payload.skills)
   return {
     version: 1,
     ownerAddress: args.ownerAddress,
@@ -1004,6 +1016,7 @@ function continuityPayloadFromArgs(args: {
     ...(args.payload.sequence !== undefined ? { sequence: args.payload.sequence } : {}),
     agent: normalizeAgentSnapshot(args.payload.agent),
     files: normalizeContinuityFiles(args.payload.files),
+    ...(skills ? { skills } : {}),
     transcript: normalizeTranscript(args.payload.transcript),
     state: normalizeState(args.payload.state),
   }
@@ -1015,6 +1028,7 @@ function normalizeContinuityPayload(input: unknown): ContinuitySnapshotPayload {
   if (obj.version !== 1) throw new Error('Continuity snapshot payload version is invalid')
   if (typeof obj.ownerAddress !== 'string') throw new Error('Continuity snapshot owner is invalid')
   if (typeof obj.createdAt !== 'string') throw new Error('Continuity snapshot timestamp is invalid')
+  const skills = normalizeContinuitySkills(obj.skills)
   return {
     version: 1,
     ownerAddress: toChecksumAddress(obj.ownerAddress),
@@ -1022,11 +1036,122 @@ function normalizeContinuityPayload(input: unknown): ContinuitySnapshotPayload {
     ...(typeof obj.sequence === 'number' && Number.isSafeInteger(obj.sequence) ? { sequence: obj.sequence } : {}),
     agent: normalizeAgentSnapshot(obj.agent),
     files: normalizeContinuityFiles(obj.files),
+    ...(skills ? { skills } : {}),
     transcript: normalizeTranscript(obj.transcript),
     state: normalizeState(obj.state),
   }
 }
 
+export function normalizeContinuitySkills(input: unknown): ContinuitySkillsTree | undefined {
+  if (input === undefined || input === null) return undefined
+  if (typeof input !== 'object' || Array.isArray(input)) return undefined
+  const obj = input as Record<string, unknown>
+  const out: ContinuitySkillsTree = {}
+  let count = 0
+  const tryInsert = (key: string, rawValue: unknown): void => {
+    if (count >= MAX_PRIVATE_SKILL_ENTRIES) return
+    if (typeof rawValue !== 'string') return
+    if (key.length === 0 || key.length > MAX_PRIVATE_SKILL_PATH_LEN) return
+    if (key.includes('\0')) return
+    if (key.includes('..')) return
+    if (key.startsWith('/')) return
+    if (/^[A-Za-z]:/.test(key)) return
+    if (!isAcceptableSkillKey(key)) return
+    if (Buffer.byteLength(rawValue, 'utf8') > MAX_PRIVATE_SKILL_BODY_BYTES) return
+    if (out[key] !== undefined) return
+    out[key] = rawValue
+    count++
+  }
+  const legacyRoots = new Set<string>()
+  const realSkillFolders = new Set<string>()
+  for (const rawKey of Object.keys(obj)) {
+    const key = rawKey.replace(/\\/g, '/')
+    const segments = key.split('/')
+    if (segments.length === 3 && segments[2] === 'SKILL.md' && segments[0] && segments[1]) {
+      legacyRoots.add(`${segments[0]}/${segments[1]}`)
+    }
+    if (segments.length === 2 && segments[1] === 'SKILL.md' && segments[0]) {
+      realSkillFolders.add(segments[0])
+    }
+  }
+  for (const [rawKey, rawValue] of Object.entries(obj)) {
+    const key = rawKey.replace(/\\/g, '/')
+    if (!isCanonicalFlatKey(key)) continue
+    if (isUnderLegacyRoot(key, legacyRoots)) continue
+    if (!keyHasRealSkillFolder(key, realSkillFolders)) continue
+    tryInsert(key, rawValue)
+  }
+  for (const [rawKey, rawValue] of Object.entries(obj)) {
+    const key = rawKey.replace(/\\/g, '/')
+    if (
+      isCanonicalFlatKey(key)
+      && !isUnderLegacyRoot(key, legacyRoots)
+      && keyHasRealSkillFolder(key, realSkillFolders)
+    ) continue
+    const upgraded = upgradeLegacySkillKey(key, legacyRoots)
+    if (!upgraded) continue
+    tryInsert(upgraded, rawValue)
+  }
+  return count > 0 ? out : undefined
+}
+
+function isUnderLegacyRoot(key: string, legacyRoots: Set<string>): boolean {
+  for (const root of legacyRoots) {
+    if (key === `${root}/SKILL.md`) return true
+    if (key.startsWith(`${root}/`)) return true
+  }
+  return false
+}
+
+function keyHasRealSkillFolder(key: string, realSkillFolders: Set<string>): boolean {
+  const first = key.split('/')[0]
+  if (!first) return false
+  return realSkillFolders.has(first)
+}
+
+function isCanonicalFlatKey(key: string): boolean {
+  if (!PRIVATE_SKILL_FILE_RE.test(key)) return false
+  const segments = key.split('/')
+  if (segments.length < 2) return false
+  const last = segments[segments.length - 1]!
+  if (last === 'SKILL.md') return segments.length === 2
+  return PRIVATE_SKILL_LAST_SEG_FILE_RE.test(last)
+}
+
+function isAcceptableSkillKey(key: string): boolean {
+  return isCanonicalFlatKey(key)
+}
+
+function upgradeLegacySkillKey(key: string, legacyRoots: Set<string>): string | null {
+  for (const root of legacyRoots) {
+    if (key === `${root}/SKILL.md` || key.startsWith(`${root}/`)) {
+      const [first, second] = root.split('/')
+      if (!first || !second) continue
+      const rest = key.slice(root.length + 1)
+      const flattened = `${first}-${second}/${rest}`
+      return isCanonicalFlatKey(flattened) ? flattened : null
+    }
+  }
+  if (LEGACY_FLAT_NAME_MD_RE.test(key)) {
+    const [category, file] = key.split('/')
+    if (!category || !file) return null
+    const slug = file.replace(/\.md$/i, '')
+    if (!slug) return null
+    const flattened = `${category}-${slug}/SKILL.md`
+    return isCanonicalFlatKey(flattened) ? flattened : null
+  }
+  if (LEGACY_NESTED_SKILL_RE.test(key)) {
+    const segments = key.split('/')
+    if (segments.length < 3) return null
+    const [first, second, ...rest] = segments
+    if (!first || !second || rest.length === 0) return null
+    const flattened = `${first}-${second}/${rest.join('/')}`
+    return isCanonicalFlatKey(flattened) ? flattened : null
+  }
+  if (isCanonicalFlatKey(key)) return key
+  return null
+}
+
 function normalizeAgentSnapshot(input: unknown): ContinuityAgentSnapshot {
   if (!input || typeof input !== 'object' || Array.isArray(input)) return {}
   const obj = input as Record<string, unknown>

package/src/identity/continuity/publicSkills.ts

@@ -1,4 +1,5 @@
 import type { EthagentIdentity } from '../../storage/config.js'
+import type { SkillIndexEntry } from './skills/types.js'
 
 type PublicSkill = {
   id: string
@@ -45,7 +46,7 @@ export function defaultPublicSkillsProfile(identity: EthagentIdentity): PublicSk
     : identity.agentId ? `ethagent #${identity.agentId}` : 'ethagent'
   const description = typeof state.description === 'string' && state.description.trim()
     ? state.description.trim()
-    : 'A wallet-owned AI coding agent.'
+    : 'privacy-first AI agent with a portable Ethereum identity'
   const imageUrl = typeof state.imageUrl === 'string' && state.imageUrl.trim()
     ? state.imageUrl.trim()
     : undefined
@@ -80,6 +81,41 @@ export function defaultPublicSkillsProfile(identity: EthagentIdentity): PublicSk
   }
 }
 
+export function appendPublicSkillEntries(
+  profile: PublicSkillsProfile,
+  entries: readonly SkillIndexEntry[],
+): PublicSkillsProfile {
+  if (entries.length === 0) return profile
+  const baselineIds = new Set(profile.skills.map(skill => skill.id))
+  const appended: PublicSkill[] = []
+  const usedIds = new Set(baselineIds)
+  for (const entry of entries) {
+    if (entry.visibility !== 'public' && entry.visibility !== 'discoverable') continue
+    const id = uniqueSkillId(entry.name, usedIds)
+    usedIds.add(id)
+    appended.push({
+      id,
+      name: entry.displayName ?? entry.name,
+      description: entry.description || entry.name,
+      inputModes: ['text/markdown'],
+      outputModes: ['text/markdown'],
+    })
+  }
+  if (appended.length === 0) return profile
+  return {
+    ...profile,
+    skills: [...profile.skills, ...appended],
+  }
+}
+
+function uniqueSkillId(base: string, used: Set<string>): string {
+  const slug = base.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'skill'
+  if (!used.has(slug)) return slug
+  let i = 2
+  while (used.has(`${slug}-${i}`)) i++
+  return `${slug}-${i}`
+}
+
 export function renderPublicSkillsJson(profile: PublicSkillsProfile): string {
   const inputModes = unique(profile.skills.flatMap(skill => skill.inputModes))
   const outputModes = unique(profile.skills.flatMap(skill => skill.outputModes))

package/src/identity/continuity/skills/frontmatter.ts

@@ -0,0 +1,183 @@
+import type { SkillFrontmatter, SkillVisibility } from './types.js'
+
+const SUPPORTED_KEYS = new Set([
+  'name',
+  'description',
+  'when_to_use',
+  'when-to-use',
+  'whenToUse',
+  'version',
+  'argument-hint',
+  'argument_hint',
+  'argumentHint',
+  'tags',
+  'visibility',
+])
+
+const VISIBILITY_VALUES: SkillVisibility[] = ['private', 'public', 'discoverable']
+
+export type ParsedSkillFile = {
+  frontmatter: SkillFrontmatter
+  body: string
+}
+
+export function parseSkillFile(content: string): ParsedSkillFile {
+  const normalized = content.replace(/^/, '').replace(/\r\n?/g, '\n')
+  if (!normalized.startsWith('---\n') && normalized !== '---' && !normalized.startsWith('---\r')) {
+    return { frontmatter: {}, body: normalized.trim() }
+  }
+  const afterOpen = normalized.slice(4)
+  const closeIdx = afterOpen.search(/^---\s*$/m)
+  if (closeIdx < 0) {
+    return { frontmatter: {}, body: normalized.trim() }
+  }
+  const fmText = afterOpen.slice(0, closeIdx)
+  const bodyText = afterOpen.slice(closeIdx).replace(/^---\s*\n?/, '').replace(/^\n+/, '')
+  return {
+    frontmatter: parseFrontmatterBlock(fmText),
+    body: bodyText.trim(),
+  }
+}
+
+function parseFrontmatterBlock(text: string): SkillFrontmatter {
+  const out: SkillFrontmatter = {}
+  const lines = text.split('\n')
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    if (line === undefined) continue
+    const trimmed = line.trim()
+    if (!trimmed || trimmed.startsWith('#')) continue
+    const match = /^([A-Za-z_][A-Za-z0-9_\-]*)\s*:\s*(.*)$/.exec(line)
+    if (!match) continue
+    const rawKey = match[1] ?? ''
+    if (!SUPPORTED_KEYS.has(rawKey)) continue
+    let rawValue = match[2] ?? ''
+    if (rawValue === '' || rawValue === '|' || rawValue === '>') {
+      const collected: string[] = []
+      while (i + 1 < lines.length) {
+        const next = lines[i + 1]
+        if (next === undefined) break
+        if (next.startsWith('  ') || next.startsWith('\t')) {
+          collected.push(next.replace(/^\s+/, ''))
+          i++
+        } else if (next === '' || next.trim() === '') {
+          break
+        } else {
+          break
+        }
+      }
+      rawValue = collected.join(' ').trim()
+    }
+    const key = normalizeKey(rawKey)
+    if (!key) continue
+    assignKey(out, key, rawValue)
+  }
+  return out
+}
+
+function normalizeKey(key: string): keyof SkillFrontmatter | null {
+  switch (key) {
+    case 'name': return 'name'
+    case 'description': return 'description'
+    case 'when_to_use':
+    case 'when-to-use':
+    case 'whenToUse':
+      return 'whenToUse'
+    case 'version': return 'version'
+    case 'argument-hint':
+    case 'argument_hint':
+    case 'argumentHint':
+      return 'argumentHint'
+    case 'tags': return 'tags'
+    case 'visibility': return 'visibility'
+    default: return null
+  }
+}
+
+function assignKey(out: SkillFrontmatter, key: keyof SkillFrontmatter, rawValue: string): void {
+  const stripped = stripInlineComment(rawValue).trim()
+  if (key === 'tags') {
+    out.tags = parseStringList(stripped)
+    return
+  }
+  if (key === 'visibility') {
+    const literal = parseScalar(stripped).toLowerCase()
+    if ((VISIBILITY_VALUES as string[]).includes(literal)) {
+      out.visibility = literal as SkillVisibility
+    }
+    return
+  }
+  const value = parseScalar(stripped)
+  if (!value) return
+  out[key] = value
+}
+
+function parseScalar(value: string): string {
+  if (value === '') return ''
+  if (value.startsWith('"') && value.endsWith('"') && value.length >= 2) {
+    return unescapeDoubleQuoted(value.slice(1, -1))
+  }
+  if (value.startsWith("'") && value.endsWith("'") && value.length >= 2) {
+    return value.slice(1, -1).replace(/''/g, "'")
+  }
+  return value
+}
+
+function parseStringList(value: string): string[] {
+  if (!value) return []
+  if (value.startsWith('[') && value.endsWith(']')) {
+    const inner = value.slice(1, -1)
+    return splitListItems(inner)
+      .map(parseScalar)
+      .filter(item => item.length > 0)
+  }
+  return splitListItems(value)
+    .map(parseScalar)
+    .filter(item => item.length > 0)
+}
+
+function splitListItems(value: string): string[] {
+  const items: string[] = []
+  let buffer = ''
+  let quote: string | null = null
+  for (let i = 0; i < value.length; i++) {
+    const ch = value[i]
+    if (quote) {
+      buffer += ch
+      if (ch === quote && value[i - 1] !== '\\') quote = null
+      continue
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch
+      buffer += ch
+      continue
+    }
+    if (ch === ',') {
+      items.push(buffer.trim())
+      buffer = ''
+      continue
+    }
+    buffer += ch
+  }
+  if (buffer.trim()) items.push(buffer.trim())
+  return items
+}
+
+function unescapeDoubleQuoted(value: string): string {
+  return value.replace(/\\(["\\/bfnrt])/g, (_, c) => {
+    switch (c) {
+      case 'n': return '\n'
+      case 'r': return '\r'
+      case 't': return '\t'
+      case 'b': return '\b'
+      case 'f': return '\f'
+      default: return c
+    }
+  })
+}
+
+function stripInlineComment(value: string): string {
+  if (value.startsWith('"') || value.startsWith("'") || value.startsWith('[')) return value
+  const hash = value.indexOf(' #')
+  return hash === -1 ? value : value.slice(0, hash)
+}