ethagent 0.2.0 → 1.0.0

package/src/tools/privateContinuityEditTool.ts

@@ -0,0 +1,178 @@
+import { z } from 'zod'
+import {
+  preparePrivateContinuityEdit,
+  writePreparedPrivateContinuityEdit,
+} from '../identity/continuity/privateEdit.js'
+import { recordPrivateContinuityHistorySnapshot } from '../identity/continuity/history.js'
+import { readContinuityFiles, readPublicSkillsFile } from '../identity/continuity/storage.js'
+import type { Tool } from './contracts.js'
+
+const schema = z.object({
+  file: z.preprocess(normalizePrivateContinuityFile, z.enum(['SOUL.md', 'MEMORY.md'])),
+  oldText: z.string().optional(),
+  newText: z.string().optional(),
+  appendToSection: z.string().optional(),
+  appendText: z.string().optional(),
+  replaceAll: z.boolean().optional(),
+  replaceWholeFile: z.boolean().optional(),
+}).superRefine((input, ctx) => {
+  const hasOldText = input.oldText !== undefined
+  const hasNewText = input.newText !== undefined
+  const hasAppendToSection = input.appendToSection !== undefined
+  const hasAppendText = input.appendText !== undefined
+  const targeted = hasOldText || hasNewText
+  const append = hasAppendToSection || hasAppendText
+  if (input.replaceWholeFile) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: 'private continuity files must be edited in place; whole-file replacement is disabled',
+      path: ['replaceWholeFile'],
+    })
+  }
+  if (!targeted && !append) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: 'file alone is not enough; provide either oldText+newText for a targeted edit or appendToSection+appendText for an in-place append',
+    })
+  }
+  if (targeted && append) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: 'provide only one edit mode: oldText+newText or appendToSection+appendText',
+    })
+  }
+  if (targeted && !input.oldText?.trim()) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: 'oldText is required for targeted private continuity edits',
+      path: ['oldText'],
+    })
+  }
+  if (targeted && !hasNewText) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: 'newText is required for targeted private continuity edits',
+      path: ['newText'],
+    })
+  }
+  if (append && !input.appendToSection?.trim()) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: 'appendToSection is required for private continuity appends',
+      path: ['appendToSection'],
+    })
+  }
+  if (append && !input.appendText?.trim()) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: 'appendText is required for private continuity appends',
+      path: ['appendText'],
+    })
+  }
+})
+
+export const privateContinuityEditTool: Tool<typeof schema> = {
+  name: 'propose_private_continuity_edit',
+  kind: 'private-continuity-edit',
+  description: [
+    'Propose an explicit user-approved in-place edit to an existing private identity continuity scaffold.',
+    'Only the identity-vault SOUL.md and MEMORY.md are valid targets; do not create workspace files with these names.',
+    'Do not call read_file, list_directory, or run_bash to locate these files; pass file as SOUL.md or MEMORY.md and this tool resolves the vault path.',
+    'For new memories or preferences call exactly: {"file":"MEMORY.md","appendToSection":"Durable User Preferences","appendText":"- User preference or memory note."}.',
+    'For persona or standing behavior call exactly: {"file":"SOUL.md","appendToSection":"Persona","appendText":"- Persona or standing behavior note."}.',
+    'Prefer appendToSection+appendText to build on an existing scaffold section; use oldText+newText only for targeted replacement after exact text is known.',
+    'Whole-file replacement is disabled for private continuity.',
+    'Approved private continuity edits are not managed by /rewind; the previous version is saved to private identity history before writing.',
+  ].join(' '),
+  inputSchema: schema,
+  inputSchemaJson: {
+    type: 'object',
+    properties: {
+      file: { type: 'string', enum: ['SOUL.md', 'MEMORY.md'], description: 'Private continuity file to edit. Use only the file name; do not pass a workspace path.' },
+      oldText: { type: 'string', description: 'Exact existing scaffold text to replace. Required for targeted replacement edits.' },
+      newText: { type: 'string', description: 'Replacement text for oldText. Do not use this as whole-file content.' },
+      appendToSection: { type: 'string', description: 'Existing markdown section heading to append under, for example "Durable User Preferences" or "Persona". Prefer this for new notes.' },
+      appendText: { type: 'string', description: 'New non-empty markdown bullet to append under appendToSection. This builds on the existing scaffold instead of overwriting it.' },
+      replaceAll: { type: 'boolean', description: 'Replace every exact oldText match. Prefer false unless certain.' },
+    },
+    required: ['file'],
+    additionalProperties: false,
+  },
+  parse(input) {
+    return schema.parse(normalizePrivateContinuityInput(input))
+  },
+  async buildPermissionRequest(input, context) {
+    const prepared = await preparePrivateContinuityEdit(input, context.config)
+    return {
+      kind: 'private-continuity-edit',
+      path: prepared.fullPath,
+      relativePath: prepared.relativePath,
+      directoryPath: prepared.directoryPath,
+      title: 'approve private continuity edit?',
+      subtitle: prepared.fullPath,
+      file: prepared.file,
+      before: prepared.previewBefore,
+      after: prepared.previewAfter,
+      diff: prepared.diff,
+      changeSummary: prepared.changeSummary,
+    }
+  },
+  async execute(input, context) {
+    const prepared = await preparePrivateContinuityEdit(input, context.config)
+    const [previousFiles, previousPublicSkills] = await Promise.all([
+      readContinuityFiles(prepared.identity),
+      readPublicSkillsFile(prepared.identity),
+    ])
+    await recordPrivateContinuityHistorySnapshot({
+      identity: prepared.identity,
+      file: prepared.file,
+      filePath: prepared.fullPath,
+      existedBefore: prepared.existedBefore,
+      previousContent: prepared.previousContent,
+      previousFiles,
+      previousPublicSkills,
+      changeSummary: prepared.changeSummary,
+      createdAt: new Date().toISOString(),
+      sessionId: context.checkpoint?.sessionId,
+      turnId: context.checkpoint?.turnId,
+      promptSnippet: context.checkpoint?.promptSnippet,
+      checkpointLabel: context.checkpoint?.checkpointLabel,
+    })
+    await writePreparedPrivateContinuityEdit(prepared)
+    return {
+      ok: true,
+      summary: prepared.changeSummary,
+      content: formatPrivateContinuityEditResult(prepared.file, prepared.fullPath),
+    }
+  },
+}
+
+function formatPrivateContinuityEditResult(file: 'SOUL.md' | 'MEMORY.md', fullPath: string): string {
+  return [
+    '## Saved private continuity',
+    '',
+    `- File: \`identity-vault/${file}\``,
+    `- Review file: \`${fullPath}\``,
+    '- Open: Identity Hub > Memory and Persona',
+    '- Publish: Identity Hub > Recovery > Publish Snapshot Now',
+    '- History: previous version saved to private identity history; `/rewind` does not restore identity continuity',
+  ].join('\n')
+}
+
+function normalizePrivateContinuityInput(input: Record<string, unknown>): Record<string, unknown> {
+  const normalized = { ...input }
+  if (normalized.appendToSection === undefined) {
+    normalized.appendToSection = normalized.section ?? normalized.heading
+  }
+  if (normalized.appendText === undefined) {
+    normalized.appendText = normalized.note ?? normalized.text ?? normalized.content
+  }
+  return normalized
+}
+
+function normalizePrivateContinuityFile(value: unknown): unknown {
+  if (typeof value !== 'string') return value
+  if (/^soul\.md$/i.test(value.trim())) return 'SOUL.md'
+  if (/^memory\.md$/i.test(value.trim())) return 'MEMORY.md'
+  return value
+}

package/src/tools/privateContinuityReadTool.ts

@@ -0,0 +1,107 @@
+import path from 'node:path'
+import { z } from 'zod'
+import {
+  continuityVaultRef,
+  ensureContinuityFiles,
+  type PrivateContinuityFile,
+} from '../identity/continuity/storage.js'
+import type { Tool } from './contracts.js'
+
+const schema = z.object({
+  file: z.preprocess(normalizePrivateContinuityFile, z.enum(['SOUL.md', 'MEMORY.md'])),
+  startLine: z.number().int().positive().optional(),
+  endLine: z.number().int().positive().optional(),
+})
+
+export const privateContinuityReadTool: Tool<typeof schema> = {
+  name: 'read_private_continuity_file',
+  kind: 'private-continuity-read',
+  description: [
+    'Read an explicitly user-approved private identity continuity file from the identity vault.',
+    'Only SOUL.md and MEMORY.md are valid targets; do not use workspace read_file for these files.',
+    'Use this before surgical removals or targeted replacements that need exact oldText.',
+    'Pass file as SOUL.md or MEMORY.md; this tool resolves the vault path.',
+    'Use startLine and endLine to limit the returned range when possible.',
+  ].join(' '),
+  inputSchema: schema,
+  inputSchemaJson: {
+    type: 'object',
+    properties: {
+      file: { type: 'string', enum: ['SOUL.md', 'MEMORY.md'], description: 'Private continuity file to read. Use only the file name; do not pass a workspace path.' },
+      startLine: { type: 'number', description: 'Optional 1-based starting line.' },
+      endLine: { type: 'number', description: 'Optional 1-based ending line.' },
+    },
+    required: ['file'],
+    additionalProperties: false,
+  },
+  parse(input) {
+    return schema.parse(normalizePrivateContinuityReadInput(input))
+  },
+  async buildPermissionRequest(input, context) {
+    const prepared = preparePrivateContinuityRead(input, context.config)
+    return {
+      kind: 'private-continuity-read',
+      path: prepared.fullPath,
+      relativePath: prepared.relativePath,
+      directoryPath: prepared.directoryPath,
+      title: 'allow private continuity read?',
+      subtitle: input.startLine || input.endLine
+        ? `${prepared.fullPath} · lines ${input.startLine ?? 1}-${input.endLine ?? 'end'}`
+        : prepared.fullPath,
+      file: input.file,
+      range: input.startLine || input.endLine
+        ? `lines ${input.startLine ?? 1}-${input.endLine ?? 'end'}`
+        : 'entire file',
+    }
+  },
+  async execute(input, context) {
+    const prepared = preparePrivateContinuityRead(input, context.config)
+    const files = await ensureContinuityFiles(prepared.identity)
+    return {
+      ok: true,
+      summary: `read private ${input.file}`,
+      content: numberedLineSlice(files[input.file], input.startLine, input.endLine),
+    }
+  },
+}
+
+function preparePrivateContinuityRead(
+  input: z.infer<typeof schema>,
+  config: Parameters<Tool['buildPermissionRequest']>[1]['config'],
+) {
+  const identity = config?.identity
+  if (!identity) {
+    throw new Error('no active identity; create or load an identity before reading private continuity files')
+  }
+  const ref = continuityVaultRef(identity)
+  const fullPath = input.file === 'SOUL.md' ? ref.soulPath : ref.memoryPath
+  return {
+    identity,
+    fullPath,
+    relativePath: `identity-vault/${input.file}`,
+    directoryPath: path.dirname(fullPath),
+  }
+}
+
+function numberedLineSlice(content: string, startLine?: number, endLine?: number): string {
+  const lines = content.replace(/\r\n/g, '\n').replace(/\r/g, '\n').split('\n')
+  const start = Math.max(1, startLine ?? 1)
+  const end = Math.max(start, endLine ?? lines.length)
+  return lines.slice(start - 1, end).map((line, index) => `${start + index}: ${line}`).join('\n')
+}
+
+function normalizePrivateContinuityReadInput(input: Record<string, unknown>): Record<string, unknown> {
+  const normalized = { ...input }
+  if (normalized.file === undefined) {
+    normalized.file = normalized.path ?? normalized.name
+  }
+  return normalized
+}
+
+function normalizePrivateContinuityFile(value: unknown): unknown {
+  if (typeof value !== 'string') return value
+  const basename = path.basename(value.replaceAll('\\', '/')).trim()
+  if (/^soul\.md$/i.test(basename)) return 'SOUL.md'
+  if (/^memory\.md$/i.test(basename)) return 'MEMORY.md'
+  return value
+}

package/src/tools/readTool.ts

@@ -0,0 +1,85 @@
+import fs from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { z } from 'zod'
+import type { EthagentConfig } from '../storage/config.js'
+import type { Tool } from './contracts.js'
+
+const schema = z.object({
+  path: z.string().min(1),
+  startLine: z.number().int().positive().optional(),
+  endLine: z.number().int().positive().optional(),
+})
+
+export const readTool: Tool<typeof schema> = {
+  name: 'read_file',
+  kind: 'read',
+  description: 'Read a text file from the current workspace. Use startLine and endLine to limit the range when the file is large.',
+  inputSchema: schema,
+  inputSchemaJson: {
+    type: 'object',
+    properties: {
+      path: { type: 'string', description: 'Path to the file to read.' },
+      startLine: { type: 'number', description: 'Optional 1-based starting line.' },
+      endLine: { type: 'number', description: 'Optional 1-based ending line.' },
+    },
+    required: ['path'],
+  },
+  parse(input) {
+    return schema.parse(input)
+  },
+  async buildPermissionRequest(input, context) {
+    assertNotPrivateContinuityWorkspacePath(input.path, context.config)
+    const fullPath = resolveWorkspacePath(context.workspaceRoot, input.path)
+    const relativePath = path.relative(context.workspaceRoot, fullPath) || path.basename(fullPath)
+    return {
+      kind: 'read',
+      path: fullPath,
+      relativePath,
+      directoryPath: path.dirname(fullPath),
+      title: 'allow file read?',
+      subtitle: input.startLine || input.endLine
+        ? `${fullPath} · lines ${input.startLine ?? 1}-${input.endLine ?? 'end'}`
+        : fullPath,
+    }
+  },
+  async execute(input, context) {
+    assertNotPrivateContinuityWorkspacePath(input.path, context.config)
+    const fullPath = resolveWorkspacePath(context.workspaceRoot, input.path)
+    const raw = await fs.readFile(fullPath, 'utf8')
+    const lines = raw.replace(/\r\n/g, '\n').split('\n')
+    const start = Math.max(1, input.startLine ?? 1)
+    const end = Math.max(start, input.endLine ?? lines.length)
+    const slice = lines.slice(start - 1, end)
+    const numbered = slice.map((line, i) => `${start + i}: ${line}`).join('\n')
+    return {
+      ok: true,
+      summary: `read ${path.relative(context.workspaceRoot, fullPath) || path.basename(fullPath)}`,
+      content: numbered,
+    }
+  },
+}
+
+function assertNotPrivateContinuityWorkspacePath(
+  requestedPath: string,
+  config: EthagentConfig | undefined,
+): void {
+  if (!config?.identity) return
+  const basename = path.basename(requestedPath.replaceAll('\\', '/')).toUpperCase()
+  if (basename !== 'SOUL.MD' && basename !== 'MEMORY.MD') return
+  throw new Error(
+    `read_file must not read ${basename} from the workspace; use read_private_continuity_file with file "${basename === 'SOUL.MD' ? 'SOUL.md' : 'MEMORY.md'}"`,
+  )
+}
+
+export function resolveWorkspacePath(workspaceRoot: string, requestedPath: string): string {
+  const expandedPath = requestedPath.startsWith('~')
+    ? path.join(os.homedir(), requestedPath.slice(1))
+    : requestedPath
+  const fullPath = path.resolve(workspaceRoot, expandedPath)
+  const rel = path.relative(workspaceRoot, fullPath)
+  if (rel.startsWith('..') || path.isAbsolute(rel)) {
+    throw new Error(`path escapes workspace: ${requestedPath}`)
+  }
+  return fullPath
+}

package/src/tools/registry.ts

@@ -0,0 +1,67 @@
+import type { AnthropicToolDefinition } from '../providers/anthropic.js'
+import type { OpenAIToolDefinition } from '../providers/openai-chat.js'
+import type { Tool } from './contracts.js'
+import { modePolicy, type SessionMode } from '../runtime/sessionMode.js'
+import { bashTool } from './bashTool.js'
+import { changeDirectoryTool } from './changeDirectoryTool.js'
+import { deleteFileTool } from './deleteFileTool.js'
+import { editTool } from './editTool.js'
+import { listDirectoryTool } from './listDirectoryTool.js'
+import { privateContinuityEditTool } from './privateContinuityEditTool.js'
+import { privateContinuityReadTool } from './privateContinuityReadTool.js'
+import { readTool } from './readTool.js'
+import { listMcpResourcesTool, readMcpResourceTool } from './mcpResourceTools.js'
+import { writeFileTool } from './writeFileTool.js'
+
+export const BUILTIN_TOOLS: Tool[] = [
+  changeDirectoryTool,
+  listDirectoryTool,
+  readTool,
+  privateContinuityReadTool,
+  listMcpResourcesTool,
+  readMcpResourceTool,
+  writeFileTool,
+  editTool,
+  privateContinuityEditTool,
+  deleteFileTool,
+  bashTool,
+]
+
+export type ToolAvailabilityContext = {
+  hasIdentity?: boolean
+  dynamicTools?: Tool[]
+}
+
+export function getTool(name: string, context: ToolAvailabilityContext = {}): Tool | undefined {
+  return [...(context.dynamicTools ?? []), ...BUILTIN_TOOLS].find(tool => tool.name === name)
+}
+
+export function toolsForMode(mode: SessionMode = 'chat', context: ToolAvailabilityContext = {}): Tool[] {
+  const policy = modePolicy(mode)
+  const allTools = [...BUILTIN_TOOLS, ...(context.dynamicTools ?? [])]
+  return allTools.filter(tool => {
+    if (mode === 'plan' && tool.kind === 'mcp' && tool.readOnly !== true) return false
+    if (!policy.exposesToolKind(tool.kind)) return false
+    if ((tool.kind === 'private-continuity-read' || tool.kind === 'private-continuity-edit') && !context.hasIdentity) return false
+    return true
+  })
+}
+
+export function anthropicTools(mode: SessionMode = 'chat', context: ToolAvailabilityContext = {}): AnthropicToolDefinition[] {
+  return toolsForMode(mode, context).map(tool => ({
+    name: tool.name,
+    description: tool.description,
+    input_schema: tool.inputSchemaJson,
+  }))
+}
+
+export function openAITools(mode: SessionMode = 'chat', context: ToolAvailabilityContext = {}): OpenAIToolDefinition[] {
+  return toolsForMode(mode, context).map(tool => ({
+    type: 'function',
+    function: {
+      name: tool.name,
+      description: tool.description,
+      parameters: tool.inputSchemaJson,
+    },
+  }))
+}

package/src/tools/writeFileTool.ts

@@ -0,0 +1,142 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { z } from 'zod'
+import { recordRewindSnapshot } from '../storage/rewind.js'
+import type { EthagentConfig } from '../storage/config.js'
+import type { Tool } from './contracts.js'
+import { resolveWorkspacePath } from './readTool.js'
+
+const schema = z.object({
+  path: z.string().min(1),
+  content: z.string(),
+  overwrite: z.boolean().optional(),
+})
+
+export const writeFileTool: Tool<typeof schema> = {
+  name: 'write_file',
+  kind: 'write',
+  description: 'Create a new text file, or replace an entire existing file only when overwrite is true. Prefer edit_file for targeted changes to existing files.',
+  inputSchema: schema,
+  inputSchemaJson: {
+    type: 'object',
+    properties: {
+      path: { type: 'string', description: 'Workspace-relative file path to write.' },
+      content: { type: 'string', description: 'Complete file contents to write.' },
+      overwrite: { type: 'boolean', description: 'Set true only when intentionally replacing an existing file.' },
+    },
+    required: ['path', 'content'],
+  },
+  parse(input) {
+    return schema.parse(input)
+  },
+  async buildPermissionRequest(input, context) {
+    const prepared = await prepareWrite(input, context)
+    return {
+      kind: 'write',
+      path: prepared.fullPath,
+      relativePath: prepared.relativePath,
+      directoryPath: path.dirname(prepared.fullPath),
+      title: prepared.existedBefore ? 'allow file rewrite?' : 'allow file creation?',
+      subtitle: prepared.fullPath,
+      before: previewText(prepared.before),
+      after: previewText(input.content),
+      changeSummary: prepared.existedBefore ? `replace entire ${prepared.relativePath}` : `create ${prepared.relativePath}`,
+    }
+  },
+  async execute(input, context) {
+    const prepared = await prepareWrite(input, context)
+    const rewindWarning = await tryRecordRewindSnapshot({
+      workspaceRoot: context.workspaceRoot,
+      filePath: prepared.fullPath,
+      relativePath: prepared.relativePath,
+      existedBefore: prepared.existedBefore,
+      previousContent: prepared.before,
+      changeSummary: prepared.existedBefore ? `replace entire ${prepared.relativePath}` : `create ${prepared.relativePath}`,
+      createdAt: new Date().toISOString(),
+      sessionId: context.checkpoint?.sessionId,
+      turnId: context.checkpoint?.turnId,
+      messageRole: context.checkpoint?.messageRole,
+      promptSnippet: context.checkpoint?.promptSnippet,
+      checkpointLabel: context.checkpoint?.checkpointLabel,
+    })
+    await fs.mkdir(path.dirname(prepared.fullPath), { recursive: true })
+    await fs.writeFile(prepared.fullPath, input.content, 'utf8')
+    return {
+      ok: true,
+      summary: prepared.existedBefore ? `replace entire ${prepared.relativePath}` : `create ${prepared.relativePath}`,
+      content: rewindWarning
+        ? `updated ${prepared.fullPath}\nwarning: ${rewindWarning}`
+        : `updated ${prepared.fullPath}`,
+    }
+  },
+}
+
+async function prepareWrite(
+  input: z.infer<typeof schema>,
+  context: { workspaceRoot: string; config?: EthagentConfig },
+) {
+  assertSafeWritePath(input.path)
+  assertNotPrivateContinuityWorkspacePath(input.path, context.config, 'write_file')
+  if (input.content.length === 0) {
+    throw new Error('write_file content is empty; provide non-empty file contents')
+  }
+
+  const fullPath = resolveWorkspacePath(context.workspaceRoot, input.path)
+  const relativePath = path.relative(context.workspaceRoot, fullPath) || path.basename(fullPath)
+  const { before, existedBefore } = await readExistingFile(fullPath)
+
+  return { fullPath, relativePath, before, existedBefore }
+}
+
+async function readExistingFile(fullPath: string): Promise<{ before: string; existedBefore: boolean }> {
+  try {
+    const stats = await fs.stat(fullPath)
+    if (stats.isDirectory()) throw new Error('write_file path points to a directory; provide a file path')
+    return { before: await fs.readFile(fullPath, 'utf8'), existedBefore: true }
+  } catch (error: unknown) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return { before: '', existedBefore: false }
+    throw error
+  }
+}
+
+async function tryRecordRewindSnapshot(
+  snapshot: Parameters<typeof recordRewindSnapshot>[0],
+): Promise<string | undefined> {
+  try {
+    await recordRewindSnapshot(snapshot)
+    return undefined
+  } catch (error: unknown) {
+    return `rewind checkpoint was not recorded (${(error as Error).message || 'unknown error'})`
+  }
+}
+
+function assertSafeWritePath(requestedPath: string): void {
+  const trimmed = requestedPath.trim()
+  if (trimmed !== requestedPath || trimmed.length === 0) {
+    throw new Error('write_file path must be a clean workspace-relative file path')
+  }
+  if (/[|;&<>`]/.test(trimmed)) {
+    throw new Error('write_file path must not contain shell operators')
+  }
+  if (/^(?:rm|del|erase|rmdir|remove-item|mkdir|type|cat|echo|copy|move|mv|cp)\b/i.test(trimmed)) {
+    throw new Error('write_file path looks like a shell command; pass only the file path')
+  }
+}
+
+function assertNotPrivateContinuityWorkspacePath(
+  requestedPath: string,
+  config: EthagentConfig | undefined,
+  toolName: string,
+): void {
+  if (!config?.identity) return
+  const basename = path.basename(requestedPath.replaceAll('\\', '/')).toUpperCase()
+  if (basename !== 'SOUL.MD' && basename !== 'MEMORY.MD') return
+  throw new Error(
+    `${toolName} must not create or overwrite ${basename}; use propose_private_continuity_edit to patch the existing identity-vault scaffold`,
+  )
+}
+
+function previewText(text: string, max = 700): string {
+  if (text.length <= max) return text
+  return `${text.slice(0, max - 3)}...`
+}