@kwirthmagnify/kwirth-common-ai 0.5.78 → 0.5.80

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,5 +1,6 @@
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
+ import type { IProviderHandle } from '@kwirthmagnify/kwirth-common-back';
3
4
  interface ILogChannel {
4
5
  logInfo?: (msg: string) => void;
5
6
  logWarning?: (msg: string) => void;
@@ -93,6 +94,7 @@ export interface IToolContext {
93
94
  clusterEvents?: any[];
94
95
  sourceRepos?: ISourceRepoCred[];
95
96
  trace: (toolName: string, args: Record<string, unknown>) => void;
97
+ consumer?: object;
96
98
  }
97
99
  export { EToolEffect } from './index';
98
100
  export declare const runWithToolContext: <T>(context: IToolContext, fn: () => Promise<T>) => Promise<T>;
@@ -189,6 +191,14 @@ export interface IEventsCapability {
189
191
  export interface IReposCapability {
190
192
  creds: ISourceRepoCred[];
191
193
  }
194
+ /**
195
+ * The providers a toolset declared (`ECapability.PROVIDERS` + its `providers` list), and ONLY those: reads
196
+ * (getData) and operations (getOperations / runOperation), through the core's handle, so the core knows who
197
+ * reads and logs who operates. Undefined: the toolset did not declare that provider, or it is not installed here.
198
+ */
199
+ export interface IProvidersCapability {
200
+ get(providerId: string): IProviderHandle | undefined;
201
+ }
192
202
  /**
193
203
  * What a tool receives when it runs. Only the capabilities its toolset declared come filled in:
194
204
  * a `requires: []` receives nothing but `trace`.
@@ -200,6 +210,7 @@ export interface IToolHost {
200
210
  metrics?: IMetricsCapability;
201
211
  events?: IEventsCapability;
202
212
  repos?: IReposCapability;
213
+ providers?: IProvidersCapability;
203
214
  }
204
215
  /** An executable tool: what travels to the front end (IAiToolInfo) plus what it takes to invoke it. */
205
216
  export interface IAiTool extends IAiToolInfo {
@@ -230,12 +241,20 @@ export declare const defineTool: <S extends z.ZodTypeAny>(definition: {
230
241
  execute: (args: z.infer<S>, host: IToolHost) => Promise<unknown>;
231
242
  }) => IAiTool;
232
243
  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. */
244
+ /**
245
+ * Sets a toolset's grant. Replaces the previous one; `[]` takes it away from everyone.
246
+ *
247
+ * A plugin granted nothing (`allTools: false`, `tools: []`) is NOT kept: "granted nothing" and "not
248
+ * granted" must behave the same, or `isToolsetGrantedTo` would say yes to a plugin that can use nothing.
249
+ * Repeated plugins are merged: the union of their tools, and `allTools` if any of them says so.
250
+ */
251
+ export declare const setToolsetGrants: (toolsetId: string, grants: IToolsetGrant[]) => void;
252
+ /** A toolset's grant, as it lives in the registry. Empty = nobody, which is the default state. */
253
+ export declare const getToolsetGrants: (toolsetId: string) => IToolsetGrant[];
254
+ /** Whether THAT plugin may use THAT toolset: at least one of its tools is granted to it. */
238
255
  export declare const isToolsetGrantedTo: (toolsetId: string, pluginId: string) => boolean;
256
+ /** Whether THAT plugin may use THAT tool of THAT toolset. */
257
+ export declare const isToolGrantedTo: (toolsetId: string, toolName: string, pluginId: string) => boolean;
239
258
  /**
240
259
  * Registers a toolset. `builtIn` is only used by the core for its own: it marks the id as reserved.
241
260
  * Throws if the id is already taken — registering the same id twice is a packaging error, not something
@@ -255,10 +274,13 @@ export declare const listToolsetInfos: () => IAiToolsetInfo[];
255
274
  * if every site assembled its own object, one of them being too generous would be enough for the
256
275
  * declaration to stop meaning anything.
257
276
  */
258
- export declare const buildToolHost: (requires: ECapability[], context: IToolContext) => IToolHost;
277
+ export declare const buildToolHost: (requires: ECapability[], context: IToolContext, providers?: string[]) => IToolHost;
259
278
  /**
260
279
  * Invokes a tool by its qualified reference. A single invocation path for built-in and installed alike,
261
280
  * with the host built according to the `requires` of ITS toolset.
281
+ *
282
+ * ⚠️ It is NOT a gate: it does not know who is asking, so it does not check the grant. Whatever runs on
283
+ * behalf of a plugin goes through `buildAgentTools`, which resolves with the requester.
262
284
  */
263
285
  export declare const invokeToolRef: (ref: string, args: Record<string, unknown>, context: IToolContext) => Promise<unknown>;
264
286
  /** Resolves a qualified reference '<toolset>/<tool>' against the registry. */
@@ -296,6 +318,13 @@ export interface IToolResolution {
296
318
  * looking in the wrong place.
297
319
  */
298
320
  notGranted: string[];
321
+ /**
322
+ * Tools of a GRANTED toolset that the admin did not grant to this plugin, as qualified references.
323
+ *
324
+ * Apart from `disabledTools` on purpose: "the admin took it from you" is fixed in the toolset's grant,
325
+ * "you turned it off" in the plugin's own config.
326
+ */
327
+ notGrantedTools: string[];
299
328
  }
300
329
  /**
301
330
  * 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
@@ -774,14 +803,7 @@ exports.getToolset = getToolset;
774
803
  const listToolsets = () => [...toolsetRegistry.values()];
775
804
  exports.listToolsets = listToolsets;
776
805
  /** What is sent to the front end: the descriptors, without inputSchema or execute. */
777
- const listToolsetInfos = () => (0, exports.listToolsets)().map(t => ({
778
- id: t.id,
779
- version: t.version,
780
- displayName: t.displayName,
781
- description: t.description,
782
- requires: t.requires,
783
- tools: t.tools.map(x => ({ name: x.name, description: x.description, effect: x.effect, sensitivity: x.sensitivity }))
784
- }));
806
+ const listToolsetInfos = () => (0, exports.listToolsets)().map(t => (Object.assign(Object.assign({ id: t.id, version: t.version, displayName: t.displayName, description: t.description, requires: t.requires }, (t.providers ? { providers: t.providers } : {})), { tools: t.tools.map(x => ({ name: x.name, description: x.description, effect: x.effect, sensitivity: x.sensitivity })) })));
785
807
  exports.listToolsetInfos = listToolsetInfos;
786
808
  /**
787
809
  * Builds a toolset's host from the core context, provisioning ONLY what was declared.
@@ -790,7 +812,7 @@ exports.listToolsetInfos = listToolsetInfos;
790
812
  * if every site assembled its own object, one of them being too generous would be enough for the
791
813
  * declaration to stop meaning anything.
792
814
  */
793
- const buildToolHost = (requires, context) => {
815
+ const buildToolHost = (requires, context, providers) => {
794
816
  var _a, _b, _c;
795
817
  const host = { trace: context.trace };
796
818
  const ci = context.clusterInfo;
@@ -815,18 +837,32 @@ const buildToolHost = (requires, context) => {
815
837
  host.events = { recent: ((_b = context.clusterEvents) !== null && _b !== void 0 ? _b : []) };
816
838
  if (requires.includes(index_1.ECapability.REPOS))
817
839
  host.repos = { creds: (_c = context.sourceRepos) !== null && _c !== void 0 ? _c : [] };
840
+ /*
841
+ The providers: only the ones the toolset NAMED, asked for on behalf of the extension the tools run for
842
+ (context.consumer), so the core's registry and its log of operations attribute them. No consumer, or a
843
+ host without getProvider, lends nothing: a tool then says the provider is not available.
844
+ */
845
+ if (requires.includes(index_1.ECapability.PROVIDERS) && context.consumer && typeof (ci === null || ci === void 0 ? void 0 : ci.getProvider) === 'function') {
846
+ const declared = new Set(providers !== null && providers !== void 0 ? providers : []);
847
+ host.providers = {
848
+ get: (providerId) => declared.has(providerId) ? ci.getProvider(providerId, context.consumer) : undefined
849
+ };
850
+ }
818
851
  return host;
819
852
  };
820
853
  exports.buildToolHost = buildToolHost;
821
854
  /**
822
855
  * Invokes a tool by its qualified reference. A single invocation path for built-in and installed alike,
823
856
  * with the host built according to the `requires` of ITS toolset.
857
+ *
858
+ * ⚠️ It is NOT a gate: it does not know who is asking, so it does not check the grant. Whatever runs on
859
+ * behalf of a plugin goes through `buildAgentTools`, which resolves with the requester.
824
860
  */
825
861
  const invokeToolRef = async (ref, args, context) => {
826
862
  const resolved = (0, exports.resolveToolRef)(ref);
827
863
  if (!resolved)
828
864
  throw new Error(`[common-ai] unknown tool '${ref}'`);
829
- return resolved.tool.execute(args, (0, exports.buildToolHost)(resolved.toolset.requires, context));
865
+ return resolved.tool.execute(args, (0, exports.buildToolHost)(resolved.toolset.requires, context, resolved.toolset.providers));
830
866
  };
831
867
  exports.invokeToolRef = invokeToolRef;
832
868
  /** Resolves a qualified reference '<toolset>/<tool>' against the registry. */
@@ -852,6 +888,7 @@ const resolveTools = (config, requesterId) => {
852
888
  const shadowed = [];
853
889
  const missing = [];
854
890
  const notGranted = [];
891
+ const notGrantedTools = [];
855
892
  const taken = new Map(); // short name → toolset serving it
856
893
  for (const toolsetId of config.activeToolsets) {
857
894
  const toolset = toolsetRegistry.get(toolsetId);
@@ -870,6 +907,12 @@ const resolveTools = (config, requesterId) => {
870
907
  }
871
908
  for (const tool of toolset.tools) {
872
909
  const ref = (0, index_1.toolRef)(toolsetId, tool.name);
910
+ // A tool not granted is out of play BEFORE the shadowing, like a disabled one: it must not hide a
911
+ // tool with the same name from a toolset of lower precedence.
912
+ if (requesterId !== undefined && !(0, exports.isToolGrantedTo)(toolsetId, tool.name, requesterId)) {
913
+ notGrantedTools.push(ref);
914
+ continue;
915
+ }
873
916
  if (disabled.has(ref))
874
917
  continue;
875
918
  const owner = taken.get(tool.name);
@@ -881,7 +924,7 @@ const resolveTools = (config, requesterId) => {
881
924
  effective.push({ name: tool.name, ref, toolsetId, tool });
882
925
  }
883
926
  }
884
- return { effective, shadowed, missing, notGranted };
927
+ return { effective, shadowed, missing, notGranted, notGrantedTools };
885
928
  };
886
929
  exports.resolveTools = resolveTools;
887
930
  /**
@@ -909,7 +952,7 @@ requesterId) => {
909
952
  description: e.tool.description,
910
953
  inputSchema: e.tool.inputSchema,
911
954
  execute: async (rawArgs) => {
912
- var _a, _b, _c, _d, _e;
955
+ var _a, _b, _c, _d, _e, _f;
913
956
  const args = (rawArgs !== null && rawArgs !== void 0 ? rawArgs : {});
914
957
  const invocation = invocationOf(args);
915
958
  const started = Date.now();
@@ -921,18 +964,18 @@ requesterId) => {
921
964
  (_a = hooks.observe) === null || _a === void 0 ? void 0 : _a.call(hooks, invocation, { ok: false, error: denial.error, ms: Date.now() - started, denied: true });
922
965
  return denial;
923
966
  }
924
- const host = (0, exports.buildToolHost)((_c = (_b = (0, exports.getToolset)(e.toolsetId)) === null || _b === void 0 ? void 0 : _b.requires) !== null && _c !== void 0 ? _c : [], context);
967
+ const host = (0, exports.buildToolHost)((_c = (_b = (0, exports.getToolset)(e.toolsetId)) === null || _b === void 0 ? void 0 : _b.requires) !== null && _c !== void 0 ? _c : [], context, (_d = (0, exports.getToolset)(e.toolsetId)) === null || _d === void 0 ? void 0 : _d.providers);
925
968
  try {
926
969
  // runWithToolContext also wraps the tools written against the OLD contract (the ones
927
970
  // that read ctx()). That is what lets the 43 be migrated package by package in S3,
928
971
  // instead of having to rewrite them all before this path can be used at all.
929
972
  const result = await (0, exports.runWithToolContext)(context, () => e.tool.execute(args, host));
930
- (_d = hooks.observe) === null || _d === void 0 ? void 0 : _d.call(hooks, invocation, { ok: true, result, ms: Date.now() - started });
973
+ (_e = hooks.observe) === null || _e === void 0 ? void 0 : _e.call(hooks, invocation, { ok: true, result, ms: Date.now() - started });
931
974
  return result;
932
975
  }
933
976
  catch (err) {
934
977
  const message = err instanceof Error ? err.message : String(err);
935
- (_e = hooks.observe) === null || _e === void 0 ? void 0 : _e.call(hooks, invocation, { ok: false, error: message, ms: Date.now() - started });
978
+ (_f = hooks.observe) === null || _f === void 0 ? void 0 : _f.call(hooks, invocation, { ok: false, error: message, ms: Date.now() - started });
936
979
  return { error: message };
937
980
  }
938
981
  }
package/dist/index.d.ts CHANGED
@@ -87,7 +87,8 @@ export declare enum ECapability {
87
87
  K8S = "k8s",// cluster access
88
88
  METRICS = "metrics",// metrics, current and historical
89
89
  EVENTS = "events",// cluster event buffer
90
- REPOS = "repos"
90
+ REPOS = "repos",// source repository credentials
91
+ PROVIDERS = "providers"
91
92
  }
92
93
  /** Separator of a qualified reference to a tool: '<toolset>/<tool>'. */
93
94
  export declare const TOOL_REF_SEPARATOR = "/";
@@ -110,8 +111,15 @@ export interface IAiToolsetInfo {
110
111
  displayName: string;
111
112
  description: string;
112
113
  requires: ECapability[];
114
+ /** With ECapability.PROVIDERS: the ids of the providers it needs (e.g. ['aws']). The host lends ONLY these. */
115
+ providers?: string[];
113
116
  tools: IAiToolInfo[];
114
117
  }
118
+ export interface IToolsetGrant {
119
+ pluginId: string;
120
+ allTools: boolean;
121
+ tools: string[];
122
+ }
115
123
  export interface IToolsetConfig {
116
124
  activeToolsets: string[];
117
125
  disabledTools: string[];
package/dist/index.js CHANGED
@@ -54,7 +54,8 @@ var ECapability;
54
54
  ECapability["K8S"] = "k8s";
55
55
  ECapability["METRICS"] = "metrics";
56
56
  ECapability["EVENTS"] = "events";
57
- ECapability["REPOS"] = "repos"; // source repository credentials
57
+ ECapability["REPOS"] = "repos";
58
+ ECapability["PROVIDERS"] = "providers"; // handles of the providers the toolset names in `providers` (reads and operations)
58
59
  })(ECapability || (exports.ECapability = ECapability = {}));
59
60
  /** Separator of a qualified reference to a tool: '<toolset>/<tool>'. */
60
61
  exports.TOOL_REF_SEPARATOR = '/';
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.80",
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",
@@ -56,17 +56,18 @@
56
56
  "zod": "^4.3.6"
57
57
  },
58
58
  "peerDependencies": {
59
- "react": ">=18.0.0",
60
- "@kubernetes/client-node": ">=1.0.0"
59
+ "@kubernetes/client-node": ">=1.0.0",
60
+ "react": ">=18.0.0"
61
61
  },
62
62
  "devDependencies": {
63
+ "@kubernetes/client-node": "^1.4.0",
63
64
  "@kwirthmagnify/kwirth-common": "^0.5.76",
65
+ "@kwirthmagnify/kwirth-common-back": "^0.6.11",
64
66
  "@mui/icons-material": "9.5.0",
65
67
  "@mui/material": "9.5.0",
66
68
  "@types/node": "^25.9.1",
67
69
  "@types/react": "^18.3.0",
68
- "typescript": "^5.4.0",
69
- "@kubernetes/client-node": "^1.4.0"
70
+ "typescript": "^5.4.0"
70
71
  },
71
72
  "peerDependenciesMeta": {
72
73
  "@kubernetes/client-node": {