@blogic-cz/agent-tools 0.14.62 → 0.15.1

package/README.md

@@ -178,6 +178,10 @@ bun run agent-tools/example-tool/index.ts ping
       // auto defaults to true:
       // darwin -> macos-scutil, linux -> linux-nmcli, win32 -> windows-rasdial
       name: "ExampleVPN",
+      // Reuse package-managed connections for 30 seconds after the last command. Set 0 for immediate cleanup.
+      idleDisconnectMs: 30000,
+      // Total window for stop plus disconnected-status confirmation.
+      disconnectTimeoutMs: 10000,
       // Optional: pass IPSec shared secret to macOS scutil from env without storing the value in config.
       secretEnvVar: "EXAMPLE_VPN_IPSEC_SHARED_SECRET",
     },
@@ -187,8 +191,7 @@ bun run agent-tools/example-tool/index.ts ping
       clusterId: "your-cluster-id",
       namespaces: { test: "your-ns-test", prod: "your-ns-prod" },
       prerequisites: [{ type: "vpn", key: "exampleVpn" }],
-      // Prerequisites are currently decoded and validated as config metadata;
-      // automatic VPN connect/disconnect execution is planned for a follow-up release.
+      // agent-tools starts disconnected VPNs, shares package-local leases, and disconnects only connections it owns.
     },
   },
   logs: {
@@ -420,7 +423,7 @@ Secrets are **never** stored in the config file. The `db-tool` config references
 }
 ```
 
-Database VPN prerequisites can be set at the database profile or environment level. If an environment declares `vpn` or `prerequisites`, that environment config replaces the profile prerequisites; `prerequisites: []` explicitly disables inherited VPN setup. DB commands try the query directly first and only connect VPN prerequisites if direct access fails.
+Database VPN prerequisites can be set at the database profile or environment level. If an environment declares `vpn` or `prerequisites`, that environment config replaces the profile prerequisites; `prerequisites: []` explicitly disables inherited VPN setup. DB commands try the query directly first and only connect VPN prerequisites if direct access fails. Package-managed VPNs remain reusable for `idleDisconnectMs` (default 30000) after the last lease; `0` restores immediate cleanup. Preconnected or `leave-running` connections are treated as external and never stopped automatically. If runtime state is corrupt, unknown, or contains legacy artifacts, first stop all agent-tools processes using the VPN, then remove that VPN state directory under `~/.agent-tools/runtime/vpn-prerequisites`.
 
 ```json5
 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blogic-cz/agent-tools",
-  "version": "0.14.62",
+  "version": "0.15.1",
   "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

@@ -558,16 +558,25 @@
           "enum": ["leave-running", "stop-if-started"]
         },
         "connectTimeoutMs": {
-          "type": "number"
+          "type": "number",
+          "minimum": 0,
+          "maximum": 2147483647,
+          "multipleOf": 1
         },
         "disconnectTimeoutMs": {
-          "type": "number"
-        },
-        "cooldownMs": {
-          "type": "number"
-        },
-        "leaseTtlMs": {
-          "type": "number"
+          "type": "number",
+          "minimum": 0,
+          "maximum": 2147483647,
+          "multipleOf": 1,
+          "description": "Total bounded stop-and-confirm window in milliseconds."
+        },
+        "idleDisconnectMs": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 2147483647,
+          "multipleOf": 1,
+          "default": 30000,
+          "description": "Managed VPN reuse window after the last lease. Set to 0 for immediate cleanup."
         },
         "secretEnvVar": {
           "type": "string",

package/src/config/loader.ts

@@ -18,6 +18,20 @@ const CredentialGuardConfigSchema = Schema.Struct({
 });
 
 const CleanupPolicySchema = Schema.Literals(["leave-running", "stop-if-started"]);
+const VPN_TIMER_FIELDS = ["connectTimeoutMs", "disconnectTimeoutMs", "idleDisconnectMs"] as const;
+const MAX_TIMER_MS = 2_147_483_647;
+
+function validateVpnTimer(key: string, field: (typeof VPN_TIMER_FIELDS)[number], value: unknown) {
+  if (
+    typeof value !== "number" ||
+    !Number.isFinite(value) ||
+    !Number.isInteger(value) ||
+    value < 0 ||
+    value > MAX_TIMER_MS
+  ) {
+    throw new Error(`VPN "${key}" ${field} must be an integer from 0 to ${MAX_TIMER_MS}.`);
+  }
+}
 
 const VpnPrerequisiteSchema = Schema.Struct({
   type: Schema.Literal("vpn"),
@@ -56,8 +70,7 @@ const VpnConfigSchema = Schema.Struct({
   defaultCleanup: Schema.optionalKey(CleanupPolicySchema),
   connectTimeoutMs: Schema.optionalKey(Schema.Number),
   disconnectTimeoutMs: Schema.optionalKey(Schema.Number),
-  cooldownMs: Schema.optionalKey(Schema.Number),
-  leaseTtlMs: Schema.optionalKey(Schema.Number),
+  idleDisconnectMs: Schema.optionalKey(Schema.Number),
   secretEnvVar: Schema.optionalKey(Schema.String),
   drivers: Schema.optionalKey(
     Schema.Struct({
@@ -215,8 +228,29 @@ export function decodeConfig(
   const sanitized = stripUnknownTopLevelKeys(parsed);
 
   try {
-    const decoded = Schema.decodeUnknownSync(AgentToolsConfigSchema)(sanitized);
-    return decoded as AgentToolsConfig;
+    if (isRecord(sanitized) && isRecord(sanitized.vpns)) {
+      for (const [key, value] of Object.entries(sanitized.vpns)) {
+        if (!isRecord(value)) continue;
+        if ("cooldownMs" in value || "leaseTtlMs" in value) {
+          throw new Error(`VPN "${key}" uses removed cooldownMs or leaseTtlMs configuration.`);
+        }
+        for (const field of VPN_TIMER_FIELDS) {
+          if (value[field] !== undefined) validateVpnTimer(key, field, value[field]);
+        }
+      }
+    }
+    const decoded = Schema.decodeUnknownSync(AgentToolsConfigSchema)(sanitized) as AgentToolsConfig;
+    return decoded.vpns
+      ? {
+          ...decoded,
+          vpns: Object.fromEntries(
+            Object.entries(decoded.vpns).map(([key, vpn]) => [
+              key,
+              { idleDisconnectMs: 30_000, ...vpn },
+            ]),
+          ),
+        }
+      : decoded;
   } catch (error) {
     throw new Error(
       `Invalid agent-tools config at ${configPath}: ${

package/src/config/types.ts

@@ -43,9 +43,10 @@ export type VpnConfig = {
   auto?: boolean;
   defaultCleanup?: CleanupPolicy;
   connectTimeoutMs?: number;
+  /** Total bounded stop-and-confirm window in milliseconds. */
   disconnectTimeoutMs?: number;
-  cooldownMs?: number;
-  leaseTtlMs?: number;
+  /** Managed VPN reuse window after the last lease. Defaults to 30000; 0 disconnects immediately. */
+  idleDisconnectMs?: number;
   /** Name of environment variable holding the VPN shared secret for supported drivers. */
   secretEnvVar?: string;
   drivers?: {

package/src/shared/prerequisites/driver-commands.ts

@@ -0,0 +1,88 @@
+import { ChildProcess } from "effect/unstable/process";
+
+import type { ResolvedVpnDriver } from "#shared/prerequisites/types";
+import type { SanitizedVpnDriver } from "#shared/prerequisites/store";
+
+export type VpnDriverAction = "status" | "start" | "stop";
+export type VpnCommandSpec = { readonly executable: string; readonly args: readonly string[] };
+
+export const sanitizeVpnDriver = (driver: ResolvedVpnDriver): SanitizedVpnDriver => {
+  if (driver.type === "macos-scutil") {
+    return { type: driver.type, platform: driver.platform, serviceName: driver.serviceName };
+  }
+  if (driver.type === "linux-nmcli") {
+    return { type: driver.type, platform: driver.platform, connectionName: driver.connectionName };
+  }
+  return { type: driver.type, platform: driver.platform, entryName: driver.entryName };
+};
+
+export const vpnCommandSpec = (
+  driver: SanitizedVpnDriver,
+  action: VpnDriverAction,
+): VpnCommandSpec => {
+  if (driver.type === "macos-scutil") {
+    return {
+      executable: "scutil",
+      args:
+        action === "status"
+          ? ["--nc", "status", driver.serviceName]
+          : ["--nc", action, driver.serviceName],
+    };
+  }
+  if (driver.type === "linux-nmcli") {
+    return {
+      executable: "nmcli",
+      args:
+        action === "status"
+          ? ["-t", "-e", "no", "-f", "NAME", "connection", "show", "--active"]
+          : ["connection", action === "start" ? "up" : "down", driver.connectionName],
+    };
+  }
+  return {
+    executable: "rasdial",
+    args:
+      action === "status"
+        ? []
+        : action === "start"
+          ? [driver.entryName]
+          : [driver.entryName, "/disconnect"],
+  };
+};
+
+export const makeParentVpnCommand = (
+  driver: ResolvedVpnDriver,
+  action: VpnDriverAction,
+  secret?: string,
+) => {
+  const spec = vpnCommandSpec(sanitizeVpnDriver(driver), action);
+  const secretArgs = action === "start" && secret ? ["--secret", secret] : [];
+  const args = [...spec.args, ...secretArgs];
+  const labelArgs = [...spec.args, ...(secretArgs.length > 0 ? ["--secret", "<redacted>"] : [])];
+  return {
+    command: ChildProcess.make(spec.executable, args, { stdout: "pipe", stderr: "pipe" }),
+    label: [spec.executable, ...labelArgs].join(" "),
+  };
+};
+
+export const parseVpnStatus = (
+  driver: SanitizedVpnDriver,
+  result: { readonly stdout: string; readonly exitCode: number },
+): boolean | undefined => {
+  if (result.exitCode !== 0) return undefined;
+  const lines = result.stdout.split(/\r?\n/);
+  if (driver.type === "macos-scutil") {
+    if (lines.includes("Connected")) return true;
+    if (lines.includes("Disconnected")) return false;
+    return undefined;
+  }
+  if (driver.type === "linux-nmcli") {
+    return lines.some((line) => line === driver.connectionName);
+  }
+  const records = lines.map((line) => line.trim()).filter((line) => line.length > 0);
+  const successFooter = "Command completed successfully.";
+  if (records.at(-1) !== successFooter) return undefined;
+  const body = records.slice(0, -1);
+  if (body.length === 1 && body[0] === "No connections") return false;
+  if (body[0] !== "Connected to" || body.length === 1) return undefined;
+  return body.slice(1).includes(driver.entryName);
+};

package/src/shared/prerequisites/guardian-entry.ts

@@ -0,0 +1,49 @@
+import type {
+  GuardianInboundMessage,
+  GuardianOutboundMessage,
+} from "#shared/prerequisites/guardian";
+import { runGuardian } from "#shared/prerequisites/guardian";
+
+let release: (() => Promise<void>) | undefined;
+let initialized = false;
+let initializedLeaseId: string | undefined;
+let requestedLeaseId: string | undefined;
+let disconnected = false;
+let releaseStarted = false;
+
+const send = (message: GuardianOutboundMessage) => process.send?.(message);
+const fail = (error: unknown) => {
+  send({ type: "ERROR", message: error instanceof Error ? error.message : String(error) });
+  process.exitCode = 1;
+};
+const releaseIfRequested = () => {
+  if (releaseStarted || !release || (!disconnected && requestedLeaseId !== initializedLeaseId)) {
+    return;
+  }
+  releaseStarted = true;
+  void release().catch(fail);
+};
+
+process.on("message", (message: GuardianInboundMessage) => {
+  if (message.type === "INIT" && !initialized) {
+    initialized = true;
+    initializedLeaseId = message.leaseId;
+    void runGuardian(message, send)
+      .then((guardian) => {
+        release = guardian.release;
+        send({ type: "READY", leaseId: message.leaseId, guardianId: message.guardianId });
+        return releaseIfRequested();
+      })
+      .catch(fail);
+    return;
+  }
+  if (message.type === "RELEASE") {
+    requestedLeaseId = message.leaseId;
+    releaseIfRequested();
+  }
+});
+
+process.on("disconnect", () => {
+  disconnected = true;
+  releaseIfRequested();
+});

package/src/shared/prerequisites/guardian.ts

@@ -0,0 +1,157 @@
+import type { SanitizedVpnDriver } from "#shared/prerequisites/store";
+import { VpnStore } from "#shared/prerequisites/store";
+import { parseVpnStatus, vpnCommandSpec } from "#shared/prerequisites/driver-commands";
+import type { VpnCleanupPolicy } from "#shared/prerequisites/types";
+
+export type GuardianInitMessage = {
+  readonly type: "INIT";
+  readonly driver: SanitizedVpnDriver;
+  readonly runtimeRoot: string;
+  readonly leaseId: string;
+  readonly guardianId: string;
+  readonly ownerPid: number;
+  readonly cleanup: VpnCleanupPolicy;
+  readonly idleDisconnectMs: number;
+  readonly disconnectTimeoutMs: number;
+};
+export type GuardianReleaseMessage = { readonly type: "RELEASE"; readonly leaseId: string };
+export type GuardianInboundMessage = GuardianInitMessage | GuardianReleaseMessage;
+export type GuardianOutboundMessage =
+  | { readonly type: "READY"; readonly leaseId: string; readonly guardianId: string }
+  | { readonly type: "RELEASED"; readonly leaseId: string }
+  | { readonly type: "ERROR"; readonly message: string };
+
+export type GuardianCommandRunner = (
+  action: "status" | "stop",
+  timeoutMs: number,
+) => Promise<{ readonly stdout: string; readonly stderr: string; readonly exitCode: number }>;
+
+const safeEnvironment = (): Record<string, string> =>
+  Object.fromEntries(
+    ["PATH", "HOME", "TMPDIR", "TEMP", "TMP", "SYSTEMROOT", "WINDIR"].flatMap((name) => {
+      const value = process.env[name];
+      return value === undefined ? [] : [[name, value]];
+    }),
+  );
+
+export const makeGuardianCommandRunner =
+  (driver: SanitizedVpnDriver): GuardianCommandRunner =>
+  async (action, timeoutMs) => {
+    const spec = vpnCommandSpec(driver, action);
+    const child = Bun.spawn([spec.executable, ...spec.args], {
+      env: safeEnvironment(),
+      stdin: "ignore",
+      stdout: "pipe",
+      stderr: "pipe",
+      timeout: timeoutMs,
+      killSignal: "SIGKILL",
+    });
+    const [exitCode, stdout, stderr] = await Promise.all([
+      child.exited,
+      new Response(child.stdout).text(),
+      new Response(child.stderr).text(),
+    ]);
+    return { stdout, stderr, exitCode };
+  };
+
+const sleep = (milliseconds: number) =>
+  new Promise<void>((resolve) => {
+    setTimeout(resolve, milliseconds);
+  });
+
+export async function stopWhenIdle(
+  store: VpnStore,
+  init: GuardianInitMessage,
+  runCommand: GuardianCommandRunner,
+  now: () => number = Date.now,
+): Promise<void> {
+  const snapshot = store.snapshot();
+  if (snapshot.lifecycle !== "IDLE" || snapshot.idleDeadline === null) return;
+  const delay = snapshot.idleDeadline - now();
+  if (delay > 0) await sleep(delay);
+
+  const operationId = crypto.randomUUID();
+  const token = crypto.randomUUID();
+  const guard = store.claimStop(operationId, token, process.pid, now());
+  if (!guard) return;
+
+  const deadline = now() + init.disconnectTimeoutMs;
+  let evidence = "VPN stop did not produce confirmed disconnected status.";
+  try {
+    let remaining = deadline - now();
+    if (remaining > 0) {
+      const stop = await runCommand("stop", remaining);
+      remaining = deadline - now();
+      if (stop.exitCode !== 0) {
+        evidence = "VPN stop command failed; ownership is unknown and stop will not be retried.";
+      } else {
+        const confirmDisconnected = async (): Promise<boolean> => {
+          const statusRemaining = deadline - now();
+          if (statusRemaining <= 0) return false;
+          const status = await runCommand("status", statusRemaining);
+          remaining = deadline - now();
+          const connected = parseVpnStatus(init.driver, status);
+          if (connected === false) return true;
+          if (connected === undefined || remaining <= 0) return false;
+          const sleepRemaining = deadline - now();
+          if (sleepRemaining <= 0) return false;
+          await sleep(Math.min(250, sleepRemaining));
+          remaining = deadline - now();
+          return remaining > 0 && confirmDisconnected();
+        };
+        if (await confirmDisconnected()) {
+          store.commitStop(guard, true, "VPN stop confirmed disconnected.", now());
+          return;
+        }
+        evidence = "VPN status failed, stayed connected, or was unparseable after stop.";
+      }
+    } else {
+      evidence = "VPN disconnect deadline expired before a command could safely start.";
+    }
+  } catch {
+    evidence = "VPN stop or confirmation timed out or failed; ownership is unknown.";
+  }
+  store.commitStop(guard, false, evidence, now());
+}
+
+export function runGuardian(
+  init: GuardianInitMessage,
+  send: (message: GuardianOutboundMessage) => void,
+  runCommand: GuardianCommandRunner = makeGuardianCommandRunner(init.driver),
+): Promise<{ release: () => Promise<void> }> {
+  return new Promise((resolve) => {
+    const store = VpnStore.open(init.driver, { root: init.runtimeRoot });
+    let released = false;
+    store.reserveLease({
+      leaseId: init.leaseId,
+      guardianId: init.guardianId,
+      ownerPid: init.ownerPid,
+      cleanup: init.cleanup,
+      now: Date.now(),
+    });
+
+    const release = async () => {
+      if (released) return;
+      released = true;
+      try {
+        const result = store.releaseLease({
+          leaseId: init.leaseId,
+          guardianId: init.guardianId,
+          idleDisconnectMs: init.idleDisconnectMs,
+          now: Date.now(),
+        });
+        const stop =
+          result.released && result.deadline !== null
+            ? stopWhenIdle(store, init, runCommand)
+            : undefined;
+        if (stop && init.idleDisconnectMs === 0) await stop;
+        send({ type: "RELEASED", leaseId: init.leaseId });
+        if (stop && init.idleDisconnectMs > 0) await stop;
+      } finally {
+        store.close();
+      }
+    };
+
+    resolve({ release });
+  });
+}