@blogic-cz/agent-tools 0.12.1 → 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.12.1",
+  "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/observability-tool/trace.ts

@@ -1,7 +1,8 @@
-import { Console, Effect } from "effect";
+import { Console, Effect, type Option } from "effect";
 import { Argument, Command, Flag } from "effect/unstable/cli";
 
 import { formatOption, formatOutput } from "#shared";
+import type { OutputFormat } from "#shared";
 
 import { ObservabilityToolError } from "./errors";
 import {
@@ -14,14 +15,31 @@ import {
 } from "./shared";
 import type {
   FlattenedSpan,
+  ObservabilityEnvConfig,
   OtlpAnyValue,
   OtlpAttribute,
+  ParsedId,
+  SearchWindow,
+  SpanResolution,
+  TempoSearchResponse,
   TempoTraceResponse,
   TraceSummary,
 } from "./types";
 
-function isHexTraceId(value: string): boolean {
-  return /^[\da-f]{32}$/i.test(value);
+const SPAN_SEARCH_WINDOWS: SearchWindow[] = [
+  { start: "now-1h", end: "now" },
+  { start: "now-24h", end: "now" },
+];
+
+function parseId(value: string): ParsedId | undefined {
+  const trimmed = value.trim().toLowerCase();
+  if (/^[\da-f]{32}$/.test(trimmed)) {
+    return { rawId: value, normalizedId: trimmed, kind: "trace_id" };
+  }
+  if (/^[\da-f]{16}$/.test(trimmed)) {
+    return { rawId: value, normalizedId: trimmed, kind: "span_id" };
+  }
+  return undefined;
 }
 
 function getStringAttribute(
@@ -111,6 +129,16 @@ function computeDurationMs(start?: string, end?: string): number | undefined {
   return Number(endNano - startNano) / 1_000_000;
 }
 
+function relativeToEpoch(value: string, nowEpoch: number): number {
+  const match = /^now-(\d+)([smhd])$/.exec(value.trim());
+  if (!match) return nowEpoch;
+
+  const amount = Number(match[1]);
+  const unit = match[2];
+  const multipliers: Record<string, number> = { s: 1, m: 60, h: 3600, d: 86400 };
+  return nowEpoch - amount * (multipliers[unit] ?? 1);
+}
+
 function isErrorStatus(code?: string | number): boolean {
   if (code === undefined) return false;
   if (typeof code === "number") return code === 2;
@@ -205,72 +233,207 @@ function parseLabel(value: string | Record<string, string>): Record<string, stri
   }
 }
 
-const getCommand = Command.make(
-  "get",
-  {
-    traceId: Argument.string("traceId"),
-    format: formatOption,
-    env: envOption,
-    profile: profileOption,
-  },
-  ({ traceId, format, env, profile }) => {
-    const startedAt = Date.now();
+type ResolvedTrace = {
+  readonly resolution: SpanResolution;
+  readonly spans: FlattenedSpan[];
+};
+
+function searchTempoBySpanId(
+  config: ObservabilityEnvConfig,
+  spanId: string,
+  window: SearchWindow,
+): Effect.Effect<TempoSearchResponse, ObservabilityToolError> {
+  const now = Math.floor(Date.now() / 1000);
+  const startEpoch = relativeToEpoch(window.start, now);
+  const endEpoch = relativeToEpoch(window.end, now);
+  const traceql = encodeURIComponent(`{ span:id = "${spanId}" }`);
+  const searchUrl =
+    `/api/datasources/proxy/uid/${config.tempoUid}/api/search` +
+    `?q=${traceql}&start=${startEpoch}&end=${endEpoch}&limit=5`;
+
+  return observabilityFetch<TempoSearchResponse>(config, searchUrl);
+}
 
-    return Effect.gen(function* () {
-      if (!isHexTraceId(traceId)) {
+function fetchFullTrace(
+  config: ObservabilityEnvConfig,
+  traceId: string,
+): Effect.Effect<FlattenedSpan[], ObservabilityToolError> {
+  return Effect.gen(function* () {
+    const raw = yield* observabilityFetch<TempoTraceResponse>(
+      config,
+      `/api/datasources/proxy/uid/${config.tempoUid}/api/traces/${traceId}`,
+    );
+    return flattenTrace(raw);
+  });
+}
+
+function resolveTraceFromId(
+  config: ObservabilityEnvConfig,
+  parsed: ParsedId,
+  explicitWindows?: { start: string; end: string },
+): Effect.Effect<ResolvedTrace, ObservabilityToolError> {
+  return Effect.gen(function* () {
+    if (parsed.kind === "trace_id") {
+      const spans = yield* fetchFullTrace(config, parsed.normalizedId);
+      if (spans.length === 0) {
         return yield* new ObservabilityToolError({
-          cause: new Error("trace get requires a 32-character hex trace ID"),
+          cause: new Error(`Trace ${parsed.normalizedId} returned zero spans`),
         });
       }
+      return {
+        resolution: {
+          via: "direct_trace_id" as const,
+          resolvedTraceId: parsed.normalizedId,
+        },
+        spans,
+      };
+    }
 
-      const config = yield* resolveConfig(env, profile);
-      const raw = yield* observabilityFetch<TempoTraceResponse>(
-        config,
-        `/api/datasources/proxy/uid/${config.tempoUid}/api/traces/${traceId.toLowerCase()}`,
-      );
-      const spans = flattenTrace(raw);
+    const windows = explicitWindows
+      ? [{ start: explicitWindows.start, end: explicitWindows.end }]
+      : SPAN_SEARCH_WINDOWS;
 
-      if (spans.length === 0) {
+    const attemptedWindows: SearchWindow[] = [];
+    let usedWindow: SearchWindow | undefined;
+    let uniqueTraceIds: string[] = [];
+
+    for (const window of windows) {
+      attemptedWindows.push(window);
+      const searchResult = yield* searchTempoBySpanId(config, parsed.normalizedId, window);
+      const traces = searchResult.traces ?? [];
+
+      if (traces.length === 0) continue;
+
+      const candidateTraceIds = traces
+        .map((trace) => trace.traceID?.toLowerCase())
+        .filter((id): id is string => id !== undefined);
+
+      uniqueTraceIds = [...new Set(candidateTraceIds)];
+
+      if (uniqueTraceIds.length > 1) {
         return yield* new ObservabilityToolError({
-          cause: new Error(`Trace ${traceId} returned zero spans`),
+          cause: {
+            message: `Ambiguous span ID ${parsed.normalizedId} — found in ${uniqueTraceIds.length} traces`,
+            code: "AMBIGUOUS_SPAN_ID",
+            retryable: true,
+            details: { candidateTraceIds: uniqueTraceIds },
+          },
         });
       }
 
-      const result = {
-        success: true,
-        message: `Resolved trace ${traceId.toLowerCase()} with ${spans.length} span(s)`,
-        data: {
-          environment: env,
-          grafanaUrl: config.url,
-          tempoDatasourceUid: config.tempoUid,
-          summary: summarizeTrace(traceId.toLowerCase(), spans),
-          spans,
+      usedWindow = window;
+      break;
+    }
+
+    if (uniqueTraceIds.length === 0 || !usedWindow) {
+      const windowDesc = attemptedWindows
+        .map((window) => `${window.start} → ${window.end}`)
+        .join(", ");
+      return yield* new ObservabilityToolError({
+        cause: new Error(
+          `No trace found containing span ${parsed.normalizedId} (searched windows: ${windowDesc})`,
+        ),
+      });
+    }
+
+    const traceId = uniqueTraceIds[0];
+    const spans = yield* fetchFullTrace(config, traceId);
+
+    if (spans.length === 0) {
+      return yield* new ObservabilityToolError({
+        cause: new Error(`Trace ${traceId} returned zero spans`),
+      });
+    }
+
+    const focusSpan = spans.find((span) => span.spanId === parsed.normalizedId);
+
+    return {
+      resolution: {
+        via: "span_search" as const,
+        resolvedTraceId: traceId,
+        searchedSpanId: parsed.normalizedId,
+        focusSpan,
+        attemptedWindows,
+        usedWindow,
+      },
+      spans,
+    };
+  });
+}
+
+function handleTraceGet(
+  id: string,
+  format: OutputFormat,
+  env: string,
+  profile: Option.Option<string>,
+) {
+  const startedAt = Date.now();
+
+  return Effect.gen(function* () {
+    const parsed = parseId(id);
+    if (!parsed) {
+      return yield* new ObservabilityToolError({
+        cause: {
+          message: `Invalid ID format: expected 32-char trace ID or 16-char span ID, got ${id.length} characters`,
+          code: "INVALID_ID_FORMAT",
+          retryable: false,
         },
-        executionTimeMs: Date.now() - startedAt,
-      };
+      });
+    }
 
-      yield* Console.log(formatOutput(result, format));
-    }).pipe(
-      Effect.catch((error) =>
-        Effect.gen(function* () {
-          const result = {
-            success: false,
-            message: "Failed to resolve trace from Tempo",
-            error: formatObservabilityError(error),
-            hint: "Check trace ID format and Grafana/Tempo connectivity",
-            executionTimeMs: Date.now() - startedAt,
-          };
-          yield* Console.log(formatOutput(result, format));
-        }),
-      ),
-    );
+    const config = yield* resolveConfig(env, profile);
+    const { resolution, spans } = yield* resolveTraceFromId(config, parsed);
+
+    const result = {
+      success: true,
+      message:
+        parsed.kind === "span_id"
+          ? `Found trace ${resolution.resolvedTraceId} via span ${parsed.normalizedId} with ${spans.length} span(s)`
+          : `Resolved trace ${resolution.resolvedTraceId} with ${spans.length} span(s)`,
+      data: {
+        environment: env,
+        grafanaUrl: config.url,
+        tempoDatasourceUid: config.tempoUid,
+        input: parsed,
+        resolution,
+        summary: summarizeTrace(resolution.resolvedTraceId, spans),
+        spans,
+      },
+      executionTimeMs: Date.now() - startedAt,
+    };
+
+    yield* Console.log(formatOutput(result, format));
+  }).pipe(
+    Effect.catch((error) =>
+      Effect.gen(function* () {
+        const result = {
+          success: false,
+          message: "Failed to resolve trace from Tempo",
+          error: formatObservabilityError(error),
+          hint: "Accepts 32-char trace ID or 16-char span ID. Check format and Grafana/Tempo connectivity",
+          executionTimeMs: Date.now() - startedAt,
+        };
+        yield* Console.log(formatOutput(result, format));
+      }),
+    ),
+  );
+}
+
+const getCommand = Command.make(
+  "get",
+  {
+    id: Argument.string("id"),
+    format: formatOption,
+    env: envOption,
+    profile: profileOption,
   },
-).pipe(Command.withDescription("Resolve a trace by ID via Grafana/Tempo"));
+  ({ id, format, env, profile }) => handleTraceGet(id, format, env, profile),
+).pipe(Command.withDescription("Resolve a trace by trace ID or span ID via Grafana/Tempo"));
 
 const logsCommand = Command.make(
   "logs",
   {
-    traceId: Argument.string("traceId"),
+    id: Argument.string("id"),
     format: formatOption,
     env: envOption,
     profile: profileOption,
@@ -287,19 +450,26 @@ const logsCommand = Command.make(
       Flag.withDefault("now"),
     ),
   },
-  ({ traceId, format, env, profile, limit, start, end }) => {
+  ({ id, format, env, profile, limit, start, end }) => {
     const startedAt = Date.now();
 
     return Effect.gen(function* () {
-      if (!isHexTraceId(traceId)) {
+      const parsed = parseId(id);
+      if (!parsed) {
         return yield* new ObservabilityToolError({
-          cause: new Error("trace logs requires a 32-character hex trace ID"),
+          cause: {
+            message: `Invalid ID format: expected 32-char trace ID or 16-char span ID, got ${id.length} characters`,
+            code: "INVALID_ID_FORMAT",
+            retryable: false,
+          },
         });
       }
 
       const config = yield* resolveConfig(env, profile);
-      const normalizedTraceId = traceId.toLowerCase();
-      const logql = `{job=~".+"} |= "${normalizedTraceId}"`;
+      const { resolution } = yield* resolveTraceFromId(config, parsed, { start, end });
+      const resolvedTraceId = resolution.resolvedTraceId;
+
+      const logql = `{job=~".+"} |= "${resolvedTraceId}"`;
       const response = yield* observabilityDsQuery(config, config.lokiUid, "loki", logql, {
         from: start,
         to: end,
@@ -343,11 +513,16 @@ const logsCommand = Command.make(
 
       const result = {
         success: true,
-        message: `Found ${logs.length} log line(s) mentioning trace ${normalizedTraceId}`,
+        message:
+          parsed.kind === "span_id"
+            ? `Found ${logs.length} log line(s) for trace ${resolvedTraceId} (resolved from span ${parsed.normalizedId})`
+            : `Found ${logs.length} log line(s) mentioning trace ${resolvedTraceId}`,
         data: {
           environment: env,
           grafanaUrl: config.url,
           lokiDatasourceUid: config.lokiUid,
+          input: parsed,
+          resolution,
           query: logql,
           logCount: logs.length,
           logs: logs.toSorted((left, right) => right.timestamp.localeCompare(left.timestamp)),
@@ -363,7 +538,7 @@ const logsCommand = Command.make(
             success: false,
             message: "Failed to execute trace log lookup",
             error: formatObservabilityError(error),
-            hint: "Check trace ID format and Grafana/Loki connectivity",
+            hint: "Accepts 32-char trace ID or 16-char span ID. Check format and Grafana/Loki connectivity",
             executionTimeMs: Date.now() - startedAt,
           };
           yield* Console.log(formatOutput(result, format));
@@ -371,9 +546,20 @@ const logsCommand = Command.make(
       ),
     );
   },
-).pipe(Command.withDescription("Find Loki logs mentioning a trace ID"));
+).pipe(Command.withDescription("Find Loki logs mentioning a trace (accepts trace ID or span ID)"));
+
+const findCommand = Command.make(
+  "find",
+  {
+    id: Argument.string("id"),
+    format: formatOption,
+    env: envOption,
+    profile: profileOption,
+  },
+  ({ id, format, env, profile }) => handleTraceGet(id, format, env, profile),
+).pipe(Command.withDescription("Alias for 'trace get' — resolve a trace by trace ID or span ID"));
 
 export const traceCommand = Command.make("trace", {}).pipe(
   Command.withDescription("Tempo trace operations"),
-  Command.withSubcommands([getCommand, logsCommand]),
+  Command.withSubcommands([getCommand, logsCommand, findCommand]),
 );

package/src/observability-tool/types.ts

@@ -1,3 +1,5 @@
+import { Schema } from "effect";
+
 export type ObservabilityEnvConfig = {
   url: string;
   token?: string;
@@ -89,6 +91,52 @@ export type TraceSummary = {
   readonly endedAtUnixNano?: string;
 };
 
+export type TempoSearchResponse = {
+  readonly traces?: ReadonlyArray<{
+    readonly traceID?: string;
+    readonly rootServiceName?: string;
+    readonly rootTraceName?: string;
+    readonly startTimeUnixNano?: string;
+    readonly durationMs?: number;
+    readonly spanSets?: ReadonlyArray<{
+      readonly spans?: ReadonlyArray<{
+        readonly spanID?: string;
+        readonly startTimeUnixNano?: string;
+        readonly durationNanos?: string;
+        readonly attributes?: ReadonlyArray<OtlpAttribute>;
+      }>;
+      readonly matched?: number;
+    }>;
+  }>;
+  readonly metrics?: Record<string, unknown>;
+};
+
+export const IdKind = Schema.Literals(["trace_id", "span_id"]);
+export type IdKind = typeof IdKind.Type;
+
+export const ResolutionVia = Schema.Literals(["direct_trace_id", "span_search"]);
+export type ResolutionVia = typeof ResolutionVia.Type;
+
+export type ParsedId = {
+  readonly rawId: string;
+  readonly normalizedId: string;
+  readonly kind: IdKind;
+};
+
+export type SearchWindow = {
+  readonly start: string;
+  readonly end: string;
+};
+
+export type SpanResolution = {
+  readonly via: ResolutionVia;
+  readonly resolvedTraceId: string;
+  readonly searchedSpanId?: string;
+  readonly focusSpan?: FlattenedSpan;
+  readonly attemptedWindows?: ReadonlyArray<SearchWindow>;
+  readonly usedWindow?: SearchWindow;
+};
+
 export type DsQueryOpts = {
   instant?: boolean;
   from?: string;

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.";
+}