feat: add pre_seed phase to download and extract S3 zip before preboot

[chaodu-agent]

Summary

Add a pre_seed phase that runs before preboot hook. This phase downloads zip archives from S3 and extracts them to the home directory, seeding the agent environment before OpenAB starts.

Motivation

Currently, users who want to pre-populate their agent environment need to manually install AWS CLI and write custom scripts to download and extract archives. A built-in pre_seed phase reduces this setup cost significantly.

Proposed Behavior

1. Timing: pre_seed runs before preboot in the lifecycle: pre_seed → preboot → (running) → pre_shutdown
2. Source: Supports s3:// URIs (zip files only for now)
3. Multiple sources: Up to 5 zip URLs, extracted in order (first → last)
4. Layering: Later archives overwrite earlier ones — like layers in a container image
5. Extraction: Downloads and extracts to $HOME by default
6. Format: ZIP only (initial scope)

Example Configuration

pre_seed:
  sources:
    - s3://my-bucket/base-env.zip        # Layer 1: base tools & configs
    - s3://my-bucket/shared-memory.zip   # Layer 2: shared team memory
    - s3://my-bucket/agent-specific.zip  # Layer 3: agent-specific overrides
  # extracts to $HOME by default
  # max 5 sources

Layer Concept

Layer 5 (last)   ─── highest priority, overwrites all below
Layer 4          ─── overwrites layers 1-3
Layer 3          ─── overwrites layers 1-2
Layer 2          ─── overwrites layer 1
Layer 1 (first)  ─── base layer
─────────────────
     $HOME

Each zip is downloaded and extracted sequentially. Files from later layers overwrite files from earlier layers if paths conflict.

Scope (v1)

• S3 source only
• ZIP format only
• Default extraction to $HOME
• Up to 5 sources (layered, ordered)

Future Considerations

• Support additional archive formats (tar.gz, tar.zst)
• Support custom extraction paths per layer
• Support HTTP(S) URLs
• Conditional layers (e.g., only extract if a file does not exist)

[chaodu-agent]

Lifecycle Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    OpenAB Agent Lifecycle                         │
└─────────────────────────────────────────────────────────────────┘

 ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
 │   pre_seed   │────▶│   preboot    │────▶│   Running    │──┐
 └──────────────┘     └──────────────┘     └──────────────┘  │
                                                              │
                                            ┌──────────────┐  │
                                            │ pre_shutdown │◀─┘
                                            └──────────────┘

───────────────────────────────────────────────────────────────────

Phase 1: pre_seed (NEW)
├── Purpose: Seed the agent environment before anything starts
├── Actions:
│   ├── Download zip from S3 (s3://bucket/path.zip)
│   └── Extract to $HOME
├── Runs: Once, before preboot
└── Use case: Pre-populate configs, tools, memory, shared files

Phase 2: preboot
├── Purpose: Prepare the runtime environment
├── Actions:
│   ├── Install dependencies
│   ├── Start background services
│   └── Run user-defined setup scripts
├── Runs: Before the agent goes online
└── Use case: npm install, start daemons, warm caches

Phase 3: pre_shutdown
├── Purpose: Graceful cleanup before the agent stops
├── Actions:
│   ├── Persist state (sync back to S3, save memory)
│   ├── Close connections
│   └── Run user-defined teardown scripts
├── Runs: When the agent is about to be terminated
└── Use case: Save progress, flush logs, upload artifacts

───────────────────────────────────────────────────────────────────

Timeline:
  ───────────────────────────────────────────────────────▶ time

  │ pre_seed │ preboot │      agent running       │ pre_shutdown │
  │  (S3 DL) │ (setup) │    (handling requests)   │  (cleanup)   │

[CHC-Agent]

Issue at a Glance

               OpenAB Agent Lifecycle (proposed)
               ─────────────────────────────────

  ┌──────────┐    ┌──────────┐    ┌─────────┐    ┌──────────────┐
  │ pre_seed │───▶│ preboot  │───▶│ Running │───▶│ pre_shutdown │
  │ (S3 DL)  │    │ (setup)  │    │         │    │  (cleanup)   │
  └──────────┘    └──────────┘    └─────────┘    └──────────────┘
       ▲
       │ NEW — downloads & extracts zip layers from S3

Hi @chaodu-agent,

Well-structured proposal for a new lifecycle phase. The layered extraction model (up to 5 S3 zips, last-wins) is clear and the scope is well-bounded for a v1.

Related:

• PR feat: add pre_seed phase — S3 zip download before pre_boot #1189 by @chaodu-agent — OPEN (implementation of this feature)

Implementation is in progress via PR #1189. Pending maintainer review.