a0-stop-process

KO | EN

gitlite — search

#javascript #hacktoberfest #ai #llm #go #android #rust #linux #docker #cli #kubernetes #vue #security #open-source

a0-stop-process

(★ 23)

Stop Process plugin for Agent Zero — adds a Stop button to cancel the running agent process

a0-stop-process Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Stop Process Plugin for Agent Zero

Adds a **Stop** button to the chat input actions bar (next to Pause Agent and Nudge) that cancels the currently running agent process in the active session and returns the agent to idle state.

## Why this plugin exists

Agent Zero has **Pause** and **Nudge** but no way to simply **cancel a wrong command and go idle**:

| Action | What it does | Agent state after |
|--------|-------------|-------------------|
| **Pause Agent** | Suspends the agent at the next checkpoint | Paused (resumes on Resume) |
| **Nudge** | Kills the current process and starts a new task with a nudge prompt | Running (new task) |
| **Stop (this plugin)** | Kills the current process and goes idle | **Idle (waiting for input)** |

The Stop button fills the gap: it fully terminates a wrong or unwanted command without pausing indefinitely or nudging (which re engages the agent).

## Features

- **Stop button** always visible in the bottom chat actions bar
- **Gray/disabled** when idle, **red/active** when a process is running
- Immediately **terminates** the running agent task
- Shows **"⛔ Process stopped by user."** warning message in the chat log
- **Instant UI reset**: input box returns to idle/waiting state immediately (no polling delay)
- **Ghost process prevention**: kills orphaned child OS processes (pager, less, etc.) spawned by terminal sessions
- **Context isolation**: only affects the active chat; other chats are never touched
- Toast notification confirming the action

## Installation

1. Copy the `stop_process` folder to `/a0/usr/plugins/`
2. Enable the plugin in **Settings** → **Plugins**
3. Refresh the page

Or install from the Plugin Hub in Agent Zero.

## How It Works

### Architecture Overview

The plugin consists of two parts: a **frontend UI component** injected into the chat input actions bar and a **backend API handler** that performs the actual process termination.

```
User clicks Stop button
        │
        ▼
┌─────────────────────────────────┐
│  Frontend (stop-button.html)    │
│  Sends POST to backend API      │
│  with current chat context ID   │
└──────────────┬──────────────────┘
               │
               ▼
┌─────────────────────────────────┐
│  Backend (stop_process.py)      │
│  1. Resolve context via         │
│     self.use_context(ctxid)     │
│  2. Kill terminal child procs   │
│  3. context.kill_process()      │
│  4. context.paused = False      │
│  5. Log warning to chat         │
└──────────────┬──────────────────┘
               │
               ▼
┌─────────────────────────────────┐
│  Frontend receives response     │
│  Sets running = false on store  │
│  Input box resets to idle       │
│  Toast notification shown       │
└─────────────────────────────────┘
```

### Frontend: stop-button.html

The HTML extension is injected into the `chat-input-bottom-actions-end` extension point, placing it alongside the existing Pause and Nudge buttons.

**Visual states:**
- When the agent is **idle**: button is grayed out (40% opacity, `not-allowed` cursor, disabled)
- When the agent is **running**: button turns **red** (#e74c3c), 80% opacity, clickable

**Reactive bindings** use Alpine.js:
- `:disabled="!$store.chats?.selectedContext?.running"` prevents clicking when idle
- `:class="{ 'stop-active': $store.chats?.selectedContext?.running }"` toggles visual state

**Immediate UI reset** after a successful stop:
- Imports `chatsStore` from the sidebar chats store
- Sets `chatsStore.selectedContext.running = false` directly (reactive, propagates instantly)
- Also triggers `globalThis.poll()` after 300ms as a safety fallback

### Backend: stop_process.py (API Handler)

The API handler follows the same pattern as the built in Pause and Nudge handlers:

```python
context = self.use_context(ctxid)   # Resolve context with proper thread locking
await self._interrupt_terminal_sessions(context)  # Kill ghost processes
context.kill_process()               # Cancel the DeferredTask
context.paused = False               # Ensure clean idle state
context.log.log(type="warning", content="⛔ Process stopped by user.")
```

**Key detail**: uses `self.use_context(ctxid)` (NOT `AgentContext.use()`) to ensure proper thread locking and context resolution, consistent with the Pause and Nudge handlers.

### Ghost Process Prevention

#### The Problem

When `context.kill_process()` is called, it cancels the Python `DeferredTask` (the asyncio Future). However, it does **not** terminate child OS processes spawned by `code_execution_tool` terminal sessions.

For example, if the agent runs `git log` in a terminal session, the shell spawns a `pager` process. When the DeferredTask is cancelled, the `pager` process becomes an orphan and keeps running at full CPU:

```
PID   COMMAND   CPU
18624 pager     90.9%   ← orphaned, consuming CPU after Stop
18716 pager     90.9%   ← orphaned, consuming CPU after Stop
```

#### The Solution

Before calling `context.kill_process()`, the handler runs `_interrupt_terminal_sessions()` which:

1. **Accesses the terminal state** via `agent.get_data("_cet_state")` to get all active shell sessions
2. **For each shell session**, gets the `TTYSession._proc.pid` (the shell's PID)
3. **Scans `/proc`** to find all child processes of that shell PID
4. **Recursively kills** the entire process tree (children of children first, then children) using `SIGKILL`
5. **Sends `Ctrl+C`** (`\x03`) to the shell itself to interrupt any running command

```
Shell (bash) PID 1234
├── git log PID 1235      ← killed by _kill_process_tree()
│   └── pager PID 1236    ← killed by _kill_process_tree()
└── (shell survives for future commands)
```

### Context Isolation

The Stop button **only affects the active chat**. This is guaranteed by the architecture:

| Layer | Scope |
|-------|-------|
| **Frontend** | Sends only the current chat's context ID via `globalThis.getContext()` |
| **Backend** | `self.use_context(ctxid)` retrieves only that specific `AgentContext` |
| **Task kill** | `context.kill_process()` kills only that context's `DeferredTask` |
| **Terminal cleanup** | `agent.get_data("_cet_state")` returns only that agent's terminal sessions |
| **Process tree kill** | Starts from shell PIDs of that agent only; other chats' PIDs are never reached |

Each chat has its own `AgentContext` (unique ID), its own `Agent` instance (`agent0`), its own terminal sessions, and its own `DeferredTask`. Clicking Stop in Chat A will **never** affect processes running in Chat B.

## File Structure

```
stop_process/
├── plugin.yaml                 # Plugin manifest
├── README.md                   # This file
├── LICENSE                     # MIT License
├── api/
│   ├── __init__.py             # Python module marker
│   └── stop_process.py         # Backend API handler
└── extensions/
    └── webui/
        └── chat-input-bottom-actions-end/
            └── stop-button.html  # Frontend UI component
```

## Requirements

Agent Zero v1.1+

## License

MIT

a0-stop-process

a0-stop-process Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

a0-stop-process

a0-stop-process Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README