@kwirthmagnify/kwirth-common-ai 0.5.78 → 0.5.79

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/back.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { ILlm, ILlmProvider, ECapability, EToolEffect, EToolSensitivity, EUsagePeriod, EUsageUnit, IAiToolInfo, IAiToolsetInfo, IToolsetConfig, IUsageAmounts, IUsageLimits } from './index';
1
+ import { ILlm, ILlmProvider, ECapability, EToolEffect, EToolSensitivity, EUsagePeriod, EUsageUnit, IAiToolInfo, IAiToolsetInfo, IToolsetConfig, IToolsetGrant, IUsageAmounts, IUsageLimits } from './index';
2
2
  import type { AppsV1Api, CoreV1Api, CustomObjectsApi, NetworkingV1Api } from '@kubernetes/client-node';
3
3
  interface ILogChannel {
4
4
  logInfo?: (msg: string) => void;
@@ -230,12 +230,20 @@ export declare const defineTool: <S extends z.ZodTypeAny>(definition: {
230
230
  execute: (args: z.infer<S>, host: IToolHost) => Promise<unknown>;
231
231
  }) => IAiTool;
232
232
  export declare const isBuiltInToolsetId: (id: string) => boolean;
233
- /** Grants a toolset to a list of plugins. Replaces the previous grant; `[]` takes it away from everyone. */
234
- export declare const setToolsetGrants: (toolsetId: string, pluginIds: string[]) => void;
235
- /** Who a toolset is granted to. Empty = nobody, which is the default state. */
236
- export declare const getToolsetGrants: (toolsetId: string) => string[];
237
- /** Whether THAT plugin may use THAT toolset. */
233
+ /**
234
+ * Sets a toolset's grant. Replaces the previous one; `[]` takes it away from everyone.
235
+ *
236
+ * A plugin granted nothing (`allTools: false`, `tools: []`) is NOT kept: "granted nothing" and "not
237
+ * granted" must behave the same, or `isToolsetGrantedTo` would say yes to a plugin that can use nothing.
238
+ * Repeated plugins are merged: the union of their tools, and `allTools` if any of them says so.
239
+ */
240
+ export declare const setToolsetGrants: (toolsetId: string, grants: IToolsetGrant[]) => void;
241
+ /** A toolset's grant, as it lives in the registry. Empty = nobody, which is the default state. */
242
+ export declare const getToolsetGrants: (toolsetId: string) => IToolsetGrant[];
243
+ /** Whether THAT plugin may use THAT toolset: at least one of its tools is granted to it. */
238
244
  export declare const isToolsetGrantedTo: (toolsetId: string, pluginId: string) => boolean;
245
+ /** Whether THAT plugin may use THAT tool of THAT toolset. */
246
+ export declare const isToolGrantedTo: (toolsetId: string, toolName: string, pluginId: string) => boolean;
239
247
  /**
240
248
  * Registers a toolset. `builtIn` is only used by the core for its own: it marks the id as reserved.
241
249
  * Throws if the id is already taken — registering the same id twice is a packaging error, not something
@@ -259,6 +267,9 @@ export declare const buildToolHost: (requires: ECapability[], context: IToolCont
259
267
  /**
260
268
  * Invokes a tool by its qualified reference. A single invocation path for built-in and installed alike,
261
269
  * with the host built according to the `requires` of ITS toolset.
270
+ *
271
+ * ⚠️ It is NOT a gate: it does not know who is asking, so it does not check the grant. Whatever runs on
272
+ * behalf of a plugin goes through `buildAgentTools`, which resolves with the requester.
262
273
  */
263
274
  export declare const invokeToolRef: (ref: string, args: Record<string, unknown>, context: IToolContext) => Promise<unknown>;
264
275
  /** Resolves a qualified reference '<toolset>/<tool>' against the registry. */
@@ -296,6 +307,13 @@ export interface IToolResolution {
296
307
  * looking in the wrong place.
297
308
  */
298
309
  notGranted: string[];
310
+ /**
311
+ * Tools of a GRANTED toolset that the admin did not grant to this plugin, as qualified references.
312
+ *
313
+ * Apart from `disabledTools` on purpose: "the admin took it from you" is fixed in the toolset's grant,
314
+ * "you turned it off" in the plugin's own config.
315
+ */
316
+ notGrantedTools: string[];
299
317
  }
300
318
  /**
301
319
  * Applies a client's ceiling over the registry. Pure: it neither executes nor touches the context, so the
package/dist/back.js CHANGED
@@ -1,6 +1,6 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.buildAgentTools = exports.resolveTools = exports.resolveToolRef = exports.invokeToolRef = exports.buildToolHost = exports.listToolsetInfos = exports.listToolsets = exports.getToolset = exports.unregisterToolset = exports.registerToolset = exports.isToolsetGrantedTo = exports.getToolsetGrants = exports.setToolsetGrants = exports.isBuiltInToolsetId = exports.defineTool = exports.runWithToolContext = exports.EToolEffect = exports.zodFromExample = exports.z = exports.tool = exports.stepCountIs = exports.Output = exports.streamText = exports.generateText = exports.loadModels = exports.generateVision = exports.runWithUsageGuard = exports.effectiveLimits = exports.usageSubjectForKey = exports.getUsageService = exports.setUsageService = exports.setAiLogger = exports.UsageLimitError = exports.EUsageScope = exports.buildModel = void 0;
3
+ exports.buildAgentTools = exports.resolveTools = exports.resolveToolRef = exports.invokeToolRef = exports.buildToolHost = exports.listToolsetInfos = exports.listToolsets = exports.getToolset = exports.unregisterToolset = exports.registerToolset = exports.isToolGrantedTo = exports.isToolsetGrantedTo = exports.getToolsetGrants = exports.setToolsetGrants = exports.isBuiltInToolsetId = exports.defineTool = exports.runWithToolContext = exports.EToolEffect = exports.zodFromExample = exports.z = exports.tool = exports.stepCountIs = exports.Output = exports.streamText = exports.generateText = exports.loadModels = exports.generateVision = exports.runWithUsageGuard = exports.effectiveLimits = exports.usageSubjectForKey = exports.getUsageService = exports.setUsageService = exports.setAiLogger = exports.UsageLimitError = exports.EUsageScope = exports.buildModel = void 0;
4
4
  const index_1 = require("./index");
5
5
  // Aliased on purpose: the generateText this module EXPORTS is the wrapped one, and nothing below should
6
6
  // be able to reach the raw SDK call by accident — that is exactly how a call would escape the counters.
@@ -726,20 +726,49 @@ const builtInToolsetIds = new Set();
726
726
  And by default nobody uses it (user's decision, 2026-09-17): installing a toolset leaves it available,
727
727
  not granted. Installing `k8s-ops` must not give anyone write access by accident.
728
728
  */
729
- const toolsetGrants = new Map(); // toolsetId → invited plugins
729
+ // And the grant is per TOOL (plan: plans/ai-tool-grants/PLAN.md, T1): the admin grants a plugin either every
730
+ // tool of the toolset (`allTools`, future ones included) or an explicit list (new ones are NOT granted).
731
+ const toolsetGrants = new Map(); // toolsetId → pluginId → its grant
730
732
  const isBuiltInToolsetId = (id) => builtInToolsetIds.has(id);
731
733
  exports.isBuiltInToolsetId = isBuiltInToolsetId;
732
- /** Grants a toolset to a list of plugins. Replaces the previous grant; `[]` takes it away from everyone. */
733
- const setToolsetGrants = (toolsetId, pluginIds) => {
734
- toolsetGrants.set(toolsetId, new Set(pluginIds));
734
+ /** Whether a grant gives anything at all. */
735
+ const grantsSomething = (g) => g.allTools || g.tools.length > 0;
736
+ /**
737
+ * Sets a toolset's grant. Replaces the previous one; `[]` takes it away from everyone.
738
+ *
739
+ * A plugin granted nothing (`allTools: false`, `tools: []`) is NOT kept: "granted nothing" and "not
740
+ * granted" must behave the same, or `isToolsetGrantedTo` would say yes to a plugin that can use nothing.
741
+ * Repeated plugins are merged: the union of their tools, and `allTools` if any of them says so.
742
+ */
743
+ const setToolsetGrants = (toolsetId, grants) => {
744
+ var _a, _b;
745
+ const byPlugin = new Map();
746
+ for (const g of grants) {
747
+ if (!grantsSomething(g))
748
+ continue;
749
+ const previous = byPlugin.get(g.pluginId);
750
+ byPlugin.set(g.pluginId, {
751
+ pluginId: g.pluginId,
752
+ allTools: g.allTools || ((_a = previous === null || previous === void 0 ? void 0 : previous.allTools) !== null && _a !== void 0 ? _a : false),
753
+ tools: [...new Set([...((_b = previous === null || previous === void 0 ? void 0 : previous.tools) !== null && _b !== void 0 ? _b : []), ...g.tools])]
754
+ });
755
+ }
756
+ toolsetGrants.set(toolsetId, byPlugin);
735
757
  };
736
758
  exports.setToolsetGrants = setToolsetGrants;
737
- /** Who a toolset is granted to. Empty = nobody, which is the default state. */
738
- const getToolsetGrants = (toolsetId) => { var _a; return [...((_a = toolsetGrants.get(toolsetId)) !== null && _a !== void 0 ? _a : [])]; };
759
+ /** A toolset's grant, as it lives in the registry. Empty = nobody, which is the default state. */
760
+ const getToolsetGrants = (toolsetId) => { var _a, _b; return [...((_b = (_a = toolsetGrants.get(toolsetId)) === null || _a === void 0 ? void 0 : _a.values()) !== null && _b !== void 0 ? _b : [])].map(g => (Object.assign(Object.assign({}, g), { tools: [...g.tools] }))); };
739
761
  exports.getToolsetGrants = getToolsetGrants;
740
- /** Whether THAT plugin may use THAT toolset. */
762
+ /** Whether THAT plugin may use THAT toolset: at least one of its tools is granted to it. */
741
763
  const isToolsetGrantedTo = (toolsetId, pluginId) => { var _a, _b; return (_b = (_a = toolsetGrants.get(toolsetId)) === null || _a === void 0 ? void 0 : _a.has(pluginId)) !== null && _b !== void 0 ? _b : false; };
742
764
  exports.isToolsetGrantedTo = isToolsetGrantedTo;
765
+ /** Whether THAT plugin may use THAT tool of THAT toolset. */
766
+ const isToolGrantedTo = (toolsetId, toolName, pluginId) => {
767
+ var _a;
768
+ const g = (_a = toolsetGrants.get(toolsetId)) === null || _a === void 0 ? void 0 : _a.get(pluginId);
769
+ return g !== undefined && (g.allTools || g.tools.includes(toolName));
770
+ };
771
+ exports.isToolGrantedTo = isToolGrantedTo;
743
772
  /**
744
773
  * Registers a toolset. `builtIn` is only used by the core for its own: it marks the id as reserved.
745
774
  * Throws if the id is already taken — registering the same id twice is a packaging error, not something
@@ -821,6 +850,9 @@ exports.buildToolHost = buildToolHost;
821
850
  /**
822
851
  * Invokes a tool by its qualified reference. A single invocation path for built-in and installed alike,
823
852
  * with the host built according to the `requires` of ITS toolset.
853
+ *
854
+ * ⚠️ It is NOT a gate: it does not know who is asking, so it does not check the grant. Whatever runs on
855
+ * behalf of a plugin goes through `buildAgentTools`, which resolves with the requester.
824
856
  */
825
857
  const invokeToolRef = async (ref, args, context) => {
826
858
  const resolved = (0, exports.resolveToolRef)(ref);
@@ -852,6 +884,7 @@ const resolveTools = (config, requesterId) => {
852
884
  const shadowed = [];
853
885
  const missing = [];
854
886
  const notGranted = [];
887
+ const notGrantedTools = [];
855
888
  const taken = new Map(); // short name → toolset serving it
856
889
  for (const toolsetId of config.activeToolsets) {
857
890
  const toolset = toolsetRegistry.get(toolsetId);
@@ -870,6 +903,12 @@ const resolveTools = (config, requesterId) => {
870
903
  }
871
904
  for (const tool of toolset.tools) {
872
905
  const ref = (0, index_1.toolRef)(toolsetId, tool.name);
906
+ // A tool not granted is out of play BEFORE the shadowing, like a disabled one: it must not hide a
907
+ // tool with the same name from a toolset of lower precedence.
908
+ if (requesterId !== undefined && !(0, exports.isToolGrantedTo)(toolsetId, tool.name, requesterId)) {
909
+ notGrantedTools.push(ref);
910
+ continue;
911
+ }
873
912
  if (disabled.has(ref))
874
913
  continue;
875
914
  const owner = taken.get(tool.name);
@@ -881,7 +920,7 @@ const resolveTools = (config, requesterId) => {
881
920
  effective.push({ name: tool.name, ref, toolsetId, tool });
882
921
  }
883
922
  }
884
- return { effective, shadowed, missing, notGranted };
923
+ return { effective, shadowed, missing, notGranted, notGrantedTools };
885
924
  };
886
925
  exports.resolveTools = resolveTools;
887
926
  /**
package/dist/index.d.ts CHANGED
@@ -112,6 +112,11 @@ export interface IAiToolsetInfo {
112
112
  requires: ECapability[];
113
113
  tools: IAiToolInfo[];
114
114
  }
115
+ export interface IToolsetGrant {
116
+ pluginId: string;
117
+ allTools: boolean;
118
+ tools: string[];
119
+ }
115
120
  export interface IToolsetConfig {
116
121
  activeToolsets: string[];
117
122
  disabledTools: string[];
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kwirthmagnify/kwirth-common-ai",
3
- "version": "0.5.78",
3
+ "version": "0.5.79",
4
4
  "description": "Shared AI/LLM types and utilities for Kwirth AI plugins",
5
5
  "scripts": {
6
6
  "build": "del .\\dist\\* /s /q 2>nul & tsc",