surma
0dc97c7682
Rewrite Ultimate roles for the WASI world and explicit repositories. Add approved proxy model families, ordered overlays, and executable parser and asset checks.
172 lines
11 KiB
TypeScript
172 lines
11 KiB
TypeScript
/** Pure parsing and ordered overlays for world agent files. The caller supplies all file contents and model configuration. */
|
|
export const thinkingLevels = ['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'] as const
|
|
export type Thinking = typeof thinkingLevels[number]
|
|
export type Family = { model: string; thinking?: Thinking }
|
|
export type Families = Record<string, Family>
|
|
export interface Definition {
|
|
name: string
|
|
description: string
|
|
path: string
|
|
instructions: string
|
|
model?: string
|
|
thinking?: Thinking
|
|
family?: string
|
|
tools?: string[]
|
|
addTools?: string[]
|
|
denyTools?: string[]
|
|
isolate?: 'none' | 'worktree'
|
|
resident?: boolean
|
|
fast?: boolean
|
|
summaries?: boolean
|
|
icon?: string
|
|
tint?: string
|
|
overlays?: string[]
|
|
}
|
|
export type File = { path: string; text: string }
|
|
const fields = ['name', 'description', 'model', 'thinking', 'family', 'tools', 'denyTools', 'isolate', 'resident', 'fast', 'summaries', 'icon', 'tint']
|
|
const familyName = (name: string) => /^[a-z][a-z0-9-]{0,23}$/.test(name)
|
|
const tools = (value: unknown): value is string[] => Array.isArray(value) && value.every(v => typeof v === 'string')
|
|
|
|
/** Scalars and flow lists, plus the block lists and folded description used in Ultimate's parser tests. Not general YAML. */
|
|
function scalar(input: string): unknown {
|
|
const text = input.trim()
|
|
if (text.startsWith('[')) {
|
|
if (!text.endsWith(']')) throw new Error('Unclosed flow list')
|
|
const items = text.slice(1, -1).match(/\s*(?:"(?:\\.|[^"\\])*"|'(?:''|[^'])*'|[^,]+)/g) ?? []
|
|
return items.filter(item => item.trim()).map(item => scalar(item))
|
|
}
|
|
if (text.startsWith('"')) return JSON.parse(text)
|
|
if (text.startsWith("'")) {
|
|
if (!text.endsWith("'")) throw new Error('Unclosed scalar')
|
|
return text.slice(1, -1).replaceAll("''", "'")
|
|
}
|
|
if (text === 'true') return true
|
|
if (text === 'false') return false
|
|
if (text === 'null' || text === '~' || text === '') return null
|
|
if (/^-?\d+(\.\d+)?$/.test(text)) return Number(text)
|
|
if (text.startsWith('{')) return {} // Mapping values cannot satisfy any supported field.
|
|
return text.replace(/\s+#.*$/, '')
|
|
}
|
|
export function parseFrontmatter(text: string): { frontmatter: Record<string, unknown>; body: string } {
|
|
const lines = text.replaceAll('\r\n', '\n').split('\n')
|
|
const end = lines.indexOf('---', 1)
|
|
if (lines[0] !== '---' || end < 0) throw new Error('Expected frontmatter fields between --- lines')
|
|
const frontmatter: Record<string, unknown> = {}
|
|
for (let i = 1; i < end; i++) {
|
|
if (!lines[i].trim() || lines[i].trimStart().startsWith('#')) continue
|
|
const match = /^([A-Za-z][A-Za-z0-9]*):\s*(.*)$/.exec(lines[i])
|
|
if (!match) throw new Error('Expected frontmatter fields between --- lines')
|
|
const [, key, raw] = match
|
|
let value = raw
|
|
if (value.trim().startsWith('[') && !value.trim().endsWith(']')) {
|
|
while (i + 1 < end && !value.trim().endsWith(']')) value += ' ' + lines[++i].trim()
|
|
}
|
|
if (raw === '>' || raw === '|' || raw === '') {
|
|
const block: string[] = []
|
|
while (i + 1 < end && /^\s+\S/.test(lines[i + 1])) block.push(lines[++i].trim())
|
|
if (raw === '>') frontmatter[key] = block.join(' ')
|
|
else if (raw === '|') frontmatter[key] = block.join('\n')
|
|
else frontmatter[key] = block[0]?.startsWith('[') ? scalar(block.join(' ')) : block.length ? block.map(line => scalar(line.replace(/^-\s+/, ''))) : null
|
|
} else frontmatter[key] = scalar(value)
|
|
}
|
|
if (!Object.keys(frontmatter).length) throw new Error('Expected frontmatter fields between --- lines')
|
|
return { frontmatter, body: lines.slice(end + 1).join('\n').trim() }
|
|
}
|
|
function settings(data: Record<string, unknown>, overlay: boolean) {
|
|
const unknown = Object.keys(data).find(key => !fields.includes(key) && !(overlay && key === 'addTools'))
|
|
if (unknown) throw new Error(`Unknown field: ${unknown}`)
|
|
if (typeof data.name !== 'string' || !/^[a-zA-Z0-9_-]+$/.test(data.name)) throw new Error('name must be a nonempty identifier')
|
|
for (const key of ['description', 'model']) {
|
|
if (data[key] !== undefined && (typeof data[key] !== 'string' || !data[key].trim())) throw new Error(key === 'description' ? 'description is required' : 'model must be a nonempty string')
|
|
}
|
|
if (data.family !== undefined && (typeof data.family !== 'string' || !familyName(data.family))) throw new Error('family must be a family name: lowercase letters, digits and -')
|
|
if (data.thinking !== undefined && !thinkingLevels.includes(data.thinking as Thinking)) throw new Error(`thinking must be one of ${thinkingLevels.join(', ')}`)
|
|
for (const key of ['tools', 'denyTools', 'addTools']) {
|
|
if (data[key] !== undefined && !tools(data[key])) throw new Error(`${key} must be a list of tool names`)
|
|
}
|
|
if (data.isolate !== undefined && data.isolate !== 'none' && data.isolate !== 'worktree') throw new Error('isolate must be none or worktree')
|
|
for (const key of ['resident', 'fast', 'summaries']) {
|
|
if (data[key] !== undefined && typeof data[key] !== 'boolean') throw new Error(`${key} must be a boolean`)
|
|
}
|
|
if (data.icon !== undefined && (typeof data.icon !== 'string' || !/^[A-Za-z][A-Za-z0-9]*(-[a-z0-9]+)*$/.test(data.icon))) throw new Error('icon must be a lucide icon name, like Gem or notebook-pen')
|
|
if (data.tint !== undefined && !['violet', 'blue', 'green', 'amber', 'red', 'pink', 'teal', 'grey'].includes(data.tint as string)) throw new Error('tint must be one of violet, blue, green, amber, red, pink, teal, grey')
|
|
return { ...data, ...(typeof data.description === 'string' ? { description: data.description.trim() } : {}) }
|
|
}
|
|
export function parseDefinition(text: string, path: string): Definition {
|
|
const { frontmatter, body } = parseFrontmatter(text)
|
|
const parsed = settings(frontmatter, false)
|
|
if (!parsed.description) throw new Error('description is required')
|
|
if (!body) throw new Error('Instructions are required')
|
|
return { ...parsed, path, instructions: body } as unknown as Definition
|
|
}
|
|
export function parseOverlay(text: string, path: string) {
|
|
const { frontmatter, body } = parseFrontmatter(text)
|
|
if ('tools' in frontmatter) throw new Error('An overlay adds tools with addTools, not tools')
|
|
const parsed = settings(frontmatter, true)
|
|
if (!tools(parsed.addTools)) throw new Error('addTools must be a list of tool names')
|
|
const { name, addTools, ...rest } = parsed
|
|
return { name: name as string, addTools, settings: rest as Partial<Definition>, path, instructions: body }
|
|
}
|
|
export function mergeOverlay(base: Definition, overlay: ReturnType<typeof parseOverlay>): Definition {
|
|
const { model: _pin, ...unpinned } = base
|
|
const suffix = overlay.settings.model?.match(/:(off|minimal|low|medium|high|xhigh|max)$/)
|
|
const resolved = suffix ? { ...overlay.settings, model: overlay.settings.model!.slice(0, -suffix[0].length), thinking: overlay.settings.thinking ?? suffix[1] as Thinking } : overlay.settings
|
|
return {
|
|
...(overlay.settings.family && !overlay.settings.model ? unpinned : base),
|
|
...resolved,
|
|
...(overlay.settings.denyTools ? { denyTools: [...new Set([...(base.denyTools ?? []), ...overlay.settings.denyTools])] } : {}),
|
|
...(base.tools ? { tools: [...new Set([...base.tools, ...overlay.addTools])] } : overlay.addTools.length ? { addTools: [...new Set([...(base.addTools ?? []), ...overlay.addTools])] } : {}),
|
|
instructions: overlay.instructions ? `${base.instructions}\n\n## Project additions\n\n${overlay.instructions}` : base.instructions,
|
|
overlays: [...(base.overlays ?? []), overlay.path],
|
|
}
|
|
}
|
|
export function parseFamilies(text: string): Families {
|
|
const value = JSON.parse(text)
|
|
if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('families must be an object')
|
|
for (const [name, spec] of Object.entries(value) as [string, Family][]) {
|
|
if (!familyName(name) || !spec || typeof spec !== 'object' || !modelRef(spec.model)) throw new Error(`Invalid family: ${name}`)
|
|
if (spec.thinking !== undefined && !thinkingLevels.includes(spec.thinking)) throw new Error(`Invalid thinking for family: ${name}`)
|
|
}
|
|
if (!value.default) throw new Error('default family is required')
|
|
return value
|
|
}
|
|
function modelRef(model: unknown): model is string { return typeof model === 'string' && /^[^/\s]+\/\S+$/.test(model) }
|
|
export function definitionRuns(definition: Definition, families: Families, models: readonly string[]) {
|
|
const family = Object.hasOwn(families, definition.family ?? 'default') ? definition.family ?? 'default' : 'default'
|
|
let model = definition.model ?? families[family].model
|
|
let thinking = definition.thinking ?? (definition.model ? undefined : families[family].thinking)
|
|
const suffix = /:(off|minimal|low|medium|high|xhigh|max)$/.exec(model)
|
|
if (suffix) { model = model.slice(0, -suffix[0].length); thinking = definition.thinking ?? suffix[1] as Thinking }
|
|
if (!modelRef(model) || !models.includes(model)) throw new Error(`model: Model "${model}" not found`)
|
|
const slash = model.indexOf('/')
|
|
return { model: { provider: model.slice(0, slash), modelId: model.slice(slash + 1) }, thinking, ...(definition.model ? { via: 'pin' as const } : { via: 'family' as const, family }) }
|
|
}
|
|
/** Sorted built-ins precede sorted project files. Invalid files produce errors without replacing an earlier definition. */
|
|
export function discoverAgents(files: readonly File[], builtinRoot: string, repo: string, families: Families, models: readonly string[]) {
|
|
const definitions = new Map<string, Definition & { source: 'builtin' | 'project' }>()
|
|
const errors: { name: string; path: string; source: string; error: string }[] = []
|
|
const replaced: { name: string; path: string; source: string }[] = []
|
|
for (const [source, root] of [['builtin', builtinRoot + '/agents/'], ['project', repo + '/.sausage/agents/']] as const) {
|
|
for (const file of files.filter(file => file.path.startsWith(root) && !file.path.slice(root.length).includes('/') && file.path.endsWith('.md')).toSorted((a, b) => a.path.localeCompare(b.path))) {
|
|
try {
|
|
let definition: Definition
|
|
if ('addTools' in parseFrontmatter(file.text).frontmatter) {
|
|
const overlay = parseOverlay(file.text, file.path)
|
|
const base = definitions.get(overlay.name)
|
|
if (!base) throw new Error(`addTools needs an earlier definition named ${overlay.name}`)
|
|
definition = mergeOverlay(base, overlay)
|
|
} else definition = parseDefinition(file.text, file.path)
|
|
definitionRuns(definition, families, models)
|
|
const previous = definitions.get(definition.name)
|
|
if (source === 'project' && previous?.source === 'builtin' && !definition.overlays) replaced.push({ name: definition.name, path: file.path, source })
|
|
definitions.set(definition.name, { ...definition, source: definition.overlays ? previous!.source : source })
|
|
} catch (error) { errors.push({ name: file.path.split('/').at(-1)!.slice(0, -3), path: file.path, source, error: String(error) }) }
|
|
}
|
|
}
|
|
return { definitions: [...definitions.values()].map(definition => ({ ...definition, runs: definitionRuns(definition, families, models) })), errors, replaced }
|
|
}
|
|
/** Tool denials also apply to inherited tools. Inputs stay unchanged. */
|
|
export function toolsFor(definition: Definition, parent: readonly string[]): string[] {
|
|
return [...new Set([...(definition.tools ?? parent), ...(definition.addTools ?? [])])].filter(tool => !definition.denyTools?.includes(tool))
|
|
}
|