Programación, endpoint y ejecutor

La configuración de una tarea también vive en el repositorio: cuándo corre sola (schedules), si otro sistema puede lanzarla (endpoint), qué modelo usa (executor) y los metadatos libres (metadata).

Programaciones (schedules)

Cada elemento programa la tarea en un entorno. El entorno se empareja por el nombre exacto: el creado en la consola o el declarado en el kadu.yaml, que la sincronización aplica antes.

  schedules:
    - environment: Produção
      cron: "0 9 * * 1-5"
      timezone: America/Sao_Paulo
    - environment: Sandbox
      cron: "0 12 * * 1"
      paused: true

Clave	Obligatoria	Efecto
environment	sí	Nombre exacto del entorno. Una programación por tarea y entorno.
cron	sí	Expresión de cinco campos.
timezone	no	Zona horaria IANA (America/Sao_Paulo). Ausente = UTC, incluso en una programación que ya existía con otra zona horaria.
paused	no	true pausa, false reanuda. Ausente = no toca: la pausa hecha en la consola sobrevive a la sincronización.

La sincronización distingue la programación que ella creó de la creada en la consola:

Situación	Qué hace la sincronización
Entorno declarado, sin programación	la crea, marcada como del repositorio
Programación borrada en la consola, entorno declarado	la recrea con los valores del frontmatter
Programación existente (de cualquier origen), entorno declarado	actualiza cron y timezone; paused solo si está declarado
Programación del repositorio, entorno fuera de la lista	la borra
Programación de la consola, entorno fuera de la lista	no la toca

schedules ausente no toca nada. schedules: [] quita las programaciones que creó el repositorio y deja las de la consola.

Un elemento con error descarta la lista completa de esa tarea, con un aviso: elemento sin cron, paused: "sim", entorno repetido, entorno que no existe, cron o zona horaria inválidos. Es a propósito: aplicar solo los elementos buenos borraría la programación del elemento con error de tipeo. Mientras el aviso esté ahí, las programaciones de la tarea quedan como estaban.

La programación no se apila: con la tarea ya en ejecución en el horario, el lanzamiento se omite. Un cron más corto que la duración de la tarea pierde lanzamientos.

Endpoint de lanzamiento (endpoint)

Hace que la tarea pueda ser lanzada por otro sistema, con POST /run-task/{task_id} y cuerpo JSON. El bloque declara solo el estado y el tipo de autenticación:

  endpoint:
    enabled: true
    auth: bearer        # basic | bearer | header | params

La credencial (token, contraseña, valor de header) se guarda cifrada en Kadu y nunca entra al repositorio. Una clave de más en el bloque, como token:, se ignora. La sincronización concilia los dos lados, y el endpoint nunca queda activado sin credencial:

Estado en Kadu	Frontmatter	Qué hace la sincronización
sin configuración	enabled: false	nada
sin configuración	enabled: true	crea la configuración desactivada, solo con el tipo de autenticación, y avisa
credencial completa	enabled: true, mismo auth	activa
credencial incompleta	enabled: true, mismo auth	lo mantiene desactivado y avisa en cada sincronización
auth guardado distinto	enabled: true	no lo toca y avisa: cambiar el tipo borraría la credencial
cualquiera	enabled: false	desactiva, sin borrar la credencial

El camino de una tarea nueva: push con enabled: true → la sincronización crea la configuración desactivada y avisa → el equipo de Kobana registra la credencial → la próxima sincronización la activa. Después de eso, la credencial se puede cambiar en Configuración → Endpoints.

Como todo campo del bloque, el repositorio manda: un endpoint desactivado a mano en la consola vuelve a activarse en el próximo push mientras el frontmatter diga enabled: true. Un bloque sin enabled o auth, o con auth fuera de la lista, se descarta completo.

Dos efectos en el cuerpo de la skill:

• el lanzamiento por el endpoint no trae archivos, aunque haya accepts_input_files: true: el cuerpo de la llamada es solo JSON. Si la tarea acepta los dos caminos, trata "ningún archivo" como un caso normal;
• environment_id es obligatorio en ese camino, y un secret de required_secrets sin valor en el entorno rechaza el lanzamiento con 422 missing_secrets antes de crear la ejecución.

El contrato de la llamada está en Endpoint de lanzamiento.

Tarea activada por el Inbox Autónomo

El endpoint recibe directamente el webhook de el Inbox Autónomo de Kobana. El correo recibido se convierte en los parámetros, filtrado por las propiedades del parameters_schema, y la fecha de la entrega se convierte en la fecha de referencia. Schema mínimo de una tarea activada por el Inbox:

{
  "type": "object",
  "required": ["message_id"],
  "properties": {
    "dry_run": { "type": "boolean", "default": false },
    "message_id": { "type": "string" },
    "download_url": { "type": ["string", "null"] }
  },
  "additionalProperties": false
}

Ejecutor y modelo (executor)

model elige el nivel (precio, ejecutor y modelo). executor sobrescribe solo el ejecutor y el modelo de IA, por encima del nivel. El precio sigue siendo el del nivel.

  executor:
    cli: claude_code          # claude_code | goose
    model: claude-opus-4-8    # claude_code: claude-* o los alias sonnet, opus, haiku

executor: inherit limpia el override y vuelve a heredar del nivel. Ausente no toca nada, incluso un override guardado por el equipo de Kobana. claude_code con un modelo que no es de Anthropic no se aplica y se convierte en un aviso.

Úsalo con moderación: una tarea con override no acompaña el cambio de modelo del nivel, y el costo deja de ser predecible por el nivel.

Metadatos (metadata)

Un objeto libre guardado completo en el custom_metadata de la tarea, visible en la API v1 y en los webhooks. Declarado, reemplaza el objeto entero; ausente, no toca nada.

  metadata:
    dono: financeiro
    centro_de_custo: "42"