@blogic-cz/agent-tools 0.13.0 → 0.14.0

package/README.md

@@ -173,10 +173,20 @@ bun run agent-tools/example-tool/index.ts ping
     retentionDays: 90,
     dbPath: "~/.agent-tools/audit.sqlite",
   },
+  vpns: {
+    blogic: {
+      // auto defaults to true:
+      // darwin -> macos-scutil, linux -> linux-nmcli, win32 -> windows-rasdial
+      name: "BLVPN",
+    },
+  },
   kubernetes: {
     default: {
       clusterId: "your-cluster-id",
       namespaces: { test: "your-ns-test", prod: "your-ns-prod" },
+      prerequisites: [{ type: "vpn", key: "blogic" }],
+      // Prerequisites are currently decoded and validated as config metadata;
+      // automatic VPN connect/disconnect execution is planned for a follow-up release.
     },
   },
   logs: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blogic-cz/agent-tools",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "CLI tools for AI coding agent workflows — GitHub, database, Kubernetes, Azure DevOps, logs, sessions, and audit",
   "keywords": [
     "agent",

package/schemas/agent-tools.schema.json

@@ -72,6 +72,13 @@
       "additionalProperties": {
         "$ref": "#/definitions/GitHubRepoConfig"
       }
+    },
+    "vpns": {
+      "description": "Named VPN definitions referenced by profile prerequisites.",
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/definitions/VpnConfig"
+      }
     }
   },
   "definitions": {
@@ -81,8 +88,14 @@
       "additionalProperties": false,
       "required": ["owner", "repo"],
       "properties": {
-        "owner": { "type": "string", "description": "GitHub organization or user name." },
-        "repo": { "type": "string", "description": "Repository name." }
+        "owner": {
+          "type": "string",
+          "description": "GitHub organization or user name."
+        },
+        "repo": {
+          "type": "string",
+          "description": "Repository name."
+        }
       }
     },
     "AzureConfig": {
@@ -125,6 +138,17 @@
         "timeoutMs": {
           "description": "Optional command timeout in milliseconds.",
           "type": "number"
+        },
+        "prerequisites": {
+          "description": "Ordered prerequisite references required before remote tool execution.",
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/Prerequisite"
+          }
+        },
+        "vpn": {
+          "type": "string",
+          "description": "Convenience sugar for a VPN prerequisite key. Runtime normalizes this to prerequisites."
         }
       },
       "required": ["clusterId", "namespaces"]
@@ -251,6 +275,21 @@
         "remotePath": {
           "description": "Remote logs path used in container or host environments.",
           "type": "string"
+        },
+        "prerequisites": {
+          "description": "Ordered prerequisite references required before remote tool execution.",
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/Prerequisite"
+          }
+        },
+        "vpn": {
+          "type": "string",
+          "description": "Convenience sugar for a VPN prerequisite key. Runtime normalizes this to prerequisites."
+        },
+        "kubernetesProfile": {
+          "type": "string",
+          "description": "Kubernetes profile used for remote logs."
         }
       },
       "required": ["localDir", "remotePath"]
@@ -336,6 +375,138 @@
           }
         }
       }
+    },
+    "VpnPrerequisite": {
+      "description": "VPN prerequisite reference used by tool profiles.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "const": "vpn",
+          "description": "Prerequisite type."
+        },
+        "key": {
+          "type": "string",
+          "description": "Key from the top-level vpns registry."
+        },
+        "cleanup": {
+          "description": "VPN cleanup policy.",
+          "type": "string",
+          "enum": ["leave-running", "stop-if-started"]
+        }
+      },
+      "required": ["type", "key"]
+    },
+    "Prerequisite": {
+      "oneOf": [
+        {
+          "$ref": "#/definitions/VpnPrerequisite"
+        }
+      ]
+    },
+    "MacosScutilVpnDriverConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "const": "macos-scutil"
+        },
+        "serviceName": {
+          "type": "string"
+        }
+      },
+      "required": ["type"]
+    },
+    "LinuxNmcliVpnDriverConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "const": "linux-nmcli"
+        },
+        "connectionName": {
+          "type": "string"
+        }
+      },
+      "required": ["type"]
+    },
+    "WindowsRasdialVpnDriverConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "const": "windows-rasdial"
+        },
+        "entryName": {
+          "type": "string"
+        }
+      },
+      "required": ["type"]
+    },
+    "VpnDriverConfig": {
+      "oneOf": [
+        {
+          "$ref": "#/definitions/MacosScutilVpnDriverConfig"
+        },
+        {
+          "$ref": "#/definitions/LinuxNmcliVpnDriverConfig"
+        },
+        {
+          "$ref": "#/definitions/WindowsRasdialVpnDriverConfig"
+        }
+      ]
+    },
+    "VpnConfig": {
+      "description": "VPN configuration. auto defaults to true and maps name to a deterministic OS-specific driver.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "VPN connection/service name used by auto driver mapping."
+        },
+        "auto": {
+          "type": "boolean",
+          "default": true,
+          "description": "Defaults to true. Maps by process.platform without heuristic discovery."
+        },
+        "defaultCleanup": {
+          "description": "VPN cleanup policy.",
+          "type": "string",
+          "enum": ["leave-running", "stop-if-started"]
+        },
+        "connectTimeoutMs": {
+          "type": "number"
+        },
+        "disconnectTimeoutMs": {
+          "type": "number"
+        },
+        "cooldownMs": {
+          "type": "number"
+        },
+        "leaseTtlMs": {
+          "type": "number"
+        },
+        "drivers": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "darwin": {
+              "$ref": "#/definitions/MacosScutilVpnDriverConfig"
+            },
+            "linux": {
+              "$ref": "#/definitions/LinuxNmcliVpnDriverConfig"
+            },
+            "win32": {
+              "$ref": "#/definitions/WindowsRasdialVpnDriverConfig"
+            }
+          }
+        },
+        "driver": {
+          "$ref": "#/definitions/VpnDriverConfig"
+        }
+      },
+      "required": ["name"]
     }
   },
   "examples": [

package/src/config/loader.ts

@@ -16,6 +16,56 @@ const CredentialGuardConfigSchema = Schema.Struct({
   additionalDangerousBashPatterns: Schema.optionalKey(Schema.Array(Schema.String)),
 });
 
+const CleanupPolicySchema = Schema.Literals(["leave-running", "stop-if-started"]);
+
+const VpnPrerequisiteSchema = Schema.Struct({
+  type: Schema.Literal("vpn"),
+  key: Schema.String,
+  cleanup: Schema.optionalKey(CleanupPolicySchema),
+});
+
+const PrerequisiteSchema = VpnPrerequisiteSchema;
+const PrerequisitesSchema = Schema.Array(PrerequisiteSchema);
+
+const MacosScutilVpnDriverConfigSchema = Schema.Struct({
+  type: Schema.Literal("macos-scutil"),
+  serviceName: Schema.optionalKey(Schema.String),
+});
+
+const LinuxNmcliVpnDriverConfigSchema = Schema.Struct({
+  type: Schema.Literal("linux-nmcli"),
+  connectionName: Schema.optionalKey(Schema.String),
+});
+
+const WindowsRasdialVpnDriverConfigSchema = Schema.Struct({
+  type: Schema.Literal("windows-rasdial"),
+  entryName: Schema.optionalKey(Schema.String),
+});
+
+const VpnDriverConfigSchema = Schema.Union([
+  MacosScutilVpnDriverConfigSchema,
+  LinuxNmcliVpnDriverConfigSchema,
+  WindowsRasdialVpnDriverConfigSchema,
+]);
+
+const VpnConfigSchema = Schema.Struct({
+  name: Schema.String,
+  auto: Schema.optionalKey(Schema.Boolean),
+  defaultCleanup: Schema.optionalKey(CleanupPolicySchema),
+  connectTimeoutMs: Schema.optionalKey(Schema.Number),
+  disconnectTimeoutMs: Schema.optionalKey(Schema.Number),
+  cooldownMs: Schema.optionalKey(Schema.Number),
+  leaseTtlMs: Schema.optionalKey(Schema.Number),
+  drivers: Schema.optionalKey(
+    Schema.Struct({
+      darwin: Schema.optionalKey(MacosScutilVpnDriverConfigSchema),
+      linux: Schema.optionalKey(LinuxNmcliVpnDriverConfigSchema),
+      win32: Schema.optionalKey(WindowsRasdialVpnDriverConfigSchema),
+    }),
+  ),
+  driver: Schema.optionalKey(VpnDriverConfigSchema),
+});
+
 const AzureConfigSchema = Schema.Struct({
   organization: Schema.String,
   defaultProject: Schema.String,
@@ -26,6 +76,8 @@ const K8sConfigSchema = Schema.Struct({
   clusterId: Schema.String,
   namespaces: Schema.Record(Schema.String, Schema.String),
   timeoutMs: Schema.optionalKey(Schema.Number),
+  prerequisites: Schema.optionalKey(PrerequisitesSchema),
+  vpn: Schema.optionalKey(Schema.String),
 });
 
 const DbEnvConfigSchema = Schema.Struct({
@@ -52,6 +104,9 @@ const DatabaseConfigSchema = Schema.Struct({
 const LogsConfigSchema = Schema.Struct({
   localDir: Schema.String,
   remotePath: Schema.String,
+  kubernetesProfile: Schema.optionalKey(Schema.String),
+  prerequisites: Schema.optionalKey(PrerequisitesSchema),
+  vpn: Schema.optionalKey(Schema.String),
 });
 
 const ObservabilityEnvTargetSchema = Schema.Struct({
@@ -78,6 +133,7 @@ const GitHubRepoConfigSchema = Schema.Struct({
 const KNOWN_TOP_LEVEL_KEYS = new Set([
   "$schema",
   "azure",
+  "vpns",
   "kubernetes",
   "database",
   "observability",
@@ -92,6 +148,7 @@ const KNOWN_TOP_LEVEL_KEYS = new Set([
 const AgentToolsConfigSchema = Schema.Struct({
   $schema: Schema.optionalKey(Schema.String),
   azure: Schema.optionalKey(Schema.Record(Schema.String, AzureConfigSchema)),
+  vpns: Schema.optionalKey(Schema.Record(Schema.String, VpnConfigSchema)),
   kubernetes: Schema.optionalKey(Schema.Record(Schema.String, K8sConfigSchema)),
   database: Schema.optionalKey(Schema.Record(Schema.String, DatabaseConfigSchema)),
   observability: Schema.optionalKey(Schema.Record(Schema.String, ObservabilityConfigSchema)),

package/src/config/types.ts

@@ -5,8 +5,60 @@ export type AzureConfig = {
   timeoutMs?: number;
 };
 
+export type CleanupPolicy = "leave-running" | "stop-if-started";
+
+export type VpnPrerequisite = {
+  type: "vpn";
+  key: string;
+  cleanup?: CleanupPolicy;
+};
+
+export type MacosScutilVpnDriverConfig = {
+  type: "macos-scutil";
+  serviceName?: string;
+};
+
+export type LinuxNmcliVpnDriverConfig = {
+  type: "linux-nmcli";
+  connectionName?: string;
+};
+
+export type WindowsRasdialVpnDriverConfig = {
+  type: "windows-rasdial";
+  entryName?: string;
+};
+
+export type VpnDriverConfig =
+  | MacosScutilVpnDriverConfig
+  | LinuxNmcliVpnDriverConfig
+  | WindowsRasdialVpnDriverConfig;
+
+export type VpnConfig = {
+  name: string;
+  /** Defaults to true. Auto maps name to the current OS driver deterministically. */
+  auto?: boolean;
+  defaultCleanup?: CleanupPolicy;
+  connectTimeoutMs?: number;
+  disconnectTimeoutMs?: number;
+  cooldownMs?: number;
+  leaseTtlMs?: number;
+  drivers?: {
+    darwin?: MacosScutilVpnDriverConfig;
+    linux?: LinuxNmcliVpnDriverConfig;
+    win32?: WindowsRasdialVpnDriverConfig;
+  };
+  /** Explicit current-platform driver, required when auto is false and no per-OS driver is available. */
+  driver?: VpnDriverConfig;
+};
+
+export type ProfilePrerequisites = {
+  prerequisites?: readonly VpnPrerequisite[];
+  /** Convenience input sugar; normalize to prerequisites before execution. */
+  vpn?: string;
+};
+
 /** Kubernetes cluster profile configuration */
-export type K8sConfig = {
+export type K8sConfig = ProfilePrerequisites & {
   clusterId: string;
   /** Named namespaces, e.g. { test: "my-app-test", prod: "my-app-prod" } */
   namespaces: Record<string, string>;
@@ -38,9 +90,10 @@ export type DatabaseConfig = {
 };
 
 /** Logs profile configuration */
-export type LogsConfig = {
+export type LogsConfig = ProfilePrerequisites & {
   localDir: string;
   remotePath: string;
+  kubernetesProfile?: string;
 };
 
 /** Single observability environment connection details */
@@ -93,6 +146,8 @@ export type AgentToolsConfig = {
   $schema?: string;
   /** Named Azure DevOps profiles. e.g. { default: { organization: "...", defaultProject: "..." } } */
   azure?: Record<string, AzureConfig>;
+  /** Named VPN definitions referenced by profile prerequisites. */
+  vpns?: Record<string, VpnConfig>;
   /** Named Kubernetes cluster profiles. e.g. { default: {...}, staging: {...} } */
   kubernetes?: Record<string, K8sConfig>;
   /** Named database profiles. e.g. { default: {...}, analytics: {...} } */

package/src/k8s-tool/index.ts

@@ -82,7 +82,7 @@ const executeK8sCommand = (command: string, options: CommonK8sCommandOptions) =>
     const resolvedEnv = yield* resolveEnv(options.env, config);
 
     const k8sService = yield* K8sService;
-    const result = yield* k8sService.runKubectl(command, options.dryRun).pipe(
+    const result = yield* k8sService.runKubectl(command, options.dryRun, profileName).pipe(
       Effect.catchTags({
         K8sContextError: (error) => {
           const errorResult: CommandResult = {

package/src/k8s-tool/service.ts

@@ -19,6 +19,7 @@ export class K8sService extends Context.Service<
     readonly runCommand: (
       cmd: string,
       env: Environment,
+      profile?: string,
     ) => Effect.Effect<
       string,
       K8sContextError | K8sCommandError | K8sTimeoutError | K8sDangerousCommandError
@@ -26,6 +27,7 @@ export class K8sService extends Context.Service<
     readonly runKubectl: (
       cmd: string,
       dryRun: boolean,
+      profile?: string,
     ) => Effect.Effect<
       CommandResult,
       K8sContextError | K8sCommandError | K8sTimeoutError | K8sDangerousCommandError
@@ -39,24 +41,27 @@ export class K8sService extends Context.Service<
         const executor = yield* ChildProcessSpawner.ChildProcessSpawner;
 
         const config = yield* ConfigService;
-        const k8sConfig = getToolConfig<K8sConfig>(config, "kubernetes");
 
-        if (!k8sConfig) {
-          const noConfigError = new K8sContextError({
-            message:
-              "No Kubernetes configuration found. Add a 'kubernetes' section to agent-tools.json5.",
-            clusterId: "unknown",
-          });
-          return {
-            runCommand: (_cmd: string, _env: Environment) => Effect.fail(noConfigError),
-            runKubectl: (_cmd: string, _dryRun: boolean) => Effect.fail(noConfigError),
-          };
-        }
+        const getK8sConfig = (profile?: string) =>
+          getToolConfig<K8sConfig>(config, "kubernetes", profile);
+
+        const requireK8sConfig = (profile?: string) =>
+          Effect.gen(function* () {
+            const k8sConfig = getK8sConfig(profile);
+            if (!k8sConfig) {
+              return yield* new K8sContextError({
+                message: profile
+                  ? `No Kubernetes configuration found for profile: ${profile}.`
+                  : "No Kubernetes configuration found. Add a 'kubernetes' section to agent-tools.json5.",
+                clusterId: profile ?? "unknown",
+              });
+            }
 
-        const KUBECTL_TIMEOUT_MS = k8sConfig.timeoutMs ?? 60000;
+            return k8sConfig;
+          });
 
-        // Create Ref for context caching (replaces module-level let)
-        const contextRef = yield* Ref.make<string | null>(null);
+        // Cache context by selected profile/cluster instead of a single default profile.
+        const contextRef = yield* Ref.make<Record<string, string>>({});
 
         // Helper that uses executor.spawn() to avoid ChildProcessSpawner requirement in return type
         const runShellCommand = (commandStr: string, timeoutMs: number) =>
@@ -97,22 +102,27 @@ export class K8sService extends Context.Service<
             ),
           );
 
-        const resolveContext = Effect.fn("K8sService.resolveContext")(function* () {
-          // Check cache first
+        const resolveContext = Effect.fn("K8sService.resolveContext")(function* (
+          profile: string | undefined,
+          k8sConfig: K8sConfig,
+        ) {
+          const timeoutMs = k8sConfig.timeoutMs ?? 60000;
+          const cacheKey = profile ?? `cluster:${k8sConfig.clusterId}`;
           const cached = yield* Ref.get(contextRef);
-          if (cached !== null) {
-            return cached;
+          const cachedContext = cached[cacheKey];
+          if (cachedContext !== undefined) {
+            return cachedContext;
           }
 
           const jqCommand = `kubectl config view -o json | jq -r '.contexts[] | select(.context.cluster == "${k8sConfig.clusterId}") | .name' | head -1`;
 
-          const contextResultOption = yield* runShellCommand(jqCommand, KUBECTL_TIMEOUT_MS);
+          const contextResultOption = yield* runShellCommand(jqCommand, timeoutMs);
 
           if (Option.isNone(contextResultOption)) {
             return yield* new K8sTimeoutError({
-              message: `Context resolution timed out after ${KUBECTL_TIMEOUT_MS}ms`,
+              message: `Context resolution timed out after ${timeoutMs}ms`,
               command: jqCommand,
-              timeoutMs: KUBECTL_TIMEOUT_MS,
+              timeoutMs,
             });
           }
 
@@ -120,19 +130,22 @@ export class K8sService extends Context.Service<
 
           if (contextResult.exitCode === 0 && contextResult.stdout.trim()) {
             const resolvedContextValue = contextResult.stdout.trim();
-            yield* Ref.set(contextRef, resolvedContextValue);
+            yield* Ref.update(contextRef, (contexts) => ({
+              ...contexts,
+              [cacheKey]: resolvedContextValue,
+            }));
             return resolvedContextValue;
           }
 
           const fallbackCommand = `kubectl config view -o json | jq -r '.contexts[] as $ctx | .clusters[] | select(.name == $ctx.context.cluster and (.cluster.server | contains("${k8sConfig.clusterId}"))) | $ctx.name' | head -1`;
 
-          const fallbackResultOption = yield* runShellCommand(fallbackCommand, KUBECTL_TIMEOUT_MS);
+          const fallbackResultOption = yield* runShellCommand(fallbackCommand, timeoutMs);
 
           if (Option.isNone(fallbackResultOption)) {
             return yield* new K8sTimeoutError({
-              message: `Context resolution timed out after ${KUBECTL_TIMEOUT_MS}ms`,
+              message: `Context resolution timed out after ${timeoutMs}ms`,
               command: fallbackCommand,
-              timeoutMs: KUBECTL_TIMEOUT_MS,
+              timeoutMs,
             });
           }
 
@@ -140,7 +153,10 @@ export class K8sService extends Context.Service<
 
           if (fallbackResult.exitCode === 0 && fallbackResult.stdout.trim()) {
             const resolvedContextValue = fallbackResult.stdout.trim();
-            yield* Ref.set(contextRef, resolvedContextValue);
+            yield* Ref.update(contextRef, (contexts) => ({
+              ...contexts,
+              [cacheKey]: resolvedContextValue,
+            }));
             return resolvedContextValue;
           }
 
@@ -150,17 +166,22 @@ export class K8sService extends Context.Service<
           });
         });
 
-        const executeCommand = Effect.fn("K8sService.executeCommand")(function* (cmd: string) {
-          const context = yield* resolveContext();
+        const executeCommand = Effect.fn("K8sService.executeCommand")(function* (
+          cmd: string,
+          profile?: string,
+        ) {
+          const k8sConfig = yield* requireK8sConfig(profile);
+          const timeoutMs = k8sConfig.timeoutMs ?? 60000;
+          const context = yield* resolveContext(profile, k8sConfig);
           const fullCommand = `kubectl --context ${context} ${cmd}`;
 
-          const resultOption = yield* runShellCommand(fullCommand, KUBECTL_TIMEOUT_MS);
+          const resultOption = yield* runShellCommand(fullCommand, timeoutMs);
 
           if (Option.isNone(resultOption)) {
             return yield* new K8sTimeoutError({
-              message: `Command timed out after ${KUBECTL_TIMEOUT_MS}ms`,
+              message: `Command timed out after ${timeoutMs}ms`,
               command: fullCommand,
-              timeoutMs: KUBECTL_TIMEOUT_MS,
+              timeoutMs,
             });
           }
 
@@ -177,6 +198,7 @@ export class K8sService extends Context.Service<
         const runCommand = Effect.fn("K8sService.runCommand")(function* (
           cmd: string,
           _env: Environment,
+          profile?: string,
         ) {
           // Security: block dangerous commands before execution
           const securityCheck = isKubectlCommandAllowed(cmd);
@@ -189,7 +211,7 @@ export class K8sService extends Context.Service<
             });
           }
 
-          const result = yield* executeCommand(cmd);
+          const result = yield* executeCommand(cmd, profile);
           if (result.exitCode !== 0) {
             return yield* new K8sCommandError({
               message: result.stderr ?? `kubectl exited with code ${result.exitCode}`,
@@ -205,6 +227,7 @@ export class K8sService extends Context.Service<
         const runKubectl = Effect.fn("K8sService.runKubectl")(function* (
           cmd: string,
           dryRun: boolean,
+          profile?: string,
         ) {
           // Security: block dangerous commands before execution (even dry-run)
           const securityCheck = isKubectlCommandAllowed(cmd);
@@ -219,7 +242,8 @@ export class K8sService extends Context.Service<
 
           const startTime = Date.now();
           if (dryRun) {
-            const context = yield* resolveContext();
+            const k8sConfig = yield* requireK8sConfig(profile);
+            const context = yield* resolveContext(profile, k8sConfig);
             const fullCommand = `kubectl --context ${context} ${cmd}`;
             return {
               success: true,
@@ -229,7 +253,7 @@ export class K8sService extends Context.Service<
             };
           }
 
-          const result = yield* executeCommand(cmd);
+          const result = yield* executeCommand(cmd, profile);
 
           if (result.exitCode !== 0) {
             return yield* new K8sCommandError({

package/src/logs-tool/service.ts

@@ -125,11 +125,13 @@ export class LogsService extends Context.Service<
         logsConfig: LogsConfig,
       ) {
         const remotePath = logsConfig.remotePath;
+        const kubernetesProfile = logsConfig.kubernetesProfile;
 
         const podResult = yield* k8s
           .runKubectl(
             `get pods --field-selector=status.phase=Running -o jsonpath='{.items[0].metadata.name}'`,
             false,
+            kubernetesProfile,
           )
           .pipe(
             Effect.mapError(
@@ -143,15 +145,17 @@ export class LogsService extends Context.Service<
 
         const pod = readCommandOutput(podResult.output).replace(/'/g, "");
 
-        const listResult = yield* k8s.runKubectl(`exec ${pod} -- ls -la ${remotePath}`, false).pipe(
-          Effect.mapError(
-            (error) =>
-              new LogsReadError({
-                message: error instanceof Error ? error.message : "Failed to list remote logs",
-                source: `${pod}:${remotePath}`,
-              }),
-          ),
-        );
+        const listResult = yield* k8s
+          .runKubectl(`exec ${pod} -- ls -la ${remotePath}`, false, kubernetesProfile)
+          .pipe(
+            Effect.mapError(
+              (error) =>
+                new LogsReadError({
+                  message: error instanceof Error ? error.message : "Failed to list remote logs",
+                  source: `${pod}:${remotePath}`,
+                }),
+            ),
+          );
 
         const files = parseLogFiles(readCommandOutput(listResult.output));
         if (files.length === 0) {
@@ -226,11 +230,13 @@ export class LogsService extends Context.Service<
         logsConfig: LogsConfig,
       ) {
         const remotePath = logsConfig.remotePath;
+        const kubernetesProfile = logsConfig.kubernetesProfile;
 
         const podResult = yield* k8s
           .runKubectl(
             `get pods --field-selector=status.phase=Running -o jsonpath='{.items[0].metadata.name}'`,
             false,
+            kubernetesProfile,
           )
           .pipe(
             Effect.mapError(
@@ -252,7 +258,7 @@ export class LogsService extends Context.Service<
         }
 
         const execResult = yield* k8s
-          .runKubectl(`exec ${pod} -- sh -c "${command}"`, false)
+          .runKubectl(`exec ${pod} -- sh -c "${command}"`, false, kubernetesProfile)
           .pipe(Effect.result);
 
         return yield* Result.match(execResult, {

package/src/shared/prerequisites/config.ts

@@ -0,0 +1,38 @@
+import type { AgentToolsConfig, VpnPrerequisite, ProfilePrerequisites } from "#config/types";
+import type { PrerequisiteResolution } from "#shared/prerequisites/types";
+
+export function normalizeProfilePrerequisites(
+  profile: ProfilePrerequisites,
+): readonly VpnPrerequisite[] {
+  const prerequisites = [...(profile.prerequisites ?? [])];
+
+  if (
+    profile.vpn &&
+    !prerequisites.some(
+      (prerequisite) => prerequisite.type === "vpn" && prerequisite.key === profile.vpn,
+    )
+  ) {
+    prerequisites.push({ type: "vpn", key: profile.vpn });
+  }
+
+  return prerequisites;
+}
+
+export function resolveProfilePrerequisites(
+  config: AgentToolsConfig,
+  profile: ProfilePrerequisites,
+): PrerequisiteResolution {
+  const prerequisites = normalizeProfilePrerequisites(profile);
+
+  for (const prerequisite of prerequisites) {
+    if (prerequisite.type === "vpn" && !config.vpns?.[prerequisite.key]) {
+      return {
+        success: false,
+        error: `VPN prerequisite "${prerequisite.key}" is not defined.`,
+        hint: `Add vpns.${prerequisite.key} to agent-tools.json5 or remove the prerequisite.`,
+      };
+    }
+  }
+
+  return { success: true, prerequisites };
+}

package/src/shared/prerequisites/types.ts

@@ -0,0 +1,21 @@
+import type {
+  LinuxNmcliVpnDriverConfig,
+  MacosScutilVpnDriverConfig,
+  VpnPrerequisite,
+  WindowsRasdialVpnDriverConfig,
+} from "#config/types";
+
+export type PrerequisiteResolution =
+  | { success: true; prerequisites: readonly VpnPrerequisite[] }
+  | { success: false; error: string; hint: string };
+
+export type SupportedPlatform = "darwin" | "linux" | "win32";
+
+export type ResolvedVpnDriver =
+  | (Required<MacosScutilVpnDriverConfig> & { platform: "darwin" })
+  | (Required<LinuxNmcliVpnDriverConfig> & { platform: "linux" })
+  | (Required<WindowsRasdialVpnDriverConfig> & { platform: "win32" });
+
+export type VpnDriverResolution =
+  | { success: true; driver: ResolvedVpnDriver }
+  | { success: false; error: string; hint: string };

package/src/shared/prerequisites/vpn.ts

@@ -0,0 +1,119 @@
+import type { VpnConfig, VpnDriverConfig } from "#config/types";
+import type {
+  ResolvedVpnDriver,
+  SupportedPlatform,
+  VpnDriverResolution,
+} from "#shared/prerequisites/types";
+
+const isSupportedPlatform = (platform: typeof process.platform): platform is SupportedPlatform =>
+  platform === "darwin" || platform === "linux" || platform === "win32";
+
+const resolveExplicitDriver = (
+  config: VpnConfig,
+  platform: SupportedPlatform,
+  driver: VpnDriverConfig,
+): VpnDriverResolution => {
+  if (driver.type === "macos-scutil") {
+    if (platform !== "darwin") {
+      return {
+        success: false,
+        error: `VPN driver "${driver.type}" is not supported on ${platform}.`,
+        hint: "Configure a driver for the current OS or enable auto detection.",
+      };
+    }
+
+    return {
+      success: true,
+      driver: { platform, type: driver.type, serviceName: driver.serviceName ?? config.name },
+    };
+  }
+
+  if (driver.type === "linux-nmcli") {
+    if (platform !== "linux") {
+      return {
+        success: false,
+        error: `VPN driver "${driver.type}" is not supported on ${platform}.`,
+        hint: "Configure a driver for the current OS or enable auto detection.",
+      };
+    }
+
+    return {
+      success: true,
+      driver: { platform, type: driver.type, connectionName: driver.connectionName ?? config.name },
+    };
+  }
+
+  if (driver.type === "windows-rasdial") {
+    if (platform !== "win32") {
+      return {
+        success: false,
+        error: `VPN driver "${driver.type}" is not supported on ${platform}.`,
+        hint: "Configure a driver for the current OS or enable auto detection.",
+      };
+    }
+
+    return {
+      success: true,
+      driver: { platform, type: driver.type, entryName: driver.entryName ?? config.name },
+    };
+  }
+
+  const exhaustive: never = driver;
+  return exhaustive;
+};
+
+export function resolveVpnDriverConfig(
+  config: VpnConfig,
+  platform: typeof process.platform = process.platform,
+): VpnDriverResolution {
+  if (!isSupportedPlatform(platform)) {
+    return {
+      success: false,
+      error: `VPN auto detection is not supported on ${platform}.`,
+      hint: "Configure an explicit supported VPN driver for this platform.",
+    };
+  }
+
+  const platformDriver = config.drivers?.[platform];
+  if (platformDriver) {
+    return resolveExplicitDriver(config, platform, platformDriver);
+  }
+
+  if (config.driver) {
+    return resolveExplicitDriver(config, platform, config.driver);
+  }
+
+  const auto = config.auto ?? true;
+  if (!auto) {
+    return {
+      success: false,
+      error: "VPN auto detection is disabled, but no driver is configured for this platform.",
+      hint: `Add vpns.<key>.drivers.${platform} or enable auto detection.`,
+    };
+  }
+
+  if (platform === "darwin") {
+    return { success: true, driver: { platform, type: "macos-scutil", serviceName: config.name } };
+  }
+
+  if (platform === "linux") {
+    return {
+      success: true,
+      driver: { platform, type: "linux-nmcli", connectionName: config.name },
+    };
+  }
+
+  return { success: true, driver: { platform, type: "windows-rasdial", entryName: config.name } };
+}
+
+export function missingVpnToolHint(driver: ResolvedVpnDriver): string {
+  if (driver.type === "macos-scutil") {
+    return "scutil was not found or is unavailable. Ensure macOS system tools are available and the VPN service name matches the Network service name.";
+  }
+
+  if (driver.type === "linux-nmcli") {
+    return "nmcli was not found. Install or enable NetworkManager CLI, or configure an explicit supported VPN driver.";
+  }
+
+  return "rasdial was not found or is unavailable. Ensure Windows RAS tooling is available and the VPN entry name matches the configured connection.";
+}