@usulpro/codex-bee 0.1.1

package/README.md

@@ -0,0 +1,535 @@
+# codex-bee
+
+`codex-bee` is an autonomous wrapper around Codex CLI. The goal is to keep the standard Codex terminal experience intact while adding opt-in continuation modes driven by Stop hooks.
+
+When installed globally, the command surface is `bee`.
+
+The preferred launch contract is:
+
+```bash
+bee <command> [command args]
+```
+
+The primary target is still Codex-compatible CLIs, so the common form is:
+
+```bash
+bee codex [codex args]
+```
+
+The wrapper also accepts the explicit separator form:
+
+```bash
+bee [wrapper options] -- <command> [command args]
+```
+
+## Status
+
+The interactive PTY baseline is live. The wrapper now boots Codex inside a PTY, keeps the normal terminal workflow visible to the user, validates the effective `codex_hooks` feature and required `SessionStart` / `UserPromptSubmit` / `Stop` hook config before starting an interactive Codex session, can bootstrap the global `~/.codex/hooks.json` hook file when it is missing, writes hook captures back into the live session workspace even when the hook script comes from a global install, surfaces a truthful early session state by moving from `Hooks ready` to `Connected` on `SessionStart` and to a running turn on `UserPromptSubmit`, supports zero-delay one-shot continuation prompts, supports guarded repeat loops with configurable max-injection and max-duration limits, renders continuation prompt templates from Stop payload data on each matched turn, exposes safer helper placeholders for previous assistant messages, supports file-based continuation templates for longer prompts, injects continuation text through bracketed paste so multiline prompts stay intact, exposes a first control overlay checkpoint behind `Ctrl+B`, records runtime events for overlay and watcher activity, includes a first isolated bee-agent continuation mode backed by `codex exec`, bounded transcript context, persistent session notes, and an optional verification-command gate that can stop auto-continue when checks pass or append failing check output to the next injected prompt, and now includes explicit automated coverage plus a review harness for concurrent same-sandbox wrapper runs.
+
+## Project goals
+
+- Preserve the native Codex TUI by running Codex inside a PTY wrapper.
+- Detect completed turns through Codex Stop hooks.
+- Forward hook payloads to a wrapper process through an IPC transport that can support multiple parallel sessions.
+- Decide whether to continue automatically, then inject the next prompt back into the PTY.
+
+## Parallel session isolation
+
+Parallel wrapper sessions are keyed by a per-process `CODEX_BEE_RUN_ID`, not only by the working directory.
+This matters when multiple `bee codex ...` sessions share the same sandbox, the same repository, or even the same shell location.
+
+Current isolation guarantees:
+
+- every wrapper run gets its own random run ID
+- the Stop-capture watcher matches captures by both `cwd` and `CODEX_BEE_RUN_ID`
+- runtime events in `.codex/tmp/bee-events.jsonl` are tagged with `runId`
+- startup no longer wipes shared Stop captures, because that broke concurrent runs by deleting evidence that belonged to another live wrapper
+
+`last-stop-capture.json` is still a shared convenience pointer inside one sandbox, so it should be treated as "latest overall capture", not "latest capture for my specific run".
+For parallel debugging, prefer `./bee-inspect-events --all` and the full `stop-captures/` directory.
+
+## Planned architecture
+
+- `src/cli.ts`: CLI entry point and process bootstrap.
+- `src/auto-continue.ts`: Stateful continuation controller and guardrails.
+- `src/pty-proxy.ts`: PTY spawn, terminal passthrough, and buffered output while the overlay is open.
+- `src/hook-server.ts`: IPC listener for hook payload delivery.
+- `src/continuation.ts`: Continuation decision engine.
+- `src/continuation-watcher.ts`: Stop-capture watcher loop and prompt injection orchestration.
+- `src/bee-agent.ts`: Bee-agent config loading, bounded context packaging, notes persistence, and isolated generator execution.
+- `src/transcript.ts`: Transcript parsing for recent user and assistant turns plus token-count snapshots.
+- `src/verification.ts`: Verification-command execution plus prompt-safe failure summaries.
+- `src/overlay.ts`: Runtime control overlay for prompt and guardrails.
+- `src/runtime-log.ts`: JSONL runtime event logging for live debugging.
+- `hooks/stop-hook.cjs`: Standalone CommonJS hook script that must remain runnable without a build step.
+
+## Requirements
+
+- Node.js 20+
+- pnpm 10+
+- Codex CLI installed and authenticated on the target machine
+
+The repository now pins the development floor with [`.nvmrc`](/home/usulpro/projects/PrimeUI/open/codex-bee/.nvmrc), so `nvm use` is the expected local bootstrap path.
+
+## Scripts
+
+- `pnpm baseline:clear`: Remove stored local Stop hook captures
+- `pnpm baseline:inspect`: Print a summary of the latest local Stop hook capture
+- `pnpm build`: Bundle the CLI with `tsup`
+- `pnpm dev`: Watch-mode build
+- `pnpm package:check`: Pack the project, install the tarball into a temporary prefix, and smoke-test the installed CLI
+- `pnpm publish:local`: Typecheck, pack, smoke-test, and install the tarball globally for local CLI testing
+- `pnpm sandbox:clean`: Remove the disposable live-test sandbox from `CODEX_BEE_SANDBOX_DIR`
+- `pnpm sandbox:prepare`: Recreate the disposable live-test sandbox and its local hook harness
+- `pnpm test`: Run focused automated coverage for continuation rendering, bee-agent context packing, and CLI parsing
+- `pnpm typecheck`: Run TypeScript without emitting files
+- `pnpm ui:demo`: Run the standalone Ink control UI against a mocked runtime host
+- `pnpm ui:dev`: Run the standalone Ink control UI in watch mode for fast iteration
+- `pnpm ui:test`: Run focused UI tests for the renderer-agnostic controller, mocked runtime, and Ink renderer smoke path
+
+## Notes
+
+- The hook script in `hooks/stop-hook.cjs` is intentionally plain CommonJS so it can run directly from Codex hooks without depending on the project build.
+- The IPC mechanism is still intentionally undecided until the baseline experiments validate env propagation, process tree behavior, and hook payload shape.
+- Prefer live hook experiments inside the disposable sandbox harness during development, but interactive `bee codex ...` runs now validate and can bootstrap the global `~/.codex/hooks.json` hook file plus the effective `codex_hooks` feature when you launch outside the sandbox.
+- When auto-continue is disabled and stdin/stdout are not TTYs, `bee codex ...` now falls back to direct inherited-stdio passthrough instead of failing on the PTY requirement. This keeps commands such as `bee codex --help` and `bee codex exec ...` usable in non-interactive environments.
+- `--verify-command` currently uses a shell command string (`sh -lc ...`) and is intentionally CLI-first. It is designed for mechanical checks such as `pnpm typecheck`, `pnpm test`, `npm run build`, or `git diff --quiet`.
+
+## Packaging
+
+`prepack` now runs `pnpm build`, so `npm pack` and `npm publish` no longer depend on a manual build step.
+
+For a reproducible package smoke check that does not rely on Volta global shims, prefer:
+
+```bash
+pnpm package:check
+```
+
+That flow:
+
+- builds through the `prepack` lifecycle
+- creates a tarball with `npm pack`
+- installs that tarball into a temporary prefix
+- runs the installed CLI with `--help`
+
+For the one-command local release flow, prefer:
+
+```bash
+pnpm publish:local
+```
+
+That flow:
+
+- runs `pnpm typecheck`
+- packs the tarball through `npm pack` and `prepack`
+- smoke-tests the packed install in a temporary prefix
+- installs that tarball globally
+- verifies the resulting `bee --help` output
+
+If the current environment cannot write to the real global toolchain location, you can redirect the install target just for this command:
+
+```bash
+BEE_PUBLISH_LOCAL_PREFIX=/tmp/codex-bee-local pnpm publish:local
+```
+
+On Volta-managed shells, the active `bee` command may still resolve through `~/.volta/bin/bee` even after a successful tarball install. `pnpm publish:local` now checks `bee --version` and fails if the active PATH entry is still shadowing the freshly installed binary. In that case, either run the installed binary directly from `$(npm prefix -g)/bin/bee`, or keep using an isolated prefix:
+
+```bash
+BEE_PUBLISH_LOCAL_PREFIX=/tmp/codex-bee-local pnpm publish:local
+/tmp/codex-bee-local/bin/bee --version
+```
+
+For manual local global-install experiments, prefer installing the tarball rather than `npm i -g .` when Volta is involved:
+
+```bash
+pnpm package:check
+npm pack
+npm i -g ./usulpro-codex-bee-<version>.tgz
+```
+
+Published installs should still use the registry form:
+
+```bash
+npm i -g @usulpro/codex-bee
+bee codex
+```
+
+## UI development
+
+The current UI iteration path uses `Ink` plus `@inkjs/ui` on top of a renderer-agnostic contract.
+This is the active TUI surface for the project right now, not a disposable reset branch.
+
+Read [docs/tui-isolated-development.md](docs/tui-isolated-development.md) before starting the next TUI pass. It is the handoff document for the isolated workflow, file boundaries, and testing loop.
+
+Current UI architecture layers:
+
+- `src/ui/core/`: renderer-agnostic state, typed intents, controller logic, and derived view helpers
+- `src/ui/runtime/`: host interfaces plus adapters for mocked and future live wrapper runtimes
+- `src/ui/renderers/ink/`: the current Ink renderer
+- `src/ui/dev-harness/`: isolated mocked runtime scenarios and standalone entry point
+
+Use the isolated harness when iterating on UI work:
+
+```bash
+pnpm ui:demo
+pnpm ui:demo -- --scenario bee-agent
+pnpm ui:dev
+pnpm ui:test
+```
+
+`pnpm ui:dev` is the fast local loop for UI work. It does not require the PTY wrapper, the sandbox harness, or a live Codex session.
+The current standalone scenarios cover idle, armed static continuation, verification failure, bee-agent mode, and repeat-loop mode.
+The current Ink renderer is the working TUI surface. Use the isolated harness to refine the existing layout, keyboard flow, status reporting, and runtime contract without destabilizing live PTY sessions.
+The live status model now distinguishes early hook readiness from a proven attached session: preflight yields `Hooks ready`, `SessionStart` upgrades that to `Connected`, and `UserPromptSubmit` marks the active turn as running before `Stop` completes it.
+Current keyboard contract inside the standalone shell:
+
+- `Tab` switches screens
+- `Ctrl+B` hides or reopens the shell
+- `Ctrl+C` exits `pnpm ui:demo`
+
+The selected screen still stays in UI state, so closing and reopening the shell returns to the same screen.
+`pnpm ui:demo` lets the Ink app own `Ctrl+C`, while `pnpm ui:dev` hands `Ctrl+C` back to the outer watch process so you can stop the dev loop cleanly without the renderer swallowing the signal first.
+
+The isolated Ink shell remains the safest local workshop for UI changes, but it should track and improve the current product direction rather than reboot it.
+Alternative renderer explorations are currently deprecated unless they are explicitly revived by product direction.
+
+## Sandbox harness
+
+Sandbox location comes from `.env`:
+
+```bash
+CODEX_BEE_SANDBOX_DIR=~/projects/PrimeUI/sandboxes/codex-bee-lab
+```
+
+Start by copying `.env.example` to `.env` and adjusting the path if needed.
+
+The sandbox is disposable. Each live experiment should start from a fresh harness:
+
+```bash
+pnpm build
+pnpm sandbox:clean
+pnpm sandbox:prepare
+cd "$CODEX_BEE_SANDBOX_DIR"
+```
+
+`pnpm sandbox:prepare` creates:
+
+- sandbox-local `.codex/config.toml`
+- sandbox-local `.codex/hooks.json`
+- sandbox-local `hooks/stop-hook.cjs`
+- sandbox-local `logs/`, `artifacts/`, and `prompts/`
+- a `bee` launcher that points back to the built wrapper in this repository
+- `bee-clear-stop-captures`, `bee-inspect-stop-capture`, `bee-inspect-events`, `bee-inspect-transcript`, and `bee-inspect-agent-state` helper launchers for local runtime artifacts
+- a `bee-record-review` launcher that records a review bundle for live PTY sessions
+- a `bee-record-parallel-review` launcher that records two concurrent same-sandbox wrapper runs for isolation checks
+- sample bee-agent prompts and `prompts/bee-agent-demo.json` for the first generated-continuation smoke path
+
+All generated sandbox launchers pin their working directory to the sandbox root before they exec Node, so hook capture paths and runtime logs stay isolated even if the launcher is invoked through an absolute path from another shell location.
+
+The sandbox also seeds a demo bee-agent config under `prompts/bee-agent-demo.json`. Prompt paths inside a bee-agent config resolve relative to the config file directory, not the process cwd.
+
+The sandbox harness captures Stop hook evidence into `.codex/tmp/stop-captures/`, refreshes `.codex/tmp/last-stop-capture.json` on each run, and records wrapper events in `.codex/tmp/bee-events.jsonl`.
+
+Example smoke run:
+
+```bash
+cd "$CODEX_BEE_SANDBOX_DIR"
+codex exec --enable codex_hooks "Reply with READY only."
+./bee-inspect-stop-capture
+./bee-inspect-events
+./bee-inspect-transcript
+```
+
+The repository root no longer carries an active `.codex/hooks.json`, so operator sessions in the repo stay isolated from the disposable live-test harness.
+
+## Interactive runs
+
+For interactive manual runs, start from the sandbox and use the `codex_bee_live` profile from `~/.codex/config.toml`.
+
+Direct Codex session:
+
+```bash
+cd "$CODEX_BEE_SANDBOX_DIR"
+codex -p codex_bee_live
+```
+
+Wrapper session from the sandbox:
+
+```bash
+pnpm build
+pnpm sandbox:clean
+pnpm sandbox:prepare
+cd "$CODEX_BEE_SANDBOX_DIR"
+./bee codex --profile codex_bee_live
+```
+
+One-shot continuation smoke run through the wrapper:
+
+```bash
+cd "$CODEX_BEE_SANDBOX_DIR"
+./bee --continue-once "Reply with READY only and stop." codex --profile codex_bee_live
+```
+
+`--continue-once` now defaults to zero extra delay after the matched Stop capture. Keep `--inject-delay-ms` only as a debug override for edge-case PTY timing experiments.
+
+Repeat continuation loop smoke run with a three-injection guardrail:
+
+```bash
+cd "$CODEX_BEE_SANDBOX_DIR"
+./bee --continue-loop "Reply with NEXT only and stop." --max-continues 3 codex --profile codex_bee_live --no-alt-screen "Reply with FIRST only and stop."
+```
+
+`--continue-loop` reuses the same follow-up prompt after each matched Stop event and stops injecting automatically after `--max-continues` is reached.
+
+Bee-agent loop smoke run through the wrapper:
+
+```bash
+cd "$CODEX_BEE_SANDBOX_DIR"
+./bee --continue-loop-agent-file prompts/bee-agent-demo.json --max-continues 2 codex --profile codex_bee_live --no-alt-screen "Reply with FIRST only and stop."
+```
+
+Expected demo sequence with the seeded sandbox bee-agent prompts:
+
+- `FIRST`
+- bee-agent generates `Reply with SECOND only and stop.`
+- `SECOND`
+- bee-agent generates `Reply with THIRD only and stop.`
+- `THIRD`
+
+After the run:
+
+```bash
+cd "$CODEX_BEE_SANDBOX_DIR"
+./bee-inspect-agent-state
+./bee-inspect-events
+./bee-inspect-transcript
+```
+
+Use this profile for PTY-focused experiments so the session has the same interactive permissions that were already confirmed to work.
+
+## Control overlay
+
+`Ctrl+B` opens the first runtime control overlay checkpoint.
+
+Current overlay capabilities:
+
+- edit the static continuation prompt, including multiline content
+- arm auto-continue directly from the overlay
+- change the repeat guardrail
+- change the session-duration guardrail with values like `90m`, `1.5h`, `5400s`, or `off`
+- disable auto-continue without restarting Codex
+
+The overlay now uses the terminal alternate screen buffer so closing it can restore the previous Codex view instead of forcing a redraw guess.
+
+Overlay commands:
+
+- `E`: edit the continuation prompt
+- `R`: edit max repeats
+- `T`: edit max duration
+- `A`: apply and arm the current draft
+- `D`: disable auto-continue
+- `Q` or `Ctrl+B`: close without applying
+
+Prompt editing uses a simple multiline editor:
+
+- `Ctrl+D`: save the prompt draft
+- `Esc`: cancel prompt editing
+
+Every overlay session now writes runtime events such as `overlay_opened`, `overlay_prompt_updated`, `overlay_apply`, `stop_capture_matched`, and `continuation_prompt_injected` to `.codex/tmp/bee-events.jsonl`.
+
+Each event now carries a `runId` and a per-run sequence number. `./bee-inspect-events` shows the latest run by default, including the exact overlay-applied prompt text, matched Stop count, and injected prompt count. Pass `--all` if you need the full history from the current sandbox log.
+
+When the overlay arms or disables auto-continue, the wrapper now also prints an explicit stderr confirmation so live runs make it obvious whether the control action actually took effect.
+
+## Review harness
+
+`./bee-record-review` is the first semi-manual PTY verification harness.
+
+It wraps a live `./bee codex ...` session in terminal recording and saves a review bundle under:
+
+```bash
+logs/reviews/<timestamp>[-label]/
+```
+
+Each review bundle includes:
+
+- `terminal.typescript`
+- `command.txt`
+- `metadata.json`
+- `checklist.md`
+- `bee-events.jsonl` when runtime events exist
+- `bee-events-summary.txt`
+- `last-stop-capture.json` when a Stop capture exists
+- `stop-capture-summary.txt`
+- `transcript-summary.txt` and `transcript-summary.json` when a transcript is available
+- `bee-agent-state.txt` when bee-agent state is available
+
+Example review recording for the current bee-agent checkpoint:
+
+```bash
+cd "$CODEX_BEE_SANDBOX_DIR"
+./bee-record-review --label bee-agent-demo --continue-loop-agent-file prompts/bee-agent-demo.json --max-continues 2 codex --profile codex_bee_live --no-alt-screen "Reply with FIRST only and stop."
+```
+
+This still requires a human to visually judge redraw and terminal fidelity, but it now leaves a consistent artifact bundle behind for later inspection instead of relying on memory and ad-hoc screenshots.
+
+For same-sandbox concurrency review, use:
+
+```bash
+cd "$CODEX_BEE_SANDBOX_DIR"
+./bee-record-parallel-review --label same-sandbox
+```
+
+This launches two wrapper sessions in parallel from the same sandbox root:
+
+- left: `ALPHA-FIRST -> ALPHA-SECOND`
+- right: `BETA-FIRST -> BETA-SECOND`
+
+The review bundle includes separate terminal recordings, shared runtime events, copied Stop captures, and a `parallel-summary.json` token check so you can confirm that each wrapper continued only its own session.
+
+## Continuation prompt templates
+
+`--continue-once`, `--continue-loop`, `--continue-once-file`, and `--continue-loop-file` all accept `{{placeholder}}` tokens. The wrapper renders those tokens from the matched Stop capture immediately before each injected prompt, so the rendered prompt can change from turn to turn without adding a second model call.
+
+File-based continuation templates are validated before Codex starts and re-read on every matched Stop event. The PTY injection path now uses bracketed paste, so multiline template files can be submitted as one logical prompt instead of breaking on the first newline.
+
+Supported placeholders:
+
+- `{{captured_at}}`
+- `{{cwd}}`
+- `{{hook_event_name}}`
+- `{{last_assistant_message_excerpt}}`
+- `{{last_assistant_message_json}}`
+- `{{last_assistant_message_single_line}}`
+- `{{last_assistant_message}}`
+- `{{model}}`
+- `{{permission_mode}}`
+- `{{run_id}}`
+- `{{session_id}}`
+- `{{stop_hook_active}}`
+- `{{transcript_path}}`
+
+Known placeholders that are missing in a capture render as empty strings. Unknown placeholders stay unchanged in the prompt, and the wrapper prints a warning once per unknown token.
+
+Safer helpers for previous assistant content:
+
+- `{{last_assistant_message_single_line}}`: collapses whitespace and newlines into a single trimmed line
+- `{{last_assistant_message_json}}`: emits a JSON string literal of the raw message, useful when you need newline-safe quoting
+- `{{last_assistant_message_excerpt}}`: emits a single-line excerpt capped at 280 characters
+
+Example loop that proves the prompt template changes on each Stop event:
+
+```bash
+cd "$CODEX_BEE_SANDBOX_DIR"
+./bee --continue-loop "Reply with TRACE: {{last_assistant_message}} only and stop." --max-continues 3 codex --profile codex_bee_live --no-alt-screen "Reply with FIRST only and stop."
+```
+
+Expected sequence:
+
+- `FIRST`
+- `TRACE: FIRST`
+- `TRACE: TRACE: FIRST`
+- `TRACE: TRACE: TRACE: FIRST`
+
+Example one-shot prompt that is safer for multiline previous answers:
+
+```bash
+cd "$CODEX_BEE_SANDBOX_DIR"
+./bee --continue-once "Reply with SAFE {{last_assistant_message_single_line}} only and stop." codex --profile codex_bee_live --no-alt-screen "Reply with exactly two lines: FIRST and SECOND. Stop after that."
+```
+
+Example multiline template file workflow:
+
+```bash
+cat >/tmp/codex-bee-follow-up.txt <<'EOF'
+Reply with the exact token from the next line only.
+SECOND-LINE
+Stop after that.
+EOF
+
+cd "$CODEX_BEE_SANDBOX_DIR"
+./bee --continue-once-file /tmp/codex-bee-follow-up.txt codex --profile codex_bee_live --no-alt-screen "Reply with READY only and stop."
+```
+
+Expected sequence:
+
+- `READY`
+- file-based continuation is injected as a single multiline prompt
+- `SECOND-LINE`
+
+## Verification-command gate
+
+`--verify-command` adds a simple mechanical gate on top of any continuation mode.
+
+Current behavior:
+
+- after each matched Stop event, the wrapper runs the configured shell command
+- if the command exits with `0`, auto-continue stops and no new prompt is injected
+- if the command exits with a non-zero code, auto-continue keeps going and appends a verification summary to the next injected prompt
+- the appended summary includes the command text, exit code, and tail excerpts from `stderr` and `stdout`
+
+Example loop that keeps Codex working until `pnpm typecheck` passes:
+
+```bash
+cd "$CODEX_BEE_SANDBOX_DIR"
+./bee --continue-loop "Continue fixing the verification failure." --verify-command "pnpm typecheck" --max-continues 5 codex --profile codex_bee_live --no-alt-screen "Find and fix the type errors, then stop."
+```
+
+This is intentionally a lightweight alternative to bee-agent orchestration. It gives the wrapper a deterministic continue-or-stop signal without requiring a second model call.
+
+## Bee-agent continuation mode
+
+`--continue-once-agent-file` and `--continue-loop-agent-file` enable the first AI-assisted continuation flow.
+
+Bee-agent config files are JSON and resolve prompt paths relative to the config file directory:
+
+```json
+{
+  "systemPromptPath": "bee-agent-system.md",
+  "sessionPromptPath": "bee-agent-session.md",
+  "model": "gpt-5.4",
+  "maxRecentMessages": 6,
+  "maxNoteChars": 4000,
+  "maxObjectiveChars": 1500,
+  "maxLastAssistantChars": 4000
+}
+```
+
+Current bounded bee-agent context includes:
+
+- `lastAssistantMessage` from the matched Stop payload
+- recent `user` and `assistant` transcript turns when `transcript_path` is available
+- the first user turn as `sessionObjective`
+- persistent `beeNotes` for the current wrapped session
+- session metadata such as `sessionId`, `cwd`, `model`, and `permissionMode`
+
+When transcript artifacts are available, the parser now prefers structured `event_msg` records over raw `response_item.message` entries:
+
+- `event_msg.user_message.message` is the cleanest source for operator-visible prompt text
+- `event_msg.task_complete.last_agent_message` is the cleanest source for the final assistant report for each completed turn
+- `event_msg.token_count` exposes per-turn token usage snapshots and the current context-window size
+
+This matters because raw `response_item.message role=user` entries often include the initial session context blob, while `user_message` tracks the actual prompts that entered the session.
+
+Current bee-agent state lives under:
+
+```bash
+.codex/tmp/bee-agent/<session-id>/
+```
+
+The wrapper stores:
+
+- `notes.md`
+- per-run `context.json`
+- per-run `generator-prompt.md`
+- per-run `result.json`
+- per-run `stdout.log` and `stderr.log`
+
+The generator run is intentionally isolated with:
+
+- `codex exec`
+- `--ephemeral`
+- `--disable codex_hooks`
+- structured JSON output through `--output-schema`
+
+If the bee-agent generator fails, the wrapper surfaces the failure and disables auto-continue instead of silently looping on broken state.

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node