@jini-ai/core 0.6.16 → 0.6.17

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @jini-ai/core
 
+## 0.6.17
+
+### Patch Changes
+
+- Mark required single-call fields in published batched-tool schemas and descriptions while preserving batching and clear missing-input errors.
+
 ## 0.6.16
 
 ### Patch Changes

package/dist/batch-tool-inputs.d.ts

@@ -20,11 +20,11 @@ export declare const BATCH_GUIDANCE_MARKER = " Batch: ";
 export declare function withoutBatchGuidance({ description }: {
     description: string;
 }, _optional?: {}): string;
-/** The top-level `required` fields {@link batchDescriptorFor} moved into its `items` description.
+/** The original top-level `required` fields retained by {@link batchDescriptorFor} as schema metadata.
  * A batch schema declares no top-level `required`, so a discovery signature built from it alone
  * makes a single call look argument-free and the model sends `{}` — this recovers them.
  * @returns The moved field names in order; [] for a non-batch schema or a tool that required none.
- * @complexity O(n) in the items description length; pure. */
+ * @complexity O(r) time and space for r required fields; pure. */
 export declare function batchItemRequiredFields({ inputSchema }: {
     inputSchema: unknown;
 }, _optional?: {}): string[];
@@ -61,15 +61,16 @@ export declare function batchOutcomeFor({ output }: {
 }, _options?: {}): BatchResult['outcome'] | undefined;
 /**
  * The descriptor a batchable tool publishes: its own schema plus an `items` array, its top-level
- * `required` list moved into the `items` description (a batch call sets those per item or once at
- * the top level through the declared legacy normalization), and batch guidance appended to its description.
+ * `required` list retained as metadata and described on required properties (a batch call sets
+ * those per item or once at the top level through the declared legacy normalization), and batch
+ * guidance appended to its description.
  *
  * @param required.descriptor - The tool's registered descriptor.
  * @param required.tool - Its batch settings.
  * @returns A new descriptor; the input is not mutated.
  * @throws {Error} If the tool publishes no object schema, or already has an `items` property
  * (the batch field would shadow it) — both developer errors caught at composition time.
- * @complexity O(p) in the schema's top-level property count.
+ * @complexity O(p + r) time and space for p top-level properties and r required fields.
  */
 export declare function batchDescriptorFor({ descriptor, tool }: {
     descriptor: ToolRegistration["descriptor"];

package/dist/batch-tool-inputs.js

@@ -18,19 +18,18 @@ export function withoutBatchGuidance({ description }, _optional = {}) {
 }
 const ITEM_NEEDS = " Each item needs ";
 const ITEM_NEEDS_END = " (inside each item).";
-/** The top-level `required` fields {@link batchDescriptorFor} moved into its `items` description.
+// Keep discovery requirements through descriptor/schema spreads without adding wire-schema keys.
+const BATCH_ITEM_REQUIRED_FIELDS = Symbol('batchItemRequiredFields');
+/** The original top-level `required` fields retained by {@link batchDescriptorFor} as schema metadata.
  * A batch schema declares no top-level `required`, so a discovery signature built from it alone
  * makes a single call look argument-free and the model sends `{}` — this recovers them.
  * @returns The moved field names in order; [] for a non-batch schema or a tool that required none.
- * @complexity O(n) in the items description length; pure. */
+ * @complexity O(r) time and space for r required fields; pure. */
 export function batchItemRequiredFields({ inputSchema }, _optional = {}) {
-    const items = isPlainObject(inputSchema) && isPlainObject(inputSchema.properties) ? inputSchema.properties.items : undefined;
-    const text = isPlainObject(items) && typeof items.description === "string" ? items.description : "";
-    const start = text.indexOf(ITEM_NEEDS);
-    const end = text.indexOf(ITEM_NEEDS_END, start);
-    if (start === -1 || end === -1)
+    if (!isPlainObject(inputSchema))
         return [];
-    return text.slice(start + ITEM_NEEDS.length, end).split(", ");
+    const schema = inputSchema;
+    return [...(schema[BATCH_ITEM_REQUIRED_FIELDS] ?? [])];
 }
 /** Used when a {@link BatchableTool} names no `maxItems`. */
 export const DEFAULT_MAX_BATCH_ITEMS = 25;
@@ -56,15 +55,16 @@ function isPlainObject(value) {
 }
 /**
  * The descriptor a batchable tool publishes: its own schema plus an `items` array, its top-level
- * `required` list moved into the `items` description (a batch call sets those per item or once at
- * the top level through the declared legacy normalization), and batch guidance appended to its description.
+ * `required` list retained as metadata and described on required properties (a batch call sets
+ * those per item or once at the top level through the declared legacy normalization), and batch
+ * guidance appended to its description.
  *
  * @param required.descriptor - The tool's registered descriptor.
  * @param required.tool - Its batch settings.
  * @returns A new descriptor; the input is not mutated.
  * @throws {Error} If the tool publishes no object schema, or already has an `items` property
  * (the batch field would shadow it) — both developer errors caught at composition time.
- * @complexity O(p) in the schema's top-level property count.
+ * @complexity O(p + r) time and space for p top-level properties and r required fields.
  */
 export function batchDescriptorFor({ descriptor, tool }, _optional = {}) {
     const schema = descriptor.inputSchema;
@@ -76,9 +76,18 @@ export function batchDescriptorFor({ descriptor, tool }, _optional = {}) {
     }
     const maxItems = tool.maxItems ?? DEFAULT_MAX_BATCH_ITEMS;
     const requiredFields = schema.required ?? [];
+    const requiredNames = new Set(requiredFields);
+    const properties = Object.fromEntries(Object.entries(schema.properties).map(([name, property]) => [
+        name,
+        requiredNames.has(name) && isPlainObject(property)
+            ? { ...property, description: `Required for a single call (or set it in each item). ${property.description ?? ""}` }
+            : property,
+    ]));
     const rest = { ...schema };
     delete rest.required;
     const needs = requiredFields.length > 0 ? `${ITEM_NEEDS}${requiredFields.join(", ")}${ITEM_NEEDS_END}` : "";
+    // Inside the removable guidance so search keeps only the authored description and signature.
+    const singleNeeds = requiredFields.length > 0 ? `Single call requires: ${requiredFields.join(", ")}. ` : "";
     const items = {
         type: "array",
         minItems: 1,
@@ -91,8 +100,9 @@ export function batchDescriptorFor({ descriptor, tool }, _optional = {}) {
         ...descriptor,
         description: `${descriptor.description ?? ""}${BATCH_GUIDANCE_MARKER}to do several at once, pass items: [{...}, ...] (up to ${maxItems}) in ONE call instead of one call per item. ` +
             "Canonical shape: {items:[{...}, ...]} only. Legacy shared top-level fields are normalized into each item; item values win. " +
+            singleNeeds +
             "Returns { batch: true, outcome: completed | partial_failure | error, total, succeeded, failed, results: [{ index, ok, result | error }] }; one item's failure does not stop the others.",
-        inputSchema: { ...rest, properties: { ...schema.properties, items } },
+        inputSchema: { ...rest, [BATCH_ITEM_REQUIRED_FIELDS]: [...requiredFields], properties: { ...properties, items } },
     };
 }
 /** The domain message without `withSchemaOnRejection`'s appended schema: the text before the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/core",
-  "version": "0.6.16",
+  "version": "0.6.17",
   "description": "The Jini kernel: typed DI tokens, pack composition and lifecycle, the tool registry, redaction, and origin/API-token auth primitives. Zero dependencies.",
   "license": "Apache-2.0",
   "repository": {