Lab 11 — Sessions & Checkpoints

Aprende a usar sesiones para guardar el estado de ejecución de Architect, reanudar tareas interrumpidas por budget o fallos, y hacer rollback a checkpoints seguros.

Setup

Nivel: Intermedio

Duración estimada: 25 minutos. Features: sessions, checkpoints, resume.

mkdir -p ~/architect-labs/lab-11 && cd ~/architect-labs/lab-11
git init && mkdir -p src tests

src/inventory.py

class Inventory:
    def __init__(self):
        self.products = {}

    def add_product(self, sku, name, price, stock):
        self.products[sku] = {"name": name, "price": price, "stock": stock}

.architect.yaml

llm:
  model: openai/gpt-4.1
  api_base: http://localhost:4000/v1
  api_key_env: LITELLM_API_KEY

sessions:
  auto_save: true
  cleanup_after_days: 7

git add -A && git commit -m "initial"

Ejercicio 1: Sesión con auto-save

architect run "Expande src/inventory.py con métodos: remove_product, \
  update_stock, get_product, search_by_name, get_low_stock(threshold). \
  Añade tests completos." \
  --config .architect.yaml \
  --confirm-mode yolo

Después de ejecutar, lista las sesiones guardadas:

architect sessions
# Muestra ID, timestamp, status, task

Consejo

Con auto_save: true, cada ejecución guarda su estado automáticamente. Esto permite reanudar ejecuciones interrumpidas sin perder progreso.

Ejercicio 2: Checkpoints en pipeline

Crea un pipeline con checkpoints:

pipelines/inventory-expand.yaml

name: inventory-expansion
steps:
  - name: add-search
    agent: build
    task: >
      Añade a src/inventory.py:
      - search_products(query) que busque por nombre
      - filter_by_price(min_price, max_price)
      Añade tests para estas funciones.
    checkpoint: true

  - name: add-reporting
    agent: build
    task: >
      Añade a src/inventory.py:
      - get_total_value() que calcule el valor total del inventario
      - get_report() que genere un resumen con totales
      Añade tests para estas funciones.
    checkpoint: true

  - name: add-export
    agent: build
    task: >
      Añade a src/inventory.py:
      - export_csv(filepath) que exporte el inventario a CSV
      - import_csv(filepath) que importe desde CSV
      Añade tests para estas funciones.
    checkpoint: true

architect pipeline pipelines/inventory-expand.yaml \
  --config .architect.yaml \
  --confirm-mode yolo

Verifica los checkpoints:

# Los checkpoints son git commits con tag especial
git log --oneline | head -10
# Deberías ver commits tipo: architect:checkpoint:step-1

Ejercicio 3: Rollback a checkpoint

Si el step 3 (export) introdujo un bug:

# Listar checkpoints
git log --oneline --grep="architect:checkpoint"

# Rollback al checkpoint del step 2
git log --oneline --grep="architect:checkpoint:step-2"
# Copia el hash del commit
git reset --hard <HASH_DEL_CHECKPOINT_STEP_2>

# Verificar que estamos en el estado post-step-2
pytest tests/ -v

Importante

git reset --hard descarta todos los cambios posteriores al checkpoint. Úsalo solo cuando estés seguro de que quieres descartar el trabajo posterior.

Ejercicio 4: Resume de sesión interrumpida

Simula una interrupción con budget bajo:

architect run "Genera 5 módulos auxiliares para inventory: \
  validators.py, formatters.py, exporters.py, importers.py, analytics.py. \
  Cada uno con al menos 3 funciones y tests." \
  --config .architect.yaml \
  --confirm-mode yolo \
  --budget 0.05
# Se detendrá por budget

# Ver la sesión guardada
architect sessions
# Copiar el SESSION_ID

# Reanudar la sesión
architect resume <SESSION_ID> \
  --budget 0.20

Consejo

Al reanudar, Architect retoma desde donde se quedó con todo el contexto previo. Puedes aumentar el budget para que tenga suficiente margen para completar.

Ejercicio 5: Limpiar sesiones antiguas

# Ver todas las sesiones
architect sessions

# Limpiar sesiones de más de 1 día
architect cleanup --older-than 1

Resumen

Concepto	Descripción
`sessions.auto_save`	Guarda estado automáticamente
`architect sessions`	Lista sesiones guardadas
`architect resume ID`	Reanuda una sesión interrumpida
`checkpoint: true`	Crea git commit checkpoint en ese step
`architect cleanup`	Limpia sesiones antiguas
Rollback	`git reset --hard` al commit del checkpoint

Siguiente lab

Lab 12: Code Rules Deep Dive — Patrones bloqueados y warnings en el código.