| name | lambda-migration |
| description | Guides Phase 2 Lambda Container Migration steps. Pass a specific step number (2-1 through 2-5) to get the goals, deliverables, validation criteria, and detailed design for that step. |
| argument-hint | [step-number, e.g. 2-1] |
| allowed-tools | Read, Write, Edit, Bash, Glob, Grep |
Phase 2: Lambda Container Migration Guide
Step to implement: $ARGUMENTS
Implementation Procedure
- Read the detailed plan for the step in the references below
- Verify that dependent steps are completed
- Create/modify files specified in the deliverables
- Write tests first (TDD) before implementing
- Verify results according to validation criteria
- Update step status in
docs/progress.md
References
Step Overview
| Step | Title | Dependencies | Key Deliverables |
|---|
| 2-1 | Lambda Container Image + Handler | None | Dockerfile, handler.ts, session-sync.ts |
| 2-2 | CDK LambdaAgentStack | 2-1 | lambda-agent-stack.ts, ECR, IAM |
| 2-3 | Response Streaming Integration | 2-1, 2-2 | routeMessage update, WS push, Telegram |
| 2-4 | Session Lifecycle Management | 2-1, 2-3 | S3 lifecycle, locking, compaction |
| 2-5 | Fargate Deprecation + Cost Verification | 2-1~2-4 | Feature flag, docs, cost dashboard |
Critical Constraints (Must Check Every Step)
- Zero OpenClaw code modifications — Wrapper layer only, upstream compatible
- Zero fixed costs — No resources that incur charges while idle
- No NAT Gateway — Lambda outside VPC (accesses S3 via public endpoint)
- No secrets on disk — API keys via env vars (SSM SecureString resolved at runtime)
- Backward compatible — Fargate path must remain functional as fallback
- Cost target — Total monthly cost < $1 at low usage (< 100 requests)
Key Technical Details
OpenClaw Library Import
import { runEmbeddedPiAgent } from "openclaw/dist/extensionAPI.js";
Session File Path Convention
S3: s3://{bucket}/sessions/{userId}/{sessionId}.jsonl
Lambda /tmp: /tmp/.openclaw/agents/default/sessions/{sessionId}.jsonl
SessionManager Behavior
SessionManager.open(path) → calls loadEntriesFromFile(path)
- File not found → returns empty array (no error)
- Uses sync fs:
readFileSync, appendFileSync, writeFileSync
- All operations work on Lambda
/tmp
Config Initialization
process.env.HOME = '/tmp';
{ "gateway": { "mode": "local" } }
Post-Validation Tasks
After implementation of each step:
- Update step status in
docs/progress.md
- Check if
docs/architecture.md needs updating
- Run full test suite:
npm run test && npm run test:e2e