---
url: /docs/en/agentbuff-stack/task-lifecycle.md
---
# Background task workflow

The shipped queue example normalizes a UTF-8 text file deterministically. It does not call an external model. Browser JSON/text tools remain synchronous and free; background tasks use a separate saved-file workflow.

## Complete a task

1. Save a UTF-8 text file in the file library.
2. Open `/tasks` or `/zh/tasks`, select the file and decide whether to remove trailing spaces.
3. Check the current quote and available credits. If configured as paid, explicitly approve the reservation.
4. Submit once and follow the server-reported status. There is no invented progress percentage.
5. After success, inspect and download the private result while available. The original file is unchanged.

The request key is stable for a retry of the same submission. If a response is lost, refresh the list or retry without changing input/options. Changing input/options creates a new request. Do not submit a new request merely to bypass an uncertain result.

## Retry and cancel

Retries retain the original attempt limit and credit reservation. Failed tasks may be retried only when input, processor, quota and remaining budget are still valid. Cancelling a running execution records a request; its input and reserved credits are released only through settlement.

Tasks retain history when individual files expire or are deleted. An unknown processor outcome enters review rather than blindly retrying. Old execution/delivery versions cannot overwrite newer results. Dead-letter recovery does not reset attempt counts.

## Extend safely

Use the existing task store, delivery, lifecycle, consumer and results modules for their separate responsibilities. `tasks.maxActive`, `maxAttempts`, rate limits and processor configuration bound execution. New submissions need storage and queue bindings. Disabling new work preserves existing read/cancel access.

The API checks personal ownership, same-origin mutations and fresh state. Language changes affect presentation, not request identity, execution count or ownership. New processors require actual input validation, output checks, cost accounting and provider reconciliation; a new label is not an implementation.

Local queue/object/database checks have been exercised. Cloud resources and real product/model delivery are deferred. See [Credits and payments](./billing-tasks).