Schedule, endpoint and executor

A task's configuration also lives in the repository: when it runs on its own (schedules), whether another system can trigger it (endpoint), which model it uses (executor) and free-form metadata (metadata).

Schedules (schedules)

Each item schedules the task in an environment. The environment is matched by exact name: the one created in the console or the one declared in kadu.yaml, which the sync applies first.

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

Key	Required	Effect
environment	yes	Exact name of the environment. One schedule per task and environment.
cron	yes	Five-field expression.
timezone	no	IANA time zone (America/Sao_Paulo). Missing = UTC, even on a schedule that already existed with another time zone.
paused	no	true pauses, false resumes. Missing = do not touch: a pause made in the console survives the sync.

The sync distinguishes the schedule it created from the one created in the console:

Situation	What the sync does
Environment declared, no schedule	creates it, marked as the repository's
Schedule deleted in the console, environment declared	recreates it with the frontmatter values
Existing schedule (from any origin), environment declared	updates cron and timezone; paused only if declared
Repository's schedule, environment outside the list	deletes it
Console's schedule, environment outside the list	does not touch it

A missing schedules touches nothing. schedules: [] removes the schedules the repository created and leaves the console's.

One item with an error discards the whole list for that task, with a warning: an item without cron, paused: "sim", a repeated environment, an environment that does not exist, an invalid cron or time zone. This is on purpose: applying only the good items would delete the schedule of the item with the typo. While the warning is there, the task's schedules stay as they were.

A schedule does not stack: with the task already running at the scheduled time, the run is skipped. A cron shorter than the task's duration loses runs.

Run endpoint (endpoint)

Makes the task triggerable by another system, with POST /run-task/{task_id} and a JSON body. The block declares only the state and the authentication type:

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

The credential (token, password, header value) is stored encrypted in Kadu and never goes into the repository. An extra key in the block, such as token:, is ignored. The sync reconciles both sides, and the endpoint is never turned on without a credential:

State in Kadu	Frontmatter	What the sync does
no configuration	enabled: false	nothing
no configuration	enabled: true	creates the configuration turned off, with only the authentication type, and warns
complete credential	enabled: true, same auth	turns on
incomplete credential	enabled: true, same auth	keeps it off and warns on every sync
stored auth differs	enabled: true	does not touch it and warns: changing the type would delete the credential
any	enabled: false	turns off, without deleting the credential

The path for a new task: push with enabled: true → the sync creates the configuration turned off and warns → the Kobana team registers the credential → the next sync turns it on. After that, the credential can be changed in Settings → Endpoints.

Like every field in the block, the repository rules: an endpoint turned off by hand in the console turns back on at the next push as long as the frontmatter says enabled: true. A block without enabled or auth, or with an auth outside the list, is discarded entirely.

Two effects on the skill body:

• a run through the endpoint brings no file, even with accepts_input_files: true: the call body is JSON only. If the task accepts both paths, treat "no file" as a normal case;
• environment_id is required on this path, and a secret in required_secrets with no value in the environment rejects the run with 422 missing_secrets before creating the execution.

The call contract is in Run endpoint.

Task triggered by the Autonomous Inbox

The endpoint directly receives Kobana's Autonomous Inbox webhook. The received email becomes the parameters, filtered by the properties of parameters_schema, and the delivery date becomes the reference date. Minimum schema for a task triggered by the 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 and model (executor)

model chooses the tier (price, executor and model). executor overrides only the executor and the AI model, on top of the tier. The price remains the tier's.

  executor:
    cli: claude_code          # claude_code | goose
    model: claude-opus-4-8    # claude_code: claude-* or the aliases sonnet, opus, haiku

executor: inherit clears the override and goes back to inheriting from the tier. Missing does not touch it, including an override stored by the Kobana team. claude_code with a non-Anthropic model is not applied and becomes a warning.

Use sparingly: a task with an override does not follow the tier's model change, and the cost is no longer predictable from the tier.

Metadata (metadata)

A free-form object stored whole in the task's custom_metadata, visible in the v1 API and in webhooks. When declared, it replaces the whole object; when missing, it does not touch it.

  metadata:
    dono: financeiro
    centro_de_custo: "42"