@jigging/agent-method 0.0.0 → 0.1.0-alpha.3

package/src/json.ts

@@ -0,0 +1,406 @@
+export type JsonScalar = null | boolean | number | string
+
+export type JsonValue = JsonScalar | readonly JsonValue[] | { readonly [key: string]: JsonValue }
+
+export type JsonObject = Readonly<Record<string, JsonValue>>
+
+export const JSON_1_LIMITS = Object.freeze({
+  bytes: 16_777_216,
+  depth: 128,
+  nodes: 262_144,
+  containerEntries: 65_536,
+  stringBytes: 8_388_608,
+  memberNameBytes: 1_024,
+  numberTokenBytes: 128,
+})
+
+const encoder = new TextEncoder()
+const decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true })
+
+export class Json1Error extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'Json1Error'
+  }
+}
+
+class Parser {
+  private position = 0
+  private nodes = 0
+
+  constructor(private readonly source: string) {}
+
+  parse(): JsonValue {
+    this.skipWhitespace()
+    const value = this.parseValue(1)
+    this.skipWhitespace()
+    if (this.position !== this.source.length) this.fail('unexpected trailing characters')
+    return value
+  }
+
+  private parseValue(depth: number): JsonValue {
+    if (depth > JSON_1_LIMITS.depth) this.fail('maximum value depth exceeded')
+    this.nodes += 1
+    if (this.nodes > JSON_1_LIMITS.nodes) this.fail('maximum value nodes exceeded')
+
+    const char = this.source[this.position]
+    if (char === '"') return this.parseString(false)
+    if (char === '{') return this.parseObject(depth)
+    if (char === '[') return this.parseArray(depth)
+    if (char === 't') return this.parseLiteral('true', true)
+    if (char === 'f') return this.parseLiteral('false', false)
+    if (char === 'n') return this.parseLiteral('null', null)
+    if (char === '-' || (char !== undefined && char >= '0' && char <= '9')) {
+      return this.parseNumber()
+    }
+    return this.fail('expected a JSON value')
+  }
+
+  private parseObject(depth: number): JsonObject {
+    this.position += 1
+    const result: Record<string, JsonValue> = Object.create(null) as Record<string, JsonValue>
+    const keys = new Set<string>()
+    this.skipWhitespace()
+    if (this.consume('}')) return result
+
+    let members = 0
+    while (true) {
+      if (this.source[this.position] !== '"') this.fail('expected an object member name')
+      const key = this.parseString(true)
+      if (keys.has(key)) this.fail(`duplicate object member ${key}`)
+      keys.add(key)
+      members += 1
+      if (members > JSON_1_LIMITS.containerEntries) {
+        this.fail('maximum object members exceeded')
+      }
+      this.skipWhitespace()
+      if (!this.consume(':')) this.fail("expected ':' after member name")
+      this.skipWhitespace()
+      result[key] = this.parseValue(depth + 1)
+      this.skipWhitespace()
+      if (this.consume('}')) return result
+      if (!this.consume(',')) this.fail("expected ',' or '}'")
+      this.skipWhitespace()
+    }
+  }
+
+  private parseArray(depth: number): readonly JsonValue[] {
+    this.position += 1
+    const result: JsonValue[] = []
+    this.skipWhitespace()
+    if (this.consume(']')) return result
+    while (true) {
+      if (result.length >= JSON_1_LIMITS.containerEntries) {
+        this.fail('maximum array items exceeded')
+      }
+      result.push(this.parseValue(depth + 1))
+      this.skipWhitespace()
+      if (this.consume(']')) return result
+      if (!this.consume(',')) this.fail("expected ',' or ']'")
+      this.skipWhitespace()
+    }
+  }
+
+  private parseString(memberName: boolean): string {
+    this.position += 1
+    const parts: string[] = []
+    let segmentStart = this.position
+    while (this.position < this.source.length) {
+      const char = this.source[this.position]
+      this.position += 1
+      if (char === '"') {
+        parts.push(this.source.slice(segmentStart, this.position - 1))
+        const value = parts.join('')
+        const limit = memberName ? JSON_1_LIMITS.memberNameBytes : JSON_1_LIMITS.stringBytes
+        if (encoder.encode(value).byteLength > limit) this.fail('maximum string bytes exceeded')
+        return value
+      }
+      if (char === '\\') {
+        parts.push(this.source.slice(segmentStart, this.position - 1))
+        parts.push(this.parseEscape())
+        segmentStart = this.position
+        continue
+      }
+      if (char === undefined || char.charCodeAt(0) <= 0x1f) {
+        this.fail('invalid character in string')
+      }
+      const code = char.charCodeAt(0)
+      if (code >= 0xd800 && code <= 0xdfff) {
+        const next = this.source[this.position]
+        if (
+          code > 0xdbff ||
+          next === undefined ||
+          next.charCodeAt(0) < 0xdc00 ||
+          next.charCodeAt(0) > 0xdfff
+        )
+          this.fail('lone Unicode surrogate')
+        this.position += 1
+      }
+    }
+    return this.fail('unterminated string')
+  }
+
+  private parseEscape(): string {
+    const escaped = this.source[this.position]
+    this.position += 1
+    switch (escaped) {
+      case '"':
+      case '\\':
+      case '/':
+        return escaped
+      case 'b':
+        return '\b'
+      case 'f':
+        return '\f'
+      case 'n':
+        return '\n'
+      case 'r':
+        return '\r'
+      case 't':
+        return '\t'
+      case 'u': {
+        const first = this.parseHexCodeUnit()
+        if (first >= 0xd800 && first <= 0xdbff) {
+          if (this.source.slice(this.position, this.position + 2) !== '\\u') {
+            this.fail('high surrogate without low surrogate')
+          }
+          this.position += 2
+          const second = this.parseHexCodeUnit()
+          if (second < 0xdc00 || second > 0xdfff) {
+            this.fail('high surrogate without low surrogate')
+          }
+          return String.fromCharCode(first, second)
+        }
+        if (first >= 0xdc00 && first <= 0xdfff) this.fail('lone low surrogate')
+        return String.fromCharCode(first)
+      }
+      default:
+        return this.fail('invalid string escape')
+    }
+  }
+
+  private parseHexCodeUnit(): number {
+    const token = this.source.slice(this.position, this.position + 4)
+    if (!/^[0-9A-Fa-f]{4}$/.test(token)) this.fail('invalid Unicode escape')
+    this.position += 4
+    return Number.parseInt(token, 16)
+  }
+
+  private parseNumber(): number {
+    const start = this.position
+    this.consume('-')
+    if (this.consume('0')) {
+      const next = this.source[this.position]
+      if (next !== undefined && next >= '0' && next <= '9') {
+        this.fail('leading zero in number')
+      }
+    } else {
+      if (!this.consumeDigit('1', '9')) this.fail('invalid number')
+      while (this.consumeDigit('0', '9')) {}
+    }
+    if (this.consume('.')) {
+      if (!this.consumeDigit('0', '9')) this.fail('fraction requires a digit')
+      while (this.consumeDigit('0', '9')) {}
+    }
+    const exponent = this.source[this.position]
+    if (exponent === 'e' || exponent === 'E') {
+      this.position += 1
+      const sign = this.source[this.position]
+      if (sign === '+' || sign === '-') this.position += 1
+      if (!this.consumeDigit('0', '9')) this.fail('exponent requires a digit')
+      while (this.consumeDigit('0', '9')) {}
+    }
+    const token = this.source.slice(start, this.position)
+    if (token.length > JSON_1_LIMITS.numberTokenBytes) {
+      this.fail('maximum number token bytes exceeded')
+    }
+    const value = Number(token)
+    if (!Number.isFinite(value)) this.fail('non-finite number')
+    if (Number.isInteger(value) && !Number.isSafeInteger(value)) {
+      this.fail('integral number outside safe range')
+    }
+    return value
+  }
+
+  private parseLiteral<T extends JsonValue>(token: string, value: T): T {
+    if (this.source.slice(this.position, this.position + token.length) !== token) {
+      this.fail(`invalid literal ${token}`)
+    }
+    this.position += token.length
+    return value
+  }
+
+  private consume(expected: string): boolean {
+    if (this.source[this.position] !== expected) return false
+    this.position += 1
+    return true
+  }
+
+  private consumeDigit(minimum: string, maximum: string): boolean {
+    const char = this.source[this.position]
+    if (char === undefined || char < minimum || char > maximum) return false
+    this.position += 1
+    return true
+  }
+
+  private skipWhitespace(): void {
+    while (true) {
+      const char = this.source[this.position]
+      if (char !== ' ' && char !== '\n' && char !== '\r' && char !== '\t') return
+      this.position += 1
+    }
+  }
+
+  private fail(message: string): never {
+    throw new Json1Error(`${message} at character ${this.position}`)
+  }
+}
+
+export function decodeJson1(bytes: Uint8Array): JsonValue {
+  if (bytes.byteLength === 0) throw new Json1Error('empty JSON/0 document')
+  if (bytes.byteLength > JSON_1_LIMITS.bytes) throw new Json1Error('maximum bytes exceeded')
+  if (bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf) {
+    throw new Json1Error('UTF-8 BOM is not allowed')
+  }
+  let text: string
+  try {
+    text = decoder.decode(bytes)
+  } catch {
+    throw new Json1Error('invalid UTF-8')
+  }
+  return new Parser(text).parse()
+}
+
+export function validateJson1(value: unknown): asserts value is JsonValue {
+  visitJson(value, 1, { nodes: 0, encodedBytes: 0, active: new WeakSet<object>() }, false)
+}
+
+interface VisitState {
+  nodes: number
+  encodedBytes: number
+  readonly active: WeakSet<object>
+}
+
+function visitJson(value: unknown, depth: number, state: VisitState, memberName: boolean): void {
+  if (depth > JSON_1_LIMITS.depth) throw new Json1Error('maximum value depth exceeded')
+  state.nodes += 1
+  if (state.nodes > JSON_1_LIMITS.nodes) throw new Json1Error('maximum value nodes exceeded')
+  if (value === null) {
+    chargeEncodedBytes(state, 4)
+    return
+  }
+  if (typeof value === 'boolean') {
+    chargeEncodedBytes(state, value ? 4 : 5)
+    return
+  }
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) throw new Json1Error('non-finite number')
+    if (Number.isInteger(value) && !Number.isSafeInteger(value)) {
+      throw new Json1Error('integral number outside safe range')
+    }
+    chargeEncodedBytes(state, (Object.is(value, -0) ? '0' : JSON.stringify(value)).length)
+    return
+  }
+  if (typeof value === 'string') {
+    validateString(value, memberName ? JSON_1_LIMITS.memberNameBytes : JSON_1_LIMITS.stringBytes)
+    chargeEncodedBytes(state, encodedJsonStringBytes(value))
+    return
+  }
+  if (typeof value !== 'object') throw new Json1Error('value is not JSON/0')
+  if (state.active.has(value)) throw new Json1Error('cyclic value')
+  state.active.add(value)
+  try {
+    if (Array.isArray(value)) {
+      if (value.length > JSON_1_LIMITS.containerEntries) {
+        throw new Json1Error('maximum array items exceeded')
+      }
+      if (
+        Object.getPrototypeOf(value) !== Array.prototype ||
+        Reflect.ownKeys(value).length !== value.length + 1
+      ) {
+        throw new Json1Error('array must contain only ordinary indexed data')
+      }
+      chargeEncodedBytes(state, 2 + Math.max(0, value.length - 1))
+      for (let index = 0; index < value.length; index += 1) {
+        const field = Object.getOwnPropertyDescriptor(value, String(index))
+        if (field === undefined || !('value' in field) || !field.enumerable) {
+          throw new Json1Error('array items must be ordinary data')
+        }
+        visitJson(field.value, depth + 1, state, false)
+      }
+      return
+    }
+    const object = value as Record<string, unknown>
+    const prototype = Object.getPrototypeOf(object)
+    if (prototype !== Object.prototype && prototype !== null) {
+      throw new Json1Error('object must be an ordinary record')
+    }
+    const keys = Object.keys(object)
+    if (Reflect.ownKeys(object).length !== keys.length) {
+      throw new Json1Error('object members must be enumerable string data')
+    }
+    if (keys.length > JSON_1_LIMITS.containerEntries) {
+      throw new Json1Error('maximum object members exceeded')
+    }
+    chargeEncodedBytes(state, 2 + keys.length + Math.max(0, keys.length - 1))
+    for (const key of keys) {
+      validateString(key, JSON_1_LIMITS.memberNameBytes)
+      chargeEncodedBytes(state, encodedJsonStringBytes(key))
+      const field = Object.getOwnPropertyDescriptor(object, key)!
+      if (!('value' in field)) throw new Json1Error('object members must be ordinary data')
+      visitJson(field.value, depth + 1, state, false)
+    }
+  } finally {
+    state.active.delete(value)
+  }
+}
+
+function chargeEncodedBytes(state: VisitState, bytes: number): void {
+  if (bytes > JSON_1_LIMITS.bytes - state.encodedBytes) {
+    throw new Json1Error('maximum encoded bytes exceeded')
+  }
+  state.encodedBytes += bytes
+}
+
+function encodedJsonStringBytes(value: string): number {
+  return encoder.encode(JSON.stringify(value)).byteLength
+}
+
+function validateString(value: string, byteLimit: number): void {
+  if (encoder.encode(value).byteLength > byteLimit) {
+    throw new Json1Error('maximum string bytes exceeded')
+  }
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index)
+    if (code >= 0xd800 && code <= 0xdbff) {
+      const next = value.charCodeAt(index + 1)
+      if (!(next >= 0xdc00 && next <= 0xdfff)) throw new Json1Error('lone Unicode surrogate')
+      index += 1
+    } else if (code >= 0xdc00 && code <= 0xdfff) {
+      throw new Json1Error('lone Unicode surrogate')
+    }
+  }
+}
+
+/** RFC 8785 canonical bytes for an already validated JSON/0 value. */
+export function canonicalJson(value: JsonValue): Uint8Array {
+  validateJson1(value)
+  return encoder.encode(canonicalText(value))
+}
+
+function canonicalText(value: JsonValue): string {
+  if (value === null || typeof value === 'boolean' || typeof value === 'string') {
+    return JSON.stringify(value)
+  }
+  if (typeof value === 'number') return Object.is(value, -0) ? '0' : JSON.stringify(value)
+  if (Array.isArray(value)) return `[${value.map(canonicalText).join(',')}]`
+  const object = value as JsonObject
+  const members = Object.keys(object)
+    .sort(compareUtf16)
+    .map((key) => `${JSON.stringify(key)}:${canonicalText(object[key]!)}`)
+  return `{${members.join(',')}}`
+}
+
+function compareUtf16(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0
+}

package/src/schema.ts

@@ -0,0 +1,230 @@
+import { AgentMethodError } from './errors.js'
+import { canonicalJson, type JsonObject, type JsonValue, validateJson1 } from './json.js'
+import { exactKeys, ordinaryRecord } from './values.js'
+
+const MAX_RESPONSE_SCHEMA_DEPTH = 8
+const MAX_PROPERTIES_PER_OBJECT = 32
+const MAX_RESPONSE_SCHEMA_PROPERTIES = 128
+const MAX_ARRAY_ITEMS = 256
+const MAX_RESPONSE_SCHEMA_ENUM_VALUES = 256
+const MAX_RESPONSE_SCHEMA_SYMBOL_CHARACTERS = 120_000
+const MAX_LARGE_ENUM_CHARACTERS = 15_000
+
+interface ResponseSchemaProfileState {
+  properties: number
+  enumValues: number
+  symbolCharacters: number
+}
+
+/** Validate Jig's deliberately bounded recursive Agent structured-output profile. */
+export function assertResponseSchema(schema: JsonObject): void {
+  requireSchemaJson(schema)
+  if (schema.$schema !== 'https://flow.jig.md/schemas/schema-0.json') invalidSchemaProfile()
+  const state: ResponseSchemaProfileState = {
+    properties: 0,
+    enumValues: 0,
+    symbolCharacters: 0,
+  }
+  assertResponseSchemaNode(schema, 1, true, state)
+}
+
+function assertResponseSchemaNode(
+  value: unknown,
+  depth: number,
+  root: boolean,
+  state: ResponseSchemaProfileState,
+): void {
+  const schema = ordinaryRecord(value)
+  if (schema === undefined || depth > MAX_RESPONSE_SCHEMA_DEPTH) invalidSchemaProfile()
+
+  if (schema.type === 'object') {
+    assertClosedResponseObject(schema, depth, root, state)
+    return
+  }
+  if (root || Object.hasOwn(schema, '$schema')) invalidSchemaProfile()
+
+  if (schema.type === 'array') {
+    const baseExpected = Object.hasOwn(schema, 'minItems')
+      ? ['items', 'maxItems', 'minItems', 'type']
+      : ['items', 'maxItems', 'type']
+    if (
+      !exactProfileKeys(schema, baseExpected) ||
+      !boundedNonnegativeInteger(schema.maxItems, MAX_ARRAY_ITEMS) ||
+      (Object.hasOwn(schema, 'minItems') &&
+        (!boundedNonnegativeInteger(schema.minItems, MAX_ARRAY_ITEMS) ||
+          (schema.minItems as number) > (schema.maxItems as number)))
+    ) {
+      invalidSchemaProfile()
+    }
+    assertResponseSchemaNode(schema.items, depth + 1, false, state)
+    return
+  }
+
+  if (schema.type === 'integer' || isNullableType(schema.type, 'integer')) {
+    if (!exactProfileKeys(schema, ['type'])) invalidSchemaProfile()
+    return
+  }
+  if (schema.type === 'string' || isNullableType(schema.type, 'string')) {
+    assertResponseString(schema, isNullableType(schema.type, 'string'), state)
+    return
+  }
+  invalidSchemaProfile()
+}
+
+function assertClosedResponseObject(
+  schema: Record<string, unknown>,
+  depth: number,
+  root: boolean,
+  state: ResponseSchemaProfileState,
+): void {
+  const expected = root
+    ? ['$schema', 'additionalProperties', 'properties', 'required', 'type']
+    : ['additionalProperties', 'properties', 'required', 'type']
+  const properties = ordinaryRecord(schema.properties)
+  if (
+    !exactProfileKeys(schema, expected) ||
+    schema.additionalProperties !== false ||
+    properties === undefined ||
+    !Array.isArray(schema.required)
+  ) {
+    invalidSchemaProfile()
+  }
+  const names = Object.keys(properties)
+  if (
+    names.length === 0 ||
+    names.length > MAX_PROPERTIES_PER_OBJECT ||
+    schema.required.length !== names.length ||
+    new Set(schema.required).size !== names.length ||
+    schema.required.some((name) => typeof name !== 'string' || !Object.hasOwn(properties, name))
+  ) {
+    invalidSchemaProfile()
+  }
+  state.properties += names.length
+  if (state.properties > MAX_RESPONSE_SCHEMA_PROPERTIES) invalidSchemaProfile()
+  for (const name of names) {
+    state.symbolCharacters += unicodeScalarLength(name)
+    if (state.symbolCharacters > MAX_RESPONSE_SCHEMA_SYMBOL_CHARACTERS) invalidSchemaProfile()
+    assertResponseSchemaNode(properties[name], depth + 1, false, state)
+  }
+}
+
+function assertResponseString(
+  schema: Record<string, unknown>,
+  nullable: boolean,
+  state: ResponseSchemaProfileState,
+): void {
+  if (!Object.hasOwn(schema, 'enum')) {
+    if (!exactProfileKeys(schema, ['type'])) invalidSchemaProfile()
+    return
+  }
+  if (
+    !exactProfileKeys(schema, ['enum', 'type']) ||
+    !Array.isArray(schema.enum) ||
+    schema.enum.length === 0 ||
+    schema.enum.length > MAX_RESPONSE_SCHEMA_ENUM_VALUES ||
+    schema.enum.some((item) => typeof item !== 'string' && (!nullable || item !== null)) ||
+    new Set(schema.enum).size !== schema.enum.length ||
+    (nullable &&
+      (!schema.enum.includes(null) || !schema.enum.some((item) => typeof item === 'string')))
+  ) {
+    invalidSchemaProfile()
+  }
+  state.enumValues += schema.enum.length
+  const enumCharacters = schema.enum.reduce(
+    (total, item) => total + (typeof item === 'string' ? unicodeScalarLength(item) : 0),
+    0,
+  )
+  if (schema.enum.length > 250 && enumCharacters > MAX_LARGE_ENUM_CHARACTERS) {
+    invalidSchemaProfile()
+  }
+  state.symbolCharacters += enumCharacters
+  if (state.enumValues > MAX_RESPONSE_SCHEMA_ENUM_VALUES) invalidSchemaProfile()
+  if (state.symbolCharacters > MAX_RESPONSE_SCHEMA_SYMBOL_CHARACTERS) invalidSchemaProfile()
+}
+
+function isNullableType(value: unknown, base: 'integer' | 'string'): boolean {
+  return (
+    Array.isArray(value) &&
+    value.length === 2 &&
+    new Set(value).size === 2 &&
+    value.includes(base) &&
+    value.includes('null')
+  )
+}
+
+function exactProfileKeys(value: Record<string, unknown>, expected: readonly string[]): boolean {
+  if (Object.hasOwn(value, 'description') && typeof value.description !== 'string') return false
+  return exactKeys(
+    value,
+    Object.hasOwn(value, 'description') ? [...expected, 'description'] : expected,
+  )
+}
+
+function boundedNonnegativeInteger(value: unknown, maximum: number): boolean {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 && value <= maximum
+}
+
+function unicodeScalarLength(value: string): number {
+  return [...value].length
+}
+
+function invalidSchemaProfile(): never {
+  throw new AgentMethodError(
+    'INVALID_INPUT',
+    'Agent responseSchema must use the bounded structured-output profile',
+  )
+}
+
+function requireSchemaJson(schema: unknown): void {
+  try {
+    validateJson1(schema)
+    if (ordinaryRecord(schema) === undefined) invalidSchemaProfile()
+    if (canonicalJson(schema).byteLength > 256 * 1024) {
+      throw new AgentMethodError('RESOURCE_EXHAUSTED', 'Agent responseSchema exceeds 256 KiB')
+    }
+  } catch (error) {
+    if (error instanceof AgentMethodError) throw error
+    throw new AgentMethodError('INVALID_INPUT', 'Agent responseSchema must be valid JSON/0')
+  }
+}
+
+/** Remove only the FLOW dialect declaration from a fresh provider-facing copy. */
+export function projectResponseSchema(schema: JsonObject): JsonObject {
+  assertResponseSchema(schema)
+  const copy = JSON.parse(new TextDecoder().decode(canonicalJson(schema))) as Record<
+    string,
+    JsonValue
+  >
+  delete copy.$schema
+  return copy
+}
+
+/** Check a value against the already asserted closed structured-output profile. */
+export function matchesResponseSchema(schema: JsonObject, value: JsonValue): boolean {
+  if (value === null && Array.isArray(schema.type) && schema.type.includes('null')) {
+    return !Array.isArray(schema.enum) || schema.enum.includes(null)
+  }
+  if (schema.type === 'object') {
+    const record = ordinaryRecord(value)
+    if (record === undefined) return false
+    const properties = schema.properties as JsonObject
+    return (
+      exactKeys(record, Object.keys(properties)) &&
+      Object.entries(properties).every(([name, child]) =>
+        matchesResponseSchema(child as JsonObject, record[name] as JsonValue),
+      )
+    )
+  }
+  if (schema.type === 'array') {
+    return (
+      Array.isArray(value) &&
+      value.length <= (schema.maxItems as number) &&
+      value.length >= ((schema.minItems as number | undefined) ?? 0) &&
+      value.every((item) => matchesResponseSchema(schema.items as JsonObject, item))
+    )
+  }
+  if (schema.type === 'integer' || isNullableType(schema.type, 'integer')) {
+    return typeof value === 'number' && Number.isSafeInteger(value)
+  }
+  return typeof value === 'string' && (!Array.isArray(schema.enum) || schema.enum.includes(value))
+}