openclaw - 💡(How to fix) Fix [Feature]: Expose bash session registry primitives via plugin-sdk

Summary

Add a plugin-sdk subpath that exposes read-only access to the in-memory bash-process-registry plus a single killBashSession(id) helper, so plugin authors can build external observability and recovery surfaces around backgrounded shell sessions.

Problem to solve

The process tool in src/agents/bash-tools.process.ts is the only consumer of bash-process-registry. It runs inside the agent loop via pi-tools.ts, so backgrounded shell sessions are reachable to the LLM but not to any external observer of an OpenClaw instance.

Today, anyone deploying OpenClaw as a long-lived hosting environment (bot platforms, IDE sidecars, automation runners, on-call dashboards) has no way to answer two operationally critical questions without paying for an LLM round trip and altering the agent's view of its own buffers:

1. What shells are currently running inside this OpenClaw process?
2. How do I kill a runaway shell when the agent itself is stuck or recovering?

pi-tools.ts:553 constructs processTool with a scopeKey tied to the agent session, and createOpenClawTools (the factory used by /tools/invoke and MCP loopback) deliberately omits it. That architectural separation is sensible — the process tool's interactive write actions (write, send-keys, paste, submit) are stdin injection and absolutely should not be reachable from external HTTP. But the read and lifecycle slice (list, log, kill) is genuinely useful externally, and currently inaccessible.

bash-process-registry.ts has the data, but its functions aren't in package.json's exports map. Node ESM blocks deep imports of unlisted subpaths, so plugins cannot reach the registry to build their own narrowly-scoped surface. The CONTRIBUTING.md guidance to prefer plugins over core changes can't be followed here.

Proposed solution

Mirror the existing loadCronStore idiom. New subpath openclaw/plugin-sdk/bash-sessions exposing:

• loadBashSessions(): { running: ReadonlyArray<BashSessionSnapshot>; finished: ReadonlyArray<FinishedBashSessionSnapshot> } — returns immutable snapshot DTOs (id, pid, command, cwd, startedAt, status, tail string copy, truncated). Does not leak internal references like the ChildProcess handle, stdin writable, or raw mutable buffers.
• killBashSession(id: string): BashSessionKillResult — wraps the cancel ceremony that bash-tools.process.ts:539 already implements (supervisor.cancel → killProcessTree fallback → markExited), so plugin authors don't reinvent and subtly break the ordering.

Intentionally not exported: addSession, appendOutput, drainSession, markExited, deleteSession, setJobTtlMs. Each bypasses the supervisor or corrupts the agent's buffer view.

Alternatives considered

1. Add processTool to createOpenClawTools so it lands in /tools/invoke directly. Larger surface change, raises scope/security design calls the SDK approach avoids, and conflicts with CONTRIBUTING.md's "most features should be plugins."
2. Scrape OpenClaw's stdout/stderr for backgrounded-session log markers. Brittle, depends on log format stability, race conditions on lifecycle, no kill capability.
3. Walk /proc for OpenClaw's child PIDs. Gives processes and commands but no correlation back to session IDs, and yields no clean kill primitive (raw SIGTERM by PID leaves the registry in a phantom state).
4. Tap the LLM proxy stream for tool_result text emitted by the exec tool to extract (sessionId, pid) pairs. Workable but couples plugin authors to a specific text format and only sees sessions the agent has been told about.

The SDK export is the smallest mechanical change that unblocks all of the above patterns cleanly.

Impact

• Affected users / systems: Anyone building external operator-facing tooling around OpenClaw — bot hosting platforms, agent-as-a-service deployments, IDE integrations with sidecar OpenClaw processes, monitoring/SRE pipelines.
• Severity: Workflow-blocking for operators on agent stuck/runaway shells; otherwise observability-blocking.
• Frequency: Continuous for any deployment that hosts long-running agents.
• Practical consequences today: Operators either ship without visibility, write fragile stdout scrapers, or fork OpenClaw to expose the registry — none of which serve the project or its users.

Rough delta

~110 lines across src/plugin-sdk/bash-sessions.ts (new — DTO snapshot mapping + re-exports), package.json (exports field), src/agents/bash-process-registry.ts (extract and export the killBashSession helper from the existing process.kill action), plus tests covering snapshot immutability, live registry state, and that killBashSession follows the same supervisor ceremony as process.kill. No public API removals, no behavioral changes to existing surfaces.