@blogic-cz/agent-tools 0.15.12 → 0.15.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blogic-cz/agent-tools",
-  "version": "0.15.12",
+  "version": "0.15.14",
   "description": "CLI tools for AI coding agent workflows — GitHub, database, Kubernetes, Azure DevOps, logs, sessions, and audit",
   "keywords": [
     "agent",
@@ -39,90 +39,38 @@
   },
   "files": [
     "src/",
-    "dist/",
     "schemas/",
     "README.md",
     "LICENSE"
   ],
   "type": "module",
-  "types": "./dist/index.d.ts",
+  "types": "./src/index.ts",
   "imports": {
-    "#shared": {
-      "types": "./dist/shared/index.d.ts",
-      "default": "./src/shared/index.ts"
-    },
-    "#shared/*": {
-      "types": "./dist/shared/*.d.ts",
-      "default": "./src/shared/*.ts"
-    },
-    "#config": {
-      "types": "./dist/config/index.d.ts",
-      "default": "./src/config/index.ts"
-    },
-    "#config/*": {
-      "types": "./dist/config/*.d.ts",
-      "default": "./src/config/*.ts"
-    },
-    "#gh/*": {
-      "types": "./dist/gh-tool/*.d.ts",
-      "default": "./src/gh-tool/*.ts"
-    },
-    "#k8s/*": {
-      "types": "./dist/k8s-tool/*.d.ts",
-      "default": "./src/k8s-tool/*.ts"
-    },
-    "#db/*": {
-      "types": "./dist/db-tool/*.d.ts",
-      "default": "./src/db-tool/*.ts"
-    },
-    "#observability/*": {
-      "types": "./dist/observability-tool/*.d.ts",
-      "default": "./src/observability-tool/*.ts"
-    },
-    "#logs/*": {
-      "types": "./dist/logs-tool/*.d.ts",
-      "default": "./src/logs-tool/*.ts"
-    },
-    "#az/*": {
-      "types": "./dist/az-tool/*.d.ts",
-      "default": "./src/az-tool/*.ts"
-    },
-    "#guard": {
-      "types": "./dist/credential-guard/index.d.ts",
-      "default": "./src/credential-guard/index.ts"
-    },
-    "#session/*": {
-      "types": "./dist/session-tool/*.d.ts",
-      "default": "./src/session-tool/*.ts"
-    }
+    "#shared": "./src/shared/index.ts",
+    "#shared/*": "./src/shared/*.ts",
+    "#config": "./src/config/index.ts",
+    "#config/*": "./src/config/*.ts",
+    "#gh/*": "./src/gh-tool/*.ts",
+    "#k8s/*": "./src/k8s-tool/*.ts",
+    "#db/*": "./src/db-tool/*.ts",
+    "#observability/*": "./src/observability-tool/*.ts",
+    "#logs/*": "./src/logs-tool/*.ts",
+    "#az/*": "./src/az-tool/*.ts",
+    "#guard": "./src/credential-guard/index.ts",
+    "#session/*": "./src/session-tool/*.ts"
   },
   "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./src/index.ts"
-    },
-    "./credential-guard": {
-      "types": "./dist/credential-guard/index.d.ts",
-      "default": "./src/credential-guard/index.ts"
-    },
-    "./config": {
-      "types": "./dist/config/index.d.ts",
-      "default": "./src/config/index.ts"
-    },
-    "./audit": {
-      "types": "./dist/shared/audit.d.ts",
-      "default": "./src/shared/audit.ts"
-    },
-    "./k8s-probe": {
-      "types": "./dist/shared/k8s-probe.d.ts",
-      "default": "./src/shared/k8s-probe.ts"
-    }
+    ".": "./src/index.ts",
+    "./credential-guard": "./src/credential-guard/index.ts",
+    "./config": "./src/config/index.ts",
+    "./audit": "./src/shared/audit.ts",
+    "./k8s-probe": "./src/shared/k8s-probe.ts",
+    "./prerequisites": "./src/shared/prerequisites/index.ts"
   },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "build:types": "tsc -p tsconfig.declarations.json",
     "check": "bun check.ts",
     "check:ci": "bun check.ts ci",
     "format": "oxfmt",
@@ -154,6 +102,6 @@
     "@effect/platform-node-shared": "4.0.0-beta.98"
   },
   "engines": {
-    "bun": ">=1.0.0"
+    "bun": ">=1.3.0"
   }
 }

package/src/az-tool/service.ts

@@ -141,7 +141,7 @@ export class AzService extends Context.Service<
             message: result.stderr || `Command failed with exit code ${result.exitCode}`,
             command: fullCommand,
             exitCode: result.exitCode,
-            stderr: result.stderr || undefined,
+            ...(result.stderr ? { stderr: result.stderr } : {}),
           });
         }
 
@@ -209,7 +209,7 @@ export class AzService extends Context.Service<
             message: result.stderr || `Invoke failed with exit code ${result.exitCode}`,
             command: fullCommand,
             exitCode: result.exitCode,
-            stderr: result.stderr || undefined,
+            ...(result.stderr ? { stderr: result.stderr } : {}),
           });
         }
 

package/src/db-tool/errors.ts

@@ -28,14 +28,6 @@ export class DbTunnelError extends Schema.TaggedErrorClass<DbTunnelError>()("DbT
   retryable: Schema.optionalKey(Schema.Boolean),
 }) {}
 
-export class DbParseError extends Schema.TaggedErrorClass<DbParseError>()("DbParseError", {
-  message: Schema.String,
-  rawOutput: Schema.String,
-  hint: Schema.optionalKey(Schema.String),
-  nextCommand: Schema.optionalKey(Schema.String),
-  retryable: Schema.optionalKey(Schema.Boolean),
-}) {}
-
 export class DbMutationBlockedError extends Schema.TaggedErrorClass<DbMutationBlockedError>()(
   "DbMutationBlockedError",
   {
@@ -47,9 +39,4 @@ export class DbMutationBlockedError extends Schema.TaggedErrorClass<DbMutationBl
   },
 ) {}
 
-export type DbError =
-  | DbConnectionError
-  | DbMutationBlockedError
-  | DbParseError
-  | DbQueryError
-  | DbTunnelError;
+export type DbError = DbConnectionError | DbMutationBlockedError | DbQueryError | DbTunnelError;

package/src/db-tool/index.ts

@@ -17,6 +17,7 @@ import { ConfigService, ConfigServiceLayer, getDefaultEnvironment } from "#confi
 import { DbConfigService, makeDbConfigLayer } from "./config-service";
 import { DbConnectionError } from "./errors";
 import { DbService } from "./service";
+import { DbSqlClient } from "./sql-client";
 
 // Extract --profile from argv before @effect/cli parsing
 // so we can build the correct config layer.
@@ -243,6 +244,7 @@ const dbConfigLayer = makeDbConfigLayer(profileArg);
 const MainLayer = DbService.layer.pipe(
   // provideMerge (not provide) so DbConfigService stays in the program context for the `envs` command,
   // which reads it directly rather than going through DbService.
+  Layer.provideMerge(DbSqlClient.layer),
   Layer.provideMerge(dbConfigLayer),
   Layer.provideMerge(ConfigServiceLayer),
   Layer.provideMerge(BunServices.layer),

package/src/db-tool/security.ts

@@ -25,9 +25,27 @@ const MUTATION_TARGET_PATTERNS: Array<[DbMutationOperation, RegExp]> = [
   ["delete", new RegExp(String.raw`^\s*DELETE\s+FROM\s+(${QUALIFIED_IDENTIFIER_PATTERN})`, "i")],
 ];
 
+const DOLLAR_QUOTE_TAG = /^\$(?:[A-Za-z_][A-Za-z0-9_]*)?\$/;
+
+/**
+ * Postgres treats a backslash as an escape only inside an E'...' literal; in a standard string
+ * it is an ordinary character, so applying escapes everywhere would swallow a real closing quote.
+ */
+function isEscapeStringPrefix(sql: string, quoteIndex: number): boolean {
+  const prefix = sql[quoteIndex - 1];
+  if (prefix !== "E" && prefix !== "e") return false;
+  const before = sql[quoteIndex - 2];
+  return before === undefined || !/[A-Za-z0-9_$]/.test(before);
+}
+
 /**
- * Strip SQL comments (block and line) while preserving string literals.
- * This prevents bypass via inline comment masking before DELETE statements.
+ * Strip SQL comments (block and line) and empty out every string literal, keeping only
+ * double-quoted identifiers verbatim because the mutation-target parser needs them.
+ * Single quotes, double-quoted identifiers and dollar-quoted bodies must all be tracked:
+ * a quote or comment token surviving inside a region another check reads differently is a
+ * guard bypass. `SELECT * FROM "weird--table"; DROP TABLE users` would lose its statement
+ * separator to a phantom comment, and `SELECT $$O\'Brien$$ AS n; DROP TABLE users` would
+ * leave an unpaired apostrophe that swallows the separator instead.
  */
 export function stripSqlComments(sql: string): string {
   let result = "";
@@ -38,38 +56,63 @@ export function stripSqlComments(sql: string): string {
     const ch = sql[i];
     const next = i + 1 < len ? sql[i + 1] : "";
 
-    // Single-quoted string literal — skip through
-    if (ch === "'") {
+    if (ch === "'" || ch === '"') {
+      const keepBody = ch === '"';
+      const backslashEscapes = ch === "'" && isEscapeStringPrefix(sql, i);
       result += ch;
       i++;
       while (i < len) {
-        if (sql[i] === "'" && i + 1 < len && sql[i + 1] === "'") {
-          result += "''";
+        if (backslashEscapes && sql[i] === "\\" && i + 1 < len) {
+          if (keepBody) result += sql[i] + sql[i + 1];
           i += 2;
-        } else if (sql[i] === "'") {
-          result += "'";
+        } else if (sql[i] === ch && sql[i + 1] === ch) {
+          if (keepBody) result += ch + ch;
+          i += 2;
+        } else if (sql[i] === ch) {
+          result += ch;
           i++;
           break;
         } else {
-          result += sql[i];
+          if (keepBody) result += sql[i];
           i++;
         }
       }
       continue;
     }
 
-    // Block comment /* ... */
+    if (ch === "$") {
+      const tag = DOLLAR_QUOTE_TAG.exec(sql.slice(i))?.[0];
+      if (tag) {
+        const closing = sql.indexOf(tag, i + tag.length);
+        const stop = closing === -1 ? len : closing + tag.length;
+        result += closing === -1 ? tag : tag + tag;
+        i = stop;
+        continue;
+      }
+    }
+
+    // Postgres block comments nest, so track depth rather than stopping at the first */.
     if (ch === "/" && next === "*") {
+      let depth = 1;
       i += 2;
-      while (i + 1 < len && !(sql[i] === "*" && sql[i + 1] === "/")) {
-        i++;
+      while (i + 1 < len && depth > 0) {
+        if (sql[i] === "/" && sql[i + 1] === "*") {
+          depth++;
+          i += 2;
+        } else if (sql[i] === "*" && sql[i + 1] === "/") {
+          depth--;
+          i += 2;
+        } else {
+          i++;
+        }
+      }
+      if (depth > 0) {
+        i = len;
       }
-      i += 2; // skip closing */
-      result += " "; // replace comment with space
+      result += " ";
       continue;
     }
 
-    // Line comment -- ...
     if (ch === "-" && next === "-") {
       i += 2;
       while (i < len && sql[i] !== "\n") {
@@ -86,6 +129,44 @@ export function stripSqlComments(sql: string): string {
   return result;
 }
 
+/**
+ * Postgres runs every statement in a simple-query batch, but MUTATION_PATTERNS only match the
+ * first one, so `select 1; delete from x` would otherwise pass the guard as a plain read.
+ * Dollar-quoted bodies containing `;` are rejected as well: this fails closed by design.
+ */
+export function hasMultipleStatements(sql: string): boolean {
+  const stripped = stripSqlComments(sql);
+  let index = 0;
+
+  while (index < stripped.length) {
+    const char = stripped[index];
+
+    if (char === "'" || char === '"') {
+      index++;
+      while (index < stripped.length) {
+        if (stripped[index] === char && stripped[index + 1] === char) {
+          index += 2;
+          continue;
+        }
+        if (stripped[index] === char) {
+          index++;
+          break;
+        }
+        index++;
+      }
+      continue;
+    }
+
+    if (char === ";" && stripped.slice(index + 1).trim().length > 0) {
+      return true;
+    }
+
+    index++;
+  }
+
+  return false;
+}
+
 export function isMutationQuery(sql: string): boolean {
   const stripped = stripSqlComments(sql);
   return MUTATION_PATTERNS.some((pattern) => pattern.test(stripped));

package/src/db-tool/service.ts

@@ -1,5 +1,5 @@
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
-import { Clock, Context, Duration, Effect, Layer, Ref, Stream } from "effect";
+import { Clock, Context, Duration, Effect, Layer, Ref, Result, Stream } from "effect";
 
 import type { DbConfig, DbMutationOperation, QueryResult, SchemaMode } from "./types";
 
@@ -9,11 +9,12 @@ import { resolveEnvTemplate } from "#shared/env-template";
 import { resolveEnvironmentScopedPrerequisites } from "#shared/prerequisites/config";
 import { runWithProfilePrerequisites } from "#shared/prerequisites/runtime";
 import { buildApiProbeArgs } from "#shared/k8s-probe";
+import { missingBinaryFromSpawnFailure } from "#shared/binary-preflight";
 import { DbConfigService, TUNNEL_CHECK_INTERVAL_MS } from "./config-service";
+import { DbSqlClient, type DbConnection } from "./sql-client";
 import {
   DbConnectionError,
   DbMutationBlockedError,
-  DbParseError,
   DbQueryError,
   DbTunnelError,
   type DbError,
@@ -29,6 +30,7 @@ import {
   detectSchemaError,
   getAllowedMutationOperation,
   getMutationTarget,
+  hasMultipleStatements,
   isValidTableName,
   isMutationQuery,
 } from "./security";
@@ -86,6 +88,7 @@ export class DbService extends Context.Service<
     Effect.scoped(
       Effect.gen(function* () {
         const executor = yield* ChildProcessSpawner.ChildProcessSpawner;
+        const sqlClient = yield* DbSqlClient;
         const agentToolsConfig = yield* ConfigService;
         const dbConfig = yield* DbConfigService;
 
@@ -230,22 +233,29 @@ export class DbService extends Context.Service<
               return { stdout, stderr, exitCode };
             }),
           ).pipe(
-            Effect.mapError(
-              (platformError) =>
-                new DbQueryError({
-                  message: `Command execution failed: ${String(platformError)}`,
-                  sql: "shell command",
-                  stderr: undefined,
-                }),
-            ),
+            Effect.mapError((platformError) => {
+              const missing = missingBinaryFromSpawnFailure("kubectl", String(platformError));
+              return new DbQueryError({
+                message: `Command execution failed: ${String(platformError)}`,
+                sql: "shell command",
+                stderr: String(platformError),
+                ...(missing ? { hint: missing.hint } : {}),
+              });
+            }),
           );
 
         const checkPortOpen = (port: number) =>
-          executeShellCommand(
-            ChildProcess.make("nc", ["-z", "localhost", String(port)], {
-              stdout: "pipe",
-              stderr: "pipe",
-            }),
+          Effect.tryPromise(async () => {
+            const socket = await Bun.connect({
+              hostname: "127.0.0.1",
+              port,
+              socket: { data: () => undefined },
+            });
+            socket.end();
+            return true;
+          }).pipe(
+            Effect.timeout(TUNNEL_CHECK_INTERVAL_MS),
+            Effect.orElseSucceed(() => false),
           );
 
         const runWithVpnPrerequisites = <E>(
@@ -282,11 +292,7 @@ export class DbService extends Context.Service<
                 return false;
               }
 
-              const result = yield* checkPortOpen(port).pipe(
-                Effect.catch(() => Effect.succeed({ exitCode: 1 })),
-              );
-
-              if (result.exitCode === 0) {
+              if (yield* checkPortOpen(port)) {
                 return true;
               }
 
@@ -376,68 +382,34 @@ export class DbService extends Context.Service<
           return result.exitCode === 0;
         });
 
-        const buildPsqlCommand = (
-          config: DbConfig,
-          sql: string,
-          password: string,
-          useTuplesOnly: boolean,
-        ) => {
-          const args = [
-            "-h",
-            config.host,
-            "-p",
-            String(config.port),
-            "-U",
-            config.user,
-            "-d",
-            config.database,
-          ];
-
-          const commandArgs = useTuplesOnly
-            ? [...args, "-t", "-A", "-c", sql]
-            : [...args, "-c", sql];
-
-          return ChildProcess.make("psql", commandArgs, {
-            stdout: "pipe",
-            stderr: "pipe",
-            env: {
-              ...process.env,
-              ...(password ? { PGPASSWORD: password } : {}),
-              ...(isFullyReadOnly(config)
-                ? { PGOPTIONS: "-c default_transaction_read_only=on" }
-                : {}),
-            } as Record<string, string>,
-          });
-        };
+        const toConnection = (config: DbConfig, password: string): DbConnection => ({
+          host: config.host,
+          port: config.port,
+          user: config.user,
+          database: config.database,
+          password,
+          readOnly: isFullyReadOnly(config),
+        });
 
-        const fetchTableNamesForError = Effect.fn("DbService.fetchTableNamesForError")(function* (
-          config: DbConfig,
-          password: string,
-        ) {
-          const command = buildPsqlCommand(
-            config,
-            `SELECT schemaname || '.' || tablename FROM pg_tables WHERE schemaname NOT IN (${SYSTEM_SCHEMAS_SQL}) ORDER BY schemaname, tablename;`,
-            password,
-            true,
-          );
-          const result = yield* executeShellCommand(command).pipe(
-            Effect.catch(() =>
-              Effect.succeed({
-                stdout: "",
-                stderr: "",
-                exitCode: 1,
-              }),
+        const runSql = (config: DbConfig, password: string, sql: string) =>
+          sqlClient.run(toConnection(config, password), sql);
+
+        const fetchSingleColumn = (config: DbConfig, password: string, sql: string) =>
+          runSql(config, password, sql).pipe(
+            Effect.map((outcome) =>
+              outcome.rows
+                .map((row) => String(Object.values(row)[0] ?? ""))
+                .filter((value) => value.length > 0),
             ),
+            Effect.orElseSucceed(() => [] as string[]),
           );
-          if (result.exitCode !== 0) {
-            return [] as string[];
-          }
 
-          return result.stdout
-            .trim()
-            .split("\n")
-            .filter((name) => name.length > 0);
-        });
+        const fetchTableNamesForError = (config: DbConfig, password: string) =>
+          fetchSingleColumn(
+            config,
+            password,
+            `SELECT schemaname || '.' || tablename FROM pg_tables WHERE schemaname NOT IN (${SYSTEM_SCHEMAS_SQL}) ORDER BY schemaname, tablename;`,
+          );
 
         const fetchColumnNamesForError = Effect.fn("DbService.fetchColumnNamesForError")(function* (
           config: DbConfig,
@@ -455,29 +427,11 @@ export class DbService extends Context.Service<
             ? `AND table_schema = '${escapedSchemaName}'`
             : `AND table_schema NOT IN (${SYSTEM_SCHEMAS_SQL})`;
 
-          const command = buildPsqlCommand(
+          return yield* fetchSingleColumn(
             config,
-            `SELECT column_name FROM information_schema.columns WHERE table_name = '${escapedTableName}' ${schemaFilter} ORDER BY table_schema, ordinal_position;`,
             password,
-            true,
-          );
-          const result = yield* executeShellCommand(command).pipe(
-            Effect.catch(() =>
-              Effect.succeed({
-                stdout: "",
-                stderr: "",
-                exitCode: 1,
-              }),
-            ),
+            `SELECT column_name FROM information_schema.columns WHERE table_name = '${escapedTableName}' ${schemaFilter} ORDER BY table_schema, ordinal_position;`,
           );
-          if (result.exitCode !== 0) {
-            return [] as string[];
-          }
-
-          return result.stdout
-            .trim()
-            .split("\n")
-            .filter((name) => name.length > 0);
         });
 
         const executeSelectQuery = Effect.fn("DbService.executeSelectQuery")(function* (
@@ -489,16 +443,15 @@ export class DbService extends Context.Service<
           limit?: number,
         ) {
           const selectSql = sql.trim().replace(/;\s*$/, "");
-          const wrappedSql = `SELECT json_agg(t) FROM (${selectSql}) t;`;
-          const command = buildPsqlCommand(config, wrappedSql, password, true);
-          const result = yield* executeShellCommand(command);
+          const outcome = yield* Effect.result(runSql(config, password, selectSql));
           const endTime = yield* Clock.currentTimeMillis;
 
-          if (result.exitCode !== 0) {
-            const schemaError = detectSchemaError(result.stderr, sql);
+          if (Result.isFailure(outcome)) {
+            const failureMessage = outcome.failure.message.trim();
+            const schemaError = detectSchemaError(failureMessage, sql);
             const baseResult: QueryResult = {
               success: false,
-              error: result.stderr.trim() || `psql exited with code ${result.exitCode}`,
+              error: failureMessage || "Query failed",
               executionTimeMs: Number(endTime) - startTimeMs,
             };
 
@@ -524,32 +477,10 @@ export class DbService extends Context.Service<
               };
             }
 
-            return yield* new DbQueryError({
-              message: baseResult.error ?? "Query failed",
-              sql,
-              stderr: result.stderr.trim() || undefined,
-            });
-          }
-
-          const trimmedOutput = result.stdout.trim();
-          if (!trimmedOutput || trimmedOutput === "null") {
-            return {
-              success: true,
-              data: [],
-              rowCount: 0,
-              executionTimeMs: Number(endTime) - startTimeMs,
-            };
+            return yield* outcome.failure;
           }
 
-          const rawData = yield* Effect.try({
-            try: () => JSON.parse(trimmedOutput) as Record<string, unknown>[],
-            catch: () =>
-              new DbParseError({
-                message: "Failed to parse query result as JSON.",
-                rawOutput: trimmedOutput.slice(0, 500),
-              }),
-          });
-
+          const rawData = outcome.success.rows;
           const transformed = applyTransform
             ? transformQueryResult(rawData, limit)
             : {
@@ -574,25 +505,13 @@ export class DbService extends Context.Service<
           password: string,
           startTimeMs: number,
         ) {
-          const command = buildPsqlCommand(config, sql, password, false);
-          const result = yield* executeShellCommand(command);
+          const outcome = yield* runSql(config, password, sql);
           const endTime = yield* Clock.currentTimeMillis;
-
-          if (result.exitCode !== 0) {
-            return yield* new DbQueryError({
-              message: result.stderr.trim() || `psql exited with code ${result.exitCode}`,
-              sql,
-              stderr: result.stderr.trim() || undefined,
-            });
-          }
-
-          const output = result.stdout.trim();
-          const rowCountMatch = output.match(/(?:UPDATE|DELETE|INSERT \d+)\s+(\d+)/i);
-          const rowCount = rowCountMatch ? parseInt(rowCountMatch[1], 10) : 0;
+          const rowCount = outcome.rowCount;
 
           return {
             success: true,
-            message: output,
+            message: `${outcome.command} ${rowCount}`.trim(),
             rowCount,
             executionTimeMs: Number(endTime) - startTimeMs,
           };
@@ -745,6 +664,15 @@ export class DbService extends Context.Service<
           const startTimeMs = yield* Clock.currentTimeMillis;
           const resolvedConfig = yield* resolveDbConfig(config, env);
           const password = yield* resolvePassword(resolvedConfig, env);
+          if (hasMultipleStatements(sql)) {
+            return yield* new DbQueryError({
+              message:
+                "Multiple SQL statements in a single call are not allowed; the mutation guard only inspects the first statement.",
+              sql,
+              hint: "Send one statement per call.",
+            });
+          }
+
           const mutation = isMutationQuery(sql);
           const mutationOperation = mutation ? getAllowedMutationOperation(sql) : undefined;
           const mutationTarget = mutation ? getMutationTarget(sql) : undefined;

package/src/db-tool/sql-client.ts

@@ -0,0 +1,80 @@
+import { Context, Effect, Layer } from "effect";
+
+import { DbQueryError } from "./errors";
+
+export type DbConnection = {
+  readonly host: string;
+  readonly port: number;
+  readonly user: string;
+  readonly database: string;
+  readonly password: string;
+  readonly readOnly: boolean;
+};
+
+export type DbQueryOutcome = {
+  readonly rows: Record<string, unknown>[];
+  readonly rowCount: number;
+  readonly command: string;
+};
+
+type BunQueryResult = unknown[] & { count?: number; command?: string };
+
+export const toErrorMessage = (cause: unknown): string =>
+  cause instanceof Error ? cause.message : String(cause);
+
+const runWithBunSql = (connection: DbConnection, sql: string) =>
+  Effect.tryPromise({
+    try: async (): Promise<DbQueryOutcome> => {
+      const client = new Bun.SQL({
+        hostname: connection.host,
+        port: connection.port,
+        username: connection.user,
+        password: connection.password,
+        database: connection.database,
+        max: 1,
+        // Startup-packet GUC: covers every pooled connection, unlike a post-connect SET.
+        ...(connection.readOnly ? { connection: { default_transaction_read_only: "on" } } : {}),
+      });
+
+      try {
+        if (connection.readOnly) {
+          const [state] = (await client.unsafe("SHOW transaction_read_only")) as {
+            transaction_read_only?: string;
+          }[];
+          if (state?.transaction_read_only !== "on") {
+            throw new Error(
+              "Refusing to query: the read-only session setting was not accepted by the server, so writes would not be blocked.",
+            );
+          }
+        }
+
+        const result = (await client.unsafe(sql)) as BunQueryResult;
+        const rows = Array.isArray(result) ? (result as Record<string, unknown>[]) : [];
+
+        return {
+          rows,
+          rowCount: result.count ?? rows.length,
+          command: result.command ?? "",
+        };
+      } finally {
+        // A rejecting close() would replace the real query error via try/finally semantics.
+        await client.close().catch(() => undefined);
+      }
+    },
+    catch: (cause) => {
+      const message = toErrorMessage(cause);
+      return new DbQueryError({ message, sql, stderr: message });
+    },
+  });
+
+export class DbSqlClient extends Context.Service<
+  DbSqlClient,
+  {
+    readonly run: (
+      connection: DbConnection,
+      sql: string,
+    ) => Effect.Effect<DbQueryOutcome, DbQueryError>;
+  }
+>()("@agent-tools/DbSqlClient") {
+  static readonly layer = Layer.succeed(DbSqlClient, { run: runWithBunSql });
+}

package/src/gh-tool/pr/helpers.ts

@@ -2,6 +2,7 @@ import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
 import { Effect, Stream } from "effect";
 
 import { GitHubCommandError } from "#gh/errors";
+import { missingBinaryFromSpawnFailure } from "#shared/binary-preflight";
 
 export type LocalCommandResult = {
   stdout: string;
@@ -69,15 +70,16 @@ export const runLocalCommand = Effect.fn("pr.runLocalCommand")(function* (
       return commandResult;
     }),
   ).pipe(
-    Effect.mapError(
-      (error) =>
-        new GitHubCommandError({
-          command: [binary, ...args].join(" "),
-          exitCode: -1,
-          stderr: String(error),
-          message: String(error),
-        }),
-    ),
+    Effect.mapError((error) => {
+      const missing = missingBinaryFromSpawnFailure(binary, String(error));
+      return new GitHubCommandError({
+        command: [binary, ...args].join(" "),
+        exitCode: -1,
+        stderr: String(error),
+        message: missing?.message ?? String(error),
+        ...(missing ? { hint: missing.hint } : {}),
+      });
+    }),
   );
 
   return result;

package/src/index.ts

@@ -1,5 +1,7 @@
 export type { AgentToolsConfig, ObservabilityConfig, ObservabilityEnvTarget } from "./config/index";
 
+export type { BaseResult, Environment, OutputFormat, ToolResult } from "./shared/types";
+
 export {
   AuditService,
   AuditServiceLayer,

package/src/k8s-tool/service.ts

@@ -14,6 +14,7 @@ import {
 import { ConfigService, getToolConfig } from "#config";
 import type { K8sConfig } from "#config";
 import { collectProcessOutput, quoteShellArg } from "#shared/exec";
+import { missingBinaryFromSpawnFailure } from "#shared/binary-preflight";
 import { resolveEnvTemplate } from "#shared/env-template";
 import { isPrerequisiteRunError } from "#shared/prerequisites/errors";
 import { normalizeProfilePrerequisites } from "#shared/prerequisites/config";
@@ -135,15 +136,16 @@ export class K8sService extends Context.Service<
             }),
           ).pipe(
             Effect.timeoutOption(timeoutMs),
-            Effect.mapError(
-              (platformError) =>
-                new K8sCommandError({
-                  message: `Command execution failed: ${String(platformError)}`,
-                  command: commandStr,
-                  exitCode: -1,
-                  stderr: undefined,
-                }),
-            ),
+            Effect.mapError((platformError) => {
+              const missing = missingBinaryFromSpawnFailure("kubectl", String(platformError));
+              return new K8sCommandError({
+                message: `Command execution failed: ${String(platformError)}`,
+                command: commandStr,
+                exitCode: -1,
+                stderr: String(platformError),
+                ...(missing ? { hint: missing.hint } : {}),
+              });
+            }),
           );
 
         const runPrerequisiteCommand = (command: ChildProcess.Command, label: string) =>
@@ -153,15 +155,16 @@ export class K8sService extends Context.Service<
               return yield* collectProcessOutput(process);
             }),
           ).pipe(
-            Effect.mapError(
-              (platformError) =>
-                new K8sCommandError({
-                  message: `Prerequisite command failed (${label}): ${String(platformError)}`,
-                  command: label,
-                  exitCode: -1,
-                  stderr: String(platformError),
-                }),
-            ),
+            Effect.mapError((platformError) => {
+              const missing = missingBinaryFromSpawnFailure("kubectl", String(platformError));
+              return new K8sCommandError({
+                message: `Prerequisite command failed (${label}): ${String(platformError)}`,
+                command: label,
+                exitCode: -1,
+                stderr: String(platformError),
+                ...(missing ? { hint: missing.hint } : {}),
+              });
+            }),
           );
 
         /**
@@ -276,6 +279,7 @@ export class K8sService extends Context.Service<
           const k8sConfig = yield* requireK8sConfig(profile);
           const timeoutMs = k8sConfig.timeoutMs ?? 60000;
           const apiProbeTimeoutMs = k8sConfig.apiProbeTimeoutMs ?? 2000;
+
           const { context, kubeconfig } = yield* resolveContext(profile, k8sConfig);
           const reachableWithoutPrerequisites = yield* probeApiReachable(
             context,
@@ -314,15 +318,16 @@ export class K8sService extends Context.Service<
                 }),
               ).pipe(
                 Effect.timeoutOption(timeoutMs),
-                Effect.mapError(
-                  (platformError) =>
-                    new K8sCommandError({
-                      message: `Command execution failed: ${String(platformError)}`,
-                      command: fullCommand,
-                      exitCode: -1,
-                      stderr: undefined,
-                    }),
-                ),
+                Effect.mapError((platformError) => {
+                  const missing = missingBinaryFromSpawnFailure("kubectl", String(platformError));
+                  return new K8sCommandError({
+                    message: `Command execution failed: ${String(platformError)}`,
+                    command: fullCommand,
+                    exitCode: -1,
+                    stderr: String(platformError),
+                    ...(missing ? { hint: missing.hint } : {}),
+                  });
+                }),
               );
 
               if (Option.isNone(resultOption)) {
@@ -473,7 +478,7 @@ export class K8sService extends Context.Service<
                 `Remote realpath exited with code ${realpathResult.exitCode}`,
               command: realpathResult.command,
               exitCode: realpathResult.exitCode,
-              stderr: realpathResult.stderr || undefined,
+              ...(realpathResult.stderr ? { stderr: realpathResult.stderr } : {}),
             });
           }
           const [canonicalBase, canonicalPath] = realpathResult.stdout.trim().split("\n");

package/src/shared/binary-preflight.ts

@@ -0,0 +1,42 @@
+export const REQUIRED_BINARIES = {
+  az: {
+    tools: "az-tool",
+    install:
+      "Install it with `brew install azure-cli` (macOS) or see https://learn.microsoft.com/cli/azure/install-azure-cli.",
+  },
+  gh: {
+    tools: "gh-tool",
+    install:
+      "Install it with `brew install gh` (macOS) or see https://cli.github.com/, then run `gh auth login`.",
+  },
+  git: {
+    tools: "gh-tool release and stack commands",
+    install:
+      "Install it with `xcode-select --install` (macOS) or see https://git-scm.com/downloads.",
+  },
+  kubectl: {
+    tools: "k8s-tool and db-tool tunnels",
+    install:
+      "Install it with `brew install kubectl` (macOS) or see https://kubernetes.io/docs/tasks/tools/.",
+  },
+} as const;
+
+export type RequiredBinary = keyof typeof REQUIRED_BINARIES;
+
+export type MissingBinary = { binary: RequiredBinary; message: string; hint: string };
+
+const isRequiredBinary = (binary: string): binary is RequiredBinary => binary in REQUIRED_BINARIES;
+
+export const describeMissingBinary = (binary: RequiredBinary): MissingBinary => ({
+  binary,
+  message: `Required binary "${binary}" was not found on PATH.`,
+  hint: `${binary} is needed by ${REQUIRED_BINARIES[binary].tools}. ${REQUIRED_BINARIES[binary].install}`,
+});
+
+export const missingBinaryFromSpawnFailure = (
+  binary: string,
+  failure: string,
+): MissingBinary | undefined =>
+  isRequiredBinary(binary) && failure.includes("NotFound")
+    ? describeMissingBinary(binary)
+    : undefined;

package/src/shared/index.ts

@@ -1,4 +1,11 @@
-export type { BaseResult, CommandOptions, CommandResult, Environment, OutputFormat } from "./types";
+export type {
+  BaseResult,
+  CommandOptions,
+  CommandResult,
+  Environment,
+  OutputFormat,
+  ToolResult,
+} from "./types";
 
 export { formatAny, formatOption, formatOutput, logFormatted } from "./format";
 

package/src/shared/prerequisites/index.ts

@@ -0,0 +1,12 @@
+export { runWithProfilePrerequisites } from "#shared/prerequisites/runtime";
+
+export { resolveEnvironmentScopedPrerequisites } from "#shared/prerequisites/config";
+
+export { isPrerequisiteRunError, PrerequisiteRunError } from "#shared/prerequisites/errors";
+
+export type {
+  PrerequisiteCommandResult,
+  PrerequisiteCommandRunner,
+} from "#shared/prerequisites/types";
+
+export type { ProfilePrerequisites, VpnPrerequisite } from "#config/types";

package/src/shared/types.ts

@@ -10,6 +10,12 @@ export type BaseResult = {
   hint?: string;
 };
 
+// Widening BaseResult itself is not honest: db-tool's select branch emits no message.
+export type ToolResult = BaseResult & {
+  message: string;
+  data?: unknown;
+};
+
 export type CommandOptions = {
   cwd?: string;
   env?: Record<string, string>;