@blogic-cz/agent-tools 0.14.62 → 0.15.2

package/src/gh-tool/service.ts

@@ -14,6 +14,41 @@ const NETWORK_ERROR_RE =
 const AUTH_401_RE = /HTTP 401|Bad credentials/i;
 const MAX_GH_RETRIES = 2;
 
+// A bare `gh` stderr tells an agent what broke but never what to do next. `hint`/`nextCommand`
+// already exist on GitHubCommandError; these fill them for the failures agents actually hit.
+const KNOWN_STDERR_HINTS: ReadonlyArray<{
+  readonly re: RegExp;
+  readonly hint: string;
+  readonly nextCommand?: string;
+}> = [
+  {
+    re: /no checks reported/i,
+    hint: "The head commit carries no check runs yet. Wait for CI to register, or trigger the workflow when the push event was dropped.",
+    nextCommand: "agent-tools-gh pr trigger-checks --pr <number> --workflow <file.yml>",
+  },
+  {
+    re: /no commits between/i,
+    hint: "Head and base point at the same commit. Push a commit before opening or updating the PR.",
+  },
+  {
+    re: /already exists/i,
+    hint: "The resource already exists. Fetch the existing one and update it instead of creating another.",
+  },
+  {
+    re: /pending review/i,
+    hint: "A pending (unsubmitted) review blocks this mutation. Inspect its contents and submit or discard it before retrying.",
+    nextCommand: "agent-tools-gh pr reviews --pr <number>",
+  },
+  {
+    re: /workflow does not have 'workflow_dispatch'/i,
+    hint: "This workflow cannot be dispatched manually. Re-run an existing run instead.",
+    nextCommand: "agent-tools-gh workflow rerun --run <run-id>",
+  },
+];
+
+const resolveStderrHint = (stderr: string) =>
+  KNOWN_STDERR_HINTS.find((entry) => entry.re.test(stderr));
+
 // Only retry verbs that are unambiguously idempotent reads — never replay a mutation on a timeout.
 const READ_VERBS = new Set(["view", "list", "checks", "status", "diff"]);
 const MUTATION_TOKENS =
@@ -204,11 +239,14 @@ export class GitHubService extends Context.Service<
               });
             }
 
+            const known = resolveStderrHint(result.stderr);
             return yield* new GitHubCommandError({
               message: result.stderr,
               command: `gh ${args.join(" ")}`,
               exitCode: result.exitCode,
               stderr: result.stderr,
+              ...(known === undefined ? {} : { hint: known.hint }),
+              ...(known?.nextCommand === undefined ? {} : { nextCommand: known.nextCommand }),
             });
           }
 

package/src/gh-tool/workflow.ts

@@ -1,5 +1,5 @@
 import { Command, Flag, Param } from "effect/unstable/cli";
-import { Console, Effect, Option } from "effect";
+import { Console, Duration, Effect, Option } from "effect";
 
 import { formatOption, logFormatted } from "#shared";
 import { CI_CHECK_WATCH_TIMEOUT_MS } from "#gh/config";
@@ -241,6 +241,65 @@ export const dispatchWorkflow = Effect.fn("workflow.dispatchWorkflow")(function*
   };
 });
 
+export type DispatchedRun = {
+  databaseId: number;
+  headSha: string;
+  status: string;
+  conclusion: string | null;
+  url: string;
+};
+
+const DISPATCH_DISCOVERY_ATTEMPTS = 8;
+const DISPATCH_DISCOVERY_INTERVAL_MS = 2000;
+
+export const listDispatchedRuns = Effect.fn("workflow.listDispatchedRuns")(function* (opts: {
+  workflow: string;
+  ref: string;
+  repo: string | null;
+}) {
+  const gh = yield* GitHubService;
+  const args = [
+    "run",
+    "list",
+    "--json",
+    "databaseId,headSha,status,conclusion,url",
+    "--limit",
+    "20",
+    "--workflow",
+    opts.workflow,
+    "--branch",
+    opts.ref,
+    "--event",
+    "workflow_dispatch",
+  ];
+
+  if (opts.repo !== null) {
+    args.push("--repo", opts.repo);
+  }
+
+  return yield* gh
+    .runGhJson<DispatchedRun[]>(args)
+    .pipe(Effect.catchTag("GitHubCommandError", () => Effect.succeed<DispatchedRun[]>([])));
+});
+
+// `gh workflow run` and the REST dispatch endpoint both return an empty body — there is no
+// dispatch-to-run mapping. Polling the run list for an id absent before the dispatch is the only
+// way to name the run we just created, and an unnamed run cannot be watched or verified.
+export const discoverDispatchedRun = Effect.fn("workflow.discoverDispatchedRun")(function* (opts: {
+  workflow: string;
+  ref: string;
+  repo: string | null;
+  knownRunIds: ReadonlySet<number>;
+}) {
+  for (let attempt = 0; attempt < DISPATCH_DISCOVERY_ATTEMPTS; attempt += 1) {
+    const runs = yield* listDispatchedRuns(opts);
+    const created = runs.find((run) => !opts.knownRunIds.has(run.databaseId));
+    if (created !== undefined) return created;
+    yield* Effect.sleep(Duration.millis(DISPATCH_DISCOVERY_INTERVAL_MS));
+  }
+  return null;
+});
+
 // `gh run watch` has no native timeout (observed hanging 36 min). Block for the caller's --timeout,
 // then fall back to a one-shot snapshot so a timeout never returns nothing.
 const DEFAULT_WATCH_RUN_TIMEOUT_SECONDS = CI_CHECK_WATCH_TIMEOUT_MS / 1000;
@@ -781,13 +840,32 @@ export const workflowRunCommand = Command.make(
   ({ field, format, ref, repo, workflow }) =>
     Effect.gen(function* () {
       const resolvedRepo = yield* resolveRepoArg(repo);
+      const before = yield* listDispatchedRuns({ workflow, ref, repo: resolvedRepo });
       const result = yield* dispatchWorkflow({
         workflow,
         ref,
         fields: field,
         repo: resolvedRepo,
       });
-      yield* logFormatted(result, format);
+      const created = yield* discoverDispatchedRun({
+        workflow,
+        ref,
+        repo: resolvedRepo,
+        knownRunIds: new Set(before.map((run) => run.databaseId)),
+      });
+      yield* logFormatted(
+        {
+          ...result,
+          runId: created?.databaseId ?? null,
+          headSha: created?.headSha ?? null,
+          url: created?.url ?? null,
+          nextCommand:
+            created === null
+              ? `agent-tools-gh workflow list --workflow ${workflow} --branch ${ref}`
+              : `agent-tools-gh workflow watch --run ${created.databaseId}`,
+        },
+        format,
+      );
     }),
 ).pipe(Command.withDescription("Dispatch a workflow_dispatch workflow run"));
 

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 });
+  });
+}