Enforce complete public reference contract

reference-config/operations.yaml

@@ -1,5 +1,20 @@
 schemaVersion: 1
 
+connect:
+  productionBaseUrl: https://sandbox.agentbox-runtime.ru
+  method: POST
+  headers:
+    - name: Agentbox-Sandbox-Id
+      required: true
+      description: Sandbox identifier.
+    - name: Agentbox-Sandbox-Port
+      required: true
+      description: Envd port routed by the sandbox proxy.
+      default: 49983
+    - name: X-Access-Token
+      required: false
+      description: Sandbox-scoped envd access token, when one was issued.
+
 controlPlane:
   source: spec/openapi.yml
   publicAuthSchemes:

reference/connect/filesystem.md

@@ -1,67 +1,89 @@
 # Filesystem API
 
-Service: `Filesystem`
+## Transport
+
+AgentBox exposes this service through the Connect protocol over HTTP.
+The AgentBox SDK supplies the routing and authorization headers automatically.
+
+- Production base URL: `https://sandbox.agentbox-runtime.ru`
+- Fully qualified service: `filesystem.Filesystem`
+- RPC URL pattern: `POST https://sandbox.agentbox-runtime.ru/filesystem.Filesystem/{RPC}`
+
+### Request headers
+
+- **`Agentbox-Sandbox-Id`** · required — Sandbox identifier.
+- **`Agentbox-Sandbox-Port`** · required — Envd port routed by the sandbox proxy. Default: `49983`.
+- **`X-Access-Token`** · conditional — Sandbox-scoped envd access token, when one was issued.
 
 ## Stat
 
 Public RPC exposed by envd.
 
+- Endpoint: `POST https://sandbox.agentbox-runtime.ru/filesystem.Filesystem/Stat`
 - Request: `StatRequest`
 - Response: `StatResponse`
 
 ## MakeDir
 
 Public RPC exposed by envd.
 
+- Endpoint: `POST https://sandbox.agentbox-runtime.ru/filesystem.Filesystem/MakeDir`
 - Request: `MakeDirRequest`
 - Response: `MakeDirResponse`
 
 ## Move
 
 Public RPC exposed by envd.
 
+- Endpoint: `POST https://sandbox.agentbox-runtime.ru/filesystem.Filesystem/Move`
 - Request: `MoveRequest`
 - Response: `MoveResponse`
 
 ## ListDir
 
 Public RPC exposed by envd.
 
+- Endpoint: `POST https://sandbox.agentbox-runtime.ru/filesystem.Filesystem/ListDir`
 - Request: `ListDirRequest`
 - Response: `ListDirResponse`
 
 ## Remove
 
 Public RPC exposed by envd.
 
+- Endpoint: `POST https://sandbox.agentbox-runtime.ru/filesystem.Filesystem/Remove`
 - Request: `RemoveRequest`
 - Response: `RemoveResponse`
 
 ## WatchDir
 
 Public RPC exposed by envd.
 
+- Endpoint: `POST https://sandbox.agentbox-runtime.ru/filesystem.Filesystem/WatchDir`
 - Request: `WatchDirRequest`
 - Response: `stream WatchDirResponse`
 
 ## CreateWatcher
 
 Non-streaming versions of WatchDir
 
+- Endpoint: `POST https://sandbox.agentbox-runtime.ru/filesystem.Filesystem/CreateWatcher`
 - Request: `CreateWatcherRequest`
 - Response: `CreateWatcherResponse`
 
 ## GetWatcherEvents
 
 Public RPC exposed by envd.
 
+- Endpoint: `POST https://sandbox.agentbox-runtime.ru/filesystem.Filesystem/GetWatcherEvents`
 - Request: `GetWatcherEventsRequest`
 - Response: `GetWatcherEventsResponse`
 
 ## RemoveWatcher
 
 Public RPC exposed by envd.
 
+- Endpoint: `POST https://sandbox.agentbox-runtime.ru/filesystem.Filesystem/RemoveWatcher`
 - Request: `RemoveWatcherRequest`
 - Response: `RemoveWatcherResponse`
 
@@ -126,6 +148,7 @@ Public RPC exposed by envd.
 | `group` | `string` | 8 |  |
 | `modified_time` | `google.protobuf.Timestamp` | 9 |  |
 | `symlink_target` | `optional string` | 10 | If the entry is a symlink, this field contains the target of the symlink. |
+| `metadata` | `map<string, string>` | 11 | User-defined metadata stored as extended attributes (xattrs) on the file. Keys live under the `user.agentbox.` xattr namespace; the prefix is stripped here. Plain `user.*` xattrs written by other tooling are not reflected. |
 
 ### ListDirRequest
 
@@ -147,27 +170,27 @@ Public RPC exposed by envd.
 | `path` | `string` | 1 |  |
 | `recursive` | `bool` | 2 |  |
 | `include_entry` | `bool` | 3 | If true, each FilesystemEvent includes the EntryInfo of the affected entry, when available. |
-| `allow_network_mounts` | `bool` | 4 | Events on network mounts may be unreliable or not delivered at all. |
+| `allow_network_mounts` | `bool` | 4 | If true, allows watching paths on network filesystem mounts (NFS, CIFS, SMB, FUSE). Events on network mounts may be unreliable or not delivered at all. |
 
 ### FilesystemEvent
 
 | Field | Type | Number | Description |
 | --- | --- | ---: | --- |
 | `name` | `string` | 1 |  |
 | `type` | `EventType` | 2 |  |
-| `entry` | `optional EntryInfo` | 3 | events, where the entry no longer exists at this path). |
+| `entry` | `optional EntryInfo` | 3 | Info of the entry that triggered the event. Only populated when include_entry was requested and the entry could be stat-ed (e.g. not set for remove/rename-away events, where the entry no longer exists at this path). |
 
 ### WatchDirResponse
 
-| Field | Type | Number | Description |
-| --- | --- | ---: | --- |
-| `start` | `StartEvent` | 1 |  |
-| `filesystem` | `FilesystemEvent` | 2 |  |
-| `keepalive` | `KeepAlive` | 3 |  |
+| Field | Type | Number | Oneof | Description |
+| --- | --- | ---: | --- | --- |
+| `start` | `StartEvent` | 1 | `event` |  |
+| `filesystem` | `FilesystemEvent` | 2 | `event` |  |
+| `keepalive` | `KeepAlive` | 3 | `event` |  |
 
-### StartEvent
+### WatchDirResponse.StartEvent
 
-### KeepAlive
+### WatchDirResponse.KeepAlive
 
 ### CreateWatcherRequest
 
@@ -176,7 +199,7 @@ Public RPC exposed by envd.
 | `path` | `string` | 1 |  |
 | `recursive` | `bool` | 2 |  |
 | `include_entry` | `bool` | 3 | If true, each FilesystemEvent includes the EntryInfo of the affected entry, when available. |
-| `allow_network_mounts` | `bool` | 4 | Events on network mounts may be unreliable or not delivered at all. |
+| `allow_network_mounts` | `bool` | 4 | If true, allows watching paths on network filesystem mounts (NFS, CIFS, SMB, FUSE). Events on network mounts may be unreliable or not delivered at all. |
 
 ### CreateWatcherResponse
 
@@ -203,3 +226,25 @@ Public RPC exposed by envd.
 | `watcher_id` | `string` | 1 |  |
 
 ### RemoveWatcherResponse
+
+## Enum types
+
+### FileType
+
+| Value | Number | Description |
+| --- | ---: | --- |
+| `FILE_TYPE_UNSPECIFIED` | 0 |  |
+| `FILE_TYPE_FILE` | 1 |  |
+| `FILE_TYPE_DIRECTORY` | 2 |  |
+| `FILE_TYPE_SYMLINK` | 3 |  |
+
+### EventType
+
+| Value | Number | Description |
+| --- | ---: | --- |
+| `EVENT_TYPE_UNSPECIFIED` | 0 |  |
+| `EVENT_TYPE_CREATE` | 1 |  |
+| `EVENT_TYPE_WRITE` | 2 |  |
+| `EVENT_TYPE_REMOVE` | 3 |  |
+| `EVENT_TYPE_RENAME` | 4 |  |
+| `EVENT_TYPE_CHMOD` | 5 |  |