@kwirthmagnify/kwirth-common-ai 0.5.53 → 0.5.55

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.
Files changed (3) hide show
  1. package/dist/back.d.ts +126 -3
  2. package/dist/back.js +129 -1
  3. package/package.json +79 -69
package/dist/back.d.ts CHANGED
@@ -1,10 +1,11 @@
1
- import { ILlm, ILlmProvider, IAgent, EToolEffect, IAiToolInfo, IAiToolsetInfo } from './index';
1
+ import { ILlm, ILlmProvider, IAgent, ECapability, EToolEffect, IAiToolInfo, IAiToolsetInfo, IToolsetConfig } from './index';
2
+ import type { AppsV1Api, CoreV1Api, NetworkingV1Api } from '@kubernetes/client-node';
2
3
  interface ILogChannel {
3
4
  logInfo?: (msg: string) => void;
4
5
  logWarning?: (msg: string) => void;
5
6
  logError?: (msg: string) => void;
6
7
  }
7
- import { LanguageModel } from 'ai';
8
+ import { LanguageModel, ToolSet } from 'ai';
8
9
  import { z } from 'zod';
9
10
  export declare const buildModel: (llm: ILlm, providers: ILlmProvider[]) => LanguageModel | null;
10
11
  export interface IVisionResult<T> {
@@ -53,10 +54,56 @@ export interface IToolInfo {
53
54
  effect: EToolEffect;
54
55
  }
55
56
  export declare const runWithToolContext: <T>(context: IToolContext, fn: () => Promise<T>) => Promise<T>;
57
+ /** Un nodo del cluster, tal y como lo ve una tool. Compatible con el `INodeInfo` del core. */
58
+ export interface IK8sNodeInfo {
59
+ name: string;
60
+ ip: string;
61
+ maxPods: number;
62
+ }
63
+ /** Acceso a Kubernetes (`ECapability.K8S`). */
64
+ export interface IK8sCapability {
65
+ /** Nombre del cluster tal y como lo conoce Kwirth. */
66
+ name: string;
67
+ /** Sabor detectado: aks, eks, gke, k3s, k3d… */
68
+ flavour: string;
69
+ vcpus: number;
70
+ /** Memoria total del cluster, en bytes. */
71
+ memory: number;
72
+ nodes: Map<string, IK8sNodeInfo>;
73
+ coreApi: CoreV1Api;
74
+ appsApi: AppsV1Api;
75
+ networkApi: NetworkingV1Api;
76
+ }
77
+ /** Metricas del cluster (`ECapability.METRICS`). */
78
+ export interface IMetricsCapability {
79
+ /** Muestras de metricas que el core mantiene en memoria. */
80
+ samples: unknown[];
81
+ }
82
+ /** Eventos recientes del cluster (`ECapability.EVENTS`). */
83
+ export interface IEventsCapability {
84
+ /** Buffer de eventos ({type, obj}) que el core va acumulando. */
85
+ recent: unknown[];
86
+ }
87
+ /** Credenciales de repositorios fuente (`ECapability.REPOS`). */
88
+ export interface IReposCapability {
89
+ creds: ISourceRepoCred[];
90
+ }
91
+ /**
92
+ * Lo que recibe una tool al ejecutarse. Solo vienen rellenas las capabilities declaradas por su toolset:
93
+ * un `requires: []` recibe unicamente `trace`.
94
+ */
95
+ export interface IToolHost {
96
+ /** Deja constancia de la invocacion. NO es una capability: se presta siempre, y no se declara. */
97
+ trace: (toolName: string, args: Record<string, unknown>) => void;
98
+ k8s?: IK8sCapability;
99
+ metrics?: IMetricsCapability;
100
+ events?: IEventsCapability;
101
+ repos?: IReposCapability;
102
+ }
56
103
  /** Una tool ejecutable: lo que viaja al front (IAiToolInfo) mas lo que hace falta para invocarla. */
57
104
  export interface IAiTool extends IAiToolInfo {
58
105
  inputSchema: z.ZodTypeAny;
59
- execute: (args: Record<string, unknown>) => Promise<unknown>;
106
+ execute: (args: Record<string, unknown>, host: IToolHost) => Promise<unknown>;
60
107
  }
61
108
  /** Un toolset ejecutable: su ficha (IAiToolsetInfo) con las tools de verdad dentro. */
62
109
  export interface IAiToolset extends Omit<IAiToolsetInfo, 'tools'> {
@@ -75,11 +122,87 @@ export declare const getToolset: (id: string) => IAiToolset | undefined;
75
122
  export declare const listToolsets: () => IAiToolset[];
76
123
  /** Lo que se le manda al front: las fichas, sin inputSchema ni execute. */
77
124
  export declare const listToolsetInfos: () => IAiToolsetInfo[];
125
+ /**
126
+ * Construye el host de un toolset a partir del contexto del core, provisionando SOLO lo declarado.
127
+ *
128
+ * Que el reparto se haga aqui y no en cada llamada es lo que hace cumplible la promesa de `ECapability`:
129
+ * si cada sitio armara su propio objeto, bastaria con que uno se pasara de generoso para que la
130
+ * declaracion dejara de significar nada.
131
+ */
132
+ export declare const buildToolHost: (requires: ECapability[], context: IToolContext) => IToolHost;
133
+ /**
134
+ * Invoca una tool por su referencia cualificada. Un unico camino de invocacion para built-in e
135
+ * instalado, con el host construido segun el `requires` de SU toolset.
136
+ */
137
+ export declare const invokeToolRef: (ref: string, args: Record<string, unknown>, context: IToolContext) => Promise<unknown>;
78
138
  /** Resuelve una referencia cualificada '<toolset>/<tool>' contra el registro. */
79
139
  export declare const resolveToolRef: (ref: string) => {
80
140
  toolset: IAiToolset;
81
141
  tool: IAiTool;
82
142
  } | undefined;
143
+ /** Una tool que SI se le ofrece al modelo. */
144
+ export interface IEffectiveTool {
145
+ /** El nombre corto: lo que viaja al LLM. */
146
+ name: string;
147
+ /** La referencia cualificada: lo que se persiste. */
148
+ ref: string;
149
+ toolsetId: string;
150
+ tool: IAiTool;
151
+ }
152
+ /** Una tool que existe pero NO se ofrece, porque otro toolset de mas precedencia trae ese nombre. */
153
+ export interface IShadowedTool {
154
+ name: string;
155
+ ref: string;
156
+ toolsetId: string;
157
+ /** Quien la tapa. El editor tiene que decirlo: si no, apagar esta parece hacer algo y no hace nada. */
158
+ shadowedBy: string;
159
+ }
160
+ export interface IToolResolution {
161
+ effective: IEffectiveTool[];
162
+ shadowed: IShadowedTool[];
163
+ /** Toolsets asignados que no estan registrados (desinstalados, o nunca instalados). */
164
+ missing: string[];
165
+ }
166
+ /**
167
+ * Aplica el techo de un cliente sobre el registro. Pura: ni ejecuta ni toca el contexto, asi que el
168
+ * editor puede llamarla para PINTAR lo mismo que se va a ejecutar.
169
+ *
170
+ * Una tool apagada no tapa: se apaga una referencia concreta ('ts1/td'), no un nombre, asi que si `ts1/td`
171
+ * esta apagada y `ts2` trae otra `td`, aflora la de `ts2`.
172
+ */
173
+ export declare const resolveTools: (config: IToolsetConfig) => IToolResolution;
174
+ /** Una invocacion concreta, tal y como la ven los dos ganchos. */
175
+ export interface IToolInvocation {
176
+ ref: string;
177
+ toolsetId: string;
178
+ toolName: string;
179
+ args: Record<string, unknown>;
180
+ }
181
+ export interface IToolAuthorization {
182
+ allowed: boolean;
183
+ /** Por que no. Viaja al modelo, asi que se escribe para que pueda decidir otra cosa. */
184
+ reason?: string;
185
+ }
186
+ /** Como acabo una invocacion. `ms` incluido: una tool lenta es un problema aunque devuelva bien. */
187
+ export interface IToolOutcome {
188
+ ok: boolean;
189
+ result?: unknown;
190
+ error?: string;
191
+ ms: number;
192
+ /** Si no llego a ejecutarse por el gancho de autorizacion. */
193
+ denied?: boolean;
194
+ }
195
+ export interface IAgentToolHooks {
196
+ /** ANTES de ejecutar. Sin gancho, se permite todo: hoy el techo lo pone la seleccion (S4 lo llena). */
197
+ authorize?: (invocation: IToolInvocation, tool: IAiTool) => IToolAuthorization | Promise<IToolAuthorization>;
198
+ /** DESPUES, pase lo que pase. No puede romper la invocacion (S6 lo llena). */
199
+ observe?: (invocation: IToolInvocation, outcome: IToolOutcome) => void;
200
+ }
201
+ /**
202
+ * Las tools listas para pasarselas al SDK de IA, ya resueltas por precedencia y con los dos ganchos
203
+ * puestos. La clave del objeto es el nombre CORTO, que es lo unico que el proveedor acepta.
204
+ */
205
+ export declare const buildAgentTools: (config: IToolsetConfig, context: IToolContext, hooks?: IAgentToolHooks) => ToolSet;
83
206
  export declare const tools: {
84
207
  readonly list_namespaces: import("ai").Tool<Record<string, never>, {
85
208
  namespaces: any;
package/dist/back.js CHANGED
@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
- exports.runAgent = exports.selectAgentToolNames = exports.toolInfoList = exports.tools = exports.resolveToolRef = exports.listToolsetInfos = exports.listToolsets = exports.getToolset = exports.unregisterToolset = exports.registerToolset = exports.isBuiltInToolsetId = exports.runWithToolContext = exports.EToolEffect = exports.zodFromExample = exports.z = exports.tool = exports.stepCountIs = exports.Output = exports.generateText = exports.loadModels = exports.generateVision = exports.buildModel = void 0;
36
+ exports.runAgent = exports.selectAgentToolNames = exports.toolInfoList = exports.tools = exports.buildAgentTools = exports.resolveTools = exports.resolveToolRef = exports.invokeToolRef = exports.buildToolHost = exports.listToolsetInfos = exports.listToolsets = exports.getToolset = exports.unregisterToolset = exports.registerToolset = exports.isBuiltInToolsetId = exports.runWithToolContext = exports.EToolEffect = exports.zodFromExample = exports.z = exports.tool = exports.stepCountIs = exports.Output = exports.generateText = exports.loadModels = exports.generateVision = exports.buildModel = void 0;
37
37
  const index_1 = require("./index");
38
38
  const ai_1 = require("ai");
39
39
  const zod_1 = require("zod");
@@ -431,6 +431,51 @@ const listToolsetInfos = () => (0, exports.listToolsets)().map(t => ({
431
431
  tools: t.tools.map(x => ({ name: x.name, description: x.description, effect: x.effect, sensitivity: x.sensitivity }))
432
432
  }));
433
433
  exports.listToolsetInfos = listToolsetInfos;
434
+ /**
435
+ * Construye el host de un toolset a partir del contexto del core, provisionando SOLO lo declarado.
436
+ *
437
+ * Que el reparto se haga aqui y no en cada llamada es lo que hace cumplible la promesa de `ECapability`:
438
+ * si cada sitio armara su propio objeto, bastaria con que uno se pasara de generoso para que la
439
+ * declaracion dejara de significar nada.
440
+ */
441
+ const buildToolHost = (requires, context) => {
442
+ var _a, _b, _c;
443
+ const host = { trace: context.trace };
444
+ const ci = context.clusterInfo;
445
+ // Sin cluster no hay capability de cluster, aunque se declare: es preferible que la tool reciba
446
+ // 'undefined' y lo diga, a entregarle una fachada a medio montar que falle por dentro.
447
+ if (requires.includes(index_1.ECapability.K8S) && ci) {
448
+ host.k8s = {
449
+ name: ci.name,
450
+ flavour: ci.flavour,
451
+ vcpus: ci.vcpus,
452
+ memory: ci.memory,
453
+ nodes: context.nodes,
454
+ coreApi: ci.coreApi,
455
+ appsApi: ci.appsApi,
456
+ networkApi: ci.networkApi
457
+ };
458
+ }
459
+ if (requires.includes(index_1.ECapability.METRICS))
460
+ host.metrics = { samples: (_a = context.clusterMetrics) !== null && _a !== void 0 ? _a : [] };
461
+ if (requires.includes(index_1.ECapability.EVENTS))
462
+ host.events = { recent: (_b = context.clusterEvents) !== null && _b !== void 0 ? _b : [] };
463
+ if (requires.includes(index_1.ECapability.REPOS))
464
+ host.repos = { creds: (_c = context.sourceRepos) !== null && _c !== void 0 ? _c : [] };
465
+ return host;
466
+ };
467
+ exports.buildToolHost = buildToolHost;
468
+ /**
469
+ * Invoca una tool por su referencia cualificada. Un unico camino de invocacion para built-in e
470
+ * instalado, con el host construido segun el `requires` de SU toolset.
471
+ */
472
+ const invokeToolRef = async (ref, args, context) => {
473
+ const resolved = (0, exports.resolveToolRef)(ref);
474
+ if (!resolved)
475
+ throw new Error(`[common-ai] unknown tool '${ref}'`);
476
+ return resolved.tool.execute(args, (0, exports.buildToolHost)(resolved.toolset.requires, context));
477
+ };
478
+ exports.invokeToolRef = invokeToolRef;
434
479
  /** Resuelve una referencia cualificada '<toolset>/<tool>' contra el registro. */
435
480
  const resolveToolRef = (ref) => {
436
481
  const parsed = (0, index_1.parseToolRef)(ref);
@@ -441,6 +486,89 @@ const resolveToolRef = (ref) => {
441
486
  return toolset && tool ? { toolset, tool } : undefined;
442
487
  };
443
488
  exports.resolveToolRef = resolveToolRef;
489
+ /**
490
+ * Aplica el techo de un cliente sobre el registro. Pura: ni ejecuta ni toca el contexto, asi que el
491
+ * editor puede llamarla para PINTAR lo mismo que se va a ejecutar.
492
+ *
493
+ * Una tool apagada no tapa: se apaga una referencia concreta ('ts1/td'), no un nombre, asi que si `ts1/td`
494
+ * esta apagada y `ts2` trae otra `td`, aflora la de `ts2`.
495
+ */
496
+ const resolveTools = (config) => {
497
+ const disabled = new Set(config.disabledTools);
498
+ const effective = [];
499
+ const shadowed = [];
500
+ const missing = [];
501
+ const taken = new Map(); // nombre corto → toolset que lo sirve
502
+ for (const toolsetId of config.activeToolsets) {
503
+ const toolset = toolsetRegistry.get(toolsetId);
504
+ if (!toolset) {
505
+ // No se calla: un techo que nombra algo que no esta instalado es una config rota, y el
506
+ // sintoma sin esto seria "el agente responde peor" sin que nadie sepa por que.
507
+ missing.push(toolsetId);
508
+ continue;
509
+ }
510
+ for (const tool of toolset.tools) {
511
+ const ref = (0, index_1.toolRef)(toolsetId, tool.name);
512
+ if (disabled.has(ref))
513
+ continue;
514
+ const owner = taken.get(tool.name);
515
+ if (owner) {
516
+ shadowed.push({ name: tool.name, ref, toolsetId, shadowedBy: owner });
517
+ continue;
518
+ }
519
+ taken.set(tool.name, toolsetId);
520
+ effective.push({ name: tool.name, ref, toolsetId, tool });
521
+ }
522
+ }
523
+ return { effective, shadowed, missing };
524
+ };
525
+ exports.resolveTools = resolveTools;
526
+ /**
527
+ * Las tools listas para pasarselas al SDK de IA, ya resueltas por precedencia y con los dos ganchos
528
+ * puestos. La clave del objeto es el nombre CORTO, que es lo unico que el proveedor acepta.
529
+ */
530
+ const buildAgentTools = (config, context, hooks = {}) => {
531
+ const { effective } = (0, exports.resolveTools)(config);
532
+ const entries = effective.map(e => {
533
+ const invocationOf = (args) => ({ ref: e.ref, toolsetId: e.toolsetId, toolName: e.name, args });
534
+ // `dynamicTool` y no `tool`: el esquema de una tool empaquetada no se conoce en compilacion, y el
535
+ // helper tipado infiere `never` para un ZodTypeAny generico.
536
+ return [e.name, (0, ai_1.dynamicTool)({
537
+ description: e.tool.description,
538
+ inputSchema: e.tool.inputSchema,
539
+ execute: async (rawArgs) => {
540
+ var _a, _b, _c, _d, _e;
541
+ const args = (rawArgs !== null && rawArgs !== void 0 ? rawArgs : {});
542
+ const invocation = invocationOf(args);
543
+ const started = Date.now();
544
+ const verdict = hooks.authorize ? await hooks.authorize(invocation, e.tool) : { allowed: true };
545
+ if (!verdict.allowed) {
546
+ // Se devuelve como DATO, no como excepcion: una excepcion corta la conversacion, y lo
547
+ // que queremos es que el modelo sepa que esa via esta cerrada y pruebe otra.
548
+ const denial = { error: `tool '${e.name}' not allowed${verdict.reason ? `: ${verdict.reason}` : ''}` };
549
+ (_a = hooks.observe) === null || _a === void 0 ? void 0 : _a.call(hooks, invocation, { ok: false, error: denial.error, ms: Date.now() - started, denied: true });
550
+ return denial;
551
+ }
552
+ 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);
553
+ try {
554
+ // El runWithToolContext envuelve tambien a las tools escritas contra el contrato VIEJO
555
+ // (las que leen ctx()). Es lo que permite migrar las 43 paquete a paquete en S3 en vez
556
+ // de tener que reescribirlas todas antes de poder usar este camino.
557
+ const result = await (0, exports.runWithToolContext)(context, () => e.tool.execute(args, host));
558
+ (_d = hooks.observe) === null || _d === void 0 ? void 0 : _d.call(hooks, invocation, { ok: true, result, ms: Date.now() - started });
559
+ return result;
560
+ }
561
+ catch (err) {
562
+ const message = err instanceof Error ? err.message : String(err);
563
+ (_e = hooks.observe) === null || _e === void 0 ? void 0 : _e.call(hooks, invocation, { ok: false, error: message, ms: Date.now() - started });
564
+ return { error: message };
565
+ }
566
+ }
567
+ })];
568
+ });
569
+ return Object.fromEntries(entries);
570
+ };
571
+ exports.buildAgentTools = buildAgentTools;
444
572
  exports.tools = {
445
573
  // ── CLUSTER CONFIG ───────────────────────────────────────────────────────
446
574
  list_namespaces: (0, ai_1.tool)({
package/package.json CHANGED
@@ -1,69 +1,79 @@
1
- {
2
- "name": "@kwirthmagnify/kwirth-common-ai",
3
- "version": "0.5.53",
4
- "description": "Shared AI/LLM types and utilities for Kwirth AI plugins",
5
- "scripts": {
6
- "build": "del .\\dist\\* /s /q 2>nul & tsc",
7
- "test": "node --test tests/*.test.mjs"
8
- },
9
- "publishConfig": {
10
- "access": "public"
11
- },
12
- "main": "dist/index.js",
13
- "module": "dist/index.js",
14
- "types": "dist/index.d.ts",
15
- "exports": {
16
- ".": {
17
- "types": "./dist/index.d.ts",
18
- "require": "./dist/index.js",
19
- "default": "./dist/index.js"
20
- },
21
- "./back": {
22
- "types": "./dist/back.d.ts",
23
- "require": "./dist/back.js",
24
- "default": "./dist/back.js"
25
- },
26
- "./front": {
27
- "types": "./dist/front.d.ts",
28
- "require": "./dist/front.js",
29
- "default": "./dist/front.js"
30
- }
31
- },
32
- "typesVersions": {
33
- "*": {
34
- "back": [
35
- "dist/back.d.ts"
36
- ],
37
- "front": [
38
- "dist/front.d.ts"
39
- ]
40
- }
41
- },
42
- "files": [
43
- "dist"
44
- ],
45
- "author": "Julio Fernandez",
46
- "license": "ISC",
47
- "dependencies": {
48
- "@ai-sdk/anthropic": "^3.0.116",
49
- "@ai-sdk/deepseek": "^2.0.29",
50
- "@ai-sdk/google": "^3.0.64",
51
- "@ai-sdk/groq": "^3.0.35",
52
- "@ai-sdk/mistral": "^3.0.30",
53
- "@ai-sdk/openai": "^3.0.53",
54
- "@openrouter/ai-sdk-provider": "^2.8.0",
55
- "ai": "^6.0.174",
56
- "zod": "^4.3.6"
57
- },
58
- "peerDependencies": {
59
- "react": ">=18.0.0"
60
- },
61
- "devDependencies": {
62
- "@kwirthmagnify/kwirth-common": "^0.5.42",
63
- "@mui/icons-material": "7.1.2",
64
- "@mui/material": "7.1.2",
65
- "@types/node": "^25.9.1",
66
- "@types/react": "^18.3.0",
67
- "typescript": "^5.4.0"
68
- }
69
- }
1
+ {
2
+ "name": "@kwirthmagnify/kwirth-common-ai",
3
+ "version": "0.5.55",
4
+ "description": "Shared AI/LLM types and utilities for Kwirth AI plugins",
5
+ "scripts": {
6
+ "build": "del .\\dist\\* /s /q 2>nul & tsc",
7
+ "test": "node --test tests/*.test.mjs"
8
+ },
9
+ "publishConfig": {
10
+ "access": "public"
11
+ },
12
+ "main": "dist/index.js",
13
+ "module": "dist/index.js",
14
+ "types": "dist/index.d.ts",
15
+ "exports": {
16
+ ".": {
17
+ "types": "./dist/index.d.ts",
18
+ "require": "./dist/index.js",
19
+ "default": "./dist/index.js"
20
+ },
21
+ "./back": {
22
+ "types": "./dist/back.d.ts",
23
+ "require": "./dist/back.js",
24
+ "default": "./dist/back.js"
25
+ },
26
+ "./front": {
27
+ "types": "./dist/front.d.ts",
28
+ "require": "./dist/front.js",
29
+ "default": "./dist/front.js"
30
+ }
31
+ },
32
+ "typesVersions": {
33
+ "*": {
34
+ "back": [
35
+ "dist/back.d.ts"
36
+ ],
37
+ "front": [
38
+ "dist/front.d.ts"
39
+ ]
40
+ }
41
+ },
42
+ "files": [
43
+ "dist"
44
+ ],
45
+ "author": "Julio Fernandez",
46
+ "license": "ISC",
47
+ "dependencies": {
48
+ "@ai-sdk/anthropic": "^3.0.116",
49
+ "@ai-sdk/deepseek": "^2.0.29",
50
+ "@ai-sdk/google": "^3.0.64",
51
+ "@ai-sdk/groq": "^3.0.35",
52
+ "@ai-sdk/mistral": "^3.0.30",
53
+ "@ai-sdk/openai": "^3.0.53",
54
+ "@openrouter/ai-sdk-provider": "^2.8.0",
55
+ "ai": "^6.0.174",
56
+ "zod": "^4.3.6"
57
+ },
58
+ "peerDependencies": {
59
+ "react": ">=18.0.0",
60
+ "@kubernetes/client-node": ">=1.0.0"
61
+ },
62
+ "devDependencies": {
63
+ "@kwirthmagnify/kwirth-common": "^0.5.42",
64
+ "@mui/icons-material": "7.1.2",
65
+ "@mui/material": "7.1.2",
66
+ "@types/node": "^25.9.1",
67
+ "@types/react": "^18.3.0",
68
+ "typescript": "^5.4.0",
69
+ "@kubernetes/client-node": "^1.4.0"
70
+ },
71
+ "peerDependenciesMeta": {
72
+ "@kubernetes/client-node": {
73
+ "optional": true
74
+ },
75
+ "react": {
76
+ "optional": true
77
+ }
78
+ }
79
+ }