18 KiB
status, created, owner
| status | created | owner |
|---|---|---|
| draft | 2026-05-21 | jcfs |
Automations in Settings
Why
Users want to schedule an agent to run a prompt on a cron (or on a GitHub PR event, or on a webhook) without first navigating to per-workspace settings, picking the right workspace, then drilling down into a workflow. They also want two execution flavors: tracked work that shows up on the kanban as a real task (current default), and fire-and-forget runs whose output is just informational — not kanban clutter.
The Automations feature, originating in PR #406, gives kandev a standalone trigger-based subsystem (cron, GitHub PR events, webhooks) that turns triggers into Tasks. This spec extends it with two changes: (1) a per-automation execution_mode choice between task (existing behavior) and run (new — creates an ephemeral kanban-hidden task that surfaces only through the AutomationRun row), and (2) a flat /settings/automations entry point that drops the per-workspace nesting from the sidebar.
What
- Every automation has an
execution_modefield —task(default) orrun. The choice is per-automation, editable in the editor. - Every automation has an optional
repository_idsfield — an ordered list of repository IDs. When non-empty, scheduled and webhook firings pin the task to every listed repository (each on its own default branch, mirroring how the task-creation dialog resolves an explicit repository). When empty, falls back to the workspace's first repository (legacy behavior).github_prtriggers always use the PR's own repository and ignorerepository_ids. - The editor's repository picker matches the task-creation dialog's UX: lists both registered workspace repositories AND filesystem-discovered repositories under the workspace's roots. Picking a discovered repo registers it with the workspace at automation-save time (one round-trip via
createRepositoryAction), then stores the resulting id on the automation. After the first save, the selection is promoted fromdiscoveredtoregisteredso subsequent edits don't try to re-register. - Multi-repository selection is gated on the selected executor profile's capability, reusing the task-creation dialog's
getMultiRepoExecutorDisabledReasonpredicate (apps/web/components/task-create-dialog-multi-repo-guard.ts):worktree,local_docker,ssh, andspritesexecutor types support sibling repositories;local,local_pc, andremote_dockerdo not.- When the selected executor profile's type supports multi-repo, the picker renders as a repeatable list (0..N rows) with an "Add repository" control. Each row independently picks a registered or discovered repository; a repository already selected in another row is marked and not independently selectable a second time (mirrors the task-creation dialog's "Already added" marker).
- When the selected executor profile's type does not support multi-repo, the picker renders as today's single dropdown (registered/discovered repos, or "Auto").
- The Executor Profile picker disables executor profiles that don't support multi-repo whenever two or more repositories are currently selected, with the same disabled-reason text as the task-creation dialog, so a user cannot silently strand a multi-repository automation on an incompatible executor.
- Automations created via the WS API directly (bypassing the editor) may still combine an incompatible executor with multiple repository IDs; this is a client-side authoring guard, not a backend rejection. Task launch on an incompatible executor fails the same way manual multi-repo task creation would.
execution_mode = task: trigger fires → a normal kanban task is created (current PR #406 behavior). Task is visible on the kanban, commentable, reviewable, and has full lifecycle.execution_mode = run: trigger fires → an ephemeral task is created (is_ephemeral = true,origin = "automation_run") so the existing session pipeline still launches an agent. The kanban hides ephemeral tasks. The AutomationRun row is the surfaced artifact; the linked task is plumbing only.- Run-mode automations auto-start their agent regardless of the workflow step's
auto_start_agentsetting — the user never opens the task to drag it, so the trigger MUST be the start signal. - The sidebar exposes a single top-level Automations entry pointing at
/settings/automations. The per-workspaceAutomationssub-link is removed (PR #406 added it; this spec drops it). /settings/automationsis a client route that branches on the workspace list already loaded into the SPA (from the boot payload / store) — it does not fetch the workspace list on load:- 0 workspaces → empty state with "Create workspace" CTA.
- 1 workspace → redirect to
/settings/workspace/<id>/automations. - 2+ workspaces → workspace picker (grid of cards, click to enter).
- The automations table shows the execution mode as a badge column ("Task" / "Run") so the user can scan which automations clutter the kanban and which don't.
Data model
Builds on PR #406's internal/automation/ schema. execution_mode folded into the canonical CREATE TABLE (no in-branch migration needed). Repository selection moved from a single column to a join table:
automations.execution_mode TEXT NOT NULL DEFAULT 'task' -- 'task' | 'run'
automation_repositories
id string PK
automation_id string FK -> automations.id (ON DELETE CASCADE)
repository_id string FK-by-id to repositories, not enforced at the DB layer
position integer 0-based order, preserved for resolution and UI row order
created_at timestamp
UNIQUE(automation_id, repository_id)
The legacy automations.repository_id TEXT NOT NULL DEFAULT '' column is dropped by the automation_repositories migration. Every pre-existing automation with a non-empty repository_id is backfilled into automation_repositories (position 0) before the column is dropped, so no automation silently loses its configured repository across the upgrade.
CreateAutomation/UpdateAutomation validate that every submitted repository ID belongs to the automation's workspace_id and reject unknown, foreign, or duplicate IDs.
The tasks.is_ephemeral and tasks.origin columns already exist (used by quick-chat). Run-mode automations set both at task-create time. New task origin constant TaskOriginAutomationRun = "automation_run" lives in internal/task/models/models.go.
automation_runs.task_id continues to reference the created task for both modes. Run mode just means that task is hidden.
API surface
PR #406's WS-based API gets execution_mode and repository_ids (an ordered string[], replacing the old singular repository_id) on:
automation.createpayload (input) —repository_ids?: string[]automation.updatepayload (input) —repository_ids?: string[]; a present-but-empty array clears the automation's repositories, an absent field leaves them unchanged (matches the existing task-updaterepositoriesconvention)automation.get/automation.listresponses (output) —repository_ids: string[], ordered byposition
No new endpoints. No HTTP routes change. Sidebar deep-links to /settings/automations (flat).
State machine
Automation lifecycle unchanged. Run-mode and task-mode share the trigger → AutomationRun pipeline. The only branching is in orchestrator/event_handlers_automation.go::handleAutomationTriggered:
trigger fires
→ resolve repository
→ CreateReviewTask(IsEphemeral=mode==run, Origin=automation_run)
→ record AutomationRun (status=task_created, task_id set)
→ associate PR if github_pr trigger
→ if mode==run OR step.auto_start_agent: StartTask
→ for mode==run: agent terminal turn outcome marks AutomationRun succeeded/failed and tears down the execution/worktree
Permissions
Inherits PR #406's model (no per-action authorization gates). The flat /settings/automations page is reachable by anyone with workspace-list access, since it only lists workspaces and links into the per-workspace UI.
Failure modes
| Dependency / invariant | Behavior |
|---|---|
| No workspaces are loaded into the SPA store when the flat page renders | Page renders the empty state (treating "none loaded" as "no workspaces"). The page reads the store and never fetches on load, so there is no per-render fetch that can fail or loop. |
| Run-mode automation's task starts but agent fails | AutomationRun transitions from task_created to failed; the row surfaces the failure instead of remaining "Running". |
| Run-mode automation's agent completes its turn successfully | AutomationRun transitions from task_created to succeeded; the agent execution and ephemeral worktree are torn down. |
| Run-mode automation's turn is cancelled by the user | AutomationRun transitions from task_created to failed with a cancellation error; the hidden session is marked CANCELLED and the agent execution is torn down. |
| User manually drags a run-mode task on the kanban | Cannot happen — ephemeral tasks are hidden from the kanban. The "auto-start" rule fires once at trigger time; no manual recovery path. |
| Existing automation upgraded from pre-execution_mode version | Migration sets execution_mode = 'task' for all existing rows. UI shows them with "Task" badge. |
Existing automation upgraded from before automation_repositories existed |
Its non-empty legacy repository_id is backfilled into automation_repositories at position 0 before the column is dropped; an empty legacy value backfills nothing (unchanged fallback-to-first-repository behavior). |
automation.create/automation.update submits a repository_ids entry outside the automation's workspace, or a duplicate ID |
Request is rejected with a validation error; no partial repository list is persisted. |
| Editor has 2+ repositories selected and the user picks an executor profile whose type doesn't support multi-repo | Editor disables that executor profile in the picker with the same reason text as the task-creation dialog; the WS API itself does not reject the combination if reached directly. |
User edits execution_mode from task to run on an enabled automation |
Next firing uses the new mode. In-flight runs are unaffected. |
Persistence guarantees
automations.execution_mode and tasks.is_ephemeral survive restart. automation_repositories rows survive restart and automation edits (replaced transactionally on update, cascade-deleted with the automation). Run-mode AutomationRuns and their hidden tasks persist normally. The kanban filter on is_ephemeral is applied at query time, not at write time — so re-marking a task non-ephemeral via direct DB update would reveal it.
Scenarios
- GIVEN a user creates an automation with
execution_mode = "task"and a cron trigger, WHEN the cron fires, THEN a normal kanban task appears with the rendered title; the user can click it, drag it, comment on it. - GIVEN a user creates an automation with
execution_mode = "run"and a cron trigger, WHEN the cron fires, THEN an ephemeral task is created (not visible on the kanban), the agent starts automatically, and the AutomationRun row in the automation's history shows the result. - GIVEN a run-mode automation agent finishes a turn with
stop_reason = "end_turn", WHEN the complete event is handled, THEN the AutomationRun row is markedsucceededand the agent execution is stopped instead of waiting for process exit. - GIVEN a user opens
/settings/automationsin an install with one workspace, WHEN the page loads, THEN the browser redirects to/settings/workspace/<id>/automations. - GIVEN a user opens
/settings/automationsin an install with three workspaces, WHEN the page loads, THEN a workspace picker is shown; clicking one navigates to its automations. - GIVEN a user opens
/settings/automationsin a fresh install with zero workspaces, WHEN the page loads, THEN an empty-state card explains "create a workspace first" with a CTA. - GIVEN a user opens
/settings/automationsin a multi-workspace install, WHEN the page loads, THEN it renders the picker from the already-loaded workspace list and issues no additionalGET /api/v1/workspacesrequest on load (guards against the render/refetch loop that a server-styleawait listWorkspaces()in the page body caused after the SPA migration). - GIVEN a user toggles an existing task-mode automation to run mode in the editor, WHEN the next trigger fires, THEN the resulting task is hidden from the kanban; previously-created tasks (from task-mode firings) remain visible.
- GIVEN a run-mode automation triggered by a GitHub PR event, WHEN the trigger fires, THEN the PR is associated with the ephemeral task via
AssociatePRWithTaskexactly as in task mode. - GIVEN a scheduled automation with
repository_idsset to one repo, WHEN the cron fires, THEN the resulting task is pinned to that repo's default branch — regardless of whether the workspace has other repositories. - GIVEN a scheduled automation with
repository_idsset to two or more repos, WHEN the cron fires, THEN the resulting task is created with all of them attached, each pinned to its own default branch, same as a manually created multi-repository task. - GIVEN a scheduled automation with
repository_ids = []in a multi-repo workspace, WHEN the cron fires, THEN the task uses the workspace's first repository (legacy fallback) and a warning is logged. - GIVEN an automation with
repository_idsset and agithub_prtrigger, WHEN a PR event fires, THEN the task uses the PR's own repository, not the configuredrepository_ids— the editor disables the picker for PR triggers with a hint. - GIVEN the editor's selected executor profile type is
worktree,local_docker,ssh, orsprites, WHEN the user opens the repository picker, THEN it renders as a repeatable list and "Add repository" is enabled. - GIVEN the editor's selected executor profile type is
local,local_pc, orremote_docker, WHEN the user opens the repository picker, THEN it renders as a single dropdown and there is no "Add repository" control. - GIVEN the editor has two or more repositories selected, WHEN the user opens the Executor Profile picker, THEN profiles whose type doesn't support multi-repo are disabled with an explanatory reason, matching the task-creation dialog's guard text.
- GIVEN an automation created before
repository_idsexisted with a non-empty legacyrepository_id, WHEN the schema migration runs, THEN the editor shows that repository pre-selected as the sole row after upgrade. - GIVEN a user picks a discovered (not-yet-registered) repository in the editor and clicks Save, WHEN the save flow runs, THEN the discovered repo is registered with the workspace first (
createRepositoryAction), its new id is written onto the automation, and the picker selection is promoted toregisteredso re-saving doesn't duplicate the registration. - GIVEN an upgrade from a pre-execution_mode kandev version, WHEN the user opens the editor for an existing automation, THEN the execution-mode selector defaults to "Task" (preserving previous behavior).
Out of scope
- AutomationRun-as-true-session-owner (instead of ephemeral task). The cleaner model — make
task_sessions.task_idnullable, addtask_sessions.automation_run_id, route run-mode bypassing tasks entirely — was considered and explicitly deferred to a future PR. It touches ~50+ files in the orchestrator + session pipeline + WS layer + frontend state, which is out of scope here. The ephemeral-task path is the pragmatic shim. - Agent-type primary picker. PR #406's editor still picks an
agent_profile_id(a fully configured profile), not a raw agent type (claude/codex/opencode). Switching to agent-type-primary requires plumbing changes in the orchestrator (which expects a profile id). Deferred. - Auto-provisioned default workspace. When no workspaces exist, the flat page shows a CTA; it does not auto-create one. Most installs already have a workspace (workspace setup is part of onboarding), so the CTA is sufficient for now.
- Cross-workspace automation listing on the flat page. Multi-workspace installs see a picker, not a merged list. Merging would require a new list-all endpoint and a workspace column in the table.
- A standalone AutomationRun detail page (showing session output for run-mode firings). Run-mode automations currently link to the linked task's detail page; since the task is hidden from the kanban it's reachable only by direct URL.
- Webhook execution-mode override (e.g. webhook payload setting
execution_modeper call). The execution mode is automation-level, not per-firing.
Open questions
- (none)