Saltar a contenido

Novedades de 0.9.0

Publicada el 2026-10-07: SDK Python rayito 0.9.0, SDK TypeScript rayito 0.9.0 y rayd 0.9.0.

0.9.0 es una release de limpieza y correcciones. Quita lo que no compensaba mantener (la opción D del arranque rápido del agente y unas excepciones de la pasarela que nada lanzaba), hace que otro proceso pueda usar el agente de un sandbox con Sandbox.connect() y alinea el SDK de Python con el de TypeScript en la región de AWS. No hay funciones nuevas con coste ni llamadas nuevas a AWS.

Hay cambios que rompen, todos con su migración en Cómo actualizar desde 0.8.x.

De un vistazo

Cambio Python TypeScript Tipo
Se retira la opción D (pool con opencode serve residente) serve=, attach=, RunRequest.attach serve, attach, RunRequest.attach rompe
Se eliminan las excepciones de la pasarela que nunca se lanzaban GatewayException GatewayError, GatewayErrorOptions rompe
BuildException y TemplateException del shim de E2B son las nativas rayito.e2b.BuildException, rayito.e2b.TemplateException — rompe
AWS_REGION gana a AWS_DEFAULT_REGION y al perfil todo el SDK ya lo hacía corrección que cambia comportamiento
connect() recupera sbx.gateways Sandbox.connect(), AsyncSandbox.connect() Sandbox.connect() corrección

Cambios que rompen

Se retira la opción D del arranque rápido del agente

El pool con opencode serve residente desaparece sin periodo de obsolescencia: apenas ganaba unas décimas a la opción C y costaba más memoria y más por plaza. Desaparecen:

  • Python: agent_pool_warmup(..., serve=), sbx.agent.prepare(serve=), attach= de sbx.agent.run()/stream() (sync y async) y RunRequest.attach.
  • TypeScript: la opción serve de agentPoolWarmup() y de sbx.agent.prepare(), attach de AgentRunOptions y RunRequest.attach.
  • El span rayito.agent.run deja de llevar rayito.agent.attached, y OPENCODE_SERVE_PORT desaparece.
  • Para quien escribe su propio runtime: el puerto AgentRuntime pierde abort_command / abortCommand (ningún runtime lo usaba ya) y warmup_steps() / warmupSteps() ya no lleva argumentos.

Migración: quita serve=True y attach=. Para un primer mensaje rápido usa agent_pool_warmup(runtime) / agentPoolWarmup(runtime) (opción C) o el arranque normal (Sandbox.create(...) y sbx.agent.run(...)); la tabla de ¿Qué uso? compara las opciones que quedan. Un runtime propio borra abort_command y el parámetro de warmup_steps.

Se eliminan GatewayException y GatewayError

Nunca se lanzaban. Lo que la pasarela de secretos rechaza por petición llega al proceso del sandbox como respuesta HTTP (403, 429, 502, 504), y una configuración que rayd rechaza es SandboxException / SandboxError. En TypeScript también desaparece GatewayErrorOptions.

Migración: quita el import y cualquier except GatewayException o instanceof GatewayError. Si capturabas fallos de la pasarela al crear o refrescar, captura SandboxException / SandboxError (Errores).

Python: BuildException y TemplateException del shim de E2B

rayito.e2b.BuildException y rayito.e2b.TemplateException eran clases propias del shim que nada lanzaba, así que except rayito.e2b.BuildException no atrapaba un Template.build() fallido. Ahora son rayito.BuildException y rayito.TemplateException.

Migración: except rayito.e2b.BuildException ya atrapa los builds fallidos reales. Ten en cuenta dos diferencias con E2B:

  • BuildException hereda de SandboxException (en E2B hereda de Exception): cambian los isinstance/issubclass que suponían lo contrario.
  • Tiene el constructor nativo, BuildException(message, *, reason=..., step=..., command=..., exit_code=..., log_tail=...): el código que la lanza o la hereda debe pasar un único mensaje; BuildException() o BuildException(a, b) fallan con TypeError.

Python: AWS_REGION gana a AWS_DEFAULT_REGION y al perfil

Antes boto3 sólo leía AWS_DEFAULT_REGION o la región del perfil, y el SDK de Python ignoraba AWS_REGION, al contrario que el de TypeScript y la CLI. Ahora toda sesión boto3 del SDK (plano de control, staging S3, secretos, índice DynamoDB, eventos, EFS, CloudFormation…) resuelve la región en un único sitio con esta prioridad:

region= > sesión del llamante > AWS_REGION > AWS_DEFAULT_REGION > perfil

Una sesión del llamante sin región sigue esa misma cadena. Quien sólo exporta AWS_DEFAULT_REGION no nota cambios.

Migración: si exportas AWS_REGION con un valor distinto de AWS_DEFAULT_REGION o de la region de tu perfil, el SDK pasa a operar en la región de AWS_REGION. Para conservar la anterior, quita AWS_REGION del entorno o pasa region= explícita.

Correcciones

  • connect() recupera sbx.gateways (Python sync y async, y TypeScript). Otro proceso (un worker, una API, una tarea programada) ya puede usar sbx.agent sobre un sandbox creado con gateways= sin recrearlo: connect() lee una vez el ConfigureStatus de rayd (nombre, puerto y último error de cada ruta; nunca el upstream ni las cabeceras). En un handle recuperado, refresh() sólo relee el estado; rotar la clave sigue siendo cosa del handle que llamó a create(gateways=), y en uno recuperado reincarnate() lanza. Si rayd rechaza el access token en esa lectura, connect() no falla: el error sale en la primera llamada autenticada, como antes (Usar el agente desde otro proceso).
  • Docstrings, TSDoc, ayuda de la CLI y mensajes alineados con la documentación: las excepciones sin docstring lo tienen, los códigos de MountException / MountError y AgentException / AgentError dicen lo que pasa de verdad, reincarnate() lista todo lo que reaplica, y los errores sin región del índice y de Template.build piden AWS_REGION.
  • rayito doctor conoce la serie 0.9: exige el rayd del tag rayd-v0.9.0 para el SDK 0.9 (Compatibilidad).

rayd 0.9.0: sin cambios en el agente. La recuperación de sbx.gateways usa el ConfigureStatus que ya existía, y la versión sube en paso con los SDK.

Cómo actualizar desde 0.8.x

  1. Actualiza el SDK.

    pip install -U "rayito[cli]"

    pnpm add rayito@latest

  2. Republica tu imagen sobre rayd 0.9.0 (Imágenes). La serie de compatibilidad pasa a 0.9: rayito doctor exige el rayd del tag rayd-v0.9.0 para el SDK 0.9 y da FAIL en la comprobación compatibility con una imagen 0.8. Si usas el agente, reconstruye también su imagen con AgentTemplate o rayito agent template build.

  3. Revisa los cambios que rompen:
Qué Hasta 0.8.x Desde 0.9.0
serve= / serve en agent_pool_warmup() y prepare(), attach= / attach en run()/stream(), RunRequest.attach opción D: un opencode serve residente en cada plaza del pool TypeError / error de tipos; usa la opción C (agent_pool_warmup(runtime))
GatewayException (Python), GatewayError y GatewayErrorOptions (TypeScript) exportadas, nunca lanzadas no existen; captura SandboxException / SandboxError
rayito.e2b.BuildException / TemplateException (Python) clases propias del shim que nada lanzaba las nativas; BuildException es un SandboxException con el constructor nativo
AWS_REGION distinto de AWS_DEFAULT_REGION o del perfil (Python) se ignoraba gana; pasa region= para fijar otra

Fuera de esas filas, no hay cambios incompatibles en la API pública de 0.8.x.