feat(sdk): add configureLogger method with modeAware option

Replace setCustomLogger() with configureLogger() that accepts LoggerConfig
object with customLogger and modeAware options. The modeAware flag controls
whether logs are suppressed during replay mode (default: false).

Changes:
- Add configureLogger(config: LoggerConfig) method to DurableContext
- Add LoggerConfig interface with customLogger and modeAware properties
- Update createModeAwareLogger to accept modeAwareEnabled parameter
- Change default modeAware behavior to false (show logs during replay)
- Update all tests to reflect new default behavior
- Add logger-test example with file-based logging (local-only tests)
- Update documentation: README, API_SPECIFICATION.md with new API
- Add TSDoc comments for Logger types and configureLogger method

Author: ParidelPooya

packages/aws-durable-execution-sdk-js-examples/src/examples/logger-example/logger-example.test.ts

@@ -0,0 +1,29 @@
+import { handler } from "./logger-after-callback";
+import { createTests } from "../../../utils/test-helper";
+import {
+  InvocationType,
+  WaitingOperationStatus,
+} from "@aws/durable-execution-sdk-js-testing";
+
+createTests({
+  name: "logger-after-callback",
+  functionName: "logger-after-callback",
+  handler,
+  invocationType: InvocationType.Event,
+  tests: (runner) => {
+    it("should log after createCallback in execution mode", async () => {
+      const executionPromise = runner.run();
+
+      const callbackOp = runner.getOperationByIndex(0);
+      await callbackOp.waitForData(WaitingOperationStatus.STARTED);
+      await callbackOp.sendCallbackSuccess("test-result");
+
+      const execution = await executionPromise;
+
+      const result = execution.getResult() as any;
+      expect(result.message).toBe("Success");
+      expect(result.callbackId).toBeDefined();
+      expect(result.result).toBe("test-result");
+    });
+  },
+});

packages/aws-durable-execution-sdk-js-examples/src/examples/logger-example/logger-example.ts

@@ -0,0 +1,21 @@
+import { withDurableExecution } from "@aws/durable-execution-sdk-js";
+import { ExampleConfig } from "../../../types";
+
+export const config: ExampleConfig = {
+  name: "Logger After Callback",
+  description: "Test logger mode switching after createCallback operation",
+};
+
+export const handler = withDurableExecution(async (_event, context) => {
+  context.configureLogger({ modeAware: true });
+
+  context.logger.info("Before createCallback");
+
+  const [callbackPromise, callbackId] = await context.createCallback<string>();
+
+  context.logger.info("After createCallback");
+
+  const result = await callbackPromise;
+
+  return { message: "Success", callbackId, result };
+});

packages/aws-durable-execution-sdk-js-examples/src/examples/logger-test/after-callback/logger-after-callback.test.ts

@@ -0,0 +1,19 @@
+import { handler } from "./logger-after-invoke";
+import { createTests } from "../../../utils/test-helper";
+
+createTests({
+  name: "logger-after-invoke",
+  functionName: "logger-after-invoke",
+  handler,
+  tests: (runner) => {
+    it("should execute successfully with modeAware logging", async () => {
+      const execution = await runner.run();
+
+      expect(execution.getResult()).toEqual({ message: "Success" });
+
+      // Verify step operation was recorded
+      const stepOp = runner.getOperationByIndex(0);
+      expect(stepOp.getType()).toBe("STEP");
+    });
+  },
+});

packages/aws-durable-execution-sdk-js-examples/src/examples/logger-test/after-callback/logger-after-callback.ts

@@ -0,0 +1,22 @@
+import { withDurableExecution } from "@aws/durable-execution-sdk-js";
+import { ExampleConfig } from "../../../types";
+
+export const config: ExampleConfig = {
+  name: "Logger After Invoke",
+  description:
+    "Test logger mode switching after backend-completed operation (using step as proxy)",
+};
+
+export const handler = withDurableExecution(async (_event, context) => {
+  context.configureLogger({ modeAware: true });
+
+  context.logger.info("Before step");
+
+  await context.step(async () => {
+    return { data: "step result" };
+  });
+
+  context.logger.info("After step");
+
+  return { message: "Success" };
+});

packages/aws-durable-execution-sdk-js-examples/src/examples/logger-test/after-invoke/logger-after-invoke.test.ts

@@ -0,0 +1,59 @@
+import { handler } from "./logger-after-wait";
+import { createTests } from "../../../utils/test-helper";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+
+createTests({
+  name: "logger-after-wait",
+  functionName: "logger-after-wait",
+  handler,
+  tests: (runner, isCloud) => {
+    if (!isCloud) {
+      it("should log after wait in execution mode with modeAware=true", async () => {
+        const logFilePath = path.join(
+          os.tmpdir(),
+          `logger-test-${Date.now()}.log`,
+        );
+
+        if (fs.existsSync(logFilePath)) {
+          fs.unlinkSync(logFilePath);
+        }
+
+        try {
+          const execution = await runner.run({
+            payload: { logFilePath, modeAware: true },
+          });
+
+          expect(execution.getResult()).toEqual({ message: "Success" });
+
+          const logContent = fs.readFileSync(logFilePath, "utf-8");
+          const logLines = logContent
+            .trim()
+            .split("\n")
+            .map((line) => JSON.parse(line));
+
+          const beforeWaitLogs = logLines.filter(
+            (log) => log.message === "Before wait",
+          );
+          const afterWaitLogs = logLines.filter(
+            (log) => log.message === "After wait",
+          );
+
+          // With modeAware: true, both logs appear once (execution mode only)
+          expect(beforeWaitLogs.length).toBe(1);
+          expect(afterWaitLogs.length).toBe(1);
+        } finally {
+          if (fs.existsSync(logFilePath)) {
+            fs.unlinkSync(logFilePath);
+          }
+        }
+      });
+    }
+
+    it("should execute successfully", async () => {
+      const execution = await runner.run();
+      expect(execution.getResult()).toEqual({ message: "Success" });
+    });
+  },
+});

packages/aws-durable-execution-sdk-js-examples/src/examples/logger-test/after-invoke/logger-after-invoke.ts

@@ -0,0 +1,65 @@
+import { withDurableExecution, Logger } from "@aws/durable-execution-sdk-js";
+import { ExampleConfig } from "../../../types";
+import * as fs from "fs";
+
+export const config: ExampleConfig = {
+  name: "Logger After Wait",
+  description: "Test logger mode switching after wait operation",
+};
+
+interface LoggerTestEvent {
+  logFilePath?: string;
+  modeAware?: boolean;
+}
+
+export const handler = withDurableExecution(
+  async (event: LoggerTestEvent, context) => {
+    if (event.logFilePath) {
+      const fileLogger: Logger = {
+        log: (level, message, data) => {
+          fs.appendFileSync(
+            event.logFilePath!,
+            JSON.stringify({ level, message, data }) + "\n",
+          );
+        },
+        info: (message, data) => {
+          fs.appendFileSync(
+            event.logFilePath!,
+            JSON.stringify({ level: "info", message, data }) + "\n",
+          );
+        },
+        error: (message, error, data) => {
+          fs.appendFileSync(
+            event.logFilePath!,
+            JSON.stringify({ level: "error", message, error, data }) + "\n",
+          );
+        },
+        warn: (message, data) => {
+          fs.appendFileSync(
+            event.logFilePath!,
+            JSON.stringify({ level: "warn", message, data }) + "\n",
+          );
+        },
+        debug: (message, data) => {
+          fs.appendFileSync(
+            event.logFilePath!,
+            JSON.stringify({ level: "debug", message, data }) + "\n",
+          );
+        },
+      };
+
+      context.configureLogger({
+        customLogger: fileLogger,
+        modeAware: event.modeAware ?? true,
+      });
+    } else {
+      context.configureLogger({ modeAware: event.modeAware ?? true });
+    }
+
+    context.logger.info("Before wait");
+    await context.wait({ seconds: 2 });
+    context.logger.info("After wait");
+
+    return { message: "Success" };
+  },
+);