Skip to content

feat(plugins): Process Pack — OS-process introspection (list + info) - #29

Merged
rrader26 merged 1 commit into
mainfrom
feat/process-introspection
May 12, 2026
Merged

feat(plugins): Process Pack — OS-process introspection (list + info)#29
rrader26 merged 1 commit into
mainfrom
feat/process-introspection

Conversation

@rrader26

Copy link
Copy Markdown
Contributor

Summary

  • New `createProcessPlugin()` adds 2 read-only OS-process tools.
  • Cross-platform pure-Node (shells out to `ps` / PowerShell `Get-Process`).
  • Read-only in v0; kill / signal sending ships in a follow-up with explicit gating.

Tools

Tool Use
`agentmark_process_list` List all running processes; optional name_filter + sort (cpu / memory / name / pid)
`agentmark_process_info` Per-PID detail: ppid, vsz_kb, memory_kb, state, command line

Why

Read-only OS observability for the agent. Use cases:

  • "Is my bridge still alive?" → `process_list` with name_filter
  • "What's eating CPU on this box?" → `process_list` sorted by cpu, top 10
  • "What spawned this orphan process?" → `process_info` with the PID → look at ppid
  • "Why isn't Excel responding?" → `process_info`, check state column

This is also a precursor to the planned Frida-style "enterprise introspection" tier — that work needs a baseline OS-level observability surface to anchor against.

What's NOT in v0

  • process_kill — too easy to misuse. Lands in a follow-up with `allow_kill: true` plugin gate + signal whitelist.
  • process_open_files (lsof) — `lsof` isn't installed everywhere; need to either declare it required or implement on platforms with native APIs.
  • process_network (netstat / ss) — same issue.

Test plan

  • `pnpm build` clean
  • `pnpm test` — 354 pass / 10 skip (12 new tests against live `ps`, no mocks)
  • Manual on Windows VM: `agentmark_process_list { name_filter: "node" }` returns the agentmark MCP server itself

🤖 Generated with Claude Code

@rrader26
rrader26 force-pushed the feat/process-introspection branch 2 times, most recently from c1c3be9 to 32f6126 Compare May 12, 2026 12:35
Cross-platform process listing + per-PID detail for agents that need
OS-level observability ("why isn't this app responding?", "is my
bridge still alive?", "what's eating CPU?"). Read-only in v0; kill
ships separately with explicit gating.

Tools shipped (2):
  agentmark_process_list   list with optional name filter + sort
  agentmark_process_info   detail for one PID

Cross-platform via OS-native tools (no Node deps):
  macOS / Linux: `ps -A -o pid,pcpu,pmem,user,etime,rss,comm`
  Windows:       PowerShell Get-Process + Win32_Process WMI for cmdline

Normalised shape regardless of platform: pid, name, user, cpu_percent,
memory_kb, command, elapsed, ppid, vsz_kb, state. Sort by cpu /
memory / name / pid. Substring filter on process name.

Tests (12 new, 354 total): live `ps` calls assert current Node process
appears in list, info resolves for own PID, unknown PID returns
found=false, sort orders are honoured, name_filter matches
case-insensitively. No mocks — real OS calls.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@rrader26
rrader26 force-pushed the feat/process-introspection branch from 32f6126 to 4f79757 Compare May 12, 2026 12:43
@rrader26
rrader26 merged commit 6338197 into main May 12, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants