Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

22.4 KB
Raw Blame
import type { ProjectSkillCatalog, ProjectSkillList } from '@/skills/project-skill-catalog'
import {
    fitLearnOutput,
    formatLearnSearchResults,
    type LearnSearchResult,
    MAX_GLOBAL_SKILLS,
    type SkillCatalog,
} from '@/skills/skill-catalog'

// Syntax line for the `learn` verb, appended to the command reference on hosts
// that receive a learn catalog. Shared with scripts/generate-exec-docs.ts so the
// published docs can't drift from the runtime declaration.
export const LEARN_COMMAND_LINE = 'learn <topic...> - load one or more learning topics\n'

export interface ExecLearnGuide {
    id: string
    title: string
    description: string
    content: string
}

export type ExecLearnGuideSummary = Omit<ExecLearnGuide, 'content'>

/** A skill source is down or not configured — an operational condition, not an agent mistake. */
export class SkillsUnavailableError extends Error {
    constructor(message: string) {
        super(message)
        this.name = 'SkillsUnavailableError'
    }
}

const SKILL_COMMANDS = [
    'learn skills',
    'learn -s "<up to 8 keywords>"',
    'learn -d <source>:<skill> [...]',
    'learn posthog:<skill> [path]',
    'learn project:<skill> [path]',
    'learn <source>:<skill> <path> [path...]',
    'learn <source>:<skill> [<source>:<skill>...]',
    'learn <source>:<skill> <path> -s "<up to 8 keywords>"',
    'learn <source>:<skill> <path> --lines <start>:<end>',
] as const
const MAX_SEARCH_QUERY_LENGTH = 200
const POSTHOG_SKILL_LIST_LIMIT = 300
// Bounds on batch fan-out to keep worst-case project-side API calls per command in check.
const MAX_DESCRIBE_SKILLS = 20
const MAX_BATCH_READS = 10
// Above this total, the zero-hit recovery links to `learn skills` instead of inlining every name.
const ZERO_HIT_INLINE_LIMIT = 25
export const QUALIFIED_IDENTIFIER = /^(posthog|project):/
// A path that itself starts with `posthog:`/`project:` parses as a multi-skill read, not a file read.
const SKILL_READ_USAGE =
    'Usage: learn <source>:<skill> [path...], learn <source>:<skill> <path> -s <query>, or learn <source>:<skill> <path> --lines <start>:<end>. Reads with several qualified names load several skills.'

type SkillSource = 'posthog' | 'project'

interface QualifiedSkill {
    source: SkillSource
    name: string
    identifier: string
}

interface ExecLearnSkillSources {
    posthog: SkillCatalog | undefined
    project?: ProjectSkillCatalog
    projectUnavailableReason?: string
}

/** A successful skill content read — the consumption signal behind `llma skill invoked`. */
export interface SkillInvocation {
    source: SkillSource
    skill: string
    path?: string
    readKind: 'skill' | 'file' | 'file_search' | 'file_lines'
}

/** Combines small bundled guides with PostHog and current-project skills. */
export class ExecLearnCatalog {
    private readonly guidesById: Map<string, ExecLearnGuide>

    constructor(
        guides: readonly ExecLearnGuide[],
        private readonly skillSources?: ExecLearnSkillSources,
        private readonly onSkillInvoked?: (invocation: SkillInvocation) => void
    ) {
        this.guidesById = new Map()
        for (const guide of guides) {
            if (guide.id === 'skills' || guide.id.startsWith('-')) {
                throw new Error(`Reserved exec learn guide ID: "${guide.id}"`)
            }
            if (this.guidesById.has(guide.id)) {
                throw new Error(`Duplicate exec learn guide ID: "${guide.id}"`)
            }
            this.guidesById.set(guide.id, guide)
        }
    }

    async execute(input: string): Promise<string> {
        const rest = input.trim()
        if (!rest) {
            const result: Record<string, unknown> = {
                guides: this.listGuides(),
            }
            if (this.skillSources) {
                result.skills = {
                    posthogAvailable: this.skillSources.posthog !== undefined,
                    projectAvailable: this.skillSources.project !== undefined,
                    commands: SKILL_COMMANDS,
                }
            }
            return JSON.stringify(result)
        }

        const tokens = tokenizeLearnInput(rest)
        const isSkillRequest =
            tokens[0] === 'skills' || tokens[0] === '-s' || tokens[0] === '-d' || tokens[0]!.includes(':')
        if (!this.skillSources && isSkillRequest) {
            return JSON.stringify({
                available: false,
                reason: 'Skill discovery is not enabled for this connection.',
            })
        }

        if (tokens.length === 1 && tokens[0] === 'skills') {
            return await this.listSkills()
        }

        if (tokens[0] === '-s') {
            const query = tokens.slice(1).join(' ')
            this.validateSearchQuery(query, 'learn -s "<task keywords>"')
            return await this.searchSkills(query)
        }

        if (tokens[0] === '-d') {
            return await this.describeSkills(tokens.slice(1))
        }

        if (!tokens[0]!.includes(':')) {
            return this.readGuides(tokens)
        }

        // Every token a qualified identifier → read several skills in one command.
        if (tokens.length > 1 && tokens.every((token) => QUALIFIED_IDENTIFIER.test(token))) {
            return await this.batchReadSkills(tokens)
        }

        const [identifier, ...args] = tokens
        const skill = parseQualifiedSkill(identifier!)
        if (args.length === 0) {
            return await this.readSkill(skill)
        }
        const flagIndex = args.findIndex((token) => token === '-s' || token === '--lines')
        const paths = flagIndex === -1 ? args : args.slice(0, flagIndex)
        if (paths.includes('--file')) {
            throw new Error(
                '`learn` does not support --file. Pass the file path directly: `learn <source>:<skill> <path>`.'
            )
        }

        if (flagIndex === -1) {
            if (args.length === 1) {
                return await this.readSkill(skill, args[0])
            }
            return await this.batchReadFiles(skill, args)
        }

        if (paths.length !== 1) {
            throw new Error(SKILL_READ_USAGE)
        }
        const path = paths[0]!
        const flag = args[flagIndex]
        const flagArgs = args.slice(flagIndex + 1)
        if (flag === '-s') {
            const query = flagArgs.join(' ')
            this.validateSearchQuery(query, 'learn <source>:<skill> <path> -s "<keywords>"')
            return await this.searchSkillFile(skill, path, query)
        }
        if (flag === '--lines' && flagArgs.length === 1) {
            const range = flagArgs[0]!.match(/^(\d+):(\d+)$/)
            if (!range) {
                throw new Error('Usage: learn <source>:<skill> <path> --lines <start>:<end>')
            }
            return await this.readSkillLines(skill, path, Number(range[1]), Number(range[2]))
        }
        throw new Error(SKILL_READ_USAGE)
    }

    private async batchReadSkills(identifiers: string[]): Promise<string> {
        if (identifiers.length > MAX_BATCH_READS) {
            throw new Error(`learn reads at most ${MAX_BATCH_READS} skills at once. Split the batch.`)
        }
        const skills = identifiers.map((identifier) => parseQualifiedSkill(identifier))
        // Fetch all before reporting any: a mid-batch failure rejects the whole
        // command, so no already-read sibling should fire an invocation.
        const reads = await Promise.all(skills.map((skill) => this.readSkillContent(skill)))
        for (const read of reads) {
            this.reportInvocation(read.invocation)
        }
        return fitLearnOutput(reads.map((read) => read.content).join('\n\n'))
    }

    private async batchReadFiles(skill: QualifiedSkill, paths: string[]): Promise<string> {
        if (paths.length > MAX_BATCH_READS) {
            throw new Error(`learn reads at most ${MAX_BATCH_READS} files at once. Split the batch.`)
        }
        // See batchReadSkills: report only after every read resolves.
        const reads = await Promise.all(paths.map((path) => this.readSkillContent(skill, path)))
        for (const read of reads) {
            this.reportInvocation(read.invocation)
        }
        return fitLearnOutput(reads.map((read) => read.content).join('\n\n'))
    }

    private async describeSkills(identifiers: string[]): Promise<string> {
        if (identifiers.length === 0) {
            throw new Error('Usage: learn -d <source>:<skill> [<source>:<skill>...]')
        }
        if (identifiers.length > MAX_DESCRIBE_SKILLS) {
            throw new Error(`learn -d describes at most ${MAX_DESCRIBE_SKILLS} skills at once. Split the batch.`)
        }

        const parsed = identifiers.map((identifier) => ({ identifier, skill: tryParseQualifiedSkill(identifier) }))
        let projectDescriptions: Map<string, string> | undefined
        let projectUnavailable: string | undefined
        const projectNames = parsed.filter(({ skill }) => skill?.source === 'project').map(({ skill }) => skill!.name)
        if (projectNames.length > 0) {
            if (!this.skillSources?.project) {
                projectUnavailable = this.requireProjectUnavailableReason()
            } else {
                try {
                    // Resolves names past a truncated listing via the exact-name endpoint, so a real
                    // skill beyond the list cap isn't misreported as unknown.
                    projectDescriptions = await this.skillSources.project.describe(projectNames)
                } catch (error) {
                    projectUnavailable = formatProjectError(error)
                }
            }
        }

        const lines = parsed.map(({ identifier, skill }) => {
            if (!skill) {
                return `[unknown skill: ${identifier}]`
            }
            if (skill.source === 'posthog') {
                if (!this.skillSources?.posthog) {
                    return '[posthog skills unavailable: PostHog skills are temporarily unavailable.]'
                }
                const description = this.skillSources.posthog.describe(skill.name)
                return description !== undefined
                    ? `posthog:${skill.name}: ${description}`
                    : `[unknown skill: ${identifier}]`
            }
            if (projectUnavailable !== undefined) {
                return `[project skills unavailable: ${projectUnavailable}]`
            }
            const description = projectDescriptions?.get(skill.name)
            return description !== undefined
                ? `project:${skill.name}: ${description}`
                : `[unknown skill: ${identifier}]`
        })
        return fitLearnOutput(lines.join('\n'))
    }

    private async listSkills(): Promise<string> {
        const allPosthogNames = this.skillSources?.posthog?.listNames() ?? []
        const posthogNames = allPosthogNames.slice(0, POSTHOG_SKILL_LIST_LIMIT).map((name) => `posthog:${name}`)
        let project:
            | { available: true; count: number; listed: number; truncated: boolean; skills: string[] }
            | { available: false; reason: string }

        if (!this.skillSources?.project) {
            project = { available: false, reason: this.requireProjectUnavailableReason() }
        } else {
            try {
                const result = await this.skillSources.project.listNames()
                project = {
                    available: true,
                    count: result.count,
                    listed: result.names.length,
                    truncated: result.truncated,
                    skills: result.names.map((name) => `project:${name}`),
                }
            } catch (error) {
                project = { available: false, reason: formatProjectError(error) }
            }
        }

        return fitLearnOutput(
            JSON.stringify({
                posthog: {
                    available: this.skillSources?.posthog !== undefined,
                    count: allPosthogNames.length,
                    listed: posthogNames.length,
                    truncated: posthogNames.length < allPosthogNames.length,
                    skills: posthogNames,
                },
                project,
            })
        )
    }

    private async searchSkills(query: string): Promise<string> {
        const results: LearnSearchResult[] = this.skillSources?.posthog?.searchResults(query, 'posthog:') ?? []
        const warnings: string[] = []
        if (!this.skillSources?.posthog) {
            warnings.push('PostHog skills are temporarily unavailable.')
        }

        if (!this.skillSources?.project) {
            warnings.push(`Project skills unavailable: ${this.requireProjectUnavailableReason()}`)
        } else {
            try {
                results.push(...(await this.skillSources.project.searchResults(query)))
            } catch (error) {
                warnings.push(`Project skills unavailable: ${formatProjectError(error)}`)
            }
        }

        // Merge both sources by relevance so an exact project match can outrank a weak PostHog one.
        const merged = results
            .sort(
                (left, right) =>
                    (right.score ?? 0) - (left.score ?? 0) || left.identifier.localeCompare(right.identifier)
            )
            .slice(0, MAX_GLOBAL_SKILLS)
        const sections = merged.length > 0 ? formatLearnSearchResults(merged) : await this.zeroHitRecovery(query)
        return fitLearnOutput(
            warnings.length > 0 ? `${sections}\n\n${warnings.map((warning) => `[${warning}]`).join('\n')}` : sections
        )
    }

    private async zeroHitRecovery(query: string): Promise<string> {
        const projectSearched = this.skillSources?.project !== undefined
        const header =
            `No skills matched "${query}".\n` +
            (projectSearched
                ? 'None of the query words appear in any skill.'
                : 'None of the query words appear in any PostHog skill; project skills were not searched.') +
            ' Try fewer or broader keywords (single words match best).'

        const posthogNames = this.skillSources?.posthog?.listNames() ?? []
        let projectListing: ProjectSkillList | undefined
        if (this.skillSources?.project) {
            try {
                projectListing = await this.skillSources.project.listNames()
            } catch {
                // Fall through to the link form; the search-level warning already explains the failure.
            }
        }

        const projectCount = projectSearched ? projectListing?.count : 0
        if (projectCount !== undefined && posthogNames.length + projectCount <= ZERO_HIT_INLINE_LIMIT) {
            const lines = [header, '', 'Available skills:']
            if (posthogNames.length > 0) {
                lines.push(`posthog: ${posthogNames.join(', ')}`)
            }
            if (projectListing && projectListing.names.length > 0) {
                lines.push(`project: ${projectListing.names.join(', ')}`)
            }
            return lines.join('\n')
        }

        // An unset listing means the count is unknown (transient failure), not zero —
        // claiming "0 project skills" would send the agent down the no-skill path.
        const counts = projectListing
            ? `${posthogNames.length} posthog and ${projectListing.count} project skills exist`
            : projectSearched
              ? `${posthogNames.length} posthog skills exist; the project skill listing is temporarily unavailable`
              : `${posthogNames.length} posthog skills exist; project skills were not searched`
        return (
            `${header}\n\n` +
            `${counts} — ` +
            'run `learn skills` to list names, or `learn -d <source>:<skill>` to describe specific ones.'
        )
    }

    private async readSkill(skill: QualifiedSkill, path?: string): Promise<string> {
        const { content, invocation } = await this.readSkillContent(skill, path)
        this.reportInvocation(invocation)
        return content
    }

    /** Fetches skill content and builds its invocation signal without reporting it —
     *  batch reads report only after every sibling read resolves, so a mid-batch
     *  failure can't over-report the reads that already succeeded. */
    private async readSkillContent(
        skill: QualifiedSkill,
        path?: string
    ): Promise<{ content: string; invocation: SkillInvocation }> {
        const content =
            skill.source === 'posthog'
                ? this.requirePostHogSkills().read(skill.name, path, skill.identifier)
                : await this.requireProjectSkills().read(skill.name, path)
        return {
            content,
            invocation: { source: skill.source, skill: skill.name, path, readKind: path ? 'file' : 'skill' },
        }
    }

    private async searchSkillFile(skill: QualifiedSkill, path: string, query: string): Promise<string> {
        const content =
            skill.source === 'posthog'
                ? this.requirePostHogSkills().searchFile(skill.name, path, query, skill.identifier)
                : await this.requireProjectSkills().searchFile(skill.name, path, query)
        this.reportInvocation({ source: skill.source, skill: skill.name, path, readKind: 'file_search' })
        return content
    }

    private async readSkillLines(skill: QualifiedSkill, path: string, start: number, end: number): Promise<string> {
        const content =
            skill.source === 'posthog'
                ? this.requirePostHogSkills().readLines(skill.name, path, start, end, skill.identifier)
                : await this.requireProjectSkills().readLines(skill.name, path, start, end)
        this.reportInvocation({ source: skill.source, skill: skill.name, path, readKind: 'file_lines' })
        return content
    }

    /** Fires only after a successful read; a listener failure never breaks `learn`. */
    private reportInvocation(invocation: SkillInvocation): void {
        try {
            this.onSkillInvoked?.(invocation)
        } catch {
            // analytics must never break skill delivery
        }
    }

    private validateSearchQuery(query: string, usage: string): void {
        if (!query.trim()) {
            throw new Error(`Search query cannot be empty. Usage: ${usage}.`)
        }
        if (query.length > MAX_SEARCH_QUERY_LENGTH) {
            throw new Error(`Search query must be at most ${MAX_SEARCH_QUERY_LENGTH} characters.`)
        }
    }

    private listGuides(): ExecLearnGuideSummary[] {
        return [...this.guidesById.values()].map(({ content: _content, ...summary }) => summary)
    }

    private readGuides(guideIds: string[]): string {
        const uniqueGuideIds = [...new Set(guideIds)]
        const guides = uniqueGuideIds.map((guideId) => this.guidesById.get(guideId))
        const unknownGuideIds = uniqueGuideIds.filter((_, index) => guides[index] === undefined)
        if (unknownGuideIds.length > 0) {
            const available = this.listGuides()
                .map((guide) => guide.id)
                .join(', ')
            const unknown = unknownGuideIds.map((guideId) => `"${guideId}"`).join(', ')
            const availableHint = available ? ` Available: ${available}.` : ''
            const recovery = this.skillSources
                ? ' To load a skill, run `learn -s "<task keywords>"`, then `learn posthog:<skill>` or `learn project:<skill>` using the exact qualified name from the results.'
                : ' Run `learn` to list available topics.'
            throw new Error(
                `Unknown learning ${unknownGuideIds.length === 1 ? 'topic' : 'topics'}: ${unknown}.${availableHint}${recovery}`
            )
        }

        const resolvedGuides = guides.filter((guide) => guide !== undefined)
        if (resolvedGuides.length === 1) {
            return resolvedGuides[0]!.content
        }
        return resolvedGuides.map((guide) => `## ${guide.title}\n\n${guide.content}`).join('\n\n')
    }

    private requirePostHogSkills(): SkillCatalog {
        if (!this.skillSources?.posthog) {
            throw new SkillsUnavailableError(
                'PostHog skills are temporarily unavailable. Core exec commands are still available.'
            )
        }
        return this.skillSources.posthog
    }

    private requireProjectSkills(): ProjectSkillCatalog {
        if (!this.skillSources?.project) {
            throw new SkillsUnavailableError(this.requireProjectUnavailableReason())
        }
        return this.skillSources.project
    }

    private requireProjectUnavailableReason(): string {
        return this.skillSources?.projectUnavailableReason ?? 'Project skills are temporarily unavailable.'
    }
}

function parseQualifiedSkill(identifier: string): QualifiedSkill {
    const skill = tryParseQualifiedSkill(identifier)
    if (!skill) {
        throw new Error(
            `Unknown guide or unqualified skill: "${identifier}". Use \`learn posthog:<skill>\` or \`learn project:<skill>\`.`
        )
    }
    if (skill.name.includes('/')) {
        throw new Error(
            `Invalid skill identifier: "${identifier}". Separate the skill name and file path with a space: \`learn <source>:<skill> <path>\`.`
        )
    }
    return skill
}

function tryParseQualifiedSkill(identifier: string): QualifiedSkill | undefined {
    const match = identifier.match(/^(posthog|project):(.+)$/)
    if (!match?.[1] || !match[2]) {
        return undefined
    }
    return { source: match[1] as SkillSource, name: match[2], identifier }
}

export function tokenizeLearnInput(input: string): string[] {
    const tokens: string[] = []
    let token = ''
    let quote: '"' | "'" | undefined
    let escaping = false

    for (const character of input) {
        if (escaping) {
            token += character
            escaping = false
        } else if (character === '\\' && quote) {
            escaping = true
        } else if (quote) {
            if (character === quote) {
                quote = undefined
            } else {
                token += character
            }
        } else if (character === '"' || character === "'") {
            quote = character
        } else if (/\s/.test(character)) {
            if (token) {
                tokens.push(token)
                token = ''
            }
        } else {
            token += character
        }
    }

    if (quote) {
        throw new Error('Unterminated quote in learn command.')
    }
    if (escaping) {
        token += '\\'
    }
    if (token) {
        tokens.push(token)
    }
    return tokens
}

function formatProjectError(error: unknown): string {
    return error instanceof Error ? error.message.slice(0, 500) : 'Project skill request failed.'
}