HiveGrid-Wireframes/hivegrid-cloud/docs/agent-playbooks/worker-backed-features.md

Worker-Backed Feature Pattern

Use this when a feature performs slow, retryable, external, scheduled, browser-backed or resource-heavy work.

Worker Required When

• Work may exceed normal request time.
• Work needs retries.
• Work calls unreliable external providers.
• Work performs browser automation.
• Work processes files, imports, exports or media.
• Work should continue after a user navigates away.
• Usage metering or cleanup must be reliable.

Required Manifest Entries

The feature manifest must declare:

• integration.workers.required.
• Queue names from packages/queue/src/names.ts.
• Job names from packages/queue/src/payloads.ts.
• Notes about retries, idempotency and cleanup.
• API route or UI flow that enqueues the job.
• UAT checks for worker success and failure states.

Implementation Rules

• API routes enqueue jobs and return job/status IDs for long-running work.
• Workers load secrets server-side from admin/platform configuration.
• Jobs must be scoped by tenant/user where applicable.
• Jobs should be idempotent or have explicit duplicate protection.
• Browser jobs must enforce admin-owned navigation policy.
• Failures should be visible to the initiating user or admin.
• AI/browser-backed features use toolctrl.ai-chatbot and toolctrl.browser-automation unless a manifest explicitly justifies a new queue.

Browser-Backed Work

Browser-backed features require extra constraints:

• Domain allowlist/denylist.
• Timeout policy.
• Screenshot/artifact storage policy.
• Credential handling rules.
• Cleanup jobs for sessions and artifacts.
• Audit events for start, completion and failure.