omp packages

@hheei/pi-bg-bash0.3.3

Background Bash tools with durable execution records and report delivery.

GitHub Actions Published 3 hours ago MIT ~467 downloads/mo

Untested on omp

This is a pi package. No one has reported whether it works on omp yet. If you try it, add your result below.

Did it work for you?

Result

One report per person. A new report replaces your old one.

Reports 0

No reports yet.

Readme

@hheei/pi-bg-bash

Background Bash for Pi. Owns one BashJobRegistry, the session execution ledger, job logs and terminal report delivery. The foreground bash tool and the bash settings group belong to @hheei/pi-ext-tools; this package only reads that group.

Install @hheei/pi-settings separately for the Settings UI. @hheei/pi-ext-core is a production dependency, not a separately loaded Pi extension.

Tools

  • bg_bash_spawn({ command, timeout? }) — starts a local command and returns JSON { id, path }, where path is the absolute log file path, on success, or the reason on failure. It does not accept a caller ID.
  • bg_bash_get({ id, keys? }) — queries status, progress, or diagnostic using a comma-separated keys string; default is status,progress. Unknown keys fail.
  • bg_bash_stop({ id }) — stops that Bash process tree and returns one confirmation sentence or a failure reason.

All three tools use deferred exposure, are inactive by default, and can be discovered with tool_search query bg_bash. There are no list or wait tools. Progress is bounded runtime context; completed output returns through automatic bg-bash-report delivery. Progress and automatic notices provide the same path (progress.path in get); read or grep that file for full output.

Execution records

Background execution records persist in tasks/<sessionId>/bash.sqlite beside the logs. Reload and session shutdown still stop owned processes. Resume restores records and missing reports only; it never adopts an old PID, resumes execution, or reruns a command. Missing reliable terminal evidence becomes unknown, with a warning that side effects may remain and logs may be incomplete. The agent must inspect evidence before deciding its next action. bg_bash_stop cannot stop an unknown historical execution. Reports are reconciled against the current raw session branch, including compacted ancestors. Forks use their own execution ledger. Legacy logs without ledger records remain untouched.

BashJobRegistry owns a single idle notice after 180s without stdout/stderr and periodic 1800s heartbeats, with timers cleared on stop, terminal state, or disposal. PTY work is deferred. Subagents use their separate agent_* tools and own execution state; only delivery batching is shared through ext-core BackgroundDelivery.

Settings

The bash group in the global ext_settings.json is registered by @hheei/pi-ext-tools. This package reads the same values at session start:

Field Default Effect here
shellPath $SHELL Shell that runs background commands.
outputTailKiB 10 Output tail retained per job record.