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.

3.0 KB
Raw Blame
#!/usr/bin/env node
/**
 * Summarizes what a PR changes for agents: tools added or removed, top-level params,
 * scopes, annotations and input schema size. Reads the tool schema snapshots and the
 * tool definitions JSON from two checkouts.
 *
 * The base side comes from `git archive <base-ref>`, so no second checkout or build runs.
 * Prints markdown to stdout, and nothing when a comparison ran and found no change.
 * Exit codes: 0 = compared (stdout may be empty), 3 = comparison unavailable (a side lacks
 * the snapshots, or reading failed; reason on stderr, stdout empty), anything else = crash.
 * Callers must not read empty output as "no change" unless the exit code is 0.
 *
 * Usage:
 *   node services/mcp/scripts/agent-api-diff.ts [--base-ref HEAD^1] [--base-dir <dir>]
 */
import { spawnSync } from 'node:child_process'
import * as fs from 'node:fs'
import * as os from 'node:os'
import * as path from 'node:path'
import { parseArgs } from 'node:util'

import { diffToolSurfaces, loadToolSurface, renderAgentApiDiff } from './lib/agent-api-diff.ts'

const REPO_ROOT = path.resolve(import.meta.dirname, '../../..')
const TRACKED_PATHS = ['services/mcp/schema', 'services/mcp/tests/unit/__snapshots__/tool-schemas']

const EXIT_UNAVAILABLE = 3

function extractBaseRef(baseRef: string, target: string): string | null {
    // A commit-root archive prefetches unrelated blobs in a partial clone, even with a path filter.
    for (const trackedPath of TRACKED_PATHS) {
        const archive = spawnSync('git', ['archive', `--prefix=${trackedPath}/`, `${baseRef}:${trackedPath}`], {
            cwd: REPO_ROOT,
            maxBuffer: 256 * 1024 * 1024,
        })
        if (archive.status !== 0) {
            console.warn(`Could not read ${baseRef}: ${archive.stderr?.toString().trim()}`)
            return null
        }
        const untar = spawnSync('tar', ['-x', '-C', target], { input: archive.stdout })
        if (untar.status !== 0) {
            console.warn(`Could not unpack ${baseRef}: ${untar.stderr?.toString().trim()}`)
            return null
        }
    }
    return target
}

function main(): void {
    const { values } = parseArgs({
        options: { 'base-ref': { type: 'string', default: 'HEAD^1' }, 'base-dir': { type: 'string' } },
    })
    const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-api-base-'))
    try {
        const baseDir = values['base-dir'] ?? extractBaseRef(values['base-ref'] as string, scratch)
        const base = baseDir ? loadToolSurface(baseDir) : null
        const head = loadToolSurface(REPO_ROOT)
        if (!base || !head) {
            console.warn('Tool schema snapshots or definitions are missing on one side, so there is no agent API diff.')
            process.exitCode = EXIT_UNAVAILABLE
            return
        }
        process.stdout.write(renderAgentApiDiff(diffToolSurfaces(base, head)))
    } catch (error) {
        console.warn(`Could not compare tool surfaces: ${error}`)
        process.exitCode = EXIT_UNAVAILABLE
    } finally {
        fs.rmSync(scratch, { recursive: true, force: true })
    }
}

main()