@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 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$1 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
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$1(input)) return readObjectSpec(input);
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
- 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 };
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.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.5.2",
74
+ "@stll/text-normalize": "^0.6.0",
75
75
  "@stll/time": "0.4.1",
76
76
  "better-result": "3.0.1"
77
77
  },