Automations

Automations are the web surface for user-owned scheduled AI work. The current implementation schedules chats, not arbitrary workflow graphs and not Research Workspace runs.

Implemented

/automations lists and edits scheduled chat Automations with search, status filtering, bounded instruction snippets, operational status, next/last run times, generated-chat counts, and compact run/edit/delete controls.
Automation editors use the shared workspace shell, sticky save/delete actions, shared Markdown instructions editor, reusable schedule editor, and the same chat setup options users get before starting a chat.
One visible schedule is exposed in the UI and API: once, hourly, daily, weekly, or monthly. Weekly supports multiple selected weekdays; monthly uses a calendar day picker; new times default to rounded 10-minute values in the browser timezone.
Automation chat setup includes an explicit Space picker. New Automations can default from the selected workspace Space, but saved Automations run against their stored Space rather than the user’s current UI Space.
Generated chats are normal chat threads with origin=automation lineage. They appear from the editor slideover, All Chats route filters, dashboard activity, and the named chat thread lineage badge beside the sticky title menu.
Generated chat realtime visibility is delayed until lineage, the persisted generated user message, and active turn state are available. Opening the thread during a run shows the generated user message first, then attaches to the active AI SDK stream when available, so the owner sees normal submitted, working, streaming, and completion behavior.
Chat completion reconciliation preserves the current thread scroll position and keeps already-matching streamed messages mounted, so reading a streaming generated chat does not jump or flicker when the persisted thread refresh lands.
Compact sidebar chat rows show Automation-origin lineage as a quiet icon near the mode icon, and their overflow menu can run the source Automation again when the Automation still exists.
The dashboard previews upcoming runs, recent generated chats, and Automations that need attention with lazy-loaded tabs and links to the full browse surfaces. Upcoming and Issues show the full returned Automation lists, while Activity remains a five-row generated-chat preview with a See more Activity link beside the always-visible Manage action.
The dashboard Automations heading links to the full Automations page while preserving normal heading styling.
Run now and scheduled dispatch use the same chat-launch path, access checks, generated-chat lineage update, run bookkeeping, and needs-attention recovery copy.
Automation-launched chat turns run in unattended mode. The shared chat isHitlAllowed policy is false for these runs, so optional clarification/source-choice requests use best judgment where possible. If future required setup/input cannot be derived from saved Automation configuration, the run fails closed into needs-attention and does not open the normal blocking chat modal.
Automations have one active issue slot backed by strict issue codes. Focus, Space, setup/customization, access-review, and runtime failures use issue-specific recovery copy and actions, with Focus issues explicitly warning on the reusable Focus control and offering a scrollable View saved Focus detail modal when useful saved source details exist, including saved connector app/account/scope labels when captured.

How It Works

Web owns the /automations UX, dashboard preview, chat-history route filter, and chat-thread lineage presentation, including the compact linked Automation badge beside the sticky chat title.
@repo/contracts owns Automation statuses, schedule payloads, chat config, and generated-chat lineage schemas. Persisted Automation statuses are active, paused, and needs-attention.
API owns user scoping, persistence, schedule materialization, due-row claims, run history, notifications, and the canonical chat launch for Automation runs.
API validates configured Spaces on create/update and validates the stored Space again before run-now or scheduled execution. Missing, foreign, or archived Spaces fail closed instead of creating a chat in a fallback group.
API reconciles active Automation issues before list/detail reads, update, resume, run now, and scheduled runs. Recheck issue uses the same evaluator and clears issue state only when the blocker is resolved.
Connector-backed Focus repair is connector-agnostic and fail-closed. The runner can repair saved connector ids only when the replacement proves the same connector key, account id, and scope key; provider or display-name matches alone do not broaden Focus.
Connector disconnect and OAuth-account deletion routes check Automation Focus dependencies and require explicit confirmation when active Automations would be affected.
API exposes an authenticated active-turn stream attachment for server-started runs; the persisted chat thread remains the durable recovery source when a browser cannot attach to that in-flight stream.
The unattended stream path reports missing setup and access failures back to the Automation runner so the generated chat stays a normal thread and recovery stays on the Automation issue surface.
Mastra owns one code-authored scheduled workflow tick. Per-user schedules remain product data in app persistence so user-created schedules do not create user-authored Mastra workflow definitions.
Scheduler runtime behavior is controlled by AUTOMATION_SCHEDULER_ENABLED, AUTOMATION_SCHEDULER_MAX_AUTOMATIONS_PER_TICK, and AUTOMATION_SCHEDULER_CLAIM_TTL_SECONDS. These settings bound the due-row claim loop and stale-claim retry window; they do not change the user-owned schedule contract.
Run now and scheduled dispatch share the same execution path, so Space validation, saved configuration, generated-chat lineage, active-stream attachment, run history, and needs-attention notifications stay consistent.

Current Limits

The current target is scheduled chats only. targetType=research is reserved for a future scheduled Research Workspace implementation.
The contract and database are array-shaped for schedules, but the V1 UI/API enforce exactly one visible schedule at schedules[0].
The UI does not expose cron expressions, scheduler claims, run ids, Mastra workflow ids, or arbitrary workflow graph editing.
Email and push notifications for Automation failures remain outside the current feature surface.

Developer Verification

Focused contract and API checks:

bun run --cwd packages/contracts test -- src/automations/contracts.test.ts
bun run --cwd apps/api test -- \
  src/automations/automationFocusDependencies.test.ts \
  src/automations/automationRouteHandlers.test.ts \
  src/chats/chatFocusScope.test.ts \
  src/chats/chatFocusAvailability.test.ts \
  src/connectors/connectorRouteHandlers.test.ts

Focused web checks:

bun run --cwd apps/web check-types
bun run --cwd apps/web test -- \
  test/nuxt/AutomationScheduleDefaults.nuxt.spec.ts \
  test/nuxt/AutomationScheduleEditor.nuxt.spec.ts \
  test/nuxt/AutomationGeneratedChatsSlideover.nuxt.spec.ts \
  test/nuxt/AutomationChatSetupEditor.nuxt.spec.ts \
  test/nuxt/AutomationsIndexWorkspace.nuxt.spec.ts \
  test/nuxt/AutomationsProxyRoutes.nuxt.spec.ts \
  test/nuxt/DashboardAutomationsPanel.nuxt.spec.ts \
  test/nuxt/ChatDraftSetupPanel.nuxt.spec.ts \
  test/nuxt/ChatSetupControls.nuxt.spec.ts \
  test/nuxt/ChatAutomationOriginIndicator.nuxt.spec.ts \
  test/nuxt/ChatHistoryRoute.nuxt.spec.ts \
  test/nuxt/ChatThreadTitleActionMenu.nuxt.spec.ts \
  test/nuxt/ConnectorResourcePicker.nuxt.spec.ts \
  test/nuxt/UseConnectorDashboard.nuxt.spec.ts \
  test/nuxt/WorkspaceChatSidebar.nuxt.spec.ts \
  test/nuxt/UseAutomations.nuxt.spec.ts \
  test/nuxt/UseAutomationsRouteState.nuxt.spec.ts \
  test/nuxt/UseChatHistoryRouteState.nuxt.spec.ts

Run bun run test:local before PR handoff when changing Automation runtime behavior, chat streaming, scheduler dispatch, dashboard previews, route filters, or chat list lineage.
Browser verification should create an Automation in the real web app, exercise schedule editing, run now, generated-chat browsing, All Chats Automation filters, and chat-thread lineage.

Canonical Sources

docs/features/automations/spec.md
docs/features/automations/stories/manage-chat-automations.stories.md
docs/features/automations/tests/automations.feature
docs/features/automations/decisions/ADR-001-automations-vs-research-workspace.md
packages/contracts/src/automations/
apps/api/src/automations/
apps/api/src/env.ts
apps/api/.env.example
apps/api/src/mastra/workflows/automationSchedulerWorkflow.ts
apps/web/app/components/automations/
apps/web/app/components/dashboard/DashboardAutomationsPanel.vue