@blogic-cz/agent-tools 0.15.6 → 0.15.8

package/README.md

@@ -263,7 +263,7 @@ Pod `exec` is limited to direct `redis-cli PING/INFO` and `ls` diagnostics. Gene
 
 ### gh-tool machine contracts
 
-`pr view` adds `headSha` and `baseSha`; failed-check evidence adds the same SHA pair. Review summaries, inline comments, and threads add `commitSha` plus `feedbackOrigin`: `current_head` only for an exact `commitSha === headSha`, `pre_existing` for a different known SHA (not an obsolescence verdict), and `unknown` when either SHA is absent. Issue comments always use `commitSha: null` and `feedbackOrigin: unknown`. `review-triage` preserves existing fields and adds `inlineComments` plus per-kind `feedbackOriginCounts`; batch triage returns the same object per PR.
+`pr view` adds `headSha` and `baseSha`; failed-check evidence adds the same SHA pair. Review summaries, inline comments, and threads add `commitSha` plus `feedbackOrigin`: `current_head` only for an exact `commitSha === headSha`, `pre_existing` for a different known SHA (not an obsolescence verdict), and `unknown` when either SHA is absent. Issue comments always use `commitSha: null` and `feedbackOrigin: unknown`. `review-triage` preserves existing fields and adds `inlineComments` plus per-kind `feedbackOriginCounts`; batch triage returns the same object per PR. `pr request-review --reviewers alice,bob` emits sorted `submittedReviewers` (normalized input) and `requestedReviewers` (GitHub-confirmed result).
 
 `pr watch --prs 12,34 --until terminal --format jsonl` accepts at most 50 unique, digits-only PR numbers and emits only JSONL state transitions. Identity uses `repo/pr/headSha/runId/attempt/jobId`; `runId`, `attempt`, and `jobId` are omitted from an event rather than emitted as `null`, and `checkId` is no longer emitted. State/bucket revisions emit even when identity stays stable; `supersedes` appears only when identity changes. Open PRs with no checks become terminal only after three stable empty snapshots, allowing bounded GitHub eventual consistency, and carry `checksObserved: false` — a terminal snapshot with no observed check is never green evidence. `pr checks`, batch checks, triage, and batch triage keep stderr silent with `--format json`; JSONL watch is also informationally silent. Failures still return structured nonzero errors on stderr.
 
@@ -275,6 +275,7 @@ bun gh-tool pr rerun-checks --pr 123 --failed-only --watch --timeout 600
 bun gh-tool pr trigger-checks --pr 123 --workflow dotnet-pull-request.yml # only when zero checks reported
 bun gh-tool pr watch --prs 123,124 --format jsonl --timeout 600
 bun gh-tool pr reply-and-resolve --comment-id 456 --body "Done" # infers PR and thread
+bun gh-tool pr request-review --repo be --pr 123 --reviewers alice,bob
 # Optional --pr/--thread-id retain legacy flow and are validated before either mutation.
 ```
 

package/package.json

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

package/src/gh-tool/index.ts

@@ -27,6 +27,7 @@ import {
   prEditCommand,
   prMergeCommand,
   prReadyCommand,
+  prRequestReviewCommand,
   prThreadsCommand,
   prCommentsCommand,
   prIssueCommentsCommand,
@@ -84,6 +85,7 @@ const prCommand = Command.make("pr", {}).pipe(
     prEditCommand,
     prMergeCommand,
     prReadyCommand,
+    prRequestReviewCommand,
     prWaitMergeableCommand,
     prThreadsCommand,
     prCommentsCommand,

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

@@ -76,6 +76,85 @@ const withRepo = <A, E, R>(repo: Option.Option<string>, effect: Effect.Effect<A,
     return yield* gh.withRepoTarget(Option.getOrNull(repo), effect);
   });
 
+const reviewerInputError = (reviewers: string) =>
+  new GitHubCommandError({
+    message: `--reviewers must be comma-separated GitHub user logins without empty segments: ${JSON.stringify(reviewers)}`,
+    command: "gh-tool pr request-review",
+    exitCode: 1,
+    stderr: "",
+    hint: "Pass user logins such as --reviewers octocat,hubot.",
+  });
+
+const prNumberError = (pr: number) =>
+  new GitHubCommandError({
+    message: `--pr must be a positive integer: ${pr}`,
+    command: "gh-tool pr request-review",
+    exitCode: 1,
+    stderr: "",
+    hint: "Pass a positive PR number, e.g. --pr 123.",
+  });
+
+const GITHUB_LOGIN_RE = /^(?!.*--)[a-z\d](?:[a-z\d-]{0,37}[a-z\d])?$/;
+
+export const parseReviewers = (reviewers: string) => {
+  const parsed = reviewers.split(",").map((reviewer) => reviewer.trim().toLowerCase());
+  if (parsed.length === 0 || parsed.some((reviewer) => !GITHUB_LOGIN_RE.test(reviewer))) {
+    return Effect.fail(reviewerInputError(reviewers));
+  }
+  return Effect.succeed([...new Set(parsed)].toSorted());
+};
+
+type RequestedReviewersResponse = { requested_reviewers?: unknown };
+
+const confirmedReviewers = (response: RequestedReviewersResponse) => {
+  if (!Array.isArray(response.requested_reviewers)) {
+    return Effect.fail(
+      new GitHubCommandError({
+        message: "GitHub requested-reviewers response omitted requested_reviewers.",
+        command: "gh-tool pr request-review",
+        exitCode: 1,
+        stderr: JSON.stringify(response),
+      }),
+    );
+  }
+  const logins = response.requested_reviewers.map((reviewer) =>
+    typeof reviewer === "object" && reviewer !== null && "login" in reviewer
+      ? (reviewer as { login?: unknown }).login
+      : undefined,
+  );
+  if (logins.some((login) => typeof login !== "string")) {
+    return Effect.fail(
+      new GitHubCommandError({
+        message: "GitHub requested-reviewers response contained an invalid reviewer.",
+        command: "gh-tool pr request-review",
+        exitCode: 1,
+        stderr: JSON.stringify(response),
+      }),
+    );
+  }
+  return Effect.succeed([...new Set(logins as string[])].toSorted());
+};
+
+export const requestReview = (pr: number, reviewers: string) =>
+  Effect.gen(function* () {
+    if (!Number.isInteger(pr) || pr <= 0) return yield* prNumberError(pr);
+    const submittedReviewers = yield* parseReviewers(reviewers);
+    const gh = yield* GitHubService;
+    const repo = yield* gh.getRepoInfo();
+    const response = yield* gh.runGhJson<RequestedReviewersResponse>([
+      "api",
+      "--method",
+      "POST",
+      `repos/${repo.owner}/${repo.name}/pulls/${pr}/requested_reviewers`,
+      ...submittedReviewers.flatMap((reviewer) => ["-f", `reviewers[]=${reviewer}`]),
+    ]);
+    return {
+      pr,
+      submittedReviewers,
+      requestedReviewers: yield* confirmedReviewers(response),
+    };
+  });
+
 type ReviewTriageSummary = {
   readonly visibleOpenReviewThreadsCount: number;
   readonly unrepliedReviewThreadsCount: number;
@@ -1347,6 +1426,25 @@ export const prReviewTriageCommand = Command.make(
   ),
 );
 
+export const prRequestReviewCommand = Command.make(
+  "request-review",
+  {
+    format: formatOption,
+    pr: Flag.integer("pr").pipe(Flag.withDescription("Positive pull request number")),
+    repo: repoOption,
+    reviewers: Flag.string("reviewers").pipe(
+      Flag.withDescription("Comma-separated GitHub user logins"),
+    ),
+  },
+  ({ format, pr, repo, reviewers }) =>
+    withRepo(
+      repo,
+      Effect.gen(function* () {
+        yield* logFormatted(yield* requestReview(pr, reviewers), format);
+      }),
+    ),
+).pipe(Command.withDescription("Request review from comma-separated GitHub user logins"));
+
 export const prReviewTriageBatchCommand = Command.make(
   "review-triage-batch",
   {

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

@@ -14,6 +14,7 @@ export {
   prListCommand,
   prMergeCommand,
   prReadyCommand,
+  prRequestReviewCommand,
   prReplyCommand,
   prRerunChecksCommand,
   prReplyAndResolveCommand,

package/src/k8s-tool/index.ts

@@ -120,8 +120,10 @@ const executeK8sCommand = (command: string, options: CommonK8sCommandOptions) =>
           const errorResult: CommandResult = {
             success: false,
             error: error.message,
-            hint: `Verify cluster ID "${k8sConfig.clusterId}" matches a context in kubectl config. Run: kubectl config get-contexts`,
-            nextCommand: "kubectl config get-contexts",
+            hint:
+              error.hint ??
+              `Verify cluster ID "${k8sConfig.clusterId}" matches a context in kubectl config. Run: kubectl config get-contexts`,
+            ...(error.hint ? {} : { nextCommand: "kubectl config get-contexts" }),
             executionTimeMs: 0,
           };
           return Effect.succeed(errorResult);

package/src/k8s-tool/service.ts

@@ -16,6 +16,7 @@ import type { K8sConfig } from "#config";
 import { collectProcessOutput, quoteShellArg } from "#shared/exec";
 import { resolveEnvTemplate } from "#shared/env-template";
 import { isPrerequisiteRunError } from "#shared/prerequisites/errors";
+import { normalizeProfilePrerequisites } from "#shared/prerequisites/config";
 import { runWithProfilePrerequisites } from "#shared/prerequisites/runtime";
 import { buildApiProbeArgs } from "#shared/k8s-probe";
 import { isKubectlCommandAllowed, isSafeLogPath } from "./security";
@@ -275,14 +276,23 @@ 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,
+            kubeconfig,
+            apiProbeTimeoutMs,
+          );
+          const vpnGated = normalizeProfilePrerequisites(k8sConfig).some(
+            (prerequisite) => prerequisite.type === "vpn",
+          );
           return yield* runWithProfilePrerequisites(
             config ?? {},
             k8sConfig,
             runPrerequisiteCommand,
             Effect.gen(function* () {
-              const { context, kubeconfig } = yield* resolveContext(profile, k8sConfig);
-
-              const reachable = yield* probeApiReachable(context, kubeconfig, apiProbeTimeoutMs);
+              const reachable =
+                reachableWithoutPrerequisites ||
+                (vpnGated && (yield* probeApiReachable(context, kubeconfig, apiProbeTimeoutMs)));
               if (!reachable) {
                 return yield* new K8sContextError({
                   message: `Kubernetes API server (${k8sConfig.clusterId}) not reachable within ${apiProbeTimeoutMs}ms. VPN likely not connected, or the cluster API is degraded.`,
@@ -332,6 +342,7 @@ export class K8sService extends Context.Service<
                 command: fullCommand,
               };
             }),
+            { alreadySatisfied: apiProbeTimeoutMs > 0 && reachableWithoutPrerequisites },
           ).pipe(
             Effect.mapError((error) =>
               isPrerequisiteRunError(error)

package/src/shared/prerequisites/guardian.ts

@@ -78,32 +78,38 @@ export async function stopWhenIdle(
   const deadline = now() + init.disconnectTimeoutMs;
   let evidence = "VPN stop did not produce confirmed disconnected status.";
   try {
-    let remaining = deadline - now();
+    const 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.";
+        evidence = `VPN stop command failed (exit ${stop.exitCode}); ownership is unknown and stop will not be retried.`;
       } else {
-        const confirmDisconnected = async (): Promise<boolean> => {
+        const stillConnected =
+          "VPN still reported connected after stop when the disconnect deadline expired.";
+        const confirmDisconnected = async (): Promise<true | string> => {
           const statusRemaining = deadline - now();
-          if (statusRemaining <= 0) return false;
+          if (statusRemaining <= 0) {
+            return "VPN stop was dispatched, but the disconnect deadline expired before status could be confirmed.";
+          }
           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;
+          if (connected === undefined) {
+            return status.exitCode === 0
+              ? "VPN status output after stop was unparseable; ownership is unknown."
+              : `VPN status command after stop failed (exit ${status.exitCode}); ownership is unknown.`;
+          }
           const sleepRemaining = deadline - now();
-          if (sleepRemaining <= 0) return false;
+          if (sleepRemaining <= 0) return stillConnected;
           await sleep(Math.min(250, sleepRemaining));
-          remaining = deadline - now();
-          return remaining > 0 && confirmDisconnected();
+          return deadline - now() > 0 ? confirmDisconnected() : stillConnected;
         };
-        if (await confirmDisconnected()) {
+        const confirmed = await confirmDisconnected();
+        if (confirmed === true) {
           store.commitStop(guard, true, "VPN stop confirmed disconnected.", now());
           return;
         }
-        evidence = "VPN status failed, stayed connected, or was unparseable after stop.";
+        evidence = confirmed;
       }
     } else {
       evidence = "VPN disconnect deadline expired before a command could safely start.";

package/src/shared/prerequisites/runtime.ts

@@ -742,6 +742,8 @@ export const runWithProfilePrerequisites = <A, E, CommandError>(
   runCommand: PrerequisiteCommandRunner<CommandError>,
   effect: Effect.Effect<A, E, never>,
   options?: {
+    /** Caller proved the target is already reachable: skip the VPN entirely (no status, no lease). */
+    alreadySatisfied?: boolean;
     tryWithoutPrerequisites?: boolean;
     runGuardianInProcess?: boolean;
     guardianSpawn?: GuardianSpawner;
@@ -750,7 +752,7 @@ export const runWithProfilePrerequisites = <A, E, CommandError>(
   const vpnPrerequisites = normalizeProfilePrerequisites(profile).filter(
     (prerequisite) => prerequisite.type === "vpn",
   );
-  if (vpnPrerequisites.length === 0) return effect;
+  if (vpnPrerequisites.length === 0 || options?.alreadySatisfied === true) return effect;
 
   return Effect.gen(function* () {
     const tryDirect = () => effect.pipe(Effect.result);