AWR
GitHub
Español
English中文Españolहिन्दीPortuguêsРусский日本語한국어DeutschFrançais

Inicio rápido

Ver fuente en GitHub

Este recorrido te lleva desde una instalación nueva de AWR hasta un traspaso de sesión verificado: instala la CLI, inicializa un proyecto, inicia una sesión de trabajo y demuestra que una sesión sucesora puede continuar donde la primera lo dejó. Todo se puede copiar y pegar; AWR incluye su propio SQLite.

1. Instala AWR

AWR se distribuye como paquetes nativos en npm y PyPI. Ambos canales instalan la misma CLI en Rust (awr) y el mismo servidor MCP (awr-mcp); no existe un SDK separado de JavaScript o Python.

Con npm (requiere Node 22.14 o superior):

npm install -g @originoneai/agent-work-runtime@0.5.1

O con pip, dentro de un entorno virtual (requiere Python 3.9 o superior):

python -m pip install agent-work-runtime==0.5.1

Verifica ambos ejecutables:

awr --version
awr-mcp --version

Las plataformas soportadas son macOS 15+ (arm64 e Intel x64), Linux x64 y arm64 con glibc 2.39 o superior (la línea base de Ubuntu 24.04) y Windows x64. En Linux, comprueba primero tu glibc:

ldd --version | head -n 1

En las instalaciones con npm, mantén las dependencias opcionales activadas: el lanzador resuelve un paquete nativo por plataforma. No hay script de instalación ni descargador de red; los wheels de pip incorporan los binarios. Existe un tercer canal para autores de aplicaciones: un payload nativo fijado con los dos binarios que una aplicación host puede incrustar, de modo que sus usuarios no necesiten Node, Python ni Rust en tiempo de ejecución.

2. Inicializa tu proyecto

La inicialización es una operación de dos pasos: una vista previa y luego una aceptación explícita. Nada se escribe hasta que pasas --accept.

AWR_PROJECT=/absolute/path/to/your/project
awr --project "$AWR_PROJECT" init

Lee la vista previa: muestra el inventario que AWR encontró — registros de tareas Markdown existentes, fuentes YAML, objetivos — y el mapeo de fuentes que propone. Los archivos existentes nunca se sobrescriben; tus documentos originales siguen siendo la autoridad. Si la vista previa te parece correcta, acéptala:

awr --project "$AWR_PROJECT" init --accept

Para un proyecto en blanco, declara su propósito desde el principio:

awr --project "$AWR_PROJECT" init --goal "Deliver a document portal" --accept

Si tu registro Markdown usa palabras de estado no estándar, mapealas en el momento de la inicialización:

awr --project "$AWR_PROJECT" init \
  --status-map pending=planned --status-map complete=completed --accept

Luego inspecciona el informe de organización:

awr --project "$AWR_PROJECT" intake inspect --json

El organization.state del informe te dice dónde estás: ready significa que al menos una tarea tiene un objetivo declarado en la fuente, criterios de aceptación, una acción siguiente y prerrequisitos resueltos. needs_organization significa que falta algo: las actions ordenadas del informe te dicen qué añadir a tus archivos fuente.

3. Inicia una sesión de trabajo

Una sesión es la unidad de propiedad del trabajo en AWR. Estos comandos usan un pequeño ayudante de shell para que cada llamada lleve la ruta del proyecto y salida JSON:

AWR_BIN=$(command -v awr)
AWR_WORK=INTAKE-001          # a task key from your intake report
AWR_AGENT=agent-primary      # a label for who is working
AWR_MODEL=your-current-model # a recorded label; AWR does not invoke the model
AWR_NOTES=$(mktemp -d "${TMPDIR:-/tmp}/awr-session.XXXXXX")
awrj() { "$AWR_BIN" --project "$AWR_PROJECT" --json "$@"; }

Comprueba qué es ejecutable y luego inicia una sesión con una reserva (propiedad en tiempo de ejecución del elemento de trabajo) y la revisión actual del proyecto:

awrj ready
AWR_REV=$(awrj status | jq -er '.project_revision')
awrj session start --work "$AWR_WORK" --agent "$AWR_AGENT" \
  --provider generic --model "$AWR_MODEL" --claim --ttl-ms 3600000 \
  --expected-revision "$AWR_REV" > "$AWR_NOTES/start.json"
AWR_SESSION=$(jq -er '.session.id' "$AWR_NOTES/start.json")

Compila el contexto de trabajo: el objetivo, los criterios de aceptación, los hechos registrados y el historial reunidos en un paquete acotado:

awrj context compile --work "$AWR_WORK" --session "$AWR_SESSION" \
  --budget 5000 > "$AWR_NOTES/context.json"
jq -e '.completeness.complete and (.work_context != null)' "$AWR_NOTES/context.json"

Lee el paquete, no solo el booleano. Ante BudgetExceeded, amplía --budget; ante SourceStale, ejecuta awrj source reindex y compila de nuevo.

4. Registra el progreso con un punto de control

Antes de apartarte — o antes de que una conversación larga del host se compacte — guarda un punto de control con el hash de contexto que realmente usaste, un resumen honesto, la acción siguiente exacta y todos los cabos abiertos:

AWR_CONTEXT_HASH=$(jq -er '.work_context.context_hash' "$AWR_NOTES/context.json")
AWR_REV=$(awrj status | jq -er '.project_revision')
awrj session checkpoint --session "$AWR_SESSION" --agent "$AWR_AGENT" \
  --context-hash "$AWR_CONTEXT_HASH" \
  --digest "Record the work actually done; do not invent a passing review." \
  --next-action "State the exact next operator or agent action." \
  --open-loop "List every unresolved loop." \
  --expected-project-revision "$AWR_REV" > "$AWR_NOTES/checkpoint.json"

Un punto de control puede registrar trabajo sin terminar; no es una prueba de pruebas superadas ni de criterios de aceptación cumplidos.

5. Continúa el trabajo en una sesión nueva

Para demostrar que la continuación funciona, termina la primera sesión y reanuda desde ella: es la misma ruta de toma de posesión que usaría un agente, una máquina o una conversación de host nuevos. Terminar libera la reserva; no marca el trabajo fuente como completado:

AWR_REV=$(awrj status | jq -er '.project_revision')
awrj session end --session "$AWR_SESSION" --outcome incomplete \
  --expected-revision "$AWR_REV"

Ahora reanuda. Cualquier agente — uno distinto, o el mismo más tarde — crea una sesión sucesora a partir de la predecesora:

AWR_PREDECESSOR="$AWR_SESSION"
awrj session show "$AWR_PREDECESSOR"
AWR_REV=$(awrj status | jq -er '.project_revision')
awrj session resume --from-session "$AWR_PREDECESSOR" \
  --agent successor --provider generic --model "$AWR_MODEL" \
  --budget 5000 --expected-revision "$AWR_REV" > "$AWR_NOTES/resume.json"
jq -e '.context_ready' "$AWR_NOTES/resume.json"
AWR_SESSION=$(jq -er '.resumed.session.id' "$AWR_NOTES/resume.json")

Dos comprobaciones confirman que el traspaso funcionó:

  • jq -e '.context_ready' sale con 0: el sucesor recibió el contexto registrado de la predecesora, incluido el último punto de control correcto.
  • La sesión reanudada tiene un ID nuevo: reanudar crea una sesión AWR nueva en lugar de modificar la anterior.

También puedes inspeccionar el estado de recuperación en modo solo lectura en cualquier momento:

awrj recovery inspect --session "$AWR_SESSION"

¿Trabajas dentro del chat de un agente de programación? Vincula la conversación del host con la sesión AWR para que los puntos de control sobrevivan a la compactación del host:

awrj client bind --client generic --external-session "myhost:$HOST_CONVERSATION_ID" \
  --work "$AWR_WORK" --session "$AWR_SESSION"

AWR no transfiere la memoria de proceso de un host ni toma el control de procesos existentes arbitrarios: la continuidad proviene de lo que se registró explícitamente.

A dónde ir después