@kwirthmagnify/kwirth-common-ai 0.5.22 → 0.5.23

package/dist/back.d.ts

@@ -1,5 +1,5 @@
 import { IBackChannelObject } from '@kwirthmagnify/kwirth-common';
-import { ILlm, ILlmProvider } from './index';
+import { ILlm, ILlmProvider, IAgent } from './index';
 import { LanguageModel } from 'ai';
 import { z } from 'zod';
 export declare const buildModel: (llm: ILlm, providers: ILlmProvider[]) => LanguageModel | null;
@@ -14,9 +14,14 @@ export interface IToolContext {
     clusterMetrics: any[];
     trace: (toolName: string, args: Record<string, unknown>) => void;
 }
+export declare enum EToolEffect {
+    READ = "read",
+    WRITE = "write"
+}
 export interface IToolInfo {
     name: string;
     description: string;
+    effect: EToolEffect;
 }
 export declare const runWithToolContext: <T>(context: IToolContext, fn: () => Promise<T>) => Promise<T>;
 export declare const tools: {
@@ -315,3 +320,12 @@ export declare const tools: {
     }, unknown>;
 };
 export declare const toolInfoList: IToolInfo[];
+export interface IAgentRunResult {
+    text: string;
+    inputTokens: number;
+    outputTokens: number;
+    steps: number;
+    toolCalls: string[];
+}
+export declare const selectAgentToolNames: (agent: IAgent) => string[];
+export declare const runAgent: (agent: IAgent, prompt: string, llms: ILlm[], providers: ILlmProvider[], context: IToolContext) => Promise<IAgentRunResult>;

package/dist/back.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toolInfoList = exports.tools = exports.runWithToolContext = exports.zodFromExample = exports.z = exports.tool = exports.stepCountIs = exports.Output = exports.generateText = exports.loadModels = exports.buildModel = void 0;
+exports.runAgent = exports.selectAgentToolNames = exports.toolInfoList = exports.tools = exports.runWithToolContext = exports.EToolEffect = exports.zodFromExample = exports.z = exports.tool = exports.stepCountIs = exports.Output = exports.generateText = exports.loadModels = exports.buildModel = void 0;
 const ai_1 = require("ai");
 const zod_1 = require("zod");
 const async_hooks_1 = require("async_hooks");
@@ -174,6 +174,13 @@ const zodFromExample = (example) => {
     return zod_1.z.object(shape);
 };
 exports.zodFromExample = zodFromExample;
+// Effect of a tool: READ (safe, informational) or WRITE (has side effects on the cluster).
+// Dual purpose: hints the LLM, and gates authorization (Agora/readOnly filter out WRITE).
+var EToolEffect;
+(function (EToolEffect) {
+    EToolEffect["READ"] = "read";
+    EToolEffect["WRITE"] = "write";
+})(EToolEffect || (exports.EToolEffect = EToolEffect = {}));
 const toolContextStorage = new async_hooks_1.AsyncLocalStorage();
 const runWithToolContext = (context, fn) => toolContextStorage.run(context, fn);
 exports.runWithToolContext = runWithToolContext;
@@ -689,29 +696,75 @@ exports.tools = {
     }),
 };
 exports.toolInfoList = [
-    { name: 'list_namespaces', description: 'Lists all namespaces in the cluster with their status and labels.' },
-    { name: 'get_node_data', description: 'Returns configuration info about all Kubernetes nodes (name, IP). Configuration only — not workload or usage data.' },
-    { name: 'get_cluster_data', description: 'Returns general cluster info: name, flavour (AKS/EKS/GKE/k3s/k3d), total vCPUs, total memory, node count and readiness status.' },
-    { name: 'get_workload_data', description: 'Returns all workloads in the cluster: deployments, statefulsets, daemonsets, pods and services. Optionally filter by namespace.' },
-    { name: 'get_space_data', description: 'Returns all resources in a specific Kubernetes namespace: pods (with restart count), deployments, services, configmap names.' },
-    { name: 'get_service_yaml', description: 'Returns the full Kubernetes Service manifest (equivalent to kubectl get service -o yaml) for a given namespace and service name.' },
-    { name: 'list_services', description: 'Lists all Services in the cluster with full details (type, clusterIP, ports, selector). Optionally filter by namespace.' },
-    { name: 'list_ingresses', description: 'Lists all Ingresses in the cluster (hosts, paths, TLS, backend services). Optionally filter by namespace.' },
-    { name: 'get_ingress_yaml', description: 'Returns the full Kubernetes Ingress manifest (equivalent to kubectl get ingress -o yaml) for a given namespace and ingress name.' },
-    { name: 'get_cluster_usage', description: 'Returns current overall cluster resource usage: CPU%, memory%, network Mbps, total vCPUs and total memory GB.' },
-    { name: 'get_node_usage', description: 'Returns current CPU and memory usage for one node or all nodes from the latest metrics reading.' },
-    { name: 'get_deployment_usage', description: 'Returns current aggregated CPU and memory usage for all pods belonging to a specific deployment.' },
-    { name: 'get_prev_cluster_usage', description: 'Returns historical overall cluster usage over the last N metrics readings (CPU%, memory%, network Mbps).' },
-    { name: 'get_prev_node_usage', description: 'Returns historical CPU and memory usage for one or all nodes over the last N metrics readings.' },
-    { name: 'get_prev_deployment_usage', description: 'Returns historical aggregated CPU and memory usage for a deployment over the last N metrics readings.' },
-    { name: 'get_prev_space_data', description: 'Returns historical aggregated CPU and memory usage for all pods in a namespace over the last N metrics readings.' },
-    { name: 'add_node', description: 'Adds a new agent node to the cluster. For k3d uses `k3d node create`. Cloud providers not yet implemented.' },
-    { name: 'remove_node', description: 'Removes a node from the cluster (cordon + delete). For k3d uses `k3d node delete`. Cloud providers not yet implemented.' },
-    { name: 'stop_node', description: 'Stops a running cluster node: cordons it then stops the container. For k3d uses `k3d node stop`.' },
-    { name: 'start_node', description: 'Starts a previously stopped cluster node and uncordons it. For k3d uses `k3d node start`.' },
-    { name: 'add_replica', description: 'Scales up a deployment by adding one replica.' },
-    { name: 'remove_replica', description: 'Scales down a deployment by removing one replica. Minimum of 1 replica is enforced.' },
-    { name: 'times_two', description: 'Multiplies a number by two.' },
-    { name: 'father_of', description: 'Returns the name of the father of a person.' },
-    { name: 'get_certificate_info', description: 'Connects to a hostname via HTTPS and returns TLS certificate details: subject, issuer, validity dates, SANs, fingerprint and whether it is currently valid.' },
+    { name: 'list_namespaces', effect: EToolEffect.READ, description: 'Lists all namespaces in the cluster with their status and labels.' },
+    { name: 'get_node_data', effect: EToolEffect.READ, description: 'Returns configuration info about all Kubernetes nodes (name, IP). Configuration only — not workload or usage data.' },
+    { name: 'get_cluster_data', effect: EToolEffect.READ, description: 'Returns general cluster info: name, flavour (AKS/EKS/GKE/k3s/k3d), total vCPUs, total memory, node count and readiness status.' },
+    { name: 'get_workload_data', effect: EToolEffect.READ, description: 'Returns all workloads in the cluster: deployments, statefulsets, daemonsets, pods and services. Optionally filter by namespace.' },
+    { name: 'get_space_data', effect: EToolEffect.READ, description: 'Returns all resources in a specific Kubernetes namespace: pods (with restart count), deployments, services, configmap names.' },
+    { name: 'get_service_yaml', effect: EToolEffect.READ, description: 'Returns the full Kubernetes Service manifest (equivalent to kubectl get service -o yaml) for a given namespace and service name.' },
+    { name: 'list_services', effect: EToolEffect.READ, description: 'Lists all Services in the cluster with full details (type, clusterIP, ports, selector). Optionally filter by namespace.' },
+    { name: 'list_ingresses', effect: EToolEffect.READ, description: 'Lists all Ingresses in the cluster (hosts, paths, TLS, backend services). Optionally filter by namespace.' },
+    { name: 'get_ingress_yaml', effect: EToolEffect.READ, description: 'Returns the full Kubernetes Ingress manifest (equivalent to kubectl get ingress -o yaml) for a given namespace and ingress name.' },
+    { name: 'get_cluster_usage', effect: EToolEffect.READ, description: 'Returns current overall cluster resource usage: CPU%, memory%, network Mbps, total vCPUs and total memory GB.' },
+    { name: 'get_node_usage', effect: EToolEffect.READ, description: 'Returns current CPU and memory usage for one node or all nodes from the latest metrics reading.' },
+    { name: 'get_deployment_usage', effect: EToolEffect.READ, description: 'Returns current aggregated CPU and memory usage for all pods belonging to a specific deployment.' },
+    { name: 'get_prev_cluster_usage', effect: EToolEffect.READ, description: 'Returns historical overall cluster usage over the last N metrics readings (CPU%, memory%, network Mbps).' },
+    { name: 'get_prev_node_usage', effect: EToolEffect.READ, description: 'Returns historical CPU and memory usage for one or all nodes over the last N metrics readings.' },
+    { name: 'get_prev_deployment_usage', effect: EToolEffect.READ, description: 'Returns historical aggregated CPU and memory usage for a deployment over the last N metrics readings.' },
+    { name: 'get_prev_space_data', effect: EToolEffect.READ, description: 'Returns historical aggregated CPU and memory usage for all pods in a namespace over the last N metrics readings.' },
+    { name: 'add_node', effect: EToolEffect.WRITE, description: 'Adds a new agent node to the cluster. For k3d uses `k3d node create`. Cloud providers not yet implemented.' },
+    { name: 'remove_node', effect: EToolEffect.WRITE, description: 'Removes a node from the cluster (cordon + delete). For k3d uses `k3d node delete`. Cloud providers not yet implemented.' },
+    { name: 'stop_node', effect: EToolEffect.WRITE, description: 'Stops a running cluster node: cordons it then stops the container. For k3d uses `k3d node stop`.' },
+    { name: 'start_node', effect: EToolEffect.WRITE, description: 'Starts a previously stopped cluster node and uncordons it. For k3d uses `k3d node start`.' },
+    { name: 'add_replica', effect: EToolEffect.WRITE, description: 'Scales up a deployment by adding one replica.' },
+    { name: 'remove_replica', effect: EToolEffect.WRITE, description: 'Scales down a deployment by removing one replica. Minimum of 1 replica is enforced.' },
+    { name: 'times_two', effect: EToolEffect.READ, description: 'Multiplies a number by two.' },
+    { name: 'father_of', effect: EToolEffect.READ, description: 'Returns the name of the father of a person.' },
+    { name: 'get_certificate_info', effect: EToolEffect.READ, description: 'Connects to a hostname via HTTPS and returns TLS certificate details: subject, issuer, validity dates, SANs, fingerprint and whether it is currently valid.' },
 ];
+// Resolves the tool names an agent may use: autoTools = full catalog, otherwise its own list
+// (intersected with the catalog); readOnly filters out WRITE-effect tools. Pure (no LLM) → unit-testable.
+const selectAgentToolNames = (agent) => {
+    const writeNames = new Set(exports.toolInfoList.filter(t => t.effect === EToolEffect.WRITE).map(t => t.name));
+    const catalogNames = exports.toolInfoList.map(t => t.name);
+    const wanted = agent.autoTools ? catalogNames : agent.tools.filter(n => catalogNames.includes(n));
+    return wanted.filter(n => !(agent.readOnly && writeNames.has(n)));
+};
+exports.selectAgentToolNames = selectAgentToolNames;
+// Runs an IAgent: resolves its LLM, selects/filters its tools (readOnly drops WRITE-effect tools) and
+// invokes the model within the k8s tool context. Wraps the existing engine (buildModel + generateText +
+// runWithToolContext) — factors the pattern pinocchio does by hand, reusable by Agora/pinocchio/defender.
+// No providerOptions here: pinocchio's are for structured output; a chat/tool agent returns free text.
+const runAgent = async (agent, prompt, llms, providers, context) => {
+    var _a, _b, _c, _d, _e, _f, _g, _h;
+    const llm = llms.find(l => l.id === agent.llm);
+    if (!llm)
+        throw new Error(`[common-ai] runAgent: llm '${agent.llm}' not found`);
+    const model = (0, exports.buildModel)(llm, providers);
+    if (!model)
+        throw new Error(`[common-ai] runAgent: could not build model for llm '${agent.llm}'`);
+    const allowed = new Set((0, exports.selectAgentToolNames)(agent));
+    const selectedTools = Object.fromEntries(Object.entries(exports.tools).filter(([n]) => allowed.has(n)));
+    const result = await (0, exports.runWithToolContext)(context, () => (0, ai_1.generateText)({
+        model,
+        temperature: llm.temperature,
+        stopWhen: (0, ai_1.stepCountIs)(agent.steps || 15),
+        tools: selectedTools,
+        system: agent.system,
+        prompt
+    }));
+    const toolCalls = [];
+    for (const step of ((_a = result.steps) !== null && _a !== void 0 ? _a : [])) {
+        const s = step;
+        for (const call of ((_b = s.toolCalls) !== null && _b !== void 0 ? _b : []))
+            toolCalls.push(call.toolName);
+    }
+    return {
+        text: result.text,
+        inputTokens: (_d = (_c = result.usage) === null || _c === void 0 ? void 0 : _c.inputTokens) !== null && _d !== void 0 ? _d : 0,
+        outputTokens: (_f = (_e = result.usage) === null || _e === void 0 ? void 0 : _e.outputTokens) !== null && _f !== void 0 ? _f : 0,
+        steps: (_h = (_g = result.steps) === null || _g === void 0 ? void 0 : _g.length) !== null && _h !== void 0 ? _h : 0,
+        toolCalls
+    };
+};
+exports.runAgent = runAgent;

package/dist/index.d.ts

@@ -23,3 +23,16 @@ export interface ILlm {
     outputCostPerMillion?: number;
     data?: unknown;
 }
+export declare const STORAGE_KEY_AGENTS = "kwirth-ai-agents";
+export interface IAgent {
+    id: string;
+    name: string;
+    description: string;
+    cluster: string;
+    llm: string;
+    system: string;
+    tools: string[];
+    autoTools: boolean;
+    steps: number;
+    readOnly: boolean;
+}

package/dist/index.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PROVIDERS_AVAILABLE = exports.STORAGE_KEY_LLMS = exports.STORAGE_KEY_PROVIDERS = void 0;
+exports.STORAGE_KEY_AGENTS = exports.PROVIDERS_AVAILABLE = exports.STORAGE_KEY_LLMS = exports.STORAGE_KEY_PROVIDERS = void 0;
 exports.STORAGE_KEY_PROVIDERS = 'kwirth-ai-providers';
 exports.STORAGE_KEY_LLMS = 'kwirth-ai-llms';
 exports.PROVIDERS_AVAILABLE = ['google', 'openai', 'openrouter', 'mistral', 'groq', 'deepseek'];
+exports.STORAGE_KEY_AGENTS = 'kwirth-ai-agents';

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@kwirthmagnify/kwirth-common-ai",
-  "version": "0.5.22",
+  "version": "0.5.23",
   "description": "Shared AI/LLM types and utilities for Kwirth AI plugins",
   "scripts": {
-    "build": "del .\\dist\\* /s /q 2>nul & tsc"
+    "build": "del .\\dist\\* /s /q 2>nul & tsc",
+    "test": "node --test tests/agent.test.mjs"
   },
   "publishConfig": {
     "access": "public"