opencode-a2a 1.1.0__tar.gz → 1.1.1__tar.gz

{opencode_a2a-1.1.0 → opencode_a2a-1.1.1}/AGENTS.md

@@ -11,6 +11,8 @@ The following rules apply to coding agent collaboration in this repository. Thes
 
 - Follow the Git, Issue, and PR workflow defined in [CONTRIBUTING.md](CONTRIBUTING.md).
 - Use `gh` CLI for all issue/PR operations (reading, writing, and comments). Do not edit through the web UI.
+- Do not use the Codex GitHub connector for any repository operation. Use `gh` CLI exclusively for issue, PR, review, comment, and metadata workflows.
+- If `gh` CLI cannot complete a required GitHub operation because of permissions, authentication, or environment limits, stop and ask the human to perform or unblock the operation. Do not fall back to the Codex GitHub connector.
 - Create a new tracking issue for any development task that does not already have one.
 - Link the issue explicitly in PR descriptions (e.g., `Closes #xx`).
 - Keep status updates synchronized to the relevant issue/PR to avoid duplicate manual work.

{opencode_a2a-1.1.0 → opencode_a2a-1.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opencode-a2a
-Version: 1.1.0
+Version: 1.1.1
 Summary: OpenCode A2A runtime
 Author: liujuanjuan1984@Intelligent-Internet
 License-Expression: Apache-2.0
@@ -43,12 +43,12 @@ Dynamic: license-file
 # opencode-a2a
 
 ```text
-  ___                    ____          _              _    ____     _
- / _ \ _ __   ___ _ __  / ___|___   __| | ___        / \  |___ \   / \
-| | | | '_ \ / _ \ '_ \| |   / _ \ / _` |/ _ \_____ / _ \   __) | / _ \
-| |_| | |_) |  __/ | | | |__| (_) | (_| |  __/_____/ ___ \ / __/ / ___ \
- \___/| .__/ \___|_| |_|\____\___/ \__,_|\___|    /_/   \_\_____/_/   \_\
-      |_|
+ ██████╗ ██████╗ ███████╗███╗   ██╗ ██████╗ ██████╗ ██████╗ ███████╗     █████╗ ██████╗  █████╗
+██╔═══██╗██╔══██╗██╔════╝████╗  ██║██╔════╝██╔═══██╗██╔══██╗██╔════╝    ██╔══██╗╚════██╗██╔══██╗
+██║   ██║██████╔╝█████╗  ██╔██╗ ██║██║     ██║   ██║██║  ██║█████╗█████╗███████║ █████╔╝███████║
+██║   ██║██╔═══╝ ██╔══╝  ██║╚██╗██║██║     ██║   ██║██║  ██║██╔══╝╚════╝██╔══██║██╔═══╝ ██╔══██║
+╚██████╔╝██║     ███████╗██║ ╚████║╚██████╗╚██████╔╝██████╔╝███████╗    ██║  ██║███████╗██║  ██║
+ ╚═════╝ ╚═╝     ╚══════╝╚═╝  ╚═══╝ ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝    ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝
 ```
 
 > Expose OpenCode through A2A.

{opencode_a2a-1.1.0 → opencode_a2a-1.1.1}/README.md

@@ -1,12 +1,12 @@
 # opencode-a2a
 
 ```text
-  ___                    ____          _              _    ____     _
- / _ \ _ __   ___ _ __  / ___|___   __| | ___        / \  |___ \   / \
-| | | | '_ \ / _ \ '_ \| |   / _ \ / _` |/ _ \_____ / _ \   __) | / _ \
-| |_| | |_) |  __/ | | | |__| (_) | (_| |  __/_____/ ___ \ / __/ / ___ \
- \___/| .__/ \___|_| |_|\____\___/ \__,_|\___|    /_/   \_\_____/_/   \_\
-      |_|
+ ██████╗ ██████╗ ███████╗███╗   ██╗ ██████╗ ██████╗ ██████╗ ███████╗     █████╗ ██████╗  █████╗
+██╔═══██╗██╔══██╗██╔════╝████╗  ██║██╔════╝██╔═══██╗██╔══██╗██╔════╝    ██╔══██╗╚════██╗██╔══██╗
+██║   ██║██████╔╝█████╗  ██╔██╗ ██║██║     ██║   ██║██║  ██║█████╗█████╗███████║ █████╔╝███████║
+██║   ██║██╔═══╝ ██╔══╝  ██║╚██╗██║██║     ██║   ██║██║  ██║██╔══╝╚════╝██╔══██║██╔═══╝ ██╔══██║
+╚██████╔╝██║     ███████╗██║ ╚████║╚██████╗╚██████╔╝██████╔╝███████╗    ██║  ██║███████╗██║  ██║
+ ╚═════╝ ╚═╝     ╚══════╝╚═╝  ╚═══╝ ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝    ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝
 ```
 
 > Expose OpenCode through A2A.

{opencode_a2a-1.1.0 → opencode_a2a-1.1.1}/src/opencode_a2a/a2a_utils.py

@@ -16,10 +16,6 @@ def clone_proto(message: ProtoT) -> ProtoT:
     return cloned
 
 
-def proto_equals(left: ProtoMessage, right: ProtoMessage) -> bool:
-    return bool(left == right)
-
-
 def _to_proto_value(value: Any) -> Value:
     proto_value = Value()
     if value is None:

{opencode_a2a-1.1.0 → opencode_a2a-1.1.1}/src/opencode_a2a/cli.py

@@ -15,12 +15,18 @@ from .config import Settings
 from .server.application import main as serve_main
 
 CLI_BRAND_BANNER = (
-    "  ___                    ____          _              _    ____     _    \n"
-    " / _ \\ _ __   ___ _ __  / ___|___   __| | ___        / \\  |___ \\   / \\   \n"
-    "| | | | '_ \\ / _ \\ '_ \\| |   / _ \\ / _` |/ _ \\_____ / _ \\   __) | / _ \\  \n"
-    "| |_| | |_) |  __/ | | | |__| (_) | (_| |  __/_____/ ___ \\ / __/ / ___ \\ \n"
-    " \\___/| .__/ \\___|_| |_|\\____\\___/ \\__,_|\\___|    /_/   \\_\\_____/_/   \\_\\\n"
-    "      |_|                                                                "
+    " ██████╗ ██████╗ ███████╗███╗   ██╗ ██████╗ ██████╗"
+    " ██████╗ ███████╗     █████╗ ██████╗  █████╗ \n"
+    "██╔═══██╗██╔══██╗██╔════╝████╗  ██║██╔════╝██╔═══██╗"
+    "██╔══██╗██╔════╝    ██╔══██╗╚════██╗██╔══██╗\n"
+    "██║   ██║██████╔╝█████╗  ██╔██╗ ██║██║     ██║   ██║"
+    "██║  ██║█████╗█████╗███████║ █████╔╝███████║\n"
+    "██║   ██║██╔═══╝ ██╔══╝  ██║╚██╗██║██║     ██║   ██║"
+    "██║  ██║██╔══╝╚════╝██╔══██║██╔═══╝ ██╔══██║\n"
+    "╚██████╔╝██║     ███████╗██║ ╚████║╚██████╗╚██████╔╝"
+    "██████╔╝███████╗    ██║  ██║███████╗██║  ██║\n"
+    " ╚═════╝ ╚═╝     ╚══════╝╚═╝  ╚═══╝ ╚═════╝ ╚═════╝"
+    " ╚═════╝ ╚══════╝    ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝"
 )
 PROJECT_REPOSITORY_URL = "https://github.com/Intelligent-Internet/opencode-a2a"
 HELP_FLAGS = frozenset({"-h", "--help"})
@@ -95,7 +101,7 @@ CALL_HELP = (
     "  Service base URLs also work, but card URLs are the preferred example form."
 )
 
-ROOT_HELP_EPILOG = f"{OPENCODE_SETUP_HELP}\n\n{SERVE_ENVIRONMENT_HELP}\n\n{CALL_HELP}"
+ROOT_HELP_EPILOG = "Command-specific help:\n  opencode-a2a serve --help\n  opencode-a2a call --help"
 SERVE_HELP_EPILOG = f"{OPENCODE_SETUP_HELP}\n\n{SERVE_ENVIRONMENT_HELP}"
 CALL_HELP_EPILOG = CALL_HELP
 
@@ -224,7 +230,7 @@ def build_parser() -> argparse.ArgumentParser:
             CLI_BRAND_BANNER
             + "\n\n"
             + f"repo: {PROJECT_REPOSITORY_URL}\n"
-            + "uv tool install --upgrade opencode-a2a\n"
+            + "uv tool install --upgrade opencode-a2a\n\n"
             + ROOT_DESCRIPTION
         ),
         formatter_class=RootHelpFormatter,

{opencode_a2a-1.1.0 → opencode_a2a-1.1.1}/src/opencode_a2a/jsonrpc/handlers/interrupt_queries.py

@@ -10,18 +10,6 @@ from ..models import JSONRPCRequest
 from .common import build_internal_error_response, build_success_response, reject_unknown_fields
 
 
-def _binding_to_result_item(binding: Any) -> dict[str, Any]:
-    return {
-        "request_id": binding.request_id,
-        "session_id": binding.session_id,
-        "interrupt_type": binding.interrupt_type,
-        "task_id": binding.task_id,
-        "context_id": binding.context_id,
-        "details": dict(binding.details) if isinstance(binding.details, dict) else None,
-        "expires_at": binding.expires_at,
-    }
-
-
 async def handle_interrupt_query_request(
     context: ExtensionHandlerContext,
     base_request: JSONRPCRequest,
@@ -58,5 +46,18 @@ async def handle_interrupt_query_request(
     return build_success_response(
         context,
         base_request.id,
-        {"items": [_binding_to_result_item(item) for item in items]},
+        {
+            "items": [
+                {
+                    "request_id": item.request_id,
+                    "session_id": item.session_id,
+                    "interrupt_type": item.interrupt_type,
+                    "task_id": item.task_id,
+                    "context_id": item.context_id,
+                    "details": dict(item.details) if isinstance(item.details, dict) else None,
+                    "expires_at": item.expires_at,
+                }
+                for item in items
+            ]
+        },
     )

{opencode_a2a-1.1.0 → opencode_a2a-1.1.1}/src/opencode_a2a/output_modes.py

@@ -37,30 +37,19 @@ _STREAM_METADATA_STREAM_KEY = "stream"
 _STREAM_METADATA_BLOCK_TYPE_KEY = "block_type"
 
 
-def _accepted_output_modes_source(source: Any) -> Iterable[str] | None:
+def normalize_accepted_output_modes(source: Any) -> tuple[str, ...] | None:
     if source is None:
         return None
-
     accepted = getattr(source, "accepted_output_modes", None) or getattr(
         source, "acceptedOutputModes", None
     )
     if accepted is not None:
         source = accepted
-
-    if isinstance(source, str | bytes | bytearray | dict):
-        return None
-    if not isinstance(source, Iterable):
-        return None
-    return cast(Iterable[str], source)
-
-
-def normalize_accepted_output_modes(source: Any) -> tuple[str, ...] | None:
-    accepted = _accepted_output_modes_source(source)
-    if accepted is None:
+    if isinstance(source, str | bytes | bytearray | dict) or not isinstance(source, Iterable):
         return None
 
     normalized: list[str] = []
-    for value in accepted:
+    for value in cast(Iterable[str], source):
         if not isinstance(value, str):
             continue
         mode = value.strip().lower()
@@ -194,9 +183,11 @@ def apply_accepted_output_modes(
         return replace_artifact_event_artifact(payload, artifact)
 
     if isinstance(payload, TaskStatusUpdateEvent):
-        message = None
-        if payload.status.HasField("message"):
-            message = _filter_optional_message(payload.status.message, normalized)
+        message = (
+            _filter_message(payload.status.message, normalized)
+            if payload.status.HasField("message")
+            else None
+        )
         return replace_status_event_message(payload, message)
 
     if isinstance(payload, Task):
@@ -375,7 +366,7 @@ class NegotiatingResultAggregator(ResultAggregator):
 def _filter_task(task: Task, accepted_output_modes: Collection[str]) -> Task:
     updated = clone_proto(task)
     if updated.status.HasField("message"):
-        filtered_message = _filter_optional_message(updated.status.message, accepted_output_modes)
+        filtered_message = _filter_message(updated.status.message, accepted_output_modes)
         if filtered_message is None:
             updated.status.ClearField("message")
         else:
@@ -404,15 +395,6 @@ def _filter_task(task: Task, accepted_output_modes: Collection[str]) -> Task:
     return updated
 
 
-def _filter_optional_message(
-    message: Message | None,
-    accepted_output_modes: Collection[str],
-) -> Message | None:
-    if message is None:
-        return None
-    return _filter_message(message, accepted_output_modes)
-
-
 def _filter_message(
     message: Message,
     accepted_output_modes: Collection[str],
@@ -439,7 +421,14 @@ def _filter_parts(
 ) -> list[Part]:
     filtered: list[Part] = []
     for part in parts:
-        media_type = _part_media_type(part)
+        if part.HasField("text"):
+            media_type = _TEXT_PLAIN_MEDIA_TYPE
+        elif part.HasField("data"):
+            media_type = _APPLICATION_JSON_MEDIA_TYPE
+        elif part.HasField("raw") or part.HasField("url"):
+            media_type = part.media_type or "application/octet-stream"
+        else:
+            media_type = None
         if media_type is None or accepts_output_mode(accepted_output_modes, media_type):
             filtered.append(part)
             continue
@@ -459,13 +448,3 @@ def _filter_parts(
                     )
                 )
     return filtered
-
-
-def _part_media_type(part: Part) -> str | None:
-    if part.HasField("text"):
-        return _TEXT_PLAIN_MEDIA_TYPE
-    if part.HasField("data"):
-        return _APPLICATION_JSON_MEDIA_TYPE
-    if part.HasField("raw") or part.HasField("url"):
-        return part.media_type or "application/octet-stream"
-    return None

{opencode_a2a-1.1.0 → opencode_a2a-1.1.1}/src/opencode_a2a/server/application.py

@@ -259,17 +259,6 @@ class OpencodeRequestHandler(LegacyRequestHandler):
             return "Task store unavailable while deleting task state."
         return "Task store unavailable."
 
-    @classmethod
-    def _task_store_failure_metadata(cls, operation: str) -> dict[str, dict[str, dict[str, str]]]:
-        return {
-            "opencode": {
-                "error": {
-                    "type": TASK_STORE_ERROR_TYPE,
-                    "operation": operation,
-                }
-            }
-        }
-
     @classmethod
     def _task_store_server_error(cls, exc: TaskStoreOperationError) -> InternalError:
         return InternalError(message=cls._task_store_failure_message(exc.operation))
@@ -295,7 +284,14 @@ class OpencodeRequestHandler(LegacyRequestHandler):
             context_id=context_id,
             status=TaskStatus(state=TaskState.TASK_STATE_FAILED, message=error_message),
             history=[error_message],
-            metadata=cls._task_store_failure_metadata(operation),
+            metadata={
+                "opencode": {
+                    "error": {
+                        "type": TASK_STORE_ERROR_TYPE,
+                        "operation": operation,
+                    }
+                }
+            },
         )
 
     @classmethod
@@ -322,7 +318,14 @@ class OpencodeRequestHandler(LegacyRequestHandler):
                 task_id=task_id,
                 context_id=context_id,
                 status=TaskStatus(state=TaskState.TASK_STATE_FAILED),
-                metadata=cls._task_store_failure_metadata(operation),
+                metadata={
+                    "opencode": {
+                        "error": {
+                            "type": TASK_STORE_ERROR_TYPE,
+                            "operation": operation,
+                        }
+                    }
+                },
             ),
         )
 

opencode_a2a-1.1.1/src/opencode_a2a/server/context_helpers.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, MutableMapping
+
+from a2a.auth.user import UnauthenticatedUser, User
+from a2a.server.context import ServerCallContext
+
+
+class AuthenticatedIdentityUser(User):
+    def __init__(self, identity: str) -> None:
+        self._identity = identity
+
+    @property
+    def is_authenticated(self) -> bool:
+        return True
+
+    @property
+    def user_name(self) -> str:
+        return self._identity
+
+
+def normalize_server_call_context(context: ServerCallContext | None) -> ServerCallContext:
+    if context is None:
+        return ServerCallContext()
+
+    raw_state = getattr(context, "state", None)
+    raw_requested_extensions = getattr(context, "requested_extensions", None)
+    raw_tenant = getattr(context, "tenant", "")
+    raw_user = getattr(context, "user", None)
+
+    if isinstance(raw_state, MutableMapping):
+        state = raw_state
+    elif isinstance(raw_state, Mapping):
+        state = dict(raw_state)
+    else:
+        state = {}
+
+    if raw_requested_extensions is None:
+        requested_extensions: set[str] = set()
+    elif isinstance(raw_requested_extensions, set):
+        requested_extensions = raw_requested_extensions
+    elif isinstance(raw_requested_extensions, str):
+        requested_extensions = {raw_requested_extensions}
+    else:
+        try:
+            requested_extensions = {str(value) for value in raw_requested_extensions}
+        except TypeError:
+            requested_extensions = set()
+
+    tenant = raw_tenant if isinstance(raw_tenant, str) else ""
+    identity = state.get("identity")
+    normalized_identity = identity if isinstance(identity, str) else None
+    if normalized_identity and (
+        not isinstance(raw_user, User) or isinstance(raw_user, UnauthenticatedUser)
+    ):
+        user: User = AuthenticatedIdentityUser(normalized_identity)
+    elif isinstance(raw_user, User):
+        user = raw_user
+    else:
+        user = UnauthenticatedUser()
+
+    if (
+        isinstance(context, ServerCallContext)
+        and raw_state is state
+        and raw_user is user
+        and raw_tenant == tenant
+        and raw_requested_extensions == requested_extensions
+    ):
+        return context
+
+    return ServerCallContext(
+        state=state,
+        user=user,
+        tenant=tenant,
+        requested_extensions=requested_extensions,
+    )

{opencode_a2a-1.1.0 → opencode_a2a-1.1.1}/src/opencode_a2a/server/task_store.py

@@ -14,7 +14,6 @@ from a2a.server.tasks.task_store import TaskStore
 from a2a.types import ListTasksRequest, ListTasksResponse, Task
 from sqlalchemy.engine import make_url
 
-from ..a2a_utils import proto_equals
 from ..config import Settings
 from ..task_states import TERMINAL_TASK_STATES
 from .context_helpers import normalize_server_call_context
@@ -67,7 +66,7 @@ class FirstTerminalStateWinsPolicy(TaskWritePolicy):
                 persist=False,
                 reason="state_overwrite_after_terminal_persistence",
             )
-        if not proto_equals(incoming, existing):
+        if incoming != existing:
             return TaskPersistenceDecision(
                 persist=False,
                 reason="late_mutation_after_terminal_persistence",
@@ -238,7 +237,7 @@ class PolicyAwareTaskStore(TaskStoreDecorator):
             if (
                 existing is not None
                 and existing.status.state in TERMINAL_TASK_STATES
-                and proto_equals(existing, task)
+                and existing == task
             ):
                 return
             raise RuntimeError(

{opencode_a2a-1.1.0 → opencode_a2a-1.1.1}/src/opencode_a2a.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opencode-a2a
-Version: 1.1.0
+Version: 1.1.1
 Summary: OpenCode A2A runtime
 Author: liujuanjuan1984@Intelligent-Internet
 License-Expression: Apache-2.0
@@ -43,12 +43,12 @@ Dynamic: license-file
 # opencode-a2a
 
 ```text
-  ___                    ____          _              _    ____     _
- / _ \ _ __   ___ _ __  / ___|___   __| | ___        / \  |___ \   / \
-| | | | '_ \ / _ \ '_ \| |   / _ \ / _` |/ _ \_____ / _ \   __) | / _ \
-| |_| | |_) |  __/ | | | |__| (_) | (_| |  __/_____/ ___ \ / __/ / ___ \
- \___/| .__/ \___|_| |_|\____\___/ \__,_|\___|    /_/   \_\_____/_/   \_\
-      |_|
+ ██████╗ ██████╗ ███████╗███╗   ██╗ ██████╗ ██████╗ ██████╗ ███████╗     █████╗ ██████╗  █████╗
+██╔═══██╗██╔══██╗██╔════╝████╗  ██║██╔════╝██╔═══██╗██╔══██╗██╔════╝    ██╔══██╗╚════██╗██╔══██╗
+██║   ██║██████╔╝█████╗  ██╔██╗ ██║██║     ██║   ██║██║  ██║█████╗█████╗███████║ █████╔╝███████║
+██║   ██║██╔═══╝ ██╔══╝  ██║╚██╗██║██║     ██║   ██║██║  ██║██╔══╝╚════╝██╔══██║██╔═══╝ ██╔══██║
+╚██████╔╝██║     ███████╗██║ ╚████║╚██████╗╚██████╔╝██████╔╝███████╗    ██║  ██║███████╗██║  ██║
+ ╚═════╝ ╚═╝     ╚══════╝╚═╝  ╚═══╝ ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝    ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝
 ```
 
 > Expose OpenCode through A2A.

{opencode_a2a-1.1.0 → opencode_a2a-1.1.1}/src/opencode_a2a.egg-info/SOURCES.txt

@@ -125,6 +125,7 @@ src/opencode_a2a/server/task_store.py
 src/opencode_a2a/server/task_store_sdk_compat.py
 tests/__init__.py
 tests/conftest.py
+tests/test_a2a_utils.py
 tests/test_metadata_access.py
 tests/test_parsing.py
 tests/test_trace_context.py
@@ -185,6 +186,7 @@ tests/server/test_auth.py
 tests/server/test_call_context_builder.py
 tests/server/test_cancel_contract.py
 tests/server/test_cli.py
+tests/server/test_context_helpers.py
 tests/server/test_database_app_persistence.py
 tests/server/test_output_negotiation.py
 tests/server/test_state_store.py

{opencode_a2a-1.1.0 → opencode_a2a-1.1.1}/tests/execution/test_agent_helpers.py

@@ -146,6 +146,39 @@ def test_format_upstream_errors_include_detail_and_provider_auth_paths() -> None
     assert "error=SomeOtherError" in inband.message
 
 
+def test_format_upstream_error_helpers_cover_status_and_generic_paths() -> None:
+    terminal = _format_stream_terminal_error(detail=None, status=503, error_name=None)
+    assert terminal.state == TaskState.TASK_STATE_FAILED
+    assert terminal.error_type == "UPSTREAM_SERVER_ERROR"
+    assert terminal.upstream_status == 503
+
+    terminal_with_detail = _format_stream_terminal_error(
+        detail="tool crashed",
+        status=None,
+        error_name=None,
+    )
+    assert terminal_with_detail.error_type == "UPSTREAM_EXECUTION_ERROR"
+    assert "detail=tool crashed" in terminal_with_detail.message
+
+    inband_with_status = _format_inband_upstream_error(
+        source="message.updated",
+        detail=None,
+        status=429,
+        error_name=None,
+    )
+    assert inband_with_status.error_type == "UPSTREAM_QUOTA_EXCEEDED"
+    assert "status=429" in inband_with_status.message
+
+    provider_auth = _format_inband_upstream_error(
+        source="message.updated",
+        detail=None,
+        status=None,
+        error_name="ProviderAuthError",
+    )
+    assert provider_auth.state == TaskState.TASK_STATE_AUTH_REQUIRED
+    assert provider_auth.error_type == "UPSTREAM_UNAUTHORIZED"
+
+
 @pytest.mark.asyncio
 async def test_await_stream_terminal_signal_handles_shortcuts_and_missing_signal() -> None:
     loop = asyncio.get_running_loop()

{opencode_a2a-1.1.0 → opencode_a2a-1.1.1}/tests/server/test_cli.py

@@ -118,13 +118,17 @@ def test_cli_help_does_not_require_runtime_settings(capsys: pytest.CaptureFixtur
     assert (
         "OpenCode A2A runtime for explicit service startup and peer calls. A2A Protocol 1.0 only."
     ) in help_text
-    assert "___                    ____" in help_text
-    assert "| | | | '_ \\ / _ \\ '_ \\| |   / _ \\ / _` |/ _ \\_____ / _ \\" in help_text
+    assert "██████╗ ██████╗ ███████╗███╗   ██╗ ██████╗" in help_text
+    assert "███████║ █████╔╝███████║" in help_text
     assert "opencode-a2a <command> [arguments] [options]" in help_text
-    assert "A2A_STATIC_AUTH_CREDENTIALS" in help_text
-    assert "opencode serve --hostname 127.0.0.1 --port 4096" in help_text
-    assert "A2A_CLIENT_BEARER_TOKEN=peer-token" in help_text
-    assert "/.well-known/agent-card.json" in help_text
+    assert "uv tool install --upgrade opencode-a2a\n\nOpenCode A2A runtime" in help_text
+    assert "Command-specific help:" in help_text
+    assert "opencode-a2a serve --help" in help_text
+    assert "opencode-a2a call --help" in help_text
+    assert "A2A_STATIC_AUTH_CREDENTIALS" not in help_text
+    assert "opencode serve --hostname 127.0.0.1 --port 4096" not in help_text
+    assert "A2A_CLIENT_BEARER_TOKEN=peer-token" not in help_text
+    assert "/.well-known/agent-card.json" not in help_text
     assert "{call}" not in help_text
     assert "serve" in help_text
     assert "deploy-release" not in help_text
@@ -180,11 +184,29 @@ def test_cli_serve_subcommand_with_invalid_configuration_prints_help(
 
     help_text = capsys.readouterr().out
     assert "Run the OpenCode A2A service. A2A Protocol 1.0 only." in help_text
+    assert "A2A_STATIC_AUTH_CREDENTIALS" in help_text
+    assert "opencode serve --hostname 127.0.0.1 --port 4096" in help_text
     assert "configuration errors:" in help_text
     assert "Configure runtime authentication via A2A_STATIC_AUTH_CREDENTIALS" in help_text
     serve_mock.assert_not_called()
 
 
+def test_cli_serve_help_prints_serve_specific_examples(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    with mock.patch("opencode_a2a.cli.serve_main") as serve_mock:
+        with pytest.raises(SystemExit) as excinfo:
+            cli.main(["serve", "--help"])
+
+    assert excinfo.value.code == 0
+    help_text = capsys.readouterr().out
+    assert "Run the OpenCode A2A service. A2A Protocol 1.0 only." in help_text
+    assert "A2A_STATIC_AUTH_CREDENTIALS" in help_text
+    assert "opencode serve --hostname 127.0.0.1 --port 4096" in help_text
+    assert "A2A_CLIENT_BEARER_TOKEN=peer-token" not in help_text
+    serve_mock.assert_not_called()
+
+
 def test_cli_call_without_required_arguments_prints_help(
     capsys: pytest.CaptureFixture[str],
 ) -> None:

opencode_a2a-1.1.1/tests/server/test_context_helpers.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from types import MappingProxyType, SimpleNamespace
+
+from a2a.auth.user import UnauthenticatedUser
+from a2a.server.context import ServerCallContext
+
+from opencode_a2a.server.context_helpers import (
+    AuthenticatedIdentityUser,
+    normalize_server_call_context,
+)
+
+
+def test_normalize_server_call_context_preserves_existing_normalized_context() -> None:
+    context = ServerCallContext(
+        state={"identity": "opaque:test-user"},
+        tenant="tenant-1",
+        requested_extensions={"ext-a"},
+        user=AuthenticatedIdentityUser("opaque:test-user"),
+    )
+
+    normalized = normalize_server_call_context(context)
+
+    assert normalized is context
+    assert normalized.user.is_authenticated is True
+    assert normalized.user.user_name == "opaque:test-user"
+
+
+def test_normalize_server_call_context_coerces_mapping_and_promotes_identity_user() -> None:
+    context = SimpleNamespace(
+        state=MappingProxyType({"identity": "opaque:test-user", "trace_id": "abc123"}),
+        tenant=123,
+        requested_extensions=["ext-a", 7, "ext-a"],
+        user=UnauthenticatedUser(),
+    )
+
+    normalized = normalize_server_call_context(context)
+
+    assert normalized is not context
+    assert normalized.state == {"identity": "opaque:test-user", "trace_id": "abc123"}
+    assert isinstance(normalized.state, dict)
+    assert normalized.tenant == ""
+    assert normalized.requested_extensions == {"ext-a", "7"}
+    assert normalized.user.is_authenticated is True
+    assert normalized.user.user_name == "opaque:test-user"
+
+
+def test_normalize_server_call_context_falls_back_for_invalid_shapes() -> None:
+    context = SimpleNamespace(
+        state=object(),
+        tenant="tenant-3",
+        requested_extensions=object(),
+        user="not-a-user",
+    )
+
+    normalized = normalize_server_call_context(context)
+
+    assert normalized.state == {}
+    assert normalized.tenant == "tenant-3"
+    assert normalized.requested_extensions == set()
+    assert isinstance(normalized.user, UnauthenticatedUser)