: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.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
/** 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
}