ya-environment-relay 0.74.0__tar.gz

ya_environment_relay-0.74.0/.gitignore

@@ -0,0 +1,169 @@
+docs/source
+
+# From https://raw.githubusercontent.com/github/gitignore/main/Python.gitignore
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+!apps/
+!apps/ya-claw-web/
+!apps/ya-claw-web/src/
+!apps/ya-claw-web/src/lib/
+!apps/ya-claw-web/src/lib/**
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.yaai/
+**/.yaai/
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.pyright/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# Vscode config files
+# .vscode/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+TO-DO.json
+dev/
+ya_agent_sdk/sandbox/shell/templates/public
+
+# Sync automaticlly
+yaacli/yaacli/skills/building-agents
+
+# Frontend
+node_modules/
+apps/*/dist/
+!apps/ya-desktop/
+!apps/ya-desktop/src/
+!apps/ya-desktop/src/**
+!apps/ya-desktop/src-tauri/
+!apps/ya-desktop/src-tauri/resources/
+!apps/ya-desktop/src-tauri/resources/uv/
+!apps/ya-desktop/src-tauri/resources/uv/.gitkeep
+apps/ya-desktop/src-tauri/resources/uv/uv
+apps/ya-desktop/src-tauri/resources/uv/uv.exe
+*.tsbuildinfo

ya_environment_relay-0.74.0/PKG-INFO

@@ -0,0 +1,36 @@
+Metadata-Version: 2.4
+Name: ya-environment-relay
+Version: 0.74.0
+Summary: Provider-neutral relay protocol for YA agent environments
+Project-URL: Repository, https://github.com/wh1isper/ya-mono
+Author-email: wh1isper <jizhongsheng957@gmail.com>
+Keywords: agent,environment,protocol,python,relay
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: <3.14,>=3.11
+Requires-Dist: pydantic>=2.0.0
+Description-Content-Type: text/markdown
+
+# ya-environment-relay
+
+Provider-neutral relay protocol for YA agent environments.
+
+`ya-environment-relay` defines how external execution capabilities are exposed to an agent runtime as Environment components.
+
+Capability families:
+
+- file operations
+- shell execution
+- custom tools
+- resources
+- artifacts
+- computer use
+
+The protocol string is `ya-environment-relay.v1`.
+
+See [`spec/`](spec/) for the protocol documents.

ya_environment_relay-0.74.0/README.md

@@ -0,0 +1,18 @@
+# ya-environment-relay
+
+Provider-neutral relay protocol for YA agent environments.
+
+`ya-environment-relay` defines how external execution capabilities are exposed to an agent runtime as Environment components.
+
+Capability families:
+
+- file operations
+- shell execution
+- custom tools
+- resources
+- artifacts
+- computer use
+
+The protocol string is `ya-environment-relay.v1`.
+
+See [`spec/`](spec/) for the protocol documents.

ya_environment_relay-0.74.0/pyproject.toml

@@ -0,0 +1,60 @@
+[project]
+name = "ya-environment-relay"
+dynamic = ["version"]
+description = "Provider-neutral relay protocol for YA agent environments"
+authors = [{ name = "wh1isper", email = "jizhongsheng957@gmail.com" }]
+readme = "README.md"
+keywords = ["python", "agent", "environment", "relay", "protocol"]
+requires-python = ">=3.11,<3.14"
+classifiers = [
+    "Intended Audience :: Developers",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+dependencies = [
+    "pydantic>=2.0.0",
+]
+
+[project.urls]
+Repository = "https://github.com/wh1isper/ya-mono"
+
+[dependency-groups]
+dev = [
+    "deptry>=0.22.0",
+    "pyright>=1.1.0",
+    "ruff>=0.9.2",
+]
+
+[build-system]
+requires = ["hatchling", "uv-dynamic-versioning>=0.7.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "uv-dynamic-versioning"
+
+[tool.uv-dynamic-versioning]
+vcs = "git"
+style = "pep440"
+bump = true
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "README.md",
+    "pyproject.toml",
+    "spec",
+    "ya_environment_relay",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["ya_environment_relay"]
+force-include = { "spec" = "spec" }
+
+[tool.deptry]
+ignore = ["DEP001", "DEP002"]
+package_module_name_map = { "pydantic" = "pydantic", "ya-environment-relay" = "ya_environment_relay" }
+per_rule_ignores = { DEP004 = ["pytest"] }

ya_environment_relay-0.74.0/spec/01-overview.md

@@ -0,0 +1,147 @@
+# 01. YA Environment Relay Overview
+
+## Goal
+
+YA Environment Relay connects an agent runtime to capabilities that execute in another process, device, sandbox, or host. It turns those external capabilities into `ya-agent-sdk` Environment components so the agent can use them through normal file, shell, resource, and tool abstractions.
+
+YA Environment Relay is protocol-level infrastructure. Product integrations such as YA Desktop, YA Claw, cloud workers, or sandbox services implement the protocol for their own deployment models.
+
+## Parties
+
+```mermaid
+flowchart TB
+    Runtime[Agent Runtime] --> RelayServer[Relay Server]
+    RelayServer <--> RelayClient[Relay Client]
+    RelayClient --> Provider[Capability Provider]
+    Provider --> Target[Local Device / Sandbox / External System]
+
+    Runtime --> SDK[ya-agent-sdk Environment]
+    SDK --> RelayEnvironment[RelayEnvironment]
+    RelayEnvironment --> RelayServer
+```
+
+Definitions:
+
+- Agent Runtime: process that runs the model loop and tool calls.
+- Relay Server: endpoint that accepts relay client connections and routes requests.
+- Relay Client: process that connects to the relay server and advertises capabilities.
+- Capability Provider: implementation behind the relay client, such as local filesystem, shell, OS automation, browser, VM, or custom tool host.
+- Relay Environment: SDK Environment implementation backed by relay requests.
+
+## Capability Families
+
+YA Environment Relay uses capability families to group provider methods:
+
+```text
+fileops
+shell
+tools
+resources
+artifacts
+computer
+browser
+```
+
+Initial protocol should define the first six families. Browser can be added as a specialized provider or implemented as custom tools.
+
+## Relationship to ya-agent-sdk
+
+`ya-agent-sdk` already has core runtime abstractions:
+
+- Environment
+- FileOperator
+- Shell
+- ResourceRegistry
+- Toolset
+- resumable resources
+
+YA Environment Relay should provide remote implementations of these abstractions:
+
+```python
+RelayEnvironment(Environment)
+RelayFileOperator(FileOperator)
+RelayShell(Shell)
+RelayResourceRegistry(ResourceRegistry)
+RelayToolset(Toolset)
+```
+
+This keeps agent code and profiles stable while moving execution to a connected provider.
+
+## Relationship to Claw
+
+Claw can use YA Environment Relay as one `WorkspaceProvider` backend:
+
+```text
+WorkspaceProvider kind = relay
+Environment = RelayEnvironment
+```
+
+Claw remains responsible for:
+
+- sessions and runs.
+- profile selection.
+- model execution.
+- HITL approvals.
+- durable trace.
+- artifact storage.
+- provider registry and connection routing.
+
+A relay client supplies execution capabilities. Claw exposes them to the agent through SDK abstractions.
+
+## Relationship to Desktop
+
+YA Desktop can act as a relay client. It can advertise local capabilities:
+
+- selected folders as workspace roots.
+- sandboxed local shell.
+- native OS computer use.
+- Desktop-managed custom tools.
+- local artifact upload.
+
+Desktop owns user consent, local grants, and native permission UX. Claw owns runtime authorization and trace.
+
+## Relationship to MCP
+
+MCP and YA Environment Relay address overlapping but different surfaces:
+
+| Surface                        | MCP                         | YA Environment Relay |
+| ------------------------------ | --------------------------- | -------------------- |
+| Tool discovery                 | yes                         | yes                  |
+| JSON Schema tool input         | yes                         | yes                  |
+| FileOperator abstraction       | product-specific            | built in             |
+| Shell streaming                | server-specific             | built in             |
+| Environment/resource lifecycle | limited by server           | built in             |
+| Runtime artifact ownership     | external or custom          | built in             |
+| User device relay              | possible with custom server | primary use case     |
+
+A relay client can wrap MCP servers and register selected tools into YA Environment Relay. A Claw profile can use MCP servers and relay capabilities together.
+
+## High-Level Flow
+
+```mermaid
+sequenceDiagram
+    participant Client as Relay Client
+    participant Server as Relay Server
+    participant Runtime as Agent Runtime
+    participant Provider as Provider
+
+    Client->>Server: WebSocket connect
+    Client->>Server: hello capabilities
+    Server-->>Client: accepted capabilities
+    Runtime->>Server: file/shell/tool/computer request
+    Server->>Client: relay request
+    Client->>Provider: execute
+    Provider-->>Client: result / stream
+    Client-->>Server: response / stream
+    Server-->>Runtime: Environment result
+```
+
+## Design Principles
+
+- The protocol is provider-neutral.
+- The runtime controls model-facing tool exposure.
+- The provider controls local execution and local policy.
+- Capabilities are explicitly advertised and accepted.
+- Streaming and cancellation are first-class.
+- Artifacts are owned by the runtime store when the call belongs to a run.
+- Security is scoped by device, connection, space/workspace, capability, and root grants.

ya_environment_relay-0.74.0/spec/02-protocol.md

@@ -0,0 +1,376 @@
+# 02. ya-environment-relay.v1 Protocol
+
+## Transport
+
+`ya-environment-relay.v1` uses WebSocket as its primary transport. The protocol requires bidirectional request/response, streaming output, cancellation, heartbeat, provider events, and artifact coordination.
+
+Connection endpoint shape for a host runtime:
+
+```http
+GET /api/v1/relay/connect
+Authorization: Bearer <relay-token>
+Upgrade: websocket
+```
+
+Products can expose a different path, but the frame format should remain stable.
+
+## Frame Types
+
+```ts
+type RelayFrame =
+  | HelloFrame
+  | EventFrame
+  | RequestFrame
+  | ResponseFrame
+  | StreamFrame
+  | CancelFrame
+  | PingFrame
+  | PongFrame;
+```
+
+All frames are JSON text frames unless a method explicitly negotiates binary transfer. Large artifacts should use artifact upload methods instead of raw WebSocket binary in the first version.
+
+## Hello
+
+The relay client sends `hello` immediately after connection:
+
+```json
+{
+  "type": "hello",
+  "protocol": "ya-environment-relay.v1",
+  "client_id": "client_macbook_123",
+  "client_kind": "ya_desktop",
+  "client_version": "0.1.0",
+  "capabilities": {
+    "fileops": {
+      "enabled": true,
+      "roots": [
+        {
+          "root_id": "main",
+          "label": "ya-mono",
+          "virtual_path": "/workspace/main",
+          "mode": "rw"
+        }
+      ]
+    },
+    "shell": {
+      "enabled": true,
+      "runtime": "sandboxed_local_shell",
+      "interactive": true
+    },
+    "tools": {
+      "enabled": true,
+      "tool_count": 2
+    },
+    "computer": {
+      "enabled": true,
+      "platform": "macos",
+      "screenshots": true,
+      "accessibility_tree": true,
+      "semantic_actions": true,
+      "coordinate_input": true
+    }
+  }
+}
+```
+
+The relay server responds with an event:
+
+```json
+{
+  "type": "event",
+  "event": "relay.accepted",
+  "payload": {
+    "connection_id": "relay_conn_123",
+    "accepted_capabilities": ["fileops", "shell", "tools", "computer"],
+    "server_time": "2026-05-11T15:40:00Z"
+  }
+}
+```
+
+## Request
+
+Either side may send requests when authorized. The most common direction is runtime to provider.
+
+```json
+{
+  "type": "request",
+  "id": "req_123",
+  "method": "file.read",
+  "params": {
+    "root_id": "main",
+    "path": "README.md",
+    "encoding": "utf-8"
+  },
+  "context": {
+    "session_id": "session_abc",
+    "run_id": "run_def",
+    "tool_call_id": "call_ghi"
+  }
+}
+```
+
+`id` must be unique within a live connection until the request reaches terminal response or cancellation.
+
+## Response
+
+Successful response:
+
+```json
+{
+  "type": "response",
+  "id": "req_123",
+  "result": {
+    "content": "# Project\n...",
+    "encoding": "utf-8"
+  }
+}
+```
+
+Error response:
+
+```json
+{
+  "type": "response",
+  "id": "req_123",
+  "error": {
+    "code": "permission_denied",
+    "message": "The path is outside the selected roots.",
+    "recoverable": true,
+    "details": {
+      "root_id": "main"
+    }
+  }
+}
+```
+
+Common error codes:
+
+```text
+invalid_request
+unknown_method
+capability_unavailable
+permission_denied
+approval_required
+policy_blocked
+not_found
+timeout
+cancelled
+provider_error
+relay_disconnected
+artifact_error
+```
+
+## Stream
+
+Long-running requests can emit stream frames before the terminal response.
+
+```json
+{
+  "type": "stream",
+  "id": "req_shell_1",
+  "event": "stdout",
+  "data": "Running tests...\n"
+}
+```
+
+Common stream event names:
+
+```text
+stdout
+stderr
+progress
+artifact
+status
+log
+```
+
+Terminal completion uses `response`:
+
+```json
+{
+  "type": "response",
+  "id": "req_shell_1",
+  "result": {
+    "exit_code": 0,
+    "duration_ms": 1234
+  }
+}
+```
+
+## Cancel
+
+Either side can cancel an active request:
+
+```json
+{
+  "type": "cancel",
+  "id": "req_shell_1",
+  "reason": "user_cancelled"
+}
+```
+
+The receiver should attempt cancellation and then send a terminal response:
+
+```json
+{
+  "type": "response",
+  "id": "req_shell_1",
+  "error": {
+    "code": "cancelled",
+    "message": "Request cancelled by user.",
+    "recoverable": true
+  }
+}
+```
+
+## Heartbeat
+
+Heartbeat frames keep the connection alive and measure latency.
+
+```json
+{
+  "type": "ping",
+  "id": "ping_1",
+  "ts": "2026-05-11T15:45:00Z"
+}
+```
+
+```json
+{
+  "type": "pong",
+  "id": "ping_1",
+  "ts": "2026-05-11T15:45:00Z"
+}
+```
+
+## Events
+
+Events are one-way notifications outside request/response.
+
+```json
+{
+  "type": "event",
+  "event": "capability.updated",
+  "payload": {
+    "capability": "computer",
+    "state": "permission_required"
+  }
+}
+```
+
+Common events:
+
+```text
+relay.accepted
+capability.updated
+provider.paused
+provider.resumed
+artifact.uploaded
+tool.registered
+tool.unregistered
+resource.updated
+```
+
+## Method Namespaces
+
+```text
+file.read
+file.write
+file.list
+file.stat
+file.mkdir
+file.delete
+file.search
+file.watch
+
+shell.start
+shell.input
+shell.resize
+shell.signal
+shell.cancel
+shell.status
+
+tool.list
+tool.register
+tool.unregister
+tool.call
+tool.cancel
+
+resource.list
+resource.get
+resource.create
+resource.dispose
+resource.export_state
+resource.restore_state
+
+computer.status
+computer.see
+computer.act
+computer.pause
+computer.resume
+computer.takeover
+computer.release
+
+artifact.reserve
+artifact.upload
+artifact.complete
+artifact.abort
+```
+
+## Artifact Coordination
+
+Large artifacts should be transferred out-of-band through runtime-owned storage.
+
+Reserve request:
+
+```json
+{
+  "type": "request",
+  "id": "req_artifact_1",
+  "method": "artifact.reserve",
+  "params": {
+    "run_id": "run_123",
+    "kind": "screenshot",
+    "mime_type": "image/png",
+    "metadata": {
+      "source": "computer.see"
+    }
+  }
+}
+```
+
+Reserve response:
+
+```json
+{
+  "type": "response",
+  "id": "req_artifact_1",
+  "result": {
+    "artifact_id": "art_123",
+    "upload_url": "https://runtime.example/upload/art_123",
+    "headers": {
+      "Authorization": "Bearer upload-token"
+    }
+  }
+}
+```
+
+Complete request:
+
+```json
+{
+  "type": "request",
+  "id": "req_artifact_2",
+  "method": "artifact.complete",
+  "params": {
+    "artifact_id": "art_123",
+    "size_bytes": 203456,
+    "sha256": "..."
+  }
+}
+```
+
+## Versioning
+
+The protocol string is `ya-environment-relay.v1`. Breaking changes should use `ya-environment-relay.v2`. Additive method fields can be negotiated through the `hello.capabilities` payload.

ya_environment_relay-0.74.0/spec/03-environment.md

@@ -0,0 +1,216 @@
+# 03. Relay Environment
+
+## Goal
+
+Relay Environment maps `ya-environment-relay.v1` capabilities into `ya-agent-sdk` runtime abstractions. Agents and toolsets should interact with normal SDK interfaces while execution happens through a connected relay provider.
+
+## Environment Shape
+
+```python
+class RelayEnvironment(Environment):
+    file_operator: RelayFileOperator
+    shell: RelayShell
+    resources: RelayResourceRegistry
+    toolsets: list[RelayToolset]
+```
+
+The environment should be created from a binding:
+
+```python
+class RelayEnvironmentBinding(BaseModel):
+    connection_id: str
+    client_id: str
+    roots: list[RelayRoot]
+    capabilities: list[str]
+    metadata: dict[str, Any] = Field(default_factory=dict)
+```
+
+## FileOperator Mapping
+
+`RelayFileOperator` maps SDK file operations to `file.*` methods:
+
+| SDK behavior     | Relay method  |
+| ---------------- | ------------- |
+| read text/bytes  | `file.read`   |
+| write text/bytes | `file.write`  |
+| list directory   | `file.list`   |
+| stat path        | `file.stat`   |
+| create directory | `file.mkdir`  |
+| delete path      | `file.delete` |
+| search content   | `file.search` |
+
+Paths should be virtualized. The model and runtime see `/workspace/main/README.md`; the relay client maps it to an approved local root.
+
+Request example:
+
+```json
+{
+  "method": "file.read",
+  "params": {
+    "root_id": "main",
+    "path": "README.md",
+    "encoding": "utf-8"
+  }
+}
+```
+
+## Shell Mapping
+
+`RelayShell` maps SDK shell execution to `shell.*` methods:
+
+| SDK behavior    | Relay method   |
+| --------------- | -------------- |
+| start command   | `shell.start`  |
+| send stdin      | `shell.input`  |
+| resize terminal | `shell.resize` |
+| send signal     | `shell.signal` |
+| cancel command  | `shell.cancel` |
+| inspect command | `shell.status` |
+
+Shell output uses stream frames:
+
+```json
+{
+  "type": "stream",
+  "id": "req_shell_1",
+  "event": "stdout",
+  "data": "pytest started\n"
+}
+```
+
+The terminal response carries exit status:
+
+```json
+{
+  "type": "response",
+  "id": "req_shell_1",
+  "result": {
+    "exit_code": 0,
+    "duration_ms": 18233
+  }
+}
+```
+
+## Resource Mapping
+
+Relay resources represent long-lived provider-side objects:
+
+- browser sessions.
+- computer sessions.
+- database connections.
+- local app automation handles.
+- external service sessions.
+
+Method mapping:
+
+```text
+resource.list
+resource.get
+resource.create
+resource.dispose
+resource.export_state
+resource.restore_state
+```
+
+Resource state should integrate with SDK resumable resources when possible.
+
+## Tool Mapping
+
+Relay custom tools are described by JSON Schema and exposed as SDK tools.
+
+Tool descriptor:
+
+```json
+{
+  "name": "local_open_in_editor",
+  "title": "Open File in Local Editor",
+  "description": "Open a workspace file in the user's configured editor.",
+  "input_schema": {
+    "type": "object",
+    "properties": {
+      "path": { "type": "string" },
+      "line": { "type": "integer" }
+    },
+    "required": ["path"]
+  },
+  "capability": "tools",
+  "risk": "low",
+  "approval_policy": "ask_once_per_run"
+}
+```
+
+Runtime mapping:
+
+1. Relay client registers tool descriptors.
+2. Runtime constructs a `RelayToolset` from accepted descriptors.
+3. Model calls generated SDK tool.
+4. Runtime sends `tool.call` over relay.
+5. Relay client executes the local tool.
+6. Runtime records trace and returns model-facing result.
+
+## Computer Mapping
+
+Computer use can be represented as either:
+
+- a specialized `RelayComputerProvider` used by a `ComputerUseToolset`.
+- custom tools registered under the `tools` capability.
+
+The specialized provider is preferred for product-grade computer use because it needs standard snapshot, action, artifact, pause, takeover, and policy semantics.
+
+Method mapping:
+
+```text
+computer.status
+computer.see
+computer.act
+computer.pause
+computer.resume
+computer.takeover
+computer.release
+```
+
+## Binding to Agent Runs
+
+Each relay request should include runtime context when available:
+
+```json
+{
+  "context": {
+    "session_id": "session_123",
+    "run_id": "run_456",
+    "tool_call_id": "call_789",
+    "workspace_id": "workspace_abc"
+  }
+}
+```
+
+This lets providers upload artifacts, render user-facing prompts, and attach local audit logs to runtime objects.
+
+## Lifecycle
+
+```mermaid
+sequenceDiagram
+    participant Runtime as Runtime
+    participant Server as Relay Server
+    participant Client as Relay Client
+
+    Client->>Server: connect + hello
+    Server->>Runtime: provider registered
+    Runtime->>Server: create RelayEnvironment for session
+    Runtime->>Server: request file/shell/tool/computer
+    Server->>Client: relay request
+    Client-->>Server: response / stream
+    Server-->>Runtime: SDK result
+    Runtime->>Server: dispose run resources
+```
+
+## Reconnect
+
+Relay clients can reconnect with the same `client_id`. Server behavior:
+
+- mark capabilities unavailable when disconnected.
+- fail pending requests with `relay_disconnected`.
+- accept a fresh `hello` after reconnect.
+- recreate environments against the new connection when session policy permits it.
+
+Future protocol versions can add resumable request IDs and provider-side durable sessions.

ya_environment_relay-0.74.0/spec/04-security-and-policy.md

@@ -0,0 +1,177 @@
+# 04. Security and Policy
+
+## Goal
+
+YA Environment Relay gives an agent runtime access to external execution environments. The protocol must make every capability explicit, scoped, revocable, and traceable.
+
+## Trust Layers
+
+```mermaid
+flowchart TB
+    RuntimePolicy[Runtime Policy] --> RelayGrant[Relay Grant]
+    RelayGrant --> ProviderPolicy[Provider Local Policy]
+    ProviderPolicy --> Capability[Capability Execution]
+
+    RuntimePolicy --> HITL[Runtime HITL]
+    ProviderPolicy --> LocalPrompt[Provider User Prompt]
+    ProviderPolicy --> LocalBlock[Local Block]
+```
+
+Runtime policy controls model-facing access. Provider policy controls local execution. Both can require approvals or block actions.
+
+## Authentication
+
+Relay connections should authenticate with a scoped token:
+
+```http
+Authorization: Bearer <relay-token>
+```
+
+Token scope should include:
+
+- client identity.
+- allowed runtime or connection.
+- workspace or Space identity.
+- capability grants.
+- expiration.
+- revocation ID.
+
+## Authorization Grant
+
+Grant shape:
+
+```ts
+type RelayGrant = {
+  grant_id: string;
+  client_id: string;
+  runtime_id: string;
+  scope_id?: string;
+  capabilities: RelayCapabilityGrant[];
+  expires_at?: string;
+  created_at: string;
+};
+
+type RelayCapabilityGrant = {
+  capability: "fileops" | "shell" | "tools" | "resources" | "artifacts" | "computer";
+  enabled: boolean;
+  policy_id?: string;
+  roots?: RelayRootGrant[];
+};
+```
+
+File roots should be individually granted:
+
+```ts
+type RelayRootGrant = {
+  root_id: string;
+  virtual_path: string;
+  mode: "ro" | "rw";
+};
+```
+
+## Capability Acceptance
+
+The relay server should accept only capabilities allowed by the active grant. The `hello` frame advertises provider capabilities. The server returns accepted capabilities in `relay.accepted`.
+
+A provider may advertise `computer`; the server can accept only `fileops` and `tools` based on policy.
+
+## Path Safety
+
+Relay file operations use virtual paths and root IDs. Providers must enforce root boundaries after path normalization.
+
+Rules:
+
+- normalize paths before access.
+- resolve symlinks according to root policy.
+- reject traversal outside roots.
+- preserve read-only grants.
+- include root ID and virtual path in audit logs.
+
+## Shell Safety
+
+Shell grants should include:
+
+- allowed roots and cwd.
+- environment variable allowlist.
+- network policy metadata.
+- command approval policy.
+- max runtime.
+- streaming output limits.
+
+Shell execution should use provider-local sandboxing when available.
+
+## Tool Safety
+
+Custom tools should declare risk and approval policy:
+
+```ts
+type RelayToolPolicy = {
+  risk: "low" | "medium" | "high" | "critical";
+  approval_policy: "allow" | "ask_once" | "ask_once_per_run" | "always_ask" | "block";
+};
+```
+
+Runtime profiles can override provider suggestions with stricter rules.
+
+## Computer Safety
+
+Computer use should use additional local controls:
+
+- explicit user enablement.
+- visible active state.
+- pause, takeover, release, stop.
+- app allow/deny lists.
+- screenshot retention policy.
+- artifact upload policy.
+- sensitive surface detection.
+
+The provider should check local control state before each computer action.
+
+## Artifact Safety
+
+Artifact uploads should be tied to a run or approved workspace scope.
+
+Artifact policy dimensions:
+
+- allowed MIME types.
+- max size.
+- retention days.
+- redaction required.
+- upload approval for sensitive classes.
+- remote runtime upload consent.
+
+## Audit
+
+Every relay request should be auditable:
+
+```ts
+type RelayAuditEntry = {
+  id: string;
+  connection_id: string;
+  client_id: string;
+  method: string;
+  session_id?: string;
+  run_id?: string;
+  tool_call_id?: string;
+  capability: string;
+  policy_decision: "allowed" | "approved" | "blocked";
+  started_at: string;
+  completed_at?: string;
+  status: "succeeded" | "failed" | "cancelled";
+};
+```
+
+Runtime and provider can both keep audit logs. Runtime audit links to run trace. Provider audit supports local diagnostics and user trust review.
+
+## Revocation
+
+Revocation should close active sockets and fail pending requests. Provider-side revocation should stop new execution immediately. Runtime-side revocation should remove the relay provider from capability discovery.
+
+Common revocation triggers:
+
+- user disables relay for a Space.
+- token expires.
+- provider loses required permissions.
+- remote runtime identity changes.
+- policy version changes.
+- user emergency stop.

ya_environment_relay-0.74.0/spec/05-implementation-plan.md

@@ -0,0 +1,129 @@
+# 05. Implementation Plan
+
+## Phase 1: Spec and Models
+
+Deliverables:
+
+- spec folder.
+- Python protocol models.
+- TypeScript protocol model references for product clients.
+- frame validation fixtures.
+- method namespace constants.
+
+Suggested Python package layout:
+
+```text
+packages/ya-environment-relay/
+  pyproject.toml
+  ya_environment_relay/
+    __init__.py
+    protocol.py
+    errors.py
+    capabilities.py
+```
+
+## Phase 2: In-Process Mock Transport
+
+Build an in-process transport before WebSocket integration.
+
+Deliverables:
+
+- mock relay server.
+- mock relay client.
+- request/response roundtrip.
+- stream and cancel tests.
+- fake fileops provider.
+- fake custom tool provider.
+
+This validates Environment mapping without product-specific networking.
+
+## Phase 3: SDK Environment Integration
+
+Deliverables:
+
+- `RelayEnvironment`.
+- `RelayFileOperator`.
+- `RelayShell`.
+- `RelayToolset`.
+- resource registry draft.
+
+Tests:
+
+- file read/list/write against fake provider.
+- shell streaming result.
+- generated tool call through `tool.call`.
+- cancellation behavior.
+
+## Phase 4: WebSocket Transport
+
+Deliverables:
+
+- relay server transport.
+- relay client transport.
+- heartbeat.
+- reconnect state.
+- request timeout handling.
+- connection registry.
+
+The server transport can first live in Claw, then move common pieces into `ya-environment-relay` after the API stabilizes.
+
+## Phase 5: Claw Integration
+
+Deliverables:
+
+- Claw relay connection endpoint.
+- relay provider registry.
+- `RelayWorkspaceProvider`.
+- session workspace binding support.
+- run trace projections for relay calls.
+- artifact reserve/upload/complete endpoints or adapters.
+
+## Phase 6: Desktop Integration
+
+Deliverables:
+
+- Desktop relay client.
+- Space-level relay grants.
+- local fileops provider.
+- local shell provider.
+- custom tool registration.
+- relay diagnostics UI.
+
+## Phase 7: Computer Use Capability
+
+Deliverables:
+
+- `RelayComputerProvider`.
+- `computer.status`.
+- `computer.see`.
+- `computer.act`.
+- artifact upload for screenshots and UI trees.
+- Desktop Host Computer Bridge integration.
+
+## Test Matrix
+
+| Area              | Test                                                 |
+| ----------------- | ---------------------------------------------------- |
+| protocol          | frame parse/serialize fixtures                       |
+| request lifecycle | success, error, timeout, cancel                      |
+| streaming         | stdout/stderr/progress ordering                      |
+| fileops           | path normalization and root boundary                 |
+| shell             | output stream and signal handling                    |
+| tools             | JSON Schema descriptor to SDK tool                   |
+| artifacts         | reserve/upload/complete failure modes                |
+| reconnect         | pending request failure and provider re-registration |
+| security          | grant filtering and capability acceptance            |
+
+## MVP Cut
+
+Recommended first production slice:
+
+1. `ya-environment-relay.v1` protocol models.
+2. Claw WebSocket endpoint.
+3. Desktop relay client.
+4. file read/list/stat.
+5. shell start with stream and cancel.
+6. custom tool list/call.
+7. artifact reserve/complete.
+
+Computer use becomes the first high-value specialized capability after the base relay environment is proven.

ya_environment_relay-0.74.0/spec/README.md

@@ -0,0 +1,56 @@
+# YA Environment Relay Spec
+
+YA Environment Relay is a provider-neutral protocol for connecting agent runtimes to external execution environments. It is designed to build on top of `ya-agent-sdk` Environment abstractions and expose remote or local capabilities as file operators, shells, resources, and toolsets.
+
+YA Environment Relay is a general protocol. YA Desktop is one important relay client, but the protocol should also support headless relay agents, server-side workers, browser sandboxes, VM sandboxes, and custom tool hosts.
+
+## Goals
+
+- Let an agent runtime call capabilities that live outside the runtime process.
+- Represent remote capabilities as SDK Environment components.
+- Support file operations, shell execution, custom tools, resources, artifacts, and computer use.
+- Use one bidirectional transport for request/response, streaming, cancellation, and provider events.
+- Keep tool schemas compatible with JSON Schema and model tool calling.
+- Preserve runtime-owned tracing, approvals, and artifact persistence.
+
+## Package Direction
+
+Initial work is spec-only. Future implementation can become a workspace package:
+
+```text
+packages/ya-environment-relay/
+  spec/
+  pyproject.toml
+  ya_environment_relay/
+    protocol.py
+    client.py
+    server.py
+    environment.py
+    providers/
+```
+
+The first Python implementation should integrate with `ya-agent-sdk` and expose:
+
+- `RelayEnvironment`
+- `RelayFileOperator`
+- `RelayShell`
+- `RelayToolset`
+- `RelayResourceRegistry`
+- protocol models for `ya-environment-relay.v1`
+
+## Section Map
+
+| Section | Document                                               | Topic                                                                  |
+| ------- | ------------------------------------------------------ | ---------------------------------------------------------------------- |
+| 01      | [01-overview.md](01-overview.md)                       | goals, parties, capability model, relationship to SDK and Claw         |
+| 02      | [02-protocol.md](02-protocol.md)                       | WebSocket frames, request/response, streaming, cancellation, errors    |
+| 03      | [03-environment.md](03-environment.md)                 | SDK Environment mapping, file operator, shell, resources, custom tools |
+| 04      | [04-security-and-policy.md](04-security-and-policy.md) | authentication, grants, policy, approvals, artifact safety             |
+| 05      | [05-implementation-plan.md](05-implementation-plan.md) | MVP phases and package layout                                          |
+
+## Relationship to Products
+
+- `ya-agent-sdk` provides the Environment concepts that YA Environment Relay implements remotely.
+- `ya-claw` can host a relay server and route agent tool calls to connected providers.
+- `ya-desktop` can act as a relay client for local files, shell, computer use, and custom tools.
+- Future services can implement relay clients for sandboxes, browsers, VMs, and specialized tools.

ya_environment_relay-0.74.0/ya_environment_relay/__init__.py

@@ -0,0 +1,5 @@
+"""YA Environment Relay protocol package."""
+
+PROTOCOL_VERSION = "ya-environment-relay.v1"
+
+__all__ = ["PROTOCOL_VERSION"]