feat(integrations): discover Codex models through bounded pagination

.github/workflows/ci.yml

@@ -163,6 +163,11 @@ jobs:
         BAND_ALLOW_MISSING_FRAMEWORKS: "1"
       run: uv run --all-packages pytest tests/e2e/baseline/ --collect-only -q --no-cov
 
+    - name: Run CrewAI activity tests
+      env:
+        BAND_ALLOW_MISSING_FRAMEWORKS: "1"
+      run: uv run --all-packages pytest tests/integrations/crewai/activity/
+
     - name: Run crewai tests
       env:
         # dev-crewai venv lacks langgraph/anthropic/parlant/pydantic-ai/etc.;
@@ -171,7 +176,7 @@ jobs:
       # Only the tests that *need* this venv. Every other crewai test fakes the
       # package through sys.modules, so the `test` job above already runs it and
       # a second pass here would add no signal — just a path to forget.
-      # tests/framework_conformance/test_crewai_job_coverage.py keeps this honest.
+      # tests/framework_conformance/crewaicoverage/ keeps this honest.
       run: |
         uv run --all-packages pytest \
           tests/adapters/test_crewai_flow_phase3.py \
@@ -233,6 +238,12 @@ jobs:
         BAND_TEST_EXTRA: "dev-strands-nooa"
       run: uv run --all-packages pytest tests/e2e/baseline/ --collect-only -q --no-cov
 
+    - name: Run Strands activity tests
+      env:
+        BAND_ALLOW_MISSING_FRAMEWORKS: "1"
+        BAND_TEST_EXTRA: "dev-strands-nooa"
+      run: uv run --all-packages pytest tests/adapters/strands/activity/
+
     - name: Run Strands and NOOA tests
       env:
         # dev-strands-nooa lacks modern framework packages;
@@ -302,6 +313,11 @@ jobs:
         BAND_ALLOW_MISSING_FRAMEWORKS: "1"
       run: uv run --all-packages pytest tests/e2e/baseline/ --collect-only -q --no-cov
 
+    - name: Run Parlant activity tests
+      env:
+        BAND_ALLOW_MISSING_FRAMEWORKS: "1"
+      run: uv run --all-packages pytest tests/integrations/parlant/activity/
+
     - name: Run parlant tests
       env:
         # dev-parlant venv lacks langgraph/anthropic-adapter/pydantic-ai/etc.;
@@ -310,7 +326,7 @@ jobs:
       # Only the tests that *need* this venv. Every other parlant test fakes the
       # package through sys.modules, so the `test` job above already runs it and
       # a second pass here would add no signal — just a path to forget.
-      # tests/framework_conformance/test_parlant_job_coverage.py keeps this honest.
+      # tests/framework_conformance/parlantcoverage/ keeps this honest.
       run: |
         uv run --all-packages pytest \
           tests/integrations/parlant/test_catalog.py \

README.md

@@ -211,6 +211,28 @@ adapter = GeminiAdapter(GeminiAdapterConfig(model="gemini-3.8-flash"))
 
 Use [examples/run_agent.py](examples/run_agent.py) when you want one command that can switch between LangGraph, Pydantic AI, Anthropic, Claude SDK, Parlant, CrewAI, Codex, A2A bridge, and A2A gateway. Use the per-framework directories under [examples/](examples/) when you want the adapter-specific setup.
 
+### Host-side Harness Probes
+
+`await adapter.preflight(timeout_s=60)` reports a harness handshake as a
+`PreflightResult` (`ok`, `reason`, `remedy`). A successful handshake does not prove
+that the account can run inference. Adapters without a standalone handshake
+implementation explicitly report that it is unsupported.
+
+`await adapter.probe_models(timeout_s=60)` discovers a canonical `ModelCatalog`
+without creating or selecting a Band room. Unsupported adapters raise
+`BandConfigError`; an empty catalog is not a substitute for unsupported discovery.
+The existing room-facing `list_models` hook remains separate.
+
+Catalog entries preserve advertised provider and default metadata. An entry's
+`efforts=None` means the harness did not report effort support; `efforts=()` means
+it explicitly offers none. `current_model` is populated only when the harness
+reports an actual selection.
+
+Timeouts bound how long a caller waits, not ownership of a partially started
+transport. Always call `await adapter.cleanup_all()` when disposing of an adapter.
+An incomplete close raises `CleanupIncompleteError` and retains its resources for
+a later cleanup attempt rather than reporting successful disposal.
+
 ### Process Signals
 
 `agent.run()` and `agent.run_forever()` stop the agent on SIGTERM/SIGINT and restore the process's previous handlers when they return. A host that owns its process signals (a launchd/systemd service, a desktop app, a test runner) passes `install_signal_handlers=False` and calls `agent.stop()` from its own handler; `run_forever` then returns. `GracefulShutdown` is a ready-made handler that does this, and `run_with_graceful_shutdown(agent)` wraps it. Put `GracefulShutdown` outside `agent` so its handlers are registered before `start()` and a mid-initialize SIGTERM can still tear down:

docs/adapters/codex.md

@@ -8,6 +8,86 @@ see [idle room resource retention](../idle-room-release.md).
 
 For existing integrations, follow the [SDK 4.x to 5.x migration](../acp.md#upgrading-from-sdk-4x-to-5x).
 
+## Host preflight
+
+`await adapter.preflight(timeout_s=60.0)` launches a throwaway app-server using
+the adapter's `codex_command`, `codex_env`, client name/title/version,
+`experimental_api` and `skill_roots`. It sends `initialize` and `account/read`
+without creating a Codex thread, spending a model turn, or claiming a Band room
+or workspace.
+
+The result is a `PreflightResult` with `ok`, `reason` and `remedy`. A missing
+account fails only when Codex explicitly reports `requiresOpenaiAuth=true`;
+an unsupported or refused `account/read` is not proof that login is missing.
+A passed handshake is not proof of provider authentication, subscription or
+inference entitlement.
+
+Room and standalone-probe transport diagnostics omit raw app-server stdout,
+stderr and exception text, including cleanup that finishes after caller
+cancellation. Malformed frames report transport, type and length; full queues
+report only the dropped event kind. Original cleanup errors remain available to
+callers and retries.
+
+```python notest
+from band.adapters.codex import CodexAdapter, CodexAdapterConfig
+
+adapter = CodexAdapter(CodexAdapterConfig())
+result = await adapter.preflight(timeout_s=30)
+```
+
+The timeout bounds handshake/RPC work and a separate cleanup wait. Cancellation
+propagates. Cleanup failures raise `CleanupIncompleteError` instead of reporting
+a successful or ordinary failed preflight, and the adapter retains the client,
+including a partially created process or Windows job. Keep that adapter and
+retry `await adapter.cleanup_all()` to join or retry cleanup. Shutdown attempts
+both probe and room cleanup even when either fails. A custom-tool callback
+requesting shutdown can receive a retryable pending-cleanup error while its own
+turn unwinds; it is not cancelled by that stop. Successful calls close their
+throwaway process before returning; a second preflight starts a fresh one.
+
+Standalone probes set the transport's `graceful_shutdown=False`. After joining
+any pending subprocess creation, their retained close owner closes stdin and
+requests immediate owned POSIX termination before ordinary settlement. The default
+`graceful_shutdown=True` leaves room settlement policy unchanged. Process exit and
+reader settlement still require confirmation; an unfinished cleanup remains owned
+for retry within the existing reporting bound.
+
+## Host model discovery
+
+`await adapter.probe_models(timeout_s=60.0)` uses the same owned throwaway
+app-server handshake, including the configured skill roots, then paginates
+`model/list`. It creates no thread or turn and leaves existing rooms, their
+selected models and their workspace claims unchanged.
+
+The result is the canonical `band.core.model_catalog.ModelCatalog`. Its visible
+`ModelChoice` entries preserve Codex IDs, display names, default-model flags,
+advertised reasoning efforts and default efforts. Provider identity is not
+reported by `model/list`, so `provider` remains `None`, including with custom
+providers. Unknown efforts remain `None`; an explicitly empty effort list becomes
+`()`. A default-model flag does not invent `current_model`: a standalone app-server
+has no selected room model.
+
+```python notest
+catalog = await adapter.probe_models(timeout_s=30)
+model_ids = catalog.model_ids
+default_choices = tuple(choice for choice in catalog.models if choice.is_default)
+```
+
+A successful empty catalog has `models=()`. Unsupported or failed RPCs raise
+instead of masquerading as an empty catalog. Cancellation and failed cleanup
+have the same ownership and retry behavior as preflight.
+
+One paginator also serves automatic room model selection, `/model list` and the
+current model's reasoning-effort lookup. It follows opaque `nextCursor` values,
+rejects repeated cursors and stops after 50 pages rather than returning a
+misleading partial catalog. Room listings use `retention.transition_timeout_s`
+as their RPC budget; explicit host discovery uses its `timeout_s` budget.
+Automatic selection retains its existing fallback to the SDK default on a
+failed or empty listing, while an explicitly configured or room-selected model
+is not replaced by a catalog default.
+
+## Room behavior
+
 - **Where settings go.** Runtime settings live in `CodexAdapterConfig`, which
   forbids unknown fields, so a misplaced `emit=` or a typo fails construction.
   `emit=`, `capabilities=` and `additional_tools=` go on `CodexAdapter`.
@@ -38,9 +118,11 @@ For existing integrations, follow the [SDK 4.x to 5.x migration](../acp.md#upgra
   On Windows, the client owns the helper and its process-tree job from startup
   through cleanup. It starts the interpreter image directly so a virtual-environment
   launcher cannot hide another helper process. Cleanup confirms the helper has
-  exited before terminating and draining the job; an empty job alone does not
-  establish helper exit.
-  Failed cleanup retains that same owner and job for retry.
+  exited, seals the job against new children, and retains member process handles
+  before requesting termination. It waits for those handles to signal physical
+  exit as well as empty job accounting; accounting alone does not prove directory
+  and file handles were released. Failed cleanup retains that same owner, job,
+  and any pending process handles for retry.
 - **Leaving is final.** Leaving a room stops it admitting work at once. A
   leave that fails or runs over keeps the process, thread and workspace claim,
   and the room refuses work until a retried leave succeeds; a later rejoin

docs/turn-outcome.md

@@ -424,3 +424,15 @@ once. It does not rewrite the original delivery's settled acknowledgement.
 Explicit interruption invalidates its activity; leave and shutdown clear the
 indicator while adapter residency retains responsibility for released workers.
 The authoritative idle report finishes before a replacement reports working.
+
+`SessionConfig.enable_working_state` controls both the indicator and activity
+detail, independently of chat narration and tool capabilities. Changes and
+keep-alives share one serialized reporter. The duration cap stops both kinds
+of refresh without cancelling provider work; actual completion still clears.
+
+Detail compatibility is learned from the `X-API-Version` header the platform
+puts on every activity response. Reports stay boolean until a response in the
+process advertises agent API 1.25.0 or later; a missing or older version keeps
+boolean reporting. A detail-bearing HTTP 422 permanently disables detail across
+all links in the process and retries that report once without detail, within
+its original deadline.

src/band/adapters/agno.py

@@ -37,6 +37,7 @@
     is_image_passthrough_result,
     redact_tool_call_args,
 )
+from band.runtime.working_state import end_tool_activity, report_tool_activity
 
 try:
     from agno.models.message import Message
@@ -451,10 +452,7 @@ async def _run_agent(
     ) -> RunOutput | None:
         """Run the Agno agent with the room's tools bound for this call.
 
-        When ``Emit.TOOL_CALLS`` is enabled the run is streamed so tool_call /
-        tool_result events are emitted *as each tool runs* (see
-        :meth:`_run_streamed`), matching the other adapters' live reporting.
-        Otherwise it runs non-streaming, exactly as before.
+        Consume provider progress as it happens, independently of chat narration.
         """
         try:
             agent = self._agent
@@ -469,17 +467,14 @@ async def _run_agent(
                 session_id,
             )
             with _bind_room_tools(tools):
-                if Emit.TOOL_CALLS in self.features.emit:
-                    response = await self._run_streamed(
-                        agent,
-                        messages,
-                        tools,
-                        session_id=session_id,
-                        room_id=room_id,
-                        msg_id=msg_id,
-                    )
-                else:
-                    response = await agent.arun(input=messages, session_id=session_id)
+                response = await self._run_streamed(
+                    agent,
+                    messages,
+                    tools,
+                    session_id=session_id,
+                    room_id=room_id,
+                    msg_id=msg_id,
+                )
             # Agno swallows run exceptions into a normal-looking return value
             # (status=error); surface it so the shared except path below treats
             # the turn as failed rather than as a silent empty reply.
@@ -532,9 +527,14 @@ async def _run_streamed(
                 # None, which would read as a successful turn with no output.
                 raise AgnoRunError(_error_summary(item.content))
             else:
-                await self._emit_stream_event(
-                    item, tools, room_id=room_id, msg_id=msg_id
-                )
+                if isinstance(item, ToolCallStartedEvent) and item.tool is not None:
+                    await report_tool_activity(tools, item.tool.tool_name or "")
+                elif isinstance(item, ToolCallCompletedEvent):
+                    await end_tool_activity(tools)
+                if Emit.TOOL_CALLS in self.features.emit:
+                    await self._emit_stream_event(
+                        item, tools, room_id=room_id, msg_id=msg_id
+                    )
         return final
 
     def _persist_turn(self, room_id: str, response: RunOutput) -> None: