Add terminate button for running workflows on tasks page

[tbrandenburg]

Summary

Add a terminate button next to each running workflow entry on the tasks page to allow users to manually stop long-running or stuck jobs.

Background

The recent cron service improvements (#297, #305) added robust timeout monitoring and admin functions like force_terminate_job() for manually terminating workflows. However, there's currently no UI for users to access this functionality.

Requirements

Frontend Changes

• Add a "Terminate" button next to each workflow entry in the tasks page that is currently running
• Button should only be visible when workflow status is "running"
• Button should be styled consistently with existing UI (likely a small red/orange button)
• Show confirmation dialog before termination: "Are you sure you want to terminate this job?"
• Disable button and show loading state during termination request
• Show success/error feedback after termination attempt

Backend Changes

• Add new API endpoint: POST /api/cron/jobs/{workflow_id}/terminate
• Endpoint should call existing force_terminate_job(workflow_id) function
• Return appropriate HTTP status codes:
  • 200: Successfully terminated
  • 404: Workflow not found or not running
  • 500: Internal error during termination
• Include response body with termination result

UX Considerations

• Button should have clear labeling and appropriate icon (stop/X symbol)
• Consider placement - likely in the actions column or as part of status indicator
• Ensure button doesn't accidentally get clicked (confirmation dialog)
• Provide clear feedback about what happened

Acceptance Criteria

• Terminate button appears only for running workflows
• Clicking button shows confirmation dialog
• Confirmed termination calls backend API
• Backend API successfully terminates running jobs
• UI updates to reflect job termination
• Error handling for failed termination attempts
• Consistent styling with existing task page design

Technical Notes

• Backend function force_terminate_job() already exists in cron_service.py
• Frontend likely needs to call existing cron diagnostics API to get current job states
• Consider real-time updates or polling to refresh job status after termination

Priority

Medium - This is a quality-of-life improvement that makes the existing admin functionality accessible to users through the UI.

[github-actions]

Investigation: Add terminate button for running workflows on tasks page

Issue: #306 (#306)
Type: ENHANCEMENT
Investigated: 2026-03-16T12:00:00Z

Assessment

Metric	Value	Reasoning
Priority	MEDIUM	As stated in issue - quality-of-life improvement making existing admin functionality accessible
Complexity	MEDIUM	2 backend files + 2 frontend files, existing patterns to follow, low integration risk
Confidence	HIGH	Clear requirements, force_terminate_job() already exists, well-documented patterns to mirror

---

Problem Statement

Users cannot manually stop long-running or stuck jobs from the UI. The backend already has force_terminate_job() function (added in PR #305), but there's no API endpoint or UI to access this functionality.

---

Analysis

Root Cause / Change Rationale

The cron service improvements (#297, #305) added force_terminate_job() in cron_service.py:436-443 as an admin function. However:

1. No API endpoint exists to expose this function to frontend
2. No UI exists in the tasks page to trigger termination

This is purely an enhancement - no bug to fix. The implementation follows the existing patterns for:

• Backend: task_agent_cancel endpoint pattern (app.py:1127-1134)
• Frontend: cancel button with Modal confirmation (TaskPage.tsx:256-266)

Evidence Chain

ENHANCEMENT: Add UI and API access to existing force_terminate_job()
↓ BECAUSE: Backend function exists but not exposed
Evidence: cron_service.py:436-443 - force_terminate_job(workflow_id: str) -> bool

↓ BECAUSE: No API endpoint exists
Evidence: app.py has no /api/cron/jobs/{workflow_id}/terminate endpoint

↓ BECAUSE: No UI button exists
Evidence: TasksPage.tsx:180-226 - workflow table has no action buttons

Affected Files

File	Lines	Action	Description
packages/pybackend/app.py	54-60	UPDATE	Add force_terminate_job import
packages/pybackend/app.py	NEW	CREATE	Add POST /api/cron/jobs/{workflow_id}/terminate endpoint
packages/frontend/src/hooks/useApi.ts	479-480	UPDATE	Add terminateWorkflow API method
packages/frontend/src/pages/TasksPage.tsx	180-226	UPDATE	Add terminate button to workflow table

Integration Points

• Backend endpoint calls force_terminate_job(workflow_id) from cron_service
• Frontend calls new API endpoint on button click
• Frontend uses existing getWorkspaceWorkflows() to refresh after termination
• Uses existing Modal component for confirmation dialog

Git History

• Introduced: 56a3de9 - 2026-03-16 - "Merge pull request Fix: Improve cron service code quality with thread safety, error handling, and runtime limits (#297) #305" - added force_terminate_job()
• Last modified: 56a3de9 - today
• Imgression: No regression - this is adding UI to existing functionality

---

Implementation Plan

Step 1: Add force_terminate_job import to app.py

File: packages/pybackend/app.py
Lines: 54-60
Action: UPDATE

Current code:

from cron_service import (
    get_cron_job_diagnostics,
    get_cron_job_last_runs,
    refresh_cron_clock,
    start_cron_clock,
    stop_cron_clock,
)

Required change:

from cron_service import (
    force_terminate_job,
    get_cron_job_diagnostics,
    get_cron_job_last_runs,
    refresh_cron_clock,
    start_cron_clock,
    stop_cron_clock,
)

Why: Need to import the existing function to expose it via API

---

Step 2: Add terminate API endpoint

File: packages/pybackend/app.py
Lines: NEW (after existing cron endpoints ~line 624)
Action: CREATE

Required change:

Add new endpoint following the pattern of task_agent_cancel (lines 1127-1134):

@app.post("/api/cron/jobs/{workflow_id}/terminate")
def cron_job_terminate(workflow_id: str):
    """Terminate a running workflow job."""
    try:
        success = force_terminate_job(workflow_id)
        if not success:
            raise HTTPException(
                status_code=status.HTTP_404_NOT_FOUND,
                detail="Workflow not found or not running",
            )
        return {"success": True, "message": "Workflow terminated"}
    except Exception as e:
        logger.exception(f"Error terminating workflow {workflow_id}")
        raise HTTPException(
            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
            detail=str(e),
        )

Why: Exposes the existing force_terminate_job function via REST API

---

Step 3: Add terminateWorkflow API method

File: packages/frontend/src/hooks/useApi.ts
Lines: 479-480 (after getWorkspaceWorkflows)
Action: UPDATE

Current code:

// Line 479-480
getWorkspaceWorkflows: () =>
    request<{ workflows: WorkspaceWorkflowSummary[] }>("/workspace/workflows"),

Required change:

getWorkspaceWorkflows: () =>
    request<{ workflows: WorkspaceWorkflowSummary[] }>("/workspace/workflows"),
terminateWorkflow: (workflowId: string) =>
    request<{ success: boolean; message?: string }>(
        `/cron/jobs/${encodeURIComponent(workflowId)}/terminate`,
        { method: "POST" },
    ),

Why: Frontend needs API method to call the new backend endpoint

---

Step 4: Add terminate button to TasksPage

File: packages/frontend/src/pages/TasksPage.tsx
Lines: 180-226 (table body)
Action: UPDATE

Current code:

// Lines 215-220 - inside tbody, after Diagnostics column
<td>{formatWorkflowLastRun(workflow)}</td>
<td>
  {renderWorkflowDiagnosticsSummary(
    workflow.diagnostics,
  )}
</td>
</tr>

Required change:

<td>{formatWorkflowLastRun(workflow)}</td>
<td>
  {renderWorkflowDiagnosticsSummary(
    workflow.diagnostics,
  )}
</td>
<td>
  {workflow.diagnostics?.running && (
    <button
      className="danger small"
      onClick={() => handleTerminateClick(workflow)}
      disabled={terminatingWorkflow === `${workflow.repository}:${workflow.id}`}
    >
      {terminatingWorkflow === `${workflow.repository}:${workflow.id}`
        ? "Terminating..."
        : "Terminate"}
    </button>
  )}
</td>
</tr>

Why: Adds terminate button that only appears for running workflows

---

Step 5: Add terminate state and handler

File: packages/frontend/src/pages/TasksPage.tsx
Lines: Add after state declarations (~line 45)
Action: UPDATE

Current code (around line 45):

const [createOpen, setCreateOpen] = useState(false);

Required change:

const [createOpen, setCreateOpen] = useState(false);
const [terminatingWorkflow, setTerminatingWorkflow] = useState<string | null>(null);
const [terminateConfirmOpen, setTerminateConfirmOpen] = useState(false);
const [workflowToTerminate, setWorkflowToTerminate] = useState<WorkspaceWorkflowSummary | null>(null);

---

Step 6: Add terminate handler function

File: packages/frontend/src/pages/TasksPage.tsx
Lines: Add after other handlers (~line 165)
Action: UPDATE

Add these functions:

const handleTerminateClick = (workflow: WorkspaceWorkflowSummary) => {
  setWorkflowToTerminate(workflow);
  setTerminateConfirmOpen(true);
};

const handleTerminateConfirm = async () => {
  if (!workflowToTerminate) return;
  
  const workflowId = `${workflowToTerminate.repository}:${workflowToTerminate.id}`;
  setTerminatingWorkflow(workflowId);
  setTerminateConfirmOpen(false);
  
  try {
    await api.terminateWorkflow(workflowId);
    await refreshWorkspaceWorkflows();
  } catch (error) {
    console.error("Failed to terminate workflow", error);
    alert(`Failed to terminate workflow: ${error instanceof Error ? error.message : "Unknown error"}`);
  } finally {
    setTerminatingWorkflow(null);
    setWorkflowToTerminate(null);
  }
};

---

Step 7: Add confirmation modal

File: packages/frontend/src/pages/TasksPage.tsx
Lines: Add after Panel component (~line 227)
Action: UPDATE

Add before closing Panel:

<TerminateConfirmModal
  open={terminateConfirmOpen}
  workflowName={workflowToTerminate?.name || ""}
  onCancel={() => {
    setTerminateConfirmOpen(false);
    setWorkflowToTerminate(null);
  }}
  onConfirm={handleTerminateConfirm}
/>

Note: You'll need to create a simple inline modal or import a reusable one. The Modal component is already imported at line 10.

---

Step 8: Create TerminateConfirmModal component

File: packages/frontend/src/components/TerminateConfirmModal.tsx
Lines: NEW
Action: CREATE

New file content:

import React from "react";
import { Modal } from "./Modal";

interface TerminateConfirmModalProps {
  open: boolean;
  workflowName: string;
  onCancel: () => void;
  onConfirm: () => void;
}

export const TerminateConfirmModal: React.FC<TerminateConfirmModalProps> = ({
  open,
  workflowName,
  onCancel,
  onConfirm,
}) => {
  return (
    <Modal open={open} title="Terminate Workflow" onClose={onCancel}>
      <p>Are you sure you want to terminate this job?</p>
      <p className="muted">Workflow: {workflowName}</p>
      <div className="modal-actions">
        <button className="secondary" onClick={onCancel}>
          Cancel
        </button>
        <button className="danger" onClick={onConfirm}>
          Terminate
        </button>
      </div>
    </Modal>
  );
};

---

Step 9: Import TerminateConfirmModal

File: packages/frontend/src/pages/TasksPage.tsx
Lines: 10 (after Modal import)
Action: UPDATE

Current code:

import { Modal } from "../components/Modal";

Required change:

import { Modal } from "../components/Modal";
import { TerminateConfirmModal } from "../components/TerminateConfirmModal";

---

Step 10: Update table header

File: packages/frontend/src/pages/TasksPage.tsx
Lines: 182-189
Action: UPDATE

Current code:

<th>Enabled</th>
<th>Schedule</th>
<th>Name</th>
<th>Repository</th>
<th>Last run</th>
<th>Diagnostics</th>

Required change:

<th>Enabled</th>
<th>Schedule</th>
<th>Name</th>
<th>Repository</th>
<th>Last run</th>
<th>Diagnostics</th>
<th>Actions</th>

---

Patterns to Follow

Backend POST endpoint pattern (app.py:1127-1134)

@app.post("/api/tasks/{name}/agent/cancel")
def task_agent_cancel(name: str):
    if not cancel_agent_message(f"task:{name}"):
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="No active agent process to cancel",
        )
    return {"success": True}

Frontend cancel handler pattern (TaskPage.tsx:256-266)

const handleCancel = async () => {
  if (!name) return;
  try {
    await api.cancelTaskAgent(name);
  } catch (error) {
    console.error("Failed to cancel agent request", error);
    setAgentStatus("Unable to cancel the agent request.");
  } finally {
    await refreshAgentStatus();
  }
};

Modal confirmation pattern (ClearSessionModal.tsx:1-33)

<Modal open={open} title="Clear session" onClose={onCancel}>
  <p>Do you also want to clear the chat history for this session?</p>
  <div className="modal-actions">
    <button className="secondary" onClick={onCancel}>
      Cancel
    </button>
    <button className="danger" onClick={onConfirm}>
      Yes
    </button>
  </div>
</Modal>

---

Edge Cases & Risks

Risk/Edge Case	Mitigation
Workflow completes before click	Check running status, show error if already terminated
Network failure during request	Frontend catches error and displays alert, state resets in finally block
Double-click on terminate	Button disabled during request via terminatingWorkflow state
Workflow ID format mismatch	Use exact format: {repository}:{workflow_id} as used in cron_service
Permission issues	Return 401/403 from backend if needed (not required per issue)

---

Validation

Automated Checks

# Backend type check
cd packages/pybackend && uv run mypy app.py

# Backend tests
cd packages/pybackend && uv run python -m pytest tests/unit -v -k "cron"

# Frontend type check
cd packages/frontend && npm run type-check

# Frontend tests
cd packages/frontend && npm run test -- --run TasksPage

Manual Verification

1. Start both servers: make run
2. Navigate to Tasks page
3. Verify running workflows show terminate button
4. Click terminate and confirm dialog appears
5. Confirm termination - workflow should stop
6. Verify button disabled during termination request
7. Verify error handling works for non-running workflows

---

Scope Boundaries

IN SCOPE:

• Add terminate button to tasks page for running workflows
• Add backend API endpoint to call force_terminate_job()
• Add confirmation dialog
• Handle success/error feedback

OUT OF SCOPE (do not touch):

• Real-time updates or polling (mentioned in issue as consideration, not required)
• Any changes to force_terminate_job() function itself
• Permission/authorization changes (issue doesn't require)
• Other workflow actions (pause, resume, etc.)

---

Metadata

• Investigated by: GHAR
• Timestamp: 2026-03-16T12:00:00Z
• Artifact: .ghar/issues/issue-306.md

[tbrandenburg]

🔍 Investigation: Add terminate button for running workflows on tasks page

Type: ENHANCEMENT

Assessment

Metric	Value	Reasoning
Priority	MEDIUM	Issue explicitly states "Medium - quality-of-life improvement that makes existing admin functionality accessible to users through the UI"
Complexity	MEDIUM	Found 3 files to modify (backend API, frontend API hook, frontend UI), follows existing patterns for cancel buttons, requires coordination between backend and frontend
Confidence	HIGH	force_terminate_job() function already exists and is tested at cron_service.py:436, found clear UI patterns to mirror, API endpoint patterns are well-established, workflow ID format is consistent throughout codebase

---

Problem Statement

Users cannot manually stop long-running or stuck workflows from the UI. The backend already has force_terminate_job() function (added in recent cron improvements #297), but there's no API endpoint or UI button to access this functionality.

---

Root Cause Analysis

ENHANCEMENT: Add UI and API access to existing force_terminate_job()
↓ BECAUSE: Backend function exists but not exposed
Evidence: cron_service.py:436-443 - force_terminate_job(workflow_id: str) -> bool

↓ BECAUSE: No API endpoint exists
Evidence: app.py has cancel endpoints for tasks/repos but none for workflows

↓ BECAUSE: No UI button exists
Evidence: TasksPage.tsx:180-226 - workflow table has no action buttons, only displays diagnostics

↓ SOLUTION: Add API endpoint + UI button following existing patterns
Evidence: Three similar cancel endpoints exist (app.py:435, 871, 1127) + danger button patterns throughout UI

---

Implementation Plan

Step	File	Change
1	packages/pybackend/app.py	Add force_terminate_job import
2	packages/pybackend/app.py	Add POST /api/workflows/{workflow_id}/terminate endpoint
3	packages/frontend/src/hooks/useApi.ts	Add terminateWorkflow() API method
4	packages/frontend/src/pages/TasksPage.tsx	Add terminate button with confirmation modal

📋 Detailed Implementation Steps

Backend Changes

1. Add API endpoint (app.py after line 630):

@app.post("/api/workflows/{workflow_id}/terminate")
def terminate_workflow(workflow_id: str):
    """Terminate a running workflow job."""
    try:
        success = force_terminate_job(workflow_id)
        if not success:
            raise HTTPException(
                status_code=status.HTTP_404_NOT_FOUND,
                detail="No active workflow process to terminate",
            )
        return {"success": True, "message": "Workflow terminated successfully"}
    except Exception as e:
        logger.exception(f"Error terminating workflow {workflow_id}")
        raise HTTPException(
            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
            detail=f"Failed to terminate workflow: {str(e)}",
        )

2. Add import (app.py lines 54-60):

from cron_service import (
    force_terminate_job,  # <-- ADD THIS
    get_cron_job_diagnostics,
    get_cron_job_last_runs,
    refresh_cron_clock,
    start_cron_clock,
    stop_cron_clock,
)

Frontend Changes

3. Add API method (useApi.ts after line 480):

terminateWorkflow: (workflowId: string) =>
    request<{ success: boolean; message?: string }>(`/workflows/${encodeURIComponent(workflowId)}/terminate`, {
        method: "POST",
    }),

4. Add UI button (TasksPage.tsx):

• Add state for termination tracking and confirmation modal
• Add terminate button in Actions column (only visible for running workflows)
• Add confirmation dialog: "Are you sure you want to terminate this job?"
• Handle loading states and error feedback

Key Features

• Button only appears when workflow.diagnostics.running === true
• Shows "Terminating..." during request
• Confirmation modal prevents accidental clicks
• Refreshes workflow list after termination
• Proper error handling with user feedback

---

Validation

# Backend validation
cd packages/pybackend && uv run mypy app.py
cd packages/pybackend && uv run python -m pytest tests/unit/test_cron_service.py::test_force_terminate_job -v

# Frontend validation  
cd packages/frontend && npm run type-check
cd packages/frontend && npm run test -- TasksPage --run

Manual Testing

1. Navigate to Tasks page
2. Verify terminate button appears only for running workflows
3. Click terminate and verify confirmation dialog
4. Confirm termination and verify workflow stops
5. Test error handling for edge cases

---

Patterns Followed

• API Endpoint: Mirrors existing cancel endpoints (app.py:435, 871, 1127)
• UI Button: Follows danger button pattern from TaskPage.tsx:490
• Confirmation: Uses existing Modal component with proper actions layout
• Error Handling: Consistent with other async operations in TasksPage

---

Next Step

Run /prp-issue-fix 306 to execute the implementation plan.

---

Investigated by Claude • 2026-03-16T12:45:00Z
Artifact: .claude/PRPs/issues/issue-306.md