# Exec Event Emission Plan

## Architecture Overview
- Exec/background process activity is centered in `src/agents/bash-tools.exec.ts` via `runExecProcess(...)`.
- Process lifecycle and output buffering are tracked in `src/agents/bash-process-registry.ts` (`addSession`, `appendOutput`, `markExited`, `drainSession`).
- Gateway event distribution already follows an emitter→listener→broadcast pattern.
- Emitter examples live in `src/infra/*-events.ts` (for example, `src/infra/agent-events.ts` and `src/infra/heartbeat-events.ts`).
- The gateway subscribes in `src/gateway/server.impl.ts` and broadcasts via `broadcast(...)`.
- Run/session linkage already exists through `runId` and agent run context.
- `runId` is created in `src/auto-reply/reply/agent-runner-execution.ts`.
- `runId` is threaded into embedded runs and tool subscriptions in `src/agents/pi-embedded-runner/run/attempt.ts`.
- The gateway resolves session keys for runs via `src/gateway/server-session-key.ts`.

## Proposed Design
- Add a dedicated exec events infra module.
- Provide a small event bus: `emitExecEvent(...)` and `onExecEvent(...)`.
- Provide a config resolver: `resolveExecEventsConfig(loadConfig())` with defaults and whitelist normalization.
- Capture orchestration context (run/tool/session) once at process start and store it on the session so background processes keep the link after the tool returns.
- Emit `exec.started` once per whitelisted process after spawn/pid is known.
- Emit `exec.output` in throttled and capped chunks tagged with `stdout` or `stderr`.
- Emit `exec.completed` once when the process closes (success or failure).

## Run Context Strategy
- Introduce a lightweight exec event context using `AsyncLocalStorage`.
- Add a new module: `src/infra/exec-events-context.ts`.
- Provide APIs: `runWithExecEventContext(context, fn)` and `getExecEventContext()`.
- Extend `createMoltbotCodingTools(...)` options with `runId?: string`.
- In `src/agents/pi-embedded-runner/run/attempt.ts`, pass `runId: params.runId`.
- In `src/agents/pi-tools.ts`, wrap each tool’s `execute(...)` so it runs inside `runWithExecEventContext({ runId, toolCallId, sessionKey })`.
- In `runExecProcess(...)`, read the current context once and attach it to the session’s exec-event state.

## Whitelist and Minimal Overhead
- Gate all exec event work behind an early, cheap check.
- If `hooks.exec.emitEvents !== true`, do nothing.
- If the command is not whitelisted, do nothing beyond a single boolean check in the output handlers.
- Normalize whitelist entries to lowercase command basenames.
- Extract candidate command names from the exec command string.
- Handle common wrappers: if the root command is `npx`, `pnpm`, `pnpmx`, `bunx`, `npm`, or `yarn`, inspect the first non-flag subcommand.
- Only run heavier shell parsing when the command text contains a possible whitelist token (string-contains prefilter).

## Output Throttling and Capping
- Maintain per-session output state only when enabled.
- Buffer per stream (`stdout` and `stderr`).
- Flush at most once per `outputThrottleMs` per process.
- Cap each emitted chunk to `outputMaxChunkBytes` (default 4096 bytes).
- On timer, emit one chunk per stream (bounded by max bytes).
- On completion, flush remaining buffered output before `exec.completed`.
- Impose a bounded in-memory buffer per stream to avoid unbounded growth under high output rates.
- If capped, drop oldest buffered data and set a `truncated` flag in the next output event payload.

## Gateway Integration
- In `src/gateway/server.impl.ts`, add an `onExecEvent(...)` subscription similar to `onAgentEvent(...)`.
- Broadcast with the existing `broadcast(eventName, payload, { dropIfSlow: true })`.
- Update `src/gateway/server-methods-list.ts` to include `exec.started`, `exec.output`, and `exec.completed`.
- Review `src/gateway/server-broadcast.ts`. Unless there is a policy reason, keep exec events available to operator clients without extra scopes.

## Configuration Plan
- In `src/config/types.hooks.ts`, add `HooksExecConfig`.
- In `src/config/zod-schema.hooks.ts`, add `HooksExecSchema`.
- In `src/config/zod-schema.ts`, include `exec: HooksExecSchema` under `hooks`.
- In `src/config/schema.ts`, add labels for `hooks.exec.emitEvents`, `hooks.exec.commandWhitelist`, `hooks.exec.outputThrottleMs`, and `hooks.exec.outputMaxChunkBytes`.
- In `src/config/schema.ts`, add descriptions aligned with the requirement defaults.
- Defaults (in the resolver, not mutating user config): `emitEvents: true`.
- Defaults (in the resolver, not mutating user config): `commandWhitelist: ["codex", "claude", "opencode", "pi", "gog", "himalaya", "playwright", "puppeteer"]`.
- Defaults (in the resolver, not mutating user config): `outputThrottleMs: 150`.
- Defaults (in the resolver, not mutating user config): `outputMaxChunkBytes: 4096`.

## Files to Modify
- `src/agents/bash-tools.exec.ts`.
- `src/agents/bash-process-registry.ts`.
- `src/agents/pi-tools.ts`.
- `src/agents/pi-embedded-runner/run/attempt.ts`.
- `src/infra/exec-events.ts` (new).
- `src/infra/exec-events-context.ts` (new).
- `src/gateway/server.impl.ts`.
- `src/gateway/server-methods-list.ts`.
- `src/gateway/server-broadcast.ts` (review-only, likely no change).
- `src/config/types.hooks.ts`.
- `src/config/zod-schema.hooks.ts`.
- `src/config/zod-schema.ts`.
- `src/config/schema.ts`.

## Beads (Discrete Units of Work)
1. Add exec event infra: implement the event bus, config resolver, whitelist matcher, and throttled output buffer helpers.
2. Add exec event context: implement `AsyncLocalStorage` context helpers for run/tool/session metadata.
3. Thread runId into tool creation: extend `createMoltbotCodingTools(...)` options and pass `runId` from run attempt.
4. Wrap tool execution with context: apply the context wrapper in `src/agents/pi-tools.ts`.
5. Instrument exec lifecycle: in `runExecProcess(...)`, decide enablement once, emit `exec.started`, throttle output, and emit `exec.completed` once.
6. Gateway subscription and event registration: broadcast exec events and add them to the handshake events list.
7. Config schema updates: update types, zod schemas, and CLI config labels and descriptions.
8. Tests: add unit tests for matching and throttling, an integration test for a whitelisted command, a regression test for non-whitelisted commands, and a benchmark harness.

## Risk Assessment
- Lost run linkage for backgrounded processes. Mitigation: capture context at process start and store it on the session.
- Duplicate `exec.completed` emissions because `markExited(...)` can be called again (for example, during `process poll`). Mitigation: track an `emittedCompleted` flag in the session exec-event state and guard completion emission.
- Output volume and backpressure. Mitigation: throttle, cap chunk size, and bound in-memory buffers; always use `dropIfSlow: true` on broadcast.
- Command detection misses due to wrappers or env assignments. Mitigation: wrapper-aware matching and a prefilter plus fallback parse path.

## Test Strategy
- Unit test whitelist matching with a direct command (`codex`).
- Unit test whitelist matching with a wrapper command (`npx playwright test`).
- Unit test whitelist matching with an env prefix (`FOO=1 codex run`).
- Unit test throttle behavior so burst output yields at most one emit per throttle window per process.
- Unit test chunk capping so large output is split to the max chunk size.
- Integration test a whitelisted command by using `node -e` to print to stdout and stderr with short delays, then asserting `exec.started`, at least one `exec.output`, and `exec.completed`.
- Integration test a non-whitelisted command (for example, `echo hi`) and assert no exec events are emitted.
- Gateway e2e coverage if needed: start the gateway test server, subscribe via websocket, run a whitelisted exec, and assert events arrive with `runId` and `sessionKey` when available.
- Performance benchmark: run non-whitelisted exec commands in a tight loop and compare baseline with exec events enabled.
- Performance benchmark acceptance: ensure overhead stays within an acceptable bound and does not regress common workflows.

## Notes and Open Questions
- Event payload shape: the required fields will be present; additional fields like `runId`, `toolCallId`, `commandName`, and `truncated` can be included to improve tracing if desired.
- Node host events: node host currently emits `exec.finished` and `exec.denied`. This plan focuses on gateway-local exec; we can optionally map node events into the same exec event bus later.