#16244: feat(gateway): add session files API and external skill management

Summary Describe the problem and fix in 2–5 bullets: - Problem: Gateway lacked a way to list files touched during a session, and had no first-class API to import/uninstall managed external skills. - Why it matters: Operators had poor observability for agent-produced artifacts and had to do manual file/skill management outside gateway RPC. - What changed: Added `sessions.files.list`, `skills.import`, and `skills.uninstall` gateway methods; added transcript-based file indexing; added managed skill import/uninstall flow; extracted shared package/security utilities and reused them in skill install. - What changed: Extended protocol schemas/method registry/authorization paths for the new methods; added `chat.abort.cascadeSubagents` support and returned stopped subagent session keys. - What did NOT change (scope boundary): No UI changes, no channel routing behavior changes, and no breaking config migration. Change Type (select all) - [ ] Bug fix - [x] Feature - [x] Refactor - [ ] Docs - [x] Security hardening - [ ] Chore/infra Scope (select all touched areas) - [x] Gateway / orchestration - [x] Skills / tool execution - [ ] Auth / tokens - [x] Memory / storage - [ ] Integrations - [x] API / contracts - [ ] UI / DX - [ ] CI/CD / infra Linked Issue/PR - Closes # .None - Related # .None User-visible / Behavior Changes - New RPC method: `sessions.files.list` to enumerate files inferred from session transcript tool calls. - New RPC methods: `skills.import` and `skills.uninstall` for managed external skill lifecycle. - `chat.abort` now accepts optional `cascadeSubagents` and may return `stoppedSubagents` and `stoppedSubagentSessionKeys`. - `sessions.list` rows now include optional `spawnedBy`. - Defaults: - `sessions.files.list.scope` defaults to `created` - `sessions.files.list.includeMissing` defaults to `false` - `sessions.files.list.limit` defaults to `500` Security Impact (required) - New permissions/capabilities? **Yes** - Secrets/tokens handling changed? **No** - New/changed network calls? **Yes** - Command/tool execution surface changed? **Yes** - Data access scope changed? **Yes** If any Yes, explain risk + mitigation: - Risk: Remote skill import introduces network fetch + archive extraction path. - Mitigation: Parameter validation, extension checks, bounded timeout, security scan (critical findings block install by default), and shared archive utility with traversal/link safeguards. - Risk: New gateway methods increase callable surface. - Mitigation: Methods are schema-validated and subject to existing gateway scope checks (`operator.read`/`operator.admin` paths). - Risk: Session file listing reads transcript content and filesystem metadata. - Mitigation: Read-only indexing behavior with bounded result size and optional missing-file filtering. Repro + Verification Environment - OS: macOS (local dev) - Runtime/container: local Node + pnpm - Model/provider: N/A (gateway/server method + utility tests) - Integration/channel (if any): Gateway RPC - Relevant config (redacted): default local config; no secret changes Steps 1. `sessions.files.list` on a session transcript containing tool calls (`exec`, `apply_patch`, `write`). 2. `skills.import` with valid local archive and with remote package mode. 3. `skills.uninstall` on an installed managed skill. Expected - Session files API returns inferred file entries with action/kind/existence metadata. - Skills import installs valid packages and blocks critical-scan packages unless explicitly bypassed. - Skills uninstall removes managed skill directory and refreshes snapshot version. Actual - Behavior matches expected in added automated tests and targeted local verification. Evidence Attach at least one: - [x] Failing test/log before + passing after - [ ] Trace/log snippets - [ ] Screenshot/recording - [ ] Perf numbers (if relevant) Evidence snippet: - `pnpm test src/gateway/server-methods/skills.import-uninstall.test.ts` - Result: `4 passed (4)` in `src/gateway/server-methods/skills.import-uninstall.test.ts` Human Verification (required) What you personally verified (not just CI), and how: - Verified scenarios: - Ran local gateway handler tests for import/uninstall validation forwarding + param rejection. - Edge cases checked: - Confirmed test coverage includes invalid params and success/failure response wiring for import/uninstall handlers. - What you did not verify: - Full live remote registry import in production network conditions. - End-to-end verification on every channel/integration path. Compatibility / Migration - Backward compatible? **Yes** - Config/env changes? **No** - Migration needed? **No** - If yes, exact upgrade steps: `.None` Failure Recovery (if this breaks) - How to disable/revert this change quickly: - Revert this PR commit(s) on `main`. - As immediate mitigation, stop calling new methods (`sessions.files.list`, `skills.import`, `skills.uninstall`) from clients. - Files/config to restore: - Gateway method registration and protocol schema entries added by this PR. - Known bad symptoms reviewers should watch for: - False positives/negatives in file inference from transcript tool-call parsing. - Unexpected import failures from stricter archive/scan safeguards. Risks and Mitigations - Risk: Transcript parsing may misclassify some shell edge cases. - Mitigation: Scope/action heuristics, path normalization, and dedicated tests for tool-call extraction cases. - Risk: Imported archives may contain unsafe structures. - Mitigation: Shared archive extraction safety checks and security scan gate before install. - Risk: Admin APIs can be abused if called by over-privileged clients. - Mitigation: Existing gateway scope checks and strict request schema validation remain in place. <!-- greptile_comment --> <h3>Greptile Summary</h3> This PR adds three major features to the gateway: session file listing, managed skill import/uninstall, and enhanced chat abort control. The implementation is comprehensive with proper security hardening and test coverage. **Key Changes:** - Added `sessions.files.list` RPC method that parses session transcripts to infer files touched by tool calls (`exec`, `write`, `apply_patch`, etc.), with optional workspace mtime scanning - Added `skills.import` and `skills.uninstall` RPC methods for managed external skill lifecycle, supporting both local archives and remote registry downloads - Enhanced `chat.abort` with optional `cascadeSubagents` parameter to stop child agent sessions - Extracted shared archive extraction utilities (`src/infra/archive.ts`) with traversal prevention, symlink blocking, and resource limits - Added security scanning for imported skills with critical-findings gate **Architecture:** - Session files implementation (1092 LOC) includes sophisticated transcript parsing, path normalization, action inference from tool calls, and optional workspace scanning - Skills import flow validates archive structure, scans for security issues, and installs to managed directory (`~/.openclaw/skills`) - Archive extraction reuses shared utilities with proper validation against path traversal, absolute paths, and Windows drive paths - New methods properly registered in gateway method list with appropriate authorization scopes (`operator.read` for listing, existing scopes for other operations) <h3>Confidence Score: 4/5</h3> - This PR is largely safe to merge with minor considerations around edge cases - The implementation demonstrates strong engineering practices with comprehensive security hardening, proper input validation, and good test coverage. Security measures include archive extraction safeguards, skill scanning, bounded result sizes, and parameter validation. The code reuses established patterns and properly integrates with existing authorization. However, the session files transcript parsing (1092 LOC) is complex and handles many edge cases that may need production validation, and the workspace mtime scanning is gated behind an environment flag which is prudent - `src/gateway/session-files.ts` warrants close monitoring in production due to its complexity in parsing various tool call formats and inferring file actions _{Last reviewed commit: cb41d62} <!-- greptile_other_comments_section --> _{(2/5) Greptile learns from your feedback when you react with thumbs up/down!} <!-- /greptile_comment -->