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 promotes the JSON-RPC envelope types (JSONRPCRequest/Response/Error) and ACP method-param types (CreateTaskParams, SendMessageParams, etc.) from agentex.lib.types.* to a new canonical package at agentex.protocol.*. The old paths are converted to thin re-export shims so existing consumer imports continue to work without any code changes.

• New agentex.protocol package (acp.py, json_rpc.py, __init__.py) holds the canonical definitions; json_rpc.py explicitly restores the from_attributes=True / populate_by_name=True ConfigDict that was previously inherited from the shared model_utils.BaseModel.
• Back-compat shims at agentex.lib.types.{acp,json_rpc} re-export all original public symbols — including RPC_SYNC_METHODS and PARAMS_MODEL_BY_METHOD — so isinstance checks, type annotations, and existing imports remain identity-safe.
• New test file tests/test_protocol_shims.py pins both the symbol-parity and class-identity invariants, and separately asserts the ConfigDict preservation.

Confidence Score: 5/5

Safe to merge — this is a pure namespace reorganisation with no behavioural changes and fully-covered back-compat shims.

Both issues raised in the previous review round have been addressed in full: the shim now re-exports RPC_SYNC_METHODS and PARAMS_MODEL_BY_METHOD, and json_rpc.py explicitly restores from_attributes=True / populate_by_name=True via a shared ConfigDict. A dedicated test file pins both invariants. All internal imports and CLI templates have been mechanically updated to the canonical paths. No logic was changed anywhere.

No files require special attention.

Important Files Changed

Filename	Overview
src/agentex/protocol/acp.py	New canonical location for ACP types; identical content to the original lib/types/acp.py using plain pydantic.BaseModel (which the original already used). All seven public symbols present.
src/agentex/protocol/json_rpc.py	New canonical location for JSON-RPC types; explicitly preserves from_attributes=True / populate_by_name=True via _PROTOCOL_MODEL_CONFIG, restoring the behavior previously inherited from model_utils.BaseModel.
src/agentex/lib/types/acp.py	Replaced with back-compat shim; re-exports all seven original public symbols including RPC_SYNC_METHODS and PARAMS_MODEL_BY_METHOD.
src/agentex/lib/types/json_rpc.py	Replaced with back-compat shim; re-exports all three JSON-RPC envelope classes from the canonical path.
tests/test_protocol_shims.py	New test file pinning symbol-parity, class-identity, and ConfigDict preservation invariants across both shims; directly addresses the concerns raised in previous review threads.
src/agentex/lib/sdk/fastacp/base/base_acp_server.py	Import updated to agentex.protocol.{acp,json_rpc}; no logic change.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[agentex.protocol.acp\nCANONICAL] -->|re-exported by| B[agentex.lib.types.acp\nback-compat shim]
    C[agentex.protocol.json_rpc\nCANONICAL] -->|re-exported by| D[agentex.lib.types.json_rpc\nback-compat shim]

    A -->|imported directly| E[fastacp/base_acp_server.py]
    A -->|imported directly| F[fastacp/impl/*.py]
    A -->|imported directly| G[temporal workflows & services]
    A -->|imported directly| H[CLI templates *.j2]

    C -->|imported directly| E

    B -->|still works for| I[external consumers]
    D -->|still works for| I

    subgraph "agentex.protocol package"
        A
        C
        J[__init__.py\ndocstring only]
    end

Loading

_{Reviews (6): Last reviewed commit: "docs(claude): document agentex.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

[max-parke-scale]

Note that the docs PR shouldn't be merged until this lands in a release - it'll fail CI until then anyway.