@aliou/pi-processes 0.6.3 → 0.6.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CONTRIBUTING.md +123 -0
- package/README.md +86 -104
- package/package.json +7 -2
- package/skills/pi-processes/SKILL.md +39 -0
- package/src/commands/settings/build-sections.ts +1 -1
- package/src/config.ts +3 -3
- package/src/tools/actions/kill.ts +1 -1
- package/src/tools/index.ts +8 -0
package/CONTRIBUTING.md
ADDED
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
# Contributing
|
|
2
|
+
|
|
3
|
+
## Scope
|
|
4
|
+
|
|
5
|
+
`README.md` is for users.
|
|
6
|
+
|
|
7
|
+
Keep development details, testing notes, internal tool guidance, and docs build details in this file.
|
|
8
|
+
|
|
9
|
+
## Development
|
|
10
|
+
|
|
11
|
+
Install dependencies:
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
pnpm install
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
Run checks:
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
pnpm lint
|
|
21
|
+
pnpm typecheck
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
## Repository layout
|
|
25
|
+
|
|
26
|
+
- `src/` - extension source
|
|
27
|
+
- `src/tools/` - `process` tool and actions
|
|
28
|
+
- `src/commands/` - `/ps` commands and settings UI
|
|
29
|
+
- `src/hooks/` - lifecycle hooks, blocker, message rendering, widgets
|
|
30
|
+
- `src/components/` - TUI components
|
|
31
|
+
- `skills/` - shipped package skills
|
|
32
|
+
- `.agents/skills/` - local repo-only skills for development workflows
|
|
33
|
+
- `.github/docs-site/` - isolated docs page build
|
|
34
|
+
|
|
35
|
+
## Internal behavior
|
|
36
|
+
|
|
37
|
+
This extension is mainly for agent-managed background processes.
|
|
38
|
+
|
|
39
|
+
Typical flow:
|
|
40
|
+
|
|
41
|
+
1. Pi starts a long-running command in the background.
|
|
42
|
+
2. Pi continues other work.
|
|
43
|
+
3. The user watches, pins, or kills the process from the UI.
|
|
44
|
+
4. Pi inspects output or logs when needed.
|
|
45
|
+
|
|
46
|
+
Use the `process` tool for long-running commands such as dev servers, test watchers, build watchers, and log tails.
|
|
47
|
+
|
|
48
|
+
Avoid shell background patterns when the process tool fits.
|
|
49
|
+
|
|
50
|
+
Background command blocking is optional. It is controlled by `interception.blockBackgroundCommands`.
|
|
51
|
+
|
|
52
|
+
## Testing
|
|
53
|
+
|
|
54
|
+
Useful local checks:
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
pnpm lint
|
|
58
|
+
pnpm typecheck
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Useful manual process scripts:
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
./test/test-output.sh
|
|
65
|
+
./test/test-exit-success.sh 5
|
|
66
|
+
./test/test-exit-failure.sh 5
|
|
67
|
+
./test/test-exit-crash.sh 5
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
## Docs conventions
|
|
71
|
+
|
|
72
|
+
### README
|
|
73
|
+
|
|
74
|
+
Keep `README.md` focused on user outcomes:
|
|
75
|
+
|
|
76
|
+
- what the extension does
|
|
77
|
+
- how users interact with it
|
|
78
|
+
- slash commands and UI behavior
|
|
79
|
+
- troubleshooting
|
|
80
|
+
|
|
81
|
+
Avoid putting these in `README.md`:
|
|
82
|
+
|
|
83
|
+
- dev commands
|
|
84
|
+
- test commands
|
|
85
|
+
- internal architecture details
|
|
86
|
+
- detailed tool-call schemas
|
|
87
|
+
- release workflow notes
|
|
88
|
+
|
|
89
|
+
### Video placeholders
|
|
90
|
+
|
|
91
|
+
Use HTML comments in `README.md`:
|
|
92
|
+
|
|
93
|
+
```md
|
|
94
|
+
<!-- VIDEO: {"id":"process-panel","title":"Browse and manage processes from the panel"} -->
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
GitHub ignores these comments. The docs page build turns them into video blocks.
|
|
98
|
+
|
|
99
|
+
Add one placeholder for each feature section.
|
|
100
|
+
|
|
101
|
+
## Docs page build
|
|
102
|
+
|
|
103
|
+
The generated docs page lives under `.github/docs-site/` and is isolated from the extension source.
|
|
104
|
+
|
|
105
|
+
It reads `README.md`, converts markdown into structured content, replaces video placeholders, highlights code with Shiki, and builds a static page with Vite and Tailwind.
|
|
106
|
+
|
|
107
|
+
The GitHub Actions workflow for this lives in `.github/workflows/docs-page.yml`.
|
|
108
|
+
|
|
109
|
+
## Demo pattern
|
|
110
|
+
|
|
111
|
+
For demo recording, use a small self-contained project with a realistic workflow.
|
|
112
|
+
|
|
113
|
+
The best pattern used for this extension was a fake Northwind API project where Pi:
|
|
114
|
+
|
|
115
|
+
1. starts a server in the background
|
|
116
|
+
2. runs tests and sees failures
|
|
117
|
+
3. runs migrations
|
|
118
|
+
4. checks server logs
|
|
119
|
+
5. updates seed data
|
|
120
|
+
6. reruns tests
|
|
121
|
+
7. cleans up the process
|
|
122
|
+
|
|
123
|
+
That pattern shows why background processes matter in a normal task instead of showing features one by one.
|
package/README.md
CHANGED
|
@@ -1,155 +1,137 @@
|
|
|
1
|
-
#
|
|
1
|
+
# pi-processes
|
|
2
2
|
|
|
3
|
-
Manage background processes from Pi
|
|
3
|
+
Manage background processes from Pi without blocking the conversation.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
This extension lets Pi keep long-running commands alive while the conversation continues. It is useful for dev servers, test watchers, local APIs, builds, and log tails.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
## Let Pi keep working while processes run
|
|
8
|
+
|
|
9
|
+
When a task needs a long-running command, Pi can start it in the background by itself and keep helping with the rest of the work.
|
|
10
|
+
|
|
11
|
+
That means Pi can, for example:
|
|
12
|
+
|
|
13
|
+
- start a dev server and keep coding
|
|
14
|
+
- keep a test watcher running while it fixes failures
|
|
15
|
+
- run a local API while it inspects logs
|
|
16
|
+
- watch build output without blocking the conversation
|
|
17
|
+
|
|
18
|
+
You can then inspect, pin, or stop those processes from the UI.
|
|
19
|
+
|
|
20
|
+
<!-- VIDEO: {"id":"agent-starts-processes","title":"Pi starts a long-running process and keeps working"} -->
|
|
8
21
|
|
|
9
22
|
## Installation
|
|
10
23
|
|
|
24
|
+
From npm:
|
|
25
|
+
|
|
11
26
|
```bash
|
|
12
27
|
pi install npm:@aliou/pi-processes
|
|
13
28
|
```
|
|
14
29
|
|
|
15
|
-
|
|
30
|
+
From git:
|
|
16
31
|
|
|
17
32
|
```bash
|
|
18
33
|
pi install git:github.com/aliou/pi-processes
|
|
19
34
|
```
|
|
20
35
|
|
|
21
|
-
##
|
|
36
|
+
## Open the process panel
|
|
22
37
|
|
|
23
|
-
|
|
24
|
-
- **Commands**: `/ps` (interactive panel), `/ps:pin` (pin dock to process), `/ps:logs` (open log overlay), `/ps:kill` (kill process), `/ps:clear` (clear finished), `/ps:dock` (control dock visibility), `/ps:settings`
|
|
25
|
-
- **Log Dock**: Unified view for all process logs with color-coded prefixes
|
|
26
|
-
- **Follow Mode**: Automatically shows dock when processes start (enabled by default)
|
|
27
|
-
- **Focus Mode**: Filter to a single process's logs
|
|
28
|
-
- Auto-cleanup on session exit
|
|
29
|
-
- File-based logging (logs written to temp files, not memory)
|
|
30
|
-
- Friendly process names (auto-inferred or custom)
|
|
38
|
+
Use `/ps` to open the main process panel.
|
|
31
39
|
|
|
32
|
-
|
|
40
|
+
From there you can:
|
|
33
41
|
|
|
34
|
-
|
|
42
|
+
- see running and finished processes
|
|
43
|
+
- inspect recent output
|
|
44
|
+
- pin a process to the dock
|
|
45
|
+
- kill a running process
|
|
46
|
+
- clear finished entries
|
|
35
47
|
|
|
36
|
-
|
|
37
|
-
process start "pnpm dev" name="backend-dev"
|
|
38
|
-
process start "pnpm build" name="build" alertOnSuccess=true
|
|
39
|
-
process start "pnpm test" alertOnFailure=true
|
|
40
|
-
process list
|
|
41
|
-
process output id="backend"
|
|
42
|
-
process logs id="proc_1"
|
|
43
|
-
process kill id="backend"
|
|
44
|
-
process clear
|
|
45
|
-
```
|
|
48
|
+
Keys:
|
|
46
49
|
|
|
47
|
-
|
|
48
|
-
- `
|
|
49
|
-
- `
|
|
50
|
-
- `
|
|
50
|
+
- `j/k` or arrow keys: move selection
|
|
51
|
+
- `J/K`: scroll preview
|
|
52
|
+
- `enter`: pin selected process to the dock
|
|
53
|
+
- `x`: kill selected process
|
|
54
|
+
- `c`: clear finished processes
|
|
55
|
+
- `q` or `esc`: close
|
|
51
56
|
|
|
52
|
-
|
|
57
|
+
<!-- VIDEO: {"id":"process-panel","title":"Browse and manage processes from the panel"} -->
|
|
53
58
|
|
|
54
|
-
|
|
59
|
+
## Inspect logs
|
|
55
60
|
|
|
56
|
-
|
|
61
|
+
Use `/ps:logs [id|name]` to open the log overlay for one process.
|
|
57
62
|
|
|
58
|
-
|
|
63
|
+
This is useful when Pi started a server, watcher, or local API and you want to follow what it is doing in more detail.
|
|
59
64
|
|
|
60
|
-
|
|
61
|
-
- `j/k` - select process
|
|
62
|
-
- `J/K` - scroll logs
|
|
63
|
-
- `enter` - focus on selected process
|
|
64
|
-
- `x` - kill selected process
|
|
65
|
-
- `c` - clear finished processes
|
|
66
|
-
- `q` - quit
|
|
65
|
+
Keys:
|
|
67
66
|
|
|
68
|
-
|
|
67
|
+
- `tab` / `shift+tab`: switch process tabs
|
|
68
|
+
- `g/G`: jump to top or bottom
|
|
69
|
+
- `j/k` or arrow keys: scroll
|
|
70
|
+
- `s`: switch between combined, stdout, and stderr
|
|
71
|
+
- `f`: toggle follow mode
|
|
72
|
+
- `/`: search
|
|
73
|
+
- `n/N`: move between search matches
|
|
74
|
+
- `q` or `esc`: close
|
|
69
75
|
|
|
70
|
-
|
|
76
|
+
<!-- VIDEO: {"id":"inspect-logs","title":"Open the log overlay and inspect output"} -->
|
|
71
77
|
|
|
72
|
-
|
|
78
|
+
## Pin one process
|
|
73
79
|
|
|
74
|
-
|
|
80
|
+
Use `/ps:pin [id|name]` to keep the dock focused on one process.
|
|
75
81
|
|
|
76
|
-
|
|
82
|
+
This is useful when one process matters more than the others, such as a dev server or a test watcher.
|
|
77
83
|
|
|
78
|
-
|
|
84
|
+
Without arguments, Pi shows a picker.
|
|
79
85
|
|
|
80
|
-
|
|
86
|
+
<!-- VIDEO: {"id":"pin-process","title":"Pin the dock to one process"} -->
|
|
81
87
|
|
|
82
|
-
|
|
88
|
+
## Control the dock
|
|
83
89
|
|
|
84
|
-
|
|
90
|
+
Use `/ps:dock [show|hide|toggle]` to control dock visibility.
|
|
85
91
|
|
|
86
|
-
|
|
92
|
+
The dock gives you a compact live view without leaving the conversation.
|
|
87
93
|
|
|
88
|
-
|
|
89
|
-
- `show` - Show dock (open)
|
|
90
|
-
- `hide` - Hide dock
|
|
91
|
-
- `toggle` - Cycle dock visibility state
|
|
94
|
+
<!-- VIDEO: {"id":"dock-control","title":"Show, hide, and use the dock"} -->
|
|
92
95
|
|
|
93
|
-
|
|
96
|
+
## Adjust settings
|
|
94
97
|
|
|
95
|
-
|
|
98
|
+
Use `/ps:settings` to configure the extension.
|
|
96
99
|
|
|
97
|
-
|
|
98
|
-
[dev] GET /api/users 200 45ms (cyan)
|
|
99
|
-
[test] Running auth.test.ts... (yellow)
|
|
100
|
-
[dev] POST /api/auth 200 12ms
|
|
101
|
-
[test] ✓ login flow
|
|
102
|
-
...
|
|
103
|
-
```
|
|
100
|
+
Available settings include:
|
|
104
101
|
|
|
105
|
-
|
|
106
|
-
-
|
|
107
|
-
-
|
|
108
|
-
-
|
|
109
|
-
-
|
|
110
|
-
-
|
|
111
|
-
- Follow mode toggle is only available via settings (`/ps:settings`)
|
|
102
|
+
- process list size
|
|
103
|
+
- output limits
|
|
104
|
+
- shell path override
|
|
105
|
+
- dock defaults
|
|
106
|
+
- follow mode behavior
|
|
107
|
+
- optional background command interception
|
|
112
108
|
|
|
113
|
-
|
|
114
|
-
- `collapsed` (1-2 lines): Summary + last log line
|
|
115
|
-
- `open` (8-12 lines): Full interleaved or focused logs
|
|
109
|
+
<!-- VIDEO: {"id":"settings","title":"Adjust process extension settings"} -->
|
|
116
110
|
|
|
117
|
-
|
|
111
|
+
## Platform support
|
|
118
112
|
|
|
119
|
-
|
|
120
|
-
-
|
|
121
|
-
-
|
|
122
|
-
- `/process:logs` → Use `/ps:logs` instead
|
|
123
|
-
- `/process:kill` → Use `/ps:kill` instead
|
|
124
|
-
- `/process:clear` → Use `/ps:clear` instead
|
|
113
|
+
- macOS: supported
|
|
114
|
+
- Linux: supported
|
|
115
|
+
- Windows: not supported
|
|
125
116
|
|
|
126
|
-
##
|
|
117
|
+
## Troubleshooting
|
|
127
118
|
|
|
128
|
-
|
|
119
|
+
### Pi started something and I want to see more output
|
|
129
120
|
|
|
130
|
-
|
|
131
|
-
- **Follow Mode**: Enable by default, auto-hide on finish
|
|
132
|
-
- **Process List**: Max visible processes, max preview lines
|
|
133
|
-
- **Output Limits**: Default tail lines, max output lines
|
|
134
|
-
- **Execution**: Shell path override
|
|
135
|
-
- **Interception**: Block background commands
|
|
121
|
+
Open `/ps` for a quick overview, or use `/ps:logs` for full logs.
|
|
136
122
|
|
|
137
|
-
|
|
123
|
+
### I want one process to stay visible
|
|
138
124
|
|
|
139
|
-
|
|
125
|
+
Use `/ps:pin` to focus the dock on that process.
|
|
140
126
|
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
127
|
+
### I want Pi to avoid shell background tricks
|
|
128
|
+
|
|
129
|
+
Enable background command interception in `/ps:settings`. When enabled, Pi avoids normal shell background patterns and uses the process workflow instead.
|
|
130
|
+
|
|
131
|
+
## Contributing
|
|
132
|
+
|
|
133
|
+
For development, testing, docs generation, and extension internals, see [CONTRIBUTING.md](./CONTRIBUTING.md).
|
|
147
134
|
|
|
148
|
-
##
|
|
135
|
+
## License
|
|
149
136
|
|
|
150
|
-
|
|
151
|
-
- [ ] **Process filtering**: Filter by name/status in full panel
|
|
152
|
-
- [ ] **Log search**: Search within logs (Ctrl+F in dock)
|
|
153
|
-
- [ ] **Copy log path**: Keyboard shortcut to copy log file path
|
|
154
|
-
- [ ] **Open in editor**: Keyboard shortcut to open logs in $EDITOR
|
|
155
|
-
- [ ] **Sound notifications**: Play sound on process completion
|
|
137
|
+
MIT
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@aliou/pi-processes",
|
|
3
|
-
"version": "0.6.
|
|
3
|
+
"version": "0.6.4",
|
|
4
4
|
"license": "MIT",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"private": false,
|
|
@@ -18,6 +18,9 @@
|
|
|
18
18
|
"extensions": [
|
|
19
19
|
"./src/index.ts"
|
|
20
20
|
],
|
|
21
|
+
"skills": [
|
|
22
|
+
"./skills/pi-processes"
|
|
23
|
+
],
|
|
21
24
|
"video": "https://assets.aliou.me/pi-extensions/demos/pi-processes.mp4"
|
|
22
25
|
},
|
|
23
26
|
"publishConfig": {
|
|
@@ -25,7 +28,9 @@
|
|
|
25
28
|
},
|
|
26
29
|
"files": [
|
|
27
30
|
"src",
|
|
28
|
-
"
|
|
31
|
+
"skills",
|
|
32
|
+
"README.md",
|
|
33
|
+
"CONTRIBUTING.md"
|
|
29
34
|
],
|
|
30
35
|
"dependencies": {
|
|
31
36
|
"@aliou/pi-utils-settings": "^0.10.0",
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: pi-processes
|
|
3
|
+
description: Manage long-running commands in the background with the process tool. Use when a task needs a dev server, test watcher, build watcher, local API, or log tail to keep running while the conversation continues.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# pi-processes
|
|
7
|
+
|
|
8
|
+
Use this skill when work needs a long-running command to stay alive while Pi continues with other steps.
|
|
9
|
+
|
|
10
|
+
## Prefer this workflow
|
|
11
|
+
|
|
12
|
+
- Use the `process` tool for long-running commands.
|
|
13
|
+
- Avoid shell background patterns when the process tool fits.
|
|
14
|
+
- Give processes stable, clear names.
|
|
15
|
+
- Continue the task after starting a process instead of waiting on it.
|
|
16
|
+
- Inspect output or log files only when needed.
|
|
17
|
+
- Kill and clear processes when they are no longer useful.
|
|
18
|
+
|
|
19
|
+
## Good fits
|
|
20
|
+
|
|
21
|
+
- `pnpm dev`
|
|
22
|
+
- `npm run server`
|
|
23
|
+
- `pnpm test --watch`
|
|
24
|
+
- `tail -f <logfile>`
|
|
25
|
+
- local preview or build watchers
|
|
26
|
+
|
|
27
|
+
## Typical flow
|
|
28
|
+
|
|
29
|
+
1. Start the long-running command with a clear name.
|
|
30
|
+
2. Continue the main task.
|
|
31
|
+
3. Inspect `output` or `logs` if something needs attention.
|
|
32
|
+
4. Use alert flags when success or failure should trigger a follow-up turn.
|
|
33
|
+
5. Kill and clear the process when done.
|
|
34
|
+
|
|
35
|
+
## Notes
|
|
36
|
+
|
|
37
|
+
- Users can inspect and manage running processes from `/ps`.
|
|
38
|
+
- Use `write` when a process expects stdin input.
|
|
39
|
+
- Use `output` for a quick tail and `logs` when the full log files are more useful.
|
|
@@ -13,7 +13,7 @@ export function buildSettingsSections(
|
|
|
13
13
|
id: "processList.maxVisibleProcesses",
|
|
14
14
|
label: "Max visible processes",
|
|
15
15
|
description:
|
|
16
|
-
"Maximum processes shown in the /
|
|
16
|
+
"Maximum processes shown in the /ps list before scrolling",
|
|
17
17
|
currentValue: String(
|
|
18
18
|
tabConfig?.processList?.maxVisibleProcesses ??
|
|
19
19
|
resolved.processList.maxVisibleProcesses,
|
package/src/config.ts
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Configuration for the processes extension.
|
|
3
3
|
*
|
|
4
|
-
* Global: ~/.pi/agent/extensions/
|
|
5
|
-
* Memory: ephemeral overrides via /
|
|
4
|
+
* Global: ~/.pi/agent/extensions/process.json
|
|
5
|
+
* Memory: ephemeral overrides via /ps:settings
|
|
6
6
|
*/
|
|
7
7
|
|
|
8
8
|
import { ConfigLoader } from "@aliou/pi-utils-settings";
|
|
@@ -11,7 +11,7 @@ import { DEFAULT_KEYBINDINGS } from "./utils/keybindings";
|
|
|
11
11
|
|
|
12
12
|
export interface ProcessesConfig {
|
|
13
13
|
processList?: {
|
|
14
|
-
/** Max visible processes in the /
|
|
14
|
+
/** Max visible processes in the /ps TUI list. */
|
|
15
15
|
maxVisibleProcesses?: number;
|
|
16
16
|
/** Max log preview lines shown below the selected process. */
|
|
17
17
|
maxPreviewLines?: number;
|
|
@@ -53,7 +53,7 @@ export async function executeKill(
|
|
|
53
53
|
if (result.reason === "timeout") {
|
|
54
54
|
const message =
|
|
55
55
|
`SIGTERM timed out for "${proc.name}" (${proc.id}). ` +
|
|
56
|
-
"Run /
|
|
56
|
+
"Run /ps and press x on terminate_timeout to force kill (SIGKILL).";
|
|
57
57
|
return {
|
|
58
58
|
content: [{ type: "text", text: message }],
|
|
59
59
|
details: {
|
package/src/tools/index.ts
CHANGED
|
@@ -88,6 +88,14 @@ export function setupProcessesTools(pi: ExtensionAPI, manager: ProcessManager) {
|
|
|
88
88
|
Important: You DON'T need to poll or wait for processes. Notifications arrive automatically based on your preferences. Start processes and continue with other work - you'll be informed if something requires attention.
|
|
89
89
|
|
|
90
90
|
Note: User always sees process updates in the UI. The notify flags control whether YOU (the agent) get a turn to react (e.g. check results, fix code, restart).`,
|
|
91
|
+
promptSnippet:
|
|
92
|
+
"Manage background processes without blocking the conversation",
|
|
93
|
+
promptGuidelines: [
|
|
94
|
+
"Use this tool for long-running commands such as dev servers, test watchers, build watchers, and log tails instead of bash.",
|
|
95
|
+
"Avoid shell background patterns such as &, nohup, disown, or setsid when the process tool fits.",
|
|
96
|
+
"After starting a process, continue other work instead of waiting for it.",
|
|
97
|
+
"Use the pi-processes skill for examples and best practices when a task depends on background processes.",
|
|
98
|
+
],
|
|
91
99
|
|
|
92
100
|
parameters: ProcessesParams,
|
|
93
101
|
|