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.* into a new canonical agentex.protocol.* package, with back-compat shims at the old paths. The motivation is to enable a future slim agentex-sdk-client package that ships only pydantic + stainless-generated types without the full ADK runtime.

• New canonical package agentex.protocol.{acp,json_rpc} created; both previous concern points from earlier review (missing RPC_SYNC_METHODS/PARAMS_MODEL_BY_METHOD in the shim, and the dropped model_utils.BaseModel config flags) are fully addressed in this version.
• Back-compat shims at agentex.lib.types.{acp,json_rpc} re-export all symbols including module-level constants; identity equality verified (A is B).
• Internal imports updated in 9 source files and 3 test files to use the new canonical path; CLI scaffold templates also updated.

Confidence Score: 5/5

This is a pure refactor — no logic changes, only type relocations with re-export shims at the old paths. Safe to merge.

The two issues flagged in a prior review pass (missing module-level constants in the shim, and the dropped model_utils.BaseModel config) are both fully resolved in this version. All symbols are re-exported at the old paths, the model_config is explicitly preserved in json_rpc.py with a clear comment, and every internal consumer has been updated to the new canonical path. No logic is changed anywhere.

No files require special attention. The shim files and canonical modules are consistent with each other.

Important Files Changed

Filename	Overview
src/agentex/protocol/acp.py	New canonical location for ACP param types; content is verbatim from the original lib/types/acp.py, using plain pydantic BaseModel (matching the original, which never used model_utils.BaseModel).
src/agentex/protocol/json_rpc.py	New canonical location for JSON-RPC envelope types; explicitly preserves the model_config (from_attributes=True, populate_by_name=True) that the original model_utils.BaseModel applied, with a clear explanatory comment.
src/agentex/lib/types/acp.py	Replaced with a back-compat shim; correctly re-exports all symbols including RPC_SYNC_METHODS and PARAMS_MODEL_BY_METHOD that were flagged missing in a prior review pass.
src/agentex/lib/types/json_rpc.py	Replaced with a back-compat shim re-exporting all three JSON-RPC types from the canonical location; all existing callers continue to work.
src/agentex/protocol/init.py	Package init with a clear docstring explaining the slim-safety contract and back-compat story; intentionally exports nothing at the package level.
src/agentex/lib/sdk/fastacp/base/base_acp_server.py	Import-only change; all logic is untouched. Now pulls RPC types from the canonical agentex.protocol paths.
src/agentex/lib/cli/templates/default/project/acp.py.j2	CLI scaffold template updated to import from the new canonical path; since templates and SDK ship together, no version mismatch risk.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    subgraph Canonical["agentex.protocol (new canonical)"]
        PA["agentex.protocol.acp\nRPCMethod, CreateTaskParams\nSendMessageParams, SendEventParams\nCancelTaskParams, RPC_SYNC_METHODS\nPARAMS_MODEL_BY_METHOD"]
        PJ["agentex.protocol.json_rpc\nJSONRPCRequest\nJSONRPCResponse\nJSONRPCError"]
    end

    subgraph Shims["agentex.lib.types (back-compat shims)"]
        LA["agentex.lib.types.acp\n(re-exports from protocol.acp)"]
        LJ["agentex.lib.types.json_rpc\n(re-exports from protocol.json_rpc)"]
    end

    subgraph Consumers["Internal consumers (updated)"]
        BS["base_acp_server.py"]
        TS["temporal_task_service.py"]
        WF["workflow.py"]
        IMPL["fastacp/impl/*.py"]
        TESTS["tests/"]
        TMPL["cli templates (*.j2)"]
    end

    PA -->|re-export| LA
    PJ -->|re-export| LJ

    BS --> PA
    BS --> PJ
    TS --> PA
    WF --> PA
    IMPL --> PA
    TESTS --> PA
    TESTS --> PJ
    TMPL --> PA

Loading

_{Reviews (3): Last reviewed commit: "fix(types): address Greptile review feed..." | 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