DocumentationExtend the framework
Add background work
Use durable triggers and idempotent steps so useful work continues while clients are closed.
On this page
Use scheduled Tasks firstAdd a platform stepKeep workflow code deterministicMake retries safeReturn useful outcomesVerify the lifecycleChoose between a user's scheduled Task and a platform background step. A daily research request belongs in scheduled Tasks. A framework feature that periodically consolidates context belongs in a versioned background step.
iOS calls scheduled entry points Triggers. The API retains /scheduled-tasks; each occurrence creates a separate Task conversation. These schedules do not implement the proposed gadget-event automation runtime.
Use scheduled Tasks first#
Scheduled plans are owned records with a time zone, timing rule and revision. Temporal admits ordinary isolated Tasks when the plan is due. The execution and result appear through the existing task protocol.
Revisions fence obsolete timers. Overlapping runs are skipped. Editing a schedule must not let an old workflow admit work under the previous plan. Use the existing scheduled-task contract before introducing another scheduler.
Add a platform step#
server/src/background/registry.ts defines BackgroundStep. Each step has a versioned key and an async run(context). Context includes userId, tickId, scheduledAt, an idempotencyKey stable across retries, and an abort signal.
Implement a factory that accepts the repositories and services the step needs. Register the returned step in the array passed to createBackgroundActivities in server/src/worker-main.ts, alongside the applicable Feed and Memory steps. The empty registry default exists for isolated tests; changing it alone does not wire a production step.
A step can start a separate per-user workflow when it has a backlog to drain. The Notes hook does this: the hourly check starts or reuses one editor workflow, which continues incomplete work immediately. The trigger cadence does not impose a document quota.
Keep workflow code deterministic#
Temporal workflow code coordinates timers and activities. Put network calls, database changes and agent execution in activities or workers. Do not run a model inside a timer callback in the API process.
Use the official client's client.beta.agents with @rebyteai/agent-extensions for generated content. Bound each run and read large inputs in parts. Preserve a persistent Session when its workspace is part of the feature. Select its tool catalog deliberately and retain the account's execution configuration. Unattended steps cannot assume a foreground phone is available.
Make retries safe#
Store a receipt under the stable step identity before reporting completion. Commit related state together through a repository. A repeated activity should return the accepted result or continue reconciliation rather than create another card or external action.
For generated reminders, preserve source resource IDs and connection generations. Recheck their validity when delivering. If a user deletes context or disconnects a service, dependent output must be withdrawn.
Return useful outcomes#
Background work may complete without visible content. The existing Feed path treats an empty check as empty, not as a reason to invent a status card. Surface failures where the user can act on them, and keep operator diagnostics separate from agent copy.
Verify the lifecycle#
Run npm run test:background for timer, restart and idempotency changes. Use npm run test:scheduled-tasks for schedule edits and overlap rules. These suites require PostgreSQL and Temporal tooling; see the server guide.
Also check deletion during a run, revoked connectors and a retry after an uncertain write. Continue with deployment and services when the local lifecycle is sound.