@blogic-cz/agent-tools 0.14.38 → 0.14.40

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blogic-cz/agent-tools",
-  "version": "0.14.38",
+  "version": "0.14.40",
   "description": "CLI tools for AI coding agent workflows — GitHub, database, Kubernetes, Azure DevOps, logs, sessions, and audit",
   "keywords": [
     "agent",
@@ -112,6 +112,10 @@
     "./audit": {
       "types": "./dist/shared/audit.d.ts",
       "default": "./src/shared/audit.ts"
+    },
+    "./k8s-probe": {
+      "types": "./dist/shared/k8s-probe.d.ts",
+      "default": "./src/shared/k8s-probe.ts"
     }
   },
   "publishConfig": {

package/src/config/loader.ts

@@ -80,6 +80,7 @@ const K8sConfigSchema = Schema.Struct({
   clusterId: Schema.String,
   namespaces: Schema.Record(Schema.String, Schema.String),
   timeoutMs: Schema.optionalKey(Schema.Number),
+  apiProbeTimeoutMs: Schema.optionalKey(Schema.Number),
   prerequisites: Schema.optionalKey(PrerequisitesSchema),
   vpn: Schema.optionalKey(Schema.String),
 });

package/src/config/types.ts

@@ -71,6 +71,13 @@ export type K8sConfig = ProfilePrerequisites & {
   /** Named namespaces, e.g. { test: "my-app-test", prod: "my-app-prod" } */
   namespaces: Record<string, string>;
   timeoutMs?: number;
+  /**
+   * Timeout in milliseconds for the cheap Kubernetes API-server reachability probe run
+   * before each command. When the cluster API is unreachable (VPN down / off the office
+   * network, or the API degraded) a real kubectl command hangs until `timeoutMs`; the
+   * probe lets it fail fast with a clear message instead. Set to 0 to disable. Defaults to 2000.
+   */
+  apiProbeTimeoutMs?: number;
 };
 
 /** Single database environment connection details */

package/src/db-tool/service.ts

@@ -8,6 +8,7 @@ import { isPrerequisiteRunError } from "#shared/prerequisites/errors";
 import { resolveEnvTemplate } from "#shared/env-template";
 import { resolveEnvironmentScopedPrerequisites } from "#shared/prerequisites/config";
 import { runWithProfilePrerequisites } from "#shared/prerequisites/runtime";
+import { buildApiProbeArgs } from "#shared/k8s-probe";
 import { DbConfigService, DbConfigServiceLayer, TUNNEL_CHECK_INTERVAL_MS } from "./config-service";
 import {
   DbConnectionError,
@@ -51,26 +52,8 @@ export function resolveDbAccessMode(
   };
 }
 
-/**
- * Build the kubectl args for the lightweight API-server reachability probe.
- * Hitting `/version` via `--raw` is the cheapest authenticated round-trip; `--request-timeout`
- * bounds it so an unreachable server (VPN down, off the office network) fails fast instead of
- * letting a subsequent `kubectl port-forward` hang on a silent TCP connect.
- */
-export function buildApiProbeArgs(
-  kubeconfig: string | undefined,
-  context: string,
-  timeoutMs: number,
-): string[] {
-  return [
-    ...(kubeconfig ? ["--kubeconfig", kubeconfig] : []),
-    "--context",
-    context,
-    "get",
-    "--raw=/version",
-    `--request-timeout=${timeoutMs}ms`,
-  ];
-}
+// Re-exported from the shared probe so existing `#db/service` consumers keep working.
+export { buildApiProbeArgs } from "#shared/k8s-probe";
 
 export class DbService extends Context.Service<
   DbService,

package/src/k8s-tool/service.ts

@@ -15,6 +15,7 @@ import { collectProcessOutput, quoteShellArg } from "#shared/exec";
 import { resolveEnvTemplate } from "#shared/env-template";
 import { isPrerequisiteRunError } from "#shared/prerequisites/errors";
 import { runWithProfilePrerequisites } from "#shared/prerequisites/runtime";
+import { buildApiProbeArgs } from "#shared/k8s-probe";
 import { isKubectlCommandAllowed } from "./security";
 
 export class K8sService extends Context.Service<
@@ -146,6 +147,40 @@ export class K8sService extends Context.Service<
             ),
           );
 
+        /**
+         * Cheap pre-flight: is the cluster API reachable right now? Returns true when the probe
+         * is disabled (apiProbeTimeoutMs <= 0) so behaviour is unchanged unless a probe can run.
+         * A false result lets the command fail fast instead of hanging until the full timeoutMs.
+         */
+        const probeApiReachable = (
+          context: string,
+          kubeconfig: string | undefined,
+          timeoutMs: number,
+        ) =>
+          Effect.gen(function* () {
+            if (timeoutMs <= 0) {
+              return true;
+            }
+
+            const probe = ChildProcess.make(
+              "kubectl",
+              buildApiProbeArgs(kubeconfig, context, timeoutMs),
+              {
+                stdout: "pipe",
+                stderr: "pipe",
+              },
+            );
+
+            const result = yield* Effect.scoped(
+              Effect.gen(function* () {
+                const process = yield* executor.spawn(probe);
+                return yield* collectProcessOutput(process);
+              }),
+            ).pipe(Effect.catch(() => Effect.succeed({ stdout: "", stderr: "", exitCode: 1 })));
+
+            return result.exitCode === 0;
+          });
+
         const resolveContext = Effect.fn("K8sService.resolveContext")(function* (
           profile: string | undefined,
           k8sConfig: K8sConfig,
@@ -223,12 +258,23 @@ export class K8sService extends Context.Service<
         ) {
           const k8sConfig = yield* requireK8sConfig(profile);
           const timeoutMs = k8sConfig.timeoutMs ?? 60000;
+          const apiProbeTimeoutMs = k8sConfig.apiProbeTimeoutMs ?? 2000;
           return yield* runWithProfilePrerequisites(
             config ?? {},
             k8sConfig,
             runPrerequisiteCommand,
             Effect.gen(function* () {
               const { context, kubeconfig } = yield* resolveContext(profile, k8sConfig);
+
+              const reachable = yield* probeApiReachable(context, kubeconfig, apiProbeTimeoutMs);
+              if (!reachable) {
+                return yield* new K8sContextError({
+                  message: `Kubernetes API server (${k8sConfig.clusterId}) not reachable within ${apiProbeTimeoutMs}ms. VPN likely not connected, or the cluster API is degraded.`,
+                  clusterId: k8sConfig.clusterId,
+                  hint: "Check the VPN connection and cluster health, then retry. Set kubernetes.apiProbeTimeoutMs to 0 in agent-tools.json5 to disable this pre-flight probe.",
+                });
+              }
+
               const fullCommand = withKubeconfig(`kubectl --context ${context} ${cmd}`, kubeconfig);
 
               const resultOption = yield* runShellCommand(fullCommand, timeoutMs);

package/src/shared/k8s-probe.ts

@@ -0,0 +1,23 @@
+/**
+ * Shared kubectl API-server reachability probe, used by every VPN-gated tool
+ * (db-tool, k8s-tool) to fail fast instead of hanging on a silently unreachable cluster.
+ *
+ * Hitting `/version` via `--raw` is the cheapest authenticated round-trip; `--request-timeout`
+ * bounds it so an unreachable server (VPN down / off the office network, or the cluster API
+ * degraded) fails in ~`timeoutMs` with a clear message instead of waiting out the tool's full
+ * command/tunnel timeout.
+ */
+export function buildApiProbeArgs(
+  kubeconfig: string | undefined,
+  context: string,
+  timeoutMs: number,
+): string[] {
+  return [
+    ...(kubeconfig ? ["--kubeconfig", kubeconfig] : []),
+    "--context",
+    context,
+    "get",
+    "--raw=/version",
+    `--request-timeout=${timeoutMs}ms`,
+  ];
+}