tesseron 0.1.0__tar.gz

tesseron-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+dist/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+*.egg-info/
+.claude/

tesseron-0.1.0/LICENSE

@@ -0,0 +1,114 @@
+Business Source License 1.1
+
+License text copyright (c) 2020 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+-----------------------------------------------------------------------------
+
+Parameters
+
+Licensor:             Kenny Vaneetvelde
+
+Licensed Work:        Tesseron
+                      The Licensed Work is (c) 2026 Kenny Vaneetvelde.
+
+Additional Use Grant: You may make production use of the Licensed Work,
+                      provided your use does not include offering the
+                      Licensed Work, or a substantial portion of its
+                      functionality, to third parties as a hosted or
+                      managed service.
+
+                      For clarity, permitted uses include (but are not
+                      limited to): embedding the Licensed Work in your
+                      own applications (commercial or otherwise),
+                      internal use within your organization, consulting
+                      engagements that integrate the Licensed Work into
+                      client applications, redistributing modified or
+                      unmodified copies of the Licensed Work, and running
+                      the gateway locally on end-user machines as part
+                      of the user's own tooling.
+
+Change Date:          Four years from the date the Licensed Work is
+                      published. For each release of the Licensed Work,
+                      the Change Date is four years from the publication
+                      date of that release.
+
+Change License:       Apache License, Version 2.0
+
+-----------------------------------------------------------------------------
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first
+publicly available distribution of a specific version of the Licensed Work
+under this License, whichever comes first, the Licensor hereby grants you
+rights under the terms of the Change License, and the rights granted in the
+paragraph above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may
+vary for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified
+copy of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in
+this License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, NON-INFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+-----------------------------------------------------------------------------
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to
+all other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License
+   can be included in a program with software provided under GPL Version 2.0
+   or a later version. Licensor may specify additional Change Licenses
+   without limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License,
+   as the Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.
+
+-----------------------------------------------------------------------------
+
+Notice
+
+The Business Source License (this document, or the "License") is not an
+Open Source license. However, the Licensed Work will eventually be made
+available under an Open Source License, as stated in this License.

tesseron-0.1.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.5
+Name: tesseron
+Version: 0.1.0
+Summary: Expose typed application actions to MCP-compatible AI agents over WebSocket.
+Project-URL: Homepage, https://eigenwise.github.io/tesseron/
+Project-URL: Documentation, https://eigenwise.github.io/tesseron/sdk/python/
+Project-URL: Repository, https://github.com/Eigenwise/tesseron-python
+Project-URL: Issues, https://github.com/Eigenwise/tesseron/issues
+Author-email: Kenny Vaneetvelde <kenny@eigenwise.io>
+License-Expression: BUSL-1.1
+License-File: LICENSE
+Keywords: agents,json-rpc,mcp,tesseron,websocket
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.7
+Requires-Dist: websockets>=14
+Description-Content-Type: text/markdown
+
+# tesseron (Python)
+
+The Python SDK lives at [Eigenwise/tesseron-python](https://github.com/Eigenwise/tesseron-python).
+The [Tesseron hub](https://github.com/Eigenwise/tesseron) owns the protocol, docs, and issues.
+
+The Python implementation of the [Tesseron](https://eigenwise.github.io/tesseron/) host
+protocol. Your application listens on loopback, the MCP gateway dials in, and the agent
+gets typed actions and readable resources instead of a scraper.
+
+Speaks protocol **1.2.0**. Compatibility is decided by protocol version, never by matching
+package numbers: see the
+[compatibility contract](https://eigenwise.github.io/tesseron/protocol/compatibility/).
+
+Not on PyPI yet.
+
+## Install
+
+```bash
+uv add tesseron
+```
+
+Python 3.11 or newer. The only runtime dependencies are Pydantic v2 and `websockets`.
+
+## A first action
+
+```python
+import asyncio
+
+from pydantic import BaseModel, Field
+from tesseron import ActionContext, TesseronApp
+
+app = TesseronApp(id="todo", name="Todo", origin="http://127.0.0.1")
+
+
+class AddTodo(BaseModel):
+    text: str = Field(min_length=1)
+    tag: str | None = None
+
+
+@app.action("addTodo", description="Add one todo")
+async def add_todo(input: AddTodo, context: ActionContext) -> dict[str, object]:
+    await context.progress(percent=100, message="saved")
+    return {"id": "1", "text": input.text, "done": False, "tag": input.tag}
+
+
+async def main() -> None:
+    host = await app.listen()
+    print(host.url)
+    await asyncio.Event().wait()
+
+
+asyncio.run(main())
+```
+
+The input type comes from the handler annotation. Its validation-mode JSON Schema is what
+the manifest publishes, and `model_validate` is what rejects bad input with `-32004` before
+the handler body runs.
+
+## What it covers
+
+Handshake and claiming, session resume with in-memory token rotation, action invocation
+with validation, cancellation, timeouts, progress, sampling, confirmation, schema-checked
+elicitation, structured logs, and resources with reads, subscriptions, and pushes.
+
+Gateway-minted claims only. WebSocket only: no Unix domain sockets and no host-minted bind
+in this release, so the conformance suite skips those fixtures honestly.
+
+## Examples
+
+From the repo root, run the headless todo app with:
+
+```bash
+uv run --locked --directory sdks/python python -m examples.todo
+```
+
+Run the prompt library with:
+
+```bash
+uv run --locked --directory sdks/python python -m examples.prompts
+```
+
+Each prints a claim code after the gateway connects. In Claude Code with the Tesseron plugin
+loaded, ask Claude to claim that code, then call the actions. The todo app includes the canonical
+`todos://all` resource and the prompt app includes `library` and `lastTest` resources.
+
+Validate both examples against the real gateway with `pnpm example:python:e2e`.
+
+## Development
+
+Run everything from this directory:
+
+```bash
+uv sync --locked
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy --strict src tests
+uv run pytest
+uv build
+```
+
+The conformance host lives in `conformance_host/`, beside the package rather than inside
+it, so the published wheel carries the SDK and nothing else. See
+[the conformance page](https://eigenwise.github.io/tesseron/sdk/python/conformance/) for how
+the runner drives it.
+
+## Documentation
+
+- [Python SDK](https://eigenwise.github.io/tesseron/sdk/python/)
+- [Protocol specification](https://eigenwise.github.io/tesseron/protocol/)
+
+## License
+
+Tesseron is licensed under the [Business Source License 1.1](./LICENSE). Each
+release auto-converts to Apache-2.0, the Change License, four years after
+publication.

tesseron-0.1.0/README.md

@@ -0,0 +1,115 @@
+# tesseron (Python)
+
+The Python SDK lives at [Eigenwise/tesseron-python](https://github.com/Eigenwise/tesseron-python).
+The [Tesseron hub](https://github.com/Eigenwise/tesseron) owns the protocol, docs, and issues.
+
+The Python implementation of the [Tesseron](https://eigenwise.github.io/tesseron/) host
+protocol. Your application listens on loopback, the MCP gateway dials in, and the agent
+gets typed actions and readable resources instead of a scraper.
+
+Speaks protocol **1.2.0**. Compatibility is decided by protocol version, never by matching
+package numbers: see the
+[compatibility contract](https://eigenwise.github.io/tesseron/protocol/compatibility/).
+
+Not on PyPI yet.
+
+## Install
+
+```bash
+uv add tesseron
+```
+
+Python 3.11 or newer. The only runtime dependencies are Pydantic v2 and `websockets`.
+
+## A first action
+
+```python
+import asyncio
+
+from pydantic import BaseModel, Field
+from tesseron import ActionContext, TesseronApp
+
+app = TesseronApp(id="todo", name="Todo", origin="http://127.0.0.1")
+
+
+class AddTodo(BaseModel):
+    text: str = Field(min_length=1)
+    tag: str | None = None
+
+
+@app.action("addTodo", description="Add one todo")
+async def add_todo(input: AddTodo, context: ActionContext) -> dict[str, object]:
+    await context.progress(percent=100, message="saved")
+    return {"id": "1", "text": input.text, "done": False, "tag": input.tag}
+
+
+async def main() -> None:
+    host = await app.listen()
+    print(host.url)
+    await asyncio.Event().wait()
+
+
+asyncio.run(main())
+```
+
+The input type comes from the handler annotation. Its validation-mode JSON Schema is what
+the manifest publishes, and `model_validate` is what rejects bad input with `-32004` before
+the handler body runs.
+
+## What it covers
+
+Handshake and claiming, session resume with in-memory token rotation, action invocation
+with validation, cancellation, timeouts, progress, sampling, confirmation, schema-checked
+elicitation, structured logs, and resources with reads, subscriptions, and pushes.
+
+Gateway-minted claims only. WebSocket only: no Unix domain sockets and no host-minted bind
+in this release, so the conformance suite skips those fixtures honestly.
+
+## Examples
+
+From the repo root, run the headless todo app with:
+
+```bash
+uv run --locked --directory sdks/python python -m examples.todo
+```
+
+Run the prompt library with:
+
+```bash
+uv run --locked --directory sdks/python python -m examples.prompts
+```
+
+Each prints a claim code after the gateway connects. In Claude Code with the Tesseron plugin
+loaded, ask Claude to claim that code, then call the actions. The todo app includes the canonical
+`todos://all` resource and the prompt app includes `library` and `lastTest` resources.
+
+Validate both examples against the real gateway with `pnpm example:python:e2e`.
+
+## Development
+
+Run everything from this directory:
+
+```bash
+uv sync --locked
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy --strict src tests
+uv run pytest
+uv build
+```
+
+The conformance host lives in `conformance_host/`, beside the package rather than inside
+it, so the published wheel carries the SDK and nothing else. See
+[the conformance page](https://eigenwise.github.io/tesseron/sdk/python/conformance/) for how
+the runner drives it.
+
+## Documentation
+
+- [Python SDK](https://eigenwise.github.io/tesseron/sdk/python/)
+- [Protocol specification](https://eigenwise.github.io/tesseron/protocol/)
+
+## License
+
+Tesseron is licensed under the [Business Source License 1.1](./LICENSE). Each
+release auto-converts to Apache-2.0, the Change License, four years after
+publication.

tesseron-0.1.0/pyproject.toml

@@ -0,0 +1,80 @@
+[project]
+name = "tesseron"
+version = "0.1.0"
+description = "Expose typed application actions to MCP-compatible AI agents over WebSocket."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "BUSL-1.1"
+authors = [{ name = "Kenny Vaneetvelde", email = "kenny@eigenwise.io" }]
+keywords = ["tesseron", "mcp", "agents", "websocket", "json-rpc"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = ["pydantic>=2.7", "websockets>=14"]
+
+[project.urls]
+Homepage = "https://eigenwise.github.io/tesseron/"
+Documentation = "https://eigenwise.github.io/tesseron/sdk/python/"
+Repository = "https://github.com/Eigenwise/tesseron-python"
+Issues = "https://github.com/Eigenwise/tesseron/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+# The conformance host lives beside the package rather than inside it, so the
+# published wheel carries the SDK and nothing else.
+[tool.hatch.build.targets.wheel]
+packages = ["src/tesseron"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "pyproject.toml"]
+
+[dependency-groups]
+dev = ["mypy>=1.11", "pytest>=8.3", "pytest-asyncio>=0.24", "ruff>=0.6"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src", "tests", "conformance_host"]
+
+[tool.ruff.lint]
+select = [
+    "A",
+    "ANN",
+    "ASYNC",
+    "B",
+    "BLE",
+    "C4",
+    "E",
+    "F",
+    "I",
+    "N",
+    "PTH",
+    "RUF",
+    "SIM",
+    "UP",
+    "W",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["ANN401"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+# The conformance host sits outside the package, so the tests that cover it need this
+# directory on the path.
+pythonpath = ["."]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+mypy_path = ["src", "."]

tesseron-0.1.0/src/tesseron/__init__.py

@@ -0,0 +1,98 @@
+"""Tesseron: expose typed application actions to MCP-compatible AI agents over WebSocket.
+
+The application listens and the gateway dials in. Build a :class:`TesseronApp`, register
+actions and resources on it, ``await app.listen()``, and hand the gateway the manifest the
+host writes.
+"""
+
+from __future__ import annotations
+
+from .action import ActionHandler, InputValidator, TypedActionHandler, ValidationIssue
+from .context import ActionContext, Cancellation
+from .errors import (
+    ActionError,
+    DuplicateNameError,
+    HostError,
+    InvalidApplicationIdError,
+    ManifestError,
+    MissingApplicationError,
+    ProtocolError,
+    TesseronErrorCode,
+)
+from .host import (
+    ClaimedEvent,
+    DisconnectedEvent,
+    HandshakeFailedEvent,
+    HostEvent,
+    HostEventListener,
+    TesseronApp,
+    TesseronHost,
+    WelcomeEvent,
+)
+from .json_types import JsonObject, JsonValue
+from .manifest import InstanceManifest, ManifestPublication
+from .protocol import (
+    GATEWAY_SUBPROTOCOL,
+    PROTOCOL_VERSION,
+    ActionDescriptor,
+    AgentIdentity,
+    ApplicationDescriptor,
+    Capabilities,
+    ClaimedParams,
+    LogLevel,
+    ResourceDescriptor,
+    WelcomeResult,
+)
+from .resource import (
+    Emit,
+    Resource,
+    ResourceReader,
+    SubscribeCallback,
+    Subscription,
+    Unsubscribe,
+)
+
+__all__ = [
+    "GATEWAY_SUBPROTOCOL",
+    "PROTOCOL_VERSION",
+    "ActionContext",
+    "ActionDescriptor",
+    "ActionError",
+    "ActionHandler",
+    "AgentIdentity",
+    "ApplicationDescriptor",
+    "Cancellation",
+    "Capabilities",
+    "ClaimedEvent",
+    "ClaimedParams",
+    "DisconnectedEvent",
+    "DuplicateNameError",
+    "Emit",
+    "HandshakeFailedEvent",
+    "HostError",
+    "HostEvent",
+    "HostEventListener",
+    "InputValidator",
+    "InstanceManifest",
+    "InvalidApplicationIdError",
+    "JsonObject",
+    "JsonValue",
+    "LogLevel",
+    "ManifestError",
+    "ManifestPublication",
+    "MissingApplicationError",
+    "ProtocolError",
+    "Resource",
+    "ResourceDescriptor",
+    "ResourceReader",
+    "SubscribeCallback",
+    "Subscription",
+    "TesseronApp",
+    "TesseronErrorCode",
+    "TesseronHost",
+    "TypedActionHandler",
+    "Unsubscribe",
+    "ValidationIssue",
+    "WelcomeEvent",
+    "WelcomeResult",
+]

tesseron-0.1.0/src/tesseron/action.py

@@ -0,0 +1,142 @@
+"""One action the agent can invoke, and the input contract it publishes."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Coroutine, Mapping, Sequence
+from dataclasses import dataclass
+from enum import Enum
+from typing import TypeAlias, TypeVar
+
+from pydantic import BaseModel, ValidationError
+
+from .context import ActionContext
+from .errors import ActionError, TesseronErrorCode
+from .json_types import JsonObject, JsonValue
+from .protocol import ActionDescriptor
+
+__all__ = [
+    "ActionHandler",
+    "InputValidator",
+    "LooseHandler",
+    "RegisteredAction",
+    "TypedActionHandler",
+    "ValidationIssue",
+    "to_json_value",
+]
+
+InputModel = TypeVar("InputModel", bound=BaseModel)
+
+TypedActionHandler: TypeAlias = "Callable[[InputModel, ActionContext], Awaitable[object]]"
+"""A handler whose first parameter is annotated with a Pydantic model."""
+
+ActionHandler: TypeAlias = "Callable[[JsonValue, ActionContext], Awaitable[object]]"
+"""A handler that takes the invocation input as raw JSON."""
+
+LooseHandler: TypeAlias = "Callable[..., Awaitable[object]]"
+"""Either handler shape.
+
+Registration reads the handler's annotations at runtime, so the decorator cannot know
+statically which of the two shapes it was handed.
+"""
+
+DispatchHandler: TypeAlias = (
+    "Callable[[JsonValue, ActionContext], Coroutine[object, object, JsonValue]]"
+)
+"""What the session runs: input validation folded in, output already JSON.
+
+Concretely a coroutine rather than any awaitable, because the session runs each invocation
+as its own task so it can race the handler against cancellation and the timeout.
+"""
+
+InputValidator: TypeAlias = "Callable[[JsonValue], list[ValidationIssue]]"
+"""Checks raw invocation input and answers every problem it finds."""
+
+
+@dataclass(frozen=True)
+class ValidationIssue:
+    """One reason invocation input was refused, reported inside a ``-32004`` failure."""
+
+    message: str
+    path: list[str]
+
+    def to_wire(self) -> JsonObject:
+        """The issue as it appears in the error ``data`` member."""
+        return {"message": self.message, "path": list(self.path)}
+
+
+@dataclass(frozen=True)
+class RegisteredAction:
+    """An action the host has accepted, ready for the session to dispatch."""
+
+    descriptor: ActionDescriptor
+    dispatch: DispatchHandler
+
+
+def to_json_value(value: object) -> JsonValue:
+    """Converts handler output into the JSON the invocation result carries.
+
+    Pydantic models, primitives, sequences, mappings, and enums are understood. Anything
+    else has no defined wire shape, so it fails as an internal error rather than reaching
+    the agent as a string of a repr.
+    """
+    if value is None or isinstance(value, bool | int | float | str):
+        return value
+    if isinstance(value, BaseModel):
+        converted: JsonValue = value.model_dump(mode="json")
+        return converted
+    if isinstance(value, Enum):
+        return to_json_value(value.value)
+    if isinstance(value, Mapping):
+        return {str(key): to_json_value(item) for key, item in value.items()}
+    if isinstance(value, Sequence):
+        return [to_json_value(item) for item in value]
+    raise ActionError.internal(
+        TypeError(f"an action returned {type(value).__name__}, which has no JSON form")
+    )
+
+
+def issues_from_validation_error(error: ValidationError) -> list[ValidationIssue]:
+    """Normalises a Pydantic failure into the issue list a ``-32004`` failure carries."""
+    return [
+        ValidationIssue(message=detail["msg"], path=[str(segment) for segment in detail["loc"]])
+        for detail in error.errors()
+    ]
+
+
+def input_validation_error(issues: list[ValidationIssue]) -> ActionError:
+    """The ``-32004`` failure for input that did not satisfy the declared schema."""
+    return ActionError.protocol(
+        TesseronErrorCode.INPUT_VALIDATION,
+        "Invalid input",
+        [issue.to_wire() for issue in issues],
+    )
+
+
+def typed_dispatch(model: type[InputModel], handler: LooseHandler) -> DispatchHandler:
+    """Wraps a model-annotated handler so the session sees one raw-JSON entry point.
+
+    The model is validated before the handler body runs, so an action whose input does not
+    fit its declared shape never reaches application code.
+    """
+
+    async def dispatch(raw_input: JsonValue, context: ActionContext) -> JsonValue:
+        try:
+            parsed = model.model_validate(raw_input)
+        except ValidationError as problem:
+            raise input_validation_error(issues_from_validation_error(problem)) from problem
+        return to_json_value(await handler(parsed, context))
+
+    return dispatch
+
+
+def raw_dispatch(handler: LooseHandler, validator: InputValidator | None) -> DispatchHandler:
+    """Wraps a raw-JSON handler, running the optional validator before the handler body."""
+
+    async def dispatch(raw_input: JsonValue, context: ActionContext) -> JsonValue:
+        if validator is not None:
+            issues = validator(raw_input)
+            if issues:
+                raise input_validation_error(issues)
+        return to_json_value(await handler(raw_input, context))
+
+    return dispatch