> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fased.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Background Exec and Process Tool

# Background Exec + Process Tool

Fased runs shell commands through the `exec` tool and keeps long-running tasks
in memory. The `process` tool manages those background sessions.

## exec tool

Key parameters:

* `command` (required)
* `yieldMs` (default 10000): auto-background after this delay
* `background` (bool): background immediately
* `timeout` (seconds, default 1800): kill the process after this timeout
* `elevated` (bool): run on host if elevated mode is enabled/allowed
* Need a real TTY? Set `pty: true`.
* `workdir`, `env`

Behavior:

* Foreground runs return output directly.
* When backgrounded (explicitly or after `yieldMs`), the tool returns
  `status: "running"` + `sessionId` and a short tail.
* Output is kept in memory until the session is polled or cleared.
* If the `process` tool is disallowed, `exec` runs synchronously and ignores
  `yieldMs`/`background`.

## Child process bridging

When spawning long-running child processes outside the exec/process tools, attach
the child-process bridge helper. That covers CLI respawns, gateway helpers, and
similar children. It forwards termination signals, detaches listeners on
exit/error, avoids orphaned processes on systemd, and keeps shutdown behavior
consistent across platforms.

Environment overrides:

* `PI_BASH_YIELD_MS`: default yield (ms)
* `PI_BASH_MAX_OUTPUT_CHARS`: in‑memory output cap (chars)
* `FASED_BASH_PENDING_MAX_OUTPUT_CHARS`: pending stdout/stderr cap per stream
  (chars)
* `PI_BASH_JOB_TTL_MS`: TTL for finished sessions (ms, bounded to 1m–3h)

Config (preferred):

* `tools.exec.backgroundMs` (default 10000)
* `tools.exec.timeoutSec` (default 1800)
* `tools.exec.cleanupMs` (default 1800000)
* `tools.exec.notifyOnExit` (default true): enqueue a system event and request a
  heartbeat when a backgrounded exec exits.
* `tools.exec.notifyOnExitEmptySuccess` (default false): also enqueue completion
  events for successful backgrounded runs that produced no output.

## process tool

Actions:

* `list`: running + finished sessions
* `poll`: drain new output for a session (also reports exit status)
* `log`: read the aggregated output (supports `offset` + `limit`)
* `write`: send stdin (`data`, optional `eof`)
* `send-keys`: send PTY key tokens, literal text, or hex bytes
* `submit`: send Enter/CR to a PTY session
* `paste`: paste text, using bracketed paste by default
* `kill`: terminate a background session
* `clear`: remove a finished session from memory
* `remove`: kill if running, otherwise clear if finished

Notes:

* Only backgrounded sessions are listed/persisted in memory.
* Sessions are lost on process restart (no disk persistence).
* Session logs are only saved to chat history if you run `process poll/log` and
  the tool result is recorded.
* `process` is scoped per agent; it only sees sessions started by that agent.
* `process list` includes a derived `name` (command verb + target) for quick scans.
* `process log` uses line-based `offset`/`limit`.
* When both `offset` and `limit` are omitted, it returns the last 200 lines and
  includes a paging hint.
* When `offset` is provided and `limit` is omitted, it returns from `offset` to
  the end and is not capped to 200.

## Examples

Run a long task and poll later:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "exec", "command": "sleep 5 && echo done", "yieldMs": 1000 }
```

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "process", "action": "poll", "sessionId": "<id>" }
```

Start immediately in background:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "exec", "command": "npm run build", "background": true }
```

Send stdin:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "process", "action": "write", "sessionId": "<id>", "data": "y\n" }
```

Submit or paste into a PTY session:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "process", "action": "submit", "sessionId": "<id>" }
```

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "hello\n" }
```