feat(deploy): per-agent base_url and workspace_path routing

- AgentDefinition gains base_url and workspace_path fields (optional)
- load_agent_registry parses them from matrix-agents.yaml
- _build_platform_from_env uses agent.base_url per agent (falls back to AGENT_BASE_URL)
- _agent_workspace_root() resolves workspace per agent from registry
- _materialize_incoming_attachments saves files to agent workspace_path/incoming/
- send_outgoing accepts workspace_root param; reads outgoing files from agent workspace_path
- dispatch loop computes workspace_root from room agent_id and passes to _send_all
- config/matrix-agents.yaml and example updated with base_url and workspace_path

adapter/matrix/files.py

@@ -36,6 +36,7 @@ def build_workspace_attachment_path(
     filename: str,
     timestamp: str | None = None,
 ) -> tuple[str, Path]:
+    """Legacy path builder used when no per-agent workspace_path is configured."""
     stamp = timestamp or datetime.now(UTC).strftime("%Y%m%d-%H%M%S")
     safe_user = _sanitize_component(matrix_user_id.lstrip("@"))
     safe_room = _sanitize_component(room_id.lstrip("!"))
@@ -46,6 +47,21 @@ def build_workspace_attachment_path(
     return relative_path.as_posix(), workspace_root / relative_path
 
 
+def build_agent_incoming_path(
+    *,
+    workspace_root: Path,
+    filename: str,
+    timestamp: str | None = None,
+) -> tuple[str, Path]:
+    """Per-agent path builder: saves to {workspace_root}/incoming/{stamp}-{filename}.
+    The returned relative path is what gets passed to agent.send_message(attachments=[...]).
+    """
+    stamp = timestamp or datetime.now(UTC).strftime("%Y%m%d-%H%M%S")
+    safe_name = _sanitize_component(filename) or "attachment.bin"
+    relative_path = Path("incoming") / f"{stamp}-{safe_name}"
+    return relative_path.as_posix(), workspace_root / relative_path
+
+
 async def download_matrix_attachment(
     *,
     client,
@@ -59,13 +75,23 @@ async def download_matrix_attachment(
         return attachment
 
     filename = _default_filename(attachment)
-    relative_path, absolute_path = build_workspace_attachment_path(
-        workspace_root=workspace_root,
-        matrix_user_id=matrix_user_id,
-        room_id=room_id,
-        filename=filename,
-        timestamp=timestamp,
-    )
+
+    if workspace_root.name and str(workspace_root) not in (".", "/workspace", "/agents"):
+        # Per-agent workspace configured — use simple incoming/ layout
+        relative_path, absolute_path = build_agent_incoming_path(
+            workspace_root=workspace_root,
+            filename=filename,
+            timestamp=timestamp,
+        )
+    else:
+        relative_path, absolute_path = build_workspace_attachment_path(
+            workspace_root=workspace_root,
+            matrix_user_id=matrix_user_id,
+            room_id=room_id,
+            filename=filename,
+            timestamp=timestamp,
+        )
+
     absolute_path.parent.mkdir(parents=True, exist_ok=True)
 
     response = await client.download(attachment.url)