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: true).

BREAKING CHANGE: Removed setCustomLogger() method in favor of configureLogger().
This is acceptable as the SDK has not been launched yet and there are no existing users.

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 true (suppress logs during replay)
- Fix replay mode switching for backend-completed operations (wait, invoke,
  createCallback, waitForCallback) by calling checkAndUpdateReplayMode() after completion
- Update all tests to reflect new default behavior and mode switching fix
- Add logger-test examples 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
- Remove old logger-example with outdated information

Author: ParidelPooya

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

@@ -0,0 +1,132 @@
+import { handler } from "./logger-after-callback";
+import { createTests } from "../../../utils/test-helper";
+import {
+  InvocationType,
+  WaitingOperationStatus,
+} from "@aws/durable-execution-sdk-js-testing";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import { randomUUID } from "crypto";
+
+createTests({
+  name: "logger-after-callback",
+  functionName: "logger-after-callback",
+  handler,
+  invocationType: InvocationType.Event,
+  tests: (runner, isCloud) => {
+    if (!isCloud) {
+      it("should log correctly with modeAware=true", async () => {
+        const logFilePath = path.join(
+          os.tmpdir(),
+          `logger-test-${randomUUID()}.log`,
+        );
+
+        if (fs.existsSync(logFilePath)) {
+          fs.unlinkSync(logFilePath);
+        }
+
+        try {
+          const executionPromise = runner.run({
+            payload: { logFilePath, modeAware: true },
+          });
+
+          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");
+
+          const logContent = fs.readFileSync(logFilePath, "utf-8");
+          const logLines = logContent
+            .trim()
+            .split("\n")
+            .map((line) => JSON.parse(line));
+
+          const beforeCallbackLogs = logLines.filter(
+            (log) => log.message === "Before createCallback",
+          );
+          const afterCallbackLogs = logLines.filter(
+            (log) => log.message === "After createCallback",
+          );
+
+          // With modeAware: true:
+          // - "Before createCallback" appears once (execution mode only, suppressed during replay)
+          // - "After createCallback" appears once (after callback resolves, in execution mode)
+          expect(beforeCallbackLogs.length).toBe(1);
+          expect(afterCallbackLogs.length).toBe(1);
+        } finally {
+          if (fs.existsSync(logFilePath)) {
+            fs.unlinkSync(logFilePath);
+          }
+        }
+      });
+
+      it("should log correctly with modeAware=false", async () => {
+        const logFilePath = path.join(
+          os.tmpdir(),
+          `logger-test-${randomUUID()}.log`,
+        );
+
+        if (fs.existsSync(logFilePath)) {
+          fs.unlinkSync(logFilePath);
+        }
+
+        try {
+          const executionPromise = runner.run({
+            payload: { logFilePath, modeAware: false },
+          });
+
+          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");
+
+          const logContent = fs.readFileSync(logFilePath, "utf-8");
+          const logLines = logContent
+            .trim()
+            .split("\n")
+            .map((line) => JSON.parse(line));
+
+          const beforeCallbackLogs = logLines.filter(
+            (log) => log.message === "Before createCallback",
+          );
+          const afterCallbackLogs = logLines.filter(
+            (log) => log.message === "After createCallback",
+          );
+
+          // With modeAware: false:
+          // - "Before createCallback" appears twice (execution + replay)
+          // - "After createCallback" appears once (after callback resolves)
+          expect(beforeCallbackLogs.length).toBe(2);
+          expect(afterCallbackLogs.length).toBe(1);
+        } finally {
+          if (fs.existsSync(logFilePath)) {
+            fs.unlinkSync(logFilePath);
+          }
+        }
+      });
+    }
+
+    it("should execute successfully", 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");
+    });
+  },
+});

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

@@ -0,0 +1,70 @@
+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 Callback",
+  description: "Test logger mode switching after createCallback 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 createCallback");
+
+    const [callbackPromise, callbackId] =
+      await context.createCallback<string>();
+
+    const result = await callbackPromise;
+
+    context.logger.info("After createCallback");
+
+    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,60 @@
+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";
+import { randomUUID } from "crypto";
+
+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-${randomUUID()}.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" });
+    });
+  },
+});