Harden A2A pipeline recovery, cleanup, and multimodal flows

pyproject.toml

@@ -74,6 +74,7 @@ dev = [
     "setuptools>=68.0",
     "wheel",
     "tomli>=2.0; python_version<\"3.11\"",
+    "pexpect>=4.9.0",
 ]
 
 [build-system]

scripts/README.md

@@ -9,6 +9,8 @@ repository root with `uv run python ...` unless a script-specific README says ot
 | --- | --- |
 | `a2a/debugger.py` | Web debugger/client for A2A pipeline streams. |
 | `a2a/debugger.md` | Manual usage notes for the A2A debugger. |
+| `a2a/selling_console.py` | Selling pipeline console local HTTP server; proxies text-only UI requests to an A2A server. |
+| `a2a/selling_console_web/` | Static Selling Console frontend. It renders pipeline progress, candidate cards, chat, and debug panels; image input coverage belongs to `a2a/debugger.py`. |
 | `a2a/e2e/` | A2A session recovery end-to-end scenario runner, shared helpers, and result notes. |
 | `a2a/smoke/test_a2a_vpc.py` | Small manual smoke script for A2A VPC/pipeline behavior. |
 | `acp/smoke/test_acp_vpc.py` | Small manual smoke script for ACP VPC behavior. |
@@ -17,14 +19,26 @@ repository root with `uv run python ...` unless a script-specific README says ot
 | `observability/local_observe/` | Local observe server implementation and static web UI. |
 | `observability/local_observe.md` | Manual usage notes for the local observe tool. |
 | `rendering/test_diagram_render.py` | Manual diagram rendering check. |
+| `repl/e2e/` | Real PTY-driven REPL pipeline end-to-end scenario runner. POSIX-only because it uses `pexpect`. |
 
 ## Common Commands
 
 ```bash
 uv run python scripts/a2a/debugger.py --help
+PATH="$HOME/.local/bin:$PATH" \
+uv run python scripts/a2a/selling_console.py --port 41980 \
+  --default-server-url http://127.0.0.1:41299 \
+  --default-cwd "$PWD"
 uv run python scripts/a2a/e2e/run_recovery_scenarios.py --help
 uv run python scripts/observability/local_observe.py --help
+uv run python scripts/repl/e2e/run_pipeline_scenarios.py --help
 ```
 
+`scripts/repl/e2e/run_pipeline_scenarios.py` writes artifacts under the system temporary directory by default and is intended for manual or smoke validation. It is not part of `make test`; the unit tests only cover helper behavior. The real PTY runner depends on the POSIX-only `pexpect` development dependency.
+
+The root `conftest.py` includes a tiktoken isolation fixture so tests do not read or write the developer's real encoding cache. Keep new tests on that fixture path rather than using the user cache directly.
+
+Cleanup ledger temporary files use a leading dot in their generated names only as a cosmetic convention. Correctness relies on atomic replace, retries, and ledger validation, not on Unix hidden-file behavior.
+
 Pytest tests for these helpers live under `tests/`; the executable scripts here are kept for local debugging,
 manual validation, and real end-to-end runs.

scripts/a2a/debugger.md

@@ -30,6 +30,33 @@ uv run python scripts/a2a/debugger.py --port 41880 \
   --default-cwd "$PWD"
 ```
 
+`--default-cwd` is sent to the A2A server as `metadata.iac_code.cwd` on each
+message. It is the server-side workspace for the task, not merely the debugger's
+own working directory.
+
+The A2A server validates this path before running the agent. By default, the
+server accepts its own startup directory and Python's temp directory. If
+`--default-cwd` points inside an allowed root and the directory does not exist
+yet, the server may create it. The request is rejected with
+`Invalid A2A workspace metadata.` when the resolved path escapes the allowed
+root, cannot be created, or cannot be used as a directory.
+
+Use one of these patterns:
+
+```bash
+# Start the debugger with a cwd accepted by the already-running server.
+uv run python scripts/a2a/debugger.py --port 41880 \
+  --default-server-url http://127.0.0.1:41299 \
+  --default-cwd "/path/to/server/workspace"
+```
+
+```bash
+# Or explicitly allow the debugger/client workspace when starting the server.
+IACCODE_A2A_ALLOWED_CWDS="/path/to/server/workspace:/path/to/client/workspace" \
+IAC_CODE_MODE=pipeline \
+uv run iac-code a2a --transport http --host 127.0.0.1 --port 41299
+```
+
 Open:
 
 ```text
@@ -67,3 +94,7 @@ uv run python scripts/a2a/debugger.py --port 41880 \
 - The debugger is a local development tool and does not provide authentication.
 - `contextId` identifies the conversation; `taskId` identifies one A2A task.
 - After `pipeline_handoff_ready`, follow-up messages normally start a new normal-chat task in the same context.
+- Image input accepts supported image MIME types only: `image/png`, `image/jpeg`, `image/webp`, and `image/gif`.
+- A2A part parser limits: text inline/raw and text `file://` parts are limited to 1 MiB; binary inline/raw/data parts are limited to 5 MiB; binary `file://` parts are limited to 25 MiB. Debugger uploads are limited to 5 MiB per image.
+- `file://` image inputs must resolve to an existing local file that is both under the request cwd and under a configured A2A allowed cwd root. Local URLs outside either boundary are rejected.
+- The A2A debugger sends image parts. The Selling Console web UI currently sends text input only.