AWS Step Functions skill for Codex

Done well means: every Task has a Retry for transient errors and a Catch that leads to a defined outcome, every wait has a timeout, the workflow type matches its duration and delivery guarantee, payloads stay small, and each state’s behaviour was exercised with TestState before the whole machine was deployed.

Before changing anything

1. Read AGENTS.md and find the definition: an .asl.json file, a CDK DefinitionBody, a SAM DefinitionUri, or Terraform. Edit it there.
2. Note the type (STANDARD or EXPRESS), the query language ("QueryLanguage": "JSONata" at the top or per state; JSONPath otherwise), and the role’s permissions.
3. For a failing workflow, read the failing execution (needs network and credentials):

aws stepfunctions list-executions --state-machine-arn $SM --status-filter FAILED --max-items 5
aws stepfunctions get-execution-history --execution-arn $EXEC --reverse-order --max-items 20 \
  --query 'events[].{t:type,id:id,err:[taskFailedEventDetails.error,executionFailedEventDetails.error],cause:taskFailedEventDetails.cause}'

Standard vs Express

Factor	Standard	Express
Max duration	1 year	5 minutes
Semantics	Exactly-once state transitions	At-least-once (async) or at-most-once (sync)
.sync and waitForTaskToken	Yes	No
Pricing	Per state transition	Per request plus duration and memory
History	Visible in console/API for 90 days	CloudWatch Logs only (enable logging)
Redrive failed executions	Yes	No
Typical use	Business processes, human approval, long jobs	High-volume event processing, API-backing workflows, Distributed Map children

Rule of thumb: anything that waits on people or long jobs, or must not run twice, is Standard. High-volume, short and idempotent is Express. A Standard parent can call Express children to combine both.

Error handling pattern

{
  "QueryLanguage": "JSONata",
  "StartAt": "ChargeCard",
  "States": {
    "ChargeCard": {
      "Type": "Task",
      "Resource": "arn:aws:states:::lambda:invoke",
      "Arguments": {
        "FunctionName": "arn:aws:lambda:eu-west-1:111111111111:function:charge-card:live",
        "Payload": "{% $states.input %}"
      },
      "Output": "{% $states.result.Payload %}",
      "TimeoutSeconds": 30,
      "Retry": [
        {
          "ErrorEquals": ["Lambda.ServiceException", "Lambda.AWSLambdaException",
                          "Lambda.SdkClientException", "Lambda.TooManyRequestsException"],
          "IntervalSeconds": 1, "MaxAttempts": 3, "BackoffRate": 2, "JitterStrategy": "FULL"
        },
        {
          "ErrorEquals": ["PaymentProviderUnavailable"],
          "IntervalSeconds": 5, "MaxAttempts": 4, "BackoffRate": 2, "MaxDelaySeconds": 60
        }
      ],
      "Catch": [
        {
          "ErrorEquals": ["CardDeclined"],
          "Output": "{% $merge([$states.input, {'error': $states.errorOutput}]) %}",
          "Next": "NotifyDeclined"
        },
        {
          "ErrorEquals": ["States.ALL"],
          "Output": "{% $merge([$states.input, {'error': $states.errorOutput}]) %}",
          "Next": "ReleaseInventory"
        }
      ],
      "Next": "ShipOrder"
    }
  }
}

Rules:

• Retry only errors that can succeed on retry: throttling, service errors, timeouts, your own transient error names. Never retry States.ALL blindly; a validation error retried 3 times is just slower failure.
• Throw named errors from your code (a Lambda raising class CardDeclined(Exception) surfaces as error CardDeclined) so Retry and Catch can match them precisely.
• Order matters: the first matching Retry and the first matching Catch win. Put specific errors before States.ALL, which must be last.
• Keep the original input when catching. In JSONPath use "ResultPath": "$.error"; in JSONata merge $states.errorOutput into the input as above. Without this the catch handler receives only the error and loses the order data.
• Every Task gets TimeoutSeconds. The default is effectively unlimited, so a hung integration holds a Standard execution open for up to a year.
• Callback tasks (.waitForTaskToken) also get HeartbeatSeconds, and the worker sends SendTaskHeartbeat while it runs.

Compensation (saga)

For multi-step business transactions, each step that has a side effect gets a matching undo state, and Catch routes to the undo chain for the steps already completed:

ReserveInventory -> ChargeCard -> ShipOrder -> Succeed
       |                |             |
       v                v             v
     Fail     <-  ReleaseInventory <- RefundCard

Compensating actions must be idempotent and retried aggressively; a failed compensation should alert a human (SNS, ticket) rather than fail silently.

Integration patterns

Pattern	Resource suffix	Use when
Request-response	arn:aws:states:::sns:publish	Fire and continue
Run a job and wait	arn:aws:states:::ecs:runTask.sync, glue:startJobRun.sync, states:startExecution.sync:2	Step Functions polls the job for you
Callback	arn:aws:states:::sqs:sendMessage.waitForTaskToken	Human approval, external systems; pass $states.context.Task.Token
Any AWS API	arn:aws:states:::aws-sdk:dynamodb:putItem	No optimized integration exists; error names become DynamoDb.ConditionalCheckFailedException style

Call AWS services directly from the state machine instead of wrapping each API call in a Lambda; fewer functions, fewer cold starts, fewer failure points.

Map and Distributed Map

Items	Use
Up to a few hundred, small, in the state input	Inline Map with MaxConcurrency
Thousands to millions, from S3 (CSV, JSON, JSON Lines, object listing)	Distributed Map with ItemReader, Express child executions, ResultWriter to S3

Set MaxConcurrency to what downstream systems can take, and ToleratedFailurePercentage so one bad record does not fail a million-item run. Batch items (ItemBatcher) when per-item work is tiny.

Limits that shape designs

• State input/output payload: 256 KiB at time of writing. Pass S3 keys or IDs, not documents.
• Standard execution history: 25,000 events. Long loops must hand off to a child execution (or use Distributed Map) before hitting it.
• Variables (Assign, JSONata or JSONPath) reduce the need to carry everything through every state’s output; prefer them to ever-growing payloads.

Data flow details for both query languages (Arguments/Output/Assign vs InputPath/Parameters/ResultSelector/ResultPath/OutputPath, context object fields and intrinsic functions) are in references/data-flow.md. Read it when writing or converting state input/output mappings.

Testing

1. Unit-test the code behind each Lambda task normally.
2. Test single states against the real service with the TestState API (needs network and credentials; it runs the state for real, so use non-production resources):

aws stepfunctions test-state \
  --definition file://states/charge-card.json \
  --role-arn arn:aws:iam::111111111111:role/sfn-test \
  --input '{"orderId":"o-1","amount":42}' \
  --inspection-level DEBUG

DEBUG shows the input and output after every data-flow step, which is how you debug mappings. Test Catch paths by feeding an input that makes the task fail. 3. Validate the full definition before deploying:

aws stepfunctions validate-state-machine-definition --definition file://order.asl.json \
  --query 'diagnostics'

4. Run an execution in a dev stack and check every branch you changed.

Operations

• Redrive a failed Standard execution from the failed state after fixing the cause: aws stepfunctions redrive-execution --execution-arn $EXEC. This re-runs side effects from that state onward; confirm with the user first for production.
• Publish versions and route an alias for safe rollouts of definition changes.
• Enable CloudWatch logging (ALL with execution data for Express in dev, ERROR in production if payloads contain personal data) and X-Ray tracing.
• Alarm on ExecutionsFailed, ExecutionsTimedOut and ExecutionThrottled.

Gotchas

• The optimized lambda:invoke integration wraps the function result in { "Payload": ..., "StatusCode": ... }. Select Payload or downstream states read the wrapper.
• Choice states without a Default fail with States.NoChoiceMatched on unexpected input.
• Mixing JSONPath and JSONata fields in one state is invalid; convert a state completely.
• The state machine role needs permission for every integration, including states:StartExecution plus EventBridge managed-rule permissions for .sync child executions.
• Changing a definition does not affect running Standard executions; they finish on the version they started with.