Add background work

Choose 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.

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.

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 @rebyteai/agent-sdk and client.beta.agents for generated content. Bound the session, 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 personal-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.