Artifact drivers

ai.artifactDrivers — runtime-объект, через который ai-agent-service управляет сессией генерации/редактирования артефакта.

Минимальный driver (plain text)

Достаточно для text-based artifact types:

export const registryTestTextDriver = {
  name: 'registry-test-doc',

  buildSessionContent(_initial: unknown, draftText: string) {
    return { text: draftText };
  },

  getInstructions() {
    return 'Артефакт — plain text в content.text. Используй readText / replaceText.';
  },

  validate(content: unknown) {
    if (typeof content !== 'object' || !content || typeof (content as { text?: unknown }).text !== 'string') {
      return { valid: false, errors: ['content.text must be a string'] };
    }
    return { valid: true, errors: [] };
  },

  finalize(content: unknown, templateDef: unknown, baseContent?: unknown) {
    const text = /* extract text */;
    return { /* merge */, text };
  },

  createTools() {
    return {};  // host добавит plain-text tools автоматически
  },
};

Условие fallback в ai-agent-service:

• buildSessionContent возвращает объект с полем text
• createTools() пустой или не определён

Host добавляет: readText, searchText, replaceText, insertText, deleteText, validateDocument, finalizeArtifact.

Полный driver (explicit tools)

project-notes реализует tools явно через ai SDK + zod:

import { tool } from 'ai';
import { z } from 'zod';

export const notesTextDriver = {
  name: 'notes-doc',
  buildSessionContent(/* … */) { /* … */ },
  createTools(session, hooks) {
    return {
      readText: tool({ /* … */ }),
      replaceText: tool({ /* … */ }),
      // …
    };
  },
};

Когда нужны explicit tools:

• Нестандартная структура content (не { text })
• Кастомная семантика операций
• Дополнительные side effects (progress, revision hooks)

Связь с ai.artifactTypes

Слой	Registry	Ответственность
Generation metadata	ai.artifactTypes	Prompts, schema, parse LLM output
Edit session	ai.artifactDrivers	Tools, validate, finalize в сессии

Оба регистрируются с одним key (notes-doc).

finalize и auth

При finalizeArtifact backend ArtifactVersion принимает author через service token (author.connect.id), не только session user. Если finalize падает с auth error после генерации — проверьте backend restart и service token flow.

См. Troubleshooting.

validate

Driver validate вызывается перед сохранением. Возвращайте { valid: boolean, errors: string[] }.

ai.artifactTypes.validateDraft — отдельная validation для draft UI (может дублировать логику).

Чеклист

• [ ] Key совпадает в app.artifactTypes, ai.artifactTypes, ai.artifactDrivers
• [ ] buildSessionContent согласован с editor content shape
• [ ] finalize merge корректно с templateDef и baseContent
• [ ] Протестирован full flow: generate → edit → validate → finalize → save

Reference

Extension	Driver style
registry-test	Minimal + plain-text fallback
project-notes	Explicit createTools with ai + zod

Исходники:

• packages/extensions/registry-test/src/ai/minimal-driver.ts
• packages/extensions/project-notes/src/ai/text-driver.ts