NEXUS Background Worker

Technical summary

Background task and queue processing worker for NEXUS: auto-executes simple tasks (HTTP checks and log cleanup), moves complex tasks to in_progress and notifies the AI by email with full context (description, attachments, priority and API token), via hourly cron or the API.

Executed scope

• plugin.json: v1.0.0, slug nexus-worker (legacy_slugs: ["worker"]), name "NEXUS Background Worker", "Core" category, is_core: true, public author_url and website (perciocastelo.com.br).
• No own tables — operates on the core tasks/comments schema (no DDL, no migrations).
• No own UI — no tab.php; access via cron, API (run_worker) and doc ("Background Worker", play icon).
• API: 1 action — run_worker (worker_run($task_id ?? null)), optional task_id.
• tasks_by_priority($status) — reads the queue via tasks_read(1, 999, "", ["status" => $status]).
• Auto-Exec (worker_try_autoexec) — tries to resolve the task by itself:

- HTTP check: title with verificar|checar|check|ping|status http + URL in the description → get_headers() and HTTP code record (or timeout/erro); - Log cleanup: title with limpar log|clean log|purge log → keeps only the last 200 lines of LOG_FILE; - Other tasks → ["auto" => false, "note" => "Requer execucao por IA."].

• build_task_context($task) — formatted context (TAREFA, ID, PROJETO, PRIORIDADE via priority_label, STATUS, DESCRIÇÃO, NOTAS ANTERIORES, ATTACHMENTS with original_name+url) + AI INSTRUCTIONS in 5 steps (access the SITE_URL dashboard, read the task and attachments, execute, comment the result, switch to done) + credentials (API: SITE_URL/api.php, TOKEN: setting('security.api_key')).
• worker_run($task_id = null) — 2 modes:

- Manual: specific task_id, validating empty holding and pending/in_progress status ("Tarefa nao disponivel." error) — used by the "Executar Agora" button; - Batch: the whole pending queue ("Nenhuma tarefa pendente." error when empty). - Per task: autoexec → task_update to done + note [Worker YYYY-MM-DD HH:MM] <result> + comment_add("system", ...); complex → task_update to in_progress + "Execucao solicitada..." comment (next step for the AI) + notify_task_ready_for_ia($task, $context).

• Cron — cronjob.json v1 with informative worker_autoexec job (editable: false, tick: false, run.mode: none — the autoexec queue runs only in worker.php, never via the cronjobs hub "Run" button) + OS cron **0 * * * *** (hourly).
• No fastr, no modals, no JS assets and no own i18n.

Stack and tools

• PHP 8 (no framework)
• MySQL 8 (core tasks/comments)
• cURL / get_headers (HTTP checks)
• OS cron + NEXUS plugin system (PluginManager: API actions, doc)

Operational tags

• Background Tasks
• Worker
• Queue
• Automação
• Verificação HTTP
• Notificação IA
• Cron
• Plugin NEXUS

Operational result

• Queues processed without intervention: pending tasks are evaluated hourly (cron) or on demand (API).
• Simple tasks resolved on the spot: HTTP availability checks (status code) and log cleanup retaining the last 200 lines.
• Complex tasks escalated to the AI: full context (description, attachments, priority, API token) sent by email with step-by-step instructions.
• Full traceability: every execution adds a system comment to the task with the result note and the worker timestamp.
• Selective execution: task_id in the API triggers the worker for a single task ("Executar Agora" button) without processing the whole queue.
• No double-execution risk: empty holding + pending/in_progress status are prerequisites for manual mode.
• The hub cron job is informative (run.mode: none) — processing happens exclusively in worker.php.