agentship-service 0.0.1__tar.gz

agentship_service-0.0.1/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Env / secrets — never commit
+.env
+.env.*
+!.env.example
+
+# Editor / OS
+.DS_Store
+.idea/
+.vscode/
+
+# Docs build
+site/

agentship_service-0.0.1/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.5
+Name: agentship-service
+Version: 0.0.1
+Summary: AgentShip runtime service — the REST/SSE/WS surface over an agent, with pluggable auth adapters and tenant isolation. The irreducible in-app core a gateway cannot replace.
+License-Expression: Apache-2.0
+Requires-Python: >=3.13
+Requires-Dist: agentship-core==0.0.1
+Requires-Dist: fastapi>=0.115
+Requires-Dist: sse-starlette>=2.1
+Provides-Extra: a2a
+Requires-Dist: a2a-sdk<2,>=1.1; extra == 'a2a'
+Provides-Extra: serve
+Requires-Dist: uvicorn[standard]>=0.30; extra == 'serve'
+Description-Content-Type: text/markdown
+
+# agentship-service
+
+The AgentShip **runtime service** — the REST / SSE / WebSocket surface that turns a built
+agent into an HTTP API, with pluggable authentication adapters and, above all, **tenant
+isolation**.
+
+This is the part of the stack a gateway *cannot* replace. A gateway (agentgateway) routes
+requests and can authenticate them at the edge; but only the app can guarantee that every
+stored read and write is scoped to the authenticated tenant. That guarantee lives here.
+
+```python
+from agentship.auth import ApiKeyAuthProvider, EnvApiKeyStore
+from agentship_service import create_app
+
+app = create_app(auth=ApiKeyAuthProvider(EnvApiKeyStore()))
+```
+
+## Integrations (we wire, we don't reinvent)
+
+- **Streaming** — `/v1 …:stream` and A2A `message/stream` frame Server-Sent Events with
+  [`sse-starlette`](https://github.com/sysid/sse-starlette)'s `EventSourceResponse`, which owns
+  the wire encoding, keepalive comments, and client-disconnect cancellation. We only shape each
+  `StreamEvent` into its event/data fields.
+- **Auth** — `agentship.auth` ships pluggable providers; the optional OIDC path
+  (`JwtAuthProvider`) delegates JWKS fetching, key-id resolution, and rotation to PyJWT's
+  `PyJWKClient`. Tenant isolation on every read/write is the part that stays here.
+- **A2A** — we speak the protocol with our own thin Pydantic wire models rather than pull in the
+  protobuf-first `a2a-sdk`. A drift guard under the `agentship-service[a2a]` extra
+  (`tests/test_a2a_conformance.py`) validates every AgentCard / Message / status frame against
+  `a2a-sdk`'s own schema, so we cannot drift from the spec. See
+  [`docs/decisions/0001-integrate-not-invent.md`](../../docs/decisions/0001-integrate-not-invent.md).
+
+See `agentship serve` for the one-command server, and the phase-04 spec for the full
+endpoint contract.

agentship_service-0.0.1/README.md

@@ -0,0 +1,34 @@
+# agentship-service
+
+The AgentShip **runtime service** — the REST / SSE / WebSocket surface that turns a built
+agent into an HTTP API, with pluggable authentication adapters and, above all, **tenant
+isolation**.
+
+This is the part of the stack a gateway *cannot* replace. A gateway (agentgateway) routes
+requests and can authenticate them at the edge; but only the app can guarantee that every
+stored read and write is scoped to the authenticated tenant. That guarantee lives here.
+
+```python
+from agentship.auth import ApiKeyAuthProvider, EnvApiKeyStore
+from agentship_service import create_app
+
+app = create_app(auth=ApiKeyAuthProvider(EnvApiKeyStore()))
+```
+
+## Integrations (we wire, we don't reinvent)
+
+- **Streaming** — `/v1 …:stream` and A2A `message/stream` frame Server-Sent Events with
+  [`sse-starlette`](https://github.com/sysid/sse-starlette)'s `EventSourceResponse`, which owns
+  the wire encoding, keepalive comments, and client-disconnect cancellation. We only shape each
+  `StreamEvent` into its event/data fields.
+- **Auth** — `agentship.auth` ships pluggable providers; the optional OIDC path
+  (`JwtAuthProvider`) delegates JWKS fetching, key-id resolution, and rotation to PyJWT's
+  `PyJWKClient`. Tenant isolation on every read/write is the part that stays here.
+- **A2A** — we speak the protocol with our own thin Pydantic wire models rather than pull in the
+  protobuf-first `a2a-sdk`. A drift guard under the `agentship-service[a2a]` extra
+  (`tests/test_a2a_conformance.py`) validates every AgentCard / Message / status frame against
+  `a2a-sdk`'s own schema, so we cannot drift from the spec. See
+  [`docs/decisions/0001-integrate-not-invent.md`](../../docs/decisions/0001-integrate-not-invent.md).
+
+See `agentship serve` for the one-command server, and the phase-04 spec for the full
+endpoint contract.

agentship_service-0.0.1/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agentship-service"
+version = "0.0.1"
+description = "AgentShip runtime service — the REST/SSE/WS surface over an agent, with pluggable auth adapters and tenant isolation. The irreducible in-app core a gateway cannot replace."
+readme = "README.md"
+requires-python = ">=3.13"
+license = "Apache-2.0"
+dependencies = [
+    "agentship-core==0.0.1",
+    "fastapi>=0.115",
+    # SSE framing for :stream and A2A message/stream — owns the event:/data: wire encoding,
+    # keepalive comments, and client-disconnect cancellation so we do not hand-frame it.
+    "sse-starlette>=2.1",
+]
+
+# `agentship serve` launches the app under uvicorn. Kept as an extra so importing the
+# app (e.g. behind gunicorn, or in tests) does not require the server, while the
+# documented `pip install "agentship-service[serve]"` gives the one-command server.
+[project.optional-dependencies]
+serve = ["uvicorn[standard]>=0.30"]
+# a2a-sdk is NOT a runtime dep — we speak A2A with our own thin vendor-free wire models
+# (a2a-sdk 1.x is protobuf-first; only its legacy compat.v0_3 layer is Pydantic/JSON). This
+# extra installs it for the schema drift guard (tests/test_a2a_conformance.py), which validates
+# every AgentCard/Message/status frame we emit against a2a-sdk's own schema so we cannot drift
+# from the A2A spec. Heavy (grpc/protobuf), hence opt-in and test-only.
+a2a = ["a2a-sdk>=1.1,<2"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentship_service"]
+# The Studio page is data, not code: name it explicitly so it cannot be dropped from a
+# wheel by a future exclude rule. GET /studio reads this file at request time.
+artifacts = ["src/agentship_service/static/studio.html"]

agentship_service-0.0.1/src/agentship_service/__init__.py

@@ -0,0 +1,14 @@
+"""AgentShip runtime service: the REST / SSE / WebSocket surface over an agent.
+
+This package is the irreducible in-app core a gateway cannot replace: it authenticates
+each request into a :class:`~agentship.context.Caller`, binds a tenant scope so every
+query is filtered to the caller's tenant, and renders every failure as RFC-9457
+problem+json. :func:`create_app` assembles the FastAPI app and its middleware stack.
+"""
+
+from __future__ import annotations
+
+from .app import create_app
+from .registry import AgentRegistry
+
+__all__ = ["AgentRegistry", "create_app"]

agentship_service-0.0.1/src/agentship_service/a2a/__init__.py

@@ -0,0 +1,13 @@
+"""The A2A *server* adapter — exposes a built agent over the A2A protocol (Phase 05 · C4).
+
+This lives in the service package (not core) because it needs the web app: it maps A2A JSON-RPC
+methods (``message/send``, ``message/stream``, ``tasks/*``) onto the ``RunnableAgent`` run/stream
+port and mounts alongside the ``/v1`` routes, so it inherits P04's auth, TLS, and rate-limit.
+The transport-agnostic pieces (wire models, Agent Card generation) live in ``agentship.a2a``.
+"""
+
+from __future__ import annotations
+
+from .server import handle_rpc, stream_rpc
+
+__all__ = ["handle_rpc", "stream_rpc"]

agentship_service-0.0.1/src/agentship_service/a2a/mapping.py

@@ -0,0 +1,64 @@
+"""Translate between A2A wire shapes and AgentShip's run inputs/outputs (§C3 mapping).
+
+One small module so the request handler and the stream handler map identically:
+
+* inbound — an A2A ``message/send`` param block → the plain text an engine's ``run``/``stream``
+  consumes (:func:`message_text`);
+* outbound — an engine :class:`~agentship.engines.base.Result` → an A2A agent ``Message``
+  (:func:`result_message`), and a streamed engine event → an A2A ``TaskStatusUpdate`` frame
+  (:func:`status_update`).
+
+Kept deliberately thin: A2A models the world as Messages/Tasks; we model it as run/stream, and the
+only shapes we translate are the ones we actually serve.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agentship.a2a.models import Message
+
+
+def message_text(params: dict[str, Any]) -> str:
+    """Extract the user text from a ``message/send`` param block.
+
+    A2A carries the turn as ``params.message.parts[]``; we speak text parts, so this joins their
+    ``text`` into the single string the engine runs on. A missing/empty message yields ``""`` — an
+    empty turn, not a crash.
+    """
+    raw = params.get("message") or {}
+    parts = raw.get("parts") or []
+    return "".join(part.get("text", "") for part in parts if part.get("kind", "text") == "text")
+
+
+def result_message(output: Any) -> dict[str, Any]:
+    """Shape an engine result's ``output`` into an A2A agent ``Message`` dict.
+
+    ``message/send`` returns a Message when the turn completes synchronously; the output is
+    rendered as one agent text part (a non-string output is stringified so the wire stays valid).
+    """
+    text = output if isinstance(output, str) else str(output)
+    return Message.agent(text).model_dump(by_alias=True)
+
+
+def status_update(
+    task_id: str, context_id: str, *, state: str, text: str = "", final: bool = False
+) -> dict[str, Any]:
+    """Build an A2A ``TaskStatusUpdate`` result for one streamed step.
+
+    ``task_id`` identifies this task and ``context_id`` the conversation it belongs to — the A2A
+    spec requires both on every status update. ``state`` is the A2A task state (``working`` while
+    tokens flow, ``completed``/``failed`` at the end); ``text`` carries the incremental agent text
+    for this step; ``final`` marks the last frame so a client knows the stream is done. This is the
+    streamed analogue of :func:`result_message`.
+    """
+    update: dict[str, Any] = {
+        "kind": "status-update",
+        "taskId": task_id,
+        "contextId": context_id,
+        "status": {"state": state},
+        "final": final,
+    }
+    if text:
+        update["status"]["message"] = Message.agent(text).model_dump(by_alias=True)
+    return update

agentship_service-0.0.1/src/agentship_service/a2a/server.py

@@ -0,0 +1,96 @@
+"""Dispatch A2A JSON-RPC methods onto a built agent (§C4 adapter).
+
+The A2A method table maps onto the same ``BaseAgent`` run/stream port the ``/v1`` routes use, so
+an agent exposed over A2A behaves identically to one invoked directly — one runtime, two protocols:
+
+* ``message/send``  → :meth:`RunnableAgent.run`   → an A2A agent ``Message`` result.
+* ``message/stream`` → :meth:`RunnableAgent.stream` → SSE frames of A2A ``TaskStatusUpdate``
+  results, reusing the ``/v1`` SSE event normalisation so both surfaces stream the same events.
+
+Long-running ``tasks/*`` methods are recognised and answered with a not-implemented JSON-RPC error
+for now (they land with the P11 task bridge, C5); an unknown method returns the standard JSON-RPC
+"method not found" (-32601) rather than crashing.
+"""
+
+from __future__ import annotations
+
+import json
+import uuid
+from collections.abc import AsyncIterator
+
+from agentship.a2a.models import JsonRpcRequest, JsonRpcResponse
+from agentship.context import Caller
+from agentship.runtime import RunnableAgent
+
+from ..routers._common import frame_data, frame_type
+from .mapping import message_text, result_message, status_update
+
+#: JSON-RPC "method not found" per the spec, returned for any method we do not serve.
+_METHOD_NOT_FOUND = -32601
+
+#: Task lifecycle methods A2A defines but we do not serve yet (they arrive with the P11 bridge).
+_DEFERRED_TASK_METHODS = frozenset(
+    {"tasks/get", "tasks/cancel", "tasks/resubscribe", "tasks/pushNotificationConfig/set"}
+)
+
+
+async def handle_rpc(agent: RunnableAgent, caller: Caller, req: JsonRpcRequest) -> JsonRpcResponse:
+    """Handle a non-streaming A2A method, returning a JSON-RPC response envelope.
+
+    Only ``message/send`` runs the agent today; ``tasks/*`` are recognised-but-deferred and any
+    other method is a "method not found" error. A recognised-but-deferred or unknown method is a
+    JSON-RPC *error*, never an HTTP error — the transport call succeeded, the method did not.
+    """
+    if req.method == "message/send":
+        text = message_text(req.params)
+        result = await agent.run(text, caller=caller, session_id=uuid.uuid4().hex)
+        return JsonRpcResponse.ok(req.id, result_message(result.output))
+    if req.method in _DEFERRED_TASK_METHODS:
+        return JsonRpcResponse.fail(
+            req.id, _METHOD_NOT_FOUND, f"method {req.method!r} is not implemented yet (P11 tasks)"
+        )
+    return JsonRpcResponse.fail(req.id, _METHOD_NOT_FOUND, f"unknown method {req.method!r}")
+
+
+async def stream_rpc(
+    agent: RunnableAgent, caller: Caller, req: JsonRpcRequest
+) -> AsyncIterator[dict]:
+    """Stream an A2A ``message/stream`` turn as SSE JSON-RPC frames of task status updates.
+
+    Each engine event with text becomes a ``working`` status update carrying that text; the stream
+    always ends with a terminal frame — ``completed`` on success, ``failed`` if the engine raised
+    mid-stream (the HTTP status was already 200 once streaming began, so a failure is delivered as
+    a final frame, mirroring the ``/v1`` stream contract).
+    """
+    task_id = uuid.uuid4().hex
+    # The context id groups every update of this turn under one A2A conversation; one per stream.
+    context_id = uuid.uuid4().hex
+    text = message_text(req.params)
+    try:
+        async for event in agent.stream(text, caller=caller, session_id=task_id):
+            chunk = _event_text(event)
+            if chunk:
+                yield _sse(req.id, status_update(task_id, context_id, state="working", text=chunk))
+        yield _sse(req.id, status_update(task_id, context_id, state="completed", final=True))
+    except Exception as exc:  # noqa: BLE001 — a mid-stream failure becomes a terminal failed frame
+        yield _sse(
+            req.id, status_update(task_id, context_id, state="failed", text=str(exc), final=True)
+        )
+
+
+def _event_text(event) -> str:
+    """Pull the incremental agent text out of one engine event (empty for non-text events)."""
+    data = frame_data(event)
+    if frame_type(event.type) in ("token", "content"):
+        return data.get("content") or data.get("token") or ""
+    return ""
+
+
+def _sse(req_id, result: dict) -> dict:
+    """Shape one JSON-RPC response as ``sse-starlette`` ``ServerSentEvent`` fields.
+
+    A2A streams JSON-RPC responses over SSE with only a ``data:`` payload; sse-starlette
+    frames it (and adds keepalive comments / disconnect handling) via EventSourceResponse.
+    """
+    body = JsonRpcResponse.ok(req_id, result).model_dump(by_alias=True)
+    return {"data": json.dumps(body)}

agentship_service-0.0.1/src/agentship_service/app.py

@@ -0,0 +1,91 @@
+"""``create_app`` — assemble the runtime-service FastAPI app with its middleware stack.
+
+The middleware are mounted in one documented order (outermost → innermost):
+
+    CORS → SecurityHeaders (+ trace id) → Auth (+ TenantScope) → router
+
+so a request is CORS-checked, stamped, rate-limited (when enabled, P04 C5), and
+authenticated *before* any route runs, and a CORS preflight (``OPTIONS``) short-circuits at
+the outermost layer without ever reaching authentication. Error handlers render every
+failure as RFC-9457 problem+json. The agent/discovery/task routers are attached here as
+they land (P04 C1); this module owns the wiring, not the routes.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from agentship.auth import AuthProvider
+from fastapi import FastAPI
+from starlette.middleware.cors import CORSMiddleware
+
+from .build_info import build_info
+from .errors import install_error_handlers
+from .middleware import AuthMiddleware, RateLimitMiddleware, SecurityHeadersMiddleware
+from .registry import AgentRegistry
+from .routers import a2a_router, agents_router, live_router, studio_router, tasks_router
+from .routers.tasks import TaskStore
+
+
+def create_app(
+    *,
+    auth: AuthProvider,
+    agents: AgentRegistry | None = None,
+    cors_origins: Sequence[str] = (),
+    hsts: bool = False,
+    rate_limit: bool = False,
+    requests_per_second: float = 10.0,
+    rate_limit_burst: int = 20,
+    title: str = "AgentShip",
+) -> FastAPI:
+    """Build the runtime-service app authenticated by ``auth`` serving ``agents``.
+
+    ``agents`` is the catalog the v1 routes invoke and discover (an empty registry when
+    omitted). ``cors_origins`` is an explicit allow-list (never ``*`` with credentials);
+    ``hsts`` turns on Strict-Transport-Security for a TLS deployment. ``rate_limit`` enables
+    the optional in-process token-bucket limiter (off by default — a gateway-free safety
+    net only; real rate-limiting is agentgateway's job). The returned app already has a
+    public ``GET /healthz`` liveness probe, the public ``GET /studio`` debug UI, the v1
+    agent + task routers, and the problem+json error handlers installed.
+    """
+    app = FastAPI(title=title, docs_url="/docs", redoc_url="/redoc")
+    app.state.agents = agents if agents is not None else AgentRegistry()
+    app.state.tasks = TaskStore()
+    install_error_handlers(app)
+
+    @app.get("/healthz", include_in_schema=False)
+    async def healthz() -> dict[str, object]:
+        """Unauthenticated liveness probe, carrying which build is answering.
+
+        The build stamp and package versions are here so a caller can tell *what code*
+        is running without shelling into the container — the question "is this the
+        latest?" should be answerable from outside.
+        """
+        return {"status": "ok", **build_info()}
+
+    app.include_router(agents_router)
+    app.include_router(live_router)
+    app.include_router(studio_router)
+    app.include_router(tasks_router)
+    app.include_router(a2a_router)
+
+    # Mount inner → outer. add_middleware makes each call the new outermost layer, so the
+    # last call (CORS) runs first on a request and the first call (Auth) runs last. The
+    # resulting request-path order is CORS → SecurityHeaders → RateLimit → Auth → router.
+    app.add_middleware(AuthMiddleware, auth=auth)
+    app.add_middleware(
+        RateLimitMiddleware,
+        enabled=rate_limit,
+        requests_per_second=requests_per_second,
+        burst=rate_limit_burst,
+    )
+    app.add_middleware(SecurityHeadersMiddleware, hsts=hsts)
+    if cors_origins:
+        app.add_middleware(
+            CORSMiddleware,
+            allow_origins=list(cors_origins),
+            allow_credentials=True,
+            allow_methods=["GET", "POST", "OPTIONS"],
+            allow_headers=["authorization", "content-type", "x-api-key"],
+        )
+    return app

agentship_service-0.0.1/src/agentship_service/build_info.py

@@ -0,0 +1,51 @@
+"""Report which AgentShip build is running.
+
+A deployment that cannot tell you what code it is running is a deployment you cannot
+trust a bug report against. The package version alone is not enough here — every package
+is pinned at ``0.0.1`` and does not move between builds — so the image also stamps a build
+id at build time (``AGENTSHIP_BUILD``, typically a git sha or a timestamp).
+"""
+
+from __future__ import annotations
+
+import os
+from importlib.metadata import PackageNotFoundError, version
+
+#: The distributions that make up a running service, in the order a reader cares about.
+PACKAGES = (
+    "agentship-core",
+    "agentship-langgraph",
+    "agentship-service",
+    "agentship-cli",
+    "agentship-observability",
+)
+
+
+def installed_versions() -> dict[str, str]:
+    """Return ``{distribution: version}`` for every AgentShip package that is installed.
+
+    A package that is not installed is simply absent, so the result also shows which
+    extras a deployment actually has — an image without ``agentship-observability`` is
+    visibly different from one that has it.
+    """
+    found: dict[str, str] = {}
+    for name in PACKAGES:
+        try:
+            found[name] = version(name)
+        except PackageNotFoundError:
+            continue
+    return found
+
+
+def build_id() -> str:
+    """The image's build stamp from ``AGENTSHIP_BUILD``, or ``"dev"`` when unset.
+
+    Set it at image build time (a git sha, or a timestamp) so two images built from
+    different source are distinguishable even though the package versions match.
+    """
+    return os.environ.get("AGENTSHIP_BUILD") or "dev"
+
+
+def build_info() -> dict[str, object]:
+    """The full build description: the build stamp plus every installed package version."""
+    return {"build": build_id(), "packages": installed_versions()}

agentship_service-0.0.1/src/agentship_service/context.py

@@ -0,0 +1,60 @@
+"""Per-request service state: the authenticated caller and the trace id.
+
+The auth middleware binds the :class:`~agentship.context.Caller` for a request here; route
+handlers and the :func:`~agentship_service.middleware.auth.require_scope` dependency read it
+back. Both live in contextvars so concurrent requests never see each other's identity, and
+so a handler need not thread the caller through every signature.
+
+The trace id is minted (or adopted from an inbound ``x-request-id``) per request and echoed
+into responses and error bodies, giving one id to correlate a request across logs and — once
+P07 lands — the span tree.
+"""
+
+from __future__ import annotations
+
+from contextvars import ContextVar, Token
+
+from agentship.context import Caller
+from agentship.errors import AgentShipError
+
+_current_caller: ContextVar[Caller | None] = ContextVar("service_current_caller", default=None)
+_current_trace_id: ContextVar[str | None] = ContextVar("service_current_trace_id", default=None)
+
+
+def bind_caller(caller: Caller) -> Token[Caller | None]:
+    """Bind ``caller`` for the current request; returns a token to :func:`reset_caller`."""
+    return _current_caller.set(caller)
+
+
+def reset_caller(token: Token[Caller | None]) -> None:
+    """Restore the caller binding captured by :func:`bind_caller`."""
+    _current_caller.reset(token)
+
+
+def current_caller() -> Caller:
+    """Return the authenticated caller for this request, or raise if none is bound.
+
+    A missing caller means a handler ran outside the auth middleware — a bug to surface,
+    never an anonymous fallback.
+    """
+    caller = _current_caller.get()
+    if caller is None:
+        raise AgentShipError(
+            "no authenticated caller is bound — the request bypassed the auth middleware"
+        )
+    return caller
+
+
+def bind_trace_id(trace_id: str) -> Token[str | None]:
+    """Bind the trace id for the current request; returns a token to :func:`reset_trace_id`."""
+    return _current_trace_id.set(trace_id)
+
+
+def reset_trace_id(token: Token[str | None]) -> None:
+    """Restore the trace-id binding captured by :func:`bind_trace_id`."""
+    _current_trace_id.reset(token)
+
+
+def current_trace_id() -> str | None:
+    """Return the trace id bound for this request, or ``None`` outside a request."""
+    return _current_trace_id.get()