Agendamento, endpoint e executor

A configuração de uma tarefa também mora no repositório: quando ela roda sozinha (schedules), se outro sistema pode dispará-la (endpoint), qual modelo usa (executor) e os metadados livres (metadata).

Agendamentos (schedules)

Cada item agenda a tarefa num ambiente. O ambiente é casado pelo nome exato: o criado no console ou o declarado no kadu.yaml, que a sincronização aplica antes.

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

Chave	Obrigatória	Efeito
environment	sim	Nome exato do ambiente. Um agendamento por tarefa e ambiente.
cron	sim	Expressão de cinco campos.
timezone	não	Fuso IANA (America/Sao_Paulo). Ausente = UTC, mesmo num agendamento que já existia com outro fuso.
paused	não	true pausa, false retoma. Ausente = não mexe: a pausa feita no console sobrevive à sincronização.

A sincronização distingue o agendamento que ela criou do criado no console:

Situação	O que a sincronização faz
Ambiente declarado, sem agendamento	cria, marcado como do repositório
Agendamento apagado no console, ambiente declarado	recria com os valores do frontmatter
Agendamento existente (de qualquer origem), ambiente declarado	atualiza cron e timezone; paused só se declarado
Agendamento do repositório, ambiente fora da lista	apaga
Agendamento do console, ambiente fora da lista	não mexe

schedules ausente não toca em nada. schedules: [] remove os agendamentos que o repositório criou e deixa os do console.

Um item com erro descarta a lista inteira daquela tarefa, com aviso: item sem cron, paused: "sim", ambiente repetido, ambiente que não existe, cron ou fuso inválidos. É de propósito: aplicar só os itens bons apagaria o agendamento do item com erro de digitação. Enquanto o aviso estiver lá, os agendamentos da tarefa ficam como estavam.

Agendamento não empilha: com a tarefa já em execução no horário, o disparo é pulado. Um cron mais curto do que a duração da tarefa perde disparos.

Endpoint de disparo (endpoint)

Torna a tarefa disparável por outro sistema, com POST /run-task/{task_id} e corpo JSON. O bloco declara só o estado e o tipo de autenticação:

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

A credencial (token, senha, valor de header) é gravada cifrada no Kadu e nunca entra no repositório. Uma chave a mais no bloco, como token:, é ignorada. A sincronização concilia os dois lados, e o endpoint nunca fica ligado sem credencial:

Estado no Kadu	Frontmatter	O que a sincronização faz
sem configuração	enabled: false	nada
sem configuração	enabled: true	cria a configuração desligada, só com o tipo de autenticação, e avisa
credencial completa	enabled: true, mesmo auth	liga
credencial incompleta	enabled: true, mesmo auth	mantém desligado e avisa a cada sincronização
auth gravado diferente	enabled: true	não toca e avisa: trocar o tipo apagaria a credencial
qualquer	enabled: false	desliga, sem apagar a credencial

O caminho de uma tarefa nova: push com enabled: true → a sincronização cria a configuração desligada e avisa → a equipe da Kobana cadastra a credencial → a próxima sincronização liga. Depois disso, a credencial pode ser trocada em Configurações → Endpoints.

Como todo campo do bloco, o repositório manda: um endpoint desligado à mão no console volta a ligar no próximo push enquanto o frontmatter disser enabled: true. Bloco sem enabled ou auth, ou com auth fora da lista, é descartado inteiro.

Dois efeitos no corpo da skill:

• disparo pelo endpoint não traz arquivo, mesmo com accepts_input_files: true: o corpo da chamada é só JSON. Se a tarefa aceita os dois caminhos, trate "nenhum arquivo" como caso normal;
• environment_id é obrigatório nesse caminho, e um secret de required_secrets sem valor no ambiente recusa o disparo com 422 missing_secrets antes de criar a execução.

O contrato da chamada está em Endpoint de disparo.

Tarefa acionada pelo Inbox Autônomo

O endpoint recebe direto o webhook do Inbox Autônomo da Kobana. O e-mail recebido vira os parâmetros, filtrado pelas propriedades do parameters_schema, e a data da entrega vira a data de referência. Schema mínimo de uma tarefa acionada pelo Inbox:

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

Executor e modelo (executor)

model escolhe o nível (preço, executor e modelo). executor sobrescreve só o executor e o modelo de IA, por cima do nível. O preço continua o do nível.

  executor:
    cli: claude_code          # claude_code | goose
    model: claude-opus-4-8    # claude_code: claude-* ou os apelidos sonnet, opus, haiku

executor: inherit limpa o override e volta a herdar do nível. Ausente não mexe, inclusive num override gravado pela equipe da Kobana. claude_code com um modelo que não é da Anthropic não é aplicado e vira aviso.

Use com parcimônia: uma tarefa com override não acompanha a troca de modelo do nível, e o custo deixa de ser previsível pelo nível.

Metadados (metadata)

Um objeto livre gravado inteiro no custom_metadata da tarefa, visível na API v1 e nos webhooks. Declarado, substitui o objeto todo; ausente, não mexe.

  metadata:
    dono: financeiro
    centro_de_custo: "42"