@stll/agent-input 0.3.0 → 0.4.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.d.ts +25 -0
- package/dist/index.js +377 -30
- package/package.json +2 -2
package/dist/index.d.ts
CHANGED
|
@@ -247,6 +247,31 @@ export declare const normalizeAgentInput: ({ path, placeholders, readers, schema
|
|
|
247
247
|
value: unknown;
|
|
248
248
|
}) => AgentInputNormalizationResult;
|
|
249
249
|
//#endregion
|
|
250
|
+
//#region src/null-optionals.d.ts
|
|
251
|
+
/**
|
|
252
|
+
* Apply the common optional-null rule before any agent-value coercion. The
|
|
253
|
+
* decision comes from the same schema validation will use: nullable values keep
|
|
254
|
+
* null, required values still fail, and optional non-null values read null as
|
|
255
|
+
* omission at every declared object level.
|
|
256
|
+
*/
|
|
257
|
+
export declare const withNullOptionalsOmitted: (schema: unknown, value: unknown) => unknown;
|
|
258
|
+
/**
|
|
259
|
+
* The same rule for a model's tool input, which also fills an optional string
|
|
260
|
+
* it is not setting with "": that reads as omitted too, but only where the
|
|
261
|
+
* property's own schema refuses "". Where "" is a value the property
|
|
262
|
+
* accepts, it stays exactly as sent. This is the placeholder rule the MCP
|
|
263
|
+
* input schemas apply (`nullAsAbsent`), read off JSON Schema.
|
|
264
|
+
*/
|
|
265
|
+
export declare const withModelPlaceholdersOmitted: (schema: unknown, value: unknown) => unknown;
|
|
266
|
+
/**
|
|
267
|
+
* `schema` with every optional property also admitting `null`, at every level
|
|
268
|
+
* `withModelPlaceholdersOmitted` reads: the spelling a model can use for "not
|
|
269
|
+
* set" on a route that treats every declared field as one to fill. Read
|
|
270
|
+
* against the original schema, `withModelPlaceholdersOmitted` drops exactly
|
|
271
|
+
* those nulls again, so the input a tool receives keeps its declared shape.
|
|
272
|
+
*/
|
|
273
|
+
export declare const withOptionalsNullable: (schema: unknown) => unknown;
|
|
274
|
+
//#endregion
|
|
250
275
|
//#region src/email-address.d.ts
|
|
251
276
|
export declare const EMAIL_ADDRESS_PATTERN: RegExp;
|
|
252
277
|
//#endregion
|
package/dist/index.js
CHANGED
|
@@ -123,7 +123,7 @@ const normalizeEnumValue = (input, allowed, options) => {
|
|
|
123
123
|
* is missing, except `iso`, whose output has none.
|
|
124
124
|
*/
|
|
125
125
|
/** Narrow `unknown` to a plain object (not null, not array). */
|
|
126
|
-
const isRecord$
|
|
126
|
+
const isRecord$2 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
|
|
127
127
|
/** What a spec means when it names only a locale. */
|
|
128
128
|
const DEFAULT_DATE_FORMAT_STYLE = "long";
|
|
129
129
|
const quoted = (values) => values.map((value) => `"${value}"`).join(", ");
|
|
@@ -220,7 +220,7 @@ const readObjectSpec = (input) => {
|
|
|
220
220
|
* the wire object. */
|
|
221
221
|
const normalizeDateFormatSpec = (input) => {
|
|
222
222
|
if (typeof input === "string") return readStringSpec(input);
|
|
223
|
-
if (isRecord$
|
|
223
|
+
if (isRecord$2(input)) return readObjectSpec(input);
|
|
224
224
|
return specAsk(input);
|
|
225
225
|
};
|
|
226
226
|
//#endregion
|
|
@@ -759,12 +759,12 @@ const agentInputNormalizationMetadata = (annotation, description) => {
|
|
|
759
759
|
description: authored === void 0 || authored.length === 0 ? guidance : `${authored}${/[.!?]$/u.test(authored) ? " " : ". "}${guidance}`
|
|
760
760
|
};
|
|
761
761
|
};
|
|
762
|
-
const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
|
|
763
|
-
const isUnknownArray = (value) => Array.isArray(value);
|
|
762
|
+
const isRecord$1 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
|
|
763
|
+
const isUnknownArray$1 = (value) => Array.isArray(value);
|
|
764
764
|
const joinPath = (path, segment) => path.length === 0 ? segment : `${path}.${segment}`;
|
|
765
765
|
const annotationOf = (schema) => {
|
|
766
766
|
const annotation = schema[AGENT_INPUT_NORMALIZATION_KEY];
|
|
767
|
-
if (!isRecord(annotation)) return;
|
|
767
|
+
if (!isRecord$1(annotation)) return;
|
|
768
768
|
const kind = annotation["kind"];
|
|
769
769
|
const normalizedKind = Object.values(AGENT_INPUT_NORMALIZATION_KIND).find((candidate) => candidate === kind);
|
|
770
770
|
if (normalizedKind === void 0) return;
|
|
@@ -792,27 +792,27 @@ const annotationOf = (schema) => {
|
|
|
792
792
|
};
|
|
793
793
|
/** The country half of an annotation, read back from the emitted schema. */
|
|
794
794
|
const countryAnnotationOf = (value) => {
|
|
795
|
-
if (!isRecord(value)) return;
|
|
795
|
+
if (!isRecord$1(value)) return;
|
|
796
796
|
const spelling = value["spelling"];
|
|
797
797
|
if (spelling !== "alpha-3" && spelling !== "alpha-2") return;
|
|
798
798
|
const admitted = value["admitted"];
|
|
799
799
|
const tool = value["tool"];
|
|
800
800
|
return {
|
|
801
801
|
spelling,
|
|
802
|
-
...isUnknownArray(admitted) && admitted.every((code) => typeof code === "string") ? { admitted } : {},
|
|
802
|
+
...isUnknownArray$1(admitted) && admitted.every((code) => typeof code === "string") ? { admitted } : {},
|
|
803
803
|
...typeof tool === "string" ? { tool } : {}
|
|
804
804
|
};
|
|
805
805
|
};
|
|
806
806
|
const stringEnumOf = (schema) => {
|
|
807
807
|
const values = schema["enum"];
|
|
808
|
-
if (isUnknownArray(values) && values.length > 0 && values.every((value) => typeof value === "string")) return values;
|
|
808
|
+
if (isUnknownArray$1(values) && values.length > 0 && values.every((value) => typeof value === "string")) return values;
|
|
809
809
|
if (typeof schema["const"] === "string") return [schema["const"]];
|
|
810
810
|
for (const keyword of ["anyOf", "oneOf"]) {
|
|
811
811
|
const branches = schema[keyword];
|
|
812
|
-
if (!isUnknownArray(branches)) continue;
|
|
812
|
+
if (!isUnknownArray$1(branches)) continue;
|
|
813
813
|
const literals = [];
|
|
814
814
|
for (const branch of branches) {
|
|
815
|
-
if (!isRecord(branch)) return;
|
|
815
|
+
if (!isRecord$1(branch)) return;
|
|
816
816
|
if (branch["type"] === "null") continue;
|
|
817
817
|
if (typeof branch["const"] !== "string") return;
|
|
818
818
|
literals.push(branch["const"]);
|
|
@@ -824,7 +824,7 @@ const inferredAnnotationOf = (schema) => {
|
|
|
824
824
|
const explicit = annotationOf(schema);
|
|
825
825
|
if (explicit !== void 0) return explicit;
|
|
826
826
|
if (schema["format"] === "date") return { kind: AGENT_INPUT_NORMALIZATION_KIND.date };
|
|
827
|
-
const types = isUnknownArray(schema["type"]) ? schema["type"] : [schema["type"]];
|
|
827
|
+
const types = isUnknownArray$1(schema["type"]) ? schema["type"] : [schema["type"]];
|
|
828
828
|
if (schema["format"] === "uuid" && types.includes("string")) return { kind: AGENT_INPUT_NORMALIZATION_KIND.uuid };
|
|
829
829
|
if (types.includes("number") || types.includes("integer")) return { kind: AGENT_INPUT_NORMALIZATION_KIND.number };
|
|
830
830
|
if (types.includes("boolean")) return { kind: AGENT_INPUT_NORMALIZATION_KIND.boolean };
|
|
@@ -882,7 +882,7 @@ const normalizeLeaf = ({ annotation, path, readers, schema, value }) => {
|
|
|
882
882
|
case "locale": return normalizeLocale(value);
|
|
883
883
|
case "number": {
|
|
884
884
|
const locale = annotation.locale;
|
|
885
|
-
const types = isUnknownArray(schema["type"]) ? schema["type"] : [schema["type"]];
|
|
885
|
+
const types = isUnknownArray$1(schema["type"]) ? schema["type"] : [schema["type"]];
|
|
886
886
|
if (annotation.range === "clamp") return normalizeNumberInRange(value, {
|
|
887
887
|
minimum: numericKeyword(schema, "minimum"),
|
|
888
888
|
maximum: numericKeyword(schema, "maximum"),
|
|
@@ -917,15 +917,15 @@ const placeholderIssue = (path, absent, presence) => {
|
|
|
917
917
|
};
|
|
918
918
|
/** Whether an array schema holds strings, so a lone string can be its one item. */
|
|
919
919
|
const holdsStrings = (items) => {
|
|
920
|
-
if (!isRecord(items)) return false;
|
|
921
|
-
return (isUnknownArray(items["type"]) ? items["type"] : [items["type"]]).includes("string") || stringEnumOf(items) !== void 0;
|
|
920
|
+
if (!isRecord$1(items)) return false;
|
|
921
|
+
return (isUnknownArray$1(items["type"]) ? items["type"] : [items["type"]]).includes("string") || stringEnumOf(items) !== void 0;
|
|
922
922
|
};
|
|
923
923
|
/**
|
|
924
924
|
* Whether a string list's items are constrained tokens (an id, a code, an
|
|
925
925
|
* advertised value), which never carry a comma of their own, so a
|
|
926
926
|
* comma-joined string is a list. Free text is never split.
|
|
927
927
|
*/
|
|
928
|
-
const holdsTokens = (items) => isRecord(items) && (typeof items["format"] === "string" || typeof items["pattern"] === "string" || stringEnumOf(items) !== void 0);
|
|
928
|
+
const holdsTokens = (items) => isRecord$1(items) && (typeof items["format"] === "string" || typeof items["pattern"] === "string" || stringEnumOf(items) !== void 0);
|
|
929
929
|
const MAX_SCHEMA_REFERENCE_DEPTH = 64;
|
|
930
930
|
const valueMatchesType = (type, value) => {
|
|
931
931
|
switch (type) {
|
|
@@ -934,13 +934,13 @@ const valueMatchesType = (type, value) => {
|
|
|
934
934
|
case "integer":
|
|
935
935
|
case "number": return typeof value === "number" || typeof value === "string";
|
|
936
936
|
case "null": return value === null;
|
|
937
|
-
case "object": return isRecord(value);
|
|
937
|
+
case "object": return isRecord$1(value);
|
|
938
938
|
case "string": return typeof value === "string";
|
|
939
939
|
default: return true;
|
|
940
940
|
}
|
|
941
941
|
};
|
|
942
942
|
const walkUnion = ({ branches, value, path, context }) => {
|
|
943
|
-
const results = branches.filter((branch) => isRecord(branch) && valueMatchesType(branch["type"], value)).map((branch) => walkSchema({
|
|
943
|
+
const results = branches.filter((branch) => isRecord$1(branch) && valueMatchesType(branch["type"], value)).map((branch) => walkSchema({
|
|
944
944
|
schema: branch,
|
|
945
945
|
value,
|
|
946
946
|
path,
|
|
@@ -962,7 +962,7 @@ const resolveLocalReference = (reference, rootSchema) => {
|
|
|
962
962
|
if (!reference.startsWith("#/")) return;
|
|
963
963
|
let resolved = rootSchema;
|
|
964
964
|
for (const rawSegment of reference.slice(2).split("/")) {
|
|
965
|
-
if (!isRecord(resolved)) return;
|
|
965
|
+
if (!isRecord$1(resolved)) return;
|
|
966
966
|
const segment = rawSegment.replaceAll("~1", "/").replaceAll("~0", "~");
|
|
967
967
|
resolved = resolved[segment];
|
|
968
968
|
}
|
|
@@ -1015,7 +1015,7 @@ const walkIntersection = ({ schema, branches, value, path, context }) => {
|
|
|
1015
1015
|
} : { status: "not-applicable" };
|
|
1016
1016
|
};
|
|
1017
1017
|
const walkSchema = ({ schema, value, path, context }) => {
|
|
1018
|
-
if (!isRecord(schema)) return { status: "not-applicable" };
|
|
1018
|
+
if (!isRecord$1(schema)) return { status: "not-applicable" };
|
|
1019
1019
|
const reference = schema["$ref"];
|
|
1020
1020
|
if (typeof reference === "string") {
|
|
1021
1021
|
if (context.remainingReferenceDepth === 0) return { status: "not-applicable" };
|
|
@@ -1031,7 +1031,7 @@ const walkSchema = ({ schema, value, path, context }) => {
|
|
|
1031
1031
|
});
|
|
1032
1032
|
}
|
|
1033
1033
|
const intersections = schema["allOf"];
|
|
1034
|
-
if (isUnknownArray(intersections)) return walkIntersection({
|
|
1034
|
+
if (isUnknownArray$1(intersections)) return walkIntersection({
|
|
1035
1035
|
schema,
|
|
1036
1036
|
branches: intersections,
|
|
1037
1037
|
value,
|
|
@@ -1041,7 +1041,7 @@ const walkSchema = ({ schema, value, path, context }) => {
|
|
|
1041
1041
|
const explicitAnnotation = annotationOf(schema);
|
|
1042
1042
|
if (explicitAnnotation === void 0) for (const keyword of ["anyOf", "oneOf"]) {
|
|
1043
1043
|
const branches = schema[keyword];
|
|
1044
|
-
if (isUnknownArray(branches)) return walkUnion({
|
|
1044
|
+
if (isUnknownArray$1(branches)) return walkUnion({
|
|
1045
1045
|
branches,
|
|
1046
1046
|
value,
|
|
1047
1047
|
path,
|
|
@@ -1049,7 +1049,7 @@ const walkSchema = ({ schema, value, path, context }) => {
|
|
|
1049
1049
|
});
|
|
1050
1050
|
}
|
|
1051
1051
|
const annotation = explicitAnnotation ?? inferredAnnotationOf(schema);
|
|
1052
|
-
const types = isUnknownArray(schema["type"]) ? schema["type"] : [schema["type"]];
|
|
1052
|
+
const types = isUnknownArray$1(schema["type"]) ? schema["type"] : [schema["type"]];
|
|
1053
1053
|
if (annotation !== void 0 && !(value === null && types.includes("null"))) {
|
|
1054
1054
|
const normalized = normalizeLeaf({
|
|
1055
1055
|
annotation,
|
|
@@ -1085,7 +1085,7 @@ const walkSchema = ({ schema, value, path, context }) => {
|
|
|
1085
1085
|
}
|
|
1086
1086
|
for (const keyword of ["anyOf", "oneOf"]) {
|
|
1087
1087
|
const branches = schema[keyword];
|
|
1088
|
-
if (isUnknownArray(branches)) return walkUnion({
|
|
1088
|
+
if (isUnknownArray$1(branches)) return walkUnion({
|
|
1089
1089
|
branches,
|
|
1090
1090
|
value,
|
|
1091
1091
|
path,
|
|
@@ -1094,7 +1094,7 @@ const walkSchema = ({ schema, value, path, context }) => {
|
|
|
1094
1094
|
}
|
|
1095
1095
|
const properties = schema["properties"];
|
|
1096
1096
|
const patternProperties = schema["patternProperties"];
|
|
1097
|
-
if (isRecord(value) && (isRecord(properties) || isRecord(patternProperties))) return walkObject({
|
|
1097
|
+
if (isRecord$1(value) && (isRecord$1(properties) || isRecord$1(patternProperties))) return walkObject({
|
|
1098
1098
|
schema,
|
|
1099
1099
|
value,
|
|
1100
1100
|
path,
|
|
@@ -1113,12 +1113,12 @@ const childSchemasOf = (schema, key) => {
|
|
|
1113
1113
|
const properties = schema["properties"];
|
|
1114
1114
|
const patternProperties = schema["patternProperties"];
|
|
1115
1115
|
const childSchemas = [];
|
|
1116
|
-
if (isRecord(properties) && Object.hasOwn(properties, key)) childSchemas.push(properties[key]);
|
|
1117
|
-
if (isRecord(patternProperties)) {
|
|
1116
|
+
if (isRecord$1(properties) && Object.hasOwn(properties, key)) childSchemas.push(properties[key]);
|
|
1117
|
+
if (isRecord$1(patternProperties)) {
|
|
1118
1118
|
for (const [pattern, childSchema] of Object.entries(patternProperties)) if (new RegExp(pattern, "u").test(key)) childSchemas.push(childSchema);
|
|
1119
1119
|
}
|
|
1120
1120
|
const additionalProperties = schema["additionalProperties"];
|
|
1121
|
-
if (childSchemas.length === 0 && isRecord(additionalProperties)) childSchemas.push(additionalProperties);
|
|
1121
|
+
if (childSchemas.length === 0 && isRecord$1(additionalProperties)) childSchemas.push(additionalProperties);
|
|
1122
1122
|
return childSchemas;
|
|
1123
1123
|
};
|
|
1124
1124
|
const walkObject = ({ schema, value, path, context }) => {
|
|
@@ -1126,7 +1126,7 @@ const walkObject = ({ schema, value, path, context }) => {
|
|
|
1126
1126
|
const notes = [];
|
|
1127
1127
|
const issues = [];
|
|
1128
1128
|
const requiredKeys = schema["required"];
|
|
1129
|
-
const required = new Set(isUnknownArray(requiredKeys) ? requiredKeys : []);
|
|
1129
|
+
const required = new Set(isUnknownArray$1(requiredKeys) ? requiredKeys : []);
|
|
1130
1130
|
for (const [key, entry] of Object.entries(value)) {
|
|
1131
1131
|
let reading = {
|
|
1132
1132
|
status: "value",
|
|
@@ -1192,7 +1192,7 @@ const walkList = ({ items, value, path, context }) => {
|
|
|
1192
1192
|
list = read.value;
|
|
1193
1193
|
if (read.note !== void 0) notes.push(read.note);
|
|
1194
1194
|
}
|
|
1195
|
-
if (!isUnknownArray(list)) return { status: "not-applicable" };
|
|
1195
|
+
if (!isUnknownArray$1(list)) return { status: "not-applicable" };
|
|
1196
1196
|
const output = [];
|
|
1197
1197
|
const issues = [];
|
|
1198
1198
|
for (const [index, entry] of list.entries()) {
|
|
@@ -1254,4 +1254,351 @@ const normalizeAgentInput = ({ path = "", placeholders = "absent", readers = {},
|
|
|
1254
1254
|
};
|
|
1255
1255
|
};
|
|
1256
1256
|
//#endregion
|
|
1257
|
-
|
|
1257
|
+
//#region src/null-optionals.ts
|
|
1258
|
+
const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
|
|
1259
|
+
const isUnknownArray = (value) => Array.isArray(value);
|
|
1260
|
+
const sameJsonValue = (left, right) => {
|
|
1261
|
+
if (Object.is(left, right)) return true;
|
|
1262
|
+
if (isUnknownArray(left) && isUnknownArray(right)) return left.length === right.length && left.every((value, index) => sameJsonValue(value, right.at(index)));
|
|
1263
|
+
if (!isRecord(left) || !isRecord(right) || Object.getPrototypeOf(left) !== Object.getPrototypeOf(right)) return false;
|
|
1264
|
+
const keys = Object.keys(left);
|
|
1265
|
+
return keys.length === Object.keys(right).length && keys.every((key) => Object.hasOwn(right, key) && sameJsonValue(left[key], right[key]));
|
|
1266
|
+
};
|
|
1267
|
+
const CONSTRAINING_KEYWORDS = [
|
|
1268
|
+
"type",
|
|
1269
|
+
"anyOf",
|
|
1270
|
+
"oneOf",
|
|
1271
|
+
"allOf",
|
|
1272
|
+
"enum",
|
|
1273
|
+
"const",
|
|
1274
|
+
"$ref"
|
|
1275
|
+
];
|
|
1276
|
+
const admitsNull = (schema) => {
|
|
1277
|
+
if (!isRecord(schema)) return true;
|
|
1278
|
+
if (schema["nullable"] === true) return true;
|
|
1279
|
+
const type = schema["type"];
|
|
1280
|
+
if (type === "null" || isUnknownArray(type) && type.includes("null")) return true;
|
|
1281
|
+
for (const keyword of ["anyOf", "oneOf"]) {
|
|
1282
|
+
const branches = schema[keyword];
|
|
1283
|
+
if (isUnknownArray(branches) && branches.some(admitsNull)) return true;
|
|
1284
|
+
}
|
|
1285
|
+
return CONSTRAINING_KEYWORDS.every((keyword) => !(keyword in schema));
|
|
1286
|
+
};
|
|
1287
|
+
const UNION_KEYWORDS = ["anyOf", "oneOf"];
|
|
1288
|
+
/**
|
|
1289
|
+
* Whether `text` matches a schema's `pattern`, or `undefined` when the pattern
|
|
1290
|
+
* does not compile as a Unicode expression: a third-party tool schema may
|
|
1291
|
+
* carry one (`^[a-z\_]+$`), and it must not fail the whole input.
|
|
1292
|
+
*/
|
|
1293
|
+
const matchesPattern = (pattern, text) => {
|
|
1294
|
+
const compiled = Result.try(() => new RegExp(pattern, "u"));
|
|
1295
|
+
return Result.isOk(compiled) ? compiled.value.test(text) : void 0;
|
|
1296
|
+
};
|
|
1297
|
+
/**
|
|
1298
|
+
* Whether a union branch could be the one `value` was written for: no `const`
|
|
1299
|
+
* property of the branch (a discriminator) disagrees with the value. A branch
|
|
1300
|
+
* with no discriminator always could.
|
|
1301
|
+
*/
|
|
1302
|
+
const branchCouldMatch = (branch, value) => {
|
|
1303
|
+
const properties = branch["properties"];
|
|
1304
|
+
if (!isRecord(properties)) return true;
|
|
1305
|
+
return Object.entries(properties).every(([name, property]) => !isRecord(property) || !("const" in property) || !Object.hasOwn(value, name) || sameJsonValue(property["const"], value[name]));
|
|
1306
|
+
};
|
|
1307
|
+
const jsonTypeOf = (value) => {
|
|
1308
|
+
if (value === null) return "null";
|
|
1309
|
+
if (isUnknownArray(value)) return "array";
|
|
1310
|
+
if (typeof value === "number") return Number.isInteger(value) ? "integer" : "number";
|
|
1311
|
+
return typeof value;
|
|
1312
|
+
};
|
|
1313
|
+
const typeTakes = (type, value) => {
|
|
1314
|
+
if (type === void 0) return true;
|
|
1315
|
+
const types = isUnknownArray(type) ? type : [type];
|
|
1316
|
+
const valueType = jsonTypeOf(value);
|
|
1317
|
+
return types.includes(valueType) || valueType === "integer" && types.includes("number");
|
|
1318
|
+
};
|
|
1319
|
+
/**
|
|
1320
|
+
* Whether `value` has a shape `schema` takes: its types, enums, constants,
|
|
1321
|
+
* required and closed object fields, read through unions, objects and arrays.
|
|
1322
|
+
* A placeholder (null, "") fits anywhere, since it is what is being judged,
|
|
1323
|
+
* and string constraints and references are left to validation.
|
|
1324
|
+
*/
|
|
1325
|
+
const shapeTakes = (schema, value) => {
|
|
1326
|
+
if (!isRecord(schema) || value === null || value === "") return true;
|
|
1327
|
+
for (const keyword of UNION_KEYWORDS) {
|
|
1328
|
+
const branches = schema[keyword];
|
|
1329
|
+
if (isUnknownArray(branches) && !branches.some((branch) => shapeTakes(branch, value))) return false;
|
|
1330
|
+
}
|
|
1331
|
+
const enumValues = schema["enum"];
|
|
1332
|
+
if (isUnknownArray(enumValues)) return enumValues.some((allowed) => sameJsonValue(allowed, value));
|
|
1333
|
+
if ("const" in schema) return sameJsonValue(schema["const"], value);
|
|
1334
|
+
if (!typeTakes(schema["type"], value)) return false;
|
|
1335
|
+
if (isUnknownArray(value)) return arrayShapeTakes(schema, value);
|
|
1336
|
+
return !isRecord(value) || objectShapeTakes(schema, value);
|
|
1337
|
+
};
|
|
1338
|
+
const arrayShapeTakes = (schema, value) => {
|
|
1339
|
+
const { maxItems, minItems } = schema;
|
|
1340
|
+
if (typeof minItems === "number" && value.length < minItems) return false;
|
|
1341
|
+
if (typeof maxItems === "number" && value.length > maxItems) return false;
|
|
1342
|
+
const items = schema["items"];
|
|
1343
|
+
return !isRecord(items) || value.every((entry) => shapeTakes(items, entry));
|
|
1344
|
+
};
|
|
1345
|
+
/**
|
|
1346
|
+
* Whether a field the object does not declare by name fits it: every
|
|
1347
|
+
* `patternProperties` schema its name matches applies, and a name matching
|
|
1348
|
+
* none falls to `additionalProperties`. A pattern that does not compile
|
|
1349
|
+
* decides nothing.
|
|
1350
|
+
*/
|
|
1351
|
+
const extraFieldTakes = (schema, key, entry) => {
|
|
1352
|
+
const patternProperties = schema["patternProperties"];
|
|
1353
|
+
let matched = false;
|
|
1354
|
+
if (isRecord(patternProperties)) for (const [pattern, childSchema] of Object.entries(patternProperties)) {
|
|
1355
|
+
const matches = matchesPattern(pattern, key);
|
|
1356
|
+
if (matches === void 0) return true;
|
|
1357
|
+
if (matches) {
|
|
1358
|
+
matched = true;
|
|
1359
|
+
if (!shapeTakes(childSchema, entry)) return false;
|
|
1360
|
+
}
|
|
1361
|
+
}
|
|
1362
|
+
if (matched) return true;
|
|
1363
|
+
const additionalProperties = schema["additionalProperties"];
|
|
1364
|
+
if (additionalProperties === false) return entry === null || entry === "";
|
|
1365
|
+
return shapeTakes(additionalProperties, entry);
|
|
1366
|
+
};
|
|
1367
|
+
const objectShapeTakes = (schema, value) => {
|
|
1368
|
+
const required = schema["required"];
|
|
1369
|
+
if (isUnknownArray(required) && !required.every((name) => typeof name !== "string" || Object.hasOwn(value, name))) return false;
|
|
1370
|
+
const properties = isRecord(schema["properties"]) ? schema["properties"] : {};
|
|
1371
|
+
return Object.entries(value).every(([key, entry]) => Object.hasOwn(properties, key) ? shapeTakes(properties[key], entry) : extraFieldTakes(schema, key, entry));
|
|
1372
|
+
};
|
|
1373
|
+
/**
|
|
1374
|
+
* A union node declares nothing itself: its members do. Without reading them,
|
|
1375
|
+
* an optional null inside a discriminated member (an array of `mode` variants)
|
|
1376
|
+
* reached validation and was refused. Of the members no discriminator rules
|
|
1377
|
+
* out, those whose shape takes the value are the ones it was written for; a
|
|
1378
|
+
* member it cannot fit must not keep a null the fitting one refuses. When
|
|
1379
|
+
* none fits (a lenient value, coerced later), every such member still counts.
|
|
1380
|
+
*/
|
|
1381
|
+
const matchedBranches = /* @__PURE__ */ new WeakMap();
|
|
1382
|
+
const matchingUnionBranches = (schema, value) => {
|
|
1383
|
+
const bySchema = matchedBranches.get(schema) ?? /* @__PURE__ */ new WeakMap();
|
|
1384
|
+
matchedBranches.set(schema, bySchema);
|
|
1385
|
+
const known = bySchema.get(value);
|
|
1386
|
+
if (known !== void 0) return known;
|
|
1387
|
+
const matching = [];
|
|
1388
|
+
for (const keyword of UNION_KEYWORDS) {
|
|
1389
|
+
const branches = schema[keyword];
|
|
1390
|
+
if (!isUnknownArray(branches)) continue;
|
|
1391
|
+
for (const branch of branches) if (isRecord(branch) && branchCouldMatch(branch, value)) matching.push(branch);
|
|
1392
|
+
}
|
|
1393
|
+
const fitting = matching.filter((branch) => shapeTakes(branch, value));
|
|
1394
|
+
const matched = fitting.length > 0 ? fitting : matching;
|
|
1395
|
+
bySchema.set(value, matched);
|
|
1396
|
+
return matched;
|
|
1397
|
+
};
|
|
1398
|
+
const requiredNamesOf = (schema, value) => {
|
|
1399
|
+
const required = schema["required"];
|
|
1400
|
+
const names = new Set(isUnknownArray(required) ? required : []);
|
|
1401
|
+
for (const branch of matchingUnionBranches(schema, value)) for (const name of requiredNamesOf(branch, value)) names.add(name);
|
|
1402
|
+
return names;
|
|
1403
|
+
};
|
|
1404
|
+
/** The schemas a node itself, not its union branches, gives `key`. */
|
|
1405
|
+
const ownChildSchemas = (schema, key) => {
|
|
1406
|
+
const children = [];
|
|
1407
|
+
const properties = schema["properties"];
|
|
1408
|
+
if (isRecord(properties) && Object.hasOwn(properties, key)) children.push(properties[key]);
|
|
1409
|
+
const patternProperties = schema["patternProperties"];
|
|
1410
|
+
if (isRecord(patternProperties)) {
|
|
1411
|
+
for (const [pattern, childSchema] of Object.entries(patternProperties)) if (matchesPattern(pattern, key) === true) children.push(childSchema);
|
|
1412
|
+
}
|
|
1413
|
+
return children;
|
|
1414
|
+
};
|
|
1415
|
+
const objectChildSchemas = (schema, key, value) => {
|
|
1416
|
+
const children = [];
|
|
1417
|
+
for (const branch of matchingUnionBranches(schema, value)) children.push(...objectChildSchemas(branch, key, value));
|
|
1418
|
+
children.push(...ownChildSchemas(schema, key));
|
|
1419
|
+
const additionalProperties = schema["additionalProperties"];
|
|
1420
|
+
if (children.length === 0 && isRecord(additionalProperties)) children.push(additionalProperties);
|
|
1421
|
+
return children;
|
|
1422
|
+
};
|
|
1423
|
+
/**
|
|
1424
|
+
* Whether the node refuses `entry` at `key`. Every schema the node itself
|
|
1425
|
+
* gives the key applies, so one refusing it is enough; union branches are
|
|
1426
|
+
* alternatives, so every branch that declares the key must refuse it, or a
|
|
1427
|
+
* value valid under one branch would lose a field another branch refuses.
|
|
1428
|
+
*/
|
|
1429
|
+
const refusesPlaceholder = (schema, site) => {
|
|
1430
|
+
const { entry, isAbsent, key, value } = site;
|
|
1431
|
+
const branches = matchingUnionBranches(schema, value).filter((branch) => objectChildSchemas(branch, key, value).length > 0);
|
|
1432
|
+
const own = ownChildSchemas(schema, key);
|
|
1433
|
+
const additionalProperties = schema["additionalProperties"];
|
|
1434
|
+
if (own.length === 0 && branches.length === 0 && isRecord(additionalProperties)) own.push(additionalProperties);
|
|
1435
|
+
if (own.some((childSchema) => isAbsent(entry, childSchema))) return true;
|
|
1436
|
+
return branches.length > 0 && branches.every((branch) => refusesPlaceholder(branch, site));
|
|
1437
|
+
};
|
|
1438
|
+
/** The item schemas a union node's array members, nested ones too, declare. */
|
|
1439
|
+
const unionItemSchemas = (schema, value) => {
|
|
1440
|
+
const members = UNION_KEYWORDS.flatMap((keyword) => {
|
|
1441
|
+
const branches = schema[keyword];
|
|
1442
|
+
return (isUnknownArray(branches) ? branches : []).filter(isRecord);
|
|
1443
|
+
});
|
|
1444
|
+
const fitting = members.filter((member) => shapeTakes(member, value));
|
|
1445
|
+
return (fitting.length > 0 ? fitting : members).flatMap((member) => member["items"] === void 0 ? unionItemSchemas(member, value) : [member["items"]]);
|
|
1446
|
+
};
|
|
1447
|
+
const omitAbsentPlaceholders = (schema, value, isAbsent) => {
|
|
1448
|
+
if (!isRecord(schema)) return value;
|
|
1449
|
+
const items = schema["items"];
|
|
1450
|
+
if (items !== void 0 && isUnknownArray(value)) return value.map((entry) => omitAbsentPlaceholders(items, entry, isAbsent));
|
|
1451
|
+
if (isUnknownArray(value)) {
|
|
1452
|
+
const itemSchemas = unionItemSchemas(schema, value);
|
|
1453
|
+
if (itemSchemas.length === 0) return value;
|
|
1454
|
+
const itemSchema = itemSchemas.length === 1 ? itemSchemas[0] : { anyOf: itemSchemas };
|
|
1455
|
+
return value.map((entry) => omitAbsentPlaceholders(itemSchema, entry, isAbsent));
|
|
1456
|
+
}
|
|
1457
|
+
if (!isRecord(value)) return value;
|
|
1458
|
+
const requiredNames = requiredNamesOf(schema, value);
|
|
1459
|
+
return Object.fromEntries(Object.entries(value).flatMap(([key, entry]) => {
|
|
1460
|
+
const childSchemas = objectChildSchemas(schema, key, value);
|
|
1461
|
+
if (childSchemas.length === 0) return [[key, entry]];
|
|
1462
|
+
if (!requiredNames.has(key) && refusesPlaceholder(schema, {
|
|
1463
|
+
entry,
|
|
1464
|
+
isAbsent,
|
|
1465
|
+
key,
|
|
1466
|
+
value
|
|
1467
|
+
})) return [];
|
|
1468
|
+
let current = entry;
|
|
1469
|
+
for (const childSchema of childSchemas) current = omitAbsentPlaceholders(childSchema, current, isAbsent);
|
|
1470
|
+
return [[key, current]];
|
|
1471
|
+
}));
|
|
1472
|
+
};
|
|
1473
|
+
const isRejectedNull = (value, schema) => value === null && !admitsNull(schema);
|
|
1474
|
+
/**
|
|
1475
|
+
* JSON Schema string formats that no empty string satisfies. An unlisted
|
|
1476
|
+
* format is an annotation a validator may ignore, so it decides nothing.
|
|
1477
|
+
*/
|
|
1478
|
+
const EMPTY_REJECTING_FORMATS = /* @__PURE__ */ new Set([
|
|
1479
|
+
"date",
|
|
1480
|
+
"date-time",
|
|
1481
|
+
"time",
|
|
1482
|
+
"duration",
|
|
1483
|
+
"email",
|
|
1484
|
+
"hostname",
|
|
1485
|
+
"ipv4",
|
|
1486
|
+
"ipv6",
|
|
1487
|
+
"uri",
|
|
1488
|
+
"uuid"
|
|
1489
|
+
]);
|
|
1490
|
+
/**
|
|
1491
|
+
* Whether a schema refuses the empty string: a declared type other than
|
|
1492
|
+
* string, a string with a minimum length, a format "" cannot satisfy or a
|
|
1493
|
+
* pattern "" does not match, or an enum or constant without "". A union
|
|
1494
|
+
* refuses it only when every branch does. A schema that declares no type
|
|
1495
|
+
* accepts it.
|
|
1496
|
+
*/
|
|
1497
|
+
const rejectsEmptyString = (schema) => {
|
|
1498
|
+
if (!isRecord(schema)) return false;
|
|
1499
|
+
for (const keyword of UNION_KEYWORDS) {
|
|
1500
|
+
const branches = schema[keyword];
|
|
1501
|
+
if (isUnknownArray(branches) && branches.length > 0) return branches.every(rejectsEmptyString);
|
|
1502
|
+
}
|
|
1503
|
+
const enumValues = schema["enum"];
|
|
1504
|
+
if (isUnknownArray(enumValues)) return !enumValues.includes("");
|
|
1505
|
+
if ("const" in schema) return schema["const"] !== "";
|
|
1506
|
+
const type = schema["type"];
|
|
1507
|
+
if (type === void 0) return false;
|
|
1508
|
+
if (!(type === "string" || isUnknownArray(type) && type.includes("string"))) return true;
|
|
1509
|
+
const minLength = schema["minLength"];
|
|
1510
|
+
if (typeof minLength === "number" && minLength > 0) return true;
|
|
1511
|
+
const format = schema["format"];
|
|
1512
|
+
if (typeof format === "string" && EMPTY_REJECTING_FORMATS.has(format)) return true;
|
|
1513
|
+
const pattern = schema["pattern"];
|
|
1514
|
+
return typeof pattern === "string" && matchesPattern(pattern, "") === false;
|
|
1515
|
+
};
|
|
1516
|
+
const isRejectedPlaceholder = (value, schema) => isRejectedNull(value, schema) || value === "" && rejectsEmptyString(schema);
|
|
1517
|
+
/**
|
|
1518
|
+
* Apply the common optional-null rule before any agent-value coercion. The
|
|
1519
|
+
* decision comes from the same schema validation will use: nullable values keep
|
|
1520
|
+
* null, required values still fail, and optional non-null values read null as
|
|
1521
|
+
* omission at every declared object level.
|
|
1522
|
+
*/
|
|
1523
|
+
const withNullOptionalsOmitted = (schema, value) => omitAbsentPlaceholders(schema, value, isRejectedNull);
|
|
1524
|
+
/**
|
|
1525
|
+
* The same rule for a model's tool input, which also fills an optional string
|
|
1526
|
+
* it is not setting with "": that reads as omitted too, but only where the
|
|
1527
|
+
* property's own schema refuses "". Where "" is a value the property
|
|
1528
|
+
* accepts, it stays exactly as sent. This is the placeholder rule the MCP
|
|
1529
|
+
* input schemas apply (`nullAsAbsent`), read off JSON Schema.
|
|
1530
|
+
*/
|
|
1531
|
+
const withModelPlaceholdersOmitted = (schema, value) => omitAbsentPlaceholders(schema, value, isRejectedPlaceholder);
|
|
1532
|
+
const NULL_SCHEMA = { type: "null" };
|
|
1533
|
+
/** Keywords past which a node is more than a bare `type`. */
|
|
1534
|
+
const BEYOND_TYPE_KEYWORDS = [
|
|
1535
|
+
"anyOf",
|
|
1536
|
+
"oneOf",
|
|
1537
|
+
"allOf",
|
|
1538
|
+
"enum",
|
|
1539
|
+
"const",
|
|
1540
|
+
"$ref"
|
|
1541
|
+
];
|
|
1542
|
+
/** `schema`, also admitting `null`. */
|
|
1543
|
+
const admittingNull = (schema) => {
|
|
1544
|
+
if (!isRecord(schema) || admitsNull(schema)) return schema;
|
|
1545
|
+
const type = schema["type"];
|
|
1546
|
+
if (BEYOND_TYPE_KEYWORDS.every((keyword) => !(keyword in schema))) {
|
|
1547
|
+
if (typeof type === "string") return {
|
|
1548
|
+
...schema,
|
|
1549
|
+
type: [type, "null"]
|
|
1550
|
+
};
|
|
1551
|
+
if (isUnknownArray(type)) return {
|
|
1552
|
+
...schema,
|
|
1553
|
+
type: [...type, "null"]
|
|
1554
|
+
};
|
|
1555
|
+
}
|
|
1556
|
+
return { anyOf: [schema, NULL_SCHEMA] };
|
|
1557
|
+
};
|
|
1558
|
+
/** The names a node requires, its union branches' included. */
|
|
1559
|
+
const requiredAnywhere = (schema) => {
|
|
1560
|
+
const required = schema["required"];
|
|
1561
|
+
const names = new Set(isUnknownArray(required) ? required : []);
|
|
1562
|
+
for (const keyword of UNION_KEYWORDS) {
|
|
1563
|
+
const branches = schema[keyword];
|
|
1564
|
+
if (!isUnknownArray(branches)) continue;
|
|
1565
|
+
for (const branch of branches) if (isRecord(branch)) for (const name of requiredAnywhere(branch)) names.add(name);
|
|
1566
|
+
}
|
|
1567
|
+
return names;
|
|
1568
|
+
};
|
|
1569
|
+
const mapEntries = (record, map) => Object.fromEntries(Object.entries(record).map(([name, entry]) => [name, map(name, entry)]));
|
|
1570
|
+
const NO_NAMES = /* @__PURE__ */ new Set();
|
|
1571
|
+
/** A union branch's object is read with its parent's required names too. */
|
|
1572
|
+
const widenOptionals = (schema, inheritedRequired) => {
|
|
1573
|
+
if (!isRecord(schema)) return schema;
|
|
1574
|
+
const required = requiredAnywhere(schema);
|
|
1575
|
+
for (const name of inheritedRequired) required.add(name);
|
|
1576
|
+
const properties = schema["properties"];
|
|
1577
|
+
const patternProperties = schema["patternProperties"];
|
|
1578
|
+
return {
|
|
1579
|
+
...schema,
|
|
1580
|
+
...isRecord(properties) ? { properties: mapEntries(properties, (name, property) => {
|
|
1581
|
+
const inner = widenOptionals(property, NO_NAMES);
|
|
1582
|
+
return required.has(name) ? inner : admittingNull(inner);
|
|
1583
|
+
}) } : {},
|
|
1584
|
+
...isRecord(patternProperties) ? { patternProperties: mapEntries(patternProperties, (_name, entry) => widenOptionals(entry, NO_NAMES)) } : {},
|
|
1585
|
+
...Object.fromEntries(["additionalProperties", "items"].flatMap((keyword) => {
|
|
1586
|
+
const child = schema[keyword];
|
|
1587
|
+
return isRecord(child) ? [[keyword, widenOptionals(child, NO_NAMES)]] : [];
|
|
1588
|
+
})),
|
|
1589
|
+
...Object.fromEntries(UNION_KEYWORDS.flatMap((keyword) => {
|
|
1590
|
+
const branches = schema[keyword];
|
|
1591
|
+
return isUnknownArray(branches) ? [[keyword, branches.map((branch) => widenOptionals(branch, required))]] : [];
|
|
1592
|
+
}))
|
|
1593
|
+
};
|
|
1594
|
+
};
|
|
1595
|
+
/**
|
|
1596
|
+
* `schema` with every optional property also admitting `null`, at every level
|
|
1597
|
+
* `withModelPlaceholdersOmitted` reads: the spelling a model can use for "not
|
|
1598
|
+
* set" on a route that treats every declared field as one to fill. Read
|
|
1599
|
+
* against the original schema, `withModelPlaceholdersOmitted` drops exactly
|
|
1600
|
+
* those nulls again, so the input a tool receives keeps its declared shape.
|
|
1601
|
+
*/
|
|
1602
|
+
const withOptionalsNullable = (schema) => widenOptionals(schema, NO_NAMES);
|
|
1603
|
+
//#endregion
|
|
1604
|
+
export { ABSENT_PLACEHOLDERS, AGENT_INPUT_NORMALIZATION_KEY, AGENT_INPUT_NORMALIZATION_KIND, COUNTRY_INPUT_MAX_CHARS, DATA_BOX_ID_PATTERN, DATE_FORMAT_SPEC_HINT, DATE_VALUE_HINT, EMAIL_ADDRESS_PATTERN, SENTINEL_UUIDS, agentInputNormalization, agentInputNormalizationGuidance, agentInputNormalizationMetadata, askForFix, askSentence, countryCodeIn, isAbsentPlaceholder, isPlausibleLocale, isSentinelUuid, normalizeAgentInput, normalizeBoolean, normalizeCountry, normalizeDateBound, normalizeDateFormatSpec, normalizeDateValue, normalizeEli, normalizeEnumValue, normalizeLocale, normalizeNumber, normalizeNumberInRange, normalizeStringList, normalizeUuid, normalizeVocabularyValue, readAsAbsent, withModelPlaceholdersOmitted, withNullOptionalsOmitted, withOptionalsNullable };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@stll/agent-input",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.1",
|
|
4
4
|
"description": "Lenient readers for values agents write: dates, date bounds, date-format specs, numbers, booleans, locales, countries, enum and vocabulary values, ids, ELIs, string lists",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"agent",
|
|
@@ -71,7 +71,7 @@
|
|
|
71
71
|
"@stll/country-codes": "^0.2.0",
|
|
72
72
|
"@stll/fuzzy-search": "1.4.0",
|
|
73
73
|
"@stll/template-conditions": "^0.6.4",
|
|
74
|
-
"@stll/text-normalize": "^0.
|
|
74
|
+
"@stll/text-normalize": "^0.6.0",
|
|
75
75
|
"@stll/time": "0.4.1",
|
|
76
76
|
"better-result": "3.0.1"
|
|
77
77
|
},
|