diff --git a/packages/aws-durable-execution-sdk-js-extras/src/compute/agentcore/__tests__/session.test.ts b/packages/aws-durable-execution-sdk-js-extras/src/compute/agentcore/__tests__/session.test.ts index 4994488f8..f8b680f32 100644 --- a/packages/aws-durable-execution-sdk-js-extras/src/compute/agentcore/__tests__/session.test.ts +++ b/packages/aws-durable-execution-sdk-js-extras/src/compute/agentcore/__tests__/session.test.ts @@ -3,11 +3,20 @@ import { type DurableContext, withDurableExecution, } from "@aws/durable-execution-sdk-js"; -import { LocalDurableTestRunner } from "@aws/durable-execution-sdk-js-testing"; +import { + LocalDurableTestRunner, + WaitingOperationStatus, +} from "@aws/durable-execution-sdk-js-testing"; import { AccessDeniedException } from "@aws-sdk/client-bedrock-agentcore"; -import { agentcoreSession } from "../session"; +import { agentcoreSession } from ".."; import type { AgentcoreSessionConfig } from "../types"; -import { FakeAgentcoreClient, metadata, RUNTIME_ARN, throwing } from "./fakes"; +import { + answer, + FakeAgentcoreClient, + metadata, + RUNTIME_ARN, + throwing, +} from "./fakes"; beforeAll(() => LocalDurableTestRunner.setupTestEnvironment({ skipTime: true }), @@ -83,6 +92,9 @@ describe("agentcoreSession", () => { expect(execution.getStatus()).toBe("FAILED"); expect(execution.getError()?.errorMessage).toContain("handler broke"); + // A handler error is not an AgentCore error. So it keeps the type that + // runInChildContext gives it without an error mapper. + expect(execution.getError()?.errorType).toBe("ChildContextError"); // Without a qualifier, the stop input has no qualifier key. expect(client.stopInputs).toStrictEqual([ { @@ -207,3 +219,272 @@ describe("agentcoreSession", () => { expect(execution.getOperations()).toHaveLength(0); }); }); + +/** Waits for the request step of `job`, then completes its callback. */ +async function completeJob( + runner: Runner, + job: string, + result: unknown, +): Promise { + await runner + .getOperation(`${job}.request`) + .waitForData(WaitingOperationStatus.COMPLETED); + await runner + .getOperation(`${job}.callback`) + .sendCallbackSuccess(JSON.stringify(result)); +} + +/** What a caller sees of an error. */ +function seen(error: unknown): { + className: string; + errorType: string; + message: string; +} { + const e = error as Error & { errorType: string }; + return { + className: e.constructor.name, + errorType: e.errorType, + message: e.message, + }; +} + +/** + * Runs `run`, which must fail, and returns what it saw on the first run and + * on replay. A step records the first view, and a wait makes the next + * invocation replay the failed operations from the checkpoint. + */ +async function bothViews( + run: (context: DurableContext) => Promise, + drive: (runner: Runner) => Promise = async () => {}, +): Promise> { + const runner = runnerFor(async (context) => { + const view = await run(context).then(() => { + throw new Error("the operation did not fail"); + }, seen); + const firstRun = await context.step("record", async () => view); + await context.wait("replay", { seconds: 1 }); + return { firstRun, replay: view }; + }); + const executionPromise = runner.run({ payload: {} }); + await drive(runner); + const execution = await executionPromise; + expect(execution.getStatus()).toBe("SUCCEEDED"); + const views = execution.getResult() as { + firstRun: ReturnType; + replay: ReturnType; + }; + expect(views.replay).toEqual(views.firstRun); + return views.firstRun; +} + +const job = { timeout: { minutes: 5 } }; + +describe("AgentcoreSession.invoke", () => { + it("runs two jobs in the same session, each with its own callback, and stops the session once", async () => { + const client = new FakeAgentcoreClient(); + const runner = runnerFor((context) => + agentcoreSession( + context, + "review", + sessionConfig(client), + async (session, child) => { + const first = await session.invoke(child, "first", { step: 1 }, job); + const second = await session.invoke(child, "second", first, job); + // The session, not a job, stops the session. + expect(client.stopInputs).toHaveLength(0); + return [first, second]; + }, + ), + ); + + const executionPromise = runner.run({ payload: {} }); + await completeJob(runner, "first", { step: 2 }); + await completeJob(runner, "second", { step: 3 }); + const execution = await executionPromise; + + expect(execution.getStatus()).toBe("SUCCEEDED"); + expect(execution.getResult()).toEqual([{ step: 2 }, { step: 3 }]); + const sessionId = runner + .getOperation("review.session") + .getStepDetails()?.result; + expect(client.invokeInputs.map((input) => input.runtimeSessionId)).toEqual([ + sessionId, + sessionId, + ]); + expect(client.document(0)).toMatchObject({ + input: { step: 1 }, + callbackId: runner.getOperation("first.callback").getCallbackDetails() + ?.callbackId, + }); + expect(client.document(1)).toMatchObject({ + input: { step: 2 }, + callbackId: runner.getOperation("second.callback").getCallbackDetails() + ?.callbackId, + }); + expect(client.document(1).callbackId).not.toBe( + client.document(0).callbackId, + ); + expect(client.stopInputs).toHaveLength(1); + // Each job is a child context named after the job. + expect( + runner + .getOperation("review") + .getChildOperations() + ?.map((operation) => operation.getName()), + ).toEqual(["review.session", "first", "second", "review.stop"]); + expect( + runner + .getOperation("first") + .getChildOperations() + ?.map((operation) => operation.getName()), + ).toEqual(["first.callback", "first.request"]); + }); + + it("creates the job in the context passed to invoke", async () => { + const client = new FakeAgentcoreClient(); + const runner = runnerFor((context) => + agentcoreSession( + context, + "review", + sessionConfig(client), + async (session, child) => + child.runInChildContext("inner", (inner) => + session.invoke(inner, "job", {}, job), + ), + ), + ); + + const executionPromise = runner.run({ payload: {} }); + await completeJob(runner, "job", "ok"); + const execution = await executionPromise; + + expect(execution.getStatus()).toBe("SUCCEEDED"); + expect(execution.getResult()).toBe("ok"); + expect( + runner + .getOperation("inner") + .getChildOperations() + ?.map((operation) => operation.getName()), + ).toEqual(["job"]); + }); + + it("rejects the job, and the handler can continue in the same session", async () => { + const client = new FakeAgentcoreClient(); + const runner = runnerFor((context) => + agentcoreSession( + context, + "review", + sessionConfig(client), + async (session, child) => { + const failure = await session + .invoke(child, "first", {}, job) + .then(() => undefined, seen); + const second = await session.invoke(child, "second", {}, job); + return { failure, second }; + }, + ), + ); + + const executionPromise = runner.run({ payload: {} }); + await runner + .getOperation("first.request") + .waitForData(WaitingOperationStatus.COMPLETED); + await runner.getOperation("first.callback").sendCallbackFailure({ + ErrorType: "ReviewFailed", + ErrorMessage: "3 comments", + }); + await completeJob(runner, "second", "ok"); + const execution = await executionPromise; + + expect(execution.getStatus()).toBe("SUCCEEDED"); + expect(execution.getResult()).toEqual({ + failure: { + className: "AgentcoreJobFailedError", + errorType: "AgentcoreJobFailedError", + message: expect.stringMatching( + /^AgentCore "first": the job failed \(ReviewFailed\): .*3 comments/, + ), + }, + second: "ok", + }); + expect(client.stopInputs).toHaveLength(1); + }); + + it.each([ + { + error: "AgentcoreJobFailedError", + options: job, + drive: async (runner: Runner) => { + await runner + .getOperation("first.request") + .waitForData(WaitingOperationStatus.COMPLETED); + await runner.getOperation("first.callback").sendCallbackFailure({ + ErrorType: "ReviewFailed", + ErrorMessage: "3 comments", + }); + }, + }, + { error: "AgentcoreTimeoutError", options: { timeout: { seconds: 2 } } }, + { + error: "AgentcoreDeliveryError", + options: job, + refuse: true, + }, + ])( + "reports a job failure that leaves the session as $error", + async ({ error, options, drive, refuse }) => { + const client = new FakeAgentcoreClient(); + if (refuse) { + client.invokeResponses = [answer('{"accepted":false}')]; + } + const view = await bothViews( + (context) => + agentcoreSession( + context, + "review", + sessionConfig(client), + async (session, child) => + session.invoke(child, "first", {}, options), + ), + drive, + ); + + expect(view.className).toBe(error); + expect(view.errorType).toBe(error); + expect(view.message).toMatch(/^AgentCore "first": /); + expect(client.stopInputs).toHaveLength(1); + }, + ); + + it("rejects an input that JSON cannot encode before any durable operation of the job", async () => { + const client = new FakeAgentcoreClient(); + const runner = runnerFor((context) => + agentcoreSession( + context, + "review", + sessionConfig(client), + async (session, child) => { + let promise: Promise | undefined; + // The input error rejects the returned promise. It is not thrown. + expect(() => { + promise = session.invoke(child, "first", 1n, job); + }).not.toThrow(); + return (promise as Promise).then(() => undefined, seen); + }, + ), + ); + + const execution = await runner.run({ payload: {} }); + + expect(execution.getResult()).toMatchObject({ + className: "TypeError", + message: expect.stringContaining( + 'AgentCore "first": the job input must be JSON-serializable', + ), + }); + expect( + execution.getOperations().map((operation) => operation.getName()), + ).toEqual(["review", "review.session", "review.stop"]); + expect(client.invokeInputs).toHaveLength(0); + }); +}); diff --git a/packages/aws-durable-execution-sdk-js-extras/src/compute/agentcore/agentcore.ts b/packages/aws-durable-execution-sdk-js-extras/src/compute/agentcore/agentcore.ts index f6d6f3892..15c9a1493 100644 --- a/packages/aws-durable-execution-sdk-js-extras/src/compute/agentcore/agentcore.ts +++ b/packages/aws-durable-execution-sdk-js-extras/src/compute/agentcore/agentcore.ts @@ -191,7 +191,7 @@ const INPUT_MEMBER_PREFIX = '{"input":'; * @returns The input's JSON text, or `undefined` when the input encodes to * no value, such as `undefined`. The document then has no `input` field. */ -function encodeInput(name: string, input: unknown): string | undefined { +export function encodeInput(name: string, input: unknown): string | undefined { let json: string; try { json = JSON.stringify({ input }); @@ -222,7 +222,7 @@ function encodeInput(name: string, input: unknown): string | undefined { * test without it. The worker rejects a job document without a Region. So * the operation fails before any durable operation instead. */ -function functionRegion(name: string): string { +export function functionRegion(name: string): string { const region = process.env.AWS_REGION; if (!region) { throw new TypeError( diff --git a/packages/aws-durable-execution-sdk-js-extras/src/compute/agentcore/errors.ts b/packages/aws-durable-execution-sdk-js-extras/src/compute/agentcore/errors.ts index 286c778d9..958c09068 100644 --- a/packages/aws-durable-execution-sdk-js-extras/src/compute/agentcore/errors.ts +++ b/packages/aws-durable-execution-sdk-js-extras/src/compute/agentcore/errors.ts @@ -3,6 +3,7 @@ import { DurableOperationError, } from "@aws/durable-execution-sdk-js"; import { ComputeError } from "../errors"; +import { callerErrorMapper } from "../microvm/errors"; /** * The base class of every error that {@link agentcore} reports for a failed @@ -158,14 +159,33 @@ export async function inStage( export function agentcoreErrorMapper( name: string, ): (error: DurableOperationError) => DurableOperationError { - return (error) => { - const Class = CLASSES[error.cause?.name ?? ""]; - return Class - ? new Class(error.message, error.cause, error.errorData) - : new AgentcoreError( - `AgentCore "${name}": ${error.message}`, - error.cause, - error.errorData, - ); - }; + return (error) => + rebuildAgentcoreError(error) ?? + new AgentcoreError( + `AgentCore "${name}": ${error.message}`, + error.cause, + error.errorData, + ); +} + +/** + * The error mapper of `agentcoreSession`. The session handler is caller + * code. So an AgentCore error, such as a failed job that the handler does + * not catch, is restored to its class, and any other error follows + * {@link callerErrorMapper}, as in `microvmSession`. + */ +export function agentcoreSessionErrorMapper( + error: DurableOperationError, +): DurableOperationError { + return rebuildAgentcoreError(error) ?? callerErrorMapper(error); +} + +/** Restores an AgentCore error from its checkpointed type, `cause.name`. */ +function rebuildAgentcoreError( + error: DurableOperationError, +): AgentcoreError | undefined { + const Class = CLASSES[error.cause?.name ?? ""]; + return Class + ? new Class(error.message, error.cause, error.errorData) + : undefined; } diff --git a/packages/aws-durable-execution-sdk-js-extras/src/compute/agentcore/index.ts b/packages/aws-durable-execution-sdk-js-extras/src/compute/agentcore/index.ts index c7e8c781c..cb3404df4 100644 --- a/packages/aws-durable-execution-sdk-js-extras/src/compute/agentcore/index.ts +++ b/packages/aws-durable-execution-sdk-js-extras/src/compute/agentcore/index.ts @@ -6,6 +6,7 @@ export { AgentcoreJobFailedError, AgentcoreTimeoutError, } from "./errors"; +export { agentcoreSession } from "./session"; export { AgentcoreOperationSubType } from "./subtypes"; export type { AgentcoreConfig, diff --git a/packages/aws-durable-execution-sdk-js-extras/src/compute/agentcore/session.ts b/packages/aws-durable-execution-sdk-js-extras/src/compute/agentcore/session.ts index e0ab51706..65d20edaf 100644 --- a/packages/aws-durable-execution-sdk-js-extras/src/compute/agentcore/session.ts +++ b/packages/aws-durable-execution-sdk-js-extras/src/compute/agentcore/session.ts @@ -2,16 +2,27 @@ import { type DurableContext, DurablePromise, } from "@aws/durable-execution-sdk-js"; +import type { BedrockAgentCoreClient } from "@aws-sdk/client-bedrock-agentcore"; import { defaultMicrovmRetryStrategy } from "../microvm/retry"; -import { getClient, validateConfig } from "./agentcore"; -import { createSessionId, type SessionTarget, stopSession } from "./steps"; -import type { AgentcoreSession, AgentcoreSessionConfig } from "./types"; - -/** - * The part of {@link AgentcoreSession} that the handler receives until - * `invoke` exists. - */ -export type AgentcoreSessionHandle = Pick; +import { + encodeInput, + functionRegion, + getClient, + validateConfig, +} from "./agentcore"; +import { agentcoreErrorMapper, agentcoreSessionErrorMapper } from "./errors"; +import { + createSessionId, + runJob, + type SessionTarget, + stopSession, +} from "./steps"; +import type { + AgentcoreConfig, + AgentcoreInvokeOptions, + AgentcoreSession, + AgentcoreSessionConfig, +} from "./types"; /** * Runs a handler in one Amazon Bedrock AgentCore Runtime session, and @@ -22,30 +33,41 @@ export type AgentcoreSessionHandle = Pick; * named `name`: * * 1. `.session` generates the runtime session ID and checkpoints it. - * 2. The handler runs with the session handle and the child context. + * 2. The handler runs with the {@link AgentcoreSession} and the child + * context. Each `session.invoke` sends one job to the session and waits + * for its result. * 3. `.stop` calls StopRuntimeSession after the handler returns or * throws. * * A stop failure does not fail the operation. The operation logs an error * and returns the handler's value or error. * + * A failed `session.invoke` rejects inside the handler. The handler can + * catch the error and continue with the same session. An error that leaves + * the handler ends the session and reaches the caller. An AgentCore error + * keeps its class. Any other error keeps its SDK error type, or is wrapped + * in `ChildContextError`. + * * @param context - The context to create the durable operations in. * @param name - The child context name. It also prefixes the inner * operation names. * @param config - The agent runtime configuration. - * @param handler - Receives the session handle and the session's child - * context. + * @param handler - Receives the session and the session's child context. * @returns The handler's return value. * @throws \{TypeError\} When `name` is empty, or `agentRuntimeArn` is not a * string. * @throws \{RangeError\} When `timeout` is shorter than 1 second. + * + * @public + * + * @experimental This function is experimental and may be changed or removed in future releases. */ export function agentcoreSession( context: DurableContext, name: string, config: AgentcoreSessionConfig, handler: ( - session: AgentcoreSessionHandle, + session: AgentcoreSession, context: DurableContext, ) => Promise, ): DurablePromise { @@ -55,24 +77,85 @@ export function agentcoreSession( return new DurablePromise(() => Promise.reject(error)); } const retryStrategy = config.retryStrategy ?? defaultMicrovmRetryStrategy; + const client = (): BedrockAgentCoreClient => getClient(config); + + return context.runInChildContext( + name, + async (child) => { + const runtimeSessionId = await createSessionId(child, name); + const target: SessionTarget = { + agentRuntimeArn: config.agentRuntimeArn, + runtimeSessionId, + ...(config.qualifier !== undefined && { qualifier: config.qualifier }), + }; + const session: AgentcoreSession = { + runtimeSessionId, + invoke: ( + jobContext: DurableContext, + jobName: string, + input: TInput, + options: AgentcoreInvokeOptions, + ): DurablePromise => + invokeJob( + jobContext, + jobName, + input, + options, + retryStrategy, + client, + target, + ), + }; + try { + return await handler(session, child); + } finally { + await stopSession(child, name, retryStrategy, client, target); + } + }, + { errorMapper: agentcoreSessionErrorMapper }, + ); +} + +/** + * Sends one job to the session and waits for its result. + * + * The job has the same shape as `agentcore`, without its own session ID and + * stop: a child context named `jobName` in `context`, a callback + * `.callback`, and a request step `.request`. The session + * stops the session, so the job's `stop` does nothing. + */ +function invokeJob( + context: DurableContext, + jobName: string, + input: unknown, + options: AgentcoreInvokeOptions, + retryStrategy: NonNullable, + client: () => BedrockAgentCoreClient, + target: SessionTarget, +): DurablePromise { + let region: string; + let inputJson: string | undefined; + try { + region = functionRegion(jobName); + inputJson = encodeInput(jobName, input); + } catch (error) { + return new DurablePromise(() => Promise.reject(error)); + } - return context.runInChildContext(name, async (child) => { - const runtimeSessionId = await createSessionId(child, name); - const target: SessionTarget = { - agentRuntimeArn: config.agentRuntimeArn, - runtimeSessionId, - ...(config.qualifier !== undefined && { qualifier: config.qualifier }), - }; - try { - return await handler({ runtimeSessionId }, child); - } finally { - await stopSession( - child, - name, + return context.runInChildContext( + jobName, + (jobContext) => + runJob( + jobContext, + jobName, + options, retryStrategy, - () => getClient(config), + client, target, - ); - } - }); + region, + inputJson, + async () => {}, + ), + { errorMapper: agentcoreErrorMapper(jobName) }, + ); } diff --git a/packages/aws-durable-execution-sdk-js-extras/src/compute/microvm/errors.ts b/packages/aws-durable-execution-sdk-js-extras/src/compute/microvm/errors.ts index e19ad5eb4..9784019b6 100644 --- a/packages/aws-durable-execution-sdk-js-extras/src/compute/microvm/errors.ts +++ b/packages/aws-durable-execution-sdk-js-extras/src/compute/microvm/errors.ts @@ -344,24 +344,35 @@ export const SDK_ERROR_TYPES: ReadonlySet = new Set([ * The rule: * * 1. A MicroVM error is restored to its class. - * 2. An SDK error type that `fromErrorObject` knows passes through. The SDK + * 2. Any other error follows {@link callerErrorMapper}. + */ +export function sessionErrorMapper( + error: DurableOperationError, +): DurableOperationError { + return rebuildMicrovmError(error) ?? callerErrorMapper(error); +} + +/** + * Maps the failure of a child context that runs caller code, after the + * compute errors are restored. A session of each compute type uses it. + * + * The rule: + * + * 1. An SDK error type that `fromErrorObject` knows passes through. The SDK * rebuilds such an error with `cause.name` set to its type. - * 3. Any other error is wrapped in `ChildContextError`, as `runInChildContext` + * 2. Any other error is wrapped in `ChildContextError`, as `runInChildContext` * does without an error mapper. * * The SDK rebuilds an error type that it does not know, such as a plain * `Error` thrown by the handler, as `StepError`, and keeps the original type * as `cause.name`. So `errorType` alone cannot tell a failed step from a - * failed handler. So rule 2 also requires `cause.name` to match the type. + * failed handler. So rule 1 also requires `cause.name` to match the type. */ -export function sessionErrorMapper( +export function callerErrorMapper( error: DurableOperationError, ): DurableOperationError { - return ( - rebuildMicrovmError(error) ?? - (SDK_ERROR_TYPES.has(error.errorType) && + return SDK_ERROR_TYPES.has(error.errorType) && error.cause?.name === error.errorType - ? error - : new ChildContextError(error.message, error)) - ); + ? error + : new ChildContextError(error.message, error); }