feat(bdd): opencode/codex CLI adapters for the general agent (#2677)

* feat(bdd)!: replace callAI general agent with opencode/codex CLI adapters

The general agent for `# @agent`/`$skill` steps is now a real CLI coding
agent spawned per step: opencode by default, Codex via
`generalAgent.type: 'codex'`. Both adapters reuse the Midscene model
endpoint/key (MIDSCENE_MODEL_*, legacy OPENAI_* fallback) with zero
config — opencode through a generated OPENCODE_CONFIG_CONTENT provider,
codex through `-c model_providers.*` TOML overrides — and degrade to the
CLI's own auth (`opencode auth login` / `codex login`) when overridden
or unavailable. New config knobs: model, env, cwd, timeoutMs,
permissions (read-only/workspace/all sandbox mapping), reuseMidsceneModelEnv,
sessionPerScenario. CallAiGeneralAgent and generalAgent.modelEnv are
removed (modelEnv now fails validation with a migration hint); the pure
prompt/verdict helpers moved to agents/general-prompt.ts unchanged.

BREAKING CHANGE: generalAgent.modelEnv is rejected; CallAiGeneralAgent
is gone. Use generalAgent.env/model/type or generalAgent.factory.

* refactor(bdd): deslop cli general-agent adapters

Dedupe the verdict-extraction block shared by both adapters into
toGeneralResult, share DEFAULT_TIMEOUT_MS and the temp-file path
construction in cli-agent.ts, inline the single-caller
findAuthFailureHint, drop the unused outputTail limit param, and
replace the sessionId `as string` cast with proper narrowing.
No behavior change.

* refactor(bdd): harden cli adapters per simplify review

Fix the stdin EPIPE crash path and split-multibyte UTF-8 decoding in
runCli, rethrow non-ENOENT errors when reading codex's last-message
file, and flatten the opencode model mapping into exclusive cases (an
explicit provider/model no longer injects an unused midscene provider).
Share planCommon/throwOnNonZeroExit between the adapters, make opencode
permissions handling exhaustive, type the resolved model env as a
discriminated union, import the env key names from @midscene/shared/env,
prune already-sent skills from resumed-session prompts, and add a
lastIndexOf backstop so an unbalanced brace in prose cannot hide a
trailing verdict.

---------

Co-authored-by: ScriptedAlchemy <zack@module-federation.io>

Author: ScriptedAlchemy

packages/bdd/README.md

@@ -26,7 +26,7 @@ Every statement is routed to exactly one executor:
 | Rule | Marker | Who executes the statement |
 | --- | --- | --- |
 | **Default** | none | Midscene UI agent — the vision model drives the page (`aiAct`) for Given/When and judges Then steps (`aiAssert`, fail-closed) |
-| **Agent** | `# [agent]` comment directly above the line, or a `$skill-name` token in it | A general-purpose coding agent (Codex app-server via `codex login`, or any OpenAI-compatible endpoint) — for behavior you cannot see in the browser: server logs, files, databases. Then steps must return a JSON verdict; a missing verdict fails (fail-closed) |
+| **Agent** | `# [agent]` comment directly above the line, or a `$skill-name` token in it | A real CLI coding agent ([opencode](https://opencode.ai) by default, [Codex](https://github.com/openai/codex) opt-in) spawned per step — for behavior you cannot see in the browser: server logs, files, databases. Then steps must return a JSON verdict; a missing verdict fails (fail-closed) |
 | **No AI** | `# [no-ai]` comment above the line (or `@no-ai` scenario/feature tag) | Classic BDD: a callback registered with `Given`/`When`/`Then`/`defineStep` from `@midscene/bdd` must match. An unimplemented step fails with a ready-to-paste snippet |
 
 All three in one scenario:
@@ -142,10 +142,11 @@ import { defineProfile } from '@midscene/bdd/profile';
 export default defineProfile().default;
 ```
 
-Model setup, either:
+Model setup:
 
-- `codex login` once, then point the general agent at it with `MIDSCENE_MODEL_BASE_URL=codex://app-server`, or
-- set the `MIDSCENE_MODEL_*` environment variables for any OpenAI-compatible endpoint (at minimum `MIDSCENE_MODEL_BASE_URL`, `MIDSCENE_MODEL_API_KEY`, `MIDSCENE_MODEL_NAME`).
+- The UI agent needs the `MIDSCENE_MODEL_*` environment variables for an OpenAI-compatible vision endpoint (at minimum `MIDSCENE_MODEL_BASE_URL`, `MIDSCENE_MODEL_API_KEY`, `MIDSCENE_MODEL_NAME`).
+- The general agent (`# [agent]`/`$skill` steps) is the [opencode](https://opencode.ai) CLI: `npm i -g opencode-ai`. With zero extra config it reuses your `MIDSCENE_MODEL_*` endpoint and key. Since that endpoint is tuned for vision, consider pointing the agent at a strong coding model instead via `generalAgent.model` (`'provider/model'`) plus `generalAgent.env`, or `opencode auth login`.
+- Prefer Codex? Set `generalAgent: { type: 'codex' }` and install it with `npm i -g @openai/codex`. Same endpoint reuse applies; without a usable endpoint it falls back to your `codex login` account.
 
 Run:
 
@@ -198,10 +199,31 @@ interface BddConfig {
   uiAgentOptions?: UiAgentOptions;
 
   generalAgent?: {
-    // MIDSCENE_MODEL_* overrides for the general agent, resolved in an
-    // isolated model config (never leaks into the UI agent). Defaults to
-    // process env; MIDSCENE_MODEL_BASE_URL=codex://app-server is supported.
-    modelEnv?: Record<string, string>;
+    // Which CLI coding agent runs `[agent]`/`$skill` steps.
+    type?: 'opencode' | 'codex';  // default: 'opencode'
+    // Model override. opencode: 'provider/model' or a bare name mapped onto
+    // the generated provider; codex: passed as -m. Default: the resolved
+    // MIDSCENE_MODEL_NAME (recommend a strong coding model over the
+    // vision default).
+    model?: string;
+    // Extra env for the spawned CLI, merged over process.env.
+    env?: Record<string, string>;
+    // Working directory the agent runs (and executes shell!) in.
+    cwd?: string;                 // default: the config file's directory
+    // Hard kill timeout per invocation.
+    timeoutMs?: number;           // default: 600_000 (10 min)
+    // SECURITY: the agent runs shell commands in cwd, driven by prose in
+    // your feature files. 'read-only' denies edits/shell writes,
+    // 'workspace' (default) allows workspace writes, 'all' disables
+    // sandboxing/permission prompts entirely — only use 'all' in an
+    // externally sandboxed environment.
+    permissions?: 'read-only' | 'workspace' | 'all';
+    // Reuse the Midscene endpoint/key (MIDSCENE_MODEL_*, legacy OPENAI_*
+    // fallback) for the CLI agent.
+    reuseMidsceneModelEnv?: boolean;  // default: true
+    // Continue one CLI session across the steps of a scenario, so later
+    // `[agent]` steps see what earlier ones found.
+    sessionPerScenario?: boolean;     // default: false
     // Escape hatch mirroring the uiAgent factory (e.g. for tests).
     factory?: () => Promise<GeneralAgent>;
   };

packages/bdd/example/README.md

@@ -6,10 +6,14 @@ needed) driven by Gherkin features through Midscene.
 ## Prerequisites
 
 1. Build the repo once from the root: `pnpm install && pnpm run build`.
-2. A model for the agents — either `codex login` (the general agent then uses
-   `MIDSCENE_MODEL_BASE_URL=codex://app-server`) or set the `MIDSCENE_MODEL_*`
-   environment variables (at minimum `MIDSCENE_MODEL_BASE_URL`,
-   `MIDSCENE_MODEL_API_KEY`, `MIDSCENE_MODEL_NAME`).
+2. A model for the UI agent: set the `MIDSCENE_MODEL_*` environment variables
+   (at minimum `MIDSCENE_MODEL_BASE_URL`, `MIDSCENE_MODEL_API_KEY`,
+   `MIDSCENE_MODEL_NAME`).
+3. The general agent (`# [agent]`/`$skill` steps): install the
+   [opencode](https://opencode.ai) CLI with `npm i -g opencode-ai` — with
+   zero extra config it reuses the `MIDSCENE_MODEL_*` endpoint above. Or set
+   `generalAgent: { type: 'codex' }` in `midscene.config.ts` and use
+   `npm i -g @openai/codex` + `codex login`.
 
 ## Run
 

packages/bdd/example/midscene.config.ts

@@ -7,4 +7,7 @@ export default defineBddConfig({
     type: 'web',
     url: pathToFileURL(join(__dirname, 'demo-app/index.html')).href,
   },
+  // General agent for `# [agent]` / `$skill` steps — zero config reuses the
+  // MIDSCENE_MODEL_* endpoint/key. Uncomment to customize:
+  // generalAgent: { type: 'opencode' },
 });

packages/bdd/package.json

@@ -7,7 +7,7 @@
     "url": "https://github.com/web-infra-dev/midscene.git",
     "directory": "packages/bdd"
   },
-  "description": "AI-native BDD test runner: standard Gherkin driven by cucumber-js, executed by Midscene. Midscene by default, coding agent on @agent/$skill, classic callbacks on @no-ai.",
+  "description": "AI-native BDD test runner: standard Gherkin driven by cucumber-js, executed by Midscene. Midscene by default, coding agent on [agent]/$skill, classic callbacks on @no-ai.",
   "author": "midscene team",
   "license": "MIT",
   "main": "./dist/lib/index.js",