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
/** Token-aware schema summarization and drill-down utilities for the exec tool. */

// 12k tokens × 4 chars/token
export const TOKEN_CHAR_LIMIT = 4 * 12_000

type JSONSchema = Record<string, unknown>

/**
 * Scalar constraints copied through from the JSON Schema as-is. Without them an
 * agent in exec mode learns a string cap only from the rejection after it sent
 * too much.
 */
interface ScalarConstraints {
    minLength?: number
    maxLength?: number
    minimum?: number
    maximum?: number
    exclusiveMinimum?: number
    exclusiveMaximum?: number
    pattern?: string
    format?: string
}

interface SummarizedProperty extends ScalarConstraints {
    type?: string
    description?: string
    enum?: unknown[]
    default?: unknown
    const?: unknown
    required?: boolean
    fields?: string[]
    items?: string
    hint?: string
}

/**
 * A summarized schema node. `properties` is always present (empty for non-object
 * nodes) so callers can read it unconditionally; `items` (arrays) and `variants`
 * (unions) carry the recursive shape that the old object-only summarizer dropped.
 */
interface NodeSummary extends ScalarConstraints {
    type: string
    title?: string
    required?: string[]
    requiredWhenSet?: Record<string, string[]>
    properties: Record<string, SummarizedProperty>
    items?: NodeSummary
    variants?: NodeSummary[]
    description?: string
    enum?: unknown[]
    const?: unknown
    default?: unknown
}

const NUMERIC_CONSTRAINT_KEYS = [
    'minLength',
    'maxLength',
    'minimum',
    'maximum',
    'exclusiveMinimum',
    'exclusiveMaximum',
] as const satisfies readonly (keyof ScalarConstraints)[]
const STRING_CONSTRAINT_KEYS = ['pattern', 'format'] as const satisfies readonly (keyof ScalarConstraints)[]

/**
 * A `pattern` longer than this is a generated regex (zod's ISO date-time pattern is
 * 310 characters) that an agent cannot act on; its `format` says the same in a word.
 * Copying every one would grow the catalogue's summaries by about 6%.
 */
const MAX_PATTERN_CHARS = 80

function copyConstraints(from: JSONSchema, to: ScalarConstraints): void {
    for (const key of NUMERIC_CONSTRAINT_KEYS) {
        const value = from[key]
        if (typeof value === 'number') {
            to[key] = value
        }
    }
    for (const key of STRING_CONSTRAINT_KEYS) {
        const value = from[key]
        if (typeof value !== 'string') {
            continue
        }
        if (key === 'pattern' && (typeof from.format === 'string' || value.length > MAX_PATTERN_CHARS)) {
            continue
        }
        to[key] = value
    }
}

/**
 * zod renders `.nullable()` as `anyOf: [variant, {type: 'null'}]` and puts the
 * field's `description` and `default` on that wrapper, not on the variant. Whoever
 * collapses the wrapper to its variant has to carry those two across or the summary
 * loses them.
 */
function carryWrapperMetadata(wrapper: JSONSchema, variant: JSONSchema): JSONSchema {
    return {
        ...variant,
        ...(wrapper.description !== undefined ? { description: wrapper.description } : {}),
        ...(wrapper.default !== undefined ? { default: wrapper.default } : {}),
    }
}

/**
 * A nullable field (`anyOf: [{type: 'string', maxLength: 3000}, {type: 'null'}]`) is
 * its one non-null variant for the caller's purposes. Returns that variant, with the
 * wrapper's description and default, so its type, enum, constraints, fields and
 * drill-down hint are summarized instead of the union wrapper, which carried none of
 * them. Anything else comes back unchanged.
 */
function unwrapNullable(schema: JSONSchema): JSONSchema {
    const variants = (schema.anyOf || schema.oneOf) as JSONSchema[] | undefined
    if (!variants) {
        return schema
    }
    const nonNull = variants.filter((v) => v.type !== 'null')
    if (nonNull.length !== 1) {
        return schema
    }
    return carryWrapperMetadata(schema, nonNull[0]!)
}

/**
 * Properties that conventionally discriminate a union variant. Zod discriminated
 * unions (e.g. the trends `series` EventsNode/ActionsNode/GroupNode split) carry the
 * variant identity in one of these as a `const`/single-value `enum`, not in `title`.
 */
const DISCRIMINATOR_KEYS = ['kind', 'type', 'nodeKind'] as const

/** Best-effort human label for a union variant: `title`, a root `const`, or a discriminator property's `const`/single-value `enum`. */
function variantName(variant: JSONSchema): string | undefined {
    if (typeof variant.title === 'string') {
        return variant.title
    }
    if (typeof variant.const === 'string') {
        return variant.const
    }
    const props = variant.properties as Record<string, JSONSchema> | undefined
    if (!props) {
        return undefined
    }
    for (const key of DISCRIMINATOR_KEYS) {
        const disc = props[key]
        if (!disc) {
            continue
        }
        if (typeof disc.const === 'string') {
            return disc.const
        }
        if (Array.isArray(disc.enum) && disc.enum.length === 1 && typeof disc.enum[0] === 'string') {
            return disc.enum[0]
        }
    }
    return undefined
}

/**
 * Describe the type of a union (anyOf/oneOf) concisely.
 * Names variants via `variantName` (title, root const, or discriminator const).
 */
function describeUnion(variants: JSONSchema[]): string {
    const names = variants.map(variantName).filter((n): n is string => typeof n === 'string')
    if (names.length > 0 && names.length <= 6) {
        return `union of ${variants.length} types (${names.join(', ')})`
    }
    return `union of ${variants.length} types`
}

/** Get the effective type string for a schema node. */
function getTypeString(schema: JSONSchema): string {
    if (typeof schema.type === 'string') {
        return schema.type
    }
    if (Array.isArray(schema.type)) {
        return (schema.type as string[]).filter((t) => t !== 'null').join(' | ')
    }
    if (schema.anyOf || schema.oneOf) {
        const variants = (schema.anyOf || schema.oneOf) as JSONSchema[]
        // Filter out null types for optional unions
        const nonNull = variants.filter((v) => v.type !== 'null')
        if (nonNull.length === 0) {
            return 'null'
        }
        return describeUnion(nonNull)
    }
    if (schema.const !== undefined) {
        return 'const'
    }
    return 'unknown'
}

/** Check if a property has complex nested structure that needs drill-down. */
function isComplex(schema: JSONSchema): boolean {
    if (schema.type === 'object' && schema.properties) {
        return true
    }
    if (schema.type === 'array' && schema.items) {
        const items = schema.items as JSONSchema
        if (items.type === 'object' && items.properties) {
            return true
        }
        if (items.anyOf || items.oneOf) {
            return true
        }
    }
    if (schema.anyOf || schema.oneOf) {
        const variants = (schema.anyOf || schema.oneOf) as JSONSchema[]
        const nonNull = variants.filter((v) => v.type !== 'null')
        // Simple nullable scalar is not complex
        if (nonNull.length <= 1 && nonNull.every((v) => typeof v.type === 'string' && v.type !== 'object')) {
            return false
        }
        return nonNull.length > 1 || nonNull.some((v) => v.type === 'object' || v.type === 'array')
    }
    return false
}

/** Describe array items concisely. */
function describeItems(items: JSONSchema): string {
    if (items.anyOf || items.oneOf) {
        const variants = (items.anyOf || items.oneOf) as JSONSchema[]
        return describeUnion(variants.filter((v) => v.type !== 'null'))
    }
    if (items.type === 'object') {
        const propNames = items.properties ? Object.keys(items.properties as Record<string, unknown>) : []
        if (propNames.length > 0) {
            return `object with ${propNames.length} fields`
        }
        return 'object'
    }
    return getTypeString(items)
}

// Defensive recursion bound for `summarizeNode`. Zod's `toJSONSchema` inlines, so
// schemas are finite trees, but array/union unwrapping recurses — cap it anyway.
const MAX_SUMMARY_DEPTH = 6

/** A tool-level control the executor strips before dispatch, so it doesn't count
 *  as one of the tool's own parameters when deciding whether a field is the sole
 *  wrapper. */
const TOOL_CONTROL_PROPERTIES = new Set(['output_format'])

/**
 * Whether a field is the wrapper a tool's whole payload sits under — the single
 * required top-level object on `query-logs`, `query-apm-spans`, `read-data-schema`
 * and their siblings.
 *
 * Callers flatten these: they send `{dateRange, limit}` where `{query: {dateRange,
 * limit}}` was wanted, because the fields they know about are the nested ones and
 * the drill-down hint alone never says the wrapper is mandatory. Naming it on the
 * field keeps the nesting in the summarized schema, which is all a caller sees once
 * the full schema overflows the token budget.
 *
 * Being the tool's ONLY parameter is what makes "everything goes inside it" true.
 * A required object sitting beside other top-level fields — `query-retention`'s
 * `retentionFilter`, `view-create`'s `query` next to `name` — is a component of the
 * payload, not the envelope, and saying otherwise would flatten calls that were
 * already correct.
 */
function isPayloadWrapper(
    name: string,
    prop: JSONSchema,
    schema: JSONSchema,
    requiredFields: readonly string[],
    fieldPath: string | undefined
): boolean {
    // Nested paths describe a field the caller already reached through the wrapper.
    if (fieldPath !== undefined || !requiredFields.includes(name)) {
        return false
    }
    const siblings = Object.keys((schema.properties || {}) as Record<string, unknown>).filter(
        (field) => field !== name && !TOOL_CONTROL_PROPERTIES.has(field)
    )
    if (siblings.length > 0) {
        return false
    }
    if (prop.type === 'object' && prop.properties) {
        return true
    }
    // A wrapper keyed by a discriminator (`read-data-schema`'s `query`) arrives as a
    // union of object variants, and gets flattened just as often.
    const variants = (prop.anyOf || prop.oneOf) as JSONSchema[] | undefined
    const nonNull = variants?.filter((variant) => variant.type !== 'null') ?? []
    return nonNull.length > 0 && nonNull.every((variant) => variant.type === 'object' && !!variant.properties)
}

/**
 * Summarize an object's top-level properties: field names, types, descriptions,
 * and drill-down hints for complex fields. Intentionally does NOT recurse into a
 * nested object/array/union field — each complex field instead carries a `hint`
 * pointing at the next `schema <tool> <path>` call.
 */
function summarizeObject(schema: JSONSchema, toolName: string, fieldPath?: string): NodeSummary {
    const properties = (schema.properties || {}) as Record<string, JSONSchema>
    const requiredFields = (schema.required || []) as string[]
    const result: Record<string, SummarizedProperty> = {}
    const pathPrefix = fieldPath ? `${fieldPath}.` : ''

    for (const [name, rawProp] of Object.entries(properties)) {
        const prop = unwrapNullable(rawProp)
        const entry: SummarizedProperty = {}
        entry.type = getTypeString(prop)

        if (typeof prop.description === 'string') {
            entry.description = prop.description
        }
        if (prop.enum) {
            entry.enum = prop.enum as unknown[]
        }
        if (prop.default !== undefined) {
            entry.default = prop.default
        }
        if (prop.const !== undefined) {
            entry.const = prop.const
        }
        copyConstraints(prop, entry)
        if (requiredFields.includes(name)) {
            entry.required = true
        }

        // For objects, list subfield names
        if (prop.type === 'object' && prop.properties) {
            entry.fields = Object.keys(prop.properties as Record<string, unknown>)
        }

        // For arrays, describe items
        if (prop.type === 'array' && prop.items) {
            entry.items = describeItems(prop.items as JSONSchema)
        }

        // Add drill-down hint for complex fields. Phrased as an imperative, not a
        // description — models observably treat declarative notes as advisory, so
        // the directive lives on the field the model is about to populate.
        if (isComplex(prop)) {
            entry.hint = `DO NOT GUESS — you MUST run \`schema ${toolName} ${pathPrefix}${name}\` before populating this field`
            if (isPayloadWrapper(name, prop, schema, requiredFields, fieldPath)) {
                entry.hint += `. Every parameter goes inside it — send {"${name}": {...}}, not the fields at the top level`
            }
        }

        result[name] = entry
    }

    const summary: NodeSummary = {
        type: (schema.type as string) || 'object',
        ...(requiredFields.length > 0 ? { required: requiredFields } : {}),
        // Before `properties`, so a caller whose output gets cut off still sees the conditional rule.
        ...(schema['x-required-when-set']
            ? { requiredWhenSet: schema['x-required-when-set'] as Record<string, string[]> }
            : {}),
        properties: result,
    }
    if (typeof schema.title === 'string') {
        summary.title = schema.title
    }
    return summary
}

/** Summarize a scalar/leaf node — its descriptive metadata only, no children. */
function summarizeLeaf(schema: JSONSchema): NodeSummary {
    const summary: NodeSummary = { type: getTypeString(schema), properties: {} }
    if (typeof schema.title === 'string') {
        summary.title = schema.title
    }
    if (typeof schema.description === 'string') {
        summary.description = schema.description
    }
    if (schema.enum) {
        summary.enum = schema.enum as unknown[]
    }
    if (schema.const !== undefined) {
        summary.const = schema.const
    }
    if (schema.default !== undefined) {
        summary.default = schema.default
    }
    copyConstraints(schema, summary)
    return summary
}

/**
 * Summarize any schema node, dispatching on its kind.
 *
 * Array and union WRAPPERS recurse, unlike the per-field summary inside an object
 * (which stops at one level and emits a `hint`). The reason: `items` and union
 * variants don't consume a path segment — `resolveSchemaPath` walks through them
 * transparently (`series.event` reaches into `series`'s array-of-union items) — so
 * a faithful summary has to unwrap them until it reaches the object/scalar beneath.
 * Without this, summarizing an array- or union-typed field that overflows the inline
 * budget (e.g. `query-trends series`) collapsed to an empty `{ type, properties: {} }`
 * and the variant shapes were invisible.
 */
function summarizeNode(
    schema: JSONSchema,
    toolName: string,
    fieldPath: string | undefined,
    depth: number
): NodeSummary {
    // Union: summarize each non-null variant. A lone non-null variant (a nullable
    // wrapper) collapses to that variant so we don't emit a pointless 1-way union.
    const unionVariants = (schema.anyOf || schema.oneOf) as JSONSchema[] | undefined
    if (unionVariants) {
        const nonNull = unionVariants.filter((v) => v.type !== 'null')
        if (nonNull.length === 0) {
            return { type: 'null', properties: {} }
        }
        if (depth >= MAX_SUMMARY_DEPTH) {
            return { type: getTypeString(schema), properties: {} }
        }
        if (nonNull.length === 1) {
            // Unwrap a nullable wrapper, keeping its description and default. Count it
            // against `depth` so a pathological chain of nested nullable unions still
            // terminates at MAX_SUMMARY_DEPTH.
            return summarizeNode(carryWrapperMetadata(schema, nonNull[0]!), toolName, fieldPath, depth + 1)
        }
        return {
            type: getTypeString(schema),
            properties: {},
            variants: nonNull.map((v) => summarizeNode(v, toolName, fieldPath, depth + 1)),
        }
    }

    // Array: summarize the item schema (which itself may be an object or a union).
    if (schema.type === 'array' && schema.items && !Array.isArray(schema.items)) {
        const items = schema.items as JSONSchema
        if (depth >= MAX_SUMMARY_DEPTH) {
            return { type: 'array', properties: {}, items: { type: describeItems(items), properties: {} } }
        }
        return { type: 'array', properties: {}, items: summarizeNode(items, toolName, fieldPath, depth + 1) }
    }

    // Object with properties: list field names + drill-down hints (one level deep).
    if (schema.properties) {
        return summarizeObject(schema, toolName, fieldPath)
    }

    // A property-less object keeps the historical empty shape; anything else is a leaf.
    if (schema.type === 'object') {
        return { type: 'object', properties: {} }
    }
    return summarizeLeaf(schema)
}

/**
 * Summarize a JSON Schema for the `info` / `schema` exec commands.
 *
 * Objects list their top-level properties with drill-down hints; arrays and unions
 * recurse through the wrapper into the underlying item/variant shapes, so the result
 * is never an empty `{ type, properties: {} }`.
 */
export function summarizeSchema(schema: JSONSchema, toolName: string, fieldPath?: string): NodeSummary {
    return summarizeNode(schema, toolName, fieldPath, 0)
}

/**
 * JSON Schema composition keywords that fan out into more sub-schemas.
 * A named child may live under any of these; resolution walks them transparently.
 */
const COMPOSITION_KEYS = ['allOf', 'anyOf', 'oneOf'] as const

function getVariants(node: JSONSchema, key: (typeof COMPOSITION_KEYS)[number]): JSONSchema[] | undefined {
    const value = node[key]
    return Array.isArray(value) ? (value as JSONSchema[]) : undefined
}

/**
 * Find a named child of a schema node, regardless of how the schema composes it.
 *
 * Walks `properties`, every composition keyword (`allOf`/`anyOf`/`oneOf`), and `items`
 * recursively — so `series.event` works whether `event` lives on `items.properties`,
 * `items.anyOf[i].properties`, `items.allOf[i].properties`, or any nested combination.
 *
 * First match wins. `seen` blocks pathological cycles if schemas ever carry self-refs
 * (Zod's `toJSONSchema` inlines, so this is defensive).
 */
function findNamedChild(node: JSONSchema, name: string, seen: WeakSet<JSONSchema> = new WeakSet()): JSONSchema | null {
    if (seen.has(node)) {
        return null
    }
    seen.add(node)

    if (node.properties) {
        const direct = (node.properties as Record<string, JSONSchema>)[name]
        if (direct) {
            return direct
        }
    }

    for (const key of COMPOSITION_KEYS) {
        const variants = getVariants(node, key)
        if (!variants) {
            continue
        }
        for (const variant of variants) {
            const hit = findNamedChild(variant, name, seen)
            if (hit) {
                return hit
            }
        }
    }

    // Array children are whatever `items` exposes — recurse transparently.
    // Tuple form (`items: [...]`) is ignored; Zod doesn't produce it and it would need
    // index-specific handling anyway.
    if (node.items && !Array.isArray(node.items)) {
        const hit = findNamedChild(node.items as JSONSchema, name, seen)
        if (hit) {
            return hit
        }
    }

    return null
}

/**
 * Resolve a numeric index: descend into array items or pick a union variant by position.
 * Arrays take precedence (all items share the same schema, so index 0/N returns the
 * same items wrapper); for unions, `0` picks the first variant, `1` the second, etc.
 */
function findIndexedChild(node: JSONSchema, idx: number): JSONSchema | null {
    if (node.items && !Array.isArray(node.items)) {
        return node.items as JSONSchema
    }
    for (const key of COMPOSITION_KEYS) {
        const variants = getVariants(node, key)
        if (variants && variants[idx]) {
            return variants[idx] as JSONSchema
        }
    }
    return null
}

/**
 * Collect every named child reachable from a node by walking composition keywords.
 * Dedupes across variants.
 */
function collectNamedChildren(
    node: JSONSchema,
    into: Set<string> = new Set(),
    seen: WeakSet<JSONSchema> = new WeakSet()
): Set<string> {
    if (seen.has(node)) {
        return into
    }
    seen.add(node)

    if (node.properties) {
        for (const k of Object.keys(node.properties as Record<string, unknown>)) {
            into.add(k)
        }
    }
    for (const key of COMPOSITION_KEYS) {
        const variants = getVariants(node, key)
        if (!variants) {
            continue
        }
        for (const variant of variants) {
            collectNamedChildren(variant, into, seen)
        }
    }
    return into
}

/**
 * Resolve a dot-separated path within a JSON Schema.
 * Returns the sub-schema at that path, or null if invalid.
 */
export function resolveSchemaPath(schema: JSONSchema, dotPath: string): JSONSchema | null {
    let current: JSONSchema = schema
    for (const segment of dotPath.split('.')) {
        const isNumeric = /^\d+$/.test(segment)
        const next = isNumeric
            ? (findIndexedChild(current, parseInt(segment, 10)) ?? findNamedChild(current, segment))
            : findNamedChild(current, segment)
        if (!next) {
            return null
        }
        current = next
    }
    return current
}

/**
 * List available child paths from a schema node.
 * Emits:
 *   - every named child reachable through any composition keyword (direct or nested)
 *   - `[items].<name>` for array-of-object/array-of-union items (via composition walk)
 *   - numeric variant labels when the node itself is a union
 */
export function listAvailablePaths(schema: JSONSchema): string[] {
    const paths: string[] = []

    // Named children at this level (covers properties + allOf/anyOf/oneOf at any nesting).
    for (const k of collectNamedChildren(schema)) {
        paths.push(k)
    }

    // Array item children, surfaced under `[items].<name>` so callers know they're
    // indexing through an array.
    if (schema.type === 'array' && schema.items && !Array.isArray(schema.items)) {
        const itemChildren = collectNamedChildren(schema.items as JSONSchema)
        for (const k of itemChildren) {
            paths.push(`[items].${k}`)
        }
    }

    // If the node is itself a union, expose variant indices so callers can pick by position.
    for (const key of COMPOSITION_KEYS) {
        const variants = getVariants(schema, key)
        if (!variants || key === 'allOf') {
            continue
        }
        for (let i = 0; i < variants.length; i++) {
            const v = variants[i]!
            const label = typeof v.title === 'string' ? `${i} (${v.title})` : `${i}`
            paths.push(label)
        }
    }

    return paths
}