: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
import { describe, expect, it } from 'vitest'
import { TOKEN_CHAR_LIMIT, listAvailablePaths, resolveSchemaPath, summarizeSchema } from '../../src/tools/schema-utils'
describe('schema-utils', () => {
describe('summarizeSchema', () => {
it('summarizes simple scalar fields without hints', () => {
const schema = {
type: 'object',
required: ['name'],
properties: {
name: { type: 'string', description: 'The name' },
count: { type: 'number', default: 10 },
status: { type: 'string', enum: ['active', 'inactive'] },
},
}
const result = summarizeSchema(schema, 'my-tool')
expect(result.type).toBe('object')
expect(result.required).toEqual(['name'])
expect(result.properties.name).toEqual({
type: 'string',
description: 'The name',
required: true,
})
expect(result.properties.count).toEqual({
type: 'number',
default: 10,
})
expect(result.properties.status).toEqual({
type: 'string',
enum: ['active', 'inactive'],
})
// No hints on simple fields
expect(result.properties.name!.hint).toBeUndefined()
expect(result.properties.count!.hint).toBeUndefined()
expect(result.properties.status!.hint).toBeUndefined()
})
it('adds hints for object fields with properties', () => {
const schema = {
type: 'object',
properties: {
filter: {
type: 'object',
description: 'Filter config',
properties: {
key: { type: 'string' },
value: { type: 'string' },
},
},
},
}
const result = summarizeSchema(schema, 'my-tool')
expect(result.properties.filter!.hint).toBe(
'DO NOT GUESS — you MUST run `schema my-tool filter` before populating this field'
)
expect(result.properties.filter!.fields).toEqual(['key', 'value'])
})
// A tool whose whole payload sits under one required object is the shape
// callers flatten. The summary is all they see once the full schema
// overflows the token budget, so the nesting has to survive into it.
describe('a sole required object parameter', () => {
const wrapperSchema = (
query: Record<string, unknown>,
siblings: Record<string, unknown> = {}
): Record<string, unknown> => ({
type: 'object',
required: ['query'],
properties: { query, ...siblings },
})
const objectQuery = { type: 'object', properties: { limit: { type: 'number' } } }
it('says every parameter goes inside it', () => {
const result = summarizeSchema(wrapperSchema(objectQuery), 'query-logs')
expect(result.properties.query!.hint).toBe(
'DO NOT GUESS — you MUST run `schema query-logs query` before populating this field. Every parameter goes inside it — send {"query": {...}}, not the fields at the top level'
)
})
it('says so for a wrapper that is a union of object variants', () => {
// `read-data-schema` keys its shape off a `kind` discriminator.
const unionQuery = {
anyOf: [
{ type: 'object', properties: { kind: { const: 'events' } } },
{ type: 'object', properties: { kind: { const: 'event_properties' } } },
],
}
expect(summarizeSchema(wrapperSchema(unionQuery), 'read-data-schema').properties.query!.hint).toContain(
'Every parameter goes inside it'
)
})
it('ignores the tool-level output_format control when counting parameters', () => {
const withControl = wrapperSchema(objectQuery, { output_format: { type: 'string' } })
expect(summarizeSchema(withControl, 'query-logs').properties.query!.hint).toContain(
'Every parameter goes inside it'
)
})
it.each([
[
'the object sits beside other top-level fields',
wrapperSchema(objectQuery, { name: { type: 'string' } }),
],
[
'the object is optional',
{ type: 'object', properties: { query: objectQuery } } as Record<string, unknown>,
],
])('stays with the bare drill-down hint when %s', (_label, schema) => {
// Saying "everything goes inside it" here would flatten calls that
// were already correct: the other top-level fields are real parameters.
const result = summarizeSchema(schema as Record<string, unknown>, 'view-create')
expect(result.properties.query!.hint).toBe(
'DO NOT GUESS — you MUST run `schema view-create query` before populating this field'
)
})
it('does not repeat the wrapper note on fields inside the wrapper', () => {
const nested = {
type: 'object',
required: ['dateRange'],
properties: { dateRange: { type: 'object', properties: { date_from: { type: 'string' } } } },
}
const result = summarizeSchema(nested, 'query-logs', 'query')
expect(result.properties.dateRange!.hint).toBe(
'DO NOT GUESS — you MUST run `schema query-logs query.dateRange` before populating this field'
)
})
})
it('adds hints for arrays with complex items', () => {
const schema = {
type: 'object',
properties: {
series: {
type: 'array',
description: 'Series list',
items: {
anyOf: [
{
type: 'object',
title: 'EventsNode',
properties: { event: { type: 'string' } },
},
{
type: 'object',
title: 'ActionsNode',
properties: { id: { type: 'number' } },
},
],
},
},
},
}
const result = summarizeSchema(schema, 'query-trends')
expect(result.properties.series!.hint).toBe(
'DO NOT GUESS — you MUST run `schema query-trends series` before populating this field'
)
expect(result.properties.series!.items).toBe('union of 2 types (EventsNode, ActionsNode)')
})
it('does not add hints for arrays with simple items', () => {
const schema = {
type: 'object',
properties: {
tags: {
type: 'array',
items: { type: 'string' },
},
},
}
const result = summarizeSchema(schema, 'my-tool')
expect(result.properties.tags!.hint).toBeUndefined()
expect(result.properties.tags!.items).toBe('string')
})
it('does not add hints for nullable scalar unions', () => {
const schema = {
type: 'object',
properties: {
name: {
anyOf: [{ type: 'string' }, { type: 'null' }],
},
},
}
const result = summarizeSchema(schema, 'my-tool')
expect(result.properties.name!.hint).toBeUndefined()
})
it('includes fieldPath in hints when provided', () => {
const schema = {
type: 'object',
properties: {
nested: {
type: 'object',
properties: {
deep: { type: 'string' },
},
},
},
}
const result = summarizeSchema(schema, 'my-tool', 'parent')
expect(result.properties.nested!.hint).toBe(
'DO NOT GUESS — you MUST run `schema my-tool parent.nested` before populating this field'
)
})
// Regression: `schema query-trends series` resolves to an array-of-union node
// that overflows the inline budget, so it gets summarized. The old summarizer
// only walked `properties`, collapsing it to `{ type: 'array', properties: {} }`
// and hiding every variant shape — forcing callers back to the prose examples.
it('summarizes an array-of-union root by recursing into the item variants', () => {
const schema = {
type: 'array',
items: {
anyOf: [
{
type: 'object',
title: 'EventsNode',
properties: { event: { type: 'string' }, math: { type: 'string' } },
},
{
type: 'object',
title: 'ActionsNode',
properties: { id: { type: 'number' } },
},
],
},
}
const result = summarizeSchema(schema, 'query-trends', 'series')
expect(result.type).toBe('array')
// Not an empty object summary anymore — the items shape is present.
expect(result.items).not.toBeUndefined()
expect(result.items!.type).toBe('union of 2 types (EventsNode, ActionsNode)')
expect(result.items!.variants).toHaveLength(2)
expect(result.items!.variants![0]!.properties.event).toEqual(expect.objectContaining({ type: 'string' }))
expect(result.items!.variants![1]!.properties.id).toEqual(expect.objectContaining({ type: 'number' }))
})
// The `series.0` numeric-step workaround resolves to the bare union node; it
// suffered the same empty-summary collapse.
it('summarizes a union root into its variants', () => {
const schema = {
anyOf: [
{ type: 'object', title: 'TypeA', properties: { a: { type: 'string' } } },
{ type: 'object', title: 'TypeB', properties: { b: { type: 'number' } } },
],
}
const result = summarizeSchema(schema, 'my-tool', 'field.0')
expect(result.type).toBe('union of 2 types (TypeA, TypeB)')
expect(result.variants).toHaveLength(2)
expect(result.variants![0]!.properties.a).toEqual(expect.objectContaining({ type: 'string' }))
})
// Array `items` and union variants don't consume a path segment, so a hint on a
// field reached through them must still point at `<field>.<name>` for the
// follow-up `schema` call to resolve.
it('threads the original field path into hints through array/union unwrapping', () => {
const schema = {
type: 'array',
items: {
anyOf: [
{
type: 'object',
properties: { props: { type: 'object', properties: { x: { type: 'string' } } } },
},
],
},
}
const result = summarizeSchema(schema, 'query-trends', 'series')
expect(result.items!.properties.props!.hint).toBe(
'DO NOT GUESS — you MUST run `schema query-trends series.props` before populating this field'
)
})
// Zod discriminated unions (e.g. trends series) put variant identity in a `kind`
// const, not a `title` — name them off that so the union header is legible.
it('names union variants by a discriminator const when no title is present', () => {
const schema = {
anyOf: [
{ type: 'object', properties: { kind: { type: 'string', const: 'EventsNode' } } },
{ type: 'object', properties: { kind: { type: 'string', enum: ['ActionsNode'] } } },
],
}
const result = summarizeSchema(schema, 'query-trends', 'series.0')
expect(result.type).toBe('union of 2 types (EventsNode, ActionsNode)')
})
it('collapses a nullable object union to the underlying object summary', () => {
const schema = {
anyOf: [{ type: 'object', properties: { a: { type: 'string' } } }, { type: 'null' }],
}
const result = summarizeSchema(schema, 'my-tool', 'maybeObj')
expect(result.type).toBe('object')
expect(result.variants).toBeUndefined()
expect(result.properties.a).toEqual(expect.objectContaining({ type: 'string' }))
})
// Nullable-wrapper unwrapping recurses; a pathological chain must terminate via
// the depth guard rather than blowing the stack on malformed input.
it('terminates on a deeply nested chain of nullable wrappers', () => {
let schema: Record<string, unknown> = { type: 'object', properties: { a: { type: 'string' } } }
for (let i = 0; i < 100; i++) {
schema = { anyOf: [schema, { type: 'null' }] }
}
expect(() => summarizeSchema(schema, 'my-tool', 'deep')).not.toThrow()
})
})
describe('resolveSchemaPath', () => {
const schema = {
type: 'object',
properties: {
name: { type: 'string' },
filter: {
type: 'object',
properties: {
key: { type: 'string' },
value: { type: 'number' },
},
},
series: {
type: 'array',
items: {
type: 'object',
properties: {
event: { type: 'string' },
math: { type: 'string', enum: ['total', 'dau'] },
},
},
},
variant: {
anyOf: [
{
type: 'object',
title: 'TypeA',
properties: { a: { type: 'string' } },
},
{
type: 'object',
title: 'TypeB',
properties: { b: { type: 'number' } },
},
],
},
},
}
it('resolves top-level properties', () => {
expect(resolveSchemaPath(schema, 'name')).toEqual({ type: 'string' })
})
it('resolves nested object properties via dot path', () => {
expect(resolveSchemaPath(schema, 'filter.key')).toEqual({
type: 'string',
})
})
it('resolves array item properties', () => {
expect(resolveSchemaPath(schema, 'series.event')).toEqual({
type: 'string',
})
})
it('resolves union variants by index', () => {
expect(resolveSchemaPath(schema, 'variant.0')).toEqual({
type: 'object',
title: 'TypeA',
properties: { a: { type: 'string' } },
})
})
it('returns null for invalid paths', () => {
expect(resolveSchemaPath(schema, 'nonexistent')).toBeNull()
expect(resolveSchemaPath(schema, 'filter.nonexistent')).toBeNull()
})
describe('array of anyOf/oneOf items', () => {
const arrayUnionSchema = {
type: 'object',
properties: {
series: {
type: 'array',
items: {
anyOf: [
{
type: 'object',
title: 'EventsNode',
properties: {
event: { type: 'string' },
math: { type: 'string', enum: ['total', 'dau'] },
},
},
{
type: 'object',
title: 'ActionsNode',
properties: {
id: { type: 'number' },
math: { type: 'string', enum: ['total'] },
},
},
],
},
},
},
}
it('resolves a named property that only exists on one variant', () => {
expect(resolveSchemaPath(arrayUnionSchema, 'series.event')).toEqual({ type: 'string' })
})
it('resolves a named property that exists on multiple variants (first match wins)', () => {
expect(resolveSchemaPath(arrayUnionSchema, 'series.math')).toEqual({
type: 'string',
enum: ['total', 'dau'],
})
})
it('still supports the numeric-first workaround (series.0.event)', () => {
expect(resolveSchemaPath(arrayUnionSchema, 'series.0.event')).toEqual({ type: 'string' })
expect(resolveSchemaPath(arrayUnionSchema, 'series.1.id')).toEqual({ type: 'number' })
})
it('returns null when the property exists on no variant', () => {
expect(resolveSchemaPath(arrayUnionSchema, 'series.nonexistent')).toBeNull()
})
it('supports oneOf in addition to anyOf', () => {
const oneOfSchema = {
type: 'object',
properties: {
items: {
type: 'array',
items: {
oneOf: [{ type: 'object', properties: { foo: { type: 'string' } } }],
},
},
},
}
expect(resolveSchemaPath(oneOfSchema, 'items.foo')).toEqual({ type: 'string' })
})
})
describe('composition walking (allOf + nesting)', () => {
it('resolves a property defined via allOf (base + extension)', () => {
const schema = {
type: 'object',
properties: {
filter: {
allOf: [
{ type: 'object', properties: { base: { type: 'string' } } },
{ type: 'object', properties: { extra: { type: 'number' } } },
],
},
},
}
expect(resolveSchemaPath(schema, 'filter.base')).toEqual({ type: 'string' })
expect(resolveSchemaPath(schema, 'filter.extra')).toEqual({ type: 'number' })
})
it('resolves a property on a top-level union variant', () => {
const schema = {
anyOf: [
{ type: 'object', title: 'A', properties: { foo: { type: 'string' } } },
{ type: 'object', title: 'B', properties: { bar: { type: 'number' } } },
],
}
expect(resolveSchemaPath(schema, 'foo')).toEqual({ type: 'string' })
expect(resolveSchemaPath(schema, 'bar')).toEqual({ type: 'number' })
})
it('walks nested unions (anyOf of anyOf)', () => {
const schema = {
type: 'object',
properties: {
node: {
anyOf: [
{
anyOf: [
{ type: 'object', properties: { deep: { type: 'boolean' } } },
{ type: 'null' },
],
},
{ type: 'object', properties: { other: { type: 'string' } } },
],
},
},
}
expect(resolveSchemaPath(schema, 'node.deep')).toEqual({ type: 'boolean' })
expect(resolveSchemaPath(schema, 'node.other')).toEqual({ type: 'string' })
})
it('walks array-of-union-of-allOf (arbitrary nesting)', () => {
const schema = {
type: 'object',
properties: {
rows: {
type: 'array',
items: {
anyOf: [
{
allOf: [
{ type: 'object', properties: { id: { type: 'number' } } },
{ type: 'object', properties: { name: { type: 'string' } } },
],
},
{ type: 'object', properties: { other: { type: 'boolean' } } },
],
},
},
},
}
expect(resolveSchemaPath(schema, 'rows.id')).toEqual({ type: 'number' })
expect(resolveSchemaPath(schema, 'rows.name')).toEqual({ type: 'string' })
expect(resolveSchemaPath(schema, 'rows.other')).toEqual({ type: 'boolean' })
})
it('ignores tuple-form items (items as array) safely', () => {
const schema = {
type: 'object',
properties: {
tuple: {
type: 'array',
items: [{ type: 'string' }, { type: 'number' }],
},
},
}
expect(resolveSchemaPath(schema, 'tuple.foo')).toBeNull()
// Numeric index falls back to composition lookup, none exists on a tuple.
expect(resolveSchemaPath(schema, 'tuple.0')).toBeNull()
})
it('blocks cycles via the seen set', () => {
const schema: Record<string, unknown> = {
type: 'object',
properties: { foo: { type: 'string' } },
}
// self-reference through anyOf
schema.anyOf = [schema]
expect(() => resolveSchemaPath(schema, 'foo')).not.toThrow()
expect(resolveSchemaPath(schema, 'foo')).toEqual({ type: 'string' })
expect(resolveSchemaPath(schema, 'nonexistent')).toBeNull()
})
})
})
describe('listAvailablePaths', () => {
it('lists property names for objects', () => {
const schema = {
type: 'object',
properties: {
name: { type: 'string' },
age: { type: 'number' },
},
}
expect(listAvailablePaths(schema)).toEqual(['name', 'age'])
})
it('lists union variant indices with titles', () => {
const schema = {
anyOf: [
{ type: 'object', title: 'TypeA' },
{ type: 'object', title: 'TypeB' },
],
}
expect(listAvailablePaths(schema)).toEqual(['0 (TypeA)', '1 (TypeB)'])
})
it('lists array item properties', () => {
const schema = {
type: 'array',
items: {
type: 'object',
properties: {
event: { type: 'string' },
math: { type: 'string' },
},
},
}
expect(listAvailablePaths(schema)).toEqual(['[items].event', '[items].math'])
})
it('lists array-of-anyOf variant properties with deduplication', () => {
const schema = {
type: 'array',
items: {
anyOf: [
{
type: 'object',
title: 'EventsNode',
properties: { event: { type: 'string' }, math: { type: 'string' } },
},
{
type: 'object',
title: 'ActionsNode',
properties: { id: { type: 'number' }, math: { type: 'string' } },
},
],
},
}
const paths = listAvailablePaths(schema)
expect(paths).toEqual(expect.arrayContaining(['[items].event', '[items].math', '[items].id']))
// math appears on both variants but should only be listed once
expect(paths.filter((p) => p === '[items].math')).toHaveLength(1)
})
it('lists properties reached through allOf composition', () => {
const schema = {
allOf: [
{ type: 'object', properties: { base: { type: 'string' } } },
{ type: 'object', properties: { extra: { type: 'number' } } },
],
}
const paths = listAvailablePaths(schema)
expect(paths).toEqual(expect.arrayContaining(['base', 'extra']))
})
it('lists properties reached through top-level anyOf (with variant indices)', () => {
const schema = {
anyOf: [
{ type: 'object', title: 'A', properties: { foo: { type: 'string' } } },
{ type: 'object', title: 'B', properties: { bar: { type: 'number' } } },
],
}
const paths = listAvailablePaths(schema)
expect(paths).toEqual(expect.arrayContaining(['foo', 'bar', '0 (A)', '1 (B)']))
})
})
describe('TOKEN_CHAR_LIMIT', () => {
it('is 48000 (8k tokens × 6 chars/token)', () => {
expect(TOKEN_CHAR_LIMIT).toBe(48_000)
})
})
describe('scalar constraints', () => {
// The exec `info` summary is the only schema an exec-mode agent sees. Dropping
// the length cap here meant the agent learned about it from the rejection.
it('keeps length, range, pattern and format constraints on object properties', () => {
const schema = {
type: 'object',
properties: {
description: { type: 'string', maxLength: 3000 },
name: { type: 'string', minLength: 1, pattern: '^[a-z-]+$' },
start: { type: 'string', format: 'date-time' },
rollout: { type: 'integer', minimum: 0, maximum: 100 },
},
}
const result = summarizeSchema(schema, 'my-tool')
expect(result.properties.description).toEqual({ type: 'string', maxLength: 3000 })
expect(result.properties.name).toEqual({ type: 'string', minLength: 1, pattern: '^[a-z-]+$' })
expect(result.properties.start).toEqual({ type: 'string', format: 'date-time' })
expect(result.properties.rollout).toEqual({ type: 'integer', minimum: 0, maximum: 100 })
})
// zod renders `.positive()` as `exclusiveMinimum: 0` (e.g. `dashboard-create-tile.id`).
it('keeps exclusive numeric bounds', () => {
const schema = {
type: 'object',
properties: {
id: { type: 'integer', exclusiveMinimum: 0 },
ratio: { type: 'number', exclusiveMaximum: 1 },
},
}
const result = summarizeSchema(schema, 'my-tool')
expect(result.properties.id).toEqual({ type: 'integer', exclusiveMinimum: 0 })
expect(result.properties.ratio).toEqual({ type: 'number', exclusiveMaximum: 1 })
})
// zod renders `.nullable()` as `anyOf: [scalar, null]`; the experiment tools'
// `description` arrives this way, and the summary used to say
// "union of 1 types" with no cap.
it('summarizes a nullable scalar as the scalar, keeping its constraints and enum', () => {
const schema = {
type: 'object',
properties: {
description: {
anyOf: [{ type: 'string', maxLength: 3000 }, { type: 'null' }],
description: 'Hypothesis',
},
stats: { anyOf: [{ type: 'string', enum: ['bayesian', 'frequentist'] }, { type: 'null' }] },
config: { anyOf: [{ type: 'object', properties: { a: {} } }, { type: 'null' }] },
},
}
const result = summarizeSchema(schema, 'my-tool')
expect(result.properties.description).toEqual({
type: 'string',
maxLength: 3000,
description: 'Hypothesis',
})
expect(result.properties.stats).toEqual({ type: 'string', enum: ['bayesian', 'frequentist'] })
// A nullable object is still complex and keeps its drill-down hint.
expect(result.properties.config!.hint).toContain('schema my-tool config')
})
// `query-web-overview.conversionGoal` is a nullable union of object variants:
// `anyOf: [{anyOf: [ActionConversionGoal, CustomEventConversionGoal]}, null]`.
it('summarizes a nullable object union as the union, with its drill-down hint', () => {
const schema = {
type: 'object',
properties: {
conversionGoal: {
anyOf: [
{
anyOf: [
{ type: 'object', properties: { actionId: { type: 'integer' } } },
{ type: 'object', properties: { customEventName: { type: 'string' } } },
],
},
{ type: 'null' },
],
description: 'Goal',
},
config: { anyOf: [{ type: 'object', properties: { a: {}, b: {} } }, { type: 'null' }] },
},
}
const result = summarizeSchema(schema, 'my-tool')
expect(result.properties.conversionGoal).toEqual({
type: 'union of 2 types',
description: 'Goal',
hint: expect.stringContaining('schema my-tool conversionGoal'),
})
expect(result.properties.config).toMatchObject({ type: 'object', fields: ['a', 'b'] })
})
it('keeps constraints on a leaf schema summarized on its own', () => {
const result = summarizeSchema({ type: 'string', maxLength: 400 }, 'my-tool')
expect(result).toMatchObject({ type: 'string', maxLength: 400 })
})
// zod puts a field's `default` (and `description`) on the nullable wrapper,
// not on the variant. `endpoint-run.refresh` is one: `{default: "cache",
// anyOf: [{type: "string", enum: [...]}, {type: "null"}]}`.
it('keeps a default that sits on the nullable wrapper, in a property and in a drill-down', () => {
const refresh = {
default: 'cache',
anyOf: [{ type: 'string', enum: ['cache', 'force', 'direct'] }, { type: 'null' }],
}
expect(summarizeSchema({ type: 'object', properties: { refresh } }, 'my-tool').properties.refresh).toEqual({
type: 'string',
enum: ['cache', 'force', 'direct'],
default: 'cache',
})
// `schema <tool> refresh` summarizes the wrapper on its own.
expect(summarizeSchema(refresh, 'my-tool')).toMatchObject({
type: 'string',
enum: ['cache', 'force', 'direct'],
default: 'cache',
})
})
// zod's ISO date-time `pattern` is a 310-character regex the agent cannot
// act on, and it rides on 85 fields; `format` says the same in a word.
it('drops a pattern that has a format or is too long to read, keeps a short one', () => {
const schema = {
type: 'object',
properties: {
at: {
type: 'string',
format: 'date-time',
pattern: '^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26])-02-29)',
},
long: { type: 'string', pattern: 'x'.repeat(81) },
slug: { type: 'string', pattern: '^[a-z-]+$' },
},
}
const result = summarizeSchema(schema, 'my-tool')
expect(result.properties.at).toEqual({ type: 'string', format: 'date-time' })
expect(result.properties.long).toEqual({ type: 'string' })
expect(result.properties.slug).toEqual({ type: 'string', pattern: '^[a-z-]+$' })
})
})
})