@usulpro/codex-bee 0.1.1 → 0.1.3

package/README.md

@@ -1,6 +1,6 @@
 # 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.
+`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 and configured from the live control UI.
 
 When installed globally, the command surface is `bee`.
 
@@ -19,12 +19,12 @@ bee codex [codex args]
 The wrapper also accepts the explicit separator form:
 
 ```bash
-bee [wrapper options] -- <command> [command args]
+bee [bee 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.
+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`, stages continuation prompts and guardrails from the in-session UI instead of startup CLI flags, renders prompt templates from hook payload data on each matched turn, injects continuation text through bracketed paste so multiline prompts stay intact, and records runtime events for overlay and watcher activity.
 
 ## Project goals
 
@@ -93,7 +93,7 @@ The repository now pins the development floor with [`.nvmrc`](/home/usulpro/proj
 - 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`.
+- The public `bee` CLI is intentionally minimal now: only `--help` and `--version` belong to the wrapper itself. Continuation prompts, guardrails, and verification commands are configured from the live UI after launch.
 
 ## Packaging
 
@@ -263,44 +263,18 @@ cd "$CODEX_BEE_SANDBOX_DIR"
 ./bee codex --profile codex_bee_live
 ```
 
-One-shot continuation smoke run through the wrapper:
+Current continuation flow is UI-driven:
 
-```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`
+- launch `./bee codex --profile codex_bee_live`
+- wait for `Hooks ready` and then `Connected`
+- press `Ctrl+B` to open the Bee screen
+- type the continuation prompt in the composer and submit it to arm static continuation
+- use slash commands such as `/steps-count 3`, `/duration 90`, `/sleep 23:30`, and `/stop-script pnpm typecheck` to change guardrails and the optional verification command for the live session
 
 After the run:
 
 ```bash
 cd "$CODEX_BEE_SANDBOX_DIR"
-./bee-inspect-agent-state
 ./bee-inspect-events
 ./bee-inspect-transcript
 ```
@@ -313,11 +287,12 @@ Use this profile for PTY-focused experiments so the session has the same interac
 
 Current overlay capabilities:
 
-- edit the static continuation prompt, including multiline content
+- stage or 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
+- show truthful hook/session state as it moves from preflight readiness to a proven attached Codex session
 
 The overlay now uses the terminal alternate screen buffer so closing it can restore the previous Codex view instead of forcing a redraw guess.
 
@@ -368,30 +343,23 @@ 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."
+./bee-record-review --label ui-session codex --profile codex_bee_live
 ```
 
 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:
+The older same-sandbox concurrency launcher is currently deprecated because it depended on the removed startup continuation flags. Leave it in the sandbox only as a reminder that a UI-driven replacement review flow still needs to be rebuilt.
+
+If you want to inspect the deprecated harness entry point:
 
 ```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.
+Continuation prompts submitted from the UI can include `{{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.
 
 Supported placeholders:
 
@@ -417,49 +385,15 @@ Safer helpers for previous assistant content:
 - `{{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:
+Example static prompt text to submit from the Bee composer:
 
-```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."
+```text
+Reply with TRACE: {{last_assistant_message_single_line}} 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.
+`/stop-script <command>` adds a simple mechanical gate on top of any continuation mode.
 
 Current behavior:
 
@@ -468,32 +402,11 @@ Current behavior:
 - 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
-}
-```
+Bee-agent plumbing still exists in the codebase, but it is not part of the minimal public launch contract right now. Treat it as internal implementation surface until the current TUI exposes it again in a deliberate way.
 
 Current bounded bee-agent context includes: