@blogic-cz/agent-tools 0.14.58 → 0.14.60

package/README.md

@@ -225,6 +225,7 @@ bun audit-tool list --limit 20
 
 ```bash
 bun gh-tool pr review-triage   # interactive summary of PR feedback
+bun gh-tool pr watch --prs 12,34 --format jsonl # transition-only multi-PR CI stream
 bun k8s-tool pods --env test   # list pods (structured command)
 ```
 
@@ -251,6 +252,24 @@ export default { handleToolExecuteBefore };
 
 All tools support `--help` for full usage documentation. Legacy `agent-tools-*` binary names (e.g. `agent-tools-gh`) still work for backwards compatibility.
 
+### 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 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`; `checkId` is nullable and reserved for actual check-run IDs. 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. `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.
+
+Useful flows:
+
+```bash
+bun gh-tool pr checks-failed --pr 123 --with-logs --format json # includes diagnosis
+bun gh-tool pr rerun-checks --pr 123 --failed-only --watch --timeout 600
+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
+# Optional --pr/--thread-id retain legacy flow and are validated before either mutation.
+```
+
+Reruns preflight every target before mutation and fail closed with `evidence_unavailable` when attempt jobs or logs cannot be read. Failed jobs use one `gh run rerun RUN --failed` mutation per workflow run. Without `--watch`, output returns current attempt metadata immediately; with `--watch`, discovery and watching share one absolute `--timeout` deadline and report `discovery_timeout` or `watch_timeout` with latest attempt state. Repeated matching pre-test infrastructure failures return `escalation_required` without mutation. See [`skills/gh-tool/SKILL.md`](skills/gh-tool/SKILL.md) for operating guidance; this section is canonical for added output fields.
+
 `audit-tool` reads the same SQLite file the wrappers write to. By default that file lives at `~/.agent-tools/audit.sqlite`, and you can override both path and retention per repo with the global `audit` config section.
 
 ## Audit Logging

package/package.json

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

@@ -44,6 +44,7 @@ import {
   prReviewTriageBatchCommand,
   prReviewTriageCommand,
   prWaitMergeableCommand,
+  prWatchCommand,
 } from "./pr/index";
 import { branchRenameCommand } from "./branch";
 import {
@@ -94,6 +95,7 @@ const prCommand = Command.make("pr", {}).pipe(
     prSubmitReviewCommand,
     prChecksCommand,
     prChecksFailedCommand,
+    prWatchCommand,
     prRerunChecksCommand,
     prReplyAndResolveCommand,
     prReviewTriageCommand,

package/src/gh-tool/issue/core.ts

@@ -82,6 +82,8 @@ const fetchAllRestPages = Effect.fn("issue.fetchAllRestPages")(function* <T>(
 
 const mapRawIssueComment = (comment: RawIssueComment): IssueComment => ({
   id: comment.id as IssueCommentId,
+  commitSha: null,
+  feedbackOrigin: "unknown",
   author: comment.user.login,
   body: comment.body,
   createdAt: comment.created_at as IsoTimestamp,

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

@@ -29,6 +29,7 @@ import {
 
 import {
   closePR,
+  collectWithStableState,
   createPR,
   detectPRStatus,
   editPR,
@@ -38,6 +39,7 @@ import {
   listPRs,
   mergePR,
   rerunChecks,
+  watchPRs,
   viewPR,
   waitForMergeable,
 } from "./core";
@@ -52,6 +54,7 @@ import {
   fetchThreads,
   postIssueComment,
   replyToComment,
+  replyAndResolveComment,
   resolveThread,
   submitPendingReview,
 } from "./review";
@@ -95,25 +98,115 @@ export const classifyReviewTriage = (
   return { status: reasons.length > 0 ? "needs_investigation" : "clear", reasons };
 };
 
-export const parsePrNumbers = (input: string): readonly number[] =>
-  input
-    .split(",")
-    .map((part) => Number.parseInt(part.trim(), 10))
-    .filter((number) => Number.isInteger(number) && number > 0);
+const MAX_BATCH_PRS = 50;
+
+export const parsePrNumbers = (
+  input: string,
+): Effect.Effect<readonly number[], GitHubCommandError> => {
+  const tokens = input.split(",").map((part) => part.trim());
+  if (tokens.some((token) => !/^\d+$/.test(token) || Number(token) < 1)) {
+    return Effect.fail(emptyBatchError(input));
+  }
+  const numbers = [...new Set(tokens.map(Number))];
+  if (numbers.length > MAX_BATCH_PRS) {
+    return Effect.fail(
+      new GitHubCommandError({
+        message: `--prs supports at most ${MAX_BATCH_PRS} unique PRs`,
+        command: "gh pr --prs",
+        exitCode: 1,
+        stderr: "",
+        hint: `Split the request into batches of at most ${MAX_BATCH_PRS} PRs.`,
+      }),
+    );
+  }
+  return Effect.succeed(numbers);
+};
+
+const withStableHead = Effect.fn("pr.withStableHead")(function* <A, E, R>(
+  pr: number | null,
+  collect: (pr: number, headSha: string | null) => Effect.Effect<A, E, R>,
+  context: { operation: string; command: string },
+) {
+  const initial = yield* viewPR(pr);
+  const snapshot = yield* collectWithStableState(
+    initial,
+    (info) => collect(info.number, info.headSha),
+    (info) => viewPR(info.number),
+    (before, after) => after.headSha === before.headSha,
+  );
+  if (snapshot !== null) return { info: snapshot.state, value: snapshot.value };
+  return yield* Effect.fail(
+    new GitHubCommandError({
+      message: `PR head changed repeatedly while collecting ${context.operation}`,
+      command: context.command,
+      exitCode: 1,
+      stderr: "",
+      nextCommand: context.command,
+      retryable: true,
+    }),
+  );
+});
+
+export const fetchCurrentThreads = (
+  pr: number | null,
+  unresolvedOnly: boolean,
+  visibleOpenOnly: boolean,
+) =>
+  withStableHead(
+    pr,
+    (number, headSha) => fetchThreads(number, unresolvedOnly, visibleOpenOnly, headSha),
+    { operation: "review threads", command: "gh-tool pr threads" },
+  ).pipe(Effect.map(({ value }) => value));
+
+export const fetchCurrentComments = (pr: number | null, since: string | null) =>
+  withStableHead(pr, (number, headSha) => fetchComments(number, since, headSha), {
+    operation: "review comments",
+    command: "gh-tool pr comments",
+  }).pipe(Effect.map(({ value }) => value));
+
+export const fetchCurrentReviews = (
+  pr: number | null,
+  author: string | null,
+  bodyContains: string | null,
+  state: string | null,
+) =>
+  withStableHead(
+    pr,
+    (number, headSha) => fetchReviews(number, author, bodyContains, state, headSha),
+    { operation: "reviews", command: "gh-tool pr reviews" },
+  ).pipe(Effect.map(({ value }) => value));
+
+export const fetchCurrentFeedback = (pr: number | null) =>
+  withStableHead(pr, (number, headSha) => fetchFeedback(number, headSha), {
+    operation: "feedback",
+    command: "gh-tool pr feedback",
+  }).pipe(Effect.map(({ value }) => value));
+
+const countFeedbackOrigins = (items: ReadonlyArray<{ feedbackOrigin: string }>) => ({
+  current_head: items.filter((item) => item.feedbackOrigin === "current_head").length,
+  pre_existing: items.filter((item) => item.feedbackOrigin === "pre_existing").length,
+  unknown: items.filter((item) => item.feedbackOrigin === "unknown").length,
+});
 
 export const fetchReviewTriage = Effect.fn("pr.fetchReviewTriage")(function* (
   prNumber: number | null,
+  format: "toon" | "json" = "toon",
 ) {
-  const [info, unresolvedThreads, visibleOpenThreads, summary, checks, reviews] = yield* Effect.all(
-    [
-      viewPR(prNumber),
-      fetchThreads(prNumber, true),
-      fetchThreads(prNumber, false, true),
-      fetchDiscussionSummary(prNumber),
-      fetchChecks(prNumber, false, false, 0),
-      fetchReviews(prNumber, null, null, null),
-    ],
+  const { info, value } = yield* withStableHead(
+    prNumber,
+    (number, headSha) =>
+      Effect.all([
+        fetchThreads(number, false, false, headSha),
+        fetchDiscussionSummary(number),
+        fetchChecks(number, false, false, 0, format === "json"),
+        fetchReviews(number, null, null, null, headSha),
+        fetchComments(number, null, headSha),
+      ]),
+    { operation: "review triage", command: "gh-tool pr review-triage" },
   );
+  const [allThreads, summary, checks, reviews, inlineComments] = value;
+  const unresolvedThreads = allThreads.filter((thread) => !thread.isResolved);
+  const visibleOpenThreads = allThreads.filter((thread) => thread.isVisibleOpen);
   const classification = classifyReviewTriage(summary, checks);
 
   // Single merge-readiness verdict so agents stop re-stitching mergeable + checks + threads +
@@ -142,6 +235,12 @@ export const fetchReviewTriage = Effect.fn("pr.fetchReviewTriage")(function* (
     summary,
     checks,
     reviews,
+    inlineComments,
+    feedbackOriginCounts: {
+      reviews: countFeedbackOrigins(reviews),
+      inlineComments: countFeedbackOrigins(inlineComments),
+      threads: countFeedbackOrigins(allThreads),
+    },
   };
 });
 
@@ -165,8 +264,7 @@ export const prViewCommand = Command.make(
       Effect.gen(function* () {
         const batch = Option.getOrNull(prs);
         if (batch !== null) {
-          const numbers = parsePrNumbers(batch);
-          if (numbers.length === 0) return yield* emptyBatchError(batch);
+          const numbers = yield* parsePrNumbers(batch);
           const results = yield* Effect.all(
             numbers.map((n) => viewPR(n).pipe(Effect.map((info) => ({ pr: n, info })))),
             { concurrency: 5 },
@@ -422,7 +520,9 @@ export const prMergeCommand = Command.make(
       Flag.withDefault(false),
     ),
     deleteBranch: Flag.boolean("delete-branch").pipe(
-      Flag.withDescription("Delete branch after merge"),
+      Flag.withDescription(
+        "Delete the remote branch after merge (local/worktree cleanup is separate)",
+      ),
       Flag.withDefault(DEFAULT_DELETE_BRANCH),
     ),
     format: formatOption,
@@ -485,15 +585,16 @@ export const prChecksCommand = Command.make(
         const batch = Option.getOrNull(prs);
         if (batch !== null) {
           if (watch) {
-            yield* Console.warn(
-              "ℹ️  --watch is ignored with --prs; batch mode returns a one-shot snapshot per PR.",
-            );
+            if (format !== "json") {
+              yield* Console.warn(
+                "ℹ️  --watch is ignored with --prs; batch mode returns a one-shot snapshot per PR.",
+              );
+            }
           }
-          const numbers = parsePrNumbers(batch);
-          if (numbers.length === 0) return yield* emptyBatchError(batch);
+          const numbers = yield* parsePrNumbers(batch);
           const results = yield* Effect.all(
             numbers.map((n) =>
-              fetchChecks(n, false, failFast, timeout).pipe(
+              fetchChecks(n, false, failFast, timeout, format === "json").pipe(
                 Effect.map((checks) => ({ pr: n, checks })),
               ),
             ),
@@ -502,7 +603,13 @@ export const prChecksCommand = Command.make(
           yield* logFormatted({ count: results.length, prs: results }, format);
           return;
         }
-        const checks = yield* fetchChecksForCommand(Option.getOrNull(pr), watch, failFast, timeout);
+        const checks = yield* fetchChecksForCommand(
+          Option.getOrNull(pr),
+          watch,
+          failFast,
+          timeout,
+          format === "json",
+        );
         yield* logFormatted(checks, format);
       }),
     ),
@@ -539,6 +646,42 @@ export const prChecksFailedCommand = Command.make(
     ),
 ).pipe(Command.withDescription("Fetch only failed CI checks for a PR"));
 
+export const prWatchCommand = Command.make(
+  "watch",
+  {
+    prs: Flag.string("prs").pipe(Flag.withDescription("Comma-separated PR numbers")),
+    until: Flag.choice("until", ["terminal"]).pipe(Flag.withDefault("terminal")),
+    format: Flag.choice("format", ["jsonl"]).pipe(Flag.withDefault("jsonl")),
+    interval: Flag.integer("interval").pipe(
+      Flag.withDefault(5),
+      Flag.filter(
+        (n) => n >= 1 && n <= 60,
+        () => "--interval must be 1..60 seconds",
+      ),
+    ),
+    timeout: Flag.integer("timeout").pipe(
+      Flag.withDefault(CI_CHECK_WATCH_TIMEOUT_MS / 1000),
+      Flag.filter(
+        (n) => n >= 1,
+        () => "--timeout must be at least 1 second",
+      ),
+    ),
+    repo: repoOption,
+  },
+  ({ prs, until, interval, timeout, repo }) =>
+    withRepo(
+      repo,
+      Effect.gen(function* () {
+        const numbers = yield* parsePrNumbers(prs);
+        yield* watchPRs(
+          numbers,
+          { intervalSeconds: interval, timeoutSeconds: timeout, until },
+          (event) => Console.log(JSON.stringify(event)),
+        );
+      }),
+    ),
+).pipe(Command.withDescription("Watch several PRs; emits JSONL state transitions only"));
+
 export const prRerunChecksCommand = Command.make(
   "rerun-checks",
   {
@@ -552,13 +695,24 @@ export const prRerunChecksCommand = Command.make(
       Flag.withDefault(true),
       Flag.withDescription("Only rerun failed checks (default: true)"),
     ),
+    watch: Flag.boolean("watch").pipe(Flag.withDefault(false)),
+    timeout: Flag.integer("timeout").pipe(
+      Flag.withDefault(60),
+      Flag.filter(
+        (n) => n >= 1,
+        () => "--timeout must be at least 1 second",
+      ),
+    ),
   },
-  ({ failedOnly, format, pr, repo }) =>
+  ({ failedOnly, format, pr, repo, watch, timeout }) =>
     withRepo(
       repo,
       Effect.gen(function* () {
         const prNumber = Option.getOrNull(pr);
-        const result = yield* rerunChecks(prNumber, failedOnly);
+        const result = yield* rerunChecks(prNumber, failedOnly, {
+          watch,
+          timeoutSeconds: timeout,
+        });
         yield* logFormatted(result, format);
       }),
     ),
@@ -591,7 +745,7 @@ export const prThreadsCommand = Command.make(
       repo,
       Effect.gen(function* () {
         const prNumber = Option.getOrNull(pr);
-        const threads = yield* fetchThreads(prNumber, unresolvedOnly, visibleOpenOnly);
+        const threads = yield* fetchCurrentThreads(prNumber, unresolvedOnly, visibleOpenOnly);
         yield* logFormatted(threads, format);
       }),
     ),
@@ -621,7 +775,7 @@ export const prCommentsCommand = Command.make(
       Effect.gen(function* () {
         const prNumber = Option.getOrNull(pr);
         const sinceValue = Option.getOrNull(since);
-        const comments = yield* fetchComments(prNumber, sinceValue);
+        const comments = yield* fetchCurrentComments(prNumber, sinceValue);
         yield* logFormatted(comments, format);
       }),
     ),
@@ -679,7 +833,7 @@ export const prReviewsCommand = Command.make(
     withRepo(
       repo,
       Effect.gen(function* () {
-        const reviews = yield* fetchReviews(
+        const reviews = yield* fetchCurrentReviews(
           Option.getOrNull(pr),
           Option.getOrNull(author),
           Option.getOrNull(bodyContains),
@@ -708,7 +862,7 @@ export const prFeedbackCommand = Command.make(
     withRepo(
       repo,
       Effect.gen(function* () {
-        const feedback = yield* fetchFeedback(Option.getOrNull(pr));
+        const feedback = yield* fetchCurrentFeedback(Option.getOrNull(pr));
         yield* logFormatted(feedback, format);
       }),
     ),
@@ -971,7 +1125,7 @@ export const prReviewTriageCommand = Command.make(
       repo,
       Effect.gen(function* () {
         const prNumber = Option.getOrNull(pr);
-        const result = yield* fetchReviewTriage(prNumber);
+        const result = yield* fetchReviewTriage(prNumber, format);
         yield* logFormatted(result, format);
       }),
     ),
@@ -992,10 +1146,9 @@ export const prReviewTriageBatchCommand = Command.make(
     withRepo(
       repo,
       Effect.gen(function* () {
-        const numbers = parsePrNumbers(prs);
-        if (numbers.length === 0) return yield* emptyBatchError(prs);
+        const numbers = yield* parsePrNumbers(prs);
         const results = yield* Effect.all(
-          numbers.map((prNumber) => fetchReviewTriage(prNumber)),
+          numbers.map((prNumber) => fetchReviewTriage(prNumber, format)),
           { concurrency: "unbounded" },
         );
         yield* logFormatted(results, format);
@@ -1025,7 +1178,10 @@ export const prReplyAndResolveCommand = Command.make(
     ),
     repo: repoOption,
     threadId: Flag.string("thread-id").pipe(
-      Flag.withDescription("GraphQL node ID of the thread to resolve"),
+      Flag.withDescription(
+        "GraphQL node ID of the thread to resolve (inferred from comment when omitted)",
+      ),
+      Flag.optional,
     ),
   },
   ({ body, bodyFile, commentId, format, pr, repo, threadId }) =>
@@ -1041,13 +1197,17 @@ export const prReplyAndResolveCommand = Command.make(
           fileFlag: "--body-file",
           label: "body",
         });
-        const replyResult = yield* replyToComment(prNumber, commentId, resolvedBody);
-        const resolveResult = yield* resolveThread(threadId);
-        yield* logFormatted({ reply: replyResult, resolve: resolveResult }, format);
+        const result = yield* replyAndResolveComment(
+          prNumber,
+          commentId,
+          Option.getOrNull(threadId),
+          resolvedBody,
+        );
+        yield* logFormatted(result, format);
       }),
     ),
 ).pipe(
   Command.withDescription(
-    "Composite: reply to a review comment and resolve its thread in one call",
+    "Composite: reply to a review comment and resolve its thread (PR/thread inferred from comment)",
   ),
 );