refactor(types): promote protocol types to agentex.protocol.*

[max-parke-scale]

Summary

Moves the JSON-RPC envelope types (JSONRPCRequest/Response/Error) and ACP method-param types (CreateTaskParams, SendMessageParams, SendEventParams, CancelTaskParams, RPCMethod) out of agentex.lib.types.* into a new canonical location at agentex.protocol.*. Back-compat shims at the old paths re-export the same classes — existing imports continue to work.

Zero install-time impact for existing consumers. Same import paths keep working.

Tracking: AGX1-292. First of two PRs:

• This PR: refactor only — set up agentex.protocol.* as the canonical location for protocol types
• Follow-up PR: introduces the slim agentex-sdk-client package (which will ship agentex.protocol.* but not agentex.lib.*), letting REST-only consumers like packages/egp-api-backend drop hand-rolled JSON-RPC dict literals in favor of these typed shapes

Motivation

egp-api-backend today hand-rolls a ~600-line JSON-RPC gateway at egp_api_backend/server/internal/interfaces/services/evaluation_task/evaluation_task_gateways/agentex_output_evaluation_task_gateway.py. Sample:

async with session.post(
    rpc_path,
    json={
        "jsonrpc": "2.0",
        "method": "task/create",
        "params": {
            "name": task_name,
            "params": {"description": ..., "is_eval": True},
        },
    },
) as resp:

These shapes map directly onto the types defined in agentex.lib.types.acp and agentex.lib.types.json_rpc. They hand-roll because importing those types currently requires pulling in the full ADK runtime (~31 deps including temporalio, fastapi, claude-agent-sdk, etc.).

Moving the protocol types out of agentex.lib.* is the prerequisite for letting them ship in a future slim-package install.

Changes

File	Change
src/agentex/protocol/__init__.py	New — package docstring
src/agentex/protocol/acp.py	Moved from src/agentex/lib/types/acp.py; no other change
src/agentex/protocol/json_rpc.py	Moved from src/agentex/lib/types/json_rpc.py; swapped from agentex.lib.utils.model_utils import BaseModel → from pydantic import BaseModel (behavior-preserving — these classes don't use any model_utils extensions like from_yaml/to_json/populate_by_name)
src/agentex/lib/types/acp.py	Replaced with back-compat shim re-exporting from canonical path
src/agentex/lib/types/json_rpc.py	Replaced with back-compat shim re-exporting from canonical path
9 files in src/agentex/lib/*	Internal imports updated to canonical path
tests/test_header_forwarding.py	Internal import updated to canonical path

Slim-safety of moved files

Both moved modules depend only on pydantic and agentex.types.{Task, Agent, Event, TaskMessageContent} — all already-slim-safe (Stainless-generated client surface + pydantic, which is in the bare client's 6 base deps).

Other agentex.lib.types.* modules have heavier deps (e.g. fastacp.py pulls temporal, converters.py pulls openai-agents) and are intentionally left in place. They can be promoted in follow-up PRs if/when other consumers need them slim-safe.

Verification (local)

ruff check .
# All checks passed!

python -m build --wheel
unzip -l dist/agentex_sdk-0.11.4-py3-none-any.whl | grep -E "(protocol/|lib/types/(acp|json_rpc))"
# Both paths shipped: agentex/protocol/acp.py + agentex/protocol/json_rpc.py
#                     agentex/lib/types/acp.py (shim) + agentex/lib/types/json_rpc.py (shim)

# Identity check from a fresh install:
python -c "
from agentex.protocol.acp import RPCMethod as A
from agentex.lib.types.acp import RPCMethod as B
assert A is B  # same class object — shim re-exports, not duplicates
print('identity OK')
"
# identity OK

Test plan

• CI passes (ruff, pyright, mypy, pytest).
• Any consumer doing from agentex.lib.types.acp import CreateTaskParams continues to work without change.
• from agentex.protocol.acp import CreateTaskParams works as the new canonical path.

Greptile Summary

This PR moves the JSON-RPC envelope types (JSONRPCRequest/Response/Error) and ACP method-param types out of agentex.lib.types.* into a new agentex.protocol.* package, the first step toward a slim REST-only client distribution. Back-compat shims at the old paths ensure existing imports continue to work unchanged.

• New canonical package src/agentex/protocol/ contains acp.py and json_rpc.py; json_rpc.py explicitly restores from_attributes=True / populate_by_name=True via _PROTOCOL_MODEL_CONFIG to match the behavior inherited from the previous model_utils.BaseModel.
• Shims at agentex.lib.types.acp and agentex.lib.types.json_rpc re-export all original symbols including RPC_SYNC_METHODS and PARAMS_MODEL_BY_METHOD, closing the regression flagged in the prior review pass.
• tests/test_protocol_shims.py pins the back-compat contract: symbol parity, class object identity (preserving isinstance semantics for mixed import styles), and model_config preservation.

Confidence Score: 5/5

Safe to merge — pure refactor with full back-compat shims, no behavioral changes, and targeted tests covering the exact regressions raised in the prior review cycle.

Both concerns from the previous review round have been resolved: RPC_SYNC_METHODS/PARAMS_MODEL_BY_METHOD are now included in the shim, and from_attributes=True/populate_by_name=True are explicitly re-applied in the canonical json_rpc.py. The new test_protocol_shims.py locks in symbol parity, class identity, and model config preservation. No logic changed — only import paths moved.

No files require special attention.

Important Files Changed

Filename	Overview
src/agentex/protocol/acp.py	New canonical home for ACP param types; exact copy from the original lib/types/acp.py using the same plain pydantic.BaseModel — no behavior change.
src/agentex/protocol/json_rpc.py	New canonical JSON-RPC types; explicitly restores from_attributes=True and populate_by_name=True via _PROTOCOL_MODEL_CONFIG to match legacy model_utils.BaseModel behavior.
src/agentex/lib/types/acp.py	Replaced with back-compat shim; re-exports all original symbols including RPC_SYNC_METHODS and PARAMS_MODEL_BY_METHOD that were flagged as missing in a prior review pass.
src/agentex/lib/types/json_rpc.py	Replaced with back-compat shim re-exporting JSONRPCError/Request/Response from the canonical path.
tests/test_protocol_shims.py	New test file pinning the back-compat contract: symbol parity, class identity, and model_config preservation — directly validates the two concerns raised in the prior review.
src/agentex/lib/sdk/fastacp/base/base_acp_server.py	Import updated from agentex.lib.types.* to agentex.protocol.* — straightforward one-line change per import group.

_{Reviews (5): Last reviewed commit: "fix(lint): sort imports in test_protocol..." | Re-trigger Greptile}

[max-parke-scale]

@greptile review

[declan-scale]

This would be a breaking change right? Any consumer that imports these types (any agentex agent using them) will have to update their import paths

[max-parke-scale]

No, there's a shim at the old path.

[declan-scale]

Can we update the CLAUDE.md file to reflect the migration and also update the the docs in scale-agentex/agentex/docs and sgp-docs

[max-parke-scale]

@declan-scale done — split across two PRs:

• In this PR (refactor(types): promote protocol types to agentex.protocol.* #371): CLAUDE.md now documents src/agentex/protocol/ as the canonical home for slim-safe wire-protocol shapes, and explicitly flags src/agentex/lib/types/{acp,json_rpc}.py as back-compat shims. Other lib/types/* modules stay on the old path because they have heavier transitive deps and weren't migrated.
• docs(agentex): use canonical agentex.protocol.acp import paths scale-agentex#254 (just opened): updates the agentex mkdocs site — 10 markdown files, 8 from agentex.lib.types.acp import ... → from agentex.protocol.acp import ... in code samples, plus 2 mkdocstrings cross-refs (::: agentex.lib.types.acp.X → ::: agentex.protocol.acp.X).

For sgp-docs: I grepped for any reference to the migrated modules (agentex.lib.types.acp / agentex.lib.types.json_rpc) and got zero hits. The only agentex.lib.types.* reference there is to tracing.SGPTracingProcessorConfig, which #371 didn't move (tracing isn't slim-safe — it brings in opentelemetry/ddtrace transitively). Let me know if I missed a doc surface there worth touching.

🤖 — posted via Claude Code