@jini-ai/core 0.4.1 → 0.4.3

package/dist/tool-registry.js

@@ -33,6 +33,48 @@ export class ToolInputError extends Error {
     }
 }
 const registrationsByRegistry = new WeakMap();
+// Static register() remains append-only; scoped host contributions below explicitly own removal.
+const registryRevisions = new WeakMap();
+/** A host can invalidate its disposable discovery snapshot without exposing handlers. */
+export function toolRegistryRevision(required, _optional = {}) {
+    return registryRevisions.get(required.registry);
+}
+/** Revocable registration scope on the SAME registry the executor owns. Collision validation
+ * completes before mutation, so a failed replacement cannot lose the working generation.
+ * Only this closure may remove its own registrations; native and other scopes remain protected.
+ * Already-authorized closures are revoked too: confirmation can await a human across disable. */
+export function createToolRegistrationScope(required, _optional = {}) {
+    const registrations = registrationsByRegistry.get(required.registry);
+    if (!registrations)
+        throw new Error('registration scopes require a core ToolRegistry');
+    let owned = new Set();
+    let generation = 0;
+    return {
+        replace({ registrations: next }, _optional = {}) {
+            const ids = new Set();
+            for (const registration of next) {
+                const id = registration.descriptor.id;
+                if (ids.has(id) || (registrations.has(id) && !owned.has(id)))
+                    throw new Error(`ToolRegistry: tool "${id}" is already registered`);
+                ids.add(id);
+            }
+            generation++;
+            const current = generation;
+            for (const id of owned)
+                registrations.delete(id);
+            for (const registration of next)
+                registrations.set(registration.descriptor.id, { ...registration,
+                    handler: (input, options) => {
+                        if (generation !== current)
+                            throw new Error('tool registration was revoked');
+                        return registration.handler(input, options);
+                    },
+                });
+            owned = ids;
+            registryRevisions.set(required.registry, (registryRevisions.get(required.registry) ?? 0) + 1);
+        },
+    };
+}
 /**
  * Creates an empty, append-only `ToolRegistry`.
  *
@@ -51,6 +93,7 @@ export function createToolRegistry(_required) {
                 throw new Error(`ToolRegistry: tool "${registration.descriptor.id}" is already registered`);
             }
             registrations.set(registration.descriptor.id, registration);
+            registryRevisions.set(registry, (registryRevisions.get(registry) ?? 0) + 1);
         },
         has({ toolId }) {
             return registrations.has(toolId);
@@ -60,6 +103,7 @@ export function createToolRegistry(_required) {
         },
     };
     registrationsByRegistry.set(registry, registrations);
+    registryRevisions.set(registry, 0);
     return registry;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/core",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "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": {
@@ -20,7 +20,50 @@
       "./contribution-registry": "universal",
       "./naming": "universal",
       "./primitives": "universal",
-      "./text": "universal"
+      "./fetch": "universal",
+      "./text": "universal",
+      "./settings": "universal",
+      "./settings/express": "node",
+      "./plugin-directory": "universal"
+    },
+    "isolation": {
+      "entries": {
+        "./primitives": "core",
+        "./fetch": "fetch",
+        "./settings": "settings",
+        "./settings/express": "settings"
+      },
+      "domains": {
+        "fetch": [
+          "src/fetch"
+        ],
+        "settings": [
+          "src/settings"
+        ]
+      },
+      "shared": [
+        "src/tool-permissions.ts"
+      ],
+      "forbidden": {
+        "universal": [
+          "node:",
+          "express",
+          "react",
+          "@jini-ai/cms"
+        ],
+        ".": [
+          "node:",
+          "express",
+          "react",
+          "@jini-ai/cms",
+          "@jini-ai/core/settings",
+          "./settings",
+          "../settings"
+        ],
+        "./settings/express": [
+          "@jini-ai/cms"
+        ]
+      }
     }
   },
   "type": "module",
@@ -63,10 +106,30 @@
       "import": "./dist/primitives/index.js",
       "default": "./dist/primitives/index.js"
     },
+    "./fetch": {
+      "types": "./dist/fetch/index.d.ts",
+      "import": "./dist/fetch/index.js",
+      "default": "./dist/fetch/index.js"
+    },
     "./text": {
       "types": "./dist/text/index.d.ts",
       "import": "./dist/text/index.js",
       "default": "./dist/text/index.js"
+    },
+    "./settings": {
+      "types": "./dist/settings/index.d.ts",
+      "import": "./dist/settings/index.js",
+      "default": "./dist/settings/index.js"
+    },
+    "./settings/express": {
+      "types": "./dist/settings/express/index.d.ts",
+      "import": "./dist/settings/express/index.js",
+      "default": "./dist/settings/express/index.js"
+    },
+    "./plugin-directory": {
+      "types": "./plugin-directory.d.ts",
+      "import": "./plugin-directory.js",
+      "default": "./plugin-directory.js"
     }
   },
   "files": [
@@ -80,14 +143,26 @@
     "!dist/**/*.test.d.ts.map",
     "!dist/**/__tests__/**",
     "!dist/**/*.typecheck.*",
-    "!dist/**/*.map"
+    "!dist/**/*.map",
+    "plugin-directory.js",
+    "plugin-directory.d.ts"
   ],
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
   },
   "devDependencies": {
-    "@vitest/coverage-v8": "^2.1.9"
+    "@vitest/coverage-v8": "^2.1.9",
+    "express": "^4.21.0",
+    "@types/express": "^4.17.21"
+  },
+  "peerDependencies": {
+    "express": "^4.21.0"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    }
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/plugin-directory.d.ts

@@ -0,0 +1,32 @@
+/** Identical identity metadata for portable agent packages and host site plugins. */
+export interface PluginIdentityExtension {
+  readonly id?: string;
+  readonly provides?: readonly string[];
+  readonly [key: string]: unknown;
+}
+export interface PluginIdentity {
+  readonly id: string;
+  readonly keywords: readonly string[];
+  readonly provides: readonly string[];
+  readonly warnings: readonly string[];
+}
+export interface PluginProvider {
+  readonly id: string;
+  readonly version: string | null;
+  readonly enabled: boolean;
+  readonly family: string;
+  /** Stable storage/activation key; publisher identity never becomes a filesystem path. */
+  readonly localId: string;
+  readonly keywords: readonly string[];
+  readonly provides: readonly string[];
+}
+export interface PluginLookupPort {
+  getPlugin(required: { readonly id: string; readonly family?: string }, optional?: Record<string, never>): Promise<PluginProvider | null>;
+  findProviders(required: { readonly capability: string }, optional?: { readonly enabledOnly?: boolean }): Promise<readonly PluginProvider[]>;
+}
+export type PluginIdentityCandidate = Pick<PluginProvider, 'id' | 'family' | 'localId'>;
+export function assertPluginIdentityAvailable(required: { readonly candidate: PluginIdentityCandidate; readonly installed: readonly PluginProvider[] }, optional?: Record<string, never>): void;
+export function createPluginLookupFacade(required: { readonly lookup: PluginLookupPort }, optional?: Record<string, never>): PluginLookupPort;
+export function validatePluginIdentity(required: { readonly manifest: unknown; readonly namespace: string }, optional?: Record<string, never>): { readonly errors: readonly string[] };
+export function readPluginIdentity(required: { readonly manifest: Readonly<Record<string, unknown>>; readonly namespace: string; readonly name?: string }, optional?: Record<string, never>): PluginIdentity;
+export function createPluginLookup(required: { readonly listPlugins: (required: Record<string, never>, optional?: Record<string, never>) => Promise<readonly PluginProvider[]> }, optional?: { readonly warn?: (message: string) => void }): PluginLookupPort;

package/plugin-directory.js

@@ -0,0 +1,140 @@
+/** Shared publisher identity and live plugin lookup. Source-backed, like persistent-state:
+ * hosts can adopt the additive entry without replacing a running server's compiled packages. */
+const SEGMENT = '[a-z0-9]+(?:[.-][a-z0-9]+)*';
+const ID_PATTERN = new RegExp(`^${SEGMENT}/${SEGMENT}$`);
+// Legacy site ids used a looser grammar than portable Agent Plugin names. Preserve those keys
+// in unknown/<name>; only explicitly declared publisher ids use the new strict grammar.
+const LEGACY_NAME_PATTERN = /^[a-z0-9.-]+$/;
+const CAPABILITY_PATTERN = new RegExp(`^${SEGMENT}(?::${SEGMENT})?$`);
+const object = value => typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/** Collects identity errors without mutating the portable manifest. Absent metadata is legacy.
+ * @param {{manifest: unknown, namespace: string}} required
+ * @param {Record<string, never>} [optional]
+ * @returns {{errors: string[]}}
+ * @complexity O(k + p) in keyword and provides entries; no I/O.
+ */
+export function validatePluginIdentity({ manifest, namespace }, optional = {}) {
+  const errors = [];
+  if (!object(manifest)) return { errors: ['Plugin manifest must be an object.'] };
+  if (manifest.extensions !== undefined && !object(manifest.extensions)) return { errors: [...errors, 'Plugin extensions must be an object.'] };
+  const extension = manifest.extensions?.[namespace];
+  if (extension === undefined) return { errors };
+  if (!object(extension)) return { errors: [...errors, 'Plugin identity extension must be an object.'] };
+  if (extension.id !== undefined && (typeof extension.id !== 'string' || extension.id.length > 129 || !ID_PATTERN.test(extension.id))) {
+    errors.push('Plugin id must have the form publisher/name (lowercase letters, digits, dots and hyphens).');
+  } else if (typeof extension.id === 'string' && extension.id.startsWith('unknown/')) {
+    // Only the host may infer a legacy identity; a publisher cannot claim its upgrade exemption.
+    errors.push("Plugin publisher 'unknown' is reserved for legacy identities.");
+  }
+  if (extension.provides !== undefined && (!Array.isArray(extension.provides) || !extension.provides.every(p => typeof p === 'string' && p.length <= 129 && CAPABILITY_PATTERN.test(p)))) {
+    errors.push('Plugin provides must be an array of capability names.');
+  }
+  return { errors };
+}
+
+/** Resolves one identity; warns on missing ids and refuses malformed declarations.
+ * @param {{manifest: Record<string, unknown>, namespace: string, name?: string}} required
+ * @param {Record<string, never>} [optional]
+ * @returns {{id: string, keywords: string[], provides: string[], warnings: string[]}}
+ * @throws {TypeError} Malformed identity metadata or missing legacy name.
+ * @example readPluginIdentity({ manifest: { name: 'example' }, namespace: 'host' })
+ * @complexity O(k + p), copying arrays so a caller cannot mutate manifest metadata.
+ */
+export function readPluginIdentity({ manifest, namespace, name }, optional = {}) {
+  const { errors } = validatePluginIdentity({ manifest, namespace });
+  if (errors.length) throw new TypeError(errors.join(' '));
+  const extension = manifest.extensions?.[namespace];
+  const localName = name ?? manifest.name;
+  if (extension?.id === undefined && (typeof localName !== 'string' || !LEGACY_NAME_PATTERN.test(localName))) {
+    throw new TypeError('A valid plugin name is required for a legacy identity.');
+  }
+  const id = extension?.id ?? `unknown/${localName}`;
+  // Keywords are advisory portable metadata: older manifests accepted mixed or non-array values.
+  // The portable parser's coercion (non-string entries dropped, non-arrays ignored) lives here
+  // so validation and lookup normalize advisory metadata through the same owner.
+  const keywords = Array.isArray(manifest.keywords) ? manifest.keywords.filter(k => typeof k === 'string' && k.trim().length > 0) : [];
+  const warnings = extension?.id === undefined ? [`Plugin '${localName}' has no publisher-qualified id; using '${id}'.`] : [];
+  if (manifest.keywords !== undefined && (!Array.isArray(manifest.keywords) || keywords.length !== manifest.keywords.length)) {
+    warnings.push('Plugin keywords must be an array of nonempty strings; invalid keywords were ignored.');
+  }
+  return { id, keywords, provides: [...(extension?.provides ?? [])], warnings };
+}
+
+/** Rejects id reuse and publisher changes at an existing storage slot. Legacy metadata may
+ * acquire its first publisher id during an upgrade; a declared publisher can never be replaced.
+ * @param {{candidate: {id: string, family: string, localId: string}, installed: import('./plugin-directory.js').PluginProvider[]}} required
+ * @param {Record<string, never>} [optional]
+ * @returns {void}
+ * @throws {Error} Conflicting publisher identity.
+ * @complexity O(n) for n installed providers.
+ */
+export function assertPluginIdentityAvailable({ candidate, installed }, optional = {}) {
+  for (const plugin of installed) {
+    const sameSlot = plugin.family === candidate.family && plugin.localId === candidate.localId;
+    if (sameSlot) {
+      if (plugin.id !== candidate.id && plugin.id !== `unknown/${candidate.localId}`) {
+        throw new Error(`Plugin '${candidate.localId}' belongs to a different publisher identity.`);
+      }
+    } else if (plugin.id === candidate.id && !(plugin.family !== candidate.family && candidate.id === `unknown/${candidate.localId}` && plugin.id === `unknown/${plugin.localId}`)) {
+      throw new Error(`Duplicate plugin id '${candidate.id}'.`);
+    }
+  }
+}
+
+/** Restricts an SDK handle at runtime, not just through a TypeScript interface. A host may carry
+ * lifecycle mutation ports, but a plugin's discovery surface exposes only these metadata reads.
+ * @param {{lookup: import('./plugin-directory.js').PluginLookupPort}} required
+ * @param {Record<string, never>} [optional]
+ * @returns {import('./plugin-directory.js').PluginLookupPort}
+ * @complexity O(1); delegates live reads without copying host methods.
+ */
+export function createPluginLookupFacade({ lookup }, optional = {}) {
+  return {
+    getPlugin: (required, options = {}) => lookup.getPlugin(required, options),
+    findProviders: (required, options = {}) => lookup.findProviders(required, options),
+  };
+}
+
+/** Live, metadata-only directory over injected workspace-scoped sources. No plugin imports.
+ * Later duplicate providers are omitted with a warning, preserving the source's incumbent order.
+ * Admission checks the unfiltered installs separately, including disabled/cross-family collisions.
+ * Legacy fallback ids are family-scoped; an unscoped ambiguous get returns null.
+ * @param {{listPlugins: (required: {}, optional?: {}) => Promise<import('./plugin-directory.js').PluginProvider[]>}} required
+ * @param {{warn?: (message: string) => void}} [optional]
+ * @returns {import('./plugin-directory.js').PluginLookupPort}
+ * @example createPluginLookup({ listPlugins: async () => [] })
+ * @complexity O(n log n) per lookup, n installed plugins. Fresh reads preserve revocation.
+ */
+export function createPluginLookup({ listPlugins }, optional = {}) {
+  const warn = optional.warn ?? console.warn;
+  async function snapshot() {
+    const plugins = await listPlugins({}, {});
+    const seen = new Set();
+    const unique = [];
+    for (const plugin of plugins) {
+      const key = plugin.id === `unknown/${plugin.localId}` ? `${plugin.family}:${plugin.id}` : plugin.id;
+      if (seen.has(key)) {
+        warn(`Duplicate plugin id '${plugin.id}'; later provider omitted from metadata lookup.`);
+        continue;
+      }
+      seen.add(key);
+      unique.push(plugin);
+    }
+    // Project metadata explicitly: host paths, services and additional source properties never
+    // leave this boundary, and a consumer cannot mutate the source's discovery arrays.
+    return unique.map(plugin => ({
+      id: plugin.id, version: plugin.version, enabled: plugin.enabled, family: plugin.family,
+      localId: plugin.localId, keywords: [...plugin.keywords], provides: [...plugin.provides],
+    })).sort((a, b) => a.id.localeCompare(b.id));
+  }
+  return {
+    async getPlugin({ id, family }, options = {}) {
+      const matches = (await snapshot()).filter(plugin => plugin.id === id && (family === undefined || plugin.family === family));
+      return matches.length === 1 ? matches[0] : null;
+    },
+    async findProviders({ capability }, { enabledOnly = false } = {}) {
+      return (await snapshot()).filter(plugin => (!enabledOnly || plugin.enabled) && plugin.provides.includes(capability));
+    },
+  };
+}