@jini-ai/core 0.4.6 → 0.4.8

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @jini-ai/core
 
+## 0.4.8 — 2026-10-16
+
+- `applyTargetScope`: one optional `site` input on read-only tools; the host resolves the target and a peer handler/principal, writes refuse a foreign target (3786c8f0).
+
+## 0.4.7 — 2026-10-16
+
+- `requireString`, `requireNumber` and `requireObject` errors list the keys the call actually received and flag unsupported `items[]` batching (a6ac9d7e, c7557838).
+
 ## 0.4.6 — 2026-10-14
 
 - Express 5 accepted: the optional `express` peer is now `^4.21.0 || ^5.0.0` (1442d875), so an Express 5 host no longer hits ERESOLVE.

package/dist/index.d.ts

@@ -21,6 +21,7 @@ export * from './naming.js';
 export type { AgentToolSideEffect, AgentToolActorClassRule, AgentToolDefinition } from './agent-tools.js';
 export * from "./registration-kit.js";
 export * from "./approval.js";
+export * from './target-scope.js';
 export * from "./native-regexp.js";
 export { ForbiddenError as ToolPermissionDeniedError, requireToolPermission, adaptLegacyAuthorize, type LegacyToolAuthorizeFn, type AuthorizationPort as ToolPermissionAuthorizationPort, type RequireToolPermissionRequired, type RequireToolPermissionOptional, } from "./tool-permissions.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -17,6 +17,7 @@ export * from './contribution-registry.js';
 export * from './naming.js';
 export * from "./registration-kit.js";
 export * from "./approval.js";
+export * from './target-scope.js';
 export * from "./native-regexp.js";
 export { ForbiddenError as ToolPermissionDeniedError, requireToolPermission, adaptLegacyAuthorize, } from "./tool-permissions.js";
 //# sourceMappingURL=index.js.map

package/dist/registration-kit.d.ts

@@ -139,6 +139,11 @@ export declare function indexCatalogById<T extends {
 export declare function requireInputRecord(required: {
     input: unknown;
 }, _optional?: Record<string, never>): Record<string, unknown>;
+/**
+ * Reads a required non-empty string, with received-key hints when the field is missing.
+ * @throws {ToolInputError} If the field is missing, empty, or not a string.
+ * @complexity O(k) for k input keys on a missing-field rejection; otherwise O(1).
+ */
 export declare function requireString(required: {
     input: Record<string, unknown>;
     key: string;

package/dist/registration-kit.js

@@ -110,11 +110,33 @@ export function requireInputRecord(required, _optional = {}) {
         throw new ToolInputError({ message: "input must be an object" });
     return candidate.value;
 }
+/**
+ * Builds received-key and unsupported-batching hints for a missing required field.
+ * @complexity O(k) for k input keys.
+ */
+function missingFieldHint(required, _optional = {}) {
+    const { input } = required;
+    // Show names, never values, so a wrong-key or batch call can be corrected without exposing content.
+    const keys = Object.keys(input);
+    let hint = keys.length > 0 ? `; received: ${keys.join(", ")}` : "";
+    if (Array.isArray(input.items)) {
+        hint += "; this tool takes one input per call — items[] batching is not supported here";
+    }
+    return hint;
+}
+/**
+ * Reads a required non-empty string, with received-key hints when the field is missing.
+ * @throws {ToolInputError} If the field is missing, empty, or not a string.
+ * @complexity O(k) for k input keys on a missing-field rejection; otherwise O(1).
+ */
 export function requireString(required, _optional = {}) {
     const { input, key } = required;
     const value = input[key];
     if (typeof value !== "string" || value.length === 0) {
-        throw new ToolInputError({ message: `'${key}' (non-empty string) is required` });
+        let message = `'${key}' (non-empty string) is required`;
+        if (value === undefined)
+            message += missingFieldHint({ input });
+        throw new ToolInputError({ message });
     }
     return value;
 }
@@ -122,7 +144,10 @@ export function requireNumber(requiredArgs, optionalArgs = {}) {
     const { input, key } = requiredArgs;
     const value = input[key];
     if (typeof value !== "number" || !Number.isFinite(value)) {
-        throw new ToolInputError({ message: `'${key}' (number) is required` });
+        let message = `'${key}' (number) is required`;
+        if (value === undefined)
+            message += missingFieldHint({ input });
+        throw new ToolInputError({ message });
     }
     return value;
 }
@@ -131,7 +156,10 @@ export function requireObject(requiredArgs, optionalArgs = {}) {
     const value = input[key];
     const candidate = { value };
     if (!isRecord(candidate) || Array.isArray(candidate.value)) {
-        throw new ToolInputError({ message: `'${key}' (object) is required` });
+        let message = `'${key}' (object) is required`;
+        if (value === undefined)
+            message += missingFieldHint({ input });
+        throw new ToolInputError({ message });
     }
     return candidate.value;
 }

package/dist/target-scope.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Keep the same tool ids plus one optional target input instead of a tool per resource:
+ * each tool keeps one permission, approval class, search entry and card. Hosts own target
+ * resolution; core knows nothing about their sites, registries or files.
+ *
+ * Writes refuse foreign targets rather than silently ignoring the unknown key. A handler
+ * that ignores unknown keys would otherwise write to the CURRENT target under the wrong label.
+ */
+import type { Principal } from './principal.js';
+import { type ToolHandler, type ToolRegistration } from './tool-registry.js';
+/** A host either keeps the current handler and principal or supplies both for a peer. */
+export type TargetResolution = 'current' | {
+    readonly handler: ToolHandler;
+    readonly principal: Principal;
+};
+/**
+ * Scope read-only registrations through host-supplied target ports and guard other tools
+ * against accidentally executing on the current target under a foreign target's name.
+ * @param required.registrations - Ordered tool catalog; registrations and schemas are never mutated.
+ * @param required.resolveTarget - Resolve a scoped read to the current handler or a peer handler and principal.
+ * @param required.isCurrentTarget - Check whether an unscoped tool names the current target.
+ * @param optional - Target input name, schema description, refusal text and a narrowing scope predicate.
+ * @returns A new array in the same order, preserving tools that already own the target input.
+ * @throws ToolInputError from a wrapped handler for a non-string target or a refused foreign target.
+ * Host port errors propagate unchanged from the wrapped handler.
+ * @complexity O(n) over registrations, plus copying supported schemas' top-level properties.
+ * @example applyTargetScope({ registrations, resolveTarget, isCurrentTarget }, { param: 'workspace' });
+ */
+export declare function applyTargetScope(required: {
+    readonly registrations: readonly ToolRegistration[];
+    /** Called only for scoped tools with a named target. Throw to refuse with the host's message unchanged. */
+    resolveTarget(required: {
+        target: string;
+        toolId: string;
+        principal: Principal;
+    }): Promise<TargetResolution>;
+    /** Called only for unscoped tools (writes and host-excluded reads) with a named target. */
+    isCurrentTarget(required: {
+        target: string;
+    }): boolean | Promise<boolean>;
+}, optional?: {
+    readonly param?: string;
+    readonly describeParam?: string;
+    readonly refuseMessage?: string;
+    /** Narrows read-only tools; returning true can never scope a tool that is not read-only. */
+    readonly scoped?: (required: {
+        registration: ToolRegistration;
+    }) => boolean;
+}): ToolRegistration[];
+//# sourceMappingURL=target-scope.d.ts.map

package/dist/target-scope.js

@@ -0,0 +1,66 @@
+import { isNonArrayRecord } from './records.js';
+import { isReadOnlyTool, ToolInputError } from './tool-registry.js';
+/** Narrow the shared record predicate to ordinary or null-prototype objects, excluding instances. */
+function isPlainObject(value) {
+    if (!isNonArrayRecord({ value }))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+/** Add an optional input only to supported object schemas; preserve other dialects unchanged. */
+function withTargetParam(schema, param, description) {
+    if (schema === undefined)
+        return { type: 'object', properties: { [param]: { type: 'string', description } } };
+    if (!isPlainObject(schema))
+        return schema;
+    if (!isPlainObject(schema.properties) && schema.type !== 'object')
+        return schema;
+    return { ...schema, properties: { ...(isPlainObject(schema.properties) ? schema.properties : {}), [param]: { type: 'string', description } } };
+}
+/**
+ * Scope read-only registrations through host-supplied target ports and guard other tools
+ * against accidentally executing on the current target under a foreign target's name.
+ * @param required.registrations - Ordered tool catalog; registrations and schemas are never mutated.
+ * @param required.resolveTarget - Resolve a scoped read to the current handler or a peer handler and principal.
+ * @param required.isCurrentTarget - Check whether an unscoped tool names the current target.
+ * @param optional - Target input name, schema description, refusal text and a narrowing scope predicate.
+ * @returns A new array in the same order, preserving tools that already own the target input.
+ * @throws ToolInputError from a wrapped handler for a non-string target or a refused foreign target.
+ * Host port errors propagate unchanged from the wrapped handler.
+ * @complexity O(n) over registrations, plus copying supported schemas' top-level properties.
+ * @example applyTargetScope({ registrations, resolveTarget, isCurrentTarget }, { param: 'workspace' });
+ */
+export function applyTargetScope(required, optional = {}) {
+    const { param = 'site', describeParam = 'Optional target name. Omit to use the current target.', refuseMessage = 'This tool runs only on the current target.' } = optional;
+    return required.registrations.map(registration => {
+        const { descriptor } = registration;
+        const schema = { value: descriptor.inputSchema };
+        const properties = { value: isNonArrayRecord(schema) ? schema.value.properties : undefined };
+        if (isNonArrayRecord(properties) && Object.hasOwn(properties.value, param))
+            return registration;
+        const scoped = isReadOnlyTool({ descriptor }) && (optional.scoped?.({ registration }) ?? true);
+        const inputSchema = scoped ? withTargetParam(descriptor.inputSchema, param, describeParam) : descriptor.inputSchema;
+        return {
+            ...registration,
+            descriptor: inputSchema === descriptor.inputSchema ? descriptor : { ...descriptor, inputSchema },
+            handler: async (ctx, options) => {
+                if (!isPlainObject(ctx.input) || !Object.hasOwn(ctx.input, param))
+                    return registration.handler(ctx, options);
+                const target = ctx.input[param];
+                if (typeof target !== 'string')
+                    throw new ToolInputError({ message: `${param} must be a string` });
+                const { [param]: _target, ...input } = ctx.input;
+                if (!scoped) {
+                    if (!await required.isCurrentTarget({ target }))
+                        throw new ToolInputError({ message: refuseMessage });
+                    return registration.handler({ ...ctx, input }, options);
+                }
+                const peer = await required.resolveTarget({ target, toolId: descriptor.id, principal: ctx.principal });
+                if (peer === 'current')
+                    return registration.handler({ ...ctx, input }, options);
+                return peer.handler({ ...ctx, input, principal: peer.principal }, options);
+            },
+        };
+    });
+}
+//# sourceMappingURL=target-scope.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/core",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "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": {