@blogic-cz/agent-tools 0.1.0 → 0.2.1

package/src/config/loader.ts

@@ -65,6 +65,7 @@ const AgentToolsConfigSchema = Schema.Struct({
     }),
   ),
   credentialGuard: Schema.optionalKey(CredentialGuardConfigSchema),
+  defaultEnvironment: Schema.optionalKey(Schema.String),
 });
 
 async function findConfigFile(startDirectory: string = process.cwd()): Promise<string | undefined> {
@@ -72,11 +73,13 @@ async function findConfigFile(startDirectory: string = process.cwd()): Promise<s
 
   while (true) {
     const json5Path = `${currentDirectory}/agent-tools.json5`;
+    // eslint-disable-next-line eslint/no-await-in-loop -- sequential directory walk, each iteration may short-circuit
     if (await Bun.file(json5Path).exists()) {
       return json5Path;
     }
 
     const jsonPath = `${currentDirectory}/agent-tools.json`;
+    // eslint-disable-next-line eslint/no-await-in-loop -- sequential directory walk, each iteration may short-circuit
     if (await Bun.file(jsonPath).exists()) {
       return jsonPath;
     }
@@ -106,6 +109,7 @@ export async function loadConfig(): Promise<AgentToolsConfig | undefined> {
       `Invalid agent-tools config at ${configPath}: ${
         error instanceof Error ? error.message : String(error)
       }`,
+      { cause: error },
     );
   }
 }
@@ -168,3 +172,7 @@ export function getToolConfig<T>(
     `Multiple ${section} profiles found: [${keys.join(", ")}]. Use --profile <name> to select one.`,
   );
 }
+
+export function getDefaultEnvironment(config: AgentToolsConfig | undefined): string | undefined {
+  return config?.defaultEnvironment;
+}

package/src/config/types.ts

@@ -79,4 +79,6 @@ export type AgentToolsConfig = {
   };
   /** Global credential guard config (merged with built-in defaults, not per-profile) */
   credentialGuard?: CredentialGuardConfig;
+  /** Optional default environment name (local|test|prod) used by tools when no --env flag is provided */
+  defaultEnvironment?: string;
 };

package/src/credential-guard/index.ts

@@ -14,7 +14,7 @@
  * at infrastructure level (K8s RBAC, file permissions, etc.)
  */
 
-import type { CliToolOverride, CredentialGuardConfig } from "../config/types.ts";
+import type { CliToolOverride, CredentialGuardConfig } from "#src/config/types.ts";
 
 // ============================================================================
 // TYPES
@@ -108,6 +108,7 @@ const SECRET_PATTERNS = [
       /(?:secret|token|password|passwd|pwd)["  \t:=]+["']?(?!\$\{|process\.env|z\.|generate|create|read|get|fetch|import|export|const|function|return|Schema)[^\s"']{32,}["']?/i,
   },
   {
+    // eslint-disable-next-line eslint/no-useless-concat -- intentionally split to avoid credential guard self-detection
     name: "Priv" + "ate Key",
     pattern: new RegExp("-----BEGIN.*PRIVATE KEY-----"),
   },

package/src/db-tool/config-service.ts

@@ -1,7 +1,7 @@
 import { Effect, Layer, ServiceMap } from "effect";
 
-import { ConfigService, getToolConfig } from "../config";
-import type { DatabaseConfig } from "../config";
+import { ConfigService, getToolConfig } from "#src/config";
+import type { DatabaseConfig } from "#src/config";
 
 /**
  * DbConfigService wraps the resolved DatabaseConfig for the selected profile.

package/src/db-tool/errors.ts

@@ -5,6 +5,9 @@ export class DbConnectionError extends Schema.TaggedErrorClass<DbConnectionError
   {
     message: Schema.String,
     environment: Schema.String,
+    hint: Schema.optionalKey(Schema.String),
+    nextCommand: Schema.optionalKey(Schema.String),
+    retryable: Schema.optionalKey(Schema.Boolean),
   },
 ) {}
 
@@ -12,16 +15,25 @@ export class DbQueryError extends Schema.TaggedErrorClass<DbQueryError>()("DbQue
   message: Schema.String,
   sql: Schema.String,
   stderr: Schema.optionalKey(Schema.String),
+  hint: Schema.optionalKey(Schema.String),
+  nextCommand: Schema.optionalKey(Schema.String),
+  retryable: Schema.optionalKey(Schema.Boolean),
 }) {}
 
 export class DbTunnelError extends Schema.TaggedErrorClass<DbTunnelError>()("DbTunnelError", {
   message: Schema.String,
   port: Schema.Number,
+  hint: Schema.optionalKey(Schema.String),
+  nextCommand: Schema.optionalKey(Schema.String),
+  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>()(
@@ -29,6 +41,9 @@ export class DbMutationBlockedError extends Schema.TaggedErrorClass<DbMutationBl
   {
     message: Schema.String,
     environment: Schema.String,
+    hint: Schema.optionalKey(Schema.String),
+    nextCommand: Schema.optionalKey(Schema.String),
+    retryable: Schema.optionalKey(Schema.Boolean),
   },
 ) {}
 

package/src/db-tool/index.ts

@@ -5,9 +5,10 @@ import { Console, Effect, Layer, Option } from "effect";
 
 import type { SchemaMode } from "./types";
 
-import { formatOption, formatOutput, renderCauseToStderr, VERSION } from "../shared";
-import { ConfigServiceLayer } from "../config";
+import { formatOption, formatOutput, renderCauseToStderr, VERSION } from "#src/shared";
+import { ConfigService, ConfigServiceLayer, getDefaultEnvironment } from "#src/config";
 import { makeDbConfigLayer } from "./config-service";
+import { DbConnectionError } from "./errors";
 import { DbService } from "./service";
 
 // Extract --profile from argv before @effect/cli parsing
@@ -15,11 +16,45 @@ import { DbService } from "./service";
 const profileIndex = process.argv.indexOf("--profile");
 const profileArg = profileIndex !== -1 ? process.argv[profileIndex + 1] : undefined;
 
+/**
+ * Resolve environment from explicit --env flag, config defaultEnvironment, or fail with hint.
+ */
+const resolveEnv = (envOption: Option.Option<string>) =>
+  Effect.gen(function* () {
+    const explicit = Option.getOrUndefined(envOption);
+    if (explicit) return explicit;
+
+    const config = yield* ConfigService;
+    const defaultEnv = getDefaultEnvironment(config);
+
+    if (defaultEnv === "prod") {
+      return yield* new DbConnectionError({
+        message:
+          "Implicit prod access blocked. Config defaultEnvironment is 'prod' but --env was not passed explicitly.",
+        environment: "(prod-safety)",
+        hint: "Pass --env prod explicitly to confirm production access, or change defaultEnvironment to a non-prod value.",
+        nextCommand: 'agent-tools-db sql --env prod --sql "SELECT 1"',
+      });
+    }
+
+    if (defaultEnv) return defaultEnv;
+
+    return yield* new DbConnectionError({
+      message:
+        "No environment specified. Use --env <name> or set defaultEnvironment in agent-tools.json5.",
+      environment: "(not specified)",
+      hint: 'Set defaultEnvironment in agent-tools.json5 (e.g. defaultEnvironment: "local") or pass --env explicitly.',
+      nextCommand: 'agent-tools-db sql --env local --sql "SELECT 1"',
+    });
+  });
+
 const sqlCommand = Command.make(
   "sql",
   {
-    env: Flag.string("env").pipe(
-      Flag.withDescription("Target database environment name (e.g. local, test, prod)"),
+    env: Flag.optional(Flag.string("env")).pipe(
+      Flag.withDescription(
+        "Target database environment name (e.g. local, test, prod). Falls back to defaultEnvironment in config.",
+      ),
     ),
     sql: Flag.string("sql").pipe(Flag.withDescription("SQL query to execute")),
     format: formatOption,
@@ -29,8 +64,9 @@ const sqlCommand = Command.make(
   },
   ({ env, sql, format }) =>
     Effect.gen(function* () {
+      const resolvedEnv = yield* resolveEnv(env);
       const db = yield* DbService;
-      const result = yield* db.executeQuery(env, sql);
+      const result = yield* db.executeQuery(resolvedEnv, sql);
       yield* Console.log(formatOutput(result, format));
     }),
 ).pipe(Command.withDescription("Execute a SQL query"));
@@ -38,8 +74,10 @@ const sqlCommand = Command.make(
 const schemaCommand = Command.make(
   "schema",
   {
-    env: Flag.string("env").pipe(
-      Flag.withDescription("Target database environment name (e.g. local, test, prod)"),
+    env: Flag.optional(Flag.string("env")).pipe(
+      Flag.withDescription(
+        "Target database environment name (e.g. local, test, prod). Falls back to defaultEnvironment in config.",
+      ),
     ),
     mode: Flag.choice("mode", ["tables", "columns", "full", "relationships"]).pipe(
       Flag.withDescription(
@@ -57,9 +95,10 @@ const schemaCommand = Command.make(
   },
   ({ env, mode, table, format }) =>
     Effect.gen(function* () {
+      const resolvedEnv = yield* resolveEnv(env);
       const db = yield* DbService;
       const result = yield* db.executeSchemaQuery(
-        env,
+        resolvedEnv,
         mode as SchemaMode,
         Option.getOrUndefined(table),
       );

package/src/db-tool/types.ts

@@ -1,4 +1,4 @@
-import type { Environment, OutputFormat } from "../shared";
+import type { Environment, OutputFormat } from "#src/shared";
 export type { Environment, OutputFormat };
 
 export type SchemaMode = "tables" | "columns" | "full" | "relationships";

package/src/gh-tool/errors.ts

@@ -7,6 +7,9 @@ export class GitHubCommandError extends Schema.TaggedErrorClass<GitHubCommandErr
     command: Schema.String,
     exitCode: Schema.Number,
     stderr: Schema.String,
+    hint: Schema.optionalKey(Schema.String),
+    nextCommand: Schema.optionalKey(Schema.String),
+    retryable: Schema.optionalKey(Schema.Boolean),
   },
 ) {}
 
@@ -16,11 +19,17 @@ export class GitHubNotFoundError extends Schema.TaggedErrorClass<GitHubNotFoundE
     message: Schema.String,
     identifier: Schema.String,
     resource: Schema.String,
+    hint: Schema.optionalKey(Schema.String),
+    nextCommand: Schema.optionalKey(Schema.String),
+    retryable: Schema.optionalKey(Schema.Boolean),
   },
 ) {}
 
 export class GitHubAuthError extends Schema.TaggedErrorClass<GitHubAuthError>()("GitHubAuthError", {
   message: Schema.String,
+  hint: Schema.optionalKey(Schema.String),
+  nextCommand: Schema.optionalKey(Schema.String),
+  retryable: Schema.optionalKey(Schema.Boolean),
 }) {}
 
 export class GitHubMergeError extends Schema.TaggedErrorClass<GitHubMergeError>()(
@@ -28,6 +37,9 @@ export class GitHubMergeError extends Schema.TaggedErrorClass<GitHubMergeError>(
   {
     message: Schema.String,
     reason: Schema.Literals(["conflicts", "checks_failing", "branch_protected", "unknown"]),
+    hint: Schema.optionalKey(Schema.String),
+    nextCommand: Schema.optionalKey(Schema.String),
+    retryable: Schema.optionalKey(Schema.Boolean),
   },
 ) {}
 
@@ -36,6 +48,9 @@ export class GitHubTimeoutError extends Schema.TaggedErrorClass<GitHubTimeoutErr
   {
     message: Schema.String,
     timeoutMs: Schema.Number,
+    hint: Schema.optionalKey(Schema.String),
+    nextCommand: Schema.optionalKey(Schema.String),
+    retryable: Schema.optionalKey(Schema.Boolean),
   },
 ) {}
 

package/src/gh-tool/index.ts

@@ -3,7 +3,7 @@ import { Command } from "effect/unstable/cli";
 import { BunRuntime, BunServices } from "@effect/platform-bun";
 import { Effect, Layer } from "effect";
 
-import { renderCauseToStderr, VERSION } from "../shared";
+import { renderCauseToStderr, VERSION } from "#src/shared";
 import {
   issueListCommand,
   issueViewCommand,
@@ -30,6 +30,8 @@ import {
   prChecksCommand,
   prChecksFailedCommand,
   prRerunChecksCommand,
+  prReplyAndResolveCommand,
+  prReviewTriageCommand,
 } from "./pr/index";
 import { repoInfoCommand, repoListCommand, repoSearchCodeCommand } from "./repo";
 import { GitHubService } from "./service";
@@ -64,6 +66,8 @@ const prCommand = Command.make("pr", {}).pipe(
     prChecksCommand,
     prChecksFailedCommand,
     prRerunChecksCommand,
+    prReplyAndResolveCommand,
+    prReviewTriageCommand,
   ]),
 );
 

package/src/gh-tool/issue.ts

@@ -1,7 +1,7 @@
 import { Command, Flag } from "effect/unstable/cli";
 import { Effect, Option } from "effect";
 
-import { formatOption, logFormatted } from "../shared";
+import { formatOption, logFormatted } from "#src/shared";
 import { GitHubCommandError } from "./errors";
 import { GitHubService } from "./service";
 

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

@@ -1,15 +1,15 @@
 import { Command, Flag } from "effect/unstable/cli";
 import { Effect, Option } from "effect";
 
-import type { PRStatusResult } from "../types";
+import type { PRStatusResult } from "#src/gh-tool/types";
 
-import { formatOption, logFormatted } from "../../shared";
+import { formatOption, logFormatted } from "#src/shared";
 import {
   CI_CHECK_WATCH_TIMEOUT_MS,
   DEFAULT_DELETE_BRANCH,
   DEFAULT_MERGE_STRATEGY,
   MERGE_STRATEGIES,
-} from "../config";
+} from "#src/gh-tool/config";
 
 import {
   createPR,
@@ -430,3 +430,58 @@ export const prSubmitReviewCommand = Command.make(
     "Submit a pending review as COMMENT (auto-detects your pending review if --review-id is omitted)",
   ),
 );
+
+export const prReviewTriageCommand = Command.make(
+  "review-triage",
+  {
+    format: formatOption,
+    pr: Flag.integer("pr").pipe(
+      Flag.withDescription("PR number (default: current branch PR)"),
+      Flag.optional,
+    ),
+  },
+  ({ format, pr }) =>
+    Effect.gen(function* () {
+      const prNumber = Option.getOrNull(pr);
+      const [info, threads, summary, checks] = yield* Effect.all([
+        viewPR(prNumber),
+        fetchThreads(prNumber, true),
+        fetchDiscussionSummary(prNumber),
+        fetchChecks(prNumber, false, false, 0),
+      ]);
+      yield* logFormatted({ info, unresolvedThreads: threads, summary, checks }, format);
+    }),
+).pipe(
+  Command.withDescription(
+    "Composite: PR info + unresolved threads + discussion summary + checks status in one call",
+  ),
+);
+
+export const prReplyAndResolveCommand = Command.make(
+  "reply-and-resolve",
+  {
+    body: Flag.string("body").pipe(Flag.withDescription("Reply body text")),
+    commentId: Flag.integer("comment-id").pipe(
+      Flag.withDescription("ID of the comment to reply to"),
+    ),
+    format: formatOption,
+    pr: Flag.integer("pr").pipe(
+      Flag.withDescription("PR number (default: current branch PR)"),
+      Flag.optional,
+    ),
+    threadId: Flag.string("thread-id").pipe(
+      Flag.withDescription("GraphQL node ID of the thread to resolve"),
+    ),
+  },
+  ({ body, commentId, format, pr, threadId }) =>
+    Effect.gen(function* () {
+      const prNumber = Option.getOrNull(pr);
+      const replyResult = yield* replyToComment(prNumber, commentId, body);
+      const resolveResult = yield* resolveThread(threadId);
+      yield* logFormatted({ reply: replyResult, resolve: resolveResult }, format);
+    }),
+).pipe(
+  Command.withDescription(
+    "Composite: reply to a review comment and resolve its thread in one call",
+  ),
+);

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

@@ -1,9 +1,15 @@
 import { Console, Effect, Option } from "effect";
 
-import type { BranchPRDetail, CheckResult, MergeResult, MergeStrategy, PRInfo } from "../types";
+import type {
+  BranchPRDetail,
+  CheckResult,
+  MergeResult,
+  MergeStrategy,
+  PRInfo,
+} from "#src/gh-tool/types";
 
-import { GitHubCommandError, GitHubMergeError, GitHubTimeoutError } from "../errors";
-import { GitHubService } from "../service";
+import { GitHubCommandError, GitHubMergeError, GitHubTimeoutError } from "#src/gh-tool/errors";
+import { GitHubService } from "#src/gh-tool/service";
 
 import type { ButStatusJson, PRViewJsonResult } from "./helpers";
 import { runLocalCommand } from "./helpers";
@@ -155,7 +161,7 @@ export const detectPRStatus = Effect.fn("pr.detectPRStatus")(function* () {
     { concurrency: "unbounded" },
   );
 
-  const foundPrs = branchResults.filter((r) => r.openPr !== null).map((r) => r.openPr!);
+  const foundPrs = branchResults.flatMap((r) => (r.openPr === null ? [] : [r.openPr]));
 
   if (foundPrs.length === 0) {
     const branchDetails: BranchPRDetail[] = branchResults.map((r) => ({
@@ -172,7 +178,7 @@ export const detectPRStatus = Effect.fn("pr.detectPRStatus")(function* () {
   if (foundPrs.length === 1) {
     return {
       mode: "single" as const,
-      pr: foundPrs[0]!,
+      pr: foundPrs[0] as PRInfo,
     };
   }
 
@@ -205,7 +211,11 @@ export const createPR = Effect.fn("pr.createPR")(function* (opts: {
           "--limit",
           "1",
         ])
-        .pipe(Effect.map((prs) => (prs.length > 0 ? Option.some(prs[0]!) : Option.none())))
+        .pipe(
+          Effect.map((prs) =>
+            prs.length > 0 ? Option.some(prs[0] as PRInfo) : Option.none<PRInfo>(),
+          ),
+        )
     : gh
         .runGhJson<{ number: number; url: string }>(["pr", "view", "--json", "number,url"])
         .pipe(Effect.option);
@@ -258,7 +268,7 @@ export const createPR = Effect.fn("pr.createPR")(function* (opts: {
     "1",
   ]);
   if (prs.length > 0) {
-    return prs[0]!;
+    return prs[0] as PRInfo;
   }
 
   return yield* Effect.fail(
@@ -324,6 +334,8 @@ export const mergePR = Effect.fn("pr.mergePR")(function* (opts: {
           new GitHubMergeError({
             message: `PR #${opts.pr} has merge conflicts`,
             reason: "conflicts",
+            hint: "Resolve merge conflicts locally, push the fix, then retry the merge.",
+            nextCommand: `gh pr diff ${opts.pr}`,
           }),
         );
       }
@@ -333,6 +345,9 @@ export const mergePR = Effect.fn("pr.mergePR")(function* (opts: {
           new GitHubMergeError({
             message: `PR #${opts.pr} has failing required checks`,
             reason: "checks_failing",
+            hint: "Wait for CI checks to pass or investigate failures before merging.",
+            nextCommand: `agent-tools-gh pr checks --pr ${opts.pr}`,
+            retryable: true,
           }),
         );
       }
@@ -342,6 +357,7 @@ export const mergePR = Effect.fn("pr.mergePR")(function* (opts: {
           new GitHubMergeError({
             message: `PR #${opts.pr} targets a protected branch`,
             reason: "branch_protected",
+            hint: "This branch has protection rules. Ensure required reviews and checks are satisfied, or ask a repo admin.",
           }),
         );
       }
@@ -350,6 +366,8 @@ export const mergePR = Effect.fn("pr.mergePR")(function* (opts: {
         new GitHubMergeError({
           message: `Failed to merge PR #${opts.pr}: ${error.stderr}`,
           reason: "unknown",
+          hint: "Check the PR state and branch protections. The PR may already be merged or closed.",
+          nextCommand: `agent-tools-gh pr view --pr ${opts.pr}`,
         }),
       );
     }),
@@ -426,6 +444,9 @@ export const fetchChecks = Effect.fn("pr.fetchChecks")(function* (
             new GitHubTimeoutError({
               message: `CI check monitoring timed out after ${timeoutSeconds}s`,
               timeoutMs,
+              hint: "CI checks are still running. Retry with a longer --timeout or check status manually.",
+              nextCommand: `agent-tools-gh pr checks${pr !== null ? ` --pr ${pr}` : ""}`,
+              retryable: true,
             }),
           ),
       }),

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

@@ -1,7 +1,7 @@
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
 import { Effect, Stream } from "effect";
 
-import { GitHubCommandError } from "../errors";
+import { GitHubCommandError } from "#src/gh-tool/errors";
 
 export type LocalCommandResult = {
   stdout: string;

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

@@ -11,9 +11,11 @@ export {
   prMergeCommand,
   prReplyCommand,
   prRerunChecksCommand,
+  prReplyAndResolveCommand,
   prResolveCommand,
   prStatusCommand,
   prSubmitReviewCommand,
   prThreadsCommand,
+  prReviewTriageCommand,
   prViewCommand,
 } from "./commands";

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

@@ -7,10 +7,10 @@ import type {
   IsoTimestamp,
   ReviewComment,
   ReviewThread,
-} from "../types";
+} from "#src/gh-tool/types";
 
-import { GitHubCommandError } from "../errors";
-import { GitHubService } from "../service";
+import { GitHubCommandError } from "#src/gh-tool/errors";
+import { GitHubService } from "#src/gh-tool/service";
 
 import { viewPR } from "./core";
 
@@ -190,9 +190,12 @@ export const fetchThreads = Effect.fn("pr.fetchThreads")(function* (
   const threads = response.repository.pullRequest.reviewThreads.nodes;
 
   const mapped: ReviewThread[] = threads
-    .filter((node) => node.comments.nodes.length > 0)
     .map((node) => {
-      const comment = node.comments.nodes[0]!;
+      const comment = node.comments.nodes[0];
+      if (!comment) {
+        return null;
+      }
+
       return {
         threadId: node.id,
         commentId: comment.databaseId,
@@ -201,7 +204,8 @@ export const fetchThreads = Effect.fn("pr.fetchThreads")(function* (
         body: comment.body,
         isResolved: node.isResolved,
       };
-    });
+    })
+    .filter((thread): thread is ReviewThread => thread !== null);
 
   return unresolvedOnly ? mapped.filter((t) => !t.isResolved) : mapped;
 });

package/src/gh-tool/repo.ts

@@ -1,7 +1,7 @@
 import { Command, Flag } from "effect/unstable/cli";
 import { Effect, Option } from "effect";
 
-import { formatOption, logFormatted } from "../shared";
+import { formatOption, logFormatted } from "#src/shared";
 import { GitHubCommandError } from "./errors";
 import { GitHubService } from "./service";
 

package/src/gh-tool/service.ts

@@ -66,6 +66,8 @@ export class GitHubService extends ServiceMap.Service<
                   command: `gh ${args.join(" ")}`,
                   exitCode: -1,
                   stderr: `Command execution failed: ${String(platformError)}`,
+                  hint: "Ensure the 'gh' CLI is installed and available on PATH.",
+                  nextCommand: "gh --version",
                 }),
             ),
           );
@@ -80,6 +82,8 @@ export class GitHubService extends ServiceMap.Service<
             ) {
               return yield* new GitHubAuthError({
                 message: "GitHub CLI not authenticated. Run 'gh auth login'.",
+                hint: "Authenticate with GitHub CLI or set GITHUB_TOKEN environment variable.",
+                nextCommand: "gh auth login",
               });
             }
 
@@ -91,6 +95,7 @@ export class GitHubService extends ServiceMap.Service<
                 message: result.stderr,
                 resource: "unknown",
                 identifier: "unknown",
+                hint: "Verify the resource exists and you have access. Check repository owner/name spelling.",
               });
             }
 

package/src/gh-tool/workflow.ts

@@ -1,7 +1,7 @@
 import { Command, Flag } from "effect/unstable/cli";
 import { Console, Effect, Option } from "effect";
 
-import { formatOption, logFormatted } from "../shared";
+import { formatOption, logFormatted } from "#src/shared";
 import { GitHubCommandError, GitHubNotFoundError } from "./errors";
 import { GitHubService } from "./service";
 
@@ -287,6 +287,8 @@ const resolveJobId = Effect.fn("workflow.resolveJobId")(function* (runId: number
       command: "workflow job-logs",
       exitCode: 1,
       stderr: "",
+      hint: `Multiple jobs match "${jobName}". Use the exact job name from the list above.`,
+      nextCommand: `agent-tools-gh workflow jobs --run ${runId}`,
     });
   }
 
@@ -294,6 +296,8 @@ const resolveJobId = Effect.fn("workflow.resolveJobId")(function* (runId: number
     message: `Job "${jobName}" not found in run ${runId}. Available jobs: ${jobs.map((j) => j.name).join(", ")}`,
     identifier: jobName,
     resource: "job",
+    hint: "Use one of the available job names listed above. Run the jobs command to see all jobs.",
+    nextCommand: `agent-tools-gh workflow jobs --run ${runId}`,
   });
 });
 

package/src/k8s-tool/errors.ts

@@ -3,6 +3,9 @@ import { Schema } from "effect";
 export class K8sContextError extends Schema.TaggedErrorClass<K8sContextError>()("K8sContextError", {
   message: Schema.String,
   clusterId: Schema.String,
+  hint: Schema.optionalKey(Schema.String),
+  nextCommand: Schema.optionalKey(Schema.String),
+  retryable: Schema.optionalKey(Schema.Boolean),
 }) {}
 
 export class K8sCommandError extends Schema.TaggedErrorClass<K8sCommandError>()("K8sCommandError", {
@@ -10,12 +13,18 @@ export class K8sCommandError extends Schema.TaggedErrorClass<K8sCommandError>()(
   command: Schema.String,
   exitCode: Schema.optionalKey(Schema.Number),
   stderr: Schema.optionalKey(Schema.String),
+  hint: Schema.optionalKey(Schema.String),
+  nextCommand: Schema.optionalKey(Schema.String),
+  retryable: Schema.optionalKey(Schema.Boolean),
 }) {}
 
 export class K8sTimeoutError extends Schema.TaggedErrorClass<K8sTimeoutError>()("K8sTimeoutError", {
   message: Schema.String,
   command: Schema.String,
   timeoutMs: Schema.Number,
+  hint: Schema.optionalKey(Schema.String),
+  nextCommand: Schema.optionalKey(Schema.String),
+  retryable: Schema.optionalKey(Schema.Boolean),
 }) {}
 
 export type K8sError = K8sContextError | K8sCommandError | K8sTimeoutError;