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

package/dist/json.js

@@ -0,0 +1,409 @@
+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) {
+        super(message);
+        this.name = 'Json1Error';
+    }
+}
+class Parser {
+    source;
+    position = 0;
+    nodes = 0;
+    constructor(source) {
+        this.source = source;
+    }
+    parse() {
+        this.skipWhitespace();
+        const value = this.parseValue(1);
+        this.skipWhitespace();
+        if (this.position !== this.source.length)
+            this.fail('unexpected trailing characters');
+        return value;
+    }
+    parseValue(depth) {
+        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');
+    }
+    parseObject(depth) {
+        this.position += 1;
+        const result = Object.create(null);
+        const keys = new Set();
+        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();
+        }
+    }
+    parseArray(depth) {
+        this.position += 1;
+        const result = [];
+        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();
+        }
+    }
+    parseString(memberName) {
+        this.position += 1;
+        const parts = [];
+        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');
+    }
+    parseEscape() {
+        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');
+        }
+    }
+    parseHexCodeUnit() {
+        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);
+    }
+    parseNumber() {
+        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;
+    }
+    parseLiteral(token, value) {
+        if (this.source.slice(this.position, this.position + token.length) !== token) {
+            this.fail(`invalid literal ${token}`);
+        }
+        this.position += token.length;
+        return value;
+    }
+    consume(expected) {
+        if (this.source[this.position] !== expected)
+            return false;
+        this.position += 1;
+        return true;
+    }
+    consumeDigit(minimum, maximum) {
+        const char = this.source[this.position];
+        if (char === undefined || char < minimum || char > maximum)
+            return false;
+        this.position += 1;
+        return true;
+    }
+    skipWhitespace() {
+        while (true) {
+            const char = this.source[this.position];
+            if (char !== ' ' && char !== '\n' && char !== '\r' && char !== '\t')
+                return;
+            this.position += 1;
+        }
+    }
+    fail(message) {
+        throw new Json1Error(`${message} at character ${this.position}`);
+    }
+}
+export function decodeJson1(bytes) {
+    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;
+    try {
+        text = decoder.decode(bytes);
+    }
+    catch {
+        throw new Json1Error('invalid UTF-8');
+    }
+    return new Parser(text).parse();
+}
+export function validateJson1(value) {
+    visitJson(value, 1, { nodes: 0, encodedBytes: 0, active: new WeakSet() }, false);
+}
+function visitJson(value, depth, state, memberName) {
+    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;
+        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, bytes) {
+    if (bytes > JSON_1_LIMITS.bytes - state.encodedBytes) {
+        throw new Json1Error('maximum encoded bytes exceeded');
+    }
+    state.encodedBytes += bytes;
+}
+function encodedJsonStringBytes(value) {
+    return encoder.encode(JSON.stringify(value)).byteLength;
+}
+function validateString(value, byteLimit) {
+    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) {
+    validateJson1(value);
+    return encoder.encode(canonicalText(value));
+}
+function canonicalText(value) {
+    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;
+    const members = Object.keys(object)
+        .sort(compareUtf16)
+        .map((key) => `${JSON.stringify(key)}:${canonicalText(object[key])}`);
+    return `{${members.join(',')}}`;
+}
+function compareUtf16(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}

package/dist/schema.d.ts

@@ -0,0 +1,7 @@
+import { type JsonObject, type JsonValue } from './json.js';
+/** Validate Jig's deliberately bounded recursive Agent structured-output profile. */
+export declare function assertResponseSchema(schema: JsonObject): void;
+/** Remove only the FLOW dialect declaration from a fresh provider-facing copy. */
+export declare function projectResponseSchema(schema: JsonObject): JsonObject;
+/** Check a value against the already asserted closed structured-output profile. */
+export declare function matchesResponseSchema(schema: JsonObject, value: JsonValue): boolean;

package/dist/schema.js

@@ -0,0 +1,180 @@
+import { AgentMethodError } from './errors.js';
+import { canonicalJson, 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;
+/** Validate Jig's deliberately bounded recursive Agent structured-output profile. */
+export function assertResponseSchema(schema) {
+    requireSchemaJson(schema);
+    if (schema.$schema !== 'https://flow.jig.md/schemas/schema-0.json')
+        invalidSchemaProfile();
+    const state = {
+        properties: 0,
+        enumValues: 0,
+        symbolCharacters: 0,
+    };
+    assertResponseSchemaNode(schema, 1, true, state);
+}
+function assertResponseSchemaNode(value, depth, root, state) {
+    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 > schema.maxItems))) {
+            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, depth, root, state) {
+    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, nullable, state) {
+    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, base) {
+    return (Array.isArray(value) &&
+        value.length === 2 &&
+        new Set(value).size === 2 &&
+        value.includes(base) &&
+        value.includes('null'));
+}
+function exactProfileKeys(value, expected) {
+    if (Object.hasOwn(value, 'description') && typeof value.description !== 'string')
+        return false;
+    return exactKeys(value, Object.hasOwn(value, 'description') ? [...expected, 'description'] : expected);
+}
+function boundedNonnegativeInteger(value, maximum) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 && value <= maximum;
+}
+function unicodeScalarLength(value) {
+    return [...value].length;
+}
+function invalidSchemaProfile() {
+    throw new AgentMethodError('INVALID_INPUT', 'Agent responseSchema must use the bounded structured-output profile');
+}
+function requireSchemaJson(schema) {
+    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) {
+    assertResponseSchema(schema);
+    const copy = JSON.parse(new TextDecoder().decode(canonicalJson(schema)));
+    delete copy.$schema;
+    return copy;
+}
+/** Check a value against the already asserted closed structured-output profile. */
+export function matchesResponseSchema(schema, value) {
+    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;
+        return (exactKeys(record, Object.keys(properties)) &&
+            Object.entries(properties).every(([name, child]) => matchesResponseSchema(child, record[name])));
+    }
+    if (schema.type === 'array') {
+        return (Array.isArray(value) &&
+            value.length <= schema.maxItems &&
+            value.length >= (schema.minItems ?? 0) &&
+            value.every((item) => matchesResponseSchema(schema.items, 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));
+}

package/dist/skills.d.ts

@@ -0,0 +1,3 @@
+import type { SkillText } from './index.js';
+/** Read explicit selections from an immutable package root, never from the CWD. */
+export declare function readPackageSkills(packageRoot: URL, names: readonly string[]): Promise<readonly SkillText[]>;