@jini-ai/core 0.6.15-rc.2 → 0.6.16

package/dist/tool-exposure.js

@@ -1,4 +1,4 @@
-const SAFE_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
+const SAFE_NAME = /^[A-Za-z_]\w{0,63}$/;
 const MAX_NAME_LENGTH = 64;
 /** A stable, non-security hash keeps transformed names independent of discovery order.
  * Collisions are still checked against the entire namespace, never trusted as unique. */
@@ -11,7 +11,7 @@ function nameHash(id) {
 function nameBase(id) {
     if (SAFE_NAME.test(id))
         return id;
-    const readable = id.replace(/[^A-Za-z0-9_]/g, '_');
+    const readable = id.replace(/\W/g, '_');
     return `tool_${readable.slice(0, 49)}_${nameHash(id)}`;
 }
 /** O(c) collision probes for c occupied alternatives; suffix space stays inside the wire limit. */
@@ -22,7 +22,8 @@ function assignName(index, id) {
     let candidate = base;
     let counter = 1;
     while (index.occupied.has(candidate)) {
-        const suffix = `_${counter++}`;
+        const suffix = `_${counter}`;
+        counter += 1;
         candidate = `${base.slice(0, MAX_NAME_LENGTH - suffix.length)}${suffix}`;
     }
     index.forward.set(id, candidate);
@@ -89,6 +90,14 @@ function pinDescriptor(descriptor) {
     }
 }
 /** Count and byte caps reject new entries without evicting any previously callable definition. */
+/** A tool that can join the snapshot (pinned), or why it is skipped. */
+function promotionCandidate(descriptor, snapshot, limits) {
+    if (!descriptor)
+        return { reason: 'not-found' };
+    const pinned = pinDescriptor(descriptor);
+    const reason = limitReason(snapshot, pinned.bytes, limits);
+    return reason ? { reason } : { pinned };
+}
 function limitReason(snapshot, bytes, limits) {
     if (snapshot.tools.length >= limits.maxTools)
         return 'tool-limit';
@@ -107,21 +116,16 @@ function promoteDescriptors(snapshot, toolIds, descriptors, names, limits) {
     for (const toolId of new Set(toolIds)) {
         if (published.has(toolId))
             continue;
-        const descriptor = available.get(toolId);
-        if (!descriptor) {
-            skipped.push({ toolId, reason: 'not-found' });
-            continue;
+        const candidate = promotionCandidate(available.get(toolId), { tools, schemaBytes, revision: snapshot.revision }, limits);
+        if ('reason' in candidate) {
+            skipped.push({ toolId, reason: candidate.reason });
         }
-        const pinned = pinDescriptor(descriptor);
-        const reason = limitReason({ tools, schemaBytes, revision: snapshot.revision }, pinned.bytes, limits);
-        if (reason) {
-            skipped.push({ toolId, reason });
-            continue;
+        else {
+            assignName(names, toolId);
+            tools.push({ wireName: names.forward.get(toolId), descriptor: candidate.pinned.descriptor });
+            schemaBytes += candidate.pinned.bytes;
+            added.push(toolId);
         }
-        assignName(names, toolId);
-        tools.push({ wireName: names.forward.get(toolId), descriptor: pinned.descriptor });
-        schemaBytes += pinned.bytes;
-        added.push(toolId);
     }
     let next = snapshot;
     if (added.length > 0)

package/dist/tool-input-normalization.d.ts

@@ -1,4 +1,3 @@
-import type { ToolRegistration } from './tool-registry.js';
 export { ToolInputNormalizationError } from './tool-input-errors.js';
 /** A value-free account of canonicalization; domain hooks use the same contract as the gate. */
 export interface NormalizedToolInput {
@@ -8,8 +7,17 @@ export interface NormalizedToolInput {
 export type ToolInputNormalizer = (required: {
     input: Readonly<Record<string, unknown>>;
 }, optional?: Record<string, never>) => NormalizedToolInput | Promise<NormalizedToolInput>;
+/** Only the registration facts consumed by normalization; carries no execution authority. */
+interface NormalizationRegistration {
+    readonly descriptor: {
+        readonly id: string;
+        readonly inputSchema?: unknown;
+    };
+    readonly invocationSchema?: unknown;
+    readonly normalizeInput?: ToolInputNormalizer;
+}
 /** Canonicalize one batch layer (including declared aliases) before merging; leave value conversion
- * and domain hooks for final normalization. Throws ToolInputError for collisions within this layer, never across
+ * and domain hooks for final normalization. Throws ToolInputError for differing colliding values within this layer, never across
  * layers. Uses the same bounded schema walk as normalizeToolInput.
  * @example canonicalizeToolInputKeys({ input: { max_chars: '1000' }, schema });
  */
@@ -28,7 +36,7 @@ export declare function canonicalizeToolInputKeys({ input, schema }: {
  */
 export declare function normalizeToolInput({ input, registration }: {
     input: unknown;
-    registration: Pick<ToolRegistration, 'descriptor' | 'normalizeInput' | 'invocationSchema'>;
+    registration: NormalizationRegistration;
 }, _options?: Record<string, never>): Promise<NormalizedToolInput>;
 /** Keep result shapes intact and make rewrite notes visible in plain and MCP tool results. */
 export declare function withNormalizationNotes({ output, notes }: {

package/dist/tool-input-normalization.js

@@ -117,10 +117,14 @@ function unknownKeyError({ key, location, shape }, _options = {}) {
     const names = [...shape.names.filter(name => required.has(name)), ...shape.names.filter(name => !required.has(name))];
     const declared = names.map(name => `${name} (${required.has(name) ? 'required' : 'optional'})`).join(', ') || 'none';
     const hints = names.filter(name => nearMiss({ left: keyShape(key), right: keyShape(name) }));
-    const suggestion = hints.length ? ` Did you mean ${hints.map(name => `'${name}'`).join(', ')}?` : '';
+    const quotedHints = hints.map(name => `'${name}'`).join(', ');
+    const suggestion = hints.length ? ` Did you mean ${quotedHints}?` : '';
     return new ToolInputError({ message: `Unknown input '${location}'. Declared inputs: ${declared}.${suggestion} Resend with the declared name.` });
 }
-/** One key of an object: canonical rename + recursion, closed-schema refusal, or open pass-through. */
+/** One key of an object: canonical rename + recursion, closed-schema refusal, or open pass-through.
+ * Agreeing scalar aliases coalesce after coercion; differing values still fail without disclosure.
+ * @complexity The bounded child walk plus O(1) source/value checks.
+ */
 function normalizeEntry({ key, raw, shape, sources, step }) {
     const { path, depth, walk } = step;
     const location = path ? `${path}.${key}` : key;
@@ -131,13 +135,15 @@ function normalizeEntry({ key, raw, shape, sources, step }) {
         const childSchema = object(shape.schema.additionalProperties) ? shape.schema.additionalProperties : undefined;
         return [key, normalizeValue({ value: raw, schema: childSchema, step: { path: location, depth: depth + 1, walk } })];
     }
-    const previous = sources.get(target);
-    if (previous !== undefined)
-        throw new ToolInputError({ message: `Conflicting inputs '${previous}' and '${key}' both name '${target}'. Send only '${target}'.` });
-    sources.set(target, key);
     if (target !== key)
         walk.notes.push(`${location}→${target}`);
-    return [target, normalizeValue({ value: raw, schema: shape.properties[target], step: { path: `${path ? `${path}.` : ''}${target}`, depth: depth + 1, walk } })];
+    const parentPrefix = path ? `${path}.` : '';
+    const value = normalizeValue({ value: raw, schema: shape.properties[target], step: { path: `${parentPrefix}${target}`, depth: depth + 1, walk } });
+    const previous = sources.get(target);
+    if (previous !== undefined && !Object.is(previous.value, value))
+        throw new ToolInputError({ message: `Conflicting inputs '${previous.key}' and '${key}' both name '${target}'. Send only '${target}'.` });
+    sources.set(target, { key, value });
+    return [target, value];
 }
 function normalizeObject({ value, schema, step }) {
     const properties = object(schema.properties) ? schema.properties : {};
@@ -170,7 +176,7 @@ function walkRoot({ input, schema, notes, validateClosed, keysOnly }) {
     return normalizeValue({ value: input, schema, step: { path: '', depth: 0, walk: { notes, validateClosed, keysOnly } } });
 }
 /** Canonicalize one batch layer (including declared aliases) before merging; leave value conversion
- * and domain hooks for final normalization. Throws ToolInputError for collisions within this layer, never across
+ * and domain hooks for final normalization. Throws ToolInputError for differing colliding values within this layer, never across
  * layers. Uses the same bounded schema walk as normalizeToolInput.
  * @example canonicalizeToolInputKeys({ input: { max_chars: '1000' }, schema });
  */

package/dist/tool-metadata-types.d.ts

@@ -7,6 +7,11 @@ export interface ToolApprovalMetadata {
     readonly rule?: string;
 }
 export interface ToolMetadata<A extends ToolApprovalMetadata = ToolApprovalMetadata> {
+    /** Human-facing action name and optional button verb; presentation only, never authority. */
+    readonly title?: string;
+    /** Plain-language consequence shown before approval; never used to classify or authorize. */
+    readonly summary?: string;
+    readonly actionVerb?: string;
     /** Installed guidance capabilities needed by a writer; independent of permission and risk. */
     readonly guidanceCapabilities?: readonly string[];
     readonly search?: {

package/dist/tool-registry.d.ts

@@ -160,9 +160,18 @@ export interface ToolExecutionContext {
     readonly input: unknown;
     readonly signal: AbortSignal;
 }
+/** Value-free human-dialog outcomes recorded by the executor; never authorization grants. */
+export type ToolApprovalDecision = 'approved' | 'declined' | 'expired' | 'abandoned';
 /** Optional handler ports supplied by the invoking transport. */
 export interface ToolExecutionOptions {
     readonly emitSurface?: SurfaceEmitter;
+    /** Reports the human wait to the executor so concurrent writes can be refused. This is
+     * notification only; it never grants authority or substitutes for the human dialog. */
+    readonly onApprovalStateChange?: (required: {
+        pending: boolean;
+        /** Bound frontend's human-dialog outcome; observation only, never an authorization grant. */
+        decision?: ToolApprovalDecision;
+    }, optional?: Record<string, never>) => void;
     /** Invoke through the same executor, retaining this call's principal, run, cancellation and
      * transport gates. Rejects on denial, failed confirmation, validation or execution failure.
      * A composition-owned registry may retain a source registration behind a derived catalog card.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/core",
-  "version": "0.6.15-rc.2",
+  "version": "0.6.16",
   "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": {
@@ -28,7 +28,8 @@
       "./settings": "universal",
       "./settings/express": "node",
       "./plugin-directory": "universal",
-      "./filesystem": "universal"
+      "./filesystem": "universal",
+      "./optional-peer": "universal"
     },
     "isolation": {
       "entries": {
@@ -161,6 +162,11 @@
       "types": "./dist/filesystem.d.ts",
       "import": "./dist/filesystem.js",
       "default": "./dist/filesystem.js"
+    },
+    "./optional-peer": {
+      "types": "./dist/optional-peer.d.ts",
+      "import": "./dist/optional-peer.js",
+      "default": "./dist/optional-peer.js"
     }
   },
   "files": [
@@ -187,14 +193,6 @@
     "express": "^4.21.0",
     "@types/express": "^4.17.21"
   },
-  "peerDependencies": {
-    "express": "^4.21.0 || ^5.0.0"
-  },
-  "peerDependenciesMeta": {
-    "express": {
-      "optional": true
-    }
-  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",