@kwirthmagnify/kwirth-common-ai 0.5.24 → 0.5.26

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
@@ -12,6 +12,7 @@ export interface IToolContext {
12
12
  nodes: Map<string, any>;
13
13
  clusterInfo: any;
14
14
  clusterMetrics: any[];
15
+ clusterEvents?: any[];
15
16
  trace: (toolName: string, args: Record<string, unknown>) => void;
16
17
  }
17
18
  export declare enum EToolEffect {
@@ -318,6 +319,85 @@ export declare const tools: {
318
319
  hostname: string;
319
320
  port?: number | undefined;
320
321
  }, unknown>;
322
+ readonly get_cluster_events: import("ai").Tool<{
323
+ warningsOnly?: boolean | undefined;
324
+ namespace?: string | undefined;
325
+ limit?: number | undefined;
326
+ }, {
327
+ count: number;
328
+ events: Record<string, unknown>[];
329
+ }>;
330
+ readonly get_object_events: import("ai").Tool<{
331
+ namespace: string;
332
+ name: string;
333
+ }, {
334
+ count: number;
335
+ events: Record<string, unknown>[];
336
+ }>;
337
+ readonly get_pod_logs: import("ai").Tool<{
338
+ namespace: string;
339
+ name: string;
340
+ container?: string | undefined;
341
+ previous?: boolean | undefined;
342
+ tailLines?: number | undefined;
343
+ }, {
344
+ namespace: string;
345
+ name: string;
346
+ container: string | null;
347
+ previous: boolean;
348
+ truncated: boolean;
349
+ logs: string;
350
+ error?: undefined;
351
+ } | {
352
+ error: any;
353
+ namespace?: undefined;
354
+ name?: undefined;
355
+ container?: undefined;
356
+ previous?: undefined;
357
+ truncated?: undefined;
358
+ logs?: undefined;
359
+ }>;
360
+ readonly describe_pod: import("ai").Tool<{
361
+ namespace: string;
362
+ name: string;
363
+ }, {
364
+ name: string;
365
+ namespace: string;
366
+ phase: any;
367
+ node: any;
368
+ startTime: any;
369
+ reason: any;
370
+ message: any;
371
+ conditions: any;
372
+ containers: any;
373
+ initContainers: any;
374
+ spec: {
375
+ containers: any;
376
+ restartPolicy: any;
377
+ };
378
+ error?: undefined;
379
+ } | {
380
+ error: any;
381
+ name?: undefined;
382
+ namespace?: undefined;
383
+ phase?: undefined;
384
+ node?: undefined;
385
+ startTime?: undefined;
386
+ reason?: undefined;
387
+ message?: undefined;
388
+ conditions?: undefined;
389
+ containers?: undefined;
390
+ initContainers?: undefined;
391
+ spec?: undefined;
392
+ }>;
393
+ readonly get_pod_yaml: import("ai").Tool<{
394
+ namespace: string;
395
+ name: string;
396
+ }, any>;
397
+ readonly get_deployment_yaml: import("ai").Tool<{
398
+ namespace: string;
399
+ name: string;
400
+ }, any>;
321
401
  };
322
402
  export declare const toolInfoList: IToolInfo[];
323
403
  export interface IAgentRunResult {
package/dist/back.js CHANGED
@@ -207,6 +207,29 @@ function mapToJson(data) {
207
207
  }
208
208
  return data;
209
209
  }
210
+ // Compact, LLM-friendly view of one buffered event ({type, obj}): a CoreV1Event (kind='Event') or an
211
+ // object lifecycle change.
212
+ const summarizeClusterEvent = (e) => {
213
+ var _a, _b, _c, _d;
214
+ const o = (_a = e === null || e === void 0 ? void 0 : e.obj) !== null && _a !== void 0 ? _a : {};
215
+ if (o.kind === 'Event') {
216
+ return {
217
+ kind: 'Event',
218
+ eventType: o.type, // Normal | Warning
219
+ reason: o.reason,
220
+ message: o.message,
221
+ involved: o.involvedObject ? { kind: o.involvedObject.kind, name: o.involvedObject.name, namespace: o.involvedObject.namespace } : undefined,
222
+ count: o.count,
223
+ lastTimestamp: (_b = o.lastTimestamp) !== null && _b !== void 0 ? _b : o.eventTime
224
+ };
225
+ }
226
+ return {
227
+ changeType: e === null || e === void 0 ? void 0 : e.type, // ADDED | MODIFIED
228
+ kind: o.kind,
229
+ name: (_c = o.metadata) === null || _c === void 0 ? void 0 : _c.name,
230
+ namespace: (_d = o.metadata) === null || _d === void 0 ? void 0 : _d.namespace
231
+ };
232
+ };
210
233
  exports.tools = {
211
234
  // ── CLUSTER CONFIG ───────────────────────────────────────────────────────
212
235
  list_namespaces: (0, ai_1.tool)({
@@ -694,6 +717,138 @@ exports.tools = {
694
717
  });
695
718
  }
696
719
  }),
720
+ // ── EVENTS (from the cluster events buffer in ctx().clusterEvents) ──────────
721
+ get_cluster_events: (0, ai_1.tool)({
722
+ description: 'Returns recent Kubernetes events buffered for this cluster: kube Events (warnings like crashloops/OOM/failed scheduling) and object lifecycle changes. Optionally filter to warnings only or by namespace.',
723
+ inputSchema: zod_1.z.object({
724
+ warningsOnly: zod_1.z.boolean().optional().describe('Only Warning-type kube Events'),
725
+ namespace: zod_1.z.string().optional().describe('Filter by namespace'),
726
+ limit: zod_1.z.number().optional().describe('Max events to return (default 50)')
727
+ }),
728
+ execute: async ({ warningsOnly, namespace, limit = 50 }) => {
729
+ var _a;
730
+ ctx().trace('get_cluster_events', { warningsOnly: !!warningsOnly, namespace: namespace !== null && namespace !== void 0 ? namespace : '*', limit });
731
+ let evs = (_a = ctx().clusterEvents) !== null && _a !== void 0 ? _a : [];
732
+ if (warningsOnly)
733
+ evs = evs.filter(e => { var _a; return ((_a = e === null || e === void 0 ? void 0 : e.obj) === null || _a === void 0 ? void 0 : _a.kind) === 'Event' && e.obj.type === 'Warning'; });
734
+ if (namespace)
735
+ evs = evs.filter(e => { var _a, _b, _c, _d, _e; return ((_c = (_b = (_a = e === null || e === void 0 ? void 0 : e.obj) === null || _a === void 0 ? void 0 : _a.metadata) === null || _b === void 0 ? void 0 : _b.namespace) !== null && _c !== void 0 ? _c : (_e = (_d = e === null || e === void 0 ? void 0 : e.obj) === null || _d === void 0 ? void 0 : _d.involvedObject) === null || _e === void 0 ? void 0 : _e.namespace) === namespace; });
736
+ return { count: evs.length, events: evs.slice(-limit).map(summarizeClusterEvent) };
737
+ }
738
+ }),
739
+ get_object_events: (0, ai_1.tool)({
740
+ description: 'Returns recent events for a specific Kubernetes object (by namespace and name): its lifecycle changes and related kube Events (via involvedObject).',
741
+ inputSchema: zod_1.z.object({
742
+ namespace: zod_1.z.string().describe('Namespace of the object'),
743
+ name: zod_1.z.string().describe('Name of the object')
744
+ }),
745
+ execute: async ({ namespace, name }) => {
746
+ var _a;
747
+ ctx().trace('get_object_events', { namespace, name });
748
+ const evs = ((_a = ctx().clusterEvents) !== null && _a !== void 0 ? _a : []).filter(e => {
749
+ var _a, _b, _c, _d, _e;
750
+ const o = (_a = e === null || e === void 0 ? void 0 : e.obj) !== null && _a !== void 0 ? _a : {};
751
+ const isObj = ((_b = o.metadata) === null || _b === void 0 ? void 0 : _b.namespace) === namespace && ((_c = o.metadata) === null || _c === void 0 ? void 0 : _c.name) === name;
752
+ const isInvolved = ((_d = o.involvedObject) === null || _d === void 0 ? void 0 : _d.namespace) === namespace && ((_e = o.involvedObject) === null || _e === void 0 ? void 0 : _e.name) === name;
753
+ return isObj || isInvolved;
754
+ });
755
+ return { count: evs.length, events: evs.map(summarizeClusterEvent) };
756
+ }
757
+ }),
758
+ // ── POD DIAGNOSIS ────────────────────────────────────────────────────────
759
+ get_pod_logs: (0, ai_1.tool)({
760
+ description: 'Returns recent container logs for a pod (equivalent to kubectl logs). For a crashing pod (CrashLoopBackOff) pass previous:true to read the CRASHED container instance logs — that is where the root cause usually is (the events only say it is restarting, not why).',
761
+ inputSchema: zod_1.z.object({
762
+ namespace: zod_1.z.string().describe('Namespace of the pod'),
763
+ name: zod_1.z.string().describe('Name of the pod'),
764
+ container: zod_1.z.string().optional().describe('Container name (omit to use the pod default / first container)'),
765
+ previous: zod_1.z.boolean().optional().describe('Read the previous (crashed/restarted) container instance logs — key for CrashLoopBackOff'),
766
+ tailLines: zod_1.z.number().optional().describe('How many trailing lines to return (default 200)')
767
+ }),
768
+ execute: async ({ namespace, name, container, previous, tailLines = 200 }) => {
769
+ var _a, _b;
770
+ ctx().trace('get_pod_logs', { namespace, name, container: container !== null && container !== void 0 ? container : '(default)', previous: !!previous, tailLines });
771
+ try {
772
+ const raw = await ctx().clusterInfo.coreApi.readNamespacedPodLog({ name, namespace, container, previous: !!previous, tailLines });
773
+ const text = typeof raw === 'string' ? raw : ((_a = raw === null || raw === void 0 ? void 0 : raw.body) !== null && _a !== void 0 ? _a : JSON.stringify(raw));
774
+ const truncated = text.length > 15000;
775
+ return { namespace, name, container: container !== null && container !== void 0 ? container : null, previous: !!previous, truncated, logs: truncated ? text.slice(-15000) : text };
776
+ }
777
+ catch (err) {
778
+ return { error: (_b = err.message) !== null && _b !== void 0 ? _b : String(err) };
779
+ }
780
+ }
781
+ }),
782
+ describe_pod: (0, ai_1.tool)({
783
+ description: 'Returns a diagnostic summary of a pod (equivalent to kubectl describe pod): phase, conditions, and per-container status — waiting reason (CrashLoopBackOff/ImagePullBackOff…), last termination reason + exitCode (137=OOMKilled, 1=app error, 143=SIGTERM), restart count, image, resources and probes. Best first step to categorize a pod failure.',
784
+ inputSchema: zod_1.z.object({
785
+ namespace: zod_1.z.string().describe('Namespace of the pod'),
786
+ name: zod_1.z.string().describe('Name of the pod')
787
+ }),
788
+ execute: async ({ namespace, name }) => {
789
+ var _a, _b, _c, _d, _e, _f, _g;
790
+ ctx().trace('describe_pod', { namespace, name });
791
+ try {
792
+ const pod = await ctx().clusterInfo.coreApi.readNamespacedPod({ name, namespace });
793
+ const spec = (_a = pod.spec) !== null && _a !== void 0 ? _a : {}, status = (_b = pod.status) !== null && _b !== void 0 ? _b : {};
794
+ const containerStatus = (cs) => {
795
+ var _a, _b, _c, _d;
796
+ return ({
797
+ name: cs.name, image: cs.image, ready: cs.ready, restartCount: cs.restartCount,
798
+ state: ((_a = cs.state) === null || _a === void 0 ? void 0 : _a.waiting) ? { waiting: { reason: cs.state.waiting.reason, message: cs.state.waiting.message } }
799
+ : ((_b = cs.state) === null || _b === void 0 ? void 0 : _b.terminated) ? { terminated: { reason: cs.state.terminated.reason, exitCode: cs.state.terminated.exitCode } }
800
+ : ((_c = cs.state) === null || _c === void 0 ? void 0 : _c.running) ? { running: { startedAt: cs.state.running.startedAt } } : cs.state,
801
+ lastTerminated: ((_d = cs.lastState) === null || _d === void 0 ? void 0 : _d.terminated) ? { reason: cs.lastState.terminated.reason, exitCode: cs.lastState.terminated.exitCode, signal: cs.lastState.terminated.signal, finishedAt: cs.lastState.terminated.finishedAt } : undefined
802
+ });
803
+ };
804
+ const specContainer = (c) => ({ name: c.name, image: c.image, resources: c.resources, livenessProbe: !!c.livenessProbe, readinessProbe: !!c.readinessProbe, startupProbe: !!c.startupProbe });
805
+ return {
806
+ name, namespace, phase: status.phase, node: spec.nodeName, startTime: status.startTime, reason: status.reason, message: status.message,
807
+ conditions: ((_c = status.conditions) !== null && _c !== void 0 ? _c : []).map((c) => ({ type: c.type, status: c.status, reason: c.reason })),
808
+ containers: ((_d = status.containerStatuses) !== null && _d !== void 0 ? _d : []).map(containerStatus),
809
+ initContainers: ((_e = status.initContainerStatuses) !== null && _e !== void 0 ? _e : []).map(containerStatus),
810
+ spec: { containers: ((_f = spec.containers) !== null && _f !== void 0 ? _f : []).map(specContainer), restartPolicy: spec.restartPolicy }
811
+ };
812
+ }
813
+ catch (err) {
814
+ return { error: (_g = err.message) !== null && _g !== void 0 ? _g : String(err) };
815
+ }
816
+ }
817
+ }),
818
+ get_pod_yaml: (0, ai_1.tool)({
819
+ description: 'Returns the full Kubernetes Pod manifest (equivalent to kubectl get pod -o yaml): complete spec (env, volumes, resources, probes) and status. Use for deeper misconfiguration analysis after describe_pod.',
820
+ inputSchema: zod_1.z.object({
821
+ namespace: zod_1.z.string().describe('Namespace of the pod'),
822
+ name: zod_1.z.string().describe('Name of the pod')
823
+ }),
824
+ execute: async ({ namespace, name }) => {
825
+ var _a;
826
+ ctx().trace('get_pod_yaml', { namespace, name });
827
+ try {
828
+ return await ctx().clusterInfo.coreApi.readNamespacedPod({ name, namespace });
829
+ }
830
+ catch (err) {
831
+ return { error: (_a = err.message) !== null && _a !== void 0 ? _a : String(err) };
832
+ }
833
+ }
834
+ }),
835
+ get_deployment_yaml: (0, ai_1.tool)({
836
+ description: 'Returns the full Kubernetes Deployment manifest (equivalent to kubectl get deployment -o yaml): the pod template (image, env, resources, probes) and strategy. Use to check if a pod problem comes from the owning workload spec.',
837
+ inputSchema: zod_1.z.object({
838
+ namespace: zod_1.z.string().describe('Namespace of the deployment'),
839
+ name: zod_1.z.string().describe('Name of the deployment')
840
+ }),
841
+ execute: async ({ namespace, name }) => {
842
+ var _a;
843
+ ctx().trace('get_deployment_yaml', { namespace, name });
844
+ try {
845
+ return await ctx().clusterInfo.appsApi.readNamespacedDeployment({ name, namespace });
846
+ }
847
+ catch (err) {
848
+ return { error: (_a = err.message) !== null && _a !== void 0 ? _a : String(err) };
849
+ }
850
+ }
851
+ }),
697
852
  };
698
853
  exports.toolInfoList = [
699
854
  { name: 'list_namespaces', effect: EToolEffect.READ, description: 'Lists all namespaces in the cluster with their status and labels.' },
@@ -721,6 +876,12 @@ exports.toolInfoList = [
721
876
  { name: 'times_two', effect: EToolEffect.READ, description: 'Multiplies a number by two.' },
722
877
  { name: 'father_of', effect: EToolEffect.READ, description: 'Returns the name of the father of a person.' },
723
878
  { 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.' },
879
+ { name: 'get_cluster_events', effect: EToolEffect.READ, description: 'Returns recent buffered Kubernetes events for this cluster (warnings + object lifecycle changes); filter by warnings only or namespace.' },
880
+ { name: 'get_object_events', effect: EToolEffect.READ, description: 'Returns recent events for a specific Kubernetes object (namespace + name), including related kube Events.' },
881
+ { name: 'get_pod_logs', effect: EToolEffect.READ, description: 'Returns container logs for a pod (kubectl logs); previous:true reads the crashed instance logs — the root cause of a CrashLoopBackOff.' },
882
+ { name: 'describe_pod', effect: EToolEffect.READ, description: 'Diagnostic summary of a pod (kubectl describe pod): per-container waiting/terminated reason + exitCode (OOMKilled/CrashLoop…), restart count, probes.' },
883
+ { name: 'get_pod_yaml', effect: EToolEffect.READ, description: 'Full Pod manifest (kubectl get pod -o yaml): spec (env, volumes, resources, probes) and status.' },
884
+ { name: 'get_deployment_yaml', effect: EToolEffect.READ, description: 'Full Deployment manifest (kubectl get deployment -o yaml): pod template (image, env, resources, probes) and strategy.' },
724
885
  ];
725
886
  // Resolves the tool names an agent may use: autoTools = full catalog, otherwise its own list
726
887
  // (intersected with the catalog); readOnly filters out WRITE-effect tools. Pure (no LLM) → unit-testable.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kwirthmagnify/kwirth-common-ai",
3
- "version": "0.5.24",
3
+ "version": "0.5.26",
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",