Skip to main content
@obversa/core runs one child process with a deadline and returns a result you can read whatever happened: it finished, it hung, it filled a pipe, or it ignored a signal. Workflows run child processes all the time, a git call, a model CLI, a test command, and a hang carries no error; this package makes every one of them end with a result. The engine command runner, the runtime’s Git and command sites and the Git memory adapter run their children through it.

Install

Included in @obversa/obversa.

Run one

Run a child with a deadline and an output cap, and read what it wrote:
examples/run-child.ts
Output
runChild(options) needs executable, timeoutMs and maxOutputBytes. It returns exitCode (a number, or null when a signal stopped the child), stdout and stderr as bytes, and the timedOut and aborted flags. All of it comes from facts the helper recorded, never from whichever callback fired first. stdout and stderr hold what arrived before the child exited and during a short drain after it; a timed-out child’s result still carries what it wrote before the deadline, up to the cap. When the deadline passes, the child is stopped and the result says so, even when the stopped child reports no exit code. Standard input is closed after the optional input, and both output streams are drained until they close or for a short grace after the child exits, under one combined byte cap. Children the helper started are stopped when your process exits or is interrupted: on exit they get a terminate signal, and on an interrupt the helper stops its children and re-raises the signal. Your own handler for a signal takes precedence.

Find an executable

resolveCommandExecutable from @obversa/core/command reads your PATH when the file runs, so a copied example doesn’t carry a machine-specific path:
examples/teams/threshold-panel.ts (excerpt)

Run an owned command

runOwnedCommand from @obversa/core/command runs a command-line tool to a deadline with output and memory bounds and returns a typed result, and stopOwnedProcessTree stops what it started. Both accept an ownerId, a sha256: digest the command passes to its children as OBVERSA_RUN_OWNER. Nested commands keep an inherited marker, and it wins over a supplied ownerId; only the outer command that supplied the id sweeps that owner’s marked processes during cleanup. On Linux the stop also finds every process that carries the request’s attemptId as OBVERSA_ATTEMPT_ID, the marker runOwnedCommand gives each process it starts. It looks again on each pass and once more before it reports that nothing is left, so a helper whose parent has already exited is still stopped. When you call stopOwnedProcessTree yourself, pass rootStartedAt, the start time readProcessIdentity(pid) reads while the root is alive. On Linux and macOS, the root’s process id counts only while that same process is alive. When the root leads its own group, that group counts until a new process gets the root’s id. Any other group stops counting once the root exits. A new process that gets the id later is not stopped, nor is its group while it runs. Without rootStartedAt, the stop finds nothing by the root’s process id or group. It then stops only the processes in observed, on Linux the processes that carry ownerId or attemptId, and their children. If it finds none, it sends no signal and returns an empty list, even if the root is still running. commandCleanupCapability() says how the platform cleans up: on Linux inherited-owner, processes carrying the marker are found through /proc; elsewhere observed-processes, cleanup follows the observed tree, and a helper that starts a new session before it’s seen can escape. inspectOwnerMarkedProcesses(ownerId) lists marked processes on Linux without stopping them and returns an empty list elsewhere, which proves nothing. Owner markers coordinate cleanup; they aren’t a security boundary. ownedCommandIdentity, attemptEnvironment, retryAfterHeaderToMs, scrubCapture, redactEnvValues and redactSecrets are the helpers the engine plugins share.

Read Claude’s stream

@obversa/core/claude-stream-json exports mapMessage, newAccumulator and the Accumulator type for reading Claude stream messages. @obversa/core/claude-tools exports claudeToolOptions, the tool configuration the Claude adapters share: it keeps only requested Read, Grep and Glob tools in read mode, no tools in none mode, removes permission rules for withheld tools, and refuses malformed rules and custom tools it can’t bound with an EngineError of kind invalid-config.

Options

timeoutMs and killGraceMs

timeoutMs is the deadline; at it the child is signalled. killGraceMs is how long the child has to stop before it is killed, and a child that still doesn’t stop makes the call throw TEARDOWN_INCOMPLETE.

detached

By default only the child is signalled, so a process the child started and left behind isn’t stopped, and the child sits in your process group so a terminal interrupt reaches it. detached: true gives the child its own group. While the child runs, each signal goes to every process in that group that ps shows starting no earlier than the child, each by its own process id. If the child’s start time can’t be read, only the child is signalled. If the child exits on SIGTERM, a process signalled this way that ps still shows once the child’s output has closed gets SIGKILL when killGraceMs has passed since the stop began. A process that joins the group after the last signal is not stopped.

The rest

Errors

  • RunChildError with a code: INVALID_OPTIONS, SPAWN_FAILED (the executable can’t start), OUTPUT_LIMIT (the child wrote past the cap), TEARDOWN_INCOMPLETE (the child didn’t stop within the grace). It carries the stdout and stderr captured so far.
  • OwnedCommandError on the command subpath: INVALID_EXECUTABLE, INVALID_COMMAND, SPAWN_FAILED, OUTPUT_LIMIT, MEMORY_LIMIT, PROCESS_INSPECTION, TEARDOWN_INCOMPLETE, with remainingProcesses.

API

  • runChild(options): one child to a deadline. Run one.
  • @obversa/core/command: runOwnedCommand, stopOwnedProcessTree, ownedCommandIdentity, resolveCommandExecutable, commandCleanupCapability, inspectOwnerMarkedProcesses, inspectOwnedProcessTree, inspectAttemptMarkedProcesses, inspectPipeHoldingProcesses, capturePipeOwnerProbe, measureOwnedProcessMemory, readAttemptMarkerProcessIds, readProcessIdentity, parseWindowsProcessRows, DEFAULT_OWNED_COMMAND_LIMITS, OwnedCommandError. Run an owned command.
  • @obversa/core/claude-stream-json: mapMessage, newAccumulator. @obversa/core/claude-tools: claudeToolOptions. Read Claude’s stream.
  • @obversa/core/testing: MockEngine, MockResponder, mockVerdict for scripted engine results. The adapter conformance kits are in @obversa/api/testing.

Next steps

  • Safe node attempts: how an engine turn is bounded and cleaned up on top of this.
  • API: the engine contract the command runner serves.