humanish 0.105.0 → 0.106.0

package/docs/architecture/state-driven-executor.md

@@ -4,21 +4,22 @@ Date: 2026-06-15
 
 Status: shipped (PR1 of issue #148). The library path (a custom executor + a
 non-vision provider, driven through the lab with NO E2B and NO vision) is
-implemented and proven. A config-only deterministic lane and a
+implemented and proven. A config-only deterministic route and a
 `subject.contract.ref` JS-module loader are deferred (see "Deferred", below).
 
 ## What this is
 
-The computer-use (CUA) loop in [`src/computer-use.ts`](../../src/computer-use.ts)
-is provider- and substrate-agnostic by design: the model lives behind a
-`CuaProvider` port and the thing being driven lives behind a `CuaExecutor` port.
-You do not have to drive a screen with a vision model. You can point the loop at
-**an already-running local app** and drive it through that app's **in-process
-JavaScript automation contract** (e.g. `window.app.getState()`,
-`sendChat(text)`, `dispatch(action)`, `navigate(target)`), using `getState()` as
-the progress signal instead of a quantized screenshot — keeping humanish's
-composition (personas, the Observer, the normalized `ActorTrace` evidence
-bundle, redaction, and the friction / no-progress loop).
+The computer-use (CUA) loop in
+[`src/actors/computer-use/loop.ts`](https://github.com/danielgwilson/humanish/blob/main/src/actors/computer-use/loop.ts) is provider- and
+substrate-agnostic by design: the model lives behind a `CuaProvider` port and the thing
+being driven lives behind a `CuaExecutor` port. Both ports are declared in
+`src/actors/computer-use/loop/types.ts`. You do not have to drive a screen with a vision
+model. You can point the loop at **an already-running local app** and drive it through that
+app's **in-process JavaScript automation contract** (e.g. `window.app.getState()`,
+`sendChat(text)`, `dispatch(action)`, `navigate(target)`), using `getState()` as the
+progress signal instead of a quantized screenshot. humanish's composition stays in place
+(personas, the Observer, the normalized `ActorTrace` evidence bundle, redaction, and the
+friction / no-progress loop).
 
 This is the "plural harnesses / transport-agnostic" intent of
 [`actor-contract.md`](./actor-contract.md), made into a supported seam.
@@ -27,14 +28,14 @@ This is the "plural harnesses / transport-agnostic" intent of
 
 ```ts
 interface CuaExecutor {
-  observe(): Promise<CuaObservation>;   // capture current state
+  observe(): Promise<CuaObservation>; // capture current state
   execute(action: CuaAction, signal?: AbortSignal): Promise<void>; // perform one action
 }
 
 interface CuaObservation {
-  screenshot?: Buffer;                  // OPTIONAL — a state executor omits it
-  stateSignature: string;              // REQUIRED — the fallback progress key
-  appState?: Record<string, unknown>;  // structured state; preferred for progress
+  screenshot?: Buffer; // OPTIONAL — a state executor omits it
+  stateSignature: string; // REQUIRED — the fallback progress key
+  appState?: Record<string, unknown>; // structured state; preferred for progress
 }
 ```
 
@@ -51,9 +52,9 @@ wait and does not cache a previous action's position.
   persists no screenshot that turn; `counts.screenshots` stays 0, so the trace's
   `redaction.screenshots` resolves to `"n/a"`. No fabricated `Buffer.alloc(0)`
   ever reaches disk. (A vision executor still returns a frame, exactly as before.)
-- **`stateSignature` is still required.** Derive it from your own state — e.g.
+- **`stateSignature` is still required.** Derive it from your own state, e.g.
   `stableProgressKey({ route, turn, modal })` (exported from `humanish`). It is the
-  canonical fallback progress key when `appState` is absent. It is never written
+  fallback progress key when `appState` is absent. It is never written
   to the trace as text.
 - **`appState` is the preferred progress input.** When present, the loop's
   friction / no-progress detection keys off a deterministic, sorted-key,
@@ -67,9 +68,9 @@ Either is enough on its own. `appState` is preferred because `getState()` is a
 far more reliable progress signal than a quantized screenshot signature on a
 graphically dense (pixel-art) UI. `stableProgressKey(appState)`:
 
-- sorts object keys (order-independent — shuffled keys ARE NOT progress);
+- sorts object keys, so key order never counts as progress;
 - caps depth, key count, array length, string length, and total output;
-- never throws on a cyclic or huge `appState` — it degrades to a bounded value
+- never throws on a cyclic or huge `appState`; it degrades to a bounded value
   (cycles become `"[Circular]"`, over-cap nodes become markers). This is
   correctness-load-bearing: a hostile or merely large state blob cannot crash the
   loop.
@@ -77,34 +78,38 @@ graphically dense (pixel-art) UI. `stableProgressKey(appState)`:
 ## A single desktop command failure is a recoverable skipped action
 
 `execute(action)` runs against a real substrate, and the real `@e2b/desktop`
-Sandbox **throws** `CommandExitError` on **any** non-zero exit — a `press`,
+Sandbox **throws** `CommandExitError` on **any** non-zero exit. A `press`,
 `scroll`, `drag`, `moveMouse`, or `click` can exit non-zero for reasons that have
 nothing to do with the run's health (a `Ctrl+Minus` zoom keypress exiting `2` was
 the reproduced case). The loop treats one such failure as a **recoverable skipped
 action**, not a fatal error:
 
-- The per-action `execute()` call is wrapped at the loop boundary (so the recovery
-  covers every action kind uniformly). When the caught error
-  `isCommandExitError` (`command-failure.ts` — matches the SDK class name or any
-  object carrying a numeric `exitCode`), the loop records a `notice` item
-  (`status: "error"`, title `action skipped: desktop command failed`, text = the
-  public-safe action label + exit code + a redacted `stderrTail`), does **not**
-  count the action as a material action, and **continues**. The next `observe()`
-  hands the model a fresh screenshot/state to adapt to.
+- The per-action `execute()` call is wrapped at the loop boundary, in `runActionBatch`
+  (`src/actors/computer-use/loop/actions.ts`), so the recovery covers every action kind
+  uniformly. When the caught error `isCommandExitError`
+  (`src/substrates/command-failure.ts`; it matches the SDK class name or any object carrying
+  a numeric `exitCode`), the loop records a `notice` item (`status: "error"`, title `action
+skipped: desktop command failed`, text = the public-safe action label + exit code + a
+  redacted `stderrTail`), does **not** count the action as a material action, and
+  **continues**. The next `observe()` hands the model a fresh screenshot/state to adapt to.
+- An executor error declared as `action_rejected` with disposition `not_dispatched` also
+  does not end the session. The loop marks the rest of the batch `not_dispatched`, records
+  an `action rejected before dispatch` notice, and sends the model a hint with the next
+  observation.
 - **Every other error is re-thrown**, byte-identically preserving the existing
-  fatal handling: a `raceSettle` deadline still classifies as `timed_out` (or
+  fatal handling: a `raceSessionDeadline` deadline still classifies as `timed_out` (or
   `budget_reached` after material progress), a `CuaAbortError` as `harness_error`,
   and any genuine non-`CommandExitError` adapter fault as `actor_error`.
 - **No infinite loop.** A skipped action changes nothing on screen, so it is not
   progress. A run that keeps failing every action makes no progress and still
   terminates honestly through the existing idle / no-progress backstop
-  (`gave_up`) — the resilience only converts a *single flaky command* from fatal
+  (`gave_up`). The resilience only converts a _single flaky command_ from fatal
   to survivable; it never masks a genuinely stuck run.
 
 Public-safety: the notice text carries only the substrate's own stderr (tailed +
 whitespace-collapsed) and a numeric exit code, and is still run through the loop's
 `redactNarration` (known-value scrub + pattern redaction). Raw typed text, secret
-values, and machine paths never appear — the action label comes from
+values, and machine paths never appear. The action label comes from
 `describeCuaAction`, which never includes typed text.
 
 ## You need a NON-vision provider too
@@ -117,17 +122,17 @@ reasons over app state).
 
 **Provider-authoring contract:**
 
-- A **vision** provider MUST set `requiresFrame: true` (the OpenAI provider does).
-  When a `requiresFrame: true` provider is handed a screenshot-less observation,
-  the loop fails closed with a structured `harness_error` per turn — not a silent
-  crash, not a false pass.
+- A **vision** provider MUST set `requiresFrame: true` (the OpenAI provider does). When a
+  `requiresFrame: true` provider is handed a screenshot-less observation, the loop ends the
+  session with a structured `harness_error` (`missingFrame` in
+  `src/actors/computer-use/loop/ending.ts`). It neither crashes silently nor passes falsely.
 - A **state-reasoning** provider omits `requiresFrame` (defaults falsey) and reads
   `req.observation.appState`.
 
-`requiresFrame` defaulting to falsey is a known third-party-author footgun (a
-vision provider that forgets to set it would get a blank-frame crash instead of a
-clean verdict). This slice accepts it because only one vision provider exists
-today, and records it here.
+`requiresFrame` defaulting to falsey is a known third-party-author footgun (a vision
+provider that forgets to set it would get a blank-frame crash instead of a clean verdict).
+This slice accepts it because every in-tree vision provider sets it: OpenAI computer use,
+the local-agent Codex and Claude sessions, and the restricted Codex participant.
 
 ## `appState` is RUNTIME-ONLY (not evidence, in this slice)
 
@@ -136,7 +141,7 @@ today, and records it here.
 into any `ActorTraceItem`, reason, id, or count, and is **never** persisted to the
 trace. Only the derived progress key is computed in-memory and discarded.
 
-Why: the published-evidence scan catches only secret-*shaped* patterns. A
+Why: the published-evidence scan catches only secret-_shaped_ patterns. A
 structured app blob (ids, free-form state, possibly user chat or shapeless
 tokens) is exactly the "value has no shape" gap that pattern redaction cannot
 close. So this slice does not treat `appState` as an evidence surface at all.
@@ -147,13 +152,13 @@ observed each turn to drive progress detection and was NOT written to the trace.
 
 A future "appState in evidence" slice MUST route a stringified projection through
 `redaction.redactText` (and the lab's `scrubText`) AND cap / whitelist fields
-before persisting — pattern + literal redaction alone cannot sanitize an
+before persisting. Pattern + literal redaction alone cannot sanitize an
 arbitrary blob.
 
 ## Provenance is honestly UNPINNED (invariant 5)
 
 An already-running local dev server cannot be commit-pinned. The bundle does not
-silently omit a subject block — it DECLARES the absence: `subject.source:
+silently omit a subject block. It declares the absence: `subject.source:
 app-url` with `state.provenance: "undeclared"` (the app-url "absence declared"
 marker), and a `cua-lab.subject.declared` event that states the entry is a local
 dev server driven in-process, caller-provisioned and UNPINNED, with no E2B
@@ -167,16 +172,16 @@ Implement `CuaExecutor.observe()/execute()`, derive `stateSignature`/`appState`
 from your own state, pair it with a non-vision `CuaProvider`, and call
 `runComputerUseLoop`. You own the bundle/redaction wiring.
 
-### 2. `runLab` + `buildExecutor` / `buildProvider` (keeps the composition)
+### 2. `runLab` + `inProcess` / `createProvider` (keeps the composition)
 
 The supported library path keeps personas, the Observer, the evidence bundle,
 redaction, and the friction loop, while skipping E2B entirely. Start with the
-[complete runnable example](examples/state-driven-local-app/README.md), which
+[complete runnable example](../../examples/participant/README.md), which
 ships in the npm package:
 
 ```bash
 npm install humanish
-node node_modules/humanish/docs/architecture/examples/state-driven-local-app/runner.mjs
+node node_modules/humanish/examples/participant/run.mjs
 ```
 
 The example includes a real loopback app, HTTP state/action bridge, full config
@@ -188,21 +193,31 @@ on `.ok`, then narrow `runLab`'s result on `backend === "cua"` before accessing
 the CUA result. The example defines all helpers rather than requiring a consumer
 to reconstruct them.
 
-When `cuaHooks.buildExecutor` is set, `runCuaActorLab` takes a branch that NEVER
+Pass `inProcess: { executor }` and `createProvider` in `RunLabOptions`. The type requires
+`createProvider` beside `inProcess`: a state executor returns no frame, so it needs a non-vision
+provider. With `inProcess` set, `runCuaActorLab` takes a branch that NEVER
 loads the E2B module, creates a sandbox, runs `prepareDesktop`, provisions a
 clone, opens a browser, or starts a stream. `sandboxId`/`streamUrl` stay
-undefined, so `result.sandbox` is omitted — the verifiable "no E2B SDK call"
-proof.
-
-Two boot-time fail-closed guards (both BEFORE any key check, so a CLI invocation
-never sees a misleading `KEYS_MISSING` first):
-
-- `HUMANISH_CUA_LAB_EXECUTOR_NO_PROVIDER` — `buildExecutor` without `buildProvider`
-  (a state executor MUST be paired with a non-vision provider). `buildProvider`
-  ALONE is allowed — that is just a model swap on the normal E2B route.
-- `HUMANISH_CUA_LAB_LOCAL_APP_NO_EXECUTOR` — a `subject.source: local-app` config
-  run with no `buildExecutor` hook (there is no built-in in-process driver yet).
-  A structured error, never a desktop attempt.
+undefined, so `result.sandbox` is omitted. That omission is the verifiable
+"no E2B SDK call" proof.
+
+Fail-closed guards, all BEFORE any key check, so a CLI invocation never sees a misleading
+`HUMANISH_CUA_LAB_KEYS_MISSING` first:
+
+- `HUMANISH_LAB_OPTION_UNSUPPORTED`: `inProcess` without `createProvider` (from JavaScript,
+  where the type does not stop it), or on a subject other than `app-url` or `local-app`.
+  `createProvider` alone is allowed; that is a model swap on the normal E2B route.
+- `HUMANISH_CUA_LAB_FANOUT_INVALID`: `inProcess`, or the deprecated `cuaHooks.buildExecutor`,
+  with more than one participant. The planner refuses it, because fan-out gives each participant
+  its own E2B desktop and the in-process route has none.
+- `HUMANISH_CUA_LAB_LOCAL_APP_NO_EXECUTOR`: a `subject.source: local-app` config run
+  without `inProcess` (there is no built-in in-process driver yet). A structured error,
+  never a desktop attempt.
+- `HUMANISH_CUA_LAB_LOCAL_DESKTOP_MISSING`: an `app-url` lab with `execution.target: local`
+  and no local desktop. `runLab` gives a local browser study its desktop; a direct route
+  call or an in-process executor on the same lab has none.
+- `HUMANISH_CUA_LAB_EXECUTOR_NO_PROVIDER`: the deprecated `cuaHooks.buildExecutor` without
+  `cuaHooks.buildProvider`.
 
 Key gating is route-aware: the in-process route uses the caller's OWN model and
 executor, so no `OPENAI_API_KEY`/`E2B_API_KEY` is required.
@@ -224,15 +239,15 @@ Read every optional field defensively, and spread-omit optional fields
 
 ## Deferred (tracked, not shipped here)
 
-- **PR2 — a config-only deterministic `state-contract` lane.** A registered,
-  model-free lane driving a built-in `window.app.*` bridge over the existing
+- **PR2: a config-only deterministic `state-contract` route.** A registered,
+  model-free route driving a built-in `window.app.*` bridge over the existing
   `ScriptedPageLike.evaluate` primitive + a YAML step program, `scenario.mode:
-  live` gating actuation. It would be deterministic step replay, NOT
+live` gating actuation. It would be deterministic step replay, NOT
   `runComputerUseLoop`, and must not overclaim friction-loop reuse.
-- **PR3 — a `subject.contract.ref` JS-module loader.** A config-referenced module
+- **PR3: a `subject.contract.ref` JS-module loader.** A config-referenced module
   loaded and run in-process with full harness privileges is a genuinely NEW trust
-  surface with no precedent in this repo (the scripted lane loads only declarative
+  surface with no precedent in this repo (the scripted route loads only declarative
   YAML; serve commands run isolated inside the disposable E2B sandbox). It earns
   its place only behind its own clamping / trust / digest-pinning design.
-  the validated library consumer does not need it: a caller builds the bridge in its own
+  The validated library consumer does not need it: a caller builds the bridge in its own
   trusted code (entry point 2 above).

package/docs/architecture/task-protocol-support.md

@@ -5,30 +5,30 @@ participant; hidden success criteria go only to the observation tracker. A route
 that cannot carry both halves refuses the declaration before execution. Removing
 `tasks` is an explicit choice to run a mission-only study, not an automatic fallback.
 
-| Execution path | Task support | Mechanism |
-| --- | --- | --- |
-| CUA, app-url, single or per-lane fan-out | Supported | Lane composer renders goals; the CUA loop tracks observations |
-| CUA, provisioned clone or local-tree, per-lane worlds | Supported | Same lane composer and loop |
-| CUA, local-app with caller executor/provider | Supported | Same loop; the caller supplies observations |
-| CUA, desktop-cli | Supported | Same prompt and tracker; unavailable criterion inputs remain unmeasured |
-| Sequential shared-world, clone or local-tree | Rejected | Seat composer and session do not forward tasks |
-| Concurrent shared-world, provisioned or external-public | Rejected | Actor specs omit the protocol before CUA session dispatch |
-| Terminal-product | Rejected | Terminal prompt and result contract do not implement tasks |
-| Scripted-browser, local or provisioned | Rejected | Scenario steps drive the participant; no task protocol is consumed |
-| Synthetic, smoke, meta | Rejected | Lab dispatch does not pass task declarations to these engines |
-| Any second or later `actors[]` entry | Rejected | Current runners consume only the first actor; use supported first-actor lanes |
+| Execution path                                        | Task support | Mechanism                                                                                     |
+| ----------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------- |
+| CUA, app-url, one participant or fan-out              | Supported    | The participant prompt composer renders goals; the CUA loop tracks observations               |
+| CUA, provisioned clone or local-tree, separate worlds | Supported    | Same prompt composer and loop                                                                 |
+| CUA, local-app with caller executor/provider          | Supported    | Same loop; the caller supplies observations                                                   |
+| CUA, desktop-cli                                      | Supported    | Same prompt and tracker; unavailable criterion inputs remain unmeasured                       |
+| Shared-world, provisioned or external-public          | Rejected     | Actor specs omit the protocol before CUA session dispatch                                     |
+| Terminal-product                                      | Rejected     | Terminal prompt and result contract do not implement tasks                                    |
+| Scripted-browser, local or provisioned                | Rejected     | Scenario steps drive the participant; no task protocol is consumed                            |
+| Synthetic (`this-repo`)                               | Rejected     | Lab dispatch does not pass task declarations to the dry-run engine                            |
+| Any second or later `actors[]` entry                  | Rejected     | Current runners consume only the first actor; declare every participant under the first actor |
 
 Both registered CUA actors (`openai-computer-use` and `local-agent`) share the CUA
 session loop. Their task support does not depend on which provider chooses actions.
 Custom session hooks remain caller-owned implementations of that same contract;
 this preflight does not certify arbitrary hook behavior.
 
-The parser reports `HUMANISH_LAB_INVALID` with the unsupported field path. Direct
-library entry points report `HUMANISH_LAB_TASKS_UNSUPPORTED` in their existing
-failure envelopes. Refusal precedes run storage, source preparation, user hooks,
-local processes, sandbox allocation, and model calls. No task content appears in
-the error. Low-level synthetic/smoke/meta APIs accept no lab config or tasks; their
-lab declaration boundary is `runLab`.
+The parser reports `HUMANISH_LAB_INVALID` with the unsupported field path. `runLab`
+and the deprecated direct route runners report `HUMANISH_LAB_TASKS_UNSUPPORTED` in
+their failure envelopes, from `planLab` (`src/lab/plan.ts`) and each route's plan.
+Refusal precedes run storage, source preparation, user hooks, local processes,
+sandbox allocation, and model calls. No task content appears in the error. The
+deprecated synthetic API, `runDryRun`, accepts no lab config or tasks. Its lab
+declaration boundary is `runLab`.
 
 A future route gains support only after proving participant goals, hidden criteria,
 observation-backed completion, honest missing-input treatment, and per-participant