@kwirthmagnify/kwirth-common-ai 0.5.28 → 0.5.30

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
@@ -316,6 +316,30 @@ export declare const tools: {
316
316
  error: any;
317
317
  message?: undefined;
318
318
  }>;
319
+ readonly restart_deployment: import("ai").Tool<{
320
+ namespace: string;
321
+ name: string;
322
+ }, {
323
+ success: boolean;
324
+ message: string;
325
+ error?: undefined;
326
+ } | {
327
+ success: boolean;
328
+ error: any;
329
+ message?: undefined;
330
+ }>;
331
+ readonly delete_pod: import("ai").Tool<{
332
+ namespace: string;
333
+ name: string;
334
+ }, {
335
+ success: boolean;
336
+ message: string;
337
+ error?: undefined;
338
+ } | {
339
+ success: boolean;
340
+ error: any;
341
+ message?: undefined;
342
+ }>;
319
343
  readonly times_two: import("ai").Tool<{
320
344
  data: number;
321
345
  }, number>;
@@ -428,6 +452,71 @@ export declare const tools: {
428
452
  revisionCount?: undefined;
429
453
  revisions?: undefined;
430
454
  }>;
455
+ readonly get_configmap: import("ai").Tool<{
456
+ namespace: string;
457
+ name: string;
458
+ }, {
459
+ name: string;
460
+ namespace: string;
461
+ resourceVersion: any;
462
+ lastModified: string | undefined;
463
+ data: any;
464
+ binaryDataKeys: string[];
465
+ error?: undefined;
466
+ } | {
467
+ error: any;
468
+ name?: undefined;
469
+ namespace?: undefined;
470
+ resourceVersion?: undefined;
471
+ lastModified?: undefined;
472
+ data?: undefined;
473
+ binaryDataKeys?: undefined;
474
+ }>;
475
+ readonly get_secret: import("ai").Tool<{
476
+ namespace: string;
477
+ name: string;
478
+ }, {
479
+ name: string;
480
+ namespace: string;
481
+ type: any;
482
+ resourceVersion: any;
483
+ lastModified: string | undefined;
484
+ keys: string[];
485
+ error?: undefined;
486
+ } | {
487
+ error: any;
488
+ name?: undefined;
489
+ namespace?: undefined;
490
+ type?: undefined;
491
+ resourceVersion?: undefined;
492
+ lastModified?: undefined;
493
+ keys?: undefined;
494
+ }>;
495
+ readonly get_workload_config_refs: import("ai").Tool<{
496
+ namespace: string;
497
+ name: string;
498
+ }, {
499
+ deployment: string;
500
+ namespace: string;
501
+ refs: ({
502
+ resourceVersion: any;
503
+ lastModified: string | undefined;
504
+ kind: string;
505
+ name: string;
506
+ via: string[];
507
+ } | {
508
+ error: any;
509
+ kind: string;
510
+ name: string;
511
+ via: string[];
512
+ })[];
513
+ error?: undefined;
514
+ } | {
515
+ error: any;
516
+ deployment?: undefined;
517
+ namespace?: undefined;
518
+ refs?: undefined;
519
+ }>;
431
520
  readonly get_source_file: import("ai").Tool<{
432
521
  repo: string;
433
522
  ref: string;
package/dist/back.js CHANGED
@@ -261,6 +261,36 @@ const summarizeClusterEvent = (e) => {
261
261
  namespace: (_d = o.metadata) === null || _d === void 0 ? void 0 : _d.namespace
262
262
  };
263
263
  };
264
+ // Best-effort "last modified" of a k8s object: the newest managedFields time (each apply stamps one),
265
+ // falling back to creationTimestamp. k8s keeps no explicit lastModified, so this is the closest signal to
266
+ // "when did this ConfigMap/Secret last change" — used to correlate a config edit with a crash.
267
+ const lastModifiedOf = (meta) => {
268
+ var _a;
269
+ const times = ((_a = meta === null || meta === void 0 ? void 0 : meta.managedFields) !== null && _a !== void 0 ? _a : []).map((f) => f.time).filter(Boolean);
270
+ return times.length ? times.sort()[times.length - 1] : meta === null || meta === void 0 ? void 0 : meta.creationTimestamp;
271
+ };
272
+ // The ConfigMap/Secret references a pod template consumes: envFrom, env.valueFrom, and volumes.
273
+ const configRefsOfPodSpec = (spec) => {
274
+ var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o;
275
+ const refs = [];
276
+ const add = (kind, name, via) => { if (name)
277
+ refs.push({ kind, name, via }); };
278
+ for (const ct of [...((_a = spec === null || spec === void 0 ? void 0 : spec.containers) !== null && _a !== void 0 ? _a : []), ...((_b = spec === null || spec === void 0 ? void 0 : spec.initContainers) !== null && _b !== void 0 ? _b : [])]) {
279
+ for (const ef of (_c = ct.envFrom) !== null && _c !== void 0 ? _c : []) {
280
+ add('ConfigMap', (_d = ef.configMapRef) === null || _d === void 0 ? void 0 : _d.name, `envFrom(${ct.name})`);
281
+ add('Secret', (_e = ef.secretRef) === null || _e === void 0 ? void 0 : _e.name, `envFrom(${ct.name})`);
282
+ }
283
+ for (const e of (_f = ct.env) !== null && _f !== void 0 ? _f : []) {
284
+ add('ConfigMap', (_h = (_g = e.valueFrom) === null || _g === void 0 ? void 0 : _g.configMapKeyRef) === null || _h === void 0 ? void 0 : _h.name, `env ${e.name}`);
285
+ add('Secret', (_k = (_j = e.valueFrom) === null || _j === void 0 ? void 0 : _j.secretKeyRef) === null || _k === void 0 ? void 0 : _k.name, `env ${e.name}`);
286
+ }
287
+ }
288
+ for (const v of (_l = spec === null || spec === void 0 ? void 0 : spec.volumes) !== null && _l !== void 0 ? _l : []) {
289
+ add('ConfigMap', (_m = v.configMap) === null || _m === void 0 ? void 0 : _m.name, `volume ${v.name}`);
290
+ add('Secret', (_o = v.secret) === null || _o === void 0 ? void 0 : _o.secretName, `volume ${v.name}`);
291
+ }
292
+ return refs;
293
+ };
264
294
  exports.tools = {
265
295
  // ── CLUSTER CONFIG ───────────────────────────────────────────────────────
266
296
  list_namespaces: (0, ai_1.tool)({
@@ -708,6 +738,43 @@ exports.tools = {
708
738
  }
709
739
  }
710
740
  }),
741
+ restart_deployment: (0, ai_1.tool)({
742
+ description: 'Rollout-restarts a deployment (equivalent to `kubectl rollout restart`): recreates its pods gracefully, respecting the rolling-update strategy, by stamping the kubectl.kubernetes.io/restartedAt annotation on the pod template. Restarts a workload WITHOUT changing its spec — recover stuck/crashing pods or pick up a changed ConfigMap/Secret. Preferred over delete_pod for a whole workload.',
743
+ inputSchema: zod_1.z.object({ namespace: zod_1.z.string().describe('Namespace of the deployment'), name: zod_1.z.string().describe('Name of the deployment') }),
744
+ execute: async ({ namespace, name }) => {
745
+ var _a, _b, _c, _d, _e;
746
+ ctx().trace('restart_deployment', { namespace, name });
747
+ try {
748
+ const c = ctx().clusterInfo;
749
+ const d = await c.appsApi.readNamespacedDeployment({ name, namespace });
750
+ const restartedAt = new Date().toISOString();
751
+ // Merge (not replace) the existing template annotations, then `add` the whole map: `add` on an
752
+ // existing path replaces it and on a missing path creates it, so it is safe whether or not the
753
+ // pod template already had annotations.
754
+ const annotations = Object.assign(Object.assign({}, ((_d = (_c = (_b = (_a = d.spec) === null || _a === void 0 ? void 0 : _a.template) === null || _b === void 0 ? void 0 : _b.metadata) === null || _c === void 0 ? void 0 : _c.annotations) !== null && _d !== void 0 ? _d : {})), { 'kubectl.kubernetes.io/restartedAt': restartedAt });
755
+ await c.appsApi.patchNamespacedDeployment({ name, namespace, body: [{ op: 'add', path: '/spec/template/metadata/annotations', value: annotations }] });
756
+ return { success: true, message: `Deployment ${namespace}/${name} rollout-restarted at ${restartedAt}` };
757
+ }
758
+ catch (err) {
759
+ return { success: false, error: (_e = err.message) !== null && _e !== void 0 ? _e : String(err) };
760
+ }
761
+ }
762
+ }),
763
+ delete_pod: (0, ai_1.tool)({
764
+ description: 'Deletes a single pod (equivalent to `kubectl delete pod`). Its controller (Deployment/StatefulSet/DaemonSet) recreates it — a surgical way to restart ONE stuck or misbehaving pod. Does not respect a rolling update; for a whole workload prefer restart_deployment.',
765
+ inputSchema: zod_1.z.object({ namespace: zod_1.z.string().describe('Namespace of the pod'), name: zod_1.z.string().describe('Name of the pod') }),
766
+ execute: async ({ namespace, name }) => {
767
+ var _a;
768
+ ctx().trace('delete_pod', { namespace, name });
769
+ try {
770
+ await ctx().clusterInfo.coreApi.deleteNamespacedPod({ name, namespace });
771
+ return { success: true, message: `Pod ${namespace}/${name} deleted; its controller will recreate it` };
772
+ }
773
+ catch (err) {
774
+ return { success: false, error: (_a = err.message) !== null && _a !== void 0 ? _a : String(err) };
775
+ }
776
+ }
777
+ }),
711
778
  // ── MISC ─────────────────────────────────────────────────────────────────
712
779
  times_two: (0, ai_1.tool)({
713
780
  description: 'Multiplies a number by two.',
@@ -906,7 +973,7 @@ exports.tools = {
906
973
  }
907
974
  }),
908
975
  get_rollout_history: (0, ai_1.tool)({
909
- description: 'Returns the rollout history (revisions) of a Deployment via its ReplicaSets: per revision the image(s), replicas and pod-template summary (env names, resources, command). Use to see WHAT CHANGED recently — a new image tag, a changed env/resource/command — that may have broken the pods (the "artifact versions" of the workload). Compare the newest revision against the previous one.',
976
+ description: 'Returns the rollout history (revisions) of a Deployment via its ReplicaSets: per revision the image(s), replicas and pod-template summary (env with inline VALUES and their configMap/secret source, resources, command). Use to see WHAT CHANGED recently — a new image tag, a changed inline env value, a resource/command change — that may have broken the pods. Compare the newest revision against the previous one. NOTE: a change to a ConfigMap/Secret VALUE does NOT create a revision — use get_workload_config_refs for that.',
910
977
  inputSchema: zod_1.z.object({
911
978
  namespace: zod_1.z.string().describe('Namespace of the deployment'),
912
979
  name: zod_1.z.string().describe('Name of the Deployment (the owning workload, e.g. describe_pod.controlledBy.name — NOT the pod name)')
@@ -917,7 +984,16 @@ exports.tools = {
917
984
  try {
918
985
  const rsList = await ctx().clusterInfo.appsApi.listNamespacedReplicaSet({ namespace });
919
986
  const owned = ((_a = rsList.items) !== null && _a !== void 0 ? _a : []).filter((rs) => { var _a, _b; return ((_b = (_a = rs.metadata) === null || _a === void 0 ? void 0 : _a.ownerReferences) !== null && _b !== void 0 ? _b : []).some((o) => o.kind === 'Deployment' && o.name === name); });
920
- const container = (ct) => { var _a; return ({ name: ct.name, image: ct.image, command: ct.command, args: ct.args, resources: ct.resources, env: ((_a = ct.env) !== null && _a !== void 0 ? _a : []).map((e) => e.name) }); };
987
+ // env: inline value + where a valueFrom env is sourced (so the LLM can both diff inline values
988
+ // across revisions AND know which vars come from a ConfigMap/Secret to check separately).
989
+ const envSource = (e) => {
990
+ var _a, _b, _c;
991
+ return ((_a = e.valueFrom) === null || _a === void 0 ? void 0 : _a.configMapKeyRef) ? `configMap:${e.valueFrom.configMapKeyRef.name}/${e.valueFrom.configMapKeyRef.key}`
992
+ : ((_b = e.valueFrom) === null || _b === void 0 ? void 0 : _b.secretKeyRef) ? `secret:${e.valueFrom.secretKeyRef.name}/${e.valueFrom.secretKeyRef.key}`
993
+ : ((_c = e.valueFrom) === null || _c === void 0 ? void 0 : _c.fieldRef) ? `field:${e.valueFrom.fieldRef.fieldPath}`
994
+ : undefined;
995
+ };
996
+ const container = (ct) => { var _a; return ({ name: ct.name, image: ct.image, command: ct.command, args: ct.args, resources: ct.resources, env: ((_a = ct.env) !== null && _a !== void 0 ? _a : []).map((e) => ({ name: e.name, value: e.value, from: envSource(e) })) }); };
921
997
  const revisions = owned.map((rs) => {
922
998
  var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o;
923
999
  const tmpl = (_c = (_b = (_a = rs.spec) === null || _a === void 0 ? void 0 : _a.template) === null || _b === void 0 ? void 0 : _b.spec) !== null && _c !== void 0 ? _c : {};
@@ -939,6 +1015,81 @@ exports.tools = {
939
1015
  }
940
1016
  }
941
1017
  }),
1018
+ get_configmap: (0, ai_1.tool)({
1019
+ description: 'Returns a ConfigMap\'s data (key → value) plus metadata (resourceVersion, lastModified). Use to inspect the ACTUAL config a workload consumes and to check whether it changed recently — a ConfigMap value change (same env var, different value) does NOT create a Deployment revision, so it is invisible to get_rollout_history.',
1020
+ inputSchema: zod_1.z.object({
1021
+ namespace: zod_1.z.string().describe('Namespace of the ConfigMap'),
1022
+ name: zod_1.z.string().describe('Name of the ConfigMap')
1023
+ }),
1024
+ execute: async ({ namespace, name }) => {
1025
+ var _a, _b, _c, _d;
1026
+ ctx().trace('get_configmap', { namespace, name });
1027
+ try {
1028
+ const cm = await ctx().clusterInfo.coreApi.readNamespacedConfigMap({ name, namespace });
1029
+ return { name, namespace, resourceVersion: (_a = cm.metadata) === null || _a === void 0 ? void 0 : _a.resourceVersion, lastModified: lastModifiedOf(cm.metadata), data: (_b = cm.data) !== null && _b !== void 0 ? _b : {}, binaryDataKeys: Object.keys((_c = cm.binaryData) !== null && _c !== void 0 ? _c : {}) };
1030
+ }
1031
+ catch (err) {
1032
+ return { error: (_d = err.message) !== null && _d !== void 0 ? _d : String(err) };
1033
+ }
1034
+ }
1035
+ }),
1036
+ get_secret: (0, ai_1.tool)({
1037
+ description: 'Returns a Secret\'s KEYS, type and metadata (resourceVersion, lastModified) — VALUES ARE REDACTED (never returned). Use to check whether a Secret a workload consumes changed recently (a value change does NOT create a Deployment revision) and which keys it holds. You cannot read the secret values.',
1038
+ inputSchema: zod_1.z.object({
1039
+ namespace: zod_1.z.string().describe('Namespace of the Secret'),
1040
+ name: zod_1.z.string().describe('Name of the Secret')
1041
+ }),
1042
+ execute: async ({ namespace, name }) => {
1043
+ var _a, _b, _c;
1044
+ ctx().trace('get_secret', { namespace, name });
1045
+ try {
1046
+ const s = await ctx().clusterInfo.coreApi.readNamespacedSecret({ name, namespace });
1047
+ return { name, namespace, type: s.type, resourceVersion: (_a = s.metadata) === null || _a === void 0 ? void 0 : _a.resourceVersion, lastModified: lastModifiedOf(s.metadata), keys: Object.keys((_b = s.data) !== null && _b !== void 0 ? _b : {}) }; // values intentionally omitted
1048
+ }
1049
+ catch (err) {
1050
+ return { error: (_c = err.message) !== null && _c !== void 0 ? _c : String(err) };
1051
+ }
1052
+ }
1053
+ }),
1054
+ get_workload_config_refs: (0, ai_1.tool)({
1055
+ description: 'Given a Deployment, lists the ConfigMaps and Secrets its pods consume (via envFrom, env valueFrom, and volumes), each with its lastModified time and resourceVersion. Use on a crash to find a config source that CHANGED WITHOUT A ROLLOUT: editing a ConfigMap/Secret value keeps the same env spec (no new revision) yet can break the pod — compare each ref\'s lastModified against when the pods started crashing, then read the changed one with get_configmap / get_secret.',
1056
+ inputSchema: zod_1.z.object({
1057
+ namespace: zod_1.z.string().describe('Namespace of the deployment'),
1058
+ name: zod_1.z.string().describe('Name of the Deployment (e.g. describe_pod.controlledBy.name)')
1059
+ }),
1060
+ execute: async ({ namespace, name }) => {
1061
+ var _a, _b, _c, _d;
1062
+ ctx().trace('get_workload_config_refs', { namespace, name });
1063
+ try {
1064
+ const c = ctx().clusterInfo;
1065
+ const dep = await c.appsApi.readNamespacedDeployment({ name, namespace });
1066
+ // dedupe by kind+name, merging the reasons (an object may be referenced several ways)
1067
+ const byKey = new Map();
1068
+ for (const r of configRefsOfPodSpec((_b = (_a = dep.spec) === null || _a === void 0 ? void 0 : _a.template) === null || _b === void 0 ? void 0 : _b.spec)) {
1069
+ const cur = (_c = byKey.get(`${r.kind}/${r.name}`)) !== null && _c !== void 0 ? _c : { kind: r.kind, name: r.name, via: [] };
1070
+ if (!cur.via.includes(r.via))
1071
+ cur.via.push(r.via);
1072
+ byKey.set(`${r.kind}/${r.name}`, cur);
1073
+ }
1074
+ const refs = await Promise.all([...byKey.values()].map(async (r) => {
1075
+ var _a;
1076
+ try {
1077
+ const meta = (r.kind === 'ConfigMap'
1078
+ ? await c.coreApi.readNamespacedConfigMap({ name: r.name, namespace })
1079
+ : await c.coreApi.readNamespacedSecret({ name: r.name, namespace })).metadata;
1080
+ return Object.assign(Object.assign({}, r), { resourceVersion: meta === null || meta === void 0 ? void 0 : meta.resourceVersion, lastModified: lastModifiedOf(meta) });
1081
+ }
1082
+ catch (err) {
1083
+ return Object.assign(Object.assign({}, r), { error: (_a = err.message) !== null && _a !== void 0 ? _a : String(err) });
1084
+ }
1085
+ }));
1086
+ return { deployment: name, namespace, refs };
1087
+ }
1088
+ catch (err) {
1089
+ return { error: (_d = err.message) !== null && _d !== void 0 ? _d : String(err) };
1090
+ }
1091
+ }
1092
+ }),
942
1093
  get_source_file: (0, ai_1.tool)({
943
1094
  description: 'Fetches the contents of a single source file from a Git repository (GitHub or GitLab) at a specific ref. Use to inspect the actual source behind a crash: read the stack-trace file:line from the logs, then fetch that file at the image build revision (describe_pod.source). Call repeatedly to follow the trace across files until you find the bug.',
944
1095
  inputSchema: zod_1.z.object({
@@ -987,6 +1138,8 @@ exports.toolInfoList = [
987
1138
  { name: 'start_node', effect: EToolEffect.WRITE, description: 'Starts a previously stopped cluster node and uncordons it. For k3d uses `k3d node start`.' },
988
1139
  { name: 'add_replica', effect: EToolEffect.WRITE, description: 'Scales up a deployment by adding one replica.' },
989
1140
  { name: 'remove_replica', effect: EToolEffect.WRITE, description: 'Scales down a deployment by removing one replica. Minimum of 1 replica is enforced.' },
1141
+ { name: 'restart_deployment', effect: EToolEffect.WRITE, description: 'Rollout-restarts a deployment (recreates its pods gracefully via the restartedAt annotation, respecting the rolling update) — restart a workload without changing its spec.' },
1142
+ { name: 'delete_pod', effect: EToolEffect.WRITE, description: 'Deletes a single pod; its controller recreates it. Surgical restart of one stuck pod (no rolling update — prefer restart_deployment for a whole workload).' },
990
1143
  { name: 'times_two', effect: EToolEffect.READ, description: 'Multiplies a number by two.' },
991
1144
  { name: 'father_of', effect: EToolEffect.READ, description: 'Returns the name of the father of a person.' },
992
1145
  { 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.' },
@@ -996,7 +1149,10 @@ exports.toolInfoList = [
996
1149
  { 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.' },
997
1150
  { name: 'get_pod_yaml', effect: EToolEffect.READ, description: 'Full Pod manifest (kubectl get pod -o yaml): spec (env, volumes, resources, probes) and status.' },
998
1151
  { name: 'get_deployment_yaml', effect: EToolEffect.READ, description: 'Full Deployment manifest (kubectl get deployment -o yaml): pod template (image, env, resources, probes) and strategy.' },
999
- { name: 'get_rollout_history', effect: EToolEffect.READ, description: 'Rollout revisions of a Deployment (via ReplicaSets): image + template per revision, to see what changed (new image/env/resource) that may have broken the pods.' },
1152
+ { name: 'get_rollout_history', effect: EToolEffect.READ, description: 'Rollout revisions of a Deployment (via ReplicaSets): image + template per revision (env with inline values + configMap/secret source), to see what changed (new image/env/resource) that may have broken the pods.' },
1153
+ { name: 'get_configmap', effect: EToolEffect.READ, description: 'A ConfigMap\'s data (key→value) + lastModified. A ConfigMap value change does NOT create a rollout revision, so check it for a crash with no deployment change.' },
1154
+ { name: 'get_secret', effect: EToolEffect.READ, description: 'A Secret\'s keys + type + lastModified (VALUES REDACTED). Check whether a consumed Secret changed recently (no rollout revision is created by a value change).' },
1155
+ { name: 'get_workload_config_refs', effect: EToolEffect.READ, description: 'The ConfigMaps/Secrets a Deployment consumes (envFrom/valueFrom/volumes) with each one\'s lastModified — find a config source that changed WITHOUT a rollout and broke the pods.' },
1000
1156
  { name: 'get_source_file', effect: EToolEffect.READ, description: 'Fetches a file from a Git repo (GitHub/GitLab) at a ref — inspect the source behind a crash by following the stack trace to the offending file:line.' },
1001
1157
  ];
1002
1158
  // Resolves the tool names an agent may use: autoTools = full catalog, otherwise its own list
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kwirthmagnify/kwirth-common-ai",
3
- "version": "0.5.28",
3
+ "version": "0.5.30",
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",