@particle-academy/prism-harness 0.8.0 → 0.9.0

package/dist/tools.js

@@ -1,33 +1,107 @@
 import { HarnessError } from './errors.js';
-/**
- * Which tools exist, and which a given run may be offered.
- *
- * Three ways in, because the three answer different questions: a tool that is
- * always the same (`register`), one that needs the session to build
- * (`registerFactory`), and a set discovered at resolve time — an MCP server's
- * catalogue, say (`registerProvider`).
- */
+import { validateAgent } from './address.js';
+import { RegistrationCollision, registrationOwner } from './registration.js';
 export class ToolRegistry {
     #tools = new Map();
     #factories = new Map();
-    #providers = [];
-    register(tool) {
+    #metadata = new Map();
+    #providers = new Map();
+    #agents = new Map();
+    #staticOwners = new Map();
+    #factoryOwners = new Map();
+    #refuseDuplicates;
+    namespace;
+    root;
+    constructor(options = null, root) {
+        if (options !== null && typeof options !== 'string' && (typeof options !== 'object' || Array.isArray(options)))
+            throw new TypeError('Registry options must be an options object, agent string or null');
+        this.namespace = typeof options === 'string' ? options : null;
+        this.root = root;
+        const setting = options !== null && typeof options === 'object' ? options.refuseDuplicates : (root === undefined ? undefined : root.#refuseDuplicates);
+        if (setting !== undefined && typeof setting !== 'boolean')
+            throw new TypeError('refuseDuplicates must be a boolean');
+        this.#refuseDuplicates = setting ?? false;
+        validateAgent(this.namespace);
+        for (const key of ['namespace', 'root'])
+            Object.defineProperty(this, key, { writable: false, configurable: false });
+    }
+    /** Immutable namespace views share registrations, never a current-agent flag. */
+    forAgent(agent) {
+        validateAgent(agent);
+        const root = this.root ?? this;
+        if (agent === null)
+            return root;
+        let view = root.#agents.get(agent);
+        if (!view) {
+            view = new ToolRegistry(agent, root);
+            root.#agents.set(agent, view);
+        }
+        return view;
+    }
+    register(tool, owner) {
+        this.#claim(tool.name, owner, 'static');
         this.#tools.set(tool.name, tool);
+        this.#staticOwners.set(tool.name, registrationOwner(owner, this.namespace));
         return this;
     }
-    registerMany(tools) {
+    registerMany(tools, owner) {
         for (const tool of tools)
-            this.register(tool);
+            this.register(tool, owner);
+        return this;
+    }
+    registerFactory(name, factory, owner) {
+        this.#claim(name, owner, 'factory');
+        this.#factories.set(name, factory);
+        this.#factoryOwners.set(name, registrationOwner(owner, this.namespace));
+        return this;
+    }
+    registerProvider(provider, owner, name) {
+        const label = registrationOwner(owner, this.namespace);
+        const id = name ?? (this.namespace === null ? `provider:${this.#providers.size}` : undefined);
+        if (!id)
+            throw new TypeError('A named provider requires a registration name.');
+        const previous = this.#providers.get(id);
+        if (this.#strict() && previous)
+            throw new RegistrationCollision(this.namespace, id, previous.owner, label);
+        this.#providers.set(id, { provider, owner: label });
+        return this;
+    }
+    replace(tool, predecessorOwner, owner) {
+        this.#claim(tool.name, owner, 'static', predecessorOwner);
+        this.#tools.set(tool.name, tool);
+        this.#staticOwners.set(tool.name, registrationOwner(owner, this.namespace));
         return this;
     }
-    registerFactory(name, factory) {
+    replaceFactory(name, factory, predecessorOwner, owner) {
+        this.#claim(name, owner, 'factory', predecessorOwner);
         this.#factories.set(name, factory);
+        this.#factoryOwners.set(name, registrationOwner(owner, this.namespace));
         return this;
     }
-    registerProvider(provider) {
-        this.#providers.push(provider);
+    replaceProvider(name, provider, predecessorOwner, owner) {
+        const label = registrationOwner(owner, this.namespace), previous = this.#providers.get(name);
+        if (!previous || previous.owner !== predecessorOwner)
+            throw new Error('Replacement must name the registered predecessor owner.');
+        this.#providers.set(name, { provider, owner: label });
         return this;
     }
+    #claim(name, owner, source, predecessor) {
+        const label = registrationOwner(owner, this.namespace), previous = this.#metadata.get(name);
+        if (predecessor !== undefined) {
+            if (!previous || previous.owner !== predecessor)
+                throw new Error('Replacement must name the registered predecessor owner.');
+        }
+        else if (this.#strict() && previous)
+            throw new RegistrationCollision(this.namespace, name, previous.owner, label);
+        if (this.#strict() || predecessor !== undefined) {
+            this.#tools.delete(name);
+            this.#factories.delete(name);
+            this.#staticOwners.delete(name);
+            this.#factoryOwners.delete(name);
+        }
+        this.#metadata.set(name, { owner: label, source });
+    }
+    #strict() { return this.namespace !== null || this.#refuseDuplicates; }
     /** Every name this registry can produce without a session. */
     names() {
         return [...new Set([...this.#tools.keys(), ...this.#factories.keys()])].sort();
@@ -41,11 +115,26 @@ export class ToolRegistry {
      * run wondering why the model never called it.
      */
     async resolve(names, session) {
-        const provided = new Map();
+        const detailed = await this.resolveDetailed(names, session);
+        return new Map([...detailed].map(([name, entry]) => [name, entry.tool]));
+    }
+    /** The offer path and inspection path consume the same ownership result. */
+    async resolveDetailed(names, session) {
+        if (session && session.agent !== this.namespace) {
+            if (this.namespace !== null)
+                throw new Error('Harness registry/session agent mismatch.');
+            return this.forAgent(session.agent).resolveDetailed(names, session);
+        }
+        const provided = new Map(), metadata = new Map(this.#metadata);
         if (session !== undefined) {
-            for (const provider of this.#providers) {
-                for (const tool of await provider(session))
+            for (const { provider, owner } of this.#providers.values()) {
+                for (const tool of await provider(session)) {
+                    const previous = metadata.get(tool.name);
+                    if (this.#strict() && previous)
+                        throw new RegistrationCollision(this.namespace, tool.name, previous.owner, owner);
                     provided.set(tool.name, tool);
+                    metadata.set(tool.name, { owner, source: 'provider' });
+                }
             }
         }
         const available = [
@@ -56,7 +145,7 @@ export class ToolRegistry {
         for (const name of selected) {
             const tool = this.#tools.get(name) ?? provided.get(name);
             if (tool !== undefined) {
-                resolved.set(name, tool);
+                resolved.set(name, { tool, ...(this.#tools.has(name) ? { owner: this.#staticOwners.get(name), source: 'static' } : metadata.get(name)) });
                 continue;
             }
             const factory = this.#factories.get(name);
@@ -66,7 +155,16 @@ export class ToolRegistry {
             if (session === undefined) {
                 throw HarnessError.toolNotAvailable(`${name} (needs a session to build)`, available);
             }
-            resolved.set(name, factory(session));
+            const built = factory(session);
+            if (this.#strict() && built.name !== name)
+                throw new Error(`Session-bound tool factory [${name}] returned [${built.name}].`);
+            if (built.name !== name) {
+                const previous = metadata.get(built.name);
+                if (this.#strict() && previous)
+                    throw new RegistrationCollision(this.namespace, built.name, previous.owner, metadata.get(name).owner);
+                metadata.set(built.name, metadata.get(name));
+            }
+            resolved.set(name, { tool: built, owner: this.#factoryOwners.get(name), source: 'factory' });
         }
         return resolved;
     }
@@ -85,19 +183,54 @@ export class ToolRegistry {
  * not to leave in place — both at once.
  */
 export class ToolAuthorizer {
+    namespace;
+    root;
     enabled;
     #offer;
     #call;
-    constructor(options = {}) {
+    #agents;
+    #scoped = new Map();
+    constructor(options = {}, namespace = null, root) {
+        this.namespace = namespace;
+        this.root = root;
+        validateAgent(namespace);
         this.enabled = options.enabled ?? false;
         this.#offer = options.offer;
         this.#call = options.call;
+        this.#agents = Object.fromEntries(Object.entries(options.agents ?? {}).map(([agent, config]) => {
+            validateAgent(agent);
+            return [agent, { ...config }];
+        }));
         if (!this.enabled && (options.offer !== undefined || options.call !== undefined)) {
             throw HarnessError.policyDefinedButDisabled();
         }
+        for (const key of ['enabled', 'namespace', 'root'])
+            Object.defineProperty(this, key, { writable: false, configurable: false });
+    }
+    forAgent(agent) {
+        validateAgent(agent);
+        const root = this.root ?? this;
+        if (agent === null)
+            return root;
+        let scoped = root.#scoped.get(agent);
+        if (!scoped) {
+            const overrides = root.#agents[agent] ?? {};
+            const options = { enabled: root.enabled, offer: root.#offer, call: root.#call, ...overrides, agents: {} };
+            if (typeof options.enabled !== 'boolean' || (options.offer !== undefined && typeof options.offer !== 'function') || (options.call !== undefined && typeof options.call !== 'function'))
+                throw new TypeError('Malformed agent tool authorization options.');
+            scoped = new ToolAuthorizer(options, agent, root);
+            root.#scoped.set(agent, scoped);
+        }
+        return scoped;
     }
+    hasCallPolicy() { return this.#call !== undefined; }
     /** The tools a run may be offered, each wrapped so the call policy is asked again. */
     async allowed(session, tools) {
+        if (session.agent !== this.namespace) {
+            if (this.namespace !== null)
+                throw new Error('Harness authorizer/session agent mismatch.');
+            return this.forAgent(session.agent).allowed(session, tools);
+        }
         if (!this.enabled) {
             return [...tools.values()];
         }
@@ -120,6 +253,11 @@ export class ToolAuthorizer {
      * be mistaken for enforcement.
      */
     async allowsCall(session, tool, args) {
+        if (session.agent !== this.namespace) {
+            if (this.namespace !== null)
+                throw new Error('Harness authorizer/session agent mismatch.');
+            return this.forAgent(session.agent).allowsCall(session, tool, args);
+        }
         if (!this.enabled || this.#call === undefined) {
             return true;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@particle-academy/prism-harness",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Durable agent sessions for TypeScript — threads, session state and store drivers.",
   "type": "module",
   "sideEffects": false,