@kwirthmagnify/kwirth-common-ai 0.5.79 → 0.5.81

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, IToolsetGrant, IUsageAmounts, IUsageLimits } from './index';
1
+ import { ILlm, ILlmProvider, ECapability, EToolEffect, EToolSensitivity, EUsagePeriod, EUsageUnit, IAiToolInfo, IAiToolsetInfo, IToolsetConfig, IToolsetGrant, IUsageAmounts, IUsageLimits, TAiToolsetConfig } 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`.
@@ -196,10 +206,12 @@ export interface IReposCapability {
196
206
  export interface IToolHost {
197
207
  /** Records the invocation. NOT a capability: it is always lent, and never declared. */
198
208
  trace: (toolName: string, args: Record<string, unknown>) => void;
209
+ config: TAiToolsetConfig;
199
210
  k8s?: IK8sCapability;
200
211
  metrics?: IMetricsCapability;
201
212
  events?: IEventsCapability;
202
213
  repos?: IReposCapability;
214
+ providers?: IProvidersCapability;
203
215
  }
204
216
  /** An executable tool: what travels to the front end (IAiToolInfo) plus what it takes to invoke it. */
205
217
  export interface IAiTool extends IAiToolInfo {
@@ -238,6 +250,10 @@ export declare const isBuiltInToolsetId: (id: string) => boolean;
238
250
  * Repeated plugins are merged: the union of their tools, and `allTools` if any of them says so.
239
251
  */
240
252
  export declare const setToolsetGrants: (toolsetId: string, grants: IToolsetGrant[]) => void;
253
+ /** Sets a toolset's settings (the defaults already applied); `undefined` removes them. Called by the core. */
254
+ export declare const setToolsetConfig: (toolsetId: string, config: TAiToolsetConfig | undefined) => void;
255
+ /** A toolset's settings as its tools receive them: a copy, `{}` when it has none. */
256
+ export declare const getToolsetConfig: (toolsetId: string) => TAiToolsetConfig;
241
257
  /** A toolset's grant, as it lives in the registry. Empty = nobody, which is the default state. */
242
258
  export declare const getToolsetGrants: (toolsetId: string) => IToolsetGrant[];
243
259
  /** Whether THAT plugin may use THAT toolset: at least one of its tools is granted to it. */
@@ -263,7 +279,7 @@ export declare const listToolsetInfos: () => IAiToolsetInfo[];
263
279
  * if every site assembled its own object, one of them being too generous would be enough for the
264
280
  * declaration to stop meaning anything.
265
281
  */
266
- export declare const buildToolHost: (requires: ECapability[], context: IToolContext) => IToolHost;
282
+ export declare const buildToolHost: (requires: ECapability[], context: IToolContext, providers?: string[], config?: TAiToolsetConfig) => IToolHost;
267
283
  /**
268
284
  * Invokes a tool by its qualified reference. A single invocation path for built-in and installed alike,
269
285
  * with the host built according to the `requires` of ITS toolset.
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.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;
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.getToolsetConfig = exports.setToolsetConfig = 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.
@@ -557,7 +557,7 @@ exports.generateText = ((options) => (0, exports.runWithUsageGuard)(options, ()
557
557
  ends (the SDK reports it with the last chunk). The whole call cannot go through runWithUsageGuard —
558
558
  the guard's promise resolves when the call finishes, but the caller needs the result object
559
559
  IMMEDIATELY to consume textStream; awaiting the guard would deliver it only after the stream is over.
560
- A failed stream records nothing, exactly like a failed generateText. First consumer: the vllm channel,
560
+ A failed stream records nothing, exactly like a failed generateText. First consumer: the llm-router channel (then vllm),
561
561
  which re-streams what the model it routed to produces.
562
562
  */
563
563
  exports.streamText = (async (options) => {
@@ -756,6 +756,24 @@ const setToolsetGrants = (toolsetId, grants) => {
756
756
  toolsetGrants.set(toolsetId, byPlugin);
757
757
  };
758
758
  exports.setToolsetGrants = setToolsetGrants;
759
+ /*
760
+ Each toolset's SETTINGS (plans/extension-config, P3), with the same pattern as the grants: in memory,
761
+ loaded and kept up to date by the core, which owns the Secret they are saved in. No invocation reads
762
+ the Secret: a tool gets `host.config` from here. With several replicas a save applies from the next
763
+ call in the replica that saved, as the grants do.
764
+ */
765
+ const toolsetConfigs = new Map();
766
+ /** Sets a toolset's settings (the defaults already applied); `undefined` removes them. Called by the core. */
767
+ const setToolsetConfig = (toolsetId, config) => {
768
+ if (config === undefined)
769
+ toolsetConfigs.delete(toolsetId);
770
+ else
771
+ toolsetConfigs.set(toolsetId, Object.assign({}, config));
772
+ };
773
+ exports.setToolsetConfig = setToolsetConfig;
774
+ /** A toolset's settings as its tools receive them: a copy, `{}` when it has none. */
775
+ const getToolsetConfig = (toolsetId) => { var _a; return (Object.assign({}, ((_a = toolsetConfigs.get(toolsetId)) !== null && _a !== void 0 ? _a : {}))); };
776
+ exports.getToolsetConfig = getToolsetConfig;
759
777
  /** A toolset's grant, as it lives in the registry. Empty = nobody, which is the default state. */
760
778
  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] }))); };
761
779
  exports.getToolsetGrants = getToolsetGrants;
@@ -793,8 +811,9 @@ const unregisterToolset = (id) => {
793
811
  if (builtInToolsetIds.has(id))
794
812
  return false;
795
813
  // The grant goes with the toolset: leaving it orphaned would make reinstalling resurrect permissions
796
- // nobody has granted again.
814
+ // nobody has granted again. The settings too: the core hands them back when it registers it again.
797
815
  toolsetGrants.delete(id);
816
+ toolsetConfigs.delete(id);
798
817
  return toolsetRegistry.delete(id);
799
818
  };
800
819
  exports.unregisterToolset = unregisterToolset;
@@ -803,14 +822,7 @@ exports.getToolset = getToolset;
803
822
  const listToolsets = () => [...toolsetRegistry.values()];
804
823
  exports.listToolsets = listToolsets;
805
824
  /** What is sent to the front end: the descriptors, without inputSchema or execute. */
806
- const listToolsetInfos = () => (0, exports.listToolsets)().map(t => ({
807
- id: t.id,
808
- version: t.version,
809
- displayName: t.displayName,
810
- description: t.description,
811
- requires: t.requires,
812
- tools: t.tools.map(x => ({ name: x.name, description: x.description, effect: x.effect, sensitivity: x.sensitivity }))
813
- }));
825
+ const listToolsetInfos = () => (0, exports.listToolsets)().map(t => (Object.assign(Object.assign(Object.assign({ id: t.id, version: t.version, displayName: t.displayName, description: t.description, requires: t.requires }, (t.providers ? { providers: t.providers } : {})), (t.configSchema ? { configSchema: t.configSchema } : {})), { tools: t.tools.map(x => ({ name: x.name, description: x.description, effect: x.effect, sensitivity: x.sensitivity })) })));
814
826
  exports.listToolsetInfos = listToolsetInfos;
815
827
  /**
816
828
  * Builds a toolset's host from the core context, provisioning ONLY what was declared.
@@ -819,9 +831,9 @@ exports.listToolsetInfos = listToolsetInfos;
819
831
  * if every site assembled its own object, one of them being too generous would be enough for the
820
832
  * declaration to stop meaning anything.
821
833
  */
822
- const buildToolHost = (requires, context) => {
834
+ const buildToolHost = (requires, context, providers, config = {}) => {
823
835
  var _a, _b, _c;
824
- const host = { trace: context.trace };
836
+ const host = { trace: context.trace, config };
825
837
  const ci = context.clusterInfo;
826
838
  // No cluster means no cluster capability, even when declared: better that the tool receives
827
839
  // 'undefined' and says so, than handing it a half-built facade that fails from the inside.
@@ -844,6 +856,17 @@ const buildToolHost = (requires, context) => {
844
856
  host.events = { recent: ((_b = context.clusterEvents) !== null && _b !== void 0 ? _b : []) };
845
857
  if (requires.includes(index_1.ECapability.REPOS))
846
858
  host.repos = { creds: (_c = context.sourceRepos) !== null && _c !== void 0 ? _c : [] };
859
+ /*
860
+ The providers: only the ones the toolset NAMED, asked for on behalf of the extension the tools run for
861
+ (context.consumer), so the core's registry and its log of operations attribute them. No consumer, or a
862
+ host without getProvider, lends nothing: a tool then says the provider is not available.
863
+ */
864
+ if (requires.includes(index_1.ECapability.PROVIDERS) && context.consumer && typeof (ci === null || ci === void 0 ? void 0 : ci.getProvider) === 'function') {
865
+ const declared = new Set(providers !== null && providers !== void 0 ? providers : []);
866
+ host.providers = {
867
+ get: (providerId) => declared.has(providerId) ? ci.getProvider(providerId, context.consumer) : undefined
868
+ };
869
+ }
847
870
  return host;
848
871
  };
849
872
  exports.buildToolHost = buildToolHost;
@@ -858,7 +881,7 @@ const invokeToolRef = async (ref, args, context) => {
858
881
  const resolved = (0, exports.resolveToolRef)(ref);
859
882
  if (!resolved)
860
883
  throw new Error(`[common-ai] unknown tool '${ref}'`);
861
- return resolved.tool.execute(args, (0, exports.buildToolHost)(resolved.toolset.requires, context));
884
+ return resolved.tool.execute(args, (0, exports.buildToolHost)(resolved.toolset.requires, context, resolved.toolset.providers, (0, exports.getToolsetConfig)(resolved.toolset.id)));
862
885
  };
863
886
  exports.invokeToolRef = invokeToolRef;
864
887
  /** Resolves a qualified reference '<toolset>/<tool>' against the registry. */
@@ -948,7 +971,7 @@ requesterId) => {
948
971
  description: e.tool.description,
949
972
  inputSchema: e.tool.inputSchema,
950
973
  execute: async (rawArgs) => {
951
- var _a, _b, _c, _d, _e;
974
+ var _a, _b, _c, _d, _e, _f;
952
975
  const args = (rawArgs !== null && rawArgs !== void 0 ? rawArgs : {});
953
976
  const invocation = invocationOf(args);
954
977
  const started = Date.now();
@@ -960,18 +983,18 @@ requesterId) => {
960
983
  (_a = hooks.observe) === null || _a === void 0 ? void 0 : _a.call(hooks, invocation, { ok: false, error: denial.error, ms: Date.now() - started, denied: true });
961
984
  return denial;
962
985
  }
963
- 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);
986
+ 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, (0, exports.getToolsetConfig)(e.toolsetId));
964
987
  try {
965
988
  // runWithToolContext also wraps the tools written against the OLD contract (the ones
966
989
  // that read ctx()). That is what lets the 43 be migrated package by package in S3,
967
990
  // instead of having to rewrite them all before this path can be used at all.
968
991
  const result = await (0, exports.runWithToolContext)(context, () => e.tool.execute(args, host));
969
- (_d = hooks.observe) === null || _d === void 0 ? void 0 : _d.call(hooks, invocation, { ok: true, result, ms: Date.now() - started });
992
+ (_e = hooks.observe) === null || _e === void 0 ? void 0 : _e.call(hooks, invocation, { ok: true, result, ms: Date.now() - started });
970
993
  return result;
971
994
  }
972
995
  catch (err) {
973
996
  const message = err instanceof Error ? err.message : String(err);
974
- (_e = hooks.observe) === null || _e === void 0 ? void 0 : _e.call(hooks, invocation, { ok: false, error: message, ms: Date.now() - started });
997
+ (_f = hooks.observe) === null || _f === void 0 ? void 0 : _f.call(hooks, invocation, { ok: false, error: message, ms: Date.now() - started });
975
998
  return { error: message };
976
999
  }
977
1000
  }
package/dist/index.d.ts CHANGED
@@ -1,3 +1,4 @@
1
+ import type { IConfigFieldDef } from '@kwirthmagnify/kwirth-common';
1
2
  export declare const STORAGE_KEY_PROVIDERS = "kwirth-ai-providers";
2
3
  export declare const STORAGE_KEY_LLMS = "kwirth-ai-llms";
3
4
  export declare const PROVIDERS_AVAILABLE: string[];
@@ -87,7 +88,8 @@ export declare enum ECapability {
87
88
  K8S = "k8s",// cluster access
88
89
  METRICS = "metrics",// metrics, current and historical
89
90
  EVENTS = "events",// cluster event buffer
90
- REPOS = "repos"
91
+ REPOS = "repos",// source repository credentials
92
+ PROVIDERS = "providers"
91
93
  }
92
94
  /** Separator of a qualified reference to a tool: '<toolset>/<tool>'. */
93
95
  export declare const TOOL_REF_SEPARATOR = "/";
@@ -110,8 +112,13 @@ export interface IAiToolsetInfo {
110
112
  displayName: string;
111
113
  description: string;
112
114
  requires: ECapability[];
115
+ /** With ECapability.PROVIDERS: the ids of the providers it needs (e.g. ['aws']). The host lends ONLY these. */
116
+ providers?: string[];
117
+ configSchema?: IConfigFieldDef[];
113
118
  tools: IAiToolInfo[];
114
119
  }
120
+ /** A toolset's settings: what its `configSchema` describes, the defaults applied. Like `TRouterConfig`. */
121
+ export type TAiToolsetConfig = Record<string, unknown>;
115
122
  export interface IToolsetGrant {
116
123
  pluginId: string;
117
124
  allTools: boolean;
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.79",
3
+ "version": "0.5.81",
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": {