Сумісність з .agent рантайму

Окремий CleanSlice runtime (cleanslice/runtime) зберігає агента як портативну теку .agent/ (SOUL, MEMORY, skills, sessions, secrets, config…). Agentfy.ai 2.0 має бути сумісним із цим форматом, щоб: імпортувати наявних runtime-агентів, запускати цикл агента рантайму без змін у нашому worker, і експортувати/бекапити агента для портативності.

Розкладка .agent/

.agent/
├── SOUL.md                 # персона / системний промпт (managed-файл)
├── USER.md                 # користувацький контекст
├── MEMORY.md               # курована довгострокова пам'ять
├── HEARTBEAT.md            # промпт heartbeat
├── agent.config.json       # IAgentConfig: maxIterations, maxTokens, accessStrategy,
│                           #   heartbeat, session(compaction), memory(limits/review),
│                           #   stopPhrases, managedFiles, syncSkills, tools{...}
├── memory/                 # ролінг денної пам'яті  (YYYY-MM-DD.md)
├── skills/<name>/SKILL.md   # скіли (markdown + frontmatter)
└── data/
    ├── access.json          # users{ id: {status, inviteCode/accessCode, createdAt} }
    ├── secrets/<userId>.json # { "service:key": value }  (напр. gmail:app_password)
    ├── sessions/<chan>:<user>.jsonl  # лог подій: {id,type,ts,data} построково
    ├── memory.sqlite         # FTS-індекс по пам'яті
    └── usage.json            # споживання токенів
# + browser-state/<profile>.json  (живі куки/стан браузера)

Маппінг .agent/ ↔ сутності Agentfy.ai

.agent/	Agentfy.ai 2.0 (близька сумісність — ті самі імена)
SOUL.md	agent.soul (персона / системний промпт — зберігається дослівно)
USER.md	agent.user (контекст людини/профілю — зберігається дослівно)
HEARTBEAT.md	agent.heartbeat (промпт heartbeat)
agent.config.json	agent.config — зберігається дослівно як IAgentConfig; ліміти / accessStrategy / runtimeProfile читаються з нього, а не перейменовуються в інші слайси
MEMORY.md + memory/*.md	agent/memory (curated = MEMORY.md, daily[date] = memory/YYYY-MM-DD.md — той самий текст)
data/memory.sqlite	— (FTS-індекс — похідний, перебудовується на старті; не зберігається/не переноситься)
skills/<name>/SKILL.md	agent/skill (ім'я + frontmatter + тіло дослівно) (слайс додати — див. прогалини)
data/sessions/<chan>:<uid>.jsonl	chat (події як є {id,type,ts,data}; id→externalId)
data/access.json	agent/access (зберігає форму users{ id:{status,inviteCode/accessCode,createdAt} })
data/secrets/<userId>.json	agent/secret (зберігає мапу service:key→value; шифрується at-rest)
data/usage.json	system/usage (BillingEvent'и)
browser-state/*.json	app/account (стан конектора) / браузер-сесія воркера
workspace/	/workspace воркера (emptyDir) + результати → system/file

Близька сумісність — зберігаємо власні імена рантайму

Ми навмисно зберігаємо імена полів рантайму в БД, а не перейменовуємо їх у прийняті в CleanSlice. SOUL.md зберігається як soul, USER.md — як user, MEMORY.md — як memory, HEARTBEAT.md — як heartbeat, а agent.config.json зберігається дослівно як config. Managed-markdown файли маппляться 1:1 на колонки з тим самим стемом; конфіг-JSON опитується на місці (ліміти, accessStrategy, runtimeProfile), а не розкладається й перейменовується по setting / runtimeProfile / access.

Чому: адаптер стає проєкцією, близькою до тотожної, а не семантичним перекладом — round-trip без втрат, цикл рантайму читає/пише ті самі імена, і немає шару перейменувань, який міг би розійтися. Коли рантайм пізніше додасть новий managed-файл, він ляже новим полем з тим самим іменем без зміни маппінгу. (Інші слайси на кшталт setting можуть дзеркалити/читати значення з config для крос-агентних запитів, але config лишається джерелом істини й не переписується.)

Стратегія: .agent/ — портативний пакет + формат на поді

• Postgres — нормалізоване джерело істини (рядок Agent, пам'ять, чат, секрети, доступ…).
• .agent/ — проєкція цього стану, використовується як (a) пакет обміну/бекапу і (b) робоча тека на поді, коли worker ганяє цикл рантайму.
• Двонаправлений адаптер (agent/package) маппить між ними; worker матеріалізує .agent/ з БД перед турном і синхронить дельти назад після.

Саме це дозволяє workerу перевикористати цикл + тул-виконавці рантайму без змін — вони читають/пишуть .agent/, а адаптер тримає БД у синхроні.

Матеріалізація / синхронізація на рантаймі

турну потрібен рантайм
   → менеджер воркера hydrate'ить .agent/ з Postgres (+ object storage) у workspace пода
   → цикл рантайму працює проти .agent/ (без змін — читає SOUL/MEMORY/skills, пише sessions/…)
   → по завершенні: синхронить дельти назад
        sessions/*.jsonl  → chat (нові повідомлення)
        MEMORY.md, memory/*.md → agent/memory
        data/secrets/*    → agent/secret (якщо змінились)
        data/usage.json   → system/usage події
        browser-state/*   → app/account
   → workspace стирається; довговічний стан уже збережено

Перевикористовуємо наявну diff-manifest S3-синхронізацію рантайму (pull-on-boot / push-on-change): под може тягнути матеріалізований .agent/ з object storage і пушити зміни, тож шар синхронізації — той, що рантайм уже постачає; Agentfy.ai володіє лише проєкцією БД↔пакет.

Імпорт / експорт

• Імпорт теки .agent/ → створити/оновити сутності Agentfy.ai (онбординг наявного runtime-агента).
• Експорт агента → тека .agent/ (бекап, портативність або запуск на окремому рантаймі). Round-trip працює, бо обидві сторони говорять одним форматом пакета.

Прогалини для повної сумісності

• Додати agent/skill (markdown-скіли з frontmatter) до групи agent — у рантайму є скіли; наша L5-розбивка їх загубила. Також підтвердити наявність сабслайсів agent/secret, agent/access, agent/heartbeat, agent/cron (вони маппляться 1:1 на .agent/).
• sessions/*.jsonl ↔ chat: визначити маппінг типів подій (user/assistant/tool_call/ tool_result/summary → рядки повідомлень + tool/summary-записи).
• access.json ↔ user: рантайм ключує користувачів за id каналу (напр. Telegram id); змапити на ідентичності user/team Agentfy.ai.
• Версіонування: запінити версію схеми .agent (рантайм її розвиває) і тримати адаптер толерантним до відсутніх/зайвих файлів.

Де живе

• Адаптер: api → agent/package (імпорт/експорт + маппінг БД↔.agent/).
• Матеріалізатор/синк: слайс runtime/worker (hydrate перед турном, синк дельт після), перевикористовуючи S3/diff-синк рантайму.
• Цикл + тул-виконавці: застосунок worker бере їх з cleanslice/runtime і ганяє проти матеріалізованої .agent/.