Repository navigation
feat(cli): add debug heap-dump command - #58252
Conversation
There was a problem hiding this comment.
Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.
An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.
![opencode-agent[bot]](https://avatars.githubusercontent.com/in/1549082?s=60&v=4){kind=small}
There was a problem hiding this comment.
I recommend merging this: the command works as described, and I found nothing that should block it.
I ran an opencode serve server from this branch and ran opencode debug heap-dump --server … against it. It printed the path of a complete snapshot file that only its owner can read (0600) and exited with 0. With no background server it fails without starting one. A wrong password gets a clear error. Pointed at a server from the base branch, it prints the "does not support heap dumps" message instead of a stack trace. The new server and CLI tests pass, and type checks pass for cli, server, util and protocol.
Public API changes, all additions and backwards compatible:
- HTTP: new
POST /api/debug/heap-dump(debug.heapDump) returning{ path, pid }, withUnknownError(500) on failure. It is in both OpenAPI documents. - Client: new
client.debug.heapDump()in the promise client andheapDumpon the effectDebugApi. - CLI: new
opencode debug heap-dump [--server <url>]; with--serverthe password comes fromOPENCODE_PASSWORD.
Related: #54928
There was a problem hiding this comment.
The new commit only edits documentation: it renames opencode2 to opencode in the opencode-dev skill. That's fine, and nothing else changed since my last review, which had no open points. The public API impact is the same as before: new POST /api/debug/heap-dump, client.debug.heapDump() and opencode debug heap-dump [--server], all backwards compatible.
There was a problem hiding this comment.
The two new commits are fine. One adds heapDump to the expected client.debug methods in the client test, which passes. The other refreshes the opencode-dev skill; the statements I spot-checked match the code (bun dev entrypoint, GET /api/info, dev:live). My last review had no open points. The public API impact is the same: new POST /api/debug/heap-dump, client.debug.heapDump() and opencode debug heap-dump [--server], all backwards compatible.
Windows has no
SIGUSR1, so there was no way to capture a heap snapshot of a running V2 background server there. This adds a CLI command that asks the server for one over its authenticated API.sequenceDiagram participant CLI as opencode debug heap-dump participant Reg as service registration participant S as background server CLI->>Reg: Service.discover (never ensure) CLI->>S: POST /api/debug/heap-dump (basic auth) S->>S: HeapSnapshot.write(global.log)<br/>one permit per process, file pre-created 0600 S-->>CLI: { path, pid } once the file is completeService.discover, notensure, so it never starts, replaces, or restarts the service. Starting a new server would only capture an empty heap, and replacing a mismatched one would destroy the leak being investigated.--server <url>targets a server started withopencode serve(password fromOPENCODE_PASSWORD).The server at <url> does not support heap dumps. Update and restart it first.instead of a stack trace.packages/util/src/heap-snapshot.tsis shared by the endpoint and the existing UnixSIGUSR1listener inpackages/cli/src/heap.ts. A process-wide semaphore queues concurrent captures, so two heaps never serialize at once.0600) before V8 writes into it, because it can contain prompts, file contents, and credentials.refand returned asUnknownError(500). The semaphore is released, so the next capture still works.node:v8is imported lazily inside the writer, so the workerd bundle carries no static dependency. A capture there fails as a normalUnknownError.Docs:
troubleshooting.mdxgets a "Capture a heap snapshot" section,cli/commands.mdxlists the command, and theopencode-devskill now leads with the command and keepsSIGUSR1for non-server processes.The OpenAPI documents include only this endpoint. The unrelated drift from
dev(/api/experimental/client-mcp) is left out.Added by the opencode bot (AI-generated).
Related: #54928
Public API: adds POST /api/debug/heap-dump, client debug.heapDump() and the
opencode debug heap-dump [--server]command (backwards compatible)