chore(agent): remove dead code from agent-workflows

docs/design/agent-workflows/documentation/adapters/agenta.md

@@ -62,8 +62,7 @@ instructions are the `AGENTS.md`. An author's own `system` / `append_system` (vi
 
 `agenta` is a harness option alongside `pi` and `claude` (the playground dropdown, the
 `harness` field). The deployed service path routes it through `SandboxAgentBackend`, which
-drives Pi over ACP and layers the Agenta persona and tools on top. `InProcessPiBackend`
-remains available for local/example contrast runs.
+drives Pi over ACP and layers the Agenta persona and tools on top.
 
 ## On the sandbox-agent (ACP) path
 

docs/design/agent-workflows/documentation/adapters/claude-code.md

@@ -102,5 +102,5 @@ same `SandboxAgentBackend` drives it. It also exercises the capability-driven br
 built on: tools over MCP because it reports `mcpTools`, a permission answer because it gates
 tools, and event-stream tracing because it does not self-instrument. A future harness that
 sandbox-agent can drive would reuse this exact path. A future harness that sandbox-agent cannot drive would
-instead get its own backend beside `SandboxAgentBackend` and `InProcessPiBackend`, behind the same
+instead get its own backend beside `SandboxAgentBackend`, behind the same
 `/run` contract.

docs/design/agent-workflows/documentation/adapters/pi.md

@@ -161,7 +161,7 @@ And auth comes from the provider key in the sandbox env when present, or from an
 
 ## The in-process engine
 
-The in-process Pi engine (`engines/pi.ts`, selected by the `InProcessPiBackend`) skips sandbox-agent
+The in-process Pi engine (`engines/pi.ts`, reached with `backend: "pi"`) skips sandbox-agent
 entirely. It drives Pi's `createAgentSession` directly, with everything in memory: AGENTS.md
 injected through the resource loader, the session and settings managers in memory, and a
 throwaway working directory. It registers the same tools as Pi `customTools` through

docs/design/agent-workflows/documentation/architecture.md

@@ -72,12 +72,13 @@ The deployed handler always uses `SandboxAgentBackend`. `select_backend` in
 of harness. So `pi`, `claude`, and `agenta` all run through the sandbox-agent daemon over ACP
 on the deployed path.
 
-`InProcessPiBackend` exists and works, but the service never selects it. It is the simplest
-backend and the reference to read when writing a new one. It is also the engine the `pi`
-engine file (`services/agent/src/engines/pi.ts`) drives directly. The sidecar still has a `pi`
-engine: a `/run` request with `backend: "pi"` runs Pi in-process inside the sidecar without
-the daemon. The deployed Python service does not send that; standalone SDK scripts and tests
-can.
+The sidecar still has an in-process `pi` engine (`services/agent/src/engines/pi.ts`): a
+`/run` request with `backend: "pi"` runs Pi in-process inside the sidecar without the daemon.
+The deployed Python service never sends that. The SDK used to ship an `InProcessPiBackend`
+adapter that drove this engine, presented as a "reference backend", but it was a confusing
+POC and was removed. A test-only helper
+(`sdks/python/oss/tests/pytest/integration/agents/_in_process_backend.py`) still drives the
+`pi` engine in the transport round-trip test.
 
 This split matters when reading the code. There are two `pi` paths:
 
@@ -93,9 +94,12 @@ The SDK runtime models engines as `Backend` adapters
 | Backend | Status | Harnesses | Sandbox support | Notes |
 | --- | --- | --- | --- | --- |
 | `SandboxAgentBackend` | Implemented | `pi`, `claude`, `agenta` | `local`, `daytona` | The deployed path. Drives `engines/sandbox_agent.ts`: starts the sandbox-agent daemon and an ACP adapter. `supported_harnesses` is `{pi, claude, agenta}` (`adapters/sandbox_agent.py:121`). |
-| `InProcessPiBackend` | Implemented | `pi`, `agenta` | `local` only | Drives `engines/pi.ts` (in-process Pi). Not selected by the deployed service; used by standalone scripts and tests (`adapters/in_process.py:119`). |
 | `LocalBackend` | Not implemented | Intended: `pi`, `claude` | Local machine | Public class exists; `create_sandbox` and `create_session` raise `NotImplementedError` (`adapters/local.py:34`). |
 
+The sidecar's in-process `pi` engine (`engines/pi.ts`) is still reachable with
+`backend: "pi"`, but the SDK no longer ships a backend adapter for it. A test-only helper
+drives it in the transport round-trip test.
+
 ## Harnesses
 
 The SDK runtime models agent-specific behavior as `Harness` adapters

docs/design/agent-workflows/documentation/ground-truth.md

@@ -13,7 +13,7 @@ this page and the referenced code as the source of truth.
 | Browser protocol adapter | `sdks/python/agenta/sdk/agents/adapters/vercel/` | Converts Vercel `UIMessage` input and emits Vercel UI Message Stream parts. |
 | SDK runtime DTOs | `sdks/python/agenta/sdk/agents/dtos.py` | Defines `AgentConfig`, `RunSelection`, `SessionConfig`, messages, events, capabilities, and harness configs. |
 | SDK runtime ports | `sdks/python/agenta/sdk/agents/interfaces.py` | Defines `Backend`, `Environment`, `Sandbox`, `Session`, `Harness`, `SessionStore`, and `NoopSessionStore`. |
-| Backend adapters | `sdks/python/agenta/sdk/agents/adapters/in_process.py`, `sandbox_agent.py`, `local.py` | Implement in-process Pi and sandbox-agent backends. `LocalBackend` is a stub. |
+| Backend adapters | `sdks/python/agenta/sdk/agents/adapters/sandbox_agent.py`, `local.py` | Implement the sandbox-agent backend. `LocalBackend` is a stub. |
 | Harness adapters | `sdks/python/agenta/sdk/agents/adapters/harnesses.py` | Maps neutral session config into Pi, Claude, and Agenta harness-specific config. |
 | Runner wire | `sdks/python/agenta/sdk/agents/utils/wire.py`, `services/agent/src/protocol.ts` | Keeps the Python and TypeScript `/run` payloads in sync. |
 | Runner transports | `sdks/python/agenta/sdk/agents/utils/ts_runner.py`, `services/agent/src/server.ts`, `services/agent/src/cli.ts` | Send one-shot JSON or live NDJSON records to and from the runner. |
@@ -35,8 +35,9 @@ this page and the referenced code as the source of truth.
 - The deployed service always uses `SandboxAgentBackend` (`services/oss/src/agent/app.py:49`).
   It does not select a backend per harness.
 - `SandboxAgentBackend` supports `pi`, `claude`, and `agenta` on local or Daytona.
-- `InProcessPiBackend` supports `pi` and `agenta` on local. It is the reference backend and is
-  not selected by the deployed service.
+- The sidecar's in-process `pi` engine (`engines/pi.ts`) is still reachable with
+  `backend: "pi"`, but the SDK no longer ships a backend adapter for it. A test-only helper
+  drives it in the transport round-trip test.
 - `PiHarness`, `ClaudeHarness`, and `AgentaHarness` exist and validate backend support.
 - Pi `systemPrompt` and `appendSystemPrompt` overrides are delivered on both the in-process Pi
   path and the sandbox-agent Pi path. The sandbox-agent engine writes `SYSTEM.md` /

docs/design/agent-workflows/documentation/ports-and-adapters.md

@@ -11,7 +11,7 @@ The SDK runtime lives under `sdks/python/agenta/sdk/agents/`.
 | --- | --- | --- |
 | DTOs | `dtos.py` | `AgentConfig`, `RunSelection`, `SessionConfig`, messages, events, capabilities, and harness-specific config models. |
 | Ports | `interfaces.py` | `Backend`, `Environment`, `Sandbox`, `Session`, `Harness`, `SessionStore`. |
-| Backend adapters | `adapters/in_process.py`, `adapters/sandbox_agent.py`, `adapters/local.py` | Engines that can run a harness. |
+| Backend adapters | `adapters/sandbox_agent.py`, `adapters/local.py` | Engines that can run a harness. |
 | Harness adapters | `adapters/harnesses.py` | Per-harness mapping from neutral session config to harness-specific config. |
 | Browser adapter | `adapters/vercel/` | Vercel `UIMessage` input and Vercel UI Message Stream output. |
 | Runner plumbing | `utils/wire.py`, `utils/ts_runner.py` | `/run` serialization and runner transports. |
@@ -30,10 +30,12 @@ Current backends:
 
 - `SandboxAgentBackend`: implemented, supports `pi`, `claude`, and `agenta`, local or Daytona.
   This is the backend the deployed service always uses (`services/oss/src/agent/app.py:49`).
-- `InProcessPiBackend`: implemented, supports `pi` and `agenta`, local only. The reference
-  backend; not selected by the deployed service.
 - `LocalBackend`: planned, public class exists, methods raise.
 
+The sidecar's in-process `pi` engine (`engines/pi.ts`) is still reachable with `backend: "pi"`,
+but the SDK no longer ships a backend adapter for it; a test-only helper drives it in the
+transport round-trip test.
+
 ### Environment
 
 `Environment` wraps a backend and owns sandbox policy. The default is one sandbox per
@@ -53,7 +55,7 @@ Current harnesses:
   permission policy.
 - `AgentaHarness` is Pi with forced Agenta policy layered on top: a base AGENTS.md preamble,
   a forced persona, forced tools, and forced skills (`adapters/agenta_builtins.py`). It runs
-  on both `SandboxAgentBackend` and `InProcessPiBackend`.
+  on `SandboxAgentBackend`.
 
 ### Session
 

docs/design/agent-workflows/scratch/dead-code-report.md

@@ -2,6 +2,31 @@
 
 Date: 2026-06-23. Read-only investigation. No code changed.
 
+## Actions taken (2026-06-23, after review)
+
+Mahmoud reviewed this report inline. Done in this pass:
+
+- Deleted: `shutdownTracing` (otel.ts), `is_import_safe` (running/sandbox.py),
+  `engines/running/registry.py` (whole file), `tools/wire.py` (`tool_spec_to_wire` /
+  `tool_specs_to_wire`, whole file), `parse_tool_configs` (parsing.py),
+  `agents/ui_messages.py` (whole file), and `services/oss/src/agent/client.py` (whole file).
+  All `__init__` re-exports for these were removed too.
+- `InProcessPiBackend`: removed from the public SDK (it was a confusing POC "reference
+  backend"). The class moved to a test-only helper
+  (`sdks/python/oss/tests/pytest/integration/agents/_in_process_backend.py`) so the transport
+  round-trip integration test still runs. Public exports, the two unit tests, and the design
+  docs were updated. If you want it gone entirely (dropping that integration test), say so.
+- Kept on request: the `engines/sandbox_agent.ts:74-75` test re-exports, `LocalBackend`,
+  `ClaudeHarness` / `AgentaHarness`.
+- Left for later (your question, not a delete): the service re-export shims `secrets.py`,
+  `tools/secrets.py`, `tools/gateway.py`. Confirmed the agent does NOT use them at runtime
+  (`app.py` resolves via `agenta.sdk.agents.platform` and `tools/resolver`); they are
+  backward-compat shims used only by tests. Deletable once those tests repoint.
+- Not touched (unmarked low/cosmetic): `mcp_server_to_wire` singular, `MessageContent`,
+  the `coerce_tool_configs` diagnostics surface.
+
+The original report follows.
+
 ## What "the code is not really doing anything" means here
 
 The premise is partly true and partly false. The live runtime path is wired and
@@ -33,7 +58,7 @@ surface `agenta/__init__.py`.
 
 ## SERVICE - `services/oss/src/agent/`
 
-### DEAD (high): `client.py` whole file
+### DEAD (high): `client.py` whole file [[[delete]]]
 
 - File: `services/oss/src/agent/client.py` (`agenta_api_base`, `request_authorization`,
   `TOOLS_TIMEOUT`).
@@ -47,7 +72,7 @@ surface `agenta/__init__.py`.
   file.
 - Action: delete.
 
-### DEAD (medium): `secrets.py` and `tools/secrets.py` and `tools/gateway.py` shims (tests-only)
+### DEAD (medium): `secrets.py` and `tools/secrets.py` and `tools/gateway.py` shims (tests-only)  [[[doesnt the agent use these?]]]
 
 - Files: `services/oss/src/agent/secrets.py` (`resolve_harness_secrets`,
   `_PROVIDER_ENV_VARS`), `services/oss/src/agent/tools/secrets.py`
@@ -85,7 +110,7 @@ surface `agenta/__init__.py`.
 
 ---
 
-## RUNNER - `services/agent/src/` (TypeScript sandbox-agent)
+## RUNNER - `services/agent/src/` (TypeScript sandbox-agent) 
 
 Entry points confirmed via `package.json`: `cli.ts` (`run:cli`) and `server.ts` (`serve`).
 Engine dispatch is `backend === "pi" ? runPi(...) : runSandboxAgent(...)` at
@@ -94,7 +119,7 @@ SDK `InProcessPiBackend` sets `AGENT_BACKEND=pi`, `SandboxAgentBackend` sets
 `sandbox-agent`. Keep both engines, both tool executors, all of `tools/`, `protocol.ts`,
 `responder.ts`.
 
-### DEAD (high): `shutdownTracing`
+### DEAD (high): `shutdownTracing`  [[[delete]]]
 
 - File: `services/agent/src/tracing/otel.ts:179`, function `shutdownTracing`.
 - Verdict: dead. Zero callers in `src`, `tests`, or the Python side.
@@ -104,7 +129,7 @@ SDK `InProcessPiBackend` sets `AGENT_BACKEND=pi`, `SandboxAgentBackend` sets
   `docs/.../archive/wp-1-pi-tracing/poc/`, a different file.
 - Action: delete.
 
-### DEAD (medium): test-only re-export aliases on the engine surface
+### DEAD (medium): test-only re-export aliases on the engine surface  [[dont delete]]
 
 - File: `services/agent/src/engines/sandbox_agent.ts:74-75`. Re-exports `buildTurnText`,
   `messageTranscript` (from `./sandbox_agent/transcript.ts`) and `toAcpMcpServers` (from
@@ -136,7 +161,7 @@ SDK `InProcessPiBackend` sets `AGENT_BACKEND=pi`, `SandboxAgentBackend` sets
 
 ## SDK - `sdks/python/agenta/sdk/agents/` and `sdk/engines/running/`
 
-### DEAD (high): broken `engines/running/registry.py`
+### DEAD (high): broken `engines/running/registry.py`  [[[check who added it and why]]]
 
 - File: `sdks/python/agenta/sdk/engines/running/registry.py` (only symbol
   `exact_match_v1`).
@@ -150,15 +175,15 @@ SDK `InProcessPiBackend` sets `AGENT_BACKEND=pi`, `SandboxAgentBackend` sets
   imports `engines.running`.
 - Action: delete file.
 
-### DEAD (high): `is_import_safe`
+### DEAD (high): `is_import_safe` [[[delete]]]
 
 - File: `sdks/python/agenta/sdk/engines/running/sandbox.py:9`, function `is_import_safe`.
 - Verdict: dead. Zero callers.
 - How I checked: `git grep "is_import_safe"` returns only the definition. The live member
   in that file is `execute_code_safely` (called from `handlers.py`).
 - Action: delete function.
 
-### DEAD (high): `tool_spec_to_wire` and `tool_specs_to_wire`
+### DEAD (high): `tool_spec_to_wire` and `tool_specs_to_wire`  [[[[deelete]]]]
 
 - File: `sdks/python/agenta/sdk/agents/tools/wire.py:10,14`.
 - Verdict: dead standalone functions. The live serialization path uses the
@@ -167,7 +192,7 @@ SDK `InProcessPiBackend` sets `AGENT_BACKEND=pi`, `SandboxAgentBackend` sets
   re-export in `tools/__init__.py:38,65-66`. No real caller.
 - Action: delete the functions and the `__init__` re-exports.
 
-### DEAD (high): `ui_messages.py` whole module
+### DEAD (high): `ui_messages.py` whole module  [[[this is strange i thought this was our internal represenation]]]
 
 - File: `sdks/python/agenta/sdk/agents/ui_messages.py`.
 - Verdict: dead compat shim re-exporting `from_ui_messages`/`to_ui_message`/
@@ -179,7 +204,7 @@ SDK `InProcessPiBackend` sets `AGENT_BACKEND=pi`, `SandboxAgentBackend` sets
   `ui_message_stream = agent_run_to_vercel_parts` in `adapters/vercel/messages.py:218-219`
   and `adapters/vercel/stream.py:216` have no real callers either and can go with it.
 
-### DEAD (high): `parse_tool_configs` (plural-of-the-wrong-name)
+### DEAD (high): `parse_tool_configs` (plural-of-the-wrong-name)  [[[[double check but then delete if so ]]]]
 
 - File: `sdks/python/agenta/sdk/agents/tools/parsing.py`.
 - Verdict: dead. Zero references anywhere, not even tests.
@@ -190,7 +215,7 @@ SDK `InProcessPiBackend` sets `AGENT_BACKEND=pi`, `SandboxAgentBackend` sets
   (singular) are tests-only plus internal `compat.py` use; keep for now or fold into test
   fixtures (medium, human call).
 
-### DEAD-ish (medium): `InProcessPiBackend` (tests-only, but a public export)
+### DEAD-ish (medium): `InProcessPiBackend` (tests-only, but a public export)  [[[lets remove that part of the code it was a poc and it is now confusing]]]
 
 - File: `sdks/python/agenta/sdk/agents/adapters/in_process.py`, class `InProcessPiBackend`.
 - Verdict: never selected by the service. Constructed only in tests
@@ -203,7 +228,7 @@ SDK `InProcessPiBackend` sets `AGENT_BACKEND=pi`, `SandboxAgentBackend` sets
   but only tests and explicit non-default callers reach it. Keep as a documented reference
   backend or demote to a test fixture.
 
-### DEAD (medium): `LocalBackend` (never instantiated, unimplemented)
+### DEAD (medium): `LocalBackend` (never instantiated, unimplemented) [[[keep]]]
 
 - File: `sdks/python/agenta/sdk/agents/adapters/local.py`, class `LocalBackend`.
 - Verdict: never instantiated anywhere; every method raises `NotImplementedError`.
@@ -212,7 +237,7 @@ SDK `InProcessPiBackend` sets `AGENT_BACKEND=pi`, `SandboxAgentBackend` sets
 - Action: keep-but-wire (a tracked Phase 3/4 stub) or delete if no longer planned. Dead
   today by design.
 
-### REACHABLE-BUT-NEVER-DEFAULT (medium): `ClaudeHarness`, `AgentaHarness` (+ `agenta_builtins.py`)
+### REACHABLE-BUT-NEVER-DEFAULT (medium): `ClaudeHarness`, `AgentaHarness` (+ `agenta_builtins.py`) [[[keeep]]]
 
 - File: `sdks/python/agenta/sdk/agents/adapters/harnesses.py:77,105`, plus the forced
   tools/skills machinery in `adapters/agenta_builtins.py`.

sdks/python/agenta/__init__.py

@@ -60,7 +60,6 @@
     AgentConfig,
     ClaudeHarness,
     Environment,
-    InProcessPiBackend,
     LocalBackend,
     PiHarness,
     SandboxAgentBackend,

sdks/python/agenta/sdk/agents/__init__.py

@@ -5,7 +5,7 @@
 - ``dtos.py`` — data contracts (``AgentConfig``, ``SessionConfig``, ``Message``, ...).
 - ``interfaces.py`` — the ports (ABCs): ``Backend``, ``Environment``, ``Sandbox``,
   ``Session``, ``Harness``.
-- ``adapters/`` — implementations: ``SandboxAgentBackend`` / ``InProcessPiBackend`` / ``LocalBackend``
+- ``adapters/`` — implementations: ``SandboxAgentBackend`` / ``LocalBackend``
   and ``PiHarness`` / ``ClaudeHarness``.
 - ``utils/`` — shared plumbing (the ``/run`` wire and the transports to the TS runner).
 
@@ -23,7 +23,6 @@
 from .adapters import (
     AgentaHarness,
     ClaudeHarness,
-    InProcessPiBackend,
     LocalBackend,
     PiHarness,
     SandboxAgentBackend,
@@ -98,7 +97,6 @@
     coerce_tool_config,
     coerce_tool_configs,
     parse_tool_config,
-    parse_tool_configs,
 )
 from .adapters.vercel import (
     from_ui_messages,
@@ -148,7 +146,6 @@
     "EnvironmentToolSecretProvider",
     "MissingSecretPolicy",
     "parse_tool_config",
-    "parse_tool_configs",
     "coerce_tool_config",
     "coerce_tool_configs",
     "ToolError",
@@ -179,7 +176,6 @@
     "ToolResolutionError",
     # Adapters
     "SandboxAgentBackend",
-    "InProcessPiBackend",
     "LocalBackend",
     "PiHarness",
     "ClaudeHarness",

sdks/python/agenta/sdk/agents/adapters/__init__.py

@@ -1,21 +1,19 @@
 """Adapters: concrete implementations of the agent runtime ports.
 
-- Backend adapters: ``SandboxAgentBackend`` (sandbox-agent over ACP), ``InProcessPiBackend`` (in-process Pi,
-  the reference backend), ``LocalBackend`` (standalone SDK runs; not yet implemented).
+- Backend adapters: ``SandboxAgentBackend`` (sandbox-agent over ACP),
+  ``LocalBackend`` (standalone SDK runs; not yet implemented).
 - Harness adapters: ``PiHarness``, ``ClaudeHarness``, ``AgentaHarness`` (+ ``make_harness``).
 - HTTP/browser protocol adapters live in subpackages, e.g. ``adapters.vercel``.
 
 Shared plumbing for the runner-backed adapters lives in ``agents/utils``.
 """
 
 from .harnesses import AgentaHarness, ClaudeHarness, PiHarness, make_harness
-from .in_process import InProcessPiBackend
 from .local import LocalBackend
 from .sandbox_agent import SandboxAgentBackend
 
 __all__ = [
     "SandboxAgentBackend",
-    "InProcessPiBackend",
     "LocalBackend",
     "PiHarness",
     "ClaudeHarness",

sdks/python/agenta/sdk/agents/interfaces.py

@@ -5,7 +5,7 @@
 - ``Backend`` is the engine. It declares which harnesses it can drive
   (``supported_harnesses``), owns sandbox + session lifecycle, and is pure plumbing: it
   takes an already-harness-shaped config and launches it. Adapters: ``SandboxAgentBackend``,
-  ``InProcessPiBackend``, ``LocalBackend``.
+  ``LocalBackend``.
 - ``Sandbox`` is where a session's process tree lives, plus the provisioning verb
   (``add_files``).
 - ``Session`` is one conversation (``prompt``, ``destroy``).

sdks/python/agenta/sdk/agents/tools/__init__.py

@@ -33,9 +33,8 @@
     ToolConfigBase,
     ToolSpec,
 )
-from .parsing import parse_tool_config, parse_tool_configs
+from .parsing import parse_tool_config
 from .resolver import EnvironmentToolSecretProvider, ToolResolver
-from .wire import tool_spec_to_wire, tool_specs_to_wire
 
 __all__ = [
     "ToolConfigBase",
@@ -57,13 +56,10 @@
     "GatewayToolResolver",
     "EnvironmentToolSecretProvider",
     "parse_tool_config",
-    "parse_tool_configs",
     "coerce_tool_config",
     "coerce_tool_configs",
     "ToolConfigDiagnostic",
     "ToolConfigParseResult",
-    "tool_spec_to_wire",
-    "tool_specs_to_wire",
     "ToolError",
     "ToolConfigError",
     "ToolConfigurationError",