feat(errors): add shared user cancellation error

src/errors/errors.test.tsx

@@ -4,7 +4,13 @@ import {
  ValidationException,
  InternalServerException,
 } from "@aws-sdk/client-bedrock-agentcore-control";
-import { AgentCoreCLIError, InputValidationError } from "./errors";
+import { CommanderError } from "commander";
+import {
+ AgentCoreCLIError,
+ InputValidationError,
+ SilentCLIError,
+ UserCancellationError,
+} from "./errors";
 
 describe("AgentCoreCLIError", () => {
  test("fromError preserves existing AgentCoreCLIError instances", () => {
@@ -17,6 +23,43 @@ describe("AgentCoreCLIError", () => {
  expect(AgentCoreCLIError.fromError(err)).toBe(err);
  });
 
+ test.each([
+ ["parse failures", new CommanderError(1, "commander.invalidArgument", "invalid option"), 2],
+ ["help", new CommanderError(0, "commander.helpDisplayed", "help displayed"), 0],
+ ])("fromError classifies Commander %s", (_label, err, exitCode) => {
+ const result = AgentCoreCLIError.fromError(err);
+ expect(result).toBeInstanceOf(SilentCLIError);
+ expect(result.json()).toMatchObject({
+ name: "CommanderError",
+ source: "user",
+ exitCode,
+ meta: { code: err.code },
+ });
+ });
+
+ test("UserCancellationError is a silent user interruption", () => {
+ const error = new UserCancellationError();
+ expect(error).toBeInstanceOf(SilentCLIError);
+ expect(error.json()).toMatchObject({
+ name: "UserCancellationError",
+ message: "Operation cancelled by user",
+ source: "user",
+ exitCode: 130,
+ });
+ });
+
+ test("UserCancellationError resolves direct and signal-propagated cancellation", () => {
+ const cancellation = new UserCancellationError();
+ const controller = new AbortController();
+ controller.abort(cancellation);
+
+ expect(UserCancellationError.resolve(cancellation)).toBe(cancellation);
+ expect(UserCancellationError.resolve(new Error("transport aborted"), controller.signal)).toBe(
+ cancellation,
+ );
+ expect(UserCancellationError.resolve(new Error("failed"))).toBeUndefined();
+ });
+
  test.each([
  [
  "AccessDeniedException (403)",

src/errors/errors.tsx

@@ -1,4 +1,5 @@
 import { ServiceException } from "@smithy/core/client";
+import { CommanderError } from "commander";
 import { join } from "node:path";
 import { ERROR_SOURCE, type ErrorSource } from "./types";
 
@@ -41,6 +42,16 @@ export class AgentCoreCLIError extends Error {
  static fromError(error: unknown): AgentCoreCLIError {
  if (error instanceof AgentCoreCLIError) return error;
 
+ if (error instanceof CommanderError) {
+ return new SilentCLIError(error.message, {
+ cause: error,
+ source: ERROR_SOURCE.USER,
+ name: error.name,
+ meta: { code: error.code },
+ exitCode: error.exitCode === 0 ? 0 : 2,
+ });
+ }
+
  if (ServiceException.isInstance(error)) {
  const httpStatusCode = error.$metadata.httpStatusCode;
  const source =
@@ -62,6 +73,9 @@ export class AgentCoreCLIError extends Error {
  }
 }
 
+/** Base for CLI errors intentionally omitted from root stderr output. */
+export class SilentCLIError extends AgentCoreCLIError {}
+
 /** Error raised for invalid user input. */
 export class InputValidationError extends AgentCoreCLIError {
  constructor(message?: string, options?: Omit<AgentCoreCLIErrorOptions, "source">) {
@@ -137,39 +151,28 @@ export class EmbeddedAssetNotFoundError extends AgentCoreCLIError {
  }
 }
 
-export class CommandInterruptedError extends AgentCoreCLIError {
- readonly reported: boolean;
+/** Raised when a user intentionally cancels a headless CLI operation. */
+export class UserCancellationError extends SilentCLIError {
+ constructor() {
+ super("Operation cancelled by user", {
+ source: ERROR_SOURCE.USER,
+ exitCode: 130,
+ });
+ }
 
- constructor(cause?: unknown, reported = false) {
- super("The operation was aborted", { cause, exitCode: 130 });
- this.name = "AbortError";
- this.reported = reported;
+ static resolve(error: unknown, signal?: AbortSignal): UserCancellationError | undefined {
+ if (error instanceof UserCancellationError) return error;
+ return signal?.reason instanceof UserCancellationError ? signal.reason : undefined;
  }
 }
 
-export class RuntimeInvokeInterruptedError extends CommandInterruptedError {}
-
-export class RuntimeInvokeResponseError extends AgentCoreCLIError {
- readonly reported = true;
-
+export class RuntimeInvokeResponseError extends SilentCLIError {
  constructor(message: string, cause?: unknown) {
  super(message, { cause });
  }
 }
 
-export class GatewayInvokeInterruptedError extends AgentCoreCLIError {
- readonly reported: boolean;
-
- constructor(cause?: unknown, reported = false) {
- super("The operation was aborted", { cause, exitCode: 130 });
- this.name = "AbortError";
- this.reported = reported;
- }
-}
-
-export class GatewayInvokeResponseError extends AgentCoreCLIError {
- readonly reported = true;
-
+export class GatewayInvokeResponseError extends SilentCLIError {
  constructor(message: string, cause?: unknown) {
  super(message, { cause });
  }

src/errors/index.tsx

@@ -1,11 +1,9 @@
 export {
  AgentCoreCLIError,
  CloudWatchQueryError,
- CommandInterruptedError,
  DeserializationError,
  EmbeddedAssetNotFoundError,
  FileWriteError,
- GatewayInvokeInterruptedError,
  GatewayInvokeResponseError,
  InputValidationError,
  InvalidEnvironmentError,
@@ -16,9 +14,10 @@ export {
  ProjectFileExistsError,
  ResourceNotFoundError,
  ResultTruncationError,
- RuntimeInvokeInterruptedError,
  RuntimeInvokeResponseError,
+ SilentCLIError,
  SourceResolutionError,
+ UserCancellationError,
  type AgentCoreCLIErrorOptions,
 } from "./errors";
 export { ERROR_SOURCE } from "./types";

src/handlers/eval/dataset/dataset.test.tsx

@@ -8,7 +8,9 @@ import {
  TestCoreClient,
  TestGlobalConfigAccessor,
  testIO,
+ waitFor,
 } from "../../../testing";
+import { UserCancellationError } from "../../../errors";
 import { createRootHandler } from "../../index";
 import type { CreateDatasetInput } from "../types";
 
@@ -442,6 +444,41 @@ describe("dataset get", () => {
  expect(call?.args.slice(0, 3)).toEqual(["dataset-orders-abc123", "2", "/tmp/v2.jsonl"]);
  });
 
+ test("SIGINT cancels a download with the shared user cancellation error", async () => {
+ const { core, route } = testDatasetCommand();
+ core.eval.downloadDataset = async (id, version, filePath, options, signal) => {
+ core.eval.calls.push({
+ method: "downloadDataset",
+ args: [id, version, filePath, options, signal],
+ });
+ return new Promise<never>((_, reject) => {
+ const abort = () => reject(signal?.reason);
+ if (signal?.aborted) abort();
+ else signal?.addEventListener("abort", abort, { once: true });
+ });
+ };
+ const pending = route([
+ "eval",
+ "dataset",
+ "get",
+ "--id",
+ "dataset-orders-abc123",
+ "--file-path",
+ "/tmp/out.jsonl",
+ ]);
+
+ try {
+ await waitFor(() => core.eval.calls.some((call) => call.method === "downloadDataset"));
+ process.emit("SIGINT", "SIGINT");
+
+ const signal = core.eval.calls[0]!.args[4] as AbortSignal;
+ expect(signal.reason).toBeInstanceOf(UserCancellationError);
+ await expect(pending).rejects.toBe(signal.reason);
+ } finally {
+ await pending.catch(() => undefined);
+ }
+ });
+
  test("requires --id", async () => {
  const { core, route } = testDatasetCommand();
 
@@ -621,6 +658,42 @@ describe("dataset update", () => {
  });
  });
 
+ test("SIGINT cancels an update with the shared user cancellation error", async () => {
+ const path = writeTempJsonl(EXAMPLE_A);
+ const { core, route } = testDatasetCommand();
+ core.eval.updateDatasetExamples = async (id, filePath, options, signal, onProgress) => {
+ core.eval.calls.push({
+ method: "updateDatasetExamples",
+ args: [id, filePath, options, signal, onProgress],
+ });
+ return new Promise<never>((_, reject) => {
+ const abort = () => reject(signal?.reason);
+ if (signal?.aborted) abort();
+ else signal?.addEventListener("abort", abort, { once: true });
+ });
+ };
+ const pending = route([
+ "eval",
+ "dataset",
+ "update",
+ "--id",
+ "dataset-orders-abc123",
+ "--file-path",
+ path,
+ ]);
+
+ try {
+ await waitFor(() => core.eval.calls.some((call) => call.method === "updateDatasetExamples"));
+ process.emit("SIGINT", "SIGINT");
+
+ const signal = core.eval.calls[0]!.args[3] as AbortSignal;
+ expect(signal.reason).toBeInstanceOf(UserCancellationError);
+ await expect(pending).rejects.toBe(signal.reason);
+ } finally {
+ await pending.catch(() => undefined);
+ }
+ });
+
  test("takes only --id and --file-path", async () => {
  const root = createRootHandler(new TestCoreClient(), {
  io: testIO().io,

src/handlers/eval/dataset/get/index.tsx

@@ -2,6 +2,7 @@ import z from "zod";
 import { createHandler, flag } from "../../../../router";
 import { InputValidationError } from "../../../../errors";
 import { JsonRendererKey } from "../../../../tui";
+import { withUserCancellation } from "../../../../runnable";
 import type { Core } from "../../../types";
 import { coreOptsFromCtx } from "../../../utils";
 
@@ -24,33 +25,29 @@ export const createGetDatasetHandler = (core: Core) =>
  ],
  handle: async (ctx, flags) => {
  if (!flags["id"]) throw new InputValidationError("required option '--id <id>' not specified");
+ const datasetId = flags["id"];
 
  const filePath = flags["file-path"];
  if (!filePath) {
  ctx
  .require(JsonRendererKey)
  .renderJson(
- await core.eval.getDataset(flags["id"], flags["version"], coreOptsFromCtx(ctx)),
+ await core.eval.getDataset(datasetId, flags["version"], coreOptsFromCtx(ctx)),
  );
  return;
  }
 
  // --file-path downloads the contents via the presigned download URL in metadata
- const controller = new AbortController();
- const interrupt = () => controller.abort();
- process.once("SIGINT", interrupt);
- try {
- const response = await core.eval.downloadDataset(
- flags["id"],
+ const response = await withUserCancellation((signal) =>
+ core.eval.downloadDataset(
+ datasetId,
  flags["version"],
  filePath,
  coreOptsFromCtx(ctx),
- controller.signal,
- );
- // file is written in addition to the normal metadata output
- ctx.require(JsonRendererKey).renderJson({ ...response, filePath });
- } finally {
- process.removeListener("SIGINT", interrupt);
- }
+ signal,
+ ),
+ );
+ // file is written in addition to the normal metadata output
+ ctx.require(JsonRendererKey).renderJson({ ...response, filePath });
  },
  });

src/handlers/eval/dataset/update/index.tsx

@@ -3,6 +3,7 @@ import { createHandler, flag } from "../../../../router";
 import { InputValidationError } from "../../../../errors";
 import type { AppIO } from "../../../../io";
 import { JsonRendererKey } from "../../../../tui";
+import { withUserCancellation } from "../../../../runnable";
 import type { Core } from "../../../types";
 import { coreOptsFromCtx } from "../../../utils";
 
@@ -16,27 +17,24 @@ export const createUpdateDatasetHandler = (core: Core, io: AppIO) =>
  ],
  handle: async (ctx, flags) => {
  if (!flags["id"]) throw new InputValidationError("required option '--id <id>' not specified");
+ const datasetId = flags["id"];
  if (!flags["file-path"]) {
  throw new InputValidationError("required option '--file-path <file-path>' not specified");
  }
+ const filePath = flags["file-path"];
 
- const controller = new AbortController();
- const interrupt = () => controller.abort();
- process.once("SIGINT", interrupt);
- try {
- ctx
- .require(JsonRendererKey)
- .renderJson(
- await core.eval.updateDatasetExamples(
- flags["id"],
- flags["file-path"],
+ ctx
+ .require(JsonRendererKey)
+ .renderJson(
+ await withUserCancellation((signal) =>
+ core.eval.updateDatasetExamples(
+ datasetId,
+ filePath,
  coreOptsFromCtx(ctx),
-controller.signal,
+ signal,
  (event) => io.stderr.write(`${event.message}\n`),
  ),
- );
- } finally {
- process.removeListener("SIGINT", interrupt);
- }
+ ),
+ );
  },
  });

src/errors/errors.test.tsx

@@ -4,7 +4,13 @@ import {
  ValidationException,
  InternalServerException,
 } from "@aws-sdk/client-bedrock-agentcore-control";
-import { AgentCoreCLIError, InputValidationError } from "./errors";
+import { CommanderError } from "commander";
+import {
+ AgentCoreCLIError,
+ InputValidationError,
+ SilentCLIError,
+ UserCancellationError,
+} from "./errors";
 
 describe("AgentCoreCLIError", () => {
  test("fromError preserves existing AgentCoreCLIError instances", () => {
@@ -17,6 +23,43 @@ describe("AgentCoreCLIError", () => {
  expect(AgentCoreCLIError.fromError(err)).toBe(err);
  });
 
+ test.each([
+ ["parse failures", new CommanderError(1, "commander.invalidArgument", "invalid option"), 2],
+ ["help", new CommanderError(0, "commander.helpDisplayed", "help displayed"), 0],
+ ])("fromError classifies Commander %s", (_label, err, exitCode) => {
+ const result = AgentCoreCLIError.fromError(err);
+ expect(result).toBeInstanceOf(SilentCLIError);
+ expect(result.json()).toMatchObject({
+ name: "CommanderError",
+ source: "user",
+ exitCode,
+ meta: { code: err.code },
+ });
+ });
+
+ test("UserCancellationError is a silent user interruption", () => {
+ const error = new UserCancellationError();
+ expect(error).toBeInstanceOf(SilentCLIError);
+ expect(error.json()).toMatchObject({
+ name: "UserCancellationError",
+ message: "Operation cancelled by user",
+ source: "user",
+ exitCode: 130,
+ });
+ });
+
+ test("UserCancellationError resolves direct and signal-propagated cancellation", () => {
+ const cancellation = new UserCancellationError();
+ const controller = new AbortController();
+ controller.abort(cancellation);
+
+ expect(UserCancellationError.resolve(cancellation)).toBe(cancellation);
+ expect(UserCancellationError.resolve(new Error("transport aborted"), controller.signal)).toBe(
+ cancellation,
+ );
+ expect(UserCancellationError.resolve(new Error("failed"))).toBeUndefined();
+ });
+
  test.each([
  [
  "AccessDeniedException (403)",

src/errors/errors.tsx

@@ -1,4 +1,5 @@
 import { ServiceException } from "@smithy/core/client";
+import { CommanderError } from "commander";
 import { join } from "node:path";
 import { ERROR_SOURCE, type ErrorSource } from "./types";
 
@@ -41,6 +42,16 @@ export class AgentCoreCLIError extends Error {
  static fromError(error: unknown): AgentCoreCLIError {
  if (error instanceof AgentCoreCLIError) return error;
 
+ if (error instanceof CommanderError) {
+ return new SilentCLIError(error.message, {
+ cause: error,
+ source: ERROR_SOURCE.USER,
+ name: error.name,
+ meta: { code: error.code },
+ exitCode: error.exitCode === 0 ? 0 : 2,
+ });
+ }
+
  if (ServiceException.isInstance(error)) {
  const httpStatusCode = error.$metadata.httpStatusCode;
  const source =
@@ -62,6 +73,9 @@ export class AgentCoreCLIError extends Error {
  }
 }
 
+/** Base for CLI errors intentionally omitted from root stderr output. */
+export class SilentCLIError extends AgentCoreCLIError {}
+
 /** Error raised for invalid user input. */
 export class InputValidationError extends AgentCoreCLIError {
  constructor(message?: string, options?: Omit<AgentCoreCLIErrorOptions, "source">) {
@@ -137,39 +151,28 @@ export class EmbeddedAssetNotFoundError extends AgentCoreCLIError {
  }
 }
 
-export class CommandInterruptedError extends AgentCoreCLIError {
- readonly reported: boolean;
+/** Raised when a user intentionally cancels a headless CLI operation. */
+export class UserCancellationError extends SilentCLIError {
+ constructor() {
+ super("Operation cancelled by user", {
+ source: ERROR_SOURCE.USER,
+ exitCode: 130,
+ });
+ }
 
- constructor(cause?: unknown, reported = false) {
- super("The operation was aborted", { cause, exitCode: 130 });
- this.name = "AbortError";
- this.reported = reported;
+ static resolve(error: unknown, signal?: AbortSignal): UserCancellationError | undefined {
+ if (error instanceof UserCancellationError) return error;
+ return signal?.reason instanceof UserCancellationError ? signal.reason : undefined;
  }
 }
 
-export class RuntimeInvokeInterruptedError extends CommandInterruptedError {}
-
-export class RuntimeInvokeResponseError extends AgentCoreCLIError {
- readonly reported = true;
-
+export class RuntimeInvokeResponseError extends SilentCLIError {
  constructor(message: string, cause?: unknown) {
  super(message, { cause });
  }
 }
 
-export class GatewayInvokeInterruptedError extends AgentCoreCLIError {
- readonly reported: boolean;
-
- constructor(cause?: unknown, reported = false) {
- super("The operation was aborted", { cause, exitCode: 130 });
- this.name = "AbortError";
- this.reported = reported;
- }
-}
-
-export class GatewayInvokeResponseError extends AgentCoreCLIError {
- readonly reported = true;
-
+export class GatewayInvokeResponseError extends SilentCLIError {
  constructor(message: string, cause?: unknown) {
  super(message, { cause });
  }

src/errors/index.tsx

@@ -1,11 +1,9 @@
 export {
  AgentCoreCLIError,
  CloudWatchQueryError,
- CommandInterruptedError,
  DeserializationError,
  EmbeddedAssetNotFoundError,
  FileWriteError,
- GatewayInvokeInterruptedError,
  GatewayInvokeResponseError,
  InputValidationError,
  InvalidEnvironmentError,
@@ -16,9 +14,10 @@ export {
  ProjectFileExistsError,
  ResourceNotFoundError,
  ResultTruncationError,
- RuntimeInvokeInterruptedError,
  RuntimeInvokeResponseError,
+ SilentCLIError,
  SourceResolutionError,
+ UserCancellationError,
  type AgentCoreCLIErrorOptions,
 } from "./errors";
 export { ERROR_SOURCE } from "./types";

src/handlers/eval/dataset/dataset.test.tsx

@@ -8,7 +8,9 @@ import {
  TestCoreClient,
  TestGlobalConfigAccessor,
  testIO,
+ waitFor,
 } from "../../../testing";
+import { UserCancellationError } from "../../../errors";
 import { createRootHandler } from "../../index";
 import type { CreateDatasetInput } from "../types";
 
@@ -442,6 +444,41 @@ describe("dataset get", () => {
  expect(call?.args.slice(0, 3)).toEqual(["dataset-orders-abc123", "2", "/tmp/v2.jsonl"]);
  });
 
+ test("SIGINT cancels a download with the shared user cancellation error", async () => {
+ const { core, route } = testDatasetCommand();
+ core.eval.downloadDataset = async (id, version, filePath, options, signal) => {
+ core.eval.calls.push({
+ method: "downloadDataset",
+ args: [id, version, filePath, options, signal],
+ });
+ return new Promise<never>((_, reject) => {
+ const abort = () => reject(signal?.reason);
+ if (signal?.aborted) abort();
+ else signal?.addEventListener("abort", abort, { once: true });
+ });
+ };
+ const pending = route([
+ "eval",
+ "dataset",
+ "get",
+ "--id",
+ "dataset-orders-abc123",
+ "--file-path",
+ "/tmp/out.jsonl",
+ ]);
+
+ try {
+ await waitFor(() => core.eval.calls.some((call) => call.method === "downloadDataset"));
+ process.emit("SIGINT", "SIGINT");
+
+ const signal = core.eval.calls[0]!.args[4] as AbortSignal;
+ expect(signal.reason).toBeInstanceOf(UserCancellationError);
+ await expect(pending).rejects.toBe(signal.reason);
+ } finally {
+ await pending.catch(() => undefined);
+ }
+ });
+
  test("requires --id", async () => {
  const { core, route } = testDatasetCommand();
 
@@ -621,6 +658,42 @@ describe("dataset update", () => {
  });
  });
 
+ test("SIGINT cancels an update with the shared user cancellation error", async () => {
+ const path = writeTempJsonl(EXAMPLE_A);
+ const { core, route } = testDatasetCommand();
+ core.eval.updateDatasetExamples = async (id, filePath, options, signal, onProgress) => {
+ core.eval.calls.push({
+ method: "updateDatasetExamples",
+ args: [id, filePath, options, signal, onProgress],
+ });
+ return new Promise<never>((_, reject) => {
+ const abort = () => reject(signal?.reason);
+ if (signal?.aborted) abort();
+ else signal?.addEventListener("abort", abort, { once: true });
+ });
+ };
+ const pending = route([
+ "eval",
+ "dataset",
+ "update",
+ "--id",
+ "dataset-orders-abc123",
+ "--file-path",
+ path,
+ ]);
+
+ try {
+ await waitFor(() => core.eval.calls.some((call) => call.method === "updateDatasetExamples"));
+ process.emit("SIGINT", "SIGINT");
+
+ const signal = core.eval.calls[0]!.args[3] as AbortSignal;
+ expect(signal.reason).toBeInstanceOf(UserCancellationError);
+ await expect(pending).rejects.toBe(signal.reason);
+ } finally {
+ await pending.catch(() => undefined);
+ }
+ });
+
  test("takes only --id and --file-path", async () => {
  const root = createRootHandler(new TestCoreClient(), {
  io: testIO().io,

src/handlers/eval/dataset/get/index.tsx

@@ -2,6 +2,7 @@ import z from "zod";
 import { createHandler, flag } from "../../../../router";
 import { InputValidationError } from "../../../../errors";
 import { JsonRendererKey } from "../../../../tui";
+import { withUserCancellation } from "../../../../runnable";
 import type { Core } from "../../../types";
 import { coreOptsFromCtx } from "../../../utils";
 
@@ -24,33 +25,29 @@ export const createGetDatasetHandler = (core: Core) =>
  ],
  handle: async (ctx, flags) => {
  if (!flags["id"]) throw new InputValidationError("required option '--id <id>' not specified");
+ const datasetId = flags["id"];
 
  const filePath = flags["file-path"];
  if (!filePath) {
  ctx
  .require(JsonRendererKey)
  .renderJson(
- await core.eval.getDataset(flags["id"], flags["version"], coreOptsFromCtx(ctx)),
+ await core.eval.getDataset(datasetId, flags["version"], coreOptsFromCtx(ctx)),
  );
  return;
  }
 
  // --file-path downloads the contents via the presigned download URL in metadata
- const controller = new AbortController();
- const interrupt = () => controller.abort();
- process.once("SIGINT", interrupt);
- try {
- const response = await core.eval.downloadDataset(
- flags["id"],
+ const response = await withUserCancellation((signal) =>
+ core.eval.downloadDataset(
+ datasetId,
  flags["version"],
  filePath,
  coreOptsFromCtx(ctx),
- controller.signal,
- );
- // file is written in addition to the normal metadata output
- ctx.require(JsonRendererKey).renderJson({ ...response, filePath });
- } finally {
- process.removeListener("SIGINT", interrupt);
- }
+ signal,
+ ),
+ );
+ // file is written in addition to the normal metadata output
+ ctx.require(JsonRendererKey).renderJson({ ...response, filePath });
  },
  });

src/handlers/eval/dataset/update/index.tsx

@@ -3,6 +3,7 @@ import { createHandler, flag } from "../../../../router";
 import { InputValidationError } from "../../../../errors";
 import type { AppIO } from "../../../../io";
 import { JsonRendererKey } from "../../../../tui";
+import { withUserCancellation } from "../../../../runnable";
 import type { Core } from "../../../types";
 import { coreOptsFromCtx } from "../../../utils";
 
@@ -16,27 +17,24 @@ export const createUpdateDatasetHandler = (core: Core, io: AppIO) =>
  ],
  handle: async (ctx, flags) => {
  if (!flags["id"]) throw new InputValidationError("required option '--id <id>' not specified");
+ const datasetId = flags["id"];
  if (!flags["file-path"]) {
  throw new InputValidationError("required option '--file-path <file-path>' not specified");
  }
+ const filePath = flags["file-path"];
 
- const controller = new AbortController();
- const interrupt = () => controller.abort();
- process.once("SIGINT", interrupt);
- try {
- ctx
- .require(JsonRendererKey)
- .renderJson(
- await core.eval.updateDatasetExamples(
- flags["id"],
- flags["file-path"],
+ ctx
+ .require(JsonRendererKey)
+ .renderJson(
+ await withUserCancellation((signal) =>
+ core.eval.updateDatasetExamples(
+ datasetId,
+ filePath,
  coreOptsFromCtx(ctx),
-controller.signal,
+ signal,
  (event) => io.stderr.write(`${event.message}\n`),
  ),
- );
- } finally {
- process.removeListener("SIGINT", interrupt);
- }
+ ),
+ );
  },
  });

src/errors/errors.test.tsx

@@ -4,7 +4,13 @@ import {
  ValidationException,
  InternalServerException,
 } from "@aws-sdk/client-bedrock-agentcore-control";
-import { AgentCoreCLIError, InputValidationError } from "./errors";
+import { CommanderError } from "commander";
+import {
+ AgentCoreCLIError,
+ InputValidationError,
+ SilentCLIError,
+ UserCancellationError,
+} from "./errors";
 
 describe("AgentCoreCLIError", () => {
  test("fromError preserves existing AgentCoreCLIError instances", () => {
@@ -17,6 +23,43 @@ describe("AgentCoreCLIError", () => {
  expect(AgentCoreCLIError.fromError(err)).toBe(err);
  });
 
+ test.each([
+ ["parse failures", new CommanderError(1, "commander.invalidArgument", "invalid option"), 2],
+ ["help", new CommanderError(0, "commander.helpDisplayed", "help displayed"), 0],
+ ])("fromError classifies Commander %s", (_label, err, exitCode) => {
+ const result = AgentCoreCLIError.fromError(err);
+ expect(result).toBeInstanceOf(SilentCLIError);
+ expect(result.json()).toMatchObject({
+ name: "CommanderError",
+ source: "user",
+ exitCode,
+ meta: { code: err.code },
+ });
+ });
+
+ test("UserCancellationError is a silent user interruption", () => {
+ const error = new UserCancellationError();
+ expect(error).toBeInstanceOf(SilentCLIError);
+ expect(error.json()).toMatchObject({
+ name: "UserCancellationError",
+ message: "Operation cancelled by user",
+ source: "user",
+ exitCode: 130,
+ });
+ });
+
+ test("UserCancellationError resolves direct and signal-propagated cancellation", () => {
+ const cancellation = new UserCancellationError();
+ const controller = new AbortController();
+ controller.abort(cancellation);
+
+ expect(UserCancellationError.resolve(cancellation)).toBe(cancellation);
+ expect(UserCancellationError.resolve(new Error("transport aborted"), controller.signal)).toBe(
+ cancellation,
+ );
+ expect(UserCancellationError.resolve(new Error("failed"))).toBeUndefined();
+ });
+
  test.each([
  [
  "AccessDeniedException (403)",

src/errors/errors.tsx

@@ -1,4 +1,5 @@
 import { ServiceException } from "@smithy/core/client";
+import { CommanderError } from "commander";
 import { join } from "node:path";
 import { ERROR_SOURCE, type ErrorSource } from "./types";
 
@@ -41,6 +42,16 @@ export class AgentCoreCLIError extends Error {
  static fromError(error: unknown): AgentCoreCLIError {
  if (error instanceof AgentCoreCLIError) return error;
 
+ if (error instanceof CommanderError) {
+ return new SilentCLIError(error.message, {
+ cause: error,
+ source: ERROR_SOURCE.USER,
+ name: error.name,
+ meta: { code: error.code },
+ exitCode: error.exitCode === 0 ? 0 : 2,
+ });
+ }
+
  if (ServiceException.isInstance(error)) {
  const httpStatusCode = error.$metadata.httpStatusCode;
  const source =
@@ -62,6 +73,9 @@ export class AgentCoreCLIError extends Error {
  }
 }
 
+/** Base for CLI errors intentionally omitted from root stderr output. */
+export class SilentCLIError extends AgentCoreCLIError {}
+
 /** Error raised for invalid user input. */
 export class InputValidationError extends AgentCoreCLIError {
  constructor(message?: string, options?: Omit<AgentCoreCLIErrorOptions, "source">) {
@@ -137,39 +151,28 @@ export class EmbeddedAssetNotFoundError extends AgentCoreCLIError {
  }
 }
 
-export class CommandInterruptedError extends AgentCoreCLIError {
- readonly reported: boolean;
+/** Raised when a user intentionally cancels a headless CLI operation. */
+export class UserCancellationError extends SilentCLIError {
+ constructor() {
+ super("Operation cancelled by user", {
+ source: ERROR_SOURCE.USER,
+ exitCode: 130,
+ });
+ }
 
- constructor(cause?: unknown, reported = false) {
- super("The operation was aborted", { cause, exitCode: 130 });
- this.name = "AbortError";
- this.reported = reported;
+ static resolve(error: unknown, signal?: AbortSignal): UserCancellationError | undefined {
+ if (error instanceof UserCancellationError) return error;
+ return signal?.reason instanceof UserCancellationError ? signal.reason : undefined;
  }
 }
 
-export class RuntimeInvokeInterruptedError extends CommandInterruptedError {}
-
-export class RuntimeInvokeResponseError extends AgentCoreCLIError {
- readonly reported = true;
-
+export class RuntimeInvokeResponseError extends SilentCLIError {
  constructor(message: string, cause?: unknown) {
  super(message, { cause });
  }
 }
 
-export class GatewayInvokeInterruptedError extends AgentCoreCLIError {
- readonly reported: boolean;
-
- constructor(cause?: unknown, reported = false) {
- super("The operation was aborted", { cause, exitCode: 130 });
- this.name = "AbortError";
- this.reported = reported;
- }
-}
-
-export class GatewayInvokeResponseError extends AgentCoreCLIError {
- readonly reported = true;
-
+export class GatewayInvokeResponseError extends SilentCLIError {
  constructor(message: string, cause?: unknown) {
  super(message, { cause });
  }

src/errors/index.tsx

@@ -1,11 +1,9 @@
 export {
  AgentCoreCLIError,
  CloudWatchQueryError,
- CommandInterruptedError,
  DeserializationError,
  EmbeddedAssetNotFoundError,
  FileWriteError,
- GatewayInvokeInterruptedError,
  GatewayInvokeResponseError,
  InputValidationError,
  InvalidEnvironmentError,
@@ -16,9 +14,10 @@ export {
  ProjectFileExistsError,
  ResourceNotFoundError,
  ResultTruncationError,
- RuntimeInvokeInterruptedError,
  RuntimeInvokeResponseError,
+ SilentCLIError,
  SourceResolutionError,
+ UserCancellationError,
  type AgentCoreCLIErrorOptions,
 } from "./errors";
 export { ERROR_SOURCE } from "./types";

src/handlers/eval/dataset/dataset.test.tsx

@@ -8,7 +8,9 @@ import {
  TestCoreClient,
  TestGlobalConfigAccessor,
  testIO,
+ waitFor,
 } from "../../../testing";
+import { UserCancellationError } from "../../../errors";
 import { createRootHandler } from "../../index";
 import type { CreateDatasetInput } from "../types";
 
@@ -442,6 +444,41 @@ describe("dataset get", () => {
  expect(call?.args.slice(0, 3)).toEqual(["dataset-orders-abc123", "2", "/tmp/v2.jsonl"]);
  });
 
+ test("SIGINT cancels a download with the shared user cancellation error", async () => {
+ const { core, route } = testDatasetCommand();
+ core.eval.downloadDataset = async (id, version, filePath, options, signal) => {
+ core.eval.calls.push({
+ method: "downloadDataset",
+ args: [id, version, filePath, options, signal],
+ });
+ return new Promise<never>((_, reject) => {
+ const abort = () => reject(signal?.reason);
+ if (signal?.aborted) abort();
+ else signal?.addEventListener("abort", abort, { once: true });
+ });
+ };
+ const pending = route([
+ "eval",
+ "dataset",
+ "get",
+ "--id",
+ "dataset-orders-abc123",
+ "--file-path",
+ "/tmp/out.jsonl",
+ ]);
+
+ try {
+ await waitFor(() => core.eval.calls.some((call) => call.method === "downloadDataset"));
+ process.emit("SIGINT", "SIGINT");
+
+ const signal = core.eval.calls[0]!.args[4] as AbortSignal;
+ expect(signal.reason).toBeInstanceOf(UserCancellationError);
+ await expect(pending).rejects.toBe(signal.reason);
+ } finally {
+ await pending.catch(() => undefined);
+ }
+ });
+
  test("requires --id", async () => {
  const { core, route } = testDatasetCommand();
 
@@ -621,6 +658,42 @@ describe("dataset update", () => {
  });
  });
 
+ test("SIGINT cancels an update with the shared user cancellation error", async () => {
+ const path = writeTempJsonl(EXAMPLE_A);
+ const { core, route } = testDatasetCommand();
+ core.eval.updateDatasetExamples = async (id, filePath, options, signal, onProgress) => {
+ core.eval.calls.push({
+ method: "updateDatasetExamples",
+ args: [id, filePath, options, signal, onProgress],
+ });
+ return new Promise<never>((_, reject) => {
+ const abort = () => reject(signal?.reason);
+ if (signal?.aborted) abort();
+ else signal?.addEventListener("abort", abort, { once: true });
+ });
+ };
+ const pending = route([
+ "eval",
+ "dataset",
+ "update",
+ "--id",
+ "dataset-orders-abc123",
+ "--file-path",
+ path,
+ ]);
+
+ try {
+ await waitFor(() => core.eval.calls.some((call) => call.method === "updateDatasetExamples"));
+ process.emit("SIGINT", "SIGINT");
+
+ const signal = core.eval.calls[0]!.args[3] as AbortSignal;
+ expect(signal.reason).toBeInstanceOf(UserCancellationError);
+ await expect(pending).rejects.toBe(signal.reason);
+ } finally {
+ await pending.catch(() => undefined);
+ }
+ });
+
  test("takes only --id and --file-path", async () => {
  const root = createRootHandler(new TestCoreClient(), {
  io: testIO().io,

src/handlers/eval/dataset/get/index.tsx

@@ -2,6 +2,7 @@ import z from "zod";
 import { createHandler, flag } from "../../../../router";
 import { InputValidationError } from "../../../../errors";
 import { JsonRendererKey } from "../../../../tui";
+import { withUserCancellation } from "../../../../runnable";
 import type { Core } from "../../../types";
 import { coreOptsFromCtx } from "../../../utils";
 
@@ -24,33 +25,29 @@ export const createGetDatasetHandler = (core: Core) =>
  ],
  handle: async (ctx, flags) => {
  if (!flags["id"]) throw new InputValidationError("required option '--id <id>' not specified");
+ const datasetId = flags["id"];
 
  const filePath = flags["file-path"];
  if (!filePath) {
  ctx
  .require(JsonRendererKey)
  .renderJson(
- await core.eval.getDataset(flags["id"], flags["version"], coreOptsFromCtx(ctx)),
+ await core.eval.getDataset(datasetId, flags["version"], coreOptsFromCtx(ctx)),
  );
  return;
  }
 
  // --file-path downloads the contents via the presigned download URL in metadata
- const controller = new AbortController();
- const interrupt = () => controller.abort();
- process.once("SIGINT", interrupt);
- try {
- const response = await core.eval.downloadDataset(
- flags["id"],
+ const response = await withUserCancellation((signal) =>
+ core.eval.downloadDataset(
+ datasetId,
  flags["version"],
  filePath,
  coreOptsFromCtx(ctx),
- controller.signal,
- );
- // file is written in addition to the normal metadata output
- ctx.require(JsonRendererKey).renderJson({ ...response, filePath });
- } finally {
- process.removeListener("SIGINT", interrupt);
- }
+ signal,
+ ),
+ );
+ // file is written in addition to the normal metadata output
+ ctx.require(JsonRendererKey).renderJson({ ...response, filePath });
  },
  });

src/handlers/eval/dataset/update/index.tsx

@@ -3,6 +3,7 @@ import { createHandler, flag } from "../../../../router";
 import { InputValidationError } from "../../../../errors";
 import type { AppIO } from "../../../../io";
 import { JsonRendererKey } from "../../../../tui";
+import { withUserCancellation } from "../../../../runnable";
 import type { Core } from "../../../types";
 import { coreOptsFromCtx } from "../../../utils";
 
@@ -16,27 +17,24 @@ export const createUpdateDatasetHandler = (core: Core, io: AppIO) =>
  ],
  handle: async (ctx, flags) => {
  if (!flags["id"]) throw new InputValidationError("required option '--id <id>' not specified");
+ const datasetId = flags["id"];
  if (!flags["file-path"]) {
  throw new InputValidationError("required option '--file-path <file-path>' not specified");
  }
+ const filePath = flags["file-path"];
 
- const controller = new AbortController();
- const interrupt = () => controller.abort();
- process.once("SIGINT", interrupt);
- try {
- ctx
- .require(JsonRendererKey)
- .renderJson(
- await core.eval.updateDatasetExamples(
- flags["id"],
- flags["file-path"],
+ ctx
+ .require(JsonRendererKey)
+ .renderJson(
+ await withUserCancellation((signal) =>
+ core.eval.updateDatasetExamples(
+ datasetId,
+ filePath,
  coreOptsFromCtx(ctx),
-controller.signal,
+ signal,
  (event) => io.stderr.write(`${event.message}\n`),
  ),
- );
- } finally {
- process.removeListener("SIGINT", interrupt);
- }
+ ),
+ );
  },
  });

src/errors/errors.test.tsx

@@ -4,7 +4,13 @@ import {
  ValidationException,
  InternalServerException,
 } from "@aws-sdk/client-bedrock-agentcore-control";
-import { AgentCoreCLIError, InputValidationError } from "./errors";
+import { CommanderError } from "commander";
+import {
+ AgentCoreCLIError,
+ InputValidationError,
+ SilentCLIError,
+ UserCancellationError,
+} from "./errors";
 
 describe("AgentCoreCLIError", () => {
  test("fromError preserves existing AgentCoreCLIError instances", () => {
@@ -17,6 +23,43 @@ describe("AgentCoreCLIError", () => {
  expect(AgentCoreCLIError.fromError(err)).toBe(err);
  });
 
+ test.each([
+ ["parse failures", new CommanderError(1, "commander.invalidArgument", "invalid option"), 2],
+ ["help", new CommanderError(0, "commander.helpDisplayed", "help displayed"), 0],
+ ])("fromError classifies Commander %s", (_label, err, exitCode) => {
+ const result = AgentCoreCLIError.fromError(err);
+ expect(result).toBeInstanceOf(SilentCLIError);
+ expect(result.json()).toMatchObject({
+ name: "CommanderError",
+ source: "user",
+ exitCode,
+ meta: { code: err.code },
+ });
+ });
+
+ test("UserCancellationError is a silent user interruption", () => {
+ const error = new UserCancellationError();
+ expect(error).toBeInstanceOf(SilentCLIError);
+ expect(error.json()).toMatchObject({
+ name: "UserCancellationError",
+ message: "Operation cancelled by user",
+ source: "user",
+ exitCode: 130,
+ });
+ });
+
+ test("UserCancellationError resolves direct and signal-propagated cancellation", () => {
+ const cancellation = new UserCancellationError();
+ const controller = new AbortController();
+ controller.abort(cancellation);
+
+ expect(UserCancellationError.resolve(cancellation)).toBe(cancellation);
+ expect(UserCancellationError.resolve(new Error("transport aborted"), controller.signal)).toBe(
+ cancellation,
+ );
+ expect(UserCancellationError.resolve(new Error("failed"))).toBeUndefined();
+ });
+
  test.each([
  [
  "AccessDeniedException (403)",

src/errors/errors.tsx

@@ -1,4 +1,5 @@
 import { ServiceException } from "@smithy/core/client";
+import { CommanderError } from "commander";
 import { join } from "node:path";
 import { ERROR_SOURCE, type ErrorSource } from "./types";
 
@@ -41,6 +42,16 @@ export class AgentCoreCLIError extends Error {
  static fromError(error: unknown): AgentCoreCLIError {
  if (error instanceof AgentCoreCLIError) return error;
 
+ if (error instanceof CommanderError) {
+ return new SilentCLIError(error.message, {
+ cause: error,
+ source: ERROR_SOURCE.USER,
+ name: error.name,
+ meta: { code: error.code },
+ exitCode: error.exitCode === 0 ? 0 : 2,
+ });
+ }
+
  if (ServiceException.isInstance(error)) {
  const httpStatusCode = error.$metadata.httpStatusCode;
  const source =
@@ -62,6 +73,9 @@ export class AgentCoreCLIError extends Error {
  }
 }
 
+/** Base for CLI errors intentionally omitted from root stderr output. */
+export class SilentCLIError extends AgentCoreCLIError {}
+
 /** Error raised for invalid user input. */
 export class InputValidationError extends AgentCoreCLIError {
  constructor(message?: string, options?: Omit<AgentCoreCLIErrorOptions, "source">) {
@@ -137,39 +151,28 @@ export class EmbeddedAssetNotFoundError extends AgentCoreCLIError {
  }
 }
 
-export class CommandInterruptedError extends AgentCoreCLIError {
- readonly reported: boolean;
+/** Raised when a user intentionally cancels a headless CLI operation. */
+export class UserCancellationError extends SilentCLIError {
+ constructor() {
+ super("Operation cancelled by user", {
+ source: ERROR_SOURCE.USER,
+ exitCode: 130,
+ });
+ }
 
- constructor(cause?: unknown, reported = false) {
- super("The operation was aborted", { cause, exitCode: 130 });
- this.name = "AbortError";
- this.reported = reported;
+ static resolve(error: unknown, signal?: AbortSignal): UserCancellationError | undefined {
+ if (error instanceof UserCancellationError) return error;
+ return signal?.reason instanceof UserCancellationError ? signal.reason : undefined;
  }
 }
 
-export class RuntimeInvokeInterruptedError extends CommandInterruptedError {}
-
-export class RuntimeInvokeResponseError extends AgentCoreCLIError {
- readonly reported = true;
-
+export class RuntimeInvokeResponseError extends SilentCLIError {
  constructor(message: string, cause?: unknown) {
  super(message, { cause });
  }
 }
 
-export class GatewayInvokeInterruptedError extends AgentCoreCLIError {
- readonly reported: boolean;
-
- constructor(cause?: unknown, reported = false) {
- super("The operation was aborted", { cause, exitCode: 130 });
- this.name = "AbortError";
- this.reported = reported;
- }
-}
-
-export class GatewayInvokeResponseError extends AgentCoreCLIError {
- readonly reported = true;
-
+export class GatewayInvokeResponseError extends SilentCLIError {
  constructor(message: string, cause?: unknown) {
  super(message, { cause });
  }

src/errors/index.tsx

@@ -1,11 +1,9 @@
 export {
  AgentCoreCLIError,
  CloudWatchQueryError,
- CommandInterruptedError,
  DeserializationError,
  EmbeddedAssetNotFoundError,
  FileWriteError,
- GatewayInvokeInterruptedError,
  GatewayInvokeResponseError,
  InputValidationError,
  InvalidEnvironmentError,
@@ -16,9 +14,10 @@ export {
  ProjectFileExistsError,
  ResourceNotFoundError,
  ResultTruncationError,
- RuntimeInvokeInterruptedError,
  RuntimeInvokeResponseError,
+ SilentCLIError,
  SourceResolutionError,
+ UserCancellationError,
  type AgentCoreCLIErrorOptions,
 } from "./errors";
 export { ERROR_SOURCE } from "./types";

src/handlers/eval/dataset/dataset.test.tsx

@@ -8,7 +8,9 @@ import {
  TestCoreClient,
  TestGlobalConfigAccessor,
  testIO,
+ waitFor,
 } from "../../../testing";
+import { UserCancellationError } from "../../../errors";
 import { createRootHandler } from "../../index";
 import type { CreateDatasetInput } from "../types";
 
@@ -442,6 +444,41 @@ describe("dataset get", () => {
  expect(call?.args.slice(0, 3)).toEqual(["dataset-orders-abc123", "2", "/tmp/v2.jsonl"]);
  });
 
+ test("SIGINT cancels a download with the shared user cancellation error", async () => {
+ const { core, route } = testDatasetCommand();
+ core.eval.downloadDataset = async (id, version, filePath, options, signal) => {
+ core.eval.calls.push({
+ method: "downloadDataset",
+ args: [id, version, filePath, options, signal],
+ });
+ return new Promise<never>((_, reject) => {
+ const abort = () => reject(signal?.reason);
+ if (signal?.aborted) abort();
+ else signal?.addEventListener("abort", abort, { once: true });
+ });
+ };
+ const pending = route([
+ "eval",
+ "dataset",
+ "get",
+ "--id",
+ "dataset-orders-abc123",
+ "--file-path",
+ "/tmp/out.jsonl",
+ ]);
+
+ try {
+ await waitFor(() => core.eval.calls.some((call) => call.method === "downloadDataset"));
+ process.emit("SIGINT", "SIGINT");
+
+ const signal = core.eval.calls[0]!.args[4] as AbortSignal;
+ expect(signal.reason).toBeInstanceOf(UserCancellationError);
+ await expect(pending).rejects.toBe(signal.reason);
+ } finally {
+ await pending.catch(() => undefined);
+ }
+ });
+
  test("requires --id", async () => {
  const { core, route } = testDatasetCommand();
 
@@ -621,6 +658,42 @@ describe("dataset update", () => {
  });
  });
 
+ test("SIGINT cancels an update with the shared user cancellation error", async () => {
+ const path = writeTempJsonl(EXAMPLE_A);
+ const { core, route } = testDatasetCommand();
+ core.eval.updateDatasetExamples = async (id, filePath, options, signal, onProgress) => {
+ core.eval.calls.push({
+ method: "updateDatasetExamples",
+ args: [id, filePath, options, signal, onProgress],
+ });
+ return new Promise<never>((_, reject) => {
+ const abort = () => reject(signal?.reason);
+ if (signal?.aborted) abort();
+ else signal?.addEventListener("abort", abort, { once: true });
+ });
+ };
+ const pending = route([
+ "eval",
+ "dataset",
+ "update",
+ "--id",
+ "dataset-orders-abc123",
+ "--file-path",
+ path,
+ ]);
+
+ try {
+ await waitFor(() => core.eval.calls.some((call) => call.method === "updateDatasetExamples"));
+ process.emit("SIGINT", "SIGINT");
+
+ const signal = core.eval.calls[0]!.args[3] as AbortSignal;
+ expect(signal.reason).toBeInstanceOf(UserCancellationError);
+ await expect(pending).rejects.toBe(signal.reason);
+ } finally {
+ await pending.catch(() => undefined);
+ }
+ });
+
  test("takes only --id and --file-path", async () => {
  const root = createRootHandler(new TestCoreClient(), {
  io: testIO().io,

src/handlers/eval/dataset/get/index.tsx

@@ -2,6 +2,7 @@ import z from "zod";
 import { createHandler, flag } from "../../../../router";
 import { InputValidationError } from "../../../../errors";
 import { JsonRendererKey } from "../../../../tui";
+import { withUserCancellation } from "../../../../runnable";
 import type { Core } from "../../../types";
 import { coreOptsFromCtx } from "../../../utils";
 
@@ -24,33 +25,29 @@ export const createGetDatasetHandler = (core: Core) =>
  ],
  handle: async (ctx, flags) => {
  if (!flags["id"]) throw new InputValidationError("required option '--id <id>' not specified");
+ const datasetId = flags["id"];
 
  const filePath = flags["file-path"];
  if (!filePath) {
  ctx
  .require(JsonRendererKey)
  .renderJson(
- await core.eval.getDataset(flags["id"], flags["version"], coreOptsFromCtx(ctx)),
+ await core.eval.getDataset(datasetId, flags["version"], coreOptsFromCtx(ctx)),
  );
  return;
  }
 
  // --file-path downloads the contents via the presigned download URL in metadata
- const controller = new AbortController();
- const interrupt = () => controller.abort();
- process.once("SIGINT", interrupt);
- try {
- const response = await core.eval.downloadDataset(
- flags["id"],
+ const response = await withUserCancellation((signal) =>
+ core.eval.downloadDataset(
+ datasetId,
  flags["version"],
  filePath,
  coreOptsFromCtx(ctx),
- controller.signal,
- );
- // file is written in addition to the normal metadata output
- ctx.require(JsonRendererKey).renderJson({ ...response, filePath });
- } finally {
- process.removeListener("SIGINT", interrupt);
- }
+ signal,
+ ),
+ );
+ // file is written in addition to the normal metadata output
+ ctx.require(JsonRendererKey).renderJson({ ...response, filePath });
  },
  });

src/handlers/eval/dataset/update/index.tsx

@@ -3,6 +3,7 @@ import { createHandler, flag } from "../../../../router";
 import { InputValidationError } from "../../../../errors";
 import type { AppIO } from "../../../../io";
 import { JsonRendererKey } from "../../../../tui";
+import { withUserCancellation } from "../../../../runnable";
 import type { Core } from "../../../types";
 import { coreOptsFromCtx } from "../../../utils";
 
@@ -16,27 +17,24 @@ export const createUpdateDatasetHandler = (core: Core, io: AppIO) =>
  ],
  handle: async (ctx, flags) => {
  if (!flags["id"]) throw new InputValidationError("required option '--id <id>' not specified");
+ const datasetId = flags["id"];
  if (!flags["file-path"]) {
  throw new InputValidationError("required option '--file-path <file-path>' not specified");
  }
+ const filePath = flags["file-path"];
 
- const controller = new AbortController();
- const interrupt = () => controller.abort();
- process.once("SIGINT", interrupt);
- try {
- ctx
- .require(JsonRendererKey)
- .renderJson(
- await core.eval.updateDatasetExamples(
- flags["id"],
- flags["file-path"],
+ ctx
+ .require(JsonRendererKey)
+ .renderJson(
+ await withUserCancellation((signal) =>
+ core.eval.updateDatasetExamples(
+ datasetId,
+ filePath,
  coreOptsFromCtx(ctx),
-controller.signal,
+ signal,
  (event) => io.stderr.write(`${event.message}\n`),
  ),
- );
- } finally {
- process.removeListener("SIGINT", interrupt);
- }
+ ),
+ );
  },
  });

src/errors/errors.test.tsx

@@ -4,7 +4,13 @@ import {
  ValidationException,
  InternalServerException,
 } from "@aws-sdk/client-bedrock-agentcore-control";
-import { AgentCoreCLIError, InputValidationError } from "./errors";
+import { CommanderError } from "commander";
+import {
+ AgentCoreCLIError,
+ InputValidationError,
+ SilentCLIError,
+ UserCancellationError,
+} from "./errors";
 
 describe("AgentCoreCLIError", () => {
  test("fromError preserves existing AgentCoreCLIError instances", () => {
@@ -17,6 +23,43 @@ describe("AgentCoreCLIError", () => {
  expect(AgentCoreCLIError.fromError(err)).toBe(err);
  });
 
+ test.each([
+ ["parse failures", new CommanderError(1, "commander.invalidArgument", "invalid option"), 2],
+ ["help", new CommanderError(0, "commander.helpDisplayed", "help displayed"), 0],
+ ])("fromError classifies Commander %s", (_label, err, exitCode) => {
+ const result = AgentCoreCLIError.fromError(err);
+ expect(result).toBeInstanceOf(SilentCLIError);
+ expect(result.json()).toMatchObject({
+ name: "CommanderError",
+ source: "user",
+ exitCode,
+ meta: { code: err.code },
+ });
+ });
+
+ test("UserCancellationError is a silent user interruption", () => {
+ const error = new UserCancellationError();
+ expect(error).toBeInstanceOf(SilentCLIError);
+ expect(error.json()).toMatchObject({
+ name: "UserCancellationError",
+ message: "Operation cancelled by user",
+ source: "user",
+ exitCode: 130,
+ });
+ });
+
+ test("UserCancellationError resolves direct and signal-propagated cancellation", () => {
+ const cancellation = new UserCancellationError();
+ const controller = new AbortController();
+ controller.abort(cancellation);
+
+ expect(UserCancellationError.resolve(cancellation)).toBe(cancellation);
+ expect(UserCancellationError.resolve(new Error("transport aborted"), controller.signal)).toBe(
+ cancellation,
+ );
+ expect(UserCancellationError.resolve(new Error("failed"))).toBeUndefined();
+ });
+
  test.each([
  [
  "AccessDeniedException (403)",

src/errors/errors.tsx

@@ -1,4 +1,5 @@
 import { ServiceException } from "@smithy/core/client";
+import { CommanderError } from "commander";
 import { join } from "node:path";
 import { ERROR_SOURCE, type ErrorSource } from "./types";
 
@@ -41,6 +42,16 @@ export class AgentCoreCLIError extends Error {
  static fromError(error: unknown): AgentCoreCLIError {
  if (error instanceof AgentCoreCLIError) return error;
 
+ if (error instanceof CommanderError) {
+ return new SilentCLIError(error.message, {
+ cause: error,
+ source: ERROR_SOURCE.USER,
+ name: error.name,
+ meta: { code: error.code },
+ exitCode: error.exitCode === 0 ? 0 : 2,
+ });
+ }
+
  if (ServiceException.isInstance(error)) {
  const httpStatusCode = error.$metadata.httpStatusCode;
  const source =
@@ -62,6 +73,9 @@ export class AgentCoreCLIError extends Error {
  }
 }
 
+/** Base for CLI errors intentionally omitted from root stderr output. */
+export class SilentCLIError extends AgentCoreCLIError {}
+
 /** Error raised for invalid user input. */
 export class InputValidationError extends AgentCoreCLIError {
  constructor(message?: string, options?: Omit<AgentCoreCLIErrorOptions, "source">) {
@@ -137,39 +151,28 @@ export class EmbeddedAssetNotFoundError extends AgentCoreCLIError {
  }
 }
 
-export class CommandInterruptedError extends AgentCoreCLIError {
- readonly reported: boolean;
+/** Raised when a user intentionally cancels a headless CLI operation. */
+export class UserCancellationError extends SilentCLIError {
+ constructor() {
+ super("Operation cancelled by user", {
+ source: ERROR_SOURCE.USER,
+ exitCode: 130,
+ });
+ }
 
- constructor(cause?: unknown, reported = false) {
- super("The operation was aborted", { cause, exitCode: 130 });
- this.name = "AbortError";
- this.reported = reported;
+ static resolve(error: unknown, signal?: AbortSignal): UserCancellationError | undefined {
+ if (error instanceof UserCancellationError) return error;
+ return signal?.reason instanceof UserCancellationError ? signal.reason : undefined;
  }
 }
 
-export class RuntimeInvokeInterruptedError extends CommandInterruptedError {}
-
-export class RuntimeInvokeResponseError extends AgentCoreCLIError {
- readonly reported = true;
-
+export class RuntimeInvokeResponseError extends SilentCLIError {
  constructor(message: string, cause?: unknown) {
  super(message, { cause });
  }
 }
 
-export class GatewayInvokeInterruptedError extends AgentCoreCLIError {
- readonly reported: boolean;
-
- constructor(cause?: unknown, reported = false) {
- super("The operation was aborted", { cause, exitCode: 130 });
- this.name = "AbortError";
- this.reported = reported;
- }
-}
-
-export class GatewayInvokeResponseError extends AgentCoreCLIError {
- readonly reported = true;
-
+export class GatewayInvokeResponseError extends SilentCLIError {
  constructor(message: string, cause?: unknown) {
  super(message, { cause });
  }

src/errors/index.tsx

@@ -1,11 +1,9 @@
 export {
  AgentCoreCLIError,
  CloudWatchQueryError,
- CommandInterruptedError,
  DeserializationError,
  EmbeddedAssetNotFoundError,
  FileWriteError,
- GatewayInvokeInterruptedError,
  GatewayInvokeResponseError,
  InputValidationError,
  InvalidEnvironmentError,
@@ -16,9 +14,10 @@ export {
  ProjectFileExistsError,
  ResourceNotFoundError,
  ResultTruncationError,
- RuntimeInvokeInterruptedError,
  RuntimeInvokeResponseError,
+ SilentCLIError,
  SourceResolutionError,
+ UserCancellationError,
  type AgentCoreCLIErrorOptions,
 } from "./errors";
 export { ERROR_SOURCE } from "./types";

src/handlers/eval/dataset/dataset.test.tsx

@@ -8,7 +8,9 @@ import {
  TestCoreClient,
  TestGlobalConfigAccessor,
  testIO,
+ waitFor,
 } from "../../../testing";
+import { UserCancellationError } from "../../../errors";
 import { createRootHandler } from "../../index";
 import type { CreateDatasetInput } from "../types";
 
@@ -442,6 +444,41 @@ describe("dataset get", () => {
  expect(call?.args.slice(0, 3)).toEqual(["dataset-orders-abc123", "2", "/tmp/v2.jsonl"]);
  });
 
+ test("SIGINT cancels a download with the shared user cancellation error", async () => {
+ const { core, route } = testDatasetCommand();
+ core.eval.downloadDataset = async (id, version, filePath, options, signal) => {
+ core.eval.calls.push({
+ method: "downloadDataset",
+ args: [id, version, filePath, options, signal],
+ });
+ return new Promise<never>((_, reject) => {
+ const abort = () => reject(signal?.reason);
+ if (signal?.aborted) abort();
+ else signal?.addEventListener("abort", abort, { once: true });
+ });
+ };
+ const pending = route([
+ "eval",
+ "dataset",
+ "get",
+ "--id",
+ "dataset-orders-abc123",
+ "--file-path",
+ "/tmp/out.jsonl",
+ ]);
+
+ try {
+ await waitFor(() => core.eval.calls.some((call) => call.method === "downloadDataset"));
+ process.emit("SIGINT", "SIGINT");
+
+ const signal = core.eval.calls[0]!.args[4] as AbortSignal;
+ expect(signal.reason).toBeInstanceOf(UserCancellationError);
+ await expect(pending).rejects.toBe(signal.reason);
+ } finally {
+ await pending.catch(() => undefined);
+ }
+ });
+
  test("requires --id", async () => {
  const { core, route } = testDatasetCommand();
 
@@ -621,6 +658,42 @@ describe("dataset update", () => {
  });
  });
 
+ test("SIGINT cancels an update with the shared user cancellation error", async () => {
+ const path = writeTempJsonl(EXAMPLE_A);
+ const { core, route } = testDatasetCommand();
+ core.eval.updateDatasetExamples = async (id, filePath, options, signal, onProgress) => {
+ core.eval.calls.push({
+ method: "updateDatasetExamples",
+ args: [id, filePath, options, signal, onProgress],
+ });
+ return new Promise<never>((_, reject) => {
+ const abort = () => reject(signal?.reason);
+ if (signal?.aborted) abort();
+ else signal?.addEventListener("abort", abort, { once: true });
+ });
+ };
+ const pending = route([
+ "eval",
+ "dataset",
+ "update",
+ "--id",
+ "dataset-orders-abc123",
+ "--file-path",
+ path,
+ ]);
+
+ try {
+ await waitFor(() => core.eval.calls.some((call) => call.method === "updateDatasetExamples"));
+ process.emit("SIGINT", "SIGINT");
+
+ const signal = core.eval.calls[0]!.args[3] as AbortSignal;
+ expect(signal.reason).toBeInstanceOf(UserCancellationError);
+ await expect(pending).rejects.toBe(signal.reason);
+ } finally {
+ await pending.catch(() => undefined);
+ }
+ });
+
  test("takes only --id and --file-path", async () => {
  const root = createRootHandler(new TestCoreClient(), {
  io: testIO().io,

src/handlers/eval/dataset/get/index.tsx

@@ -2,6 +2,7 @@ import z from "zod";
 import { createHandler, flag } from "../../../../router";
 import { InputValidationError } from "../../../../errors";
 import { JsonRendererKey } from "../../../../tui";
+import { withUserCancellation } from "../../../../runnable";
 import type { Core } from "../../../types";
 import { coreOptsFromCtx } from "../../../utils";
 
@@ -24,33 +25,29 @@ export const createGetDatasetHandler = (core: Core) =>
  ],
  handle: async (ctx, flags) => {
  if (!flags["id"]) throw new InputValidationError("required option '--id <id>' not specified");
+ const datasetId = flags["id"];
 
  const filePath = flags["file-path"];
  if (!filePath) {
  ctx
  .require(JsonRendererKey)
  .renderJson(
- await core.eval.getDataset(flags["id"], flags["version"], coreOptsFromCtx(ctx)),
+ await core.eval.getDataset(datasetId, flags["version"], coreOptsFromCtx(ctx)),
  );
  return;
  }
 
  // --file-path downloads the contents via the presigned download URL in metadata
- const controller = new AbortController();
- const interrupt = () => controller.abort();
- process.once("SIGINT", interrupt);
- try {
- const response = await core.eval.downloadDataset(
- flags["id"],
+ const response = await withUserCancellation((signal) =>
+ core.eval.downloadDataset(
+ datasetId,
  flags["version"],
  filePath,
  coreOptsFromCtx(ctx),
- controller.signal,
- );
- // file is written in addition to the normal metadata output
- ctx.require(JsonRendererKey).renderJson({ ...response, filePath });
- } finally {
- process.removeListener("SIGINT", interrupt);
- }
+ signal,
+ ),
+ );
+ // file is written in addition to the normal metadata output
+ ctx.require(JsonRendererKey).renderJson({ ...response, filePath });
  },
  });

src/handlers/eval/dataset/update/index.tsx

@@ -3,6 +3,7 @@ import { createHandler, flag } from "../../../../router";
 import { InputValidationError } from "../../../../errors";
 import type { AppIO } from "../../../../io";
 import { JsonRendererKey } from "../../../../tui";
+import { withUserCancellation } from "../../../../runnable";
 import type { Core } from "../../../types";
 import { coreOptsFromCtx } from "../../../utils";
 
@@ -16,27 +17,24 @@ export const createUpdateDatasetHandler = (core: Core, io: AppIO) =>
  ],
  handle: async (ctx, flags) => {
  if (!flags["id"]) throw new InputValidationError("required option '--id <id>' not specified");
+ const datasetId = flags["id"];
  if (!flags["file-path"]) {
  throw new InputValidationError("required option '--file-path <file-path>' not specified");
  }
+ const filePath = flags["file-path"];
 
- const controller = new AbortController();
- const interrupt = () => controller.abort();
- process.once("SIGINT", interrupt);
- try {
- ctx
- .require(JsonRendererKey)
- .renderJson(
- await core.eval.updateDatasetExamples(
- flags["id"],
- flags["file-path"],
+ ctx
+ .require(JsonRendererKey)
+ .renderJson(
+ await withUserCancellation((signal) =>
+ core.eval.updateDatasetExamples(
+ datasetId,
+ filePath,
  coreOptsFromCtx(ctx),
-controller.signal,
+ signal,
  (event) => io.stderr.write(`${event.message}\n`),
  ),
- );
- } finally {
- process.removeListener("SIGINT", interrupt);
- }
+ ),
+ );
  },
  });

src/errors/errors.test.tsx

@@ -4,7 +4,13 @@ import {
  ValidationException,
  InternalServerException,
 } from "@aws-sdk/client-bedrock-agentcore-control";
-import { AgentCoreCLIError, InputValidationError } from "./errors";
+import { CommanderError } from "commander";
+import {
+ AgentCoreCLIError,
+ InputValidationError,
+ SilentCLIError,
+ UserCancellationError,
+} from "./errors";
 
 describe("AgentCoreCLIError", () => {
  test("fromError preserves existing AgentCoreCLIError instances", () => {
@@ -17,6 +23,43 @@ describe("AgentCoreCLIError", () => {
  expect(AgentCoreCLIError.fromError(err)).toBe(err);
  });
 
+ test.each([
+ ["parse failures", new CommanderError(1, "commander.invalidArgument", "invalid option"), 2],
+ ["help", new CommanderError(0, "commander.helpDisplayed", "help displayed"), 0],
+ ])("fromError classifies Commander %s", (_label, err, exitCode) => {
+ const result = AgentCoreCLIError.fromError(err);
+ expect(result).toBeInstanceOf(SilentCLIError);
+ expect(result.json()).toMatchObject({
+ name: "CommanderError",
+ source: "user",
+ exitCode,
+ meta: { code: err.code },
+ });
+ });
+
+ test("UserCancellationError is a silent user interruption", () => {
+ const error = new UserCancellationError();
+ expect(error).toBeInstanceOf(SilentCLIError);
+ expect(error.json()).toMatchObject({
+ name: "UserCancellationError",
+ message: "Operation cancelled by user",
+ source: "user",
+ exitCode: 130,
+ });
+ });
+
+ test("UserCancellationError resolves direct and signal-propagated cancellation", () => {
+ const cancellation = new UserCancellationError();
+ const controller = new AbortController();
+ controller.abort(cancellation);
+
+ expect(UserCancellationError.resolve(cancellation)).toBe(cancellation);
+ expect(UserCancellationError.resolve(new Error("transport aborted"), controller.signal)).toBe(
+ cancellation,
+ );
+ expect(UserCancellationError.resolve(new Error("failed"))).toBeUndefined();
+ });
+
  test.each([
  [
  "AccessDeniedException (403)",

src/errors/errors.tsx

@@ -1,4 +1,5 @@
 import { ServiceException } from "@smithy/core/client";
+import { CommanderError } from "commander";
 import { join } from "node:path";
 import { ERROR_SOURCE, type ErrorSource } from "./types";
 
@@ -41,6 +42,16 @@ export class AgentCoreCLIError extends Error {
  static fromError(error: unknown): AgentCoreCLIError {
  if (error instanceof AgentCoreCLIError) return error;
 
+ if (error instanceof CommanderError) {
+ return new SilentCLIError(error.message, {
+ cause: error,
+ source: ERROR_SOURCE.USER,
+ name: error.name,
+ meta: { code: error.code },
+ exitCode: error.exitCode === 0 ? 0 : 2,
+ });
+ }
+
  if (ServiceException.isInstance(error)) {
  const httpStatusCode = error.$metadata.httpStatusCode;
  const source =
@@ -62,6 +73,9 @@ export class AgentCoreCLIError extends Error {
  }
 }
 
+/** Base for CLI errors intentionally omitted from root stderr output. */
+export class SilentCLIError extends AgentCoreCLIError {}
+
 /** Error raised for invalid user input. */
 export class InputValidationError extends AgentCoreCLIError {
  constructor(message?: string, options?: Omit<AgentCoreCLIErrorOptions, "source">) {
@@ -137,39 +151,28 @@ export class EmbeddedAssetNotFoundError extends AgentCoreCLIError {
  }
 }
 
-export class CommandInterruptedError extends AgentCoreCLIError {
- readonly reported: boolean;
+/** Raised when a user intentionally cancels a headless CLI operation. */
+export class UserCancellationError extends SilentCLIError {
+ constructor() {
+ super("Operation cancelled by user", {
+ source: ERROR_SOURCE.USER,
+ exitCode: 130,
+ });
+ }
 
- constructor(cause?: unknown, reported = false) {
- super("The operation was aborted", { cause, exitCode: 130 });
- this.name = "AbortError";
- this.reported = reported;
+ static resolve(error: unknown, signal?: AbortSignal): UserCancellationError | undefined {
+ if (error instanceof UserCancellationError) return error;
+ return signal?.reason instanceof UserCancellationError ? signal.reason : undefined;
  }
 }
 
-export class RuntimeInvokeInterruptedError extends CommandInterruptedError {}
-
-export class RuntimeInvokeResponseError extends AgentCoreCLIError {
- readonly reported = true;
-
+export class RuntimeInvokeResponseError extends SilentCLIError {
  constructor(message: string, cause?: unknown) {
  super(message, { cause });
  }
 }
 
-export class GatewayInvokeInterruptedError extends AgentCoreCLIError {
- readonly reported: boolean;
-
- constructor(cause?: unknown, reported = false) {
- super("The operation was aborted", { cause, exitCode: 130 });
- this.name = "AbortError";
- this.reported = reported;
- }
-}
-
-export class GatewayInvokeResponseError extends AgentCoreCLIError {
- readonly reported = true;
-
+export class GatewayInvokeResponseError extends SilentCLIError {
  constructor(message: string, cause?: unknown) {
  super(message, { cause });
  }

src/errors/index.tsx

@@ -1,11 +1,9 @@
 export {
  AgentCoreCLIError,
  CloudWatchQueryError,
- CommandInterruptedError,
  DeserializationError,
  EmbeddedAssetNotFoundError,
  FileWriteError,
- GatewayInvokeInterruptedError,
  GatewayInvokeResponseError,
  InputValidationError,
  InvalidEnvironmentError,
@@ -16,9 +14,10 @@ export {
  ProjectFileExistsError,
  ResourceNotFoundError,
  ResultTruncationError,
- RuntimeInvokeInterruptedError,
  RuntimeInvokeResponseError,
+ SilentCLIError,
  SourceResolutionError,
+ UserCancellationError,
  type AgentCoreCLIErrorOptions,
 } from "./errors";
 export { ERROR_SOURCE } from "./types";

src/handlers/eval/dataset/dataset.test.tsx

@@ -8,7 +8,9 @@ import {
  TestCoreClient,
  TestGlobalConfigAccessor,
  testIO,
+ waitFor,
 } from "../../../testing";
+import { UserCancellationError } from "../../../errors";
 import { createRootHandler } from "../../index";
 import type { CreateDatasetInput } from "../types";
 
@@ -442,6 +444,41 @@ describe("dataset get", () => {
  expect(call?.args.slice(0, 3)).toEqual(["dataset-orders-abc123", "2", "/tmp/v2.jsonl"]);
  });
 
+ test("SIGINT cancels a download with the shared user cancellation error", async () => {
+ const { core, route } = testDatasetCommand();
+ core.eval.downloadDataset = async (id, version, filePath, options, signal) => {
+ core.eval.calls.push({
+ method: "downloadDataset",
+ args: [id, version, filePath, options, signal],
+ });
+ return new Promise<never>((_, reject) => {
+ const abort = () => reject(signal?.reason);
+ if (signal?.aborted) abort();
+ else signal?.addEventListener("abort", abort, { once: true });
+ });
+ };
+ const pending = route([
+ "eval",
+ "dataset",
+ "get",
+ "--id",
+ "dataset-orders-abc123",
+ "--file-path",
+ "/tmp/out.jsonl",
+ ]);
+
+ try {
+ await waitFor(() => core.eval.calls.some((call) => call.method === "downloadDataset"));
+ process.emit("SIGINT", "SIGINT");
+
+ const signal = core.eval.calls[0]!.args[4] as AbortSignal;
+ expect(signal.reason).toBeInstanceOf(UserCancellationError);
+ await expect(pending).rejects.toBe(signal.reason);
+ } finally {
+ await pending.catch(() => undefined);
+ }
+ });
+
  test("requires --id", async () => {
  const { core, route } = testDatasetCommand();
 
@@ -621,6 +658,42 @@ describe("dataset update", () => {
  });
  });
 
+ test("SIGINT cancels an update with the shared user cancellation error", async () => {
+ const path = writeTempJsonl(EXAMPLE_A);
+ const { core, route } = testDatasetCommand();
+ core.eval.updateDatasetExamples = async (id, filePath, options, signal, onProgress) => {
+ core.eval.calls.push({
+ method: "updateDatasetExamples",
+ args: [id, filePath, options, signal, onProgress],
+ });
+ return new Promise<never>((_, reject) => {
+ const abort = () => reject(signal?.reason);
+ if (signal?.aborted) abort();
+ else signal?.addEventListener("abort", abort, { once: true });
+ });
+ };
+ const pending = route([
+ "eval",
+ "dataset",
+ "update",
+ "--id",
+ "dataset-orders-abc123",
+ "--file-path",
+ path,
+ ]);
+
+ try {
+ await waitFor(() => core.eval.calls.some((call) => call.method === "updateDatasetExamples"));
+ process.emit("SIGINT", "SIGINT");
+
+ const signal = core.eval.calls[0]!.args[3] as AbortSignal;
+ expect(signal.reason).toBeInstanceOf(UserCancellationError);
+ await expect(pending).rejects.toBe(signal.reason);
+ } finally {
+ await pending.catch(() => undefined);
+ }
+ });
+
  test("takes only --id and --file-path", async () => {
  const root = createRootHandler(new TestCoreClient(), {
  io: testIO().io,

src/handlers/eval/dataset/get/index.tsx

@@ -2,6 +2,7 @@ import z from "zod";
 import { createHandler, flag } from "../../../../router";
 import { InputValidationError } from "../../../../errors";
 import { JsonRendererKey } from "../../../../tui";
+import { withUserCancellation } from "../../../../runnable";
 import type { Core } from "../../../types";
 import { coreOptsFromCtx } from "../../../utils";
 
@@ -24,33 +25,29 @@ export const createGetDatasetHandler = (core: Core) =>
  ],
  handle: async (ctx, flags) => {
  if (!flags["id"]) throw new InputValidationError("required option '--id <id>' not specified");
+ const datasetId = flags["id"];
 
  const filePath = flags["file-path"];
  if (!filePath) {
  ctx
  .require(JsonRendererKey)
  .renderJson(
- await core.eval.getDataset(flags["id"], flags["version"], coreOptsFromCtx(ctx)),
+ await core.eval.getDataset(datasetId, flags["version"], coreOptsFromCtx(ctx)),
  );
  return;
  }
 
  // --file-path downloads the contents via the presigned download URL in metadata
- const controller = new AbortController();
- const interrupt = () => controller.abort();
- process.once("SIGINT", interrupt);
- try {
- const response = await core.eval.downloadDataset(
- flags["id"],
+ const response = await withUserCancellation((signal) =>
+ core.eval.downloadDataset(
+ datasetId,
  flags["version"],
  filePath,
  coreOptsFromCtx(ctx),
- controller.signal,
- );
- // file is written in addition to the normal metadata output
- ctx.require(JsonRendererKey).renderJson({ ...response, filePath });
- } finally {
- process.removeListener("SIGINT", interrupt);
- }
+ signal,
+ ),
+ );
+ // file is written in addition to the normal metadata output
+ ctx.require(JsonRendererKey).renderJson({ ...response, filePath });
  },
  });

src/handlers/eval/dataset/update/index.tsx

@@ -3,6 +3,7 @@ import { createHandler, flag } from "../../../../router";
 import { InputValidationError } from "../../../../errors";
 import type { AppIO } from "../../../../io";
 import { JsonRendererKey } from "../../../../tui";
+import { withUserCancellation } from "../../../../runnable";
 import type { Core } from "../../../types";
 import { coreOptsFromCtx } from "../../../utils";
 
@@ -16,27 +17,24 @@ export const createUpdateDatasetHandler = (core: Core, io: AppIO) =>
  ],
  handle: async (ctx, flags) => {
  if (!flags["id"]) throw new InputValidationError("required option '--id <id>' not specified");
+ const datasetId = flags["id"];
  if (!flags["file-path"]) {
  throw new InputValidationError("required option '--file-path <file-path>' not specified");
  }
+ const filePath = flags["file-path"];
 
- const controller = new AbortController();
- const interrupt = () => controller.abort();
- process.once("SIGINT", interrupt);
- try {
- ctx
- .require(JsonRendererKey)
- .renderJson(
- await core.eval.updateDatasetExamples(
- flags["id"],
- flags["file-path"],
+ ctx
+ .require(JsonRendererKey)
+ .renderJson(
+ await withUserCancellation((signal) =>
+ core.eval.updateDatasetExamples(
+ datasetId,
+ filePath,
  coreOptsFromCtx(ctx),
-controller.signal,
+ signal,
  (event) => io.stderr.write(`${event.message}\n`),
  ),
- );
- } finally {
- process.removeListener("SIGINT", interrupt);
- }
+ ),
+ );
  },
  });

src/errors/errors.test.tsx

@@ -4,7 +4,13 @@ import {
  ValidationException,
  InternalServerException,
 } from "@aws-sdk/client-bedrock-agentcore-control";
-import { AgentCoreCLIError, InputValidationError } from "./errors";
+import { CommanderError } from "commander";
+import {
+ AgentCoreCLIError,
+ InputValidationError,
+ SilentCLIError,
+ UserCancellationError,
+} from "./errors";
 
 describe("AgentCoreCLIError", () => {
  test("fromError preserves existing AgentCoreCLIError instances", () => {
@@ -17,6 +23,43 @@ describe("AgentCoreCLIError", () => {
  expect(AgentCoreCLIError.fromError(err)).toBe(err);
  });
 
+ test.each([
+ ["parse failures", new CommanderError(1, "commander.invalidArgument", "invalid option"), 2],
+ ["help", new CommanderError(0, "commander.helpDisplayed", "help displayed"), 0],
+ ])("fromError classifies Commander %s", (_label, err, exitCode) => {
+ const result = AgentCoreCLIError.fromError(err);
+ expect(result).toBeInstanceOf(SilentCLIError);
+ expect(result.json()).toMatchObject({
+ name: "CommanderError",
+ source: "user",
+ exitCode,
+ meta: { code: err.code },
+ });
+ });
+
+ test("UserCancellationError is a silent user interruption", () => {
+ const error = new UserCancellationError();
+ expect(error).toBeInstanceOf(SilentCLIError);
+ expect(error.json()).toMatchObject({
+ name: "UserCancellationError",
+ message: "Operation cancelled by user",
+ source: "user",
+ exitCode: 130,
+ });
+ });
+
+ test("UserCancellationError resolves direct and signal-propagated cancellation", () => {
+ const cancellation = new UserCancellationError();
+ const controller = new AbortController();
+ controller.abort(cancellation);
+
+ expect(UserCancellationError.resolve(cancellation)).toBe(cancellation);
+ expect(UserCancellationError.resolve(new Error("transport aborted"), controller.signal)).toBe(
+ cancellation,
+ );
+ expect(UserCancellationError.resolve(new Error("failed"))).toBeUndefined();
+ });
+
  test.each([
  [
  "AccessDeniedException (403)",

src/errors/errors.tsx

@@ -1,4 +1,5 @@
 import { ServiceException } from "@smithy/core/client";
+import { CommanderError } from "commander";
 import { join } from "node:path";
 import { ERROR_SOURCE, type ErrorSource } from "./types";
 
@@ -41,6 +42,16 @@ export class AgentCoreCLIError extends Error {
  static fromError(error: unknown): AgentCoreCLIError {
  if (error instanceof AgentCoreCLIError) return error;
 
+ if (error instanceof CommanderError) {
+ return new SilentCLIError(error.message, {
+ cause: error,
+ source: ERROR_SOURCE.USER,
+ name: error.name,
+ meta: { code: error.code },
+ exitCode: error.exitCode === 0 ? 0 : 2,
+ });
+ }
+
  if (ServiceException.isInstance(error)) {
  const httpStatusCode = error.$metadata.httpStatusCode;
  const source =
@@ -62,6 +73,9 @@ export class AgentCoreCLIError extends Error {
  }
 }
 
+/** Base for CLI errors intentionally omitted from root stderr output. */
+export class SilentCLIError extends AgentCoreCLIError {}
+
 /** Error raised for invalid user input. */
 export class InputValidationError extends AgentCoreCLIError {
  constructor(message?: string, options?: Omit<AgentCoreCLIErrorOptions, "source">) {
@@ -137,39 +151,28 @@ export class EmbeddedAssetNotFoundError extends AgentCoreCLIError {
  }
 }
 
-export class CommandInterruptedError extends AgentCoreCLIError {
- readonly reported: boolean;
+/** Raised when a user intentionally cancels a headless CLI operation. */
+export class UserCancellationError extends SilentCLIError {
+ constructor() {
+ super("Operation cancelled by user", {
+ source: ERROR_SOURCE.USER,
+ exitCode: 130,
+ });
+ }
 
- constructor(cause?: unknown, reported = false) {
- super("The operation was aborted", { cause, exitCode: 130 });
- this.name = "AbortError";
- this.reported = reported;
+ static resolve(error: unknown, signal?: AbortSignal): UserCancellationError | undefined {
+ if (error instanceof UserCancellationError) return error;
+ return signal?.reason instanceof UserCancellationError ? signal.reason : undefined;
  }
 }
 
-export class RuntimeInvokeInterruptedError extends CommandInterruptedError {}
-
-export class RuntimeInvokeResponseError extends AgentCoreCLIError {
- readonly reported = true;
-
+export class RuntimeInvokeResponseError extends SilentCLIError {
  constructor(message: string, cause?: unknown) {
  super(message, { cause });
  }
 }
 
-export class GatewayInvokeInterruptedError extends AgentCoreCLIError {
- readonly reported: boolean;
-
- constructor(cause?: unknown, reported = false) {
- super("The operation was aborted", { cause, exitCode: 130 });
- this.name = "AbortError";
- this.reported = reported;
- }
-}
-
-export class GatewayInvokeResponseError extends AgentCoreCLIError {
- readonly reported = true;
-
+export class GatewayInvokeResponseError extends SilentCLIError {
  constructor(message: string, cause?: unknown) {
  super(message, { cause });
  }

src/errors/index.tsx

@@ -1,11 +1,9 @@
 export {
  AgentCoreCLIError,
  CloudWatchQueryError,
- CommandInterruptedError,
  DeserializationError,
  EmbeddedAssetNotFoundError,
  FileWriteError,
- GatewayInvokeInterruptedError,
  GatewayInvokeResponseError,
  InputValidationError,
  InvalidEnvironmentError,
@@ -16,9 +14,10 @@ export {
  ProjectFileExistsError,
  ResourceNotFoundError,
  ResultTruncationError,
- RuntimeInvokeInterruptedError,
  RuntimeInvokeResponseError,
+ SilentCLIError,
  SourceResolutionError,
+ UserCancellationError,
  type AgentCoreCLIErrorOptions,
 } from "./errors";
 export { ERROR_SOURCE } from "./types";

src/handlers/eval/dataset/dataset.test.tsx

@@ -8,7 +8,9 @@ import {
  TestCoreClient,
  TestGlobalConfigAccessor,
  testIO,
+ waitFor,
 } from "../../../testing";
+import { UserCancellationError } from "../../../errors";
 import { createRootHandler } from "../../index";
 import type { CreateDatasetInput } from "../types";
 
@@ -442,6 +444,41 @@ describe("dataset get", () => {
  expect(call?.args.slice(0, 3)).toEqual(["dataset-orders-abc123", "2", "/tmp/v2.jsonl"]);
  });
 
+ test("SIGINT cancels a download with the shared user cancellation error", async () => {
+ const { core, route } = testDatasetCommand();
+ core.eval.downloadDataset = async (id, version, filePath, options, signal) => {
+ core.eval.calls.push({
+ method: "downloadDataset",
+ args: [id, version, filePath, options, signal],
+ });
+ return new Promise<never>((_, reject) => {
+ const abort = () => reject(signal?.reason);
+ if (signal?.aborted) abort();
+ else signal?.addEventListener("abort", abort, { once: true });
+ });
+ };
+ const pending = route([
+ "eval",
+ "dataset",
+ "get",
+ "--id",
+ "dataset-orders-abc123",
+ "--file-path",
+ "/tmp/out.jsonl",
+ ]);
+
+ try {
+ await waitFor(() => core.eval.calls.some((call) => call.method === "downloadDataset"));
+ process.emit("SIGINT", "SIGINT");
+
+ const signal = core.eval.calls[0]!.args[4] as AbortSignal;
+ expect(signal.reason).toBeInstanceOf(UserCancellationError);
+ await expect(pending).rejects.toBe(signal.reason);
+ } finally {
+ await pending.catch(() => undefined);
+ }
+ });
+
  test("requires --id", async () => {
  const { core, route } = testDatasetCommand();
 
@@ -621,6 +658,42 @@ describe("dataset update", () => {
  });
  });
 
+ test("SIGINT cancels an update with the shared user cancellation error", async () => {
+ const path = writeTempJsonl(EXAMPLE_A);
+ const { core, route } = testDatasetCommand();
+ core.eval.updateDatasetExamples = async (id, filePath, options, signal, onProgress) => {
+ core.eval.calls.push({
+ method: "updateDatasetExamples",
+ args: [id, filePath, options, signal, onProgress],
+ });
+ return new Promise<never>((_, reject) => {
+ const abort = () => reject(signal?.reason);
+ if (signal?.aborted) abort();
+ else signal?.addEventListener("abort", abort, { once: true });
+ });
+ };
+ const pending = route([
+ "eval",
+ "dataset",
+ "update",
+ "--id",
+ "dataset-orders-abc123",
+ "--file-path",
+ path,
+ ]);
+
+ try {
+ await waitFor(() => core.eval.calls.some((call) => call.method === "updateDatasetExamples"));
+ process.emit("SIGINT", "SIGINT");
+
+ const signal = core.eval.calls[0]!.args[3] as AbortSignal;
+ expect(signal.reason).toBeInstanceOf(UserCancellationError);
+ await expect(pending).rejects.toBe(signal.reason);
+ } finally {
+ await pending.catch(() => undefined);
+ }
+ });
+
  test("takes only --id and --file-path", async () => {
  const root = createRootHandler(new TestCoreClient(), {
  io: testIO().io,

src/handlers/eval/dataset/get/index.tsx

@@ -2,6 +2,7 @@ import z from "zod";
 import { createHandler, flag } from "../../../../router";
 import { InputValidationError } from "../../../../errors";
 import { JsonRendererKey } from "../../../../tui";
+import { withUserCancellation } from "../../../../runnable";
 import type { Core } from "../../../types";
 import { coreOptsFromCtx } from "../../../utils";
 
@@ -24,33 +25,29 @@ export const createGetDatasetHandler = (core: Core) =>
  ],
  handle: async (ctx, flags) => {
  if (!flags["id"]) throw new InputValidationError("required option '--id <id>' not specified");
+ const datasetId = flags["id"];
 
  const filePath = flags["file-path"];
  if (!filePath) {
  ctx
  .require(JsonRendererKey)
  .renderJson(
- await core.eval.getDataset(flags["id"], flags["version"], coreOptsFromCtx(ctx)),
+ await core.eval.getDataset(datasetId, flags["version"], coreOptsFromCtx(ctx)),
  );
  return;
  }
 
  // --file-path downloads the contents via the presigned download URL in metadata
- const controller = new AbortController();
- const interrupt = () => controller.abort();
- process.once("SIGINT", interrupt);
- try {
- const response = await core.eval.downloadDataset(
- flags["id"],
+ const response = await withUserCancellation((signal) =>
+ core.eval.downloadDataset(
+ datasetId,
  flags["version"],
  filePath,
  coreOptsFromCtx(ctx),
- controller.signal,
- );
- // file is written in addition to the normal metadata output
- ctx.require(JsonRendererKey).renderJson({ ...response, filePath });
- } finally {
- process.removeListener("SIGINT", interrupt);
- }
+ signal,
+ ),
+ );
+ // file is written in addition to the normal metadata output
+ ctx.require(JsonRendererKey).renderJson({ ...response, filePath });
  },
  });

src/handlers/eval/dataset/update/index.tsx

@@ -3,6 +3,7 @@ import { createHandler, flag } from "../../../../router";
 import { InputValidationError } from "../../../../errors";
 import type { AppIO } from "../../../../io";
 import { JsonRendererKey } from "../../../../tui";
+import { withUserCancellation } from "../../../../runnable";
 import type { Core } from "../../../types";
 import { coreOptsFromCtx } from "../../../utils";
 
@@ -16,27 +17,24 @@ export const createUpdateDatasetHandler = (core: Core, io: AppIO) =>
  ],
  handle: async (ctx, flags) => {
  if (!flags["id"]) throw new InputValidationError("required option '--id <id>' not specified");
+ const datasetId = flags["id"];
  if (!flags["file-path"]) {
  throw new InputValidationError("required option '--file-path <file-path>' not specified");
  }
+ const filePath = flags["file-path"];
 
- const controller = new AbortController();
- const interrupt = () => controller.abort();
- process.once("SIGINT", interrupt);
- try {
- ctx
- .require(JsonRendererKey)
- .renderJson(
- await core.eval.updateDatasetExamples(
- flags["id"],
- flags["file-path"],
+ ctx
+ .require(JsonRendererKey)
+ .renderJson(
+ await withUserCancellation((signal) =>
+ core.eval.updateDatasetExamples(
+ datasetId,
+ filePath,
  coreOptsFromCtx(ctx),
-controller.signal,
+ signal,
  (event) => io.stderr.write(`${event.message}\n`),
  ),
- );
- } finally {
- process.removeListener("SIGINT", interrupt);
- }
+ ),
+ );
  },
  });

src/errors/errors.test.tsx

@@ -4,7 +4,13 @@ import {
  ValidationException,
  InternalServerException,
 } from "@aws-sdk/client-bedrock-agentcore-control";
-import { AgentCoreCLIError, InputValidationError } from "./errors";
+import { CommanderError } from "commander";
+import {
+ AgentCoreCLIError,
+ InputValidationError,
+ SilentCLIError,
+ UserCancellationError,
+} from "./errors";
 
 describe("AgentCoreCLIError", () => {
  test("fromError preserves existing AgentCoreCLIError instances", () => {
@@ -17,6 +23,43 @@ describe("AgentCoreCLIError", () => {
  expect(AgentCoreCLIError.fromError(err)).toBe(err);
  });
 
+ test.each([
+ ["parse failures", new CommanderError(1, "commander.invalidArgument", "invalid option"), 2],
+ ["help", new CommanderError(0, "commander.helpDisplayed", "help displayed"), 0],
+ ])("fromError classifies Commander %s", (_label, err, exitCode) => {
+ const result = AgentCoreCLIError.fromError(err);
+ expect(result).toBeInstanceOf(SilentCLIError);
+ expect(result.json()).toMatchObject({
+ name: "CommanderError",
+ source: "user",
+ exitCode,
+ meta: { code: err.code },
+ });
+ });
+
+ test("UserCancellationError is a silent user interruption", () => {
+ const error = new UserCancellationError();
+ expect(error).toBeInstanceOf(SilentCLIError);
+ expect(error.json()).toMatchObject({
+ name: "UserCancellationError",
+ message: "Operation cancelled by user",
+ source: "user",
+ exitCode: 130,
+ });
+ });
+
+ test("UserCancellationError resolves direct and signal-propagated cancellation", () => {
+ const cancellation = new UserCancellationError();
+ const controller = new AbortController();
+ controller.abort(cancellation);
+
+ expect(UserCancellationError.resolve(cancellation)).toBe(cancellation);
+ expect(UserCancellationError.resolve(new Error("transport aborted"), controller.signal)).toBe(
+ cancellation,
+ );
+ expect(UserCancellationError.resolve(new Error("failed"))).toBeUndefined();
+ });
+
  test.each([
  [
  "AccessDeniedException (403)",

src/errors/errors.tsx

@@ -1,4 +1,5 @@
 import { ServiceException } from "@smithy/core/client";
+import { CommanderError } from "commander";
 import { join } from "node:path";
 import { ERROR_SOURCE, type ErrorSource } from "./types";
 
@@ -41,6 +42,16 @@ export class AgentCoreCLIError extends Error {
  static fromError(error: unknown): AgentCoreCLIError {
  if (error instanceof AgentCoreCLIError) return error;
 
+ if (error instanceof CommanderError) {
+ return new SilentCLIError(error.message, {
+ cause: error,
+ source: ERROR_SOURCE.USER,
+ name: error.name,
+ meta: { code: error.code },
+ exitCode: error.exitCode === 0 ? 0 : 2,
+ });
+ }
+
  if (ServiceException.isInstance(error)) {
  const httpStatusCode = error.$metadata.httpStatusCode;
  const source =
@@ -62,6 +73,9 @@ export class AgentCoreCLIError extends Error {
  }
 }
 
+/** Base for CLI errors intentionally omitted from root stderr output. */
+export class SilentCLIError extends AgentCoreCLIError {}
+
 /** Error raised for invalid user input. */
 export class InputValidationError extends AgentCoreCLIError {
  constructor(message?: string, options?: Omit<AgentCoreCLIErrorOptions, "source">) {
@@ -137,39 +151,28 @@ export class EmbeddedAssetNotFoundError extends AgentCoreCLIError {
  }
 }
 
-export class CommandInterruptedError extends AgentCoreCLIError {
- readonly reported: boolean;
+/** Raised when a user intentionally cancels a headless CLI operation. */
+export class UserCancellationError extends SilentCLIError {
+ constructor() {
+ super("Operation cancelled by user", {
+ source: ERROR_SOURCE.USER,
+ exitCode: 130,
+ });
+ }
 
- constructor(cause?: unknown, reported = false) {
- super("The operation was aborted", { cause, exitCode: 130 });
- this.name = "AbortError";
- this.reported = reported;
+ static resolve(error: unknown, signal?: AbortSignal): UserCancellationError | undefined {
+ if (error instanceof UserCancellationError) return error;
+ return signal?.reason instanceof UserCancellationError ? signal.reason : undefined;
  }
 }
 
-export class RuntimeInvokeInterruptedError extends CommandInterruptedError {}
-
-export class RuntimeInvokeResponseError extends AgentCoreCLIError {
- readonly reported = true;
-
+export class RuntimeInvokeResponseError extends SilentCLIError {
  constructor(message: string, cause?: unknown) {
  super(message, { cause });
  }
 }
 
-export class GatewayInvokeInterruptedError extends AgentCoreCLIError {
- readonly reported: boolean;
-
- constructor(cause?: unknown, reported = false) {
- super("The operation was aborted", { cause, exitCode: 130 });
- this.name = "AbortError";
- this.reported = reported;
- }
-}
-
-export class GatewayInvokeResponseError extends AgentCoreCLIError {
- readonly reported = true;
-
+export class GatewayInvokeResponseError extends SilentCLIError {
  constructor(message: string, cause?: unknown) {
  super(message, { cause });
  }

src/errors/index.tsx

@@ -1,11 +1,9 @@
 export {
  AgentCoreCLIError,
  CloudWatchQueryError,
- CommandInterruptedError,
  DeserializationError,
  EmbeddedAssetNotFoundError,
  FileWriteError,
- GatewayInvokeInterruptedError,
  GatewayInvokeResponseError,
  InputValidationError,
  InvalidEnvironmentError,
@@ -16,9 +14,10 @@ export {
  ProjectFileExistsError,
  ResourceNotFoundError,
  ResultTruncationError,
- RuntimeInvokeInterruptedError,
  RuntimeInvokeResponseError,
+ SilentCLIError,
  SourceResolutionError,
+ UserCancellationError,
  type AgentCoreCLIErrorOptions,
 } from "./errors";
 export { ERROR_SOURCE } from "./types";

src/handlers/eval/dataset/dataset.test.tsx

@@ -8,7 +8,9 @@ import {
  TestCoreClient,
  TestGlobalConfigAccessor,
  testIO,
+ waitFor,
 } from "../../../testing";
+import { UserCancellationError } from "../../../errors";
 import { createRootHandler } from "../../index";
 import type { CreateDatasetInput } from "../types";
 
@@ -442,6 +444,41 @@ describe("dataset get", () => {
  expect(call?.args.slice(0, 3)).toEqual(["dataset-orders-abc123", "2", "/tmp/v2.jsonl"]);
  });
 
+ test("SIGINT cancels a download with the shared user cancellation error", async () => {
+ const { core, route } = testDatasetCommand();
+ core.eval.downloadDataset = async (id, version, filePath, options, signal) => {
+ core.eval.calls.push({
+ method: "downloadDataset",
+ args: [id, version, filePath, options, signal],
+ });
+ return new Promise<never>((_, reject) => {
+ const abort = () => reject(signal?.reason);
+ if (signal?.aborted) abort();
+ else signal?.addEventListener("abort", abort, { once: true });
+ });
+ };
+ const pending = route([
+ "eval",
+ "dataset",
+ "get",
+ "--id",
+ "dataset-orders-abc123",
+ "--file-path",
+ "/tmp/out.jsonl",
+ ]);
+
+ try {
+ await waitFor(() => core.eval.calls.some((call) => call.method === "downloadDataset"));
+ process.emit("SIGINT", "SIGINT");
+
+ const signal = core.eval.calls[0]!.args[4] as AbortSignal;
+ expect(signal.reason).toBeInstanceOf(UserCancellationError);
+ await expect(pending).rejects.toBe(signal.reason);
+ } finally {
+ await pending.catch(() => undefined);
+ }
+ });
+
  test("requires --id", async () => {
  const { core, route } = testDatasetCommand();
 
@@ -621,6 +658,42 @@ describe("dataset update", () => {
  });
  });
 
+ test("SIGINT cancels an update with the shared user cancellation error", async () => {
+ const path = writeTempJsonl(EXAMPLE_A);
+ const { core, route } = testDatasetCommand();
+ core.eval.updateDatasetExamples = async (id, filePath, options, signal, onProgress) => {
+ core.eval.calls.push({
+ method: "updateDatasetExamples",
+ args: [id, filePath, options, signal, onProgress],
+ });
+ return new Promise<never>((_, reject) => {
+ const abort = () => reject(signal?.reason);
+ if (signal?.aborted) abort();
+ else signal?.addEventListener("abort", abort, { once: true });
+ });
+ };
+ const pending = route([
+ "eval",
+ "dataset",
+ "update",
+ "--id",
+ "dataset-orders-abc123",
+ "--file-path",
+ path,
+ ]);
+
+ try {
+ await waitFor(() => core.eval.calls.some((call) => call.method === "updateDatasetExamples"));
+ process.emit("SIGINT", "SIGINT");
+
+ const signal = core.eval.calls[0]!.args[3] as AbortSignal;
+ expect(signal.reason).toBeInstanceOf(UserCancellationError);
+ await expect(pending).rejects.toBe(signal.reason);
+ } finally {
+ await pending.catch(() => undefined);
+ }
+ });
+
  test("takes only --id and --file-path", async () => {
  const root = createRootHandler(new TestCoreClient(), {
  io: testIO().io,

src/handlers/eval/dataset/get/index.tsx

@@ -2,6 +2,7 @@ import z from "zod";
 import { createHandler, flag } from "../../../../router";
 import { InputValidationError } from "../../../../errors";
 import { JsonRendererKey } from "../../../../tui";
+import { withUserCancellation } from "../../../../runnable";
 import type { Core } from "../../../types";
 import { coreOptsFromCtx } from "../../../utils";
 
@@ -24,33 +25,29 @@ export const createGetDatasetHandler = (core: Core) =>
  ],
  handle: async (ctx, flags) => {
  if (!flags["id"]) throw new InputValidationError("required option '--id <id>' not specified");
+ const datasetId = flags["id"];
 
  const filePath = flags["file-path"];
  if (!filePath) {
  ctx
  .require(JsonRendererKey)
  .renderJson(
- await core.eval.getDataset(flags["id"], flags["version"], coreOptsFromCtx(ctx)),
+ await core.eval.getDataset(datasetId, flags["version"], coreOptsFromCtx(ctx)),
  );
  return;
  }
 
  // --file-path downloads the contents via the presigned download URL in metadata
- const controller = new AbortController();
- const interrupt = () => controller.abort();
- process.once("SIGINT", interrupt);
- try {
- const response = await core.eval.downloadDataset(
- flags["id"],
+ const response = await withUserCancellation((signal) =>
+ core.eval.downloadDataset(
+ datasetId,
  flags["version"],
  filePath,
  coreOptsFromCtx(ctx),
- controller.signal,
- );
- // file is written in addition to the normal metadata output
- ctx.require(JsonRendererKey).renderJson({ ...response, filePath });
- } finally {
- process.removeListener("SIGINT", interrupt);
- }
+ signal,
+ ),
+ );
+ // file is written in addition to the normal metadata output
+ ctx.require(JsonRendererKey).renderJson({ ...response, filePath });
  },
  });

src/handlers/eval/dataset/update/index.tsx

@@ -3,6 +3,7 @@ import { createHandler, flag } from "../../../../router";
 import { InputValidationError } from "../../../../errors";
 import type { AppIO } from "../../../../io";
 import { JsonRendererKey } from "../../../../tui";
+import { withUserCancellation } from "../../../../runnable";
 import type { Core } from "../../../types";
 import { coreOptsFromCtx } from "../../../utils";
 
@@ -16,27 +17,24 @@ export const createUpdateDatasetHandler = (core: Core, io: AppIO) =>
  ],
  handle: async (ctx, flags) => {
  if (!flags["id"]) throw new InputValidationError("required option '--id <id>' not specified");
+ const datasetId = flags["id"];
  if (!flags["file-path"]) {
  throw new InputValidationError("required option '--file-path <file-path>' not specified");
  }
+ const filePath = flags["file-path"];
 
- const controller = new AbortController();
- const interrupt = () => controller.abort();
- process.once("SIGINT", interrupt);
- try {
- ctx
- .require(JsonRendererKey)
- .renderJson(
- await core.eval.updateDatasetExamples(
- flags["id"],
- flags["file-path"],
+ ctx
+ .require(JsonRendererKey)
+ .renderJson(
+ await withUserCancellation((signal) =>
+ core.eval.updateDatasetExamples(
+ datasetId,
+ filePath,
  coreOptsFromCtx(ctx),
-controller.signal,
+ signal,
  (event) => io.stderr.write(`${event.message}\n`),
  ),
- );
- } finally {
- process.removeListener("SIGINT", interrupt);
- }
+ ),
+ );
  },
  });